@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
@@ -9,28 +9,44 @@ import { BOUNDARIES, BOUNDARY_META, recordOf } from '../guardrails/boundaries.js
9
9
  import { DETECT_ACTION_META, DETECT_ACTIONS, DETECT_DEFAULTS, DETECTOR_BOUNDARIES, DETECTOR_META, DETECTORS, } from '../guardrails/detectors.js';
10
10
  import { LABEL_NOTES } from '../guardrails/labels.js';
11
11
  import { BLOCKED_REPLY_ON_BLOCK, DESTINATION_GATES, TAINT_GATES, } from '../guardrails/types.js';
12
+ import { FIELD_DOCS, OPTION_DOCS } from './field-docs.js';
12
13
  import { PROFILE_FIELD_PRESENCE } from './profile-presence.js';
13
14
  import { isProfileRootField, profileFieldScope, profileKeysOf, valuesAt } from './profile-scope.js';
14
15
  export { BLOCKED_REPLY_ON_BLOCK };
15
16
  /** The kinds of profile: each fixes which fields and models a profile may use. */
16
17
  export const PROFILE_TYPES = [
18
+ /** A chat or task agent. Each turn the model answers in text, or in JSON when outputs ask for a structured reply, and can call tools on the way. */
17
19
  'text',
20
+ /** Makes pictures from a prompt, in the shape, size, and format the image block sets. */
18
21
  'image',
22
+ /** Gives your app a voice. Each turn reads text aloud in the voice the speech block names. */
19
23
  'speech',
24
+ /** Turns a voice clip into text. Each turn takes one clip and gives back what was said. */
20
25
  'transcription',
26
+ /** For talking in real time. One continuous voice and video session, rather than separate turns. */
21
27
  'live',
28
+ /** For when your app needs a judgement, not a reply. It answers questions about a JSON state, each with a choice, a score, or a number. */
22
29
  'decision',
30
+ /** For when your app needs vectors from text or provider-supported media. */
23
31
  'embedding',
32
+ /** A governed passthrough to your tool registry, with no model. It calls MCP, HTTP, and in-app function tools under the same permissions and traces as any agent, guarded by detect and network. */
24
33
  'host',
25
34
  ];
26
35
  /** Reasoning effort levels, lowest to highest; a model accepts only the levels its catalog row lists. */
27
36
  export const THINKING_LEVELS = [
37
+ /** No thinking, where the provider has that level. */
28
38
  'none',
39
+ /** The least thinking. */
29
40
  'minimal',
41
+ /** Light thinking. */
30
42
  'low',
43
+ /** Moderate thinking. */
31
44
  'medium',
45
+ /** Heavy thinking. */
32
46
  'high',
47
+ /** Heavier thinking, where the provider has that level. */
33
48
  'xhigh',
49
+ /** The most thinking the model supports, where the provider has that level. */
34
50
  'max',
35
51
  ];
36
52
  /** The longest a profile's `id` may be, in characters: room for a dotted or generated one. */
@@ -48,65 +64,138 @@ export const MEDIA_INPUT_KIND_VALUES = ['image', 'audio', 'video', 'document'];
48
64
  /** Whether thought summaries are asked for (`auto`) or not (`none`). */
49
65
  export const SUMMARY_MODES = ['auto', 'none'];
50
66
  /** Whether the provider call streams (`sse`) or is one buffered call. */
51
- export const STREAM_MODES = ['sse', 'buffered'];
67
+ export const STREAM_MODES = [
68
+ /** Events arrive as the model writes, so a reply that fails outputs.validation has already streamed when it is rewritten; some providers always answer image and speech in one piece. */
69
+ 'sse',
70
+ /** One non-streaming call, whose events arrive together; under outputs.validation, only once the reply passes or retries run out. Thinking still streams. */
71
+ 'buffered',
72
+ ];
52
73
  /** Audio encodings a speech profile can return. */
53
- export const SPEECH_AUDIO_FORMATS = ['pcm', 'mp3'];
74
+ export const SPEECH_AUDIO_FORMATS = [
75
+ /** Uncompressed audio, delivered as WAV. */
76
+ 'pcm',
77
+ /** Compressed audio; a provider that cannot make it refuses the turn. */
78
+ 'mp3',
79
+ ];
54
80
  /** Who can send a turn its context: the browser, or the host's own code. */
55
81
  /** How long a caller is away, in milliseconds, before `live.resumed.prompt` is sent, when the profile sets no `afterMs`. */
56
82
  export const DEFAULT_RESUMED_AFTER_MS = 3000;
57
- export const CONTEXT_SENDERS = ['client', 'server'];
83
+ export const CONTEXT_SENDERS = [
84
+ /** The browser. A visitor can change it, so it is untrusted. */
85
+ 'client',
86
+ /** The host's own code. It is assembled, like turn system text. */
87
+ 'server',
88
+ ];
58
89
  /** What the user starting to speak does to a live model that is mid-reply. */
59
- export const LIVE_ACTIVITY_HANDLINGS = ['START_OF_ACTIVITY_INTERRUPTS', 'NO_INTERRUPTION'];
90
+ export const LIVE_ACTIVITY_HANDLINGS = [
91
+ /** The user speaking cuts the reply off. */
92
+ 'START_OF_ACTIVITY_INTERRUPTS',
93
+ /** The model finishes its reply. */
94
+ 'NO_INTERRUPTION',
95
+ ];
60
96
  /** How readily live voice detection decides the user has started speaking. */
61
97
  export const LIVE_START_SENSITIVITIES = [
98
+ /** Detects the start of speech less often. */
62
99
  'START_SENSITIVITY_LOW',
100
+ /** Detects the start of speech more often. */
63
101
  'START_SENSITIVITY_HIGH',
64
102
  ];
65
103
  /** How readily live voice detection decides the user has stopped speaking. */
66
- export const LIVE_END_SENSITIVITIES = ['END_SENSITIVITY_LOW', 'END_SENSITIVITY_HIGH'];
104
+ export const LIVE_END_SENSITIVITIES = [
105
+ /** Ends speech less often, waiting through pauses. */
106
+ 'END_SENSITIVITY_LOW',
107
+ /** Ends speech more often, at shorter pauses. */
108
+ 'END_SENSITIVITY_HIGH',
109
+ ];
67
110
  /** What compaction counts against its token limit: the stored history or the next request's input. */
68
- export const COMPACTION_METERS = ['history', 'input'];
111
+ export const COMPACTION_METERS = [
112
+ /** Tokens in the earlier conversation. */
113
+ 'history',
114
+ /** The prompt tokens the provider reported for the last call, or the count the host passes in. */
115
+ 'input',
116
+ ];
69
117
  /** Whether compaction runs before or after a turn. */
70
- export const COMPACTION_TIMINGS = ['before', 'after'];
71
- /**
72
- * - `compacted`: a summary replaced the compacted messages.
73
- * - `deferred`: the compactor failed and the history still fits `maxTokens`, so it is kept whole.
74
- * - `dropped`: the compactor failed over `maxTokens`, so the compacted messages were dropped.
75
- */
76
- export const COMPACTION_OUTCOMES = ['compacted', 'deferred', 'dropped'];
118
+ export const COMPACTION_TIMINGS = [
119
+ /** The kernel compacts before the turn runs. */
120
+ 'before',
121
+ /** The turn's done event says compaction is due, and the host runs it. */
122
+ 'after',
123
+ ];
124
+ /** What a compaction did. */
125
+ export const COMPACTION_OUTCOMES = [
126
+ /** A summary replaced the compacted messages. */
127
+ 'compacted',
128
+ /** The compactor failed and the history still fits `maxTokens`, so it is kept whole. */
129
+ 'deferred',
130
+ /** The compactor failed over `maxTokens`, so the compacted messages were dropped. */
131
+ 'dropped',
132
+ ];
77
133
  /** Which part of the prompt is cached: the whole request (`automatic`) or the system instruction only (`system`). */
78
134
  export const CACHE_MODES = ['automatic', 'system'];
79
135
  /** How long a provider keeps a cached prompt. */
80
136
  export const CACHE_TTLS = ['5m', '1h'];
81
137
  /** Why a turn stopped, as `done.stop.kind` reports it. */
82
138
  export const TURN_STOP_KINDS = [
139
+ /** The model finished its reply. */
83
140
  'completed',
141
+ /** The model reached its token limit. */
84
142
  'length',
85
- /** The model called tools and the turn hands them to the host (`done.tools`). */
143
+ /**
144
+ * The model called tools and the turn hands them to the host, in done.tools.
145
+ *
146
+ * @remarks The model called tools and the turn hands them to the host (`done.tools`).
147
+ */
86
148
  'tool',
87
- /** `pre_tool` blocked the body; the host resumes via invokeTool/executeTool, not continueFrom. */
149
+ /**
150
+ * A tool call waits for confirmation, permission, sign-in, or the page that answers it. The host
151
+ * resumes it with invokeTool, not continueFrom.
152
+ *
153
+ * @remarks `pre_tool` blocked the body; the host resumes via invokeTool/executeTool, not continueFrom.
154
+ */
88
155
  'gate',
156
+ /** The provider filtered the reply, or the egress guardrail withheld it. */
89
157
  'filtered',
158
+ /** The provider failed or reported an error. */
90
159
  'provider_error',
160
+ /** The user or host cancelled the turn, or a stage aborted it. */
91
161
  'cancelled',
162
+ /** The stream ended without the provider reporting a final status. */
92
163
  'stream_incomplete',
93
- /** The turn made its last allowed model call and that call asked for tools: there is no answer. */
164
+ /**
165
+ * The last model call maxSteps allows asked for tools, so the turn ended with no answer.
166
+ *
167
+ * @remarks The turn made its last allowed model call and that call asked for tools: there is no answer.
168
+ */
94
169
  'step_limit',
95
170
  /** The model finished without calling the answer tool, and no repair was left. */
96
171
  'answer_missing',
172
+ /** Live: the user spoke over the reply and cut it off. */
97
173
  'interrupted',
98
- /** Live: model finished generating audio/text for this utterance; turn may still be open. */
174
+ /**
175
+ * Live: the model finished generating audio or text for this utterance. The turn may still be open.
176
+ *
177
+ * @remarks Live: model finished generating audio/text for this utterance; turn may still be open.
178
+ */
99
179
  'generation_complete',
100
180
  ];
101
181
  /** What a text turn's last allowed model call may do, as `turnBehaviour.atStepLimit` sets it. */
102
- export const STEP_LIMIT_MODES = ['stop', 'answer'];
182
+ export const STEP_LIMIT_MODES = [
183
+ /** It may still call tools; if it does, they run and the turn stops as step_limit with no answer. */
184
+ 'stop',
185
+ /** It is sent without tools, so it writes the answer from what the turn has gathered. */
186
+ 'answer',
187
+ ];
103
188
  /** What happens to a list item its check refuses, as `outputs.validation.items.*.onFail` sets it. */
104
189
  export const ITEM_FAIL_ACTIONS = ['drop', 'fix'];
105
190
  /** Every other stop resumes by another host path, or not at all. */
106
191
  export const CONTINUE_STOP_KINDS = [
192
+ /** The reply hit the output token limit. */
107
193
  'length',
194
+ /** The connection dropped mid-reply. */
108
195
  'stream_incomplete',
196
+ /** The provider returned an error or timed out. */
109
197
  'provider_error',
198
+ /** The model finished without calling the answer tool. */
110
199
  'answer_missing',
111
200
  ];
112
201
  /** The points in a turn where a stage handler runs. */
@@ -160,21 +249,91 @@ export const STAGE_APPLY_WARNING_CODES = [
160
249
  /** The `status` of a tool output that asks the user a question. */
161
250
  export const AWAITING_USER_INPUT_STATUS = 'awaiting_user_input';
162
251
  /** Enforced by the kernel at resolve time. */
163
- export const TOOL_LOAD_TIERS = ['T0', 'T2'];
252
+ export const TOOL_LOAD_TIERS = [
253
+ /** At the start of every turn. */
254
+ 'T0',
255
+ /** On demand: when tools.t1Policy picks it at the start of a turn, or when the tools.t2Loader tool loads it mid-turn (custom tools only). */
256
+ 'T2',
257
+ ];
164
258
  /** The HTTP methods an `http` tool may use. */
165
259
  export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
166
260
  /** When remote tool auth is missing or expired. */
167
- export const AUTH_UNAUTHENTICATED_POLICIES = ['gate', 'report_to_model', 'fail'];
261
+ export const AUTH_UNAUTHENTICATED_POLICIES = [
262
+ /** The turn stops and asks the host for a credential. */
263
+ 'gate',
264
+ /** The model is told the tool isn't signed in, and the turn goes on. */
265
+ 'report_to_model',
266
+ /** The call fails as not signed in, for a key the host holds that no person can sign in to replace. */
267
+ 'fail',
268
+ ];
168
269
  /** The kinds of tool a profile can list. */
169
- export const TOOL_TYPES = ['builtin', 'function', 'http', 'mcp', 'agent'];
270
+ export const TOOL_TYPES = [
271
+ /** The provider's own tool, such as Google Search, run by the provider. */
272
+ 'builtin',
273
+ /** Your handler runs it. */
274
+ 'function',
275
+ /** The kernel calls your HTTP endpoint. */
276
+ 'http',
277
+ /** The kernel calls a tool on a remote MCP server. */
278
+ 'mcp',
279
+ /** The kernel runs one turn of another registered agent and returns its reply. */
280
+ 'agent',
281
+ ];
282
+ /** When the model gets a tool's reply, as `registerTool.background` sets it. */
283
+ const TOOL_BACKGROUND_MODES = [
284
+ /** The model gets its reply when the body ends. */
285
+ 'never',
286
+ /** The model chooses, call by call, whether to go on without the result. */
287
+ 'ask',
288
+ /** The model gets its reply at once, and the body goes on after the turn. */
289
+ 'always',
290
+ /** The model gets its reply once the body has run past this time. */
291
+ 'afterMs',
292
+ ];
293
+ /** The kinds of question a decision asks, as `decision.questions.type` sets them. */
294
+ const DECISION_QUESTION_TYPES = [
295
+ /** One of the named options, with a confidence and a probability for each option. */
296
+ 'choice',
297
+ /** A level on an ordered scale, with a confidence. */
298
+ 'score',
299
+ /** One number, which may weigh named criteria. */
300
+ 'noul',
301
+ /** Where something is in an image: its top, bottom, left and right edges, with a confidence. */
302
+ 'box',
303
+ ];
170
304
  /** How much a tool can change: nothing, data, or irreversibly. */
171
- export const TOOL_ACCESS = ['read-only', 'read-write', 'destructive'];
305
+ export const TOOL_ACCESS = [
306
+ /** Only reads. */
307
+ 'read-only',
308
+ /** Creates or updates things. */
309
+ 'read-write',
310
+ /** Deletes, charges, or does something else hard to undo. */
311
+ 'destructive',
312
+ ];
172
313
  /** When the user must approve a tool call: never, once per session, or every call. */
173
- export const TOOL_PERMISSION = ['auto', 'session_consent', 'always_confirm'];
314
+ export const TOOL_PERMISSION = [
315
+ /** Runs without asking. */
316
+ 'auto',
317
+ /** Asks once; the approval lasts as long as the host keeps passing it back. */
318
+ 'session_consent',
319
+ /** Asks every time. */
320
+ 'always_confirm',
321
+ ];
174
322
  /** The credential shapes a remote tool can authenticate with. */
175
- export const TOOL_AUTH_TYPES = ['bearer', 'api_key', 'oauth2'];
323
+ export const TOOL_AUTH_TYPES = [
324
+ /** A token; a secret typed in at the prompt becomes a bearer token. */
325
+ 'bearer',
326
+ /** An API key; a secret typed in at the prompt becomes an API key. */
327
+ 'api_key',
328
+ /** An OAuth sign-in; the host supplies the token. */
329
+ 'oauth2',
330
+ ];
176
331
  /** Adds UI-only `none`, which omits auth at compile time. */
177
- export const STUDIO_AUTH_TYPES = ['none', ...TOOL_AUTH_TYPES];
332
+ export const STUDIO_AUTH_TYPES = [
333
+ /** The tool sends no credential. */
334
+ 'none',
335
+ ...TOOL_AUTH_TYPES,
336
+ ];
178
337
  /**
179
338
  * The package's complete media-input vocabulary: `assertMediaMime` refuses any MIME not
180
339
  * here, so hosts keep no second table. Rows follow Google Interactions / Live's documented
@@ -263,9 +422,18 @@ export const VOICE_ACCEPT_MIMES = ['audio/*', ...mimesOf('audio')];
263
422
  function unionType(values) {
264
423
  return values.map((value) => `'${value}'`).join(' | ');
265
424
  }
266
- function field(type, doc, options, optionDescriptionsOrNote, optionNote) {
425
+ /** A field a kernel type declares: its doc is the JSDoc there, through `FIELD_DOCS`. */
426
+ function field(type, options, optionDescriptionsOrNote, optionNote) {
427
+ return metaField(type, '', options, optionDescriptionsOrNote, optionNote);
428
+ }
429
+ /**
430
+ * A detector or boundary row: its doc is `DETECTOR_META`'s or `BOUNDARY_META`'s, since a member
431
+ * of a string union has no JSDoc.
432
+ */
433
+ function metaField(type, doc, options, optionDescriptionsOrNote, optionNote) {
267
434
  if (options) {
268
435
  if (typeof optionDescriptionsOrNote === 'object') {
436
+ sourcedOptionDocs(options, optionDescriptionsOrNote);
269
437
  return optionNote
270
438
  ? { type, doc, options, optionDescriptions: optionDescriptionsOrNote, optionNote }
271
439
  : { type, doc, options, optionDescriptions: optionDescriptionsOrNote };
@@ -277,6 +445,16 @@ function field(type, doc, options, optionDescriptionsOrNote, optionNote) {
277
445
  }
278
446
  return { type, doc };
279
447
  }
448
+ /**
449
+ * Throws unless the docs are a list's `OPTION_DOCS` entry, or `DETECT_ACTION_META`'s, and name
450
+ * exactly these options, so a value's doc has one source.
451
+ */
452
+ function sourcedOptionDocs(options, docs) {
453
+ const sourced = Object.values(OPTION_DOCS).includes(docs) ||
454
+ DETECT_ACTIONS.every((action) => docs[action] === DETECT_ACTION_META[action].doc);
455
+ if (!sourced)
456
+ throw new Error(`option docs for ${options.join(', ')} are not a list's JSDoc`);
457
+ }
280
458
  /**
281
459
  * Parents whose next key is a host-owned map key (model id, slot name, …).
282
460
  * The annotator substitutes `*` so `models.flash.apiId` → `models.*.apiId`.
@@ -313,98 +491,66 @@ const DETECT_ACTION_DOCS = recordOf(DETECT_ACTIONS, (action) => DETECT_ACTION_ME
313
491
  function allowFields(path, detector) {
314
492
  if (DETECTOR_META[detector].allow === 'names') {
315
493
  return [
316
- [`${path}.allow`, field('NameAllow', 'The names that are innocent in a reply.')],
494
+ [`${path}.allow`, field('NameAllow')],
317
495
  [
318
496
  `${path}.allow.names`,
319
497
  {
320
- ...field('string[]', 'Names of tools or parameters that are not read for, such as a tool called search.'),
498
+ ...field('string[]'),
321
499
  unset: 'None',
322
500
  },
323
501
  ],
324
502
  ];
325
503
  }
326
- const hosts = detector === 'ungiven_links'
327
- ? 'Hostnames whose links pass whatever their URL; the hosts ungiven_images allows pass too.'
328
- : 'Hostnames whose images load whatever their URL, such as your own CDN.';
329
504
  return [
330
- [
331
- `${path}.allow`,
332
- field('UrlAllow', 'What passes besides the URLs the model was given this turn.'),
333
- ],
334
- [`${path}.allow.hosts`, { ...field('string[]', hosts), unset: 'None' }],
505
+ [`${path}.allow`, field('UrlAllow')],
506
+ [`${path}.allow.hosts`, { ...field('string[]'), unset: 'None' }],
335
507
  [
336
508
  `${path}.allow.fromTools`,
337
509
  {
338
- ...field('boolean', 'Whether a URL a tool returned counts as given. Off keeps only what the system prompt, the user, and history gave.'),
510
+ ...field('boolean'),
339
511
  unset: 'On',
340
512
  },
341
513
  ],
342
514
  ];
343
515
  }
344
- const COMPILED_DOC = 'The table your patterns compile to, from compileDetect or `agents detect-compile`. Needed whenever patterns is set.';
345
516
  /** The rows of one pattern in a detector's `patterns`. */
346
517
  function patternRows(path) {
347
518
  const each = `${path}.patterns.*`;
348
519
  return [
349
- [`${each}.name`, field('string', 'What a match is called in the trace.')],
350
- [
351
- `${each}.pattern`,
352
- field('string', 'The source of a regular expression. A pattern takes this or words.'),
353
- ],
520
+ [`${each}.name`, field('string')],
521
+ [`${each}.pattern`, field('string')],
354
522
  [
355
523
  `${each}.flags`,
356
524
  {
357
- ...field('string', 'Regular-expression flags, each a letter: i ignores case, m matches ^ and $ at each line, s lets . match a line break, u reads Unicode. Not g or y: every match is always found.'),
525
+ ...field('string'),
358
526
  unset: 'None',
359
527
  },
360
528
  ],
361
- [
362
- `${each}.words`,
363
- field('string[]', 'Words to match whole, whatever their case. A space in one matches any run of whitespace.'),
364
- ],
529
+ [`${each}.words`, field('string[]')],
365
530
  ];
366
531
  }
367
532
  /** The rows of a detector of the host's own, under a key with a dot. */
368
533
  function hostDetectorFields(path) {
369
- const action = (doc) => field('DetectAction', doc, DETECT_ACTIONS, DETECT_ACTION_DOCS);
534
+ const action = (doc) => doc
535
+ ? metaField('DetectAction', doc, DETECT_ACTIONS, DETECT_ACTION_DOCS)
536
+ : field('DetectAction', DETECT_ACTIONS, DETECT_ACTION_DOCS);
370
537
  return [
371
- [
372
- path,
373
- field('HostDetectorConfig', 'Your own detector, keyed with a dot: acme.codenames. No default action.'),
374
- ],
375
- [`${path}.label`, field('string', 'What an editor and the trace call it.')],
538
+ [path, field('HostDetectorConfig')],
539
+ [`${path}.label`, field('string')],
376
540
  [
377
541
  `${path}.action`,
378
542
  {
379
- ...action('What a match does, at every boundary.'),
543
+ ...action(),
380
544
  unset: 'Only the boundaries at names are read',
381
545
  },
382
546
  ],
383
- [`${path}.at`, field('{ [boundary]: DetectAction }', 'An action per boundary, over action.')],
547
+ [`${path}.at`, field('{ [boundary]: DetectAction }')],
384
548
  ...BOUNDARIES.map((boundary) => [
385
549
  `${path}.at.${boundary}`,
386
550
  { ...action(BOUNDARY_META[boundary].doc), unset: DETECT_ACTION_META.ignore.label },
387
551
  ]),
388
- [
389
- `${path}.patterns`,
390
- {
391
- ...field('HostPattern[]', 'Its patterns, each a name and a regular expression or a list of words, read on the text as written.'),
392
- unset: 'None',
393
- },
394
- ],
395
- ...patternRows(path),
396
- [`${path}.compiled`, field('CompiledPatterns', COMPILED_DOC)],
397
- [
398
- `${path}.hint`,
399
- {
400
- ...field('string', 'One line telling the model what to leave out, sent when this detector blocks a reply that is then retried.'),
401
- unset: 'The labels’s detect.hint.own, which names the label',
402
- },
403
- ],
404
- [
405
- `${path}.find`,
406
- field('HostFind', 'Its own reading, for what patterns cannot say: a function that returns where the matches start and end. It runs on every text crossing a boundary the detector reads, so it returns at once.'),
407
- ],
552
+ ...patternTail(path, 'The labels’s detect.hint.own, which names the label'),
553
+ [`${path}.find`, field('HostFind')],
408
554
  ];
409
555
  }
410
556
  /** The rows of a detector that reads with patterns: whose it reads with. */
@@ -413,26 +559,20 @@ function patternFields(path) {
413
559
  [
414
560
  `${path}.theorem`,
415
561
  {
416
- ...field('boolean', 'Whether Theorem’s own patterns run. Off with no patterns of your own turns the detector off.'),
562
+ ...field('boolean'),
417
563
  unset: 'On',
418
564
  },
419
565
  ],
420
- [
421
- `${path}.patterns`,
422
- {
423
- ...field('HostPattern[]', 'Your own patterns, each a name and a regular expression or a list of words. A match takes this detector’s action.'),
424
- unset: 'None',
425
- },
426
- ],
566
+ ...patternTail(path, 'The labels’s detect.hint line for this detector'),
567
+ ];
568
+ }
569
+ /** The patterns, compiled patterns and hint rows a detector that reads with patterns shares. */
570
+ function patternTail(path, hintUnset) {
571
+ return [
572
+ [`${path}.patterns`, { ...field('HostPattern[]'), unset: 'None' }],
427
573
  ...patternRows(path),
428
- [`${path}.compiled`, field('CompiledPatterns', COMPILED_DOC)],
429
- [
430
- `${path}.hint`,
431
- {
432
- ...field('string', 'One line telling the model what to leave out, sent when this detector blocks a reply that is then retried. Set it beside patterns of your own.'),
433
- unset: `The labels’s detect.hint line for this detector`,
434
- },
435
- ],
574
+ [`${path}.compiled`, field('CompiledPatterns')],
575
+ [`${path}.hint`, { ...field('string'), unset: hintUnset }],
436
576
  ];
437
577
  }
438
578
  /** The settings a detector's full form takes, as a sentence lists them. */
@@ -446,12 +586,11 @@ function settingsOf(detector) {
446
586
  }
447
587
  /** The `guardrails.detect` rows: one for the setting, one per detector, and one per detector and boundary. */
448
588
  function detectFields() {
449
- const action = (type, doc) => field(type, doc, DETECT_ACTIONS, DETECT_ACTION_DOCS);
589
+ const action = (type, doc) => doc
590
+ ? metaField(type, doc, DETECT_ACTIONS, DETECT_ACTION_DOCS)
591
+ : field(type, DETECT_ACTIONS, DETECT_ACTION_DOCS);
450
592
  const rows = [
451
- [
452
- 'guardrails.detect',
453
- action('DetectAction | { [detector]: DetectorRule }', 'What a guardrail does when a detector matches. One action covers every detector; an object sets each detector (or one of your own) apart. Absent: each detector keeps its default action.'),
454
- ],
593
+ ['guardrails.detect', action('DetectAction | { [detector]: DetectorRule }')],
455
594
  ];
456
595
  for (const detector of DETECTORS) {
457
596
  const path = `guardrails.detect.${detector}`;
@@ -466,14 +605,11 @@ function detectFields() {
466
605
  rows.push([
467
606
  `${path}.action`,
468
607
  {
469
- ...action('DetectAction', 'What a match of this detector does at every boundary it reads, unless `at` names that boundary.'),
608
+ ...action('DetectAction'),
470
609
  unset: 'Each boundary keeps its default',
471
610
  },
472
611
  ]);
473
- rows.push([
474
- `${path}.at`,
475
- field('{ [boundary]: DetectAction }', 'An action per boundary, over action or the default.'),
476
- ]);
612
+ rows.push([`${path}.at`, field('{ [boundary]: DetectAction }')]);
477
613
  for (const boundary of DETECTOR_BOUNDARIES[detector]) {
478
614
  const unset = DETECT_ACTION_META[DETECT_DEFAULTS[detector][boundary]].label;
479
615
  const meta = action('DetectAction', BOUNDARY_META[boundary].doc);
@@ -483,8 +619,20 @@ function detectFields() {
483
619
  rows.push(...hostDetectorFields('guardrails.detect.*'));
484
620
  return Object.fromEntries(rows);
485
621
  }
486
- function withScopeAndPresence(fields) {
622
+ /** Gives each field its doc from `FIELD_DOCS`; a field that also writes one here throws, so one text has one source. */
623
+ function withFieldDocs(fields) {
487
624
  return Object.fromEntries(Object.entries(fields).map(([path, meta]) => {
625
+ const declared = FIELD_DOCS[path];
626
+ if (declared === undefined)
627
+ return [path, meta];
628
+ if (meta.doc) {
629
+ throw new Error(`${path}: a kernel type declares it, so its doc is that JSDoc; use field()`);
630
+ }
631
+ return [path, { ...meta, doc: declared }];
632
+ }));
633
+ }
634
+ function withScopeAndPresence(fields) {
635
+ return Object.fromEntries(Object.entries(withFieldDocs(fields)).map(([path, meta]) => {
488
636
  const scope = profileFieldScope(path);
489
637
  return [
490
638
  path,
@@ -497,470 +645,363 @@ function withScopeAndPresence(fields) {
497
645
  }));
498
646
  }
499
647
  /**
500
- * Adding a profile field? Add it here; scope it in `PROFILE_FIELD_SCOPE` if only some types
501
- * take it, and record it in `PROFILE_FIELD_PRESENCE` if it is required or its absence matters.
648
+ * Adding a profile field? Write its doc as JSDoc on the type, run `deno task field-docs`, and add
649
+ * it here with `field()`; scope it in `PROFILE_FIELD_SCOPE` if only some types take it, and record
650
+ * it in `PROFILE_FIELD_PRESENCE` if it is required or its absence matters. A map's entries
651
+ * (`models.*`) take their doc from a `@catalog <path> <text>` tag on the map's property.
502
652
  */
503
653
  export const PROFILE_FIELDS = withScopeAndPresence({
504
- 'profile.id': field('string', 'The name this profile is registered and looked up by, at most 64 characters; registering the same id again replaces it.'),
505
- 'profile.type': field("'text' | 'image' | 'speech' | 'transcription' | 'live' | 'decision' | 'embedding' | 'host'", 'What kind of agent this is, and so what each call gives back: text, image, speech, transcription, live, decision, embedding, or host.', PROFILE_TYPES, {
506
- text: 'A chat or task agent. Each turn the model answers in text, or in JSON when outputs ask for a structured reply, and can call tools on the way.',
507
- image: 'Makes pictures from a prompt, in the shape, size, and format the image block sets.',
508
- speech: 'Gives your app a voice. Each turn reads text aloud in the voice the speech block names.',
509
- transcription: 'Turns a voice clip into text. Each turn takes one clip and gives back what was said.',
510
- live: 'For talking in real time. One continuous voice and video session, rather than separate turns.',
511
- decision: 'For when your app needs a judgement, not a reply. It answers questions about a JSON state, each with a choice, a score, or a number.',
512
- embedding: 'For when your app needs vectors from text or provider-supported media.',
513
- host: 'A governed passthrough to your tool registry, with no model. It calls MCP, HTTP, and in-app function tools under the same permissions and traces as any agent, guarded by detect and network.',
514
- }),
515
- identity: field('{ handle, options?, system? }', "The agent's display name and the system instruction it is given."),
516
- 'identity.handle': field('string', 'The name hosts and users see for this agent, at most 32 characters; the model never sees it.'),
517
- 'identity.options': field('Record<string, OptionDecl>', 'The options the host\'s code sets on runTurn, which a person never sees. A line of identity.system reads one as "when plan is free: …" and prints it as {plan}. One named path holds the turn\'s path.'),
518
- 'identity.options.*': field('OptionDecl', '{ label?, choices: { value, description? }[] }, the same shape as inputs.options.*.'),
519
- 'identity.options.*.label': field('string', "A person-readable title. Omit to show the option's name."),
520
- 'identity.options.*.choices': field('OptionChoice[]', 'The values this option can take.'),
521
- 'identity.options.*.choices.*.value': field('string', 'The value the code sets, which `when` reads and {name} prints.'),
522
- 'identity.options.*.choices.*.description': field('string', 'What this value means. It is never sent to the model.'),
523
- 'identity.system': field('string | Array<string | Array<string | { private: string }>>', 'The instruction the model gets, as one string or a list of lines; some providers send it for an image profile only with includeText on. A line that opens "when plan is free: …" goes only on turns where that fits, and every line that fits is sent, a blank line apart. A line can be a list of parts; mark what must not leak as { private: text }; only that is guarded. With none, the whole prompt is.'),
524
- models: field('Record<ModelId, ModelBinding | DecisionModelBinding>', 'The trained AI systems that turn input into results. Each entry binds a local name to an upstream model and its call settings.'),
525
- 'models.*': field('ModelBinding | DecisionModelBinding', 'One model: how to reach it and the settings sent with it.'),
526
- 'models.*.protocol': field('string', 'The API shape this model is spoken to in.'),
527
- 'models.*.provider': field('string', 'The service that runs the model or routes requests to one, such as Gemini or OpenRouter. Its registration supplies the endpoint and authentication.'),
528
- 'models.*.keySlot': field('KeySlot', "The key slot this model's calls are signed with, instead of the provider's. Use it to bill one model to a different key. Absent: the provider's primary slot."),
529
- 'models.*.fallbackKeySlot': field('KeySlot', "The key slot tried once after a rate limit or a busy model on the primary slot, instead of the provider's fallback. Must differ from the primary slot. Absent: the provider's fallback slot, if it has one."),
530
- 'models.*.options': field('JsonObject', "Settings only this model's protocol has, such as a task type or vector size. Each is checked when the profile loads. Any left out keep the provider's default."),
531
- providerContinuation: field('ProviderContinuationPolicy', 'Who holds the conversation a saved provider state continues.'),
532
- 'providerContinuation.history': field("'host' | 'stateless' | 'provider'", 'Who holds the conversation a checkpoint continues: the host passes history back, the provider keeps it and the checkpoint travels alone, or the profile is stateless and every request stands alone.', ['host', 'stateless', 'provider']),
533
- 'models.*.apiId': field('string', "The model's id as the provider lists it, such as gemini-2.5-flash; sent on every call. The name this model has in the profile is its key in models."),
534
- 'models.*.timeoutMs': field('number', 'How long a decision waits for its provider, in milliseconds. Omit for no timeout.'),
535
- 'models.*.limits': field('ProviderLimits', "The points at which Theorem stops this model's calls. Each one left out is no limit, so the provider's own limits apply. A runTurn limits value overrides each field it sets."),
536
- 'models.*.limits.operationTimeoutMs': field('number', 'How long one call may take, in milliseconds, retries included.'),
537
- 'models.*.limits.connectTimeoutMs': field('number', 'How long a live session may take to open, in milliseconds.'),
538
- 'models.*.limits.liveStepTimeoutMs': field('number', 'How long a live session may wait for the model to answer, in milliseconds.'),
539
- 'models.*.limits.maxWireRecordBytes': field('number', 'The most bytes in one record the provider sends: a stream event or a socket message.'),
540
- 'models.*.limits.maxWireResponseBytes': field('number', 'The most bytes the provider sends for one step.'),
541
- 'models.*.limits.maxEventBytes': field('number', 'The most bytes in one event of a step.'),
542
- 'models.*.limits.maxStepBytes': field('number', 'The most bytes in all the events of one step.'),
543
- 'models.*.limits.maxStepEvents': field('number', 'The most events in one step.'),
544
- 'models.*.limits.maxPendingToolCalls': field('number', 'The most tool calls one step may ask for.'),
545
- decision: field('{ contract: DecisionContractId }', 'Names the host decision this profile makes.'),
546
- 'decision.contract': field('string', 'Your name for this decision, on its traces. Not sent to the model. Not checked against the questions.'),
547
- 'models.*.efforts': field('Record<string, ThinkingLevel>', 'Named thinking levels. A turn picks one when allowEffortSelect is on. A provider refuses a level its model does not take. Speech ignores them, and so may an image profile without includeText.'),
548
- 'models.*.efforts.*': field(unionType(THINKING_LEVELS), 'The thinking level sent to the provider for this name.', THINKING_LEVELS, {
549
- none: 'No thinking, where the provider has that level.',
550
- minimal: 'The least thinking.',
551
- low: 'Light thinking.',
552
- medium: 'Moderate thinking.',
553
- high: 'Heavy thinking.',
554
- xhigh: 'Heavier thinking, where the provider has that level.',
555
- max: 'The most thinking the model supports, where the provider has that level.',
556
- }),
557
- 'models.*.defaultEffort': field('string', "The effort a turn gets when it doesn't pick one."),
558
- 'models.*.allowEffortSelect': field('boolean', 'Lets a turn pick an effort; needs two or more efforts.'),
559
- 'models.*.summaries': field('boolean', 'Asks the model for summaries of its thinking, which not every model sends; with some providers, off only hides thoughts, and others ignore it.'),
560
- 'models.*.maxOutputTokens': field('number', 'The token limit for one reply. Some providers never send it for speech, or for image without includeText.'),
561
- 'models.*.temperature': field('number', "How varied the model's wording is; higher is more random. Some providers never send it for speech, or for image without includeText."),
562
- 'models.*.builtInTools': field('BuiltinToolId[]', "The provider's own tools, such as Google Search, this model may use; each must be registered as a builtin tool and declared by the provider's adapter."),
563
- 'models.*.compaction': field('CompactionSpec', 'Summarises history past a threshold. A text agent can write the summary. Other types name a compaction profile.'),
564
- 'models.*.compaction.maxTokens': field('number', 'The token budget compactAt is a fraction of.'),
565
- 'models.*.compaction.trigger': field('(ctx: CompactionTriggerContext) => boolean | Promise<boolean>', 'Your function that decides when to compact, in place of compactAt and maxTokens.'),
566
- 'models.*.compaction.compactAt': field('number', 'The fraction of maxTokens, between 0 and 1, at which compaction starts, unless trigger decides.'),
567
- 'models.*.compaction.previousExchanges': field('number', 'How much recent history compaction keeps: a number of exchanges (1 or more), a fraction of maxTokens below compactAt, or 0 to compact it all.'),
654
+ 'profile.id': field('string'),
655
+ 'profile.type': field("'text' | 'image' | 'speech' | 'transcription' | 'live' | 'decision' | 'embedding' | 'host'", PROFILE_TYPES, OPTION_DOCS.PROFILE_TYPES),
656
+ identity: field('{ handle, options?, system? }'),
657
+ 'identity.handle': field('string'),
658
+ 'identity.options': field('Record<string, OptionDecl>'),
659
+ 'identity.options.*': field('OptionDecl'),
660
+ 'identity.options.*.label': field('string'),
661
+ 'identity.options.*.choices': field('OptionChoice[]'),
662
+ 'identity.options.*.choices.*.value': field('string'),
663
+ 'identity.options.*.choices.*.description': field('string'),
664
+ 'identity.system': field('string | Array<string | Array<string | { private: string }>>'),
665
+ models: field('Record<ModelId, ModelBinding | DecisionModelBinding>'),
666
+ 'models.*': field('ModelBinding | DecisionModelBinding'),
667
+ 'models.*.protocol': field('string'),
668
+ 'models.*.provider': field('string'),
669
+ 'models.*.keySlot': field('KeySlot'),
670
+ 'models.*.fallbackKeySlot': field('KeySlot'),
671
+ 'models.*.options': field('JsonObject'),
672
+ providerContinuation: field('ProviderContinuationPolicy'),
673
+ 'providerContinuation.history': field("'host' | 'stateless' | 'provider'", [
674
+ 'host',
675
+ 'stateless',
676
+ 'provider',
677
+ ]),
678
+ 'models.*.apiId': field('string'),
679
+ 'models.*.timeoutMs': field('number'),
680
+ 'models.*.limits': field('ProviderLimits'),
681
+ 'models.*.limits.operationTimeoutMs': field('number'),
682
+ 'models.*.limits.connectTimeoutMs': field('number'),
683
+ 'models.*.limits.liveStepTimeoutMs': field('number'),
684
+ 'models.*.limits.maxWireRecordBytes': field('number'),
685
+ 'models.*.limits.maxWireResponseBytes': field('number'),
686
+ 'models.*.limits.maxEventBytes': field('number'),
687
+ 'models.*.limits.maxStepBytes': field('number'),
688
+ 'models.*.limits.maxStepEvents': field('number'),
689
+ 'models.*.limits.maxPendingToolCalls': field('number'),
690
+ decision: field('{ contract: DecisionContractId }'),
691
+ 'decision.contract': field('string'),
692
+ 'models.*.efforts': field('Record<string, ThinkingLevel>'),
693
+ 'models.*.efforts.*': field(unionType(THINKING_LEVELS), THINKING_LEVELS, OPTION_DOCS.THINKING_LEVELS),
694
+ 'models.*.defaultEffort': field('string'),
695
+ 'models.*.allowEffortSelect': field('boolean'),
696
+ 'models.*.summaries': field('boolean'),
697
+ 'models.*.maxOutputTokens': field('number'),
698
+ 'models.*.temperature': field('number'),
699
+ 'models.*.builtInTools': field('BuiltinToolId[]'),
700
+ 'models.*.compaction': field('CompactionSpec'),
701
+ 'models.*.compaction.maxTokens': field('number'),
702
+ 'models.*.compaction.trigger': field('(ctx: CompactionTriggerContext) => boolean | Promise<boolean>'),
703
+ 'models.*.compaction.compactAt': field('number'),
704
+ 'models.*.compaction.previousExchanges': field('number'),
568
705
  'models.*.compaction.profile': {
569
- ...field('ProfileId', 'The text profile that writes the summary; register it before this one. Leave it out and a text agent summarises its own history, with its own instructions and model and no tools. Its registered model binding selects the provider independently of the calling agent.'),
706
+ ...field('ProfileId'),
570
707
  unset: 'The agent itself',
571
708
  },
572
- 'models.*.compaction.timing': field(unionType(COMPACTION_TIMINGS), 'Whether the kernel compacts before the turn or tells the host to compact after it.', COMPACTION_TIMINGS, {
573
- before: 'The kernel compacts before the turn runs.',
574
- after: "The turn's done event says compaction is due, and the host runs it.",
575
- }),
576
- 'models.*.compaction.meter': field(unionType(COMPACTION_METERS), 'What the threshold counts.', COMPACTION_METERS, {
577
- history: 'Tokens in the earlier conversation.',
578
- input: 'The prompt tokens the provider reported for the last call, or the count the host passes in.',
579
- }),
580
- 'profile.defaultModel': field('ModelId', "The model a turn gets when it doesn't pick one."),
581
- 'profile.allowModelSelect': field('boolean', 'Lets a turn name the model it runs on; a name the profile does not declare is refused.'),
582
- 'profile.maxSteps': field('number', 'The most model calls one turn may make while using tools, counted afresh for each rewrite; 1 runs the tools asked for but never sends their results back. Live sessions ignore it.'),
583
- tools: field('{ allow: ToolId[]; t1Policy?; t2Loader?; parallel? }', 'The registered tools this profile may use, and how they load. Built-in tools are set per model.'),
584
- 'tools.allow': field('ToolId[]', "Your registered tools this agent may use; the provider's own tools go on the model's builtInTools instead."),
585
- 'tools.t1Policy': field('(ctx) => ToolId[] | Promise<ToolId[]>', 'Your function that picks, at the start of each turn, which T2 tools to load up front; the rest wait for tools.t2Loader.'),
586
- 'tools.t2Loader': field('ToolId', "The function tool that loads T2 tools. It must be in allow and return { loaded: ToolId[] }. One forbidden id fails the load. Ids off the turn path are skipped. The tools it loads can be called from the next step: a step's calls see the tools as they stood when the step began."),
587
- 'tools.parallel': field('boolean', 'true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts its body once those calls settle. Left out or false: they run one at a time, in the order the model made them. A step is the calls the model makes together in a turn, or the calls a host runs through invokeToolStep.'),
588
- inputs: field('ProfileInputsSpec | DecisionInputsSpec', 'What a turn may send (text, files, voice, choices), or on a decision, the state it reads.'),
589
- 'inputs.state': field("'json'", 'A decision reads JSON state, passed on each call.', ['json']),
590
- 'inputs.maxStateBytes': field('number', 'The largest state, in bytes, a decision call may send; larger state is refused before it leaves your process.'),
591
- 'inputs.text': field('boolean', 'Whether a turn may send text.'),
592
- 'inputs.attachments': field('{ accept: string[] }', 'Lets turns send files.'),
593
- 'inputs.attachments.accept': field('string[]', 'The file types a turn may send, where type/* matches a whole family; image profiles take only images, video, and PDF.', ATTACHMENT_ACCEPT_MIMES, "Types the kernel knows; a listed type it doesn't know is refused when a turn sends it."),
594
- 'inputs.voice': field('{ accept: string[] }', 'Lets turns send voice clips. A transcription profile must set it.'),
595
- 'inputs.voice.accept': field('string[]', 'The audio types a voice clip may be; audio/* matches them all.', VOICE_ACCEPT_MIMES, 'Audio types the kernel knows.'),
596
- 'inputs.maxFiles': field('number', 'The most files and voice clips one turn or embedding request may send, counted together.'),
597
- 'inputs.maxBytes': field('number', 'The largest file or clip, in bytes, a turn or embedding request may send inline.'),
598
- 'inputs.maxTurnBytes': field('number', 'The most bytes one turn or embedding request may send inline across all its files and clips.'),
599
- 'inputs.limitsByMime': field('Record<string, number>', 'Size limits by file type that replace maxBytes for those types.'),
600
- 'inputs.limitsByMime.*': field('number', 'The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.'),
601
- 'inputs.options': field('Record<string, OptionDecl>', 'The options a person picks, each shown as a picker. A prompt reads one as "when reader is student: …" and prints it as {reader}.'),
602
- 'inputs.options.*': field('OptionDecl', '{ label?, choices: { value, description? }[] }. Value is what the turn sends and what {name} prints.'),
603
- 'inputs.options.*.label': field('string', "Visitor-facing title for this option in the composer (for example Source Bias). Omit to show the option's name."),
604
- 'inputs.options.*.choices': field('OptionChoice[]', 'The values this option can take, each with an optional UI description.'),
605
- 'inputs.options.*.choices.*.value': field('string', 'The value the turn sends for this choice, which `when` reads and {name} prints.'),
606
- 'inputs.options.*.choices.*.description': field('string', 'Visitor-facing blurb for this choice in the composer. Never substituted into prompts.'),
607
- 'inputs.context': field('{ from: ContextSender[]; maxChars: number }', 'Lets the page or the host send the agent one package of things to know, read at the context boundary.'),
608
- 'inputs.context.from': field("Array<'client' | 'server'>", 'Who may send context; context from anyone else is refused.', CONTEXT_SENDERS, {
609
- client: 'The browser. A visitor can change it, so it is untrusted.',
610
- server: "The host's own code. It is assembled, like turn system text.",
611
- }),
612
- 'inputs.context.maxChars': field('number', 'The longest package, in characters of its JSON, each sender may send.'),
613
- outputs: field('ProfileOutputsSpec', 'The shape of the reply, how it is checked, and how it streams.'),
614
- 'outputs.structured': field('StructuredSchemaId | StructuredByOption | null', 'The registered JSON schema the reply must follow, which can vary by option; register it before the profile.'),
615
- image: field('ProfileImageSpec', 'How the images this profile generates are shaped and made: size, format, quality and references. Each setting is sent only where the provider has it; one it lacks is refused or ignored, as that setting says.'),
616
- 'image.aspectRatio': field('string', 'The shape of generated images, such as 16:9.'),
617
- 'image.resolution': field('string', 'How detailed generated images are, such as 1K, 2K or 4K.'),
618
- 'image.mimeType': field('string', 'The file type of generated images; a provider that takes a fixed set of types may use png for any other.'),
619
- 'image.quality': field('string', 'How much effort the model spends on each image: auto, low, medium, or high. A provider that has no such setting refuses it.'),
620
- 'image.background': field('string', 'The background of generated images: auto, transparent, or opaque. A provider that has no such setting refuses it.'),
621
- 'image.n': field('number', 'How many images one request makes, where the provider takes a count.'),
622
- 'image.seed': field('number', 'A seed for repeatable images, where the provider and the model honour it.'),
623
- 'image.outputCompression': field('number', 'Compression from 0 to 100 for jpeg and webp images, where the provider takes it.'),
624
- 'image.references': field('Array<TurnBlob | TurnMediaRef>', "Images sent with every turn, before the user's. Each is bytes (`data`) or a link (`uri`). Some providers take http(s) links only, and none with includeText."),
625
- 'image.includeText': field('boolean', 'Whether the model may write text alongside its images; with some providers this also sends the system instruction and history.'),
626
- speech: field('ProfileSpeechSpec', "How the profile's speech sounds and is delivered: voice, style, speed and audio format. A turn may replace voice, style and speed for that turn."),
627
- 'speech.voice': field('string', "The voice the speech is read in, by the provider's own name for it; a turn's speech.voice replaces it."),
628
- 'speech.style': field('string', "How the script is delivered, in plain words (pace, mood, accent); it is never read aloud, and a turn's speech.style replaces it. A model that takes no direction ignores it."),
629
- 'speech.speed': field('number', "The speaking rate, where 1 is the voice's own pace; a turn's speech.speed replaces it. A provider that has no rate refuses it or ignores it."),
630
- 'speech.format': field(unionType(SPEECH_AUDIO_FORMATS), "The audio encoding each turn's speech comes back in, and so what the host plays or stores.", SPEECH_AUDIO_FORMATS, {
631
- pcm: 'Uncompressed audio, delivered as WAV.',
632
- mp3: 'Compressed audio; a provider that cannot make it refuses the turn.',
633
- }),
634
- live: field('ProfileLiveSpec', 'How a realtime voice and video session runs: what it accepts from the user, the voice it answers in, when it hears the user start and stop, and how it resumes and trims its context.'),
635
- 'live.ingress': field('LiveIngressSpec', 'Which channels the session accepts from the user.'),
636
- 'live.ingress.audio': field('boolean', 'Whether the session accepts microphone audio.'),
637
- 'live.ingress.video': field('boolean', 'Whether the session accepts camera frames.'),
638
- 'live.ingress.text': field('boolean', 'Whether the session accepts typed text.'),
639
- 'live.voice': field('string', 'The voice the model speaks in.'),
640
- 'live.vad': field('LiveVadSpec', 'How the session detects when the user starts and stops speaking.'),
641
- 'live.vad.activityHandling': field(unionType(LIVE_ACTIVITY_HANDLINGS), "Whether the user speaking interrupts the model's reply.", LIVE_ACTIVITY_HANDLINGS, {
642
- START_OF_ACTIVITY_INTERRUPTS: 'The user speaking cuts the reply off.',
643
- NO_INTERRUPTION: 'The model finishes its reply.',
644
- }),
645
- 'live.vad.startSensitivity': field(unionType(LIVE_START_SENSITIVITIES), 'How readily the session decides the user has started speaking.', LIVE_START_SENSITIVITIES, {
646
- START_SENSITIVITY_LOW: 'Detects the start of speech less often.',
647
- START_SENSITIVITY_HIGH: 'Detects the start of speech more often.',
648
- }),
649
- 'live.vad.endSensitivity': field(unionType(LIVE_END_SENSITIVITIES), 'How readily the session decides the user has stopped speaking.', LIVE_END_SENSITIVITIES, {
650
- END_SENSITIVITY_LOW: 'Ends speech less often, waiting through pauses.',
651
- END_SENSITIVITY_HIGH: 'Ends speech more often, at shorter pauses.',
652
- }),
653
- 'live.vad.prefixPaddingMs': field('number', 'How long speech must last, in milliseconds, before it counts as the user starting to speak.'),
654
- 'live.vad.silenceDurationMs': field('number', "How long a silence, in milliseconds, ends the user's speech."),
655
- 'live.sessionResumption': field('boolean', 'Whether the provider sends resume handles, which the host can pass to a new session to carry this one on.'),
656
- 'live.greeting': field('string', 'A prompt the call sends itself when it opens new, so the agent speaks first. The visitor does not see it. It may use {name}, and is not sent when an option it prints is unset.'),
657
- 'live.resumed': field('{ prompt: string; afterMs?: number }', 'What happens when a call comes back after a drop. It needs live.sessionResumption.'),
658
- 'live.resumed.prompt': field('string', 'A prompt the call sends itself when it resumes, so the agent says it is back. The visitor does not see it. It may use {name}, and is not sent when an option it prints is unset.'),
659
- 'live.resumed.afterMs': field('number', 'The shortest time away, in milliseconds, that earns the prompt; a shorter drop resumes silently.'),
660
- 'live.contextCompression': field('LiveContextCompressionSpec', "Trims the session's context once it grows past the trigger."),
661
- 'live.contextCompression.triggerTokens': field('number', 'The context size, in tokens, that starts trimming.'),
662
- 'live.contextCompression.slidingWindow': field('LiveSlidingWindowSpec', 'Trims by dropping the oldest turns; the system instruction stays.'),
663
- 'live.contextCompression.slidingWindow.targetTokens': field('number', 'The context size, in tokens, to trim down to; below the trigger.'),
664
- 'live.transcription': field('LiveTranscriptionSpec', "Text transcripts of the session's speech."),
665
- 'live.transcription.input': field('boolean', "Whether the user's speech is transcribed."),
666
- 'live.transcription.output': field('boolean', "Whether the model's speech is transcribed; always on while a detector reads live_reply, since it reads the transcript."),
667
- 'outputs.validation': field('ProfileValidationSpec', 'Your checks on a structured reply, and how many rewrites a failure gets.'),
668
- 'outputs.validation.fields': field('Record<string, ProfileValidator>', 'Your checks, each keyed by a dotted path into the structured reply, such as diagram.mermaid; a path no structured schema reaches is refused when the profile registers.'),
669
- 'outputs.validation.fields.*': field('(candidate: unknown, options?: Record<string, string>) => ValidationResult | Promise<ValidationResult>', '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.'),
670
- 'outputs.validation.items': field('Record<string, ProfileItemRule>', 'Your checks on the items of a list, each keyed by the dotted path of that list in the structured reply, such as claims; a path no structured schema reaches as a list is refused when the profile registers.'),
671
- 'outputs.validation.items.*': field('ProfileItemRule', 'Your check on each item of this list. A refused item never fails the reply and the rest of the reply is kept.'),
672
- 'outputs.validation.items.*.check': field('(item: unknown, turn: ItemCheckTurn) => ValidationResult | Promise<ValidationResult>', 'Your check on one item, given what the tools of the turn returned (turn.toolResults); its error is the reason the model reads on a rewrite and the host reads on the removed item.'),
673
- 'outputs.validation.items.*.onFail': field("'drop' | 'fix'", 'drop removes a refused item. fix first asks the model to rewrite the refused items alone, once and while retries remain, then removes any refused again. Removed items leave on the structured event as removed.', ITEM_FAIL_ACTIONS),
674
- 'outputs.validation.maxRetries': field('number', "How many times the model may rewrite a reply that fails your checks or the schema's required keys before it goes out as it is; under sse, an attempt that gets rewritten has already streamed. A rewrite of a blocked reply (guardrails.blockedReply) counts against this too."),
675
- 'outputs.streaming': field('ProfileStreamingSpec', 'How the reply reaches the host, and whether its thinking does.'),
676
- 'outputs.streaming.mode': field(unionType(STREAM_MODES), 'Whether the reply reaches the host as the model writes it, or whole.', STREAM_MODES, {
677
- sse: 'Events arrive as the model writes, so a reply that fails outputs.validation has already streamed when it is rewritten; some providers always answer image and speech in one piece.',
678
- buffered: 'One non-streaming call, whose events arrive together; under outputs.validation, only once the reply passes or retries run out. Thinking still streams.',
679
- }),
680
- 'outputs.streaming.streamThoughts': field('boolean', "Whether the model's thinking reaches the host."),
681
- turnBehaviour: field('ProfileTurnBehaviourSpec', 'Whether a reply that stopped early can be continued, and whether a running turn can be steered.'),
682
- 'turnBehaviour.resumption': field('ProfileTurnResumptionSpec', 'Continuing a reply that stopped early; live uses sessionResumption instead.'),
683
- 'turnBehaviour.resumption.allowContinue': field('ContinueStopKind[]', "Which early stops the host offers the user a Continue for; the kernel doesn't refuse a continue after other stops.", CONTINUE_STOP_KINDS, {
684
- length: 'The reply hit the output token limit.',
685
- stream_incomplete: 'The connection dropped mid-reply.',
686
- provider_error: 'The provider returned an error or timed out.',
687
- }),
688
- 'turnBehaviour.resumption.autoContinue': field('ContinueStopKind[]', 'Which early stops are continued without asking, whether or not allowContinue offers a Continue for them. When set, a text turn sends a listed failed model call that gave no reply again itself; the host continues the rest.', CONTINUE_STOP_KINDS, {
689
- length: 'The reply hit the output token limit.',
690
- stream_incomplete: 'The connection dropped mid-reply.',
691
- provider_error: 'The provider returned an error or timed out.',
692
- }),
693
- 'turnBehaviour.resumption.maxContinues': field('number', 'How many times one reply may be continued; once set, each continue must say which one it is. Also how many failed model calls one text turn sends again itself (one when unset).'),
694
- 'turnBehaviour.allowSteering': field('boolean', 'Lets your onStage hook add messages to a running turn. Text profiles also let the user steer.'),
695
- 'turnBehaviour.atStepLimit': field("'stop' | 'answer'", 'What happens when a turn reaches maxSteps while the model still wants tools: the turn stops with no answer, or the last call is made without tools so it answers.', STEP_LIMIT_MODES, {
696
- stop: 'It may still call tools; if it does, they run and the turn stops as step_limit with no answer.',
697
- answer: 'It is sent without tools, so it writes the answer from what the turn has gathered.',
698
- }),
699
- guardrails: field('ProfileGuardrailsSpec', 'Theorem checks what enters or leaves an agent’s context and generation against built-in or custom rules at each configured boundary.'),
700
- 'guardrails.quota': field('QuotaGuardrailSpec', 'A daily turn limit. Your server enforces it with takeSlot.'),
701
- 'guardrails.quota.perDay': field('number', 'Turns each client IP may run on this profile per UTC day, one at a time; counts live in the process, and a loopback caller is not counted.'),
709
+ 'models.*.compaction.timing': field(unionType(COMPACTION_TIMINGS), COMPACTION_TIMINGS, OPTION_DOCS.COMPACTION_TIMINGS),
710
+ 'models.*.compaction.meter': field(unionType(COMPACTION_METERS), COMPACTION_METERS, OPTION_DOCS.COMPACTION_METERS),
711
+ 'profile.defaultModel': field('ModelId'),
712
+ 'profile.allowModelSelect': field('boolean'),
713
+ 'profile.maxSteps': field('number'),
714
+ tools: field('{ allow: ToolId[]; t1Policy?; t2Loader?; parallel? }'),
715
+ 'tools.allow': field('ToolId[]'),
716
+ 'tools.t1Policy': field('(ctx) => ToolId[] | Promise<ToolId[]>'),
717
+ 'tools.t2Loader': field('ToolId'),
718
+ 'tools.parallel': field('boolean'),
719
+ inputs: field('ProfileInputsSpec | DecisionInputsSpec'),
720
+ 'inputs.state': field("'json'", ['json']),
721
+ 'inputs.maxStateBytes': field('number'),
722
+ 'inputs.text': field('boolean'),
723
+ 'inputs.attachments': field('{ accept: string[] }'),
724
+ 'inputs.attachments.accept': field('string[]', ATTACHMENT_ACCEPT_MIMES, "Types the kernel knows; a listed type it doesn't know is refused when a turn sends it."),
725
+ 'inputs.voice': field('{ accept: string[] }'),
726
+ 'inputs.voice.accept': field('string[]', VOICE_ACCEPT_MIMES, 'Audio types the kernel knows.'),
727
+ 'inputs.maxFiles': field('number'),
728
+ 'inputs.maxBytes': field('number'),
729
+ 'inputs.maxTurnBytes': field('number'),
730
+ 'inputs.limitsByMime': field('Record<string, number>'),
731
+ 'inputs.limitsByMime.*': field('number'),
732
+ 'inputs.options': field('Record<string, OptionDecl>'),
733
+ 'inputs.options.*': field('OptionDecl'),
734
+ 'inputs.options.*.label': field('string'),
735
+ 'inputs.options.*.choices': field('OptionChoice[]'),
736
+ 'inputs.options.*.choices.*.value': field('string'),
737
+ 'inputs.options.*.choices.*.description': field('string'),
738
+ 'inputs.context': field('{ from: ContextSender[]; maxChars: number }'),
739
+ 'inputs.context.from': field("Array<'client' | 'server'>", CONTEXT_SENDERS, OPTION_DOCS.CONTEXT_SENDERS),
740
+ 'inputs.context.maxChars': field('number'),
741
+ outputs: field('ProfileOutputsSpec'),
742
+ 'outputs.structured': field('StructuredSchemaId | StructuredByOption | null'),
743
+ image: field('ProfileImageSpec'),
744
+ 'image.aspectRatio': field('string'),
745
+ 'image.resolution': field('string'),
746
+ 'image.mimeType': field('string'),
747
+ 'image.quality': field('string'),
748
+ 'image.background': field('string'),
749
+ 'image.n': field('number'),
750
+ 'image.seed': field('number'),
751
+ 'image.outputCompression': field('number'),
752
+ 'image.references': field('Array<TurnBlob | TurnMediaRef>'),
753
+ 'image.includeText': field('boolean'),
754
+ speech: field('ProfileSpeechSpec'),
755
+ 'speech.voice': field('string'),
756
+ 'speech.style': field('string'),
757
+ 'speech.speed': field('number'),
758
+ 'speech.format': field(unionType(SPEECH_AUDIO_FORMATS), SPEECH_AUDIO_FORMATS, OPTION_DOCS.SPEECH_AUDIO_FORMATS),
759
+ live: field('ProfileLiveSpec'),
760
+ 'live.ingress': field('LiveIngressSpec'),
761
+ 'live.ingress.audio': field('boolean'),
762
+ 'live.ingress.video': field('boolean'),
763
+ 'live.ingress.text': field('boolean'),
764
+ 'live.voice': field('string'),
765
+ 'live.vad': field('LiveVadSpec'),
766
+ 'live.vad.activityHandling': field(unionType(LIVE_ACTIVITY_HANDLINGS), LIVE_ACTIVITY_HANDLINGS, OPTION_DOCS.LIVE_ACTIVITY_HANDLINGS),
767
+ 'live.vad.startSensitivity': field(unionType(LIVE_START_SENSITIVITIES), LIVE_START_SENSITIVITIES, OPTION_DOCS.LIVE_START_SENSITIVITIES),
768
+ 'live.vad.endSensitivity': field(unionType(LIVE_END_SENSITIVITIES), LIVE_END_SENSITIVITIES, OPTION_DOCS.LIVE_END_SENSITIVITIES),
769
+ 'live.vad.prefixPaddingMs': field('number'),
770
+ 'live.vad.silenceDurationMs': field('number'),
771
+ 'live.sessionResumption': field('boolean'),
772
+ 'live.greeting': field('string'),
773
+ 'live.resumed': field('{ prompt: string; afterMs?: number }'),
774
+ 'live.resumed.prompt': field('string'),
775
+ 'live.resumed.afterMs': field('number'),
776
+ 'live.contextCompression': field('LiveContextCompressionSpec'),
777
+ 'live.contextCompression.triggerTokens': field('number'),
778
+ 'live.contextCompression.slidingWindow': field('LiveSlidingWindowSpec'),
779
+ 'live.contextCompression.slidingWindow.targetTokens': field('number'),
780
+ 'live.transcription': field('LiveTranscriptionSpec'),
781
+ 'live.transcription.input': field('boolean'),
782
+ 'live.transcription.output': field('boolean'),
783
+ 'outputs.validation': field('ProfileValidationSpec'),
784
+ 'outputs.validation.fields': field('Record<string, ProfileValidator>'),
785
+ 'outputs.validation.fields.*': field('(candidate: unknown, options?: Record<string, string>) => ValidationResult | Promise<ValidationResult>'),
786
+ 'outputs.validation.items': field('Record<string, ProfileItemRule>'),
787
+ 'outputs.validation.items.*': field('ProfileItemRule'),
788
+ 'outputs.validation.items.*.check': field('(item: unknown, turn: ItemCheckTurn) => ValidationResult | Promise<ValidationResult>'),
789
+ 'outputs.validation.items.*.onFail': field("'drop' | 'fix'", ITEM_FAIL_ACTIONS),
790
+ 'outputs.validation.maxRetries': field('number'),
791
+ 'outputs.streaming': field('ProfileStreamingSpec'),
792
+ 'outputs.streaming.mode': field(unionType(STREAM_MODES), STREAM_MODES, OPTION_DOCS.STREAM_MODES),
793
+ 'outputs.streaming.streamThoughts': field('boolean'),
794
+ turnBehaviour: field('ProfileTurnBehaviourSpec'),
795
+ 'turnBehaviour.resumption': field('ProfileTurnResumptionSpec'),
796
+ 'turnBehaviour.resumption.allowContinue': field('ContinueStopKind[]', CONTINUE_STOP_KINDS, OPTION_DOCS.CONTINUE_STOP_KINDS),
797
+ 'turnBehaviour.resumption.autoContinue': field('ContinueStopKind[]', CONTINUE_STOP_KINDS, OPTION_DOCS.CONTINUE_STOP_KINDS),
798
+ 'turnBehaviour.resumption.maxContinues': field('number'),
799
+ 'turnBehaviour.allowSteering': field('boolean'),
800
+ 'turnBehaviour.atStepLimit': field("'stop' | 'answer'", STEP_LIMIT_MODES, OPTION_DOCS.STEP_LIMIT_MODES),
801
+ guardrails: field('ProfileGuardrailsSpec'),
802
+ 'guardrails.quota': field('QuotaGuardrailSpec'),
803
+ 'guardrails.quota.perDay': field('number'),
702
804
  ...detectFields(),
703
- 'guardrails.blockedReply': field('BlockedReplySpec', 'How a reply a guardrail blocked is handled: the model rewrites it, or the user gets a refusal, and how many rewrites it gets.'),
704
- 'guardrails.blockedReply.onBlock': field(unionType(BLOCKED_REPLY_ON_BLOCK), 'Whether the model gets to rewrite a reply a guardrail blocked, or the user gets a refusal in its place.', BLOCKED_REPLY_ON_BLOCK, {
705
- retry: 'The model reads why and rewrites the reply, up to maxRetries times; once retries run out, the reply is withheld and the turn ends with a safety error. Live never rewrites: it withholds at once.',
706
- refuse: 'The user sees the egress.refusal wording in place of the reply, and the turn ends.',
707
- }),
708
- 'guardrails.blockedReply.maxRetries': field('number', 'How many times the model may rewrite a blocked reply. Live ignores it.'),
709
- 'guardrails.network': field('NetworkGuardrailSpec', 'Addresses HTTP and MCP tools may reach.'),
710
- 'guardrails.network.allowPrivateNetworks': field('boolean', 'Lets tools reach localhost and private network addresses, for local development.'),
711
- 'guardrails.network.allowedHosts': field('string[]', "Hostnames tools may reach even when they resolve to a private address; public hosts don't need listing. Names are resolved only when the host passes resolveHost."),
712
- 'guardrails.network.allowedSchemes': field('string[]', 'The URL schemes tools may use.'),
713
- 'guardrails.taint': field('TaintGuardrailSpec', 'Tool limits after a remote read.'),
714
- 'guardrails.taint.afterRemoteRead': field(unionType(TAINT_GATES), "Which tool calls are refused, by each tool's access, once the turn has read a remote tool's result.", TAINT_GATES, {
715
- off: 'None; risky calls are only logged.',
716
- destructive: 'Destructive calls.',
717
- write: 'Read-write and destructive calls.',
718
- }),
719
- 'guardrails.taint.remoteDestination': field(unionType(DESTINATION_GATES), "What happens to a tool call, read-only ones too, that sends to an email address, a link's host or a bank account number (IBAN) that only the running text of a remote tool's result named. One the user, the system prompt, or a local tool gave passes, and so does one that is a whole field of the result.", DESTINATION_GATES, {
720
- off: 'The call runs; it is only logged.',
721
- confirm: 'The call waits for the user to approve it; an approval runs it.',
722
- block: 'The call is refused, and the model is told why.',
723
- }),
724
- 'guardrails.disclosure': field('{ enforce: DecisionDisclosureEnforcer }', 'Your check on the state before a decision sends it to the model.'),
725
- 'guardrails.disclosure.enforce': field('(state, context) => DecisionDisclosureVerdict | Promise<DecisionDisclosureVerdict>', 'Your function that allows or blocks the state before it is sent.'),
726
- labels: field('LabelOverrides', "This profile's own wording for error lines, notices, and notes to the model, by labels key."),
727
- 'labels.*': field('string', 'The wording for this labels key; canary.bind_note must keep its {canary} placeholder.'),
728
- observability: field('ProfileObservabilitySpec', "Where this profile's traces go and what they keep."),
729
- 'observability.writeTo': field('false | string | TraceSink', 'Where traces go: a registered destination id, your own writer, or false. An unregistered id fails the turn at the start. A sink passed to runTurn replaces it.'),
730
- 'observability.sampleRate': field('number', 'The share of traces kept, from 0 to 1, each kept or dropped whole; a sink passed straight to runTurn keeps every trace.'),
731
- 'observability.include': field('TraceIncludeSpec', 'Which optional parts of a trace are kept.'),
732
- 'observability.include.upstreamLog': field('boolean', 'Keeps each row the provider sent back, scrubbed, as it arrived, with media bytes replaced by their sha256.'),
733
- 'observability.include.outboundWire': field('boolean', 'Keeps each request body sent to the provider, scrubbed.'),
734
- 'observability.include.evidenceRaw': field('boolean', "Keeps the provider's raw payload on grounding results such as search citations; upstreamLog rows keep their own copy."),
735
- 'observability.include.usage': field('boolean', 'Keeps token counts and other usage figures on spans; upstreamLog rows keep their own.'),
736
- 'observability.include.guardrailDecisions': field('boolean', 'Keeps each guardrail decision.'),
737
- 'observability.include.guardrailMatchPreview': field('boolean', "Keeps the exact text each guardrail matched, unscrubbed, on the trace and the host's event stream; for debugging only."),
738
- 'observability.resource': field('Record<string, TraceAttributeValue>', 'Attributes stamped on every trace, such as service.name.'),
739
- 'observability.scrub': field('TraceScrubSpec', "What is removed from stored traces, separately from the turn's guardrails."),
740
- 'observability.scrub.sensitive': field('ScrubSwitch', "Removes what the data detectors (IDs, Financial, Network, Credentials) and your own detectors find from stored traces. On, it cleans with the patterns each reads the turn with; { theorem, host } picks Theorem's patterns, yours, or both for the trace alone."),
741
- 'observability.scrub.injection': field('ScrubSwitch', "Removes what Injection and Tool instructions find from stored traces. On, it cleans with the patterns each reads the turn with; { theorem, host } picks Theorem's patterns, yours, or both for the trace alone."),
742
- 'observability.scrub.canary': field('ScrubSwitch', "Removes the canary token from stored traces. The canary is Theorem's, so { theorem: false } keeps it."),
743
- 'observability.retainForDays': field('number', 'Days a trace file is kept, by its UTC day. The next write removes old files. 0 or less keeps all.'),
744
- 'observability.rotateAfterMiB': field('number', 'File size in MiB at which a file-based destination starts a new file, handed to every destination with the record. Default 32.'),
745
- 'observability.onWriteError': field('(err: unknown) => void', "Your function called when a trace can't be built or written; the turn carries on, and a destination's own error handler takes priority. An unregistered writeTo id is a config error instead."),
805
+ 'guardrails.blockedReply': field('BlockedReplySpec'),
806
+ 'guardrails.blockedReply.onBlock': field(unionType(BLOCKED_REPLY_ON_BLOCK), BLOCKED_REPLY_ON_BLOCK, OPTION_DOCS.BLOCKED_REPLY_ON_BLOCK),
807
+ 'guardrails.blockedReply.maxRetries': field('number'),
808
+ 'guardrails.network': field('NetworkGuardrailSpec'),
809
+ 'guardrails.network.allowPrivateNetworks': field('boolean'),
810
+ 'guardrails.network.allowedHosts': field('string[]'),
811
+ 'guardrails.network.allowedSchemes': field('string[]'),
812
+ 'guardrails.taint': field('TaintGuardrailSpec'),
813
+ 'guardrails.taint.afterRemoteRead': field(unionType(TAINT_GATES), TAINT_GATES, OPTION_DOCS.TAINT_GATES),
814
+ 'guardrails.taint.remoteDestination': field(unionType(DESTINATION_GATES), DESTINATION_GATES, OPTION_DOCS.DESTINATION_GATES),
815
+ 'guardrails.disclosure': field('{ enforce: DecisionDisclosureEnforcer }'),
816
+ 'guardrails.disclosure.enforce': field('(state, context) => DecisionDisclosureVerdict | Promise<DecisionDisclosureVerdict>'),
817
+ labels: field('LabelOverrides'),
818
+ 'labels.*': field('string'),
819
+ observability: field('ProfileObservabilitySpec'),
820
+ 'observability.writeTo': field('false | string | TraceSink'),
821
+ 'observability.sampleRate': field('number'),
822
+ 'observability.include': field('TraceIncludeSpec'),
823
+ 'observability.include.upstreamLog': field('boolean'),
824
+ 'observability.include.outboundWire': field('boolean'),
825
+ 'observability.include.evidenceRaw': field('boolean'),
826
+ 'observability.include.usage': field('boolean'),
827
+ 'observability.include.guardrailDecisions': field('boolean'),
828
+ 'observability.include.guardrailMatchPreview': field('boolean'),
829
+ 'observability.resource': field('Record<string, TraceAttributeValue>'),
830
+ 'observability.scrub': field('TraceScrubSpec'),
831
+ 'observability.scrub.sensitive': field('ScrubSwitch'),
832
+ 'observability.scrub.injection': field('ScrubSwitch'),
833
+ 'observability.scrub.canary': field('ScrubSwitch'),
834
+ 'observability.retainForDays': field('number'),
835
+ 'observability.rotateAfterMiB': field('number'),
836
+ 'observability.onWriteError': field('(err: unknown) => void'),
746
837
  });
747
- const TOOL_TYPE_FIELD = field(unionType(TOOL_TYPES), 'How the tool runs.', TOOL_TYPES, {
748
- builtin: "The provider's own tool, such as Google Search, run by the provider.",
749
- function: 'Your handler runs it.',
750
- http: 'The kernel calls your HTTP endpoint.',
751
- mcp: 'The kernel calls a tool on a remote MCP server.',
752
- agent: 'The kernel runs one turn of another registered agent and returns its reply.',
753
- });
754
- const CREDENTIAL_KINDS = {
755
- bearer: 'A token; a secret typed in at the prompt becomes a bearer token.',
756
- ['api_' + 'key']: 'An API key; a secret typed in at the prompt becomes an API key.',
757
- oauth2: 'An OAuth sign-in; the host supplies the token.',
758
- };
838
+ const TOOL_TYPE_FIELD = field(unionType(TOOL_TYPES), TOOL_TYPES, OPTION_DOCS.TOOL_TYPES);
759
839
  /**
760
840
  * The catalog of the fields `registerTool` takes, keyed `registerTool.<field>`. The `studio.` and
761
841
  * `local.` rows are the studio's own; a builder never sets them.
762
842
  */
763
- export const EXTRA_FIELDS = {
764
- 'done.stop.kind': field('TurnStopKind', 'Why the turn ended, on the done event: its stop.kind.', TURN_STOP_KINDS, {
765
- completed: 'The model finished its reply.',
766
- length: 'The model reached its token limit.',
767
- tool: 'The model called tools and the turn hands them to the host, in done.tools.',
768
- gate: 'A pre_tool stage held a tool call. The host resumes it with invokeTool, not continueFrom.',
769
- filtered: 'The provider filtered the reply, or the egress guardrail withheld it.',
770
- provider_error: 'The provider failed or reported an error.',
771
- cancelled: 'The turn was cancelled, by the user or by a stage that aborted it.',
772
- stream_incomplete: 'The stream ended without the provider reporting a final status.',
773
- step_limit: 'The last model call maxSteps allows asked for tools, so the turn ended with no answer.',
774
- interrupted: 'A live utterance was cut off by an interruption.',
775
- generation_complete: 'Live: the model finished generating audio or text for this utterance. The turn may still be open.',
776
- }),
843
+ export const EXTRA_FIELDS = withFieldDocs({
844
+ 'done.stop.kind': field('TurnStopKind', TURN_STOP_KINDS, OPTION_DOCS.TURN_STOP_KINDS),
777
845
  'registerTool.type': TOOL_TYPE_FIELD,
778
846
  /** Studio-only rows: the editor's local-model connection, and a decision's questions and images. */
779
- 'local.baseUrl': field('string', 'Where your local model server listens, such as Ollama, llama.cpp or vLLM. The browser calls it directly.'),
847
+ 'local.baseUrl': field('string'),
780
848
  'studio.remoteTools': {
781
- ...field('boolean', 'Whether tools that reach other hosts (HTTP and MCP) may run while a local model is in use. Off, a run with a local model reaches no host.'),
849
+ ...field('boolean'),
782
850
  unset: 'Off',
783
851
  },
784
- 'decision.questions.id': field('string', "The question's name. Its answer comes back under it."),
785
- 'decision.questions.type': field("'choice' | 'score' | 'noul' | 'box'", 'The kind of answer the question takes.', ['choice', 'score', 'noul', 'box'], {
786
- choice: 'One of the named options, with a confidence and a probability for each option.',
787
- score: 'A level on an ordered scale, with a confidence.',
788
- noul: 'One number, which may weigh named criteria.',
789
- box: 'Where something is in an image: its top, bottom, left and right edges, with a confidence.',
790
- }),
791
- 'decision.questions.instructions': field('DecisionEntry', "What to ask about the state. Name a state field in backticks, such as `photo`, and one of the decision's images by its reference, such as <ginger>. A box names what to find and the image it is in, such as the ginger in `photo`."),
852
+ 'decision.questions.id': field('string'),
853
+ 'decision.questions.type': field(unionType(DECISION_QUESTION_TYPES), DECISION_QUESTION_TYPES, OPTION_DOCS.DECISION_QUESTION_TYPES),
854
+ 'decision.questions.instructions': field('DecisionEntry'),
792
855
  'decision.questions.image': {
793
- ...field('string', "The image a box is in: one of the decision's images, such as <ghs02>, or a state field its instructions name, such as `photo`. The model is told it in the instructions."),
856
+ ...field('string'),
794
857
  unset: 'The image the instructions name',
795
858
  },
796
- 'decision.images': field('Record<string, DecisionAsset>', "Pictures a decision can send. Write one's reference, such as <ghs02>, in the state or a question, and the model reads the picture there; a picture nothing references is not sent. A PNG or JPEG."),
797
- 'decision.images.name': field('string', 'The reference a question writes, without its angle brackets: ghs02 is written <ghs02>. Lowercase letters, digits and _.'),
798
- 'registerTool.name': field('string', "The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model calls a custom tool by."),
799
- 'registerTool.description': field('string', 'Tells the model what the tool does (custom tools only).'),
800
- 'registerTool.input': field('ZodSchema', "The Zod schema for the tool's arguments, sent to the model and checked on every call."),
801
- 'registerTool.output': field('ZodSchema', "The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is not checked."),
802
- 'registerTool.handler': field('ToolHandler', 'Your function that runs the tool; it can also yield progress as it goes.'),
803
- 'registerTool.endpoint': field('string', 'The URL the tool calls, with {name} placeholders for mapping.pathParams; the scheme and host must be written out.'),
804
- 'registerTool.method': field(unionType(HTTP_METHODS), 'The HTTP method; every method but GET sends a JSON body.', HTTP_METHODS),
805
- 'registerTool.headers': field('Record<string, string>', "Headers sent with every request to the tool's own origin, never once a redirect leaves it."),
806
- 'registerTool.mapping': field('{ pathParams?, queryParams?, bodyParam? }', 'Where each argument goes in the request.'),
807
- 'registerTool.mapping.pathParams': field('string[]', 'Arguments that fill the {name} placeholders in the endpoint.'),
808
- 'registerTool.mapping.queryParams': field('string[]', 'Arguments added to the query string.'),
809
- 'registerTool.mapping.bodyParam': field('string', 'The one argument sent as the whole JSON body; without it, a method other than GET sends every argument the path and query leave unused.'),
810
- 'registerTool.serverUrl': field('string', "The MCP server's URL."),
811
- 'registerTool.mcpToolName': field('string', "The tool's name on the MCP server."),
812
- 'registerTool.profile': field('ProfileId', 'The profile this agent tool runs: text, image, or speech. Register it first. Nothing it calls may stop on a gate.'),
859
+ 'decision.images': field('Record<string, DecisionAsset>'),
860
+ 'decision.images.name': field('string'),
861
+ 'registerTool.name': field('string'),
862
+ 'registerTool.description': field('string'),
863
+ 'registerTool.input': field('ZodSchema'),
864
+ 'registerTool.output': field('ZodSchema'),
865
+ 'registerTool.handler': field('ToolHandler'),
866
+ 'registerTool.endpoint': field('string'),
867
+ 'registerTool.method': field(unionType(HTTP_METHODS), HTTP_METHODS),
868
+ 'registerTool.headers': field('Record<string, string>'),
869
+ 'registerTool.mapping': field('{ pathParams?, queryParams?, bodyParam? }'),
870
+ 'registerTool.mapping.pathParams': field('string[]'),
871
+ 'registerTool.mapping.queryParams': field('string[]'),
872
+ 'registerTool.mapping.bodyParam': field('string'),
873
+ 'registerTool.serverUrl': field('string'),
874
+ 'registerTool.mcpToolName': field('string'),
875
+ 'registerTool.profile': field('ProfileId'),
813
876
  'registerTool.answeredBy': {
814
- ...field("'page'", 'Who answers a call to a function tool. With page, the page the agent is on returns the output, and the tool has no handler.', ['page']),
877
+ ...field("'page'", ['page']),
815
878
  unset: 'Its handler',
816
879
  },
817
880
  'registerTool.maxResponseBytes': {
818
- ...field('number', 'The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with response_too_large.'),
881
+ ...field('number'),
819
882
  unset: 'No limit',
820
883
  },
821
884
  'registerTool.session': {
822
- ...field('McpSessionLimits', "How long and how many of an MCP tool's server sessions the kernel keeps."),
885
+ ...field('McpSessionLimits'),
823
886
  unset: 'No limits',
824
887
  },
825
888
  'registerTool.session.idleMs': {
826
- ...field('number', 'How long a session may sit unused before the next call opens a new one, in milliseconds.'),
889
+ ...field('number'),
827
890
  unset: 'No limit',
828
891
  },
829
892
  'registerTool.session.max': {
830
- ...field('number', 'The most sessions the tool keeps open; past it the least recently used is dropped.'),
893
+ ...field('number'),
831
894
  unset: 'No limit',
832
895
  },
833
896
  'registerTool.maxCallsPerTurn': {
834
- ...field('number', 'How many times one turn of the calling agent may run this tool.'),
897
+ ...field('number'),
835
898
  unset: 'As many as its steps allow',
836
899
  },
837
900
  'registerTool.fieldText': {
838
- ...field('Partial<Record<keyof AgentToolInput, string>>', 'What the calling model reads on a field of an agent tool input, such as text. A field the profile does not take is refused when the tool registers.'),
901
+ ...field('Partial<Record<keyof AgentToolInput, string>>'),
839
902
  unset: 'The fields carry no text',
840
903
  },
841
904
  'registerTool.hostFields': {
842
- ...field('Record<string, ZodType>', 'Fields the calling model fills on an agent tool that only the host reads. onAgentCall gets them as hostInput and turns them into what the agent is sent; the agent never sees them. A name the input already has is refused when the tool registers.'),
905
+ ...field('Record<string, ZodType>'),
843
906
  unset: 'The input is only what the profile takes',
844
907
  },
845
908
  'registerTool.hostOnly': {
846
- ...field("Array<'attachments' | 'voice' | 'options'>", 'Channels the called profile takes that the calling model cannot fill on an agent tool; only onAgentCall sends them. A channel the profile does not take is refused when the tool registers.'),
909
+ ...field("Array<'attachments' | 'voice' | 'options'>"),
847
910
  unset: 'The model can fill every channel the profile takes',
848
911
  },
849
912
  'registerTool.auth': {
850
- ...field('ToolAuthConfig', 'How the tool gets its credential.'),
913
+ ...field('ToolAuthConfig'),
851
914
  unset: 'No credential',
852
915
  },
853
- 'registerTool.auth.type': field(unionType(TOOL_AUTH_TYPES), "The kind of credential the tool expects, shown when a turn stops to ask for one; the header follows the stored credential's own kind.", TOOL_AUTH_TYPES, CREDENTIAL_KINDS),
854
- 'registerTool.auth.slot': field('string', 'Which of the credentials the turn passes in this tool uses.'),
855
- 'registerTool.auth.service': field('string', 'The service the person signs in to, as they know it, named when a turn stops to ask for a credential.'),
916
+ 'registerTool.auth.type': field(unionType(TOOL_AUTH_TYPES), TOOL_AUTH_TYPES, OPTION_DOCS.TOOL_AUTH_TYPES),
917
+ 'registerTool.auth.slot': field('string'),
918
+ 'registerTool.auth.service': field('string'),
856
919
  'registerTool.auth.headerName': {
857
- ...field('string', "The header the credential goes in; an API key's own headerName comes first."),
920
+ ...field('string'),
858
921
  unset: 'Authorization',
859
922
  },
860
923
  'registerTool.auth.headerPrefix': {
861
- ...field('string', "Text put before the credential in the header; an API key's own headerPrefix comes first."),
924
+ ...field('string'),
862
925
  unset: '"Bearer " for tokens, nothing for API keys',
863
926
  },
864
927
  'registerTool.auth.queryParam': {
865
- ...field('string', 'For a service that takes its API key in the URL: the query parameter the key goes in, in place of a header.'),
928
+ ...field('string'),
866
929
  unset: 'The key goes in a header',
867
930
  },
868
931
  'registerTool.auth.onUnauthenticated': {
869
- ...field(unionType(AUTH_UNAUTHENTICATED_POLICIES), "What happens when the credential is missing, expired, can't be refreshed or is refused by the service.", AUTH_UNAUTHENTICATED_POLICIES, {
870
- gate: 'The turn stops and asks the host for a credential.',
871
- report_to_model: "The model is told the tool isn't signed in, and the turn goes on.",
872
- fail: 'The call fails as not signed in, for a key the host holds that no person can sign in to replace.',
873
- }),
932
+ ...field(unionType(AUTH_UNAUTHENTICATED_POLICIES), AUTH_UNAUTHENTICATED_POLICIES, OPTION_DOCS.AUTH_UNAUTHENTICATED_POLICIES),
874
933
  unset: 'gate',
875
934
  },
876
- 'registerTool.auth.preResolved': field('Partial<OAuthEndpoints & { resource: string }>', "Named on the auth gate for the host's OAuth flow, so it need not find them."),
877
- 'registerTool.auth.scopes': field('string[]', 'The OAuth scopes the tool needs, shown when a turn stops to ask for a credential. A service asking for any other scope fails the call, with no new sign-in.'),
878
- 'registerTool.auth.clientId': field('string', "Your OAuth client id, kept for the host's sign-in flow; the kernel doesn't read it."),
879
- 'registerTool.auth.redirectUri': field('string', "Your OAuth redirect URI, kept for the host's sign-in flow; the kernel doesn't read it."),
880
- 'studio.authType': field(unionType(STUDIO_AUTH_TYPES), 'The kind of credential the tool expects, or none.', STUDIO_AUTH_TYPES, { none: 'The tool sends no credential.', ...CREDENTIAL_KINDS }),
881
- 'studio.testCredential': field('string', "A credential for this tool's connection tests, kept in the tab and never saved."),
935
+ 'registerTool.auth.preResolved': field('Partial<OAuthEndpoints & { resource: string }>'),
936
+ 'registerTool.auth.scopes': field('string[]'),
937
+ 'registerTool.auth.clientId': field('string'),
938
+ 'registerTool.auth.redirectUri': field('string'),
939
+ 'studio.authType': field(unionType(STUDIO_AUTH_TYPES), STUDIO_AUTH_TYPES, OPTION_DOCS.STUDIO_AUTH_TYPES),
940
+ 'studio.testCredential': field('string'),
882
941
  'studio.stubOutput': {
883
- ...field('Record<string, unknown>', 'What a function tool returns in the studio, unless a demo handler has its name.'),
942
+ ...field('Record<string, unknown>'),
884
943
  unset: 'A stand-in built from the output schema',
885
944
  },
886
- 'studio.sampleInput': field('Record<string, unknown>', 'Arguments for the connection test, never saved.'),
887
- 'registerTool.inputSchema': field('Record<string, unknown>', "The tool's arguments as a JSON Schema, sent to the model."),
888
- 'registerTool.outputSchema': field('Record<string, unknown>', "The tool's result as a JSON Schema, which a function tool's stand-in result is built from."),
889
- 'registerStructured.jsonSchema': field('Record<string, unknown>', 'The JSON Schema a structured reply must follow, sent to the model as its response format.'),
890
- 'registerTool.access': field(unionType(TOOL_ACCESS), "What the tool can change, which taint.afterRemoteRead refuses calls by after a turn reads a remote tool's result.", TOOL_ACCESS, {
891
- 'read-only': 'Only reads.',
892
- 'read-write': 'Creates or updates things.',
893
- destructive: 'Deletes, charges, or does something else hard to undo.',
894
- }),
895
- 'registerTool.loadTier': field(unionType(TOOL_LOAD_TIERS), 'When the tool becomes available to the model; live and host profiles load every allowed tool at the start.', TOOL_LOAD_TIERS, {
896
- T0: 'At the start of every turn.',
897
- T2: 'On demand: when tools.t1Policy picks it at the start of a turn, or when the tools.t2Loader tool loads it mid-turn (custom tools only).',
898
- }),
899
- 'registerTool.permission': field(unionType(TOOL_PERMISSION), "Whether the host must approve a call before it runs; the provider's own tools never ask.", TOOL_PERMISSION, {
900
- auto: 'Runs without asking.',
901
- session_consent: 'Asks once; the approval lasts as long as the host keeps passing it back.',
902
- always_confirm: 'Asks every time.',
903
- }),
904
- 'registerTool.preTool': field('(input, ctx) => StageResult | undefined', "Runs before the host's pre_tool onStage."),
945
+ 'studio.sampleInput': field('Record<string, unknown>'),
946
+ 'registerTool.inputSchema': field('Record<string, unknown>'),
947
+ 'registerTool.outputSchema': field('Record<string, unknown>'),
948
+ 'registerStructured.jsonSchema': field('Record<string, unknown>'),
949
+ 'registerTool.access': field(unionType(TOOL_ACCESS), TOOL_ACCESS, OPTION_DOCS.TOOL_ACCESS),
950
+ 'registerTool.loadTier': field(unionType(TOOL_LOAD_TIERS), TOOL_LOAD_TIERS, OPTION_DOCS.TOOL_LOAD_TIERS),
951
+ 'registerTool.permission': field(unionType(TOOL_PERMISSION), TOOL_PERMISSION, OPTION_DOCS.TOOL_PERMISSION),
952
+ 'registerTool.preTool': field('(input, ctx) => StageResult | undefined'),
905
953
  'registerTool.exposeToModel': {
906
- ...field('boolean', 'Whether the model can see and call the tool.'),
954
+ ...field('boolean'),
907
955
  unset: 'The model can',
908
956
  },
909
- 'registerTool.sources': field('(output) => Source[]', 'The sources a result cites. One that fails sourceSchema, or a throw, is a sources_invalid warning and is not cited.'),
910
- 'registerTool.images': field('(output) => string[]', 'The https addresses of pictures in the output the model should see. The kernel fetches each one through the profile network policy, without the tool credentials.'),
957
+ 'registerTool.sources': field('(output) => Source[]'),
958
+ 'registerTool.images': field('(output) => string[]'),
911
959
  'registerTool.imageLimits': {
912
- ...field('ToolImageLimits', 'How many of those pictures the kernel fetches, how large, and how slowly.'),
960
+ ...field('ToolImageLimits'),
913
961
  unset: 'No limit',
914
962
  },
915
- 'registerTool.askInputSchema': field('Record<string, unknown>', '`inputSchema` with the `background` argument. The registry sets it on an `ask` tool.'),
916
- 'registerTool.conflictsWith': field('string[]', 'The built-in tools a builtin tool cannot run beside.'),
963
+ 'registerTool.askInputSchema': field('Record<string, unknown>'),
964
+ 'registerTool.conflictsWith': field('string[]'),
917
965
  'registerTool.limit': {
918
- ...field('HttpToolLimit', "The service's own limit for one key; the kernel keeps this tool's requests within it."),
966
+ ...field('HttpToolLimit'),
919
967
  unset: 'No limit',
920
968
  },
921
969
  'registerTool.timeoutMs': {
922
- ...field('number', 'How long the service may take to answer, its body read included. Past it the call fails timeout and frees its place in the limit.'),
970
+ ...field('number'),
923
971
  unset: "As long as the caller's signal lets it",
924
972
  },
925
973
  'registerTool.after': {
926
- ...field('boolean', 'Gives the model an after field on this tool: the tools called in the same step that must settle before this call starts. The kernel removes the field before the tool, the stages or a gate read the input. A name with no other call in the step fails the call wait_unknown.'),
974
+ ...field('boolean'),
927
975
  unset: 'The model sets no order',
928
976
  },
929
977
  'registerTool.background': {
930
- ...field("'always' | { afterMs: number } | 'ask' | 'never'", "When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }: once the body has run past this time. 'ask': at the hand-off if the model sets the background argument. A turn with no background service runs the tool inline."),
931
- options: ['never', 'ask', 'always', 'afterMs'],
932
- optionDescriptions: {
933
- never: 'The model gets its reply when the body ends.',
934
- ask: 'The model chooses, call by call, whether to go on without the result.',
935
- always: 'The model gets its reply at once, and the body goes on after the turn.',
936
- afterMs: 'The model gets its reply once the body has run past this time.',
937
- },
978
+ ...field("'always' | { afterMs: number } | 'ask' | 'never'", TOOL_BACKGROUND_MODES, OPTION_DOCS.TOOL_BACKGROUND_MODES),
938
979
  unset: "'never': the model gets its reply when the body ends",
939
980
  },
940
- 'registerTool.background.afterMs': field('number', 'Milliseconds the body runs before the model gets its reply. A body that ends sooner answers in the turn.'),
941
- 'registerTool.category': field('string', 'A label for grouping tools; nothing reads it yet.'),
942
- 'registerTool.labels': field('ToolLabels', "Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list item. {path|text} shows the text when the value is unusable. {count hit|hits} shows a number with the word for one or for any other number: '1 hit', '3 hits'. With no fallback, the label is dropped. A label is one line, or a list read top to bottom: the first line that fits is shown. A line fits when each {path} has a value and its condition holds, as in 'when status is archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in words. The last line of a list must always fit."),
981
+ 'registerTool.background.afterMs': field('number'),
982
+ 'registerTool.category': field('string'),
983
+ 'registerTool.labels': field('ToolLabels'),
943
984
  'registerTool.labels.activity': {
944
- ...field('string | string[]', "Transcript text while a call runs, e.g. 'Saving {title} to your collection'. {path} reads the call's input."),
985
+ ...field('string | string[]'),
945
986
  unset: 'The tool name, in words',
946
987
  },
947
988
  'registerTool.labels.activityPast': {
948
- ...field('string | string[]', "What the transcript says once a call completes, e.g. 'Found {results.0.name}'. Each {path} is filled from the call's input, then its output."),
989
+ ...field('string | string[]'),
949
990
  unset: 'The tool name, in words',
950
991
  },
951
992
  'registerTool.labels.activityFailed': {
952
- ...field('string | string[]', "What the transcript says when a call fails or the host labels it failed, e.g. 'Couldn't save {title}'. Each {path} is filled from the call's input."),
993
+ ...field('string | string[]'),
953
994
  unset: "Couldn't complete, then the tool name in words",
954
995
  },
955
996
  'registerTool.labels.request': {
956
- ...field('string | string[]', "What the approval card says the agent wants to do, e.g. 'check the weather in {city}'. Each {path} is filled from the call's input."),
997
+ ...field('string | string[]'),
957
998
  unset: 'The tool name, in words',
958
999
  },
959
1000
  'registerTool.paths': {
960
- ...field('string[]', 'The turn paths this tool is offered on, where * means every path; a turn with no path gets only * tools. Host profiles ignore it.'),
1001
+ ...field('string[]'),
961
1002
  unset: 'Every path',
962
1003
  },
963
- };
1004
+ });
964
1005
  /** `labels.<key>` resolves to `labels.*` with that key's own note. */
965
1006
  export function fieldMeta(path) {
966
1007
  const meta = PROFILE_FIELDS[path] ?? EXTRA_FIELDS[path];