@absolutejs/voice 0.0.22-beta.622 → 0.0.22-beta.624

package/dist/core/types.d.ts

@@ -803,6 +803,28 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
     sttRecoveryLine?: string | ((input: {
         session: TSession;
     }) => string | Promise<string>);
+    stuckCallClose?: {
+        afterMs: number;
+        line?: string | ((input: {
+            session: TSession;
+        }) => string | Promise<string>);
+        reason?: string;
+    };
+    /** Gentle re-engagement before a silent call is given up on. When the caller
+     *  makes no progress (no committed turn / user partial) for `afterMs`, the
+     *  assistant speaks `line` ("still there?") instead of ending, and the close
+     *  deadline (stuckCallClose) is pushed out — up to `maxReprompts` times (default
+     *  1). After the budget is spent the normal close path runs. Caller speech
+     *  resets the budget. Assistant speech does NOT, so this can only extend a
+     *  bounded amount. `afterMs` should be < stuckCallClose.afterMs so the nudge
+     *  fires first. */
+    idleReprompt?: {
+        afterMs: number;
+        line: string | ((input: {
+            session: TSession;
+        }) => string | Promise<string>);
+        maxReprompts?: number;
+    };
     languageStrategy?: VoiceLanguageStrategy;
     lexicon?: VoiceLexiconEntry[] | VoiceLexiconResolver<TContext>;
     phraseHints?: VoicePhraseHint[] | VoicePhraseHintResolver<TContext>;
@@ -958,6 +980,35 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     sttRecoveryLine?: string | ((input: {
         session: TSession;
     }) => string | Promise<string>);
+    /** Last-resort GRACEFUL terminal close for a wedged call. If no caller-side
+     *  progress (committed turn / user partial) lands for `afterMs` on a live call
+     *  — STT permanently deaf, or the caller left — the assistant speaks `line` and
+     *  the session COMPLETES (disposition "completed") so onComplete still saves and
+     *  the call ends with a real goodbye instead of dead air + "abandoned". Reset by
+     *  real progress (committed turn / user partial / (re)connect), NOT by the
+     *  assistant's own speech, so STT recovery re-prompts can't defer it forever. */
+    stuckCallClose?: {
+        afterMs: number;
+        line?: string | ((input: {
+            session: TSession;
+        }) => string | Promise<string>);
+        reason?: string;
+    };
+    /** Gentle re-engagement before a silent call is given up on. When the caller
+     *  makes no progress (no committed turn / user partial) for `afterMs`, the
+     *  assistant speaks `line` ("still there?") instead of ending, and the close
+     *  deadline (stuckCallClose) is pushed out — up to `maxReprompts` times (default
+     *  1). After the budget is spent the normal close path runs. Caller speech
+     *  resets the budget. Assistant speech does NOT, so this can only extend a
+     *  bounded amount. `afterMs` should be < stuckCallClose.afterMs so the nudge
+     *  fires first. */
+    idleReprompt?: {
+        afterMs: number;
+        line: string | ((input: {
+            session: TSession;
+        }) => string | Promise<string>);
+        maxReprompts?: number;
+    };
     stt?: STTAdapter;
     realtime?: RealtimeAdapter;
     realtimeInputFormat?: AudioFormat;

package/dist/index.js

@@ -4186,6 +4186,90 @@ var createVoiceSession = (options) => {
     clearCallSilenceWatchdog();
     callSilenceWatchdog = setTimeout(fireCallSilenceTimeout, callSilenceTimeoutMs);
   };
+  const stuckCloseConfig = options.stuckCallClose;
+  const stuckCloseAfterMs = stuckCloseConfig && stuckCloseConfig.afterMs > 0 ? stuckCloseConfig.afterMs : undefined;
+  let stuckCloseWatchdog = null;
+  let stuckCloseFired = false;
+  const clearStuckCloseWatchdog = () => {
+    if (stuckCloseWatchdog) {
+      clearTimeout(stuckCloseWatchdog);
+      stuckCloseWatchdog = null;
+    }
+  };
+  const fireStuckClose = () => {
+    stuckCloseWatchdog = null;
+    if (stuckCloseFired) {
+      return;
+    }
+    stuckCloseFired = true;
+    runSerial("stuck-call-close", async () => {
+      const snapshot = await readSession();
+      if (snapshot.status === "completed" || snapshot.status === "failed" || snapshot.call?.endedAt) {
+        return;
+      }
+      await appendTrace({
+        payload: {
+          action: "stuck-call-close",
+          reason: `no caller progress for ${stuckCloseAfterMs}ms`
+        },
+        session: snapshot,
+        type: "session.error"
+      });
+      if (stuckCloseConfig?.line) {
+        await speakResolvedLine(stuckCloseConfig.line, snapshot);
+      }
+      await completeInternal(undefined, {
+        disposition: "completed",
+        reason: stuckCloseConfig?.reason ?? "stuck-call-close"
+      });
+    });
+  };
+  const kickStuckCloseWatchdog = () => {
+    if (stuckCloseAfterMs === undefined || stuckCloseFired) {
+      return;
+    }
+    clearStuckCloseWatchdog();
+    stuckCloseWatchdog = setTimeout(fireStuckClose, stuckCloseAfterMs);
+  };
+  const idleRepromptConfig = options.idleReprompt;
+  const idleRepromptAfterMs = idleRepromptConfig && idleRepromptConfig.afterMs > 0 ? idleRepromptConfig.afterMs : undefined;
+  const idleRepromptMax = Math.max(1, idleRepromptConfig?.maxReprompts ?? 1);
+  let idleRepromptsUsed = 0;
+  let idleRepromptWatchdog = null;
+  const clearIdleRepromptWatchdog = () => {
+    if (idleRepromptWatchdog) {
+      clearTimeout(idleRepromptWatchdog);
+      idleRepromptWatchdog = null;
+    }
+  };
+  const kickIdleRepromptWatchdog = (resetBudget = false) => {
+    if (idleRepromptAfterMs === undefined) {
+      return;
+    }
+    if (resetBudget) {
+      idleRepromptsUsed = 0;
+    }
+    clearIdleRepromptWatchdog();
+    if (idleRepromptsUsed >= idleRepromptMax) {
+      return;
+    }
+    idleRepromptWatchdog = setTimeout(() => {
+      idleRepromptWatchdog = null;
+      if (idleRepromptConfig === undefined || idleRepromptsUsed >= idleRepromptMax) {
+        return;
+      }
+      runSerial("idle-reprompt", async () => {
+        const snapshot = await readSession();
+        if (snapshot.status === "completed" || snapshot.status === "failed" || snapshot.call?.endedAt) {
+          return;
+        }
+        idleRepromptsUsed += 1;
+        await speakResolvedLine(idleRepromptConfig.line, snapshot);
+        kickStuckCloseWatchdog();
+        kickIdleRepromptWatchdog();
+      });
+    }, idleRepromptAfterMs);
+  };
   const recordingConfig = options.recording;
   const recordingChannels = new Set(recordingConfig?.channels ?? ["assistant", "user"]);
   const recordingMaxBytes = recordingConfig?.maxBytesPerChannel ?? 50 * 1024 * 1024;
@@ -4682,6 +4766,8 @@ var createVoiceSession = (options) => {
       type: "error"
     });
     clearCallSilenceWatchdog();
+    clearStuckCloseWatchdog();
+    clearIdleRepromptWatchdog();
     clearAmdEvaluationTimer();
     await closeTTSSession("failed");
     await closeAdapter("failed");
@@ -4791,6 +4877,8 @@ var createVoiceSession = (options) => {
       type: "complete"
     });
     clearCallSilenceWatchdog();
+    clearStuckCloseWatchdog();
+    clearIdleRepromptWatchdog();
     clearAmdEvaluationTimer();
     await closeTTSSession("complete");
     await closeAdapter("complete");
@@ -5268,6 +5356,10 @@ var createVoiceSession = (options) => {
     };
   };
   const handlePartial = async (transcript) => {
+    if (transcript.text.trim()) {
+      kickStuckCloseWatchdog();
+      kickIdleRepromptWatchdog(true);
+    }
     if (activeTTSTurnId !== undefined) {
       const triggeringText = transcript.text.trim();
       if (triggeringText) {
@@ -5742,6 +5834,8 @@ var createVoiceSession = (options) => {
   };
   const completeTurn = async (session, turn) => {
     console.error(`[voice] completeTurn ENTER session=${options.id} turn=${turn.id} textLen=${turn.text?.length ?? 0}`);
+    kickStuckCloseWatchdog();
+    kickIdleRepromptWatchdog(true);
     const liveOpsControl = await options.liveOps?.getControl(options.id);
     if (liveOpsControl?.assistantPaused || liveOpsControl?.operatorTakeover) {
       await appendTrace({
@@ -6443,6 +6537,8 @@ var createVoiceSession = (options) => {
     await ensureAdapter();
     warmTTSSession();
     kickCallSilenceWatchdog();
+    kickStuckCloseWatchdog();
+    kickIdleRepromptWatchdog(true);
     startAmdEvaluationTimer();
     if (options.greeting && session.turns.length === 0) {
       await speakResolvedLine(options.greeting, session);
@@ -6588,6 +6684,8 @@ var createVoiceSession = (options) => {
     });
     clearSilenceTimer();
     clearCallSilenceWatchdog();
+    clearStuckCloseWatchdog();
+    clearIdleRepromptWatchdog();
     clearAmdEvaluationTimer();
     if (options.noiseSuppressor?.close) {
       try {
@@ -39705,6 +39803,7 @@ var voice = (config) => {
       greeting: config.greeting,
       resumeGreeting: config.resumeGreeting,
       sttRecoveryLine: config.sttRecoveryLine,
+      stuckCallClose: config.stuckCallClose,
       handoff: config.handoff,
       languageStrategy: config.languageStrategy,
       lexicon,

package/dist/testing/index.js

@@ -6506,6 +6506,90 @@ var createVoiceSession = (options) => {
     clearCallSilenceWatchdog();
     callSilenceWatchdog = setTimeout(fireCallSilenceTimeout, callSilenceTimeoutMs);
   };
+  const stuckCloseConfig = options.stuckCallClose;
+  const stuckCloseAfterMs = stuckCloseConfig && stuckCloseConfig.afterMs > 0 ? stuckCloseConfig.afterMs : undefined;
+  let stuckCloseWatchdog = null;
+  let stuckCloseFired = false;
+  const clearStuckCloseWatchdog = () => {
+    if (stuckCloseWatchdog) {
+      clearTimeout(stuckCloseWatchdog);
+      stuckCloseWatchdog = null;
+    }
+  };
+  const fireStuckClose = () => {
+    stuckCloseWatchdog = null;
+    if (stuckCloseFired) {
+      return;
+    }
+    stuckCloseFired = true;
+    runSerial("stuck-call-close", async () => {
+      const snapshot = await readSession();
+      if (snapshot.status === "completed" || snapshot.status === "failed" || snapshot.call?.endedAt) {
+        return;
+      }
+      await appendTrace({
+        payload: {
+          action: "stuck-call-close",
+          reason: `no caller progress for ${stuckCloseAfterMs}ms`
+        },
+        session: snapshot,
+        type: "session.error"
+      });
+      if (stuckCloseConfig?.line) {
+        await speakResolvedLine(stuckCloseConfig.line, snapshot);
+      }
+      await completeInternal(undefined, {
+        disposition: "completed",
+        reason: stuckCloseConfig?.reason ?? "stuck-call-close"
+      });
+    });
+  };
+  const kickStuckCloseWatchdog = () => {
+    if (stuckCloseAfterMs === undefined || stuckCloseFired) {
+      return;
+    }
+    clearStuckCloseWatchdog();
+    stuckCloseWatchdog = setTimeout(fireStuckClose, stuckCloseAfterMs);
+  };
+  const idleRepromptConfig = options.idleReprompt;
+  const idleRepromptAfterMs = idleRepromptConfig && idleRepromptConfig.afterMs > 0 ? idleRepromptConfig.afterMs : undefined;
+  const idleRepromptMax = Math.max(1, idleRepromptConfig?.maxReprompts ?? 1);
+  let idleRepromptsUsed = 0;
+  let idleRepromptWatchdog = null;
+  const clearIdleRepromptWatchdog = () => {
+    if (idleRepromptWatchdog) {
+      clearTimeout(idleRepromptWatchdog);
+      idleRepromptWatchdog = null;
+    }
+  };
+  const kickIdleRepromptWatchdog = (resetBudget = false) => {
+    if (idleRepromptAfterMs === undefined) {
+      return;
+    }
+    if (resetBudget) {
+      idleRepromptsUsed = 0;
+    }
+    clearIdleRepromptWatchdog();
+    if (idleRepromptsUsed >= idleRepromptMax) {
+      return;
+    }
+    idleRepromptWatchdog = setTimeout(() => {
+      idleRepromptWatchdog = null;
+      if (idleRepromptConfig === undefined || idleRepromptsUsed >= idleRepromptMax) {
+        return;
+      }
+      runSerial("idle-reprompt", async () => {
+        const snapshot = await readSession();
+        if (snapshot.status === "completed" || snapshot.status === "failed" || snapshot.call?.endedAt) {
+          return;
+        }
+        idleRepromptsUsed += 1;
+        await speakResolvedLine(idleRepromptConfig.line, snapshot);
+        kickStuckCloseWatchdog();
+        kickIdleRepromptWatchdog();
+      });
+    }, idleRepromptAfterMs);
+  };
   const recordingConfig = options.recording;
   const recordingChannels = new Set(recordingConfig?.channels ?? ["assistant", "user"]);
   const recordingMaxBytes = recordingConfig?.maxBytesPerChannel ?? 50 * 1024 * 1024;
@@ -7002,6 +7086,8 @@ var createVoiceSession = (options) => {
       type: "error"
     });
     clearCallSilenceWatchdog();
+    clearStuckCloseWatchdog();
+    clearIdleRepromptWatchdog();
     clearAmdEvaluationTimer();
     await closeTTSSession("failed");
     await closeAdapter("failed");
@@ -7111,6 +7197,8 @@ var createVoiceSession = (options) => {
       type: "complete"
     });
     clearCallSilenceWatchdog();
+    clearStuckCloseWatchdog();
+    clearIdleRepromptWatchdog();
     clearAmdEvaluationTimer();
     await closeTTSSession("complete");
     await closeAdapter("complete");
@@ -7588,6 +7676,10 @@ var createVoiceSession = (options) => {
     };
   };
   const handlePartial = async (transcript) => {
+    if (transcript.text.trim()) {
+      kickStuckCloseWatchdog();
+      kickIdleRepromptWatchdog(true);
+    }
     if (activeTTSTurnId !== undefined) {
       const triggeringText = transcript.text.trim();
       if (triggeringText) {
@@ -8062,6 +8154,8 @@ var createVoiceSession = (options) => {
   };
   const completeTurn = async (session, turn) => {
     console.error(`[voice] completeTurn ENTER session=${options.id} turn=${turn.id} textLen=${turn.text?.length ?? 0}`);
+    kickStuckCloseWatchdog();
+    kickIdleRepromptWatchdog(true);
     const liveOpsControl = await options.liveOps?.getControl(options.id);
     if (liveOpsControl?.assistantPaused || liveOpsControl?.operatorTakeover) {
       await appendTrace({
@@ -8763,6 +8857,8 @@ var createVoiceSession = (options) => {
     await ensureAdapter();
     warmTTSSession();
     kickCallSilenceWatchdog();
+    kickStuckCloseWatchdog();
+    kickIdleRepromptWatchdog(true);
     startAmdEvaluationTimer();
     if (options.greeting && session.turns.length === 0) {
       await speakResolvedLine(options.greeting, session);
@@ -8908,6 +9004,8 @@ var createVoiceSession = (options) => {
     });
     clearSilenceTimer();
     clearCallSilenceWatchdog();
+    clearStuckCloseWatchdog();
+    clearIdleRepromptWatchdog();
     clearAmdEvaluationTimer();
     if (options.noiseSuppressor?.close) {
       try {

package/package.json

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