xo-harness 0.2.0 → 0.3.0

package/dist/internal/harness/xo.js

@@ -5,29 +5,41 @@ export class XO {
     tools;
     #toolPolicy;
     #maxToolResultBytes;
+    #runtimeLimits;
+    #startingSessionIds = new Set();
     constructor(options) {
         this.store = options.store;
         this.tools = new ToolRegistry(options.tools);
         this.#toolPolicy = options.toolPolicy;
         this.#maxToolResultBytes = options.maxToolResultBytes;
+        this.#runtimeLimits = options.runtimeLimits === undefined ? undefined : { ...options.runtimeLimits };
     }
     registerTool(tool) {
         this.tools.register(tool);
     }
-    startSession(options) {
+    async startSession(options) {
+        const sessionId = options.sessionId ?? crypto.randomUUID();
+        if (this.#startingSessionIds.has(sessionId))
+            throw new Error(`Session id already exists: ${sessionId}`);
+        // Reserve before startup's first await. Once it settles, the persisted start record
+        // owns the ID; other XO instances/processes still need host-owned admission.
+        this.#startingSessionIds.add(sessionId);
         const toolPolicy = options.toolPolicy ?? this.#toolPolicy;
         const maxToolResultBytes = options.maxToolResultBytes ?? this.#maxToolResultBytes;
-        return VoiceSession.create({
-            sessionId: options.sessionId ?? crypto.randomUUID(),
-            provider: options.provider,
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
-            store: this.store,
-            tools: this.tools,
-            ...(toolPolicy === undefined ? {} : { toolPolicy }),
-            ...(maxToolResultBytes === undefined ? {} : { maxToolResultBytes }),
-            ...(options.instructions === undefined ? {} : { instructions: options.instructions }),
-            ...(options.outputModalities === undefined ? {} : { outputModalities: options.outputModalities }),
-            ...(options.maxDurationMs === undefined ? {} : { maxDurationMs: options.maxDurationMs }),
-        });
+        try {
+            return await VoiceSession.create({
+                ...options,
+                sessionId,
+                provider: options.provider,
+                store: this.store,
+                tools: this.tools,
+                ...(toolPolicy === undefined ? {} : { toolPolicy }),
+                ...(maxToolResultBytes === undefined ? {} : { maxToolResultBytes }),
+                runtimeLimits: { ...this.#runtimeLimits, ...options.runtimeLimits },
+            });
+        }
+        finally {
+            this.#startingSessionIds.delete(sessionId);
+        }
     }
 }

package/dist/internal/protocol/async-queue.d.ts

@@ -1,8 +1,29 @@
-/** Unbounded push/pull bridge between a callback producer and an async-iterating consumer. */
+export interface AsyncQueueOptions<Value> {
+    maxItems?: number;
+    maxBytes?: number;
+    sizeOf?: (value: Value) => number;
+}
+export declare class AsyncQueueOverflowError extends Error {
+    readonly limit: "items" | "bytes";
+    readonly maximum: number;
+    readonly code: "queue_items_exceeded" | "queue_bytes_exceeded";
+    constructor(limit: "items" | "bytes", maximum: number);
+}
+/** FIFO callback/iterator bridge. Optional limits fail explicitly and discard undelivered values. */
 export declare class AsyncQueue<Value> implements AsyncIterableIterator<Value> {
     #private;
+    constructor(options?: AsyncQueueOptions<Value>);
     push(value: Value): void;
     close(): void;
+    /** Failure is outside capacity: it remains observable even when the queue was full. */
+    fail(error: unknown): void;
+    stats(): {
+        pendingItems: number;
+        pendingBytes: number;
+        state: "open" | "closed" | "failed";
+    };
     next(): Promise<IteratorResult<Value>>;
+    /** Explicit abandonment; iterator breaks retain the historical shared-queue behavior. */
+    discard(): void;
     [Symbol.asyncIterator](): AsyncIterableIterator<Value>;
 }

package/dist/internal/protocol/async-queue.js

@@ -1,34 +1,108 @@
-/** Unbounded push/pull bridge between a callback producer and an async-iterating consumer. */
+export class AsyncQueueOverflowError extends Error {
+    limit;
+    maximum;
+    code;
+    constructor(limit, maximum) {
+        super(`Event queue exceeds its ${maximum} ${limit} limit; undelivered events were discarded`);
+        this.limit = limit;
+        this.maximum = maximum;
+        this.name = "AsyncQueueOverflowError";
+        this.code = limit === "items" ? "queue_items_exceeded" : "queue_bytes_exceeded";
+    }
+}
+/** FIFO callback/iterator bridge. Optional limits fail explicitly and discard undelivered values. */
 export class AsyncQueue {
     #values = [];
     #resolvers = [];
+    #maxItems;
+    #maxBytes;
+    #sizeOf;
+    #bytes = 0;
     #closed = false;
+    #failure;
+    constructor(options = {}) {
+        this.#maxItems = queueLimit(options.maxItems, "maxItems");
+        this.#maxBytes = queueLimit(options.maxBytes, "maxBytes");
+        this.#sizeOf = options.sizeOf ?? (() => 0);
+    }
     push(value) {
+        if (this.#failure)
+            throw this.#failure.error;
         if (this.#closed)
             throw new Error("Cannot push to a closed queue");
-        const resolve = this.#resolvers.shift();
-        if (resolve)
-            resolve({ done: false, value });
-        else
-            this.#values.push(value);
+        const bytes = this.#sizeOf(value);
+        if (!Number.isSafeInteger(bytes) || bytes < 0)
+            throw new RangeError("Queue size must be a nonnegative safe integer");
+        const limit = this.#bytes + bytes > this.#maxBytes
+            ? "bytes"
+            : this.#resolvers.length === 0 && this.#values.length >= this.#maxItems
+                ? "items"
+                : undefined;
+        if (limit) {
+            const error = new AsyncQueueOverflowError(limit, limit === "items" ? this.#maxItems : this.#maxBytes);
+            this.fail(error);
+            throw error;
+        }
+        const waiter = this.#resolvers.shift();
+        if (waiter)
+            waiter.resolve({ done: false, value });
+        else {
+            this.#values.push({ value, bytes });
+            this.#bytes += bytes;
+        }
     }
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
-        for (const resolve of this.#resolvers.splice(0)) {
-            resolve({ done: true, value: undefined });
+        for (const waiter of this.#resolvers.splice(0)) {
+            waiter.resolve({ done: true, value: undefined });
         }
     }
+    /** Failure is outside capacity: it remains observable even when the queue was full. */
+    fail(error) {
+        if (this.#failure)
+            return;
+        this.#failure = { error };
+        this.#closed = true;
+        this.#values.length = 0;
+        this.#bytes = 0;
+        for (const waiter of this.#resolvers.splice(0))
+            waiter.reject(error);
+    }
+    stats() {
+        return {
+            pendingItems: this.#values.length,
+            pendingBytes: this.#bytes,
+            state: this.#failure ? "failed" : this.#closed ? "closed" : "open",
+        };
+    }
     next() {
-        const value = this.#values.shift();
-        if (value !== undefined)
-            return Promise.resolve({ done: false, value });
+        if (this.#failure)
+            return Promise.reject(this.#failure.error);
+        const entry = this.#values.shift();
+        if (entry !== undefined) {
+            this.#bytes -= entry.bytes;
+            return Promise.resolve({ done: false, value: entry.value });
+        }
         if (this.#closed)
             return Promise.resolve({ done: true, value: undefined });
-        return new Promise((resolve) => this.#resolvers.push(resolve));
+        return new Promise((resolve, reject) => this.#resolvers.push({ resolve, reject }));
+    }
+    /** Explicit abandonment; iterator breaks retain the historical shared-queue behavior. */
+    discard() {
+        this.#values.length = 0;
+        this.#bytes = 0;
+        this.close();
     }
     [Symbol.asyncIterator]() {
         return this;
     }
 }
+function queueLimit(value, name) {
+    if (value === undefined || value === Number.POSITIVE_INFINITY)
+        return Number.POSITIVE_INFINITY;
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError(`${name} must be a positive safe integer or Infinity`);
+    return value;
+}

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

@@ -7,6 +7,20 @@ export declare const AudioChunkSchema: z.ZodObject<{
     channels: z.ZodInt;
     startSample: z.ZodInt;
     data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export type AudioChunk = z.infer<typeof AudioChunkSchema>;
-export declare function audioSampleCount(chunk: AudioChunk): number;
+/** A recorded sample range whose PCM was deliberately not retained. Never playable audio. */
+export declare const AudioChunkMetadataSchema: z.ZodObject<{
+    streamId: z.ZodString;
+    sequence: z.ZodInt;
+    encoding: z.ZodLiteral<"pcm_s16le">;
+    sampleRate: z.ZodInt;
+    channels: z.ZodInt;
+    startSample: z.ZodInt;
+    sampleCount: z.ZodInt;
+    availability: z.ZodLiteral<"omitted">;
+    data: z.ZodOptional<z.ZodNever>;
+}, z.core.$strict>;
+export type AudioChunkMetadata = z.infer<typeof AudioChunkMetadataSchema>;
+export declare function audioSampleCount(chunk: AudioChunk | AudioChunkMetadata): number;
+export declare function toAudioMetadata(chunk: AudioChunk | AudioChunkMetadata): AudioChunkMetadata;

package/dist/internal/protocol/audio.js

@@ -1,14 +1,14 @@
 import { z } from "zod";
-export const AudioChunkSchema = z
-    .object({
+const AudioFormatSchema = z.object({
     streamId: z.string().min(1),
     sequence: z.int().nonnegative(),
     encoding: z.literal("pcm_s16le"),
     sampleRate: z.int().positive(),
     channels: z.int().positive(),
     startSample: z.int().nonnegative(),
-    data: z.instanceof(Uint8Array),
-})
+});
+export const AudioChunkSchema = AudioFormatSchema.extend({ data: z.instanceof(Uint8Array) })
+    .strict()
     .superRefine((chunk, context) => {
     const frameWidth = chunk.channels * 2;
     if (chunk.data.byteLength % frameWidth !== 0) {
@@ -19,6 +19,24 @@ export const AudioChunkSchema = z
         });
     }
 });
+/** A recorded sample range whose PCM was deliberately not retained. Never playable audio. */
+export const AudioChunkMetadataSchema = AudioFormatSchema.extend({
+    sampleCount: z.int().nonnegative(),
+    availability: z.literal("omitted"),
+    data: z.never().optional(),
+}).strict();
 export function audioSampleCount(chunk) {
-    return chunk.data.byteLength / (chunk.channels * 2);
+    return chunk.data === undefined ? chunk.sampleCount : chunk.data.byteLength / (chunk.channels * 2);
+}
+export function toAudioMetadata(chunk) {
+    return AudioChunkMetadataSchema.parse({
+        streamId: chunk.streamId,
+        sequence: chunk.sequence,
+        encoding: chunk.encoding,
+        sampleRate: chunk.sampleRate,
+        channels: chunk.channels,
+        startSample: chunk.startSample,
+        sampleCount: audioSampleCount(chunk),
+        availability: "omitted",
+    });
 }

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

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/** Backend output is not a spoken caption or evidence of device playback. */
+export declare const BackendOutputSourceSchema: z.ZodObject<{
+    delegationId: z.ZodOptional<z.ZodString>;
+    scope: z.ZodLiteral<"backend">;
+    responseId: z.ZodString;
+    itemId: z.ZodString;
+    outputIndex: z.ZodInt;
+}, z.core.$strip>;
+/** Public content positions within one native item; private/encrypted reasoning is excluded. */
+export declare const BackendOutputContentSchema: 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">;
+export declare const BackendOutputDeltaSchema: 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;
+}, z.core.$strip>;
+export declare const BackendOutputSchema: 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";
+    }>>;
+}, z.core.$strip>;
+export type BackendOutput = z.infer<typeof BackendOutputSchema>;
+export type BackendOutputDelta = z.infer<typeof BackendOutputDeltaSchema>;
+export type BackendOutputContent = z.infer<typeof BackendOutputContentSchema>;

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

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { ProviderOutputSourceSchema } from "./output-source.js";
+/** Backend output is not a spoken caption or evidence of device playback. */
+export const BackendOutputSourceSchema = ProviderOutputSourceSchema.omit({
+    contentIndex: true,
+    summaryIndex: true,
+}).extend({
+    scope: z.literal("backend"),
+    responseId: z.string().min(1),
+    itemId: z.string().min(1),
+    outputIndex: z.int().nonnegative(),
+});
+/** Public content positions within one native item; private/encrypted reasoning is excluded. */
+export const BackendOutputContentSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.enum(["text", "refusal"]), text: z.string(), contentIndex: z.int().nonnegative() }),
+    z.object({ kind: z.literal("reasoning_summary"), text: z.string(), summaryIndex: z.int().nonnegative() }),
+]);
+export const BackendOutputDeltaSchema = z
+    .object({
+    kind: z.enum(["text", "refusal", "reasoning_summary"]),
+    source: BackendOutputSourceSchema.extend({
+        contentIndex: z.int().nonnegative().optional(),
+        summaryIndex: z.int().nonnegative().optional(),
+    }).refine((source) => (source.contentIndex === undefined) !== (source.summaryIndex === undefined), "Backend delta requires exactly one native content or summary position"),
+    delta: z.string(),
+})
+    .refine((event) => event.kind === "reasoning_summary"
+    ? event.source.summaryIndex !== undefined
+    : event.source.contentIndex !== undefined, "Backend delta kind must match its native content or summary position");
+export const BackendOutputSchema = z.object({
+    source: BackendOutputSourceSchema,
+    /** Authoritative final item snapshot, including an empty list or removed positions. */
+    content: z.array(BackendOutputContentSchema).refine((content) => {
+        const positions = content.map((part) => "contentIndex" in part ? `content:${part.contentIndex}` : `summary:${part.summaryIndex}`);
+        return new Set(positions).size === positions.length;
+    }, "Backend item snapshot cannot repeat a content position"),
+    /** Actual native item status, when supplied. The final event alone does not imply success. */
+    status: z.enum(["in_progress", "completed", "incomplete", "cancelled", "failed"]).optional(),
+});

package/dist/internal/protocol/event-json.d.ts

@@ -0,0 +1,3 @@
+/** Shared wire encoding for live events and retained records. */
+export declare function stringifyEventJson(value: unknown): string;
+export declare function parseEventJson(serialized: string): unknown;

package/dist/internal/protocol/event-json.js

@@ -0,0 +1,15 @@
+/** Shared wire encoding for live events and retained records. */
+export function stringifyEventJson(value) {
+    return JSON.stringify(value, (_key, field) => field instanceof Uint8Array ? { $xoBytes: Array.from(field) } : field);
+}
+export function parseEventJson(serialized) {
+    return JSON.parse(serialized, (_key, candidate) => {
+        if (typeof candidate === "object" && candidate !== null && "$xoBytes" in candidate) {
+            const encoded = candidate.$xoBytes;
+            if (Array.isArray(encoded) &&
+                encoded.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255))
+                return Uint8Array.from(encoded);
+        }
+        return candidate;
+    });
+}