@theoremjs/agents 0.3.4-next.855.gc82d4ec → 0.3.4-next.869.gb64db05

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/esm/src/guardrails/detectors.d.ts +91 -21
  2. package/esm/src/guardrails/host-patterns.d.ts +15 -2
  3. package/esm/src/guardrails/labels.d.ts +11 -3
  4. package/esm/src/guardrails/labels.js +42 -23
  5. package/esm/src/guardrails/quota.d.ts +9 -3
  6. package/esm/src/guardrails/quota.js +9 -3
  7. package/esm/src/guardrails/theorem-error.d.ts +5 -1
  8. package/esm/src/guardrails/theorem-error.js +8 -4
  9. package/esm/src/guardrails/types.d.ts +66 -18
  10. package/esm/src/guardrails/types.js +22 -3
  11. package/esm/src/kernel/api-catalog.d.ts +26 -75
  12. package/esm/src/kernel/api-catalog.js +37 -119
  13. package/esm/src/kernel/checkpoint.d.ts +5 -1
  14. package/esm/src/kernel/default-scope.d.ts +52 -10
  15. package/esm/src/kernel/default-scope.js +52 -10
  16. package/esm/src/kernel/engine/runner/gates.js +66 -22
  17. package/esm/src/kernel/engine/runner/state.d.ts +5 -2
  18. package/esm/src/kernel/engine/runner/steps.js +15 -15
  19. package/esm/src/kernel/engine/runner/stream.d.ts +5 -0
  20. package/esm/src/kernel/engine/runner/stream.js +12 -1
  21. package/esm/src/kernel/field-docs.d.ts +13 -0
  22. package/esm/src/kernel/field-docs.js +613 -0
  23. package/esm/src/kernel/protocols/binding.d.ts +56 -0
  24. package/esm/src/kernel/protocols/limits.d.ts +9 -0
  25. package/esm/src/kernel/protocols/provider.d.ts +5 -1
  26. package/esm/src/kernel/protocols/provider.js +5 -1
  27. package/esm/src/kernel/registry/profiles.d.ts +154 -5
  28. package/esm/src/kernel/schema.d.ts +5 -7
  29. package/esm/src/kernel/schema.js +511 -470
  30. package/esm/src/kernel/stop.d.ts +41 -17
  31. package/esm/src/kernel/stop.js +9 -1
  32. package/esm/src/kernel/tools/background.d.ts +4 -0
  33. package/esm/src/kernel/tools/types.d.ts +331 -43
  34. package/esm/src/kernel/turn-events.d.ts +4 -3
  35. package/esm/src/kernel/types.d.ts +482 -89
  36. package/esm/src/observability/destinations.d.ts +5 -1
  37. package/esm/src/observability/destinations.js +5 -1
  38. package/esm/src/observability/trace-catalog.js +62 -102
  39. package/esm/src/observability/types.d.ts +93 -19
  40. package/esm/src/providers/shared/carried-tool-files.js +9 -8
  41. package/package.json +1 -1
@@ -34,16 +34,43 @@ export type ProfileId = string;
34
34
  export type ChatRole = 'system' | 'user' | 'assistant';
35
35
  /** Host strings (presets own the vocabularies); an unpinned value is the provider default. */
36
36
  export interface ProfileImageSpec {
37
+ /** The shape of generated images, such as 16:9. */
37
38
  aspectRatio?: string;
39
+ /** How detailed generated images are, such as 1K, 2K or 4K. */
38
40
  resolution?: string;
41
+ /**
42
+ * The file type of generated images; a provider that takes a fixed set of types may use png for
43
+ * any other.
44
+ */
39
45
  mimeType?: string;
46
+ /**
47
+ * How much effort the model spends on each image: auto, low, medium, or high. A provider that has
48
+ * no such setting refuses it.
49
+ */
40
50
  quality?: string;
51
+ /**
52
+ * The background of generated images: auto, transparent, or opaque. A provider that has no such
53
+ * setting refuses it.
54
+ */
41
55
  background?: string;
56
+ /** How many images one request makes, where the provider takes a count. */
42
57
  n?: number;
58
+ /** A seed for repeatable images, where the provider and the model honour it. */
43
59
  seed?: number;
60
+ /** Compression from 0 to 100 for jpeg and webp images, where the provider takes it. */
44
61
  outputCompression?: number;
62
+ /**
63
+ * Images sent with every turn, before the user's. Each is bytes (`data`) or a link (`uri`). Some
64
+ * providers take http(s) links only, and none with includeText.
65
+ */
45
66
  references?: Array<TurnBlob | TurnMediaRef>;
46
- /** Also request interleaved text with the images (Google: text + image `response_format`). */
67
+ /**
68
+ * Whether the model may write text alongside its images; with some providers this also sends the
69
+ * system instruction and history.
70
+ *
71
+ * @remarks Also request interleaved text with the images (Google: text + image
72
+ * `response_format`).
73
+ */
47
74
  includeText?: boolean;
48
75
  }
49
76
  import type { DecisionModelBinding, ModelBinding } from './protocols/binding.js';
@@ -72,60 +99,110 @@ export interface CompactionTriggerContext {
72
99
  /** When history compacts and how: the meter, the token budget, and the compactor. */
73
100
  export interface CompactionSpec {
74
101
  /**
75
- * Token budget compared by the trigger (`compactAt * maxTokens`).
76
- * Meaning depends on `meter`: history budget vs full-prompt input budget.
102
+ * The token budget compactAt is a fraction of.
103
+ *
104
+ * @remarks Token budget compared by the trigger (`compactAt * maxTokens`). Meaning depends on
105
+ * `meter`: history budget vs full-prompt input budget.
77
106
  */
78
107
  maxTokens: number;
79
- /** Fraction of `maxTokens` at which compaction fires. Must be in (0, 1). */
108
+ /**
109
+ * The fraction of maxTokens, between 0 and 1, at which compaction starts, unless trigger decides.
110
+ *
111
+ * @remarks Fraction of `maxTokens` at which compaction fires. Must be in (0, 1).
112
+ */
80
113
  compactAt: number;
81
114
  /**
82
- * Recent exchanges kept verbatim (an exchange is a user message and everything up to the
115
+ * How much recent history compaction keeps: a number of exchanges (1 or more), a fraction of
116
+ * maxTokens below compactAt, or 0 to compact it all.
117
+ *
118
+ * @remarks Recent exchanges kept verbatim (an exchange is a user message and everything up to the
83
119
  * next one). `≥ 1` = exchange count, `(0, 1)` = fraction of `maxTokens`, `0` = compact all.
84
120
  */
85
121
  previousExchanges: number;
86
122
  /**
87
- * Profile id of the compaction agent. Must be registered before the owning profile.
88
- * Omit it and the agent compacts its own history: the same instructions and model, no tools.
123
+ * The text profile that writes the summary; register it before this one. Leave it out and a text
124
+ * agent summarises its own history, with its own instructions and model and no tools. Its
125
+ * registered model binding selects the provider independently of the calling agent.
126
+ *
127
+ * @remarks Profile id of the compaction agent. Must be registered before the owning profile. Omit
128
+ * it and the agent compacts its own history: the same instructions and model, no tools.
89
129
  */
90
130
  profile?: ProfileId;
91
131
  /**
92
- * When compaction runs relative to the primary turn.
132
+ * Whether the kernel compacts before the turn or tells the host to compact after it.
133
+ *
134
+ * @remarks When compaction runs relative to the primary turn.
93
135
  * - `'before'`: kernel compacts synchronously before the turn; user pays latency on this turn.
94
136
  * - `'after'`: kernel signals in the `done` event; host runs compaction asynchronously.
95
137
  */
96
138
  timing: CompactionTiming;
97
139
  /**
98
- * Threshold meter. Defaults to `'history'`.
99
- * Use `'input'` when the host prefers provider full-prompt usage (after
100
- * subtracting a known baseline in `maxTokens` / `compactAt`).
140
+ * What the threshold counts.
141
+ *
142
+ * @remarks Threshold meter. Defaults to `'history'`. Use `'input'` when the host prefers provider
143
+ * full-prompt usage (after subtracting a known baseline in `maxTokens` / `compactAt`).
101
144
  */
102
145
  meter?: CompactionMeter;
103
- /** Replaces the default `tokens > compactAt * maxTokens` check. */
146
+ /**
147
+ * Your function that decides when to compact, in place of compactAt and maxTokens.
148
+ *
149
+ * @remarks Replaces the default `tokens > compactAt * maxTokens` check.
150
+ */
104
151
  trigger?: (ctx: CompactionTriggerContext) => boolean | Promise<boolean>;
105
152
  }
106
153
  /** What every request that runs a model takes: how to stop it, and where its trace goes. */
107
154
  export interface RunControls {
108
- /** Stops the run when it aborts, and cancels in-flight provider HTTP where the adapter supports it. */
155
+ /**
156
+ * Stops the run when it aborts, and cancels its provider call where the provider can.
157
+ *
158
+ * @remarks Stops the run when it aborts, and cancels in-flight provider HTTP where the adapter
159
+ * supports it.
160
+ */
109
161
  signal?: AbortSignal;
110
- /** Host-owned metadata preserved on the run's trace records; the kernel does not interpret it. */
162
+ /**
163
+ * Your own values, kept on the trace; Theorem does not read them.
164
+ *
165
+ * @remarks Host-owned metadata preserved on the run's trace records; the kernel does not
166
+ * interpret it.
167
+ */
111
168
  metadata?: Record<string, unknown>;
112
169
  /**
113
- * W3C `traceparent` of the host span this run goes under. The run's root span joins that trace
114
- * as its child; without it the run starts a new trace. A malformed value throws.
170
+ * The W3C traceparent of your span; the run's trace joins it as a child.
171
+ *
172
+ * @remarks W3C `traceparent` of the host span this run goes under. The run's root span joins that
173
+ * trace as its child; without it the run starts a new trace. A malformed value throws.
115
174
  */
116
175
  traceparent?: string;
117
176
  /** Your project id, recorded on the trace. */
118
177
  projectId?: string;
119
- /** Host conversation id, recorded as `gen_ai.conversation.id`. */
178
+ /**
179
+ * Your conversation id, recorded on the trace.
180
+ *
181
+ * @remarks Host conversation id, recorded as `gen_ai.conversation.id`.
182
+ */
120
183
  conversationId?: string;
121
- /** Earlier traces this run follows. */
184
+ /**
185
+ * Earlier traces this run follows: a resume, a continue, or a retry.
186
+ *
187
+ * @remarks Earlier traces this run follows.
188
+ */
122
189
  links?: TurnTraceLink[];
123
190
  }
124
191
  /** Which of the profile's models a run uses, and how hard it thinks. */
125
192
  export interface ModelChoice {
126
- /** Selected model id when `profile.allowModelSelect` is true. */
193
+ /**
194
+ * The model id the turn or session picks from the profile's models; refused unless the profile
195
+ * sets allowModelSelect.
196
+ *
197
+ * @remarks Selected model id when `profile.allowModelSelect` is true.
198
+ */
127
199
  model?: ModelId;
128
- /** Selected effort alias when the binding has `allowEffortSelect`. */
200
+ /**
201
+ * The effort the turn or session picks from the model's efforts; refused unless the model sets
202
+ * allowEffortSelect.
203
+ *
204
+ * @remarks Selected effort alias when the binding has `allowEffortSelect`.
205
+ */
129
206
  effort?: string;
130
207
  }
131
208
  /** `compactHistory` input, for `timing: 'after'`: the host passes back what `done.compaction` carried. */
@@ -140,6 +217,7 @@ export interface CompactHistoryRequest extends RunControls {
140
217
  }
141
218
  /** A structured-output schema given inline. */
142
219
  export interface StructuredSpec {
220
+ /** The JSON Schema a structured reply must follow, sent to the model as its response format. */
143
221
  jsonSchema: Record<string, unknown>;
144
222
  }
145
223
  /** Caps on the files a turn may attach. */
@@ -216,39 +294,90 @@ export type ProfileItemCheck = (item: unknown, turn: ItemCheckTurn) => Validatio
216
294
  * rewrite the refused items alone, then removes any that are refused again.
217
295
  */
218
296
  export interface ProfileItemRule {
297
+ /**
298
+ * Your check on one item, given what the tools of the turn returned (turn.toolResults); its error
299
+ * is the reason the model reads on a rewrite and the host reads on the removed item.
300
+ */
219
301
  check: ProfileItemCheck;
302
+ /**
303
+ * drop removes a refused item. fix first asks the model to rewrite the refused items alone, once
304
+ * and while retries remain, then removes any refused again. Removed items leave on the structured
305
+ * event as removed.
306
+ */
220
307
  onFail: 'drop' | 'fix';
221
308
  }
222
309
  /** Host validators a profile runs on its structured output. */
223
310
  export interface ProfileValidationSpec {
224
311
  /**
225
- * Host domain validators keyed by dotted paths into structured output
226
- * (e.g. `diagram.mermaid`). Presence/required is owned by the JSON Schema;
227
- * these run only for required paths and for optional paths that are present.
312
+ * Your checks, each keyed by a dotted path into the structured reply, such as diagram.mermaid; a
313
+ * path no structured schema reaches is refused when the profile registers.
314
+ *
315
+ * @remarks Host domain validators keyed by dotted paths into structured output (e.g.
316
+ * `diagram.mermaid`). Presence/required is owned by the JSON Schema; these run only for required
317
+ * paths and for optional paths that are present.
318
+ *
319
+ * @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.
228
320
  */
229
321
  fields?: Record<string, ProfileValidator>;
230
- /** Host checks on list items, keyed by the dotted path of a list in the structured output. */
322
+ /**
323
+ * Your checks on the items of a list, each keyed by the dotted path of that list in the
324
+ * structured reply, such as claims; a path no structured schema reaches as a list is refused when
325
+ * the profile registers.
326
+ *
327
+ * @remarks Host checks on list items, keyed by the dotted path of a list in the structured
328
+ * output.
329
+ *
330
+ * @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.
331
+ */
231
332
  items?: Record<string, ProfileItemRule>;
333
+ /**
334
+ * How many times the model may rewrite a reply that fails your checks or the schema's required
335
+ * keys before it goes out as it is; under sse, an attempt that gets rewritten has already
336
+ * streamed. A rewrite of a blocked reply (guardrails.blockedReply) counts against this too.
337
+ */
232
338
  maxRetries?: number;
233
339
  }
234
340
  /** `voice` is the TTS voice id, not ingress audio (`inputs.voice`). */
235
341
  export interface ProfileSpeechSpec {
342
+ /**
343
+ * The voice the speech is read in, by the provider's own name for it; a turn's speech.voice
344
+ * replaces it.
345
+ */
236
346
  voice?: string;
237
- /** How the script is delivered, in plain words: pace, mood, accent. Never read aloud. */
347
+ /**
348
+ * How the script is delivered, in plain words (pace, mood, accent); it is never read aloud, and a
349
+ * turn's speech.style replaces it. A model that takes no direction ignores it.
350
+ *
351
+ * @remarks How the script is delivered, in plain words: pace, mood, accent. Never read aloud.
352
+ */
238
353
  style?: string;
239
- /** The speaking rate; 1 is the voice's own pace. */
354
+ /**
355
+ * The speaking rate, where 1 is the voice's own pace; a turn's speech.speed replaces it. A
356
+ * provider that has no rate refuses it or ignores it.
357
+ *
358
+ * @remarks The speaking rate; 1 is the voice's own pace.
359
+ */
240
360
  speed?: number;
241
- /** A provider that cannot make the format refuses the turn. */
361
+ /**
362
+ * The audio encoding each turn's speech comes back in, and so what the host plays or stores.
363
+ *
364
+ * @remarks A provider that cannot make the format refuses the turn.
365
+ */
242
366
  format?: SpeechAudioFormat;
243
367
  }
244
368
  /** What one speech turn sets for itself; each field given replaces the profile's `speech` field of that name. */
245
369
  export type TurnSpeech = Pick<ProfileSpeechSpec, 'voice' | 'style' | 'speed'>;
246
370
  /** Voice activity detection settings for a live session. */
247
371
  export interface LiveVadSpec {
372
+ /** Whether the user speaking interrupts the model's reply. */
248
373
  activityHandling?: LiveActivityHandling;
374
+ /** How readily the session decides the user has started speaking. */
249
375
  startSensitivity?: LiveStartSensitivity;
376
+ /** How readily the session decides the user has stopped speaking. */
250
377
  endSensitivity?: LiveEndSensitivity;
378
+ /** How long speech must last, in milliseconds, before it counts as the user starting to speak. */
251
379
  prefixPaddingMs?: number;
380
+ /** How long a silence, in milliseconds, ends the user's speech. */
252
381
  silenceDurationMs?: number;
253
382
  }
254
383
  /**
@@ -258,25 +387,37 @@ export interface LiveVadSpec {
258
387
  */
259
388
  export interface LiveContextCompressionSpec {
260
389
  /**
261
- * Context tokens, counted before a turn, that start compression. A whole
262
- * number above 0. Omit → provider default (Gemini: 80% of the model's context
263
- * window).
390
+ * The context size, in tokens, that starts trimming.
391
+ *
392
+ * @remarks Context tokens, counted before a turn, that start compression. A whole number above 0.
393
+ * Omit → provider default (Gemini: 80% of the model's context window).
264
394
  */
265
395
  triggerTokens?: number;
266
- /** Drops the oldest turns; the system instruction stays. Gemini's only mechanism. */
396
+ /**
397
+ * Trims by dropping the oldest turns; the system instruction stays.
398
+ *
399
+ * @remarks Drops the oldest turns; the system instruction stays. Gemini's only mechanism.
400
+ */
267
401
  slidingWindow: LiveSlidingWindowSpec;
268
402
  }
269
403
  /** Sliding-window context compression for a live session. */
270
404
  export interface LiveSlidingWindowSpec {
271
405
  /**
272
- * Tokens to keep after compressing. A whole number above 0, below
273
- * `triggerTokens`. Omit → provider default (Gemini: half of `triggerTokens`).
406
+ * The context size, in tokens, to trim down to; below the trigger.
407
+ *
408
+ * @remarks Tokens to keep after compressing. A whole number above 0, below `triggerTokens`. Omit
409
+ * → provider default (Gemini: half of `triggerTokens`).
274
410
  */
275
411
  targetTokens?: number;
276
412
  }
277
413
  /** Which sides of a live session are transcribed. */
278
414
  export interface LiveTranscriptionSpec {
415
+ /** Whether the user's speech is transcribed. */
279
416
  input?: boolean;
417
+ /**
418
+ * Whether the model's speech is transcribed; always on while a detector reads live_reply, since
419
+ * it reads the transcript.
420
+ */
280
421
  output?: boolean;
281
422
  }
282
423
  /**
@@ -285,37 +426,87 @@ export interface LiveTranscriptionSpec {
285
426
  * `LiveSession.sendAudio` / `sendVideo` / `sendText` channels.
286
427
  */
287
428
  export interface LiveIngressSpec {
288
- /** Microphone PCM via `sendAudio`. Omit → enabled. */
429
+ /**
430
+ * Whether the session accepts microphone audio.
431
+ *
432
+ * @remarks Microphone PCM via `sendAudio`. Omit → enabled.
433
+ */
289
434
  audio?: boolean;
290
- /** Webcam JPEG frames via `sendVideo`. Omit → enabled. */
435
+ /**
436
+ * Whether the session accepts camera frames.
437
+ *
438
+ * @remarks Webcam JPEG frames via `sendVideo`. Omit → enabled.
439
+ */
291
440
  video?: boolean;
292
- /** Typed text via `sendText`. Omit → disabled (opt-in). */
441
+ /**
442
+ * Whether the session accepts typed text.
443
+ *
444
+ * @remarks Typed text via `sendText`. Omit → disabled (opt-in).
445
+ */
293
446
  text?: boolean;
294
447
  }
295
448
  /** The prompt a resumed call opens with, and how long away earns it. */
296
449
  export interface LiveResumedSpec {
450
+ /**
451
+ * A prompt the call sends itself when it resumes, so the agent says it is back. The visitor does
452
+ * not see it. It may use {name}, and is not sent when an option it prints is unset.
453
+ */
297
454
  prompt: string;
298
- /** The shortest time away, in milliseconds, the agent remarks on. Omit → `DEFAULT_RESUMED_AFTER_MS`. */
455
+ /**
456
+ * The shortest time away, in milliseconds, that earns the prompt; a shorter drop resumes
457
+ * silently.
458
+ *
459
+ * @remarks The shortest time away, in milliseconds, the agent remarks on. Omit →
460
+ * `DEFAULT_RESUMED_AFTER_MS`.
461
+ */
299
462
  afterMs?: number;
300
463
  }
301
464
  /** The settings only a live profile has: ingress, voice, detection, windowing, transcription, and resumption. */
302
465
  export interface ProfileLiveSpec {
466
+ /** Which channels the session accepts from the user. */
303
467
  ingress?: LiveIngressSpec;
468
+ /** The voice the model speaks in. */
304
469
  voice?: string;
470
+ /** How the session detects when the user starts and stops speaking. */
305
471
  vad?: LiveVadSpec;
472
+ /**
473
+ * Whether the provider sends resume handles, which the host can pass to a new session to carry
474
+ * this one on.
475
+ */
306
476
  sessionResumption?: boolean;
307
- /** A prompt the session sends itself when a call opens new, so the agent speaks first. Omit → the agent waits. */
477
+ /**
478
+ * A prompt the call sends itself when it opens new, so the agent speaks first. The visitor does
479
+ * not see it. It may use {name}, and is not sent when an option it prints is unset.
480
+ *
481
+ * @remarks A prompt the session sends itself when a call opens new, so the agent speaks first.
482
+ * Omit → the agent waits.
483
+ */
308
484
  greeting?: string;
309
- /** What the agent is prompted with when a call resumes after the caller was away. Omit → a resumed call is silent. */
485
+ /**
486
+ * What happens when a call comes back after a drop. It needs live.sessionResumption.
487
+ *
488
+ * @remarks What the agent is prompted with when a call resumes after the caller was away. Omit →
489
+ * a resumed call is silent.
490
+ */
310
491
  resumed?: LiveResumedSpec;
311
- /** Context window compression. Omit → none: the provider ends the session at its limit. */
492
+ /**
493
+ * Trims the session's context once it grows past the trigger.
494
+ *
495
+ * @remarks Context window compression. Omit → none: the provider ends the session at its limit.
496
+ */
312
497
  contextCompression?: LiveContextCompressionSpec;
498
+ /** Text transcripts of the session's speech. */
313
499
  transcription?: LiveTranscriptionSpec;
314
500
  }
315
501
  /** How a profile's reply streams. */
316
502
  export interface ProfileStreamingSpec {
503
+ /** Whether the reply reaches the host as the model writes it, or whole. */
317
504
  mode?: StreamMode;
318
- /** When false, filter `thought` events from the turn stream. */
505
+ /**
506
+ * Whether the model's thinking reaches the host.
507
+ *
508
+ * @remarks When false, filter `thought` events from the turn stream.
509
+ */
319
510
  streamThoughts?: boolean;
320
511
  }
321
512
  export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
@@ -339,46 +530,105 @@ export interface ProfileModelFields {
339
530
  }
340
531
  /** One value an option can take. `description` is what a picker shows beside it. */
341
532
  export interface OptionChoice {
533
+ /**
534
+ * The value the code sets, which `when` reads and {name} prints.
535
+ *
536
+ * @catalog inputs.options.*.choices.*.value The value the turn sends for this choice, which
537
+ * `when` reads and {name} prints.
538
+ */
342
539
  value: string;
540
+ /**
541
+ * What this value means. It is never sent to the model.
542
+ *
543
+ * @catalog inputs.options.*.choices.*.description Visitor-facing blurb for this choice in the
544
+ * composer. Never substituted into prompts.
545
+ */
343
546
  description?: string;
344
547
  }
345
548
  /** One named option: its `label` for a picker, and the values it can take. */
346
549
  export interface OptionDecl {
550
+ /**
551
+ * A person-readable title. Omit to show the option's name.
552
+ *
553
+ * @catalog inputs.options.*.label Visitor-facing title for this option in the composer (for
554
+ * example Source Bias). Omit to show the option's name.
555
+ */
347
556
  label?: string;
557
+ /**
558
+ * The values this option can take.
559
+ *
560
+ * @catalog inputs.options.*.choices The values this option can take, each with an optional UI
561
+ * description.
562
+ */
348
563
  choices: OptionChoice[];
349
564
  }
350
565
  /** A profile's options by name. Which object holds them says who drives them. */
351
566
  export type ProfileOptions = Readonly<Record<string, OptionDecl>>;
352
567
  /** What a profile accepts as input. */
353
568
  export interface ProfileInputsSpec {
569
+ /** Whether a turn may send text. */
354
570
  text?: boolean;
571
+ /** Lets turns send files. */
355
572
  attachments?: {
573
+ /**
574
+ * The file types a turn may send, where type/* matches a whole family; image profiles take only
575
+ * images, video, and PDF.
576
+ */
356
577
  accept: string[];
357
578
  };
579
+ /** Lets turns send voice clips. A transcription profile must set it. */
358
580
  voice?: {
359
- accept: string[];
581
+ /** The audio types a voice clip may be; audio/* matches them all. */ accept: string[];
360
582
  };
583
+ /** The most files and voice clips one turn or embedding request may send, counted together. */
361
584
  maxFiles?: number;
585
+ /** The largest file or clip, in bytes, a turn or embedding request may send inline. */
362
586
  maxBytes?: number;
587
+ /**
588
+ * The most bytes one turn or embedding request may send inline across all its files and clips.
589
+ */
363
590
  maxTurnBytes?: number;
591
+ /**
592
+ * Size limits by file type that replace maxBytes for those types.
593
+ *
594
+ * @catalog inputs.limitsByMime.* The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.
595
+ */
364
596
  limitsByMime?: Record<string, number>;
365
- /** The options a person picks: a host shows each one as a picker. */
597
+ /**
598
+ * The options a person picks, each shown as a picker. A prompt reads one as "when reader is
599
+ * student: …" and prints it as {reader}.
600
+ *
601
+ * @remarks The options a person picks: a host shows each one as a picker.
602
+ * @catalog inputs.options.* { label?, choices: { value, description? }[] }. Value is what the turn sends and what {name} prints.
603
+ */
366
604
  options?: ProfileOptions;
605
+ /**
606
+ * Lets the page or the host send the agent one package of things to know, read at the context
607
+ * boundary.
608
+ */
367
609
  context?: ProfileContextSpec;
368
610
  }
369
611
  /** What a live profile declares beside its ingress channels. */
370
612
  export type LiveInputsSpec = Pick<ProfileInputsSpec, 'options' | 'context'>;
371
613
  /** Who may send a turn its context, and how much. */
372
614
  export interface ProfileContextSpec {
615
+ /** Who may send context; context from anyone else is refused. */
373
616
  from: ContextSender[];
617
+ /** The longest package, in characters of its JSON, each sender may send. */
374
618
  maxChars: number;
375
619
  }
376
620
  /** The context each sender gives a turn: any JSON, or text. */
377
621
  export type TurnContext = Partial<Record<ContextSender, unknown>>;
378
622
  /** What a profile returns: its structured schema, validation, and streaming. */
379
623
  export interface ProfileOutputsSpec {
624
+ /**
625
+ * The registered JSON schema the reply must follow, which can vary by option; register it before
626
+ * the profile.
627
+ */
380
628
  structured?: StructuredSchemaId | StructuredByOption | null;
629
+ /** Your checks on a structured reply, and how many rewrites a failure gets. */
381
630
  validation?: ProfileValidationSpec;
631
+ /** How the reply reaches the host, and whether its thinking does. */
382
632
  streaming?: ProfileStreamingSpec;
383
633
  }
384
634
  /** Text a reply may not repeat when the rest of its prompt is marked shareable. */
@@ -404,9 +654,26 @@ export interface SystemPiece {
404
654
  }
405
655
  /** A profile's handle and system prompt. */
406
656
  export interface ProfileIdentity {
657
+ /**
658
+ * The name hosts and users see for this agent, at most 32 characters; the model never sees it.
659
+ */
407
660
  handle: string;
408
- /** The options the host's code states. A person never sees them. */
661
+ /**
662
+ * The options the host's code sets on runTurn, which a person never sees. A line of
663
+ * identity.system reads one as "when plan is free: …" and prints it as {plan}. One named path
664
+ * holds the turn's path.
665
+ *
666
+ * @remarks The options the host's code states. A person never sees them.
667
+ * @catalog identity.options.* { label?, choices: { value, description? }[] }, the same shape as inputs.options.*.
668
+ */
409
669
  options?: ProfileOptions;
670
+ /**
671
+ * The instruction the model gets, as one string or a list of lines; some providers send it for an
672
+ * image profile only with includeText on. A line that opens "when plan is free: …" goes only on
673
+ * turns where that fits, and every line that fits is sent, a blank line apart. A line can be a
674
+ * list of parts; mark what must not leak as { private: text }; only that is guarded. With none,
675
+ * the whole prompt is.
676
+ */
410
677
  system?: ProfileSystem;
411
678
  }
412
679
  /** The fields every profile type shares. */
@@ -430,7 +697,12 @@ export type DecisionJson = null | string | number | boolean | DecisionJson[] | {
430
697
  };
431
698
  /** What a decision profile accepts: JSON state up to a byte cap. */
432
699
  export interface DecisionInputsSpec {
700
+ /** A decision reads JSON state, passed on each call. */
433
701
  state: 'json';
702
+ /**
703
+ * The largest state, in bytes, a decision call may send; larger state is refused before it leaves
704
+ * your process.
705
+ */
434
706
  maxStateBytes?: number;
435
707
  }
436
708
  /**
@@ -448,6 +720,10 @@ export interface DecisionProfile {
448
720
  models: Record<ModelId, DecisionModelBinding>;
449
721
  inputs: DecisionInputsSpec;
450
722
  decision: {
723
+ /**
724
+ * Your name for this decision, on its traces. Not sent to the model. Not checked against the
725
+ * questions.
726
+ */
451
727
  contract: DecisionContractId;
452
728
  };
453
729
  guardrails?: DecisionGuardrailsSpec;
@@ -565,13 +841,29 @@ export type EmbeddingInput = string | {
565
841
  };
566
842
  /** A profile's accepted embedding input kinds and limits. */
567
843
  export interface EmbeddingInputsSpec {
844
+ /** Whether a turn may send text. */
568
845
  text?: boolean;
846
+ /** Lets turns send files. */
569
847
  attachments?: {
848
+ /**
849
+ * The file types a turn may send, where type/* matches a whole family; image profiles take only
850
+ * images, video, and PDF.
851
+ */
570
852
  accept: string[];
571
853
  };
854
+ /** The most files and voice clips one turn or embedding request may send, counted together. */
572
855
  maxFiles?: number;
856
+ /** The largest file or clip, in bytes, a turn or embedding request may send inline. */
573
857
  maxBytes?: number;
858
+ /**
859
+ * The most bytes one turn or embedding request may send inline across all its files and clips.
860
+ */
574
861
  maxTurnBytes?: number;
862
+ /**
863
+ * Size limits by file type that replace maxBytes for those types.
864
+ *
865
+ * @catalog inputs.limitsByMime.* The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.
866
+ */
575
867
  limitsByMime?: Record<string, number>;
576
868
  }
577
869
  /** A profile that returns vectors instead of a model turn. */
@@ -724,26 +1016,57 @@ export interface TurnRepairRequest {
724
1016
  }
725
1017
  /** What the user sent for a turn: text, options, attachments, voice, and history. */
726
1018
  export interface TurnInput {
1019
+ /** The user's message. */
727
1020
  text?: string;
728
- /** The value picked for each of the profile's `inputs.options`. */
1021
+ /**
1022
+ * The value a person picked for each option in the profile's inputs.options; an option or a value
1023
+ * the profile does not declare is refused.
1024
+ *
1025
+ * @remarks The value picked for each of the profile's `inputs.options`.
1026
+ */
729
1027
  options?: Readonly<Record<string, string>>;
730
- /** What the page or the host wants the model to know, by sender; the profile's `inputs.context` allows it. */
1028
+ /**
1029
+ * What the page (client) or the host (server) wants the model to know, as any JSON or text; a
1030
+ * sender the profile's inputs.context does not list, or a package over its maxChars, is refused.
1031
+ *
1032
+ * @remarks What the page or the host wants the model to know, by sender; the profile's
1033
+ * `inputs.context` allows it.
1034
+ */
731
1035
  context?: TurnContext;
1036
+ /**
1037
+ * Files sent with the turn, as bytes or as a provider file reference; each must pass the
1038
+ * profile's inputs.attachments.
1039
+ */
732
1040
  attachments?: Array<TurnBlob | TurnMediaRef>;
1041
+ /** Recorded speech sent with the turn; each must pass the profile's inputs.voice. */
733
1042
  voice?: TurnBlob[];
1043
+ /** The earlier messages of the conversation, when the host keeps them. */
734
1044
  history?: TurnHistoryMessage[];
735
- /** Tool calls that settled after their turn, as the host stored them. Each counts as read in this reply. */
1045
+ /**
1046
+ * Background tool calls that settled after their turn, as the host stored them. The model reads
1047
+ * each as a tool result, and this reply counts it as a remote read when the call was remote. Pass
1048
+ * each one once: the turn emits it as a late_results event, so a history built from events holds
1049
+ * it.
1050
+ *
1051
+ * @remarks Tool calls that settled after their turn, as the host stored them. Each counts as read
1052
+ * in this reply.
1053
+ */
736
1054
  lateResults?: ToolOperationOutcome[];
1055
+ /** A reply your host rejected and why, so that the model writes it again. */
737
1056
  repair?: TurnRepairRequest;
738
1057
  /**
739
- * Optional host-supplied history token count for `meter: 'history'`.
740
- * When set, overrides the local history estimate. Not full-prompt API tokens.
1058
+ * Your count of the history's tokens, used by compaction that meters history.
1059
+ *
1060
+ * @remarks Optional host-supplied history token count for `meter: 'history'`. When set, overrides
1061
+ * the local history estimate. Not full-prompt API tokens.
741
1062
  */
742
1063
  historyTokens?: number;
743
1064
  /**
744
- * Optional host-supplied full-prompt input token count for `meter: 'input'`
745
- * with `timing: 'before'` (typically the previous turn's `tokens.input`).
746
- * Ignored when `meter` is `'history'`.
1065
+ * Your count of the whole prompt's tokens, used by compaction that meters input before the call.
1066
+ *
1067
+ * @remarks Optional host-supplied full-prompt input token count for `meter: 'input'` with
1068
+ * `timing: 'before'` (typically the previous turn's `tokens.input`). Ignored when `meter` is
1069
+ * `'history'`.
747
1070
  */
748
1071
  inputTokens?: number;
749
1072
  }
@@ -765,94 +1088,164 @@ export interface TurnTraceLink {
765
1088
  }
766
1089
  /** What `runTurn` and `runSession` both take: an agent's profile, its model, and the host's hooks and keys. */
767
1090
  export interface AgentRunRequest extends RunControls, ModelChoice {
1091
+ /** Host-owned atomic tool claims and outcomes. Never sent to providers. */
768
1092
  execution?: ToolExecutionCoordinator;
1093
+ /**
1094
+ * Host-issued service for tool calls that go on after their reply. It needs a coordinator with
1095
+ * detach. Without it every tool runs inline.
1096
+ */
769
1097
  background?: ToolBackgroundService;
1098
+ /** Host-issued browser dispatch with a claimed operation and correlated result. */
770
1099
  pageExecution?: PageToolExecution;
1100
+ /** Native provider state saved alongside portable history. */
771
1101
  providerState?: ProviderCheckpoint;
1102
+ /** The id of the registered profile the turn or session runs. */
772
1103
  profile: ProfileId;
773
1104
  /**
774
- * Args for built-in tools on the chosen model's `builtInTools`, by tool id.
775
- * Each is parsed by the schema the provider's adapter declares for that tool.
1105
+ * Args for the provider's own tools on the chosen model's builtInTools, by tool id; each is
1106
+ * checked by the schema the provider declares for that tool.
1107
+ *
1108
+ * @remarks Args for built-in tools on the chosen model's `builtInTools`, by tool id. Each is
1109
+ * parsed by the schema the provider's adapter declares for that tool.
776
1110
  */
777
1111
  builtInArgs?: BuiltInArgs;
778
- /** Host-provided dynamic system prompt combined with profile persona */
1112
+ /**
1113
+ * An instruction for this request only, added to the profile's own.
1114
+ *
1115
+ * @remarks Host-provided dynamic system prompt combined with profile persona
1116
+ */
779
1117
  system?: SystemPrompt;
1118
+ /** The tools the user has already approved for this session. */
780
1119
  sessionPermissions?: string[];
781
- /** Host channel/path for catalog `paths` filtering. */
1120
+ /**
1121
+ * The channel the turn or session comes from; only tools whose paths name it, or *, are offered.
1122
+ *
1123
+ * @remarks Host channel/path for catalog `paths` filtering.
1124
+ */
782
1125
  path?: string;
783
- /** This run's value for each of `profile.identity.options` it sets; `path` is the run's own. */
1126
+ /**
1127
+ * The value the host's code sets for each option in the profile's identity.options but path; an
1128
+ * option or a value the profile does not declare is refused.
1129
+ *
1130
+ * @remarks This run's value for each of `profile.identity.options` it sets; `path` is the run's
1131
+ * own.
1132
+ */
784
1133
  options?: Readonly<Record<string, string>>;
785
1134
  /**
786
- * Opaque application context handed to tool `handler` / `preTool` and
787
- * `tools.t1Policy` as `ctx.host`. The kernel never reads, logs, traces, or
788
- * serializes it.
1135
+ * Your own context, handed to tool handlers as ctx.host; Theorem never reads or records it.
1136
+ *
1137
+ * @remarks Opaque application context handed to tool `handler` / `preTool` and `tools.t1Policy`
1138
+ * as `ctx.host`. The kernel never reads, logs, traces, or serializes it.
789
1139
  */
790
1140
  host?: unknown;
791
- /** Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs one. */
1141
+ /**
1142
+ * Where an HTTP or MCP tool gets the credential for its auth slot.
1143
+ *
1144
+ * @remarks Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs
1145
+ * one.
1146
+ */
792
1147
  credentials?: ToolCredentialSource;
793
1148
  /**
794
- * Resolves remote tool and OAuth host names before each request; a name that
795
- * resolves to a private address is refused (see `fetchGuarded`).
1149
+ * Resolves the host name of a remote tool before each request; a name that resolves to a private
1150
+ * address is refused.
1151
+ *
1152
+ * @remarks Resolves remote tool and OAuth host names before each request; a name that resolves to
1153
+ * a private address is refused (see `fetchGuarded`).
796
1154
  */
797
1155
  resolveHost?: ResolveHost;
798
1156
  /**
799
- * Sends each request a remote tool makes (HTTP, MCP, a signed-in fetch, an image read), once
800
- * that request's network checks pass. A page whose tools cannot reach a host directly sends them
801
- * through its own server here. Default: the global `fetch`.
1157
+ * Sends each request a remote tool makes, once that request's network checks pass. A page whose
1158
+ * tools cannot reach a host directly sends them through its own server here.
1159
+ *
1160
+ * @remarks Sends each request a remote tool makes (HTTP, MCP, a signed-in fetch, an image read),
1161
+ * once that request's network checks pass. A page whose tools cannot reach a host directly sends
1162
+ * them through its own server here. Default: the global `fetch`.
802
1163
  */
803
1164
  fetch?: typeof fetch;
804
- /** Text `runTurn` and `runSession` emit stages and apply the returned affordances. A session's is set once. */
1165
+ /**
1166
+ * Your function that sees each stage of a text turn or a live session, and can answer with what
1167
+ * the stage allows.
1168
+ *
1169
+ * @remarks Text `runTurn` and `runSession` emit stages and apply the returned affordances. A
1170
+ * session's is set once.
1171
+ */
805
1172
  onStage?: StageHandler;
806
1173
  /**
807
- * Runs before each agent tool call in this run, and in the turns those
808
- * calls run. Shape the called agent's request (history, model, provider) or
809
- * refuse the call. Omit it: the agent runs on what the model sent.
1174
+ * Runs before each agent tool call, to shape the request to the called agent or to refuse the
1175
+ * call.
1176
+ *
1177
+ * @remarks Runs before each agent tool call in this run, and in the turns those calls run. Shape
1178
+ * the called agent's request (history, model, provider) or refuse the call. Omit it: the agent
1179
+ * runs on what the model sent.
810
1180
  */
811
1181
  onAgentCall?: AgentCallHook;
812
1182
  }
813
1183
  /** A request to `runTurn`: the shared controls and the turn's input. */
814
1184
  export interface TurnRequest extends AgentRunRequest {
815
1185
  /**
816
- * Sticky routing / cache session key for OpenRouter (`session_id`).
817
- * Not the same as `projectId` or Gemini `previousInteractionId`.
1186
+ * A session key that OpenRouter uses for routing and caching.
1187
+ *
1188
+ * @remarks Sticky routing / cache session key for OpenRouter (`session_id`). Not the same as
1189
+ * `projectId` or Gemini `previousInteractionId`.
818
1190
  */
819
1191
  sessionId?: string;
820
- /** This turn's voice, style, and speed, over `profile.speech`. Speech profiles only. */
1192
+ /**
1193
+ * This turn's voice, style, and speed; each one given replaces the profile's speech field of that
1194
+ * name. Refused on a profile that is not speech.
1195
+ *
1196
+ * @remarks This turn's voice, style, and speed, over `profile.speech`. Speech profiles only.
1197
+ */
821
1198
  speech?: TurnSpeech;
822
1199
  /**
823
- * Continue a prior resumeable stop. On text profiles the turn's user message
824
- * is the continue instruction (no `input.text`); the host passes the partial
825
- * reply as the last assistant message in `input.history`. Image and speech
826
- * re-send the original request unchanged.
1200
+ * Continues a turn that stopped in a way the profile lets a turn continue.
1201
+ *
1202
+ * @remarks Continue a prior resumeable stop. On text profiles the turn's user message is the
1203
+ * continue instruction (no `input.text`); the host passes the partial reply as the last assistant
1204
+ * message in `input.history`. Image and speech re-send the original request unchanged.
827
1205
  */
828
1206
  continueFrom?: TurnContinueFrom;
829
1207
  /**
830
- * 1-based continue attempt when `continueFrom` is set.
831
- * Compared to `profile.turnBehaviour.resumption.maxContinues` when that cap is set.
1208
+ * Which continue attempt this is, from 1; checked against the maxContinues of the profile.
1209
+ *
1210
+ * @remarks 1-based continue attempt when `continueFrom` is set. Compared to
1211
+ * `profile.turnBehaviour.resumption.maxContinues` when that cap is set.
832
1212
  */
833
1213
  continuation?: number;
834
1214
  /**
835
- * Tools this reply already had when an earlier run of it paused. The turn opens with them on its
836
- * list, so an answered call does not take back what the model loaded. An id `tools.allow` or the
837
- * path does not grant is left out, as for `tools.t1Policy`.
1215
+ * Tools this reply already had when an earlier run of it paused; the turn opens with them on its
1216
+ * list.
1217
+ *
1218
+ * @remarks Tools this reply already had when an earlier run of it paused. The turn opens with
1219
+ * them on its list, so an answered call does not take back what the model loaded. An id
1220
+ * `tools.allow` or the path does not grant is left out, as for `tools.t1Policy`.
838
1221
  */
839
1222
  promoted?: ToolId[];
840
1223
  /**
841
- * Steps this reply already took when an earlier run of it paused. They count against `maxSteps`,
842
- * so an answered call does not give the reply its steps back. Read `done.steps`.
1224
+ * Steps this reply already took when an earlier run of it paused; they count against maxSteps.
1225
+ *
1226
+ * @remarks Steps this reply already took when an earlier run of it paused. They count against
1227
+ * `maxSteps`, so an answered call does not give the reply its steps back. Read `done.steps`.
843
1228
  */
844
1229
  stepsTaken?: number;
845
1230
  /**
846
- * Reads each of this turn's events as it leaves `runTurn`, before the caller gets it. The app
847
- * sets it in `TurnWiring.prepare` to act on a turn someone else runs, such as saving the reply
848
- * when `done` arrives. A throw ends the turn with that error. `invokeTool` does not call it.
1231
+ * Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw ends
1232
+ * the turn with that error.
1233
+ *
1234
+ * @remarks Reads each of this turn's events as it leaves `runTurn`, before the caller gets it.
1235
+ * The app sets it in `TurnWiring.prepare` to act on a turn someone else runs, such as saving the
1236
+ * reply when `done` arrives. A throw ends the turn with that error. `invokeTool` does not call
1237
+ * it.
849
1238
  */
850
1239
  onEvent?: (event: TurnEvent) => void | Promise<void>;
851
1240
  /**
852
- * Set on the turn `TurnWiring.prepare` is given for a held call that goes on once answered. No
853
- * model runs and `input` is the paused turn's, so it is not a new message.
1241
+ * Set on the turn TurnWiring.prepare is given for a held call that goes on once answered: no
1242
+ * model runs, and input is the paused turn's.
1243
+ *
1244
+ * @remarks Set on the turn `TurnWiring.prepare` is given for a held call that goes on once
1245
+ * answered. No model runs and `input` is the paused turn's, so it is not a new message.
854
1246
  */
855
1247
  answersHeldCall?: true;
1248
+ /** What the user sent for the turn. */
856
1249
  input?: TurnInput;
857
1250
  }
858
1251
  /**