@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
@@ -24,45 +24,90 @@ declare const DETECT_ACTIONS: readonly ["ignore", "flag", "redact", "block"];
24
24
  type DetectAction = (typeof DETECT_ACTIONS)[number];
25
25
  /** The addresses `ungiven_images` or `ungiven_links` lets through beyond the ones the model was given. */
26
26
  interface UrlAllow {
27
- /** Hostnames let through whatever their URL, such as the host's own CDN. */
27
+ /**
28
+ * Hostnames whose images load whatever their URL, such as your own CDN.
29
+ *
30
+ * @catalog guardrails.detect.ungiven_links.allow.hosts Hostnames whose links pass whatever their
31
+ * URL; the hosts ungiven_images allows pass too.
32
+ *
33
+ * @remarks Hostnames let through whatever their URL, such as the host's own CDN.
34
+ */
28
35
  hosts?: readonly string[];
29
36
  /**
30
- * Whether a URL a tool returned counts as given. Default true. A tool result can offer the
31
- * model URLs to pick from, and the pick tells their server something; false closes that
37
+ * Whether a URL a tool returned counts as given. Off keeps only what the system prompt, the user,
38
+ * and history gave.
39
+ *
40
+ * @remarks Whether a URL a tool returned counts as given. Default true. A tool result can offer
41
+ * the model URLs to pick from, and the pick tells their server something; false closes that
32
42
  * channel, and keeps only what the system prompt, the user, and host history gave.
33
43
  */
34
44
  fromTools?: boolean;
35
45
  }
36
46
  /** The names `tool_leak` lets through. */
37
47
  interface NameAllow {
38
- /** Names of tools or parameters that are innocent in a reply, such as a tool called `search`. */
48
+ /**
49
+ * Names of tools or parameters that are not read for, such as a tool called search.
50
+ *
51
+ * @remarks Names of tools or parameters that are innocent in a reply, such as a tool called
52
+ * `search`.
53
+ */
39
54
  names?: readonly string[];
40
55
  }
41
56
  /** A detector's setting in full. */
42
57
  interface DetectorConfig {
43
- /** The action at every boundary. Left out, each boundary keeps its default. */
58
+ /**
59
+ * What a match of this detector does at every boundary it reads, unless `at` names that boundary.
60
+ *
61
+ * @remarks The action at every boundary. Left out, each boundary keeps its default.
62
+ */
44
63
  action?: DetectAction;
45
- /** An action for the boundaries it names, over `action` or the default. */
64
+ /**
65
+ * An action per boundary, over action or the default.
66
+ *
67
+ * @remarks An action for the boundaries it names, over `action` or the default.
68
+ */
46
69
  at?: Partial<Record<Boundary, DetectAction>>;
47
70
  /**
48
- * Whether Theorem's own patterns run. Default true. With `patterns` it gives the four choices:
49
- * both, only Theorem's, only the host's (`false` with patterns), or none (`false` without).
50
- * A detector that takes no patterns refuses it.
71
+ * Whether Theorem’s own patterns run. Off with no patterns of your own turns the detector off.
72
+ *
73
+ * @remarks Whether Theorem's own patterns run. Default true. With `patterns` it gives the four
74
+ * choices: both, only Theorem's, only the host's (`false` with patterns), or none (`false`
75
+ * without). A detector that takes no patterns refuses it.
51
76
  */
52
77
  theorem?: boolean;
53
- /** The host's own patterns, read on the text as written. A detector that takes no patterns refuses them. */
78
+ /**
79
+ * Your own patterns, each a name and a regular expression or a list of words. A match takes this
80
+ * detector’s action.
81
+ *
82
+ * @remarks The host's own patterns, read on the text as written. A detector that takes no
83
+ * patterns refuses them.
84
+ */
54
85
  patterns?: readonly HostPattern[];
55
- /** The table compiled for `patterns` (`compilePatterns`, `agents detect-compile`). Patterns need it. */
86
+ /**
87
+ * The table your patterns compile to, from compileDetect or `agents detect-compile`. Needed
88
+ * whenever patterns is set.
89
+ *
90
+ * @remarks The table compiled for `patterns` (`compilePatterns`, `agents detect-compile`).
91
+ * Patterns need it.
92
+ */
56
93
  compiled?: CompiledPatterns;
57
94
  /**
58
95
  * One line telling the model what to leave out, sent when this detector blocks a reply that is
59
- * then retried. Left out, the labels' `detect.hint.<detector>`. Only beside `patterns`: the
60
- * labels' hint describes Theorem's patterns, not the host's.
96
+ * then retried. Set it beside patterns of your own.
97
+ *
98
+ * @remarks One line telling the model what to leave out, sent when this detector blocks a reply
99
+ * that is then retried. Left out, the labels' `detect.hint.<detector>`. Only beside `patterns`:
100
+ * the labels' hint describes Theorem's patterns, not the host's.
61
101
  */
62
102
  hint?: string;
63
103
  /**
64
- * What the detector lets through: for `ungiven_images` and `ungiven_links` the addresses besides
65
- * the given ones, for `tool_leak` the names that are innocent. Any other detector refuses it.
104
+ * What passes besides the URLs the model was given this turn.
105
+ *
106
+ * @catalog guardrails.detect.tool_leak.allow The names that are innocent in a reply.
107
+ *
108
+ * @remarks What the detector lets through: for `ungiven_images` and `ungiven_links` the addresses
109
+ * besides the given ones, for `tool_leak` the names that are innocent. Any other detector refuses
110
+ * it.
66
111
  */
67
112
  allow?: UrlAllow | NameAllow;
68
113
  }
@@ -91,23 +136,48 @@ type HostFind = (text: string, context: {
91
136
  interface HostDetectorConfig {
92
137
  /** What an editor and the trace call it. */
93
138
  label: string;
94
- /** The action at every boundary. Left out, only the boundaries `at` names are read. */
139
+ /**
140
+ * What a match does, at every boundary.
141
+ *
142
+ * @remarks The action at every boundary. Left out, only the boundaries `at` names are read.
143
+ */
95
144
  action?: DetectAction;
96
- /** An action for the boundaries it names, over `action`. */
145
+ /**
146
+ * An action per boundary, over action.
147
+ *
148
+ * @remarks An action for the boundaries it names, over `action`.
149
+ */
97
150
  at?: Partial<Record<Boundary, DetectAction>>;
98
- /** Its patterns, read on the text as written. */
151
+ /**
152
+ * Its patterns, each a name and a regular expression or a list of words, read on the text as
153
+ * written.
154
+ *
155
+ * @remarks Its patterns, read on the text as written.
156
+ */
99
157
  patterns?: readonly HostPattern[];
100
- /** The table compiled for `patterns` (`compilePatterns`, `agents detect-compile`). Patterns need it. */
158
+ /**
159
+ * The table your patterns compile to, from compileDetect or `agents detect-compile`. Needed
160
+ * whenever patterns is set.
161
+ *
162
+ * @remarks The table compiled for `patterns` (`compilePatterns`, `agents detect-compile`).
163
+ * Patterns need it.
164
+ */
101
165
  compiled?: CompiledPatterns;
102
166
  /**
103
- * Its own reading. As a reply streams, a `find` reads the text held so far, and the last
167
+ * Its own reading, for what patterns cannot say: a function that returns where the matches start
168
+ * and end. It runs on every text crossing a boundary the detector reads, so it returns at once.
169
+ *
170
+ * @remarks Its own reading. As a reply streams, a `find` reads the text held so far, and the last
104
171
  * `HOST_FIND_HOLD` characters stay held (`HOST_FIND_HOLD_LIVE` in a Live reply): a match is
105
172
  * caught whole when it is no longer than that.
106
173
  */
107
174
  find?: HostFind;
108
175
  /**
109
176
  * One line telling the model what to leave out, sent when this detector blocks a reply that is
110
- * then retried. Left out, the labels' `detect.hint.own`, which names the label.
177
+ * then retried.
178
+ *
179
+ * @remarks One line telling the model what to leave out, sent when this detector blocks a reply
180
+ * that is then retried. Left out, the labels' `detect.hint.own`, which names the label.
111
181
  */
112
182
  hint?: string;
113
183
  }
@@ -6,13 +6,26 @@
6
6
  type HostPattern = {
7
7
  /** What a match is called in the trace. */
8
8
  name: string;
9
- /** The source of a regular expression. */
9
+ /**
10
+ * The source of a regular expression. A pattern takes this or words.
11
+ *
12
+ * @remarks The source of a regular expression.
13
+ */
10
14
  pattern: string;
11
- /** Any of `i`, `m`, `s`, and `u`. Every match is found, so `g` is implied; `y` is refused. */
15
+ /**
16
+ * Regular-expression flags, each a letter: i ignores case, m matches ^ and $ at each line, s
17
+ * lets . match a line break, u reads Unicode. Not g or y: every match is always found.
18
+ *
19
+ * @remarks Any of `i`, `m`, `s`, and `u`. Every match is found, so `g` is implied; `y` is
20
+ * refused.
21
+ */
12
22
  flags?: string;
13
23
  } | {
14
24
  /** What a match is called in the trace. */
15
25
  name: string;
26
+ /**
27
+ * Words to match whole, whatever their case. A space in one matches any run of whitespace.
28
+ */
16
29
  words: readonly string[];
17
30
  };
18
31
  /**
@@ -1,7 +1,7 @@
1
1
  /** Values that fill a label template's `{param}` placeholders. */
2
2
  export type LabelParams = Record<string, string | number>;
3
3
  /** Keys are stable API. */
4
- export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
4
+ export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.reply_cut_off", "repair.call_cut_off", "repair.call_cut_off_guidance", "repair.nothing_written", "repair.nothing_written_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
5
5
  /** One of {@linkcode LABEL_KEYS}. */
6
6
  export type LabelKey = (typeof LABEL_KEYS)[number];
7
7
  /**
@@ -28,9 +28,17 @@ export declare const LABEL_NOTES: Record<LabelKey, string>;
28
28
  export declare function labelPlaceholders(key: LabelKey): readonly string[];
29
29
  /** `owner` names where the overrides came from in the error. */
30
30
  export declare function validateLabelOverrides(entries: LabelOverrides, owner: string): void;
31
- /** Process-wide; a profile's own `labels` wins over these. */
31
+ /**
32
+ * Replaces status lines for every profile in the process; a profile's own labels wins.
33
+ *
34
+ * @remarks Process-wide; a profile's own `labels` wins over these.
35
+ */
32
36
  export declare function overrideLabels(entries: LabelOverrides): void;
33
- /** Remove every label override. */
37
+ /**
38
+ * Removes every replacement that overrideLabels made.
39
+ *
40
+ * @remarks Remove every label override.
41
+ */
34
42
  export declare function resetLabels(): void;
35
43
  /** The wording for a key, with a profile's override applied and the params filled in. */
36
44
  export declare function labelText(key: LabelKey, params?: LabelParams, profileLabels?: LabelOverrides): string;
@@ -1,6 +1,7 @@
1
1
  // invariant: "Host decides, Theorem runs": the kernel ships overridable defaults, never unreplaceable copy, so every
2
2
  // emit-site takes its string from here and `scripts/docs-truth/copy-lint.mjs` fails the build on prose elsewhere.
3
- import { TheoremError } from './theorem-error.js';
3
+ import { OPTION_DOCS } from '../kernel/field-docs.js';
4
+ import { ERROR_KINDS, TheoremError } from './theorem-error.js';
4
5
  /** Keys are stable API. */
5
6
  export const LABEL_KEYS = [
6
7
  'provider.decision_failed',
@@ -93,6 +94,11 @@ export const LABEL_KEYS = [
93
94
  'repair.default_guidance',
94
95
  'repair.items_guidance',
95
96
  'repair.cut_off_guidance',
97
+ 'repair.reply_cut_off',
98
+ 'repair.call_cut_off',
99
+ 'repair.call_cut_off_guidance',
100
+ 'repair.nothing_written',
101
+ 'repair.nothing_written_guidance',
96
102
  'repair.prompt_header',
97
103
  'repair.prompt_intro',
98
104
  'repair.prompt_instructions',
@@ -439,6 +445,11 @@ const DEFAULTS = {
439
445
  'repair.default_guidance': 'Revise the previous output so it satisfies the validator rejection. Preserve the intended user-facing substance unless the guidance says otherwise.',
440
446
  'repair.items_guidance': 'The previous output holds only the items that were rejected; the rest of your reply is kept. Return only these items, corrected, in the same order.',
441
447
  'repair.cut_off_guidance': 'Your answer was cut off before it ended. Give the whole answer again, written shorter so it fits. Keep what matters most.',
448
+ 'repair.reply_cut_off': 'The reply was cut off at the output limit before it ended.',
449
+ 'repair.call_cut_off': 'The call to {tool} was cut off at the output limit before its arguments ended.',
450
+ 'repair.call_cut_off_guidance': 'Your call to {tool} was cut off before its arguments ended. Call it again with arguments short enough to fit, or split the work into smaller calls.',
451
+ 'repair.nothing_written': 'The output limit was reached before any reply or tool call was written.',
452
+ 'repair.nothing_written_guidance': 'You reached the output limit before any reply or tool call came through. Spend less of the limit thinking, and keep any tool call short enough to fit, or split it into smaller calls.',
442
453
  'repair.prompt_header': '## OUTPUT REPAIR REQUEST',
443
454
  'repair.prompt_intro': 'The previous assistant output was rejected by a host validator and must be revised.',
444
455
  'repair.prompt_instructions': '1. Inspect the previous output and validator rejection.\n2. Apply the repair guidance without inventing unsupported facts.\n3. Return only the corrected assistant output required by the active profile.',
@@ -554,6 +565,18 @@ const DEFAULTS = {
554
565
  'tool.agent_failed': "Tool '{tool}' didn't get a reply from its agent",
555
566
  'tool.activity_failed': "Couldn't complete {tool}",
556
567
  };
568
+ /** What an error kind's label note adds to the kind's doc: by default, that it takes {tool}. */
569
+ const ERROR_NOTE_EXTRAS = {
570
+ conflict: 'HTTP 409. Takes {tool} when one step failed.',
571
+ not_found: 'HTTP 404. Takes {tool} when one step failed.',
572
+ busy: 'HTTP 503 or 529. Takes {tool} when one step failed.',
573
+ network: 'A tool that could not be reached shows tool.unreachable.',
574
+ };
575
+ /** Each `error.<kind>` label's note: the kind's doc, from the JSDoc on its `ERROR_KINDS` member. */
576
+ const ERROR_LABEL_NOTES = Object.fromEntries(ERROR_KINDS.map((kind) => [
577
+ `error.${kind}`,
578
+ `Shown to the user for this failure: ${OPTION_DOCS.ERROR_KINDS[kind]} ${ERROR_NOTE_EXTRAS[kind] ?? 'Takes {tool} when one step failed.'}`,
579
+ ]));
557
580
  /**
558
581
  * What each key is: when the kernel uses it, who reads it, and the placeholders it takes. For the
559
582
  * builders who replace the wording; the field catalog reads it for `labels.<key>`.
@@ -648,29 +671,15 @@ export const LABEL_NOTES = {
648
671
  'attachments.limits_unconfigured': 'Shown to the user who sends a file to an agent whose file limits are not set.',
649
672
  'quota.exhausted': 'Shown to the user who has used up the daily message cap. Takes {perDay}.',
650
673
  'quota.busy': 'Shown to the user who sends a message while their last one is still being answered (`quotaBusy`).',
651
- 'error.config': "Shown to the user when the turn fails because the agent's profile, a tool, or a schema is set up wrong. Takes {tool} when one step failed.",
652
- 'error.request': 'Shown to the user when the turn fails because the host called Theorem wrongly. Takes {tool} when one step failed.',
653
- 'error.conflict': 'Shown to the user when the call conflicts with something still in progress, such as a step that is not settled (HTTP 409). Takes {tool} when one step failed.',
654
- 'error.not_found': 'Shown to the user when something the call names is not there, such as a conversation that is no longer kept (HTTP 404). Takes {tool} when one step failed.',
655
- 'error.input': 'Shown to the user when they sent something the agent does not accept. Takes {tool} when one step failed.',
656
- 'error.action': 'Shown to the user when they asked for something the agent does not allow. Takes {tool} when one step failed.',
657
- 'error.auth': 'Shown to the user when a model key is missing or rejected, or its account cannot be billed. Takes {tool} when one step failed.',
658
- 'error.rate_limit': 'Shown to the user when the model provider reports too many requests, or a quota is used up. Takes {tool} when one step failed.',
659
- 'error.busy': 'Shown to the user when the model provider is up but too busy for the call (HTTP 503 or 529). Takes {tool} when one step failed.',
660
- 'error.unsupported': 'Shown to the user when the model or its route cannot serve the request. Takes {tool} when one step failed.',
661
- 'error.unavailable': 'Shown to the user when the model provider is down. Takes {tool} when one step failed.',
662
- 'error.bad_response': 'Shown to the user when the model provider answers with something that cannot be used. Takes {tool} when one step failed.',
663
- 'error.network': 'Shown to the user when the request never reached the model provider. A tool that could not be reached shows tool.unreachable.',
664
- 'error.timeout': 'Shown to the user when the model takes longer than the host allows. Takes {tool} when one step failed.',
665
- 'error.safety': 'Shown to the user when Theorem or the model provider holds the reply back. Takes {tool} when one step failed.',
666
- 'error.blocked': "Shown to the user when a guardrail or host policy stops one of the agent's steps. Takes {tool} when one step failed.",
667
- 'error.declined': "Shown to the user after they decline one of the agent's steps. Takes {tool} when one step failed.",
668
- 'error.failed': "Shown to the user when one of the agent's steps runs and fails. Takes {tool} when one step failed.",
669
- 'error.cancelled': 'Shown to the user when they or the host stop the turn. Takes {tool} when one step failed.',
670
- 'error.internal': 'Shown to the user when something inside Theorem breaks. Takes {tool} when one step failed.',
674
+ ...ERROR_LABEL_NOTES,
671
675
  'repair.default_guidance': "Sent to the model when a validator rejects its output and the host gives no guidance of its own; also the Repair guidance setting's default.",
672
676
  'repair.items_guidance': 'Sent to the model when an item rule rejects some items of a list in its structured reply and asks for those items alone to be rewritten.',
673
677
  'repair.cut_off_guidance': 'Sent to the model when its answer was cut off at the output limit and it is asked to give it again, shorter.',
678
+ 'repair.reply_cut_off': 'The validator rejection in the repair request when a text reply was cut off at the output limit.',
679
+ 'repair.call_cut_off': "The validator rejection in the repair request when a tool call's arguments were cut off at the output limit. Takes {tool}.",
680
+ 'repair.call_cut_off_guidance': "Sent to the model when a tool call's arguments were cut off at the output limit and it is asked to make the call again, shorter or split. Takes {tool}.",
681
+ 'repair.nothing_written': 'The validator rejection in the repair request when the output limit was reached before the model wrote a reply or a tool call.',
682
+ 'repair.nothing_written_guidance': 'Sent to the model when it reached the output limit before writing anything, asking it to think less and answer.',
674
683
  'repair.prompt_header': 'The heading that opens the repair request sent to the model after a validator or the egress check rejects its output.',
675
684
  'repair.prompt_intro': 'The first line of the repair request, saying why the model is asked to revise.',
676
685
  'repair.prompt_instructions': 'The numbered steps at the end of the repair request.',
@@ -830,6 +839,8 @@ const LABEL_PLACEHOLDERS = {
830
839
  'quota.exhausted': ['perDay'],
831
840
  'repair.history_heading': ['count'],
832
841
  'structured.answer_missing': TOOL,
842
+ 'repair.call_cut_off': TOOL,
843
+ 'repair.call_cut_off_guidance': TOOL,
833
844
  'compaction.tool_call': ['tool', 'arguments'],
834
845
  'compaction.tool_result': ['tool', 'result'],
835
846
  'compaction.tool_files': ['tool'],
@@ -910,7 +921,11 @@ export function validateLabelOverrides(entries, owner) {
910
921
  }
911
922
  }
912
923
  }
913
- /** Process-wide; a profile's own `labels` wins over these. */
924
+ /**
925
+ * Replaces status lines for every profile in the process; a profile's own labels wins.
926
+ *
927
+ * @remarks Process-wide; a profile's own `labels` wins over these.
928
+ */
914
929
  export function overrideLabels(entries) {
915
930
  validateLabelOverrides(entries, 'overrideLabels');
916
931
  for (const [key, template] of Object.entries(entries)) {
@@ -918,7 +933,11 @@ export function overrideLabels(entries) {
918
933
  overrides.set(key, template);
919
934
  }
920
935
  }
921
- /** Remove every label override. */
936
+ /**
937
+ * Removes every replacement that overrideLabels made.
938
+ *
939
+ * @remarks Remove every label override.
940
+ */
922
941
  export function resetLabels() {
923
942
  overrides.clear();
924
943
  }
@@ -7,11 +7,17 @@ declare function skipQuota(peer: string, req: Request): boolean;
7
7
  /** Resolves the client identity, preferring Cloudflare's header for local peers. */
8
8
  declare function clientIp(peer: string, req: Request): string;
9
9
  /**
10
- * Reserves one profile-and-client daily quota slot. The reservation stays busy
11
- * until `releaseSlot` is called, preventing concurrent turns from overspending.
10
+ * Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.
11
+ *
12
+ * @remarks Reserves one profile-and-client daily quota slot. The reservation stays busy until
13
+ * `releaseSlot` is called, preventing concurrent turns from overspending.
12
14
  */
13
15
  declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus;
14
- /** Releases an active quota reservation without decrementing its daily count. */
16
+ /**
17
+ * Frees the turn slot that takeSlot gave.
18
+ *
19
+ * @remarks Releases an active quota reservation without decrementing its daily count.
20
+ */
15
21
  declare function releaseSlot(profile: Profile, ip: string): void;
16
22
  /** `undefined` when the profile has no quota configured. */
17
23
  declare function quotaExhausted(profile: Profile): TheoremError | undefined;
@@ -32,8 +32,10 @@ function clientIp(peer, req) {
32
32
  return 'unknown';
33
33
  }
34
34
  /**
35
- * Reserves one profile-and-client daily quota slot. The reservation stays busy
36
- * until `releaseSlot` is called, preventing concurrent turns from overspending.
35
+ * Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.
36
+ *
37
+ * @remarks Reserves one profile-and-client daily quota slot. The reservation stays busy until
38
+ * `releaseSlot` is called, preventing concurrent turns from overspending.
37
39
  */
38
40
  function takeSlot(profile, ip, now) {
39
41
  const quota = resolveGuardrailPolicy(profile.guardrails).quota;
@@ -57,7 +59,11 @@ function takeSlot(profile, ip, now) {
57
59
  slot.count += 1;
58
60
  return 'ok';
59
61
  }
60
- /** Releases an active quota reservation without decrementing its daily count. */
62
+ /**
63
+ * Frees the turn slot that takeSlot gave.
64
+ *
65
+ * @remarks Releases an active quota reservation without decrementing its daily count.
66
+ */
61
67
  function releaseSlot(profile, ip) {
62
68
  const slot = slots.get(slotKey(profile.id, ip));
63
69
  if (slot) {
@@ -13,7 +13,11 @@ export interface TheoremErrorOptions extends ErrorOptions {
13
13
  /** User wording more specific than the kind's: one line, or one per problem found. */
14
14
  copy?: ErrorCopies;
15
15
  }
16
- /** An error that carries a `kind`, from which hosts choose a status and the user's wording. */
16
+ /**
17
+ * The error Theorem throws; its kind tells your host which status and wording to use.
18
+ *
19
+ * @remarks An error that carries a `kind`, from which hosts choose a status and the user's wording.
20
+ */
17
21
  export declare class TheoremError extends Error {
18
22
  readonly kind: ErrorKind;
19
23
  readonly copy?: ErrorCopies;
@@ -7,7 +7,7 @@
7
7
  export const ERROR_KINDS = [
8
8
  /** The profile, tool, or schema is set up wrong. */
9
9
  'config',
10
- /** The host called THEOREM wrongly. */
10
+ /** The host called Theorem wrongly. */
11
11
  'request',
12
12
  /** The call conflicts with the state it acts on, such as an operation that is still running or not settled. */
13
13
  'conflict',
@@ -33,7 +33,7 @@ export const ERROR_KINDS = [
33
33
  'network',
34
34
  /** The model took longer than the host allowed. */
35
35
  'timeout',
36
- /** THEOREM or the provider held the reply back. */
36
+ /** Theorem or the provider held the reply back. */
37
37
  'safety',
38
38
  /** A guardrail or host policy stopped one of the agent's steps. */
39
39
  'blocked',
@@ -43,10 +43,14 @@ export const ERROR_KINDS = [
43
43
  'failed',
44
44
  /** The user or host stopped the turn. */
45
45
  'cancelled',
46
- /** A THEOREM invariant broke. */
46
+ /** A Theorem invariant broke. */
47
47
  'internal',
48
48
  ];
49
- /** An error that carries a `kind`, from which hosts choose a status and the user's wording. */
49
+ /**
50
+ * The error Theorem throws; its kind tells your host which status and wording to use.
51
+ *
52
+ * @remarks An error that carries a `kind`, from which hosts choose a status and the user's wording.
53
+ */
50
54
  export class TheoremError extends Error {
51
55
  kind;
52
56
  copy;
@@ -29,14 +29,19 @@ export type BlockedReplyOnBlock = (typeof BLOCKED_REPLY_ON_BLOCK)[number];
29
29
  /** What happens once a detector blocks a reply. */
30
30
  export interface BlockedReplySpec {
31
31
  /**
32
- * `retry` (the default) tells the model what blocked the reply and has it write another;
33
- * `refuse` sends the user the labels' `egress.refusal` in its place, or ends the part
34
- * they already have with `egress.refusal_cut`.
32
+ * Whether the model gets to rewrite a reply a guardrail blocked, or the user gets a refusal in
33
+ * its place.
34
+ *
35
+ * @remarks `retry` (the default) tells the model what blocked the reply and has it write another;
36
+ * `refuse` sends the user the labels' `egress.refusal` in its place, or ends the part they
37
+ * already have with `egress.refusal_cut`.
35
38
  */
36
39
  onBlock?: BlockedReplyOnBlock;
37
40
  /**
38
- * Under `retry`, how many times the model may rewrite a blocked reply (default 1). Once they
39
- * are spent the reply is withheld and the turn ends in a `safety` error.
41
+ * How many times the model may rewrite a blocked reply. Live ignores it.
42
+ *
43
+ * @remarks Under `retry`, how many times the model may rewrite a blocked reply (default 1). Once
44
+ * they are spent the reply is withheld and the turn ends in a `safety` error.
40
45
  */
41
46
  maxRetries?: number;
42
47
  }
@@ -126,11 +131,20 @@ export type DestinationGate = (typeof DESTINATION_GATES)[number];
126
131
  */
127
132
  export interface TaintGuardrailSpec {
128
133
  /**
129
- * Stated as a capability threshold rather than a list of tool `access` values so
130
- * the guardrail vocabulary stays independent of the tool registry; the kernel
131
- * maps a tool's declared access onto it.
134
+ * Which tool calls are refused, by each tool's access, once the turn has read a remote tool's
135
+ * result.
136
+ *
137
+ * @remarks Stated as a capability threshold rather than a list of tool `access` values so the
138
+ * guardrail vocabulary stays independent of the tool registry; the kernel maps a tool's declared
139
+ * access onto it.
132
140
  */
133
141
  afterRemoteRead?: TaintGate;
142
+ /**
143
+ * What happens to a tool call, read-only ones too, that sends to an email address, a link's host
144
+ * or a bank account number (IBAN) that only the running text of a remote tool's result named. One
145
+ * the user, the system prompt, or a local tool gave passes, and so does one that is a whole field
146
+ * of the result.
147
+ */
134
148
  remoteDestination?: DestinationGate;
135
149
  }
136
150
  /** Facts a check may read. Deliberately excludes the full profile. */
@@ -178,35 +192,67 @@ export interface OutboundPayload {
178
192
  }
179
193
  /** Which hosts and networks a tool's requests may reach. */
180
194
  export interface NetworkGuardrailSpec {
181
- /** Allows localhost, loopback, and private subnets (local dev and testing). Default false. */
195
+ /**
196
+ * Lets tools reach localhost and private network addresses, for local development.
197
+ *
198
+ * @remarks Allows localhost, loopback, and private subnets (local dev and testing). Default
199
+ * false.
200
+ */
182
201
  allowPrivateNetworks?: boolean;
183
- /** Hostnames or IP addresses permitted regardless of private subnet status. */
202
+ /**
203
+ * Hostnames tools may reach even when they resolve to a private address; public hosts don't need
204
+ * listing. Names are resolved only when the host passes resolveHost.
205
+ *
206
+ * @remarks Hostnames or IP addresses permitted regardless of private subnet status.
207
+ */
184
208
  allowedHosts?: string[];
185
209
  /**
186
- * Allowed URL schemes. Defaults to `['https']`, or `['http', 'https']` when
210
+ * The URL schemes tools may use.
211
+ *
212
+ * @remarks Allowed URL schemes. Defaults to `['https']`, or `['http', 'https']` when
187
213
  * `allowPrivateNetworks` is set.
188
214
  */
189
215
  allowedSchemes?: string[];
190
216
  }
191
217
  /** Optional daily turn quota consumed by host HTTP middleware. */
192
218
  export interface QuotaGuardrailSpec {
219
+ /**
220
+ * Turns each client IP may run on this profile per UTC day, one at a time; counts live in the
221
+ * process, and a loopback caller is not counted.
222
+ */
193
223
  perDay: number;
194
224
  }
195
225
  /** The guardrails a profile turns on, each with its own settings. */
196
226
  export interface ProfileGuardrailsSpec {
197
- /** Omitted means quota enforcement is not configured. */
227
+ /**
228
+ * A daily turn limit. Your server enforces it with takeSlot.
229
+ *
230
+ * @remarks Omitted means quota enforcement is not configured.
231
+ */
198
232
  quota?: QuotaGuardrailSpec;
199
233
  /**
200
- * What the kernel does when a detector finds a match, per boundary: one action
201
- * for everything, or a rule for the detectors it names. Anything left out keeps
202
- * its default (`DETECT_DEFAULTS`). A canary is bound into the system prompt
203
- * while `canary_leak` is above `ignore` somewhere; the note that binds it is
204
- * the labels' `canary.bind_note` (the profile's `labels` may replace it).
234
+ * What a guardrail does when a detector matches. One action covers every detector; an object sets
235
+ * each detector (or one of your own) apart. Absent: each detector keeps its default action.
236
+ *
237
+ * @remarks What the kernel does when a detector finds a match, per boundary: one action for
238
+ * everything, or a rule for the detectors it names. Anything left out keeps its default
239
+ * (`DETECT_DEFAULTS`). A canary is bound into the system prompt while `canary_leak` is above
240
+ * `ignore` somewhere; the note that binds it is the labels' `canary.bind_note` (the profile's
241
+ * `labels` may replace it).
242
+ *
243
+ * @catalog guardrails.detect.* Your own detector, keyed with a dot: acme.codenames. No default action.
205
244
  */
206
245
  detect?: DetectSpec;
207
- /** What happens once a reply is blocked. Left out, the model rewrites it once. */
246
+ /**
247
+ * How a reply a guardrail blocked is handled: the model rewrites it, or the user gets a refusal,
248
+ * and how many rewrites it gets.
249
+ *
250
+ * @remarks What happens once a reply is blocked. Left out, the model rewrites it once.
251
+ */
208
252
  blockedReply?: BlockedReplySpec;
253
+ /** Addresses HTTP and MCP tools may reach. */
209
254
  network?: NetworkGuardrailSpec;
255
+ /** Tool limits after a remote read. */
210
256
  taint?: TaintGuardrailSpec;
211
257
  }
212
258
  /** Pre-dispatch policy for structured state leaving a decision profile. */
@@ -229,7 +275,9 @@ export type DecisionDisclosureEnforcer = (state: unknown, context: {
229
275
  * decision registry rejects every inherited field as inert in this release.
230
276
  */
231
277
  export interface DecisionGuardrailsSpec extends Partial<ProfileGuardrailsSpec> {
278
+ /** Your check on the state before a decision sends it to the model. */
232
279
  disclosure?: {
280
+ /** Your function that allows or blocks the state before it is sent. */
233
281
  enforce: DecisionDisclosureEnforcer;
234
282
  };
235
283
  }