xo-harness 0.1.2 → 0.2.0

package/dist/internal/protocol/provider.js

@@ -15,6 +15,8 @@ export const ProviderCapabilitiesSchema = z.object({
     supportsAsyncContext: z.boolean(),
     /** Honors playout acknowledgements for truncation-accurate barge-in. */
     supportsPlayoutAcknowledgements: z.boolean(),
+    /** Emits response.state for pending generation and queued continuations. Optional for continuous models. */
+    reportsResponseState: z.boolean().optional(),
 });
 export const PlayoutProgressSchema = z.object({
     streamId: z.string().min(1),
@@ -50,25 +52,71 @@ export const TranscriptPayloadSchema = z.object({
     text: z.string().min(1),
     streamId: z.string().min(1).optional(),
 });
-/** Incremental assistant text as the model streams it; finalized by a `transcript`. */
+/** Incremental text from either speaker; finalized by a matching `transcript`. */
 export const TranscriptDeltaPayloadSchema = z.object({
     role: z.enum(["user", "assistant"]),
     delta: z.string().min(1),
     streamId: z.string().min(1).optional(),
 });
+/** Generation state only: idle says nothing about buffered audio playback or background tasks. */
+export const ResponseStateSchema = z.enum(["pending", "idle"]);
+/** Limits optional provider diagnostics so inspection artifacts stay bounded. */
+export const PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH = 256;
+export const PROVIDER_DIAGNOSTIC_MAX_OUTPUTS = 32;
+export const PROVIDER_DIAGNOSTIC_MAX_CONTENT_TYPES = 16;
+const ProviderDiagnosticStringSchema = z.string().min(1).max(PROVIDER_DIAGNOSTIC_STRING_MAX_LENGTH);
+/**
+ * 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 const ProviderDiagnosticSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("session"),
+        model: ProviderDiagnosticStringSchema.optional(),
+    }),
+    z.object({
+        kind: z.literal("speech"),
+        phase: z.enum(["started", "stopped"]),
+        streamId: ProviderDiagnosticStringSchema.optional(),
+        audioOffsetMs: z.number().nonnegative().optional(),
+    }),
+    z.object({
+        kind: z.literal("response"),
+        phase: z.enum(["started", "completed"]),
+        responseId: ProviderDiagnosticStringSchema.optional(),
+        status: ProviderDiagnosticStringSchema.optional(),
+        reason: ProviderDiagnosticStringSchema.optional(),
+        /** A bounded provider error code, when response status reports one. */
+        code: ProviderDiagnosticStringSchema.optional(),
+        outputs: z
+            .array(z.object({
+            streamId: ProviderDiagnosticStringSchema.optional(),
+            type: ProviderDiagnosticStringSchema,
+            contentTypes: z.array(ProviderDiagnosticStringSchema).max(PROVIDER_DIAGNOSTIC_MAX_CONTENT_TYPES),
+        }))
+            .max(PROVIDER_DIAGNOSTIC_MAX_OUTPUTS)
+            .optional(),
+    }),
+]);
 /**
  * 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 const ProviderEventSchema = z.discriminatedUnion("type", [
     /** Session configuration acknowledged; the model is listening. */
     z.object({ type: z.literal("ready") }),
+    z.object({ type: z.literal("response.state"), state: ResponseStateSchema }),
+    /** Optional allow-listed diagnostics for explaining provider behavior after the fact. */
+    z.object({ type: z.literal("diagnostic"), diagnostic: ProviderDiagnosticSchema }),
     /** Model speech as sample-addressed PCM. */
     z.object({ type: z.literal("audio.output"), chunk: AudioChunkSchema }),
+    /** Clear queued playback for this stream and ignore its subsequent audio chunks. */
+    z.object({ type: z.literal("audio.interrupted"), streamId: z.string().min(1) }),
     /** Final transcript text for either role. */
     TranscriptPayloadSchema.extend({ type: z.literal("transcript") }),
-    /** Incremental assistant text; assembled into a streaming text part. */
+    /** Incremental text from either speaker; assembled into a streaming text part. */
     TranscriptDeltaPayloadSchema.extend({ type: z.literal("transcript.delta") }),
     /** The model requested a tool invocation. */
     z.object({ type: z.literal("tool.call"), call: ToolCallSchema }),

package/dist/internal/provider/grok-voice.d.ts

@@ -39,6 +39,7 @@ export declare class GrokVoiceProvider implements VoiceProvider {
         readonly supportsToolCalls: true;
         readonly supportsAsyncContext: true;
         readonly supportsPlayoutAcknowledgements: true;
+        readonly reportsResponseState: true;
     };
     constructor(options: GrokVoiceProviderOptions);
     createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;

package/dist/internal/provider/grok-voice.js

@@ -22,6 +22,7 @@ export class GrokVoiceProvider {
         supportsToolCalls: true,
         supportsAsyncContext: true,
         supportsPlayoutAcknowledgements: true,
+        reportsResponseState: true,
     };
     #options;
     constructor(options) {
@@ -41,10 +42,13 @@ export class GrokVoiceProvider {
         });
         return new RealtimeVoiceSession(socket, {
             label: "Grok voice",
+            inputTranscriptSettleMs: 300,
             sessionUpdate: this.#sessionUpdate(options, inputSampleRate),
             inputSampleRate,
             outputSampleRate: DEFAULT_SAMPLE_RATE,
             announceTaskSettlement: this.#options.announceTaskSettlement ?? true,
+            autoRespondToAudio: this.#options.turnDetection !== null && this.#options.turnDetection?.create_response !== false,
+            interruptOnSpeech: this.#options.turnDetection !== null && this.#options.turnDetection?.interrupt_response !== false,
         }, options);
     }
     #sessionUpdate(options, inputSampleRate) {

package/dist/internal/provider/openai-realtime.d.ts

@@ -12,10 +12,18 @@ export interface OpenAIRealtimeProviderOptions {
     voice?: string;
     /** Sample rate of the PCM16 mono input the harness will send. */
     inputSampleRate?: number;
+    /** Input filtering before VAD/model processing. Omitted keeps the API default; null disables it. */
+    noiseReduction?: "near_field" | "far_field" | null;
     /** Server-side turn detection. Defaults to semantic VAD; null disables it for push-to-talk. */
     turnDetection?: Record<string, unknown> | null;
-    /** Input transcription model; final transcripts surface as transcript events. Null disables. */
+    /** Input transcription model; partial/final text surfaces as transcript.delta/transcript. Null disables. */
     transcriptionModel?: string | null;
+    /** Optional ISO-639-1 input language hint, e.g. cs or en. Omitted means automatic detection. */
+    transcriptionLanguage?: string;
+    /** Latency/accuracy tradeoff for gpt-live-transcribe. */
+    transcriptionDelay?: "minimal" | "low" | "medium" | "high" | "xhigh";
+    /** Realtime 2 reasoning/latency tradeoff. Omitted leaves the model default intact. */
+    reasoningEffort?: "minimal" | "low" | "medium" | "high" | "xhigh";
     /** Request a spoken response when a background task settles. */
     announceTaskSettlement?: boolean;
     handshakeTimeoutMs?: number;
@@ -37,6 +45,7 @@ export declare class OpenAIRealtimeVoiceProvider implements VoiceProvider {
         readonly supportsToolCalls: true;
         readonly supportsAsyncContext: true;
         readonly supportsPlayoutAcknowledgements: true;
+        readonly reportsResponseState: true;
     };
     constructor(options: OpenAIRealtimeProviderOptions);
     createSession(options: CreateProviderSessionOptions): Promise<VoiceProviderSession>;

package/dist/internal/provider/openai-realtime.js

@@ -21,6 +21,7 @@ export class OpenAIRealtimeVoiceProvider {
         supportsToolCalls: true,
         supportsAsyncContext: true,
         supportsPlayoutAcknowledgements: true,
+        reportsResponseState: true,
     };
     #options;
     constructor(options) {
@@ -45,6 +46,8 @@ export class OpenAIRealtimeVoiceProvider {
             inputSampleRate,
             outputSampleRate: DEFAULT_SAMPLE_RATE,
             announceTaskSettlement: this.#options.announceTaskSettlement ?? true,
+            autoRespondToAudio: this.#options.turnDetection !== null && this.#options.turnDetection?.create_response !== false,
+            interruptOnSpeech: this.#options.turnDetection !== null && this.#options.turnDetection?.interrupt_response !== false,
         }, options);
     }
     #sessionUpdate(options, inputSampleRate) {
@@ -60,7 +63,26 @@ export class OpenAIRealtimeVoiceProvider {
                 input: {
                     format: { type: "audio/pcm", rate: inputSampleRate },
                     turn_detection: turnDetection,
-                    ...(transcriptionModel === null ? {} : { transcription: { model: transcriptionModel } }),
+                    ...(this.#options.noiseReduction === undefined
+                        ? {}
+                        : {
+                            noise_reduction: this.#options.noiseReduction === null ? null : { type: this.#options.noiseReduction },
+                        }),
+                    ...(transcriptionModel === null
+                        ? {}
+                        : {
+                            transcription: {
+                                model: transcriptionModel,
+                                ...(this.#options.transcriptionLanguage === undefined
+                                    ? {}
+                                    : transcriptionModel.startsWith("gpt-live-transcribe")
+                                        ? { languages: [this.#options.transcriptionLanguage] }
+                                        : { language: this.#options.transcriptionLanguage }),
+                                ...(this.#options.transcriptionDelay === undefined
+                                    ? {}
+                                    : { delay: this.#options.transcriptionDelay }),
+                            },
+                        }),
                 },
                 output: {
                     format: { type: "audio/pcm", rate: DEFAULT_SAMPLE_RATE },
@@ -71,6 +93,9 @@ export class OpenAIRealtimeVoiceProvider {
         };
         if (options.instructions !== undefined)
             session.instructions = options.instructions;
+        if (this.#options.reasoningEffort !== undefined) {
+            session.reasoning = { effort: this.#options.reasoningEffort };
+        }
         return session;
     }
 }

package/dist/internal/provider/realtime-session.d.ts

@@ -15,6 +15,12 @@ export interface RealtimeWireOptions {
     inputSampleRate: number;
     outputSampleRate: number;
     announceTaskSettlement: boolean;
+    /** VAD will create a response after the user's speech; coalesce tool continuations into it. */
+    autoRespondToAudio: boolean;
+    /** Follow the provider's VAD interruption setting. Defaults to true. */
+    interruptOnSpeech?: boolean;
+    /** xAI sends revisions through its completed event; other providers settle immediately. */
+    inputTranscriptSettleMs?: number;
 }
 export declare class RealtimeVoiceSession implements VoiceProviderSession {
     #private;