@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/presets/google.js

@@ -0,0 +1,197 @@
+/**
+ * Google / Gemini convenience preset.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { registerTools } from '../kernel/default-scope.js';
+import { GOOGLE_SPEECH_VOICES } from './google/speech-voices.js';
+import { GOOGLE_SPEECH_FORMATS, GOOGLE_THINKING_LEVELS, googleEfforts, } from './google-limits.js';
+/** The image MIME types a Gemini profile can take as input. */
+const GOOGLE_IMAGE_INPUT_MIMES = [
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/heic',
+    'image/heif',
+];
+/** The audio MIME types a Gemini profile can take as voice input. */
+const GOOGLE_VOICE_INPUT_MIMES = ['audio/webm', 'audio/wav', 'audio/mpeg', 'audio/mp4'];
+/**
+ * TTS models that reject any history with a model turn, so compaction's summary fails them
+ * (live, 29/09/2026).
+ */
+const GOOGLE_SINGLE_TURN_API_IDS = [
+    'gemini-2.5-flash-preview-tts',
+    'gemini-3.1-flash-tts-preview',
+    'gemini-3.8-flash-tts',
+    'gemini-3.8-flash-lite-tts',
+];
+/**
+ * Models that reject any thinking setting, `summaries: false` included: leave
+ * `efforts` and `summaries` unset (live, 30/09/2026).
+ */
+const GOOGLE_NO_THINKING_API_IDS = [
+    'gemini-2.5-flash-image',
+    'antigravity-preview-05-2026',
+    'antigravity-preview-09-2026',
+    'antigravity-preview-latest',
+];
+/**
+ * Models that refuse a thinking level and take `summaries`: leave `efforts` unset
+ * (live, 01/10/2026: Live closes 1007 "Thinking level is not supported for this model";
+ * 04/10/2026: setup takes `includeThoughts` either way).
+ */
+const GOOGLE_NO_EFFORT_API_IDS = ['gemini-3.8-live'];
+/**
+ * Models that refuse a session without a thinking level: pin `efforts`
+ * (live, 01/10/2026: Live closes 1007 "Thinking level must be specified for this model").
+ */
+const GOOGLE_THINKING_REQUIRED_API_IDS = ['gemini-3.8-live-extended-thinking'];
+const grounding = (googleSearch, googleMaps) => ({
+    googleSearch,
+    googleMaps,
+});
+/**
+ * Models with a non-zero free-tier quota, and the grounding each allows (AI Studio, Sep 2026).
+ * No model keeps free Maps quota: 3.5 Flash-Lite turns with Maps are refused as over quota
+ * (live, 13/10/2026).
+ * A builtin with no quota is refused as if over quota: on Live, a close 1011 "You exceeded your
+ * current quota" at setup, whatever the key's usage (live, 01/10/2026).
+ */
+const GOOGLE_FREE_TIER_GROUNDING = {
+    'gemini-2.5-flash-lite': grounding(true, false),
+    'gemini-2.5-flash': grounding(true, false),
+    'gemini-2.5-flash-preview-tts': grounding(true, false),
+    'gemini-3-flash-preview': grounding(false, false),
+    'gemini-3.1-flash-lite': grounding(false, false),
+    'gemini-3.1-flash-lite-image': grounding(false, false),
+    'gemini-3.1-flash-tts-preview': grounding(false, false),
+    'gemini-3.5-flash-lite': grounding(false, false),
+    'gemini-3.5-flash': grounding(false, false),
+    'gemini-3.6-flash': grounding(false, false),
+    'gemini-3.7-flash': grounding(false, false),
+    'gemini-3.8-flash-tts': grounding(false, false),
+    'gemini-3.8-flash-lite-tts': grounding(false, false),
+    'gemma-4-26b-a4b-it': grounding(false, false),
+    'gemma-4-31b-it': grounding(false, false),
+    'gemini-3.1-flash-live-preview': grounding(false, false),
+    'gemini-3.8-live': grounding(false, false),
+    'gemini-3.8-live-extended-thinking': grounding(false, false),
+};
+/** Grounding builtins the free tier allows on `apiId`; none for a model with no free quota. */
+function googleFreeTierBuiltins(apiId) {
+    const allowed = GOOGLE_FREE_TIER_GROUNDING[apiId.trim()];
+    if (!allowed)
+        return [];
+    return ['googleSearch', 'googleMaps'].filter((id) => allowed[id]);
+}
+function pinsEffort(binding) {
+    return Object.keys(binding.efforts ?? {}).length > 0;
+}
+/**
+ * The first setting Google would refuse on this binding, or `undefined`. With `freeTier`, it
+ * also holds the binding to the free-tier table: a listed model, and only the grounding its
+ * quota allows.
+ */
+function googleBindingViolation(binding, options = {}) {
+    const apiId = binding.apiId.trim();
+    const noThinking = GOOGLE_NO_THINKING_API_IDS;
+    const noEffort = GOOGLE_NO_EFFORT_API_IDS;
+    const thinkingRequired = GOOGLE_THINKING_REQUIRED_API_IDS;
+    if ((noThinking.includes(apiId) || noEffort.includes(apiId)) && pinsEffort(binding)) {
+        return {
+            field: 'efforts',
+            message: `${apiId} takes no thinking level; leave efforts unset.`,
+        };
+    }
+    if (noThinking.includes(apiId) && binding.summaries !== undefined) {
+        return {
+            field: 'summaries',
+            message: `${apiId} takes no thinking setting; leave summaries unset.`,
+        };
+    }
+    if (thinkingRequired.includes(apiId) && !pinsEffort(binding)) {
+        return { field: 'efforts', message: `${apiId} needs a thinking level; pin efforts.` };
+    }
+    if (!options.freeTier)
+        return undefined;
+    if (!GOOGLE_FREE_TIER_GROUNDING[apiId]) {
+        return { field: 'apiId', message: `${apiId} has no free-tier quota.` };
+    }
+    const allowed = googleFreeTierBuiltins(apiId);
+    for (const builtin of binding.builtInTools ?? []) {
+        if ((builtin === 'googleSearch' || builtin === 'googleMaps') && !allowed.includes(builtin)) {
+            return { field: 'builtInTools', message: `${apiId} has no free-tier quota for ${builtin}.` };
+        }
+    }
+    return undefined;
+}
+/** The aspect ratios a Gemini image model can return. */
+const GOOGLE_IMAGE_ASPECT_RATIOS = [
+    '1:1',
+    '3:2',
+    '2:3',
+    '3:4',
+    '4:3',
+    '4:5',
+    '5:4',
+    '9:16',
+    '16:9',
+    '21:9',
+];
+/** The resolutions a Gemini image model can return. */
+const GOOGLE_IMAGE_RESOLUTIONS = ['1K', '2K', '4K'];
+/** What a Gemini image model can be asked to return. */
+const GOOGLE_IMAGE_OUTPUT_MIMES = ['image/png', 'image/jpeg'];
+/** The tools Gemini runs itself, as `builtin` tool definitions. */
+const GOOGLE_BUILTIN_TOOLS = [
+    {
+        type: 'builtin',
+        name: 'googleSearch',
+        description: 'Google Search grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+    },
+    {
+        type: 'builtin',
+        name: 'googleMaps',
+        description: 'Google Maps grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        // why: Google refuses a request that carries Maps with Search or URL context.
+        conflictsWith: ['googleSearch', 'urlContext'],
+    },
+    {
+        type: 'builtin',
+        name: 'urlContext',
+        description: 'Fetch URL context',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+    },
+    {
+        type: 'builtin',
+        name: 'codeExecution',
+        description: 'Google code execution',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+    },
+];
+/** Registers into the default scope; a scope of its own takes `GOOGLE_BUILTIN_TOOLS`. */
+function registerGooglePreset() {
+    registerTools(GOOGLE_BUILTIN_TOOLS);
+}
+export { GEMINI_MODELS_URL } from '../providers/google/urls.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_EFFORT_API_IDS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, };

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

@@ -0,0 +1,26 @@
+/**
+ * Local model convenience preset.
+ *
+ * @module
+ */
+import type { ModelBinding } from '../kernel/types.js';
+/**
+ * Whether an Ollama model thinks, read from the server's `POST /api/show` reply for it:
+ * `capabilities` lists `thinking` (Ollama 0.34.0, 04/10/2026). The host fetches the reply.
+ */
+declare function ollamaModelThinks(show: unknown): boolean;
+/** A local binding field its model would refuse, and what is wrong with it. */
+interface LocalBindingViolation {
+    field: 'efforts';
+    message: string;
+}
+/**
+ * The first setting a local server would refuse on this binding, or `undefined`. A thinking
+ * level goes to the server as `reasoning_effort`; Ollama answers HTTP 400 "does not support
+ * thinking" for a model that does not think (04/10/2026).
+ */
+declare function localBindingViolation(binding: Pick<ModelBinding, 'apiId' | 'efforts'>, model: {
+    thinks: boolean;
+}): LocalBindingViolation | undefined;
+export type { LocalBindingViolation };
+export { localBindingViolation, ollamaModelThinks };

package/esm/src/presets/local.js

@@ -0,0 +1,30 @@
+/**
+ * Local model convenience preset.
+ *
+ * @module
+ */
+/**
+ * Whether an Ollama model thinks, read from the server's `POST /api/show` reply for it:
+ * `capabilities` lists `thinking` (Ollama 0.34.0, 04/10/2026). The host fetches the reply.
+ */
+function ollamaModelThinks(show) {
+    if (!show || typeof show !== 'object')
+        return false;
+    const { capabilities } = show;
+    return Array.isArray(capabilities) && capabilities.includes('thinking');
+}
+/**
+ * The first setting a local server would refuse on this binding, or `undefined`. A thinking
+ * level goes to the server as `reasoning_effort`; Ollama answers HTTP 400 "does not support
+ * thinking" for a model that does not think (04/10/2026).
+ */
+function localBindingViolation(binding, model) {
+    if (!model.thinks && Object.keys(binding.efforts ?? {}).length > 0) {
+        return {
+            field: 'efforts',
+            message: `${binding.apiId.trim()} does not think; leave efforts unset.`,
+        };
+    }
+    return undefined;
+}
+export { localBindingViolation, ollamaModelThinks };

package/esm/src/presets/mod.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Host-convenience catalogs for first-party providers: provider builtins and media vocabularies.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { GoogleBindingViolation, GoogleFreeTierGrounding, GoogleImageAspectRatio, GoogleImageInputMime, GoogleImageOutputMime, GoogleImagePins, GoogleImageResolution, GoogleSpeechVoice, GoogleThinkingLevel, GoogleVoiceInputMime, } from './google.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_EFFORT_API_IDS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, } from './google.js';
+export type { LocalBindingViolation } from './local.js';
+export { localBindingViolation, ollamaModelThinks } from './local.js';
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, } from './openrouter.js';

package/esm/src/presets/mod.js

@@ -0,0 +1,9 @@
+/**
+ * Host-convenience catalogs for first-party providers: provider builtins and media vocabularies.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_FREE_TIER_GROUNDING, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_OUTPUT_MIMES, GOOGLE_IMAGE_RESOLUTIONS, GOOGLE_NO_EFFORT_API_IDS, GOOGLE_NO_THINKING_API_IDS, GOOGLE_SINGLE_TURN_API_IDS, GOOGLE_SPEECH_FORMATS, GOOGLE_SPEECH_VOICES, GOOGLE_THINKING_LEVELS, GOOGLE_THINKING_REQUIRED_API_IDS, GOOGLE_VOICE_INPUT_MIMES, googleBindingViolation, googleEfforts, googleFreeTierBuiltins, registerGooglePreset, } from './google.js';
+export { localBindingViolation, ollamaModelThinks } from './local.js';
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, } from './openrouter.js';

package/esm/src/presets/openrouter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OpenRouter convenience preset.
+ *
+ * @module
+ */
+/** `/images` takes image references only; a profile on it lists nothing wider in `inputs.attachments.accept`. */
+declare const OPENROUTER_IMAGES_INPUT_MIMES: readonly ["image/*"];
+/**
+ * What `/images` never sends the model: it reads the prompt text and the reference images
+ * only. The chat path (`image.includeText`) sends the system prompt and history.
+ */
+declare const OPENROUTER_IMAGES_IGNORED_INPUTS: readonly ["system", "history"];
+/** The tools OpenRouter runs itself, as `builtin` tool definitions. */
+declare const OPENROUTER_BUILTIN_TOOLS: {
+    type: "builtin";
+    name: string;
+    description: string;
+    category: string;
+    access: "read-only";
+    paths: string[];
+    loadTier: "T0";
+    permission: "auto";
+}[];
+/** Registers into the default scope; a scope of its own takes `OPENROUTER_BUILTIN_TOOLS`. */
+declare function registerOpenRouterPreset(): void;
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, };

package/esm/src/presets/openrouter.js

@@ -0,0 +1,31 @@
+/**
+ * OpenRouter convenience preset.
+ *
+ * @module
+ */
+import { registerTools } from '../kernel/default-scope.js';
+/** `/images` takes image references only; a profile on it lists nothing wider in `inputs.attachments.accept`. */
+const OPENROUTER_IMAGES_INPUT_MIMES = ['image/*'];
+/**
+ * What `/images` never sends the model: it reads the prompt text and the reference images
+ * only. The chat path (`image.includeText`) sends the system prompt and history.
+ */
+const OPENROUTER_IMAGES_IGNORED_INPUTS = ['system', 'history'];
+/** The tools OpenRouter runs itself, as `builtin` tool definitions. */
+const OPENROUTER_BUILTIN_TOOLS = [
+    {
+        type: 'builtin',
+        name: 'webSearch',
+        description: 'OpenRouter web search',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+    },
+];
+/** Registers into the default scope; a scope of its own takes `OPENROUTER_BUILTIN_TOOLS`. */
+function registerOpenRouterPreset() {
+    registerTools(OPENROUTER_BUILTIN_TOOLS);
+}
+export { OPENROUTER_BUILTIN_TOOLS, OPENROUTER_IMAGES_IGNORED_INPUTS, OPENROUTER_IMAGES_INPUT_MIMES, registerOpenRouterPreset, };

package/esm/src/providers/embedding-limits.d.ts

@@ -0,0 +1,7 @@
+import type { ModelBinding } from '../kernel/protocols/binding.js';
+import type { EmbeddingModelLimits, Protocol } from '../kernel/protocols/protocol.js';
+/**
+ * What a binding's embedding model takes, read from its protocol: one Theorem ships, or one of
+ * `protocols`. Undefined when neither has it, and the kernel then holds requests to the profile alone.
+ */
+export declare function embeddingModelLimits(binding: Pick<ModelBinding, 'protocol' | 'apiId'>, protocols?: readonly Protocol[]): EmbeddingModelLimits | undefined;

package/esm/src/providers/embedding-limits.js

@@ -0,0 +1,12 @@
+import { geminiEmbedding } from './gemini/embedding-protocol.js';
+import { ollamaEmbedding } from './local/embedding-protocol.js';
+import { openRouterEmbedding } from './openrouter/embedding-protocol.js';
+const SHIPPED = [geminiEmbedding, openRouterEmbedding, ollamaEmbedding];
+/**
+ * What a binding's embedding model takes, read from its protocol: one Theorem ships, or one of
+ * `protocols`. Undefined when neither has it, and the kernel then holds requests to the profile alone.
+ */
+export function embeddingModelLimits(binding, protocols = []) {
+    const protocol = [...protocols, ...SHIPPED].find((entry) => entry.id === binding.protocol);
+    return protocol?.embeddingLimits?.(binding.apiId);
+}

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

@@ -0,0 +1,8 @@
+import type { Protocol } from '../../kernel/protocols/protocol.js';
+/** What a `geminiEmbedding` binding sets in `options`. */
+export interface GeminiEmbeddingOptions {
+    /** For `gemini-embedding-001`; Gemini Embedding 2 refuses it and reads the request's `task` from the text. */
+    taskType?: 'RETRIEVAL_QUERY' | 'RETRIEVAL_DOCUMENT' | 'SEMANTIC_SIMILARITY' | 'CLASSIFICATION' | 'CLUSTERING' | 'QUESTION_ANSWERING' | 'FACT_VERIFICATION' | 'CODE_RETRIEVAL_QUERY';
+    outputDimensionality?: 768 | 1536 | 3072;
+}
+export declare const geminiEmbedding: Protocol<GeminiEmbeddingOptions>;

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,105 @@
+import { z } from 'zod';
+import { kindOfHttpStatus, TheoremError } from '../../guardrails/error.js';
+import { asRecord } from '../../kernel/engine/record.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 { 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 kind = kindOfHttpStatus(failure.status);
+        const record = asRecord(failure.body);
+        const stated = record ? readGeminiApiError(record) : null;
+        return new TheoremError(stated?.kind === 'auth' ? 'auth' : kind, stated?.message ?? `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>>;