switchroom 0.21.0 → 0.21.3

package/telegram-plugin/shared/sent-text-capture.ts

@@ -0,0 +1,191 @@
+/**
+ * sent-text-capture.ts — the card-body FALLBACK: stamp a send's REQUEST body
+ * onto the `Message` Telegram returned for it (#4571 / #4576 follow-up).
+ *
+ * Read this first: it is NOT the primary source of the stored card body.
+ * -----------------------------------------------------------------------
+ * `system-message-observer.ts` takes the body off the RESPONSE — `rich_message`
+ * (Telegram's own rendered block tree) first, then `text` / `caption`. That is
+ * the more faithful source, and it covers every send verb the gateway writes a
+ * history row for. This module supplies the LAST tier of that precedence
+ * chain, for responses that carry no renderable body at all: a rich send whose
+ * blocks flatten to nothing (a media-only card), or a future verb whose
+ * response omits the body.
+ *
+ * Deliberately last, because the body it captures is NOT the body as written.
+ * The dominant card path is `sendRichMessage(chat, richMessage(body))`, and
+ * `richMessage()` applies `guardAccidentalFormatting` in the CALLER
+ * (`rich-send.ts`), long before any transformer seam. So what this module sees
+ * on that path is already wire-escaped: `sent_text_capture.ts` arrives as
+ * `sent\_text\_capture.ts`, `$12.40` as `\$12.40`. Escaped-but-present beats
+ * empty, which is why the tier exists at all — but it must never win over a
+ * response that resolved those escapes.
+ *
+ * The bug this exists to backstop
+ * -------------------------------
+ * #4576 gave every gateway card a `role='system'` history row so a quote-reply
+ * to it resolves. The row carried the right `message_id`, chat, thread and
+ * `kind` — and an EMPTY `text`, on 100% of the rows, on every agent in the
+ * fleet. `resolveReplyToFromBuffer` only sets `reply_to_text` when the stored
+ * body is non-empty (`inbound-router.ts`), so the agent learned WHICH card was
+ * tapped and still could not see WHAT IT SAID. That was the entire point.
+ *
+ * Root cause: the observer read ONE body field off the response
+ * (`msg.text ?? msg.caption`), and every card goes out through Bot API 10.1
+ * `sendRichMessage`, whose response is a `Message.RichMessageMessage` — the
+ * body lives under `rich_message: { blocks }`, and `text` / `caption` are
+ * simply absent (`@grammyjs/types` `message.d.ts:94`, `:180`; Bot API
+ * `RichMessage.blocks` = "Content of the message"). So the extractor fell
+ * through to `''` every single time. Reading `rich_message` is the fix; this
+ * module is the belt to that pair of braces.
+ *
+ * The mechanism
+ * -------------
+ * Capture the body from the REQUEST at the one seam no outbound call can
+ * bypass: a grammY API transformer (`bot.api.config.use`) — the same seam
+ * `installRichMarkdownGuard` already uses, and the reason that guard is
+ * universal where `richMessage()` is not.
+ *
+ * The transformer sees the outbound payload AND the resolved response in one
+ * call, so it can pair them with zero bookkeeping: no id→text map, no eviction,
+ * no cross-call race. It stamps the body onto the returned `Message` under a
+ * non-enumerable, `Symbol.for`-keyed property, which:
+ *   - survives grammY's `callApi` unwrapping — the transformer chain resolves
+ *     with the raw `{ok, result}` envelope and `callApi` returns `data.result`
+ *     BY REFERENCE (grammy 1.44.0 `out/core/client.js:95-99`), so the object
+ *     the caller receives is the object we stamped;
+ *   - is invisible to `JSON.stringify`, `Object.keys`, spreads and structural
+ *     equality, so nothing that reads a `Message` today can observe it.
+ *
+ * Non-negotiable: this must never break the send it observes. Every step is
+ * defensive and the transformer's only unconditional act is `return prev(...)`.
+ */
+
+import type { Bot } from 'grammy'
+
+/**
+ * The stamp key. `Symbol.for` (not a module-local `Symbol()`) deliberately:
+ * the plugin is consumed both from source and from a bundle, and a duplicated
+ * module instance would otherwise mint a second, non-matching symbol and
+ * silently reopen the exact hole this file closes.
+ */
+export const SENT_TEXT = Symbol.for('switchroom.telegram.sentText')
+
+/** Depth cap for the rich-block walk — a hostile/odd payload cannot recurse us. */
+const MAX_BLOCK_DEPTH = 8
+
+/**
+ * Best-effort readable text out of an OUTBOUND `InputRichMessage.blocks` array.
+ *
+ * Nothing in this repo builds `{ blocks }` today (every rich send goes through
+ * `richMessage()` → `{ markdown }`), so this is purely the guard against a
+ * future adopter silently re-emptying the card lane. Bounded, allocation-shy,
+ * never throws.
+ */
+function flattenInputRichBlocks(blocks: unknown, depth: number): string {
+  if (!Array.isArray(blocks) || depth > MAX_BLOCK_DEPTH) return ''
+  const parts: string[] = []
+  for (const block of blocks) {
+    if (block == null || typeof block !== 'object') continue
+    const b = block as Record<string, unknown>
+    for (const key of ['markdown', 'html', 'text', 'caption'] as const) {
+      const v = b[key]
+      if (typeof v === 'string' && v.length > 0) parts.push(v)
+    }
+    const nested = flattenInputRichBlocks(b.blocks, depth + 1)
+    if (nested.length > 0) parts.push(nested)
+  }
+  return parts.join('\n')
+}
+
+/**
+ * The body a Telegram API request is about to POST, or null when the payload
+ * carries no user-visible text (pins, deletes, reactions, `getUpdates`, …).
+ *
+ * Shape verified against grammy 1.44.0 `out/core/api.js` and the payload notes
+ * in `installRichMarkdownGuard`: `sendRichMessage` / rich `editMessageText`
+ * put the body at `payload.rich_message.markdown`, plain sends at
+ * `payload.text`, media sends at `payload.caption`. Pure.
+ */
+export function outboundPayloadText(payload: unknown): string | null {
+  if (payload == null || typeof payload !== 'object') return null
+  const p = payload as Record<string, unknown>
+  const rich = p.rich_message
+  if (rich != null && typeof rich === 'object') {
+    const r = rich as Record<string, unknown>
+    if (typeof r.markdown === 'string') return r.markdown
+    if (typeof r.html === 'string') return r.html
+    const flat = flattenInputRichBlocks(r.blocks, 0)
+    if (flat.length > 0) return flat
+  }
+  if (typeof p.text === 'string') return p.text
+  if (typeof p.caption === 'string') return p.caption
+  return null
+}
+
+/**
+ * Stamp `text` onto a resolved API response envelope's `Message` result.
+ *
+ * Takes the raw `{ok, result}` envelope (what a transformer sees), not the
+ * unwrapped message, and no-ops on anything that isn't a single Message —
+ * `true` (pins / dropped edits / `editMessageText` on an inline message),
+ * arrays, `{ok:false}` rejections. Never throws.
+ */
+export function attachSentText(envelope: unknown, text: string): void {
+  try {
+    if (envelope == null || typeof envelope !== 'object') return
+    const env = envelope as { ok?: unknown; result?: unknown }
+    if (env.ok !== true) return
+    const result = env.result
+    if (result == null || typeof result !== 'object' || Array.isArray(result)) return
+    Object.defineProperty(result, SENT_TEXT, {
+      value: text,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    })
+  } catch {
+    /* stamping must never break the send */
+  }
+}
+
+/**
+ * Read the body stamped by {@link installSentTextCapture} off a `Message`, or
+ * null when the message did not transit a capture-installed bot (a test double,
+ * a second Bot instance, a hand-built fixture). Pure.
+ */
+export function readSentText(message: unknown): string | null {
+  if (message == null || typeof message !== 'object') return null
+  const v = (message as Record<symbol, unknown>)[SENT_TEXT]
+  return typeof v === 'string' ? v : null
+}
+
+/**
+ * Install the capture transformer on the production Bot.
+ *
+ * Install it AFTER `installRichMarkdownGuard` so it composes OUTSIDE the guard
+ * (grammY's last-installed transformer runs first) and therefore captures the
+ * payload before the guard's backslash escapes are applied.
+ *
+ * Be precise about what that does and does not buy. It only avoids the
+ * TRANSFORMER's escaping pass, which matters for the call sites that build a
+ * raw `{ markdown }` and go straight to `sendRichMessage` / `editMessageText`
+ * (banners, approval and folder-picker edits — see `richMessage()`'s docblock
+ * for the list). It does NOT recover a pre-escape body for the dominant path,
+ * because `richMessage()` escapes in the CALLER, upstream of every transformer.
+ * There is no seam that can. That is precisely why this capture is the LAST
+ * tier of the observer's precedence chain rather than the first.
+ */
+export function installSentTextCapture(bot: Bot): void {
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    let text: string | null = null
+    try {
+      text = outboundPayloadText(payload)
+    } catch {
+      text = null
+    }
+    const res = await prev(method, payload, signal)
+    if (text != null) attachSentText(res, text)
+    return res
+  })
+}

package/telegram-plugin/tests/card-history-lane.test.ts

@@ -49,6 +49,10 @@ import {
   type EnvelopeBuildParams,
 } from '../gateway/inbound-router.js'
 import { makeSystemMessageObserver } from '../gateway/system-message-observer.js'
+import { Bot } from 'grammy'
+import { installRichMarkdownGuard } from '../shared/bot-runtime.js'
+import { installSentTextCapture } from '../shared/sent-text-capture.js'
+import { richMessage } from '../rich-send.js'
 
 const CHAT = '5550001'
 const REPLY_TO_TEXT_MAX = 200
@@ -62,11 +66,58 @@ function makeObserver(now?: () => number) {
   })
 }
 
-/** A Telegram Message response, as `robustApiCall` resolves with. */
+/**
+ * A Telegram Message response, as `robustApiCall` resolves with.
+ *
+ * NOTE (#4576): this PLAIN shape is what `sendMessage` returns. No CARD send
+ * uses it — cards go out via `sendRichMessage`, whose response carries no
+ * `text` at all. Tests that assert the card BODY must use `sentRichCard()`
+ * below; a hand-built `{ text }` fixture cannot fail on the empty-body bug.
+ */
 function sentMessage(messageId: number, text: string) {
   return { message_id: messageId, chat: { id: Number(CHAT) }, text }
 }
 
+/**
+ * The result of a REAL `sendRichMessage` through the production transformer
+ * stack (fmt guard + `installSentTextCapture`), transport stubbed to answer
+ * with the true `Message.RichMessageMessage` shape: `rich_message` blocks, and
+ * NO `text` / `caption`.
+ *
+ * This is the fixture the #4576 defect demanded: every `role='system'` row on
+ * every agent in the fleet had `length(text)=0`, because the lane's tests fed
+ * the observer a response shape production never produces.
+ */
+async function sentRichCard(messageId: number, body: string): Promise<unknown> {
+  const fakeFetch = (async () =>
+    ({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        ok: true,
+        result: {
+          message_id: messageId,
+          date: 0,
+          chat: { id: Number(CHAT), type: 'private' },
+          rich_message: { blocks: [{ type: 'paragraph', text: { text: body } }] },
+        },
+      }),
+    }) as unknown as Response) as unknown as typeof fetch
+
+  const bot = new Bot('123456:TEST_TOKEN', {
+    botInfo: {
+      id: 123456, is_bot: true, first_name: 'Test', username: 'test_bot',
+      can_join_groups: false, can_read_all_group_messages: false,
+      supports_inline_queries: false, can_connect_to_business: false,
+      has_main_web_app: false,
+    },
+    client: { fetch: fakeFetch },
+  })
+  installRichMarkdownGuard(bot)
+  installSentTextCapture(bot)
+  return bot.api.sendRichMessage(Number(CHAT), richMessage(body))
+}
+
 /** The reply-antecedent lookup as gateway.ts binds it (#4571: includeSystem). */
 function boundLookup(messageId: number) {
   return lookupMessageRoleAndText(CHAT, messageId, { includeSystem: true })
@@ -197,6 +248,75 @@ describe('a quote-reply to the live activity card is UNDERSTOOD, end to end', ()
   })
 })
 
+describe('#4576: the stored card body is NOT empty — real sendRichMessage response', () => {
+  it('a rich card write leaves a non-empty row, and the quote-reply carries the body', async () => {
+    const observe = makeObserver()
+    const CARD_ID = 20395
+    const BODY = '⚙️ Working — reading history.ts, 3 tools'
+
+    // The exact production path: sendRichMessage → transformer stack → observer.
+    // Its response has NO `text` field, which is what made every fleet row empty.
+    const result = await sentRichCard(CARD_ID, BODY)
+    expect((result as { text?: unknown }).text).toBeUndefined()
+    observe(result, { chat_id: CHAT, verb: 'activity-summary.send' })
+
+    const row = lookupMessageRoleAndText(CHAT, CARD_ID, { includeSystem: true })
+    expect(row?.role).toBe('system')
+    expect(row?.kind).toBe('activity-summary')
+    // The assertion the shipped bug fails: a stored body, not ''.
+    expect(row?.text.length).toBeGreaterThan(0)
+    expect(row?.text).toBe(BODY)
+
+    const resolved = resolveReplyToFromBuffer({
+      replyToMessageId: CARD_ID,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: boundLookup,
+    })
+    expect(resolved.replyToText).toBe(BODY)
+
+    const msg = buildInboundEnvelope(
+      makeEnvelopeParams({
+        replyToMessageId: CARD_ID,
+        replyToTextEscaped: resolved.replyToTextEscaped,
+        replyToRole: resolved.replyToRole,
+        replyToKind: resolved.replyToKind,
+      }),
+    )
+    expect(msg.meta?.reply_to_text).toBe(BODY)
+  })
+
+  it('holds for every card verb observed on the live fleet, not just the activity card', async () => {
+    const observe = makeObserver()
+    // The `kind` values measured on live agents' history.db after v0.21.0.
+    const verbs: [string, number, string][] = [
+      ['boot-card', 5082, '🟢 **overlord** is up — sonnet, 3 skills'],
+      ['worker-feed', 20404, '🛠 Worker — scoping the card-persistence defect'],
+      ['issues-card', 20405, '**3 open issues** — #4571, #4576, #4580'],
+      ['rollout-status-post', 20402, 'Rolling v0.21.0 — 4/12 agents done'],
+      ['quota-watch.fleet-roll', 20407, 'Quota 61% — resets 09:00'],
+      ['permission_request', 20406, '**Approve** `docker restart switchroom-clerk`?'],
+    ]
+    for (const [verb, id, body] of verbs) {
+      observe(await sentRichCard(id, body), { chat_id: CHAT, verb })
+    }
+    for (const [verb, id, body] of verbs) {
+      const row = lookupMessageRoleAndText(CHAT, id, { includeSystem: true })
+      expect(`${verb}:${row?.text.length ?? 0}`).not.toBe(`${verb}:0`)
+      expect(row?.text).toBe(body)
+    }
+    // No card row anywhere in the buffer is bodiless — the fleet-wide invariant
+    // the shipped release violated on 100% of its rows.
+    const cards = query({ chat_id: CHAT, limit: 100, include_system: true }).filter(
+      (r) => r.role === 'system',
+    )
+    expect(cards).toHaveLength(verbs.length)
+    expect(cards.filter((r) => r.text.length === 0)).toEqual([])
+  })
+})
+
 describe('the card lane does not pollute normal history reads', () => {
   it('query() (get_recent_messages) lists the conversation, never the cards', () => {
     const observe = makeObserver()