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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/esm/src/guardrails/detectors.d.ts +91 -21
  2. package/esm/src/guardrails/host-patterns.d.ts +15 -2
  3. package/esm/src/guardrails/labels.d.ts +11 -3
  4. package/esm/src/guardrails/labels.js +42 -23
  5. package/esm/src/guardrails/quota.d.ts +9 -3
  6. package/esm/src/guardrails/quota.js +9 -3
  7. package/esm/src/guardrails/theorem-error.d.ts +5 -1
  8. package/esm/src/guardrails/theorem-error.js +8 -4
  9. package/esm/src/guardrails/types.d.ts +66 -18
  10. package/esm/src/guardrails/types.js +22 -3
  11. package/esm/src/kernel/api-catalog.d.ts +26 -75
  12. package/esm/src/kernel/api-catalog.js +37 -119
  13. package/esm/src/kernel/checkpoint.d.ts +5 -1
  14. package/esm/src/kernel/default-scope.d.ts +52 -10
  15. package/esm/src/kernel/default-scope.js +52 -10
  16. package/esm/src/kernel/engine/runner/gates.js +66 -22
  17. package/esm/src/kernel/engine/runner/state.d.ts +5 -2
  18. package/esm/src/kernel/engine/runner/steps.js +15 -15
  19. package/esm/src/kernel/engine/runner/stream.d.ts +5 -0
  20. package/esm/src/kernel/engine/runner/stream.js +12 -1
  21. package/esm/src/kernel/field-docs.d.ts +13 -0
  22. package/esm/src/kernel/field-docs.js +613 -0
  23. package/esm/src/kernel/protocols/binding.d.ts +56 -0
  24. package/esm/src/kernel/protocols/limits.d.ts +9 -0
  25. package/esm/src/kernel/protocols/provider.d.ts +5 -1
  26. package/esm/src/kernel/protocols/provider.js +5 -1
  27. package/esm/src/kernel/registry/profiles.d.ts +154 -5
  28. package/esm/src/kernel/schema.d.ts +5 -7
  29. package/esm/src/kernel/schema.js +511 -470
  30. package/esm/src/kernel/stop.d.ts +41 -17
  31. package/esm/src/kernel/stop.js +9 -1
  32. package/esm/src/kernel/tools/background.d.ts +4 -0
  33. package/esm/src/kernel/tools/types.d.ts +331 -43
  34. package/esm/src/kernel/turn-events.d.ts +4 -3
  35. package/esm/src/kernel/types.d.ts +482 -89
  36. package/esm/src/observability/destinations.d.ts +5 -1
  37. package/esm/src/observability/destinations.js +5 -1
  38. package/esm/src/observability/trace-catalog.js +62 -102
  39. package/esm/src/observability/types.d.ts +93 -19
  40. package/esm/src/providers/shared/carried-tool-files.js +9 -8
  41. package/package.json +1 -1
@@ -7,8 +7,23 @@ import type { RegisteredProvider } from './provider.js';
7
7
  /** A vault slot name. */
8
8
  export declare const keySlotSchema: z.ZodString;
9
9
  export declare const commonModelSettingsSchema: z.ZodObject<{
10
+ /**
11
+ * The token limit for one reply. Some providers never send it for speech, or for image without
12
+ * includeText.
13
+ */
10
14
  maxOutputTokens: z.ZodOptional<z.ZodNumber>;
15
+ /**
16
+ * How varied the model's wording is; higher is more random. Some providers never send it for
17
+ * speech, or for image without includeText.
18
+ */
11
19
  temperature: z.ZodOptional<z.ZodNumber>;
20
+ /**
21
+ * Named thinking levels. A turn picks one when allowEffortSelect is on. A provider refuses a
22
+ * level its model does not take. Speech ignores them, and so may an image profile without
23
+ * includeText.
24
+ *
25
+ * @catalog models.*.efforts.* The thinking level sent to the provider for this name.
26
+ */
12
27
  efforts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
13
28
  none: 'none';
14
29
  minimal: 'minimal';
@@ -18,24 +33,65 @@ export declare const commonModelSettingsSchema: z.ZodObject<{
18
33
  xhigh: 'xhigh';
19
34
  max: 'max';
20
35
  }>>>;
36
+ /** The effort a turn gets when it doesn't pick one. */
21
37
  defaultEffort: z.ZodOptional<z.ZodString>;
38
+ /** Lets a turn pick an effort; needs two or more efforts. */
22
39
  allowEffortSelect: z.ZodOptional<z.ZodBoolean>;
40
+ /**
41
+ * Asks the model for summaries of its thinking, which not every model sends; with some providers,
42
+ * off only hides thoughts, and others ignore it.
43
+ */
23
44
  summaries: z.ZodOptional<z.ZodBoolean>;
45
+ /**
46
+ * The provider's own tools, such as Google Search, this model may use; each must be registered as
47
+ * a builtin tool and declared by the provider's adapter.
48
+ */
24
49
  builtInTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
50
+ /**
51
+ * Summarises history past a threshold. A text agent can write the summary. Other types name a
52
+ * compaction profile.
53
+ */
25
54
  compaction: z.ZodOptional<z.ZodCustom<import('../types.js').CompactionSpec>>;
26
55
  }>;
27
56
  /** One entry under a profile's `models`: which protocol, which provider, which model, and its settings. */
28
57
  export interface ModelBinding extends z.infer<typeof commonModelSettingsSchema> {
58
+ /** The API shape this model is spoken to in. */
29
59
  protocol: string;
60
+ /**
61
+ * The service that runs the model or routes requests to one, such as Gemini or OpenRouter. Its
62
+ * registration supplies the endpoint and authentication.
63
+ */
30
64
  provider: string;
65
+ /**
66
+ * The model's id as the provider lists it, such as gemini-2.5-flash; sent on every call. The name
67
+ * this model has in the profile is its key in models.
68
+ */
31
69
  apiId: string;
70
+ /**
71
+ * The key slot this model's calls are signed with, instead of the provider's. Use it to bill one
72
+ * model to a different key. Absent: the provider's primary slot.
73
+ */
32
74
  keySlot?: string;
75
+ /**
76
+ * The key slot tried once after a rate limit or a busy model on the primary slot, instead of the
77
+ * provider's fallback. Must differ from the primary slot. Absent: the provider's fallback slot,
78
+ * if it has one.
79
+ */
33
80
  fallbackKeySlot?: string;
81
+ /**
82
+ * Settings only this model's protocol has, such as a task type or vector size. Each is checked
83
+ * when the profile loads. Any left out keep the provider's default.
84
+ */
34
85
  options?: JsonObject;
86
+ /**
87
+ * The points at which Theorem stops this model's calls. Each one left out is no limit, so the
88
+ * provider's own limits apply. A runTurn limits value overrides each field it sets.
89
+ */
35
90
  limits?: ProviderLimits;
36
91
  }
37
92
  /** A decision profile's model: no generation settings, and a time limit. */
38
93
  export interface DecisionModelBinding extends Pick<ModelBinding, 'protocol' | 'provider' | 'apiId' | 'keySlot' | 'fallbackKeySlot' | 'options' | 'limits'> {
94
+ /** How long a decision waits for its provider, in milliseconds. Omit for no timeout. */
39
95
  timeoutMs?: number;
40
96
  }
41
97
  export declare const modelBindingSchema: z.ZodType<ModelBinding>;
@@ -1,14 +1,23 @@
1
1
  import { z } from 'zod';
2
2
  /** The budgets a provider call runs under. Each one left out is no limit: the provider's own applies. */
3
3
  export interface ProviderLimits {
4
+ /** How long one call may take, in milliseconds, retries included. */
4
5
  operationTimeoutMs?: number;
6
+ /** How long a live session may take to open, in milliseconds. */
5
7
  connectTimeoutMs?: number;
8
+ /** How long a live session may wait for the model to answer, in milliseconds. */
6
9
  liveStepTimeoutMs?: number;
10
+ /** The most bytes in one record the provider sends: a stream event or a socket message. */
7
11
  maxWireRecordBytes?: number;
12
+ /** The most bytes the provider sends for one step. */
8
13
  maxWireResponseBytes?: number;
14
+ /** The most bytes in one event of a step. */
9
15
  maxEventBytes?: number;
16
+ /** The most bytes in all the events of one step. */
10
17
  maxStepBytes?: number;
18
+ /** The most events in one step. */
11
19
  maxStepEvents?: number;
20
+ /** The most tool calls one step may ask for. */
12
21
  maxPendingToolCalls?: number;
13
22
  }
14
23
  export declare const providerLimitsSchema: z.ZodType<ProviderLimits>;
@@ -75,7 +75,11 @@ export interface ProviderDefinition<C = unknown, K = unknown> {
75
75
  }
76
76
  /** A provider as defined; register it to use it. */
77
77
  export type Provider<C = unknown, K = unknown> = Readonly<ProviderDefinition<C, K>>;
78
- /** Defines a provider. Nothing in it can change a request or read a reply. */
78
+ /**
79
+ * Validates a provider definition and supplies its typed model helper.
80
+ *
81
+ * @remarks Defines a provider. Nothing in it can change a request or read a reply.
82
+ */
79
83
  export declare function defineProvider<C = undefined, K = undefined>(definition: ProviderDefinition<C, K>): Provider<C, K>;
80
84
  /** What a builder sets when registering a provider. */
81
85
  export interface Registration<C> {
@@ -41,7 +41,11 @@ const providerShape = z.object({
41
41
  description: z.string().min(1),
42
42
  traceName: z.string().min(1).optional(),
43
43
  });
44
- /** Defines a provider. Nothing in it can change a request or read a reply. */
44
+ /**
45
+ * Validates a provider definition and supplies its typed model helper.
46
+ *
47
+ * @remarks Defines a provider. Nothing in it can change a request or read a reply.
48
+ */
45
49
  export function defineProvider(definition) {
46
50
  const parsed = providerShape.safeParse(definition);
47
51
  if (!parsed.success || typeof definition.serves !== 'function')
@@ -7,89 +7,238 @@ import type { DecisionModelBinding, DecisionProfile, EmbeddingProfile, HostProfi
7
7
  import type { SchemaRegistry } from './schemas.js';
8
8
  /** Not shared by host profiles, which invoke tools without a model turn. */
9
9
  export type ProfileDefinitionBase = {
10
+ /**
11
+ * The name this profile is registered and looked up by, at most 64 characters; registering the
12
+ * same id again replaces it.
13
+ */
10
14
  id: Profile['id'];
15
+ /** The agent's display name and the system instruction it is given. */
11
16
  identity: ProfileIdentity;
17
+ /**
18
+ * The trained AI systems that turn input into results. Each entry binds a local name to an
19
+ * upstream model and its call settings.
20
+ *
21
+ * @catalog models.* One model: how to reach it and the settings sent with it.
22
+ */
12
23
  models: Record<ModelId, ModelBinding>;
24
+ /** Who holds the conversation a saved provider state continues. */
13
25
  providerContinuation?: import('../checkpoint.js').ProviderContinuationPolicy;
26
+ /** The model a turn gets when it doesn't pick one. */
14
27
  defaultModel?: ModelId;
28
+ /** Lets a turn name the model it runs on; a name the profile does not declare is refused. */
15
29
  allowModelSelect?: boolean;
30
+ /**
31
+ * The most model calls one turn may make while using tools, counted afresh for each rewrite; 1
32
+ * runs the tools asked for but never sends their results back. Live sessions ignore it.
33
+ */
16
34
  maxSteps?: number;
35
+ /** The shape of the reply, how it is checked, and how it streams. */
17
36
  outputs?: ProfileOutputsSpec;
37
+ /**
38
+ * Theorem checks what enters or leaves an agent’s context and generation against built-in or
39
+ * custom rules at each configured boundary.
40
+ */
18
41
  guardrails?: ProfileGuardrailsSpec;
42
+ /** Where this profile's traces go and what they keep. */
19
43
  observability?: ProfileObservabilitySpec;
44
+ /**
45
+ * This profile's own wording for error lines, notices, and notes to the model, by labels key.
46
+ *
47
+ * @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
48
+ */
20
49
  labels?: LabelOverrides;
21
50
  };
22
51
  /** What a host writes to define an embedding profile. */
23
52
  export type EmbeddingProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'outputs' | 'maxSteps'> & {
53
+ /**
54
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
55
+ * transcription, live, decision, embedding, or host.
56
+ */
24
57
  type: 'embedding';
58
+ /** The agent's display name and the system instruction it is given. */
25
59
  identity: Pick<ProfileIdentity, 'handle'>;
60
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
26
61
  inputs: EmbeddingProfile['inputs'];
27
62
  };
28
63
  /** What a host writes to define a text profile. */
29
64
  export type TextProfileDefinition = ProfileDefinitionBase & {
65
+ /**
66
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
67
+ * transcription, live, decision, embedding, or host.
68
+ */
30
69
  type: 'text';
70
+ /**
71
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
72
+ */
31
73
  tools: ProfileToolsSpec;
74
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
32
75
  inputs: ProfileInputsSpec;
76
+ /**
77
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
78
+ */
33
79
  turnBehaviour?: ProfileTurnBehaviourSpec;
34
80
  };
35
81
  /** What a host writes to define an image profile. */
36
82
  export type ImageProfileDefinition = ProfileDefinitionBase & {
83
+ /**
84
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
85
+ * transcription, live, decision, embedding, or host.
86
+ */
37
87
  type: 'image';
88
+ /**
89
+ * How the images this profile generates are shaped and made: size, format, quality and
90
+ * references. Each setting is sent only where the provider has it; one it lacks is refused or
91
+ * ignored, as that setting says.
92
+ */
38
93
  image: NonNullable<ImageProfile['image']>;
94
+ /**
95
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
96
+ */
39
97
  tools: ProfileToolsSpec;
98
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
40
99
  inputs: ImageInputsSpec;
100
+ /**
101
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
102
+ */
41
103
  turnBehaviour?: MediaTurnBehaviourSpec;
42
104
  };
43
105
  /** What a host writes to define a speech profile. */
44
106
  export type SpeechProfileDefinition = Omit<ProfileDefinitionBase, 'identity'> & {
107
+ /**
108
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
109
+ * transcription, live, decision, embedding, or host.
110
+ */
45
111
  type: 'speech';
112
+ /** The agent's display name and the system instruction it is given. */
46
113
  identity: SpeechProfile['identity'];
114
+ /**
115
+ * How the profile's speech sounds and is delivered: voice, style, speed and audio format. A turn
116
+ * may replace voice, style and speed for that turn.
117
+ */
47
118
  speech: NonNullable<SpeechProfile['speech']>;
119
+ /**
120
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
121
+ */
48
122
  turnBehaviour?: MediaTurnBehaviourSpec;
49
123
  };
50
124
  /** What a host writes to define a transcription profile. */
51
125
  export type TranscriptionProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'outputs' | 'maxSteps'> & {
126
+ /**
127
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
128
+ * transcription, live, decision, embedding, or host.
129
+ */
52
130
  type: 'transcription';
131
+ /** The agent's display name and the system instruction it is given. */
53
132
  identity: TranscriptionProfile['identity'];
133
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
54
134
  inputs: TranscriptionInputsSpec & {
55
- text?: false;
135
+ /** Whether a turn may send text. */ text?: false;
56
136
  };
57
137
  };
58
138
  /** What a host writes to define a live profile. */
59
139
  export type LiveProfileDefinition = Omit<ProfileDefinitionBase, 'maxSteps'> & {
140
+ /**
141
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
142
+ * transcription, live, decision, embedding, or host.
143
+ */
60
144
  type: 'live';
145
+ /**
146
+ * How a realtime voice and video session runs: what it accepts from the user, the voice it
147
+ * answers in, when it hears the user start and stop, and how it resumes and trims its context.
148
+ */
61
149
  live: NonNullable<LiveProfile['live']>;
150
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
62
151
  inputs?: LiveProfile['inputs'];
152
+ /**
153
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
154
+ */
63
155
  tools: LiveProfileToolsSpec;
64
- /** Inject gate only — resumption is `live.sessionResumption`. */
156
+ /**
157
+ * Whether a reply that stopped early can be continued, and whether a running turn can be steered.
158
+ *
159
+ * @remarks Inject gate only — resumption is `live.sessionResumption`.
160
+ */
65
161
  turnBehaviour?: Pick<ProfileTurnBehaviourSpec, 'allowSteering'>;
66
162
  };
67
163
  /** What a host writes to define a decision profile. */
68
164
  export type DecisionProfileDefinition = {
165
+ /**
166
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
167
+ * transcription, live, decision, embedding, or host.
168
+ */
69
169
  type: 'decision';
170
+ /**
171
+ * The name this profile is registered and looked up by, at most 64 characters; registering the
172
+ * same id again replaces it.
173
+ */
70
174
  id: Profile['id'];
175
+ /** The agent's display name and the system instruction it is given. */
71
176
  identity: Pick<ProfileIdentity, 'handle'>;
72
- /** Exactly one model. */
177
+ /**
178
+ * The trained AI systems that turn input into results. Each entry binds a local name to an
179
+ * upstream model and its call settings.
180
+ *
181
+ * @remarks Exactly one model.
182
+ * @catalog models.* One model: how to reach it and the settings sent with it.
183
+ */
73
184
  models: Record<ModelId, DecisionModelBinding>;
185
+ /** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
74
186
  inputs: DecisionProfile['inputs'];
187
+ /** Names the host decision this profile makes. */
75
188
  decision: DecisionProfile['decision'];
189
+ /**
190
+ * Theorem checks what enters or leaves an agent’s context and generation against built-in or
191
+ * custom rules at each configured boundary.
192
+ */
76
193
  guardrails?: DecisionGuardrailsSpec;
194
+ /** Where this profile's traces go and what they keep. */
77
195
  observability?: ProfileObservabilitySpec;
196
+ /**
197
+ * This profile's own wording for error lines, notices, and notes to the model, by labels key.
198
+ *
199
+ * @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
200
+ */
78
201
  labels?: LabelOverrides;
79
202
  };
80
203
  /** What a host writes to define a host profile, which runs tools and no model. */
81
204
  export type HostProfileDefinition = {
205
+ /**
206
+ * What kind of agent this is, and so what each call gives back: text, image, speech,
207
+ * transcription, live, decision, embedding, or host.
208
+ */
82
209
  type: 'host';
210
+ /**
211
+ * The name this profile is registered and looked up by, at most 64 characters; registering the
212
+ * same id again replaces it.
213
+ */
83
214
  id: Profile['id'];
215
+ /**
216
+ * The registered tools this profile may use, and how they load. Built-in tools are set per model.
217
+ */
84
218
  tools: HostProfileToolsSpec;
85
- /** Only the guards that fire on the `invokeTool` path. */
219
+ /**
220
+ * Theorem checks what enters or leaves an agent’s context and generation against built-in or
221
+ * custom rules at each configured boundary.
222
+ *
223
+ * @remarks Only the guards that fire on the `invokeTool` path.
224
+ */
86
225
  guardrails?: HostGuardrailsSpec;
226
+ /** Where this profile's traces go and what they keep. */
87
227
  observability?: ProfileObservabilitySpec;
228
+ /**
229
+ * This profile's own wording for error lines, notices, and notes to the model, by labels key.
230
+ *
231
+ * @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
232
+ */
88
233
  labels?: LabelOverrides;
89
234
  };
90
235
  /** Any profile definition, discriminated by `type`. */
91
236
  export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | DecisionProfileDefinition | TranscriptionProfileDefinition | EmbeddingProfileDefinition | HostProfileDefinition;
92
- /** Validate a definition and return the profile; throws on a malformed one. */
237
+ /**
238
+ * Checks a profile and returns it; a field the profile type cannot take is a config error.
239
+ *
240
+ * @remarks Validate a definition and return the profile; throws on a malformed one.
241
+ */
93
242
  declare function defineProfile(input: TextProfileDefinition): TextProfile;
94
243
  /** Validate an image definition and return the profile. */
95
244
  declare function defineProfile(input: ImageProfileDefinition): ImageProfile;
@@ -69,11 +69,7 @@ export type CompactionMeter = (typeof COMPACTION_METERS)[number];
69
69
  export declare const COMPACTION_TIMINGS: readonly ["before", "after"];
70
70
  /** One of {@linkcode COMPACTION_TIMINGS}. */
71
71
  export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
72
- /**
73
- * - `compacted`: a summary replaced the compacted messages.
74
- * - `deferred`: the compactor failed and the history still fits `maxTokens`, so it is kept whole.
75
- * - `dropped`: the compactor failed over `maxTokens`, so the compacted messages were dropped.
76
- */
72
+ /** What a compaction did. */
77
73
  export declare const COMPACTION_OUTCOMES: readonly ["compacted", "deferred", "dropped"];
78
74
  /** One of {@linkcode COMPACTION_OUTCOMES}. */
79
75
  export type CompactionOutcome = (typeof COMPACTION_OUTCOMES)[number];
@@ -210,8 +206,10 @@ export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
210
206
  /** Turns a key path into its catalog path, replacing host-chosen map keys with `*`. */
211
207
  export declare function catalogPathFor(keys: readonly string[]): string;
212
208
  /**
213
- * Adding a profile field? Add it here; scope it in `PROFILE_FIELD_SCOPE` if only some types
214
- * take it, and record it in `PROFILE_FIELD_PRESENCE` if it is required or its absence matters.
209
+ * Adding a profile field? Write its doc as JSDoc on the type, run `deno task field-docs`, and add
210
+ * it here with `field()`; scope it in `PROFILE_FIELD_SCOPE` if only some types take it, and record
211
+ * it in `PROFILE_FIELD_PRESENCE` if it is required or its absence matters. A map's entries
212
+ * (`models.*`) take their doc from a `@catalog <path> <text>` tag on the map's property.
215
213
  */
216
214
  export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
217
215
  /**