@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,19 @@
+import { type ProducedError } from '../../../guardrails/error.js';
+import type { InteractionPart, ProviderCompleteRequest, 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: ProviderCompleteRequest, 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 { 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 {
+        // 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);
+        }
+        // video and document ride as a `file` 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;
+}
+/** `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 });
+    }
+    if (req.history && req.history.length > 0) {
+        for (const h of req.history) {
+            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, ProviderCompleteRequest } 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 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/sdk-messages.d.ts

@@ -0,0 +1,10 @@
+import type { ModelMessage } from 'ai';
+import type { InteractionPart, ProviderCompleteRequest, TurnHistoryMessage } from '../../../kernel/types.js';
+export declare function sdkPart(input: InteractionPart): Record<string, unknown>;
+export declare function sdkContentFromParts(parts: InteractionPart[]): string | Array<Record<string, unknown>>;
+export declare function toolResultMessage(msg: TurnHistoryMessage): ModelMessage;
+export declare function assistantToolCallMessage(msg: TurnHistoryMessage): ModelMessage | null;
+export declare function contentHistoryMessage(msg: TurnHistoryMessage): ModelMessage;
+export declare function historyToSdk(msg: TurnHistoryMessage): ModelMessage | null;
+/** Leaves `req.system` to the caller (`systemDelivery` in chat.ts). */
+export declare function buildAiSdkMessages(req: ProviderCompleteRequest): ModelMessage[];

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

@@ -0,0 +1,99 @@
+import { TheoremError } from '../../../guardrails/error.js';
+import { historyMessageParts, isMediaRefPart } from '../../../kernel/interaction-parts.js';
+import { historyToolArguments, historyToolIdentity } from '../../shared/tool-args.js';
+function inlineMediaPart(part) {
+    if (isMediaRefPart(part)) {
+        throw new TheoremError('unsupported', 'media references are not supported on openAi');
+    }
+    return part;
+}
+export function sdkPart(input) {
+    if (input.type === 'text') {
+        return { type: 'text', text: input.text };
+    }
+    const part = inlineMediaPart(input);
+    return { type: 'file', mediaType: part.mimeType, data: part.data };
+}
+export function sdkContentFromParts(parts) {
+    if (parts.every((part) => part.type === 'text')) {
+        return parts
+            .map((part) => (part.type === 'text' ? part.text : ''))
+            .filter(Boolean)
+            .join('\n');
+    }
+    return parts.map(sdkPart);
+}
+export function toolResultMessage(msg) {
+    const parts = historyMessageParts(msg);
+    const content = sdkContentFromParts(parts);
+    const output = typeof content === 'string'
+        ? { type: 'text', value: content }
+        : {
+            type: 'content',
+            value: parts.map((input) => {
+                if (input.type === 'text') {
+                    return { type: 'text', text: input.text };
+                }
+                const part = inlineMediaPart(input);
+                return {
+                    type: 'file',
+                    mediaType: part.mimeType,
+                    data: { type: 'data', data: part.data },
+                };
+            }),
+        };
+    // AI SDK ToolModelMessage is a branded union; structural tool-result is correct at runtime.
+    return {
+        role: 'tool',
+        content: [
+            {
+                type: 'tool-result',
+                // The AI SDK rejects a missing id or name (`AI_InvalidPromptError`).
+                ...historyToolIdentity({ toolCallId: msg.tool_call_id, toolName: msg.name }),
+                output,
+            },
+        ],
+    };
+}
+export function assistantToolCallMessage(msg) {
+    if (!msg.tool_calls || msg.tool_calls.length === 0) {
+        return null;
+    }
+    const said = sdkContentFromParts(historyMessageParts(msg));
+    const lead = typeof said === 'string' ? (said ? [{ type: 'text', text: said }] : []) : said;
+    return {
+        role: 'assistant',
+        content: [
+            ...lead,
+            ...msg.tool_calls.map((call) => ({
+                type: 'tool-call',
+                toolCallId: call.id,
+                toolName: call.function.name,
+                input: historyToolArguments(call.function.arguments),
+            })),
+        ],
+    };
+}
+export function contentHistoryMessage(msg) {
+    return { role: msg.role, content: sdkContentFromParts(historyMessageParts(msg)) };
+}
+export function historyToSdk(msg) {
+    if (msg.role === 'tool') {
+        return toolResultMessage(msg);
+    }
+    return assistantToolCallMessage(msg) || contentHistoryMessage(msg);
+}
+/** Leaves `req.system` to the caller (`systemDelivery` in chat.ts). */
+export function buildAiSdkMessages(req) {
+    const messages = [];
+    for (const msg of req.history ?? []) {
+        const wired = historyToSdk(msg);
+        if (wired) {
+            messages.push(wired);
+        }
+    }
+    if (req.input.length > 0) {
+        messages.push({ role: 'user', content: sdkContentFromParts(req.input) });
+    }
+    return messages;
+}

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/resolve-api-key.d.ts

@@ -0,0 +1,3 @@
+import type { KeySlot } from '../../kernel/types.js';
+import type { OpenAiGatewayTransport } from '../types.js';
+export declare function resolveOpenAiGatewayApiKey(config: OpenAiGatewayTransport, keySlot: KeySlot | undefined): string;

package/esm/src/providers/openrouter/resolve-api-key.js

@@ -0,0 +1,8 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { requireKey } from '../shared/vault.js';
+export function resolveOpenAiGatewayApiKey(config, keySlot) {
+    if (keySlot === undefined) {
+        throw new TheoremError('auth', 'an OpenRouter model must name a vault slot');
+    }
+    return requireKey(config.vault, keySlot);
+}

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

@@ -0,0 +1,18 @@
+import type { InteractionPart, ModelProvider, ProfileSpeechSpec, ProviderCompleteRequest, ProviderEvent } from '../../kernel/types.js';
+import type { OpenAiGatewayTransport } from '../types.js';
+export type SpeechProviderConfig = OpenAiGatewayTransport & {
+    /** Fallback when the profile does not pin `speech.voice`. */
+    voice?: string;
+};
+export declare function extractInputText(input: InteractionPart[]): string;
+export declare function buildSpeechHeaders(apiKey: string, config: SpeechProviderConfig): Record<string, string>;
+export declare function buildPayload(req: ProviderCompleteRequest, text: string, speech: ProfileSpeechSpec | undefined, configVoice?: string): Record<string, unknown>;
+export declare function requestSpeech(apiKey: string, text: string, req: ProviderCompleteRequest, config: SpeechProviderConfig): Promise<Response>;
+/**
+ * The response's `content-type` states the audio (probe 23/09/2026:
+ * `audio/pcm;rate=24000;channels=1` for `pcm`). Raw PCM with a stated rate is
+ * wrapped as WAV; anything else keeps its reported type.
+ */
+export declare function yieldSpeechSuccess(rawBytes: Uint8Array, contentType: string | null): Generator<ProviderEvent>;
+export declare function streamSpeech(req: ProviderCompleteRequest, config?: SpeechProviderConfig): AsyncGenerator<ProviderEvent>;
+export declare function createSpeechProvider(config?: SpeechProviderConfig): ModelProvider;

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

@@ -0,0 +1,109 @@
+import { TheoremError, toErrorEvent } from '../../guardrails/error.js';
+import { bytesToBase64 } from '../../kernel/util/base64.js';
+import { mimeEssence } from '../../kernel/util/mime.js';
+import { pcmFormatFromMime, wrapPcmAsWav } from '../shared/pcm.js';
+import { networkFetch } from '../shared/upstream-tap.js';
+import { bearerFetch } from '../shared/vault.js';
+import { httpErrorEvent, openAiGatewayHeaders } from './openai/compat.js';
+import { resolveOpenAiGatewayApiKey } from './resolve-api-key.js';
+const HTTP_OK = 200;
+export function extractInputText(input) {
+    return input
+        .filter((p) => p.type === 'text')
+        .map((p) => (p.type === 'text' ? p.text : ''))
+        .join(' ')
+        .trim();
+}
+export function buildSpeechHeaders(apiKey, config) {
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+    };
+    const gateway = openAiGatewayHeaders(config);
+    if (gateway)
+        Object.assign(headers, gateway);
+    return headers;
+}
+export function buildPayload(req, text, speech, configVoice) {
+    const voice = speech?.voice ?? configVoice;
+    const payload = {
+        model: req.apiId,
+        input: text,
+    };
+    if (speech?.format) {
+        payload.response_format = speech.format;
+    }
+    if (voice) {
+        payload.voice = voice;
+    }
+    return payload;
+}
+export async function requestSpeech(apiKey, text, req, config) {
+    const fetchFn = bearerFetch(req, networkFetch(config.fetch ?? fetch), config.vault, apiKey);
+    const baseUrl = config.baseUrl?.replace(/\/+$/, '') ?? 'https://openrouter.ai/api/v1';
+    const url = `${baseUrl}/audio/speech`;
+    return await fetchFn(url, {
+        method: 'POST',
+        headers: buildSpeechHeaders(apiKey, config),
+        body: JSON.stringify(buildPayload(req, text, req.speech, config.voice)),
+        signal: req.signal,
+    });
+}
+/**
+ * The response's `content-type` states the audio (probe 23/09/2026:
+ * `audio/pcm;rate=24000;channels=1` for `pcm`). Raw PCM with a stated rate is
+ * wrapped as WAV; anything else keeps its reported type.
+ */
+export function* yieldSpeechSuccess(rawBytes, contentType) {
+    const format = pcmFormatFromMime(contentType ?? '');
+    const media = format
+        ? { mimeType: 'audio/wav', data: bytesToBase64(wrapPcmAsWav(rawBytes, format)) }
+        : {
+            mimeType: mimeEssence(contentType ?? '') || 'application/octet-stream',
+            data: bytesToBase64(rawBytes),
+        };
+    yield { type: 'media', media };
+    // The endpoint answers whole or not at all: a body with audio completed.
+    yield { type: 'done', stop: { kind: 'completed' } };
+}
+export async function* streamSpeech(req, config = {}) {
+    let apiKey;
+    try {
+        apiKey = resolveOpenAiGatewayApiKey(config, req.keySlot);
+    }
+    catch (err) {
+        yield toErrorEvent(err);
+        return;
+    }
+    const text = extractInputText(req.input);
+    if (!text) {
+        yield toErrorEvent(new TheoremError('request', 'empty text for speech'));
+        return;
+    }
+    const res = await requestSpeech(apiKey, text, req, config);
+    if (res.status !== HTTP_OK) {
+        yield await httpErrorEvent(res, 'Speech');
+        return;
+    }
+    const arrayBuffer = await res.arrayBuffer();
+    const rawBytes = new Uint8Array(arrayBuffer);
+    const contentType = res.headers.get('content-type');
+    // The audio body as a tape row; the tape keeps its hash, not its bytes.
+    req.tapUpstream?.({
+        eventType: 'http_body',
+        mime_type: contentType ?? '',
+        data: bytesToBase64(rawBytes),
+    });
+    if (rawBytes.length === 0) {
+        yield toErrorEvent(new TheoremError('bad_response', 'no audio returned from speech'));
+        return;
+    }
+    for (const ev of yieldSpeechSuccess(rawBytes, contentType)) {
+        yield ev;
+    }
+}
+export function createSpeechProvider(config = {}) {
+    return {
+        complete: (req) => streamSpeech(req, config),
+    };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * With `THEOREM_IMPORT_PROBE=1`, lets subprocess tests assert adapters stay unloaded
+ * until `complete` runs. Only `create-provider.ts` may call it.
+ */
+export declare function markModuleLoad(label: string): void;

package/esm/src/providers/probe.js

@@ -0,0 +1,15 @@
+/**
+ * With `THEOREM_IMPORT_PROBE=1`, lets subprocess tests assert adapters stay unloaded
+ * until `complete` runs. Only `create-provider.ts` may call it.
+ */
+export function markModuleLoad(label) {
+    try {
+        const d = globalThis.Deno;
+        if (d?.env?.get('THEOREM_IMPORT_PROBE') === '1' && d.stdout?.writeSync) {
+            d.stdout.writeSync(new TextEncoder().encode(`LOADED:${label}\n`));
+        }
+    }
+    catch {
+        // Non-Deno runtime or missing --allow-env.
+    }
+}

package/esm/src/providers/shared/builtin-wire.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinWire } from '../../kernel/tools/types.js';
+import type { ProviderBuiltin } from '../../kernel/types.js';
+declare function builtinWire(builtin: ProviderBuiltin, transport: keyof BuiltinWire): string;
+export { builtinWire };

package/esm/src/providers/shared/builtin-wire.js

@@ -0,0 +1,9 @@
+import { TheoremError } from '../../guardrails/error.js';
+function builtinWire(builtin, transport) {
+    const wire = builtin.wire[transport];
+    if (!wire) {
+        throw new TheoremError('config', `Builtin '${builtin.id}' has no wire.${transport}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return wire;
+}
+export { builtinWire };