@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/providers/google/live/framing.js

@@ -5,14 +5,13 @@ import { historyMessageParts, isMediaRefPart } from '../../../kernel/interaction
 import { mediaKindForMime } from '../../../kernel/registry/catalog.js';
 import { toolEvent } from '../../../kernel/tools/events.js';
 import { isRecord } from '../../../kernel/util/record.js';
-import { builtinWire } from '../../shared/builtin-wire.js';
 import { pcmMediaAsWav } from '../../shared/pcm.js';
 import { historyToolArguments, historyToolIdentity, toolCallEvents, } from '../../shared/tool-args.js';
+import { liveBuiltinTool } from '../builtins.js';
 import { groundingFromLiveMetadata } from '../grounding.js';
 import { assertGoogleThinkingLevel } from '../thinking.js';
 import { GEMINI_LIVE_WS_URL } from '../urls.js';
 import { byModality, modalityCounts } from '../usage.js';
-import { toGeminiOpenApiSchema } from './openapi-schema.js';
 export function buildGeminiLiveWebSocketUrl(apiKey) {
     return `${GEMINI_LIVE_WS_URL}?key=${encodeURIComponent(apiKey)}`;
 }
@@ -21,26 +20,19 @@ export function buildGeminiLiveWebSocketUrl(apiKey) {
  * model keeps speaking, and a cancel reaches it as a `tool` event with `phase: 'cancel'`.
  */
 const LIVE_FUNCTION_BEHAVIOR = 'NON_BLOCKING';
+/** `parametersJsonSchema` takes the JSON Schema as it is; `parameters` takes only Google's OpenAPI subset. */
 export function wireFunctionDeclaration(decl) {
-    const parameters = toGeminiOpenApiSchema(decl.parameters);
     return {
         name: decl.name,
         description: decl.description,
         behavior: LIVE_FUNCTION_BEHAVIOR,
-        parameters: parameters && typeof parameters === 'object'
-            ? parameters
-            : { type: 'OBJECT', properties: {} },
+        parametersJsonSchema: decl.parameters ?? { type: 'object', properties: {} },
     };
 }
-/**
- * Builtins are their own tool entries (`{ googleSearch: {} }`), functions share
- * one `functionDeclarations` entry. Which builtins a model takes is the API's
- * answer (probe 23/09/2026: a model without one closes the socket with 1007).
- */
 function wireLiveTools(req) {
     const tools = [];
     for (const builtin of req.builtins) {
-        tools.push({ [builtinWire(builtin, 'live')]: {} });
+        tools.push(liveBuiltinTool(builtin));
     }
     const functionDeclarations = (req.wireTools ?? []).map(wireFunctionDeclaration);
     if (functionDeclarations.length > 0) {
@@ -64,14 +56,16 @@ function buildLiveGenerationConfig(req) {
         };
     }
     assertGoogleThinkingLevel(req.thinking);
-    if (req.thinking) {
-        generationConfig.thinkingConfig = {
-            thinkingLevel: req.thinking,
-        };
+    const thinkingConfig = {
+        ...(req.thinking ? { thinkingLevel: req.thinking } : {}),
+        ...(req.summaries ? { includeThoughts: req.summaries === 'auto' } : {}),
+    };
+    if (Object.keys(thinkingConfig).length > 0) {
+        generationConfig.thinkingConfig = thinkingConfig;
     }
     return generationConfig;
 }
-// Unset numbers are left to Gemini's defaults.
+// why: Unset numbers are left to Gemini's defaults.
 function buildContextWindowCompression(compression) {
     const { triggerTokens } = compression;
     const { targetTokens } = compression.slidingWindow;
@@ -128,7 +122,7 @@ export function buildGeminiLiveSetupMessage(req) {
     const realtimeInputConfig = live?.vad ? buildLiveRealtimeInputConfig(live.vad) : undefined;
     const tools = wireLiveTools(req);
     const sessionResumption = buildLiveSessionResumption(req);
-    // `initialHistoryInClientContent` makes Gemini wait for clientContent before
+    // why: `initialHistoryInClientContent` makes Gemini wait for clientContent before
     // realtime generation, so an empty session (e.g. Th30) would hang forever.
     const seedInitialHistory = Boolean(req.history && req.history.length > 0);
     const setup = {
@@ -228,27 +222,30 @@ export function buildGeminiLiveRealtimeInput(input) {
         };
     }
     const part = inlineMediaPart(input);
-    // The part's mime as given: the API reads the rate from it and rejects what it cannot take.
+    // why: The part's mime as given: the API reads the rate from it and rejects what it cannot take.
     const media = { mimeType: part.mimeType, data: part.data };
     return { realtimeInput: part.type === 'audio' ? { audio: media } : { video: media } };
 }
-export function liveFunctionResponsePayload(output) {
+function liveFunctionResponsePayload(output) {
     const error = asRecord(output)?.error;
     if (typeof error === 'string') {
         return { error };
     }
     return { result: output };
 }
-export function buildGeminiLiveToolResponse(id, name, output) {
-    return buildGeminiLiveToolResponses([{ id, name, output }]);
+export function buildGeminiLiveToolResponse(id, name, output, parts) {
+    return buildGeminiLiveToolResponses([{ id, name, output, parts }]);
 }
 export function buildGeminiLiveToolResponses(responses) {
     return {
         toolResponse: {
-            functionResponses: responses.map(({ id, name, output }) => ({
+            functionResponses: responses.map(({ id, name, output, parts }) => ({
                 id,
                 name,
                 response: liveFunctionResponsePayload(output),
+                ...(parts?.length
+                    ? { parts: parts.filter((part) => part.type !== 'text').map(contentPart) }
+                    : {}),
             })),
         },
     };
@@ -393,13 +390,16 @@ function foldToolCalls(message, fold, events) {
     const calls = asRecord(message.toolCall)?.functionCalls;
     if (!Array.isArray(calls))
         return;
+    // why: The calls of one `toolCall` message are the model's step: chosen together, before any result.
+    const stepId = crypto.randomUUID();
+    const stepCallCount = calls.length;
     for (const value of calls) {
         const call = asRecord(value) ?? {};
         const id = typeof call.id === 'string' && call.id ? call.id : undefined;
         const name = typeof call.name === 'string' ? call.name : '';
         if (id && name)
             fold.calls.set(id, name);
-        events.push(...toolCallEvents({ id, name }, call.args));
+        events.push(...toolCallEvents({ id, name, stepId, stepCallCount }, call.args));
     }
 }
 /**
@@ -415,7 +415,7 @@ function foldToolCancellations(message, fold, events) {
     for (const id of ids) {
         const name = typeof id === 'string' ? fold.calls.get(id) : undefined;
         if (typeof id !== 'string' || !name) {
-            // Every observed cancel names a call this connection issued; anything else is a wire change.
+            // why: Every observed cancel names a call this connection issued; anything else is a wire change.
             events.push(toErrorEvent(new TheoremError('bad_response', `Live cancelled a tool call it never issued: ${String(id)}`)));
             continue;
         }

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

@@ -1,51 +1,13 @@
 import { TheoremError } from '../../../guardrails/error.js';
-import type { ProviderCompleteRequest, ProviderEvent } from '../../../kernel/types.js';
-export type LiveTurnPhase = 'streaming' | 'complete' | 'abort';
-export declare function sendLiveFrame(ws: LiveSocketSender, payload: Record<string, unknown>, tap: ProviderCompleteRequest['tapUpstream']): void;
-/** `row` is the parsed frame, so the kernel records it beside the events it produced. */
-export type SessionQueueItem = {
-    type: 'batch';
-    events: ProviderEvent[];
-    turnPhase: LiveTurnPhase;
-    row: Record<string, unknown>;
-} | {
-    type: 'row';
-    row: Record<string, unknown>;
-} | {
-    type: 'error';
-    error: Error;
-    row?: Record<string, unknown>;
-}
-/** `error` is set when the close was not normal; `goAway` when the provider warned first. */
- | {
-    type: 'closed';
-    code: number;
-    reason: string;
-    error?: TheoremError;
-    goAway?: GoAwayClose;
-};
-export interface GoAwayClose {
+import type { ModelEvent } from '../../../kernel/types.js';
+import type { LiveTurnPhase } from '../../types.js';
+export declare function closeError(code: number, reason: string, during: 'setup' | 'session'): TheoremError;
+export declare function goAwayIn(events: readonly ModelEvent[]): {
     timeLeftMs?: number;
-    /** Milliseconds from the last `goAway` to the close. */
-    closedAfterMs: number;
-}
-export declare function readMessageData(data: unknown): Promise<string>;
-export declare function performLiveSetup(ws: WebSocket, req: ProviderCompleteRequest): Promise<Record<string, unknown>>;
-export type LiveSocketSender = {
-    send(data: string): void;
-};
-export declare function sendInitialPayloads(ws: LiveSocketSender, req: ProviderCompleteRequest): void;
-export interface LiveQueue {
-    push: (item: SessionQueueItem) => void;
-    next: () => Promise<SessionQueueItem | undefined>;
-    close: () => void;
-    isClosed: () => boolean;
-}
-export declare function createLiveQueue(): LiveQueue;
+} | undefined;
 /**
  * `interactionStatus`, when sent, is authoritative: `IN_PROGRESS` keeps the cycle
  * open across `turnComplete` (background reasoning or async tools may still
  * produce output). Without it, `turnComplete` is the boundary.
  */
-export declare function turnPhaseFromMessage(message: Record<string, unknown>, events: ProviderEvent[]): LiveTurnPhase;
-export declare function attachLiveSessionHandlers(ws: WebSocket, liveQueue: LiveQueue): void;
+export declare function turnPhaseFromMessage(message: Record<string, unknown>, events: ModelEvent[]): LiveTurnPhase;

package/esm/src/providers/google/live/stream.js

@@ -1,9 +1,7 @@
 import { TheoremError } from '../../../guardrails/error.js';
 import { asRecord } from '../../../kernel/engine/record.js';
 import { findLast } from '../../../kernel/util/find-last.js';
-import { readGeminiApiError } from '../api-error.js';
-import { buildGeminiLiveClientContent, buildGeminiLiveRealtimeInput, buildGeminiLiveSetupMessage, foldGeminiLiveServerMessage, newLiveFold, parseGeminiLiveMessage, readLiveInteractionStatus, } from './framing.js';
-const SETUP_TIMEOUT_MS = 20_000;
+import { readLiveInteractionStatus } from './framing.js';
 /** RFC 6455 §7.4.1 close codes; any other code is `unavailable`. */
 const CLOSE_KINDS = {
     1006: 'network',
@@ -12,7 +10,6 @@ const CLOSE_KINDS = {
     1011: 'unavailable',
     1013: 'unavailable',
 };
-const NORMAL_CLOSE = 1000;
 /**
  * Google refuses an over-quota Live key with code 1011 (`unavailable`) and a reason
  * ("You exceeded your current quota, …"); the reason is the only quota signal.
@@ -31,148 +28,15 @@ function closeReasonKind(reason) {
         return 'auth';
     return undefined;
 }
-function closeError(code, reason, during) {
+export function closeError(code, reason, during) {
     return new TheoremError(closeReasonKind(reason) ?? CLOSE_KINDS[code] ?? 'unavailable', `Gemini Live WebSocket closed during ${during} (${code}: ${reason})`);
 }
-/** Received frames travel on the queue, not as tap rows. */
-const LIVE_SEND_ROW = 'ws_send';
-export function sendLiveFrame(ws, payload, tap) {
-    tap?.({ eventType: LIVE_SEND_ROW, body: payload });
-    ws.send(JSON.stringify(payload));
-}
-function goAwayIn(events) {
+export function goAwayIn(events) {
     const warning = findLast(events, (ev) => ev.type === 'session' && ev.session.kind === 'closing_soon');
     return warning?.session.kind === 'closing_soon'
         ? { timeLeftMs: warning.session.timeLeftMs }
         : undefined;
 }
-export async function readMessageData(data) {
-    if (typeof data === 'string')
-        return data;
-    if (data instanceof ArrayBuffer) {
-        return new TextDecoder().decode(data);
-    }
-    if (typeof Blob !== 'undefined' && data instanceof Blob) {
-        return await data.text();
-    }
-    return String(data);
-}
-export function performLiveSetup(ws, req) {
-    return new Promise((resolve, reject) => {
-        let setupResolved = false;
-        const timeout = setTimeout(() => {
-            if (!setupResolved) {
-                setupResolved = true;
-                reject(new TheoremError('timeout', `Gemini Live setup timed out after ${SETUP_TIMEOUT_MS}ms`));
-            }
-        }, SETUP_TIMEOUT_MS);
-        const sendSetup = () => {
-            try {
-                sendLiveFrame(ws, buildGeminiLiveSetupMessage(req), req.tapUpstream);
-            }
-            catch (err) {
-                clearTimeout(timeout);
-                setupResolved = true;
-                reject(err instanceof Error ? err : new Error(String(err)));
-            }
-        };
-        ws.onerror = () => {
-            clearTimeout(timeout);
-            if (!setupResolved) {
-                setupResolved = true;
-                reject(new TheoremError('network', 'Gemini Live WebSocket error during setup'));
-            }
-        };
-        ws.onclose = (evt) => {
-            clearTimeout(timeout);
-            if (!setupResolved) {
-                setupResolved = true;
-                reject(closeError(evt.code, evt.reason, 'setup'));
-            }
-        };
-        const initialMessageHandler = async (evt) => {
-            const rawText = await readMessageData(evt.data);
-            const parsed = parseGeminiLiveMessage(rawText);
-            if (!parsed.ok) {
-                if (parsed.reason === 'empty')
-                    return;
-                clearTimeout(timeout);
-                setupResolved = true;
-                reject(new TheoremError('bad_response', 'malformed Gemini Live message during setup'));
-                return;
-            }
-            const apiError = readGeminiApiError(parsed.value);
-            if (apiError) {
-                clearTimeout(timeout);
-                setupResolved = true;
-                reject(apiError);
-                return;
-            }
-            if (parsed.value.setupComplete) {
-                clearTimeout(timeout);
-                setupResolved = true;
-                ws.removeEventListener('message', initialMessageHandler);
-                resolve(parsed.value);
-            }
-        };
-        ws.addEventListener('message', initialMessageHandler);
-        // A fetch-upgraded socket (Cloudflare `resp.webSocket.accept()`) is already
-        // open and never fires `open`.
-        if (ws.readyState === WebSocket.OPEN) {
-            sendSetup();
-        }
-        else {
-            ws.onopen = sendSetup;
-        }
-    });
-}
-export function sendInitialPayloads(ws, req) {
-    if (req.history && req.history.length > 0) {
-        const historyMsg = buildGeminiLiveClientContent(req.history);
-        if (historyMsg) {
-            sendLiveFrame(ws, historyMsg, req.tapUpstream);
-        }
-    }
-    for (const part of req.input ?? []) {
-        sendLiveFrame(ws, buildGeminiLiveRealtimeInput(part), req.tapUpstream);
-    }
-}
-export function createLiveQueue() {
-    const queue = [];
-    let notify = null;
-    let closed = false;
-    return {
-        push(item) {
-            queue.push(item);
-            if (notify) {
-                const fn = notify;
-                notify = null;
-                fn();
-            }
-        },
-        async next() {
-            while (queue.length === 0) {
-                if (closed)
-                    return undefined;
-                await new Promise((resolve) => {
-                    notify = resolve;
-                });
-            }
-            return queue.shift();
-        },
-        close() {
-            closed = true;
-            if (notify) {
-                const fn = notify;
-                notify = null;
-                fn();
-            }
-        },
-        isClosed() {
-            return closed;
-        },
-    };
-}
 /**
  * `interactionStatus`, when sent, is authoritative: `IN_PROGRESS` keeps the cycle
  * open across `turnComplete` (background reasoning or async tools may still
@@ -191,73 +55,3 @@ export function turnPhaseFromMessage(message, events) {
         return 'complete';
     return 'streaming';
 }
-export function attachLiveSessionHandlers(ws, liveQueue) {
-    const fold = newLiveFold();
-    /** The last `goAway`, and when it arrived (monotonic ms). */
-    let goAway;
-    ws.onmessage = async (evt) => {
-        try {
-            const rawText = await readMessageData(evt.data);
-            const parsed = parseGeminiLiveMessage(rawText);
-            if (!parsed.ok) {
-                if (parsed.reason === 'empty')
-                    return;
-                liveQueue.push({
-                    type: 'error',
-                    error: new TheoremError('bad_response', 'malformed Gemini Live message'),
-                });
-                return;
-            }
-            if (parsed.value.setupComplete)
-                return;
-            const apiError = readGeminiApiError(parsed.value);
-            if (apiError) {
-                liveQueue.push({ type: 'error', error: apiError, row: parsed.value });
-                return;
-            }
-            const events = foldGeminiLiveServerMessage(parsed.value, fold);
-            const warning = goAwayIn(events);
-            if (warning)
-                goAway = { ...warning, atMs: performance.now() };
-            const turnPhase = turnPhaseFromMessage(parsed.value, events);
-            liveQueue.push(events.length > 0 || turnPhase !== 'streaming'
-                ? { type: 'batch', events, turnPhase, row: parsed.value }
-                : { type: 'row', row: parsed.value });
-        }
-        catch (err) {
-            liveQueue.push({
-                type: 'error',
-                error: err instanceof Error ? err : new Error(String(err)),
-            });
-        }
-    };
-    ws.onerror = () => {
-        if (!liveQueue.isClosed()) {
-            liveQueue.push({
-                type: 'error',
-                error: new TheoremError('network', 'Gemini Live WebSocket error'),
-            });
-        }
-    };
-    ws.onclose = (evt) => {
-        if (!liveQueue.isClosed()) {
-            liveQueue.push({
-                type: 'closed',
-                code: evt.code,
-                reason: evt.reason,
-                ...(evt.code === NORMAL_CLOSE
-                    ? {}
-                    : { error: closeError(evt.code, evt.reason, 'session') }),
-                ...(goAway
-                    ? {
-                        goAway: {
-                            ...(goAway.timeLeftMs !== undefined ? { timeLeftMs: goAway.timeLeftMs } : {}),
-                            closedAfterMs: Math.round(performance.now() - goAway.atMs),
-                        },
-                    }
-                    : {}),
-            });
-            liveQueue.close();
-        }
-    };
-}

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

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

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

@@ -1,6 +1,4 @@
-const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse';
-const INTERACTIONS_JSON_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions';
 /** 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, INTERACTIONS_JSON_URL, INTERACTIONS_URL };
+export { GEMINI_LIVE_WS_URL, GEMINI_MODELS_URL };

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

@@ -1,5 +1,5 @@
-/*
- * Google usage lists, in the spellings the wire sends (probed 23/09/2026):
+/* 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`,

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

@@ -1,11 +1,32 @@
 /**
- * `createProvider(profile, options)` binds a profile to a transport with host-supplied credentials.
- *
+ * 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 { KeyVault } from '../kernel/types.js';
-export type { CreateProviderOptions } from './create-provider.js';
-export { createProvider } from './create-provider.js';
-export type { GeminiOptions } from './google/keys.js';
-export type { LocalProviderConfig, OpenAiGatewayConfig } from './types.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

@@ -1,7 +1,23 @@
 /**
- * `createProvider(profile, options)` binds a profile to a transport with host-supplied credentials.
- *
+ * 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 { createProvider } from './create-provider.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';