xo-harness 0.2.1 → 0.3.1

package/dist/internal/harness/voice-session.js

@@ -1,6 +1,10 @@
-import { AgentInputSchema, AssistantTurnRequestSchema, AudioChunkSchema, agentInputToText, MessageInputTextSchema, PlayoutProgressSchema, ProviderEventSchema, } from "../protocol/index.js";
+import { AgentInputSchema, AssistantTurnRequestSchema, AudioChunkSchema, agentInputToText, ConversationContextUpdateSchema, MessageInputTextSchema, PlayoutProgressSchema, PlayoutRangeSchema, ProviderCapabilitiesSchema, ProviderEventSchema, } from "../protocol/index.js";
+import { errorMessage } from "../protocol/internal.js";
 import { ReplayEventStream } from "./event-stream.js";
+import { validateRuntimeLimits, } from "./runtime-limits.js";
+import { SessionPersistence } from "./session-persistence.js";
 import { TaskSupervisor } from "./task-supervisor.js";
+import { ToolCallTracker } from "./tool-calls.js";
 import { DEFAULT_MAX_TOOL_RESULT_BYTES, validateMaxToolResultBytes } from "./tool-delivery.js";
 import { allowAllToolPolicy } from "./tool-policy.js";
 import { ToolRuntime } from "./tool-runtime.js";
@@ -9,32 +13,63 @@ export class VoiceSession {
     id;
     #providerSession;
     #store;
-    #events = new ReplayEventStream();
+    #events;
     #controller = new AbortController();
+    #providerController;
+    #capabilities;
+    #providerId;
+    #closeTimeoutMs;
+    #ownAudioBuffers;
+    #recordingEnded = false;
+    #providerClosed = false;
+    #persistenceFailure;
+    #providerFailure;
     #startedAt;
     #toolExecutions = new Set();
     #pendingRecords = new Set();
     #tasks;
     #toolRuntime;
+    #toolCalls = new ToolCallTracker();
+    #toolStatusDelivery = Promise.resolve();
     #providerReadiness;
     #settleProviderReadiness = () => undefined;
     #providerReadinessSettled = false;
     #detachOwnerAbort;
+    #detachProviderFailure;
     #providerPump;
     #closePromise;
     #maxDurationTimer;
-    constructor(options, providerSession, startedAt, startedEvent) {
+    constructor(options, providerSession, startedAt, startedEvent, providerController, capabilities, persistence) {
         this.id = options.sessionId;
         this.#providerSession = providerSession;
-        this.#store = options.store;
+        this.#providerController = providerController;
+        this.#capabilities = capabilities;
+        this.#providerId = options.provider.id;
+        this.#closeTimeoutMs = options.closeTimeoutMs ?? 15_000;
+        this.#ownAudioBuffers =
+            options.runtimeLimits?.maxReplayAudioBytes !== undefined ||
+                options.runtimeLimits?.maxPendingAudioBytes !== undefined;
+        this.#store = persistence;
+        this.#events = new ReplayEventStream({
+            maxEvents: options.runtimeLimits?.maxReplayEvents,
+            maxAudioBytes: options.runtimeLimits?.maxReplayAudioBytes,
+        });
         this.#startedAt = startedAt;
         this.#events.publish(startedEvent);
+        persistence.onFailure = (error) => {
+            this.#persistenceFailure = error;
+            this.#recordingEnded = true;
+            this.#events.fail(error);
+            this.#providerController.abort(error.code);
+            this.#closeFromInternal(error.code);
+        };
         this.#providerReadiness = new Promise((resolve) => {
             this.#settleProviderReadiness = resolve;
         });
         this.#tasks = new TaskSupervisor({
             record: (event) => this.#record(event),
-            sendContext: (event) => this.#providerSession.sendContext(event),
+            // Shutdown still records task outcomes; it must not prompt another spoken response.
+            sendContext: (event) => this.#controller.signal.aborted ? Promise.resolve() : this.#providerSession.sendContext(event),
             flush: () => this.#store.flush(this.id),
             sessionSignal: this.#controller.signal,
             onError: () => {
@@ -56,29 +91,44 @@ export class VoiceSession {
         });
     }
     static async create(options) {
+        // Capture declared behavior before any application/provider startup awaits.
+        const capabilities = Object.freeze(ProviderCapabilitiesSchema.parse(options.provider.capabilities));
+        const runtimeLimits = validateRuntimeLimits(options.runtimeLimits);
+        const persistence = new SessionPersistence(options.store, runtimeLimits);
         const maxToolResultBytes = options.maxToolResultBytes ?? DEFAULT_MAX_TOOL_RESULT_BYTES;
         validateMaxToolResultBytes(maxToolResultBytes);
+        for (const [name, value] of [
+            ["closeTimeoutMs", options.closeTimeoutMs],
+            ["maxDurationMs", options.maxDurationMs],
+        ])
+            if (value !== undefined && (!Number.isInteger(value) || value < 1 || value > 2_147_483_647))
+                throw new Error(`${name} must be a positive integer no greater than 2147483647 ms`);
+        if (options.outputModalities?.includes("text") &&
+            !options.outputModalities.includes("audio") &&
+            capabilities.supportsTextOutput === false) {
+            throw new Error("This provider does not support text-only output");
+        }
         // Registrations made after startup begins belong to future sessions. Execution
         // must use the same catalog that this session advertises to its provider.
         const tools = new ToolRegistry(options.tools.list());
-        const existingEvents = await options.store.list(options.sessionId);
+        const existingEvents = await persistence.list(options.sessionId);
         if (existingEvents.length > 0) {
             throw new Error(`Session id already exists: ${options.sessionId}`);
         }
         const startedAt = performance.now();
-        const startedEvent = await options.store.append(createUnsequencedEvent(options.sessionId, startedAt, {
+        const startedEvent = await persistence.append(createUnsequencedEvent(options.sessionId, startedAt, {
             type: "session.started",
-            formatVersion: 1,
+            formatVersion: capabilities.outputLifecycle === "continuous" ? 2 : 1,
             providerId: options.provider.id,
-            capabilities: options.provider.capabilities,
+            capabilities,
             ...(options.instructions === undefined ? {} : { instructions: options.instructions }),
             ...(options.outputModalities === undefined
                 ? {}
                 : { outputModalities: [...options.outputModalities] }),
         }));
-        await options.store.flush(options.sessionId);
+        await persistence.flush(options.sessionId);
         if (options.signal?.aborted) {
-            await recordFailedCreation(options.store, options.sessionId, startedAt, "owner_revoked");
+            await recordFailedCreation(persistence, options.sessionId, startedAt, "owner_revoked");
             throw options.signal.reason ?? new Error("Session owner revoked before startup");
         }
         const providerController = new AbortController();
@@ -99,29 +149,37 @@ export class VoiceSession {
         catch (error) {
             options.signal?.removeEventListener("abort", abortProviderFromOwner);
             providerController.abort(error);
-            await recordFailedCreation(options.store, options.sessionId, startedAt, options.signal?.aborted ? "owner_revoked" : "provider_create_failed");
+            await recordFailedCreation(persistence, options.sessionId, startedAt, options.signal?.aborted ? "owner_revoked" : "provider_create_failed");
             throw error;
         }
+        const session = new VoiceSession({ ...options, tools, maxToolResultBytes, runtimeLimits }, providerSession, startedAt, startedEvent, providerController, capabilities, persistence);
+        options.signal?.removeEventListener("abort", abortProviderFromOwner);
+        session.#providerPump = session.#pumpProviderEvents();
         if (options.signal?.aborted) {
-            options.signal.removeEventListener("abort", abortProviderFromOwner);
-            await providerSession.close("owner_revoked").catch(() => undefined);
-            await recordFailedCreation(options.store, options.sessionId, startedAt, "owner_revoked");
+            // A returned provider now belongs to a session, including its normal close deadline
+            // and terminal recording. Do not leave startup waiting on an unbounded close handshake.
+            await session.close("owner_revoked");
             throw options.signal.reason ?? new Error("Session owner revoked during startup");
         }
-        const session = new VoiceSession({ ...options, tools, maxToolResultBytes }, providerSession, startedAt, startedEvent);
-        session.#controller.signal.addEventListener("abort", () => providerController.abort(session.#controller.signal.reason), {
-            once: true,
-        });
-        options.signal?.removeEventListener("abort", abortProviderFromOwner);
         if (options.signal) {
             const abortSessionFromOwner = () => {
+                providerController.abort(options.signal?.reason ?? "owner_revoked");
                 session.#closeFromInternal("owner_revoked");
             };
             options.signal.addEventListener("abort", abortSessionFromOwner, { once: true });
             session.#detachOwnerAbort = () => options.signal?.removeEventListener("abort", abortSessionFromOwner);
         }
-        session.#providerPump = session.#pumpProviderEvents();
-        if (options.maxDurationMs !== undefined) {
+        // An ingress failure must fence tools/input even while the event pump awaits storage.
+        // Install after assigning the pump so an already-failed provider can drain safely.
+        const failureSignal = providerSession.failureSignal;
+        if (failureSignal) {
+            const onFailure = () => session.#failProvider(failureSignal.reason);
+            failureSignal.addEventListener("abort", onFailure, { once: true });
+            session.#detachProviderFailure = () => failureSignal.removeEventListener("abort", onFailure);
+            if (failureSignal.aborted)
+                onFailure();
+        }
+        if (options.maxDurationMs !== undefined && !session.#closePromise) {
             session.#maxDurationTimer = setTimeout(() => {
                 session.#closeFromInternal("max_duration_reached");
             }, options.maxDurationMs);
@@ -134,37 +192,88 @@ export class VoiceSession {
     history() {
         return this.#store.list(this.id);
     }
-    async sendAudio(chunk) {
+    /** Separate buffer owners; these counters are not a whole-process memory ceiling. */
+    runtimeStats() {
+        const providerQueue = this.#providerSession.eventQueueStats?.();
+        return {
+            replay: this.#events.stats(),
+            ...this.#store.stats(),
+            ...(providerQueue === undefined ? {} : { providerQueue }),
+        };
+    }
+    /** Immutable startup snapshot; missing optional fields retain their documented legacy meaning. */
+    get capabilities() {
+        return this.#capabilities;
+    }
+    /** Recorded tool/task execution. Completion does not imply a spoken announcement. */
+    toolCalls() {
+        return this.#toolCalls.list();
+    }
+    /** Requests one task's cancellation. The terminal task event, not this result, records settlement. */
+    cancelTask(taskId, reason) {
+        this.#assertOpen();
+        return this.#tasks.requestCancel(taskId, reason);
+    }
+    async sendAudio(chunk, metadata = {}) {
         this.#assertOpen();
         const validated = AudioChunkSchema.parse(chunk);
         // The store reserves this event's log position synchronously, so the durable append
         // and the provider forward can run in parallel without reordering the log. Media
         // latency must not wait on persistence; the call still settles only once both are done.
-        const recorded = this.#record({ type: "audio.input", chunk: validated });
+        const recorded = this.#record({ type: "audio.input", chunk: validated, ...metadata });
         recorded.catch(() => undefined);
+        this.#assertOpen();
         await this.#providerSession.sendAudio(validated);
         await recorded;
     }
     /**
-     * Injects a user turn. Accepts a plain string or multimodal `AgentInput` (text /
-     * image / file parts). The parts are recorded on the `message.input` event, so the
-     * log keeps full fidelity for projection; realtime providers only consume text, so
-     * the collapsed text is what goes over the wire (media-native providers wire later).
+     * Submits a string or text-only AgentInput to the declared provider destination.
+     * Image/file parts are rejected before recording or partial delivery. Applications
+     * route those parts to their own backend. input.delivery records local submission,
+     * not backend consumption; interrupted shutdown can leave delivery unconfirmed.
      */
     async sendText(input) {
         this.#assertOpen();
         const parsed = AgentInputSchema.parse(input);
+        const target = this.#capabilities.textInput ?? "conversation";
+        if (target === "unsupported")
+            throw new Error("This session does not accept typed input; send it to the application backend");
+        if (typeof parsed !== "string" && parsed.some((part) => part.type !== "text"))
+            throw new Error("This session accepts text parts only; send image/file input to the application backend");
         const collapsed = agentInputToText(parsed);
         if (collapsed === "") {
-            throw new Error("Realtime providers require at least one text part in AgentInput");
+            throw new Error("Typed input requires at least one nonempty text part");
         }
         const text = MessageInputTextSchema.parse(collapsed);
-        await this.#record({
+        const recorded = await this.#record({
             type: "message.input",
             text,
             ...(typeof parsed === "string" ? {} : { parts: parsed }),
         });
-        await this.#providerSession.sendText(text);
+        try {
+            this.#assertOpen();
+            await this.#providerSession.sendText(text);
+        }
+        catch (error) {
+            if (!this.#recordingEnded)
+                await this.#record({
+                    type: "input.delivery",
+                    inputId: recorded.id,
+                    providerId: this.#providerId,
+                    target,
+                    phase: "failed",
+                    error: errorMessage(error).slice(0, 2000) || "Input submission failed",
+                });
+            throw error;
+        }
+        if (!this.#recordingEnded)
+            await this.#record({
+                type: "input.delivery",
+                inputId: recorded.id,
+                providerId: this.#providerId,
+                target,
+                phase: "submitted",
+            });
     }
     /**
      * Resolves only after the provider has acknowledged its session configuration.
@@ -183,50 +292,136 @@ export class VoiceSession {
      * creates a synthetic user message in the session log.
      */
     async requestAssistantTurn(request = {}) {
+        if (this.#capabilities.supportsAssistantTurn === false) {
+            throw new Error("This provider does not support assistant turns; use appendContext for conversation steering");
+        }
         const validated = AssistantTurnRequestSchema.parse(request);
         await this.waitUntilReady();
         await this.#record({ type: "assistant.turn.requested" });
+        this.#assertOpen();
         await this.#providerSession.requestAssistantTurn(validated);
     }
     async reportPlayout(progress) {
         this.#assertOpen();
         const validated = PlayoutProgressSchema.parse(progress);
         await this.#record({ type: "playout.progress", ...validated });
+        // An admitted receipt remains valid local evidence when shutdown wins the append.
+        // Avoid further transport work without turning normal playback cleanup into an error.
+        if (this.#closePromise || this.#controller.signal.aborted)
+            return;
         await this.#providerSession.reportPlayout(validated);
     }
+    /** Records local evidence even when a provider cannot consume playout acknowledgements. */
+    async reportPlayoutRange(range) {
+        this.#assertOpen();
+        await this.#record({ type: "playout.range", ...PlayoutRangeSchema.parse(range) });
+    }
+    async appendContext(update) {
+        const validated = ConversationContextUpdateSchema.parse(update);
+        const limit = this.#capabilities.maxContextUpdateBytes;
+        if (limit !== undefined && new TextEncoder().encode(validated.content).byteLength > limit)
+            throw new Error(`Context update exceeds this session's ${limit}-byte UTF-8 limit`);
+        await this.waitUntilReady();
+        if (!this.#providerSession.appendContext)
+            throw new Error("This provider does not support direct context updates");
+        await this.#providerSession.appendContext(validated);
+    }
     close(reason = "client_closed") {
-        this.#closePromise ??= this.#performClose(reason);
+        if (this.#closePromise)
+            return this.#closePromise;
+        const completion = Promise.withResolvers();
+        // Abort callbacks can call close synchronously, so reserve the shared result first.
+        this.#closePromise = completion.promise;
+        void this.#performClose(reason).then(completion.resolve, completion.reject);
         return this.#closePromise;
     }
     #closeFromInternal(reason) {
         void this.close(reason).catch(() => undefined);
     }
+    #failProvider(reason) {
+        if (this.#providerFailure || this.#recordingEnded)
+            return;
+        const error = reason instanceof Error ? reason : new Error(errorMessage(reason));
+        this.#providerFailure = error;
+        this.#controller.abort("provider_error");
+        this.#settleReadiness(false);
+        // Stop subscribers now; accepted durable writes may still settle afterward.
+        this.#events.fail(error);
+        this.#trackRecord(this.#record({ type: "provider.error", message: error.message, recoverable: false }));
+        this.#closeFromInternal("provider_error");
+    }
     async #performClose(reason) {
-        this.#detachOwnerAbort?.();
-        this.#detachOwnerAbort = undefined;
         if (this.#maxDurationTimer)
             clearTimeout(this.#maxDurationTimer);
         this.#controller.abort(reason);
-        await Promise.allSettled([...this.#toolExecutions]);
-        await this.#tasks.cancelAll(reason);
-        try {
-            await this.#providerSession.close(reason);
+        let deadline;
+        const drain = async () => {
+            await Promise.allSettled([...this.#toolExecutions]);
+            await this.#tasks.cancelAll(reason);
+            try {
+                await this.#providerSession.close(reason);
+            }
+            catch (error) {
+                // Keep the original shutdown failure even if this best-effort terminal
+                // observation cannot be persisted. A failed close never confirms usage.
+                await this.#recordProviderClosed("provider_close_failed", false).catch(() => undefined);
+                throw error;
+            }
             await this.#providerPump;
+            // A resolved close method is not a provider finalization receipt. The pump
+            // may have stopped on invalid input or ended without a terminal event.
+            await this.#recordProviderClosed("provider_stream_ended", false);
+        };
+        try {
+            const completed = await Promise.race([
+                drain().then(() => true),
+                new Promise((resolve) => {
+                    deadline = setTimeout(() => resolve(false), this.#closeTimeoutMs);
+                }),
+            ]);
+            if (!completed) {
+                this.#providerController.abort("close_timeout");
+                await this.#recordProviderClosed("close_timeout", false);
+            }
         }
         finally {
+            clearTimeout(deadline);
+            this.#providerController.abort(reason);
+            this.#detachOwnerAbort?.();
+            this.#detachOwnerAbort = undefined;
+            this.#detachProviderFailure?.();
+            this.#detachProviderFailure = undefined;
+            this.#settleReadiness(false);
+            // Fence late/uncooperative producers before the final append; accepted writes retain order.
+            this.#recordingEnded = true;
             await Promise.allSettled([...this.#pendingRecords]);
-            try {
-                await this.#record({ type: "session.ended", reason });
+            await this.#finishRecording(reason);
+        }
+    }
+    async #finishRecording(reason) {
+        try {
+            if (this.#providerFailure) {
+                // Preserve any accepted records, but a lost ingress event cannot become a complete log.
                 await this.#store.flush(this.id);
+                throw this.#providerFailure;
             }
-            finally {
-                this.#events.close();
-            }
+            const ended = await this.#store.append(createUnsequencedEvent(this.id, this.#startedAt, { type: "session.ended", reason }));
+            await this.#store.flush(this.id);
+            this.#events.publish(ended);
+        }
+        catch (error) {
+            this.#events.fail(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        finally {
+            this.#events.close();
         }
     }
     async #pumpProviderEvents() {
         try {
             for await (const candidate of this.#providerSession.events) {
+                if (this.#recordingEnded)
+                    break;
                 const event = ProviderEventSchema.parse(candidate);
                 switch (event.type) {
                     case "ready":
@@ -237,32 +432,33 @@ export class VoiceSession {
                         // Pipelined: the append is enqueued (log position reserved) without stalling
                         // the pump, so a burst of audio deltas cannot delay a trailing tool call or
                         // error behind per-chunk persistence.
-                        this.#trackRecord(this.#record({ type: "audio.output", chunk: event.chunk }));
+                        this.#trackRecord(this.#record(event));
                         break;
                     case "audio.interrupted":
                         this.#trackRecord(this.#record({ type: "audio.interrupted", streamId: event.streamId }));
                         break;
                     case "transcript":
-                        await this.#record({
-                            type: "transcript",
-                            role: event.role,
-                            text: event.text,
-                            ...(event.streamId === undefined ? {} : { streamId: event.streamId }),
-                        });
+                        await this.#record(event);
                         break;
                     case "transcript.delta":
-                        this.#trackRecord(this.#record({
-                            type: "transcript.delta",
-                            role: event.role,
-                            delta: event.delta,
-                            ...(event.streamId === undefined ? {} : { streamId: event.streamId }),
-                        }));
+                    case "backend.output.delta":
+                        this.#trackRecord(this.#record(event));
                         break;
                     case "tool.call":
+                        if (this.#controller.signal.aborted)
+                            break;
                         await this.#record({ type: "tool.requested", call: event.call });
                         this.#trackToolExecution(this.#toolRuntime.execute(event.call));
                         break;
                     case "response.state":
+                    case "transcript.fragment":
+                    case "backend.response":
+                    case "backend.output":
+                    case "backend.tool":
+                    case "delegation.created":
+                    case "context.delivery":
+                    case "usage.duration":
+                    case "tool.delivery_failed":
                         await this.#record(event);
                         break;
                     case "diagnostic":
@@ -286,7 +482,7 @@ export class VoiceSession {
                         break;
                     case "closed":
                         this.#settleReadiness(false);
-                        await this.#record({ type: "provider.closed", reason: event.reason });
+                        await this.#recordProviderClosed(event.reason, event.finalized);
                         this.#closeFromInternal("provider_closed");
                         break;
                 }
@@ -299,10 +495,15 @@ export class VoiceSession {
                     message: errorMessage(error),
                     recoverable: false,
                 });
+                this.#closeFromInternal("provider_error");
             }
         }
         finally {
             this.#settleReadiness(false);
+            // A custom adapter may end its iterator without a terminal receipt. Reuse
+            // shutdown to fence input and seal the log with unconfirmed finalization.
+            if (!this.#controller.signal.aborted)
+                this.#closeFromInternal("provider_stream_ended");
         }
     }
     #settleReadiness(ready) {
@@ -311,6 +512,20 @@ export class VoiceSession {
         this.#providerReadinessSettled = true;
         this.#settleProviderReadiness(ready);
     }
+    async #recordProviderClosed(reason, finalized) {
+        if (this.#providerClosed)
+            return;
+        // Mark before persistence: a transport abort can enqueue the same terminal
+        // observation while the close deadline is recording its fallback.
+        this.#providerClosed = true;
+        if (this.#providerFailure)
+            finalized = false;
+        await this.#record({
+            type: "provider.closed",
+            reason,
+            ...(finalized === undefined ? {} : { finalized }),
+        });
+    }
     #trackToolExecution(execution) {
         this.#toolExecutions.add(execution);
         void execution.then(() => this.#toolExecutions.delete(execution), () => {
@@ -326,16 +541,97 @@ export class VoiceSession {
         });
     }
     async #record(event) {
+        if (this.#recordingEnded)
+            throw new Error("Session recording has ended");
+        if (this.#ownAudioBuffers && (event.type === "audio.input" || event.type === "audio.output")) {
+            const data = event.chunk.data;
+            // A small view can otherwise retain a whole recording or pooled buffer beyond the byte limit.
+            // Storage and replay share this one exact-sized payload; caller/provider references are separate.
+            if (data.byteLength !== data.buffer.byteLength)
+                event = { ...event, chunk: { ...event.chunk, data: Uint8Array.from(data) } };
+        }
         const stored = await this.#store.append(createUnsequencedEvent(this.id, this.#startedAt, event));
-        this.#events.publish(stored);
+        const changed = this.#toolCalls.apply(stored);
+        this.#syncToolStatus(stored, changed);
+        if (!this.#providerFailure)
+            this.#events.publish(stored);
         return stored;
     }
+    /** Status is optional observation: it must not hold up results, tasks, or media. */
+    #sendToolStatus(event) {
+        const delivery = this.#toolStatusDelivery.then(async () => {
+            if (this.#controller.signal.aborted)
+                return;
+            await this.#store.flush(this.id);
+            if (this.#controller.signal.aborted)
+                return;
+            if (this.#recordingEnded || this.#providerClosed || this.#providerController.signal.aborted)
+                throw new Error("Provider closed before context could be submitted");
+            const current = this.#toolCalls.get(event.call.callId);
+            // A slow transport may leave progress queued after its execution already settled.
+            if (!current || toolStatus(current) !== event.status)
+                return;
+            await this.#providerSession.sendContext(event);
+        });
+        // Each caller records its own delivery failure; one failure must not poison later updates.
+        this.#toolStatusDelivery = delivery.catch(() => undefined);
+        return delivery;
+    }
+    #syncToolStatus(event, changed) {
+        if (!this.#capabilities.supportsToolStatusContext || this.#controller.signal.aborted)
+            return;
+        // A request may still be denied by admission. Report execution only after tool.started.
+        const call = event.type === "tool.started" ? this.#toolCalls.get(event.callId) : changed;
+        if (!call)
+            return;
+        if (event.type !== "tool.started" &&
+            event.type !== "tool.completed" &&
+            event.type !== "tool.failed" &&
+            event.type !== "tool.denied" &&
+            event.type !== "task.completed" &&
+            event.type !== "task.failed" &&
+            event.type !== "task.cancelled")
+            return;
+        const contextId = `tool-status:${event.id}`;
+        this.#toolStatusDelivery = this.#sendToolStatus({
+            type: "tool.status",
+            contextId,
+            sourceSequence: event.sequence,
+            call: { callId: call.callId, name: call.name, arguments: call.state.input },
+            status: toolStatus(call),
+            ...(call.taskId === undefined ? {} : { taskId: call.taskId }),
+        }).catch(async (error) => {
+            if (this.#recordingEnded)
+                return;
+            await this.#record({
+                type: "context.delivery",
+                contextId,
+                callId: call.callId,
+                ...(call.taskId === undefined ? {} : { taskId: call.taskId }),
+                kind: "thinking",
+                phase: "failed",
+                message: error instanceof Error ? error.message.slice(0, 2000) : "Tool status context failed",
+            });
+        });
+        void this.#toolStatusDelivery.catch(() => this.#closeFromInternal("storage_error"));
+    }
     #assertOpen() {
+        if (this.#persistenceFailure)
+            throw this.#persistenceFailure;
+        if (this.#providerFailure)
+            throw this.#providerFailure;
         if (this.#closePromise || this.#controller.signal.aborted) {
             throw new Error("Voice session is closed");
         }
     }
 }
+function toolStatus(call) {
+    if (call.state.status === "running")
+        return "running";
+    if (call.state.outcome.type === "accepted_task")
+        return "background";
+    return call.state.outcome.type === "failed" ? "failed" : "completed";
+}
 function createUnsequencedEvent(sessionId, startedAt, event) {
     return {
         ...event,
@@ -357,6 +653,3 @@ async function recordFailedCreation(store, sessionId, startedAt, reason) {
         // Preserve the provider creation error; the original started event remains inspectable.
     }
 }
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/internal/harness/xo.d.ts

@@ -1,9 +1,8 @@
-import type { OutputModality } from "../protocol/index.js";
-import type { VoiceProvider } from "../provider/index.js";
 import type { EventStore } from "../storage/index.js";
+import type { SessionRuntimeLimits } from "./runtime-limits.js";
 import type { ToolPolicy } from "./tool-policy.js";
 import { ToolRegistry, type VoiceTool } from "./tools.js";
-import { VoiceSession } from "./voice-session.js";
+import { type CreateVoiceSessionOptions, VoiceSession } from "./voice-session.js";
 export interface XOOptions {
     store: EventStore;
     tools?: readonly VoiceTool[];
@@ -14,21 +13,17 @@ export interface XOOptions {
      * An integer of at least 128, or Infinity (the default). The log keeps the full outcome.
      */
     maxToolResultBytes?: number;
+    runtimeLimits?: SessionRuntimeLimits;
 }
-export interface StartSessionOptions {
-    provider: VoiceProvider;
-    /** Cancels provider startup and closes the live session when its owner is revoked. */
-    signal?: AbortSignal;
+/** Session options share the low-level contract; XO supplies storage and the tool registry. */
+export interface StartSessionOptions extends Omit<CreateVoiceSessionOptions, "sessionId" | "store" | "tools"> {
     sessionId?: string;
     /** Overrides the harness-level tool policy for this session. */
     toolPolicy?: ToolPolicy;
     /** Overrides the harness-level delivery budget for this session. */
     maxToolResultBytes?: number;
-    instructions?: string;
-    /** What the model may produce this session; ["text"] disables audio output. Default: audio. */
-    outputModalities?: readonly OutputModality[];
-    /** Closes the session with max_duration_reached once elapsed. Guards runaway metered sessions. */
-    maxDurationMs?: number;
+    /** Overrides individual harness runtime limits for this session. */
+    runtimeLimits?: SessionRuntimeLimits;
 }
 export declare class XO {
     #private;