theorum 0.1.15 → 1.1.3

package/esm/src/providers/{openrouter.js → openrouter/chat.js}

@@ -3,25 +3,27 @@
  *
  * THEORUM keeps the public `ModelProvider` and `TurnEvent` contract; AI SDK
  * owns the OpenRouter call, stream parsing, provider compatibility, and tool
- * call normalization.
+ * call normalization. Message assembly delegates to `openai/sdk-messages.ts`.
  *
  * @module
  */
 import { createOpenRouter } from '@openrouter/ai-sdk-provider';
 import { jsonSchema, streamText, tool, } from 'ai';
-import { isAbortError, toErrorEvent } from '../guardrails/error.js';
-import { tryStructured } from '../kernel/engine/delta.js';
-import { getStructured } from '../kernel/registry/schemas.js';
-import { turnStopFromOpenRouter } from '../kernel/stop.js';
-import { exposeForTests } from './expose-for-tests.js';
-import { resolveOpenRouterModel, resolveOpenRouterPlugins, toOpenRouterPayload, } from './openrouter-payload.js';
-function trimApiKey(explicitKey) {
+import { isAbortError, TheorumError, toErrorEvent } from '../../guardrails/error.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';
+import { resolveOpenAiGatewayApiKey } from './resolve-api-key.js';
+export function trimApiKey(explicitKey) {
     if (explicitKey?.trim()) {
         return explicitKey.trim();
     }
     return undefined;
 }
-function createAccumulator() {
+export function createAccumulator() {
     return {
         text: '',
         evidenceSeen: false,
@@ -29,127 +31,35 @@ function createAccumulator() {
         errored: false,
     };
 }
-function mediaPart(part) {
-    if (part.type === 'text') {
-        return { type: 'text', text: part.text };
-    }
-    if (part.type === 'image') {
-        return {
-            type: 'image',
-            image: `data:${part.mimeType};base64,${part.data}`,
-        };
-    }
-    return { type: 'file', mediaType: part.mimeType, data: part.data };
-}
-function contentFromParts(parts) {
-    if (parts.every((part) => part.type === 'text')) {
-        return parts
-            .map((part) => (part.type === 'text' ? part.text : ''))
-            .filter(Boolean)
-            .join('\n');
-    }
-    return parts.map(mediaPart);
-}
-function parseToolInput(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return { _raw: raw };
-    }
-}
-function stringDefault(value, fallback) {
-    return value === undefined ? fallback : value;
-}
-function fallbackToolCallId(name) {
-    return `call_${stringDefault(name, 'tool')}`;
-}
-function toolResultContent(msg) {
-    const toolName = stringDefault(msg.name, 'tool');
-    return {
-        role: 'tool',
-        content: [
-            {
-                type: 'tool-result',
-                toolCallId: stringDefault(msg.tool_call_id, fallbackToolCallId(msg.name)),
-                toolName,
-                output: { type: 'text', value: stringDefault(msg.content, '') },
-            },
-        ],
-    };
-}
-function assistantToolCallContent(msg) {
-    if (!msg.tool_calls || msg.tool_calls.length === 0) {
-        return null;
-    }
-    return {
-        role: 'assistant',
-        content: msg.tool_calls.map((call) => ({
-            type: 'tool-call',
-            toolCallId: call.id,
-            toolName: call.function.name,
-            input: parseToolInput(call.function.arguments),
-        })),
-    };
-}
-function historyMessage(msg) {
-    if (msg.role === 'tool') {
-        return toolResultContent(msg);
-    }
-    return assistantToolCallContent(msg) || contentHistoryMessage(msg);
-}
-function contentFromOptionalParts(parts, text) {
-    if (!parts || parts.length === 0) {
-        return stringDefault(text, '');
-    }
-    return contentFromParts(parts);
-}
-function contentHistoryMessage(msg) {
-    const content = contentFromOptionalParts(msg.parts, msg.content);
-    return { role: msg.role, content };
-}
-function sourceEvent(part) {
+export function sourceEvent(part) {
     if (part.sourceType !== 'url') {
         return {
             type: 'evidence',
             evidence: { provider: 'openrouter', raw: part },
         };
     }
-    const title = part.title ?? part.url;
+    const title = part.title ?? part.url ?? '';
     return {
         type: 'evidence',
         evidence: {
             provider: 'openrouter',
             raw: part,
-            citations: [part.url],
-            sources: [{ title, uri: part.url, type: 'web' }],
+            citations: part.url ? [part.url] : [],
+            sources: part.url ? [{ title, uri: part.url, type: 'web' }] : [],
         },
     };
 }
-function buildMessages(req) {
-    const messages = [];
-    for (const msg of req.history ?? []) {
-        const wired = historyMessage(msg);
-        if (wired) {
-            messages.push(wired);
-        }
-    }
-    if (req.input.length > 0) {
-        messages.push({ role: 'user', content: contentFromParts(req.input) });
-    }
-    return messages;
-}
-function schemaForTool(decl) {
+export function schemaForTool(decl) {
     return decl.parameters ?? { type: 'object', properties: {}, additionalProperties: true };
 }
-function buildTools(dynamicTools) {
-    if (!dynamicTools || dynamicTools.length === 0) {
+export function buildTools(wireTools) {
+    if (!wireTools || wireTools.length === 0) {
         return undefined;
     }
     const tools = {};
-    for (const decl of dynamicTools) {
+    for (const decl of wireTools) {
         tools[decl.name] = tool({
-            description: decl.description ?? '',
+            description: decl.description,
             inputSchema: jsonSchema(schemaForTool(decl)),
         });
     }
@@ -167,36 +77,44 @@ function openRouterSettings(req) {
         settings.web_search_options = {};
     return settings;
 }
-function tokensFromUsage(usage) {
+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 } : {}),
     };
 }
-function rawRecord(value) {
+export function rawRecord(value) {
     if (value && typeof value === 'object' && !Array.isArray(value)) {
         return value;
     }
     return undefined;
 }
-function stringArray(value) {
+export function stringArray(value) {
     if (!Array.isArray(value)) {
         return undefined;
     }
     const out = value.filter((item) => typeof item === 'string');
     return out.length > 0 ? out : undefined;
 }
-function metadataRecord(raw, key) {
+export function metadataRecord(raw, key) {
     return rawRecord(raw[key]);
 }
-function citationCandidates(raw) {
+export function citationCandidates(raw) {
     const openrouter = metadataRecord(raw, 'openrouter') ?? {};
     return [
         raw.citations,
@@ -207,7 +125,7 @@ function citationCandidates(raw) {
         metadataRecord(openrouter, 'provider_metadata')?.citations,
     ];
 }
-function nestedCitations(raw) {
+export function nestedCitations(raw) {
     for (const candidate of citationCandidates(raw)) {
         const citations = stringArray(candidate);
         if (citations) {
@@ -216,7 +134,7 @@ function nestedCitations(raw) {
     }
     return undefined;
 }
-function metadataAnnotations(raw) {
+export function metadataAnnotations(raw) {
     const openrouter = metadataRecord(raw, 'openrouter');
     if (Array.isArray(raw.annotations)) {
         return raw.annotations;
@@ -226,7 +144,7 @@ function metadataAnnotations(raw) {
     }
     return undefined;
 }
-function evidenceFromMetadata(metadata, acc) {
+export function evidenceFromMetadata(metadata, acc) {
     const raw = rawRecord(metadata);
     if (!raw || acc.evidenceSeen) {
         return undefined;
@@ -242,7 +160,7 @@ function evidenceFromMetadata(metadata, acc) {
         evidence: { provider: 'openrouter', raw, citations, annotations },
     };
 }
-function toolArguments(input) {
+export function toolArguments(input) {
     if (input && typeof input === 'object' && !Array.isArray(input)) {
         return input;
     }
@@ -251,10 +169,10 @@ function toolArguments(input) {
     }
     return { value: input };
 }
-function toolResultData(output) {
+export function toolResultData(output) {
     return rawRecord(output);
 }
-function rawThoughtEvent(raw) {
+export function rawThoughtEvent(raw) {
     const choices = raw.choices;
     if (!Array.isArray(choices)) {
         return undefined;
@@ -267,7 +185,7 @@ function rawThoughtEvent(raw) {
     }
     return undefined;
 }
-function rawChoiceMessageEvidence(raw, acc) {
+export function rawChoiceMessageEvidence(raw, acc) {
     const choices = raw.choices;
     if (!Array.isArray(choices)) {
         return undefined;
@@ -284,7 +202,7 @@ function rawChoiceMessageEvidence(raw, acc) {
     }
     return undefined;
 }
-function rawEvents(raw, acc) {
+export function rawEvents(raw, acc) {
     const record = rawRecord(raw);
     if (!record) {
         return [];
@@ -302,6 +220,13 @@ 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);
@@ -316,7 +241,7 @@ function rawEvents(raw, acc) {
     }
     return events;
 }
-function toolCallEvent(part) {
+export function toolCallEvent(part) {
     return {
         type: 'tool',
         tool: {
@@ -326,32 +251,30 @@ function toolCallEvent(part) {
         },
     };
 }
-function toolResultEvent(part) {
+export function toolResultEvent(part) {
+    const output = typeof part.output === 'string' ? part.output : toolResultData(part.output);
     return {
         type: 'tool',
         tool: {
             name: part.toolName,
             arguments: toolArguments(part.input),
-            result: {
-                status: 'ok',
-                data: toolResultData(part.output),
-                finding: typeof part.output === 'string' ? part.output : undefined,
-            },
             id: part.toolCallId,
+            phase: 'complete',
+            output,
         },
     };
 }
-function tokenEvent(part) {
+export function tokenEvent(part) {
     const tokens = tokensFromUsage(part.totalUsage);
     return tokens ? { type: 'tokens', tokens } : undefined;
 }
-function providerMetadataEvent(part, acc) {
+export function providerMetadataEvent(part, acc) {
     if (!('providerMetadata' in part)) {
         return undefined;
     }
     return evidenceFromMetadata(part.providerMetadata, acc);
 }
-function eventFromPart(part, acc) {
+export function eventFromPart(part, acc) {
     const mapped = primaryEventFromPart(part, acc);
     if (mapped) {
         return [mapped];
@@ -359,7 +282,7 @@ function eventFromPart(part, acc) {
     const evidence = providerMetadataEvent(part, acc);
     return evidence ? [evidence] : [];
 }
-function primaryEventFromPart(part, acc) {
+export function primaryEventFromPart(part, acc) {
     switch (part.type) {
         case 'text-delta':
             acc.text += part.text;
@@ -385,59 +308,84 @@ function primaryEventFromPart(part, acc) {
             return undefined;
     }
 }
-function finishEvent(part, acc) {
-    if ('finishReason' in part && part.finishReason != null) {
+export function finishEvent(part, acc) {
+    if (part.finishReason != null) {
         acc.finishReason = String(part.finishReason);
     }
     if (acc.emittedTokens) {
         return undefined;
     }
-    const event = tokenEvent(part);
+    if (!part.totalUsage) {
+        return undefined;
+    }
+    const event = tokenEvent({ totalUsage: part.totalUsage });
     if (event) {
         acc.emittedTokens = true;
     }
     return event;
 }
-function* finalEvents(req, acc) {
+export function* finalEvents(req, acc) {
     if (acc.errored) {
         return;
     }
     if (req.structured && acc.text) {
-        const structured = tryStructured(acc.text);
-        if (structured) {
-            yield structured;
+        const parsed = parseStructuredOutput(acc.text);
+        if (!parsed.ok) {
+            yield toErrorEvent(new TheorumError(parsed.error));
+            return;
         }
+        yield { type: 'structured', structured: parsed.structured };
     }
     yield {
         type: 'done',
-        stop: turnStopFromOpenRouter(acc.finishReason, acc.nativeFinishReason),
+        stop: turnStopFromOpenAiFinishReason(acc.finishReason, acc.nativeFinishReason),
     };
 }
 function createStreamContext(req, config, apiKey) {
     const openrouter = createOpenRouter({
         apiKey,
         baseURL: config.baseUrl,
-        headers: openRouterHeaders(config),
+        headers: openAiGatewayHeaders(config),
         fetch: config.fetch,
         compatibility: 'strict',
     });
     return {
         openrouter,
-        modelName: resolveOpenRouterModel(req.model, config.modelMap, {
-            apiId: req.apiId,
-            openRouterId: req.openRouterId,
-        }),
+        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: buildMessages(req),
+        instructions: delivery.instructions,
+        messages,
         allowSystemInMessages: true,
         temperature: req.temperature,
         maxOutputTokens: req.maxOutputTokens,
-        tools: buildTools(req.dynamicTools),
+        tools: buildTools(req.wireTools),
         providerOptions: providerOptionsFor(req),
         include: { rawChunks: true },
         abortSignal: req.signal,
@@ -448,7 +396,7 @@ async function* yieldAiSdkStream(req, acc, context) {
     const result = streamText(streamTextOptions(req, context));
     for await (const part of result.stream) {
         if (part.type === 'raw') {
-            req.tapGemini?.(rawRecord(part.rawValue) ?? { rawValue: part.rawValue });
+            req.tapUpstream?.(rawRecord(part.rawValue) ?? { rawValue: part.rawValue });
             for (const event of rawEvents(part.rawValue, acc)) {
                 yield event;
             }
@@ -459,13 +407,16 @@ async function* yieldAiSdkStream(req, acc, context) {
         }
     }
 }
-function missingOpenRouterKey() {
+export function missingOpenRouterKey() {
     return toErrorEvent('missing OpenRouter API key');
 }
 async function* streamOpenRouter(req, config) {
-    const apiKey = trimApiKey(config.apiKey);
-    if (!apiKey) {
-        yield missingOpenRouterKey();
+    let apiKey;
+    try {
+        apiKey = resolveOpenAiGatewayApiKey(config, req.keySlot);
+    }
+    catch (err) {
+        yield toErrorEvent(err);
         return;
     }
     const acc = createAccumulator();
@@ -481,93 +432,28 @@ async function* streamOpenRouter(req, config) {
         yield toErrorEvent(err);
     }
 }
-function responseFormatFor(req) {
-    if (!req.structured)
-        return undefined;
-    const spec = getStructured(req.structured);
-    if (!spec.jsonSchema)
-        return undefined;
-    return {
-        type: 'json_schema',
-        json_schema: {
-            name: String(req.structured),
-            strict: true,
-            schema: spec.jsonSchema,
-        },
-    };
-}
-function providerOptionsFor(req) {
+export function providerOptionsFor(req) {
     const openrouter = {};
-    if (req.thinking !== 'none') {
+    if (req.thinking && req.thinking !== 'none') {
         openrouter.reasoning = { effort: req.thinking };
     }
-    const responseFormat = responseFormatFor(req);
+    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 };
 }
-function openRouterHeaders(config) {
-    const headers = {};
-    if (config.siteUrl) {
-        headers['HTTP-Referer'] = config.siteUrl;
-    }
-    if (config.siteName) {
-        headers['X-Title'] = config.siteName;
-    }
-    return Object.keys(headers).length > 0 ? headers : undefined;
-}
 /** Create a `ModelProvider` backed by OpenRouter through AI SDK Core. */
-function createOpenRouterProvider(config = {}) {
+export function createOpenRouterProvider(config = {}) {
     return {
         complete: (req) => streamOpenRouter(req, config),
     };
 }
-export { createOpenRouterProvider, resolveOpenRouterModel, toOpenRouterPayload };
-exposeForTests('openrouter', {
-    trimApiKey,
-    createAccumulator,
-    mediaPart,
-    contentFromParts,
-    parseToolInput,
-    stringDefault,
-    fallbackToolCallId,
-    toolResultContent,
-    assistantToolCallContent,
-    historyMessage,
-    contentFromOptionalParts,
-    contentHistoryMessage,
-    buildMessages,
-    schemaForTool,
-    buildTools,
-    openRouterSettings,
-    tokensFromUsage,
-    rawRecord,
-    stringArray,
-    metadataRecord,
-    citationCandidates,
-    nestedCitations,
-    metadataAnnotations,
-    evidenceFromMetadata,
-    toolArguments,
-    toolResultData,
-    rawThoughtEvent,
-    rawChoiceMessageEvidence,
-    rawEvents,
-    toolCallEvent,
-    toolResultEvent,
-    tokenEvent,
-    providerMetadataEvent,
-    eventFromPart,
-    primaryEventFromPart,
-    finishEvent,
-    sourceEvent,
-    finalEvents,
-    responseFormatFor,
-    providerOptionsFor,
-    openRouterHeaders,
-    missingOpenRouterKey,
-    streamTextOptions,
-});

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

@@ -0,0 +1,34 @@
+/**
+ * OpenAI-compatible image generation transport (internal).
+ *
+ * Hosts use `createProvider(profile, { openAiGateway })` — this module is selected
+ * when the profile is an openAi image role on OpenRouter.
+ *
+ * Image-only turns POST `/images`. When `image.includeText` is set, chat
+ * completions carry an OpenRouter image-generation server tool so the model may
+ * return interleaved assistant text and images.
+ *
+ * @module
+ */
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../../kernel/types.js';
+import type { OpenAiGatewayConfig } from '../types.js';
+/** OpenRouter chat server tool for inline image generation. */
+export declare const OPENROUTER_IMAGE_TOOL = "openrouter:image_generation";
+export type ImageProviderConfig = OpenAiGatewayConfig;
+export declare function buildImageHeaders(apiKey: string, config: ImageProviderConfig): Record<string, string>;
+export declare function mediaFromImagesResponse(body: Record<string, unknown>, fallbackMime?: string): {
+    mimeType: string;
+    data: string;
+} | null;
+export declare function fetchImageAsBase64(url: string, fetchFn: typeof fetch, signal?: AbortSignal): Promise<{
+    mimeType: string;
+    data: string;
+} | null>;
+export declare function markdownImageUrls(content: string): string[];
+export declare function plainTextFromContent(content: unknown): string;
+export declare function buildInterleavedChatPayload(req: ProviderCompleteRequest): Record<string, unknown>;
+export declare function yieldInterleavedChat(req: ProviderCompleteRequest, config: ImageProviderConfig, apiKey: string): AsyncGenerator<TurnEvent>;
+export declare function yieldImagesEndpoint(req: ProviderCompleteRequest, config: ImageProviderConfig, apiKey: string): AsyncGenerator<TurnEvent>;
+export declare function streamImage(req: ProviderCompleteRequest, config?: ImageProviderConfig): AsyncGenerator<TurnEvent>;
+/** Internal ModelProvider for openAi image roles on OpenRouter. */
+export declare function createImageProvider(config?: ImageProviderConfig): ModelProvider;