switchroom 0.13.53 → 0.13.55

package/telegram-plugin/gateway/gateway.ts

@@ -265,6 +265,7 @@ import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
 
 import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js'
 import { handleRequestDriveApproval } from './drive-write-approval.js'
+import { handleRequestMs365Approval } from './ms365-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
 import { createInboundSpool } from './inbound-spool.js'
@@ -2999,8 +3000,18 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     return
   }
 
+  // PR4b emitter sweep: supergroup-mode agents route operator-event
+  // cards (boot crash, restart-watchdog, model-unavailable, etc.) into
+  // the alerts/admin alias topic instead of chat-root. The
+  // 'compact-watchdog' kind covers all system-initiated notifications
+  // — alerts alias → default_topic_id fallback (see router contract).
+  // Fleet-shared / DM agents see `undefined` → no `message_thread_id`
+  // is added to the broadcast opts → behavior unchanged.
+  const opEventTopic = resolveAgentOutboundTopic({ kind: 'compact-watchdog' })
+
   process.stderr.write(
-    `telegram gateway: operator-event posting agent=${agent} kind=${kind} to ${access.allowFrom.length} chat(s)\n`,
+    `telegram gateway: operator-event posting agent=${agent} kind=${kind} to ${access.allowFrom.length} chat(s)` +
+      (opEventTopic != null ? ` topic=${opEventTopic}` : '') + '\n',
   )
   for (const chat_id of access.allowFrom) {
     // grammy's Other<...> opts type is generated and stricter than our
@@ -3008,8 +3019,12 @@ function emitGatewayOperatorEvent(event: OperatorEvent): void {
     const opts = {
       parse_mode: 'HTML' as const,
       ...(renderedKeyboard ? { reply_markup: renderedKeyboard } : {}),
+      ...(opEventTopic != null ? { message_thread_id: opEventTopic } : {}),
     }
-    // allow-raw-bot-api: operator-event broadcast loop; opts has no message_thread_id
+    // Comment-only context for the reader; the lint marker on the
+    // very next line is what unlocks the raw bot.api call.
+    // Opts now includes message_thread_id when supergroup mode is on.
+    // allow-raw-bot-api: operator-event broadcast loop; topic-aware opts
     void bot.api.sendMessage(chat_id, renderedText, opts as never).catch(e => {
       process.stderr.write(
         `telegram gateway: operator-event send to ${chat_id} failed agent=${agent} kind=${kind}: ${e}\n`,
@@ -4009,13 +4024,36 @@ const ipcServer: IpcServer = createIpcServer({
         .row()
         .text(`🔁 Always allow ${alwaysRule.label}`, `perm:always:${requestId}`)
     }
+    // PR4b emitter sweep — supergroup-mode permission card routing.
+    // Per CPO #3 the design is "turn-initiated requests follow the
+    // conversation topic; background requests go to admin alias."
+    // Permission requests come from the bridge mid-tool-use, so they
+    // are always turn-initiated in practice — the currently active
+    // turn's sessionThreadId is the originating topic. Fall back to
+    // admin alias when no active turn (cron / background path).
+    // Fleet-shared / DM agents see `undefined` → no
+    // `message_thread_id` is added → behavior unchanged.
+    // currentTurn is the singleton "claude is currently on this turn"
+    // pointer — per Framing 1 / PR3b scope-discovery, claude
+    // serializes so there's exactly one (or zero) active turn at any
+    // moment. When set, the permission request is in-flight for that
+    // turn and follows the originating topic.
+    const activeTurn = currentTurn
+    const permTopic = resolveAgentOutboundTopic({
+      kind: 'permission',
+      turnInitiated: activeTurn != null,
+      originThreadId: activeTurn?.sessionThreadId,
+    })
     for (const chat_id of access.allowFrom) {
       // parse_mode=HTML pairs with formatPermissionCardBody (#1790)
       // so the <b>/<i> tags render as formatting.
-      // allow-raw-bot-api: permission-request keyboard fan-out; reply_markup + parse_mode only, no thread_id
+      // PR4b emitter sweep — opts now optionally carries
+      // message_thread_id when supergroup mode is on.
+      // allow-raw-bot-api: permission-request keyboard fan-out; topic-aware opts
       void bot.api.sendMessage(chat_id, text, {
         parse_mode: 'HTML',
         reply_markup: keyboard,
+        ...(permTopic != null ? { message_thread_id: permTopic } : {}),
       }).catch(e => {
         process.stderr.write(`telegram gateway: permission_request send to ${chat_id} failed: ${e}\n`)
       })
@@ -4138,7 +4176,18 @@ const ipcServer: IpcServer = createIpcServer({
         // routing surface (see how /folders posts) — this picks the
         // DM path which is the common case; group-routing follow-up
         // can extend this.
-        return { chatId: operator }
+        // PR4b emitter sweep — supergroup-mode adds an explicit
+        // topic. Drive approval cards follow the originating turn
+        // (operator-initiated tool call), admin alias fallback.
+        const activeTurn = currentTurn
+        const driveTopic = resolveAgentOutboundTopic({
+          kind: 'hostd-approval',
+          originThreadId: activeTurn?.sessionThreadId,
+        })
+        return {
+          chatId: operator,
+          ...(driveTopic != null ? { threadId: driveTopic } : {}),
+        }
       },
       registerApproval: async (args) => {
         const r = await kernelApprovalRequest({
@@ -4186,6 +4235,76 @@ const ipcServer: IpcServer = createIpcServer({
     })
   },
 
+  /**
+   * RFC #1873 §8 — MS-365 write approval card. Mirrors
+   * onRequestDriveApproval but with the weak-metadata v1 preview shape
+   * (no diff-preview — just plain text card).
+   */
+  async onRequestMs365Approval(client: IpcClient, msg) {
+    await handleRequestMs365Approval(client, msg, {
+      agentName: getMyAgentName(),
+      loadAllowFrom: () => loadAccess().allowFrom,
+      loadTargetChat: () => {
+        const access = loadAccess()
+        const operator = access.allowFrom[0]
+        if (operator === undefined) return null
+        // PR4b emitter sweep — MS365 write approval cards route into
+        // the originating turn's topic in supergroup mode, admin
+        // alias fallback for background cases. Same shape as hostd /
+        // drive approvals below.
+        const activeTurn = currentTurn
+        const ms365Topic = resolveAgentOutboundTopic({
+          kind: 'hostd-approval',
+          originThreadId: activeTurn?.sessionThreadId,
+        })
+        return {
+          chatId: operator,
+          ...(ms365Topic != null ? { threadId: ms365Topic } : {}),
+        }
+      },
+      registerApproval: async (args) => {
+        const r = await kernelApprovalRequest({
+          agent_unit: args.agent_unit,
+          scope: args.scope,
+          action: args.action,
+          approver_set: args.approver_set,
+          why: args.why,
+          ttl_ms: args.ttl_ms,
+        })
+        if (r === null || r.state === 'rate_limited') return null
+        return {
+          request_id: r.request_id,
+          expires_at_ms: r.expires_at,
+        }
+      },
+      postCard: async (args) => {
+        try {
+          const sent = await robustApiCall(
+            () =>
+              bot.api.sendMessage(args.chatId, args.text, {
+                ...(args.threadId !== undefined
+                  ? { message_thread_id: args.threadId }
+                  : {}),
+                reply_markup: args.replyMarkup as never,
+              }),
+            {
+              chat_id: String(args.chatId),
+              verb: 'ms365-approval-card',
+              ...(args.threadId !== undefined ? { threadId: args.threadId } : {}),
+            },
+          )
+          return { messageId: (sent as { message_id: number }).message_id }
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: ms365-approval postCard failed: ${(err as Error).message}\n`,
+          )
+          return null
+        }
+      },
+      log: (m) => process.stderr.write(`telegram gateway: ms365-approval — ${m}\n`),
+    })
+  },
+
   /**
    * #1623 — hostd-initiated config-edit approval card. hostd posts a
    * `request_config_approval` message; we render the card via
@@ -4206,7 +4325,21 @@ const ipcServer: IpcServer = createIpcServer({
         const access = loadAccess()
         const operator = access.allowFrom[0]
         if (operator === undefined) return null
-        return { chatId: operator }
+        // PR4b emitter sweep — hostd config-approval cards are
+        // operator-initiated (someone typed /update apply or tapped
+        // a button). Follow the originating turn when there is one;
+        // admin alias fallback in supergroup mode otherwise. Helper
+        // returns undefined for non-supergroup agents → behavior
+        // unchanged.
+        const activeTurn = currentTurn
+        const cfgTopic = resolveAgentOutboundTopic({
+          kind: 'hostd-approval',
+          originThreadId: activeTurn?.sessionThreadId,
+        })
+        return {
+          chatId: operator,
+          ...(cfgTopic != null ? { threadId: cfgTopic } : {}),
+        }
       },
       buildKeyboard: (requestId) =>
         new InlineKeyboard()
@@ -9156,10 +9289,26 @@ type SwitchroomReplyMarkup =
 async function switchroomReply(
   ctx: Context,
   text: string,
-  options: { html?: boolean; reply_markup?: SwitchroomReplyMarkup } = {},
+  options: {
+    html?: boolean
+    reply_markup?: SwitchroomReplyMarkup
+    // PR5 — supergroup-mode slash-command smart split (CPO #4).
+    // 'query' (default semantics) follows the originating topic;
+    // 'mutation' and 'heavy' route to admin alias in supergroup mode;
+    // omitted/undefined preserves legacy in-place reply behavior.
+    classification?: 'query' | 'mutation' | 'heavy'
+  } = {},
 ): Promise<void> {
   const chatId = String(ctx.chat!.id)
-  const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+  const baseThreadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+  // PR5 — when caller flagged the reply as mutation/heavy AND we're
+  // in supergroup mode, override the in-place thread with the
+  // admin-alias topic. For 'query' (or non-supergroup), routedOpts
+  // is `{}` and baseThreadId wins → behavior unchanged.
+  const routedOpts = options.classification
+    ? slashCommandReplyOpts(ctx, options.classification)
+    : {}
+  const threadId = routedOpts.message_thread_id ?? baseThreadId
   await ctx.reply(text, {
     ...(threadId != null ? { message_thread_id: threadId } : {}),
     ...(options.html ? { parse_mode: 'HTML' as const, link_preview_options: { is_disabled: true } } : {}),
@@ -9469,6 +9618,53 @@ function resolveSystemdRunPath(): string | null {
   return _systemdRunPath
 }
 
+/**
+ * PR5 — supergroup-mode slash-command smart split (CPO #4 design).
+ *
+ * Classifies a slash-command response by event class and returns the
+ * `message_thread_id` an outbound reply should target in supergroup
+ * mode, or `undefined` when the agent isn't in supergroup-owned mode
+ * (caller falls through to grammY's default `ctx.reply` which
+ * routes to the originating topic).
+ *
+ * Three classes:
+ *   - `query` (`/help`, `/status`, etc.) — follows the originating
+ *     topic, identical to default `ctx.reply` behaviour.
+ *   - `mutation` (`/restart`, `/update apply`) — admin alias.
+ *   - `heavy` (`/logs`, `/audit`, `/upgradestatus`, `/memory <q>`)
+ *     — admin alias (operational separation per CPO #4).
+ *
+ * Callers spread the returned topic onto their send opts:
+ *
+ *   await ctx.reply(text, {
+ *     ...opts,
+ *     ...slashCommandReplyOpts(ctx, 'heavy'),
+ *   })
+ *
+ * Returns `{}` when no override is needed (non-supergroup, or
+ * helper resolved to the originating topic). Returns
+ * `{ message_thread_id: N }` otherwise.
+ */
+function slashCommandReplyOpts(
+  ctx: Context,
+  classification: 'query' | 'mutation' | 'heavy',
+): { message_thread_id?: number } {
+  const originThreadId = ctx.message?.message_thread_id
+  const event =
+    classification === 'query'
+      ? ({ kind: 'command-query', originThreadId } as const)
+      : classification === 'mutation'
+        ? ({ kind: 'command-mutation' } as const)
+        : ({ kind: 'command-heavy' } as const)
+  const target = resolveAgentOutboundTopic(event)
+  if (target == null) return {}
+  // Avoid the spurious explicit thread_id when it would equal the
+  // implicit-reply destination — keeps the wire identical to default
+  // ctx.reply for the query class in supergroup mode.
+  if (target === originThreadId) return {}
+  return { message_thread_id: target }
+}
+
 /**
  * Detect whether `docker` is callable from this process — required by
  * `switchroom update`'s pull-images and recreate-containers steps.
@@ -9920,18 +10116,27 @@ async function dispatchShortVerbViaHostd(
   )
 }
 
-async function runSwitchroomCommand(ctx: Context, args: string[], label: string): Promise<void> {
+async function runSwitchroomCommand(
+  ctx: Context,
+  args: string[],
+  label: string,
+  // PR5 — supergroup-mode classification threaded through to
+  // switchroomReply. Default 'query' so existing callers (most
+  // commands) preserve in-place reply behavior. /logs /audit
+  // /upgradestatus /memory pass 'heavy' to route to admin alias.
+  classification: 'query' | 'mutation' | 'heavy' = 'query',
+): Promise<void> {
   try {
     const output = stripAnsi(switchroomExec(args))
     const formatted = formatSwitchroomOutput(output)
-    if (formatted) { await switchroomReply(ctx, preBlock(formatted), { html: true }) }
-    else { await switchroomReply(ctx, `${label}: done (no output)`) }
+    if (formatted) { await switchroomReply(ctx, preBlock(formatted), { html: true, classification }) }
+    else { await switchroomReply(ctx, `${label}: done (no output)`, { classification }) }
   } catch (err: unknown) {
     const error = err as { status?: number; stderr?: string; message?: string }
-    if (error.message?.includes('ENOENT')) { await switchroomReply(ctx, 'switchroom CLI not found.', { html: true }); return }
-    if (error.message?.includes('ETIMEDOUT') || error.message?.includes('timed out')) { await switchroomReply(ctx, `${label}: timed out`); return }
+    if (error.message?.includes('ENOENT')) { await switchroomReply(ctx, 'switchroom CLI not found.', { html: true, classification }); return }
+    if (error.message?.includes('ETIMEDOUT') || error.message?.includes('timed out')) { await switchroomReply(ctx, `${label}: timed out`, { classification }); return }
     const detail = stripAnsi(error.stderr?.trim() || error.message || 'unknown error')
-    await switchroomReply(ctx, `<b>${escapeHtmlForTg(label)} failed:</b>\n${preBlock(formatSwitchroomOutput(detail))}`, { html: true })
+    await switchroomReply(ctx, `<b>${escapeHtmlForTg(label)} failed:</b>\n${preBlock(formatSwitchroomOutput(detail))}`, { html: true, classification })
   }
 }
 
@@ -10896,7 +11101,9 @@ bot.command('update', async ctx => {
 // /upgrade-status. The /upgrade alias just below redirects.)
 bot.command('upgradestatus', async ctx => {
   if (!isAuthorizedSender(ctx)) return
-  await runSwitchroomCommand(ctx, ['update', '--status'], 'update --status')
+  // PR5 — heavy-output: route to admin alias in supergroup mode
+  // (CPO #4). Fleet-shared / DM agents fall through to in-place reply.
+  await runSwitchroomCommand(ctx, ['update', '--status'], 'update --status', 'heavy')
 })
 // Alias with hyphen — Grammy doesn't allow hyphens in command names
 // (Telegram's slash-command grammar excludes them) but operators are
@@ -10984,7 +11191,8 @@ bot.command('audit', async ctx => {
     )
     return
   }
-  await runSwitchroomCommand(ctx, argv, `hostd audit${argv.length > 2 ? ' …' : ''}`)
+  // PR5 — heavy-output → admin alias in supergroup mode (CPO #4).
+  await runSwitchroomCommand(ctx, argv, `hostd audit${argv.length > 2 ? ' …' : ''}`, 'heavy')
 })
 
 // ─── /approve, /deny, /pending ────────────────────────────────────────────
@@ -13766,14 +13974,16 @@ bot.command('logs', async ctx => {
   try { assertSafeAgentName(name) } catch { await switchroomReply(ctx, 'Invalid agent name.'); return }
   const lines = linesArg ? parseInt(linesArg, 10) : 20
   const lineCount = isNaN(lines) || lines < 1 ? 20 : Math.min(lines, 200)
-  await runSwitchroomCommand(ctx, ['agent', 'logs', name, '--lines', String(lineCount)], `logs ${name}`)
+  // PR5 — heavy-output → admin alias in supergroup mode (CPO #4).
+  await runSwitchroomCommand(ctx, ['agent', 'logs', name, '--lines', String(lineCount)], `logs ${name}`, 'heavy')
 })
 
 bot.command('memory', async ctx => {
   if (!isAuthorizedSender(ctx)) return
   const query = ctx.match?.trim()
   if (!query) { await switchroomReply(ctx, 'Usage: /memory <search query>'); return }
-  await runSwitchroomCommand(ctx, ['memory', 'search', query], 'memory search')
+  // PR5 — heavy-output → admin alias in supergroup mode (CPO #4).
+  await runSwitchroomCommand(ctx, ['memory', 'search', query], 'memory search', 'heavy')
 })
 
 bot.command('issues', async ctx => {

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

@@ -127,6 +127,7 @@ export type GatewayToClient =
   | ToolCallResult
   | ScheduleRestartResult
   | DriveApprovalPostedEvent
+  | Ms365ApprovalPostedEvent
   | ConfigApprovalResolvedEvent;
 
 // === Bridge (Client) -> Gateway messages ===
@@ -306,6 +307,41 @@ export interface RequestDriveApprovalMessage {
   ttlMs?: number;
 }
 
+/**
+ * RFC #1873 §8 — Microsoft 365 write approval (PR 4).
+ *
+ * Sent by the `ms-365-write-pretool` PreToolUse hook when softeria
+ * tries a gated write tool (OneDrive upload, calendar/mail mutations).
+ * Same shape as `request_drive_approval` but carries the weak-metadata
+ * v1 preview shape (file path / id / size delta / deep link / agent
+ * rationale) rather than Google's full DiffPreviewInput. Structural-
+ * diff preview is RFC §8 v1.5.
+ */
+export interface RequestMs365ApprovalMessage {
+  type: "request_ms365_approval";
+  correlationId: string;
+  agentName: string;
+  /**
+   * Weak-metadata payload — see Ms365WritePreview in
+   * `telegram-plugin/gateway/ms365-write-approval.ts`. Opaque on the
+   * wire; gateway validates via the handler.
+   */
+  preview: Record<string, unknown>;
+  ttlMs?: number;
+}
+
+/**
+ * Gateway → hook response after card is posted (or fails).
+ */
+export interface Ms365ApprovalPostedEvent {
+  type: "ms365_approval_posted";
+  correlationId: string;
+  ok: boolean;
+  requestId?: string;
+  expiresAtMs?: number;
+  reason?: string;
+}
+
 /**
  * hostd config-edit approval — sent by hostd to the caller agent's
  * gateway to render an approval card with the full unified diff in
@@ -367,5 +403,6 @@ export type ClientToGateway =
   | UpdatePlaceholderMessage
   | InjectInboundMessage
   | RequestDriveApprovalMessage
+  | RequestMs365ApprovalMessage
   | RequestConfigApprovalMessage
   | RequestConfigFinalizeMessage;

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

@@ -11,6 +11,7 @@ import type {
   RequestConfigApprovalMessage,
   RequestConfigFinalizeMessage,
   RequestDriveApprovalMessage,
+  RequestMs365ApprovalMessage,
   ScheduleRestartMessage,
   SessionEventForward,
   ToolCallMessage,
@@ -55,6 +56,15 @@ export interface IpcServerOptions {
     client: IpcClient,
     msg: RequestDriveApprovalMessage,
   ) => Promise<void>;
+  /**
+   * RFC #1873 §8 — Microsoft 365 write approval (PR 4). Same shape as
+   * onRequestDriveApproval but for softeria write tools. Optional;
+   * gateways without M365 integration ignore.
+   */
+  onRequestMs365Approval?: (
+    client: IpcClient,
+    msg: RequestMs365ApprovalMessage,
+  ) => Promise<void>;
   /**
    * #1623 — hostd-initiated config-edit approval card. Handler posts
    * a Telegram card with [✅ Approve] [🚫 Deny] buttons, tracks the
@@ -273,6 +283,22 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
           || (m.ttlMs as number) < 0)) return false;
       return true;
     }
+    case "request_ms365_approval": {
+      // RFC #1873 §8 PR 4. Same wire-shape gate as Drive — gateway
+      // routes on the outer fields; the inner `preview` is opaque
+      // and re-validated by `validateMs365Preview()` downstream.
+      if (typeof m.correlationId !== "string"
+        || (m.correlationId as string).length === 0
+        || (m.correlationId as string).length > 64) return false;
+      if (typeof m.agentName !== "string"
+        || !AGENT_NAME_RE.test(m.agentName as string)) return false;
+      if (typeof m.preview !== "object" || m.preview === null) return false;
+      if (m.ttlMs !== undefined
+        && (typeof m.ttlMs !== "number"
+          || !Number.isFinite(m.ttlMs)
+          || (m.ttlMs as number) < 0)) return false;
+      return true;
+    }
     default:
       return false;
   }
@@ -292,6 +318,7 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onPtyPartial,
     onInjectInbound,
     onRequestDriveApproval,
+    onRequestMs365Approval,
     onRequestConfigApproval,
     onRequestConfigFinalize,
     log = () => {},
@@ -436,6 +463,38 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
           }
         }
         break;
+      case "request_ms365_approval":
+        if (onRequestMs365Approval) {
+          onRequestMs365Approval(client, msg as RequestMs365ApprovalMessage).catch(
+            (err) => {
+              log(
+                `request_ms365_approval handler threw (client=${client.id}): ${(err as Error).message}`,
+              );
+              try {
+                client.send({
+                  type: "ms365_approval_posted",
+                  correlationId: (msg as RequestMs365ApprovalMessage).correlationId,
+                  ok: false,
+                  reason: `gateway handler error: ${(err as Error).message}`,
+                });
+              } catch {
+                /* best effort */
+              }
+            },
+          );
+        } else {
+          try {
+            client.send({
+              type: "ms365_approval_posted",
+              correlationId: (msg as RequestMs365ApprovalMessage).correlationId,
+              ok: false,
+              reason: "gateway not configured for MS-365 write approval",
+            });
+          } catch {
+            /* best effort */
+          }
+        }
+        break;
       case "request_config_approval":
         if (onRequestConfigApproval) {
           onRequestConfigApproval(