@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/guardrails/live-outbound-gate.js

@@ -0,0 +1,305 @@
+import { isStreamedCanaryEvent } from './canary.js';
+import { eventPromptLeakHits, isPromptLeakHit, promptLeakReason, runEnforcer, WITHHELD_REASON, } from './egress.js';
+import { streamPlanOf } from './egress-stream.js';
+import { TheoremError } from './error.js';
+import { guardrailFromHits, guardrailFromVerdict } from './events.js';
+import { lexiconText } from './lexicon.js';
+import { resolveGuardrailPolicy } from './policy.js';
+import { createOutboundProgressiveGate, LIVE_DEFAULT_HOLDBACK, } from './progressive-yield.js';
+import { thoughtGuardFor } from './thought-guard.js';
+const UNTRANSCRIBED_HIT = { rule: 'live.untranscribed-audio', severity: 'high' };
+function egressSpec(session) {
+    return session.policy.egress;
+}
+/**
+ * The policy with Live's shorter default lookback when a host enforcer set
+ * none: every held character of transcript holds its audio. The bundled policy
+ * holds exactly and takes no lookback.
+ */
+function liveHoldback(policy) {
+    if (!policy.egress ||
+        policy.egress.holdback !== undefined ||
+        streamPlanOf(policy.egress.enforce)) {
+        return policy;
+    }
+    return { ...policy, egress: { ...policy.egress, holdback: LIVE_DEFAULT_HOLDBACK } };
+}
+/** A canary is attached only when the profile policy enables it and the caller supplied a token. */
+function createLiveOutboundGateSession(profile, canary, privateSystem, givenUrls) {
+    const policy = liveHoldback(resolveGuardrailPolicy(profile.guardrails));
+    const useCanary = policy.canary && Boolean(canary);
+    const context = {
+        stage: 'live_outbound',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...(useCanary ? { canary } : {}),
+        // The system prompt is guarded against echo alongside the canary that binds it.
+        ...(useCanary && policy.promptEcho && privateSystem?.length ? { privateSystem } : {}),
+        ...(profile.lexicon ? { lexicon: profile.lexicon } : {}),
+        ...(givenUrls ? { givenUrls } : {}),
+    };
+    const thoughts = thoughtGuardFor(policy.egress?.enforce, context);
+    return {
+        policy,
+        context,
+        gate: createOutboundProgressiveGate(policy, context),
+        held: [],
+        releasedTo: 0,
+        withholdVisible: false,
+        ...(thoughts ? { thoughts } : {}),
+    };
+}
+function resetCycle(session) {
+    const carry = session.gate?.carryOut();
+    session.gate = createOutboundProgressiveGate(session.policy, session.context, carry);
+    session.held = [];
+    session.releasedTo = 0;
+    session.withholdVisible = false;
+    session.promptLeaks = undefined;
+}
+/** Canary-only profiles stop the turn immediately; egress profiles defer to finalize. */
+function canaryOnlyImmediateWithhold(session) {
+    return !egressSpec(session)?.enforce;
+}
+function withholdResult(reason, hits, prior = []) {
+    const guardrail = guardrailFromHits('live_outbound', 'untrusted', hits, 'block');
+    return {
+        action: 'withhold',
+        error: new TheoremError('safety', reason),
+        events: [...prior, ...(guardrail ? [guardrail] : [])],
+    };
+}
+/** Window offset the gate has cleared for release. */
+function clearedTo(gate) {
+    return gate.accumulated().length - gate.unreleased().length;
+}
+/**
+ * Release held output up to window offset `to`: reply chunks as far as they
+ * reach, media once the transcript covering it is cleared — or all of it when
+ * the transcript is whole. Stops at the first item that cannot go yet, so the
+ * host sees output in arrival order.
+ */
+function releaseHeld(session, gate, to, into, transcriptWhole = false) {
+    const window = gate.accumulated();
+    for (let item = session.held[0]; item !== undefined; item = session.held[0]) {
+        const { event } = item;
+        if (event.type !== 'media') {
+            const from = Math.max(item.start, session.releasedTo);
+            const upTo = Math.min(item.end, to);
+            if (upTo > from) {
+                into.push({ ...event, text: window.slice(from, upTo) });
+                session.releasedTo = upTo;
+            }
+        }
+        if (item.end > to && !(transcriptWhole && event.type === 'media')) {
+            return;
+        }
+        if (event.type === 'media') {
+            into.push(event);
+        }
+        session.held.shift();
+    }
+}
+/**
+ * Apply a progressive scan result. Clean: release what the gate cleared.
+ * Blocked: canary-only withholds the session; egress withholds the rest of
+ * the cycle and reports the hit. `undefined` means keep going.
+ */
+function applyScan(session, gate, result, into) {
+    if (!result.blocked) {
+        releaseHeld(session, gate, clearedTo(gate), into);
+        return undefined;
+    }
+    if (canaryOnlyImmediateWithhold(session)) {
+        return withholdResult(promptLeakReason(result.hits), result.hits, into);
+    }
+    const leaks = result.hits.filter(isPromptLeakHit);
+    if (leaks.length > 0) {
+        session.promptLeaks = leaks;
+    }
+    session.withholdVisible = true;
+    const guardrail = guardrailFromHits('live_outbound', 'untrusted', result.hits, 'block');
+    if (guardrail) {
+        into.push(guardrail);
+    }
+    return undefined;
+}
+/** Scan and release everything held (a non-reply event, or the end of the cycle). */
+async function flushHeld(session, gate, into) {
+    if (session.withholdVisible || session.held.length === 0) {
+        return undefined;
+    }
+    return applyScan(session, gate, await gate.flush(), into);
+}
+/** Media waits behind the reply before it, so speech is heard only after its transcript clears the scan. */
+function holdMedia(session, gate, event, transcribed) {
+    const at = gate.accumulated().length;
+    session.held.push({ event, start: at, end: transcribed ? at : Number.POSITIVE_INFINITY });
+}
+/** The media still waiting for a transcript chunk is covered by this one. */
+function coverMedia(session, end) {
+    for (let i = session.held.length - 1; i >= 0; i -= 1) {
+        const item = session.held[i];
+        if (item === undefined || item.end !== Number.POSITIVE_INFINITY) {
+            return;
+        }
+        item.end = end;
+    }
+}
+async function holdStreamChunk(session, gate, event, into) {
+    const text = event.text ?? '';
+    if (!text) {
+        return undefined;
+    }
+    const start = gate.accumulated().length;
+    coverMedia(session, start + text.length);
+    session.held.push({ event, start, end: start + text.length });
+    const result = await gate.process(text);
+    if (session.withholdVisible) {
+        // Keep feeding the window so finalize judges the whole cycle.
+        return undefined;
+    }
+    return applyScan(session, gate, result, into);
+}
+async function processLiveOutboundBatch(session, events) {
+    const toEmit = [];
+    const { gate } = session;
+    if (!gate) {
+        return emitOrIdle(events);
+    }
+    // One batch is one provider message: its transcript is its audio's.
+    let transcribed = false;
+    for (const event of events) {
+        if (isStreamedCanaryEvent(event)) {
+            transcribed ||= Boolean(event.text);
+            const stopped = await holdStreamChunk(session, gate, event, toEmit);
+            if (stopped) {
+                return stopped;
+            }
+            continue;
+        }
+        if (event.type === 'media') {
+            holdMedia(session, gate, event, transcribed);
+            // Media not yet held until the next event can release it now.
+            if (!session.withholdVisible)
+                releaseHeld(session, gate, clearedTo(gate), toEmit);
+            continue;
+        }
+        const stopped = await flushHeld(session, gate, toEmit);
+        if (stopped) {
+            return stopped;
+        }
+        if (isGenerationComplete(event)) {
+            releaseSpoken(session, gate, toEmit);
+        }
+        const leaks = session.context.canary
+            ? eventPromptLeakHits(event, session.context.canary, session.context.privateSystem)
+            : [];
+        if (leaks.length > 0) {
+            return withholdResult(promptLeakReason(leaks), leaks, toEmit);
+        }
+        if (event.type === 'thought' && session.thoughts) {
+            toEmit.push(...thoughtEvents(session.thoughts.push(event.text), event));
+            continue;
+        }
+        toEmit.push(event);
+    }
+    return emitOrIdle(toEmit);
+}
+/** What a thought guard released, after the event saying what it omitted from it. */
+function thoughtEvents({ text, hits }, event) {
+    const guardrail = guardrailFromHits('thought', 'untrusted', hits, 'redact');
+    return [...(guardrail ? [guardrail] : []), ...(text ? [{ ...event, text }] : [])];
+}
+function isGenerationComplete(event) {
+    return event.type === 'done' && event.stop?.kind === 'generation_complete';
+}
+/**
+ * The model finished speaking: its transcript is whole and cleared, so the
+ * audio after its last chunk goes too. A cycle with no transcript keeps its
+ * audio for `dropUntranscribed`; a withheld cycle keeps it for the verdict.
+ */
+function releaseSpoken(session, gate, into) {
+    const whole = gate.accumulated().length;
+    if (session.withholdVisible || whole === 0 || clearedTo(gate) < whole) {
+        return;
+    }
+    releaseHeld(session, gate, whole, into, true);
+}
+function emitOrIdle(events) {
+    return events.length === 0 ? { action: 'idle' } : { action: 'emit', events };
+}
+/**
+ * Live has no repair loop. Allow releases what is still held; redact and refuse replace it with
+ * text (held audio is dropped); block withholds it as a `safety` error.
+ */
+async function finalEgressVerdict(session, gate, egress, prior) {
+    // The host policy adds checks; it never releases a system-prompt leak.
+    const leaks = session.promptLeaks;
+    const verdict = leaks
+        ? { action: 'block', hits: leaks, rejection: WITHHELD_REASON.egress }
+        : await runEnforcer(egress.enforce, { text: gate.accumulated() }, session.context);
+    const guardrail = guardrailFromVerdict('live_outbound', 'untrusted', verdict);
+    const events = [...prior, ...(guardrail ? [guardrail] : [])];
+    if (verdict.action === 'redact') {
+        return { action: 'emit', events: [...events, { type: 'text', text: verdict.text }] };
+    }
+    if (verdict.action === 'block') {
+        if (egress.onBlock === 'refuse_to_user') {
+            const text = lexiconText('egress.refusal', {}, session.context.lexicon);
+            return { action: 'emit', events: [...events, { type: 'text', text }] };
+        }
+        return withholdResult(WITHHELD_REASON.egress, verdict.hits, prior);
+    }
+    releaseHeld(session, gate, gate.accumulated().length, events, true);
+    return emitOrIdle(events);
+}
+/**
+ * A cycle that held audio but produced no transcript: nothing checked the
+ * audio, so it is dropped and reported, never released.
+ */
+function dropUntranscribed(session, events) {
+    if (session.held.length === 0) {
+        return events;
+    }
+    const guardrail = guardrailFromHits('live_outbound', 'untrusted', [UNTRANSCRIBED_HIT], 'block');
+    return guardrail ? [...events, guardrail] : events;
+}
+async function finalizeCycle(session, gate) {
+    const events = [];
+    const stopped = await flushHeld(session, gate, events);
+    if (stopped) {
+        return stopped;
+    }
+    if (!gate.accumulated()) {
+        return emitOrIdle(dropUntranscribed(session, events));
+    }
+    const egress = egressSpec(session);
+    if (egress) {
+        return await finalEgressVerdict(session, gate, egress, events);
+    }
+    releaseHeld(session, gate, gate.accumulated().length, events, true);
+    return emitOrIdle(events);
+}
+/** Call once after the provider has finished the cycle; it also starts the next one. */
+async function finalizeLiveOutboundTurn(session) {
+    if (!session.gate) {
+        return { action: 'idle' };
+    }
+    const thought = session.thoughts
+        ? thoughtEvents(session.thoughts.flush(), { type: 'thought', text: '' })
+        : [];
+    const result = await finalizeCycle(session, session.gate);
+    resetCycle(session);
+    if (thought.length === 0)
+        return result;
+    if (result.action === 'idle')
+        return { action: 'emit', events: thought };
+    return { ...result, events: [...thought, ...(result.events ?? [])] };
+}
+/** Drop the cycle's held output when the user interrupts mid-turn. */
+function abortLiveOutboundTurn(session) {
+    session.thoughts?.flush();
+    resetCycle(session);
+}
+export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, };

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

@@ -0,0 +1,46 @@
+/**
+ * Inbound and outbound guardrail primitives: sanitization, injection and sensitive detection,
+ * canary egress gates, egress policy and public error mapping. App-specific policy copy stays host-owned.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { CanaryGateResult, CanaryStreamGate } from './canary.js';
+export { bindCanary, createCanaryStreamGate, eventHasCanary, isStreamedCanaryEvent, mintCanary, OMIT_CANARY, redactCanary, scanTextForCanaryLeak, USER_CLOSE, USER_OPEN, wrapUserData, } from './canary.js';
+export type { CanaryGateSession } from './canary-gate.js';
+export { createCanaryGateSession, filterCanaryGatedEvents } from './canary-gate.js';
+export type { EgressChecks, UrlCheck } from './egress.js';
+export { collectEgressHits, hitRules, runEnforcer, standardEgressEnforce, } from './egress.js';
+export type { EgressPolicyOptions } from './egress-policy.js';
+export { egressPolicy } from './egress-policy.js';
+export type { CompiledEgressRules, EgressRule } from './egress-rules.js';
+export type { GivenUrls } from './egress-urls.js';
+export type { ErrorCopies, ErrorCopy, ErrorKind, TheoremErrorOptions } from './error.js';
+export { describeError, ERROR_KINDS, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicWording, } from './error.js';
+export { errorCopiesSchema, errorKindSchema, guardrailEventSchema } from './event-schemas.js';
+export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent, } from './events.js';
+export { hitFromSpan, projectGuardrailEvent, } from './hits.js';
+export { injectionSpans } from './injection.js';
+export type { ClientLexiconKey, LexiconKey, LexiconOverrides, LexiconParams } from './lexicon.js';
+export { CLIENT_LEXICON_KEYS, LEXICON_KEYS, lexiconDefault, lexiconText, overrideLexicon, resetLexicon, } from './lexicon.js';
+export type { LiveHeldOutput, LiveOutboundBatchResult, LiveOutboundGateSession, } from './live-outbound-gate.js';
+export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from './live-outbound-gate.js';
+export type { DetectionOptions } from './policy.js';
+export { detectionForTrust, resolveGuardrailPolicy } from './policy.js';
+export type { ProgressiveYieldGate, ProgressiveYieldGateOptions, ProgressiveYieldResult, } from './progressive-yield.js';
+export { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK, LIVE_DEFAULT_HOLDBACK, } from './progressive-yield.js';
+export { PROMPT_ECHO_WORDS, scanTextForPromptEcho } from './prompt-echo.js';
+export type { QuotaSlotStatus } from './quota.js';
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
+export type { GuardrailRule } from './rules.js';
+export { DIRECTIVE_RULES, EGRESS_RULES, NETWORK_RULES, SANITIZE_RULES, TOOL_RULES, } from './rules.js';
+export { detectionForProfile, detectText, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, } from './sanitize.js';
+export type { SensitiveGroup, SensitiveGroups, SensitiveSelection, SensitiveSwitches, } from './sensitive.js';
+export { SENSITIVE_GROUPS, sensitiveSpans } from './sensitive.js';
+export type { ScanText } from './serialize.js';
+export { scanTextOf, textForScan } from './serialize.js';
+export { advisoryLevel, directiveHits, looksDirective, } from './tool-directives.js';
+export type { GuardedToolText } from './tool-result.js';
+export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, } from './tool-result.js';
+export type { AdvisoryLevel, EgressEnforcer, EgressOnBlock, GuardrailAction, GuardrailContext, GuardrailEvent, GuardrailHit, GuardrailStage, HostGuardrailsSpec, NetworkGuardrailSpec, OutboundPayload, ProfileEgressSpec, ProfileGuardrailsSpec, Provenance, QuotaGuardrailSpec, ResolvedEgressSpec, ResolvedGuardrailPolicy, Severity, TaintGate, TaintGuardrailSpec, ToolOrigin, TrustLevel, TurnTaint, Verdict, } from './types.js';
+export { ADVISORY_LEVELS, EGRESS_ON_BLOCK, GUARDRAIL_STAGES, SEVERITIES, TAINT_GATES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';

package/esm/src/guardrails/mod.js

@@ -0,0 +1,29 @@
+/**
+ * Inbound and outbound guardrail primitives: sanitization, injection and sensitive detection,
+ * canary egress gates, egress policy and public error mapping. App-specific policy copy stays host-owned.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { bindCanary, createCanaryStreamGate, eventHasCanary, isStreamedCanaryEvent, mintCanary, OMIT_CANARY, redactCanary, scanTextForCanaryLeak, USER_CLOSE, USER_OPEN, wrapUserData, } from './canary.js';
+export { createCanaryGateSession, filterCanaryGatedEvents } from './canary-gate.js';
+export { collectEgressHits, hitRules, runEnforcer, standardEgressEnforce, } from './egress.js';
+export { egressPolicy } from './egress-policy.js';
+export { describeError, ERROR_KINDS, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicWording, } from './error.js';
+export { errorCopiesSchema, errorKindSchema, guardrailEventSchema } from './event-schemas.js';
+export { guardrailFromHits, guardrailFromVerdict, guardrailTurnEvent, projectGuardrailTurnEvent, } from './events.js';
+export { hitFromSpan, projectGuardrailEvent, } from './hits.js';
+export { injectionSpans } from './injection.js';
+export { CLIENT_LEXICON_KEYS, LEXICON_KEYS, lexiconDefault, lexiconText, overrideLexicon, resetLexicon, } from './lexicon.js';
+export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from './live-outbound-gate.js';
+export { detectionForTrust, resolveGuardrailPolicy } from './policy.js';
+export { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK, LIVE_DEFAULT_HOLDBACK, } from './progressive-yield.js';
+export { PROMPT_ECHO_WORDS, scanTextForPromptEcho } from './prompt-echo.js';
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
+export { DIRECTIVE_RULES, EGRESS_RULES, NETWORK_RULES, SANITIZE_RULES, TOOL_RULES, } from './rules.js';
+export { detectionForProfile, detectText, redactSensitiveOnly, sanitizeHistory, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, } from './sanitize.js';
+export { SENSITIVE_GROUPS, sensitiveSpans } from './sensitive.js';
+export { scanTextOf, textForScan } from './serialize.js';
+export { advisoryLevel, directiveHits, looksDirective, } from './tool-directives.js';
+export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, TOOL_CLOSE, toolCallEvent, wrapToolData, } from './tool-result.js';
+export { ADVISORY_LEVELS, EGRESS_ON_BLOCK, GUARDRAIL_STAGES, SEVERITIES, TAINT_GATES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';

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

@@ -0,0 +1,42 @@
+import type { NetworkGuardrailSpec } from './types.js';
+export declare function isLocalhostName(hostname: string): boolean;
+export declare function isPrivateOrLocalAddress(ipOrHost: string): boolean;
+/** Throws a `TheoremError` when the URL is blocked. */
+export declare function assertSafeUrl(urlStr: string, policy?: NetworkGuardrailSpec): URL;
+export interface GuardedFetchOptions {
+    policy?: NetworkGuardrailSpec;
+    /** Follow redirects, clearing each hop; when false a redirect comes back as the response. */
+    followRedirects: boolean;
+    /**
+     * Headers for the first request's origin only: credentials and host-configured
+     * headers. Once a redirect leaves that origin they are never sent again.
+     */
+    originBoundHeaders?: Record<string, string>;
+    /**
+     * Resolves each hop's host name before it is fetched; the hop is refused when
+     * any address is private or the name does not resolve. Skipped for literal
+     * addresses and wherever `policy` already permits private targets.
+     */
+    resolveHost?: ResolveHost;
+    fetchFn?: typeof fetch;
+    /** Told how long each hop's checks took: its address, and its lookup when `resolveHost` is set. */
+    onCheck?: (ms: number) => void;
+}
+/** A host name's IPv4 and IPv6 addresses; empty when the name does not exist. */
+export type ResolveHost = (hostname: string, signal?: AbortSignal) => Promise<readonly string[]>;
+/** Every redirect hop must clear `policy`; throws a `TheoremError` (`blocked`) when one is refused. */
+export declare function fetchGuarded(url: string, init: Omit<RequestInit, 'redirect' | 'body'> & {
+    body?: string;
+}, options: GuardedFetchOptions): Promise<Response>;
+export interface DnsOverHttpsOptions {
+    /** A DNS JSON API endpoint, e.g. `https://cloudflare-dns.com/dns-query`. */
+    endpoint: string;
+    fetchFn?: typeof fetch;
+}
+/**
+ * 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 declare function dnsOverHttpsResolver(options: DnsOverHttpsOptions): ResolveHost;