@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/egress-compiler.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Build-time compiler for a host's patterns, behind `@theoremjs/agents/guardrails/compile`.
+ *
+ * The streaming hold reads each pattern as an automaton that accepts
+ * every match of it and more, so it can hold exactly the text a match could
+ * still be under way in. Building those automata takes a regex engine (refa)
+ * and time a Worker cold start cannot spare, so it runs here, at build time:
+ * `agents detect-compile` writes the tables, and `guardrails.detect` loads them.
+ *
+ * An automaton drops its pattern's assertions: a lookbehind, `\b`, `^`, and `$`
+ * match nothing, and a lookahead is skipped, with its text read after what
+ * precedes it wherever the match may end before that text does. A bounded
+ * repeat over `COUNT_LIMIT` is unbounded. An optional repeat of one character
+ * class that opens the pattern is left out and its class named in `leads`:
+ * the stream reads a match as starting where the run of that class it is in
+ * started. An inline modifier's flags are set on the whole pattern. Each
+ * change only widens what it accepts, so the hold can only hold more than it
+ * must. A backreference to text that varies has no automaton;
+ * compiling it fails.
+ *
+ * @module
+ */
+import type { DetectSpec } from './detectors.js';
+import { type AutomatonData, type CompiledPatterns, type HostPattern } from './host-patterns.js';
+/**
+ * What makes `source` slow on hostile text, or `undefined`. A source that does not parse is
+ * not this check's to report: whatever reads it says so.
+ */
+declare function slowPatternProblem(source: string, flags?: string): string | undefined;
+/**
+ * The table a detector needs for the host's `patterns`: each checked, and their automaton. A
+ * pattern is refused when it does not compile, matches the empty text, is sticky, could hang
+ * or get slow on long text (`slowProblem`), or has no automaton the stream can hold by (a
+ * backreference to text that varies).
+ */
+declare function compilePatterns(patterns: readonly HostPattern[]): CompiledPatterns;
+/**
+ * `detect` with the table compiled for every detector's `patterns`, for a host that compiles as
+ * it starts in place of `agents detect-compile` at build time. A table already set is replaced.
+ */
+declare function compileDetect<Spec extends DetectSpec>(detect: Spec): Spec;
+/** The table for each detector `detect` gives patterns, by detector. */
+declare function compileDetectTables(detect: DetectSpec): Record<string, CompiledPatterns>;
+/** `tables` as a module exporting them as `compiledDetect`, each to set as its detector's `compiled`. */
+declare function compiledDetectModule(tables: Record<string, CompiledPatterns>): string;
+/**
+ * Everything `egress-automata.ts` holds, from the bundled patterns as they are
+ * now: the injection patterns reversed, and the forward and reversed automata.
+ */
+declare function bundledEgressAutomata(): {
+    reversedPatterns: RegExp[];
+    forward: AutomatonData;
+    reversed: AutomatonData;
+};
+export { bundledEgressAutomata, compileDetect, compileDetectTables, compiledDetectModule, compilePatterns, slowPatternProblem, };

package/esm/src/guardrails/egress-compiler.js

@@ -0,0 +1,431 @@
+/**
+ * Build-time compiler for a host's patterns, behind `@theoremjs/agents/guardrails/compile`.
+ *
+ * The streaming hold reads each pattern as an automaton that accepts
+ * every match of it and more, so it can hold exactly the text a match could
+ * still be under way in. Building those automata takes a regex engine (refa)
+ * and time a Worker cold start cannot spare, so it runs here, at build time:
+ * `agents detect-compile` writes the tables, and `guardrails.detect` loads them.
+ *
+ * An automaton drops its pattern's assertions: a lookbehind, `\b`, `^`, and `$`
+ * match nothing, and a lookahead is skipped, with its text read after what
+ * precedes it wherever the match may end before that text does. A bounded
+ * repeat over `COUNT_LIMIT` is unbounded. An optional repeat of one character
+ * class that opens the pattern is left out and its class named in `leads`:
+ * the stream reads a match as starting where the run of that class it is in
+ * started. An inline modifier's flags are set on the whole pattern. Each
+ * change only widens what it accepts, so the hold can only hold more than it
+ * must. A backreference to text that varies has no automaton;
+ * compiling it fails.
+ *
+ * @module
+ */
+import { RegExpParser, visitRegExpAST } from '@eslint-community/regexpp';
+import { JS, NFA } from 'refa';
+import { analyse } from 'scslre';
+import { EGRESS_PATTERNS } from './egress-patterns.js';
+import { TheoremError } from './error.js';
+import { MAX_PATTERNS, PATTERN_COMPILER_VERSION, patternProblem, patternSources, } from './host-patterns.js';
+const MAX_CHAR = 0xffff;
+/**
+ * A bounded repeat longer than this is read as unbounded: the hold cannot
+ * tell the bound is reached without counting, and holding on is the safe side.
+ */
+const COUNT_LIMIT = 256;
+/** The pattern read right to left: `P` on reversed text matches where this matches on the text. */
+function reversed(alternatives) {
+    return alternatives.map((concat) => ({
+        type: 'Concatenation',
+        elements: concat.elements.map(reversedElement).reverse(),
+    }));
+}
+function reversedElement(element) {
+    switch (element.type) {
+        case 'Alternation':
+        case 'Quantifier':
+            return { ...element, alternatives: reversed(element.alternatives) };
+        case 'Assertion':
+            return {
+                ...element,
+                kind: element.kind === 'ahead' ? 'behind' : 'ahead',
+                alternatives: reversed(element.alternatives),
+            };
+        case 'CharacterClass':
+            return element;
+        default:
+            // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            throw new Error(`cannot reverse a ${element.type} element`);
+    }
+}
+/**
+ * The pattern with its assertions loosened and a long bounded repeat
+ * unbounded. A lookbehind (and `\b`, `^`, `$`, which parse to lookarounds)
+ * matches the empty string. A lookahead:
+ *
+ * - no longer than what must follow it is skipped: the match has read its text;
+ * - with nothing after it is read or skipped;
+ * - otherwise is skipped, and what precedes it followed by its text is an
+ *   alternative of the pattern (in `ends`), so the automaton is still under
+ *   way, and then at a match, while the text that settles it arrives.
+ */
+function loosened(alternatives, after, ends) {
+    return alternatives.map((concat) => {
+        const elements = [];
+        concat.elements.forEach((element, i) => {
+            const rest = lengthOf(concat.elements.slice(i + 1));
+            elements.push(...loosenedElement(element, { min: after.min + rest.min, max: after.max + rest.max }, ends && { before: [...ends.before, ...elements], out: ends.out }));
+        });
+        return { type: 'Concatenation', elements };
+    });
+}
+/** The fewest and the most characters a match of the elements, one after another, reads. */
+function lengthOf(elements) {
+    let min = 0;
+    let max = 0;
+    for (const element of elements) {
+        if (element.type === 'Assertion')
+            continue;
+        if (element.type === 'CharacterClass') {
+            min++;
+            max++;
+            continue;
+        }
+        if (element.type === 'Unknown') {
+            max = Number.POSITIVE_INFINITY;
+            continue;
+        }
+        const each = element.alternatives.map((concat) => lengthOf(concat.elements));
+        const times = element.type === 'Quantifier' ? element : { min: 1, max: 1 };
+        const most = Math.max(...each.map((length) => length.max));
+        min += times.min * Math.min(...each.map((length) => length.min));
+        max += most === 0 ? 0 : times.max * most;
+    }
+    return { min, max };
+}
+/** `element` loosened, where `after` characters follow it in a match. */
+function loosenedElement(element, after, ends) {
+    switch (element.type) {
+        case 'Alternation':
+            return [{ ...element, alternatives: loosened(element.alternatives, after, ends) }];
+        case 'Quantifier': {
+            const max = element.max > COUNT_LIMIT ? Number.POSITIVE_INFINITY : element.max;
+            const inside = max > 1 ? { min: after.min, max: Number.POSITIVE_INFINITY } : after;
+            const repeat = { ...element, max, alternatives: loosened(element.alternatives, inside) };
+            if (ends) {
+                const earlier = { ...repeat, min: 0, max: Number.POSITIVE_INFINITY };
+                loosened(element.alternatives, inside, {
+                    before: max > 1 ? [...ends.before, earlier] : ends.before,
+                    out: ends.out,
+                });
+            }
+            return [repeat];
+        }
+        case 'Assertion': {
+            if (element.kind === 'behind')
+                return [];
+            const text = loosened(element.alternatives, { min: 0, max: 0 }, ends);
+            const { max } = lengthOf([{ type: 'Alternation', alternatives: text }]);
+            if (max <= after.min)
+                return [];
+            const read = { type: 'Alternation', alternatives: text };
+            if (after.max > 0) {
+                ends?.out.push({ type: 'Concatenation', elements: [...ends.before, read] });
+                return [];
+            }
+            return [
+                {
+                    type: 'Alternation',
+                    alternatives: [{ type: 'Concatenation', elements: [] }, ...text],
+                },
+            ];
+        }
+        case 'CharacterClass':
+            return [element];
+        default:
+            // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            throw new Error(`cannot loosen a ${element.type} element`);
+    }
+}
+/**
+ * `literal` as current JavaScript reads it: refa's own parser stops at ES2024,
+ * and refa ignores an inline modifier group, so its flags go on the pattern.
+ */
+function literalAst(literal) {
+    const ast = new RegExpParser().parseLiteral(literal);
+    visitRegExpAST(ast, {
+        onModifiersEnter({ add }) {
+            ast.flags.ignoreCase ||= add.ignoreCase;
+            ast.flags.dotAll ||= add.dotAll;
+            ast.flags.multiline ||= add.multiline;
+        },
+    });
+    return ast;
+}
+/**
+ * The pattern over UTF-16 code units. A `u` or `v` pattern reads code points;
+ * it is rewritten to the equivalent pattern on the units that spell them.
+ */
+function parsed(pattern) {
+    const ast = literalAst(String(pattern));
+    const { expression } = JS.Parser.fromAst(ast).parse({ assertions: 'parse' });
+    if (!ast.flags.unicode && !ast.flags.unicodeSets) {
+        return expression.alternatives;
+    }
+    const units = JS.toLiteral(expression, { flags: { unicode: false, unicodeSets: false } });
+    return JS.Parser.fromLiteral(units).parse({ assertions: 'parse' }).expression.alternatives;
+}
+/**
+ * The pattern's source spelled so no lint rule has anything to say about it: `[\s\S]` for any
+ * character (not `[^]`) and `\v` for the vertical tab (not `\x0b`). Each pair matches the same text.
+ */
+function plainSource(source) {
+    let out = '';
+    let inClass = false;
+    for (let i = 0; i < source.length; i++) {
+        const char = source[i];
+        if (char === '\\') {
+            const next = source.slice(i, i + 4);
+            if (next === '\\x0b') {
+                out += '\\v';
+                i += 3;
+            }
+            else {
+                out += source.slice(i, i + 2);
+                i++;
+            }
+        }
+        else if (!inClass && source.startsWith('[^]', i)) {
+            out += '[\\s\\S]';
+            i += 2;
+        }
+        else {
+            if (char === '[')
+                inClass = true;
+            else if (char === ']')
+                inClass = false;
+            out += char;
+        }
+    }
+    return out;
+}
+/** A regex literal for the reversed pattern, with the original's flags. */
+function reversedLiteral(pattern) {
+    const literal = JS.toLiteral(reversed(parsed(pattern)), {
+        flags: { global: true, unicode: false, sticky: false },
+    });
+    return new RegExp(plainSource(literal.source), literal.flags);
+}
+/**
+ * The pattern split at an optional repeat of one character class that opens
+ * it: the class, and the rest. Counted in the automaton, the repeat would keep
+ * a state per repeat alive at every character of a run of the class.
+ */
+function led(alternatives) {
+    const [concat] = alternatives;
+    if (alternatives.length !== 1 || !concat)
+        return { rest: alternatives };
+    const [first, ...after] = concat.elements;
+    if (first?.type === 'Alternation' && first.alternatives.length === 1) {
+        const [inner] = first.alternatives;
+        return led([{ type: 'Concatenation', elements: [...(inner?.elements ?? []), ...after] }]);
+    }
+    if (first?.type !== 'Quantifier' || first.min !== 0 || first.max < 2) {
+        return { rest: alternatives };
+    }
+    const [repeated] = first.alternatives;
+    const [only] = repeated?.elements ?? [];
+    if (first.alternatives.length !== 1 || repeated?.elements.length !== 1) {
+        return { rest: alternatives };
+    }
+    return only?.type === 'CharacterClass'
+        ? { lead: only.characters, rest: [{ type: 'Concatenation', elements: after }] }
+        : { rest: alternatives };
+}
+function nfaOf(alternatives) {
+    const ends = [];
+    const whole = [...loosened(alternatives, { min: 0, max: 0 }, { before: [], out: ends }), ...ends];
+    const { lead, rest } = led(whole);
+    const build = (from) => {
+        const nfa = NFA.fromRegex(from, { maxCharacter: MAX_CHAR });
+        nfa.removeUnreachable();
+        return { initial: nfa.initial, nodes: [...nfa.nodes()], finals: nfa.finals };
+    };
+    const nfa = build(rest);
+    if (!lead)
+        return nfa;
+    return nfa.finals.has(nfa.initial) ? build(whole) : { ...nfa, lead };
+}
+/** The union of the patterns' automata as tables, nodes tagged with their pattern. */
+function automatonData(patterns) {
+    const nfas = patterns.map(nfaOf);
+    const bounds = new Set([0]);
+    for (const nfa of nfas) {
+        const sets = nfa.nodes.flatMap((node) => [...node.out.values()]);
+        for (const set of nfa.lead ? [...sets, nfa.lead] : sets) {
+            for (const range of set.ranges) {
+                bounds.add(range.min);
+                if (range.max < MAX_CHAR)
+                    bounds.add(range.max + 1);
+            }
+        }
+    }
+    const classStarts = [...bounds].sort((a, b) => a - b);
+    const classOf = (code) => {
+        let lo = 0;
+        let hi = classStarts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (classStarts[mid] <= code)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo;
+    };
+    const charsets = [];
+    const charsetIds = new Map();
+    const charsetId = (ranges) => {
+        const classes = [];
+        for (const { min, max } of ranges) {
+            for (let k = classOf(min); k < classStarts.length && classStarts[k] <= max; k++) {
+                classes.push(k);
+            }
+        }
+        const key = classes.join(',');
+        let id = charsetIds.get(key);
+        if (id === undefined) {
+            id = charsets.length;
+            charsets.push(classes);
+            charsetIds.set(key, id);
+        }
+        return id;
+    };
+    const nodes = [];
+    const initials = [];
+    nfas.forEach((nfa, pattern) => {
+        const ids = new Map();
+        for (const node of nfa.nodes)
+            ids.set(node, nodes.length + ids.size);
+        initials.push(ids.get(nfa.initial));
+        for (const node of nfa.nodes) {
+            const row = [pattern, nfa.finals.has(node) ? 1 : 0];
+            for (const [to, set] of node.out)
+                row.push(ids.get(to), charsetId(set.ranges));
+            nodes.push(row);
+        }
+    });
+    const leads = nfas.map(({ lead }) => (lead ? charsetId(lead.ranges) : -1));
+    return { classStarts, charsets, initials, leads, nodes };
+}
+function patternError(message) {
+    return new TheoremError('config', `compilePatterns: ${message}`);
+}
+/**
+ * Why `pattern` could take far longer than the text is long, or `undefined`: a repeat that
+ * matches the same text in more than one way, or one the engine reads again from every position.
+ */
+function slowProblem(pattern) {
+    const [report] = analyse(pattern, { maxReports: 1 }).reports;
+    if (!report)
+        return undefined;
+    const repeat = report.type === 'Trade' ? report.startQuant.raw : report.quant.raw;
+    // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    return report.type === 'Move'
+        ? `gets slow on long text: its time grows with the square of the text. Bound the repeat ${repeat} ({1,64} in place of + or *)`
+        : `can hang on text that nearly matches: the repeat ${repeat} matches the same text in more than one way. Bound it ({1,64} in place of + or *) or make its parts unable to overlap`;
+}
+/**
+ * What makes `source` slow on hostile text, or `undefined`. A source that does not parse is
+ * not this check's to report: whatever reads it says so.
+ */
+function slowPatternProblem(source, flags = '') {
+    let regex;
+    try {
+        regex = new RegExp(source, flags);
+    }
+    catch {
+        return undefined;
+    }
+    return slowProblem(regex);
+}
+/**
+ * The table a detector needs for the host's `patterns`: each checked, and their automaton. A
+ * pattern is refused when it does not compile, matches the empty text, is sticky, could hang
+ * or get slow on long text (`slowProblem`), or has no automaton the stream can hold by (a
+ * backreference to text that varies).
+ */
+function compilePatterns(patterns) {
+    if (patterns.length > MAX_PATTERNS) {
+        throw patternError(`${patterns.length} patterns; a detector takes at most ${MAX_PATTERNS}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    patterns.forEach((pattern, index) => {
+        const problem = patternProblem(`patterns[${index}]`, pattern);
+        if (problem !== undefined)
+            throw patternError(problem);
+    });
+    const sources = patternSources(patterns);
+    const alternatives = sources.map(({ name, source, flags }) => {
+        const slow = slowProblem(new RegExp(source, flags));
+        if (slow !== undefined)
+            throw patternError(`${name}: /${source}/${flags} ${slow}`);
+        try {
+            const units = parsed(new RegExp(source, flags));
+            nfaOf(units);
+            return units;
+        }
+        catch (err) {
+            throw patternError(`${name}: /${source}/${flags} has no automaton the stream can hold for (${err instanceof Error ? err.message : String(err)})`);
+        }
+    });
+    return {
+        compiler: PATTERN_COMPILER_VERSION,
+        patterns: sources,
+        automaton: automatonData(alternatives),
+    };
+}
+/**
+ * `detect` with the table compiled for every detector's `patterns`, for a host that compiles as
+ * it starts in place of `agents detect-compile` at build time. A table already set is replaced.
+ */
+function compileDetect(detect) {
+    if (typeof detect === 'string')
+        return detect;
+    const tables = compileDetectTables(detect);
+    const rules = Object.entries(detect).map(([detector, rule]) => {
+        const compiled = tables[detector];
+        return [detector, compiled && typeof rule !== 'string' ? { ...rule, compiled } : rule];
+    });
+    return Object.fromEntries(rules);
+}
+/** The table for each detector `detect` gives patterns, by detector. */
+function compileDetectTables(detect) {
+    if (typeof detect === 'string')
+        return {};
+    const tables = {};
+    for (const [detector, rule] of Object.entries(detect)) {
+        if (typeof rule === 'string' || !rule.patterns?.length)
+            continue;
+        tables[detector] = compilePatterns(rule.patterns);
+    }
+    return tables;
+}
+/** `tables` as a module exporting them as `compiledDetect`, each to set as its detector's `compiled`. */
+function compiledDetectModule(tables) {
+    // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    return `// Generated by \`agents detect-compile\`. Do not edit: change the patterns and compile again.
+export const compiledDetect = ${JSON.stringify(tables)};
+`;
+}
+/**
+ * Everything `egress-automata.ts` holds, from the bundled patterns as they are
+ * now: the injection patterns reversed, and the forward and reversed automata.
+ */
+function bundledEgressAutomata() {
+    const injection = EGRESS_PATTERNS.filter((entry) => entry.kind === 'injection');
+    return {
+        reversedPatterns: injection.map(({ pattern }) => reversedLiteral(pattern)),
+        forward: automatonData(EGRESS_PATTERNS.map(({ pattern }) => parsed(pattern))),
+        reversed: automatonData(injection.map(({ pattern }) => reversed(parsed(pattern)))),
+    };
+}
+export { bundledEgressAutomata, compileDetect, compileDetectTables, compiledDetectModule, compilePatterns, slowPatternProblem, };

package/esm/src/guardrails/egress-patterns.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Every pattern the bundled egress policy matches on the reply, in the order
+ * the streaming hold's automata number them (`egress-automata.ts`, generated
+ * from this list by `scripts/gen-egress-automata.ts`).
+ *
+ * @module
+ */
+import type { SensitiveGroup } from './sensitive-groups.js';
+declare const SYSTEM_BOUNDARY: RegExp;
+/** What a match of the pattern means: the rule it trips, or the blob its filter decodes. */
+type EgressPatternKind = 'injection' | 'sensitive' | 'card' | 'boundary' | 'base64' | 'hex' | 'spaced' | 'pipe' | 'image' | 'link';
+interface EgressPattern {
+    kind: EgressPatternKind;
+    pattern: RegExp;
+    /** The sensitive-data group a `sensitive` or `card` pattern belongs to. */
+    group?: SensitiveGroup;
+}
+/**
+ * Patterns matched on the reply as written. The injection patterns come first:
+ * the rewritten views (typo, Unicode, rot13, leet, URL) match those alone.
+ */
+declare const EGRESS_PATTERNS: readonly EgressPattern[];
+/** A reply repeating `note`, a canary note's own words (`canaryNoteMarker`), as written, case aside. */
+declare function notePattern(note: string): RegExp;
+export type { EgressPattern, EgressPatternKind };
+export { EGRESS_PATTERNS, notePattern, SYSTEM_BOUNDARY };

package/esm/src/guardrails/egress-patterns.js

@@ -0,0 +1,36 @@
+/**
+ * Every pattern the bundled egress policy matches on the reply, in the order
+ * the streaming hold's automata number them (`egress-automata.ts`, generated
+ * from this list by `scripts/gen-egress-automata.ts`).
+ *
+ * @module
+ */
+import { IMAGE_PATTERNS, LINK_PATTERNS } from './egress-urls.js';
+import { BASE64_BLOB, HEX_BLOB, INJECTION_PATTERNS, PIPE_SEPARATED, SPACED_LETTERS, } from './injection-patterns.js';
+import { CARD_CANDIDATE, SENSITIVE_PATTERNS } from './sensitive.js';
+const SYSTEM_BOUNDARY = /This turn\x27s canary is|Your canary token is|<\s*(?:\/\s*)?user_data(?:\s*(?:\/\s*)?>)?/i; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+/**
+ * Patterns matched on the reply as written. The injection patterns come first:
+ * the rewritten views (typo, Unicode, rot13, leet, URL) match those alone.
+ */
+const EGRESS_PATTERNS = [
+    ...INJECTION_PATTERNS.map((pattern) => ({ kind: 'injection', pattern })),
+    ...SENSITIVE_PATTERNS.map(({ group, pattern }) => ({
+        kind: 'sensitive',
+        pattern,
+        group,
+    })),
+    { kind: 'card', pattern: CARD_CANDIDATE, group: 'financial' },
+    { kind: 'boundary', pattern: new RegExp(SYSTEM_BOUNDARY.source, 'gi') },
+    { kind: 'base64', pattern: BASE64_BLOB },
+    { kind: 'hex', pattern: HEX_BLOB },
+    { kind: 'spaced', pattern: SPACED_LETTERS },
+    { kind: 'pipe', pattern: PIPE_SEPARATED },
+    ...IMAGE_PATTERNS.map((pattern) => ({ kind: 'image', pattern })),
+    ...LINK_PATTERNS.map((pattern) => ({ kind: 'link', pattern })),
+];
+/** A reply repeating `note`, a canary note's own words (`canaryNoteMarker`), as written, case aside. */
+function notePattern(note) {
+    return new RegExp(note.replace(/[\\^$.*+?()[\]{}|/-]/g, '\\$&'), 'gi');
+}
+export { EGRESS_PATTERNS, notePattern, SYSTEM_BOUNDARY };

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

@@ -0,0 +1,123 @@
+/**
+ * The detectors, Theorem's and the host's own, run on a reply as it streams.
+ *
+ * Each matches its patterns on the reply as written and, for
+ * injection phrasing, on
+ * rewrites of it (typo-folded, Unicode-folded, rot13, leet, URL-decoded, read
+ * backwards). The stream keeps each rewrite growing with the reply and, for
+ * every pattern, an automaton accepting every match of it and more
+ * (`egress-automata.ts`). Text is held from the earliest place any match could
+ * still be under way in any rewrite, and nowhere else: a match that completes
+ * later starts at or after that place, so none of it has been released.
+ *
+ * A match whose outcome no later text can change is settled; a settled match
+ * of the pattern itself (not the automaton) is a hit, and does what
+ * `guardrails.detect` sets (`detect-stream.ts`). Each character is read a bounded number of times, so a
+ * long reply costs time in proportion to its length.
+ *
+ * @module
+ */
+import type { Detector, ResolvedAllow } from './detectors.js';
+import { type GivenUrls } from './egress-urls.js';
+import type { CompiledPatterns, HostMatcher } from './host-patterns.js';
+import { type OwnTools } from './tool-leak.js';
+import type { Severity } from './types.js';
+/** A settled match. */
+interface EgressStreamHit {
+    rule: string;
+    severity: Severity;
+    /** Where in the reply the match starts (the start of its rewrite's source). */
+    start: number;
+    /** The detector whose match it is, or the id of the host's own. */
+    detector: string;
+}
+interface EgressStream {
+    /**
+     * Read the next piece of the reply; the matches that settled, none when the reply is clear so
+     * far.
+     */
+    push: (chunk: string) => EgressStreamHit[];
+    /** The earliest index of the reply a match could still start at. */
+    holdFrom: () => number;
+}
+/**
+ * Reads Theorem's automata, the most of the kernel's size, the first time a stream needs them.
+ * Every gate's constructor waits for this, so an app that never streams a reply never loads them.
+ */
+declare function loadEgressAutomata(): Promise<void>;
+/**
+ * Text grown at its end, with what its latest update added. Reading a grown
+ * string copies the whole of it, so what reads each new character reads it
+ * from `fresh`.
+ */
+interface Grown {
+    text: string;
+    fresh: string;
+}
+/**
+ * A rewrite of the reply, grown as the reply is: its settled text (no later
+ * reply text changes it) and, per settled character, the reply index a match
+ * starting there must be held from.
+ */
+interface View extends Grown {
+    /** Reply index to hold from for a match starting at view index `j`. */
+    rawAt: (j: number) => number;
+    /** Take whatever the source has settled since the last call. */
+    update: () => void;
+}
+/**
+ * `typoNormalize` of the source. It rewrites whole words (`\w` runs), so a
+ * word settles when a non-word character ends it, or as soon as it can no
+ * longer fold to a target (then the rest of it passes as is). A corrected word
+ * may be a letter longer or shorter than the word as written, so each
+ * character keeps the source index it stands for.
+ */
+declare function typoView(source: View): View;
+/** A rewrite whose characters keep their own reply index. */
+interface MappedView extends View {
+    from: number[];
+}
+/**
+ * `normalizeForDetection` of the reply, in its three passes: each code point
+ * mapped, emoji runs between letters dropped, a backslash before a letter
+ * dropped. Unsettled: a high surrogate whose low half may follow (in the reply
+ * or in the mapped text), an emoji run after a letter until the character
+ * after it, a backslash until the character after it.
+ */
+declare function normalizedReplyView(reply: Grown): MappedView;
+/**
+ * `decodeUrlRuns` of the reply: a run of `%XX` escapes is unsettled until the
+ * character after it shows the run is over. Its decoded text holds from the
+ * run's first `%`.
+ */
+declare function urlView(reply: Grown): MappedView;
+interface EgressStreamOptions {
+    /** The detectors whose matches the stream settles. Default none. */
+    detect?: readonly Detector[];
+    /** What `ungiven_images` and `ungiven_links` let through besides the given URLs. */
+    allow?: ResolvedAllow;
+    /**
+     * Whether `ungiven_links` leaves an image's own markup alone. Default: `ungiven_images` is
+     * among `detect`. Set when another reader has the images.
+     */
+    skipImages?: boolean;
+    /**
+     * The host's own patterns, read on the text as written, with their compiled table: those it
+     * adds to a detector, or those of a detector of its own, named by its id.
+     */
+    own?: readonly {
+        detector: string;
+        compiled: CompiledPatterns;
+        matchers: readonly HostMatcher[];
+    }[];
+    /** The URLs the model was given, for `ungiven_images` and `ungiven_links`. */
+    given?: GivenUrls;
+    /** The words of the profile's own canary note, for `marker_leak` (`boundaryNote`). */
+    note?: string;
+    /** The names of the profile's tools and of their parameters, for `tool_leak`. */
+    tools?: OwnTools;
+}
+/** Scans the detectors' patterns, Theorem's and the host's own, as a reply streams. */
+declare function createEgressStream(options?: EgressStreamOptions): EgressStream;
+export type { EgressStream, EgressStreamHit, EgressStreamOptions, Grown, MappedView, View };
+export { createEgressStream, loadEgressAutomata, normalizedReplyView, typoView, urlView };