xo-harness 0.2.0 → 0.3.0

package/dist/internal/harness/socket-bridge.js

@@ -1,9 +1,9 @@
-import { MessageInputTextSchema, OutputModalitySchema, } from "../protocol/index.js";
+import { MessageInputTextSchema, OutputModalitySchema, PlayoutRangeSchema, } from "../protocol/index.js";
 import { z } from "zod";
 /**
  * The client wire protocol every XO transport speaks:
  * - text frames are JSON control messages (start / playout / stop up; started / event /
- *   error / closed down),
+ *   interrupt / error / closed down),
  * - binary frames are PCM16 mono audio (microphone up; length-prefixed model audio down:
  *   u32le header length, JSON header, PCM bytes).
  *
@@ -33,6 +33,7 @@ export const VoiceClientMessageSchema = z.discriminatedUnion("type", [
         streamId: z.string().min(1),
         playedThroughSample: z.number().int().nonnegative(),
     }),
+    PlayoutRangeSchema.safeExtend({ type: z.literal("playout.range") }),
     /** Graceful end; the server still delivers the trailing events and a closed frame. */
     z.object({ type: z.literal("stop"), reason: z.string().min(1).optional() }),
 ]);
@@ -40,15 +41,35 @@ export const VOICE_BRIDGE_INPUT_SAMPLE_RATE = 24_000;
 export class VoiceSocketBridge {
     #socket;
     #startSession;
+    #onStarted;
+    #shouldSendEvent;
+    #onError;
+    #startupCloseTimeoutMs;
     #inputSampleRate;
+    #workController = new AbortController();
+    #startupController;
+    #startup;
+    #eventPump;
+    #teardownPromise;
+    #closeReason;
+    #socketFailed = false;
     #session;
     #sequence = 0;
     #startSample = 0;
     #closing = false;
     #sessionEnded = false;
+    #starting = false;
+    #ready = false;
     constructor(options) {
+        const timeout = options.startupCloseTimeoutMs ?? 5_000;
+        if (!Number.isInteger(timeout) || timeout < 1 || timeout > 2_147_483_647)
+            throw new Error("startupCloseTimeoutMs must be a positive integer no greater than 2147483647 ms");
         this.#socket = options.socket;
         this.#startSession = options.startSession;
+        this.#onStarted = options.onStarted;
+        this.#shouldSendEvent = options.shouldSendEvent;
+        this.#onError = options.onError;
+        this.#startupCloseTimeoutMs = timeout;
         this.#inputSampleRate = options.inputSampleRate ?? VOICE_BRIDGE_INPUT_SAMPLE_RATE;
     }
     /** Feed every text frame from the client socket here. */
@@ -57,7 +78,7 @@ export class VoiceSocketBridge {
             await this.#handleControl(VoiceClientMessageSchema.parse(JSON.parse(text)));
         }
         catch (error) {
-            this.#sendJson({ type: "error", message: errorMessage(error) });
+            this.#reportError(error);
         }
     }
     /** Feed every binary frame from the client socket here. */
@@ -66,36 +87,82 @@ export class VoiceSocketBridge {
             await this.#pushAudio(data);
         }
         catch (error) {
-            this.#sendJson({ type: "error", message: errorMessage(error) });
+            this.#reportError(error);
         }
     }
-    /** Call when the client socket closes; settles the session. */
-    async handleClose(reason = "socket_closed") {
-        await this.#teardown(reason);
+    /**
+     * Closes an attached session gracefully, or cancels pending creation and waits up to
+     * startupCloseTimeoutMs. Repeated calls share one result. Unconfirmed startup is still
+     * cleaned up if it returns later; this result never claims provider finalization.
+     */
+    handleClose(reason = "socket_closed") {
+        return this.#teardown(reason);
     }
     async #handleControl(message) {
         switch (message.type) {
             case "start": {
-                if (this.#session)
+                if (this.#session || this.#starting)
                     throw new Error("A session is already active on this connection");
+                if (this.#closing || this.#sessionEnded)
+                    throw new Error("This voice connection has ended");
+                this.#starting = true;
                 const { type: _type, ...start } = message;
-                const session = await this.#startSession(start);
-                this.#session = session;
-                this.#sequence = 0;
-                this.#startSample = 0;
-                this.#sessionEnded = false;
-                this.#sendJson({ type: "started", sessionId: session.id, provider: message.provider });
-                void this.#pumpEvents(session);
+                const controller = new AbortController();
+                this.#startupController = controller;
+                // Assign the tracked promise before invoking host code, which can close reentrantly.
+                const creation = Promise.resolve()
+                    .then(async () => {
+                    controller.signal.throwIfAborted();
+                    const session = await this.#startSession(start, { startupSignal: controller.signal });
+                    // Ownership transfers at factory return, before readiness. Ordinary close must
+                    // never abort this persistent owner signal after the session has been attached.
+                    this.#startupController = undefined;
+                    if (this.#closing) {
+                        await session
+                            .close(this.#closeReason ?? "client_disconnected_during_startup")
+                            .catch((error) => this.#reportError(error));
+                    }
+                    else {
+                        this.#session = session;
+                        this.#eventPump = this.#pumpEvents(session, message.provider);
+                    }
+                    return session;
+                })
+                    .finally(() => {
+                    this.#startupController = undefined;
+                });
+                this.#startup = creation.then(() => undefined, () => undefined);
+                try {
+                    const session = await creation;
+                    if (this.#closing)
+                        break;
+                    await session.waitUntilReady();
+                    if (this.#closing || this.#sessionEnded)
+                        break;
+                    if (!this.#announceStarted(session, message.provider))
+                        break;
+                    if (!this.#closing && !this.#sessionEnded)
+                        void this.#runOnStarted(session);
+                }
+                catch (error) {
+                    if (!this.#closing) {
+                        void this.#teardown("startup_failed");
+                        throw error;
+                    }
+                }
+                finally {
+                    this.#starting = false;
+                }
                 break;
             }
             case "text": {
-                if (this.#sessionEnded)
-                    break;
-                await this.#session?.sendText(message.text);
+                if (!this.#ready || !this.#session || this.#sessionEnded || this.#closing)
+                    throw new Error("Typed input requires an active, started voice session");
+                await this.#session.sendText(message.text);
                 break;
             }
             case "playout": {
-                if (this.#sessionEnded)
+                if (this.#sessionEnded || this.#closing)
                     break;
                 await this.#session?.reportPlayout({
                     streamId: message.streamId,
@@ -103,6 +170,13 @@ export class VoiceSocketBridge {
                 });
                 break;
             }
+            case "playout.range": {
+                if (this.#sessionEnded || this.#closing)
+                    break;
+                const { type: _type, ...range } = message;
+                await this.#session?.reportPlayoutRange(range);
+                break;
+            }
             case "stop": {
                 await this.#teardown(message.reason ?? "client_stopped");
                 break;
@@ -112,11 +186,13 @@ export class VoiceSocketBridge {
     async #pushAudio(data) {
         const session = this.#session;
         // In-flight microphone frames after settlement are expected, not an error.
-        if (!session || this.#closing || this.#sessionEnded)
+        if (!session || !this.#ready || this.#closing || this.#sessionEnded)
             return;
-        const byteLength = data.byteLength - (data.byteLength % 2);
+        const byteLength = data.byteLength;
         if (byteLength === 0)
             return;
+        if (byteLength % 2 !== 0)
+            throw new Error("Microphone PCM16 frames must contain complete 2-byte samples");
         const chunk = {
             streamId: "microphone",
             sequence: this.#sequence,
@@ -124,65 +200,163 @@ export class VoiceSocketBridge {
             sampleRate: this.#inputSampleRate,
             channels: 1,
             startSample: this.#startSample,
-            data: copyBytes(data, byteLength),
+            data: Uint8Array.from(data),
         };
         this.#sequence += 1;
         this.#startSample += byteLength / 2;
         await session.sendAudio(chunk);
     }
-    async #pumpEvents(session) {
+    async #pumpEvents(session, provider) {
         try {
             for await (const event of session.events()) {
+                let visible = true;
+                try {
+                    if (this.#shouldSendEvent) {
+                        visible = this.#shouldSendEvent(event);
+                        if (typeof visible !== "boolean") {
+                            // Observe an accidentally async callback without accepting its eventual decision.
+                            void Promise.resolve(visible).catch(() => undefined);
+                            throw new TypeError("shouldSendEvent must return a boolean");
+                        }
+                    }
+                }
+                catch (cause) {
+                    throw new Error("Client event filter failed", { cause });
+                }
+                // Keep consuming startup events without buffering, while presenting readiness
+                // only after the control frame that enables the client's media/input path.
+                if (event.type === "provider.ready")
+                    this.#announceStarted(session, provider);
                 if (event.type === "audio.output") {
                     this.#sendBinary(encodeVoiceAudioFrame(event.chunk));
                 }
-                this.#sendJson({ type: "event", event: summarizeVoiceEvent(event) });
+                // Playback must still stop when the application's journal visibility policy
+                // hides this event. The control frame carries no private source metadata.
+                if (event.type === "audio.interrupted" && !visible)
+                    this.#sendJson({ type: "interrupt", streamId: event.streamId });
+                if (visible)
+                    this.#sendJson({ type: "event", event: summarizeVoiceEvent(event) });
                 if (event.type === "session.ended") {
-                    this.#sessionEnded = true;
-                    this.#sendJson({ type: "closed", reason: event.reason });
+                    this.#finishClient(event.reason);
                 }
             }
         }
         catch (error) {
-            this.#sendJson({ type: "error", message: errorMessage(error) });
+            this.#reportError(error);
+            void this.#teardown("session_stream_failed");
         }
         finally {
             // However the pump exits, the connection must settle: no more media forwarding,
             // and the client always receives a closed frame exactly once.
-            if (!this.#sessionEnded) {
-                this.#sessionEnded = true;
-                this.#sendJson({ type: "closed", reason: "session_stream_ended" });
-            }
+            this.#finishClient("session_stream_ended");
         }
     }
-    async #teardown(reason) {
-        if (this.#closing)
-            return;
+    #announceStarted(session, provider) {
+        if (this.#closing || this.#sessionEnded)
+            return false;
+        if (this.#ready)
+            return true;
+        this.#ready = true;
+        return this.#sendJson({
+            type: "started",
+            sessionId: session.id,
+            provider,
+            inputCadence: session.capabilities.inputCadence ?? "on-demand",
+            outputLifecycle: session.capabilities.outputLifecycle ?? "response",
+        });
+    }
+    #teardown(reason) {
+        if (this.#teardownPromise)
+            return this.#teardownPromise;
+        const settled = Promise.withResolvers();
+        this.#teardownPromise = settled.promise;
         this.#closing = true;
+        this.#closeReason = reason;
+        this.#ready = false;
+        this.#workController.abort(reason);
+        this.#startupController?.abort(reason);
+        void this.#performTeardown(reason).then(settled.resolve, settled.reject);
+        return settled.promise;
+    }
+    async #performTeardown(reason) {
         const session = this.#session;
         this.#session = undefined;
+        if (session) {
+            await session.close(reason).catch((error) => this.#reportError(error));
+            await this.#eventPump;
+            return { startup: "settled" };
+        }
+        let deadline;
         try {
-            if (session)
-                await session.close(reason).catch(() => undefined);
+            const result = this.#startup
+                ? await Promise.race([
+                    this.#startup.then(() => ({ startup: "settled" })),
+                    new Promise((resolve) => {
+                        deadline = setTimeout(() => resolve({ startup: "unconfirmed" }), this.#startupCloseTimeoutMs);
+                    }),
+                ])
+                : { startup: "settled" };
+            this.#finishClient(reason);
+            return result;
         }
         finally {
-            this.#closing = false;
+            clearTimeout(deadline);
         }
     }
+    async #runOnStarted(session) {
+        try {
+            await this.#onStarted?.(session, { signal: this.#workController.signal });
+        }
+        catch (error) {
+            if (!this.#workController.signal.aborted)
+                this.#reportError(error);
+        }
+    }
+    #finishClient(reason) {
+        if (this.#sessionEnded)
+            return;
+        this.#sessionEnded = true;
+        this.#ready = false;
+        this.#workController.abort(reason);
+        this.#sendJson({ type: "closed", reason });
+    }
+    #reportError(error) {
+        this.#notifyError(error);
+        this.#sendJson({ type: "error", message: errorMessage(error) });
+    }
+    #notifyError(error) {
+        try {
+            this.#onError?.(error instanceof Error ? error : new Error(String(error)));
+        }
+        catch {
+            // An observation callback must not interrupt cleanup or recursively report itself.
+        }
+    }
+    #socketFailure(error) {
+        this.#socketFailed = true;
+        void this.#teardown("socket_send_failed");
+        this.#notifyError(error);
+    }
     #sendJson(payload) {
+        if (this.#socketFailed)
+            return false;
         try {
             this.#socket.sendText(JSON.stringify(payload));
+            return true;
         }
-        catch {
-            // The client socket is gone; teardown happens via handleClose.
+        catch (error) {
+            this.#socketFailure(error);
+            return false;
         }
     }
     #sendBinary(frame) {
+        if (this.#socketFailed)
+            return;
         try {
             this.#socket.sendBinary(frame);
         }
-        catch {
-            // The client socket is gone; teardown happens via handleClose.
+        catch (error) {
+            this.#socketFailure(error);
         }
     }
 }
@@ -217,11 +391,6 @@ export function summarizeVoiceEvent(event) {
     }
     return { ...event };
 }
-function copyBytes(data, byteLength) {
-    const copy = new Uint8Array(byteLength);
-    copy.set(data.subarray(0, byteLength));
-    return copy;
-}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/internal/harness/task-supervisor.d.ts

@@ -1,5 +1,5 @@
 import type { HarnessEvent, NewHarnessEvent, ProviderContextEvent } from "../protocol/index.js";
-import type { BackgroundTaskLauncher } from "./tools.js";
+import { type BackgroundTaskLauncher, type TaskCancellationRequestResult } from "./tools.js";
 type RecordEvent = (event: NewHarnessEvent) => Promise<HarnessEvent>;
 type SendContext = (event: ProviderContextEvent) => Promise<void>;
 type Flush = () => Promise<void>;
@@ -14,7 +14,11 @@ export declare class TaskSupervisor {
     });
     forCall(callId: string): BackgroundTaskLauncher;
     activate(taskId: string, callId: string): Promise<boolean>;
-    cancelPending(taskId: string, callId: string, reason: string): Promise<boolean>;
+    /** Records and signals one cancellation request without waiting for a running task to settle. */
+    requestCancel(taskId: string, reason?: string): Promise<TaskCancellationRequestResult>;
+    cancelPending(taskId: string, callId: string, reason: string, deliverContext?: boolean): Promise<boolean>;
+    /** A finished tool only transfers ownership of the task ID in its accepted outcome. */
+    cancelUnaccepted(callId: string, acceptedTaskId?: string): Promise<void>;
     cancelAll(reason: string): Promise<void>;
 }
 export {};

package/dist/internal/harness/task-supervisor.js

@@ -1,7 +1,8 @@
 import { JsonValueSchema } from "../protocol/index.js";
+import { BackgroundTaskOutcomeSchema, } from "./tools.js";
 export class TaskSupervisor {
     #tasks = new Map();
-    #terminalTasks = new Set();
+    #terminalTasks = new Map();
     #record;
     #sendContext;
     #flush;
@@ -16,7 +17,8 @@ export class TaskSupervisor {
     }
     forCall(callId) {
         return {
-            start: (runner, options) => this.#register(callId, runner, options),
+            start: (runner, options) => this.#register(callId, runner, false, options),
+            startOutcome: (runner, options) => this.#register(callId, runner, true, options),
         };
     }
     async activate(taskId, callId) {
@@ -25,14 +27,64 @@ export class TaskSupervisor {
             await this.#settle({ type: "task.failed", taskId, callId, error: "activation_failed" }, true);
             return false;
         }
-        if (task.state === "running")
+        if (task.cancellationRequest)
+            await task.cancellationRequest;
+        if (this.#tasks.get(taskId) !== task || task.state === "running")
+            return false;
+        if (task.controller.signal.aborted) {
+            await this.cancelPending(taskId, callId, cancellationReason(task.controller.signal), true);
             return false;
+        }
         task.state = "running";
         task.promise = this.#run(taskId, task);
         void task.promise.catch(this.#onError);
         return true;
     }
-    async cancelPending(taskId, callId, reason) {
+    /** Records and signals one cancellation request without waiting for a running task to settle. */
+    async requestCancel(taskId, reason = "cancelled") {
+        if (!reason.trim())
+            throw new Error("Task cancellation reason must not be empty");
+        const task = this.#tasks.get(taskId);
+        if (!task) {
+            for (const terminalId of this.#terminalTasks.values()) {
+                if (terminalId === taskId)
+                    return { status: "settled" };
+            }
+            return { status: "not_found" };
+        }
+        if (this.#terminalTasks.has(taskKey(taskId, task.callId)))
+            return { status: "settled" };
+        if (task.cancellationRequest) {
+            await task.cancellationRequest;
+            return { status: "already_requested" };
+        }
+        if (task.controller.signal.aborted)
+            return { status: "already_requested" };
+        const request = this.#requestCancellation(taskId, task, reason);
+        task.cancellationRequest = request;
+        try {
+            await request;
+        }
+        catch (error) {
+            task.cancellationRequest = undefined;
+            throw error;
+        }
+        return { status: "requested" };
+    }
+    async #requestCancellation(taskId, task, reason) {
+        if (task.recordedCancellationReason === undefined) {
+            await this.#record({ type: "task.cancellation_requested", taskId, callId: task.callId, reason });
+            task.recordedCancellationReason = reason;
+        }
+        // A failed flush leaves the successful append in place. Retry durability before
+        // signalling, preserving the original request rather than appending a second one.
+        await this.#flush();
+        task.controller.abort(task.recordedCancellationReason);
+        // Leave acceptance ordering intact. Activation or teardown records the pending task's terminal.
+        if (task.state === "pending")
+            this.#releasePending(task);
+    }
+    async cancelPending(taskId, callId, reason, deliverContext = false) {
         const task = this.#tasks.get(taskId);
         if (!task || task.callId !== callId) {
             await this.#settle({ type: "task.failed", taskId, callId, error: "activation_failed" }, false);
@@ -44,9 +96,16 @@ export class TaskSupervisor {
         task.detachSessionAbort();
         task.controller.abort(reason);
         this.#releasePending(task);
-        await this.#settle({ type: "task.cancelled", taskId, callId, reason }, false);
+        await this.#settle({ type: "task.cancelled", taskId, callId, reason }, deliverContext);
         return true;
     }
+    /** A finished tool only transfers ownership of the task ID in its accepted outcome. */
+    async cancelUnaccepted(callId, acceptedTaskId) {
+        for (const [taskId, task] of this.#tasks) {
+            if (task.callId === callId && task.state === "pending" && taskId !== acceptedTaskId)
+                await this.cancelPending(taskId, callId, "tool_did_not_accept_task");
+        }
+    }
     async cancelAll(reason) {
         const pendingCancellations = [];
         const running = [];
@@ -67,14 +126,16 @@ export class TaskSupervisor {
         await Promise.allSettled([...pendingCancellations, ...running]);
     }
     #releasePending(task) {
+        const release = task.onPendingCancel;
+        task.onPendingCancel = undefined;
         try {
-            task.onPendingCancel?.();
+            release?.();
         }
         catch (error) {
             this.#onError(error);
         }
     }
-    async #register(callId, runner, options) {
+    async #register(callId, runner, explicitOutcome, options) {
         if (this.#sessionSignal.aborted)
             throw new Error("Session is closing");
         const taskId = crypto.randomUUID();
@@ -85,6 +146,9 @@ export class TaskSupervisor {
             callId,
             controller,
             runner,
+            explicitOutcome,
+            cancellationRequest: undefined,
+            recordedCancellationReason: undefined,
             onPendingCancel: options?.onPendingCancel,
             state: "pending",
             detachSessionAbort: () => this.#sessionSignal.removeEventListener("abort", abortFromSession),
@@ -109,7 +173,7 @@ export class TaskSupervisor {
             let terminal;
             let infrastructureFailure;
             try {
-                const result = JsonValueSchema.parse(await task.runner({
+                const result = await task.runner({
                     signal: task.controller.signal,
                     report: async (update) => {
                         try {
@@ -123,30 +187,45 @@ export class TaskSupervisor {
                             throw error;
                         }
                     },
-                }));
+                });
                 if (infrastructureFailure)
                     throw infrastructureFailure.error;
-                if (task.controller.signal.aborted) {
+                if (task.explicitOutcome) {
+                    const outcome = BackgroundTaskOutcomeSchema.parse(result);
+                    const identity = { taskId, callId: task.callId };
+                    terminal =
+                        outcome.type === "completed"
+                            ? { type: "task.completed", ...identity, result: outcome.result }
+                            : outcome.type === "failed"
+                                ? { type: "task.failed", ...identity, error: outcome.error }
+                                : { type: "task.cancelled", ...identity, reason: outcome.reason };
+                }
+                else if (task.controller.signal.aborted) {
                     terminal = {
                         type: "task.cancelled",
                         taskId,
                         callId: task.callId,
-                        reason: String(task.controller.signal.reason ?? "cancelled"),
+                        reason: cancellationReason(task.controller.signal),
                     };
                 }
                 else {
-                    terminal = { type: "task.completed", taskId, callId: task.callId, result };
+                    terminal = {
+                        type: "task.completed",
+                        taskId,
+                        callId: task.callId,
+                        result: JsonValueSchema.parse(result),
+                    };
                 }
             }
             catch (error) {
                 if (infrastructureFailure)
                     throw infrastructureFailure.error;
-                if (task.controller.signal.aborted) {
+                if (!task.explicitOutcome && task.controller.signal.aborted) {
                     terminal = {
                         type: "task.cancelled",
                         taskId,
                         callId: task.callId,
-                        reason: String(task.controller.signal.reason ?? "cancelled"),
+                        reason: cancellationReason(task.controller.signal),
                     };
                 }
                 else {
@@ -164,7 +243,7 @@ export class TaskSupervisor {
         const key = taskKey(event.taskId, event.callId);
         if (this.#terminalTasks.has(key))
             return false;
-        this.#terminalTasks.add(key);
+        this.#terminalTasks.set(key, event.taskId);
         try {
             await this.#record(event);
         }
@@ -199,3 +278,6 @@ function taskKey(taskId, callId) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function cancellationReason(signal) {
+    return String(signal.reason ?? "cancelled");
+}

package/dist/internal/harness/tool-calls.d.ts

@@ -0,0 +1,40 @@
+import type { HarnessRecord, JsonValue, ProviderOutputSource, ToolPartState } from "../protocol/index.js";
+export interface ToolDeliveryFailure {
+    eventId: string;
+    phase: "tool" | "progress" | "terminal";
+    error: string;
+    recordedAtMs: number;
+}
+/** One call's recorded execution, independent of delivery or spoken announcements. */
+export interface ToolCallProjection {
+    callId: string;
+    name: string;
+    /** Native invocation provenance, independent of execution and delivery status. */
+    source?: ProviderOutputSource;
+    /** The same canonical state used by message tool parts. */
+    state: ToolPartState;
+    /** An accepted task is still pending even though its initial tool call settled. */
+    status: "pending" | "result_ready";
+    /** Retained after an accepted_task outcome upgrades to its eventual result. */
+    taskId?: string;
+    progress?: {
+        update: JsonValue;
+        recordedAtMs: number;
+    };
+    deliveryFailures: readonly ToolDeliveryFailure[];
+}
+/**
+ * Incremental projection of a single session's sequence-ordered event log. This
+ * observes execution; ToolRuntime and TaskSupervisor remain its only owners.
+ * Applying an event replaces the changed entry, leaving prior snapshots stable.
+ */
+export declare class ToolCallTracker {
+    #private;
+    get(callId: string): ToolCallProjection | undefined;
+    list(): ToolCallProjection[];
+    hasPending(): boolean;
+    /** Returns the updated call, or undefined when the event has no effect. */
+    apply(event: HarnessRecord): ToolCallProjection | undefined;
+}
+/** Pure replay of the same lifecycle used by live harness consumers and messages. */
+export declare function projectToolCalls(events: readonly HarnessRecord[]): ToolCallProjection[];