@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/guardrails/detect-stream.js

@@ -0,0 +1,77 @@
+/**
+ * `guardrails.detect` on text released as it streams: a reply, a Live reply, a
+ * thought. The stream scanner (`egress-stream.ts`) says where a match could
+ * still be under way, so nothing a detector reads is released early, and where
+ * one settled; `detectRelease` then reads the stretch being released and takes
+ * the action the profile set.
+ *
+ * @module
+ */
+import { detectorsAt, detectRelease, hostAt, isScoped, } from './detect-at.js';
+import { HOST_FIND_HOLD, HOST_FIND_HOLD_LIVE, } from './detectors.js';
+import { createEgressStream } from './egress-stream.js';
+/**
+ * A reader for text streaming across `boundary` in a turn of `scope`, or `undefined` when no
+ * detector it streams reads it. `canary_leak` and `prompt_leak` (`isScoped`) are not among them:
+ * the gate at the boundary reads those as the text grows. Nor are the detectors in `leave`, which
+ * another reader at the boundary has.
+ */
+function createDetectStream(boundary, detect, scope = {}, leave = []) {
+    const theirs = detectorsAt(boundary, detect).filter((detector) => !(isScoped(detector) || leave.includes(detector)));
+    const hosts = hostAt(boundary, detect);
+    if (theirs.length === 0 && hosts.length === 0)
+        return undefined;
+    const detectors = [...theirs, ...hosts.map(({ id }) => id)];
+    const sources = detect.sources ?? {};
+    /** The host's patterns, with whose they are: a detector they add to, or one of the host's own. */
+    const own = [
+        ...theirs.map((detector) => ({ detector, ...sources[detector] })),
+        ...hosts.map(({ id, matchers, compiled }) => ({ detector: id, matchers, compiled })),
+    ];
+    // why: A host's patterns with no table have no automaton to hold by, so nothing is released
+    // until the text ends and is read whole. Registration refuses such a profile.
+    const unheld = own.some(({ matchers, compiled }) => matchers?.length && !compiled);
+    const stream = createEgressStream({
+        detect: theirs.filter((detector) => sources[detector]?.theorem !== false),
+        own: own.flatMap(({ detector, compiled, matchers = [] }) => compiled ? [{ detector, compiled, matchers }] : []),
+        skipImages: detect.ungiven_images[boundary] !== 'ignore',
+        ...(scope.allow ? { allow: scope.allow } : {}),
+        ...(scope.givenUrls ? { given: scope.givenUrls } : {}),
+        ...(scope.note ? { note: scope.note } : {}),
+        ...(scope.ownTools ? { tools: scope.ownTools } : {}),
+    });
+    // why: A `find` says nothing of where a match could still start, so a fixed tail stays held and
+    // every release is read: a match no longer than the tail is caught whole.
+    const finds = hosts.some(({ find }) => find);
+    const tail = boundary === 'live_reply' ? HOST_FIND_HOLD_LIVE : HOST_FIND_HOLD;
+    let window = '';
+    /** The matches the stream settled that no release has reached yet. */
+    let settled = [];
+    return {
+        push(fragment) {
+            window += fragment;
+            for (const { start, detector } of stream.push(fragment)) {
+                if (detector)
+                    settled.push({ start, detector });
+            }
+        },
+        holdFrom() {
+            if (unheld)
+                return 0;
+            const held = stream.holdFrom();
+            return finds ? Math.min(held, Math.max(0, window.length - tail)) : held;
+        },
+        take(from, to, ended = false) {
+            const reached = settled.filter(({ start }) => start < to);
+            // why: A text that ends mid-match never settles it, so the end is read whole.
+            if (reached.length === 0 && !ended && !finds) {
+                return { action: 'allow', text: window.slice(from, to), hits: [], taken: to - from };
+            }
+            const stretch = { from, to, settled: reached.map(({ detector }) => detector) };
+            const release = detectRelease(window, stretch, boundary, detect, { detectors, scope });
+            settled = settled.filter(({ start }) => start >= from + release.taken);
+            return release;
+        },
+    };
+}
+export { createDetectStream };

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

@@ -0,0 +1,216 @@
+/** labels-exempt-file: authoring labels, descriptions and profile-registration diagnostics for detectors — not runtime user or model copy (P2) */
+import { type Boundary } from './boundaries.js';
+import { type CompiledPatterns, type HostMatcher, type HostPattern } from './host-patterns.js';
+/**
+ * What the kernel finds in text: the four families of sensitive data, prompt-injection phrasing,
+ * a tool's text that instructs the agent, and what is the profile's own on its way out (the canary token, the system instruction, the
+ * kernel's markers, an image or link to an address the model was not given, and the names of its
+ * tools).
+ */
+declare const DETECTORS: readonly ["ids", "financial", "network", "credentials", "injection", "tool_instructions", "canary_leak", "prompt_leak", "marker_leak", "ungiven_images", "ungiven_links", "tool_leak"];
+/** A detector recognizes a particular kind of content in text. Its configured action determines what happens when it finds a match. */
+type Detector = (typeof DETECTORS)[number];
+/**
+ * What the kernel does with a match, the same at every boundary:
+ * - `ignore` — the text is not checked.
+ * - `flag` — the match is recorded in the trace; nothing changes.
+ * - `redact` — the match is replaced with a placeholder; the rest is kept.
+ * - `block` — the whole message, reply, or tool call is stopped.
+ */
+declare const DETECT_ACTIONS: readonly ["ignore", "flag", "redact", "block"];
+/** One of {@linkcode DETECT_ACTIONS}. */
+type DetectAction = (typeof DETECT_ACTIONS)[number];
+/** The addresses `ungiven_images` or `ungiven_links` lets through beyond the ones the model was given. */
+interface UrlAllow {
+    /** Hostnames let through whatever their URL, such as the host's own CDN. */
+    hosts?: readonly string[];
+    /**
+     * Whether a URL a tool returned counts as given. Default true. A tool result can offer the
+     * model URLs to pick from, and the pick tells their server something; false closes that
+     * channel, and keeps only what the system prompt, the user, and host history gave.
+     */
+    fromTools?: boolean;
+}
+/** The names `tool_leak` lets through. */
+interface NameAllow {
+    /** Names of tools or parameters that are innocent in a reply, such as a tool called `search`. */
+    names?: readonly string[];
+}
+/** A detector's setting in full. */
+interface DetectorConfig {
+    /** The action at every boundary. Left out, each boundary keeps its default. */
+    action?: DetectAction;
+    /** An action for the boundaries it names, over `action` or the default. */
+    at?: Partial<Record<Boundary, DetectAction>>;
+    /**
+     * Whether Theorem's own patterns run. Default true. With `patterns` it gives the four choices:
+     * both, only Theorem's, only the host's (`false` with patterns), or none (`false` without).
+     * A detector that takes no patterns refuses it.
+     */
+    theorem?: boolean;
+    /** The host's own patterns, read on the text as written. A detector that takes no patterns refuses them. */
+    patterns?: readonly HostPattern[];
+    /** The table compiled for `patterns` (`compilePatterns`, `agents detect-compile`). Patterns need it. */
+    compiled?: CompiledPatterns;
+    /**
+     * One line telling the model what to leave out, sent when this detector blocks a reply that is
+     * then retried. Left out, the labels' `detect.hint.<detector>`. Only beside `patterns`: the
+     * labels' hint describes Theorem's patterns, not the host's.
+     */
+    hint?: string;
+    /**
+     * What the detector lets through: for `ungiven_images` and `ungiven_links` the addresses besides
+     * the given ones, for `tool_leak` the names that are innocent. Any other detector refuses it.
+     */
+    allow?: UrlAllow | NameAllow;
+}
+/** One action at every boundary, or the setting in full. */
+type DetectorRule = DetectAction | DetectorConfig;
+/** The key of a detector of the host's own: its namespace, a dot, a name (`acme.record`). */
+type HostDetectorId = `${string}.${string}`;
+/** A stretch of the text a host's `find` matched: `[start, end)`, in UTF-16 units. */
+interface HostSpan {
+    start: number;
+    end: number;
+}
+/**
+ * A host's own reading of a text, for what patterns cannot say. It runs on every text crossing a
+ * boundary the detector reads, so it returns at once and does not wait on anything. If it throws,
+ * or returns a span outside the text, the text does not cross. It also reads the text a trace
+ * stores, where there is no `boundary`; a text it fails on there is stored as a placeholder.
+ */
+type HostFind = (text: string, context: {
+    boundary?: Boundary;
+}) => readonly HostSpan[];
+/**
+ * A detector of the host's own, under a key with a dot. It reads with `patterns`, `find`, or both,
+ * and has no default: it reads the boundaries `action` and `at` put above `ignore`.
+ */
+interface HostDetectorConfig {
+    /** What an editor and the trace call it. */
+    label: string;
+    /** The action at every boundary. Left out, only the boundaries `at` names are read. */
+    action?: DetectAction;
+    /** An action for the boundaries it names, over `action`. */
+    at?: Partial<Record<Boundary, DetectAction>>;
+    /** Its patterns, read on the text as written. */
+    patterns?: readonly HostPattern[];
+    /** The table compiled for `patterns` (`compilePatterns`, `agents detect-compile`). Patterns need it. */
+    compiled?: CompiledPatterns;
+    /**
+     * Its own reading. As a reply streams, a `find` reads the text held so far, and the last
+     * `HOST_FIND_HOLD` characters stay held (`HOST_FIND_HOLD_LIVE` in a Live reply): a match is
+     * caught whole when it is no longer than that.
+     */
+    find?: HostFind;
+    /**
+     * One line telling the model what to leave out, sent when this detector blocks a reply that is
+     * then retried. Left out, the labels' `detect.hint.own`, which names the label.
+     */
+    hint?: string;
+}
+/** One action for every detector at every boundary, or a rule for the detectors it names. */
+type DetectSpec = DetectAction | (Partial<Record<Detector, DetectorRule>> & {
+    readonly [id: HostDetectorId]: HostDetectorConfig;
+});
+/** A host's detector, resolved: its action at every boundary and what it reads with. */
+interface HostDetector {
+    id: HostDetectorId;
+    label: string;
+    actions: Readonly<Record<Boundary, DetectAction>>;
+    /** Its patterns, ready to run. */
+    matchers: readonly HostMatcher[];
+    /** The table compiled for its patterns; absent when it has none. */
+    compiled?: CompiledPatterns;
+    find?: HostFind;
+    hint?: string;
+}
+/** How much of a streaming reply stays held for a host's `find`, in characters. */
+declare const HOST_FIND_HOLD = 256;
+/** The same in a Live reply, which is spoken as it is written. */
+declare const HOST_FIND_HOLD_LIVE = 96;
+/** Whose patterns a detector reads with: Theorem's, the host's, both, or neither. */
+interface DetectorSource {
+    /** Whether Theorem's own patterns run. */
+    theorem: boolean;
+    /** The host's patterns, ready to run. */
+    matchers: readonly HostMatcher[];
+    /** The table compiled for the host's patterns; absent when it has none. */
+    compiled?: CompiledPatterns;
+}
+/** The source of each detector a profile changed it for. One left out reads with Theorem's patterns only. */
+type DetectSources = Readonly<Partial<Record<Detector, DetectorSource>>>;
+/** Every detector's action at every boundary. */
+type DetectMatrix = Readonly<Record<Detector, Readonly<Record<Boundary, DetectAction>>>>;
+/**
+ * Every detector's action at every boundary, defaults applied, and whose patterns each reads
+ * with. A detector left with no patterns at all is `ignore` everywhere: it has nothing to find.
+ */
+type ResolvedDetect = DetectMatrix & {
+    readonly sources?: DetectSources;
+    /** The hint of each of Theorem's detectors the profile set one on. */
+    readonly hints?: Readonly<Partial<Record<Detector, string>>>;
+    /** The names `tool_leak` lets through. */
+    readonly innocent?: readonly string[];
+    /** The host's own detectors, in the order the profile lists them. */
+    readonly host?: readonly HostDetector[];
+};
+/** How a detector, a group, or an action is named and described to a builder. */
+interface DetectMeta {
+    label: string;
+    doc: string;
+}
+/** The groups an editor lists detectors under, in order. */
+declare const DETECTOR_GROUPS: readonly ["data", "manipulation", "setup", "addresses"];
+/** One of {@linkcode DETECTOR_GROUPS}. */
+type DetectorGroup = (typeof DETECTOR_GROUPS)[number];
+/** The label of every group, and what its detectors find. */
+declare const DETECTOR_GROUP_META: Readonly<Record<DetectorGroup, DetectMeta>>;
+/**
+ * Everything that describes a detector: what it finds, its group, and its default action at each
+ * boundary it applies at. The default is also the recommended action. A boundary left out is one
+ * the detector does not apply at.
+ */
+interface DetectorDeclaration extends DetectMeta {
+    group: DetectorGroup;
+    /** Its name in a list under its group's name, where the group says the rest. */
+    short?: string;
+    defaults: Readonly<Partial<Record<Boundary, DetectAction>>>;
+    /** What its setting's `allow` lists, when it takes one: addresses, or names. */
+    allow?: 'urls' | 'names';
+    /** Whether it reads with patterns, so its setting takes `theorem` and `patterns`. */
+    patterns?: true;
+}
+/** Every detector's declaration. The editor, validation, and the catalog are built from it. */
+declare const DETECTOR_META: Readonly<Record<Detector, DetectorDeclaration>>;
+/** The detectors that read with patterns: their setting takes `theorem` and `patterns`. */
+declare const PATTERN_DETECTORS: readonly Detector[];
+/** The boundaries each detector applies at, in the kernel's order. */
+declare const DETECTOR_BOUNDARIES: Readonly<Record<Detector, readonly Boundary[]>>;
+/** The label of every action, and what it does. */
+declare const DETECT_ACTION_META: Readonly<Record<DetectAction, DetectMeta>>;
+/** What a profile that sets no `guardrails.detect` gets. */
+declare const DETECT_DEFAULTS: ResolvedDetect;
+/** Whether `detector` is above `ignore` at any of `boundaries`. */
+declare function detects(detect: ResolvedDetect, detector: Detector, boundaries?: readonly Boundary[]): boolean;
+/** `spec` with everything it leaves out at its default. */
+declare function resolveDetect(spec?: DetectSpec): ResolvedDetect;
+/** The action of `key`, a detector of Theorem's or the host's, at `boundary`. One unknown is `ignore`. */
+declare function actionAt(detect: ResolvedDetect, key: string, boundary: Boundary): DetectAction;
+/** The detectors whose setting takes `allow`. */
+type UrlDetector = 'ungiven_images' | 'ungiven_links';
+/** What each of the {@linkcode UrlDetector}s lets through, as the profile set it. */
+type ResolvedAllow = Readonly<Record<UrlDetector, UrlAllow>>;
+declare const NO_ALLOW: ResolvedAllow;
+/** The `allow` of each detector that takes one. */
+declare function resolveAllow(spec?: DetectSpec): ResolvedAllow;
+declare function hintProblem(path: string, hint: unknown): string | undefined;
+declare function isDetector(value: string): value is Detector;
+/**
+ * What is wrong with a `guardrails.detect` value, or `undefined` when it is valid. A misspelt
+ * detector or boundary would leave the one it meant at its default, silently, so both are errors.
+ * `boundaries` are the ones the profile has; a rule naming another is an error.
+ */
+declare function detectProblem(path: string, spec: unknown, boundaries?: readonly Boundary[]): string | undefined;
+export type { DetectAction, DetectMatrix, DetectMeta, Detector, DetectorConfig, DetectorDeclaration, DetectorGroup, DetectorRule, DetectorSource, DetectSources, DetectSpec, HostDetector, HostDetectorConfig, HostDetectorId, HostFind, HostSpan, NameAllow, ResolvedAllow, ResolvedDetect, UrlAllow, UrlDetector, };
+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, isDetector, NO_ALLOW, PATTERN_DETECTORS, resolveAllow, resolveDetect, };