@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/guardrails/detect-at.js

@@ -0,0 +1,434 @@
+// invariant: The one place a match becomes an action. Every boundary calls `detectAt`; nothing
+// else reads the matrix to decide what a match does.
+import { applySpans, spansFromPatterns } from '../observability/spans.js';
+import { INBOUND_BOUNDARIES, recordOf, TOOL_BOUNDARIES } from './boundaries.js';
+import { canaryLeakRanges } from './canary.js';
+import { actionAt, DETECTORS, detects, } from './detectors.js';
+import { boundaryNote } from './egress.js';
+import { notePattern, SYSTEM_BOUNDARY } from './egress-patterns.js';
+import { imageLeakSpans, linkLeakSpans } from './egress-urls.js';
+import { CANARY_HIT, hitFromSpan, PROMPT_ECHO_HIT } from './hits.js';
+import { injectionSpans } from './injection.js';
+import { promptEchoRanges } from './prompt-echo.js';
+import { DETECT_RULES, detectRule } from './rules.js';
+import { sensitiveSpans } from './sensitive.js';
+import { SENSITIVE_GROUPS } from './sensitive-groups.js';
+import { TheoremError } from './theorem-error.js';
+import { directives, mergedRanges } from './tool-directives.js';
+import { ownToolsWithout, toolLeakSpans } from './tool-leak.js';
+const STRENGTH = ['allow', 'flag', 'redact', 'block'];
+function stronger(left, right) {
+    if (right === 'ignore')
+        return left;
+    return STRENGTH.indexOf(right) > STRENGTH.indexOf(left) ? right : left;
+}
+/** Each sensitive group alone, for a scan that reads one detector at a time. */
+const ONLY = recordOf(SENSITIVE_GROUPS, (group) => recordOf(SENSITIVE_GROUPS, (other) => other === group));
+const NO_SCOPE = {};
+/**
+ * The {@linkcode LeakScope} of a turn under `detect`: each part only while its detector is above
+ * `ignore` somewhere, so a profile that reads for neither binds nothing to read for.
+ */
+function leakScopeOf(detect, turn) {
+    const canary = detects(detect, 'canary_leak') ? turn.canary : undefined;
+    const guarded = detects(detect, 'prompt_leak') && turn.privateSystem?.length;
+    return {
+        ...(canary ? { canary } : {}),
+        ...(canary && turn.canaryGiven ? { canaryGiven: true } : {}),
+        ...(guarded ? { privateSystem: turn.privateSystem } : {}),
+    };
+}
+/** The {@linkcode DetectScope} of a turn under `policy`: each part only while a detector reads it. */
+function scopeOf(policy, turn) {
+    const { detect } = policy;
+    const leaks = leakScopeOf(detect, turn);
+    const urls = detects(detect, 'ungiven_images') || detects(detect, 'ungiven_links');
+    const note = detects(detect, 'marker_leak')
+        ? boundaryNote({ canary: leaks.canary, labels: turn.labels })
+        : undefined;
+    const tools = detects(detect, 'tool_leak')
+        ? ownToolsWithout(turn.ownTools, detect.innocent)
+        : undefined;
+    return {
+        ...leaks,
+        ...(urls && turn.givenUrls ? { givenUrls: turn.givenUrls } : {}),
+        ...(urls ? { allow: policy.allow } : {}),
+        ...(note ? { note } : {}),
+        ...(tools ? { ownTools: tools } : {}),
+    };
+}
+/** The detectors a stream gate reads itself, as the text grows. */
+const SCOPED = ['canary_leak', 'prompt_leak'];
+function isScoped(detector) {
+    return SCOPED.includes(detector);
+}
+/** One span for each run of overlapping `ranges`: a passage matched window by window is one match. */
+function ranged(ranges, kind) {
+    return mergedRanges(ranges).map(([start, end]) => ({ start, end, kind }));
+}
+/** What `detector` lets through in a turn of `scope`. */
+function urlScope(detector, scope) {
+    return { ...scope.allow?.[detector], ...(scope.givenUrls ? { given: scope.givenUrls } : {}) };
+}
+const MARKERS = new RegExp(SYSTEM_BOUNDARY.source, 'gi');
+/** Every match of the host's `matchers` in `text`, each named for its pattern. */
+function hostSpans(text, matchers, kind) {
+    return matchers.flatMap(({ name, regex }) => spansFromPatterns(text, [regex], kind).map((span) => ({ ...span, name })));
+}
+/** The placeholder a host's pattern leaves for a detector, where it is not the sensitive one. */
+const HOST_KIND = {
+    injection: 'injection',
+    tool_instructions: 'directive',
+    tool_leak: 'tool',
+};
+/**
+ * What `detector` finds in `text`: with Theorem's patterns, the host's, both, or neither, as its
+ * `source` says. Left out, Theorem's only. A host's pattern is read on the text as written.
+ */
+function spansOf(detector, text, scope, source, skipImages = false) {
+    if (!source)
+        return theoremSpans(detector, text, scope, skipImages);
+    const own = hostSpans(text, source.matchers, HOST_KIND[detector] ?? 'sensitive');
+    return source.theorem ? [...theoremSpans(detector, text, scope, skipImages), ...own] : own;
+}
+/** With `skipImages`, `ungiven_links` leaves an image's own markup to `ungiven_images`. */
+function theoremSpans(detector, text, scope, skipImages = false) {
+    if (detector === 'injection')
+        return injectionSpans(text);
+    if (detector === 'marker_leak') {
+        const patterns = [MARKERS, ...(scope.note ? [notePattern(scope.note)] : [])];
+        return spansFromPatterns(text, patterns, 'prompt');
+    }
+    if (detector === 'ungiven_images') {
+        const spans = imageLeakSpans(text, urlScope(detector, scope));
+        return spans.map((span) => ({ ...span, kind: 'image' }));
+    }
+    if (detector === 'ungiven_links') {
+        const spans = linkLeakSpans(text, urlScope(detector, scope), skipImages);
+        return spans.map((span) => ({ ...span, kind: 'link' }));
+    }
+    if (detector === 'canary_leak') {
+        const { canary, canaryGiven } = scope;
+        return canary && !canaryGiven ? ranged(canaryLeakRanges(text, canary), 'canary') : [];
+    }
+    if (detector === 'prompt_leak') {
+        const { privateSystem, canary } = scope;
+        return privateSystem ? ranged(promptEchoRanges(text, privateSystem, canary), 'prompt') : [];
+    }
+    if (detector === 'tool_leak')
+        return toolLeakSpans(text, scope.ownTools);
+    if (detector === 'tool_instructions') {
+        return directives(text, scope.callable).map((found) => ({ ...found, kind: 'directive' }));
+    }
+    return sensitiveSpans(text, ONLY[detector]);
+}
+/** The hit for a match of `detector`. One of ours never carries what it matched. */
+function hitOf(detector, text, span) {
+    const { start, end } = span;
+    if (detector === 'canary_leak')
+        return { ...CANARY_HIT, span: { start, end } };
+    if (detector === 'prompt_leak')
+        return { ...PROMPT_ECHO_HIT, span: { start, end } };
+    if (detector === 'tool_instructions' && span.signal) {
+        const severity = span.signal === 'order' || span.signal === 'authority' ? 'medium' : 'high';
+        return { ...hitFromSpan(text, span, DETECT_RULES[detector], severity), signal: span.signal };
+    }
+    return hitFromSpan(text, span, DETECT_RULES[detector], 'high');
+}
+/** Whether `detector` leaves an image to `ungiven_images`, read at `boundary` beside it. */
+function leavesImages(detector, boundary, detect) {
+    return detector === 'ungiven_links' && detect.ungiven_images[boundary] !== 'ignore';
+}
+/** What a host's `find` matched in `text`, or how it failed. */
+function foundBy(find, text, boundary) {
+    try {
+        const spans = find(text, boundary ? { boundary } : {});
+        if (!Array.isArray(spans))
+            return 'find_result';
+        const inside = spans.every(({ start, end }) => Number.isInteger(start) &&
+            Number.isInteger(end) &&
+            start >= 0 &&
+            start < end &&
+            end <= text.length);
+        return inside ? spans.map(({ start, end }) => ({ start, end, kind: 'host' })) : 'find_result';
+    }
+    catch {
+        // why: A reading that failed found nothing it can vouch for, so the text does not cross.
+        return 'find_threw';
+    }
+}
+function hostReader(host, boundary, chosen) {
+    const rule = detectRule(host.id);
+    return {
+        key: host.id,
+        rule,
+        label: host.label,
+        chosen,
+        spans(text) {
+            const matched = hostSpans(text, host.matchers, 'host');
+            if (!host.find)
+                return matched;
+            const found = foundBy(host.find, text, boundary);
+            return typeof found === 'string' ? found : [...matched, ...found];
+        },
+        hit: (text, span) => ({ ...hitFromSpan(text, span, rule, 'high'), label: host.label }),
+    };
+}
+/** The host's own detectors that read `boundary`. */
+function hostAt(boundary, detect) {
+    return (detect.host ?? []).filter(({ actions }) => actions[boundary] !== 'ignore');
+}
+/** Every detector that reads `boundary`, Theorem's then the host's; among `keys` when given. */
+function readersAt(boundary, detect, scope, keys) {
+    const readers = [];
+    for (const detector of DETECTORS) {
+        const chosen = detect[detector][boundary];
+        if (chosen === 'ignore')
+            continue;
+        const skip = leavesImages(detector, boundary, detect);
+        readers.push({
+            key: detector,
+            rule: DETECT_RULES[detector],
+            chosen,
+            spans: (text) => spansOf(detector, text, scope, detect.sources?.[detector], skip),
+            hit: (text, span) => hitOf(detector, text, span),
+        });
+    }
+    for (const host of hostAt(boundary, detect)) {
+        readers.push(hostReader(host, boundary, host.actions[boundary]));
+    }
+    return keys ? readers.filter(({ key }) => keys.includes(key)) : readers;
+}
+/** The hit of a host's `find` that failed: it names the detector, how it failed and no match. */
+function failedHit({ rule, label }, signal) {
+    return {
+        rule,
+        severity: 'high',
+        ...(label === undefined ? {} : { label }),
+        ...(signal === undefined ? {} : { signal }),
+    };
+}
+/**
+ * The longest single text the person or host may send, in characters: far over any model's
+ * context, and under what the detectors read safely.
+ */
+const MAX_INBOUND_CHARS = 1_000_000;
+const INBOUND = new Set(INBOUND_BOUNDARIES);
+/** Refuses a text the person or host sent that is over `MAX_INBOUND_CHARS`; `where` names it for the log. */
+function refuseOverlong(text, where) {
+    if (text.length <= MAX_INBOUND_CHARS)
+        return;
+    // labels-exempt: internal diagnostic; the person reads `input.too_long`
+    throw new TheoremError('input', `${where} text of ${text.length} characters is over ${MAX_INBOUND_CHARS}`, {
+        copy: { key: 'input.too_long', params: { maxChars: MAX_INBOUND_CHARS } },
+    });
+}
+/** Reads `text` as it crosses `boundary` under the profile's resolved matrix. */
+function detectAt(text, boundary, detect, scope = NO_SCOPE) {
+    if (INBOUND.has(boundary))
+        refuseOverlong(text, boundary);
+    const hits = [];
+    const redact = [];
+    let action = 'allow';
+    for (const reader of readersAt(boundary, detect, scope)) {
+        const spans = reader.spans(text);
+        if (typeof spans === 'string') {
+            hits.push(failedHit(reader, spans));
+            action = 'block';
+            continue;
+        }
+        if (spans.length === 0)
+            continue;
+        for (const span of spans)
+            hits.push(reader.hit(text, span));
+        if (reader.chosen === 'redact')
+            redact.push(...spans);
+        action = stronger(action, reader.chosen);
+    }
+    if (action === 'block')
+        return { action, hits };
+    if (redact.length === 0)
+        return { action, text, hits };
+    const replaced = applySpans(text, redact);
+    // why: Replacing a match can join what was around it into a new one: that text does not cross.
+    if (leftAfterRedact(replaced, boundary, detect, scope))
+        return { action: 'block', hits };
+    return { action, text: replaced, hits };
+}
+/**
+ * Whether `replaced`, a text whose matches were replaced, still holds a match of a detector set
+ * to `redact` or `block` at `boundary`, among `detectors`.
+ */
+function leftAfterRedact(replaced, boundary, detect, scope, detectors) {
+    return readersAt(boundary, detect, scope, detectors).some(({ chosen, spans }) => {
+        if (chosen === 'flag')
+            return false;
+        const left = spans(replaced);
+        return !left || left.length > 0;
+    });
+}
+/** The detectors that read `boundary`: every one not set to `ignore`. */
+function detectorsAt(boundary, detect) {
+    return DETECTORS.filter((detector) => detect[detector][boundary] !== 'ignore');
+}
+/** Whether `scope` holds the part `detector` reads for. One that reads no scope always has its part. */
+function hasPart(detector, scope) {
+    if (detector === 'canary_leak')
+        return Boolean(scope.canary);
+    if (detector === 'prompt_leak')
+        return Boolean(scope.privateSystem?.length);
+    if (detector === 'tool_leak')
+        return Boolean(scope.ownTools?.names.length);
+    return true;
+}
+/**
+ * Whether any detector reads one of `boundaries`. Given the turn's `scope`, a
+ * detector whose part is absent does not count: it has nothing to find.
+ */
+function detectReads(boundaries, detect, scope) {
+    return boundaries.some((boundary) => hostAt(boundary, detect).length > 0 ||
+        detectorsAt(boundary, detect).some((detector) => !scope || hasPart(detector, scope)));
+}
+/**
+ * Reads the stretch `[from, to)` of `window`, a text released as it streams. A match is reported
+ * with the stretch it starts in. One being replaced is released whole: `to` is pulled back to its
+ * start when the stretch would cut it, and `taken` is how far the release got. A detector set to
+ * `block` that the stream settled a match of blocks even when this reading finds none: the two
+ * are then out of step, and the stream's finding stands.
+ */
+function detectRelease(window, { from, to, settled }, boundary, detect, { detectors, scope }) {
+    const failed = [];
+    const found = readersAt(boundary, detect, scope, detectors).flatMap((reader) => {
+        const spans = reader.spans(window);
+        if (typeof spans === 'string')
+            failed.push(failedHit(reader, spans));
+        return (typeof spans === 'string' ? [] : spans)
+            .filter((span) => span.end > from && span.start < to)
+            .map((span) => ({ span, rule: reader.rule, label: reader.label, chosen: reader.chosen }));
+    });
+    if (failed.length > 0)
+        return { action: 'block', hits: failed, taken: 0 };
+    const hitOf = ({ span, rule, label }) => ({
+        ...hitFromSpan(window, span, rule, 'high'),
+        ...(label === undefined ? {} : { label }),
+    });
+    const blocking = found.filter(({ chosen }) => chosen === 'block');
+    if (blocking.length > 0)
+        return { action: 'block', hits: blocking.map(hitOf), taken: 0 };
+    const unread = settled.filter((key) => actionAt(detect, key, boundary) === 'block');
+    if (unread.length > 0) {
+        const hits = unread.map((key) => failedHit({
+            rule: detectRule(key),
+            label: detect.host?.find(({ id }) => id === key)?.label,
+        }));
+        return { action: 'block', hits, taken: 0 };
+    }
+    const replaced = found.filter(({ chosen }) => chosen === 'redact');
+    let end = to;
+    for (;;) {
+        const cut = replaced.find(({ span }) => span.start < end && span.end > end);
+        if (!cut)
+            break;
+        end = Math.max(from, cut.span.start);
+    }
+    const inside = found.filter(({ span, chosen }) => chosen === 'redact' ? span.end <= end : span.start >= from && span.start < end);
+    const spans = inside
+        .filter(({ chosen }) => chosen === 'redact')
+        .map(({ span }) => ({ ...span, start: Math.max(0, span.start - from), end: span.end - from }));
+    const text = applySpans(window.slice(from, end), spans);
+    if (spans.length > 0 && leftAfterRedact(text, boundary, detect, scope, detectors)) {
+        return { action: 'block', hits: inside.map(hitOf), taken: 0 };
+    }
+    return {
+        action: inside.reduce((action, { chosen }) => stronger(action, chosen), 'allow'),
+        text,
+        hits: inside.map(hitOf),
+        taken: end - from,
+    };
+}
+/** `text` with every match of `detectors` replaced by its placeholder, whatever a profile sets. */
+function redactDetectors(text, detectors) {
+    return applySpans(text, detectors.flatMap((detector) => spansOf(detector, text, NO_SCOPE)));
+}
+/**
+ * What `detectors` find in a text a trace stores, whatever action a profile sets. `detect` is
+ * the profile's, for the patterns a host added to each.
+ */
+function storedSpans(text, detectors, sides, detect) {
+    return detectors.flatMap((detector) => {
+        const turn = detect?.sources?.[detector];
+        const source = sides === true
+            ? turn
+            : { theorem: sides.theorem, matchers: sides.host ? (turn?.matchers ?? []) : [] };
+        return spansOf(detector, text, NO_SCOPE, source);
+    });
+}
+/** What a host's own detectors find in a text a trace stores. A `find` that fails covers it all. */
+function storedHostSpans(text, detect) {
+    return (detect?.host ?? []).flatMap((host) => {
+        const matched = hostSpans(text, host.matchers, 'host');
+        if (!host.find || !text)
+            return matched;
+        const found = foundBy(host.find, text);
+        return typeof found === 'string'
+            ? [{ start: 0, end: text.length, kind: 'host' }]
+            : [...matched, ...found];
+    });
+}
+/** A reader for everything crossing `boundary` in one request. */
+function boundaryReader(boundary, detect) {
+    const hits = [];
+    let action = 'allow';
+    return {
+        read(text) {
+            const detected = detectAt(text, boundary, detect);
+            hits.push(...detected.hits);
+            action = stronger(action, detected.action);
+            return detected.text ?? '';
+        },
+        found: () => ({ action, hits }),
+    };
+}
+const TOOL_STAGE = Object.fromEntries(TOOL_BOUNDARIES.map((boundary) => [
+    boundary,
+    boundary.startsWith('tool_arguments') ? 'tool_call' : 'tool_result',
+]));
+/** The trace stage each boundary reports under. */
+const BOUNDARY_STAGE = {
+    user: 'input',
+    slots: 'input',
+    context: 'input',
+    repair: 'input',
+    attachment: 'attachment',
+    voice: 'attachment',
+    history: 'history',
+    injected: 'history',
+    system: 'system',
+    live_user: 'live_inbound',
+    ...TOOL_STAGE,
+    reply: 'output_final',
+    reply_structured: 'output_final',
+    live_reply: 'live_outbound',
+    thought: 'thought',
+};
+/** Host-built per-turn system text is `assembled`; everything else a detector reads is `untrusted`. */
+function trustAt(boundary) {
+    return boundary === 'system' ? 'assembled' : 'untrusted';
+}
+/**
+ * The guardrail event for what was found at a boundary, or `undefined` when nothing matched.
+ * `stage` is the boundary's own unless the text was read as it streamed.
+ */
+function detectEvent(boundary, found, provenance, stage = BOUNDARY_STAGE[boundary]) {
+    if (found.action === 'allow')
+        return undefined;
+    return {
+        stage,
+        boundary,
+        trust: trustAt(boundary),
+        action: found.action,
+        hits: found.hits,
+        ...(provenance ? { provenance } : {}),
+    };
+}
+export { boundaryReader, detectAt, detectEvent, detectorsAt, detectReads, detectRelease, hostAt, isScoped, leakScopeOf, redactDetectors, refuseOverlong, scopeOf, storedHostSpans, storedSpans, stronger, };

package/esm/src/guardrails/detect-reply.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `guardrails.detect` on a reply once it has ended. The stream gate
+ * (`progressive-yield.ts`) already reported and replaced what it released; this
+ * reads the reply whole, so a match the stream held back, or one in the
+ * structured output, meets the action the profile set before the reply crosses.
+ *
+ * @module
+ */
+import type { Boundary } from './boundaries.js';
+import { type Detection, type DetectScope } from './detect-at.js';
+import type { ResolvedDetect } from './detectors.js';
+import type { GuardrailEvent, GuardrailHit } from './event-schemas.js';
+import { type LabelOverrides } from './labels.js';
+import type { OutboundPayload } from './types.js';
+/** The boundaries a turn's reply crosses: its text, and its structured output. */
+declare const TURN_REPLY: readonly ["reply", "reply_structured"];
+/** A reply read whole at its boundaries. */
+interface ReplyRead {
+    /** The reply to send on: every match set to `redact` replaced. */
+    payload: OutboundPayload;
+    /** Whether `payload.text` differs from the text as written. */
+    rewritten: boolean;
+    /** One event for each boundary with something to report. */
+    events: GuardrailEvent[];
+    /** Set when a match blocks: the reply does not cross. */
+    blocked?: GuardrailHit[];
+}
+/** A JSON value read at `boundary`, with each match in a string replaced, or what stops it crossing. */
+declare function readValue(value: unknown, boundary: Boundary, detect: ResolvedDetect, scope?: DetectScope): Pick<Detection, 'action' | 'hits'> & {
+    value?: unknown;
+};
+/**
+ * Reads a reply's text at `boundary`, and its structured output at
+ * `reply_structured`. A flag in text the stream released was reported then, so
+ * it is reported here only past `reportedTo`: how far into the text the stream
+ * released, or all of it when left out. `scope` is what the detectors of what
+ * is the profile's own read of the turn.
+ */
+declare function readReply(written: OutboundPayload, detect: ResolvedDetect, { boundary, reportedTo, scope, }: {
+    boundary: 'reply' | 'live_reply';
+    reportedTo?: number;
+    scope?: DetectScope;
+}): ReplyRead;
+/**
+ * The hits a reply stays stopped on: this reading's block, or else a leak the
+ * stream `stopped` on that this reading does not find. The two are out of
+ * step then, and the stream's finding stands.
+ */
+declare function standingBlock(read: ReplyRead, stopped?: readonly GuardrailHit[]): GuardrailHit[] | undefined;
+/**
+ * `text` as the host receives it after `shown`, the reply text it already has:
+ * the rest of it when it carries on from there, or else set apart from it.
+ */
+declare function replyAfter(shown: string, text: string): string;
+/**
+ * The refusal as the host receives it after `shown`: the whole refusal when the user has
+ * none of the reply, or the cut that ends the part they have.
+ */
+declare function refusalAfter(shown: string, labels?: LabelOverrides): string;
+export type { ReplyRead };
+export { readReply, readValue, refusalAfter, replyAfter, standingBlock, TURN_REPLY };

package/esm/src/guardrails/detect-reply.js

@@ -0,0 +1,95 @@
+/**
+ * `guardrails.detect` on a reply once it has ended. The stream gate
+ * (`progressive-yield.ts`) already reported and replaced what it released; this
+ * reads the reply whole, so a match the stream held back, or one in the
+ * structured output, meets the action the profile set before the reply crosses.
+ *
+ * @module
+ */
+import { mapStrings } from '../kernel/engine/tree.js';
+import { detectAt, detectEvent, detectReads, } from './detect-at.js';
+import { labelText } from './labels.js';
+import { EGRESS_RULES } from './rules.js';
+import { textForScan } from './serialize.js';
+/** The boundaries a turn's reply crosses: its text, and its structured output. */
+const TURN_REPLY = ['reply', 'reply_structured'];
+/** A JSON value read at `boundary`, with each match in a string replaced, or what stops it crossing. */
+function readValue(value, boundary, detect, scope = {}) {
+    if (!detectReads([boundary], detect))
+        return { action: 'allow', hits: [], value };
+    const scan = textForScan(value);
+    if (scan.unscannable) {
+        // why: Cannot inspect it, so cannot vouch for it. Fail closed.
+        return { action: 'block', hits: [{ rule: EGRESS_RULES.unscannable, severity: 'high' }] };
+    }
+    const found = detectAt(scan.text, boundary, detect, scope);
+    if (found.action !== 'redact')
+        return { action: found.action, hits: found.hits, value };
+    const redacted = mapStrings(value, (leaf) => detectAt(leaf, boundary, detect, scope).text ?? '');
+    const left = detectAt(textForScan(redacted).text, boundary, detect, scope).action;
+    // why: A match in a key, or one that runs across values, has no string to replace: it does not cross.
+    if (left === 'redact' || left === 'block')
+        return { action: 'block', hits: found.hits };
+    return { action: 'redact', hits: found.hits, value: redacted };
+}
+/**
+ * Reads a reply's text at `boundary`, and its structured output at
+ * `reply_structured`. A flag in text the stream released was reported then, so
+ * it is reported here only past `reportedTo`: how far into the text the stream
+ * released, or all of it when left out. `scope` is what the detectors of what
+ * is the profile's own read of the turn.
+ */
+function readReply(written, detect, { boundary, reportedTo = written.text.length, scope = {}, }) {
+    const text = detectAt(written.text, boundary, detect, scope);
+    const structured = written.structured === undefined
+        ? undefined
+        : readValue(written.structured, 'reply_structured', detect, scope);
+    const flagged = reportedTo >= written.text.length
+        ? []
+        : text.hits.filter((hit) => !hit.span || hit.span.start >= reportedTo);
+    const events = [
+        text.action === 'flag'
+            ? detectEvent(boundary, { action: flagged.length > 0 ? 'flag' : 'allow', hits: flagged })
+            : detectEvent(boundary, text),
+        structured ? detectEvent('reply_structured', structured) : undefined,
+    ].filter((event) => event !== undefined);
+    const blocked = [text, structured].flatMap((found) => found?.action === 'block' ? found.hits : []);
+    return {
+        payload: {
+            text: text.text ?? written.text,
+            ...(structured ? { structured: structured.value } : {}),
+        },
+        rewritten: text.action === 'redact',
+        events,
+        ...(blocked.length > 0 ? { blocked } : {}),
+    };
+}
+/**
+ * The hits a reply stays stopped on: this reading's block, or else a leak the
+ * stream `stopped` on that this reading does not find. The two are out of
+ * step then, and the stream's finding stands.
+ */
+function standingBlock(read, stopped = []) {
+    if (read.blocked)
+        return read.blocked;
+    const reread = new Set(read.events.flatMap((event) => event.hits.map((hit) => hit.rule)));
+    const unread = stopped.filter((hit) => !reread.has(hit.rule));
+    return unread.length > 0 ? unread : undefined;
+}
+/**
+ * `text` as the host receives it after `shown`, the reply text it already has:
+ * the rest of it when it carries on from there, or else set apart from it.
+ */
+function replyAfter(shown, text) {
+    if (!shown)
+        return text;
+    return text.startsWith(shown) ? text.slice(shown.length) : `\n\n${text}`;
+}
+/**
+ * The refusal as the host receives it after `shown`: the whole refusal when the user has
+ * none of the reply, or the cut that ends the part they have.
+ */
+function refusalAfter(shown, labels) {
+    return labelText(shown ? 'egress.refusal_cut' : 'egress.refusal', {}, labels);
+}
+export { readReply, readValue, refusalAfter, replyAfter, standingBlock, TURN_REPLY };

package/esm/src/guardrails/detect-stream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `guardrails.detect` on text released as it streams: a reply, a Live reply, a
+ * thought. The stream scanner (`egress-stream.ts`) says where a match could
+ * still be under way, so nothing a detector reads is released early, and where
+ * one settled; `detectRelease` then reads the stretch being released and takes
+ * the action the profile set.
+ *
+ * @module
+ */
+import type { Boundary } from './boundaries.js';
+import { type DetectScope, type Release } from './detect-at.js';
+import { type Detector, type ResolvedDetect } from './detectors.js';
+/** Text read at one boundary as it streams. Indices are of the text as written. */
+interface DetectStream {
+    /** Read the next piece of the text. */
+    push(fragment: string): void;
+    /** The earliest index a match could still start at: nothing from there on is released yet. */
+    holdFrom(): number;
+    /**
+     * Release the text from `from` up to `to`, or all of it once it has `ended`:
+     * what crosses, what was found in it, and how far the release got.
+     */
+    take(from: number, to: number, ended?: boolean): Release;
+}
+/**
+ * A reader for text streaming across `boundary` in a turn of `scope`, or `undefined` when no
+ * detector it streams reads it. `canary_leak` and `prompt_leak` (`isScoped`) are not among them:
+ * the gate at the boundary reads those as the text grows. Nor are the detectors in `leave`, which
+ * another reader at the boundary has.
+ */
+declare function createDetectStream(boundary: Boundary, detect: ResolvedDetect, scope?: DetectScope, leave?: readonly Detector[]): DetectStream | undefined;
+export type { DetectStream };
+export { createDetectStream };