xo-harness 0.1.0

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

@@ -0,0 +1,461 @@
+import { Buffer } from "node:buffer";
+import { AsyncQueue, AudioChunkSchema, audioSampleCount, PlayoutProgressSchema, ProviderContextEventSchema, ProviderToolResultSchema, ToolCallSchema, } from "../protocol/index.js";
+import { z } from "zod";
+const FALLBACK_STREAM_ID = "assistant-output";
+const CLOSE_REASON_BYTE_LIMIT = 120;
+const ServerEnvelopeSchema = z.looseObject({ type: z.string().min(1) });
+const OutputAudioDeltaSchema = z.looseObject({
+    item_id: z.string().min(1).optional(),
+    response_id: z.string().min(1).optional(),
+    delta: z.string().min(1).optional(),
+    data: z.string().min(1).optional(),
+});
+const FunctionCallItemSchema = z.looseObject({
+    type: z.literal("function_call"),
+    call_id: z.string().min(1),
+    name: z.string().min(1),
+    arguments: z.string(),
+});
+const FunctionCallArgumentsDoneSchema = z.looseObject({
+    call_id: z.string().min(1),
+    name: z.string().min(1),
+    arguments: z.string(),
+});
+const UsageDetailsSchema = z.looseObject({
+    text_tokens: z.number().int().nonnegative().optional(),
+    audio_tokens: z.number().int().nonnegative().optional(),
+    cached_tokens: z.number().int().nonnegative().optional(),
+    cached_tokens_details: z
+        .looseObject({
+        text_tokens: z.number().int().nonnegative().optional(),
+        audio_tokens: z.number().int().nonnegative().optional(),
+    })
+        .optional(),
+});
+const ResponseDoneSchema = z.looseObject({
+    response: z.looseObject({
+        output: z.array(z.looseObject({ type: z.string().optional() })).optional(),
+        usage: z
+            .looseObject({
+            total_tokens: z.number().int().nonnegative(),
+            input_tokens: z.number().int().nonnegative(),
+            output_tokens: z.number().int().nonnegative(),
+            input_token_details: UsageDetailsSchema.optional(),
+            output_token_details: UsageDetailsSchema.optional(),
+        })
+            .optional(),
+    }),
+});
+const TranscriptEventSchema = z.looseObject({
+    transcript: z.string(),
+    item_id: z.string().min(1).optional(),
+});
+const OutputTextDoneSchema = z.looseObject({
+    text: z.string(),
+    item_id: z.string().min(1).optional(),
+});
+const TranscriptDeltaWireSchema = z.looseObject({
+    delta: z.string(),
+    item_id: z.string().min(1).optional(),
+});
+const ServerErrorSchema = z.looseObject({
+    error: z.looseObject({ message: z.string().optional() }).optional(),
+});
+const SessionUpdatedSchema = z.looseObject({
+    session: z
+        .looseObject({
+        audio: z
+            .looseObject({
+            output: z
+                .looseObject({
+                format: z.looseObject({ rate: z.int().positive().optional() }).optional(),
+            })
+                .optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+});
+export class RealtimeVoiceSession {
+    #socket;
+    #wire;
+    #queue = new AsyncQueue();
+    #outputStreams = new Map();
+    #playedThrough = new Map();
+    #deliveredToolCalls = new Set();
+    #settled;
+    #resolveSettled;
+    #outputSampleRate;
+    #activeOutputItemId;
+    #responseActive = false;
+    #responseWanted = false;
+    #ready = false;
+    #closed = false;
+    #closeReason;
+    constructor(socket, wire, options) {
+        this.#socket = socket;
+        this.#wire = wire;
+        this.#outputSampleRate = wire.outputSampleRate;
+        this.#settled = new Promise((resolve) => {
+            this.#resolveSettled = resolve;
+        });
+        socket.onMessage = (text) => this.#handleMessage(text);
+        socket.onError = (message) => this.#emitError(message, false);
+        socket.onClose = (code) => this.#settle(this.#closeReason ?? `socket_closed_${code}`);
+        options.signal.addEventListener("abort", () => {
+            void this.close(String(options.signal.reason ?? "aborted"));
+        }, { once: true });
+        this.#send({ type: "session.update", session: wire.sessionUpdate });
+    }
+    get events() {
+        return this.#queue;
+    }
+    async sendAudio(chunk) {
+        const validated = AudioChunkSchema.parse(chunk);
+        if (validated.channels !== 1) {
+            throw new Error(`${this.#wire.label} expects mono PCM input`);
+        }
+        if (validated.sampleRate !== this.#wire.inputSampleRate) {
+            throw new Error(`${this.#wire.label} session is configured for ${this.#wire.inputSampleRate} Hz input, received ${validated.sampleRate} Hz`);
+        }
+        this.#send({ type: "input_audio_buffer.append", audio: toBase64(validated.data) });
+    }
+    async sendText(text) {
+        this.#send({
+            type: "conversation.item.create",
+            item: { type: "message", role: "user", content: [{ type: "input_text", text }] },
+        });
+        this.#requestResponse();
+    }
+    async reportPlayout(progress) {
+        const validated = PlayoutProgressSchema.parse(progress);
+        this.#playedThrough.set(validated.streamId, validated.playedThroughSample);
+    }
+    async sendToolResult(result) {
+        const validated = ProviderToolResultSchema.parse(result);
+        this.#send({
+            type: "conversation.item.create",
+            item: {
+                type: "function_call_output",
+                call_id: validated.callId,
+                output: toolOutcomePayload(validated.outcome),
+            },
+        });
+        this.#requestResponse();
+    }
+    async sendContext(event) {
+        const validated = ProviderContextEventSchema.parse(event);
+        this.#send({
+            type: "conversation.item.create",
+            item: {
+                type: "message",
+                role: "system",
+                content: [{ type: "input_text", text: contextText(validated) }],
+            },
+        });
+        if (validated.type !== "task.progress" && this.#wire.announceTaskSettlement) {
+            this.#requestResponse();
+        }
+    }
+    async close(reason = "client_closed") {
+        this.#closeReason ??= reason;
+        if (!this.#closed) {
+            if (this.#socket.state === "closed") {
+                this.#settle(this.#closeReason);
+            }
+            else {
+                this.#socket.close(1000, truncateCloseReason(this.#closeReason));
+            }
+        }
+        await this.#settled;
+    }
+    #handleMessage(text) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            this.#emitError(`Received malformed JSON from ${this.#wire.label}`, true);
+            return;
+        }
+        const envelope = ServerEnvelopeSchema.safeParse(parsed);
+        if (!envelope.success) {
+            this.#emitError(`Received a ${this.#wire.label} event without a type`, true);
+            return;
+        }
+        switch (envelope.data.type) {
+            case "session.updated":
+                this.#handleSessionUpdated(parsed);
+                break;
+            case "response.created":
+                this.#responseActive = true;
+                break;
+            case "response.output_audio.delta":
+                this.#handleAudioDelta(parsed);
+                break;
+            case "response.output_audio_transcript.delta":
+            case "response.output_text.delta":
+                this.#handleTranscriptDelta(parsed);
+                break;
+            case "response.output_audio_transcript.done":
+                this.#handleTranscript(parsed, "assistant");
+                break;
+            case "response.output_text.done":
+                this.#handleOutputText(parsed);
+                break;
+            case "conversation.item.input_audio_transcription.completed":
+                this.#handleTranscript(parsed, "user");
+                break;
+            case "response.function_call_arguments.done":
+                this.#handleFunctionCallArgumentsDone(parsed);
+                break;
+            case "response.done":
+                this.#handleResponseDone(parsed);
+                break;
+            case "input_audio_buffer.speech_started":
+                this.#handleSpeechStarted();
+                break;
+            case "error":
+                this.#handleServerError(parsed);
+                break;
+            default:
+                break;
+        }
+    }
+    #handleSessionUpdated(parsed) {
+        const updated = SessionUpdatedSchema.safeParse(parsed);
+        const rate = updated.success ? updated.data.session?.audio?.output?.format?.rate : undefined;
+        if (rate !== undefined)
+            this.#outputSampleRate = rate;
+        if (!this.#ready) {
+            this.#ready = true;
+            this.#emit({ type: "ready" });
+        }
+    }
+    #handleAudioDelta(parsed) {
+        const delta = OutputAudioDeltaSchema.safeParse(parsed);
+        if (!delta.success) {
+            this.#emitError("Received a malformed output audio delta", true);
+            return;
+        }
+        const payload = delta.data.delta ?? delta.data.data;
+        if (payload === undefined) {
+            this.#emitError("Received an output audio delta without an audio payload", true);
+            return;
+        }
+        const bytes = Buffer.from(payload, "base64");
+        if (bytes.byteLength === 0 || bytes.byteLength % 2 !== 0) {
+            this.#emitError(`Received a PCM16 delta with invalid byte length ${bytes.byteLength}`, true);
+            return;
+        }
+        const streamId = delta.data.item_id ?? delta.data.response_id ?? FALLBACK_STREAM_ID;
+        const stream = this.#outputStreams.get(streamId) ?? { sequence: 0, startSample: 0 };
+        const chunk = AudioChunkSchema.parse({
+            streamId,
+            sequence: stream.sequence,
+            encoding: "pcm_s16le",
+            sampleRate: this.#outputSampleRate,
+            channels: 1,
+            startSample: stream.startSample,
+            data: new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+        });
+        stream.sequence += 1;
+        stream.startSample += audioSampleCount(chunk);
+        this.#outputStreams.set(streamId, stream);
+        this.#activeOutputItemId = streamId;
+        this.#emit({ type: "audio.output", chunk });
+    }
+    #handleTranscript(parsed, role) {
+        const transcript = TranscriptEventSchema.safeParse(parsed);
+        if (!transcript.success)
+            return;
+        this.#emitTranscript(role, transcript.data.transcript, transcript.data.item_id);
+    }
+    #handleTranscriptDelta(parsed) {
+        const delta = TranscriptDeltaWireSchema.safeParse(parsed);
+        if (!delta.success || delta.data.delta === "")
+            return;
+        this.#emit({
+            type: "transcript.delta",
+            role: "assistant",
+            delta: delta.data.delta,
+            ...(delta.data.item_id === undefined ? {} : { streamId: delta.data.item_id }),
+        });
+    }
+    #handleOutputText(parsed) {
+        const output = OutputTextDoneSchema.safeParse(parsed);
+        if (!output.success)
+            return;
+        this.#emitTranscript("assistant", output.data.text, output.data.item_id);
+    }
+    #emitTranscript(role, rawText, streamId) {
+        const text = rawText.trim();
+        if (text === "")
+            return;
+        this.#emit({ type: "transcript", role, text, ...(streamId === undefined ? {} : { streamId }) });
+    }
+    #handleFunctionCallArgumentsDone(parsed) {
+        const done = FunctionCallArgumentsDoneSchema.safeParse(parsed);
+        if (!done.success)
+            return;
+        this.#emitFunctionCall(done.data.call_id, done.data.name, done.data.arguments);
+    }
+    #handleResponseDone(parsed) {
+        this.#responseActive = false;
+        this.#activeOutputItemId = undefined;
+        const done = ResponseDoneSchema.safeParse(parsed);
+        if (done.success) {
+            const usage = done.data.response.usage;
+            if (usage)
+                this.#emitUsage(usage);
+            for (const item of done.data.response.output ?? []) {
+                if (item.type !== "function_call")
+                    continue;
+                const call = FunctionCallItemSchema.safeParse(item);
+                if (!call.success) {
+                    this.#emitError("Received a function call item without call_id, name, or arguments", true);
+                    continue;
+                }
+                this.#emitFunctionCall(call.data.call_id, call.data.name, call.data.arguments);
+            }
+        }
+        if (this.#responseWanted)
+            this.#requestResponse();
+    }
+    #emitUsage(usage) {
+        const input = usage.input_token_details;
+        const output = usage.output_token_details;
+        this.#emit({
+            type: "usage",
+            inputTokens: usage.input_tokens,
+            outputTokens: usage.output_tokens,
+            totalTokens: usage.total_tokens,
+            ...(input?.cached_tokens === undefined ? {} : { cachedInputTokens: input.cached_tokens }),
+            ...(input?.audio_tokens === undefined ? {} : { audioInputTokens: input.audio_tokens }),
+            ...(output?.audio_tokens === undefined ? {} : { audioOutputTokens: output.audio_tokens }),
+            ...(input?.cached_tokens_details?.audio_tokens === undefined
+                ? {}
+                : { cachedAudioInputTokens: input.cached_tokens_details.audio_tokens }),
+        });
+    }
+    #emitFunctionCall(callId, name, rawArguments) {
+        if (this.#deliveredToolCalls.has(callId))
+            return;
+        let parsedArguments;
+        try {
+            parsedArguments = rawArguments.trim() === "" ? {} : JSON.parse(rawArguments);
+        }
+        catch {
+            this.#emitError(`Could not parse arguments for tool call ${name}`, true);
+            return;
+        }
+        if (parsedArguments === null || typeof parsedArguments !== "object" || Array.isArray(parsedArguments)) {
+            this.#emitError(`Tool call ${name} arguments are not a JSON object`, true);
+            return;
+        }
+        this.#deliveredToolCalls.add(callId);
+        this.#emit({
+            type: "tool.call",
+            call: ToolCallSchema.parse({ callId, name, arguments: parsedArguments }),
+        });
+    }
+    #handleSpeechStarted() {
+        const itemId = this.#activeOutputItemId;
+        if (itemId === undefined)
+            return;
+        this.#activeOutputItemId = undefined;
+        const playedThroughSample = this.#playedThrough.get(itemId);
+        if (playedThroughSample === undefined)
+            return;
+        this.#trySend({
+            type: "conversation.item.truncate",
+            item_id: itemId,
+            content_index: 0,
+            audio_end_ms: Math.floor((playedThroughSample / this.#outputSampleRate) * 1000),
+        });
+    }
+    #handleServerError(parsed) {
+        const error = ServerErrorSchema.safeParse(parsed);
+        const message = error.success ? error.data.error?.message : undefined;
+        this.#emitError(message ?? `${this.#wire.label} reported an error`, true);
+    }
+    #requestResponse() {
+        if (this.#responseActive) {
+            this.#responseWanted = true;
+            return;
+        }
+        this.#responseWanted = false;
+        this.#responseActive = true;
+        this.#trySend({ type: "response.create" });
+    }
+    #send(payload) {
+        if (this.#socket.state !== "open") {
+            throw new Error(`${this.#wire.label} session socket is not open`);
+        }
+        this.#socket.send(JSON.stringify(payload));
+    }
+    /** For sends triggered by incoming events: a closing socket is settlement, not an error. */
+    #trySend(payload) {
+        if (this.#socket.state !== "open")
+            return;
+        this.#send(payload);
+    }
+    #emit(event) {
+        if (this.#closed)
+            return;
+        this.#queue.push(event);
+    }
+    #emitError(message, recoverable) {
+        this.#emit({ type: "error", message, recoverable });
+    }
+    #settle(reason) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#queue.push({ type: "closed", reason });
+        this.#queue.close();
+        this.#resolveSettled();
+    }
+}
+export function toRealtimeFunctionTool(definition) {
+    return {
+        type: "function",
+        name: definition.name,
+        description: definition.description,
+        parameters: definition.inputSchema,
+    };
+}
+function toolOutcomePayload(outcome) {
+    switch (outcome.type) {
+        case "completed":
+            return JSON.stringify(outcome.value);
+        case "accepted_task":
+            return JSON.stringify({
+                status: "accepted_task",
+                taskId: outcome.taskId,
+                note: "The task is running in the background; updates will arrive as system context.",
+            });
+        case "failed":
+            return JSON.stringify({ status: "failed", error: outcome.error });
+    }
+}
+function contextText(event) {
+    switch (event.type) {
+        case "task.progress":
+            return `Background task ${event.taskId} progress: ${JSON.stringify(event.update)}`;
+        case "task.completed":
+            return `Background task ${event.taskId} completed with result: ${JSON.stringify(event.result)}`;
+        case "task.failed":
+            return `Background task ${event.taskId} failed: ${event.error}`;
+        case "task.cancelled":
+            return `Background task ${event.taskId} was cancelled: ${event.reason}`;
+    }
+}
+function toBase64(data) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("base64");
+}
+function truncateCloseReason(reason) {
+    return Buffer.byteLength(reason, "utf8") <= CLOSE_REASON_BYTE_LIMIT
+        ? reason
+        : Buffer.from(reason, "utf8").subarray(0, CLOSE_REASON_BYTE_LIMIT).toString("utf8");
+}

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

@@ -0,0 +1,42 @@
+export type RealtimeSocketState = "connecting" | "open" | "closing" | "closed";
+/**
+ * The minimal transport surface the realtime session needs. Adapters normalize incoming
+ * frames to text and surface lifecycle through assignable callbacks, so the same session
+ * runs on Node (ws) and on Cloudflare Workers (fetch upgrade) unchanged.
+ */
+export interface RealtimeSocket {
+    readonly state: RealtimeSocketState;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onMessage: ((text: string) => void) | undefined;
+    onError: ((message: string) => void) | undefined;
+    onClose: ((code: number) => void) | undefined;
+}
+export interface RealtimeSocketTarget {
+    /** Full endpoint including the model query parameter. */
+    url: string;
+    apiKey: string;
+    /** Subprotocol-based auth (e.g. OpenAI's), for runtimes whose standard WebSocket
+     *  constructor cannot send an Authorization header. */
+    authProtocols?: readonly string[];
+    handshakeTimeoutMs: number;
+    signal: AbortSignal;
+}
+export type RealtimeSocketFactory = (target: RealtimeSocketTarget) => Promise<RealtimeSocket>;
+/**
+ * Entry modules register their runtime's factory; providers resolve it lazily. Registration
+ * is write-once: re-registering the same factory is a no-op, and registering a different
+ * one throws so that mixing entries never silently depends on import order.
+ */
+export declare function setDefaultRealtimeSocketFactory(factory: RealtimeSocketFactory): void;
+export declare function getDefaultRealtimeSocketFactory(): RealtimeSocketFactory;
+export interface ConnectRealtimeSocketOptions {
+    url: string;
+    model: string;
+    apiKey: string;
+    authProtocols?: readonly string[];
+    handshakeTimeoutMs: number;
+    signal: AbortSignal;
+    factory?: RealtimeSocketFactory;
+}
+export declare function connectRealtimeSocket(options: ConnectRealtimeSocketOptions): Promise<RealtimeSocket>;

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

@@ -0,0 +1,30 @@
+let defaultFactory;
+/**
+ * Entry modules register their runtime's factory; providers resolve it lazily. Registration
+ * is write-once: re-registering the same factory is a no-op, and registering a different
+ * one throws so that mixing entries never silently depends on import order.
+ */
+export function setDefaultRealtimeSocketFactory(factory) {
+    if (defaultFactory === factory)
+        return;
+    if (defaultFactory !== undefined) {
+        throw new Error("A default realtime socket factory is already registered. Import exactly one of xo-harness/provider (Node) and xo-harness/provider/workers per process, or pass socketFactory explicitly.");
+    }
+    defaultFactory = factory;
+}
+export function getDefaultRealtimeSocketFactory() {
+    if (!defaultFactory) {
+        throw new Error("No realtime socket factory is registered. Import xo-harness/provider (Node) or xo-harness/provider/workers first, or pass socketFactory explicitly.");
+    }
+    return defaultFactory;
+}
+export function connectRealtimeSocket(options) {
+    const factory = options.factory ?? getDefaultRealtimeSocketFactory();
+    return factory({
+        url: `${options.url}?model=${encodeURIComponent(options.model)}`,
+        apiKey: options.apiKey,
+        handshakeTimeoutMs: options.handshakeTimeoutMs,
+        signal: options.signal,
+        ...(options.authProtocols === undefined ? {} : { authProtocols: options.authProtocols }),
+    });
+}

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

@@ -0,0 +1,11 @@
+import type { RealtimeSocketFactory } from "./realtime-socket.js";
+/**
+ * Cloudflare Workers transport. Primary path: fetch upgrade with an Authorization
+ * header — the server-proper auth mechanism, and the one provider edges accept when
+ * they reject the browser-style subprotocol handshake from Workers egress (observed
+ * live 2026-08-11, production outage). Fallback: the standard WebSocket constructor
+ * with subprotocol auth, whose sockets get the runtime's full protocol handling
+ * (ping/pong) — a keepalive edge fetch-upgraded sockets have not always received;
+ * duplex media traffic keeps provider sessions busy enough that it has not bitten.
+ */
+export declare const workersSocketFactory: RealtimeSocketFactory;

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

@@ -0,0 +1,108 @@
+/**
+ * Cloudflare Workers transport. Primary path: fetch upgrade with an Authorization
+ * header — the server-proper auth mechanism, and the one provider edges accept when
+ * they reject the browser-style subprotocol handshake from Workers egress (observed
+ * live 2026-08-11, production outage). Fallback: the standard WebSocket constructor
+ * with subprotocol auth, whose sockets get the runtime's full protocol handling
+ * (ping/pong) — a keepalive edge fetch-upgraded sockets have not always received;
+ * duplex media traffic keeps provider sessions busy enough that it has not bitten.
+ */
+export const workersSocketFactory = async (target) => {
+    try {
+        return await fetchUpgradeSocket(target);
+    }
+    catch (error) {
+        const fallback = await subprotocolSocket(target);
+        if (!fallback)
+            throw error;
+        console.warn("fetch-upgrade handshake failed, falling back to subprotocol auth", error);
+        return fallback;
+    }
+};
+/** The native WebSocket + auth-subprotocol handshake; undefined when unavailable. */
+const subprotocolSocket = async (target) => {
+    if (!target.authProtocols || target.authProtocols.length === 0)
+        return undefined;
+    const WorkersWebSocket = globalThis.WebSocket;
+    if (!WorkersWebSocket)
+        return undefined;
+    const ws = new WorkersWebSocket(target.url, [...target.authProtocols]);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("Realtime WebSocket handshake timed out")), target.handshakeTimeoutMs);
+        ws.addEventListener("open", () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        ws.addEventListener("error", () => {
+            clearTimeout(timer);
+            reject(new Error("Realtime WebSocket handshake failed"));
+        });
+        ws.addEventListener("close", () => {
+            clearTimeout(timer);
+            reject(new Error("Realtime WebSocket closed during handshake"));
+        });
+    });
+    return wrapWorkersWebSocket(ws, target.signal);
+};
+const fetchUpgradeSocket = async (target) => {
+    const url = target.url.replace(/^ws(s?):/, "http$1:");
+    // The timeout must guard only the handshake. An AbortSignal passed to fetch stays
+    // attached to the upgraded connection on this runtime and would kill the live
+    // socket when it fires — so the deadline is raced, never attached.
+    let handshakeTimer;
+    const response = await Promise.race([
+        fetch(url, {
+            headers: { Upgrade: "websocket", Authorization: `Bearer ${target.apiKey}` },
+        }),
+        new Promise((_resolve, reject) => {
+            handshakeTimer = setTimeout(() => reject(new Error("Realtime WebSocket handshake timed out")), target.handshakeTimeoutMs);
+        }),
+    ]).finally(() => clearTimeout(handshakeTimer));
+    const ws = response.webSocket;
+    if (!ws) {
+        throw new Error(`Realtime WebSocket upgrade failed with status ${response.status}`);
+    }
+    ws.accept();
+    return wrapWorkersWebSocket(ws, target.signal);
+};
+function wrapWorkersWebSocket(ws, signal) {
+    let state = "open";
+    const socket = {
+        get state() {
+            return state;
+        },
+        send: (data) => ws.send(data),
+        close: (code, reason) => {
+            if (state === "open")
+                state = "closing";
+            ws.close(code, reason);
+        },
+        onMessage: undefined,
+        onError: undefined,
+        onClose: undefined,
+    };
+    ws.addEventListener("message", (event) => {
+        if (typeof event.data === "string") {
+            socket.onMessage?.(event.data);
+        }
+        else if (event.data instanceof ArrayBuffer) {
+            socket.onMessage?.(new TextDecoder().decode(event.data));
+        }
+    });
+    ws.addEventListener("close", (event) => {
+        state = "closed";
+        socket.onClose?.(event.code ?? 1005);
+    });
+    ws.addEventListener("error", () => {
+        // Close races surface as error events on this runtime; settlement is not an error.
+        if (state !== "open")
+            return;
+        // An errored socket on workerd may never deliver a close event, so an error while
+        // open IS the close: report it, then settle, or the session waits forever.
+        state = "closed";
+        socket.onError?.("Realtime WebSocket transport error");
+        socket.onClose?.(1006);
+    });
+    signal.addEventListener("abort", () => socket.close(1000, "aborted"), { once: true });
+    return socket;
+}

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

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

package/dist/internal/provider/workers.js

@@ -0,0 +1,11 @@
+// Cloudflare Workers entry: identical provider surface, fetch-upgrade transport,
+// and no ws dependency anywhere in the module graph.
+import { setDefaultRealtimeSocketFactory } from "./realtime-socket.js";
+import { workersSocketFactory } from "./workers-socket.js";
+setDefaultRealtimeSocketFactory(workersSocketFactory);
+export * from "./contract.js";
+export * from "./grok-voice.js";
+export * from "./openai-realtime.js";
+export { RealtimeVoiceSession } from "./realtime-session.js";
+export * from "./realtime-socket.js";
+export { workersSocketFactory } from "./workers-socket.js";