xo-harness 0.1.2 → 0.2.0

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

@@ -1,4 +1,11 @@
 import { ToolOutcomeSchema, } from "../protocol/index.js";
+import { z } from "zod";
+import { boundToolOutcomeForDelivery } from "./tool-delivery.js";
+import { toolDenialError } from "./tool-policy.js";
+const ToolAdmissionSchema = z.discriminatedUnion("decision", [
+    z.object({ decision: z.literal("allow") }),
+    z.object({ decision: z.literal("deny"), reason: z.string().trim().min(1) }),
+]);
 export class ToolRuntime {
     #tools;
     #tasks;
@@ -6,6 +13,9 @@ export class ToolRuntime {
     #resultSink;
     #signal;
     #flush;
+    #policy;
+    #history;
+    #maxResultBytes;
     #inFlight = new Set();
     #terminal = new Set();
     constructor(options) {
@@ -15,14 +25,27 @@ export class ToolRuntime {
         this.#resultSink = options.resultSink;
         this.#signal = options.signal;
         this.#flush = options.flush;
+        this.#policy = options.policy;
+        this.#history = options.history;
+        this.#maxResultBytes = options.maxResultBytes;
     }
     async execute(call) {
         if (this.#inFlight.has(call.callId) || this.#terminal.has(call.callId))
             return;
         this.#inFlight.add(call.callId);
         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);
+                return;
+            }
             await this.#record({ type: "tool.started", callId: call.callId, name: call.name });
             await this.#flush();
+            if (this.#signal.aborted)
+                return;
             const tool = this.#tools.get(call.name);
             if (!tool) {
                 await this.#settleFailure(call.callId, `Tool not found: ${call.name}`);
@@ -31,6 +54,8 @@ export class ToolRuntime {
             let outcome;
             try {
                 const input = await tool.input.parseAsync(call.arguments);
+                if (this.#signal.aborted)
+                    return;
                 outcome = ToolOutcomeSchema.parse(await this.#run(tool, input, call.callId));
             }
             catch (error) {
@@ -43,9 +68,46 @@ export class ToolRuntime {
             this.#inFlight.delete(call.callId);
         }
     }
+    async #admit(call) {
+        if (this.#signal.aborted)
+            return undefined;
+        const annotations = this.#tools.get(call.name)?.annotations;
+        const decision = (async () => {
+            try {
+                return ToolAdmissionSchema.parse(await this.#policy.admit({
+                    call,
+                    ...(annotations === undefined ? {} : { annotations }),
+                    signal: this.#signal,
+                    history: this.#history,
+                }));
+            }
+            catch (error) {
+                // A broken policy must not grant access; the gate fails closed with the reason.
+                return { decision: "deny", reason: `Tool policy error: ${errorMessage(error)}` };
+            }
+        })();
+        // Session close must never wait on a stalled policy (e.g. an unanswered approval
+        // round-trip). Unlike a running tool body, nothing durable has begun yet, so the
+        // 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, {
             signal: this.#signal,
+            maxResultBytes: this.#maxResultBytes,
             tasks: this.#tasks.forCall(callId),
             report: async (update) => {
                 await this.#record({ type: "tool.progress", callId, update });
@@ -80,7 +142,11 @@ export class ToolRuntime {
     }
     async #deliver(callId, outcome) {
         try {
-            await this.#resultSink.deliver({ callId, outcome });
+            // The log keeps the full outcome; only the provider-bound copy is bounded.
+            await this.#resultSink.deliver({
+                callId,
+                outcome: boundToolOutcomeForDelivery(outcome, this.#maxResultBytes),
+            });
         }
         catch (error) {
             await this.#record({ type: "tool.delivery_failed", callId, error: errorMessage(error) });
@@ -100,6 +166,21 @@ export class ToolRuntime {
         }
     }
 }
+function raceWithAbort(work, signal) {
+    if (signal.aborted)
+        return Promise.resolve(undefined);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => resolve(undefined);
+        signal.addEventListener("abort", onAbort, { once: true });
+        work.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

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

@@ -1,22 +1,43 @@
 import { type JsonValue, type ProviderToolDefinition, type ToolOutcome } from "../protocol/index.js";
 import { z } from "zod";
 export interface BackgroundTaskContext {
+    /** Runners must release their resources and settle promptly when aborted; close waits for settlement. */
     readonly signal: AbortSignal;
     report(update: JsonValue): Promise<void>;
 }
 export type BackgroundTaskRunner = (context: BackgroundTaskContext) => Promise<JsonValue>;
+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): Promise<string>;
+    start(run: BackgroundTaskRunner, options?: BackgroundTaskOptions): Promise<string>;
 }
 export interface ToolExecutionContext {
+    /** 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. */
+    readonly maxResultBytes?: number;
     readonly tasks: BackgroundTaskLauncher;
     report(update: JsonValue): Promise<void>;
 }
+/**
+ * Behavior hints consumed by tool admission policies; never sent to providers. The two
+ * hints a permission decision actually turns on, named as in MCP `ToolAnnotations` so
+ * MCP-discovered tools map onto them verbatim. Hints, not guarantees — a policy should
+ * treat a missing hint conservatively (absent `readOnlyHint` means "may mutate").
+ */
+export interface ToolAnnotations {
+    /** The tool observes without mutating its environment. */
+    readonly readOnlyHint?: boolean;
+    /** The tool may perform destructive updates (sends, deletes, spends). */
+    readonly destructiveHint?: boolean;
+}
 export interface VoiceTool<Schema extends z.ZodType = z.ZodType> {
     readonly name: string;
     readonly description: string;
     readonly input: Schema;
+    readonly annotations?: ToolAnnotations;
     execute(input: z.output<Schema>, context: ToolExecutionContext): ToolOutcome | Promise<ToolOutcome>;
 }
 export declare function defineTool<const Schema extends z.ZodType>(tool: VoiceTool<Schema>): VoiceTool<Schema>;

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

@@ -1,7 +1,8 @@
 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";
+import { type ToolPolicy } from "./tool-policy.js";
+import { ToolRegistry } from "./tools.js";
 export interface CreateVoiceSessionOptions {
     sessionId: string;
     provider: VoiceProvider;
@@ -9,6 +10,13 @@ export interface CreateVoiceSessionOptions {
     signal?: AbortSignal;
     store: EventStore;
     tools: ToolRegistry;
+    /** Admits or refuses model-requested tool calls before execution. Default: allow all. */
+    toolPolicy?: ToolPolicy;
+    /**
+     * UTF-8 JSON byte budget for a completed value or error string, excluding provider envelopes.
+     * An integer of at least 128, or Infinity (the default). The log keeps the full outcome.
+     */
+    maxToolResultBytes?: number;
     instructions?: string;
     /** What the model may produce this session; ["text"] disables audio output. Default: audio. */
     outputModalities?: readonly OutputModality[];

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

@@ -1,7 +1,10 @@
 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 { DEFAULT_MAX_TOOL_RESULT_BYTES, validateMaxToolResultBytes } from "./tool-delivery.js";
+import { allowAllToolPolicy } from "./tool-policy.js";
 import { ToolRuntime } from "./tool-runtime.js";
+import { ToolRegistry } from "./tools.js";
 export class VoiceSession {
     id;
     #providerSession;
@@ -47,9 +50,17 @@ export class VoiceSession {
             },
             signal: this.#controller.signal,
             flush: () => this.#store.flush(this.id),
+            policy: options.toolPolicy ?? allowAllToolPolicy,
+            history: () => this.#store.list(this.id),
+            maxResultBytes: options.maxToolResultBytes ?? DEFAULT_MAX_TOOL_RESULT_BYTES,
         });
     }
     static async create(options) {
+        const maxToolResultBytes = options.maxToolResultBytes ?? DEFAULT_MAX_TOOL_RESULT_BYTES;
+        validateMaxToolResultBytes(maxToolResultBytes);
+        // Registrations made after startup begins belong to future sessions. Execution
+        // must use the same catalog that this session advertises to its provider.
+        const tools = new ToolRegistry(options.tools.list());
         const existingEvents = await options.store.list(options.sessionId);
         if (existingEvents.length > 0) {
             throw new Error(`Session id already exists: ${options.sessionId}`);
@@ -80,7 +91,7 @@ export class VoiceSession {
             providerSession = await options.provider.createSession({
                 sessionId: options.sessionId,
                 signal: providerController.signal,
-                tools: options.tools.definitions(),
+                tools: tools.definitions(),
                 ...(options.instructions === undefined ? {} : { instructions: options.instructions }),
                 ...(options.outputModalities === undefined ? {} : { outputModalities: options.outputModalities }),
             });
@@ -97,7 +108,7 @@ export class VoiceSession {
             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);
+        const session = new VoiceSession({ ...options, tools, maxToolResultBytes }, providerSession, startedAt, startedEvent);
         session.#controller.signal.addEventListener("abort", () => providerController.abort(session.#controller.signal.reason), {
             once: true,
         });
@@ -228,6 +239,9 @@ export class VoiceSession {
                         // error behind per-chunk persistence.
                         this.#trackRecord(this.#record({ type: "audio.output", chunk: event.chunk }));
                         break;
+                    case "audio.interrupted":
+                        this.#trackRecord(this.#record({ type: "audio.interrupted", streamId: event.streamId }));
+                        break;
                     case "transcript":
                         await this.#record({
                             type: "transcript",
@@ -248,6 +262,12 @@ export class VoiceSession {
                         await this.#record({ type: "tool.requested", call: event.call });
                         this.#trackToolExecution(this.#toolRuntime.execute(event.call));
                         break;
+                    case "response.state":
+                        await this.#record(event);
+                        break;
+                    case "diagnostic":
+                        await this.#record({ type: "provider.diagnostic", diagnostic: event.diagnostic });
+                        break;
                     case "usage": {
                         const { type: _type, ...usage } = event;
                         await this.#record({ type: "usage", ...usage });

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

@@ -1,17 +1,29 @@
 import type { OutputModality } from "../protocol/index.js";
 import type { VoiceProvider } from "../provider/index.js";
 import type { EventStore } from "../storage/index.js";
+import type { ToolPolicy } from "./tool-policy.js";
 import { ToolRegistry, type VoiceTool } from "./tools.js";
 import { VoiceSession } from "./voice-session.js";
 export interface XOOptions {
     store: EventStore;
     tools?: readonly VoiceTool[];
+    /** Admits or refuses model-requested tool calls before execution. Default: allow all. */
+    toolPolicy?: ToolPolicy;
+    /**
+     * UTF-8 JSON byte budget for a completed value or error string, excluding provider envelopes.
+     * An integer of at least 128, or Infinity (the default). The log keeps the full outcome.
+     */
+    maxToolResultBytes?: number;
 }
 export interface StartSessionOptions {
     provider: VoiceProvider;
     /** Cancels provider startup and closes the live session when its owner is revoked. */
     signal?: AbortSignal;
     sessionId?: string;
+    /** Overrides the harness-level tool policy for this session. */
+    toolPolicy?: ToolPolicy;
+    /** Overrides the harness-level delivery budget for this session. */
+    maxToolResultBytes?: number;
     instructions?: string;
     /** What the model may produce this session; ["text"] disables audio output. Default: audio. */
     outputModalities?: readonly OutputModality[];
@@ -19,6 +31,7 @@ export interface StartSessionOptions {
     maxDurationMs?: number;
 }
 export declare class XO {
+    #private;
     readonly store: EventStore;
     readonly tools: ToolRegistry;
     constructor(options: XOOptions);

package/dist/internal/harness/xo.js

@@ -3,20 +3,28 @@ import { VoiceSession } from "./voice-session.js";
 export class XO {
     store;
     tools;
+    #toolPolicy;
+    #maxToolResultBytes;
     constructor(options) {
         this.store = options.store;
         this.tools = new ToolRegistry(options.tools);
+        this.#toolPolicy = options.toolPolicy;
+        this.#maxToolResultBytes = options.maxToolResultBytes;
     }
     registerTool(tool) {
         this.tools.register(tool);
     }
     startSession(options) {
+        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 }),

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

@@ -24,6 +24,7 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         supportsToolCalls: z.ZodBoolean;
         supportsAsyncContext: z.ZodBoolean;
         supportsPlayoutAcknowledgements: z.ZodBoolean;
+        reportsResponseState: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     instructions: z.ZodOptional<z.ZodString>;
     outputModalities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
@@ -49,6 +50,55 @@ 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<"response.state">;
+    state: z.ZodEnum<{
+        idle: "idle";
+        pending: "pending";
+    }>;
+}, 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.diagnostic">;
+    diagnostic: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"session">;
+        model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"speech">;
+        phase: z.ZodEnum<{
+            started: "started";
+            stopped: "stopped";
+        }>;
+        streamId: z.ZodOptional<z.ZodString>;
+        audioOffsetMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"response">;
+        phase: z.ZodEnum<{
+            completed: "completed";
+            started: "started";
+        }>;
+        responseId: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        outputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            streamId: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+            contentTypes: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>], "kind">;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     sessionId: z.ZodString;
@@ -138,6 +188,16 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         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.interrupted">;
+    streamId: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     role: z.ZodEnum<{
         assistant: "assistant";
@@ -209,6 +269,18 @@ export declare const HarnessEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         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.denied">;
+    callId: z.ZodString;
+    name: 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,7 @@
 import { z } from "zod";
 import { AudioChunkSchema } from "./audio.js";
 import { InputPartSchema } from "./parts.js";
-import { OutputModalitySchema, ProviderCapabilitiesSchema, TranscriptDeltaPayloadSchema, TranscriptPayloadSchema, UsagePayloadSchema, } from "./provider.js";
+import { OutputModalitySchema, ProviderCapabilitiesSchema, ProviderDiagnosticSchema, ResponseStateSchema, 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);
@@ -34,6 +34,10 @@ 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") }),
+    /** Optional provider generation state; never a gate on audio or background work. */
+    EventBaseSchema.extend({ type: z.literal("response.state"), state: ResponseStateSchema }),
+    /** Allow-listed provider observation for explaining response and speech behavior. */
+    EventBaseSchema.extend({ type: z.literal("provider.diagnostic"), diagnostic: ProviderDiagnosticSchema }),
     /** 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. */
@@ -58,6 +62,8 @@ export const HarnessEventSchema = z.discriminatedUnion("type", [
     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 }),
+    /** 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. */
@@ -72,6 +78,13 @@ export const HarnessEventSchema = z.discriminatedUnion("type", [
     }),
     /** The model asked for a tool; recorded before execution begins. */
     EventBaseSchema.extend({ type: z.literal("tool.requested"), call: ToolCallSchema }),
+    /** The admission policy refused a requested tool; execution never began. Terminal for the call. */
+    EventBaseSchema.extend({
+        type: z.literal("tool.denied"),
+        callId: z.string().min(1),
+        name: z.string().min(1),
+        reason: z.string().min(1),
+    }),
     /** Local execution of a requested tool has begun. */
     EventBaseSchema.extend({
         type: z.literal("tool.started"),

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

@@ -9,6 +9,7 @@ export declare const ProviderCapabilitiesSchema: z.ZodObject<{
     supportsToolCalls: z.ZodBoolean;
     supportsAsyncContext: z.ZodBoolean;
     supportsPlayoutAcknowledgements: z.ZodBoolean;
+    reportsResponseState: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ProviderCapabilities = z.infer<typeof ProviderCapabilitiesSchema>;
 export declare const PlayoutProgressSchema: z.ZodObject<{
@@ -55,7 +56,7 @@ export declare const TranscriptPayloadSchema: z.ZodObject<{
     streamId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type TranscriptPayload = z.infer<typeof TranscriptPayloadSchema>;
-/** Incremental assistant text as the model streams it; finalized by a `transcript`. */
+/** Incremental text from either speaker; finalized by a matching `transcript`. */
 export declare const TranscriptDeltaPayloadSchema: z.ZodObject<{
     role: z.ZodEnum<{
         assistant: "assistant";
@@ -65,13 +66,91 @@ export declare const TranscriptDeltaPayloadSchema: z.ZodObject<{
     streamId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type TranscriptDeltaPayload = z.infer<typeof TranscriptDeltaPayloadSchema>;
+/** Generation state only: idle says nothing about buffered audio playback or background tasks. */
+export declare const ResponseStateSchema: z.ZodEnum<{
+    idle: "idle";
+    pending: "pending";
+}>;
+export type ResponseState = z.infer<typeof ResponseStateSchema>;
+/** Limits optional provider diagnostics so inspection artifacts stay bounded. */
+export declare const PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH = 256;
+export declare const PROVIDER_DIAGNOSTIC_MAX_OUTPUTS = 32;
+export declare const PROVIDER_DIAGNOSTIC_MAX_CONTENT_TYPES = 16;
+/**
+ * Bounded, allow-listed provider observations for diagnosing a silent turn. These
+ * facts are never used to schedule media or model work, and intentionally exclude
+ * vendor payloads, reasoning, credentials, and content text.
+ */
+export declare const ProviderDiagnosticSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"session">;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"speech">;
+    phase: z.ZodEnum<{
+        started: "started";
+        stopped: "stopped";
+    }>;
+    streamId: z.ZodOptional<z.ZodString>;
+    audioOffsetMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"response">;
+    phase: z.ZodEnum<{
+        completed: "completed";
+        started: "started";
+    }>;
+    responseId: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    outputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        streamId: z.ZodOptional<z.ZodString>;
+        type: z.ZodString;
+        contentTypes: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>], "kind">;
+export type ProviderDiagnostic = z.infer<typeof ProviderDiagnosticSchema>;
 /**
  * What a provider adapter yields to the harness. Deliberately minimal: adapters
- * translate vendor wire dialects into these eight shapes, and the harness turns them
+ * translate vendor wire dialects into these shapes, and the harness turns them
  * into HarnessEvents. Anything not expressible here does not exist to the harness.
  */
 export declare const ProviderEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"ready">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"response.state">;
+    state: z.ZodEnum<{
+        idle: "idle";
+        pending: "pending";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"diagnostic">;
+    diagnostic: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"session">;
+        model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"speech">;
+        phase: z.ZodEnum<{
+            started: "started";
+            stopped: "stopped";
+        }>;
+        streamId: z.ZodOptional<z.ZodString>;
+        audioOffsetMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"response">;
+        phase: z.ZodEnum<{
+            completed: "completed";
+            started: "started";
+        }>;
+        responseId: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+        outputs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            streamId: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+            contentTypes: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>], "kind">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"audio.output">;
     chunk: z.ZodObject<{
@@ -83,6 +162,9 @@ export declare const ProviderEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         startSample: z.ZodInt;
         data: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"audio.interrupted">;
+    streamId: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     role: z.ZodEnum<{
         assistant: "assistant";