theorum 1.0.0 → 1.1.3

package/esm/src/providers/google/live/stream.js

@@ -7,7 +7,7 @@
  * @module
  */
 import { TheorumError } from '../../../guardrails/error.js';
-import { buildGeminiLiveClientContent, buildGeminiLiveRealtimeInput, buildGeminiLiveSetupMessage, foldGeminiLiveServerMessage, parseGeminiLiveMessage, } from './framing.js';
+import { buildGeminiLiveClientContent, buildGeminiLiveRealtimeInput, buildGeminiLiveSetupMessage, foldGeminiLiveServerMessage, parseGeminiLiveMessage, readLiveInteractionStatus, } from './framing.js';
 const SETUP_TIMEOUT_MS = 20_000;
 export async function readMessageData(data) {
     if (typeof data === 'string')
@@ -143,12 +143,25 @@ export function createLiveQueue() {
         },
     };
 }
-function turnPhaseFromMessage(message, events) {
+/**
+ * Conversational cycle boundary.
+ *
+ * When the server reports `interactionStatus`, that is authoritative: `IDLE`
+ * closes the cycle and `IN_PROGRESS` keeps it open even across `turnComplete`
+ * (background reasoning / async tools may still produce output). Without the
+ * field, `turnComplete` is the boundary as before.
+ */
+export function turnPhaseFromMessage(message, events) {
     const interrupted = events.some((ev) => ev.type === 'done' && ev.interrupted === true);
     if (interrupted)
         return 'abort';
+    const status = readLiveInteractionStatus(message);
+    if (status === 'IDLE')
+        return 'complete';
+    if (status === 'IN_PROGRESS')
+        return 'streaming';
     const serverContent = message.serverContent;
-    if (serverContent?.turnComplete)
+    if (serverContent?.turnComplete || serverContent?.turn_complete)
         return 'complete';
     return 'streaming';
 }

package/esm/src/providers/openrouter/cache-control.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared OpenRouter `cache_control` directive from a profile CacheSpec.
+ *
+ * Used by AI SDK `providerOptionsFor` and REST `toOpenAiChatPayload` so both
+ * paths share one wire shape.
+ *
+ * @module
+ */
+import type { CacheTtl } from '../../kernel/schema.js';
+import type { CacheSpec } from '../../kernel/types.js';
+/** Anthropic / OpenRouter ephemeral cache_control object. */
+export interface CacheControlDirective {
+    type: 'ephemeral';
+    ttl?: CacheTtl;
+}
+/** Map a profile CacheSpec to the upstream cache_control body fragment. */
+export declare function cacheControlFromSpec(spec: CacheSpec): CacheControlDirective;
+/**
+ * Plain JSON object for AI SDK `providerOptions` (needs string index signature).
+ * Same values as `cacheControlFromSpec`.
+ */
+export declare function cacheControlJson(spec: CacheSpec): {
+    [key: string]: string;
+};

package/esm/src/providers/openrouter/cache-control.js

@@ -0,0 +1,23 @@
+/**
+ * Shared OpenRouter `cache_control` directive from a profile CacheSpec.
+ *
+ * Used by AI SDK `providerOptionsFor` and REST `toOpenAiChatPayload` so both
+ * paths share one wire shape.
+ *
+ * @module
+ */
+/** Map a profile CacheSpec to the upstream cache_control body fragment. */
+export function cacheControlFromSpec(spec) {
+    if (spec.ttl) {
+        return { type: 'ephemeral', ttl: spec.ttl };
+    }
+    return { type: 'ephemeral' };
+}
+/**
+ * Plain JSON object for AI SDK `providerOptions` (needs string index signature).
+ * Same values as `cacheControlFromSpec`.
+ */
+export function cacheControlJson(spec) {
+    const directive = cacheControlFromSpec(spec);
+    return directive.ttl ? { type: directive.type, ttl: directive.ttl } : { type: directive.type };
+}

package/esm/src/providers/openrouter/chat.d.ts

@@ -7,7 +7,7 @@
  *
  * @module
  */
-import { type TextStreamPart, type ToolSet } from 'ai';
+import { type ModelMessage, type TextStreamPart, type ToolSet } from 'ai';
 import type { ModelProvider, ProviderCompleteRequest, TurnEvent, TurnTokens, WireFunctionTool } from '../../kernel/types.js';
 import type { OpenAiGatewayConfig } from '../types.js';
 export interface StreamAccumulator {
@@ -37,6 +37,11 @@ export declare function tokensFromUsage(usage: {
     inputTokens?: number | null;
     outputTokens?: number | null;
     totalTokens?: number | null;
+    inputTokenDetails?: {
+        cacheReadTokens?: number | null;
+        cacheWriteTokens?: number | null;
+    } | null;
+    cachedInputTokens?: number | null;
 }): TurnTokens | undefined;
 export declare function rawRecord(value: unknown): Record<string, unknown> | undefined;
 export declare function stringArray(value: unknown): string[] | undefined;
@@ -66,6 +71,11 @@ export declare function tokenEvent(part: {
         inputTokens?: number | null;
         outputTokens?: number | null;
         totalTokens?: number | null;
+        inputTokenDetails?: {
+            cacheReadTokens?: number | null;
+            cacheWriteTokens?: number | null;
+        } | null;
+        cachedInputTokens?: number | null;
     };
 }): TurnEvent | undefined;
 export declare function providerMetadataEvent(part: TextStreamPart<ToolSet>, acc: StreamAccumulator): TurnEvent | undefined;
@@ -77,9 +87,19 @@ export declare function finishEvent(part: {
         inputTokens?: number | null;
         outputTokens?: number | null;
         totalTokens?: number | null;
+        inputTokenDetails?: {
+            cacheReadTokens?: number | null;
+            cacheWriteTokens?: number | null;
+        } | null;
+        cachedInputTokens?: number | null;
     };
 }, acc: StreamAccumulator): TurnEvent | undefined;
 export declare function finalEvents(req: ProviderCompleteRequest, acc: StreamAccumulator): Generator<TurnEvent>;
+/** System via instructions XOR a cache-marked system message — never both. */
+export declare function systemDelivery(req: ProviderCompleteRequest): {
+    instructions?: string;
+    systemMessage?: ModelMessage;
+};
 export declare function missingOpenRouterKey(): TurnEvent;
 export declare function providerOptionsFor(req: ProviderCompleteRequest): ProviderOptions | undefined;
 /** Create a `ModelProvider` backed by OpenRouter through AI SDK Core. */

package/esm/src/providers/openrouter/chat.js

@@ -8,10 +8,11 @@
  * @module
  */
 import { createOpenRouter } from '@openrouter/ai-sdk-provider';
-import { jsonSchema, streamText, tool } from 'ai';
+import { jsonSchema, streamText, tool, } from 'ai';
 import { isAbortError, TheorumError, toErrorEvent } from '../../guardrails/error.js';
-import { parseStructuredOutput } from '../../kernel/engine/delta.js';
+import { extractUsageTokens, parseStructuredOutput } from '../../kernel/engine/delta.js';
 import { turnStopFromOpenAiFinishReason } from '../../kernel/stop.js';
+import { cacheControlJson } from './cache-control.js';
 import { resolveOpenRouterPlugins } from './openai/chat-payload.js';
 import { openAiGatewayHeaders, resolveResponseFormat } from './openai/compat.js';
 import { buildAiSdkMessages } from './openai/sdk-messages.js';
@@ -80,13 +81,21 @@ export function tokensFromUsage(usage) {
     const input = usage.inputTokens ?? 0;
     const output = usage.outputTokens ?? 0;
     const total = usage.totalTokens ?? input + output;
-    if (input === 0 && output === 0 && total === 0) {
+    const cached = usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens ?? undefined;
+    const cacheWrite = usage.inputTokenDetails?.cacheWriteTokens ?? undefined;
+    if (input === 0 &&
+        output === 0 &&
+        total === 0 &&
+        !(cached && cached > 0) &&
+        !(cacheWrite && cacheWrite > 0)) {
         return undefined;
     }
     return {
         input,
         output,
         total,
+        ...(cached && cached > 0 ? { cached } : {}),
+        ...(cacheWrite && cacheWrite > 0 ? { cacheWrite } : {}),
     };
 }
 export function rawRecord(value) {
@@ -211,6 +220,13 @@ export function rawEvents(raw, acc) {
     if (messageEvidence) {
         events.push(messageEvidence);
     }
+    if (!acc.emittedTokens) {
+        const usage = extractUsageTokens(record.usage);
+        if (usage) {
+            acc.emittedTokens = true;
+            events.push({ type: 'tokens', tokens: usage });
+        }
+    }
     const choices = Array.isArray(record.choices) ? record.choices : [];
     for (const choice of choices) {
         const row = rawRecord(choice);
@@ -338,11 +354,34 @@ function createStreamContext(req, config, apiKey) {
         modelName: req.apiId,
     };
 }
+/** System via instructions XOR a cache-marked system message — never both. */
+export function systemDelivery(req) {
+    if (!req.system) {
+        return {};
+    }
+    if (req.cache?.mode === 'system') {
+        return {
+            systemMessage: {
+                role: 'system',
+                content: req.system,
+                providerOptions: {
+                    openrouter: { cacheControl: cacheControlJson(req.cache) },
+                },
+            },
+        };
+    }
+    return { instructions: req.system };
+}
 function streamTextOptions(req, context) {
+    const delivery = systemDelivery(req);
+    const messages = buildAiSdkMessages(req);
+    if (delivery.systemMessage) {
+        messages.unshift(delivery.systemMessage);
+    }
     return {
         model: context.openrouter.chat(context.modelName, openRouterSettings(req)),
-        instructions: req.system,
-        messages: buildAiSdkMessages(req),
+        instructions: delivery.instructions,
+        messages,
         allowSystemInMessages: true,
         temperature: req.temperature,
         maxOutputTokens: req.maxOutputTokens,
@@ -395,13 +434,19 @@ async function* streamOpenRouter(req, config) {
 }
 export function providerOptionsFor(req) {
     const openrouter = {};
-    if (req.thinking !== 'none') {
+    if (req.thinking && req.thinking !== 'none') {
         openrouter.reasoning = { effort: req.thinking };
     }
     const responseFormat = resolveResponseFormat(req.structured);
     if (responseFormat) {
         openrouter.response_format = responseFormat;
     }
+    if (req.cache?.mode === 'automatic') {
+        openrouter.cacheControl = cacheControlJson(req.cache);
+    }
+    if (req.sessionId) {
+        openrouter.session_id = req.sessionId;
+    }
     if (Object.keys(openrouter).length === 0)
         return undefined;
     return { openrouter };

package/esm/src/providers/openrouter/image.js

@@ -11,6 +11,7 @@
  * @module
  */
 import { toErrorEvent } from '../../guardrails/error.js';
+import { extractUsageTokens } from '../../kernel/engine/delta.js';
 import { bytesToBase64 } from '../shared/pcm.js';
 import { buildChatMessages, openAiGatewayHeaders } from './openai/compat.js';
 import { buildImagesPayload, extractPromptText, imageToolParameters, } from './openai/image-payload.js';
@@ -32,24 +33,12 @@ export function buildImageHeaders(apiKey, config) {
 function baseUrl(config) {
     return config.baseUrl?.replace(/\/+$/, '') ?? 'https://openrouter.ai/api/v1';
 }
-function usageFromRecord(raw) {
-    if (!raw || typeof raw !== 'object') {
-        return null;
-    }
-    const usage = raw;
-    const input = typeof usage.prompt_tokens === 'number' ? usage.prompt_tokens : 0;
-    const output = typeof usage.completion_tokens === 'number' ? usage.completion_tokens : 0;
-    const total = typeof usage.total_tokens === 'number' ? usage.total_tokens : input + output;
-    if (input + output + total === 0) {
-        return null;
-    }
-    return { input, output, total };
-}
-function* yieldUsage(usage) {
-    if (!usage) {
+function* yieldUsage(raw) {
+    const tokens = extractUsageTokens(raw);
+    if (!tokens) {
         return;
     }
-    yield { type: 'tokens', tokens: usage };
+    yield { type: 'tokens', tokens };
 }
 export function mediaFromImagesResponse(body, fallbackMime) {
     const data = body.data;
@@ -176,7 +165,7 @@ export function buildInterleavedChatPayload(req) {
         messages: buildChatMessages(req),
         temperature: req.temperature,
         max_tokens: req.maxOutputTokens,
-        reasoning: { effort: req.thinking },
+        ...(req.thinking && req.thinking !== 'none' ? { reasoning: { effort: req.thinking } } : {}),
         tools: [
             {
                 type: OPENROUTER_IMAGE_TOOL,
@@ -234,7 +223,7 @@ export async function* yieldInterleavedChat(req, config, apiKey) {
         yield toErrorEvent('no image returned from chat image generation');
         return;
     }
-    yield* yieldUsage(usageFromRecord(body.usage));
+    yield* yieldUsage(body.usage);
     yield { type: 'done' };
 }
 export async function* yieldImagesEndpoint(req, config, apiKey) {
@@ -251,7 +240,7 @@ export async function* yieldImagesEndpoint(req, config, apiKey) {
         return;
     }
     yield { type: 'media', media };
-    yield* yieldUsage(usageFromRecord(body.usage));
+    yield* yieldUsage(body.usage);
     yield { type: 'done' };
 }
 export async function* streamImage(req, config = {}) {

package/esm/src/providers/openrouter/openai/chat-payload.js

@@ -11,10 +11,24 @@
  * @module
  */
 import { getTool } from '../../../kernel/tools/registry.js';
+import { cacheControlFromSpec } from '../cache-control.js';
 import { buildChatMessages, resolveResponseFormat, wireTools } from './compat.js';
 /** Convert a provider-neutral request into an OpenAI chat completion payload. */
 function toOpenAiChatPayload(req) {
     const messages = buildChatMessages(req);
+    if (req.cache?.mode === 'system' && req.system) {
+        const directive = cacheControlFromSpec(req.cache);
+        const systemIdx = messages.findIndex((m) => m.role === 'system');
+        if (systemIdx >= 0) {
+            const text = typeof messages[systemIdx].content === 'string'
+                ? messages[systemIdx].content
+                : '';
+            messages[systemIdx] = {
+                role: 'system',
+                content: [{ type: 'text', text, cache_control: directive }],
+            };
+        }
+    }
     const payload = {
         model: req.apiId,
         stream: true,
@@ -22,7 +36,15 @@ function toOpenAiChatPayload(req) {
         temperature: req.temperature,
         max_tokens: req.maxOutputTokens,
     };
-    payload.reasoning = { effort: req.thinking };
+    if (req.thinking && req.thinking !== 'none') {
+        payload.reasoning = { effort: req.thinking };
+    }
+    if (req.cache?.mode === 'automatic') {
+        payload.cache_control = cacheControlFromSpec(req.cache);
+    }
+    if (req.sessionId) {
+        payload.session_id = req.sessionId;
+    }
     const responseFormat = resolveResponseFormat(req.structured);
     if (responseFormat) {
         payload.response_format = responseFormat;

package/esm/src/providers/openrouter/openai/compat.d.ts

@@ -9,7 +9,7 @@
  *
  * @module
  */
-import type { ProviderCompleteRequest, StructuredSchemaId, WireFunctionTool } from '../../../kernel/types.js';
+import type { InteractionPart, ProviderCompleteRequest, StructuredSchemaId, WireFunctionTool } from '../../../kernel/types.js';
 /** Subset of provider config used for OpenAI-gateway HTTP headers. */
 interface GatewayHeaderConfig {
     siteUrl?: string;
@@ -18,6 +18,12 @@ interface GatewayHeaderConfig {
 declare function stringDefault(value: string | undefined, fallback: string): string;
 declare function fallbackToolCallId(name?: string): string;
 declare function parseToolInput(raw: string): Record<string, unknown>;
+/**
+ * Map InteractionPart[] to OpenAI-compat message content.
+ * Text-only inputs are joined as a plain string; mixed inputs produce a
+ * content-part array (text, image_url, input_audio, file).
+ */
+export declare function wireMessageContent(parts: InteractionPart[]): unknown;
 /**
  * Build the complete `messages` array for an OpenAI chat completion request.
  * Assembles: system → history → user input.

package/esm/src/providers/openrouter/openai/compat.js

@@ -10,6 +10,7 @@
  * @module
  */
 import { TheorumError } from '../../../guardrails/error.js';
+import { isMediaRefPart } from '../../../kernel/interaction-parts.js';
 import { getStructured } from '../../../kernel/registry/schemas.js';
 import { parseToolArgumentsObject } from '../../shared/tool-args.js';
 // ── shared tool helpers ─────────────────────────────
@@ -27,6 +28,11 @@ function parseToolInput(raw) {
     return parsed.value;
 }
 // ── content wire format ─────────────────────────────
+function rejectMediaRef(part) {
+    if (isMediaRefPart(part)) {
+        throw new TheorumError('media references are not supported on openAi');
+    }
+}
 function wireAudioPart(part) {
     let format = 'mp3';
     if (part.mimeType.includes('wav')) {
@@ -43,9 +49,9 @@ function wireAudioPart(part) {
 /**
  * Map InteractionPart[] to OpenAI-compat message content.
  * Text-only inputs are joined as a plain string; mixed inputs produce a
- * content-part array (text, image_url, input_audio).
+ * content-part array (text, image_url, input_audio, file).
  */
-function wireMessageContent(parts) {
+export function wireMessageContent(parts) {
     const isAllText = parts.every((p) => p.type === 'text');
     if (isAllText) {
         return parts
@@ -62,6 +68,7 @@ function wireMessageContent(parts) {
         if (part.type === 'text') {
             return { type: 'text', text: part.text };
         }
+        rejectMediaRef(part);
         if (part.type === 'image') {
             return {
                 type: 'image_url',
@@ -71,7 +78,14 @@ function wireMessageContent(parts) {
         if (part.type === 'audio') {
             return wireAudioPart(part);
         }
-        return { type: 'text', text: '' };
+        // video + document — file part (OpenAI-compat / OpenRouter)
+        return {
+            type: 'file',
+            file: {
+                filename: part.type === 'video' ? 'clip.bin' : 'document.bin',
+                file_data: `data:${part.mimeType};base64,${part.data}`,
+            },
+        };
     });
 }
 // ── history message wire format ─────────────────────
@@ -82,11 +96,16 @@ function wireMessageContent(parts) {
  */
 function wireHistoryMessage(msg) {
     if (msg.role === 'tool') {
+        let content = msg.content ?? '';
+        if (msg.parts && msg.parts.length > 0) {
+            // Prefer multimodal parts; if only text parts, wireMessageContent collapses to string.
+            content = wireMessageContent(msg.parts);
+        }
         return {
             role: 'tool',
             tool_call_id: msg.tool_call_id ?? fallbackToolCallId(msg.name),
             name: msg.name,
-            content: msg.content ?? '',
+            content,
         };
     }
     let content = msg.content ?? '';

package/esm/src/providers/openrouter/openai/image-payload.js

@@ -6,6 +6,8 @@
  *
  * @module
  */
+import { TheorumError } from '../../../guardrails/error.js';
+import { isMediaRefPart } from '../../../kernel/interaction-parts.js';
 export function extractPromptText(input) {
     return input
         .filter((part) => part.type === 'text')
@@ -32,9 +34,13 @@ export function wireInputReference(part) {
 export function wireInputReferences(input) {
     const references = [];
     for (const part of input) {
-        if (part.type === 'image') {
-            references.push(wireInputReference(part));
+        if (part.type !== 'image') {
+            continue;
         }
+        if (isMediaRefPart(part)) {
+            throw new TheorumError('media references are not supported on openAi');
+        }
+        references.push(wireInputReference(part));
     }
     return references;
 }

package/esm/src/providers/openrouter/openai/sdk-messages.d.ts

@@ -8,7 +8,7 @@
  */
 import type { ModelMessage } from 'ai';
 import type { InteractionPart, ProviderCompleteRequest, TurnHistoryMessage } from '../../../kernel/types.js';
-export declare function sdkPart(part: InteractionPart): Record<string, unknown>;
+export declare function sdkPart(input: InteractionPart): Record<string, unknown>;
 export declare function sdkContentFromParts(parts: InteractionPart[]): string | Array<Record<string, unknown>>;
 export declare function sdkContentFromOptionalParts(parts: InteractionPart[] | undefined, text: string | undefined): string | Array<Record<string, unknown>>;
 export declare function toolResultMessage(msg: TurnHistoryMessage): ModelMessage;

package/esm/src/providers/openrouter/openai/sdk-messages.js

@@ -6,14 +6,23 @@
  *
  * @module
  */
+import { TheorumError } from '../../../guardrails/error.js';
+import { isMediaRefPart } from '../../../kernel/interaction-parts.js';
 import { fallbackToolCallId, parseToolInput } from './compat.js';
+function inlineMediaPart(part) {
+    if (isMediaRefPart(part)) {
+        throw new TheorumError('media references are not supported on openAi');
+    }
+    return part;
+}
 function stringDefault(value, fallback) {
     return value === undefined ? fallback : value;
 }
-export function sdkPart(part) {
-    if (part.type === 'text') {
-        return { type: 'text', text: part.text };
+export function sdkPart(input) {
+    if (input.type === 'text') {
+        return { type: 'text', text: input.text };
     }
+    const part = inlineMediaPart(input);
     if (part.type === 'image') {
         return {
             type: 'image',
@@ -39,15 +48,33 @@ export function sdkContentFromOptionalParts(parts, text) {
 }
 export function toolResultMessage(msg) {
     const toolName = stringDefault(msg.name, 'tool');
+    const toolCallId = stringDefault(msg.tool_call_id, fallbackToolCallId(msg.name));
+    const output = msg.parts && msg.parts.length > 0
+        ? {
+            type: 'content',
+            value: msg.parts.map((input) => {
+                if (input.type === 'text') {
+                    return { type: 'text', text: input.text };
+                }
+                // image / audio / video / document — AI SDK tool-result file parts
+                const part = inlineMediaPart(input);
+                return {
+                    type: 'file',
+                    mediaType: part.mimeType,
+                    data: { type: 'data', data: part.data },
+                };
+            }),
+        }
+        : { type: 'text', value: stringDefault(msg.content, '') };
     // AI SDK ToolModelMessage is a branded union; structural tool-result is correct at runtime.
     return {
         role: 'tool',
         content: [
             {
                 type: 'tool-result',
-                toolCallId: stringDefault(msg.tool_call_id, fallbackToolCallId(msg.name)),
+                toolCallId,
                 toolName,
-                output: { type: 'text', value: stringDefault(msg.content, '') },
+                output,
             },
         ],
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theorum",
-  "version": "1.0.0",
+  "version": "1.1.3",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",

package/esm/src/interface/blocks.d.ts

@@ -1,20 +0,0 @@
-/**
- * Turn event folding — map kernel `TurnEvent` streams to transcript blocks.
- *
- * @module
- */
-import type { TurnEvent } from '../kernel/types.js';
-import type { FoldTurnEventsOptions, TranscriptBlock, UserTurnDraft } from './types.js';
-declare function resetBlockIds(): void;
-/** Build transcript blocks for a user-authored turn. */
-declare function buildUserTurnBlocks(draft: UserTurnDraft, idPrefix?: string): TranscriptBlock[];
-/**
- * Fold a single assistant turn's `TurnEvent` stream into ordered transcript blocks.
- *
- * Merges consecutive `text` and `thought` deltas, upserts tool calls by id, and
- * skips kernel bookkeeping events (`tokens`, `session`) unless folded into `turn-done`.
- */
-declare function foldTurnEvents(events: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
-/** User draft blocks followed by folded assistant turn events. */
-declare function foldConversationTurn(draft: UserTurnDraft, assistantEvents: readonly TurnEvent[], options?: FoldTurnEventsOptions): TranscriptBlock[];
-export { buildUserTurnBlocks, foldConversationTurn, foldTurnEvents, resetBlockIds };