@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,106 @@
+import type { ProviderEvent } from '../kernel/types.js';
+import { type GivenUrls } from './egress-urls.js';
+import { type SensitiveGroups, type SensitiveSelection } from './sensitive.js';
+import type { EgressEnforcer, GuardrailContext, GuardrailHit, OutboundPayload, Verdict } from './types.js';
+/** Why a reply was withheld, for the builder (`errorInternal`); the user reads `error.safety`. */
+declare const WITHHELD_REASON: {
+    readonly canary: "canary leaked";
+    readonly promptEcho: "system prompt echoed";
+    readonly providerToolLeak: "a provider-side tool already sent the canary or system prompt";
+    readonly egress: "Turn withheld: egress disclosure violation";
+};
+/** Never carries the live token, only a placeholder. */
+declare const CANARY_HIT: GuardrailHit;
+declare const PROMPT_ECHO_HIT: GuardrailHit;
+/** The prompt-echo hit, when `text` repeats the guarded system prompt's own words. */
+declare function promptEchoHits(text: string, privateSystem?: readonly string[], canary?: string): GuardrailHit[];
+/**
+ * The system-prompt leak hits in any content-bearing field of an event
+ * (`guardedEventTexts`). In the report of a provider-side tool they are one
+ * `egress.provider-tool-leak`: the call already ran.
+ */
+declare function eventPromptLeakHits(event: ProviderEvent, canary?: string, privateSystem?: readonly string[]): GuardrailHit[];
+/** Whether a hit is a system-prompt leak: a hard stop under any host policy. */
+declare function isPromptLeakHit(hit: GuardrailHit): boolean;
+/** Why a system-prompt leak withheld the reply, for the builder. */
+declare function promptLeakReason(hits: GuardrailHit[]): string;
+/** Where a URL check lets a URL through beyond the ones the model was given. */
+interface UrlCheck {
+    /** Hostnames the check lets through whatever their URL, such as the host's own CDN. */
+    hosts?: readonly string[];
+    /**
+     * Whether a URL a tool returned counts as given. Default true. A tool result
+     * can offer the model URLs to pick from, and the pick tells their server
+     * something; false closes that channel, and keeps only what the system
+     * prompt, the user and host history gave.
+     */
+    fromTools?: boolean;
+}
+/**
+ * Which bundled egress checks run; a check left out keeps its default. The
+ * system-prompt leak checks are not among them: `guardrails.canary` and
+ * `guardrails.promptEcho` switch those, and they run under any policy.
+ */
+interface EgressChecks {
+    /**
+     * Sensitive data in the reply, by group. Default every group but `network`:
+     * an address in a reply is not a secret, and replies explaining networks
+     * cite them.
+     */
+    sensitive?: SensitiveSelection;
+    /** The fence the kernel puts around user data, and the canary's note. Default on. */
+    boundary?: boolean;
+    /** Injection phrasing in the reply, as written or disguised. Default on. */
+    injection?: boolean;
+    /** Images that load a URL the model was not given. Default on. */
+    images?: boolean | UrlCheck;
+    /**
+     * Links to a URL the model was not given. Default off: a link loads on a
+     * click, or where the host unfurls links into previews, and replies cite
+     * pages from what the model knows. A host that unfurls turns it on.
+     */
+    links?: boolean | UrlCheck;
+}
+/** `EgressChecks` with defaults applied; a URL check is undefined when off. */
+interface ResolvedEgressChecks {
+    sensitive: SensitiveGroups;
+    boundary: boolean;
+    injection: boolean;
+    images?: UrlCheck;
+    links?: UrlCheck;
+}
+declare function resolveEgressChecks(checks?: EgressChecks): ResolvedEgressChecks;
+/** Every check off: the system-prompt leak checks alone. */
+declare const NO_CHECKS: ResolvedEgressChecks;
+declare const DEFAULT_CHECKS: ResolvedEgressChecks;
+/** What the bundled policy reads besides the reply. */
+interface EgressScope {
+    canary?: string;
+    privateSystem?: readonly string[];
+    /** The URLs the model was given this turn. */
+    given?: GivenUrls;
+}
+/** The bundled policy's hits in `text`, from the checks `checks` runs. */
+declare function collectEgressHits(text: string, scope?: EgressScope, checks?: ResolvedEgressChecks): GuardrailHit[];
+declare function hitRules(hits: GuardrailHit[]): string[];
+/** An enforce that blocks on `collect`'s hits in the reply and in any structured output. */
+declare function hitsEnforcer(collect: (text: string, context: GuardrailContext) => GuardrailHit[]): (payload: OutboundPayload, context: GuardrailContext) => Verdict;
+/** What the bundled policy reads from a gate's context. */
+declare function egressScope(context: GuardrailContext): EgressScope;
+/** Default egress enforce: every bundled check at its default (`EgressChecks`). */
+declare const standardEgressEnforce: (payload: OutboundPayload, context: GuardrailContext) => Verdict;
+declare function registerEgressChecks(enforce: EgressEnforcer, checks: ResolvedEgressChecks): void;
+/** The bundled checks `enforce` runs; undefined for a host enforce, whose checks are its own. */
+declare function egressChecksOf(enforce: EgressEnforcer | undefined): ResolvedEgressChecks | undefined;
+/** A misspelt check or group would leave the check it meant at its default, silently. */
+declare function egressChecksProblem(path: string, checks: unknown): string | undefined;
+/**
+ * A policy that throws has reached no decision, so it cannot vouch for the output:
+ * the failure becomes a `block`, not a pass. The turn then follows the profile's
+ * ordinary `onBlock` handling instead of surfacing a raw host stack trace. The
+ * thrown message may carry host internals, so it goes to the builder only
+ * (`errorInternal`); the model reads the lexicon's `egress.policy_failed`.
+ */
+declare function runEnforcer(enforce: EgressEnforcer, payload: OutboundPayload, context: GuardrailContext): Promise<Verdict>;
+export type { EgressChecks, EgressScope, ResolvedEgressChecks, UrlCheck };
+export { CANARY_HIT, collectEgressHits, DEFAULT_CHECKS, egressChecksOf, egressChecksProblem, egressScope, eventPromptLeakHits, hitRules, hitsEnforcer, isPromptLeakHit, NO_CHECKS, PROMPT_ECHO_HIT, promptEchoHits, promptLeakReason, registerEgressChecks, resolveEgressChecks, runEnforcer, standardEgressEnforce, WITHHELD_REASON, };

package/esm/src/guardrails/egress.js

@@ -0,0 +1,374 @@
+import { isRecord } from '../kernel/util/record.js';
+import { guardedEventTexts, scanTextForCanaryLeak } from './canary.js';
+import { SYSTEM_BOUNDARY } from './egress-patterns.js';
+import { imageLeakSpans, linkLeakSpans } from './egress-urls.js';
+import { describeError } from './error.js';
+import { hitFromSpan } from './hits.js';
+import { injectionSpans } from './injection.js';
+import { lexiconText } from './lexicon.js';
+import { scanTextForPromptEcho } from './prompt-echo.js';
+import { EGRESS_RULES } from './rules.js';
+import { anySensitive, resolveSensitive, SENSITIVE_GROUPS, sensitiveSpans, } from './sensitive.js';
+import { textForScan } from './serialize.js';
+import { SEVERITIES } from './types.js';
+function hitsFromSpans(text, spans, rule, severity) {
+    return spans.map((span) => hitFromSpan(text, span, rule, severity));
+}
+/** Why a reply was withheld, for the builder (`errorInternal`); the user reads `error.safety`. */
+const WITHHELD_REASON = {
+    canary: 'canary leaked',
+    promptEcho: 'system prompt echoed', // lexicon-exempt: internal diagnostic — the user reads error.safety
+    providerToolLeak: 'a provider-side tool already sent the canary or system prompt', // lexicon-exempt: internal diagnostic — the user reads error.safety
+    egress: 'Turn withheld: egress disclosure violation', // lexicon-exempt: internal diagnostic — the user reads error.safety
+};
+/** Never carries the live token, only a placeholder. */
+const CANARY_HIT = { rule: EGRESS_RULES.canary, severity: 'high', match: '[canary]' };
+const PROMPT_ECHO_HIT = { rule: EGRESS_RULES.promptEcho, severity: 'high' };
+function canaryHits(text, canary) {
+    return canary && scanTextForCanaryLeak(text, canary) ? [CANARY_HIT] : [];
+}
+/** The prompt-echo hit, when `text` repeats the guarded system prompt's own words. */
+function promptEchoHits(text, privateSystem, canary) {
+    return privateSystem && scanTextForPromptEcho(text, privateSystem, canary)
+        ? [PROMPT_ECHO_HIT]
+        : [];
+}
+/** The system-prompt leak hits: the canary, and the prompt's own words when guarded. */
+function promptLeakHits(text, canary, privateSystem) {
+    return [...canaryHits(text, canary), ...promptEchoHits(text, privateSystem, canary)];
+}
+const PROVIDER_TOOL_LEAK_HIT = {
+    rule: EGRESS_RULES.providerToolLeak,
+    severity: 'high',
+};
+/**
+ * Evidence kinds that report a step the provider ran itself: its built-in
+ * tools, and any step an adapter does not map (`provider_step`).
+ */
+const PROVIDER_TOOL_EVIDENCE = new Set([
+    'code_execution_call',
+    'code_execution_result',
+    'url_context',
+    'provider_step',
+]);
+/** The provider's report of a built-in tool it already ran. What it carries has left. */
+function isProviderToolReport(event) {
+    return (event.type === 'grounding' ||
+        (event.type === 'evidence' && PROVIDER_TOOL_EVIDENCE.has(event.evidence.kind)));
+}
+/**
+ * The system-prompt leak hits in any content-bearing field of an event
+ * (`guardedEventTexts`). In the report of a provider-side tool they are one
+ * `egress.provider-tool-leak`: the call already ran.
+ */
+function eventPromptLeakHits(event, canary, privateSystem) {
+    const hits = guardedEventTexts(event).flatMap((text) => promptLeakHits(text, canary, privateSystem));
+    if (hits.length > 0 && isProviderToolReport(event)) {
+        return [PROVIDER_TOOL_LEAK_HIT];
+    }
+    return [...new Map(hits.map((hit) => [hit.rule, hit])).values()];
+}
+const PROMPT_LEAK_RULES = new Set([
+    EGRESS_RULES.canary,
+    EGRESS_RULES.promptEcho,
+    EGRESS_RULES.providerToolLeak,
+]);
+/** Whether a hit is a system-prompt leak: a hard stop under any host policy. */
+function isPromptLeakHit(hit) {
+    return PROMPT_LEAK_RULES.has(hit.rule);
+}
+/** Why a system-prompt leak withheld the reply, for the builder. */
+function promptLeakReason(hits) {
+    if (hits.some((hit) => hit.rule === EGRESS_RULES.providerToolLeak)) {
+        return WITHHELD_REASON.providerToolLeak;
+    }
+    return hits.some((hit) => hit.rule === EGRESS_RULES.canary)
+        ? WITHHELD_REASON.canary
+        : WITHHELD_REASON.promptEcho;
+}
+const EGRESS_SENSITIVE_DEFAULT = {
+    ids: true,
+    financial: true,
+    network: false,
+    credentials: true,
+};
+function resolveUrlCheck(check, byDefault) {
+    if (check === undefined)
+        return byDefault ? {} : undefined;
+    if (typeof check === 'boolean')
+        return check ? {} : undefined;
+    return check;
+}
+function resolveEgressChecks(checks = {}) {
+    const images = resolveUrlCheck(checks.images, true);
+    const resolved = resolveUrlCheck(checks.links, false);
+    // A host images load from already takes data with no click, so a link there opens nothing new.
+    const links = resolved && images?.hosts
+        ? { ...resolved, hosts: [...new Set([...(resolved.hosts ?? []), ...images.hosts])] }
+        : resolved;
+    return {
+        sensitive: resolveSensitive(checks.sensitive, EGRESS_SENSITIVE_DEFAULT),
+        boundary: checks.boundary ?? true,
+        injection: checks.injection ?? true,
+        ...(images ? { images } : {}),
+        ...(links ? { links } : {}),
+    };
+}
+/** Every check off: the system-prompt leak checks alone. */
+const NO_CHECKS = resolveEgressChecks({
+    sensitive: false,
+    boundary: false,
+    injection: false,
+    images: false,
+});
+const DEFAULT_CHECKS = resolveEgressChecks();
+function urlScope(check, given) {
+    return { ...check, ...(given ? { given } : {}) };
+}
+/** The bundled policy's hits in `text`, from the checks `checks` runs. */
+function collectEgressHits(text, scope = {}, checks = DEFAULT_CHECKS) {
+    const hits = promptLeakHits(text, scope.canary, scope.privateSystem);
+    if (anySensitive(checks.sensitive)) {
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        hits.push(...hitsFromSpans(text, sensitiveSpans(text, checks.sensitive), EGRESS_RULES.sensitive, 'high'));
+    }
+    const boundary = checks.boundary ? SYSTEM_BOUNDARY.exec(text) : null;
+    if (boundary && boundary.index !== undefined) {
+        hits.push(hitFromSpan(text, { start: boundary.index, end: boundary.index + boundary[0].length }, EGRESS_RULES.boundary, 'medium'));
+    }
+    if (checks.injection) {
+        hits.push(...hitsFromSpans(text, injectionSpans(text), EGRESS_RULES.injection, 'medium')); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (checks.images) {
+        const spans = imageLeakSpans(text, urlScope(checks.images, scope.given));
+        hits.push(...hitsFromSpans(text, spans, EGRESS_RULES.image, 'high'));
+    }
+    if (checks.links) {
+        const spans = linkLeakSpans(text, urlScope(checks.links, scope.given), Boolean(checks.images));
+        hits.push(...hitsFromSpans(text, spans, EGRESS_RULES.link, 'high'));
+    }
+    return hits;
+}
+function hitRules(hits) {
+    return [...new Set(hits.map((hit) => hit.rule))];
+}
+function isGuardrailHit(value) {
+    if (!isRecord(value) ||
+        typeof value.rule !== 'string' ||
+        !value.rule.trim() ||
+        !SEVERITIES.includes(value.severity)) {
+        return false;
+    }
+    for (const key of ['match', 'label', 'doc']) {
+        if (value[key] !== undefined && typeof value[key] !== 'string')
+            return false;
+    }
+    if (value.span !== undefined) {
+        if (!isRecord(value.span) ||
+            typeof value.span.start !== 'number' ||
+            !Number.isFinite(value.span.start) ||
+            typeof value.span.end !== 'number' ||
+            !Number.isFinite(value.span.end)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isGuardrailHits(value) {
+    return Array.isArray(value) && value.every(isGuardrailHit);
+}
+function isVerdict(value) {
+    if (!isRecord(value))
+        return false;
+    switch (value.action) {
+        case 'allow':
+            return true;
+        case 'redact':
+            return typeof value.text === 'string' && isGuardrailHits(value.hits);
+        case 'flag':
+            return isGuardrailHits(value.hits);
+        case 'block':
+            return (isGuardrailHits(value.hits) &&
+                typeof value.rejection === 'string' &&
+                (value.errorInternal === undefined || typeof value.errorInternal === 'string'));
+        default:
+            return false;
+    }
+}
+function legacyHits(value) {
+    if (!Array.isArray(value)) {
+        return [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }];
+    }
+    const hits = value
+        .map((hit) => {
+        if (typeof hit === 'string' && hit.trim()) {
+            return { rule: hit, severity: 'high' };
+        }
+        if (isRecord(hit) && typeof hit.rule === 'string' && hit.rule.trim()) {
+            const severity = SEVERITIES.includes(hit.severity)
+                ? hit.severity
+                : 'high';
+            return {
+                rule: hit.rule,
+                severity,
+                ...(typeof hit.label === 'string' ? { label: hit.label } : {}),
+                ...(typeof hit.doc === 'string' ? { doc: hit.doc } : {}),
+            };
+        }
+        return undefined;
+    })
+        .filter((hit) => Boolean(hit));
+    return hits.length ? hits : [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }];
+}
+function normalizeVerdict(value, context) {
+    if (isVerdict(value)) {
+        return value;
+    }
+    if (isRecord(value) && typeof value.blocked === 'boolean') {
+        if (!value.blocked) {
+            return { action: 'allow' };
+        }
+        const hits = legacyHits(value.hits);
+        const rejection = typeof value.rejectionMessage === 'string' && value.rejectionMessage.trim()
+            ? value.rejectionMessage
+            : lexiconText('egress.rejection', { rules: hitRules(hits).join(', ') }, context.lexicon);
+        return { action: 'block', hits, rejection };
+    }
+    return {
+        action: 'block',
+        hits: [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }],
+        rejection: lexiconText('egress.invalid_verdict', {}, context.lexicon),
+    };
+}
+/** An enforce that blocks on `collect`'s hits in the reply and in any structured output. */
+function hitsEnforcer(collect) {
+    return (payload, context) => {
+        const hits = collect(payload.text, context);
+        if (payload.structured !== undefined) {
+            const structured = textForScan(payload.structured);
+            if (structured.unscannable) {
+                // Cannot inspect it, so cannot vouch for it. Fail closed.
+                hits.push({ rule: EGRESS_RULES.unscannable, severity: 'high' }); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            else {
+                hits.push(...collect(structured.text, context));
+            }
+        }
+        if (hits.length === 0) {
+            return { action: 'allow' };
+        }
+        return {
+            action: 'block',
+            hits,
+            rejection: lexiconText('egress.rejection', { rules: hitRules(hits).join(', ') }, context.lexicon),
+        };
+    };
+}
+/** What the bundled policy reads from a gate's context. */
+function egressScope(context) {
+    return {
+        ...(context.canary ? { canary: context.canary } : {}),
+        ...(context.privateSystem ? { privateSystem: context.privateSystem } : {}),
+        ...(context.givenUrls ? { given: context.givenUrls } : {}),
+    };
+}
+/** Default egress enforce: every bundled check at its default (`EgressChecks`). */
+const standardEgressEnforce = hitsEnforcer((text, context) => collectEgressHits(text, egressScope(context)));
+/** The bundled checks each enforce runs, for the enforces built from them. */
+const KNOWN_CHECKS = new WeakMap([
+    [standardEgressEnforce, DEFAULT_CHECKS],
+]);
+function registerEgressChecks(enforce, checks) {
+    KNOWN_CHECKS.set(enforce, checks);
+}
+/** The bundled checks `enforce` runs; undefined for a host enforce, whose checks are its own. */
+function egressChecksOf(enforce) {
+    return enforce && KNOWN_CHECKS.get(enforce);
+}
+const CHECK_NAMES = new Set(['sensitive', 'boundary', 'injection', 'images', 'links']);
+const URL_CHECK_NAMES = new Set(['hosts', 'fromTools']);
+const GROUP_NAMES = new Set(SENSITIVE_GROUPS);
+/** A hostname is all a URL check's host is: a scheme, port or path would never match one. */
+function urlCheckProblem(path, check) {
+    if (check === undefined || typeof check === 'boolean')
+        return undefined;
+    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (typeof check !== 'object' || check === null)
+        return `${path} must be a boolean or an object`;
+    const unknown = Object.keys(check).find((key) => !URL_CHECK_NAMES.has(key));
+    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (unknown !== undefined)
+        return `${path} has no option ${JSON.stringify(unknown)}`;
+    const { hosts, fromTools } = check;
+    if (fromTools !== undefined && typeof fromTools !== 'boolean') {
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return `${path}.fromTools must be a boolean`;
+    }
+    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (hosts !== undefined && !Array.isArray(hosts))
+        return `${path}.hosts must be a list`;
+    const bad = (hosts ?? []).find((host) => typeof host !== 'string' || !/^[a-z0-9.-]+$/i.test(host) || host.startsWith('.'));
+    return bad === undefined
+        ? undefined
+        : // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            `${path}.hosts lists ${JSON.stringify(bad)}, which is not a hostname`;
+}
+/** A misspelt check or group would leave the check it meant at its default, silently. */
+function egressChecksProblem(path, checks) {
+    if (typeof checks === 'boolean')
+        return undefined;
+    if (typeof checks !== 'object' || checks === null)
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        return `${path} must be a boolean or an object`;
+    const unknown = Object.keys(checks).find((key) => !CHECK_NAMES.has(key));
+    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (unknown !== undefined)
+        return `${path} has no check ${JSON.stringify(unknown)}`;
+    const { sensitive, boundary, injection, images, links } = checks;
+    for (const [name, value] of [
+        ['boundary', boundary],
+        ['injection', injection],
+    ]) {
+        if (value !== undefined && typeof value !== 'boolean')
+            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            return `${path}.${name} must be a boolean`;
+    }
+    if (sensitive !== undefined && typeof sensitive !== 'boolean') {
+        if (typeof sensitive !== 'object' || sensitive === null) {
+            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            return `${path}.sensitive must be a boolean or an object`;
+        }
+        const unknownGroup = Object.keys(sensitive).find((group) => !GROUP_NAMES.has(group));
+        if (unknownGroup !== undefined) {
+            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            return `${path}.sensitive has no group ${JSON.stringify(unknownGroup)} (${SENSITIVE_GROUPS.join(', ')})`;
+        }
+        const bad = Object.entries(sensitive).find(([, on]) => typeof on !== 'boolean');
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        if (bad !== undefined)
+            return `${path}.sensitive.${bad[0]} must be a boolean`;
+    }
+    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    return urlCheckProblem(`${path}.images`, images) ?? urlCheckProblem(`${path}.links`, links);
+}
+/**
+ * A policy that throws has reached no decision, so it cannot vouch for the output:
+ * the failure becomes a `block`, not a pass. The turn then follows the profile's
+ * ordinary `onBlock` handling instead of surfacing a raw host stack trace. The
+ * thrown message may carry host internals, so it goes to the builder only
+ * (`errorInternal`); the model reads the lexicon's `egress.policy_failed`.
+ */
+async function runEnforcer(enforce, payload, context) {
+    try {
+        return normalizeVerdict(await enforce(payload, context), context);
+    }
+    catch (err) {
+        return {
+            action: 'block',
+            hits: [{ rule: EGRESS_RULES.enforcerError, severity: 'high' }],
+            rejection: lexiconText('egress.policy_failed', {}, context.lexicon),
+            errorInternal: describeError(err),
+        };
+    }
+}
+export { CANARY_HIT, collectEgressHits, DEFAULT_CHECKS, egressChecksOf, egressChecksProblem, egressScope, eventPromptLeakHits, hitRules, hitsEnforcer, isPromptLeakHit, NO_CHECKS, PROMPT_ECHO_HIT, promptEchoHits, promptLeakReason, registerEgressChecks, resolveEgressChecks, runEnforcer, standardEgressEnforce, WITHHELD_REASON, };

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

@@ -0,0 +1,26 @@
+import type { TurnEventOf } from '../kernel/turn-events.js';
+import type { TurnEvent } from '../kernel/types.js';
+import { type LexiconOverrides } from './lexicon.js';
+import { type ErrorKind, TheoremError } from './theorem-error.js';
+declare function isAbortError(err: unknown): boolean;
+/** `AbortSignal.timeout` rejects with a `TimeoutError`, not an `AbortError`. */
+declare function isTimeoutError(err: unknown): boolean;
+declare function throwIfAborted(signal?: AbortSignal): void;
+/** Anything that is not a `TheoremError` or an abort escaped every boundary that names kinds: a THEOREM bug. */
+declare function errorKind(err: unknown): ErrorKind;
+declare function kindOfHttpStatus(status: number): ErrorKind;
+/** Pass the profile's `lexicon`, or the profile's wording is skipped. */
+declare function publicError(err: unknown, lexicon?: LexiconOverrides): string;
+/** Raw diagnostic for hosts, traces and logs; never shown to end users. */
+declare function describeError(err: unknown): string;
+type ProducedError = TurnEventOf<'error'> & {
+    errorInternal: string;
+};
+/** No user wording yet: `withPublicWording` adds it where the event reaches the host, the one place that knows the profile. */
+declare function toErrorEvent(err: unknown): ProducedError;
+/** Wording already set (host copy) is kept. */
+declare function withPublicWording(event: TurnEvent, lexicon?: LexiconOverrides): TurnEvent;
+export type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './theorem-error.js';
+export { ERROR_KINDS } from './theorem-error.js';
+export type { ProducedError };
+export { describeError, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicWording, };

package/esm/src/guardrails/error.js

@@ -0,0 +1,91 @@
+import { lexiconText } from './lexicon.js';
+import { TheoremError } from './theorem-error.js';
+function isAbortError(err) {
+    return errorName(err) === 'AbortError';
+}
+/** `AbortSignal.timeout` rejects with a `TimeoutError`, not an `AbortError`. */
+function isTimeoutError(err) {
+    return errorName(err) === 'TimeoutError';
+}
+function errorName(err) {
+    return err && typeof err === 'object' ? err.name : undefined;
+}
+function throwIfAborted(signal) {
+    if (!signal?.aborted) {
+        return;
+    }
+    const { reason } = signal;
+    if (isAbortError(reason) || isTimeoutError(reason)) {
+        throw reason;
+    }
+    throw new DOMException('The operation was aborted.', 'AbortError'); // lexicon-exempt: DOM AbortError fingerprint
+}
+/** Anything that is not a `TheoremError` or an abort escaped every boundary that names kinds: a THEOREM bug. */
+function errorKind(err) {
+    if (err instanceof TheoremError)
+        return err.kind;
+    if (isTimeoutError(err))
+        return 'timeout';
+    if (isAbortError(err))
+        return 'cancelled';
+    return 'internal';
+}
+function kindOfHttpStatus(status) {
+    if (status === 401 || status === 402 || status === 403)
+        return 'auth';
+    if (status === 408 || status === 504 || status === 524)
+        return 'timeout';
+    if (status === 429)
+        return 'rate_limit';
+    if (status >= 500)
+        return 'unavailable';
+    return 'unsupported';
+}
+function kindText(kind, lexicon, params) {
+    return lexiconText(`error.${kind}`, params, lexicon);
+}
+function wording(kind, copy, lexicon) {
+    if (!copy)
+        return kindText(kind, lexicon);
+    const lines = 'key' in copy ? [copy] : copy;
+    return lines.map((line) => lexiconText(line.key, line.params, lexicon)).join('\n');
+}
+/** Pass the profile's `lexicon`, or the profile's wording is skipped. */
+function publicError(err, lexicon) {
+    return wording(errorKind(err), err instanceof TheoremError ? err.copy : undefined, lexicon);
+}
+/** Raw diagnostic for hosts, traces and logs; never shown to end users. */
+function describeError(err) {
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err instanceof Error && err.message) {
+        return err.message;
+    }
+    return String(err);
+}
+/** No user wording yet: `withPublicWording` adds it where the event reaches the host, the one place that knows the profile. */
+function toErrorEvent(err) {
+    return {
+        type: 'error',
+        errorKind: errorKind(err),
+        ...(err instanceof TheoremError && err.copy ? { errorCopy: err.copy } : {}),
+        errorInternal: describeError(err),
+    };
+}
+/** Wording already set (host copy) is kept. */
+function withPublicWording(event, lexicon) {
+    if (event.type === 'error' && event.error === undefined) {
+        return { ...event, error: wording(event.errorKind, event.errorCopy, lexicon) };
+    }
+    if (event.type === 'tool' &&
+        event.tool.phase === 'error' &&
+        event.tool.failure.error === undefined) {
+        const { tool } = event;
+        const error = kindText(tool.failure.kind, lexicon, { tool: tool.name });
+        return { ...event, tool: { ...tool, failure: { ...tool.failure, error } } };
+    }
+    return event;
+}
+export { ERROR_KINDS } from './theorem-error.js';
+export { describeError, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicWording, };

package/esm/src/guardrails/event-schemas.d.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { type LexiconKey } from './lexicon.js';
+import { type ErrorKind } from './theorem-error.js';
+import { type GuardrailAction, type GuardrailStage, type Severity, type ToolOrigin, type TrustLevel } from './types.js';
+export declare const errorKindSchema: z.ZodType<ErrorKind>;
+/** Wording for the user more specific than its kind's: a lexicon key and its parameters. */
+export interface ErrorCopy {
+    key: LexiconKey;
+    params?: Record<string, string | number>;
+}
+/** One line of wording, or one per problem found. */
+export type ErrorCopies = ErrorCopy | readonly ErrorCopy[];
+export declare const errorCopiesSchema: z.ZodType<ErrorCopies>;
+/**
+ * `depth` is hops from the user's turn: a direct tool call is 1; a tool result
+ * produced by a delegated agent that itself called tools is deeper. Depth
+ * matters because a two-hop delegation can otherwise launder remote content
+ * into trusted-looking output.
+ */
+export interface Provenance {
+    origin: ToolOrigin;
+    tool: string;
+    depth: number;
+}
+export interface GuardrailHit {
+    /** Stable rule id, e.g. `egress.canary-leak`. */
+    rule: string;
+    severity: Severity;
+    /** Offsets into the inspected text; absent for whole-payload checks. */
+    span?: {
+        start: number;
+        end: number;
+    };
+    /** Stripped from host and trace unless `observability.include.guardrailMatchPreview`. */
+    match?: string;
+    /**
+     * What the rule catches, in a few words, for a host's own rule: Theorem's
+     * rules are named in the trace catalog. Shown in place of the id.
+     */
+    label?: string;
+    /** Why a match matters, in a sentence, for a host's own rule. */
+    doc?: string;
+}
+/**
+ * Matched text rides only under `observability.include.guardrailMatchPreview`, so by default a
+ * trace sink can count and locate hits without becoming a second copy of the secret.
+ */
+export interface GuardrailEvent {
+    stage: GuardrailStage;
+    trust: TrustLevel;
+    action: GuardrailAction;
+    hits: GuardrailHit[];
+    provenance?: Provenance;
+    /** The block verdict's `errorInternal`: builder-only, stripped by `forClient`. */
+    errorInternal?: string;
+}
+export declare const guardrailEventSchema: z.ZodType<GuardrailEvent>;