xo-harness 0.1.0

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

@@ -0,0 +1,46 @@
+import { type AudioChunk, type OutputModality, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolDefinition, type ProviderToolResult, type ToolCall } from "../protocol/index.js";
+import type { CreateProviderSessionOptions, VoiceProvider, VoiceProviderSession } from "../provider/index.js";
+export * from "./replay-voice-provider.js";
+export * from "./scripted-voice-provider.js";
+export interface FakeVoiceProviderOptions {
+    autoReady?: boolean;
+    echoInput?: boolean;
+}
+export declare class FakeVoiceProvider implements VoiceProvider {
+    #private;
+    readonly id = "fake-duplex";
+    readonly capabilities: {
+        readonly continuousInputDuringOutput: true;
+        readonly modelManagedFloor: true;
+        readonly supportsToolCalls: true;
+        readonly supportsAsyncContext: true;
+        readonly supportsPlayoutAcknowledgements: true;
+    };
+    constructor(options?: FakeVoiceProviderOptions);
+    get session(): FakeVoiceProviderSession;
+    createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;
+}
+export declare class FakeVoiceProviderSession implements VoiceProviderSession {
+    #private;
+    readonly receivedAudio: AudioChunk[];
+    readonly receivedTexts: string[];
+    readonly playoutProgress: PlayoutProgress[];
+    readonly toolResults: ProviderToolResult[];
+    readonly contextEvents: ProviderContextEvent[];
+    readonly availableTools: readonly ProviderToolDefinition[];
+    readonly instructions: string | undefined;
+    readonly outputModalities: readonly OutputModality[] | undefined;
+    constructor(options: CreateProviderSessionOptions, fakeOptions: Required<FakeVoiceProviderOptions>);
+    get events(): AsyncIterable<ProviderEvent>;
+    get closed(): boolean;
+    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>;
+    emit(event: ProviderEvent): void;
+    emitAudio(chunk: AudioChunk): void;
+    emitTranscript(role: "user" | "assistant", text: string, streamId?: string): void;
+    requestTool(call: ToolCall): void;
+    close(reason?: string): Promise<void>;
+}

package/dist/internal/provider-fake/index.js

@@ -0,0 +1,112 @@
+import { AsyncQueue, AudioChunkSchema, PlayoutProgressSchema, ProviderContextEventSchema, ProviderEventSchema, ProviderToolResultSchema, } from "../protocol/index.js";
+export * from "./replay-voice-provider.js";
+export * from "./scripted-voice-provider.js";
+export class FakeVoiceProvider {
+    id = "fake-duplex";
+    capabilities = {
+        continuousInputDuringOutput: true,
+        modelManagedFloor: true,
+        supportsToolCalls: true,
+        supportsAsyncContext: true,
+        supportsPlayoutAcknowledgements: true,
+    };
+    #options;
+    #session;
+    constructor(options = {}) {
+        this.#options = {
+            autoReady: options.autoReady ?? true,
+            echoInput: options.echoInput ?? false,
+        };
+    }
+    get session() {
+        if (!this.#session)
+            throw new Error("Fake provider session has not been created");
+        return this.#session;
+    }
+    async createSession(options) {
+        if (this.#session && !this.#session.closed) {
+            throw new Error("FakeVoiceProvider supports one active session per instance");
+        }
+        this.#session = new FakeVoiceProviderSession(options, this.#options);
+        return this.#session;
+    }
+}
+export class FakeVoiceProviderSession {
+    receivedAudio = [];
+    receivedTexts = [];
+    playoutProgress = [];
+    toolResults = [];
+    contextEvents = [];
+    availableTools;
+    instructions;
+    outputModalities;
+    #queue = new AsyncQueue();
+    #options;
+    #outputSequence = 0;
+    #closed = false;
+    constructor(options, fakeOptions) {
+        this.#options = fakeOptions;
+        this.availableTools = options.tools;
+        this.instructions = options.instructions;
+        this.outputModalities = options.outputModalities;
+        options.signal.addEventListener("abort", () => {
+            void this.close(String(options.signal.reason ?? "aborted"));
+        }, { once: true });
+        if (this.#options.autoReady)
+            queueMicrotask(() => this.emit({ type: "ready" }));
+    }
+    get events() {
+        return this.#queue;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    async sendAudio(chunk) {
+        const validated = AudioChunkSchema.parse(chunk);
+        this.receivedAudio.push(validated);
+        if (this.#options.echoInput) {
+            this.emit({
+                type: "audio.output",
+                chunk: {
+                    ...validated,
+                    streamId: "fake-output",
+                    sequence: this.#outputSequence++,
+                },
+            });
+        }
+    }
+    async sendText(text) {
+        this.receivedTexts.push(text);
+        if (this.#options.echoInput) {
+            this.emitTranscript("assistant", text);
+        }
+    }
+    async reportPlayout(progress) {
+        this.playoutProgress.push(PlayoutProgressSchema.parse(progress));
+    }
+    async sendToolResult(result) {
+        this.toolResults.push(ProviderToolResultSchema.parse(result));
+    }
+    async sendContext(event) {
+        this.contextEvents.push(ProviderContextEventSchema.parse(event));
+    }
+    emit(event) {
+        this.#queue.push(ProviderEventSchema.parse(event));
+    }
+    emitAudio(chunk) {
+        this.emit({ type: "audio.output", chunk: AudioChunkSchema.parse(chunk) });
+    }
+    emitTranscript(role, text, streamId) {
+        this.emit({ type: "transcript", role, text, ...(streamId === undefined ? {} : { streamId }) });
+    }
+    requestTool(call) {
+        this.emit({ type: "tool.call", call });
+    }
+    async close(reason = "fake_closed") {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#queue.push({ type: "closed", reason });
+        this.#queue.close();
+    }
+}

package/dist/internal/provider-fake/replay-voice-provider.d.ts

@@ -0,0 +1,47 @@
+import { type AudioChunk, type HarnessEvent, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolResult } from "../protocol/index.js";
+import type { CreateProviderSessionOptions, VoiceProvider, VoiceProviderSession } from "../provider/index.js";
+export interface ReplayVoiceProviderOptions {
+    /** Recorded harness events to replay. Takes precedence over load. */
+    events?: readonly HarnessEvent[];
+    /** Loads the recorded events when a session starts. */
+    load?: () => Promise<readonly HarnessEvent[]>;
+    /** realtime honors recorded sessionTimeMs spacing; instant replays without waiting. */
+    pacing?: "realtime" | "instant";
+}
+/**
+ * Replays the provider-visible half of a recorded session: model audio, tool requests,
+ * and provider errors, in recorded order and (optionally) recorded pacing. Input audio,
+ * playout acknowledgements, tool results, and context are accepted and captured but do
+ * not influence playback. This is the shadow-test primitive: re-drive UIs, tools, and
+ * stores from an authoritative log without a live model or an API key.
+ */
+export declare class ReplayVoiceProvider implements VoiceProvider {
+    #private;
+    readonly id = "replay";
+    readonly capabilities: {
+        readonly continuousInputDuringOutput: true;
+        readonly modelManagedFloor: true;
+        readonly supportsToolCalls: true;
+        readonly supportsAsyncContext: true;
+        readonly supportsPlayoutAcknowledgements: true;
+    };
+    constructor(options: ReplayVoiceProviderOptions);
+    createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;
+}
+export declare class ReplayVoiceProviderSession implements VoiceProviderSession {
+    #private;
+    readonly receivedAudio: AudioChunk[];
+    readonly receivedTexts: string[];
+    readonly playoutProgress: PlayoutProgress[];
+    readonly toolResults: ProviderToolResult[];
+    readonly contextEvents: ProviderContextEvent[];
+    constructor(events: readonly HarnessEvent[], pacing: "realtime" | "instant", options: CreateProviderSessionOptions);
+    get events(): AsyncIterable<ProviderEvent>;
+    get closed(): boolean;
+    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>;
+}

package/dist/internal/provider-fake/replay-voice-provider.js

@@ -0,0 +1,133 @@
+import { AsyncQueue, AudioChunkSchema, PlayoutProgressSchema, ProviderContextEventSchema, ProviderToolResultSchema, } from "../protocol/index.js";
+/**
+ * Replays the provider-visible half of a recorded session: model audio, tool requests,
+ * and provider errors, in recorded order and (optionally) recorded pacing. Input audio,
+ * playout acknowledgements, tool results, and context are accepted and captured but do
+ * not influence playback. This is the shadow-test primitive: re-drive UIs, tools, and
+ * stores from an authoritative log without a live model or an API key.
+ */
+export class ReplayVoiceProvider {
+    id = "replay";
+    capabilities = {
+        continuousInputDuringOutput: true,
+        modelManagedFloor: true,
+        supportsToolCalls: true,
+        supportsAsyncContext: true,
+        supportsPlayoutAcknowledgements: true,
+    };
+    #options;
+    constructor(options) {
+        if (!options.events && !options.load) {
+            throw new Error("ReplayVoiceProvider needs recorded events or a load callback");
+        }
+        this.#options = options;
+    }
+    async createSession(options) {
+        const events = this.#options.events ?? (await this.#options.load?.()) ?? [];
+        return new ReplayVoiceProviderSession(events, this.#options.pacing ?? "realtime", options);
+    }
+}
+export class ReplayVoiceProviderSession {
+    receivedAudio = [];
+    receivedTexts = [];
+    playoutProgress = [];
+    toolResults = [];
+    contextEvents = [];
+    #queue = new AsyncQueue();
+    #closed = false;
+    #cancelDelay;
+    constructor(events, pacing, options) {
+        options.signal.addEventListener("abort", () => {
+            void this.close(String(options.signal.reason ?? "aborted"));
+        }, { once: true });
+        void this.#run(events, pacing);
+    }
+    get events() {
+        return this.#queue;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    async sendAudio(chunk) {
+        this.receivedAudio.push(AudioChunkSchema.parse(chunk));
+    }
+    async sendText(text) {
+        this.receivedTexts.push(text);
+    }
+    async reportPlayout(progress) {
+        this.playoutProgress.push(PlayoutProgressSchema.parse(progress));
+    }
+    async sendToolResult(result) {
+        this.toolResults.push(ProviderToolResultSchema.parse(result));
+    }
+    async sendContext(event) {
+        this.contextEvents.push(ProviderContextEventSchema.parse(event));
+    }
+    async close(reason = "replay_closed") {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#cancelDelay?.();
+        this.#queue.push({ type: "closed", reason });
+        this.#queue.close();
+    }
+    async #run(events, pacing) {
+        this.#emit({ type: "ready" });
+        const replayable = events.filter(isReplayable);
+        const startTimeMs = replayable[0]?.sessionTimeMs ?? 0;
+        let elapsedMs = 0;
+        for (const event of replayable) {
+            if (pacing === "realtime") {
+                const waitMs = event.sessionTimeMs - startTimeMs - elapsedMs;
+                if (waitMs > 0) {
+                    await this.#delay(waitMs);
+                    elapsedMs += waitMs;
+                }
+            }
+            if (this.#closed)
+                return;
+            this.#emit(toProviderEvent(event));
+        }
+        await this.close("replay_complete");
+    }
+    #emit(event) {
+        if (!this.#closed)
+            this.#queue.push(event);
+    }
+    #delay(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#cancelDelay = undefined;
+                resolve();
+            }, ms);
+            this.#cancelDelay = () => {
+                clearTimeout(timer);
+                this.#cancelDelay = undefined;
+                resolve();
+            };
+        });
+    }
+}
+function isReplayable(event) {
+    return (event.type === "audio.output" ||
+        event.type === "transcript" ||
+        event.type === "tool.requested" ||
+        event.type === "provider.error");
+}
+function toProviderEvent(event) {
+    switch (event.type) {
+        case "audio.output":
+            return { type: "audio.output", chunk: event.chunk };
+        case "transcript":
+            return {
+                type: "transcript",
+                role: event.role,
+                text: event.text,
+                ...(event.streamId === undefined ? {} : { streamId: event.streamId }),
+            };
+        case "tool.requested":
+            return { type: "tool.call", call: event.call };
+        case "provider.error":
+            return { type: "error", message: event.message, recoverable: event.recoverable };
+    }
+}

package/dist/internal/provider-fake/scripted-voice-provider.d.ts

@@ -0,0 +1,61 @@
+import { type AudioChunk, type OutputModality, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolDefinition, type ProviderToolResult } from "../protocol/index.js";
+import type { CreateProviderSessionOptions, VoiceProvider, VoiceProviderSession } from "../provider/index.js";
+export type ScriptedVoiceStep = {
+    type: "emit";
+    event: ProviderEvent;
+} | {
+    type: "expect.audio";
+    value: AudioChunk;
+} | {
+    type: "expect.text";
+    value: string;
+} | {
+    type: "expect.playout";
+    value: PlayoutProgress;
+} | {
+    type: "expect.tool_result";
+    value: ProviderToolResult;
+} | {
+    type: "expect.context";
+    value: ProviderContextEvent;
+};
+export interface ScriptedVoiceProviderOptions {
+    steps: readonly ScriptedVoiceStep[];
+    /** Fails a script that is waiting for harness traffic. Defaults to two seconds. */
+    stepTimeoutMs?: number;
+}
+/**
+ * A closed-loop deterministic provider. Unlike recorded replay, scripts can stop after
+ * emitting a tool call and verify the exact result before the next model event appears.
+ */
+export declare class ScriptedVoiceProvider implements VoiceProvider {
+    #private;
+    readonly id = "scripted";
+    readonly capabilities: {
+        readonly continuousInputDuringOutput: true;
+        readonly modelManagedFloor: true;
+        readonly supportsToolCalls: true;
+        readonly supportsAsyncContext: true;
+        readonly supportsPlayoutAcknowledgements: true;
+    };
+    constructor(options: ScriptedVoiceProviderOptions);
+    get session(): ScriptedVoiceProviderSession;
+    createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;
+    completed(): Promise<void>;
+}
+export declare class ScriptedVoiceProviderSession implements VoiceProviderSession {
+    #private;
+    readonly availableTools: readonly ProviderToolDefinition[];
+    readonly instructions: string | undefined;
+    readonly outputModalities: readonly OutputModality[] | undefined;
+    constructor(options: CreateProviderSessionOptions, script: Required<ScriptedVoiceProviderOptions>);
+    get events(): AsyncIterable<ProviderEvent>;
+    get closed(): boolean;
+    completed(): Promise<void>;
+    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>;
+}

package/dist/internal/provider-fake/scripted-voice-provider.js

@@ -0,0 +1,185 @@
+import { AsyncQueue, AudioChunkSchema, PlayoutProgressSchema, ProviderContextEventSchema, ProviderEventSchema, ProviderToolResultSchema, } from "../protocol/index.js";
+/**
+ * A closed-loop deterministic provider. Unlike recorded replay, scripts can stop after
+ * emitting a tool call and verify the exact result before the next model event appears.
+ */
+export class ScriptedVoiceProvider {
+    id = "scripted";
+    capabilities = {
+        continuousInputDuringOutput: true,
+        modelManagedFloor: true,
+        supportsToolCalls: true,
+        supportsAsyncContext: true,
+        supportsPlayoutAcknowledgements: true,
+    };
+    #options;
+    #session;
+    constructor(options) {
+        this.#options = {
+            steps: options.steps,
+            stepTimeoutMs: options.stepTimeoutMs ?? 2_000,
+        };
+    }
+    get session() {
+        if (!this.#session)
+            throw new Error("Scripted provider session has not been created");
+        return this.#session;
+    }
+    async createSession(options) {
+        if (this.#session && !this.#session.closed) {
+            throw new Error("ScriptedVoiceProvider supports one active session per instance");
+        }
+        this.#session = new ScriptedVoiceProviderSession(options, this.#options);
+        return this.#session;
+    }
+    completed() {
+        return this.session.completed();
+    }
+}
+export class ScriptedVoiceProviderSession {
+    availableTools;
+    instructions;
+    outputModalities;
+    #queue = new AsyncQueue();
+    #steps;
+    #stepTimeoutMs;
+    #completion;
+    #resolveCompletion = () => undefined;
+    #rejectCompletion = () => undefined;
+    #stepIndex = 0;
+    #stepTimer;
+    #closed = false;
+    constructor(options, script) {
+        this.availableTools = options.tools;
+        this.instructions = options.instructions;
+        this.outputModalities = options.outputModalities;
+        this.#steps = script.steps;
+        this.#stepTimeoutMs = script.stepTimeoutMs;
+        this.#completion = new Promise((resolve, reject) => {
+            this.#resolveCompletion = resolve;
+            this.#rejectCompletion = reject;
+        });
+        // A caller may choose to observe completion only through the harness event log.
+        void this.#completion.catch(() => undefined);
+        options.signal.addEventListener("abort", () => {
+            void this.close(String(options.signal.reason ?? "aborted"));
+        }, { once: true });
+        queueMicrotask(() => {
+            this.#queue.push({ type: "ready" });
+            this.#advance();
+        });
+    }
+    get events() {
+        return this.#queue;
+    }
+    get closed() {
+        return this.#closed;
+    }
+    completed() {
+        return this.#completion;
+    }
+    async sendAudio(chunk) {
+        this.#accept("expect.audio", AudioChunkSchema.parse(chunk));
+    }
+    async sendText(text) {
+        this.#accept("expect.text", text);
+    }
+    async reportPlayout(progress) {
+        this.#accept("expect.playout", PlayoutProgressSchema.parse(progress));
+    }
+    async sendToolResult(result) {
+        this.#accept("expect.tool_result", ProviderToolResultSchema.parse(result));
+    }
+    async sendContext(event) {
+        this.#accept("expect.context", ProviderContextEventSchema.parse(event));
+    }
+    async close(reason = "scripted_closed") {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#clearStepTimer();
+        if (this.#stepIndex < this.#steps.length) {
+            this.#rejectCompletion(new Error(`Script closed at step ${this.#stepIndex + 1}/${this.#steps.length}: ${reason}`));
+        }
+        this.#queue.close();
+    }
+    #accept(type, value) {
+        if (this.#closed)
+            throw new Error("Scripted provider is closed");
+        const step = this.#steps[this.#stepIndex];
+        if (!step || step.type !== type) {
+            const expected = step?.type ?? "end of script";
+            const error = new Error(`Script step ${this.#stepIndex + 1} expected ${expected}, received ${type}: ${formatValue(value)}`);
+            this.#fail(error);
+            throw error;
+        }
+        if (!deepEqual(value, step.value)) {
+            const error = new Error(`Script step ${this.#stepIndex + 1} failed: expected ${formatValue(step.value)}, received ${formatValue(value)}`);
+            this.#fail(error);
+            throw error;
+        }
+        this.#clearStepTimer();
+        this.#stepIndex += 1;
+        this.#advance();
+    }
+    #advance() {
+        while (!this.#closed) {
+            const step = this.#steps[this.#stepIndex];
+            if (!step) {
+                this.#closed = true;
+                this.#resolveCompletion();
+                this.#queue.push({ type: "closed", reason: "script_complete" });
+                this.#queue.close();
+                return;
+            }
+            if (step.type !== "emit") {
+                this.#armStepTimer(step.type);
+                return;
+            }
+            this.#queue.push(ProviderEventSchema.parse(step.event));
+            this.#stepIndex += 1;
+        }
+    }
+    #armStepTimer(type) {
+        this.#clearStepTimer();
+        this.#stepTimer = setTimeout(() => {
+            this.#fail(new Error(`Script stalled at step ${this.#stepIndex + 1}/${this.#steps.length}, waiting for ${type}`));
+        }, this.#stepTimeoutMs);
+    }
+    #clearStepTimer() {
+        if (this.#stepTimer)
+            clearTimeout(this.#stepTimer);
+        this.#stepTimer = undefined;
+    }
+    #fail(error) {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#clearStepTimer();
+        this.#rejectCompletion(error);
+        this.#queue.push({ type: "error", message: error.message, recoverable: false });
+        this.#queue.close();
+    }
+}
+function deepEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (left instanceof Uint8Array && right instanceof Uint8Array) {
+        return left.byteLength === right.byteLength && left.every((value, index) => value === right[index]);
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        return left.length === right.length && left.every((value, index) => deepEqual(value, right[index]));
+    }
+    if (isRecord(left) && isRecord(right)) {
+        const leftKeys = Object.keys(left).sort();
+        const rightKeys = Object.keys(right).sort();
+        return deepEqual(leftKeys, rightKeys) && leftKeys.every((key) => deepEqual(left[key], right[key]));
+    }
+    return false;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function formatValue(value) {
+    return JSON.stringify(value, (_key, candidate) => candidate instanceof Uint8Array ? [...candidate] : candidate);
+}

package/dist/internal/storage/append-tail.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Serializes per-session append work onto one promise tail. `run` reserves the caller's
+ * position synchronously — before its first await — so appends enqueued back to back
+ * settle in call order even while earlier work is still awaiting. Rejected work rejects
+ * its caller but never poisons the tail.
+ */
+export declare class SessionAppendTails {
+    #private;
+    run<T>(sessionId: string, work: () => Promise<T>): Promise<T>;
+    /** Resolves once every append enqueued for the session so far has settled. */
+    settled(sessionId: string): Promise<void>;
+}

package/dist/internal/storage/append-tail.js

@@ -0,0 +1,19 @@
+/**
+ * Serializes per-session append work onto one promise tail. `run` reserves the caller's
+ * position synchronously — before its first await — so appends enqueued back to back
+ * settle in call order even while earlier work is still awaiting. Rejected work rejects
+ * its caller but never poisons the tail.
+ */
+export class SessionAppendTails {
+    #tails = new Map();
+    run(sessionId, work) {
+        const previousTail = this.#tails.get(sessionId) ?? Promise.resolve();
+        const result = previousTail.then(work);
+        this.#tails.set(sessionId, result.then(() => undefined, () => undefined));
+        return result;
+    }
+    /** Resolves once every append enqueued for the session so far has settled. */
+    settled(sessionId) {
+        return this.#tails.get(sessionId) ?? Promise.resolve();
+    }
+}

package/dist/internal/storage/event-store.d.ts

@@ -0,0 +1,19 @@
+import type { HarnessEvent, UnsequencedHarnessEvent } from "../protocol/index.js";
+export interface EventStore {
+    /**
+     * Durably appends one event to the session log.
+     *
+     * Implementations must reserve the event's position in the session's serialized append
+     * tail synchronously (before their first await) and settle appends in that order —
+     * SessionAppendTails is the canonical way to honor this. The harness pipelines media
+     * records against this guarantee: it forwards audio while the append is still settling,
+     * relying on enqueue order to keep the log causal.
+     */
+    append(event: UnsequencedHarnessEvent): Promise<HarnessEvent>;
+    /**
+     * Durability barrier for every append enqueued for the session before this call.
+     * Implementations must reserve the barrier in the same serialized tail as append.
+     */
+    flush(sessionId: string): Promise<void>;
+    list(sessionId: string): Promise<readonly HarnessEvent[]>;
+}

package/dist/internal/storage/event-store.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+export * from "./append-tail.js";
+export * from "./event-store.js";
+export * from "./jsonl-event-store.js";
+export * from "./memory-event-store.js";

package/dist/internal/storage/index.js

@@ -0,0 +1,4 @@
+export * from "./append-tail.js";
+export * from "./event-store.js";
+export * from "./jsonl-event-store.js";
+export * from "./memory-event-store.js";

package/dist/internal/storage/jsonl-event-store.d.ts

@@ -0,0 +1,13 @@
+import { type HarnessEvent, type UnsequencedHarnessEvent } from "../protocol/index.js";
+import type { EventStore } from "./event-store.js";
+/**
+ * Local JSONL persistence for one harness process. Cross-process writer fencing and
+ * directory fsync for newly published session files are deferred to the resume slice.
+ */
+export declare class JsonlEventStore implements EventStore {
+    #private;
+    constructor(rootDirectory: string);
+    append(event: UnsequencedHarnessEvent): Promise<HarnessEvent>;
+    flush(sessionId: string): Promise<void>;
+    list(sessionId: string): Promise<readonly HarnessEvent[]>;
+}