@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/network.js

@@ -0,0 +1,330 @@
+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,
+    (b0) => b0 === 127,
+    (b0) => b0 === 10,
+    (b0, b1) => b0 === 100 && b1 >= 64 && b1 <= 127,
+    (b0, b1) => b0 === 172 && b1 >= 16 && b1 <= 31,
+    (b0, b1) => b0 === 192 && b1 === 168,
+    (b0, b1) => b0 === 169 && b1 === 254,
+    (b0, b1, b2) => b0 === 192 && b1 === 0 && (b2 === 0 || b2 === 2),
+    (b0, b1) => b0 === 198 && (b1 === 18 || b1 === 19),
+    (b0, b1, b2) => b0 === 198 && b1 === 51 && b2 === 100,
+    (b0, b1, b2) => b0 === 203 && b1 === 0 && b2 === 113,
+    (b0) => b0 >= 224,
+];
+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);
+    });
+}
+/** True for loopback addresses and names reserved for local use: `localhost`, `.local`, `.internal`, `.lan`, `.home.arpa`, and `.localdomain`. */
+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]');
+}
+/** True when the IP address, or bracketed IPv6 host, is a private or local IPv4 or IPv6 address. */
+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}"`); // labels-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();
+    // invariant: 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.`); // labels-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 redirect = response.headers.get('location');
+        if (!options.followRedirects || !REDIRECT_STATUSES.has(response.status) || redirect === null) {
+            return response;
+        }
+        await response.body?.cancel();
+        if (hop === FETCH_REDIRECT_LIMIT) {
+            throw new TheoremError('network', `Too many redirects from "${url}"`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        target = await clearHop(new URL(redirect, 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,20 @@
+/** 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;
+/** `normalizeForDetection` of a text, and for each index of it the stretch of the text it stands for. */
+interface NormalizedView {
+    text: string;
+    /** Where in the text as written the character at each index starts. */
+    start: number[];
+    /** Where in the text as written the character at each index ends. */
+    end: number[];
+}
+/**
+ * `normalizeForDetection(text)` with its way back: a match in the normalized
+ * text is placed on the characters of `text` it was read from.
+ */
+declare function normalizedView(text: string): NormalizedView;
+export type { NormalizedView };
+export { isEmoji, normalizeCodePoint, normalizedView, normalizeForDetection };

package/esm/src/guardrails/normalize.js

@@ -0,0 +1,165 @@
+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, '');
+}
+function withoutMatches(view, pattern) {
+    const kept = { text: '', start: [], end: [] };
+    let last = 0;
+    const keep = (to) => {
+        kept.text += view.text.slice(last, to);
+        kept.start.push(...view.start.slice(last, to));
+        kept.end.push(...view.end.slice(last, to));
+    };
+    for (const match of view.text.matchAll(pattern)) {
+        keep(match.index);
+        last = match.index + match[0].length;
+    }
+    keep(view.text.length);
+    return kept;
+}
+/**
+ * `normalizeForDetection(text)` with its way back: a match in the normalized
+ * text is placed on the characters of `text` it was read from.
+ */
+function normalizedView(text) {
+    const view = { text: '', start: [], end: [] };
+    let at = 0;
+    for (const ch of text) {
+        const folded = normalizeCodePoint(ch);
+        for (let i = 0; i < folded.length; i += 1) {
+            view.start.push(at);
+            view.end.push(at + ch.length);
+        }
+        view.text += folded;
+        at += ch.length;
+    }
+    return withoutMatches(withoutMatches(view, EMOJI_BETWEEN), BACKSLASH_BEFORE_ALPHA);
+}
+export { isEmoji, normalizeCodePoint, normalizedView, normalizeForDetection };

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

@@ -0,0 +1,4 @@
+import type { ProfileGuardrailsSpec, ResolvedGuardrailPolicy } from './types.js';
+/** Every ingress and egress path resolves through here so none can drift on what "unset" means. */
+declare function resolveGuardrailPolicy(spec: ProfileGuardrailsSpec | undefined): ResolvedGuardrailPolicy;
+export { resolveGuardrailPolicy };

package/esm/src/guardrails/policy.js

@@ -0,0 +1,21 @@
+import { resolveAllow, resolveDetect } from './detectors.js';
+/** A blocked reply is rewritten once unless the profile says otherwise. */
+const BLOCKED_REPLY = { onBlock: 'retry', maxRetries: 1 };
+function resolveBlockedReply(spec) {
+    return {
+        onBlock: spec?.onBlock ?? BLOCKED_REPLY.onBlock,
+        maxRetries: spec?.maxRetries ?? BLOCKED_REPLY.maxRetries,
+    };
+}
+/** Every ingress and egress path resolves through here so none can drift on what "unset" means. */
+function resolveGuardrailPolicy(spec) {
+    return {
+        detect: resolveDetect(spec?.detect),
+        allow: resolveAllow(spec?.detect),
+        blockedReply: resolveBlockedReply(spec?.blockedReply),
+        network: spec?.network,
+        quota: spec?.quota,
+        taint: spec?.taint,
+    };
+}
+export { resolveGuardrailPolicy };

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

@@ -0,0 +1,110 @@
+import type { Boundary, ToolBoundary } from './boundaries.js';
+import { type Detection, type DetectScope } from './detect-at.js';
+import type { ResolvedDetect } from './detectors.js';
+import type { GuardrailContext, GuardrailHit, ResolvedGuardrailPolicy } from './types.js';
+/** A reply boundary the gate reads as the reply streams. */
+export type ReplyBoundary = Extract<Boundary, 'reply' | 'live_reply'>;
+/** Where a draft is read: where the whole it previews is (a tool call, a tool's output, a structured reply). */
+export type DraftBoundary = ToolBoundary | Extract<Boundary, 'reply_structured'>;
+/** Where a gate stands: a reply boundary, or a draft's. */
+export type GateBoundary = ReplyBoundary | DraftBoundary;
+export type ProgressiveYieldOk = {
+    blocked: false;
+    emit: string;
+    /** What `guardrails.detect` reported or replaced in `emit`. */
+    found?: Pick<Detection, 'action' | 'hits'>;
+};
+export type ProgressiveYieldBlocked = {
+    blocked: true;
+    hits: GuardrailHit[];
+    /** Set when a detector stopped the reply: the boundary it was read at. */
+    boundary?: GateBoundary;
+};
+/** What one step of the progressive gate returns: the text to emit, or the hits that block the reply. */
+export type ProgressiveYieldResult = ProgressiveYieldOk | ProgressiveYieldBlocked;
+/** Settings for the progressive gate: the guardrail context, the detectors it reads with, and the carry from the window before. */
+export interface ProgressiveYieldGateOptions {
+    /** Also carries the turn canary. */
+    context: GuardrailContext;
+    /**
+     * `guardrails.detect` and the reply boundary this gate stands at. With
+     * `rewrite`, a match set to `redact` is replaced as the text is released;
+     * without it (Live, where the text is the transcript of audio already held)
+     * the gate stops there and the cycle's verdict replaces the reply.
+     */
+    detect?: {
+        matrix: ResolvedDetect;
+        boundary: GateBoundary;
+        rewrite: boolean;
+        /** What the detectors read against (`scopeOf`). Left out, the URL and marker detectors read with none. */
+        scope?: DetectScope;
+    };
+    /**
+     * 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) => ProgressiveYieldResult;
+    flush: () => 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): Promise<ProgressiveYieldGate>;
+/**
+ * Whether a reply read at `boundaries` gets a verdict once it has ended: a
+ * detector reads one of them. A gate that stops such a reply withholds it for
+ * that verdict.
+ */
+declare function replyIsJudged(policy: ResolvedGuardrailPolicy, boundaries: readonly Boundary[], scope?: DetectScope): boolean;
+/**
+ * Shared constructor for runTurn + Live: a gate when a detector reads
+ * `boundary`. `context.canary` is set only while `canary_leak` is above
+ * `ignore` somewhere, and `context.privateSystem` while `prompt_leak` is.
+ */
+declare function createOutboundProgressiveGate(policy: ResolvedGuardrailPolicy, context: GuardrailContext, boundary: ReplyBoundary, carry?: string): Promise<ProgressiveYieldGate | null>;
+/** `createOutboundProgressiveGate`, once the automata are loaded. */
+declare function outboundProgressiveGate(policy: ResolvedGuardrailPolicy, context: GuardrailContext, boundary: ReplyBoundary, carry?: string): ProgressiveYieldGate | null;
+/**
+ * A gate for a draft read at `boundary`, where the whole it previews is read before the host sees
+ * it: a tool call the model is still writing, a tool's output as the tool writes it, or a
+ * structured reply's JSON as the model writes it. It never
+ * rewrites: a match the whole's check would replace or stop stops the draft instead, because the
+ * host gets the whole only as that check leaves it. `scope` is what that check reads against;
+ * left out, the turn's (`scopeOf`).
+ */
+declare function createDraftGate(policy: ResolvedGuardrailPolicy, context: GuardrailContext, boundary: DraftBoundary, scope?: DetectScope): Promise<ProgressiveYieldGate | null>;
+/**
+ * One stream of drafts read through one draft gate, opened on the first draft. A match stops
+ * the rest of the stream; with no gate (nothing is judged there), every draft passes as is.
+ */
+declare class DraftReader {
+    private readonly open;
+    private gate;
+    constructor(open: () => Promise<ProgressiveYieldGate | null>);
+    /** What of `text` may be shown now: empty while the gate holds it, or once a match stopped the stream. */
+    read(text: string): Promise<string>;
+    /** The tail the gate still holds, once the stream has ended. */
+    end(): string;
+}
+export type { ProgressiveYieldGate };
+export { createDraftGate, createOutboundProgressiveGate, createProgressiveYieldGate, DraftReader, outboundProgressiveGate, replyIsJudged, };