@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,248 @@
+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 { textForScan } from './serialize.js';
+import { advisoryLevel, directiveHits } from './tool-directives.js';
+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']);
+function isRemoteOrigin(origin) {
+    return REMOTE_ORIGINS.has(origin);
+}
+/**
+ * Strip fence markers a tool result tried to forge before wrapping it.
+ * Linear scan — avoids polynomial regex on forged `<tool_data…>` runs.
+ */
+function stripToolFences(text) {
+    const lower = text.toLowerCase();
+    let out = '';
+    let i = 0;
+    while (i < text.length) {
+        const openAt = lower.indexOf(TOOL_OPEN, i);
+        const closeAt = lower.indexOf(TOOL_CLOSE, i);
+        let next = -1;
+        let kind = null;
+        if (openAt >= 0 && (closeAt < 0 || openAt <= closeAt)) {
+            next = openAt;
+            kind = 'open';
+        }
+        else if (closeAt >= 0) {
+            next = closeAt;
+            kind = 'close';
+        }
+        if (next < 0 || kind === null) {
+            out += text.slice(i);
+            break;
+        }
+        out += text.slice(i, next);
+        if (kind === 'close') {
+            i = next + TOOL_CLOSE.length;
+            continue;
+        }
+        const gt = text.indexOf('>', next + TOOL_OPEN.length);
+        if (gt < 0) {
+            out += text.slice(next);
+            break;
+        }
+        i = gt + 1;
+    }
+    return out;
+}
+/**
+ * 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();
+    const attrs = `tool="${provenance.tool}" origin="${provenance.origin}"` +
+        (advisory === 'none' ? '' : ` advisory="${advisory}"`);
+    const notice = advisory === 'none'
+        ? ''
+        : `${advisoryNotice(advisory, lexicon)}${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
+ * 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) {
+    const key = advisory === 'high' ? 'advisory.notice_high' : 'advisory.notice_elevated';
+    return lexiconText(key, {}, lexicon);
+}
+/**
+ * `finding` is the tool's summary and `data` its structured payload; both reach
+ * the model, so both are guarded together rather than only the prose half.
+ */
+function composeToolText(finding, data) {
+    if (data === undefined) {
+        return finding;
+    }
+    const rendered = textForScan(data);
+    if (rendered.unscannable) {
+        return finding;
+    }
+    return `${finding}\n${rendered.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.
+ */
+function guardToolResult(finding, data, provenance, policy, callableTools = [], lexicon) {
+    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 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: {
+            stage: 'tool_result',
+            trust: 'untrusted',
+            // Redaction changed the text; directive signals only annotate it.
+            action: changed ? 'redact' : 'flag',
+            hits,
+            provenance,
+        },
+    };
+}
+/**
+ * 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 };
+    }
+    return {
+        text: redacted,
+        event: {
+            stage: 'tool_result',
+            trust: 'untrusted',
+            action: 'redact',
+            hits: [{ rule: TOOL_RULES.failureRedacted, severity: 'medium' }],
+            provenance,
+        },
+    };
+}
+/**
+ * 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.
+ */
+function inspectToolArguments(args, policy) {
+    if (!anySensitive(policy.redactSensitive)) {
+        return { action: 'allow' };
+    }
+    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' };
+    }
+    return {
+        action: 'flag',
+        hits: [{ rule: TOOL_RULES.sensitiveArgument, severity: 'high' }],
+    };
+}
+function toolCallEvent(verdict, provenance) {
+    if (verdict.action === 'allow') {
+        return undefined;
+    }
+    return {
+        stage: 'tool_call',
+        trust: 'untrusted',
+        action: verdict.action,
+        hits: verdict.hits,
+        provenance,
+    };
+}
+/**
+ * Only remote origins taint: a local host tool returns bytes the host's own code
+ * produced, and treating those as attacker-influenceable would make the gate
+ * useless in practice.
+ */
+function recordTaint(taint, provenance, suspicious = []) {
+    const sources = taint?.sources ?? [];
+    const prior = taint?.suspicious ?? [];
+    if (!isRemoteOrigin(provenance.origin)) {
+        return { sources, suspicious: prior };
+    }
+    return { sources: [...sources, provenance], suspicious: [...prior, ...suspicious] };
+}
+function isTainted(taint) {
+    return (taint?.sources.length ?? 0) > 0;
+}
+function isSuspicious(taint) {
+    return (taint?.suspicious.length ?? 0) > 0;
+}
+/** Capability rank, so a single threshold can express "this and anything worse". */
+const CAPABILITY_RANK = {
+    'read-only': 0,
+    'read-write': 1,
+    destructive: 2,
+};
+const GATE_RANK = {
+    off: Number.POSITIVE_INFINITY,
+    destructive: 2,
+    write: 1,
+};
+/**
+ * A `flag` says the call is happening on a tainted turn and is worth recording; a
+ * `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) {
+    if (!isTainted(taint)) {
+        return { action: 'allow' };
+    }
+    const rank = CAPABILITY_RANK[access] ?? 0;
+    if (rank === 0) {
+        return { action: 'allow' };
+    }
+    const suspicious = isSuspicious(taint);
+    const hits = [
+        {
+            rule: suspicious ? TOOL_RULES.steeredTurn : TOOL_RULES.taintedTurn,
+            severity: 'high',
+        },
+    ];
+    // 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);
+    return {
+        action: 'block',
+        hits,
+        rejection: lexiconText('taint.blocked', { access, sources: read, reason }, lexicon),
+    };
+}
+export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };

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

@@ -0,0 +1,242 @@
+import type { EgressChecks } from './egress.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';
+export type { GuardrailEvent, GuardrailHit, Provenance };
+/**
+ * - `trusted` — author-time profile text (`identity.system`). Sensitive redaction
+ *   only; injection redaction 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"];
+export type TrustLevel = (typeof TRUST_LEVELS)[number];
+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"];
+export type GuardrailStage = (typeof GUARDRAIL_STAGES)[number];
+/** Does not decide what happens next; that is `onBlock`. */
+export declare const SEVERITIES: readonly ["info", "low", "medium", "high"];
+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];
+/**
+ * A discriminated union so a new variant fails every unhandled `switch` at
+ * compile time rather than falling through at runtime.
+ */
+export type Verdict = {
+    action: 'allow';
+} | {
+    action: 'redact';
+    text: string;
+    hits: GuardrailHit[];
+} | {
+    action: 'flag';
+    hits: GuardrailHit[];
+} | {
+    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`.
+     */
+    rejection: string;
+    /**
+     * Why the check blocked, for the builder only: it reaches the host and the
+     * trace (content-gated), never the model or a client (`forClient`).
+     */
+    errorInternal?: string;
+};
+export declare const GUARDRAIL_ACTIONS: readonly ["allow", "redact", "flag", "block"];
+export type GuardrailAction = (typeof GUARDRAIL_ACTIONS)[number];
+/**
+ * `local` is host TypeScript the profile registered; `http` and `mcp` are remote
+ * services whose bytes the host does not control. `delegated` is another agent
+ * answering through the tool boundary — its output is model-generated prose that
+ * reads as authoritative, which is why depth is tracked separately.
+ */
+export declare const TOOL_ORIGINS: readonly ["local", "builtin", "http", "mcp", "delegated"];
+export type ToolOrigin = (typeof TOOL_ORIGINS)[number];
+/**
+ * Once a turn has read attacker-influenceable bytes, a later tool call is a
+ * confused-deputy risk: the content can ask the agent to act, and the agent has
+ * authority the content does not. Sources are kept in order so a policy can reason
+ * about depth as well as presence.
+ */
+export interface TurnTaint {
+    sources: Provenance[];
+    /**
+     * Separates "read something remote" from "read something that tried to steer
+     * me". The second is far rarer, so a gate keyed on it refuses far less
+     * legitimate work.
+     */
+    suspicious: GuardrailHit[];
+}
+/**
+ * Not a probability: there is no calibrated model behind it. `elevated` means one
+ * directive signal alongside an external destination; `high` means the content
+ * named a tool the model can call, or several signals agreed.
+ */
+export declare const ADVISORY_LEVELS: readonly ["none", "elevated", "high"];
+export type AdvisoryLevel = (typeof ADVISORY_LEVELS)[number];
+export declare const TAINT_GATES: readonly ["off", "destructive", "write"];
+export type TaintGate = (typeof TAINT_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
+ * to gate rather than having the kernel guess.
+ *
+ * Only structural facts gate tool calls. Content signals from `tool-directives.ts` deliberately have no gate here. They
+ * are pattern matches with no measured precision, and refusing a tool call on an
+ * unpredictable signal makes an agent unreliable rather than safe — the failure is
+ * invisible to the user and looks like the agent being stupid. Those signals
+ * annotate the fence and raise telemetry; the model still gets to decide, and the
+ * host still gets to see.
+ */
+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;
+}
+/** Facts a check may read. Deliberately excludes the full profile. */
+export interface GuardrailContext {
+    stage: GuardrailStage;
+    trust: TrustLevel;
+    profileId: string;
+    canary?: string;
+    /**
+     * 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.
+     */
+    privateSystem?: readonly string[];
+    role?: string;
+    slots?: Record<string, string>;
+    /** Set on tool-shaped stages; absent for user and system text. */
+    provenance?: Provenance;
+    /**
+     * Canonical absolute URLs in what the model was given this turn or session:
+     * the system prompt, the user's input and history, and apart, tool results.
+     * An image or link in the reply to any other URL can carry data to its
+     * 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;
+}
+/**
+ * Structured output travels alongside text so a profile with `outputs.structured`
+ * is not invisible to its own egress policy.
+ */
+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;
+}
+export interface NetworkGuardrailSpec {
+    /** 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[];
+    /**
+     * Allowed URL schemes. Defaults to `['https']`, or `['http', 'https']` when
+     * `allowPrivateNetworks` is set.
+     */
+    allowedSchemes?: string[];
+}
+/** Optional daily turn quota consumed by host HTTP middleware. */
+export interface QuotaGuardrailSpec {
+    perDay: number;
+}
+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).
+     */
+    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;
+    network?: NetworkGuardrailSpec;
+    taint?: TaintGuardrailSpec;
+}
+/** Pre-dispatch policy for structured state leaving a decision profile. */
+export type DecisionDisclosureVerdict = Extract<Verdict, {
+    action: 'allow' | 'block';
+}>;
+export type DecisionDisclosureEnforcer = (state: unknown, context: {
+    destination: 'typesafe' | 'openrouter';
+    profileId: string;
+    model: string;
+    questionIds: string[];
+}) => DecisionDisclosureVerdict | Promise<DecisionDisclosureVerdict>;
+/**
+ * Keeps the shared guardrail vocabulary structurally compatible while the
+ * decision registry rejects every inherited field as inert in this release.
+ */
+export interface DecisionGuardrailsSpec extends Partial<ProfileGuardrailsSpec> {
+    disclosure?: {
+        enforce: DecisionDisclosureEnforcer;
+    };
+}
+/** The guardrail field names a `host` profile may set. */
+export declare const HOST_GUARDRAIL_FIELDS: readonly ["sanitizeInput", "redactSensitive", "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]>;
+export interface ResolvedGuardrailPolicy {
+    sanitizeInput: boolean;
+    redactSensitive: SensitiveGroups;
+    canary: boolean;
+    promptEcho: boolean;
+    /** `checks` resolved to the bundled policy's `enforce`. */
+    egress?: ResolvedEgressSpec;
+    network?: NetworkGuardrailSpec;
+    quota?: QuotaGuardrailSpec;
+    taint?: TaintGuardrailSpec;
+}
+export type ResolvedEgressSpec = Omit<ProfileEgressSpec, 'enforce' | 'checks'> & {
+    enforce: EgressEnforcer;
+};

package/esm/src/guardrails/types.js

@@ -0,0 +1,54 @@
+// 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.
+ * - `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'];
+export const GUARDRAIL_STAGES = [
+    'input',
+    'history',
+    'system',
+    'attachment',
+    'tool_call',
+    'tool_result',
+    'output_delta',
+    'output_final',
+    'thought',
+    'network',
+    'live_inbound',
+    'live_outbound',
+    'trace',
+];
+/** Does not decide what happens next; that is `onBlock`. */
+export const SEVERITIES = ['info', 'low', 'medium', 'high'];
+export const EGRESS_ON_BLOCK = ['reject_to_agent', 'refuse_to_user'];
+export const GUARDRAIL_ACTIONS = [
+    'allow',
+    'redact',
+    'flag',
+    'block',
+];
+/**
+ * `local` is host TypeScript the profile registered; `http` and `mcp` are remote
+ * services whose bytes the host does not control. `delegated` is another agent
+ * answering through the tool boundary — its output is model-generated prose that
+ * reads as authoritative, which is why depth is tracked separately.
+ */
+export const TOOL_ORIGINS = ['local', 'builtin', 'http', 'mcp', 'delegated'];
+/**
+ * Not a probability: there is no calibrated model behind it. `elevated` means one
+ * directive signal alongside an external destination; `high` means the content
+ * named a tool the model can call, or several signals agreed.
+ */
+export const ADVISORY_LEVELS = ['none', 'elevated', 'high'];
+export const TAINT_GATES = ['off', 'destructive', 'write'];
+/** The guardrail field names a `host` profile may set. */
+export const HOST_GUARDRAIL_FIELDS = [
+    'sanitizeInput',
+    'redactSensitive',
+    'network',
+];

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

@@ -0,0 +1,9 @@
+import type { TurnEvent } from '../kernel/types.js';
+export interface ClientTurnOptions {
+    /** Keep provider-native payloads on `evidence` events. Default: false; parsed fields remain. */
+    includeEvidenceRaw?: boolean;
+}
+/** Strips host-only diagnostics, so the copy is safe to forward to browsers or end-user SSE. */
+declare function forClient(event: TurnEvent, options?: ClientTurnOptions): TurnEvent;
+declare function forClientEvents(events: TurnEvent[], options?: ClientTurnOptions): TurnEvent[];
+export { forClient, forClientEvents };

package/esm/src/host/client-turn.js

@@ -0,0 +1,38 @@
+import { projectGuardrailTurnEvent } from '../guardrails/events.js';
+/** Raw diagnostics ride on error events, an ended session's close, and a tool call's failure. */
+function stripErrorInternal(event) {
+    if ((event.type !== 'error' && event.type !== 'session' && event.type !== 'tool') ||
+        event.errorInternal === undefined) {
+        return event;
+    }
+    const { errorInternal: _internal, ...rest } = event;
+    return rest;
+}
+function stripGuardrailInternal(event) {
+    if (event.type !== 'guardrail' || !event.guardrail?.errorInternal) {
+        return event;
+    }
+    const { errorInternal: _internal, ...guardrail } = event.guardrail;
+    return { ...event, guardrail };
+}
+function stripEvidenceRaw(event) {
+    if (event.type !== 'evidence' || !event.evidence?.raw) {
+        return event;
+    }
+    const { raw: _raw, ...evidence } = event.evidence;
+    return { ...event, evidence };
+}
+/** Strips host-only diagnostics, so the copy is safe to forward to browsers or end-user SSE. */
+function forClient(event, options) {
+    let out = stripGuardrailInternal(stripErrorInternal(event));
+    if (!options?.includeEvidenceRaw) {
+        out = stripEvidenceRaw(out);
+    }
+    // Clients never receive matched substrings, even if the host opted into guardrailMatchPreview.
+    out = projectGuardrailTurnEvent(out, false);
+    return out;
+}
+function forClientEvents(events, options) {
+    return events.map((event) => forClient(event, options));
+}
+export { forClient, forClientEvents };

package/esm/src/host/mint-trace.d.ts

@@ -0,0 +1,28 @@
+import type { Profile } from '../kernel/types.js';
+import { type TraceRecord } from '../observability/trace-record.js';
+import type { TraceSink } from '../observability/trace-sink.js';
+interface CutoutTape {
+    ok: boolean;
+    /** How long the cutout took; the span ends now and starts this long before. */
+    ms: number;
+    url?: string;
+    inSha256?: string;
+    outSha256?: string;
+    /** The upstream exchange, recorded as a `theorem.upstream.row` event. */
+    http?: unknown;
+    error?: string;
+}
+/**
+ * Writes the held turn record, then one `cutout` span parented on its root, so both read as one
+ * trace. Without a `sink` nothing is written.
+ */
+declare function flushMintTrace(args: {
+    /** The profile the held turn ran on; its observability governs both writes. */
+    profile: Profile;
+    held: TraceRecord[];
+    app: Record<string, unknown>;
+    cutout: CutoutTape;
+    sink?: TraceSink;
+}): Promise<void>;
+export type { CutoutTape };
+export { flushMintTrace };

package/esm/src/host/mint-trace.js

@@ -0,0 +1,59 @@
+import { TheoremError } from '../guardrails/error.js';
+import { urlAttributes } from '../kernel/engine/turn-trace.js';
+import { resolveTraceWriter } from '../observability/policy.js';
+import { writeTrace } from '../observability/trace.js';
+import { buildRecord } from '../observability/trace-record.js';
+import { formatTraceparent, startTrace, traceContent, traceJson, } from '../observability/trace-span.js';
+const NANOS_PER_MS = 1_000_000;
+const AGENT_NAME = 'gen_ai.agent.name';
+function cutoutAttributes(cutout) {
+    return {
+        ...urlAttributes(cutout.url),
+        ...(cutout.inSha256 ? { 'theorem.cutout.input.sha256': cutout.inSha256 } : {}),
+        ...(cutout.outSha256 ? { 'theorem.cutout.output.sha256': cutout.outSha256 } : {}),
+    };
+}
+/**
+ * Writes the held turn record, then one `cutout` span parented on its root, so both read as one
+ * trace. Without a `sink` nothing is written.
+ */
+async function flushMintTrace(args) {
+    const [record] = args.held;
+    const root = record?.spans[0];
+    if (!record || !root || !args.sink) {
+        return;
+    }
+    const ranOn = root.attributes[AGENT_NAME];
+    if (ranOn !== args.profile.id) {
+        throw new TheoremError('config', `flushMintTrace: the held turn ran on '${String(ranOn)}', not '${args.profile.id}'`);
+    }
+    const { sink, policy } = resolveTraceWriter({
+        override: args.sink,
+        observability: args.profile.observability,
+    });
+    await writeTrace(sink, Promise.resolve(record), policy);
+    const { cutout } = args;
+    // One instant: the cutout was reported done now and ran for `ms` before it.
+    const now = BigInt(Date.now()) * BigInt(NANOS_PER_MS);
+    const tree = startTrace('cutout', {
+        clock: { nowUnixNano: () => now },
+        kind: 'CLIENT',
+        traceparent: formatTraceparent(root.traceId, root.spanId),
+        startTimeUnixNano: String(now - BigInt(Math.round(cutout.ms * NANOS_PER_MS))),
+        attributes: cutoutAttributes(cutout),
+    });
+    if (cutout.http !== undefined) {
+        tree.root.event('theorem.upstream.row', { row: traceJson(cutout.http) });
+    }
+    // The host's error text is free text: stored by hash under the scrub, like any exception.
+    if (cutout.error) {
+        tree.root.event('exception', { 'exception.message': traceContent(cutout.error) });
+    }
+    tree.root.end({ code: cutout.ok ? 'OK' : 'ERROR' });
+    await writeTrace(sink, buildRecord({
+        spans: tree.collect(),
+        policy,
+        metadata: { ...record.metadata, app: args.app },
+    }), policy);
+}
+export { flushMintTrace };