switchroom 0.12.29 → 0.13.1

package/telegram-plugin/gateway/gateway.ts

@@ -1278,32 +1278,62 @@ function streamKey(chatId: string, threadId?: number | null): string {
   return chatKey(chatId, threadId)
 }
 
-function purgeReactionTracking(key: string, endingTurn?: CurrentTurn): void {
-  // Phase 2b: turn end. The key was registered via setTurnStarted when
-  // the inbound arrived; purge is the canonical turn-end signal.
-  //
-  // outboundEmitted: read from the explicit `endingTurn` parameter when
-  // provided (canonical path via endCurrentTurnAtomic — module-scope
-  // currentTurn is already null by the time we get here), falling back
-  // to `currentTurn?.replyCalled` for the legacy callsites that haven't
-  // been threaded yet (sibling-key purges, restart-init cleanup).
-  // Without this explicit-turn handoff the shadow trace would report
-  // outboundEmitted=false on every replied turn (the dominant happy
-  // path), producing strictly worse data than the blind `true` it
-  // replaced. Invariant #5's `lastOutboundAt` correctness depends on
-  // this signal being accurate.
-  const outboundEmitted = endingTurn != null
-    ? endingTurn.replyCalled === true
-    : currentTurn?.replyCalled === true
-  shadowEmit({ kind: 'turnEnd', key: key as _ChatKey, at: Date.now(), outboundEmitted })
+/**
+ * Reaction-state cleanup — controller + msg-id maps + active-reaction
+ * file removal. PURE reaction-cleanup, no turn-end semantics:
+ *   - does NOT emit shadow `turnEnd`
+ *   - does NOT clear `activeTurnStartedAt` (turn-active marker)
+ *   - does NOT fire the model-idle restart/flush gate
+ *
+ * Called from mid-turn signals like `endStatusReaction` (post-reply-tool,
+ * post-stream-reply-finalize) where the 👍 transition fires but the
+ * turn is still active. Per #1603 audit step 2: the reply tool was
+ * previously calling `purgeReactionTracking` here, which fired premature
+ * shadow `turnEnd` events and cleared `activeTurnStartedAt` mid-turn —
+ * the latter would trigger the model-idle restart probe and
+ * pendingInbound flush as if claude had gone idle.
+ */
+function clearReactionState(key: string): void {
   const msgInfo = activeReactionMsgIds.get(key)
   activeStatusReactions.delete(key)
   activeReactionMsgIds.delete(key)
-  activeTurnStartedAt.delete(key)
   if (msgInfo) {
     const agentDir = resolveAgentDirFromEnv()
     if (agentDir != null) removeActiveReaction(agentDir, msgInfo.chatId, msgInfo.messageId)
   }
+}
+
+function purgeReactionTracking(
+  key: string,
+  endingTurn?: CurrentTurn,
+  outboundEmittedOverride?: boolean,
+): void {
+  // Phase 2b: turn end. The key was registered via setTurnStarted when
+  // the inbound arrived; purge is the canonical turn-end signal.
+  //
+  // outboundEmitted derivation, in precedence order:
+  //   1. Explicit `outboundEmittedOverride` (e.g. silence-poke
+  //      framework fallback FORCES false because the 5-min fallback
+  //      firing proves visible delivery never happened — regardless of
+  //      whatever `replyCalled` the wedged turn object carries).
+  //   2. `endingTurn.replyCalled` when the canonical caller threads
+  //      the authoritative turn (endCurrentTurnAtomic path; module-scope
+  //      currentTurn is already null by the time we get here).
+  //   3. `currentTurn?.replyCalled` fallback for the (now-vanishing)
+  //      legacy callsites. Without the explicit-turn handoff the shadow
+  //      trace would report outboundEmitted=false on every replied
+  //      turn (the dominant happy path), producing strictly worse data
+  //      than the blind `true` it replaced. Invariant #5's
+  //      `lastOutboundAt` correctness depends on this signal being
+  //      accurate.
+  const outboundEmitted = outboundEmittedOverride !== undefined
+    ? outboundEmittedOverride
+    : endingTurn != null
+      ? endingTurn.replyCalled === true
+      : currentTurn?.replyCalled === true
+  shadowEmit({ kind: 'turnEnd', key: key as _ChatKey, at: Date.now(), outboundEmitted })
+  clearReactionState(key)
+  activeTurnStartedAt.delete(key)
 
   // If no more active turns and a restart is pending, perform it now.
   //
@@ -1593,12 +1623,24 @@ async function resolveCompactCard(
 }
 
 function endStatusReaction(chatId: string, threadId: number | undefined, outcome: 'done' | 'error'): void {
+  // Mid-turn signal: the reply tool fired, or stream_reply finalized,
+  // and the status-reaction needs to transition to its terminal emoji
+  // (👍 / ⚠️). The turn itself is still active — the canonical turn-end
+  // signal is `endCurrentTurnAtomic(turn)`, which runs later via the
+  // turn_end handler / context-exhaust path / silent-marker path.
+  //
+  // Pre-#1603 audit step 2 (this commit), this called
+  // `purgeReactionTracking(key)` directly, which would fire shadow
+  // `turnEnd` and clear the turn-active marker mid-turn — the latter
+  // triggering the model-idle restart probe + pendingInbound flush as
+  // if claude had gone idle. Use `clearReactionState` to only do the
+  // reaction-cleanup work.
   const key = statusKey(chatId, threadId)
   const ctrl = activeStatusReactions.get(key)
   if (!ctrl) return
   if (outcome === 'done') ctrl.setDone()
   else ctrl.setError()
-  purgeReactionTracking(key)
+  clearReactionState(key)
 }
 
 function resolveThreadId(chat_id: string, explicit?: string | number | null): number | undefined {
@@ -2786,6 +2828,17 @@ function postLegacyBanner(
 // short-circuit to no-ops at runtime. `progressDriver` is typed `any`
 // so TS doesn't resolve `progressDriver?.X` to `never`.
 const streamMode = process.env.SWITCHROOM_TG_STREAM_MODE ?? 'checklist'
+// PR B: per-agent stream throttle override via channels.telegram.stream_throttle_ms.
+// When unset, draft-stream.ts applies transport-aware defaults (300 ms draft,
+// 1000 ms message). Parsed once at boot; sub-zero / NaN values fall back to
+// undefined so the per-transport default wins. See `src/agents/scaffold.ts`
+// `channelsToEnv()` for the yaml → env wiring.
+const STREAM_THROTTLE_MS_OVERRIDE: number | undefined = (() => {
+  const raw = process.env.SWITCHROOM_TG_STREAM_THROTTLE_MS
+  if (raw == null || raw === '') return undefined
+  const n = Number.parseInt(raw, 10)
+  return Number.isFinite(n) && n >= 0 ? n : undefined
+})()
 const TURN_FLUSH_SAFETY_ENABLED = isTurnFlushSafetyEnabled()
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const progressDriver: any = null
@@ -3082,7 +3135,15 @@ silencePoke.startTimer({
     // Drop silence-poke state and clear turn-active so the next inbound
     // for this chat starts a fresh turn instead of queueing forever.
     silencePoke.endTurn(fbKey)
-    purgeReactionTracking(fbKey)
+    // PR 3b step 5 (#1603 audit): force outboundEmitted=false. The
+    // framework fallback fires precisely because visible delivery
+    // didn't happen in 5 min — `wedgedTurn.replyCalled` may have been
+    // set during the turn (e.g. reply tool invoked but Telegram side
+    // never confirmed delivery), but from the user's perspective no
+    // outbound landed. The state machine's `noteOutbound` effect
+    // must NOT fire for this path. Pass `undefined` for endingTurn
+    // and `false` as the explicit override.
+    purgeReactionTracking(fbKey, undefined, false)
     // Defense-in-depth: the fallback's purgeReactionTracking above
     // clears the canonical statusKey(chatId, threadId) for fbKey
     // only. activeTurnStartedAt can hold sibling entries for the
@@ -3095,10 +3156,14 @@ silencePoke.startTimer({
     // purger. Multi-chat-safe — only touches keys for fbChatId, so
     // #1546's intentional cross-chat safety guard is preserved.
     // See turn-state-purge.ts.
+    //
+    // Same `outboundEmitted=false` rationale as the bare call above —
+    // wrap the purger so every sibling-key purge emits a fallback
+    // shadow turnEnd with the truthful "no visible delivery" signal.
     const fbExtraPurge = purgeStaleTurnsForChat(
       fbChatId,
       activeTurnStartedAt.keys(),
-      purgeReactionTracking,
+      (k) => purgeReactionTracking(k, undefined, false),
     )
     // Null `currentTurn` if it's still pointing at the wedged turn —
     // when claude eventually fires a late `turn_end` for this session
@@ -4471,7 +4536,13 @@ async function executeStreamReply(args: Record<string, unknown>): Promise<unknow
       recordOutbound,
       ...(HISTORY_ENABLED ? { getLatestInboundMessageId } : {}),
       writeError: (line) => process.stderr.write(line),
-      throttleMs: 600,
+      // PR B: drop the legacy 600 ms compromise. When the operator sets
+      // `channels.telegram.stream_throttle_ms` in yaml, the env override
+      // wins; otherwise draft-stream's transport-aware default fires
+      // (300 ms draft / 1000 ms message). `throttleMs: undefined` is a
+      // signal — handlers downgrade to `?? undefined`, which then
+      // passes through to draft-stream where the default applies.
+      ...(STREAM_THROTTLE_MS_OVERRIDE != null ? { throttleMs: STREAM_THROTTLE_MS_OVERRIDE } : {}),
       progressCardActive: streamMode === 'checklist',
     },
   )
@@ -5811,7 +5882,10 @@ function handleSessionEvent(ev: SessionEvent): void {
         const ceKey = statusKey(chatId, threadId)
         const ctrl = activeStatusReactions.get(ceKey)
         if (ctrl) ctrl.setError()
-        purgeReactionTracking(ceKey)
+        // Duplicate-emit removed (#1603 audit, step 1): the canonical
+        // endCurrentTurnAtomic(turn) call at line ~5851 below already
+        // invokes purgeReactionTracking on the same ceKey. The bare
+        // call here was firing a second shadow `turnEnd` per traversal.
         // Surfaced during CC-5 investigation (`docs/status-ask-cause-classes.md`):
         // the context-exhaust bail path teardown was missing
         // `silencePoke.endTurn(key)`. Without it, the silence-poke state for
@@ -5969,7 +6043,10 @@ function handleSessionEvent(ev: SessionEvent): void {
         // Fall through to normal state cleanup (ctrl.setDone, purge, etc.)
         // but skip the regular closeProgressLane so we don't re-finalize.
         if (ctrl) ctrl.setDone()
-        purgeReactionTracking(statusKey(chatId, threadId))
+        // Duplicate-emit removed (#1603 audit, step 1): endCurrentTurnAtomic(turn)
+        // at line ~6049 below invokes purgeReactionTracking on the same key
+        // (statusKey(chatId, threadId)). The bare call here was firing a
+        // second shadow `turnEnd` per silent-marker traversal.
         // Match the normal turn_end path's telemetry so silent-marker turns
         // still appear in turn-duration graphs.
         {
@@ -6110,7 +6187,15 @@ function handleSessionEvent(ev: SessionEvent): void {
                 // mirroring this contract — so reply-only turns transition
                 // to terminal 👍 in their own success path rather than
                 // relying on this dedup heuristic.
-                purgeReactionTracking(statusKey(backstopChatId, backstopThreadId))
+                //
+                // PR 3b step 3 (#1603 audit): thread the captured `turn`
+                // explicitly. `endCurrentTurnAtomic(turn)` ran at line ~6120
+                // before this IIFE started, so `currentTurn === null` by
+                // now — without an explicit endingTurn argument, the shadow
+                // trace would read `outboundEmitted=false` for this dedup
+                // path even though `recentCount > 0` proves the reply tool
+                // did fire (turn.replyCalled === true).
+                purgeReactionTracking(statusKey(backstopChatId, backstopThreadId), turn)
                 return
               }
             } catch {}
@@ -6238,14 +6323,35 @@ function handleSessionEvent(ev: SessionEvent): void {
             process.stderr.write(`telegram gateway: turn-flush send failed: ${(err as Error).message}\n`)
             if (backstopCtrl) backstopCtrl.setError()
           } finally {
-            purgeReactionTracking(statusKey(backstopChatId, backstopThreadId))
+            // PR 3b step 3 (#1603 audit): thread the captured `turn`
+            // explicitly. The turn-flush backstop runs inside this IIFE
+            // after `endCurrentTurnAtomic(turn)` already nulled
+            // `currentTurn` at line ~6120. Without threading, the shadow
+            // trace would read `outboundEmitted=currentTurn?.replyCalled
+            // === undefined` → false. For the turn-flush path
+            // `turn.replyCalled` is `false` regardless (the model didn't
+            // call the reply tool — the gateway backstop did the work),
+            // so the threaded value matches the existing fallback here.
+            // But pinning the source via the captured turn matches the
+            // canonical pattern and survives any future change to how
+            // `currentTurn` is sequenced.
+            purgeReactionTracking(statusKey(backstopChatId, backstopThreadId), turn)
           }
         })()
         return
       }
 
       if (ctrl) ctrl.setDone()
-      purgeReactionTracking(statusKey(chatId, threadId))
+      // Duplicate-emit removed (#1603 audit, step 4 — the audit's
+      // original "route through endCurrentTurnAtomic" recommendation
+      // missed that this same code path already calls
+      // `endCurrentTurnAtomic(turn)` ~90 lines below at line ~6412
+      // on the same key — `chatId === turn.sessionChatId` and
+      // `threadId === turn.sessionThreadId` per the bindings at
+      // ~5946-5947. Removing this bare call closes the last duplicate
+      // shadow-`turnEnd` emit on the dominant happy-path turn-end
+      // tail; the canonical primitive below still fires the single
+      // authoritative turnEnd with the threaded turn).
       {
         const sKey = streamKey(chatId, threadId)
         const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0
@@ -6418,6 +6524,14 @@ function handlePtyActivity(text: string): void {
       historyEnabled: false,
       recordOutbound,
       writeError: (line) => process.stderr.write(line),
+      // PR B note: this is the PTY-activity stream, NOT the LLM
+      // stream_reply path. PTY drives many tiny partials as a TUI
+      // re-renders; 600 ms is a deliberate compromise tuned for the
+      // PTY flicker characteristics, not LLM token cadence. The
+      // transport-aware defaults (300/1000) deliberately do NOT
+      // apply here. If you change this, also check
+      // telegram-plugin/pty-partial-handler.ts:159 which has the
+      // same value for the same reason.
       throttleMs: 600,
     },
   ).catch((err) => {

package/telegram-plugin/stream-reply-handler.ts

@@ -514,7 +514,9 @@ export async function handleStreamReply(
       threadId,
       parseMode,
       disableLinkPreview: deps.disableLinkPreview,
-      throttleMs: deps.throttleMs ?? 600,
+      // PR B: pass undefined when caller didn't override, so draft-stream's
+      // transport-aware default (300 ms draft / 1000 ms message) wins.
+      ...(deps.throttleMs != null ? { throttleMs: deps.throttleMs } : {}),
       retry: deps.retry,
       ...(replyToMessageId != null ? { replyToMessageId } : {}),
       ...(args.quote_text != null && replyToMessageId != null ? { quoteText: args.quote_text } : {}),