@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/guardrails/canary-gate.js

@@ -0,0 +1,40 @@
+import { createCanaryStreamGate, eventHasCanary, guardedEventTexts, isStreamedCanaryEvent, } from './canary.js';
+import { scanTextForPromptEcho } from './prompt-echo.js';
+/** Pass the system prompt as sent to catch replies that echo it, as `runTurn` and Live do. */
+function createCanaryGateSession(canary, privateSystem) {
+    return {
+        canary,
+        ...(privateSystem ? { privateSystem } : {}),
+        gate: createCanaryStreamGate(canary, privateSystem),
+    };
+}
+function echoesPrompt(event, canary, privateSystem) {
+    return (privateSystem !== undefined &&
+        guardedEventTexts(event).some((text) => scanTextForPromptEcho(text, privateSystem, canary)));
+}
+/**
+ * Canary-only batch filter for hosts that need stream lookback without full egress. Stops at the
+ * first leak, so no unsafe event is returned; thoughts are unguarded (`isGuardedOutput`).
+ */
+function filterCanaryGatedEvents(session, events) {
+    const out = [];
+    for (const event of events) {
+        if (isStreamedCanaryEvent(event)) {
+            const result = session.gate.process(event.text ?? '');
+            if (result.leak) {
+                return { leaked: true };
+            }
+            if (result.emit) {
+                out.push({ ...event, text: result.emit });
+            }
+            continue;
+        }
+        if (eventHasCanary(event, session.canary) ||
+            echoesPrompt(event, session.canary, session.privateSystem)) {
+            return { leaked: true };
+        }
+        out.push(event);
+    }
+    return { leaked: false, events: out };
+}
+export { createCanaryGateSession, filterCanaryGatedEvents };

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

@@ -0,0 +1,146 @@
+import type { ContextSender } from '../kernel/schema.js';
+import { type ModelEvent, type TurnEvent, type TurnEventOf } from '../kernel/turn-events.js';
+import type { ModelRequest, SystemPiece } from '../kernel/types.js';
+import { OMIT_CANARY } from '../observability/spans.js';
+import { type LabelOverrides } from './labels.js';
+/** The tag that opens the fence around user content. */
+declare const USER_OPEN = "<user_data>";
+/** The tag that closes the fence around user content. */
+declare const USER_CLOSE = "</user_data>";
+/** Creates a 128-bit, cryptographically random token for one turn's canary binding. */
+declare function mintCanary(): string;
+/**
+ * A profile's canary for a system prompt: the same on every turn that sends
+ * that prompt, so the prompt a provider caches stays the same.
+ */
+declare function profileCanary(profileId: string, system: readonly SystemPiece[]): Promise<string>;
+/**
+ * Whether a request gives the model `canary` outside its system prompt: in
+ * its input, or in a history message the model did not write.
+ * `scanned` skips what an earlier step of the turn already read.
+ */
+declare function requestGivesCanary(request: Pick<ModelRequest, 'input' | 'history'>, canary: string, scanned: WeakSet<object>): boolean;
+/**
+ * Removes pre-existing user-data fences, trims the input, and encloses the result
+ * in the canonical user-data fence used by the guardrail prompt contract.
+ */
+declare function wrapUserData(text: string): string;
+/**
+ * Encloses context in the fence that names its sender, with any fence already in it removed, so
+ * neither the page nor the person can pass text off as the host's.
+ */
+declare function wrapContext(sender: ContextSender, text: string): string;
+/** The labels' `context.note`, which tells the model what `wrapContext`'s tags mean. */
+declare function contextNote(labels?: LabelOverrides): string;
+/**
+ * The note is the labels' `canary.bind_note`: the profile's `labels`, then
+ * `overrideLabels`, then the default. Every override is checked for the
+ * `{canary}` placeholder when it is set — a note without the token binds nothing.
+ */
+declare function bindCanary(system: string, canary: string, labels?: LabelOverrides): string;
+/** The note `bindCanary` appends, or nothing without a canary. */
+declare function canaryNote(canary: string, labels?: LabelOverrides): string;
+/**
+ * The words of the note `labels` binds, without the canary: its text before
+ * the canary, or after it when nothing comes before. A reply repeating them
+ * repeats the system prompt. Undefined when the note has no words of its own.
+ */
+declare function canaryNoteMarker(labels?: LabelOverrides): string | undefined;
+/** The labels' `user_data.note`, which tells the model what `wrapUserData`'s tags mean. */
+declare function userDataNote(labels?: LabelOverrides): string;
+/**
+ * Offsets `[start, end)` of `text` covering each leak, ordered by start. One
+ * stretch read as a leak under several forms is one leak: ranges that overlap
+ * are joined.
+ */
+declare function canaryLeakRanges(text: string, canary: string): Array<[number, number]>;
+/** Leak detection over `canaryLeakForms` only, not general-purpose encoded-data detection. */
+declare function scanTextForCanaryLeak(text: string, canary: string): boolean;
+/**
+ * Where the word `at` would cut in two starts, as the scan reads words; `at`
+ * itself when it cuts none. The start of a word reads as another word once
+ * the rest is omitted ("0This" as "0"), so a release never ends inside one.
+ */
+declare function wordStartAcross(text: string, at: number): number;
+/**
+ * How much released text the hold rereads: an opening it released holds at
+ * most `CANARY_OPENING_MIN - 1` characters, each at most `LONGEST_WORD_READ`
+ * long and `LEAK_GAP` from the next, and a word cut where this starts reads
+ * as no character.
+ */
+declare const RELEASED_LOOKBACK: number;
+/**
+ * How far before a point a leak run reaching past it can start: the longest
+ * run less one character, each read as above.
+ */
+declare const CANARY_LEAK_REACH: number;
+/**
+ * Offset from which `text` must stay held: the earliest point where what
+ * follows is an opening of a leak form at least `CANARY_OPENING_MIN` long,
+ * and so could still grow into a leak; 0 when one began in `released`, the
+ * text shown before it. A shorter opening is released; the scan still reads
+ * it with what follows, so the leak it grows into is caught.
+ */
+declare function canaryHoldFrom(text: string, canary: string, released?: string): number;
+/** Where the earliest opening the hold keeps starts in `text`; its length when none does. */
+declare function canaryOpeningFrom(text: string, canary: string): number;
+/**
+ * Scans a stream for a canary leak as it arrives, reading each character
+ * once: every reading keeps its projection of the stream so far and extends
+ * it with the new text, and only runs that end in what the new text added
+ * are checked. It reads the same leaks as `scanTextForCanaryLeak` over the
+ * whole stream, in time proportional to the stream's length.
+ */
+interface CanaryScanner {
+    /** Reads the next text of the stream; true once the stream holds a leak. */
+    push: (text: string) => boolean;
+}
+declare function createCanaryScanner(canary: string): CanaryScanner;
+/**
+ * What the next window of the same turn or session scans in front of its own:
+ * a possible canary opening, and the words a prompt echo could continue from.
+ */
+declare function promptLeakCarry(text: string, canary: string | undefined, privateSystem?: readonly string[]): string;
+declare function redactCanaryText(text: string, canary: string): string;
+/**
+ * The text of each field of an event's host content (`hostContentOf`), one
+ * string per field. Unguarded output (`isGuardedOutput`) carries none.
+ */
+declare function guardedEventTexts(event: ModelEvent): string[];
+/**
+ * Whether any field of an event's host content (`guardedEventTexts`) carries
+ * a leak. Unguarded output (`isGuardedOutput`) never carries one.
+ */
+declare function eventHasCanary(event: ModelEvent, canary: string): boolean;
+/** What a canary gate decides about a fragment: a leak, or the text that is safe to emit. */
+type CanaryGateResult = {
+    leak: true;
+} | {
+    leak: false;
+    emit: string;
+};
+/**
+ * Incremental canary scanner that retains the tail that could start a leak
+ * (`canaryHoldFrom`), so a leak split across adjacent stream chunks is not
+ * released prematurely.
+ */
+interface CanaryStreamGate {
+    process: (fragment: string) => CanaryGateResult;
+    flush: () => CanaryGateResult;
+}
+/**
+ * Call `flush` at stream end to release the held tail. With `privateSystem`, a reply
+ * echoing the system prompt (`scanTextForPromptEcho`) is a leak too.
+ */
+declare function createCanaryStreamGate(canary: string, privateSystem?: readonly string[]): CanaryStreamGate;
+type StreamedReplyEvent = TurnEventOf<'text' | 'evidence'>;
+/**
+ * The reply as it streams: text deltas, and the transcript of spoken output
+ * (Live `output_transcription` evidence). The one stream the outbound gates
+ * scan progressively; everything else is scanned whole per event.
+ */
+declare function isStreamedCanaryEvent(event: ModelEvent): event is StreamedReplyEvent;
+/** The event with the canary replaced by `OMIT_CANARY` in every string it holds. */
+declare function redactCanary(event: TurnEvent, canary: string): TurnEvent;
+export type { CanaryGateResult, CanaryScanner, CanaryStreamGate, StreamedReplyEvent };
+export { bindCanary, CANARY_LEAK_REACH, canaryHoldFrom, canaryLeakRanges, canaryNote, canaryNoteMarker, canaryOpeningFrom, contextNote, createCanaryScanner, createCanaryStreamGate, eventHasCanary, guardedEventTexts, isStreamedCanaryEvent, mintCanary, OMIT_CANARY, profileCanary, promptLeakCarry, RELEASED_LOOKBACK, redactCanary, redactCanaryText, requestGivesCanary, scanTextForCanaryLeak, USER_CLOSE, USER_OPEN, userDataNote, wordStartAcross, wrapContext, wrapUserData, };