switchroom 0.5.0

package/telegram-plugin/tests/real-gateway-f1-ladder-integrity.test.ts

@@ -0,0 +1,123 @@
+/**
+ * F1 — "ladder collapse" — regression test against real-gateway harness.
+ *
+ * Symptom from #545: on a Class B turn (1–3 tool calls, < ~15s), the
+ * status reaction jumps straight from 👀 to 👍, skipping the
+ * intermediate 🤔 (thinking) and 🔥 (tool work) states. User loses the
+ * "agent is doing things" signal.
+ *
+ * Root cause: `StatusReactionController.scheduleState()` debounces
+ * non-immediate transitions (default `debounceMs=700`). When a turn
+ * completes faster than the debounce window, intermediate states never
+ * cross the timer — `setDone()` calls `finishWithState()` which
+ * `clearDebounceTimer()`s and emits 👍 directly, dropping the pending
+ * 🤔/🔥.
+ *
+ * Spec contract from `waiting-ux-spec.md`:
+ *
+ *   F1: ladder integrity — for Class B turns, recorded reaction
+ *       sequence MUST contain 👀 followed by at least one
+ *       intermediate state (🤔 / 🔥 / a tool-specific reaction)
+ *       BEFORE 👍. No straight-to-👍 collapse.
+ *
+ * The fix flushes any pending non-terminal reaction before the
+ * terminal 👍 emits. Tracking: #545 (parent), #553 (Phase 3).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createRealGatewayHarness } from './real-gateway-harness.js'
+
+const CHAT = '8248703757'
+const INBOUND_MSG = 100
+
+beforeEach(() => { vi.useFakeTimers() })
+afterEach(() => { vi.useRealTimers() })
+
+/**
+ * Dedupe consecutive duplicate reactions in the recorded sequence.
+ * The post-F2 harness fires 👀 twice (early-ack + controller setQueued);
+ * Telegram dedupes by emoji so consecutive duplicates are visually one
+ * step. Tests asserting ladder integrity should ignore them.
+ */
+function uniqueLadder(seq: string[]): string[] {
+  const out: string[] = []
+  for (const e of seq) {
+    if (out[out.length - 1] !== e) out.push(e)
+  }
+  return out
+}
+
+describe('F1 — ladder integrity (no straight-to-👍 collapse)', () => {
+  it('Class B sub-debounce turn (~500ms): pending tool reaction MUST emit before 👍', async () => {
+    // The exact failure case from the live demo: a turn that completes
+    // faster than the controller's 700ms debounce window. Pre-fix, the
+    // 🔥 reaction was scheduled but cancelled when setDone() cleared
+    // the debounce timer. User saw 👀 → 👍 with no intermediate state.
+    const h = createRealGatewayHarness({ gapMs: 0 })
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'quick task' })
+    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'quick task' })
+    await h.clock.advance(50)
+    h.feedSessionEvent({ kind: 'thinking' })
+    await h.clock.advance(50)
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Bash' })
+    await h.clock.advance(400) // tool runs ~400ms, total turn ~500ms — under 700ms debounce
+    h.feedSessionEvent({ kind: 'turn_end', durationMs: 500 })
+    await h.clock.advance(1500) // settle, well past debounce window
+
+    const ladder = uniqueLadder(h.recorder.reactionSequence())
+    expect(ladder[0]).toBe('👀')
+    expect(ladder[ladder.length - 1]).toBe('👍')
+    // Must contain at least one intermediate — no straight 👀 → 👍 collapse.
+    expect(ladder.length).toBeGreaterThanOrEqual(3)
+    h.finalize()
+  })
+
+  it('Class B medium turn (~2s, single tool): ladder shows 👀 → tool reaction → 👍', async () => {
+    // Slower turn (single 2s tool) — works correctly even pre-fix because
+    // 2000ms > 700ms debounce. Pin so the fix doesn't regress the working case.
+    const h = createRealGatewayHarness({ gapMs: 0 })
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'medium task' })
+    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'medium task' })
+    await h.clock.advance(50)
+    h.feedSessionEvent({ kind: 'thinking' })
+    await h.clock.advance(200)
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Bash' })
+    await h.clock.advance(2000)
+    h.feedSessionEvent({ kind: 'turn_end', durationMs: 2300 })
+    await h.clock.advance(1000)
+
+    const ladder = uniqueLadder(h.recorder.reactionSequence())
+    expect(ladder[0]).toBe('👀')
+    expect(ladder[ladder.length - 1]).toBe('👍')
+    expect(ladder.length).toBeGreaterThanOrEqual(3)
+    h.finalize()
+  })
+
+  it('Class B 3-tool series at sub-debounce intervals: each transition shows', async () => {
+    // Three rapid tool transitions inside a single debounce window.
+    // Pre-fix, only the LAST one would survive (the others got
+    // overwritten by the next setTool). We don't strictly require all
+    // three to appear (the controller can collapse same-emoji adjacent
+    // calls) — but the FINAL pending state before 👍 must emit.
+    const h = createRealGatewayHarness({ gapMs: 0 })
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'rapid tools' })
+    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'rapid tools' })
+    await h.clock.advance(50)
+    h.feedSessionEvent({ kind: 'thinking' })
+    await h.clock.advance(50)
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Read' })
+    await h.clock.advance(100)
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Bash' })
+    await h.clock.advance(100)
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Edit' })
+    await h.clock.advance(200)
+    h.feedSessionEvent({ kind: 'turn_end', durationMs: 500 })
+    await h.clock.advance(1500)
+
+    const ladder = uniqueLadder(h.recorder.reactionSequence())
+    expect(ladder[0]).toBe('👀')
+    expect(ladder[ladder.length - 1]).toBe('👍')
+    expect(ladder.length).toBeGreaterThanOrEqual(3)
+    h.finalize()
+  })
+})

package/telegram-plugin/tests/real-gateway-f2-instant-draft.test.ts

@@ -0,0 +1,82 @@
+/**
+ * F2 — "no instant draft / typing signal" — regression test.
+ *
+ * Spec contract from `waiting-ux-spec.md`:
+ *
+ *   F2 deadline: firstReactionAt - inboundAt < 800ms for ALL turn classes.
+ *
+ * Pre-fix history: Phase 1's harness (#547) called `setQueued()` synchronously
+ * inside its `inbound()` helper, so F2 passed trivially — the harness was
+ * lying about the inbound flow. The Phase 3 real-gateway harness (#553 PR 1)
+ * wired the production `InboundCoalescer` BEFORE first-paint, exposing that
+ * 👀 only fired AFTER the coalesce window (default 1500ms) — ~700ms over deadline.
+ *
+ * Fix (#553 PR 2): `gateway.ts handleInboundCoalesced` now fires the 👀
+ * reaction directly on raw arrival via `bot.api.setMessageReaction`,
+ * BEFORE the coalesce buffer. Eligibility: paired DM users on a fresh
+ * turn (mid-turn messages preserve the current 🔥/🤔 state). The
+ * controller's later `setQueued()` runs as before; Telegram dedupes
+ * the duplicate 👀 emit.
+ *
+ * These tests pin the post-fix contract so the gap can never re-open.
+ *
+ * Tracking: #545 (parent), #553 (Phase 3 harness + fixes).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createRealGatewayHarness } from './real-gateway-harness.js'
+
+const CHAT = '8248703757'
+const INBOUND_MSG = 100
+
+beforeEach(() => { vi.useFakeTimers() })
+afterEach(() => { vi.useRealTimers() })
+
+describe('F2 — first-paint deadline (👀 within 800ms of inbound)', () => {
+  it('Class A — instant reply: 👀 reaction within 800ms', async () => {
+    const h = createRealGatewayHarness({ gapMs: 1500 }) // production default
+    const inboundAt = h.clock.now()
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'hi' })
+    // Allow up to 800ms for the deadline; do NOT advance through the
+    // full coalesce window — the deadline says 👀 lands BEFORE the
+    // coalesce flush would.
+    await h.clock.advance(800)
+    const firstReactionMs = h.recorder.firstReactionMs(CHAT)
+    expect(firstReactionMs).not.toBeNull()
+    expect((firstReactionMs ?? Infinity) - inboundAt).toBeLessThan(800)
+    h.finalize()
+  })
+
+  it('Class B — short turn: 👀 reaction within 800ms even with later tool calls', async () => {
+    const h = createRealGatewayHarness({ gapMs: 1500 })
+    const inboundAt = h.clock.now()
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'do a thing' })
+    await h.clock.advance(800)
+    const firstReactionMs = h.recorder.firstReactionMs(CHAT)
+    expect(firstReactionMs).not.toBeNull()
+    expect((firstReactionMs ?? Infinity) - inboundAt).toBeLessThan(800)
+    h.finalize()
+  })
+
+  it('Class C — long / multi-agent: 👀 reaction within 800ms regardless of total turn duration', async () => {
+    const h = createRealGatewayHarness({ gapMs: 1500 })
+    const inboundAt = h.clock.now()
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'big task' })
+    await h.clock.advance(800)
+    const firstReactionMs = h.recorder.firstReactionMs(CHAT)
+    expect(firstReactionMs).not.toBeNull()
+    expect((firstReactionMs ?? Infinity) - inboundAt).toBeLessThan(800)
+    h.finalize()
+  })
+
+  it('still meets deadline when an operator tunes coalescingGapMs lower', async () => {
+    const h = createRealGatewayHarness({ gapMs: 500 })
+    const inboundAt = h.clock.now()
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'hi' })
+    await h.clock.advance(800)
+    const firstReactionMs = h.recorder.firstReactionMs(CHAT)
+    expect(firstReactionMs).not.toBeNull()
+    expect((firstReactionMs ?? Infinity) - inboundAt).toBeLessThan(800)
+    h.finalize()
+  })
+})

package/telegram-plugin/tests/real-gateway-f3-late-card.test.ts

@@ -0,0 +1,114 @@
+/**
+ * F3 — "late progress card" — REFRAMED under v2 (#553 PR 4).
+ *
+ * Original symptom from #545: on long-running turns (Class C), the
+ * progress card rendered late — sometimes after `turn_end`, sometimes
+ * never. Under v1, the user sat watching status reactions cycle for
+ * 10+ seconds with no card visible, then either got a sudden card right
+ * before the reply or just the reply with no card at all.
+ *
+ * **Under v2 (#553 PR 4), F3's symptom is by design — tool-only turns
+ * never show the card.** The card now requires sub-agents OR
+ * `elapsed >= 60s`. F3-style late-card is no longer a bug; it's the
+ * spec. The driver defaults shifted from
+ * `initialDelayMs=30_000, promoteAfterMs=5_000, promoteOnParentToolCount=3`
+ * to `initialDelayMs=60_000, promoteAfterMs=0, promoteOnParentToolCount=0`.
+ *
+ * What this file now covers:
+ *   - Long single-tool turn (~10s): card MUST NOT render (tools alone
+ *     don't promote).
+ *   - Two-tool turn (~6s): card MUST NOT render.
+ *   - Class A instant reply (<2s, no tools): card MUST NOT render
+ *     (regression guard, unchanged).
+ *
+ * The "card renders after >=60s" path is covered by the v2 spec test
+ * (`real-gateway-spec.test.ts` → "Class C — progress card appears when
+ * elapsed >= 60s even without a sub-agent"). The "card renders on
+ * sub-agent" path is covered there too.
+ *
+ * Tracking: #545 (parent), #553 (Phase 3, PR 4 reframe).
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createRealGatewayHarness } from './real-gateway-harness.js'
+
+const CHAT = '8248703757'
+const INBOUND_MSG = 100
+
+beforeEach(() => { vi.useFakeTimers() })
+afterEach(() => { vi.useRealTimers() })
+
+describe('F3 — under v2: tool-only turns intentionally show no card', () => {
+  it('long single-tool turn (~10s): NO card rendered (intentional, v2 spec)', async () => {
+    // v2 defaults: initialDelayMs=60_000, promoteAfterMs=0 (disabled),
+    // promoteOnParentToolCount=0 (disabled). A 10s single-tool turn
+    // crosses neither the 60s threshold nor any tool/sub-agent promote
+    // gate — the card is suppressed by design.
+    const h = createRealGatewayHarness({ gapMs: 0 })
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'long task' })
+    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'long task' })
+    await h.clock.advance(200)
+    h.feedSessionEvent({ kind: 'thinking' })
+    await h.clock.advance(500)
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Bash', toolUseId: 't1' })
+    // Tool runs ~10s — well under the 60s spec threshold.
+    await h.clock.advance(10_000)
+    h.feedSessionEvent({ kind: 'tool_result', toolUseId: 't1', toolName: 'Bash' })
+    await h.clock.advance(200)
+
+    // Spec: tools alone never trigger the card.
+    expect(h.recorder.progressCardSendMs(CHAT)).toBeNull()
+
+    // Drain the rest of the turn so afterEach doesn't leak timers.
+    await h.streamReply({ chat_id: CHAT, text: 'done', done: true })
+    h.feedSessionEvent({ kind: 'turn_end', durationMs: 11_000 })
+    await h.clock.advance(2_000)
+    h.finalize()
+  })
+
+  it('two-tool turn (~6s): NO card rendered (intentional, v2 spec)', async () => {
+    // 2 tools, ~6s — same v2 contract: tools alone don't promote, and
+    // 6s is well under the 60s threshold. Card stays suppressed.
+    const h = createRealGatewayHarness({ gapMs: 0 })
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'two tools' })
+    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'two tools' })
+    await h.clock.advance(200)
+    h.feedSessionEvent({ kind: 'thinking' })
+    await h.clock.advance(500)
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Read', toolUseId: 't1' })
+    await h.clock.advance(2_000)
+    h.feedSessionEvent({ kind: 'tool_result', toolUseId: 't1', toolName: 'Read' })
+    h.feedSessionEvent({ kind: 'tool_use', toolName: 'Bash', toolUseId: 't2' })
+    await h.clock.advance(3_000)
+    h.feedSessionEvent({ kind: 'tool_result', toolUseId: 't2', toolName: 'Bash' })
+    await h.clock.advance(500)
+
+    expect(h.recorder.progressCardSendMs(CHAT)).toBeNull()
+
+    // Drain
+    await h.streamReply({ chat_id: CHAT, text: 'done', done: true })
+    h.feedSessionEvent({ kind: 'turn_end', durationMs: 7_000 })
+    await h.clock.advance(2_000)
+    h.finalize()
+  })
+
+  it('instant reply (Class A, <2s, no tools): card is STILL suppressed (regression guard)', async () => {
+    // Unchanged from the original F3 file — the v2 contract preserves
+    // fast-turn suppression for instant replies. This is the only
+    // "card should not appear" assertion that has the same meaning
+    // pre- and post-v2.
+    const h = createRealGatewayHarness({ gapMs: 0 })
+    h.inbound({ chatId: CHAT, messageId: INBOUND_MSG, text: 'hi' })
+    h.feedSessionEvent({ kind: 'enqueue', chatId: CHAT, messageId: '1', threadId: null, rawContent: 'hi' })
+    await h.clock.advance(200)
+    h.feedSessionEvent({ kind: 'thinking' })
+    await h.clock.advance(500)
+    await h.streamReply({ chat_id: CHAT, text: 'hello back', done: true })
+    h.feedSessionEvent({ kind: 'turn_end', durationMs: 1_500 })
+    await h.clock.advance(2_000)
+
+    // Class A: no card.
+    expect(h.recorder.progressCardSendMs(CHAT)).toBeNull()
+    h.finalize()
+  })
+})