@absolutejs/voice 0.0.22-beta.581 → 0.0.22-beta.583

package/dist/client/audioPlayer.d.ts

@@ -22,9 +22,16 @@ type MinimalGainNode = {
         value: number;
     };
 };
+type MinimalAnalyserNode = {
+    connect?: (destination: unknown) => void;
+    disconnect?: () => void;
+    fftSize: number;
+    getByteTimeDomainData: (array: Uint8Array) => void;
+};
 type MinimalAudioContext = {
     baseLatency?: number;
     close: () => Promise<void>;
+    createAnalyser?: () => MinimalAnalyserNode;
     createBuffer: (numberOfChannels: number, length: number, sampleRate: number) => MinimalAudioBuffer;
     createBufferSource: () => MinimalAudioBufferSourceNode;
     createGain?: () => MinimalGainNode;

package/dist/client/htmxBootstrap.js

@@ -1693,6 +1693,8 @@ var DEFAULT_PLAYBACK_RATE = 1;
 var MIN_PLAYBACK_RATE = 0.5;
 var MAX_PLAYBACK_RATE = 2;
 var STRETCH_BYPASS_EPSILON = 0.01;
+var ANALYSER_FFT_SIZE = 256;
+var PCM_BYTE_MIDPOINT = 128;
 var createInitialState3 = () => ({
   activeSourceCount: 0,
   error: null,
@@ -1753,6 +1755,8 @@ var createVoiceAudioPlayer = (source, options = {}) => {
   let state = createInitialState3();
   let audioContext = null;
   let outputNode = null;
+  let analyserNode = null;
+  let analyserBuffer = null;
   let volume = clampVolume(options.volume);
   let playbackRate = clampPlaybackRate(options.playbackRate);
   let stretcher = null;
@@ -1849,6 +1853,12 @@ var createVoiceAudioPlayer = (source, options = {}) => {
     if (audioContext.createGain) {
       outputNode = audioContext.createGain();
       outputNode.connect?.(audioContext.destination);
+      if (audioContext.createAnalyser) {
+        analyserNode = audioContext.createAnalyser();
+        analyserNode.fftSize = ANALYSER_FFT_SIZE;
+        analyserBuffer = new Uint8Array(analyserNode.fftSize);
+        outputNode.connect?.(analyserNode);
+      }
     }
     queueEndTime = audioContext.currentTime;
     return audioContext;
@@ -1973,6 +1983,9 @@ var createVoiceAudioPlayer = (source, options = {}) => {
       audioContext = null;
       outputNode?.disconnect?.();
       outputNode = null;
+      analyserNode?.disconnect?.();
+      analyserNode = null;
+      analyserBuffer = null;
       queueEndTime = 0;
       setState({
         activeSourceCount: 0,
@@ -1983,6 +1996,18 @@ var createVoiceAudioPlayer = (source, options = {}) => {
     get error() {
       return state.error;
     },
+    getOutputLevel: () => {
+      if (!analyserNode || !analyserBuffer) {
+        return 0;
+      }
+      analyserNode.getByteTimeDomainData(analyserBuffer);
+      let sumSquares = 0;
+      for (const sample of analyserBuffer) {
+        const centered = (sample - PCM_BYTE_MIDPOINT) / PCM_BYTE_MIDPOINT;
+        sumSquares += centered * centered;
+      }
+      return Math.sqrt(sumSquares / analyserBuffer.length);
+    },
     getSnapshot: () => state,
     interrupt: async () => {
       const startedAt = Date.now();

package/dist/client/index.js

@@ -529,6 +529,8 @@ var DEFAULT_PLAYBACK_RATE = 1;
 var MIN_PLAYBACK_RATE = 0.5;
 var MAX_PLAYBACK_RATE = 2;
 var STRETCH_BYPASS_EPSILON = 0.01;
+var ANALYSER_FFT_SIZE = 256;
+var PCM_BYTE_MIDPOINT = 128;
 var createInitialState = () => ({
   activeSourceCount: 0,
   error: null,
@@ -589,6 +591,8 @@ var createVoiceAudioPlayer = (source, options = {}) => {
   let state = createInitialState();
   let audioContext = null;
   let outputNode = null;
+  let analyserNode = null;
+  let analyserBuffer = null;
   let volume = clampVolume(options.volume);
   let playbackRate = clampPlaybackRate(options.playbackRate);
   let stretcher = null;
@@ -685,6 +689,12 @@ var createVoiceAudioPlayer = (source, options = {}) => {
     if (audioContext.createGain) {
       outputNode = audioContext.createGain();
       outputNode.connect?.(audioContext.destination);
+      if (audioContext.createAnalyser) {
+        analyserNode = audioContext.createAnalyser();
+        analyserNode.fftSize = ANALYSER_FFT_SIZE;
+        analyserBuffer = new Uint8Array(analyserNode.fftSize);
+        outputNode.connect?.(analyserNode);
+      }
     }
     queueEndTime = audioContext.currentTime;
     return audioContext;
@@ -809,6 +819,9 @@ var createVoiceAudioPlayer = (source, options = {}) => {
       audioContext = null;
       outputNode?.disconnect?.();
       outputNode = null;
+      analyserNode?.disconnect?.();
+      analyserNode = null;
+      analyserBuffer = null;
       queueEndTime = 0;
       setState({
         activeSourceCount: 0,
@@ -819,6 +832,18 @@ var createVoiceAudioPlayer = (source, options = {}) => {
     get error() {
       return state.error;
     },
+    getOutputLevel: () => {
+      if (!analyserNode || !analyserBuffer) {
+        return 0;
+      }
+      analyserNode.getByteTimeDomainData(analyserBuffer);
+      let sumSquares = 0;
+      for (const sample of analyserBuffer) {
+        const centered = (sample - PCM_BYTE_MIDPOINT) / PCM_BYTE_MIDPOINT;
+        sumSquares += centered * centered;
+      }
+      return Math.sqrt(sumSquares / analyserBuffer.length);
+    },
     getSnapshot: () => state,
     interrupt: async () => {
       const startedAt = Date.now();

package/dist/core/debugTiming.d.ts

@@ -0,0 +1,11 @@
+export declare const logVoiceTiming: (sessionId: string, stage: string, elapsedMs: number, detail?: Record<string, unknown>) => void;
+/**
+ * A per-turn stopwatch. `stamp(stage, detail?)` logs the elapsed since the timer
+ * was created, so one timer per turn lays every stage out on a single timeline:
+ *
+ *   const stamp = startVoiceTimer(session.id);
+ *   stamp("agent.system-resolved", { chars });
+ *   stamp("agent.round0.generate-done", { ms });
+ */
+export declare const startVoiceTimer: (sessionId: string) => (stage: string, detail?: Record<string, unknown>) => void;
+export declare const voiceTimingEnabled: () => boolean;

package/dist/core/types.d.ts

@@ -1331,6 +1331,9 @@ export type VoiceAudioPlayerSource = {
 export type VoiceAudioPlayer = {
     close: () => Promise<void>;
     error: string | null;
+    /** Instantaneous RMS amplitude (0..1) of the assistant's audio output — for
+     *  driving a visualizer from the actual voice. 0 when idle / no analyser. */
+    getOutputLevel: () => number;
     getSnapshot: () => VoiceAudioPlayerState;
     activeSourceCount: number;
     isActive: boolean;

package/dist/index.d.ts

@@ -71,6 +71,7 @@ export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, crea
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool, } from "./core/agent";
 export { createPersonaVoiceCaller, createScriptedVoiceCaller, renderVoiceSimulationTranscript, runVoiceConversationSimulation, } from "./core/conversationSimulator";
 export type { RunVoiceConversationSimulationInput, VoiceConversationSimulationEndedReason, VoiceConversationSimulationResult, VoicePersonaCallerCompletion, VoiceScriptedCallerStep, VoiceSimulatedSpeaker, VoiceSimulatedTurn, VoiceSimulatorCaller, VoiceSimulatorCallerModel, VoiceSimulatorCallerReply, } from "./core/conversationSimulator";
+export { logVoiceTiming, startVoiceTimer, voiceTimingEnabled, } from "./core/debugTiming";
 export { createVoiceMCPToolset } from "./core/mcpToolset";
 export type { CreateVoiceMCPToolsetOptions, MCPClientLike, MCPToolCallResult, MCPToolContentBlock, MCPToolDefinition, VoiceMCPToolResult, } from "./core/mcpToolset";
 export { createAIVoiceModel } from "./core/aiVoiceModel";

package/dist/index.js

@@ -3091,6 +3091,21 @@ var toVoiceSessionSummary = (session) => ({
 // src/core/session.ts
 import { Buffer as Buffer2 } from "buffer";
 
+// src/core/debugTiming.ts
+var timingEnabled = () => process.env.ABSOLUTEJS_VOICE_TIMING === "1" || process.env.ABSOLUTEJS_VOICE_TIMING === "true";
+var emitTiming = (sessionId, stage, elapsedMs, detail) => {
+  if (!timingEnabled())
+    return;
+  const extra = detail ? ` ${JSON.stringify(detail)}` : "";
+  console.info(`[voice][timing] session=${sessionId} ${stage} +${Math.round(elapsedMs)}ms${extra}`);
+};
+var logVoiceTiming = (sessionId, stage, elapsedMs, detail) => emitTiming(sessionId, stage, elapsedMs, detail);
+var startVoiceTimer = (sessionId) => {
+  const startedAt = Date.now();
+  return (stage, detail) => emitTiming(sessionId, stage, Date.now() - startedAt, detail);
+};
+var voiceTimingEnabled = () => timingEnabled();
+
 // src/core/backchannel.ts
 var DEFAULT_CUES = [
   { text: "mm-hmm" },
@@ -5534,6 +5549,7 @@ var createVoiceSession = (options) => {
     const onTurnTimeoutMs = options.routeOnTurnTimeoutMs ?? 45000;
     let committedOutput;
     const onTurnStartedAt = Date.now();
+    logVoiceTiming(session.id, "session.commit-to-onturn", onTurnStartedAt - (turn.committedAt || onTurnStartedAt), { fillerScheduled: fillerTimer !== null });
     try {
       const onTurnPromise = options.route.onTurn({
         api,
@@ -7446,7 +7462,9 @@ var createVoiceAgent = (options) => {
   const maxToolRounds = Math.max(0, options.maxToolRounds ?? 2);
   const audit = resolveVoiceAgentAuditLogger(options.audit);
   const run = async (input) => {
+    const stamp = startVoiceTimer(input.session.id);
     const messages = input.messages ?? createHistoryMessages(input.session, input.turn);
+    stamp("agent.history-built", { messages: messages.length });
     const toolResults = [];
     const baseSystem = typeof options.system === "function" ? await options.system({
       context: input.context,
@@ -7456,9 +7474,11 @@ var createVoiceAgent = (options) => {
     const system = [baseSystem, input.system].filter((value) => Boolean(value?.trim())).join(`
 
 `) || undefined;
+    stamp("agent.system-resolved", { systemChars: system?.length ?? 0 });
     let output = {};
     for (let round = 0;round <= maxToolRounds; round += 1) {
       const modelStartedAt = Date.now();
+      stamp(`agent.round${round}.generate-start`);
       try {
         output = await options.model.generate({
           agentId: options.id,
@@ -7474,6 +7494,11 @@ var createVoiceAgent = (options) => {
           })),
           turn: input.turn
         });
+        stamp(`agent.round${round}.generate-done`, {
+          ms: Date.now() - modelStartedAt,
+          textChars: output.assistantText?.length ?? 0,
+          toolCalls: output.toolCalls?.length ?? 0
+        });
         await audit?.providerCall({
           actor: {
             id: options.id,
@@ -7487,6 +7512,9 @@ var createVoiceAgent = (options) => {
           sessionId: input.session.id
         });
       } catch (error) {
+        stamp(`agent.round${round}.generate-error`, {
+          ms: Date.now() - modelStartedAt
+        });
         await audit?.providerCall({
           actor: {
             id: options.id,
@@ -45368,6 +45396,7 @@ var createOpenAIVoiceAssistantModel = (options) => {
   const timeoutMs = options.timeoutMs ?? 60000;
   return {
     generate: async (input) => {
+      const stamp = startVoiceTimer(input.session.id);
       const ac = new AbortController;
       const timer = setTimeout(() => {
         ac.abort(new Error(`OpenAI /responses timed out after ${timeoutMs}ms (no completion event received)`));
@@ -45408,6 +45437,10 @@ var createOpenAIVoiceAssistantModel = (options) => {
         clearTimeout(timer);
         throw error;
       }
+      stamp("openai.fetch-returned", {
+        messages: input.messages.length,
+        status: response.status
+      });
       if (!response.ok) {
         clearTimeout(timer);
         throw createHTTPError("OpenAI", response);
@@ -45415,11 +45448,23 @@ var createOpenAIVoiceAssistantModel = (options) => {
       let assistantText;
       let toolCalls;
       let usage;
+      let firstDeltaSeen = false;
+      const onTextDelta = input.onTextDelta ? (delta) => {
+        if (!firstDeltaSeen) {
+          firstDeltaSeen = true;
+          stamp("openai.first-delta");
+        }
+        input.onTextDelta?.(delta);
+      } : undefined;
       try {
-        ({ assistantText, toolCalls, usage } = await consumeOpenAIResponsesStream(response, input.onTextDelta, {
+        ({ assistantText, toolCalls, usage } = await consumeOpenAIResponsesStream(response, onTextDelta, {
           signal: ac.signal,
           inactivityMs: 1e4
         }));
+        stamp("openai.stream-done", {
+          textChars: assistantText?.length ?? 0,
+          toolCalls: toolCalls.length
+        });
       } finally {
         clearTimeout(timer);
       }
@@ -52391,6 +52436,7 @@ export {
   wrapVoiceHTMLInHTMXContainer,
   withVoiceOpsTaskId,
   withVoiceIntegrationEventId,
+  voiceTimingEnabled,
   voiceTelephonyOutcomeToRouteResult,
   voiceObservabilityExportSchemaVersion,
   voiceObservabilityExportSchemaId,
@@ -52448,6 +52494,7 @@ export {
   summarizeVoiceAuditSinkDeliveries,
   summarizeVoiceAssistantRuns,
   summarizeVoiceAssistantHealth,
+  startVoiceTimer,
   startVoiceOpsTask,
   signVoiceWebhookBody,
   signVoiceTwilioWebhook,
@@ -52648,6 +52695,7 @@ export {
   matchesVoiceOpsTaskAssignmentRule,
   markVoiceOpsTaskSLABreached,
   mapVoiceProofTargetsWithConcurrency,
+  logVoiceTiming,
   loadVoiceRealCallProfileEvidenceFromTraceStore,
   loadVoiceRealCallProfileEvidenceFromStore,
   loadVoiceObservabilityExportReplaySource,

package/dist/testing/index.js

@@ -1736,6 +1736,8 @@ var DEFAULT_PLAYBACK_RATE = 1;
 var MIN_PLAYBACK_RATE = 0.5;
 var MAX_PLAYBACK_RATE = 2;
 var STRETCH_BYPASS_EPSILON = 0.01;
+var ANALYSER_FFT_SIZE = 256;
+var PCM_BYTE_MIDPOINT = 128;
 var createInitialState = () => ({
   activeSourceCount: 0,
   error: null,
@@ -1796,6 +1798,8 @@ var createVoiceAudioPlayer = (source, options = {}) => {
   let state = createInitialState();
   let audioContext = null;
   let outputNode = null;
+  let analyserNode = null;
+  let analyserBuffer = null;
   let volume = clampVolume(options.volume);
   let playbackRate = clampPlaybackRate(options.playbackRate);
   let stretcher = null;
@@ -1892,6 +1896,12 @@ var createVoiceAudioPlayer = (source, options = {}) => {
     if (audioContext.createGain) {
       outputNode = audioContext.createGain();
       outputNode.connect?.(audioContext.destination);
+      if (audioContext.createAnalyser) {
+        analyserNode = audioContext.createAnalyser();
+        analyserNode.fftSize = ANALYSER_FFT_SIZE;
+        analyserBuffer = new Uint8Array(analyserNode.fftSize);
+        outputNode.connect?.(analyserNode);
+      }
     }
     queueEndTime = audioContext.currentTime;
     return audioContext;
@@ -2016,6 +2026,9 @@ var createVoiceAudioPlayer = (source, options = {}) => {
       audioContext = null;
       outputNode?.disconnect?.();
       outputNode = null;
+      analyserNode?.disconnect?.();
+      analyserNode = null;
+      analyserBuffer = null;
       queueEndTime = 0;
       setState({
         activeSourceCount: 0,
@@ -2026,6 +2039,18 @@ var createVoiceAudioPlayer = (source, options = {}) => {
     get error() {
       return state.error;
     },
+    getOutputLevel: () => {
+      if (!analyserNode || !analyserBuffer) {
+        return 0;
+      }
+      analyserNode.getByteTimeDomainData(analyserBuffer);
+      let sumSquares = 0;
+      for (const sample of analyserBuffer) {
+        const centered = (sample - PCM_BYTE_MIDPOINT) / PCM_BYTE_MIDPOINT;
+        sumSquares += centered * centered;
+      }
+      return Math.sqrt(sumSquares / analyserBuffer.length);
+    },
     getSnapshot: () => state,
     interrupt: async () => {
       const startedAt = Date.now();
@@ -4170,6 +4195,21 @@ var createVoiceIOProviderFailureSimulator = (options) => {
     run
   };
 };
+// src/core/debugTiming.ts
+var timingEnabled = () => process.env.ABSOLUTEJS_VOICE_TIMING === "1" || process.env.ABSOLUTEJS_VOICE_TIMING === "true";
+var emitTiming = (sessionId, stage, elapsedMs, detail) => {
+  if (!timingEnabled())
+    return;
+  const extra = detail ? ` ${JSON.stringify(detail)}` : "";
+  console.info(`[voice][timing] session=${sessionId} ${stage} +${Math.round(elapsedMs)}ms${extra}`);
+};
+var logVoiceTiming = (sessionId, stage, elapsedMs, detail) => emitTiming(sessionId, stage, elapsedMs, detail);
+var startVoiceTimer = (sessionId) => {
+  const startedAt = Date.now();
+  return (stage, detail) => emitTiming(sessionId, stage, Date.now() - startedAt, detail);
+};
+var voiceTimingEnabled = () => timingEnabled();
+
 // src/core/modelAdapters.ts
 var isVoiceProviderRoutingPolicyPreset = (value) => value === "balanced" || value === "cost-cap" || value === "cost-first" || value === "latency-first" || value === "quality-first";
 var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
@@ -4880,6 +4920,7 @@ var createOpenAIVoiceAssistantModel = (options) => {
   const timeoutMs = options.timeoutMs ?? 60000;
   return {
     generate: async (input) => {
+      const stamp = startVoiceTimer(input.session.id);
       const ac = new AbortController;
       const timer = setTimeout(() => {
         ac.abort(new Error(`OpenAI /responses timed out after ${timeoutMs}ms (no completion event received)`));
@@ -4920,6 +4961,10 @@ var createOpenAIVoiceAssistantModel = (options) => {
         clearTimeout(timer);
         throw error;
       }
+      stamp("openai.fetch-returned", {
+        messages: input.messages.length,
+        status: response.status
+      });
       if (!response.ok) {
         clearTimeout(timer);
         throw createHTTPError("OpenAI", response);
@@ -4927,11 +4972,23 @@ var createOpenAIVoiceAssistantModel = (options) => {
       let assistantText;
       let toolCalls;
       let usage;
+      let firstDeltaSeen = false;
+      const onTextDelta = input.onTextDelta ? (delta) => {
+        if (!firstDeltaSeen) {
+          firstDeltaSeen = true;
+          stamp("openai.first-delta");
+        }
+        input.onTextDelta?.(delta);
+      } : undefined;
       try {
-        ({ assistantText, toolCalls, usage } = await consumeOpenAIResponsesStream(response, input.onTextDelta, {
+        ({ assistantText, toolCalls, usage } = await consumeOpenAIResponsesStream(response, onTextDelta, {
           signal: ac.signal,
           inactivityMs: 1e4
         }));
+        stamp("openai.stream-done", {
+          textChars: assistantText?.length ?? 0,
+          toolCalls: toolCalls.length
+        });
       } finally {
         clearTimeout(timer);
       }
@@ -7651,6 +7708,7 @@ var createVoiceSession = (options) => {
     const onTurnTimeoutMs = options.routeOnTurnTimeoutMs ?? 45000;
     let committedOutput;
     const onTurnStartedAt = Date.now();
+    logVoiceTiming(session.id, "session.commit-to-onturn", onTurnStartedAt - (turn.committedAt || onTurnStartedAt), { fillerScheduled: fillerTimer !== null });
     try {
       const onTurnPromise = options.route.onTurn({
         api,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.581",
+  "version": "0.0.22-beta.583",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",