@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,10 @@
+import { type Provider } from '../../kernel/protocols/provider.js';
+/** What registering `openRouterProvider` takes as `connection`. */
+export interface OpenRouterConnection {
+    baseUrl?: string;
+    decisionUrl?: string;
+    siteUrl?: string;
+    siteName?: string;
+}
+/** OpenRouter: many labs' models behind one key. Chat, speech, images, and decisions. */
+export declare const openRouterProvider: Provider<OpenRouterConnection, string>;

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

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { bearer, defineProvider, endpointUrlSchema, } from '../../kernel/protocols/provider.js';
+import { systemOne } from '../system-one/protocol.js';
+import { openRouterEmbedding } from './embedding-protocol.js';
+import { openRouterImages } from './images-protocol.js';
+import { openRouter } from './protocol.js';
+const connection = z.strictObject({
+    baseUrl: endpointUrlSchema
+        .optional()
+        .describe('The API, by default https://openrouter.ai/api/v1.'), // labels-exempt: builder field description, read by the studio and docs
+    decisionUrl: endpointUrlSchema
+        .optional()
+        .describe('The decision API, by default https://openrouter.ai/api/alpha/decisions.'), // labels-exempt: builder field description, read by the studio and docs
+    siteUrl: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe('Sent as HTTP-Referer, for OpenRouter rankings.'), // labels-exempt: builder field description, read by the studio and docs
+    siteName: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe('Sent as X-Title, for OpenRouter rankings.'), // labels-exempt: builder field description, read by the studio and docs
+});
+/** OpenRouter: many labs' models behind one key. Chat, speech, images, and decisions. */
+export const openRouterProvider = defineProvider({
+    id: 'openrouter',
+    name: 'OpenRouter',
+    description: "Many labs' models behind one key.", // labels-exempt: builder field description, read by the studio and docs
+    connection: connection.default({}),
+    key: z.string().trim().min(1),
+    authorize: bearer(),
+    serves(at) {
+        const baseUrl = at.baseUrl ?? 'https://openrouter.ai/api/v1';
+        const headers = {};
+        if (at.siteUrl)
+            headers['HTTP-Referer'] = at.siteUrl;
+        if (at.siteName)
+            headers['X-Title'] = at.siteName;
+        const decisionUrl = at.decisionUrl ?? 'https://openrouter.ai/api/alpha/decisions';
+        return [
+            { protocol: openRouter, baseUrl, headers },
+            { protocol: openRouterEmbedding, baseUrl, headers },
+            { protocol: openRouterImages, baseUrl, headers },
+            { protocol: systemOne, baseUrl: decisionUrl, url: () => decisionUrl, headers },
+        ];
+    },
+});

package/esm/src/providers/shared/carried-tool-files.d.ts

@@ -0,0 +1,7 @@
+import type { InteractionPart, TurnHistoryMessage } from '../../kernel/types.js';
+/**
+ * History for a wire whose tool result holds only the `holds` part types. Every
+ * other file leaves a marker in its place and follows the run of tool results in
+ * one user message, so the results of a parallel call stay together.
+ */
+export declare function withCarriedToolFiles(messages: readonly TurnHistoryMessage[], holds: ReadonlySet<InteractionPart['type']>): TurnHistoryMessage[];

package/esm/src/providers/shared/carried-tool-files.js

@@ -0,0 +1,43 @@
+/** What stands in a tool result where a file it cannot hold was. */
+function carriedFileMarker(part) {
+    return { type: 'text', text: `[${part.type}: sent in the next message]` };
+}
+/** What leads the files of one tool result in the user message that carries them. */
+function carriedFilesLead(msg) {
+    const from = msg.name ? `the ${msg.name} result` : 'a tool result';
+    return { type: 'text', text: `Files from ${from}:` };
+}
+/**
+ * History for a wire whose tool result holds only the `holds` part types. Every
+ * other file leaves a marker in its place and follows the run of tool results in
+ * one user message, so the results of a parallel call stay together.
+ */
+export function withCarriedToolFiles(messages, holds) {
+    const out = [];
+    let carried = [];
+    const flush = () => {
+        if (carried.length === 0)
+            return;
+        out.push({ role: 'user', parts: carried });
+        carried = [];
+    };
+    for (const msg of messages) {
+        if (msg.role !== 'tool') {
+            flush();
+            out.push(msg);
+            continue;
+        }
+        const files = (msg.parts ?? []).filter((part) => !holds.has(part.type));
+        if (files.length === 0) {
+            out.push(msg);
+            continue;
+        }
+        out.push({
+            ...msg,
+            parts: (msg.parts ?? []).map((part) => holds.has(part.type) ? part : carriedFileMarker(part)),
+        });
+        carried.push(carriedFilesLead(msg), ...files);
+    }
+    flush();
+    return out;
+}

package/esm/src/providers/shared/pcm.d.ts

@@ -0,0 +1,14 @@
+export interface PcmFormat {
+    sampleRate: number;
+    channels: number;
+}
+export declare function writeAscii(view: DataView, offset: number, str: string): void;
+export declare function pcmFormatFromMime(mime: string): PcmFormat | undefined;
+export declare function wrapPcmAsWav(pcm: Uint8Array, format: PcmFormat): Uint8Array;
+export declare function pcmMediaAsWav(media: {
+    mimeType: string;
+    data: string;
+}): {
+    mimeType: string;
+    data: string;
+};

package/esm/src/providers/shared/pcm.js

@@ -0,0 +1,78 @@
+/*probed 2026-09-23:
+ * Each transport states the PCM format on the wire (probes 23/09/2026):
+ * - Gemini Live: `audio/pcm;rate=24000`
+ * - Interactions: `audio/l16; rate=24000; channels=1` (buffered), or
+ *   `audio/l16` with `sample_rate` / `channels` fields (stream deltas)
+ * - OpenRouter speech: `content-type: audio/pcm;rate=24000;channels=1`
+ *
+ * Samples are 16-bit little-endian on all three (measured), although RFC 2586
+ * defines `audio/L16` as big-endian. A mime without `rate=` has no known
+ * format, so its bytes pass through unchanged rather than being wrapped at a
+ * guessed rate. `channels=` absent means one channel (the RFC 2586 default;
+ * Live documents mono output).
+ */
+import { base64ToBytes, bytesToBase64 } from '../../kernel/util/base64.js';
+const BITS_PER_SAMPLE = 16;
+const RAW_PCM_ESSENCES = new Set(['audio/pcm', 'audio/l16']);
+export function writeAscii(view, offset, str) {
+    for (let i = 0; i < str.length; i++)
+        view.setUint8(offset + i, str.charCodeAt(i));
+}
+function positiveInt(value) {
+    if (value === undefined || !/^\d+$/.test(value))
+        return undefined;
+    const n = Number(value);
+    return n > 0 ? n : undefined;
+}
+function parseMime(mime) {
+    const [essence = '', ...rest] = mime.split(';');
+    const params = new Map();
+    for (const param of rest) {
+        const eq = param.indexOf('=');
+        if (eq > 0)
+            params.set(param.slice(0, eq).trim().toLowerCase(), param.slice(eq + 1).trim());
+    }
+    return { essence: essence.trim().toLowerCase(), params };
+}
+export function pcmFormatFromMime(mime) {
+    const { essence, params } = parseMime(mime);
+    if (!RAW_PCM_ESSENCES.has(essence))
+        return undefined;
+    const sampleRate = positiveInt(params.get('rate'));
+    if (sampleRate === undefined)
+        return undefined;
+    const channels = params.has('channels') ? positiveInt(params.get('channels')) : 1;
+    if (channels === undefined)
+        return undefined;
+    return { sampleRate, channels };
+}
+export function wrapPcmAsWav(pcm, format) {
+    const { sampleRate, channels } = format;
+    const blockAlign = (channels * BITS_PER_SAMPLE) / 8;
+    const byteRate = sampleRate * blockAlign;
+    const dataSize = pcm.length;
+    const buf = new ArrayBuffer(44 + dataSize);
+    const view = new DataView(buf);
+    writeAscii(view, 0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true);
+    writeAscii(view, 8, 'WAVE');
+    writeAscii(view, 12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, channels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, byteRate, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, BITS_PER_SAMPLE, true);
+    writeAscii(view, 36, 'data');
+    view.setUint32(40, dataSize, true);
+    new Uint8Array(buf, 44).set(pcm);
+    return new Uint8Array(buf);
+}
+export function pcmMediaAsWav(media) {
+    const format = pcmFormatFromMime(media.mimeType);
+    if (!format)
+        return media;
+    const wav = wrapPcmAsWav(base64ToBytes(media.data), format);
+    return { mimeType: 'audio/wav', data: bytesToBase64(wav) };
+}

package/esm/src/providers/shared/protocol-events.d.ts

@@ -0,0 +1,8 @@
+import type { ProtocolEvent } from '../../kernel/protocols/mod.js';
+import type { ModelEvent } from '../../kernel/types.js';
+/**
+ * One event from the shared Gemini and Chat Completions readers, as a protocol event: a finished
+ * call is a `tool_call`, a cancelled one a `tool_cancel`, and a broken one an error. A `done` keeps
+ * only its stop; the protocol adds its own state.
+ */
+export declare function asProtocolEvent<S>(event: ModelEvent): ProtocolEvent<S> | undefined;

package/esm/src/providers/shared/protocol-events.js

@@ -0,0 +1,20 @@
+/**
+ * One event from the shared Gemini and Chat Completions readers, as a protocol event: a finished
+ * call is a `tool_call`, a cancelled one a `tool_cancel`, and a broken one an error. A `done` keeps
+ * only its stop; the protocol adds its own state.
+ */
+export function asProtocolEvent(event) {
+    if (event.type === 'done')
+        return {
+            type: 'done',
+            stop: event.stop,
+            ...(event.interrupted === undefined ? {} : { interrupted: event.interrupted }),
+        };
+    if (event.type !== 'tool')
+        return event;
+    if (event.tool.phase === undefined)
+        return { type: 'tool_call', call: event.tool };
+    if (event.tool.phase === 'cancel')
+        return { type: 'tool_cancel', callId: event.tool.callId };
+    return event.tool.phase === 'error' ? { type: 'error', errorKind: 'bad_response' } : undefined;
+}

package/esm/src/providers/shared/response-identity.d.ts

@@ -0,0 +1,11 @@
+import type { ModelEvent, TurnResponse } from '../../kernel/types.js';
+/**
+ * Emits as soon as the wire names the response and again whenever that changes, so a
+ * call that fails or is cut by a guardrail still records which model served it.
+ */
+export declare function foldResponse(known: TurnResponse | undefined, seen: TurnResponse | undefined): {
+    known: TurnResponse | undefined;
+    event?: Extract<ModelEvent, {
+        type: 'response';
+    }>;
+};

package/esm/src/providers/shared/response-identity.js

@@ -0,0 +1,12 @@
+/**
+ * Emits as soon as the wire names the response and again whenever that changes, so a
+ * call that fails or is cut by a guardrail still records which model served it.
+ */
+export function foldResponse(known, seen) {
+    if (!seen)
+        return { known };
+    const next = { ...known, ...seen };
+    if (next.id === known?.id && next.model === known?.model)
+        return { known };
+    return { known: next, event: { type: 'response', response: next } };
+}

package/esm/src/providers/shared/retry.d.ts

@@ -0,0 +1,17 @@
+/** How a retry waits; a host or test may pass its own. The signal ends the wait early. */
+export type Wait = (ms: number, signal?: AbortSignal | null) => Promise<void>;
+/** All the waiting one call may do between tries; a wait that would pass it sends the last answer back. */
+export declare const WAIT_BUDGET_MS = 5000;
+export declare const waitDefault: Wait;
+export declare function isTransientHttp(status: number): boolean;
+export declare function isTransientThrown(err: unknown): boolean;
+export declare function backoffMs(attempt: number): number;
+/** `retry-after-ms`, else `Retry-After` in seconds or as a date; undefined when absent or unreadable. */
+export declare function retryAfterMs(headers: Headers, now?: number): number | undefined;
+/**
+ * Retries a transient status (408, 429, 5xx gateway) or a network failure while the waits stay
+ * within five seconds in all, at most four times. Each wait is the response's `Retry-After` when it gives one, else
+ * 1s, 2s, 4s then 8s; a wait that would pass the five seconds, or the call's own time left, is not
+ * taken, and the last answer or error goes back as it came. An abort ends the wait.
+ */
+export declare function retryTransient(send: typeof fetch, wait?: Wait, timeLeft?: () => number): typeof fetch;

package/esm/src/providers/shared/retry.js

@@ -0,0 +1,90 @@
+import { isAbortError, isTimeoutError } from '../../guardrails/error.js';
+const BACKOFF_MS = [1000, 2000, 4000, 8000];
+/** All the waiting one call may do between tries; a wait that would pass it sends the last answer back. */
+export const WAIT_BUDGET_MS = 5000;
+/** The most tries after the first: a `Retry-After: 0` costs no wait, so the budget alone never ends it. */
+const MAX_RETRIES = BACKOFF_MS.length;
+const MS_PER_SECOND = 1000;
+const TRANSIENT_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const TRANSIENT_THROWN_RE = /name resolution|dns|econnreset|econnrefused|etimedout|connection (?:refused|reset)|error sending request|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
+export const waitDefault = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(abortReason(signal));
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+    }, ms);
+    function onAbort() {
+        clearTimeout(timer);
+        reject(abortReason(signal));
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+function abortReason(signal) {
+    return signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+}
+export function isTransientHttp(status) {
+    return TRANSIENT_STATUSES.has(status);
+}
+export function isTransientThrown(err) {
+    if (isAbortError(err) || isTimeoutError(err)) {
+        return false;
+    }
+    return TRANSIENT_THROWN_RE.test(String(err));
+}
+export function backoffMs(attempt) {
+    return BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)];
+}
+/** `retry-after-ms`, else `Retry-After` in seconds or as a date; undefined when absent or unreadable. */
+export function retryAfterMs(headers, now = Date.now()) {
+    const ms = headers.get('retry-after-ms');
+    const after = headers.get('retry-after');
+    let delay;
+    if (ms !== null && ms.trim() !== '' && Number.isFinite(Number(ms))) {
+        delay = Number(ms);
+    }
+    else if (after !== null && after.trim() !== '') {
+        const seconds = Number(after);
+        delay = Number.isFinite(seconds) ? seconds * MS_PER_SECOND : Date.parse(after) - now;
+    }
+    if (delay === undefined || Number.isNaN(delay) || delay < 0) {
+        return undefined;
+    }
+    return delay;
+}
+/**
+ * Retries a transient status (408, 429, 5xx gateway) or a network failure while the waits stay
+ * within five seconds in all, at most four times. Each wait is the response's `Retry-After` when it gives one, else
+ * 1s, 2s, 4s then 8s; a wait that would pass the five seconds, or the call's own time left, is not
+ * taken, and the last answer or error goes back as it came. An abort ends the wait.
+ */
+export function retryTransient(send, wait = waitDefault, timeLeft = () => Number.POSITIVE_INFINITY) {
+    return async (url, init) => {
+        let waited = 0;
+        for (let attempt = 0;; attempt++) {
+            const left = Math.min(WAIT_BUDGET_MS - waited, timeLeft());
+            let delay;
+            try {
+                const res = await send(url, init);
+                if (!isTransientHttp(res.status)) {
+                    return res;
+                }
+                delay = retryAfterMs(res.headers) ?? backoffMs(attempt);
+                if (delay > left || attempt >= MAX_RETRIES) {
+                    return res;
+                }
+                await res.body?.cancel();
+            }
+            catch (err) {
+                delay = backoffMs(attempt);
+                if (!isTransientThrown(err) || delay > left || attempt >= MAX_RETRIES) {
+                    throw err;
+                }
+            }
+            await wait(delay, init?.signal);
+            waited += delay;
+        }
+    };
+}

package/esm/src/providers/shared/sse.d.ts

@@ -0,0 +1,6 @@
+export declare function takeSsePayloads(buffer: string, pendingEvent?: string): {
+    rest: string;
+    payloads: Record<string, unknown>[];
+    pendingEvent: string;
+};
+export declare function readSseChunks(body: ReadableStream<Uint8Array>): AsyncGenerator<Record<string, unknown>>;

package/esm/src/providers/shared/sse.js

@@ -0,0 +1,93 @@
+const DONE = '[DONE]';
+function asObject(parsed) {
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return undefined;
+}
+function dataRecord(raw, sseEvent) {
+    const data = raw.startsWith('data:') ? raw.slice(5).replace(/^ /, '') : raw;
+    const row = {};
+    if (sseEvent) {
+        row.sseEvent = sseEvent;
+    }
+    if (data === DONE) {
+        row.eventType = 'sse_done';
+        return row;
+    }
+    try {
+        const parsed = JSON.parse(data);
+        const obj = asObject(parsed);
+        if (obj) {
+            return { ...obj, ...row };
+        }
+        row.eventType = 'sse_unparsed';
+        row.data = parsed;
+        return row;
+    }
+    catch {
+        row.eventType = 'sse_unparsed';
+        row.data = data;
+        return row;
+    }
+}
+export function takeSsePayloads(buffer, pendingEvent = '') {
+    const payloads = [];
+    let event = pendingEvent;
+    let data = [];
+    let hasData = false;
+    let consumed = 0;
+    const lineEnds = /\r\n|\r|\n/g;
+    let start = 0;
+    for (let match = lineEnds.exec(buffer); match; match = lineEnds.exec(buffer)) {
+        if (match[0] === '\r' && match.index === buffer.length - 1)
+            break;
+        const line = buffer.slice(start, match.index);
+        start = match.index + match[0].length;
+        if (!line) {
+            if (hasData)
+                payloads.push(dataRecord(data.join('\n'), event));
+            event = '';
+            data = [];
+            hasData = false;
+            consumed = start;
+        }
+        else if (!line.startsWith(':')) {
+            const colon = line.indexOf(':');
+            const field = colon < 0 ? line : line.slice(0, colon);
+            const value = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+            if (field === 'event')
+                event = value;
+            if (field === 'data') {
+                data.push(value);
+                hasData = true;
+            }
+        }
+    }
+    return { rest: buffer.slice(consumed), payloads, pendingEvent: '' };
+}
+export async function* readSseChunks(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let ended = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                ended = true;
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            const result = takeSsePayloads(buffer);
+            buffer = result.rest;
+            for (const payload of result.payloads)
+                yield payload;
+        }
+    }
+    finally {
+        if (!ended)
+            void reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}

package/esm/src/providers/shared/structured-output.d.ts

@@ -0,0 +1,4 @@
+import type { TurnEvent } from '../../kernel/types.js';
+/** Invalid JSON is a `bad_response` error, never a silent skip. */
+declare function structuredEvent(text: string): TurnEvent;
+export { structuredEvent };

package/esm/src/providers/shared/structured-output.js

@@ -0,0 +1,11 @@
+import { TheoremError, toErrorEvent } from '../../guardrails/error.js';
+/** Invalid JSON is a `bad_response` error, never a silent skip. */
+function structuredEvent(text) {
+    try {
+        return { type: 'structured', structured: JSON.parse(text) };
+    }
+    catch (cause) {
+        return toErrorEvent(new TheoremError('bad_response', 'structured output was not valid JSON', { cause }));
+    }
+}
+export { structuredEvent };

package/esm/src/providers/shared/tool-args.d.ts

@@ -0,0 +1,24 @@
+import { type ToolCallBase } from '../../kernel/tools/events.js';
+import type { ToolCallRequest } from '../../kernel/tools/types.js';
+import type { ModelEvent } from '../../kernel/types.js';
+/**
+ * Adapters never invent a history call id or name: a provider that needs a
+ * missing one rejects the request, and that error is the answer.
+ */
+export declare function historyToolIdentity(fields: Record<string, string | undefined>): Record<string, string>;
+export type ParsedToolArguments = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+    raw: string;
+};
+export declare function parseToolArgumentsObject(raw: unknown): ParsedToolArguments;
+export declare function historyToolArguments(raw: unknown): Record<string, unknown>;
+/** A call sent without an id gets one, so its request and failure events join. */
+export declare function toolCallEvents(call: Pick<ToolCallRequest, 'name' | 'stepId' | 'stepCallCount'> & {
+    id?: string;
+}, rawArguments: unknown): ModelEvent[];
+/** The model still reads the failed call's result back. */
+export declare function malformedToolCall(base: ToolCallBase, message: string, raw: unknown, request?: Pick<ToolCallRequest, 'stepId' | 'stepCallCount'>): ModelEvent[];

package/esm/src/providers/shared/tool-args.js

@@ -0,0 +1,88 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { failureEvent, newCallId, toolCallRequestEvent, } from '../../kernel/tools/events.js';
+import { isRecord } from '../../kernel/util/record.js';
+/**
+ * Adapters never invent a history call id or name: a provider that needs a
+ * missing one rejects the request, and that error is the answer.
+ */
+export function historyToolIdentity(fields) {
+    const present = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined)
+            present[key] = value;
+    }
+    return present;
+}
+export function parseToolArgumentsObject(raw) {
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0) {
+            return { ok: true, value: {} };
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (isRecord(parsed)) {
+                return { ok: true, value: parsed };
+            }
+            return {
+                ok: false,
+                error: 'tool arguments JSON must be an object',
+                raw,
+            };
+        }
+        catch {
+            return {
+                ok: false,
+                error: 'malformed tool arguments JSON',
+                raw,
+            };
+        }
+    }
+    if (isRecord(raw)) {
+        return { ok: true, value: raw };
+    }
+    if (raw === undefined || raw === null) {
+        return { ok: true, value: {} };
+    }
+    return {
+        ok: false,
+        error: 'tool arguments must be a JSON object',
+        raw: String(raw),
+    };
+}
+export function historyToolArguments(raw) {
+    const parsed = parseToolArgumentsObject(raw);
+    if (!parsed.ok) {
+        throw new TheoremError('bad_response', parsed.error);
+    }
+    return parsed.value;
+}
+/** A call sent without an id gets one, so its request and failure events join. */
+export function toolCallEvents(call, rawArguments) {
+    const name = call.name.trim();
+    const base = { name, callId: call.id ?? newCallId(name) };
+    const request = {
+        stepId: call.stepId,
+        stepCallCount: call.stepCallCount,
+    };
+    if (!name) {
+        return malformedToolCall(base, 'function call is missing a name', rawArguments, request);
+    }
+    const parsed = parseToolArgumentsObject(rawArguments);
+    if (!parsed.ok) {
+        return malformedToolCall(base, parsed.error, parsed.raw, request);
+    }
+    return [toolCallRequestEvent(base, parsed.value, request)];
+}
+/** The model still reads the failed call's result back. */
+export function malformedToolCall(base, message, raw, request = {}) {
+    return [
+        toolCallRequestEvent(base, {}, request),
+        failureEvent(base, {
+            code: 'malformed_arguments',
+            kind: 'bad_response',
+            message,
+            details: { raw },
+        }),
+    ];
+}

package/esm/src/providers/shared/tool-draft.d.ts

@@ -0,0 +1,16 @@
+import type { ModelEvent } from '../../kernel/types.js';
+/** A tool call a provider is streaming: its id and name as far as they have come, and its arguments' text. */
+export interface StreamingToolCall {
+    id?: string;
+    name: string;
+    args: string;
+    /** How much of `args` has gone out as `tool_draft` events. */
+    drafted?: number;
+}
+/**
+ * The `tool_draft` event for what `call.args` has gained since it last drafted, and advances
+ * `call.drafted`. Nothing until the call has an id and a name: the call is emitted under that id,
+ * and its draft is joined to it by that id alone. Whatever came before then goes out in the first
+ * draft.
+ */
+export declare function toolDraftEvents(call: StreamingToolCall): ModelEvent[];

package/esm/src/providers/shared/tool-draft.js

@@ -0,0 +1,14 @@
+/**
+ * The `tool_draft` event for what `call.args` has gained since it last drafted, and advances
+ * `call.drafted`. Nothing until the call has an id and a name: the call is emitted under that id,
+ * and its draft is joined to it by that id alone. Whatever came before then goes out in the first
+ * draft.
+ */
+export function toolDraftEvents(call) {
+    const name = call.name.trim();
+    const from = call.drafted ?? 0;
+    if (!(call.id && name) || call.args.length <= from)
+        return [];
+    call.drafted = call.args.length;
+    return [{ type: 'tool_draft', callId: call.id, name, text: call.args.slice(from) }];
+}

package/esm/src/providers/shared/upstream-tap.d.ts

@@ -0,0 +1,8 @@
+import type { KeySlot, ModelRequest } from '../../kernel/types.js';
+export declare function tapeHeaderValue(key: string, value: string): string;
+export declare function tapeHeaders(headers?: HeadersInit): Record<string, string>;
+export declare function throwRow(err: unknown): Record<string, unknown>;
+export declare function tapFetch(tap: ModelRequest['tapUpstream'], send?: typeof fetch, keySlot?: KeySlot): typeof fetch;
+/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
+export declare function networkError(err: unknown): unknown;
+export declare function networkFetch(send?: typeof fetch): typeof fetch;