@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/thought-guard.js

@@ -0,0 +1,664 @@
+/**
+ * Thought guarding, under `guardrails.detect` at `thought`. A host that renders `thought` events shows the user what
+ * they say and loads what they link, as it does a reply: the canary, the
+ * system prompt and the user-data markers leak through a thought, and a URL
+ * the model was not given carries data out. Nothing in a thought stops a turn
+ * (`isGuardedOutput`); each leak is omitted and the rest of the thought
+ * released, or under `block` omitted with the rest of the thought.
+ *
+ * @module
+ */
+import { CANARY_LEAK_REACH, canaryHoldFrom, canaryLeakRanges, canaryOpeningFrom, createCanaryScanner, promptLeakCarry, RELEASED_LOOKBACK, wordStartAcross, } from './canary.js';
+import { detectReads, scopeOf, stronger, } from './detect-at.js';
+import { createDetectStream } from './detect-stream.js';
+import { boundaryNote } from './egress.js';
+import { notePattern, SYSTEM_BOUNDARY } from './egress-patterns.js';
+import { createEgressStream, loadEgressAutomata } from './egress-stream.js';
+import { imageLeakSpans, linkLeakSpans } from './egress-urls.js';
+import { CANARY_HIT, PROMPT_ECHO_HIT } from './hits.js';
+import { labelText } from './labels.js';
+import { promptEchoHoldFrom, promptEchoRanges, promptEchoScanFrom } from './prompt-echo.js';
+import { DETECT_RULES } from './rules.js';
+const OMIT_KEYS = {
+    image: 'thought.omitted_image',
+    link: 'thought.omitted_link',
+    instructions: 'thought.omitted_instructions',
+};
+const IMAGE_HIT = { rule: DETECT_RULES.ungiven_images, severity: 'high' };
+const LINK_HIT = { rule: DETECT_RULES.ungiven_links, severity: 'high' };
+const MARKER_HIT = { rule: DETECT_RULES.marker_leak, severity: 'high' };
+/** Where `raw`, an offset into `view.text`, stands in the thought: a placeholder's start, or with `end` its end. */
+function shownAt(view, raw, end = false) {
+    let piece = view.pieces[0];
+    for (const next of view.pieces) {
+        if (next.raw > raw || (end && next.raw === raw && raw > 0))
+            break;
+        piece = next;
+    }
+    if (!piece)
+        return raw;
+    if (piece.mark)
+        return end ? piece.mark.end : piece.mark.start;
+    return piece.shown + raw - piece.raw;
+}
+/** Sorted, with overlapping leaks as one: an image's URL is a bare link too. */
+function merged(spans) {
+    const out = [];
+    for (const span of [...spans].sort((a, b) => a.start - b.start)) {
+        const last = out.at(-1);
+        if (last && span.start < last.end)
+            last.end = Math.max(last.end, span.end);
+        else
+            out.push({ ...span });
+    }
+    return out;
+}
+/** Omitting one leak can join what was around it into another; past this many rounds, the rest goes. */
+const MAX_ROUNDS = 8;
+/** Each leak rereads the thought; a thought still writing them past this many loses the rest. */
+const MAX_LEAKS = 16;
+/**
+ * The guard reads the thought as it will be shown, placeholders in: text
+ * released is final, and what is held changes only by omission. The canary
+ * and prompt echo are read a second time with each placeholder as the text it
+ * replaced, so a leak running on past one, or across one longer than its
+ * text, is omitted too.
+ */
+function createThoughtGuard(options) {
+    const { omit = {}, canary, privateSystem, ends, given, labels } = options;
+    /** The detectors whose matches the guard omits as the thought streams. */
+    const streamed = [
+        ...(omit.markers ? ['marker_leak'] : []),
+        ...(omit.images ? ['ungiven_images'] : []),
+        ...(omit.links ? ['ungiven_links'] : []),
+    ];
+    const skipImages = omit.imagesRead ?? omit.images !== undefined;
+    /** The canary as the echo and the note read it: planted, whether or not a thought is read for it. */
+    const slot = canary ?? options.planted;
+    const note = boundaryNote({ canary: slot, labels });
+    const scope = (check) => ({ ...check, ...(given ? { given } : {}) });
+    /** The placeholder for `kind` after `before`, without a second space. */
+    function placeholder(kind, before) {
+        const text = labelText(OMIT_KEYS[kind], {}, labels);
+        return /\s$/.test(before) ? text.trimStart() : text;
+    }
+    let out = canary || privateSystem ? (options.carry ?? '') : '';
+    let held = '';
+    let stream;
+    let scanner;
+    /** How far the prompt echo has read `out + held` clean. */
+    let echoed = 0;
+    /** How much of `out + held` the readers have read. */
+    let readTo = 0;
+    /** Where a leak still growing at the end of the held text starts; held until it ends. */
+    let open;
+    /** The placeholders in `out + held` a leak reaching the held text could run through, in order. */
+    let marks = [];
+    /**
+     * No canary opening starts in `out + held` before this while the held text
+     * only grows and is released: a point further back than `RELEASED_LOOKBACK`
+     * that is no opening cannot become one. An omission rewrites the held text,
+     * and the hold is read whole again.
+     */
+    let openingFrom = 0;
+    /** Set once the rest of the thought is omitted: nothing more is read until the flush. */
+    let cut = false;
+    let leaks = 0;
+    let hits = new Map();
+    /** Fresh readers over `text`, as if it had streamed: true when it already holds a leak. */
+    function restart(text) {
+        stream =
+            streamed.length > 0
+                ? createEgressStream({
+                    detect: streamed,
+                    allow: { ungiven_images: omit.images ?? {}, ungiven_links: omit.links ?? {} },
+                    skipImages,
+                    ...(given ? { given } : {}),
+                    ...(note ? { note } : {}),
+                })
+                : undefined;
+        scanner = canary ? createCanaryScanner(canary) : undefined;
+        echoed = 0;
+        readTo = 0;
+        return read(text);
+    }
+    /** Read `text`, what follows the read part of `out + held`; true when a leak has settled. */
+    function read(text) {
+        readTo += text.length;
+        const urlHit = (stream?.push(text).length ?? 0) > 0;
+        const canaryHit = scanner?.push(text) ?? false;
+        let echoHit = false;
+        if (privateSystem) {
+            const whole = (out + held).slice(0, readTo);
+            const from = promptEchoScanFrom(whole, echoed);
+            echoHit = promptEchoRanges(whole.slice(from), privateSystem, slot).length > 0;
+            echoed = whole.length;
+        }
+        return urlHit || canaryHit || echoHit;
+    }
+    function leakSpans(text) {
+        const spans = [];
+        if (omit.images) {
+            for (const span of imageLeakSpans(text, scope(omit.images))) {
+                spans.push({ ...span, kind: 'image', hit: IMAGE_HIT });
+            }
+        }
+        if (omit.links) {
+            for (const span of linkLeakSpans(text, scope(omit.links), skipImages)) {
+                spans.push({ ...span, kind: 'link', hit: LINK_HIT });
+            }
+        }
+        if (omit.markers) {
+            const patterns = [
+                new RegExp(SYSTEM_BOUNDARY.source, 'gi'),
+                ...(note ? [notePattern(note)] : []),
+            ];
+            for (const match of patterns.flatMap((pattern) => [...text.matchAll(pattern)])) {
+                const start = match.index;
+                spans.push({
+                    start,
+                    end: start + match[0].length,
+                    kind: 'instructions',
+                    hit: MARKER_HIT,
+                });
+            }
+        }
+        if (canary) {
+            for (const [start, end] of canaryLeakRanges(text, canary)) {
+                spans.push({ start, end, kind: 'instructions', hit: CANARY_HIT });
+            }
+        }
+        if (privateSystem) {
+            for (const [start, end] of promptEchoRanges(text, privateSystem, slot)) {
+                spans.push({ start, end, kind: 'instructions', hit: PROMPT_ECHO_HIT });
+            }
+        }
+        return spans;
+    }
+    /** The mark `at` falls inside, if any. */
+    function markAt(at) {
+        return marks.find((mark) => mark.start < at && at < mark.end);
+    }
+    /** `out + held` from `from` to `to`, mark boundaries both, each placeholder as the text it replaced. */
+    function rawOf(from, to) {
+        const whole = out + held;
+        let text = '';
+        let at = from;
+        for (const mark of marks) {
+            if (mark.end <= from || mark.start >= to)
+                continue;
+            text += whole.slice(at, mark.start) + mark.raw;
+            at = mark.end;
+        }
+        return text + whole.slice(at, to);
+    }
+    /**
+     * The thought from far enough back that a leak reaching the held text
+     * starts inside, placeholders read as what they replaced; none when no
+     * placeholder is that close, as it then reads as the thought does.
+     */
+    function rawView() {
+        const whole = out + held;
+        for (let reach = CANARY_LEAK_REACH;; reach *= 2) {
+            let from = out.length;
+            let length = 0;
+            for (let i = marks.length - 1; from > 0 && length < reach;) {
+                const mark = marks[i];
+                if (mark && mark.end > from) {
+                    i--;
+                }
+                else if (mark && mark.end === from) {
+                    length += mark.raw.length;
+                    from = mark.start;
+                    i--;
+                }
+                else {
+                    const stop = Math.max(mark?.end ?? 0, from - (reach - length));
+                    length += from - stop;
+                    from = stop;
+                }
+            }
+            marks = marks.filter((mark) => mark.end > from);
+            if (marks.length === 0)
+                return undefined;
+            const view = { text: '', held: 0, pieces: [] };
+            let at = from;
+            for (const mark of [...marks, undefined]) {
+                const plain = mark ? mark.start : whole.length;
+                if (plain > at)
+                    view.pieces.push({ raw: view.text.length, shown: at });
+                if (at <= out.length && out.length <= plain)
+                    view.held = view.text.length + out.length - at;
+                view.text += whole.slice(at, plain);
+                if (!mark)
+                    break;
+                view.pieces.push({ raw: view.text.length, shown: mark.start, mark });
+                view.text += mark.raw;
+                at = mark.end;
+            }
+            // why: An echo run is counted in words: read back until it fits, or the thought starts.
+            if (!privateSystem || from === 0 || promptEchoScanFrom(view.text, view.held) > 0)
+                return view;
+        }
+    }
+    /** The leaks the raw view finds that leave something held still shown, as spans of the thought. */
+    function rawLeaks() {
+        const view = rawView();
+        if (!view)
+            return [];
+        const ranges = [];
+        if (canary) {
+            for (const [start, end] of canaryLeakRanges(view.text, canary)) {
+                ranges.push([start, end, CANARY_HIT]);
+            }
+        }
+        if (privateSystem) {
+            for (const [start, end] of promptEchoRanges(view.text, privateSystem, slot)) {
+                ranges.push([start, end, PROMPT_ECHO_HIT]);
+            }
+        }
+        const spans = [];
+        for (const [rawStart, rawEnd, hit] of ranges) {
+            if (rawEnd <= view.held)
+                continue;
+            const start = shownAt(view, rawStart);
+            const end = shownAt(view, rawEnd, true);
+            let shows = false;
+            for (let at = Math.max(start, out.length); at < end && !shows; at++) {
+                shows = !marks.some((mark) => mark.start <= at && at < mark.end);
+            }
+            if (shows)
+                spans.push({ start, end, kind: 'instructions', hit });
+        }
+        return spans;
+    }
+    /** Every leak in the thought, as shown and as written, overlapping ones as one. */
+    function allLeaks() {
+        return merged([...leakSpans(out + held), ...rawLeaks()]);
+    }
+    /** The leaks reaching into the held text, in order. */
+    function heldLeaks() {
+        return allLeaks().filter(({ end }) => end > out.length);
+    }
+    /** `at` moved off the inside of a placeholder: back to its start, or with `end` on to its end. */
+    function offMark(at, end = false) {
+        const mark = markAt(at);
+        return mark ? (end ? mark.end : mark.start) : at;
+    }
+    /**
+     * Replace each leak reaching into the held text with its placeholder, but
+     * for one reaching its end, which the next chunk could continue: that one is
+     * held whole (`open`) unless the thought has ended. False when nothing was replaced.
+     */
+    function omitHeld(ended) {
+        const spans = heldLeaks();
+        const whole = out + held;
+        const tail = spans.at(-1);
+        const growing = !ended && tail !== undefined && tail.end >= whole.length ? tail : undefined;
+        const closed = growing ? spans.slice(0, -1) : spans;
+        const kept = marks.filter((mark) => mark.end <= out.length);
+        let next = '';
+        let at = out.length;
+        /** Copy `whole` up to `to`, and the marks in it. */
+        const copy = (to) => {
+            const shift = out.length + next.length - at;
+            for (const mark of marks) {
+                if (mark.start >= at && mark.end <= to) {
+                    kept.push({ ...mark, start: mark.start + shift, end: mark.end + shift });
+                }
+            }
+            next += whole.slice(at, Math.max(at, to));
+            at = Math.max(at, to);
+        };
+        for (const { start, end, kind, hit } of closed) {
+            copy(offMark(start));
+            // why: A leak set to `block` takes the rest of the thought with it.
+            cut = ends?.has(hit.rule) ?? false;
+            const to = cut ? whole.length : Math.max(at, offMark(end, true));
+            const text = placeholder(kind, out + next);
+            const begin = out.length + next.length;
+            kept.push({ start: begin, end: begin + text.length, raw: rawOf(at, to) });
+            next += text;
+            hits.set(hit.rule, hit);
+            at = to;
+            if (cut)
+                break;
+        }
+        open = undefined;
+        if (growing && !cut) {
+            copy(offMark(growing.start));
+            open = out.length + next.length;
+        }
+        copy(whole.length);
+        marks = kept;
+        held = next;
+        openingFrom = 0;
+        return closed.length > 0;
+    }
+    /** Omit the held text from the first leak on; all of it when the leak is in what was shown. */
+    function cutRest() {
+        const first = allLeaks()[0];
+        const from = first ? Math.max(0, offMark(first.start) - out.length) : 0;
+        const kept = held.slice(0, from);
+        const text = placeholder(first?.kind ?? 'instructions', out + kept);
+        const begin = out.length + from;
+        const raw = rawOf(begin, out.length + held.length);
+        marks = marks.filter((mark) => mark.end <= begin);
+        marks.push({ start: begin, end: begin + text.length, raw });
+        held = kept + text;
+        openingFrom = 0;
+        if (first)
+            hits.set(first.hit.rule, first.hit);
+        open = undefined;
+        cut = true;
+    }
+    /** What the readers read: the thought up to a leak still growing. */
+    function readable() {
+        const whole = out + held;
+        return open === undefined ? whole : whole.slice(0, open);
+    }
+    /** Omit leaks until fresh readers over the thought settle none; failing that, the rest. */
+    function settle() {
+        for (let round = 0; round < MAX_ROUNDS; round++) {
+            if (leaks >= MAX_LEAKS)
+                break;
+            const before = new Set(marks.map((mark) => mark.start));
+            if (!omitHeld(false)) {
+                // why: A leak the readers settled that no span covers is cut, not shown.
+                if (open === undefined)
+                    break;
+                return;
+            }
+            if (cut)
+                return;
+            // why: A leak running on past its placeholder only grows it.
+            if (marks.some((mark) => !before.has(mark.start)))
+                leaks++;
+            if (!restart(readable()))
+                return;
+        }
+        cutRest();
+    }
+    /** The earliest index of `out + held` a leak could still start at, moved back to the start of a word it cuts. */
+    function holdFrom() {
+        const end = out.length + held.length;
+        const url = stream ? stream.holdFrom() : end;
+        const leak = canary ? canaryFrom(canary) : end;
+        const echo = privateSystem ? out.length + promptEchoHoldFrom(held, privateSystem, slot) : end;
+        const from = Math.min(url, leak, echo, rawHoldFrom() ?? end, open ?? end);
+        return offMark(from < out.length ? from : out.length + wordStartAcross(held, from - out.length));
+    }
+    /** `canaryHoldFrom` on the held text, as an index of `out + held`, read from where an opening could start. */
+    function canaryFrom(canary) {
+        const from = Math.max(out.length, openingFrom);
+        const lead = Math.max(0, from - RELEASED_LOOKBACK);
+        let at = lead + canaryOpeningFrom(textFrom(lead), canary);
+        if (at < from && from > out.length) {
+            const whole = Math.max(0, out.length - RELEASED_LOOKBACK);
+            at = whole + canaryOpeningFrom(textFrom(whole), canary);
+        }
+        openingFrom = Math.min(at, out.length + held.length - RELEASED_LOOKBACK);
+        return Math.max(out.length, at);
+    }
+    /** `out + held` from `from` on. */
+    function textFrom(from) {
+        return from < out.length ? out.slice(from) + held : held.slice(from - out.length);
+    }
+    /** The hold as the raw view reads it: an opening a placeholder spent may not be spent. */
+    function rawHoldFrom() {
+        const view = rawView();
+        if (!view)
+            return undefined;
+        const rest = view.text.slice(view.held);
+        const leak = canary ? canaryHoldFrom(rest, canary, view.text.slice(0, view.held)) : rest.length;
+        const echo = privateSystem ? promptEchoHoldFrom(rest, privateSystem, slot) : rest.length;
+        return shownAt(view, view.held + Math.min(leak, echo));
+    }
+    function release(text) {
+        const shown = { text, hits: [...hits.values()] };
+        hits = new Map();
+        return shown;
+    }
+    restart(out);
+    return {
+        push(text) {
+            if (cut || !text)
+                return release('');
+            held += text;
+            if (open !== undefined || read(text) || rawLeaks().length > 0)
+                settle();
+            if (cut)
+                return release('');
+            const clear = Math.max(0, holdFrom() - out.length);
+            const shown = held.slice(0, clear);
+            out += shown;
+            held = held.slice(clear);
+            return release(shown);
+        },
+        flush() {
+            if (!cut) {
+                for (let round = 0; round < MAX_ROUNDS && !cut && omitHeld(true); round++)
+                    ;
+                // why: A leak left is one the text shown already takes part in, such as a definition an image opener held here could use.
+                if (!cut && held && (leakSpans(out + held).length > 0 || rawLeaks().length > 0))
+                    cutRest();
+            }
+            const shown = held;
+            const whole = out + held;
+            out = canary || privateSystem ? promptLeakCarry(whole, canary, privateSystem) : '';
+            const shift = out.length - whole.length;
+            marks = marks
+                .filter((mark) => mark.start + shift >= 0)
+                .map((mark) => ({ ...mark, start: mark.start + shift, end: mark.end + shift }));
+            held = '';
+            openingFrom = 0;
+            open = undefined;
+            cut = false;
+            leaks = 0;
+            restart(out);
+            return release(shown);
+        },
+        carryOut: () => out,
+    };
+}
+/** What several readers of one stretch of a thought found: every hit, once a rule, at the strongest action. */
+function foundBy(...founds) {
+    const all = founds.filter((found) => found !== undefined);
+    if (all.length === 0)
+        return {};
+    return {
+        found: {
+            action: all.reduce((action, found) => stronger(action, found.action), 'allow'),
+            hits: [...new Map(all.flatMap(({ hits }) => hits).map((hit) => [hit.rule, hit])).values()],
+        },
+    };
+}
+/**
+ * `guard` with `guardrails.detect` read at `thought` in front of it: the guard
+ * reads the thought as the detectors let it through. A match set to `block`
+ * ends what is shown of the thought there. The detectors in `leave` are the
+ * guard's own. `guard` unchanged when no other detector reads a thought.
+ */
+function detectingThoughts(guard, detect, scope, leave) {
+    const open = () => createDetectStream('thought', detect, scope, leave);
+    let reader = open();
+    if (!reader)
+        return guard;
+    /** How much of the thought has been written, and how much of that released. */
+    let written = 0;
+    let read = 0;
+    let stopped = false;
+    /** The text now through the detectors, and what they found in it. */
+    function through(ended) {
+        if (stopped || !reader)
+            return { text: '' };
+        const to = ended ? written : Math.max(read, reader.holdFrom());
+        const { action, text = '', hits, taken } = reader.take(read, to, ended);
+        stopped = action === 'block';
+        read += taken;
+        return { text, ...(action === 'allow' ? {} : { found: { action, hits } }) };
+    }
+    return {
+        push(text) {
+            written += text.length;
+            reader?.push(text);
+            const { text: clear, found } = through(false);
+            const shown = guard ? guard.push(clear) : { text: clear, hits: [] };
+            return { text: shown.text, hits: shown.hits, ...foundBy(found, shown.found) };
+        },
+        flush() {
+            const { text: clear, found } = through(true);
+            const last = guard?.push(clear);
+            const rest = guard ? guard.flush() : { text: clear, hits: [] };
+            reader = open();
+            written = 0;
+            read = 0;
+            stopped = false;
+            return {
+                text: (last?.text ?? '') + rest.text,
+                hits: [
+                    ...new Map([...(last?.hits ?? []), ...rest.hits].map((hit) => [hit.rule, hit])).values(),
+                ],
+                ...foundBy(found, last?.found, rest.found),
+            };
+        },
+        carryOut: () => guard?.carryOut() ?? '',
+    };
+}
+/** The detectors a thought guard omits a match of, and the hit it reports for each. */
+const LEAK_DETECTORS = {
+    canary_leak: CANARY_HIT,
+    prompt_leak: PROMPT_ECHO_HIT,
+    marker_leak: MARKER_HIT,
+    ungiven_images: IMAGE_HIT,
+    ungiven_links: LINK_HIT,
+};
+/** The detectors among them the guard reads a thought's own text for; the gate has the other two. */
+const TEXT_LEAKS = ['marker_leak', 'ungiven_images', 'ungiven_links'];
+/**
+ * Reads a thought for the leaks set to `flag`: each is reported once a thought
+ * and the thought shown as written, so nothing is held for it.
+ */
+function flaggedLeaks(scope, planted) {
+    const { canary, privateSystem } = scope;
+    let scanner = canary ? createCanaryScanner(canary) : undefined;
+    let seen = '';
+    let reported = new Set();
+    return {
+        read(text) {
+            const from = promptEchoScanFrom(seen + text, seen.length);
+            seen += text;
+            const hits = [];
+            if (scanner?.push(text))
+                hits.push(CANARY_HIT);
+            if (privateSystem && promptEchoRanges(seen.slice(from), privateSystem, planted).length > 0) {
+                hits.push(PROMPT_ECHO_HIT);
+            }
+            const fresh = hits.filter((hit) => !reported.has(hit.rule));
+            for (const hit of fresh)
+                reported.add(hit.rule);
+            return fresh;
+        },
+        reset() {
+            scanner = canary ? createCanaryScanner(canary) : undefined;
+            seen = '';
+            reported = new Set();
+        },
+    };
+}
+/**
+ * `guard` with what it omitted reported as its detector's finding at `thought`,
+ * beside the leaks `flagged` reads for.
+ */
+function reportingLeaks(guard, detect, flagged, planted) {
+    const flags = flaggedLeaks(flagged, planted);
+    const actions = new Map(Object.entries(LEAK_DETECTORS).map(([detector, hit]) => [
+        hit.rule,
+        detect[detector].thought,
+    ]));
+    function report(release, noted) {
+        const ours = [...noted, ...release.hits.filter((hit) => actions.has(hit.rule))];
+        if (ours.length === 0)
+            return release;
+        const action = ours.reduce((found, hit) => stronger(found, actions.get(hit.rule) ?? 'ignore'), release.found?.action ?? 'allow');
+        return {
+            text: release.text,
+            hits: release.hits.filter((hit) => !actions.has(hit.rule)),
+            found: { action, hits: [...(release.found?.hits ?? []), ...ours] },
+        };
+    }
+    return {
+        push: (text) => report(guard.push(text), flags.read(text)),
+        flush() {
+            flags.reset();
+            return report(guard.flush(), []);
+        },
+        carryOut: () => guard.carryOut(),
+    };
+}
+/**
+ * A guard for a turn's thoughts: the detectors `guardrails.detect` sets at
+ * `thought`. `context` carries the canary and the system instruction only
+ * while their detectors read somewhere (`leakScopeOf`); at `thought`, `redact`
+ * omits a match, `block` ends what is shown of the thought there, and `flag`
+ * reports it and shows it.
+ */
+async function thoughtGuardFor(policy, context, carry) {
+    const { detect } = policy;
+    const own = TEXT_LEAKS.filter((detector) => omitsThought(detect, detector));
+    const omitted = leakScopeAt(detect, context, omitsThought);
+    const flagged = leakScopeAt(detect, context, (set, detector) => set[detector].thought === 'flag');
+    const guarded = own.length > 0 || scoped(omitted) || scoped(flagged);
+    const scope = scopeOf(policy, context);
+    if (guarded || detectReads(['thought'], detect, scope))
+        await loadEgressAutomata();
+    const guard = guarded
+        ? createThoughtGuard({
+            omit: thoughtOmits(policy),
+            ...omitted,
+            ...thoughtEnds(detect),
+            ...thoughtTurn(context),
+            ...(carry ? { carry } : {}),
+        })
+        : undefined;
+    const leaks = guard && reportingLeaks(guard, detect, flagged, context.canary);
+    return detectingThoughts(leaks, detect, scope, own);
+}
+/** Whether `detector` takes its matches out of a thought. */
+function omitsThought(detect, detector) {
+    return detect[detector].thought === 'redact' || detect[detector].thought === 'block';
+}
+/** What `guardrails.detect` omits from a thought by its marker, image, and link detectors. */
+function thoughtOmits({ detect, allow, }) {
+    return {
+        ...(omitsThought(detect, 'marker_leak') ? { markers: true } : {}),
+        ...(omitsThought(detect, 'ungiven_images') ? { images: allow.ungiven_images } : {}),
+        ...(omitsThought(detect, 'ungiven_links') ? { links: allow.ungiven_links } : {}),
+        imagesRead: detect.ungiven_images.thought !== 'ignore',
+    };
+}
+/** The canary and the system instruction, each while `applies` to its detector and the turn has it to read. */
+function leakScopeAt(detect, context, applies) {
+    const canary = applies(detect, 'canary_leak') && !context.canaryGiven && context.canary;
+    const privateSystem = applies(detect, 'prompt_leak') && context.privateSystem;
+    return { ...(canary ? { canary } : {}), ...(privateSystem ? { privateSystem } : {}) };
+}
+function scoped(scope) {
+    return scope.canary !== undefined || scope.privateSystem !== undefined;
+}
+/** The rules whose match ends what is shown of a thought. */
+function thoughtEnds(detect) {
+    const ends = new Set(Object.entries(LEAK_DETECTORS)
+        .filter(([detector]) => detect[detector].thought === 'block')
+        .map(([, hit]) => hit.rule));
+    return ends.size > 0 ? { ends } : {};
+}
+/** What the turn gives a thought guard to read against. */
+function thoughtTurn({ canary, givenUrls, labels, }) {
+    return {
+        ...(canary ? { planted: canary } : {}),
+        ...(givenUrls ? { given: givenUrls } : {}),
+        ...(labels ? { labels } : {}),
+    };
+}
+export { createThoughtGuard, thoughtGuardFor };