@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -5,6 +5,7 @@ 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
@@ -16,6 +17,7 @@ export interface LiveHeldOutput {
     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;
@@ -26,14 +28,12 @@ export interface LiveOutboundGateSession {
     releasedTo: number;
     /** Stop releasing held output after a progressive egress hit. */
     withholdVisible: boolean;
-    /**
-     * System-prompt leaks this cycle withheld under a host policy. They pin the
-     * cycle's final verdict to block: no host verdict may release them.
-     */
+    /** 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[];
@@ -44,11 +44,12 @@ export type LiveOutboundBatchResult = {
 } | {
     action: 'idle';
 };
-/** A canary is attached only when the profile policy enables it and the caller supplied a token. */
-declare function createLiveOutboundGateSession(profile: Profile, canary?: string, privateSystem?: readonly string[], givenUrls?: GivenUrls): LiveOutboundGateSession;
-declare function processLiveOutboundBatch(session: LiveOutboundGateSession, events: TurnEvent[]): Promise<LiveOutboundBatchResult>;
+/** 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): Promise<LiveOutboundBatchResult>;
+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

@@ -1,48 +1,30 @@
 import { isStreamedCanaryEvent } from './canary.js';
-import { eventPromptLeakHits, isPromptLeakHit, promptLeakReason, runEnforcer, WITHHELD_REASON, } from './egress.js';
-import { streamPlanOf } from './egress-stream.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, guardrailFromVerdict } from './events.js';
-import { lexiconText } from './lexicon.js';
+import { guardrailFromHits, guardrailTurnEvent } from './events.js';
 import { resolveGuardrailPolicy } from './policy.js';
-import { createOutboundProgressiveGate, LIVE_DEFAULT_HOLDBACK, } from './progressive-yield.js';
+import { createOutboundProgressiveGate, outboundProgressiveGate, } 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);
+/** 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,
-        ...(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 } : {}),
+        ...leakScopeOf(policy.detect, { canary, privateSystem }),
+        ...(profile.labels ? { labels: profile.labels } : {}),
         ...(givenUrls ? { givenUrls } : {}),
+        ...(ownTools ? { ownTools } : {}),
     };
-    const thoughts = thoughtGuardFor(policy.egress?.enforce, context);
+    const thoughts = await thoughtGuardFor(policy, context);
     return {
         policy,
         context,
-        gate: createOutboundProgressiveGate(policy, context),
+        gate: await createOutboundProgressiveGate(policy, context, 'live_reply'),
         held: [],
         releasedTo: 0,
         withholdVisible: false,
@@ -51,16 +33,12 @@ function createLiveOutboundGateSession(profile, canary, privateSystem, givenUrls
 }
 function resetCycle(session) {
     const carry = session.gate?.carryOut();
-    session.gate = createOutboundProgressiveGate(session.policy, session.context, carry);
+    session.gate = outboundProgressiveGate(session.policy, session.context, 'live_reply', 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 {
@@ -102,34 +80,35 @@ function releaseHeld(session, gate, to, into, transcriptWhole = false) {
 }
 /**
  * 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.
+ * 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 undefined;
-    }
-    if (canaryOnlyImmediateWithhold(session)) {
-        return withholdResult(promptLeakReason(result.hits), result.hits, into);
+        return;
     }
     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');
+    // 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);
     }
-    return undefined;
 }
 /** Scan and release everything held (a non-reply event, or the end of the cycle). */
-async function flushHeld(session, gate, into) {
+function flushHeld(session, gate, into) {
     if (session.withholdVisible || session.held.length === 0) {
-        return undefined;
+        return;
     }
-    return applyScan(session, gate, await gate.flush(), into);
+    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) {
@@ -146,57 +125,60 @@ function coverMedia(session, end) {
         item.end = end;
     }
 }
-async function holdStreamChunk(session, gate, event, into) {
+function holdStreamChunk(session, gate, event, into) {
     const text = event.text ?? '';
     if (!text) {
-        return undefined;
+        return;
     }
     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);
+    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);
 }
-async function processLiveOutboundBatch(session, events) {
+/** 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) {
-        return emitOrIdle(events);
+        // 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]));
     }
-    // One batch is one provider message: its transcript is its audio's.
+    // 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);
-            const stopped = await holdStreamChunk(session, gate, event, toEmit);
-            if (stopped) {
-                return stopped;
-            }
+            holdStreamChunk(session, gate, event, toEmit);
             continue;
         }
         if (event.type === 'media') {
             holdMedia(session, gate, event, transcribed);
-            // Media not yet held until the next event can release it now.
+            // why: 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;
-        }
+        flushHeld(session, gate, toEmit);
         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);
+        // 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));
@@ -207,9 +189,14 @@ async function processLiveOutboundBatch(session, events) {
     return emitOrIdle(toEmit);
 }
 /** What a thought guard released, after the event saying what it omitted from it. */
-function thoughtEvents({ text, hits }, event) {
+function thoughtEvents({ text, hits, found }, event) {
+    const detected = found && detectEvent('thought', found);
     const guardrail = guardrailFromHits('thought', 'untrusted', hits, 'redact');
-    return [...(guardrail ? [guardrail] : []), ...(text ? [{ ...event, text }] : [])];
+    return [
+        ...(detected ? [guardrailTurnEvent(detected)] : []),
+        ...(guardrail ? [guardrail] : []),
+        ...(text ? [{ ...event, text }] : []),
+    ];
 }
 function isGenerationComplete(event) {
     return event.type === 'done' && event.stop?.kind === 'generation_complete';
@@ -230,26 +217,41 @@ 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.
+ * 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.
  */
-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);
+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 withholdResult(WITHHELD_REASON.egress, verdict.hits, prior);
+        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);
@@ -265,31 +267,22 @@ function dropUntranscribed(session, events) {
     const guardrail = guardrailFromHits('live_outbound', 'untrusted', [UNTRANSCRIBED_HIT], 'block');
     return guardrail ? [...events, guardrail] : events;
 }
-async function finalizeCycle(session, gate) {
+function finalizeCycle(session, gate) {
     const events = [];
-    const stopped = await flushHeld(session, gate, events);
-    if (stopped) {
-        return stopped;
-    }
+    flushHeld(session, gate, events);
     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);
+    return finalEgressVerdict(session, gate, 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' };
-    }
+function finalizeLiveOutboundTurn(session) {
     const thought = session.thoughts
         ? thoughtEvents(session.thoughts.flush(), { type: 'thought', text: '' })
         : [];
-    const result = await finalizeCycle(session, session.gate);
+    if (!session.gate)
+        return emitOrIdle(thought);
+    const result = finalizeCycle(session, session.gate);
     resetCycle(session);
     if (thought.length === 0)
         return result;

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

@@ -1,46 +1,54 @@
 /**
- * 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.
+ * 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 { 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 { 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, withPublicWording, } 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 { ClientLexiconKey, LexiconKey, LexiconOverrides, LexiconParams } from './lexicon.js';
-export { CLIENT_LEXICON_KEYS, LEXICON_KEYS, lexiconDefault, lexiconText, overrideLexicon, resetLexicon, } from './lexicon.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 type { DetectionOptions } from './policy.js';
-export { detectionForTrust, resolveGuardrailPolicy } from './policy.js';
+export { 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 { 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 { 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 { 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 { advisoryLevel, directiveHits, looksDirective, } from './tool-directives.js';
-export type { GuardedToolText } from './tool-result.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, 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';
+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

@@ -1,29 +1,34 @@
 /**
- * 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.
+ * 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 { 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 { 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_LEXICON_KEYS, LEXICON_KEYS, lexiconDefault, lexiconText, overrideLexicon, resetLexicon, } from './lexicon.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 { detectionForTrust, resolveGuardrailPolicy } from './policy.js';
-export { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK, LIVE_DEFAULT_HOLDBACK, } from './progressive-yield.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 { 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 { 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, directiveHits, looksDirective, } from './tool-directives.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, EGRESS_ON_BLOCK, GUARDRAIL_STAGES, SEVERITIES, TAINT_GATES, TOOL_ORIGINS, TRUST_LEVELS, } 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/network.d.ts

@@ -1,8 +1,11 @@
 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. */
@@ -28,6 +31,7 @@ export type ResolveHost = (hostname: string, signal?: AbortSignal) => Promise<re
 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;

package/esm/src/guardrails/network.js

@@ -13,18 +13,18 @@ import { TheoremError } from './error.js';
 /** 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)
+    (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));
@@ -143,6 +143,7 @@ function isPrivateOrLocalIPv6(ip) {
         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('.')) {
@@ -164,6 +165,7 @@ export function isLocalhostName(hostname) {
         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);
@@ -175,12 +177,12 @@ export function assertSafeUrl(urlStr, policy) {
         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)
+        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();
-    // An allowed host is exempt from the address checks, never from the scheme.
+    // 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()}:`))
@@ -223,7 +225,7 @@ async function assertResolvesPublic(target, options, signal) {
     }
     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)
+        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) {
@@ -270,15 +272,15 @@ export async function fetchGuarded(url, init, options) {
             body,
             redirect: 'manual',
         });
-        const location = response.headers.get('location');
-        if (!options.followRedirects || !REDIRECT_STATUSES.has(response.status) || location === null) {
+        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}"`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            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(location, target).href);
+        target = await clearHop(new URL(redirect, target).href);
         onOrigin &&= target.origin === origin;
         if (redirectsToGet(response.status, method)) {
             method = 'GET';