switchroom 0.13.9 → 0.13.11

package/telegram-plugin/gateway/gateway.ts

@@ -281,6 +281,7 @@ import {
   buildVaultSaveFailedInbound,
   buildVaultSaveDiscardedInbound,
 } from './vault-grant-inbound-builders.js'
+import { decideSubagentHandback } from './subagent-handback-inbound-builder.js'
 import { createPollHealthCheck, type PollHealthCheckHandle } from './poll-health.js'
 import type {
   ToolCallMessage,
@@ -2711,8 +2712,14 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     // Card text branches on the AND. wouldFireFleetAutoFallback is a
     // pure read of the dedup state; calling fireFleetAutoFallback only
     // when both are true keeps the card honest.
-    const isAutoKind =
-      modelUnavailable.kind === 'quota_exhausted' || modelUnavailable.kind === 'overload'
+    // Only a genuine quota / usage-limit hit is addressable by fleet
+    // auto-fallback (swap to an account that still has runway). An
+    // `overload` is transient Anthropic SERVER-side capacity pressure —
+    // every account is equally affected, so failing over does nothing;
+    // it just produces a self-cancelling "probed healthy / Stale event?"
+    // loop on every 529. Overload is handled by Claude Code's own
+    // internal retry, not by switching accounts.
+    const isAutoKind = modelUnavailable.kind === 'quota_exhausted'
     const willActuallyFire = isAutoKind && wouldFireFleetAutoFallback()
     process.stderr.write(
       `telegram gateway: operator-event suppressing-raw-stderr-for-model-unavailable agent=${agent} kind=${kind} detected=${modelUnavailable.kind} autoKind=${isAutoKind} willFire=${willActuallyFire}\n`,
@@ -3438,11 +3445,15 @@ const ipcServer: IpcServer = createIpcServer({
   },
 
   onClientDisconnected(client: IpcClient) {
-    process.stderr.write(`telegram gateway: bridge disconnected — agent=${client.agentName}\n`)
-    // Phase 2b shadow: ONLY emit bridgeDown for the REAL bridge sidecar
-    // (matching the bridgeUp gate above). Anonymous IPC clients
-    // disconnect frequently — those are not bridge flaps.
+    // ONLY log "bridge disconnected" + emit bridgeDown for the REAL
+    // bridge sidecar (matching the bridgeUp gate above). Anonymous IPC
+    // clients — e.g. recall.py's one-shot legacy update_placeholder
+    // handshake — connect and disconnect constantly with agentName=null;
+    // logging those as "bridge disconnected — agent=null" reads as a
+    // bridge flap in the supervisor log when nothing flapped. The
+    // anonymous disconnect is still traced by disconnect-flush.ts.
     if (client.agentName != null) {
+      process.stderr.write(`telegram gateway: bridge disconnected — agent=${client.agentName}\n`)
       shadowEmit({ kind: 'bridgeDown', at: Date.now() })
     }
 
@@ -3768,6 +3779,102 @@ const ipcServer: IpcServer = createIpcServer({
     })
   },
 
+  /**
+   * #1623 — hostd-initiated config-edit approval card. hostd posts a
+   * `request_config_approval` message; we render the card via
+   * `handleRequestConfigApproval`, awaiting the operator tap (or
+   * timeout) before sending `config_approval_resolved` back. After
+   * hostd's apply attempt completes it posts
+   * `request_config_finalize` to flip the card to the terminal
+   * outcome.
+   */
+  async onRequestConfigApproval(client: IpcClient, msg) {
+    const { handleRequestConfigApproval } = await import(
+      './config-approval-handler.js'
+    )
+    const { InlineKeyboard } = await import('grammy')
+    await handleRequestConfigApproval(client, msg, {
+      agentName: getMyAgentName(),
+      loadTargetChat: () => {
+        const access = loadAccess()
+        const operator = access.allowFrom[0]
+        if (operator === undefined) return null
+        return { chatId: operator }
+      },
+      buildKeyboard: (requestId) =>
+        new InlineKeyboard()
+          .text('✅ Approve', `cfg:${requestId}:approve`)
+          .text('🚫 Deny', `cfg:${requestId}:deny`),
+      postCard: async (args) => {
+        try {
+          const sent = await robustApiCall(
+            () =>
+              bot.api.sendMessage(args.chatId, args.text, {
+                parse_mode: 'HTML',
+                ...(args.threadId !== undefined
+                  ? { message_thread_id: args.threadId }
+                  : {}),
+                reply_markup: args.replyMarkup as never,
+              }),
+            {
+              chat_id: String(args.chatId),
+              verb: 'config-approval-card',
+              ...(args.threadId !== undefined ? { threadId: args.threadId } : {}),
+            },
+          )
+          return { messageId: (sent as { message_id: number }).message_id }
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: config-approval postCard failed: ${(err as Error).message}\n`,
+          )
+          return null
+        }
+      },
+      editCard: async (args) => {
+        try {
+          await robustApiCall(
+            () =>
+              bot.api.editMessageText(args.chatId, args.messageId, args.text, {
+                parse_mode: 'HTML',
+              }),
+            { chat_id: String(args.chatId), verb: 'config-approval-edit' },
+          )
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: config-approval editCard failed: ${(err as Error).message}\n`,
+          )
+        }
+      },
+      log: (m) =>
+        process.stderr.write(`telegram gateway: config-approval — ${m}\n`),
+    })
+  },
+
+  async onRequestConfigFinalize(client: IpcClient, msg) {
+    const { handleRequestConfigFinalize } = await import(
+      './config-approval-handler.js'
+    )
+    await handleRequestConfigFinalize(client, msg, {
+      editCard: async (args) => {
+        try {
+          await robustApiCall(
+            () =>
+              bot.api.editMessageText(args.chatId, args.messageId, args.text, {
+                parse_mode: 'HTML',
+              }),
+            { chat_id: String(args.chatId), verb: 'config-approval-finalize' },
+          )
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: config-finalize editCard failed: ${(err as Error).message}\n`,
+          )
+        }
+      },
+      log: (m) =>
+        process.stderr.write(`telegram gateway: config-finalize — ${m}\n`),
+    })
+  },
+
   onInjectInbound(_client: IpcClient, msg: InjectInboundMessage) {
     const promptKey = typeof msg.inbound.meta?.prompt_key === 'string'
       ? msg.inbound.meta.prompt_key
@@ -12716,6 +12823,55 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // #1623: cfg:<requestId>:<approve|deny> — hostd config-edit
+  // approval card. Resolves the pending approval (gateway-side
+  // in-memory map), sends `config_approval_resolved` back to hostd
+  // over the original IPC connection, and edits the card to the
+  // interim "Applying…" / "Denied" state. Same operator-allowlist
+  // gate as every other callback family.
+  if (data.startsWith('cfg:')) {
+    const access = loadAccess()
+    const senderId = String(ctx.from?.id ?? '')
+    if (!access.allowFrom.includes(senderId)) {
+      await ctx.answerCallbackQuery({ text: 'Not authorized.' })
+      return
+    }
+    const { parseConfigApprovalCallback, resolvePendingConfigApproval } =
+      await import('./config-approval-handler.js')
+    const parsed = parseConfigApprovalCallback(data)
+    if (parsed === null) {
+      await ctx.answerCallbackQuery({ text: 'Malformed callback.' })
+      return
+    }
+    const resolved = await resolvePendingConfigApproval(
+      parsed.requestId,
+      parsed.choice,
+      {
+        editCard: async (args) => {
+          try {
+            await robustApiCall(() =>
+              bot.api.editMessageText(args.chatId, args.messageId, args.text, {
+                parse_mode: 'HTML',
+              }),
+            )
+          } catch {
+            /* best effort */
+          }
+        },
+        log: (m) =>
+          process.stderr.write(`telegram gateway: config-approval cb — ${m}\n`),
+      },
+    )
+    await ctx.answerCallbackQuery({
+      text: resolved
+        ? parsed.choice === 'approve'
+          ? 'Approving…'
+          : 'Denied'
+        : 'Already resolved.',
+    })
+    return
+  }
+
   // RFC E §4.1: drvpick:<verb>:<agent>[:<...>] — folder-picker card taps.
   // open / enter / back / refresh re-render the card in place;
   // grant writes an allow_always kernel decision at
@@ -14897,25 +15053,40 @@ void (async () => {
                   )
                 }
               },
-              // #card-audit-log: symmetric sub_agent_finished surface.
-              // The driver's per-chat shadow knows the parent turnKey and
-              // the registry DB carries the background flag — combine them
-              // into a single audit-log line for retrospective debugging.
-              onFinish: ({ agentId, outcome, toolCount, durationMs }) => {
-                let parentTurnKey = ''
-                let chatId = ''
+              // conversational-pacing beat 4 — the handback. A foreground
+              // sub-agent hands its result straight back as the Task tool
+              // result, inside the parent's own turn; the model sees it
+              // in-context. A *background* sub-agent does not — it
+              // finishes decoupled from any turn boundary, with the parent
+              // typically idle and no turn to receive the result. Without
+              // a nudge the user never hears back until they send the next
+              // message themselves. So: when a background sub-agent
+              // terminates, wake the agent with a `subagent_handback`
+              // inbound carrying the worker's result text, and let it
+              // synthesise a user-facing handback in its own voice.
+              //
+              // Gated to background completions: foreground sub-agents
+              // need nothing here, and 'orphan' is a stale historical-at-
+              // boot row, not a fresh completion the user is waiting on.
+              onFinish: ({ agentId, outcome, description, resultText }) => {
+                // IO: resolve the fleet chat id and the background flag.
+                // The DECISION (gating + inbound build) is delegated to
+                // the pure `decideSubagentHandback` so it is unit-tested
+                // independent of the gateway — see
+                // `subagent-handback-decision.test.ts`.
+                let fleetChatId = ''
                 let isBackground = false
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
                   for (const f of fleets) {
                     if (f.fleet.has(agentId)) {
-                      parentTurnKey = f.turnKey
-                      chatId = f.chatId ?? ''
+                      fleetChatId = f.chatId ?? ''
                       break
                     }
                   }
                 } catch {
-                  // peek failures are non-fatal — we still emit the event.
+                  // peek failures are non-fatal — fall through to the
+                  // owner-chat fallback inside decideSubagentHandback.
                 }
                 if (turnsDb != null) {
                   try {
@@ -14925,15 +15096,37 @@ void (async () => {
                     if (row != null) isBackground = row.background === 1
                   } catch { /* best-effort */ }
                 }
-                // #1122 PR3: card-event-log emission removed with the
-                // progress card. Sub-agent completion is now visible
-                // via the agent's own chat narration.
-                const finalOutcome: 'completed' | 'orphan' | 'background' =
-                  isBackground ? 'background' : (outcome === 'completed' ? 'completed' : 'orphan')
-                void finalOutcome
-                void parentTurnKey
-                void durationMs
-                void toolCount
+
+                const decision = decideSubagentHandback({
+                  handbackEnvValue: process.env.SWITCHROOM_SUBAGENT_HANDBACK,
+                  outcome,
+                  isBackground,
+                  fleetChatId,
+                  // Owner-chat fallback: if the progress-driver fleet
+                  // entry was already cleaned up, route to the owner
+                  // chat. Every switchroom fleet agent is DM-shaped, so
+                  // allowFrom[0] is the conversation that dispatched.
+                  ownerChatId: loadAccess().allowFrom[0] ?? '',
+                  taskDescription: description,
+                  resultText,
+                })
+                if (!decision.deliver) {
+                  if (decision.reason === 'no-chat') {
+                    process.stderr.write(
+                      `telegram gateway: subagent-handback ${agentId} — no chat to deliver to; skipped\n`,
+                    )
+                  }
+                  return
+                }
+
+                // Deliver via pendingInboundBuffer + the idle-drain tick.
+                // The drain only releases at an idle prompt (no active
+                // turn), so the handback always lands as a clean fresh
+                // turn and never races a turn-in-flight composer (#1556).
+                pendingInboundBuffer.push(process.env.SWITCHROOM_AGENT_NAME ?? '', decision.inbound)
+                process.stderr.write(
+                  `telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${decision.chatId} resultChars=${resultText.length}\n`,
+                )
               },
             })
             process.stderr.write('telegram gateway: subagent-watcher active\n')

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -93,13 +93,32 @@ export interface DriveApprovalPostedEvent {
   reason?: string;
 }
 
+/**
+ * hostd config-edit approval — sent by the gateway back to hostd
+ * after the operator taps Approve/Deny on a `request_config_approval`
+ * card (or the 10-minute timeout elapses).
+ *
+ * The gateway is the source of truth for the verdict; hostd treats
+ * this as a one-shot reply per `requestId`. Subsequent taps on the
+ * same card are ignored at the callback dispatcher (#1623, RFC §3.4).
+ */
+export interface ConfigApprovalResolvedEvent {
+  type: "config_approval_resolved";
+  /** Echoes the requestId from the originating request_config_approval. */
+  requestId: string;
+  verdict: "approve" | "deny" | "timeout";
+  /** Diagnostic detail when present (currently unused; reserved). */
+  reason?: string;
+}
+
 export type GatewayToClient =
   | InboundMessage
   | PermissionEvent
   | StatusEvent
   | ToolCallResult
   | ScheduleRestartResult
-  | DriveApprovalPostedEvent;
+  | DriveApprovalPostedEvent
+  | ConfigApprovalResolvedEvent;
 
 // === Bridge (Client) -> Gateway messages ===
 
@@ -278,6 +297,55 @@ export interface RequestDriveApprovalMessage {
   ttlMs?: number;
 }
 
+/**
+ * hostd config-edit approval — sent by hostd to the caller agent's
+ * gateway to render an approval card with the full unified diff in
+ * the operator's primary chat. The gateway:
+ *
+ *   1. Posts a Telegram card with [✅ Approve] [🚫 Deny] buttons
+ *      using callback_data `cfg:<requestId>:approve` / `:deny`.
+ *   2. Tracks the pending request in-memory (no SQLite).
+ *   3. On button tap (or 10-minute timeout) sends a single
+ *      `config_approval_resolved` event back over the same
+ *      connection.
+ *   4. After hostd reports the apply outcome via
+ *      `request_config_finalize`, edits the card body to the final
+ *      state ("✅ applied" / "⚠️ reconcile failed; rolled back" /
+ *      "🚫 denied" / "⏱ expired").
+ *
+ * Trust model: same as request_drive_approval — the gateway socket
+ * lives inside the agent container, only that-UID processes can
+ * connect. hostd reaches it via the per-agent state-dir bind mount
+ * (`<state-dir>/gateway.sock`).
+ */
+export interface RequestConfigApprovalMessage {
+  type: "request_config_approval";
+  /** Hostd-generated stable id (8-hex). Echoed in resolved/finalize. */
+  requestId: string;
+  /** Name of the admin agent that called config_propose_edit. */
+  agentName: string;
+  /** Operator-visible justification (≤500 chars). */
+  reason: string;
+  /** Full unified diff to render in a code block on the card. */
+  unifiedDiff: string;
+  /** Card timeout in milliseconds (gateway-enforced). */
+  timeoutMs: number;
+}
+
+/**
+ * Sent by hostd after the apply attempt completes (success OR
+ * rollback) so the gateway can edit the approval card body to a
+ * terminal state. Idempotent: if the card was already edited (e.g.
+ * by the timeout path), the second edit is a best-effort no-op.
+ */
+export interface RequestConfigFinalizeMessage {
+  type: "request_config_finalize";
+  requestId: string;
+  outcome: "applied" | "reconcile_failed_rolled_back";
+  /** Optional short diagnostic appended to the card body. */
+  detail?: string;
+}
+
 export type ClientToGateway =
   | RegisterMessage
   | ToolCallMessage
@@ -289,4 +357,6 @@ export type ClientToGateway =
   | PtyPartialForward
   | UpdatePlaceholderMessage
   | InjectInboundMessage
-  | RequestDriveApprovalMessage;
+  | RequestDriveApprovalMessage
+  | RequestConfigApprovalMessage
+  | RequestConfigFinalizeMessage;

package/telegram-plugin/gateway/ipc-server.ts

@@ -8,6 +8,8 @@ import type {
   PermissionRequestForward,
   PtyPartialForward,
   RegisterMessage,
+  RequestConfigApprovalMessage,
+  RequestConfigFinalizeMessage,
   RequestDriveApprovalMessage,
   ScheduleRestartMessage,
   SessionEventForward,
@@ -53,6 +55,26 @@ export interface IpcServerOptions {
     client: IpcClient,
     msg: RequestDriveApprovalMessage,
   ) => Promise<void>;
+  /**
+   * #1623 — hostd-initiated config-edit approval card. Handler posts
+   * a Telegram card with [✅ Approve] [🚫 Deny] buttons, tracks the
+   * pending request in-memory, and sends `config_approval_resolved`
+   * back over the same connection when the operator taps or the
+   * timeout fires. Optional: gateways without the hostd integration
+   * configured ignore these messages.
+   */
+  onRequestConfigApproval?: (
+    client: IpcClient,
+    msg: RequestConfigApprovalMessage,
+  ) => Promise<void>;
+  /**
+   * #1623 — hostd-initiated terminal card edit after apply completed
+   * (success OR rolled-back). Best-effort; no reply expected.
+   */
+  onRequestConfigFinalize?: (
+    client: IpcClient,
+    msg: RequestConfigFinalizeMessage,
+  ) => Promise<void>;
   log?: (msg: string) => void;
   /**
    * How long (in ms) to wait without a heartbeat before force-closing the
@@ -205,6 +227,35 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
         && typeof inb.meta === "object"
         && inb.meta !== null;
     }
+    case "request_config_approval": {
+      // #1623 — hostd-initiated config-edit approval card. Wire shape
+      // only; the handler module validates the diff content.
+      if (typeof m.requestId !== "string"
+        || (m.requestId as string).length === 0
+        || (m.requestId as string).length > 64) return false;
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.reason !== "string"
+        || (m.reason as string).length === 0
+        || (m.reason as string).length > 500) return false;
+      if (typeof m.unifiedDiff !== "string"
+        || (m.unifiedDiff as string).length === 0) return false;
+      if (typeof m.timeoutMs !== "number"
+        || !Number.isFinite(m.timeoutMs)
+        || (m.timeoutMs as number) <= 0) return false;
+      return true;
+    }
+    case "request_config_finalize": {
+      if (typeof m.requestId !== "string"
+        || (m.requestId as string).length === 0
+        || (m.requestId as string).length > 64) return false;
+      if (m.outcome !== "applied"
+        && m.outcome !== "reconcile_failed_rolled_back") return false;
+      if (m.detail !== undefined
+        && (typeof m.detail !== "string"
+          || (m.detail as string).length > 500)) return false;
+      return true;
+    }
     case "request_drive_approval": {
       // RFC E §4.2 Cut 2. Validate the wire-shaped fields the
       // gateway will route on; the inner `preview` is treated as
@@ -241,6 +292,8 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onPtyPartial,
     onInjectInbound,
     onRequestDriveApproval,
+    onRequestConfigApproval,
+    onRequestConfigFinalize,
     log = () => {},
     heartbeatTimeoutMs = 30_000,
   } = options;
@@ -383,6 +436,54 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
           }
         }
         break;
+      case "request_config_approval":
+        if (onRequestConfigApproval) {
+          onRequestConfigApproval(
+            client,
+            msg as RequestConfigApprovalMessage,
+          ).catch((err) => {
+            log(
+              `request_config_approval handler threw (client=${client.id}): ${(err as Error).message}`,
+            );
+            try {
+              client.send({
+                type: "config_approval_resolved",
+                requestId: (msg as RequestConfigApprovalMessage).requestId,
+                verdict: "deny",
+                reason: `gateway handler error: ${(err as Error).message}`,
+              });
+            } catch {
+              /* best effort */
+            }
+          });
+        } else {
+          // Fail closed — hostd treats this as deny so the apply path
+          // never runs without an operator-attested approval card.
+          try {
+            client.send({
+              type: "config_approval_resolved",
+              requestId: (msg as RequestConfigApprovalMessage).requestId,
+              verdict: "deny",
+              reason: "gateway not configured for config-edit approval",
+            });
+          } catch {
+            /* best effort */
+          }
+        }
+        break;
+      case "request_config_finalize":
+        if (onRequestConfigFinalize) {
+          onRequestConfigFinalize(
+            client,
+            msg as RequestConfigFinalizeMessage,
+          ).catch((err) => {
+            log(
+              `request_config_finalize handler threw (client=${client.id}): ${(err as Error).message}`,
+            );
+          });
+        }
+        // No reply expected.
+        break;
       case "update_placeholder":
         // Legacy recall.py IPC — placeholder UX was removed in #553 PR 5.
         // Soft-accepted so recall.py keeps working without modifying