@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/progressive-yield.js

@@ -0,0 +1,281 @@
+import { canaryOpeningFrom, createCanaryScanner, promptLeakCarry, RELEASED_LOOKBACK, } from './canary.js';
+import { detectReads, scopeOf } from './detect-at.js';
+import { createDetectStream } from './detect-stream.js';
+import { promptEchoHits } from './egress.js';
+import { loadEgressAutomata } from './egress-stream.js';
+import { CANARY_HIT } from './hits.js';
+import { promptEchoHoldFrom, promptEchoScanFrom } from './prompt-echo.js';
+/** Call `flush` when the stream ends to release the held tail. */
+async function createProgressiveYieldGate(options) {
+    if (options.detect)
+        await loadEgressAutomata();
+    return progressiveYieldGate(options);
+}
+/** `createProgressiveYieldGate`, once the automata are loaded: a Live cycle opens its next gate mid-stream. */
+function progressiveYieldGate(options) {
+    const { context } = options;
+    const reads = options.detect;
+    const detecting = reads
+        ? createDetectStream(reads.boundary, reads.matrix, reads.scope)
+        : undefined;
+    /** What a match of one of ours does at this gate's boundary. A gate given no matrix stops on it. */
+    const ours = (detector) => reads ? reads.matrix[detector][reads.boundary] : 'block';
+    const canaryAction = ours('canary_leak');
+    const promptAction = ours('prompt_leak');
+    /** The canary a reply must not repeat: none when it was given (`canaryGiven`), or not read here. */
+    const token = context.canaryGiven || canaryAction === 'ignore' ? undefined : context.canary;
+    /** The private system instruction a reply must not repeat: none when not read here. */
+    const privateSystem = promptAction === 'ignore' ? undefined : context.privateSystem;
+    const guarded = token !== undefined || privateSystem !== undefined;
+    const carry = guarded ? (options.carry ?? '') : '';
+    /** The leaks set to `flag` found since the last release, and the rules already reported. */
+    let noted = [];
+    const reported = new Set();
+    let accumulated = '';
+    let emitted = 0;
+    /** The window from `emitted` on. Each piece of the reply is kept apart, so no step rereads the whole. */
+    let held = '';
+    /** The carry and the released window, as far back as the canary hold rereads. */
+    let released = carry.slice(-RELEASED_LOOKBACK);
+    /** The carry and window from where the next prompt echo scan may reach back to. */
+    let echoed = carry;
+    /** Where `echoed` starts in the carry and window. */
+    let echoedFrom = 0;
+    /**
+     * The carry and window from `openingBase` on, for the canary hold. No
+     * opening of a leak starts before `openingFrom`: a point further back than
+     * `RELEASED_LOOKBACK` that does not open one by now never will. So each
+     * step reads from there, not the whole held text.
+     */
+    let opening = carry;
+    let openingBase = 0;
+    let openingFrom = 0;
+    /** Reads the carry, then the window as it grows. */
+    const scanner = token ? createCanaryScanner(token) : undefined;
+    scanner?.push(carry);
+    /**
+     * The leaks of what is ours (canary, prompt echo) in the carry and this
+     * window that stop the reply. One set to `flag` is noted for the next
+     * release instead, once. The canary scan reads each character once
+     * (`createCanaryScanner`) and the echo check rereads only its own short
+     * lookback (`promptEchoScanFrom`), so a long reply costs time in proportion
+     * to its length, not its square.
+     */
+    function leakStops(fresh) {
+        const found = [];
+        if (scanner?.push(fresh))
+            found.push([canaryAction, CANARY_HIT]);
+        if (privateSystem) {
+            const scanned = echoed.length;
+            echoed += fresh;
+            const from = promptEchoScanFrom(echoed, scanned);
+            echoed = echoed.slice(from);
+            echoedFrom += from;
+            const [hit] = promptEchoHits(echoed, privateSystem, context.canary);
+            if (hit)
+                found.push([promptAction, hit]);
+        }
+        for (const [action, hit] of found) {
+            if (action !== 'flag' || reported.has(hit.rule))
+                continue;
+            reported.add(hit.rule);
+            noted.push(hit);
+        }
+        return found.filter(([action]) => action !== 'flag').map(([, hit]) => hit);
+    }
+    /** What stops the reply at this step: a leak of ours, read at the gate's boundary. */
+    function scan(fragment) {
+        const leaks = guarded ? leakStops(fragment ?? '') : [];
+        if (fragment)
+            detecting?.push(fragment);
+        if (leaks.length === 0)
+            return null;
+        return { hits: leaks, ...(reads ? { boundary: reads.boundary } : {}) };
+    }
+    /**
+     * Where the leak checks hold from: a canary opening, or words a prompt echo
+     * could grow from. A leak set to `flag` holds nothing: it is shown.
+     */
+    function leakHoldFrom() {
+        const canary = token && canaryAction !== 'flag' ? canaryFrom(token) : held.length;
+        const echo = privateSystem && promptAction !== 'flag'
+            ? echoHoldFrom(privateSystem, context.canary)
+            : held.length;
+        return emitted + Math.min(canary, echo);
+    }
+    /** `result` with the leaks noted since the last release reported in it. */
+    function withNoted(result) {
+        if (noted.length === 0)
+            return result;
+        const hits = [...noted, ...(result.found?.hits ?? [])];
+        noted = [];
+        return { ...result, found: { action: result.found?.action ?? 'flag', hits } };
+    }
+    /** `canaryHoldFrom` on the held text, read from where an opening could start. */
+    function canaryFrom(canary) {
+        const shownTo = carry.length + emitted;
+        const from = Math.max(shownTo, openingFrom);
+        const lead = Math.max(openingBase, from - RELEASED_LOOKBACK);
+        let at = lead + canaryOpeningFrom(opening.slice(lead - openingBase), canary);
+        if (at < from && from > shownTo) {
+            // why: An opening the bound rules out: read the held text whole, and from there on.
+            opening = released + held;
+            openingBase = shownTo - released.length;
+            at = openingBase + canaryOpeningFrom(opening, canary);
+        }
+        openingFrom = Math.min(at, carry.length + accumulated.length - RELEASED_LOOKBACK);
+        const base = Math.max(openingBase, Math.max(shownTo, openingFrom) - RELEASED_LOOKBACK);
+        opening = opening.slice(base - openingBase);
+        openingBase = base;
+        return Math.max(0, at - shownTo);
+    }
+    /** `promptEchoHoldFrom` on the held text, read from its last few words. */
+    function echoHoldFrom(privateSystem, canary) {
+        // why: Until this window releases anything, its opening may continue the carry.
+        const lead = emitted === 0 ? carry : '';
+        const leadFrom = carry.length + emitted - lead.length;
+        const [text, from] = echoedFrom >= leadFrom ? [echoed, echoedFrom] : [lead + held, leadFrom];
+        return Math.max(0, from + promptEchoHoldFrom(text, privateSystem, canary) - carry.length - emitted);
+    }
+    function release(fragment) {
+        const stop = scan(fragment);
+        if (stop) {
+            return { blocked: true, ...stop };
+        }
+        const ended = fragment === undefined;
+        const end = ended
+            ? accumulated.length
+            : Math.min(leakHoldFrom(), detecting?.holdFrom() ?? accumulated.length);
+        const length = Math.max(0, end - emitted);
+        if (!(reads && detecting)) {
+            return withNoted({ blocked: false, emit: take(length) });
+        }
+        const read = detecting.take(emitted, emitted + length, ended);
+        if (read.action === 'block' || (read.action === 'redact' && !reads.rewrite)) {
+            return { blocked: true, hits: read.hits, boundary: reads.boundary };
+        }
+        take(read.taken);
+        return withNoted({
+            blocked: false,
+            emit: read.text ?? '',
+            ...(read.action === 'allow' ? {} : { found: { action: read.action, hits: read.hits } }),
+        });
+    }
+    /** Release the first `length` characters held, as written. */
+    function take(length) {
+        const emit = held.slice(0, length);
+        held = held.slice(length);
+        emitted += emit.length;
+        if (guarded)
+            released = (released + emit).slice(-RELEASED_LOOKBACK);
+        return emit;
+    }
+    return {
+        process(fragment) {
+            if (!fragment) {
+                return { blocked: false, emit: '' };
+            }
+            accumulated += fragment;
+            held += fragment;
+            if (guarded)
+                opening += fragment;
+            return release(fragment);
+        },
+        flush: () => release(),
+        accumulated: () => accumulated,
+        unreleased: () => held,
+        drainUnreleased: () => take(held.length),
+        carryOut: () => (guarded ? promptLeakCarry(carry + accumulated, token, privateSystem) : ''),
+    };
+}
+/**
+ * Whether a reply read at `boundaries` gets a verdict once it has ended: a
+ * detector reads one of them. A gate that stops such a reply withholds it for
+ * that verdict.
+ */
+function replyIsJudged(policy, boundaries, scope) {
+    return detectReads(boundaries, policy.detect, scope);
+}
+/**
+ * Shared constructor for runTurn + Live: a gate when a detector reads
+ * `boundary`. `context.canary` is set only while `canary_leak` is above
+ * `ignore` somewhere, and `context.privateSystem` while `prompt_leak` is.
+ */
+async function createOutboundProgressiveGate(policy, context, boundary, carry) {
+    if (!replyIsJudged(policy, [boundary], context))
+        return null;
+    await loadEgressAutomata();
+    return outboundProgressiveGate(policy, context, boundary, carry);
+}
+/** `createOutboundProgressiveGate`, once the automata are loaded. */
+function outboundProgressiveGate(policy, context, boundary, carry) {
+    if (!replyIsJudged(policy, [boundary], context)) {
+        return null;
+    }
+    return progressiveYieldGate({
+        context,
+        detect: {
+            matrix: policy.detect,
+            boundary,
+            rewrite: boundary === 'reply',
+            scope: scopeOf(policy, context),
+        },
+        ...(carry ? { carry } : {}),
+    });
+}
+/**
+ * A gate for a draft read at `boundary`, where the whole it previews is read before the host sees
+ * it: a tool call the model is still writing, a tool's output as the tool writes it, or a
+ * structured reply's JSON as the model writes it. It never
+ * rewrites: a match the whole's check would replace or stop stops the draft instead, because the
+ * host gets the whole only as that check leaves it. `scope` is what that check reads against;
+ * left out, the turn's (`scopeOf`).
+ */
+async function createDraftGate(policy, context, boundary, scope) {
+    if (!replyIsJudged(policy, [boundary], scope ?? context))
+        return null;
+    await loadEgressAutomata();
+    return progressiveYieldGate({
+        context,
+        detect: {
+            matrix: policy.detect,
+            boundary,
+            rewrite: false,
+            scope: scope ?? scopeOf(policy, context),
+        },
+    });
+}
+/**
+ * One stream of drafts read through one draft gate, opened on the first draft. A match stops
+ * the rest of the stream; with no gate (nothing is judged there), every draft passes as is.
+ */
+class DraftReader {
+    open;
+    gate;
+    constructor(open) {
+        this.open = open;
+    }
+    /** What of `text` may be shown now: empty while the gate holds it, or once a match stopped the stream. */
+    async read(text) {
+        if (this.gate === undefined)
+            this.gate = await this.open();
+        if (this.gate === 'stopped')
+            return '';
+        if (!this.gate)
+            return text;
+        const result = this.gate.process(text);
+        if (result.blocked) {
+            this.gate = 'stopped';
+            return '';
+        }
+        return result.emit;
+    }
+    /** The tail the gate still holds, once the stream has ended. */
+    end() {
+        if (!this.gate || this.gate === 'stopped')
+            return '';
+        const result = this.gate.flush();
+        return result.blocked ? '' : result.emit;
+    }
+}
+export { createDraftGate, createOutboundProgressiveGate, createProgressiveYieldGate, DraftReader, outboundProgressiveGate, replyIsJudged, };

package/esm/src/guardrails/prompt-echo.d.ts

@@ -0,0 +1,40 @@
+/**
+ * System-prompt echo — the leak the canary cannot see.
+ *
+ * The canary proves the token leaked; a reply that restates the system prompt
+ * while leaving the token out trips nothing. This check reads the reply for a
+ * run of `PROMPT_ECHO_WORDS` consecutive words of one private stretch of the
+ * system prompt (`BoundSystem.private`); text the host marked shareable is
+ * not read, and no run reaches across it. Words are
+ * compared case-folded after Unicode compatibility folding, punctuation and
+ * markup between them ignored, and bare numbers skipped, so reformatting a
+ * dump as a numbered or bulleted list does not hide it. Nor does encoding it:
+ * the prompt is also read backwards and in rot13, and both it and the reply
+ * with leetspeak decoded. Where the prompt has
+ * the canary, any one word, or none continues a run: a model told to hide the
+ * canary echoes the prompt around a stand-in for it. A streamed reply holds
+ * the words an echo could still grow from (`promptEchoHoldFrom`), so none of
+ * an echo reaches the host.
+ *
+ * @module
+ */
+/** Consecutive system-prompt words that make a reply an echo of it. */
+declare const PROMPT_ECHO_WORDS = 12;
+/**
+ * Where an echo still being written could start: the first word of the
+ * longest run of words ending `text` that the system prompt also has, or the
+ * word still being written when that is earlier and could become a prompt
+ * word. Any echo that completes later starts there or after.
+ */
+declare function promptEchoHoldFrom(text: string, stretches: readonly string[], canary?: string): number;
+/** Offsets `[start, end)` of `text` that repeat a private stretch, ordered by start. */
+declare function promptEchoRanges(text: string, stretches: readonly string[], canary?: string): Array<[number, number]>;
+/** Whether `text` repeats `PROMPT_ECHO_WORDS` consecutive words of a private stretch. */
+declare function scanTextForPromptEcho(text: string, stretches: readonly string[], canary?: string): boolean;
+/**
+ * Where a scan of `text` must start when everything before `from` was
+ * already scanned clean: at the word an echo run ending past `from` could
+ * start in.
+ */
+declare function promptEchoScanFrom(text: string, from: number): number;
+export { PROMPT_ECHO_WORDS, promptEchoHoldFrom, promptEchoRanges, promptEchoScanFrom, scanTextForPromptEcho, };

package/esm/src/guardrails/prompt-echo.js

@@ -0,0 +1,306 @@
+/**
+ * System-prompt echo — the leak the canary cannot see.
+ *
+ * The canary proves the token leaked; a reply that restates the system prompt
+ * while leaving the token out trips nothing. This check reads the reply for a
+ * run of `PROMPT_ECHO_WORDS` consecutive words of one private stretch of the
+ * system prompt (`BoundSystem.private`); text the host marked shareable is
+ * not read, and no run reaches across it. Words are
+ * compared case-folded after Unicode compatibility folding, punctuation and
+ * markup between them ignored, and bare numbers skipped, so reformatting a
+ * dump as a numbered or bulleted list does not hide it. Nor does encoding it:
+ * the prompt is also read backwards and in rot13, and both it and the reply
+ * with leetspeak decoded. Where the prompt has
+ * the canary, any one word, or none continues a run: a model told to hide the
+ * canary echoes the prompt around a stand-in for it. A streamed reply holds
+ * the words an echo could still grow from (`promptEchoHoldFrom`), so none of
+ * an echo reaches the host.
+ *
+ * @module
+ */
+import { LEET_MAP, tryRot13 } from './injection.js';
+/** Consecutive system-prompt words that make a reply an echo of it. */
+const PROMPT_ECHO_WORDS = 12;
+/** Words a scan rereads before new text: an echo run ending in it starts no earlier. */
+const ECHO_LOOKBACK_WORDS = PROMPT_ECHO_WORDS;
+const WORD = /[\p{L}\p{N}]+/gu;
+const WORD_CHAR = /[\p{L}\p{N}]/u;
+const NUMBER = /^\p{N}+$/u;
+const ASCII = /^\p{ASCII}*$/u;
+/** Most letters compatibility folding joins into one (a Hangul syllable from its jamo). */
+const MAX_FOLD = 3;
+/** The words a text is compared by, with the offsets each came from. */
+function echoWords(text) {
+    const words = [];
+    for (const match of text.matchAll(WORD)) {
+        const word = match[0].normalize('NFKC').toLowerCase();
+        if (!NUMBER.test(word)) {
+            words.push({ word, at: match.index, to: match.index + match[0].length });
+        }
+    }
+    return words;
+}
+/** Where the canary stood in the prompt's words: any one word or none matches it. */
+const SLOT = '\u0000';
+/**
+ * The prompt as a reply can encode it: written backwards, by code point, in
+ * rot13, or as the decoded leetspeak reply reads it.
+ */
+const PROMPT_VIEWS = [
+    (text) => text,
+    (text) => [...text].reverse().join(''),
+    tryRot13,
+    decodeLeet,
+];
+/**
+ * The private stretches' words as a run can repeat them, in each of
+ * `PROMPT_VIEWS`: as written, with the canary left out, and with the canary
+ * as `SLOT`.
+ */
+function promptReadings(stretches, canary) {
+    const readings = { plain: [], slotted: [] };
+    for (const view of PROMPT_VIEWS) {
+        const read = viewReadings(stretches.map(view), canary === undefined ? undefined : view(canary));
+        readings.plain.push(...read.plain);
+        readings.slotted.push(...read.slotted);
+    }
+    return readings;
+}
+function viewReadings(stretches, canary) {
+    const token = canary ? echoWords(canary).map((entry) => entry.word) : [];
+    const readings = { plain: [], slotted: [] };
+    for (const stretch of stretches) {
+        const words = echoWords(stretch).map((entry) => entry.word);
+        readings.plain.push(words);
+        if (token.length === 0)
+            continue;
+        const slotted = [];
+        for (let at = 0; at < words.length;) {
+            if (token.every((word, k) => words[at + k] === word)) {
+                slotted.push(SLOT);
+                at += token.length;
+            }
+            else {
+                slotted.push(words[at]);
+                at++;
+            }
+        }
+        if (!slotted.includes(SLOT))
+            continue;
+        readings.plain.push(slotted.filter((word) => word !== SLOT));
+        readings.slotted.push(slotted);
+    }
+    return readings;
+}
+/** A run with a slot, keyed by where the slot is and the words around it. */
+function slotKey(run, slot) {
+    // why: Bare numbers are never words here, so the slot's index leads unambiguously.
+    return [slot, ...run.filter((_, k) => k !== slot)].join(' ');
+}
+/** A run may not start on the canary's place unless `leading`: a stand-in for it is not prompt text. */
+function addRuns(set, readings, lengths, leading) {
+    for (const words of readings.plain) {
+        for (const length of lengths) {
+            for (let from = 0; from + length <= words.length; from++) {
+                set.plain.add(words.slice(from, from + length).join(' '));
+            }
+        }
+    }
+    for (const slotted of readings.slotted) {
+        for (const length of lengths) {
+            for (let from = 0; from + length <= slotted.length; from++) {
+                const run = slotted.slice(from, from + length);
+                const slot = run.indexOf(SLOT);
+                if (slot === -1 || (slot === 0 && !leading))
+                    continue;
+                set.slotted.add(slotKey(run, slot));
+                set.slots.add(slot);
+            }
+        }
+    }
+}
+/** Where in `run` the canary's place fell when `set` has it: -1 for nowhere, undefined when not a run. */
+function matchRun(set, run) {
+    if (set.plain.has(run.join(' ')))
+        return -1;
+    for (const slot of set.slots) {
+        if (slot < run.length && set.slotted.has(slotKey(run, slot)))
+            return slot;
+    }
+    return undefined;
+}
+function sameStretches(a, b) {
+    return a === b || (a.length === b.length && a.every((stretch, k) => stretch === b[k]));
+}
+let gramsCache;
+/** Every run of `PROMPT_ECHO_WORDS` words in a private stretch. */
+function promptGrams(stretches, canary) {
+    if (gramsCache &&
+        gramsCache.canary === canary &&
+        sameStretches(gramsCache.stretches, stretches)) {
+        return gramsCache.grams;
+    }
+    const grams = { plain: new Set(), slotted: new Set(), slots: new Set() };
+    addRuns(grams, promptReadings(stretches, canary), [PROMPT_ECHO_WORDS], true);
+    gramsCache = { stretches, canary, grams };
+    return grams;
+}
+let shapeCache;
+function promptShape(stretches, canary) {
+    if (shapeCache &&
+        shapeCache.canary === canary &&
+        sameStretches(shapeCache.stretches, stretches)) {
+        return shapeCache.shape;
+    }
+    const readings = promptReadings(stretches, canary);
+    const shape = {
+        runs: { plain: new Set(), slotted: new Set(), slots: new Set() },
+        prefixes: new Set(),
+        longest: 0,
+    };
+    for (const word of readings.plain.flat()) {
+        shape.longest = Math.max(shape.longest, word.length);
+        for (let end = 1; end <= word.length && ASCII.test(word.charAt(end - 1)); end++) {
+            shape.prefixes.add(word.slice(0, end));
+        }
+    }
+    addRuns(shape.runs, readings, Array.from({ length: PROMPT_ECHO_WORDS - 1 }, (_, k) => k + 1), false);
+    shapeCache = { stretches, canary, shape };
+    return shape;
+}
+/**
+ * Whether a word still being written could end as a word of the system
+ * prompt. ASCII folds letter by letter, so it must start one; other
+ * scripts can fold several letters into one (Hangul jamo, up to three), so
+ * only a word too long to fold down to any of them is ruled out.
+ */
+function mayBecomePromptWord(partial, shape) {
+    if (ASCII.test(partial)) {
+        return shape.prefixes.has(partial.toLowerCase());
+    }
+    return partial.length <= MAX_FOLD * shape.longest;
+}
+/**
+ * Where an echo still being written could start: the first word of the
+ * longest run of words ending `text` that the system prompt also has, or the
+ * word still being written when that is earlier and could become a prompt
+ * word. Any echo that completes later starts there or after.
+ */
+function promptEchoHoldFrom(text, stretches, canary) {
+    for (let reach = TAIL_REACH;; reach *= 2) {
+        const start = decodableFrom(text, text.length - reach);
+        const holds = replyViews(text.slice(start)).map((view) => holdFrom(view, stretches, canary));
+        if (start === 0 || holds.every(({ tail }) => tail > 0)) {
+            return start + Math.min(...holds.map(({ hold }) => hold));
+        }
+    }
+}
+/** The hold in `text`, and where the words it was read from start: at 0, `text` may be too short a tail. */
+function holdFrom(text, stretches, canary) {
+    const tail = promptEchoScanFrom(text, text.length);
+    return { hold: holdIn(text, tail, stretches, canary), tail };
+}
+function holdIn(text, tail, stretches, canary) {
+    const words = echoWords(text.slice(tail));
+    let writing = text.length;
+    while (writing > 0 && WORD_CHAR.test(text.charAt(writing - 1)))
+        writing--;
+    const complete = words.filter((entry) => tail + entry.to < text.length || writing === text.length);
+    const shape = promptShape(stretches, canary);
+    const hold = mayBecomePromptWord(text.slice(writing), shape) ? writing : text.length;
+    for (let from = Math.max(0, complete.length - (PROMPT_ECHO_WORDS - 1)); from < complete.length; from++) {
+        const run = complete.slice(from).map((entry) => entry.word);
+        if (matchRun(shape.runs, run) !== undefined) {
+            return Math.min(hold, tail + complete[from].at);
+        }
+    }
+    return hold;
+}
+/** A leetspeak letter, or a list number that stays one; `!` only before a word goes on. */
+const LEET = /(?<=^|\n)[ \t]*\p{N}+[.)]|[0-9@]|!(?=[\p{L}\p{N}@])/gu;
+/** How far back a tail is first read from; a tail with too few words in it is doubled. */
+const TAIL_REACH = 512;
+const LIST_NUMBER_CHAR = /[ \t\p{N}]/u;
+const NUMBER_CHAR = /\p{N}/u;
+/**
+ * A start at or before `at` from which `text` decodes as it does whole: a
+ * list number is one from its line's start, so the start is no later than the
+ * character before the blanks and digits leading up to `at`.
+ */
+function decodableFrom(text, at) {
+    let start = Math.max(0, at);
+    while (start > 0 && LIST_NUMBER_CHAR.test(text.charAt(start - 1)))
+        start--;
+    return Math.max(0, start - 1);
+}
+/** `text` with its leetspeak decoded, letter for letter, so offsets keep. */
+function decodeLeet(text) {
+    return text.replace(LEET, (match) => (match.length === 1 ? (LEET_MAP[match] ?? match) : match));
+}
+/** The reply as written and with its leetspeak decoded. */
+function replyViews(text) {
+    const decoded = decodeLeet(text);
+    return decoded === text ? [text] : [text, decoded];
+}
+/** Offsets `[start, end)` of `text` that repeat a private stretch, ordered by start. */
+function promptEchoRanges(text, stretches, canary) {
+    return replyViews(text)
+        .flatMap((view) => echoRanges(view, stretches, canary))
+        .sort((a, b) => a[0] - b[0]);
+}
+function echoRanges(text, stretches, canary) {
+    const grams = promptGrams(stretches, canary);
+    if (!text || grams.plain.size === 0) {
+        return [];
+    }
+    const words = echoWords(text);
+    const ranges = [];
+    for (let from = 0; from + PROMPT_ECHO_WORDS <= words.length; from++) {
+        const run = words.slice(from, from + PROMPT_ECHO_WORDS).map((entry) => entry.word);
+        const slot = matchRun(grams, run);
+        if (slot === undefined)
+            continue;
+        // why: A stand-in for the canary at either end is the model's, not the prompt's.
+        const first = slot === 0 ? from + 1 : from;
+        const last = slot === PROMPT_ECHO_WORDS - 1 ? from + slot - 1 : from + PROMPT_ECHO_WORDS - 1;
+        ranges.push([words[first]?.at ?? 0, words[last]?.to ?? 0]);
+    }
+    return ranges;
+}
+/** Whether `text` repeats `PROMPT_ECHO_WORDS` consecutive words of a private stretch. */
+function scanTextForPromptEcho(text, stretches, canary) {
+    return promptEchoRanges(text, stretches, canary).length > 0;
+}
+/**
+ * Where a scan of `text` must start when everything before `from` was
+ * already scanned clean: at the word an echo run ending past `from` could
+ * start in.
+ */
+function promptEchoScanFrom(text, from) {
+    const end = Math.min(from, text.length);
+    for (let reach = TAIL_REACH;; reach *= 2) {
+        const start = decodableFrom(text, end - reach);
+        // why: What follows `end` decides how the tail's last characters read: a `!` by the next one, digits by the list number they may be.
+        let stop = end;
+        while (stop < text.length && NUMBER_CHAR.test(text.charAt(stop)))
+            stop++;
+        const tail = text.slice(start, stop + 1);
+        const at = Math.min(...replyViews(tail).map((view) => scanFrom(view, end - start)));
+        if (start === 0 || at > 0)
+            return start + at;
+    }
+}
+function scanFrom(text, from) {
+    let at = Math.min(from, text.length);
+    for (let counted = 0; counted < ECHO_LOOKBACK_WORDS && at > 0;) {
+        while (at > 0 && !WORD_CHAR.test(text.charAt(at - 1)))
+            at--;
+        const end = at;
+        while (at > 0 && WORD_CHAR.test(text.charAt(at - 1)))
+            at--;
+        if (end > at && !NUMBER.test(text.slice(at, end)))
+            counted++;
+    }
+    return at;
+}
+export { PROMPT_ECHO_WORDS, promptEchoHoldFrom, promptEchoRanges, promptEchoScanFrom, scanTextForPromptEcho, };

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

@@ -0,0 +1,21 @@
+import type { Profile } from '../kernel/types.js';
+import { TheoremError } from './theorem-error.js';
+/** What taking a quota slot returned: `ok` (reserved), `busy` (a turn already holds the slot), `quota` (the day's limit is used) or `not_configured` (the profile sets no quota). */
+type QuotaSlotStatus = 'ok' | 'busy' | 'quota' | 'not_configured';
+/** Returns whether a local request lacks the proxy header needed for quota identity. */
+declare function skipQuota(peer: string, req: Request): boolean;
+/** Resolves the client identity, preferring Cloudflare's header for local peers. */
+declare function clientIp(peer: string, req: Request): string;
+/**
+ * Reserves one profile-and-client daily quota slot. The reservation stays busy
+ * until `releaseSlot` is called, preventing concurrent turns from overspending.
+ */
+declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus;
+/** Releases an active quota reservation without decrementing its daily count. */
+declare function releaseSlot(profile: Profile, ip: string): void;
+/** `undefined` when the profile has no quota configured. */
+declare function quotaExhausted(profile: Profile): TheoremError | undefined;
+/** Clears all process-local quota counters; intended for tests or host resets. */
+declare function resetSlots(): void;
+export type { QuotaSlotStatus };
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot };