theorum 0.1.14 → 1.0.0

package/esm/src/providers/{keys.js → google/keys.js}

@@ -1,13 +1,12 @@
 /**
- * Gemini key vault selection, quota overflow, and fetch retries.
+ * Google transport credentials, quota overflow, and fetch retries.
  *
- * Host applications supply vault credentials through `GeminiTransport`.
+ * Hosts supply a provider-neutral `KeyVault` via `GeminiTransport`.
  * THEORUM does not read environment variables for these keys.
  *
  * @module
  */
-import { isAbortError, TheorumError, UPSTREAM_FAILED } from '../guardrails/error.js';
-import { exposeForTests } from './expose-for-tests.js';
+import { isAbortError, TheorumError, UPSTREAM_FAILED } from '../../guardrails/error.js';
 const ATTEMPTS = 3;
 const LAST_ATTEMPT = ATTEMPTS - 1;
 const BACKOFF_FIRST_MS = 1000;
@@ -22,16 +21,16 @@ const HTTP_UNAVAILABLE = 503;
 const HTTP_GATEWAY_TIMEOUT = 504;
 const QUOTA_RE = /quota/i;
 const TRANSIENT_THROWN_RE = /name resolution|dns|econnreset|econnrefused|etimedout|network|fetch failed|temporarily unavailable|socket|503|502|504/i;
-function waitDefault(ms) {
+export function waitDefault(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
     });
 }
-function isQuota(err) {
+export function isQuota(err) {
     const s = String(err);
     return s.includes(String(HTTP_QUOTA)) || s.includes('RESOURCE_EXHAUSTED') || QUOTA_RE.test(s);
 }
-function isTransientHttp(status) {
+export function isTransientHttp(status) {
     return (status === HTTP_TIMEOUT ||
         status === HTTP_QUOTA ||
         status === HTTP_SERVER ||
@@ -39,20 +38,20 @@ function isTransientHttp(status) {
         status === HTTP_UNAVAILABLE ||
         status === HTTP_GATEWAY_TIMEOUT);
 }
-function isTransientThrown(err) {
+export function isTransientThrown(err) {
     if (isAbortError(err)) {
         return false;
     }
     return TRANSIENT_THROWN_RE.test(String(err));
 }
-function requireKey(vault, bucket) {
-    const key = vault[bucket];
+export function requireKey(vault, slot) {
+    const key = vault[slot];
     if (!key) {
         throw new TheorumError(UPSTREAM_FAILED);
     }
     return key;
 }
-function backoffMs(attempt) {
+export function backoffMs(attempt) {
     return BACKOFF_MS[attempt] ?? BACKOFF_SECOND_MS;
 }
 async function runWithBackoff(apiKey, run, wait, attempt) {
@@ -69,8 +68,8 @@ async function runWithBackoff(apiKey, run, wait, attempt) {
         return runWithBackoff(apiKey, run, wait, attempt + 1);
     }
 }
-function canOverflow(bucket, vault, primary) {
-    if (bucket === 'paid') {
+export function canOverflow(slot, vault, primary) {
+    if (slot === 'paid') {
         return undefined;
     }
     const { paid } = vault;
@@ -79,21 +78,21 @@ function canOverflow(bucket, vault, primary) {
     }
     return paid;
 }
-async function withGeminiKey(bucket, run, transport) {
+export async function withGeminiKey(slot, run, transport) {
     const wait = transport.wait ?? waitDefault;
-    const primary = requireKey(transport.vault, bucket);
+    const primary = requireKey(transport.vault, slot);
     try {
         return await runWithBackoff(primary, run, wait, 0);
     }
     catch (err) {
-        const paid = canOverflow(bucket, transport.vault, primary);
+        const paid = canOverflow(slot, transport.vault, primary);
         if (!(isQuota(err) && paid)) {
             throw err;
         }
         return await runWithBackoff(paid, run, wait, 0);
     }
 }
-function withApiKey(init, apiKey) {
+export function withApiKey(init, apiKey) {
     const headers = new Headers(init.headers);
     headers.set('x-goog-api-key', apiKey);
     if (!headers.has('Content-Type') && (init.method || 'GET').toUpperCase() !== 'GET') {
@@ -125,26 +124,15 @@ async function fetchWithBackoff(args) {
         return fetchWithBackoff({ ...args, attempt: args.attempt + 1 });
     }
 }
-async function fetchGemini(url, init, bucket, transport) {
+export async function fetchGemini(url, init, slot, transport) {
     const parsed = new URL(url);
     parsed.searchParams.delete('key');
     const href = parsed.toString();
-    const primary = requireKey(transport.vault, bucket);
+    const primary = requireKey(transport.vault, slot);
     let last = await fetchWithBackoff({ href, init, apiKey: primary, transport, attempt: 0 });
-    const paid = canOverflow(bucket, transport.vault, primary);
+    const paid = canOverflow(slot, transport.vault, primary);
     if (last.status === HTTP_QUOTA && paid) {
         last = await fetchWithBackoff({ href, init, apiKey: paid, transport, attempt: 0 });
     }
     return last;
 }
-export { fetchGemini, withGeminiKey };
-exposeForTests('keys', {
-    waitDefault,
-    isQuota,
-    isTransientHttp,
-    isTransientThrown,
-    requireKey,
-    backoffMs,
-    canOverflow,
-    withApiKey,
-});

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

@@ -0,0 +1,46 @@
+/**
+ * Pure protocol framing & serialization for Google Gemini Live WebSocket API (`BidiGenerateContent`).
+ *
+ * All functions are pure data transformations with no network I/O.
+ *
+ * @module
+ */
+import type { InteractionPart, ProviderCompleteRequest, TurnEvent, TurnHistoryMessage, TurnTokens, WireFunctionTool } from '../../../kernel/types.js';
+import { parseToolArgumentsObject } from '../../shared/tool-args.js';
+/** Construct authenticated WebSocket URL for Gemini Live API. */
+export declare function buildGeminiLiveWebSocketUrl(apiKey: string): string;
+export declare function wireFunctionDeclaration(decl: WireFunctionTool): Record<string, unknown>;
+export declare function wireLiveTools(req: ProviderCompleteRequest): Array<Record<string, unknown>>;
+/** Build the initial `setup` message sent once immediately after WebSocket open. */
+export declare function buildGeminiLiveSetupMessage(req: ProviderCompleteRequest): Record<string, unknown>;
+/** Build the `clientContent` message used for seeding conversation history before realtime streaming. */
+export declare function buildGeminiLiveClientContent(history: TurnHistoryMessage[]): Record<string, unknown> | null;
+/** Build a `realtimeInput` message for streaming audio, video, or text chunks. */
+export declare function buildGeminiLiveRealtimeInput(part: InteractionPart): Record<string, unknown>;
+/** Build a `realtimeInput` message with text. */
+export declare function buildGeminiLiveRealtimeText(text: string): Record<string, unknown>;
+/** Build a `toolResponse` message returning the execution result of a tool call. */
+export declare function buildGeminiLiveToolResponse(id: string, name: string, output: unknown): Record<string, unknown>;
+/** Build a batched `toolResponse` for one or more function results. */
+export declare function buildGeminiLiveToolResponses(responses: Array<{
+    id: string;
+    name: string;
+    output: unknown;
+}>): Record<string, unknown>;
+/** Parse raw WebSocket message text / buffer into a JSON record. */
+export type ParsedLiveMessage = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: 'empty' | 'malformed';
+};
+export declare function parseGeminiLiveMessage(raw: unknown): ParsedLiveMessage;
+export declare function parseFunctionArguments(raw: unknown): ReturnType<typeof parseToolArgumentsObject>;
+export declare function extractUsageTokens(metadata: Record<string, unknown>): TurnTokens | undefined;
+/** Parse Gemini goAway.timeLeft (seconds number, "10s", duration string) → ms when known. */
+export declare function parseGoAwayTimeLeftMs(timeLeft: unknown): number | undefined;
+/**
+ * Fold a raw `BidiGenerateContentServerMessage` into normalized `TurnEvent` items.
+ */
+export declare function foldGeminiLiveServerMessage(message: Record<string, unknown> | null | undefined): TurnEvent[];

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

@@ -0,0 +1,515 @@
+/**
+ * Pure protocol framing & serialization for Google Gemini Live WebSocket API (`BidiGenerateContent`).
+ *
+ * All functions are pure data transformations with no network I/O.
+ *
+ * @module
+ */
+import { getTool } from '../../../kernel/tools/registry.js';
+import { groundingFromEvent } from '../../../kernel/engine/delta.js';
+import { base64ToBytes, bytesToBase64, wrapPcmAsWav } from '../../shared/pcm.js';
+import { parseToolArgumentsObject } from '../../shared/tool-args.js';
+import { GEMINI_LIVE_WS_URL } from '../urls.js';
+import { toGeminiOpenApiSchema } from './openapi-schema.js';
+/** Construct authenticated WebSocket URL for Gemini Live API. */
+export function buildGeminiLiveWebSocketUrl(apiKey) {
+    return `${GEMINI_LIVE_WS_URL}?key=${encodeURIComponent(apiKey)}`;
+}
+export function wireFunctionDeclaration(decl) {
+    const parameters = toGeminiOpenApiSchema(decl.parameters);
+    return {
+        name: decl.name,
+        description: decl.description,
+        parameters: parameters && typeof parameters === 'object'
+            ? parameters
+            : { type: 'OBJECT', properties: {} },
+    };
+}
+export function wireLiveTools(req) {
+    const functionDeclarations = [];
+    for (const id of req.builtins) {
+        const entry = getTool(id);
+        if (entry?.type === 'builtin' && entry.wire.live) {
+            functionDeclarations.push({
+                name: id,
+                description: entry.description,
+            });
+        }
+    }
+    for (const decl of req.wireTools ?? []) {
+        functionDeclarations.push(wireFunctionDeclaration(decl));
+    }
+    if (functionDeclarations.length === 0) {
+        return [];
+    }
+    return [{ functionDeclarations }];
+}
+function buildLiveGenerationConfig(req) {
+    const generationConfig = {
+        responseModalities: ['AUDIO'],
+        temperature: req.temperature,
+        maxOutputTokens: req.maxOutputTokens,
+    };
+    if (req.live?.voice) {
+        generationConfig.speechConfig = {
+            voiceConfig: {
+                prebuiltVoiceConfig: {
+                    voiceName: req.live.voice,
+                },
+            },
+        };
+    }
+    if (req.thinking && req.thinking !== 'none') {
+        generationConfig.thinkingConfig = {
+            thinkingLevel: req.thinking,
+        };
+    }
+    return generationConfig;
+}
+function normalizeStartSensitivity(val) {
+    return val?.includes('HIGH') ? 'START_SENSITIVITY_HIGH' : 'START_SENSITIVITY_LOW';
+}
+function normalizeEndSensitivity(val) {
+    return val?.includes('HIGH') ? 'END_SENSITIVITY_HIGH' : 'END_SENSITIVITY_LOW';
+}
+function buildLiveRealtimeInputConfig(vad) {
+    const automaticActivityDetection = {};
+    if (vad.startSensitivity !== undefined) {
+        automaticActivityDetection.startOfSpeechSensitivity = normalizeStartSensitivity(vad.startSensitivity);
+    }
+    if (vad.endSensitivity !== undefined) {
+        automaticActivityDetection.endOfSpeechSensitivity = normalizeEndSensitivity(vad.endSensitivity);
+    }
+    if (vad.prefixPaddingMs !== undefined) {
+        automaticActivityDetection.prefixPaddingMs = vad.prefixPaddingMs;
+    }
+    if (vad.silenceDurationMs !== undefined) {
+        automaticActivityDetection.silenceDurationMs = vad.silenceDurationMs;
+    }
+    const config = {};
+    if (vad.activityHandling !== undefined) {
+        config.activityHandling = vad.activityHandling;
+    }
+    if (Object.keys(automaticActivityDetection).length > 0) {
+        config.automaticActivityDetection = automaticActivityDetection;
+    }
+    return Object.keys(config).length > 0 ? config : undefined;
+}
+function buildLiveSessionResumption(req) {
+    if (req.sessionResumptionHandle) {
+        return { handle: req.sessionResumptionHandle };
+    }
+    if (req.live?.sessionResumption) {
+        return {};
+    }
+    return undefined;
+}
+function liveModelName(apiId) {
+    return apiId.startsWith('models/') ? apiId : `models/${apiId}`;
+}
+function applyLiveOptionalFeatures(live, setup) {
+    if (live?.transcription?.input) {
+        setup.inputAudioTranscription = {};
+    }
+    if (live?.transcription?.output) {
+        setup.outputAudioTranscription = {};
+    }
+    if (live?.proactiveAudio === true) {
+        setup.proactivity = { proactiveAudio: true };
+    }
+}
+/** Build the initial `setup` message sent once immediately after WebSocket open. */
+export function buildGeminiLiveSetupMessage(req) {
+    const live = req.live;
+    const realtimeInputConfig = live?.vad ? buildLiveRealtimeInputConfig(live.vad) : undefined;
+    const tools = wireLiveTools(req);
+    const sessionResumption = buildLiveSessionResumption(req);
+    // Only opt into initial-history gating when we actually have history to seed.
+    // With `initialHistoryInClientContent: true`, Gemini waits for clientContent
+    // after setupComplete and will not start realtime generation until that lands —
+    // empty sessions (e.g. Th30) would hang forever if this were always set.
+    const seedInitialHistory = Boolean(req.history && req.history.length > 0);
+    const setup = {
+        model: liveModelName(req.apiId),
+        generationConfig: buildLiveGenerationConfig(req),
+        systemInstruction: {
+            parts: [{ text: req.system }],
+        },
+        ...(tools.length > 0 ? { tools } : {}),
+        ...(sessionResumption ? { sessionResumption } : {}),
+        ...(live?.contextCompression === 'slidingWindow'
+            ? { contextWindowCompression: { slidingWindow: {} } }
+            : {}),
+        ...(seedInitialHistory ? { historyConfig: { initialHistoryInClientContent: true } } : {}),
+        ...(realtimeInputConfig ? { realtimeInputConfig } : {}),
+    };
+    applyLiveOptionalFeatures(live, setup);
+    return { setup };
+}
+/** Format a single history message into a Google turn object. */
+function historyTurnToGoogleTurn(msg) {
+    const role = msg.role === 'assistant' ? 'model' : 'user';
+    const parts = [];
+    if (msg.content) {
+        parts.push({ text: msg.content });
+    }
+    for (const part of msg.parts ?? []) {
+        if (part.type === 'text') {
+            parts.push({ text: part.text });
+        }
+        else {
+            parts.push({
+                inlineData: {
+                    mimeType: part.mimeType,
+                    data: part.data,
+                },
+            });
+        }
+    }
+    return { role, parts };
+}
+/** Build the `clientContent` message used for seeding conversation history before realtime streaming. */
+export function buildGeminiLiveClientContent(history) {
+    if (!history || history.length === 0) {
+        return null;
+    }
+    return {
+        clientContent: {
+            turns: history.map(historyTurnToGoogleTurn),
+            turnComplete: true,
+        },
+    };
+}
+/** Build a `realtimeInput` message for streaming audio, video, or text chunks. */
+export function buildGeminiLiveRealtimeInput(part) {
+    if (part.type === 'text') {
+        return {
+            realtimeInput: {
+                text: part.text,
+            },
+        };
+    }
+    if (part.type === 'audio') {
+        return {
+            realtimeInput: {
+                audio: {
+                    mimeType: part.mimeType.includes('rate=') ? part.mimeType : 'audio/pcm;rate=16000',
+                    data: part.data,
+                },
+            },
+        };
+    }
+    // Image / video frame
+    return {
+        realtimeInput: {
+            video: {
+                mimeType: part.mimeType || 'image/jpeg',
+                data: part.data,
+            },
+        },
+    };
+}
+/** Build a `realtimeInput` message with text. */
+export function buildGeminiLiveRealtimeText(text) {
+    return {
+        realtimeInput: {
+            text,
+        },
+    };
+}
+/** Build the Gemini Live `response` struct for a function result. */
+function liveFunctionResponsePayload(output) {
+    if (typeof output === 'object' &&
+        output !== null &&
+        'error' in output &&
+        typeof output.error === 'string') {
+        return { error: output.error };
+    }
+    return { result: output };
+}
+/** Build a `toolResponse` message returning the execution result of a tool call. */
+export function buildGeminiLiveToolResponse(id, name, output) {
+    return buildGeminiLiveToolResponses([{ id, name, output }]);
+}
+/** Build a batched `toolResponse` for one or more function results. */
+export function buildGeminiLiveToolResponses(responses) {
+    return {
+        toolResponse: {
+            functionResponses: responses.map(({ id, name, output }) => ({
+                id,
+                name,
+                response: liveFunctionResponsePayload(output),
+            })),
+        },
+    };
+}
+export function parseGeminiLiveMessage(raw) {
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+        if (raw instanceof ArrayBuffer || raw instanceof Uint8Array) {
+            const text = new TextDecoder().decode(raw);
+            return parseGeminiLiveMessage(text);
+        }
+    }
+    if (typeof raw !== 'string' || !raw.trim()) {
+        return { ok: false, reason: 'empty' };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return { ok: true, value: parsed };
+        }
+        return { ok: false, reason: 'malformed' };
+    }
+    catch {
+        return { ok: false, reason: 'malformed' };
+    }
+}
+export function parseFunctionArguments(raw) {
+    return parseToolArgumentsObject(raw);
+}
+function readTokenCount(metadata, camelKey, snakeKey) {
+    const val = metadata[camelKey] ?? metadata[snakeKey];
+    return typeof val === 'number' ? val : 0;
+}
+export function extractUsageTokens(metadata) {
+    const prompt = readTokenCount(metadata, 'promptTokenCount', 'prompt_token_count');
+    const output = readTokenCount(metadata, 'responseTokenCount', 'response_token_count');
+    const thinking = readTokenCount(metadata, 'thoughtsTokenCount', 'thoughts_token_count');
+    const rawTotal = metadata.totalTokenCount ?? metadata.total_token_count;
+    const total = typeof rawTotal === 'number' ? rawTotal : prompt + output;
+    if (prompt === 0 && output === 0 && total === 0) {
+        return undefined;
+    }
+    return {
+        input: prompt,
+        output,
+        thinking: thinking > 0 ? thinking : undefined,
+        total,
+    };
+}
+function foldSessionUpdate(message, events) {
+    const sessionUpdate = message.sessionResumptionUpdate;
+    if (!sessionUpdate || typeof sessionUpdate !== 'object')
+        return;
+    const hasHandle = typeof sessionUpdate.newHandle === 'string' && sessionUpdate.newHandle.length > 0;
+    const hasResumable = typeof sessionUpdate.resumable === 'boolean';
+    if (!hasHandle && !hasResumable)
+        return;
+    events.push({
+        type: 'evidence',
+        ...(hasHandle ? { sessionResumptionHandle: sessionUpdate.newHandle } : {}),
+        evidence: {
+            provider: 'google',
+            kind: 'session_resumption',
+            resumable: hasResumable ? sessionUpdate.resumable : hasHandle,
+            raw: sessionUpdate,
+        },
+    });
+}
+function foldToolCalls(message, events) {
+    const toolCall = message.toolCall;
+    if (!toolCall?.functionCalls || !Array.isArray(toolCall.functionCalls))
+        return;
+    for (const call of toolCall.functionCalls) {
+        if (!call.name)
+            continue;
+        const parsed = parseFunctionArguments(call.args);
+        if (!parsed.ok) {
+            events.push({
+                type: 'tool',
+                tool: {
+                    id: call.id,
+                    name: call.name,
+                    arguments: {},
+                    phase: 'error',
+                    failure: {
+                        code: 'malformed_arguments',
+                        message: parsed.error,
+                        details: { raw: parsed.raw },
+                    },
+                },
+            });
+            continue;
+        }
+        events.push({
+            type: 'tool',
+            tool: {
+                id: call.id,
+                name: call.name,
+                arguments: parsed.value,
+            },
+        });
+    }
+}
+function foldToolCancellations(message, events) {
+    const cancellation = message.toolCallCancellation;
+    const ids = cancellation?.ids;
+    if (!Array.isArray(ids))
+        return;
+    for (const id of ids) {
+        if (typeof id !== 'string' || id.length === 0)
+            continue;
+        events.push({
+            type: 'tool',
+            tool: {
+                id,
+                name: '',
+                phase: 'cancel',
+            },
+        });
+    }
+}
+/** Parse Gemini goAway.timeLeft (seconds number, "10s", duration string) → ms when known. */
+export function parseGoAwayTimeLeftMs(timeLeft) {
+    if (typeof timeLeft === 'number' && Number.isFinite(timeLeft) && timeLeft >= 0) {
+        return Math.round(timeLeft * 1000);
+    }
+    if (typeof timeLeft !== 'string')
+        return undefined;
+    const trimmed = timeLeft.trim();
+    if (!trimmed)
+        return undefined;
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.round(seconds * 1000);
+    }
+    const match = /^(\d+(?:\.\d+)?)\s*s$/i.exec(trimmed);
+    if (match?.[1]) {
+        const s = Number(match[1]);
+        if (Number.isFinite(s) && s >= 0)
+            return Math.round(s * 1000);
+    }
+    return undefined;
+}
+function foldGoAway(message, events) {
+    const goAway = message.goAway;
+    if (!goAway || typeof goAway !== 'object')
+        return;
+    const timeLeftMs = parseGoAwayTimeLeftMs(goAway.timeLeft);
+    events.push({
+        type: 'session',
+        session: {
+            kind: 'closing_soon',
+            ...(timeLeftMs !== undefined ? { timeLeftMs } : {}),
+        },
+    });
+}
+function foldModelPart(part, events) {
+    if (part.text) {
+        if (part.thought) {
+            events.push({ type: 'thought', text: part.text });
+        }
+        else {
+            events.push({ type: 'text', text: part.text });
+        }
+    }
+    if (part.inlineData?.data) {
+        const mime = part.inlineData.mimeType ?? 'audio/pcm;rate=24000';
+        if (mime.startsWith('audio/pcm') ||
+            mime.startsWith('audio/raw') ||
+            mime.startsWith('audio/l16')) {
+            const wav = wrapPcmAsWav(base64ToBytes(part.inlineData.data), 24000);
+            events.push({
+                type: 'media',
+                media: { mimeType: 'audio/wav', data: bytesToBase64(wav) },
+            });
+        }
+        else {
+            events.push({
+                type: 'media',
+                media: { mimeType: mime, data: part.inlineData.data },
+            });
+        }
+    }
+}
+function foldTranscription(text, kind, events, interim) {
+    if (!text)
+        return;
+    events.push({
+        type: 'evidence',
+        text,
+        evidence: {
+            provider: 'google',
+            kind,
+            ...(interim ? { interim: true } : {}),
+        },
+    });
+}
+function foldLiveGrounding(serverContent, events) {
+    const groundingEvent = groundingFromEvent({
+        groundingMetadata: serverContent.groundingMetadata ?? serverContent.grounding_metadata,
+    });
+    if (groundingEvent) {
+        events.push(groundingEvent);
+    }
+    const urlContext = serverContent.urlContextMetadata ?? serverContent.url_context_metadata;
+    if (urlContext && typeof urlContext === 'object') {
+        events.push({
+            type: 'evidence',
+            evidence: {
+                provider: 'google',
+                kind: 'url_context',
+                raw: urlContext,
+            },
+        });
+    }
+}
+function foldServerContent(message, events) {
+    const serverContent = message.serverContent;
+    if (!serverContent || typeof serverContent !== 'object')
+        return;
+    if (serverContent.interrupted === true) {
+        events.push({
+            type: 'done',
+            interrupted: true,
+            stop: { kind: 'interrupted' },
+        });
+    }
+    if (serverContent.waitingForInput === true || serverContent.waiting_for_input === true) {
+        events.push({
+            type: 'session',
+            session: { kind: 'waiting_for_input' },
+        });
+    }
+    if (serverContent.generationComplete === true || serverContent.generation_complete === true) {
+        events.push({
+            type: 'done',
+            stop: { kind: 'generation_complete' },
+        });
+    }
+    const inputTranscription = serverContent.inputTranscription;
+    foldTranscription(inputTranscription?.text, 'input_transcription', events);
+    const interimInput = serverContent.interimInputTranscription;
+    foldTranscription(interimInput?.text, 'input_transcription', events, true);
+    const outputTranscription = serverContent.outputTranscription;
+    foldTranscription(outputTranscription?.text, 'output_transcription', events);
+    const modelTurn = serverContent.modelTurn;
+    for (const part of modelTurn?.parts ?? []) {
+        foldModelPart(part, events);
+    }
+    foldLiveGrounding(serverContent, events);
+}
+function foldUsageMetadata(message, events) {
+    const usageMetadata = message.usageMetadata;
+    if (usageMetadata) {
+        const tokens = extractUsageTokens(usageMetadata);
+        if (tokens) {
+            events.push({ type: 'tokens', tokens });
+        }
+    }
+}
+/**
+ * Fold a raw `BidiGenerateContentServerMessage` into normalized `TurnEvent` items.
+ */
+export function foldGeminiLiveServerMessage(message) {
+    if (!message || typeof message !== 'object')
+        return [];
+    const events = [];
+    foldGoAway(message, events);
+    foldSessionUpdate(message, events);
+    foldToolCalls(message, events);
+    foldToolCancellations(message, events);
+    foldServerContent(message, events);
+    foldUsageMetadata(message, events);
+    return events;
+}

package/esm/src/providers/google/live/openapi-schema.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Gemini Live / OpenAPI Schema 3.0 style type uppercasing for function parameters.
+ * JSON Schema uses lowercase `object`/`string`; Gemini Live expects `OBJECT`/`STRING`.
+ */
+/** Convert JSON-Schema-ish parameters to Gemini Live OpenAPI Schema shape. */
+export declare function toGeminiOpenApiSchema(value: unknown): unknown;