switchroom 0.5.0

package/telegram-plugin/tests/pty-partial-handler.test.ts

@@ -0,0 +1,326 @@
+/**
+ * Integration tests for the PTY partial handler state machine.
+ *
+ * These run against the real `createStreamController` (backed by the mock
+ * bot harness) so they exercise the full send/edit wiring — not just the
+ * decision logic.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  createPtyPartialHandler,
+  handlePtyPartialPure,
+  type PtyHandlerState,
+  type PtyHandlerDeps,
+} from '../pty-partial-handler.js'
+import type { DraftStreamHandle } from '../draft-stream.js'
+import { createMockBot, installBotResetHook, microtaskFlush } from './bot-api.harness.js'
+
+function makeState(overrides?: Partial<PtyHandlerState>): PtyHandlerState {
+  return {
+    currentSessionChatId: null,
+    currentSessionThreadId: undefined,
+    pendingPtyPartial: null,
+    activeDraftStreams: new Map<string, DraftStreamHandle>(),
+    suppressPtyPreview: new Set<string>(),
+    lastPtyPreviewByChat: new Map<string, string>(),
+    ...overrides,
+  }
+}
+
+function makeDeps(
+  bot: ReturnType<typeof createMockBot>,
+  overrides?: Partial<PtyHandlerDeps>,
+): PtyHandlerDeps {
+  return {
+    bot,
+    renderText: (t) => t, // identity for tests — easier to assert
+    ...overrides,
+  }
+}
+
+describe('handlePtyPartialPure', () => {
+  const bot = createMockBot()
+  installBotResetHook(bot)
+
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('buffers the first partial when chatId is not yet known', () => {
+    const state = makeState()
+    const action = handlePtyPartialPure('drafting', state, makeDeps(bot))
+    expect(action).toBe('buffered')
+    expect(state.pendingPtyPartial).toEqual({ text: 'drafting' })
+    expect(state.activeDraftStreams.size).toBe(0)
+    expect(bot.api.sendMessage).not.toHaveBeenCalled()
+  })
+
+  it('suppressed chat drops partial (no state mutation, no send)', () => {
+    const state = makeState({
+      currentSessionChatId: '1',
+      suppressPtyPreview: new Set(['1:_']),
+    })
+    const action = handlePtyPartialPure('should be dropped', state, makeDeps(bot))
+    expect(action).toBe('suppressed')
+    expect(state.activeDraftStreams.size).toBe(0)
+    expect(state.lastPtyPreviewByChat.size).toBe(0)
+    expect(bot.api.sendMessage).not.toHaveBeenCalled()
+  })
+
+  it('dedups when same text arrives twice in a row', async () => {
+    const state = makeState({ currentSessionChatId: '1' })
+    const deps = makeDeps(bot)
+
+    expect(handlePtyPartialPure('same', state, deps)).toBe('update-new')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+
+    expect(handlePtyPartialPure('same', state, deps)).toBe('dedup-skip')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1) // no second call
+    expect(bot.api.editMessageText).not.toHaveBeenCalled()
+  })
+
+  it('first partial for a chat triggers onFirstPartial exactly once', async () => {
+    const state = makeState({ currentSessionChatId: '1' })
+    const onFirstPartial = vi.fn<(chatId: string, chars: number) => void>()
+    const deps = makeDeps(bot, { onFirstPartial })
+
+    handlePtyPartialPure('hello', state, deps)
+    handlePtyPartialPure('hello world', state, deps)
+    await microtaskFlush()
+
+    expect(onFirstPartial).toHaveBeenCalledTimes(1)
+    expect(onFirstPartial).toHaveBeenCalledWith('1', 5)
+  })
+
+  it('applies renderText before pushing into the stream', async () => {
+    const state = makeState({ currentSessionChatId: '1' })
+    const deps = makeDeps(bot, {
+      renderText: (t) => `<b>${t}</b>`,
+    })
+
+    handlePtyPartialPure('bold', state, deps)
+    await microtaskFlush()
+
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendMessage.mock.calls[0][1]).toBe('<b>bold</b>')
+  })
+
+  it('reuses an existing stream on second update', async () => {
+    const state = makeState({ currentSessionChatId: '1' })
+    const deps = makeDeps(bot)
+
+    expect(handlePtyPartialPure('one', state, deps)).toBe('update-new')
+    await microtaskFlush()
+
+    vi.advanceTimersByTime(1000)
+    expect(handlePtyPartialPure('two', state, deps)).toBe('update-existing')
+    await microtaskFlush()
+
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
+    expect(bot.api.editMessageText.mock.calls[0][2]).toBe('two')
+  })
+
+  it('keyed by chat+thread — independent streams per forum topic', async () => {
+    const state = makeState({ currentSessionChatId: '1', currentSessionThreadId: 10 })
+    const deps = makeDeps(bot)
+    handlePtyPartialPure('topic A', state, deps)
+    state.currentSessionThreadId = 20
+    handlePtyPartialPure('topic B', state, deps)
+    await microtaskFlush()
+
+    expect(state.activeDraftStreams.size).toBe(2)
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(2)
+  })
+
+  it('onStreamSend fires with chatId + messageId after initial send lands', async () => {
+    const state = makeState({ currentSessionChatId: '1' })
+    const onStreamSend = vi.fn<(chatId: string, messageId: number, chars: number) => void>()
+    const deps = makeDeps(bot, { onStreamSend })
+
+    handlePtyPartialPure('hi', state, deps)
+    await microtaskFlush()
+
+    expect(onStreamSend).toHaveBeenCalledWith('1', 500, 2)
+  })
+})
+
+describe('createPtyPartialHandler — session + buffer replay', () => {
+  const bot = createMockBot()
+  installBotResetHook(bot)
+
+  beforeEach(() => vi.useFakeTimers())
+  afterEach(() => vi.useRealTimers())
+
+  it('buffers partial arriving before enqueue, replays on onSessionEnqueue', async () => {
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    expect(handler.onPartial('early partial')).toBe('buffered')
+    expect(bot.api.sendMessage).not.toHaveBeenCalled()
+    expect(state.pendingPtyPartial).toEqual({ text: 'early partial' })
+
+    const replayed = handler.onSessionEnqueue('42')
+    await microtaskFlush()
+
+    expect(replayed).toBe('update-new')
+    expect(state.pendingPtyPartial).toBeNull()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendMessage.mock.calls[0][0]).toBe('42')
+    expect(bot.api.sendMessage.mock.calls[0][1]).toBe('early partial')
+  })
+
+  it('onSessionEnqueue with no buffered partial is a no-op send-wise', () => {
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    const result = handler.onSessionEnqueue('42', 7)
+    expect(result).toBeNull()
+    expect(state.currentSessionChatId).toBe('42')
+    expect(state.currentSessionThreadId).toBe(7)
+    expect(bot.api.sendMessage).not.toHaveBeenCalled()
+  })
+
+  it('onTurnEnd clears session + dedup cache for the active chat only', async () => {
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    handler.onSessionEnqueue('A')
+    handler.onPartial('text A')
+    // switch chat
+    state.currentSessionChatId = 'B'
+    handler.onPartial('text B')
+    await microtaskFlush()
+
+    // Pretend we're still "on" chat B for turn_end
+    state.currentSessionChatId = 'B'
+    handler.onTurnEnd()
+
+    expect(state.currentSessionChatId).toBeNull()
+    expect(state.lastPtyPreviewByChat.has('B:_')).toBe(false)
+    // Chat A's cache entry should still exist (wasn't the active chat)
+    expect(state.lastPtyPreviewByChat.has('A:_')).toBe(true)
+  })
+
+  it('full happy-path: buffer → enqueue replay → live partials → final send', async () => {
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    // Extractor fires before session-tail reads enqueue
+    handler.onPartial('hel')
+    handler.onPartial('hello') // second one overwrites the buffer
+    expect(state.pendingPtyPartial).toEqual({ text: 'hello' })
+
+    // Session-tail finally resolves chat id; buffered partial replays
+    handler.onSessionEnqueue('user-123')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+    expect(bot.api.sendMessage.mock.calls[0][1]).toBe('hello')
+
+    // Live partials land as edits after throttle
+    vi.advanceTimersByTime(1000)
+    handler.onPartial('hello world')
+    await microtaskFlush()
+    expect(bot.api.editMessageText).toHaveBeenCalledTimes(1)
+    expect(bot.api.editMessageText.mock.calls[0][2]).toBe('hello world')
+  })
+
+  it('claim survives turn_end — late PTY partial after reply does NOT send a duplicate', async () => {
+    // Regression: user saw a formatted canonical reply, then ~30s later
+    // the same content re-landed as a fresh unformatted message. Root
+    // cause was `suppressPtyPreview.delete` at turn_end opening a window
+    // during which a delayed PTY partial would call draft_send afresh
+    // with raw TUI text. The claim must persist across turn_end.
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    handler.onSessionEnqueue('1')
+    handler.onPartial('draft')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+
+    // Reply tool claims and finalizes (same shape as server.ts reply handler)
+    state.suppressPtyPreview.add('1:_')
+    const open = state.activeDraftStreams.get('1:_')!
+    await open.finalize()
+    state.activeDraftStreams.delete('1:_')
+
+    // Turn ends
+    state.currentSessionChatId = '1'
+    handler.onTurnEnd()
+
+    // A delayed PTY partial arrives AFTER turn_end — this used to create
+    // a second message; with the fix the claim still holds.
+    state.currentSessionChatId = '1'
+    vi.advanceTimersByTime(30_000)
+    expect(handler.onPartial('stale TUI text')).toBe('suppressed')
+    await microtaskFlush()
+
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1) // no duplicate
+  })
+
+  it('onInboundNewCycle releases the claim so the next turn streams live preview', async () => {
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    // Prior turn ran, landed a reply, turn ended — claim still held.
+    state.suppressPtyPreview.add('1:_')
+    state.currentSessionChatId = '1'
+    handler.onTurnEnd()
+    expect(state.suppressPtyPreview.has('1:_')).toBe(true)
+
+    // New inbound user message fires the new-cycle boundary.
+    handler.onInboundNewCycle('1')
+    expect(state.suppressPtyPreview.has('1:_')).toBe(false)
+
+    // PTY partial for the fresh turn creates a stream normally.
+    handler.onSessionEnqueue('1')
+    expect(handler.onPartial('new turn draft')).toBe('update-new')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalled()
+  })
+
+  it('orphaned-reply path is untouched — no claim was set, PTY still streams', async () => {
+    // Safety check: if the agent turn ends WITHOUT ever calling reply
+    // (orphaned-reply / backstop path), suppressPtyPreview was never
+    // added for this chat, so PTY partials keep working across the
+    // turn_end boundary as before.
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    handler.onSessionEnqueue('9')
+    // No reply tool call, no claim added.
+    state.currentSessionChatId = '9'
+    handler.onTurnEnd()
+
+    state.currentSessionChatId = '9'
+    expect(handler.onPartial('still streaming')).toBe('update-new')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+  })
+
+  it('claim from reply handler (suppressPtyPreview) is honored mid-stream', async () => {
+    const state = makeState()
+    const handler = createPtyPartialHandler(state, makeDeps(bot))
+
+    handler.onSessionEnqueue('1')
+    handler.onPartial('first')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+
+    // Reply tool claims — adds to suppress set, finalizes, deletes stream
+    state.suppressPtyPreview.add('1:_')
+    const open = state.activeDraftStreams.get('1:_')!
+    await open.finalize()
+    state.activeDraftStreams.delete('1:_')
+
+    // Next PTY partial: dropped
+    vi.advanceTimersByTime(1000)
+    expect(handler.onPartial('racy')).toBe('suppressed')
+    await microtaskFlush()
+
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1) // no duplicate
+    expect(state.activeDraftStreams.size).toBe(0)
+  })
+})

package/telegram-plugin/tests/pty-tail-real-fixture.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Integration test: V1Extractor against REAL captured Claude Code TUI output.
+ *
+ * The existing pty-tail.test.ts cases use synthesized input that
+ * matches "what we think the TUI looks like." This file uses the
+ * actual bytes captured from a live agent's service.log to test
+ * what V1Extractor extracts from current production output.
+ *
+ * Why this exists (the testing gap that PR #486 missed):
+ *
+ * V1Extractor scans Claude Code's TUI for `● switchroom-telegram - reply`
+ * markers to extract the in-flight `text:` argument. The synthesized
+ * tests assume a verbose marker shape. Real Claude Code recently
+ * collapsed tool-call rendering by default — the TUI now shows just
+ * `Calling switchroom-telegram` until the user presses ctrl+o to expand.
+ *
+ * That format change silently dropped V1Extractor to "always returns
+ * null" — and the unit tests couldn't catch it because they tested
+ * the synthesized old format, not the live one.
+ *
+ * Lesson: any extractor that parses external-system output needs at
+ * least one test that uses captured-from-production bytes, not just
+ * the test author's mental model of what the format looks like.
+ *
+ * Maintenance: when Claude Code TUI changes shape, recapture the
+ * fixture from a fresh `~/.switchroom/agents/<agent>/service.log`:
+ *
+ *   tail -c 30000 ~/.switchroom/agents/<agent>/service.log > \
+ *     telegram-plugin/tests/fixtures/service-log-current-claude-code.bin
+ *
+ * Then verify this test still passes (or update V1Extractor to
+ * handle the new format).
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Terminal } from '@xterm/headless'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { V1Extractor } from '../pty-tail.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const FIXTURE_PATH = resolve(__dirname, 'fixtures', 'service-log-current-claude-code.bin')
+const FIXTURE_BYTES = readFileSync(FIXTURE_PATH, 'utf8')
+
+async function feedToTerm(input: string): Promise<Terminal> {
+  const term = new Terminal({
+    cols: 132,
+    rows: 40,
+    scrollback: 5000,
+    allowProposedApi: true,
+  })
+  await new Promise<void>((resolve) => {
+    term.write(input, () => resolve())
+  })
+  return term
+}
+
+describe('V1Extractor — real production TUI output (regression catch for PR #486)', () => {
+  it('the fixture contains current Claude Code TUI output (smoke check)', () => {
+    // If this fails, the fixture file is empty or corrupted.
+    expect(FIXTURE_BYTES.length).toBeGreaterThan(1000)
+    // The TUI always emits the bot/agent name at minimum.
+    expect(FIXTURE_BYTES).toContain('switchroom-telegram')
+  })
+
+  /**
+   * The next two assertions document the CURRENT BROKEN STATE.
+   * They pin "V1Extractor returns null on real production output" so:
+   *
+   *   1. The bug is loudly visible — the test name says "returns null
+   *      (regression)", not "extracts text correctly"
+   *   2. If V1Extractor is ever fixed (via a new extractor that
+   *      handles the compact format, or upstream restores verbose
+   *      rendering), these assertions will FAIL → forces a deliberate
+   *      review + update of the test
+   *   3. The fixture is canonical evidence of the bug; comparing
+   *      against future captures shows what changed
+   *
+   * When this is fixed, replace the negative assertions with the
+   * positive ones (`toBeNull` → `not.toBeNull`, etc.) and update the
+   * test names. Don't just delete — the fixture-based pattern is the
+   * point.
+   */
+  it('current Claude Code TUI does NOT contain the verbose marker (regression)', () => {
+    // Format observed today (compact / collapsed):
+    //   `Calling switchroom-telegram`
+    // Format V1Extractor expects (verbose / pre-collapse):
+    //   `● switchroom-telegram - reply (MCP)(text: "...")`
+    // The bug: Claude Code now collapses tool-call rendering by
+    // default. The marker `switchroom-telegram - reply` (with the
+    // dash + tool name) is hidden until the user presses ctrl+o to
+    // expand. V1Extractor never sees it, so it always returns null.
+    expect(FIXTURE_BYTES).not.toContain('switchroom-telegram - reply')
+  })
+
+  it('V1Extractor.extract returns null on real fixture (regression — PR #486 PTY-tail wiring is dead code)', async () => {
+    // The acceptance test that should have existed in PR #486:
+    // given real production output, what does V1Extractor return?
+    // Today: null. PTY-tail produces zero pty_partial events.
+    // Bridge → gateway IPC wired correctly; just nothing on the wire.
+    //
+    // Replacement strategy is "heartbeat placeholder driven by JSONL
+    // events" — doesn't depend on TUI parsing, never breaks on
+    // Claude Code updates. See streaming roadmap for next steps.
+    //
+    // When V1Extractor is restored, flip this to .not.toBeNull and
+    // pick a more useful assertion (e.g. extracted text contains
+    // expected substring).
+    const term = await feedToTerm(FIXTURE_BYTES)
+    const result = new V1Extractor().extract(term)
+    expect(result).toBeNull()
+  })
+})

package/telegram-plugin/tests/pty-tail-tmux-fragment.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Pty-tail extractor against a tmux pipe-pane fragment (#725).
+ *
+ * Under the tmux supervisor, `service.log` is fed by
+ * `tmux pipe-pane -o ... 'cat >> service.log'` instead of `script -qfc`
+ * directly. The bytes are the same xterm escape stream Claude writes
+ * to its PTY (tmux just splits the stream), but it's worth pinning a
+ * fixture so a future tmux-config regression (different terminal type,
+ * stripped escapes, etc.) can't silently break extraction.
+ *
+ * Fixture: small synthesized Ink-style fragment containing a
+ * `● switchroom-telegram - reply (MCP)(... text: "...")` marker.
+ * Kept ≤2KB.
+ *
+ * Recapture procedure (for future maintainers):
+ *
+ *   To regenerate this fixture from a live tmux-supervised agent:
+ *     1. tail -c 250 "$AGENT_DIR/service.log" \
+ *          > telegram-plugin/tests/fixtures/pty-tail-tmux-fragment.bin
+ *        (adjust byte count as needed; aim for the smallest tail that
+ *        still contains a complete `● switchroom-telegram - reply (MCP)`
+ *        block including the `text: "..."` argument).
+ *     2. Run this test; it should still parse the marker.
+ *
+ *   If the parse breaks after Ink rendering changes upstream (Claude
+ *   updates how MCP tool calls are rendered, terminal width changes,
+ *   etc.), recapture from a known-good agent and confirm the
+ *   `V1Extractor` still finds `● switchroom-telegram - reply (MCP)`
+ *   in the rendered terminal output.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Terminal } from '@xterm/headless'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { V1Extractor } from '../pty-tail.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const FIXTURE_PATH = resolve(__dirname, 'fixtures', 'pty-tail-tmux-fragment.bin')
+
+async function feed(input: string): Promise<Terminal> {
+  const term = new Terminal({
+    cols: 132,
+    rows: 40,
+    scrollback: 5000,
+    allowProposedApi: true,
+  })
+  await new Promise<void>((res) => {
+    term.write(input, () => res())
+  })
+  return term
+}
+
+describe('V1Extractor — tmux pipe-pane fragment (#725)', () => {
+  it('fixture is small (≤2KB) so test data stays cheap to maintain', () => {
+    const bytes = readFileSync(FIXTURE_PATH)
+    expect(bytes.length).toBeLessThanOrEqual(2048)
+    expect(bytes.length).toBeGreaterThan(0)
+  })
+
+  it('extracts the reply text from a synthesized tmux pipe-pane fragment', async () => {
+    const raw = readFileSync(FIXTURE_PATH, 'utf8')
+    const term = await feed(raw)
+    const extracted = new V1Extractor().extract(term)
+    expect(extracted).not.toBeNull()
+    // Continuation lines collapse to single-spaced text.
+    expect(extracted).toContain('Hello')
+    expect(extracted).toContain('from tmux pipe-pane fragment')
+  })
+})