@theoremjs/agents 0.3.4-next.855.gc82d4ec → 0.3.4-next.869.gb64db05
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/esm/src/guardrails/detectors.d.ts +91 -21
- package/esm/src/guardrails/host-patterns.d.ts +15 -2
- package/esm/src/guardrails/labels.d.ts +11 -3
- package/esm/src/guardrails/labels.js +42 -23
- package/esm/src/guardrails/quota.d.ts +9 -3
- package/esm/src/guardrails/quota.js +9 -3
- package/esm/src/guardrails/theorem-error.d.ts +5 -1
- package/esm/src/guardrails/theorem-error.js +8 -4
- package/esm/src/guardrails/types.d.ts +66 -18
- package/esm/src/guardrails/types.js +22 -3
- package/esm/src/kernel/api-catalog.d.ts +26 -75
- package/esm/src/kernel/api-catalog.js +37 -119
- package/esm/src/kernel/checkpoint.d.ts +5 -1
- package/esm/src/kernel/default-scope.d.ts +52 -10
- package/esm/src/kernel/default-scope.js +52 -10
- package/esm/src/kernel/engine/runner/gates.js +66 -22
- package/esm/src/kernel/engine/runner/state.d.ts +5 -2
- package/esm/src/kernel/engine/runner/steps.js +15 -15
- package/esm/src/kernel/engine/runner/stream.d.ts +5 -0
- package/esm/src/kernel/engine/runner/stream.js +12 -1
- package/esm/src/kernel/field-docs.d.ts +13 -0
- package/esm/src/kernel/field-docs.js +613 -0
- package/esm/src/kernel/protocols/binding.d.ts +56 -0
- package/esm/src/kernel/protocols/limits.d.ts +9 -0
- package/esm/src/kernel/protocols/provider.d.ts +5 -1
- package/esm/src/kernel/protocols/provider.js +5 -1
- package/esm/src/kernel/registry/profiles.d.ts +154 -5
- package/esm/src/kernel/schema.d.ts +5 -7
- package/esm/src/kernel/schema.js +511 -470
- package/esm/src/kernel/stop.d.ts +41 -17
- package/esm/src/kernel/stop.js +9 -1
- package/esm/src/kernel/tools/background.d.ts +4 -0
- package/esm/src/kernel/tools/types.d.ts +331 -43
- package/esm/src/kernel/turn-events.d.ts +4 -3
- package/esm/src/kernel/types.d.ts +482 -89
- package/esm/src/observability/destinations.d.ts +5 -1
- package/esm/src/observability/destinations.js +5 -1
- package/esm/src/observability/trace-catalog.js +62 -102
- package/esm/src/observability/types.d.ts +93 -19
- package/esm/src/providers/shared/carried-tool-files.js +9 -8
- package/package.json +1 -1
|
@@ -13,19 +13,63 @@ import type { PageToolExecution, ToolExecutionCoordinator } from './operation.js
|
|
|
13
13
|
import type { UncheckedOutput } from './unchecked-output.js';
|
|
14
14
|
export type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPermission, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool, };
|
|
15
15
|
export interface ToolLabels {
|
|
16
|
+
/**
|
|
17
|
+
* Transcript text while a call runs, e.g. 'Saving {title} to your collection'. {path} reads the
|
|
18
|
+
* call's input.
|
|
19
|
+
*/
|
|
16
20
|
activity?: LabelTemplate;
|
|
21
|
+
/**
|
|
22
|
+
* What the transcript says once a call completes, e.g. 'Found {results.0.name}'. Each {path} is
|
|
23
|
+
* filled from the call's input, then its output.
|
|
24
|
+
*/
|
|
17
25
|
activityPast?: LabelTemplate;
|
|
26
|
+
/**
|
|
27
|
+
* What the transcript says when a call fails or the host labels it failed, e.g. 'Couldn't save
|
|
28
|
+
* {title}'. Each {path} is filled from the call's input.
|
|
29
|
+
*/
|
|
18
30
|
activityFailed?: LabelTemplate;
|
|
31
|
+
/**
|
|
32
|
+
* What the approval card says the agent wants to do, e.g. 'check the weather in {city}'. Each
|
|
33
|
+
* {path} is filled from the call's input.
|
|
34
|
+
*/
|
|
19
35
|
request?: LabelTemplate;
|
|
20
36
|
}
|
|
21
37
|
export interface ToolBase {
|
|
38
|
+
/**
|
|
39
|
+
* The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model
|
|
40
|
+
* calls a custom tool by.
|
|
41
|
+
*/
|
|
22
42
|
name: string;
|
|
43
|
+
/** Tells the model what the tool does (custom tools only). */
|
|
23
44
|
description: string;
|
|
45
|
+
/** A label for grouping tools; nothing reads it yet. */
|
|
24
46
|
category: string;
|
|
47
|
+
/**
|
|
48
|
+
* What the tool can change, which taint.afterRemoteRead refuses calls by after a turn reads a
|
|
49
|
+
* remote tool's result.
|
|
50
|
+
*/
|
|
25
51
|
access: ToolAccess;
|
|
52
|
+
/**
|
|
53
|
+
* The turn paths this tool is offered on, where * means every path; a turn with no path gets only
|
|
54
|
+
* * tools. Host profiles ignore it.
|
|
55
|
+
*/
|
|
26
56
|
paths: string[];
|
|
57
|
+
/**
|
|
58
|
+
* When the tool becomes available to the model; live and host profiles load every allowed tool at
|
|
59
|
+
* the start.
|
|
60
|
+
*/
|
|
27
61
|
loadTier: ToolLoadTier;
|
|
62
|
+
/** Whether the host must approve a call before it runs; the provider's own tools never ask. */
|
|
28
63
|
permission: ToolPermission;
|
|
64
|
+
/**
|
|
65
|
+
* Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list
|
|
66
|
+
* item. {path|text} shows the text when the value is unusable. {count hit|hits} shows a number
|
|
67
|
+
* with the word for one or for any other number: '1 hit', '3 hits'. With no fallback, the label
|
|
68
|
+
* is dropped. A label is one line, or a list read top to bottom: the first line that fits is
|
|
69
|
+
* shown. A line fits when each {path} has a value and its condition holds, as in 'when status is
|
|
70
|
+
* archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in
|
|
71
|
+
* words. The last line of a list must always fit.
|
|
72
|
+
*/
|
|
29
73
|
labels?: ToolLabels;
|
|
30
74
|
}
|
|
31
75
|
/**
|
|
@@ -33,7 +77,9 @@ export interface ToolBase {
|
|
|
33
77
|
* adapter declares it (`ProviderAdapter.builtins`) and owns how it is sent.
|
|
34
78
|
*/
|
|
35
79
|
export interface BuiltinToolDef extends ToolBase {
|
|
80
|
+
/** How the tool runs. */
|
|
36
81
|
type: 'builtin';
|
|
82
|
+
/** The built-in tools a builtin tool cannot run beside. */
|
|
37
83
|
conflictsWith?: string[];
|
|
38
84
|
}
|
|
39
85
|
/** How a held tool call resumes: approved, refused, or retried after sign-in. */
|
|
@@ -152,32 +198,71 @@ export type ToolHandler<TIn, TOut> = SyncToolHandler<TIn, TOut> | StreamToolHand
|
|
|
152
198
|
* the handler's return type; moving them here silently breaks inference for stream handlers.
|
|
153
199
|
*/
|
|
154
200
|
export interface ToolHostHooks<TIn = unknown> {
|
|
201
|
+
/**
|
|
202
|
+
* The tool's arguments as a JSON Schema, sent to the model.
|
|
203
|
+
*/
|
|
155
204
|
inputSchema: Record<string, unknown>;
|
|
205
|
+
/**
|
|
206
|
+
* The tool's result as a JSON Schema, which a function tool's stand-in result is built from.
|
|
207
|
+
*/
|
|
156
208
|
outputSchema: Record<string, unknown>;
|
|
157
|
-
/**
|
|
209
|
+
/**
|
|
210
|
+
* Runs before the host's pre_tool onStage.
|
|
211
|
+
*
|
|
212
|
+
* @remarks Runs before the host's `pre_tool` `onStage`.
|
|
213
|
+
*/
|
|
158
214
|
preTool?: (input: TIn, ctx: ToolContext) => import('../stages.js').StageResult | undefined | Promise<import('../stages.js').StageResult | undefined>;
|
|
215
|
+
/** Whether the model can see and call the tool. */
|
|
159
216
|
exposeToModel?: boolean;
|
|
160
|
-
/**
|
|
217
|
+
/**
|
|
218
|
+
* Gives the model an after field on this tool: the tools called in the same step that must settle
|
|
219
|
+
* before this call starts. The kernel removes the field before the tool, the stages or a gate
|
|
220
|
+
* read the input. A name with no other call in the step fails the call wait_unknown.
|
|
221
|
+
*
|
|
222
|
+
* @remarks The model gets an `after` field: the tools in the same step that must settle before
|
|
223
|
+
* this call starts.
|
|
224
|
+
*/
|
|
161
225
|
after?: boolean;
|
|
162
|
-
/**
|
|
226
|
+
/**
|
|
227
|
+
* When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }:
|
|
228
|
+
* once the body has run past this time. 'ask': at the hand-off if the model sets the background
|
|
229
|
+
* argument. A turn with no background service runs the tool inline.
|
|
230
|
+
*
|
|
231
|
+
* @remarks When the model gets its reply. Unset is `never`: when the body ends. A turn without a
|
|
232
|
+
* background service runs inline.
|
|
233
|
+
*/
|
|
163
234
|
background?: ToolBackground;
|
|
164
235
|
/** `inputSchema` with the `background` argument. The registry sets it on an `ask` tool. */
|
|
165
236
|
askInputSchema?: Record<string, unknown>;
|
|
166
237
|
}
|
|
167
238
|
export interface ToolOutputHooks<TOut = unknown> {
|
|
168
|
-
/**
|
|
239
|
+
/**
|
|
240
|
+
* The sources a result cites. One that fails sourceSchema, or a throw, is a sources_invalid
|
|
241
|
+
* warning and is not cited.
|
|
242
|
+
*
|
|
243
|
+
* @remarks A source that fails `sourceSchema`, or a throw, is a `sources_invalid` warning and is
|
|
244
|
+
* not cited.
|
|
245
|
+
*/
|
|
169
246
|
sources?: (output: TOut) => Source[];
|
|
170
247
|
}
|
|
171
248
|
/** For a tool whose result names pictures by address; function tools return the bytes themselves as `parts`. */
|
|
172
249
|
export interface ToolImageHooks<TOut = unknown> {
|
|
173
250
|
/**
|
|
174
|
-
* The https addresses of pictures in
|
|
175
|
-
*
|
|
176
|
-
*
|
|
177
|
-
* `
|
|
251
|
+
* The https addresses of pictures in the output the model should see. The kernel fetches each one
|
|
252
|
+
* through the profile network policy, without the tool credentials.
|
|
253
|
+
*
|
|
254
|
+
* @remarks The https addresses of pictures in `output` the model should see. After the result
|
|
255
|
+
* passes the output guard, the kernel fetches each one through the profile's network policy,
|
|
256
|
+
* without the tool's credentials, and hands the model the image as a part; one it cannot fetch is
|
|
257
|
+
* an `images_unfetched` warning, never a failed call.
|
|
178
258
|
*/
|
|
179
259
|
images?: (output: TOut) => string[];
|
|
180
|
-
/**
|
|
260
|
+
/**
|
|
261
|
+
* How many of those pictures the kernel fetches, how large, and how slowly.
|
|
262
|
+
*
|
|
263
|
+
* @remarks How many of those pictures the kernel fetches, how large, and how slowly. Left out,
|
|
264
|
+
* there is no limit.
|
|
265
|
+
*/
|
|
181
266
|
imageLimits?: ToolImageLimits;
|
|
182
267
|
}
|
|
183
268
|
/** Each limit left out is no limit. A picture past one is left out, not cut. */
|
|
@@ -192,67 +277,140 @@ export interface ToolImageLimits {
|
|
|
192
277
|
timeoutMs?: number;
|
|
193
278
|
}
|
|
194
279
|
export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
|
|
280
|
+
/** How the tool runs. */
|
|
195
281
|
type: 'function';
|
|
282
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
196
283
|
input: z.ZodType<TIn>;
|
|
284
|
+
/**
|
|
285
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
286
|
+
* not checked.
|
|
287
|
+
*/
|
|
197
288
|
output: z.ZodType<TOut>;
|
|
198
|
-
/**
|
|
289
|
+
/**
|
|
290
|
+
* Your function that runs the tool; it can also yield progress as it goes.
|
|
291
|
+
*
|
|
292
|
+
* @remarks Returns `output`'s type, or `uncheckedOutput(value)` for a value it cannot type.
|
|
293
|
+
*/
|
|
199
294
|
handler: ToolHandler<TIn, NoInfer<TOut>>;
|
|
200
295
|
/**
|
|
201
|
-
*
|
|
202
|
-
*
|
|
296
|
+
* Who answers a call to a function tool. With page, the page the agent is on returns the
|
|
297
|
+
* output, and the tool has no handler.
|
|
298
|
+
*
|
|
299
|
+
* @remarks `'page'`: the page the person is on answers the call, and the kernel supplies the
|
|
300
|
+
* handler. `output` checks what the page sent.
|
|
203
301
|
*/
|
|
204
302
|
answeredBy?: 'page';
|
|
205
303
|
/**
|
|
206
|
-
*
|
|
207
|
-
*
|
|
208
|
-
*
|
|
304
|
+
* How the tool gets its credential.
|
|
305
|
+
*
|
|
306
|
+
* @remarks The service the handler acts on for the person. The kernel resolves the slot before
|
|
307
|
+
* the handler runs (gating, refreshing, or telling the model as the policy says) and hands the
|
|
308
|
+
* handler `ctx.signedInFetch`; the handler never sees the credential.
|
|
209
309
|
*/
|
|
210
310
|
auth?: ToolAuthConfig;
|
|
211
311
|
}
|
|
212
312
|
/** How a tool that acts for the person signs in to the service; http, mcp, and function tools share it. */
|
|
213
313
|
export interface ToolAuthConfig {
|
|
314
|
+
/** Which of the credentials the turn passes in this tool uses. */
|
|
214
315
|
slot: string;
|
|
316
|
+
/**
|
|
317
|
+
* The kind of credential the tool expects, shown when a turn stops to ask for one; the header
|
|
318
|
+
* follows the stored credential's own kind.
|
|
319
|
+
*/
|
|
215
320
|
type: ToolAuthType;
|
|
216
|
-
/**
|
|
321
|
+
/**
|
|
322
|
+
* The service the person signs in to, as they know it, named when a turn stops to ask for a
|
|
323
|
+
* credential.
|
|
324
|
+
*
|
|
325
|
+
* @remarks The service the person signs in to, as they know it (e.g. "GitHub"); never blank.
|
|
326
|
+
*/
|
|
217
327
|
service: string;
|
|
328
|
+
/** The header the credential goes in; an API key's own headerName comes first. */
|
|
218
329
|
headerName?: string;
|
|
330
|
+
/** Text put before the credential in the header; an API key's own headerPrefix comes first. */
|
|
219
331
|
headerPrefix?: string;
|
|
220
332
|
/**
|
|
221
|
-
* For a service that takes its API key in the URL
|
|
222
|
-
*
|
|
333
|
+
* For a service that takes its API key in the URL: the query parameter the key goes in, in place
|
|
334
|
+
* of a header.
|
|
335
|
+
*
|
|
336
|
+
* @remarks For a service that takes its API key in the URL (`?key=…`): the query parameter the
|
|
337
|
+
* key goes in, in place of a header. Only an `api_key` tool sets it, with no `headerName` or
|
|
223
338
|
* `headerPrefix`.
|
|
224
339
|
*/
|
|
225
340
|
queryParam?: string;
|
|
341
|
+
/**
|
|
342
|
+
* What happens when the credential is missing, expired, can't be refreshed or is refused by the
|
|
343
|
+
* service.
|
|
344
|
+
*/
|
|
226
345
|
onUnauthenticated?: AuthUnauthenticatedPolicy;
|
|
227
|
-
/**
|
|
346
|
+
/**
|
|
347
|
+
* Named on the auth gate for the host's OAuth flow, so it need not find them.
|
|
348
|
+
*
|
|
349
|
+
* @remarks Named on the auth gate for the host's OAuth flow.
|
|
350
|
+
*/
|
|
228
351
|
preResolved?: Partial<OAuthEndpoints & {
|
|
229
352
|
resource: string;
|
|
230
353
|
}>;
|
|
354
|
+
/**
|
|
355
|
+
* The OAuth scopes the tool needs, shown when a turn stops to ask for a credential. A service
|
|
356
|
+
* asking for any other scope fails the call, with no new sign-in.
|
|
357
|
+
*/
|
|
231
358
|
scopes?: string[];
|
|
359
|
+
/** Your OAuth client id, kept for the host's sign-in flow; the kernel doesn't read it. */
|
|
232
360
|
clientId?: string;
|
|
361
|
+
/** Your OAuth redirect URI, kept for the host's sign-in flow; the kernel doesn't read it. */
|
|
233
362
|
redirectUri?: string;
|
|
234
363
|
}
|
|
235
364
|
export interface HttpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut>, ToolImageHooks<TOut> {
|
|
365
|
+
/** How the tool runs. */
|
|
236
366
|
type: 'http';
|
|
367
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
237
368
|
input: z.ZodType<TIn>;
|
|
369
|
+
/**
|
|
370
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
371
|
+
* not checked.
|
|
372
|
+
*/
|
|
238
373
|
output: z.ZodType<TOut>;
|
|
374
|
+
/**
|
|
375
|
+
* The URL the tool calls, with {name} placeholders for mapping.pathParams; the scheme and host
|
|
376
|
+
* must be written out.
|
|
377
|
+
*/
|
|
239
378
|
endpoint: string;
|
|
379
|
+
/** The HTTP method; every method but GET sends a JSON body. */
|
|
240
380
|
method: HttpMethod;
|
|
381
|
+
/** Headers sent with every request to the tool's own origin, never once a redirect leaves it. */
|
|
241
382
|
headers?: Record<string, string>;
|
|
383
|
+
/** How the tool gets its credential. */
|
|
242
384
|
auth?: ToolAuthConfig;
|
|
385
|
+
/** Where each argument goes in the request. */
|
|
243
386
|
mapping?: {
|
|
387
|
+
/** Arguments that fill the {name} placeholders in the endpoint. */
|
|
244
388
|
pathParams?: string[];
|
|
389
|
+
/** Arguments added to the query string. */
|
|
245
390
|
queryParams?: string[];
|
|
391
|
+
/**
|
|
392
|
+
* The one argument sent as the whole JSON body; without it, a method other than GET sends every
|
|
393
|
+
* argument the path and query leave unused.
|
|
394
|
+
*/
|
|
246
395
|
bodyParam?: string;
|
|
247
396
|
};
|
|
248
397
|
/** The service's own limit for one key; the kernel keeps this tool's requests within it. */
|
|
249
398
|
limit?: HttpToolLimit;
|
|
250
|
-
/**
|
|
399
|
+
/**
|
|
400
|
+
* The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with
|
|
401
|
+
* response_too_large.
|
|
402
|
+
*
|
|
403
|
+
* @remarks The most of a response body the kernel reads; past it the call fails
|
|
404
|
+
* `response_too_large`. Left out, there is no limit.
|
|
405
|
+
*/
|
|
251
406
|
maxResponseBytes?: number;
|
|
252
407
|
/**
|
|
253
|
-
* How long the service may take to answer, its body read included. Past it the call
|
|
254
|
-
*
|
|
255
|
-
*
|
|
408
|
+
* How long the service may take to answer, its body read included. Past it the call fails timeout
|
|
409
|
+
* and frees its place in the limit.
|
|
410
|
+
*
|
|
411
|
+
* @remarks How long the service may take to answer, its body read included. Past it the call
|
|
412
|
+
* fails `timeout` and frees its place in the limit. Left out, a call waits as long as the
|
|
413
|
+
* caller's signal lets it.
|
|
256
414
|
*/
|
|
257
415
|
timeoutMs?: number;
|
|
258
416
|
}
|
|
@@ -262,16 +420,37 @@ export interface HttpToolLimit {
|
|
|
262
420
|
windowMs: number;
|
|
263
421
|
}
|
|
264
422
|
export interface McpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut>, ToolImageHooks<TOut> {
|
|
423
|
+
/** How the tool runs. */
|
|
265
424
|
type: 'mcp';
|
|
425
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
266
426
|
input: z.ZodType<TIn>;
|
|
427
|
+
/**
|
|
428
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
429
|
+
* not checked.
|
|
430
|
+
*/
|
|
267
431
|
output: z.ZodType<TOut>;
|
|
432
|
+
/** The MCP server's URL. */
|
|
268
433
|
serverUrl: string;
|
|
434
|
+
/** The tool's name on the MCP server. */
|
|
269
435
|
mcpToolName: string;
|
|
436
|
+
/** Headers sent with every request to the tool's own origin, never once a redirect leaves it. */
|
|
270
437
|
headers?: Record<string, string>;
|
|
438
|
+
/** How the tool gets its credential. */
|
|
271
439
|
auth?: ToolAuthConfig;
|
|
272
|
-
/**
|
|
440
|
+
/**
|
|
441
|
+
* The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with
|
|
442
|
+
* response_too_large.
|
|
443
|
+
*
|
|
444
|
+
* @remarks The most of a response body the kernel reads; past it the call fails
|
|
445
|
+
* `response_too_large`. Left out, there is no limit.
|
|
446
|
+
*/
|
|
273
447
|
maxResponseBytes?: number;
|
|
274
|
-
/**
|
|
448
|
+
/**
|
|
449
|
+
* How long and how many of an MCP tool's server sessions the kernel keeps.
|
|
450
|
+
*
|
|
451
|
+
* @remarks How long and how many of this tool's server sessions the kernel keeps. Left out, there
|
|
452
|
+
* is no limit.
|
|
453
|
+
*/
|
|
275
454
|
session?: McpSessionLimits;
|
|
276
455
|
}
|
|
277
456
|
/** The sessions an MCP tool keeps: each field left out is no limit. */
|
|
@@ -308,28 +487,72 @@ export type AgentToolChannel = 'attachments' | 'voice' | 'options';
|
|
|
308
487
|
* is what that profile's `inputs` declares; the host can reshape a call (`onAgentCall`).
|
|
309
488
|
*/
|
|
310
489
|
export interface AgentToolDef extends ToolBase {
|
|
490
|
+
/** How the tool runs. */
|
|
311
491
|
type: 'agent';
|
|
312
|
-
/**
|
|
492
|
+
/**
|
|
493
|
+
* The profile this agent tool runs: text, image, or speech. Register it first. Nothing it calls
|
|
494
|
+
* may stop on a gate.
|
|
495
|
+
*
|
|
496
|
+
* @remarks A text, image, or speech profile, registered before this tool. Nothing it can call may
|
|
497
|
+
* gate.
|
|
498
|
+
*/
|
|
313
499
|
profile: ProfileId;
|
|
314
|
-
/**
|
|
500
|
+
/**
|
|
501
|
+
* How many times one turn of the calling agent may run this tool.
|
|
502
|
+
*
|
|
503
|
+
* @remarks Calls to this tool in one turn of its caller. Omit: only `maxSteps` bounds them.
|
|
504
|
+
*/
|
|
315
505
|
maxCallsPerTurn?: number;
|
|
316
|
-
/**
|
|
506
|
+
/**
|
|
507
|
+
* What the calling model reads on a field of an agent tool input, such as text. A field the
|
|
508
|
+
* profile does not take is refused when the tool registers.
|
|
509
|
+
*
|
|
510
|
+
* @remarks What the calling model reads on a field of the tool's input, by field. A field the
|
|
511
|
+
* profile does not take is refused.
|
|
512
|
+
*/
|
|
317
513
|
fieldText?: Partial<Record<keyof AgentToolInput, string>>;
|
|
318
514
|
/**
|
|
319
|
-
* Fields the calling model fills that only the host reads.
|
|
320
|
-
*
|
|
321
|
-
*
|
|
515
|
+
* Fields the calling model fills on an agent tool that only the host reads. onAgentCall gets them
|
|
516
|
+
* as hostInput and turns them into what the agent is sent; the agent never sees them. A name the
|
|
517
|
+
* input already has is refused when the tool registers.
|
|
518
|
+
*
|
|
519
|
+
* @remarks Fields the calling model fills that only the host reads. `onAgentCall` gets them as
|
|
520
|
+
* `hostInput` and turns them into the agent's input; they are never sent to the agent. A name the
|
|
521
|
+
* input already has is refused, and a call without the hook is a config error.
|
|
322
522
|
*/
|
|
323
523
|
hostFields?: Record<string, z.ZodType>;
|
|
324
|
-
/**
|
|
524
|
+
/**
|
|
525
|
+
* Channels the called profile takes that the calling model cannot fill on an agent tool; only
|
|
526
|
+
* onAgentCall sends them. A channel the profile does not take is refused when the tool registers.
|
|
527
|
+
*
|
|
528
|
+
* @remarks Channels the profile takes that the calling model can't fill; only `onAgentCall` sends
|
|
529
|
+
* them.
|
|
530
|
+
*/
|
|
325
531
|
hostOnly?: AgentToolChannel[];
|
|
532
|
+
/** Runs before the host's pre_tool onStage. */
|
|
326
533
|
preTool?: ToolHostHooks<AgentToolInput>['preTool'];
|
|
534
|
+
/**
|
|
535
|
+
* Gives the model an after field on this tool: the tools called in the same step that must settle
|
|
536
|
+
* before this call starts. The kernel removes the field before the tool, the stages or a gate
|
|
537
|
+
* read the input. A name with no other call in the step fails the call wait_unknown.
|
|
538
|
+
*/
|
|
327
539
|
after?: ToolHostHooks<AgentToolInput>['after'];
|
|
540
|
+
/**
|
|
541
|
+
* When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }:
|
|
542
|
+
* once the body has run past this time. 'ask': at the hand-off if the model sets the background
|
|
543
|
+
* argument. A turn with no background service runs the tool inline.
|
|
544
|
+
*/
|
|
328
545
|
background?: ToolHostHooks<AgentToolInput>['background'];
|
|
546
|
+
/** Whether the model can see and call the tool. */
|
|
329
547
|
exposeToModel?: boolean;
|
|
330
548
|
}
|
|
331
549
|
export interface RegisteredAgentTool extends AgentToolDef, ToolHostHooks<AgentToolInput>, ToolOutputHooks<AgentToolOutput> {
|
|
550
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
332
551
|
input: z.ZodType<AgentToolInput>;
|
|
552
|
+
/**
|
|
553
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
554
|
+
* not checked.
|
|
555
|
+
*/
|
|
333
556
|
output: z.ZodType<AgentToolOutput>;
|
|
334
557
|
}
|
|
335
558
|
/** An agent tool call, as the host's `onAgentCall` sees it before the agent runs. */
|
|
@@ -371,20 +594,45 @@ export type AgentCallHook = (call: AgentCall) => AgentCallRequest | {
|
|
|
371
594
|
export type RegisteredTool<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolDef<TIn, TOut> | HttpToolDef<TIn, TOut> | McpToolDef<TIn, TOut> | RegisteredAgentTool;
|
|
372
595
|
/** A function tool as registered: it has a `handler`, or the page answers it. */
|
|
373
596
|
export type FunctionToolInput<TIn = unknown, TOut = unknown> = Omit<FunctionToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema' | 'handler' | 'answeredBy'> & {
|
|
597
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
374
598
|
input: z.ZodType<TIn>;
|
|
599
|
+
/**
|
|
600
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
601
|
+
* not checked.
|
|
602
|
+
*/
|
|
375
603
|
output: z.ZodType<TOut>;
|
|
376
604
|
} & ({
|
|
605
|
+
/** Your function that runs the tool; it can also yield progress as it goes. */
|
|
377
606
|
handler: ToolHandler<TIn, NoInfer<TOut>>;
|
|
607
|
+
/**
|
|
608
|
+
* Who answers a call to a function tool. With page, the page the agent is on returns the
|
|
609
|
+
* output, and the tool has no handler.
|
|
610
|
+
*/
|
|
378
611
|
answeredBy?: 'page';
|
|
379
612
|
} | {
|
|
613
|
+
/**
|
|
614
|
+
* Who answers a call to a function tool. With page, the page the agent is on returns the
|
|
615
|
+
* output, and the tool has no handler.
|
|
616
|
+
*/
|
|
380
617
|
answeredBy: 'page';
|
|
618
|
+
/** Your function that runs the tool; it can also yield progress as it goes. */
|
|
381
619
|
handler?: undefined;
|
|
382
620
|
});
|
|
383
621
|
export type ToolDefinitionInput<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolInput<TIn, TOut> | (Omit<HttpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
|
|
622
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
384
623
|
input: z.ZodType<TIn>;
|
|
624
|
+
/**
|
|
625
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in
|
|
626
|
+
* note is not checked.
|
|
627
|
+
*/
|
|
385
628
|
output: z.ZodType<TOut>;
|
|
386
629
|
}) | (Omit<McpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
|
|
630
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
387
631
|
input: z.ZodType<TIn>;
|
|
632
|
+
/**
|
|
633
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in
|
|
634
|
+
* note is not checked.
|
|
635
|
+
*/
|
|
388
636
|
output: z.ZodType<TOut>;
|
|
389
637
|
}) | AgentToolDef;
|
|
390
638
|
export interface PromoteLoadedResult {
|
|
@@ -467,37 +715,77 @@ export interface InvokeToolStepRequest extends Omit<InvokeToolRequest, 'name' |
|
|
|
467
715
|
}
|
|
468
716
|
/** The tools a profile may use and how they load. */
|
|
469
717
|
export interface ProfileToolsSpec {
|
|
470
|
-
/**
|
|
718
|
+
/**
|
|
719
|
+
* Your registered tools this agent may use; the provider's own tools go on the model's
|
|
720
|
+
* builtInTools instead.
|
|
721
|
+
*
|
|
722
|
+
* @remarks Custom tools only; builtins live on `models.*.builtInTools`.
|
|
723
|
+
*/
|
|
471
724
|
allow: ToolId[];
|
|
472
|
-
/**
|
|
725
|
+
/**
|
|
726
|
+
* Your function that picks, at the start of each turn, which T2 tools to load up front; the rest
|
|
727
|
+
* wait for tools.t2Loader.
|
|
728
|
+
*
|
|
729
|
+
* @remarks Returns ids already allowed with `loadTier: 'T2'` to load at turn start. Not supported
|
|
730
|
+
* on `type: 'live'`.
|
|
731
|
+
*/
|
|
473
732
|
t1Policy?: ToolPolicy;
|
|
474
733
|
/**
|
|
475
|
-
*
|
|
476
|
-
* The tools it loads can be
|
|
734
|
+
* The function tool that loads T2 tools. It must be in allow and return { loaded: ToolId[] }. One
|
|
735
|
+
* forbidden id fails the load. Ids off the turn path are skipped. The tools it loads can be
|
|
736
|
+
* called from the next step: a step's calls see the tools as they stood when the step began.
|
|
737
|
+
*
|
|
738
|
+
* @remarks Must be in `allow`; completing with `{ loaded: string[] }` promotes those T2 ids. Not
|
|
739
|
+
* on `type: 'live'`. The tools it loads can be called from the next step.
|
|
477
740
|
*/
|
|
478
741
|
t2Loader?: ToolId;
|
|
479
742
|
/**
|
|
480
|
-
*
|
|
481
|
-
*
|
|
743
|
+
* true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
|
|
744
|
+
* its body once those calls settle. Left out or false: they run one at a time, in the order the
|
|
745
|
+
* model made them. A step is the calls the model makes together in a turn, or the calls a host
|
|
746
|
+
* runs through invokeToolStep.
|
|
747
|
+
*
|
|
748
|
+
* @remarks `true`: a step's calls run side by side, each body starting once the calls its
|
|
749
|
+
* `pre_tool` `waitFor` names have settled. Left out or `false`: one at a time, in the order the
|
|
750
|
+
* model made them.
|
|
482
751
|
*/
|
|
483
752
|
parallel?: boolean;
|
|
484
753
|
}
|
|
485
754
|
/** Live declarations cannot be added mid-session, so every allowed tool is wired at setup as if T0. */
|
|
486
755
|
export interface LiveProfileToolsSpec {
|
|
756
|
+
/**
|
|
757
|
+
* Your registered tools this agent may use; the provider's own tools go on the model's
|
|
758
|
+
* builtInTools instead.
|
|
759
|
+
*/
|
|
487
760
|
allow: ToolId[];
|
|
488
761
|
/**
|
|
489
|
-
*
|
|
490
|
-
*
|
|
491
|
-
*
|
|
762
|
+
* true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
|
|
763
|
+
* its body once those calls settle. Left out or false: they run one at a time, in the order the
|
|
764
|
+
* model made them. A step is the calls the model makes together in a turn, or the calls a host
|
|
765
|
+
* runs through invokeToolStep.
|
|
766
|
+
*
|
|
767
|
+
* @remarks `true`: the calls of one model message, run as a step through `invokeToolStep`, run
|
|
768
|
+
* side by side, each body starting once the calls its `pre_tool` `waitFor` names have settled.
|
|
769
|
+
* Left out or `false`: one at a time, in the order the model made them.
|
|
492
770
|
*/
|
|
493
771
|
parallel?: boolean;
|
|
494
772
|
}
|
|
495
773
|
/** Every id in `allow` is invokable with no visibility tiers and no path gating. */
|
|
496
774
|
export interface HostProfileToolsSpec {
|
|
775
|
+
/**
|
|
776
|
+
* Your registered tools this agent may use; the provider's own tools go on the model's
|
|
777
|
+
* builtInTools instead.
|
|
778
|
+
*/
|
|
497
779
|
allow: ToolId[];
|
|
498
780
|
/**
|
|
499
|
-
*
|
|
500
|
-
* its
|
|
781
|
+
* true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
|
|
782
|
+
* its body once those calls settle. Left out or false: they run one at a time, in the order the
|
|
783
|
+
* model made them. A step is the calls the model makes together in a turn, or the calls a host
|
|
784
|
+
* runs through invokeToolStep.
|
|
785
|
+
*
|
|
786
|
+
* @remarks `true`: the calls of one `invokeToolStep` run side by side, each body starting once
|
|
787
|
+
* the calls its `pre_tool` `waitFor` names have settled. Left out or `false`: one at a time, in
|
|
788
|
+
* the order given.
|
|
501
789
|
*/
|
|
502
790
|
parallel?: boolean;
|
|
503
791
|
}
|
|
@@ -77,6 +77,7 @@ export interface InjectedMessages {
|
|
|
77
77
|
}
|
|
78
78
|
/** Why a turn or live utterance ended. */
|
|
79
79
|
export interface TurnStop {
|
|
80
|
+
/** Why the turn ended, on the done event: its stop.kind. */
|
|
80
81
|
kind: TurnStopKind;
|
|
81
82
|
native?: string;
|
|
82
83
|
}
|
|
@@ -84,15 +85,15 @@ export declare const turnStopSchema: z.ZodObject<{
|
|
|
84
85
|
kind: z.ZodEnum<{
|
|
85
86
|
length: "length";
|
|
86
87
|
tool: "tool";
|
|
87
|
-
|
|
88
|
-
interrupted: "interrupted";
|
|
88
|
+
gate: "gate";
|
|
89
89
|
stream_incomplete: "stream_incomplete";
|
|
90
90
|
provider_error: "provider_error";
|
|
91
91
|
answer_missing: "answer_missing";
|
|
92
|
+
cancelled: "cancelled";
|
|
92
93
|
completed: "completed";
|
|
93
|
-
gate: "gate";
|
|
94
94
|
filtered: "filtered";
|
|
95
95
|
step_limit: "step_limit";
|
|
96
|
+
interrupted: "interrupted";
|
|
96
97
|
generation_complete: "generation_complete";
|
|
97
98
|
}>;
|
|
98
99
|
native: z.ZodOptional<z.ZodString>;
|