@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/guardrails/detectors.js

@@ -0,0 +1,503 @@
+// invariant: Imports the boundary vocabulary, the sensitive groups, and the host's patterns only:
+// nothing from `src/guardrails/types.ts` or `src/kernel/`, so `types.ts` can read these types
+// without a cycle.
+/** labels-exempt-file: authoring labels, descriptions and profile-registration diagnostics for detectors — not runtime user or model copy (P2) */
+import { BOUNDARIES, INBOUND_BOUNDARIES, OUTBOUND_BOUNDARIES, recordOf, TOOL_BOUNDARIES, TOOL_KINDS, toolBoundary, } from './boundaries.js';
+import { matchersOf, patternsProblem, } from './host-patterns.js';
+import { SENSITIVE_GROUPS } from './sensitive-groups.js';
+/**
+ * What the kernel finds in text: the four families of sensitive data, prompt-injection phrasing,
+ * a tool's text that instructs the agent, and what is the profile's own on its way out (the canary token, the system instruction, the
+ * kernel's markers, an image or link to an address the model was not given, and the names of its
+ * tools).
+ */
+const DETECTORS = [
+    ...SENSITIVE_GROUPS,
+    'injection',
+    'tool_instructions',
+    'canary_leak',
+    'prompt_leak',
+    'marker_leak',
+    'ungiven_images',
+    'ungiven_links',
+    'tool_leak',
+];
+/**
+ * What the kernel does with a match, the same at every boundary:
+ * - `ignore` — the text is not checked.
+ * - `flag` — the match is recorded in the trace; nothing changes.
+ * - `redact` — the match is replaced with a placeholder; the rest is kept.
+ * - `block` — the whole message, reply, or tool call is stopped.
+ */
+const DETECT_ACTIONS = ['ignore', 'flag', 'redact', 'block'];
+/** How much of a streaming reply stays held for a host's `find`, in characters. */
+const HOST_FIND_HOLD = 256;
+/** The same in a Live reply, which is spoken as it is written. */
+const HOST_FIND_HOLD_LIVE = 96;
+/** The groups an editor lists detectors under, in order. */
+const DETECTOR_GROUPS = ['data', 'manipulation', 'setup', 'addresses'];
+/** The label of every group, and what its detectors find. */
+const DETECTOR_GROUP_META = {
+    data: { label: 'Sensitive data', doc: 'Personal and secret data.' },
+    manipulation: { label: 'Manipulation', doc: 'Text that steers the agent.' },
+    setup: {
+        label: 'Agent setup',
+        doc: "The profile's own text in model output.",
+    },
+    addresses: {
+        label: 'Unknown addresses',
+        doc: 'Addresses the model was not given.',
+    },
+};
+const TOOL_ARGUMENT_BOUNDARIES = TOOL_KINDS.map((kind) => toolBoundary('tool_arguments', kind));
+const TOOL_SHOWN_BOUNDARIES = TOOL_KINDS.map((kind) => toolBoundary('tool_shown', kind));
+/**
+ * Text on its way to the model is redacted, a tool call takes `toTool`, and what the model writes
+ * or a tool shows the person is not read.
+ */
+function everywhere(toTool) {
+    return {
+        ...recordOf(INBOUND_BOUNDARIES, () => 'redact'),
+        ...recordOf(TOOL_BOUNDARIES, () => 'redact'),
+        ...recordOf(TOOL_ARGUMENT_BOUNDARIES, () => toTool),
+        ...recordOf(TOOL_SHOWN_BOUNDARIES, () => 'ignore'),
+        ...recordOf(OUTBOUND_BOUNDARIES, () => 'ignore'),
+    };
+}
+/** What the model writes: a tool call takes `toTool`, what it says takes `said`, a thought `thought`. */
+function leaving(toTool, said, thought) {
+    return {
+        ...recordOf(TOOL_ARGUMENT_BOUNDARIES, () => toTool),
+        reply: said,
+        reply_structured: said,
+        live_reply: said,
+        thought,
+    };
+}
+/** What a tool returns, its output, and its error text: `remote` from a tool the host did not write, `local` from a function. */
+function returned(remote, local) {
+    const crossings = ['tool_output', 'tool_failure'];
+    return Object.fromEntries(crossings.flatMap((crossing) => TOOL_KINDS.map((kind) => [
+        toolBoundary(crossing, kind),
+        kind === 'function' ? local : remote,
+    ])));
+}
+/** What the model says or thinks: a reply of any kind takes `said`, a thought `thought`. */
+function shown(said, thought) {
+    return { reply: said, reply_structured: said, live_reply: said, thought };
+}
+/** Every detector's declaration. The editor, validation, and the catalog are built from it. */
+const DETECTOR_META = {
+    ids: {
+        label: 'IDs',
+        doc: 'US SSN, ITIN, and EIN numbers.',
+        group: 'data',
+        defaults: everywhere('flag'),
+        patterns: true,
+    },
+    financial: {
+        label: 'Financial',
+        doc: 'IBANs and card numbers.',
+        group: 'data',
+        defaults: everywhere('flag'),
+        patterns: true,
+    },
+    network: {
+        label: 'Network',
+        doc: 'IPv4 and IPv6 addresses.',
+        group: 'data',
+        defaults: everywhere('flag'),
+        patterns: true,
+    },
+    credentials: {
+        label: 'Credentials',
+        doc: 'API keys, tokens, passwords, and private keys.',
+        group: 'data',
+        // why: A key the model was handed (in its instructions or a tool's output) is a key the person
+        // reading the reply should not get, nor one a tool returned; the rest still shows. A thought and
+        // a Live reply stay unread, so neither holds its stream nor turns transcription on for every turn.
+        defaults: {
+            ...everywhere('flag'),
+            ...recordOf(TOOL_SHOWN_BOUNDARIES, () => 'redact'),
+            reply: 'redact',
+            reply_structured: 'redact',
+        },
+        patterns: true,
+    },
+    injection: {
+        label: 'Injection',
+        doc: 'Prompt-injection phrasing, plain or disguised.',
+        group: 'manipulation',
+        defaults: everywhere('ignore'),
+        patterns: true,
+    },
+    tool_instructions: {
+        label: 'Tool instructions',
+        short: 'From tools',
+        doc: 'Tool output that instructs the agent. A match raises taint.',
+        group: 'manipulation',
+        defaults: returned('flag', 'ignore'),
+        patterns: true,
+    },
+    canary_leak: {
+        label: 'Canary leak',
+        doc: 'The canary token, plain or encoded. Planted only above Ignore.',
+        group: 'setup',
+        defaults: leaving('block', 'block', 'redact'),
+    },
+    prompt_leak: {
+        label: 'Prompt leak',
+        doc: 'Private system-instruction text, plain or disguised.',
+        group: 'setup',
+        defaults: leaving('flag', 'block', 'redact'),
+    },
+    marker_leak: {
+        label: 'Marker leak',
+        doc: "The kernel's data markers and canary note.",
+        group: 'setup',
+        defaults: shown('block', 'redact'),
+    },
+    ungiven_images: {
+        label: 'Ungiven images',
+        short: 'Images',
+        doc: 'An image at an address not given. Loads with no click.',
+        group: 'addresses',
+        defaults: shown('block', 'redact'),
+        allow: 'urls',
+    },
+    ungiven_links: {
+        label: 'Ungiven links',
+        short: 'Links',
+        doc: 'A link to an address not given. Replies cite known pages, so it is not checked by default.',
+        group: 'addresses',
+        defaults: shown('ignore', 'ignore'),
+        allow: 'urls',
+    },
+    tool_leak: {
+        label: 'Tool leak',
+        doc: "The profile's tool and parameter names.",
+        group: 'setup',
+        defaults: shown('flag', 'flag'),
+        allow: 'names',
+        patterns: true,
+    },
+};
+/** The detectors that read with patterns: their setting takes `theorem` and `patterns`. */
+const PATTERN_DETECTORS = DETECTORS.filter((detector) => DETECTOR_META[detector].patterns);
+/** The boundaries each detector applies at, in the kernel's order. */
+const DETECTOR_BOUNDARIES = recordOf(DETECTORS, (detector) => BOUNDARIES.filter((boundary) => boundary in DETECTOR_META[detector].defaults));
+/** The label of every action, and what it does. */
+const DETECT_ACTION_META = {
+    ignore: { label: 'Ignore', doc: 'Does not check the text.' },
+    flag: {
+        label: 'Flag',
+        doc: 'Records the match in the trace. Changes nothing.',
+    },
+    redact: {
+        label: 'Redact',
+        doc: 'Replaces the match with a placeholder. Keeps the rest.',
+    },
+    block: {
+        label: 'Block',
+        doc: 'Stops the whole message, reply, or tool call. None of it gets through.',
+    },
+};
+/** `action` wherever `detector` applies. Anywhere else it is `ignore`: the detector is not run there. */
+function wherever(detector, action) {
+    const applies = DETECTOR_META[detector].defaults;
+    return recordOf(BOUNDARIES, (boundary) => (boundary in applies ? action : 'ignore'));
+}
+/** What a profile that sets no `guardrails.detect` gets. */
+const DETECT_DEFAULTS = recordOf(DETECTORS, (detector) => ({
+    ...wherever(detector, 'ignore'),
+    ...DETECTOR_META[detector].defaults,
+}));
+/** Whether `detector` is above `ignore` at any of `boundaries`. */
+function detects(detect, detector, boundaries = BOUNDARIES) {
+    return boundaries.some((boundary) => detect[detector][boundary] !== 'ignore');
+}
+function isAction(value) {
+    return DETECT_ACTIONS.includes(value);
+}
+function resolveRule(detector, rule) {
+    const base = DETECT_DEFAULTS[detector];
+    if (rule === undefined)
+        return base;
+    if (isAction(rule))
+        return wherever(detector, rule);
+    // why: With neither Theorem's patterns nor the host's, the detector has nothing to find.
+    const { action, at, theorem = true, patterns = [] } = rule;
+    if (!theorem && patterns.length === 0)
+        return wherever(detector, 'ignore');
+    return { ...(action === undefined ? base : wherever(detector, action)), ...at };
+}
+/** Whose patterns `rule` reads with, when it says: `undefined` is Theorem's only. */
+function sourceOf(rule) {
+    if (rule === undefined || isAction(rule))
+        return undefined;
+    const { theorem = true, patterns = [], compiled } = rule;
+    if (theorem && patterns.length === 0)
+        return undefined;
+    return {
+        theorem,
+        matchers: matchersOf(patterns),
+        ...(compiled && patterns.length > 0 ? { compiled } : {}),
+    };
+}
+/** `spec` with everything it leaves out at its default. */
+function resolveDetect(spec) {
+    if (spec === undefined)
+        return DETECT_DEFAULTS;
+    if (isAction(spec))
+        return recordOf(DETECTORS, (detector) => wherever(detector, spec));
+    const matrix = recordOf(DETECTORS, (detector) => resolveRule(detector, spec[detector]));
+    const sources = {};
+    const hints = {};
+    for (const detector of PATTERN_DETECTORS) {
+        const rule = spec[detector];
+        const source = sourceOf(rule);
+        if (source)
+            sources[detector] = source;
+        if (rule !== undefined && !isAction(rule) && rule.hint)
+            hints[detector] = rule.hint;
+    }
+    const leak = spec.tool_leak;
+    const innocent = isAction(leak) ? undefined : leak?.allow?.names;
+    const host = Object.entries(spec).flatMap(([id, rule]) => isHostId(id) ? [hostDetector(id, rule)] : []);
+    return {
+        ...matrix,
+        ...(Object.keys(sources).length > 0 ? { sources } : {}),
+        ...(Object.keys(hints).length > 0 ? { hints } : {}),
+        ...(innocent?.length ? { innocent } : {}),
+        ...(host.length > 0 ? { host } : {}),
+    };
+}
+function isHostId(key) {
+    return key.includes('.');
+}
+function hostDetector(id, config) {
+    const { label, action = 'ignore', at, patterns = [], compiled, find, hint } = config;
+    return {
+        id,
+        label,
+        actions: recordOf(BOUNDARIES, (boundary) => at?.[boundary] ?? action),
+        matchers: matchersOf(patterns),
+        ...(compiled && patterns.length > 0 ? { compiled } : {}),
+        ...(find ? { find } : {}),
+        ...(hint ? { hint } : {}),
+    };
+}
+/** The action of `key`, a detector of Theorem's or the host's, at `boundary`. One unknown is `ignore`. */
+function actionAt(detect, key, boundary) {
+    if (isDetector(key))
+        return detect[key][boundary];
+    return detect.host?.find(({ id }) => id === key)?.actions[boundary] ?? 'ignore';
+}
+const NO_ALLOW = { ungiven_images: {}, ungiven_links: {} };
+function allowOf(rule) {
+    return (isAction(rule) ? undefined : rule?.allow) ?? {};
+}
+/** The `allow` of each detector that takes one. */
+function resolveAllow(spec) {
+    if (spec === undefined || isAction(spec))
+        return NO_ALLOW;
+    const images = allowOf(spec.ungiven_images);
+    const links = allowOf(spec.ungiven_links);
+    // why: A host images load from already takes data with no click, so a link there opens nothing new.
+    const hosts = [...new Set([...(links.hosts ?? []), ...(images.hosts ?? [])])];
+    return {
+        ungiven_images: images,
+        ungiven_links: hosts.length > 0 ? { ...links, hosts } : links,
+    };
+}
+const ACTION_LIST = DETECT_ACTIONS.join(', ');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `detector` left out is one of the host's own, which applies at every boundary. */
+function atProblem(path, at, boundaries, detector) {
+    if (at === undefined)
+        return undefined;
+    if (!isRecord(at))
+        return `${path} must be an object of boundaries`;
+    const known = new Set(boundaries);
+    const applies = detector ? DETECTOR_BOUNDARIES[detector] : BOUNDARIES;
+    for (const [boundary, action] of Object.entries(at)) {
+        if (!known.has(boundary)) {
+            return `${path}.${boundary} is not a boundary this profile has (${boundaries.join(', ')})`;
+        }
+        if (!applies.includes(boundary)) {
+            return `${path}.${boundary} is not a boundary ${detector} applies at (${applies.join(', ')})`;
+        }
+        if (!isAction(action))
+            return `${path}.${boundary} must be one of ${ACTION_LIST}`;
+    }
+    return undefined;
+}
+const CONFIG_KEYS = [
+    'action',
+    'at',
+    'theorem',
+    'patterns',
+    'compiled',
+    'hint',
+    'allow',
+];
+const SOURCE_KEYS = [
+    'theorem',
+    'patterns',
+    'compiled',
+    'hint',
+];
+const ALLOW_KEYS = ['hosts', 'fromTools'];
+/** The `allow` of `tool_leak`: names, each a string. */
+function namesProblem(path, allow) {
+    const unknown = Object.keys(allow).find((key) => key !== 'names');
+    if (unknown !== undefined)
+        return `${path}.${unknown} is not a setting of allow (names)`;
+    const { names } = allow;
+    if (names === undefined)
+        return undefined;
+    if (!Array.isArray(names))
+        return `${path}.names must be a list`;
+    const bad = names.find((name) => typeof name !== 'string' || !name.trim());
+    return bad === undefined
+        ? undefined
+        : `${path}.names lists ${JSON.stringify(bad)}, which is not a name`;
+}
+/** A hostname is all an allowed host is: a scheme, port, or path would never match one. */
+function allowProblem(path, allow, detector) {
+    if (allow === undefined)
+        return undefined;
+    const lists = DETECTOR_META[detector].allow;
+    if (!lists) {
+        return `${path} is a setting of ungiven_images, ungiven_links, and tool_leak only`;
+    }
+    if (!isRecord(allow))
+        return `${path} must be an object`;
+    if (lists === 'names')
+        return namesProblem(path, allow);
+    const unknown = Object.keys(allow).find((key) => !ALLOW_KEYS.includes(key));
+    if (unknown !== undefined) {
+        return `${path}.${unknown} is not a setting of allow (${ALLOW_KEYS.join(', ')})`;
+    }
+    const { hosts, fromTools } = allow;
+    if (fromTools !== undefined && typeof fromTools !== 'boolean') {
+        return `${path}.fromTools must be a boolean`;
+    }
+    if (hosts === undefined)
+        return undefined;
+    if (!Array.isArray(hosts))
+        return `${path}.hosts must be a list`;
+    const bad = hosts.find((host) => typeof host !== 'string' || !/^[a-z0-9.-]+$/i.test(host) || host.startsWith('.'));
+    return bad === undefined
+        ? undefined
+        : `${path}.hosts lists ${JSON.stringify(bad)}, which is not a hostname`;
+}
+function ruleProblem(path, rule, detector, boundaries) {
+    if (isAction(rule))
+        return undefined;
+    if (!isRecord(rule))
+        return `${path} must be one of ${ACTION_LIST}, or an object`;
+    const unknown = Object.keys(rule).find((key) => !CONFIG_KEYS.includes(key));
+    if (unknown !== undefined) {
+        return `${path}.${unknown} is not a setting of a detector (${CONFIG_KEYS.join(', ')})`;
+    }
+    if (rule.action !== undefined && !isAction(rule.action)) {
+        return `${path}.action must be one of ${ACTION_LIST}`;
+    }
+    return (atProblem(`${path}.at`, rule.at, boundaries, detector) ??
+        sourceProblem(path, rule, detector) ??
+        allowProblem(`${path}.allow`, rule.allow, detector));
+}
+/** `theorem`, `patterns`, and `compiled`: settings of a detector that reads with patterns. */
+function sourceProblem(path, rule, detector) {
+    if (!DETECTOR_META[detector].patterns) {
+        const set = SOURCE_KEYS.find((key) => rule[key] !== undefined);
+        return set === undefined
+            ? undefined
+            : `${path}.${set} is a setting of the detectors that read with patterns only (${PATTERN_DETECTORS.join(', ')})`;
+    }
+    if (rule.theorem !== undefined && typeof rule.theorem !== 'boolean') {
+        return `${path}.theorem must be a boolean`;
+    }
+    if (rule.hint !== undefined && !(Array.isArray(rule.patterns) && rule.patterns.length > 0)) {
+        return `${path}.hint goes beside patterns of your own: without them the labels' detect.hint.${detector} is the hint`;
+    }
+    return (hintProblem(`${path}.hint`, rule.hint) ?? patternsProblem(path, rule.patterns, rule.compiled));
+}
+/** A hint may be this long, in characters: it is a line in the retry, once for each detector that matched. */
+const MAX_HINT = 300;
+function hintProblem(path, hint) {
+    if (hint === undefined)
+        return undefined;
+    if (typeof hint !== 'string' || !hint.trim())
+        return `${path} must be a non-empty string`;
+    if (hint.includes('\n'))
+        return `${path} must be one line`;
+    return hint.length > MAX_HINT ? `${path} must be ${MAX_HINT} characters or fewer` : undefined;
+}
+function isDetector(value) {
+    return DETECTORS.includes(value);
+}
+/**
+ * What is wrong with a `guardrails.detect` value, or `undefined` when it is valid. A misspelt
+ * detector or boundary would leave the one it meant at its default, silently, so both are errors.
+ * `boundaries` are the ones the profile has; a rule naming another is an error.
+ */
+function detectProblem(path, spec, boundaries = BOUNDARIES) {
+    if (spec === undefined || isAction(spec))
+        return undefined;
+    if (!isRecord(spec))
+        return `${path} must be one of ${ACTION_LIST}, or an object of detectors`;
+    for (const [detector, rule] of Object.entries(spec)) {
+        const at = `${path}.${detector}`;
+        if (!(isDetector(detector) || isHostId(detector))) {
+            return `${at} is not a detector (${DETECTORS.join(', ')}), nor one of your own: those have a dot in their key, as in acme.record`;
+        }
+        const problem = isDetector(detector)
+            ? ruleProblem(at, rule, detector, boundaries)
+            : hostProblem(at, detector, rule, boundaries);
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+}
+const HOST_KEYS = [
+    'label',
+    'action',
+    'at',
+    'patterns',
+    'compiled',
+    'find',
+    'hint',
+];
+/** What is wrong with a detector of the host's own. It has no default, so it says what it reads with and where. */
+function hostProblem(path, id, rule, boundaries) {
+    if (!/^[a-z][a-z0-9_]*(\.[a-z0-9_]+)+$/.test(id)) {
+        return `${path}: a detector of your own is keyed namespace.name in lower case, digits and _, as in acme.record`;
+    }
+    if (!isRecord(rule))
+        return `${path} must be an object: a label, an action or at, and patterns or find`;
+    const unknown = Object.keys(rule).find((key) => !HOST_KEYS.includes(key));
+    if (unknown !== undefined) {
+        return `${path}.${unknown} is not a setting of a detector of your own (${HOST_KEYS.join(', ')})`;
+    }
+    const { label, action, at, patterns, compiled, find, hint } = rule;
+    if (typeof label !== 'string' || !label.trim())
+        return `${path}.label must be a non-empty string`;
+    if (action !== undefined && !isAction(action))
+        return `${path}.action must be one of ${ACTION_LIST}`;
+    if (action === undefined && at === undefined) {
+        return `${path} needs an action or at: a detector of your own has no default`;
+    }
+    if (find !== undefined && typeof find !== 'function')
+        return `${path}.find must be a function`;
+    if (patterns === undefined && find === undefined) {
+        return `${path} needs patterns or find: it has nothing to read with`;
+    }
+    return (atProblem(`${path}.at`, at, boundaries) ??
+        hintProblem(`${path}.hint`, hint) ??
+        patternsProblem(path, patterns, compiled));
+}
+export { actionAt, DETECT_ACTION_META, DETECT_ACTIONS, DETECT_DEFAULTS, DETECTOR_BOUNDARIES, DETECTOR_GROUP_META, DETECTOR_GROUPS, DETECTOR_META, DETECTORS, detectProblem, detects, HOST_FIND_HOLD, HOST_FIND_HOLD_LIVE, hintProblem, isDetector, NO_ALLOW, PATTERN_DETECTORS, resolveAllow, resolveDetect, };

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

@@ -4,11 +4,9 @@
  *
  * @module
  */
-import type { EgressAutomatonData } from './egress-rules.js';
-/** Each injection pattern reversed: it matches where the pattern matches the text written backwards. */
-declare const REVERSED_INJECTION_PATTERNS: RegExp[];
+import type { AutomatonData } from './host-patterns.js';
 /** Every egress pattern, loosened to a superset automaton, in `EGRESS_PATTERNS` order. */
-declare const FORWARD_AUTOMATON: EgressAutomatonData;
+declare const FORWARD_AUTOMATON: AutomatonData;
 /** Each reversed injection pattern, loosened the same way. */
-declare const REVERSED_AUTOMATON: EgressAutomatonData;
-export { FORWARD_AUTOMATON, REVERSED_AUTOMATON, REVERSED_INJECTION_PATTERNS };
+declare const REVERSED_AUTOMATON: AutomatonData;
+export { FORWARD_AUTOMATON, REVERSED_AUTOMATON };