@absolutejs/voice 0.0.22-beta.180 → 0.0.22-beta.182

package/dist/agent.d.ts

@@ -61,10 +61,30 @@ export type VoiceAgentModelOutput<TResult = unknown> = VoiceRouteResult<TResult>
 export type VoiceAgentModel<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     generate: (input: VoiceAgentModelInput<TContext, TSession>) => Promise<VoiceAgentModelOutput<TResult>> | VoiceAgentModelOutput<TResult>;
 };
+export type VoiceAgentSquadHandoffStatus = 'allowed' | 'blocked' | 'max-exceeded' | 'unknown-target';
+export type VoiceAgentSquadStateHandoff = {
+    at: number;
+    fromAgentId: string;
+    metadata?: Record<string, unknown>;
+    originalTargetAgentId?: string;
+    reason?: string;
+    status: VoiceAgentSquadHandoffStatus;
+    summary?: string;
+    targetAgentId: string;
+    turnId: string;
+};
+export type VoiceAgentSquadState = {
+    agentId: string;
+    handoffCount: number;
+    handoffs: VoiceAgentSquadStateHandoff[];
+    lastHandoff?: VoiceAgentSquadStateHandoff;
+    previousAgentId?: string;
+};
 export type VoiceAgentRunResult<TResult = unknown> = VoiceRouteResult<TResult> & {
     agentId: string;
     handoff?: VoiceAgentModelOutput<TResult>['handoff'];
     messages: VoiceAgentMessage[];
+    squad?: VoiceAgentSquadState;
     toolResults: VoiceAgentToolResult[];
 };
 export type VoiceAgentSquadHandoffPolicyResult<TResult = unknown> = {
@@ -120,8 +140,10 @@ export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSes
     onHandoff?: (input: {
         context: TContext;
         fromAgentId: string;
+        metadata?: Record<string, unknown>;
         reason?: string;
         session: TSession;
+        summary?: string;
         targetAgentId: string;
         turn: VoiceTurnRecord;
     }) => Promise<void> | void;

package/dist/agentSquadContract.d.ts

@@ -1,10 +1,15 @@
-import type { VoiceAgent, VoiceAgentRunResult } from './agent';
+import type { VoiceAgent, VoiceAgentRunResult, VoiceAgentSquadHandoffStatus } from './agent';
 import type { VoiceTraceEventStore } from './trace';
 import type { VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord } from './types';
 export type VoiceAgentSquadContractOutcome = 'assistant' | 'complete' | 'escalate' | 'no-answer' | 'transfer' | 'voicemail';
 export type VoiceAgentSquadHandoffExpectation = {
     fromAgentId?: string;
-    status?: 'allowed' | 'blocked' | 'max-exceeded' | 'unknown-target';
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    reasonIncludes?: string[];
+    status?: VoiceAgentSquadHandoffStatus;
+    summary?: string;
+    summaryIncludes?: string[];
     targetAgentId?: string;
 };
 export type VoiceAgentSquadTurnExpectation<TResult = unknown> = {

package/dist/index.d.ts

@@ -110,7 +110,7 @@ export type { VoiceProviderStackChoice, VoiceProviderStackCapabilities, VoicePro
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingKindSummary, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind, VoiceRoutingSessionSummary, VoiceRoutingSessionSummaryOptions } from './resilienceRoutes';
 export type { VoiceIOProviderRouterEvent, VoiceIOProviderRouterOptions, VoiceIOProviderRouterPolicy, VoiceIOProviderRouterPolicyConfig, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions } from './providerAdapters';
-export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
+export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadHandoffStatus, VoiceAgentSquadOptions, VoiceAgentSquadState, VoiceAgentSquadStateHandoff, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
 export type { VoiceAgentSquadContractDefinition, VoiceAgentSquadContractIssue, VoiceAgentSquadContractOutcome, VoiceAgentSquadContractReport, VoiceAgentSquadContractRunOptions, VoiceAgentSquadContractTurn, VoiceAgentSquadContractTurnReport, VoiceAgentSquadHandoffExpectation, VoiceAgentSquadTurnExpectation } from './agentSquadContract';
 export type { VoiceToolRetryDelay, VoiceToolRuntime, VoiceToolRuntimeExecuteInput, VoiceToolRuntimeOptions, VoiceToolRuntimeResult } from './toolRuntime';
 export type { VoiceToolContractCase, VoiceToolContractCaseReport, VoiceToolContractDefinition, VoiceToolContractExpectation, VoiceToolContractHandlerOptions, VoiceToolContractHTMLHandlerOptions, VoiceToolContractIssue, VoiceToolContractReport, VoiceToolContractRoutesOptions, VoiceToolContractSuiteReport } from './toolContract';

package/dist/index.js

@@ -6887,6 +6887,47 @@ var resolveVoiceAgentAuditLogger = (audit) => {
   return "append" in audit ? createVoiceAuditLogger(audit) : audit;
 };
 var toAuditOutcome = (status) => status === "allowed" ? "success" : status === "blocked" ? "skipped" : "error";
+var createVoiceAgentSquadState = (input) => {
+  const lastHandoff = input.handoffs.at(-1);
+  return {
+    agentId: input.agentId,
+    handoffCount: input.handoffs.length,
+    handoffs: [...input.handoffs],
+    lastHandoff,
+    previousAgentId: lastHandoff?.status === "allowed" ? lastHandoff.fromAgentId : undefined
+  };
+};
+var appendVoiceAgentSquadHandoff = async (input) => {
+  const handoff = {
+    at: Date.now(),
+    fromAgentId: input.fromAgentId,
+    metadata: input.metadata,
+    originalTargetAgentId: input.originalTargetAgentId,
+    reason: input.reason,
+    status: input.status,
+    summary: input.summary,
+    targetAgentId: input.targetAgentId,
+    turnId: input.turn.id
+  };
+  input.handoffs.push(handoff);
+  await appendVoiceAgentTrace({
+    agentId: input.agentId,
+    event: {
+      fromAgentId: handoff.fromAgentId,
+      metadata: handoff.metadata,
+      originalTargetAgentId: handoff.originalTargetAgentId,
+      reason: handoff.reason,
+      status: handoff.status,
+      summary: handoff.summary,
+      targetAgentId: handoff.targetAgentId
+    },
+    session: input.session,
+    trace: input.trace,
+    turn: input.turn,
+    type: "agent.handoff"
+  });
+  return handoff;
+};
 var createVoiceAgentTool = (tool) => tool;
 var createVoiceAgent = (options) => {
   const toolMap = new Map(options.tools?.map((tool) => [tool.name, tool]) ?? []);
@@ -7187,6 +7228,7 @@ var createVoiceAgentSquad = (options) => {
     let agent = agents.get(agentId) ?? defaultAgent;
     const messages = input.messages ?? createHistoryMessages(input.session, input.turn);
     const toolResults = [];
+    const handoffs = [];
     const maxHandoffs = Math.max(0, options.maxHandoffsPerTurn ?? 2);
     let result = await agent.run({
       ...input,
@@ -7207,26 +7249,26 @@ var createVoiceAgentSquad = (options) => {
       const targetAgentId = normalizeText3(policy?.targetAgentId) || originalTargetAgentId;
       const nextAgent = agents.get(targetAgentId);
       const handoffReason = policy?.summary ?? policy?.reason ?? result.handoff.reason;
+      const handoffSummary = policy?.summary ?? result.handoff.reason ?? policy?.reason;
       const handoffMetadata = {
         ...result.handoff.metadata,
         ...policy?.metadata
       };
       const metadata = Object.keys(handoffMetadata).length > 0 ? handoffMetadata : undefined;
       if (policy?.allow === false) {
-        await appendVoiceAgentTrace({
+        await appendVoiceAgentSquadHandoff({
           agentId: options.id,
-          event: {
-            fromAgentId: agent.id,
-            metadata,
-            originalTargetAgentId,
-            reason: handoffReason,
-            status: "blocked",
-            targetAgentId
-          },
+          fromAgentId: agent.id,
+          handoffs,
+          metadata,
+          originalTargetAgentId: originalTargetAgentId === targetAgentId ? undefined : originalTargetAgentId,
+          reason: handoffReason,
           session: input.session,
+          status: "blocked",
+          summary: handoffSummary,
+          targetAgentId,
           trace: options.trace,
-          turn: input.turn,
-          type: "agent.handoff"
+          turn: input.turn
         });
         await audit?.handoff({
           actor: {
@@ -7247,24 +7289,27 @@ var createVoiceAgentSquad = (options) => {
             reason: handoffReason ?? `Blocked handoff to ${targetAgentId}`
           },
           handoff: undefined,
+          squad: createVoiceAgentSquadState({
+            agentId: agent.id,
+            handoffs
+          }),
           toolResults
         };
       }
       if (!nextAgent) {
-        await appendVoiceAgentTrace({
+        await appendVoiceAgentSquadHandoff({
           agentId: options.id,
-          event: {
-            fromAgentId: agent.id,
-            metadata,
-            originalTargetAgentId,
-            reason: handoffReason,
-            status: "unknown-target",
-            targetAgentId
-          },
+          fromAgentId: agent.id,
+          handoffs,
+          metadata,
+          originalTargetAgentId: originalTargetAgentId === targetAgentId ? undefined : originalTargetAgentId,
+          reason: handoffReason,
           session: input.session,
+          status: "unknown-target",
+          summary: handoffSummary,
+          targetAgentId,
           trace: options.trace,
-          turn: input.turn,
-          type: "agent.handoff"
+          turn: input.turn
         });
         await audit?.handoff({
           actor: {
@@ -7285,31 +7330,36 @@ var createVoiceAgentSquad = (options) => {
             reason: `Unknown handoff target: ${targetAgentId}`
           },
           handoff: undefined,
+          squad: createVoiceAgentSquadState({
+            agentId: agent.id,
+            handoffs
+          }),
           toolResults
         };
       }
       await options.onHandoff?.({
         context: input.context,
         fromAgentId: agent.id,
+        metadata,
         reason: handoffReason,
         session: input.session,
+        summary: handoffSummary,
         targetAgentId: nextAgent.id,
         turn: input.turn
       });
-      await appendVoiceAgentTrace({
+      await appendVoiceAgentSquadHandoff({
         agentId: options.id,
-        event: {
-          fromAgentId: agent.id,
-          metadata,
-          originalTargetAgentId: originalTargetAgentId === nextAgent.id ? undefined : originalTargetAgentId,
-          reason: handoffReason,
-          status: "allowed",
-          targetAgentId: nextAgent.id
-        },
+        fromAgentId: agent.id,
+        handoffs,
+        metadata,
+        originalTargetAgentId: originalTargetAgentId === nextAgent.id ? undefined : originalTargetAgentId,
+        reason: handoffReason,
         session: input.session,
+        status: "allowed",
+        summary: handoffSummary,
+        targetAgentId: nextAgent.id,
         trace: options.trace,
-        turn: input.turn,
-        type: "agent.handoff"
+        turn: input.turn
       });
       await audit?.handoff({
         actor: {
@@ -7324,7 +7374,7 @@ var createVoiceAgentSquad = (options) => {
         toAgentId: nextAgent.id
       });
       messages.push({
-        content: handoffReason ?? `Handoff to ${nextAgent.id}`,
+        content: handoffSummary ?? handoffReason ?? `Handoff to ${nextAgent.id}`,
         metadata,
         name: nextAgent.id,
         role: "system"
@@ -7338,19 +7388,18 @@ var createVoiceAgentSquad = (options) => {
       toolResults.push(...result.toolResults);
     }
     if (result.handoff) {
-      await appendVoiceAgentTrace({
+      await appendVoiceAgentSquadHandoff({
         agentId: options.id,
-        event: {
-          fromAgentId: agent.id,
-          metadata: result.handoff.metadata,
-          reason: result.handoff.reason,
-          status: "max-exceeded",
-          targetAgentId: result.handoff.targetAgentId
-        },
+        fromAgentId: agent.id,
+        handoffs,
+        metadata: result.handoff.metadata,
+        reason: result.handoff.reason,
         session: input.session,
+        status: "max-exceeded",
+        summary: result.handoff.reason,
+        targetAgentId: result.handoff.targetAgentId,
         trace: options.trace,
-        turn: input.turn,
-        type: "agent.handoff"
+        turn: input.turn
       });
       await audit?.handoff({
         actor: {
@@ -7371,12 +7420,20 @@ var createVoiceAgentSquad = (options) => {
           reason: `Max handoffs exceeded: ${maxHandoffs}`
         },
         handoff: undefined,
+        squad: createVoiceAgentSquadState({
+          agentId: agent.id,
+          handoffs
+        }),
         toolResults
       };
     }
     return {
       ...result,
       agentId,
+      squad: createVoiceAgentSquadState({
+        agentId,
+        handoffs
+      }),
       toolResults
     };
   };
@@ -10059,8 +10116,24 @@ var summarizeVoiceBargeIn = (events, options = {}) => {
 };
 var renderVoiceBargeInHTML = (report, options = {}) => {
   const title = options.title ?? "Voice Barge-In";
+  const snippet = `const traceStore = createVoiceMemoryTraceEventStore();
+
+app.use(
+  createVoiceBargeInRoutes({
+    htmlPath: '/barge-in',
+    path: '/api/voice-barge-in',
+    store: traceStore,
+    thresholdMs: 250
+  })
+);
+
+// Browser/runtime side:
+const bargeInMonitor = createVoiceBargeInMonitor({
+  path: '/api/voice-barge-in',
+  sessionId
+});`;
   const sessions = report.sessions.length ? report.sessions.map((session) => `<tr><td>${escapeHtml10(session.sessionId)}</td><td>${String(session.total)}</td><td>${String(session.passed)}</td><td>${String(session.failed)}</td><td>${String(session.averageLatencyMs ?? 0)}ms</td></tr>`).join("") : '<tr><td colspan="5">No barge-in events yet.</td></tr>';
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml10(title)}</title><style>body{background:#101316;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1100px;padding:32px}.eyebrow{color:#5eead4;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.4rem,6vw,4.5rem);line-height:.92;margin:.2rem 0 1rem}.status{border:1px solid #475569;border-radius:999px;display:inline-flex;padding:8px 12px}.pass{color:#86efac}.warn{color:#fbbf24}.fail{color:#fca5a5}.empty{color:#cbd5e1}.metrics{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(170px,1fr));margin:20px 0}.metrics article{background:#181f27;border:1px solid #2b3642;border-radius:20px;padding:16px}.metrics span{color:#a8b0b8}.metrics strong{display:block;font-size:2rem}table{background:#181f27;border-collapse:collapse;border-radius:18px;overflow:hidden;width:100%}td,th{border-bottom:1px solid #2b3642;padding:12px;text-align:left}</style></head><body><main><p class="eyebrow">Interruption quality</p><h1>${escapeHtml10(title)}</h1><p class="status ${escapeHtml10(report.status)}">Status: ${escapeHtml10(report.status)}</p><section class="metrics"><article><span>Interruptions</span><strong>${String(report.total)}</strong></article><article><span>Avg latency</span><strong>${String(report.averageLatencyMs ?? 0)}ms</strong></article><article><span>Passed</span><strong>${String(report.passed)}</strong></article><article><span>Failed</span><strong>${String(report.failed)}</strong></article></section><table><thead><tr><th>Session</th><th>Total</th><th>Passed</th><th>Failed</th><th>Avg latency</th></tr></thead><tbody>${sessions}</tbody></table></main></body></html>`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml10(title)}</title><style>body{background:#101316;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1100px;padding:32px}.eyebrow{color:#5eead4;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.4rem,6vw,4.5rem);line-height:.92;margin:.2rem 0 1rem}.status{border:1px solid #475569;border-radius:999px;display:inline-flex;padding:8px 12px}.pass{color:#86efac}.warn{color:#fbbf24}.fail{color:#fca5a5}.empty{color:#cbd5e1}.metrics{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(170px,1fr));margin:20px 0}.metrics article,.primitive{background:#181f27;border:1px solid #2b3642;border-radius:20px;padding:16px}.metrics span{color:#a8b0b8}.metrics strong{display:block;font-size:2rem}.primitive{margin:0 0 20px}.primitive h2{margin:.2rem 0 .5rem}.primitive p{color:#cbd5e1}.primitive pre{background:#0a0d10;border:1px solid #2b3642;border-radius:16px;color:#d9fff7;overflow:auto;padding:16px}table{background:#181f27;border-collapse:collapse;border-radius:18px;overflow:hidden;width:100%}td,th{border-bottom:1px solid #2b3642;padding:12px;text-align:left}</style></head><body><main><p class="eyebrow">Interruption quality</p><h1>${escapeHtml10(title)}</h1><p class="status ${escapeHtml10(report.status)}">Status: ${escapeHtml10(report.status)}</p><section class="metrics"><article><span>Interruptions</span><strong>${String(report.total)}</strong></article><article><span>Avg latency</span><strong>${String(report.averageLatencyMs ?? 0)}ms</strong></article><article><span>Passed</span><strong>${String(report.passed)}</strong></article><article><span>Failed</span><strong>${String(report.failed)}</strong></article></section><section class="primitive"><p class="eyebrow">Copy into your app</p><h2><code>createVoiceBargeInRoutes(...)</code> proves interruption quality</h2><p>Use the shared trace store for browser interrupts, readiness gates, trace timelines, and production evidence instead of trusting a black-box hosted dashboard.</p><pre><code>${escapeHtml10(snippet)}</code></pre></section><table><thead><tr><th>Session</th><th>Total</th><th>Passed</th><th>Failed</th><th>Avg latency</th></tr></thead><tbody>${sessions}</tbody></table></main></body></html>`;
 };
 var createVoiceBargeInRoutes = (options) => {
   const path = options.path ?? "/api/voice-barge-in";
@@ -14417,9 +14490,16 @@ var getPayloadString2 = (event, key) => {
   const value = event.payload[key];
   return typeof value === "string" ? value : undefined;
 };
+var getPayloadRecord = (event, key) => {
+  const value = event.payload[key];
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+};
 var toHandoffExpectation = (event) => ({
   fromAgentId: getPayloadString2(event, "fromAgentId"),
+  metadata: getPayloadRecord(event, "metadata"),
+  reason: getPayloadString2(event, "reason"),
   status: getPayloadString2(event, "status"),
+  summary: getPayloadString2(event, "summary"),
   targetAgentId: getPayloadString2(event, "targetAgentId")
 });
 var createContractApi = (session) => ({
@@ -14449,6 +14529,28 @@ var appendIssue = (issues, issue, turnId) => {
     turnId: issue.turnId ?? turnId
   });
 };
+var assertIncludes = (input) => {
+  const actual = normalizeIncludes(input.actual?.join(" ") ?? "");
+  for (const expected of input.expected ?? []) {
+    if (!actual.includes(normalizeIncludes(expected))) {
+      appendIssue(input.issues, {
+        code: input.code,
+        message: `Expected handoff ${input.handoffIndex + 1} ${input.label} to include: ${expected}`
+      }, input.turnId);
+    }
+  }
+};
+var assertMetadata = (input) => {
+  for (const [key, expectedValue] of Object.entries(input.expected ?? {})) {
+    const actualValue = input.actual?.[key];
+    if (actualValue !== expectedValue) {
+      appendIssue(input.issues, {
+        code: "agent_squad.handoff_metadata_mismatch",
+        message: `Expected handoff ${input.handoffIndex + 1} metadata ${key} ${String(expectedValue)}, saw ${String(actualValue ?? "none")}.`
+      }, input.turnId);
+    }
+  }
+};
 var runVoiceAgentSquadContract = async (options) => {
   const session = options.session ?? createVoiceSessionRecord(`agent-squad-contract-${options.contract.id}`, options.contract.scenarioId ?? options.contract.id);
   const api = options.api ?? createContractApi(session);
@@ -14515,6 +14617,39 @@ var runVoiceAgentSquadContract = async (options) => {
           }, turn.id);
         }
       }
+      for (const key of ["reason", "summary"]) {
+        if (expectedHandoff[key] && actual[key] !== expectedHandoff[key]) {
+          appendIssue(turnIssues, {
+            code: `agent_squad.handoff_${key}_mismatch`,
+            message: `Expected handoff ${handoffIndex + 1} ${key} ${expectedHandoff[key]}, saw ${actual[key] ?? "none"}.`
+          }, turn.id);
+        }
+      }
+      assertIncludes({
+        actual: actual.reason ? [actual.reason] : undefined,
+        code: "agent_squad.handoff_reason_missing",
+        expected: expectedHandoff.reasonIncludes,
+        handoffIndex,
+        issues: turnIssues,
+        label: "reason",
+        turnId: turn.id
+      });
+      assertIncludes({
+        actual: actual.summary ? [actual.summary] : undefined,
+        code: "agent_squad.handoff_summary_missing",
+        expected: expectedHandoff.summaryIncludes,
+        handoffIndex,
+        issues: turnIssues,
+        label: "summary",
+        turnId: turn.id
+      });
+      assertMetadata({
+        actual: actual.metadata,
+        expected: expectedHandoff.metadata,
+        handoffIndex,
+        issues: turnIssues,
+        turnId: turn.id
+      });
     }
     for (const issue of expected?.result?.({
       result: result.result,
@@ -14672,11 +14807,29 @@ var summarizeVoiceTurnLatency = async (options) => {
 var formatMs = (value) => typeof value === "number" ? `${Math.round(value)}ms` : "n/a";
 var renderVoiceTurnLatencyHTML = (report, options = {}) => {
   const title = options.title ?? "Voice Turn Latency";
+  const snippet = `app.use(
+  createVoiceTurnLatencyRoutes({
+    failAfterMs: 3200,
+    htmlPath: '/turn-latency',
+    path: '/api/turn-latency',
+    store: sessionStore,
+    traceStore,
+    warnAfterMs: 1800
+  })
+);
+
+await traceStore.append({
+  at: Date.now(),
+  payload: { stage: 'assistant_audio_received' },
+  sessionId,
+  turnId,
+  type: 'turn_latency.stage'
+});`;
   const turns = report.turns.map((turn) => `<article class="turn ${escapeHtml24(turn.status)}">
   <header><div><p class="eyebrow">${escapeHtml24(turn.sessionId)} \xB7 ${escapeHtml24(turn.turnId)}</p><h2>${escapeHtml24(turn.text || "Empty turn")}</h2></div><strong>${escapeHtml24(turn.status)}</strong></header>
   <dl>${turn.stages.map((stage) => `<div><dt>${escapeHtml24(stage.label)}</dt><dd>${escapeHtml24(formatMs(stage.valueMs))}</dd></div>`).join("")}</dl>
 </article>`).join("");
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml24(title)}</title><style>body{background:#101316;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1180px;padding:32px}.hero,.turn{background:#181d22;border:1px solid #2a323a;border-radius:20px;margin-bottom:16px;padding:20px}.hero{background:linear-gradient(135deg,rgba(94,234,212,.16),rgba(251,191,36,.1))}.eyebrow{color:#5eead4;font-size:.78rem;font-weight:900;letter-spacing:.08em;text-transform:uppercase}h1{font-size:clamp(2.3rem,6vw,5rem);letter-spacing:-.06em;line-height:.9;margin:.2rem 0 1rem}h2{margin:.2rem 0 1rem}.summary{display:flex;flex-wrap:wrap;gap:10px}.pill{background:#0f1217;border:1px solid #3f3f46;border-radius:999px;padding:7px 10px}.turn header{align-items:flex-start;display:flex;gap:16px;justify-content:space-between}.pass{color:#86efac}.warn,.empty{color:#fde68a}.fail{color:#fca5a5}.turn.fail{border-color:rgba(248,113,113,.45)}dl{display:grid;gap:8px;grid-template-columns:repeat(auto-fit,minmax(160px,1fr))}dt{color:#a8b0b8;font-size:.8rem}dd{font-weight:900;margin:0}@media(max-width:800px){main{padding:18px}.turn header{display:block}}</style></head><body><main><section class="hero"><p class="eyebrow">End-to-end responsiveness</p><h1>${escapeHtml24(title)}</h1><div class="summary"><span class="pill ${escapeHtml24(report.status)}">${escapeHtml24(report.status)}</span><span class="pill">${String(report.total)} turns</span><span class="pill">avg ${escapeHtml24(formatMs(report.averageTotalMs))}</span><span class="pill">${String(report.warnings)} warnings</span><span class="pill">${String(report.failed)} failed</span></div></section>${turns || '<section class="turn"><p>No committed turns found.</p></section>'}</main></body></html>`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml24(title)}</title><style>body{background:#101316;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1180px;padding:32px}.hero,.turn,.primitive{background:#181d22;border:1px solid #2a323a;border-radius:20px;margin-bottom:16px;padding:20px}.hero{background:linear-gradient(135deg,rgba(94,234,212,.16),rgba(251,191,36,.1))}.eyebrow{color:#5eead4;font-size:.78rem;font-weight:900;letter-spacing:.08em;text-transform:uppercase}h1{font-size:clamp(2.3rem,6vw,5rem);letter-spacing:-.06em;line-height:.9;margin:.2rem 0 1rem}h2{margin:.2rem 0 1rem}.summary{display:flex;flex-wrap:wrap;gap:10px}.pill{background:#0f1217;border:1px solid #3f3f46;border-radius:999px;padding:7px 10px}.primitive p{color:#cbd5e1}.primitive pre{background:#0a0d10;border:1px solid #2a323a;border-radius:16px;color:#d9fff7;overflow:auto;padding:16px}.turn header{align-items:flex-start;display:flex;gap:16px;justify-content:space-between}.pass{color:#86efac}.warn,.empty{color:#fde68a}.fail{color:#fca5a5}.turn.fail{border-color:rgba(248,113,113,.45)}dl{display:grid;gap:8px;grid-template-columns:repeat(auto-fit,minmax(160px,1fr))}dt{color:#a8b0b8;font-size:.8rem}dd{font-weight:900;margin:0}@media(max-width:800px){main{padding:18px}.turn header{display:block}}</style></head><body><main><section class="hero"><p class="eyebrow">End-to-end responsiveness</p><h1>${escapeHtml24(title)}</h1><div class="summary"><span class="pill ${escapeHtml24(report.status)}">${escapeHtml24(report.status)}</span><span class="pill">${String(report.total)} turns</span><span class="pill">avg ${escapeHtml24(formatMs(report.averageTotalMs))}</span><span class="pill">${String(report.warnings)} warnings</span><span class="pill">${String(report.failed)} failed</span></div></section><section class="primitive"><p class="eyebrow">Copy into your app</p><h2><code>createVoiceTurnLatencyRoutes(...)</code> exposes the full turn waterfall</h2><p>Attach stage traces for speech detection, commit, model response, TTS send, and first audio so teams can prove where latency actually comes from.</p><pre><code>${escapeHtml24(snippet)}</code></pre></section>${turns || '<section class="turn"><p>No committed turns found.</p></section>'}</main></body></html>`;
 };
 var createVoiceTurnLatencyJSONHandler = (options) => async () => summarizeVoiceTurnLatency(options);
 var createVoiceTurnLatencyHTMLHandler = (options) => async () => {
@@ -14751,8 +14904,27 @@ var summarizeVoiceLiveLatency = async (options) => {
 var formatMs2 = (value) => typeof value === "number" ? `${Math.round(value)}ms` : "n/a";
 var renderVoiceLiveLatencyHTML = (report, options = {}) => {
   const title = options.title ?? "Voice Live Latency";
+  const snippet = `app.use(
+  createVoiceLiveLatencyRoutes({
+    failAfterMs: 3200,
+    htmlPath: '/live-latency',
+    path: '/api/live-latency',
+    store: traceStore,
+    warnAfterMs: 1800
+  })
+);
+
+await traceStore.append({
+  at: Date.now(),
+  payload: {
+    latencyMs,
+    status: 'assistant_audio_started'
+  },
+  sessionId,
+  type: 'client.live_latency'
+});`;
   const rows = report.recent.map((sample) => `<tr><td>${escapeHtml25(sample.sessionId)}</td><td>${escapeHtml25(formatMs2(sample.latencyMs))}</td><td>${escapeHtml25(sample.status ?? "unknown")}</td><td>${escapeHtml25(new Date(sample.at).toLocaleString())}</td></tr>`).join("");
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml25(title)}</title><style>body{background:#0c0f14;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1060px;padding:32px}.hero{background:linear-gradient(135deg,rgba(94,234,212,.16),rgba(245,158,11,.1));border:1px solid #26313d;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#5eead4;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.4rem,6vw,5rem);line-height:.9;margin:.2rem 0 1rem}.status{border:1px solid #3f3f46;border-radius:999px;display:inline-flex;padding:8px 12px}.pass{color:#86efac}.warn,.empty{color:#fbbf24}.fail{color:#fca5a5}.metrics{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(160px,1fr));margin:18px 0}.metrics article,table{background:#141922;border:1px solid #26313d;border-radius:18px}.metrics article{padding:16px}.metrics span{color:#a8b0b8}.metrics strong{display:block;font-size:2rem;margin-top:.25rem}table{border-collapse:collapse;overflow:hidden;width:100%}td,th{border-bottom:1px solid #26313d;padding:12px;text-align:left}@media(max-width:760px){main{padding:20px}}</style></head><body><main><section class="hero"><p class="eyebrow">Browser proof</p><h1>${escapeHtml25(title)}</h1><p>Recent real browser speech-to-assistant response measurements from persisted <code>client.live_latency</code> traces.</p><p class="status ${escapeHtml25(report.status)}">Status: ${escapeHtml25(report.status)}</p><section class="metrics"><article><span>p50</span><strong>${escapeHtml25(formatMs2(report.p50LatencyMs))}</strong></article><article><span>p95</span><strong>${escapeHtml25(formatMs2(report.p95LatencyMs))}</strong></article><article><span>Average</span><strong>${escapeHtml25(formatMs2(report.averageLatencyMs))}</strong></article><article><span>Samples</span><strong>${String(report.total)}</strong></article></section></section><table><thead><tr><th>Session</th><th>Latency</th><th>Status</th><th>Measured</th></tr></thead><tbody>${rows || '<tr><td colspan="4">No live latency samples yet.</td></tr>'}</tbody></table></main></body></html>`;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml25(title)}</title><style>body{background:#0c0f14;color:#f6f2e8;font-family:ui-sans-serif,system-ui,sans-serif;margin:0}main{margin:auto;max-width:1060px;padding:32px}.hero{background:linear-gradient(135deg,rgba(94,234,212,.16),rgba(245,158,11,.1));border:1px solid #26313d;border-radius:28px;margin-bottom:18px;padding:28px}.eyebrow{color:#5eead4;font-weight:900;letter-spacing:.12em;text-transform:uppercase}h1{font-size:clamp(2.4rem,6vw,5rem);line-height:.9;margin:.2rem 0 1rem}.status{border:1px solid #3f3f46;border-radius:999px;display:inline-flex;padding:8px 12px}.pass{color:#86efac}.warn,.empty{color:#fbbf24}.fail{color:#fca5a5}.metrics{display:grid;gap:14px;grid-template-columns:repeat(auto-fit,minmax(160px,1fr));margin:18px 0}.metrics article,table,.primitive{background:#141922;border:1px solid #26313d;border-radius:18px}.metrics article,.primitive{padding:16px}.metrics span{color:#a8b0b8}.metrics strong{display:block;font-size:2rem;margin-top:.25rem}.primitive{margin:0 0 18px}.primitive h2{margin:.2rem 0 .5rem}.primitive p{color:#cbd5e1}.primitive pre{background:#080b10;border:1px solid #26313d;border-radius:16px;color:#d9fff7;overflow:auto;padding:16px}table{border-collapse:collapse;overflow:hidden;width:100%}td,th{border-bottom:1px solid #26313d;padding:12px;text-align:left}@media(max-width:760px){main{padding:20px}}</style></head><body><main><section class="hero"><p class="eyebrow">Browser proof</p><h1>${escapeHtml25(title)}</h1><p>Recent real browser speech-to-assistant response measurements from persisted <code>client.live_latency</code> traces.</p><p class="status ${escapeHtml25(report.status)}">Status: ${escapeHtml25(report.status)}</p><section class="metrics"><article><span>p50</span><strong>${escapeHtml25(formatMs2(report.p50LatencyMs))}</strong></article><article><span>p95</span><strong>${escapeHtml25(formatMs2(report.p95LatencyMs))}</strong></article><article><span>Average</span><strong>${escapeHtml25(formatMs2(report.averageLatencyMs))}</strong></article><article><span>Samples</span><strong>${String(report.total)}</strong></article></section></section><section class="primitive"><p class="eyebrow">Copy into your app</p><h2><code>createVoiceLiveLatencyRoutes(...)</code> turns real browser timing into a release gate</h2><p>Persist live timing samples into the trace store so readiness, simulations, and trace timelines all point at the same self-hosted proof.</p><pre><code>${escapeHtml25(snippet)}</code></pre></section><table><thead><tr><th>Session</th><th>Latency</th><th>Status</th><th>Measured</th></tr></thead><tbody>${rows || '<tr><td colspan="4">No live latency samples yet.</td></tr>'}</tbody></table></main></body></html>`;
 };
 var createVoiceLiveLatencyRoutes = (options) => {
   const path = options.path ?? "/api/live-latency";

package/package.json

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