@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { defineProtocol, modelOptions } from '../../kernel/protocols/mod.js';
+function task(value, title, description) {
+    return z.literal(value).meta({ title, description });
+}
+const options = z.strictObject({
+    // why: Labels and descriptions are Google's own task-type table (ai.google.dev/gemini-api/docs/embeddings), so a studio can show them.
+    taskType: z
+        .union([
+        task('RETRIEVAL_QUERY', 'Retrieval query', 'Embeddings optimized for general search queries. Pair with Retrieval document for the documents searched.'),
+        task('RETRIEVAL_DOCUMENT', 'Retrieval document', 'Embeddings optimized for document search, such as indexing articles, books or web pages.'),
+        task('SEMANTIC_SIMILARITY', 'Semantic similarity', 'Embeddings optimized to assess text similarity, such as for recommendations or duplicate detection.'),
+        task('CLASSIFICATION', 'Classification', 'Embeddings optimized to classify texts according to preset labels, such as sentiment or spam.'),
+        task('CLUSTERING', 'Clustering', 'Embeddings optimized to cluster texts based on their similarities.'),
+        task('QUESTION_ANSWERING', 'Question answering', 'Embeddings for questions, optimized for finding documents that answer them. Pair with Retrieval document.'),
+        task('FACT_VERIFICATION', 'Fact verification', 'Embeddings for statements to verify, optimized for retrieving evidence that supports or refutes them. Pair with Retrieval document.'),
+        task('CODE_RETRIEVAL_QUERY', 'Code retrieval query', 'Embeddings optimized for finding code blocks from natural language queries. Pair with Retrieval document for the code.'),
+    ])
+        .optional()
+        .describe("What the vectors will be used for, so Google tunes them to it. Only gemini-embedding-001 takes it; later models read the request's task from the text. Absent: no tuning."),
+    outputDimensionality: z
+        .union([z.literal(768), z.literal(1536), z.literal(3072)])
+        .optional()
+        .describe('How many numbers each vector holds. A shorter vector is cheaper to store and compare and a little less precise. Absent: the 3072 the model returns.'),
+});
+/** Models that take the task as `taskType`. Later ones (Gemini Embedding 2 on) refuse the field and read the task from the text. */
+const TASK_FIELD_MODELS = /^(gemini-embedding-001|text-embedding-|embedding-)/;
+// why: ai.google.dev/gemini-api/docs/embeddings gives 6 images and 1 PDF per input, and duration caps (not counts) for audio and video; a batch of 101 inputs is refused (checked 2026-10-19).
+const MULTIMODAL = {
+    maxInputs: 100,
+    media: [
+        { accept: ['image/png', 'image/jpeg'], maxPerInput: 6 },
+        { accept: ['application/pdf'], maxPerInput: 1 },
+        { accept: ['audio/mpeg', 'audio/mp3', 'audio/wav', 'audio/x-wav'] },
+        { accept: ['video/mp4', 'video/quicktime'] },
+    ],
+};
+const TEXT_ONLY = { maxInputs: 100, media: [] };
+const TASK_TYPES = {
+    query: 'RETRIEVAL_QUERY',
+    document: 'RETRIEVAL_DOCUMENT',
+};
+// why: The formats Google gives for Gemini Embedding 2 search (ai.google.dev/gemini-api/docs/embeddings); it advises leaving input with media unprefixed.
+function withTask(text, task) {
+    return task === 'query' ? `task: search result | query: ${text}` : `title: none | text: ${text}`;
+}
+function parts(input, task) {
+    const list = typeof input === 'string' ? [{ type: 'text', text: input }] : input.parts;
+    const textOnly = list.every((part) => part.type === 'text');
+    return list.map((part, at) => {
+        if (part.type === 'text')
+            return { text: task && textOnly && at === 0 ? withTask(part.text, task) : part.text };
+        if (part.type === 'media') {
+            return { inlineData: { mimeType: part.mimeType, data: part.data } };
+        }
+        return { fileData: { mimeType: part.mimeType, fileUri: part.uri } };
+    });
+}
+function values(row) {
+    const embedding = row.embedding;
+    const values = embedding && typeof embedding === 'object'
+        ? embedding.values
+        : undefined;
+    return Array.isArray(values)
+        ? values.filter((value) => typeof value === 'number')
+        : [];
+}
+function requestBody(input, parsed, shape) {
+    const body = {
+        content: { parts: parts(input, shape.taskField ? undefined : shape.task) },
+    };
+    const taskType = shape.taskField && shape.task ? TASK_TYPES[shape.task] : parsed.taskType;
+    if (taskType)
+        body.taskType = taskType;
+    if (parsed.outputDimensionality)
+        body.outputDimensionality = parsed.outputDimensionality;
+    return body;
+}
+export const geminiEmbedding = defineProtocol({
+    id: 'geminiEmbedding',
+    name: 'Gemini Embeddings',
+    description: "Google's embedding API for text and supported media.",
+    endpoints: { embedding: '/models/{apiId}:embedContent' },
+    options,
+    embeddingLimits: (apiId) => (TASK_FIELD_MODELS.test(apiId) ? TEXT_ONLY : MULTIMODAL),
+    // why: Gemini Embedding 2 reads the task from the text and refuses the field; the request's `task` says it.
+    refusedOptions: (apiId) => (TASK_FIELD_MODELS.test(apiId) ? [] : ['taskType']),
+    create(context) {
+        return {
+            async embed(request) {
+                const parsed = modelOptions(geminiEmbedding, context.apiId, request.options);
+                const taskField = TASK_FIELD_MODELS.test(context.apiId);
+                const shape = { taskField, ...(request.task ? { task: request.task } : {}) };
+                const inputs = Array.isArray(request.input) ? request.input : [request.input];
+                const body = inputs.length === 1
+                    ? requestBody(inputs[0], parsed, shape)
+                    : {
+                        requests: inputs.map((input) => ({
+                            model: `models/${context.apiId}`,
+                            ...requestBody(input, parsed, shape),
+                        })),
+                    };
+                const path = inputs.length === 1
+                    ? `/models/${encodeURIComponent(context.apiId)}:embedContent`
+                    : `/models/${encodeURIComponent(context.apiId)}:batchEmbedContents`;
+                let row;
+                for await (const current of context.send(body, { stream: false, path }))
+                    row = current;
+                const raw = Array.isArray(row?.embeddings)
+                    ? row.embeddings
+                    : row?.embedding
+                        ? [row.embedding]
+                        : [];
+                return {
+                    model: context.apiId,
+                    embeddings: raw.map((item, index) => ({
+                        index,
+                        values: item && typeof item === 'object' ? values({ embedding: item }) : [],
+                        dimensions: item && typeof item === 'object' ? values({ embedding: item }).length : 0,
+                    })),
+                };
+            },
+        };
+    },
+});

package/esm/src/providers/gemini/interactions-protocol.d.ts

@@ -0,0 +1,8 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** What a `geminiInteractions` binding sets in `options`. */
+export interface GeminiInteractionsOptions {
+    store?: boolean;
+    persistViaInteractionId?: boolean;
+}
+/** Gemini's Interactions API: text, images, and speech, all at `/interactions`. */
+export declare const geminiInteractions: Protocol<GeminiInteractionsOptions>;

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

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { asRecord } from '../../kernel/engine/record.js';
+import { jsonObjectSchema } from '../../kernel/json.js';
+import { defineProtocol, } from '../../kernel/protocols/mod.js';
+import { readGeminiApiError, statedOrStatusError } from '../google/api-error.js';
+import { googleBuiltins } from '../google/builtins.js';
+import { thoughtSignature, toInteractionsBody, } from '../google/interactions/framing.js';
+import { finalizeStructured, foldBody, foldPayload, missingMediaError, newStreamFold, openStepEvents, } from '../google/interactions/stream.js';
+import { asProtocolEvent } from '../shared/protocol-events.js';
+const state = z.strictObject({ interactionId: z.string().min(1) });
+const options = z
+    .strictObject({
+    store: z
+        .boolean()
+        .optional()
+        .describe('Whether Google keeps the interaction. Off, nothing is stored server-side.'), // labels-exempt: builder field description, read by the studio and docs
+    persistViaInteractionId: z.boolean().optional().describe('Continue from the stored interaction instead of sending the conversation again. Needs store.'),
+})
+    .refine((value) => !value.persistViaInteractionId || value.store !== false, 'persistViaInteractionId needs store');
+function wireRequest(context, request) {
+    const history = request.history ?? [];
+    const previous = context.options.persistViaInteractionId
+        ? request.state?.interactionId
+        : undefined;
+    const builtins = googleBuiltins(request.builtins);
+    const wire = {
+        ...request,
+        apiId: context.apiId,
+        history,
+        builtins,
+        state: undefined,
+        tapUpstream: undefined,
+        store: context.options.store,
+        previousInteractionId: previous,
+        continuation: previous
+            ? [
+                ...history.slice(request.stateHistoryLength ?? 0),
+                ...request.input.map((part) => ({ role: 'user', parts: [part] })),
+            ]
+            : undefined,
+    };
+    const body = jsonObjectSchema.parse(JSON.parse(JSON.stringify(toInteractionsBody(wire))));
+    return { wire, body, wroteTools: builtins.map((builtin) => builtin.id) };
+}
+/** The shared reader's events as protocol events; the `done` waits for the end, with the state to keep. */
+function asProtocolEvents(events, reply, persist) {
+    return events.flatMap((event) => {
+        if (event.type !== 'done') {
+            const converted = asProtocolEvent(event);
+            return converted ? [converted] : [];
+        }
+        const { interactionId, ...done } = event;
+        reply.done = {
+            ...done,
+            ...(persist && interactionId ? { state: { interactionId } } : {}),
+        };
+        return [];
+    });
+}
+/** Gemini's Interactions API: text, images, and speech, all at `/interactions`. */
+export const geminiInteractions = defineProtocol({
+    id: 'geminiInteractions',
+    name: 'Gemini Interactions',
+    description: "Google's Interactions API for Gemini: text, images and speech at one endpoint.", // labels-exempt: builder field description, read by the studio and docs
+    endpoints: { text: '/interactions', image: '/interactions', speech: '/interactions' },
+    options,
+    continuation: { version: 1, schema: state, keyOptions: ['store', 'persistViaInteractionId'] },
+    reasoning: thoughtSignature,
+    error(failure) {
+        const record = asRecord(failure.body);
+        return statedOrStatusError(record ? readGeminiApiError(record) : null, failure.status, `Gemini HTTP ${failure.status}`);
+    },
+    create(context) {
+        return {
+            async *complete(request) {
+                const { wire, body, wroteTools } = wireRequest(context, request);
+                const stream = request.stream !== false;
+                const persist = Boolean(context.options.persistViaInteractionId);
+                const reply = { fold: newStreamFold() };
+                const init = { stream, wroteTools, ...(stream ? { path: '/interactions?alt=sse' } : {}) };
+                for await (const row of context.send(body, init)) {
+                    // why: an error row before any output is thrown, so the kernel can fall back to the other key.
+                    const failed = readGeminiApiError(row);
+                    if (failed)
+                        throw failed;
+                    const events = stream ? foldPayload(row, reply.fold) : foldBody(row, reply.fold);
+                    yield* asProtocolEvents(events, reply, persist);
+                    if (events.some((event) => event.type === 'error')) {
+                        yield* asProtocolEvents(openStepEvents(reply.fold), reply, persist);
+                        return;
+                    }
+                }
+                yield* asProtocolEvents(openStepEvents(reply.fold), reply, persist);
+                yield* asProtocolEvents([...finalizeStructured(wire, reply.fold)], reply, persist);
+                const missing = missingMediaError(wire, reply.fold);
+                if (missing)
+                    yield* asProtocolEvents([missing], reply, persist);
+                yield reply.done ?? { type: 'done', stop: { kind: 'stream_incomplete' } };
+            },
+        };
+    },
+});

package/esm/src/providers/gemini/live-protocol.d.ts

@@ -0,0 +1,3 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** Gemini Live: a spoken session over one WebSocket. */
+export declare const geminiLive: Protocol<Record<string, never>>;

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

@@ -6,3 +6,5 @@ import { TheoremError } from '../../guardrails/error.js';
 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>;
+/** A non-OK reply's error: the body's own when it names a refused key, else the status's with the body's message. */
+export declare function statedOrStatusError(stated: TheoremError | null, status: number, fallback: string): TheoremError;

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

@@ -72,13 +72,15 @@ const BLOCKED_CODES = new Set([
  * codes (`malformed_function_call`, `no_image`, …) and any code Google adds later
  * are `bad_response`.
  */
-function kindOfNamedCode(code) {
+function namedCodeError(code, message) {
     if (code === 'cancelled')
-        return 'cancelled';
+        return new TheoremError('cancelled', message);
     if (BLOCKED_CODES.has(code))
-        return 'safety';
+        return new TheoremError('safety', message);
     const status = NAMED_CODE_STATUS[code];
-    return status === undefined ? 'bad_response' : kindOfHttpStatus(status);
+    return status === undefined
+        ? new TheoremError('bad_response', message)
+        : new TheoremError(kindOfHttpStatus(status), message);
 }
 /**
  * Interactions (SSE `error` rows, non-OK bodies) and Live (error frames) both send
@@ -90,28 +92,34 @@ export function readGeminiApiError(record) {
         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.');
+    const text = typeof message !== 'string' || message.length === 0
+        ? 'Gemini returned an error.'
+        : typeof status === 'string'
+            ? `${status}: ${message}`
+            : message;
+    if (refusesKey(details))
+        return new TheoremError('auth', text);
+    if (typeof code === 'number' && code >= HTTP_STATUS_MIN && code <= HTTP_STATUS_MAX) {
+        return new TheoremError(kindOfHttpStatus(code), text);
     }
-    return new TheoremError(kind, typeof status === 'string' ? `${status}: ${message}` : message);
+    return typeof code === 'string'
+        ? namedCodeError(code, text)
+        : new TheoremError('bad_response', text);
 }
 /** 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}`);
+        return new TheoremError(kindOfHttpStatus(response.status), `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}`);
+    return statedOrStatusError(parsed ? readGeminiApiError(parsed) : null, response.status, `Gemini HTTP ${response.status}: ${text}`);
+}
+/** A non-OK reply's error: the body's own when it names a refused key, else the status's with the body's message. */
+export function statedOrStatusError(stated, status, fallback) {
+    if (stated?.kind === 'auth')
+        return stated;
+    return new TheoremError(kindOfHttpStatus(status), stated?.message ?? fallback);
 }
 function parseRecord(text) {
     try {

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 };