@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,150 @@
+import { describeError, isAbortError, TheoremError } from '../../../guardrails/error.js';
+import { fallbackKey, requireKey } from '../../shared/vault.js';
+import { buildGeminiLiveWebSocketUrl } from './framing.js';
+import { attachLiveSessionHandlers, createLiveQueue, performLiveSetup, sendInitialPayloads, sendLiveFrame, } 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);
+}
+/** Tape row: setup on the pinned key was refused for quota, so the session opens on the fallback slot. */
+export const LIVE_FALLBACK_ROW = 'ws_fallback';
+async function openOnKey(req, apiKey, openWebSocket) {
+    let ws;
+    try {
+        ws = await openWebSocket(buildGeminiLiveWebSocketUrl(apiKey));
+    }
+    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 {
+        return { ws, liveQueue, detachAbort, setup: await performLiveSetup(ws, req) };
+    }
+    catch (err) {
+        detachAbort();
+        try {
+            ws.close();
+        }
+        catch {
+            // Ignore
+        }
+        throw err;
+    }
+}
+/**
+ * Open on the pinned key; a quota refusal at setup reopens on the profile's
+ * fallback slot when it names one, as `fetchGemini` does for HTTP.
+ * The tape records the refusal (`ws_fallback`) before the retry.
+ */
+async function openWithOverflow(req, transport, openWebSocket) {
+    if (!req.keySlot) {
+        throw new TheoremError('config', 'Request requires keySlot');
+    }
+    const primary = requireKey(transport.vault, req.keySlot);
+    try {
+        return await openOnKey(req, primary, openWebSocket);
+    }
+    catch (err) {
+        const fallback = fallbackKey(req.fallbackKeySlot, transport.vault, primary);
+        if (!fallback || !(err instanceof TheoremError) || err.kind !== 'rate_limit')
+            throw err;
+        req.tapUpstream?.({
+            eventType: LIVE_FALLBACK_ROW,
+            from: req.keySlot,
+            keySlot: fallback.slot,
+            errorKind: err.kind,
+            error: describeError(err),
+        });
+        return await openOnKey(req, fallback.key, openWebSocket);
+    }
+}
+/** @param openWebSocket Host override, e.g. for a Cloudflare fetch-upgrade. */
+export async function openGoogleLiveSession(req, transport, openWebSocket = defaultOpenWebSocket) {
+    const { ws, liveQueue, detachAbort, setup } = await openWithOverflow(req, transport, openWebSocket);
+    attachLiveSessionHandlers(ws, liveQueue);
+    sendInitialPayloads(ws, req);
+    return {
+        setup,
+        send(payload) {
+            if (ws.readyState === WebSocket.OPEN) {
+                sendLiveFrame(ws, payload, req.tapUpstream);
+            }
+        },
+        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,51 @@
+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 {
+    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;
+/**
+ * `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;

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

@@ -0,0 +1,263 @@
+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;
+/** RFC 6455 §7.4.1 close codes; any other code is `unavailable`. */
+const CLOSE_KINDS = {
+    1006: 'network',
+    1007: 'unsupported',
+    1008: 'unsupported',
+    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.
+ */
+const QUOTA_CLOSE_RE = /\bquota\b/i;
+/**
+ * A bad key closes setup with 1007 ("API key not valid. …"), which by code
+ * reads as `unsupported`; like quota, the reason is the only signal.
+ */
+const AUTH_CLOSE_RE = /\bAPI key (?:not valid|expired)\b/i;
+/** The kind a close's reason names, if any. */
+function closeReasonKind(reason) {
+    if (QUOTA_CLOSE_RE.test(reason))
+        return 'rate_limit';
+    if (AUTH_CLOSE_RE.test(reason))
+        return 'auth';
+    return undefined;
+}
+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) {
+    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
+ * produce output). Without it, `turnComplete` is the boundary.
+ */
+export function turnPhaseFromMessage(message, events) {
+    const interrupted = events.some((ev) => ev.type === 'done' && ev.interrupted === true);
+    if (interrupted)
+        return 'abort';
+    const status = readLiveInteractionStatus(message);
+    if (status === 'IDLE')
+        return 'complete';
+    if (status === 'IN_PROGRESS')
+        return 'streaming';
+    if (asRecord(message.serverContent)?.turnComplete === true)
+        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/thinking.d.ts

@@ -0,0 +1,3 @@
+import type { ThinkingLevel } from '../../kernel/schema.js';
+/** Refuses a thinking level Gemini does not take, rather than sending it. */
+export declare function assertGoogleThinkingLevel(level: ThinkingLevel | undefined): void;

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

@@ -0,0 +1,8 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { GOOGLE_THINKING_LEVELS } from '../../presets/google-limits.js';
+/** Refuses a thinking level Gemini does not take, rather than sending it. */
+export function assertGoogleThinkingLevel(level) {
+    if (level && !GOOGLE_THINKING_LEVELS.includes(level)) {
+        throw new TheoremError('unsupported', `Gemini does not take the '${level}' thinking level (${GOOGLE_THINKING_LEVELS.join(', ')})`);
+    }
+}

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

@@ -0,0 +1,6 @@
+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 };

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

@@ -0,0 +1,6 @@
+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 };

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

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

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

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

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

@@ -0,0 +1,12 @@
+import type { ModelProvider, ProviderEvent } from '../../kernel/types.js';
+import { buildChatMessages, wireTools } from '../openrouter/openai/compat.js';
+import type { LocalTransport } from '../types.js';
+export type PendingToolCall = {
+    id: string;
+    name: string;
+    args: string;
+};
+export declare function resolveBaseUrl(config: LocalTransport): string;
+export declare function flushPending(pending: Map<number, PendingToolCall>): ProviderEvent[];
+declare function createLocalProvider(config: LocalTransport): ModelProvider;
+export { buildChatMessages as historyToWire, createLocalProvider, wireTools as toolsToWire };