switchroom 0.16.23 → 0.16.27

package/telegram-plugin/secret-detect/vault-error.ts

@@ -127,10 +127,17 @@ export interface VaultErrorRendering {
 }
 
 function htmlEscape(s: string): string {
-  return s
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
+  return s.replace(/([\\`*_~=\[\]|])/g, "\\$1");
+}
+
+/**
+ * Make a string safe to interpolate INSIDE a `code span` without escaping —
+ * content there is literal, so markdown-escaping a key would leak visible
+ * backslashes (e.g. `my\_key`). Only a backtick can prematurely close the
+ * span, so split it with a zero-width space (#2669).
+ */
+function codeSpanSafe(s: string): string {
+  return s.replace(/`/g, "`​");
 }
 
 /**
@@ -173,13 +180,13 @@ export function renderVaultCliError(
       return {
         suppressRaw: true,
         html:
-          `⚠️ <b>New vault key — operator approval required.</b>\n` +
+          `⚠️ **New vault key — operator approval required.**\n` +
           (key
-            ? `The agent tried to save <code>${htmlEscape(key)}</code>, but `
+            ? `The agent tried to save \`${codeSpanSafe(key)}\`, but `
             : `The agent tried to save a new key, but `) +
           `agents can only rotate existing keys via the broker; introducing ` +
           `a new key needs an operator action.\n\n` +
-          `<b>Ask the agent</b> to call its <code>vault_request_save</code> ` +
+          `**Ask the agent** to call its \`vault_request_save\` ` +
           `tool — it'll render an approval card in this chat with ` +
           `[✅ Save once] [🚫 Discard] [✏️ Rename] buttons. One tap saves the ` +
           `secret to the vault; no re-paste needed.`,
@@ -194,12 +201,12 @@ export function renderVaultCliError(
       return {
         suppressRaw: true,
         html:
-          `⚠️ <b>Vault broker isn't reachable.</b>\n` +
+          `⚠️ **Vault broker isn't reachable.**\n` +
           `From inside the agent sandbox there's no fallback path. ` +
           `Telegram-native broker recovery is tracked as a follow-up — ` +
           `for now, on the host:\n` +
-          `<pre>switchroom vault broker status</pre>\n` +
-          `<i>Or, if the broker is wedged: <code>docker compose -p switchroom restart vault-broker</code>.</i>`,
+          "```\nswitchroom vault broker status\n```\n" +
+          `_Or, if the broker is wedged: \`docker compose -p switchroom restart vault-broker\`._`,
       };
     case "broker_denied":
       // Telegram-native grant flow shipped in #969 P2b + #1012:
@@ -210,14 +217,14 @@ export function renderVaultCliError(
       return {
         suppressRaw: true,
         html:
-          `⚠️ <b>Vault broker refused the request.</b>\n` +
+          `⚠️ **Vault broker refused the request.**\n` +
           (key
-            ? `The agent isn't authorized to access <code>${htmlEscape(key)}</code>. `
+            ? `The agent isn't authorized to access \`${codeSpanSafe(key)}\`. `
             : `The agent isn't authorized to access this key. `) +
           `Grant access in two taps:\n` +
-          `• <code>/vault audit &lt;agent&gt;</code> in this chat → tap ` +
+          `• \`/vault audit <agent>\` in this chat → tap ` +
           `[🔓 Allow${key ? ` ${htmlEscape(key)}` : ""}] on the recent denial, OR\n` +
-          `• ask the agent to call <code>vault_request_access</code> — ` +
+          `• ask the agent to call \`vault_request_access\` — ` +
           `an approval card lands here with [✅ Approve] / [🚫 Deny].`,
       };
     case "other":
@@ -234,36 +241,36 @@ function renderSandboxContextSuggestion(
   verb: "set" | "get" | "list" | "init" | "remove" | "save",
   key: string | undefined,
 ): string {
-  const head = `⚠️ <b>Direct vault file IO isn't available from inside the agent sandbox.</b>\n`;
+  const head = `⚠️ **Direct vault file IO isn't available from inside the agent sandbox.**\n`;
   switch (verb) {
     case "set":
     case "save":
       return (
         head +
         (key
-          ? `<b>Ask the agent</b> to call its <code>vault_request_save</code> ` +
-            `tool for <code>${htmlEscape(key)}</code> — an approval card ` +
+          ? `**Ask the agent** to call its \`vault_request_save\` ` +
+            `tool for \`${codeSpanSafe(key)}\` — an approval card ` +
             `lands here with [✅ Save once] / [🚫 Discard] / [✏️ Rename] buttons.`
-          : `<b>Ask the agent</b> to call its <code>vault_request_save</code> ` +
+          : `**Ask the agent** to call its \`vault_request_save\` ` +
             `tool — an approval card lands here with [✅ Save once] / [🚫 Discard] / [✏️ Rename] buttons.`)
       );
     case "get":
       return (
         head +
-        `From this chat: <code>/vault get${key ? ` ${htmlEscape(key)}` : " &lt;key&gt;"}</code>`
+        `From this chat: \`/vault get${key ? ` ${codeSpanSafe(key)}` : " <key>"}\``
       );
     case "list":
-      return head + `From this chat: <code>/vault list</code>`;
+      return head + `From this chat: \`/vault list\``;
     case "remove":
       return (
         head +
         `Use the operator host CLI for now — Telegram-native delete is tracked as a follow-up. ` +
-        `<i>(Removing a vault key is a rare, irreversible operation; an in-chat confirmation card is on the punch list.)</i>`
+        `_(Removing a vault key is a rare, irreversible operation; an in-chat confirmation card is on the punch list.)_`
       );
     case "init":
       return (
         head +
-        `Vault bootstrap is a one-time host-shell step: <code>switchroom vault init</code>.`
+        `Vault bootstrap is a one-time host-shell step: \`switchroom vault init\`.`
       );
   }
 }

package/telegram-plugin/shared/bot-runtime.ts

@@ -29,6 +29,7 @@ import { createHash } from 'crypto'
 import { AsyncLocalStorage } from 'async_hooks'
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
 import { createRetryApiCall } from '../retry-api-call.js'
+import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
 
 // ─── tg-post tag plumbing ─────────────────────────────────────────────────
 
@@ -154,21 +155,36 @@ export function createRobustApiCall() {
   })
 }
 
-// ─── HTML escape helpers ─────────────────────────────────────────────────
+// ─── Markdown escape helpers (#2669) ──────────────────────────────────────
 
+/**
+ * Escape GFM-markdown specials in a dynamic value interpolated into prose.
+ * Kept under the legacy `escapeHtmlForTg` name so callers don't churn.
+ */
 export function escapeHtmlForTg(text: string): string {
-  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1')
 }
 
+/**
+ * Wrap CLI / command output in a fenced code block. Inside a fence the
+ * content is literal (no escaping), so we pass `text` through verbatim —
+ * except a fence-closing ``` sequence in the content, which we defuse so it
+ * can't terminate the block early.
+ */
 export function preBlock(text: string): string {
-  return '<pre>' + escapeHtmlForTg(text) + '</pre>'
+  const safe = text.replace(/```/g, '`​``')
+  return '```\n' + safe + '\n```'
 }
 
 export function stripAnsi(text: string): string {
   return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')
 }
 
-export function formatSwitchroomOutput(output: string, maxLen = 4000): string {
+// Default truncation budget for CLI output bound for Telegram. Post-#2669 the
+// rich-message wire cap is RICH_MESSAGE_MAX_CHARS (32768), not the legacy 4096
+// plain-text limit; the preBlock fence framing (~8 chars) easily fits the
+// remaining headroom.
+export function formatSwitchroomOutput(output: string, maxLen = RICH_MESSAGE_MAX_CHARS): string {
   const trimmed = output.trim()
   if (trimmed.length <= maxLen) return trimmed
   return trimmed.slice(0, maxLen - 20) + '\n... (truncated)'
@@ -278,11 +294,17 @@ export function makeSwitchroomReply(
   ): Promise<void> {
     const chatId = String(ctx.chat!.id)
     const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
-    await ctx.reply(text, {
+    const opts = {
       ...(threadId != null ? { message_thread_id: threadId } : {}),
-      ...(options.html ? { parse_mode: 'HTML' as const, link_preview_options: { is_disabled: true } } : {}),
       ...(options.reply_markup ? { reply_markup: options.reply_markup } : {}),
-    })
+    }
+    // #2669: `options.html:true` now means "render `text` as GFM markdown via
+    // the rich-message path" (legacy field name kept). Plain otherwise.
+    if (options.html) {
+      await ctx.replyWithRichMessage({ markdown: text }, opts)
+    } else {
+      await ctx.reply(text, opts)
+    }
   }
 }
 

package/telegram-plugin/silence-poke.ts

@@ -377,17 +377,20 @@ export function silenceMsForKey(key: string, now: number): number | null {
 }
 
 /**
- * Verbatim framework-fallback text — the user-visible "still working / still
- * thinking" message the gateway sends at the 300s threshold when the model
- * hasn't broken its own silence. Wording is load-bearing (see
- * `reference/rfcs/conversational-pacing.md` § Safety net). Two principles:
+ * Framework-fallback text for the 300s silence threshold. Returns `null` for
+ * the pure-stall cases (the "still working / still thinking" / "running <Tool>
+ * for Nm" notice) — that timer-fired stall ping was a stop-gap from before the
+ * live-updating reply/draft carried the progress beats natively, and the
+ * operator has retired it (it's the exact cadence-based "still working" update
+ * the conversational-pacing RFC's Anti-patterns section bans). The 300s
+ * fallback's surviving job — unwedging a turn that produced no output at all —
+ * is the gateway's turn-teardown after this call, NOT a user-visible message,
+ * so dropping the stall send keeps the safety net's real work intact (see
+ * `reference/rfcs/conversational-pacing.md` § Silence-poke fallback).
  *
- *   1. The parenthetical `(no update from agent in N min)` is honest —
- *      distinguishes from "the agent said something" so users learn to trust
- *      real agent messages. `N` is derived from `silenceMs`, never hard-coded.
- *   2. The verb is `working` by default, `thinking` only when the session
- *      stream has emitted a `kind: 'thinking'` event in the last 30s. Picked
- *      by the caller via `fallbackKind`; this helper just formats.
+ * The ONE case that still returns a string is `blockedOnApproval`: the turn is
+ * parked on an approval card waiting for YOUR tap. That is not a stall — it
+ * tells the user the ball is in their court — so it keeps pinging.
  *
  * Extracted from the gateway's `onFrameworkFallback` callback so the wording
  * can be snapshot-tested in isolation. CC-4 in `docs/status-ask-cause-classes.md`.
@@ -397,73 +400,27 @@ export function formatFrameworkFallbackText(
   silenceMs: number,
   inFlightTools: ToolSnapshot[] = [],
   blockedOnApproval = false,
-): string {
+): string | null {
   const minutes = Math.max(1, Math.round(silenceMs / 60_000))
   // The turn isn't stalled — it's parked on an approval card waiting for YOUR
   // tap (the dominant live "wedge" class is benign approval-latency, not a
   // hang). Saying "still working…" here actively lies; name the real blocker so
   // the operator knows the ball is in their court. Takes precedence over the
-  // in-flight-tool framing (a tool awaiting approval isn't "running").
+  // in-flight-tool framing (a tool awaiting approval isn't "running"). This is
+  // the only branch that still emits a user-visible message.
   if (blockedOnApproval) {
     return `waiting for your approval — tap Approve or Deny on the card above (${minutes} min)`
   }
-  const suffix = `(no update from agent in ${minutes} min)`
-  // #1292 case (a): tools in flight. Name the longest-running one
-  // (entry[0] — caller pre-sorts by startedAt ascending). Avoid the
-  // "still working" framing #1292 explicitly calls out as dishonest:
-  // the agent IS doing work, we can see the tool. Format:
-  //   running Grep "foo" for 4m (no update from agent in 5 min)
-  //   running Grep "foo" + 2 more (4m) (no update from agent in 5 min)
-  //   running Grep (no label) for 4m (no update from agent in 5 min)
-  //
-  // Raw MCP tool names (`mcp__server__tool`) are technical identifiers
-  // and look like a leak when surfaced to a user. When the tool name
-  // matches that shape AND a human-friendly label is available, drop
-  // the raw name and lead with the label instead:
-  //   Searching memory for 4m (no update from agent in 5 min)
-  // Built-in tool names (Grep, Read, Bash) stay as-is — they ARE
-  // human-readable, and the label is supplementary detail (e.g. the
-  // search pattern) that reads naturally after the verb.
-  if (inFlightTools.length > 0) {
-    const longest = inFlightTools[0]!
-    const dur = formatDurationShort(longest.durationMs)
-    const labelTail = longest.label && longest.label.length > 0
-      ? ` ${truncateLabel(longest.label)}`
-      : ''
-    const more = inFlightTools.length > 1
-      ? ` + ${inFlightTools.length - 1} more`
-      : ''
-    const isMcpRawName = /^mcp__/.test(longest.name)
-    if (isMcpRawName && labelTail !== '') {
-      // Label-only: "Searching memory for 4m (…)". Drop the raw
-      // `mcp__server__tool` and the leading "running" because the
-      // label already reads as a gerund phrase.
-      return `${truncateLabel(longest.label!)}${more} for ${dur} ${suffix}`
-    }
-    return `running ${longest.name}${labelTail}${more} for ${dur} ${suffix}`
-  }
-  return fallbackKind === 'thinking'
-    ? `still thinking… ${suffix}`
-    : `still working… ${suffix}`
-}
-
-/** Compact m/s rendering for the fallback message. Anything under a
- *  minute reads as `${s}s`, otherwise `${m}m`. Always rounds toward the
- *  user-honest direction — "4m" for 4m 30s, "5m" for 4m 45s. */
-function formatDurationShort(ms: number): string {
-  const totalSec = Math.max(0, Math.round(ms / 1000))
-  if (totalSec < 60) return `${totalSec}s`
-  const minutes = Math.round(totalSec / 60)
-  return `${minutes}m`
-}
-
-/** Telegram lines are short on mobile. Clip the label to keep the
- *  fallback message readable. Truncation point is generous (60 chars)
- *  because tool labels are pre-truncated by `toolLabel()` already. */
-function truncateLabel(label: string): string {
-  const MAX = 60
-  if (label.length <= MAX) return label
-  return label.slice(0, MAX - 1) + '…'
+  // Stop-gap retired: the "still working… (no update from agent in N min)" /
+  // "running <Tool> for Nm" stall notice (including the #1292 tool-aware
+  // enrichment) no longer sends. The live draft + the model's own pacing beats
+  // carry progress; a timer-fired stall ping on top of that is the banned
+  // cadence-based update. `fallbackKind` and `inFlightTools` are now unused for
+  // the stall path but kept on the signature so the gateway's call sites — and
+  // the deterministic update-status / unwedge paths around them — are untouched.
+  void fallbackKind
+  void inFlightTools
+  return null
 }
 
 /** Snapshot in-flight tools sorted longest-running first — for the honest

package/telegram-plugin/silent-reply-anchor.ts

@@ -38,8 +38,15 @@
  * the safety net off; reverts to per-reply fresh send.
  */
 
-/** Telegram caption / text limit. The accumulator stays under this. */
-export const TELEGRAM_MSG_CAP = 4000
+import { RICH_MESSAGE_MAX_CHARS } from './format.js'
+
+/**
+ * Telegram rich-message text limit. The accumulator stays under this before
+ * it rolls to a fresh anchor. Post-#2669 every reply renders as GFM markdown
+ * via `sendRichMessage`, so the cap is `RICH_MESSAGE_MAX_CHARS` (32768), not
+ * the legacy 4096 plain-text limit.
+ */
+export const TELEGRAM_MSG_CAP = RICH_MESSAGE_MAX_CHARS
 
 export interface SilentReplyAnchorDecisionInput {
   /** True when the model passed `disable_notification: true` for

package/telegram-plugin/slot-banner-driver.ts

@@ -31,10 +31,15 @@ export interface BannerBotApi {
     text: string,
     opts?: Record<string, unknown>,
   ): Promise<{ message_id: number }>;
+  sendRichMessage(
+    chat_id: string | number,
+    rich_message: { markdown: string },
+    opts?: Record<string, unknown>,
+  ): Promise<{ message_id: number }>;
   editMessageText(
     chat_id: string | number,
     message_id: number,
-    text: string,
+    text: string | { markdown: string },
     opts?: Record<string, unknown>,
   ): Promise<unknown>;
   pinChatMessage(
@@ -107,9 +112,8 @@ export async function refreshBanner(
   if (action.kind === 'pin') {
     let sent: { message_id: number };
     try {
-      sent = await args.bot.api.sendMessage(args.ownerChatId, action.text, {
-        parse_mode: 'HTML',
-        link_preview_options: { is_disabled: true },
+      // sendRichMessage doesn't accept link_preview_options — omit it.
+      sent = await args.bot.api.sendRichMessage(args.ownerChatId, { markdown: action.text }, {
         // OAuth slot banner is a status notice — silence the open ping.
         // (the pin below is already silent; the edit path doesn't ping.)
         disable_notification: true,
@@ -135,9 +139,8 @@ export async function refreshBanner(
     await args.bot.api.editMessageText(
       args.ownerChatId,
       action.messageId,
-      action.text,
+      { markdown: action.text },
       {
-        parse_mode: 'HTML',
         link_preview_options: { is_disabled: true },
       },
     );

package/telegram-plugin/slot-banner.ts

@@ -72,15 +72,12 @@ export function formatBannerHtml(
   defaultSlot: string,
 ): string {
   return [
-    `📌 <b>${escapeHtml(agentName)}</b> is running on slot <code>${escapeHtml(currentSlot)}</code>`,
-    `<i>(failover from <code>${escapeHtml(defaultSlot)}</code>)</i>`,
+    `📌 **${escapeMarkdown(agentName)}** is running on slot \`${currentSlot}\``,
+    `_(failover from \`${defaultSlot}\`)_`,
   ].join(' ');
 }
 
-function escapeHtml(text: string): string {
-  return text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
+/** Local GFM-markdown escaper (keeps this module dependency-free). */
+function escapeMarkdown(text: string): string {
+  return text.replace(/([\\`*_~=\[\]|])/g, '\\$1');
 }

package/telegram-plugin/status-no-truncate.ts

@@ -8,6 +8,10 @@
  * holds the tuning constants that primitive (and its internal helpers)
  * read, so a forked renderer never re-derives them.
  *
+ * Wire cap: since the Bot API 10.1 rich-message migration (#2669) every card
+ * renders as GFM markdown via `sendRichMessage`, whose limit is
+ * `RICH_MESSAGE_MAX_CHARS` (32768), not the legacy 4096 plain-text cap.
+ *
  * The former `SWITCHROOM_STATUS_NO_TRUNCATE` feature flag was retired:
  * rolling-window-with-char-budget is now the only behaviour. The per-line
  * cap (`STATUS_LINE_MAX`) and rolling window (`STATUS_ROLLING_LINES`) apply
@@ -15,6 +19,8 @@
  * (`STATUS_CARD_CHAR_BUDGET`) is the wire-limit backstop.
  */
 
+import { RICH_MESSAGE_MAX_CHARS } from './format.js'
+
 /**
  * Number of trailing narrative/step lines shown in the rolling window.
  * The feed is a fixed-height rolling window: oldest drops off as new arrive.
@@ -30,15 +36,15 @@ export const STATUS_ROLLING_LINES = 5
 export const STATUS_LINE_MAX = 200
 
 /**
- * The safe char budget for a rendered Telegram status card. Telegram's hard
- * cap is 4096; we use 4000 to leave 96 chars of headroom for HTML framing,
- * emoji, and escape expansion — matching the convention in
- * pending-work-progress.ts (TELEGRAM_MSG_CAP = 4000).
+ * The safe char budget for a rendered Telegram status card. The rich-message
+ * wire cap is `RICH_MESSAGE_MAX_CHARS` (32768) post-#2669 — the legacy 4096
+ * plain-text cap no longer applies on the rich path. We use the constant
+ * directly as the backstop.
  *
  * With STATUS_ROLLING_LINES=5 lines each ≤ STATUS_LINE_MAX this backstop
  * effectively never fires in practice, but is kept as a wire-limit safety net.
  */
-export const STATUS_CARD_CHAR_BUDGET = 4000
+export const STATUS_CARD_CHAR_BUDGET = RICH_MESSAGE_MAX_CHARS
 
 /** Indent marker for a nested (foreground sub-agent) step line. */
 export const NESTED_PREFIX = '   ↳ '

package/telegram-plugin/steering.ts

@@ -9,7 +9,6 @@
  * These helpers are pure so server.ts stays testable without standing up
  * grammy.
  */
-import { escapeHtml } from './format.js'
 
 /**
  * Detect and strip the `/queue ` or `/q ` prefix.
@@ -181,6 +180,3 @@ export function buildChannelMetaAttributes(opts: ChannelMetaAttributeOptions): s
   }
   return parts.length === 0 ? '' : ' ' + parts.join(' ')
 }
-
-/** Re-export so callers that want HTML-escape for body content don't need a second import. */
-export { escapeHtml }