theorum 0.1.14 → 1.0.0

package/esm/src/providers/google/live/openapi-schema.js

@@ -0,0 +1,45 @@
+/**
+ * Gemini Live / OpenAPI Schema 3.0 style type uppercasing for function parameters.
+ * JSON Schema uses lowercase `object`/`string`; Gemini Live expects `OBJECT`/`STRING`.
+ */
+function convertGeminiSchemaType(value) {
+    if (typeof value === 'string')
+        return { type: value.toUpperCase() };
+    if (!Array.isArray(value))
+        return { type: toGeminiOpenApiSchema(value) };
+    const schemaTypes = value.filter((item) => typeof item === 'string');
+    const nonNullTypes = schemaTypes.filter((item) => item !== 'null');
+    const converted = {};
+    if (schemaTypes.includes('null'))
+        converted.nullable = true;
+    if (nonNullTypes.length === 1)
+        converted.type = nonNullTypes[0].toUpperCase();
+    if (nonNullTypes.length > 1) {
+        converted.anyOf = nonNullTypes.map((item) => ({ type: item.toUpperCase() }));
+    }
+    return converted;
+}
+function convertGeminiSchemaObject(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === 'type') {
+            Object.assign(result, convertGeminiSchemaType(value));
+        }
+        else if (key === 'enum' && Array.isArray(value)) {
+            result.enum = value.filter((item) => item !== null);
+        }
+        else {
+            result[key] = toGeminiOpenApiSchema(value);
+        }
+    }
+    return result;
+}
+/** Convert JSON-Schema-ish parameters to Gemini Live OpenAPI Schema shape. */
+export function toGeminiOpenApiSchema(value) {
+    if (Array.isArray(value))
+        return value.map(toGeminiOpenApiSchema);
+    if (value !== null && typeof value === 'object') {
+        return convertGeminiSchemaObject(value);
+    }
+    return value;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Google Gemini Live session transport — long-lived BidiGenerateContent WebSocket.
+ *
+ * `turnComplete` is a conversational turn boundary, not session teardown.
+ *
+ * @module
+ */
+import type { ProviderCompleteRequest } from '../../../kernel/types.js';
+import { type GeminiTransport } from '../keys.js';
+import { type SessionQueueItem } from './stream.js';
+export interface GoogleLiveConnection {
+    /** Send a framed JSON payload upstream. */
+    send(payload: string): void;
+    /** Drain session batches until the socket closes or errors. */
+    batches(): AsyncGenerator<SessionQueueItem>;
+    close(code?: number, reason?: string): void;
+}
+export type OpenLiveWebSocket = (url: string) => Promise<WebSocket>;
+/**
+ * Open a long-lived Gemini Live WebSocket after setup handshake.
+ * Callers own send / batch drain / close — typically via `runSession`.
+ *
+ * @param openWebSocket Host override for Cloudflare fetch-upgrade (etc.).
+ */
+export declare function openGoogleLiveSession(req: ProviderCompleteRequest, transport: GeminiTransport, openWebSocket?: OpenLiveWebSocket): Promise<GoogleLiveConnection>;

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

@@ -0,0 +1,134 @@
+/**
+ * Google Gemini Live session transport — long-lived BidiGenerateContent WebSocket.
+ *
+ * `turnComplete` is a conversational turn boundary, not session teardown.
+ *
+ * @module
+ */
+import { isAbortError, TheorumError } from '../../../guardrails/error.js';
+import { requireKey } from '../keys.js';
+import { buildGeminiLiveWebSocketUrl } from './framing.js';
+import { attachLiveSessionHandlers, createLiveQueue, performLiveSetup, sendInitialPayloads, } from './stream.js';
+function defaultOpenWebSocket(url) {
+    return Promise.resolve(new WebSocket(url));
+}
+function attachAbort(ws, liveQueue, signal) {
+    const onAbort = () => {
+        if (!liveQueue.isClosed()) {
+            liveQueue.close();
+            try {
+                ws.close(1000, 'aborted');
+            }
+            catch {
+                // Ignore
+            }
+            liveQueue.push({
+                type: 'error',
+                error: new DOMException('The operation was aborted.', 'AbortError'),
+            });
+        }
+    };
+    if (!signal) {
+        return () => { };
+    }
+    if (signal.aborted) {
+        onAbort();
+        return () => { };
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+    return () => signal.removeEventListener('abort', onAbort);
+}
+/**
+ * Open a long-lived Gemini Live WebSocket after setup handshake.
+ * Callers own send / batch drain / close — typically via `runSession`.
+ *
+ * @param openWebSocket Host override for Cloudflare fetch-upgrade (etc.).
+ */
+export async function openGoogleLiveSession(req, transport, openWebSocket = defaultOpenWebSocket) {
+    if (!req.keySlot) {
+        throw new TheorumError('Request requires keySlot');
+    }
+    const apiKey = requireKey(transport.vault, req.keySlot);
+    const wsUrl = buildGeminiLiveWebSocketUrl(apiKey);
+    let ws;
+    try {
+        ws = await openWebSocket(wsUrl);
+    }
+    catch (err) {
+        throw err instanceof Error ? err : new Error(String(err));
+    }
+    const liveQueue = createLiveQueue();
+    const detachAbort = attachAbort(ws, liveQueue, req.signal);
+    if (req.signal?.aborted) {
+        detachAbort();
+        try {
+            ws.close();
+        }
+        catch {
+            // Ignore
+        }
+        throw new DOMException('The operation was aborted.', 'AbortError');
+    }
+    try {
+        await performLiveSetup(ws, req);
+    }
+    catch (err) {
+        detachAbort();
+        try {
+            ws.close();
+        }
+        catch {
+            // Ignore
+        }
+        throw err;
+    }
+    attachLiveSessionHandlers(ws, liveQueue);
+    sendInitialPayloads(ws, req);
+    return {
+        send(payload) {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.send(payload);
+            }
+        },
+        async *batches() {
+            try {
+                while (true) {
+                    const item = await liveQueue.next();
+                    if (!item)
+                        break;
+                    if (item.type === 'error' && isAbortError(item.error)) {
+                        throw item.error;
+                    }
+                    yield item;
+                    if (item.type === 'closed' || item.type === 'error') {
+                        break;
+                    }
+                }
+            }
+            finally {
+                detachAbort();
+                liveQueue.close();
+                try {
+                    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                        ws.close(1000, 'session-closed');
+                    }
+                }
+                catch {
+                    // Ignore
+                }
+            }
+        },
+        close(code = 1000, reason = 'session-closed') {
+            detachAbort();
+            liveQueue.close();
+            try {
+                if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                    ws.close(code, reason);
+                }
+            }
+            catch {
+                // Ignore
+            }
+        },
+    };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Shared Gemini Live WebSocket transport helpers.
+ *
+ * Used by `openGoogleLiveSession` / `runSession`. No ModelProvider.complete() path —
+ * live is session-scoped, not turn-scoped.
+ *
+ * @module
+ */
+import type { ProviderCompleteRequest, TurnEvent } from '../../../kernel/types.js';
+export type LiveTurnPhase = 'streaming' | 'complete' | 'abort';
+export type SessionQueueItem = {
+    type: 'batch';
+    events: TurnEvent[];
+    turnPhase: LiveTurnPhase;
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: 'closed';
+};
+export declare function readMessageData(data: unknown): Promise<string>;
+export declare function readGeminiLiveErrorMessage(message: Record<string, unknown>): string | null;
+export declare function performLiveSetup(ws: WebSocket, req: ProviderCompleteRequest): Promise<void>;
+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;
+/** Attach handlers that keep the socket open across conversational turns. */
+export declare function attachLiveSessionHandlers(ws: WebSocket, liveQueue: LiveQueue): void;

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

@@ -0,0 +1,201 @@
+/**
+ * Shared Gemini Live WebSocket transport helpers.
+ *
+ * Used by `openGoogleLiveSession` / `runSession`. No ModelProvider.complete() path —
+ * live is session-scoped, not turn-scoped.
+ *
+ * @module
+ */
+import { TheorumError } from '../../../guardrails/error.js';
+import { buildGeminiLiveClientContent, buildGeminiLiveRealtimeInput, buildGeminiLiveSetupMessage, foldGeminiLiveServerMessage, parseGeminiLiveMessage, } from './framing.js';
+const SETUP_TIMEOUT_MS = 20_000;
+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 readGeminiLiveErrorMessage(message) {
+    const error = message.error;
+    if (!error || typeof error !== 'object')
+        return null;
+    const record = error;
+    if (typeof record.message === 'string' && record.message.length > 0) {
+        const status = typeof record.status === 'string' ? record.status : null;
+        return status ? `${status}: ${record.message}` : record.message;
+    }
+    return 'Gemini returned an error during live session.';
+}
+export function performLiveSetup(ws, req) {
+    return new Promise((resolve, reject) => {
+        let setupResolved = false;
+        const timeout = setTimeout(() => {
+            if (!setupResolved) {
+                setupResolved = true;
+                reject(new TheorumError(`Gemini Live setup timed out after ${SETUP_TIMEOUT_MS}ms`));
+            }
+        }, SETUP_TIMEOUT_MS);
+        ws.onopen = () => {
+            try {
+                const setupMsg = buildGeminiLiveSetupMessage(req);
+                ws.send(JSON.stringify(setupMsg));
+            }
+            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 TheorumError('Gemini Live WebSocket error during setup'));
+            }
+        };
+        ws.onclose = (evt) => {
+            clearTimeout(timeout);
+            if (!setupResolved) {
+                setupResolved = true;
+                reject(new TheorumError(`Gemini Live WebSocket closed during setup (${evt.code}: ${evt.reason})`));
+            }
+        };
+        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 TheorumError('malformed Gemini Live message during setup'));
+                return;
+            }
+            const errMsg = readGeminiLiveErrorMessage(parsed.value);
+            if (errMsg) {
+                clearTimeout(timeout);
+                setupResolved = true;
+                reject(new TheorumError(errMsg));
+                return;
+            }
+            if (parsed.value.setupComplete) {
+                clearTimeout(timeout);
+                setupResolved = true;
+                ws.removeEventListener('message', initialMessageHandler);
+                resolve();
+            }
+        };
+        ws.addEventListener('message', initialMessageHandler);
+    });
+}
+export function sendInitialPayloads(ws, req) {
+    if (req.history && req.history.length > 0) {
+        const historyMsg = buildGeminiLiveClientContent(req.history);
+        if (historyMsg) {
+            ws.send(JSON.stringify(historyMsg));
+        }
+    }
+    if (req.input && req.input.length > 0) {
+        for (const part of req.input) {
+            const inputMsg = buildGeminiLiveRealtimeInput(part);
+            ws.send(JSON.stringify(inputMsg));
+        }
+    }
+}
+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;
+        },
+    };
+}
+function turnPhaseFromMessage(message, events) {
+    const interrupted = events.some((ev) => ev.type === 'done' && ev.interrupted === true);
+    if (interrupted)
+        return 'abort';
+    const serverContent = message.serverContent;
+    if (serverContent?.turnComplete)
+        return 'complete';
+    return 'streaming';
+}
+/** Attach handlers that keep the socket open across conversational turns. */
+export function attachLiveSessionHandlers(ws, liveQueue) {
+    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 TheorumError('malformed Gemini Live message'),
+                });
+                return;
+            }
+            if (parsed.value.setupComplete)
+                return;
+            const errMsg = readGeminiLiveErrorMessage(parsed.value);
+            if (errMsg) {
+                liveQueue.push({ type: 'error', error: new TheorumError(errMsg) });
+                return;
+            }
+            const events = foldGeminiLiveServerMessage(parsed.value);
+            const turnPhase = turnPhaseFromMessage(parsed.value, events);
+            if (events.length > 0 || turnPhase !== 'streaming') {
+                liveQueue.push({ type: 'batch', events, turnPhase });
+            }
+        }
+        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 TheorumError('Gemini Live WebSocket error') });
+        }
+    };
+    ws.onclose = () => {
+        if (!liveQueue.isClosed()) {
+            liveQueue.push({ type: 'closed' });
+            liveQueue.close();
+        }
+    };
+}

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

@@ -0,0 +1,6 @@
+/** Google Interactions API endpoints. */
+declare const INTERACTIONS_URL = "https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse";
+declare const INTERACTIONS_JSON_URL = "https://generativelanguage.googleapis.com/v1beta/interactions";
+/** Google Gemini Live WebSocket endpoint. */
+declare const GEMINI_LIVE_WS_URL = "wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent";
+export { GEMINI_LIVE_WS_URL, INTERACTIONS_JSON_URL, INTERACTIONS_URL };

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

@@ -0,0 +1,6 @@
+/** Google Interactions API endpoints. */
+const INTERACTIONS_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions?alt=sse';
+const INTERACTIONS_JSON_URL = 'https://generativelanguage.googleapis.com/v1beta/interactions';
+/** Google Gemini Live WebSocket endpoint. */
+const GEMINI_LIVE_WS_URL = 'wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent';
+export { GEMINI_LIVE_WS_URL, INTERACTIONS_JSON_URL, INTERACTIONS_URL };

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

@@ -0,0 +1,30 @@
+/**
+ * Local provider adapter for OpenAI-compatible endpoints (Ollama, llama.cpp,
+ * vLLM, LM Studio, etc.).
+ *
+ * Streams SSE from `/v1/chat/completions`, accumulates tool calls, and yields
+ * normalized `TurnEvent` objects. No external SDK dependency — raw fetch + SSE.
+ *
+ * Wire-format message building delegates to the shared `openai/compat` module.
+ * SSE parsing delegates to the shared `parseSseStream` from `sse.ts`.
+ *
+ * Hosts pass `baseUrl` explicitly. THEORUM does not read `OLLAMA_HOST` or other
+ * environment variables (see docs/contracts/providers.md).
+ *
+ * @module
+ */
+import type { ModelProvider, TurnEvent } from '../../kernel/types.js';
+import { buildChatMessages, wireTools } from '../openrouter/openai/compat.js';
+import type { LocalProviderConfig } from '../types.js';
+/** Default OpenAI-compat base when the host omits `baseUrl` (Ollama's default port). */
+export declare const DEFAULT_LOCAL_BASE_URL = "http://127.0.0.1:11434";
+export type PendingToolCall = {
+    id: string;
+    name: string;
+    args: string;
+};
+export declare function resolveBaseUrl(config?: LocalProviderConfig): string;
+export declare function flushPending(pending: Map<number, PendingToolCall>): TurnEvent[];
+/** Create a `ModelProvider` for a local OpenAI-compatible server (Ollama, llama.cpp, vLLM, LM Studio). */
+declare function createLocalProvider(config?: LocalProviderConfig): ModelProvider;
+export { buildChatMessages as historyToWire, createLocalProvider, wireTools as toolsToWire };