Skip to content

Commit a52d8ff

Browse files
bloveblove
authored
feat: add client tool execution claims (#789)
1 parent 7684fc2 commit a52d8ff

14 files changed

Lines changed: 1104 additions & 15 deletions

‎apps/website/content/docs/chat/api/api-docs.json‎

Lines changed: 230 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1821,6 +1821,12 @@
18211821
"description": "",
18221822
"optional": false
18231823
},
1824+
{
1825+
"name": "clientToolExecutionGuard",
1826+
"type": "InputSignal<ClientToolExecutionGuard | undefined>",
1827+
"description": "",
1828+
"optional": false
1829+
},
18241830
{
18251831
"name": "clientTools",
18261832
"type": "InputSignal<Readonly<Record<string, ClientToolDef>> | undefined>",
@@ -6309,6 +6315,12 @@
63096315
"description": "",
63106316
"optional": false
63116317
},
6318+
{
6319+
"name": "idempotent",
6320+
"type": "boolean",
6321+
"description": "",
6322+
"optional": true
6323+
},
63126324
{
63136325
"name": "kind",
63146326
"type": "\"function\"",
@@ -6688,6 +6700,134 @@
66886700
],
66896701
"examples": []
66906702
},
6703+
{
6704+
"name": "ClientToolExecutionGuard",
6705+
"kind": "interface",
6706+
"description": "Opt-in guard configuration for claim-before-execute client tools.",
6707+
"properties": [
6708+
{
6709+
"name": "store",
6710+
"type": "ClientToolExecutionStore",
6711+
"description": "",
6712+
"optional": false
6713+
},
6714+
{
6715+
"name": "threadId",
6716+
"type": "string",
6717+
"description": "",
6718+
"optional": false
6719+
}
6720+
],
6721+
"examples": []
6722+
},
6723+
{
6724+
"name": "ClientToolExecutionKey",
6725+
"kind": "interface",
6726+
"description": "Durable identity for one client-tool execution on one thread.",
6727+
"properties": [
6728+
{
6729+
"name": "threadId",
6730+
"type": "string",
6731+
"description": "",
6732+
"optional": false
6733+
},
6734+
{
6735+
"name": "toolCallId",
6736+
"type": "string",
6737+
"description": "",
6738+
"optional": false
6739+
}
6740+
],
6741+
"examples": []
6742+
},
6743+
{
6744+
"name": "ClientToolExecutionOptions",
6745+
"kind": "interface",
6746+
"description": "Execution policy options for browser-executed function tools.",
6747+
"properties": [
6748+
{
6749+
"name": "idempotent",
6750+
"type": "boolean",
6751+
"description": "True when the handler may safely re-run and should skip durable pre-claims.",
6752+
"optional": true
6753+
}
6754+
],
6755+
"examples": []
6756+
},
6757+
{
6758+
"name": "ClientToolExecutionStore",
6759+
"kind": "interface",
6760+
"description": "Structural store contract for guarded browser client-tool execution.",
6761+
"properties": [],
6762+
"methods": [
6763+
{
6764+
"name": "claim",
6765+
"signature": "claim(key: ClientToolExecutionKey): Promise<\"claimed\" | ClientToolExecutionRecord>",
6766+
"description": "Atomically claim a tool-call execution. Returns prior state when present.",
6767+
"params": [
6768+
{
6769+
"name": "key",
6770+
"type": "ClientToolExecutionKey",
6771+
"description": "",
6772+
"optional": false
6773+
}
6774+
]
6775+
},
6776+
{
6777+
"name": "lookup",
6778+
"signature": "lookup(threadId: string, toolCallIds: readonly string[]): Promise<Record<string, ClientToolExecutionRecord>>",
6779+
"description": "Lookup prior execution states for pending tool calls on a thread.",
6780+
"params": [
6781+
{
6782+
"name": "threadId",
6783+
"type": "string",
6784+
"description": "",
6785+
"optional": false
6786+
},
6787+
{
6788+
"name": "toolCallIds",
6789+
"type": "readonly string[]",
6790+
"description": "",
6791+
"optional": false
6792+
}
6793+
]
6794+
},
6795+
{
6796+
"name": "record",
6797+
"signature": "record(key: ClientToolExecutionKey, result: ClientToolResult): Promise<void>",
6798+
"description": "Record the final client-tool result for a claimed execution.",
6799+
"params": [
6800+
{
6801+
"name": "key",
6802+
"type": "ClientToolExecutionKey",
6803+
"description": "",
6804+
"optional": false
6805+
},
6806+
{
6807+
"name": "result",
6808+
"type": "ClientToolResult",
6809+
"description": "",
6810+
"optional": false
6811+
}
6812+
]
6813+
}
6814+
],
6815+
"examples": []
6816+
},
6817+
{
6818+
"name": "ClientToolExecutorOptions",
6819+
"kind": "interface",
6820+
"description": "Options for wiring automatic browser function-tool execution.",
6821+
"properties": [
6822+
{
6823+
"name": "executionGuard",
6824+
"type": "ClientToolExecutionGuard",
6825+
"description": "",
6826+
"optional": true
6827+
}
6828+
],
6829+
"examples": []
6830+
},
66916831
{
66926832
"name": "ClientToolsCapability",
66936833
"kind": "interface",
@@ -6980,6 +7120,12 @@
69807120
"description": "",
69817121
"optional": false
69827122
},
7123+
{
7124+
"name": "idempotent",
7125+
"type": "boolean",
7126+
"description": "",
7127+
"optional": true
7128+
},
69837129
{
69847130
"name": "kind",
69857131
"type": "\"function\"",
@@ -7979,6 +8125,13 @@
79798125
"signature": "AnyFunctionToolDef | ViewToolDef | AskToolDef",
79808126
"examples": []
79818127
},
8128+
{
8129+
"name": "ClientToolExecutionRecord",
8130+
"kind": "type",
8131+
"description": "Prior durable execution state returned by a client-tool execution store.",
8132+
"signature": "object | object | object",
8133+
"examples": []
8134+
},
79828135
{
79838136
"name": "ClientToolRegistry",
79848137
"kind": "type",
@@ -8158,7 +8311,7 @@
81588311
"name": "action",
81598312
"kind": "function",
81608313
"description": "Declare an async function tool the model can call; its resolved return value\nbecomes the tool result shipped back to the model.",
8161-
"signature": "action(description: string, schema: S, handler: (args: StandardSchemaInferOutput<S>, context: FunctionToolHandlerContext) => R | Promise<R>): FunctionToolDef<S, R>",
8314+
"signature": "action(description: string, schema: S, handler: (args: StandardSchemaInferOutput<S>, context: FunctionToolHandlerContext) => R | Promise<R>, options: ClientToolExecutionOptions): FunctionToolDef<S, R>",
81628315
"params": [
81638316
{
81648317
"name": "description",
@@ -8177,6 +8330,12 @@
81778330
"type": "(args: StandardSchemaInferOutput<S>, context: FunctionToolHandlerContext) => R | Promise<R>",
81788331
"description": "Runs in the browser when the model calls the tool. The second\n argument carries an `AbortSignal`; its return type `R` is carried on the\n resulting FunctionToolDef.",
81798332
"optional": false
8333+
},
8334+
{
8335+
"name": "options",
8336+
"type": "ClientToolExecutionOptions",
8337+
"description": "Execution policy options, including `idempotent: true` to skip\n durable pre-execution claims when a guard is configured.",
8338+
"optional": true
81808339
}
81818340
],
81828341
"returns": {
@@ -8302,6 +8461,31 @@
83028461
},
83038462
"examples": []
83048463
},
8464+
{
8465+
"name": "clientToolGuardFailureResult",
8466+
"kind": "function",
8467+
"description": "Default fail-closed result when the execution guard itself cannot be reached.",
8468+
"signature": "clientToolGuardFailureResult(toolCallId: string, error: unknown): ClientToolResult",
8469+
"params": [
8470+
{
8471+
"name": "toolCallId",
8472+
"type": "string",
8473+
"description": "",
8474+
"optional": false
8475+
},
8476+
{
8477+
"name": "error",
8478+
"type": "unknown",
8479+
"description": "",
8480+
"optional": false
8481+
}
8482+
],
8483+
"returns": {
8484+
"type": "ClientToolResult",
8485+
"description": ""
8486+
},
8487+
"examples": []
8488+
},
83058489
{
83068490
"name": "createA2uiSurfaceStore",
83078491
"kind": "function",
@@ -8391,6 +8575,25 @@
83918575
},
83928576
"examples": []
83938577
},
8578+
{
8579+
"name": "defaultInterruptedClientToolResult",
8580+
"kind": "function",
8581+
"description": "Default fail-closed result for a stale in-progress client-tool execution.",
8582+
"signature": "defaultInterruptedClientToolResult(toolCallId: string): ClientToolResult",
8583+
"params": [
8584+
{
8585+
"name": "toolCallId",
8586+
"type": "string",
8587+
"description": "",
8588+
"optional": false
8589+
}
8590+
],
8591+
"returns": {
8592+
"type": "ClientToolResult",
8593+
"description": ""
8594+
},
8595+
"examples": []
8596+
},
83948597
{
83958598
"name": "deriveDomain",
83968599
"kind": "function",
@@ -8966,11 +9169,30 @@
89669169
},
89679170
"examples": []
89689171
},
9172+
{
9173+
"name": "shouldClaimBeforeExecute",
9174+
"kind": "function",
9175+
"description": "Return whether this function tool should claim before browser execution.",
9176+
"signature": "shouldClaimBeforeExecute(def: AnyFunctionToolDef): boolean",
9177+
"params": [
9178+
{
9179+
"name": "def",
9180+
"type": "AnyFunctionToolDef",
9181+
"description": "",
9182+
"optional": false
9183+
}
9184+
],
9185+
"returns": {
9186+
"type": "boolean",
9187+
"description": ""
9188+
},
9189+
"examples": []
9190+
},
89699191
{
89709192
"name": "startClientToolExecutor",
89719193
"kind": "function",
89729194
"description": "Watches the agent's pending client tool calls and auto-runs FUNCTION tools,\nresolving each with its result. View/ask (component) tools are handled by the\nrendering layer, not here. No-op if the agent lacks the clientTools\ncapability. MUST be called in an injection context (sets up an effect).",
8973-
"signature": "startClientToolExecutor(agent: Agent<>, registry: ClientToolRegistry): void",
9195+
"signature": "startClientToolExecutor(agent: Agent<>, registry: ClientToolRegistry, options: ClientToolExecutorOptions): void",
89749196
"params": [
89759197
{
89769198
"name": "agent",
@@ -8983,6 +9205,12 @@
89839205
"type": "ClientToolRegistry",
89849206
"description": "",
89859207
"optional": false
9208+
},
9209+
{
9210+
"name": "options",
9211+
"type": "ClientToolExecutorOptions",
9212+
"description": "",
9213+
"optional": true
89869214
}
89879215
],
89889216
"returns": {

0 commit comments

Comments
 (0)