@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,46 @@
+import type { ModelEvent } from '../kernel/types.js';
+import type { ResolvedDetect } from './detectors.js';
+import type { GuardrailContext, GuardrailHit } 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";
+};
+/** 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[];
+/** What a prompt-leak check reads of the turn. */
+type LeakScope = Pick<GuardrailContext, 'canary' | 'canaryGiven' | 'privateSystem'>;
+/**
+ * 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: ModelEvent, scope: LeakScope): GuardrailHit[];
+/** A leak of ours in an event that is not the reply's text: its hits, and whether it stops the turn. */
+interface EventLeak {
+    stop: boolean;
+    hits: GuardrailHit[];
+}
+/**
+ * What the detectors of what is ours find in an event's host content
+ * (`guardedEventTexts`) under their actions at `boundary`, as the event goes
+ * to the host with the reply. `flag` reports it; `redact` and `block` stop the
+ * turn, as an event has no text to replace. The report of a provider-side tool
+ * is read whatever the actions are and always stops: the call already ran.
+ */
+declare function eventLeak(event: ModelEvent, scope: LeakScope, detect: ResolvedDetect, boundary: 'reply' | 'live_reply'): EventLeak | undefined;
+/** Whether a hit is a system-prompt leak. */
+declare function isPromptLeakHit(hit: GuardrailHit): boolean;
+/** Why a system-prompt leak withheld the reply, for the builder. */
+declare function promptLeakReason(hits: GuardrailHit[]): string;
+/** The distinct rule names among the hits. */
+declare function hitRules(hits: GuardrailHit[]): string[];
+/**
+ * The words of the canary note a turn binds, when the profile's labels
+ * rewords it so that `SYSTEM_BOUNDARY` no longer reads them.
+ */
+declare function boundaryNote({ canary, labels, }: Pick<GuardrailContext, 'canary' | 'labels'>): string | undefined;
+export type { EventLeak, LeakScope };
+export { boundaryNote, eventLeak, eventPromptLeakHits, hitRules, isPromptLeakHit, promptEchoHits, promptLeakReason, WITHHELD_REASON, };

package/esm/src/guardrails/egress.js

@@ -0,0 +1,124 @@
+import { canaryNoteMarker, guardedEventTexts, scanTextForCanaryLeak } from './canary.js';
+import { SYSTEM_BOUNDARY } from './egress-patterns.js';
+import { CANARY_HIT, PROMPT_ECHO_HIT } from './hits.js';
+import { scanTextForPromptEcho } from './prompt-echo.js';
+import { DETECT_RULES, EGRESS_RULES } from './rules.js';
+/** Why a reply was withheld, for the builder (`errorInternal`); the user reads `error.safety`. */
+const WITHHELD_REASON = {
+    canary: 'canary leaked',
+    promptEcho: 'system prompt echoed', // labels-exempt: internal diagnostic — the user reads error.safety
+    providerToolLeak: 'a provider-side tool already sent the canary or system prompt', // labels-exempt: internal diagnostic — the user reads error.safety
+    egress: 'Turn withheld: egress disclosure violation', // labels-exempt: internal diagnostic — the user reads error.safety
+};
+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 unless it was given, and the prompt's own words when guarded. */
+function promptLeakHits(text, scope) {
+    const { canary, canaryGiven, privateSystem } = scope;
+    return [
+        ...canaryHits(text, canaryGiven ? undefined : 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, scope) {
+    const hits = guardedEventTexts(event).flatMap((text) => promptLeakHits(text, scope));
+    if (hits.length > 0 && isProviderToolReport(event)) {
+        return [PROVIDER_TOOL_LEAK_HIT];
+    }
+    return [...new Map(hits.map((hit) => [hit.rule, hit])).values()];
+}
+/**
+ * What the detectors of what is ours find in an event's host content
+ * (`guardedEventTexts`) under their actions at `boundary`, as the event goes
+ * to the host with the reply. `flag` reports it; `redact` and `block` stop the
+ * turn, as an event has no text to replace. The report of a provider-side tool
+ * is read whatever the actions are and always stops: the call already ran.
+ */
+function eventLeak(event, scope, detect, boundary) {
+    if (isProviderToolReport(event)) {
+        const hits = eventPromptLeakHits(event, scope);
+        return hits.length > 0 ? { stop: true, hits } : undefined;
+    }
+    const texts = guardedEventTexts(event);
+    const found = [];
+    const canary = scope.canaryGiven ? undefined : scope.canary;
+    const canaryAction = detect.canary_leak[boundary];
+    if (canaryAction !== 'ignore' && texts.some((text) => canaryHits(text, canary).length > 0)) {
+        found.push([canaryAction, CANARY_HIT]);
+    }
+    const promptAction = detect.prompt_leak[boundary];
+    if (promptAction !== 'ignore' &&
+        texts.some((text) => promptEchoHits(text, scope.privateSystem, scope.canary).length > 0)) {
+        found.push([promptAction, PROMPT_ECHO_HIT]);
+    }
+    if (found.length === 0)
+        return undefined;
+    return {
+        stop: found.some(([action]) => action !== 'flag'),
+        hits: found.map(([, hit]) => hit),
+    };
+}
+const PROMPT_LEAK_RULES = new Set([
+    DETECT_RULES.canary_leak,
+    DETECT_RULES.prompt_leak,
+    EGRESS_RULES.providerToolLeak,
+]);
+/** Whether a hit is a system-prompt leak. */
+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 === DETECT_RULES.canary_leak)
+        ? WITHHELD_REASON.canary
+        : WITHHELD_REASON.promptEcho;
+}
+/** The distinct rule names among the hits. */
+function hitRules(hits) {
+    return [...new Set(hits.map((hit) => hit.rule))];
+}
+/**
+ * The words of the canary note a turn binds, when the profile's labels
+ * rewords it so that `SYSTEM_BOUNDARY` no longer reads them.
+ */
+function boundaryNote({ canary, labels, }) {
+    if (!canary)
+        return undefined;
+    const marker = canaryNoteMarker(labels);
+    return marker && !SYSTEM_BOUNDARY.test(marker) ? marker : undefined;
+}
+export { boundaryNote, eventLeak, eventPromptLeakHits, hitRules, isPromptLeakHit, promptEchoHits, promptLeakReason, WITHHELD_REASON, };

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

@@ -0,0 +1,31 @@
+import type { TurnEventOf } from '../kernel/turn-events.js';
+import type { TurnEvent } from '../kernel/types.js';
+import { type LabelOverrides } from './labels.js';
+import { type ErrorCopies, type ErrorKind, TheoremError } from './theorem-error.js';
+/** True when the value is an error named `AbortError`. */
+declare function isAbortError(err: unknown): boolean;
+/** `AbortSignal.timeout` rejects with a `TimeoutError`, not an `AbortError`. */
+declare function isTimeoutError(err: unknown): boolean;
+/** Throws when the signal has aborted: its framework, abort or timeout reason, else an `AbortError`. */
+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;
+/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 500 and above `unavailable`; the rest `unsupported`. */
+declare function kindOfHttpStatus(status: number): ErrorKind;
+/** The named reasons an error carries, one line each, in the profile's wording. */
+declare function errorCopyText(copy: ErrorCopies, labels?: LabelOverrides): string;
+/** Pass the profile's `labels`, or the profile's wording is skipped. */
+declare function publicError(err: unknown, labels?: LabelOverrides): 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: `withPublicLabels` 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 withPublicLabels(event: TurnEvent, labels?: LabelOverrides): TurnEvent;
+export type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './theorem-error.js';
+export { ERROR_KINDS } from './theorem-error.js';
+export type { ProducedError };
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

package/esm/src/guardrails/error.js

@@ -0,0 +1,96 @@
+import { labelText } from './labels.js';
+import { TheoremError } from './theorem-error.js';
+/** True when the value is an error named `AbortError`. */
+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;
+}
+/** Throws when the signal has aborted: its framework, abort or timeout reason, else an `AbortError`. */
+function throwIfAborted(signal) {
+    if (!signal?.aborted) {
+        return;
+    }
+    const { reason } = signal;
+    if (reason instanceof TheoremError || isAbortError(reason) || isTimeoutError(reason)) {
+        throw reason;
+    }
+    throw new DOMException('The operation was aborted.', 'AbortError'); // labels-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';
+}
+/** The error kind for an HTTP status: 401, 402 and 403 are `auth`; 408, 504 and 524 `timeout`; 429 `rate_limit`; 500 and above `unavailable`; the rest `unsupported`. */
+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, labels, params) {
+    return labelText(`error.${kind}`, params, labels);
+}
+function wording(kind, copy, labels) {
+    return copy ? errorCopyText(copy, labels) : kindText(kind, labels);
+}
+/** The named reasons an error carries, one line each, in the profile's wording. */
+function errorCopyText(copy, labels) {
+    const lines = 'key' in copy ? [copy] : copy;
+    return lines.map((line) => labelText(line.key, line.params, labels)).join('\n');
+}
+/** Pass the profile's `labels`, or the profile's wording is skipped. */
+function publicError(err, labels) {
+    return wording(errorKind(err), err instanceof TheoremError ? err.copy : undefined, labels);
+}
+/** 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: `withPublicLabels` 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 withPublicLabels(event, labels) {
+    if (event.type === 'error' && event.error === undefined) {
+        return { ...event, error: wording(event.errorKind, event.errorCopy, labels) };
+    }
+    if (event.type === 'tool' &&
+        event.tool.phase === 'error' &&
+        event.tool.failure.error === undefined) {
+        const { tool } = event;
+        const error = kindText(tool.failure.kind, labels, { tool: tool.name });
+        return { ...event, tool: { ...tool, failure: { ...tool.failure, error } } };
+    }
+    return event;
+}
+export { ERROR_KINDS } from './theorem-error.js';
+export { describeError, errorCopyText, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, };

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

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { type Boundary } from './boundaries.js';
+import { type LabelKey } from './labels.js';
+import { type ErrorKind } from './theorem-error.js';
+import { type GuardrailAction, type GuardrailStage, type Severity, type ToolOrigin, type TrustLevel } from './types.js';
+/** The schema an error kind parses against. */
+export declare const errorKindSchema: z.ZodType<ErrorKind>;
+/** Wording for the user more specific than its kind's: a label key and its parameters. */
+export interface ErrorCopy {
+    key: LabelKey;
+    params?: Record<string, string | number>;
+}
+/** One line of wording, or one per problem found. */
+export type ErrorCopies = ErrorCopy | readonly ErrorCopy[];
+/** The schema error wording parses against. */
+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 declare const provenance: z.ZodObject<{
+    origin: z.ZodEnum<{
+        http: "http";
+        mcp: "mcp";
+        builtin: "builtin";
+        local: "local";
+        delegated: "delegated";
+    }>;
+    tool: z.ZodString;
+    depth: z.ZodNumber;
+}, z.core.$strip>;
+/** One rule match: the rule id, its severity, where it matched and, when kept, the matched text. */
+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;
+    /** The name of the host's pattern that matched; unset for a match of Theorem's own patterns. */
+    pattern?: string;
+    /**
+     * What about the match made it one, for `tool_instructions`: `override`, `tool_name`, `order`
+     * or `authority`. For a host's `find` that failed, how: `find_threw` or `find_result`.
+     */
+    signal?: string;
+}
+export declare const guardrailHit: z.ZodObject<{
+    rule: z.ZodString;
+    severity: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        info: "info";
+    }>;
+    span: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strip>>;
+    match: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    doc: z.ZodOptional<z.ZodString>;
+    pattern: z.ZodOptional<z.ZodString>;
+    signal: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 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;
+    /** Where the text was crossing, when a detector read it there. */
+    boundary?: Boundary;
+    trust: TrustLevel;
+    action: GuardrailAction;
+    hits: GuardrailHit[];
+    provenance?: Provenance;
+    /** The block verdict's `errorInternal`: builder-only, stripped by `forClient`. */
+    errorInternal?: string;
+}
+/** The schema a guardrail event parses against. */
+export declare const guardrailEventSchema: z.ZodType<GuardrailEvent>;

package/esm/src/guardrails/event-schemas.js

@@ -0,0 +1,48 @@
+// invariant: Imports nothing from `src/kernel/` but the dependency-free `Equals`: `src/kernel/turn-events.ts` imports these.
+import { z } from 'zod';
+import { BOUNDARIES } from './boundaries.js';
+import { LABEL_KEYS } from './labels.js';
+import { ERROR_KINDS } from './theorem-error.js';
+import { GUARDRAIL_ACTIONS, GUARDRAIL_STAGES, SEVERITIES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';
+const errorKind = z.enum(ERROR_KINDS);
+true;
+/** The schema an error kind parses against. */
+export const errorKindSchema = errorKind;
+const errorCopy = z.object({
+    key: z.enum(LABEL_KEYS),
+    params: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+});
+true;
+const errorCopies = z.union([errorCopy, z.array(errorCopy).readonly()]);
+true;
+/** The schema error wording parses against. */
+export const errorCopiesSchema = errorCopies;
+export const provenance = z.object({
+    origin: z.enum(TOOL_ORIGINS),
+    tool: z.string(),
+    depth: z.number(),
+});
+true;
+export const guardrailHit = z.object({
+    rule: z.string(),
+    severity: z.enum(SEVERITIES),
+    span: z.object({ start: z.number(), end: z.number() }).optional(),
+    match: z.string().optional(),
+    label: z.string().optional(),
+    doc: z.string().optional(),
+    pattern: z.string().optional(),
+    signal: z.string().optional(),
+});
+true;
+const guardrailEvent = z.object({
+    stage: z.enum(GUARDRAIL_STAGES),
+    boundary: z.enum(BOUNDARIES).optional(),
+    trust: z.enum(TRUST_LEVELS),
+    action: z.enum(GUARDRAIL_ACTIONS),
+    hits: z.array(guardrailHit),
+    provenance: provenance.optional(),
+    errorInternal: z.string().optional(),
+});
+true;
+/** The schema a guardrail event parses against. */
+export const guardrailEventSchema = guardrailEvent;

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

@@ -0,0 +1,13 @@
+import type { TurnEvent, TurnEventOf } from '../kernel/turn-events.js';
+import type { GuardrailAction, GuardrailEvent, GuardrailHit, GuardrailStage, Provenance, TrustLevel, Verdict } from './types.js';
+/** Wraps a guardrail event as a turn event. */
+declare function guardrailTurnEvent(guardrail: GuardrailEvent): TurnEventOf<'guardrail'>;
+/** `allow` yields nothing; `flag`, `redact`, and `block` all emit so hosts and traces can count hits. */
+declare function guardrailFromVerdict(stage: GuardrailStage, trust: TrustLevel, verdict: Verdict, provenance?: Provenance): TurnEventOf<'guardrail'> | undefined;
+/** Builds the guardrail event for the hits found at a stage. */
+declare function guardrailFromHits(stage: GuardrailStage, trust: TrustLevel, hits: GuardrailHit[], action?: GuardrailAction, provenance?: Provenance): TurnEventOf<'guardrail'> | undefined;
+/** The guardrail turn event, with the matched text kept or dropped. */
+declare function projectGuardrailTurnEvent(event: TurnEventOf<'guardrail'>, includeMatch: boolean): TurnEventOf<'guardrail'>;
+/** The turn event unchanged, or a guardrail one with the matched text kept or dropped. */
+declare function projectGuardrailTurnEvent(event: TurnEvent, includeMatch: boolean): TurnEvent;
+export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent };

package/esm/src/guardrails/events.js

@@ -0,0 +1,45 @@
+import { projectGuardrailEvent } from './hits.js';
+/** Wraps a guardrail event as a turn event. */
+function guardrailTurnEvent(guardrail) {
+    return { type: 'guardrail', guardrail };
+}
+/** `allow` yields nothing; `flag`, `redact`, and `block` all emit so hosts and traces can count hits. */
+function guardrailFromVerdict(stage, trust, verdict, provenance) {
+    if (verdict.action === 'allow') {
+        return undefined;
+    }
+    return guardrailTurnEvent({
+        stage,
+        trust,
+        action: verdict.action,
+        hits: verdict.hits,
+        ...(provenance ? { provenance } : {}),
+        ...(verdict.action === 'block' && verdict.errorInternal
+            ? { errorInternal: verdict.errorInternal }
+            : {}),
+    });
+}
+/** Builds the guardrail event for the hits found at a stage. */
+function guardrailFromHits(stage, trust, hits, action = 'redact', provenance) {
+    if (hits.length === 0) {
+        return undefined;
+    }
+    return guardrailTurnEvent({
+        stage,
+        trust,
+        action,
+        hits,
+        ...(provenance ? { provenance } : {}),
+    });
+}
+/** The turn event unchanged, or a guardrail one with the matched text kept or dropped. */
+function projectGuardrailTurnEvent(event, includeMatch) {
+    if (event.type !== 'guardrail') {
+        return event;
+    }
+    return {
+        ...event,
+        guardrail: projectGuardrailEvent(event.guardrail, includeMatch),
+    };
+}
+export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent };

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

@@ -0,0 +1,14 @@
+/**
+ * What a model is told when a reply a detector blocked is retried: for each detector that
+ * matched, its hint and, where a match may be repeated, what it matched. The retry is read at the
+ * `repair` boundary like any other text on its way to the model, so a secret quoted here meets
+ * the action the profile set there.
+ *
+ * @module
+ */
+import { type ResolvedDetect } from './detectors.js';
+import type { GuardrailHit } from './event-schemas.js';
+import { type LabelOverrides } from './labels.js';
+/** The rejection a retry carries for the `hits` that stopped a reply, a line for each rule among them. */
+declare function retryRejection(hits: readonly GuardrailHit[], detect: ResolvedDetect, labels?: LabelOverrides): string;
+export { retryRejection };

package/esm/src/guardrails/hints.js

@@ -0,0 +1,57 @@
+/**
+ * What a model is told when a reply a detector blocked is retried: for each detector that
+ * matched, its hint and, where a match may be repeated, what it matched. The retry is read at the
+ * `repair` boundary like any other text on its way to the model, so a secret quoted here meets
+ * the action the profile set there.
+ *
+ * @module
+ */
+import { isDetector } from './detectors.js';
+import { labelText } from './labels.js';
+import { DETECT_RULES, EGRESS_RULES } from './rules.js';
+/** The hint of what stops a reply besides a detector's match. */
+const OTHER_HINTS = {
+    [EGRESS_RULES.unscannable]: 'egress.hint_unscannable',
+    [EGRESS_RULES.providerToolLeak]: 'egress.hint_provider_tool_leak',
+};
+/** The rules whose match is the profile's own, and is never repeated. */
+const UNQUOTED = [DETECT_RULES.canary_leak, DETECT_RULES.prompt_leak];
+/** How many matches a detector's line quotes, and how much of each. */
+const MAX_QUOTED = 3;
+const MAX_QUOTE = 120;
+const DETECT_PREFIX = 'detect.';
+/** The hint of the rule `hit` reports: the profile's, or else the labels'. */
+function hintOf(hit, detect, labels) {
+    const other = OTHER_HINTS[hit.rule];
+    if (other)
+        return labelText(other, {}, labels);
+    const key = hit.rule.startsWith(DETECT_PREFIX) ? hit.rule.slice(DETECT_PREFIX.length) : hit.rule;
+    if (isDetector(key)) {
+        return detect.hints?.[key] ?? labelText(`detect.hint.${key}`, {}, labels);
+    }
+    const host = detect.host?.find(({ id }) => id === key);
+    const label = host?.label ?? hit.label ?? key;
+    return host?.hint ?? labelText('detect.hint.own', { label }, labels);
+}
+/** The matched text of `hits` a line may quote: each once, the first few, cut to length. */
+function quoted(hits) {
+    const matches = hits.flatMap(({ rule, match }) => match && !UNQUOTED.includes(rule) ? [match] : []);
+    return [...new Set(matches)]
+        .slice(0, MAX_QUOTED)
+        .map((match) => JSON.stringify(match.length > MAX_QUOTE ? match.slice(0, MAX_QUOTE) : match));
+}
+/** The rejection a retry carries for the `hits` that stopped a reply, a line for each rule among them. */
+function retryRejection(hits, detect, labels) {
+    const byRule = new Map();
+    for (const hit of hits)
+        byRule.set(hit.rule, [...(byRule.get(hit.rule) ?? []), hit]);
+    const lines = [...byRule.values()].map((found) => {
+        const hint = hintOf(found[0], detect, labels);
+        const matches = quoted(found);
+        return matches.length > 0
+            ? labelText('egress.rejection_found', { hint, matches: matches.join(', ') }, labels)
+            : hint;
+    });
+    return labelText('egress.rejection', { found: lines.join('\n') }, labels);
+}
+export { retryRejection };

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

@@ -0,0 +1,14 @@
+import type { GuardrailEvent, GuardrailHit, Severity } from './types.js';
+/** A canary leak. Never carries the live token, only a placeholder. */
+declare const CANARY_HIT: GuardrailHit;
+/** A prompt leak. Never carries the words: they are the private system instruction's. */
+declare const PROMPT_ECHO_HIT: GuardrailHit;
+/** A guardrail hit for a span of the text, with the matched text sliced from it. */
+declare function hitFromSpan(text: string, span: {
+    start: number;
+    end: number;
+    name?: string;
+}, rule: string, severity: Severity): GuardrailHit;
+/** `match` is the caught text itself, so hosts and traces get it only via `observability.include.guardrailMatchPreview`. */
+declare function projectGuardrailEvent(event: GuardrailEvent, includeMatch: boolean): GuardrailEvent;
+export { CANARY_HIT, hitFromSpan, PROMPT_ECHO_HIT, projectGuardrailEvent };

package/esm/src/guardrails/hits.js

@@ -0,0 +1,30 @@
+import { DETECT_RULES } from './rules.js';
+/** A canary leak. Never carries the live token, only a placeholder. */
+const CANARY_HIT = {
+    rule: DETECT_RULES.canary_leak,
+    severity: 'high',
+    match: '[canary]',
+};
+/** A prompt leak. Never carries the words: they are the private system instruction's. */
+const PROMPT_ECHO_HIT = { rule: DETECT_RULES.prompt_leak, severity: 'high' };
+/** A guardrail hit for a span of the text, with the matched text sliced from it. */
+function hitFromSpan(text, span, rule, severity) {
+    return {
+        rule,
+        severity,
+        span: { start: span.start, end: span.end },
+        match: text.slice(span.start, span.end),
+        ...(span.name === undefined ? {} : { pattern: span.name }),
+    };
+}
+/** `match` is the caught text itself, so hosts and traces get it only via `observability.include.guardrailMatchPreview`. */
+function projectGuardrailEvent(event, includeMatch) {
+    if (includeMatch) {
+        return event;
+    }
+    return {
+        ...event,
+        hits: event.hits.map(({ match: _match, ...hit }) => hit),
+    };
+}
+export { CANARY_HIT, hitFromSpan, PROMPT_ECHO_HIT, projectGuardrailEvent };