@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.
Files changed (41) hide show
  1. package/esm/src/guardrails/detectors.d.ts +91 -21
  2. package/esm/src/guardrails/host-patterns.d.ts +15 -2
  3. package/esm/src/guardrails/labels.d.ts +11 -3
  4. package/esm/src/guardrails/labels.js +42 -23
  5. package/esm/src/guardrails/quota.d.ts +9 -3
  6. package/esm/src/guardrails/quota.js +9 -3
  7. package/esm/src/guardrails/theorem-error.d.ts +5 -1
  8. package/esm/src/guardrails/theorem-error.js +8 -4
  9. package/esm/src/guardrails/types.d.ts +66 -18
  10. package/esm/src/guardrails/types.js +22 -3
  11. package/esm/src/kernel/api-catalog.d.ts +26 -75
  12. package/esm/src/kernel/api-catalog.js +37 -119
  13. package/esm/src/kernel/checkpoint.d.ts +5 -1
  14. package/esm/src/kernel/default-scope.d.ts +52 -10
  15. package/esm/src/kernel/default-scope.js +52 -10
  16. package/esm/src/kernel/engine/runner/gates.js +66 -22
  17. package/esm/src/kernel/engine/runner/state.d.ts +5 -2
  18. package/esm/src/kernel/engine/runner/steps.js +15 -15
  19. package/esm/src/kernel/engine/runner/stream.d.ts +5 -0
  20. package/esm/src/kernel/engine/runner/stream.js +12 -1
  21. package/esm/src/kernel/field-docs.d.ts +13 -0
  22. package/esm/src/kernel/field-docs.js +613 -0
  23. package/esm/src/kernel/protocols/binding.d.ts +56 -0
  24. package/esm/src/kernel/protocols/limits.d.ts +9 -0
  25. package/esm/src/kernel/protocols/provider.d.ts +5 -1
  26. package/esm/src/kernel/protocols/provider.js +5 -1
  27. package/esm/src/kernel/registry/profiles.d.ts +154 -5
  28. package/esm/src/kernel/schema.d.ts +5 -7
  29. package/esm/src/kernel/schema.js +511 -470
  30. package/esm/src/kernel/stop.d.ts +41 -17
  31. package/esm/src/kernel/stop.js +9 -1
  32. package/esm/src/kernel/tools/background.d.ts +4 -0
  33. package/esm/src/kernel/tools/types.d.ts +331 -43
  34. package/esm/src/kernel/turn-events.d.ts +4 -3
  35. package/esm/src/kernel/types.d.ts +482 -89
  36. package/esm/src/observability/destinations.d.ts +5 -1
  37. package/esm/src/observability/destinations.js +5 -1
  38. package/esm/src/observability/trace-catalog.js +62 -102
  39. package/esm/src/observability/types.d.ts +93 -19
  40. package/esm/src/providers/shared/carried-tool-files.js +9 -8
  41. 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
- /** Runs before the host's `pre_tool` `onStage`. */
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
- /** The model gets an `after` field: the tools in the same step that must settle before this call starts. */
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
- /** When the model gets its reply. Unset is `never`: when the body ends. A turn without a background service runs inline. */
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
- /** A source that fails `sourceSchema`, or a throw, is a `sources_invalid` warning and is not cited. */
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 `output` the model should see. After the result passes the
175
- * output guard, the kernel fetches each one through the profile's network policy, without the
176
- * tool's credentials, and hands the model the image as a part; one it cannot fetch is an
177
- * `images_unfetched` warning, never a failed call.
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
- /** How many of those pictures the kernel fetches, how large, and how slowly. Left out, there is no limit. */
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
- /** Returns `output`'s type, or `uncheckedOutput(value)` for a value it cannot type. */
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
- * `'page'`: the page the person is on answers the call, and the kernel supplies the handler.
202
- * `output` checks what the page sent.
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
- * The service the handler acts on for the person. The kernel resolves the slot
207
- * before the handler runs (gating, refreshing, or telling the model as the policy
208
- * says) and hands the handler `ctx.signedInFetch`; the handler never sees the credential.
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
- /** The service the person signs in to, as they know it (e.g. "GitHub"); never blank. */
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 (`?key=…`): the query parameter the key
222
- * goes in, in place of a header. Only an `api_key` tool sets it, with no `headerName` or
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
- /** Named on the auth gate for the host's OAuth flow. */
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
- /** The most of a response body the kernel reads; past it the call fails `response_too_large`. Left out, there is no limit. */
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
- * fails `timeout` and frees its place in the limit. Left out, a call waits as long as
255
- * the caller's signal lets it.
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
- /** The most of a response body the kernel reads; past it the call fails `response_too_large`. Left out, there is no limit. */
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
- /** How long and how many of this tool's server sessions the kernel keeps. Left out, there is no limit. */
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
- /** A text, image, or speech profile, registered before this tool. Nothing it can call may gate. */
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
- /** Calls to this tool in one turn of its caller. Omit: only `maxSteps` bounds them. */
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
- /** What the calling model reads on a field of the tool's input, by field. A field the profile does not take is refused. */
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. `onAgentCall` gets them as
320
- * `hostInput` and turns them into the agent's input; they are never sent to the agent.
321
- * A name the input already has is refused, and a call without the hook is a config error.
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
- /** Channels the profile takes that the calling model can't fill; only `onAgentCall` sends them. */
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
- /** Custom tools only; builtins live on `models.*.builtInTools`. */
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
- /** Returns ids already allowed with `loadTier: 'T2'` to load at turn start. Not supported on `type: 'live'`. */
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
- * Must be in `allow`; completing with `{ loaded: string[] }` promotes those T2 ids. Not on `type: 'live'`.
476
- * The tools it loads can be called from the next step.
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
- * `true`: a step's calls run side by side, each body starting once the calls its `pre_tool`
481
- * `waitFor` names have settled. Left out or `false`: one at a time, in the order the model made them.
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
- * `true`: the calls of one model message, run as a step through `invokeToolStep`, run side by
490
- * side, each body starting once the calls its `pre_tool` `waitFor` names have settled. Left out
491
- * or `false`: one at a time, in the order the model made them.
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
- * `true`: the calls of one `invokeToolStep` run side by side, each body starting once the calls
500
- * its `pre_tool` `waitFor` names have settled. Left out or `false`: one at a time, in the order given.
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
- cancelled: "cancelled";
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>;