Skip to content

fix(agent): defer intake and provider web tools #3536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kojiwakayama merged 5 commits into from
Aug 10, 2026
Merged

fix(agent): defer intake and provider web tools #3536

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4be0567
fix(agent): defer intake and provider web tools
kojiwakayama Aug 10, 2026
ead5081
docs(agent): align deferred tool discovery guides
kojiwakayama Aug 10, 2026
15173d6
test(agent): satisfy exposure test typecheck
kojiwakayama Aug 10, 2026
90836a8
test(agent): update deferred streaming exposure contract
kojiwakayama Aug 10, 2026
5fbee85
docs(agent): clarify deferred exposure evidence
kojiwakayama Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/api-reference/veryfront/agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -761,7 +761,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `executeHostedDurableChatRun` | Execute hosted durable chat run. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/durable-chat-run-start.ts#L232) |
| `executeHostedDurableChildFork` | Execute hosted durable child fork. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/durable-child-fork-execution.ts#L807) |
| `executeHostedLocalChildInvoke` | Execute hosted local child invoke. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/durable-child-fork-execution.ts#L414) |
| `expandAllowedRemoteToolNames` | Normalize allowed remote tool names without adding undeclared provider-native tools. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L62) |
| `expandAllowedRemoteToolNames` | Normalize allowed remote tool names without adding undeclared provider-native tools. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L82) |
| `expandHostedChildRequestedTools` | Expand hosted child requested tools helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/child-requested-tools.ts#L87) |
| `extractChatMessageMetadata` | Extract chat message metadata. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/chat/chat-ui-message-helpers.ts#L302) |
| `extractLatestUserText` | Extract latest user text. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/artifacts/default-research-artifact-support.ts#L68) |
Expand Down Expand Up @@ -803,7 +803,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `getConversationRun` | Return conversation run. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/conversation/durable.ts#L1065) |
| `getConversationRunEventJsonByteLength` | Return conversation run event JSON byte length. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/conversation/run-event-normalization.ts#L27) |
| `getEmptyHostedFinalizedMessageTerminalError` | Error shape for get empty hosted finalized message terminal. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/stream-terminal-error.ts#L113) |
| `getForkRuntimeAllowedToolNames` | Return fork runtime allowed tool names. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L69) |
| `getForkRuntimeAllowedToolNames` | Return fork runtime allowed tool names. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L89) |
| `getForwardedHostedModelId` | Return forwarded hosted model ID. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/runtime-request-config.ts#L86) |
| `getForwardedHostedRuntimeOverrides` | Return forwarded hosted runtime overrides. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/runtime-request-config.ts#L96) |
| `getHostedChildWrittenArtifactPath` | Return hosted child written artifact path. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/child-artifact-support.ts#L112) |
Expand All @@ -814,7 +814,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `getMaxForkRuntimeStepCount` | Return max fork runtime step count. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/streaming/fork-runtime-stream.ts#L445) |
| `getProjectAgentRuntimeAgentIdCandidates` | Return project agent runtime agent ID candidates. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/project/agent-runtime.ts#L223) |
| `getProjectSteeringMutation` | Return project steering mutation. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/project/steering-mutation.ts#L112) |
| `getProviderNativeToolNames` | Return provider native tool names. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L48) |
| `getProviderNativeToolNames` | Return provider native tool names. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L53) |
| `getProviderToolProfile` | Return provider tool profile. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-tool-compat.ts#L59) |
| `getRuntimeAgentMarkdownDefinition` | Definition for get runtime agent markdown. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/agent-markdown-adapter.ts#L45) |
| `getRuntimeProjectFile` | Return runtime project file. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/project-files-client.ts#L404) |
Expand Down Expand Up @@ -1719,7 +1719,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `ProjectSteeringMutationInput` | Input payload for project steering mutation. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/project/steering-mutation.ts#L29) |
| `ProjectSteeringMutationResult` | Result returned from project steering mutation. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/project/steering-mutation.ts#L38) |
| `ProjectSteeringPaths` | Public API contract for project steering paths. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/project/steering-mutation.ts#L23) |
| `ProviderNativeToolInventoryOptions` | Options accepted by provider native tool inventory. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L11) |
| `ProviderNativeToolInventoryOptions` | Options accepted by provider native tool inventory. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-native-tool-inventory.ts#L16) |
| `ProviderToolCompatOptions` | Options accepted by provider tool compat. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-tool-compat.ts#L20) |
| `ProviderToolCompatProvider` | Public API contract for provider tool compat provider. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-tool-compat.ts#L5) |
| `ProviderToolProfile` | Public API contract for provider tool profile. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/provider-tool-compat.ts#L13) |
Expand Down
25 changes: 16 additions & 9 deletions docs/architecture/28-model-driven-tool-discovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,13 @@ example. Read it in
[`chat-runtime-tool-assembly.ts`](../../src/agent/hosted/chat-runtime-tool-assembly.ts).

- **deferred**: the agent has no explicit `tools` binding. The model initially
sees only `tool_search` plus whichever bootstrap tools (`form_input`,
`load_skill`) the run actually authorizes. Bootstrap tools are filtered
against the authorized set, so a run that authorizes neither exposes
`tool_search` alone. That is why the measurement below reports one initially
exposed tool.
sees only `tool_search` plus the `load_skill` bootstrap tool when the run
authorizes it. `form_input` remains authorized but deferred until a search
loads it. Bootstrap tools are filtered against the authorized set, so a run
that does not authorize `load_skill` exposes `tool_search` alone. That is why
the measurement below reports one initially exposed tool. Its deterministic
fixture authorizes exactly 64 generated tools and does not authorize
`load_skill`.
- **eager**: the agent declares a binding. The bound set is exposed directly and
`selectProviderCompatibleToolNames` still applies, so a binding larger than
the provider cap is still truncated in alphabetical order after local tools
Expand Down Expand Up @@ -78,14 +80,19 @@ mechanism.
constants in `tool-exposure.ts`.
- Matching schemas are loaded into `ToolExposureState.loadedToolNames` and are
callable from the next model step.
- Configured provider-native tools supported by the selected model enter the
authorized catalog as schema-free name and description records. A matching
search attaches the provider's native schema on the next model step. The
runtime never treats that record as a local executable tool.

## Authorization: two independent gates

1. **Discovery**: `tool_search` searches only the authorized catalog.
2. **Execution**: unchanged. `prepareExecution` in
`project-scoped-remote-tools.ts` re-checks allowance at call time via
`isRemoteToolNameAllowed`, so a schema reaching a request is not sufficient
to execute.
2. **Execution**: `prepareExecution` in
`project-scoped-remote-tools.ts` re-checks remote allowance at call time via
`isRemoteToolNameAllowed`. Provider-native exposure is intersected with the
current configured provider tools and selected model support before each
step. A schema reaching an earlier request is not sufficient to execute.
Comment thread
coderabbitai[bot] marked this conversation as resolved.

## Durability and resume

Expand Down
19 changes: 12 additions & 7 deletions docs/guides/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,11 +154,15 @@ const assistant = agent({
```

The framework `tool_search` fallback is provider-neutral. It searches the
authorized `tools` catalog and does not search `providerTools`. Search ranks an
exact tool name first, followed by normalized substrings in the tool name,
description, and input parameter descriptions. It returns at most five names
and descriptions. Results never include schemas, and `tool_search` has no
pagination options.
authorized `tools` catalog and configured `providerTools` that the selected
model supports. Provider-native entries contain only a name and description
until a search loads them. The runtime attaches the provider's native schema on
the next model step.

Search ranks an exact tool name first, followed by normalized substrings in the
tool name, description, and input parameter descriptions. It returns at most
five names and descriptions. Results never include schemas, and `tool_search`
has no pagination options.

Loading a schema never authorizes a tool. The runtime rechecks authorization
before execution. It also filters restored loaded-tool state against the
Expand All @@ -168,8 +172,9 @@ You can use deferred loading with a direct provider and its API key without
Veryfront Cloud. Hosted durable runs additionally require the Veryfront API
durable run-event contract. The hosted runtime stores loaded-tool state in a
private checkpoint and waits for that checkpoint before continuing. Private
checkpoint data does not appear in public messages or replay. Provider-native
tool search and provider replay are not part of this feature.
checkpoint data does not appear in public messages or replay. Configured,
supported provider-native tools use the same private exposure checkpoint.
Provider replay is not part of this feature.

See [Tools](./tools.md#how-agents-use-tools) for the search and execution flow.

Expand Down
Loading