@theoremjs/agents 0.3.0 → 0.3.2

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

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

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

@@ -1,15 +1,27 @@
-import type { InteractionPart, ProviderCompleteRequest, TurnHistoryMessage } from '../../../kernel/types.js';
+import { z } from 'zod';
+import type { InteractionPart, ModelRequest, TurnHistoryMessage } from '../../../kernel/types.js';
+/** A turn as Interactions frames it: the request, plus whether Google keeps it and what it continues. */
+export type InteractionsRequest = ModelRequest & {
+    store?: boolean;
+    previousInteractionId?: string;
+    /** What came after the stored interaction, sent in place of the whole history. */
+    continuation?: TurnHistoryMessage[];
+};
 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>;
-/** Assistant `tool_calls` (often with no `content`) become `function_call` steps, never empty `model_output`. */
+/** A thought's signature, for the tool call at `call` in the same assistant message. */
+export declare const thoughtSignature: z.ZodType<{
+    call: number;
+    signature: string;
+}>;
 export declare function historySteps(msg: TurnHistoryMessage): Record<string, unknown>[];
 export declare function historyStep(msg: TurnHistoryMessage): Record<string, unknown>;
 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>;
-export declare function toInteractionsBody(req: ProviderCompleteRequest): Record<string, unknown>;
+export declare function attachResponseFormat(req: InteractionsRequest, camel: Record<string, unknown>): void;
+export declare function attachSpeechConfig(req: InteractionsRequest, generationConfig: Record<string, unknown>): void;
+export declare function inputStepsFromRequest(req: InteractionsRequest): Record<string, unknown>[];
+export declare function applyOptionalRequestFields(req: InteractionsRequest, camel: Record<string, unknown>): void;
+export declare function baseInteractionsBody(req: InteractionsRequest): Record<string, unknown>;
+export declare function toInteractionsBody(req: InteractionsRequest): Record<string, unknown>;

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

@@ -1,8 +1,10 @@
+import { z } from 'zod';
 import { TheoremError } from '../../../guardrails/error.js';
 import { historyMessageParts, wireInteractionPart } from '../../../kernel/interaction-parts.js';
 import { GOOGLE_SPEECH_FORMATS } from '../../../presets/google-limits.js';
-import { builtinWire } from '../../shared/builtin-wire.js';
+import { withCarriedToolFiles } from '../../shared/carried-tool-files.js';
 import { historyToolArguments, historyToolIdentity } from '../../shared/tool-args.js';
+import { interactionsBuiltinTool } from '../builtins.js';
 import { assertGoogleThinkingLevel } from '../thinking.js';
 export function camelToSnake(key) {
     return key.replaceAll(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
@@ -14,8 +16,8 @@ export function toGoogleValue(value) {
     if (value && typeof value === 'object') {
         const out = {};
         for (const [key, nested] of Object.entries(value)) {
-            // Schema property names stay as authored; snake-casing them breaks Gemini validation.
-            if (key === 'schema' || key === 'parameters') {
+            // why: A schema's property names and a call's argument names are the builder's own; snake-casing them breaks Gemini validation and shows the model a call it did not make.
+            if (key === 'schema' || key === 'parameters' || key === 'arguments') {
                 out[camelToSnake(key)] = nested;
                 continue;
             }
@@ -36,12 +38,18 @@ function historyContent(msg) {
     const parts = historyMessageParts(msg);
     return parts.length > 0 ? parts.map(wirePart) : [{ type: 'text', text: '' }];
 }
+// why: Google refuses any other part inside a `function_result`: "The value 'document' is not supported for 'type' at 'input[8].result[2]'. Supported values: 'function', 'image', 'text', 'video'." (live, 13/10/2026, gemini-3.5-flash-lite).
+const FUNCTION_RESULT_PART_TYPES = new Set([
+    'text',
+    'image',
+    'video',
+]);
 function functionResultStep(msg) {
-    const result = historyContent(msg);
+    const parts = historyMessageParts(msg);
     return {
         type: 'function_result',
         ...historyToolIdentity({ name: msg.name, call_id: msg.tool_call_id }),
-        result,
+        result: parts.length > 0 ? parts.map(wirePart) : [{ type: 'text', text: '' }],
     };
 }
 /**
@@ -51,34 +59,43 @@ function functionResultStep(msg) {
  * the call; a `thought` step with the signature ahead of it is accepted (probe
  * 25/09/2026, gemini-3.1-flash-lite, `store: false`).
  */
-function functionCallSteps(call) {
+function functionCallSteps(call, signature) {
     const step = {
         type: 'function_call',
         id: call.id,
         name: call.function.name,
         arguments: historyToolArguments(call.function.arguments),
     };
-    return call.thoughtSignature
-        ? [{ type: 'thought', signature: call.thoughtSignature }, step]
-        : [step];
+    return signature ? [{ type: 'thought', signature }, step] : [step];
+}
+/** A thought's signature, for the tool call at `call` in the same assistant message. */
+export const thoughtSignature = z.strictObject({
+    call: z.number().int().min(0),
+    signature: z.string().min(1),
+});
+/** The signature written with the message's call at `index`, if its reasoning holds one. */
+function signatureAt(msg, index) {
+    for (const part of msg.reasoning ?? []) {
+        const parsed = thoughtSignature.safeParse(part.data);
+        if (parsed.success && parsed.data.call === index)
+            return parsed.data.signature;
+    }
+    return undefined;
 }
 function textOrPartsStep(role, msg) {
-    // Assistant history is `model_output`, not `model_turn`.
+    // why: Assistant history is `model_output`, not `model_turn`.
     const type = role === 'assistant' ? 'model_output' : 'user_input';
     return { type, content: historyContent(msg) };
 }
 /** Assistant `tool_calls` (often with no `content`) become `function_call` steps, never empty `model_output`. */
-export function historySteps(msg) {
-    if (msg.role === 'tool') {
-        return [functionResultStep(msg)];
-    }
+function nonToolSteps(msg) {
     if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
         const steps = [];
         if (historyMessageParts(msg).length > 0) {
             steps.push(textOrPartsStep('assistant', msg));
         }
-        for (const call of msg.tool_calls) {
-            steps.push(...functionCallSteps(call));
+        for (const [index, call] of msg.tool_calls.entries()) {
+            steps.push(...functionCallSteps(call, signatureAt(msg, index)));
         }
         return steps;
     }
@@ -87,6 +104,16 @@ export function historySteps(msg) {
     }
     return [textOrPartsStep('user', msg)];
 }
+/**
+ * History as input steps. A file a `function_result` cannot hold follows its run
+ * of tool results in a `user_input` step (`withCarriedToolFiles`).
+ */
+function historyStepsOf(messages) {
+    return withCarriedToolFiles(messages, FUNCTION_RESULT_PART_TYPES).flatMap((msg) => msg.role === 'tool' ? [functionResultStep(msg)] : nonToolSteps(msg));
+}
+export function historySteps(msg) {
+    return historyStepsOf([msg]);
+}
 export function historyStep(msg) {
     const steps = historySteps(msg);
     return steps[0] ?? { type: 'user_input', content: [{ type: 'text', text: '' }] };
@@ -107,7 +134,6 @@ export function attachResponseFormat(req, camel) {
             throw new TheoremError('unsupported', `Gemini speech returns ${GOOGLE_SPEECH_FORMATS.join(', ')}, not '${format}'`);
         }
         camel.responseFormat = { type: 'audio' };
-        camel.responseModalities = ['audio'];
         return;
     }
     if (req.image) {
@@ -131,7 +157,6 @@ export function attachResponseFormat(req, camel) {
                 throw new TheoremError('unsupported', `image.${name} is not supported on Google image models`);
             }
         }
-        // An object asks for image only; an array for text + image.
         camel.responseFormat = req.image.includeText ? [{ type: 'text' }, imageEntry] : imageEntry;
         return;
     }
@@ -144,12 +169,46 @@ export function attachSpeechConfig(req, generationConfig) {
     if (!req.speech) {
         return;
     }
-    const voice = req.speech.voice;
+    const { voice, speed } = req.speech;
+    if (speed !== undefined) {
+        // why: Interactions has no rate field, and a speed dropped here would be a setting the host believes it made.
+        throw new TheoremError('config', 'Gemini Interactions speech has no speed field: set the pace in speech.style');
+    }
     if (!voice) {
-        return;
+        // why: Interactions has no default voice and refuses the request without one (live, 17/10/2026).
+        throw new TheoremError('config', 'Gemini speech needs a voice: set speech.voice');
     }
     generationConfig.speechConfig = [{ voice }];
 }
+/**
+ * The speech models that read a delivery note as a `speech_metadata` annotation. The others refuse
+ * it ("Speech metadata is not supported for this model", gemini-3.1-flash-tts-preview, live
+ * 17/10/2026) and take the note as a direction ahead of the script, as Google's guide shows.
+ */
+const SPEECH_METADATA_MODELS = new Set([
+    'gemini-3.8-flash-tts',
+    'gemini-3.8-flash-lite-tts',
+]);
+/** The script with its delivery note, in the form the model reads it. */
+function speechInputStep(parts, style, apiId) {
+    if (!SPEECH_METADATA_MODELS.has(apiId)) {
+        return {
+            type: USER_INPUT,
+            content: [
+                { type: 'text', text: `Read the following aloud. ${style.trim()}\n` },
+                ...parts.map(wirePart),
+            ],
+        };
+    }
+    // why: Gemini reads `text` aloud and `speech_metadata` as direction.
+    const annotations = [{ type: 'speech_metadata', style }];
+    return {
+        type: USER_INPUT,
+        content: parts
+            .map(wirePart)
+            .map((part) => (part.type === 'text' ? { ...part, annotations } : part)),
+    };
+}
 function wireInteractionsFunctionTool(decl) {
     return {
         type: 'function',
@@ -158,26 +217,10 @@ function wireInteractionsFunctionTool(decl) {
         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 builtin of req.builtins) {
-        const type = builtinWire(builtin, 'interactions');
-        if (type === 'google_maps') {
-            tools.push(wireGoogleMapsTool(req));
-            continue;
-        }
-        tools.push({ type });
+        tools.push(interactionsBuiltinTool(builtin));
     }
     for (const decl of req.wireTools ?? []) {
         tools.push(wireInteractionsFunctionTool(decl));
@@ -201,14 +244,12 @@ function withToolNames(messages) {
 }
 export function inputStepsFromRequest(req) {
     if (req.continuation && req.continuation.length > 0) {
-        return withToolNames(req.continuation).flatMap((msg) => historySteps(msg));
-    }
-    const inputSteps = [];
-    for (const h of withToolNames(req.history ?? [])) {
-        inputSteps.push(...historySteps(h));
+        return historyStepsOf(withToolNames(req.continuation));
     }
+    const inputSteps = historyStepsOf(withToolNames(req.history ?? []));
     if (req.input.length > 0 || inputSteps.length === 0) {
-        inputSteps.push(userInputStep(req.input));
+        const style = req.speech?.style;
+        inputSteps.push(style ? speechInputStep(req.input, style, req.apiId) : userInputStep(req.input));
     }
     return inputSteps;
 }
@@ -233,7 +274,7 @@ export function baseInteractionsBody(req) {
         maxOutputTokens: req.maxOutputTokens,
     };
     if (req.speech) {
-        // TTS models reject chat thinking knobs; voice lives under speech_config.
+        // why: TTS models reject chat thinking knobs; voice lives under speech_config.
         attachSpeechConfig(req, generationConfig);
     }
     else {

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

@@ -1,12 +1,12 @@
-import type { ProviderEvent, TurnEventOf, TurnResponse } from '../../../kernel/types.js';
+import type { ModelEvent, TurnEventOf, TurnResponse } from '../../../kernel/types.js';
 declare function isCodeExecutionType(type: string): boolean;
 declare function isGoogleBuiltinStepType(type: string): boolean;
 declare function rawStepEvidence(raw: Record<string, unknown>): TurnEventOf<'evidence'>;
 declare function codeExecutionEvidence(raw: Record<string, unknown>): TurnEventOf<'evidence'>;
-declare function eventsFromDelta(deltaValue: unknown): ProviderEvent[];
-declare function eventsFromThoughtStep(step: Record<string, unknown>): ProviderEvent[];
-declare function eventsFromModelOutputStep(step: Record<string, unknown>): ProviderEvent[];
+declare function eventsFromDelta(deltaValue: unknown): ModelEvent[];
+declare function eventsFromThoughtStep(step: Record<string, unknown>): ModelEvent[];
+declare function eventsFromModelOutputStep(step: Record<string, unknown>): ModelEvent[];
 declare function extractTokenEvent(interaction: Record<string, unknown>): TurnEventOf<'tokens'> | undefined;
-declare function eventsFromInteractionEnd(interaction: Record<string, unknown>): ProviderEvent[];
+declare function eventsFromInteractionEnd(interaction: Record<string, unknown>): ModelEvent[];
 declare function interactionResponse(interaction: Record<string, unknown>): TurnResponse | undefined;
 export { codeExecutionEvidence, eventsFromDelta, eventsFromInteractionEnd, eventsFromModelOutputStep, eventsFromThoughtStep, extractTokenEvent, interactionResponse, isCodeExecutionType, isGoogleBuiltinStepType, rawStepEvidence, };

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

@@ -3,9 +3,9 @@ import { reportedTokens, usageCount } from '../../../kernel/engine/usage.js';
 import { turnStopFromInteractionStatus } from '../../../kernel/stop.js';
 import { groundingFromSteps } from '../grounding.js';
 import { byModality, groundingCounts, modalityCounts } from '../usage.js';
-/*
+/* probed 2026-09-23:
  * Interactions steps and deltas read only the shapes recorded from the wire
- * (probes 23/09/2026, gemini-3.8-flash, gemini-3.1-pro-preview, image and TTS
+ * (probes 23/09/2026, gemini-3.8-flash, gemini-3.1-pro-preview, image, and TTS
  * models, streamed and buffered):
  *
  * - `text` deltas carry `text`; `thought_summary` deltas carry
@@ -16,7 +16,7 @@ import { byModality, groundingCounts, modalityCounts } from '../usage.js';
  *   buffered mime already states them (`audio/l16; rate=24000; channels=1`),
  *   the streamed one does not (`audio/l16`), so they are folded into the mime.
  * - `code_execution_call` carries `id` and `arguments: { language, code }`;
- *   `code_execution_result` carries `call_id`, `result` and `is_error`. Each
+ *   `code_execution_result` carries `call_id`, `result`, and `is_error`. Each
  *   arrives whole, in one delta (5 577 characters of code in one probe).
  */
 function thoughtText(content) {
@@ -171,7 +171,7 @@ function eventsFromInteractionEnd(interaction) {
     const tokenEvent = extractTokenEvent(interaction);
     if (tokenEvent)
         events.push(tokenEvent);
-    // Only a buffered body carries `steps[]`; streamed grounding arrives on deltas.
+    // why: Only a buffered body carries `steps[]`; streamed grounding arrives on deltas.
     const { steps } = interaction;
     if (Array.isArray(steps))
         events.push(...groundingFromSteps(steps));

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

@@ -1,8 +1,7 @@
-import type { ModelProvider, ProviderCompleteRequest, ProviderEvent, TurnResponse } from '../../../kernel/types.js';
-import { type GeminiTransport } from '../keys.js';
+import type { ModelEvent, ModelRequest, TurnResponse } from '../../../kernel/types.js';
 export interface StreamFold {
     text: string;
-    /** Open `function_call`, `code_execution_*` and builtin steps by `index`. */
+    /** Open `function_call`, `code_execution_*`, and builtin steps by `index`. */
     steps: Map<number, Record<string, unknown>>;
     sawMedia: boolean;
     /** A `done` came out: the interaction reported a status. */
@@ -11,14 +10,14 @@ export interface StreamFold {
     response?: TurnResponse;
     /** The signature of the last thought, until the `function_call` that follows it takes it. */
     thoughtSignature?: string;
+    /** Function calls read so far: a signature names its call by this position. */
+    calls: number;
 }
 export declare function newStreamFold(): StreamFold;
-export declare function eventsFromStep(step: Record<string, unknown>, fold: StreamFold): ProviderEvent[];
-export declare function openStepEvents(fold: StreamFold): ProviderEvent[];
-export declare function foldPayload(payload: Record<string, unknown>, fold: StreamFold): ProviderEvent[];
-export declare function foldBody(body: Record<string, unknown>, fold: StreamFold): ProviderEvent[];
-export declare function finalizeStructured(req: ProviderCompleteRequest, fold: StreamFold): Generator<ProviderEvent>;
-export declare function isVoiceProfile(req: ProviderCompleteRequest): boolean;
+export declare function eventsFromStep(step: Record<string, unknown>, fold: StreamFold): ModelEvent[];
+export declare function openStepEvents(fold: StreamFold): ModelEvent[];
+export declare function foldPayload(payload: Record<string, unknown>, fold: StreamFold): ModelEvent[];
+export declare function foldBody(body: Record<string, unknown>, fold: StreamFold): ModelEvent[];
+export declare function finalizeStructured(req: ModelRequest, fold: StreamFold): Generator<ModelEvent>;
 /** What the profile asked for and the model did not return; even an empty turn fails. */
-export declare function missingMediaError(req: ProviderCompleteRequest, fold: StreamFold): ProviderEvent | undefined;
-export declare function createInteractionsProvider(transport: GeminiTransport): ModelProvider;
+export declare function missingMediaError(req: ModelRequest, fold: StreamFold): ModelEvent | undefined;

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

@@ -1,19 +1,15 @@
-import { isAbortError, TheoremError, toErrorEvent } from '../../../guardrails/error.js';
+import { TheoremError, toErrorEvent } from '../../../guardrails/error.js';
 import { asRecord } from '../../../kernel/engine/record.js';
 import { pcmMediaAsWav } from '../../shared/pcm.js';
 import { foldResponse } from '../../shared/response-identity.js';
-import { readSseChunks } from '../../shared/sse.js';
 import { structuredEvent } from '../../shared/structured-output.js';
 import { toolCallEvents } from '../../shared/tool-args.js';
-import { readGeminiApiError, readNonOkError } from '../api-error.js';
+import { toolDraftEvents } from '../../shared/tool-draft.js';
+import { readGeminiApiError } from '../api-error.js';
 import { groundingFromDelta } from '../grounding.js';
-import { fetchGemini } from '../keys.js';
-import { INTERACTIONS_JSON_URL, INTERACTIONS_URL } from '../urls.js';
-import { toInteractionsBody } from './framing.js';
 import { codeExecutionEvidence, eventsFromDelta, eventsFromInteractionEnd, eventsFromModelOutputStep, eventsFromThoughtStep, interactionResponse, isCodeExecutionType, isGoogleBuiltinStepType, rawStepEvidence, } from './steps.js';
-const HTTP_OK = 200;
 export function newStreamFold() {
-    return { text: '', steps: new Map(), sawMedia: false, sawDone: false };
+    return { text: '', steps: new Map(), sawMedia: false, sawDone: false, calls: 0 };
 }
 function isMergedStepType(type) {
     return type === 'function_call' || isCodeExecutionType(type) || isGoogleBuiltinStepType(type);
@@ -47,8 +43,20 @@ export function eventsFromStep(step, fold) {
     if (type === 'function_call') {
         const id = typeof step.id === 'string' ? step.id : undefined;
         const name = typeof step.name === 'string' ? step.name : '';
-        const thoughtSignature = takeThoughtSignature(step, fold);
-        return toolCallEvents({ id, name, thoughtSignature }, step.arguments);
+        const signature = takeThoughtSignature(step, fold);
+        const call = fold.calls++;
+        return [
+            ...(signature
+                ? [
+                    {
+                        type: 'reasoning',
+                        data: { call, signature },
+                        origin: { protocol: 'geminiInteractions' },
+                    },
+                ]
+                : []),
+            ...toolCallEvents({ id, name }, step.arguments),
+        ];
     }
     if (isCodeExecutionType(type)) {
         return [codeExecutionEvidence(step)];
@@ -93,10 +101,19 @@ function foldStepDelta(payload, fold) {
         return eventsFromDelta(delta);
     }
     if (delta.type === 'arguments_delta') {
-        // Replaces the `arguments: {}` placeholder from `step.start` with the streamed JSON string.
+        // why: Replaces the `arguments: {}` placeholder from `step.start` with the streamed JSON string.
         const sofar = typeof open.arguments === 'string' ? open.arguments : '';
-        open.arguments = sofar + (typeof delta.arguments === 'string' ? delta.arguments : '');
-        return [];
+        const args = sofar + (typeof delta.arguments === 'string' ? delta.arguments : '');
+        open.arguments = args;
+        if (open.type !== 'function_call')
+            return [];
+        // why: The call at `step.stop` goes out under the `id` and `name` that `step.start` gave.
+        return toolDraftEvents({
+            id: nonEmptyString(open.id),
+            name: typeof open.name === 'string' ? open.name : '',
+            args,
+            drafted: sofar.length,
+        });
     }
     Object.assign(open, delta);
     return [];
@@ -138,7 +155,7 @@ function delivered(events, fold) {
 }
 function eventsFromStreamRow(payload, fold) {
     if (payload.eventType === 'sse_unparsed') {
-        // Every observed Interactions row is a JSON object; anything else is a wire change.
+        // why: Every observed Interactions row is a JSON object; anything else is a wire change.
         return [
             toErrorEvent(new TheoremError('bad_response', 'Interactions stream row was not a JSON object')),
         ];
@@ -196,8 +213,8 @@ export function* finalizeStructured(req, fold) {
     }
     yield structuredEvent(fold.text);
 }
-export function isVoiceProfile(req) {
-    return Boolean(req.speech?.voice);
+function isVoiceProfile(req) {
+    return Boolean(req.speech);
 }
 /** What the profile asked for and the model did not return; even an empty turn fails. */
 export function missingMediaError(req, fold) {
@@ -211,87 +228,3 @@ export function missingMediaError(req, fold) {
     }
     return undefined;
 }
-async function* parseInteractionsSse(response, req) {
-    if (!response.body) {
-        yield toErrorEvent(new TheoremError('bad_response', 'empty response body'));
-        return;
-    }
-    const fold = newStreamFold();
-    for await (const row of readSseChunks(response.body)) {
-        req.tapUpstream?.(row);
-        if (row.eventType === 'sse_done') {
-            break;
-        }
-        const events = foldPayload(row, fold);
-        yield* events;
-        if (events.some((ev) => ev.type === 'error')) {
-            yield* openStepEvents(fold);
-            return;
-        }
-    }
-    yield* openStepEvents(fold);
-    yield* finalizeStructured(req, fold);
-    const missing = missingMediaError(req, fold);
-    if (missing)
-        yield missing;
-    if (!fold.sawDone) {
-        // The stream ended before the interaction reported a status: it did not complete.
-        yield { type: 'done', stop: { kind: 'stream_incomplete' } };
-    }
-}
-async function postInteractions(url, req, transport) {
-    if (!req.keySlot) {
-        throw new TheoremError('config', 'Request requires keySlot');
-    }
-    const init = {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify(toInteractionsBody(req)),
-        signal: req.signal,
-    };
-    const response = await fetchGemini(url, init, req.keySlot, transport, req.tapUpstream, req.fallbackKeySlot);
-    if (response.status !== HTTP_OK) {
-        throw await readNonOkError(response);
-    }
-    return response;
-}
-async function* fetchInteractionsOnce(req, transport) {
-    const response = await postInteractions(INTERACTIONS_JSON_URL, req, transport);
-    const text = await response.text();
-    const parsed = JSON.parse(text);
-    const apiError = readGeminiApiError(parsed);
-    if (apiError) {
-        throw apiError;
-    }
-    req.tapUpstream?.(parsed);
-    const fold = newStreamFold();
-    yield* foldBody(parsed, fold);
-    yield* finalizeStructured(req, fold);
-    const missing = missingMediaError(req, fold);
-    if (missing)
-        yield missing;
-}
-async function* streamInteractions(req, transport) {
-    const response = await postInteractions(INTERACTIONS_URL, req, transport);
-    yield* parseInteractionsSse(response, req);
-}
-export function createInteractionsProvider(transport) {
-    return {
-        async *complete(req) {
-            try {
-                if (req.stream === false) {
-                    yield* fetchInteractionsOnce(req, transport);
-                }
-                else {
-                    yield* streamInteractions(req, transport);
-                }
-            }
-            catch (err) {
-                if (isAbortError(err)) {
-                    throw err;
-                }
-                yield toErrorEvent(err);
-            }
-        },
-    };
-}

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

@@ -1,16 +1,26 @@
-import type { InteractionPart, ProviderCompleteRequest, ProviderEvent, TurnHistoryMessage, TurnTokens, WireFunctionTool } from '../../../kernel/types.js';
+import type { InteractionPart, ModelEvent, ModelRequest, TurnHistoryMessage, TurnTokens, WireFunctionTool } from '../../../kernel/types.js';
 export declare function buildGeminiLiveWebSocketUrl(apiKey: string): string;
+/** `parametersJsonSchema` takes the JSON Schema as it is; `parameters` takes only Google's OpenAPI subset. */
 export declare function wireFunctionDeclaration(decl: WireFunctionTool): Record<string, unknown>;
-export declare function buildGeminiLiveSetupMessage(req: ProviderCompleteRequest): Record<string, unknown>;
+/**
+ * Builtins are their own tool entries (`{ googleSearch: {} }`), functions share
+ * one `functionDeclarations` entry. Which builtins a model takes is the API's
+ * answer (probe 23/09/2026: a model without one closes the socket with 1007).
+ */
+/** A live session's setup as Gemini frames it: the request, plus the handle it resumes from. */
+export type LiveSetupRequest = ModelRequest & {
+    sessionResumptionHandle?: string;
+};
+export declare function buildGeminiLiveSetupMessage(req: LiveSetupRequest): Record<string, unknown>;
 export declare function buildGeminiLiveClientContent(history: TurnHistoryMessage[]): Record<string, unknown> | null;
 export declare function buildGeminiLiveContext(text: string): Record<string, unknown>;
 export declare function buildGeminiLiveRealtimeInput(input: InteractionPart): Record<string, unknown>;
-export declare function liveFunctionResponsePayload(output: unknown): Record<string, unknown>;
-export declare function buildGeminiLiveToolResponse(id: string, name: string, output: unknown): Record<string, unknown>;
+export declare function buildGeminiLiveToolResponse(id: string, name: string, output: unknown, parts?: InteractionPart[]): Record<string, unknown>;
 export declare function buildGeminiLiveToolResponses(responses: Array<{
     id: string;
     name: string;
     output: unknown;
+    parts?: InteractionPart[];
 }>): Record<string, unknown>;
 /** What one outbound frame gives the model to read; setup and control frames give none. */
 export declare function liveFrameInput(frame: Record<string, unknown>): TurnHistoryMessage[];
@@ -48,4 +58,4 @@ export type LiveInteractionStatus = 'IN_PROGRESS' | 'IDLE';
  * flow, `IDLE` on the last).
  */
 export declare function readLiveInteractionStatus(message: Record<string, unknown>): LiveInteractionStatus | undefined;
-export declare function foldGeminiLiveServerMessage(message: Record<string, unknown> | null | undefined, fold: LiveFold): ProviderEvent[];
+export declare function foldGeminiLiveServerMessage(message: Record<string, unknown> | null | undefined, fold: LiveFold): ModelEvent[];