@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/guardrails/thought-guard.js

@@ -0,0 +1,464 @@
+/**
+ * Thought guarding. A host that renders `thought` events shows the user what
+ * they say and loads what they link, as it does a reply: the canary, the
+ * system prompt and the user-data markers leak through a thought, and a URL
+ * the model was not given carries data out. Nothing in a thought stops a turn
+ * (`isGuardedOutput`); each leak is omitted and the rest of the thought
+ * released.
+ *
+ * @module
+ */
+import { CANARY_LEAK_REACH, canaryHoldFrom, canaryLeakRanges, canaryOpeningFrom, createCanaryScanner, promptLeakCarry, RELEASED_LOOKBACK, wordStartAcross, } from './canary.js';
+import { CANARY_HIT, egressChecksOf, NO_CHECKS, PROMPT_ECHO_HIT, } from './egress.js';
+import { SYSTEM_BOUNDARY } from './egress-patterns.js';
+import { createEgressStream } from './egress-stream.js';
+import { imageLeakSpans, linkLeakSpans } from './egress-urls.js';
+import { lexiconText } from './lexicon.js';
+import { promptEchoHoldFrom, promptEchoRanges, promptEchoScanFrom } from './prompt-echo.js';
+import { EGRESS_RULES } from './rules.js';
+const OMIT_KEYS = {
+    image: 'thought.omitted_image',
+    link: 'thought.omitted_link',
+    instructions: 'thought.omitted_instructions',
+};
+const IMAGE_HIT = { rule: EGRESS_RULES.image, severity: 'high' };
+const LINK_HIT = { rule: EGRESS_RULES.link, severity: 'high' };
+const BOUNDARY_HIT = { rule: EGRESS_RULES.boundary, severity: 'medium' };
+/** Where `raw`, an offset into `view.text`, stands in the thought: a placeholder's start, or with `end` its end. */
+function shownAt(view, raw, end = false) {
+    let piece = view.pieces[0];
+    for (const next of view.pieces) {
+        if (next.raw > raw || (end && next.raw === raw && raw > 0))
+            break;
+        piece = next;
+    }
+    if (!piece)
+        return raw;
+    if (piece.mark)
+        return end ? piece.mark.end : piece.mark.start;
+    return piece.shown + raw - piece.raw;
+}
+/** The checks of `checks` a thought runs: what it would load, and the markers it would show. */
+function thoughtChecks(checks) {
+    if (!(checks.images || checks.links || checks.boundary))
+        return undefined;
+    return {
+        ...NO_CHECKS,
+        boundary: checks.boundary,
+        ...(checks.images ? { images: checks.images } : {}),
+        ...(checks.links ? { links: checks.links } : {}),
+    };
+}
+/** Sorted, with overlapping leaks as one: an image's URL is a bare link too. */
+function merged(spans) {
+    const out = [];
+    for (const span of [...spans].sort((a, b) => a.start - b.start)) {
+        const last = out.at(-1);
+        if (last && span.start < last.end)
+            last.end = Math.max(last.end, span.end);
+        else
+            out.push({ ...span });
+    }
+    return out;
+}
+/** Omitting one leak can join what was around it into another; past this many rounds, the rest goes. */
+const MAX_ROUNDS = 8;
+/** Each leak rereads the thought; a thought still writing them past this many loses the rest. */
+const MAX_LEAKS = 16;
+/**
+ * The guard reads the thought as it will be shown, placeholders in: text
+ * released is final, and what is held changes only by omission. The canary
+ * and prompt echo are read a second time with each placeholder as the text it
+ * replaced, so a leak running on past one, or across one longer than its
+ * text, is omitted too.
+ */
+function createThoughtGuard(options) {
+    const { checks, canary, given, lexicon } = options;
+    const privateSystem = canary ? options.privateSystem : undefined;
+    const scope = (check) => ({ ...check, ...(given ? { given } : {}) });
+    /** The placeholder for `kind` after `before`, without a second space. */
+    function placeholder(kind, before) {
+        const text = lexiconText(OMIT_KEYS[kind], {}, lexicon);
+        return /\s$/.test(before) ? text.trimStart() : text;
+    }
+    let out = canary ? (options.carry ?? '') : '';
+    let held = '';
+    let stream;
+    let scanner;
+    /** How far the prompt echo has read `out + held` clean. */
+    let echoed = 0;
+    /** How much of `out + held` the readers have read. */
+    let readTo = 0;
+    /** Where a leak still growing at the end of the held text starts; held until it ends. */
+    let open;
+    /** The placeholders in `out + held` a leak reaching the held text could run through, in order. */
+    let marks = [];
+    /**
+     * No canary opening starts in `out + held` before this while the held text
+     * only grows and is released: a point further back than `RELEASED_LOOKBACK`
+     * that is no opening cannot become one. An omission rewrites the held text,
+     * and the hold is read whole again.
+     */
+    let openingFrom = 0;
+    /** Set once the rest of the thought is omitted: nothing more is read until the flush. */
+    let cut = false;
+    let leaks = 0;
+    let hits = new Map();
+    /** Fresh readers over `text`, as if it had streamed: true when it already holds a leak. */
+    function restart(text) {
+        stream = checks ? createEgressStream({ checks, ...(given ? { given } : {}) }) : undefined;
+        scanner = canary ? createCanaryScanner(canary) : undefined;
+        echoed = 0;
+        readTo = 0;
+        return read(text);
+    }
+    /** Read `text`, what follows the read part of `out + held`; true when a leak has settled. */
+    function read(text) {
+        readTo += text.length;
+        const urlHit = stream?.push(text) !== undefined;
+        const canaryHit = scanner?.push(text) ?? false;
+        let echoHit = false;
+        if (privateSystem) {
+            const whole = (out + held).slice(0, readTo);
+            const from = promptEchoScanFrom(whole, echoed);
+            echoHit = promptEchoRanges(whole.slice(from), privateSystem, canary).length > 0;
+            echoed = whole.length;
+        }
+        return urlHit || canaryHit || echoHit;
+    }
+    function leakSpans(text) {
+        const spans = [];
+        if (checks?.images) {
+            for (const span of imageLeakSpans(text, scope(checks.images))) {
+                spans.push({ ...span, kind: 'image', hit: IMAGE_HIT });
+            }
+        }
+        if (checks?.links) {
+            for (const span of linkLeakSpans(text, scope(checks.links), checks.images !== undefined)) {
+                spans.push({ ...span, kind: 'link', hit: LINK_HIT });
+            }
+        }
+        if (checks?.boundary) {
+            for (const match of text.matchAll(new RegExp(SYSTEM_BOUNDARY.source, 'gi'))) {
+                const start = match.index;
+                spans.push({
+                    start,
+                    end: start + match[0].length,
+                    kind: 'instructions',
+                    hit: BOUNDARY_HIT,
+                });
+            }
+        }
+        if (canary) {
+            for (const [start, end] of canaryLeakRanges(text, canary)) {
+                spans.push({ start, end, kind: 'instructions', hit: CANARY_HIT });
+            }
+        }
+        if (privateSystem) {
+            for (const [start, end] of promptEchoRanges(text, privateSystem, canary)) {
+                spans.push({ start, end, kind: 'instructions', hit: PROMPT_ECHO_HIT });
+            }
+        }
+        return spans;
+    }
+    /** The mark `at` falls inside, if any. */
+    function markAt(at) {
+        return marks.find((mark) => mark.start < at && at < mark.end);
+    }
+    /** `out + held` from `from` to `to`, mark boundaries both, each placeholder as the text it replaced. */
+    function rawOf(from, to) {
+        const whole = out + held;
+        let text = '';
+        let at = from;
+        for (const mark of marks) {
+            if (mark.end <= from || mark.start >= to)
+                continue;
+            text += whole.slice(at, mark.start) + mark.raw;
+            at = mark.end;
+        }
+        return text + whole.slice(at, to);
+    }
+    /**
+     * The thought from far enough back that a leak reaching the held text
+     * starts inside, placeholders read as what they replaced; none when no
+     * placeholder is that close, as it then reads as the thought does.
+     */
+    function rawView() {
+        const whole = out + held;
+        for (let reach = CANARY_LEAK_REACH;; reach *= 2) {
+            let from = out.length;
+            let length = 0;
+            for (let i = marks.length - 1; from > 0 && length < reach;) {
+                const mark = marks[i];
+                if (mark && mark.end > from) {
+                    i--;
+                }
+                else if (mark && mark.end === from) {
+                    length += mark.raw.length;
+                    from = mark.start;
+                    i--;
+                }
+                else {
+                    const stop = Math.max(mark?.end ?? 0, from - (reach - length));
+                    length += from - stop;
+                    from = stop;
+                }
+            }
+            marks = marks.filter((mark) => mark.end > from);
+            if (marks.length === 0)
+                return undefined;
+            const view = { text: '', held: 0, pieces: [] };
+            let at = from;
+            for (const mark of [...marks, undefined]) {
+                const plain = mark ? mark.start : whole.length;
+                if (plain > at)
+                    view.pieces.push({ raw: view.text.length, shown: at });
+                if (at <= out.length && out.length <= plain)
+                    view.held = view.text.length + out.length - at;
+                view.text += whole.slice(at, plain);
+                if (!mark)
+                    break;
+                view.pieces.push({ raw: view.text.length, shown: mark.start, mark });
+                view.text += mark.raw;
+                at = mark.end;
+            }
+            // An echo run is counted in words: read back until it fits, or the thought starts.
+            if (!privateSystem || from === 0 || promptEchoScanFrom(view.text, view.held) > 0)
+                return view;
+        }
+    }
+    /** The leaks the raw view finds that leave something held still shown, as spans of the thought. */
+    function rawLeaks() {
+        const view = rawView();
+        if (!view)
+            return [];
+        const ranges = [];
+        if (canary) {
+            for (const [start, end] of canaryLeakRanges(view.text, canary)) {
+                ranges.push([start, end, CANARY_HIT]);
+            }
+        }
+        if (privateSystem) {
+            for (const [start, end] of promptEchoRanges(view.text, privateSystem, canary)) {
+                ranges.push([start, end, PROMPT_ECHO_HIT]);
+            }
+        }
+        const spans = [];
+        for (const [rawStart, rawEnd, hit] of ranges) {
+            if (rawEnd <= view.held)
+                continue;
+            const start = shownAt(view, rawStart);
+            const end = shownAt(view, rawEnd, true);
+            let shows = false;
+            for (let at = Math.max(start, out.length); at < end && !shows; at++) {
+                shows = !marks.some((mark) => mark.start <= at && at < mark.end);
+            }
+            if (shows)
+                spans.push({ start, end, kind: 'instructions', hit });
+        }
+        return spans;
+    }
+    /** Every leak in the thought, as shown and as written, overlapping ones as one. */
+    function allLeaks() {
+        return merged([...leakSpans(out + held), ...rawLeaks()]);
+    }
+    /** The leaks reaching into the held text, in order. */
+    function heldLeaks() {
+        return allLeaks().filter(({ end }) => end > out.length);
+    }
+    /** `at` moved off the inside of a placeholder: back to its start, or with `end` on to its end. */
+    function offMark(at, end = false) {
+        const mark = markAt(at);
+        return mark ? (end ? mark.end : mark.start) : at;
+    }
+    /**
+     * Replace each leak reaching into the held text with its placeholder, but
+     * for one reaching its end, which the next chunk could continue: that one is
+     * held whole (`open`) unless the thought has ended. False when nothing was replaced.
+     */
+    function omitHeld(ended) {
+        const spans = heldLeaks();
+        const whole = out + held;
+        const tail = spans.at(-1);
+        const growing = !ended && tail !== undefined && tail.end >= whole.length ? tail : undefined;
+        const closed = growing ? spans.slice(0, -1) : spans;
+        const kept = marks.filter((mark) => mark.end <= out.length);
+        let next = '';
+        let at = out.length;
+        /** Copy `whole` up to `to`, and the marks in it. */
+        const copy = (to) => {
+            const shift = out.length + next.length - at;
+            for (const mark of marks) {
+                if (mark.start >= at && mark.end <= to) {
+                    kept.push({ ...mark, start: mark.start + shift, end: mark.end + shift });
+                }
+            }
+            next += whole.slice(at, Math.max(at, to));
+            at = Math.max(at, to);
+        };
+        for (const { start, end, kind, hit } of closed) {
+            copy(offMark(start));
+            const to = Math.max(at, offMark(end, true));
+            const text = placeholder(kind, out + next);
+            const begin = out.length + next.length;
+            kept.push({ start: begin, end: begin + text.length, raw: rawOf(at, to) });
+            next += text;
+            hits.set(hit.rule, hit);
+            at = to;
+        }
+        open = undefined;
+        if (growing) {
+            copy(offMark(growing.start));
+            open = out.length + next.length;
+        }
+        copy(whole.length);
+        marks = kept;
+        held = next;
+        openingFrom = 0;
+        return closed.length > 0;
+    }
+    /** Omit the held text from the first leak on; all of it when the leak is in what was shown. */
+    function cutRest() {
+        const first = allLeaks()[0];
+        const from = first ? Math.max(0, offMark(first.start) - out.length) : 0;
+        const kept = held.slice(0, from);
+        const text = placeholder(first?.kind ?? 'instructions', out + kept);
+        const begin = out.length + from;
+        const raw = rawOf(begin, out.length + held.length);
+        marks = marks.filter((mark) => mark.end <= begin);
+        marks.push({ start: begin, end: begin + text.length, raw });
+        held = kept + text;
+        openingFrom = 0;
+        if (first)
+            hits.set(first.hit.rule, first.hit);
+        open = undefined;
+        cut = true;
+    }
+    /** What the readers read: the thought up to a leak still growing. */
+    function readable() {
+        const whole = out + held;
+        return open === undefined ? whole : whole.slice(0, open);
+    }
+    /** Omit leaks until fresh readers over the thought settle none; failing that, the rest. */
+    function settle() {
+        for (let round = 0; round < MAX_ROUNDS; round++) {
+            if (leaks >= MAX_LEAKS)
+                break;
+            const before = new Set(marks.map((mark) => mark.start));
+            if (!omitHeld(false)) {
+                // A leak the readers settled that no span covers is cut, not shown.
+                if (open === undefined)
+                    break;
+                return;
+            }
+            // A leak running on past its placeholder only grows it.
+            if (marks.some((mark) => !before.has(mark.start)))
+                leaks++;
+            if (!restart(readable()))
+                return;
+        }
+        cutRest();
+    }
+    /** The earliest index of `out + held` a leak could still start at, moved back to the start of a word it cuts. */
+    function holdFrom() {
+        const end = out.length + held.length;
+        const url = stream ? stream.holdFrom() : end;
+        const leak = canary ? canaryFrom(canary) : end;
+        const echo = privateSystem ? out.length + promptEchoHoldFrom(held, privateSystem, canary) : end;
+        const from = Math.min(url, leak, echo, rawHoldFrom() ?? end, open ?? end);
+        return offMark(from < out.length ? from : out.length + wordStartAcross(held, from - out.length));
+    }
+    /** `canaryHoldFrom` on the held text, as an index of `out + held`, read from where an opening could start. */
+    function canaryFrom(canary) {
+        const from = Math.max(out.length, openingFrom);
+        const lead = Math.max(0, from - RELEASED_LOOKBACK);
+        let at = lead + canaryOpeningFrom(textFrom(lead), canary);
+        if (at < from && from > out.length) {
+            // An opening the bound rules out: read the held text whole.
+            const whole = Math.max(0, out.length - RELEASED_LOOKBACK);
+            at = whole + canaryOpeningFrom(textFrom(whole), canary);
+        }
+        openingFrom = Math.min(at, out.length + held.length - RELEASED_LOOKBACK);
+        return Math.max(out.length, at);
+    }
+    /** `out + held` from `from` on. */
+    function textFrom(from) {
+        return from < out.length ? out.slice(from) + held : held.slice(from - out.length);
+    }
+    /** The hold as the raw view reads it: an opening a placeholder spent may not be spent. */
+    function rawHoldFrom() {
+        const view = rawView();
+        if (!view)
+            return undefined;
+        const rest = view.text.slice(view.held);
+        const leak = canary ? canaryHoldFrom(rest, canary, view.text.slice(0, view.held)) : rest.length;
+        const echo = privateSystem ? promptEchoHoldFrom(rest, privateSystem, canary) : rest.length;
+        return shownAt(view, view.held + Math.min(leak, echo));
+    }
+    function release(text) {
+        const shown = { text, hits: [...hits.values()] };
+        hits = new Map();
+        return shown;
+    }
+    restart(out);
+    return {
+        push(text) {
+            if (cut || !text)
+                return release('');
+            held += text;
+            if (open !== undefined || read(text) || rawLeaks().length > 0)
+                settle();
+            if (cut)
+                return release('');
+            const clear = Math.max(0, holdFrom() - out.length);
+            const shown = held.slice(0, clear);
+            out += shown;
+            held = held.slice(clear);
+            return release(shown);
+        },
+        flush() {
+            if (!cut) {
+                for (let round = 0; round < MAX_ROUNDS && omitHeld(true); round++)
+                    ;
+                // A leak left is one the text shown already takes part in, such as a definition an image opener held here could use.
+                if (held && (leakSpans(out + held).length > 0 || rawLeaks().length > 0))
+                    cutRest();
+            }
+            const shown = held;
+            const whole = out + held;
+            out = canary ? promptLeakCarry(whole, canary, privateSystem) : '';
+            const shift = out.length - whole.length;
+            marks = marks
+                .filter((mark) => mark.start + shift >= 0)
+                .map((mark) => ({ ...mark, start: mark.start + shift, end: mark.end + shift }));
+            held = '';
+            openingFrom = 0;
+            open = undefined;
+            cut = false;
+            leaks = 0;
+            restart(out);
+            return release(shown);
+        },
+        carryOut: () => out,
+    };
+}
+/**
+ * A guard for a turn's thoughts: the canary and prompt echo whenever the turn
+ * binds a canary, and the URL and boundary checks `enforce` runs.
+ */
+function thoughtGuardFor(enforce, context, carry) {
+    const known = egressChecksOf(enforce);
+    const checks = known ? thoughtChecks(known) : undefined;
+    const { canary, privateSystem, givenUrls, lexicon } = context;
+    if (!(checks || canary))
+        return undefined;
+    return createThoughtGuard({
+        ...(checks ? { checks } : {}),
+        ...(canary ? { canary } : {}),
+        ...(privateSystem ? { privateSystem } : {}),
+        ...(givenUrls ? { given: givenUrls } : {}),
+        ...(lexicon ? { lexicon } : {}),
+        ...(carry ? { carry } : {}),
+    });
+}
+export { createThoughtGuard, thoughtGuardFor };

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

@@ -0,0 +1,19 @@
+import type { AdvisoryLevel, GuardrailHit } from './types.js';
+/**
+ * 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.
+ *
+ * `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.
+ */
+declare function directiveHits(text: string, callableTools?: readonly string[]): GuardrailHit[];
+declare function looksDirective(hits: GuardrailHit[]): boolean;
+/**
+ * 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.
+ */
+declare function advisoryLevel(hits: GuardrailHit[]): AdvisoryLevel;
+export { advisoryLevel, directiveHits, looksDirective };

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

@@ -0,0 +1,109 @@
+import { normalizeForDetection } from './normalize.js';
+import { DIRECTIVE_RULES } from './rules.js';
+/**
+ * Imperatives aimed at an agent rather than a reader.
+ *
+ * Bounded quantifiers throughout: tool results can be large, and an unbounded
+ * scanner on attacker-controlled bytes is a denial-of-service surface.
+ */
+const IMPERATIVES = [
+    /\b(?:next|final|remaining)\s+steps?\s*[:—-]/gi,
+    /\byou\s+(?:must|should|need\s+to|are\s+required\s+to)\s+(?:now\s+)?\w{2,20}/gi,
+    /\bto\s+(?:complete|finish|fulfil|fulfill)\s+(?:this|the)\s+\w{2,20}/gi,
+    /\b(?:call|invoke|run|execute)\s+(?:the\s+)?[\w.-]{2,40}\s+(?:tool|function)\b/gi,
+    /\b(?:send|forward|email|transfer|upload|post)\s+(?:the\s+|all\s+|your\s+)?[\w\s]{2,40}\s+to\s+\S{3,80}/gi,
+    /\b(?:delete|remove|drop|purge)\s+(?:the\s+|all\s+)?[\w\s]{2,40}\b/gi,
+];
+/**
+ * A concrete external destination — the thing exfiltration needs and ordinary
+ * process prose almost never carries.
+ *
+ * This is the discriminator. Directive language on its own is everywhere in
+ * legitimate tool output: documentation says "you must be an admin", support
+ * 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.
+ */
+const EXFIL_TARGET = /\b[\w.+-]{1,64}@[\w-]{1,63}(?:\.[\w-]{1,63}){1,4}\b|\bhttps?:\/\/\S{4,120}/i;
+/** 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,
+    /\b(?:system|admin|operator)\s+(?:note|notice|message|override|instruction)s?\s*[:—-]/gi,
+    /\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);
+    });
+}
+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) {
+    if (tool.length < 3) {
+        return false;
+    }
+    const haystack = text.toLowerCase();
+    const needle = tool.toLowerCase();
+    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;
+        }
+        at = haystack.indexOf(needle, at + needle.length);
+    }
+    return false;
+}
+/**
+ * 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.
+ *
+ * `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.
+ */
+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.
+        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' });
+    }
+    return hits;
+}
+function looksDirective(hits) {
+    return hits.length > 0;
+}
+/**
+ * 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.
+ */
+function advisoryLevel(hits) {
+    if (hits.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';
+}
+export { advisoryLevel, directiveHits, looksDirective };

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

@@ -0,0 +1,61 @@
+import { type LexiconOverrides } from './lexicon.js';
+import type { AdvisoryLevel, GuardrailEvent, GuardrailHit, Provenance, ResolvedGuardrailPolicy, ToolOrigin, TurnTaint, Verdict } from './types.js';
+declare const TOOL_CLOSE = "</tool_data>";
+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;
+export interface GuardedToolText {
+    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.
+     */
+    suspicious?: GuardrailHit[];
+}
+/**
+ * `finding` is the tool's summary and `data` its structured payload; both reach
+ * the model, so both are guarded together rather than only the prose half.
+ */
+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.
+ */
+declare function guardToolResult(finding: string, data: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, callableTools?: readonly string[], lexicon?: LexiconOverrides): 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;
+/**
+ * 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.
+ */
+declare function inspectToolArguments(args: unknown, policy: ResolvedGuardrailPolicy): Verdict;
+declare function toolCallEvent(verdict: Verdict, provenance: Provenance): GuardrailEvent | undefined;
+/**
+ * Only remote origins taint: a local host tool returns bytes the host's own code
+ * produced, and treating those as attacker-influenceable would make the gate
+ * useless in practice.
+ */
+declare function recordTaint(taint: TurnTaint | undefined, provenance: Provenance, suspicious?: GuardrailHit[]): TurnTaint;
+declare function isTainted(taint: TurnTaint | undefined): boolean;
+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, };