xo-harness 0.1.0

package/dist/internal/harness/socket-bridge.d.ts

@@ -0,0 +1,65 @@
+import { type AudioChunk, type HarnessEvent } from "../protocol/index.js";
+import { z } from "zod";
+import type { VoiceSession } from "./voice-session.js";
+/**
+ * The client wire protocol every XO transport speaks:
+ * - text frames are JSON control messages (start / playout / stop up; started / event /
+ *   error / closed down),
+ * - binary frames are PCM16 mono audio (microphone up; length-prefixed model audio down:
+ *   u32le header length, JSON header, PCM bytes).
+ *
+ * VoiceSocketBridge owns everything between a client socket and a VoiceSession —
+ * validation, microphone chunk bookkeeping, the event pump, teardown — so a server
+ * (Node WebSocket, Durable Object, anything that can pass text and bytes) wires it
+ * with a few lines instead of reimplementing the protocol.
+ */
+export declare const VoiceClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"start">;
+    provider: z.ZodString;
+    agent: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+    outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        audio: "audio";
+        text: "text";
+    }>>>;
+    voice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"playout">;
+    streamId: z.ZodString;
+    playedThroughSample: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"stop">;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type VoiceClientMessage = z.infer<typeof VoiceClientMessageSchema>;
+/** The start message minus its discriminant — the zod schema stays the single source of truth. */
+export type VoiceStartRequest = Omit<Extract<VoiceClientMessage, {
+    type: "start";
+}>, "type">;
+export interface VoiceBridgeSocket {
+    sendText(text: string): void;
+    sendBinary(frame: ArrayBuffer): void;
+}
+export interface VoiceSocketBridgeOptions {
+    socket: VoiceBridgeSocket;
+    /** Owns provider resolution and XO construction; the bridge owns only the wire. */
+    startSession(start: VoiceStartRequest): Promise<VoiceSession>;
+    inputSampleRate?: number;
+}
+export declare const VOICE_BRIDGE_INPUT_SAMPLE_RATE = 24000;
+export declare class VoiceSocketBridge {
+    #private;
+    constructor(options: VoiceSocketBridgeOptions);
+    /** Feed every text frame from the client socket here. */
+    handleText(text: string): Promise<void>;
+    /** Feed every binary frame from the client socket here. */
+    handleBinary(data: Uint8Array): Promise<void>;
+    /** Call when the client socket closes; settles the session. */
+    handleClose(reason?: string): Promise<void>;
+}
+export declare function encodeVoiceAudioFrame(chunk: AudioChunk): ArrayBuffer;
+/** Event payload for clients: audio chunks shrink to metadata, bytes stay server-side. */
+export declare function summarizeVoiceEvent(event: HarnessEvent): Record<string, unknown>;

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

@@ -0,0 +1,227 @@
+import { MessageInputTextSchema, OutputModalitySchema, } 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),
+ * - binary frames are PCM16 mono audio (microphone up; length-prefixed model audio down:
+ *   u32le header length, JSON header, PCM bytes).
+ *
+ * VoiceSocketBridge owns everything between a client socket and a VoiceSession —
+ * validation, microphone chunk bookkeeping, the event pump, teardown — so a server
+ * (Node WebSocket, Durable Object, anything that can pass text and bytes) wires it
+ * with a few lines instead of reimplementing the protocol.
+ */
+export const VoiceClientMessageSchema = z.discriminatedUnion("type", [
+    /** Open a session; must be the first message, and only one per connection. */
+    z.object({
+        type: z.literal("start"),
+        provider: z.string().min(1),
+        /** Named server-side persona; the host maps it to instructions and tools it composes itself. */
+        agent: z.string().min(1).max(64).optional(),
+        instructions: z.string().max(10_000).optional(),
+        /** Restrict model output, e.g. ["text"] for a text-only session. Default: provider's choice (audio). */
+        outputModalities: z.array(OutputModalitySchema).min(1).optional(),
+        /** Output voice id; the host validates it against the provider's set (unknown → default). */
+        voice: z.string().min(1).max(64).optional(),
+    }),
+    /** A typed user turn (text mode, or typing alongside voice). */
+    z.object({ type: z.literal("text"), text: MessageInputTextSchema }),
+    /** Playback acknowledgement; feeds barge-in truncation. Send every ~250 ms while playing. */
+    z.object({
+        type: z.literal("playout"),
+        streamId: z.string().min(1),
+        playedThroughSample: z.number().int().nonnegative(),
+    }),
+    /** 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() }),
+]);
+export const VOICE_BRIDGE_INPUT_SAMPLE_RATE = 24_000;
+export class VoiceSocketBridge {
+    #socket;
+    #startSession;
+    #inputSampleRate;
+    #session;
+    #sequence = 0;
+    #startSample = 0;
+    #closing = false;
+    #sessionEnded = false;
+    constructor(options) {
+        this.#socket = options.socket;
+        this.#startSession = options.startSession;
+        this.#inputSampleRate = options.inputSampleRate ?? VOICE_BRIDGE_INPUT_SAMPLE_RATE;
+    }
+    /** Feed every text frame from the client socket here. */
+    async handleText(text) {
+        try {
+            await this.#handleControl(VoiceClientMessageSchema.parse(JSON.parse(text)));
+        }
+        catch (error) {
+            this.#sendJson({ type: "error", message: errorMessage(error) });
+        }
+    }
+    /** Feed every binary frame from the client socket here. */
+    async handleBinary(data) {
+        try {
+            await this.#pushAudio(data);
+        }
+        catch (error) {
+            this.#sendJson({ type: "error", message: errorMessage(error) });
+        }
+    }
+    /** Call when the client socket closes; settles the session. */
+    async handleClose(reason = "socket_closed") {
+        await this.#teardown(reason);
+    }
+    async #handleControl(message) {
+        switch (message.type) {
+            case "start": {
+                if (this.#session)
+                    throw new Error("A session is already active on this connection");
+                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);
+                break;
+            }
+            case "text": {
+                if (this.#sessionEnded)
+                    break;
+                await this.#session?.sendText(message.text);
+                break;
+            }
+            case "playout": {
+                if (this.#sessionEnded)
+                    break;
+                await this.#session?.reportPlayout({
+                    streamId: message.streamId,
+                    playedThroughSample: message.playedThroughSample,
+                });
+                break;
+            }
+            case "stop": {
+                await this.#teardown(message.reason ?? "client_stopped");
+                break;
+            }
+        }
+    }
+    async #pushAudio(data) {
+        const session = this.#session;
+        // In-flight microphone frames after settlement are expected, not an error.
+        if (!session || this.#closing || this.#sessionEnded)
+            return;
+        const byteLength = data.byteLength - (data.byteLength % 2);
+        if (byteLength === 0)
+            return;
+        const chunk = {
+            streamId: "microphone",
+            sequence: this.#sequence,
+            encoding: "pcm_s16le",
+            sampleRate: this.#inputSampleRate,
+            channels: 1,
+            startSample: this.#startSample,
+            data: copyBytes(data, byteLength),
+        };
+        this.#sequence += 1;
+        this.#startSample += byteLength / 2;
+        await session.sendAudio(chunk);
+    }
+    async #pumpEvents(session) {
+        try {
+            for await (const event of session.events()) {
+                if (event.type === "audio.output") {
+                    this.#sendBinary(encodeVoiceAudioFrame(event.chunk));
+                }
+                this.#sendJson({ type: "event", event: summarizeVoiceEvent(event) });
+                if (event.type === "session.ended") {
+                    this.#sessionEnded = true;
+                    this.#sendJson({ type: "closed", reason: event.reason });
+                }
+            }
+        }
+        catch (error) {
+            this.#sendJson({ type: "error", message: errorMessage(error) });
+        }
+        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" });
+            }
+        }
+    }
+    async #teardown(reason) {
+        if (this.#closing)
+            return;
+        this.#closing = true;
+        const session = this.#session;
+        this.#session = undefined;
+        try {
+            if (session)
+                await session.close(reason).catch(() => undefined);
+        }
+        finally {
+            this.#closing = false;
+        }
+    }
+    #sendJson(payload) {
+        try {
+            this.#socket.sendText(JSON.stringify(payload));
+        }
+        catch {
+            // The client socket is gone; teardown happens via handleClose.
+        }
+    }
+    #sendBinary(frame) {
+        try {
+            this.#socket.sendBinary(frame);
+        }
+        catch {
+            // The client socket is gone; teardown happens via handleClose.
+        }
+    }
+}
+export function encodeVoiceAudioFrame(chunk) {
+    const header = new TextEncoder().encode(JSON.stringify({
+        streamId: chunk.streamId,
+        sequence: chunk.sequence,
+        startSample: chunk.startSample,
+        sampleRate: chunk.sampleRate,
+        channels: chunk.channels,
+    }));
+    const frame = new Uint8Array(4 + header.byteLength + chunk.data.byteLength);
+    new DataView(frame.buffer).setUint32(0, header.byteLength, true);
+    frame.set(header, 4);
+    frame.set(chunk.data, 4 + header.byteLength);
+    return frame.buffer;
+}
+/** Event payload for clients: audio chunks shrink to metadata, bytes stay server-side. */
+export function summarizeVoiceEvent(event) {
+    if (event.type === "audio.input" || event.type === "audio.output") {
+        const { chunk, ...rest } = event;
+        return {
+            ...rest,
+            chunk: {
+                streamId: chunk.streamId,
+                sequence: chunk.sequence,
+                startSample: chunk.startSample,
+                sampleRate: chunk.sampleRate,
+                byteLength: chunk.data.byteLength,
+            },
+        };
+    }
+    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

@@ -0,0 +1,20 @@
+import type { HarnessEvent, NewHarnessEvent, ProviderContextEvent } from "../protocol/index.js";
+import type { BackgroundTaskLauncher } from "./tools.js";
+type RecordEvent = (event: NewHarnessEvent) => Promise<HarnessEvent>;
+type SendContext = (event: ProviderContextEvent) => Promise<void>;
+type Flush = () => Promise<void>;
+export declare class TaskSupervisor {
+    #private;
+    constructor(options: {
+        record: RecordEvent;
+        sendContext: SendContext;
+        flush: Flush;
+        sessionSignal: AbortSignal;
+        onError: (error: unknown) => void;
+    });
+    forCall(callId: string): BackgroundTaskLauncher;
+    activate(taskId: string, callId: string): Promise<boolean>;
+    cancelPending(taskId: string, callId: string, reason: string): Promise<boolean>;
+    cancelAll(reason: string): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,180 @@
+import { JsonValueSchema } from "../protocol/index.js";
+export class TaskSupervisor {
+    #tasks = new Map();
+    #terminalTasks = new Set();
+    #record;
+    #sendContext;
+    #flush;
+    #sessionSignal;
+    #onError;
+    constructor(options) {
+        this.#record = options.record;
+        this.#sendContext = options.sendContext;
+        this.#flush = options.flush;
+        this.#sessionSignal = options.sessionSignal;
+        this.#onError = options.onError;
+    }
+    forCall(callId) {
+        return {
+            start: (runner) => this.#register(callId, runner),
+        };
+    }
+    async activate(taskId, callId) {
+        const task = this.#tasks.get(taskId);
+        if (!task || task.callId !== callId) {
+            await this.#settle({ type: "task.failed", taskId, callId, error: "activation_failed" }, true);
+            return false;
+        }
+        if (task.state === "running")
+            return false;
+        task.state = "running";
+        task.promise = this.#run(taskId, task);
+        void task.promise.catch(this.#onError);
+        return true;
+    }
+    async cancelPending(taskId, callId, reason) {
+        const task = this.#tasks.get(taskId);
+        if (!task || task.callId !== callId) {
+            await this.#settle({ type: "task.failed", taskId, callId, error: "activation_failed" }, false);
+            return false;
+        }
+        if (task.state === "running")
+            return false;
+        this.#tasks.delete(taskId);
+        task.detachSessionAbort();
+        task.controller.abort(reason);
+        await this.#settle({ type: "task.cancelled", taskId, callId, reason }, false);
+        return true;
+    }
+    async cancelAll(reason) {
+        const pendingCancellations = [];
+        const running = [];
+        for (const [taskId, task] of this.#tasks) {
+            if (task.state === "pending") {
+                this.#tasks.delete(taskId);
+                task.detachSessionAbort();
+                task.controller.abort(reason);
+                pendingCancellations.push(this.#settle({ type: "task.cancelled", taskId, callId: task.callId, reason }, true).then(() => undefined));
+            }
+            else {
+                task.controller.abort(reason);
+                if (task.promise)
+                    running.push(task.promise);
+            }
+        }
+        await Promise.allSettled([...pendingCancellations, ...running]);
+    }
+    async #register(callId, runner) {
+        if (this.#sessionSignal.aborted)
+            throw new Error("Session is closing");
+        const taskId = crypto.randomUUID();
+        const controller = new AbortController();
+        const abortFromSession = () => controller.abort(this.#sessionSignal.reason);
+        this.#sessionSignal.addEventListener("abort", abortFromSession, { once: true });
+        this.#tasks.set(taskId, {
+            callId,
+            controller,
+            runner,
+            state: "pending",
+            detachSessionAbort: () => this.#sessionSignal.removeEventListener("abort", abortFromSession),
+        });
+        try {
+            await this.#record({ type: "task.accepted", taskId, callId });
+        }
+        catch (error) {
+            this.#tasks.delete(taskId);
+            this.#sessionSignal.removeEventListener("abort", abortFromSession);
+            controller.abort("task_acceptance_failed");
+            throw error;
+        }
+        return taskId;
+    }
+    async #run(taskId, task) {
+        try {
+            let terminal;
+            let infrastructureFailure;
+            try {
+                const result = JsonValueSchema.parse(await task.runner({
+                    signal: task.controller.signal,
+                    report: async (update) => {
+                        try {
+                            const event = { type: "task.progress", taskId, callId: task.callId, update };
+                            await this.#record(event);
+                            await this.#flush();
+                            await this.#deliverContext(event, "progress");
+                        }
+                        catch (error) {
+                            infrastructureFailure = { error };
+                            throw error;
+                        }
+                    },
+                }));
+                if (infrastructureFailure)
+                    throw infrastructureFailure.error;
+                if (task.controller.signal.aborted) {
+                    terminal = {
+                        type: "task.cancelled",
+                        taskId,
+                        callId: task.callId,
+                        reason: String(task.controller.signal.reason ?? "cancelled"),
+                    };
+                }
+                else {
+                    terminal = { type: "task.completed", taskId, callId: task.callId, result };
+                }
+            }
+            catch (error) {
+                if (infrastructureFailure)
+                    throw infrastructureFailure.error;
+                if (task.controller.signal.aborted) {
+                    terminal = {
+                        type: "task.cancelled",
+                        taskId,
+                        callId: task.callId,
+                        reason: String(task.controller.signal.reason ?? "cancelled"),
+                    };
+                }
+                else {
+                    terminal = { type: "task.failed", taskId, callId: task.callId, error: errorMessage(error) };
+                }
+            }
+            await this.#settle(terminal, true);
+        }
+        finally {
+            task.detachSessionAbort();
+            this.#tasks.delete(taskId);
+        }
+    }
+    async #settle(event, deliverContext) {
+        const key = taskKey(event.taskId, event.callId);
+        if (this.#terminalTasks.has(key))
+            return false;
+        await this.#record(event);
+        this.#terminalTasks.add(key);
+        await this.#flush();
+        if (deliverContext)
+            await this.#deliverContext(event, "terminal");
+        return true;
+    }
+    async #deliverContext(event, phase) {
+        try {
+            await this.#sendContext(event);
+        }
+        catch (error) {
+            await this.#record({
+                type: "task.delivery_failed",
+                taskId: event.taskId,
+                callId: event.callId,
+                phase,
+                error: errorMessage(error),
+            });
+            await this.#flush();
+        }
+    }
+}
+function taskKey(taskId, callId) {
+    return JSON.stringify([taskId, callId]);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,20 @@
+import { type HarnessEvent, type NewHarnessEvent, type ProviderToolResult, type ToolCall } from "../protocol/index.js";
+import type { TaskSupervisor } from "./task-supervisor.js";
+import type { ToolRegistry } from "./tools.js";
+type RecordEvent = (event: NewHarnessEvent) => Promise<HarnessEvent>;
+export interface ToolResultSink {
+    deliver(result: ProviderToolResult): Promise<void>;
+}
+export declare class ToolRuntime {
+    #private;
+    constructor(options: {
+        tools: ToolRegistry;
+        tasks: TaskSupervisor;
+        record: RecordEvent;
+        resultSink: ToolResultSink;
+        signal: AbortSignal;
+        flush: () => Promise<void>;
+    });
+    execute(call: ToolCall): Promise<void>;
+}
+export {};

package/dist/internal/harness/tool-runtime.js

@@ -0,0 +1,93 @@
+import { ToolOutcomeSchema, } from "../protocol/index.js";
+export class ToolRuntime {
+    #tools;
+    #tasks;
+    #record;
+    #resultSink;
+    #signal;
+    #flush;
+    #inFlight = new Set();
+    #terminal = new Set();
+    constructor(options) {
+        this.#tools = options.tools;
+        this.#tasks = options.tasks;
+        this.#record = options.record;
+        this.#resultSink = options.resultSink;
+        this.#signal = options.signal;
+        this.#flush = options.flush;
+    }
+    async execute(call) {
+        if (this.#inFlight.has(call.callId) || this.#terminal.has(call.callId))
+            return;
+        this.#inFlight.add(call.callId);
+        try {
+            await this.#record({ type: "tool.started", callId: call.callId, name: call.name });
+            await this.#flush();
+            const tool = this.#tools.get(call.name);
+            if (!tool) {
+                await this.#settleFailure(call.callId, `Tool not found: ${call.name}`);
+                return;
+            }
+            let outcome;
+            try {
+                const input = await tool.input.parseAsync(call.arguments);
+                outcome = ToolOutcomeSchema.parse(await this.#run(tool, input, call.callId));
+            }
+            catch (error) {
+                await this.#settleFailure(call.callId, errorMessage(error));
+                return;
+            }
+            await this.#settleCompleted(call.callId, outcome);
+        }
+        finally {
+            this.#inFlight.delete(call.callId);
+        }
+    }
+    async #run(tool, input, callId) {
+        return tool.execute(input, {
+            signal: this.#signal,
+            tasks: this.#tasks.forCall(callId),
+            report: async (update) => {
+                await this.#record({ type: "tool.progress", callId, update });
+            },
+        });
+    }
+    async #settleCompleted(callId, outcome) {
+        this.#assertNotTerminal(callId);
+        await this.#record({ type: "tool.completed", callId, outcome });
+        this.#terminal.add(callId);
+        await this.#flush();
+        await this.#deliver(callId, outcome);
+    }
+    async #settleFailure(callId, message) {
+        this.#assertNotTerminal(callId);
+        await this.#record({ type: "tool.failed", callId, error: message });
+        this.#terminal.add(callId);
+        await this.#flush();
+        await this.#deliver(callId, { type: "failed", error: message });
+    }
+    async #deliver(callId, outcome) {
+        try {
+            await this.#resultSink.deliver({ callId, outcome });
+        }
+        catch (error) {
+            await this.#record({ type: "tool.delivery_failed", callId, error: errorMessage(error) });
+            await this.#flush();
+            if (outcome.type === "accepted_task") {
+                await this.#tasks.cancelPending(outcome.taskId, callId, "tool_result_delivery_failed");
+            }
+            return;
+        }
+        if (outcome.type === "accepted_task") {
+            await this.#tasks.activate(outcome.taskId, callId);
+        }
+    }
+    #assertNotTerminal(callId) {
+        if (this.#terminal.has(callId)) {
+            throw new Error(`Tool call already settled: ${callId}`);
+        }
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,32 @@
+import { type JsonValue, type ProviderToolDefinition, type ToolOutcome } from "../protocol/index.js";
+import { z } from "zod";
+export interface BackgroundTaskContext {
+    readonly signal: AbortSignal;
+    report(update: JsonValue): Promise<void>;
+}
+export type BackgroundTaskRunner = (context: BackgroundTaskContext) => Promise<JsonValue>;
+export interface BackgroundTaskLauncher {
+    start(run: BackgroundTaskRunner): Promise<string>;
+}
+export interface ToolExecutionContext {
+    readonly signal: AbortSignal;
+    readonly tasks: BackgroundTaskLauncher;
+    report(update: JsonValue): Promise<void>;
+}
+export interface VoiceTool<Schema extends z.ZodType = z.ZodType> {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Schema;
+    execute(input: z.output<Schema>, context: ToolExecutionContext): ToolOutcome | Promise<ToolOutcome>;
+}
+export declare function defineTool<const Schema extends z.ZodType>(tool: VoiceTool<Schema>): VoiceTool<Schema>;
+type ErasedVoiceTool = VoiceTool<z.ZodType<unknown>>;
+export declare class ToolRegistry {
+    #private;
+    constructor(tools?: readonly VoiceTool[]);
+    register<const Schema extends z.ZodType>(tool: VoiceTool<Schema>): void;
+    get(name: string): ErasedVoiceTool | undefined;
+    list(): readonly ErasedVoiceTool[];
+    definitions(): readonly ProviderToolDefinition[];
+}
+export {};

package/dist/internal/harness/tools.js

@@ -0,0 +1,30 @@
+import { ProviderToolDefinitionSchema, } from "../protocol/index.js";
+import { z } from "zod";
+export function defineTool(tool) {
+    return tool;
+}
+export class ToolRegistry {
+    #tools = new Map();
+    constructor(tools = []) {
+        for (const tool of tools)
+            this.register(tool);
+    }
+    register(tool) {
+        if (this.#tools.has(tool.name))
+            throw new Error(`Tool already registered: ${tool.name}`);
+        this.#tools.set(tool.name, tool);
+    }
+    get(name) {
+        return this.#tools.get(name);
+    }
+    list() {
+        return [...this.#tools.values()];
+    }
+    definitions() {
+        return this.list().map((tool) => ProviderToolDefinitionSchema.parse({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: z.toJSONSchema(tool.input),
+        }));
+    }
+}