@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/providers/gemini/live-protocol.js

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { jsonObjectSchema } from '../../kernel/json.js';
+import { defineProtocol, } from '../../kernel/protocols/mod.js';
+import { readGeminiApiError } from '../google/api-error.js';
+import { googleBuiltins } from '../google/builtins.js';
+import { buildGeminiLiveClientContent, buildGeminiLiveContext, buildGeminiLiveRealtimeInput, buildGeminiLiveSetupMessage, buildGeminiLiveToolResponse, foldGeminiLiveServerMessage, liveFrameInput, newLiveFold, } from '../google/live/framing.js';
+import { closeError, goAwayIn, turnPhaseFromMessage } from '../google/live/stream.js';
+import { asProtocolEvent } from '../shared/protocol-events.js';
+const state = z.strictObject({ liveHandle: z.string().min(1) });
+const NORMAL_CLOSE = 1000;
+/** What a frame that is not the model's says: a close, a socket error, or bytes that are not JSON. */
+function socketTrouble(frame, during) {
+    if (frame.eventType === 'ws_error')
+        return new TheoremError('network', `Gemini Live WebSocket error during ${during}`); // labels-exempt: developer diagnostic
+    if (frame.eventType === 'ws_unparsed')
+        return new TheoremError('bad_response', 'malformed Gemini Live message'); // labels-exempt: developer diagnostic
+    return readGeminiApiError(frame) ?? undefined;
+}
+/** Waits for `setupComplete`; a refusal here comes before any event, so the kernel can try the other key. */
+async function setupComplete(frames, context) {
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new TheoremError('timeout', `Gemini Live setup timed out after ${context.limits.connectTimeoutMs}ms`)), context.limits.connectTimeoutMs);
+    });
+    try {
+        for (;;) {
+            const next = await Promise.race([frames.next(), late]);
+            if (next.done)
+                throw closeError(1006, '', 'setup');
+            const frame = next.value;
+            if (frame.eventType === 'ws_close')
+                throw closeError(Number(frame.code), String(frame.reason ?? ''), 'setup');
+            const trouble = socketTrouble(frame, 'setup');
+            if (trouble)
+                throw trouble;
+            if (frame.setupComplete)
+                return;
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function wireRequest(context, request) {
+    const handle = request.state?.liveHandle;
+    const history = request.history ?? [];
+    const builtins = googleBuiltins(request.builtins);
+    const wire = {
+        ...request,
+        apiId: context.apiId,
+        builtins,
+        state: undefined,
+        tapUpstream: undefined,
+        sessionResumptionHandle: handle,
+        // why: a resumed session already holds what came before its handle.
+        history: handle ? history.slice(request.stateHistoryLength ?? 0) : history,
+        live: {
+            ...request.live,
+            transcription: { ...request.live?.transcription, input: true, output: true },
+        },
+    };
+    const setup = jsonObjectSchema.parse(JSON.parse(JSON.stringify(buildGeminiLiveSetupMessage(wire))));
+    return { wire, setup, wroteTools: builtins.map((builtin) => builtin.id) };
+}
+/** One server message's events, then the stop its turn phase calls for. */
+function* batch(events, phase, handle) {
+    // why: usage first, so a turn's tokens are counted before its stop.
+    const ordered = [
+        ...events.filter((event) => event.type === 'tokens'),
+        ...events.filter((event) => event.type !== 'tokens'),
+    ];
+    for (const event of ordered) {
+        const converted = asProtocolEvent(event);
+        if (converted)
+            yield converted;
+    }
+    if (phase === 'abort')
+        return;
+    const saved = handle ? { state: { liveHandle: handle } } : {};
+    if (events.some((event) => event.type === 'tool' && event.tool.phase === undefined))
+        yield { type: 'done', stop: { kind: 'tool' }, ...saved };
+    if (phase === 'complete')
+        yield { type: 'done', stop: { kind: 'completed' }, ...saved };
+}
+function session(socket, frames, context, resumedFrom) {
+    const send = (frame) => sendFrame(socket, frame);
+    const fold = newLiveFold();
+    let handle = resumedFrom;
+    let goAway;
+    let closed;
+    return {
+        closeInfo: () => closed,
+        async *events() {
+            for (;;) {
+                const next = await frames.next();
+                if (next.done)
+                    return;
+                const frame = next.value;
+                if (frame.eventType === 'ws_close') {
+                    context.signal?.throwIfAborted();
+                    const code = Number(frame.code);
+                    const reason = String(frame.reason ?? '');
+                    closed = {
+                        code,
+                        reason,
+                        ...(code === NORMAL_CLOSE ? {} : { error: closeError(code, reason, 'session') }),
+                        ...(goAway
+                            ? {
+                                warning: {
+                                    ...(goAway.timeLeftMs === undefined ? {} : { timeLeftMs: goAway.timeLeftMs }),
+                                    closedAfterMs: Math.round(performance.now() - goAway.atMs),
+                                },
+                            }
+                            : {}),
+                    };
+                    return;
+                }
+                const trouble = socketTrouble(frame, 'session');
+                if (trouble)
+                    throw trouble;
+                if (frame.setupComplete)
+                    continue;
+                const events = foldGeminiLiveServerMessage(frame, fold);
+                const warning = goAwayIn(events);
+                if (warning)
+                    goAway = { ...warning, atMs: performance.now() };
+                for (const event of events)
+                    if (event.type === 'evidence' && event.sessionResumptionHandle)
+                        handle = event.sessionResumptionHandle;
+                yield* batch(events, turnPhaseFromMessage(frame, events), handle);
+            }
+        },
+        sendText: (text) => settled(() => send(buildGeminiLiveRealtimeInput({ type: 'text', text }))),
+        sendAudio: (media) => settled(() => send(buildGeminiLiveRealtimeInput({ type: 'audio', ...media }))),
+        sendVideo: (media) => settled(() => send(buildGeminiLiveRealtimeInput({ type: 'video', ...media }))),
+        sendContext: (value) => settled(() => send(buildGeminiLiveContext(typeof value.server === 'string' ? value.server : JSON.stringify(value)))),
+        sendToolResult: (result) => settled(() => send(buildGeminiLiveToolResponse(result.callId, result.name, result.text, result.parts))),
+        close: (reason) => settled(() => socket.close(NORMAL_CLOSE, reason ?? 'session-closed')),
+    };
+}
+/** Gemini Live: a spoken session over one WebSocket. */
+export const geminiLive = defineProtocol({
+    id: 'geminiLive',
+    name: 'Gemini Live',
+    description: "Google's Live API for Gemini: a spoken session over one WebSocket.", // labels-exempt: builder field description, read by the studio and docs
+    endpoints: { live: '/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent' },
+    options: z.strictObject({}),
+    continuation: { version: 1, schema: state },
+    create(context) {
+        return {
+            async openSession(request) {
+                const { wire, setup, wroteTools } = wireRequest(context, request);
+                const socket = await context.connect(setup, { wroteTools });
+                const frames = socket.frames()[Symbol.asyncIterator]();
+                const abort = () => socket.close(NORMAL_CLOSE, 'aborted');
+                context.signal?.addEventListener('abort', abort, { once: true });
+                try {
+                    context.signal?.throwIfAborted();
+                    await setupComplete(frames, context);
+                }
+                catch (error) {
+                    context.signal?.removeEventListener('abort', abort);
+                    socket.close(NORMAL_CLOSE, 'setup-failed');
+                    throw error;
+                }
+                const history = wire.history?.length
+                    ? buildGeminiLiveClientContent(wire.history)
+                    : undefined;
+                if (history)
+                    sendFrame(socket, history);
+                for (const part of wire.input)
+                    sendFrame(socket, buildGeminiLiveRealtimeInput(part));
+                return session(socket, frames, context, wire.sessionResumptionHandle);
+            },
+        };
+    },
+});
+/** A send that throws becomes a rejected promise, as the session's callers expect. */
+function settled(act) {
+    try {
+        act();
+        return Promise.resolve();
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+}
+function sendFrame(socket, frame) {
+    socket.send(frame, liveFrameInput(frame));
+}

package/esm/src/providers/gemini/prices.d.ts

@@ -0,0 +1,3 @@
+import type { PriceTable } from '../../kernel/protocols/prices.js';
+/** What the Gemini API charges per model. */
+export declare const geminiPrices: PriceTable;

package/esm/src/providers/gemini/prices.js

@@ -0,0 +1,63 @@
+/* probed 2026-10-15: https://ai.google.dev/gemini-api/docs/pricing, paid tier, US dollars per
+ * million tokens. The Gemini API reports no cost. gemini-3.8-flash rises to $1.50 input and $7.50
+ * output on 2027-01-01. Cached input is one rate here, so gemini-3.1-flash-lite's cached audio
+ * ($0.05) is billed at its cached text rate. Gemma, gemini-3.7-flash and gemini-3.5-flash list no paid price;
+ * gemini-2.5-flash-image's output is all image, $30 per million tokens.
+ */
+const live = {
+    input: 0.75,
+    output: 4.5,
+    byModality: { input: { audio: 3, image: 1, video: 1 }, output: { audio: 12 } },
+};
+/** What the Gemini API charges per model. */
+export const geminiPrices = {
+    checked: '2026-10-15',
+    models: {
+        'gemini-3.8-flash': { input: 0.75, output: 3.75, cachedInput: 0.075 },
+        'gemini-3.6-flash': { input: 0.75, output: 3.75, cachedInput: 0.075 },
+        'gemini-3.8-live': live,
+        'gemini-3.8-live-extended-thinking': live,
+        'gemini-3.1-flash-live-preview': live,
+        'gemini-3.5-flash-lite': { input: 0.3, output: 2.5, cachedInput: 0.03 },
+        'gemini-3.1-flash-lite': {
+            input: 0.25,
+            output: 1.5,
+            cachedInput: 0.025,
+            byModality: { input: { audio: 0.5 } },
+        },
+        'gemini-3.1-pro-preview': {
+            input: 2,
+            output: 12,
+            cachedInput: 0.2,
+            longContext: { above: 200_000, input: 4, output: 18, cachedInput: 0.4 },
+        },
+        'gemini-3.1-flash-lite-image': {
+            input: 0.25,
+            output: 1.5,
+            byModality: { output: { image: 30 } },
+        },
+        'gemini-3.8-flash-tts': { input: 0.5, output: 9 },
+        'gemini-3.8-flash-lite-tts': { input: 0.5, output: 6 },
+        'gemini-3.1-flash-tts-preview': { input: 1, output: 20 },
+        'gemini-3-flash-preview': {
+            input: 0.5,
+            output: 3,
+            cachedInput: 0.05,
+            byModality: { input: { audio: 1 } },
+        },
+        'gemini-2.5-flash': {
+            input: 0.3,
+            output: 2.5,
+            cachedInput: 0.03,
+            byModality: { input: { audio: 1 } },
+        },
+        'gemini-2.5-flash-lite': {
+            input: 0.1,
+            output: 0.4,
+            cachedInput: 0.01,
+            byModality: { input: { audio: 0.3 } },
+        },
+        'gemini-2.5-flash-preview-tts': { input: 0.5, output: 10 },
+        'gemini-2.5-flash-image': { input: 0.3, output: 30 },
+    },
+};

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

@@ -0,0 +1,7 @@
+import { type Provider } from '../../kernel/protocols/provider.js';
+/** What registering `geminiProvider` takes as `connection`. */
+export interface GeminiConnection {
+    host?: string;
+}
+/** Gemini: Google's models with an API key. Text, images, and speech, and Live voice. */
+export declare const geminiProvider: Provider<GeminiConnection, string>;

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

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { labelText } from '../../guardrails/labels.js';
+import { defineProvider, endpointUrlSchema, header, query, } from '../../kernel/protocols/provider.js';
+import { geminiEmbedding } from './embedding-protocol.js';
+import { geminiInteractions } from './interactions-protocol.js';
+import { geminiLive } from './live-protocol.js';
+import { geminiPrices } from './prices.js';
+/** Gemini: Google's models with an API key. Text, images, and speech, and Live voice. */
+export const geminiProvider = defineProvider({
+    id: 'gemini',
+    name: 'Gemini',
+    description: "Google's models with an API key, from Google AI Studio.", // labels-exempt: builder field description, read by the studio and docs
+    traceName: 'gcp.gemini',
+    connection: z
+        .strictObject({
+        host: endpointUrlSchema
+            .refine((value) => {
+            const url = new URL(value);
+            return url.pathname === '/' && !url.search && !url.hash;
+        }, labelText('protocol.endpoint_host'))
+            .optional()
+            .describe('The API host, by default https://generativelanguage.googleapis.com. Live connects to the same host over wss.'),
+    })
+        .default({}),
+    key: z.string().trim().min(1),
+    authorize: header('x-goog-api-key'),
+    prices: geminiPrices,
+    serves(at) {
+        const host = new URL(at.host ?? 'https://generativelanguage.googleapis.com');
+        const origin = host.origin;
+        const liveOrigin = `${host.protocol === 'http:' ? 'ws:' : 'wss:'}//${host.host}`;
+        return [
+            { protocol: geminiInteractions, baseUrl: `${origin}/v1beta` },
+            { protocol: geminiEmbedding, baseUrl: `${origin}/v1beta` },
+            // probed 2026-09-23: Live's WebSocket takes the key only in the URL's query.
+            { protocol: geminiLive, baseUrl: `${liveOrigin}/ws`, authorize: query('key') },
+        ];
+    },
+});

package/esm/src/providers/google/api-error.d.ts

@@ -0,0 +1,8 @@
+import { TheoremError } from '../../guardrails/error.js';
+/**
+ * Interactions (SSE `error` rows, non-OK bodies) and Live (error frames) both send
+ * `{ error: { code, message, status } }`; `code` is an HTTP status or a named code.
+ */
+export declare function readGeminiApiError(record: Record<string, unknown>): TheoremError | null;
+/** The kind is the HTTP status's, unless the body names a refused key. */
+export declare function readNonOkError(response: Response): Promise<TheoremError>;

package/esm/src/providers/google/api-error.js

@@ -0,0 +1,123 @@
+import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
+import { asRecord } from '../../kernel/engine/record.js';
+const HTTP_STATUS_MIN = 100;
+const HTTP_STATUS_MAX = 599;
+/**
+ * Google refuses a bad key as a 400 `INVALID_ARGUMENT`, so the status reads as
+ * a request THEOREM cannot make; the `ErrorInfo` reason is what says it is the
+ * key. An expired key carries the same reason.
+ */
+const AUTH_REASONS = new Set(['API_KEY_INVALID']);
+/** Whether an error's `details` name a key Google refused. */
+function refusesKey(details) {
+    return (Array.isArray(details) &&
+        details.some((detail) => {
+            const reason = asRecord(detail)?.reason;
+            return typeof reason === 'string' && AUTH_REASONS.has(reason);
+        }));
+}
+/**
+ * The HTTP status behind each named code Google puts on an Interactions error
+ * (https://ai.google.dev/gemini-api/docs/api-errors). A code it does not list
+ * is the snake_case name of the HTTP status, so those names are here too.
+ */
+const NAMED_CODE_STATUS = {
+    invalid_request: 400,
+    failed_precondition: 400,
+    parameter_unknown: 400,
+    authentication: 401,
+    payment_required: 402,
+    permission_denied: 403,
+    not_found: 404,
+    model_not_found: 404,
+    already_exists: 409,
+    aborted: 409,
+    out_of_range: 416,
+    rate_limit_exceeded: 429,
+    quota_exceeded: 429,
+    too_many_requests: 429,
+    api_error: 500,
+    unimplemented: 501,
+    service_unavailable: 503,
+    deadline_exceeded: 504,
+    bad_request: 400,
+    unauthorized: 401,
+    forbidden: 403,
+    method_not_allowed: 405,
+    request_timeout: 408,
+    conflict: 409,
+    payload_too_large: 413,
+    unprocessable_entity: 422,
+    internal_server_error: 500,
+    not_implemented: 501,
+    bad_gateway: 502,
+    gateway_timeout: 504,
+};
+/** Codes for a generation Google's safety filters held back. */
+const BLOCKED_CODES = new Set([
+    'safety',
+    'recitation',
+    'language',
+    'prohibited_content',
+    'spii',
+    'blocklist',
+    'image_safety',
+    'image_prohibited_content',
+    'image_recitation',
+    'image_other',
+    'content_blocked',
+]);
+/**
+ * `cancelled` (499) is the request stopped on THEOREM's side. Generation error
+ * codes (`malformed_function_call`, `no_image`, …) and any code Google adds later
+ * are `bad_response`.
+ */
+function kindOfNamedCode(code) {
+    if (code === 'cancelled')
+        return 'cancelled';
+    if (BLOCKED_CODES.has(code))
+        return 'safety';
+    const status = NAMED_CODE_STATUS[code];
+    return status === undefined ? 'bad_response' : kindOfHttpStatus(status);
+}
+/**
+ * Interactions (SSE `error` rows, non-OK bodies) and Live (error frames) both send
+ * `{ error: { code, message, status } }`; `code` is an HTTP status or a named code.
+ */
+export function readGeminiApiError(record) {
+    const error = asRecord(record.error);
+    if (!error) {
+        return null;
+    }
+    const { code, message, status, details } = error;
+    const kind = refusesKey(details)
+        ? 'auth'
+        : typeof code === 'number' && code >= HTTP_STATUS_MIN && code <= HTTP_STATUS_MAX
+            ? kindOfHttpStatus(code)
+            : typeof code === 'string'
+                ? kindOfNamedCode(code)
+                : 'bad_response';
+    if (typeof message !== 'string' || message.length === 0) {
+        return new TheoremError(kind, 'Gemini returned an error.');
+    }
+    return new TheoremError(kind, typeof status === 'string' ? `${status}: ${message}` : message);
+}
+/** The kind is the HTTP status's, unless the body names a refused key. */
+export async function readNonOkError(response) {
+    const kind = kindOfHttpStatus(response.status);
+    const text = await response.text().catch(() => '');
+    if (!text.trim()) {
+        return new TheoremError(kind, `HTTP ${response.status}`);
+    }
+    const parsed = parseRecord(text);
+    const stated = parsed ? readGeminiApiError(parsed) : null;
+    return new TheoremError(stated?.kind === 'auth' ? 'auth' : kind, stated?.message ?? `Gemini HTTP ${response.status}: ${text}`);
+}
+function parseRecord(text) {
+    try {
+        return asRecord(JSON.parse(text));
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * The tools Gemini runs itself, and how each is sent on Interactions and on Live, with what it
+ * takes from a request's `builtInArgs`.
+ *
+ * @module
+ */
+import type { ProviderBuiltin } from '../../kernel/types.js';
+/** The request's builtins that are Google's own tools; the wire takes no others. */
+declare function googleBuiltins<B extends ProviderBuiltin>(builtins: readonly B[]): B[];
+/** One builtin as an Interactions `tools` entry. */
+declare function interactionsBuiltinTool(builtin: ProviderBuiltin): Record<string, unknown>;
+/** One builtin as a Live setup `tools` entry. Live takes no args for any of them. */
+declare function liveBuiltinTool(builtin: ProviderBuiltin): Record<string, unknown>;
+export { googleBuiltins, interactionsBuiltinTool, liveBuiltinTool };

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

@@ -0,0 +1,57 @@
+/**
+ * The tools Gemini runs itself, and how each is sent on Interactions and on Live, with what it
+ * takes from a request's `builtInArgs`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+const googleMapsArgs = z.strictObject({
+    /** Where Maps grounding searches around. */
+    location: z.strictObject({
+        latitude: z.number().min(-90).max(90),
+        longitude: z.number().min(-180).max(180),
+    }),
+});
+const GOOGLE_BUILTIN_IDS = [
+    'googleSearch',
+    'googleMaps',
+    'urlContext',
+    'codeExecution',
+];
+const INTERACTIONS_TYPE = {
+    googleSearch: 'google_search',
+    googleMaps: 'google_maps',
+    urlContext: 'url_context',
+    codeExecution: 'code_execution',
+};
+/** The request's builtins that are Google's own tools; the wire takes no others. */
+function googleBuiltins(builtins) {
+    return builtins.filter((builtin) => GOOGLE_BUILTIN_IDS.includes(builtin.id));
+}
+function googleBuiltinId(builtin) {
+    const id = GOOGLE_BUILTIN_IDS.find((known) => known === builtin.id);
+    if (!id) {
+        throw new TheoremError('config', `Builtin '${builtin.id}' is not a Google tool`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return id;
+}
+/** One builtin as an Interactions `tools` entry. */
+function interactionsBuiltinTool(builtin) {
+    const id = googleBuiltinId(builtin);
+    const type = INTERACTIONS_TYPE[id];
+    if (id === 'googleMaps' && builtin.args) {
+        const { location } = googleMapsArgs.parse(builtin.args);
+        return { type, latitude: location.latitude, longitude: location.longitude };
+    }
+    return { type };
+}
+/** One builtin as a Live setup `tools` entry. Live takes no args for any of them. */
+function liveBuiltinTool(builtin) {
+    const id = googleBuiltinId(builtin);
+    if (builtin.args) {
+        throw new TheoremError('unsupported', `Builtin '${id}' takes no args on Google Live`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return { [id]: {} };
+}
+export { googleBuiltins, interactionsBuiltinTool, liveBuiltinTool };

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

@@ -0,0 +1,5 @@
+import type { ModelEvent } from '../../kernel/types.js';
+declare function groundingFromDelta(event: Record<string, unknown>): ModelEvent[];
+declare function groundingFromSteps(steps: unknown[]): ModelEvent[];
+declare function groundingFromLiveMetadata(value: unknown): ModelEvent[];
+export { groundingFromDelta, groundingFromLiveMetadata, groundingFromSteps };