switchroom 0.18.8 → 0.18.10

package/telegram-plugin/dist/server.js

@@ -24286,6 +24286,25 @@ function createOutstandingPermissionLedger() {
   };
 }
 
+// bridge/crash-breadcrumb.ts
+import { appendFileSync as appendFileSync3, statSync as statSync6, renameSync as renameSync4 } from "node:fs";
+function appendCrashBreadcrumb(logPath, kind, err, now = new Date) {
+  try {
+    try {
+      if (statSync6(logPath).size > MAX_LOG_BYTES)
+        renameSync4(logPath, `${logPath}.1`);
+    } catch {}
+    const detail = err instanceof Error ? err.stack ?? err.message : String(err);
+    const folded = detail.replace(/\s*\n\s*/g, " | ").slice(0, 4000);
+    appendFileSync3(logPath, `${now.toISOString()} ${kind} pid=${process.pid} ${folded}
+`);
+  } catch {}
+}
+var MAX_LOG_BYTES;
+var init_crash_breadcrumb = __esm(() => {
+  MAX_LOG_BYTES = 1024 * 1024;
+});
+
 // bridge/bridge.ts
 var exports_bridge = {};
 import { dirname as dirname3, join as join5 } from "path";
@@ -24394,7 +24413,7 @@ async function main() {
   }
   await mcp.connect(new StdioServerTransport);
 }
-var STATE_DIR, SOCKET_PATH, TOPIC_ID, AGENT_NAME, mcp, TOOL_SCHEMAS, EFFECTIVE_TOOL_SCHEMAS, sessionAllowRules, outstandingPermissions, permissionRearmEnabled, ipc = null, sessionTailEnabled, sessionTailHandle = null, ptyTailEnabled, ptyTailHandle = null;
+var STATE_DIR, SOCKET_PATH, TOPIC_ID, AGENT_NAME, mcp, TOOL_SCHEMAS, EFFECTIVE_TOOL_SCHEMAS, sessionAllowRules, outstandingPermissions, permissionRearmEnabled, ipc = null, sessionTailEnabled, sessionTailHandle = null, ptyTailEnabled, ptyTailHandle = null, CRASH_LOG_PATH;
 var init_bridge = __esm(async () => {
   init_server2();
   init_stdio2();
@@ -24406,6 +24425,7 @@ var init_bridge = __esm(async () => {
   init_ipc_client();
   init_tool_filter();
   init_permission_rule();
+  init_crash_breadcrumb();
   installPluginLogger2();
   STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join5(homedir4(), ".claude", "channels", "telegram");
   SOCKET_PATH = process.env.SWITCHROOM_GATEWAY_SOCKET ?? join5(STATE_DIR, "gateway.sock");
@@ -24454,7 +24474,7 @@ var init_bridge = __esm(async () => {
           quote: { type: "boolean", description: "Opt out of the default quote-reply behavior. Default: true. Pass false to send a bare message with no quote reference. Ignored when reply_to is explicitly set." },
           message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified." },
           origin_turn_id: { type: "string", description: "In a forum supergroup, pass back the origin_turn_id attribute from the <channel> message you are answering. It pins the reply to that message's topic even if another topic's turn started meanwhile. Omit in DMs / single-topic chats." },
-          files: { type: "array", items: { type: "string" }, description: "Absolute file paths to attach. Images send as photos; other types as documents. Max 50MB each." },
+          files: { type: "array", items: { type: "string" }, description: "Absolute file paths to attach. Images send as photos; other types as documents. Max 50MB each. Telegram rejects photos with extreme dimensions (aspect ratio over ~10:1, width+height over 10000px, or over 10MB) \u2014 very tall images like full-page screenshots are auto-rerouted as documents; crop or split them first if the user should see them inline as photos." },
           format: { type: "string", enum: ["html", "markdownv2", "text"], description: "Rendering mode. 'html' (default) converts markdown to Telegram HTML." },
           disable_web_page_preview: { type: "boolean", description: "Disable link preview thumbnails. Default: true." },
           protect_content: { type: "boolean", description: "When true, Telegram prevents the message from being forwarded or saved." },
@@ -25019,9 +25039,16 @@ var init_bridge = __esm(async () => {
     cleanup();
     setTimeout(() => process.exit(0), 500);
   });
+  CRASH_LOG_PATH = join5(STATE_DIR, "bridge-crash.log");
   process.on("unhandledRejection", (err) => {
     process.stderr.write(`telegram bridge: unhandled rejection: ${err}
 `);
+    appendCrashBreadcrumb(CRASH_LOG_PATH, "unhandledRejection", err);
+  });
+  process.on("uncaughtException", (err) => {
+    process.stderr.write(`telegram bridge: uncaught exception (continuing): ${err?.stack ?? err}
+`);
+    appendCrashBreadcrumb(CRASH_LOG_PATH, "uncaughtException", err);
   });
   await main().catch((err) => {
     process.stderr.write(`telegram bridge: fatal: ${err}

package/telegram-plugin/fallback-card-collapse.ts

@@ -0,0 +1,131 @@
+/**
+ * Reactive-path message collapse (#3031 PR 3).
+ *
+ * Pre-fix, a mid-turn 429 emitted up to three separate operator messages:
+ *   1. the ⚠️ model-unavailable card (sent BEFORE the fallback outcome is
+ *      known — deliberate, see the promise-honesty note below),
+ *   2. the fleet-fallback success announcement ("Switched to <account> …"),
+ *   3. the resume/boot notice.
+ *
+ * This module owns the SAFE part of collapsing that flow: when the swap
+ * SUCCEEDS, the announcement is folded into an EDIT of the just-sent
+ * model-unavailable card (one evolving card) instead of a second message.
+ *
+ * CRITICAL constraint (2026-06-06→07 incident): the card is deliberately
+ * sent before the outcome is known, and a FAILURE notice must arrive as its
+ * own message on EVERY error path — the card promised an announcement, and
+ * an edit that never happens (or a swallowed failure) breaks that promise.
+ * Therefore:
+ *   - `decideAnnouncementDelivery` returns 'edit' ONLY for a successful
+ *     'switched' outcome with a fresh, fallback-promising card on record.
+ *     Every other outcome kind ('all-blocked', 'no-old-active',
+ *     'no-eligible-target', errors) is 'send' — a separate message, exactly
+ *     the pre-fix behaviour.
+ *   - The gateway falls back to a plain send when the edit itself throws.
+ *
+ * Pure module (injected clock, no Telegram/bot imports) so the decision
+ * logic is unit-testable at the seam.
+ */
+
+/** One recorded model-unavailable card, per chat. */
+export interface ModelUnavailableCardRecord {
+  /** Telegram message id of the sent card (null until the send resolves —
+   *  callers should record only after the send succeeds). */
+  messageId: number;
+  /** The rendered card text as sent, so the edit can append to it. */
+  text: string;
+  /** Unix ms the card send resolved. */
+  atMs: number;
+  /** Did the card promise an in-flight auto-failover? Only such cards may
+   *  absorb the announcement — a manual-hint card never promised one. */
+  promisedFallback: boolean;
+}
+
+/**
+ * Freshness ceiling for folding into a card. The fallback dispatcher runs
+ * seconds after the card in the normal case; a card older than this belongs
+ * to a previous incident and must not absorb an unrelated announcement.
+ *
+ * Known accepted race (#3035 review, finding 4): the record lands only
+ * AFTER the card send resolves, and stays editable for this whole window —
+ * so a LATER 'switched' outcome (a second dispatch inside the window) can
+ * edit a card whose incident was already answered. Bounded by this 5-min
+ * ceiling plus the one-shot `take` semantics (a card absorbs at most one
+ * announcement); worst case is one announcement folded into a slightly
+ * older card instead of arriving as a separate message — never a lost
+ * announcement.
+ */
+export const CARD_COLLAPSE_MAX_AGE_MS = 5 * 60_000;
+
+export interface ModelUnavailableCardRegistry {
+  /** Record the card most recently sent to `chatId` (replaces any prior). */
+  record(chatId: string, rec: ModelUnavailableCardRecord): void;
+  /**
+   * One-shot take: return the fresh, fallback-promising card for `chatId`
+   * and remove it (a card absorbs at most one announcement). Returns null —
+   * and clears the entry — when the record is stale or never promised a
+   * fallback.
+   */
+  take(chatId: string, now: number): ModelUnavailableCardRecord | null;
+  /** Number of chats with a recorded card (test/introspection helper). */
+  size(): number;
+}
+
+export function createModelUnavailableCardRegistry(
+  maxAgeMs: number = CARD_COLLAPSE_MAX_AGE_MS,
+): ModelUnavailableCardRegistry {
+  const cards = new Map<string, ModelUnavailableCardRecord>();
+  return {
+    record(chatId, rec) {
+      cards.set(chatId, rec);
+    },
+    take(chatId, now) {
+      const rec = cards.get(chatId);
+      if (!rec) return null;
+      cards.delete(chatId);
+      if (!rec.promisedFallback) return null;
+      if (now - rec.atMs > maxAgeMs) return null;
+      return rec;
+    },
+    size() {
+      return cards.size;
+    },
+  };
+}
+
+/**
+ * The outcome kinds `runFleetAutoFallback` can produce, plus 'error' for
+ * the dispatcher-threw path (broker unreachable, listState/markExhausted
+ * throw). Kept as a plain string union so this module stays import-free.
+ */
+export type FallbackDeliveryOutcomeKind =
+  | 'switched'
+  | 'all-blocked'
+  | 'no-old-active'
+  | 'no-eligible-target'
+  | 'error';
+
+/**
+ * Should the announcement for `outcomeKind` be delivered by EDITING the
+ * recorded model-unavailable card, or by SENDING a separate message?
+ *
+ * 'edit' is returned ONLY when the swap succeeded AND a fresh
+ * fallback-promising card exists for the chat. Every failure / no-op
+ * outcome is 'send' — the promise-honesty contract: a failure notice must
+ * arrive as its own message on every error path.
+ */
+export function decideAnnouncementDelivery(
+  outcomeKind: FallbackDeliveryOutcomeKind,
+  card: ModelUnavailableCardRecord | null,
+): 'edit' | 'send' {
+  if (outcomeKind !== 'switched') return 'send';
+  return card !== null ? 'edit' : 'send';
+}
+
+/**
+ * The single evolving card: original card text plus the announcement,
+ * separated by a rule so the "before/after" reads as one incident timeline.
+ */
+export function foldAnnouncementIntoCard(cardText: string, announcement: string): string {
+  return `${cardText}\n\n${announcement}`;
+}

package/telegram-plugin/gateway/approval-card-stores.ts

@@ -0,0 +1,99 @@
+/**
+ * In-memory storage for the four AGENT-INITIATED approval-card families
+ * (vault_request_access / vault_request_save / request_secret /
+ * mental_model_propose), extracted from gateway.ts (Phase 3 step 1 of the
+ * gateway decomposition — see #2996). STORAGE ONLY: the per-card expiry LOGIC
+ * (card edits, timeout synthetics, missed-approval re-offers) still lives in
+ * gateway.ts and is injected here as `expire`. This module owns the Map
+ * lifecycle and CO-LOCATES the TTL sweep next to the storage it sweeps, so the
+ * gateway's authoritative `pendingStateReaper` calls a single `store.sweep(now)`
+ * delegation instead of open-coding a `sweepExpiredEntries(...)` per family.
+ *
+ * Why a Map-compatible surface (get/set/delete/has/iteration) rather than a
+ * bespoke API: every existing gateway call site — the callback-query handlers,
+ * the executor add-sites, and `restorePendingApprovalCards` — used the raw Map
+ * directly. Preserving the exact Map method surface keeps those call sites
+ * BYTE-IDENTICAL (the variable name and every `.get`/`.set`/`.delete`/`for..of`
+ * are unchanged), which is the invariant this phase must not break: the store
+ * moves WHERE the Map is constructed and WHERE its sweep lives, nothing about
+ * how the gateway reads or writes it. Restore semantics are therefore untouched.
+ *
+ * Race contract preserved (pinned by approval-card-stores.test.ts):
+ *   - A verdict (operator tap → `.delete(stageId)`) arriving DURING an expiry
+ *     sweep is single-shot-safe: the pure `expirePendingCard` core removes the
+ *     entry before any fallible side effect, so the same card can never both
+ *     expire and resolve. The store's `sweep` is a thin pass-through to that
+ *     core via `sweepExpiredEntries`, so the ordering guarantee is unchanged.
+ *   - A verdict arriving DURING restore is a plain `.set`/`.delete` on the same
+ *     Map instance the restore populates — no separate storage to desync.
+ *   - The shared reaper cadence is unchanged: `sweep(now)` performs exactly the
+ *     work the old `sweepPendingX(now)` free functions did, in the same order.
+ *
+ * `expire` and `log` are supplied as THUNKS so a store constructed early in
+ * gateway module-eval can reference the hoisted `expire*Card` functions and the
+ * `const cardExpiryLog` arrow (which is in the temporal dead zone at
+ * construction time); both are resolved lazily at sweep time.
+ */
+
+import { sweepExpiredEntries } from './pending-card-expiry.js'
+
+export interface SweepableCardStore<T> {
+  get(stageId: string): T | undefined
+  set(stageId: string, value: T): void
+  delete(stageId: string): boolean
+  has(stageId: string): boolean
+  clear(): void
+  readonly size: number
+  keys(): IterableIterator<string>
+  values(): IterableIterator<T>
+  entries(): IterableIterator<[string, T]>
+  forEach(cb: (value: T, key: string, map: Map<string, T>) => void): void
+  [Symbol.iterator](): IterableIterator<[string, T]>
+  /**
+   * Expire every entry past its TTL. Delegates to the same pure
+   * `sweepExpiredEntries` core the gateway used inline, so per-entry
+   * fault-isolation and single-shot ordering are byte-identical.
+   */
+  sweep(now: number): void
+}
+
+export interface SweepableCardStoreDeps<T> {
+  /** Predicate: is this entry past its TTL at `now`? Closes over the family TTL. */
+  isExpired: (value: T, now: number) => boolean
+  /**
+   * Per-entry expiry action (card strip + timeout synthetic + missed-approval
+   * re-offer). A THUNK so it can reference gateway functions that are hoisted /
+   * defined after this store is constructed. Called once per expired entry.
+   */
+  expire: () => (stageId: string, value: T, now: number) => void
+  /** Error sink thunk (resolves the gateway's `cardExpiryLog` lazily). */
+  log: () => (msg: string) => void
+}
+
+/**
+ * Create a Map-backed, self-sweeping store for one approval-card family.
+ * The backing Map is the sole storage; the returned object forwards the Map
+ * surface the gateway uses plus a co-located `sweep`.
+ */
+export function createSweepableCardStore<T>(
+  deps: SweepableCardStoreDeps<T>,
+): SweepableCardStore<T> {
+  const map = new Map<string, T>()
+  return {
+    get: (stageId) => map.get(stageId),
+    set: (stageId, value) => void map.set(stageId, value),
+    delete: (stageId) => map.delete(stageId),
+    has: (stageId) => map.has(stageId),
+    clear: () => map.clear(),
+    get size() {
+      return map.size
+    },
+    keys: () => map.keys(),
+    values: () => map.values(),
+    entries: () => map.entries(),
+    forEach: (cb) => map.forEach(cb),
+    [Symbol.iterator]: () => map[Symbol.iterator](),
+    sweep: (now) =>
+      sweepExpiredEntries(map, deps.isExpired, deps.expire(), now, deps.log()),
+  }
+}

package/telegram-plugin/gateway/bot-commands-ops-info.ts

@@ -0,0 +1,194 @@
+import type { Bot, Context, InlineKeyboard } from 'grammy'
+import { hostdWillBeUsed } from './hostd-dispatch.js'
+import { maskVaultKey } from '../demo-mask.js'
+import { switchroomHelpText as buildSwitchroomHelpText } from '../welcome-text.js'
+
+/**
+ * Read-only ops/info slash commands extracted verbatim from gateway.ts
+ * (#2996 Phase 5 leaf move): `/doctor`, `/grant`, `/dangerous`,
+ * `/permissions`, `/version`, `/whoami`, `/commands`.
+ *
+ * These are pure info/ops surfaces (no send-path or turn-lifecycle
+ * coupling). Every gateway-local helper they close over is passed in via
+ * `deps` (repo factory-deps precedent) so the module never back-references
+ * the gateway singleton or reads `currentTurn`. `bot` is injected so
+ * grammy registration order is preserved at the original call site.
+ */
+export interface OpsInfoCommandDeps {
+  AGENT_ADMIN: boolean
+  isAuthorizedSender: (ctx: Context) => boolean
+  getMyAgentName: () => string
+  switchroomReply: (
+    ctx: Context,
+    text: string,
+    options?: {
+      html?: boolean
+      reply_markup?: InlineKeyboard
+      classification?: 'query' | 'mutation' | 'heavy'
+    },
+  ) => Promise<void>
+  buildDoctorScopeKeyboard: () => InlineKeyboard
+  renderSelfDoctor: (ctx: Context) => Promise<void>
+  preBlock: (text: string) => string
+  formatSwitchroomOutput: (output: string, maxLen?: number) => string
+  getCommandArgs: (ctx: Context) => string
+  assertSafeAgentName: (name: string) => void
+  runSwitchroomCommand: (
+    ctx: Context,
+    args: string[],
+    label: string,
+    classification?: 'query' | 'mutation' | 'heavy',
+  ) => Promise<void>
+  switchroomExecCombined: (args: string[], timeoutMs?: number) => string
+  stripAnsi: (text: string) => string
+  hasDemoFlag: (args: string) => boolean
+  escapeHtmlForTg: (text: string) => string
+}
+
+export function registerOpsInfoCommands(bot: Bot, deps: OpsInfoCommandDeps): void {
+  const {
+    AGENT_ADMIN,
+    isAuthorizedSender,
+    getMyAgentName,
+    switchroomReply,
+    buildDoctorScopeKeyboard,
+    renderSelfDoctor,
+    preBlock,
+    formatSwitchroomOutput,
+    getCommandArgs,
+    assertSafeAgentName,
+    runSwitchroomCommand,
+    switchroomExecCombined,
+    stripAnsi,
+    hasDemoFlag,
+    escapeHtmlForTg,
+  } = deps
+
+  /** Compact HTML card from the `config whoami` JSON view. Names/booleans only.
+   *  `demo` (the `/whoami demo` suffix) masks the vault key NAMES via maskVaultKey
+   *  for screen recordings — agent/MCP/model/skills topology is left untouched
+   *  (out of scope). Off by default. */
+  function formatWhoamiCard(v: {
+    name?: string; persona?: string | null; model?: string | null; tier?: string;
+    tools?: { allow?: string[]; deny?: string[] }; mcpServers?: string[]; skills?: string[];
+    vault?: { key: string; readable: boolean }[];
+    powers?: { admin?: boolean; root?: boolean; configEdit?: boolean; crossAgentHostVerbs?: boolean };
+    scheduleCount?: number; memoryBackend?: string | null;
+  }, demo = false): string {
+    const esc = escapeHtmlForTg
+    const yn = (b?: boolean) => (b ? '✓' : '✗')
+    const lines: string[] = []
+    lines.push(`👤 **${esc(v.name ?? '?')}** · ${esc(v.tier ?? 'standard')}`)
+    if (v.persona) lines.push(esc(v.persona))
+    if (v.model) lines.push(`Model: ${esc(v.model)}`)
+    const allow = v.tools?.allow ?? []
+    lines.push(`Tools: ${allow.length ? esc(allow.slice(0, 8).join(', ')) + (allow.length > 8 ? ` …(+${allow.length - 8})` : '') : '—'}`)
+    if ((v.tools?.deny ?? []).length) lines.push(`Denied: ${esc((v.tools!.deny!).join(', '))}`)
+    if ((v.mcpServers ?? []).length) lines.push(`MCP: ${esc(v.mcpServers!.join(', '))}`)
+    if ((v.skills ?? []).length) lines.push(`Skills: ${esc(v.skills!.join(', '))}`)
+    if ((v.vault ?? []).length) {
+      lines.push(`Vault keys (names only): ${v.vault!.map(k => `${esc(demo ? maskVaultKey(k.key) : k.key)} ${yn(k.readable)}`).join(', ')}`)
+    }
+    const p = v.powers ?? {}
+    lines.push(`Powers: admin ${yn(p.admin)} · root ${yn(p.root)} · config-edit ${yn(p.configEdit)} · cross-agent verbs ${yn(p.crossAgentHostVerbs)}`)
+    lines.push(`Schedule: ${v.scheduleCount ?? 0} cron · Memory: ${esc(v.memoryBackend ?? 'none')}`)
+    return lines.join('\n')
+  }
+
+  bot.command('doctor', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    try {
+      // Admin agents with hostd reachable choose scope (one tap, no
+      // approval card — doctor is read-only). Everyone else keeps the
+      // original zero-extra-tap in-container behaviour.
+      if (AGENT_ADMIN && hostdWillBeUsed(getMyAgentName())) {
+        await switchroomReply(ctx, '🩺 **Doctor** — which scope?', {
+          html: true,
+          reply_markup: buildDoctorScopeKeyboard(),
+        })
+        return
+      }
+      await renderSelfDoctor(ctx)
+    } catch (err: unknown) {
+      await switchroomReply(ctx, `**doctor failed:**\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
+    }
+  })
+
+  bot.command('grant', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    const parts = getCommandArgs(ctx).split(/\s+/).filter(Boolean)
+    if (parts.length === 0) { await switchroomReply(ctx, 'Usage: /grant <tool>  or  /grant <agent> <tool>'); return }
+    let agentName: string; let tool: string
+    if (parts.length === 1) { agentName = getMyAgentName(); tool = parts[0] }
+    else { agentName = parts[0]; tool = parts.slice(1).join(' ') }
+    try { assertSafeAgentName(agentName) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
+    await runSwitchroomCommand(ctx, ['agent', 'grant', agentName, tool], `grant ${agentName} ${tool}`)
+  })
+
+  bot.command('dangerous', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    const parts = getCommandArgs(ctx).split(/\s+/).filter(Boolean)
+    let agentName: string; let off = false
+    if (parts.length === 0) { agentName = getMyAgentName() }
+    else if (parts.length === 1 && parts[0] === 'off') { agentName = getMyAgentName(); off = true }
+    else { agentName = parts[0]; if (parts[1] === 'off') off = true }
+    try { assertSafeAgentName(agentName) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
+    const args = ['agent', 'dangerous', agentName]; if (off) args.push('--off')
+    await runSwitchroomCommand(ctx, args, `dangerous ${agentName}${off ? ' off' : ''}`)
+  })
+
+  bot.command('permissions', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    const agentName = (typeof ctx.match === "string" ? ctx.match : "").trim() || getMyAgentName()
+    try { assertSafeAgentName(agentName) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
+    await runSwitchroomCommand(ctx, ['agent', 'permissions', agentName], `permissions ${agentName}`)
+  })
+
+  // Drive-by cleanup (#927): the dead /update handler that lived here
+  // was a pre-#919 stub. Grammy registers in order so the comprehensive
+  // /update handler at line ~6516 (added in #919, hardened in #924,
+  // docker-guarded in #934) fired first and this one never ran.
+  // Removed to avoid future confusion.
+
+  bot.command('version', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    try {
+      let output: string
+      try { output = switchroomExecCombined(['version'], 10000) }
+      catch (err: unknown) { output = (err as any).stdout ?? (err as any).message ?? 'version failed' }
+      const trimmed = stripAnsi(output).trim()
+      if (!trimmed) { await switchroomReply(ctx, 'version: no output'); return }
+      await switchroomReply(ctx, preBlock(formatSwitchroomOutput(trimmed)), { html: true })
+    } catch (err: unknown) {
+      await switchroomReply(ctx, `**version failed:**\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
+    }
+  })
+
+
+  // /whoami — the operator's view of THIS agent's sandbox (the same
+  // `config whoami` the agent itself can call as an MCP tool, and the host CLI
+  // exposes). Read-only, isAuthorizedSender-gated like /version — surfaces
+  // tools / MCP / vault key-NAMES (never values) / powers so the operator can
+  // see at a glance what this agent is authorized for.
+  bot.command('whoami', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    const demo = hasDemoFlag(getCommandArgs(ctx))
+    try {
+      let raw: string
+      try { raw = switchroomExecCombined(['config', 'whoami'], 10000) }
+      catch (err: unknown) { raw = (err as any).stdout ?? (err as any).message ?? 'whoami failed' }
+      const trimmed = stripAnsi(raw).trim()
+      let card: string
+      try { card = formatWhoamiCard(JSON.parse(trimmed.split('\n').pop() ?? trimmed), demo) }
+      catch { card = preBlock(formatSwitchroomOutput(trimmed || 'whoami: no output')) }
+      await switchroomReply(ctx, card, { html: true })
+    } catch (err: unknown) {
+      await switchroomReply(ctx, `**whoami failed:**\n${preBlock(formatSwitchroomOutput((err as any).message ?? 'unknown error'))}`, { html: true })
+    }
+  })
+
+  bot.command('commands', async ctx => {
+    if (!isAuthorizedSender(ctx)) return
+    await switchroomReply(ctx, buildSwitchroomHelpText(getMyAgentName()), { html: true })
+  })
+}