xo-harness 0.2.0 → 0.3.0

package/dist/internal/harness/event-stream.js

@@ -1,42 +1,172 @@
-import { AsyncQueue } from "../protocol/index.js";
+export class EventReplayUnavailableError extends Error {
+    afterSequence;
+    oldestAvailableSequence;
+    latestSequence;
+    constructor(afterSequence, oldestAvailableSequence, latestSequence) {
+        super(`Event replay after sequence ${afterSequence} is unavailable; retained history starts at ${oldestAvailableSequence ?? "no event"} (latest sequence ${latestSequence})`);
+        this.afterSequence = afterSequence;
+        this.oldestAvailableSequence = oldestAvailableSequence;
+        this.latestSequence = latestSequence;
+        this.name = "EventReplayUnavailableError";
+    }
+}
+const done = () => ({ done: true, value: undefined });
+/** One shared replay buffer; iterators retain cursors, never private event queues. */
 export class ReplayEventStream {
     #history = [];
     #subscribers = new Set();
+    #maxEvents;
+    #maxAudioBytes;
+    #head = 0;
+    #offset = 0;
+    #audioBytes = 0;
+    #lastEvictedSequence = 0;
+    #latestSequence = 0;
     #closed = false;
+    #failure;
+    constructor(options = {}) {
+        for (const [name, value] of Object.entries(options)) {
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+                throw new Error(`${name} must be a nonnegative safe integer`);
+        }
+        this.#maxEvents = options.maxEvents ?? Number.POSITIVE_INFINITY;
+        this.#maxAudioBytes = options.maxAudioBytes ?? Number.POSITIVE_INFINITY;
+    }
     publish(event) {
         if (this.#closed)
             throw new Error("Cannot publish after the event stream is closed");
+        if (event.sequence <= this.#latestSequence)
+            throw new Error("Event stream sequences must increase");
+        this.#latestSequence = event.sequence;
         this.#history.push(event);
-        for (const subscriber of this.#subscribers)
-            subscriber.push(event);
+        this.#audioBytes += audioBytes(event);
+        // Already waiting readers can receive an event even when replay retention is zero.
+        for (const cursor of this.#subscribers)
+            this.#flush(cursor);
+        while (this.#history.length - this.#head > this.#maxEvents || this.#audioBytes > this.#maxAudioBytes) {
+            const oldest = this.#history[this.#head];
+            if (!oldest)
+                break;
+            this.#audioBytes -= audioBytes(oldest);
+            this.#lastEvictedSequence = oldest.sequence;
+            this.#history[this.#head++] = undefined;
+        }
+        if (this.#head >= 1024 && this.#head * 2 >= this.#history.length) {
+            this.#history = this.#history.slice(this.#head);
+            this.#offset += this.#head;
+            this.#head = 0;
+        }
     }
+    /** At most one next() may be pending per iterator. Evicted cursors fail rather than skip events. */
     subscribe(afterSequence = 0) {
-        const queue = new AsyncQueue();
-        const backlog = this.#history.filter((event) => event.sequence > afterSequence);
-        for (const event of backlog)
-            queue.push(event);
-        if (this.#closed)
-            queue.close();
-        else
-            this.#subscribers.add(queue);
-        const subscribers = this.#subscribers;
+        if (!Number.isSafeInteger(afterSequence) || afterSequence < 0)
+            throw new Error("afterSequence must be a nonnegative safe integer");
+        let low = this.#head;
+        let high = this.#history.length;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            const event = this.#history[middle];
+            if (event && event.sequence <= afterSequence)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        const cursor = { afterSequence, position: this.#offset + low, done: false };
+        if (!this.#closed)
+            this.#subscribers.add(cursor);
         return {
-            async *[Symbol.asyncIterator]() {
+            next: () => {
+                if (cursor.pending)
+                    return Promise.reject(new Error("Only one next() may be pending"));
                 try {
-                    yield* queue;
+                    const result = this.#take(cursor);
+                    if (result)
+                        return Promise.resolve(result);
+                    cursor.pending = Promise.withResolvers();
+                    return cursor.pending.promise;
                 }
-                finally {
-                    subscribers.delete(queue);
+                catch (error) {
+                    this.#release(cursor);
+                    return Promise.reject(error);
                 }
             },
+            return: () => {
+                this.#release(cursor);
+                return Promise.resolve(done());
+            },
+            [Symbol.asyncIterator]() {
+                return this;
+            },
         };
     }
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
-        for (const subscriber of this.#subscribers)
-            subscriber.close();
+        for (const cursor of this.#subscribers)
+            this.#flush(cursor);
         this.#subscribers.clear();
     }
+    /** Drain retained history, then reject reads with the failure instead of reporting a clean end. */
+    fail(error) {
+        if (this.#closed)
+            return;
+        this.#failure = { error };
+        this.close();
+    }
+    stats() {
+        return {
+            retainedEvents: this.#history.length - this.#head,
+            retainedAudioBytes: this.#audioBytes,
+            oldestSequence: this.#history[this.#head]?.sequence,
+            latestSequence: this.#latestSequence,
+            subscribers: this.#subscribers.size,
+        };
+    }
+    #take(cursor) {
+        if (cursor.done)
+            return done();
+        if (cursor.afterSequence < this.#lastEvictedSequence)
+            throw new EventReplayUnavailableError(cursor.afterSequence, this.#history[this.#head]?.sequence, this.#latestSequence);
+        cursor.position = Math.max(cursor.position, this.#offset + this.#head);
+        while (cursor.position < this.#offset + this.#history.length) {
+            const event = this.#history[cursor.position++ - this.#offset];
+            if (event && event.sequence > cursor.afterSequence) {
+                cursor.afterSequence = event.sequence;
+                return { done: false, value: event };
+            }
+        }
+        if (!this.#closed)
+            return undefined;
+        if (this.#failure)
+            throw this.#failure.error;
+        this.#release(cursor);
+        return done();
+    }
+    #flush(cursor) {
+        if (!cursor.pending)
+            return;
+        const pending = cursor.pending;
+        try {
+            const result = this.#take(cursor);
+            if (!result)
+                return;
+            cursor.pending = undefined;
+            pending.resolve(result);
+        }
+        catch (error) {
+            cursor.pending = undefined;
+            this.#release(cursor);
+            pending.reject(error);
+        }
+    }
+    #release(cursor) {
+        cursor.done = true;
+        this.#subscribers.delete(cursor);
+        cursor.pending?.resolve(done());
+        cursor.pending = undefined;
+    }
+}
+function audioBytes(event) {
+    return event.type === "audio.input" || event.type === "audio.output" ? event.chunk.data.byteLength : 0;
 }

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

@@ -1,10 +1,16 @@
-export * from "./message.js";
+export * from "./conversation-context.js";
+export * from "./conversation-projection.js";
+export { EventReplayUnavailableError } from "./event-stream.js";
+export { projectMessages } from "./message.js";
 export * from "./report.js";
 export * from "./report-diff.js";
+export { SessionPersistenceError, type SessionRuntimeLimits } from "./runtime-limits.js";
 export * from "./shadow.js";
 export * from "./socket-bridge.js";
+export * from "./tool-calls.js";
 export * from "./tool-delivery.js";
 export * from "./tool-policy.js";
 export * from "./tools.js";
+export * from "./usage-tracker.js";
 export * from "./voice-session.js";
 export * from "./xo.js";

package/dist/internal/harness/index.js

@@ -1,10 +1,16 @@
-export * from "./message.js";
+export * from "./conversation-context.js";
+export * from "./conversation-projection.js";
+export { EventReplayUnavailableError } from "./event-stream.js";
+export { projectMessages } from "./message.js";
 export * from "./report.js";
 export * from "./report-diff.js";
+export { SessionPersistenceError } from "./runtime-limits.js";
 export * from "./shadow.js";
 export * from "./socket-bridge.js";
+export * from "./tool-calls.js";
 export * from "./tool-delivery.js";
 export * from "./tool-policy.js";
 export * from "./tools.js";
+export * from "./usage-tracker.js";
 export * from "./voice-session.js";
 export * from "./xo.js";

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

@@ -1,10 +1,9 @@
-import type { HarnessEvent, Message } from "../protocol/index.js";
+import { type HarnessRecord, type Message } from "../protocol/index.js";
+/** Text evidence, independent of display state, session sealing, and device playback. */
+export type ConversationTextCompletion = "input" | "provider-final" | "unconfirmed";
 /**
- * Projects the flat, sequence-ordered event log into the v2 `Message[]` part model —
- * the shape every agent harness renders and persists (opencode / Vercel AI SDK v5 /
- * agent-server / echo). Pure AND deterministic over the recorded events: ids derive
- * from the opening event, so the same log always projects to the same identities —
- * re-folds diff cleanly, upserts stay idempotent, and renderers can key on part ids.
+ * Projects the sequence-ordered source log into display messages. Identities derive
+ * from opening events, so replay produces the same message and part IDs.
  *
  * Folding rules:
  *  - `message.input` → a user message; its recorded `parts` project with full fidelity
@@ -12,14 +11,28 @@ import type { HarnessEvent, Message } from "../protocol/index.js";
  *  - `transcript.delta` from either speaker → a `streaming` text part accumulating deltas,
  *    finalized in place by the matching `transcript` (streamId-correlated, so a
  *    barge-in interrupted stream still finalizes into its original part).
- *  - `audio.output` → an `audio` part on the current assistant message (deduped per
- *    streamId), linked to its transcript text part by that streamId.
+ *  - Response audio and its transcript share a stream's message owner, including
+ *    when the first caption arrives after another speaker's input.
+ *  - Confirmed interruption separates the next new assistant speech stream; late
+ *    updates still belong to their original stream. Timed fragments keep their
+ *    independent, revisable display grouping. Interrupted response streams retain
+ *    their generated text with playback evidence; a final caption does not erase it.
+ *  - `backend.output.*` → backend item-owned text/refusal/summary parts, separate
+ *    from speech. Final items replace their content; failed responses settle only
+ *    unfinished parts. Backend completion is never evidence of spoken delivery.
  *  - `tool.requested` → ONE `tool` part in `running` state; `tool.completed`/`tool.failed`
  *    settle it with the canonical outcome, and a task terminal upgrades an
  *    `accepted_task` outcome to the task's real result. This is why a tool result
  *    (e.g. a crisis card) replays from history: the outcome lives on the part.
  *
- * A tool part belongs to the assistant message open when it was requested; a new
- * assistant transcript or user turn opens the next message.
+ * A tool part retains an existing native item owner when one is known. Otherwise,
+ * continuous-output tools own a separate assistant message, independent of revisable
+ * captions; response-based tools belong to the assistant message open at invocation.
+ * Display messages are not provider turns or evidence of device playback.
  */
-export declare function projectMessages(events: readonly HarnessEvent[]): Message[];
+export declare function projectMessages(events: readonly HarnessRecord[]): Message[];
+/** Internal shared fold: persistence and batch rendering use the same text evidence. */
+export declare function foldMessages(events: readonly HarnessRecord[]): {
+    messages: Message[];
+    textCompletion: Record<string, ConversationTextCompletion>;
+};