switchroom 0.13.51 → 0.13.53

package/telegram-plugin/tests/parallel-turns-deadlock-fix.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'vitest'
+
+/**
+ * PR3b regression pin: supergroup-mode parallel-turns deadlock fix.
+ *
+ * The bug. Pre-fix, the gateway used ONE map `activeTurnStartedAt`
+ * for two distinct concerns:
+ *   (a) "user-visible turn started" — set eagerly in the fresh-turn
+ *       branch on inbound RECEIPT, used by per-key reads (status-query
+ *       metric, wedge detection, progress timeout, etc.) that want a
+ *       receipt-side timestamp.
+ *   (b) "claude is currently busy on this turn" — the fleet-wide gate
+ *       at purgeReactionTracking / releaseTurnBufferGate /
+ *       idle-drain / inbound buffer-or-deliver, where `.size === 0`
+ *       means "claude is idle, safe to flush buffered inbound."
+ *
+ * Under fleet-shared / DM topology the two concerns coincide — every
+ * received inbound is delivered to claude — so the singleton worked.
+ *
+ * Under SUPERGROUP-OWNED topology (one agent owns the whole
+ * supergroup, multiple topics share the gateway process), they
+ * diverge:
+ *
+ *   1. Topic A delivers + processes — keyA in activeTurnStartedAt
+ *      (set on receipt) AND claudeBusyKeys (set on delivery).
+ *   2. Topic B inbound arrives → fresh-turn branch eagerly sets
+ *      keyB in activeTurnStartedAt, displays 👀 / starts typing.
+ *   3. `decideInboundDelivery` reads `turnInFlight = .size > 0` →
+ *      TRUE (keyA present) → B is buffered, NOT delivered to claude.
+ *   4. A's turn_end → purgeReactionTracking deletes keyA →
+ *      `.size === 0` check fires the held-inbound flush. BUT under
+ *      old (singleton) semantics, keyB is STILL in
+ *      activeTurnStartedAt (set in step 2, never cleared because B
+ *      never started in claude so no turn_end ever fires for B).
+ *   5. `.size > 0` (keyB lingers) → flush never runs → B's buffered
+ *      msg never delivered → B's user sees 👀 forever.
+ *
+ *   DEADLOCK.
+ *
+ * The fix splits concerns. `activeTurnStartedAt` keeps semantic (a)
+ * — set on receipt, all per-key reads use it. `claudeBusyKeys` (new)
+ * carries semantic (b) — set ONLY on successful sendToAgent
+ * (delivery), cleared on turn_end / disconnect / buffer-gate-release.
+ * Fleet gates switch to claudeBusyKeys. The deadlock breaks because
+ * step 5's gate now reads `claudeBusyKeys.size` which only ever held
+ * keyA (delivered) → after step 4's delete, size === 0 → flush →
+ * B's buffered msg delivered → claudeBusyKeys.add(keyB) → ... →
+ * B's eventual turn_end clears keyB.
+ *
+ * This test pins the load-bearing invariants. The actual wiring
+ * lives in `gateway.ts` and `disconnect-flush.ts`; this file is the
+ * structural-contract regression guard so a future "let's simplify
+ * the gates back to one map" refactor fails loudly here.
+ */
+
+describe('PR3b parallel-turns deadlock fix: claudeBusyKeys decoupled from activeTurnStartedAt', () => {
+  function makeState() {
+    const activeTurnStartedAt = new Map<string, number>()
+    const claudeBusyKeys = new Set<string>()
+    return { activeTurnStartedAt, claudeBusyKeys }
+  }
+
+  // Mirror the gateway's fresh-turn-on-receipt path (the part that
+  // updates the two maps). Stripped to ONLY the state mutations we
+  // care about for this invariant.
+  function receiveInbound(state: ReturnType<typeof makeState>, key: string, at: number): void {
+    state.activeTurnStartedAt.set(key, at)
+    // CRITICAL: claudeBusyKeys is NOT touched here. The whole point
+    // of the split is that receipt ≠ delivery.
+  }
+
+  function deliverToClaude(state: ReturnType<typeof makeState>, key: string): void {
+    // Mirror of markClaudeBusyForInbound at every successful
+    // sendToAgent callsite in gateway.ts.
+    state.claudeBusyKeys.add(key)
+  }
+
+  function turnEnd(state: ReturnType<typeof makeState>, key: string): void {
+    // Mirror of purgeReactionTracking + releaseTurnBufferGate —
+    // both maps cleared together at turn_end.
+    state.activeTurnStartedAt.delete(key)
+    state.claudeBusyKeys.delete(key)
+  }
+
+  function fleetGateOpen(state: ReturnType<typeof makeState>): boolean {
+    // Mirror of the four fleet-wide gates:
+    //   purgeReactionTracking line 1393:  if (claudeBusyKeys.size === 0)
+    //   releaseTurnBufferGate line 1484:  if (claudeBusyKeys.size === 0)
+    //   onScheduleRestart line 4020:      turnInFlight = .size > 0
+    //   idle-drain tick line 4343:        if (.size > 0) return false
+    //   handleInbound line 8087:          turnInFlightAtReceipt = .size > 0
+    return state.claudeBusyKeys.size === 0
+  }
+
+  it('pre-fix scenario: singleton map deadlocks supergroup-mode parallel turns', () => {
+    // Simulate the BROKEN behavior — one map serving both concerns
+    // (i.e. what would happen if claudeBusyKeys did NOT exist and
+    // the gates read activeTurnStartedAt.size). This is the
+    // *opposite* of the test below; documents what we're fixing.
+    const legacyState = new Map<string, number>()
+    const legacyFleetGate = () => legacyState.size === 0
+
+    // Step 1: A delivered (eager set on receipt)
+    legacyState.set('keyA', 100)
+    // Step 2: B received but buffered (eager set fires regardless)
+    legacyState.set('keyB', 200)
+    expect(legacyFleetGate()).toBe(false)
+
+    // Step 4: A's turn_end clears keyA
+    legacyState.delete('keyA')
+    // DEADLOCK — keyB lingers forever because B never started
+    // in claude so no turn_end ever fires for B.
+    expect(legacyFleetGate()).toBe(false)
+    expect(legacyState.has('keyB')).toBe(true)
+  })
+
+  it('post-fix scenario: split maps let A.turn_end unblock B', () => {
+    const state = makeState()
+
+    // Step 1: A's inbound received AND delivered to claude.
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    expect(state.activeTurnStartedAt.has('keyA')).toBe(true)
+    expect(state.claudeBusyKeys.has('keyA')).toBe(true)
+
+    // Step 2: B's inbound received, but `decideInboundDelivery`
+    // returned buffer-until-idle (turnInFlightAtReceipt was true
+    // because keyA is in claudeBusyKeys). B's fresh-turn branch
+    // STILL fired — eager activeTurnStartedAt[keyB] set —
+    // for the user-visible 👀 / typing indicator.
+    receiveInbound(state, 'keyB', 200)
+    // CRITICAL: claudeBusyKeys does NOT contain keyB because B was
+    // buffered, not delivered. The split semantics is the entire
+    // PR3b contract.
+    expect(state.activeTurnStartedAt.has('keyB')).toBe(true)
+    expect(state.claudeBusyKeys.has('keyB')).toBe(false)
+    expect(state.claudeBusyKeys.size).toBe(1)
+    expect(fleetGateOpen(state)).toBe(false)
+
+    // Step 4: A's turn_end clears keyA from BOTH maps.
+    turnEnd(state, 'keyA')
+
+    // Step 5 (the deadlock fix): fleet gate now OPENS because
+    // claudeBusyKeys is empty, even though activeTurnStartedAt
+    // still has keyB (which is fine — that's the user-visible
+    // receipt timestamp, not the claude-busy flag).
+    expect(state.claudeBusyKeys.size).toBe(0)
+    expect(state.activeTurnStartedAt.has('keyB')).toBe(true)
+    expect(fleetGateOpen(state)).toBe(true)
+
+    // The flush triggers → B's buffered msg gets sent →
+    // deliverToClaude fires for keyB → busy gate closes again.
+    deliverToClaude(state, 'keyB')
+    expect(fleetGateOpen(state)).toBe(false)
+
+    // B's turn_end completes the cycle.
+    turnEnd(state, 'keyB')
+    expect(state.activeTurnStartedAt.size).toBe(0)
+    expect(state.claudeBusyKeys.size).toBe(0)
+    expect(fleetGateOpen(state)).toBe(true)
+  })
+
+  it('per-key reads (priorTurnStartedAt timing, status-query metric) keep working on activeTurnStartedAt', () => {
+    // The split must not regress per-key timestamp reads. These all
+    // want the RECEIPT timestamp (the user's send-time, not when
+    // claude finally got to it), so they correctly read
+    // activeTurnStartedAt — preserved across the buffer window.
+    const state = makeState()
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    receiveInbound(state, 'keyB', 200) // buffered, no deliverToClaude
+
+    // A second message on keyB arriving during the buffer window —
+    // mid-turn classification reads activeTurnStartedAt.get(keyB)
+    // for `priorTurnStartedAt`, which must still be 200 (the
+    // original receipt time, even though B never reached claude).
+    expect(state.activeTurnStartedAt.get('keyB')).toBe(200)
+    // And keyA's receipt timestamp is preserved too — A's
+    // follow-ups during its own processing window get accurate
+    // secondsSinceTurnStart metric.
+    expect(state.activeTurnStartedAt.get('keyA')).toBe(100)
+  })
+
+  it('disconnect-flush sweeps both maps together (the bridge died, all in-flight turns are dead)', () => {
+    // Mirror of the disconnect-flush sweep loop in disconnect-flush.ts —
+    // a registered-agent disconnect clears both maps because every
+    // turn it was processing is dead by definition.
+    const state = makeState()
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    receiveInbound(state, 'keyB', 200) // buffered
+
+    // Bridge dies (claude crashed mid-A). Sweep both maps.
+    for (const k of [...state.activeTurnStartedAt.keys()]) {
+      state.activeTurnStartedAt.delete(k)
+      state.claudeBusyKeys.delete(k)
+    }
+
+    expect(state.activeTurnStartedAt.size).toBe(0)
+    expect(state.claudeBusyKeys.size).toBe(0)
+    expect(fleetGateOpen(state)).toBe(true)
+  })
+
+  it('idempotent: multiple inbounds for the same key (e.g. A user spamming) are a single entry', () => {
+    // Set semantics — A's 5 follow-up messages while A is processing
+    // collapse to a single claudeBusyKeys entry. Turn_end clears
+    // once; size accounting stays correct.
+    const state = makeState()
+    receiveInbound(state, 'keyA', 100)
+    deliverToClaude(state, 'keyA')
+    deliverToClaude(state, 'keyA')
+    deliverToClaude(state, 'keyA')
+    expect(state.claudeBusyKeys.size).toBe(1)
+    turnEnd(state, 'keyA')
+    expect(state.claudeBusyKeys.size).toBe(0)
+  })
+})

package/telegram-plugin/tests/typing-wrap.test.ts

@@ -2,8 +2,11 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createTypingWrapper } from '../typing-wrap.js'
 
 function makeDeps(overrides: { isSurfaceTool?: (name: string) => boolean } = {}) {
-  const startTypingLoop = vi.fn<(chatId: string) => void>()
-  const stopTypingLoop = vi.fn<(chatId: string) => void>()
+  // PR3 supergroup-mode: start/stop now take (chatId, threadId?). The
+  // existing tests cover the chatId-only case (threadId omitted → null);
+  // new tests below pin the per-thread isolation.
+  const startTypingLoop = vi.fn<(chatId: string, threadId?: number | null) => void>()
+  const stopTypingLoop = vi.fn<(chatId: string, threadId?: number | null) => void>()
   const isSurfaceTool =
     overrides.isSurfaceTool ??
     ((name: string) =>
@@ -28,7 +31,7 @@ describe('createTypingWrapper', () => {
     w.onToolUse('t1', 'chat-A', 'Bash')
     // First tool on a fresh chat fires immediately — no timer wait required.
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)
-    expect(deps.startTypingLoop).toHaveBeenCalledWith('chat-A')
+    expect(deps.startTypingLoop).toHaveBeenCalledWith('chat-A', null)
   })
 
   it('a parallel second tool on the same chat uses the debounce', () => {
@@ -69,7 +72,7 @@ describe('createTypingWrapper', () => {
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)
     w.onToolResult('t1')
     expect(deps.stopTypingLoop).toHaveBeenCalledTimes(1)
-    expect(deps.stopTypingLoop).toHaveBeenCalledWith('chat-A')
+    expect(deps.stopTypingLoop).toHaveBeenCalledWith('chat-A', null)
   })
 
   it('skips surface tools (reply/stream_reply/edit_message/react)', () => {
@@ -93,16 +96,16 @@ describe('createTypingWrapper', () => {
     w.onToolUse('t1', 'chat-A', 'Bash')
     w.onToolUse('t2', 'chat-B', 'Grep')
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
-    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(1, 'chat-A')
-    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(2, 'chat-B')
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(1, 'chat-A', null)
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(2, 'chat-B', null)
 
     w.onToolResult('t1')
     expect(deps.stopTypingLoop).toHaveBeenCalledTimes(1)
-    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-A')
+    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-A', null)
 
     w.onToolResult('t2')
     expect(deps.stopTypingLoop).toHaveBeenCalledTimes(2)
-    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-B')
+    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-B', null)
   })
 
   it('drainAll clears pending entries and stops any started loops', () => {
@@ -138,4 +141,58 @@ describe('createTypingWrapper', () => {
     vi.advanceTimersByTime(2)
     expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
   })
+
+  // ─── PR3 supergroup-mode: per-(chat,thread) lane isolation ────────────
+  it('SAME chat + DIFFERENT threads each get their own immediate-fire lane', () => {
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    // Both are "first tool on lane" — both fire immediately, not debounced.
+    w.onToolUse('t1', 'chat-A', 'Bash', 17)
+    w.onToolUse('t2', 'chat-A', 'Read', 23)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(1, 'chat-A', 17)
+    expect(deps.startTypingLoop).toHaveBeenNthCalledWith(2, 'chat-A', 23)
+  })
+
+  it('SAME chat + SAME thread STILL uses debounce on the second tool', () => {
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    w.onToolUse('t1', 'chat-A', 'Bash', 17)
+    w.onToolUse('t2', 'chat-A', 'Read', 17)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)
+    vi.advanceTimersByTime(500)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
+  })
+
+  it('stopping topic A does NOT clear topic B\'s lane (the headline bug fix)', () => {
+    // The bug: chatId-only keying meant `activeChats.delete(chatId)`
+    // when topic A's tool ended ALSO marked topic B's lane as inactive,
+    // so topic B's next tool would re-fire immediately (wrong — it's
+    // already typing) and a subsequent stop could mismatch.
+    // Per-(chat,thread) lane keying preserves independence.
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    w.onToolUse('t1', 'chat-A', 'Bash', 17)   // topic A lane: active
+    w.onToolUse('t2', 'chat-A', 'Read', 23)   // topic B lane: active (independent)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)
+
+    w.onToolResult('t1')  // topic A done
+    expect(deps.stopTypingLoop).toHaveBeenLastCalledWith('chat-A', 17)
+    // Topic B is still active — a third tool on topic B should DEBOUNCE
+    // (lane is still active), not fire immediately.
+    w.onToolUse('t3', 'chat-A', 'Edit', 23)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(2)  // no immediate fire
+    vi.advanceTimersByTime(500)
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(3)
+    expect(deps.startTypingLoop).toHaveBeenLastCalledWith('chat-A', 23)
+  })
+
+  it('treats undefined / null threadId as the same lane (chatKey null/0 collapse)', () => {
+    const deps = makeDeps()
+    const w = createTypingWrapper(deps)
+    w.onToolUse('t1', 'chat-A', 'Bash')           // undefined thread
+    w.onToolUse('t2', 'chat-A', 'Read', null)     // null thread — same lane
+    expect(deps.startTypingLoop).toHaveBeenCalledTimes(1)  // only first fires immediately
+    expect(deps.startTypingLoop).toHaveBeenLastCalledWith('chat-A', null)
+  })
 })

package/telegram-plugin/typing-wrap.ts

@@ -1,26 +1,43 @@
 // Auto-wrap tool dispatch with a Telegram typing-indicator loop so the user
 // sees a live "agent is working" signal during the 3–30s gap where the
 // progress card is deliberately suppressed (its initialDelayMs is 3s).
-// The first tool call on a given chat fires the typing loop immediately so
-// there's no silent dead window before the progress card appears. Subsequent
-// calls on the same chat honour the debounce to avoid churn.
-// Surface tools own their own loop — see isSurfaceTool.
+// The first tool call on a given (chat, thread) fires the typing loop
+// immediately so there's no silent dead window before the progress card
+// appears. Subsequent calls on the same lane honour the debounce to avoid
+// churn. Surface tools own their own loop — see isSurfaceTool.
+//
+// Keying changed from `chatId` to `(chatId, threadId)` in PR3 of the
+// supergroup-mode rollout. In supergroup mode one agent owns many topics
+// in one chat; chatId-only keying made topic A's typing indicator die when
+// topic B's tool-call ended (last-stop-wins on a shared key). Per-thread
+// keying preserves independent typing loops across topics — matches the
+// per-(chat,thread) state model the rest of the gateway already uses.
+// Callers that don't yet carry a thread context pass `undefined` and
+// behave exactly as before (null thread collapses to `_` per chatKey()).
+
+import { chatKey } from './gateway/chat-key.js'
 
 export interface TypingWrapperDeps {
-  startTypingLoop: (chatId: string) => void
-  stopTypingLoop: (chatId: string) => void
+  startTypingLoop: (chatId: string, threadId?: number | null) => void
+  stopTypingLoop: (chatId: string, threadId?: number | null) => void
   isSurfaceTool: (toolName: string) => boolean
   debounceMs?: number
 }
 
 export interface TypingWrapper {
-  onToolUse: (toolUseId: string, chatId: string, toolName: string) => void
+  onToolUse: (
+    toolUseId: string,
+    chatId: string,
+    toolName: string,
+    threadId?: number | null,
+  ) => void
   onToolResult: (toolUseId: string) => void
   drainAll: () => void
 }
 
 interface Entry {
   chatId: string
+  threadId: number | null
   timer: ReturnType<typeof setTimeout>
   started: boolean
 }
@@ -28,29 +45,33 @@ interface Entry {
 export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
   const debounceMs = deps.debounceMs ?? 500
   const pending = new Map<string, Entry>()
-  // Track chats that already have an active typing loop so the first
-  // tool call fires immediately while subsequent calls use the debounce.
-  const activeChats = new Set<string>()
+  // Track per-(chat,thread) lanes that already have an active typing loop
+  // so the first tool call on a lane fires immediately while subsequent
+  // calls on the same lane use the debounce.
+  const activeLanes = new Set<string>()
 
   return {
-    onToolUse(toolUseId, chatId, toolName) {
+    onToolUse(toolUseId, chatId, toolName, threadId) {
       if (!toolUseId) return
       if (deps.isSurfaceTool(toolName)) return
+      const tid = threadId ?? null
+      const lane = chatKey(chatId, tid) as string
       // Replace any pre-existing entry for the same id defensively.
       const prior = pending.get(toolUseId)
       if (prior) {
         clearTimeout(prior.timer)
-        if (prior.started) deps.stopTypingLoop(prior.chatId)
+        if (prior.started) deps.stopTypingLoop(prior.chatId, prior.threadId)
         pending.delete(toolUseId)
       }
-      // First tool on this chat: fire immediately rather than waiting for
+      // First tool on this lane: fire immediately rather than waiting for
       // the debounce — this closes the silent dead window before the first
       // progress card appears.
-      if (!activeChats.has(chatId)) {
-        deps.startTypingLoop(chatId)
-        activeChats.add(chatId)
+      if (!activeLanes.has(lane)) {
+        deps.startTypingLoop(chatId, tid)
+        activeLanes.add(lane)
         const entry: Entry = {
           chatId,
+          threadId: tid,
           started: true,
           timer: setTimeout(() => {}, 0), // no-op sentinel
         }
@@ -59,9 +80,10 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
       }
       const entry: Entry = {
         chatId,
+        threadId: tid,
         started: false,
         timer: setTimeout(() => {
-          deps.startTypingLoop(chatId)
+          deps.startTypingLoop(chatId, tid)
           entry.started = true
         }, debounceMs),
       }
@@ -74,8 +96,8 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
       if (!entry) return
       clearTimeout(entry.timer)
       if (entry.started) {
-        deps.stopTypingLoop(entry.chatId)
-        activeChats.delete(entry.chatId)
+        deps.stopTypingLoop(entry.chatId, entry.threadId)
+        activeLanes.delete(chatKey(entry.chatId, entry.threadId) as string)
       }
       pending.delete(toolUseId)
     },
@@ -83,10 +105,10 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
     drainAll() {
       for (const entry of pending.values()) {
         clearTimeout(entry.timer)
-        if (entry.started) deps.stopTypingLoop(entry.chatId)
+        if (entry.started) deps.stopTypingLoop(entry.chatId, entry.threadId)
       }
       pending.clear()
-      activeChats.clear()
+      activeLanes.clear()
     },
   }
 }