@theoremjs/agents 0.3.0 → 0.3.1

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

@@ -3,4 +3,18 @@ declare function normalizeCodePoint(ch: string): string;
 /** Whether a code point is one `EMOJI_BETWEEN` drops between letters. */
 declare function isEmoji(ch: string): boolean;
 declare function normalizeForDetection(text: string): string;
-export { isEmoji, normalizeCodePoint, normalizeForDetection };
+/** `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

@@ -129,4 +129,37 @@ function normalizeForDetection(text) {
     }
     return out.replace(EMOJI_BETWEEN, '').replace(BACKSLASH_BEFORE_ALPHA, '');
 }
-export { isEmoji, normalizeCodePoint, normalizeForDetection };
+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

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

package/esm/src/guardrails/policy.js

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

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

@@ -1,34 +1,44 @@
-import type { EgressEnforcer, GuardrailContext, GuardrailHit, ResolvedGuardrailPolicy } from './types.js';
-/** Default lookback under a host `egress.enforce` the gate cannot read. */
-declare const DEFAULT_HOLDBACK = 256;
-/**
- * Default lookback on Live under a host policy the gate cannot read, where the
- * held transcript holds back audio too: the shortest that shows the host no
- * character of any egress corpus match however the transcript is chunked
- * (88), with a margin.
- */
-declare const LIVE_DEFAULT_HOLDBACK = 96;
+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;
-    /** When set, each step runs this policy on the accumulated window before emit. */
-    enforce?: EgressEnforcer;
     /**
-     * Lookback in characters under an `enforce` the gate cannot read (default
-     * `DEFAULT_HOLDBACK`). The bundled policy holds exactly and takes none: it
-     * is an error to set one with it. A tail that could start a canary leak is
-     * always held on top.
+     * `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.
      */
-    holdback?: number;
+    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
@@ -41,8 +51,8 @@ export interface ProgressiveYieldGateOptions {
  * prefixes outside its retained lookback window.
  */
 interface ProgressiveYieldGate {
-    process: (fragment: string) => Promise<ProgressiveYieldResult>;
-    flush: () => Promise<ProgressiveYieldResult>;
+    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. */
@@ -59,11 +69,42 @@ interface ProgressiveYieldGate {
     carryOut: () => string;
 }
 /** Call `flush` when the stream ends to release the held tail. */
-declare function createProgressiveYieldGate(options: ProgressiveYieldGateOptions): ProgressiveYieldGate;
+declare function createProgressiveYieldGate(options: ProgressiveYieldGateOptions): Promise<ProgressiveYieldGate>;
 /**
- * Shared constructor for runTurn + Live: gate when canary and/or egress.enforce
- * is active. `context.canary` is set only when the profile enabled canary minting.
+ * 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 createOutboundProgressiveGate(policy: ResolvedGuardrailPolicy, context: GuardrailContext, carry?: string): ProgressiveYieldGate | null;
+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 { createOutboundProgressiveGate, createProgressiveYieldGate, DEFAULT_HOLDBACK, LIVE_DEFAULT_HOLDBACK, };
+export { createDraftGate, createOutboundProgressiveGate, createProgressiveYieldGate, DraftReader, outboundProgressiveGate, replyIsJudged, };