switchroom 0.16.15 → 0.16.20

package/telegram-plugin/tests/feed-heartbeat-liveness-open.test.ts

@@ -12,12 +12,22 @@
  *     `evaluatePostAnswerLiveness(...)` consulted each tick, with the cap fed
  *     from `POST_ANSWER_LIVENESS_STALE_MS`.
  *
- * Pre-answer liveness-open branch:
+ * Pre-answer liveness-open path (`openLivenessFeedIfDue`, the shared helper the
+ * heartbeat AND the enqueue-time early-open timer both call — early-card-open
+ * change):
  *   1. The SWITCHROOM_FEED_LIVENESS_OPEN kill-switch (default ON, i.e. `!== '0'`)
- *      gates the liveness-open path — operators can disable it with =0.
- *   2. FEED_LIVENESS_OPEN_MS is parsed from env with a sane default (12 000 ms).
- *   3. The `age < FEED_LIVENESS_OPEN_MS` return-guard fires BEFORE the 0-tool
- *      feed opens — a turn that hasn't yet passed the threshold returns early.
+ *      gates the liveness-open path — operators can disable it with =0. The
+ *      WHEN-gate (`shouldEarlyOpenLiveness`, feed-open-gate.ts) reads it.
+ *   2. FEED_LIVENESS_OPEN_MS is parsed from env with a sane default of ~1.2 s
+ *      (dropped from 12 s to kill the dead-air gap before the card opens).
+ *   3. The age-vs-threshold + already-open return-guards live in the pure
+ *      `shouldEarlyOpenLiveness` decision, consulted at the top of
+ *      `openLivenessFeedIfDue` BEFORE the drain — a turn that hasn't passed the
+ *      threshold, or one whose card is already open, returns early (no
+ *      double-open).
+ *   4. The 0-tool branch of `feedHeartbeatTick` delegates to that one shared
+ *      helper rather than inlining the open — so the heartbeat and the
+ *      enqueue-time timer can never double-open.
  *
  * These are STRUCTURAL (source-read) assertions; the gateway IIFE can't be
  * instantiated in-process. Pattern matches silence-liveness-wiring.test.ts.
@@ -38,21 +48,10 @@ function feedHeartbeatTickSrc(): string {
   return after.split('\nfunction ')[0] ?? after
 }
 
-/**
- * Extract the 0-tool liveness-open branch: the section from
- * `if (turn.mirrorLines.length === 0)` to its closing `return`. This scopes
- * the FEED_LIVENESS_OPEN_ENABLED and age-guard assertions to the correct branch
- * (the post-answer Fix-2 block now precedes it and also has a drain call).
- */
-function liveness0ToolBranchSrc(): string {
-  const body = feedHeartbeatTickSrc()
-  const start = body.indexOf('if (turn.mirrorLines.length === 0)')
-  if (start === -1) return ''
-  // Capture until the closing `return\n  }` of this if-block (the next blank-line-terminated return).
-  const after = body.slice(start)
-  // Take up to the labelled-feed heartbeat comment that follows.
-  const end = after.indexOf('// Labelled-feed heartbeat')
-  return end === -1 ? after : after.slice(0, end)
+/** Return the source text of `openLivenessFeedIfDue` (the shared open helper). */
+function openLivenessFeedIfDueSrc(): string {
+  const after = gatewaySrc.split('function openLivenessFeedIfDue(turn: CurrentTurn): void {')[1] ?? ''
+  return after.split('\nfunction ')[0] ?? after
 }
 
 describe('H-1: feedHeartbeatTick liveness-open threshold', () => {
@@ -63,36 +62,43 @@ describe('H-1: feedHeartbeatTick liveness-open threshold', () => {
     )
   })
 
-  it('FEED_LIVENESS_OPEN_MS defaults to 12_000 ms when env is unset', () => {
+  it('FEED_LIVENESS_OPEN_MS defaults to ~1.2 s (dropped from 12 s to kill the dead-air gap)', () => {
     // The IIFE initialiser `const FEED_LIVENESS_OPEN_MS = (() => { ... })()` must
-    // contain the fallback 12_000. Split on the const definition (not the comment).
+    // contain the new fallback 1_200. Split on the const definition (not the comment).
     const afterConst = gatewaySrc.split('const FEED_LIVENESS_OPEN_MS')[1] ?? ''
     // The IIFE closes with `})()` — take everything before that.
     const initBlock = afterConst.split('})()')[0] ?? ''
-    expect(initBlock).toMatch(/12[_]?000/)
+    expect(initBlock).toMatch(/1[_]?200/)
   })
 
-  it('age < FEED_LIVENESS_OPEN_MS return-guard exists inside the 0-tool liveness branch', () => {
-    const branch = liveness0ToolBranchSrc()
-    expect(branch).toMatch(/if\s*\(age\s*<\s*FEED_LIVENESS_OPEN_MS\)\s*return/)
+  it('the 0-tool liveness branch delegates to the shared openLivenessFeedIfDue helper', () => {
+    // The open logic lives in ONE place so the heartbeat and the enqueue-time
+    // early-open timer cannot double-open. The 0-tool branch must call the
+    // shared helper rather than inline its own open.
+    const body = feedHeartbeatTickSrc()
+    const start = body.indexOf('if (turn.mirrorLines.length === 0)')
+    expect(start).toBeGreaterThan(-1)
+    const branch = body.slice(start)
+    const end = branch.indexOf('// Labelled-feed heartbeat')
+    const scoped = end === -1 ? branch : branch.slice(0, end)
+    expect(scoped).toMatch(/openLivenessFeedIfDue\(turn\)/)
   })
 
-  it('FEED_LIVENESS_OPEN_ENABLED check precedes the drain call in the 0-tool liveness branch', () => {
-    const branch = liveness0ToolBranchSrc()
-    const enabledIdx = branch.indexOf('FEED_LIVENESS_OPEN_ENABLED')
-    // Use the actual call site (assignment to activityInFlight) not the comment mention.
-    const drainCallIdx = branch.indexOf('turn.activityInFlight = drainActivitySummary')
-    expect(enabledIdx).toBeGreaterThan(-1)
-    expect(drainCallIdx).toBeGreaterThan(enabledIdx)
+  it('the WHEN-gate (shouldEarlyOpenLiveness) precedes the drain call inside openLivenessFeedIfDue', () => {
+    const body = openLivenessFeedIfDueSrc()
+    const gateIdx = body.indexOf('shouldEarlyOpenLiveness(')
+    // Use the actual call site (assignment to activityInFlight) not a comment mention.
+    const drainCallIdx = body.indexOf('turn.activityInFlight = drainActivitySummary')
+    expect(gateIdx).toBeGreaterThan(-1)
+    expect(drainCallIdx).toBeGreaterThan(gateIdx)
   })
 
-  it('age < FEED_LIVENESS_OPEN_MS guard precedes the drain call in the 0-tool branch (early-return)', () => {
-    const branch = liveness0ToolBranchSrc()
-    const guardIdx = branch.indexOf('age < FEED_LIVENESS_OPEN_MS')
-    // Use the actual call site (assignment to activityInFlight) not the comment mention.
-    const drainCallIdx = branch.indexOf('turn.activityInFlight = drainActivitySummary')
-    expect(guardIdx).toBeGreaterThan(-1)
-    expect(drainCallIdx).toBeGreaterThan(guardIdx)
+  it('the early-open timer is scheduled at turn enqueue and torn down at turn-end', () => {
+    // The enqueue-time early-open (the dead-air fix): a one-shot timer fires the
+    // shared open helper at turn start, and it is cancelled at the canonical
+    // turn-end so a leaked timer can never fire against a successor turn.
+    expect(gatewaySrc).toMatch(/scheduleEarlyLivenessOpen\(next\)/)
+    expect(gatewaySrc).toMatch(/stopEarlyLivenessOpen\(key as string\)/)
   })
 })
 

package/telegram-plugin/tests/feed-open-gate.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest'
 
-import { mayOpenActivityCard } from '../gateway/feed-open-gate.js'
+import {
+  mayOpenActivityCard,
+  shouldEarlyOpenLiveness,
+} from '../gateway/feed-open-gate.js'
 
 /**
  * Feed-OPEN gate — pure decision (design `docs/message-emission-determinism.md`
@@ -176,6 +179,77 @@ describe('mayOpenActivityCard — lever 1 exception: post-answer sub-agent liven
   })
 })
 
+describe('shouldEarlyOpenLiveness — the early-open WHEN gate (enqueue + heartbeat)', () => {
+  // The minimal "Working…" placeholder is due to open for a 0-label turn once it
+  // has been alive past the threshold and NO card is open yet. Both the
+  // enqueue-time early-open timer and the 6 s heartbeat consult this, so an
+  // already-open card returns false (the drain EDITs instead) — they can never
+  // double-open. This is the fix for the 12 s dead-air gap before the card first
+  // appears on a thinking / pure-narration turn.
+
+  const base = {
+    enabled: true,
+    ageMs: 1_500,
+    thresholdMs: 1_200,
+    mirrorLineCount: 0,
+    activityMessageId: null as number | null,
+    sessionChatId: 'chat-1' as string | null,
+  }
+
+  it('opens at the liveness threshold for a 0-tool turn with no card yet', () => {
+    // The core change: a turn alive past the (now ~1.2 s) threshold with no tool
+    // label and no card opens the placeholder — narration before the first tool
+    // surfaces right away instead of after 12 s.
+    expect(shouldEarlyOpenLiveness({ ...base })).toBe(true)
+  })
+
+  it('is a NO-OP once a card is already open (never double-open / race)', () => {
+    // A tool/narrative drain already opened the card (activityMessageId set).
+    // Both callers see false here, so the second one maintains via EDIT, not a
+    // fresh OPEN.
+    expect(
+      shouldEarlyOpenLiveness({ ...base, activityMessageId: 4242 }),
+    ).toBe(false)
+  })
+
+  it('does not open before the threshold (turn still fresh)', () => {
+    expect(
+      shouldEarlyOpenLiveness({ ...base, ageMs: 300, thresholdMs: 1_200 }),
+    ).toBe(false)
+  })
+
+  it('opens exactly AT the threshold (>= boundary)', () => {
+    expect(
+      shouldEarlyOpenLiveness({ ...base, ageMs: 1_200, thresholdMs: 1_200 }),
+    ).toBe(true)
+  })
+
+  it('never opens when the feature flag is off', () => {
+    expect(shouldEarlyOpenLiveness({ ...base, enabled: false })).toBe(false)
+  })
+
+  it('never opens with no target chat (e.g. an anonymous / null-agent surface)', () => {
+    expect(shouldEarlyOpenLiveness({ ...base, sessionChatId: null })).toBe(false)
+  })
+
+  it('opens to render accumulated narration: mirrorLines staged but no card yet (§3 case)', () => {
+    // The edge the early open serves: narration was staged (mirrorLineCount > 0)
+    // but no card opened yet (activityMessageId == null). The placeholder opens
+    // and renders that accumulated narration rather than a bare "Working…".
+    expect(
+      shouldEarlyOpenLiveness({ ...base, mirrorLineCount: 3, activityMessageId: null }),
+    ).toBe(true)
+  })
+
+  it('does NOT fight the labelled feed once a card is open AND labels exist', () => {
+    // A real tool label drives the labelled-feed heartbeat (card open). The
+    // placeholder must not fight it → no fresh OPEN.
+    expect(
+      shouldEarlyOpenLiveness({ ...base, mirrorLineCount: 2, activityMessageId: 99 }),
+    ).toBe(false)
+  })
+})
+
 describe('mayOpenActivityCard — lever 4 (no OPEN below an EARLIER turn answer; race C/D)', () => {
   // The cross-turn case: a synthetic represent/owed-reply turn starts with a
   // CLEARED per-turn `finalAnswerEverDelivered` latch even though a substantive

package/telegram-plugin/tests/tool-activity-summary.test.ts

@@ -397,6 +397,26 @@ describe("renderActivityFeedWithNested — foreground sub-agent nesting (Model A
         "<i>✓ Working…</i>",
       );
     });
+
+    it("early open renders ACCUMULATED narration, not a bare 'Working…' (§3 case)", () => {
+      // The early-open path (gateway `openLivenessFeedIfDue`) passes the turn's
+      // accumulated `mirrorLines` when non-empty instead of the bare "Working…"
+      // placeholder. This is the §3 case: narration emitted BEFORE the first
+      // tool was staged into mirrorLines, and the early open surfaces it on the
+      // card the instant it opens — so the pre-tool narration is visible
+      // immediately, not lost until a tool label lands.
+      const staged = [
+        "Let me check the migration history first",
+        "Now comparing against the live schema",
+      ];
+      const out = renderActivityFeedWithNested(staged, [], false, " · 1s")!;
+      // The live in-progress line carries the LAST staged narration line, and the
+      // earlier line is retained in the feed body — the accumulated narration
+      // renders, not "Working…".
+      expect(out).toContain("Now comparing against the live schema");
+      expect(out).toContain("Let me check the migration history first");
+      expect(out).not.toContain("Working…");
+    });
   });
 
   it("stepCount=0 → no footer even on final=true", () => {

package/telegram-plugin/tests/turn-typing-loop.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { createTurnTypingLoop } from '../gateway/turn-typing-loop.js'
+
+/**
+ * Turn-level `typing…` indicator lifecycle — the second "something is happening"
+ * signal that runs alongside the early-card-open. Telegram's typing action
+ * auto-expires after ~5 s, so the loop must re-fire on a periodic refresh while
+ * the turn is in flight and stop cleanly at turn-end WITHOUT leaking a refresh
+ * interval. The factory is unit-tested over fake timers + a spy `sendChatAction`
+ * so the lifecycle is proven without the gateway or the bot API.
+ */
+
+function makeDeps(overrides: { refreshMs?: number } = {}) {
+  const sendChatAction =
+    vi.fn<(chatId: string, threadId: number | null) => void>()
+  // Mirror the gateway's chatKey null/0-collapse: undefined/null thread → '_'.
+  const chatKey = (chatId: string, threadId: number | null) =>
+    `${chatId}:${threadId == null ? '_' : threadId}`
+  return { sendChatAction, chatKey, refreshMs: overrides.refreshMs }
+}
+
+describe('createTurnTypingLoop — turn-long typing indicator lifecycle', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('fires a typing action immediately on turn start (no wait for the first refresh)', () => {
+    const deps = makeDeps()
+    const loop = createTurnTypingLoop(deps)
+    loop.start('chat-A')
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(1)
+    expect(deps.sendChatAction).toHaveBeenCalledWith('chat-A', null)
+    expect(loop.activeCount()).toBe(1)
+  })
+
+  it('refreshes the typing action every refreshMs while the turn is in flight', () => {
+    const deps = makeDeps({ refreshMs: 4000 })
+    const loop = createTurnTypingLoop(deps)
+    loop.start('chat-A')
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(1) // immediate
+    vi.advanceTimersByTime(4000)
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(2) // first refresh
+    vi.advanceTimersByTime(8000)
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(4) // two more refreshes
+  })
+
+  it('stops cleanly on turn end and leaks NO refresh interval afterwards', () => {
+    const deps = makeDeps({ refreshMs: 4000 })
+    const loop = createTurnTypingLoop(deps)
+    loop.start('chat-A')
+    vi.advanceTimersByTime(4000)
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(2)
+    loop.stop('chat-A')
+    expect(loop.activeCount()).toBe(0)
+    // No further fires after the stop — the interval was cleared, not leaked.
+    vi.advanceTimersByTime(60_000)
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(2)
+  })
+
+  it('stop is idempotent (a no-op when no loop is registered)', () => {
+    const deps = makeDeps()
+    const loop = createTurnTypingLoop(deps)
+    // Stop before any start — must not throw and must remain at zero loops.
+    expect(() => loop.stop('chat-A')).not.toThrow()
+    expect(loop.activeCount()).toBe(0)
+  })
+
+  it('restart on the same key never leaks a second interval (self-heal)', () => {
+    const deps = makeDeps({ refreshMs: 4000 })
+    const loop = createTurnTypingLoop(deps)
+    loop.start('chat-A') // turn 1
+    loop.start('chat-A') // turn 2 on the same key (abnormal abort skipped stop)
+    // Exactly one live loop, not two.
+    expect(loop.activeCount()).toBe(1)
+    // After one refresh window, only ONE refresh fired (plus the 2 immediates).
+    vi.advanceTimersByTime(4000)
+    // 2 immediates (one per start) + 1 refresh from the single live interval.
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(3)
+  })
+
+  it('isolates per-(chat,thread): stopping topic A leaves topic B running', () => {
+    const deps = makeDeps({ refreshMs: 4000 })
+    const loop = createTurnTypingLoop(deps)
+    loop.start('chat-A', 17) // topic A
+    loop.start('chat-A', 23) // topic B — same chat, different thread, own lane
+    expect(loop.activeCount()).toBe(2)
+    expect(deps.sendChatAction).toHaveBeenNthCalledWith(1, 'chat-A', 17)
+    expect(deps.sendChatAction).toHaveBeenNthCalledWith(2, 'chat-A', 23)
+
+    loop.stop('chat-A', 17) // end topic A's turn only
+    expect(loop.activeCount()).toBe(1) // topic B still live
+
+    deps.sendChatAction.mockClear()
+    vi.advanceTimersByTime(4000)
+    // Only topic B refreshes; topic A is fully stopped.
+    expect(deps.sendChatAction).toHaveBeenCalledTimes(1)
+    expect(deps.sendChatAction).toHaveBeenCalledWith('chat-A', 23)
+  })
+
+  it('stopAll clears every live loop (shutdown-drain cleanup) and leaks none', () => {
+    const deps = makeDeps({ refreshMs: 4000 })
+    const loop = createTurnTypingLoop(deps)
+    loop.start('chat-A', 17)
+    loop.start('chat-B')
+    expect(loop.activeCount()).toBe(2)
+    loop.stopAll()
+    expect(loop.activeCount()).toBe(0)
+    deps.sendChatAction.mockClear()
+    vi.advanceTimersByTime(60_000)
+    expect(deps.sendChatAction).not.toHaveBeenCalled()
+  })
+
+  it('collapses undefined and null threadId to the same lane', () => {
+    const deps = makeDeps()
+    const loop = createTurnTypingLoop(deps)
+    loop.start('chat-A') // undefined thread
+    loop.start('chat-A', null) // null thread — same lane (restart, not a 2nd loop)
+    expect(loop.activeCount()).toBe(1)
+  })
+})