switchroom 0.11.0 → 0.12.0

package/telegram-plugin/gateway/update-announce.ts

@@ -0,0 +1,167 @@
+/**
+ * Update-flow PR C — boot-card surfacing for MCP-originated updates.
+ *
+ * When an agent (e.g. klanker) runs `mcp__hostd__update_apply` the work
+ * happens hostd-side, the agent itself restarts at the end, and the
+ * resulting boot card for THIS agent (the one that just restarted via
+ * the redeploy) needs to surface the outcome — success or failure with a
+ * recovery hint — so the operator sees what happened without trawling
+ * the audit log.
+ *
+ * Implementation: on boot, scan ~/.switchroom/host-control-audit.log for
+ * the most recent `phase: "terminal"` `update_apply` row within a recent
+ * window. Dedupe via an atomic O_EXCL marker so a respawn within the
+ * window doesn't re-announce. Render a single line that's appended to
+ * the existing boot-card body.
+ *
+ * Pure & test-friendly — `readLastTerminalUpdateAudit` accepts an
+ * injectable file-reader, `renderUpdateOutcomeLine` is a pure function,
+ * and `claimUpdateAnnouncement` accepts an injectable claim-dir + clock.
+ */
+
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { readAndFilter, defaultAuditLogPath, type AuditEntry } from '../../src/host-control/audit-reader.js'
+
+/** Default lookback window: 10 minutes is enough to catch the boot that
+ *  follows a normal update_apply but small enough that an audit row from
+ *  yesterday's run can't re-trigger an announcement after a long
+ *  outage. */
+export const DEFAULT_LOOKBACK_MS = 10 * 60 * 1000
+
+export interface ReadOpts {
+  /** Read the file system. Override in tests. */
+  readFile?: (path: string) => string
+  /** Exists check. Override in tests. */
+  exists?: (path: string) => boolean
+  /** Override the audit-log path (defaults to ~/.switchroom/host-control-audit.log). */
+  auditLogPath?: string
+  /** Wall-clock for the lookback comparison. */
+  now?: number
+  /** Lookback window in ms. Defaults to {@link DEFAULT_LOOKBACK_MS}. */
+  lookbackMs?: number
+}
+
+/**
+ * Read the audit log and return the most-recent `update_apply` terminal
+ * row within the lookback window, or null if none. We deliberately do
+ * not filter by caller — any update_apply outcome is interesting to the
+ * person watching this chat regardless of which agent ran the verb.
+ */
+export function readLastTerminalUpdateAudit(opts: ReadOpts = {}): AuditEntry | null {
+  const path = opts.auditLogPath ?? defaultAuditLogPath()
+  const exists = opts.exists ?? existsSync
+  const readFile = opts.readFile ?? ((p: string) => readFileSync(p, 'utf-8'))
+  if (!exists(path)) return null
+  let raw: string
+  try {
+    raw = readFile(path)
+  } catch {
+    return null
+  }
+  // Pull recent update_apply rows, then trim to terminal-phase within window.
+  const recent = readAndFilter(raw, { op: 'update_apply' }, 200)
+  const now = opts.now ?? Date.now()
+  const since = now - (opts.lookbackMs ?? DEFAULT_LOOKBACK_MS)
+  let best: AuditEntry | null = null
+  for (const e of recent) {
+    if (e.phase !== 'terminal') continue
+    const ts = Date.parse(e.ts)
+    if (Number.isNaN(ts)) continue
+    if (ts < since) continue
+    if (best == null || Date.parse(best.ts) < ts) best = e
+  }
+  return best
+}
+
+const RECOVERY_HINTS: Record<string, string> = {
+  binary:
+    'curl https://switchroom.ai/install.sh | sh && switchroom update',
+  source:
+    'cd ~/code/switchroom && git pull && bun install && bun run build && switchroom update',
+  'source-unlinked':
+    'cd ~/code/switchroom && bun link && switchroom update  # ensures binary is in PATH first',
+  docker:
+    'docker compose -p switchroom pull && docker compose -p switchroom up -d',
+  unknown:
+    'Cannot auto-detect install type. Run `switchroom apply` to refresh ~/.switchroom/install-type.json, then retry.',
+}
+
+function recoveryHint(installType: string | undefined): string {
+  if (!installType) return RECOVERY_HINTS.unknown
+  return RECOVERY_HINTS[installType] ?? RECOVERY_HINTS.unknown
+}
+
+function shortSha(s: string): string {
+  return s.replace(/^sha256:/, '').slice(0, 12)
+}
+
+/**
+ * Pure renderer. Returns the single line (HTML-safe — plain ASCII)
+ * to append to the boot card body. `null` means nothing to surface
+ * (entry too stale, schema invalid, etc.).
+ */
+export function renderUpdateOutcomeLine(entry: AuditEntry): string {
+  const success = entry.exit_code === 0 && entry.result !== 'error' && entry.result !== 'denied'
+  if (success) {
+    const channel = entry.channel ? `channel:${entry.channel}` : entry.pin ? `pin:${entry.pin}` : 'channel:?'
+    let shaStr = ''
+    if (entry.resolved_sha) {
+      const firstSha = Object.values(entry.resolved_sha)[0]
+      if (firstSha) shaStr = `, sha:${shortSha(firstSha)}`
+    }
+    return `✅ update completed (${channel}${shaStr})`
+  }
+  const stderrTail = (entry.stderr_tail ?? entry.error ?? '').slice(-400)
+  const opStep = entry.op
+  const hint = recoveryHint(entry.install_context?.install_type)
+  // Single line is reader-friendly when short; multi-line when stderr is present.
+  const lines = [`❌ update failed at ${opStep}: ${stderrTail || '(no stderr captured)'}`, `    ↳ Recovery: ${hint}`]
+  return lines.join('\n')
+}
+
+export interface ClaimOpts {
+  /** Override state-dir base (default: $TELEGRAM_STATE_DIR or ~/.switchroom/<agent>/telegram). */
+  stateDir?: string
+}
+
+/**
+ * Atomic claim via `O_CREAT|O_EXCL` — returns true if THIS process is
+ * the first to announce this request_id. Idempotent across respawns
+ * within the same state-dir. We deliberately don't clean up old
+ * markers — they're tiny and bounded by the lookback window above.
+ */
+export function claimUpdateAnnouncement(requestId: string, opts: ClaimOpts = {}): boolean {
+  const stateDir = opts.stateDir ?? process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.switchroom')
+  const dir = join(stateDir, 'update-announced')
+  try {
+    mkdirSync(dir, { recursive: true })
+  } catch {
+    return false
+  }
+  const safeId = requestId.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 200)
+  const path = join(dir, safeId)
+  try {
+    // O_CREAT | O_EXCL — fails with EEXIST if another boot already
+    // claimed this request_id.
+    const fd = openSync(path, 'wx')
+    closeSync(fd)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Combined entry-point used by the gateway boot path: read + claim +
+ * render. Returns the line to append (already escaped for HTML — plain
+ * ASCII text — caller embeds with no further processing) or null when
+ * there's nothing to surface OR another boot already claimed the row.
+ */
+export function maybeRenderUpdateAnnouncement(opts: ReadOpts & ClaimOpts = {}): string | null {
+  const entry = readLastTerminalUpdateAudit(opts)
+  if (!entry) return null
+  if (!claimUpdateAnnouncement(entry.request_id, opts)) return null
+  return renderUpdateOutcomeLine(entry)
+}

package/telegram-plugin/quota-check.ts

@@ -256,198 +256,3 @@ export function formatQuotaBlock(q: QuotaUtilization, now: Date = new Date()): s
   return lines.join("\n");
 }
 
-/* ── Account-level quota probe + short-lived cache ───────────────────── */
-
-/**
- * Resolve an account's OAuth access token from
- * `~/.switchroom/accounts/<label>/credentials.json` (new account model
- * — see `reference/share-auth-across-the-fleet.md`). Returns null when
- * the file is missing, malformed, or has no accessToken — caller
- * surfaces a graceful "missing credentials" badge.
- *
- * Exported for unit testing; production callers go through
- * {@link fetchAccountQuota}.
- */
-export function readAccountAccessToken(
-  label: string,
-  home: string = (process.env.HOME ?? "/root"),
-): string | null {
-  const credPath = join(home, ".switchroom", "accounts", label, "credentials.json");
-  if (!existsSync(credPath)) return null;
-  try {
-    const raw = readFileSync(credPath, "utf-8");
-    const parsed = JSON.parse(raw) as {
-      claudeAiOauth?: { accessToken?: string };
-    };
-    const token = parsed.claudeAiOauth?.accessToken?.trim();
-    return token && token.length > 0 ? token : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Cache key per account label. The cached entry holds the result and
- * the wall-clock timestamp it was fetched at, so the dashboard tap
- * pattern (refresh-on-tap) doesn't trigger a fresh API call within the
- * TTL window. Quota numbers don't move within a few seconds anyway.
- */
-type AccountQuotaCacheEntry = {
-  fetchedAt: number;
-  result: QuotaResult;
-};
-
-/** TTL for the per-account quota cache — controls when
- *  `prefetchAccountQuotaIfStale` re-probes Anthropic and when
- *  `fetchAccountQuota`'s cache-bypass kicks in. 5 min: quota numbers
- *  don't move within a few minutes for human-scale usage; the
- *  prefetch fires on every dashboard render so the cache stays fresh
- *  whenever the operator interacts. The dashboard's sync read
- *  (`getCachedAccountQuota`) returns last-known data regardless of
- *  staleness — see that function's docstring for why. */
-export const ACCOUNT_QUOTA_CACHE_TTL_MS = 5 * 60_000;
-
-const accountQuotaCache = new Map<string, AccountQuotaCacheEntry>();
-
-/**
- * Fetch quota for a global account by label. Wraps {@link fetchQuota}
- * with token-resolution (`~/.switchroom/accounts/<label>/credentials.json`)
- * and a short-lived in-process cache so repeat dashboard taps within
- * the TTL don't re-hit the Anthropic API.
- *
- * Pass `force: true` to bypass the cache (used when the user
- * explicitly taps "📊 Full quota" — they expect a live read).
- */
-export async function fetchAccountQuota(
-  label: string,
-  opts: {
-    home?: string;
-    force?: boolean;
-    now?: () => number;
-    fetchImpl?: typeof fetch;
-    timeoutMs?: number;
-  } = {},
-): Promise<QuotaResult> {
-  const now = opts.now?.() ?? Date.now();
-  if (!opts.force) {
-    const cached = accountQuotaCache.get(label);
-    if (cached && now - cached.fetchedAt < ACCOUNT_QUOTA_CACHE_TTL_MS) {
-      return cached.result;
-    }
-  }
-
-  const token = readAccountAccessToken(label, opts.home);
-  if (!token) {
-    const result: QuotaResult = {
-      ok: false,
-      reason: "no credentials.json or accessToken for account",
-    };
-    accountQuotaCache.set(label, { fetchedAt: now, result });
-    return result;
-  }
-
-  const result = await fetchQuota({
-    accessToken: token,
-    fetchImpl: opts.fetchImpl,
-    timeoutMs: opts.timeoutMs,
-  });
-  accountQuotaCache.set(label, { fetchedAt: now, result });
-  // Note: pre-RFC-H this also persisted to disk via writeAccountQuota
-  // (#708) so a gateway restart could re-hydrate without an API call.
-  // Post-RFC-H the broker holds canonical quota state and answers
-  // via `list-state`, so the gateway's in-process cache is enough.
-  return result;
-}
-
-/**
- * Re-hydrate the in-process account-quota cache from on-disk
- * snapshots written by previous gateway lifetimes (issue #708).
- * Called once at gateway boot so the boot card and the first /auth
- * tap have data instantly — no need to wait for the background
- * prefetch tick.
- *
- * Safe to call repeatedly: each label is set to the disk snapshot's
- * `capturedAt` timestamp so a fresher live probe still wins on
- * `now - fetchedAt < TTL` comparisons. When the disk snapshot is
- * older than the TTL, the cache entry is still seeded — the background
- * prefetch will replace it on the next tap.
- */
-export function hydrateAccountQuotaCacheFromDisk(
-  _labels: ReadonlyArray<string>,
-  _home?: string,
-): void {
-  // No-op post-RFC-H. The disk-snapshot store this function used to
-  // re-hydrate from (per-account quota.json files under
-  // ~/.switchroom/accounts/<label>/) is gone — switchroom-auth-broker
-  // now owns canonical quota state. Boot-time hydration is the
-  // broker's `list-state` call instead. Signature preserved so
-  // existing call sites continue to compile while we phase them out.
-}
-
-/** Test/utility helper — wipe the per-account quota cache. The
- *  gateway calls this on auth-account-level mutations (account add,
- *  account rm, account rename, refresh-accounts tick) so a stale
- *  pre-rename label doesn't survive into the dashboard. */
-export function clearAccountQuotaCache(label?: string): void {
-  if (label == null) {
-    accountQuotaCache.clear();
-    return;
-  }
-  accountQuotaCache.delete(label);
-}
-
-/**
- * Sync read of the account quota cache. Returns whatever's cached for
- * this label — `null` only when there's NO entry at all. Stale-but-
- * present cache entries are returned on purpose:
- *
- *   - The dashboard renders sync; awaiting a fresh probe would block
- *     the user-visible message (and a probe can stall on Anthropic
- *     latency or network).
- *   - Showing yesterday's number is dramatically better UX than
- *     showing nothing — quota changes slowly enough that "the cached
- *     value" is almost always close to truth.
- *   - The background prefetch (`prefetchAccountQuotaIfStale`) keeps
- *     the cache fresh across renders. Within the 5-min TTL it
- *     no-ops; past the TTL it kicks off a fresh probe whose result
- *     is visible on the operator's NEXT render (refresh tap or
- *     auto-refresh after an action).
- *
- * Pre-v0.6.11 this function treated stale entries as a miss, which
- * meant the boot-warmed cache vanished after 30s and the operator
- * saw empty quota rows on the first /auth tap of any day after the
- * gateway restart. That's the bug this docstring exists to keep
- * fixed.
- */
-export function getCachedAccountQuota(
-  _label: string,
-  _now: number = Date.now(),
-): QuotaResult | null {
-  // Note the unused params — we keep the signature stable for callers
-  // that pass `now` (test helpers) even though we no longer use it.
-  const cached = accountQuotaCache.get(_label);
-  if (!cached) return null;
-  return cached.result;
-}
-
-/**
- * Fire-and-forget background prefetch — kicks off
- * `fetchAccountQuota` if the cache is cold/stale and discards the
- * promise. Safe to call on every dashboard render: the cache TTL
- * keeps the API call rate bounded to ~1 per account per 30s
- * regardless of how many times the user taps /auth.
- *
- * Errors are swallowed (the next tap re-tries via the cache miss
- * path); the dashboard's empty quota row is the user-visible
- * "didn't probe yet" signal.
- */
-export function prefetchAccountQuotaIfStale(
-  label: string,
-  opts: { home?: string; now?: () => number; fetchImpl?: typeof fetch } = {},
-): void {
-  const now = opts.now?.() ?? Date.now();
-  const cached = accountQuotaCache.get(label);
-  if (cached && now - cached.fetchedAt < ACCOUNT_QUOTA_CACHE_TTL_MS) return;
-  // Don't await — background warm.
-  void fetchAccountQuota(label, opts).catch(() => {});
-}

package/telegram-plugin/retry-api-call.ts

@@ -250,3 +250,27 @@ export async function retryWithThreadFallback<T>(
     throw err
   }
 }
+
+/**
+ * True when Telegram rejected a message because it couldn't parse the
+ * HTML/entities we sent — our prevention (markdownToHtml +
+ * sanitizeForTelegram + splitHtmlChunks) let something malformed
+ * through anyway. These 400s are deliberately NOT swallowed or retried
+ * by `retryApiCall` (only not-modified / not-found / thread-not-found
+ * are) — they surface to the caller, which recovers by resending the
+ * chunk as plain text (parse_mode unset). Same "caller-level fallback"
+ * shape as the THREAD_NOT_FOUND contract above.
+ */
+export function isHtmlParseRejectError(err: unknown): boolean {
+  if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  const d = (err.description || '').toLowerCase()
+  return (
+    d.includes("can't parse entities") ||
+    d.includes('can’t parse entities') ||
+    d.includes('unsupported start tag') ||
+    d.includes('unclosed start tag') ||
+    d.includes("can't find end of the entity") ||
+    // covers both "expected end tag" and "unexpected end tag"
+    d.includes('expected end tag')
+  )
+}

package/telegram-plugin/server.ts

@@ -159,13 +159,16 @@ installPluginLogger()
   //     missing-feature bugs (no /issues card, no quota notifications, no
   //     graceful failover). A clean error is more honest.
   //
-  // To install the gateway: `switchroom setup` provisions the
-  // `switchroom-telegram-gateway` systemd unit. Inspect with
-  // `systemctl --user status switchroom-telegram-gateway`.
+  // In v0.7+ the gateway is an in-container sidecar started by start.sh
+  // (no systemd unit). On a Docker host inspect/recover with
+  // `docker logs switchroom-<agent>` / `switchroom agent restart <agent>`;
+  // on a legacy non-docker install it's the gateway systemd user unit.
+  const recover = process.env.SWITCHROOM_RUNTIME === 'docker'
+    ? 'check `docker logs switchroom-<agent>` then `switchroom agent restart <agent>`'
+    : 'run `switchroom setup` to install the gateway, or check `systemctl --user status switchroom-telegram-gateway`'
   process.stderr.write(
     `telegram channel: no gateway socket at ${_gatewaySocket}. ` +
-    `Run \`switchroom setup\` to install the gateway daemon, or check ` +
-    `\`systemctl --user status switchroom-telegram-gateway\`. Exiting sidecar.\n`,
+    `The gateway sidecar is not running — ${recover}. Exiting sidecar.\n`,
   )
   process.exit(1)
 }

package/telegram-plugin/tests/auth-add-flow.test.ts

@@ -26,10 +26,39 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
+/**
+ * Pick an exec-allowed temp root. Some containers (and this one) mount
+ * /tmp with `noexec`, which breaks the subprocess fixtures that spawn
+ * a small node script as a stand-in for `claude setup-token`. When the
+ * default tmpdir is noexec, fall back to a project-local `.test-tmp/`
+ * which inherits the project mount's exec bits.
+ */
+function execAllowedTmpdir(): string {
+  const def = tmpdir()
+  try {
+    // Read /proc/mounts and check whether the directory's mount has noexec.
+    const mounts = readFileSync('/proc/mounts', 'utf8')
+    const noexec = mounts.split('\n').some((line) => {
+      const parts = line.split(' ')
+      if (parts.length < 4) return false
+      const [, mountPoint, , opts] = parts
+      return mountPoint === def && opts.split(',').includes('noexec')
+    })
+    if (!noexec) return def
+  } catch {
+    return def
+  }
+  const fallback = join(process.cwd(), '.test-tmp')
+  mkdirSync(fallback, { recursive: true })
+  return fallback
+}
+
+const EXEC_TMPDIR = execAllowedTmpdir()
+
 import {
   parseAuthCommand,
   handleAuthCommand,
@@ -51,7 +80,7 @@ import {
 let workspace: string
 
 beforeEach(() => {
-  workspace = mkdtempSync(join(tmpdir(), 'auth-add-flow-test-'))
+  workspace = mkdtempSync(join(EXEC_TMPDIR, 'auth-add-flow-test-'))
   pendingAuthAddFlows.clear()
 })
 

package/telegram-plugin/tests/boot-probes.test.ts

@@ -292,6 +292,59 @@ describe('probeQuota — #1163: /v1/messages headers path', () => {
     expect(result.detail).toContain('18% / 7d')
   })
 
+  it('prefers the broker probe and does NOT do a direct fetch when it succeeds (Option A / #1336)', async () => {
+    const directFetch: typeof fetch = async () => {
+      throw new Error('direct fetch must not run when the broker probe returns a result')
+    }
+    const brokerProbe = async () => ({
+      ok: true as const,
+      data: {
+        fiveHourUtilizationPct: 30,
+        sevenDayUtilizationPct: 12,
+        fiveHourResetAt: null,
+        sevenDayResetAt: null,
+        representativeClaim: null,
+        overageStatus: null,
+        overageDisabledReason: null,
+      },
+    })
+    const result = await probeQuota(claudeDir, agentDir, directFetch, { brokerProbe })
+    expect(result.status).toBe('ok')
+    expect(result.detail).toContain('30% / 5h')
+    expect(result.detail).toContain('12% / 7d')
+  })
+
+  it('falls back to a direct probe when the broker probe returns null (broker unreachable)', async () => {
+    const headers = new Headers({
+      'anthropic-ratelimit-unified-5h-utilization': '0.55',
+      'anthropic-ratelimit-unified-7d-utilization': '0.22',
+    })
+    const directFetch: typeof fetch = async () =>
+      new Response('{}', { status: 200, headers }) as Response
+    const brokerProbe = async () => null
+
+    const result = await probeQuota(claudeDir, agentDir, directFetch, { brokerProbe })
+    expect(result.status).toBe('ok')
+    expect(result.detail).toContain('55% / 5h')
+    expect(result.detail).toContain('22% / 7d')
+  })
+
+  it('falls back to a direct probe when the broker probe throws', async () => {
+    const headers = new Headers({
+      'anthropic-ratelimit-unified-5h-utilization': '0.10',
+      'anthropic-ratelimit-unified-7d-utilization': '0.05',
+    })
+    const directFetch: typeof fetch = async () =>
+      new Response('{}', { status: 200, headers }) as Response
+    const brokerProbe = async () => {
+      throw new Error('broker UDS connect failed')
+    }
+
+    const result = await probeQuota(claudeDir, agentDir, directFetch, { brokerProbe })
+    expect(result.status).toBe('ok')
+    expect(result.detail).toContain('10% / 5h')
+  })
+
   it('surfaces auth rejection with the RFC-H replace-account hint on 403', async () => {
     const fakeFetch: typeof fetch = async () =>
       new Response(null, { status: 403 }) as Response

package/telegram-plugin/tests/bot-runtime.test.ts

@@ -7,7 +7,7 @@
  * via integration tests; here we keep it to pure unit coverage.
  */
 
-import { describe, it, expect, vi } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import {
   escapeHtmlForTg,
   preBlock,
@@ -20,6 +20,28 @@ import {
 } from '../shared/bot-runtime.js'
 import type { Context } from 'grammy'
 
+// ─── env hygiene ─────────────────────────────────────────────────────────
+// The exec factories read SWITCHROOM_CONFIG and prepend `--config <path>` to
+// argv. When the test runner inherits SWITCHROOM_CONFIG from the environment
+// (e.g. switchroom-managed shells), this leaks into tests that use `echo`
+// as the cliPath and breaks stdout assertions. Clear before each test and
+// restore after.
+
+let savedSwitchroomConfig: string | undefined
+
+beforeEach(() => {
+  savedSwitchroomConfig = process.env.SWITCHROOM_CONFIG
+  delete process.env.SWITCHROOM_CONFIG
+})
+
+afterEach(() => {
+  if (savedSwitchroomConfig !== undefined) {
+    process.env.SWITCHROOM_CONFIG = savedSwitchroomConfig
+  } else {
+    delete process.env.SWITCHROOM_CONFIG
+  }
+})
+
 // ─── escapeHtmlForTg ─────────────────────────────────────────────────────
 
 describe('escapeHtmlForTg', () => {