@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/guardrails/credential-scan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Credentials found the way gitleaks finds them: a rule's regex, then the
+ * secret in it (its `secretGroup`, else its first non-empty group), dropped
+ * when the rule's keywords are not in the text, when the secret's Shannon
+ * entropy is at or under the rule's floor, or when an allowlist lets it through.
+ *
+ * gitleaks reads a rule's keywords anywhere in a file. Here one must be in the
+ * text by the end of the match, so a reply read as it streams and the reply
+ * read whole find the same secrets.
+ *
+ * gitleaks' `gitleaks:allow` comment is not honoured: in a chat the model or
+ * a page writes it, not the owner of the secret.
+ *
+ * @module
+ */
+import type { RedactSpan } from '../observability/spans.js';
+/** Matches a credential rule lets through. */
+interface CredentialAllowlist {
+    /** What the regexes read: the secret, the whole match, or the lines the match is on. */
+    target: 'secret' | 'match' | 'line';
+    regexes: readonly RegExp[];
+    /** SHA-256 hex digests of values that let through, so a literal is not kept in source. */
+    hashes: readonly string[];
+    /** Words that, anywhere in the secret, case aside, let it through. */
+    stopwords: readonly string[];
+}
+interface CredentialRule {
+    id: string;
+    pattern: RegExp;
+    /** The group holding the secret; else the first non-empty group, else the match. */
+    secretGroup?: number;
+    /** The Shannon entropy, in bits per character, a secret must be over. */
+    entropy?: number;
+    /** Words, lower case, one of which the text must hold by the end of a match. */
+    keywords: readonly string[];
+    allowlists: readonly CredentialAllowlist[];
+}
+/** Shannon entropy over the characters of `data`, per UTF-8 byte as gitleaks counts it. */
+declare function shannonEntropy(data: string): number;
+/** The secrets `rules` find in `text`, each one's span. */
+declare function credentialSpans(text: string, rules: readonly CredentialRule[], global: CredentialAllowlist): RedactSpan[];
+/** Whether a match of `rule` at `at` of `text` is a credential gitleaks reports. */
+declare function credentialHit(rule: CredentialRule, global: CredentialAllowlist, match: string, text: string, at: number): boolean;
+export type { CredentialAllowlist, CredentialRule };
+export { credentialHit, credentialSpans, shannonEntropy };

package/esm/src/guardrails/credential-scan.js

@@ -0,0 +1,172 @@
+/**
+ * Credentials found the way gitleaks finds them: a rule's regex, then the
+ * secret in it (its `secretGroup`, else its first non-empty group), dropped
+ * when the rule's keywords are not in the text, when the secret's Shannon
+ * entropy is at or under the rule's floor, or when an allowlist lets it through.
+ *
+ * gitleaks reads a rule's keywords anywhere in a file. Here one must be in the
+ * text by the end of the match, so a reply read as it streams and the reply
+ * read whole find the same secrets.
+ *
+ * gitleaks' `gitleaks:allow` comment is not honoured: in a chat the model or
+ * a page writes it, not the owner of the secret.
+ *
+ * @module
+ */
+/** Shannon entropy over the characters of `data`, per UTF-8 byte as gitleaks counts it. */
+function shannonEntropy(data) {
+    if (data === '')
+        return 0;
+    const counts = new Map();
+    for (const char of data)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    const bytes = new TextEncoder().encode(data).length;
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const freq = count / bytes;
+        entropy -= freq * Math.log2(freq);
+    }
+    return entropy;
+}
+const SHA256_K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/** SHA-256 of `text` as lower-case hex, synchronously: the scan is synchronous and runs in the browser too. */
+function sha256Hex(text) {
+    const bytes = new TextEncoder().encode(text);
+    const bits = bytes.length * 8;
+    const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) * 64);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 4, bits >>> 0);
+    view.setUint32(padded.length - 8, Math.floor(bits / 0x100000000));
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(off + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const x = w[i - 15];
+            const y = w[i - 2];
+            const s0 = ((x >>> 7) | (x << 25)) ^ ((x >>> 18) | (x << 14)) ^ (x >>> 3);
+            const s1 = ((y >>> 17) | (y << 15)) ^ ((y >>> 19) | (y << 13)) ^ (y >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+        let [a, b, c, d, e, f, g, k] = h;
+        for (let i = 0; i < 64; i++) {
+            const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (k + S1 + ch + SHA256_K[i] + w[i]) | 0;
+            const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (S0 + maj) | 0;
+            [k, g, f, e, d, c, b, a] = [g, f, e, (d + t1) | 0, c, b, a, (t1 + t2) | 0];
+        }
+        const next = [a, b, c, d, e, f, g, k];
+        for (let i = 0; i < 8; i++)
+            h[i] = (h[i] + next[i]) | 0;
+    }
+    return [...h].map((x) => x.toString(16).padStart(8, '0')).join('');
+}
+function allowed(list, read) {
+    const target = read[list.target];
+    const lower = read.secret.toLowerCase();
+    return ((target !== '' && list.regexes.some((regex) => regex.test(target))) ||
+        (target !== '' && list.hashes.length > 0 && list.hashes.includes(sha256Hex(target))) ||
+        (lower !== '' && list.stopwords.some((word) => lower.includes(word))));
+}
+/** The lines of `text` the stretch [start, end) is on. */
+function linesOf(text, start, end) {
+    const from = text.lastIndexOf('\n', start - 1) + 1;
+    const to = text.indexOf('\n', end);
+    return text.slice(from, to < 0 ? text.length : to);
+}
+/** Whether one of `rule`'s keywords is in `lower`, the text in lower case, by `end`. */
+function keywordsIn(rule, lower, end = lower.length) {
+    return (rule.keywords.length === 0 ||
+        rule.keywords.some((word) => {
+            const at = lower.indexOf(word);
+            return at >= 0 && at + word.length <= end;
+        }));
+}
+const FINDERS = new WeakMap();
+/** `pattern` with its indices, read from the start of a string. */
+function finder(pattern) {
+    let found = FINDERS.get(pattern);
+    if (!found) {
+        found = new RegExp(pattern.source, `${pattern.flags.replace('g', '')}d`);
+        FINDERS.set(pattern, found);
+    }
+    return found;
+}
+/**
+ * Where the secret in `rule`'s match at `at` of `text` is, or undefined when
+ * gitleaks would let the match through. Keywords are not read here.
+ */
+function credentialSecret(rule, global, text, match, at) {
+    let lead = 0;
+    while (match[lead] === '\n')
+        lead++;
+    let tail = match.length;
+    while (tail > lead && match[tail - 1] === '\n')
+        tail--;
+    const trimmed = match.slice(lead, tail);
+    const start = at + lead;
+    let secret = { start, end: start + trimmed.length };
+    const groups = finder(rule.pattern).exec(trimmed);
+    const indices = groups?.indices;
+    if (groups && indices && groups.length >= 2) {
+        const group = rule.secretGroup ??
+            groups.findIndex((value, index) => index > 0 && value !== undefined && value !== '');
+        const span = indices[group];
+        if (span)
+            secret = { start: start + span[0], end: start + span[1] };
+        else if (rule.secretGroup)
+            secret = { start, end: start };
+    }
+    const read = {
+        secret: text.slice(secret.start, secret.end),
+        match: trimmed,
+        line: linesOf(text, start, start + trimmed.length),
+    };
+    if (rule.entropy !== undefined && shannonEntropy(read.secret) <= rule.entropy)
+        return undefined;
+    if (allowed(global, read) || rule.allowlists.some((list) => allowed(list, read))) {
+        return undefined;
+    }
+    return secret.end > secret.start ? secret : { start, end: start + trimmed.length };
+}
+/** The secrets `rules` find in `text`, each one's span. */
+function credentialSpans(text, rules, global) {
+    const lower = text.toLowerCase();
+    const spans = [];
+    for (const rule of rules) {
+        if (!keywordsIn(rule, lower))
+            continue;
+        const pattern = new RegExp(rule.pattern.source, `${rule.pattern.flags}g`);
+        for (const match of text.matchAll(pattern)) {
+            if (match[0] === '' || !keywordsIn(rule, lower, match.index + match[0].length))
+                continue;
+            const secret = credentialSecret(rule, global, text, match[0], match.index);
+            if (secret)
+                spans.push({ ...secret, kind: 'sensitive' });
+        }
+    }
+    return spans;
+}
+/** Whether a match of `rule` at `at` of `text` is a credential gitleaks reports. */
+function credentialHit(rule, global, match, text, at) {
+    return (keywordsIn(rule, text.slice(0, at + match.length).toLowerCase()) &&
+        credentialSecret(rule, global, text, match, at) !== undefined);
+}
+export { credentialHit, credentialSpans, shannonEntropy };

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

@@ -0,0 +1,45 @@
+/**
+ * A hijacked agent has to send what it took somewhere, and the hijacker has to
+ * say where.
+ *
+ * @module
+ */
+import type { TurnHistoryMessage } from '../kernel/turn-events.js';
+import type { ModelRequest } from '../kernel/types.js';
+import { type LabelOverrides } from './labels.js';
+import type { Provenance, ResolvedGuardrailPolicy, Verdict } from './types.js';
+/** What the turn has read so far, by who wrote it. Keys are `kind:value`, lowercased. */
+interface TurnDestinations {
+    /** From the system prompt, the user, host history, and local tools. */
+    given: Set<string>;
+    /** From the running text of remote tool results, with the tool that returned each. */
+    remote: Map<string, string>;
+}
+declare function turnDestinations(): TurnDestinations;
+/** Notes every destination in `value`'s strings as given. */
+declare function addGivenDestinations(turn: TurnDestinations, value: unknown): void;
+/** Notes what the user and the host said in `messages`. */
+declare function addHistoryDestinations(turn: TurnDestinations, messages: readonly TurnHistoryMessage[], own: WeakSet<object>): void;
+/** Notes what a provider request gives the model. `own` holds what quotes the model's own words. */
+declare function addRequestDestinations(turn: TurnDestinations, request: Pick<ModelRequest, 'system' | 'input' | 'history'>, own: WeakSet<object>): void;
+/**
+ * Notes what a tool result gives the model. A local tool runs the host's own
+ * code, so what it returns is given, as for taint.
+ */
+declare function addResultDestinations(turn: TurnDestinations, result: {
+    finding: string;
+    data?: unknown;
+}, provenance: Provenance): void;
+/** A call's verdict, and what an approval card says when the profile asks the user first. */
+interface DestinationVerdict {
+    verdict: Verdict;
+    /** Set when the profile holds the call for the user's answer. */
+    confirm?: string;
+}
+/**
+ * Reported whether or not the profile acts on it, so a host sees how often the
+ * rule would hold a call before it turns that on.
+ */
+declare function checkDestinationGate(turn: TurnDestinations | undefined, args: unknown, policy: ResolvedGuardrailPolicy, labels?: LabelOverrides): DestinationVerdict;
+export type { DestinationVerdict, TurnDestinations };
+export { addGivenDestinations, addHistoryDestinations, addRequestDestinations, addResultDestinations, checkDestinationGate, turnDestinations, };

package/esm/src/guardrails/destinations.js

@@ -0,0 +1,234 @@
+/**
+ * A hijacked agent has to send what it took somewhere, and the hijacker has to
+ * say where.
+ *
+ * @module
+ */
+import { labelText } from './labels.js';
+import { TOOL_RULES } from './rules.js';
+import { textForScan } from './serialize.js';
+import { isRemoteOrigin } from './tool-result.js';
+function turnDestinations() {
+    return { given: new Set(), remote: new Map() };
+}
+const LOCAL_PART = /[\p{L}\p{N}_.+-]/u;
+const LABEL_CHAR = /[\p{L}\p{N}_-]/u;
+const LINK = /(?:https?:\/\/|www\.)[^\s'"<>)\]]+/gi;
+/** An IBAN's shape: two letters, two check digits, then the account. */
+const ACCOUNT = /\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b/g;
+const HOST_END = /[/?#]/;
+/** Where the run of label characters starting at `from` ends. */
+function labelEnd(text, from) {
+    let end = from;
+    while (end < text.length) {
+        const char = String.fromCodePoint(text.codePointAt(end) ?? 0);
+        if (!LABEL_CHAR.test(char))
+            break;
+        end += char.length;
+    }
+    return end;
+}
+/**
+ * Where the domain starting at `from` ends: two or more labels joined by single
+ * dots. `-1` when there is no domain there. Read in one pass, so a long run of
+ * hyphens costs its length once.
+ */
+function domainEnd(text, from) {
+    let end = labelEnd(text, from);
+    if (end === from)
+        return -1;
+    let labels = 1;
+    while (text.charAt(end) === '.') {
+        const next = labelEnd(text, end + 1);
+        if (next === end + 1)
+            break;
+        end = next;
+        labels += 1;
+    }
+    return labels > 1 ? end : -1;
+}
+/** `host` without the full stops and commas a sentence left on its end. */
+function withoutTrailingPunctuation(host) {
+    let end = host.length;
+    while (end > 0 && (host.charAt(end - 1) === '.' || host.charAt(end - 1) === ','))
+        end -= 1;
+    return host.slice(0, end);
+}
+/** Read outward from each `@`, so a long run of letters with no address in it is read once. */
+function emailsIn(text) {
+    const found = [];
+    let at = text.indexOf('@');
+    while (at >= 0) {
+        let start = at;
+        while (start > 0 && LOCAL_PART.test(text.charAt(start - 1)))
+            start -= 1;
+        const end = start < at ? domainEnd(text, at + 1) : -1;
+        if (end >= 0) {
+            found.push({ key: `email:${text.slice(start, end).toLowerCase()}`, start, end });
+            at = text.indexOf('@', end);
+        }
+        else {
+            at = text.indexOf('@', at + 1);
+        }
+    }
+    return found;
+}
+/** Two links to one server are one destination, whatever their paths. */
+function hostOf(link) {
+    const afterScheme = link.replace(/^https?:\/\//i, '');
+    const end = afterScheme.search(HOST_END);
+    const authority = end < 0 ? afterScheme : afterScheme.slice(0, end);
+    const host = authority.slice(authority.lastIndexOf('@') + 1).replace(/:\d*$/, '');
+    return withoutTrailingPunctuation(host.toLowerCase()).replace(/^www\./, '');
+}
+function destinationsIn(text) {
+    const emails = emailsIn(text);
+    let rest = text;
+    for (const { start, end } of emails) {
+        rest = rest.slice(0, start) + ' '.repeat(end - start) + rest.slice(end);
+    }
+    const found = [...emails];
+    for (const match of [...rest.matchAll(LINK)]) {
+        const host = hostOf(match[0]);
+        if (host) {
+            found.push({ key: `host:${host}`, start: match.index, end: match.index + match[0].length });
+        }
+    }
+    for (const match of [...rest.matchAll(ACCOUNT)]) {
+        found.push({
+            key: `account:${match[0].toLowerCase()}`,
+            start: match.index,
+            end: match.index + match[0].length,
+        });
+    }
+    return found;
+}
+/** JSON a tool returned as text has fields too. */
+function parsedJson(text) {
+    const first = text.trimStart().charAt(0);
+    if (first !== '{' && first !== '[')
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+const MAX_DEPTH = 32;
+function eachString(value, visit, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return;
+    if (typeof value === 'string') {
+        const parsed = parsedJson(value);
+        if (parsed === undefined)
+            visit(value);
+        else
+            eachString(parsed, visit, depth + 1);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            eachString(item, visit, depth + 1);
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            eachString(item, visit, depth + 1);
+    }
+}
+/** Every destination in `value`'s strings; `inProse` leaves out one that is a string's whole value. */
+function destinationKeys(value, inProse = false) {
+    const keys = new Set();
+    eachString(value, (text) => {
+        const trimmed = text.trim();
+        const found = destinationsIn(trimmed);
+        const [only] = found;
+        const whole = found.length === 1 && only?.start === 0 && only.end === trimmed.length;
+        if (inProse && whole)
+            return;
+        for (const { key } of found)
+            keys.add(key);
+    });
+    return keys;
+}
+/** Notes every destination in `value`'s strings as given. */
+function addGivenDestinations(turn, value) {
+    for (const key of destinationKeys(value))
+        turn.given.add(key);
+}
+/** Notes what the user and the host said in `messages`. */
+function addHistoryDestinations(turn, messages, own) {
+    for (const message of messages) {
+        // why: An earlier turn's tool result is neither the user's word nor this turn's read.
+        if (message.role === 'assistant' || message.role === 'tool' || own.has(message))
+            continue;
+        addGivenDestinations(turn, textForScan(message).text);
+    }
+}
+/** Notes what a provider request gives the model. `own` holds what quotes the model's own words. */
+function addRequestDestinations(turn, request, own) {
+    addGivenDestinations(turn, request.system);
+    if (!own.has(request.input))
+        addGivenDestinations(turn, textForScan(request.input).text);
+    addHistoryDestinations(turn, request.history ?? [], own);
+}
+/**
+ * Notes what a tool result gives the model. A local tool runs the host's own
+ * code, so what it returns is given, as for taint.
+ */
+function addResultDestinations(turn, result, provenance) {
+    if (!isRemoteOrigin(provenance.origin)) {
+        addGivenDestinations(turn, [result.finding, result.data]);
+        return;
+    }
+    const structured = parsedJson(result.finding);
+    const prose = new Set([
+        ...(structured === undefined
+            ? destinationKeys(result.finding)
+            : destinationKeys(structured, true)),
+        ...destinationKeys(result.data, true),
+    ]);
+    for (const key of prose) {
+        if (!turn.remote.has(key))
+            turn.remote.set(key, provenance.tool);
+    }
+}
+/**
+ * Reported whether or not the profile acts on it, so a host sees how often the
+ * rule would hold a call before it turns that on.
+ */
+function checkDestinationGate(turn, args, policy, labels) {
+    if (!turn || turn.remote.size === 0)
+        return { verdict: { action: 'allow' } };
+    const found = [...destinationKeys(args)].filter((key) => turn.remote.has(key) && !turn.given.has(key));
+    if (found.length === 0)
+        return { verdict: { action: 'allow' } };
+    const values = found.map((key) => key.slice(key.indexOf(':') + 1));
+    const hits = values.map((match) => ({
+        rule: TOOL_RULES.remoteDestination,
+        severity: 'high',
+        match,
+    }));
+    const said = {
+        destination: values.join(', '),
+        sources: [...new Set(found.map((key) => turn.remote.get(key) ?? ''))].join(', '),
+    };
+    const action = policy.taint?.remoteDestination ?? 'off';
+    if (action === 'block') {
+        return {
+            verdict: {
+                action: 'block',
+                hits,
+                rejection: labelText('taint.destination_blocked', said, labels),
+            },
+        };
+    }
+    return {
+        verdict: { action: 'flag', hits },
+        ...(action === 'confirm'
+            ? { confirm: labelText('taint.destination_confirm', said, labels) }
+            : {}),
+    };
+}
+export { addGivenDestinations, addHistoryDestinations, addRequestDestinations, addResultDestinations, checkDestinationGate, turnDestinations, };

package/esm/src/guardrails/detect-at.d.ts

@@ -0,0 +1,107 @@
+import { type RedactSpan } from '../observability/spans.js';
+import { type Boundary } from './boundaries.js';
+import { type DetectAction, type Detector, type HostDetector, type ResolvedAllow, type ResolvedDetect } from './detectors.js';
+import { type LeakScope } from './egress.js';
+import type { GuardrailEvent, GuardrailHit } from './event-schemas.js';
+import type { GuardrailContext, GuardrailStage, Provenance, ResolvedGuardrailPolicy } from './types.js';
+/** What happened to text at a boundary: nothing matched, or the strongest action among the matches. */
+type DetectOutcome = 'allow' | Exclude<DetectAction, 'ignore'>;
+/** Text read as it crossed a boundary. */
+interface Detection {
+    action: DetectOutcome;
+    /** The text to let through: unchanged, or with placeholders. Absent on `block`: nothing crosses. */
+    text?: string;
+    /** Every match, each named for its detector. */
+    hits: GuardrailHit[];
+}
+declare function stronger(left: DetectOutcome, right: DetectOutcome | 'ignore'): DetectOutcome;
+/**
+ * What of the turn the detectors of what is the profile's own read: the canary it planted, whether
+ * the model was given it besides, the private stretches of its system instruction, and the URLs
+ * the model was given, and the names of its tools. A detector whose part is absent reads without
+ * it: `canary_leak`, `prompt_leak`, and `tool_leak` find nothing, and to `ungiven_images` and
+ * `ungiven_links` no URL was given.
+ */
+interface DetectScope extends LeakScope, Pick<GuardrailContext, 'givenUrls' | 'ownTools'> {
+    /** The words of the profile's own canary note, when its labels rewords it (`boundaryNote`). */
+    note?: string;
+    /** What `ungiven_images` and `ungiven_links` let through besides the given URLs. */
+    allow?: ResolvedAllow;
+    /** The tools the model can call this turn, for `tool_instructions`: a tool's text naming one is a match. */
+    callable?: readonly string[];
+}
+/**
+ * The {@linkcode LeakScope} of a turn under `detect`: each part only while its detector is above
+ * `ignore` somewhere, so a profile that reads for neither binds nothing to read for.
+ */
+declare function leakScopeOf(detect: ResolvedDetect, turn: LeakScope): LeakScope;
+/** The {@linkcode DetectScope} of a turn under `policy`: each part only while a detector reads it. */
+declare function scopeOf(policy: Pick<ResolvedGuardrailPolicy, 'detect' | 'allow'>, turn: LeakScope & Pick<GuardrailContext, 'givenUrls' | 'labels' | 'ownTools'>): DetectScope;
+/** The detectors a stream gate reads itself, as the text grows. */
+declare const SCOPED: readonly ["canary_leak", "prompt_leak"];
+declare function isScoped(detector: Detector): detector is (typeof SCOPED)[number];
+/** The host's own detectors that read `boundary`. */
+declare function hostAt(boundary: Boundary, detect: ResolvedDetect): HostDetector[];
+/** Refuses a text the person or host sent that is over `MAX_INBOUND_CHARS`; `where` names it for the log. */
+declare function refuseOverlong(text: string, where: string): void;
+/** Reads `text` as it crosses `boundary` under the profile's resolved matrix. */
+declare function detectAt(text: string, boundary: Boundary, detect: ResolvedDetect, scope?: DetectScope): Detection;
+/** The detectors that read `boundary`: every one not set to `ignore`. */
+declare function detectorsAt(boundary: Boundary, detect: ResolvedDetect): Detector[];
+/**
+ * Whether any detector reads one of `boundaries`. Given the turn's `scope`, a
+ * detector whose part is absent does not count: it has nothing to find.
+ */
+declare function detectReads(boundaries: readonly Boundary[], detect: ResolvedDetect, scope?: DetectScope): boolean;
+/** A stretch of streamed text released at a boundary, and how much of the stretch it covers. */
+interface Release extends Detection {
+    taken: number;
+}
+/** A stretch of a streamed text, and the detectors the stream settled a match of inside it. */
+interface Stretch {
+    from: number;
+    to: number;
+    settled: readonly string[];
+}
+/** What a stream reads a released stretch for: its detectors, Theorem's and the host's, in a turn of `scope`. */
+interface StreamRead {
+    detectors: readonly string[];
+    scope: DetectScope;
+}
+/**
+ * Reads the stretch `[from, to)` of `window`, a text released as it streams. A match is reported
+ * with the stretch it starts in. One being replaced is released whole: `to` is pulled back to its
+ * start when the stretch would cut it, and `taken` is how far the release got. A detector set to
+ * `block` that the stream settled a match of blocks even when this reading finds none: the two
+ * are then out of step, and the stream's finding stands.
+ */
+declare function detectRelease(window: string, { from, to, settled }: Stretch, boundary: Boundary, detect: ResolvedDetect, { detectors, scope }: StreamRead): Release;
+/** `text` with every match of `detectors` replaced by its placeholder, whatever a profile sets. */
+declare function redactDetectors(text: string, detectors: readonly Detector[]): string;
+/** Whose patterns clean a stored trace: what the turn reads with (`true`), or the sides named. */
+type StoredSides = true | {
+    theorem: boolean;
+    host: boolean;
+};
+/**
+ * What `detectors` find in a text a trace stores, whatever action a profile sets. `detect` is
+ * the profile's, for the patterns a host added to each.
+ */
+declare function storedSpans(text: string, detectors: readonly Detector[], sides: StoredSides, detect?: ResolvedDetect): RedactSpan[];
+/** What a host's own detectors find in a text a trace stores. A `find` that fails covers it all. */
+declare function storedHostSpans(text: string, detect?: ResolvedDetect): RedactSpan[];
+/** Reads several texts crossing one boundary and keeps what was found across them. */
+interface BoundaryReader {
+    /** The text to let through, or `''` once a match blocks: the caller reads `found().action`. */
+    read(text: string): string;
+    found(): Pick<Detection, 'action' | 'hits'>;
+}
+/** A reader for everything crossing `boundary` in one request. */
+declare function boundaryReader(boundary: Boundary, detect: ResolvedDetect): BoundaryReader;
+/**
+ * The guardrail event for what was found at a boundary, or `undefined` when nothing matched.
+ * `stage` is the boundary's own unless the text was read as it streamed.
+ */
+declare function detectEvent(boundary: Boundary, found: Pick<Detection, 'action' | 'hits'>, provenance?: Provenance, stage?: GuardrailStage): GuardrailEvent | undefined;
+export type { BoundaryReader, Detection, DetectOutcome, DetectScope, Release, StoredSides, StreamRead, Stretch, };
+export { boundaryReader, detectAt, detectEvent, detectorsAt, detectReads, detectRelease, hostAt, isScoped, leakScopeOf, redactDetectors, refuseOverlong, scopeOf, storedHostSpans, storedSpans, stronger, };