@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/guardrails/tool-directives.js

@@ -1,5 +1,6 @@
-import { normalizeForDetection } from './normalize.js';
-import { DIRECTIVE_RULES } from './rules.js';
+import { typoFolded } from './injection.js';
+import { overrideFrame } from './injection-patterns.js';
+import { normalizedView, normalizeForDetection } from './normalize.js';
 /**
  * Imperatives aimed at an agent rather than a reader.
  *
@@ -23,8 +24,45 @@ const IMPERATIVES = [
  * articles say "to remove a user", status reports say "the user has approved".
  * Measured on a benign sample, directive signals alone produced false positives
  * on most of it. Pairing a signal with a destination removed all of them.
+ *
+ * The pairing is close. A web page always carries an address somewhere, and a
+ * shop's page says "Remove This Item" and "if you need to exchange it, send us
+ * an email at …": of 20 real search results, a destination anywhere in the
+ * result flagged 3. An order or a claim counts when the destination is in what
+ * it orders, up to the next comma; a tool's name when one is in its sentence.
  */
 const EXFIL_TARGET = /\b[\w.+-]{1,64}@[\w-]{1,63}(?:\.[\w-]{1,63}){1,4}\b|\bhttps?:\/\/\S{4,120}/i;
+const EXFIL_TARGETS = new RegExp(EXFIL_TARGET.source, 'gi');
+/** How far from a signal its sentence is read, where the text has no sentence ends. */
+const SENTENCE_REACH = 240;
+/** Whether a sentence of `text` ends at `at`: a line break, or `.`, `!`, or `?` before a space. */
+function endsSentence(text, at) {
+    const ch = text[at];
+    if (ch === '\n')
+        return true;
+    return (ch === '.' || ch === '!' || ch === '?') && /\s/.test(text[at + 1] ?? ' ');
+}
+/** Whether a clause of `text` ends at `at`: where a sentence does, or at `,` or `;` before a space. */
+function endsClause(text, at) {
+    const ch = text[at];
+    return endsSentence(text, at) || ((ch === ',' || ch === ';') && /\s/.test(text[at + 1] ?? ' '));
+}
+/** Where the stretch of `text` from `end` stops: at the first place `ends` holds, at most `SENTENCE_REACH` on. */
+function reachFrom(text, end, ends) {
+    let to = end;
+    const ceiling = Math.min(text.length, end + SENTENCE_REACH);
+    while (to < ceiling && !ends(text, to))
+        to += 1;
+    return to;
+}
+/** Where the sentence of `text` holding `start` begins, at most `SENTENCE_REACH` back. */
+function sentenceStart(text, start) {
+    let from = start;
+    const floor = Math.max(0, start - SENTENCE_REACH);
+    while (from > floor && !endsSentence(text, from - 1))
+        from -= 1;
+    return from;
+}
 /** Claims of permission or provenance the content cannot actually hold. */
 const AUTHORITY = [
     /\b(?:the\s+)?user\s+has\s+(?:already\s+)?(?:approved|authorised|authorized|confirmed|requested)\b/gi,
@@ -32,78 +70,126 @@ const AUTHORITY = [
     /\bon\s+behalf\s+of\s+the\s+(?:user|operator|admin)\b/gi,
     /\bthis\s+(?:is|was)\s+(?:pre-?)?(?:approved|authorised|authorized)\b/gi,
 ];
-function matches(patterns, text) {
-    return patterns.some((pattern) => {
-        pattern.lastIndex = 0;
-        return pattern.test(text);
-    });
+/**
+ * An order to set instructions aside. Data has no reason to address the
+ * agent's instructions, so here the order counts when negated and with more
+ * words between its verb and its object than `injection-patterns.ts` allows.
+ */
+const OVERRIDE = [new RegExp(overrideFrame(5), 'gi')];
+/** Every destination in `text` between `from` and `to`. */
+function targetsIn(text, from, to) {
+    return [...text.slice(from, to).matchAll(EXFIL_TARGETS)].map((match) => [
+        from + match.index,
+        from + match.index + match[0].length,
+    ]);
+}
+/** Each match of `patterns` in `text` that names a destination before its clause ends, and the destinations it names. */
+function directsOut(patterns, text) {
+    return patterns.flatMap((pattern) => [...text.matchAll(pattern)].flatMap((match) => {
+        const end = match.index + match[0].length;
+        const targets = targetsIn(text, match.index, reachFrom(text, end, endsClause));
+        return targets.length > 0 ? [[match.index, end], ...targets] : [];
+    }));
+}
+/** Each order in `text` to set instructions aside, read with its misspellings put right. */
+function overrides(text) {
+    const folded = typoFolded(text);
+    return OVERRIDE.flatMap((pattern) => [...folded.text.matchAll(pattern)].map((match) => [folded.at(match.index), folded.at(match.index + match[0].length - 1) + 1]));
 }
 function isToolNameBoundary(ch) {
     return ch === undefined || !/[a-z0-9_-]/i.test(ch);
 }
-/** Word-boundary match for a tool name without compiling registry input as a pattern. */
-function mentionsTool(text, tool) {
+/**
+ * Where `text` names `tool`, at word boundaries, in a sentence with a
+ * destination: the name, and the destinations of its sentence. A name inside a
+ * destination (`https://shop.example/search`) is part of the address. Registry
+ * input is not compiled as a pattern.
+ */
+function directsToTool(text, tool) {
     if (tool.length < 3) {
-        return false;
+        return [];
     }
     const haystack = text.toLowerCase();
     const needle = tool.toLowerCase();
+    const found = [];
     let at = haystack.indexOf(needle);
     while (at >= 0) {
-        const before = haystack[at - 1];
-        const after = haystack[at + needle.length];
-        if (isToolNameBoundary(before) && isToolNameBoundary(after)) {
-            return true;
+        const end = at + needle.length;
+        if (isToolNameBoundary(haystack[at - 1]) && isToolNameBoundary(haystack[end])) {
+            const targets = targetsIn(text, sentenceStart(text, at), reachFrom(text, end, endsSentence));
+            const isInTarget = targets.some(([start, stop]) => start <= at && end <= stop);
+            if (targets.length > 0 && !isInTarget) {
+                found.push([at, end], ...targets);
+            }
         }
-        at = haystack.indexOf(needle, at + needle.length);
+        at = haystack.indexOf(needle, end);
+    }
+    return found;
+}
+/**
+ * What of a tool's text reads as an instruction to the agent: an order to set its instructions
+ * aside, the name of a tool it can call, an order, or a claim of authority. The last three count
+ * only beside a destination.
+ */
+const DIRECTIVE_SIGNALS = ['override', 'tool_name', 'order', 'authority'];
+/** One range for each run of overlapping `ranges`, in order. */
+function mergedRanges(ranges) {
+    const runs = [];
+    for (const [start, end] of [...ranges].sort((a, b) => a[0] - b[0])) {
+        const last = runs.at(-1);
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            runs.push([start, end]);
     }
-    return false;
+    return runs;
+}
+/** One directive for each run of overlapping `ranges`. */
+function directivesOf(signal, ranges) {
+    return mergedRanges(ranges).map(([start, end]) => ({ signal, start, end }));
 }
 /**
  * Real indirect injection rarely names what it attacks, so this looks for content that behaves
- * like an instruction. Hits raise the turn's taint rather than rewriting the text: a page
- * documenting an email API legitimately says "call send_email", and being wrong should cost a
- * refused write, not silently damaged input.
+ * like an instruction: each order, claim of authority, tool name, and destination, where it sits
+ * in `text`. A page documenting an email API legitimately says "call send_email", so the
+ * detector that reads with this (`tool_instructions`) starts at `flag`.
  *
  * `callableTools` is the set the model can invoke this turn. A result naming one is the
  * highest-precision signal: ordinary data has no reason to, and no generic filter can check it
  * without the turn's registry.
+ *
+ * The text is read normalized. Where that changes it, each signal found is placed on the
+ * stretch of `text` it was read from (`normalizedView`).
  */
-function directiveHits(text, callableTools = []) {
-    if (!text || !EXFIL_TARGET.test(text)) {
-        // No destination, no exfiltration. Action-shaped attacks that carry no target
-        // are left to the taint gate, which does not depend on reading the content.
+function directives(text, callableTools = []) {
+    if (!text) {
         return [];
     }
     const normalized = normalizeForDetection(text);
-    const hits = [];
-    // One hit per named tool — several names is a stronger signal than one.
-    for (const _tool of callableTools.filter((tool) => mentionsTool(normalized, tool))) {
-        hits.push({ rule: DIRECTIVE_RULES.toolName, severity: 'high' });
-    }
-    if (matches(IMPERATIVES, normalized)) {
-        hits.push({ rule: DIRECTIVE_RULES.imperative, severity: 'medium' });
-    }
-    if (matches(AUTHORITY, normalized)) {
-        hits.push({ rule: DIRECTIVE_RULES.authority, severity: 'medium' });
+    const found = directivesOf('override', overrides(normalized));
+    // why: No destination, no exfiltration. Action-shaped attacks that carry no target
+    // are left to the taint gate, which does not depend on reading the content.
+    if (EXFIL_TARGET.test(normalized)) {
+        found.push(...directivesOf('tool_name', callableTools.flatMap((tool) => directsToTool(normalized, tool))), ...directivesOf('order', directsOut(IMPERATIVES, normalized)), ...directivesOf('authority', directsOut(AUTHORITY, normalized)));
     }
-    return hits;
-}
-function looksDirective(hits) {
-    return hits.length > 0;
+    if (normalized === text || found.length === 0)
+        return found;
+    const view = normalizedView(text);
+    return found.map(({ signal, start, end }) => ({
+        signal,
+        start: view.start[start] ?? text.length,
+        end: view.end[end - 1] ?? text.length,
+    }));
 }
 /**
- * Naming a tool the model can call is the sharpest signal available, so it alone
- * reaches `high`; so does agreement between two different signal kinds.
+ * How strongly a tool's text reads as instructions, by the `signals` found in it: `high` for an
+ * order to drop instructions, a callable tool's name, or two signals together.
  */
-function advisoryLevel(hits) {
-    if (hits.length === 0) {
+function advisoryLevel(signals) {
+    if (signals.length === 0) {
         return 'none';
     }
-    const kinds = new Set(hits.map((hit) => hit.rule));
-    if (kinds.has(DIRECTIVE_RULES.toolName) || kinds.size > 1) {
-        return 'high';
-    }
-    return 'elevated';
+    const kinds = new Set(signals);
+    return kinds.has('tool_name') || kinds.has('override') || kinds.size > 1 ? 'high' : 'elevated';
 }
-export { advisoryLevel, directiveHits, looksDirective };
+export { advisoryLevel, DIRECTIVE_SIGNALS, directives, mergedRanges };

package/esm/src/guardrails/tool-leak.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What `tool_leak` reads for: the names of the profile's own tools, each as a word of its own,
+ * and the names of their parameters in double quotes, as tool-call JSON writes its keys. A
+ * parameter is often a plain word (`city`, `query`), so outside quotes it is left alone.
+ *
+ * @module
+ */
+import type { RedactSpan } from '../observability/spans.js';
+/** The names of a profile's own tools, and of their parameters. */
+interface OwnTools {
+    names: readonly string[];
+    params: readonly string[];
+}
+/** A literal of a name to find, and the pattern that reads a match of it. */
+interface NamePattern {
+    literal: string;
+    regex: RegExp;
+}
+/** The pattern of each name of `own`. A tool's name starts and ends where a word does. */
+declare function namePatterns(own: OwnTools): NamePattern[];
+/** Every match of a name of `own` in `text`. */
+declare function toolLeakSpans(text: string, own: OwnTools | undefined): RedactSpan[];
+/** `own` without the names in `innocent`, or `undefined` when none is left. */
+declare function ownToolsWithout(own: OwnTools | undefined, innocent?: readonly string[]): OwnTools | undefined;
+export type { NamePattern, OwnTools };
+export { namePatterns, ownToolsWithout, toolLeakSpans };

package/esm/src/guardrails/tool-leak.js

@@ -0,0 +1,45 @@
+/**
+ * What `tool_leak` reads for: the names of the profile's own tools, each as a word of its own,
+ * and the names of their parameters in double quotes, as tool-call JSON writes its keys. A
+ * parameter is often a plain word (`city`, `query`), so outside quotes it is left alone.
+ *
+ * @module
+ */
+const WORD = '[A-Za-z0-9_]';
+function escaped(text) {
+    return text.replace(/[\\^$.*+?()[\]{}|/-]/g, '\\$&');
+}
+/** The pattern of each name of `own`. A tool's name starts and ends where a word does. */
+function namePatterns(own) {
+    const after = `(?!${WORD})`;
+    const names = [...new Set(own.names)].filter(Boolean).map((name) => ({
+        literal: name,
+        regex: new RegExp(`(?<!${WORD})${escaped(name)}${after}`, 'g'),
+    }));
+    const keys = [...new Set(own.params)]
+        .filter(Boolean)
+        .flatMap((param) => [`"${param}"`, `\\"${param}\\"`])
+        .map((literal) => ({ literal, regex: new RegExp(escaped(literal), 'g') }));
+    return [...names, ...keys];
+}
+/** Every match of a name of `own` in `text`. */
+function toolLeakSpans(text, own) {
+    if (!own)
+        return [];
+    return namePatterns(own).flatMap(({ literal, regex }) => text.includes(literal)
+        ? [...text.matchAll(regex)].map(({ index, 0: match }) => ({
+            start: index,
+            end: index + match.length,
+            kind: 'tool',
+        }))
+        : []);
+}
+/** `own` without the names in `innocent`, or `undefined` when none is left. */
+function ownToolsWithout(own, innocent = []) {
+    if (!own)
+        return undefined;
+    const names = own.names.filter((name) => !innocent.includes(name));
+    const params = own.params.filter((name) => !innocent.includes(name));
+    return names.length + params.length > 0 ? { names, params } : undefined;
+}
+export { namePatterns, ownToolsWithout, toolLeakSpans };

package/esm/src/guardrails/tool-result.d.ts

@@ -1,20 +1,26 @@
-import { type LexiconOverrides } from './lexicon.js';
+import type { ToolBoundary } from './boundaries.js';
+import { type DetectScope } from './detect-at.js';
+import { type LabelOverrides } from './labels.js';
 import type { AdvisoryLevel, GuardrailEvent, GuardrailHit, Provenance, ResolvedGuardrailPolicy, ToolOrigin, TurnTaint, Verdict } from './types.js';
+/** The closing tag of the fence a tool result is wrapped in. */
 declare const TOOL_CLOSE = "</tool_data>";
+/** True when the tool's bytes come from outside the host. */
 declare function isRemoteOrigin(origin: ToolOrigin): boolean;
 /**
  * The origin is on the tag rather than in prose so a result cannot claim a
  * friendlier provenance than it has by writing one into its own body.
  */
-declare function wrapToolData(text: string, provenance: Provenance, advisory?: AdvisoryLevel, lexicon?: LexiconOverrides): string;
+declare function wrapToolData(text: string, provenance: Provenance, advisory?: AdvisoryLevel, labels?: LabelOverrides): string;
+/** A tool result after the guard: the text the model sees, any event, and the suspicious hits. */
 export interface GuardedToolText {
-    text: string;
+    /** Absent when a match blocks: the model does not read the text. */
+    text?: string;
     /** Emitted when the guard did anything worth recording. */
     event?: GuardrailEvent;
     /**
-     * Reported, never redacted: legitimate tool output is frequently
-     * instruction-shaped, so rewriting on this signal would corrupt real data.
-     * These raise the turn's taint instead.
+     * What `tool_instructions` found. Legitimate tool output is frequently
+     * instruction-shaped, so the detector starts at `flag`; whatever its action,
+     * these raise the turn's taint.
      */
     suspicious?: GuardrailHit[];
 }
@@ -27,22 +33,45 @@ declare function composeToolText(finding: string, data: unknown): string;
  * Local host tools are still detected — a host tool reading a database returns
  * data the host did not write — but only remote origins are fenced, because
  * fencing a local tool's output would change prompts hosts have already tuned.
+ * `boundary` is absent for text that crosses none: a provider builtin's, or a
+ * failure already read at its own boundary.
  */
-declare function guardToolResult(finding: string, data: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, callableTools?: readonly string[], lexicon?: LexiconOverrides): GuardedToolText;
+declare function guardToolResult(finding: string, data: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined, callableTools?: readonly string[], labels?: LabelOverrides): GuardedToolText;
 /**
  * A remote server authors its own error strings, so an unguarded failure message
  * is the cleanest injection path across this boundary: it reaches the model
  * verbatim and is framed by the kernel as a system report.
  */
-declare function guardToolFailureText(message: string, provenance: Provenance, policy: ResolvedGuardrailPolicy): GuardedToolText;
+declare function guardToolFailureText(message: string, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined): GuardedToolText;
+/** What a call shows the person of one value, after it was read at `tool_shown_<kind>`. */
+export interface ShownToolValue {
+    /** The value to show: every match set to `redact` replaced. Absent when a match blocks it. */
+    value?: unknown;
+    event?: GuardrailEvent;
+}
+/**
+ * A call's output, error, artifacts, and trace reach the person on the turn's events, apart from
+ * what the model read back: the host's server forwards them to the browser as they are. Each is
+ * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
+ * untouched: what the model read is settled at `tool_output_<kind>`.
+ */
+declare function guardShownValue(value: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined): ShownToolValue;
+/** A tool call's arguments after they were read at their boundary. */
+export interface InspectedToolArguments {
+    /** The arguments to call the tool with. Absent when a match blocks: the tool is not called. */
+    args?: unknown;
+    event?: GuardrailEvent;
+}
 /**
  * Arguments are model-authored, so the risk is not instruction smuggling but
  * exfiltration: a credential lifted from context and posted outward as a
- * parameter. Detection reports rather than rewrites — silently altering a tool
- * argument would make the call succeed against something the model did not ask
- * for.
+ * parameter. The whole call is read as it will be sent; `redact` then replaces
+ * the match inside each string it sits in, so the tool is called with the
+ * placeholder. `scope` is what the detectors of what is the profile's own
+ * read of the turn: the canary, and its system instruction.
  */
-declare function inspectToolArguments(args: unknown, policy: ResolvedGuardrailPolicy): Verdict;
+declare function inspectToolArguments(args: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined, scope?: DetectScope): InspectedToolArguments;
+/** The guardrail event for a tool call verdict, or `undefined` when it was allowed. */
 declare function toolCallEvent(verdict: Verdict, provenance: Provenance): GuardrailEvent | undefined;
 /**
  * Only remote origins taint: a local host tool returns bytes the host's own code
@@ -50,12 +79,14 @@ declare function toolCallEvent(verdict: Verdict, provenance: Provenance): Guardr
  * useless in practice.
  */
 declare function recordTaint(taint: TurnTaint | undefined, provenance: Provenance, suspicious?: GuardrailHit[]): TurnTaint;
+/** True when the turn has read content from outside the host. */
 declare function isTainted(taint: TurnTaint | undefined): boolean;
+/** True when something the turn read looked like instructions. */
 declare function isSuspicious(taint: TurnTaint | undefined): boolean;
 /**
  * A `flag` says the call is happening on a tainted turn and is worth recording; a
  * `block` says the profile asked for it to be refused. Reporting happens whether
  * or not enforcement is configured, so the risk is visible before a host opts in.
  */
-declare function checkTaintGate(taint: TurnTaint | undefined, access: string, policy: ResolvedGuardrailPolicy, lexicon?: LexiconOverrides): Verdict;
-export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };
+declare function checkTaintGate(taint: TurnTaint | undefined, access: string, policy: ResolvedGuardrailPolicy, labels?: LabelOverrides): Verdict;
+export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, };