@theoremjs/studio 0.3.4-next.863.gb601f58 → 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 (71) hide show
  1. package/browser-connection.d.ts +12 -0
  2. package/draft.d.ts +26 -2
  3. package/map.d.ts +13 -0
  4. package/map.js +28 -0
  5. package/mod.d.ts +1 -1
  6. package/mod.js +1 -1
  7. package/package.json +4 -4
  8. package/page/assets/{BottomSheet-B8-prREc.js → BottomSheet-Bdz8RqsO.js} +1 -1
  9. package/page/assets/{ConsoleFrame-CYYtfWNI.js → ConsoleFrame-prQmvBQJ.js} +1 -1
  10. package/page/assets/{DateInput-CaOcecG2.js → DateInput-C-NBD2Av.js} +1 -1
  11. package/page/assets/{MenuBottomSheet-Ctymn_LQ.js → MenuBottomSheet-BAKdx1Jc.js} +1 -1
  12. package/page/assets/{SchemaFields-D1_c3uax.js → SchemaFields-B8ZoCrBk.js} +1 -1
  13. package/page/assets/{TokenizerBottomSheet-BOahsgu5.js → TokenizerBottomSheet-DgHHQbMZ.js} +1 -1
  14. package/page/assets/{ToolResultCharts-DxlRxTlp.js → ToolResultCharts-8Z8PG65Q.js} +1 -1
  15. package/page/assets/{Toolbar-DzqcK9Za.js → Toolbar-CH-nc1zH.js} +1 -1
  16. package/page/assets/TraceInspector-BlLVhWaD.js +1 -0
  17. package/page/assets/TraceOverview-DGIAvCW_.js +57 -0
  18. package/page/assets/{_virtual_studio-type-sources-DW2xrHRZ.js → _virtual_studio-type-sources-NQ8eY2_H.js} +1470 -320
  19. package/page/assets/browser-connection-Nwupg4Oq.js +1 -0
  20. package/page/assets/browser-engine-CLCjrxrC.js +16 -0
  21. package/page/assets/browser-transport-Bv6Cau54.js +2 -0
  22. package/page/assets/compile-Brpb8u3_.js +2 -0
  23. package/page/assets/{encode-files-JlTZOKQT.js → encode-files-CQ_E7QUG.js} +1 -1
  24. package/page/assets/{export-agent-DbT9mJEv.js → export-agent-Cmvo5grj.js} +1 -1
  25. package/page/assets/{guardrail-tester-XhX2mqHc.js → guardrail-tester-BrxgKLMf.js} +1 -1
  26. package/page/assets/{index-C1WNmgOO.js → index-B9sy5r24.js} +73 -73
  27. package/page/assets/{json-code-DoIDKNEG.js → json-code-BjPSAV7R.js} +1 -1
  28. package/page/assets/{labels-provider-Bv9WPagB.js → labels-provider-Cdg61Tfx.js} +1 -1
  29. package/page/assets/{live-messages-iGBTap-t.js → live-messages-CDqr92n4.js} +1 -1
  30. package/page/assets/{prompt-row-Bsz-A4Bf.js → prompt-row-6SUZf7NQ.js} +1 -1
  31. package/page/assets/reader-CYeq9zud.js +5 -0
  32. package/page/assets/registry-Du0mj5wR.js +1 -0
  33. package/page/assets/{schema-DfEjr_N4.js → schema-Cra2BPNa.js} +2 -2
  34. package/page/assets/shaped-data-BlRLB3TY.js +25 -0
  35. package/page/assets/{stub-CsZVvwgT.js → stub-J7M8qV3l.js} +1 -1
  36. package/page/assets/{studio-code-pane-Db-AAr3b.js → studio-code-pane-T1G5_SXQ.js} +4 -4
  37. package/page/assets/{studio-console-71u2GwPw.js → studio-console-Dhjgp9m8.js} +1 -1
  38. package/page/assets/{studio-decision-BHPpdQM9.js → studio-decision-BvTPixPE.js} +1 -1
  39. package/page/assets/{studio-embedding-VyWNTUU8.js → studio-embedding-CI1qYy8H.js} +1 -1
  40. package/page/assets/{studio-host-console-C1Rt8PSv.js → studio-host-console-BOR62HKM.js} +2 -2
  41. package/page/assets/{studio-labels-EQRWPOr5.js → studio-labels-2O090qBe.js} +2 -2
  42. package/page/assets/{studio-live-D0pjddZ9.js → studio-live-PavFV9rI.js} +2 -2
  43. package/page/assets/studio-map-zWaeNeKY.js +1 -0
  44. package/page/assets/studio-trace-replay-DjJvbdOo.js +3 -0
  45. package/page/assets/{studio-type-checker-dXJ4DZVL.js → studio-type-checker-DDcpR_0b.js} +1 -1
  46. package/page/assets/tool-schema-DWmQkthX.js +13 -0
  47. package/page/assets/trace-record-C07Cf_EG.js +1 -0
  48. package/page/assets/tree-CgaAoXtn.js +3 -0
  49. package/page/assets/{turn-client-CobwqNwm.js → turn-client-B4zazitl.js} +2 -2
  50. package/page/assets/{types-2sRz_M-W.js → types-D5agZBnA.js} +1 -1
  51. package/page/assets/{use-one-call-CMoYqsKk.js → use-one-call-BgGMm9MZ.js} +1 -1
  52. package/page/assets/{workspace-C7bvk7HE.js → workspace-Dsqtx6eI.js} +1 -1
  53. package/page/index.html +17 -17
  54. package/types.d.ts +10 -0
  55. package/ui/profile-editor.js +4 -4
  56. package/ui/studio-map.js +4 -13
  57. package/ui/studio-screen.js +20 -7
  58. package/page/assets/TraceInspector-BR3SDDuV.js +0 -1
  59. package/page/assets/TraceOverview-bvtLAnsR.js +0 -57
  60. package/page/assets/browser-connection-CA_G_F8Q.js +0 -1
  61. package/page/assets/browser-engine-DctWhKjF.js +0 -16
  62. package/page/assets/browser-transport-DVnbvtNO.js +0 -2
  63. package/page/assets/compile-CYYqzzo2.js +0 -2
  64. package/page/assets/reader-DhyhAoss.js +0 -5
  65. package/page/assets/registry-CtZn4S17.js +0 -1
  66. package/page/assets/shaped-data-CtJtZSw9.js +0 -21
  67. package/page/assets/studio-map-CpYHfNRm.js +0 -1
  68. package/page/assets/studio-trace-replay-B0O6qFwD.js +0 -3
  69. package/page/assets/tool-schema-hDeCZqPI.js +0 -17
  70. package/page/assets/trace-record-C-Opk3HK.js +0 -1
  71. package/page/assets/tree-Bo29WGA0.js +0 -3
@@ -4363,13 +4363,26 @@ export { bundledEgressAutomata, compileDetect, compileDetectTables, compiledDete
4363
4363
  type HostPattern = {
4364
4364
  /** What a match is called in the trace. */
4365
4365
  name: string;
4366
- /** The source of a regular expression. */
4366
+ /**
4367
+ * The source of a regular expression. A pattern takes this or words.
4368
+ *
4369
+ * @remarks The source of a regular expression.
4370
+ */
4367
4371
  pattern: string;
4368
- /** Any of \`i\`, \`m\`, \`s\`, and \`u\`. Every match is found, so \`g\` is implied; \`y\` is refused. */
4372
+ /**
4373
+ * Regular-expression flags, each a letter: i ignores case, m matches ^ and $ at each line, s
4374
+ * lets . match a line break, u reads Unicode. Not g or y: every match is always found.
4375
+ *
4376
+ * @remarks Any of \`i\`, \`m\`, \`s\`, and \`u\`. Every match is found, so \`g\` is implied; \`y\` is
4377
+ * refused.
4378
+ */
4369
4379
  flags?: string;
4370
4380
  } | {
4371
4381
  /** What a match is called in the trace. */
4372
4382
  name: string;
4383
+ /**
4384
+ * Words to match whole, whatever their case. A space in one matches any run of whitespace.
4385
+ */
4373
4386
  words: readonly string[];
4374
4387
  };
4375
4388
  /**
@@ -4463,45 +4476,90 @@ declare const DETECT_ACTIONS: readonly ["ignore", "flag", "redact", "block"];
4463
4476
  type DetectAction = (typeof DETECT_ACTIONS)[number];
4464
4477
  /** The addresses \`ungiven_images\` or \`ungiven_links\` lets through beyond the ones the model was given. */
4465
4478
  interface UrlAllow {
4466
- /** Hostnames let through whatever their URL, such as the host's own CDN. */
4479
+ /**
4480
+ * Hostnames whose images load whatever their URL, such as your own CDN.
4481
+ *
4482
+ * @catalog guardrails.detect.ungiven_links.allow.hosts Hostnames whose links pass whatever their
4483
+ * URL; the hosts ungiven_images allows pass too.
4484
+ *
4485
+ * @remarks Hostnames let through whatever their URL, such as the host's own CDN.
4486
+ */
4467
4487
  hosts?: readonly string[];
4468
4488
  /**
4469
- * Whether a URL a tool returned counts as given. Default true. A tool result can offer the
4470
- * model URLs to pick from, and the pick tells their server something; false closes that
4489
+ * Whether a URL a tool returned counts as given. Off keeps only what the system prompt, the user,
4490
+ * and history gave.
4491
+ *
4492
+ * @remarks Whether a URL a tool returned counts as given. Default true. A tool result can offer
4493
+ * the model URLs to pick from, and the pick tells their server something; false closes that
4471
4494
  * channel, and keeps only what the system prompt, the user, and host history gave.
4472
4495
  */
4473
4496
  fromTools?: boolean;
4474
4497
  }
4475
4498
  /** The names \`tool_leak\` lets through. */
4476
4499
  interface NameAllow {
4477
- /** Names of tools or parameters that are innocent in a reply, such as a tool called \`search\`. */
4500
+ /**
4501
+ * Names of tools or parameters that are not read for, such as a tool called search.
4502
+ *
4503
+ * @remarks Names of tools or parameters that are innocent in a reply, such as a tool called
4504
+ * \`search\`.
4505
+ */
4478
4506
  names?: readonly string[];
4479
4507
  }
4480
4508
  /** A detector's setting in full. */
4481
4509
  interface DetectorConfig {
4482
- /** The action at every boundary. Left out, each boundary keeps its default. */
4510
+ /**
4511
+ * What a match of this detector does at every boundary it reads, unless \`at\` names that boundary.
4512
+ *
4513
+ * @remarks The action at every boundary. Left out, each boundary keeps its default.
4514
+ */
4483
4515
  action?: DetectAction;
4484
- /** An action for the boundaries it names, over \`action\` or the default. */
4516
+ /**
4517
+ * An action per boundary, over action or the default.
4518
+ *
4519
+ * @remarks An action for the boundaries it names, over \`action\` or the default.
4520
+ */
4485
4521
  at?: Partial<Record<Boundary, DetectAction>>;
4486
4522
  /**
4487
- * Whether Theorem's own patterns run. Default true. With \`patterns\` it gives the four choices:
4488
- * both, only Theorem's, only the host's (\`false\` with patterns), or none (\`false\` without).
4489
- * A detector that takes no patterns refuses it.
4523
+ * Whether Theorem’s own patterns run. Off with no patterns of your own turns the detector off.
4524
+ *
4525
+ * @remarks Whether Theorem's own patterns run. Default true. With \`patterns\` it gives the four
4526
+ * choices: both, only Theorem's, only the host's (\`false\` with patterns), or none (\`false\`
4527
+ * without). A detector that takes no patterns refuses it.
4490
4528
  */
4491
4529
  theorem?: boolean;
4492
- /** The host's own patterns, read on the text as written. A detector that takes no patterns refuses them. */
4530
+ /**
4531
+ * Your own patterns, each a name and a regular expression or a list of words. A match takes this
4532
+ * detector’s action.
4533
+ *
4534
+ * @remarks The host's own patterns, read on the text as written. A detector that takes no
4535
+ * patterns refuses them.
4536
+ */
4493
4537
  patterns?: readonly HostPattern[];
4494
- /** The table compiled for \`patterns\` (\`compilePatterns\`, \`agents detect-compile\`). Patterns need it. */
4538
+ /**
4539
+ * The table your patterns compile to, from compileDetect or \`agents detect-compile\`. Needed
4540
+ * whenever patterns is set.
4541
+ *
4542
+ * @remarks The table compiled for \`patterns\` (\`compilePatterns\`, \`agents detect-compile\`).
4543
+ * Patterns need it.
4544
+ */
4495
4545
  compiled?: CompiledPatterns;
4496
4546
  /**
4497
4547
  * One line telling the model what to leave out, sent when this detector blocks a reply that is
4498
- * then retried. Left out, the labels' \`detect.hint.<detector>\`. Only beside \`patterns\`: the
4499
- * labels' hint describes Theorem's patterns, not the host's.
4548
+ * then retried. Set it beside patterns of your own.
4549
+ *
4550
+ * @remarks One line telling the model what to leave out, sent when this detector blocks a reply
4551
+ * that is then retried. Left out, the labels' \`detect.hint.<detector>\`. Only beside \`patterns\`:
4552
+ * the labels' hint describes Theorem's patterns, not the host's.
4500
4553
  */
4501
4554
  hint?: string;
4502
4555
  /**
4503
- * What the detector lets through: for \`ungiven_images\` and \`ungiven_links\` the addresses besides
4504
- * the given ones, for \`tool_leak\` the names that are innocent. Any other detector refuses it.
4556
+ * What passes besides the URLs the model was given this turn.
4557
+ *
4558
+ * @catalog guardrails.detect.tool_leak.allow The names that are innocent in a reply.
4559
+ *
4560
+ * @remarks What the detector lets through: for \`ungiven_images\` and \`ungiven_links\` the addresses
4561
+ * besides the given ones, for \`tool_leak\` the names that are innocent. Any other detector refuses
4562
+ * it.
4505
4563
  */
4506
4564
  allow?: UrlAllow | NameAllow;
4507
4565
  }
@@ -4530,23 +4588,48 @@ type HostFind = (text: string, context: {
4530
4588
  interface HostDetectorConfig {
4531
4589
  /** What an editor and the trace call it. */
4532
4590
  label: string;
4533
- /** The action at every boundary. Left out, only the boundaries \`at\` names are read. */
4591
+ /**
4592
+ * What a match does, at every boundary.
4593
+ *
4594
+ * @remarks The action at every boundary. Left out, only the boundaries \`at\` names are read.
4595
+ */
4534
4596
  action?: DetectAction;
4535
- /** An action for the boundaries it names, over \`action\`. */
4597
+ /**
4598
+ * An action per boundary, over action.
4599
+ *
4600
+ * @remarks An action for the boundaries it names, over \`action\`.
4601
+ */
4536
4602
  at?: Partial<Record<Boundary, DetectAction>>;
4537
- /** Its patterns, read on the text as written. */
4603
+ /**
4604
+ * Its patterns, each a name and a regular expression or a list of words, read on the text as
4605
+ * written.
4606
+ *
4607
+ * @remarks Its patterns, read on the text as written.
4608
+ */
4538
4609
  patterns?: readonly HostPattern[];
4539
- /** The table compiled for \`patterns\` (\`compilePatterns\`, \`agents detect-compile\`). Patterns need it. */
4610
+ /**
4611
+ * The table your patterns compile to, from compileDetect or \`agents detect-compile\`. Needed
4612
+ * whenever patterns is set.
4613
+ *
4614
+ * @remarks The table compiled for \`patterns\` (\`compilePatterns\`, \`agents detect-compile\`).
4615
+ * Patterns need it.
4616
+ */
4540
4617
  compiled?: CompiledPatterns;
4541
4618
  /**
4542
- * Its own reading. As a reply streams, a \`find\` reads the text held so far, and the last
4619
+ * Its own reading, for what patterns cannot say: a function that returns where the matches start
4620
+ * and end. It runs on every text crossing a boundary the detector reads, so it returns at once.
4621
+ *
4622
+ * @remarks Its own reading. As a reply streams, a \`find\` reads the text held so far, and the last
4543
4623
  * \`HOST_FIND_HOLD\` characters stay held (\`HOST_FIND_HOLD_LIVE\` in a Live reply): a match is
4544
4624
  * caught whole when it is no longer than that.
4545
4625
  */
4546
4626
  find?: HostFind;
4547
4627
  /**
4548
4628
  * One line telling the model what to leave out, sent when this detector blocks a reply that is
4549
- * then retried. Left out, the labels' \`detect.hint.own\`, which names the label.
4629
+ * then retried.
4630
+ *
4631
+ * @remarks One line telling the model what to leave out, sent when this detector blocks a reply
4632
+ * that is then retried. Left out, the labels' \`detect.hint.own\`, which names the label.
4550
4633
  */
4551
4634
  hint?: string;
4552
4635
  }
@@ -4896,7 +4979,11 @@ export interface ProviderDefinition<C = unknown, K = unknown> {
4896
4979
  }
4897
4980
  /** A provider as defined; register it to use it. */
4898
4981
  export type Provider<C = unknown, K = unknown> = Readonly<ProviderDefinition<C, K>>;
4899
- /** Defines a provider. Nothing in it can change a request or read a reply. */
4982
+ /**
4983
+ * Validates a provider definition and supplies its typed model helper.
4984
+ *
4985
+ * @remarks Defines a provider. Nothing in it can change a request or read a reply.
4986
+ */
4900
4987
  export declare function defineProvider<C = undefined, K = undefined>(definition: ProviderDefinition<C, K>): Provider<C, K>;
4901
4988
  /** What a builder sets when registering a provider. */
4902
4989
  export interface Registration<C> {
@@ -5205,14 +5292,23 @@ export declare function carriesTo(writer: string, target: Pick<Protocol, 'lineag
5205
5292
  `,"file:///node_modules/@theoremjs/agents/src/kernel/protocols/limits.d.ts":`import { z } from 'zod';
5206
5293
  /** The budgets a provider call runs under. Each one left out is no limit: the provider's own applies. */
5207
5294
  export interface ProviderLimits {
5295
+ /** How long one call may take, in milliseconds, retries included. */
5208
5296
  operationTimeoutMs?: number;
5297
+ /** How long a live session may take to open, in milliseconds. */
5209
5298
  connectTimeoutMs?: number;
5299
+ /** How long a live session may wait for the model to answer, in milliseconds. */
5210
5300
  liveStepTimeoutMs?: number;
5301
+ /** The most bytes in one record the provider sends: a stream event or a socket message. */
5211
5302
  maxWireRecordBytes?: number;
5303
+ /** The most bytes the provider sends for one step. */
5212
5304
  maxWireResponseBytes?: number;
5305
+ /** The most bytes in one event of a step. */
5213
5306
  maxEventBytes?: number;
5307
+ /** The most bytes in all the events of one step. */
5214
5308
  maxStepBytes?: number;
5309
+ /** The most events in one step. */
5215
5310
  maxStepEvents?: number;
5311
+ /** The most tool calls one step may ask for. */
5216
5312
  maxPendingToolCalls?: number;
5217
5313
  }
5218
5314
  export declare const providerLimitsSchema: z.ZodType<ProviderLimits>;
@@ -5252,16 +5348,43 @@ export type ProfileId = string;
5252
5348
  export type ChatRole = 'system' | 'user' | 'assistant';
5253
5349
  /** Host strings (presets own the vocabularies); an unpinned value is the provider default. */
5254
5350
  export interface ProfileImageSpec {
5351
+ /** The shape of generated images, such as 16:9. */
5255
5352
  aspectRatio?: string;
5353
+ /** How detailed generated images are, such as 1K, 2K or 4K. */
5256
5354
  resolution?: string;
5355
+ /**
5356
+ * The file type of generated images; a provider that takes a fixed set of types may use png for
5357
+ * any other.
5358
+ */
5257
5359
  mimeType?: string;
5360
+ /**
5361
+ * How much effort the model spends on each image: auto, low, medium, or high. A provider that has
5362
+ * no such setting refuses it.
5363
+ */
5258
5364
  quality?: string;
5365
+ /**
5366
+ * The background of generated images: auto, transparent, or opaque. A provider that has no such
5367
+ * setting refuses it.
5368
+ */
5259
5369
  background?: string;
5370
+ /** How many images one request makes, where the provider takes a count. */
5260
5371
  n?: number;
5372
+ /** A seed for repeatable images, where the provider and the model honour it. */
5261
5373
  seed?: number;
5374
+ /** Compression from 0 to 100 for jpeg and webp images, where the provider takes it. */
5262
5375
  outputCompression?: number;
5376
+ /**
5377
+ * Images sent with every turn, before the user's. Each is bytes (\`data\`) or a link (\`uri\`). Some
5378
+ * providers take http(s) links only, and none with includeText.
5379
+ */
5263
5380
  references?: Array<TurnBlob | TurnMediaRef>;
5264
- /** Also request interleaved text with the images (Google: text + image \`response_format\`). */
5381
+ /**
5382
+ * Whether the model may write text alongside its images; with some providers this also sends the
5383
+ * system instruction and history.
5384
+ *
5385
+ * @remarks Also request interleaved text with the images (Google: text + image
5386
+ * \`response_format\`).
5387
+ */
5265
5388
  includeText?: boolean;
5266
5389
  }
5267
5390
  import type { DecisionModelBinding, ModelBinding } from './protocols/binding.js';
@@ -5290,60 +5413,110 @@ export interface CompactionTriggerContext {
5290
5413
  /** When history compacts and how: the meter, the token budget, and the compactor. */
5291
5414
  export interface CompactionSpec {
5292
5415
  /**
5293
- * Token budget compared by the trigger (\`compactAt * maxTokens\`).
5294
- * Meaning depends on \`meter\`: history budget vs full-prompt input budget.
5416
+ * The token budget compactAt is a fraction of.
5417
+ *
5418
+ * @remarks Token budget compared by the trigger (\`compactAt * maxTokens\`). Meaning depends on
5419
+ * \`meter\`: history budget vs full-prompt input budget.
5295
5420
  */
5296
5421
  maxTokens: number;
5297
- /** Fraction of \`maxTokens\` at which compaction fires. Must be in (0, 1). */
5422
+ /**
5423
+ * The fraction of maxTokens, between 0 and 1, at which compaction starts, unless trigger decides.
5424
+ *
5425
+ * @remarks Fraction of \`maxTokens\` at which compaction fires. Must be in (0, 1).
5426
+ */
5298
5427
  compactAt: number;
5299
5428
  /**
5300
- * Recent exchanges kept verbatim (an exchange is a user message and everything up to the
5429
+ * How much recent history compaction keeps: a number of exchanges (1 or more), a fraction of
5430
+ * maxTokens below compactAt, or 0 to compact it all.
5431
+ *
5432
+ * @remarks Recent exchanges kept verbatim (an exchange is a user message and everything up to the
5301
5433
  * next one). \`≥ 1\` = exchange count, \`(0, 1)\` = fraction of \`maxTokens\`, \`0\` = compact all.
5302
5434
  */
5303
5435
  previousExchanges: number;
5304
5436
  /**
5305
- * Profile id of the compaction agent. Must be registered before the owning profile.
5306
- * Omit it and the agent compacts its own history: the same instructions and model, no tools.
5437
+ * The text profile that writes the summary; register it before this one. Leave it out and a text
5438
+ * agent summarises its own history, with its own instructions and model and no tools. Its
5439
+ * registered model binding selects the provider independently of the calling agent.
5440
+ *
5441
+ * @remarks Profile id of the compaction agent. Must be registered before the owning profile. Omit
5442
+ * it and the agent compacts its own history: the same instructions and model, no tools.
5307
5443
  */
5308
5444
  profile?: ProfileId;
5309
5445
  /**
5310
- * When compaction runs relative to the primary turn.
5446
+ * Whether the kernel compacts before the turn or tells the host to compact after it.
5447
+ *
5448
+ * @remarks When compaction runs relative to the primary turn.
5311
5449
  * - \`'before'\`: kernel compacts synchronously before the turn; user pays latency on this turn.
5312
5450
  * - \`'after'\`: kernel signals in the \`done\` event; host runs compaction asynchronously.
5313
5451
  */
5314
5452
  timing: CompactionTiming;
5315
5453
  /**
5316
- * Threshold meter. Defaults to \`'history'\`.
5317
- * Use \`'input'\` when the host prefers provider full-prompt usage (after
5318
- * subtracting a known baseline in \`maxTokens\` / \`compactAt\`).
5454
+ * What the threshold counts.
5455
+ *
5456
+ * @remarks Threshold meter. Defaults to \`'history'\`. Use \`'input'\` when the host prefers provider
5457
+ * full-prompt usage (after subtracting a known baseline in \`maxTokens\` / \`compactAt\`).
5319
5458
  */
5320
5459
  meter?: CompactionMeter;
5321
- /** Replaces the default \`tokens > compactAt * maxTokens\` check. */
5460
+ /**
5461
+ * Your function that decides when to compact, in place of compactAt and maxTokens.
5462
+ *
5463
+ * @remarks Replaces the default \`tokens > compactAt * maxTokens\` check.
5464
+ */
5322
5465
  trigger?: (ctx: CompactionTriggerContext) => boolean | Promise<boolean>;
5323
5466
  }
5324
5467
  /** What every request that runs a model takes: how to stop it, and where its trace goes. */
5325
5468
  export interface RunControls {
5326
- /** Stops the run when it aborts, and cancels in-flight provider HTTP where the adapter supports it. */
5469
+ /**
5470
+ * Stops the run when it aborts, and cancels its provider call where the provider can.
5471
+ *
5472
+ * @remarks Stops the run when it aborts, and cancels in-flight provider HTTP where the adapter
5473
+ * supports it.
5474
+ */
5327
5475
  signal?: AbortSignal;
5328
- /** Host-owned metadata preserved on the run's trace records; the kernel does not interpret it. */
5476
+ /**
5477
+ * Your own values, kept on the trace; Theorem does not read them.
5478
+ *
5479
+ * @remarks Host-owned metadata preserved on the run's trace records; the kernel does not
5480
+ * interpret it.
5481
+ */
5329
5482
  metadata?: Record<string, unknown>;
5330
5483
  /**
5331
- * W3C \`traceparent\` of the host span this run goes under. The run's root span joins that trace
5332
- * as its child; without it the run starts a new trace. A malformed value throws.
5484
+ * The W3C traceparent of your span; the run's trace joins it as a child.
5485
+ *
5486
+ * @remarks W3C \`traceparent\` of the host span this run goes under. The run's root span joins that
5487
+ * trace as its child; without it the run starts a new trace. A malformed value throws.
5333
5488
  */
5334
5489
  traceparent?: string;
5335
5490
  /** Your project id, recorded on the trace. */
5336
5491
  projectId?: string;
5337
- /** Host conversation id, recorded as \`gen_ai.conversation.id\`. */
5492
+ /**
5493
+ * Your conversation id, recorded on the trace.
5494
+ *
5495
+ * @remarks Host conversation id, recorded as \`gen_ai.conversation.id\`.
5496
+ */
5338
5497
  conversationId?: string;
5339
- /** Earlier traces this run follows. */
5498
+ /**
5499
+ * Earlier traces this run follows: a resume, a continue, or a retry.
5500
+ *
5501
+ * @remarks Earlier traces this run follows.
5502
+ */
5340
5503
  links?: TurnTraceLink[];
5341
5504
  }
5342
5505
  /** Which of the profile's models a run uses, and how hard it thinks. */
5343
5506
  export interface ModelChoice {
5344
- /** Selected model id when \`profile.allowModelSelect\` is true. */
5507
+ /**
5508
+ * The model id the turn or session picks from the profile's models; refused unless the profile
5509
+ * sets allowModelSelect.
5510
+ *
5511
+ * @remarks Selected model id when \`profile.allowModelSelect\` is true.
5512
+ */
5345
5513
  model?: ModelId;
5346
- /** Selected effort alias when the binding has \`allowEffortSelect\`. */
5514
+ /**
5515
+ * The effort the turn or session picks from the model's efforts; refused unless the model sets
5516
+ * allowEffortSelect.
5517
+ *
5518
+ * @remarks Selected effort alias when the binding has \`allowEffortSelect\`.
5519
+ */
5347
5520
  effort?: string;
5348
5521
  }
5349
5522
  /** \`compactHistory\` input, for \`timing: 'after'\`: the host passes back what \`done.compaction\` carried. */
@@ -5358,6 +5531,7 @@ export interface CompactHistoryRequest extends RunControls {
5358
5531
  }
5359
5532
  /** A structured-output schema given inline. */
5360
5533
  export interface StructuredSpec {
5534
+ /** The JSON Schema a structured reply must follow, sent to the model as its response format. */
5361
5535
  jsonSchema: Record<string, unknown>;
5362
5536
  }
5363
5537
  /** Caps on the files a turn may attach. */
@@ -5434,39 +5608,90 @@ export type ProfileItemCheck = (item: unknown, turn: ItemCheckTurn) => Validatio
5434
5608
  * rewrite the refused items alone, then removes any that are refused again.
5435
5609
  */
5436
5610
  export interface ProfileItemRule {
5611
+ /**
5612
+ * Your check on one item, given what the tools of the turn returned (turn.toolResults); its error
5613
+ * is the reason the model reads on a rewrite and the host reads on the removed item.
5614
+ */
5437
5615
  check: ProfileItemCheck;
5616
+ /**
5617
+ * drop removes a refused item. fix first asks the model to rewrite the refused items alone, once
5618
+ * and while retries remain, then removes any refused again. Removed items leave on the structured
5619
+ * event as removed.
5620
+ */
5438
5621
  onFail: 'drop' | 'fix';
5439
5622
  }
5440
5623
  /** Host validators a profile runs on its structured output. */
5441
5624
  export interface ProfileValidationSpec {
5442
5625
  /**
5443
- * Host domain validators keyed by dotted paths into structured output
5444
- * (e.g. \`diagram.mermaid\`). Presence/required is owned by the JSON Schema;
5445
- * these run only for required paths and for optional paths that are present.
5626
+ * Your checks, each keyed by a dotted path into the structured reply, such as diagram.mermaid; a
5627
+ * path no structured schema reaches is refused when the profile registers.
5628
+ *
5629
+ * @remarks Host domain validators keyed by dotted paths into structured output (e.g.
5630
+ * \`diagram.mermaid\`). Presence/required is owned by the JSON Schema; these run only for required
5631
+ * paths and for optional paths that are present.
5632
+ *
5633
+ * @catalog outputs.validation.fields.* Your check on this part of the reply, reached through object properties only; a failure sends its error back to the model to rewrite while retries remain.
5446
5634
  */
5447
5635
  fields?: Record<string, ProfileValidator>;
5448
- /** Host checks on list items, keyed by the dotted path of a list in the structured output. */
5636
+ /**
5637
+ * Your checks on the items of a list, each keyed by the dotted path of that list in the
5638
+ * structured reply, such as claims; a path no structured schema reaches as a list is refused when
5639
+ * the profile registers.
5640
+ *
5641
+ * @remarks Host checks on list items, keyed by the dotted path of a list in the structured
5642
+ * output.
5643
+ *
5644
+ * @catalog outputs.validation.items.* Your check on each item of this list. A refused item never fails the reply and the rest of the reply is kept.
5645
+ */
5449
5646
  items?: Record<string, ProfileItemRule>;
5647
+ /**
5648
+ * How many times the model may rewrite a reply that fails your checks or the schema's required
5649
+ * keys before it goes out as it is; under sse, an attempt that gets rewritten has already
5650
+ * streamed. A rewrite of a blocked reply (guardrails.blockedReply) counts against this too.
5651
+ */
5450
5652
  maxRetries?: number;
5451
5653
  }
5452
5654
  /** \`voice\` is the TTS voice id, not ingress audio (\`inputs.voice\`). */
5453
5655
  export interface ProfileSpeechSpec {
5656
+ /**
5657
+ * The voice the speech is read in, by the provider's own name for it; a turn's speech.voice
5658
+ * replaces it.
5659
+ */
5454
5660
  voice?: string;
5455
- /** How the script is delivered, in plain words: pace, mood, accent. Never read aloud. */
5661
+ /**
5662
+ * How the script is delivered, in plain words (pace, mood, accent); it is never read aloud, and a
5663
+ * turn's speech.style replaces it. A model that takes no direction ignores it.
5664
+ *
5665
+ * @remarks How the script is delivered, in plain words: pace, mood, accent. Never read aloud.
5666
+ */
5456
5667
  style?: string;
5457
- /** The speaking rate; 1 is the voice's own pace. */
5668
+ /**
5669
+ * The speaking rate, where 1 is the voice's own pace; a turn's speech.speed replaces it. A
5670
+ * provider that has no rate refuses it or ignores it.
5671
+ *
5672
+ * @remarks The speaking rate; 1 is the voice's own pace.
5673
+ */
5458
5674
  speed?: number;
5459
- /** A provider that cannot make the format refuses the turn. */
5675
+ /**
5676
+ * The audio encoding each turn's speech comes back in, and so what the host plays or stores.
5677
+ *
5678
+ * @remarks A provider that cannot make the format refuses the turn.
5679
+ */
5460
5680
  format?: SpeechAudioFormat;
5461
5681
  }
5462
5682
  /** What one speech turn sets for itself; each field given replaces the profile's \`speech\` field of that name. */
5463
5683
  export type TurnSpeech = Pick<ProfileSpeechSpec, 'voice' | 'style' | 'speed'>;
5464
5684
  /** Voice activity detection settings for a live session. */
5465
5685
  export interface LiveVadSpec {
5686
+ /** Whether the user speaking interrupts the model's reply. */
5466
5687
  activityHandling?: LiveActivityHandling;
5688
+ /** How readily the session decides the user has started speaking. */
5467
5689
  startSensitivity?: LiveStartSensitivity;
5690
+ /** How readily the session decides the user has stopped speaking. */
5468
5691
  endSensitivity?: LiveEndSensitivity;
5692
+ /** How long speech must last, in milliseconds, before it counts as the user starting to speak. */
5469
5693
  prefixPaddingMs?: number;
5694
+ /** How long a silence, in milliseconds, ends the user's speech. */
5470
5695
  silenceDurationMs?: number;
5471
5696
  }
5472
5697
  /**
@@ -5476,25 +5701,37 @@ export interface LiveVadSpec {
5476
5701
  */
5477
5702
  export interface LiveContextCompressionSpec {
5478
5703
  /**
5479
- * Context tokens, counted before a turn, that start compression. A whole
5480
- * number above 0. Omit → provider default (Gemini: 80% of the model's context
5481
- * window).
5704
+ * The context size, in tokens, that starts trimming.
5705
+ *
5706
+ * @remarks Context tokens, counted before a turn, that start compression. A whole number above 0.
5707
+ * Omit → provider default (Gemini: 80% of the model's context window).
5482
5708
  */
5483
5709
  triggerTokens?: number;
5484
- /** Drops the oldest turns; the system instruction stays. Gemini's only mechanism. */
5710
+ /**
5711
+ * Trims by dropping the oldest turns; the system instruction stays.
5712
+ *
5713
+ * @remarks Drops the oldest turns; the system instruction stays. Gemini's only mechanism.
5714
+ */
5485
5715
  slidingWindow: LiveSlidingWindowSpec;
5486
5716
  }
5487
5717
  /** Sliding-window context compression for a live session. */
5488
5718
  export interface LiveSlidingWindowSpec {
5489
5719
  /**
5490
- * Tokens to keep after compressing. A whole number above 0, below
5491
- * \`triggerTokens\`. Omit → provider default (Gemini: half of \`triggerTokens\`).
5720
+ * The context size, in tokens, to trim down to; below the trigger.
5721
+ *
5722
+ * @remarks Tokens to keep after compressing. A whole number above 0, below \`triggerTokens\`. Omit
5723
+ * → provider default (Gemini: half of \`triggerTokens\`).
5492
5724
  */
5493
5725
  targetTokens?: number;
5494
5726
  }
5495
5727
  /** Which sides of a live session are transcribed. */
5496
5728
  export interface LiveTranscriptionSpec {
5729
+ /** Whether the user's speech is transcribed. */
5497
5730
  input?: boolean;
5731
+ /**
5732
+ * Whether the model's speech is transcribed; always on while a detector reads live_reply, since
5733
+ * it reads the transcript.
5734
+ */
5498
5735
  output?: boolean;
5499
5736
  }
5500
5737
  /**
@@ -5503,37 +5740,87 @@ export interface LiveTranscriptionSpec {
5503
5740
  * \`LiveSession.sendAudio\` / \`sendVideo\` / \`sendText\` channels.
5504
5741
  */
5505
5742
  export interface LiveIngressSpec {
5506
- /** Microphone PCM via \`sendAudio\`. Omit → enabled. */
5743
+ /**
5744
+ * Whether the session accepts microphone audio.
5745
+ *
5746
+ * @remarks Microphone PCM via \`sendAudio\`. Omit → enabled.
5747
+ */
5507
5748
  audio?: boolean;
5508
- /** Webcam JPEG frames via \`sendVideo\`. Omit → enabled. */
5749
+ /**
5750
+ * Whether the session accepts camera frames.
5751
+ *
5752
+ * @remarks Webcam JPEG frames via \`sendVideo\`. Omit → enabled.
5753
+ */
5509
5754
  video?: boolean;
5510
- /** Typed text via \`sendText\`. Omit → disabled (opt-in). */
5755
+ /**
5756
+ * Whether the session accepts typed text.
5757
+ *
5758
+ * @remarks Typed text via \`sendText\`. Omit → disabled (opt-in).
5759
+ */
5511
5760
  text?: boolean;
5512
5761
  }
5513
5762
  /** The prompt a resumed call opens with, and how long away earns it. */
5514
5763
  export interface LiveResumedSpec {
5764
+ /**
5765
+ * A prompt the call sends itself when it resumes, so the agent says it is back. The visitor does
5766
+ * not see it. It may use {name}, and is not sent when an option it prints is unset.
5767
+ */
5515
5768
  prompt: string;
5516
- /** The shortest time away, in milliseconds, the agent remarks on. Omit → \`DEFAULT_RESUMED_AFTER_MS\`. */
5769
+ /**
5770
+ * The shortest time away, in milliseconds, that earns the prompt; a shorter drop resumes
5771
+ * silently.
5772
+ *
5773
+ * @remarks The shortest time away, in milliseconds, the agent remarks on. Omit →
5774
+ * \`DEFAULT_RESUMED_AFTER_MS\`.
5775
+ */
5517
5776
  afterMs?: number;
5518
5777
  }
5519
5778
  /** The settings only a live profile has: ingress, voice, detection, windowing, transcription, and resumption. */
5520
5779
  export interface ProfileLiveSpec {
5780
+ /** Which channels the session accepts from the user. */
5521
5781
  ingress?: LiveIngressSpec;
5782
+ /** The voice the model speaks in. */
5522
5783
  voice?: string;
5784
+ /** How the session detects when the user starts and stops speaking. */
5523
5785
  vad?: LiveVadSpec;
5786
+ /**
5787
+ * Whether the provider sends resume handles, which the host can pass to a new session to carry
5788
+ * this one on.
5789
+ */
5524
5790
  sessionResumption?: boolean;
5525
- /** A prompt the session sends itself when a call opens new, so the agent speaks first. Omit → the agent waits. */
5791
+ /**
5792
+ * A prompt the call sends itself when it opens new, so the agent speaks first. The visitor does
5793
+ * not see it. It may use {name}, and is not sent when an option it prints is unset.
5794
+ *
5795
+ * @remarks A prompt the session sends itself when a call opens new, so the agent speaks first.
5796
+ * Omit → the agent waits.
5797
+ */
5526
5798
  greeting?: string;
5527
- /** What the agent is prompted with when a call resumes after the caller was away. Omit → a resumed call is silent. */
5799
+ /**
5800
+ * What happens when a call comes back after a drop. It needs live.sessionResumption.
5801
+ *
5802
+ * @remarks What the agent is prompted with when a call resumes after the caller was away. Omit →
5803
+ * a resumed call is silent.
5804
+ */
5528
5805
  resumed?: LiveResumedSpec;
5529
- /** Context window compression. Omit → none: the provider ends the session at its limit. */
5806
+ /**
5807
+ * Trims the session's context once it grows past the trigger.
5808
+ *
5809
+ * @remarks Context window compression. Omit → none: the provider ends the session at its limit.
5810
+ */
5530
5811
  contextCompression?: LiveContextCompressionSpec;
5812
+ /** Text transcripts of the session's speech. */
5531
5813
  transcription?: LiveTranscriptionSpec;
5532
5814
  }
5533
5815
  /** How a profile's reply streams. */
5534
5816
  export interface ProfileStreamingSpec {
5817
+ /** Whether the reply reaches the host as the model writes it, or whole. */
5535
5818
  mode?: StreamMode;
5536
- /** When false, filter \`thought\` events from the turn stream. */
5819
+ /**
5820
+ * Whether the model's thinking reaches the host.
5821
+ *
5822
+ * @remarks When false, filter \`thought\` events from the turn stream.
5823
+ */
5537
5824
  streamThoughts?: boolean;
5538
5825
  }
5539
5826
  export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
@@ -5557,46 +5844,105 @@ export interface ProfileModelFields {
5557
5844
  }
5558
5845
  /** One value an option can take. \`description\` is what a picker shows beside it. */
5559
5846
  export interface OptionChoice {
5847
+ /**
5848
+ * The value the code sets, which \`when\` reads and {name} prints.
5849
+ *
5850
+ * @catalog inputs.options.*.choices.*.value The value the turn sends for this choice, which
5851
+ * \`when\` reads and {name} prints.
5852
+ */
5560
5853
  value: string;
5854
+ /**
5855
+ * What this value means. It is never sent to the model.
5856
+ *
5857
+ * @catalog inputs.options.*.choices.*.description Visitor-facing blurb for this choice in the
5858
+ * composer. Never substituted into prompts.
5859
+ */
5561
5860
  description?: string;
5562
5861
  }
5563
5862
  /** One named option: its \`label\` for a picker, and the values it can take. */
5564
5863
  export interface OptionDecl {
5864
+ /**
5865
+ * A person-readable title. Omit to show the option's name.
5866
+ *
5867
+ * @catalog inputs.options.*.label Visitor-facing title for this option in the composer (for
5868
+ * example Source Bias). Omit to show the option's name.
5869
+ */
5565
5870
  label?: string;
5871
+ /**
5872
+ * The values this option can take.
5873
+ *
5874
+ * @catalog inputs.options.*.choices The values this option can take, each with an optional UI
5875
+ * description.
5876
+ */
5566
5877
  choices: OptionChoice[];
5567
5878
  }
5568
5879
  /** A profile's options by name. Which object holds them says who drives them. */
5569
5880
  export type ProfileOptions = Readonly<Record<string, OptionDecl>>;
5570
5881
  /** What a profile accepts as input. */
5571
5882
  export interface ProfileInputsSpec {
5883
+ /** Whether a turn may send text. */
5572
5884
  text?: boolean;
5885
+ /** Lets turns send files. */
5573
5886
  attachments?: {
5887
+ /**
5888
+ * The file types a turn may send, where type/* matches a whole family; image profiles take only
5889
+ * images, video, and PDF.
5890
+ */
5574
5891
  accept: string[];
5575
5892
  };
5893
+ /** Lets turns send voice clips. A transcription profile must set it. */
5576
5894
  voice?: {
5577
- accept: string[];
5895
+ /** The audio types a voice clip may be; audio/* matches them all. */ accept: string[];
5578
5896
  };
5897
+ /** The most files and voice clips one turn or embedding request may send, counted together. */
5579
5898
  maxFiles?: number;
5899
+ /** The largest file or clip, in bytes, a turn or embedding request may send inline. */
5580
5900
  maxBytes?: number;
5901
+ /**
5902
+ * The most bytes one turn or embedding request may send inline across all its files and clips.
5903
+ */
5581
5904
  maxTurnBytes?: number;
5905
+ /**
5906
+ * Size limits by file type that replace maxBytes for those types.
5907
+ *
5908
+ * @catalog inputs.limitsByMime.* The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.
5909
+ */
5582
5910
  limitsByMime?: Record<string, number>;
5583
- /** The options a person picks: a host shows each one as a picker. */
5911
+ /**
5912
+ * The options a person picks, each shown as a picker. A prompt reads one as "when reader is
5913
+ * student: …" and prints it as {reader}.
5914
+ *
5915
+ * @remarks The options a person picks: a host shows each one as a picker.
5916
+ * @catalog inputs.options.* { label?, choices: { value, description? }[] }. Value is what the turn sends and what {name} prints.
5917
+ */
5584
5918
  options?: ProfileOptions;
5919
+ /**
5920
+ * Lets the page or the host send the agent one package of things to know, read at the context
5921
+ * boundary.
5922
+ */
5585
5923
  context?: ProfileContextSpec;
5586
5924
  }
5587
5925
  /** What a live profile declares beside its ingress channels. */
5588
5926
  export type LiveInputsSpec = Pick<ProfileInputsSpec, 'options' | 'context'>;
5589
5927
  /** Who may send a turn its context, and how much. */
5590
5928
  export interface ProfileContextSpec {
5929
+ /** Who may send context; context from anyone else is refused. */
5591
5930
  from: ContextSender[];
5931
+ /** The longest package, in characters of its JSON, each sender may send. */
5592
5932
  maxChars: number;
5593
5933
  }
5594
5934
  /** The context each sender gives a turn: any JSON, or text. */
5595
5935
  export type TurnContext = Partial<Record<ContextSender, unknown>>;
5596
5936
  /** What a profile returns: its structured schema, validation, and streaming. */
5597
5937
  export interface ProfileOutputsSpec {
5938
+ /**
5939
+ * The registered JSON schema the reply must follow, which can vary by option; register it before
5940
+ * the profile.
5941
+ */
5598
5942
  structured?: StructuredSchemaId | StructuredByOption | null;
5943
+ /** Your checks on a structured reply, and how many rewrites a failure gets. */
5599
5944
  validation?: ProfileValidationSpec;
5945
+ /** How the reply reaches the host, and whether its thinking does. */
5600
5946
  streaming?: ProfileStreamingSpec;
5601
5947
  }
5602
5948
  /** Text a reply may not repeat when the rest of its prompt is marked shareable. */
@@ -5622,9 +5968,26 @@ export interface SystemPiece {
5622
5968
  }
5623
5969
  /** A profile's handle and system prompt. */
5624
5970
  export interface ProfileIdentity {
5971
+ /**
5972
+ * The name hosts and users see for this agent, at most 32 characters; the model never sees it.
5973
+ */
5625
5974
  handle: string;
5626
- /** The options the host's code states. A person never sees them. */
5975
+ /**
5976
+ * The options the host's code sets on runTurn, which a person never sees. A line of
5977
+ * identity.system reads one as "when plan is free: …" and prints it as {plan}. One named path
5978
+ * holds the turn's path.
5979
+ *
5980
+ * @remarks The options the host's code states. A person never sees them.
5981
+ * @catalog identity.options.* { label?, choices: { value, description? }[] }, the same shape as inputs.options.*.
5982
+ */
5627
5983
  options?: ProfileOptions;
5984
+ /**
5985
+ * The instruction the model gets, as one string or a list of lines; some providers send it for an
5986
+ * image profile only with includeText on. A line that opens "when plan is free: …" goes only on
5987
+ * turns where that fits, and every line that fits is sent, a blank line apart. A line can be a
5988
+ * list of parts; mark what must not leak as { private: text }; only that is guarded. With none,
5989
+ * the whole prompt is.
5990
+ */
5628
5991
  system?: ProfileSystem;
5629
5992
  }
5630
5993
  /** The fields every profile type shares. */
@@ -5648,7 +6011,12 @@ export type DecisionJson = null | string | number | boolean | DecisionJson[] | {
5648
6011
  };
5649
6012
  /** What a decision profile accepts: JSON state up to a byte cap. */
5650
6013
  export interface DecisionInputsSpec {
6014
+ /** A decision reads JSON state, passed on each call. */
5651
6015
  state: 'json';
6016
+ /**
6017
+ * The largest state, in bytes, a decision call may send; larger state is refused before it leaves
6018
+ * your process.
6019
+ */
5652
6020
  maxStateBytes?: number;
5653
6021
  }
5654
6022
  /**
@@ -5666,6 +6034,10 @@ export interface DecisionProfile {
5666
6034
  models: Record<ModelId, DecisionModelBinding>;
5667
6035
  inputs: DecisionInputsSpec;
5668
6036
  decision: {
6037
+ /**
6038
+ * Your name for this decision, on its traces. Not sent to the model. Not checked against the
6039
+ * questions.
6040
+ */
5669
6041
  contract: DecisionContractId;
5670
6042
  };
5671
6043
  guardrails?: DecisionGuardrailsSpec;
@@ -5783,13 +6155,29 @@ export type EmbeddingInput = string | {
5783
6155
  };
5784
6156
  /** A profile's accepted embedding input kinds and limits. */
5785
6157
  export interface EmbeddingInputsSpec {
6158
+ /** Whether a turn may send text. */
5786
6159
  text?: boolean;
6160
+ /** Lets turns send files. */
5787
6161
  attachments?: {
6162
+ /**
6163
+ * The file types a turn may send, where type/* matches a whole family; image profiles take only
6164
+ * images, video, and PDF.
6165
+ */
5788
6166
  accept: string[];
5789
6167
  };
6168
+ /** The most files and voice clips one turn or embedding request may send, counted together. */
5790
6169
  maxFiles?: number;
6170
+ /** The largest file or clip, in bytes, a turn or embedding request may send inline. */
5791
6171
  maxBytes?: number;
6172
+ /**
6173
+ * The most bytes one turn or embedding request may send inline across all its files and clips.
6174
+ */
5792
6175
  maxTurnBytes?: number;
6176
+ /**
6177
+ * Size limits by file type that replace maxBytes for those types.
6178
+ *
6179
+ * @catalog inputs.limitsByMime.* The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.
6180
+ */
5793
6181
  limitsByMime?: Record<string, number>;
5794
6182
  }
5795
6183
  /** A profile that returns vectors instead of a model turn. */
@@ -5942,26 +6330,57 @@ export interface TurnRepairRequest {
5942
6330
  }
5943
6331
  /** What the user sent for a turn: text, options, attachments, voice, and history. */
5944
6332
  export interface TurnInput {
6333
+ /** The user's message. */
5945
6334
  text?: string;
5946
- /** The value picked for each of the profile's \`inputs.options\`. */
6335
+ /**
6336
+ * The value a person picked for each option in the profile's inputs.options; an option or a value
6337
+ * the profile does not declare is refused.
6338
+ *
6339
+ * @remarks The value picked for each of the profile's \`inputs.options\`.
6340
+ */
5947
6341
  options?: Readonly<Record<string, string>>;
5948
- /** What the page or the host wants the model to know, by sender; the profile's \`inputs.context\` allows it. */
6342
+ /**
6343
+ * What the page (client) or the host (server) wants the model to know, as any JSON or text; a
6344
+ * sender the profile's inputs.context does not list, or a package over its maxChars, is refused.
6345
+ *
6346
+ * @remarks What the page or the host wants the model to know, by sender; the profile's
6347
+ * \`inputs.context\` allows it.
6348
+ */
5949
6349
  context?: TurnContext;
6350
+ /**
6351
+ * Files sent with the turn, as bytes or as a provider file reference; each must pass the
6352
+ * profile's inputs.attachments.
6353
+ */
5950
6354
  attachments?: Array<TurnBlob | TurnMediaRef>;
6355
+ /** Recorded speech sent with the turn; each must pass the profile's inputs.voice. */
5951
6356
  voice?: TurnBlob[];
6357
+ /** The earlier messages of the conversation, when the host keeps them. */
5952
6358
  history?: TurnHistoryMessage[];
5953
- /** Tool calls that settled after their turn, as the host stored them. Each counts as read in this reply. */
6359
+ /**
6360
+ * Background tool calls that settled after their turn, as the host stored them. The model reads
6361
+ * each as a tool result, and this reply counts it as a remote read when the call was remote. Pass
6362
+ * each one once: the turn emits it as a late_results event, so a history built from events holds
6363
+ * it.
6364
+ *
6365
+ * @remarks Tool calls that settled after their turn, as the host stored them. Each counts as read
6366
+ * in this reply.
6367
+ */
5954
6368
  lateResults?: ToolOperationOutcome[];
6369
+ /** A reply your host rejected and why, so that the model writes it again. */
5955
6370
  repair?: TurnRepairRequest;
5956
6371
  /**
5957
- * Optional host-supplied history token count for \`meter: 'history'\`.
5958
- * When set, overrides the local history estimate. Not full-prompt API tokens.
6372
+ * Your count of the history's tokens, used by compaction that meters history.
6373
+ *
6374
+ * @remarks Optional host-supplied history token count for \`meter: 'history'\`. When set, overrides
6375
+ * the local history estimate. Not full-prompt API tokens.
5959
6376
  */
5960
6377
  historyTokens?: number;
5961
6378
  /**
5962
- * Optional host-supplied full-prompt input token count for \`meter: 'input'\`
5963
- * with \`timing: 'before'\` (typically the previous turn's \`tokens.input\`).
5964
- * Ignored when \`meter\` is \`'history'\`.
6379
+ * Your count of the whole prompt's tokens, used by compaction that meters input before the call.
6380
+ *
6381
+ * @remarks Optional host-supplied full-prompt input token count for \`meter: 'input'\` with
6382
+ * \`timing: 'before'\` (typically the previous turn's \`tokens.input\`). Ignored when \`meter\` is
6383
+ * \`'history'\`.
5965
6384
  */
5966
6385
  inputTokens?: number;
5967
6386
  }
@@ -5983,94 +6402,164 @@ export interface TurnTraceLink {
5983
6402
  }
5984
6403
  /** What \`runTurn\` and \`runSession\` both take: an agent's profile, its model, and the host's hooks and keys. */
5985
6404
  export interface AgentRunRequest extends RunControls, ModelChoice {
6405
+ /** Host-owned atomic tool claims and outcomes. Never sent to providers. */
5986
6406
  execution?: ToolExecutionCoordinator;
6407
+ /**
6408
+ * Host-issued service for tool calls that go on after their reply. It needs a coordinator with
6409
+ * detach. Without it every tool runs inline.
6410
+ */
5987
6411
  background?: ToolBackgroundService;
6412
+ /** Host-issued browser dispatch with a claimed operation and correlated result. */
5988
6413
  pageExecution?: PageToolExecution;
6414
+ /** Native provider state saved alongside portable history. */
5989
6415
  providerState?: ProviderCheckpoint;
6416
+ /** The id of the registered profile the turn or session runs. */
5990
6417
  profile: ProfileId;
5991
6418
  /**
5992
- * Args for built-in tools on the chosen model's \`builtInTools\`, by tool id.
5993
- * Each is parsed by the schema the provider's adapter declares for that tool.
6419
+ * Args for the provider's own tools on the chosen model's builtInTools, by tool id; each is
6420
+ * checked by the schema the provider declares for that tool.
6421
+ *
6422
+ * @remarks Args for built-in tools on the chosen model's \`builtInTools\`, by tool id. Each is
6423
+ * parsed by the schema the provider's adapter declares for that tool.
5994
6424
  */
5995
6425
  builtInArgs?: BuiltInArgs;
5996
- /** Host-provided dynamic system prompt combined with profile persona */
6426
+ /**
6427
+ * An instruction for this request only, added to the profile's own.
6428
+ *
6429
+ * @remarks Host-provided dynamic system prompt combined with profile persona
6430
+ */
5997
6431
  system?: SystemPrompt;
6432
+ /** The tools the user has already approved for this session. */
5998
6433
  sessionPermissions?: string[];
5999
- /** Host channel/path for catalog \`paths\` filtering. */
6434
+ /**
6435
+ * The channel the turn or session comes from; only tools whose paths name it, or *, are offered.
6436
+ *
6437
+ * @remarks Host channel/path for catalog \`paths\` filtering.
6438
+ */
6000
6439
  path?: string;
6001
- /** This run's value for each of \`profile.identity.options\` it sets; \`path\` is the run's own. */
6440
+ /**
6441
+ * The value the host's code sets for each option in the profile's identity.options but path; an
6442
+ * option or a value the profile does not declare is refused.
6443
+ *
6444
+ * @remarks This run's value for each of \`profile.identity.options\` it sets; \`path\` is the run's
6445
+ * own.
6446
+ */
6002
6447
  options?: Readonly<Record<string, string>>;
6003
6448
  /**
6004
- * Opaque application context handed to tool \`handler\` / \`preTool\` and
6005
- * \`tools.t1Policy\` as \`ctx.host\`. The kernel never reads, logs, traces, or
6006
- * serializes it.
6449
+ * Your own context, handed to tool handlers as ctx.host; Theorem never reads or records it.
6450
+ *
6451
+ * @remarks Opaque application context handed to tool \`handler\` / \`preTool\` and \`tools.t1Policy\`
6452
+ * as \`ctx.host\`. The kernel never reads, logs, traces, or serializes it.
6007
6453
  */
6008
6454
  host?: unknown;
6009
- /** Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs one. */
6455
+ /**
6456
+ * Where an HTTP or MCP tool gets the credential for its auth slot.
6457
+ *
6458
+ * @remarks Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs
6459
+ * one.
6460
+ */
6010
6461
  credentials?: ToolCredentialSource;
6011
6462
  /**
6012
- * Resolves remote tool and OAuth host names before each request; a name that
6013
- * resolves to a private address is refused (see \`fetchGuarded\`).
6463
+ * Resolves the host name of a remote tool before each request; a name that resolves to a private
6464
+ * address is refused.
6465
+ *
6466
+ * @remarks Resolves remote tool and OAuth host names before each request; a name that resolves to
6467
+ * a private address is refused (see \`fetchGuarded\`).
6014
6468
  */
6015
6469
  resolveHost?: ResolveHost;
6016
6470
  /**
6017
- * Sends each request a remote tool makes (HTTP, MCP, a signed-in fetch, an image read), once
6018
- * that request's network checks pass. A page whose tools cannot reach a host directly sends them
6019
- * through its own server here. Default: the global \`fetch\`.
6471
+ * Sends each request a remote tool makes, once that request's network checks pass. A page whose
6472
+ * tools cannot reach a host directly sends them through its own server here.
6473
+ *
6474
+ * @remarks Sends each request a remote tool makes (HTTP, MCP, a signed-in fetch, an image read),
6475
+ * once that request's network checks pass. A page whose tools cannot reach a host directly sends
6476
+ * them through its own server here. Default: the global \`fetch\`.
6020
6477
  */
6021
6478
  fetch?: typeof fetch;
6022
- /** Text \`runTurn\` and \`runSession\` emit stages and apply the returned affordances. A session's is set once. */
6479
+ /**
6480
+ * Your function that sees each stage of a text turn or a live session, and can answer with what
6481
+ * the stage allows.
6482
+ *
6483
+ * @remarks Text \`runTurn\` and \`runSession\` emit stages and apply the returned affordances. A
6484
+ * session's is set once.
6485
+ */
6023
6486
  onStage?: StageHandler;
6024
6487
  /**
6025
- * Runs before each agent tool call in this run, and in the turns those
6026
- * calls run. Shape the called agent's request (history, model, provider) or
6027
- * refuse the call. Omit it: the agent runs on what the model sent.
6488
+ * Runs before each agent tool call, to shape the request to the called agent or to refuse the
6489
+ * call.
6490
+ *
6491
+ * @remarks Runs before each agent tool call in this run, and in the turns those calls run. Shape
6492
+ * the called agent's request (history, model, provider) or refuse the call. Omit it: the agent
6493
+ * runs on what the model sent.
6028
6494
  */
6029
6495
  onAgentCall?: AgentCallHook;
6030
6496
  }
6031
6497
  /** A request to \`runTurn\`: the shared controls and the turn's input. */
6032
6498
  export interface TurnRequest extends AgentRunRequest {
6033
6499
  /**
6034
- * Sticky routing / cache session key for OpenRouter (\`session_id\`).
6035
- * Not the same as \`projectId\` or Gemini \`previousInteractionId\`.
6500
+ * A session key that OpenRouter uses for routing and caching.
6501
+ *
6502
+ * @remarks Sticky routing / cache session key for OpenRouter (\`session_id\`). Not the same as
6503
+ * \`projectId\` or Gemini \`previousInteractionId\`.
6036
6504
  */
6037
6505
  sessionId?: string;
6038
- /** This turn's voice, style, and speed, over \`profile.speech\`. Speech profiles only. */
6506
+ /**
6507
+ * This turn's voice, style, and speed; each one given replaces the profile's speech field of that
6508
+ * name. Refused on a profile that is not speech.
6509
+ *
6510
+ * @remarks This turn's voice, style, and speed, over \`profile.speech\`. Speech profiles only.
6511
+ */
6039
6512
  speech?: TurnSpeech;
6040
6513
  /**
6041
- * Continue a prior resumeable stop. On text profiles the turn's user message
6042
- * is the continue instruction (no \`input.text\`); the host passes the partial
6043
- * reply as the last assistant message in \`input.history\`. Image and speech
6044
- * re-send the original request unchanged.
6514
+ * Continues a turn that stopped in a way the profile lets a turn continue.
6515
+ *
6516
+ * @remarks Continue a prior resumeable stop. On text profiles the turn's user message is the
6517
+ * continue instruction (no \`input.text\`); the host passes the partial reply as the last assistant
6518
+ * message in \`input.history\`. Image and speech re-send the original request unchanged.
6045
6519
  */
6046
6520
  continueFrom?: TurnContinueFrom;
6047
6521
  /**
6048
- * 1-based continue attempt when \`continueFrom\` is set.
6049
- * Compared to \`profile.turnBehaviour.resumption.maxContinues\` when that cap is set.
6522
+ * Which continue attempt this is, from 1; checked against the maxContinues of the profile.
6523
+ *
6524
+ * @remarks 1-based continue attempt when \`continueFrom\` is set. Compared to
6525
+ * \`profile.turnBehaviour.resumption.maxContinues\` when that cap is set.
6050
6526
  */
6051
6527
  continuation?: number;
6052
6528
  /**
6053
- * Tools this reply already had when an earlier run of it paused. The turn opens with them on its
6054
- * list, so an answered call does not take back what the model loaded. An id \`tools.allow\` or the
6055
- * path does not grant is left out, as for \`tools.t1Policy\`.
6529
+ * Tools this reply already had when an earlier run of it paused; the turn opens with them on its
6530
+ * list.
6531
+ *
6532
+ * @remarks Tools this reply already had when an earlier run of it paused. The turn opens with
6533
+ * them on its list, so an answered call does not take back what the model loaded. An id
6534
+ * \`tools.allow\` or the path does not grant is left out, as for \`tools.t1Policy\`.
6056
6535
  */
6057
6536
  promoted?: ToolId[];
6058
6537
  /**
6059
- * Steps this reply already took when an earlier run of it paused. They count against \`maxSteps\`,
6060
- * so an answered call does not give the reply its steps back. Read \`done.steps\`.
6538
+ * Steps this reply already took when an earlier run of it paused; they count against maxSteps.
6539
+ *
6540
+ * @remarks Steps this reply already took when an earlier run of it paused. They count against
6541
+ * \`maxSteps\`, so an answered call does not give the reply its steps back. Read \`done.steps\`.
6061
6542
  */
6062
6543
  stepsTaken?: number;
6063
6544
  /**
6064
- * Reads each of this turn's events as it leaves \`runTurn\`, before the caller gets it. The app
6065
- * sets it in \`TurnWiring.prepare\` to act on a turn someone else runs, such as saving the reply
6066
- * when \`done\` arrives. A throw ends the turn with that error. \`invokeTool\` does not call it.
6545
+ * Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw ends
6546
+ * the turn with that error.
6547
+ *
6548
+ * @remarks Reads each of this turn's events as it leaves \`runTurn\`, before the caller gets it.
6549
+ * The app sets it in \`TurnWiring.prepare\` to act on a turn someone else runs, such as saving the
6550
+ * reply when \`done\` arrives. A throw ends the turn with that error. \`invokeTool\` does not call
6551
+ * it.
6067
6552
  */
6068
6553
  onEvent?: (event: TurnEvent) => void | Promise<void>;
6069
6554
  /**
6070
- * Set on the turn \`TurnWiring.prepare\` is given for a held call that goes on once answered. No
6071
- * model runs and \`input\` is the paused turn's, so it is not a new message.
6555
+ * Set on the turn TurnWiring.prepare is given for a held call that goes on once answered: no
6556
+ * model runs, and input is the paused turn's.
6557
+ *
6558
+ * @remarks Set on the turn \`TurnWiring.prepare\` is given for a held call that goes on once
6559
+ * answered. No model runs and \`input\` is the paused turn's, so it is not a new message.
6072
6560
  */
6073
6561
  answersHeldCall?: true;
6562
+ /** What the user sent for the turn. */
6074
6563
  input?: TurnInput;
6075
6564
  }
6076
6565
  /**
@@ -6306,26 +6795,39 @@ export declare const AUTO_CONTINUE_DELAY_MS = 1500;
6306
6795
  /** Which stops a profile offers Continue for, and which the host continues on its own. */
6307
6796
  export interface ProfileTurnResumptionSpec {
6308
6797
  /**
6309
- * The host's UI policy for offering Continue: the kernel does not refuse a \`continueFrom\`
6310
- * outside it, since a continue is one more turn the host could send as plain text anyway.
6311
- * Omit → length / stream_incomplete / provider_error; \`[]\` = none.
6798
+ * Which early stops the host offers the user a Continue for; the kernel doesn't refuse a continue
6799
+ * after other stops.
6800
+ *
6801
+ * @remarks The host's UI policy for offering Continue: the kernel does not refuse a
6802
+ * \`continueFrom\` outside it, since a continue is one more turn the host could send as plain text
6803
+ * anyway. Omit → length / stream_incomplete / provider_error; \`[]\` = none.
6312
6804
  */
6313
6805
  allowContinue?: ContinueStopKind[];
6314
6806
  /**
6315
- * Omit → length / stream_incomplete; \`[]\` = none. Apart from \`allowContinue\`: a stop can be
6316
- * continued without Continue being offered for it. The host sends the \`continueFrom\` turn
6317
- * with \`continuation\`. A text turn also sends a failed model call (\`provider_error\`,
6318
- * \`stream_incomplete\`) again itself when this list is set and names that stop, and the
6319
- * call gave no reply and no tool call: the turn keeps its history, its step count and
6320
- * what it has read. A failure the same call would meet again (the provider refused the
6321
- * request) is not sent again, except once without its files when it carried any: accepted
6322
- * that way, the turn goes on and \`done.mediaRefused\` names them. Omitted, a turn sends
6323
- * nothing again.
6807
+ * Which early stops are continued without asking, whether or not allowContinue offers a Continue
6808
+ * for them. When set, a text turn sends a listed failed model call that gave no reply again
6809
+ * itself; the host continues the rest. Naming length also repairs a call the output limit cut
6810
+ * off: the model gets back what it wrote, or that it wrote nothing, and is asked again to fit.
6811
+ *
6812
+ * @remarks Omit → length / stream_incomplete; \`[]\` = none. Apart from \`allowContinue\`: a stop can
6813
+ * be continued without Continue being offered for it. The host sends the \`continueFrom\` turn with
6814
+ * \`continuation\`. A text turn also sends a failed model call (\`provider_error\`,
6815
+ * \`stream_incomplete\`) again itself when this list is set and names that stop, and the call gave
6816
+ * no reply and no tool call: the turn keeps its history, its step count and what it has read. A
6817
+ * failure the same call would meet again (the provider refused the request) is not sent again,
6818
+ * except once without its files when it carried any: accepted that way, the turn goes on and
6819
+ * \`done.mediaRefused\` names them. Named here, \`length\` also repairs a call the output limit cut
6820
+ * off: the model gets back what it wrote, or that it wrote nothing, and is asked again to fit.
6821
+ * Omitted, a turn sends nothing again.
6324
6822
  */
6325
6823
  autoContinue?: ContinueStopKind[];
6326
6824
  /**
6327
- * Compared against \`TurnRequest.continuation\`; omit → no count cap. Also how many model
6328
- * calls one text turn sends again itself; omit → one.
6825
+ * How many times one reply may be continued; once set, each continue must say which one it is.
6826
+ * Also how many model calls one text turn sends again itself, failed calls and cut-off repairs
6827
+ * together (one when unset).
6828
+ *
6829
+ * @remarks Compared against \`TurnRequest.continuation\`; omit → no count cap. Also how many model
6830
+ * calls one text turn sends again itself, failed calls and cut-off repairs together; omit → one.
6329
6831
  */
6330
6832
  maxContinues?: number;
6331
6833
  }
@@ -6336,12 +6838,20 @@ export declare function isContinueStopKind(kind: string): kind is ContinueStopKi
6336
6838
  * interfaces always project \`canStop: true\` because \`TurnRequest.signal\` is always wired.
6337
6839
  */
6338
6840
  export interface ProfileTurnBehaviourSpec {
6841
+ /** Continuing a reply that stopped early; live uses sessionResumption instead. */
6339
6842
  resumption?: ProfileTurnResumptionSpec;
6340
- /** Default true on text / live. Gates injects only; stage events still emit. */
6843
+ /**
6844
+ * Lets your onStage hook add messages to a running turn. Text profiles also let the user steer.
6845
+ *
6846
+ * @remarks Default true on text / live. Gates injects only; stage events still emit.
6847
+ */
6341
6848
  allowSteering?: boolean;
6342
6849
  /**
6343
- * Text only. What the last model call under \`maxSteps\` may do. Omit = \`'stop'\`: it may call
6344
- * tools, and if it does the turn stops as \`step_limit\`. \`'answer'\` sends it without tools.
6850
+ * What happens when a turn reaches maxSteps while the model still wants tools: the turn stops
6851
+ * with no answer, or the last call is made without tools so it answers.
6852
+ *
6853
+ * @remarks Text only. What the last model call under \`maxSteps\` may do. Omit = \`'stop'\`: it may
6854
+ * call tools, and if it does the turn stops as \`step_limit\`. \`'answer'\` sends it without tools.
6345
6855
  */
6346
6856
  atStepLimit?: StepLimitMode;
6347
6857
  }
@@ -6351,6 +6861,7 @@ export interface ProfileTurnBehaviourSpec {
6351
6861
  * no mid-turn inject to steer.
6352
6862
  */
6353
6863
  export interface MediaTurnBehaviourSpec {
6864
+ /** Continuing a reply that stopped early; live uses sessionResumption instead. */
6354
6865
  resumption?: ProfileTurnResumptionSpec;
6355
6866
  }
6356
6867
  /**
@@ -6381,6 +6892,8 @@ export declare function profileTurnResumption(profile: {
6381
6892
  type: string;
6382
6893
  turnBehaviour?: ProfileTurnBehaviourSpec;
6383
6894
  }): ProfileTurnResumptionSpec | undefined;
6895
+ /** How many model calls a turn sends again when the output limit cuts one off: \`maxContinues\` (one when unset) while \`autoContinue\` names \`length\`, else none. */
6896
+ export declare function cutOffRepairs(profile: Parameters<typeof profileTurnResumption>[0]): number;
6384
6897
  /** Text-only, for the interface \`allowSteering\` projection; \`profileAllowsInject\` adds live. */
6385
6898
  export declare function profileAllowsSteering(profile: {
6386
6899
  type: string;
@@ -6488,6 +7001,7 @@ export interface InjectedMessages {
6488
7001
  }
6489
7002
  /** Why a turn or live utterance ended. */
6490
7003
  export interface TurnStop {
7004
+ /** Why the turn ended, on the done event: its stop.kind. */
6491
7005
  kind: TurnStopKind;
6492
7006
  native?: string;
6493
7007
  }
@@ -6495,15 +7009,15 @@ export declare const turnStopSchema: z.ZodObject<{
6495
7009
  kind: z.ZodEnum<{
6496
7010
  length: "length";
6497
7011
  tool: "tool";
6498
- cancelled: "cancelled";
6499
- interrupted: "interrupted";
7012
+ gate: "gate";
6500
7013
  stream_incomplete: "stream_incomplete";
6501
7014
  provider_error: "provider_error";
6502
7015
  answer_missing: "answer_missing";
7016
+ cancelled: "cancelled";
6503
7017
  completed: "completed";
6504
- gate: "gate";
6505
7018
  filtered: "filtered";
6506
7019
  step_limit: "step_limit";
7020
+ interrupted: "interrupted";
6507
7021
  generation_complete: "generation_complete";
6508
7022
  }>;
6509
7023
  native: z.ZodOptional<z.ZodString>;
@@ -7297,11 +7811,7 @@ export type CompactionMeter = (typeof COMPACTION_METERS)[number];
7297
7811
  export declare const COMPACTION_TIMINGS: readonly ["before", "after"];
7298
7812
  /** One of {@linkcode COMPACTION_TIMINGS}. */
7299
7813
  export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
7300
- /**
7301
- * - \`compacted\`: a summary replaced the compacted messages.
7302
- * - \`deferred\`: the compactor failed and the history still fits \`maxTokens\`, so it is kept whole.
7303
- * - \`dropped\`: the compactor failed over \`maxTokens\`, so the compacted messages were dropped.
7304
- */
7814
+ /** What a compaction did. */
7305
7815
  export declare const COMPACTION_OUTCOMES: readonly ["compacted", "deferred", "dropped"];
7306
7816
  /** One of {@linkcode COMPACTION_OUTCOMES}. */
7307
7817
  export type CompactionOutcome = (typeof COMPACTION_OUTCOMES)[number];
@@ -7438,8 +7948,10 @@ export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
7438
7948
  /** Turns a key path into its catalog path, replacing host-chosen map keys with \`*\`. */
7439
7949
  export declare function catalogPathFor(keys: readonly string[]): string;
7440
7950
  /**
7441
- * Adding a profile field? Add it here; scope it in \`PROFILE_FIELD_SCOPE\` if only some types
7442
- * take it, and record it in \`PROFILE_FIELD_PRESENCE\` if it is required or its absence matters.
7951
+ * Adding a profile field? Write its doc as JSDoc on the type, run \`deno task field-docs\`, and add
7952
+ * it here with \`field()\`; scope it in \`PROFILE_FIELD_SCOPE\` if only some types take it, and record
7953
+ * it in \`PROFILE_FIELD_PRESENCE\` if it is required or its absence matters. A map's entries
7954
+ * (\`models.*\`) take their doc from a \`@catalog <path> <text>\` tag on the map's property.
7443
7955
  */
7444
7956
  export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
7445
7957
  /**
@@ -7609,88 +8121,39 @@ export { profileGraphFacet, spineFacetsForProfileType };
7609
8121
  `,"file:///node_modules/@theoremjs/agents/src/kernel/api-catalog.d.ts":`/** labels-exempt-file: authoring request-field and export meta — not runtime user or model copy (P2) */
7610
8122
  import type { FieldMeta } from './schema.js';
7611
8123
  import type { TurnInput, TurnRequest } from './types.js';
8124
+ /** A \`runTurn\` request field's catalog path. */
8125
+ export type RequestPath = \`runTurn.\${keyof TurnRequest | \`input.\${keyof TurnInput}\`}\`;
7612
8126
  /** The catalog of the fields a \`runTurn\` request takes, keyed \`runTurn.<field>\`. */
7613
- export declare const REQUEST_FIELDS: Record<\`runTurn.\${keyof TurnRequest | \`input.\${keyof TurnInput}\`}\`, FieldMeta>;
8127
+ export declare const REQUEST_FIELDS: Record<RequestPath, FieldMeta>;
7614
8128
  /** What the catalog records about one export: what it is and what it does. */
7615
8129
  export type ApiExportMeta = {
7616
8130
  kind: 'function' | 'class';
7617
8131
  doc: string;
7618
8132
  };
7619
- /** The catalog of the exports a builder calls by name, keyed by that name. */
7620
- export declare const API_EXPORTS: {
7621
- readonly defineProfile: {
7622
- readonly kind: "function";
7623
- readonly doc: "Checks a profile and returns it; a field the profile type cannot take is a config error.";
7624
- };
7625
- readonly registerProfile: {
7626
- readonly kind: "function";
7627
- readonly doc: "Stores a profile under its id, so that a request can name it.";
7628
- };
7629
- readonly registerTool: {
7630
- readonly kind: "function";
7631
- readonly doc: "Stores a tool under its name, so that a profile can list it in tools.allow.";
7632
- };
7633
- readonly registerStructured: {
7634
- readonly kind: "function";
7635
- readonly doc: "Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.";
7636
- };
7637
- readonly registerTraceDestination: {
7638
- readonly kind: "function";
7639
- readonly doc: "Stores a place to write traces under an id, so that a profile can name it in observability.";
7640
- };
7641
- readonly defineProvider: {
7642
- readonly kind: "function";
7643
- readonly doc: "Validates a provider definition and supplies its typed model helper.";
7644
- };
7645
- readonly registerProvider: {
7646
- readonly kind: "function";
7647
- readonly doc: "Registers a provider instance before profiles reference its ID.";
7648
- };
7649
- readonly runTurn: {
7650
- readonly kind: "function";
7651
- readonly doc: "Runs one turn of a text, image, or speech profile and yields its events.";
7652
- };
7653
- readonly runSession: {
7654
- readonly kind: "function";
7655
- readonly doc: "Runs a realtime voice or video session of a live profile.";
7656
- };
7657
- readonly runDecision: {
7658
- readonly kind: "function";
7659
- readonly doc: "Asks a decision profile its questions about your JSON state and returns checked answers.";
7660
- };
7661
- readonly invokeTool: {
7662
- readonly kind: "function";
7663
- readonly doc: "Runs one registered tool through a profile, with no model.";
7664
- };
7665
- readonly runTool: {
7666
- readonly kind: "function";
7667
- readonly doc: "Runs one registered tool through a profile, with no model, and returns how the call settled.";
7668
- };
7669
- readonly compactHistory: {
7670
- readonly kind: "function";
7671
- readonly doc: "Shortens a conversation history with the compaction the profile sets.";
7672
- };
7673
- readonly takeSlot: {
7674
- readonly kind: "function";
7675
- readonly doc: "Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.";
7676
- };
7677
- readonly releaseSlot: {
7678
- readonly kind: "function";
7679
- readonly doc: "Frees the turn slot that takeSlot gave.";
7680
- };
7681
- readonly overrideLabels: {
7682
- readonly kind: "function";
7683
- readonly doc: "Replaces status lines for every profile in the process; a profile's own labels wins.";
7684
- };
7685
- readonly resetLabels: {
7686
- readonly kind: "function";
7687
- readonly doc: "Removes every replacement that overrideLabels made.";
7688
- };
7689
- readonly TheoremError: {
7690
- readonly kind: "class";
7691
- readonly doc: "The error Theorem throws; its kind tells your host which status and wording to use.";
7692
- };
7693
- };
8133
+ /** What each export a builder calls by name is. */
8134
+ declare const EXPORT_KINDS: {
8135
+ readonly defineProfile: "function";
8136
+ readonly registerProfile: "function";
8137
+ readonly registerTool: "function";
8138
+ readonly registerStructured: "function";
8139
+ readonly registerTraceDestination: "function";
8140
+ readonly defineProvider: "function";
8141
+ readonly registerProvider: "function";
8142
+ readonly runTurn: "function";
8143
+ readonly runSession: "function";
8144
+ readonly runDecision: "function";
8145
+ readonly invokeTool: "function";
8146
+ readonly runTool: "function";
8147
+ readonly compactHistory: "function";
8148
+ readonly takeSlot: "function";
8149
+ readonly releaseSlot: "function";
8150
+ readonly overrideLabels: "function";
8151
+ readonly resetLabels: "function";
8152
+ readonly TheoremError: "class";
8153
+ };
8154
+ /** The catalog of the exports a builder calls by name, keyed by that name; each doc is its JSDoc. */
8155
+ export declare const API_EXPORTS: Record<keyof typeof EXPORT_KINDS, ApiExportMeta>;
8156
+ export {};
7694
8157
  `,"file:///node_modules/@theoremjs/agents/src/kernel/registry/vault.d.ts":`import type { JsonObject } from '../json.js';
7695
8158
  import type { KeySlot } from '../types.js';
7696
8159
  /** A key as the vault holds it: a string, or an object for a provider that signs in with several fields. */
@@ -7747,14 +8210,19 @@ export type BlockedReplyOnBlock = (typeof BLOCKED_REPLY_ON_BLOCK)[number];
7747
8210
  /** What happens once a detector blocks a reply. */
7748
8211
  export interface BlockedReplySpec {
7749
8212
  /**
7750
- * \`retry\` (the default) tells the model what blocked the reply and has it write another;
7751
- * \`refuse\` sends the user the labels' \`egress.refusal\` in its place, or ends the part
7752
- * they already have with \`egress.refusal_cut\`.
8213
+ * Whether the model gets to rewrite a reply a guardrail blocked, or the user gets a refusal in
8214
+ * its place.
8215
+ *
8216
+ * @remarks \`retry\` (the default) tells the model what blocked the reply and has it write another;
8217
+ * \`refuse\` sends the user the labels' \`egress.refusal\` in its place, or ends the part they
8218
+ * already have with \`egress.refusal_cut\`.
7753
8219
  */
7754
8220
  onBlock?: BlockedReplyOnBlock;
7755
8221
  /**
7756
- * Under \`retry\`, how many times the model may rewrite a blocked reply (default 1). Once they
7757
- * are spent the reply is withheld and the turn ends in a \`safety\` error.
8222
+ * How many times the model may rewrite a blocked reply. Live ignores it.
8223
+ *
8224
+ * @remarks Under \`retry\`, how many times the model may rewrite a blocked reply (default 1). Once
8225
+ * they are spent the reply is withheld and the turn ends in a \`safety\` error.
7758
8226
  */
7759
8227
  maxRetries?: number;
7760
8228
  }
@@ -7844,11 +8312,20 @@ export type DestinationGate = (typeof DESTINATION_GATES)[number];
7844
8312
  */
7845
8313
  export interface TaintGuardrailSpec {
7846
8314
  /**
7847
- * Stated as a capability threshold rather than a list of tool \`access\` values so
7848
- * the guardrail vocabulary stays independent of the tool registry; the kernel
7849
- * maps a tool's declared access onto it.
8315
+ * Which tool calls are refused, by each tool's access, once the turn has read a remote tool's
8316
+ * result.
8317
+ *
8318
+ * @remarks Stated as a capability threshold rather than a list of tool \`access\` values so the
8319
+ * guardrail vocabulary stays independent of the tool registry; the kernel maps a tool's declared
8320
+ * access onto it.
7850
8321
  */
7851
8322
  afterRemoteRead?: TaintGate;
8323
+ /**
8324
+ * What happens to a tool call, read-only ones too, that sends to an email address, a link's host
8325
+ * or a bank account number (IBAN) that only the running text of a remote tool's result named. One
8326
+ * the user, the system prompt, or a local tool gave passes, and so does one that is a whole field
8327
+ * of the result.
8328
+ */
7852
8329
  remoteDestination?: DestinationGate;
7853
8330
  }
7854
8331
  /** Facts a check may read. Deliberately excludes the full profile. */
@@ -7896,35 +8373,67 @@ export interface OutboundPayload {
7896
8373
  }
7897
8374
  /** Which hosts and networks a tool's requests may reach. */
7898
8375
  export interface NetworkGuardrailSpec {
7899
- /** Allows localhost, loopback, and private subnets (local dev and testing). Default false. */
8376
+ /**
8377
+ * Lets tools reach localhost and private network addresses, for local development.
8378
+ *
8379
+ * @remarks Allows localhost, loopback, and private subnets (local dev and testing). Default
8380
+ * false.
8381
+ */
7900
8382
  allowPrivateNetworks?: boolean;
7901
- /** Hostnames or IP addresses permitted regardless of private subnet status. */
8383
+ /**
8384
+ * Hostnames tools may reach even when they resolve to a private address; public hosts don't need
8385
+ * listing. Names are resolved only when the host passes resolveHost.
8386
+ *
8387
+ * @remarks Hostnames or IP addresses permitted regardless of private subnet status.
8388
+ */
7902
8389
  allowedHosts?: string[];
7903
8390
  /**
7904
- * Allowed URL schemes. Defaults to \`['https']\`, or \`['http', 'https']\` when
8391
+ * The URL schemes tools may use.
8392
+ *
8393
+ * @remarks Allowed URL schemes. Defaults to \`['https']\`, or \`['http', 'https']\` when
7905
8394
  * \`allowPrivateNetworks\` is set.
7906
8395
  */
7907
8396
  allowedSchemes?: string[];
7908
8397
  }
7909
8398
  /** Optional daily turn quota consumed by host HTTP middleware. */
7910
8399
  export interface QuotaGuardrailSpec {
8400
+ /**
8401
+ * Turns each client IP may run on this profile per UTC day, one at a time; counts live in the
8402
+ * process, and a loopback caller is not counted.
8403
+ */
7911
8404
  perDay: number;
7912
8405
  }
7913
8406
  /** The guardrails a profile turns on, each with its own settings. */
7914
8407
  export interface ProfileGuardrailsSpec {
7915
- /** Omitted means quota enforcement is not configured. */
8408
+ /**
8409
+ * A daily turn limit. Your server enforces it with takeSlot.
8410
+ *
8411
+ * @remarks Omitted means quota enforcement is not configured.
8412
+ */
7916
8413
  quota?: QuotaGuardrailSpec;
7917
8414
  /**
7918
- * What the kernel does when a detector finds a match, per boundary: one action
7919
- * for everything, or a rule for the detectors it names. Anything left out keeps
7920
- * its default (\`DETECT_DEFAULTS\`). A canary is bound into the system prompt
7921
- * while \`canary_leak\` is above \`ignore\` somewhere; the note that binds it is
7922
- * the labels' \`canary.bind_note\` (the profile's \`labels\` may replace it).
8415
+ * What a guardrail does when a detector matches. One action covers every detector; an object sets
8416
+ * each detector (or one of your own) apart. Absent: each detector keeps its default action.
8417
+ *
8418
+ * @remarks What the kernel does when a detector finds a match, per boundary: one action for
8419
+ * everything, or a rule for the detectors it names. Anything left out keeps its default
8420
+ * (\`DETECT_DEFAULTS\`). A canary is bound into the system prompt while \`canary_leak\` is above
8421
+ * \`ignore\` somewhere; the note that binds it is the labels' \`canary.bind_note\` (the profile's
8422
+ * \`labels\` may replace it).
8423
+ *
8424
+ * @catalog guardrails.detect.* Your own detector, keyed with a dot: acme.codenames. No default action.
7923
8425
  */
7924
8426
  detect?: DetectSpec;
7925
- /** What happens once a reply is blocked. Left out, the model rewrites it once. */
8427
+ /**
8428
+ * How a reply a guardrail blocked is handled: the model rewrites it, or the user gets a refusal,
8429
+ * and how many rewrites it gets.
8430
+ *
8431
+ * @remarks What happens once a reply is blocked. Left out, the model rewrites it once.
8432
+ */
7926
8433
  blockedReply?: BlockedReplySpec;
8434
+ /** Addresses HTTP and MCP tools may reach. */
7927
8435
  network?: NetworkGuardrailSpec;
8436
+ /** Tool limits after a remote read. */
7928
8437
  taint?: TaintGuardrailSpec;
7929
8438
  }
7930
8439
  /** Pre-dispatch policy for structured state leaving a decision profile. */
@@ -7947,7 +8456,9 @@ export type DecisionDisclosureEnforcer = (state: unknown, context: {
7947
8456
  * decision registry rejects every inherited field as inert in this release.
7948
8457
  */
7949
8458
  export interface DecisionGuardrailsSpec extends Partial<ProfileGuardrailsSpec> {
8459
+ /** Your check on the state before a decision sends it to the model. */
7950
8460
  disclosure?: {
8461
+ /** Your function that allows or blocks the state before it is sent. */
7951
8462
  enforce: DecisionDisclosureEnforcer;
7952
8463
  };
7953
8464
  }
@@ -8018,7 +8529,7 @@ export { applySpans, blobAt, mergeSpans, OMIT_CANARY, OMIT_INJECTION, OMIT_PROMP
8018
8529
  `,"file:///node_modules/@theoremjs/agents/src/guardrails/labels.d.ts":`/** Values that fill a label template's \`{param}\` placeholders. */
8019
8530
  export type LabelParams = Record<string, string | number>;
8020
8531
  /** Keys are stable API. */
8021
- export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
8532
+ export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.reply_cut_off", "repair.call_cut_off", "repair.call_cut_off_guidance", "repair.nothing_written", "repair.nothing_written_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
8022
8533
  /** One of {@linkcode LABEL_KEYS}. */
8023
8534
  export type LabelKey = (typeof LABEL_KEYS)[number];
8024
8535
  /**
@@ -8045,9 +8556,17 @@ export declare const LABEL_NOTES: Record<LabelKey, string>;
8045
8556
  export declare function labelPlaceholders(key: LabelKey): readonly string[];
8046
8557
  /** \`owner\` names where the overrides came from in the error. */
8047
8558
  export declare function validateLabelOverrides(entries: LabelOverrides, owner: string): void;
8048
- /** Process-wide; a profile's own \`labels\` wins over these. */
8559
+ /**
8560
+ * Replaces status lines for every profile in the process; a profile's own labels wins.
8561
+ *
8562
+ * @remarks Process-wide; a profile's own \`labels\` wins over these.
8563
+ */
8049
8564
  export declare function overrideLabels(entries: LabelOverrides): void;
8050
- /** Remove every label override. */
8565
+ /**
8566
+ * Removes every replacement that overrideLabels made.
8567
+ *
8568
+ * @remarks Remove every label override.
8569
+ */
8051
8570
  export declare function resetLabels(): void;
8052
8571
  /** The wording for a key, with a profile's override applied and the params filled in. */
8053
8572
  export declare function labelText(key: LabelKey, params?: LabelParams, profileLabels?: LabelOverrides): string;
@@ -8180,7 +8699,11 @@ export interface TheoremErrorOptions extends ErrorOptions {
8180
8699
  /** User wording more specific than the kind's: one line, or one per problem found. */
8181
8700
  copy?: ErrorCopies;
8182
8701
  }
8183
- /** An error that carries a \`kind\`, from which hosts choose a status and the user's wording. */
8702
+ /**
8703
+ * The error Theorem throws; its kind tells your host which status and wording to use.
8704
+ *
8705
+ * @remarks An error that carries a \`kind\`, from which hosts choose a status and the user's wording.
8706
+ */
8184
8707
  export declare class TheoremError extends Error {
8185
8708
  readonly kind: ErrorKind;
8186
8709
  readonly copy?: ErrorCopies;
@@ -8305,7 +8828,11 @@ export interface ProviderWarning {
8305
8828
  export declare const providerWarningSchema: z.ZodType<ProviderWarning>;
8306
8829
  export interface ProviderContinuationPolicy {
8307
8830
  /**
8308
- * Who holds the conversation a checkpoint continues. \`'host'\` (unset) passes the covered
8831
+ * Who holds the conversation a checkpoint continues: the host passes history back, the provider
8832
+ * keeps it and the checkpoint travels alone, or the profile is stateless and every request stands
8833
+ * alone.
8834
+ *
8835
+ * @remarks Who holds the conversation a checkpoint continues. \`'host'\` (unset) passes the covered
8309
8836
  * history back with the checkpoint. \`'provider'\` passes the checkpoint alone: the provider's
8310
8837
  * stored conversation is the history, and a turn that goes elsewhere needs the host's history.
8311
8838
  * \`'stateless'\` keeps no conversation: a request that carries history or a checkpoint is refused,
@@ -8543,19 +9070,45 @@ import type { TraceSink } from './trace-sink.js';
8543
9070
  import type { TraceAttributes } from './trace-span.js';
8544
9071
  /** Which payloads land in each TraceRecord. Omitted keys use resolved defaults. */
8545
9072
  export interface TraceIncludeSpec {
8546
- /** Scrubbed provider rows and frames (\`theorem.upstream.row\` events). Default: true. */
9073
+ /**
9074
+ * Keeps each row the provider sent back, scrubbed, as it arrived, with media bytes replaced by
9075
+ * their sha256.
9076
+ *
9077
+ * @remarks Scrubbed provider rows and frames (\`theorem.upstream.row\` events). Default: true.
9078
+ */
8547
9079
  upstreamLog?: boolean;
8548
- /** Scrubbed outbound request bodies (\`theorem.wire.request\` events). Default: false. */
9080
+ /**
9081
+ * Keeps each request body sent to the provider, scrubbed.
9082
+ *
9083
+ * @remarks Scrubbed outbound request bodies (\`theorem.wire.request\` events). Default: false.
9084
+ */
8549
9085
  outboundWire?: boolean;
8550
- /** The provider's raw grounding payload (\`raw\` on \`theorem.grounding\` events). Default: false. */
9086
+ /**
9087
+ * Keeps the provider's raw payload on grounding results such as search citations; upstreamLog
9088
+ * rows keep their own copy.
9089
+ *
9090
+ * @remarks The provider's raw grounding payload (\`raw\` on \`theorem.grounding\` events). Default:
9091
+ * false.
9092
+ */
8551
9093
  evidenceRaw?: boolean;
8552
- /** Usage attributes (\`gen_ai.usage.*\`, \`theorem.usage.*\`). Default: true. */
9094
+ /**
9095
+ * Keeps token counts and other usage figures on spans; upstreamLog rows keep their own.
9096
+ *
9097
+ * @remarks Usage attributes (\`gen_ai.usage.*\`, \`theorem.usage.*\`). Default: true.
9098
+ */
8553
9099
  usage?: boolean;
8554
- /** Guardrail decisions (\`theorem.guardrail\` events). Default: true. */
9100
+ /**
9101
+ * Keeps each guardrail decision.
9102
+ *
9103
+ * @remarks Guardrail decisions (\`theorem.guardrail\` events). Default: true.
9104
+ */
8555
9105
  guardrailDecisions?: boolean;
8556
9106
  /**
8557
- * Keep \`GuardrailHit.match\` (the exact matched text) on guardrail events. Default: false;
8558
- * debugging only, so treat the store like server logs when enabled.
9107
+ * Keeps the exact text each guardrail matched, unscrubbed, on the trace and the host's event
9108
+ * stream; for debugging only.
9109
+ *
9110
+ * @remarks Keep \`GuardrailHit.match\` (the exact matched text) on guardrail events. Default:
9111
+ * false; debugging only, so treat the store like server logs when enabled.
8559
9112
  */
8560
9113
  guardrailMatchPreview?: boolean;
8561
9114
  }
@@ -8574,42 +9127,90 @@ export type ScrubSwitch = boolean | {
8574
9127
  * their actions: a detector set to \`ignore\` in the turn still cleans the trace. Defaults are on.
8575
9128
  */
8576
9129
  export interface TraceScrubSpec {
8577
- /** The data detectors (\`ids\`, \`financial\`, \`network\`, \`credentials\`) and the host's own. Default: true. */
9130
+ /**
9131
+ * Removes what the data detectors (IDs, Financial, Network, Credentials) and your own detectors
9132
+ * find from stored traces. On, it cleans with the patterns each reads the turn with; { theorem,
9133
+ * host } picks Theorem's patterns, yours, or both for the trace alone.
9134
+ *
9135
+ * @remarks The data detectors (\`ids\`, \`financial\`, \`network\`, \`credentials\`) and the host's own.
9136
+ * Default: true.
9137
+ */
8578
9138
  sensitive?: ScrubSwitch;
8579
- /** \`injection\`, with the orders to the agent it finds in what a tool returns. Default: true. */
9139
+ /**
9140
+ * Removes what Injection and Tool instructions find from stored traces. On, it cleans with the
9141
+ * patterns each reads the turn with; { theorem, host } picks Theorem's patterns, yours, or both
9142
+ * for the trace alone.
9143
+ *
9144
+ * @remarks \`injection\`, with the orders to the agent it finds in what a tool returns. Default:
9145
+ * true.
9146
+ */
8580
9147
  injection?: ScrubSwitch;
8581
- /** Never persist the canary token. It is Theorem's alone, so the host side adds nothing. Default: true. */
9148
+ /**
9149
+ * Removes the canary token from stored traces. The canary is Theorem's, so { theorem: false }
9150
+ * keeps it.
9151
+ *
9152
+ * @remarks Never persist the canary token. It is Theorem's alone, so the host side adds nothing.
9153
+ * Default: true.
9154
+ */
8582
9155
  canary?: ScrubSwitch;
8583
9156
  }
8584
9157
  /** Omit the whole block for no tracing. */
8585
9158
  export interface ProfileObservabilitySpec {
8586
9159
  /**
8587
- * \`false\` is off, a string is a \`registerTraceDestination\` id, a TraceSink is an inline writer.
8588
- * \`runTurn(..., sink)\` still overrides this for one call.
9160
+ * Where traces go: a registered destination id, your own writer, or false. An unregistered id
9161
+ * fails the turn at the start. A sink passed to runTurn replaces it.
9162
+ *
9163
+ * @remarks \`false\` is off, a string is a \`registerTraceDestination\` id, a TraceSink is an inline
9164
+ * writer. \`runTurn(..., sink)\` still overrides this for one call.
8589
9165
  */
8590
9166
  writeTo?: false | string | TraceSink;
8591
9167
  /**
8592
- * Fraction of traces to record, 0–1 inclusive. Default: 1. Decided by trace id, so every
9168
+ * The share of traces kept, from 0 to 1, each kept or dropped whole; a sink passed straight to
9169
+ * runTurn keeps every trace.
9170
+ *
9171
+ * @remarks Fraction of traces to record, 0–1 inclusive. Default: 1. Decided by trace id, so every
8593
9172
  * record of one trace is kept or dropped together.
8594
9173
  */
8595
9174
  sampleRate?: number;
9175
+ /** Which optional parts of a trace are kept. */
8596
9176
  include?: TraceIncludeSpec;
8597
- /** Stamped on every record as \`TraceRecord.resource\`, e.g. \`{ 'service.name': 'harbor' }\`. */
9177
+ /**
9178
+ * Attributes stamped on every trace, such as service.name.
9179
+ *
9180
+ * @remarks Stamped on every record as \`TraceRecord.resource\`, e.g. \`{ 'service.name': 'harbor'
9181
+ * }\`.
9182
+ */
8598
9183
  resource?: TraceAttributes;
8599
- /** Defaults stay on even when \`guardrails.detect\` is \`ignore\`. */
9184
+ /**
9185
+ * What is removed from stored traces, separately from the turn's guardrails.
9186
+ *
9187
+ * @remarks Defaults stay on even when \`guardrails.detect\` is \`ignore\`.
9188
+ */
8600
9189
  scrub?: TraceScrubSpec;
8601
9190
  /**
8602
- * Days to keep each record, handed to every destination with the record
8603
- * (\`TraceWriteContext\`): the JSONL writer prunes by it, a host store computes
8604
- * its own expiry from it. \`<= 0\` keeps records forever. Default: 14.
9191
+ * Days a trace file is kept, by its UTC day. The next write removes old files. 0 or less keeps
9192
+ * all.
9193
+ *
9194
+ * @remarks Days to keep each record, handed to every destination with the record
9195
+ * (\`TraceWriteContext\`): the JSONL writer prunes by it, a host store computes its own expiry from
9196
+ * it. \`<= 0\` keeps records forever. Default: 14.
8605
9197
  */
8606
9198
  retainForDays?: number;
8607
9199
  /**
8608
9200
  * File size in MiB at which a file-based destination starts a new file, handed to every
9201
+ * destination with the record. Default 32.
9202
+ *
9203
+ * @remarks File size in MiB at which a file-based destination starts a new file, handed to every
8609
9204
  * destination with the record (\`TraceWriteContext\`). Default: 32.
8610
9205
  */
8611
9206
  rotateAfterMiB?: number;
8612
- /** Called when record build or destination write fails. Must not throw. */
9207
+ /**
9208
+ * Your function called when a trace can't be built or written; the turn carries on, and a
9209
+ * destination's own error handler takes priority. An unregistered writeTo id is a config error
9210
+ * instead.
9211
+ *
9212
+ * @remarks Called when record build or destination write fails. Must not throw.
9213
+ */
8613
9214
  onWriteError?: (err: unknown) => void;
8614
9215
  }
8615
9216
  /** Which optional content a trace record includes, each on or off. */
@@ -8937,8 +9538,23 @@ import type { RegisteredProvider } from './provider.js';
8937
9538
  /** A vault slot name. */
8938
9539
  export declare const keySlotSchema: z.ZodString;
8939
9540
  export declare const commonModelSettingsSchema: z.ZodObject<{
9541
+ /**
9542
+ * The token limit for one reply. Some providers never send it for speech, or for image without
9543
+ * includeText.
9544
+ */
8940
9545
  maxOutputTokens: z.ZodOptional<z.ZodNumber>;
9546
+ /**
9547
+ * How varied the model's wording is; higher is more random. Some providers never send it for
9548
+ * speech, or for image without includeText.
9549
+ */
8941
9550
  temperature: z.ZodOptional<z.ZodNumber>;
9551
+ /**
9552
+ * Named thinking levels. A turn picks one when allowEffortSelect is on. A provider refuses a
9553
+ * level its model does not take. Speech ignores them, and so may an image profile without
9554
+ * includeText.
9555
+ *
9556
+ * @catalog models.*.efforts.* The thinking level sent to the provider for this name.
9557
+ */
8942
9558
  efforts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
8943
9559
  none: 'none';
8944
9560
  minimal: 'minimal';
@@ -8948,24 +9564,65 @@ export declare const commonModelSettingsSchema: z.ZodObject<{
8948
9564
  xhigh: 'xhigh';
8949
9565
  max: 'max';
8950
9566
  }>>>;
9567
+ /** The effort a turn gets when it doesn't pick one. */
8951
9568
  defaultEffort: z.ZodOptional<z.ZodString>;
9569
+ /** Lets a turn pick an effort; needs two or more efforts. */
8952
9570
  allowEffortSelect: z.ZodOptional<z.ZodBoolean>;
9571
+ /**
9572
+ * Asks the model for summaries of its thinking, which not every model sends; with some providers,
9573
+ * off only hides thoughts, and others ignore it.
9574
+ */
8953
9575
  summaries: z.ZodOptional<z.ZodBoolean>;
9576
+ /**
9577
+ * The provider's own tools, such as Google Search, this model may use; each must be registered as
9578
+ * a builtin tool and declared by the provider's adapter.
9579
+ */
8954
9580
  builtInTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
9581
+ /**
9582
+ * Summarises history past a threshold. A text agent can write the summary. Other types name a
9583
+ * compaction profile.
9584
+ */
8955
9585
  compaction: z.ZodOptional<z.ZodCustom<import('../types.js').CompactionSpec>>;
8956
9586
  }>;
8957
9587
  /** One entry under a profile's \`models\`: which protocol, which provider, which model, and its settings. */
8958
9588
  export interface ModelBinding extends z.infer<typeof commonModelSettingsSchema> {
9589
+ /** The API shape this model is spoken to in. */
8959
9590
  protocol: string;
9591
+ /**
9592
+ * The service that runs the model or routes requests to one, such as Gemini or OpenRouter. Its
9593
+ * registration supplies the endpoint and authentication.
9594
+ */
8960
9595
  provider: string;
9596
+ /**
9597
+ * The model's id as the provider lists it, such as gemini-2.5-flash; sent on every call. The name
9598
+ * this model has in the profile is its key in models.
9599
+ */
8961
9600
  apiId: string;
9601
+ /**
9602
+ * The key slot this model's calls are signed with, instead of the provider's. Use it to bill one
9603
+ * model to a different key. Absent: the provider's primary slot.
9604
+ */
8962
9605
  keySlot?: string;
9606
+ /**
9607
+ * The key slot tried once after a rate limit or a busy model on the primary slot, instead of the
9608
+ * provider's fallback. Must differ from the primary slot. Absent: the provider's fallback slot,
9609
+ * if it has one.
9610
+ */
8963
9611
  fallbackKeySlot?: string;
9612
+ /**
9613
+ * Settings only this model's protocol has, such as a task type or vector size. Each is checked
9614
+ * when the profile loads. Any left out keep the provider's default.
9615
+ */
8964
9616
  options?: JsonObject;
9617
+ /**
9618
+ * The points at which Theorem stops this model's calls. Each one left out is no limit, so the
9619
+ * provider's own limits apply. A runTurn limits value overrides each field it sets.
9620
+ */
8965
9621
  limits?: ProviderLimits;
8966
9622
  }
8967
9623
  /** A decision profile's model: no generation settings, and a time limit. */
8968
9624
  export interface DecisionModelBinding extends Pick<ModelBinding, 'protocol' | 'provider' | 'apiId' | 'keySlot' | 'fallbackKeySlot' | 'options' | 'limits'> {
9625
+ /** How long a decision waits for its provider, in milliseconds. Omit for no timeout. */
8969
9626
  timeoutMs?: number;
8970
9627
  }
8971
9628
  export declare const modelBindingSchema: z.ZodType<ModelBinding>;
@@ -9030,19 +9687,63 @@ import type { PageToolExecution, ToolExecutionCoordinator } from './operation.js
9030
9687
  import type { UncheckedOutput } from './unchecked-output.js';
9031
9688
  export type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPermission, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool, };
9032
9689
  export interface ToolLabels {
9690
+ /**
9691
+ * Transcript text while a call runs, e.g. 'Saving {title} to your collection'. {path} reads the
9692
+ * call's input.
9693
+ */
9033
9694
  activity?: LabelTemplate;
9695
+ /**
9696
+ * What the transcript says once a call completes, e.g. 'Found {results.0.name}'. Each {path} is
9697
+ * filled from the call's input, then its output.
9698
+ */
9034
9699
  activityPast?: LabelTemplate;
9700
+ /**
9701
+ * What the transcript says when a call fails or the host labels it failed, e.g. 'Couldn't save
9702
+ * {title}'. Each {path} is filled from the call's input.
9703
+ */
9035
9704
  activityFailed?: LabelTemplate;
9705
+ /**
9706
+ * What the approval card says the agent wants to do, e.g. 'check the weather in {city}'. Each
9707
+ * {path} is filled from the call's input.
9708
+ */
9036
9709
  request?: LabelTemplate;
9037
9710
  }
9038
9711
  export interface ToolBase {
9712
+ /**
9713
+ * The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model
9714
+ * calls a custom tool by.
9715
+ */
9039
9716
  name: string;
9717
+ /** Tells the model what the tool does (custom tools only). */
9040
9718
  description: string;
9719
+ /** A label for grouping tools; nothing reads it yet. */
9041
9720
  category: string;
9721
+ /**
9722
+ * What the tool can change, which taint.afterRemoteRead refuses calls by after a turn reads a
9723
+ * remote tool's result.
9724
+ */
9042
9725
  access: ToolAccess;
9726
+ /**
9727
+ * The turn paths this tool is offered on, where * means every path; a turn with no path gets only
9728
+ * * tools. Host profiles ignore it.
9729
+ */
9043
9730
  paths: string[];
9731
+ /**
9732
+ * When the tool becomes available to the model; live and host profiles load every allowed tool at
9733
+ * the start.
9734
+ */
9044
9735
  loadTier: ToolLoadTier;
9736
+ /** Whether the host must approve a call before it runs; the provider's own tools never ask. */
9045
9737
  permission: ToolPermission;
9738
+ /**
9739
+ * Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list
9740
+ * item. {path|text} shows the text when the value is unusable. {count hit|hits} shows a number
9741
+ * with the word for one or for any other number: '1 hit', '3 hits'. With no fallback, the label
9742
+ * is dropped. A label is one line, or a list read top to bottom: the first line that fits is
9743
+ * shown. A line fits when each {path} has a value and its condition holds, as in 'when status is
9744
+ * archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in
9745
+ * words. The last line of a list must always fit.
9746
+ */
9046
9747
  labels?: ToolLabels;
9047
9748
  }
9048
9749
  /**
@@ -9050,7 +9751,9 @@ export interface ToolBase {
9050
9751
  * adapter declares it (\`ProviderAdapter.builtins\`) and owns how it is sent.
9051
9752
  */
9052
9753
  export interface BuiltinToolDef extends ToolBase {
9754
+ /** How the tool runs. */
9053
9755
  type: 'builtin';
9756
+ /** The built-in tools a builtin tool cannot run beside. */
9054
9757
  conflictsWith?: string[];
9055
9758
  }
9056
9759
  /** How a held tool call resumes: approved, refused, or retried after sign-in. */
@@ -9169,32 +9872,71 @@ export type ToolHandler<TIn, TOut> = SyncToolHandler<TIn, TOut> | StreamToolHand
9169
9872
  * the handler's return type; moving them here silently breaks inference for stream handlers.
9170
9873
  */
9171
9874
  export interface ToolHostHooks<TIn = unknown> {
9875
+ /**
9876
+ * The tool's arguments as a JSON Schema, sent to the model.
9877
+ */
9172
9878
  inputSchema: Record<string, unknown>;
9879
+ /**
9880
+ * The tool's result as a JSON Schema, which a function tool's stand-in result is built from.
9881
+ */
9173
9882
  outputSchema: Record<string, unknown>;
9174
- /** Runs before the host's \`pre_tool\` \`onStage\`. */
9883
+ /**
9884
+ * Runs before the host's pre_tool onStage.
9885
+ *
9886
+ * @remarks Runs before the host's \`pre_tool\` \`onStage\`.
9887
+ */
9175
9888
  preTool?: (input: TIn, ctx: ToolContext) => import('../stages.js').StageResult | undefined | Promise<import('../stages.js').StageResult | undefined>;
9889
+ /** Whether the model can see and call the tool. */
9176
9890
  exposeToModel?: boolean;
9177
- /** The model gets an \`after\` field: the tools in the same step that must settle before this call starts. */
9891
+ /**
9892
+ * Gives the model an after field on this tool: the tools called in the same step that must settle
9893
+ * before this call starts. The kernel removes the field before the tool, the stages or a gate
9894
+ * read the input. A name with no other call in the step fails the call wait_unknown.
9895
+ *
9896
+ * @remarks The model gets an \`after\` field: the tools in the same step that must settle before
9897
+ * this call starts.
9898
+ */
9178
9899
  after?: boolean;
9179
- /** When the model gets its reply. Unset is \`never\`: when the body ends. A turn without a background service runs inline. */
9900
+ /**
9901
+ * When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }:
9902
+ * once the body has run past this time. 'ask': at the hand-off if the model sets the background
9903
+ * argument. A turn with no background service runs the tool inline.
9904
+ *
9905
+ * @remarks When the model gets its reply. Unset is \`never\`: when the body ends. A turn without a
9906
+ * background service runs inline.
9907
+ */
9180
9908
  background?: ToolBackground;
9181
9909
  /** \`inputSchema\` with the \`background\` argument. The registry sets it on an \`ask\` tool. */
9182
9910
  askInputSchema?: Record<string, unknown>;
9183
9911
  }
9184
9912
  export interface ToolOutputHooks<TOut = unknown> {
9185
- /** A source that fails \`sourceSchema\`, or a throw, is a \`sources_invalid\` warning and is not cited. */
9913
+ /**
9914
+ * The sources a result cites. One that fails sourceSchema, or a throw, is a sources_invalid
9915
+ * warning and is not cited.
9916
+ *
9917
+ * @remarks A source that fails \`sourceSchema\`, or a throw, is a \`sources_invalid\` warning and is
9918
+ * not cited.
9919
+ */
9186
9920
  sources?: (output: TOut) => Source[];
9187
9921
  }
9188
9922
  /** For a tool whose result names pictures by address; function tools return the bytes themselves as \`parts\`. */
9189
9923
  export interface ToolImageHooks<TOut = unknown> {
9190
9924
  /**
9191
- * The https addresses of pictures in \`output\` the model should see. After the result passes the
9192
- * output guard, the kernel fetches each one through the profile's network policy, without the
9193
- * tool's credentials, and hands the model the image as a part; one it cannot fetch is an
9194
- * \`images_unfetched\` warning, never a failed call.
9925
+ * The https addresses of pictures in the output the model should see. The kernel fetches each one
9926
+ * through the profile network policy, without the tool credentials.
9927
+ *
9928
+ * @remarks The https addresses of pictures in \`output\` the model should see. After the result
9929
+ * passes the output guard, the kernel fetches each one through the profile's network policy,
9930
+ * without the tool's credentials, and hands the model the image as a part; one it cannot fetch is
9931
+ * an \`images_unfetched\` warning, never a failed call.
9195
9932
  */
9196
9933
  images?: (output: TOut) => string[];
9197
- /** How many of those pictures the kernel fetches, how large, and how slowly. Left out, there is no limit. */
9934
+ /**
9935
+ * How many of those pictures the kernel fetches, how large, and how slowly.
9936
+ *
9937
+ * @remarks How many of those pictures the kernel fetches, how large, and how slowly. Left out,
9938
+ * there is no limit.
9939
+ */
9198
9940
  imageLimits?: ToolImageLimits;
9199
9941
  }
9200
9942
  /** Each limit left out is no limit. A picture past one is left out, not cut. */
@@ -9209,67 +9951,140 @@ export interface ToolImageLimits {
9209
9951
  timeoutMs?: number;
9210
9952
  }
9211
9953
  export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
9954
+ /** How the tool runs. */
9212
9955
  type: 'function';
9956
+ /** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
9213
9957
  input: z.ZodType<TIn>;
9958
+ /**
9959
+ * The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
9960
+ * not checked.
9961
+ */
9214
9962
  output: z.ZodType<TOut>;
9215
- /** Returns \`output\`'s type, or \`uncheckedOutput(value)\` for a value it cannot type. */
9963
+ /**
9964
+ * Your function that runs the tool; it can also yield progress as it goes.
9965
+ *
9966
+ * @remarks Returns \`output\`'s type, or \`uncheckedOutput(value)\` for a value it cannot type.
9967
+ */
9216
9968
  handler: ToolHandler<TIn, NoInfer<TOut>>;
9217
9969
  /**
9218
- * \`'page'\`: the page the person is on answers the call, and the kernel supplies the handler.
9219
- * \`output\` checks what the page sent.
9970
+ * Who answers a call to a function tool. With page, the page the agent is on returns the
9971
+ * output, and the tool has no handler.
9972
+ *
9973
+ * @remarks \`'page'\`: the page the person is on answers the call, and the kernel supplies the
9974
+ * handler. \`output\` checks what the page sent.
9220
9975
  */
9221
9976
  answeredBy?: 'page';
9222
9977
  /**
9223
- * The service the handler acts on for the person. The kernel resolves the slot
9224
- * before the handler runs (gating, refreshing, or telling the model as the policy
9225
- * says) and hands the handler \`ctx.signedInFetch\`; the handler never sees the credential.
9978
+ * How the tool gets its credential.
9979
+ *
9980
+ * @remarks The service the handler acts on for the person. The kernel resolves the slot before
9981
+ * the handler runs (gating, refreshing, or telling the model as the policy says) and hands the
9982
+ * handler \`ctx.signedInFetch\`; the handler never sees the credential.
9226
9983
  */
9227
9984
  auth?: ToolAuthConfig;
9228
9985
  }
9229
9986
  /** How a tool that acts for the person signs in to the service; http, mcp, and function tools share it. */
9230
9987
  export interface ToolAuthConfig {
9988
+ /** Which of the credentials the turn passes in this tool uses. */
9231
9989
  slot: string;
9990
+ /**
9991
+ * The kind of credential the tool expects, shown when a turn stops to ask for one; the header
9992
+ * follows the stored credential's own kind.
9993
+ */
9232
9994
  type: ToolAuthType;
9233
- /** The service the person signs in to, as they know it (e.g. "GitHub"); never blank. */
9995
+ /**
9996
+ * The service the person signs in to, as they know it, named when a turn stops to ask for a
9997
+ * credential.
9998
+ *
9999
+ * @remarks The service the person signs in to, as they know it (e.g. "GitHub"); never blank.
10000
+ */
9234
10001
  service: string;
10002
+ /** The header the credential goes in; an API key's own headerName comes first. */
9235
10003
  headerName?: string;
10004
+ /** Text put before the credential in the header; an API key's own headerPrefix comes first. */
9236
10005
  headerPrefix?: string;
9237
10006
  /**
9238
- * For a service that takes its API key in the URL (\`?key=…\`): the query parameter the key
9239
- * goes in, in place of a header. Only an \`api_key\` tool sets it, with no \`headerName\` or
10007
+ * For a service that takes its API key in the URL: the query parameter the key goes in, in place
10008
+ * of a header.
10009
+ *
10010
+ * @remarks For a service that takes its API key in the URL (\`?key=…\`): the query parameter the
10011
+ * key goes in, in place of a header. Only an \`api_key\` tool sets it, with no \`headerName\` or
9240
10012
  * \`headerPrefix\`.
9241
10013
  */
9242
10014
  queryParam?: string;
10015
+ /**
10016
+ * What happens when the credential is missing, expired, can't be refreshed or is refused by the
10017
+ * service.
10018
+ */
9243
10019
  onUnauthenticated?: AuthUnauthenticatedPolicy;
9244
- /** Named on the auth gate for the host's OAuth flow. */
10020
+ /**
10021
+ * Named on the auth gate for the host's OAuth flow, so it need not find them.
10022
+ *
10023
+ * @remarks Named on the auth gate for the host's OAuth flow.
10024
+ */
9245
10025
  preResolved?: Partial<OAuthEndpoints & {
9246
10026
  resource: string;
9247
10027
  }>;
10028
+ /**
10029
+ * The OAuth scopes the tool needs, shown when a turn stops to ask for a credential. A service
10030
+ * asking for any other scope fails the call, with no new sign-in.
10031
+ */
9248
10032
  scopes?: string[];
10033
+ /** Your OAuth client id, kept for the host's sign-in flow; the kernel doesn't read it. */
9249
10034
  clientId?: string;
10035
+ /** Your OAuth redirect URI, kept for the host's sign-in flow; the kernel doesn't read it. */
9250
10036
  redirectUri?: string;
9251
10037
  }
9252
10038
  export interface HttpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut>, ToolImageHooks<TOut> {
10039
+ /** How the tool runs. */
9253
10040
  type: 'http';
10041
+ /** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
9254
10042
  input: z.ZodType<TIn>;
10043
+ /**
10044
+ * The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
10045
+ * not checked.
10046
+ */
9255
10047
  output: z.ZodType<TOut>;
10048
+ /**
10049
+ * The URL the tool calls, with {name} placeholders for mapping.pathParams; the scheme and host
10050
+ * must be written out.
10051
+ */
9256
10052
  endpoint: string;
10053
+ /** The HTTP method; every method but GET sends a JSON body. */
9257
10054
  method: HttpMethod;
10055
+ /** Headers sent with every request to the tool's own origin, never once a redirect leaves it. */
9258
10056
  headers?: Record<string, string>;
10057
+ /** How the tool gets its credential. */
9259
10058
  auth?: ToolAuthConfig;
10059
+ /** Where each argument goes in the request. */
9260
10060
  mapping?: {
10061
+ /** Arguments that fill the {name} placeholders in the endpoint. */
9261
10062
  pathParams?: string[];
10063
+ /** Arguments added to the query string. */
9262
10064
  queryParams?: string[];
10065
+ /**
10066
+ * The one argument sent as the whole JSON body; without it, a method other than GET sends every
10067
+ * argument the path and query leave unused.
10068
+ */
9263
10069
  bodyParam?: string;
9264
10070
  };
9265
10071
  /** The service's own limit for one key; the kernel keeps this tool's requests within it. */
9266
10072
  limit?: HttpToolLimit;
9267
- /** The most of a response body the kernel reads; past it the call fails \`response_too_large\`. Left out, there is no limit. */
10073
+ /**
10074
+ * The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with
10075
+ * response_too_large.
10076
+ *
10077
+ * @remarks The most of a response body the kernel reads; past it the call fails
10078
+ * \`response_too_large\`. Left out, there is no limit.
10079
+ */
9268
10080
  maxResponseBytes?: number;
9269
10081
  /**
9270
- * How long the service may take to answer, its body read included. Past it the call
9271
- * fails \`timeout\` and frees its place in the limit. Left out, a call waits as long as
9272
- * the caller's signal lets it.
10082
+ * How long the service may take to answer, its body read included. Past it the call fails timeout
10083
+ * and frees its place in the limit.
10084
+ *
10085
+ * @remarks How long the service may take to answer, its body read included. Past it the call
10086
+ * fails \`timeout\` and frees its place in the limit. Left out, a call waits as long as the
10087
+ * caller's signal lets it.
9273
10088
  */
9274
10089
  timeoutMs?: number;
9275
10090
  }
@@ -9279,16 +10094,37 @@ export interface HttpToolLimit {
9279
10094
  windowMs: number;
9280
10095
  }
9281
10096
  export interface McpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut>, ToolImageHooks<TOut> {
10097
+ /** How the tool runs. */
9282
10098
  type: 'mcp';
10099
+ /** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
9283
10100
  input: z.ZodType<TIn>;
10101
+ /**
10102
+ * The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
10103
+ * not checked.
10104
+ */
9284
10105
  output: z.ZodType<TOut>;
10106
+ /** The MCP server's URL. */
9285
10107
  serverUrl: string;
10108
+ /** The tool's name on the MCP server. */
9286
10109
  mcpToolName: string;
10110
+ /** Headers sent with every request to the tool's own origin, never once a redirect leaves it. */
9287
10111
  headers?: Record<string, string>;
10112
+ /** How the tool gets its credential. */
9288
10113
  auth?: ToolAuthConfig;
9289
- /** The most of a response body the kernel reads; past it the call fails \`response_too_large\`. Left out, there is no limit. */
10114
+ /**
10115
+ * The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with
10116
+ * response_too_large.
10117
+ *
10118
+ * @remarks The most of a response body the kernel reads; past it the call fails
10119
+ * \`response_too_large\`. Left out, there is no limit.
10120
+ */
9290
10121
  maxResponseBytes?: number;
9291
- /** How long and how many of this tool's server sessions the kernel keeps. Left out, there is no limit. */
10122
+ /**
10123
+ * How long and how many of an MCP tool's server sessions the kernel keeps.
10124
+ *
10125
+ * @remarks How long and how many of this tool's server sessions the kernel keeps. Left out, there
10126
+ * is no limit.
10127
+ */
9292
10128
  session?: McpSessionLimits;
9293
10129
  }
9294
10130
  /** The sessions an MCP tool keeps: each field left out is no limit. */
@@ -9325,28 +10161,72 @@ export type AgentToolChannel = 'attachments' | 'voice' | 'options';
9325
10161
  * is what that profile's \`inputs\` declares; the host can reshape a call (\`onAgentCall\`).
9326
10162
  */
9327
10163
  export interface AgentToolDef extends ToolBase {
10164
+ /** How the tool runs. */
9328
10165
  type: 'agent';
9329
- /** A text, image, or speech profile, registered before this tool. Nothing it can call may gate. */
10166
+ /**
10167
+ * The profile this agent tool runs: text, image, or speech. Register it first. Nothing it calls
10168
+ * may stop on a gate.
10169
+ *
10170
+ * @remarks A text, image, or speech profile, registered before this tool. Nothing it can call may
10171
+ * gate.
10172
+ */
9330
10173
  profile: ProfileId;
9331
- /** Calls to this tool in one turn of its caller. Omit: only \`maxSteps\` bounds them. */
10174
+ /**
10175
+ * How many times one turn of the calling agent may run this tool.
10176
+ *
10177
+ * @remarks Calls to this tool in one turn of its caller. Omit: only \`maxSteps\` bounds them.
10178
+ */
9332
10179
  maxCallsPerTurn?: number;
9333
- /** What the calling model reads on a field of the tool's input, by field. A field the profile does not take is refused. */
10180
+ /**
10181
+ * What the calling model reads on a field of an agent tool input, such as text. A field the
10182
+ * profile does not take is refused when the tool registers.
10183
+ *
10184
+ * @remarks What the calling model reads on a field of the tool's input, by field. A field the
10185
+ * profile does not take is refused.
10186
+ */
9334
10187
  fieldText?: Partial<Record<keyof AgentToolInput, string>>;
9335
10188
  /**
9336
- * Fields the calling model fills that only the host reads. \`onAgentCall\` gets them as
9337
- * \`hostInput\` and turns them into the agent's input; they are never sent to the agent.
9338
- * A name the input already has is refused, and a call without the hook is a config error.
10189
+ * Fields the calling model fills on an agent tool that only the host reads. onAgentCall gets them
10190
+ * as hostInput and turns them into what the agent is sent; the agent never sees them. A name the
10191
+ * input already has is refused when the tool registers.
10192
+ *
10193
+ * @remarks Fields the calling model fills that only the host reads. \`onAgentCall\` gets them as
10194
+ * \`hostInput\` and turns them into the agent's input; they are never sent to the agent. A name the
10195
+ * input already has is refused, and a call without the hook is a config error.
9339
10196
  */
9340
10197
  hostFields?: Record<string, z.ZodType>;
9341
- /** Channels the profile takes that the calling model can't fill; only \`onAgentCall\` sends them. */
10198
+ /**
10199
+ * Channels the called profile takes that the calling model cannot fill on an agent tool; only
10200
+ * onAgentCall sends them. A channel the profile does not take is refused when the tool registers.
10201
+ *
10202
+ * @remarks Channels the profile takes that the calling model can't fill; only \`onAgentCall\` sends
10203
+ * them.
10204
+ */
9342
10205
  hostOnly?: AgentToolChannel[];
10206
+ /** Runs before the host's pre_tool onStage. */
9343
10207
  preTool?: ToolHostHooks<AgentToolInput>['preTool'];
10208
+ /**
10209
+ * Gives the model an after field on this tool: the tools called in the same step that must settle
10210
+ * before this call starts. The kernel removes the field before the tool, the stages or a gate
10211
+ * read the input. A name with no other call in the step fails the call wait_unknown.
10212
+ */
9344
10213
  after?: ToolHostHooks<AgentToolInput>['after'];
10214
+ /**
10215
+ * When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }:
10216
+ * once the body has run past this time. 'ask': at the hand-off if the model sets the background
10217
+ * argument. A turn with no background service runs the tool inline.
10218
+ */
9345
10219
  background?: ToolHostHooks<AgentToolInput>['background'];
10220
+ /** Whether the model can see and call the tool. */
9346
10221
  exposeToModel?: boolean;
9347
10222
  }
9348
10223
  export interface RegisteredAgentTool extends AgentToolDef, ToolHostHooks<AgentToolInput>, ToolOutputHooks<AgentToolOutput> {
10224
+ /** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
9349
10225
  input: z.ZodType<AgentToolInput>;
10226
+ /**
10227
+ * The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
10228
+ * not checked.
10229
+ */
9350
10230
  output: z.ZodType<AgentToolOutput>;
9351
10231
  }
9352
10232
  /** An agent tool call, as the host's \`onAgentCall\` sees it before the agent runs. */
@@ -9388,20 +10268,45 @@ export type AgentCallHook = (call: AgentCall) => AgentCallRequest | {
9388
10268
  export type RegisteredTool<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolDef<TIn, TOut> | HttpToolDef<TIn, TOut> | McpToolDef<TIn, TOut> | RegisteredAgentTool;
9389
10269
  /** A function tool as registered: it has a \`handler\`, or the page answers it. */
9390
10270
  export type FunctionToolInput<TIn = unknown, TOut = unknown> = Omit<FunctionToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema' | 'handler' | 'answeredBy'> & {
10271
+ /** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
9391
10272
  input: z.ZodType<TIn>;
10273
+ /**
10274
+ * The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
10275
+ * not checked.
10276
+ */
9392
10277
  output: z.ZodType<TOut>;
9393
10278
  } & ({
10279
+ /** Your function that runs the tool; it can also yield progress as it goes. */
9394
10280
  handler: ToolHandler<TIn, NoInfer<TOut>>;
10281
+ /**
10282
+ * Who answers a call to a function tool. With page, the page the agent is on returns the
10283
+ * output, and the tool has no handler.
10284
+ */
9395
10285
  answeredBy?: 'page';
9396
10286
  } | {
10287
+ /**
10288
+ * Who answers a call to a function tool. With page, the page the agent is on returns the
10289
+ * output, and the tool has no handler.
10290
+ */
9397
10291
  answeredBy: 'page';
10292
+ /** Your function that runs the tool; it can also yield progress as it goes. */
9398
10293
  handler?: undefined;
9399
10294
  });
9400
10295
  export type ToolDefinitionInput<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolInput<TIn, TOut> | (Omit<HttpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
10296
+ /** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
9401
10297
  input: z.ZodType<TIn>;
10298
+ /**
10299
+ * The Zod schema every result the tool returns must match; the kernel's own not-signed-in
10300
+ * note is not checked.
10301
+ */
9402
10302
  output: z.ZodType<TOut>;
9403
10303
  }) | (Omit<McpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
10304
+ /** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
9404
10305
  input: z.ZodType<TIn>;
10306
+ /**
10307
+ * The Zod schema every result the tool returns must match; the kernel's own not-signed-in
10308
+ * note is not checked.
10309
+ */
9405
10310
  output: z.ZodType<TOut>;
9406
10311
  }) | AgentToolDef;
9407
10312
  export interface PromoteLoadedResult {
@@ -9484,37 +10389,77 @@ export interface InvokeToolStepRequest extends Omit<InvokeToolRequest, 'name' |
9484
10389
  }
9485
10390
  /** The tools a profile may use and how they load. */
9486
10391
  export interface ProfileToolsSpec {
9487
- /** Custom tools only; builtins live on \`models.*.builtInTools\`. */
10392
+ /**
10393
+ * Your registered tools this agent may use; the provider's own tools go on the model's
10394
+ * builtInTools instead.
10395
+ *
10396
+ * @remarks Custom tools only; builtins live on \`models.*.builtInTools\`.
10397
+ */
9488
10398
  allow: ToolId[];
9489
- /** Returns ids already allowed with \`loadTier: 'T2'\` to load at turn start. Not supported on \`type: 'live'\`. */
10399
+ /**
10400
+ * Your function that picks, at the start of each turn, which T2 tools to load up front; the rest
10401
+ * wait for tools.t2Loader.
10402
+ *
10403
+ * @remarks Returns ids already allowed with \`loadTier: 'T2'\` to load at turn start. Not supported
10404
+ * on \`type: 'live'\`.
10405
+ */
9490
10406
  t1Policy?: ToolPolicy;
9491
10407
  /**
9492
- * Must be in \`allow\`; completing with \`{ loaded: string[] }\` promotes those T2 ids. Not on \`type: 'live'\`.
9493
- * The tools it loads can be called from the next step.
10408
+ * The function tool that loads T2 tools. It must be in allow and return { loaded: ToolId[] }. One
10409
+ * forbidden id fails the load. Ids off the turn path are skipped. The tools it loads can be
10410
+ * called from the next step: a step's calls see the tools as they stood when the step began.
10411
+ *
10412
+ * @remarks Must be in \`allow\`; completing with \`{ loaded: string[] }\` promotes those T2 ids. Not
10413
+ * on \`type: 'live'\`. The tools it loads can be called from the next step.
9494
10414
  */
9495
10415
  t2Loader?: ToolId;
9496
10416
  /**
9497
- * \`true\`: a step's calls run side by side, each body starting once the calls its \`pre_tool\`
9498
- * \`waitFor\` names have settled. Left out or \`false\`: one at a time, in the order the model made them.
10417
+ * true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
10418
+ * its body once those calls settle. Left out or false: they run one at a time, in the order the
10419
+ * model made them. A step is the calls the model makes together in a turn, or the calls a host
10420
+ * runs through invokeToolStep.
10421
+ *
10422
+ * @remarks \`true\`: a step's calls run side by side, each body starting once the calls its
10423
+ * \`pre_tool\` \`waitFor\` names have settled. Left out or \`false\`: one at a time, in the order the
10424
+ * model made them.
9499
10425
  */
9500
10426
  parallel?: boolean;
9501
10427
  }
9502
10428
  /** Live declarations cannot be added mid-session, so every allowed tool is wired at setup as if T0. */
9503
10429
  export interface LiveProfileToolsSpec {
10430
+ /**
10431
+ * Your registered tools this agent may use; the provider's own tools go on the model's
10432
+ * builtInTools instead.
10433
+ */
9504
10434
  allow: ToolId[];
9505
10435
  /**
9506
- * \`true\`: the calls of one model message, run as a step through \`invokeToolStep\`, run side by
9507
- * side, each body starting once the calls its \`pre_tool\` \`waitFor\` names have settled. Left out
9508
- * or \`false\`: one at a time, in the order the model made them.
10436
+ * true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
10437
+ * its body once those calls settle. Left out or false: they run one at a time, in the order the
10438
+ * model made them. A step is the calls the model makes together in a turn, or the calls a host
10439
+ * runs through invokeToolStep.
10440
+ *
10441
+ * @remarks \`true\`: the calls of one model message, run as a step through \`invokeToolStep\`, run
10442
+ * side by side, each body starting once the calls its \`pre_tool\` \`waitFor\` names have settled.
10443
+ * Left out or \`false\`: one at a time, in the order the model made them.
9509
10444
  */
9510
10445
  parallel?: boolean;
9511
10446
  }
9512
10447
  /** Every id in \`allow\` is invokable with no visibility tiers and no path gating. */
9513
10448
  export interface HostProfileToolsSpec {
10449
+ /**
10450
+ * Your registered tools this agent may use; the provider's own tools go on the model's
10451
+ * builtInTools instead.
10452
+ */
9514
10453
  allow: ToolId[];
9515
10454
  /**
9516
- * \`true\`: the calls of one \`invokeToolStep\` run side by side, each body starting once the calls
9517
- * its \`pre_tool\` \`waitFor\` names have settled. Left out or \`false\`: one at a time, in the order given.
10455
+ * true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
10456
+ * its body once those calls settle. Left out or false: they run one at a time, in the order the
10457
+ * model made them. A step is the calls the model makes together in a turn, or the calls a host
10458
+ * runs through invokeToolStep.
10459
+ *
10460
+ * @remarks \`true\`: the calls of one \`invokeToolStep\` run side by side, each body starting once
10461
+ * the calls its \`pre_tool\` \`waitFor\` names have settled. Left out or \`false\`: one at a time, in
10462
+ * the order given.
9518
10463
  */
9519
10464
  parallel?: boolean;
9520
10465
  }
@@ -9875,6 +10820,10 @@ import { type ToolCallBase } from './events.js';
9875
10820
  import { type ToolExecutionCoordinator, type ToolOperationReply } from './operation.js';
9876
10821
  /** When the model gets its reply: at the hand-off, past a time, if it asks, or when the body ends. */
9877
10822
  export type ToolBackground = 'always' | {
10823
+ /**
10824
+ * Milliseconds the body runs before the model gets its reply. A body that ends sooner answers
10825
+ * in the turn.
10826
+ */
9878
10827
  afterMs: number;
9879
10828
  } | 'ask' | 'never';
9880
10829
  /** The call a detached event belongs to. */
@@ -10604,7 +11553,11 @@ export { toOtlpJson };
10604
11553
  `,"file:///node_modules/@theoremjs/agents/src/observability/destinations.d.ts":`import type { TraceSink } from './trace-sink.js';
10605
11554
  /** True when the value is a trace sink. */
10606
11555
  declare function isTraceSink(value: unknown): value is TraceSink;
10607
- /** Register a trace sink under an id; throws when the id is empty. */
11556
+ /**
11557
+ * Stores a place to write traces under an id, so that a profile can name it in observability.
11558
+ *
11559
+ * @remarks Register a trace sink under an id; throws when the id is empty.
11560
+ */
10608
11561
  declare function registerTraceDestination(id: string, destination: TraceSink): void;
10609
11562
  /** The sink registered under the id, or \`undefined\`. */
10610
11563
  declare function getTraceDestination(id: string): TraceSink | undefined;
@@ -10711,89 +11664,238 @@ import type { DecisionModelBinding, DecisionProfile, EmbeddingProfile, HostProfi
10711
11664
  import type { SchemaRegistry } from './schemas.js';
10712
11665
  /** Not shared by host profiles, which invoke tools without a model turn. */
10713
11666
  export type ProfileDefinitionBase = {
11667
+ /**
11668
+ * The name this profile is registered and looked up by, at most 64 characters; registering the
11669
+ * same id again replaces it.
11670
+ */
10714
11671
  id: Profile['id'];
11672
+ /** The agent's display name and the system instruction it is given. */
10715
11673
  identity: ProfileIdentity;
11674
+ /**
11675
+ * The trained AI systems that turn input into results. Each entry binds a local name to an
11676
+ * upstream model and its call settings.
11677
+ *
11678
+ * @catalog models.* One model: how to reach it and the settings sent with it.
11679
+ */
10716
11680
  models: Record<ModelId, ModelBinding>;
11681
+ /** Who holds the conversation a saved provider state continues. */
10717
11682
  providerContinuation?: import('../checkpoint.js').ProviderContinuationPolicy;
11683
+ /** The model a turn gets when it doesn't pick one. */
10718
11684
  defaultModel?: ModelId;
11685
+ /** Lets a turn name the model it runs on; a name the profile does not declare is refused. */
10719
11686
  allowModelSelect?: boolean;
11687
+ /**
11688
+ * The most model calls one turn may make while using tools, counted afresh for each rewrite; 1
11689
+ * runs the tools asked for but never sends their results back. Live sessions ignore it.
11690
+ */
10720
11691
  maxSteps?: number;
11692
+ /** The shape of the reply, how it is checked, and how it streams. */
10721
11693
  outputs?: ProfileOutputsSpec;
11694
+ /**
11695
+ * Theorem checks what enters or leaves an agent’s context and generation against built-in or
11696
+ * custom rules at each configured boundary.
11697
+ */
10722
11698
  guardrails?: ProfileGuardrailsSpec;
11699
+ /** Where this profile's traces go and what they keep. */
10723
11700
  observability?: ProfileObservabilitySpec;
11701
+ /**
11702
+ * This profile's own wording for error lines, notices, and notes to the model, by labels key.
11703
+ *
11704
+ * @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
11705
+ */
10724
11706
  labels?: LabelOverrides;
10725
11707
  };
10726
11708
  /** What a host writes to define an embedding profile. */
10727
11709
  export type EmbeddingProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'outputs' | 'maxSteps'> & {
11710
+ /**
11711
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11712
+ * transcription, live, decision, embedding, or host.
11713
+ */
10728
11714
  type: 'embedding';
11715
+ /** The agent's display name and the system instruction it is given. */
10729
11716
  identity: Pick<ProfileIdentity, 'handle'>;
11717
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
10730
11718
  inputs: EmbeddingProfile['inputs'];
10731
11719
  };
10732
11720
  /** What a host writes to define a text profile. */
10733
11721
  export type TextProfileDefinition = ProfileDefinitionBase & {
11722
+ /**
11723
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11724
+ * transcription, live, decision, embedding, or host.
11725
+ */
10734
11726
  type: 'text';
11727
+ /**
11728
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
11729
+ */
10735
11730
  tools: ProfileToolsSpec;
11731
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
10736
11732
  inputs: ProfileInputsSpec;
11733
+ /**
11734
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
11735
+ */
10737
11736
  turnBehaviour?: ProfileTurnBehaviourSpec;
10738
11737
  };
10739
11738
  /** What a host writes to define an image profile. */
10740
11739
  export type ImageProfileDefinition = ProfileDefinitionBase & {
11740
+ /**
11741
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11742
+ * transcription, live, decision, embedding, or host.
11743
+ */
10741
11744
  type: 'image';
11745
+ /**
11746
+ * How the images this profile generates are shaped and made: size, format, quality and
11747
+ * references. Each setting is sent only where the provider has it; one it lacks is refused or
11748
+ * ignored, as that setting says.
11749
+ */
10742
11750
  image: NonNullable<ImageProfile['image']>;
11751
+ /**
11752
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
11753
+ */
10743
11754
  tools: ProfileToolsSpec;
11755
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
10744
11756
  inputs: ImageInputsSpec;
11757
+ /**
11758
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
11759
+ */
10745
11760
  turnBehaviour?: MediaTurnBehaviourSpec;
10746
11761
  };
10747
11762
  /** What a host writes to define a speech profile. */
10748
11763
  export type SpeechProfileDefinition = Omit<ProfileDefinitionBase, 'identity'> & {
11764
+ /**
11765
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11766
+ * transcription, live, decision, embedding, or host.
11767
+ */
10749
11768
  type: 'speech';
11769
+ /** The agent's display name and the system instruction it is given. */
10750
11770
  identity: SpeechProfile['identity'];
11771
+ /**
11772
+ * How the profile's speech sounds and is delivered: voice, style, speed and audio format. A turn
11773
+ * may replace voice, style and speed for that turn.
11774
+ */
10751
11775
  speech: NonNullable<SpeechProfile['speech']>;
11776
+ /**
11777
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
11778
+ */
10752
11779
  turnBehaviour?: MediaTurnBehaviourSpec;
10753
11780
  };
10754
11781
  /** What a host writes to define a transcription profile. */
10755
11782
  export type TranscriptionProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'outputs' | 'maxSteps'> & {
11783
+ /**
11784
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11785
+ * transcription, live, decision, embedding, or host.
11786
+ */
10756
11787
  type: 'transcription';
11788
+ /** The agent's display name and the system instruction it is given. */
10757
11789
  identity: TranscriptionProfile['identity'];
11790
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
10758
11791
  inputs: TranscriptionInputsSpec & {
10759
- text?: false;
11792
+ /** Whether a turn may send text. */ text?: false;
10760
11793
  };
10761
11794
  };
10762
11795
  /** What a host writes to define a live profile. */
10763
11796
  export type LiveProfileDefinition = Omit<ProfileDefinitionBase, 'maxSteps'> & {
11797
+ /**
11798
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11799
+ * transcription, live, decision, embedding, or host.
11800
+ */
10764
11801
  type: 'live';
11802
+ /**
11803
+ * How a realtime voice and video session runs: what it accepts from the user, the voice it
11804
+ * answers in, when it hears the user start and stop, and how it resumes and trims its context.
11805
+ */
10765
11806
  live: NonNullable<LiveProfile['live']>;
11807
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
10766
11808
  inputs?: LiveProfile['inputs'];
11809
+ /**
11810
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
11811
+ */
10767
11812
  tools: LiveProfileToolsSpec;
10768
- /** Inject gate only — resumption is \`live.sessionResumption\`. */
11813
+ /**
11814
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
11815
+ *
11816
+ * @remarks Inject gate only — resumption is \`live.sessionResumption\`.
11817
+ */
10769
11818
  turnBehaviour?: Pick<ProfileTurnBehaviourSpec, 'allowSteering'>;
10770
11819
  };
10771
11820
  /** What a host writes to define a decision profile. */
10772
11821
  export type DecisionProfileDefinition = {
11822
+ /**
11823
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11824
+ * transcription, live, decision, embedding, or host.
11825
+ */
10773
11826
  type: 'decision';
11827
+ /**
11828
+ * The name this profile is registered and looked up by, at most 64 characters; registering the
11829
+ * same id again replaces it.
11830
+ */
10774
11831
  id: Profile['id'];
11832
+ /** The agent's display name and the system instruction it is given. */
10775
11833
  identity: Pick<ProfileIdentity, 'handle'>;
10776
- /** Exactly one model. */
11834
+ /**
11835
+ * The trained AI systems that turn input into results. Each entry binds a local name to an
11836
+ * upstream model and its call settings.
11837
+ *
11838
+ * @remarks Exactly one model.
11839
+ * @catalog models.* One model: how to reach it and the settings sent with it.
11840
+ */
10777
11841
  models: Record<ModelId, DecisionModelBinding>;
11842
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
10778
11843
  inputs: DecisionProfile['inputs'];
11844
+ /** Names the host decision this profile makes. */
10779
11845
  decision: DecisionProfile['decision'];
11846
+ /**
11847
+ * Theorem checks what enters or leaves an agent’s context and generation against built-in or
11848
+ * custom rules at each configured boundary.
11849
+ */
10780
11850
  guardrails?: DecisionGuardrailsSpec;
11851
+ /** Where this profile's traces go and what they keep. */
10781
11852
  observability?: ProfileObservabilitySpec;
11853
+ /**
11854
+ * This profile's own wording for error lines, notices, and notes to the model, by labels key.
11855
+ *
11856
+ * @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
11857
+ */
10782
11858
  labels?: LabelOverrides;
10783
11859
  };
10784
11860
  /** What a host writes to define a host profile, which runs tools and no model. */
10785
11861
  export type HostProfileDefinition = {
11862
+ /**
11863
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
11864
+ * transcription, live, decision, embedding, or host.
11865
+ */
10786
11866
  type: 'host';
11867
+ /**
11868
+ * The name this profile is registered and looked up by, at most 64 characters; registering the
11869
+ * same id again replaces it.
11870
+ */
10787
11871
  id: Profile['id'];
11872
+ /**
11873
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
11874
+ */
10788
11875
  tools: HostProfileToolsSpec;
10789
- /** Only the guards that fire on the \`invokeTool\` path. */
11876
+ /**
11877
+ * Theorem checks what enters or leaves an agent’s context and generation against built-in or
11878
+ * custom rules at each configured boundary.
11879
+ *
11880
+ * @remarks Only the guards that fire on the \`invokeTool\` path.
11881
+ */
10790
11882
  guardrails?: HostGuardrailsSpec;
11883
+ /** Where this profile's traces go and what they keep. */
10791
11884
  observability?: ProfileObservabilitySpec;
11885
+ /**
11886
+ * This profile's own wording for error lines, notices, and notes to the model, by labels key.
11887
+ *
11888
+ * @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
11889
+ */
10792
11890
  labels?: LabelOverrides;
10793
11891
  };
10794
11892
  /** Any profile definition, discriminated by \`type\`. */
10795
11893
  export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | DecisionProfileDefinition | TranscriptionProfileDefinition | EmbeddingProfileDefinition | HostProfileDefinition;
10796
- /** Validate a definition and return the profile; throws on a malformed one. */
11894
+ /**
11895
+ * Checks a profile and returns it; a field the profile type cannot take is a config error.
11896
+ *
11897
+ * @remarks Validate a definition and return the profile; throws on a malformed one.
11898
+ */
10797
11899
  declare function defineProfile(input: TextProfileDefinition): TextProfile;
10798
11900
  /** Validate an image definition and return the profile. */
10799
11901
  declare function defineProfile(input: ImageProfileDefinition): ImageProfile;
@@ -12313,7 +13415,11 @@ import { defaultKernelScope as scope } from './scope.js';
12313
13415
  import type { ToolCallResult, ToolStepCallResult } from './tools/run.js';
12314
13416
  import type { InvokeToolRequest, InvokeToolStepRequest, RegisteredTool, ToolDefinitionInput } from './tools/types.js';
12315
13417
  import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, EmbeddingRequest, EmbeddingResult, LiveSession, Profile, ProjectedProfile, SessionRequest, StructuredSpec, TurnEvent, TurnRequest } from './types.js';
12316
- /** Register or replace a tool in the default scope. */
13418
+ /**
13419
+ * Stores a tool under its name, so that a profile can list it in tools.allow.
13420
+ *
13421
+ * @remarks Register or replace a tool in the default scope.
13422
+ */
12317
13423
  declare function registerTool<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
12318
13424
  /** Register or replace several tools in the default scope. */
12319
13425
  declare function registerTools(defs: ToolDefinitionInput[]): RegisteredTool[];
@@ -12327,7 +13433,11 @@ declare function hasTool(name: string): boolean;
12327
13433
  declare function listTools(): RegisteredTool[];
12328
13434
  /** Remove every tool from the default scope. */
12329
13435
  declare function resetTools(): void;
12330
- /** Define, validate, and register a profile in the default scope. */
13436
+ /**
13437
+ * Stores a profile under its id, so that a request can name it.
13438
+ *
13439
+ * @remarks Define, validate, and register a profile in the default scope.
13440
+ */
12331
13441
  declare function registerProfile(profile: Profile | ProfileDefinition): void;
12332
13442
  /** Define, validate, and register several profiles in the default scope. */
12333
13443
  declare function registerProfiles(profiles: Array<Profile | ProfileDefinition>): void;
@@ -12339,21 +13449,47 @@ declare function hasProfile(id: string): boolean;
12339
13449
  declare function listProfiles(): Profile[];
12340
13450
  /** Remove every profile from the default scope. */
12341
13451
  declare function clearProfiles(): void;
12342
- /** Register a structured-output schema in the default scope under \`id\`. */
13452
+ /**
13453
+ * Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.
13454
+ *
13455
+ * @remarks Register a structured-output schema in the default scope under \`id\`.
13456
+ */
12343
13457
  declare function registerStructured(id: string, spec: StructuredSpec): void;
12344
13458
  /** The default scope's schema \`id\`; throws when there is none. */
12345
13459
  declare function getStructured(id: string): StructuredSpec;
12346
- /** Run one turn of a profile in the default scope, streaming its events. */
13460
+ /**
13461
+ * Runs one turn of a text, image, or speech profile and yields its events.
13462
+ *
13463
+ * @remarks Run one turn of a profile in the default scope, streaming its events.
13464
+ */
12347
13465
  declare function runTurn(req: TurnRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
12348
- /** Open a live session for a live profile in the default scope. */
13466
+ /**
13467
+ * Runs a realtime voice or video session of a live profile.
13468
+ *
13469
+ * @remarks Open a live session for a live profile in the default scope.
13470
+ */
12349
13471
  declare function runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
12350
- /** Compact a conversation history with the model, or \`undefined\` when there is nothing to compact. */
13472
+ /**
13473
+ * Shortens a conversation history with the compaction the profile sets.
13474
+ *
13475
+ * @remarks Compact a conversation history with the model, or \`undefined\` when there is nothing to
13476
+ * compact.
13477
+ */
12351
13478
  declare function compactHistory(req: CompactHistoryRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
12352
- /** Run a held tool call in the default scope, streaming the events of the turn it resumes. */
13479
+ /**
13480
+ * Runs one registered tool through a profile, with no model.
13481
+ *
13482
+ * @remarks Run a held tool call in the default scope, streaming the events of the turn it resumes.
13483
+ */
12353
13484
  declare function invokeTool(request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
12354
13485
  /** Run the host's calls as one step in the default scope, streaming each call's events as they come. */
12355
13486
  declare function invokeToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
12356
- /** Run one tool call in the default scope to its end: how it settled, with every event it emitted. */
13487
+ /**
13488
+ * Runs one registered tool through a profile, with no model, and returns how the call settled.
13489
+ *
13490
+ * @remarks Run one tool call in the default scope to its end: how it settled, with every event it
13491
+ * emitted.
13492
+ */
12357
13493
  declare function runTool(request: InvokeToolRequest, sinkOverride?: TraceSink): Promise<ToolCallResult>;
12358
13494
  /** Run the host's calls as one step in the default scope, giving each call's end as it settles. */
12359
13495
  declare function runToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<ToolStepCallResult>;
@@ -12362,12 +13498,20 @@ declare function resolveTurn(req: TurnRequest): ReturnType<typeof scope.resolveT
12362
13498
  /** Each model of profile \`id\` in the default scope that cannot run a plain turn on its provider, and why. */
12363
13499
  /** The profile \`id\` projected for a client, with server-only fields removed. */
12364
13500
  declare function projectProfile(id: string): ProjectedProfile;
12365
- /** Answer a decision request with the profile's model in the default scope. */
13501
+ /**
13502
+ * Asks a decision profile its questions about your JSON state and returns checked answers.
13503
+ *
13504
+ * @remarks Answer a decision request with the profile's model in the default scope.
13505
+ */
12366
13506
  declare function runDecision(request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
12367
13507
  /** Create vectors for one or more inputs in the default scope. */
12368
13508
  declare function runEmbedding(request: EmbeddingRequest, options?: RunEmbeddingOptions): Promise<EmbeddingResult>;
12369
13509
  export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTool, runToolStep, runTurn, };
12370
- /** Registers a provider in the default scope, with this project's connection and key slots. */
13510
+ /**
13511
+ * Registers a provider instance before profiles reference its ID.
13512
+ *
13513
+ * @remarks Registers a provider in the default scope, with this project's connection and key slots.
13514
+ */
12371
13515
  export declare function registerProvider<C, K>(provider: Provider<C, K>, registration?: Registration<C>): RegisteredProvider;
12372
13516
  export declare function getProvider(id: string): RegisteredProvider | undefined;
12373
13517
  export declare function listProviders(): RegisteredProvider[];
@@ -12422,11 +13566,17 @@ declare function skipQuota(peer: string, req: Request): boolean;
12422
13566
  /** Resolves the client identity, preferring Cloudflare's header for local peers. */
12423
13567
  declare function clientIp(peer: string, req: Request): string;
12424
13568
  /**
12425
- * Reserves one profile-and-client daily quota slot. The reservation stays busy
12426
- * until \`releaseSlot\` is called, preventing concurrent turns from overspending.
13569
+ * Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.
13570
+ *
13571
+ * @remarks Reserves one profile-and-client daily quota slot. The reservation stays busy until
13572
+ * \`releaseSlot\` is called, preventing concurrent turns from overspending.
12427
13573
  */
12428
13574
  declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus;
12429
- /** Releases an active quota reservation without decrementing its daily count. */
13575
+ /**
13576
+ * Frees the turn slot that takeSlot gave.
13577
+ *
13578
+ * @remarks Releases an active quota reservation without decrementing its daily count.
13579
+ */
12430
13580
  declare function releaseSlot(profile: Profile, ip: string): void;
12431
13581
  /** \`undefined\` when the profile has no quota configured. */
12432
13582
  declare function quotaExhausted(profile: Profile): TheoremError | undefined;