@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,112 @@
+import { type ProviderEvent, type TurnEvent, type TurnEventOf } from '../kernel/turn-events.js';
+import { type LexiconOverrides } from './lexicon.js';
+declare const USER_OPEN = "<user_data>";
+declare const USER_CLOSE = "</user_data>";
+declare const OMIT_CANARY = "[omitted - canary]";
+/** Creates a 128-bit, cryptographically random token for one turn's canary binding. */
+declare function mintCanary(): string;
+/**
+ * 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;
+/**
+ * The note is the lexicon's `canary.bind_note`: the profile's `lexicon`, then
+ * `overrideLexicon`, 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, lexicon?: LexiconOverrides): string;
+/** The note `bindCanary` appends, or nothing without a canary. */
+declare function canaryNote(canary: string, lexicon?: LexiconOverrides): string;
+/** The lexicon's `user_data.note`, which tells the model what `wrapUserData`'s tags mean. */
+declare function userDataNote(lexicon?: LexiconOverrides): string;
+/** Offsets `[start, end)` of `text` covering each leak, ordered by start. */
+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, 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: ProviderEvent): string[];
+/**
+ * Whether any field of an event's host content (`guardedEventTexts`) carries
+ * a leak. Unguarded output (`isGuardedOutput`) never carries one.
+ */
+declare function eventHasCanary(event: ProviderEvent, canary: string): boolean;
+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: ProviderEvent): event is StreamedReplyEvent;
+declare function redactCanary(event: TurnEvent, canary: string): TurnEvent;
+export type { CanaryGateResult, CanaryScanner, CanaryStreamGate, StreamedReplyEvent };
+export { bindCanary, CANARY_LEAK_REACH, canaryHoldFrom, canaryLeakRanges, canaryNote, canaryOpeningFrom, createCanaryScanner, createCanaryStreamGate, eventHasCanary, guardedEventTexts, isStreamedCanaryEvent, mintCanary, OMIT_CANARY, promptLeakCarry, RELEASED_LOOKBACK, redactCanary, redactCanaryText, scanTextForCanaryLeak, USER_CLOSE, USER_OPEN, userDataNote, wordStartAcross, wrapUserData, };