switchroom 0.13.65 → 0.14.1

package/telegram-plugin/gateway/gateway.ts

@@ -57,6 +57,7 @@ import { allocateDraftId } from '../draft-transport.js'
 import {
   makeEmptyActivityState,
   registerAndRender,
+  describeToolUse,
   type ActivityState,
 } from '../tool-activity-summary.js'
 import { toolLabel } from '../tool-labels.js'
@@ -372,6 +373,14 @@ import {
   loadCreditState,
   saveCreditState,
 } from '../credits-watch.js'
+import {
+  evaluateQuotaWatchAccount,
+  loadQuotaWatchState,
+  saveQuotaWatchState,
+  patchQuotaWatchState,
+  emptyAccountState,
+} from '../quota-watch.js'
+import { buildSnapshotsFromState, buildSnapshotsFromCachedState } from '../auth-snapshot-format.js'
 import {
   writeTurnActiveMarker,
   touchTurnActiveMarker,
@@ -3897,11 +3906,12 @@ const ipcServer: IpcServer = createIpcServer({
           const updateOutcomeLine = (() => {
             try { return maybeRenderUpdateAnnouncement() ?? undefined } catch { return undefined }
           })()
+          const resolvedAgentDirForCard = agentDir ?? (process.env.TELEGRAM_STATE_DIR ? require('path').dirname(process.env.TELEGRAM_STATE_DIR) : '/tmp')
           startBootCard(chatId, threadId, botApiForCard, {
             agentName: agentDisplayName,
             agentSlug,
             version: formatBootVersion(),
-            agentDir: agentDir ?? (process.env.TELEGRAM_STATE_DIR ? require('path').dirname(process.env.TELEGRAM_STATE_DIR) : '/tmp'),
+            agentDir: resolvedAgentDirForCard,
             gatewayInfo: { pid: process.pid, startedAtMs: GATEWAY_STARTED_AT_MS },
             restartReason: reason,
             restartAgeMs: markerAgeMs,
@@ -3910,6 +3920,7 @@ const ipcServer: IpcServer = createIpcServer({
             probeQuotaViaBroker: (t) => probeQuotaForBootCard(agentSlug, t),
             tmuxSupervisor: process.env.SWITCHROOM_TMUX_SUPERVISOR === '1',
             dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
+            configSnapshotPath: join(resolvedAgentDirForCard, '.config-snapshot.json'),
             ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
           }, ackMsgId).then(handle => {
             activeBootCard = handle
@@ -6837,7 +6848,12 @@ async function drainActivitySummary(turn: CurrentTurn): Promise<void> {
     while (turn.activityPendingRender !== turn.activityLastSentRender) {
       const target = turn.activityPendingRender
       if (target == null) break
-      const html = `<i>${target}</i>`
+      // Escape before wrapping in <i> + parse_mode HTML. The legacy
+      // verb-count summaries were safe ASCII, but the draft-mirror's
+      // describeToolUse content (file names, Bash descriptions, search
+      // queries) can contain <, >, & — which would break HTML parsing
+      // and surface literal tags (the exact #1942 bug class).
+      const html = `<i>${escapeHtmlForTg(target)}</i>`
       const chat = turn.sessionChatId
       const thread = turn.sessionThreadId
       // sendMessageDraft doesn't support forum threads.
@@ -7130,14 +7146,21 @@ function handleSessionEvent(ev: SessionEvent): void {
       // exactly once at a time and re-running until pending matches
       // the last-sent. Captures `turn` so a late drain after turn-swap
       // can't corrupt the next turn's atom.
-      // DRAFT_MIRROR (RFC draft-mirror-preview, Phase 1): the model's
-      // prose narration owns the single per-chat draft slot. Suppress
-      // the activity-summary tool-count draft so the two don't collide
-      // (Telegram shows one draft per chat — the later write clobbers
-      // the earlier). The activity-summary code stays intact for the
-      // kill-switch path; it's retired for good only in Phase 4.
-      if (!DRAFT_MIRROR_ENABLED && !turn.replyCalled && !isTelegramSurfaceTool(name)) {
-        const rendered = registerAndRender(turn.toolActivity, name)
+      // DRAFT_MIRROR (RFC draft-mirror-preview): render each tool_use as a
+      // human-friendly line in the live preview, using the model-authored
+      // descriptive field (Bash.description, Read/Edit file basename,
+      // hindsight→"Searching memory", etc. — see describeToolUse). Latest
+      // action wins (the draft shows "doing X" live), clears on reply.
+      // Never surfaces raw shell/query syntax — option A, uniform across
+      // code + non-code agents.
+      //
+      // Flag OFF (default): the legacy generic verb-count summary
+      // ("Ran 5 commands") via registerAndRender — byte-identical to
+      // pre-draft-mirror behavior.
+      if (!turn.replyCalled && !isTelegramSurfaceTool(name)) {
+        const rendered = DRAFT_MIRROR_ENABLED
+          ? describeToolUse(name, ev.input)
+          : registerAndRender(turn.toolActivity, name)
         if (rendered != null) {
           turn.activityPendingRender = rendered
           if (turn.activityInFlight == null) {
@@ -7185,19 +7208,19 @@ function handleSessionEvent(ev: SessionEvent): void {
             isPrivateChat: turn.isDm,
             threadId: turn.sessionThreadId,
             // Transport selection:
-            // - DRAFT_MIRROR (RFC draft-mirror-preview, Phase 1): force
-            //   the ephemeral compose-area draft so narration is a
-            //   clears-on-reply preview. Wins over visible-answer-stream.
-            //   No-reply delivery is owned by turn-flush, not materialize.
-            // - else #869-Phase1 visible-answer-stream: omit the draft
-            //   API so the lane edits a user-visible chat-timeline
-            //   message (minInitialChars:1 opens it on the first chunk).
-            // - else legacy: draft transport.
-            ...(DRAFT_MIRROR_ENABLED
-              ? { sendMessageDraft: sendMessageDraftFn }
-              : ANSWER_STREAM_VISIBLE_ENABLED
-                ? { minInitialChars: 1 }
-                : { sendMessageDraft: sendMessageDraftFn }),
+            // #869-Phase1 visible-answer-stream: omit the draft API so
+            // the lane edits a user-visible chat-timeline message
+            // (minInitialChars:1 opens it on the first chunk). The
+            // draft-mirror does NOT touch this lane — the canary proved
+            // the model emits almost no interstitial assistant.text
+            // (it thinks→tool→reply), so routing it to the draft just
+            // emptied the preview. The draft-mirror instead renders the
+            // tool_use stream (case 'tool_use' above) where the real
+            // signal lives. assistant.text keeps its visible-message
+            // home; the reply tool stays the canonical answer.
+            ...(ANSWER_STREAM_VISIBLE_ENABLED
+              ? { minInitialChars: 1 }
+              : { sendMessageDraft: sendMessageDraftFn }),
             // #1075: route through robustApiCall so flood-wait,
             // benign-400, and THREAD_NOT_FOUND are handled uniformly
             // instead of crashing the answer-stream loop on a deleted
@@ -11849,6 +11872,183 @@ async function runCreditWatch(): Promise<void> {
   }
 }
 
+/**
+ * Quota threshold-tier push loop body (#E4). Reads the broker's in-memory
+ * cached utilization (populated by previous probeQuota calls from /auth,
+ * auto-fallback, and boot cards) via `listState.accounts[].last_quota`.
+ * Classifies each account via classifyHealth, and fires one Telegram message
+ * per healthy ↔ throttling transition (edge-triggered, not level-triggered).
+ * Does NOT fire on healthy → blocked or blocked → healthy — credits-watch.ts
+ * owns those.
+ *
+ * Probe discipline:
+ *   - Steady-state polls: ONE broker `listState` IPC call only (no network).
+ *   - Accounts with no cached snapshot (null last_quota): skipped silently
+ *     (classifyHealth returns 'unknown'). Cache populates from /auth, boot
+ *     card, and auto-fallback probes in normal use.
+ *   - State transition detected: ONE targeted `probeQuota` call for ONLY the
+ *     crossing account, immediately before sending the notification, to get
+ *     fresh numbers for the message body. All other steady-state accounts
+ *     are not probed.
+ *
+ * This replaces the previous implementation that called probeQuota for ALL
+ * accounts unconditionally on every 15-minute poll (~768 live Anthropic
+ * network calls/day for an 8-account fleet). The corrected version makes
+ * 0 network calls on steady-state polls and at most 1 call per crossing
+ * event (which is also when we need to notify the user anyway).
+ *
+ * State persists across restarts via `<stateDir>/quota-watch.json`.
+ * Mirrors runCreditWatch's structure and notification routing.
+ */
+async function runQuotaWatch(): Promise<void> {
+  const agentName = getMyAgentName()
+  const stateDir = STATE_DIR
+
+  // Read broker state. The listState response now includes last_quota
+  // per account — the broker's in-memory cache from previous probeQuota
+  // calls. This is a local IPC call: no network, no Anthropic contact.
+  const brokerClient = await getAuthBrokerClient(agentName)
+  if (!brokerClient) {
+    process.stderr.write('telegram gateway: quota-watch: broker client unavailable — skipping\n')
+    return
+  }
+
+  let listStateData: Awaited<ReturnType<typeof brokerClient.listState>>
+  try {
+    listStateData = await brokerClient.listState()
+  } catch (err) {
+    process.stderr.write(`telegram gateway: quota-watch: listState failed: ${err}\n`)
+    return
+  }
+
+  if (!listStateData.accounts || listStateData.accounts.length === 0) {
+    return // No accounts — nothing to watch.
+  }
+
+  // Build AccountSnapshot[] from cached broker state only — no live probe.
+  // Accounts with null last_quota produce quota=null snapshots; classifyHealth
+  // returns 'unknown'; evaluateQuotaWatchAccount skips — no false alarms.
+  const snapshots = buildSnapshotsFromCachedState(listStateData)
+
+  // Load persisted per-account state.
+  let watchState = loadQuotaWatchState(stateDir)
+  const now = Date.now()
+  const access = loadAccess()
+
+  // First pass: evaluate all accounts against cached state. Collect
+  // labels that need a live probe (i.e. accounts with a detected transition
+  // that we're about to notify about). We probe those to get fresh
+  // utilization numbers for the notification body — not for classification.
+  const pendingTransitions: Array<{
+    accountLabel: string
+    snapIndex: number
+    decision: ReturnType<typeof evaluateQuotaWatchAccount>
+  }> = []
+
+  const labelToSnapIndex = new Map<string, number>(
+    snapshots.map((s, i) => [s.label, i]),
+  )
+
+  for (const snap of snapshots) {
+    const prev = watchState[snap.label] ?? emptyAccountState()
+    const decision = evaluateQuotaWatchAccount({ agentName, snap, prev, now })
+    if (decision.kind !== 'skip') {
+      pendingTransitions.push({
+        accountLabel: snap.label,
+        snapIndex: labelToSnapIndex.get(snap.label) ?? -1,
+        decision,
+      })
+    }
+  }
+
+  if (pendingTransitions.length === 0) {
+    return // Steady-state: no notifications, no probes, no state write.
+  }
+
+  // Transition detected: probe ONLY the crossing accounts to get fresh
+  // numbers for the notification message bodies. One batched RPC for all
+  // crossing accounts (typically 1, rarely 2+).
+  const crossingLabels = pendingTransitions.map(t => t.accountLabel)
+  let freshProbeMap = new Map<string, Awaited<ReturnType<typeof brokerClient.probeQuota>>['results'][number]['result']>()
+  try {
+    const probeData = await brokerClient.probeQuota(crossingLabels, 8000)
+    for (const entry of probeData.results) {
+      freshProbeMap.set(entry.label, entry.result)
+    }
+  } catch (err) {
+    // Probe failed — still send notifications using cached data.
+    // Don't abort: the user should know about the threshold crossing
+    // even if the message body shows slightly stale numbers.
+    process.stderr.write(`telegram gateway: quota-watch: probe for crossing accounts failed: ${err}\n`)
+  }
+
+  // Build final notifications, enriching the snapshot with fresh probe
+  // data where available.
+  let mutatedState = watchState
+  const notifications: Array<{ message: string; accountLabel: string }> = []
+
+  for (const { accountLabel, snapIndex, decision } of pendingTransitions) {
+    // Re-evaluate with fresh probe data to get an accurate message body.
+    // If the fresh probe succeeded, replace the snap's quota with live data.
+    const freshResult = freshProbeMap.get(accountLabel)
+    let enrichedDecision = decision
+    // pendingTransitions only ever holds notify decisions (pushed under
+    // `decision.kind !== 'skip'`). Narrow explicitly so `decision.transition`
+    // type-checks below; this continue never fires at runtime.
+    if (decision.kind !== 'notify') continue
+    if (freshResult && freshResult.ok && snapIndex >= 0) {
+      const enrichedSnap = { ...snapshots[snapIndex]!, quota: freshResult.data }
+      const prev = watchState[accountLabel] ?? emptyAccountState()
+      const re = evaluateQuotaWatchAccount({ agentName, snap: enrichedSnap, prev, now })
+      // If the fresh probe still shows the same transition, use the
+      // enriched message. If it no longer shows a transition (e.g. the
+      // account recovered in the 100ms between listState and probe),
+      // fall through to skip this notification.
+      if (re.kind === 'notify' && re.transition === decision.transition) {
+        enrichedDecision = re
+      } else if (re.kind === 'skip') {
+        // State normalised by the time of the probe — don't notify.
+        continue
+      }
+    }
+
+    if (enrichedDecision.kind !== 'notify') continue
+    notifications.push({ message: enrichedDecision.message, accountLabel })
+    mutatedState = patchQuotaWatchState(mutatedState, accountLabel, enrichedDecision.newAccountState)
+  }
+
+  if (notifications.length === 0) {
+    return // All transitions resolved by the time of the live probe.
+  }
+
+  // Send all notifications (one message per crossing account).
+  for (const { message, accountLabel } of notifications) {
+    for (const chat_id of access.allowFrom) {
+      // Quota-watch notify — best-effort. Wrap via swallowingApiCall so
+      // flood-wait / deleted-chat / not-found surface as a stderr log
+      // rather than a thrown exception that aborts the loop and leaves
+      // half the allowFrom chats unnotified. Matches the wrapping
+      // contract enforced by scripts/check-bot-api-wrapping.sh (#1075).
+      await swallowingApiCall(
+        () =>
+          bot.api.sendMessage(chat_id, message, {
+            parse_mode: 'HTML',
+            link_preview_options: { is_disabled: true },
+          }),
+        { chat_id, verb: 'quota-watch.notify' },
+      )
+    }
+    process.stderr.write(`telegram gateway: quota-watch: notified transition for account=${accountLabel}\n`)
+  }
+
+  // Persist updated state regardless of whether sends succeeded.
+  try {
+    saveQuotaWatchState(stateDir, mutatedState)
+  } catch (err) {
+    process.stderr.write(`telegram gateway: quota-watch state persist failed: ${err}\n`)
+  }
+}
+
 bot.command("auth", async ctx => {
   // sec WS7-F2b (#1394): `/auth` drives the auth-broker credential
   // lifecycle (`/auth add` mints/attaches an Anthropic account token,
@@ -12133,8 +12333,7 @@ function resolveAgentDirForName(agent: string): string | null {
  *   restart   — systemctl --user restart switchroom-<agent>
  *   reauth    — delegate to runSwitchroomAuthCommand (same flow as /auth reauth)
  *   logs      — post last 30 lines of journalctl for the agent
- *   swap-slot, add-slot — Phase 4c will wire these; for now toast with the
- *                         equivalent CLI command for the user to run manually.
+ *   slot management buttons — removed (E5); use /auth use or /auth add instead.
  */
 /**
  * Issue #44: handle taps on the deferred-secret card's inline buttons.
@@ -13763,15 +13962,6 @@ async function handleOperatorEventCallback(ctx: Context, data: string): Promise<
       }
       return
     }
-    case 'swap-slot':
-    case 'add-slot': {
-      await ctx.answerCallbackQuery({ text: 'Phase 4c will wire this' }).catch(() => {})
-      const cmd = action === 'swap-slot' ? `auth use ${agent} <slot-name>` : `auth add ${agent}`
-      await ctx.reply(`Phase 4c will wire ${action} buttons. Until then, run in terminal: <code>switchroom ${cmd}</code>`, {
-        parse_mode: 'HTML',
-      })
-      return
-    }
     default: {
       await ctx.answerCallbackQuery({ text: `Unknown action: ${action}` }).catch(() => {})
       return
@@ -14666,7 +14856,7 @@ bot.on('callback_query:data', async ctx => {
 
   // op:<action>:<encoded-agent> callbacks from operator-events.ts
   // renderOperatorEvent(). Agent name is URL-encoded at emit (issue #24).
-  // Actions: dismiss, restart, reauth, swap-slot, add-slot, logs.
+  // Actions: dismiss, restart, reauth, logs.
   if (data.startsWith('op:')) {
     await handleOperatorEventCallback(ctx, data)
     return
@@ -16628,11 +16818,12 @@ void (async () => {
                     const updateOutcomeLine = (() => {
                       try { return maybeRenderUpdateAnnouncement() ?? undefined } catch { return undefined }
                     })()
+                    const resolvedAgentDirForBootCard = agentDir ?? join(homedir(), '.switchroom', 'agents', agentSlug)
                     const handle = await startBootCard(chatId, threadId, botApiForCard, {
                       agentName: agentDisplayName,
                       agentSlug,
                       version: formatBootVersion(),
-                      agentDir: agentDir ?? join(homedir(), '.switchroom', 'agents', agentSlug),
+                      agentDir: resolvedAgentDirForBootCard,
                       gatewayInfo: { pid: process.pid, startedAtMs: GATEWAY_STARTED_AT_MS },
                       restartReason: reason,
                       restartAgeMs: markerAgeMs,
@@ -16641,6 +16832,7 @@ void (async () => {
                       probeQuotaViaBroker: (t) => probeQuotaForBootCard(agentSlug, t),
                       tmuxSupervisor: process.env.SWITCHROOM_TMUX_SUPERVISOR === '1',
                       dockerMode: process.env.SWITCHROOM_RUNTIME === 'docker',
+                      configSnapshotPath: join(resolvedAgentDirForBootCard, '.config-snapshot.json'),
                       ...(updateOutcomeLine ? { updateOutcomeLine } : {}),
                     }, ackMsgId)
                     activeBootCard = handle
@@ -16692,6 +16884,34 @@ void (async () => {
           }, CREDIT_WATCH_POLL_MS).unref()
         }
 
+        // Proactive quota threshold-tier push (#E4). Reads broker cached
+        // quota for all accounts in the pool, classifies health via
+        // classifyHealth, and fires one Telegram message per
+        // healthy ↔ throttling transition (edge-triggered). Does NOT
+        // cover healthy → blocked or blocked → healthy — credits-watch
+        // handles those fatal-billing transitions above.
+        //
+        // Cadence: 15 min by default (same as credit-watch). Each poll
+        // calls broker listState (local IPC, cheap) + probeQuota only
+        // when a state-change is detected (to get fresh numbers for
+        // the notification body). SWITCHROOM_QUOTA_WATCH_POLL_MS=0 disables.
+        const QUOTA_WATCH_POLL_MS = Number(process.env.SWITCHROOM_QUOTA_WATCH_POLL_MS ?? 15 * 60_000)
+        if (QUOTA_WATCH_POLL_MS > 0) {
+          // Delay the initial run by 30 s to let the broker connection
+          // settle after boot (avoids a probe race with the boot-card
+          // quota probe that fires in the first few seconds).
+          setTimeout(() => {
+            void runQuotaWatch().catch((err) => {
+              process.stderr.write(`telegram gateway: quota-watch initial run failed: ${err}\n`)
+            })
+          }, 30_000)
+          setInterval(() => {
+            void runQuotaWatch().catch((err) => {
+              process.stderr.write(`telegram gateway: quota-watch scheduled run failed: ${err}\n`)
+            })
+          }, QUOTA_WATCH_POLL_MS).unref()
+        }
+
         // Restart-watchdog: poll systemd's NRestarts for the agent unit.
         // When the count ticks up without a corresponding restart-pending
         // marker (= user-initiated /restart), emit an operator event.

package/telegram-plugin/operator-events.ts

@@ -257,16 +257,12 @@ export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
         text: [
           `💳 <b>Credit balance too low</b> for <b>${agent}</b>.`,
           detail ? `<i>${detail}</i>` : '',
-          `Swap to another account slot or add a new one.`,
+          `Use <code>/auth use &lt;label&gt;</code> to switch account slot or <code>/auth add</code> to add one.`,
         ]
           .filter(Boolean)
           .join('\n'),
         keyboard: {
           inline_keyboard: [
-            [
-              { text: '🔄 Swap slot', callback_data: `op:swap-slot:${encodeURIComponent(ev.agent)}` },
-              { text: '➕ Add slot', callback_data: `op:add-slot:${encodeURIComponent(ev.agent)}` },
-            ],
             [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
           ],
         },
@@ -280,16 +276,12 @@ export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
         text: [
           `⚠️ <b>Quota exhausted</b> for <b>${agent}</b>.`,
           detail ? `<i>${detail}</i>` : '',
-          `All account slots are at the usage limit. Switchroom will auto-fallback when another slot is available.`,
+          `All account slots are at the usage limit. Switchroom will auto-fallback when another slot is available. Use <code>/auth use &lt;label&gt;</code> to switch manually.`,
         ]
           .filter(Boolean)
           .join('\n'),
         keyboard: {
           inline_keyboard: [
-            [
-              { text: '🔄 Swap slot', callback_data: `op:swap-slot:${encodeURIComponent(ev.agent)}` },
-              { text: '➕ Add slot', callback_data: `op:add-slot:${encodeURIComponent(ev.agent)}` },
-            ],
             [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
           ],
         },