agent-voice 0.2.1 → 0.2.2

package/dist/{ask-A32EH5QX.js → ask-OIE6HL2H.js}

@@ -10,22 +10,38 @@ import {
 // src/ask.ts
 import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
+function pcm16Rms(pcm16) {
+  const samples = Math.floor(pcm16.length / 2);
+  if (samples === 0) return 0;
+  let sumSquares = 0;
+  for (let i = 0; i < samples; i++) {
+    const value = pcm16.readInt16LE(i * 2);
+    sumSquares += value * value;
+  }
+  return Math.sqrt(sumSquares / samples);
+}
+function readEnvInt(name, fallback) {
+  const raw = process.env[name];
+  if (raw == null) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
 async function ask(message, options = {}) {
   const {
     voice = DEFAULT_VOICE,
     timeout = 30,
     ack = false,
     auth,
+    createSession,
+    createAudioEngine,
+    onTrace,
     onAudioFrameSent,
     onAssistantAudio,
     onMicAudio
   } = options;
   const { AudioEngine } = require2("agent-voice-audio");
-  const streamDelayMs = Number.parseInt(
-    process.env.AGENT_VOICE_AEC_STREAM_DELAY_MS ?? "30",
-    10
-  );
-  const engine = new AudioEngine({
+  const streamDelayMs = readEnvInt("AGENT_VOICE_AEC_STREAM_DELAY_MS", 30);
+  const engine = (createAudioEngine ?? ((engineOptions) => new AudioEngine(engineOptions)))({
     sampleRate: SAMPLE_RATE,
     channels: 1,
     enableAec: true,
@@ -41,7 +57,11 @@ async function ask(message, options = {}) {
     process.stderr.write(`[ask ${elapsed}ms] ${event}${suffix}
 `);
   }
+  function trace(event, detail) {
+    onTrace?.({ atMs: Date.now() - startMs, event, detail });
+  }
   logEvent("start");
+  trace("start");
   return new Promise((resolve, reject) => {
     let transcript = "";
     let timeoutTimer = null;
@@ -49,15 +69,19 @@ async function ask(message, options = {}) {
     let transcriptTimer = null;
     let capturePollTimer = null;
     let speechDetected = false;
+    let speechStartedAtMs = 0;
     let initialResponseDone = false;
     let heardAssistantAudio = false;
     let lastAssistantAudioAt = 0;
+    let nearEndEvidenceSeen = false;
+    let nearEndEvidenceAtMs = 0;
     let cleaned = false;
     let settled = false;
     async function cleanup() {
       if (cleaned) return;
       cleaned = true;
       logEvent("cleanup:start");
+      trace("cleanup:start");
       if (timeoutTimer) clearTimeout(timeoutTimer);
       if (responseStartTimer) clearTimeout(responseStartTimer);
       if (transcriptTimer) clearTimeout(transcriptTimer);
@@ -69,6 +93,7 @@ async function ask(message, options = {}) {
       }
       session.close();
       logEvent("cleanup:done");
+      trace("cleanup:done");
     }
     function resolveOnce(value) {
       if (settled) return;
@@ -93,41 +118,75 @@ async function ask(message, options = {}) {
             `audio engine capture read failed: ${err instanceof Error ? err.message : String(err)}`
           )
         );
+        trace("audio:capture_read_error", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         return;
       }
       for (const frame of rawFrames) onMicAudio?.(frame);
       if (!heardAssistantAudio) return;
       for (const frame of processedFrames) {
+        const rms = pcm16Rms(frame);
+        const minSpeechRms = readEnvInt("AGENT_VOICE_MIN_SPEECH_RMS", 550);
+        if (rms >= minSpeechRms) {
+          nearEndEvidenceSeen = true;
+          nearEndEvidenceAtMs = Date.now();
+          trace("audio:near_end_evidence", { rms, minSpeechRms });
+        }
         onAudioFrameSent?.(frame);
         session.sendAudio(frame);
       }
+      if (processedFrames.length > 0) {
+        trace("audio:sent_capture", { frames: processedFrames.length });
+      }
     }, 10);
-    const session = createRealtimeSession({
+    const session = (createSession ?? createRealtimeSession)({
       voice,
       mode: "default",
       ack,
       auth,
       onAudioDelta(pcm16) {
         logEvent("realtime:audio_delta", `bytes=${pcm16.length}`);
+        trace("realtime:audio_delta", { bytes: pcm16.length });
         heardAssistantAudio = true;
         lastAssistantAudioAt = Date.now();
         onAssistantAudio?.(pcm16);
         engine.play(pcm16);
       },
       onTranscript(text) {
-        const echoGuardMs = Number.parseInt(
-          process.env.AGENT_VOICE_ECHO_GUARD_MS ?? "1500",
-          10
-        );
+        const echoGuardMs = readEnvInt("AGENT_VOICE_ECHO_GUARD_MS", 1500);
         const sinceAssistantMs = Date.now() - lastAssistantAudioAt;
         if (heardAssistantAudio && sinceAssistantMs < echoGuardMs) {
           logEvent(
             "realtime:transcript_ignored_echo_guard",
             `since_assistant_ms=${sinceAssistantMs} text="${text}"`
           );
+          trace("realtime:transcript_ignored_echo_guard", {
+            sinceAssistantMs,
+            text
+          });
           return;
         }
         logEvent("realtime:transcript", `text="${text}"`);
+        trace("realtime:transcript", { text });
+        if (speechDetected) {
+          const evidenceWindowMs = readEnvInt(
+            "AGENT_VOICE_SPEECH_EVIDENCE_WINDOW_MS",
+            1200
+          );
+          const evidenceAgeMs = nearEndEvidenceSeen ? Math.abs(nearEndEvidenceAtMs - speechStartedAtMs) : Number.POSITIVE_INFINITY;
+          if (!nearEndEvidenceSeen || evidenceAgeMs > evidenceWindowMs) {
+            trace("realtime:transcript_ignored_no_near_end_evidence", {
+              text,
+              speechStartedAtMs,
+              nearEndEvidenceSeen,
+              nearEndEvidenceAtMs,
+              evidenceAgeMs,
+              evidenceWindowMs
+            });
+            return;
+          }
+        }
         if (transcriptTimer) {
           clearTimeout(transcriptTimer);
           transcriptTimer = null;
@@ -137,7 +196,9 @@ async function ask(message, options = {}) {
       },
       onSpeechStarted() {
         logEvent("realtime:speech_started");
+        trace("realtime:speech_started");
         speechDetected = true;
+        speechStartedAtMs = Date.now();
         if (timeoutTimer) {
           clearTimeout(timeoutTimer);
           timeoutTimer = null;
@@ -145,6 +206,9 @@ async function ask(message, options = {}) {
         if (transcriptTimer) clearTimeout(transcriptTimer);
         transcriptTimer = setTimeout(() => {
           logEvent("timeout:no_transcript_after_speech");
+          trace("timeout:no_transcript_after_speech", {
+            timeoutSeconds: timeout
+          });
           rejectOnce(
             new Error(
               `No transcript received within ${timeout}s after speech started`
@@ -160,10 +224,12 @@ async function ask(message, options = {}) {
       },
       onInitialResponseDone() {
         logEvent("realtime:initial_response_done");
+        trace("realtime:initial_response_done");
         initialResponseDone = true;
         timeoutTimer = setTimeout(() => {
           if (!speechDetected) {
             logEvent("timeout:no_speech");
+            trace("timeout:no_speech", { timeoutSeconds: timeout });
             rejectOnce(
               new Error(`No speech detected within ${timeout}s timeout`)
             );
@@ -172,21 +238,26 @@ async function ask(message, options = {}) {
       },
       onDone() {
         logEvent("realtime:done");
+        trace("realtime:done");
         if (ack) resolveOnce(transcript);
       },
       onError(error) {
         logEvent("realtime:error", error);
+        trace("realtime:error", { error });
         rejectOnce(new Error(error));
       }
     });
     session.connect().then(
       () => {
         logEvent("realtime:connected");
+        trace("realtime:connected");
         logEvent("realtime:send_message");
+        trace("realtime:send_message");
         session.sendMessage(message);
         responseStartTimer = setTimeout(() => {
           if (!heardAssistantAudio) {
             logEvent("timeout:no_assistant_audio");
+            trace("timeout:no_assistant_audio");
             rejectOnce(
               new Error("No assistant audio received after sending message")
             );
@@ -198,6 +269,9 @@ async function ask(message, options = {}) {
           "realtime:connect_error",
           err instanceof Error ? err.message : String(err)
         );
+        trace("realtime:connect_error", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         rejectOnce(err instanceof Error ? err : new Error(String(err)));
       }
     );

package/dist/cli.js

@@ -12,7 +12,13 @@ import {
 } from "./chunk-AHLLYIEW.js";
 
 // src/cli.ts
-import { closeSync, mkdirSync, openSync, writeFileSync, writeSync } from "fs";
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  writeFileSync,
+  writeSync
+} from "fs";
 import { join } from "path";
 import { Command } from "commander";
 async function withSuppressedNativeOutput() {
@@ -22,8 +28,8 @@ async function withSuppressedNativeOutput() {
   openSync("/dev/null", "w");
   closeSync(2);
   openSync("/dev/null", "w");
-  const { ask } = await import("./ask-A32EH5QX.js");
-  const { say } = await import("./say-ELJAIWUM.js");
+  const { ask } = await import("./ask-OIE6HL2H.js");
+  const { say } = await import("./say-ZVF6EX52.js");
   function writeResult(text) {
     writeSync(savedStdout, `${text}
 `);
@@ -78,7 +84,10 @@ function writeDebugAudio(dir, assistantChunks, micChunks, modelInputChunks) {
   const modelInputFile = join(dir, `ask-${stamp}-model-input.wav`);
   writeFileSync(assistantFile, createWavBuffer(Buffer.concat(assistantChunks)));
   writeFileSync(micFile, createWavBuffer(Buffer.concat(micChunks)));
-  writeFileSync(modelInputFile, createWavBuffer(Buffer.concat(modelInputChunks)));
+  writeFileSync(
+    modelInputFile,
+    createWavBuffer(Buffer.concat(modelInputChunks))
+  );
   return { assistantFile, micFile, modelInputFile };
 }
 var program = new Command().name("agent-voice").description("AI agent voice interaction CLI");
@@ -120,7 +129,10 @@ voicesCmd.command("set <voice>").description("Set the default voice").action((vo
 `);
   process.exit(0);
 });
-program.command("ask").description("Speak a message and listen for a response").option("-m, --message <text>", "Text message to speak").option("--voice <name>", "OpenAI voice", defaultVoice).option("--timeout <seconds>", "Seconds to wait for user speech", "120").option("--ack", "Speak an acknowledgment after the user responds").option("--debug-audio-dir <dir>", "Write ask audio debug WAVs to this directory").action(async (opts) => {
+program.command("ask").description("Speak a message and listen for a response").option("-m, --message <text>", "Text message to speak").option("--voice <name>", "OpenAI voice", defaultVoice).option("--timeout <seconds>", "Seconds to wait for user speech", "120").option("--ack", "Speak an acknowledgment after the user responds").option(
+  "--debug-audio-dir <dir>",
+  "Write ask audio debug WAVs to this directory"
+).action(async (opts) => {
   const { ask, writeResult, writeError } = await withSuppressedNativeOutput();
   const assistantChunks = [];
   const micChunks = [];

package/dist/index.d.ts

@@ -5,11 +5,65 @@ type AuthConfig = {
 declare function resolveAuth(): AuthConfig;
 declare function resolveVoice(): string;
 
+declare const VOICES: readonly ["alloy", "ash", "ballad", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer", "verse"];
+type Voice = (typeof VOICES)[number];
+declare const DEFAULT_VOICE: Voice;
+type Mode = "default" | "say";
+
+type RealtimeSessionOptions = {
+    voice: string;
+    mode: Mode;
+    ack: boolean;
+    auth?: AuthConfig;
+    onAudioDelta: (pcm16: Buffer) => void;
+    onAudioDone?: () => void;
+    onTranscript: (text: string) => void;
+    onSpeechStarted: () => void;
+    onInitialResponseDone: () => void;
+    onDone: () => void;
+    onError: (error: string) => void;
+};
+type RealtimeSession = {
+    connect(): Promise<void>;
+    sendMessage(text: string): void;
+    sendAudio(pcm16: Buffer): void;
+    close(): void;
+};
+
+type RustAudioEngine$1 = {
+    start(): void;
+    stop(): void;
+    close(): void;
+    play(pcm16: Buffer): void;
+    readProcessedCapture(maxFrames?: number): Buffer[];
+    readRawCapture(maxFrames?: number): Buffer[];
+    setStreamDelayMs(delayMs: number): void;
+    getStats(): {
+        captureFrames: number;
+        processedFrames: number;
+        playbackUnderruns: number;
+        droppedRawFrames: number;
+        droppedProcessedFrames: number;
+    };
+};
 type AskOptions = {
     voice?: string;
     timeout?: number;
     ack?: boolean;
     auth?: AuthConfig;
+    createSession?: (options: RealtimeSessionOptions) => RealtimeSession;
+    createAudioEngine?: (options: {
+        sampleRate?: number;
+        channels?: number;
+        enableAec?: boolean;
+        streamDelayMs?: number;
+        maxCaptureFrames?: number;
+    }) => RustAudioEngine$1;
+    onTrace?: (event: {
+        atMs: number;
+        event: string;
+        detail?: Record<string, unknown>;
+    }) => void;
     createPlayer?: unknown;
     createRecorder?: unknown;
     onAudioFrameSent?: (pcm16: Buffer) => void;
@@ -18,15 +72,32 @@ type AskOptions = {
 };
 declare function ask(message: string, options?: AskOptions): Promise<string>;
 
+type RustAudioEngine = {
+    start(): void;
+    stop(): void;
+    close(): void;
+    play(pcm16: Buffer): void;
+    getStats?(): {
+        pendingPlaybackSamples?: number;
+    };
+};
 type SayOptions = {
     voice?: string;
     auth?: AuthConfig;
+    createSession?: (options: RealtimeSessionOptions) => RealtimeSession;
+    createAudioEngine?: (options: {
+        sampleRate?: number;
+        channels?: number;
+        enableAec?: boolean;
+        streamDelayMs?: number;
+    }) => RustAudioEngine;
+    onTrace?: (event: {
+        atMs: number;
+        event: string;
+        detail?: Record<string, unknown>;
+    }) => void;
     createPlayer?: unknown;
 };
 declare function say(message: string, options?: SayOptions): Promise<void>;
 
-declare const VOICES: readonly ["alloy", "ash", "ballad", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer", "verse"];
-type Voice = (typeof VOICES)[number];
-declare const DEFAULT_VOICE: Voice;
-
 export { type AskOptions, type AuthConfig, DEFAULT_VOICE, type SayOptions, VOICES, type Voice, ask, resolveAuth, resolveVoice, say };

package/dist/index.js

@@ -132,22 +132,38 @@ var DEFAULT_VOICE = "ash";
 
 // src/ask.ts
 var require2 = createRequire(import.meta.url);
+function pcm16Rms(pcm16) {
+  const samples = Math.floor(pcm16.length / 2);
+  if (samples === 0) return 0;
+  let sumSquares = 0;
+  for (let i = 0; i < samples; i++) {
+    const value = pcm16.readInt16LE(i * 2);
+    sumSquares += value * value;
+  }
+  return Math.sqrt(sumSquares / samples);
+}
+function readEnvInt(name, fallback) {
+  const raw = process.env[name];
+  if (raw == null) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
 async function ask(message, options = {}) {
   const {
     voice = DEFAULT_VOICE,
     timeout = 30,
     ack = false,
     auth,
+    createSession,
+    createAudioEngine,
+    onTrace,
     onAudioFrameSent,
     onAssistantAudio,
     onMicAudio
   } = options;
   const { AudioEngine } = require2("agent-voice-audio");
-  const streamDelayMs = Number.parseInt(
-    process.env.AGENT_VOICE_AEC_STREAM_DELAY_MS ?? "30",
-    10
-  );
-  const engine = new AudioEngine({
+  const streamDelayMs = readEnvInt("AGENT_VOICE_AEC_STREAM_DELAY_MS", 30);
+  const engine = (createAudioEngine ?? ((engineOptions) => new AudioEngine(engineOptions)))({
     sampleRate: SAMPLE_RATE,
     channels: 1,
     enableAec: true,
@@ -163,7 +179,11 @@ async function ask(message, options = {}) {
     process.stderr.write(`[ask ${elapsed}ms] ${event}${suffix}
 `);
   }
+  function trace(event, detail) {
+    onTrace?.({ atMs: Date.now() - startMs, event, detail });
+  }
   logEvent("start");
+  trace("start");
   return new Promise((resolve, reject) => {
     let transcript = "";
     let timeoutTimer = null;
@@ -171,15 +191,19 @@ async function ask(message, options = {}) {
     let transcriptTimer = null;
     let capturePollTimer = null;
     let speechDetected = false;
+    let speechStartedAtMs = 0;
     let initialResponseDone = false;
     let heardAssistantAudio = false;
     let lastAssistantAudioAt = 0;
+    let nearEndEvidenceSeen = false;
+    let nearEndEvidenceAtMs = 0;
     let cleaned = false;
     let settled = false;
     async function cleanup() {
       if (cleaned) return;
       cleaned = true;
       logEvent("cleanup:start");
+      trace("cleanup:start");
       if (timeoutTimer) clearTimeout(timeoutTimer);
       if (responseStartTimer) clearTimeout(responseStartTimer);
       if (transcriptTimer) clearTimeout(transcriptTimer);
@@ -191,6 +215,7 @@ async function ask(message, options = {}) {
       }
       session.close();
       logEvent("cleanup:done");
+      trace("cleanup:done");
     }
     function resolveOnce(value) {
       if (settled) return;
@@ -215,41 +240,75 @@ async function ask(message, options = {}) {
             `audio engine capture read failed: ${err instanceof Error ? err.message : String(err)}`
           )
         );
+        trace("audio:capture_read_error", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         return;
       }
       for (const frame of rawFrames) onMicAudio?.(frame);
       if (!heardAssistantAudio) return;
       for (const frame of processedFrames) {
+        const rms = pcm16Rms(frame);
+        const minSpeechRms = readEnvInt("AGENT_VOICE_MIN_SPEECH_RMS", 550);
+        if (rms >= minSpeechRms) {
+          nearEndEvidenceSeen = true;
+          nearEndEvidenceAtMs = Date.now();
+          trace("audio:near_end_evidence", { rms, minSpeechRms });
+        }
         onAudioFrameSent?.(frame);
         session.sendAudio(frame);
       }
+      if (processedFrames.length > 0) {
+        trace("audio:sent_capture", { frames: processedFrames.length });
+      }
     }, 10);
-    const session = createRealtimeSession({
+    const session = (createSession ?? createRealtimeSession)({
       voice,
       mode: "default",
       ack,
       auth,
       onAudioDelta(pcm16) {
         logEvent("realtime:audio_delta", `bytes=${pcm16.length}`);
+        trace("realtime:audio_delta", { bytes: pcm16.length });
         heardAssistantAudio = true;
         lastAssistantAudioAt = Date.now();
         onAssistantAudio?.(pcm16);
         engine.play(pcm16);
       },
       onTranscript(text) {
-        const echoGuardMs = Number.parseInt(
-          process.env.AGENT_VOICE_ECHO_GUARD_MS ?? "1500",
-          10
-        );
+        const echoGuardMs = readEnvInt("AGENT_VOICE_ECHO_GUARD_MS", 1500);
         const sinceAssistantMs = Date.now() - lastAssistantAudioAt;
         if (heardAssistantAudio && sinceAssistantMs < echoGuardMs) {
           logEvent(
             "realtime:transcript_ignored_echo_guard",
             `since_assistant_ms=${sinceAssistantMs} text="${text}"`
           );
+          trace("realtime:transcript_ignored_echo_guard", {
+            sinceAssistantMs,
+            text
+          });
           return;
         }
         logEvent("realtime:transcript", `text="${text}"`);
+        trace("realtime:transcript", { text });
+        if (speechDetected) {
+          const evidenceWindowMs = readEnvInt(
+            "AGENT_VOICE_SPEECH_EVIDENCE_WINDOW_MS",
+            1200
+          );
+          const evidenceAgeMs = nearEndEvidenceSeen ? Math.abs(nearEndEvidenceAtMs - speechStartedAtMs) : Number.POSITIVE_INFINITY;
+          if (!nearEndEvidenceSeen || evidenceAgeMs > evidenceWindowMs) {
+            trace("realtime:transcript_ignored_no_near_end_evidence", {
+              text,
+              speechStartedAtMs,
+              nearEndEvidenceSeen,
+              nearEndEvidenceAtMs,
+              evidenceAgeMs,
+              evidenceWindowMs
+            });
+            return;
+          }
+        }
         if (transcriptTimer) {
           clearTimeout(transcriptTimer);
           transcriptTimer = null;
@@ -259,7 +318,9 @@ async function ask(message, options = {}) {
       },
       onSpeechStarted() {
         logEvent("realtime:speech_started");
+        trace("realtime:speech_started");
         speechDetected = true;
+        speechStartedAtMs = Date.now();
         if (timeoutTimer) {
           clearTimeout(timeoutTimer);
           timeoutTimer = null;
@@ -267,6 +328,9 @@ async function ask(message, options = {}) {
         if (transcriptTimer) clearTimeout(transcriptTimer);
         transcriptTimer = setTimeout(() => {
           logEvent("timeout:no_transcript_after_speech");
+          trace("timeout:no_transcript_after_speech", {
+            timeoutSeconds: timeout
+          });
           rejectOnce(
             new Error(
               `No transcript received within ${timeout}s after speech started`
@@ -282,10 +346,12 @@ async function ask(message, options = {}) {
       },
       onInitialResponseDone() {
         logEvent("realtime:initial_response_done");
+        trace("realtime:initial_response_done");
         initialResponseDone = true;
         timeoutTimer = setTimeout(() => {
           if (!speechDetected) {
             logEvent("timeout:no_speech");
+            trace("timeout:no_speech", { timeoutSeconds: timeout });
             rejectOnce(
               new Error(`No speech detected within ${timeout}s timeout`)
             );
@@ -294,21 +360,26 @@ async function ask(message, options = {}) {
       },
       onDone() {
         logEvent("realtime:done");
+        trace("realtime:done");
         if (ack) resolveOnce(transcript);
       },
       onError(error) {
         logEvent("realtime:error", error);
+        trace("realtime:error", { error });
         rejectOnce(new Error(error));
       }
     });
     session.connect().then(
       () => {
         logEvent("realtime:connected");
+        trace("realtime:connected");
         logEvent("realtime:send_message");
+        trace("realtime:send_message");
         session.sendMessage(message);
         responseStartTimer = setTimeout(() => {
           if (!heardAssistantAudio) {
             logEvent("timeout:no_assistant_audio");
+            trace("timeout:no_assistant_audio");
             rejectOnce(
               new Error("No assistant audio received after sending message")
             );
@@ -320,6 +391,9 @@ async function ask(message, options = {}) {
           "realtime:connect_error",
           err instanceof Error ? err.message : String(err)
         );
+        trace("realtime:connect_error", {
+          error: err instanceof Error ? err.message : String(err)
+        });
         rejectOnce(err instanceof Error ? err : new Error(String(err)));
       }
     );
@@ -360,30 +434,46 @@ function resolveVoice() {
 import { createRequire as createRequire2 } from "module";
 var require3 = createRequire2(import.meta.url);
 async function say(message, options = {}) {
-  const { voice = DEFAULT_VOICE, auth } = options;
+  const {
+    voice = DEFAULT_VOICE,
+    auth,
+    createSession,
+    createAudioEngine,
+    onTrace
+  } = options;
   const { AudioEngine } = require3("agent-voice-audio");
-  const engine = new AudioEngine({
+  const startMs = Date.now();
+  function trace(event, detail) {
+    onTrace?.({ atMs: Date.now() - startMs, event, detail });
+  }
+  const engine = (createAudioEngine ?? ((engineOptions) => new AudioEngine(engineOptions)))({
     sampleRate: SAMPLE_RATE,
     channels: 1,
     enableAec: false
   });
   engine.start();
+  trace("start");
   return new Promise((resolve, reject) => {
     let cleaned = false;
     let settled = false;
     let responseDoneFallbackTimer = null;
     let completionTailTimer = null;
+    let drainPollTimer = null;
+    let drainDeadlineTimer = null;
     function cleanup() {
       if (cleaned) return;
       cleaned = true;
       if (responseDoneFallbackTimer) clearTimeout(responseDoneFallbackTimer);
       if (completionTailTimer) clearTimeout(completionTailTimer);
+      if (drainPollTimer) clearInterval(drainPollTimer);
+      if (drainDeadlineTimer) clearTimeout(drainDeadlineTimer);
       try {
         engine.stop();
         engine.close();
       } catch {
       }
       session.close();
+      trace("cleanup");
     }
     function resolveOnce() {
       if (settled) return;
@@ -397,23 +487,76 @@ async function say(message, options = {}) {
       cleanup();
       reject(error);
     }
+    function waitForPlaybackDrain() {
+      if (settled) return;
+      if (!engine.getStats) {
+        trace("drain:no_stats");
+        resolveOnce();
+        return;
+      }
+      const absoluteDeadlineMs = 2e4;
+      const maxNoProgressMs = 1200;
+      const drainStartMs = Date.now();
+      let lastProgressAtMs = drainStartMs;
+      let lastPending = Number.POSITIVE_INFINITY;
+      trace("drain:deadline_scheduled", {
+        absoluteDeadlineMs,
+        maxNoProgressMs
+      });
+      let zeroStreak = 0;
+      drainPollTimer = setInterval(() => {
+        if (settled) return;
+        let pending = 0;
+        try {
+          pending = Number(engine.getStats?.().pendingPlaybackSamples ?? 0);
+        } catch {
+          pending = 0;
+        }
+        trace("drain:poll", { pendingPlaybackSamples: pending });
+        if (pending < lastPending) {
+          lastPending = pending;
+          lastProgressAtMs = Date.now();
+        }
+        if (pending <= 0) {
+          zeroStreak += 1;
+          if (zeroStreak >= 3) {
+            resolveOnce();
+          }
+          return;
+        }
+        zeroStreak = 0;
+        if (Date.now() - lastProgressAtMs > maxNoProgressMs) {
+          trace("drain:no_progress_timeout", {
+            pendingPlaybackSamples: pending
+          });
+          resolveOnce();
+        }
+      }, 20);
+      drainDeadlineTimer = setTimeout(() => {
+        trace("drain:deadline");
+        resolveOnce();
+      }, absoluteDeadlineMs);
+    }
     function scheduleTailResolve(delayMs) {
       if (settled) return;
       if (completionTailTimer) clearTimeout(completionTailTimer);
       completionTailTimer = setTimeout(() => {
-        resolveOnce();
+        waitForPlaybackDrain();
       }, delayMs);
+      trace("tail_scheduled", { delayMs });
     }
-    const session = createRealtimeSession({
+    const session = (createSession ?? createRealtimeSession)({
       voice,
       mode: "say",
       ack: false,
       auth,
       onAudioDelta(pcm16) {
         engine.play(pcm16);
+        trace("realtime:audio_delta", { bytes: pcm16.length });
       },
       onAudioDone() {
         scheduleTailResolve(140);
+        trace("realtime:audio_done");
       },
       onTranscript() {
       },
@@ -424,14 +567,17 @@ async function say(message, options = {}) {
         responseDoneFallbackTimer = setTimeout(() => {
           scheduleTailResolve(220);
         }, 700);
+        trace("realtime:initial_response_done");
       },
       onDone() {
       },
       onError(error) {
+        trace("realtime:error", { error });
         rejectOnce(new Error(error));
       }
     });
     session.connect().then(() => {
+      trace("realtime:connected");
       session.sendMessage(message);
     }, reject);
   });

package/dist/say-ZVF6EX52.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import {
+  createRealtimeSession
+} from "./chunk-UYBFONQE.js";
+import {
+  DEFAULT_VOICE,
+  SAMPLE_RATE
+} from "./chunk-AHLLYIEW.js";
+
+// src/say.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+async function say(message, options = {}) {
+  const {
+    voice = DEFAULT_VOICE,
+    auth,
+    createSession,
+    createAudioEngine,
+    onTrace
+  } = options;
+  const { AudioEngine } = require2("agent-voice-audio");
+  const startMs = Date.now();
+  function trace(event, detail) {
+    onTrace?.({ atMs: Date.now() - startMs, event, detail });
+  }
+  const engine = (createAudioEngine ?? ((engineOptions) => new AudioEngine(engineOptions)))({
+    sampleRate: SAMPLE_RATE,
+    channels: 1,
+    enableAec: false
+  });
+  engine.start();
+  trace("start");
+  return new Promise((resolve, reject) => {
+    let cleaned = false;
+    let settled = false;
+    let responseDoneFallbackTimer = null;
+    let completionTailTimer = null;
+    let drainPollTimer = null;
+    let drainDeadlineTimer = null;
+    function cleanup() {
+      if (cleaned) return;
+      cleaned = true;
+      if (responseDoneFallbackTimer) clearTimeout(responseDoneFallbackTimer);
+      if (completionTailTimer) clearTimeout(completionTailTimer);
+      if (drainPollTimer) clearInterval(drainPollTimer);
+      if (drainDeadlineTimer) clearTimeout(drainDeadlineTimer);
+      try {
+        engine.stop();
+        engine.close();
+      } catch {
+      }
+      session.close();
+      trace("cleanup");
+    }
+    function resolveOnce() {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve();
+    }
+    function rejectOnce(error) {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    }
+    function waitForPlaybackDrain() {
+      if (settled) return;
+      if (!engine.getStats) {
+        trace("drain:no_stats");
+        resolveOnce();
+        return;
+      }
+      const absoluteDeadlineMs = 2e4;
+      const maxNoProgressMs = 1200;
+      const drainStartMs = Date.now();
+      let lastProgressAtMs = drainStartMs;
+      let lastPending = Number.POSITIVE_INFINITY;
+      trace("drain:deadline_scheduled", {
+        absoluteDeadlineMs,
+        maxNoProgressMs
+      });
+      let zeroStreak = 0;
+      drainPollTimer = setInterval(() => {
+        if (settled) return;
+        let pending = 0;
+        try {
+          pending = Number(engine.getStats?.().pendingPlaybackSamples ?? 0);
+        } catch {
+          pending = 0;
+        }
+        trace("drain:poll", { pendingPlaybackSamples: pending });
+        if (pending < lastPending) {
+          lastPending = pending;
+          lastProgressAtMs = Date.now();
+        }
+        if (pending <= 0) {
+          zeroStreak += 1;
+          if (zeroStreak >= 3) {
+            resolveOnce();
+          }
+          return;
+        }
+        zeroStreak = 0;
+        if (Date.now() - lastProgressAtMs > maxNoProgressMs) {
+          trace("drain:no_progress_timeout", {
+            pendingPlaybackSamples: pending
+          });
+          resolveOnce();
+        }
+      }, 20);
+      drainDeadlineTimer = setTimeout(() => {
+        trace("drain:deadline");
+        resolveOnce();
+      }, absoluteDeadlineMs);
+    }
+    function scheduleTailResolve(delayMs) {
+      if (settled) return;
+      if (completionTailTimer) clearTimeout(completionTailTimer);
+      completionTailTimer = setTimeout(() => {
+        waitForPlaybackDrain();
+      }, delayMs);
+      trace("tail_scheduled", { delayMs });
+    }
+    const session = (createSession ?? createRealtimeSession)({
+      voice,
+      mode: "say",
+      ack: false,
+      auth,
+      onAudioDelta(pcm16) {
+        engine.play(pcm16);
+        trace("realtime:audio_delta", { bytes: pcm16.length });
+      },
+      onAudioDone() {
+        scheduleTailResolve(140);
+        trace("realtime:audio_done");
+      },
+      onTranscript() {
+      },
+      onSpeechStarted() {
+      },
+      onInitialResponseDone() {
+        if (responseDoneFallbackTimer) clearTimeout(responseDoneFallbackTimer);
+        responseDoneFallbackTimer = setTimeout(() => {
+          scheduleTailResolve(220);
+        }, 700);
+        trace("realtime:initial_response_done");
+      },
+      onDone() {
+      },
+      onError(error) {
+        trace("realtime:error", { error });
+        rejectOnce(new Error(error));
+      }
+    });
+    session.connect().then(() => {
+      trace("realtime:connected");
+      session.sendMessage(message);
+    }, reject);
+  });
+}
+export {
+  say
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-voice",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "CLI for AI agents to interact with humans via voice",
   "type": "module",
   "main": "./dist/index.js",

package/dist/say-ELJAIWUM.js

@@ -1,92 +0,0 @@
-#!/usr/bin/env node
-import {
-  createRealtimeSession
-} from "./chunk-UYBFONQE.js";
-import {
-  DEFAULT_VOICE,
-  SAMPLE_RATE
-} from "./chunk-AHLLYIEW.js";
-
-// src/say.ts
-import { createRequire } from "module";
-var require2 = createRequire(import.meta.url);
-async function say(message, options = {}) {
-  const { voice = DEFAULT_VOICE, auth } = options;
-  const { AudioEngine } = require2("agent-voice-audio");
-  const engine = new AudioEngine({
-    sampleRate: SAMPLE_RATE,
-    channels: 1,
-    enableAec: false
-  });
-  engine.start();
-  return new Promise((resolve, reject) => {
-    let cleaned = false;
-    let settled = false;
-    let responseDoneFallbackTimer = null;
-    let completionTailTimer = null;
-    function cleanup() {
-      if (cleaned) return;
-      cleaned = true;
-      if (responseDoneFallbackTimer) clearTimeout(responseDoneFallbackTimer);
-      if (completionTailTimer) clearTimeout(completionTailTimer);
-      try {
-        engine.stop();
-        engine.close();
-      } catch {
-      }
-      session.close();
-    }
-    function resolveOnce() {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      resolve();
-    }
-    function rejectOnce(error) {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(error);
-    }
-    function scheduleTailResolve(delayMs) {
-      if (settled) return;
-      if (completionTailTimer) clearTimeout(completionTailTimer);
-      completionTailTimer = setTimeout(() => {
-        resolveOnce();
-      }, delayMs);
-    }
-    const session = createRealtimeSession({
-      voice,
-      mode: "say",
-      ack: false,
-      auth,
-      onAudioDelta(pcm16) {
-        engine.play(pcm16);
-      },
-      onAudioDone() {
-        scheduleTailResolve(140);
-      },
-      onTranscript() {
-      },
-      onSpeechStarted() {
-      },
-      onInitialResponseDone() {
-        if (responseDoneFallbackTimer) clearTimeout(responseDoneFallbackTimer);
-        responseDoneFallbackTimer = setTimeout(() => {
-          scheduleTailResolve(220);
-        }, 700);
-      },
-      onDone() {
-      },
-      onError(error) {
-        rejectOnce(new Error(error));
-      }
-    });
-    session.connect().then(() => {
-      session.sendMessage(message);
-    }, reject);
-  });
-}
-export {
-  say
-};