switchroom 0.13.9 → 0.13.10

package/telegram-plugin/gateway/gateway.ts

@@ -281,6 +281,7 @@ import {
   buildVaultSaveFailedInbound,
   buildVaultSaveDiscardedInbound,
 } from './vault-grant-inbound-builders.js'
+import { buildSubagentHandbackInbound } from './subagent-handback-inbound-builder.js'
 import { createPollHealthCheck, type PollHealthCheckHandle } from './poll-health.js'
 import type {
   ToolCallMessage,
@@ -3438,11 +3439,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 +3773,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 +12817,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 +15047,38 @@ 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 = ''
+              // 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 }) => {
+                if (process.env.SWITCHROOM_SUBAGENT_HANDBACK === '0') return
+                if (outcome !== 'completed' && outcome !== 'failed') return
+
                 let chatId = ''
                 let isBackground = false
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
                   for (const f of fleets) {
                     if (f.fleet.has(agentId)) {
-                      parentTurnKey = f.turnKey
                       chatId = 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 below.
                 }
                 if (turnsDb != null) {
                   try {
@@ -14925,15 +15088,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
+                if (!isBackground) return
+
+                // chatId fallback: if the progress-driver fleet entry was
+                // already cleaned up by the time onFinish fires, route to
+                // the owner chat. Every switchroom fleet agent is
+                // DM-shaped, so allowFrom[0] is the conversation that
+                // dispatched the work.
+                const handbackChatId = chatId || (loadAccess().allowFrom[0] ?? '')
+                if (!handbackChatId) {
+                  process.stderr.write(
+                    `telegram gateway: subagent-handback ${agentId} — no chat to deliver to; skipped\n`,
+                  )
+                  return
+                }
+
+                const inbound = buildSubagentHandbackInbound({
+                  ctx: {
+                    chatId: String(handbackChatId),
+                    taskDescription: description,
+                    resultText,
+                    outcome,
+                  },
+                })
+                // 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 ?? '', inbound)
+                process.stderr.write(
+                  `telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${handbackChatId} 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

package/telegram-plugin/gateway/subagent-handback-inbound-builder.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure builder for the synthetic `subagent_handback` inbound the gateway
+ * injects when a *background* sub-agent (worker / researcher) finishes.
+ *
+ * Why this exists (conversational-pacing beat 4 — the handback):
+ * A foreground sub-agent hands its result straight back as the `Task`
+ * tool result, in the parent's own turn — the model sees it in-context.
+ * A background sub-agent does not: it finishes decoupled from any turn
+ * boundary, and when it completes the parent agent is typically idle
+ * with no turn in flight to receive the result. Claude Code surfaces a
+ * background result only on the parent's *next* turn — for a Telegram
+ * agent that means the user must send another message before they ever
+ * hear back. The agent never proactively says "the worker's done".
+ *
+ * This builder produces the InboundMessage that closes that gap. The
+ * gateway's subagent-watcher `onFinish` callback (which already knows
+ * the moment a background sub-agent terminates) feeds the worker's
+ * result text in here; the gateway delivers the envelope through the
+ * same idle-drain path cron and vault-grant wake-ups use. The model
+ * wakes, sees `<channel source="subagent_handback">`, and synthesises a
+ * user-facing handback in its own voice — beat 4 made deterministic.
+ *
+ * Shape contract (mirrors `vault-grant-inbound-builders.ts`): the
+ * `meta.source` string is load-bearing — the MCP channel notification
+ * wraps it as `<channel source="subagent_handback">`. A regression that
+ * changes the source string or drops a meta field silently breaks the
+ * wake-up. Pinned by `subagent-handback-inbound-builder.test.ts`.
+ */
+
+import type { InboundMessage } from './ipc-protocol.js'
+
+/** Cap on the worker result text carried in the inbound. The model
+ *  synthesises a fresh handback from it — the full transcript is never
+ *  needed, and an unbounded paste bloats the parent's context. */
+export const HANDBACK_RESULT_MAX = 3000
+/** Cap on the dispatch-time task description echoed back for context. */
+export const HANDBACK_DESC_MAX = 200
+
+export interface SubagentHandbackContext {
+  /** Telegram chat the work was dispatched from — the synthesized
+   *  handback turn lands here so it stays with the conversation. */
+  chatId: string
+  /** Dispatch-time task description (the sub-agent's `description`). */
+  taskDescription: string
+  /** The worker's final result text — its last narrative emission
+   *  before terminating. May be empty if the watcher never observed a
+   *  text line (rare: a worker that only ran tools then exited). */
+  resultText: string
+  /** Terminal outcome as classified by the watcher. */
+  outcome: 'completed' | 'failed'
+}
+
+function truncate(s: string, max: number): string {
+  const t = s.trim()
+  return t.length > max ? t.slice(0, max) + '…' : t
+}
+
+/**
+ * Build the synthetic InboundMessage for a finished background
+ * sub-agent. Deterministic under a fixed `nowMs` for tests.
+ */
+export function buildSubagentHandbackInbound(opts: {
+  ctx: SubagentHandbackContext
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  const desc = truncate(opts.ctx.taskDescription, HANDBACK_DESC_MAX) || '(no description)'
+  const result = truncate(opts.ctx.resultText, HANDBACK_RESULT_MAX)
+
+  const text =
+    opts.ctx.outcome === 'failed'
+      ? `🤝 A background worker you dispatched has FAILED.\n\n` +
+        `Task: ${desc}\n\n` +
+        (result ? `What it reported before failing:\n${result}\n\n` : '') +
+        `This is beat 4 — the handback. Tell the user plainly that the ` +
+        `delegated work did not complete, what is known, and your ` +
+        `recommended next step — one \`reply\` in your own voice. Do not ` +
+        `stay silent.`
+      : `🤝 A background worker you dispatched has finished.\n\n` +
+        `Task: ${desc}\n\n` +
+        (result
+          ? `What the worker reported:\n${result}\n\n`
+          : `The worker left no summary text.\n\n`) +
+        `This is beat 4 — the handback. Synthesise this for the user ` +
+        `now: one \`reply\` in your own voice covering what the worker ` +
+        `found and your recommended next step. Do NOT paste the raw ` +
+        `report and do NOT stay silent — the user dispatched this and ` +
+        `is waiting to hear back.`
+
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chatId,
+    messageId: ts, // synthetic — no Telegram message id exists
+    user: 'subagent-watcher',
+    userId: 0,
+    ts,
+    text,
+    meta: {
+      source: 'subagent_handback',
+      outcome: opts.ctx.outcome,
+    },
+  }
+}