@kuralle-syrinx/server-websocket 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/server-websocket",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "private": false,
   "description": "Node WebSocket voice host for Syrinx — browser transport plus Twilio/Telnyx/SmartPBX telephony adapters, background audio, admission control",
   "keywords": [
@@ -35,8 +35,8 @@
   "dependencies": {
     "@evan/opus": "1.0.3",
     "ws": "^8.21.0",
-    "@kuralle-syrinx/core": "4.3.0",
-    "@kuralle-syrinx/ws": "4.3.0"
+    "@kuralle-syrinx/core": "4.4.0",
+    "@kuralle-syrinx/ws": "4.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/edge.ts

@@ -37,6 +37,7 @@ import {
   resampleAudioBytes,
   socketDataToBytes,
 } from "./inbound-audio.js";
+import { TurnMetricsTracker, type TurnTimestampState } from "./turn-metrics.js";
 
 /**
  * Sink for per-conversation audio recording. The edge taps inbound caller audio
@@ -287,6 +288,7 @@ export async function runVoiceEdgeWebSocketConnection(
       socket,
       disposers,
       outputSampleRateHz,
+      leased.managed.turnMetricsTurns,
       options.recorder,
       options.backgroundAudio ? new BackgroundAudioMixer(options.backgroundAudio) : undefined,
     );
@@ -372,10 +374,24 @@ function wireEdgeSessionEvents(
   socket: ManagedSocket,
   disposers: Array<() => void>,
   outputSampleRateHz: number,
+  turnMetricsTurns: Map<string, TurnTimestampState>,
   recorder?: EdgeRecorder,
   backgroundAudio?: BackgroundAudioMixer,
 ): void {
   if (backgroundAudio) wireBackgroundAudio(session, backgroundAudio);
+
+  // Same per-turn latency decomposition the Node websocket path emits (turn-metrics.ts) —
+  // the browser/edge protocol is shared, so the `metrics` message must be too. Unlike
+  // Node, this transport is client-paced (no server-side pacer guarantees a
+  // `tts.playout_progress` completion), so also finalize on `tts.end` — see
+  // TurnMetricsTrackerOptions.finalizeOnTtsEnd.
+  const turnMetrics = new TurnMetricsTracker(
+    session.bus,
+    (message) => sendJson(socket, message),
+    turnMetricsTurns,
+    { finalizeOnTtsEnd: true },
+  );
+  turnMetrics.wire(disposers);
   const onSession = <K extends keyof VoiceAgentSessionEvents>(
     event: K,
     handler: VoiceAgentSessionEvents[K],

package/src/turn-metrics.ts

@@ -8,8 +8,11 @@ import {
   type PipelineBus,
   type SttResultPacket,
   type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
   type TextToSpeechPlayoutProgressPacket,
   type TextToSpeechPlayoutStartedPacket,
+  type TurnEndOwner,
+  type TurnEndReason,
   type VadSpeechEndedPacket,
 } from "@kuralle-syrinx/core";
 
@@ -22,6 +25,12 @@ export interface TurnTimestampState {
   firstAudioByteMs: number;
   firstAudioPlayedMs: number;
   lastAudioPlayedMs: number;
+  /** Who decided the turn ended — captured from the completing eos packet. */
+  endpointingOwner?: TurnEndOwner;
+  /** Why the turn ended — captured from the completing eos packet. */
+  endpointingReason?: TurnEndReason;
+  /** Set when the STT force-finalize watchdog fired for this turn. */
+  forceFinalized?: boolean;
 }
 
 export interface BrowserMetricsMessage {
@@ -43,8 +52,36 @@ export interface BrowserMetricsMessage {
     readonly endpointDelayMs?: number;
     readonly totalMs?: number;
   };
+  /** Which owner decided the turn ended. Omitted when the backend did not say. */
+  readonly endpointingOwner?: TurnEndOwner;
+  /** Why the turn ended. Omitted when the backend did not say. */
+  readonly endpointingReason?: TurnEndReason;
 }
 
+/**
+ * The field set `buildBrowserMetricsMessage` populates for an audio-originated turn
+ * (`vad.speech_ended` + `stt.result` + `llm.delta` + `tts.audio` all measured) —
+ * everything EXCEPT `firstAudioPlayedMs`/`lastAudioPlayedMs`, which depend on a
+ * playout-completion signal whose *source* legitimately differs per transport
+ * (Node's browser websocket path paces server-side; the Workers/DO edge path is
+ * client-paced). Both runtimes call this same builder and must emit this same core
+ * set; the parity tests in both packages assert against this constant so a runtime
+ * that silently drops the `metrics` message, or diverges in shape, fails loudly.
+ */
+export const CORE_METRICS_FIELDS = [
+  "type",
+  "turnId",
+  "correlationId",
+  "speechEndMs",
+  "textReadyMs",
+  "firstAudioByteMs",
+  "sttMs",
+  "llmTTFTMs",
+  "ttsTTFBMs",
+  "e2eMs",
+  "eouBudgetMs",
+] as const;
+
 function positiveDelta(endMs: number, startMs: number): number | undefined {
   if (endMs <= 0 || startMs <= 0 || endMs < startMs) return undefined;
   return endMs - startMs;
@@ -81,6 +118,15 @@ export function buildBrowserMetricsMessage(
         }
       : undefined;
 
+  // The endpointing decision is a fact about the turn, not a timing measurement, so
+  // it is emitted whenever it is known — never coerced to a zero. A force-finalize
+  // watchdog firing overrides the emitter's reason: the STT plugin that produced the
+  // completing eos cannot know the watchdog fired, but this mark (stt.force_finalized)
+  // arrives independently on the bus, so the truth wins here regardless of emitter.
+  const endpointingOwner = timestamps.endpointingOwner;
+  const endpointingReason =
+    timestamps.forceFinalized === true ? "force_finalized" : timestamps.endpointingReason;
+
   return {
     type: "metrics",
     turnId,
@@ -95,6 +141,8 @@ export function buildBrowserMetricsMessage(
     ...(ttsTTFBMs !== undefined ? { ttsTTFBMs } : {}),
     ...(e2eFromPlayout !== undefined ? { e2eMs: e2eFromPlayout } : e2eFromByte !== undefined ? { e2eMs: e2eFromByte } : {}),
     ...(eouBudgetMs !== undefined ? { eouBudgetMs } : {}),
+    ...(endpointingOwner !== undefined ? { endpointingOwner } : {}),
+    ...(endpointingReason !== undefined ? { endpointingReason } : {}),
   };
 }
 
@@ -111,6 +159,23 @@ function emptyTurnState(): TurnTimestampState {
   };
 }
 
+export interface TurnMetricsTrackerOptions {
+  /**
+   * Additionally finalize (emit + clear) a turn's metrics on `tts.end` when no
+   * `tts.playout_progress` completion has arrived yet. The Node browser websocket
+   * path always gets a `tts.playout_progress` completion shortly after `tts.end`
+   * from its own server-side pacer (playout-progress.ts) — turning this on there
+   * would race a premature, playout-less emission ahead of the real one, so it
+   * defaults off and Node leaves it unset. The Workers/DO edge path is
+   * client-paced (the browser reports playout over the wire); a client that never
+   * reports it — a non-browser client, or a text-only smoke probe — would
+   * otherwise leave a turn's metrics pending forever, so edge opts in. If a
+   * richer client-reported completion arrives after this floor already fired,
+   * it is a no-op: the turn was already finalized and cleared.
+   */
+  readonly finalizeOnTtsEnd?: boolean;
+}
+
 export class TurnMetricsTracker {
   private readonly turns: Map<string, TurnTimestampState>;
 
@@ -118,6 +183,7 @@ export class TurnMetricsTracker {
     private readonly bus: PipelineBus,
     private readonly onEmit: (message: BrowserMetricsMessage) => void,
     persistedTurns?: Map<string, TurnTimestampState>,
+    private readonly options: TurnMetricsTrackerOptions = {},
   ) {
     this.turns = persistedTurns ?? new Map();
   }
@@ -136,16 +202,29 @@ export class TurnMetricsTracker {
       }),
       this.bus.on("metric.conversation", (pkt) => {
         const metric = pkt as ConversationMetricPacket;
-        if (metric.name !== "vad.stop_hangover_ms") return;
-        const hangoverMs = Number(metric.value);
-        if (Number.isNaN(hangoverMs)) return;
-        const state = this.turnState(metric.contextId);
-        if (state.vadStopHangoverMs === 0) state.vadStopHangoverMs = hangoverMs;
+        if (metric.name === "vad.stop_hangover_ms") {
+          const hangoverMs = Number(metric.value);
+          if (Number.isNaN(hangoverMs)) return;
+          const state = this.turnState(metric.contextId);
+          if (state.vadStopHangoverMs === 0) state.vadStopHangoverMs = hangoverMs;
+          return;
+        }
+        if (metric.name === "stt.force_finalized") {
+          this.turnState(metric.contextId).forceFinalized = true;
+        }
       }),
       this.bus.on("eos.turn_complete", (pkt) => {
         const eos = pkt as EndOfSpeechPacket;
         const state = this.turnState(eos.contextId);
         if (state.eosMs === 0) state.eosMs = eos.timestampMs;
+        // First eos wins (mirrors eosMs): the completing eos is the first, and any
+        // duplicate is dropped downstream. Owner/reason are facts, not measurements.
+        if (state.endpointingOwner === undefined && eos.endpointingOwner !== undefined) {
+          state.endpointingOwner = eos.endpointingOwner;
+        }
+        if (state.endpointingReason === undefined && eos.endpointingReason !== undefined) {
+          state.endpointingReason = eos.endpointingReason;
+        }
       }),
       this.bus.on("llm.delta", (pkt) => {
         const delta = pkt as LlmDeltaPacket;
@@ -170,12 +249,35 @@ export class TurnMetricsTracker {
         const progress = pkt as TextToSpeechPlayoutProgressPacket;
         const state = this.turns.get(progress.contextId);
         if (!state) return;
+        // The edge transport never emits `tts.playout_started` — the browser reports
+        // its own playout clock and that is forwarded here (edge.ts). So take the
+        // first progress report as the moment audio started playing. On the Node path
+        // `playout_started` has already set this, and the `=== 0` guard leaves it be.
+        if (state.firstAudioPlayedMs === 0) state.firstAudioPlayedMs = progress.timestampMs;
         if (progress.complete) {
           state.lastAudioPlayedMs = progress.timestampMs;
           this.onEmit(buildBrowserMetricsMessage(progress.contextId, state));
           this.turns.delete(progress.contextId);
         }
       }),
+      this.bus.on("tts.end", (pkt) => {
+        if (!this.options.finalizeOnTtsEnd) return;
+        const end = pkt as TextToSpeechEndPacket;
+        const state = this.turns.get(end.contextId);
+        if (!state) return;
+        // `tts.end` means synthesis finished, which is EARLIER than playback finishing.
+        // So if this client is pacing playout, firing here would emit a poorer message
+        // and delete the turn before the real completion arrived — costing
+        // firstAudioPlayedMs, lastAudioPlayedMs, and downgrading e2eMs from
+        // "to first audio played" to "to first byte" on this runtime only. That is the
+        // exact runtime drift this tracker exists to prevent.
+        //
+        // A non-zero firstAudioPlayedMs means playout has been reported, so wait.
+        // The floor is only for clients that never report at all.
+        if (state.firstAudioPlayedMs !== 0) return;
+        this.onEmit(buildBrowserMetricsMessage(end.contextId, state));
+        this.turns.delete(end.contextId);
+      }),
       this.bus.on("interrupt.tts", (pkt) => {
         this.turns.delete((pkt as InterruptTtsPacket).contextId);
       }),