switchroom 0.8.1 → 0.10.0

package/telegram-plugin/gateway/hostd-dispatch.ts

@@ -0,0 +1,117 @@
+/**
+ * Hostd dispatch helpers for the gateway's self-restart slash-commands
+ * (#1175 RFC C, Phase 2). When the operator has opted into
+ * `host_control.enabled: true`, /restart, /new, /reset, and
+ * /update apply route through the per-agent hostd UDS instead of the
+ * in-container `spawnSwitchroomDetached` shellout.
+ *
+ * Rationale: in docker-mode (the v0.7+ default) the agent container
+ * has no docker binary and no `/var/run/docker.sock` — so the
+ * spawn-path verbs fail with exit-127 the moment they touch compose.
+ * Hostd runs on the host with the docker socket mounted, so the verbs
+ * actually work.
+ *
+ * Extracted from gateway.ts for unit-testability — gateway.ts itself
+ * has too many boot-time side-effects to import directly in a test.
+ */
+import { existsSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { hostdRequest } from "../../src/host-control/client.js";
+import type {
+  HostdRequest,
+  HostdResponse,
+} from "../../src/host-control/protocol.js";
+import { loadConfig as loadSwitchroomConfig } from "../../src/config/loader.js";
+
+let _hostdEnabled: boolean | undefined;
+
+/**
+ * Reads `host_control.enabled` from the resolved switchroom config.
+ * Cached for the gateway's lifetime — config doesn't change without a
+ * restart, and the file-read isn't free.
+ *
+ * Best-effort: if the config can't be loaded (gateway running in a
+ * dir where loadConfig fails), returns false so the dispatch helper
+ * falls through to the legacy spawn path.
+ */
+export function isHostdEnabled(): boolean {
+  if (_hostdEnabled !== undefined) return _hostdEnabled;
+  try {
+    const cfg = loadSwitchroomConfig();
+    _hostdEnabled = cfg.host_control?.enabled === true;
+  } catch {
+    _hostdEnabled = false;
+  }
+  return _hostdEnabled;
+}
+
+/** @internal Reset the cache so tests can swap config and re-probe. */
+export function _resetHostdEnabledCache(): void {
+  _hostdEnabled = undefined;
+}
+
+export function hostdSocketPath(agentName: string): string {
+  return `/run/switchroom/hostd/${agentName}/sock`;
+}
+
+/**
+ * True only when (a) host_control is enabled in config AND (b) the
+ * per-agent socket is bound on disk. Distinct from "will the wire call
+ * succeed" — that's only knowable after attempting it.
+ *
+ * Callers use this to decide *whether to skip docker-availability
+ * preflight guards* (since hostd doesn't need in-container docker).
+ */
+export function hostdWillBeUsed(agentName: string): boolean {
+  if (!isHostdEnabled()) return false;
+  return existsSync(hostdSocketPath(agentName));
+}
+
+/**
+ * Send one request to the per-agent hostd socket.
+ *
+ * Returns:
+ *   - `"not-configured"` — hostd is disabled in config OR the per-agent
+ *     socket isn't bound. Callers should fall back to the legacy
+ *     `spawnSwitchroomDetached` path.
+ *   - `HostdResponse` — hostd was contacted. Callers branch on
+ *     `resp.result`. Wire errors (ECONNREFUSED, timeout, bad frame)
+ *     are synthesized into a `result: "error"` response so callers
+ *     don't need a separate try/catch around the failure.
+ *
+ * Deliberately no silent fallback to spawn when hostd is configured-on
+ * but returns error/denied: the operator opted in, so masking failures
+ * would just confuse them about why the verb didn't actually run.
+ */
+export async function tryHostdDispatch(
+  agentName: string,
+  req: HostdRequest,
+): Promise<HostdResponse | "not-configured"> {
+  if (!isHostdEnabled()) return "not-configured";
+  const sockPath = hostdSocketPath(agentName);
+  if (!existsSync(sockPath)) return "not-configured";
+  try {
+    return await hostdRequest(
+      { socketPath: sockPath, timeoutMs: 5000 },
+      req,
+    );
+  } catch (err) {
+    process.stderr.write(
+      `telegram gateway: hostd dispatch failed ` +
+        `(request_id=${req.request_id} op=${req.op}): ` +
+        `${(err as Error).message}\n`,
+    );
+    return {
+      v: 1,
+      request_id: req.request_id,
+      result: "error",
+      exit_code: null,
+      duration_ms: 0,
+      error: `hostd wire error: ${(err as Error).message}`,
+    };
+  }
+}
+
+export function hostdRequestId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${randomBytes(4).toString("hex")}`;
+}

package/telegram-plugin/hooks/tool-label-pretool.mjs

@@ -111,6 +111,17 @@ export function computeLabel(toolName, input) {
     case 'KillBash':
     case 'KillShell':
       return 'Stopping background process'
+    case 'Skill': {
+      // The Skill tool's input is `{ skill: "<slug>", args?: "..." }`.
+      // We emit `Running skill <slug>` so downstream observers
+      // (notably the skill-coverage UAT runner at
+      // telegram-plugin/uat/runners/skill-coverage.ts) can tail the
+      // sidecar JSONL and recover which skill fired per turn —
+      // the progress card path that used to surface this was retired
+      // when `progressDriver` was nulled out in #1122 PR3.
+      const slug = clip(String(i.skill ?? ''), 64)
+      return slug ? `Running skill ${slug}` : null
+    }
   }
 
   // MCP allowlist.

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/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