switchroom 0.7.15 → 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/gateway/ipc-protocol.ts

@@ -18,6 +18,24 @@ export interface PermissionEvent {
   type: "permission";
   requestId: string;
   behavior: "allow" | "deny";
+  /**
+   * Session-scoped always-allow rule. Only set when the operator taps
+   * "🔁 Always allow" — the gateway already persists the rule to
+   * switchroom.yaml + settings.json via `switchroom agent grant`, but
+   * those writes only kick in on the NEXT agent boot. This field carries
+   * the rule to the running bridge so it can short-circuit future
+   * `permission_request` notifications (from the parent claude AND any
+   * sub-agents dispatched via the Task tool, which share the same MCP
+   * server / bridge process) within the current session.
+   *
+   * Issue #1138: without this, a sub-agent dispatched after the operator
+   * tapped "Always allow" still hit the popup, because Claude Code reads
+   * `.claude/settings.json` once at boot.
+   *
+   * Format matches `resolveAlwaysAllowRule`'s output: bare tool name
+   * (`Edit`), `Skill(<name>)`, or `mcp__<server>__<tool>`.
+   */
+  rule?: string;
 }
 
 export interface StatusEvent {

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -0,0 +1,106 @@
+/**
+ * Per-agent buffer for synthetic inbounds the gateway couldn't deliver
+ * because no live IPC client was registered for the agent at send-time.
+ *
+ * Background: `ipcServer.sendToAgent(agent, msg)` returns `false` when
+ * the agent's bridge isn't connected. Before this buffer existed, the
+ * gateway logged the failure and dropped the message — root cause of
+ * issue #1150 (operator taps Approve on a vault_request_access card,
+ * grant lands, but the `vault_grant_approved` inbound that wakes the
+ * agent never arrives if the bridge happens to be reconnecting in
+ * that exact 100ms window).
+ *
+ * Contract:
+ *   - `push(agent, msg)` is best-effort and synchronous. Bounded:
+ *     a slow / dead bridge can't fill memory.
+ *   - `drain(agent)` returns ALL pending messages for `agent` in
+ *     insertion order and removes them from the buffer. Called from
+ *     `onClientRegistered` so a fresh bridge picks up the missed
+ *     wake-ups before doing anything else.
+ *   - In-memory only. Survives across IPC disconnect/reconnect within
+ *     a single gateway-process lifetime, but NOT a gateway restart.
+ *     A gateway crash mid-buffer means lost wake-ups; the silence-
+ *     poke ladder catches this downstream so the worst-case is a
+ *     5-minute delay, not a permanent stall.
+ *
+ * Per-agent cap prevents a never-reconnecting bridge from leaking
+ * unbounded memory. When the cap is hit, the OLDEST entry is dropped
+ * — the assumption is the freshest wake-up is the most relevant. A
+ * dropped entry is logged via the provided logger.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+/** Default cap per agent. Tuned for `should fit a reasonable backlog of
+ *  approval cards stacked while bridge is offline` but no more. */
+export const DEFAULT_PENDING_INBOUND_CAP = 32
+
+export interface PendingInboundBuffer {
+  /** Append `msg` to `agent`'s queue. Returns true if accepted, false if
+   *  the cap forced an eviction (the message is STILL accepted; `false`
+   *  signals "tail dropped to make room"). */
+  push: (agent: string, msg: InboundMessage) => boolean
+  /** Pop and return all pending messages for `agent`. Empty array when
+   *  none. Idempotent. */
+  drain: (agent: string) => InboundMessage[]
+  /** Test-only: current depth for `agent`. */
+  depth: (agent: string) => number
+  /** Test-only: total depth across all agents. */
+  totalDepth: () => number
+}
+
+export interface PendingInboundBufferOptions {
+  capPerAgent?: number
+  log?: (line: string) => void
+}
+
+export function createPendingInboundBuffer(
+  opts: PendingInboundBufferOptions = {},
+): PendingInboundBuffer {
+  const cap = opts.capPerAgent ?? DEFAULT_PENDING_INBOUND_CAP
+  const log = opts.log ?? ((line: string) => process.stderr.write(line))
+  const queues = new Map<string, InboundMessage[]>()
+
+  return {
+    push(agent, msg) {
+      let q = queues.get(agent)
+      if (q == null) {
+        q = []
+        queues.set(agent, q)
+      }
+      let evicted = false
+      if (q.length >= cap) {
+        const dropped = q.shift()
+        evicted = true
+        log(
+          `pending-inbound-buffer: agent=${agent} cap=${cap} reached — ` +
+          `dropped oldest entry source=${dropped?.meta?.source ?? '-'} ts=${dropped?.ts ?? '-'}\n`,
+        )
+      }
+      q.push(msg)
+      log(
+        `pending-inbound-buffer: agent=${agent} buffered source=${msg.meta?.source ?? '-'} ` +
+        `depth_after=${q.length} evicted=${evicted}\n`,
+      )
+      return !evicted
+    },
+    drain(agent) {
+      const q = queues.get(agent)
+      if (q == null || q.length === 0) return []
+      queues.delete(agent)
+      log(
+        `pending-inbound-buffer: drained agent=${agent} count=${q.length} ` +
+        `sources=[${q.map((m) => m.meta?.source ?? '-').join(',')}]\n`,
+      )
+      return q
+    },
+    depth(agent) {
+      return queues.get(agent)?.length ?? 0
+    },
+    totalDepth() {
+      let n = 0
+      for (const q of queues.values()) n += q.length
+      return n
+    },
+  }
+}

package/telegram-plugin/gateway/quarantine.ts

@@ -0,0 +1,69 @@
+/**
+ * Gateway-side writer for the agent quarantine marker (#1076).
+ *
+ * Mirrors the on-disk contract owned by `src/agents/quarantine.ts` —
+ * the host-side host CLI reads the marker, the gateway writes it. We
+ * keep a tiny copy here (writer only) because the gateway is bundled
+ * separately and can't import from `src/`.
+ *
+ * The schema MUST stay in sync with `src/agents/quarantine.ts`:
+ *
+ *   { v: 1, reason: "startup.unauthorized", ts: <ms>, detail?: <string> }
+ *
+ * Any change to the shape should land in both files in the same PR
+ * (or be guarded by `v`). See the src module's docstring for the full
+ * threat-model and operator remediation.
+ *
+ * SECURITY: never write the bot token (or any secret material) into
+ * the marker. The detail field is for the API description ("Unauthorized")
+ * and similar non-secret context.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const QUARANTINE_FILENAME = 'quarantine.json'
+
+export type QuarantineReason =
+  | 'startup.unauthorized'
+  // Config-class refusal-to-boot. Added 2026-05-13 after the
+  // vault-posture init started throwing as an unhandled rejection
+  // when the operator declared telegram-id posture but the auto-
+  // unlock blob couldn't be read. Pre-fix that path produced a tight
+  // restart loop ($n/60s -> hit supervisor cap -> stop) and posted
+  // an "agent-crashed" event per restart. The right outcome is a
+  // single EX_CONFIG exit at the first failure → supervisor
+  // quarantines → operator sees one clean error.
+  | 'startup.config_error'
+
+export interface QuarantineMarker {
+  v: 1
+  reason: QuarantineReason
+  ts: number
+  detail?: string
+}
+
+/**
+ * Write the quarantine marker into a Telegram state dir (typically
+ * `process.env.TELEGRAM_STATE_DIR`). Idempotent — overwrites any
+ * existing marker. Creates the parent dir if missing.
+ */
+export function writeQuarantineMarker(
+  telegramStateDir: string,
+  reason: QuarantineReason,
+  detail?: string,
+  nowFn: () => number = Date.now,
+): void {
+  mkdirSync(telegramStateDir, { recursive: true, mode: 0o700 })
+  const marker: QuarantineMarker = {
+    v: 1,
+    reason,
+    ts: nowFn(),
+    detail,
+  }
+  writeFileSync(
+    join(telegramStateDir, QUARANTINE_FILENAME),
+    JSON.stringify(marker) + '\n',
+    'utf-8',
+  )
+}

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

@@ -37,9 +37,14 @@ export const DEFAULT_TTL_MS = 5 * 60 * 1000  // 5 min
  * 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
+
+// Resolved lazily so tests can set SWITCHROOM_QUOTA_CACHE_PATH per-test
+// (the env var was previously read at module-import time, which made the
+// override in test setUp a no-op once the module was cached).
+export function defaultCachePath(): string {
+  return 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.
@@ -54,7 +59,7 @@ export function readQuotaCache(opts: {
   path?: string
   now?: number
 } = {}): ProbeResult | null {
-  const path = opts.path ?? DEFAULT_CACHE_PATH
+  const path = opts.path ?? defaultCachePath()
   const now = opts.now ?? Date.now()
 
   if (!existsSync(path)) return null
@@ -102,7 +107,7 @@ export function writeQuotaCache(
   // Don't cache hard failures — let the next boot retry clean.
   if (result.status === 'fail') return
 
-  const path = opts.path ?? DEFAULT_CACHE_PATH
+  const path = opts.path ?? defaultCachePath()
   // 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