@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,33 @@
+/**
+ * Build-time compiler for egress rules, behind `@theoremjs/agents/guardrails/compile`.
+ *
+ * The streaming egress 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 egress-compile` writes the table, and `egressPolicy` loads it.
+ *
+ * An automaton drops its pattern's assertions: a lookbehind, `\b`, `^` and `$`
+ * match nothing, and a lookahead may be read or skipped. A bounded repeat over
+ * `COUNT_LIMIT` is unbounded. 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 CompiledEgressRules, type EgressAutomatonData, type EgressRule } from './egress-rules.js';
+/** The table `egressPolicy` needs to hold exactly for `rules`. */
+declare function compileEgressRules(rules: readonly EgressRule[]): CompiledEgressRules;
+/** `compiled` as a module exporting it as `compiledEgressRules`. */
+declare function compiledEgressModule(compiled: CompiledEgressRules): 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: EgressAutomatonData;
+    reversed: EgressAutomatonData;
+};
+export { bundledEgressAutomata, compiledEgressModule, compileEgressRules };

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

@@ -0,0 +1,237 @@
+/**
+ * Build-time compiler for egress rules, behind `@theoremjs/agents/guardrails/compile`.
+ *
+ * The streaming egress 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 egress-compile` writes the table, and `egressPolicy` loads it.
+ *
+ * An automaton drops its pattern's assertions: a lookbehind, `\b`, `^` and `$`
+ * match nothing, and a lookahead may be read or skipped. A bounded repeat over
+ * `COUNT_LIMIT` is unbounded. 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 { EGRESS_PATTERNS } from './egress-patterns.js';
+import { assertEgressRules, EGRESS_COMPILER_VERSION, ruleFingerprint, } from './egress-rules.js';
+import { TheoremError } from './error.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:
+            // lexicon-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: a lookbehind (and `\b`, `^`, `$`,
+ * which parse to lookarounds) matches the empty string, a lookahead is either
+ * skipped or read as part of the match, and a long bounded repeat is unbounded.
+ */
+function loosened(alternatives) {
+    return alternatives.map((concat) => ({
+        type: 'Concatenation',
+        elements: concat.elements.flatMap(loosenedElement),
+    }));
+}
+function loosenedElement(element) {
+    switch (element.type) {
+        case 'Alternation':
+            return [{ ...element, alternatives: loosened(element.alternatives) }];
+        case 'Quantifier':
+            return [
+                {
+                    ...element,
+                    max: element.max > COUNT_LIMIT ? Number.POSITIVE_INFINITY : element.max,
+                    alternatives: loosened(element.alternatives),
+                },
+            ];
+        case 'Assertion':
+            if (element.kind === 'behind')
+                return [];
+            return [
+                {
+                    type: 'Alternation',
+                    alternatives: [
+                        { type: 'Concatenation', elements: [] },
+                        ...loosened(element.alternatives),
+                    ],
+                },
+            ];
+        case 'CharacterClass':
+            return [element];
+        default:
+            // lexicon-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;
+}
+/** 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(literal.source, literal.flags);
+}
+function nfaOf(alternatives) {
+    const nfa = NFA.fromRegex(loosened(alternatives), { maxCharacter: MAX_CHAR });
+    nfa.removeUnreachable();
+    return { initial: nfa.initial, nodes: [...nfa.nodes()], finals: nfa.finals };
+}
+/** 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) {
+        for (const node of nfa.nodes) {
+            for (const set of node.out.values()) {
+                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);
+        }
+    });
+    return { classStarts, charsets, initials, nodes };
+}
+/** The table `egressPolicy` needs to hold exactly for `rules`. */
+function compileEgressRules(rules) {
+    assertEgressRules(rules);
+    const alternatives = rules.map(({ rule, pattern }) => {
+        try {
+            const units = parsed(pattern);
+            nfaOf(units);
+            return units;
+        }
+        catch (err) {
+            throw new TheoremError('config', `egress rule ${rule}: ${pattern} has no automaton the stream can hold for (${err instanceof Error ? err.message : String(err)})`);
+        }
+    });
+    return {
+        compiler: EGRESS_COMPILER_VERSION,
+        rules: ruleFingerprint(rules),
+        automaton: automatonData(alternatives),
+    };
+}
+/** `compiled` as a module exporting it as `compiledEgressRules`. */
+function compiledEgressModule(compiled) {
+    // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    return `// Generated by \`agents egress-compile\`. Do not edit: change the rules and compile again.
+export const compiledEgressRules = ${JSON.stringify(compiled)};
+`;
+}
+/**
+ * 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, compiledEgressModule, compileEgressRules };

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

@@ -0,0 +1,24 @@
+/**
+ * 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.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[];
+export type { EgressPattern, EgressPatternKind };
+export { EGRESS_PATTERNS, SYSTEM_BOUNDARY };

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

@@ -0,0 +1,32 @@
+/**
+ * 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|<\s*(?:\/\s*)?user_data(?:\s*(?:\/\s*)?>)?/i; // lexicon-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 })),
+];
+export { EGRESS_PATTERNS, SYSTEM_BOUNDARY };

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

@@ -0,0 +1,27 @@
+/**
+ * `egressPolicy`: the bundled egress checks a host selects, with its own
+ * rules added. The rules' automata come from `agents egress-compile`, so the
+ * stream holds exactly the text a host match could still be under way in, as
+ * it does for the bundled patterns.
+ *
+ * @module
+ */
+import { type EgressChecks } from './egress.js';
+import { type CompiledEgressRules, type EgressRule } from './egress-rules.js';
+import type { EgressEnforcer } from './types.js';
+interface EgressPolicyOptions {
+    /** Host rules, blocked on alongside the bundled checks. */
+    rules?: readonly EgressRule[];
+    /** `compiledEgressRules` from the module `agents egress-compile` wrote for `rules`. */
+    compiled?: CompiledEgressRules;
+    /**
+     * The bundled checks: `true` (the default) runs each at its default, `false`
+     * none, and an object switches the ones it names (`EgressChecks`). The
+     * system-prompt leak checks run either way.
+     */
+    bundled?: boolean | EgressChecks;
+}
+/** An egress enforce that blocks on each host rule and on the bundled checks `bundled` selects. */
+declare function egressPolicy({ rules, compiled, bundled, }?: EgressPolicyOptions): EgressEnforcer;
+export type { EgressPolicyOptions };
+export { egressPolicy };

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

@@ -0,0 +1,76 @@
+/**
+ * `egressPolicy`: the bundled egress checks a host selects, with its own
+ * rules added. The rules' automata come from `agents egress-compile`, so the
+ * stream holds exactly the text a host match could still be under way in, as
+ * it does for the bundled patterns.
+ *
+ * @module
+ */
+import { collectEgressHits, egressChecksProblem, egressScope, hitsEnforcer, NO_CHECKS, registerEgressChecks, resolveEgressChecks, } from './egress.js';
+import { assertEgressRules, EGRESS_COMPILER_VERSION, globalPattern, ruleFingerprint, } from './egress-rules.js';
+import { createEgressStream, registerStreamPlan, } from './egress-stream.js';
+import { TheoremError } from './error.js';
+import { hitFromSpan } from './hits.js';
+/** Every host rule's matches in `text`. An empty match is not a hit. */
+function ruleHits(text, rules) {
+    const hits = [];
+    for (const { rule, severity, pattern } of rules) {
+        for (const match of text.matchAll(pattern)) {
+            if (!match[0])
+                continue;
+            hits.push(hitFromSpan(text, { start: match.index, end: match.index + match[0].length }, rule, severity));
+        }
+    }
+    return hits;
+}
+/** A compiled table that no longer matches `rules` would hold for the wrong patterns. */
+function assertCompiledFor(rules, compiled) {
+    const stale = (why) => configError(`the compiled rules ${why}; run \`agents egress-compile\` again`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (compiled?.compiler !== EGRESS_COMPILER_VERSION) {
+        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw stale(`come from compiler ${compiled?.compiler}, this one is ${EGRESS_COMPILER_VERSION}`);
+    }
+    const want = ruleFingerprint(rules);
+    if (JSON.stringify(compiled.rules) !== JSON.stringify(want)) {
+        throw stale('were compiled from different rules'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function configError(message) {
+    return new TheoremError('config', `egressPolicy: ${message}`);
+}
+function assertEgressChecks(checks) {
+    const problem = egressChecksProblem('bundled', checks);
+    if (problem !== undefined)
+        throw configError(problem);
+}
+/** An egress enforce that blocks on each host rule and on the bundled checks `bundled` selects. */
+function egressPolicy({ rules = [], compiled, bundled = true, } = {}) {
+    assertEgressRules(rules);
+    if (rules.length > 0) {
+        if (compiled === undefined) {
+            throw configError('rules need the compiled table `agents egress-compile` writes for them'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        assertCompiledFor(rules, compiled);
+    }
+    assertEgressChecks(bundled);
+    const checks = bundled === false ? NO_CHECKS : resolveEgressChecks(bundled === true ? {} : bundled);
+    const host = rules.map(({ rule, pattern, severity }) => ({
+        rule,
+        severity: severity ?? 'high',
+        pattern: globalPattern(pattern),
+    }));
+    const enforce = hitsEnforcer((text, context) => {
+        const hits = collectEgressHits(text, egressScope(context), checks);
+        hits.push(...ruleHits(text, host));
+        return hits;
+    });
+    const scan = compiled && host.length > 0 ? { automaton: compiled.automaton, rules: host } : undefined;
+    registerStreamPlan(enforce, (context) => createEgressStream({
+        checks,
+        ...(scan ? { host: scan } : {}),
+        ...(context.givenUrls ? { given: context.givenUrls } : {}),
+    }));
+    registerEgressChecks(enforce, checks);
+    return enforce;
+}
+export { egressPolicy };

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

@@ -0,0 +1,54 @@
+/**
+ * Host egress rules: the patterns a host adds to (or runs instead of) the
+ * bundled egress policy, and the tables `agents egress-compile` writes for
+ * them. Shared by the build-time compiler and `egressPolicy`.
+ *
+ * @module
+ */
+import type { Severity } from './types.js';
+/** One host egress rule: a reply matching `pattern` is blocked under `rule`. */
+interface EgressRule {
+    /** The rule id hits carry, e.g. `acme.account-number`. `egress.` ids are the bundled policy's. */
+    rule: string;
+    /** Matched on the reply as written. No sticky (`y`) flag; `g` is implied. */
+    pattern: RegExp;
+    /** Default `high`. */
+    severity?: Severity;
+}
+/**
+ * An automaton over UTF-16 code units, as tables.
+ *
+ * - `classStarts`: first code unit of each character class; class k covers
+ *   `[classStarts[k], classStarts[k+1])`.
+ * - `charsets`: each charset as the sorted class ids it contains.
+ * - `initials`: the initial node of each pattern.
+ * - `nodes`: each node as `[pattern, final (0/1), target, charset, target, charset, ...]`.
+ */
+interface EgressAutomatonData {
+    classStarts: readonly number[];
+    charsets: readonly (readonly number[])[];
+    initials: readonly number[];
+    nodes: readonly (readonly number[])[];
+}
+/** What `compileEgressRules` writes: the rules it read, and their automaton. */
+interface CompiledEgressRules {
+    /** `EGRESS_COMPILER_VERSION` of the compiler that wrote it. */
+    compiler: number;
+    /** Each rule's id and pattern, in order: `egressPolicy` refuses a table that no longer matches its rules. */
+    rules: readonly {
+        rule: string;
+        source: string;
+        flags: string;
+    }[];
+    automaton: EgressAutomatonData;
+}
+/** Bumped whenever the compiled table's layout or meaning changes. */
+declare const EGRESS_COMPILER_VERSION = 1;
+/** Rule ids are non-empty, unique and not the bundled policy's; patterns are not sticky. */
+declare function assertEgressRules(rules: readonly EgressRule[]): void;
+/** The rules as a compiled table records them. */
+declare function ruleFingerprint(rules: readonly EgressRule[]): CompiledEgressRules['rules'];
+/** The pattern, global, for scanning every match. */
+declare function globalPattern(pattern: RegExp): RegExp;
+export type { CompiledEgressRules, EgressAutomatonData, EgressRule };
+export { assertEgressRules, EGRESS_COMPILER_VERSION, globalPattern, ruleFingerprint };

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

@@ -0,0 +1,49 @@
+/**
+ * Host egress rules: the patterns a host adds to (or runs instead of) the
+ * bundled egress policy, and the tables `agents egress-compile` writes for
+ * them. Shared by the build-time compiler and `egressPolicy`.
+ *
+ * @module
+ */
+import { TheoremError } from './error.js';
+/** Bumped whenever the compiled table's layout or meaning changes. */
+const EGRESS_COMPILER_VERSION = 1;
+const RESERVED_PREFIX = 'egress.';
+function configError(message) {
+    return new TheoremError('config', message);
+}
+/** Rule ids are non-empty, unique and not the bundled policy's; patterns are not sticky. */
+function assertEgressRules(rules) {
+    const seen = new Set();
+    for (const { rule, pattern } of rules) {
+        if (typeof rule !== 'string' || !rule.trim()) {
+            throw configError('egress rule ids must be non-empty strings'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (rule.startsWith(RESERVED_PREFIX)) {
+            throw configError(
+            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            `egress rule ${rule}: ids starting "${RESERVED_PREFIX}" are the bundled policy's`);
+        }
+        if (seen.has(rule)) {
+            throw configError(`egress rule ${rule} is listed twice`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        seen.add(rule);
+        if (!(pattern instanceof RegExp)) {
+            throw configError(`egress rule ${rule}: pattern must be a RegExp`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        if (pattern.sticky) {
+            throw configError(
+            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            `egress rule ${rule}: a sticky (y) pattern only matches where the last one ended`);
+        }
+    }
+}
+/** The rules as a compiled table records them. */
+function ruleFingerprint(rules) {
+    return rules.map(({ rule, pattern }) => ({ rule, source: pattern.source, flags: pattern.flags }));
+}
+/** The pattern, global, for scanning every match. */
+function globalPattern(pattern) {
+    return new RegExp(pattern.source, pattern.global ? pattern.flags : `${pattern.flags}g`);
+}
+export { assertEgressRules, EGRESS_COMPILER_VERSION, globalPattern, ruleFingerprint };

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

@@ -0,0 +1,105 @@
+/**
+ * The bundled egress policy, run on a reply as it streams.
+ *
+ * The bundled checks match their 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 the reply is
+ * blocked there. Each character is read a bounded number of times, so a long
+ * reply costs time in proportion to its length.
+ *
+ * @module
+ */
+import { type ResolvedEgressChecks } from './egress.js';
+import { type EgressAutomatonData } from './egress-rules.js';
+import { type GivenUrls } from './egress-urls.js';
+import type { EgressEnforcer, GuardrailContext, Severity } from './types.js';
+/** A settled match the policy blocks on. */
+interface EgressStreamHit {
+    rule: string;
+    severity: Severity;
+    /** Where in the reply the match starts (the start of its rewrite's source). */
+    start: number;
+}
+interface EgressStream {
+    /** Read the next piece of the reply; a hit when a match has settled. */
+    push: (chunk: string) => EgressStreamHit | undefined;
+    /** The earliest index of the reply a match could still start at. */
+    holdFrom: () => number;
+}
+/**
+ * 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) of the
+ * same length, 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).
+ */
+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 normalizedView(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 bundled checks to run. Default each at its default (`EgressChecks`). */
+    checks?: ResolvedEgressChecks;
+    /** Host rules, read on the reply as written, with their compiled automaton. */
+    host?: {
+        automaton: EgressAutomatonData;
+        rules: readonly {
+            rule: string;
+            severity: Severity;
+            pattern: RegExp;
+        }[];
+    };
+    /** The URLs the model was given, for the image and link checks. */
+    given?: GivenUrls;
+}
+/** Scans the bundled egress policy's patterns, and any host rules, as a reply streams. */
+declare function createEgressStream(options?: EgressStreamOptions): EgressStream;
+/** A stream running a policy's checks, for the turn or session `context` describes. */
+type EgressStreamPlan = (context: GuardrailContext) => EgressStream;
+/** The streaming plan for `enforce`, when the stream knows its checks. */
+declare function streamPlanOf(enforce: EgressEnforcer): EgressStreamPlan | undefined;
+/** Tell the gate `enforce` runs exactly the checks `plan` streams. */
+declare function registerStreamPlan(enforce: EgressEnforcer, plan: EgressStreamPlan): void;
+export type { EgressStream, EgressStreamHit, EgressStreamOptions, EgressStreamPlan, Grown, MappedView, View, };
+export { createEgressStream, normalizedView, registerStreamPlan, streamPlanOf, typoView, urlView };