@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/providers/google/urls.js

@@ -0,0 +1,4 @@
+/** The models a key's project can call; paged with `pageToken`. */
+const GEMINI_MODELS_URL = 'https://generativelanguage.googleapis.com/v1beta/models';
+const GEMINI_LIVE_WS_URL = 'wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent';
+export { GEMINI_LIVE_WS_URL, GEMINI_MODELS_URL };

package/esm/src/providers/google/usage.d.ts

@@ -0,0 +1,7 @@
+import type { TurnGroundingCount } from '../../kernel/types.js';
+export declare function modalityCounts(raw: unknown, countKey: 'tokens' | 'tokenCount'): Record<string, number> | undefined;
+export declare function byModality(input: Record<string, number> | undefined, output: Record<string, number> | undefined): {
+    input?: Record<string, number>;
+    output?: Record<string, number>;
+} | undefined;
+export declare function groundingCounts(raw: unknown): TurnGroundingCount[] | undefined;

package/esm/src/providers/google/usage.js

@@ -0,0 +1,49 @@
+/* probed 2026-09-23:
+ * Google usage lists, in the spellings the wire sends:
+ *
+ * - Interactions: `input_tokens_by_modality` / `output_tokens_by_modality`,
+ *   `[{ modality: 'text', tokens }]`; `grounding_tool_count`,
+ *   `[{ type, count, search_query_count }]`.
+ * - Live: `promptTokensDetails` / `responseTokensDetails`,
+ *   `[{ modality: 'TEXT', tokenCount }]`.
+ *
+ * Both list only some modalities (Live listed 126 text of 144 prompt tokens;
+ * an image reply listed 1,120 image of 1,378 output tokens), so the shares
+ * are kept as reported and never filled to the total.
+ */
+import { asRecord } from '../../kernel/engine/record.js';
+import { usageCount } from '../../kernel/engine/usage.js';
+export function modalityCounts(raw, countKey) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const counts = {};
+    for (const entry of raw) {
+        const rec = asRecord(entry);
+        const count = usageCount(rec?.[countKey]);
+        if (typeof rec?.modality === 'string' && count !== undefined) {
+            const modality = rec.modality.toLowerCase();
+            counts[modality] = (counts[modality] ?? 0) + count;
+        }
+    }
+    return Object.keys(counts).length > 0 ? counts : undefined;
+}
+export function byModality(input, output) {
+    if (!input && !output)
+        return undefined;
+    return { ...(input ? { input } : {}), ...(output ? { output } : {}) };
+}
+export function groundingCounts(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const counts = raw.flatMap((entry) => {
+        const rec = asRecord(entry);
+        const count = usageCount(rec?.count);
+        if (typeof rec?.type !== 'string' || count === undefined)
+            return [];
+        const queries = usageCount(rec.search_query_count);
+        return [
+            { type: rec.type, count, ...(queries === undefined ? {} : { searchQueryCount: queries }) },
+        ];
+    });
+    return counts.length > 0 ? counts : undefined;
+}

package/esm/src/providers/live.d.ts

@@ -0,0 +1,6 @@
+/** Provider-neutral live tracing and tool read-back helpers.
+ * @module
+ */
+import type { TurnHistoryMessage } from '../kernel/types.js';
+export declare function liveSentInput(row: Record<string, unknown>): TurnHistoryMessage[];
+export declare function liveToolReadBack(output: unknown): string;

package/esm/src/providers/live.js

@@ -0,0 +1,6 @@
+export function liveSentInput(row) {
+    return Array.isArray(row.input) ? row.input : [];
+}
+export function liveToolReadBack(output) {
+    return typeof output === 'string' ? output : JSON.stringify(output);
+}

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

@@ -0,0 +1,7 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** What an `ollamaEmbedding` binding sets in `options`. */
+export interface OllamaEmbeddingOptions {
+    truncate?: boolean;
+    dimensions?: number;
+}
+export declare const ollamaEmbedding: Protocol<OllamaEmbeddingOptions>;

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

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { defineProtocol } from '../../kernel/protocols/mod.js';
+const options = z.strictObject({
+    truncate: z
+        .boolean()
+        .optional()
+        .describe('What happens to an input longer than the model reads. On, it is cut to fit; off, the call fails. Absent: Ollama cuts it.'),
+    dimensions: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('How many numbers each vector holds, for models that can shorten theirs. Absent: the length the model returns.'),
+});
+function strings(input) {
+    const values = Array.isArray(input) ? input : [input];
+    return values.map((item) => {
+        if (typeof item === 'string')
+            return item;
+        if (item.parts.length !== 1 || item.parts[0]?.type !== 'text')
+            throw new TheoremError('unsupported', 'The Ollama embedding protocol accepts text only');
+        return item.parts[0].text;
+    });
+}
+export const ollamaEmbedding = defineProtocol({
+    id: 'ollamaEmbedding',
+    name: 'Ollama Embeddings',
+    description: 'Ollama’s local embedding endpoint.',
+    endpoints: { embedding: '/api/embed' },
+    options,
+    embeddingLimits: () => ({ media: [] }),
+    create(context) {
+        return {
+            async embed(request) {
+                const parsed = options.parse(request.options ?? {});
+                const rows = context.send({
+                    model: context.apiId,
+                    input: strings(request.input),
+                    ...(parsed.truncate === undefined ? {} : { truncate: parsed.truncate }),
+                    ...(parsed.dimensions === undefined ? {} : { dimensions: parsed.dimensions }),
+                }, { stream: false });
+                let row;
+                for await (const current of rows)
+                    row = current;
+                const embeddings = Array.isArray(row?.embeddings) ? row.embeddings : [];
+                return {
+                    model: typeof row?.model === 'string' ? row.model : context.apiId,
+                    embeddings: embeddings.map((values, index) => ({
+                        index,
+                        values: Array.isArray(values)
+                            ? values.filter((value) => typeof value === 'number')
+                            : [],
+                        dimensions: Array.isArray(values) ? values.length : 0,
+                    })),
+                };
+            },
+        };
+    },
+});

package/esm/src/providers/local/provider.d.ts

@@ -0,0 +1,7 @@
+import { type Provider } from '../../kernel/protocols/provider.js';
+/** What registering `localProvider` takes as `connection`. */
+export interface LocalConnection {
+    baseUrl: string;
+}
+/** A server on your machine or network that speaks OpenAI's chat API: Ollama, llama.cpp, vLLM, LM Studio. */
+export declare const localProvider: Provider<LocalConnection, string>;

package/esm/src/providers/local/provider.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { bearer, defineProvider, endpointUrlSchema, } from '../../kernel/protocols/provider.js';
+import { openAi } from '../open-ai/protocol.js';
+import { ollamaEmbedding } from './embedding-protocol.js';
+/** A server on your machine or network that speaks OpenAI's chat API: Ollama, llama.cpp, vLLM, LM Studio. */
+export const localProvider = defineProvider({
+    id: 'local',
+    name: 'Local',
+    description: "A server that speaks OpenAI's chat API: Ollama, llama.cpp, vLLM, LM Studio.", // labels-exempt: builder field description, read by the studio and docs
+    traceName: 'openai',
+    connection: z.strictObject({
+        baseUrl: endpointUrlSchema.describe('Where the server listens, up to and including /v1, e.g. http://localhost:11434/v1.'),
+    }),
+    key: z.string().trim().min(1).optional(),
+    authorize: bearer(),
+    serves: (at) => [
+        { protocol: openAi, baseUrl: at.baseUrl },
+        {
+            protocol: ollamaEmbedding,
+            baseUrl: at.baseUrl,
+            url: ({ path }) => {
+                const base = new URL(at.baseUrl);
+                base.pathname = base.pathname.replace(/\/v1\/?$/, '') || '/';
+                return new URL(path.replace(/^\/+/, ''), base).toString();
+            },
+        },
+    ],
+});

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

@@ -0,0 +1,32 @@
+/**
+ * Protocols, providers, and what it takes to define either: a protocol owns the wire, a provider is
+ * where a service is and how to sign in to it.
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { ProviderCheckpoint, ProviderContinuationPolicy, ProviderWarning, } from '../kernel/checkpoint.js';
+export type { JsonObject, JsonValue } from '../kernel/json.js';
+export { jsonObjectSchema, jsonValueSchema } from '../kernel/json.js';
+export type { DecisionModelBinding, ModelBinding } from '../kernel/protocols/binding.js';
+export type { ProviderLimits } from '../kernel/protocols/limits.js';
+export type { ModelPrice, PriceTable, Rates } from '../kernel/protocols/prices.js';
+export type { Continuation, DecisionCall, EmbeddingCall, EmbeddingMediaKind, EmbeddingModelLimits, ExtensionBodyAt, ExtensionReader, LiveToolResult, ModelProfileType, Protocol, ProtocolContentEvent, ProtocolContext, ProtocolDefinition, ProtocolEvent, ProtocolExtension, ProtocolOperations, ProtocolRequest, ProtocolSession, ProtocolSocket, SendInit, UpstreamFailure, } from '../kernel/protocols/protocol.js';
+export { carriesTo, defineProtocol, extendProtocol, modelOptions, } from '../kernel/protocols/protocol.js';
+export type { Authorize, Outgoing, Provider, ProviderDefinition, ProviderRegistry, RegisteredProvider, Registration, Serve, Signer, } from '../kernel/protocols/provider.js';
+export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from '../kernel/protocols/provider.js';
+export type { OpenWebSocket, ProviderHostOptions } from '../kernel/protocols/runtime.js';
+export type { CredentialContext, CredentialResolver, KeyCredential, KeyVault, } from '../kernel/registry/vault.js';
+export { embeddingModelLimits } from './embedding-limits.js';
+export { geminiEmbedding } from './gemini/embedding-protocol.js';
+export { geminiInteractions } from './gemini/interactions-protocol.js';
+export { geminiLive } from './gemini/live-protocol.js';
+export { geminiProvider } from './gemini/provider.js';
+export { ollamaEmbedding } from './local/embedding-protocol.js';
+export { localProvider } from './local/provider.js';
+export { openAi } from './open-ai/protocol.js';
+export { openRouterEmbedding } from './openrouter/embedding-protocol.js';
+export { openRouterImages } from './openrouter/images-protocol.js';
+export { openRouter } from './openrouter/protocol.js';
+export { openRouterProvider } from './openrouter/provider.js';
+export { systemOne } from './system-one/protocol.js';
+export { typesafeProvider } from './typesafe/provider.js';

package/esm/src/providers/mod.js

@@ -0,0 +1,23 @@
+/**
+ * Protocols, providers, and what it takes to define either: a protocol owns the wire, a provider is
+ * where a service is and how to sign in to it.
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { jsonObjectSchema, jsonValueSchema } from '../kernel/json.js';
+export { carriesTo, defineProtocol, extendProtocol, modelOptions, } from '../kernel/protocols/protocol.js';
+export { bearer, createProviderRegistry, defineProvider, endpointUrlSchema, header, query, } from '../kernel/protocols/provider.js';
+export { embeddingModelLimits } from './embedding-limits.js';
+export { geminiEmbedding } from './gemini/embedding-protocol.js';
+export { geminiInteractions } from './gemini/interactions-protocol.js';
+export { geminiLive } from './gemini/live-protocol.js';
+export { geminiProvider } from './gemini/provider.js';
+export { ollamaEmbedding } from './local/embedding-protocol.js';
+export { localProvider } from './local/provider.js';
+export { openAi } from './open-ai/protocol.js';
+export { openRouterEmbedding } from './openrouter/embedding-protocol.js';
+export { openRouterImages } from './openrouter/images-protocol.js';
+export { openRouter } from './openrouter/protocol.js';
+export { openRouterProvider } from './openrouter/provider.js';
+export { systemOne } from './system-one/protocol.js';
+export { typesafeProvider } from './typesafe/provider.js';

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

@@ -0,0 +1,15 @@
+export declare const OPENROUTER_IMAGE_TOOL = "openrouter:image_generation";
+/** `/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;
+    data: string;
+}[];
+/**
+ * OpenRouter returns chat images on `message.images[]` as `{ type: 'image_url', image_url: { url } }`
+ * with a base64 data url; `message.content` holds only the text (probe 23/09/2026,
+ * gemini-3.1-flash-lite with the image generation tool).
+ */
+export declare function imagesFromChatMessage(message: Record<string, unknown>): {
+    mimeType: string;
+    data: string;
+}[];

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

@@ -0,0 +1,34 @@
+import { asRecord, nonEmptyString } from '../../kernel/engine/record.js';
+export const OPENROUTER_IMAGE_TOOL = 'openrouter:image_generation';
+/** `/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 : [];
+    return entries.flatMap((value) => {
+        const entry = asRecord(value);
+        const data = nonEmptyString(entry?.b64_json);
+        const mimeType = nonEmptyString(entry?.media_type);
+        return data && mimeType ? [{ mimeType, data }] : [];
+    });
+}
+function mediaFromDataUrl(url) {
+    if (typeof url !== 'string') {
+        return undefined;
+    }
+    const match = /^data:([^;,]+);base64,(.+)$/s.exec(url);
+    if (!match?.[1] || !match[2]) {
+        return undefined;
+    }
+    return { mimeType: match[1], data: match[2] };
+}
+/**
+ * OpenRouter returns chat images on `message.images[]` as `{ type: 'image_url', image_url: { url } }`
+ * with a base64 data url; `message.content` holds only the text (probe 23/09/2026,
+ * gemini-3.1-flash-lite with the image generation tool).
+ */
+export function imagesFromChatMessage(message) {
+    const images = Array.isArray(message.images) ? message.images : [];
+    return images.flatMap((entry) => {
+        const media = mediaFromDataUrl(asRecord(asRecord(entry)?.image_url)?.url);
+        return media ? [media] : [];
+    });
+}

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>>;