@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/guardrails/tool-result.js

@@ -1,14 +1,16 @@
-import { lexiconText } from './lexicon.js';
-import { detectionForTrust } from './policy.js';
-import { TOOL_RULES } from './rules.js';
-import { sanitizeText } from './sanitize.js';
-import { anySensitive } from './sensitive.js';
+import { mapStrings } from '../kernel/engine/tree.js';
+import { detectAt, detectEvent, detectReads, } from './detect-at.js';
+import { readValue } from './detect-reply.js';
+import { labelText } from './labels.js';
+import { DETECT_RULES, EGRESS_RULES, TOOL_RULES } from './rules.js';
 import { textForScan } from './serialize.js';
-import { advisoryLevel, directiveHits } from './tool-directives.js';
+import { advisoryLevel } from './tool-directives.js';
+/** The closing tag of the fence a tool result is wrapped in. */
 const TOOL_CLOSE = '</tool_data>';
 const TOOL_OPEN = '<tool_data';
 /** Origins whose bytes the host does not author and cannot vouch for. */
 const REMOTE_ORIGINS = new Set(['http', 'mcp', 'delegated']);
+/** True when the tool's bytes come from outside the host. */
 function isRemoteOrigin(origin) {
     return REMOTE_ORIGINS.has(origin);
 }
@@ -55,24 +57,24 @@ function stripToolFences(text) {
  * The origin is on the tag rather than in prose so a result cannot claim a
  * friendlier provenance than it has by writing one into its own body.
  */
-function wrapToolData(text, provenance, advisory = 'none', lexicon) {
-    const guidance = lexiconText('advisory.guidance', {}, lexicon).trim();
+function wrapToolData(text, provenance, advisory = 'none', labels) {
+    const guidance = labelText('advisory.guidance', {}, labels).trim();
     const attrs = `tool="${provenance.tool}" origin="${provenance.origin}"` +
         (advisory === 'none' ? '' : ` advisory="${advisory}"`);
     const notice = advisory === 'none'
         ? ''
-        : `${advisoryNotice(advisory, lexicon)}${guidance ? ` ${guidance}` : ''}\n`;
+        : `${advisoryNotice(advisory, labels)}${guidance ? ` ${guidance}` : ''}\n`;
     return `<${'tool_data'} ${attrs}>\n${notice}${stripToolFences(text)}\n${TOOL_CLOSE}`;
 }
 /**
  * Deliberately an observation, not an instruction: what the agent should do about
- * it is product behaviour, supplied by the host as lexicon `advisory.guidance`. Emitted
+ * it is product behaviour, supplied by the host as labels `advisory.guidance`. Emitted
  * only when signals fired, so it stays rare enough to carry weight — a warning on
  * every fetch is one the model learns to skip.
  */
-function advisoryNotice(advisory, lexicon) {
+function advisoryNotice(advisory, labels) {
     const key = advisory === 'high' ? 'advisory.notice_high' : 'advisory.notice_elevated';
-    return lexiconText(key, {}, lexicon);
+    return labelText(key, {}, labels);
 }
 /**
  * `finding` is the tool's summary and `data` its structured payload; both reach
@@ -88,88 +90,108 @@ function composeToolText(finding, data) {
     }
     return `${finding}\n${rendered.text}`;
 }
+const NOTHING_FOUND = { action: 'allow', hits: [] };
+/** `text` read at `boundary`, or passed as it is when the text crosses none. */
+function readAt(text, boundary, detect, scope) {
+    return boundary ? detectAt(text, boundary, detect, scope) : { ...NOTHING_FOUND, text };
+}
 /**
  * Local host tools are still detected — a host tool reading a database returns
  * data the host did not write — but only remote origins are fenced, because
  * fencing a local tool's output would change prompts hosts have already tuned.
+ * `boundary` is absent for text that crosses none: a provider builtin's, or a
+ * failure already read at its own boundary.
  */
-function guardToolResult(finding, data, provenance, policy, callableTools = [], lexicon) {
+function guardToolResult(finding, data, provenance, policy, boundary, callableTools = [], labels) {
     const composed = composeToolText(finding, data);
-    const options = detectionForTrust(policy, 'untrusted');
-    const redacted = sanitizeText(composed, options);
-    const changed = redacted !== composed;
-    // Directive detection runs on remote content only: a local tool's output is
-    // bytes the host's own code produced.
+    const detected = readAt(composed, boundary, policy.detect, { callable: callableTools });
+    const suspicious = detected.hits.filter(({ rule }) => rule === DETECT_RULES.tool_instructions);
     const remote = isRemoteOrigin(provenance.origin);
-    const suspicious = remote ? directiveHits(composed, callableTools) : [];
-    const advisory = advisoryLevel(suspicious);
-    const fenced = remote ? wrapToolData(redacted, provenance, advisory, lexicon) : redacted;
-    const hits = [
-        ...(changed ? [{ rule: TOOL_RULES.resultRedacted, severity: 'medium' }] : []),
-        ...suspicious,
-    ];
-    if (hits.length === 0) {
-        return { text: fenced };
-    }
-    return {
-        text: fenced,
-        ...(suspicious.length > 0 ? { suspicious } : {}),
-        event: {
+    const event = detected.action === 'allow'
+        ? undefined
+        : {
             stage: 'tool_result',
+            ...(boundary ? { boundary } : {}),
             trust: 'untrusted',
-            // Redaction changed the text; directive signals only annotate it.
-            action: changed ? 'redact' : 'flag',
-            hits,
+            action: detected.action,
+            hits: detected.hits,
             provenance,
-        },
+        };
+    const found = {
+        ...(suspicious.length > 0 ? { suspicious } : {}),
+        ...(event ? { event } : {}),
     };
+    if (detected.text === undefined)
+        return found;
+    const fenced = remote
+        ? wrapToolData(detected.text, provenance, advisoryLevel(suspicious.map(({ signal }) => signal)), labels)
+        : detected.text;
+    return { text: fenced, ...found };
 }
 /**
  * A remote server authors its own error strings, so an unguarded failure message
  * is the cleanest injection path across this boundary: it reaches the model
  * verbatim and is framed by the kernel as a system report.
  */
-function guardToolFailureText(message, provenance, policy) {
-    const options = detectionForTrust(policy, 'untrusted');
-    const redacted = sanitizeText(stripToolFences(message), options);
-    if (redacted === message) {
-        return { text: redacted };
-    }
+function guardToolFailureText(message, provenance, policy, boundary) {
+    const detected = readAt(stripToolFences(message), boundary, policy.detect);
+    const event = boundary ? detectEvent(boundary, detected, provenance) : undefined;
     return {
-        text: redacted,
-        event: {
-            stage: 'tool_result',
-            trust: 'untrusted',
-            action: 'redact',
-            hits: [{ rule: TOOL_RULES.failureRedacted, severity: 'medium' }],
-            provenance,
-        },
+        ...(detected.text === undefined ? {} : { text: detected.text }),
+        ...(event ? { event } : {}),
+    };
+}
+/**
+ * A call's output, error, artifacts, and trace reach the person on the turn's events, apart from
+ * what the model read back: the host's server forwards them to the browser as they are. Each is
+ * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
+ * untouched: what the model read is settled at `tool_output_<kind>`.
+ */
+function guardShownValue(value, provenance, policy, boundary) {
+    if (!boundary || value === undefined)
+        return { value };
+    const found = readValue(value, boundary, policy.detect);
+    const event = detectEvent(boundary, found, provenance);
+    return {
+        ...(found.action === 'block' ? {} : { value: found.value }),
+        ...(event ? { event } : {}),
     };
 }
 /**
  * Arguments are model-authored, so the risk is not instruction smuggling but
  * exfiltration: a credential lifted from context and posted outward as a
- * parameter. Detection reports rather than rewrites — silently altering a tool
- * argument would make the call succeed against something the model did not ask
- * for.
+ * parameter. The whole call is read as it will be sent; `redact` then replaces
+ * the match inside each string it sits in, so the tool is called with the
+ * placeholder. `scope` is what the detectors of what is the profile's own
+ * read of the turn: the canary, and its system instruction.
  */
-function inspectToolArguments(args, policy) {
-    if (!anySensitive(policy.redactSensitive)) {
-        return { action: 'allow' };
+function inspectToolArguments(args, provenance, policy, boundary, scope = {}) {
+    if (!(boundary && detectReads([boundary], policy.detect))) {
+        return { args };
     }
+    const stopped = (hits) => {
+        const event = detectEvent(boundary, { action: 'block', hits }, provenance);
+        return event ? { event } : {};
+    };
     const rendered = textForScan(args);
     if (rendered.unscannable) {
-        return { action: 'allow' };
-    }
-    const options = { sanitizeInput: false, redactSensitive: policy.redactSensitive };
-    if (sanitizeText(rendered.text, options) === rendered.text) {
-        return { action: 'allow' };
+        // why: Cannot inspect it, so cannot vouch for it. Fail closed.
+        return stopped([{ rule: EGRESS_RULES.unscannable, severity: 'high' }]);
     }
-    return {
-        action: 'flag',
-        hits: [{ rule: TOOL_RULES.sensitiveArgument, severity: 'high' }],
-    };
+    const detected = detectAt(rendered.text, boundary, policy.detect, scope);
+    if (detected.action === 'block')
+        return stopped(detected.hits);
+    const event = detectEvent(boundary, detected, provenance);
+    if (detected.action !== 'redact')
+        return { args, ...(event ? { event } : {}) };
+    const safe = mapStrings(args, (text) => detectAt(text, boundary, policy.detect, scope).text ?? '');
+    const left = detectAt(textForScan(safe).text, boundary, policy.detect, scope).action;
+    // why: A match in a key, or one that runs across values, has no string to replace: the tool is not called.
+    if (left === 'redact' || left === 'block')
+        return stopped(detected.hits);
+    return { args: safe, ...(event ? { event } : {}) };
 }
+/** The guardrail event for a tool call verdict, or `undefined` when it was allowed. */
 function toolCallEvent(verdict, provenance) {
     if (verdict.action === 'allow') {
         return undefined;
@@ -195,9 +217,11 @@ function recordTaint(taint, provenance, suspicious = []) {
     }
     return { sources: [...sources, provenance], suspicious: [...prior, ...suspicious] };
 }
+/** True when the turn has read content from outside the host. */
 function isTainted(taint) {
     return (taint?.sources.length ?? 0) > 0;
 }
+/** True when something the turn read looked like instructions. */
 function isSuspicious(taint) {
     return (taint?.suspicious.length ?? 0) > 0;
 }
@@ -217,7 +241,7 @@ const GATE_RANK = {
  * `block` says the profile asked for it to be refused. Reporting happens whether
  * or not enforcement is configured, so the risk is visible before a host opts in.
  */
-function checkTaintGate(taint, access, policy, lexicon) {
+function checkTaintGate(taint, access, policy, labels) {
     if (!isTainted(taint)) {
         return { action: 'allow' };
     }
@@ -232,17 +256,17 @@ function checkTaintGate(taint, access, policy, lexicon) {
             severity: 'high',
         },
     ];
-    // Gated on origin alone. Whether the content looked directive changes the rule
+    // why: Gated on origin alone. Whether the content looked directive changes the rule
     // reported, never whether the call is refused.
     if (rank < GATE_RANK[policy.taint?.afterRemoteRead ?? 'off']) {
         return { action: 'flag', hits };
     }
     const read = taint?.sources.map((s) => s.tool).join(', ') ?? '';
-    const reason = lexiconText(suspicious ? 'taint.reason_steered' : 'taint.reason_tainted', {}, lexicon);
+    const reason = labelText(suspicious ? 'taint.reason_steered' : 'taint.reason_tainted', {}, labels);
     return {
         action: 'block',
         hits,
-        rejection: lexiconText('taint.blocked', { access, sources: read, reason }, lexicon),
+        rejection: labelText('taint.blocked', { access, sources: read, reason }, labels),
     };
 }
-export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };
+export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };

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

@@ -1,25 +1,47 @@
-import type { EgressChecks } from './egress.js';
+import type { DetectSpec, ResolvedAllow, ResolvedDetect } from './detectors.js';
 import type { GivenUrls } from './egress-urls.js';
 import type { GuardrailEvent, GuardrailHit, Provenance } from './event-schemas.js';
-import type { LexiconOverrides } from './lexicon.js';
-import type { SensitiveGroups, SensitiveSelection } from './sensitive.js';
+import type { LabelOverrides } from './labels.js';
+import type { OwnTools } from './tool-leak.js';
 export type { GuardrailEvent, GuardrailHit, Provenance };
 /**
- * - `trusted` — author-time profile text (`identity.system`). Sensitive redaction
- *   only; injection redaction would mangle the host's own instructions.
+ * - `trusted` — author-time profile text (`identity.system`). Left verbatim: no
+ *   injection or sensitive redaction, which would mangle the host's own instructions.
  * - `assembled` — host-built per turn (`req.system`). Interpolates retrieval and
  *   user data, so it is permeable and takes full detection.
  * - `untrusted` — user input, tool results, attachments, delegated agents.
  */
 export declare const TRUST_LEVELS: readonly ["trusted", "assembled", "untrusted"];
+/** One of {@linkcode TRUST_LEVELS}. */
 export type TrustLevel = (typeof TRUST_LEVELS)[number];
+/** The points a guardrail can run: input, history, system, attachments, tool calls, and results, output, thoughts, network, live audio, and traces. */
 export declare const GUARDRAIL_STAGES: readonly ["input", "history", "system", "attachment", "tool_call", "tool_result", "output_delta", "output_final", "thought", "network", "live_inbound", "live_outbound", "trace"];
+/** One of {@linkcode GUARDRAIL_STAGES}. */
 export type GuardrailStage = (typeof GUARDRAIL_STAGES)[number];
-/** Does not decide what happens next; that is `onBlock`. */
+/** Does not decide what happens next; that is `blockedReply`. */
 export declare const SEVERITIES: readonly ["info", "low", "medium", "high"];
+/** One of {@linkcode SEVERITIES}. */
 export type Severity = (typeof SEVERITIES)[number];
-export declare const EGRESS_ON_BLOCK: readonly ["reject_to_agent", "refuse_to_user"];
-export type EgressOnBlock = (typeof EGRESS_ON_BLOCK)[number];
+/** What follows a blocked reply: the model rewrites it, or the user reads a refusal. */
+export declare const BLOCKED_REPLY_ON_BLOCK: readonly ["retry", "refuse"];
+/** One of {@linkcode BLOCKED_REPLY_ON_BLOCK}. */
+export type BlockedReplyOnBlock = (typeof BLOCKED_REPLY_ON_BLOCK)[number];
+/** What happens once a detector blocks a reply. */
+export interface BlockedReplySpec {
+    /**
+     * `retry` (the default) tells the model what blocked the reply and has it write another;
+     * `refuse` sends the user the labels' `egress.refusal` in its place, or ends the part
+     * they already have with `egress.refusal_cut`.
+     */
+    onBlock?: BlockedReplyOnBlock;
+    /**
+     * Under `retry`, how many times the model may rewrite a blocked reply (default 1). Once they
+     * are spent the reply is withheld and the turn ends in a `safety` error.
+     */
+    maxRetries?: number;
+}
+/** {@linkcode BlockedReplySpec} with its defaults applied. */
+export type ResolvedBlockedReply = Required<BlockedReplySpec>;
 /**
  * A discriminated union so a new variant fails every unhandled `switch` at
  * compile time rather than falling through at runtime.
@@ -37,8 +59,8 @@ export type Verdict = {
     action: 'block';
     hits: GuardrailHit[];
     /**
-     * Sent to the model on a repair turn when `onBlock` is `reject_to_agent`.
-     * With `refuse_to_user` the user reads the lexicon's `egress.refusal`.
+     * Sent to the model on a repair turn when `blockedReply.onBlock` is `retry`.
+     * With `refuse` the user reads the labels' `egress.refusal`.
      */
     rejection: string;
     /**
@@ -48,6 +70,7 @@ export type Verdict = {
     errorInternal?: string;
 };
 export declare const GUARDRAIL_ACTIONS: readonly ["allow", "redact", "flag", "block"];
+/** One of {@linkcode GUARDRAIL_ACTIONS}. */
 export type GuardrailAction = (typeof GUARDRAIL_ACTIONS)[number];
 /**
  * `local` is host TypeScript the profile registered; `http` and `mcp` are remote
@@ -56,6 +79,7 @@ export type GuardrailAction = (typeof GUARDRAIL_ACTIONS)[number];
  * reads as authoritative, which is why depth is tracked separately.
  */
 export declare const TOOL_ORIGINS: readonly ["local", "builtin", "http", "mcp", "delegated"];
+/** One of {@linkcode TOOL_ORIGINS}. */
 export type ToolOrigin = (typeof TOOL_ORIGINS)[number];
 /**
  * Once a turn has read attacker-influenceable bytes, a later tool call is a
@@ -78,9 +102,16 @@ export interface TurnTaint {
  * named a tool the model can call, or several signals agreed.
  */
 export declare const ADVISORY_LEVELS: readonly ["none", "elevated", "high"];
+/** One of {@linkcode ADVISORY_LEVELS}. */
 export type AdvisoryLevel = (typeof ADVISORY_LEVELS)[number];
+/** Which tool access levels refuse to run once a turn has read untrusted content. */
 export declare const TAINT_GATES: readonly ["off", "destructive", "write"];
+/** One of {@linkcode TAINT_GATES}. */
 export type TaintGate = (typeof TAINT_GATES)[number];
+/** What happens to a tool call that sends to a destination only remote content named. */
+export declare const DESTINATION_GATES: readonly ["off", "confirm", "block"];
+/** One of {@linkcode DESTINATION_GATES}. */
+export type DestinationGate = (typeof DESTINATION_GATES)[number];
 /**
  * Enforcement is opt-in: every remote read is reported, but refusing tool calls
  * changes what working agents may do, so the host declares which access levels
@@ -95,15 +126,12 @@ export type TaintGate = (typeof TAINT_GATES)[number];
  */
 export interface TaintGuardrailSpec {
     /**
-     * - `off` (default) — report only.
-     * - `destructive` — refuse hard-to-undo calls.
-     * - `write` — refuse those and any state-changing call.
-     *
      * Stated as a capability threshold rather than a list of tool `access` values so
      * the guardrail vocabulary stays independent of the tool registry; the kernel
      * maps a tool's declared access onto it.
      */
     afterRemoteRead?: TaintGate;
+    remoteDestination?: DestinationGate;
 }
 /** Facts a check may read. Deliberately excludes the full profile. */
 export interface GuardrailContext {
@@ -111,10 +139,16 @@ export interface GuardrailContext {
     trust: TrustLevel;
     profileId: string;
     canary?: string;
+    /**
+     * The canary was in what the model was given besides the system prompt (its
+     * input, the user's and tools' history): a reply repeating it is not a
+     * leak. It still binds prompt echo.
+     */
+    canaryGiven?: boolean;
     /**
      * The private stretches of the system prompt as sent (`BoundSystem.private`),
-     * when the profile guards it against echo (`guardrails.promptEcho`): a reply
-     * repeating one is a leak.
+     * while the `prompt_leak` detector reads somewhere: text repeating one is a
+     * leak.
      */
     privateSystem?: readonly string[];
     role?: string;
@@ -128,41 +162,23 @@ export interface GuardrailContext {
      * server. The kernel adds to them as the model is given more. Unset: none.
      */
     givenUrls?: GivenUrls;
-    /** The profile's lexicon, so a policy's rejection reads in the host's wording. */
-    lexicon?: LexiconOverrides;
+    /** The names of the profile's tools and of their parameters, for `tool_leak`. Unset: none. */
+    ownTools?: OwnTools;
+    /** The profile's labels, so a rejection reads in the host's wording. */
+    labels?: LabelOverrides;
 }
 /**
  * Structured output travels alongside text so a profile with `outputs.structured`
- * is not invisible to its own egress policy.
+ * has it read by the detectors too.
  */
 export interface OutboundPayload {
     /** Concatenated user-visible text for this attempt. */
     text: string;
     structured?: unknown;
 }
-export type EgressEnforcer = (payload: OutboundPayload, context: GuardrailContext) => Verdict | Promise<Verdict>;
-/** `enforce` or `checks`, never both. */
-export interface ProfileEgressSpec {
-    /** The host's own check. */
-    enforce?: EgressEnforcer;
-    /**
-     * The bundled policy's checks: `true` runs each at its default, `false` none
-     * but the system-prompt leak checks, and an object switches the ones it names.
-     */
-    checks?: boolean | EgressChecks;
-    onBlock?: EgressOnBlock;
-    maxRetries?: number;
-    /**
-     * For a host `enforce` only: characters the progressive gate holds back so
-     * `enforce` sees a match split across stream chunks before any of it is
-     * released (default `DEFAULT_HOLDBACK`, 256; on Live `LIVE_DEFAULT_HOLDBACK`,
-     * 96). The bundled `standardEgressEnforce` holds exactly what could still
-     * become a match, and setting this with it is a profile error.
-     */
-    holdback?: number;
-}
+/** Which hosts and networks a tool's requests may reach. */
 export interface NetworkGuardrailSpec {
-    /** Allows localhost, loopback and private subnets (local dev and testing). Default false. */
+    /** Allows localhost, loopback, and private subnets (local dev and testing). Default false. */
     allowPrivateNetworks?: boolean;
     /** Hostnames or IP addresses permitted regardless of private subnet status. */
     allowedHosts?: string[];
@@ -176,30 +192,20 @@ export interface NetworkGuardrailSpec {
 export interface QuotaGuardrailSpec {
     perDay: number;
 }
+/** The guardrails a profile turns on, each with its own settings. */
 export interface ProfileGuardrailsSpec {
     /** Omitted means quota enforcement is not configured. */
     quota?: QuotaGuardrailSpec;
     /**
-     * Mint a per-turn canary into the system prompt. Default true. The note
-     * that binds it is the lexicon's `canary.bind_note` (the profile's `lexicon`
-     * may replace it).
+     * What the kernel does when a detector finds a match, per boundary: one action
+     * for everything, or a rule for the detectors it names. Anything left out keeps
+     * its default (`DETECT_DEFAULTS`). A canary is bound into the system prompt
+     * while `canary_leak` is above `ignore` somewhere; the note that binds it is
+     * the labels' `canary.bind_note` (the profile's `labels` may replace it).
      */
-    canary?: boolean;
-    /**
-     * With the canary on, also treat a reply that repeats `PROMPT_ECHO_WORDS`
-     * (12) consecutive words of the system prompt as a leak: the dump the token
-     * alone cannot see. Default true; set false when the prompt holds text the
-     * agent is meant to quote word for word.
-     */
-    promptEcho?: boolean;
-    sanitizeInput?: boolean;
-    /**
-     * Redact sensitive data from untrusted text before the model reads it:
-     * `true` (the default) every group, `false` none, an object the groups it
-     * switches, the rest on (`ids`, `financial`, `network`, `credentials`).
-     */
-    redactSensitive?: SensitiveSelection;
-    egress?: ProfileEgressSpec;
+    detect?: DetectSpec;
+    /** What happens once a reply is blocked. Left out, the model rewrites it once. */
+    blockedReply?: BlockedReplySpec;
     network?: NetworkGuardrailSpec;
     taint?: TaintGuardrailSpec;
 }
@@ -208,10 +214,15 @@ export type DecisionDisclosureVerdict = Extract<Verdict, {
     action: 'allow' | 'block';
 }>;
 export type DecisionDisclosureEnforcer = (state: unknown, context: {
-    destination: 'typesafe' | 'openrouter';
+    destination: string;
     profileId: string;
     model: string;
     questionIds: string[];
+    /** The images the call sends with the state, by reference. Absent: none. */
+    assets?: Record<string, {
+        mimeType: 'image/png' | 'image/jpeg';
+        data: string;
+    }>;
 }) => DecisionDisclosureVerdict | Promise<DecisionDisclosureVerdict>;
 /**
  * Keeps the shared guardrail vocabulary structurally compatible while the
@@ -223,20 +234,17 @@ export interface DecisionGuardrailsSpec extends Partial<ProfileGuardrailsSpec> {
     };
 }
 /** The guardrail field names a `host` profile may set. */
-export declare const HOST_GUARDRAIL_FIELDS: readonly ["sanitizeInput", "redactSensitive", "network"];
+export declare const HOST_GUARDRAIL_FIELDS: readonly ["detect", "network"];
 /** The guardrails that fire on the `invokeTool` path; the rest guard a model turn. */
 export type HostGuardrailsSpec = Pick<ProfileGuardrailsSpec, (typeof HOST_GUARDRAIL_FIELDS)[number]>;
+/** A profile's guardrails after defaults are applied. */
 export interface ResolvedGuardrailPolicy {
-    sanitizeInput: boolean;
-    redactSensitive: SensitiveGroups;
-    canary: boolean;
-    promptEcho: boolean;
-    /** `checks` resolved to the bundled policy's `enforce`. */
-    egress?: ResolvedEgressSpec;
+    /** Every detector's action at every boundary. */
+    detect: ResolvedDetect;
+    /** What `ungiven_images` and `ungiven_links` let through besides the given URLs. */
+    allow: ResolvedAllow;
+    blockedReply: ResolvedBlockedReply;
     network?: NetworkGuardrailSpec;
     quota?: QuotaGuardrailSpec;
     taint?: TaintGuardrailSpec;
 }
-export type ResolvedEgressSpec = Omit<ProfileEgressSpec, 'enforce' | 'checks'> & {
-    enforce: EgressEnforcer;
-};

package/esm/src/guardrails/types.js

@@ -1,13 +1,14 @@
-// Must not import from `src/kernel/`: the kernel type-imports `ProfileGuardrailsSpec`, and that edge
+// invariant: Must not import from `src/kernel/`: the kernel type-imports `ProfileGuardrailsSpec`, and that edge
 // stays one-directional. Other modules under `src/guardrails/` may import kernel types.
 /**
- * - `trusted` — author-time profile text (`identity.system`). Sensitive redaction
- *   only; injection redaction would mangle the host's own instructions.
+ * - `trusted` — author-time profile text (`identity.system`). Left verbatim: no
+ *   injection or sensitive redaction, which would mangle the host's own instructions.
  * - `assembled` — host-built per turn (`req.system`). Interpolates retrieval and
  *   user data, so it is permeable and takes full detection.
  * - `untrusted` — user input, tool results, attachments, delegated agents.
  */
 export const TRUST_LEVELS = ['trusted', 'assembled', 'untrusted'];
+/** The points a guardrail can run: input, history, system, attachments, tool calls, and results, output, thoughts, network, live audio, and traces. */
 export const GUARDRAIL_STAGES = [
     'input',
     'history',
@@ -23,9 +24,10 @@ export const GUARDRAIL_STAGES = [
     'live_outbound',
     'trace',
 ];
-/** Does not decide what happens next; that is `onBlock`. */
+/** Does not decide what happens next; that is `blockedReply`. */
 export const SEVERITIES = ['info', 'low', 'medium', 'high'];
-export const EGRESS_ON_BLOCK = ['reject_to_agent', 'refuse_to_user'];
+/** What follows a blocked reply: the model rewrites it, or the user reads a refusal. */
+export const BLOCKED_REPLY_ON_BLOCK = ['retry', 'refuse'];
 export const GUARDRAIL_ACTIONS = [
     'allow',
     'redact',
@@ -45,10 +47,12 @@ export const TOOL_ORIGINS = ['local', 'builtin', 'http', 'mcp', 'delegated'];
  * named a tool the model can call, or several signals agreed.
  */
 export const ADVISORY_LEVELS = ['none', 'elevated', 'high'];
+/** Which tool access levels refuse to run once a turn has read untrusted content. */
 export const TAINT_GATES = ['off', 'destructive', 'write'];
+/** What happens to a tool call that sends to a destination only remote content named. */
+export const DESTINATION_GATES = ['off', 'confirm', 'block'];
 /** The guardrail field names a `host` profile may set. */
 export const HOST_GUARDRAIL_FIELDS = [
-    'sanitizeInput',
-    'redactSensitive',
+    'detect',
     'network',
 ];

package/esm/src/host/client-turn.d.ts

@@ -1,9 +1,36 @@
+import { type ErrorCopies, type ErrorKind } from '../guardrails/error.js';
+import type { LabelOverrides } from '../guardrails/labels.js';
 import type { TurnEvent } from '../kernel/types.js';
+/** Options for `forClient` and `clientError`: who reads the copy, and whether evidence keeps its provider-native payload. */
 export interface ClientTurnOptions {
     /** Keep provider-native payloads on `evidence` events. Default: false; parsed fields remain. */
     includeEvidenceRaw?: boolean;
+    /**
+     * Who reads the copy. A `'visitor'` (the default) reads the profile's wording, and every
+     * builder-only diagnostic is stripped. A `'builder'` is whoever builds the app, on their own
+     * machine and keys, as in a local development tool: a failed turn, an ended session, and a tool
+     * call's failure read their raw reason in place of the profile's wording, and builder-only
+     * diagnostics stay. Never for a page visitors reach.
+     */
+    reader?: 'visitor' | 'builder';
 }
-/** Strips host-only diagnostics, so the copy is safe to forward to browsers or end-user SSE. */
+/**
+ * The copy of an event its reader may have. For a visitor (the default) host-only diagnostics are
+ * stripped, so the copy is safe to forward to browsers or end-user SSE.
+ */
 declare function forClient(event: TurnEvent, options?: ClientTurnOptions): TurnEvent;
+/** `forClient` over a list of events. */
 declare function forClientEvents(events: TurnEvent[], options?: ClientTurnOptions): TurnEvent[];
-export { forClient, forClientEvents };
+/** A failure's wording and kind as a client reads them: the body of an error reply or line. */
+type ClientError = {
+    error: string;
+    errorKind: ErrorKind;
+    errorCopy?: ErrorCopies;
+};
+/**
+ * A caught failure as its reader may have it, by the same rule as `forClient`: the profile's
+ * wording (pass its `labels`) for a visitor, the raw diagnostic for a builder.
+ */
+declare function clientError(err: unknown, labels?: LabelOverrides, options?: ClientTurnOptions): ClientError;
+export type { ClientError };
+export { clientError, forClient, forClientEvents };