xo-harness 0.1.0

package/dist/internal/harness/voice-session.d.ts

@@ -0,0 +1,33 @@
+import { type AgentInput, type AudioChunk, type HarnessEvent, type OutputModality, type PlayoutProgress } from "../protocol/index.js";
+import type { VoiceProvider } from "../provider/index.js";
+import type { EventStore } from "../storage/index.js";
+import type { ToolRegistry } from "./tools.js";
+export interface CreateVoiceSessionOptions {
+    sessionId: string;
+    provider: VoiceProvider;
+    store: EventStore;
+    tools: ToolRegistry;
+    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;
+}
+export declare class VoiceSession {
+    #private;
+    readonly id: string;
+    private constructor();
+    static create(options: CreateVoiceSessionOptions): Promise<VoiceSession>;
+    events(afterSequence?: number): AsyncIterable<HarnessEvent>;
+    history(): Promise<readonly HarnessEvent[]>;
+    sendAudio(chunk: AudioChunk): Promise<void>;
+    /**
+     * 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).
+     */
+    sendText(input: AgentInput): Promise<void>;
+    reportPlayout(progress: PlayoutProgress): Promise<void>;
+    close(reason?: string): Promise<void>;
+}

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

@@ -0,0 +1,268 @@
+import { AgentInputSchema, AudioChunkSchema, agentInputToText, MessageInputTextSchema, PlayoutProgressSchema, ProviderEventSchema, } from "../protocol/index.js";
+import { ReplayEventStream } from "./event-stream.js";
+import { TaskSupervisor } from "./task-supervisor.js";
+import { ToolRuntime } from "./tool-runtime.js";
+export class VoiceSession {
+    id;
+    #providerSession;
+    #store;
+    #events = new ReplayEventStream();
+    #controller = new AbortController();
+    #startedAt;
+    #toolExecutions = new Set();
+    #pendingRecords = new Set();
+    #tasks;
+    #toolRuntime;
+    #providerPump;
+    #closePromise;
+    #maxDurationTimer;
+    constructor(options, providerSession, startedAt, startedEvent) {
+        this.id = options.sessionId;
+        this.#providerSession = providerSession;
+        this.#store = options.store;
+        this.#startedAt = startedAt;
+        this.#events.publish(startedEvent);
+        this.#tasks = new TaskSupervisor({
+            record: (event) => this.#record(event),
+            sendContext: (event) => this.#providerSession.sendContext(event),
+            flush: () => this.#store.flush(this.id),
+            sessionSignal: this.#controller.signal,
+            onError: () => {
+                void this.close("storage_error");
+            },
+        });
+        this.#toolRuntime = new ToolRuntime({
+            tools: options.tools,
+            tasks: this.#tasks,
+            record: (event) => this.#record(event),
+            resultSink: {
+                deliver: (result) => this.#providerSession.sendToolResult(result),
+            },
+            signal: this.#controller.signal,
+            flush: () => this.#store.flush(this.id),
+        });
+    }
+    static async create(options) {
+        const startedAt = performance.now();
+        const startedEvent = await options.store.append(createUnsequencedEvent(options.sessionId, startedAt, {
+            type: "session.started",
+            formatVersion: 1,
+            providerId: options.provider.id,
+            capabilities: options.provider.capabilities,
+            ...(options.instructions === undefined ? {} : { instructions: options.instructions }),
+            ...(options.outputModalities === undefined
+                ? {}
+                : { outputModalities: [...options.outputModalities] }),
+        }));
+        await options.store.flush(options.sessionId);
+        const providerController = new AbortController();
+        let providerSession;
+        try {
+            providerSession = await options.provider.createSession({
+                sessionId: options.sessionId,
+                signal: providerController.signal,
+                tools: options.tools.definitions(),
+                ...(options.instructions === undefined ? {} : { instructions: options.instructions }),
+                ...(options.outputModalities === undefined ? {} : { outputModalities: options.outputModalities }),
+            });
+        }
+        catch (error) {
+            providerController.abort(error);
+            await recordFailedCreation(options.store, options.sessionId, startedAt);
+            throw error;
+        }
+        const session = new VoiceSession(options, providerSession, startedAt, startedEvent);
+        session.#controller.signal.addEventListener("abort", () => providerController.abort(session.#controller.signal.reason), {
+            once: true,
+        });
+        session.#providerPump = session.#pumpProviderEvents();
+        if (options.maxDurationMs !== undefined) {
+            session.#maxDurationTimer = setTimeout(() => {
+                void session.close("max_duration_reached");
+            }, options.maxDurationMs);
+        }
+        return session;
+    }
+    events(afterSequence = 0) {
+        return this.#events.subscribe(afterSequence);
+    }
+    history() {
+        return this.#store.list(this.id);
+    }
+    async sendAudio(chunk) {
+        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 });
+        recorded.catch(() => undefined);
+        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).
+     */
+    async sendText(input) {
+        this.#assertOpen();
+        const parsed = AgentInputSchema.parse(input);
+        const collapsed = agentInputToText(parsed);
+        if (collapsed === "") {
+            throw new Error("Realtime providers require at least one text part in AgentInput");
+        }
+        const text = MessageInputTextSchema.parse(collapsed);
+        await this.#record({
+            type: "message.input",
+            text,
+            ...(typeof parsed === "string" ? {} : { parts: parsed }),
+        });
+        await this.#providerSession.sendText(text);
+    }
+    async reportPlayout(progress) {
+        this.#assertOpen();
+        const validated = PlayoutProgressSchema.parse(progress);
+        await this.#record({ type: "playout.progress", ...validated });
+        await this.#providerSession.reportPlayout(validated);
+    }
+    close(reason = "client_closed") {
+        this.#closePromise ??= this.#performClose(reason);
+        return this.#closePromise;
+    }
+    async #performClose(reason) {
+        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);
+            await this.#providerPump;
+        }
+        finally {
+            await Promise.allSettled([...this.#pendingRecords]);
+            try {
+                await this.#record({ type: "session.ended", reason });
+                await this.#store.flush(this.id);
+            }
+            finally {
+                this.#events.close();
+            }
+        }
+    }
+    async #pumpProviderEvents() {
+        try {
+            for await (const candidate of this.#providerSession.events) {
+                const event = ProviderEventSchema.parse(candidate);
+                switch (event.type) {
+                    case "ready":
+                        await this.#record({ type: "provider.ready" });
+                        break;
+                    case "audio.output":
+                        // 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 }));
+                        break;
+                    case "transcript":
+                        await this.#record({
+                            type: "transcript",
+                            role: event.role,
+                            text: event.text,
+                            ...(event.streamId === undefined ? {} : { streamId: event.streamId }),
+                        });
+                        break;
+                    case "transcript.delta":
+                        this.#trackRecord(this.#record({
+                            type: "transcript.delta",
+                            role: event.role,
+                            delta: event.delta,
+                            ...(event.streamId === undefined ? {} : { streamId: event.streamId }),
+                        }));
+                        break;
+                    case "tool.call":
+                        await this.#record({ type: "tool.requested", call: event.call });
+                        this.#trackToolExecution(this.#toolRuntime.execute(event.call));
+                        break;
+                    case "usage": {
+                        const { type: _type, ...usage } = event;
+                        await this.#record({ type: "usage", ...usage });
+                        break;
+                    }
+                    case "error":
+                        await this.#record({
+                            type: "provider.error",
+                            message: event.message,
+                            recoverable: event.recoverable,
+                        });
+                        if (!event.recoverable)
+                            void this.close("provider_error");
+                        break;
+                    case "closed":
+                        await this.#record({ type: "provider.closed", reason: event.reason });
+                        void this.close("provider_closed");
+                        break;
+                }
+            }
+        }
+        catch (error) {
+            if (!this.#controller.signal.aborted) {
+                await this.#record({
+                    type: "provider.error",
+                    message: errorMessage(error),
+                    recoverable: false,
+                });
+            }
+        }
+    }
+    #trackToolExecution(execution) {
+        this.#toolExecutions.add(execution);
+        void execution.then(() => this.#toolExecutions.delete(execution), () => {
+            this.#toolExecutions.delete(execution);
+            void this.close("storage_error");
+        });
+    }
+    #trackRecord(record) {
+        this.#pendingRecords.add(record);
+        void record.then(() => this.#pendingRecords.delete(record), () => {
+            this.#pendingRecords.delete(record);
+            void this.close("storage_error");
+        });
+    }
+    async #record(event) {
+        const stored = await this.#store.append(createUnsequencedEvent(this.id, this.#startedAt, event));
+        this.#events.publish(stored);
+        return stored;
+    }
+    #assertOpen() {
+        if (this.#closePromise || this.#controller.signal.aborted) {
+            throw new Error("Voice session is closed");
+        }
+    }
+}
+function createUnsequencedEvent(sessionId, startedAt, event) {
+    return {
+        ...event,
+        id: crypto.randomUUID(),
+        sessionId,
+        recordedAtMs: Date.now(),
+        sessionTimeMs: performance.now() - startedAt,
+    };
+}
+async function recordFailedCreation(store, sessionId, startedAt) {
+    try {
+        await store.append(createUnsequencedEvent(sessionId, startedAt, {
+            type: "session.ended",
+            reason: "provider_create_failed",
+        }));
+        await store.flush(sessionId);
+    }
+    catch {
+        // 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

@@ -0,0 +1,25 @@
+import type { OutputModality } from "../protocol/index.js";
+import type { VoiceProvider } from "../provider/index.js";
+import type { EventStore } from "../storage/index.js";
+import { ToolRegistry, type VoiceTool } from "./tools.js";
+import { VoiceSession } from "./voice-session.js";
+export interface XOOptions {
+    store: EventStore;
+    tools?: readonly VoiceTool[];
+}
+export interface StartSessionOptions {
+    provider: VoiceProvider;
+    sessionId?: string;
+    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;
+}
+export declare class XO {
+    readonly store: EventStore;
+    readonly tools: ToolRegistry;
+    constructor(options: XOOptions);
+    registerTool<const Tool extends VoiceTool>(tool: Tool): void;
+    startSession(options: StartSessionOptions): Promise<VoiceSession>;
+}

package/dist/internal/harness/xo.js

@@ -0,0 +1,24 @@
+import { ToolRegistry } from "./tools.js";
+import { VoiceSession } from "./voice-session.js";
+export class XO {
+    store;
+    tools;
+    constructor(options) {
+        this.store = options.store;
+        this.tools = new ToolRegistry(options.tools);
+    }
+    registerTool(tool) {
+        this.tools.register(tool);
+    }
+    startSession(options) {
+        return VoiceSession.create({
+            sessionId: options.sessionId ?? crypto.randomUUID(),
+            provider: options.provider,
+            store: this.store,
+            tools: this.tools,
+            ...(options.instructions === undefined ? {} : { instructions: options.instructions }),
+            ...(options.outputModalities === undefined ? {} : { outputModalities: options.outputModalities }),
+            ...(options.maxDurationMs === undefined ? {} : { maxDurationMs: options.maxDurationMs }),
+        });
+    }
+}

package/dist/internal/protocol/async-queue.d.ts

@@ -0,0 +1,8 @@
+/** Unbounded push/pull bridge between a callback producer and an async-iterating consumer. */
+export declare class AsyncQueue<Value> implements AsyncIterableIterator<Value> {
+    #private;
+    push(value: Value): void;
+    close(): void;
+    next(): Promise<IteratorResult<Value>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Value>;
+}

package/dist/internal/protocol/async-queue.js

@@ -0,0 +1,34 @@
+/** Unbounded push/pull bridge between a callback producer and an async-iterating consumer. */
+export class AsyncQueue {
+    #values = [];
+    #resolvers = [];
+    #closed = false;
+    push(value) {
+        if (this.#closed)
+            throw new Error("Cannot push to a closed queue");
+        const resolve = this.#resolvers.shift();
+        if (resolve)
+            resolve({ done: false, value });
+        else
+            this.#values.push(value);
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const resolve of this.#resolvers.splice(0)) {
+            resolve({ done: true, value: undefined });
+        }
+    }
+    next() {
+        const value = this.#values.shift();
+        if (value !== undefined)
+            return Promise.resolve({ done: false, value });
+        if (this.#closed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve) => this.#resolvers.push(resolve));
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}

package/dist/internal/protocol/audio.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export declare const AudioChunkSchema: z.ZodObject<{
+    streamId: z.ZodString;
+    sequence: z.ZodInt;
+    encoding: z.ZodLiteral<"pcm_s16le">;
+    sampleRate: z.ZodInt;
+    channels: z.ZodInt;
+    startSample: z.ZodInt;
+    data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
+export type AudioChunk = z.infer<typeof AudioChunkSchema>;
+export declare function audioSampleCount(chunk: AudioChunk): number;

package/dist/internal/protocol/audio.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export const AudioChunkSchema = z
+    .object({
+    streamId: z.string().min(1),
+    sequence: z.int().nonnegative(),
+    encoding: z.literal("pcm_s16le"),
+    sampleRate: z.int().positive(),
+    channels: z.int().positive(),
+    startSample: z.int().nonnegative(),
+    data: z.instanceof(Uint8Array),
+})
+    .superRefine((chunk, context) => {
+    const frameWidth = chunk.channels * 2;
+    if (chunk.data.byteLength % frameWidth !== 0) {
+        context.addIssue({
+            code: "custom",
+            message: `PCM byte length must be divisible by the ${frameWidth}-byte frame width`,
+            path: ["data"],
+        });
+    }
+});
+export function audioSampleCount(chunk) {
+    return chunk.data.byteLength / (chunk.channels * 2);
+}