theorum 0.1.3 → 0.1.5

package/README.md

@@ -16,6 +16,8 @@ THEORUM is a compact TypeScript agent kernel for apps that need deterministic ag
 
 The package is intentionally **not** an agent product. It ships no app profiles, no prompts, no secrets, no database policy, no business rules, and no channel-specific UX. Those belong in the host application.
 
+OpenRouter chat transport is powered by Vercel AI SDK Core under the adapter. THEORUM keeps the runner contract, guardrails, tool permissions, egress, media buffering, and trace event shape; AI SDK handles the OpenRouter request/stream/tool-call normalization layer.
+
 ---
 
 ## Core Principles
@@ -62,7 +64,7 @@ flowchart TD
     end
 
     subgraph Providers["Provider adapters"]
-        OR["OpenRouter chat"]
+        OR["OpenRouter chat via Vercel AI SDK Core"]
         GI["Google Interactions"]
         Speech["Speech (Interactions or /audio/speech)"]
     end
@@ -149,10 +151,11 @@ const profile = defineProfile({
   model: {
     protocol: "openAi",
     provider: "openrouter",
-    allow: ["gemini35FlashLite"],
+    allow: ["hostFastModel"],
     config: {
-      gemini35FlashLite: {
-        apiId: "gemini-3.5-flash-lite",
+      hostFastModel: {
+        apiId: "perplexity/sonar",
+        openRouterId: "perplexity/sonar",
         thinking: { on: "high", off: "minimal" },
         thinkingLevels: ["minimal", "low", "medium", "high"],
         summaries: { on: "auto", off: "none" },
@@ -235,10 +238,11 @@ Inbound and outbound safety are generic kernel hooks.
 const guardedProfile = defineProfile({
   id: "assistant.guarded",
   model: {
-    allow: ["gemini35FlashLite"],
+    allow: ["hostFastModel"],
     config: {
-      gemini35FlashLite: {
-        apiId: "gemini-3.5-flash-lite",
+      hostFastModel: {
+        apiId: "perplexity/sonar",
+        openRouterId: "perplexity/sonar",
         thinking: { on: "high", off: "minimal" },
         thinkingLevels: ["minimal", "low", "medium", "high"],
         summaries: { on: "auto", off: "none" },
@@ -299,7 +303,9 @@ for await (const event of runTurn({ profile: profile.id, input: { text: "…" }
 | `openAi` + `openrouter` (chat) | OpenRouter chat completions |
 | `openAi` + `openrouter` (speech role) | OpenRouter `/audio/speech` |
 
-Advanced payload helpers live under `theorum/openrouter` (`toOpenRouterPayload`, …). Prefer `createProvider` for turns.
+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.
+
+Advanced OpenRouter exports live under `theorum/openrouter` (`createOpenRouterProvider`, `toOpenRouterPayload`, …). Prefer `createProvider` for turns unless the host needs to wire the OpenRouter adapter directly.
 
 ---
 
@@ -310,7 +316,7 @@ Advanced payload helpers live under `theorum/openrouter` (`toOpenRouterPayload`,
 | `jsr:@theorum/core` / `theorum` | Main kernel API: profiles, schemas, runner, core types, provider constructors. |
 | `jsr:@theorum/core/kernel` / `theorum/kernel` | Profile/turn types, tool catalog, `requireModelSpec`, thinking clamps over host model maps. |
 | `jsr:@theorum/core/providers` / `theorum/providers` | `createProvider` + Gemini vault types. |
-| `jsr:@theorum/core/openrouter` / `theorum/openrouter` | OpenRouter payload helpers (advanced). |
+| `jsr:@theorum/core/openrouter` / `theorum/openrouter` | Direct OpenRouter provider adapter and payload helpers (advanced). |
 | `jsr:@theorum/core/guardrails` / `theorum/guardrails` | Sanitization, public error mapping, inbound injection/sensitive-data primitives. |
 | `jsr:@theorum/core/observability` / `theorum/observability` | Trace sinks and trace record helpers. |
 | `jsr:@theorum/core/host` / `theorum/host` | Optional Deno HTTP helpers (`json`, status mapping, cutout mint flush). |
@@ -347,6 +353,21 @@ cd npm
 npm pack
 ```
 
+Run a live OpenRouter smoke test with a host-resolved key. The key is passed as an argument and is never read from a Theorum `.env` file.
+
+```bash
+deno run --allow-net scripts/verify-live.ts --api-key "$OPENROUTER_API_KEY"
+```
+
+The default live verifier uses `perplexity/sonar` because it is broadly available on OpenRouter. Hosts can override both the profile-facing model id and provider-native id:
+
+```bash
+deno run --allow-net scripts/verify-live.ts \
+  --api-key "$OPENROUTER_API_KEY" \
+  --model hostFastModel \
+  --api-id perplexity/sonar
+```
+
 ---
 
 ## Package Boundary

package/esm/mod.d.ts

@@ -37,10 +37,12 @@
  * @module
  */
 import "./_dnt.polyfills.js";
-export { publicError, TheorumError } from './src/guardrails/error.js';
+export { publicError, describeError, TheorumError, toErrorEvent } from './src/guardrails/error.js';
+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 { runTurn } from './src/kernel/engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.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';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';

package/esm/mod.js

@@ -37,10 +37,11 @@
  * @module
  */
 import "./_dnt.polyfills.js";
-export { publicError, TheorumError } from './src/guardrails/error.js';
+export { publicError, describeError, TheorumError, 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 { runTurn } from './src/kernel/engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.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';

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

@@ -30,4 +30,16 @@ declare const PUBLIC_FILE_COUNT = "Too many files for one message.";
 declare const PUBLIC_IMAGE_SIZE = "That image size isn't supported.";
 /** Convert an unknown thrown value or internal message to user-safe text. */
 declare function publicError(err: unknown): string;
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };
+/** Raw diagnostic text for hosts, traces, and logs (never shown to end users). */
+declare function describeError(err: unknown): string;
+/**
+ * Stream error event with a public-safe `error` and a preserved `errorInternal`.
+ * Providers and the runner should emit this instead of public-only error strings
+ * so traces and host logs are never a black box.
+ */
+declare function toErrorEvent(err: unknown): {
+    type: 'error';
+    error: string;
+    errorInternal: string;
+};
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };

package/esm/src/guardrails/error.js

@@ -89,7 +89,20 @@ const RULES = [
         resolve: () => PUBLIC_GENERIC,
     },
 ];
+const ALREADY_PUBLIC = new Set([
+    PUBLIC_GENERIC,
+    PUBLIC_UNAVAILABLE,
+    PUBLIC_CANARY,
+    PUBLIC_ACTION,
+    PUBLIC_FILE_TYPE,
+    PUBLIC_FILE_SIZE,
+    PUBLIC_FILE_COUNT,
+    PUBLIC_IMAGE_SIZE,
+]);
 function publicText(text) {
+    if (ALREADY_PUBLIC.has(text)) {
+        return text;
+    }
     const exact = EXACT[text];
     if (exact) {
         return exact;
@@ -111,4 +124,26 @@ function publicError(err) {
     }
     return PUBLIC_UNAVAILABLE;
 }
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, };
+/** Raw diagnostic text for hosts, traces, and logs (never shown to end users). */
+function describeError(err) {
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err instanceof Error && err.message) {
+        return err.message;
+    }
+    return String(err);
+}
+/**
+ * Stream error event with a public-safe `error` and a preserved `errorInternal`.
+ * Providers and the runner should emit this instead of public-only error strings
+ * so traces and host logs are never a black box.
+ */
+function toErrorEvent(err) {
+    return {
+        type: 'error',
+        error: publicError(err),
+        errorInternal: describeError(err),
+    };
+}
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, };

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

@@ -8,7 +8,9 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, } from './error.js';
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
+export type { QuotaSlotStatus } from './quota.js';
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';
 export { sensitiveSpans } from './sensitive.js';

package/esm/src/guardrails/mod.js

@@ -8,7 +8,8 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, publicError, TheorumError, UPSTREAM_FAILED, } from './error.js';
+export { PUBLIC_ACTION, PUBLIC_CANARY, PUBLIC_FILE_COUNT, PUBLIC_FILE_SIZE, PUBLIC_FILE_TYPE, PUBLIC_GENERIC, PUBLIC_IMAGE_SIZE, PUBLIC_UNAVAILABLE, describeError, publicError, TheorumError, toErrorEvent, UPSTREAM_FAILED, } from './error.js';
 export { injectionSpans } from './injection.js';
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, } from './quota.js';
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './sanitize.js';
 export { sensitiveSpans } from './sensitive.js';

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

@@ -0,0 +1,10 @@
+import type { Profile } from '../kernel/types.js';
+type QuotaSlotStatus = 'ok' | 'busy' | 'quota' | 'not_configured';
+declare function skipQuota(peer: string, req: Request): boolean;
+declare function clientIp(peer: string, req: Request): string;
+declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus;
+declare function releaseSlot(profile: Profile, ip: string): void;
+declare function quotaMessage(profile: Profile): string;
+declare function resetSlots(): void;
+export type { QuotaSlotStatus };
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/guardrails/quota.js

@@ -0,0 +1,64 @@
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+const slots = new Map();
+function utcDay(now) {
+    return new Date(now).toISOString().slice(0, 10);
+}
+function isLoopback(peer) {
+    return LOOPBACK.has(peer);
+}
+function cfConnectingIp(req) {
+    return req.headers.get('cf-connecting-ip')?.trim() ?? '';
+}
+function slotKey(profileId, ip) {
+    return `${profileId}:${ip}`;
+}
+function skipQuota(peer, req) {
+    return isLoopback(peer) && !cfConnectingIp(req);
+}
+function clientIp(peer, req) {
+    if (isLoopback(peer)) {
+        const cf = cfConnectingIp(req);
+        if (cf) {
+            return cf;
+        }
+    }
+    if (peer) {
+        return peer;
+    }
+    return 'unknown';
+}
+function takeSlot(profile, ip, now) {
+    const quota = profile.guardrails.quota;
+    if (!quota) {
+        return 'not_configured';
+    }
+    const day = utcDay(now);
+    const key = slotKey(profile.id, ip);
+    let slot = slots.get(key);
+    if (!slot || slot.day !== day) {
+        slot = { day, count: 0, busy: false };
+        slots.set(key, slot);
+    }
+    if (slot.busy) {
+        return 'busy';
+    }
+    if (slot.count >= quota.perDay) {
+        return 'quota';
+    }
+    slot.busy = true;
+    slot.count += 1;
+    return 'ok';
+}
+function releaseSlot(profile, ip) {
+    const slot = slots.get(slotKey(profile.id, ip));
+    if (slot) {
+        slot.busy = false;
+    }
+}
+function quotaMessage(profile) {
+    return `Enjoying ${profile.identity.handle}? You've reached today's limit`;
+}
+function resetSlots() {
+    slots.clear();
+}
+export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot };

package/esm/src/kernel/engine/runner/gates.js

@@ -1,4 +1,4 @@
-import { publicError } from '../../../guardrails/error.js';
+import { toErrorEvent } from '../../../guardrails/error.js';
 import { sanitizeTurnRequest } from '../../../guardrails/sanitize.js';
 import { resolveTurn } from '../../registry/resolve.js';
 import { executeAttempt } from './steps.js';
@@ -59,10 +59,7 @@ async function evaluateEgressOutcome(args) {
     }
     return {
         action: 'withhold',
-        event: {
-            type: 'error',
-            error: publicError('Turn withheld: egress disclosure violation'),
-        },
+        event: toErrorEvent('Turn withheld: egress disclosure violation'),
     };
 }
 async function evaluateValidationOutcome(args) {

package/esm/src/kernel/engine/runner/mod.js

@@ -67,6 +67,12 @@ async function* runTurn(req, provider, sink = noopSink()) {
             gemini,
         })) {
             seen.push(event);
+            if (event.type === 'error') {
+                const detail = event.errorInternal ?? event.error;
+                if (detail) {
+                    console.error(`[theorum] turn error (${req.profile}): ${detail}`);
+                }
+            }
             if (shouldSkipStreamEvent(event, profile)) {
                 continue;
             }

package/esm/src/kernel/engine/runner/stream.js

@@ -1,4 +1,4 @@
-import { publicError } from '../../../guardrails/error.js';
+import { publicError, toErrorEvent } from '../../../guardrails/error.js';
 import { providerCompleteRequest } from '../../registry/provider-request.js';
 import { eventHasCanary, redactCanary } from '../boundary.js';
 import { dispatchModelTool } from './tools.js';
@@ -39,7 +39,12 @@ function* processNormalEvent(event, profile, generation) {
         yield* interceptProviderTool(event, profile, generation);
     }
     else if (event.type === 'error') {
-        yield { type: 'error', error: publicError(event.error) };
+        const internal = event.errorInternal ?? event.error ?? '';
+        yield {
+            type: 'error',
+            error: publicError(event.error ?? internal),
+            ...(internal ? { errorInternal: internal } : {}),
+        };
     }
     else {
         yield event;
@@ -56,7 +61,7 @@ async function* yieldProviderEvents(args) {
     })) {
         if (canary && eventHasCanary(event, canary)) {
             yield redactCanary(event, canary);
-            yield { type: 'error', error: publicError('canary leaked') };
+            yield toErrorEvent('canary leaked');
             return;
         }
         yield* processNormalEvent(event, profile, generation);

package/esm/src/kernel/engine/runner/tools.js

@@ -1,4 +1,4 @@
-import { publicError } from '../../../guardrails/error.js';
+import { toErrorEvent } from '../../../guardrails/error.js';
 import { CATALOG } from '../../registry/catalog.js';
 import { executeTool } from '../../registry/tools.js';
 function formatToolFinding(res) {
@@ -22,13 +22,13 @@ function* invokeFromUi(profile, req) {
             tool: { name: invoke.name, arguments: invoke.arguments, result },
         };
         if (result.status === 'error') {
-            yield { type: 'error', error: publicError(formatToolFinding(result)) };
+            yield toErrorEvent(formatToolFinding(result));
             return;
         }
         yield { type: 'done' };
     }
     catch (err) {
-        yield { type: 'error', error: publicError(err) };
+        yield toErrorEvent(err);
         yield { type: 'done' };
     }
 }
@@ -42,12 +42,12 @@ function executeCustomModelTool(profile, name, args) {
             },
         ];
         if (result.status === 'error') {
-            events.push({ type: 'error', error: publicError(formatToolFinding(result)) });
+            events.push(toErrorEvent(formatToolFinding(result)));
         }
         return events;
     }
     catch (err) {
-        return [{ type: 'error', error: publicError(err) }];
+        return [toErrorEvent(err)];
     }
 }
 function dispatchModelTool(profile, event, gated) {
@@ -60,12 +60,7 @@ function dispatchModelTool(profile, event, gated) {
         return [event];
     }
     if (!gated.includes(name)) {
-        return [
-            {
-                type: 'error',
-                error: publicError(`Tool '${name}' is not gated on this turn`),
-            },
-        ];
+        return [toErrorEvent(`Tool '${name}' is not gated on this turn`)];
     }
     const args = tool.arguments ?? {};
     return executeCustomModelTool(profile, name, args);

package/esm/src/kernel/mod.d.ts

@@ -9,7 +9,7 @@
  */
 import "../../_dnt.polyfills.js";
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
 export type { ProfileDefinition } from './registry/profiles.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
 export { projectProfile, resolveTurn } from './registry/resolve.js';

package/esm/src/kernel/mod.js

@@ -9,7 +9,7 @@
  */
 import "../../_dnt.polyfills.js";
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
 export { projectProfile, resolveTurn } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';

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

@@ -495,7 +495,10 @@ export interface TurnEvent {
     evidence?: ProviderEvidenceEvent;
     tokens?: TurnTokens;
     interactionId?: string;
+    /** Public-safe failure text for hosts to show users. */
     error?: string;
+    /** Raw diagnostic detail for traces/logs; never surface to end users. */
+    errorInternal?: string;
 }
 /** Provider-neutral request object sent from the kernel to a model adapter. */
 export interface ProviderCompleteRequest extends ProviderGenerationConfig {

package/esm/src/observability/trace-record.d.ts

@@ -30,6 +30,7 @@ export interface TraceEvent {
     grounding?: TurnEvent['grounding'];
     evidence?: TurnEvent['evidence'];
     error?: string;
+    errorInternal?: string;
 }
 /** Complete trace-safe record for one attempted turn. */
 interface TraceRecord {

package/esm/src/observability/trace-record.js

@@ -31,6 +31,9 @@ async function snapshotEvent(event) {
     if (event.error) {
         row.error = event.error;
     }
+    if (event.errorInternal) {
+        row.errorInternal = sanitizeText(event.errorInternal);
+    }
     if (event.structured !== undefined) {
         row.structured = event.structured;
     }
@@ -89,7 +92,7 @@ function titleFrom(text) {
 function attachFailure(record, thrown, lastErr, canary) {
     if (!record.ok) {
         record.error = publicError(thrown ?? lastErr?.error);
-        const inside = internalError(thrown) ?? lastErr?.error;
+        const inside = internalError(thrown) ?? lastErr?.errorInternal ?? lastErr?.error;
         if (inside) {
             record.errorInternal = inside;
         }

package/esm/src/providers/interactions.js

@@ -35,7 +35,8 @@ function userInputStep(parts) {
 }
 function historyStep(msg) {
     const isAssistant = msg.role === 'assistant';
-    const type = isAssistant ? 'model_turn' : 'user_input';
+    // Google Interactions input steps: assistant history is `model_output` (not `model_turn`).
+    const type = isAssistant ? 'model_output' : 'user_input';
     if (msg.parts && msg.parts.length > 0) {
         return { type, content: msg.parts.map(wirePart) };
     }

package/esm/src/providers/openrouter.js

@@ -9,7 +9,7 @@
  */
 import { createOpenRouter } from '@openrouter/ai-sdk-provider';
 import { jsonSchema, streamText, tool, } from 'ai';
-import { publicError } from '../guardrails/error.js';
+import { toErrorEvent } from '../guardrails/error.js';
 import { tryStructured } from '../kernel/engine/delta.js';
 import { getTool } from '../kernel/registry/catalog.js';
 import { resolveOpenRouterModel, toOpenRouterPayload, } from './openrouter-payload.js';
@@ -441,7 +441,7 @@ function primaryEventFromPart(part, acc) {
             return finishEvent(part, acc);
         case 'error':
             acc.errored = true;
-            return { type: 'error', error: publicError(part.error) };
+            return toErrorEvent(part.error);
         default:
             return undefined;
     }
@@ -528,7 +528,7 @@ async function* yieldCapturedRawEventsUnchecked(context) {
     }
 }
 function missingOpenRouterKey() {
-    return { type: 'error', error: publicError('missing OpenRouter API key') };
+    return toErrorEvent('missing OpenRouter API key');
 }
 async function* streamOpenRouter(req, config) {
     const apiKey = trimApiKey(config.apiKey);
@@ -545,7 +545,7 @@ async function* streamOpenRouter(req, config) {
     }
     catch (err) {
         yield* yieldCapturedRawEventsUnchecked(context);
-        yield { type: 'error', error: publicError(err) };
+        yield toErrorEvent(err);
     }
 }
 function* finalEvents(req, acc) {

package/esm/src/providers/provider.js

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import { publicError, TheorumError } from '../guardrails/error.js';
+import { TheorumError, toErrorEvent } from '../guardrails/error.js';
 import { eventsFromComplete, eventsFromDelta, extractTokenEvent, groundingFromEvent, tryStructured, } from '../kernel/engine/delta.js';
 import { tapFetch } from './google-tap.js';
 import { toInteractionsBody } from './interactions.js';
@@ -118,19 +118,13 @@ function withTap(req, transport) {
 }
 async function* streamComplete(req, transport) {
     if (!req.geminiBucket) {
-        yield {
-            type: 'error',
-            error: publicError('missing Gemini vault bucket for Interactions'),
-        };
+        yield toErrorEvent('missing Gemini vault bucket for Interactions');
         return;
     }
     const res = await fetchGemini(INTERACTIONS_URL, { method: 'POST', body: JSON.stringify(toInteractionsBody(req)) }, req.geminiBucket, withTap(req, transport));
     if (res.status !== HTTP_OK) {
         const errorBody = await res.text().catch(() => '');
-        yield {
-            type: 'error',
-            error: publicError(`Gemini HTTP ${String(res.status)}: ${errorBody}`),
-        };
+        yield toErrorEvent(`Gemini HTTP ${String(res.status)}: ${errorBody}`);
         return;
     }
     const acc = { text: '' };
@@ -154,7 +148,7 @@ async function* streamGuarded(req, transport) {
         yield* streamComplete(req, transport);
     }
     catch (err) {
-        yield { type: 'error', error: publicError(err) };
+        yield toErrorEvent(err);
     }
 }
 /** Create a `ModelProvider` backed by Google Interactions streaming. */

package/esm/src/providers/speech.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import { publicError } from '../guardrails/error.js';
+import { toErrorEvent } from '../guardrails/error.js';
 import { wrapPcmAsWav } from './pcm.js';
 const HTTP_OK = 200;
 function bytesToBase64(bytes) {
@@ -92,23 +92,23 @@ function* yieldSpeechSuccess(rawBytes, text, format) {
 async function* streamSpeech(req, config = {}) {
     const apiKey = config.apiKey?.trim() || undefined;
     if (!apiKey) {
-        yield { type: 'error', error: publicError('missing API key for speech') };
+        yield toErrorEvent('missing API key for speech');
         return;
     }
     const text = extractInputText(req.input);
     if (!text) {
-        yield { type: 'error', error: publicError('empty text for speech') };
+        yield toErrorEvent('empty text for speech');
         return;
     }
     const res = await requestSpeech(apiKey, text, req, config);
     if (res.status !== HTTP_OK) {
-        yield { type: 'error', error: publicError(`Speech HTTP ${String(res.status)}`) };
+        yield toErrorEvent(`Speech HTTP ${String(res.status)}`);
         return;
     }
     const arrayBuffer = await res.arrayBuffer();
     const rawBytes = new Uint8Array(arrayBuffer);
     if (rawBytes.length === 0) {
-        yield { type: 'error', error: publicError('no audio returned from speech') };
+        yield toErrorEvent('no audio returned from speech');
         return;
     }
     const format = req.speech?.format ?? 'pcm';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theorum",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",
@@ -49,7 +49,7 @@
   },
   "scripts": {},
   "bin": {
-    "theorum": "esm/src/cli/index.js"
+    "theorum": "./esm/src/cli/index.js"
   },
   "type": "module",
   "sideEffects": false,
@@ -62,4 +62,4 @@
     "@types/node": "^20.9.0"
   },
   "_generatedBy": "dnt@0.43.2"
-}
+}