xo-harness 0.2.0 → 0.3.0

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

@@ -0,0 +1,132 @@
+import { toolDenialError } from "./tool-policy.js";
+/**
+ * Incremental projection of a single session's sequence-ordered event log. This
+ * observes execution; ToolRuntime and TaskSupervisor remain its only owners.
+ * Applying an event replaces the changed entry, leaving prior snapshots stable.
+ */
+export class ToolCallTracker {
+    #calls = new Map();
+    get(callId) {
+        return this.#calls.get(callId);
+    }
+    list() {
+        return [...this.#calls.values()];
+    }
+    hasPending() {
+        for (const call of this.#calls.values()) {
+            if (call.status === "pending")
+                return true;
+        }
+        return false;
+    }
+    /** Returns the updated call, or undefined when the event has no effect. */
+    apply(event) {
+        if (event.type === "tool.requested") {
+            if (this.#calls.has(event.call.callId))
+                return;
+            return this.#save({
+                callId: event.call.callId,
+                name: event.call.name,
+                ...(event.call.source === undefined ? {} : { source: { ...event.call.source } }),
+                state: { status: "running", input: event.call.arguments, startedAtMs: event.recordedAtMs },
+                status: "pending",
+                deliveryFailures: [],
+            });
+        }
+        if (!("callId" in event) || event.callId === undefined)
+            return;
+        const call = this.#calls.get(event.callId);
+        if (!call)
+            return;
+        switch (event.type) {
+            case "tool.completed":
+                if (call.state.status !== "running")
+                    return;
+                return this.#settle(call, event.outcome, event.recordedAtMs);
+            case "tool.failed":
+                if (call.state.status !== "running")
+                    return;
+                return this.#settle(call, { type: "failed", error: event.error }, event.recordedAtMs);
+            case "tool.denied":
+                if (call.state.status !== "running")
+                    return;
+                return this.#settle(call, { type: "failed", error: toolDenialError(event.reason) }, event.recordedAtMs);
+            case "task.accepted":
+                if (call.taskId !== undefined || call.status !== "pending")
+                    return;
+                return this.#save({ ...call, taskId: event.taskId });
+            case "tool.progress":
+                if (call.state.status !== "running")
+                    return;
+                return this.#progress(call, event);
+            case "task.progress":
+                if (call.status !== "pending" || call.taskId !== event.taskId)
+                    return;
+                return this.#progress(call, event);
+            case "task.completed":
+            case "task.failed":
+            case "task.cancelled": {
+                if (call.state.status !== "settled" ||
+                    call.state.outcome.type !== "accepted_task" ||
+                    call.state.outcome.taskId !== event.taskId)
+                    return;
+                return this.#settle(call, event.type === "task.completed"
+                    ? { type: "completed", value: event.result }
+                    : event.type === "task.failed"
+                        ? { type: "failed", error: event.error }
+                        : { type: "failed", error: `Task cancelled: ${event.reason}` }, event.recordedAtMs);
+            }
+            case "tool.delivery_failed":
+            case "task.delivery_failed":
+                if (event.type === "task.delivery_failed" && call.taskId !== event.taskId)
+                    return;
+                if (call.deliveryFailures.some((failure) => failure.eventId === event.id))
+                    return;
+                return this.#save({
+                    ...call,
+                    deliveryFailures: [
+                        ...call.deliveryFailures,
+                        {
+                            eventId: event.id,
+                            phase: event.type === "tool.delivery_failed" ? "tool" : event.phase,
+                            error: event.error,
+                            recordedAtMs: event.recordedAtMs,
+                        },
+                    ],
+                });
+            default:
+                return;
+        }
+    }
+    #settle(call, outcome, recordedAtMs) {
+        return this.#save({
+            ...call,
+            state: {
+                status: "settled",
+                input: call.state.input,
+                startedAtMs: call.state.startedAtMs,
+                endedAtMs: recordedAtMs,
+                outcome,
+            },
+            status: outcome.type === "accepted_task" ? "pending" : "result_ready",
+            ...(outcome.type === "accepted_task" ? { taskId: outcome.taskId } : {}),
+        });
+    }
+    #progress(call, event) {
+        return this.#save({
+            ...call,
+            progress: { update: event.update, recordedAtMs: event.recordedAtMs },
+        });
+    }
+    #save(call) {
+        this.#calls.set(call.callId, call);
+        return call;
+    }
+}
+/** Pure replay of the same lifecycle used by live harness consumers and messages. */
+export function projectToolCalls(events) {
+    const tracker = new ToolCallTracker();
+    for (const event of events)
+        tracker.apply(event);
+    return tracker.list();
+}

package/dist/internal/harness/tool-policy.d.ts

@@ -1,4 +1,4 @@
-import type { HarnessEvent, ToolCall } from "../protocol/index.js";
+import type { HarnessRecord, ToolCall } from "../protocol/index.js";
 import type { ToolAnnotations } from "./tools.js";
 /** Everything a policy may consult when admitting one tool call. */
 export interface ToolAdmissionContext {
@@ -16,7 +16,7 @@ export interface ToolAdmissionContext {
      * this. Reads the store (audio events included), so call it only when a decision
      * needs it, and project with `projectMessages` rather than scanning raw events.
      */
-    history(): Promise<readonly HarnessEvent[]>;
+    history(): Promise<readonly HarnessRecord[]>;
 }
 export type ToolAdmission = {
     decision: "allow";

package/dist/internal/harness/tool-runtime.d.ts

@@ -1,4 +1,4 @@
-import { type HarnessEvent, type NewHarnessEvent, type ProviderToolResult, type ToolCall } from "../protocol/index.js";
+import { type HarnessEvent, type HarnessRecord, type NewHarnessEvent, type ProviderToolResult, type ToolCall } from "../protocol/index.js";
 import type { TaskSupervisor } from "./task-supervisor.js";
 import { type ToolPolicy } from "./tool-policy.js";
 import type { ToolRegistry } from "./tools.js";
@@ -16,7 +16,7 @@ export declare class ToolRuntime {
         signal: AbortSignal;
         flush: () => Promise<void>;
         policy: ToolPolicy;
-        history: () => Promise<readonly HarnessEvent[]>;
+        history: () => Promise<readonly HarnessRecord[]>;
         maxResultBytes: number;
     });
     execute(call: ToolCall): Promise<void>;

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

@@ -33,13 +33,19 @@ export class ToolRuntime {
         if (this.#inFlight.has(call.callId) || this.#terminal.has(call.callId))
             return;
         this.#inFlight.add(call.callId);
+        let acceptedTaskId;
         try {
             const admission = await this.#admit(call);
             // Cancellation can follow a resolved admission before this continuation runs.
             if (admission === undefined || this.#signal.aborted)
                 return;
             if (admission.decision === "deny") {
-                await this.#settleDenied(call, admission.reason);
+                await this.#settle({
+                    type: "tool.denied",
+                    callId: call.callId,
+                    name: call.name,
+                    reason: admission.reason,
+                });
                 return;
             }
             await this.#record({ type: "tool.started", callId: call.callId, name: call.name });
@@ -48,7 +54,11 @@ export class ToolRuntime {
                 return;
             const tool = this.#tools.get(call.name);
             if (!tool) {
-                await this.#settleFailure(call.callId, `Tool not found: ${call.name}`);
+                await this.#settle({
+                    type: "tool.failed",
+                    callId: call.callId,
+                    error: `Tool not found: ${call.name}`,
+                });
                 return;
             }
             let outcome;
@@ -59,13 +69,20 @@ export class ToolRuntime {
                 outcome = ToolOutcomeSchema.parse(await this.#run(tool, input, call.callId));
             }
             catch (error) {
-                await this.#settleFailure(call.callId, errorMessage(error));
+                await this.#settle({ type: "tool.failed", callId: call.callId, error: errorMessage(error) });
                 return;
             }
-            await this.#settleCompleted(call.callId, outcome);
+            if (outcome.type === "accepted_task")
+                acceptedTaskId = outcome.taskId;
+            await this.#settle({ type: "tool.completed", callId: call.callId, outcome });
         }
         finally {
-            this.#inFlight.delete(call.callId);
+            try {
+                await this.#tasks.cancelUnaccepted(call.callId, acceptedTaskId);
+            }
+            finally {
+                this.#inFlight.delete(call.callId);
+            }
         }
     }
     async #admit(call) {
@@ -91,21 +108,9 @@ export class ToolRuntime {
         // aborted call is simply left unterminated — the same shape a lost process leaves.
         return raceWithAbort(decision, this.#signal);
     }
-    async #settleDenied(call, reason) {
-        this.#assertNotTerminal(call.callId);
-        this.#terminal.add(call.callId);
-        try {
-            await this.#record({ type: "tool.denied", callId: call.callId, name: call.name, reason });
-        }
-        catch (error) {
-            this.#terminal.delete(call.callId);
-            throw error;
-        }
-        await this.#flush();
-        await this.#deliver(call.callId, { type: "failed", error: toolDenialError(reason) });
-    }
     async #run(tool, input, callId) {
         return tool.execute(input, {
+            callId,
             signal: this.#signal,
             maxResultBytes: this.#maxResultBytes,
             tasks: this.#tasks.forCall(callId),
@@ -114,33 +119,30 @@ export class ToolRuntime {
             },
         });
     }
-    async #settleCompleted(callId, outcome) {
-        this.#assertNotTerminal(callId);
-        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);
+    async #settle(event) {
+        const { callId } = event;
+        if (this.#terminal.has(callId))
+            throw new Error(`Tool call already settled: ${callId}`);
         this.#terminal.add(callId);
         try {
-            await this.#record({ type: "tool.failed", callId, error: message });
+            await this.#record(event);
         }
         catch (error) {
             this.#terminal.delete(callId);
             throw error;
         }
         await this.#flush();
-        await this.#deliver(callId, { type: "failed", error: message });
+        await this.#deliver(callId, event.type === "tool.completed"
+            ? event.outcome
+            : {
+                type: "failed",
+                error: event.type === "tool.denied" ? toolDenialError(event.reason) : event.error,
+            });
     }
     async #deliver(callId, outcome) {
+        // Keep the terminal record, but do not restart model work while the session drains.
+        if (this.#signal.aborted)
+            return;
         try {
             // The log keeps the full outcome; only the provider-bound copy is bounded.
             await this.#resultSink.deliver({
@@ -160,11 +162,6 @@ export class ToolRuntime {
             await this.#tasks.activate(outcome.taskId, callId);
         }
     }
-    #assertNotTerminal(callId) {
-        if (this.#terminal.has(callId)) {
-            throw new Error(`Tool call already settled: ${callId}`);
-        }
-    }
 }
 function raceWithAbort(work, signal) {
     if (signal.aborted)

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

@@ -6,14 +6,35 @@ export interface BackgroundTaskContext {
     report(update: JsonValue): Promise<void>;
 }
 export type BackgroundTaskRunner = (context: BackgroundTaskContext) => Promise<JsonValue>;
+/** An explicit execution outcome; arbitrary JSON returned by tasks.start remains result data. */
+export declare const BackgroundTaskOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"completed">;
+    result: z.ZodJSONSchema;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"failed">;
+    error: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"cancelled">;
+    reason: z.ZodString;
+}, z.core.$strip>], "type">;
+export type BackgroundTaskOutcome = z.infer<typeof BackgroundTaskOutcomeSchema>;
+export type BackgroundTaskOutcomeRunner = (context: BackgroundTaskContext) => Promise<BackgroundTaskOutcome>;
+/** A request receipt, never confirmation that a remote worker stopped. */
+export interface TaskCancellationRequestResult {
+    status: "requested" | "already_requested" | "settled" | "not_found";
+}
 export interface BackgroundTaskOptions {
     /** Release resources reserved before start if the task is cancelled before its runner activates. */
     onPendingCancel?: () => void;
 }
 export interface BackgroundTaskLauncher {
     start(run: BackgroundTaskRunner, options?: BackgroundTaskOptions): Promise<string>;
+    /** Returned outcomes remain authoritative when cancellation races settlement. Throws are failures. */
+    startOutcome(run: BackgroundTaskOutcomeRunner, options?: BackgroundTaskOptions): Promise<string>;
 }
 export interface ToolExecutionContext {
+    /** The provider call being executed, suitable for correlating application-owned work. */
+    readonly callId: string;
     /** Session lifetime signal. Executions must settle on abort; arbitrary JavaScript cannot be forcibly stopped. */
     readonly signal: AbortSignal;
     /** JSON payload budget for provider delivery; tools can use it to size recoverable pages. */

package/dist/internal/harness/tools.js

@@ -1,5 +1,11 @@
-import { ProviderToolDefinitionSchema, } from "../protocol/index.js";
+import { JsonValueSchema, ProviderToolDefinitionSchema, } from "../protocol/index.js";
 import { z } from "zod";
+/** An explicit execution outcome; arbitrary JSON returned by tasks.start remains result data. */
+export const BackgroundTaskOutcomeSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("completed"), result: JsonValueSchema }),
+    z.object({ type: z.literal("failed"), error: z.string().min(1) }),
+    z.object({ type: z.literal("cancelled"), reason: z.string().min(1) }),
+]);
 export function defineTool(tool) {
     return tool;
 }

package/dist/internal/harness/usage-tracker.d.ts

@@ -0,0 +1,39 @@
+import type { HarnessRecord } from "../protocol/index.js";
+/** Provider-reported token totals. Duration is a separate accounting domain. */
+export interface UsageTotals {
+    responses: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedInputTokens: number;
+    audioInputTokens: number;
+    audioOutputTokens: number;
+    cachedAudioInputTokens: number;
+}
+export interface SessionUsageSnapshot {
+    sessionId: string;
+    usage: UsageTotals;
+    backendUsage?: UsageTotals;
+    voiceDuration?: {
+        seconds: number;
+        final: boolean;
+    };
+    /** Session end, provider finalization, and final duration are independent observations. */
+    ended: boolean;
+    endedReason?: string;
+    finalized?: boolean;
+}
+/**
+ * Incremental accounting for one session. Apply its ordered events; exact event-ID
+ * replay and repeated response IDs are counted once. Retains no PCM or transcripts.
+ * Host ledgers must commit each session's contribution idempotently themselves.
+ */
+export declare class SessionUsageTracker {
+    #private;
+    constructor(options: {
+        sessionId: string;
+    });
+    apply(event: HarnessRecord): boolean;
+    /** Detached values remain stable while an asynchronous persistence queue drains. */
+    snapshot(): SessionUsageSnapshot;
+}

package/dist/internal/harness/usage-tracker.js

@@ -0,0 +1,104 @@
+/**
+ * Incremental accounting for one session. Apply its ordered events; exact event-ID
+ * replay and repeated response IDs are counted once. Retains no PCM or transcripts.
+ * Host ledgers must commit each session's contribution idempotently themselves.
+ */
+export class SessionUsageTracker {
+    #sessionId;
+    #seen = new Set();
+    #responses = new Set();
+    #usage = emptyUsage();
+    #backendUsage;
+    #voiceDuration;
+    #endedReason;
+    #providerClosed = false;
+    #finalized;
+    constructor(options) {
+        if (!options.sessionId)
+            throw new Error("Usage tracker requires a session ID");
+        this.#sessionId = options.sessionId;
+    }
+    apply(event) {
+        if (event.sessionId !== this.#sessionId)
+            throw new Error("Usage event belongs to another session");
+        if (event.type !== "usage" &&
+            event.type !== "usage.duration" &&
+            event.type !== "provider.closed" &&
+            event.type !== "session.ended")
+            return false;
+        if (this.#seen.has(event.id))
+            return false;
+        this.#seen.add(event.id);
+        switch (event.type) {
+            case "usage": {
+                const key = event.responseId && JSON.stringify([event.scope ?? "voice", event.responseId]);
+                if (key && this.#responses.has(key))
+                    return false;
+                if (key)
+                    this.#responses.add(key);
+                addUsage(this.#usage, event);
+                if (event.scope === "backend") {
+                    this.#backendUsage ??= emptyUsage();
+                    addUsage(this.#backendUsage, event);
+                }
+                return true;
+            }
+            case "usage.duration": {
+                if (this.#voiceDuration?.final)
+                    return false;
+                // Interim snapshots cannot regress. A final provider report remains authoritative.
+                const seconds = event.final
+                    ? event.seconds
+                    : Math.max(this.#voiceDuration?.seconds ?? 0, event.seconds);
+                const changed = seconds !== this.#voiceDuration?.seconds || event.final !== this.#voiceDuration?.final;
+                this.#voiceDuration = { seconds, final: event.final };
+                return changed;
+            }
+            case "provider.closed":
+                if (this.#providerClosed)
+                    return false;
+                this.#providerClosed = true;
+                this.#finalized = event.finalized;
+                return true;
+            case "session.ended":
+                if (this.#endedReason !== undefined)
+                    return false;
+                this.#endedReason = event.reason;
+                return true;
+        }
+    }
+    /** Detached values remain stable while an asynchronous persistence queue drains. */
+    snapshot() {
+        return {
+            sessionId: this.#sessionId,
+            usage: { ...this.#usage },
+            ended: this.#endedReason !== undefined,
+            ...(this.#backendUsage === undefined ? {} : { backendUsage: { ...this.#backendUsage } }),
+            ...(this.#voiceDuration === undefined ? {} : { voiceDuration: { ...this.#voiceDuration } }),
+            ...(this.#endedReason === undefined ? {} : { endedReason: this.#endedReason }),
+            ...(this.#finalized === undefined ? {} : { finalized: this.#finalized }),
+        };
+    }
+}
+function emptyUsage() {
+    return {
+        responses: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        cachedInputTokens: 0,
+        audioInputTokens: 0,
+        audioOutputTokens: 0,
+        cachedAudioInputTokens: 0,
+    };
+}
+function addUsage(total, event) {
+    total.responses += 1;
+    total.inputTokens += event.inputTokens;
+    total.outputTokens += event.outputTokens;
+    total.totalTokens += event.totalTokens;
+    total.cachedInputTokens += event.cachedInputTokens ?? 0;
+    total.audioInputTokens += event.audioInputTokens ?? 0;
+    total.audioOutputTokens += event.audioOutputTokens ?? 0;
+    total.cachedAudioInputTokens += event.cachedAudioInputTokens ?? 0;
+}

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

@@ -1,7 +1,10 @@
-import { type AgentInput, type AssistantTurnRequest, type AudioChunk, type HarnessEvent, type OutputModality, type PlayoutProgress } from "../protocol/index.js";
+import { type AgentInput, type AssistantTurnRequest, type AudioChunk, type ConversationContextUpdate, type HarnessEvent, type HarnessRecord, type OutputModality, type PlayoutProgress, type PlayoutRange, type ProviderCapabilities } from "../protocol/index.js";
 import type { VoiceProvider } from "../provider/index.js";
 import type { EventStore } from "../storage/index.js";
+import { type SessionRuntimeLimits } from "./runtime-limits.js";
+import { type ToolCallProjection } from "./tool-calls.js";
 import { type ToolPolicy } from "./tool-policy.js";
+import type { TaskCancellationRequestResult } from "./tools.js";
 import { ToolRegistry } from "./tools.js";
 export interface CreateVoiceSessionOptions {
     sessionId: string;
@@ -20,8 +23,12 @@ export interface CreateVoiceSessionOptions {
     instructions?: string;
     /** What the model may produce this session; ["text"] disables audio output. Default: audio. */
     outputModalities?: readonly OutputModality[];
-    /** Closes the session with max_duration_reached once elapsed. Guards runaway metered sessions. */
+    /** Closes with max_duration_reached once elapsed. Integer 1–2147483647 ms; omitted means no timer. */
     maxDurationMs?: number;
+    /** Bounds shutdown of an uncooperative provider or tool. Integer 1–2147483647 ms; default: 15 seconds. */
+    closeTimeoutMs?: number;
+    /** Opt-in replay-window, append-backlog, and store-operation limits. */
+    runtimeLimits?: SessionRuntimeLimits;
 }
 export declare class VoiceSession {
     #private;
@@ -29,13 +36,34 @@ export declare class VoiceSession {
     private constructor();
     static create(options: CreateVoiceSessionOptions): Promise<VoiceSession>;
     events(afterSequence?: number): AsyncIterable<HarnessEvent>;
-    history(): Promise<readonly HarnessEvent[]>;
-    sendAudio(chunk: AudioChunk): Promise<void>;
+    history(): Promise<readonly HarnessRecord[]>;
+    /** Separate buffer owners; these counters are not a whole-process memory ceiling. */
+    runtimeStats(): {
+        pendingAppends: number;
+        pendingAppendAudioBytes: number;
+        replay: {
+            retainedEvents: number;
+            retainedAudioBytes: number;
+            oldestSequence: number | undefined;
+            latestSequence: number;
+            subscribers: number;
+        };
+        providerQueue?: import("../provider/index.js").ProviderEventQueueStats;
+    };
+    /** Immutable startup snapshot; missing optional fields retain their documented legacy meaning. */
+    get capabilities(): Readonly<ProviderCapabilities>;
+    /** Recorded tool/task execution. Completion does not imply a spoken announcement. */
+    toolCalls(): readonly ToolCallProjection[];
+    /** Requests one task's cancellation. The terminal task event, not this result, records settlement. */
+    cancelTask(taskId: string, reason?: string): Promise<TaskCancellationRequestResult>;
+    sendAudio(chunk: AudioChunk, metadata?: {
+        syntheticSilence?: boolean;
+    }): Promise<void>;
     /**
-     * Injects a user turn. Accepts a plain string or multimodal `AgentInput` (text /
-     * image / file parts). The parts are recorded on the `message.input` event, so the
-     * log keeps full fidelity for projection; realtime providers only consume text, so
-     * the collapsed text is what goes over the wire (media-native providers wire later).
+     * Submits a string or text-only AgentInput to the declared provider destination.
+     * Image/file parts are rejected before recording or partial delivery. Applications
+     * route those parts to their own backend. input.delivery records local submission,
+     * not backend consumption; interrupted shutdown can leave delivery unconfirmed.
      */
     sendText(input: AgentInput): Promise<void>;
     /**
@@ -50,5 +78,8 @@ export declare class VoiceSession {
      */
     requestAssistantTurn(request?: AssistantTurnRequest): Promise<void>;
     reportPlayout(progress: PlayoutProgress): Promise<void>;
+    /** Records local evidence even when a provider cannot consume playout acknowledgements. */
+    reportPlayoutRange(range: PlayoutRange): Promise<void>;
+    appendContext(update: ConversationContextUpdate): Promise<void>;
     close(reason?: string): Promise<void>;
 }