theorum 0.1.14 → 1.0.0

package/esm/src/presets/google.js

@@ -1,36 +1,11 @@
 /**
  * Google / Gemini convenience preset.
  *
- * Kernel stays open (`string` pins). This pack owns Google vocabularies as
- * real unions so host profiles stay typed when they opt into the preset.
- *
- * Call `registerGooglePreset()` at host startup for tools; use the exported
- * types/constants when authoring image/speech-adjacent profile fields.
- *
  * @module
  */
 import "../../_dnt.polyfills.js";
-import { registerTools } from '../kernel/registry/catalog.js';
-/** Google Interactions / Gemini grounding builtins. */
-const GOOGLE_BUILTIN_TOOLS = {
-    googleSearch: {
-        kind: 'builtin',
-        ui: true,
-        interactionsType: 'google_search',
-        openRouterPlugin: 'web',
-    },
-    googleMaps: {
-        kind: 'builtin',
-        ui: true,
-        interactionsType: 'google_maps',
-        conflictsWith: ['googleSearch', 'urlContext'],
-    },
-    urlContext: {
-        kind: 'builtin',
-        ui: true,
-        interactionsType: 'url_context',
-    },
-};
+import { registerTools } from '../kernel/tools/mod.js';
+import { GOOGLE_SPEECH_VOICES } from './google/speech-voices.js';
 /** Common Gemini image input MIME allowlist. */
 const GOOGLE_IMAGE_INPUT_MIMES = [
     'image/png',
@@ -41,40 +16,6 @@ const GOOGLE_IMAGE_INPUT_MIMES = [
 ];
 /** Common voice/audio input MIME allowlist for Gemini multimodal. */
 const GOOGLE_VOICE_INPUT_MIMES = ['audio/webm', 'audio/wav', 'audio/mpeg', 'audio/mp4'];
-/** Common Gemini TTS voice names for `outputs.speech.voice`. */
-const GOOGLE_SPEECH_VOICES = [
-    'Zephyr',
-    'Puck',
-    'Charon',
-    'Kore',
-    'Fenrir',
-    'Leda',
-    'Orus',
-    'Aoede',
-    'Callirrhoe',
-    'Autonoe',
-    'Enceladus',
-    'Iapetus',
-    'Umbriel',
-    'Algieba',
-    'Despina',
-    'Erinome',
-    'Algenib',
-    'Rasalgethi',
-    'Laomedeia',
-    'Achernar',
-    'Alnilam',
-    'Schedar',
-    'Gacrux',
-    'Pulcherrima',
-    'Achird',
-    'Zubenelgenubi',
-    'Vindemiatrix',
-    'Sadachbia',
-    'Sadaltager',
-    'Sulafat',
-];
-/** Aspect ratios commonly accepted by Gemini image models. */
 const GOOGLE_IMAGE_ASPECT_RATIOS = [
     '1:1',
     '3:2',
@@ -87,9 +28,55 @@ const GOOGLE_IMAGE_ASPECT_RATIOS = [
     '16:9',
     '21:9',
 ];
-/** Image sizes commonly accepted by Gemini Flash Lite image. */
 const GOOGLE_IMAGE_SIZES = ['1K'];
-/** Register Google provider builtins into the process-local tool catalog. */
+const GOOGLE_BUILTIN_TOOLS = [
+    {
+        type: 'builtin',
+        name: 'googleSearch',
+        description: 'Google Search grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        forcePaidKey: true,
+        wire: { interactions: 'google_search', openRouter: 'web' },
+    },
+    {
+        type: 'builtin',
+        name: 'googleMaps',
+        description: 'Google Maps grounding',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'google_maps' },
+    },
+    {
+        type: 'builtin',
+        name: 'urlContext',
+        description: 'Fetch URL context',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'url_context' },
+    },
+    {
+        type: 'builtin',
+        name: 'codeExecution',
+        description: 'Google code execution',
+        category: 'grounding',
+        access: 'read-only',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        wire: { interactions: 'code_execution' },
+    },
+];
+/** Register Google provider builtins into the process-local tool registry. */
 function registerGooglePreset() {
     registerTools(GOOGLE_BUILTIN_TOOLS);
 }

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

@@ -7,5 +7,5 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export type { GoogleImageAspectRatio, GoogleImageInputMime, GoogleImagePins, GoogleImageSize, GoogleVoiceInputMime, } from './google.js';
-export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';
+export type { GoogleImageAspectRatio, GoogleImageInputMime, GoogleImagePins, GoogleImageSize, GoogleSpeechVoice, GoogleVoiceInputMime, } from './google.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_SPEECH_VOICES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';

package/esm/src/presets/mod.js

@@ -7,4 +7,4 @@
  * @module
  */
 import "../../_dnt.polyfills.js";
-export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';
+export { GOOGLE_BUILTIN_TOOLS, GOOGLE_IMAGE_ASPECT_RATIOS, GOOGLE_IMAGE_INPUT_MIMES, GOOGLE_IMAGE_SIZES, GOOGLE_SPEECH_VOICES, GOOGLE_VOICE_INPUT_MIMES, registerGooglePreset, } from './google.js';

package/esm/src/providers/create-provider.d.ts

@@ -2,35 +2,35 @@
  * Host provider factory — the single public door for binding a profile to a transport.
  *
  * Routes from `profile.model.protocol` / `provider` (and whether the profile is
- * a speech role). Adapters under this folder are internal implementation.
+ * a speech or image role). Adapters under this folder are internal implementation.
  *
- * The OpenRouter / Vercel AI SDK stack is loaded only when an `openAi` +
- * `openrouter` chat provider actually runs `complete` — not when this module
- * is imported, and not for Google or local paths.
+ * Every adapter graph is loaded only when that transport's first `complete` runs —
+ * not when this module is imported.
  *
  * @module
  */
 import type { ModelProvider, Profile } from '../kernel/types.js';
-import type { GeminiTransport } from './keys.js';
-import { type LocalProviderConfig } from './local.js';
-import type { OpenRouterConfig } from './openrouter-payload.js';
+import type { GeminiTransport } from './google/keys.js';
+import type { LocalProviderConfig, OpenAiGatewayConfig } from './types.js';
 /** Credentials supplied by the host when creating a provider. */
 export interface CreateProviderOptions {
-    /** Google Interactions (chat, image, and speech when protocol is geminiInteractions). */
+    /** Google Interactions (text, image, and speech when protocol is geminiInteractions). */
     gemini?: GeminiTransport;
     /**
-     * OpenRouter-compatible credentials for `openAi` profiles.
-     * Used for chat completions or `/audio/speech` when the profile is a speech role.
-     * Optional `voice` is a fallback when `outputs.speech.voice` is omitted.
+     * OpenAI-gateway credentials for `openAi` profiles (OpenRouter or compatible).
+     * Used for chat completions, `/images`, or `/audio/speech` depending on output role.
+     * Optional `voice` is a fallback when `speech.voice` is omitted.
      */
-    openRouter?: OpenRouterConfig & {
+    openAiGateway?: OpenAiGatewayConfig & {
         voice?: string;
     };
     /** Local OpenAI-compatible server (Ollama, llama.cpp, vLLM, LM Studio). */
     local?: LocalProviderConfig;
 }
+export declare function isSpeechRole(profile: Profile): boolean;
+export declare function isImageRole(profile: Profile): boolean;
 /**
- * Create a `ModelProvider` for a profile.
- * One call: protocol/provider (and speech role) pick the transport.
+ * Create a `ModelProvider` for a turn-based profile (text / image / speech).
+ * Live profiles use `runSession` — `createProvider` rejects geminiLive.
  */
 export declare function createProvider(profile: Profile, options?: CreateProviderOptions): ModelProvider;

package/esm/src/providers/create-provider.js

@@ -2,59 +2,91 @@
  * Host provider factory — the single public door for binding a profile to a transport.
  *
  * Routes from `profile.model.protocol` / `provider` (and whether the profile is
- * a speech role). Adapters under this folder are internal implementation.
+ * a speech or image role). Adapters under this folder are internal implementation.
  *
- * The OpenRouter / Vercel AI SDK stack is loaded only when an `openAi` +
- * `openrouter` chat provider actually runs `complete` — not when this module
- * is imported, and not for Google or local paths.
+ * Every adapter graph is loaded only when that transport's first `complete` runs —
+ * not when this module is imported.
  *
  * @module
  */
 import { TheorumError } from '../guardrails/error.js';
-import { exposeForTests } from './expose-for-tests.js';
-import { createLocalProvider } from './local.js';
-import { createInteractionsProvider } from './provider.js';
-import { createSpeechProvider } from './speech.js';
-function isSpeechRole(profile) {
-    return profile.outputs.speech !== undefined;
+import { isValidPair } from '../kernel/schema.js';
+import { markModuleLoad } from './probe.js';
+export function isSpeechRole(profile) {
+    return profile.type === 'speech';
+}
+export function isImageRole(profile) {
+    return profile.type === 'image';
 }
 /**
- * Defer loading `@openrouter/ai-sdk-provider` / `ai` until the first `complete`.
- * Keeps Google and local hosts free of the Vercel SDK graph.
+ * Lazy-load an adapter on first `complete`. When `THEORUM_IMPORT_PROBE=1`,
+ * emits `LOADED:<label>` exactly once at load time (import-isolation tests).
  */
-function lazyOpenRouterChat(config) {
+function lazyAdapter(label, load) {
     let pending;
     return {
         async *complete(req) {
-            pending ??= import('./openrouter.js').then((m) => m.createOpenRouterProvider(config));
+            pending ??= (async () => {
+                markModuleLoad(label);
+                return await load();
+            })();
             yield* (await pending).complete(req);
         },
     };
 }
+function lazyOpenRouterChat(config) {
+    return lazyAdapter('openrouter-chat', () => import('./openrouter/chat.js').then((m) => m.createOpenRouterProvider(config)));
+}
+function lazyGoogleInteractions(config) {
+    return lazyAdapter('google-interactions-adapter', () => import('./google/interactions/mod.js').then((m) => m.createInteractionsProvider(config)));
+}
+function lazySpeech(config) {
+    return lazyAdapter('openrouter-speech', () => import('./openrouter/speech.js').then((m) => m.createSpeechProvider(config)));
+}
+function lazyImage(config) {
+    return lazyAdapter('openrouter-image', () => import('./openrouter/image.js').then((m) => m.createImageProvider(config)));
+}
+function lazyLocal(config) {
+    return lazyAdapter('local-adapter', () => import('./local/local.js').then((m) => m.createLocalProvider(config)));
+}
 /**
- * Create a `ModelProvider` for a profile.
- * One call: protocol/provider (and speech role) pick the transport.
+ * Create a `ModelProvider` for a turn-based profile (text / image / speech).
+ * Live profiles use `runSession` — `createProvider` rejects geminiLive.
  */
 export function createProvider(profile, options = {}) {
     const { protocol, provider } = profile.model;
+    if (!isValidPair(protocol, provider)) {
+        throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
+    }
     if (protocol === 'geminiInteractions' && provider === 'google') {
         if (!options.gemini) {
             throw new TheorumError('createProvider requires gemini transport for google Interactions');
         }
-        return createInteractionsProvider(options.gemini);
+        return lazyGoogleInteractions(options.gemini);
+    }
+    if (protocol === 'geminiLive' && provider === 'google') {
+        throw new TheorumError("createProvider does not support type 'live' / geminiLive — use runSession(req, { gemini })");
     }
     if (protocol === 'openAi' && provider === 'openrouter') {
-        if (!options.openRouter) {
-            throw new TheorumError('createProvider requires openRouter config for openAi/openrouter');
+        if (!options.openAiGateway) {
+            throw new TheorumError('createProvider requires openAiGateway config for openAi/openrouter');
         }
         if (isSpeechRole(profile)) {
-            return createSpeechProvider(options.openRouter);
+            return lazySpeech(options.openAiGateway);
+        }
+        if (isImageRole(profile)) {
+            return lazyImage(options.openAiGateway);
         }
-        return lazyOpenRouterChat(options.openRouter);
+        return lazyOpenRouterChat(options.openAiGateway);
     }
     if (protocol === 'openAi' && provider === 'local') {
-        return createLocalProvider(options.local);
+        if (isImageRole(profile)) {
+            throw new TheorumError('createProvider: type image requires openrouter provider for openAi protocol');
+        }
+        return lazyLocal(options.local);
     }
+    // Exhaustiveness guard: isValidPair above already rejects unknown pairs, so
+    // this throw is unreachable at runtime. It exists so TypeScript errors if a
+    // new protocol/provider is added to PROTOCOL_PROVIDERS without a branch here.
     throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
 }
-exposeForTests('create-provider', { isSpeechRole, createProvider, lazyOpenRouterChat });

package/esm/src/providers/google/interactions/framing.d.ts

@@ -0,0 +1,15 @@
+import type { InteractionPart, ProviderCompleteRequest, TurnHistoryMessage } from '../../../kernel/types.js';
+export declare function camelToSnake(key: string): string;
+export declare function toGoogleValue(value: unknown): unknown;
+export declare function wirePart(part: InteractionPart): Record<string, string>;
+export declare function userInputStep(parts: InteractionPart[]): Record<string, unknown>;
+export declare function historyStep(msg: TurnHistoryMessage): Record<string, unknown>;
+export declare function systemHoldsUserInput(system: string, parts: InteractionPart[]): boolean;
+export declare function jsonResponseFormat(schema: Record<string, unknown>): unknown[];
+export declare function attachResponseFormat(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+export declare function attachSpeechConfig(req: ProviderCompleteRequest, generationConfig: Record<string, unknown>): void;
+export declare function inputStepsFromRequest(req: ProviderCompleteRequest): Record<string, unknown>[];
+export declare function applyOptionalRequestFields(req: ProviderCompleteRequest, camel: Record<string, unknown>): void;
+export declare function baseInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
+/** Compatibility wrapper for callers that need the complete wire body. */
+export declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;

package/esm/src/providers/google/interactions/framing.js

@@ -0,0 +1,208 @@
+import { TheorumError } from '../../../guardrails/error.js';
+import { getStructured } from '../../../kernel/registry/schemas.js';
+import { getTool } from '../../../kernel/tools/registry.js';
+export function camelToSnake(key) {
+    return key.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+export function toGoogleValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(toGoogleValue);
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, nested] of Object.entries(value)) {
+            // JSON Schema property names must stay as authored (e.g. correctAnswer in
+            // both properties and required). Snake-casing breaks Gemini validation.
+            if (key === 'schema' || key === 'parameters') {
+                out[camelToSnake(key)] = nested;
+                continue;
+            }
+            out[camelToSnake(key)] = toGoogleValue(nested);
+        }
+        return out;
+    }
+    return value;
+}
+export function wirePart(part) {
+    if (part.type === 'text') {
+        return { type: 'text', text: part.text };
+    }
+    return { type: part.type, mimeType: part.mimeType, data: part.data };
+}
+const USER_INPUT = 'user_input';
+export function userInputStep(parts) {
+    return { type: USER_INPUT, content: parts.map(wirePart) };
+}
+function functionResultStep(msg) {
+    return {
+        type: 'function_result',
+        name: msg.name ?? '',
+        call_id: msg.tool_call_id ?? '',
+        result: [{ type: 'text', text: msg.content ?? '' }],
+    };
+}
+export function historyStep(msg) {
+    if (msg.role === 'tool') {
+        return functionResultStep(msg);
+    }
+    const isAssistant = msg.role === 'assistant';
+    // Google Interactions input steps: assistant history is `model_output` (not `model_turn`).
+    const type = isAssistant ? 'model_output' : 'user_input';
+    if (msg.parts && msg.parts.length > 0) {
+        return { type, content: msg.parts.map(wirePart) };
+    }
+    return { type, content: [{ type: 'text', text: msg.content ?? '' }] };
+}
+export function systemHoldsUserInput(system, parts) {
+    for (const part of parts) {
+        if (part.type === 'text' && part.text && system.includes(part.text)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function jsonResponseFormat(schema) {
+    return [{ type: 'text', mimeType: 'application/json', schema }];
+}
+export function attachResponseFormat(req, camel) {
+    if (req.speech) {
+        if (req.image) {
+            throw new TheorumError('cannot mix speech and image response formats');
+        }
+        if (req.structured) {
+            throw new TheorumError('cannot mix speech and structured response formats');
+        }
+        camel.responseFormat = { type: 'audio' };
+        camel.responseModalities = ['audio'];
+        return;
+    }
+    if (req.image) {
+        const imageEntry = {
+            type: 'image',
+            mimeType: req.image.mimeType,
+        };
+        if (req.image.aspectRatio) {
+            imageEntry.aspectRatio = req.image.aspectRatio;
+        }
+        if (req.image.size) {
+            imageEntry.imageSize = req.image.size;
+        }
+        // Post–May 2026 Interactions API: object = image-only; array = text + image.
+        camel.responseFormat = req.image.includeText ? [{ type: 'text' }, imageEntry] : imageEntry;
+        return;
+    }
+    if (!req.structured) {
+        return;
+    }
+    const spec = getStructured(req.structured);
+    if (spec.enforced !== 'responseFormat' || !spec.jsonSchema) {
+        return;
+    }
+    camel.responseFormat = jsonResponseFormat(spec.jsonSchema);
+}
+export function attachSpeechConfig(req, generationConfig) {
+    if (!req.speech) {
+        return;
+    }
+    const voice = req.speech.voice;
+    if (!voice) {
+        return;
+    }
+    generationConfig.speechConfig = [{ voice }];
+}
+function wireInteractionsFunctionTool(decl) {
+    return {
+        type: 'function',
+        name: decl.name,
+        description: decl.description,
+        parameters: decl.parameters,
+    };
+}
+function wireGoogleMapsTool(req) {
+    const loc = req.googleMapsLocation;
+    if (loc && Number.isFinite(loc.latitude) && Number.isFinite(loc.longitude)) {
+        return {
+            type: 'google_maps',
+            latitude: loc.latitude,
+            longitude: loc.longitude,
+        };
+    }
+    return { type: 'google_maps' };
+}
+function wireInteractionsTools(req) {
+    const tools = [];
+    for (const id of req.builtins) {
+        const entry = getTool(id);
+        const type = entry?.type === 'builtin' ? entry.wire.interactions : undefined;
+        if (!type) {
+            throw new TheorumError(`Builtin '${id}' has no Interactions wire type`);
+        }
+        if (type === 'google_maps') {
+            tools.push(wireGoogleMapsTool(req));
+            continue;
+        }
+        tools.push({ type });
+    }
+    for (const decl of req.wireTools ?? []) {
+        tools.push(wireInteractionsFunctionTool(decl));
+    }
+    return tools;
+}
+export function inputStepsFromRequest(req) {
+    if (req.interactionOnlyInput && req.interactionOnlyInput.length > 0) {
+        return req.interactionOnlyInput;
+    }
+    const inputSteps = [];
+    for (const h of req.history ?? []) {
+        inputSteps.push(historyStep(h));
+    }
+    if (req.input.length > 0 || inputSteps.length === 0) {
+        inputSteps.push(userInputStep(req.input));
+    }
+    return inputSteps;
+}
+export function applyOptionalRequestFields(req, camel) {
+    if (req.store !== undefined) {
+        camel.store = req.store;
+    }
+    if (req.previousInteractionId) {
+        camel.previousInteractionId = req.previousInteractionId;
+    }
+    if (req.system) {
+        if (systemHoldsUserInput(req.system, req.input)) {
+            throw new TheorumError('User payload must not be copied into system instructions');
+        }
+        camel.systemInstruction = req.system;
+    }
+    const tools = wireInteractionsTools(req);
+    if (tools.length > 0) {
+        camel.tools = tools;
+    }
+}
+export function baseInteractionsBody(req) {
+    const generationConfig = {
+        temperature: req.temperature,
+        maxOutputTokens: req.maxOutputTokens,
+    };
+    if (req.speech) {
+        // TTS models reject chat thinking knobs; voice lives under speech_config.
+        attachSpeechConfig(req, generationConfig);
+    }
+    else {
+        generationConfig.thinkingLevel = req.thinking;
+        generationConfig.thinkingSummaries = req.summaries;
+    }
+    return {
+        model: req.apiId,
+        stream: req.stream ?? true,
+        input: inputStepsFromRequest(req),
+        generationConfig,
+    };
+}
+/** Compatibility wrapper for callers that need the complete wire body. */
+export function toInteractionsBody(req) {
+    const body = baseInteractionsBody(req);
+    attachResponseFormat(req, body);
+    applyOptionalRequestFields(req, body);
+    return toGoogleValue(body);
+}

package/esm/src/providers/google/interactions/mod.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Google Interactions provider module.
+ *
+ * @module
+ */
+export { camelToSnake, toInteractionsBody } from './framing.js';
+export { createInteractionsProvider } from './stream.js';

package/esm/src/providers/google/interactions/mod.js

@@ -0,0 +1,7 @@
+/**
+ * Google Interactions provider module.
+ *
+ * @module
+ */
+export { camelToSnake, toInteractionsBody } from './framing.js';
+export { createInteractionsProvider } from './stream.js';

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

@@ -0,0 +1,83 @@
+/**
+ * Google Interactions provider adapter.
+ *
+ * This adapter converts THEORUM's provider-neutral request into the Google
+ * Interactions wire format and streams normalized `TurnEvent` objects.
+ * Speech-role turns use `response_format: audio` + `speech_config` (same
+ * transport as chat/image).
+ *
+ * @module
+ */
+import type { ModelProvider, ProviderCompleteRequest, TurnEvent } from '../../../kernel/types.js';
+import { type ParsedToolArguments } from '../../shared/tool-args.js';
+import { type GeminiTransport } from '../keys.js';
+export interface PendingFunctionCall {
+    id?: string;
+    name?: string;
+    arguments: string;
+}
+export interface StreamFold {
+    text: string;
+    functionCalls: Map<number, PendingFunctionCall>;
+    emittedToolKeys: Set<string>;
+    emittedEvidenceKeys: Set<string>;
+    codeSteps: Map<number, Record<string, unknown>>;
+    sawStreamedMedia: boolean;
+}
+export declare function isRawPcmMime(mime: string): boolean;
+export declare function normalizeSpeechMedia(event: TurnEvent, speech: boolean): TurnEvent;
+export declare function newStreamFold(): StreamFold;
+export declare function eventType(payload: Record<string, unknown>): string;
+export declare function isDeltaEvent(type: string): boolean;
+export declare function isCompleteEvent(type: string): boolean;
+export declare function yieldGrounding(event: Record<string, unknown>): Generator<TurnEvent>;
+export declare function yieldTokens(event: Record<string, unknown>): Generator<TurnEvent>;
+export declare function functionCallKey(tool: {
+    name?: string;
+    id?: string;
+    arguments?: Record<string, unknown>;
+}): string;
+export declare function yieldEvidenceStep(step: Record<string, unknown>, emittedKeys: Set<string>): Generator<TurnEvent>;
+export declare function isCompleteCodeStep(step: Record<string, unknown>): boolean;
+export declare function foldStepStart(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export type { ParsedToolArguments };
+export declare function parseArgumentsObject(raw: unknown): ParsedToolArguments;
+export declare function emitUniqueToolEvent(tool: {
+    id?: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    phase?: 'error';
+    failure?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}, fold: StreamFold): TurnEvent[];
+/** Emit a tool call, or a structured tool failure when arguments cannot be parsed. */
+export declare function emitToolCallFromRawArguments(tool: {
+    id?: string;
+    name: string;
+}, rawArguments: unknown, fold: StreamFold): TurnEvent[];
+export declare function foldArgumentsDelta(delta: Record<string, unknown>, index: number, fold: StreamFold): void;
+export declare function foldFunctionCallDelta(delta: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldDeltaPayload(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function readData(part: Record<string, unknown>): string | undefined;
+export declare function readMime(part: Record<string, unknown>): string | undefined;
+export declare function yieldMediaChunk(part: Record<string, unknown>): Generator<TurnEvent>;
+export declare function scanMediaParts(content: unknown): Generator<TurnEvent>;
+export declare function emitPendingFunctionCall(index: number, fold: StreamFold): TurnEvent[];
+export declare function foldStepStop(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldInteractionSteps(interaction: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldCompleteEvents(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function foldPayload(payload: Record<string, unknown>, fold: StreamFold): TurnEvent[];
+export declare function finalizeStructured(req: ProviderCompleteRequest, fold: StreamFold): Generator<TurnEvent>;
+export declare function scanInteractionsMedia(json: Record<string, unknown>): Generator<TurnEvent>;
+export declare function isVoiceProfile(req: ProviderCompleteRequest): boolean;
+export declare function shouldReportMissingSpeechAudio(req: ProviderCompleteRequest, fold: StreamFold): boolean;
+/** Speech-role turns must receive real audio; never invent PCM from text bytes. */
+export declare function missingSpeechAudioError(): Generator<TurnEvent>;
+export declare function readApiErrorMessage(record: Record<string, unknown>): string | null;
+export declare function readNonOkErrorMessage(response: Response): Promise<string>;
+export declare function withTap(req: ProviderCompleteRequest, transport: GeminiTransport): GeminiTransport;
+/** Create a `ModelProvider` backed by Google Interactions HTTP / SSE. */
+export declare function createInteractionsProvider(transport: GeminiTransport): ModelProvider;