@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/guardrails/network.js

@@ -0,0 +1,328 @@
+import { TheoremError } from './error.js';
+/**
+ * IPv4 ranges refused outright:
+ * - Loopback: 127.0.0.0/8
+ * - RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
+ * - Link-local / Cloud metadata: 169.254.0.0/16
+ * - Current network: 0.0.0.0/8
+ * - RFC 6598 Carrier-grade NAT: 100.64.0.0/10
+ * - RFC 5737 / RFC 6890 documentation / assignments: 192.0.0.0/24, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24
+ * - RFC 2544 benchmark testing: 198.18.0.0/15
+ * - Broadcast / multicast / reserved: 224.0.0.0/4, 240.0.0.0/4, 255.255.255.255
+ */
+/** Four dotted decimal octets and nothing else, so an IPv6 literal's dotted tail is never read as an IPv4 address. */
+const IPV4_LITERAL = /^\d{1,3}(\.\d{1,3}){3}$/;
+const PRIVATE_OR_LOCAL_IPV4_MATCHES = [
+    (b0) => b0 === 0, // 0.0.0.0/8
+    (b0) => b0 === 127, // 127.0.0.0/8 (loopback)
+    (b0) => b0 === 10, // 10.0.0.0/8
+    (b0, b1) => b0 === 100 && b1 >= 64 && b1 <= 127, // 100.64.0.0/10 (CGNAT)
+    (b0, b1) => b0 === 172 && b1 >= 16 && b1 <= 31, // 172.16.0.0/12
+    (b0, b1) => b0 === 192 && b1 === 168, // 192.168.0.0/16
+    (b0, b1) => b0 === 169 && b1 === 254, // 169.254.0.0/16 (link-local)
+    (b0, b1, b2) => b0 === 192 && b1 === 0 && (b2 === 0 || b2 === 2), // 192.0.0.0/24, 192.0.2.0/24
+    (b0, b1) => b0 === 198 && (b1 === 18 || b1 === 19), // 198.18.0.0/15
+    (b0, b1, b2) => b0 === 198 && b1 === 51 && b2 === 100, // 198.51.100.0/24
+    (b0, b1, b2) => b0 === 203 && b1 === 0 && b2 === 113, // 203.0.113.0/24
+    (b0) => b0 >= 224, // Multicast & Reserved (224.0.0.0/4, 240.0.0.0/4)
+];
+function isPrivateOrLocalIPv4Parts(b0, b1, b2, _b3) {
+    return PRIVATE_OR_LOCAL_IPV4_MATCHES.some((match) => match(b0, b1, b2));
+}
+function isPrivateOrLocalIPv4(ip) {
+    if (!IPV4_LITERAL.test(ip)) {
+        return false;
+    }
+    const [b0 = 0, b1 = 0, b2 = 0, b3 = 0] = ip.split('.').map(Number);
+    if (b0 > 255 || b1 > 255 || b2 > 255 || b3 > 255) {
+        return false;
+    }
+    return isPrivateOrLocalIPv4Parts(b0, b1, b2, b3);
+}
+function parseIPv6Words(ip) {
+    const trimmed = ip.toLowerCase().trim();
+    const lastColon = trimmed.lastIndexOf(':');
+    let ipv4Words = [];
+    let v6Str = trimmed;
+    if (lastColon !== -1) {
+        const potentialV4 = trimmed.slice(lastColon + 1);
+        if (potentialV4.includes('.')) {
+            const v4Parts = potentialV4.split('.').map((p) => Number.parseInt(p, 10));
+            if (v4Parts.length !== 4 || v4Parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+                return null;
+            }
+            const b0 = v4Parts[0] ?? 0;
+            const b1 = v4Parts[1] ?? 0;
+            const b2 = v4Parts[2] ?? 0;
+            const b3 = v4Parts[3] ?? 0;
+            ipv4Words = [(b0 << 8) | b1, (b2 << 8) | b3];
+            const head = trimmed.slice(0, lastColon + 1);
+            v6Str = head.endsWith('::') ? head : head.slice(0, -1);
+        }
+    }
+    const parts = v6Str.split('::');
+    if (parts.length > 2)
+        return null;
+    const left = parts[0] ? parts[0].split(':').filter(Boolean) : [];
+    const right = parts.length === 2 && parts[1] ? parts[1].split(':').filter(Boolean) : [];
+    const needed = 8 - ipv4Words.length;
+    if (parts.length === 1) {
+        if (left.length !== needed)
+            return null;
+    }
+    else {
+        if (left.length + right.length >= needed)
+            return null;
+    }
+    const zerosNeeded = needed - (left.length + right.length);
+    const mid = new Array(zerosNeeded).fill(0);
+    const parseHex = (s) => (/^[0-9a-f]{1,4}$/.test(s) ? Number.parseInt(s, 16) : null);
+    const leftWords = [];
+    for (const s of left) {
+        const w = parseHex(s);
+        if (w === null)
+            return null;
+        leftWords.push(w);
+    }
+    const rightWords = [];
+    for (const s of right) {
+        const w = parseHex(s);
+        if (w === null)
+            return null;
+        rightWords.push(w);
+    }
+    return [...leftWords, ...mid, ...rightWords, ...ipv4Words];
+}
+const zeros = (w, from, to) => w.slice(from, to).every((x) => x === 0);
+/**
+ * IPv6 ranges refused outright:
+ * - Unspecified `::` and loopback `::1`
+ * - Link-local fe80::/10, deprecated site-local fec0::/10, unique local fc00::/7
+ * - Multicast ff00::/8, documentation 2001:db8::/32, discard 100::/64
+ * - Local-use NAT64 64:ff9b:1::/48 (RFC 8215), which translates to IPv4 behind
+ *   the host's own gateway, and Teredo 2001::/32, whose client address is hidden
+ */
+const PRIVATE_OR_LOCAL_IPV6_MATCHES = [
+    (w) => zeros(w, 0, 8),
+    (w) => zeros(w, 0, 7) && w[7] === 1,
+    (w) => ((w[0] ?? 0) & 0xffc0) === 0xfe80,
+    (w) => ((w[0] ?? 0) & 0xffc0) === 0xfec0,
+    (w) => ((w[0] ?? 0) & 0xfe00) === 0xfc00,
+    (w) => ((w[0] ?? 0) & 0xff00) === 0xff00,
+    (w) => w[0] === 0x2001 && w[1] === 0x0db8,
+    (w) => w[0] === 0x0100 && zeros(w, 1, 4),
+    (w) => w[0] === 0x0064 && w[1] === 0xff9b && w[2] === 0x0001,
+    (w) => w[0] === 0x2001 && w[1] === 0x0000,
+];
+/**
+ * IPv6 ranges that carry an IPv4 address, judged by that address. `at` is the
+ * word where its two words start.
+ * - IPv4-mapped ::ffff:0:0/96 and IPv4-translated ::ffff:0:0:0/96
+ * - IPv4-compatible ::/96 and NAT64 64:ff9b::/96
+ * - 6to4 2002::/16, whose relay forwards to the embedded address
+ */
+const EMBEDDED_IPV4_RANGES = [
+    { match: (w) => zeros(w, 0, 5) && w[5] === 0xffff, at: 6 },
+    { match: (w) => zeros(w, 0, 4) && w[4] === 0xffff && w[5] === 0, at: 6 },
+    { match: (w) => zeros(w, 0, 6), at: 6 },
+    { match: (w) => w[0] === 0x0064 && w[1] === 0xff9b && zeros(w, 2, 6), at: 6 },
+    { match: (w) => w[0] === 0x2002, at: 1 },
+];
+function isPrivateOrLocalIPv6(ip) {
+    const words = parseIPv6Words(ip);
+    if (words?.length !== 8) {
+        return false;
+    }
+    if (PRIVATE_OR_LOCAL_IPV6_MATCHES.some((match) => match(words)))
+        return true;
+    return EMBEDDED_IPV4_RANGES.some(({ match, at }) => {
+        if (!match(words))
+            return false;
+        const hi = words[at] ?? 0;
+        const lo = words[at + 1] ?? 0;
+        return isPrivateOrLocalIPv4Parts((hi >> 8) & 0xff, hi & 0xff, (lo >> 8) & 0xff, lo & 0xff);
+    });
+}
+export function isLocalhostName(hostname) {
+    let lower = hostname.toLowerCase();
+    while (lower.endsWith('.')) {
+        lower = lower.slice(0, -1);
+    }
+    return (lower === 'localhost' ||
+        lower.endsWith('.localhost') ||
+        lower === 'local' ||
+        lower.endsWith('.local') ||
+        lower === 'internal' ||
+        lower.endsWith('.internal') ||
+        lower === 'lan' ||
+        lower.endsWith('.lan') ||
+        lower === 'home.arpa' ||
+        lower.endsWith('.home.arpa') ||
+        lower === 'localdomain' ||
+        lower.endsWith('.localdomain') ||
+        lower === '127.0.0.1' ||
+        lower === '::1' ||
+        lower === '[::1]');
+}
+export function isPrivateOrLocalAddress(ipOrHost) {
+    const stripped = ipOrHost.startsWith('[') && ipOrHost.endsWith(']') ? ipOrHost.slice(1, -1) : ipOrHost;
+    return isPrivateOrLocalIPv4(stripped) || isPrivateOrLocalIPv6(stripped);
+}
+/** Throws a `TheoremError` when the URL is blocked. */
+export function assertSafeUrl(urlStr, policy) {
+    let parsed;
+    try {
+        parsed = new URL(urlStr);
+    }
+    catch {
+        throw new TheoremError('request', `Invalid URL provided: "${urlStr}"`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const allowPrivate = policy?.allowPrivateNetworks ?? false;
+    const allowedHosts = policy?.allowedHosts?.map((h) => h.toLowerCase()) ?? [];
+    const hostname = parsed.hostname.toLowerCase();
+    // An allowed host is exempt from the address checks, never from the scheme.
+    const defaultSchemes = allowPrivate ? ['http:', 'https:'] : ['https:'];
+    const allowedSchemes = policy?.allowedSchemes
+        ? policy.allowedSchemes.map((s) => (s.endsWith(':') ? s.toLowerCase() : `${s.toLowerCase()}:`))
+        : defaultSchemes;
+    if (!allowedSchemes.includes(parsed.protocol)) {
+        throw new TheoremError('blocked', `URL scheme "${parsed.protocol}" is not permitted by network policy. Allowed: ${allowedSchemes.join(', ')}`);
+    }
+    if (!allowPrivate && !allowedHosts.includes(hostname)) {
+        if (isLocalhostName(hostname)) {
+            throw new TheoremError('blocked', `Access to loopback target "${hostname}" blocked by network guardrail. Enable allowPrivateNetworks to permit local addresses.`);
+        }
+        if (isPrivateOrLocalIPv4(hostname)) {
+            throw new TheoremError('blocked', `Access to private IPv4 address "${hostname}" blocked by network guardrail.`);
+        }
+        const strippedV6 = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
+        if (isPrivateOrLocalIPv6(strippedV6)) {
+            throw new TheoremError('blocked', `Access to private IPv6 address "${hostname}" blocked by network guardrail.`);
+        }
+    }
+    return parsed;
+}
+/** The Fetch standard's redirect limit — the one `redirect: 'follow'` applies. */
+const FETCH_REDIRECT_LIMIT = 20;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * `assertSafeUrl` judges literal addresses and local names, so a public name whose DNS answers a
+ * private address passes it. This lookup is separate from the connection's own: it stops names that
+ * point inward, but not a DNS server that changes its answer between the two (rebinding); only the
+ * host's egress layer can.
+ */
+async function assertResolvesPublic(target, options, signal) {
+    const { resolveHost, policy } = options;
+    const hostname = target.hostname.toLowerCase();
+    if (resolveHost === undefined ||
+        policy?.allowPrivateNetworks === true ||
+        policy?.allowedHosts?.some((h) => h.toLowerCase() === hostname) === true ||
+        hostname.startsWith('[') ||
+        IPV4_LITERAL.test(hostname)) {
+        return;
+    }
+    const addresses = await resolveHost(hostname, signal ?? undefined);
+    if (addresses.length === 0) {
+        throw new TheoremError('blocked', `Host "${hostname}" did not resolve to an address.`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const inward = addresses.find(isPrivateOrLocalAddress);
+    if (inward !== undefined) {
+        throw new TheoremError('blocked', `Host "${hostname}" resolves to private address "${inward}", blocked by network guardrail.`);
+    }
+}
+/** A 301/302 turns a POST into a GET, and a 303 turns anything but HEAD into a GET (Fetch standard). */
+function redirectsToGet(status, method) {
+    if (status === 303)
+        return method !== 'HEAD';
+    return (status === 301 || status === 302) && method === 'POST';
+}
+/** Every redirect hop must clear `policy`; throws a `TheoremError` (`blocked`) when one is refused. */
+export async function fetchGuarded(url, init, options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const clearHop = async (href) => {
+        const start = performance.now();
+        try {
+            const safe = assertSafeUrl(href, options.policy);
+            await assertResolvesPublic(safe, options, init.signal);
+            return safe;
+        }
+        finally {
+            options.onCheck?.(performance.now() - start);
+        }
+    };
+    let target = await clearHop(url);
+    const origin = target.origin;
+    const headers = new Headers(init.headers);
+    let method = init.method ?? 'GET';
+    let body = init.body;
+    let onOrigin = true;
+    for (let hop = 0;; hop++) {
+        const sent = new Headers(headers);
+        if (onOrigin) {
+            for (const [name, value] of Object.entries(options.originBoundHeaders ?? {})) {
+                sent.set(name, value);
+            }
+        }
+        const response = await fetchFn(target.href, {
+            ...init,
+            method,
+            headers: sent,
+            body,
+            redirect: 'manual',
+        });
+        const location = response.headers.get('location');
+        if (!options.followRedirects || !REDIRECT_STATUSES.has(response.status) || location === null) {
+            return response;
+        }
+        await response.body?.cancel();
+        if (hop === FETCH_REDIRECT_LIMIT) {
+            throw new TheoremError('network', `Too many redirects from "${url}"`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        target = await clearHop(new URL(location, target).href);
+        onOrigin &&= target.origin === origin;
+        if (redirectsToGet(response.status, method)) {
+            method = 'GET';
+            body = undefined;
+            headers.delete('content-type');
+        }
+    }
+}
+const DNS_TYPE_A = 1;
+const DNS_TYPE_AAAA = 28;
+const DNS_NOERROR = 0;
+const DNS_NXDOMAIN = 3;
+/**
+ * A {@link ResolveHost} over DNS-over-HTTPS (the DNS JSON API), for runtimes
+ * with `fetch` but no DNS lookup, such as Cloudflare Workers. It asks the
+ * endpoint, not the machine's resolver, so names only an internal resolver
+ * knows are not seen; a server host should resolve through its own DNS.
+ */
+export function dnsOverHttpsResolver(options) {
+    const fetchFn = options.fetchFn ?? fetch;
+    const query = async (hostname, type, signal) => {
+        const url = new URL(options.endpoint);
+        url.searchParams.set('name', hostname);
+        url.searchParams.set('type', String(type));
+        const response = await fetchFn(url.href, {
+            headers: { accept: 'application/dns-json' },
+            ...(signal ? { signal } : {}),
+        });
+        if (!response.ok) {
+            throw new TheoremError('network', `DNS lookup for "${hostname}" failed: HTTP ${response.status}`);
+        }
+        const answer = (await response.json());
+        if (answer.Status === DNS_NXDOMAIN)
+            return [];
+        if (answer.Status !== DNS_NOERROR) {
+            throw new TheoremError('network', `DNS lookup for "${hostname}" failed: status ${answer.Status}`);
+        }
+        return (answer.Answer ?? []).flatMap((record) => record.type === type && typeof record.data === 'string' ? [record.data] : []);
+    };
+    return async (hostname, signal) => {
+        const [v4, v6] = await Promise.all([
+            query(hostname, DNS_TYPE_A, signal),
+            query(hostname, DNS_TYPE_AAAA, signal),
+        ]);
+        return [...v4, ...v6];
+    };
+}

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

@@ -0,0 +1,6 @@
+/** What one code point reads as: stripped, folded to ASCII, or itself. */
+declare function normalizeCodePoint(ch: string): string;
+/** Whether a code point is one `EMOJI_BETWEEN` drops between letters. */
+declare function isEmoji(ch: string): boolean;
+declare function normalizeForDetection(text: string): string;
+export { isEmoji, normalizeCodePoint, normalizeForDetection };

package/esm/src/guardrails/normalize.js

@@ -0,0 +1,132 @@
+const STRIP_CODES = [
+    0x200b, 0x200c, 0x200d, 0xfeff, 0x00ad, 0x200e, 0x200f, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e,
+    0x2060, 0x2061, 0x2062, 0x2063, 0x2064, 0x034f, 0x061c, 0x180e, 0x2066, 0x2067, 0x2068, 0x2069,
+];
+const STRIP_SET = new Set(STRIP_CODES);
+const SPACE_CODES = [
+    0x00a0, 0x1680, 0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009,
+    0x200a, 0x202f, 0x205f, 0x3000,
+];
+const SPACE_SET = new Set(SPACE_CODES);
+const HOMOGLYPH_MAP = new Map([
+    [0x0430, 'a'],
+    [0x0441, 'c'],
+    [0x0435, 'e'],
+    [0x0456, 'i'],
+    [0x043e, 'o'],
+    [0x0440, 'p'],
+    [0x0455, 's'],
+    [0x0443, 'y'],
+    [0x0445, 'x'],
+    [0x043a, 'k'],
+    [0x043d, 'h'],
+    [0x0410, 'A'],
+    [0x0412, 'B'],
+    [0x0415, 'E'],
+    [0x041d, 'H'],
+    [0x041e, 'O'],
+    [0x041a, 'K'],
+    [0x041c, 'M'],
+    [0x0420, 'P'],
+    [0x0421, 'C'],
+    [0x0422, 'T'],
+    [0x0425, 'X'],
+    [0x03b1, 'a'],
+    [0x03b5, 'e'],
+    [0x03b9, 'i'],
+    [0x03bf, 'o'],
+    [0x03c1, 'p'],
+    [0x2071, 'i'],
+    [0x207f, 'n'],
+    [0x1d43, 'a'],
+    [0x1d47, 'b'],
+    [0x1d48, 'd'],
+    [0x1d49, 'e'],
+    [0x1d4d, 'g'],
+    [0x1d4f, 'k'],
+    [0x1d50, 'm'],
+    [0x1d52, 'o'],
+    [0x1d56, 'p'],
+    [0x1d57, 't'],
+    [0x1d58, 'u'],
+    [0x1d5b, 'v'],
+]);
+const FULLWIDTH_LO = 0xff01;
+const FULLWIDTH_HI = 0xff5e;
+const FULLWIDTH_OFFSET = 0xfee0;
+const COMBINING_LO = 0x0300;
+const COMBINING_HI = 0x036f;
+const MATH_ALPHA = [
+    [0x1d400, 0x1d41a],
+    [0x1d434, 0x1d44e],
+    [0x1d468, 0x1d482],
+    [0x1d49c, 0x1d4b6],
+    [0x1d4d0, 0x1d4ea],
+    [0x1d504, 0x1d51e],
+    [0x1d538, 0x1d552],
+    [0x1d56c, 0x1d586],
+    [0x1d5a0, 0x1d5ba],
+    [0x1d5d4, 0x1d5ee],
+    [0x1d608, 0x1d622],
+    [0x1d63c, 0x1d656],
+    [0x1d670, 0x1d68a],
+];
+const MATH_DIGIT = [0x1d7ce, 0x1d7d8, 0x1d7e2, 0x1d7ec, 0x1d7f6];
+const ALPHA_SIZE = 26;
+const DIGIT_SIZE = 10;
+const UPPER_A = 0x41;
+const LOWER_A = 0x61;
+const DIGIT_0 = 0x30;
+function mapMath(code) {
+    for (const [upper, lower] of MATH_ALPHA) {
+        if (code >= upper && code < upper + ALPHA_SIZE) {
+            return String.fromCodePoint(UPPER_A + code - upper);
+        }
+        if (code >= lower && code < lower + ALPHA_SIZE) {
+            return String.fromCodePoint(LOWER_A + code - lower);
+        }
+    }
+    for (const start of MATH_DIGIT) {
+        if (code >= start && code < start + DIGIT_SIZE) {
+            return String.fromCodePoint(DIGIT_0 + code - start);
+        }
+    }
+    return undefined;
+}
+const EMOJI = String.raw `(?:[\u{1F300}-\u{1FFFF}]|[\u{2600}-\u{27BF}]|[\u{FE00}-\u{FE0F}]|[\u{231A}-\u{23FF}])`;
+/** Emoji runs between two letters are dropped: `ig😀nore` reads `ignore`. */
+const EMOJI_BETWEEN = new RegExp(`(?<=[a-zA-Z])${EMOJI}+(?=[a-zA-Z])`, 'gu');
+const EMOJI_CHAR = new RegExp(`^${EMOJI}$`, 'u');
+const BACKSLASH_BEFORE_ALPHA = /\\(?=[a-zA-Z])/g;
+/** What one code point reads as: stripped, folded to ASCII, or itself. */
+function normalizeCodePoint(ch) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (STRIP_SET.has(code))
+        return '';
+    if (code >= COMBINING_LO && code <= COMBINING_HI)
+        return '';
+    if (code >= FULLWIDTH_LO && code <= FULLWIDTH_HI) {
+        return String.fromCodePoint(code - FULLWIDTH_OFFSET);
+    }
+    const math = mapMath(code);
+    if (math !== undefined)
+        return math;
+    const homo = HOMOGLYPH_MAP.get(code);
+    if (homo !== undefined)
+        return homo;
+    if (SPACE_SET.has(code))
+        return ' ';
+    return ch;
+}
+/** Whether a code point is one `EMOJI_BETWEEN` drops between letters. */
+function isEmoji(ch) {
+    return EMOJI_CHAR.test(ch);
+}
+function normalizeForDetection(text) {
+    let out = '';
+    for (const ch of text) {
+        out += normalizeCodePoint(ch);
+    }
+    return out.replace(EMOJI_BETWEEN, '').replace(BACKSLASH_BEFORE_ALPHA, '');
+}
+export { isEmoji, normalizeCodePoint, normalizeForDetection };

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

@@ -0,0 +1,19 @@
+import { type SensitiveSelection } from './sensitive.js';
+import type { ProfileGuardrailsSpec, ResolvedGuardrailPolicy, TrustLevel } from './types.js';
+export interface DetectionOptions {
+    sanitizeInput: boolean;
+    redactSensitive: SensitiveSelection;
+}
+/** Every ingress and egress path resolves through here so none can drift on what "unset" means. */
+declare function resolveGuardrailPolicy(spec: ProfileGuardrailsSpec | undefined): ResolvedGuardrailPolicy;
+/**
+ * Trusted text is author-time profile copy. Injection redaction would strip the
+ * host's own anti-injection instructions, and sensitive redaction would rewrite a
+ * prompt that legitimately shows a key or address format — so trusted text is
+ * passed to the provider verbatim. Trace safety does not depend on this: the trace
+ * writer redacts independently on every path.
+ *
+ * Assembled and untrusted text take whatever the profile enabled.
+ */
+declare function detectionForTrust(policy: ResolvedGuardrailPolicy, trust: TrustLevel): DetectionOptions;
+export { detectionForTrust, resolveGuardrailPolicy };

package/esm/src/guardrails/policy.js

@@ -0,0 +1,50 @@
+import { egressPolicy } from './egress-policy.js';
+import { resolveSensitive } from './sensitive.js';
+const NO_GROUPS = resolveSensitive(false);
+/** One enforce per spec, so the gates' per-enforce plans are built once. */
+const BUNDLED = new WeakMap();
+function resolveEgress(spec) {
+    if (!spec)
+        return undefined;
+    const { enforce, checks, ...rest } = spec;
+    if (enforce)
+        return { ...rest, enforce };
+    let bundled = BUNDLED.get(spec);
+    if (!bundled) {
+        bundled = egressPolicy({ bundled: checks ?? true });
+        BUNDLED.set(spec, bundled);
+    }
+    return { ...rest, enforce: bundled };
+}
+/** Every ingress and egress path resolves through here so none can drift on what "unset" means. */
+function resolveGuardrailPolicy(spec) {
+    return {
+        sanitizeInput: spec?.sanitizeInput ?? true,
+        redactSensitive: resolveSensitive(spec?.redactSensitive),
+        canary: spec?.canary ?? true,
+        promptEcho: spec?.promptEcho ?? true,
+        egress: resolveEgress(spec?.egress),
+        network: spec?.network,
+        quota: spec?.quota,
+        taint: spec?.taint,
+    };
+}
+/**
+ * Trusted text is author-time profile copy. Injection redaction would strip the
+ * host's own anti-injection instructions, and sensitive redaction would rewrite a
+ * prompt that legitimately shows a key or address format — so trusted text is
+ * passed to the provider verbatim. Trace safety does not depend on this: the trace
+ * writer redacts independently on every path.
+ *
+ * Assembled and untrusted text take whatever the profile enabled.
+ */
+function detectionForTrust(policy, trust) {
+    if (trust === 'trusted') {
+        return { sanitizeInput: false, redactSensitive: NO_GROUPS };
+    }
+    return {
+        sanitizeInput: policy.sanitizeInput,
+        redactSensitive: policy.redactSensitive,
+    };
+}
+export { detectionForTrust, resolveGuardrailPolicy };

package/esm/src/guardrails/progressive-yield.d.ts

@@ -0,0 +1,69 @@
+import type { EgressEnforcer, GuardrailContext, GuardrailHit, ResolvedGuardrailPolicy } from './types.js';
+/** Default lookback under a host `egress.enforce` the gate cannot read. */
+declare const DEFAULT_HOLDBACK = 256;
+/**
+ * Default lookback on Live under a host policy the gate cannot read, where the
+ * held transcript holds back audio too: the shortest that shows the host no
+ * character of any egress corpus match however the transcript is chunked
+ * (88), with a margin.
+ */
+declare const LIVE_DEFAULT_HOLDBACK = 96;
+export type ProgressiveYieldOk = {
+    blocked: false;
+    emit: string;
+};
+export type ProgressiveYieldBlocked = {
+    blocked: true;
+    hits: GuardrailHit[];
+};
+export type ProgressiveYieldResult = ProgressiveYieldOk | ProgressiveYieldBlocked;
+export interface ProgressiveYieldGateOptions {
+    /** Also carries the turn canary. */
+    context: GuardrailContext;
+    /** When set, each step runs this policy on the accumulated window before emit. */
+    enforce?: EgressEnforcer;
+    /**
+     * Lookback in characters under an `enforce` the gate cannot read (default
+     * `DEFAULT_HOLDBACK`). The bundled policy holds exactly and takes none: it
+     * is an error to set one with it. A tail that could start a canary leak is
+     * always held on top.
+     */
+    holdback?: number;
+    /**
+     * Text an earlier window of the same canary ended on that could still open a
+     * leak (`promptLeakCarry`). It is scanned in front of this window, never released
+     * again, so a token split across steps or cycles is still one match.
+     */
+    carry?: string;
+}
+/**
+ * Incremental outbound gate that scans accumulated output and releases only
+ * prefixes outside its retained lookback window.
+ */
+interface ProgressiveYieldGate {
+    process: (fragment: string) => Promise<ProgressiveYieldResult>;
+    flush: () => Promise<ProgressiveYieldResult>;
+    /** Full window inspected so far (for end-of-attempt egress / repair). */
+    accumulated: () => string;
+    /** Lookback tail not yet released to the host. Peek only. */
+    unreleased: () => string;
+    /**
+     * Take the tail not yet released and mark it released.
+     *
+     * Used when the runner records withheld text for the egress window: without
+     * advancing the cursor a later `flush` re-releases the same range and the
+     * attempt buffer ends up holding the text twice.
+     */
+    drainUnreleased: () => string;
+    /** The tail the next window of the same canary must scan in front of its own. */
+    carryOut: () => string;
+}
+/** Call `flush` when the stream ends to release the held tail. */
+declare function createProgressiveYieldGate(options: ProgressiveYieldGateOptions): ProgressiveYieldGate;
+/**
+ * Shared constructor for runTurn + Live: gate when canary and/or egress.enforce
+ * is active. `context.canary` is set only when the profile enabled canary minting.
+ */
+declare function createOutboundProgressiveGate(policy: ResolvedGuardrailPolicy, context: GuardrailContext, carry?: string): ProgressiveYieldGate | null;
+export type { ProgressiveYieldGate };
+export { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK, LIVE_DEFAULT_HOLDBACK, };