xo-harness 0.2.0 → 0.3.0

package/dist/internal/browser/browser-voice-client.js

@@ -0,0 +1,316 @@
+import { MessageInputTextSchema } from "../protocol/index.js";
+const INPUT_SAMPLE_RATE = 24_000;
+/** One live voice conversation: microphone up over the socket, model audio down to the speakers. */
+export class BrowserVoiceClient {
+    #socket;
+    #context;
+    #media;
+    #player;
+    #running = true;
+    #started = false;
+    #stopping = false;
+    #closed = Promise.withResolvers();
+    #teardownPromise;
+    constructor(socket, context, media, player) {
+        this.#socket = socket;
+        this.#context = context;
+        this.#media = media;
+        this.#player = player;
+    }
+    /** Resolves after submitting start locally; onStarted reports the server's readiness frame. */
+    static async start(options, callbacks) {
+        const { signal } = options;
+        signal?.throwIfAborted();
+        const context = new AudioContext({ sampleRate: INPUT_SAMPLE_RATE });
+        if (context.sampleRate !== INPUT_SAMPLE_RATE) {
+            await context.close();
+            throw new Error(`AudioContext runs at ${context.sampleRate} Hz; this browser cannot resample to 24 kHz`);
+        }
+        let acquiredMedia;
+        let openedSocket;
+        try {
+            await duringStartup(Promise.all([
+                context.audioWorklet.addModule(String(options.workletUrls.capture)),
+                context.audioWorklet.addModule(String(options.workletUrls.playback)),
+            ]), signal);
+            signal?.throwIfAborted();
+            const media = await duringStartup(navigator.mediaDevices.getUserMedia({
+                audio: {
+                    channelCount: 1,
+                    echoCancellation: { exact: true },
+                    noiseSuppression: true,
+                    autoGainControl: true,
+                },
+            }), signal, (lateMedia) => {
+                for (const track of lateMedia.getTracks())
+                    track.stop();
+            });
+            acquiredMedia = media;
+            signal?.throwIfAborted();
+            if (!media.getAudioTracks()[0]?.getSettings().echoCancellation) {
+                throw new Error("This browser could not enable microphone echo cancellation. Use a browser that supports echo-cancelled capture.");
+            }
+            const socket = new WebSocket(options.socketUrl);
+            openedSocket = socket;
+            socket.binaryType = "arraybuffer";
+            await duringStartup(new Promise((resolve, reject) => {
+                socket.onopen = () => resolve();
+                socket.onerror = () => reject(new Error("Could not open the voice socket"));
+                socket.onclose = () => reject(new Error("Voice socket closed before connecting"));
+            }), signal);
+            signal?.throwIfAborted();
+            const source = context.createMediaStreamSource(media);
+            const capture = new AudioWorkletNode(context, "xo-capture", {
+                numberOfInputs: 1,
+                numberOfOutputs: 0,
+            });
+            source.connect(capture);
+            const player = new AudioWorkletNode(context, "xo-playback", {
+                numberOfInputs: 0,
+                numberOfOutputs: 1,
+                outputChannelCount: [1],
+            });
+            player.connect(context.destination);
+            const session = new BrowserVoiceClient(socket, context, media, player);
+            const fail = (error, reason = "audio_error") => {
+                if (!session.#running)
+                    return;
+                void session.#teardown();
+                callbacks.onError(error instanceof Error ? error.message : String(error));
+                callbacks.onClosed(reason);
+            };
+            const send = (data) => {
+                try {
+                    socket.send(data);
+                    return true;
+                }
+                catch (error) {
+                    fail(error, "socket_error");
+                    return false;
+                }
+            };
+            capture.onprocessorerror = () => fail(new Error("Microphone audio processing failed"));
+            player.onprocessorerror = () => fail(new Error("Playback audio processing failed"));
+            capture.port.onmessage = (event) => {
+                if (!session.#running || !session.#started || socket.readyState !== WebSocket.OPEN)
+                    return;
+                if (socket.bufferedAmount + event.data.byteLength > INPUT_SAMPLE_RATE * 2 * 30) {
+                    fail(new Error("Microphone upload is more than 30 seconds behind"));
+                    return;
+                }
+                if (send(event.data))
+                    callbacks.onStats({ sentBytes: event.data.byteLength });
+            };
+            player.port.onmessage = (event) => {
+                if (!session.#running)
+                    return;
+                if (event.data.type === "playout.error") {
+                    fail(new Error(event.data.message ?? "Playback audio processing failed"));
+                    return;
+                }
+                if (event.data.type === "playout.underrun" || event.data.type === "playout.rebuffered") {
+                    callbacks.onEvent(event.data);
+                    return;
+                }
+                if (socket.readyState !== WebSocket.OPEN)
+                    return;
+                if (event.data.type === "playout.range") {
+                    send(JSON.stringify(event.data));
+                    return;
+                }
+                if (event.data.type !== "playout")
+                    return;
+                send(JSON.stringify({
+                    type: "playout",
+                    streamId: event.data.streamId,
+                    playedThroughSample: event.data.playedThroughSample,
+                }));
+            };
+            socket.onmessage = (event) => {
+                if (!session.#running)
+                    return;
+                try {
+                    if (typeof event.data === "string") {
+                        session.#handleControl(JSON.parse(event.data), callbacks);
+                    }
+                    else if (!session.#stopping) {
+                        session.#handleAudioFrame(event.data, callbacks);
+                    }
+                }
+                catch (error) {
+                    fail(error);
+                }
+            };
+            socket.onclose = () => {
+                const notify = session.#running;
+                void session.#teardown();
+                if (notify)
+                    callbacks.onClosed("socket_closed");
+            };
+            socket.send(JSON.stringify({ ...options.start, type: "start" }));
+            return session;
+        }
+        catch (error) {
+            for (const track of acquiredMedia?.getTracks() ?? [])
+                track.stop();
+            openedSocket?.close();
+            await context.close().catch(() => undefined);
+            throw error;
+        }
+    }
+    async stop() {
+        if (!this.#running)
+            return this.#teardown();
+        this.#stopping = true;
+        this.#started = false;
+        this.setMicrophoneMuted(true);
+        // The server can take time to settle work; end local speech immediately.
+        this.discardPlayback();
+        try {
+            if (this.#socket.readyState === WebSocket.OPEN) {
+                this.#socket.send(JSON.stringify({ type: "stop", reason: "user_stopped" }));
+                let timer;
+                await Promise.race([
+                    this.#closed.promise,
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, 5000);
+                    }),
+                ]);
+                clearTimeout(timer);
+            }
+        }
+        finally {
+            await this.#teardown();
+        }
+    }
+    /** Submits locally after onStarted; throws if the session cannot accept the message. */
+    sendText(text) {
+        if (!this.#running || this.#stopping)
+            throw new Error("Voice session is closed");
+        if (!this.#started)
+            throw new Error("Typed input requires a started voice session; wait for onStarted");
+        if (this.#socket.readyState !== WebSocket.OPEN)
+            throw new Error("Voice socket is not open");
+        this.#socket.send(JSON.stringify({ type: "text", text: MessageInputTextSchema.parse(text) }));
+    }
+    setMicrophoneMuted(muted) {
+        // Disabled tracks still produce zero PCM; the capture worklet keeps the continuous input clock alive.
+        for (const track of this.#media.getAudioTracks())
+            track.enabled = !muted;
+    }
+    discardPlayback() {
+        this.#player.port.postMessage({ type: "discard" });
+    }
+    #handleControl(message, callbacks) {
+        switch (message.type) {
+            case "started":
+                if (this.#stopping)
+                    break;
+                // Media configuration is available even when the host hides journal events.
+                // Older bridges still configure playback through session.started below.
+                if (message.outputLifecycle === "continuous" || message.outputLifecycle === "response")
+                    this.#player.port.postMessage({
+                        type: "configure",
+                        ranges: message.outputLifecycle === "continuous",
+                    });
+                this.#started = true;
+                callbacks.onStarted(String(message.sessionId ?? ""));
+                break;
+            case "interrupt":
+                if (typeof message.streamId === "string" && message.streamId)
+                    this.#player.port.postMessage({ type: "interrupt", streamId: message.streamId });
+                break;
+            case "event":
+                {
+                    const event = (message.event ?? {});
+                    if (event.type === "session.started")
+                        this.#player.port.postMessage({
+                            type: "configure",
+                            ranges: event.capabilities?.outputLifecycle ===
+                                "continuous",
+                        });
+                    if (event.type === "audio.interrupted")
+                        this.#player.port.postMessage({ type: "interrupt", streamId: event.streamId });
+                    callbacks.onEvent(event);
+                }
+                break;
+            case "error":
+                callbacks.onError(String(message.message ?? "unknown error"));
+                break;
+            case "closed": {
+                const notify = this.#running;
+                void this.#teardown();
+                if (notify)
+                    callbacks.onClosed(String(message.reason ?? "closed"));
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    #handleAudioFrame(frame, callbacks) {
+        const view = new DataView(frame);
+        if (frame.byteLength < 4)
+            throw new Error("Invalid audio frame header");
+        const headerLength = view.getUint32(0, true);
+        if (frame.byteLength < 4 + headerLength)
+            throw new Error("Invalid audio frame header");
+        const header = JSON.parse(new TextDecoder().decode(new Uint8Array(frame, 4, headerLength)));
+        if (header?.sampleRate !== INPUT_SAMPLE_RATE || header.channels !== 1)
+            throw new Error("Browser playback requires 24 kHz mono PCM16");
+        if (typeof header.streamId !== "string" ||
+            !header.streamId ||
+            !Number.isSafeInteger(header.startSample) ||
+            header.startSample < 0 ||
+            (frame.byteLength - 4 - headerLength) % 2 !== 0)
+            throw new Error("Invalid PCM16 playback frame");
+        if (frame.byteLength === 4 + headerLength)
+            return;
+        const pcm = frame.slice(4 + headerLength);
+        callbacks.onStats({ receivedBytes: pcm.byteLength });
+        this.#player.port.postMessage({ type: "chunk", streamId: header.streamId, startSample: header.startSample, pcm }, [pcm]);
+    }
+    #teardown() {
+        if (this.#teardownPromise)
+            return this.#teardownPromise;
+        const settled = Promise.withResolvers();
+        // Cache before releasing resources: socket.close may synchronously notify a host adapter.
+        this.#teardownPromise = settled.promise;
+        this.#closed.resolve();
+        this.#running = false;
+        void this.#releaseResources().then(settled.resolve, settled.reject);
+        return settled.promise;
+    }
+    async #releaseResources() {
+        for (const track of this.#media.getTracks())
+            track.stop();
+        this.#player.port.postMessage({ type: "reset" });
+        if (this.#socket.readyState === WebSocket.OPEN || this.#socket.readyState === WebSocket.CONNECTING) {
+            this.#socket.close();
+        }
+        await this.#context.close().catch(() => undefined);
+    }
+}
+/** Browser permission requests cannot be revoked; release their resources if they resolve after abort. */
+function duringStartup(work, signal, releaseLate) {
+    if (!signal)
+        return work;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+        work.then((value) => {
+            signal.removeEventListener("abort", abort);
+            if (signal.aborted) {
+                releaseLate?.(value);
+                reject(signal.reason);
+            }
+            else
+                resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+    });
+}

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

@@ -0,0 +1,2 @@
+export type { VoiceStartRequest } from "../harness/index.js";
+export * from "./browser-voice-client.js";

package/dist/internal/browser/index.js

@@ -0,0 +1 @@
+export * from "./browser-voice-client.js";

package/dist/internal/harness/conversation-context.d.ts

@@ -0,0 +1,45 @@
+import type { Message, ProviderOutputSource } from "../protocol/index.js";
+import type { ConversationSnapshot, ConversationTextCompletion } from "./conversation-projection.js";
+export interface ConversationContextOptions {
+    /** Each selected text part becomes one context message. Zero selects no messages. */
+    maxMessages: number;
+    /** Combined UTF-8 text bytes, not tokens or encoded request size. */
+    maxTextBytes: number;
+    /**
+     * Live captions have no authoritative turn-final event, even after session end.
+     * Including unconfirmed text is a deliberate application choice; it may be partial.
+     */
+    unconfirmedText: "include" | "omit";
+    /** Include successful backend text/refusals; these are not evidence of spoken delivery. */
+    includeBackendText?: boolean;
+}
+export interface ConversationContextMessage {
+    role: Message["role"];
+    text: string;
+    messageId: string;
+    partId: string;
+    completion: ConversationTextCompletion;
+    source?: ProviderOutputSource;
+}
+export type ConversationContextOmissionReason = "non-text" | "empty" | "backend-excluded" | "unconfirmed" | "incomplete" | "cancelled" | "failed" | "interrupted" | "message-limit" | "text-byte-limit";
+export interface ConversationContextSelection {
+    sessionId: string;
+    throughSequence: number;
+    messages: ConversationContextMessage[];
+    omitted: {
+        messageId: string;
+        partId: string;
+        reason: ConversationContextOmissionReason;
+    }[];
+}
+/**
+ * Selects a newest suffix of eligible whole text parts, preserving projection order,
+ * roles and exact text. At the first budget boundary all older eligible text is
+ * omitted; an oversized recent request is never silently replaced with older ones.
+ *
+ * This detached selection seeds a new model session. It does not resume the provider,
+ * replay tools, summarize outcomes, or prove that assistant text was heard. Tools,
+ * reasoning and media are reported as omissions without copying their payloads.
+ * Provider input conversion and token limits remain the caller's responsibility.
+ */
+export declare function selectConversationContext(snapshot: ConversationSnapshot, options: ConversationContextOptions): ConversationContextSelection;

package/dist/internal/harness/conversation-context.js

@@ -0,0 +1,79 @@
+/**
+ * Selects a newest suffix of eligible whole text parts, preserving projection order,
+ * roles and exact text. At the first budget boundary all older eligible text is
+ * omitted; an oversized recent request is never silently replaced with older ones.
+ *
+ * This detached selection seeds a new model session. It does not resume the provider,
+ * replay tools, summarize outcomes, or prove that assistant text was heard. Tools,
+ * reasoning and media are reported as omissions without copying their payloads.
+ * Provider input conversion and token limits remain the caller's responsibility.
+ */
+export function selectConversationContext(snapshot, options) {
+    for (const [name, value] of [
+        ["maxMessages", options.maxMessages],
+        ["maxTextBytes", options.maxTextBytes],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new Error(`${name} must be a nonnegative safe integer`);
+    }
+    if (options.unconfirmedText !== "include" && options.unconfirmedText !== "omit")
+        throw new Error("unconfirmedText must be include or omit");
+    const messages = [];
+    const omitted = [];
+    const encoder = new TextEncoder();
+    let textBytes = 0;
+    let boundary;
+    for (let messageIndex = snapshot.messages.length - 1; messageIndex >= 0; messageIndex--) {
+        const message = snapshot.messages[messageIndex];
+        if (!message)
+            continue;
+        for (let partIndex = message.parts.length - 1; partIndex >= 0; partIndex--) {
+            const part = message.parts[partIndex];
+            if (!part)
+                continue;
+            const completion = snapshot.textCompletion[part.id] ?? "unconfirmed";
+            let reason;
+            if (part.type !== "text")
+                reason = "non-text";
+            else if (!part.text.trim())
+                reason = "empty";
+            else if (part.source?.scope === "backend" && !options.includeBackendText)
+                reason = "backend-excluded";
+            else if (message.role === "assistant" && part.playback === "interrupted")
+                reason = "interrupted";
+            else if (part.state === "incomplete" || part.state === "cancelled" || part.state === "failed")
+                reason = part.state;
+            else if (completion === "unconfirmed" &&
+                (options.unconfirmedText === "omit" || part.source?.scope === "backend"))
+                reason = "unconfirmed";
+            else if (boundary)
+                reason = boundary;
+            else if (messages.length >= options.maxMessages)
+                reason = boundary = "message-limit";
+            else {
+                const bytes = encoder.encode(part.text).byteLength;
+                if (bytes > options.maxTextBytes - textBytes)
+                    reason = boundary = "text-byte-limit";
+                else {
+                    messages.push({
+                        role: message.role,
+                        text: part.text,
+                        messageId: message.id,
+                        partId: part.id,
+                        completion,
+                        ...(part.source === undefined ? {} : { source: { ...part.source } }),
+                    });
+                    textBytes += bytes;
+                }
+            }
+            if (reason)
+                omitted.push({ messageId: message.id, partId: part.id, reason });
+        }
+    }
+    return {
+        sessionId: snapshot.sessionId,
+        throughSequence: snapshot.throughSequence,
+        messages: messages.reverse(),
+        omitted: omitted.reverse(),
+    };
+}

package/dist/internal/harness/conversation-projection.d.ts

@@ -0,0 +1,55 @@
+import { type HarnessRecord, type Message } from "../protocol/index.js";
+import { type ConversationTextCompletion } from "./message.js";
+export type { ConversationTextCompletion } from "./message.js";
+/** Bump when replay changes persisted membership or evidence. Version 4 retains response playback interruptions. */
+export declare const CONVERSATION_PROJECTION_VERSION = 4;
+export interface ConversationSnapshot {
+    sessionId: string;
+    throughSequence: number;
+    /** The source log contains session.ended; this does not finalize unfinished utterances. */
+    sealed: boolean;
+    messages: readonly Message[];
+    /** Complete current map keyed by text part ID. Timed display groups remain unconfirmed after sealing. */
+    textCompletion: Readonly<Record<string, ConversationTextCompletion>>;
+}
+export interface ConversationChange {
+    sessionId: string;
+    throughSequence: number;
+    sealed: boolean;
+    /** Complete current message order; timestamps may tie and IDs are not sortable. */
+    messageIds: readonly string[];
+    upsert: readonly Message[];
+    removeIds: readonly string[];
+    /** Complete replacement map, including when there are no changed messages. */
+    textCompletion: Readonly<Record<string, ConversationTextCompletion>>;
+}
+/**
+ * One session's persistent conversation view, reusing the batch message projector.
+ * Feed the complete contiguous log from session.started at sequence 1. This is not
+ * a checkpoint restore API: hosts replay source events to reconstruct its state.
+ *
+ * apply only captures detached metadata; changes/snapshot fold lazily. PCM content
+ * is never read or retained, and only the first output marker per legacy response
+ * stream is retained. Duplicate/conflict checks compare format, sample ranges and
+ * other metadata, not audio bytes; this is not a full event-log integrity verifier.
+ *
+ * Persist identities as (sessionId, message.id). Each emitted value is deeply
+ * detached, safe to queue or mutate without changing the projector or older results.
+ * Host transactions must commit message writes/removals and throughSequence together.
+ */
+export declare class ConversationProjector {
+    #private;
+    constructor(options: {
+        sessionId: string;
+    });
+    /** Returns false for a repeated metadata-identical event, even after the session is sealed. */
+    apply(event: HarnessRecord): boolean;
+    /** Observes the complete view without consuming pending changes. */
+    snapshot(): ConversationSnapshot;
+    /**
+     * Changes since the previous changes() call. Empty diffs still advance the source
+     * checkpoint. Queue batches in order; if persistence fails, retry the returned batch
+     * rather than calling changes() again to reconstruct it. snapshot() does not drain it.
+     */
+    changes(): ConversationChange;
+}

package/dist/internal/harness/conversation-projection.js

@@ -0,0 +1,145 @@
+import { HarnessRecordSchema, toHarnessRecord } from "../protocol/index.js";
+import { foldMessages } from "./message.js";
+/** Bump when replay changes persisted membership or evidence. Version 4 retains response playback interruptions. */
+export const CONVERSATION_PROJECTION_VERSION = 4;
+/**
+ * One session's persistent conversation view, reusing the batch message projector.
+ * Feed the complete contiguous log from session.started at sequence 1. This is not
+ * a checkpoint restore API: hosts replay source events to reconstruct its state.
+ *
+ * apply only captures detached metadata; changes/snapshot fold lazily. PCM content
+ * is never read or retained, and only the first output marker per legacy response
+ * stream is retained. Duplicate/conflict checks compare format, sample ranges and
+ * other metadata, not audio bytes; this is not a full event-log integrity verifier.
+ *
+ * Persist identities as (sessionId, message.id). Each emitted value is deeply
+ * detached, safe to queue or mutate without changing the projector or older results.
+ * Host transactions must commit message writes/removals and throughSequence together.
+ */
+export class ConversationProjector {
+    #sessionId;
+    #events = [];
+    #signatures = [];
+    #eventIds = new Set();
+    #audioStreams = new Set();
+    #continuousOutput = false;
+    #sealed = false;
+    #dirty = false;
+    #messages = [];
+    #textCompletion = {};
+    #previousMessages = new Map();
+    constructor(options) {
+        if (!options.sessionId)
+            throw new Error("Conversation projection requires a sessionId");
+        this.#sessionId = options.sessionId;
+    }
+    /** Returns false for a repeated metadata-identical event, even after the session is sealed. */
+    apply(event) {
+        if (event.sessionId !== this.#sessionId)
+            throw new Error("Conversation projection cannot mix sessions");
+        if (!Number.isSafeInteger(event.sequence) || event.sequence < 1)
+            throw new Error("Conversation event sequence must be a positive safe integer");
+        const metadata = structuredClone(HarnessRecordSchema.parse(toHarnessRecord(event, "metadata")));
+        const signature = fingerprint(metadata);
+        const existing = this.#signatures[event.sequence - 1];
+        if (existing !== undefined) {
+            if (existing !== signature)
+                throw new Error(`Conflicting event at sequence ${event.sequence}`);
+            return false;
+        }
+        if (event.sequence !== this.#signatures.length + 1)
+            throw new Error(`Expected sequence ${this.#signatures.length + 1}; received ${event.sequence}`);
+        if (this.#sealed)
+            throw new Error("Conversation projection is sealed");
+        if (this.#signatures.length === 0 && event.type !== "session.started")
+            throw new Error("Conversation projection must begin with session.started");
+        if (this.#signatures.length > 0 && event.type === "session.started")
+            throw new Error("Conversation projection already has a session.started event");
+        if (this.#eventIds.has(event.id))
+            throw new Error(`Event ID ${event.id} already belongs to another sequence`);
+        this.#signatures.push(signature);
+        this.#eventIds.add(event.id);
+        if (this.#retain(metadata)) {
+            this.#events.push(metadata);
+            this.#dirty = true;
+        }
+        return true;
+    }
+    /** Observes the complete view without consuming pending changes. */
+    snapshot() {
+        this.#reconcile();
+        return structuredClone({
+            sessionId: this.#sessionId,
+            throughSequence: this.#signatures.length,
+            sealed: this.#sealed,
+            messages: this.#messages,
+            textCompletion: this.#textCompletion,
+        });
+    }
+    /**
+     * Changes since the previous changes() call. Empty diffs still advance the source
+     * checkpoint. Queue batches in order; if persistence fails, retry the returned batch
+     * rather than calling changes() again to reconstruct it. snapshot() does not drain it.
+     */
+    changes() {
+        this.#reconcile();
+        const current = new Map();
+        const upsert = this.#messages.filter((message) => {
+            const signature = fingerprint(message);
+            current.set(message.id, signature);
+            return this.#previousMessages.get(message.id) !== signature;
+        });
+        const removeIds = [...this.#previousMessages.keys()].filter((id) => !current.has(id));
+        this.#previousMessages = current;
+        return structuredClone({
+            sessionId: this.#sessionId,
+            throughSequence: this.#signatures.length,
+            sealed: this.#sealed,
+            messageIds: this.#messages.map((message) => message.id),
+            upsert,
+            removeIds,
+            textCompletion: this.#textCompletion,
+        });
+    }
+    #retain(event) {
+        switch (event.type) {
+            case "session.started":
+                this.#continuousOutput = event.capabilities.outputLifecycle === "continuous";
+                return true;
+            case "session.ended":
+                this.#sealed = true;
+                return true;
+            case "audio.output":
+                if (this.#continuousOutput || this.#audioStreams.has(event.chunk.streamId))
+                    return false;
+                this.#audioStreams.add(event.chunk.streamId);
+                return true;
+            case "message.input":
+            case "audio.interrupted":
+            case "transcript":
+            case "transcript.delta":
+            case "transcript.fragment":
+            case "backend.output.delta":
+            case "backend.output":
+            case "backend.response":
+                return true;
+            default:
+                // The shared fold owns tool/task interpretation, including future lifecycle events.
+                return event.type.startsWith("tool.") || event.type.startsWith("task.");
+        }
+    }
+    #reconcile() {
+        if (!this.#dirty)
+            return;
+        const projection = foldMessages(this.#events);
+        this.#messages = projection.messages;
+        this.#textCompletion = projection.textCompletion;
+        this.#dirty = false;
+    }
+}
+/** Canonical object-key order makes replay insensitive to JSON property insertion order. */
+function fingerprint(value) {
+    return JSON.stringify(value, (_key, field) => field !== null && typeof field === "object" && !Array.isArray(field)
+        ? Object.fromEntries(Object.entries(field).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)))
+        : field);
+}

package/dist/internal/harness/event-stream.d.ts

@@ -1,7 +1,28 @@
-import { type HarnessEvent } from "../protocol/index.js";
+import type { HarnessEvent } from "../protocol/index.js";
+export declare class EventReplayUnavailableError extends Error {
+    readonly afterSequence: number;
+    readonly oldestAvailableSequence: number | undefined;
+    readonly latestSequence: number;
+    constructor(afterSequence: number, oldestAvailableSequence: number | undefined, latestSequence: number);
+}
+/** One shared replay buffer; iterators retain cursors, never private event queues. */
 export declare class ReplayEventStream {
     #private;
+    constructor(options?: {
+        maxEvents?: number | undefined;
+        maxAudioBytes?: number | undefined;
+    });
     publish(event: HarnessEvent): void;
-    subscribe(afterSequence?: number): AsyncIterable<HarnessEvent>;
+    /** At most one next() may be pending per iterator. Evicted cursors fail rather than skip events. */
+    subscribe(afterSequence?: number): AsyncIterableIterator<HarnessEvent>;
     close(): void;
+    /** Drain retained history, then reject reads with the failure instead of reporting a clean end. */
+    fail(error: unknown): void;
+    stats(): {
+        retainedEvents: number;
+        retainedAudioBytes: number;
+        oldestSequence: number | undefined;
+        latestSequence: number;
+        subscribers: number;
+    };
 }