@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/guardrails/injection.js

@@ -1,7 +1,7 @@
-import { blobAt, spansFromPatterns } from '../observability/spans.js';
-import { REVERSED_INJECTION_PATTERNS } from './egress-automata.js';
+import { blobAt, mergeSpans, spansFromPatterns } from '../observability/spans.js';
 import { BASE64_BLOB, HEX_BLOB, INJECTION_PATTERNS, PIPE_SEPARATED, SPACED_LETTERS, } from './injection-patterns.js';
-import { normalizeForDetection } from './normalize.js';
+import { REVERSED_INJECTION_PATTERNS } from './injection-reversed.js';
+import { normalizedView, normalizeForDetection } from './normalize.js';
 const TYPO_TARGETS = [
     'ignore',
     'bypass',
@@ -24,10 +24,66 @@ const TYPO_TARGETS = [
     'developer',
     'disable',
     'measures',
+    'output',
 ];
+/** The shortest target a one-edit misspelling is read as: a shorter word has too many real neighbours. */
+const EDIT_TARGET_MIN = 6;
+/**
+ * Real words one edit from a target (`forgot`, `safely`, `filter`): the dictionary's, and the
+ * inflections it leaves out. They are words, not misspellings.
+ */
+const REAL_WORDS = new Set([
+    'instruction',
+    'filter',
+    'guideline',
+    'restriction',
+    'measure',
+    'ignote',
+    'bypast',
+    'overrode',
+    'overrife',
+    'overripe',
+    'overrise',
+    'overrude',
+    'overside',
+    'overtide',
+    'overwide',
+    'redeal',
+    'reheal',
+    'repeal',
+    'reseal',
+    'reveil',
+    'revel',
+    'delate',
+    'deplete',
+    'safely',
+    'fitters',
+    'precious',
+    'premious',
+    'prepious',
+    'forge',
+    'forged',
+    'forger',
+    'forges',
+    'forgot',
+    'forlet',
+    'forpet',
+    'forset',
+    'gorget',
+    'developed',
+    'measured',
+    'measurer',
+    'outcut',
+    'outhut',
+    'outjut',
+]);
+const TYPO_TARGET_SET = new Set(TYPO_TARGETS);
+/** The longest word a typo can be read from: a target with a letter added. */
+const TYPO_WORD_MAX = Math.max(...TYPO_TARGETS.map((target) => target.length)) + 1;
 /** Pipe evasion only when the first token is a known injection lead-in. */
 const PIPE_HEAD_VERBS = /^(ignore|disregard|forget|bypass|reveal|show|repeat|output|disable|override|new|jailbreak|pretend|act|enter|activate|void|supersede|do)$/i;
-const WORD = /\b[A-Za-z]{4,}\b/g;
+// why: Bounded, so a long run of letters can't overflow the regex engine's stack; no longer word can be a typo.
+const WORD = new RegExp(`\\b[A-Za-z]{4,${TYPO_WORD_MAX}}\\b`, 'g');
 const PRINTABLE_MIN = 0.85;
 const CODE_TAB = 9;
 const CODE_LF = 10;
@@ -64,15 +120,102 @@ function isTypoglycemia(word, target) {
     }
     return sortedLetters(lower.slice(1, -1)) === sortedLetters(target.slice(1, -1));
 }
+/** Whether one insertion, deletion, substitution, or swap of two neighbours turns `word` into `target`. */
+function isOneEdit(word, target) {
+    const wordEnd = word.length - 1;
+    const targetEnd = target.length - 1;
+    if (word[0] !== target[0] && word[wordEnd] !== target[targetEnd]) {
+        return false;
+    }
+    const short = Math.min(word.length, target.length);
+    let head = 0;
+    while (head < short && word[head] === target[head]) {
+        head += 1;
+    }
+    let tail = 0;
+    while (tail < short - head && word[wordEnd - tail] === target[targetEnd - tail]) {
+        tail += 1;
+    }
+    if (word.length !== target.length) {
+        return head + tail === short;
+    }
+    const differing = short - head - tail;
+    return (differing === 1 ||
+        (differing === 2 && word[head] === target[head + 1] && word[head + 1] === target[head]));
+}
+/**
+ * Whether `word` is `target` misspelt by one edit. A real word is not: one of
+ * {@linkcode REAL_WORDS}, or the target with a letter added at its end
+ * (`ignored`, `systems`).
+ */
+function isMisspelling(word, target) {
+    return isOneEdit(word, target) && !REAL_WORDS.has(word) && word.slice(0, -1) !== target;
+}
+/** For a word length, the targets a scramble of that length can be, and the targets a one-edit misspelling of it can be. */
+const TARGETS_BY_LENGTH = new Map();
+for (let length = 4; length <= TYPO_WORD_MAX; length += 1) {
+    TARGETS_BY_LENGTH.set(length, {
+        same: TYPO_TARGETS.filter((target) => target.length === length),
+        near: TYPO_TARGETS.filter((target) => target.length >= EDIT_TARGET_MIN && Math.abs(target.length - length) <= 1),
+    });
+}
+/** The target `word` is read as, or `undefined`: a scramble of one first, then a one-edit misspelling. */
+function targetOf(word) {
+    const targets = TARGETS_BY_LENGTH.get(word.length);
+    if (targets === undefined) {
+        return undefined;
+    }
+    const lower = word.toLowerCase();
+    if (TYPO_TARGET_SET.has(lower)) {
+        return undefined;
+    }
+    return (targets.same.find((target) => isTypoglycemia(lower, target)) ??
+        targets.near.find((target) => isMisspelling(lower, target)));
+}
+function typoFolds(text) {
+    const folds = [];
+    for (const match of text.matchAll(WORD)) {
+        const to = targetOf(match[0]);
+        if (to !== undefined) {
+            folds.push({ start: match.index, end: match.index + match[0].length, to });
+        }
+    }
+    return folds;
+}
+function applyFolds(text, folds) {
+    let out = '';
+    let at = 0;
+    for (const fold of folds) {
+        out += text.slice(at, fold.start) + fold.to;
+        at = fold.end;
+    }
+    return out + text.slice(at);
+}
 function typoNormalize(text) {
-    return text.replace(WORD, (word) => {
-        for (const target of TYPO_TARGETS) {
-            if (isTypoglycemia(word, target)) {
-                return target;
+    return applyFolds(text, typoFolds(text));
+}
+/**
+ * `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.
+ */
+function typoFolded(text) {
+    const folds = typoFolds(text);
+    const at = (index) => {
+        let shift = 0;
+        for (const fold of folds) {
+            const start = fold.start + shift;
+            if (index < start) {
+                break;
+            }
+            if (index < start + fold.to.length) {
+                return fold.start + Math.min(index - start, fold.end - fold.start - 1);
             }
+            shift += fold.to.length - (fold.end - fold.start);
         }
-        return word;
-    });
+        return index - shift;
+    };
+    return { text: applyFolds(text, folds), at };
 }
 function isMostlyPrintable(value) {
     if (!value) {
@@ -202,36 +345,116 @@ function tryLeet(text) {
     const decoded = text.replace(LEET_CHARS, (c) => LEET_MAP[c] ?? c);
     return decoded !== text ? decoded : undefined;
 }
+/** Matches found in a rewrite, each placed on the stretch of the text as written it was read from. */
+function placed(spans, view) {
+    return spans.map((span) => ({
+        ...span,
+        start: view.start(span.start),
+        end: view.end(span.end - 1),
+    }));
+}
+/** The matches in the text typo-folded, as indexes of the folded text, and the way back from it. */
+function typoSpans(text) {
+    const folded = typoFolded(text);
+    return {
+        spans: folded.text === text ? [] : injectionSpansOn(folded.text),
+        view: { text: folded.text, start: folded.at, end: (index) => folded.at(index) + 1 },
+    };
+}
+function unicodeView(text) {
+    const view = normalizedView(text);
+    return {
+        text: view.text,
+        start: (index) => view.start[index] ?? text.length,
+        end: (index) => view.end[index] ?? text.length,
+    };
+}
+/** `decodeUrlRuns(text)`: a decoded character stands for the whole run of escapes it came from. */
+function urlView(text) {
+    const start = [];
+    const end = [];
+    let decoded = '';
+    let last = 0;
+    const keep = (to) => {
+        for (let i = last; i < to; i += 1) {
+            start.push(i);
+            end.push(i + 1);
+        }
+        decoded += text.slice(last, to);
+    };
+    for (const match of text.matchAll(URL_ESCAPES)) {
+        keep(match.index);
+        const run = decodeUrlRuns(match[0]);
+        last = match.index + match[0].length;
+        for (let i = 0; i < run.length; i += 1) {
+            start.push(match.index);
+            end.push(last);
+        }
+        decoded += run;
+    }
+    keep(text.length);
+    return {
+        text: decoded,
+        start: (index) => start[index] ?? text.length,
+        end: (index) => end[index] ?? text.length,
+    };
+}
+/** A rewrite of a rewrite: `inner` is a view of `outer.text`. */
+function through(inner, outer) {
+    return {
+        text: inner.text,
+        start: (index) => outer.start(inner.start(index)),
+        end: (index) => outer.end(inner.end(index) - 1),
+    };
+}
+function urlSpans(text) {
+    const decoded = tryUrlDecode(text);
+    const spans = decoded === undefined ? [] : injectionSpansOn(decoded);
+    return spans.length > 0 ? placed(spans, urlView(text)) : [];
+}
 /**
- * Text written backwards reads as an injection: each pattern reversed
- * (`REVERSED_INJECTION_PATTERNS`), matched on the text as written.
+ * The matches in the text decoded: ROT13 and leet keep each character in its
+ * place, a URL-decoded match is placed through {@linkcode urlView}, and text
+ * written backwards is matched as written, by each pattern reversed
+ * (`REVERSED_INJECTION_PATTERNS`).
  */
-function reversedHits(text) {
-    return spansFromPatterns(text, REVERSED_INJECTION_PATTERNS, 'injection').length > 0;
-}
 function decodedTextSpans(text) {
-    const attempts = [tryRot13(text), tryUrlDecode(text), tryLeet(text)];
-    const decodedHit = attempts.some((decoded) => decoded && decoded !== text && injectionSpansOn(decoded).length > 0);
-    return decodedHit || reversedHits(text)
-        ? [{ start: 0, end: text.length, kind: 'injection' }]
-        : [];
+    const leet = tryLeet(text);
+    return [
+        ...injectionSpansOn(tryRot13(text)),
+        ...(leet === undefined ? [] : injectionSpansOn(leet)),
+        ...urlSpans(text),
+        ...spansFromPatterns(text, REVERSED_INJECTION_PATTERNS, 'injection'),
+    ];
 }
-function injectionSpans(text) {
-    const direct = injectionSpansOn(text);
-    const shadow = typoNormalize(text);
-    let typo = [];
-    if (shadow !== text) {
-        typo = injectionSpansOn(shadow);
-    }
+/** The matches in the text normalized, and in that typo-folded. The way back is built only when one of them matches. */
+function unicodeSpans(text) {
     const normalized = normalizeForDetection(text);
-    let unicodeHits = [];
-    if (normalized !== text) {
-        const normalizedTypo = typoNormalize(normalized);
-        if (injectionSpansOn(normalized).length > 0 ||
-            (normalizedTypo !== normalized && injectionSpansOn(normalizedTypo).length > 0)) {
-            unicodeHits = [{ start: 0, end: text.length, kind: 'injection' }];
-        }
+    if (normalized === text) {
+        return [];
+    }
+    const spans = injectionSpansOn(normalized);
+    const typo = typoSpans(normalized);
+    if (spans.length === 0 && typo.spans.length === 0) {
+        return [];
     }
-    return [...direct, ...typo, ...unicodeHits, ...blobSpans(text), ...decodedTextSpans(text)];
+    const view = unicodeView(text);
+    return [...placed(spans, view), ...placed(typo.spans, through(typo.view, view))];
+}
+/**
+ * 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.
+ */
+function injectionSpans(text) {
+    const typo = typoSpans(text);
+    return mergeSpans([
+        ...injectionSpansOn(text),
+        ...placed(typo.spans, typo.view),
+        ...unicodeSpans(text),
+        ...blobSpans(text),
+        ...decodedTextSpans(text),
+    ]);
 }
-export { decodeUrlRuns, INJECTION_BLOBS, injectionSpans, TYPO_TARGETS, tryLeet, tryRot13, typoNormalize, };
+export { decodeUrlRuns, INJECTION_BLOBS, injectionSpans, LEET_MAP, TYPO_TARGETS, tryLeet, tryRot13, typoFolded, typoNormalize, };

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

@@ -0,0 +1,40 @@
+/** Values that fill a label template's `{param}` placeholders. */
+export type LabelParams = Record<string, string | number>;
+/** Keys are stable API. */
+export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "input.too_long", "attachments.limits_unconfigured", "quota.exhausted", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "compaction.request", "compaction.tool_call", "compaction.tool_result", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.injection", "detect.hint.tool_instructions", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
+/** One of {@linkcode LABEL_KEYS}. */
+export type LabelKey = (typeof LABEL_KEYS)[number];
+/**
+ * The keys a browser client words or writes: what the user reads (errors,
+ * attachment and voice problems, session states) and the tool lines the client
+ * puts into history. Only these overrides travel to the browser; the rest
+ * (repair prompts, canary, taint, egress) stay on the host.
+ */
+export declare const CLIENT_LABEL_KEYS: readonly ["attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "input.too_long", "attachments.limits_unconfigured", "detect.blocked", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "session.abandon_gated", "session.tool_denied", "session.sign_in", "session.gate_expired", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "tool.awaiting_user", "tool.completed_hidden", "tool.execution_uncertain", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "composer.model", "composer.effort"];
+/** One of {@linkcode CLIENT_LABEL_KEYS}. */
+export type ClientLabelKey = (typeof CLIENT_LABEL_KEYS)[number];
+/** Host-supplied replacement templates, `{param}` placeholders included. */
+export type LabelOverrides = Partial<Record<LabelKey, string>>;
+/**
+ * What each key is: when the kernel uses it, who reads it, and the placeholders it takes. For the
+ * builders who replace the wording; the field catalog reads it for `labels.<key>`.
+ */
+export declare const LABEL_NOTES: Record<LabelKey, string>;
+export declare function labelPlaceholders(key: LabelKey): readonly string[];
+/** `owner` names where the overrides came from in the error. */
+export declare function validateLabelOverrides(entries: LabelOverrides, owner: string): void;
+/** Process-wide; a profile's own `labels` wins over these. */
+export declare function overrideLabels(entries: LabelOverrides): void;
+/** Remove every label override. */
+export declare function resetLabels(): void;
+/** The wording for a key, with a profile's override applied and the params filled in. */
+export declare function labelText(key: LabelKey, params?: LabelParams, profileLabels?: LabelOverrides): string;
+/** Overrides only, resolved on the host; keys without one fall back to the defaults the client ships with. */
+export declare function clientLabels(profileLabels?: LabelOverrides): LabelOverrides;
+/** Ignores overrides. */
+export declare function labelDefault(key: LabelKey, params?: LabelParams): string;
+/** Every label with its default text, named by the profile path that overrides it: `labels.<key>`. */
+export declare function labelCatalogRows(): readonly {
+    name: string;
+    text: string;
+}[];