theorum 0.1.10 → 0.1.13

package/README.md

@@ -288,6 +288,8 @@ import { createProvider, runTurn } from "jsr:@theorum/core";
 const provider = createProvider(profile, {
   gemini: { vault: hostGeminiKeyVault, fetch },
   openRouter: { apiKey: hostSecrets.openRouterApiKey },
+  // openAi + local — optional; default baseUrl http://127.0.0.1:11434
+  local: { baseUrl: hostResolvedLocalBaseUrl },
 });
 
 for await (const event of runTurn({ profile: profile.id, input: { text: "…" } }, provider)) {
@@ -302,10 +304,21 @@ for await (const event of runTurn({ profile: profile.id, input: { text: "…" }
 | `geminiInteractions` + `google` | Google Interactions (chat, image, speech) |
 | `openAi` + `openrouter` (chat) | OpenRouter chat completions |
 | `openAi` + `openrouter` (speech role) | OpenRouter `/audio/speech` |
+| `openAi` + `local` | Local OpenAI-compatible `/v1/chat/completions` (Ollama, llama.cpp, vLLM, LM Studio, …) |
 
-OpenRouter uses Vercel AI SDK Core inside THEORUM's provider adapter. The adapter still emits THEORUM `TurnEvent` values and preserves raw provider evidence for citations/provenance where the normalized SDK stream does not expose enough detail.
+Local adapters take an optional `baseUrl` (default `http://127.0.0.1:11434`). THEORUM does not read `OLLAMA_HOST`; hosts that honor that env should resolve it and pass `local.baseUrl`. History `parts` (including images) are mapped on the wire; `done` events include a normalized `stop` from the OpenAI `finish_reason`.
 
-Advanced OpenRouter exports live under `theorum/openrouter` (`createOpenRouterProvider`, `toOpenRouterPayload`, …). Prefer `createProvider` for turns unless the host needs to wire the OpenRouter adapter directly.
+OpenRouter uses Vercel AI SDK Core inside THEORUM's provider adapter. That stack
+loads **lazily on the first `complete` call** for `openAi` + `openrouter` chat —
+not when importing THEORUM, and not for Google or local providers. The adapter
+still emits THEORUM `TurnEvent` values and preserves raw provider evidence for
+citations/provenance where the normalized SDK stream does not expose enough detail.
+
+Advanced OpenRouter exports live under `theorum/openrouter` (`createOpenRouterProvider`,
+`toOpenRouterPayload`, …). Prefer `createProvider` for turns unless the host needs
+to wire the OpenRouter adapter directly. Direct local construction is also available
+as `createLocalProvider` from the main / providers entrypoints. Importing
+`theorum/openrouter` loads the Vercel SDK immediately.
 
 ---
 
@@ -328,6 +341,16 @@ Internal files remain present in source for maintainability, but package consume
 
 ---
 
+## Documentation
+
+| Doc | Topic |
+| :--- | :--- |
+| [`docs/SECRETS.md`](docs/SECRETS.md) | Host-owned credentials; `createProvider` args; no env reads |
+| [`docs/COMPACTION.md`](docs/COMPACTION.md) | History / input meters, lazy BPE, `trigger`, signals |
+| [`docs/STOP.md`](docs/STOP.md) | Normalized `done.stop`, resume policy, `continueFrom` |
+
+---
+
 ## Development
 
 ```bash

package/docs/COMPACTION.md

@@ -0,0 +1,227 @@
+# Compaction
+
+Optional, profile-driven compaction for managing conversation history when it
+approaches a model's context window limit.
+
+The kernel owns the trigger, the split logic, and the timing. The host (or the
+kernel itself, for the easy path) owns the execution and reassembly.
+
+## Why
+
+Long-running conversations accumulate history that eventually exceeds the
+model's context window. Compaction types the trigger and split into a config
+block; the host still owns how summaries are shaped and persisted.
+
+## Configuration
+
+Compaction is configured per model in a profile's `model.config`:
+
+```ts
+const speakerModel: ModelSpec = {
+  apiId: "gemini-3.5-flash",
+  // ...existing model config...
+  compaction: {
+    maxTokens: 2000,           // budget for the chosen meter
+    compactAt: 0.75,           // fire when 75% full
+    previousExchanges: 8,      // keep last 8 exchanges verbatim
+    profile: "my.compactor",   // profile that does the compacting
+    timing: "after",           // 'before' or 'after' the turn
+    meter: "history",          // default; or "input"
+  },
+};
+```
+
+### `meter`
+
+What the threshold compares:
+
+| Value | Meaning |
+| --- | --- |
+| `'history'` (default) | Conversational history only. Host `input.historyTokens`, else local estimate of `input.history`. Excludes system, tool schemas, and this-turn attachments. |
+| `'input'` | Full-prompt provider input tokens. For `timing: 'before'`, pass previous turn's usage as `input.inputTokens`. For `timing: 'after'`, the kernel uses this turn's `tokens.input`. |
+
+Provider `tokens` events always stay on the stream for billing / observability.
+With `meter: 'history'` they do **not** gate compaction. With `meter: 'input'`
+they (or host-threaded `inputTokens`) **do**.
+
+### `maxTokens`
+
+Budget compared as `tokens > compactAt * maxTokens`.
+
+- With `meter: 'history'`: set from the model's context window minus known fixed
+  costs (system, tools, output headroom).
+- With `meter: 'input'`: set as a full-prompt ceiling (or baseline + headroom).
+  Small history-style budgets (e.g. 2000) will fire often if system + tools are
+  large — that is expected for this meter.
+
+### How `meter: 'history'` counts
+
+1. If the host sets `input.historyTokens`, that value is used.
+2. Otherwise the kernel estimates from `input.history` (or `[]`):
+   - **Text** — tiktoken `o200k_base` (via `gpt-tokenizer`) over `content`,
+     text `parts`, and `tool_calls` arguments. Declared local BPE; Gemini has
+     no open JS tokenizer — pass `historyTokens` for Gemini `countTokens`.
+     The BPE ranks load **lazily on first text estimate** — not when the package
+     is imported. `meter: 'input'`, host `historyTokens`, empty history, and
+     media-only estimates never load the tokenizer.
+   - **Media parts** — minimum stubs when size/duration are unknown (not
+     payload bytes). Image/document: 258 (one still-image / page unit).
+     Audio: 32 (1s @ 32/s). Video: 263 (1s @ 263/s). Larger Gemini 2.x images
+     are 258×tiles; Gemini 3 uses `media_resolution` budgets (often 560–1120).
+     Prefer `historyTokens` when the host knows better.
+   - Current-turn `attachments` / `voice` are **not** history.
+
+The same history estimator is used by `splitForCompaction` for fractional
+`previousExchanges` (integer / `0` splits do not need the tokenizer). Empty or
+missing history is **0** (does not fire).
+
+### `compactAt`
+
+Fraction of `maxTokens` at which compaction fires. Must be in (0, 1).
+
+### `previousExchanges`
+
+How many recent exchanges to preserve verbatim after compaction. An exchange
+starts at each user message and includes all subsequent messages (assistant
+replies, tool calls, tool results) until the next user message.
+
+- **`>= 1` (integer)** — keep that many recent exchanges.
+- **`(0, 1)` (fraction)** — retain exchanges that fit within this fraction of
+  `maxTokens` (history estimate), walking backwards. Must be less than
+  `compactAt`.
+- **`0`** — compact everything; no tail is retained.
+
+### `profile`
+
+Profile id of the compaction agent. Must be registered before the owning
+profile.
+
+### `timing`
+
+- **`'before'`** — compact synchronously before the turn.
+- **`'after'`** — signal on the `done` event; host runs compaction async.
+
+### `trigger`
+
+Optional custom gate. When set, it **replaces** the default
+`tokens > compactAt * maxTokens` check. The kernel still resolves `{ meter,
+tokens }` first and passes them as `CompactionTriggerContext` so the host can
+combine token pressure with other signals (e.g. free RAM):
+
+```ts
+compaction: {
+  maxTokens: 2000,
+  compactAt: 0.75,
+  previousExchanges: 8,
+  profile: "my.compactor",
+  timing: "after",
+  trigger: (ctx) =>
+    ctx.tokens > ctx.compactAt * ctx.maxTokens || hostRamPressure(),
+},
+```
+
+Sync and async triggers are both accepted. Omit `trigger` to keep the default
+threshold.
+
+## The compaction profile
+
+A compaction profile is a standard THEORUM profile. A simple summarizer:
+
+```ts
+registerProfile(
+  defineProfile({
+    id: "my.compactor",
+    identity: {
+      handle: "Compactor",
+      system: "Summarize this conversation concisely. Preserve unresolved "
+        + "issues, decisions made, and key facts. Drop greetings and filler.",
+    },
+    model: {
+      ...modelAllow("gemini35FlashLite"),
+      thinking: "minimal",
+      maxSteps: 1,
+    },
+    tools: { allow: [] },
+    inputs: { text: true },
+    outputs: { structured: "my.summary.schema" },
+    guardrails: {
+      canary: false,
+      sanitizeInput: false,
+      redactSensitive: false,
+    },
+  }),
+);
+```
+
+## Usage: `meter: 'history'` (default)
+
+```ts
+const nextReq: TurnRequest = {
+  profile: "my.agent",
+  input: {
+    text: userMessage,
+    history: conversationHistory,
+    // optional: historyTokens: hostHistoryCount,
+  },
+};
+```
+
+## Usage: `meter: 'input'`
+
+```ts
+// timing: 'before' — thread previous turn's full-prompt usage
+input: {
+  text: userMessage,
+  history: conversationHistory,
+  inputTokens: previousTokensInput,
+}
+
+// timing: 'after' — kernel reads this turn's tokens.input automatically
+for await (const event of runTurn(req, provider)) {
+  if (event.type === "done" && event.compaction?.needed) {
+    const { history, tokens, meter, promptTokens } = event.compaction;
+    // meter === 'input'; tokens === promptTokens (when known)
+  }
+}
+```
+
+If the compaction profile uses a different provider, pass `compactionProvider`
+on the `TurnRequest`.
+
+## Exported API
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `CompactionSpec` | type | Config on `ModelSpec` |
+| `CompactionMeter` | type | `'history' \| 'input'` |
+| `CompactionTriggerContext` | type | Args for optional `trigger` |
+| `CompactionSignal` | type | `done.compaction`: `meter`, `tokens`, optional `promptTokens`, `history` |
+| `CompactionSplit` / `CompactionTokens` | type | Split result / resolved meter count |
+| `resolveHistoryTokens` | async function | Host `historyTokens` or local history estimate |
+| `resolveCompactionTokens` | async function | Resolve `{ meter, tokens }` for a turn |
+| `estimateHistoryTokens` | async function | tiktoken `o200k_base` + media stubs (lazy BPE) |
+| `HISTORY_TEXT_ENCODING` | const | `'o200k_base'` |
+| `HISTORY_MEDIA_TOKENS` | const | Media minima: image/document 258, audio 32, video 263 |
+| `compactionNeeded` | function | `(tokens, spec) => boolean` |
+| `shouldCompact` | async function | Custom `trigger` or `compactionNeeded` |
+| `splitForCompaction` | async function | `(history, spec) => { toCompact, toRetain }` |
+
+## Validation
+
+At `registerProfile` time:
+
+- `maxTokens` must be > 0
+- `compactAt` must be in (0, 1)
+- `previousExchanges` as a fraction must be < `compactAt`
+- `previousExchanges` >= 1 must be an integer
+- `meter`, when set, must be `'history'` or `'input'`
+- The named compaction profile must already be registered
+
+## 0.1.13
+
+- Default meter is **history** (local BPE + media stubs, or host `historyTokens`).
+- Optional `meter: 'input'` gates on full-prompt provider usage.
+- Budget field is `maxTokens` (not `maxHistoryTokens`).
+- `CompactionSignal` uses `meter` + `tokens` (no deprecated aliases).
+- Optional `trigger` replaces the default threshold check.
+- History BPE (`gpt-tokenizer` / `o200k_base`) loads lazily on first text estimate.

package/docs/SECRETS.md

@@ -30,6 +30,11 @@ const provider = createProvider(profile, {
   openRouter: {
     apiKey: hostResolvedOpenRouterKey,
   },
+  // openAi / local (Ollama, llama.cpp, vLLM, LM Studio, …)
+  // Hosts that honor OLLAMA_HOST should resolve it themselves — THEORUM does not.
+  local: {
+    baseUrl: hostResolvedLocalBaseUrl, // optional; default http://127.0.0.1:11434
+  },
 });
 
 for await (const event of runTurn({ profile: profile.id, input: { text: '…' } }, provider)) {
@@ -37,7 +42,7 @@ for await (const event of runTurn({ profile: profile.id, input: { text: '…' }
 }
 ```
 
-`createProvider` picks the transport from `profile.model.protocol` / `provider` (and whether the profile is a speech role). Hosts do not choose a separate speech constructor.
+`createProvider` picks the transport from `profile.model.protocol` / `provider` (and whether the profile is a speech role). Hosts do not choose a separate speech constructor. OpenRouter's Vercel AI SDK dependency loads only when an `openAi` + `openrouter` chat provider first calls `complete` — Google and local paths never import it.
 
 ## 3. Tracing
 

package/docs/STOP.md

@@ -0,0 +1,85 @@
+# Turn stop and resume
+
+Providers end turns for many reasons (completed, length, tool call, filter,
+network drop). THEORUM normalizes those into `TurnStop` on terminal `done`
+events so hosts can decide Continue / auto-continue without parsing each
+adapter.
+
+## `done.stop`
+
+Adapters attach a `stop` when the turn ends cleanly enough to classify:
+
+| `kind` | Meaning |
+| --- | --- |
+| `completed` | Normal completion |
+| `length` | Output / budget cut off |
+| `tool` | Model requested tool use |
+| `filtered` | Content filter |
+| `provider_error` | Upstream failure |
+| `cancelled` | User / host abort |
+| `stream_incomplete` | Stream ended without a terminal reason (tunnel drop, etc.) |
+
+OpenRouter maps `finish_reason` (+ optional native reason). Google Interactions
+maps terminal `status`. Local OpenAI-compat servers use the same OpenRouter
+finish-reason mapping. Hosts classify client SSE drops with
+`turnStopFromClientStreamEnd`.
+
+## Profile resume policy
+
+Under `outputs.resume`:
+
+```ts
+outputs: {
+  structured: null,
+  resume: {
+    allowContinue: ['length', 'stream_incomplete', 'provider_error'],
+    autoContinue: ['length', 'stream_incomplete'],
+  },
+}
+```
+
+- `allowContinue` — kinds eligible for a Continue CTA / `continueFrom` turn
+  (default: length, stream_incomplete, provider_error).
+- `autoContinue` — kinds the host may silently resume **once** after a short
+  pause (`AUTO_CONTINUE_DELAY_MS`, 1500). Kernel does not loop; hosts call
+  `continueFrom` at most once. User `cancelled` is never auto-continued.
+
+Helpers: `isResumeableStop`, `shouldAutoContinue`, `isUserCancelledStop`.
+
+## Continuing a turn
+
+Pass `continueFrom` on the next `TurnRequest`. The kernel appends the fixed
+`CONTINUE_INSTRUCTION` (do not invent per-app continue prompts):
+
+```ts
+for await (const event of runTurn({
+  profile: "my.agent",
+  input: { text: "" },
+  continueFrom: {
+    stop: previousDone.stop,
+    partialText: bufferedAssistantText,
+    // optional: partialArtifact
+  },
+}, provider)) {
+  // …
+}
+```
+
+## Errors
+
+`GenerationStopError` carries a `stop` for hosts that prefer throw/catch over
+stream events. `isGenerationStopError` narrows it.
+
+## Exported API
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `TurnStop` / `TurnStopKind` | type | Normalized stop on `done` |
+| `TurnContinueFrom` | type | Partial state for resume |
+| `ProfileResumeSpec` | type | `outputs.resume` policy |
+| `CONTINUE_INSTRUCTION` | const | Fixed continue system text |
+| `DEFAULT_AUTO_CONTINUE` | const | Default one-shot auto-continue kinds |
+| `AUTO_CONTINUE_DELAY_MS` | const | Suggested pause before auto-continue |
+| `isResumeableStop` / `shouldAutoContinue` / `isUserCancelledStop` | function | Host policy helpers |
+| `turnStopFromOpenRouter` / `turnStopFromInteractionStatus` / `turnStopFromClientStreamEnd` | function | Provider / client mappers |
+| `GenerationStopError` / `isGenerationStopError` | class / function | Optional throw path |

package/esm/mod.d.ts

@@ -41,6 +41,8 @@ export { describeError, isAbortError, publicError, TheorumError, throwIfAborted,
 export type { QuotaSlotStatus } from './src/guardrails/quota.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
+export type { CompactionSplit, CompactionTokens } from './src/kernel/engine/compaction.js';
+export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './src/kernel/engine/compaction.js';
 export { runTurn } from './src/kernel/engine/runner.js';
 export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
 export type { ProfileDefinition } from './src/kernel/registry/profiles.js';
@@ -48,8 +50,10 @@ export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, reg
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
 export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';
 export { executeTool } from './src/kernel/registry/tools.js';
+export type { ProfileResumeSpec, TurnContinueFrom, TurnStop, TurnStopKind, } from './src/kernel/stop.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenRouter, } from './src/kernel/stop.js';
 export type * from './src/kernel/types.js';
 export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
 export type { TraceRecord } from './src/observability/trace-record.js';
-export type { CreateProviderOptions, GeminiTransport, GeminiVault } from './src/providers/mod.js';
-export { createProvider } from './src/providers/mod.js';
+export type { CreateProviderOptions, GeminiTransport, GeminiVault, LocalProviderConfig, } from './src/providers/mod.js';
+export { createLocalProvider, createProvider, DEFAULT_LOCAL_BASE_URL, } from './src/providers/mod.js';

package/esm/mod.js

@@ -40,11 +40,13 @@ import "./_dnt.polyfills.js";
 export { describeError, isAbortError, publicError, TheorumError, throwIfAborted, toErrorEvent, } from './src/guardrails/error.js';
 export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './src/guardrails/quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
+export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './src/kernel/engine/compaction.js';
 export { runTurn } from './src/kernel/engine/runner.js';
 export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
 export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';
 export { executeTool } from './src/kernel/registry/tools.js';
+export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION, DEFAULT_AUTO_CONTINUE, GenerationStopError, isGenerationStopError, isResumeableStop, isUserCancelledStop, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenRouter, } from './src/kernel/stop.js';
 export { jsonlSink, memorySink, noopSink, resolveTraceDir, sinkFromDir, writeTrace, } from './src/observability/trace.js';
-export { createProvider } from './src/providers/mod.js';
+export { createLocalProvider, createProvider, DEFAULT_LOCAL_BASE_URL, } from './src/providers/mod.js';

package/esm/src/cli/commands/bench.js

@@ -15,7 +15,7 @@
 import { sanitizeTurnRequest } from '../../guardrails/sanitize.js';
 import { bindCanary, eventHasCanary, mintCanary } from '../../kernel/engine/boundary.js';
 import { runTurn } from '../../kernel/engine/runner.js';
-import { clearProfiles, registerProfile, } from '../../kernel/registry/profiles.js';
+import { clearProfiles, registerProfile } from '../../kernel/registry/profiles.js';
 import { pickSystemRole, resolveTurn } from '../../kernel/registry/resolve.js';
 import { buildRecord } from '../../observability/trace-record.js';
 const DEFAULT_CHUNKS = 200;
@@ -159,9 +159,7 @@ function aggregate(results) {
     const ttfe = results.map((r) => r.ttfe).sort((a, b) => a - b);
     const ttft = results.map((r) => r.ttft).sort((a, b) => a - b);
     const total = results.map((r) => r.totalMs).sort((a, b) => a - b);
-    const tps = results
-        .map((r) => (r.textEvents / r.totalMs) * MS_PER_SEC)
-        .sort((a, b) => a - b);
+    const tps = results.map((r) => (r.textEvents / r.totalMs) * MS_PER_SEC).sort((a, b) => a - b);
     const mean = (arr) => arr.reduce((a, b) => a + b, 0) / arr.length;
     return {
         ttfeMs: {