@theoremjs/agents 0.3.4-next.855.gc82d4ec → 0.3.4-next.869.gb64db05
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/esm/src/guardrails/detectors.d.ts +91 -21
- package/esm/src/guardrails/host-patterns.d.ts +15 -2
- package/esm/src/guardrails/labels.d.ts +11 -3
- package/esm/src/guardrails/labels.js +42 -23
- package/esm/src/guardrails/quota.d.ts +9 -3
- package/esm/src/guardrails/quota.js +9 -3
- package/esm/src/guardrails/theorem-error.d.ts +5 -1
- package/esm/src/guardrails/theorem-error.js +8 -4
- package/esm/src/guardrails/types.d.ts +66 -18
- package/esm/src/guardrails/types.js +22 -3
- package/esm/src/kernel/api-catalog.d.ts +26 -75
- package/esm/src/kernel/api-catalog.js +37 -119
- package/esm/src/kernel/checkpoint.d.ts +5 -1
- package/esm/src/kernel/default-scope.d.ts +52 -10
- package/esm/src/kernel/default-scope.js +52 -10
- package/esm/src/kernel/engine/runner/gates.js +66 -22
- package/esm/src/kernel/engine/runner/state.d.ts +5 -2
- package/esm/src/kernel/engine/runner/steps.js +15 -15
- package/esm/src/kernel/engine/runner/stream.d.ts +5 -0
- package/esm/src/kernel/engine/runner/stream.js +12 -1
- package/esm/src/kernel/field-docs.d.ts +13 -0
- package/esm/src/kernel/field-docs.js +613 -0
- package/esm/src/kernel/protocols/binding.d.ts +56 -0
- package/esm/src/kernel/protocols/limits.d.ts +9 -0
- package/esm/src/kernel/protocols/provider.d.ts +5 -1
- package/esm/src/kernel/protocols/provider.js +5 -1
- package/esm/src/kernel/registry/profiles.d.ts +154 -5
- package/esm/src/kernel/schema.d.ts +5 -7
- package/esm/src/kernel/schema.js +511 -470
- package/esm/src/kernel/stop.d.ts +41 -17
- package/esm/src/kernel/stop.js +9 -1
- package/esm/src/kernel/tools/background.d.ts +4 -0
- package/esm/src/kernel/tools/types.d.ts +331 -43
- package/esm/src/kernel/turn-events.d.ts +4 -3
- package/esm/src/kernel/types.d.ts +482 -89
- package/esm/src/observability/destinations.d.ts +5 -1
- package/esm/src/observability/destinations.js +5 -1
- package/esm/src/observability/trace-catalog.js +62 -102
- package/esm/src/observability/types.d.ts +93 -19
- package/esm/src/providers/shared/carried-tool-files.js +9 -8
- package/package.json +1 -1
package/esm/src/kernel/schema.js
CHANGED
|
@@ -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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
71
|
-
/**
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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 = [
|
|
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
|
-
|
|
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'
|
|
494
|
+
[`${path}.allow`, field('NameAllow')],
|
|
317
495
|
[
|
|
318
496
|
`${path}.allow.names`,
|
|
319
497
|
{
|
|
320
|
-
...field('string[]'
|
|
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
|
-
|
|
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'
|
|
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'
|
|
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'
|
|
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) =>
|
|
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
|
-
|
|
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(
|
|
543
|
+
...action(),
|
|
380
544
|
unset: 'Only the boundaries at names are read',
|
|
381
545
|
},
|
|
382
546
|
],
|
|
383
|
-
[`${path}.at`, field('{ [boundary]: DetectAction }'
|
|
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
|
-
|
|
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'
|
|
562
|
+
...field('boolean'),
|
|
417
563
|
unset: 'On',
|
|
418
564
|
},
|
|
419
565
|
],
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
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'
|
|
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) =>
|
|
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'
|
|
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
|
-
|
|
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?
|
|
501
|
-
*
|
|
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'
|
|
505
|
-
'profile.type': field("'text' | 'image' | 'speech' | 'transcription' | 'live' | 'decision' | 'embedding' | 'host'",
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
}),
|
|
515
|
-
|
|
516
|
-
'
|
|
517
|
-
'
|
|
518
|
-
'
|
|
519
|
-
'
|
|
520
|
-
'
|
|
521
|
-
'
|
|
522
|
-
|
|
523
|
-
'
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
'models.*.
|
|
529
|
-
'models.*.
|
|
530
|
-
'models.*.
|
|
531
|
-
|
|
532
|
-
'
|
|
533
|
-
'models.*.
|
|
534
|
-
'models.*.
|
|
535
|
-
'models.*.limits': field('
|
|
536
|
-
'models.*.limits.
|
|
537
|
-
'models.*.limits.
|
|
538
|
-
'models.*.limits.
|
|
539
|
-
'models.*.limits.
|
|
540
|
-
|
|
541
|
-
'
|
|
542
|
-
'models.*.
|
|
543
|
-
'models.*.
|
|
544
|
-
'models.*.
|
|
545
|
-
|
|
546
|
-
'
|
|
547
|
-
'models.*.
|
|
548
|
-
'models.*.
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
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'
|
|
706
|
+
...field('ProfileId'),
|
|
570
707
|
unset: 'The agent itself',
|
|
571
708
|
},
|
|
572
|
-
'models.*.compaction.timing': field(unionType(COMPACTION_TIMINGS),
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
'
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
'
|
|
581
|
-
'
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
'
|
|
585
|
-
'
|
|
586
|
-
'
|
|
587
|
-
'
|
|
588
|
-
inputs: field('
|
|
589
|
-
'inputs.
|
|
590
|
-
'inputs.
|
|
591
|
-
'inputs.
|
|
592
|
-
'inputs.
|
|
593
|
-
'inputs.
|
|
594
|
-
'inputs.
|
|
595
|
-
'inputs.
|
|
596
|
-
'inputs.
|
|
597
|
-
'inputs.
|
|
598
|
-
'inputs.
|
|
599
|
-
'inputs.
|
|
600
|
-
'inputs.
|
|
601
|
-
'inputs.
|
|
602
|
-
'inputs.
|
|
603
|
-
'inputs.
|
|
604
|
-
|
|
605
|
-
'
|
|
606
|
-
|
|
607
|
-
'
|
|
608
|
-
'
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
'
|
|
613
|
-
|
|
614
|
-
'
|
|
615
|
-
image: field('
|
|
616
|
-
'image.
|
|
617
|
-
|
|
618
|
-
'
|
|
619
|
-
'
|
|
620
|
-
'
|
|
621
|
-
'
|
|
622
|
-
|
|
623
|
-
'
|
|
624
|
-
'
|
|
625
|
-
'
|
|
626
|
-
|
|
627
|
-
'
|
|
628
|
-
'
|
|
629
|
-
'
|
|
630
|
-
'
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
live: field('
|
|
635
|
-
'live.
|
|
636
|
-
'live.
|
|
637
|
-
'live.
|
|
638
|
-
'live.
|
|
639
|
-
'live.
|
|
640
|
-
'live.
|
|
641
|
-
'live.
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
'live.
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
'
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
'
|
|
654
|
-
'
|
|
655
|
-
'
|
|
656
|
-
'
|
|
657
|
-
|
|
658
|
-
'
|
|
659
|
-
'
|
|
660
|
-
'
|
|
661
|
-
'
|
|
662
|
-
'
|
|
663
|
-
'
|
|
664
|
-
|
|
665
|
-
'
|
|
666
|
-
'
|
|
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'
|
|
704
|
-
'guardrails.blockedReply.onBlock': field(unionType(BLOCKED_REPLY_ON_BLOCK),
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
'guardrails.
|
|
709
|
-
'guardrails.network': field('
|
|
710
|
-
'guardrails.
|
|
711
|
-
'guardrails.
|
|
712
|
-
'guardrails.
|
|
713
|
-
'guardrails.
|
|
714
|
-
'guardrails.
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
'
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
'
|
|
725
|
-
'
|
|
726
|
-
|
|
727
|
-
'
|
|
728
|
-
observability: field('
|
|
729
|
-
'observability.
|
|
730
|
-
'observability.
|
|
731
|
-
'observability.
|
|
732
|
-
'observability.
|
|
733
|
-
'observability.
|
|
734
|
-
'observability.
|
|
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),
|
|
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',
|
|
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'
|
|
847
|
+
'local.baseUrl': field('string'),
|
|
780
848
|
'studio.remoteTools': {
|
|
781
|
-
...field('boolean'
|
|
849
|
+
...field('boolean'),
|
|
782
850
|
unset: 'Off',
|
|
783
851
|
},
|
|
784
|
-
'decision.questions.id': field('string'
|
|
785
|
-
'decision.questions.type': field(
|
|
786
|
-
|
|
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'
|
|
856
|
+
...field('string'),
|
|
794
857
|
unset: 'The image the instructions name',
|
|
795
858
|
},
|
|
796
|
-
'decision.images': field('Record<string, DecisionAsset>'
|
|
797
|
-
'decision.images.name': field('string'
|
|
798
|
-
'registerTool.name': field('string'
|
|
799
|
-
'registerTool.description': field('string'
|
|
800
|
-
'registerTool.input': field('ZodSchema'
|
|
801
|
-
'registerTool.output': field('ZodSchema'
|
|
802
|
-
'registerTool.handler': field('ToolHandler'
|
|
803
|
-
'registerTool.endpoint': field('string'
|
|
804
|
-
'registerTool.method': field(unionType(HTTP_METHODS),
|
|
805
|
-
'registerTool.headers': field('Record<string, string>'
|
|
806
|
-
'registerTool.mapping': field('{ pathParams?, queryParams?, bodyParam? }'
|
|
807
|
-
'registerTool.mapping.pathParams': field('string[]'
|
|
808
|
-
'registerTool.mapping.queryParams': field('string[]'
|
|
809
|
-
'registerTool.mapping.bodyParam': field('string'
|
|
810
|
-
'registerTool.serverUrl': field('string'
|
|
811
|
-
'registerTool.mcpToolName': field('string'
|
|
812
|
-
'registerTool.profile': field('ProfileId'
|
|
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'",
|
|
877
|
+
...field("'page'", ['page']),
|
|
815
878
|
unset: 'Its handler',
|
|
816
879
|
},
|
|
817
880
|
'registerTool.maxResponseBytes': {
|
|
818
|
-
...field('number'
|
|
881
|
+
...field('number'),
|
|
819
882
|
unset: 'No limit',
|
|
820
883
|
},
|
|
821
884
|
'registerTool.session': {
|
|
822
|
-
...field('McpSessionLimits'
|
|
885
|
+
...field('McpSessionLimits'),
|
|
823
886
|
unset: 'No limits',
|
|
824
887
|
},
|
|
825
888
|
'registerTool.session.idleMs': {
|
|
826
|
-
...field('number'
|
|
889
|
+
...field('number'),
|
|
827
890
|
unset: 'No limit',
|
|
828
891
|
},
|
|
829
892
|
'registerTool.session.max': {
|
|
830
|
-
...field('number'
|
|
893
|
+
...field('number'),
|
|
831
894
|
unset: 'No limit',
|
|
832
895
|
},
|
|
833
896
|
'registerTool.maxCallsPerTurn': {
|
|
834
|
-
...field('number'
|
|
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>>'
|
|
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>'
|
|
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'>"
|
|
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'
|
|
913
|
+
...field('ToolAuthConfig'),
|
|
851
914
|
unset: 'No credential',
|
|
852
915
|
},
|
|
853
|
-
'registerTool.auth.type': field(unionType(TOOL_AUTH_TYPES),
|
|
854
|
-
'registerTool.auth.slot': field('string'
|
|
855
|
-
'registerTool.auth.service': field('string'
|
|
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'
|
|
920
|
+
...field('string'),
|
|
858
921
|
unset: 'Authorization',
|
|
859
922
|
},
|
|
860
923
|
'registerTool.auth.headerPrefix': {
|
|
861
|
-
...field('string'
|
|
924
|
+
...field('string'),
|
|
862
925
|
unset: '"Bearer " for tokens, nothing for API keys',
|
|
863
926
|
},
|
|
864
927
|
'registerTool.auth.queryParam': {
|
|
865
|
-
...field('string'
|
|
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),
|
|
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 }>'
|
|
877
|
-
'registerTool.auth.scopes': field('string[]'
|
|
878
|
-
'registerTool.auth.clientId': field('string'
|
|
879
|
-
'registerTool.auth.redirectUri': field('string'
|
|
880
|
-
'studio.authType': field(unionType(STUDIO_AUTH_TYPES),
|
|
881
|
-
'studio.testCredential': field('string'
|
|
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>'
|
|
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>'
|
|
887
|
-
'registerTool.inputSchema': field('Record<string, unknown>'
|
|
888
|
-
'registerTool.outputSchema': field('Record<string, unknown>'
|
|
889
|
-
'registerStructured.jsonSchema': field('Record<string, unknown>'
|
|
890
|
-
'registerTool.access': field(unionType(TOOL_ACCESS),
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
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'
|
|
954
|
+
...field('boolean'),
|
|
907
955
|
unset: 'The model can',
|
|
908
956
|
},
|
|
909
|
-
'registerTool.sources': field('(output) => Source[]'
|
|
910
|
-
'registerTool.images': field('(output) => string[]'
|
|
957
|
+
'registerTool.sources': field('(output) => Source[]'),
|
|
958
|
+
'registerTool.images': field('(output) => string[]'),
|
|
911
959
|
'registerTool.imageLimits': {
|
|
912
|
-
...field('ToolImageLimits'
|
|
960
|
+
...field('ToolImageLimits'),
|
|
913
961
|
unset: 'No limit',
|
|
914
962
|
},
|
|
915
|
-
'registerTool.askInputSchema': field('Record<string, unknown>'
|
|
916
|
-
'registerTool.conflictsWith': field('string[]'
|
|
963
|
+
'registerTool.askInputSchema': field('Record<string, unknown>'),
|
|
964
|
+
'registerTool.conflictsWith': field('string[]'),
|
|
917
965
|
'registerTool.limit': {
|
|
918
|
-
...field('HttpToolLimit'
|
|
966
|
+
...field('HttpToolLimit'),
|
|
919
967
|
unset: 'No limit',
|
|
920
968
|
},
|
|
921
969
|
'registerTool.timeoutMs': {
|
|
922
|
-
...field('number'
|
|
970
|
+
...field('number'),
|
|
923
971
|
unset: "As long as the caller's signal lets it",
|
|
924
972
|
},
|
|
925
973
|
'registerTool.after': {
|
|
926
|
-
...field('boolean'
|
|
974
|
+
...field('boolean'),
|
|
927
975
|
unset: 'The model sets no order',
|
|
928
976
|
},
|
|
929
977
|
'registerTool.background': {
|
|
930
|
-
...field("'always' | { afterMs: number } | 'ask' | 'never'",
|
|
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'
|
|
941
|
-
'registerTool.category': field('string'
|
|
942
|
-
'registerTool.labels': field('ToolLabels'
|
|
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[]'
|
|
985
|
+
...field('string | string[]'),
|
|
945
986
|
unset: 'The tool name, in words',
|
|
946
987
|
},
|
|
947
988
|
'registerTool.labels.activityPast': {
|
|
948
|
-
...field('string | string[]'
|
|
989
|
+
...field('string | string[]'),
|
|
949
990
|
unset: 'The tool name, in words',
|
|
950
991
|
},
|
|
951
992
|
'registerTool.labels.activityFailed': {
|
|
952
|
-
...field('string | string[]'
|
|
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[]'
|
|
997
|
+
...field('string | string[]'),
|
|
957
998
|
unset: 'The tool name, in words',
|
|
958
999
|
},
|
|
959
1000
|
'registerTool.paths': {
|
|
960
|
-
...field('string[]'
|
|
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];
|