theorum 0.1.14 → 1.0.0

package/esm/src/providers/{google-tap.js → shared/upstream-tap.js}

@@ -1,25 +1,24 @@
-import { exposeForTests } from './expose-for-tests.js';
 const SECRET_HEADER = /key|auth|cookie|secret|token/i;
-function tapeHeaderValue(key, value) {
+export function tapeHeaderValue(key, value) {
     if (SECRET_HEADER.test(key)) {
         return '[redacted]';
     }
     return value;
 }
-function tapeHeaders(headers) {
+export function tapeHeaders(headers) {
     const out = {};
     for (const [key, value] of new Headers(headers).entries()) {
         out[key] = tapeHeaderValue(key, value);
     }
     return out;
 }
-function throwRow(err) {
+export function throwRow(err) {
     if (err instanceof Error) {
         return { eventType: 'http_throw', name: err.name, message: err.message };
     }
     return { eventType: 'http_throw', name: 'Error', message: String(err) };
 }
-function tapFetch(tap, send = fetch) {
+export function tapFetch(tap, send = fetch) {
     return async (url, init) => {
         const method = init?.method ?? 'GET';
         tap?.({
@@ -46,5 +45,3 @@ function tapFetch(tap, send = fetch) {
         }
     };
 }
-export { tapFetch };
-exposeForTests('google-tap', { tapeHeaderValue, tapeHeaders, throwRow, tapFetch });

package/esm/src/providers/shared/upstream-tape.d.ts

@@ -0,0 +1,6 @@
+export declare function isImageBlob(rec: Record<string, unknown>): boolean;
+export declare function scrubEntry(rec: Record<string, unknown>, key: string, nested: unknown): Promise<[string, unknown]>;
+export declare function scrubRecord(rec: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function scrubUpstream(value: unknown): Promise<unknown>;
+export declare function redactCanaryInTree(value: unknown, canary: string): unknown;
+export declare function tapeUpstream(value: unknown, canary: string): Promise<unknown>;

package/esm/src/providers/{gemini-tape.js → shared/upstream-tape.js}

@@ -1,8 +1,7 @@
-import { OMIT_CANARY } from '../kernel/engine/boundary.js';
-import { sha256 } from '../kernel/engine/hash.js';
-import { mapStrings } from '../kernel/engine/tree.js';
-import { exposeForTests } from './expose-for-tests.js';
-function isImageBlob(rec) {
+import { OMIT_CANARY } from '../../guardrails/canary.js';
+import { sha256 } from '../../kernel/engine/hash.js';
+import { mapStrings } from '../../kernel/engine/tree.js';
+export function isImageBlob(rec) {
     if (rec.type === 'image' || rec.type === 'media') {
         return true;
     }
@@ -11,13 +10,13 @@ function isImageBlob(rec) {
     }
     return false;
 }
-async function scrubEntry(rec, key, nested) {
+export async function scrubEntry(rec, key, nested) {
     if (key === 'data' && typeof nested === 'string' && isImageBlob(rec)) {
         return [key, await sha256(nested)];
     }
-    return [key, await scrubGemini(nested)];
+    return [key, await scrubUpstream(nested)];
 }
-function scrubRecord(rec) {
+export function scrubRecord(rec) {
     return Promise.all(Object.entries(rec).map(([key, nested]) => scrubEntry(rec, key, nested))).then((pairs) => {
         const out = Object.fromEntries(pairs);
         if (typeof rec.data === 'string' && isImageBlob(rec)) {
@@ -26,30 +25,21 @@ function scrubRecord(rec) {
         return out;
     });
 }
-function scrubGemini(value) {
+export function scrubUpstream(value) {
     if (Array.isArray(value)) {
-        return Promise.all(value.map((item) => scrubGemini(item)));
+        return Promise.all(value.map((item) => scrubUpstream(item)));
     }
     if (value && typeof value === 'object') {
         return scrubRecord(value);
     }
     return Promise.resolve(value);
 }
-function redactCanaryInTree(value, canary) {
+export function redactCanaryInTree(value, canary) {
     if (!canary) {
         return value;
     }
     return mapStrings(value, (text) => text.replaceAll(canary, OMIT_CANARY));
 }
-async function tapeGemini(value, canary) {
-    return redactCanaryInTree(await scrubGemini(value), canary);
+export async function tapeUpstream(value, canary) {
+    return redactCanaryInTree(await scrubUpstream(value), canary);
 }
-export { tapeGemini };
-exposeForTests('gemini-tape', {
-    isImageBlob,
-    scrubEntry,
-    scrubRecord,
-    scrubGemini,
-    redactCanaryInTree,
-    tapeGemini,
-});

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

@@ -0,0 +1,27 @@
+import type { KeyVault } from '../kernel/types.js';
+/** OpenAI-gateway credentials for `openAi` profiles (OpenRouter or compatible). */
+export interface OpenAiGatewayConfig {
+    /**
+     * Multi-slot credential vault (same `KEY_SLOTS` shape as Google).
+     * When `keySlot` is set on the turn, the adapter reads `vault[keySlot]`.
+     */
+    vault?: KeyVault;
+    /**
+     * Single-key fallback when the profile does not pin `model.key` / `keySlot`.
+     * Ignored when `keySlot` is set (vault is required then).
+     */
+    apiKey?: string;
+    baseUrl?: string;
+    siteUrl?: string;
+    siteName?: string;
+    fetch?: typeof fetch;
+}
+/** Host-supplied config for the local OpenAI-compat provider. */
+export interface LocalProviderConfig {
+    /**
+     * Base URL of the OpenAI-compat server (no trailing slash).
+     * Defaults to `http://127.0.0.1:11434`.
+     */
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}

package/esm/src/providers/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "theorum",
-  "version": "0.1.14",
-  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
+  "version": "1.0.0",
+  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",
     "ai",
@@ -29,12 +29,15 @@
     "./providers": {
       "import": "./esm/src/providers/mod.js"
     },
-    "./openrouter": {
-      "import": "./esm/src/providers/openrouter-mod.js"
+    "./providers/local": {
+      "import": "./esm/src/providers/local/mod.js"
     },
     "./guardrails": {
       "import": "./esm/src/guardrails/mod.js"
     },
+    "./guardrails/testing": {
+      "import": "./esm/src/guardrails/testing.js"
+    },
     "./observability": {
       "import": "./esm/src/observability/mod.js"
     },
@@ -49,9 +52,6 @@
     },
     "./presets/google": {
       "import": "./esm/src/presets/google.js"
-    },
-    "./streaming": {
-      "import": "./esm/src/streaming/mod.js"
     }
   },
   "scripts": {},
@@ -64,8 +64,12 @@
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.0",
     "gpt-tokenizer": "^4.0.0",
+    "zod": "^4.1.8",
     "@deno/shim-deno": "~0.18.0"
   },
+  "peerDependencies": {
+    "zod": "^4.1.8"
+  },
   "devDependencies": {
     "@types/node": "^20.9.0"
   },

package/docs/cli.md

@@ -1,97 +0,0 @@
-# CLI (`theorum/cli`)
-
-Profile inspection and stress-test CLI. On npm this entry is also the
-`theorum` binary. Hosts must register profiles (and providers) in-process
-before commands that execute turns — the CLI does not embed app profiles.
-
-## Export
-
-| Field | Value |
-| --- | --- |
-| Import | `theorum/cli` / `jsr:@theorum/core/cli` |
-| Module | `src/cli/index.ts` |
-| Binary | `theorum` (npm `bin`) |
-
-## Ownership
-
-| Path | Role |
-| --- | --- |
-| `src/cli/index.ts` | Argument parser + command dispatch |
-| `src/cli/commands/*` | `bench`, `fuzz`, `test`, `run`, `profile` |
-| `src/cli/matrix/*` | Permutation synthesizer + fixtures |
-
-## Commands
-
-```text
-theorum <command> [options]
-```
-
-| Command | Purpose |
-| --- | --- |
-| `bench` | Synthetic kernel performance benchmark (`--chunks`, `--iterations`, `--warmup`) |
-| `fuzz` | Adversarial guardrail fuzzer |
-| `test` | Stress matrix or custom profile tests (`--profile`, `--all`, `--lite`, `--matrix`, `--mode`, `--search`, `--map`) |
-| `run` | Execute a turn with streaming output (`--profile`, `--prompt`, `--mode`, …) |
-| `profile list` / `profile show <id>` | Inspect registered profile blueprints |
-| `help` | Usage |
-
-Exit code `1` on failed `test` runs. `run` requires `--profile` (or `-p`).
-
-```bash
-theorum test --profile my.agent --matrix
-theorum run --profile my.agent --prompt "ping"
-```
-
-## Matrix and fixtures
-
-| Module | Role |
-| --- | --- |
-| `matrix/synthesizer.ts` | Builds valid permutation cases (modes, optional tools) |
-| `matrix/fixtures.ts` | Shared harness fixtures (not product personas) |
-
-The matrix respects profile allowlists — e.g. `--search` only applies when
-`googleSearch` is allowlisted.
-
-## Exported API
-
-The entry module is the CLI program itself (side-effect main when run as a
-bin). Prefer `deno task theorum` / `npx theorum` over importing commands in
-application code.
-
-```theorum-evidence
-{
-  "sections": {
-    "Export": {
-      "supports": [
-        { "kind": "source", "path": "src/cli/index.ts" },
-        { "kind": "config", "path": "package.json" }
-      ]
-    },
-    "Ownership": {
-      "supports": [
-        { "kind": "source", "path": "src/cli/index.ts" },
-        { "kind": "graph", "path": "docs/_map.mjs" }
-      ]
-    },
-    "Commands": {
-      "supports": [
-        { "kind": "source", "path": "src/cli/index.ts" },
-        { "kind": "source", "path": "src/cli/commands/run.ts" },
-        { "kind": "contract_test", "path": "tests/cli/cli.test.ts" }
-      ]
-    },
-    "Matrix and fixtures": {
-      "supports": [
-        { "kind": "source", "path": "src/cli/matrix/synthesizer.ts" },
-        { "kind": "contract_test", "path": "tests/cli/cli.test.ts" }
-      ]
-    },
-    "Exported API": {
-      "supports": [
-        { "kind": "source", "path": "src/cli/index.ts" },
-        { "kind": "contract_test", "path": "tests/cli/cli.test.ts" }
-      ]
-    }
-  }
-}
-```

package/docs/guardrails.md

@@ -1,178 +0,0 @@
-# Guardrails (`theorum/guardrails`)
-
-Generic inbound and outbound guardrail primitives. App-specific policy,
-product copy, and channel UX remain host-owned — this entry ships reusable
-detectors, sanitizers, public error mapping, and optional per-day quota slots.
-
-## Export
-
-| Field | Value |
-| --- | --- |
-| Import | `theorum/guardrails` / `jsr:@theorum/core/guardrails` |
-| Module | `src/guardrails/mod.ts` |
-| Also on | Root `theorum` re-exports common error/sanitize/quota helpers |
-
-## Ownership
-
-Owns every module under `src/guardrails/`.
-
-| Module | Role |
-| --- | --- |
-| `error.ts` | `TheorumError`, `publicError`, abort helpers |
-| `sanitize.ts` | Turn + text sanitization |
-| `injection.ts` | Prompt-injection span patterns |
-| `sensitive.ts` | Credential / PII span patterns |
-| `normalize.ts` | Detection normalization |
-| `quota.ts` | In-memory daily slots for HTTP hosts |
-
-## Public errors
-
-`TheorumError` marks expected contract failures. Never show raw internal
-messages to end users — map through `publicError(err)` (or `toErrorEvent` for
-streams).
-
-| Internal marker | Public copy |
-| --- | --- |
-| `UPSTREAM_FAILED` | `PUBLIC_UNAVAILABLE` |
-| `canary leaked` / egress violations | `PUBLIC_CANARY` |
-| Abort | `PUBLIC_CANCELLED` |
-| Tool / MIME / size denials | `PUBLIC_ACTION` / `PUBLIC_FILE_*` |
-
-`describeError` returns structured detail for logs. `throwIfAborted(signal)`
-rethrows `AbortError` when a turn should stop early.
-
-Exact-message and regex rules live in `error.ts` (`EXACT`, `RULES` arrays) —
-extend there when adding new stable public mappings.
-
-## Sanitization
-
-Driven by profile `guardrails.sanitizeInput` and `guardrails.redactSensitive`
-(default both on in `sanitizeText` unless overridden).
-
-| API | Role |
-| --- | --- |
-| `sanitizeText` | Strip injection + sensitive spans from one string |
-| `sanitizeTurnRequest` | Full turn: text, slots, dynamic tool args, blobs |
-| `sanitizeProjectId` | Bound project id strings (`PROJECT_ID_MAX`) |
-
-`injectionSpans` and `sensitiveSpans` return `RedactSpan[]`; `applySpans`
-(from observability) performs replacement. Detection runs on normalized text
-(`normalizeForDetection`).
-
-### Injection categories (non-exhaustive)
-
-Patterns target untrusted user text before provider submission:
-
-- Instruction override (`ignore previous instructions`, `disregard rules`, …)
-- Mode hijack (`developer mode`, `jailbreak`, `DAN`, `do anything now`)
-- Safety bypass (`disable safety filters`, …)
-- Role / delimiter forgery (`<system>`, `[System Message]`, ChatML tokens)
-- Prompt exfiltration (`reveal your system prompt`, …)
-- Multilingual override fragments
-
-False-positive tuning belongs in `injection.ts` tests
-(`tests/guardrails/false-positives.test.ts`).
-
-## Sensitive data
-
-| API | Role |
-| --- | --- |
-| `sensitiveSpans` | Credential / PII span detection |
-| `redactSensitiveOnly` | Model output path without injection patterns |
-
-`sensitiveSpans` redacts credential-like and PII patterns from inbound text and,
-when enabled, outbound paths. Use `redactSensitiveOnly` on model output when
-injection patterns should not run.
-
-## Quota
-
-**Not** enforced inside `runTurn`. HTTP hosts call:
-
-```ts
-const ip = clientIp(peer, req);
-if (skipQuota(peer, req)) { /* local dev */ }
-const status = takeSlot(profile, ip, Date.now());
-// 'ok' | 'busy' | 'quota' | 'not_configured'
-try {
-  await runTurn(...);
-} finally {
-  releaseSlot(profile, ip);
-}
-```
-
-| Status | Meaning |
-| --- | --- |
-| `ok` | Slot taken; increment daily count |
-| `busy` | Same ip/profile already in flight |
-| `quota` | `perDay` exhausted |
-| `not_configured` | Profile has no `guardrails.quota` |
-
-`quotaMessage(profile)` uses `identity.handle` for user-facing limit copy.
-`resetSlots()` clears in-memory state (tests).
-
-## Exported API
-
-From `src/guardrails/mod.ts`:
-
-| Group | Symbols |
-| --- | --- |
-| Public errors | `describeError`, `isAbortError`, `publicError`, `TheorumError`, `throwIfAborted`, `toErrorEvent`, `PUBLIC_ACTION`, `PUBLIC_CANARY`, `PUBLIC_CANCELLED`, `PUBLIC_FILE_COUNT`, `PUBLIC_FILE_SIZE`, `PUBLIC_FILE_TYPE`, `PUBLIC_GENERIC`, `PUBLIC_IMAGE_SIZE`, `PUBLIC_UNAVAILABLE`, `UPSTREAM_FAILED` |
-| Injection / sensitive | `injectionSpans`, `sensitiveSpans` |
-| Quota | `QuotaSlotStatus`, `clientIp`, `quotaMessage`, `releaseSlot`, `resetSlots`, `skipQuota`, `takeSlot` |
-| Sanitize | `PROJECT_ID_MAX`, `sanitizeProjectId`, `sanitizeText`, `sanitizeTurnRequest` |
-
-```theorum-evidence
-{
-  "sections": {
-    "Export": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/mod.ts" },
-        { "kind": "config", "path": "package.json" }
-      ]
-    },
-    "Ownership": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/mod.ts" },
-        { "kind": "graph", "path": "docs/_map.mjs" }
-      ]
-    },
-    "Public errors": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/error.ts" },
-        { "kind": "contract_test", "path": "tests/guardrails/error.test.ts" }
-      ]
-    },
-    "Sanitization": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/sanitize.ts" },
-        { "kind": "source", "path": "src/guardrails/injection.ts" },
-        { "kind": "contract_test", "path": "tests/guardrails/sanitize.test.ts" }
-      ]
-    },
-    "Injection categories (non-exhaustive)": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/injection.ts" },
-        { "kind": "contract_test", "path": "tests/guardrails/false-positives.test.ts" }
-      ]
-    },
-    "Sensitive data": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/sensitive.ts" },
-        { "kind": "contract_test", "path": "tests/guardrails/sanitize.test.ts" }
-      ]
-    },
-    "Quota": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/quota.ts" },
-        { "kind": "contract_test", "path": "tests/guardrails/quota.test.ts" }
-      ]
-    },
-    "Exported API": {
-      "supports": [
-        { "kind": "source", "path": "src/guardrails/mod.ts" },
-        { "kind": "contract_test", "path": "tests/guardrails/error.test.ts" }
-      ]
-    }
-  }
-}
-```

package/docs/host.md

@@ -1,97 +0,0 @@
-# Host (`theorum/host`)
-
-Optional Deno HTTP helpers for host applications. **Not** part of the turn
-kernel — import only when you want shared reply/status glue and cutout-trace
-flushing without reimplementing it per route.
-
-## Export
-
-| Field | Value |
-| --- | --- |
-| Import | `theorum/host` / `jsr:@theorum/core/host` |
-| Module | `src/host/mod.ts` |
-
-## Ownership
-
-| Path | Role |
-| --- | --- |
-| `src/host/reply.ts` | JSON responses + HTTP status constants |
-| `src/host/mint-trace.ts` | Cutout mint trace flush helpers |
-| `src/host/mod.ts` | Public barrel |
-
-## HTTP replies
-
-| Export | Role |
-| --- | --- |
-| `json(status, body, cors)` | JSON `Response` with merged CORS headers |
-| `caughtStatus(err)` | `400` for `TheorumError`, else `500` |
-| `HTTP_OK` | `200` |
-| `HTTP_BUSY` | `429` |
-| `HTTP_NOT_FOUND` | `404` |
-| `HTTP_METHOD` | `405` |
-
-Example:
-
-```ts
-import { caughtStatus, HTTP_BUSY, json } from "theorum/host";
-
-try {
-  return json(200, { ok: true }, cors);
-} catch (err) {
-  return json(caughtStatus(err), { error: publicError(err) }, cors);
-}
-```
-
-Quota busy responses typically use `HTTP_BUSY` after `takeSlot` returns `busy`.
-
-## Cutout mint trace
-
-| Export | Role |
-| --- | --- |
-| `flushMintTrace` | Flush pending cutout mint records after a turn |
-| `CutoutTape` | Tape type for mint/cutout correlation |
-
-Use when your Deno HTTP host records mint/cutout telemetry alongside THEORUM
-turns. Skip entirely for non-HTTP or non-Deno hosts.
-
-## Exported API
-
-Live list: `src/host/mod.ts` (`json`, status constants, `caughtStatus`,
-`flushMintTrace`, `CutoutTape`).
-
-```theorum-evidence
-{
-  "sections": {
-    "Export": {
-      "supports": [
-        { "kind": "source", "path": "src/host/mod.ts" },
-        { "kind": "config", "path": "package.json" }
-      ]
-    },
-    "Ownership": {
-      "supports": [
-        { "kind": "source", "path": "src/host/mod.ts" },
-        { "kind": "graph", "path": "docs/_map.mjs" }
-      ]
-    },
-    "HTTP replies": {
-      "supports": [
-        { "kind": "source", "path": "src/host/reply.ts" },
-        { "kind": "contract_test", "path": "tests/host/host.test.ts" }
-      ]
-    },
-    "Cutout mint trace": {
-      "supports": [
-        { "kind": "source", "path": "src/host/mint-trace.ts" },
-        { "kind": "contract_test", "path": "tests/host/host.test.ts" }
-      ]
-    },
-    "Exported API": {
-      "supports": [
-        { "kind": "source", "path": "src/host/mod.ts" },
-        { "kind": "contract_test", "path": "tests/host/host.test.ts" }
-      ]
-    }
-  }
-}
-```