@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/surface/types.d.ts

@@ -8,6 +8,7 @@ import type { z } from 'zod';
  * - `text` (the default): as is, then scrubbed with every other answer.
  */
 export type SurfaceFieldFormat = 'secret' | 'url' | 'headers' | 'text';
+/** One value on a surface: what it holds and how the agent should read it. */
 export interface SurfaceField {
     value: unknown;
     /** The kind of value, as the agent should read it ("boolean", "one of …"). */
@@ -40,10 +41,12 @@ export interface SurfaceRejection {
 export type SurfaceEffect = 'read' | 'run' | 'write';
 /** Who a change is by, for the surface to record: notes are told only about the person's. */
 export type SurfaceAuthor = 'person' | 'agent';
+/** What an action run is told: its call id and who started it. */
 export interface SurfaceActionContext {
     callId: string;
     by: SurfaceAuthor;
 }
+/** What an action run returns: any rejections and its result. */
 export interface SurfaceActionOutcome {
     rejected?: SurfaceRejection[];
     /** What the action found or made; scrubbed like everything else. */
@@ -51,6 +54,7 @@ export interface SurfaceActionOutcome {
     /** The node the change landed on (local id), shown back to the agent. */
     node?: string;
 }
+/** Something the agent can do on a node: its description, effect, input schema, and `run`. */
 export interface SurfaceAction<Input = Record<string, unknown>> {
     description: string;
     effect: SurfaceEffect;
@@ -60,6 +64,7 @@ export interface SurfaceAction<Input = Record<string, unknown>> {
     intent?: boolean;
     run(input: Input, ctx: SurfaceActionContext): SurfaceActionOutcome | Promise<SurfaceActionOutcome>;
 }
+/** One part of a surface, with its fields and actions. */
 export interface SurfaceNode {
     /** Unique in its surface. The root's is `''`, addressed by the surface id alone. */
     id: string;
@@ -79,6 +84,7 @@ export interface SurfaceNode {
     point?(field?: string): void;
     actions?: Record<string, SurfaceAction<never>>;
 }
+/** A recorded change to a surface: its revision, author, and the nodes it touched. */
 export interface SurfaceChange {
     revision: number;
     by: SurfaceAuthor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",
@@ -15,7 +15,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/masudl-hub/theoremai"
+    "url": "git+https://github.com/masudl-hub/theoremai.git"
   },
   "license": "MIT",
   "module": "./esm/mod.js",
@@ -29,9 +29,6 @@
     "./providers": {
       "import": "./esm/src/providers/mod.js"
     },
-    "./providers/local": {
-      "import": "./esm/src/providers/local/mod.js"
-    },
     "./guardrails": {
       "import": "./esm/src/guardrails/mod.js"
     },
@@ -79,9 +76,6 @@
     },
     "./evals": {
       "import": "./esm/src/evals/mod.js"
-    },
-    "./providers/google/live": {
-      "import": "./esm/src/providers/google/live/mod.js"
     }
   },
   "scripts": {},
@@ -95,13 +89,11 @@
   "sideEffects": false,
   "dependencies": {
     "@eslint-community/regexpp": "4.12.2",
-    "@openrouter/ai-sdk-provider": "^3.0.0",
-    "ai": "^7.0.0",
-    "gpt-tokenizer": "^4.0.0",
-    "refa": "0.12.1"
+    "refa": "0.12.1",
+    "scslre": "0.3.0"
   },
   "peerDependencies": {
-    "zod": "^4.1.8"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@types/node": "^20.19.43"

package/esm/src/cli/commands/egress-compile.d.ts

@@ -1,17 +0,0 @@
-/**
- * `agents egress-compile`: reads a module's exported egress rules and writes
- * the table `egressPolicy` loads with them.
- *
- * @module
- */
-interface EgressCompileOptions {
-    /** Path or URL of the module exporting the rules. */
-    module: string;
-    /** The export holding the rules. Default `rules`. */
-    exportName?: string;
-    /** Where the compiled module is written. */
-    out: string;
-}
-/** Compiles the rules and writes the module; returns how many rules it read. */
-declare function egressCompileCommand({ module, exportName, out, }: EgressCompileOptions): Promise<number>;
-export { egressCompileCommand };

package/esm/src/cli/commands/egress-compile.js

@@ -1,25 +0,0 @@
-/**
- * `agents egress-compile`: reads a module's exported egress rules and writes
- * the table `egressPolicy` loads with them.
- *
- * @module
- */
-import { writeFile } from 'node:fs/promises';
-import { cwd } from 'node:process';
-/** `specifier` as a URL, relative paths read from the working directory. */
-function moduleUrl(specifier) {
-    return new URL(specifier, `file://${cwd()}/`).href;
-}
-/** Compiles the rules and writes the module; returns how many rules it read. */
-async function egressCompileCommand({ module, exportName = 'rules', out, }) {
-    const loaded = await import(moduleUrl(module));
-    const rules = loaded[exportName];
-    if (!Array.isArray(rules)) {
-        throw new Error(`${module} has no array export named ${exportName}`);
-    }
-    // Loaded here so no other command loads the regex engine.
-    const { compiledEgressModule, compileEgressRules } = await import('../../guardrails/egress-compiler.js');
-    await writeFile(out, compiledEgressModule(compileEgressRules(rules)));
-    return rules.length;
-}
-export { egressCompileCommand };

package/esm/src/guardrails/egress-policy.d.ts

@@ -1,27 +0,0 @@
-/**
- * `egressPolicy`: the bundled egress checks a host selects, with its own
- * rules added. The rules' automata come from `agents egress-compile`, so the
- * stream holds exactly the text a host match could still be under way in, as
- * it does for the bundled patterns.
- *
- * @module
- */
-import { type EgressChecks } from './egress.js';
-import { type CompiledEgressRules, type EgressRule } from './egress-rules.js';
-import type { EgressEnforcer } from './types.js';
-interface EgressPolicyOptions {
-    /** Host rules, blocked on alongside the bundled checks. */
-    rules?: readonly EgressRule[];
-    /** `compiledEgressRules` from the module `agents egress-compile` wrote for `rules`. */
-    compiled?: CompiledEgressRules;
-    /**
-     * The bundled checks: `true` (the default) runs each at its default, `false`
-     * none, and an object switches the ones it names (`EgressChecks`). The
-     * system-prompt leak checks run either way.
-     */
-    bundled?: boolean | EgressChecks;
-}
-/** An egress enforce that blocks on each host rule and on the bundled checks `bundled` selects. */
-declare function egressPolicy({ rules, compiled, bundled, }?: EgressPolicyOptions): EgressEnforcer;
-export type { EgressPolicyOptions };
-export { egressPolicy };

package/esm/src/guardrails/egress-policy.js

@@ -1,76 +0,0 @@
-/**
- * `egressPolicy`: the bundled egress checks a host selects, with its own
- * rules added. The rules' automata come from `agents egress-compile`, so the
- * stream holds exactly the text a host match could still be under way in, as
- * it does for the bundled patterns.
- *
- * @module
- */
-import { collectEgressHits, egressChecksProblem, egressScope, hitsEnforcer, NO_CHECKS, registerEgressChecks, resolveEgressChecks, } from './egress.js';
-import { assertEgressRules, EGRESS_COMPILER_VERSION, globalPattern, ruleFingerprint, } from './egress-rules.js';
-import { createEgressStream, registerStreamPlan, } from './egress-stream.js';
-import { TheoremError } from './error.js';
-import { hitFromSpan } from './hits.js';
-/** Every host rule's matches in `text`. An empty match is not a hit. */
-function ruleHits(text, rules) {
-    const hits = [];
-    for (const { rule, severity, pattern } of rules) {
-        for (const match of text.matchAll(pattern)) {
-            if (!match[0])
-                continue;
-            hits.push(hitFromSpan(text, { start: match.index, end: match.index + match[0].length }, rule, severity));
-        }
-    }
-    return hits;
-}
-/** A compiled table that no longer matches `rules` would hold for the wrong patterns. */
-function assertCompiledFor(rules, compiled) {
-    const stale = (why) => configError(`the compiled rules ${why}; run \`agents egress-compile\` again`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    if (compiled?.compiler !== EGRESS_COMPILER_VERSION) {
-        // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        throw stale(`come from compiler ${compiled?.compiler}, this one is ${EGRESS_COMPILER_VERSION}`);
-    }
-    const want = ruleFingerprint(rules);
-    if (JSON.stringify(compiled.rules) !== JSON.stringify(want)) {
-        throw stale('were compiled from different rules'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-    }
-}
-function configError(message) {
-    return new TheoremError('config', `egressPolicy: ${message}`);
-}
-function assertEgressChecks(checks) {
-    const problem = egressChecksProblem('bundled', checks);
-    if (problem !== undefined)
-        throw configError(problem);
-}
-/** An egress enforce that blocks on each host rule and on the bundled checks `bundled` selects. */
-function egressPolicy({ rules = [], compiled, bundled = true, } = {}) {
-    assertEgressRules(rules);
-    if (rules.length > 0) {
-        if (compiled === undefined) {
-            throw configError('rules need the compiled table `agents egress-compile` writes for them'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        }
-        assertCompiledFor(rules, compiled);
-    }
-    assertEgressChecks(bundled);
-    const checks = bundled === false ? NO_CHECKS : resolveEgressChecks(bundled === true ? {} : bundled);
-    const host = rules.map(({ rule, pattern, severity }) => ({
-        rule,
-        severity: severity ?? 'high',
-        pattern: globalPattern(pattern),
-    }));
-    const enforce = hitsEnforcer((text, context) => {
-        const hits = collectEgressHits(text, egressScope(context), checks);
-        hits.push(...ruleHits(text, host));
-        return hits;
-    });
-    const scan = compiled && host.length > 0 ? { automaton: compiled.automaton, rules: host } : undefined;
-    registerStreamPlan(enforce, (context) => createEgressStream({
-        checks,
-        ...(scan ? { host: scan } : {}),
-        ...(context.givenUrls ? { given: context.givenUrls } : {}),
-    }));
-    registerEgressChecks(enforce, checks);
-    return enforce;
-}
-export { egressPolicy };

package/esm/src/guardrails/egress-rules.d.ts

@@ -1,54 +0,0 @@
-/**
- * Host egress rules: the patterns a host adds to (or runs instead of) the
- * bundled egress policy, and the tables `agents egress-compile` writes for
- * them. Shared by the build-time compiler and `egressPolicy`.
- *
- * @module
- */
-import type { Severity } from './types.js';
-/** One host egress rule: a reply matching `pattern` is blocked under `rule`. */
-interface EgressRule {
-    /** The rule id hits carry, e.g. `acme.account-number`. `egress.` ids are the bundled policy's. */
-    rule: string;
-    /** Matched on the reply as written. No sticky (`y`) flag; `g` is implied. */
-    pattern: RegExp;
-    /** Default `high`. */
-    severity?: Severity;
-}
-/**
- * An automaton over UTF-16 code units, as tables.
- *
- * - `classStarts`: first code unit of each character class; class k covers
- *   `[classStarts[k], classStarts[k+1])`.
- * - `charsets`: each charset as the sorted class ids it contains.
- * - `initials`: the initial node of each pattern.
- * - `nodes`: each node as `[pattern, final (0/1), target, charset, target, charset, ...]`.
- */
-interface EgressAutomatonData {
-    classStarts: readonly number[];
-    charsets: readonly (readonly number[])[];
-    initials: readonly number[];
-    nodes: readonly (readonly number[])[];
-}
-/** What `compileEgressRules` writes: the rules it read, and their automaton. */
-interface CompiledEgressRules {
-    /** `EGRESS_COMPILER_VERSION` of the compiler that wrote it. */
-    compiler: number;
-    /** Each rule's id and pattern, in order: `egressPolicy` refuses a table that no longer matches its rules. */
-    rules: readonly {
-        rule: string;
-        source: string;
-        flags: string;
-    }[];
-    automaton: EgressAutomatonData;
-}
-/** Bumped whenever the compiled table's layout or meaning changes. */
-declare const EGRESS_COMPILER_VERSION = 1;
-/** Rule ids are non-empty, unique and not the bundled policy's; patterns are not sticky. */
-declare function assertEgressRules(rules: readonly EgressRule[]): void;
-/** The rules as a compiled table records them. */
-declare function ruleFingerprint(rules: readonly EgressRule[]): CompiledEgressRules['rules'];
-/** The pattern, global, for scanning every match. */
-declare function globalPattern(pattern: RegExp): RegExp;
-export type { CompiledEgressRules, EgressAutomatonData, EgressRule };
-export { assertEgressRules, EGRESS_COMPILER_VERSION, globalPattern, ruleFingerprint };

package/esm/src/guardrails/egress-rules.js

@@ -1,49 +0,0 @@
-/**
- * Host egress rules: the patterns a host adds to (or runs instead of) the
- * bundled egress policy, and the tables `agents egress-compile` writes for
- * them. Shared by the build-time compiler and `egressPolicy`.
- *
- * @module
- */
-import { TheoremError } from './error.js';
-/** Bumped whenever the compiled table's layout or meaning changes. */
-const EGRESS_COMPILER_VERSION = 1;
-const RESERVED_PREFIX = 'egress.';
-function configError(message) {
-    return new TheoremError('config', message);
-}
-/** Rule ids are non-empty, unique and not the bundled policy's; patterns are not sticky. */
-function assertEgressRules(rules) {
-    const seen = new Set();
-    for (const { rule, pattern } of rules) {
-        if (typeof rule !== 'string' || !rule.trim()) {
-            throw configError('egress rule ids must be non-empty strings'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        }
-        if (rule.startsWith(RESERVED_PREFIX)) {
-            throw configError(
-            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            `egress rule ${rule}: ids starting "${RESERVED_PREFIX}" are the bundled policy's`);
-        }
-        if (seen.has(rule)) {
-            throw configError(`egress rule ${rule} is listed twice`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        }
-        seen.add(rule);
-        if (!(pattern instanceof RegExp)) {
-            throw configError(`egress rule ${rule}: pattern must be a RegExp`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-        }
-        if (pattern.sticky) {
-            throw configError(
-            // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
-            `egress rule ${rule}: a sticky (y) pattern only matches where the last one ended`);
-        }
-    }
-}
-/** The rules as a compiled table records them. */
-function ruleFingerprint(rules) {
-    return rules.map(({ rule, pattern }) => ({ rule, source: pattern.source, flags: pattern.flags }));
-}
-/** The pattern, global, for scanning every match. */
-function globalPattern(pattern) {
-    return new RegExp(pattern.source, pattern.global ? pattern.flags : `${pattern.flags}g`);
-}
-export { assertEgressRules, EGRESS_COMPILER_VERSION, globalPattern, ruleFingerprint };

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

@@ -1,30 +0,0 @@
-export type LexiconParams = Record<string, string | number>;
-/** Keys are stable API. */
-export declare const LEXICON_KEYS: readonly ["continue.instruction", "canary.bind_note", "user_data.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "compaction.request", "compaction.tool_call", "compaction.tool_result", "egress.default_repair_guidance", "egress.refusal", "egress.rejection", "egress.invalid_verdict", "egress.policy_failed", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.input_invalid", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.output_invalid", "tool.not_wired_t1", "tool.not_loaded_t2", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type"];
-export type LexiconKey = (typeof LEXICON_KEYS)[number];
-/**
- * The keys a browser client words or writes: what the user reads (errors,
- * attachment and voice problems, session states) and the tool lines the client
- * puts into history. Only these overrides travel to the browser; the rest
- * (repair prompts, canary, taint, egress) stay on the host.
- */
-export declare const CLIENT_LEXICON_KEYS: readonly ["attachments.too_many_files", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "error.config", "error.request", "error.input", "error.action", "error.auth", "error.rate_limit", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "session.abandon_gated", "session.tool_denied", "session.sign_in", "session.gate_expired", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "tool.awaiting_user", "tool.completed_hidden", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty"];
-export type ClientLexiconKey = (typeof CLIENT_LEXICON_KEYS)[number];
-/** Host-supplied replacement templates, `{param}` placeholders included. */
-export type LexiconOverrides = Partial<Record<LexiconKey, string>>;
-/**
- * What each key is: when the kernel uses it, who reads it, and the placeholders it takes. For the
- * builders who replace the wording; the field catalog reads it for `lexicon.<key>`.
- */
-export declare const LEXICON_NOTES: Record<LexiconKey, string>;
-export declare function lexiconPlaceholders(key: LexiconKey): readonly string[];
-/** `owner` names where the overrides came from in the error. */
-export declare function validateLexiconOverrides(entries: LexiconOverrides, owner: string): void;
-/** Process-wide; a profile's own `lexicon` wins over these. */
-export declare function overrideLexicon(entries: LexiconOverrides): void;
-export declare function resetLexicon(): void;
-export declare function lexiconText(key: LexiconKey, params?: LexiconParams, profileLexicon?: LexiconOverrides): string;
-/** Overrides only, resolved on the host; keys without one fall back to the defaults the client ships with. */
-export declare function clientLexicon(profileLexicon?: LexiconOverrides): LexiconOverrides;
-/** Ignores overrides. */
-export declare function lexiconDefault(key: LexiconKey, params?: LexiconParams): string;