@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/providers/openrouter/images-protocol.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { asRecord, nonEmptyString } from '../../kernel/engine/record.js';
+import { defineProtocol, } from '../../kernel/protocols/mod.js';
+import { turnStopFromOpenAiFinishReason } from '../../kernel/stop.js';
+import { imagesFromChatMessage, imagesFromImagesBody, OPENROUTER_IMAGE_TOOL } from './image.js';
+import { buildChatMessages } from './openai/compat.js';
+import { buildImagesPayload, extractPromptText, imageToolParameters, } from './openai/image-payload.js';
+import { openAiUsageTokens } from './openai/usage.js';
+function json(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function tokens(row) {
+    const counted = openAiUsageTokens(row.usage);
+    return counted ? [{ type: 'tokens', tokens: counted }] : [];
+}
+function noImage() {
+    return new TheoremError('bad_response', 'no image returned from image generation');
+}
+/** `/images`: the picture alone, answered whole. */
+async function* images(context, request) {
+    const body = json(buildImagesPayload({ ...request, apiId: context.apiId }));
+    for await (const row of context.send(body, { stream: false })) {
+        const media = imagesFromImagesBody(row);
+        if (!media.length)
+            throw noImage();
+        for (const item of media)
+            yield { type: 'media', media: item };
+        yield* tokens(row);
+        // why: the endpoint answers whole or not at all: a body with images completed.
+        yield { type: 'done', stop: { kind: 'completed' } };
+    }
+}
+/** Text with the picture: Chat Completions with OpenRouter's image tool, on the chat path. */
+async function* withText(context, request, image) {
+    const body = json({
+        model: context.apiId,
+        stream: false,
+        provider: { require_parameters: true },
+        messages: buildChatMessages(request),
+        temperature: request.temperature,
+        max_tokens: request.maxOutputTokens,
+        ...(request.thinking ? { reasoning: { effort: request.thinking } } : {}),
+        tools: [{ type: OPENROUTER_IMAGE_TOOL, parameters: imageToolParameters(image) }],
+    });
+    for await (const row of context.send(body, { stream: false, path: '/chat/completions' })) {
+        const choice = asRecord(Array.isArray(row.choices) ? row.choices[0] : undefined);
+        const message = asRecord(choice?.message);
+        const text = nonEmptyString(message?.content);
+        if (text)
+            yield { type: 'text', text };
+        const media = message ? imagesFromChatMessage(message) : [];
+        if (!media.length)
+            throw noImage();
+        for (const item of media)
+            yield { type: 'media', media: item };
+        yield* tokens(row);
+        const finish = typeof choice?.finish_reason === 'string' ? choice.finish_reason : undefined;
+        const native = typeof choice?.native_finish_reason === 'string' ? choice.native_finish_reason : undefined;
+        yield { type: 'done', stop: turnStopFromOpenAiFinishReason(finish, native) };
+    }
+}
+/** OpenRouter's image generation: `/images`, or the chat path with its image tool when text is wanted too. */
+export const openRouterImages = defineProtocol({
+    id: 'openRouterImages',
+    name: 'OpenRouter Images',
+    description: "OpenRouter's image generation, with or without text beside the picture.", // labels-exempt: builder field description, read by the studio and docs
+    endpoints: { image: '/images' },
+    options: z.strictObject({}),
+    create(context) {
+        return {
+            complete(request) {
+                const image = request.image;
+                if (!image)
+                    throw new TheoremError('request', 'missing image response format');
+                if (!extractPromptText(request.input))
+                    throw new TheoremError('request', 'empty text for image generation');
+                return image.includeText ? withText(context, request, image) : images(context, request);
+            },
+        };
+    },
+});

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

@@ -0,0 +1,19 @@
+import { type ProducedError } from '../../../guardrails/error.js';
+import type { InteractionPart, ModelRequest, ResolvedStructured, WireFunctionTool } from '../../../kernel/types.js';
+/** The detail is the body's `error.message` (or raw text), so the upstream reason reaches traces. */
+declare function httpErrorEvent(res: Response, label: string): Promise<ProducedError>;
+interface GatewayHeaderConfig {
+    siteUrl?: string;
+    siteName?: string;
+}
+/** Text-only input collapses to one string; mixed input is a content-part array. */
+export declare function wireMessageContent(parts: InteractionPart[]): unknown;
+/** `includeSystem: false` when the caller passes system text separately (AI SDK `instructions`). */
+declare function buildChatMessages(req: Pick<ModelRequest, 'system' | 'history' | 'input'>, options?: {
+    includeSystem?: boolean;
+}): Record<string, unknown>[];
+declare function wireTools(wireTools?: WireFunctionTool[]): Record<string, unknown>[] | undefined;
+declare function resolveResponseFormat(structured: ResolvedStructured | null): Record<string, unknown> | undefined;
+declare function openAiGatewayHeaders(config: GatewayHeaderConfig): Record<string, string> | undefined;
+export type { GatewayHeaderConfig };
+export { buildChatMessages, httpErrorEvent, openAiGatewayHeaders, resolveResponseFormat, wireTools, };

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

@@ -0,0 +1,162 @@
+import { kindOfHttpStatus, TheoremError, toErrorEvent, } from '../../../guardrails/error.js';
+import { asRecord } from '../../../kernel/engine/record.js';
+import { historyMessageParts, isMediaRefPart } from '../../../kernel/interaction-parts.js';
+import { withCarriedToolFiles } from '../../shared/carried-tool-files.js';
+import { historyToolIdentity } from '../../shared/tool-args.js';
+/** The detail is the body's `error.message` (or raw text), so the upstream reason reaches traces. */
+async function httpErrorEvent(res, label) {
+    const text = (await res.text()).trim();
+    let detail = text;
+    try {
+        const message = asRecord(asRecord(JSON.parse(text))?.error)?.message;
+        if (typeof message === 'string' && message)
+            detail = message;
+    }
+    catch {
+        // why: Not JSON: the raw body is the detail.
+    }
+    const head = `${label} HTTP ${String(res.status)}`;
+    return toErrorEvent(new TheoremError(kindOfHttpStatus(res.status), detail ? `${head}: ${detail}` : head));
+}
+function rejectMediaRef(part) {
+    if (isMediaRefPart(part)) {
+        throw new TheoremError('unsupported', 'media references are not supported on openAi');
+    }
+}
+function wireAudioPart(part) {
+    let format = 'mp3';
+    if (part.mimeType.includes('wav')) {
+        format = 'wav';
+    }
+    return {
+        type: 'input_audio',
+        input_audio: {
+            data: part.data,
+            format,
+        },
+    };
+}
+/** Text-only input collapses to one string; mixed input is a content-part array. */
+export function wireMessageContent(parts) {
+    const isAllText = parts.every((p) => p.type === 'text');
+    if (isAllText) {
+        return parts
+            .map((p) => {
+            if (p.type === 'text') {
+                return p.text;
+            }
+            return '';
+        })
+            .filter(Boolean)
+            .join('\n');
+    }
+    return parts.map((part) => {
+        if (part.type === 'text') {
+            return { type: 'text', text: part.text };
+        }
+        rejectMediaRef(part);
+        if (part.type === 'image') {
+            return {
+                type: 'image_url',
+                image_url: { url: `data:${part.mimeType};base64,${part.data}` },
+            };
+        }
+        if (part.type === 'audio') {
+            return wireAudioPart(part);
+        }
+        return {
+            type: 'file',
+            file: {
+                filename: part.type === 'video' ? 'clip.bin' : 'document.bin',
+                file_data: `data:${part.mimeType};base64,${part.data}`,
+            },
+        };
+    });
+}
+/** Assistant `tool_calls` are rebuilt to strip non-standard fields. */
+function wireHistoryMessage(msg) {
+    const content = wireMessageContent(historyMessageParts(msg));
+    if (msg.role === 'tool') {
+        return {
+            role: 'tool',
+            ...historyToolIdentity({ tool_call_id: msg.tool_call_id, name: msg.name }),
+            content,
+        };
+    }
+    const wired = {
+        role: msg.role,
+        content,
+    };
+    if (msg.tool_calls && msg.tool_calls.length > 0) {
+        wired.tool_calls = msg.tool_calls.map((tc) => ({
+            id: tc.id,
+            type: 'function',
+            function: { name: tc.function.name, arguments: tc.function.arguments },
+        }));
+    }
+    if (msg.name) {
+        wired.name = msg.name;
+    }
+    return wired;
+}
+// why: A PDF inside a `role: 'tool'` message was accepted and never read, and was read from the user message after it; a photo inside one was read (live, 13/10/2026, google/gemini-3.5-flash-lite).
+const TOOL_MESSAGE_PART_TYPES = new Set(['text', 'image']);
+/** `includeSystem: false` when the caller passes system text separately (AI SDK `instructions`). */
+function buildChatMessages(req, options) {
+    const includeSystem = options?.includeSystem !== false;
+    const messages = [];
+    if (includeSystem && req.system) {
+        messages.push({ role: 'system', content: req.system });
+    }
+    for (const h of withCarriedToolFiles(req.history ?? [], TOOL_MESSAGE_PART_TYPES)) {
+        messages.push(wireHistoryMessage(h));
+    }
+    if (req.input.length > 0) {
+        messages.push({
+            role: 'user',
+            content: wireMessageContent(req.input),
+        });
+    }
+    return messages;
+}
+function wireTools(wireTools) {
+    if (!wireTools || wireTools.length === 0) {
+        return undefined;
+    }
+    return wireTools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+        },
+    }));
+}
+/** OpenAI takes a schema name of at most 64 of `[A-Za-z0-9_-]` and refuses the call otherwise. */
+function schemaName(id) {
+    return id.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64);
+}
+function resolveResponseFormat(structured) {
+    if (!structured) {
+        return undefined;
+    }
+    return {
+        type: 'json_schema',
+        json_schema: {
+            name: schemaName(structured.id),
+            strict: true,
+            schema: structured.jsonSchema,
+        },
+    };
+}
+function openAiGatewayHeaders(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;
+}
+export { buildChatMessages, httpErrorEvent, openAiGatewayHeaders, resolveResponseFormat, wireTools, };

package/esm/src/providers/openrouter/openai/image-payload.d.ts

@@ -0,0 +1,9 @@
+import type { ImageResponseFormat, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, ModelRequest } from '../../../kernel/types.js';
+export declare function extractPromptText(input: InteractionPart[]): string;
+export declare function outputFormatFromMime(mimeType: string): string;
+export declare function wireInputReference(part: InteractionMediaPart | InteractionMediaRefPart): Record<string, unknown>;
+/** Non-image media is refused, not dropped: a dropped file would leave the user believing the model saw it. */
+export declare function wireInputReferences(input: InteractionPart[]): Record<string, unknown>[];
+export declare function attachImagePins(payload: Record<string, unknown>, image: ImageResponseFormat): void;
+export declare function buildImagesPayload(req: ModelRequest): Record<string, unknown>;
+export declare function imageToolParameters(image: ImageResponseFormat): Record<string, unknown>;

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

@@ -0,0 +1,115 @@
+import { TheoremError } from '../../../guardrails/error.js';
+import { isMediaRefPart } from '../../../kernel/interaction-parts.js';
+export function extractPromptText(input) {
+    return input
+        .filter((part) => part.type === 'text')
+        .map((part) => (part.type === 'text' ? part.text : ''))
+        .join('\n')
+        .trim();
+}
+export function outputFormatFromMime(mimeType) {
+    const essence = mimeType.toLowerCase().replace(/^image\//, '');
+    if (essence === 'jpg') {
+        return 'jpeg';
+    }
+    if (essence === 'png' || essence === 'jpeg' || essence === 'webp') {
+        return essence;
+    }
+    return 'png';
+}
+const HTTP_URL = /^https?:\/\//i;
+export function wireInputReference(part) {
+    const url = isMediaRefPart(part) ? part.uri : `data:${part.mimeType};base64,${part.data}`;
+    return { type: 'image_url', image_url: { url } };
+}
+/** Non-image media is refused, not dropped: a dropped file would leave the user believing the model saw it. */
+export function wireInputReferences(input) {
+    const references = [];
+    for (const part of input) {
+        if (part.type === 'text') {
+            continue;
+        }
+        if (part.type !== 'image') {
+            throw new TheoremError('unsupported', `${part.mimeType} input is not supported on /images, which takes image references only`);
+        }
+        if (isMediaRefPart(part) && !HTTP_URL.test(part.uri)) {
+            throw new TheoremError('unsupported', 'only http(s) media references are supported on /images');
+        }
+        references.push(wireInputReference(part));
+    }
+    return references;
+}
+export function attachImagePins(payload, image) {
+    if (image.aspectRatio) {
+        payload.aspect_ratio = image.aspectRatio;
+    }
+    if (image.resolution) {
+        payload.resolution = image.resolution;
+    }
+    if (image.mimeType) {
+        payload.output_format = outputFormatFromMime(image.mimeType);
+    }
+    if (image.quality) {
+        payload.quality = image.quality;
+    }
+    if (image.background) {
+        payload.background = image.background;
+    }
+    if (image.n !== undefined) {
+        payload.n = image.n;
+    }
+    if (image.seed !== undefined) {
+        payload.seed = image.seed;
+    }
+    if (image.outputCompression !== undefined) {
+        payload.output_compression = image.outputCompression;
+    }
+}
+export function buildImagesPayload(req) {
+    if (!req.image) {
+        throw new Error('buildImagesPayload requires req.image');
+    }
+    const payload = {
+        model: req.apiId,
+        prompt: extractPromptText(req.input),
+    };
+    attachImagePins(payload, req.image);
+    const references = wireInputReferences(req.input);
+    if (references.length > 0) {
+        payload.input_references = references;
+    }
+    if (req.stream === false) {
+        payload.stream = false;
+    }
+    return payload;
+}
+export function imageToolParameters(image) {
+    const params = {};
+    if (image.mimeType) {
+        params.output_format = outputFormatFromMime(image.mimeType);
+    }
+    if (image.aspectRatio) {
+        params.aspect_ratio = image.aspectRatio;
+    }
+    if (image.resolution) {
+        params.resolution = image.resolution;
+    }
+    if (image.quality) {
+        params.quality = image.quality;
+    }
+    if (image.background) {
+        params.background = image.background;
+    }
+    if (image.outputCompression !== undefined) {
+        params.output_compression = image.outputCompression;
+    }
+    for (const [name, value] of [
+        ['n', image.n],
+        ['seed', image.seed],
+    ]) {
+        if (value !== undefined) {
+            throw new TheoremError('unsupported', `image.${name} is not supported with image.includeText`);
+        }
+    }
+    return params;
+}

package/esm/src/providers/openrouter/openai/reasoning-state.d.ts

@@ -0,0 +1,2 @@
+import { type JsonObject } from '../../../kernel/json.js';
+export declare function collectReasoning(row: Record<string, unknown>, details: Map<string, JsonObject>): string;

package/esm/src/providers/openrouter/openai/reasoning-state.js

@@ -0,0 +1,31 @@
+import { jsonObjectSchema } from '../../../kernel/json.js';
+import { isRecord } from '../../../kernel/util/record.js';
+export function collectReasoning(row, details) {
+    let content = '';
+    for (const choice of Array.isArray(row.choices) ? row.choices : []) {
+        if (!isRecord(choice))
+            continue;
+        const delta = isRecord(choice.delta)
+            ? choice.delta
+            : isRecord(choice.message)
+                ? choice.message
+                : undefined;
+        if (!delta)
+            continue;
+        if (typeof delta.reasoning === 'string')
+            content += delta.reasoning;
+        else if (typeof delta.reasoning_content === 'string')
+            content += delta.reasoning_content;
+        for (const raw of Array.isArray(delta.reasoning_details) ? delta.reasoning_details : []) {
+            const detail = jsonObjectSchema.parse(raw);
+            const key = JSON.stringify([detail.index ?? detail.id ?? details.size, detail.type]);
+            const previous = details.get(key);
+            const merged = { ...previous, ...detail };
+            for (const field of ['text', 'summary', 'data'])
+                if (previous && typeof previous[field] === 'string' && typeof detail[field] === 'string')
+                    merged[field] = previous[field] + detail[field];
+            details.set(key, merged);
+        }
+    }
+    return content;
+}

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

@@ -0,0 +1,8 @@
+import type { TurnResponse, TurnTokens } from '../../../kernel/types.js';
+/**
+ * Chat Completions reports `prompt_tokens` / `completion_tokens`, the Images API
+ * `input_tokens` / `output_tokens`. Both already mean what OpenTelemetry means:
+ * completion includes reasoning and prompt includes cached tokens.
+ */
+export declare function openAiUsageTokens(raw: unknown): TurnTokens | undefined;
+export declare function openAiResponse(raw: Record<string, unknown>): TurnResponse | undefined;

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

@@ -0,0 +1,56 @@
+import { asRecord, nonEmptyString } from '../../../kernel/engine/record.js';
+import { reportedTokens, usageCount } from '../../../kernel/engine/usage.js';
+function cost(usage) {
+    const usd = usageCount(usage.cost);
+    if (usd === undefined)
+        return undefined;
+    const upstreamUsd = usageCount(asRecord(usage.cost_details)?.upstream_inference_cost);
+    return { usd, ...(upstreamUsd === undefined ? {} : { upstreamUsd }) };
+}
+function detailCounts(details, keys) {
+    const counts = Object.entries(keys).flatMap(([key, modality]) => {
+        const count = usageCount(details?.[key]);
+        return count === undefined ? [] : [[modality, count]];
+    });
+    return counts.length > 0 ? Object.fromEntries(counts) : undefined;
+}
+/**
+ * OpenRouter's per-modality detail counts, as reported (probed 23/09/2026):
+ * prompt `audio_tokens` / `video_tokens` (no image count, even for an image
+ * input) and completion `image_tokens` / `audio_tokens`.
+ */
+function modalityCounts(prompt, completion) {
+    const input = detailCounts(prompt, { audio_tokens: 'audio', video_tokens: 'video' });
+    const output = detailCounts(completion, { image_tokens: 'image', audio_tokens: 'audio' });
+    if (!input && !output)
+        return undefined;
+    return { ...(input ? { input } : {}), ...(output ? { output } : {}) };
+}
+/**
+ * Chat Completions reports `prompt_tokens` / `completion_tokens`, the Images API
+ * `input_tokens` / `output_tokens`. Both already mean what OpenTelemetry means:
+ * completion includes reasoning and prompt includes cached tokens.
+ */
+export function openAiUsageTokens(raw) {
+    const usage = asRecord(raw);
+    if (!usage)
+        return undefined;
+    const prompt = asRecord(usage.prompt_tokens_details) ?? asRecord(usage.input_tokens_details);
+    const completion = asRecord(usage.completion_tokens_details);
+    return reportedTokens({
+        input: usageCount(usage.prompt_tokens) ?? usageCount(usage.input_tokens),
+        output: usageCount(usage.completion_tokens) ?? usageCount(usage.output_tokens),
+        thinking: usageCount(completion?.reasoning_tokens),
+        cached: usageCount(prompt?.cached_tokens),
+        cacheWrite: usageCount(prompt?.cache_write_tokens),
+        cost: cost(usage),
+        byModality: modalityCounts(prompt, completion),
+    });
+}
+export function openAiResponse(raw) {
+    const id = nonEmptyString(raw.id);
+    const model = nonEmptyString(raw.model);
+    if (!id && !model)
+        return undefined;
+    return { ...(id ? { id } : {}), ...(model ? { model } : {}) };
+}

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

@@ -0,0 +1,8 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+import type { CacheSpec } from '../../kernel/types.js';
+/** What an `openRouter` binding sets in `options`. */
+export interface OpenRouterOptions {
+    cache?: CacheSpec;
+}
+/** Chat Completions with OpenRouter's caching, routing, web search, citations, and reasoning. */
+export declare const openRouter: Protocol<OpenRouterOptions>;

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

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { asRecord } from '../../kernel/engine/record.js';
+import { jsonObjectSchema } from '../../kernel/json.js';
+import { extendProtocol } from '../../kernel/protocols/mod.js';
+import { CACHE_MODES, CACHE_TTLS } from '../../kernel/schema.js';
+import { openAi } from '../open-ai/protocol.js';
+import { collectReasoning } from './openai/reasoning-state.js';
+// labels-exempt: builder field description, read by the studio and docs
+const cache = z
+    .strictObject({
+    mode: z
+        .enum(CACHE_MODES)
+        .describe('What is cached: the whole request (`automatic`) or the system instruction only (`system`).'),
+    ttl: z
+        .enum(CACHE_TTLS)
+        .optional()
+        .describe('How long the cache is kept. Absent: the upstream default.'),
+})
+    .describe('Prompt caching, for models that support it.');
+/** What OpenRouter's reasoning comes back as, to be sent back word for word. */
+const reasoning = z.strictObject({
+    details: z.array(jsonObjectSchema),
+    content: z.string().optional(),
+});
+function cacheControl(spec) {
+    return spec.ttl ? { type: 'ephemeral', ttl: spec.ttl } : { type: 'ephemeral' };
+}
+function callIds(message) {
+    const calls = asRecord(message)?.tool_calls;
+    return Array.isArray(calls) ? calls.map((call) => String(asRecord(call)?.id)) : [];
+}
+/** Puts the reasoning OpenRouter wrote back on the assistant message it came with, matched by its calls. */
+function replay(messages, history) {
+    for (const message of messages) {
+        const ids = callIds(message);
+        if (message.role !== 'assistant' || !ids.length)
+            continue;
+        const source = history.find((item) => item.role === 'assistant' &&
+            JSON.stringify((item.tool_calls ?? []).map((call) => call.id)) === JSON.stringify(ids));
+        const data = (source?.reasoning ?? [])
+            .map((item) => reasoning.safeParse(item.data))
+            .find((parsed) => parsed.success);
+        if (!data?.success)
+            continue;
+        message.reasoning_details = data.data.details;
+        if (data.data.content)
+            message.reasoning = data.data.content;
+    }
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+/** Where OpenRouter puts plain citation lists: the row, its metadata, and each choice. */
+function citedUris(row) {
+    const meta = (record) => [
+        record?.citations,
+        asRecord(record?.providerMetadata)?.citations,
+        asRecord(record?.provider_metadata)?.citations,
+    ];
+    const openrouter = asRecord(row.openrouter);
+    const choices = Array.isArray(row.choices) ? row.choices.map(asRecord) : [];
+    return [
+        ...meta(row),
+        ...meta(openrouter),
+        ...meta(asRecord(openrouter?.providerMetadata)),
+        ...meta(asRecord(openrouter?.provider_metadata)),
+        ...choices.flatMap((choice) => [
+            ...meta(asRecord(choice?.message)),
+            ...meta(asRecord(choice?.delta)),
+        ]),
+    ].flatMap(strings);
+}
+/** Annotations other than URL citations (which the base reads), from the row and its choices. */
+function otherAnnotations(row) {
+    const choices = Array.isArray(row.choices) ? row.choices.map(asRecord) : [];
+    const lists = [
+        row.annotations,
+        asRecord(row.openrouter)?.annotations,
+        ...choices.flatMap((choice) => [
+            asRecord(choice?.message)?.annotations,
+            asRecord(choice?.delta)?.annotations,
+        ]),
+    ];
+    return lists
+        .flatMap((list) => (Array.isArray(list) ? list : []))
+        .filter((item) => asRecord(item)?.type !== 'url_citation');
+}
+function thinking(row) {
+    const choices = Array.isArray(row.choices) ? row.choices : [];
+    return choices
+        .map((choice) => asRecord(asRecord(choice)?.delta)?.thinking)
+        .filter((text) => typeof text === 'string')
+        .join('');
+}
+/** Chat Completions with OpenRouter's caching, routing, web search, citations, and reasoning. */
+export const openRouter = extendProtocol(openAi, {
+    id: 'openRouter',
+    name: 'OpenRouter Chat Completions',
+    description: "Chat Completions with OpenRouter's caching, routing, web search, citations and reasoning.", // labels-exempt: builder field description, read by the studio and docs
+    options: z.strictObject({ cache: cache.optional() }),
+    reasoning,
+    body(body, at) {
+        // why: its fields are Chat Completions ones; a speech request goes as openAi sends it.
+        if (at.profileType !== 'text')
+            return { body };
+        const out = { ...body, provider: { require_parameters: true } };
+        if (out.reasoning_effort !== undefined) {
+            out.reasoning = { effort: out.reasoning_effort };
+            delete out.reasoning_effort;
+        }
+        const messages = Array.isArray(out.messages) ? out.messages : [];
+        const spec = at.options.cache;
+        if (spec?.mode === 'automatic')
+            out.cache_control = cacheControl(spec);
+        if (spec?.mode === 'system' && messages[0]?.role === 'system')
+            messages[0] = {
+                ...messages[0],
+                content: [
+                    { type: 'text', text: messages[0].content ?? '', cache_control: cacheControl(spec) },
+                ],
+            };
+        replay(messages, at.request?.history ?? []);
+        if (at.request?.sessionId)
+            out.session_id = at.request.sessionId;
+        const web = at.builtInTools.includes('webSearch');
+        if (web)
+            out.web_search_options = {};
+        return { body: { ...out, messages }, wroteTools: web ? ['webSearch'] : [] };
+    },
+    read(at) {
+        const details = new Map();
+        const cited = new Set();
+        const reported = new Set();
+        let content = '';
+        return {
+            row(row) {
+                content += collectReasoning(row, details);
+                const events = [];
+                const thought = thinking(row);
+                if (thought && at.request?.summaries !== 'none')
+                    events.push({ type: 'thought', text: thought });
+                const sources = citedUris(row)
+                    .filter((uri) => !cited.has(uri) && cited.add(uri))
+                    .map((uri) => ({ title: uri, uri, type: 'web' }));
+                if (sources.length)
+                    events.push({ type: 'citation', sources });
+                const annotations = otherAnnotations(row).filter((item) => {
+                    const key = JSON.stringify(item);
+                    return !reported.has(key) && reported.add(key);
+                });
+                if (annotations.length)
+                    events.push({
+                        type: 'evidence',
+                        evidence: {
+                            provider: 'openrouter',
+                            kind: 'provider_step',
+                            step: 'annotations',
+                            raw: { annotations },
+                        },
+                    });
+                return { events };
+            },
+            finish() {
+                if (!details.size && !content)
+                    return {};
+                const data = { details: [...details.values()], ...(content ? { content } : {}) };
+                return { events: [{ type: 'reasoning', data }] };
+            },
+        };
+    },
+});