switchroom 0.8.1 → 0.11.0

package/telegram-plugin/hooks/wedge-detect-posttool.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse hook — detect a wedged persistent-bash session.
+ *
+ * Claude Code's Bash tool uses a persistent `bash` subprocess for state
+ * continuity (so `cd /foo` in one call survives to the next). When that
+ * subprocess's IO state desyncs — typically after a long-running or
+ * interrupted command leaves stdin in mid-heredoc, or after sentinel
+ * parsing breaks — every subsequent Bash call returns exit-1 with empty
+ * stdout and empty stderr. Even `true` returns exit 1. The wedge is
+ * sticky for the session; `switchroom agent restart <self>` is the only
+ * reliable recovery (it spawns a fresh `claude` → fresh persistent bash).
+ *
+ * This hook watches PostToolUse events for the wedge signature and,
+ * after N consecutive matches, writes a sentinel + logs to stderr so
+ * the operator (via `docker logs`) or the gateway (via a future card)
+ * can prompt for restart. The hook itself can NEVER fix the wedge —
+ * PostToolUse fires after the tool already ran. It's a detection +
+ * surfacing surface, not a recovery surface.
+ *
+ * Claude Code PostToolUse protocol:
+ *   stdin:  JSON { tool_name, tool_use_id, tool_input, tool_response, ... }
+ *   stdout: optional JSON (hookSpecificOutput.additionalContext for next
+ *           turn). We use this to nudge the model toward KillBash +
+ *           self-restart guidance once the wedge is detected.
+ *   exit:   0 always. Hook failures must never block the tool flow.
+ *
+ * State:
+ *   $TELEGRAM_STATE_DIR/wedge-counter.txt — integer, consecutive empty Bash
+ *     results. Reset to 0 on any non-Bash event or any non-empty Bash
+ *     result. Incremented on each empty Bash result.
+ *   $TELEGRAM_STATE_DIR/wedge-detected.json — JSON sentinel written when
+ *     counter reaches THRESHOLD. Contains { ts, session_id, agent,
+ *     consecutive }. Gateway can poll for this and surface a card; for
+ *     now its presence is informational only.
+ *
+ * Threshold: 3. Picked to balance false positives (some real commands
+ * legitimately produce no output and exit non-zero, e.g. `test -f
+ * /nonexistent`) against latency-to-detect. Three in a row is rare
+ * outside genuine wedge.
+ *
+ * Detection is shape-based not exit-code-based because the tool_response
+ * shape varies by Claude Code version. We match on:
+ *   - tool_name === "Bash"
+ *   - stringified response contains BOTH empty stdout marker AND empty
+ *     stderr marker. Marker patterns covered: <bash-stdout></bash-stdout>,
+ *     "stdout":"" + "stderr":"", and the bare "(no output)" string some
+ *     versions emit.
+ *
+ * If detection markers change in a future Claude Code release, this hook
+ * silently misses the wedge — that's the right failure mode (better than
+ * false-firing).
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+// Higher than the original 3 to avoid false-firing on legitimate
+// empty-output command sequences (a sed, then two greps with no matches,
+// is a normal refactor pattern and shouldn't trigger). PR #1188 review
+// found 3 was guaranteed-FP. 5 + the noOutputExpected /
+// returnCodeInterpretation skip below should keep real wedges detectable
+// while staying quiet during normal grep/find/sed chains.
+const THRESHOLD = 5
+
+// node:fs operations on the counter / sentinel files are read-modify-write
+// without explicit locking. Safe because Claude Code serializes tool calls
+// per session — there is at most one PostToolUse fire in flight per agent
+// at any time. Documented so a future caller doesn't introduce parallelism
+// and silently lose counts.
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+function stateDir() {
+  return process.env.TELEGRAM_STATE_DIR || null
+}
+
+function counterPath() {
+  const dir = stateDir()
+  return dir ? join(dir, 'wedge-counter.txt') : null
+}
+
+function sentinelPath() {
+  const dir = stateDir()
+  return dir ? join(dir, 'wedge-detected.json') : null
+}
+
+function readCounter() {
+  const p = counterPath()
+  if (!p || !existsSync(p)) return 0
+  try {
+    const raw = readFileSync(p, 'utf8').trim()
+    const n = Number.parseInt(raw, 10)
+    return Number.isFinite(n) && n >= 0 ? n : 0
+  } catch {
+    return 0
+  }
+}
+
+function writeCounter(n) {
+  const p = counterPath()
+  if (!p) return
+  try {
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, String(n), 'utf8')
+  } catch {
+    // fail-silent; counter loss just delays detection by a couple of cycles
+  }
+}
+
+function writeSentinel(payload) {
+  const p = sentinelPath()
+  if (!p) return
+  try {
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, JSON.stringify(payload, null, 2), 'utf8')
+  } catch {
+    // fail-silent
+  }
+}
+
+function clearSentinel() {
+  const p = sentinelPath()
+  if (!p) return
+  try {
+    rmSync(p, { force: true })
+  } catch {
+    // fail-silent
+  }
+}
+
+function resetCounter() {
+  // Counter reset means we're back in healthy territory — clear the
+  // sentinel too so a future operator-side surface that polls for
+  // `wedge-detected.json` doesn't see stale state from a long-cleared
+  // wedge. Per PR #1188 review B2.
+  writeCounter(0)
+  clearSentinel()
+}
+
+/**
+ * Test whether a Bash tool_response matches the wedge signature.
+ *
+ * The wedge produces: empty stdout AND empty stderr AND no
+ * Claude-Code-supplied "no output is expected here" annotation AND not
+ * interrupted by the user.
+ *
+ * The benign empty-output cases that PR #1188 review B1 called out
+ * (grep/find/sed/test with no matches or in-place mutation) are
+ * disambiguated by:
+ *   - `noOutputExpected: true` — Claude Code annotates Bash calls whose
+ *     command pattern legitimately produces no output.
+ *   - `returnCodeInterpretation: "..."` — present when Claude Code has
+ *     a human-readable explanation for the exit code (e.g. "No matches
+ *     found" for grep). Its presence means "this empty result is
+ *     understood, not a desync."
+ *   - `interrupted: true` — user pressed `!` mid-command. Not a wedge.
+ *
+ * Defensive: response shape varies across Claude Code versions and
+ * across plain-string vs structured-object representations. We check
+ * each known marker and fail-no-match on anything else.
+ */
+function isEmptyBashResponse(toolResponse) {
+  if (toolResponse == null) return false
+
+  // Structured-object path. Most reliable — read the fields directly
+  // and consult the annotations.
+  if (typeof toolResponse === 'object') {
+    const r = toolResponse
+    // Interruption is user-initiated, not a desync. Don't count.
+    if (r.interrupted === true) return false
+    // Claude Code already knows this command's empty output is expected.
+    if (r.noOutputExpected === true) return false
+    // Claude Code has a human-readable explanation — the empty result is
+    // accounted for, not a parse failure.
+    if (typeof r.returnCodeInterpretation === 'string' && r.returnCodeInterpretation.length > 0) {
+      return false
+    }
+    // Real empty-result check. Both streams empty (or missing).
+    const stdout = typeof r.stdout === 'string' ? r.stdout : ''
+    const stderr = typeof r.stderr === 'string' ? r.stderr : ''
+    if (stdout === '' && stderr === '') return true
+    return false
+  }
+
+  // String path — older Claude Code versions, or when the response was
+  // wrapped before reaching the hook. We can't read structured fields,
+  // so we rely on substring shape and accept slightly higher FP risk on
+  // this path (covered by THRESHOLD raise + skill-side recovery being
+  // cheap).
+  let body
+  try {
+    body = String(toolResponse)
+  } catch {
+    return false
+  }
+  if (body.length > 4096) return false
+
+  // If the string form contains noOutputExpected:true or a
+  // returnCodeInterpretation, treat as accounted-for.
+  if (/"noOutputExpected"\s*:\s*true/.test(body)) return false
+  if (/"interrupted"\s*:\s*true/.test(body)) return false
+  if (/"returnCodeInterpretation"\s*:\s*"[^"]+"/.test(body)) return false
+
+  // XML-style tags: <bash-stdout></bash-stdout><bash-stderr></bash-stderr>
+  const hasEmptyStdoutTag = /<bash-stdout>\s*<\/bash-stdout>/i.test(body)
+  const hasEmptyStderrTag = /<bash-stderr>\s*<\/bash-stderr>/i.test(body)
+  if (hasEmptyStdoutTag && hasEmptyStderrTag) return true
+
+  // JSON-stringified shape from older serializers.
+  const hasEmptyStdoutJson = /"stdout"\s*:\s*""/.test(body)
+  const hasEmptyStderrJson = /"stderr"\s*:\s*""/.test(body)
+  if (hasEmptyStdoutJson && hasEmptyStderrJson) return true
+
+  // Literal zero-info bodies.
+  if (body === '{}' || body === '""' || body === '') return true
+
+  return false
+}
+
+function emitWedgeContext(consecutive) {
+  // PostToolUse can prepend additionalContext to the model's next turn.
+  // Use it to surface a single-line nudge once the wedge is suspected
+  // so the agent knows to try recovery rather than retrying the same
+  // command in a loop.
+  const text =
+    `[wedge-detect] ${consecutive} consecutive empty-result Bash calls — ` +
+    `your persistent shell is likely wedged. Try \`KillBash\` to drop ` +
+    `the wedged session, OR ask the user for \`switchroom agent restart ${process.env.SWITCHROOM_AGENT_NAME || '<self>'}\` ` +
+    `if KillBash doesn't recover. Don't retry the same command.`
+  const payload = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: text,
+    },
+  }
+  try {
+    process.stdout.write(JSON.stringify(payload) + '\n')
+  } catch {
+    // fail-silent
+  }
+}
+
+function main() {
+  const raw = readStdin()
+  if (!raw) return
+  let evt
+  try {
+    evt = JSON.parse(raw)
+  } catch {
+    return
+  }
+
+  // Non-Bash events reset the counter (the wedge is specific to the
+  // persistent shell; other tools succeeding doesn't tell us anything
+  // about Bash, but a different tool firing means we're at least not in
+  // a tight loop of Bash retries — safe to reset).
+  if (evt.tool_name !== 'Bash') {
+    resetCounter()
+    return
+  }
+
+  if (!isEmptyBashResponse(evt.tool_response)) {
+    // Bash call returned real output → not wedged → reset.
+    resetCounter()
+    return
+  }
+
+  // Empty Bash result. Increment.
+  const next = readCounter() + 1
+  writeCounter(next)
+
+  if (next >= THRESHOLD) {
+    const sentinel = {
+      ts: new Date().toISOString(),
+      session_id: evt.session_id || null,
+      agent: process.env.SWITCHROOM_AGENT_NAME || null,
+      consecutive: next,
+      // Capture the last tool_use_id so an operator-side investigator
+      // can pin which tool calls triggered the threshold.
+      last_tool_use_id: evt.tool_use_id || null,
+    }
+    writeSentinel(sentinel)
+    process.stderr.write(
+      `wedge-detect: ${next} consecutive empty-result Bash calls; ` +
+      `sentinel at ${sentinelPath()}; recommend KillBash or ` +
+      `switchroom agent restart\n`,
+    )
+    emitWedgeContext(next)
+  }
+}
+
+try {
+  main()
+} catch {
+  // PostToolUse must never block the tool flow.
+}

package/telegram-plugin/model-unavailable.ts

@@ -216,20 +216,21 @@ export interface FormatCardOptions {
   slot?: string | null
   /** Anchor for relative-time formatting. Tests pin this; prod omits it. */
   now?: Date
+  /**
+   * True when the gateway has concurrently fired
+   * `fireFleetAutoFallback` for this event. Switches the card body
+   * from "What to try" (manual commands) to "Auto-failover in
+   * progress" so the user doesn't manually `/auth use` while a
+   * fleet swap is mid-flight. Caller MUST pass this when invoking
+   * the dispatcher in parallel — otherwise the card lies.
+   */
+  autoFallbackInFlight?: boolean
 }
 
 /**
  * Render the actionable ⚠️ card for a detected model-unavailable event.
  * HTML-formatted for Telegram. Stable shape so snapshot tests remain
  * meaningful when the suggestion list shifts.
- *
- *   ⚠️ <b>Model unavailable</b> on agent <b>name</b>
- *   Reason: quota exhausted (resets in 5h)
- *
- *   <b>What to try</b>
- *   • <code>/authfallback</code> — switch to the next account slot
- *   • <code>/auth add</code> — attach another subscription
- *   • <code>/usage</code> — show quota breakdown
  */
 export function formatModelUnavailableCard(
   detection: ModelUnavailableDetection,
@@ -243,11 +244,26 @@ export function formatModelUnavailableCard(
     `⚠️ <b>Model unavailable</b> on agent <b>${escHtml(agent)}</b>${slotPart}`,
     `Reason: ${reason}`,
     '',
-    '<b>What to try</b>',
-    '• <code>/authfallback</code> — switch to the next account slot',
-    '• <code>/auth add</code> — attach another subscription',
-    '• <code>/usage</code> — show quota breakdown',
   ]
+  if (opts.autoFallbackInFlight) {
+    // Quiet variant — the gateway already kicked off a fleet-wide
+    // swap; a follow-up announcement (causal-shape) will land within
+    // ~1s. Mention it explicitly so the user knows not to react.
+    lines.push(
+      '<i>Auto-failover in progress — see the announcement below.</i>',
+    )
+  } else {
+    // Default — kinds where auto-fallback can't help (network)
+    // or pre-Format-2 callers. Also: `/authfallback` is no longer
+    // a verb (post-RFC-H); `/auth use <label>` is the canonical
+    // fleet-wide swap.
+    lines.push(
+      '<b>What to try</b>',
+      '• <code>/auth use &lt;label&gt;</code> — switch the fleet to a healthy account',
+      '• <code>/auth add</code> — attach another subscription',
+      '• <code>/usage</code> — show quota breakdown',
+    )
+  }
   return lines.join('\n')
 }
 

package/telegram-plugin/permission-title.ts

@@ -17,6 +17,45 @@ import { basename } from "node:path";
 const COMMAND_TITLE_MAX = 40;
 const PATH_TITLE_MAX = 40;
 
+/**
+ * Human-friendly descriptions for switchroom-managed MCP tools. The
+ * raw `mcp__<server>__<tool>` name is operator-unfriendly — they shouldn't
+ * have to decode the namespace to understand what the agent is asking
+ * to do. Use this map to turn the code-level identifier into a verb
+ * phrase ("Read its own merged config" instead of
+ * "mcp__agent-config__config_get") for the approval card.
+ *
+ * Note: post-#1215 these tools are pre-allowed in scaffolded
+ * settings.permissions.allow, so the card should fire rarely.
+ * This map is for the fallback path — agents the operator
+ * narrowed the allowlist on, or tools added in future PRs that
+ * haven't shipped the allowlist bump yet.
+ */
+const MCP_TOOL_DESCRIPTIONS: Record<string, string> = {
+  // agent-config — every agent's self-service surface (#1163, #1215)
+  "mcp__agent-config__config_get": "Read its own merged config",
+  "mcp__agent-config__cron_list": "List its own scheduled tasks",
+  "mcp__agent-config__skill_list": "List its own installed skills",
+  "mcp__agent-config__audit_tail": "Read its own recent tool-call audit log",
+  "mcp__agent-config__peers_list": "List the other agents on this instance",
+  "mcp__agent-config__schedule_add": "Add a scheduled task to its own cron",
+  "mcp__agent-config__schedule_remove": "Remove one of its own scheduled tasks",
+  "mcp__agent-config__skill_install": "Install a bundled skill onto itself",
+  "mcp__agent-config__skill_remove": "Remove one of its own installed skills",
+  // hostd — admin-flagged agents' fleet-management surface (#1175, #1215)
+  "mcp__hostd__agent_restart": "Restart an agent in the fleet",
+  "mcp__hostd__agent_start": "Start a stopped agent in the fleet",
+  "mcp__hostd__agent_stop": "Stop a running agent in the fleet",
+  "mcp__hostd__agent_logs": "Read another agent's container logs",
+  "mcp__hostd__agent_exec": "Run a read-only inspection inside another agent",
+  "mcp__hostd__update_check": "Check what a fleet-wide update would do",
+  "mcp__hostd__update_apply": "Apply a fleet-wide update (pull + recreate)",
+  // hindsight — memory
+  "mcp__hindsight__recall": "Recall relevant memories",
+  "mcp__hindsight__retain": "Retain a memory",
+  "mcp__hindsight__reflect": "Reflect across its memory bank",
+};
+
 /**
  * Build a title fragment for a permission prompt. Returns the toolName
  * for any tool we don't recognise — the helper is intentionally
@@ -27,6 +66,23 @@ export function summarizeToolForTitle(
   toolName: string,
   inputPreview: string | undefined,
 ): string {
+  // MCP tools: `mcp__<server>__<verb>`. Prefer a curated human
+  // description (so the card reads "Read its own merged config"
+  // instead of "mcp__agent-config__config_get"). Fall through to a
+  // generic `<server>: <verb-with-spaces>` shape for unknown MCP
+  // tools and finally to the raw name when even that fails.
+  if (toolName.startsWith("mcp__")) {
+    const curated = MCP_TOOL_DESCRIPTIONS[toolName];
+    if (curated) return curated;
+    const parts = toolName.split("__");
+    if (parts.length >= 3) {
+      const server = parts[1]!;
+      const verb = parts.slice(2).join("__").replace(/_/g, " ");
+      return `${server}: ${verb}`;
+    }
+    return toolName;
+  }
+
   const input = parseInput(inputPreview);
   if (!input) return toolName;
 

package/telegram-plugin/quota-check.ts

@@ -17,11 +17,13 @@
 
 import { readFileSync, existsSync } from "fs";
 import { join } from "path";
-import {
-  readAccountQuota,
-  snapshotFromQuotaUtilization,
-  writeAccountQuota,
-} from "../src/auth/account-quota-store.js";
+
+// RFC H: per-account quota state moved to switchroom-auth-broker
+// (state/auth-broker/quota.json). The gateway's in-process cache
+// below is still useful for sub-second formatting, but the disk-
+// persistence layer that account-quota-store provided is gone —
+// the broker owns the canonical store and exposes it via
+// `list-state`. Disk hydrate / disk persist below are no-ops.
 
 /**
  * OAuth beta flag — proves the request is coming from a subscription client.
@@ -350,20 +352,10 @@ export async function fetchAccountQuota(
     timeoutMs: opts.timeoutMs,
   });
   accountQuotaCache.set(label, { fetchedAt: now, result });
-  // Persist the snapshot to disk so a future gateway restart can
-  // re-hydrate its in-process cache without an API call. Best-effort
-  // (write errors swallowed inside writeAccountQuota). Issue #708.
-  if (result.ok) {
-    try {
-      writeAccountQuota(
-        label,
-        snapshotFromQuotaUtilization(result.data, new Date(now)),
-        opts.home,
-      );
-    } catch {
-      /* best-effort */
-    }
-  }
+  // 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;
 }
 
@@ -381,29 +373,15 @@ export async function fetchAccountQuota(
  * prefetch will replace it on the next tap.
  */
 export function hydrateAccountQuotaCacheFromDisk(
-  labels: ReadonlyArray<string>,
-  home?: string,
+  _labels: ReadonlyArray<string>,
+  _home?: string,
 ): void {
-  for (const label of labels) {
-    if (accountQuotaCache.has(label)) continue;
-    const snap = readAccountQuota(label, home);
-    if (!snap) continue;
-    const fetchedAt = Date.parse(snap.capturedAt);
-    if (!Number.isFinite(fetchedAt)) continue;
-    const result: QuotaResult = {
-      ok: true,
-      data: {
-        fiveHourUtilizationPct: snap.fiveHourPct ?? 0,
-        sevenDayUtilizationPct: snap.sevenDayPct ?? 0,
-        fiveHourResetAt: snap.fiveHourResetAt ? new Date(snap.fiveHourResetAt) : null,
-        sevenDayResetAt: snap.sevenDayResetAt ? new Date(snap.sevenDayResetAt) : null,
-        representativeClaim: null,
-        overageStatus: null,
-        overageDisabledReason: null,
-      },
-    };
-    accountQuotaCache.set(label, { fetchedAt, result });
-  }
+  // 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

package/telegram-plugin/scripts/build.mjs

@@ -24,7 +24,6 @@ const entries = [
   { src: "server.ts", out: "server.js", label: "server (legacy + dual-mode shim)" },
   { src: "gateway/gateway.ts", out: "gateway/gateway.js", label: "gateway (persistent service)" },
   { src: "bridge/bridge.ts", out: "bridge/bridge.js", label: "bridge (MCP proxy)" },
-  { src: "foreman/foreman.ts", out: "foreman/foreman.js", label: "foreman (admin bot)" },
 ];
 
 for (const { src, out, label } of entries) {

package/telegram-plugin/shared/bot-runtime.ts

@@ -1,7 +1,8 @@
 /**
- * Shared bot runtime helpers — extracted from gateway.ts so both the
- * per-agent gateway and the foreman bot can share the same core plumbing
- * without duplicating code.
+ * Shared bot runtime helpers — extracted from gateway.ts as a reusable
+ * core that callers can build on without duplicating the boilerplate.
+ * Used today by the per-agent gateway; historically also by the
+ * standalone foreman bot before its retirement.
  *
  * What lives here:
  *   - `createRobustApiCall` — thin re-export of createRetryApiCall pre-wired
@@ -361,7 +362,7 @@ export async function runPollingLoop(
 
 /**
  * Returns true if the sender's user ID is in the allowFrom list.
- * Used by both gateway and foreman for auth gating.
+ * Used by the gateway for sender-allowlist auth gating.
  */
 export function isAllowedSender(ctx: Context, allowFrom: string[]): boolean {
   const from = ctx.from