xo-harness 0.1.0

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

@@ -0,0 +1,350 @@
+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;
+/**
+ * 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 —
+ * duplex audio overlaps — conversation views are projections over this log.
+ * The full catalog with ordering rules lives in docs/protocol.md.
+ */
+export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[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<"session.started">;
+    formatVersion: z.ZodOptional<z.ZodInt>;
+    providerId: z.ZodString;
+    capabilities: z.ZodObject<{
+        continuousInputDuringOutput: z.ZodBoolean;
+        modelManagedFloor: z.ZodBoolean;
+        supportsToolCalls: z.ZodBoolean;
+        supportsAsyncContext: z.ZodBoolean;
+        supportsPlayoutAcknowledgements: z.ZodBoolean;
+    }, z.core.$strip>;
+    instructions: z.ZodOptional<z.ZodString>;
+    outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        audio: "audio";
+        text: "text";
+    }>>>;
+}, 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<"session.ended">;
+    reason: 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<"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<"provider.closed">;
+    reason: 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<"provider.error">;
+    message: z.ZodString;
+    recoverable: z.ZodBoolean;
+}, 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<"message.input">;
+    text: z.ZodString;
+    parts: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        mediaType: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        mediaType: z.ZodString;
+        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<"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.$strip>;
+}, 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<"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.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    text: z.ZodString;
+    streamId: 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<"transcript">;
+}, z.core.$strip>, z.ZodObject<{
+    role: z.ZodEnum<{
+        assistant: "assistant";
+        user: "user";
+    }>;
+    delta: z.ZodString;
+    streamId: 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<"transcript.delta">;
+}, z.core.$strip>, z.ZodObject<{
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    audioInputTokens: z.ZodOptional<z.ZodNumber>;
+    audioOutputTokens: z.ZodOptional<z.ZodNumber>;
+    cachedAudioInputTokens: 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">;
+}, 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<"playout.progress">;
+    streamId: z.ZodString;
+    playedThroughSample: z.ZodInt;
+}, 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<"tool.requested">;
+    call: z.ZodObject<{
+        callId: z.ZodString;
+        name: z.ZodString;
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>;
+}, 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<"tool.started">;
+    callId: z.ZodString;
+    name: 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<"tool.progress">;
+    callId: z.ZodString;
+    update: z.ZodJSONSchema;
+}, 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<"tool.completed">;
+    callId: z.ZodString;
+    outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"completed">;
+        value: z.ZodJSONSchema;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"accepted_task">;
+        taskId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"failed">;
+        error: 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<"tool.failed">;
+    callId: z.ZodString;
+    error: 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<"tool.delivery_failed">;
+    callId: z.ZodString;
+    error: 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.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.progress">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    update: z.ZodJSONSchema;
+}, 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.completed">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    result: z.ZodJSONSchema;
+}, 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.failed">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    error: 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.cancelled">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    reason: 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.delivery_failed">;
+    taskId: z.ZodString;
+    callId: z.ZodString;
+    phase: z.ZodEnum<{
+        progress: "progress";
+        terminal: "terminal";
+    }>;
+    error: z.ZodString;
+}, z.core.$strip>], "type">;
+export type HarnessEvent = z.infer<typeof HarnessEventSchema>;
+type DynamicEventField = "sequence";
+export type UnsequencedHarnessEvent = HarnessEvent extends infer Event ? Event extends HarnessEvent ? Omit<Event, DynamicEventField> : never : never;
+type GeneratedEventField = "id" | "sessionId" | "sequence" | "recordedAtMs" | "sessionTimeMs";
+export type NewHarnessEvent = HarnessEvent extends infer Event ? Event extends HarnessEvent ? Omit<Event, GeneratedEventField> : never : never;
+export declare function stringifyHarnessEvent(event: HarnessEvent): string;
+export declare function parseHarnessEvent(serialized: string): HarnessEvent;
+export {};

package/dist/internal/protocol/events.js

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import { AudioChunkSchema } from "./audio.js";
+import { InputPartSchema } from "./parts.js";
+import { OutputModalitySchema, ProviderCapabilitiesSchema, TranscriptDeltaPayloadSchema, 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);
+const EventBaseSchema = z.object({
+    id: z.string().min(1),
+    sessionId: z.string().min(1),
+    sequence: z.int().positive(),
+    recordedAtMs: z.number().nonnegative(),
+    sessionTimeMs: z.number().nonnegative(),
+    correlationId: z.string().min(1).optional(),
+    causationId: z.string().min(1).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 —
+ * duplex audio overlaps — conversation views are projections over this log.
+ * The full catalog with ordering rules lives in docs/protocol.md.
+ */
+export const HarnessEventSchema = z.discriminatedUnion("type", [
+    /** First event of every session, durably appended before any provider event flows. */
+    EventBaseSchema.extend({
+        type: z.literal("session.started"),
+        formatVersion: z.int().positive().optional(),
+        providerId: z.string().min(1),
+        capabilities: ProviderCapabilitiesSchema,
+        instructions: z.string().optional(),
+        outputModalities: z.array(OutputModalitySchema).min(1).optional(),
+    }),
+    /** Always the final event; appended after tools settle and pending media records land. */
+    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") }),
+    /** 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. */
+    EventBaseSchema.extend({
+        type: z.literal("provider.error"),
+        message: z.string().min(1),
+        recoverable: z.boolean(),
+    }),
+    /**
+     * 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.
+     */
+    EventBaseSchema.extend({
+        type: z.literal("message.input"),
+        text: MessageInputTextSchema,
+        parts: z.array(InputPartSchema).min(1).optional(),
+    }),
+    /** Microphone PCM as received; the append and the provider forward run in parallel. */
+    EventBaseSchema.extend({ type: z.literal("audio.input"), chunk: AudioChunkSchema }),
+    /** Model PCM as received; records are pipelined so bursts never stall the event pump. */
+    EventBaseSchema.extend({ type: z.literal("audio.output"), chunk: AudioChunkSchema }),
+    /** 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 }),
+    /** 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. */
+    EventBaseSchema.extend({
+        type: z.literal("playout.progress"),
+        streamId: z.string().min(1),
+        playedThroughSample: z.int().nonnegative(),
+    }),
+    /** The model asked for a tool; recorded before execution begins. */
+    EventBaseSchema.extend({ type: z.literal("tool.requested"), call: ToolCallSchema }),
+    /** Local execution of a requested tool has begun. */
+    EventBaseSchema.extend({
+        type: z.literal("tool.started"),
+        callId: z.string().min(1),
+        name: z.string().min(1),
+    }),
+    /** Intermediate progress reported by a running tool. */
+    EventBaseSchema.extend({
+        type: z.literal("tool.progress"),
+        callId: z.string().min(1),
+        update: JsonValueSchema,
+    }),
+    /** The tool execution settled; provider delivery is tracked independently. */
+    EventBaseSchema.extend({
+        type: z.literal("tool.completed"),
+        callId: z.string().min(1),
+        outcome: ToolOutcomeSchema,
+    }),
+    /** Tool lookup, validation, or execution failed; provider delivery is tracked independently. */
+    EventBaseSchema.extend({
+        type: z.literal("tool.failed"),
+        callId: z.string().min(1),
+        error: z.string().min(1),
+    }),
+    /** A terminal tool result could not be delivered to the provider. */
+    EventBaseSchema.extend({
+        type: z.literal("tool.delivery_failed"),
+        callId: z.string().min(1),
+        error: z.string().min(1),
+    }),
+    /** A tool handed off to a long-running task that outlives the tool call. */
+    EventBaseSchema.extend({
+        type: z.literal("task.accepted"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+    }),
+    /** Intermediate progress from a background task. */
+    EventBaseSchema.extend({
+        type: z.literal("task.progress"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        update: JsonValueSchema,
+    }),
+    /** The background task finished; providers may announce the settlement mid-conversation. */
+    EventBaseSchema.extend({
+        type: z.literal("task.completed"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        result: JsonValueSchema,
+    }),
+    /** The background task failed after acceptance. */
+    EventBaseSchema.extend({
+        type: z.literal("task.failed"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        error: z.string().min(1),
+    }),
+    /** The background task was cancelled, usually because the session is closing. */
+    EventBaseSchema.extend({
+        type: z.literal("task.cancelled"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        reason: z.string().min(1),
+    }),
+    /** Recorded task context could not be delivered to the provider. */
+    EventBaseSchema.extend({
+        type: z.literal("task.delivery_failed"),
+        taskId: z.string().min(1),
+        callId: z.string().min(1),
+        phase: z.enum(["progress", "terminal"]),
+        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;
+    });
+}
+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);
+}

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

@@ -0,0 +1,6 @@
+export * from "./async-queue.js";
+export * from "./audio.js";
+export * from "./events.js";
+export * from "./parts.js";
+export * from "./provider.js";
+export * from "./tools.js";

package/dist/internal/protocol/index.js

@@ -0,0 +1,6 @@
+export * from "./async-queue.js";
+export * from "./audio.js";
+export * from "./events.js";
+export * from "./parts.js";
+export * from "./provider.js";
+export * from "./tools.js";