switchroom 0.5.0

package/telegram-plugin/gateway/pid-file.ts

@@ -0,0 +1,103 @@
+/**
+ * Gateway PID file — records the live gateway's PID so the in-agent
+ * plugin (server.ts dual-mode probe) can distinguish "gateway is
+ * genuinely gone, fall back to legacy monolith" from "gateway is alive
+ * but the socket blinked (EAGAIN, accept-backlog, handshake race)".
+ *
+ * 2026-04-22 incident: a transient Bun.connect failure against a LIVE
+ * gateway tripped the legacy-fallback path in server.ts, spawning a
+ * second grammY long-poll client. That client 409'd against the
+ * gateway's own poller, which fired a grammY poll-restart, which fired
+ * the "⚡ Recovered from unexpected restart" banner — without any
+ * actual process restart (same PID across 8 minutes, systemd logged
+ * zero lifecycle events).
+ *
+ * Rule: fall back to legacy ONLY if no PID file exists OR the recorded
+ * PID is dead. If the PID is alive, retry the socket with backoff.
+ */
+
+import { writeFileSync, readFileSync, unlinkSync, renameSync } from "node:fs";
+
+/** Shape of the PID file on disk. */
+export interface GatewayPidRecord {
+  pid: number;
+  /** epoch ms when this process started (Date.now() at write time) */
+  startedAtMs: number;
+}
+
+/**
+ * Atomic write via tmp+rename so a crashed writer can't leave a
+ * half-written file that subsequent readers mistake for a live PID.
+ */
+export function writePidFile(path: string, record: GatewayPidRecord): void {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(record), "utf-8");
+  renameSync(tmp, path);
+}
+
+export function readPidFile(path: string): GatewayPidRecord | null {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<GatewayPidRecord>;
+    if (
+      typeof parsed.pid === "number" &&
+      typeof parsed.startedAtMs === "number" &&
+      Number.isFinite(parsed.pid) &&
+      Number.isFinite(parsed.startedAtMs)
+    ) {
+      return { pid: parsed.pid, startedAtMs: parsed.startedAtMs };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function clearPidFile(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    /* best effort */
+  }
+}
+
+/**
+ * Returns true if the PID refers to a live process. Uses kill(pid, 0)
+ * which sends no signal but throws ESRCH if the process is gone.
+ * EPERM means the process exists but is owned by another user — we
+ * conservatively treat that as alive (don't fall back to legacy).
+ */
+export function isPidAlive(
+  pid: number,
+  killFn: (p: number, sig: number) => void = (p, s) => process.kill(p, s),
+): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  if (pid === process.pid) return true;
+  try {
+    killFn(pid, 0);
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
+
+/**
+ * Pure decision function for the dual-mode probe. Extracted so the
+ * fallback policy is testable in isolation.
+ *
+ * Fall back to legacy ONLY when we have strong evidence the gateway is
+ * truly gone — no PID file OR a dead PID. A transient socket miss
+ * against a live PID means "retry the socket", not "spawn a second
+ * poller".
+ */
+export function shouldFallBackToLegacy(input: {
+  socketReachable: boolean;
+  pidFileExists: boolean;
+  pidAlive: boolean;
+}): boolean {
+  if (input.socketReachable) return false;
+  if (!input.pidFileExists) return true;
+  return !input.pidAlive;
+}

package/telegram-plugin/gateway/poll-health.ts

@@ -0,0 +1,156 @@
+/**
+ * Long-poll health-check for the Telegram gateway.
+ *
+ * Motivation (issue #56):
+ *   grammY's runner holds a permanent HTTPS connection to Telegram's
+ *   getUpdates endpoint. On some network paths this connection can
+ *   silently freeze — the TCP socket stays open but no bytes flow.
+ *   The runner's `isRunning()` stays true and the gateway appears
+ *   alive, but Telegram messages never arrive.
+ *
+ * Fix:
+ *   A separate setInterval calls `getMe()` (a lightweight Bot API
+ *   endpoint) every HEALTH_INTERVAL_MS. Three consecutive failures
+ *   constitute a stall: we stop the runner, wait RESTART_GRACE_MS
+ *   for the in-flight request to die, then let the caller restart it.
+ *
+ *   A single failure doesn't count — transient network blips happen.
+ *   The threshold must be >= 3 so a brief Telegram outage (e.g. a
+ *   data-centre hiccup) doesn't cause thrashing.
+ *
+ * Usage:
+ *   const hc = createPollHealthCheck({
+ *     ping:  () => bot.api.getMe(),
+ *     onStall: async () => { await runnerHandle.stop(); … restart … },
+ *     log:   (msg) => process.stderr.write(msg),
+ *   });
+ *   // start after the runner is up:
+ *   hc.start();
+ *   // on clean shutdown:
+ *   hc.stop();
+ */
+
+export interface PollHealthCheckOptions {
+  /**
+   * Lightweight Bot API probe. Implementations should call `bot.api.getMe()`
+   * or similar. The check is marked as a failure if this rejects.
+   */
+  ping: () => Promise<unknown>;
+
+  /**
+   * Called when `failureThreshold` consecutive pings have failed.
+   * The health check stops itself before calling this, so `onStall`
+   * is called at most once per `start()`. The implementation should
+   * restart the runner and call `healthCheck.start()` again when ready.
+   */
+  onStall: () => Promise<void>;
+
+  /** Interval between health pings. Defaults to 5 minutes. */
+  intervalMs?: number;
+
+  /**
+   * Number of consecutive failures before `onStall` fires.
+   * Defaults to 3.
+   */
+  failureThreshold?: number;
+
+  /** Logger. Defaults to process.stderr. */
+  log?: (msg: string) => void;
+
+  /**
+   * Injectable timer (for tests). Defaults to setInterval / clearInterval.
+   */
+  setIntervalFn?: (fn: () => void, ms: number) => ReturnType<typeof setInterval>;
+  clearIntervalFn?: (id: ReturnType<typeof setInterval>) => void;
+}
+
+export interface PollHealthCheckHandle {
+  /** Start the periodic health-check interval. Idempotent. */
+  start(): void;
+  /** Stop the interval without triggering onStall. Idempotent. */
+  stop(): void;
+  /** Current count of consecutive failures (exposed for testing). */
+  consecutiveFailures(): number;
+}
+
+const DEFAULT_LOG = (msg: string): void => {
+  process.stderr.write(msg.endsWith("\n") ? msg : msg + "\n");
+};
+
+export function createPollHealthCheck(
+  options: PollHealthCheckOptions,
+): PollHealthCheckHandle {
+  const {
+    ping,
+    onStall,
+    intervalMs = 5 * 60_000,
+    failureThreshold = 3,
+    log = DEFAULT_LOG,
+    setIntervalFn = setInterval,
+    clearIntervalFn = clearInterval,
+  } = options;
+
+  let timer: ReturnType<typeof setInterval> | null = null;
+  let failures = 0;
+  let active = false;
+
+  async function tick(): Promise<void> {
+    try {
+      await ping();
+      if (failures > 0) {
+        log(`telegram gateway: poll.health_check recovered after ${failures} failure(s)`);
+      }
+      failures = 0;
+    } catch (err) {
+      failures++;
+      const msg = err instanceof Error ? err.message : String(err);
+      log(
+        `telegram gateway: poll.health_check ping failed (${failures}/${failureThreshold}): ${msg}`,
+      );
+      if (failures >= failureThreshold) {
+        log(
+          `telegram gateway: poll.health_check stall detected after ${failures} consecutive failures — triggering recovery`,
+        );
+        // Stop before calling onStall so we don't fire again during recovery.
+        doStop();
+        try {
+          await onStall();
+        } catch (stallErr) {
+          log(
+            `telegram gateway: poll.health_check onStall error: ${stallErr instanceof Error ? stallErr.message : String(stallErr)}`,
+          );
+        }
+      }
+    }
+  }
+
+  function doStop(): void {
+    active = false;
+    if (timer !== null) {
+      clearIntervalFn(timer);
+      timer = null;
+    }
+  }
+
+  return {
+    start(): void {
+      if (active) return; // idempotent
+      active = true;
+      failures = 0;
+      timer = setIntervalFn(() => { void tick(); }, intervalMs);
+      // unref so the interval doesn't prevent process exit on clean shutdown
+      if (typeof (timer as any)?.unref === "function") {
+        (timer as any).unref();
+      }
+      log(`telegram gateway: poll.health_check started interval=${intervalMs}ms threshold=${failureThreshold}`);
+    },
+
+    stop(): void {
+      doStop();
+    },
+
+    consecutiveFailures(): number {
+      return failures;
+    },
+  };
+}

package/telegram-plugin/gateway/preamble-suppressor.ts

@@ -0,0 +1,154 @@
+/**
+ * Preamble-text suppression for the answer-stream path (#549).
+ *
+ * When the agent emits assistant text BEFORE a tool call within the
+ * same turn, that text is "preamble" — think-out-loud guidance about
+ * what's about to happen. The progress-card driver consumes preamble
+ * text as a narrative row for the upcoming tool. Independently, the
+ * answer-stream path was also sending the same text to chat as a
+ * standalone message — so the user saw the same line twice (#549).
+ *
+ * This module isolates the buffering policy:
+ *
+ *   - `onText(chunk)` — append to the pending buffer; (re)start the
+ *     flush timer. If no `onTool` arrives within `bufferMs`, the timer
+ *     fires and treats the buffered text as ANSWER text (the agent
+ *     emitted it as the reply, not as preamble).
+ *
+ *   - `onTool({ isReplyTool })` — a non-reply tool consumes the
+ *     pending buffer as preamble (drop). A reply/stream_reply tool is
+ *     itself the answer surface; flush so its text isn't suppressed
+ *     when delivered via separate paths.
+ *
+ *   - `flushNow()` — force-flush whatever's pending (used at turn_end
+ *     when no preamble-claiming tool ever arrived).
+ *
+ *   - `dropNow()` — drop without flushing (used when the answer
+ *     stream is being torn down for an unrelated reason).
+ *
+ *   - `reset()` — clear ALL state including `answerTextOnly` (called
+ *     at fresh-turn enqueue).
+ *
+ * The class owns its own state so the gateway's module-level mutable
+ * state stays bounded. Pure aside from the supplied `flushFn` and
+ * `setTimer` / `clearTimer` (injected for tests so vi.useFakeTimers
+ * can drive them).
+ */
+
+export interface PreambleSuppressorDeps {
+  /**
+   * Called when a chunk has been promoted from "pending" to "answer
+   * text." Receives the cumulative answer text since the last reset()
+   * — caller should treat it as the full answer-stream payload.
+   */
+  emitAnswer: (cumulativeAnswerText: string) => void
+
+  /**
+   * Buffer window in ms. Default 150ms — long enough that a
+   * tool_use following a text emit comfortably arrives within the
+   * window, short enough that a true answer-text reply still feels
+   * snappy. Override in tests with `vi.useFakeTimers()`.
+   */
+  bufferMs?: number
+
+  /**
+   * Injected for testability. Defaults to global setTimeout/clearTimeout.
+   */
+  setTimer?: (fn: () => void, ms: number) => unknown
+  clearTimer?: (handle: unknown) => void
+}
+
+const DEFAULT_BUFFER_MS = 150
+
+export class PreambleSuppressor {
+  private readonly emitAnswer: (text: string) => void
+  private readonly bufferMs: number
+  private readonly setTimer: (fn: () => void, ms: number) => unknown
+  private readonly clearTimer: (handle: unknown) => void
+  private answerTextOnly = ''
+  private pendingBuffer = ''
+  private pendingTimer: unknown = null
+
+  constructor(deps: PreambleSuppressorDeps) {
+    this.emitAnswer = deps.emitAnswer
+    this.bufferMs = deps.bufferMs ?? DEFAULT_BUFFER_MS
+    this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms))
+    this.clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>))
+  }
+
+  /** Append a text chunk and (re)arm the flush timer. */
+  onText(chunk: string): void {
+    if (chunk.length === 0) return
+    this.pendingBuffer += chunk
+    if (this.pendingTimer != null) this.clearTimer(this.pendingTimer)
+    this.pendingTimer = this.setTimer(() => this.flushNow(), this.bufferMs)
+  }
+
+  /**
+   * Tool-use signal. Non-reply tools consume the buffer as preamble
+   * (drop). Reply/stream_reply tools flush the buffer as answer text
+   * (their own payload IS the answer surface; flushing here keeps the
+   * chat-side state consistent).
+   */
+  onTool(opts: { isReplyTool: boolean }): void {
+    if (opts.isReplyTool) {
+      this.flushNow()
+    } else {
+      this.dropNow()
+    }
+  }
+
+  /** Force-flush any pending text as answer text. Idempotent. */
+  flushNow(): void {
+    if (this.pendingTimer != null) {
+      this.clearTimer(this.pendingTimer)
+      this.pendingTimer = null
+    }
+    if (this.pendingBuffer.length === 0) return
+    this.answerTextOnly += this.pendingBuffer
+    this.pendingBuffer = ''
+    this.emitAnswer(this.answerTextOnly)
+  }
+
+  /**
+   * Drop pending text without flushing. Idempotent. Also clears
+   * `answerTextOnly` to prevent cross-turn contamination — the
+   * silent-marker / turn-flush teardown sites use dropNow because
+   * the text is being handed off to other paths (currentTurnCapturedText
+   * → turn-flush; silent suppression). Leaving stale answer text in
+   * the suppressor would prepend it to the next turn's first flush.
+   */
+  dropNow(): void {
+    if (this.pendingTimer != null) {
+      this.clearTimer(this.pendingTimer)
+      this.pendingTimer = null
+    }
+    this.pendingBuffer = ''
+    this.answerTextOnly = ''
+  }
+
+  /**
+   * Full reset — clears the cumulative answer-text-only memory plus
+   * the pending buffer. Call on fresh-turn enqueue.
+   */
+  reset(): void {
+    if (this.pendingTimer != null) {
+      this.clearTimer(this.pendingTimer)
+      this.pendingTimer = null
+    }
+    this.pendingBuffer = ''
+    this.answerTextOnly = ''
+  }
+
+  // ─── Test introspection ───────────────────────────────────────────────
+
+  /** True if the buffer holds text waiting for a flush decision. */
+  hasPending(): boolean {
+    return this.pendingBuffer.length > 0
+  }
+
+  /** Current cumulative answer-text-only payload. */
+  currentAnswerText(): string {
+    return this.answerTextOnly
+  }
+}

package/telegram-plugin/gateway/quota-cache.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared quota probe cache.
+ *
+ * Background: every gateway boot AND every bridge-reconnect calls
+ * `probeQuota` which hits Anthropic's /api/oauth/usage endpoint. With
+ * four agents on one OAuth account and reconnects happening multiple
+ * times per minute (per the boot-card-on-every-start design), the
+ * endpoint returns 429 and the boot card shows 🟡 "rate limited" — a
+ * cosmetic alarm caused by the boot card itself.
+ *
+ * Cache the result for 5 min in a single file shared across all agents.
+ * On a hit, the cached ProbeResult is returned instead of making the
+ * HTTP call. 429 (rate-limited) results are cached for a shorter 30 s
+ * window so fleet-restart bursts are absorbed without holding stale state
+ * for 5 min. Fail results are never cached.
+ *
+ * Cache location: `~/.switchroom/quota-cache.json` (mode 0600). Format:
+ *   { capturedAt: string, ttlMs: number, result: ProbeResult }
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import type { ProbeResult } from './boot-probes.js'
+
+export interface QuotaCacheEntry {
+  capturedAt: string  // ISO 8601
+  ttlMs: number
+  result: ProbeResult
+}
+
+export const DEFAULT_TTL_MS = 5 * 60 * 1000  // 5 min
+
+/**
+ * Short TTL used when caching a 429 result. 30 s is long enough to absorb
+ * a simultaneous fleet restart (all N agents firing their quota probe within
+ * the same second) while clearing fast enough that any real retry or the
+ * next scheduled boot gets a live result.
+ */
+export const RATE_LIMIT_TTL_MS = 30 * 1000  // 30 s
+export const DEFAULT_CACHE_PATH =
+  process.env.SWITCHROOM_QUOTA_CACHE_PATH
+    ?? join(process.env.HOME ?? '/tmp', '.switchroom', 'quota-cache.json')
+
+/**
+ * Read a cached probe result if one exists and is still within TTL.
+ * Returns null on:
+ *   - file missing
+ *   - JSON parse error
+ *   - cache entry past its TTL
+ *
+ * Pure helper — accepts a clock so tests can advance time.
+ */
+export function readQuotaCache(opts: {
+  path?: string
+  now?: number
+} = {}): ProbeResult | null {
+  const path = opts.path ?? DEFAULT_CACHE_PATH
+  const now = opts.now ?? Date.now()
+
+  if (!existsSync(path)) return null
+
+  let entry: QuotaCacheEntry
+  try {
+    entry = JSON.parse(readFileSync(path, 'utf8')) as QuotaCacheEntry
+  } catch {
+    return null
+  }
+
+  const capturedAtMs = Date.parse(entry.capturedAt)
+  if (!isFinite(capturedAtMs)) return null
+
+  const ageMs = now - capturedAtMs
+  if (ageMs < 0) return null  // clock went backwards; treat as miss
+  if (ageMs >= entry.ttlMs) return null  // expired
+
+  return entry.result
+}
+
+/**
+ * Write a probe result to the cache.
+ *
+ * Normal results (ok / degraded non-rate-limit) use the standard 5-min TTL.
+ * A result with `rateLimited: true` (HTTP 429) uses the short
+ * RATE_LIMIT_TTL_MS (30 s) so back-to-back fleet restarts read the cached
+ * 'ok' row instead of piling up on the endpoint, while still clearing fast
+ * enough for any real next-boot probe to see a live result.
+ *
+ * Fail results are still not cached — they indicate a real error and the
+ * next boot should always retry.
+ *
+ * Writes are best-effort: any IO error is swallowed (cache is an
+ * optimization, not a correctness requirement).
+ */
+export function writeQuotaCache(
+  result: ProbeResult,
+  opts: {
+    path?: string
+    ttlMs?: number
+    now?: number
+  } = {},
+): void {
+  // Don't cache hard failures — let the next boot retry clean.
+  if (result.status === 'fail') return
+
+  const path = opts.path ?? DEFAULT_CACHE_PATH
+  // Rate-limit results use a shorter TTL: long enough to absorb a fleet
+  // restart burst, short enough that subsequent boots get a live probe.
+  // Use the structured `rateLimited` field rather than string-matching on
+  // `detail` — the detail string is user-facing and may change.
+  const ttlMs = opts.ttlMs ?? (result.rateLimited ? RATE_LIMIT_TTL_MS : DEFAULT_TTL_MS)
+  const now = opts.now ?? Date.now()
+
+  const entry: QuotaCacheEntry = {
+    capturedAt: new Date(now).toISOString(),
+    ttlMs,
+    result,
+  }
+
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(entry, null, 2), { mode: 0o600 })
+  } catch {
+    // Best-effort. Swallow.
+  }
+}

package/telegram-plugin/gateway/resolve-calling-subagent.ts

@@ -0,0 +1,78 @@
+/**
+ * Issue #305 Option A — resolve which sub-agent (by jsonl_agent_id) is
+ * calling progress_update.
+ *
+ * Three resolution strategies, in priority order:
+ *   1. agentIdHint — exact match on subagents.jsonl_agent_id
+ *   2. toolUseIdHint — exact match on subagents.id (parent's Agent tool_use_id)
+ *   3. Heuristic: most-recently-started running sub-agent in the active turn
+ *      for this chat. Logs a stderr warning when multiple candidates exist.
+ *
+ * Returns null if no match (caller falls through to message-send).
+ * Never throws; SQL errors return null.
+ *
+ * Extracted from gateway.ts so the resolver can be unit-tested against an
+ * in-memory SQLite DB without spinning up the full grammY bot harness.
+ */
+
+/**
+ * Minimal duck-typed interface that matches both bun:sqlite's `Database`
+ * and the `SqliteDatabase` shape returned by `openTurnsDb`. We accept the
+ * narrowed shape so the resolver can run against any equivalent handle.
+ */
+export interface ResolverDb {
+  prepare(sql: string): {
+    get(...params: unknown[]): unknown
+    all(...params: unknown[]): unknown[]
+  }
+}
+
+export interface ResolveCallingSubagentOpts {
+  db: ResolverDb | null
+  chatId: string
+  threadId?: number | string
+  agentIdHint: string | null
+  toolUseIdHint: string | null
+}
+
+export type ResolveCallingSubagentResult = { agentId: string } | null
+
+export function resolveCallingSubagent(
+  opts: ResolveCallingSubagentOpts,
+): ResolveCallingSubagentResult {
+  if (opts.db == null) return null
+  try {
+    if (opts.agentIdHint != null) {
+      const row = opts.db.prepare(
+        "SELECT jsonl_agent_id FROM subagents WHERE jsonl_agent_id = ? AND status = 'running'",
+      ).get(opts.agentIdHint) as { jsonl_agent_id: string } | undefined
+      if (row?.jsonl_agent_id) return { agentId: row.jsonl_agent_id }
+    }
+    if (opts.toolUseIdHint != null) {
+      const row = opts.db.prepare(
+        "SELECT jsonl_agent_id FROM subagents WHERE id = ? AND status = 'running'",
+      ).get(opts.toolUseIdHint) as { jsonl_agent_id: string | null } | undefined
+      if (row?.jsonl_agent_id) return { agentId: row.jsonl_agent_id }
+    }
+    // Heuristic fallback.
+    const turnRow = opts.db.prepare(
+      "SELECT turn_key FROM turns WHERE chat_id = ? AND ended_at IS NULL ORDER BY started_at DESC LIMIT 1",
+    ).get(opts.chatId) as { turn_key: string } | undefined
+    if (turnRow?.turn_key == null) return null
+    const candidates = opts.db.prepare(
+      "SELECT jsonl_agent_id FROM subagents WHERE parent_turn_key = ? AND status = 'running' AND jsonl_agent_id IS NOT NULL ORDER BY started_at DESC",
+    ).all(turnRow.turn_key) as Array<{ jsonl_agent_id: string }>
+    if (candidates.length === 0) return null
+    if (candidates.length > 1) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `progress_update: heuristic resolution selected most-recent of ${candidates.length} running sub-agents (chat=${opts.chatId}); pass agent_id explicitly to avoid mis-attribution`,
+      )
+    }
+    return { agentId: candidates[0].jsonl_agent_id }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn('progress_update: resolveCallingSubagent SQL error', err)
+    return null
+  }
+}