@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/guardrails/rules.js

@@ -0,0 +1,54 @@
+/**
+ * Every rule id Theorem's own guardrails report, in one place. The trace
+ * catalog describes each one, and its description map is keyed by
+ * {@link GuardrailRule}, so a new id fails typecheck until it is described.
+ * A host's egress `enforce` hook may report ids of its own; those are not here.
+ *
+ * @module
+ */
+/** Injection phrasing or sensitive data stripped from text entering the turn. */
+export const SANITIZE_RULES = {
+    injection: 'sanitize.injection',
+    sensitive: 'sanitize.sensitive',
+};
+/** What the bundled egress policy finds in the model's outbound text. */
+export const EGRESS_RULES = {
+    canary: 'egress.canary-leak',
+    /** The reply repeats the system prompt (`guardrails.promptEcho`). */
+    promptEcho: 'egress.prompt-echo', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /**
+     * A provider-side built-in tool carried the canary or the system prompt. It
+     * ran before Theorem saw it: the data already left, so this is an incident.
+     */
+    providerToolLeak: 'egress.provider-tool-leak', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    sensitive: 'egress.sensitive-echo',
+    boundary: 'egress.system-boundary',
+    injection: 'egress.injection-echo', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /** An image loads a URL the model was not given, from a host not allowed. */
+    image: 'egress.image-exfil', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /** A link goes to a URL the model was not given, on a host not allowed. */
+    link: 'egress.link-exfil', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /** Payload could not be rendered for inspection — released output is unverified. */
+    unscannable: 'egress.unscannable', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    enforcerError: 'egress.enforcer-error', // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    /** The progressive gate stopped the stream on a host verdict that named no rule. */
+    blocked: 'egress.blocked',
+};
+/** Remote tool content behaving like an instruction to the agent. */
+export const DIRECTIVE_RULES = {
+    toolName: 'tool_result.names-callable-tool',
+    imperative: 'tool_result.imperative',
+    authority: 'tool_result.authority-claim',
+};
+/** The tool boundary: results and failures redacted, and calls flagged or blocked. */
+export const TOOL_RULES = {
+    resultRedacted: 'tool_result.redacted',
+    failureRedacted: 'tool_failure.redacted',
+    sensitiveArgument: 'tool_call.sensitive-argument',
+    taintedTurn: 'tool_call.tainted-turn',
+    steeredTurn: 'tool_call.steered-turn',
+};
+/** A tool's network target refused before any request was made. */
+export const NETWORK_RULES = {
+    blocked: 'network.blocked',
+};

package/esm/src/guardrails/sanitize.d.ts

@@ -0,0 +1,23 @@
+import type { NormalizedTurnRequest, Profile, TurnEvent, TurnRequest } from '../kernel/types.js';
+import { type DetectionOptions } from './policy.js';
+import type { GuardrailHit, TrustLevel } from './types.js';
+declare function detectText(text: string, options?: Partial<DetectionOptions>): {
+    text: string;
+    hits: GuardrailHit[];
+};
+declare function sanitizeText(text: string, options?: Partial<DetectionOptions>): string;
+declare function redactSensitiveOnly(text: string): string;
+declare function sanitizeProjectId(id: string | undefined): string | undefined;
+/**
+ * Exported because every path that injects messages into a turn needs it — turn
+ * history, and host steer injects mid-turn. A second copy would drift.
+ */
+declare function sanitizeHistory(history: import('../kernel/types.js').TurnHistoryMessage[], options: DetectionOptions, hits?: GuardrailHit[]): import('../kernel/types.js').TurnHistoryMessage[];
+declare function detectionForProfile(profile: Profile, trust: TrustLevel): DetectionOptions;
+declare function sanitizeTurnRequest(req: TurnRequest, profile: Profile): NormalizedTurnRequest;
+/** Attachments and voice are validated but emit no guardrail events. */
+declare function sanitizeTurnRequestWithEvents(req: TurnRequest, profile: Profile): {
+    request: NormalizedTurnRequest;
+    events: TurnEvent[];
+};
+export { detectionForProfile, detectText, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };

package/esm/src/guardrails/sanitize.js

@@ -0,0 +1,184 @@
+import { sanitizeTurnBlobs } from '../kernel/registry/attachments.js';
+import { mapSystemPrompt } from '../kernel/system-parts.js';
+import { applySpans } from '../observability/spans.js';
+import { guardrailFromHits } from './events.js';
+import { hitFromSpan } from './hits.js';
+import { injectionSpans } from './injection.js';
+import { detectionForTrust, resolveGuardrailPolicy } from './policy.js';
+import { SANITIZE_RULES } from './rules.js';
+import { anySensitive, resolveSensitive, sensitiveSpans } from './sensitive.js';
+function detectText(text, options) {
+    const sanitizeInput = options?.sanitizeInput ?? true;
+    const groups = resolveSensitive(options?.redactSensitive);
+    if (!sanitizeInput && !anySensitive(groups)) {
+        return { text, hits: [] };
+    }
+    const spans = [...(sanitizeInput ? injectionSpans(text) : []), ...sensitiveSpans(text, groups)];
+    const hits = spans.map((span) => hitFromSpan(text, span, span.kind === 'injection' ? SANITIZE_RULES.injection : SANITIZE_RULES.sensitive, 'high'));
+    return { text: applySpans(text, spans), hits };
+}
+function sanitizeText(text, options) {
+    return detectText(text, options).text;
+}
+function redactSensitiveOnly(text) {
+    return detectText(text, { sanitizeInput: false, redactSensitive: true }).text;
+}
+function appendHits(into, hits) {
+    for (const hit of hits) {
+        into.push(hit);
+    }
+}
+function sanitizeSlots(slots, options, hits) {
+    if (!slots) {
+        return slots;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(slots)) {
+        const detected = detectText(value, options);
+        appendHits(hits, detected.hits);
+        out[key] = detected.text;
+    }
+    return out;
+}
+const PROJECT_ID_OK = /^[A-Za-z0-9._-]+$/;
+function sanitizeProjectId(id) {
+    const trimmed = id?.trim();
+    return trimmed && PROJECT_ID_OK.test(trimmed) ? trimmed : undefined;
+}
+function sanitizeRepair(repair, options, hits) {
+    if (!repair) {
+        return repair;
+    }
+    const previous = detectText(repair.previousOutput, options);
+    const rejection = detectText(repair.rejection, options);
+    appendHits(hits, previous.hits);
+    appendHits(hits, rejection.hits);
+    let guidance = repair.guidance;
+    if (guidance) {
+        const detected = detectText(guidance, options);
+        appendHits(hits, detected.hits);
+        guidance = detected.text;
+    }
+    return {
+        previousOutput: previous.text,
+        rejection: rejection.text,
+        ...(guidance ? { guidance } : {}),
+    };
+}
+/**
+ * Exported because every path that injects messages into a turn needs it — turn
+ * history, and host steer injects mid-turn. A second copy would drift.
+ */
+function sanitizeHistory(history, options, hits = []) {
+    return history.map((m) => {
+        let content = m.content;
+        if (content !== undefined) {
+            const detected = detectText(content, options);
+            appendHits(hits, detected.hits);
+            content = detected.text;
+        }
+        let parts = m.parts;
+        if (parts) {
+            parts = parts.map((p) => {
+                if (p.type !== 'text') {
+                    return p;
+                }
+                const detected = detectText(p.text, options);
+                appendHits(hits, detected.hits);
+                return { ...p, text: detected.text };
+            });
+        }
+        return {
+            role: m.role,
+            ...(content !== undefined ? { content } : {}),
+            ...(parts ? { parts } : {}),
+            ...(m.tool_calls ? { tool_calls: m.tool_calls } : {}),
+            ...(m.tool_call_id ? { tool_call_id: m.tool_call_id } : {}),
+            ...(m.name ? { name: m.name } : {}),
+            ...(m.metadata ? { metadata: m.metadata } : {}),
+        };
+    });
+}
+function detectionForProfile(profile, trust) {
+    return detectionForTrust(resolveGuardrailPolicy(profile.guardrails), trust);
+}
+function pushStageEvent(events, stage, trust, hits) {
+    const event = guardrailFromHits(stage, trust, hits, 'redact');
+    if (event) {
+        events.push(event);
+    }
+}
+/**
+ * `req.system` is host-assembled per turn — it interpolates retrieval and user
+ * data, so it is treated as `assembled`, not trusted. `identity.system` never
+ * reaches this path and stays verbatim.
+ */
+function sanitizeTurnRequestText(req, profile) {
+    const untrusted = detectionForProfile(profile, 'untrusted');
+    const assembled = detectionForProfile(profile, 'assembled');
+    const input = req.input ?? {};
+    const events = [];
+    const inputHits = [];
+    const historyHits = [];
+    const systemHits = [];
+    const { text: rawText } = input;
+    let text = rawText;
+    if (rawText !== undefined) {
+        const detected = detectText(rawText, untrusted);
+        appendHits(inputHits, detected.hits);
+        text = detected.text;
+    }
+    const system = req.system === undefined
+        ? undefined
+        : mapSystemPrompt(req.system, 'TurnRequest.system', (part) => {
+            const detected = detectText(part, assembled);
+            appendHits(systemHits, detected.hits);
+            return detected.text;
+        });
+    const slots = sanitizeSlots(input.slots, untrusted, inputHits);
+    const repair = sanitizeRepair(input.repair, untrusted, inputHits);
+    const history = input.history
+        ? sanitizeHistory(input.history, untrusted, historyHits)
+        : undefined;
+    pushStageEvent(events, 'input', 'untrusted', inputHits);
+    pushStageEvent(events, 'history', 'untrusted', historyHits);
+    pushStageEvent(events, 'system', 'assembled', systemHits);
+    return {
+        request: {
+            ...req,
+            system,
+            projectId: sanitizeProjectId(req.projectId),
+            input: {
+                ...input,
+                text,
+                slots,
+                repair,
+                history,
+            },
+        },
+        events,
+    };
+}
+function sanitizeTurnRequest(req, profile) {
+    return sanitizeTurnRequestWithEvents(req, profile).request;
+}
+/** Attachments and voice are validated but emit no guardrail events. */
+function sanitizeTurnRequestWithEvents(req, profile) {
+    const { request: textSafe, events } = sanitizeTurnRequestText(req, profile);
+    const input = textSafe.input ?? {};
+    const { attachments, voice } = input.attachments?.length || input.voice?.length
+        ? sanitizeTurnBlobs(profile, input.attachments, input.voice)
+        : input;
+    return {
+        request: {
+            ...textSafe,
+            input: {
+                ...input,
+                attachments,
+                voice,
+            },
+        },
+        events,
+    };
+}
+export { detectionForProfile, detectText, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, };

package/esm/src/guardrails/sensitive.d.ts

@@ -0,0 +1,29 @@
+import { type RedactSpan } from '../observability/spans.js';
+declare const CARD_CANDIDATE: RegExp;
+/**
+ * The families of sensitive data, each switched on its own: a profile can
+ * redact credentials and card numbers but leave network addresses alone.
+ */
+declare const SENSITIVE_GROUPS: readonly ["ids", "financial", "network", "credentials"];
+type SensitiveGroup = (typeof SENSITIVE_GROUPS)[number];
+/** Per group, whether it runs. A group left out keeps its default. */
+type SensitiveSwitches = Partial<Record<SensitiveGroup, boolean>>;
+/** `true` runs every group, `false` none; an object switches the groups it names. */
+type SensitiveSelection = boolean | SensitiveSwitches;
+/** Every group's switch, defaults applied. */
+type SensitiveGroups = Readonly<Record<SensitiveGroup, boolean>>;
+/** Every pattern, with its group. */
+declare const SENSITIVE_PATTERNS: readonly {
+    group: SensitiveGroup;
+    pattern: RegExp;
+}[];
+/** `selection` with the groups it leaves out taken from `defaults`. */
+declare function resolveSensitive(selection: SensitiveSelection | undefined, defaults?: SensitiveGroups): SensitiveGroups;
+/** Whether any group runs. */
+declare function anySensitive(groups: SensitiveGroups): boolean;
+/** A card-number candidate that is a card: 13–19 digits passing the Luhn check. */
+declare function cardHit(blob: string): boolean;
+/** Sensitive-data spans in `text`, from the groups `selection` runs (every group by default). */
+declare function sensitiveSpans(text: string, selection?: SensitiveSelection): RedactSpan[];
+export type { SensitiveGroup, SensitiveGroups, SensitiveSelection, SensitiveSwitches };
+export { anySensitive, CARD_CANDIDATE, cardHit, resolveSensitive, SENSITIVE_GROUPS, SENSITIVE_PATTERNS, sensitiveSpans, };

package/esm/src/guardrails/sensitive.js

@@ -0,0 +1,113 @@
+import { blobAt, spansFromPatterns } from '../observability/spans.js';
+const SSN = /\b\d{3}-\d{2}-\d{4}\b/g;
+const SSN_CONTEXTUAL = /(?:SSN|social\s*security(?:\s*number)?)[:\s]+(?:\d[-\s]*){9}/gi;
+const ITIN = /\b9\d{2}-\d{2}-\d{4}\b/g;
+const EIN = /\b\d{2}-\d{7}\b/g;
+const IBAN = /\b[A-Z]{2}\d{2}[A-Z0-9]{13,30}\b/g;
+const IPV4 = /\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b/g;
+const IPV6 = /\b(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}\b/gi;
+const AWS_ACCESS = /\bAKIA[0-9A-Z]{16,20}\b/g;
+const GOOGLE_API = /\bAIza[0-9A-Za-z_-]{35}\b/g;
+const OPENAI_KEY = /\bsk-\s*[A-Za-z0-9]{20,}\b/g;
+const ANTHROPIC_KEY = /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g;
+const OPENROUTER_KEY = /\bsk-or-[A-Za-z0-9_-]{20,}\b/g;
+const GITHUB_PAT = /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g;
+const GITHUB_TOKEN = /\bghp_[A-Za-z0-9]{36}\b/g;
+const SLACK_TOKEN = /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g;
+const BEARER = /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi;
+/** Bounded payload so PEM redaction cannot ReDoS on repeated BEGIN markers. */
+const PEM_KEY = /-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]{0,16384}?-----END (?:RSA )?PRIVATE KEY-----/g;
+const CARD_CANDIDATE = /\b(?:\d[\s.-]*?){13,19}\b/g;
+/**
+ * The families of sensitive data, each switched on its own: a profile can
+ * redact credentials and card numbers but leave network addresses alone.
+ */
+const SENSITIVE_GROUPS = ['ids', 'financial', 'network', 'credentials'];
+/** The patterns each group matches. Card numbers are financial too, found by `cardSpans`. */
+const GROUP_PATTERNS = {
+    ids: [SSN, SSN_CONTEXTUAL, ITIN, EIN],
+    financial: [IBAN],
+    network: [IPV4, IPV6],
+    credentials: [
+        AWS_ACCESS,
+        GOOGLE_API,
+        OPENAI_KEY,
+        ANTHROPIC_KEY,
+        OPENROUTER_KEY,
+        GITHUB_PAT,
+        GITHUB_TOKEN,
+        SLACK_TOKEN,
+        BEARER,
+        PEM_KEY,
+    ],
+};
+/** Every pattern, with its group. */
+const SENSITIVE_PATTERNS = SENSITIVE_GROUPS.flatMap((group) => GROUP_PATTERNS[group].map((pattern) => ({ group, pattern })));
+const ALL_GROUPS = {
+    ids: true,
+    financial: true,
+    network: true,
+    credentials: true,
+};
+/** `selection` with the groups it leaves out taken from `defaults`. */
+function resolveSensitive(selection, defaults = ALL_GROUPS) {
+    if (selection === undefined)
+        return defaults;
+    if (typeof selection === 'boolean') {
+        return { ids: selection, financial: selection, network: selection, credentials: selection };
+    }
+    return { ...defaults, ...selection };
+}
+/** Whether any group runs. */
+function anySensitive(groups) {
+    return SENSITIVE_GROUPS.some((group) => groups[group]);
+}
+const LUHN_DOUBLE = 2;
+const LUHN_NINE = 9;
+const LUHN_TEN = 10;
+const CARD_MIN_DIGITS = 13;
+const CARD_MAX_DIGITS = 19;
+function luhnOk(digits) {
+    let sum = 0;
+    let doubleIt = false;
+    for (let i = digits.length - 1; i >= 0; i -= 1) {
+        const ch = digits[i];
+        if (ch === undefined) {
+            return false;
+        }
+        let n = Number(ch);
+        if (doubleIt) {
+            n *= LUHN_DOUBLE;
+            if (n > LUHN_NINE) {
+                n -= LUHN_NINE;
+            }
+        }
+        sum += n;
+        doubleIt = !doubleIt;
+    }
+    return sum % LUHN_TEN === 0;
+}
+/** A card-number candidate that is a card: 13–19 digits passing the Luhn check. */
+function cardHit(blob) {
+    const digits = blob.replaceAll(/[^\d]/g, '');
+    const inRange = digits.length >= CARD_MIN_DIGITS && digits.length <= CARD_MAX_DIGITS;
+    return inRange && luhnOk(digits);
+}
+function cardSpans(text) {
+    const spans = [];
+    for (const match of text.matchAll(CARD_CANDIDATE)) {
+        const found = blobAt(match);
+        if (found && cardHit(found.blob)) {
+            spans.push({ start: found.index, end: found.index + found.blob.length, kind: 'sensitive' });
+        }
+    }
+    return spans;
+}
+/** Sensitive-data spans in `text`, from the groups `selection` runs (every group by default). */
+function sensitiveSpans(text, selection = true) {
+    const groups = resolveSensitive(selection);
+    const patterns = SENSITIVE_GROUPS.flatMap((group) => groups[group] ? GROUP_PATTERNS[group] : []);
+    const spans = spansFromPatterns(text, patterns, 'sensitive');
+    return groups.financial ? [...spans, ...cardSpans(text)] : spans;
+}
+export { anySensitive, CARD_CANDIDATE, cardHit, resolveSensitive, SENSITIVE_GROUPS, SENSITIVE_PATTERNS, sensitiveSpans, };

package/esm/src/guardrails/serialize.d.ts

@@ -0,0 +1,14 @@
+declare const CIRCULAR = "[circular]";
+export interface ScanText {
+    text: string;
+    /** True when the payload could not be rendered and was not inspected. */
+    unscannable: boolean;
+}
+/**
+ * A guardrail must never be the thing that throws: cycles and bigints still get inspected, and
+ * only a payload that defeats that (a throwing `toJSON`) comes back `unscannable` so the caller can fail closed.
+ */
+declare function textForScan(value: unknown): ScanText;
+/** Discards `unscannable`: only for callers to whom an unrenderable payload is the same as no match. */
+declare function scanTextOf(value: unknown): string;
+export { CIRCULAR, scanTextOf, textForScan };

package/esm/src/guardrails/serialize.js

@@ -0,0 +1,37 @@
+const CIRCULAR = '[circular]';
+/**
+ * A guardrail must never be the thing that throws: cycles and bigints still get inspected, and
+ * only a payload that defeats that (a throwing `toJSON`) comes back `unscannable` so the caller can fail closed.
+ */
+function textForScan(value) {
+    if (value === undefined) {
+        return { text: '', unscannable: false };
+    }
+    if (typeof value === 'string') {
+        return { text: value, unscannable: false };
+    }
+    const seen = new WeakSet();
+    try {
+        const json = JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'bigint') {
+                return val.toString();
+            }
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val)) {
+                    return CIRCULAR;
+                }
+                seen.add(val);
+            }
+            return val;
+        });
+        return { text: json ?? '', unscannable: false };
+    }
+    catch {
+        return { text: '', unscannable: true };
+    }
+}
+/** Discards `unscannable`: only for callers to whom an unrenderable payload is the same as no match. */
+function scanTextOf(value) {
+    return textForScan(value).text;
+}
+export { CIRCULAR, scanTextOf, textForScan };

package/esm/src/guardrails/testing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Adversarial corpus, fuzz runners and live attack builders, kept off the production guardrails entry.
+ *
+ * @module
+ */
+/** lexicon-exempt-file: adversarial harness helpers — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+export type { CanaryEgressAttack, CanaryEgressCatalogEntry, InboundFuzzPayload, InboundFuzzResult, LiveAttack, } from './corpus/mod.js';
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, FUZZ_SYSTEM, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';

package/esm/src/guardrails/testing.js

@@ -0,0 +1,8 @@
+/**
+ * Adversarial corpus, fuzz runners and live attack builders, kept off the production guardrails entry.
+ *
+ * @module
+ */
+/** lexicon-exempt-file: adversarial harness helpers — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, FUZZ_SYSTEM, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';

package/esm/src/guardrails/theorem-error.d.ts

@@ -0,0 +1,18 @@
+import type { ErrorCopies, ErrorCopy } from './event-schemas.js';
+export type { ErrorCopies, ErrorCopy };
+/**
+ * What kind of failure happened, decided where it happens. Both worlds read it:
+ * the builder in code and traces (`errorKind`, `error.type`), the user through
+ * the kind's wording (`error.<kind>` in the lexicon).
+ */
+export declare const ERROR_KINDS: readonly ["config", "request", "input", "action", "auth", "rate_limit", "unsupported", "unavailable", "bad_response", "network", "timeout", "safety", "blocked", "declined", "failed", "cancelled", "internal"];
+export type ErrorKind = (typeof ERROR_KINDS)[number];
+export interface TheoremErrorOptions extends ErrorOptions {
+    /** User wording more specific than the kind's: one line, or one per problem found. */
+    copy?: ErrorCopies;
+}
+export declare class TheoremError extends Error {
+    readonly kind: ErrorKind;
+    readonly copy?: ErrorCopies;
+    constructor(kind: ErrorKind, message: string, options?: TheoremErrorOptions);
+}

package/esm/src/guardrails/theorem-error.js

@@ -0,0 +1,53 @@
+// Its own module so `lexicon.ts` can throw it without importing `error.ts`, which reads the lexicon.
+/**
+ * What kind of failure happened, decided where it happens. Both worlds read it:
+ * the builder in code and traces (`errorKind`, `error.type`), the user through
+ * the kind's wording (`error.<kind>` in the lexicon).
+ */
+export const ERROR_KINDS = [
+    /** The profile, tool, or schema is set up wrong. */
+    'config',
+    /** The host called THEOREM wrongly. */
+    'request',
+    /** The user sent input the profile does not accept. */
+    'input',
+    /** The user asked for something the profile does not allow. */
+    'action',
+    /** A missing or rejected credential, or an account that cannot be billed. */
+    'auth',
+    /** Too many requests, or a quota used up. */
+    'rate_limit',
+    /** The model or route cannot serve this request. */
+    'unsupported',
+    /** The provider is down or overloaded. */
+    'unavailable',
+    /** The provider answered with something that cannot be used. */
+    'bad_response',
+    /** The request never reached the provider. */
+    'network',
+    /** The model took longer than the host allowed. */
+    'timeout',
+    /** THEOREM or the provider held the reply back. */
+    'safety',
+    /** A guardrail or host policy stopped one of the agent's steps. */
+    'blocked',
+    /** The user declined one of the agent's steps. */
+    'declined',
+    /** One of the agent's steps ran and failed. */
+    'failed',
+    /** The user or host stopped the turn. */
+    'cancelled',
+    /** A THEOREM invariant broke. */
+    'internal',
+];
+export class TheoremError extends Error {
+    kind;
+    copy;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.name = 'TheoremError';
+        this.kind = kind;
+        if (options?.copy)
+            this.copy = options.copy;
+    }
+}

package/esm/src/guardrails/thought-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Thought guarding. A host that renders `thought` events shows the user what
+ * they say and loads what they link, as it does a reply: the canary, the
+ * system prompt and the user-data markers leak through a thought, and a URL
+ * the model was not given carries data out. Nothing in a thought stops a turn
+ * (`isGuardedOutput`); each leak is omitted and the rest of the thought
+ * released.
+ *
+ * @module
+ */
+import { type ResolvedEgressChecks } from './egress.js';
+import { type GivenUrls } from './egress-urls.js';
+import { type LexiconOverrides } from './lexicon.js';
+import type { EgressEnforcer, GuardrailContext, GuardrailHit } from './types.js';
+/** What a thought guard lets through: the text to show, and what it omitted from it. */
+interface ThoughtRelease {
+    text: string;
+    /** One hit per rule that omitted something; empty when nothing was. */
+    hits: GuardrailHit[];
+}
+/** One provider call's (or Live cycle's) thought text, released as it clears. */
+interface ThoughtGuard {
+    /** Read the next thought chunk; the text now clear to show, leaks omitted. */
+    push(text: string): ThoughtRelease;
+    /** The thought ended: everything still held, leaks omitted. The next thought reads on from it. */
+    flush(): ThoughtRelease;
+    /** The tail of what was shown that a leak in the next call's thoughts could continue. */
+    carryOut(): string;
+}
+interface ThoughtGuardOptions {
+    /** The URL and boundary checks thoughts run; the rest of a policy is for replies. */
+    checks?: ResolvedEgressChecks;
+    canary?: string;
+    /** Guarded against echo alongside the canary. */
+    privateSystem?: readonly string[];
+    given?: GivenUrls;
+    lexicon?: LexiconOverrides;
+    /** Shown text an earlier thought ended on (`carryOut`), read in front and never shown again. */
+    carry?: string;
+}
+/**
+ * The guard reads the thought as it will be shown, placeholders in: text
+ * released is final, and what is held changes only by omission. The canary
+ * and prompt echo are read a second time with each placeholder as the text it
+ * replaced, so a leak running on past one, or across one longer than its
+ * text, is omitted too.
+ */
+declare function createThoughtGuard(options: ThoughtGuardOptions): ThoughtGuard;
+/**
+ * A guard for a turn's thoughts: the canary and prompt echo whenever the turn
+ * binds a canary, and the URL and boundary checks `enforce` runs.
+ */
+declare function thoughtGuardFor(enforce: EgressEnforcer | undefined, context: GuardrailContext, carry?: string): ThoughtGuard | undefined;
+export type { ThoughtGuard, ThoughtGuardOptions, ThoughtRelease };
+export { createThoughtGuard, thoughtGuardFor };