@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/live-outbound-gate.d.ts

@@ -0,0 +1,55 @@
+import type { TurnEventOf } from '../kernel/turn-events.js';
+import type { Profile, TurnEvent } from '../kernel/types.js';
+import { type StreamedReplyEvent } from './canary.js';
+import type { GivenUrls } from './egress-urls.js';
+import { TheoremError } from './error.js';
+import { type ProgressiveYieldGate } from './progressive-yield.js';
+import { type ThoughtGuard } from './thought-guard.js';
+import type { OwnTools } from './tool-leak.js';
+import type { GuardrailContext, GuardrailHit, ResolvedGuardrailPolicy } from './types.js';
+/**
+ * One piece of output not yet released: a reply-stream chunk covering
+ * `[start, end)` of the gate's window, or media arriving at `start`, whose
+ * `end` is where its covering transcript ends (`Infinity` until one arrives).
+ */
+export interface LiveHeldOutput {
+    event: StreamedReplyEvent | TurnEventOf<'media'>;
+    start: number;
+    end: number;
+}
+/** The gate's state for one live session: its policy and context, the progressive gate, the output held, and how far reply text has been released. */
+export interface LiveOutboundGateSession {
+    policy: ResolvedGuardrailPolicy;
+    context: GuardrailContext;
+    gate: ProgressiveYieldGate | null;
+    /** Reply chunks and media not yet released, in arrival order. */
+    held: LiveHeldOutput[];
+    /** Window offset the host has received reply text up to. */
+    releasedTo: number;
+    /** Stop releasing held output after a progressive egress hit. */
+    withholdVisible: boolean;
+    /** System-prompt leaks this cycle withheld. They pin the cycle's final verdict to block. */
+    promptLeaks?: GuardrailHit[];
+    /** Omits what in the session's thoughts leaks; carries from one cycle to the next. */
+    thoughts?: ThoughtGuard;
+}
+/** What the gate does with a batch of a live model's events: `emit` what is released, `withhold` with an error, or stay `idle` when nothing is released yet. */
+export type LiveOutboundBatchResult = {
+    action: 'emit';
+    events: TurnEvent[];
+} | {
+    action: 'withhold';
+    error: TheoremError;
+    events?: TurnEvent[];
+} | {
+    action: 'idle';
+};
+/** The canary and the system instruction are read for only while their detectors read somewhere (`scopeOf`). */
+declare function createLiveOutboundGateSession(profile: Profile, canary?: string, privateSystem?: readonly string[], givenUrls?: GivenUrls, ownTools?: OwnTools): Promise<LiveOutboundGateSession>;
+/** Passes one provider message's events through the outbound gate: reply text and audio are held until the egress checks clear them, a prompt leak, or egress hit withholds, and thoughts go through the thought guard. */
+declare function processLiveOutboundBatch(session: LiveOutboundGateSession, events: TurnEvent[]): LiveOutboundBatchResult;
+/** Call once after the provider has finished the cycle; it also starts the next one. */
+declare function finalizeLiveOutboundTurn(session: LiveOutboundGateSession): LiveOutboundBatchResult;
+/** Drop the cycle's held output when the user interrupts mid-turn. */
+declare function abortLiveOutboundTurn(session: LiveOutboundGateSession): void;
+export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, };

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

@@ -0,0 +1,298 @@
+import { isStreamedCanaryEvent } from './canary.js';
+import { detectEvent, leakScopeOf, scopeOf } from './detect-at.js';
+import { readReply, refusalAfter, replyAfter, standingBlock } from './detect-reply.js';
+import { eventLeak, isPromptLeakHit, promptLeakReason, WITHHELD_REASON } from './egress.js';
+import { TheoremError } from './error.js';
+import { guardrailFromHits, guardrailTurnEvent } from './events.js';
+import { resolveGuardrailPolicy } from './policy.js';
+import { createOutboundProgressiveGate, outboundProgressiveGate, } from './progressive-yield.js';
+import { thoughtGuardFor } from './thought-guard.js';
+const UNTRANSCRIBED_HIT = { rule: 'live.untranscribed-audio', severity: 'high' };
+/** The canary and the system instruction are read for only while their detectors read somewhere (`scopeOf`). */
+async function createLiveOutboundGateSession(profile, canary, privateSystem, givenUrls, ownTools) {
+    const policy = resolveGuardrailPolicy(profile.guardrails);
+    const context = {
+        stage: 'live_outbound',
+        trust: 'untrusted',
+        profileId: profile.id,
+        ...leakScopeOf(policy.detect, { canary, privateSystem }),
+        ...(profile.labels ? { labels: profile.labels } : {}),
+        ...(givenUrls ? { givenUrls } : {}),
+        ...(ownTools ? { ownTools } : {}),
+    };
+    const thoughts = await thoughtGuardFor(policy, context);
+    return {
+        policy,
+        context,
+        gate: await createOutboundProgressiveGate(policy, context, 'live_reply'),
+        held: [],
+        releasedTo: 0,
+        withholdVisible: false,
+        ...(thoughts ? { thoughts } : {}),
+    };
+}
+function resetCycle(session) {
+    const carry = session.gate?.carryOut();
+    session.gate = outboundProgressiveGate(session.policy, session.context, 'live_reply', carry);
+    session.held = [];
+    session.releasedTo = 0;
+    session.withholdVisible = false;
+    session.promptLeaks = undefined;
+}
+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: the rest of the cycle is withheld for its verdict.
+ */
+function applyScan(session, gate, result, into) {
+    if (!result.blocked) {
+        const found = result.found && detectEvent('live_reply', result.found);
+        if (found)
+            into.push(guardrailTurnEvent(found));
+        releaseHeld(session, gate, clearedTo(gate), into);
+        return;
+    }
+    const leaks = result.hits.filter(isPromptLeakHit);
+    if (leaks.length > 0) {
+        session.promptLeaks = leaks;
+    }
+    session.withholdVisible = true;
+    // why: A detector's stop is reported once, by the verdict on the whole reply.
+    const guardrail = result.boundary
+        ? undefined
+        : guardrailFromHits('live_outbound', 'untrusted', result.hits, 'block');
+    if (guardrail) {
+        into.push(guardrail);
+    }
+}
+/** Scan and release everything held (a non-reply event, or the end of the cycle). */
+function flushHeld(session, gate, into) {
+    if (session.withholdVisible || session.held.length === 0) {
+        return;
+    }
+    applyScan(session, gate, 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;
+    }
+}
+function holdStreamChunk(session, gate, event, into) {
+    const text = event.text ?? '';
+    if (!text) {
+        return;
+    }
+    const start = gate.accumulated().length;
+    coverMedia(session, start + text.length);
+    session.held.push({ event, start, end: start + text.length });
+    const result = gate.process(text);
+    // why: A withheld cycle keeps feeding the window so finalize judges the whole of it.
+    if (!session.withholdVisible)
+        applyScan(session, gate, result, into);
+}
+/** Passes one provider message's events through the outbound gate: reply text and audio are held until the egress checks clear them, a prompt leak, or egress hit withholds, and thoughts go through the thought guard. */
+function processLiveOutboundBatch(session, events) {
+    const toEmit = [];
+    const { gate } = session;
+    if (!gate) {
+        // why: Nothing reads the reply, but a thought is read at its own boundary.
+        const { thoughts } = session;
+        if (!thoughts)
+            return emitOrIdle(events);
+        return emitOrIdle(events.flatMap((event) => event.type === 'thought' ? thoughtEvents(thoughts.push(event.text), event) : [event]));
+    }
+    // why: 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);
+            holdStreamChunk(session, gate, event, toEmit);
+            continue;
+        }
+        if (event.type === 'media') {
+            holdMedia(session, gate, event, transcribed);
+            // why: Media not yet held until the next event can release it now.
+            if (!session.withholdVisible)
+                releaseHeld(session, gate, clearedTo(gate), toEmit);
+            continue;
+        }
+        flushHeld(session, gate, toEmit);
+        if (isGenerationComplete(event)) {
+            releaseSpoken(session, gate, toEmit);
+        }
+        // why: The model's tool call is read at its `tool_arguments` boundary.
+        const leak = event.type === 'tool'
+            ? undefined
+            : eventLeak(event, session.context, session.policy.detect, 'live_reply');
+        if (leak?.stop) {
+            return withholdResult(promptLeakReason(leak.hits), leak.hits, toEmit);
+        }
+        if (leak) {
+            const flagged = detectEvent('live_reply', { action: 'flag', hits: leak.hits });
+            if (flagged)
+                toEmit.push(guardrailTurnEvent(flagged));
+        }
+        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, found }, event) {
+    const detected = found && detectEvent('thought', found);
+    const guardrail = guardrailFromHits('thought', 'untrusted', hits, 'redact');
+    return [
+        ...(detected ? [guardrailTurnEvent(detected)] : []),
+        ...(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. `guardrails.detect` reads the cycle's whole
+ * transcript. Allow releases what is still held; redact and refuse replace it
+ * with text (held audio is dropped); block withholds it as a `safety` error.
+ */
+function finalEgressVerdict(session, gate, prior) {
+    const { detect, blockedReply } = session.policy;
+    const read = readReply({ text: gate.accumulated() }, detect, {
+        boundary: 'live_reply',
+        ...(session.withholdVisible ? { reportedTo: clearedTo(gate) } : {}),
+        scope: scopeOf(session.policy, session.context),
+    });
+    /** The part of the cycle's reply the host already has. */
+    const shown = gate.accumulated().slice(0, session.releasedTo);
+    const stopped = standingBlock(read, session.promptLeaks);
+    // why: A detector's block is reported by its own event, which names the boundary.
+    const judged = stopped && stopped !== read.blocked
+        ? guardrailFromHits('live_outbound', 'untrusted', stopped, 'block')
+        : undefined;
+    const events = [...prior, ...read.events.map(guardrailTurnEvent), ...(judged ? [judged] : [])];
+    if (stopped) {
+        // why: Live never rewrites: audio already spoken cannot be taken back for another try.
+        if (blockedReply.onBlock === 'refuse') {
+            const text = refusalAfter(shown, session.context.labels);
+            return { action: 'emit', events: [...events, { type: 'text', text }] };
+        }
+        return {
+            action: 'withhold',
+            error: new TheoremError('safety', WITHHELD_REASON.egress),
+            events,
+        };
+    }
+    if (read.rewritten) {
+        // why: The audio says what the transcript did: only the replaced text goes out.
+        const text = replyAfter(shown, read.payload.text);
+        return { action: 'emit', events: [...events, { type: 'text', text }] };
+    }
+    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;
+}
+function finalizeCycle(session, gate) {
+    const events = [];
+    flushHeld(session, gate, events);
+    if (!gate.accumulated()) {
+        return emitOrIdle(dropUntranscribed(session, events));
+    }
+    return finalEgressVerdict(session, gate, events);
+}
+/** Call once after the provider has finished the cycle; it also starts the next one. */
+function finalizeLiveOutboundTurn(session) {
+    const thought = session.thoughts
+        ? thoughtEvents(session.thoughts.flush(), { type: 'thought', text: '' })
+        : [];
+    if (!session.gate)
+        return emitOrIdle(thought);
+    const result = 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,54 @@
+/**
+ * Inbound and outbound guardrail primitives: sanitization, injection, and sensitive detection,
+ * canary egress gates, the detectors, and public error mapping. App-specific policy copy stays host-owned.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { Boundary, BoundaryMeta, ToolBoundary, ToolCrossing, ToolKind, } from './boundaries.js';
+export { BOUNDARIES, BOUNDARY_META, recordOf, TOOL_BOUNDARIES, TOOL_KINDS, toolBoundary, } from './boundaries.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 { DestinationVerdict, TurnDestinations } from './destinations.js';
+export { addGivenDestinations, addHistoryDestinations, addRequestDestinations, addResultDestinations, checkDestinationGate, turnDestinations, } from './destinations.js';
+export type { Detection, DetectOutcome } from './detect-at.js';
+export { detectAt } from './detect-at.js';
+export type { DetectAction, DetectMatrix, DetectMeta, Detector, DetectorConfig, DetectorDeclaration, DetectorGroup, DetectorRule, DetectorSource, DetectSources, DetectSpec, HostDetector, HostDetectorConfig, HostDetectorId, HostFind, HostSpan, NameAllow, ResolvedAllow, ResolvedDetect, UrlAllow, UrlDetector, } from './detectors.js';
+export { actionAt, DETECT_ACTION_META, DETECT_ACTIONS, DETECT_DEFAULTS, DETECTOR_BOUNDARIES, DETECTOR_GROUP_META, DETECTOR_GROUPS, DETECTOR_META, DETECTORS, detectProblem, detects, HOST_FIND_HOLD, HOST_FIND_HOLD_LIVE, hintProblem, PATTERN_DETECTORS, resolveAllow, resolveDetect, } from './detectors.js';
+export { hitRules } from './egress.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, withPublicLabels, } 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 type { CompiledPatterns, HostPattern } from './host-patterns.js';
+export { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, patternListProblem, } from './host-patterns.js';
+export { injectionSpans } from './injection.js';
+export type { ClientLabelKey, LabelKey, LabelOverrides, LabelParams } from './labels.js';
+export { CLIENT_LABEL_KEYS, LABEL_KEYS, labelCatalogRows, labelDefault, labelText, overrideLabels, resetLabels, validateLabelOverrides, } from './labels.js';
+export type { LiveHeldOutput, LiveOutboundBatchResult, LiveOutboundGateSession, } from './live-outbound-gate.js';
+export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from './live-outbound-gate.js';
+export { resolveGuardrailPolicy } from './policy.js';
+export type { ProgressiveYieldGate, ProgressiveYieldGateOptions, ProgressiveYieldResult, } from './progressive-yield.js';
+export { createOutboundProgressiveGate, createProgressiveYieldGate } 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 { DETECT_RULES, detectRule, EGRESS_RULES, NETWORK_RULES, TOOL_RULES, } from './rules.js';
+export type { SanitizedTurnRequest } from './sanitize.js';
+export { sanitizeHistory, sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, } from './sanitize.js';
+export { sensitiveSpans } from './sensitive.js';
+export type { SensitiveGroup, SensitiveGroups, SensitiveSelection, SensitiveSwitches, } from './sensitive-groups.js';
+export { SENSITIVE_GROUPS } from './sensitive-groups.js';
+export type { ScanText } from './serialize.js';
+export { scanTextOf, textForScan } from './serialize.js';
+export type { Directive, DirectiveSignal } from './tool-directives.js';
+export { advisoryLevel, DIRECTIVE_SIGNALS, directives } from './tool-directives.js';
+export type { GuardedToolText, InspectedToolArguments } 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, BlockedReplyOnBlock, BlockedReplySpec, DestinationGate, GuardrailAction, GuardrailContext, GuardrailEvent, GuardrailHit, GuardrailStage, HostGuardrailsSpec, NetworkGuardrailSpec, OutboundPayload, ProfileGuardrailsSpec, Provenance, QuotaGuardrailSpec, ResolvedBlockedReply, ResolvedGuardrailPolicy, Severity, TaintGate, TaintGuardrailSpec, ToolOrigin, TrustLevel, TurnTaint, Verdict, } from './types.js';
+export { ADVISORY_LEVELS, BLOCKED_REPLY_ON_BLOCK, DESTINATION_GATES, GUARDRAIL_STAGES, SEVERITIES, TAINT_GATES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';

package/esm/src/guardrails/mod.js

@@ -0,0 +1,34 @@
+/**
+ * Inbound and outbound guardrail primitives: sanitization, injection, and sensitive detection,
+ * canary egress gates, the detectors, and public error mapping. App-specific policy copy stays host-owned.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { BOUNDARIES, BOUNDARY_META, recordOf, TOOL_BOUNDARIES, TOOL_KINDS, toolBoundary, } from './boundaries.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 { addGivenDestinations, addHistoryDestinations, addRequestDestinations, addResultDestinations, checkDestinationGate, turnDestinations, } from './destinations.js';
+export { detectAt } from './detect-at.js';
+export { actionAt, DETECT_ACTION_META, DETECT_ACTIONS, DETECT_DEFAULTS, DETECTOR_BOUNDARIES, DETECTOR_GROUP_META, DETECTOR_GROUPS, DETECTOR_META, DETECTORS, detectProblem, detects, HOST_FIND_HOLD, HOST_FIND_HOLD_LIVE, hintProblem, PATTERN_DETECTORS, resolveAllow, resolveDetect, } from './detectors.js';
+export { hitRules } from './egress.js';
+export { describeError, ERROR_KINDS, errorKind, isAbortError, isTimeoutError, kindOfHttpStatus, publicError, TheoremError, throwIfAborted, toErrorEvent, withPublicLabels, } 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 { listsPatterns, MAX_PATTERN_LENGTH, MAX_PATTERNS, patternListProblem, } from './host-patterns.js';
+export { injectionSpans } from './injection.js';
+export { CLIENT_LABEL_KEYS, LABEL_KEYS, labelCatalogRows, labelDefault, labelText, overrideLabels, resetLabels, validateLabelOverrides, } from './labels.js';
+export { abortLiveOutboundTurn, createLiveOutboundGateSession, finalizeLiveOutboundTurn, processLiveOutboundBatch, } from './live-outbound-gate.js';
+export { resolveGuardrailPolicy } from './policy.js';
+export { createOutboundProgressiveGate, createProgressiveYieldGate } from './progressive-yield.js';
+export { PROMPT_ECHO_WORDS, scanTextForPromptEcho } from './prompt-echo.js';
+export { clientIp, quotaExhausted, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
+export { DETECT_RULES, detectRule, EGRESS_RULES, NETWORK_RULES, TOOL_RULES, } from './rules.js';
+export { sanitizeHistory, sanitizeProjectId, sanitizeTurnRequest, sanitizeTurnRequestWithEvents, } from './sanitize.js';
+export { sensitiveSpans } from './sensitive.js';
+export { SENSITIVE_GROUPS } from './sensitive-groups.js';
+export { scanTextOf, textForScan } from './serialize.js';
+export { advisoryLevel, DIRECTIVE_SIGNALS, directives } 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, BLOCKED_REPLY_ON_BLOCK, DESTINATION_GATES, GUARDRAIL_STAGES, SEVERITIES, TAINT_GATES, TOOL_ORIGINS, TRUST_LEVELS, } from './types.js';

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

@@ -0,0 +1,46 @@
+import type { NetworkGuardrailSpec } from './types.js';
+/** True for loopback addresses and names reserved for local use: `localhost`, `.local`, `.internal`, `.lan`, `.home.arpa`, and `.localdomain`. */
+export declare function isLocalhostName(hostname: string): boolean;
+/** True when the IP address, or bracketed IPv6 host, is a private or local IPv4 or IPv6 address. */
+export declare function isPrivateOrLocalAddress(ipOrHost: string): boolean;
+/** Throws a `TheoremError` when the URL is blocked. */
+export declare function assertSafeUrl(urlStr: string, policy?: NetworkGuardrailSpec): URL;
+/** Options for a fetch that checks the network policy on every hop. */
+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>;
+/** Options for `dnsOverHttpsResolver`: the DNS JSON endpoint and an optional `fetch`. */
+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;