@theoremjs/agents 0.3.4-next.863.gb601f58 → 0.3.4-next.871.gea9bbcc

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
@@ -27,7 +27,12 @@ export const GUARDRAIL_STAGES = [
27
27
  /** Does not decide what happens next; that is `blockedReply`. */
28
28
  export const SEVERITIES = ['info', 'low', 'medium', 'high'];
29
29
  /** What follows a blocked reply: the model rewrites it, or the user reads a refusal. */
30
- export const BLOCKED_REPLY_ON_BLOCK = ['retry', 'refuse'];
30
+ export const BLOCKED_REPLY_ON_BLOCK = [
31
+ /** 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. */
32
+ 'retry',
33
+ /** The user sees the egress.refusal wording in place of the reply, and the turn ends. */
34
+ 'refuse',
35
+ ];
31
36
  export const GUARDRAIL_ACTIONS = [
32
37
  'allow',
33
38
  'redact',
@@ -48,9 +53,23 @@ export const TOOL_ORIGINS = ['local', 'builtin', 'http', 'mcp', 'delegated'];
48
53
  */
49
54
  export const ADVISORY_LEVELS = ['none', 'elevated', 'high'];
50
55
  /** Which tool access levels refuse to run once a turn has read untrusted content. */
51
- export const TAINT_GATES = ['off', 'destructive', 'write'];
56
+ export const TAINT_GATES = [
57
+ /** None; risky calls are only logged. */
58
+ 'off',
59
+ /** Destructive calls. */
60
+ 'destructive',
61
+ /** Read-write and destructive calls. */
62
+ 'write',
63
+ ];
52
64
  /** What happens to a tool call that sends to a destination only remote content named. */
53
- export const DESTINATION_GATES = ['off', 'confirm', 'block'];
65
+ export const DESTINATION_GATES = [
66
+ /** The call runs; it is only logged. */
67
+ 'off',
68
+ /** The call waits for the user to approve it; an approval runs it. */
69
+ 'confirm',
70
+ /** The call is refused, and the model is told why. */
71
+ 'block',
72
+ ];
54
73
  /** The guardrail field names a `host` profile may set. */
55
74
  export const HOST_GUARDRAIL_FIELDS = [
56
75
  'detect',
@@ -1,85 +1,36 @@
1
1
  /** labels-exempt-file: authoring request-field and export meta — not runtime user or model copy (P2) */
2
2
  import type { FieldMeta } from './schema.js';
3
3
  import type { TurnInput, TurnRequest } from './types.js';
4
+ /** A `runTurn` request field's catalog path. */
5
+ export type RequestPath = `runTurn.${keyof TurnRequest | `input.${keyof TurnInput}`}`;
4
6
  /** The catalog of the fields a `runTurn` request takes, keyed `runTurn.<field>`. */
5
- export declare const REQUEST_FIELDS: Record<`runTurn.${keyof TurnRequest | `input.${keyof TurnInput}`}`, FieldMeta>;
7
+ export declare const REQUEST_FIELDS: Record<RequestPath, FieldMeta>;
6
8
  /** What the catalog records about one export: what it is and what it does. */
7
9
  export type ApiExportMeta = {
8
10
  kind: 'function' | 'class';
9
11
  doc: string;
10
12
  };
11
- /** The catalog of the exports a builder calls by name, keyed by that name. */
12
- export declare const API_EXPORTS: {
13
- readonly defineProfile: {
14
- readonly kind: "function";
15
- readonly doc: "Checks a profile and returns it; a field the profile type cannot take is a config error.";
16
- };
17
- readonly registerProfile: {
18
- readonly kind: "function";
19
- readonly doc: "Stores a profile under its id, so that a request can name it.";
20
- };
21
- readonly registerTool: {
22
- readonly kind: "function";
23
- readonly doc: "Stores a tool under its name, so that a profile can list it in tools.allow.";
24
- };
25
- readonly registerStructured: {
26
- readonly kind: "function";
27
- readonly doc: "Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.";
28
- };
29
- readonly registerTraceDestination: {
30
- readonly kind: "function";
31
- readonly doc: "Stores a place to write traces under an id, so that a profile can name it in observability.";
32
- };
33
- readonly defineProvider: {
34
- readonly kind: "function";
35
- readonly doc: "Validates a provider definition and supplies its typed model helper.";
36
- };
37
- readonly registerProvider: {
38
- readonly kind: "function";
39
- readonly doc: "Registers a provider instance before profiles reference its ID.";
40
- };
41
- readonly runTurn: {
42
- readonly kind: "function";
43
- readonly doc: "Runs one turn of a text, image, or speech profile and yields its events.";
44
- };
45
- readonly runSession: {
46
- readonly kind: "function";
47
- readonly doc: "Runs a realtime voice or video session of a live profile.";
48
- };
49
- readonly runDecision: {
50
- readonly kind: "function";
51
- readonly doc: "Asks a decision profile its questions about your JSON state and returns checked answers.";
52
- };
53
- readonly invokeTool: {
54
- readonly kind: "function";
55
- readonly doc: "Runs one registered tool through a profile, with no model.";
56
- };
57
- readonly runTool: {
58
- readonly kind: "function";
59
- readonly doc: "Runs one registered tool through a profile, with no model, and returns how the call settled.";
60
- };
61
- readonly compactHistory: {
62
- readonly kind: "function";
63
- readonly doc: "Shortens a conversation history with the compaction the profile sets.";
64
- };
65
- readonly takeSlot: {
66
- readonly kind: "function";
67
- readonly doc: "Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.";
68
- };
69
- readonly releaseSlot: {
70
- readonly kind: "function";
71
- readonly doc: "Frees the turn slot that takeSlot gave.";
72
- };
73
- readonly overrideLabels: {
74
- readonly kind: "function";
75
- readonly doc: "Replaces status lines for every profile in the process; a profile's own labels wins.";
76
- };
77
- readonly resetLabels: {
78
- readonly kind: "function";
79
- readonly doc: "Removes every replacement that overrideLabels made.";
80
- };
81
- readonly TheoremError: {
82
- readonly kind: "class";
83
- readonly doc: "The error Theorem throws; its kind tells your host which status and wording to use.";
84
- };
13
+ /** What each export a builder calls by name is. */
14
+ declare const EXPORT_KINDS: {
15
+ readonly defineProfile: "function";
16
+ readonly registerProfile: "function";
17
+ readonly registerTool: "function";
18
+ readonly registerStructured: "function";
19
+ readonly registerTraceDestination: "function";
20
+ readonly defineProvider: "function";
21
+ readonly registerProvider: "function";
22
+ readonly runTurn: "function";
23
+ readonly runSession: "function";
24
+ readonly runDecision: "function";
25
+ readonly invokeTool: "function";
26
+ readonly runTool: "function";
27
+ readonly compactHistory: "function";
28
+ readonly takeSlot: "function";
29
+ readonly releaseSlot: "function";
30
+ readonly overrideLabels: "function";
31
+ readonly resetLabels: "function";
32
+ readonly TheoremError: "class";
85
33
  };
34
+ /** The catalog of the exports a builder calls by name, keyed by that name; each doc is its JSDoc. */
35
+ export declare const API_EXPORTS: Record<keyof typeof EXPORT_KINDS, ApiExportMeta>;
36
+ export {};
@@ -1,260 +1,178 @@
1
1
  /** labels-exempt-file: authoring request-field and export meta — not runtime user or model copy (P2) */
2
+ import { EXPORT_DOCS, FIELD_DOCS } from './field-docs.js';
3
+ /** Gives each row its doc: the JSDoc on its declaration, through `FIELD_DOCS`. */
4
+ function withFieldDocs(rows) {
5
+ return Object.fromEntries(Object.entries(rows).map(([path, { type, ...rest }]) => [
6
+ path,
7
+ { type, doc: FIELD_DOCS[path] ?? '', ...rest },
8
+ ]));
9
+ }
2
10
  /** The catalog of the fields a `runTurn` request takes, keyed `runTurn.<field>`. */
3
- export const REQUEST_FIELDS = {
11
+ export const REQUEST_FIELDS = withFieldDocs({
4
12
  'runTurn.background': {
5
13
  type: 'ToolBackgroundService',
6
- doc: 'Host-issued service for tool calls that go on after their reply. It needs a coordinator with detach. Without it every tool runs inline.',
7
14
  },
8
15
  'runTurn.pageExecution': {
9
16
  type: 'PageToolExecution',
10
- doc: 'Host-issued browser dispatch with a claimed operation and correlated result.',
11
17
  },
12
18
  'runTurn.execution': {
13
19
  type: 'ToolExecutionCoordinator',
14
- doc: 'Host-owned atomic tool claims and outcomes. Never sent to providers.',
15
20
  },
16
21
  'runTurn.providerState': {
17
22
  type: 'ProviderCheckpoint',
18
- doc: 'Native provider state saved alongside portable history.',
19
23
  },
20
24
  'runTurn.profile': {
21
25
  type: 'string',
22
- doc: 'The id of the registered profile the turn runs.',
23
26
  required: true,
24
27
  },
25
- 'runTurn.input': { type: 'TurnInput', doc: 'What the user sent for the turn.' },
26
- 'runTurn.input.text': { type: 'string', doc: "The user's message." },
28
+ 'runTurn.input': { type: 'TurnInput' },
29
+ 'runTurn.input.text': { type: 'string' },
27
30
  'runTurn.input.options': {
28
31
  type: 'Record<string, string>',
29
- doc: "The value a person picked for each option in the profile's inputs.options; an option or a value the profile does not declare is refused.",
30
32
  unset: 'The person picked none',
31
33
  },
32
34
  'runTurn.input.context': {
33
35
  type: "Partial<Record<'client' | 'server', unknown>>",
34
- doc: "What the page (client) or the host (server) wants the model to know, as any JSON or text; a sender the profile's inputs.context does not list, or a package over its maxChars, is refused.",
35
36
  unset: 'No context',
36
37
  },
37
38
  'runTurn.input.lateResults': {
38
39
  type: 'ToolOperationOutcome[]',
39
- doc: 'Background tool calls that settled after their turn, as the host stored them. The model reads each as a tool result, and this reply counts it as a remote read when the call was remote. Pass each one once: the turn emits it as a late_results event, so a history built from events holds it.',
40
40
  unset: 'No late results',
41
41
  },
42
42
  'runTurn.input.attachments': {
43
43
  type: 'Array<TurnBlob | TurnMediaRef>',
44
- doc: "Files sent with the turn, as bytes or as a provider file reference; each must pass the profile's inputs.attachments.",
45
44
  },
46
45
  'runTurn.input.voice': {
47
46
  type: 'TurnBlob[]',
48
- doc: "Recorded speech sent with the turn; each must pass the profile's inputs.voice.",
49
47
  },
50
48
  'runTurn.input.history': {
51
49
  type: 'TurnHistoryMessage[]',
52
- doc: 'The earlier messages of the conversation, when the host keeps them.',
53
50
  unset: 'The turn starts a new conversation',
54
51
  },
55
52
  'runTurn.input.repair': {
56
53
  type: 'TurnRepairRequest',
57
- doc: 'A reply your host rejected and why, so that the model writes it again.',
58
54
  },
59
55
  'runTurn.input.historyTokens': {
60
56
  type: 'number',
61
- doc: "Your count of the history's tokens, used by compaction that meters history.",
62
57
  unset: "Theorem's own estimate",
63
58
  },
64
59
  'runTurn.input.inputTokens': {
65
60
  type: 'number',
66
- doc: "Your count of the whole prompt's tokens, used by compaction that meters input before the call.",
67
61
  },
68
62
  'runTurn.model': {
69
63
  type: 'string',
70
- doc: "The model id the turn picks from the profile's models; refused unless the profile sets allowModelSelect.",
71
64
  unset: "The profile's defaultModel",
72
65
  },
73
66
  'runTurn.effort': {
74
67
  type: 'string',
75
- doc: "The effort the turn picks from the model's efforts; refused unless the model sets allowEffortSelect.",
76
68
  unset: "The model's default effort",
77
69
  },
78
70
  'runTurn.builtInArgs': {
79
71
  type: 'Record<BuiltinToolId, JsonObject>',
80
- doc: "Args for the provider's own tools on the chosen model's builtInTools, by tool id; each is checked by the schema the provider declares for that tool.",
81
72
  unset: 'Each built-in runs with no args',
82
73
  },
83
74
  'runTurn.system': {
84
75
  type: 'SystemPrompt',
85
- doc: "An instruction for this request only, added to the profile's own.",
86
76
  },
87
77
  'runTurn.options': {
88
78
  type: 'Record<string, string>',
89
- doc: "The value the host's code sets for each option in the profile's identity.options but path; an option or a value the profile does not declare is refused.",
90
79
  unset: 'The code set none',
91
80
  },
92
81
  'runTurn.path': {
93
82
  type: 'string',
94
- doc: 'The channel the turn comes from; only tools whose paths name it, or *, are offered.',
95
83
  unset: 'Only tools on every path',
96
84
  },
97
85
  'runTurn.sessionPermissions': {
98
86
  type: 'string[]',
99
- doc: 'The tools the user has already approved for this session.',
100
87
  },
101
88
  'runTurn.credentials': {
102
89
  type: 'ToolCredentialSource',
103
- doc: 'Where an HTTP or MCP tool gets the credential for its auth slot.',
104
90
  },
105
91
  'runTurn.host': {
106
92
  type: 'unknown',
107
- doc: 'Your own context, handed to tool handlers as ctx.host; Theorem never reads or records it.',
108
93
  },
109
94
  'runTurn.signal': {
110
95
  type: 'AbortSignal',
111
- doc: 'Stops the turn when it aborts, and cancels the provider call where the provider can.',
112
96
  },
113
97
  'runTurn.sessionId': {
114
98
  type: 'string',
115
- doc: 'A session key that OpenRouter uses for routing and caching.',
116
99
  },
117
100
  'runTurn.projectId': {
118
101
  type: 'string',
119
- doc: 'Your project id, recorded on the trace.',
120
102
  },
121
103
  'runTurn.conversationId': {
122
104
  type: 'string',
123
- doc: 'Your conversation id, recorded on the trace.',
124
105
  },
125
106
  'runTurn.metadata': {
126
107
  type: 'Record<string, unknown>',
127
- doc: 'Your own values, kept on the trace; Theorem does not read them.',
128
108
  },
129
109
  'runTurn.traceparent': {
130
110
  type: 'string',
131
- doc: "The W3C traceparent of your span; the turn's trace joins it as a child.",
132
111
  unset: 'The turn starts a new trace',
133
112
  },
134
113
  'runTurn.links': {
135
114
  type: 'TurnTraceLink[]',
136
- doc: 'Earlier traces this turn follows: a resume, a continue, or a retry.',
137
115
  },
138
116
  'runTurn.continueFrom': {
139
117
  type: 'TurnContinueFrom',
140
- doc: 'Continues a turn that stopped in a way the profile lets a turn continue.',
141
118
  },
142
119
  'runTurn.continuation': {
143
120
  type: 'number',
144
- doc: 'Which continue attempt this is, from 1; checked against the maxContinues of the profile.',
145
121
  },
146
122
  'runTurn.promoted': {
147
123
  type: 'ToolId[]',
148
- doc: 'Tools this reply already had when an earlier run of it paused; the turn opens with them on its list.',
149
124
  },
150
125
  'runTurn.stepsTaken': {
151
126
  type: 'number',
152
- doc: 'Steps this reply already took when an earlier run of it paused; they count against maxSteps.',
153
127
  },
154
128
  'runTurn.speech': {
155
129
  type: 'TurnSpeech',
156
- doc: "This turn's voice, style, and speed; each one given replaces the profile's speech field of that name. Refused on a profile that is not speech.",
157
130
  unset: "The profile's speech settings",
158
131
  },
159
132
  'runTurn.resolveHost': {
160
133
  type: 'ResolveHost',
161
- doc: 'Resolves the host name of a remote tool before each request; a name that resolves to a private address is refused.',
162
134
  },
163
135
  'runTurn.fetch': {
164
136
  type: 'typeof fetch',
165
- doc: "Sends each request a remote tool makes, once that request's network checks pass. A page whose tools cannot reach a host directly sends them through its own server here.",
166
137
  unset: 'The global fetch',
167
138
  },
168
139
  'runTurn.onStage': {
169
140
  type: 'StageHandler',
170
- doc: 'Your function that sees each stage of a text turn and can answer with what the stage allows.',
171
141
  },
172
142
  'runTurn.onAgentCall': {
173
143
  type: 'AgentCallHook',
174
- doc: 'Runs before each agent tool call, to shape the request to the called agent or to refuse the call.',
175
144
  unset: 'The agent runs on what the model sent',
176
145
  },
177
146
  'runTurn.onEvent': {
178
147
  type: '(event: TurnEvent) => void | Promise<void>',
179
- doc: "Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw ends the turn with that error.",
180
148
  },
181
149
  'runTurn.answersHeldCall': {
182
150
  type: 'true',
183
- doc: "Set on the turn TurnWiring.prepare is given for a held call that goes on once answered: no model runs, and input is the paused turn's.",
184
- },
185
- };
186
- /** The catalog of the exports a builder calls by name, keyed by that name. */
187
- export const API_EXPORTS = {
188
- defineProfile: {
189
- kind: 'function',
190
- doc: 'Checks a profile and returns it; a field the profile type cannot take is a config error.',
191
- },
192
- registerProfile: {
193
- kind: 'function',
194
- doc: 'Stores a profile under its id, so that a request can name it.',
195
- },
196
- registerTool: {
197
- kind: 'function',
198
- doc: 'Stores a tool under its name, so that a profile can list it in tools.allow.',
199
- },
200
- registerStructured: {
201
- kind: 'function',
202
- doc: 'Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.',
203
- },
204
- registerTraceDestination: {
205
- kind: 'function',
206
- doc: 'Stores a place to write traces under an id, so that a profile can name it in observability.',
207
- },
208
- defineProvider: {
209
- kind: 'function',
210
- doc: 'Validates a provider definition and supplies its typed model helper.',
211
- },
212
- registerProvider: {
213
- kind: 'function',
214
- doc: 'Registers a provider instance before profiles reference its ID.',
215
- },
216
- runTurn: {
217
- kind: 'function',
218
- doc: 'Runs one turn of a text, image, or speech profile and yields its events.',
219
- },
220
- runSession: {
221
- kind: 'function',
222
- doc: 'Runs a realtime voice or video session of a live profile.',
223
- },
224
- runDecision: {
225
- kind: 'function',
226
- doc: 'Asks a decision profile its questions about your JSON state and returns checked answers.',
227
- },
228
- invokeTool: {
229
- kind: 'function',
230
- doc: 'Runs one registered tool through a profile, with no model.',
231
- },
232
- runTool: {
233
- kind: 'function',
234
- doc: 'Runs one registered tool through a profile, with no model, and returns how the call settled.',
235
- },
236
- compactHistory: {
237
- kind: 'function',
238
- doc: 'Shortens a conversation history with the compaction the profile sets.',
239
- },
240
- takeSlot: {
241
- kind: 'function',
242
- doc: "Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.",
243
- },
244
- releaseSlot: {
245
- kind: 'function',
246
- doc: 'Frees the turn slot that takeSlot gave.',
247
- },
248
- overrideLabels: {
249
- kind: 'function',
250
- doc: "Replaces status lines for every profile in the process; a profile's own labels wins.",
251
- },
252
- resetLabels: {
253
- kind: 'function',
254
- doc: 'Removes every replacement that overrideLabels made.',
255
- },
256
- TheoremError: {
257
- kind: 'class',
258
- doc: 'The error Theorem throws; its kind tells your host which status and wording to use.',
259
151
  },
152
+ });
153
+ /** What each export a builder calls by name is. */
154
+ const EXPORT_KINDS = {
155
+ defineProfile: 'function',
156
+ registerProfile: 'function',
157
+ registerTool: 'function',
158
+ registerStructured: 'function',
159
+ registerTraceDestination: 'function',
160
+ defineProvider: 'function',
161
+ registerProvider: 'function',
162
+ runTurn: 'function',
163
+ runSession: 'function',
164
+ runDecision: 'function',
165
+ invokeTool: 'function',
166
+ runTool: 'function',
167
+ compactHistory: 'function',
168
+ takeSlot: 'function',
169
+ releaseSlot: 'function',
170
+ overrideLabels: 'function',
171
+ resetLabels: 'function',
172
+ TheoremError: 'class',
260
173
  };
174
+ /** The catalog of the exports a builder calls by name, keyed by that name; each doc is its JSDoc. */
175
+ export const API_EXPORTS = Object.fromEntries(Object.entries(EXPORT_KINDS).map(([name, kind]) => [
176
+ name,
177
+ { kind, doc: EXPORT_DOCS[name] ?? '' },
178
+ ]));
@@ -31,7 +31,11 @@ export interface ProviderWarning {
31
31
  export declare const providerWarningSchema: z.ZodType<ProviderWarning>;
32
32
  export interface ProviderContinuationPolicy {
33
33
  /**
34
- * Who holds the conversation a checkpoint continues. `'host'` (unset) passes the covered
34
+ * Who holds the conversation a checkpoint continues: the host passes history back, the provider
35
+ * keeps it and the checkpoint travels alone, or the profile is stateless and every request stands
36
+ * alone.
37
+ *
38
+ * @remarks Who holds the conversation a checkpoint continues. `'host'` (unset) passes the covered
35
39
  * history back with the checkpoint. `'provider'` passes the checkpoint alone: the provider's
36
40
  * stored conversation is the history, and a turn that goes elsewhere needs the host's history.
37
41
  * `'stateless'` keeps no conversation: a request that carries history or a checkpoint is refused,
@@ -10,7 +10,11 @@ import { defaultKernelScope as scope } from './scope.js';
10
10
  import type { ToolCallResult, ToolStepCallResult } from './tools/run.js';
11
11
  import type { InvokeToolRequest, InvokeToolStepRequest, RegisteredTool, ToolDefinitionInput } from './tools/types.js';
12
12
  import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, EmbeddingRequest, EmbeddingResult, LiveSession, Profile, ProjectedProfile, SessionRequest, StructuredSpec, TurnEvent, TurnRequest } from './types.js';
13
- /** Register or replace a tool in the default scope. */
13
+ /**
14
+ * Stores a tool under its name, so that a profile can list it in tools.allow.
15
+ *
16
+ * @remarks Register or replace a tool in the default scope.
17
+ */
14
18
  declare function registerTool<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
15
19
  /** Register or replace several tools in the default scope. */
16
20
  declare function registerTools(defs: ToolDefinitionInput[]): RegisteredTool[];
@@ -24,7 +28,11 @@ declare function hasTool(name: string): boolean;
24
28
  declare function listTools(): RegisteredTool[];
25
29
  /** Remove every tool from the default scope. */
26
30
  declare function resetTools(): void;
27
- /** Define, validate, and register a profile in the default scope. */
31
+ /**
32
+ * Stores a profile under its id, so that a request can name it.
33
+ *
34
+ * @remarks Define, validate, and register a profile in the default scope.
35
+ */
28
36
  declare function registerProfile(profile: Profile | ProfileDefinition): void;
29
37
  /** Define, validate, and register several profiles in the default scope. */
30
38
  declare function registerProfiles(profiles: Array<Profile | ProfileDefinition>): void;
@@ -36,21 +44,47 @@ declare function hasProfile(id: string): boolean;
36
44
  declare function listProfiles(): Profile[];
37
45
  /** Remove every profile from the default scope. */
38
46
  declare function clearProfiles(): void;
39
- /** Register a structured-output schema in the default scope under `id`. */
47
+ /**
48
+ * Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.
49
+ *
50
+ * @remarks Register a structured-output schema in the default scope under `id`.
51
+ */
40
52
  declare function registerStructured(id: string, spec: StructuredSpec): void;
41
53
  /** The default scope's schema `id`; throws when there is none. */
42
54
  declare function getStructured(id: string): StructuredSpec;
43
- /** Run one turn of a profile in the default scope, streaming its events. */
55
+ /**
56
+ * Runs one turn of a text, image, or speech profile and yields its events.
57
+ *
58
+ * @remarks Run one turn of a profile in the default scope, streaming its events.
59
+ */
44
60
  declare function runTurn(req: TurnRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
45
- /** Open a live session for a live profile in the default scope. */
61
+ /**
62
+ * Runs a realtime voice or video session of a live profile.
63
+ *
64
+ * @remarks Open a live session for a live profile in the default scope.
65
+ */
46
66
  declare function runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
47
- /** Compact a conversation history with the model, or `undefined` when there is nothing to compact. */
67
+ /**
68
+ * Shortens a conversation history with the compaction the profile sets.
69
+ *
70
+ * @remarks Compact a conversation history with the model, or `undefined` when there is nothing to
71
+ * compact.
72
+ */
48
73
  declare function compactHistory(req: CompactHistoryRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
49
- /** Run a held tool call in the default scope, streaming the events of the turn it resumes. */
74
+ /**
75
+ * Runs one registered tool through a profile, with no model.
76
+ *
77
+ * @remarks Run a held tool call in the default scope, streaming the events of the turn it resumes.
78
+ */
50
79
  declare function invokeTool(request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
51
80
  /** Run the host's calls as one step in the default scope, streaming each call's events as they come. */
52
81
  declare function invokeToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
53
- /** Run one tool call in the default scope to its end: how it settled, with every event it emitted. */
82
+ /**
83
+ * Runs one registered tool through a profile, with no model, and returns how the call settled.
84
+ *
85
+ * @remarks Run one tool call in the default scope to its end: how it settled, with every event it
86
+ * emitted.
87
+ */
54
88
  declare function runTool(request: InvokeToolRequest, sinkOverride?: TraceSink): Promise<ToolCallResult>;
55
89
  /** Run the host's calls as one step in the default scope, giving each call's end as it settles. */
56
90
  declare function runToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<ToolStepCallResult>;
@@ -59,12 +93,20 @@ declare function resolveTurn(req: TurnRequest): ReturnType<typeof scope.resolveT
59
93
  /** Each model of profile `id` in the default scope that cannot run a plain turn on its provider, and why. */
60
94
  /** The profile `id` projected for a client, with server-only fields removed. */
61
95
  declare function projectProfile(id: string): ProjectedProfile;
62
- /** Answer a decision request with the profile's model in the default scope. */
96
+ /**
97
+ * Asks a decision profile its questions about your JSON state and returns checked answers.
98
+ *
99
+ * @remarks Answer a decision request with the profile's model in the default scope.
100
+ */
63
101
  declare function runDecision(request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
64
102
  /** Create vectors for one or more inputs in the default scope. */
65
103
  declare function runEmbedding(request: EmbeddingRequest, options?: RunEmbeddingOptions): Promise<EmbeddingResult>;
66
104
  export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTool, runToolStep, runTurn, };
67
- /** Registers a provider in the default scope, with this project's connection and key slots. */
105
+ /**
106
+ * Registers a provider instance before profiles reference its ID.
107
+ *
108
+ * @remarks Registers a provider in the default scope, with this project's connection and key slots.
109
+ */
68
110
  export declare function registerProvider<C, K>(provider: Provider<C, K>, registration?: Registration<C>): RegisteredProvider;
69
111
  export declare function getProvider(id: string): RegisteredProvider | undefined;
70
112
  export declare function listProviders(): RegisteredProvider[];