@kuralle-syrinx/core 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/core",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "private": false,
   "description": "Voice pipeline kernel for Syrinx — pipeline bus, turn arbitration, playout clock, packets, and the framework-agnostic Reasoner seam",
   "keywords": [

package/src/index.ts

@@ -39,6 +39,8 @@ export {
   type EndOfSpeechPacket,
   type InterimEndOfSpeechPacket,
   type EndOfSpeechRetractedPacket,
+  type TurnEndOwner,
+  type TurnEndReason,
   type UserInputPacket,
 } from "./packets.js";
 

package/src/interaction-coordinator.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 
 import type { VadAudioPacket } from "./packets.js";
-import type { SttInterimPacket, SttResultPacket } from "./packets.js";
+import type { SttInterimPacket, SttResultPacket, TurnEndOwner, TurnEndReason } from "./packets.js";
 import { Route } from "./pipeline-bus.js";
 import type { PipelineBus } from "./pipeline-bus.js";
 import { confidenceToWaitMs } from "./confidence-to-wait.js";
@@ -41,6 +41,10 @@ export class InteractionCoordinator {
       isTtsActive?: () => boolean;
       hasCueAsset?: (cueId: string) => boolean;
       onBackchannelEmitted?: (contextId: string) => void;
+      /** Session's configured endpointing owner — labels every eos this coordinator emits. */
+      endpointingOwner?: TurnEndOwner;
+      /** True when the STT force-finalize watchdog already fired for this context. */
+      wasForceFinalized?: (contextId: string) => boolean;
     },
   ) {
     this.scheduler = deps.scheduler ?? new TimerScheduler();
@@ -180,7 +184,18 @@ export class InteractionCoordinator {
         live.transcripts.length > 0
           ? live.transcripts
           : [{ kind: "stt.result", contextId, timestampMs: Date.now(), text: finalText, confidence: 0 }];
-      this.deps.bus.push(Route.Main, make.eosTurnComplete(contextId, Date.now(), finalText, transcripts));
+      // The policy committed to this turn, so the endpointing decision is genuinely
+      // known here — label who decided and why. A force-finalize watchdog firing
+      // underneath us is a different diagnosis from a natural endpoint.
+      const configuredOwner = this.deps.endpointingOwner;
+      const forced = this.deps.wasForceFinalized?.(contextId) === true;
+      const reason: TurnEndReason = forced ? "force_finalized" : "end_of_speech";
+      const endpointing =
+        configuredOwner === undefined ? undefined : { owner: configuredOwner, reason };
+      this.deps.bus.push(
+        Route.Main,
+        make.eosTurnComplete(contextId, Date.now(), finalText, transcripts, endpointing),
+      );
     });
   }
 

package/src/packet-factories.ts

@@ -29,6 +29,8 @@ import type {
   SpeechToTextAudioPacket,
   EndOfSpeechAudioPacket,
   EndOfSpeechPacket,
+  TurnEndOwner,
+  TurnEndReason,
   SttPartialPacket,
   SttResultPacket,
   FinalizeSttPacket,
@@ -220,8 +222,19 @@ export function eosTurnComplete(
   timestampMs: number,
   text: string,
   transcripts: readonly SttResultPacket[],
+  endpointing?: { readonly owner: TurnEndOwner; readonly reason: TurnEndReason },
 ): EndOfSpeechPacket {
-  return { kind: "eos.turn_complete", contextId, timestampMs, text, transcripts };
+  return endpointing === undefined
+    ? { kind: "eos.turn_complete", contextId, timestampMs, text, transcripts }
+    : {
+        kind: "eos.turn_complete",
+        contextId,
+        timestampMs,
+        text,
+        transcripts,
+        endpointingOwner: endpointing.owner,
+        endpointingReason: endpointing.reason,
+      };
 }
 
 export function finalizeStt(contextId: string, timestampMs: number): FinalizeSttPacket {

package/src/packets.ts

@@ -10,7 +10,7 @@
 //   Lifecycle:              InitStepCompleted, InitFailed, InitCompleted
 
 import type { WordTiming } from "./interaction-policy.js";
-import type { SttReconfigurePartial } from "./plugin-contract.js";
+import type { EndpointingOwner, SttReconfigurePartial } from "./plugin-contract.js";
 
 // =============================================================================
 // Base Types
@@ -220,11 +220,34 @@ export interface EndOfSpeechAudioPacket extends VoicePacket {
   readonly audio: Uint8Array;
 }
 
+/**
+ * Who decided a turn ended. Extends {@link EndpointingOwner} with the two
+ * non-plugin regimes: `"timer"` (a realtime front owns its own turn
+ * detection) and `"text"` (the user typed — no endpointer fired at all).
+ *
+ * Absent means genuinely unknown: never fabricate an owner the backend did
+ * not measure. A debugging surface that guesses is worse than one that says so.
+ */
+export type TurnEndOwner = EndpointingOwner | "timer" | "text";
+
+/**
+ * Why a turn ended, paired with {@link TurnEndOwner}.
+ * - `end_of_speech` — an endpointer marked natural end of speech.
+ * - `force_finalized` — the STT was force-finalized by the
+ *   `sttForceFinalizeTimeoutMs` watchdog (a timeout), not a natural endpoint.
+ * - `typed` — the turn came from typed input; no speech was endpointed.
+ */
+export type TurnEndReason = "end_of_speech" | "force_finalized" | "typed";
+
 export interface EndOfSpeechPacket extends VoicePacket {
   readonly kind: "eos.turn_complete";
   readonly text: string;
   /** All accumulated STT transcripts for this turn. */
   readonly transcripts: readonly SttResultPacket[];
+  /** Which owner decided the turn ended. Omitted when genuinely unknown. */
+  readonly endpointingOwner?: TurnEndOwner;
+  /** Why the turn ended. Omitted when genuinely unknown. */
+  readonly endpointingReason?: TurnEndReason;
 }
 
 export interface InterimEndOfSpeechPacket extends VoicePacket {

package/src/voice-agent-session-util.ts

@@ -81,6 +81,8 @@ export class VoiceSessionWatchdogs {
   private readonly scheduler: Scheduler;
   private sttForceFinalizeScheduled = false;
   private pendingSttContextId = "";
+  /** Contexts whose STT the force-finalize watchdog has already fired on this turn. */
+  private readonly forceFinalizedContexts = new Set<string>();
   private vaqiMissedResponseScheduled = false;
   private vaqiMissedResponseContextId = "";
   private vaqiMissedResponseStartMs = 0;
@@ -98,6 +100,7 @@ export class VoiceSessionWatchdogs {
     this.clearVaqiMissedResponseTimer();
     this.clearTtsStallTimer();
     this.clearInputCadenceWatchdog();
+    this.forceFinalizedContexts.clear();
   }
 
   scheduleSttForceFinalize(contextId: string): void {
@@ -109,11 +112,26 @@ export class VoiceSessionWatchdogs {
     this.sttForceFinalizeScheduled = true;
     this.scheduler.schedule("voice.watchdog.stt_force_finalize", this.deps.sttForceFinalizeTimeoutMs, () => {
       this.sttForceFinalizeScheduled = false;
+      this.forceFinalizedContexts.add(contextId);
+      // Broadcast the decision on the bus: the completing eos may come from the STT
+      // plugin (which cannot know the watchdog fired), so the metrics tracker reads
+      // this mark to label the turn rather than each emitter re-deriving it.
+      this.deps.bus.push(Route.Background, make.metric(contextId, "stt.force_finalized", "1"));
       const plugin = findForceFinalizableSttPlugin(this.deps.plugins);
       plugin?.forceFinalize(contextId);
     });
   }
 
+  /** True when the force-finalize watchdog has already fired for this context this turn. */
+  wasForceFinalized(contextId: string): boolean {
+    return this.forceFinalizedContexts.has(contextId);
+  }
+
+  /** Retire the flag once the turn has completed (read by the emitter + metrics tracker). */
+  clearForceFinalized(contextId: string): void {
+    this.forceFinalizedContexts.delete(contextId);
+  }
+
   clearSttForceFinalizeIfContext(contextId: string): void {
     if (this.pendingSttContextId === contextId) {
       this.clearSttForceFinalizeTimer();

package/src/voice-agent-session.ts

@@ -511,6 +511,8 @@ export class VoiceAgentSession {
       onBackchannelEmitted: (contextId) => {
         this.timingFor(contextId).backchannelUsed = true;
       },
+      endpointingOwner: this.endpointingOwner,
+      wasForceFinalized: (contextId) => this.watchdogs.wasForceFinalized(contextId),
     });
     this.watchdogs = new VoiceSessionWatchdogs({
       bus: this.bus,
@@ -874,8 +876,16 @@ export class VoiceAgentSession {
   }
 
   private handleUserText(pkt: UserTextReceivedPacket): void {
-    // Treat text input as an immediate EOS turn complete
-    this.bus.push(Route.Main, make.eosTurnComplete(pkt.contextId, pkt.timestampMs, pkt.text, []));
+    // Typed input is an immediate turn end — but nothing endpointed it and no one
+    // decided the caller stopped talking, because they typed. Label it as `text` so
+    // the timeline never claims a speech endpointer fired on a typed turn.
+    this.bus.push(
+      Route.Main,
+      make.eosTurnComplete(pkt.contextId, pkt.timestampMs, pkt.text, [], {
+        owner: "text",
+        reason: "typed",
+      }),
+    );
   }
 
   private handleSttPartial(pkt: SttPartialPacket): void {
@@ -1179,6 +1189,10 @@ export class VoiceAgentSession {
     }
     this.lastFinalizedContextId = pkt.contextId;
     this.interaction.reset(pkt.contextId);
+    // The force-finalize flag has now been read by whoever emitted this eos (and
+    // captured by the metrics tracker via its metric) — retire it so the per-call
+    // Set does not grow unbounded on a stable transport contextId.
+    this.watchdogs.clearForceFinalized(pkt.contextId);
 
     // Re-arm per-turn guard state for the next turn. Transports with a stable
     // per-call contextId (telephony callSid) reuse one id across turns, so these