theorum 1.0.0 → 1.1.3

package/esm/src/observability/trace.js

@@ -2,22 +2,21 @@
  * Trace sink primitives for THEORUM.
  *
  * Tracing is host-injected: the kernel can write to a provided sink, a memory
- * sink, a JSONL directory, or a noop sink. It does not read environment
- * variables or own a database destination.
+ * sink, a JSONL directory, or a noop sink. Profiles declare policy via
+ * `observability`; hosts register named destinations. THEORUM does not read
+ * environment variables or own a database destination.
  *
  * @module
  */
 import * as dntShim from "../../_dnt.shims.js";
-const RETAIN_DAYS = 14;
+const DEFAULT_RETAIN_DAYS = 14;
 const HOURS_PER_DAY = 24;
 const MIN_PER_HOUR = 60;
 const SEC_PER_MIN = 60;
 const MS_PER_SEC = 1000;
-const RETAIN_MS = RETAIN_DAYS * HOURS_PER_DAY * MIN_PER_HOUR * SEC_PER_MIN * MS_PER_SEC;
 const KIB = 1024;
 const MIB = KIB * KIB;
-const ROTATE_MIB = 32;
-const ROTATE_BYTES = ROTATE_MIB * MIB;
+const DEFAULT_ROTATE_MIB = 32;
 const FILE_DAY = /^turns-(\d{4}-\d{2}-\d{2})(?:-\d+)?\.jsonl$/;
 /**
  * Write a trace record without allowing trace failures to fail the turn.
@@ -55,8 +54,9 @@ function dayStamp(ms) {
 function fileDay(name) {
     return FILE_DAY.exec(name)?.[1];
 }
-async function pruneTraces(dir, now) {
-    const cutoff = now - RETAIN_MS;
+async function pruneTraces(dir, now, retainForDays) {
+    const retainMs = retainForDays * HOURS_PER_DAY * MIN_PER_HOUR * SEC_PER_MIN * MS_PER_SEC;
+    const cutoff = now - retainMs;
     for await (const entry of dntShim.Deno.readDir(dir)) {
         const day = fileDay(entry.name);
         if (day && Date.parse(`${day}T00:00:00.000Z`) < cutoff) {
@@ -64,12 +64,12 @@ async function pruneTraces(dir, now) {
         }
     }
 }
-async function pickFile(dir, now) {
+async function pickFile(dir, now, rotateBytes) {
     const day = dayStamp(now);
     const base = `${dir}/turns-${day}.jsonl`;
     try {
         const info = await dntShim.Deno.stat(base);
-        if ((info.size ?? 0) < ROTATE_BYTES) {
+        if ((info.size ?? 0) < rotateBytes) {
             return base;
         }
     }
@@ -78,14 +78,23 @@ async function pickFile(dir, now) {
     }
     return `${dir}/turns-${day}-${now}.jsonl`;
 }
-/** Trace sink that writes daily rotating JSONL files under a host-selected directory. */
-function jsonlSink(dir, now = Date.now) {
+/**
+ * Trace sink that writes daily rotating JSONL files under a host-selected directory.
+ *
+ * @param dir - Absolute host-chosen directory
+ * @param optionsOrNow - Retention/rotate options, or a `now` clock (legacy)
+ */
+function jsonlSink(dir, optionsOrNow) {
+    const options = typeof optionsOrNow === 'function' ? { now: optionsOrNow } : (optionsOrNow ?? {});
+    const now = options.now ?? Date.now;
+    const retainForDays = options.retainForDays ?? DEFAULT_RETAIN_DAYS;
+    const rotateBytes = (options.rotateAfterMiB ?? DEFAULT_ROTATE_MIB) * MIB;
     return {
         write: async (record) => {
             const at = now();
             await dntShim.Deno.mkdir(dir, { recursive: true });
-            await pruneTraces(dir, at);
-            const path = await pickFile(dir, at);
+            await pruneTraces(dir, at, retainForDays);
+            const path = await pickFile(dir, at, rotateBytes);
             await dntShim.Deno.writeTextFile(path, `${JSON.stringify(record)}\n`, { append: true });
         },
     };

package/esm/src/observability/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Profile observability vocabulary — destination, scrub, and include policy.
+ *
+ * This module is the single source of truth for observability profile types. It
+ * must not import from `src/kernel/`: the kernel type-imports
+ * `ProfileObservabilitySpec` for `ProfileCommon.observability`, and that edge
+ * stays one-directional.
+ *
+ * @module
+ */
+import type { TraceSink } from './trace-sink.js';
+/** Which payloads land in each TraceRecord. Omitted keys use resolved defaults. */
+export interface TraceIncludeSpec {
+    /** Scrubbed provider HTTP/SSE rows. Default: true. */
+    upstreamLog?: boolean;
+    /** Scrubbed outbound request body. Default: false. */
+    outboundWire?: boolean;
+    /** Verbatim provider step JSON (`events[].evidence.raw`). Default: false. */
+    evidenceRaw?: boolean;
+    /** Token / usage fields. Default: true. */
+    usage?: boolean;
+    /**
+     * Persist `{ type: 'guardrail' }` decisions into the TraceRecord. Default: true.
+     */
+    guardrailDecisions?: boolean;
+    /**
+     * Keep `GuardrailHit.match` (exact matched substring, capped) on guardrail
+     * events in the live stream and TraceRecord. Default: false — debugging only;
+     * treat like server logs when enabled.
+     */
+    guardrailMatchPreview?: boolean;
+}
+/**
+ * Scrubbing of what is written — independent of turn-path `profile.guardrails`.
+ * Defaults are safe for a host-confidential store.
+ */
+export interface TraceScrubSpec {
+    /** Strip credentials / PII spans in stored text. Default: true. */
+    sensitive?: boolean;
+    /** Strip injection spans in the stored request copy. Default: true. */
+    injection?: boolean;
+    /** Never persist the canary token. Default: true. */
+    canary?: boolean;
+}
+/**
+ * Profile observability — what to record, and where.
+ *
+ * Omit the whole block → no tracing (noop). Prefer `writeTo: '<registered-id>'`
+ * in shared profiles; pass a TraceSink only for tests / custom exporters.
+ */
+export interface ProfileObservabilitySpec {
+    /**
+     * Destination for completed turn records.
+     *
+     * - `false` — explicitly off
+     * - `string` — host-registered destination id (`registerTraceDestination`)
+     * - `TraceSink` — inline writer (tests, OTEL bridge, etc.)
+     *
+     * `runTurn(..., sink)` still overrides this for one call.
+     */
+    writeTo?: false | string | TraceSink;
+    /**
+     * Fraction of turns to record, 0–1 inclusive.
+     * Omitted → 1 (every turn). `0` means record none.
+     */
+    sampleRate?: number;
+    /** Which payloads land in each TraceRecord. */
+    include?: TraceIncludeSpec;
+    /**
+     * Scrubbing of stored records — independent of turn-path guardrails.
+     * Defaults stay on even when `guardrails.redactSensitive` is false.
+     */
+    scrub?: TraceScrubSpec;
+    /** JSONL retention days when the resolved destination is JSONL. Default: 14. */
+    retainForDays?: number;
+    /** JSONL rotate threshold in MiB when the resolved destination is JSONL. Default: 32. */
+    rotateAfterMiB?: number;
+    /**
+     * Called when record build or destination write fails.
+     * Must not throw; tracing never fails the turn.
+     */
+    onWriteError?: (err: unknown) => void;
+}
+/** Resolved include flags after defaults. */
+export interface ResolvedTraceInclude {
+    upstreamLog: boolean;
+    outboundWire: boolean;
+    evidenceRaw: boolean;
+    usage: boolean;
+    guardrailDecisions: boolean;
+    guardrailMatchPreview: boolean;
+}
+/** Resolved scrub flags after defaults. */
+export interface ResolvedTraceScrub {
+    sensitive: boolean;
+    injection: boolean;
+    canary: boolean;
+}
+/**
+ * Observability policy with defaults applied.
+ * Every path resolves through `resolveObservabilityPolicy`.
+ */
+export interface ResolvedObservabilityPolicy {
+    /** False when omitted, `writeTo: false`, or sampleRate drops the turn. */
+    record: boolean;
+    writeTo: false | string | TraceSink | undefined;
+    sampleRate: number;
+    include: ResolvedTraceInclude;
+    scrub: ResolvedTraceScrub;
+    retainForDays: number;
+    rotateAfterMiB: number;
+    onWriteError?: (err: unknown) => void;
+}

package/esm/src/observability/types.js

@@ -0,0 +1,11 @@
+/**
+ * Profile observability vocabulary — destination, scrub, and include policy.
+ *
+ * This module is the single source of truth for observability profile types. It
+ * must not import from `src/kernel/`: the kernel type-imports
+ * `ProfileObservabilitySpec` for `ProfileCommon.observability`, and that edge
+ * stays one-directional.
+ *
+ * @module
+ */
+export {};

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

@@ -1,15 +1,15 @@
 /**
  * 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 or image role). Adapters under this folder are internal implementation.
+ * Routes from the selected model binding's `protocol` / `provider` (and whether the
+ * profile is a speech or image role). Adapters under this folder are internal implementation.
  *
  * 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 { ModelId, ModelProvider, Profile } from '../kernel/types.js';
 import type { GeminiTransport } from './google/keys.js';
 import type { LocalProviderConfig, OpenAiGatewayConfig } from './types.js';
 /** Credentials supplied by the host when creating a provider. */
@@ -32,5 +32,8 @@ export declare function isImageRole(profile: Profile): boolean;
 /**
  * Create a `ModelProvider` for a turn-based profile (text / image / speech).
  * Live profiles use `runSession` — `createProvider` rejects geminiLive.
+ *
+ * When a profile declares multiple models, pass `modelId` to pick the binding used
+ * for adapter selection (defaults to `defaultModel` or the sole model key).
  */
-export declare function createProvider(profile: Profile, options?: CreateProviderOptions): ModelProvider;
+export declare function createProvider(profile: Profile, options?: CreateProviderOptions, modelId?: ModelId): ModelProvider;

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

@@ -1,8 +1,8 @@
 /**
  * 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 or image role). Adapters under this folder are internal implementation.
+ * Routes from the selected model binding's `protocol` / `provider` (and whether the
+ * profile is a speech or image role). Adapters under this folder are internal implementation.
  *
  * Every adapter graph is loaded only when that transport's first `complete` runs —
  * not when this module is imported.
@@ -10,6 +10,8 @@
  * @module
  */
 import { TheorumError } from '../guardrails/error.js';
+import { requireModelProfile } from '../kernel/registry/resolve.js';
+import { soleModelId } from '../kernel/registry/sole-model.js';
 import { isValidPair } from '../kernel/schema.js';
 import { markModuleLoad } from './probe.js';
 export function isSpeechRole(profile) {
@@ -18,6 +20,18 @@ export function isSpeechRole(profile) {
 export function isImageRole(profile) {
     return profile.type === 'image';
 }
+function bindingForProvider(input, modelId) {
+    const profile = requireModelProfile(input, 'createProvider');
+    const id = modelId ?? profile.defaultModel ?? soleModelId(profile.models);
+    if (!id) {
+        throw new TheorumError(`createProvider: profile '${profile.id}' must set defaultModel when multiple models are declared`);
+    }
+    const binding = profile.models[id];
+    if (!binding) {
+        throw new TheorumError(`createProvider: profile '${profile.id}' has no model '${id}'`);
+    }
+    return binding;
+}
 /**
  * Lazy-load an adapter on first `complete`. When `THEORUM_IMPORT_PROBE=1`,
  * emits `LOADED:<label>` exactly once at load time (import-isolation tests).
@@ -52,9 +66,12 @@ function lazyLocal(config) {
 /**
  * Create a `ModelProvider` for a turn-based profile (text / image / speech).
  * Live profiles use `runSession` — `createProvider` rejects geminiLive.
+ *
+ * When a profile declares multiple models, pass `modelId` to pick the binding used
+ * for adapter selection (defaults to `defaultModel` or the sole model key).
  */
-export function createProvider(profile, options = {}) {
-    const { protocol, provider } = profile.model;
+export function createProvider(profile, options = {}, modelId) {
+    const { protocol, provider } = bindingForProvider(profile, modelId);
     if (!isValidPair(protocol, provider)) {
         throw new TheorumError(`createProvider: unsupported protocol/provider pair '${protocol}'/'${provider}'`);
     }
@@ -85,8 +102,5 @@ export function createProvider(profile, options = {}) {
         }
         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}'`);
 }

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

@@ -3,6 +3,14 @@ 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>;
+/**
+ * Map one host history message to Interactions input step(s).
+ *
+ * OpenAI-shaped assistant `tool_calls` (often with no `content`) become
+ * `function_call` steps — never empty `model_output` text.
+ */
+export declare function historySteps(msg: TurnHistoryMessage): Record<string, unknown>[];
+/** Single-step helper for simple messages (first of {@link historySteps}). */
 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[];

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

@@ -1,4 +1,5 @@
 import { TheorumError } from '../../../guardrails/error.js';
+import { wireInteractionPart } from '../../../kernel/interaction-parts.js';
 import { getStructured } from '../../../kernel/registry/schemas.js';
 import { getTool } from '../../../kernel/tools/registry.js';
 export function camelToSnake(key) {
@@ -24,35 +25,91 @@ export function toGoogleValue(value) {
     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 };
+    return wireInteractionPart(part);
 }
 const USER_INPUT = 'user_input';
 export function userInputStep(parts) {
     return { type: USER_INPUT, content: parts.map(wirePart) };
 }
 function functionResultStep(msg) {
+    const result = msg.parts && msg.parts.length > 0
+        ? msg.parts.map(wirePart)
+        : [{ type: 'text', text: msg.content ?? '' }];
     return {
         type: 'function_result',
         name: msg.name ?? '',
         call_id: msg.tool_call_id ?? '',
-        result: [{ type: 'text', text: msg.content ?? '' }],
+        result,
     };
 }
-export function historyStep(msg) {
-    if (msg.role === 'tool') {
-        return functionResultStep(msg);
+/** Parse OpenAI-style tool-call `arguments` JSON into an Interactions object. */
+function functionCallArguments(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return {};
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return { value: parsed };
+    }
+    catch {
+        return { value: raw };
     }
-    const isAssistant = msg.role === 'assistant';
+}
+function functionCallStep(call) {
+    const step = {
+        type: 'function_call',
+        id: call.id,
+        name: call.function.name,
+        arguments: functionCallArguments(call.function.arguments),
+    };
+    if (call.thoughtSignature) {
+        step.thoughtSignature = call.thoughtSignature;
+    }
+    return step;
+}
+function textOrPartsStep(role, msg) {
     // Google Interactions input steps: assistant history is `model_output` (not `model_turn`).
-    const type = isAssistant ? 'model_output' : 'user_input';
+    const type = role === 'assistant' ? '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 ?? '' }] };
 }
+/**
+ * Map one host history message to Interactions input step(s).
+ *
+ * OpenAI-shaped assistant `tool_calls` (often with no `content`) become
+ * `function_call` steps — never empty `model_output` text.
+ */
+export function historySteps(msg) {
+    if (msg.role === 'tool') {
+        return [functionResultStep(msg)];
+    }
+    if (msg.role === 'assistant' && msg.tool_calls && msg.tool_calls.length > 0) {
+        const steps = [];
+        const hasParts = Boolean(msg.parts && msg.parts.length > 0);
+        const hasText = Boolean(msg.content?.trim());
+        if (hasParts || hasText) {
+            steps.push(textOrPartsStep('assistant', msg));
+        }
+        for (const call of msg.tool_calls) {
+            steps.push(functionCallStep(call));
+        }
+        return steps;
+    }
+    if (msg.role === 'assistant') {
+        return [textOrPartsStep('assistant', msg)];
+    }
+    return [textOrPartsStep('user', msg)];
+}
+/** Single-step helper for simple messages (first of {@link historySteps}). */
+export function historyStep(msg) {
+    const steps = historySteps(msg);
+    return steps[0] ?? { type: 'user_input', content: [{ type: 'text', text: '' }] };
+}
 export function systemHoldsUserInput(system, parts) {
     for (const part of parts) {
         if (part.type === 'text' && part.text && system.includes(part.text)) {
@@ -154,7 +211,7 @@ export function inputStepsFromRequest(req) {
     }
     const inputSteps = [];
     for (const h of req.history ?? []) {
-        inputSteps.push(historyStep(h));
+        inputSteps.push(...historySteps(h));
     }
     if (req.input.length > 0 || inputSteps.length === 0) {
         inputSteps.push(userInputStep(req.input));
@@ -189,8 +246,12 @@ export function baseInteractionsBody(req) {
         attachSpeechConfig(req, generationConfig);
     }
     else {
-        generationConfig.thinkingLevel = req.thinking;
-        generationConfig.thinkingSummaries = req.summaries;
+        if (req.thinking) {
+            generationConfig.thinkingLevel = req.thinking;
+        }
+        if (req.summaries) {
+            generationConfig.thinkingSummaries = req.summaries;
+        }
     }
     return {
         model: req.apiId,

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

@@ -16,7 +16,7 @@ export declare function buildGeminiLiveSetupMessage(req: ProviderCompleteRequest
 /** 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>;
+export declare function buildGeminiLiveRealtimeInput(input: 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. */
@@ -37,9 +37,12 @@ export type ParsedLiveMessage = {
 };
 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;
+export declare function extractLiveUsageTokens(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;
+export type LiveInteractionStatus = 'IN_PROGRESS' | 'IDLE';
+/** Read the server-side `interactionStatus` when the message carries one. */
+export declare function readLiveInteractionStatus(message: Record<string, unknown>): LiveInteractionStatus | undefined;
 /**
  * Fold a raw `BidiGenerateContentServerMessage` into normalized `TurnEvent` items.
  */

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

@@ -5,8 +5,10 @@
  *
  * @module
  */
-import { getTool } from '../../../kernel/tools/registry.js';
+import { TheorumError } from '../../../guardrails/error.js';
 import { groundingFromEvent } from '../../../kernel/engine/delta.js';
+import { isMediaRefPart } from '../../../kernel/interaction-parts.js';
+import { getTool } from '../../../kernel/tools/registry.js';
 import { base64ToBytes, bytesToBase64, wrapPcmAsWav } from '../../shared/pcm.js';
 import { parseToolArgumentsObject } from '../../shared/tool-args.js';
 import { GEMINI_LIVE_WS_URL } from '../urls.js';
@@ -15,11 +17,18 @@ import { toGeminiOpenApiSchema } from './openapi-schema.js';
 export function buildGeminiLiveWebSocketUrl(apiKey) {
     return `${GEMINI_LIVE_WS_URL}?key=${encodeURIComponent(apiKey)}`;
 }
+/**
+ * Live tools are always declared non-blocking: the kernel session already runs
+ * tool execution asynchronously and honours `toolCallCancellation`, so the model
+ * is free to keep speaking while a call is in flight.
+ */
+const LIVE_FUNCTION_BEHAVIOR = 'NON_BLOCKING';
 export function wireFunctionDeclaration(decl) {
     const parameters = toGeminiOpenApiSchema(decl.parameters);
     return {
         name: decl.name,
         description: decl.description,
+        behavior: LIVE_FUNCTION_BEHAVIOR,
         parameters: parameters && typeof parameters === 'object'
             ? parameters
             : { type: 'OBJECT', properties: {} },
@@ -33,6 +42,7 @@ export function wireLiveTools(req) {
             functionDeclarations.push({
                 name: id,
                 description: entry.description,
+                behavior: LIVE_FUNCTION_BEHAVIOR,
             });
         }
     }
@@ -146,6 +156,17 @@ export function buildGeminiLiveSetupMessage(req) {
     applyLiveOptionalFeatures(live, setup);
     return { setup };
 }
+/** Live carries inline bytes only — provider file references are rejected until support is verified. */
+function inlineMediaPart(part) {
+    if (isMediaRefPart(part)) {
+        throw new TheorumError('media references are not supported on geminiLive');
+    }
+    return part;
+}
+function inlineData(part) {
+    const inline = inlineMediaPart(part);
+    return { mimeType: inline.mimeType, data: inline.data };
+}
 /** Format a single history message into a Google turn object. */
 function historyTurnToGoogleTurn(msg) {
     const role = msg.role === 'assistant' ? 'model' : 'user';
@@ -158,12 +179,7 @@ function historyTurnToGoogleTurn(msg) {
             parts.push({ text: part.text });
         }
         else {
-            parts.push({
-                inlineData: {
-                    mimeType: part.mimeType,
-                    data: part.data,
-                },
-            });
+            parts.push({ inlineData: inlineData(part) });
         }
     }
     return { role, parts };
@@ -181,14 +197,15 @@ export function buildGeminiLiveClientContent(history) {
     };
 }
 /** Build a `realtimeInput` message for streaming audio, video, or text chunks. */
-export function buildGeminiLiveRealtimeInput(part) {
-    if (part.type === 'text') {
+export function buildGeminiLiveRealtimeInput(input) {
+    if (input.type === 'text') {
         return {
             realtimeInput: {
-                text: part.text,
+                text: input.text,
             },
         };
     }
+    const part = inlineMediaPart(input);
     if (part.type === 'audio') {
         return {
             realtimeInput: {
@@ -271,7 +288,7 @@ function readTokenCount(metadata, camelKey, snakeKey) {
     const val = metadata[camelKey] ?? metadata[snakeKey];
     return typeof val === 'number' ? val : 0;
 }
-export function extractUsageTokens(metadata) {
+export function extractLiveUsageTokens(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');
@@ -454,6 +471,22 @@ function foldLiveGrounding(serverContent, events) {
         });
     }
 }
+/** Read the server-side `interactionStatus` when the message carries one. */
+export function readLiveInteractionStatus(message) {
+    const raw = message.interactionStatus ?? message.interaction_status;
+    if (raw === 'IN_PROGRESS' || raw === 'IDLE')
+        return raw;
+    return undefined;
+}
+function foldInteractionStatus(message, events) {
+    const status = readLiveInteractionStatus(message);
+    if (!status)
+        return;
+    events.push({
+        type: 'session',
+        session: { kind: status === 'IDLE' ? 'idle' : 'working' },
+    });
+}
 function foldServerContent(message, events) {
     const serverContent = message.serverContent;
     if (!serverContent || typeof serverContent !== 'object')
@@ -488,11 +521,14 @@ function foldServerContent(message, events) {
         foldModelPart(part, events);
     }
     foldLiveGrounding(serverContent, events);
+    if (serverContent.turnComplete === true || serverContent.turn_complete === true) {
+        events.push({ type: 'session', session: { kind: 'turn_complete' } });
+    }
 }
 function foldUsageMetadata(message, events) {
     const usageMetadata = message.usageMetadata;
     if (usageMetadata) {
-        const tokens = extractUsageTokens(usageMetadata);
+        const tokens = extractLiveUsageTokens(usageMetadata);
         if (tokens) {
             events.push({ type: 'tokens', tokens });
         }
@@ -510,6 +546,7 @@ export function foldGeminiLiveServerMessage(message) {
     foldToolCalls(message, events);
     foldToolCancellations(message, events);
     foldServerContent(message, events);
+    foldInteractionStatus(message, events);
     foldUsageMetadata(message, events);
     return events;
 }

package/esm/src/providers/google/live/openapi-schema.js

@@ -12,8 +12,9 @@ function convertGeminiSchemaType(value) {
     const converted = {};
     if (schemaTypes.includes('null'))
         converted.nullable = true;
-    if (nonNullTypes.length === 1)
-        converted.type = nonNullTypes[0].toUpperCase();
+    const [onlyType] = nonNullTypes;
+    if (onlyType !== undefined && nonNullTypes.length === 1)
+        converted.type = onlyType.toUpperCase();
     if (nonNullTypes.length > 1) {
         converted.anyOf = nonNullTypes.map((item) => ({ type: item.toUpperCase() }));
     }

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

@@ -32,5 +32,14 @@ export interface LiveQueue {
     isClosed: () => boolean;
 }
 export declare function createLiveQueue(): LiveQueue;
+/**
+ * Conversational cycle boundary.
+ *
+ * When the server reports `interactionStatus`, that is authoritative: `IDLE`
+ * closes the cycle and `IN_PROGRESS` keeps it open even across `turnComplete`
+ * (background reasoning / async tools may still produce output). Without the
+ * field, `turnComplete` is the boundary as before.
+ */
+export declare function turnPhaseFromMessage(message: Record<string, unknown>, events: TurnEvent[]): LiveTurnPhase;
 /** Attach handlers that keep the socket open across conversational turns. */
 export declare function attachLiveSessionHandlers(ws: WebSocket, liveQueue: LiveQueue): void;