feat(typing): add TTL safety-net for stuck indicators (land #27428, thanks @Crpdim)

Co-authored-by: Crpdim <crpdim@users.noreply.github.com>

src/channels/typing.test.ts

@@ -109,4 +109,156 @@ describe("createTypingCallbacks", () => {
       vi.useRealTimers();
     }
   });
+
+  // ========== TTL Safety Tests ==========
+  describe("TTL safety", () => {
+    it("auto-stops typing after maxDurationMs", async () => {
+      vi.useFakeTimers();
+      try {
+        const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const start = vi.fn().mockResolvedValue(undefined);
+        const stop = vi.fn().mockResolvedValue(undefined);
+        const onStartError = vi.fn();
+        const callbacks = createTypingCallbacks({
+          start,
+          stop,
+          onStartError,
+          maxDurationMs: 10_000,
+        });
+
+        await callbacks.onReplyStart();
+        expect(start).toHaveBeenCalledTimes(1);
+        expect(stop).not.toHaveBeenCalled();
+
+        // Advance past TTL
+        await vi.advanceTimersByTimeAsync(10_000);
+
+        // Should auto-stop
+        expect(stop).toHaveBeenCalledTimes(1);
+        expect(consoleWarn).toHaveBeenCalledWith(expect.stringContaining("TTL exceeded"));
+
+        consoleWarn.mockRestore();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("does not auto-stop if idle is called before TTL", async () => {
+      vi.useFakeTimers();
+      try {
+        const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const start = vi.fn().mockResolvedValue(undefined);
+        const stop = vi.fn().mockResolvedValue(undefined);
+        const onStartError = vi.fn();
+        const callbacks = createTypingCallbacks({
+          start,
+          stop,
+          onStartError,
+          maxDurationMs: 10_000,
+        });
+
+        await callbacks.onReplyStart();
+
+        // Stop before TTL
+        await vi.advanceTimersByTimeAsync(5_000);
+        callbacks.onIdle?.();
+        await flushMicrotasks();
+
+        expect(stop).toHaveBeenCalledTimes(1);
+
+        // Advance past original TTL
+        await vi.advanceTimersByTimeAsync(10_000);
+
+        // Should not have triggered TTL warning
+        expect(consoleWarn).not.toHaveBeenCalled();
+        // Stop should still be called only once
+        expect(stop).toHaveBeenCalledTimes(1);
+
+        consoleWarn.mockRestore();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("uses default 60s TTL when not specified", async () => {
+      vi.useFakeTimers();
+      try {
+        const start = vi.fn().mockResolvedValue(undefined);
+        const stop = vi.fn().mockResolvedValue(undefined);
+        const onStartError = vi.fn();
+        const callbacks = createTypingCallbacks({ start, stop, onStartError });
+
+        await callbacks.onReplyStart();
+
+        // Should not stop at 59s
+        await vi.advanceTimersByTimeAsync(59_000);
+        expect(stop).not.toHaveBeenCalled();
+
+        // Should stop at 60s
+        await vi.advanceTimersByTimeAsync(1_000);
+        expect(stop).toHaveBeenCalledTimes(1);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("disables TTL when maxDurationMs is 0", async () => {
+      vi.useFakeTimers();
+      try {
+        const start = vi.fn().mockResolvedValue(undefined);
+        const stop = vi.fn().mockResolvedValue(undefined);
+        const onStartError = vi.fn();
+        const callbacks = createTypingCallbacks({
+          start,
+          stop,
+          onStartError,
+          maxDurationMs: 0,
+        });
+
+        await callbacks.onReplyStart();
+
+        // Should not auto-stop even after long time
+        await vi.advanceTimersByTimeAsync(300_000);
+        expect(stop).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it("resets TTL timer on restart after idle", async () => {
+      vi.useFakeTimers();
+      try {
+        const start = vi.fn().mockResolvedValue(undefined);
+        const stop = vi.fn().mockResolvedValue(undefined);
+        const onStartError = vi.fn();
+        const callbacks = createTypingCallbacks({
+          start,
+          stop,
+          onStartError,
+          maxDurationMs: 10_000,
+        });
+
+        // First start
+        await callbacks.onReplyStart();
+        await vi.advanceTimersByTimeAsync(5_000);
+
+        // Idle and restart
+        callbacks.onIdle?.();
+        await flushMicrotasks();
+        expect(stop).toHaveBeenCalledTimes(1);
+
+        // Reset mock to track second start
+        stop.mockClear();
+
+        // After stop, callbacks are closed, so new onReplyStart should be no-op
+        await callbacks.onReplyStart();
+        await vi.advanceTimersByTimeAsync(15_000);
+
+        // Should not trigger stop again since it's closed
+        expect(stop).not.toHaveBeenCalled();
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+  });
 });

src/channels/typing.ts

@@ -3,21 +3,27 @@ import { createTypingKeepaliveLoop } from "./typing-lifecycle.js";
 export type TypingCallbacks = {
   onReplyStart: () => Promise<void>;
   onIdle?: () => void;
-  /** Called when the typing controller is cleaned up (e.g., on NO_REPLY). */
+  /** Called when the typing controller is cleaned up (e.g. on NO_REPLY). */
   onCleanup?: () => void;
 };
 
-export function createTypingCallbacks(params: {
+export type CreateTypingCallbacksParams = {
   start: () => Promise<void>;
   stop?: () => Promise<void>;
   onStartError: (err: unknown) => void;
   onStopError?: (err: unknown) => void;
   keepaliveIntervalMs?: number;
-}): TypingCallbacks {
+  /** Maximum duration for typing indicator before auto-cleanup (safety TTL). Default: 60s */
+  maxDurationMs?: number;
+};
+
+export function createTypingCallbacks(params: CreateTypingCallbacksParams): TypingCallbacks {
   const stop = params.stop;
   const keepaliveIntervalMs = params.keepaliveIntervalMs ?? 3_000;
+  const maxDurationMs = params.maxDurationMs ?? 60_000; // Default 60s TTL
   let stopSent = false;
   let closed = false;
+  let ttlTimer: ReturnType<typeof setTimeout> | undefined;
 
   const fireStart = async () => {
     if (closed) {
@@ -35,19 +41,43 @@ export function createTypingCallbacks(params: {
     onTick: fireStart,
   });
 
+  // TTL safety: auto-stop typing after maxDurationMs
+  const startTtlTimer = () => {
+    if (maxDurationMs <= 0) {
+      return;
+    }
+    clearTtlTimer();
+    ttlTimer = setTimeout(() => {
+      if (!closed) {
+        console.warn(`[typing] TTL exceeded (${maxDurationMs}ms), auto-stopping typing indicator`);
+        fireStop();
+      }
+    }, maxDurationMs);
+  };
+
+  const clearTtlTimer = () => {
+    if (ttlTimer) {
+      clearTimeout(ttlTimer);
+      ttlTimer = undefined;
+    }
+  };
+
   const onReplyStart = async () => {
     if (closed) {
       return;
     }
     stopSent = false;
     keepaliveLoop.stop();
+    clearTtlTimer();
     await fireStart();
     keepaliveLoop.start();
+    startTtlTimer(); // Start TTL safety timer
   };
 
   const fireStop = () => {
     closed = true;
     keepaliveLoop.stop();
+    clearTtlTimer(); // Clear TTL timer on normal stop
     if (!stop || stopSent) {
       return;
     }