switchroom 0.16.28 → 0.16.38

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

@@ -142,7 +142,8 @@ export type GatewayToClient =
   | ScheduleRestartResult
   | DriveApprovalPostedEvent
   | Ms365ApprovalPostedEvent
-  | ConfigApprovalResolvedEvent;
+  | ConfigApprovalResolvedEvent
+  | RolloutStatusPostedEvent;
 
 // === Bridge (Client) -> Gateway messages ===
 
@@ -493,6 +494,67 @@ export interface PostSkillProposalMessage {
   draft: Record<string, string>;
 }
 
+/**
+ * #2726 Part 1 — hostd asks the caller agent's gateway to POST one ordinary
+ * operator-DM message narrating a rollout's terminal outcome. This is a NORMAL
+ * message, NOT a pinned card and NOT a bespoke widget — the framework speaking
+ * a plain progress line in the chat, which keeps it clear of
+ * `chat-is-the-single-source-of-truth` (in-chat narration, not a parallel
+ * pinned mirror).
+ *
+ * The gateway posts `text` to the operator chat (`allowFrom[0]`) and — for the
+ * Part 2 narration surface — replies with a `rollout_status_posted` event
+ * carrying the message_id so hostd can EDIT it as later phases arrive. Part 1
+ * uses only the terminal post and ignores the reply (fire-and-forget).
+ *
+ * Trust model: same as request_config_approval — the gateway socket lives in
+ * the agent container; hostd reaches it via the per-agent state-dir bind mount.
+ * `agentName` is validated server-side; the chat target is the gateway's OWN
+ * operator, never a caller-supplied chat.
+ */
+export interface RolloutStatusPostMessage {
+  type: "rollout_status_post";
+  /** hostd request_id of the roll (binds the surface to a real request). */
+  requestId: string;
+  /** The admin agent whose gateway relays the message (the rollout caller). */
+  agentName: string;
+  /** Fully-rendered message body. */
+  text: string;
+}
+
+/**
+ * #2726 Part 2 — hostd asks the gateway to EDIT the rollout status message it
+ * previously posted (identified by `messageId`, returned in the
+ * `rollout_status_posted` reply). Best-effort, fire-and-forget: an edit failure
+ * (incl. Telegram 429) is handled gateway-side and never surfaced back toward
+ * the roll.
+ */
+export interface RolloutStatusEditMessage {
+  type: "rollout_status_edit";
+  requestId: string;
+  agentName: string;
+  /** message_id of the status message to edit (from rollout_status_posted). */
+  messageId: number;
+  /** New fully-rendered body. */
+  text: string;
+}
+
+/**
+ * #2726 — gateway → hostd reply after a `rollout_status_post` was posted, so
+ * hostd learns the message_id to EDIT for subsequent phases. `ok:false` when
+ * the post failed (hostd then simply won't edit — the durable log + terminal
+ * push remain the record).
+ */
+export interface RolloutStatusPostedEvent {
+  type: "rollout_status_posted";
+  requestId: string;
+  ok: boolean;
+  /** Telegram message_id of the posted status message (present when ok). */
+  messageId?: number;
+  /** Diagnostic detail on failure. */
+  reason?: string;
+}
+
 export type ClientToGateway =
   | RegisterMessage
   | ToolCallMessage
@@ -510,4 +572,6 @@ export type ClientToGateway =
   | RequestConfigFinalizeMessage
   | QuotaWallDetectedMessage
   | SendOutboundMessage
-  | PostSkillProposalMessage;
+  | PostSkillProposalMessage
+  | RolloutStatusPostMessage
+  | RolloutStatusEditMessage;

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

@@ -1,4 +1,4 @@
-import { renameSync, unlinkSync } from "fs";
+import { renameSync, unlinkSync, chmodSync } from "fs";
 import type {
   ClientToGateway,
   GatewayToClient,
@@ -15,6 +15,8 @@ import type {
   RequestConfigFinalizeMessage,
   RequestDriveApprovalMessage,
   RequestMs365ApprovalMessage,
+  RolloutStatusPostMessage,
+  RolloutStatusEditMessage,
   ScheduleRestartMessage,
   SessionEventForward,
   ToolCallMessage,
@@ -113,6 +115,25 @@ export interface IpcServerOptions {
     client: IpcClient,
     msg: RequestConfigFinalizeMessage,
   ) => Promise<void>;
+  /**
+   * #2726 Part 1 — hostd asks the gateway to POST one ordinary operator-DM
+   * message narrating a rollout's terminal outcome (Part 1) or its first phase
+   * (Part 2). Handler posts to the agent's own operator chat and — for Part 2 —
+   * replies with a `rollout_status_posted` event carrying the message_id.
+   * Optional: gateways without the hostd integration ignore it.
+   */
+  onRolloutStatusPost?: (
+    client: IpcClient,
+    msg: RolloutStatusPostMessage,
+  ) => Promise<void>;
+  /**
+   * #2726 Part 2 — hostd asks the gateway to EDIT a previously-posted rollout
+   * status message as later phases arrive. Best-effort, no reply. Optional.
+   */
+  onRolloutStatusEdit?: (
+    client: IpcClient,
+    msg: RolloutStatusEditMessage,
+  ) => void;
   log?: (msg: string) => void;
   /**
    * How long (in ms) to wait without a heartbeat before force-closing the
@@ -381,6 +402,33 @@ export function validateClientMessage(msg: unknown): msg is ClientToGateway {
           || (m.ttlMs as number) < 0)) return false;
       return true;
     }
+    case "rollout_status_post": {
+      // #2726 Part 1 — hostd-initiated terminal ping / status post. Wire shape
+      // only; the gateway handler fences the chat to the agent's own operator.
+      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.text !== "string"
+        || (m.text as string).length === 0
+        || (m.text as string).length > RICH_MESSAGE_MAX_CHARS) return false;
+      return true;
+    }
+    case "rollout_status_edit": {
+      // #2726 Part 2 — hostd-initiated status-message edit.
+      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.messageId !== "number"
+        || !Number.isInteger(m.messageId as number)) return false;
+      if (typeof m.text !== "string"
+        || (m.text as string).length === 0
+        || (m.text as string).length > RICH_MESSAGE_MAX_CHARS) return false;
+      return true;
+    }
     default:
       return false;
   }
@@ -406,6 +454,8 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     onRequestMs365Approval,
     onRequestConfigApproval,
     onRequestConfigFinalize,
+    onRolloutStatusPost,
+    onRolloutStatusEdit,
     log = () => {},
     heartbeatTimeoutMs = 30_000,
   } = options;
@@ -637,6 +687,42 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
         }
         // No reply expected.
         break;
+      case "rollout_status_post":
+        if (onRolloutStatusPost) {
+          onRolloutStatusPost(client, msg as RolloutStatusPostMessage).catch(
+            (err) => {
+              log(
+                `rollout_status_post handler threw (client=${client.id}): ${(err as Error).message}`,
+              );
+              // Best-effort failure reply so hostd's Part 2 renderer knows the
+              // post failed (it just won't edit). Part 1 ignores the reply.
+              try {
+                client.send({
+                  type: "rollout_status_posted",
+                  requestId: (msg as RolloutStatusPostMessage).requestId,
+                  ok: false,
+                  reason: `gateway handler error: ${(err as Error).message}`,
+                });
+              } catch {
+                /* best effort */
+              }
+            },
+          );
+        }
+        // No reply required when unwired — hostd falls back to the durable log.
+        break;
+      case "rollout_status_edit":
+        if (onRolloutStatusEdit) {
+          try {
+            onRolloutStatusEdit(client, msg as RolloutStatusEditMessage);
+          } catch (err) {
+            log(
+              `rollout_status_edit handler threw (client=${client.id}): ${(err as Error).message}`,
+            );
+          }
+        }
+        // Fire-and-forget; no reply.
+        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
@@ -786,6 +872,10 @@ export function createIpcServer(options: IpcServerOptions): IpcServer {
     },
   });
 
+  // Allow the web container (uid=1000, operator) to inject prompts via
+  // injectInbound without needing root — the socket is inside the per-agent
+  // state directory which is already operator-accessible.
+  try { chmodSync(socketPath, 0o666); } catch { /* best-effort */ }
   log(`listening on ${socketPath}`);
 
   // ─── Heartbeat watchdog (issue #71) ─────────────────────────────────────

package/telegram-plugin/gateway/linear-activity.ts

@@ -15,6 +15,7 @@
  * agent to `vault_request_access` for that key rather than failing opaquely.
  */
 
+import { escapeMarkdown } from '../format.js'
 import {
   getViaBrokerStructured,
   putViaBroker,
@@ -30,10 +31,6 @@ export type LinearAuthDeadReason = 'no_bundle' | 'revoked'
 /** Minimal GFM-markdown escape (#2669). Kept local so the message builder is
  *  self-contained + unit-testable without reaching into a gateway-only
  *  escaper (the bug that shipped the first cut of this alert). */
-function escapeMarkdownMin(s: string): string {
-  return s.replace(/([\\`*_~=\[\]|])/g, '\\$1')
-}
-
 /**
  * Build the operator-facing Telegram alert (GFM markdown) for an un-healable
  * Linear auth failure. Pure + self-escaping so it can be unit-tested directly.
@@ -42,7 +39,7 @@ function escapeMarkdownMin(s: string): string {
 export function buildLinearAuthDeadMessage(agent: string, reason: LinearAuthDeadReason): string {
   // Inside `code` spans the agent slug is literal (no escaping); in prose it
   // is markdown-escaped.
-  const aEsc = escapeMarkdownMin(agent)
+  const aEsc = escapeMarkdown(agent)
   const why =
     reason === 'no_bundle'
       ? `no refresh credentials are stored (\`linear/${agent}/oauth\` is missing), so its daily-expiring token can't renew`

package/telegram-plugin/gateway/obligation-turn-end.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure decision for what a turn_end does to the ending turn's delivery
+ * obligation (#2624).
+ *
+ * Two branches, both must be pinned by tests:
+ *
+ *   - **Normal reply** — the turn either delivered a genuine final answer
+ *     (`finalAnswerDelivered`) OR the model explicitly called reply
+ *     (`replyCalled`, true even for a short LiteLLM sr-* `reply("OK",
+ *     {disable_notification:true})` that `isFinalAnswerReply` demoted to
+ *     non-final). Either way the obligation is satisfied → close it at
+ *     turn_end.
+ *
+ *   - **Ack-then-ghost / no-reply** — the turn ended with no reply at all
+ *     (no ack, no answer). The obligation must NOT close at turn_end; it
+ *     stays open and the idle sweep later ends it via the silence_fallback
+ *     path. At turn_end we only stamp the grace clock (`note-ended`).
+ *
+ * Returns the action the caller applies to the ledger. Pure — no ledger
+ * mutation, no module state.
+ */
+export function decideObligationTurnEnd(
+  finalAnswerDelivered: boolean,
+  replyCalled: boolean,
+): 'close' | 'note-ended' {
+  return finalAnswerDelivered || replyCalled ? 'close' : 'note-ended'
+}

package/telegram-plugin/gateway/permission-card-store.ts

@@ -0,0 +1,104 @@
+/**
+ * Persistence store for in-flight permission card references.
+ *
+ * Problem: `pendingPermissions` is in-memory. When the gateway restarts
+ * (gateway crash OR container restart), all entries are lost. Old permission
+ * cards in Telegram keep their [Allow][Deny] inline keyboard buttons.
+ * When the operator taps one, they get STALE_TAP_NOTICE ("already resolved
+ * (timed out)"), which is misleading — the request wasn't resolved, it was
+ * lost. Operators interpret this as "my approval didn't work."
+ *
+ * Fix: persist the (chatId, messageId) references for every posted card to a
+ * JSON file in STATE_DIR. On each resolution (allow/deny/TTL-expire), remove
+ * the entry. On gateway boot, load any surviving entries (they were never
+ * resolved — the gateway crashed) and strip their inline keyboards + add a
+ * "gateway restarted" footer so the operator sees a clear explanation instead
+ * of a tappable-but-dead button.
+ *
+ * File format: JSON array of PersistedPermCard objects. Kept small (one file,
+ * written synchronously to avoid interleaving on concurrent card posts).
+ * Production rate: a few cards per permission request; file stays tiny.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface PersistedPermCard {
+  requestId: string
+  chatId: string
+  messageId: number
+  startedAt: number
+  toolName: string
+  cardText: string
+}
+
+export interface PermissionCardStore {
+  /** Record a newly-posted card. Idempotent on requestId+messageId. */
+  add(entry: PersistedPermCard): void
+  /** Remove all entries for this request (resolved — allow, deny, TTL). */
+  remove(requestId: string): void
+  /** Return all persisted entries (for boot-time stale-strip sweep). */
+  loadAll(): PersistedPermCard[]
+  /** Delete the backing file entirely (after boot sweep completes). */
+  clear(): void
+}
+
+export function createPermissionCardStore(stateDir: string): PermissionCardStore {
+  const filePath = join(stateDir, 'pending-perm-cards.json')
+
+  function read(): PersistedPermCard[] {
+    try {
+      const raw = readFileSync(filePath, 'utf-8')
+      const parsed = JSON.parse(raw)
+      return Array.isArray(parsed) ? (parsed as PersistedPermCard[]) : []
+    } catch {
+      return []
+    }
+  }
+
+  function write(entries: PersistedPermCard[]): void {
+    try {
+      writeFileSync(filePath, JSON.stringify(entries), { encoding: 'utf-8', mode: 0o600 })
+    } catch (err) {
+      process.stderr.write(
+        `telegram gateway: permission-card-store write failed: ${(err as Error).message}\n`,
+      )
+    }
+  }
+
+  return {
+    add(entry) {
+      const entries = read()
+      // Replace existing entry for same (requestId, messageId) if present
+      const idx = entries.findIndex(
+        e => e.requestId === entry.requestId && e.messageId === entry.messageId,
+      )
+      if (idx >= 0) {
+        entries[idx] = entry
+      } else {
+        entries.push(entry)
+      }
+      write(entries)
+    },
+
+    remove(requestId) {
+      const entries = read()
+      const filtered = entries.filter(e => e.requestId !== requestId)
+      if (filtered.length !== entries.length) {
+        write(filtered)
+      }
+    },
+
+    loadAll() {
+      return read()
+    },
+
+    clear() {
+      try {
+        unlinkSync(filePath)
+      } catch {
+        // File may not exist — that's fine
+      }
+    },
+  }
+}

package/telegram-plugin/gateway/permission-timeout.ts

@@ -71,17 +71,36 @@ export function isRecentTimeoutDuplicate(
 
 // ─── Bug 2 — per-tool TTL + timed-out card hygiene + stale-tap honesty ──────
 
-/** Default operator approval-card lifetime. */
-export const PERMISSION_TTL_MS = 10 * 60_000
+/** Fallback operator approval-card lifetime when nothing is configured. */
+export const PERMISSION_TTL_DEFAULT_MS = 60 * 60_000
+
+/**
+ * Resolve the operator approval-card lifetime (ms) from the environment.
+ * Threaded from config as `channels.telegram.approval_timeout_minutes` →
+ * `SWITCHROOM_TG_APPROVAL_TIMEOUT_MS` (see scaffold.ts `channelsToEnv`). A
+ * blank/garbage value falls back to the 60-min default; `0` (or negative) is
+ * clamped to the default so a card can never be born already-expired.
+ */
+export function approvalTtlMs(
+  env: Record<string, string | undefined> = process.env,
+): number {
+  const raw = env.SWITCHROOM_TG_APPROVAL_TIMEOUT_MS
+  if (raw === undefined || raw.trim() === '') return PERMISSION_TTL_DEFAULT_MS
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n <= 0) return PERMISSION_TTL_DEFAULT_MS
+  return Math.floor(n)
+}
+
+/** Default operator approval-card lifetime (config-driven, 60 min default). */
+export const PERMISSION_TTL_MS = approvalTtlMs()
 
 /**
  * hostd gated fleet-mutation verbs (rollout / update_apply / agent_* /
  * config_propose_edit) surface an OPERATOR approval card and demand a
- * human-scale decision window — 10 min is too tight when the operator is
- * mid-task. The `mcp__hostd__*` family gets 30 min; everything else keeps
- * the 10-min default.
+ * human-scale decision window. The `mcp__hostd__*` family gets at least
+ * 30 min; if the configured approval window is longer, it wins.
  */
-export const HOSTD_PERMISSION_TTL_MS = 30 * 60_000
+export const HOSTD_PERMISSION_TTL_MS = Math.max(30 * 60_000, PERMISSION_TTL_MS)
 
 /** Per-tool approval-card TTL. */
 export function ttlForTool(toolName: string | undefined): number {