@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/providers/open-ai/protocol.d.ts

@@ -0,0 +1,3 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** OpenAI Chat Completions: the shape most compatible servers speak. */
+export declare const openAi: Protocol<Record<string, never>>;

package/esm/src/providers/open-ai/protocol.js

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
+import { asRecord } from '../../kernel/engine/record.js';
+import { defineProtocol, } from '../../kernel/protocols/mod.js';
+import { turnStopFromOpenAiFinishReason } from '../../kernel/stop.js';
+import { base64ToBytes, bytesToBase64 } from '../../kernel/util/base64.js';
+import { mimeEssence } from '../../kernel/util/mime.js';
+import { buildChatMessages, resolveResponseFormat, wireTools, } from '../openrouter/openai/compat.js';
+import { openAiResponse, openAiUsageTokens } from '../openrouter/openai/usage.js';
+import { pcmFormatFromMime, wrapPcmAsWav } from '../shared/pcm.js';
+import { asProtocolEvent } from '../shared/protocol-events.js';
+import { foldResponse } from '../shared/response-identity.js';
+import { structuredEvent } from '../shared/structured-output.js';
+import { toolCallEvents } from '../shared/tool-args.js';
+import { toolDraftEvents } from '../shared/tool-draft.js';
+/** Old-shape events from the shared helpers, as protocol events. */
+function asProtocolEvents(events) {
+    return events.flatMap((event) => asProtocolEvent(event) ?? []);
+}
+function requestBody(context, request) {
+    const stream = request.stream !== false;
+    const tools = wireTools(request.wireTools);
+    const format = resolveResponseFormat(request.structured);
+    const body = {
+        model: context.apiId,
+        // why: replayed reasoning belongs to the protocol that wrote it, never to plain Chat Completions.
+        messages: buildChatMessages(request),
+        stream,
+        ...(stream ? { stream_options: { include_usage: true } } : {}),
+        ...(request.temperature === undefined ? {} : { temperature: request.temperature }),
+        ...(request.maxOutputTokens === undefined ? {} : { max_tokens: request.maxOutputTokens }),
+        ...(request.thinking ? { reasoning_effort: request.thinking } : {}),
+        ...(format ? { response_format: format } : {}),
+        // probed 2026-10-09: an empty `tools` list counts as a parameter the model must support, so OpenRouter refuses models without tool calling.
+        ...(tools ? { tools } : {}),
+    };
+    return JSON.parse(JSON.stringify(body));
+}
+/** An error row inside a 200 reply: thrown, so a quota refusal before any output can still fall back. */
+function errorRow(row) {
+    const error = asRecord(row.error);
+    if (!error)
+        return;
+    const status = typeof error.code === 'number' ? error.code : 502;
+    const message = typeof error.message === 'string' ? error.message : JSON.stringify(error);
+    throw new TheoremError(kindOfHttpStatus(status), message);
+}
+function citations(part, reply) {
+    const sources = (Array.isArray(part.annotations) ? part.annotations : []).flatMap((item) => {
+        const cited = asRecord(asRecord(item)?.url_citation);
+        if (typeof cited?.url !== 'string' || reply.cited.has(cited.url))
+            return [];
+        reply.cited.add(cited.url);
+        const title = typeof cited.title === 'string' && cited.title ? cited.title : cited.url;
+        return [{ title, uri: cited.url, type: 'web' }];
+    });
+    return sources.length ? [{ type: 'citation', sources }] : [];
+}
+function mergeCalls(part, reply) {
+    for (const [position, value] of (Array.isArray(part.tool_calls)
+        ? part.tool_calls
+        : []).entries()) {
+        const call = asRecord(value);
+        const fn = asRecord(call?.function);
+        const index = typeof call?.index === 'number' ? call.index : position;
+        const current = reply.calls.get(index) ?? { name: '', args: '' };
+        if (typeof call?.id === 'string' && call.id)
+            current.id = call.id;
+        if (typeof fn?.name === 'string')
+            current.name += fn.name;
+        if (typeof fn?.arguments === 'string')
+            current.args += fn.arguments;
+        reply.calls.set(index, current);
+    }
+}
+/** One choice's delta (streamed) or message (whole). */
+function partEvents(part, reply, request) {
+    const events = [];
+    const thought = part.reasoning ?? part.reasoning_content;
+    if (typeof thought === 'string' && thought && request.summaries !== 'none')
+        events.push({ type: 'thought', text: thought });
+    if (typeof part.content === 'string' && part.content) {
+        reply.text += part.content;
+        events.push({ type: 'text', text: part.content });
+    }
+    events.push(...citations(part, reply));
+    mergeCalls(part, reply);
+    return events;
+}
+function rowEvents(row, reply, request, stream) {
+    errorRow(row);
+    const events = [];
+    const identity = foldResponse(reply.response, openAiResponse(row));
+    reply.response = identity.known;
+    if (identity.event)
+        events.push(identity.event);
+    const tokens = reply.tokens ? undefined : openAiUsageTokens(row.usage);
+    if (tokens) {
+        reply.tokens = true;
+        events.push({ type: 'tokens', tokens });
+    }
+    for (const item of Array.isArray(row.choices) ? row.choices : []) {
+        const choice = asRecord(item);
+        const part = asRecord(stream ? choice?.delta : choice?.message);
+        if (part)
+            events.push(...partEvents(part, reply, request));
+        if (typeof choice?.finish_reason === 'string')
+            reply.finish = choice.finish_reason;
+        // why: gateways add the upstream's own reason beside it; it tells a provider failure from a stop.
+        if (typeof choice?.native_finish_reason === 'string')
+            reply.native = choice.native_finish_reason;
+    }
+    // why: a whole reply carries each call complete; only a streamed one has a draft to show.
+    if (stream)
+        for (const call of reply.calls.values())
+            events.push(...asProtocolEvents(toolDraftEvents(call)));
+    return events;
+}
+/** The calls, the structured reply, and the stop, once the rows are done. */
+function endEvents(reply, request) {
+    const events = [];
+    // why: some compatible servers end a tool-calling reply with `stop`, so the calls go out whatever the finish.
+    for (const [index, call] of reply.calls)
+        events.push(...asProtocolEvents(toolCallEvents({ ...call, id: call.id ?? `call_${index}` }, call.args)));
+    const stop = turnStopFromOpenAiFinishReason(reply.finish, reply.native);
+    if (request.structured && reply.text && stop.kind === 'completed') {
+        const structured = asProtocolEvents([structuredEvent(reply.text)]);
+        events.push(...structured);
+        if (structured[0]?.type === 'error')
+            return events;
+    }
+    events.push({ type: 'done', stop });
+    return events;
+}
+/** `/audio/speech`: the input's text read aloud, answered whole. Raw PCM with a stated rate becomes WAV. */
+async function* speech(context, request) {
+    const text = request.input
+        .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+        .join(' ')
+        .trim();
+    if (!text)
+        throw new TheoremError('request', 'empty text for speech');
+    const spec = request.speech;
+    const body = {
+        model: context.apiId,
+        input: text,
+        ...(spec?.format ? { response_format: spec.format } : {}),
+        ...(spec?.voice ? { voice: spec.voice } : {}),
+        ...(spec?.speed === undefined ? {} : { speed: spec.speed }),
+        // why: `instructions` is the endpoint's own field for delivery, never read aloud (probe 07/10/2026: Gemini 3.8 slowed and sped by it).
+        ...(spec?.style ? { instructions: spec.style } : {}),
+    };
+    for await (const row of context.send(body, { stream: false })) {
+        const type = typeof row.mime_type === 'string' ? row.mime_type : '';
+        const bytes = typeof row.data === 'string' ? base64ToBytes(row.data) : new Uint8Array();
+        if (!bytes.length)
+            throw new TheoremError('bad_response', 'no audio returned from speech');
+        const pcm = pcmFormatFromMime(type);
+        const media = pcm
+            ? { mimeType: 'audio/wav', data: bytesToBase64(wrapPcmAsWav(bytes, pcm)) }
+            : { mimeType: mimeEssence(type) || 'application/octet-stream', data: row.data };
+        yield { type: 'media', media };
+        // why: the endpoint answers whole or not at all: a body with audio completed.
+        yield { type: 'done', stop: { kind: 'completed' } };
+    }
+}
+/** OpenAI Chat Completions: the shape most compatible servers speak. */
+export const openAi = defineProtocol({
+    id: 'openAi',
+    name: 'OpenAI Chat Completions',
+    description: 'The Chat Completions shape that OpenAI and most compatible servers speak.', // labels-exempt: builder field description, read by the studio and docs
+    endpoints: { text: '/chat/completions', speech: '/audio/speech' },
+    options: z.strictObject({}),
+    create(context) {
+        return {
+            async *complete(request) {
+                if (context.profileType === 'speech') {
+                    yield* speech(context, request);
+                    return;
+                }
+                const stream = request.stream !== false;
+                const reply = { text: '', tokens: false, cited: new Set(), calls: new Map() };
+                for await (const row of context.send(requestBody(context, request), { stream }))
+                    yield* rowEvents(row, reply, request, stream);
+                yield* endEvents(reply, request);
+            },
+        };
+    },
+});

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

@@ -0,0 +1,6 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** What an `openRouterEmbedding` binding sets in `options`. */
+export interface OpenRouterEmbeddingOptions {
+    encodingFormat?: 'float' | 'base64';
+}
+export declare const openRouterEmbedding: Protocol<OpenRouterEmbeddingOptions>;

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

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { defineProtocol, } from '../../kernel/protocols/mod.js';
+import { base64ToBytes } from '../../kernel/util/base64.js';
+const options = z.strictObject({
+    encodingFormat: z
+        .enum(['float', 'base64'])
+        .optional()
+        .describe('How OpenRouter sends each vector back: as a list of numbers (`float`) or packed into a base64 string (`base64`, smaller on the wire). Theorem decodes both to the same numbers. Absent: `float`.'),
+});
+// why: OpenRouter's embeddings reference takes images only and caps neither inputs nor images per input; a text-only model refuses an image itself.
+const LIMITS = { media: [{ accept: ['image/*'] }] };
+/** A string stays a string; a multimodal input is one `{ content }` item, as OpenRouter documents. */
+function inputValue(input) {
+    if (typeof input === 'string')
+        return input;
+    return {
+        content: input.parts.map((part) => {
+            if (part.type === 'text')
+                return { type: 'text', text: part.text };
+            const url = part.type === 'media' ? `data:${part.mimeType};base64,${part.data}` : part.uri;
+            return { type: 'image_url', image_url: { url } };
+        }),
+    };
+}
+function embeddingValues(value) {
+    if (Array.isArray(value)) {
+        if (!value.every((entry) => typeof entry === 'number' && Number.isFinite(entry))) {
+            throw new Error('OpenRouter returned an embedding with a non-finite value');
+        }
+        return value;
+    }
+    if (typeof value !== 'string') {
+        throw new Error('OpenRouter returned an embedding in an unsupported format');
+    }
+    const bytes = base64ToBytes(value);
+    if (bytes.byteLength % Float32Array.BYTES_PER_ELEMENT !== 0) {
+        throw new Error('OpenRouter returned an invalid base64 embedding length');
+    }
+    return Array.from(new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / Float32Array.BYTES_PER_ELEMENT));
+}
+export const openRouterEmbedding = defineProtocol({
+    id: 'openRouterEmbedding',
+    name: 'OpenRouter Embeddings',
+    description: 'OpenRouter embedding models, including supported multimodal models.',
+    endpoints: { embedding: '/embeddings' },
+    options,
+    embeddingLimits: () => LIMITS,
+    create(context) {
+        return {
+            async embed(request) {
+                const parsed = options.parse(request.options ?? {});
+                const inputs = Array.isArray(request.input) ? request.input : [request.input];
+                const body = {
+                    model: context.apiId,
+                    input: inputs.length === 1 && typeof inputs[0] === 'string'
+                        ? inputs[0]
+                        : inputs.map(inputValue),
+                };
+                if (parsed.encodingFormat)
+                    body.encoding_format = parsed.encodingFormat;
+                let row;
+                for await (const current of context.send(body, { stream: false }))
+                    row = current;
+                const data = Array.isArray(row?.data) ? row.data : [];
+                const usage = row?.usage && typeof row.usage === 'object'
+                    ? row.usage
+                    : undefined;
+                return {
+                    model: typeof row?.model === 'string' ? row.model : context.apiId,
+                    embeddings: data.map((item, position) => {
+                        const record = item && typeof item === 'object' ? item : {};
+                        const values = embeddingValues(record.embedding);
+                        return {
+                            index: typeof record.index === 'number' ? record.index : position,
+                            values,
+                            dimensions: values.length,
+                        };
+                    }),
+                    ...(typeof usage?.prompt_tokens === 'number'
+                        ? { usage: { inputTokens: usage.prompt_tokens } }
+                        : {}),
+                };
+            },
+        };
+    },
+});

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

@@ -1,8 +1,4 @@
-import type { ModelProvider, ProviderCompleteRequest, ProviderEvent } from '../../kernel/types.js';
-import type { OpenAiGatewayTransport } from '../types.js';
 export declare const OPENROUTER_IMAGE_TOOL = "openrouter:image_generation";
-export type ImageProviderConfig = OpenAiGatewayTransport;
-export declare function buildImageHeaders(apiKey: string, config: ImageProviderConfig): Record<string, string>;
 /** `/images` answers `data[]` of `b64_json` + `media_type` (probe 23/09/2026, bytedance-seed/seedream-4.5). */
 export declare function imagesFromImagesBody(body: Record<string, unknown>): {
     mimeType: string;
@@ -17,8 +13,3 @@ export declare function imagesFromChatMessage(message: Record<string, unknown>):
     mimeType: string;
     data: string;
 }[];
-export declare function buildInterleavedChatPayload(req: ProviderCompleteRequest): Record<string, unknown>;
-export declare function yieldInterleavedChat(req: ProviderCompleteRequest, config: ImageProviderConfig, apiKey: string): AsyncGenerator<ProviderEvent>;
-export declare function yieldImagesEndpoint(req: ProviderCompleteRequest, config: ImageProviderConfig, apiKey: string): AsyncGenerator<ProviderEvent>;
-export declare function streamImage(req: ProviderCompleteRequest, config?: ImageProviderConfig): AsyncGenerator<ProviderEvent>;
-export declare function createImageProvider(config?: ImageProviderConfig): ModelProvider;

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

@@ -1,35 +1,5 @@
-import { TheoremError, toErrorEvent } from '../../guardrails/error.js';
 import { asRecord, nonEmptyString } from '../../kernel/engine/record.js';
-import { turnStopFromOpenAiFinishReason } from '../../kernel/stop.js';
-import { networkFetch } from '../shared/upstream-tap.js';
-import { bearerFetch } from '../shared/vault.js';
-import { buildChatMessages, httpErrorEvent, openAiGatewayHeaders } from './openai/compat.js';
-import { buildImagesPayload, extractPromptText, imageToolParameters, } from './openai/image-payload.js';
-import { openAiUsageTokens } from './openai/usage.js';
-import { resolveOpenAiGatewayApiKey } from './resolve-api-key.js';
-const HTTP_OK = 200;
 export const OPENROUTER_IMAGE_TOOL = 'openrouter:image_generation';
-export function buildImageHeaders(apiKey, config) {
-    const headers = {
-        Authorization: `Bearer ${apiKey}`,
-        'Content-Type': 'application/json',
-    };
-    const gateway = openAiGatewayHeaders(config);
-    if (gateway) {
-        Object.assign(headers, gateway);
-    }
-    return headers;
-}
-function baseUrl(config) {
-    return config.baseUrl?.replace(/\/+$/, '') ?? 'https://openrouter.ai/api/v1';
-}
-function* yieldUsage(raw) {
-    const tokens = openAiUsageTokens(raw);
-    if (!tokens) {
-        return;
-    }
-    yield { type: 'tokens', tokens };
-}
 /** `/images` answers `data[]` of `b64_json` + `media_type` (probe 23/09/2026, bytedance-seed/seedream-4.5). */
 export function imagesFromImagesBody(body) {
     const entries = Array.isArray(body.data) ? body.data : [];
@@ -62,126 +32,3 @@ export function imagesFromChatMessage(message) {
         return media ? [media] : [];
     });
 }
-async function postJson(req, config, apiKey, path, body) {
-    const fetchFn = bearerFetch(req, networkFetch(config.fetch ?? fetch), config.vault, apiKey);
-    return await fetchFn(`${baseUrl(config)}${path}`, {
-        method: 'POST',
-        headers: buildImageHeaders(apiKey, config),
-        body: JSON.stringify(body),
-        signal: req.signal,
-    });
-}
-async function readTapedJson(req, res) {
-    const body = (await res.json());
-    req.tapUpstream?.(body);
-    return body;
-}
-async function requestImages(req, config, apiKey) {
-    return await postJson(req, config, apiKey, '/images', buildImagesPayload(req));
-}
-export function buildInterleavedChatPayload(req) {
-    if (!req.image) {
-        throw new Error('buildInterleavedChatPayload requires req.image');
-    }
-    return {
-        model: req.apiId,
-        stream: false,
-        messages: buildChatMessages(req),
-        temperature: req.temperature,
-        max_tokens: req.maxOutputTokens,
-        ...(req.thinking ? { reasoning: { effort: req.thinking } } : {}),
-        tools: [
-            {
-                type: OPENROUTER_IMAGE_TOOL,
-                parameters: imageToolParameters(req.image),
-            },
-        ],
-    };
-}
-async function requestInterleavedChat(req, config, apiKey) {
-    return await postJson(req, config, apiKey, '/chat/completions', buildInterleavedChatPayload(req));
-}
-export async function* yieldInterleavedChat(req, config, apiKey) {
-    const res = await requestInterleavedChat(req, config, apiKey);
-    if (res.status !== HTTP_OK) {
-        yield await httpErrorEvent(res, 'Image chat');
-        return;
-    }
-    const body = await readTapedJson(req, res);
-    const choices = body.choices;
-    if (!Array.isArray(choices) || choices.length === 0) {
-        yield toErrorEvent(new TheoremError('bad_response', 'no chat choices returned for image generation'));
-        return;
-    }
-    const choice = asRecord(choices[0]);
-    const message = asRecord(choice?.message);
-    if (!message) {
-        yield toErrorEvent(new TheoremError('bad_response', 'no assistant message returned for image generation'));
-        return;
-    }
-    const text = nonEmptyString(message.content);
-    if (text) {
-        yield { type: 'text', text };
-    }
-    const images = imagesFromChatMessage(message);
-    if (images.length === 0) {
-        yield toErrorEvent(new TheoremError('bad_response', 'no image returned from chat image generation'));
-        return;
-    }
-    for (const media of images) {
-        yield { type: 'media', media };
-    }
-    yield* yieldUsage(body.usage);
-    yield {
-        type: 'done',
-        stop: turnStopFromOpenAiFinishReason(typeof choice?.finish_reason === 'string' ? choice.finish_reason : undefined, typeof choice?.native_finish_reason === 'string' ? choice.native_finish_reason : undefined),
-    };
-}
-export async function* yieldImagesEndpoint(req, config, apiKey) {
-    const res = await requestImages(req, config, apiKey);
-    if (res.status !== HTTP_OK) {
-        yield await httpErrorEvent(res, 'Image');
-        return;
-    }
-    const body = await readTapedJson(req, res);
-    const images = imagesFromImagesBody(body);
-    if (images.length === 0) {
-        yield toErrorEvent(new TheoremError('bad_response', 'no image returned from image generation'));
-        return;
-    }
-    for (const media of images) {
-        yield { type: 'media', media };
-    }
-    yield* yieldUsage(body.usage);
-    // The endpoint answers whole or not at all: a body with images completed.
-    yield { type: 'done', stop: { kind: 'completed' } };
-}
-export async function* streamImage(req, config = {}) {
-    let apiKey;
-    try {
-        apiKey = resolveOpenAiGatewayApiKey(config, req.keySlot);
-    }
-    catch (err) {
-        yield toErrorEvent(err);
-        return;
-    }
-    if (!req.image) {
-        yield toErrorEvent(new TheoremError('request', 'missing image response format'));
-        return;
-    }
-    const prompt = extractPromptText(req.input);
-    if (!prompt) {
-        yield toErrorEvent(new TheoremError('request', 'empty text for image generation'));
-        return;
-    }
-    if (req.image.includeText) {
-        yield* yieldInterleavedChat(req, config, apiKey);
-        return;
-    }
-    yield* yieldImagesEndpoint(req, config, apiKey);
-}
-export function createImageProvider(config = {}) {
-    return {
-        complete: (req) => streamImage(req, config),
-    };
-}

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

@@ -0,0 +1,3 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** OpenRouter's image generation: `/images`, or the chat path with its image tool when text is wanted too. */
+export declare const openRouterImages: Protocol<Record<string, never>>;

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

@@ -1,5 +1,5 @@
 import { type ProducedError } from '../../../guardrails/error.js';
-import type { InteractionPart, ProviderCompleteRequest, ResolvedStructured, WireFunctionTool } from '../../../kernel/types.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 {
@@ -9,7 +9,7 @@ interface GatewayHeaderConfig {
 /** 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: ProviderCompleteRequest, options?: {
+declare function buildChatMessages(req: Pick<ModelRequest, 'system' | 'history' | 'input'>, options?: {
     includeSystem?: boolean;
 }): Record<string, unknown>[];
 declare function wireTools(wireTools?: WireFunctionTool[]): Record<string, unknown>[] | undefined;

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

@@ -1,6 +1,7 @@
 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) {
@@ -12,7 +13,7 @@ async function httpErrorEvent(res, label) {
             detail = message;
     }
     catch {
-        // Not JSON: the raw body is the detail.
+        // 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));
@@ -63,7 +64,6 @@ export function wireMessageContent(parts) {
         if (part.type === 'audio') {
             return wireAudioPart(part);
         }
-        // video and document ride as a `file` part.
         return {
             type: 'file',
             file: {
@@ -99,6 +99,8 @@ function wireHistoryMessage(msg) {
     }
     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;
@@ -106,10 +108,8 @@ function buildChatMessages(req, options) {
     if (includeSystem && req.system) {
         messages.push({ role: 'system', content: req.system });
     }
-    if (req.history && req.history.length > 0) {
-        for (const h of req.history) {
-            messages.push(wireHistoryMessage(h));
-        }
+    for (const h of withCarriedToolFiles(req.history ?? [], TOOL_MESSAGE_PART_TYPES)) {
+        messages.push(wireHistoryMessage(h));
     }
     if (req.input.length > 0) {
         messages.push({

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

@@ -1,9 +1,9 @@
-import type { ImageResponseFormat, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, ProviderCompleteRequest } from '../../../kernel/types.js';
+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: ProviderCompleteRequest): Record<string, unknown>;
+export declare function buildImagesPayload(req: ModelRequest): Record<string, unknown>;
 export declare function imageToolParameters(image: ImageResponseFormat): Record<string, unknown>;

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;