@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/guardrails/event-schemas.js

@@ -1,36 +1,42 @@
-// Imports nothing from `src/kernel/` but the dependency-free `Equals`: `src/kernel/turn-events.ts` imports these.
+// invariant: Imports nothing from `src/kernel/` but the dependency-free `Equals`: `src/kernel/turn-events.ts` imports these.
 import { z } from 'zod';
-import { LEXICON_KEYS } from './lexicon.js';
+import { BOUNDARIES } from './boundaries.js';
+import { LABEL_KEYS } from './labels.js';
 import { ERROR_KINDS } from './theorem-error.js';
 import { GUARDRAIL_ACTIONS, GUARDRAIL_STAGES, SEVERITIES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';
 const errorKind = z.enum(ERROR_KINDS);
 true;
+/** The schema an error kind parses against. */
 export const errorKindSchema = errorKind;
 const errorCopy = z.object({
-    key: z.enum(LEXICON_KEYS),
+    key: z.enum(LABEL_KEYS),
     params: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
 });
 true;
 const errorCopies = z.union([errorCopy, z.array(errorCopy).readonly()]);
 true;
+/** The schema error wording parses against. */
 export const errorCopiesSchema = errorCopies;
-const provenance = z.object({
+export const provenance = z.object({
     origin: z.enum(TOOL_ORIGINS),
     tool: z.string(),
     depth: z.number(),
 });
 true;
-const guardrailHit = z.object({
+export const guardrailHit = z.object({
     rule: z.string(),
     severity: z.enum(SEVERITIES),
     span: z.object({ start: z.number(), end: z.number() }).optional(),
     match: z.string().optional(),
     label: z.string().optional(),
     doc: z.string().optional(),
+    pattern: z.string().optional(),
+    signal: z.string().optional(),
 });
 true;
 const guardrailEvent = z.object({
     stage: z.enum(GUARDRAIL_STAGES),
+    boundary: z.enum(BOUNDARIES).optional(),
     trust: z.enum(TRUST_LEVELS),
     action: z.enum(GUARDRAIL_ACTIONS),
     hits: z.array(guardrailHit),
@@ -38,4 +44,5 @@ const guardrailEvent = z.object({
     errorInternal: z.string().optional(),
 });
 true;
+/** The schema a guardrail event parses against. */
 export const guardrailEventSchema = guardrailEvent;

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

@@ -1,9 +1,13 @@
 import type { TurnEvent, TurnEventOf } from '../kernel/turn-events.js';
 import type { GuardrailAction, GuardrailEvent, GuardrailHit, GuardrailStage, Provenance, TrustLevel, Verdict } from './types.js';
+/** Wraps a guardrail event as a turn event. */
 declare function guardrailTurnEvent(guardrail: GuardrailEvent): TurnEventOf<'guardrail'>;
-/** `allow` yields nothing; `flag`, `redact` and `block` all emit so hosts and traces can count hits. */
+/** `allow` yields nothing; `flag`, `redact`, and `block` all emit so hosts and traces can count hits. */
 declare function guardrailFromVerdict(stage: GuardrailStage, trust: TrustLevel, verdict: Verdict, provenance?: Provenance): TurnEventOf<'guardrail'> | undefined;
+/** Builds the guardrail event for the hits found at a stage. */
 declare function guardrailFromHits(stage: GuardrailStage, trust: TrustLevel, hits: GuardrailHit[], action?: GuardrailAction, provenance?: Provenance): TurnEventOf<'guardrail'> | undefined;
+/** The guardrail turn event, with the matched text kept or dropped. */
 declare function projectGuardrailTurnEvent(event: TurnEventOf<'guardrail'>, includeMatch: boolean): TurnEventOf<'guardrail'>;
+/** The turn event unchanged, or a guardrail one with the matched text kept or dropped. */
 declare function projectGuardrailTurnEvent(event: TurnEvent, includeMatch: boolean): TurnEvent;
 export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent };

package/esm/src/guardrails/events.js

@@ -1,8 +1,9 @@
 import { projectGuardrailEvent } from './hits.js';
+/** Wraps a guardrail event as a turn event. */
 function guardrailTurnEvent(guardrail) {
     return { type: 'guardrail', guardrail };
 }
-/** `allow` yields nothing; `flag`, `redact` and `block` all emit so hosts and traces can count hits. */
+/** `allow` yields nothing; `flag`, `redact`, and `block` all emit so hosts and traces can count hits. */
 function guardrailFromVerdict(stage, trust, verdict, provenance) {
     if (verdict.action === 'allow') {
         return undefined;
@@ -18,6 +19,7 @@ function guardrailFromVerdict(stage, trust, verdict, provenance) {
             : {}),
     });
 }
+/** Builds the guardrail event for the hits found at a stage. */
 function guardrailFromHits(stage, trust, hits, action = 'redact', provenance) {
     if (hits.length === 0) {
         return undefined;
@@ -30,6 +32,7 @@ function guardrailFromHits(stage, trust, hits, action = 'redact', provenance) {
         ...(provenance ? { provenance } : {}),
     });
 }
+/** The turn event unchanged, or a guardrail one with the matched text kept or dropped. */
 function projectGuardrailTurnEvent(event, includeMatch) {
     if (event.type !== 'guardrail') {
         return event;

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

@@ -0,0 +1,14 @@
+/**
+ * What a model is told when a reply a detector blocked is retried: for each detector that
+ * matched, its hint and, where a match may be repeated, what it matched. The retry is read at the
+ * `repair` boundary like any other text on its way to the model, so a secret quoted here meets
+ * the action the profile set there.
+ *
+ * @module
+ */
+import { type ResolvedDetect } from './detectors.js';
+import type { GuardrailHit } from './event-schemas.js';
+import { type LabelOverrides } from './labels.js';
+/** The rejection a retry carries for the `hits` that stopped a reply, a line for each rule among them. */
+declare function retryRejection(hits: readonly GuardrailHit[], detect: ResolvedDetect, labels?: LabelOverrides): string;
+export { retryRejection };

package/esm/src/guardrails/hints.js

@@ -0,0 +1,57 @@
+/**
+ * What a model is told when a reply a detector blocked is retried: for each detector that
+ * matched, its hint and, where a match may be repeated, what it matched. The retry is read at the
+ * `repair` boundary like any other text on its way to the model, so a secret quoted here meets
+ * the action the profile set there.
+ *
+ * @module
+ */
+import { isDetector } from './detectors.js';
+import { labelText } from './labels.js';
+import { DETECT_RULES, EGRESS_RULES } from './rules.js';
+/** The hint of what stops a reply besides a detector's match. */
+const OTHER_HINTS = {
+    [EGRESS_RULES.unscannable]: 'egress.hint_unscannable',
+    [EGRESS_RULES.providerToolLeak]: 'egress.hint_provider_tool_leak',
+};
+/** The rules whose match is the profile's own, and is never repeated. */
+const UNQUOTED = [DETECT_RULES.canary_leak, DETECT_RULES.prompt_leak];
+/** How many matches a detector's line quotes, and how much of each. */
+const MAX_QUOTED = 3;
+const MAX_QUOTE = 120;
+const DETECT_PREFIX = 'detect.';
+/** The hint of the rule `hit` reports: the profile's, or else the labels'. */
+function hintOf(hit, detect, labels) {
+    const other = OTHER_HINTS[hit.rule];
+    if (other)
+        return labelText(other, {}, labels);
+    const key = hit.rule.startsWith(DETECT_PREFIX) ? hit.rule.slice(DETECT_PREFIX.length) : hit.rule;
+    if (isDetector(key)) {
+        return detect.hints?.[key] ?? labelText(`detect.hint.${key}`, {}, labels);
+    }
+    const host = detect.host?.find(({ id }) => id === key);
+    const label = host?.label ?? hit.label ?? key;
+    return host?.hint ?? labelText('detect.hint.own', { label }, labels);
+}
+/** The matched text of `hits` a line may quote: each once, the first few, cut to length. */
+function quoted(hits) {
+    const matches = hits.flatMap(({ rule, match }) => match && !UNQUOTED.includes(rule) ? [match] : []);
+    return [...new Set(matches)]
+        .slice(0, MAX_QUOTED)
+        .map((match) => JSON.stringify(match.length > MAX_QUOTE ? match.slice(0, MAX_QUOTE) : match));
+}
+/** The rejection a retry carries for the `hits` that stopped a reply, a line for each rule among them. */
+function retryRejection(hits, detect, labels) {
+    const byRule = new Map();
+    for (const hit of hits)
+        byRule.set(hit.rule, [...(byRule.get(hit.rule) ?? []), hit]);
+    const lines = [...byRule.values()].map((found) => {
+        const hint = hintOf(found[0], detect, labels);
+        const matches = quoted(found);
+        return matches.length > 0
+            ? labelText('egress.rejection_found', { hint, matches: matches.join(', ') }, labels)
+            : hint;
+    });
+    return labelText('egress.rejection', { found: lines.join('\n') }, labels);
+}
+export { retryRejection };

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

@@ -1,8 +1,14 @@
 import type { GuardrailEvent, GuardrailHit, Severity } from './types.js';
+/** A canary leak. Never carries the live token, only a placeholder. */
+declare const CANARY_HIT: GuardrailHit;
+/** A prompt leak. Never carries the words: they are the private system instruction's. */
+declare const PROMPT_ECHO_HIT: GuardrailHit;
+/** A guardrail hit for a span of the text, with the matched text sliced from it. */
 declare function hitFromSpan(text: string, span: {
     start: number;
     end: number;
+    name?: string;
 }, rule: string, severity: Severity): GuardrailHit;
 /** `match` is the caught text itself, so hosts and traces get it only via `observability.include.guardrailMatchPreview`. */
 declare function projectGuardrailEvent(event: GuardrailEvent, includeMatch: boolean): GuardrailEvent;
-export { hitFromSpan, projectGuardrailEvent };
+export { CANARY_HIT, hitFromSpan, PROMPT_ECHO_HIT, projectGuardrailEvent };

package/esm/src/guardrails/hits.js

@@ -1,9 +1,20 @@
+import { DETECT_RULES } from './rules.js';
+/** A canary leak. Never carries the live token, only a placeholder. */
+const CANARY_HIT = {
+    rule: DETECT_RULES.canary_leak,
+    severity: 'high',
+    match: '[canary]',
+};
+/** A prompt leak. Never carries the words: they are the private system instruction's. */
+const PROMPT_ECHO_HIT = { rule: DETECT_RULES.prompt_leak, severity: 'high' };
+/** A guardrail hit for a span of the text, with the matched text sliced from it. */
 function hitFromSpan(text, span, rule, severity) {
     return {
         rule,
         severity,
         span: { start: span.start, end: span.end },
         match: text.slice(span.start, span.end),
+        ...(span.name === undefined ? {} : { pattern: span.name }),
     };
 }
 /** `match` is the caught text itself, so hosts and traces get it only via `observability.include.guardrailMatchPreview`. */
@@ -16,4 +27,4 @@ function projectGuardrailEvent(event, includeMatch) {
         hits: event.hits.map(({ match: _match, ...hit }) => hit),
     };
 }
-export { hitFromSpan, projectGuardrailEvent };
+export { CANARY_HIT, hitFromSpan, PROMPT_ECHO_HIT, projectGuardrailEvent };

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

@@ -0,0 +1,85 @@
+/** labels-exempt-file: profile-registration diagnostics for a host's patterns — not runtime user or model copy (P2) */
+/**
+ * A pattern of the host's own, as data: a regular expression, or words. Words match whole and
+ * without regard to case, and a space in one matches any run of whitespace.
+ */
+type HostPattern = {
+    /** What a match is called in the trace. */
+    name: string;
+    /** The source of a regular expression. */
+    pattern: string;
+    /** Any of `i`, `m`, `s`, and `u`. Every match is found, so `g` is implied; `y` is refused. */
+    flags?: string;
+} | {
+    /** What a match is called in the trace. */
+    name: string;
+    words: readonly string[];
+};
+/**
+ * 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.
+ * - `leads`: per pattern, the charset an optional repeat opening it reads, or
+ *   -1. The pattern's nodes are of what follows the repeat.
+ * - `nodes`: each node as `[pattern, final (0/1), target, charset, target, charset, ...]`.
+ */
+interface AutomatonData {
+    classStarts: readonly number[];
+    charsets: readonly (readonly number[])[];
+    initials: readonly number[];
+    leads: readonly number[];
+    nodes: readonly (readonly number[])[];
+}
+/**
+ * What compiling a list of patterns writes (`compilePatterns`, `agents detect-compile`): the
+ * patterns it read and checked, and their automaton. A stream holds exactly the text a match
+ * could still be under way in by it.
+ */
+interface CompiledPatterns {
+    /** `PATTERN_COMPILER_VERSION` of the compiler that wrote it. */
+    compiler: number;
+    /** Each pattern as compiled, in order: a table that no longer matches its patterns is refused. */
+    patterns: readonly PatternSource[];
+    automaton: AutomatonData;
+}
+/** A pattern as the kernel runs it: the source and flags of its regular expression. */
+interface PatternSource {
+    name: string;
+    source: string;
+    flags: string;
+}
+/** A host pattern ready to run. */
+interface HostMatcher {
+    name: string;
+    /** Global, so every match is found. */
+    regex: RegExp;
+}
+/** Bumped whenever the compiled table's layout or meaning changes. */
+declare const PATTERN_COMPILER_VERSION = 3;
+/** The most patterns one detector takes, and the longest each may be once written as a regular expression. */
+declare const MAX_PATTERNS = 64;
+declare const MAX_PATTERN_LENGTH = 1024;
+/** The patterns as a compiled table records them. */
+declare function patternSources(patterns: readonly HostPattern[]): PatternSource[];
+/** What is wrong with one pattern, or `undefined` when it runs. */
+declare function patternProblem(path: string, pattern: unknown): string | undefined;
+/**
+ * What is wrong with a detector's `patterns` and the table `compiled` for them, or `undefined`
+ * when both are sound. Patterns need their table: compiling is where a pattern that could take
+ * more than linear time on hostile text is refused.
+ */
+declare function patternsProblem(path: string, patterns: unknown, compiled: unknown): string | undefined;
+/**
+ * What is wrong with a list of patterns before it is compiled, or `undefined`: an editor checks
+ * with it as the patterns are written.
+ */
+declare function patternListProblem(path: string, patterns: unknown): string | undefined;
+/** Whether any detector of `detect` lists patterns of the host's own, which need compiling. */
+declare function listsPatterns(detect: unknown): boolean;
+/** `patterns`, valid, ready to run. */
+declare function matchersOf(patterns: readonly HostPattern[]): readonly HostMatcher[];
+export type { AutomatonData, CompiledPatterns, HostMatcher, HostPattern, PatternSource };
+export { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, matchersOf, PATTERN_COMPILER_VERSION, patternListProblem, patternProblem, patternSources, patternsProblem, };

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

@@ -0,0 +1,173 @@
+// invariant: Leaf module. Imports nothing from `src/guardrails/types.ts` or `src/kernel/`, so
+// `detectors.ts` can read a host's patterns without a cycle.
+/** Bumped whenever the compiled table's layout or meaning changes. */
+const PATTERN_COMPILER_VERSION = 3;
+/** The most patterns one detector takes, and the longest each may be once written as a regular expression. */
+const MAX_PATTERNS = 64;
+const MAX_PATTERN_LENGTH = 1024;
+const PATTERN_FLAGS = 'imsu';
+/** A letter, digit, or underscore in any script: what a word may not touch on either side. */
+const WORD_UNIT = '[\\p{L}\\p{N}_]';
+function escaped(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** `words` as one alternation, longest first so a word is not cut short by one it starts with. */
+function wordsSource(words) {
+    const alternatives = [...new Set(words.map((word) => word.trim()).filter(Boolean))]
+        .sort((left, right) => right.length - left.length)
+        .map((word) => word.split(/\s+/).map(escaped).join('\\s+'));
+    return `(?<!${WORD_UNIT})(?:${alternatives.join('|')})(?!${WORD_UNIT})`;
+}
+/** The regular expression `pattern` runs as. */
+function patternSource(pattern) {
+    if ('words' in pattern) {
+        return { name: pattern.name, source: wordsSource(pattern.words), flags: 'iu' };
+    }
+    return { name: pattern.name, source: pattern.pattern, flags: pattern.flags ?? '' };
+}
+/** The patterns as a compiled table records them. */
+function patternSources(patterns) {
+    return patterns.map(patternSource);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStrings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/** What is wrong with the shape of one pattern, before it is compiled. */
+function shapeProblem(path, pattern) {
+    if (!isRecord(pattern))
+        return `${path} must be an object`;
+    const { name, words, flags } = pattern;
+    if (typeof name !== 'string' || !name.trim())
+        return `${path}.name must be a non-empty string`;
+    const kinds = ['pattern', 'words'].filter((key) => pattern[key] !== undefined);
+    if (kinds.length !== 1)
+        return `${path} takes one of pattern and words`;
+    const unknown = Object.keys(pattern).find((key) => !['name', 'pattern', 'flags', 'words'].includes(key));
+    if (unknown !== undefined) {
+        return `${path}.${unknown} is not a setting of a pattern (name, pattern, flags, words)`;
+    }
+    if (words !== undefined) {
+        if (flags !== undefined)
+            return `${path}.flags is a setting of pattern, not of words`;
+        if (!isStrings(words) || !words.some((word) => word.trim())) {
+            return `${path}.words must be a list with at least one word`;
+        }
+        return undefined;
+    }
+    if (typeof pattern.pattern !== 'string' || !pattern.pattern) {
+        return `${path}.pattern must be a non-empty string`;
+    }
+    if (flags === undefined)
+        return undefined;
+    if (typeof flags !== 'string')
+        return `${path}.flags must be a string`;
+    const bad = [...flags].find((flag, at) => !PATTERN_FLAGS.includes(flag) || flags.indexOf(flag) < at);
+    if (bad === 'y')
+        return `${path}.flags: a sticky (y) pattern only matches where the last one ended`;
+    if (bad === 'g')
+        return `${path}.flags: g is implied, every match is found`;
+    return bad === undefined
+        ? undefined
+        : `${path}.flags takes each of ${[...PATTERN_FLAGS].join(', ')} once, not ${JSON.stringify(bad)}`;
+}
+/** What is wrong with one pattern, or `undefined` when it runs. */
+function patternProblem(path, pattern) {
+    const shape = shapeProblem(path, pattern);
+    if (shape !== undefined)
+        return shape;
+    const { source, flags } = patternSource(pattern);
+    if (source.length > MAX_PATTERN_LENGTH) {
+        return `${path} is ${source.length} characters as a regular expression; the most is ${MAX_PATTERN_LENGTH}`;
+    }
+    let regex;
+    try {
+        // why: this only checks that the pattern parses and tests it on the empty text; a pattern that
+        // could run away on hostile text is refused when it is compiled (compilePatterns).
+        regex = new RegExp(source, `${flags}g`);
+    }
+    catch (err) {
+        return `${path} does not compile (${err instanceof Error ? err.message : String(err)})`;
+    }
+    // why: A pattern the empty text matches matches between every two characters: it names nothing.
+    return regex.test('') ? `${path} matches the empty text` : undefined;
+}
+/** Whether `compiled` was written for `sources` by this compiler. */
+function compiledProblem(path, compiled, sources) {
+    const again = 'run `agents detect-compile` or compilePatterns again';
+    if (!isRecord(compiled) || !isRecord(compiled.automaton) || !Array.isArray(compiled.patterns)) {
+        return `${path} must be the table compilePatterns or \`agents detect-compile\` writes`;
+    }
+    if (compiled.compiler !== PATTERN_COMPILER_VERSION) {
+        return `${path} comes from compiler ${String(compiled.compiler)}, this one is ${PATTERN_COMPILER_VERSION}; ${again}`;
+    }
+    return JSON.stringify(compiled.patterns) === JSON.stringify(sources)
+        ? undefined
+        : `${path} was compiled from other patterns; ${again}`;
+}
+/**
+ * What is wrong with a detector's `patterns` and the table `compiled` for them, or `undefined`
+ * when both are sound. Patterns need their table: compiling is where a pattern that could take
+ * more than linear time on hostile text is refused.
+ */
+function patternsProblem(path, patterns, compiled) {
+    if (patterns === undefined) {
+        return compiled === undefined ? undefined : `${path}.compiled is set without patterns`;
+    }
+    const problem = patternListProblem(path, patterns);
+    if (problem !== undefined)
+        return problem;
+    if (patterns.length === 0) {
+        return compiled === undefined ? undefined : `${path}.compiled is set without patterns`;
+    }
+    if (compiled === undefined) {
+        return `${path}.patterns need their compiled table: set ${path}.compiled from \`agents detect-compile\`, or wrap the detect setting in compileDetect from @theoremjs/agents/guardrails/compile`;
+    }
+    return compiledProblem(`${path}.compiled`, compiled, patternSources(patterns));
+}
+/**
+ * What is wrong with a list of patterns before it is compiled, or `undefined`: an editor checks
+ * with it as the patterns are written.
+ */
+function patternListProblem(path, patterns) {
+    if (!Array.isArray(patterns))
+        return `${path}.patterns must be a list`;
+    if (patterns.length > MAX_PATTERNS) {
+        return `${path}.patterns lists ${patterns.length} patterns; the most is ${MAX_PATTERNS}`;
+    }
+    const names = new Set();
+    for (const [index, pattern] of patterns.entries()) {
+        const at = `${path}.patterns[${index}]`;
+        const problem = patternProblem(at, pattern);
+        if (problem !== undefined)
+            return problem;
+        const { name } = pattern;
+        if (names.has(name))
+            return `${at}.name ${JSON.stringify(name)} is listed twice`;
+        names.add(name);
+    }
+    return undefined;
+}
+/** Whether any detector of `detect` lists patterns of the host's own, which need compiling. */
+function listsPatterns(detect) {
+    if (!isRecord(detect))
+        return false;
+    return Object.values(detect).some((rule) => isRecord(rule) && Array.isArray(rule.patterns) && rule.patterns.length > 0);
+}
+/** The matchers of each list of patterns, built once: a profile's patterns are resolved every turn. */
+const MATCHERS = new WeakMap();
+/** `patterns`, valid, ready to run. */
+function matchersOf(patterns) {
+    let matchers = MATCHERS.get(patterns);
+    if (!matchers) {
+        matchers = patternSources(patterns).map(({ name, source, flags }) => ({
+            name,
+            regex: new RegExp(source, `${flags}g`),
+        }));
+        MATCHERS.set(patterns, matchers);
+    }
+    return matchers;
+}
+export { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, matchersOf, PATTERN_COMPILER_VERSION, patternListProblem, patternProblem, patternSources, patternsProblem, };

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

@@ -5,6 +5,11 @@
  *
  * @module
  */
+/**
+ * An order to set instructions aside, with up to `gap` words between the verb
+ * and its object. `word` is what a word in the gap may be.
+ */
+declare function overrideFrame(gap: number, word?: string): string;
 declare const INJECTION_PATTERNS: RegExp[];
 /** Runs that might encode an injection; each is decoded and checked in `injection.ts`. */
 declare const BASE64_BLOB: RegExp;
@@ -12,4 +17,4 @@ declare const HEX_BLOB: RegExp;
 declare const SPACED_LETTERS: RegExp;
 /** Three+ alphabetic tokens joined by `|` (no shell spaces around pipes). */
 declare const PIPE_SEPARATED: RegExp;
-export { BASE64_BLOB, HEX_BLOB, INJECTION_PATTERNS, PIPE_SEPARATED, SPACED_LETTERS };
+export { BASE64_BLOB, HEX_BLOB, INJECTION_PATTERNS, overrideFrame, PIPE_SEPARATED, SPACED_LETTERS };

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

@@ -45,6 +45,37 @@ const LLAMA_INST = /\[\/?INST\]/gi;
 const IGNORE_YOUR_INSTRUCTIONS = /ignore\s+(all\s+)?(your\s+)?(instructions?|rules?)\b/gi;
 const UNRESTRICTED_MODE = /\bunrestricted\s+(ai|mode|model)\b/gi;
 const IGNORE_MULTILANG = /\b(?:ignorieren|ignorez|ignora|ignorer|oubliez|vergessen|olvida|desestima|missachten)\b[\s\S]{0,50}\b(?:anweisungen|instructions?|instrucciones|directives?|r[eè]gles|reglas)\b/gi;
+/** The verbs that tell a reader to set a thing aside, as written to give an order. */
+const OVERRIDE_VERB = 'ignore|disregard|forget|override|bypass';
+/** What an agent is told to set aside. */
+const OVERRIDE_OBJECT = 'instructions?|rules|guidelines?|constraints?|directives?|prompts?';
+const FRAME_WORD = String.raw `[\w'’-]{1,40}`;
+/**
+ * An order to set instructions aside, with up to `gap` words between the verb
+ * and its object. `word` is what a word in the gap may be.
+ */
+function overrideFrame(gap, word = FRAME_WORD) {
+    return String.raw `\b(?:${OVERRIDE_VERB})\s+(?:${word}\s+){0,${gap}}(?:${OVERRIDE_OBJECT})\b`;
+}
+/** The verb is negated: "never ignore the rules". */
+const NEGATED = String.raw `(?<!(?:\b(?:not|never|cannot|without)|n['’]t)\s+(?:${FRAME_WORD}\s+)?)`;
+/** The verb is a noun: "his disregard for the rules". */
+const NOUN_USE = String.raw `(?<!\b(?:the|a|an|his|her|its|their|your|my|our)\s+)`;
+/**
+ * The verb reports or describes, and "you" is not its subject: "an attempt to
+ * bypass the rules", "I must ignore the instructions", "they override
+ * constraints". "you must ignore the rules" and "I want you to ignore the
+ * rules" stay orders.
+ */
+const DESCRIBED = String.raw `(?:(?<=\byou\s+(?:${FRAME_WORD}\s+){0,2})|(?<!\b(?:to|must|should|would|will|can|could|may|might|shall|I|we|they|he|she|it|who|that|which)\s+(?:\w+ly\s+)?))`;
+/** A word in the gap that is not the writer's own: "ignore my rules" speaks of the writer's rules. */
+const NOT_OWN = String.raw `(?!(?:my|our)\b)${FRAME_WORD}`;
+/**
+ * {@linkcode overrideFrame} where the verb gives the reader an order about
+ * the reader's instructions. The patterns above still match their own wording
+ * in every guarded case.
+ */
+const OVERRIDE_FRAME = new RegExp(`${NEGATED}${NOUN_USE}${DESCRIBED}${overrideFrame(3, NOT_OWN)}`, 'gi');
 const INJECTION_PATTERNS = [
     IGNORE_PREVIOUS,
     DISREGARD_INSTRUCTIONS,
@@ -84,6 +115,7 @@ const INJECTION_PATTERNS = [
     IGNORE_YOUR_INSTRUCTIONS,
     UNRESTRICTED_MODE,
     IGNORE_MULTILANG,
+    OVERRIDE_FRAME,
 ];
 /** Runs that might encode an injection; each is decoded and checked in `injection.ts`. */
 const BASE64_BLOB = /[A-Za-z0-9+/]{16,}={0,2}/g;
@@ -91,4 +123,4 @@ const HEX_BLOB = /(?:[0-9a-f]{2}[\s]?){8,}/gi;
 const SPACED_LETTERS = /\b(?:[A-Za-z] ){3,}[A-Za-z]\b/g;
 /** Three+ alphabetic tokens joined by `|` (no shell spaces around pipes). */
 const PIPE_SEPARATED = /\b(?:[A-Za-z]+\|){2,}[A-Za-z]+\b/g;
-export { BASE64_BLOB, HEX_BLOB, INJECTION_PATTERNS, PIPE_SEPARATED, SPACED_LETTERS };
+export { BASE64_BLOB, HEX_BLOB, INJECTION_PATTERNS, overrideFrame, PIPE_SEPARATED, SPACED_LETTERS };

package/esm/src/guardrails/injection-reversed.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generated by `scripts/gen-egress-automata.ts` from `egress-patterns.ts`.
+ * Do not edit: change the patterns and run the script.
+ *
+ * @module
+ */
+/** Each injection pattern reversed: it matches where the pattern matches the text written backwards. */
+declare const REVERSED_INJECTION_PATTERNS: RegExp[];
+export { REVERSED_INJECTION_PATTERNS };

package/esm/src/guardrails/injection-reversed.js

@@ -0,0 +1,49 @@
+/**
+ * Generated by `scripts/gen-egress-automata.ts` from `egress-patterns.ts`.
+ * Do not edit: change the patterns and run the script.
+ *
+ * @module
+ */
+/** Each injection pattern reversed: it matches where the pattern matches the text written backwards. */
+const REVERSED_INJECTION_PATTERNS = [
+    /(?:S?NOITCURTSNI|S?ELUR|S?ENILEDIUG|S?TNIARTSNOC|S?EVITCERID)(?:\s+(?:YTEFAS|YTIRUCES|METSYS|LANOITAREPO|LANRETNI|EROC|LANIGIRO|LAITINI|GNITSIXE|NEVIG|DETATS|DEDIVORP|DENIFED|DEIFICEPS|DEHSILBATSE))?\s+(?:SUOIVERP|ROIRP)(?:\s+LLA)?\s+ERONGI/gi,
+    /(?:S?NOITCURTSNI|S?ELUR|S?ENILEDIUG|S?TNIARTSNOC|S?EVITCERID)\s+(?:SUOIVERP|ROIRP|EVOBA)(?:\s+LLA)?\s+DRAGERSID/gi,
+    /(?:S?NOITCURTSNI|S?ELUR|S?ENILEDIUG|S?TNIARTSNOC|S?EVITCERID)\s+(?:SUOIVERP|ROIRP|EVOBA)(?:\s+LLA)?\s+TEGROF/gi,
+    /:S?NOITCURTSNI\s+WEN/gi,
+    /(?:METSYS|REPOLEVED|SUOIVERP|LANIGIRO)(?:\s+EHT)?\s+WOLLOF\s+TON\s+OD/gi,
+    /(?:S?NOITCURTSNI|S?ELUR|S?ENILEDIUG|S?TNIARTSNOC|S?EVITCERID)\s+(?:ROIRP|SUOIVERP)(?:\s+LLA)?\s+S?EDESREPUS/gi,
+    /(?:DIOV|DILAVNI|LLUN|ETELOSBO|DELLECNAC|DEKOVER)\s+(?:ERA|SI)\s+S?NOITCURTSNI\s+(?:SUOIVERP|ROIRP)(?:\s+LLA)?/gi,
+    /EDOM\s+REPOLEVED(?:\s+NI)?\s+WON\s+ERA\s+UOY/gi,
+    /(?<!\b(?:NI|NO|AIV|HGUORHT|MORF|GNISU|ROF)\s+)EDOM\s+(?:REPOLEVED|NIMDA|GUBED|ECNANETNIAM)\s+RETNE/gi,
+    /(?<!\b(?:NI|NO|AIV|HGUORHT|MORF|GNISU|ROF)\s+)EDOM\s+(?:REPOLEVED|NIMDA|GUBED|KAERBLIAJ)\s+ETAVITCA/gi,
+    /\bEDIRREVO\s+METSYS\b/gi,
+    /(?:S?NOITCURTSNI|S?ELUR|S?ENILEDIUG|S?TNIARTSNOC|S?EVITCERID)(?:\s+RUOY)?\s+EDIRREVO/gi,
+    /\bTPMORP(?:\s+(?:METSYS|EMTSYS|MTESYS|P?METSYS))?(?:\s+(?:LLUF|NEDDIH|ETELPMOC|LANRETNI|TERCES|LANIGIRO|ERITNE|TCAXE|LAUTCA|LAER)){0,2}(?:\s+(?:R?UOY|UROY|ROUY|EHT|YM|STI|SIH|REH|RUO|RIEHT))?\s+LAEVER/gi,
+    /\bTPMORP(?:\s+(?:METSYS|EMTSYS|MTESYS|P?METSYS))?\s+(?:R?UOY|UROY|ROUY|EHT|YM|STI|SIH|REH|RUO|RIEHT)(?:\s+EM)?\s+WOHS/gi,
+    /SNOITCURTSNI(?:\s+TCAXE)?(?:\s+RUOY)?\s+(?:ERA|EREW)\s+TAHW/gi,
+    /(?:EVOBA|EROFEB)\s+(?:TXET|S?NOITCURTSNI)(?:\s+EHT)?\s+TAEPER/gi,
+    /(?:TPMORP|S?NOITCURTSNI)\s+(?:LAITINI|LANIGIRO|METSYS)(?:\s+RUOY)?\s+TUPTUO/gi,
+    /(?:DNUOB|DETCIRTSER|DETIMIL)\s+REGNOL\s+ON\s+ERA\s+UOY/gi,
+    /DNUOB\s+TON(?:\s+(?:ER'|ERA\s+)UOY)?\s+FI\s+SA\s+TCA/gi,
+    /(?:IA|TNATSISSA|LEDOM)\s+TNEREFFID(?:\s+A)?(?:\s+(?:ER'|ERA\s+)UOY)?\s+DNETERP/gi,
+    /(?:TCIRTSER(?:\s+YNA)?\s+TUOHTIW|(?:LLA|YNA|YREVE|VERP)\s+\w*RONGI|SSAPYB|TCIRTSERNU|TIMILNU|YLNO\s+YEBO|(?:SELUR|STIMIL|TCIRTSER|IRADNUOB)\s+ON).{0,40}\w+(?:\s+(?:A|NA))?\s+WON\s+ERA\s+UOY/gi,
+    /\bwon\s+gnihtyna\s+od\b[\s\S]{0,120}\bNAD\b/g,
+    /(?:EDOM|TPMORP)\s+(?:DE)?KAERBLIAJ/gi,
+    /\bWON\s+GNIHTYNA\s+OD\b/gi,
+    /(?:S?RETLIF|S?ERUSAEM|S?ENILEDIUG|S?NOITCIRTSER)\s+(?:YTEFAS|YTIRUCES|TNETNOC|LACIHTE)(?:\s+RUOY)?\s+SSAPYB/gi,
+    /(?:S?RETLIF|S?ERUSAEM|S?ELUR|S?ENILEDIUG|S?NOITCIRTSER)\s+(?:YTEFAS|YTIRUCES|TNETNOC)(?:\s+RUOY)?(?:\s+LLA)?\s+(?:ELBASID|ETELED|EVOMER|FFO\s+NRUT|ETANIMILE)/gi,
+    /(?:S?ENILEDIUG|S?ELUR|S?NOITCIRTSER|S?ERUSAEM|S?RETLIF|(?:Y|SEI)CILOP|S?LOCOTORP)\s+(?:YTEFAS|YTIRUCES|LACIHTE|TNETNOC)(?:\s+RUOY)?(?:\s+LLA)?\s+(?:ERONGI|DRAGERSID)/gi,
+    />\/?[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}METSYS[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}\/?[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}</gi,
+    />\/?[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}(?:TNATSISSA|REPOLEVED|LOOT|NOITCNUF)[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}\/?[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}</gi,
+    /:\]?(?:METSYS|TNATSISSA|RESU)\[?[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}\n[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}\]/gi,
+    /\][\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}(?:EGASSEM[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,8}METSYS|METSYS|TNATSISSA|LANRETNI)[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}\[/gi,
+    /(?:ERA\s+UOY|ERONGI|EDIRREVO)[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{1,32}:METSYS[\t\v\f \xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]{0,32}$/gim,
+    />\|(?:trats_mi|dne_mi|di_toe|di_redaeh_trats|di_redaeh_dne|txetfodne)\|</g,
+    />\uff5c(?:ecnetnes\u2581fo\u2581dne|ecnetnes\u2581fo\u2581nigeb)\uff5c</g,
+    /\]TSNI\/?\[/gi,
+    /\b(?:S?NOITCURTSNI|S?ELUR)(?:\s+RUOY)?(?:\s+LLA)?\s+ERONGI/gi,
+    /\b(?:IA|EDOM|LEDOM)\s+DETCIRTSERNU\b/gi,
+    /\b(?:NEGNUSIEWNA|S?NOITCURTSNI|SENOICCURTSNI|S?EVITCERID|SELG[E\xc8]R|SALGER)\b[\s\S]{0,50}\b(?:NEREIRONGI|ZERONGI|ARONGI|RERONGI|ZEILBUO|NESSEGREV|ADIVLO|AMITSESED|NETHCASSIM)\b/gi,
+    /\b(?:S?NOITCURTSNI|SELUR|S?ENILEDIUG|S?TNIARTSNOC|S?EVITCERID|S?TPMORP)(?:\s+[-\w'\u2019]{1,40}(?<!\b(?:YM|RUO))){0,3}\s+(?:ERONGI|DRAGERSID|TEGROF|EDIRREVO|SSAPYB)\b(?:(?=(?:\s+[-\w'\u2019]{1,40}){0,2}\s+UOY\b)|(?!(?:\s+YL\w+)?\s+(?:OT|TSUM|DLUOHS|DLUOW|LLIW|NAC|DLUOC|YAM|THGIM|LLAHS|I|EW|YEHT|EH|EHS|TI|OHW|TAHT|HCIHW)\b))(?!\s+(?:EHT|A|NA|SIH|REH|STI|RIEHT|RUOY|YM|RUO)\b)(?!(?:\s+[-\w'\u2019]{1,40})?\s+(?:(?:TON|REVEN|TONNAC|TUOHTIW)\b|T['\u2019]N))/gi,
+];
+export { REVERSED_INJECTION_PATTERNS };

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

@@ -1,6 +1,15 @@
 import { type RedactSpan } from '../observability/spans.js';
 declare const TYPO_TARGETS: string[];
 declare function typoNormalize(text: string): string;
+/**
+ * `typoNormalize(text)`, and for an index in it the index of `text` it stands
+ * for. A corrected word may be a letter longer or shorter than the word as
+ * written, so an index past the written word stands for its last letter.
+ */
+declare function typoFolded(text: string): {
+    text: string;
+    at: (index: number) => number;
+};
 /** Blob patterns whose match is a hit only when the blob decodes to an injection. */
 declare const INJECTION_BLOBS: readonly {
     pattern: RegExp;
@@ -9,6 +18,13 @@ declare const INJECTION_BLOBS: readonly {
 declare function tryRot13(text: string): string;
 /** Each run of `%XX` escapes decoded on its own, so one stray `%` cannot switch decoding off. */
 declare function decodeUrlRuns(text: string): string;
+declare const LEET_MAP: Record<string, string>;
 declare function tryLeet(text: string): string | undefined;
+/**
+ * The spans of injection in the text, each stretch once. The text is read as
+ * written and in each rewrite of it: typo-folded, normalized, decoded, and its
+ * encoded blobs. A match in a rewrite is the stretch of the text as written it
+ * was read from, so text around a match stays.
+ */
 declare function injectionSpans(text: string): RedactSpan[];
-export { decodeUrlRuns, INJECTION_BLOBS, injectionSpans, TYPO_TARGETS, tryLeet, tryRot13, typoNormalize, };
+export { decodeUrlRuns, INJECTION_BLOBS, injectionSpans, LEET_MAP, TYPO_TARGETS, tryLeet, tryRot13, typoFolded, typoNormalize, };