switchroom 0.5.0

package/telegram-plugin/gateway/inbound-coalesce.ts

@@ -0,0 +1,147 @@
+/**
+ * Inbound message coalescer — buffers consecutive messages from the same
+ * (chat, user) pair so the gateway dispatches them as one Claude turn
+ * instead of N rapid-fire turns. Pulled out of `gateway.ts` (#553 Phase 3)
+ * so the real-gateway test harness can exercise the same coalescing
+ * timing the production gateway uses, instead of a parallel reimplementation.
+ *
+ * Behaviour pinned (tests cover all four):
+ *   - First message: schedule a flush after `gapMs`.
+ *   - Subsequent message before flush: append to the buffer, reset the
+ *     timer (sliding window, not fixed-window — typical "user keeps
+ *     typing → keep waiting").
+ *   - Flush invokes `onFlush(key, joined)` exactly once with the
+ *     accumulated text joined by `'\n'`.
+ *   - `gapMs <= 0` disables coalescing (caller gets back a synchronous
+ *     "flush immediately" path via the `bypass` field).
+ *
+ * Out of scope: the user-perceived "👀 reaction within 800ms" deadline
+ * (#545 F2) — that's a separate problem rooted in the gateway calling
+ * `firstPaintTurn` from inside the coalesced flush instead of on raw
+ * arrival. The real-gateway harness asserts the deadline and the F2 fix
+ * will move first-paint out of the coalesce flush. This module just owns
+ * the "wait for the user to stop typing" buffer.
+ *
+ * Generic over `T` so the harness can pass `{ text: string }` while the
+ * production gateway passes its full `CoalesceEntry` (ctx + attachments
+ * + downloadImage closure). The buffer doesn't care.
+ */
+
+export interface InboundCoalescerOptions<T> {
+  /**
+   * Sliding window in ms. Each new message resets the timer. Set to
+   * `<= 0` to disable coalescing entirely (`enqueue` returns
+   * `{ bypass: true }` and the caller should flush immediately).
+   *
+   * Pass a function (`() => number`) instead of a number when the
+   * window is config-driven and the operator can change it at runtime
+   * — gateway.ts reads it per-call from the access file so a
+   * `/access set-coalesce 500` takes effect on the next message
+   * without restarting the gateway.
+   */
+  gapMs: number | (() => number)
+  /**
+   * Called when the buffered window expires. Receives the buffer key
+   * and the merged payload (last-write-wins for non-text fields,
+   * concatenated text via `merge`).
+   */
+  onFlush: (key: string, merged: T) => void
+  /**
+   * Build a merged payload from the accumulated entries. Lets callers
+   * decide how to combine non-text fields (e.g. "use the latest
+   * downloadImage closure", "concat all texts with '\n'").
+   */
+  merge: (entries: T[]) => T
+  /**
+   * Timer factory. Defaults to `setTimeout`. Override in tests for
+   * deterministic time control under fake timers.
+   */
+  setTimer?: (cb: () => void, ms: number) => ReturnType<typeof setTimeout>
+  /**
+   * Timer canceller. Defaults to `clearTimeout`.
+   */
+  clearTimer?: (handle: ReturnType<typeof setTimeout>) => void
+}
+
+interface BufferEntry<T> {
+  payloads: T[]
+  timer: ReturnType<typeof setTimeout>
+}
+
+export interface InboundCoalescer<T> {
+  /**
+   * Buffer a payload under `key`. Returns `{ bypass: true }` when
+   * coalescing is disabled — caller should flush immediately and skip
+   * the buffer entirely.
+   */
+  enqueue(key: string, payload: T): { bypass: boolean }
+  /**
+   * Inspect buffer state — for diagnostics + tests. Don't mutate.
+   */
+  peek(key: string): { count: number } | null
+  /** Total number of buffered entries — for /status surface. */
+  size(): number
+  /**
+   * Cancel any pending timers and drop all buffered entries. Tests
+   * use this; production code shouldn't unless the gateway is shutting
+   * down.
+   */
+  reset(): void
+}
+
+export function createInboundCoalescer<T>(opts: InboundCoalescerOptions<T>): InboundCoalescer<T> {
+  const buffer = new Map<string, BufferEntry<T>>()
+  const setTimer = opts.setTimer ?? setTimeout
+  const clearTimer = opts.clearTimer ?? clearTimeout
+
+  function flush(key: string): void {
+    const entry = buffer.get(key)
+    if (!entry) return
+    buffer.delete(key)
+    opts.onFlush(key, opts.merge(entry.payloads))
+  }
+
+  function resolveGap(): number {
+    return typeof opts.gapMs === 'function' ? opts.gapMs() : opts.gapMs
+  }
+
+  return {
+    enqueue(key, payload) {
+      const gapMs = resolveGap()
+      if (gapMs <= 0) return { bypass: true }
+      const existing = buffer.get(key)
+      if (existing) {
+        clearTimer(existing.timer)
+        existing.payloads.push(payload)
+        existing.timer = setTimer(() => flush(key), gapMs)
+      } else {
+        buffer.set(key, {
+          payloads: [payload],
+          timer: setTimer(() => flush(key), gapMs),
+        })
+      }
+      return { bypass: false }
+    },
+    peek(key) {
+      const e = buffer.get(key)
+      return e ? { count: e.payloads.length } : null
+    },
+    size() {
+      return buffer.size
+    },
+    reset() {
+      for (const entry of buffer.values()) clearTimer(entry.timer)
+      buffer.clear()
+    },
+  }
+}
+
+/**
+ * Build a coalesce key from `(chatId, userId)`. Identity-stable across
+ * messages from the same sender in the same chat, distinct across
+ * different senders so a user-driven reply isn't merged with a sibling
+ * message from someone else in a group chat.
+ */
+export function inboundCoalesceKey(chatId: string, userId: string): string {
+  return `${chatId}:${userId}`
+}

package/telegram-plugin/gateway/inject-handler.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Unit tests for the /inject Telegram handler (#725 epic UX upgrade).
+ *
+ * The handler is factored out of gateway.ts so we can exercise it
+ * without booting grammy/Bot. Real tmux is never touched — the inject
+ * function is mocked via the InjectDeps seam.
+ *
+ * Run with: npx vitest run telegram-plugin/gateway/inject-handler.test.ts
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import type { Context } from 'grammy'
+import { handleInjectCommand, type InjectDeps, type InjectAccent } from './inject-handler.js'
+import { InjectError, INJECT_COMMANDS, type InjectResult } from '../../src/agents/inject.js'
+
+function fakeCtx(): Context {
+  return {} as unknown as Context
+}
+
+interface CapturedReply {
+  text: string
+  opts?: { html?: boolean; accent?: InjectAccent }
+}
+
+function makeDeps(overrides: Partial<InjectDeps> = {}): {
+  deps: InjectDeps
+  replies: CapturedReply[]
+} {
+  const replies: CapturedReply[] = []
+  const deps: InjectDeps = {
+    isAuthorized: () => true,
+    inject: vi.fn().mockResolvedValue({
+      outcome: 'ok',
+      output: 'mock',
+      truncated: false,
+      command: '/cost',
+      meta: INJECT_COMMANDS.get('/cost') ?? null,
+    } satisfies InjectResult),
+    reply: async (_ctx, text, opts) => {
+      replies.push({ text, opts })
+    },
+    getAgentName: () => 'gymbro',
+    getArgs: () => '/cost',
+    escapeHtml: (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'),
+    preBlock: (s) => `<pre>${s}</pre>`,
+    ...overrides,
+  }
+  return { deps, replies }
+}
+
+function okResult(verb: string, output: string, truncated = false): InjectResult {
+  return {
+    outcome: 'ok',
+    output,
+    truncated,
+    command: verb,
+    meta: INJECT_COMMANDS.get(verb) ?? null,
+    ...(truncated ? { diagnostic: 'truncated_output' as const } : {}),
+  }
+}
+
+function noOutputResult(verb: string): InjectResult {
+  return {
+    outcome: 'ok_no_output',
+    output: '',
+    truncated: false,
+    command: verb,
+    meta: INJECT_COMMANDS.get(verb) ?? null,
+  }
+}
+
+function failedResult(
+  verb: string,
+  errorCode: NonNullable<InjectResult['errorCode']>,
+  errorMessage: string,
+): InjectResult {
+  return {
+    outcome: 'failed',
+    output: '',
+    truncated: false,
+    command: verb,
+    meta: INJECT_COMMANDS.get(verb) ?? null,
+    errorCode,
+    errorMessage,
+  }
+}
+
+describe('handleInjectCommand — guards', () => {
+  it('drops messages from unauthorized senders without replying', async () => {
+    const { deps, replies } = makeDeps({ isAuthorized: () => false })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies).toHaveLength(0)
+    expect(deps.inject).not.toHaveBeenCalled()
+  })
+
+  it('replies with usage when no slash-command argument is provided', async () => {
+    const inject = vi.fn()
+    const { deps, replies } = makeDeps({ getArgs: () => '', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(inject).not.toHaveBeenCalled()
+    expect(replies).toHaveLength(1)
+    expect(replies[0].text).toContain('Usage')
+    expect(replies[0].text).toContain('/cost')
+  })
+})
+
+describe('handleInjectCommand — outcome=ok', () => {
+  it('renders verb + pre-block, accent=done', async () => {
+    const inject = vi.fn().mockResolvedValue(okResult('/cost', 'Total cost: $0.42'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/cost', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies).toHaveLength(1)
+    expect(replies[0].opts?.accent).toBe('done')
+    expect(replies[0].text).toContain('✅')
+    expect(replies[0].text).toContain('<code>/cost</code>')
+    expect(replies[0].text).toContain('<pre>Total cost: $0.42</pre>')
+  })
+
+  it('appends <i>truncated</i> when output truncated', async () => {
+    const inject = vi.fn().mockResolvedValue(okResult('/cost', 'a lot of text', true))
+    const { deps, replies } = makeDeps({ getArgs: () => '/cost', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].text).toContain('<i>truncated</i>')
+    expect(replies[0].opts?.accent).toBe('done')
+  })
+
+  it('prepends slash if the operator omitted it', async () => {
+    const inject = vi.fn().mockResolvedValue(okResult('/cost', 'ok'))
+    const { deps } = makeDeps({ getArgs: () => 'cost', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(inject).toHaveBeenCalledWith('gymbro', '/cost')
+  })
+})
+
+describe('handleInjectCommand — outcome=ok_no_output', () => {
+  it('uses silentNote when meta provides one (e.g. /compact)', async () => {
+    const inject = vi.fn().mockResolvedValue(noOutputResult('/compact'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/compact', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('done')
+    expect(replies[0].text).toContain('<code>/compact</code>')
+    expect(replies[0].text).toContain('compaction runs silently')
+    expect(replies[0].text).not.toContain('<pre>')
+  })
+
+  it('warns with accent=issue when expectsOutput=true and capture empty (/cost)', async () => {
+    const inject = vi.fn().mockResolvedValue(noOutputResult('/cost'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/cost', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('issue')
+    expect(replies[0].text).toContain('⚠️')
+    expect(replies[0].text).toContain('empty capture')
+  })
+
+  it('bare ack with accent=done when expectsOutput=false and no silentNote (/clear)', async () => {
+    const inject = vi.fn().mockResolvedValue(noOutputResult('/clear'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/clear', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('done')
+    expect(replies[0].text).toContain('<code>/clear</code>')
+    expect(replies[0].text).not.toContain('empty capture')
+    expect(replies[0].text).not.toContain('<pre>')
+  })
+})
+
+describe('handleInjectCommand — outcome=failed', () => {
+  it('not_allowed: lists allowed verbs, accent=issue', async () => {
+    const inject = vi
+      .fn()
+      .mockResolvedValue(failedResult('/foo', 'not_allowed', '/foo not in allowlist'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/foo', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('issue')
+    expect(replies[0].text).toContain('not allowed')
+    expect(replies[0].text).toContain('/cost')
+    expect(replies[0].text).toContain('/clear')
+  })
+
+  it('blocked: surfaces parenthetical reason', async () => {
+    const inject = vi
+      .fn()
+      .mockResolvedValue(
+        failedResult('/login', 'blocked', '/login is explicitly blocked from inject (would mutate auth state).'),
+      )
+    const { deps, replies } = makeDeps({ getArgs: () => '/login', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('issue')
+    expect(replies[0].text).toContain('<code>/login</code>')
+    expect(replies[0].text).toContain('blocked: would mutate auth state')
+  })
+
+  it('session_missing: hints at experimental.legacy_pty', async () => {
+    const inject = vi
+      .fn()
+      .mockResolvedValue(failedResult('/cost', 'session_missing', 'session not found'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/cost', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('issue')
+    expect(replies[0].text).toContain('tmux session not found')
+    expect(replies[0].text).toContain('experimental.legacy_pty')
+  })
+
+  it('tmux_failed: surfaces escaped error message', async () => {
+    const inject = vi
+      .fn()
+      .mockResolvedValue(failedResult('/cost', 'tmux_failed', 'connection <refused>'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/cost', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('issue')
+    expect(replies[0].text).toContain('tmux send-keys failed')
+    expect(replies[0].text).toContain('connection &lt;refused&gt;')
+  })
+
+  it('thrown InjectError from inject() is normalized to outcome=failed', async () => {
+    const inject = vi.fn().mockRejectedValue(new InjectError('not_allowed', '/foo not allowed'))
+    const { deps, replies } = makeDeps({ getArgs: () => '/foo', inject })
+    await handleInjectCommand(fakeCtx(), deps)
+    expect(replies[0].opts?.accent).toBe('issue')
+    expect(replies[0].text).toContain('not allowed')
+  })
+})

package/telegram-plugin/gateway/inject-handler.ts

@@ -0,0 +1,190 @@
+/**
+ * #725 Phase 2 — Telegram /inject command handler.
+ *
+ * Lives in its own module so the unit tests can import it without
+ * triggering gateway.ts's top-level `new Bot(TOKEN)` initialisation.
+ * gateway.ts wires this into bot.command('inject', ...).
+ *
+ * UX upgrade: the underlying inject primitive now returns a tagged
+ * `InjectResult` (outcome of `ok | ok_no_output | failed`). This
+ * handler switches on that outcome and shapes a single Telegram
+ * reply per the table in the epic spec — accent header from
+ * stream-reply-handler's `buildAccentHeader` + a short body.
+ */
+
+import type { Context } from 'grammy'
+import {
+  INJECT_COMMANDS,
+  injectSlashCommand as defaultInject,
+  type InjectResult,
+} from '../../src/agents/inject.js'
+import { buildAccentHeader } from '../stream-reply-handler.js'
+
+export type InjectAccent = 'done' | 'issue' | 'in-progress'
+
+export interface InjectDeps {
+  isAuthorized: (ctx: Context) => boolean
+  inject: (agent: string, command: string) => Promise<InjectResult>
+  /**
+   * Send a reply. The optional `accent` lifts the status header into
+   * the rendered HTML body via `buildAccentHeader`. The handler always
+   * sends `html: true` so callers can prepend the accent header.
+   */
+  reply: (
+    ctx: Context,
+    text: string,
+    opts?: { html?: boolean; accent?: InjectAccent },
+  ) => Promise<void>
+  getAgentName: () => string
+  /** Pull the slash-command body out of the message (defaults to ctx.match-style logic). */
+  getArgs: (ctx: Context) => string
+  /** HTML-escape helper (matches gateway.ts's escapeHtmlForTg). */
+  escapeHtml: (s: string) => string
+  /** Format pre-block helper (matches gateway.ts's preBlock). */
+  preBlock: (s: string) => string
+  /** Optional formatter that trims/wraps the captured output. */
+  formatOutput?: (s: string) => string
+}
+
+/**
+ * Render the inject reply body. Accent header is prepended HERE so
+ * tests can assert exact final text — `deps.reply` is treated as a
+ * dumb sender. Returns { body, accent } for the caller to hand to
+ * `deps.reply`.
+ */
+function shapeReply(
+  result: InjectResult,
+  slashCommand: string,
+  deps: Pick<InjectDeps, 'escapeHtml' | 'preBlock' | 'formatOutput'>,
+): { body: string; accent: InjectAccent } {
+  const verbHtml = `<code>${deps.escapeHtml(result.command || slashCommand)}</code>`
+
+  if (result.outcome === 'ok') {
+    const formatted = deps.formatOutput ? deps.formatOutput(result.output) : result.output
+    let body = `${verbHtml}\n${deps.preBlock(formatted)}`
+    if (result.diagnostic === 'truncated_output' || result.truncated) {
+      body += '\n<i>truncated</i>'
+    }
+    return { body, accent: 'done' }
+  }
+
+  if (result.outcome === 'ok_no_output') {
+    const meta = result.meta
+    if (meta?.silentNote) {
+      return {
+        body: `${verbHtml} — ${deps.escapeHtml(meta.silentNote)}`,
+        accent: 'done',
+      }
+    }
+    if (meta?.expectsOutput) {
+      return {
+        body: `${verbHtml} — empty capture; agent may be busy or pane scrolled`,
+        accent: 'issue',
+      }
+    }
+    // expectsOutput=false, no silentNote — bare ack.
+    return { body: verbHtml, accent: 'done' }
+  }
+
+  // outcome === 'failed'
+  const code = result.errorCode ?? 'tmux_failed'
+  const msg = result.errorMessage ?? 'unknown error'
+  if (code === 'blocked') {
+    // errorMessage already mentions the reason; keep the body focused.
+    return {
+      body: `${verbHtml} — blocked: ${deps.escapeHtml(stripBlockedPrefix(msg))}`,
+      accent: 'issue',
+    }
+  }
+  if (code === 'not_allowed') {
+    const allowed = [...INJECT_COMMANDS.keys()].sort().join(' ')
+    return {
+      body: `${verbHtml} — not allowed. Try: ${deps.escapeHtml(allowed)}`,
+      accent: 'issue',
+    }
+  }
+  if (code === 'session_missing') {
+    return {
+      body: 'tmux session not found — agent must be running under the tmux supervisor (the default). Remove <code>experimental.legacy_pty: true</code> if set.',
+      accent: 'issue',
+    }
+  }
+  if (code === 'invalid') {
+    return {
+      body: 'usage: <code>/inject /&lt;command&gt;</code>',
+      accent: 'issue',
+    }
+  }
+  // tmux_failed / timeout / other
+  return {
+    body: `tmux send-keys failed: ${deps.escapeHtml(msg)}`,
+    accent: 'issue',
+  }
+}
+
+/**
+ * Strip the boilerplate "X is explicitly blocked from inject (" wrapper
+ * from a blocked-error message so the surfaced reason is just the
+ * parenthetical reason text. Defensive — falls through to the original
+ * message when the shape doesn't match.
+ */
+function stripBlockedPrefix(msg: string): string {
+  const m = /\(([^)]+)\)\.?$/.exec(msg)
+  return m ? m[1] : msg
+}
+
+export async function handleInjectCommand(ctx: Context, deps: InjectDeps): Promise<void> {
+  if (!deps.isAuthorized(ctx)) return
+  const arg = deps.getArgs(ctx).trim()
+  if (!arg) {
+    const allow = [...INJECT_COMMANDS.keys()].sort().join(', ')
+    await deps.reply(
+      ctx,
+      `Usage: <code>/inject &lt;slashCommand&gt;</code>\nAllowed: <code>${deps.escapeHtml(allow)}</code>`,
+      { html: true },
+    )
+    return
+  }
+  const slashCommand = arg.startsWith('/') ? arg : `/${arg}`
+  const agentName = deps.getAgentName()
+
+  let result: InjectResult
+  try {
+    result = await deps.inject(agentName, slashCommand)
+  } catch (err) {
+    // The default runner throws InjectError on validation failures (so
+    // CLI use that doesn't pre-validate still works). Surface as
+    // outcome=failed for shaping. Anything non-InjectError is an
+    // unexpected runtime — bubble a generic failure body.
+    const anyErr = err as { code?: string; message?: string; name?: string }
+    if (anyErr?.name === 'InjectError' && typeof anyErr.code === 'string') {
+      result = {
+        outcome: 'failed',
+        output: '',
+        truncated: false,
+        command: slashCommand.split(/\s+/, 1)[0]?.toLowerCase() ?? '',
+        meta: null,
+        errorCode: anyErr.code as InjectResult['errorCode'],
+        errorMessage: anyErr.message ?? 'inject failed',
+      }
+    } else {
+      result = {
+        outcome: 'failed',
+        output: '',
+        truncated: false,
+        command: slashCommand.split(/\s+/, 1)[0]?.toLowerCase() ?? '',
+        meta: null,
+        errorCode: 'tmux_failed',
+        errorMessage: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  const { body, accent } = shapeReply(result, slashCommand, deps)
+  // Prepend accent header into the body so callers downstream of
+  // deps.reply (and tests) see a single, fully-rendered string.
+  const finalText = buildAccentHeader(accent) + body
+  await deps.reply(ctx, finalText, { html: true, accent })
+}
+
+export { defaultInject }