@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,15 @@
+declare const CIRCULAR = "[circular]";
+/** A value rendered as text for a guardrail scan, and whether it could not be rendered. */
+export interface ScanText {
+    text: string;
+    /** True when the payload could not be rendered and was not inspected. */
+    unscannable: boolean;
+}
+/**
+ * A guardrail must never be the thing that throws: cycles and bigints still get inspected, and
+ * only a payload that defeats that (a throwing `toJSON`) comes back `unscannable` so the caller can fail closed.
+ */
+declare function textForScan(value: unknown): ScanText;
+/** Discards `unscannable`: only for callers to whom an unrenderable payload is the same as no match. */
+declare function scanTextOf(value: unknown): string;
+export { CIRCULAR, scanTextOf, textForScan };

package/esm/src/guardrails/serialize.js

@@ -0,0 +1,37 @@
+const CIRCULAR = '[circular]';
+/**
+ * A guardrail must never be the thing that throws: cycles and bigints still get inspected, and
+ * only a payload that defeats that (a throwing `toJSON`) comes back `unscannable` so the caller can fail closed.
+ */
+function textForScan(value) {
+    if (value === undefined) {
+        return { text: '', unscannable: false };
+    }
+    if (typeof value === 'string') {
+        return { text: value, unscannable: false };
+    }
+    const seen = new WeakSet();
+    try {
+        const json = JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'bigint') {
+                return val.toString();
+            }
+            if (typeof val === 'object' && val !== null) {
+                if (seen.has(val)) {
+                    return CIRCULAR;
+                }
+                seen.add(val);
+            }
+            return val;
+        });
+        return { text: json ?? '', unscannable: false };
+    }
+    catch {
+        return { text: '', unscannable: true };
+    }
+}
+/** Discards `unscannable`: only for callers to whom an unrenderable payload is the same as no match. */
+function scanTextOf(value) {
+    return textForScan(value).text;
+}
+export { CIRCULAR, scanTextOf, textForScan };

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

@@ -0,0 +1,11 @@
+/**
+ * Adversarial corpus, fuzz runners, and live attack builders, kept off the production guardrails entry.
+ *
+ * @module
+ */
+/** labels-exempt-file: adversarial harness helpers — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+export type { CanaryEgressAttack, CanaryEgressCatalogEntry, InboundFuzzPayload, InboundFuzzResult, LiveAttack, } from './corpus/mod.js';
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, FUZZ_SYSTEM, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';
+export { TEST_AWS_KEY, TEST_GITHUB_PAT, TEST_GOOGLE_KEY, TEST_OPENAI_KEY, TEST_PEM, TEST_SLACK, TEST_VISA, } from './corpus/secrets.js';
+export { INJ_IGNORE, INJ_IGNORE_REVEAL, injHexSpaced } from './corpus/strings.js';

package/esm/src/guardrails/testing.js

@@ -0,0 +1,10 @@
+/**
+ * Adversarial corpus, fuzz runners, and live attack builders, kept off the production guardrails entry.
+ *
+ * @module
+ */
+/** labels-exempt-file: adversarial harness helpers — not runtime user or model copy (P2) */
+import "../../_dnt.polyfills.js";
+export { buildCanaryEgressAttacks, buildLiveAttacks, canaryEgressCatalog, FIXED_CANARY, FUZZ_SYSTEM, filterLiveAttacks, inboundFuzzPayloads, inboundPayloadByName, runInboundGuardrailFuzz, summarizeAttackBank, } from './corpus/mod.js';
+export { TEST_AWS_KEY, TEST_GITHUB_PAT, TEST_GOOGLE_KEY, TEST_OPENAI_KEY, TEST_PEM, TEST_SLACK, TEST_VISA, } from './corpus/secrets.js';
+export { INJ_IGNORE, INJ_IGNORE_REVEAL, injHexSpaced } from './corpus/strings.js';

package/esm/src/guardrails/theorem-error.d.ts

@@ -0,0 +1,21 @@
+import type { ErrorCopies, ErrorCopy } from './event-schemas.js';
+export type { ErrorCopies, ErrorCopy };
+/**
+ * What kind of failure happened, decided where it happens. Both worlds read it:
+ * the builder in code and traces (`errorKind`, `error.type`), the user through
+ * the kind's wording (`error.<kind>` in the labels).
+ */
+export declare const ERROR_KINDS: readonly ["config", "request", "input", "action", "auth", "rate_limit", "unsupported", "unavailable", "bad_response", "network", "timeout", "safety", "blocked", "declined", "failed", "cancelled", "internal"];
+/** Why an operation failed; the user's wording and the HTTP status follow from it. */
+export type ErrorKind = (typeof ERROR_KINDS)[number];
+/** Options for a `TheoremError`: the cause and, optionally, wording for the user. */
+export interface TheoremErrorOptions extends ErrorOptions {
+    /** User wording more specific than the kind's: one line, or one per problem found. */
+    copy?: ErrorCopies;
+}
+/** An error that carries a `kind`, from which hosts choose a status and the user's wording. */
+export declare class TheoremError extends Error {
+    readonly kind: ErrorKind;
+    readonly copy?: ErrorCopies;
+    constructor(kind: ErrorKind, message: string, options?: TheoremErrorOptions);
+}

package/esm/src/guardrails/theorem-error.js

@@ -0,0 +1,54 @@
+// invariant: Its own module so `labels.ts` can throw it without importing `error.ts`, which reads the labels.
+/**
+ * What kind of failure happened, decided where it happens. Both worlds read it:
+ * the builder in code and traces (`errorKind`, `error.type`), the user through
+ * the kind's wording (`error.<kind>` in the labels).
+ */
+export const ERROR_KINDS = [
+    /** The profile, tool, or schema is set up wrong. */
+    'config',
+    /** The host called THEOREM wrongly. */
+    'request',
+    /** The user sent input the profile does not accept. */
+    'input',
+    /** The user asked for something the profile does not allow. */
+    'action',
+    /** A missing or rejected credential, or an account that cannot be billed. */
+    'auth',
+    /** Too many requests, or a quota used up. */
+    'rate_limit',
+    /** The model or route cannot serve this request. */
+    'unsupported',
+    /** The provider is down or overloaded. */
+    'unavailable',
+    /** The provider answered with something that cannot be used. */
+    'bad_response',
+    /** The request never reached the provider. */
+    'network',
+    /** The model took longer than the host allowed. */
+    'timeout',
+    /** THEOREM or the provider held the reply back. */
+    'safety',
+    /** A guardrail or host policy stopped one of the agent's steps. */
+    'blocked',
+    /** The user declined one of the agent's steps. */
+    'declined',
+    /** One of the agent's steps ran and failed. */
+    'failed',
+    /** The user or host stopped the turn. */
+    'cancelled',
+    /** A THEOREM invariant broke. */
+    'internal',
+];
+/** An error that carries a `kind`, from which hosts choose a status and the user's wording. */
+export class TheoremError extends Error {
+    kind;
+    copy;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.name = 'TheoremError';
+        this.kind = kind;
+        if (options?.copy)
+            this.copy = options.copy;
+    }
+}

package/esm/src/guardrails/thought-guard.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Thought guarding, under `guardrails.detect` at `thought`. A host that renders `thought` events shows the user what
+ * they say and loads what they link, as it does a reply: the canary, the
+ * system prompt and the user-data markers leak through a thought, and a URL
+ * the model was not given carries data out. Nothing in a thought stops a turn
+ * (`isGuardedOutput`); each leak is omitted and the rest of the thought
+ * released, or under `block` omitted with the rest of the thought.
+ *
+ * @module
+ */
+import { type Detection } from './detect-at.js';
+import type { UrlAllow } from './detectors.js';
+import { type GivenUrls } from './egress-urls.js';
+import { type LabelOverrides } from './labels.js';
+import type { GuardrailContext, GuardrailHit, ResolvedGuardrailPolicy } from './types.js';
+/** What a thought guard lets through: the text to show, and what it omitted from it. */
+interface ThoughtRelease {
+    text: string;
+    /** One hit per rule that omitted something; empty when nothing was. */
+    hits: GuardrailHit[];
+    /** What `guardrails.detect` found in the thought as it was read at `thought`. */
+    found?: Pick<Detection, 'action' | 'hits'>;
+}
+/** One provider call's (or Live cycle's) thought text, released as it clears. */
+interface ThoughtGuard {
+    /** Read the next thought chunk; the text now clear to show, leaks omitted. */
+    push(text: string): ThoughtRelease;
+    /** The thought ended: everything still held, leaks omitted. The next thought reads on from it. */
+    flush(): ThoughtRelease;
+    /** The tail of what was shown that a leak in the next call's thoughts could continue. */
+    carryOut(): string;
+}
+/** What a thought loses besides the canary and the system instruction. */
+interface ThoughtOmits {
+    /** The kernel's markers and the words of the canary note (`marker_leak`). */
+    markers?: boolean;
+    /** Images to a URL the model was not given, but for what this lets through (`ungiven_images`). */
+    images?: UrlAllow;
+    /** Links to a URL the model was not given, but for what this lets through (`ungiven_links`). */
+    links?: UrlAllow;
+    /** Whether `ungiven_images` reads the thought, here or in front: a link then leaves an image's markup to it. */
+    imagesRead?: boolean;
+}
+interface ThoughtGuardOptions {
+    omit?: ThoughtOmits;
+    /** The canary to omit from a thought. */
+    canary?: string;
+    /** The private stretches of the system instruction, whose words are omitted from a thought. */
+    privateSystem?: readonly string[];
+    /** The canary the turn planted, when a thought is not read for it: the echo and the note still know its place. */
+    planted?: string;
+    /** Rules whose leak ends what is shown of the thought, where the others are omitted alone. */
+    ends?: ReadonlySet<string>;
+    given?: GivenUrls;
+    labels?: LabelOverrides;
+    /** Shown text an earlier thought ended on (`carryOut`), read in front and never shown again. */
+    carry?: string;
+}
+/**
+ * The guard reads the thought as it will be shown, placeholders in: text
+ * released is final, and what is held changes only by omission. The canary
+ * and prompt echo are read a second time with each placeholder as the text it
+ * replaced, so a leak running on past one, or across one longer than its
+ * text, is omitted too.
+ */
+declare function createThoughtGuard(options: ThoughtGuardOptions): ThoughtGuard;
+/**
+ * A guard for a turn's thoughts: the detectors `guardrails.detect` sets at
+ * `thought`. `context` carries the canary and the system instruction only
+ * while their detectors read somewhere (`leakScopeOf`); at `thought`, `redact`
+ * omits a match, `block` ends what is shown of the thought there, and `flag`
+ * reports it and shows it.
+ */
+declare function thoughtGuardFor(policy: Pick<ResolvedGuardrailPolicy, 'detect' | 'allow'>, context: GuardrailContext, carry?: string): Promise<ThoughtGuard | undefined>;
+export type { ThoughtGuard, ThoughtGuardOptions, ThoughtOmits, ThoughtRelease };
+export { createThoughtGuard, thoughtGuardFor };