xo-harness 0.1.0 → 0.1.2

package/README.md

@@ -17,6 +17,9 @@ const harness = new XO({ store: new JsonlEventStore(".xo/sessions") });
 const session = await harness.startSession({
   provider: new OpenAIRealtimeVoiceProvider({ apiKey: process.env.OPENAI_API_KEY! }),
 });
+
+// The model can open from its existing instructions/context; no fake user turn is added.
+await session.requestAssistantTurn({ instructions: "Welcome the caller in one sentence." });
 ```
 
 Additional entry points are available for focused imports:

package/dist/internal/harness/task-supervisor.js

@@ -149,8 +149,14 @@ export class TaskSupervisor {
         const key = taskKey(event.taskId, event.callId);
         if (this.#terminalTasks.has(key))
             return false;
-        await this.#record(event);
         this.#terminalTasks.add(key);
+        try {
+            await this.#record(event);
+        }
+        catch (error) {
+            this.#terminalTasks.delete(key);
+            throw error;
+        }
         await this.#flush();
         if (deliverContext)
             await this.#deliverContext(event, "terminal");

package/dist/internal/harness/tool-runtime.js

@@ -54,15 +54,27 @@ export class ToolRuntime {
     }
     async #settleCompleted(callId, outcome) {
         this.#assertNotTerminal(callId);
-        await this.#record({ type: "tool.completed", callId, outcome });
         this.#terminal.add(callId);
+        try {
+            await this.#record({ type: "tool.completed", callId, outcome });
+        }
+        catch (error) {
+            this.#terminal.delete(callId);
+            throw error;
+        }
         await this.#flush();
         await this.#deliver(callId, outcome);
     }
     async #settleFailure(callId, message) {
         this.#assertNotTerminal(callId);
-        await this.#record({ type: "tool.failed", callId, error: message });
         this.#terminal.add(callId);
+        try {
+            await this.#record({ type: "tool.failed", callId, error: message });
+        }
+        catch (error) {
+            this.#terminal.delete(callId);
+            throw error;
+        }
         await this.#flush();
         await this.#deliver(callId, { type: "failed", error: message });
     }

package/dist/internal/harness/voice-session.d.ts

@@ -1,10 +1,12 @@
-import { type AgentInput, type AudioChunk, type HarnessEvent, type OutputModality, type PlayoutProgress } from "../protocol/index.js";
+import { type AgentInput, type AssistantTurnRequest, type AudioChunk, type HarnessEvent, type OutputModality, type PlayoutProgress } from "../protocol/index.js";
 import type { VoiceProvider } from "../provider/index.js";
 import type { EventStore } from "../storage/index.js";
 import type { ToolRegistry } from "./tools.js";
 export interface CreateVoiceSessionOptions {
     sessionId: string;
     provider: VoiceProvider;
+    /** Cancels provider startup and closes the live session when its owner is revoked. */
+    signal?: AbortSignal;
     store: EventStore;
     tools: ToolRegistry;
     instructions?: string;
@@ -28,6 +30,17 @@ export declare class VoiceSession {
      * the collapsed text is what goes over the wire (media-native providers wire later).
      */
     sendText(input: AgentInput): Promise<void>;
+    /**
+     * Resolves only after the provider has acknowledged its session configuration.
+     * Hosts can apply their own timeout policy around this promise.
+     */
+    waitUntilReady(): Promise<void>;
+    /**
+     * Begins an assistant turn from existing provider context. The request waits for
+     * provider.ready, is recorded without its potentially private guidance, and never
+     * creates a synthetic user message in the session log.
+     */
+    requestAssistantTurn(request?: AssistantTurnRequest): Promise<void>;
     reportPlayout(progress: PlayoutProgress): Promise<void>;
     close(reason?: string): Promise<void>;
 }

package/dist/internal/harness/voice-session.js

@@ -1,4 +1,4 @@
-import { AgentInputSchema, AudioChunkSchema, agentInputToText, MessageInputTextSchema, PlayoutProgressSchema, ProviderEventSchema, } from "../protocol/index.js";
+import { AgentInputSchema, AssistantTurnRequestSchema, AudioChunkSchema, agentInputToText, MessageInputTextSchema, PlayoutProgressSchema, ProviderEventSchema, } from "../protocol/index.js";
 import { ReplayEventStream } from "./event-stream.js";
 import { TaskSupervisor } from "./task-supervisor.js";
 import { ToolRuntime } from "./tool-runtime.js";
@@ -13,6 +13,10 @@ export class VoiceSession {
     #pendingRecords = new Set();
     #tasks;
     #toolRuntime;
+    #providerReadiness;
+    #settleProviderReadiness = () => undefined;
+    #providerReadinessSettled = false;
+    #detachOwnerAbort;
     #providerPump;
     #closePromise;
     #maxDurationTimer;
@@ -22,13 +26,16 @@ export class VoiceSession {
         this.#store = options.store;
         this.#startedAt = startedAt;
         this.#events.publish(startedEvent);
+        this.#providerReadiness = new Promise((resolve) => {
+            this.#settleProviderReadiness = resolve;
+        });
         this.#tasks = new TaskSupervisor({
             record: (event) => this.#record(event),
             sendContext: (event) => this.#providerSession.sendContext(event),
             flush: () => this.#store.flush(this.id),
             sessionSignal: this.#controller.signal,
             onError: () => {
-                void this.close("storage_error");
+                this.#closeFromInternal("storage_error");
             },
         });
         this.#toolRuntime = new ToolRuntime({
@@ -43,6 +50,10 @@ export class VoiceSession {
         });
     }
     static async create(options) {
+        const existingEvents = await options.store.list(options.sessionId);
+        if (existingEvents.length > 0) {
+            throw new Error(`Session id already exists: ${options.sessionId}`);
+        }
         const startedAt = performance.now();
         const startedEvent = await options.store.append(createUnsequencedEvent(options.sessionId, startedAt, {
             type: "session.started",
@@ -55,7 +66,15 @@ export class VoiceSession {
                 : { outputModalities: [...options.outputModalities] }),
         }));
         await options.store.flush(options.sessionId);
+        if (options.signal?.aborted) {
+            await recordFailedCreation(options.store, options.sessionId, startedAt, "owner_revoked");
+            throw options.signal.reason ?? new Error("Session owner revoked before startup");
+        }
         const providerController = new AbortController();
+        const abortProviderFromOwner = () => providerController.abort(options.signal?.reason ?? "owner_revoked");
+        if (options.signal?.aborted)
+            abortProviderFromOwner();
+        options.signal?.addEventListener("abort", abortProviderFromOwner, { once: true });
         let providerSession;
         try {
             providerSession = await options.provider.createSession({
@@ -67,18 +86,33 @@ export class VoiceSession {
             });
         }
         catch (error) {
+            options.signal?.removeEventListener("abort", abortProviderFromOwner);
             providerController.abort(error);
-            await recordFailedCreation(options.store, options.sessionId, startedAt);
+            await recordFailedCreation(options.store, options.sessionId, startedAt, options.signal?.aborted ? "owner_revoked" : "provider_create_failed");
             throw error;
         }
+        if (options.signal?.aborted) {
+            options.signal.removeEventListener("abort", abortProviderFromOwner);
+            await providerSession.close("owner_revoked").catch(() => undefined);
+            await recordFailedCreation(options.store, options.sessionId, startedAt, "owner_revoked");
+            throw options.signal.reason ?? new Error("Session owner revoked during startup");
+        }
         const session = new VoiceSession(options, providerSession, startedAt, startedEvent);
         session.#controller.signal.addEventListener("abort", () => providerController.abort(session.#controller.signal.reason), {
             once: true,
         });
+        options.signal?.removeEventListener("abort", abortProviderFromOwner);
+        if (options.signal) {
+            const abortSessionFromOwner = () => {
+                session.#closeFromInternal("owner_revoked");
+            };
+            options.signal.addEventListener("abort", abortSessionFromOwner, { once: true });
+            session.#detachOwnerAbort = () => options.signal?.removeEventListener("abort", abortSessionFromOwner);
+        }
         session.#providerPump = session.#pumpProviderEvents();
         if (options.maxDurationMs !== undefined) {
             session.#maxDurationTimer = setTimeout(() => {
-                void session.close("max_duration_reached");
+                session.#closeFromInternal("max_duration_reached");
             }, options.maxDurationMs);
         }
         return session;
@@ -121,6 +155,28 @@ export class VoiceSession {
         });
         await this.#providerSession.sendText(text);
     }
+    /**
+     * Resolves only after the provider has acknowledged its session configuration.
+     * Hosts can apply their own timeout policy around this promise.
+     */
+    async waitUntilReady() {
+        this.#assertOpen();
+        if (!(await this.#providerReadiness)) {
+            throw new Error("Voice provider closed before it became ready");
+        }
+        this.#assertOpen();
+    }
+    /**
+     * Begins an assistant turn from existing provider context. The request waits for
+     * provider.ready, is recorded without its potentially private guidance, and never
+     * creates a synthetic user message in the session log.
+     */
+    async requestAssistantTurn(request = {}) {
+        const validated = AssistantTurnRequestSchema.parse(request);
+        await this.waitUntilReady();
+        await this.#record({ type: "assistant.turn.requested" });
+        await this.#providerSession.requestAssistantTurn(validated);
+    }
     async reportPlayout(progress) {
         this.#assertOpen();
         const validated = PlayoutProgressSchema.parse(progress);
@@ -131,7 +187,12 @@ export class VoiceSession {
         this.#closePromise ??= this.#performClose(reason);
         return this.#closePromise;
     }
+    #closeFromInternal(reason) {
+        void this.close(reason).catch(() => undefined);
+    }
     async #performClose(reason) {
+        this.#detachOwnerAbort?.();
+        this.#detachOwnerAbort = undefined;
         if (this.#maxDurationTimer)
             clearTimeout(this.#maxDurationTimer);
         this.#controller.abort(reason);
@@ -159,6 +220,7 @@ export class VoiceSession {
                 switch (event.type) {
                     case "ready":
                         await this.#record({ type: "provider.ready" });
+                        this.#settleReadiness(true);
                         break;
                     case "audio.output":
                         // Pipelined: the append is enqueued (log position reserved) without stalling
@@ -197,12 +259,15 @@ export class VoiceSession {
                             message: event.message,
                             recoverable: event.recoverable,
                         });
-                        if (!event.recoverable)
-                            void this.close("provider_error");
+                        if (!event.recoverable) {
+                            this.#settleReadiness(false);
+                            this.#closeFromInternal("provider_error");
+                        }
                         break;
                     case "closed":
+                        this.#settleReadiness(false);
                         await this.#record({ type: "provider.closed", reason: event.reason });
-                        void this.close("provider_closed");
+                        this.#closeFromInternal("provider_closed");
                         break;
                 }
             }
@@ -216,19 +281,28 @@ export class VoiceSession {
                 });
             }
         }
+        finally {
+            this.#settleReadiness(false);
+        }
+    }
+    #settleReadiness(ready) {
+        if (this.#providerReadinessSettled)
+            return;
+        this.#providerReadinessSettled = true;
+        this.#settleProviderReadiness(ready);
     }
     #trackToolExecution(execution) {
         this.#toolExecutions.add(execution);
         void execution.then(() => this.#toolExecutions.delete(execution), () => {
             this.#toolExecutions.delete(execution);
-            void this.close("storage_error");
+            this.#closeFromInternal("storage_error");
         });
     }
     #trackRecord(record) {
         this.#pendingRecords.add(record);
         void record.then(() => this.#pendingRecords.delete(record), () => {
             this.#pendingRecords.delete(record);
-            void this.close("storage_error");
+            this.#closeFromInternal("storage_error");
         });
     }
     async #record(event) {
@@ -251,11 +325,11 @@ function createUnsequencedEvent(sessionId, startedAt, event) {
         sessionTimeMs: performance.now() - startedAt,
     };
 }
-async function recordFailedCreation(store, sessionId, startedAt) {
+async function recordFailedCreation(store, sessionId, startedAt, reason) {
     try {
         await store.append(createUnsequencedEvent(sessionId, startedAt, {
             type: "session.ended",
-            reason: "provider_create_failed",
+            reason,
         }));
         await store.flush(sessionId);
     }

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

@@ -9,6 +9,8 @@ export interface XOOptions {
 }
 export interface StartSessionOptions {
     provider: VoiceProvider;
+    /** Cancels provider startup and closes the live session when its owner is revoked. */
+    signal?: AbortSignal;
     sessionId?: string;
     instructions?: string;
     /** What the model may produce this session; ["text"] disables audio output. Default: audio. */

package/dist/internal/harness/xo.js

@@ -14,6 +14,7 @@ export class XO {
         return VoiceSession.create({
             sessionId: options.sessionId ?? crypto.randomUUID(),
             provider: options.provider,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
             store: this.store,
             tools: this.tools,
             ...(options.instructions === undefined ? {} : { instructions: options.instructions }),

package/dist/internal/protocol/events.d.ts

@@ -49,6 +49,15 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     correlationId: z.ZodOptional<z.ZodString>;
     causationId: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"provider.ready">;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    sequence: z.ZodInt;
+    recordedAtMs: z.ZodNumber;
+    sessionTimeMs: z.ZodNumber;
+    correlationId: z.ZodOptional<z.ZodString>;
+    causationId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"assistant.turn.requested">;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     sessionId: z.ZodString;

package/dist/internal/protocol/events.js

@@ -34,6 +34,8 @@ export const HarnessEventSchema = z.discriminatedUnion("type", [
     EventBaseSchema.extend({ type: z.literal("session.ended"), reason: z.string().min(1) }),
     /** The provider accepted the session configuration; media may now flow. */
     EventBaseSchema.extend({ type: z.literal("provider.ready") }),
+    /** A host asked the ready provider to begin an assistant turn without fabricating user input. */
+    EventBaseSchema.extend({ type: z.literal("assistant.turn.requested") }),
     /** The provider connection settled; the harness closes the session in response. */
     EventBaseSchema.extend({ type: z.literal("provider.closed"), reason: z.string().min(1) }),
     /** Provider-reported fault; recoverable errors leave the session running. */

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

@@ -22,6 +22,14 @@ export declare const OutputModalitySchema: z.ZodEnum<{
     text: "text";
 }>;
 export type OutputModality = z.infer<typeof OutputModalitySchema>;
+/**
+ * A host-initiated assistant turn. This is deliberately not a synthetic user
+ * message: the model responds from the existing conversation and session context.
+ */
+export declare const AssistantTurnRequestSchema: z.ZodObject<{
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AssistantTurnRequest = z.infer<typeof AssistantTurnRequestSchema>;
 /**
  * Token accounting for one completed model response, as reported by the provider.
  * cachedInputTokens is the slice of input served from the provider's prompt cache —

package/dist/internal/protocol/provider.js

@@ -22,6 +22,14 @@ export const PlayoutProgressSchema = z.object({
 });
 /** What the model may produce; ["text"] runs a session without audio output. */
 export const OutputModalitySchema = z.enum(["audio", "text"]);
+/**
+ * A host-initiated assistant turn. This is deliberately not a synthetic user
+ * message: the model responds from the existing conversation and session context.
+ */
+export const AssistantTurnRequestSchema = z.object({
+    /** Per-response guidance; it overrides session instructions for this turn only. */
+    instructions: z.string().min(1).max(4_000).optional(),
+});
 /**
  * Token accounting for one completed model response, as reported by the provider.
  * cachedInputTokens is the slice of input served from the provider's prompt cache —

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

@@ -1,4 +1,4 @@
-import type { AudioChunk, OutputModality, PlayoutProgress, ProviderCapabilities, ProviderContextEvent, ProviderEvent, ProviderToolDefinition, ProviderToolResult } from "../protocol/index.js";
+import type { AssistantTurnRequest, AudioChunk, OutputModality, PlayoutProgress, ProviderCapabilities, ProviderContextEvent, ProviderEvent, ProviderToolDefinition, ProviderToolResult } from "../protocol/index.js";
 export interface CreateProviderSessionOptions {
     sessionId: string;
     signal: AbortSignal;
@@ -12,6 +12,8 @@ export interface VoiceProviderSession {
     sendAudio(chunk: AudioChunk): Promise<void>;
     /** Injects a typed user message into the conversation; the model responds as usual. */
     sendText(text: string): Promise<void>;
+    /** Starts a model turn from existing context without adding a fake user message. */
+    requestAssistantTurn(request?: AssistantTurnRequest): Promise<void>;
     reportPlayout(progress: PlayoutProgress): Promise<void>;
     sendToolResult(result: ProviderToolResult): Promise<void>;
     sendContext(event: ProviderContextEvent): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { type AudioChunk, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolDefinition, type ProviderToolResult } from "../protocol/index.js";
+import { type AssistantTurnRequest, type AudioChunk, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolDefinition, type ProviderToolResult } from "../protocol/index.js";
 import type { CreateProviderSessionOptions, VoiceProviderSession } from "./contract.js";
 import type { RealtimeSocket } from "./realtime-socket.js";
 /**
@@ -22,6 +22,7 @@ export declare class RealtimeVoiceSession implements VoiceProviderSession {
     get events(): AsyncIterable<ProviderEvent>;
     sendAudio(chunk: AudioChunk): Promise<void>;
     sendText(text: string): Promise<void>;
+    requestAssistantTurn(request?: AssistantTurnRequest): Promise<void>;
     reportPlayout(progress: PlayoutProgress): Promise<void>;
     sendToolResult(result: ProviderToolResult): Promise<void>;
     sendContext(event: ProviderContextEvent): Promise<void>;

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

@@ -1,8 +1,10 @@
 import { Buffer } from "node:buffer";
-import { AsyncQueue, AudioChunkSchema, audioSampleCount, PlayoutProgressSchema, ProviderContextEventSchema, ProviderToolResultSchema, ToolCallSchema, } from "../protocol/index.js";
+import { AssistantTurnRequestSchema, 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 INPUT_TRANSCRIPT_SETTLE_MS = 300;
+const EMITTED_USER_TRANSCRIPT_CACHE_LIMIT = 128;
 const ServerEnvelopeSchema = z.looseObject({ type: z.string().min(1) });
 const OutputAudioDeltaSchema = z.looseObject({
     item_id: z.string().min(1).optional(),
@@ -83,12 +85,15 @@ export class RealtimeVoiceSession {
     #outputStreams = new Map();
     #playedThrough = new Map();
     #deliveredToolCalls = new Set();
+    #pendingUserTranscripts = new Map();
+    #emittedUserTranscripts = new Map();
     #settled;
     #resolveSettled;
     #outputSampleRate;
     #activeOutputItemId;
     #responseActive = false;
     #responseWanted = false;
+    #wantedResponseInstructions;
     #ready = false;
     #closed = false;
     #closeReason;
@@ -127,6 +132,10 @@ export class RealtimeVoiceSession {
         });
         this.#requestResponse();
     }
+    async requestAssistantTurn(request = {}) {
+        const validated = AssistantTurnRequestSchema.parse(request);
+        this.#requestResponse(validated.instructions);
+    }
     async reportPlayout(progress) {
         const validated = PlayoutProgressSchema.parse(progress);
         this.#playedThrough.set(validated.streamId, validated.playedThroughSample);
@@ -269,8 +278,44 @@ export class RealtimeVoiceSession {
         const transcript = TranscriptEventSchema.safeParse(parsed);
         if (!transcript.success)
             return;
+        if (role === "user" && transcript.data.item_id !== undefined) {
+            this.#queueUserTranscript(transcript.data.item_id, transcript.data.transcript);
+            return;
+        }
         this.#emitTranscript(role, transcript.data.transcript, transcript.data.item_id);
     }
+    /** xAI can send several "completed" revisions for one input item; emit only the settled text. */
+    #queueUserTranscript(streamId, rawText) {
+        const text = rawText.trim();
+        if (text === "")
+            return;
+        const pending = this.#pendingUserTranscripts.get(streamId);
+        if (pending)
+            clearTimeout(pending.timer);
+        const timer = setTimeout(() => this.#flushUserTranscript(streamId), INPUT_TRANSCRIPT_SETTLE_MS);
+        this.#pendingUserTranscripts.set(streamId, { text, timer });
+    }
+    #flushUserTranscript(streamId) {
+        const pending = this.#pendingUserTranscripts.get(streamId);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.#pendingUserTranscripts.delete(streamId);
+        if (this.#emittedUserTranscripts.get(streamId) === pending.text)
+            return;
+        this.#emittedUserTranscripts.delete(streamId);
+        this.#emittedUserTranscripts.set(streamId, pending.text);
+        if (this.#emittedUserTranscripts.size > EMITTED_USER_TRANSCRIPT_CACHE_LIMIT) {
+            const oldestStreamId = this.#emittedUserTranscripts.keys().next().value;
+            if (oldestStreamId !== undefined)
+                this.#emittedUserTranscripts.delete(oldestStreamId);
+        }
+        this.#emitTranscript("user", pending.text, streamId);
+    }
+    #flushUserTranscripts() {
+        for (const streamId of [...this.#pendingUserTranscripts.keys()])
+            this.#flushUserTranscript(streamId);
+    }
     #handleTranscriptDelta(parsed) {
         const delta = TranscriptDeltaWireSchema.safeParse(parsed);
         if (!delta.success || delta.data.delta === "")
@@ -319,8 +364,11 @@ export class RealtimeVoiceSession {
                 this.#emitFunctionCall(call.data.call_id, call.data.name, call.data.arguments);
             }
         }
-        if (this.#responseWanted)
-            this.#requestResponse();
+        if (this.#responseWanted) {
+            const instructions = this.#wantedResponseInstructions;
+            this.#wantedResponseInstructions = undefined;
+            this.#requestResponse(instructions);
+        }
     }
     #emitUsage(usage) {
         const input = usage.input_token_details;
@@ -379,14 +427,19 @@ export class RealtimeVoiceSession {
         const message = error.success ? error.data.error?.message : undefined;
         this.#emitError(message ?? `${this.#wire.label} reported an error`, true);
     }
-    #requestResponse() {
+    #requestResponse(instructions) {
         if (this.#responseActive) {
             this.#responseWanted = true;
+            if (instructions !== undefined)
+                this.#wantedResponseInstructions = instructions;
             return;
         }
         this.#responseWanted = false;
         this.#responseActive = true;
-        this.#trySend({ type: "response.create" });
+        this.#trySend({
+            type: "response.create",
+            ...(instructions === undefined ? {} : { response: { instructions } }),
+        });
     }
     #send(payload) {
         if (this.#socket.state !== "open") {
@@ -411,6 +464,7 @@ export class RealtimeVoiceSession {
     #settle(reason) {
         if (this.#closed)
             return;
+        this.#flushUserTranscripts();
         this.#closed = true;
         this.#queue.push({ type: "closed", reason });
         this.#queue.close();

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

@@ -1,4 +1,4 @@
-import { type AudioChunk, type OutputModality, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolDefinition, type ProviderToolResult, type ToolCall } from "../protocol/index.js";
+import { type AssistantTurnRequest, 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";
@@ -24,6 +24,7 @@ export declare class FakeVoiceProviderSession implements VoiceProviderSession {
     #private;
     readonly receivedAudio: AudioChunk[];
     readonly receivedTexts: string[];
+    readonly assistantTurnRequests: AssistantTurnRequest[];
     readonly playoutProgress: PlayoutProgress[];
     readonly toolResults: ProviderToolResult[];
     readonly contextEvents: ProviderContextEvent[];
@@ -35,6 +36,7 @@ export declare class FakeVoiceProviderSession implements VoiceProviderSession {
     get closed(): boolean;
     sendAudio(chunk: AudioChunk): Promise<void>;
     sendText(text: string): Promise<void>;
+    requestAssistantTurn(request?: AssistantTurnRequest): Promise<void>;
     reportPlayout(progress: PlayoutProgress): Promise<void>;
     sendToolResult(result: ProviderToolResult): Promise<void>;
     sendContext(event: ProviderContextEvent): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { AsyncQueue, AudioChunkSchema, PlayoutProgressSchema, ProviderContextEventSchema, ProviderEventSchema, ProviderToolResultSchema, } from "../protocol/index.js";
+import { AssistantTurnRequestSchema, 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 {
@@ -34,6 +34,7 @@ export class FakeVoiceProvider {
 export class FakeVoiceProviderSession {
     receivedAudio = [];
     receivedTexts = [];
+    assistantTurnRequests = [];
     playoutProgress = [];
     toolResults = [];
     contextEvents = [];
@@ -81,6 +82,9 @@ export class FakeVoiceProviderSession {
             this.emitTranscript("assistant", text);
         }
     }
+    async requestAssistantTurn(request = {}) {
+        this.assistantTurnRequests.push(AssistantTurnRequestSchema.parse(request));
+    }
     async reportPlayout(progress) {
         this.playoutProgress.push(PlayoutProgressSchema.parse(progress));
     }

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

@@ -1,4 +1,4 @@
-import { type AudioChunk, type HarnessEvent, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolResult } from "../protocol/index.js";
+import { type AssistantTurnRequest, 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. */
@@ -32,6 +32,7 @@ export declare class ReplayVoiceProviderSession implements VoiceProviderSession
     #private;
     readonly receivedAudio: AudioChunk[];
     readonly receivedTexts: string[];
+    readonly assistantTurnRequests: AssistantTurnRequest[];
     readonly playoutProgress: PlayoutProgress[];
     readonly toolResults: ProviderToolResult[];
     readonly contextEvents: ProviderContextEvent[];
@@ -40,6 +41,7 @@ export declare class ReplayVoiceProviderSession implements VoiceProviderSession
     get closed(): boolean;
     sendAudio(chunk: AudioChunk): Promise<void>;
     sendText(text: string): Promise<void>;
+    requestAssistantTurn(request?: AssistantTurnRequest): Promise<void>;
     reportPlayout(progress: PlayoutProgress): Promise<void>;
     sendToolResult(result: ProviderToolResult): Promise<void>;
     sendContext(event: ProviderContextEvent): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { AsyncQueue, AudioChunkSchema, PlayoutProgressSchema, ProviderContextEventSchema, ProviderToolResultSchema, } from "../protocol/index.js";
+import { AssistantTurnRequestSchema, 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,
@@ -30,6 +30,7 @@ export class ReplayVoiceProvider {
 export class ReplayVoiceProviderSession {
     receivedAudio = [];
     receivedTexts = [];
+    assistantTurnRequests = [];
     playoutProgress = [];
     toolResults = [];
     contextEvents = [];
@@ -54,6 +55,9 @@ export class ReplayVoiceProviderSession {
     async sendText(text) {
         this.receivedTexts.push(text);
     }
+    async requestAssistantTurn(request = {}) {
+        this.assistantTurnRequests.push(AssistantTurnRequestSchema.parse(request));
+    }
     async reportPlayout(progress) {
         this.playoutProgress.push(PlayoutProgressSchema.parse(progress));
     }

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

@@ -1,4 +1,4 @@
-import { type AudioChunk, type OutputModality, type PlayoutProgress, type ProviderContextEvent, type ProviderEvent, type ProviderToolDefinition, type ProviderToolResult } from "../protocol/index.js";
+import { type AssistantTurnRequest, 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";
@@ -9,6 +9,9 @@ export type ScriptedVoiceStep = {
 } | {
     type: "expect.text";
     value: string;
+} | {
+    type: "expect.assistant_turn";
+    value: AssistantTurnRequest;
 } | {
     type: "expect.playout";
     value: PlayoutProgress;
@@ -54,6 +57,7 @@ export declare class ScriptedVoiceProviderSession implements VoiceProviderSessio
     completed(): Promise<void>;
     sendAudio(chunk: AudioChunk): Promise<void>;
     sendText(text: string): Promise<void>;
+    requestAssistantTurn(request?: AssistantTurnRequest): Promise<void>;
     reportPlayout(progress: PlayoutProgress): Promise<void>;
     sendToolResult(result: ProviderToolResult): Promise<void>;
     sendContext(event: ProviderContextEvent): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { AsyncQueue, AudioChunkSchema, PlayoutProgressSchema, ProviderContextEventSchema, ProviderEventSchema, ProviderToolResultSchema, } from "../protocol/index.js";
+import { AssistantTurnRequestSchema, 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.
@@ -84,6 +84,9 @@ export class ScriptedVoiceProviderSession {
     async sendText(text) {
         this.#accept("expect.text", text);
     }
+    async requestAssistantTurn(request = {}) {
+        this.#accept("expect.assistant_turn", AssistantTurnRequestSchema.parse(request));
+    }
     async reportPlayout(progress) {
         this.#accept("expect.playout", PlayoutProgressSchema.parse(progress));
     }

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

@@ -28,7 +28,7 @@ export class JsonlEventStore {
         this.#assertSessionId(sessionId);
         return this.#tails.run(sessionId, async () => {
             try {
-                const file = await open(this.#sessionPath(sessionId), "r");
+                const file = await open(this.#sessionPath(sessionId), "r+");
                 try {
                     await file.sync();
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xo-harness",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A TypeScript-first agent harness for continuous, fully duplex voice models.",
   "type": "module",
   "sideEffects": [