@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/canary.js

@@ -0,0 +1,974 @@
+import { sha256 } from '../kernel/engine/hash.js';
+import { mapStrings } from '../kernel/engine/tree.js';
+import { turnEventSchema, } from '../kernel/turn-events.js';
+import { OMIT_CANARY } from '../observability/spans.js';
+import { labelText } from './labels.js';
+import { promptEchoScanFrom, scanTextForPromptEcho } from './prompt-echo.js';
+import { scanTextOf, textForScan } from './serialize.js';
+/** The tag that opens the fence around user content. */
+const USER_OPEN = '<user_data>';
+/** The tag that closes the fence around user content. */
+const USER_CLOSE = '</user_data>';
+/** The tag that closes the fence around context. */
+const CONTEXT_CLOSE = '</page_context>';
+const CANARY_BYTES = 16;
+const HEX_RADIX = 16;
+const HEX_PAD = 2;
+/** What replaces canary text a reply or event would have carried. */
+/** A fence tag as a model could read one: spacing, case and closing `>` aside. */
+const FENCE = /<\s*(?:\/\s*)?(?:user[\s_-]*data|page[\s_-]*context)\b(?:[^<>\n]{0,40}>|\s*(?:\/\s*)?>)?/gi;
+/** Creates a 128-bit, cryptographically random token for one turn's canary binding. */
+function mintCanary() {
+    const bytes = new Uint8Array(CANARY_BYTES);
+    crypto.getRandomValues(bytes);
+    let hex = '';
+    for (const byte of bytes) {
+        hex += byte.toString(HEX_RADIX).padStart(HEX_PAD, '0');
+    }
+    return hex;
+}
+/**
+ * A profile's canary for a system prompt: the same on every turn that sends
+ * that prompt, so the prompt a provider caches stays the same.
+ */
+async function profileCanary(profileId, system) {
+    const hash = await sha256(JSON.stringify(['theorem.canary', profileId, system]));
+    return hash.slice(0, CANARY_BYTES * HEX_PAD);
+}
+/**
+ * Whether a request gives the model `canary` outside its system prompt: in
+ * its input, or in a history message the model did not write.
+ * `scanned` skips what an earlier step of the turn already read.
+ */
+function requestGivesCanary(request, canary, scanned) {
+    const given = [request.input, ...(request.history ?? [])];
+    for (const part of given) {
+        if (('role' in part && part.role === 'assistant') || scanned.has(part))
+            continue;
+        scanned.add(part);
+        if (scanTextForCanaryLeak(textForScan(part).text, canary))
+            return true;
+    }
+    return false;
+}
+function stripUserFences(text) {
+    // why: Until none is left: removing one can join the text around it into another.
+    let stripped = text;
+    for (let last = ''; stripped !== last;) {
+        last = stripped;
+        stripped = stripped.replaceAll(FENCE, '');
+    }
+    return stripped.trim();
+}
+/**
+ * Removes pre-existing user-data fences, trims the input, and encloses the result
+ * in the canonical user-data fence used by the guardrail prompt contract.
+ */
+function wrapUserData(text) {
+    return `${USER_OPEN}\n${stripUserFences(text)}\n${USER_CLOSE}`;
+}
+/**
+ * Encloses context in the fence that names its sender, with any fence already in it removed, so
+ * neither the page nor the person can pass text off as the host's.
+ */
+function wrapContext(sender, text) {
+    return `<page_context from="${sender}">\n${stripUserFences(text)}\n${CONTEXT_CLOSE}`;
+}
+/** The labels' `context.note`, which tells the model what `wrapContext`'s tags mean. */
+function contextNote(labels) {
+    return labelText('context.note', {}, labels);
+}
+/**
+ * The note is the labels' `canary.bind_note`: the profile's `labels`, then
+ * `overrideLabels`, then the default. Every override is checked for the
+ * `{canary}` placeholder when it is set — a note without the token binds nothing.
+ */
+function bindCanary(system, canary, labels) {
+    const note = canaryNote(canary, labels);
+    if (!note) {
+        return system;
+    }
+    if (!system) {
+        return note;
+    }
+    return `${system}\n\n${note}`;
+}
+/** The note `bindCanary` appends, or nothing without a canary. */
+function canaryNote(canary, labels) {
+    return canary ? labelText('canary.bind_note', { canary }, labels) : '';
+}
+/**
+ * The words of the note `labels` binds, without the canary: its text before
+ * the canary, or after it when nothing comes before. A reply repeating them
+ * repeats the system prompt. Undefined when the note has no words of its own.
+ */
+function canaryNoteMarker(labels) {
+    const pieces = canaryNote('\u0000', labels)
+        .split('\u0000')
+        .map((piece) => piece.trim());
+    return pieces.find((piece) => piece.length > 0);
+}
+/** The labels' `user_data.note`, which tells the model what `wrapUserData`'s tags mean. */
+function userDataNote(labels) {
+    return labelText('user_data.note', {}, labels);
+}
+/**
+ * Lookalike letters the scan reads as the Latin letter they imitate, for the
+ * letters a hex token and its transforms are written with (a–f, n–s).
+ */
+const CONFUSABLES = {
+    а: 'a',
+    ɑ: 'a',
+    α: 'a',
+    ь: 'b',
+    в: 'b',
+    β: 'b',
+    с: 'c',
+    ϲ: 'c',
+    ԁ: 'd',
+    е: 'e',
+    ε: 'e',
+    о: 'o',
+    ο: 'o',
+    օ: 'o',
+    р: 'p',
+    ρ: 'p',
+    ԛ: 'q',
+    ѕ: 's',
+};
+/** Spoken names the word reading maps to the character they spell. */
+const SPELLED = {
+    zero: '0',
+    one: '1',
+    two: '2',
+    three: '3',
+    four: '4',
+    five: '5',
+    six: '6',
+    seven: '7',
+    eight: '8',
+    nine: '9',
+    alpha: 'a',
+    alfa: 'a',
+    bravo: 'b',
+    charlie: 'c',
+    delta: 'd',
+    echo: 'e',
+    foxtrot: 'f',
+    november: 'n',
+    oscar: 'o',
+    papa: 'p',
+    quebec: 'q',
+    romeo: 'r',
+    sierra: 's',
+};
+/** The longest name in `SPELLED`: the most text one character of a leak can cover. */
+const LONGEST_SPELLED = Math.max(...Object.keys(SPELLED).map((word) => word.length));
+const WORD_CHAR = /^[\p{L}\p{N}]$/u;
+const ASCII_END = 0x80;
+function isAsciiAlphanumeric(code) {
+    return ((code >= 0x30 && code <= 0x39) ||
+        (code >= 0x41 && code <= 0x5a) ||
+        (code >= 0x61 && code <= 0x7a));
+}
+function isWordChar(char) {
+    const code = char.charCodeAt(0);
+    return code < ASCII_END ? isAsciiAlphanumeric(code) : WORD_CHAR.test(char);
+}
+/** Standard base64 characters: letters, digits, `+`, `/`. */
+function isBase64Char(char) {
+    const code = char.charCodeAt(0);
+    return char === '+' || char === '/' || (code < ASCII_END && isAsciiAlphanumeric(code));
+}
+/** The last text folded, per case mode: every form of one scan reads the same text. */
+const foldCache = new Map();
+function foldText(text, foldCase) {
+    const cached = foldCache.get(foldCase);
+    if (cached?.text === text) {
+        return cached.chars;
+    }
+    const chars = foldChars(text, foldCase);
+    foldCache.set(foldCase, { text, chars });
+    return chars;
+}
+/** The characters of `text` as the scan reads them; `offset` is where `text` starts in the stream. */
+function foldChars(text, foldCase, offset = 0) {
+    const out = [];
+    let at = offset;
+    for (const point of text) {
+        const to = at + point.length;
+        const lower = foldCase ? point.toLowerCase() : point;
+        const folded = point < '\u0080' ? lower : (CONFUSABLES[lower] ?? lower.normalize('NFKC'));
+        for (const char of folded) {
+            const read = foldCase ? char.toLowerCase() : char;
+            out.push({ char: read, at, to, word: isWordChar(read) });
+        }
+        at = to;
+    }
+    return out;
+}
+/**
+ * The most text allowed between two characters of one leak. Further apart,
+ * they are not read as one token, so an opening stops being held once this
+ * much text follows it: the hold stays short however sparse the alphabet.
+ */
+const LEAK_GAP = 32;
+/** Marks a gap wider than `LEAK_GAP` in a projection; no form's value contains it. */
+const GAP = ' ';
+function newProjection() {
+    return { kept: '', at: [], to: [] };
+}
+function breakGap(projection, at) {
+    const last = projection.to.at(-1);
+    if (last !== undefined && at - last > LEAK_GAP && !projection.kept.endsWith(GAP)) {
+        projection.kept += GAP;
+        projection.at.push(last);
+        projection.to.push(last);
+    }
+}
+/** Close a projection: an opening followed by more than `LEAK_GAP` of text is spent. */
+function finish(projection, length) {
+    breakGap(projection, length);
+    return projection;
+}
+function keep(projection, char, at, to) {
+    breakGap(projection, at);
+    projection.kept += char;
+    projection.at.push(at);
+    projection.to.push(to);
+}
+/**
+ * How many consecutive characters of a form count as a leak: 16 of the token
+ * (64 bits), so a truncated or partly split token is still caught. A form
+ * shorter than its run is matched whole.
+ */
+const TOKEN_LEAK_RUN = 16;
+/** The same 64+ bits written as base64 (6 bits a character) or byte codes (2–3 digits a byte). */
+const BASE64_LEAK_RUN = 20;
+const BYTE_CODE_LEAK_RUN = 32;
+const HEX_RADIX_OUT = 16;
+const BASE64_EDGE = /^[A-Za-z0-9+/=_-]$/;
+const BASE64_GROUP = 3;
+const BASE64_GROUP_CHARS = 4;
+const ROT13_SHIFT = 13;
+const LATIN_LETTERS = 26;
+const LOWER_A = 'a'.charCodeAt(0);
+function rot13(text) {
+    return text.replace(/[a-z]/g, (char) => String.fromCharCode(((char.charCodeAt(0) - LOWER_A + ROT13_SHIFT) % LATIN_LETTERS) + LOWER_A));
+}
+function trimProjection(projection, length) {
+    const dropped = Math.max(0, projection.kept.length - length);
+    if (dropped > 0) {
+        projection.kept = projection.kept.slice(dropped);
+        projection.at.splice(0, dropped);
+        projection.to.splice(0, dropped);
+    }
+    return dropped;
+}
+/** A reader whose every character settles as it is read. */
+function settledReader(accept) {
+    const projection = newProjection();
+    return {
+        projection,
+        read(chars) {
+            for (const { char, at, to } of chars) {
+                const kept = accept(char);
+                if (kept !== undefined)
+                    keep(projection, kept, at, to);
+            }
+        },
+        openKept: () => '',
+        close: (length) => finish(projection, length),
+        shrunkTo: () => projection.kept.length,
+        trim: (length) => trimProjection(projection, length),
+    };
+}
+/** Reads, case-folded, each character of `alphabet` wherever it stands. */
+function byCharacter(alphabet) {
+    return {
+        key: `char:${[...alphabet].sort().join('')}`,
+        foldCase: true,
+        open: () => settledReader((char) => (alphabet.has(char) ? char : undefined)),
+    };
+}
+/** The last projection of each reading: forms with the same reading share it within a scan. */
+const projectionCache = new Map();
+/** `text` as `reading` reads it, whole. */
+function project(reading, text) {
+    const cached = projectionCache.get(reading.key);
+    if (cached?.text === text) {
+        return cached.projection;
+    }
+    const reader = reading.open();
+    reader.read(foldText(text, reading.foldCase));
+    const projection = reader.close(text.length);
+    projectionCache.set(reading.key, { text, projection });
+    return projection;
+}
+/** The token characters a word cut off by the end of the text could still spell. */
+function couldSpell(written, alphabet) {
+    return Object.entries(SPELLED)
+        .filter(([name, char]) => name.startsWith(written) && alphabet.has(char))
+        .map(([, char]) => char)
+        .join('');
+}
+/**
+ * The shortest opening of a leak the hold keeps back. Shorter openings go out,
+ * so ordinary text is not held on every letter a token could start with; the
+ * cost is that a blocked leak shows the host at most this many characters less
+ * one — 3 of a 16-character run, where any run under 16 already passes.
+ */
+const CANARY_OPENING_MIN = 4;
+/** `CANARY_OPENING_MIN`, scaled down for a form whose leak run is short. */
+function openingMin(form) {
+    return Math.min(CANARY_OPENING_MIN, Math.ceil(form.min / CANARY_OPENING_MIN));
+}
+const ANY_OPENING = () => 1;
+/**
+ * Where the opening of `form` at the end of `kept` starts, if one is at least
+ * `shortest` long: any piece of the token it goes on past, as a run can start
+ * anywhere in it.
+ */
+function openingFrom(kept, at, form, shortest) {
+    const continued = form.value.slice(0, -1);
+    for (let size = Math.min(kept.length, continued.length); size >= shortest; size--) {
+        if (continued.includes(kept.slice(kept.length - size))) {
+            return at[kept.length - size];
+        }
+    }
+    return undefined;
+}
+/**
+ * A word longer than this can be neither a spoken name nor one behind `0x`:
+ * how it reads is settled but for whether it stays in the alphabet.
+ */
+const LONGEST_WORD_READ = LONGEST_SPELLED + HEX_PAD;
+/** Whether `chars`, a whole word, starts with a `0x` byte prefix; the byte is the word. */
+function isHexByte(chars) {
+    return chars.length > HEX_PAD && chars[0]?.char === '0' && chars[1]?.char === 'x';
+}
+/**
+ * Reads one word into `projection`; `open` when the text ends inside it, so
+ * it may still grow into another word.
+ */
+function readWord(projection, chars, alphabet, open) {
+    const word = isHexByte(chars) ? chars.slice(HEX_PAD) : chars;
+    const written = word.map((c) => c.char).join('');
+    if (open) {
+        breakGap(projection, word[0]?.at ?? 0);
+        projection.unfinished = {
+            at: chars[0]?.at ?? 0,
+            settled: projection.kept.length,
+            spells: couldSpell(written, alphabet),
+        };
+    }
+    const spelled = SPELLED[written];
+    if (spelled !== undefined && alphabet.has(spelled)) {
+        keep(projection, spelled, word[0]?.at ?? 0, word.at(-1)?.to ?? 0);
+    }
+    else if (word.every((c) => alphabet.has(c.char))) {
+        for (const { char, at, to } of word)
+            keep(projection, char, at, to);
+    }
+}
+/**
+ * Reads word by word: a word written only in `alphabet` counts in full, a
+ * spoken name (`SPELLED`) counts as the character it spells, and any other
+ * word is a separator. "3, then f" reads as "3f"; "zero one" as "01".
+ *
+ * A word longer than `LONGEST_WORD_READ` is read as it streams: its
+ * characters are kept as they come while every one is in the alphabet, and
+ * taken back out if one is not. However long the word, each character is
+ * read once.
+ */
+function byWord(alphabet) {
+    return {
+        key: `word:${[...alphabet].sort().join('')}`,
+        foldCase: true,
+        open: () => wordReader(alphabet),
+    };
+}
+function wordReader(alphabet) {
+    const projection = newProjection();
+    /** The open word. */
+    let word = [];
+    /** A long open word: how long `kept` was before it, and after the gap in front of it. */
+    let long;
+    let shrunk = 0;
+    function truncate(length) {
+        projection.kept = projection.kept.slice(0, length);
+        projection.at.length = length;
+        projection.to.length = length;
+        shrunk = Math.min(shrunk, length);
+    }
+    /** The open word just grew past `LONGEST_WORD_READ`: keep it while it is in the alphabet. */
+    function lengthen() {
+        const body = isHexByte(word) ? word.slice(HEX_PAD) : word;
+        const before = projection.kept.length;
+        breakGap(projection, body[0]?.at ?? 0);
+        long = { before, after: projection.kept.length, broken: false };
+        if (body.every((c) => alphabet.has(c.char))) {
+            for (const { char, at, to } of body)
+                keep(projection, char, at, to);
+        }
+        else {
+            breakWord();
+        }
+    }
+    /** The long open word has a character outside the alphabet: it is a separator. */
+    function breakWord() {
+        if (long && !long.broken) {
+            truncate(Math.max(0, long.before));
+            long.broken = true;
+        }
+    }
+    function grow(char) {
+        word.push(char);
+        if (word.length === LONGEST_WORD_READ + 1) {
+            lengthen();
+        }
+        else if (long && !long.broken) {
+            if (alphabet.has(char.char))
+                keep(projection, char.char, char.at, char.to);
+            else
+                breakWord();
+        }
+    }
+    function settle() {
+        // why: A long word's characters are already kept, or already taken back out.
+        if (!long)
+            readWord(projection, word, alphabet, false);
+        word = [];
+        long = undefined;
+    }
+    return {
+        projection,
+        read(chars) {
+            for (const char of chars) {
+                if (char.word)
+                    grow(char);
+                else if (word.length > 0)
+                    settle();
+            }
+        },
+        openKept() {
+            if (word.length === 0 || long) {
+                return '';
+            }
+            // why: Only `kept` is read back: the gap check needs just the last offset.
+            const view = { kept: projection.kept, at: [], to: projection.to.slice(-1) };
+            readWord(view, word, alphabet, true);
+            return view.kept.slice(projection.kept.length);
+        },
+        close(length) {
+            if (word.length > 0 && !long) {
+                readWord(projection, word, alphabet, true);
+            }
+            else if (long) {
+                const body = isHexByte(word) ? word.slice(HEX_PAD) : word;
+                breakGap(projection, body[0]?.at ?? 0);
+                projection.unfinished = {
+                    at: word[0]?.at ?? 0,
+                    settled: long.broken ? projection.kept.length : long.after,
+                    spells: '',
+                };
+            }
+            return finish(projection, length);
+        },
+        shrunkTo() {
+            const least = shrunk;
+            shrunk = projection.kept.length;
+            return least;
+        },
+        trim(length) {
+            // why: A long word still kept may yet be taken back out, leaving what came
+            // before it to continue a run: keep `length` characters in front of it.
+            // Once its text spans more than `LEAK_GAP`, nothing before it can join a
+            // run after it, so that can go too. Its text, not what it folds to: a
+            // ligature keeps two characters for one.
+            const kept = long && !long.broken ? long : undefined;
+            const span = (word.at(-1)?.to ?? 0) - (word[0]?.at ?? 0);
+            const shallow = kept && span <= LEAK_GAP;
+            const dropped = trimProjection(projection, shallow ? projection.kept.length - kept.before + length : length);
+            if (kept) {
+                kept.before -= dropped;
+                kept.after -= dropped;
+            }
+            shrunk -= dropped;
+            return dropped;
+        },
+    };
+}
+/** Reads base64 characters wherever they stand; every base64 form shares the reading. */
+const readBase64 = {
+    key: 'base64',
+    foldCase: false,
+    // why: URL-safe base64 reads as standard; padding is not part of the token.
+    open: () => settledReader((char) => {
+        const standard = char === '-' ? '+' : char === '_' ? '/' : char;
+        return isBase64Char(standard) ? standard : undefined;
+    }),
+};
+/**
+ * The base64 of the token at each of the three byte offsets it can start at
+ * inside larger encoded text, trimmed to the groups made of token bytes only.
+ */
+function base64Cores(bytes) {
+    const cores = [];
+    for (let offset = 0; offset < BASE64_GROUP; offset++) {
+        const encoded = btoa('\0'.repeat(offset) + bytes);
+        const first = Math.ceil(offset / BASE64_GROUP);
+        const last = Math.floor((offset + bytes.length) / BASE64_GROUP);
+        cores.push(encoded.slice(first * BASE64_GROUP_CHARS, last * BASE64_GROUP_CHARS));
+    }
+    return cores;
+}
+/** The bytes a hex token spells, as a binary string; `undefined` for any other token. */
+function decodedHexBytes(literal) {
+    if (literal.length % HEX_PAD !== 0 || !/^[0-9a-f]+$/.test(literal)) {
+        return undefined;
+    }
+    let bytes = '';
+    for (let at = 0; at < literal.length; at += HEX_PAD) {
+        bytes += String.fromCharCode(Number.parseInt(literal.slice(at, at + HEX_PAD), HEX_RADIX_OUT));
+    }
+    return bytes;
+}
+function leakRun(value, run) {
+    return Math.min(value.length, run);
+}
+let formsCache;
+/**
+ * Every form a leaked canary is detected in: the token itself, reversed, and
+ * in ROT13 — each read character by character and word by word — its
+ * characters as hex or decimal codes, and its base64 at every byte offset; a
+ * hex token also as the bytes it spells, in decimal or base64. The token carries no fixed prefix, so no form
+ * depends on a marker the model could drop or split off.
+ */
+function canaryLeakForms(canary) {
+    if (formsCache?.canary === canary) {
+        return formsCache.forms;
+    }
+    const literal = canary.toLowerCase();
+    const forms = [];
+    const seen = new Set();
+    // why: A token that reads the same reversed, or has no letters to rotate, is already covered.
+    for (const value of [literal, [...literal].reverse().join(''), rot13(literal)]) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        const alphabet = new Set(value);
+        const min = leakRun(value, TOKEN_LEAK_RUN);
+        forms.push({ value, min, reading: byCharacter(alphabet) });
+        forms.push({ value, min, reading: byWord(alphabet) });
+    }
+    const codes = [...canary].map((char) => char.charCodeAt(0));
+    const decoded = decodedHexBytes(literal);
+    for (const value of [
+        codes.map((code) => code.toString(HEX_RADIX_OUT).padStart(HEX_PAD, '0')).join(''),
+        codes.join(''),
+        ...(decoded ? [[...decoded].map((char) => char.charCodeAt(0)).join('')] : []),
+    ]) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        forms.push({
+            value,
+            min: leakRun(value, BYTE_CODE_LEAK_RUN),
+            reading: byCharacter(new Set(value)),
+        });
+    }
+    try {
+        for (const value of [...base64Cores(canary), ...(decoded ? base64Cores(decoded) : [])]) {
+            if (value && !seen.has(value)) {
+                seen.add(value);
+                forms.push({
+                    value,
+                    min: leakRun(value, BASE64_LEAK_RUN),
+                    reading: readBase64,
+                    edge: BASE64_EDGE,
+                });
+            }
+        }
+    }
+    catch {
+        /* why: a host canary outside Latin-1 has no base64 form */
+    }
+    formsCache = { canary, forms };
+    return forms;
+}
+/** Every `[start, end)` in `kept` holding `min` or more consecutive characters of `value`. */
+function leakRunsIn(kept, form) {
+    const runs = [];
+    for (let from = 0; from + form.min <= form.value.length; from++) {
+        const piece = form.value.slice(from, from + form.min);
+        for (let found = kept.indexOf(piece); found >= 0; found = kept.indexOf(piece, found + 1)) {
+            runs.push([found, found + form.min]);
+        }
+    }
+    return runs;
+}
+function widen(text, [start, end], edge) {
+    if (!edge) {
+        return [start, end];
+    }
+    let from = start;
+    while (from > 0 && start - from < BASE64_GROUP_CHARS && edge.test(text.charAt(from - 1)))
+        from--;
+    let to = end;
+    while (to < text.length && to - end < BASE64_GROUP_CHARS && edge.test(text.charAt(to)))
+        to++;
+    return [from, to];
+}
+/**
+ * Offsets `[start, end)` of `text` covering each leak, ordered by start. One
+ * stretch read as a leak under several forms is one leak: ranges that overlap
+ * are joined.
+ */
+function canaryLeakRanges(text, canary) {
+    const ranges = [];
+    for (const form of canaryLeakForms(canary)) {
+        const { kept, at, to } = project(form.reading, text);
+        for (const [start, end] of leakRunsIn(kept, form)) {
+            ranges.push(widen(text, [at[start] ?? 0, to[end - 1] ?? 0], form.edge));
+        }
+    }
+    const joined = [];
+    for (const [start, end] of ranges.sort((a, b) => a[0] - b[0])) {
+        const last = joined.at(-1);
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            joined.push([start, end]);
+    }
+    return joined;
+}
+/** Leak detection over `canaryLeakForms` only, not general-purpose encoded-data detection. */
+function scanTextForCanaryLeak(text, canary) {
+    if (!text || !canary) {
+        return false;
+    }
+    return canaryLeakForms(canary).some((form) => leakRunsIn(project(form.reading, text).kept, form).length > 0);
+}
+/** Whether `point` starts (`first`) or ends (`last`) in a word, as the scan reads words. */
+function foldsToWord(point, edge) {
+    const chars = foldChars(point, true);
+    return (edge === 'first' ? chars[0] : chars.at(-1))?.word ?? false;
+}
+/**
+ * Where the word `at` would cut in two starts, as the scan reads words; `at`
+ * itself when it cuts none. The start of a word reads as another word once
+ * the rest is omitted ("0This" as "0"), so a release never ends inside one.
+ */
+function wordStartAcross(text, at) {
+    const following = text.codePointAt(at);
+    if (following === undefined || !foldsToWord(String.fromCodePoint(following), 'first')) {
+        return at;
+    }
+    let start = at;
+    while (start > 0) {
+        const pair = start > 1 ? text.slice(start - 2, start) : '';
+        const point = pair.length === 2 && [...pair].length === 1 ? pair : text.slice(start - 1, start);
+        if (!foldsToWord(point, 'last'))
+            break;
+        start -= point.length;
+        if (!foldChars(point, true).every((c) => c.word))
+            break;
+    }
+    return start;
+}
+/**
+ * How much released text the hold rereads: an opening it released holds at
+ * most `CANARY_OPENING_MIN - 1` characters, each at most `LONGEST_WORD_READ`
+ * long and `LEAK_GAP` from the next, and a word cut where this starts reads
+ * as no character.
+ */
+const RELEASED_LOOKBACK = CANARY_OPENING_MIN * (LONGEST_WORD_READ + LEAK_GAP) + LONGEST_WORD_READ;
+/**
+ * How far before a point a leak run reaching past it can start: the longest
+ * run less one character, each read as above.
+ */
+const CANARY_LEAK_REACH = Math.max(TOKEN_LEAK_RUN, BASE64_LEAK_RUN, BYTE_CODE_LEAK_RUN) * (LONGEST_WORD_READ + LEAK_GAP) +
+    LONGEST_WORD_READ;
+/**
+ * Offset from which `text` must stay held: the earliest point where what
+ * follows is an opening of a leak form at least `CANARY_OPENING_MIN` long,
+ * and so could still grow into a leak; 0 when one began in `released`, the
+ * text shown before it. A shorter opening is released; the scan still reads
+ * it with what follows, so the leak it grows into is caught.
+ */
+function canaryHoldFrom(text, canary, released = '') {
+    const lead = released.slice(-RELEASED_LOOKBACK);
+    return Math.max(0, canaryOpeningFrom(lead + text, canary) - lead.length);
+}
+/** Where the earliest opening the hold keeps starts in `text`; its length when none does. */
+function canaryOpeningFrom(text, canary) {
+    return leakOpeningFrom(text, canary, openingMin);
+}
+/** Where the earliest opening of any leak form at least `minimum(form)` long starts in `text`. */
+function leakOpeningFrom(text, canary, minimum) {
+    let from = text.length;
+    if (!canary) {
+        return from;
+    }
+    for (const form of canaryLeakForms(canary)) {
+        const { kept, at, unfinished } = project(form.reading, text);
+        const shortest = minimum(form);
+        const openings = [openingFrom(kept, at, form, shortest)];
+        if (unfinished) {
+            // why: An opening before the last word stays held until that word ends, whatever it reads as now.
+            const settled = kept.slice(0, unfinished.settled);
+            openings.push(openingFrom(settled, at, form, shortest));
+            // why: The last word may still grow into a spelled character that makes one long enough.
+            const grown = [...at.slice(0, unfinished.settled), unfinished.at];
+            for (const char of unfinished.spells) {
+                openings.push(openingFrom(settled + char, grown, form, shortest));
+            }
+        }
+        for (const opening of openings) {
+            if (opening !== undefined)
+                from = Math.min(from, opening);
+        }
+    }
+    return from;
+}
+/** Settled characters of a reading the stream scan keeps: every leak run is shorter. */
+const SCAN_KEPT = BYTE_CODE_LEAK_RUN;
+/** How long a reading's settled characters grow before the stream scan drops all but `SCAN_KEPT`. */
+const SCAN_TRIM_AT = 8 * SCAN_KEPT;
+const HIGH_SURROGATE_FIRST = 0xd800;
+const HIGH_SURROGATE_LAST = 0xdbff;
+function createCanaryScanner(canary) {
+    const readings = new Map();
+    for (const form of canary ? canaryLeakForms(canary) : []) {
+        const known = readings.get(form.reading.key);
+        if (known)
+            known.forms.push(form);
+        else {
+            readings.set(form.reading.key, {
+                reader: form.reading.open(),
+                foldCase: form.reading.foldCase,
+                forms: [form],
+                checked: 0,
+            });
+        }
+    }
+    let offset = 0;
+    /** A high surrogate the last text ended on, read with the low one that follows. */
+    let split = '';
+    let leaked = false;
+    function check(reading) {
+        const { reader } = reading;
+        // why: Runs ending before `checked` were read clean; a broken word may have moved it back.
+        const checked = Math.min(reading.checked, reader.shrunkTo());
+        const kept = reader.projection.kept + reader.openKept();
+        const found = reading.forms.some((form) => leakRunsIn(kept.slice(Math.max(0, checked - form.min + 1)), form).length > 0);
+        reading.checked = reader.projection.kept.length;
+        if (reading.checked > SCAN_TRIM_AT)
+            reading.checked -= reader.trim(SCAN_KEPT);
+        return found;
+    }
+    return {
+        push(fragment) {
+            if (leaked || !fragment) {
+                return leaked;
+            }
+            let text = split + fragment;
+            const last = text.charCodeAt(text.length - 1);
+            split = last >= HIGH_SURROGATE_FIRST && last <= HIGH_SURROGATE_LAST ? text.slice(-1) : '';
+            text = text.slice(0, text.length - split.length);
+            const folded = new Map();
+            for (const reading of readings.values()) {
+                let chars = folded.get(reading.foldCase);
+                if (!chars) {
+                    chars = foldChars(text, reading.foldCase, offset);
+                    folded.set(reading.foldCase, chars);
+                }
+                reading.reader.read(chars);
+                if (check(reading))
+                    leaked = true;
+            }
+            offset += text.length;
+            return leaked;
+        },
+    };
+}
+/**
+ * The tail of a finished window that could still open a leak: what the next
+ * window of the same canary scans in front of its own text. Carried forward
+ * as it grows, it bounds the carry to one token's length. Unlike the hold it
+ * keeps openings of any length: a leak split across windows is still one run.
+ */
+function canaryCarry(text, canary) {
+    return text.slice(leakOpeningFrom(text, canary, ANY_OPENING));
+}
+/**
+ * What the next window of the same turn or session scans in front of its own:
+ * a possible canary opening, and the words a prompt echo could continue from.
+ */
+function promptLeakCarry(text, canary, privateSystem) {
+    const canaryTail = canary ? text.length - canaryCarry(text, canary).length : text.length;
+    const from = privateSystem
+        ? Math.min(canaryTail, promptEchoScanFrom(text, text.length))
+        : canaryTail;
+    return text.slice(from);
+}
+function redactCanaryText(text, canary) {
+    if (!text || !canary) {
+        return text;
+    }
+    let out = '';
+    let from = 0;
+    for (const [start, end] of canaryLeakRanges(text, canary)) {
+        if (start >= from) {
+            out += `${text.slice(from, start)}${OMIT_CANARY}`;
+        }
+        from = Math.max(from, end);
+    }
+    return out + text.slice(from);
+}
+/**
+ * Nothing in a thought stops the turn: `thought-guard.ts` omits what in it
+ * leaks. Every outbound gate reads this before scanning.
+ */
+function isGuardedOutput(event) {
+    return event.type !== 'thought';
+}
+/**
+ * What of an event reaches the host as content, field by field: the one list
+ * every canary and prompt-leak scan reads. Builder-only fields
+ * (`errorInternal`), counts, identities, and media bytes are not content.
+ */
+function hostContentOf(event) {
+    switch (event.type) {
+        case 'text':
+        case 'thought':
+            return [event.text];
+        case 'structured':
+            return [event.structured];
+        case 'grounding':
+            return [event.grounding];
+        case 'citation':
+            return [event.sources];
+        case 'compaction':
+            return [event.summary];
+        case 'evidence':
+            return [event.evidence, event.text, event.sessionResumptionHandle];
+        case 'session':
+            return [event.session];
+        case 'tool':
+            return [event.tool];
+        case 'tool_draft':
+        case 'structured_draft':
+            return [event.text];
+        case 'error':
+            return [event.error, event.errorCopy];
+        case 'custom':
+            return [event.data];
+        case 'reasoning':
+            return [event.text];
+        case 'attempt':
+        case 'media':
+        case 'tokens':
+        case 'guardrail':
+        case 'stage':
+        case 'done':
+        case 'response':
+        case 'provider_checkpoint':
+        case 'provider_warning':
+            return [];
+        default: {
+            const unhandled = event;
+            return unhandled;
+        }
+    }
+}
+/**
+ * The text of each field of an event's host content (`hostContentOf`), one
+ * string per field. Unguarded output (`isGuardedOutput`) carries none.
+ */
+function guardedEventTexts(event) {
+    if (!isGuardedOutput(event)) {
+        return [];
+    }
+    return hostContentOf(event)
+        .map((field) => scanTextOf(field))
+        .filter((text) => text !== '');
+}
+/**
+ * Whether any field of an event's host content (`guardedEventTexts`) carries
+ * a leak. Unguarded output (`isGuardedOutput`) never carries one.
+ */
+function eventHasCanary(event, canary) {
+    if (!canary) {
+        return false;
+    }
+    return guardedEventTexts(event).some((text) => scanTextForCanaryLeak(text, canary));
+}
+/**
+ * Call `flush` at stream end to release the held tail. With `privateSystem`, a reply
+ * echoing the system prompt (`scanTextForPromptEcho`) is a leak too.
+ */
+function createCanaryStreamGate(canary, privateSystem) {
+    const scanner = createCanaryScanner(canary);
+    let pending = '';
+    /** Released text an opening or a prompt echo could still continue from, read but never re-released. */
+    let released = '';
+    /**
+     * Whether the stream holds a leak once `fragment` arrives, `window` being
+     * the unreleased text it ends. The canary scan reads each character once;
+     * the echo check rereads its own short lookback.
+     */
+    function leaks(fragment, window) {
+        const text = released + window;
+        return (scanner.push(fragment) ||
+            (privateSystem !== undefined &&
+                scanTextForPromptEcho(text.slice(promptEchoScanFrom(text, released.length)), privateSystem, canary)));
+    }
+    function step(fragment) {
+        const window = pending + fragment;
+        if (leaks(fragment, window)) {
+            return { leak: true };
+        }
+        const safeEnd = canaryHoldFrom(window, canary, released);
+        const emit = window.slice(0, safeEnd);
+        pending = window.slice(safeEnd);
+        released += emit;
+        const echoFrom = privateSystem
+            ? promptEchoScanFrom(released, released.length)
+            : released.length;
+        released = released.slice(Math.min(echoFrom, Math.max(0, released.length - RELEASED_LOOKBACK)));
+        return { leak: false, emit };
+    }
+    return {
+        process(fragment) {
+            if (!fragment) {
+                return { leak: false, emit: '' };
+            }
+            return step(fragment);
+        },
+        flush() {
+            if (leaks('', pending)) {
+                return { leak: true };
+            }
+            const emit = pending;
+            pending = '';
+            return { leak: false, emit };
+        },
+    };
+}
+/**
+ * The reply as it streams: text deltas, and the transcript of spoken output
+ * (Live `output_transcription` evidence). The one stream the outbound gates
+ * scan progressively; everything else is scanned whole per event.
+ */
+function isStreamedCanaryEvent(event) {
+    return (event.type === 'text' ||
+        (event.type === 'evidence' && event.evidence.kind === 'output_transcription'));
+}
+/** The event with the canary replaced by `OMIT_CANARY` in every string it holds. */
+function redactCanary(event, canary) {
+    // why: Replacing strings keeps the event's shape; the parse re-types it.
+    return turnEventSchema.parse(mapStrings(event, (text) => redactCanaryText(text, canary)));
+}
+export { bindCanary, CANARY_LEAK_REACH, canaryHoldFrom, canaryLeakRanges, canaryNote, canaryNoteMarker, canaryOpeningFrom, contextNote, createCanaryScanner, createCanaryStreamGate, eventHasCanary, guardedEventTexts, isStreamedCanaryEvent, mintCanary, OMIT_CANARY, profileCanary, promptLeakCarry, RELEASED_LOOKBACK, redactCanary, redactCanaryText, requestGivesCanary, scanTextForCanaryLeak, USER_CLOSE, USER_OPEN, userDataNote, wordStartAcross, wrapContext, wrapUserData, };