xo-harness 0.1.0

package/dist/internal/provider/grok-voice.d.ts

@@ -0,0 +1,45 @@
+import type { CreateProviderSessionOptions, VoiceProvider, VoiceProviderSession } from "./contract.js";
+import { type RealtimeSocketFactory } from "./realtime-socket.js";
+export interface GrokVoiceProviderOptions {
+    apiKey: string;
+    /** Transport override; defaults to the runtime's registered factory (Node ws or Workers). */
+    socketFactory?: RealtimeSocketFactory;
+    /** Voice model id; grok-voice-latest currently resolves to Grok Voice Think Fast 2.0. */
+    model?: string;
+    /** WebSocket endpoint, overridable for tests and proxies. */
+    url?: string;
+    /** Output voice: eve (default), ara, rex, sal, or leo. */
+    voice?: string;
+    /** Sample rate of the PCM16 mono input the harness will send. The API expects 24000. */
+    inputSampleRate?: number;
+    /** Server-side turn detection; xAI supports server_vad with threshold and padding tuning. */
+    turnDetection?: Record<string, unknown> | null;
+    /** Input transcription model recorded into the conversation. */
+    transcriptionModel?: string;
+    /** Think Fast reasoning effort: "high" reasons in parallel with speech, "none" disables it. */
+    reasoningEffort?: "high" | "none";
+    /** Request a spoken response when a background task settles. */
+    announceTaskSettlement?: boolean;
+    handshakeTimeoutMs?: number;
+}
+/**
+ * Adapts xAI's Grok voice realtime API (Think Fast models) to the XO duplex provider
+ * contract. The wire protocol is the same realtime dialect the OpenAI adapter speaks;
+ * the differences live entirely in the session.update payload: voice and turn_detection
+ * sit at the session top level, input transcription is configured explicitly, and
+ * reasoning effort is tunable. Think Fast listens and reasons while speaking, so the
+ * duplex capability flags here are literal, not bridged.
+ */
+export declare class GrokVoiceProvider implements VoiceProvider {
+    #private;
+    readonly id = "grok-voice";
+    readonly capabilities: {
+        readonly continuousInputDuringOutput: true;
+        readonly modelManagedFloor: true;
+        readonly supportsToolCalls: true;
+        readonly supportsAsyncContext: true;
+        readonly supportsPlayoutAcknowledgements: true;
+    };
+    constructor(options: GrokVoiceProviderOptions);
+    createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;
+}

package/dist/internal/provider/grok-voice.js

@@ -0,0 +1,77 @@
+import { RealtimeVoiceSession, toRealtimeFunctionTool } from "./realtime-session.js";
+import { connectRealtimeSocket } from "./realtime-socket.js";
+const DEFAULT_URL = "wss://api.x.ai/v1/realtime";
+const DEFAULT_MODEL = "grok-voice-latest";
+const DEFAULT_VOICE = "eve";
+const DEFAULT_SAMPLE_RATE = 24_000;
+const DEFAULT_TRANSCRIPTION_MODEL = "grok-transcribe";
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 15_000;
+/**
+ * Adapts xAI's Grok voice realtime API (Think Fast models) to the XO duplex provider
+ * contract. The wire protocol is the same realtime dialect the OpenAI adapter speaks;
+ * the differences live entirely in the session.update payload: voice and turn_detection
+ * sit at the session top level, input transcription is configured explicitly, and
+ * reasoning effort is tunable. Think Fast listens and reasons while speaking, so the
+ * duplex capability flags here are literal, not bridged.
+ */
+export class GrokVoiceProvider {
+    id = "grok-voice";
+    capabilities = {
+        continuousInputDuringOutput: true,
+        modelManagedFloor: true,
+        supportsToolCalls: true,
+        supportsAsyncContext: true,
+        supportsPlayoutAcknowledgements: true,
+    };
+    #options;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("GrokVoiceProvider requires an apiKey");
+        this.#options = options;
+    }
+    async createSession(options) {
+        const inputSampleRate = this.#options.inputSampleRate ?? DEFAULT_SAMPLE_RATE;
+        const socket = await connectRealtimeSocket({
+            url: this.#options.url ?? DEFAULT_URL,
+            model: this.#options.model ?? DEFAULT_MODEL,
+            apiKey: this.#options.apiKey,
+            handshakeTimeoutMs: this.#options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS,
+            signal: options.signal,
+            ...(this.#options.socketFactory === undefined ? {} : { factory: this.#options.socketFactory }),
+        });
+        return new RealtimeVoiceSession(socket, {
+            label: "Grok voice",
+            sessionUpdate: this.#sessionUpdate(options, inputSampleRate),
+            inputSampleRate,
+            outputSampleRate: DEFAULT_SAMPLE_RATE,
+            announceTaskSettlement: this.#options.announceTaskSettlement ?? true,
+        }, options);
+    }
+    #sessionUpdate(options, inputSampleRate) {
+        const turnDetection = this.#options.turnDetection === undefined ? { type: "server_vad" } : this.#options.turnDetection;
+        const session = {
+            voice: this.#options.voice ?? DEFAULT_VOICE,
+            output_modalities: [...(options.outputModalities ?? ["audio"])],
+            turn_detection: turnDetection,
+            audio: {
+                input: {
+                    format: { type: "audio/pcm", rate: inputSampleRate },
+                    transcription: { model: this.#options.transcriptionModel ?? DEFAULT_TRANSCRIPTION_MODEL },
+                },
+                output: {
+                    format: { type: "audio/pcm", rate: DEFAULT_SAMPLE_RATE },
+                },
+            },
+        };
+        if (options.instructions !== undefined)
+            session.instructions = options.instructions;
+        if (this.#options.reasoningEffort !== undefined) {
+            session.reasoning = { effort: this.#options.reasoningEffort };
+        }
+        if (options.tools.length > 0) {
+            session.tools = options.tools.map(toRealtimeFunctionTool);
+            session.tool_choice = "auto";
+        }
+        return session;
+    }
+}

package/dist/internal/provider/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./contract.js";
+export * from "./grok-voice.js";
+export { nodeSocketFactory } from "./node-socket.js";
+export * from "./openai-realtime.js";
+export { RealtimeVoiceSession, type RealtimeWireOptions } from "./realtime-session.js";
+export * from "./realtime-socket.js";

package/dist/internal/provider/index.js

@@ -0,0 +1,9 @@
+import { nodeSocketFactory } from "./node-socket.js";
+import { setDefaultRealtimeSocketFactory } from "./realtime-socket.js";
+setDefaultRealtimeSocketFactory(nodeSocketFactory);
+export * from "./contract.js";
+export * from "./grok-voice.js";
+export { nodeSocketFactory } from "./node-socket.js";
+export * from "./openai-realtime.js";
+export { RealtimeVoiceSession } from "./realtime-session.js";
+export * from "./realtime-socket.js";

package/dist/internal/provider/node-socket.d.ts

@@ -0,0 +1,3 @@
+import type { RealtimeSocketFactory } from "./realtime-socket.js";
+/** Node transport: the ws client, which supports Authorization headers directly. */
+export declare const nodeSocketFactory: RealtimeSocketFactory;

package/dist/internal/provider/node-socket.js

@@ -0,0 +1,74 @@
+import { Buffer } from "node:buffer";
+import WebSocket, {} from "ws";
+/** Node transport: the ws client, which supports Authorization headers directly. */
+export const nodeSocketFactory = async (target) => {
+    const ws = new WebSocket(target.url, {
+        headers: { Authorization: `Bearer ${target.apiKey}` },
+        handshakeTimeout: target.handshakeTimeoutMs,
+    });
+    await openSocket(ws, target.signal);
+    const socket = {
+        get state() {
+            switch (ws.readyState) {
+                case WebSocket.CONNECTING:
+                    return "connecting";
+                case WebSocket.OPEN:
+                    return "open";
+                case WebSocket.CLOSING:
+                    return "closing";
+                default:
+                    return "closed";
+            }
+        },
+        send: (data) => {
+            ws.send(data, (error) => {
+                if (error)
+                    socket.onError?.(errorMessage(error));
+            });
+        },
+        close: (code, reason) => ws.close(code, reason),
+        onMessage: undefined,
+        onError: undefined,
+        onClose: undefined,
+    };
+    ws.on("message", (data) => socket.onMessage?.(rawDataToString(data)));
+    ws.on("error", (error) => socket.onError?.(errorMessage(error)));
+    ws.on("close", (code) => socket.onClose?.(code));
+    return socket;
+};
+function openSocket(socket, signal) {
+    return new Promise((resolve, reject) => {
+        const settle = (result) => {
+            socket.off("open", onOpen);
+            socket.off("error", onError);
+            socket.off("close", onClose);
+            signal.removeEventListener("abort", onAbort);
+            result();
+        };
+        const onOpen = () => settle(resolve);
+        const onError = (error) => settle(() => reject(error));
+        const onClose = (code) => settle(() => reject(new Error(`Socket closed during handshake with code ${code}`)));
+        const onAbort = () => settle(() => {
+            socket.terminate();
+            reject(new Error(`Connection aborted: ${String(signal.reason ?? "aborted")}`));
+        });
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        socket.once("open", onOpen);
+        socket.once("error", onError);
+        socket.once("close", onClose);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function rawDataToString(data) {
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString("utf8");
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data).toString("utf8");
+    return data.toString("utf8");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/internal/provider/openai-realtime.d.ts

@@ -0,0 +1,43 @@
+import type { CreateProviderSessionOptions, VoiceProvider, VoiceProviderSession } from "./contract.js";
+import { type RealtimeSocketFactory } from "./realtime-socket.js";
+export interface OpenAIRealtimeProviderOptions {
+    apiKey: string;
+    /** Transport override; defaults to the runtime's registered factory (Node ws or Workers). */
+    socketFactory?: RealtimeSocketFactory;
+    /** Realtime-capable model id. Swap this for gpt-live once its API is public. */
+    model?: string;
+    /** WebSocket endpoint, overridable for tests and proxies. */
+    url?: string;
+    /** Output voice name. Omitted by default so the API default applies. */
+    voice?: string;
+    /** Sample rate of the PCM16 mono input the harness will send. */
+    inputSampleRate?: number;
+    /** Server-side turn detection. Defaults to semantic VAD; null disables it for push-to-talk. */
+    turnDetection?: Record<string, unknown> | null;
+    /** Input transcription model; final transcripts surface as transcript events. Null disables. */
+    transcriptionModel?: string | null;
+    /** Request a spoken response when a background task settles. */
+    announceTaskSettlement?: boolean;
+    handshakeTimeoutMs?: number;
+}
+/**
+ * Adapts the OpenAI Realtime API to the XO duplex provider contract.
+ *
+ * The Realtime API is turn-based under the hood: server-side VAD decides when the model
+ * takes the floor, and barge-in works by truncating the assistant item at the last
+ * acknowledged playout position. The shared realtime session absorbs that so the harness
+ * can treat the model as fully duplex.
+ */
+export declare class OpenAIRealtimeVoiceProvider implements VoiceProvider {
+    #private;
+    readonly id = "openai-realtime";
+    readonly capabilities: {
+        readonly continuousInputDuringOutput: true;
+        readonly modelManagedFloor: true;
+        readonly supportsToolCalls: true;
+        readonly supportsAsyncContext: true;
+        readonly supportsPlayoutAcknowledgements: true;
+    };
+    constructor(options: OpenAIRealtimeProviderOptions);
+    createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;
+}

package/dist/internal/provider/openai-realtime.js

@@ -0,0 +1,76 @@
+import { RealtimeVoiceSession, toRealtimeFunctionTool } from "./realtime-session.js";
+import { connectRealtimeSocket } from "./realtime-socket.js";
+const DEFAULT_URL = "wss://api.openai.com/v1/realtime";
+const DEFAULT_MODEL = "gpt-realtime-2";
+const DEFAULT_SAMPLE_RATE = 24_000;
+const DEFAULT_TRANSCRIPTION_MODEL = "gpt-4o-mini-transcribe";
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 15_000;
+/**
+ * Adapts the OpenAI Realtime API to the XO duplex provider contract.
+ *
+ * The Realtime API is turn-based under the hood: server-side VAD decides when the model
+ * takes the floor, and barge-in works by truncating the assistant item at the last
+ * acknowledged playout position. The shared realtime session absorbs that so the harness
+ * can treat the model as fully duplex.
+ */
+export class OpenAIRealtimeVoiceProvider {
+    id = "openai-realtime";
+    capabilities = {
+        continuousInputDuringOutput: true,
+        modelManagedFloor: true,
+        supportsToolCalls: true,
+        supportsAsyncContext: true,
+        supportsPlayoutAcknowledgements: true,
+    };
+    #options;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("OpenAIRealtimeVoiceProvider requires an apiKey");
+        this.#options = options;
+    }
+    async createSession(options) {
+        const inputSampleRate = this.#options.inputSampleRate ?? DEFAULT_SAMPLE_RATE;
+        const socket = await connectRealtimeSocket({
+            url: this.#options.url ?? DEFAULT_URL,
+            model: this.#options.model ?? DEFAULT_MODEL,
+            apiKey: this.#options.apiKey,
+            authProtocols: ["realtime", `openai-insecure-api-key.${this.#options.apiKey}`],
+            handshakeTimeoutMs: this.#options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS,
+            signal: options.signal,
+            ...(this.#options.socketFactory === undefined ? {} : { factory: this.#options.socketFactory }),
+        });
+        return new RealtimeVoiceSession(socket, {
+            label: "OpenAI Realtime",
+            sessionUpdate: this.#sessionUpdate(options, inputSampleRate),
+            inputSampleRate,
+            outputSampleRate: DEFAULT_SAMPLE_RATE,
+            announceTaskSettlement: this.#options.announceTaskSettlement ?? true,
+        }, options);
+    }
+    #sessionUpdate(options, inputSampleRate) {
+        const turnDetection = this.#options.turnDetection === undefined ? { type: "semantic_vad" } : this.#options.turnDetection;
+        const transcriptionModel = this.#options.transcriptionModel === undefined
+            ? DEFAULT_TRANSCRIPTION_MODEL
+            : this.#options.transcriptionModel;
+        const session = {
+            type: "realtime",
+            model: this.#options.model ?? DEFAULT_MODEL,
+            output_modalities: [...(options.outputModalities ?? ["audio"])],
+            audio: {
+                input: {
+                    format: { type: "audio/pcm", rate: inputSampleRate },
+                    turn_detection: turnDetection,
+                    ...(transcriptionModel === null ? {} : { transcription: { model: transcriptionModel } }),
+                },
+                output: {
+                    format: { type: "audio/pcm", rate: DEFAULT_SAMPLE_RATE },
+                    ...(this.#options.voice === undefined ? {} : { voice: this.#options.voice }),
+                },
+            },
+            tools: options.tools.map(toRealtimeFunctionTool),
+        };
+        if (options.instructions !== undefined)
+            session.instructions = options.instructions;
+        return session;
+    }
+}

package/dist/internal/provider/realtime-session.d.ts

@@ -0,0 +1,30 @@
+import { type AudioChunk, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolDefinition, type ProviderToolResult } from "../protocol/index.js";
+import type { CreateProviderSessionOptions, VoiceProviderSession } from "./contract.js";
+import type { RealtimeSocket } from "./realtime-socket.js";
+/**
+ * Wire-level configuration for one realtime session. Providers own the dialect —
+ * the exact session.update payload — while this session owns the shared duplex
+ * bridge: continuous input, sample-addressed output, tool calls, context items,
+ * and barge-in truncation at the last acknowledged playout sample.
+ */
+export interface RealtimeWireOptions {
+    /** Provider label used in error messages, e.g. "OpenAI Realtime". */
+    label: string;
+    /** Complete session.update payload sent once the socket opens. */
+    sessionUpdate: Record<string, unknown>;
+    inputSampleRate: number;
+    outputSampleRate: number;
+    announceTaskSettlement: boolean;
+}
+export declare class RealtimeVoiceSession implements VoiceProviderSession {
+    #private;
+    constructor(socket: RealtimeSocket, wire: RealtimeWireOptions, options: CreateProviderSessionOptions);
+    get events(): AsyncIterable<ProviderEvent>;
+    sendAudio(chunk: AudioChunk): Promise<void>;
+    sendText(text: string): Promise<void>;
+    reportPlayout(progress: PlayoutProgress): Promise<void>;
+    sendToolResult(result: ProviderToolResult): Promise<void>;
+    sendContext(event: ProviderContextEvent): Promise<void>;
+    close(reason?: string): Promise<void>;
+}
+export declare function toRealtimeFunctionTool(definition: ProviderToolDefinition): Record<string, unknown>;