xo-harness 0.2.0 → 0.3.0

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

@@ -1,9 +1,61 @@
 import { z } from "zod";
 /** Bounds for a typed user message, shared by the event, the session API, and wire schemas. */
 export declare const MessageInputTextSchema: z.ZodString;
+export declare const InputAudioEventSchema: 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<"audio.input">;
+    chunk: z.ZodObject<{
+        streamId: z.ZodString;
+        sequence: z.ZodInt;
+        encoding: z.ZodLiteral<"pcm_s16le">;
+        sampleRate: z.ZodInt;
+        channels: z.ZodInt;
+        startSample: z.ZodInt;
+        data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    }, z.core.$strict>;
+    syntheticSilence: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const OutputAudioEventSchema: 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<"audio.output">;
+    chunk: z.ZodObject<{
+        streamId: z.ZodString;
+        sequence: z.ZodInt;
+        encoding: z.ZodLiteral<"pcm_s16le">;
+        sampleRate: z.ZodInt;
+        channels: z.ZodInt;
+        startSample: z.ZodInt;
+        data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    }, z.core.$strict>;
+    source: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<{
+            backend: "backend";
+            voice: "voice";
+        }>;
+        responseId: z.ZodOptional<z.ZodString>;
+        itemId: z.ZodOptional<z.ZodString>;
+        outputIndex: z.ZodOptional<z.ZodInt>;
+        contentIndex: z.ZodOptional<z.ZodInt>;
+        summaryIndex: z.ZodOptional<z.ZodInt>;
+        delegationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
- * The authoritative session log: every observable fact of a conversation, in one flat,
- * durably ordered stream. There is deliberately no turn or message hierarchy here —
+ * Sequenced live facts of a conversation, in one flat, store-ordered stream. Retained
+ * HarnessRecord values preserve this envelope and may explicitly omit audio bytes.
+ * There is deliberately no turn or message hierarchy here —
  * duplex audio overlaps — conversation views are projections over this log.
  * The full catalog with ordering rules lives in docs/protocol.md.
  */
@@ -23,8 +75,25 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         modelManagedFloor: z.ZodBoolean;
         supportsToolCalls: z.ZodBoolean;
         supportsAsyncContext: z.ZodBoolean;
+        supportsToolStatusContext: z.ZodOptional<z.ZodBoolean>;
         supportsPlayoutAcknowledgements: z.ZodBoolean;
         reportsResponseState: z.ZodOptional<z.ZodBoolean>;
+        inputCadence: z.ZodOptional<z.ZodEnum<{
+            continuous: "continuous";
+            "on-demand": "on-demand";
+        }>>;
+        outputLifecycle: z.ZodOptional<z.ZodEnum<{
+            continuous: "continuous";
+            response: "response";
+        }>>;
+        supportsAssistantTurn: z.ZodOptional<z.ZodBoolean>;
+        supportsTextOutput: z.ZodOptional<z.ZodBoolean>;
+        textInput: z.ZodOptional<z.ZodEnum<{
+            backend: "backend";
+            conversation: "conversation";
+            unsupported: "unsupported";
+        }>>;
+        maxContextUpdateBytes: z.ZodOptional<z.ZodInt>;
     }, z.core.$strip>;
     instructions: z.ZodOptional<z.ZodString>;
     outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
@@ -118,6 +187,7 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     causationId: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"provider.closed">;
     reason: z.ZodString;
+    finalized: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     sessionId: z.ZodString;
@@ -152,6 +222,26 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         url: z.ZodString;
         filename: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "type">>>;
+}, 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<"input.delivery">;
+    inputId: z.ZodString;
+    providerId: z.ZodString;
+    target: z.ZodEnum<{
+        backend: "backend";
+        conversation: "conversation";
+    }>;
+    phase: z.ZodEnum<{
+        failed: "failed";
+        submitted: "submitted";
+    }>;
+    error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     sessionId: z.ZodString;
@@ -169,7 +259,8 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         channels: z.ZodInt;
         startSample: z.ZodInt;
         data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
+    syntheticSilence: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     sessionId: z.ZodString;
@@ -187,7 +278,19 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         channels: z.ZodInt;
         startSample: z.ZodInt;
         data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
-    }, z.core.$strip>;
+    }, z.core.$strict>;
+    source: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<{
+            backend: "backend";
+            voice: "voice";
+        }>;
+        responseId: z.ZodOptional<z.ZodString>;
+        itemId: z.ZodOptional<z.ZodString>;
+        outputIndex: z.ZodOptional<z.ZodInt>;
+        contentIndex: z.ZodOptional<z.ZodInt>;
+        summaryIndex: z.ZodOptional<z.ZodInt>;
+        delegationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     sessionId: z.ZodString;
@@ -205,6 +308,18 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     text: z.ZodString;
     streamId: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<{
+            backend: "backend";
+            voice: "voice";
+        }>;
+        responseId: z.ZodOptional<z.ZodString>;
+        itemId: z.ZodOptional<z.ZodString>;
+        outputIndex: z.ZodOptional<z.ZodInt>;
+        contentIndex: z.ZodOptional<z.ZodInt>;
+        summaryIndex: z.ZodOptional<z.ZodInt>;
+        delegationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     id: z.ZodString;
     sessionId: z.ZodString;
     sequence: z.ZodInt;
@@ -220,6 +335,18 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>;
     delta: z.ZodString;
     streamId: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<{
+            backend: "backend";
+            voice: "voice";
+        }>;
+        responseId: z.ZodOptional<z.ZodString>;
+        itemId: z.ZodOptional<z.ZodString>;
+        outputIndex: z.ZodOptional<z.ZodInt>;
+        contentIndex: z.ZodOptional<z.ZodInt>;
+        summaryIndex: z.ZodOptional<z.ZodInt>;
+        delegationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     id: z.ZodString;
     sessionId: z.ZodString;
     sequence: z.ZodInt;
@@ -229,6 +356,193 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     causationId: z.ZodOptional<z.ZodString>;
     type: z.ZodLiteral<"transcript.delta">;
 }, z.core.$strip>, z.ZodObject<{
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    text: z.ZodString;
+    fragmentId: z.ZodString;
+    startMs: z.ZodNumber;
+    endMs: z.ZodNumber;
+    timebase: z.ZodLiteral<"provider-session">;
+    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<"transcript.fragment">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodEnum<{
+        reasoning_summary: "reasoning_summary";
+        refusal: "refusal";
+        text: "text";
+    }>;
+    source: z.ZodObject<{
+        delegationId: z.ZodOptional<z.ZodString>;
+        scope: z.ZodLiteral<"backend">;
+        responseId: z.ZodString;
+        itemId: z.ZodString;
+        outputIndex: z.ZodInt;
+        contentIndex: z.ZodOptional<z.ZodInt>;
+        summaryIndex: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strip>;
+    delta: z.ZodString;
+    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<"backend.output.delta">;
+}, z.core.$strip>, z.ZodObject<{
+    source: z.ZodObject<{
+        delegationId: z.ZodOptional<z.ZodString>;
+        scope: z.ZodLiteral<"backend">;
+        responseId: z.ZodString;
+        itemId: z.ZodString;
+        outputIndex: z.ZodInt;
+    }, z.core.$strip>;
+    content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodEnum<{
+            refusal: "refusal";
+            text: "text";
+        }>;
+        text: z.ZodString;
+        contentIndex: z.ZodInt;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"reasoning_summary">;
+        text: z.ZodString;
+        summaryIndex: z.ZodInt;
+    }, z.core.$strip>], "kind">>;
+    status: z.ZodOptional<z.ZodEnum<{
+        cancelled: "cancelled";
+        completed: "completed";
+        failed: "failed";
+        in_progress: "in_progress";
+        incomplete: "incomplete";
+    }>>;
+    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<"backend.output">;
+}, z.core.$strip>, z.ZodObject<{
+    delegationId: z.ZodOptional<z.ZodString>;
+    responseId: z.ZodString;
+    phase: z.ZodEnum<{
+        completed: "completed";
+        started: "started";
+        "waiting-for-tools": "waiting-for-tools";
+    }>;
+    status: z.ZodOptional<z.ZodString>;
+    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<"backend.response">;
+}, z.core.$strip>, z.ZodObject<{
+    delegationId: z.ZodOptional<z.ZodString>;
+    responseId: z.ZodString;
+    toolId: z.ZodString;
+    outputIndex: z.ZodOptional<z.ZodInt>;
+    name: z.ZodString;
+    phase: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        started: "started";
+    }>;
+    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<"backend.tool">;
+}, z.core.$strip>, z.ZodObject<{
+    delegationId: z.ZodString;
+    target: z.ZodEnum<{
+        client: "client";
+        responses: "responses";
+    }>;
+    offsetMs: z.ZodNumber;
+    responseId: z.ZodOptional<z.ZodString>;
+    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<"delegation.created">;
+}, z.core.$strip>, z.ZodObject<{
+    contextId: z.ZodString;
+    callId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    phase: z.ZodEnum<{
+        acknowledged: "acknowledged";
+        failed: "failed";
+        submitted: "submitted";
+    }>;
+    kind: z.ZodEnum<{
+        commentary: "commentary";
+        instructions: "instructions";
+        thinking: "thinking";
+    }>;
+    startMs: z.ZodOptional<z.ZodNumber>;
+    endMs: z.ZodOptional<z.ZodNumber>;
+    message: z.ZodOptional<z.ZodString>;
+    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<"context.delivery">;
+}, z.core.$strip>, z.ZodObject<{
+    seconds: z.ZodNumber;
+    final: z.ZodBoolean;
+    contextWindowUsageRatio: z.ZodOptional<z.ZodNumber>;
+    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<"usage.duration">;
+}, z.core.$strip>, z.ZodObject<{
+    streamId: z.ZodString;
+    startSample: z.ZodInt;
+    endSample: z.ZodInt;
+    status: z.ZodEnum<{
+        discarded: "discarded";
+        played: "played";
+    }>;
+    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<"playout.range">;
+}, z.core.$strip>, z.ZodObject<{
+    responseId: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        backend: "backend";
+        voice: "voice";
+    }>>;
     inputTokens: z.ZodNumber;
     outputTokens: z.ZodNumber;
     totalTokens: z.ZodNumber;
@@ -268,6 +582,18 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         callId: z.ZodString;
         name: z.ZodString;
         arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        source: z.ZodOptional<z.ZodObject<{
+            scope: z.ZodEnum<{
+                backend: "backend";
+                voice: "voice";
+            }>;
+            responseId: z.ZodOptional<z.ZodString>;
+            itemId: z.ZodOptional<z.ZodString>;
+            outputIndex: z.ZodOptional<z.ZodInt>;
+            contentIndex: z.ZodOptional<z.ZodInt>;
+            summaryIndex: z.ZodOptional<z.ZodInt>;
+            delegationId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
@@ -356,6 +682,18 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"task.accepted">;
     taskId: z.ZodString;
     callId: z.ZodString;
+}, 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<"task.cancellation_requested">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    reason: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     sessionId: z.ZodString;

package/dist/internal/protocol/events.js

@@ -1,7 +1,10 @@
 import { z } from "zod";
 import { AudioChunkSchema } from "./audio.js";
+import { BackendOutputDeltaSchema, BackendOutputSchema } from "./backend-output.js";
+import { parseEventJson, stringifyEventJson } from "./event-json.js";
+import { ProviderOutputSourceSchema } from "./output-source.js";
 import { InputPartSchema } from "./parts.js";
-import { OutputModalitySchema, ProviderCapabilitiesSchema, ProviderDiagnosticSchema, ResponseStateSchema, TranscriptDeltaPayloadSchema, TranscriptPayloadSchema, UsagePayloadSchema, } from "./provider.js";
+import { BackendResponseSchema, BackendToolSchema, ContextDeliverySchema, DelegationCreatedSchema, DurationUsageSchema, OutputModalitySchema, PlayoutRangeSchema, ProviderCapabilitiesSchema, ProviderDiagnosticSchema, ResponseStateSchema, TranscriptDeltaPayloadSchema, TranscriptFragmentSchema, TranscriptPayloadSchema, UsagePayloadSchema, } from "./provider.js";
 import { JsonValueSchema, ToolCallSchema, ToolOutcomeSchema } from "./tools.js";
 /** Bounds for a typed user message, shared by the event, the session API, and wire schemas. */
 export const MessageInputTextSchema = z.string().min(1).max(8_000);
@@ -14,9 +17,20 @@ const EventBaseSchema = z.object({
     correlationId: z.string().min(1).optional(),
     causationId: z.string().min(1).optional(),
 });
+export const InputAudioEventSchema = EventBaseSchema.extend({
+    type: z.literal("audio.input"),
+    chunk: AudioChunkSchema,
+    syntheticSilence: z.boolean().optional(),
+});
+export const OutputAudioEventSchema = EventBaseSchema.extend({
+    type: z.literal("audio.output"),
+    chunk: AudioChunkSchema,
+    source: ProviderOutputSourceSchema.optional(),
+});
 /**
- * The authoritative session log: every observable fact of a conversation, in one flat,
- * durably ordered stream. There is deliberately no turn or message hierarchy here —
+ * Sequenced live facts of a conversation, in one flat, store-ordered stream. Retained
+ * HarnessRecord values preserve this envelope and may explicitly omit audio bytes.
+ * There is deliberately no turn or message hierarchy here —
  * duplex audio overlaps — conversation views are projections over this log.
  * The full catalog with ordering rules lives in docs/protocol.md.
  */
@@ -41,7 +55,11 @@ export const HarnessEventSchema = z.discriminatedUnion("type", [
     /** 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) }),
+    EventBaseSchema.extend({
+        type: z.literal("provider.closed"),
+        reason: z.string().min(1),
+        finalized: z.boolean().optional(),
+    }),
     /** Provider-reported fault; recoverable errors leave the session running. */
     EventBaseSchema.extend({
         type: z.literal("provider.error"),
@@ -50,24 +68,42 @@ export const HarnessEventSchema = z.discriminatedUnion("type", [
     }),
     /**
      * A typed user message injected into the conversation (text mode or mixed mode).
-     * `text` is the collapsed string realtime providers consume; `parts` preserves the
-     * full multimodal input (text/image/file) for projection when one was given.
+     * This captures input, not delivery. Legacy logs may contain image/file parts that
+     * were never forwarded; current sendText rejects those before partial submission.
      */
     EventBaseSchema.extend({
         type: z.literal("message.input"),
         text: MessageInputTextSchema,
         parts: z.array(InputPartSchema).min(1).optional(),
     }),
+    /** Local provider submission outcome for a captured message; never proof of consumption or speech. */
+    EventBaseSchema.extend({
+        type: z.literal("input.delivery"),
+        inputId: z.string().min(1),
+        providerId: z.string().min(1),
+        target: z.enum(["conversation", "backend"]),
+        phase: z.enum(["submitted", "failed"]),
+        error: z.string().min(1).max(2000).optional(),
+    }),
     /** Microphone PCM as received; the append and the provider forward run in parallel. */
-    EventBaseSchema.extend({ type: z.literal("audio.input"), chunk: AudioChunkSchema }),
+    InputAudioEventSchema,
     /** Model PCM as received; records are pipelined so bursts never stall the event pump. */
-    EventBaseSchema.extend({ type: z.literal("audio.output"), chunk: AudioChunkSchema }),
+    OutputAudioEventSchema,
     /** User barge-in: clients must clear this output stream, including buffered audio. */
     EventBaseSchema.extend({ type: z.literal("audio.interrupted"), streamId: z.string().min(1) }),
     /** Final text for either speaker — speech-to-text, or the model's text output in text mode. */
     EventBaseSchema.extend({ type: z.literal("transcript"), ...TranscriptPayloadSchema.shape }),
     /** Incremental assistant text streamed before the final transcript; live-render only. */
     EventBaseSchema.extend({ type: z.literal("transcript.delta"), ...TranscriptDeltaPayloadSchema.shape }),
+    TranscriptFragmentSchema.safeExtend({ ...EventBaseSchema.shape, type: z.literal("transcript.fragment") }),
+    BackendOutputDeltaSchema.safeExtend({ ...EventBaseSchema.shape, type: z.literal("backend.output.delta") }),
+    EventBaseSchema.extend({ type: z.literal("backend.output"), ...BackendOutputSchema.shape }),
+    EventBaseSchema.extend({ type: z.literal("backend.response"), ...BackendResponseSchema.shape }),
+    EventBaseSchema.extend({ type: z.literal("backend.tool"), ...BackendToolSchema.shape }),
+    EventBaseSchema.extend({ type: z.literal("delegation.created"), ...DelegationCreatedSchema.shape }),
+    EventBaseSchema.extend({ type: z.literal("context.delivery"), ...ContextDeliverySchema.shape }),
+    EventBaseSchema.extend({ type: z.literal("usage.duration"), ...DurationUsageSchema.shape }),
+    PlayoutRangeSchema.safeExtend({ ...EventBaseSchema.shape, type: z.literal("playout.range") }),
     /** Provider-reported token accounting for one completed response. */
     EventBaseSchema.extend({ type: z.literal("usage"), ...UsagePayloadSchema.shape }),
     /** Client acknowledgement of playback position; the authority for barge-in truncation. */
@@ -121,6 +157,13 @@ export const HarnessEventSchema = z.discriminatedUnion("type", [
         taskId: z.string().min(1),
         callId: z.string().min(1),
     }),
+    /** Requested cancellation, not confirmation that the runner or a remote worker stopped. */
+    EventBaseSchema.extend({
+        type: z.literal("task.cancellation_requested"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        reason: z.string().min(1),
+    }),
     /** Intermediate progress from a background task. */
     EventBaseSchema.extend({
         type: z.literal("task.progress"),
@@ -158,25 +201,10 @@ export const HarnessEventSchema = z.discriminatedUnion("type", [
         error: z.string().min(1),
     }),
 ]);
-const bytesMarker = "$xoBytes";
 export function stringifyHarnessEvent(event) {
     HarnessEventSchema.parse(event);
-    return JSON.stringify(event, (_key, value) => {
-        if (value instanceof Uint8Array) {
-            return { [bytesMarker]: Array.from(value) };
-        }
-        return value;
-    });
+    return stringifyEventJson(event);
 }
 export function parseHarnessEvent(serialized) {
-    const value = JSON.parse(serialized, (_key, candidate) => {
-        if (typeof candidate === "object" && candidate !== null && bytesMarker in candidate) {
-            const encoded = candidate[bytesMarker];
-            if (Array.isArray(encoded) && encoded.every((value) => typeof value === "number")) {
-                return Uint8Array.from(encoded);
-            }
-        }
-        return candidate;
-    });
-    return HarnessEventSchema.parse(value);
+    return HarnessEventSchema.parse(parseEventJson(serialized));
 }

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

@@ -1,6 +1,11 @@
 export * from "./async-queue.js";
 export * from "./audio.js";
+export * from "./backend-output.js";
 export * from "./events.js";
+export * from "./output-source.js";
+export * from "./paced-audio.js";
 export * from "./parts.js";
 export * from "./provider.js";
+export * from "./records.js";
 export * from "./tools.js";
+export * from "./transcript.js";

package/dist/internal/protocol/index.js

@@ -1,6 +1,11 @@
 export * from "./async-queue.js";
 export * from "./audio.js";
+export * from "./backend-output.js";
 export * from "./events.js";
+export * from "./output-source.js";
+export * from "./paced-audio.js";
 export * from "./parts.js";
 export * from "./provider.js";
+export * from "./records.js";
 export * from "./tools.js";
+export * from "./transcript.js";

package/dist/internal/protocol/output-source.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/**
+ * Native provenance, when the provider supplies it. Indices are local to the
+ * native response/item, not XO message order, event sequence, or completion.
+ */
+export declare const ProviderOutputSourceSchema: z.ZodObject<{
+    scope: z.ZodEnum<{
+        backend: "backend";
+        voice: "voice";
+    }>;
+    responseId: z.ZodOptional<z.ZodString>;
+    itemId: z.ZodOptional<z.ZodString>;
+    outputIndex: z.ZodOptional<z.ZodInt>;
+    contentIndex: z.ZodOptional<z.ZodInt>;
+    summaryIndex: z.ZodOptional<z.ZodInt>;
+    delegationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProviderOutputSource = z.infer<typeof ProviderOutputSourceSchema>;

package/dist/internal/protocol/output-source.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/**
+ * Native provenance, when the provider supplies it. Indices are local to the
+ * native response/item, not XO message order, event sequence, or completion.
+ */
+export const ProviderOutputSourceSchema = z.object({
+    scope: z.enum(["voice", "backend"]),
+    responseId: z.string().min(1).optional(),
+    itemId: z.string().min(1).optional(),
+    outputIndex: z.int().nonnegative().optional(),
+    contentIndex: z.int().nonnegative().optional(),
+    /** Native reasoning summary position, distinct from message content_index. */
+    summaryIndex: z.int().nonnegative().optional(),
+    delegationId: z.string().min(1).optional(),
+});

package/dist/internal/protocol/paced-audio.d.ts

@@ -0,0 +1,27 @@
+/** One clock for a continuous PCM16 mono input, including time without a microphone or file. */
+export declare class PacedAudioInput {
+    #private;
+    readonly options: {
+        send(data: Uint8Array, syntheticSilence: boolean): Promise<void>;
+        signal: AbortSignal;
+        sampleRate?: number;
+        frameMs?: number;
+        maxBufferedMs?: number;
+        onLate?(delayMs: number): void;
+    };
+    readonly done: Promise<void>;
+    constructor(options: {
+        send(data: Uint8Array, syntheticSilence: boolean): Promise<void>;
+        signal: AbortSignal;
+        sampleRate?: number;
+        frameMs?: number;
+        maxBufferedMs?: number;
+        onLate?(delayMs: number): void;
+    });
+    /**
+     * Resolves when these samples have been submitted. Capture sources enqueue at their
+     * capture cadence; file sources assemble full frames (100 ms by default) before
+     * awaiting writes. Awaiting each shorter packet would pad every packet with silence.
+     */
+    write(data: Uint8Array): Promise<void>;
+}