switchroom 0.19.14 → 0.19.16

package/telegram-plugin/tests/forwarded-rich-message-coalesce.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Outcome regression (#3516 follow-up): a forwarded rich (bot) message MUST
+ * coalesce through the same sliding window as `message:text`.
+ *
+ * THE BUG: PR #3516 registered `message:rich_message` but wired it with
+ * `mediaEnvelopeDeps`, whose `handleInbound` is the BARE (non-coalescing)
+ * inbound function — the same surface the cluster-A media-envelope handlers
+ * (contact/location/poll/…) use. The sibling text/photo/voice/attachment
+ * handlers all route through `handleInboundCoalesced`. Result: a forwarded
+ * bot message arriving in the same coalesce window as another inbound
+ * message did NOT fold into one turn — it bypassed the window entirely,
+ * contradicting rich-message-handler.ts's own docstring ("hands it to the
+ * normal COALESCING inbound pipeline … identical to message:text").
+ *
+ * Two guards, both anchored to the real production code:
+ *
+ *   1. WIRING (source-parse, deterministic RED/GREEN): parse gateway.ts and
+ *      assert the deps object passed to the `message:rich_message`
+ *      registration binds `handleInbound` to `handleInboundCoalesced` (the
+ *      coalescing entry point), the SAME path `message:text` takes. This
+ *      guard is RED on the pre-fix wiring (`mediaEnvelopeDeps`, bare
+ *      `handleInbound`) and GREEN after it.
+ *
+ *   2. OUTCOME (real grammy Bot + real handler + real coalescer): drive the
+ *      production `handleRichMessageMessage` and `message:text` through one
+ *      shared `createInboundCoalescer` (the exact module gateway.ts uses),
+ *      and assert a rich message + a text message in the same window flush
+ *      as ONE ordered turn — and that the bare (non-coalescing) surface the
+ *      bug used would instead emit TWO turns.
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+import { Bot } from 'grammy'
+import type { Update } from 'grammy/types'
+import { resetUpdateCounters } from './update-factory.js'
+import { handleRichMessageMessage } from '../gateway/rich-message-handler.js'
+import type { MediaEnvelopeDeps } from '../gateway/media-message-handlers.js'
+import {
+  createInboundCoalescer,
+  inboundCoalesceKey,
+} from '../gateway/inbound-coalesce.js'
+
+// ---------------------------------------------------------------------------
+// Guard 1 — wiring source-parse
+// ---------------------------------------------------------------------------
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_PATH = resolve(__dirname, '..', 'gateway', 'gateway.ts')
+const GATEWAY_SRC = readFileSync(GATEWAY_PATH, 'utf8')
+const sourceFile = ts.createSourceFile(
+  GATEWAY_PATH,
+  GATEWAY_SRC,
+  ts.ScriptTarget.Latest,
+  true,
+  ts.ScriptKind.TS,
+)
+
+/** The deps argument (arg 2) of `bot.on('message:rich_message', ctx =>
+ * handleRichMessageMessage(ctx, DEPS))` as an AST node, or null. */
+function findRichMessageDepsArg(): ts.Expression | null {
+  let found: ts.Expression | null = null
+  const visit = (node: ts.Node): void => {
+    if (found) return
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      ts.isIdentifier(node.expression.expression) &&
+      node.expression.expression.text === 'bot' &&
+      node.expression.name.text === 'on'
+    ) {
+      const arg0 = node.arguments[0]
+      const evName = arg0 && ts.isStringLiteralLike(arg0) ? arg0.text : null
+      if (evName === 'message:rich_message') {
+        // arg1 is `ctx => handleRichMessageMessage(ctx, DEPS)`
+        const arg1 = node.arguments[1]
+        if (arg1 && (ts.isArrowFunction(arg1) || ts.isFunctionExpression(arg1))) {
+          const body = arg1.body
+          const inner = !ts.isBlock(body) && ts.isCallExpression(body) ? body : undefined
+          if (inner && inner.arguments.length >= 2) found = inner.arguments[1]
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return found
+}
+
+/** Resolve the deps arg to its source text — inline object literal directly,
+ * or the initializer of the `const <name> = { … }` it names. */
+function resolveDepsText(arg: ts.Expression): string | null {
+  if (ts.isObjectLiteralExpression(arg)) return arg.getText(sourceFile)
+  if (ts.isIdentifier(arg)) {
+    let text: string | null = null
+    const visit = (node: ts.Node): void => {
+      if (text) return
+      if (
+        ts.isVariableDeclaration(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === arg.text &&
+        node.initializer
+      ) {
+        text = node.initializer.getText(sourceFile)
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(sourceFile)
+    return text
+  }
+  return null
+}
+
+describe('wiring: message:rich_message dispatches through the coalescing path', () => {
+  it('the rich_message registration passes deps that bind handleInbound to handleInboundCoalesced', () => {
+    const depsArg = findRichMessageDepsArg()
+    expect(depsArg, 'could not locate the message:rich_message registration deps arg').not.toBeNull()
+
+    const depsText = resolveDepsText(depsArg as ts.Expression)
+    expect(depsText, 'could not resolve the rich_message deps source text').not.toBeNull()
+
+    // The coalescing entry point — the same one message:text routes through.
+    // Pre-fix the deps was `mediaEnvelopeDeps` (bare `handleInbound,`
+    // shorthand), so this assertion is RED on the bug and GREEN with the fix.
+    expect(depsText).toContain('handleInbound: handleInboundCoalesced')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Guard 2 — outcome: real handler + real coalescer
+//
+// NOTE: Guard 2 drives its OWN `richCoalesces` boolean toggle rather than
+// importing the gateway's dispatch wiring, so it validates the coalescer
+// CONTRACT (folding/ordering into one turn vs. the pre-fix split) — it is NOT
+// a wiring regression guard. Guard 1 (the AST/source-parse over gateway.ts) is
+// the SOLE guard that regresses if the rich_message registration stops routing
+// through `handleInboundCoalesced`.
+// ---------------------------------------------------------------------------
+
+const CHAT_ID = -1004223464247
+const USER_ID = 777
+
+function makeBotInfo() {
+  return {
+    id: 999,
+    is_bot: true,
+    first_name: 'TestBot',
+    username: 'test_bot',
+    can_join_groups: true,
+    can_read_all_group_messages: false,
+    supports_inline_queries: false,
+    can_connect_to_business: false,
+    has_main_web_app: false,
+  }
+}
+
+/** Forwarded rich (bot) message, no top-level text/caption — the live shape. */
+function makeForwardedRichUpdate(update_id: number, blocks: unknown[]): Update {
+  const originUser = { id: 8500000001, is_bot: true, first_name: 'Klanker', username: 'meken_klanker_bot' }
+  return {
+    update_id,
+    message: {
+      message_id: update_id,
+      chat: { id: CHAT_ID, type: 'supergroup', title: 'ProductOS', is_forum: true },
+      from: { id: USER_ID, is_bot: false, first_name: 'Ken' },
+      date: 1784837003,
+      forward_origin: { type: 'user', date: 1784830000, sender_user: originUser },
+      forward_from: originUser,
+      forward_date: 1784830000,
+      rich_message: { blocks },
+    },
+  } as unknown as Update
+}
+
+function makeTextUpdate(update_id: number, text: string): Update {
+  return {
+    update_id,
+    message: {
+      message_id: update_id,
+      chat: { id: CHAT_ID, type: 'supergroup', title: 'ProductOS', is_forum: true },
+      from: { id: USER_ID, is_bot: false, first_name: 'Ken' },
+      date: 1784837004,
+      text,
+    },
+  } as unknown as Update
+}
+
+interface HarnessOptions {
+  /** Bind the rich handler's dispatch to the coalescing path (the fix) or to
+   * the bare non-coalescing path (the pre-fix bug). */
+  richCoalesces: boolean
+}
+
+/**
+ * Wire a real grammy Bot the way the production gateway does: message:text
+ * enqueues into a shared coalescer; message:rich_message goes through the
+ * REAL production handler with deps whose `handleInbound` is bound to either
+ * the same coalescer (fix) or a bare immediate dispatch (bug).
+ */
+function buildHarness(opts: HarnessOptions) {
+  const flushed: string[] = []
+
+  // The exact coalescer module the gateway uses. 1500ms sliding window.
+  const coalescer = createInboundCoalescer<{ text: string }>({
+    gapMs: 1500,
+    merge: entries => ({ text: entries.map(e => e.text).join('\n') }),
+    onFlush: (_key, merged) => flushed.push(merged.text),
+  })
+
+  const key = inboundCoalesceKey(String(CHAT_ID), null, String(USER_ID))
+
+  /** Coalescing dispatch — mirrors handleInboundCoalesced's enqueue step. */
+  const coalescedDispatch = async (text: string): Promise<void> => {
+    const { bypass } = coalescer.enqueue(key, { text })
+    if (bypass) flushed.push(text)
+  }
+  /** Bare dispatch — the pre-fix bug: every message is its own turn. */
+  const bareDispatch = async (text: string): Promise<void> => {
+    flushed.push(text)
+  }
+
+  const bot = new Bot('12345:TEST_TOKEN_NOT_REAL')
+  bot.botInfo = makeBotInfo()
+
+  bot.on('message:text', async ctx => {
+    await coalescedDispatch(ctx.message.text)
+  })
+
+  const richDeps: MediaEnvelopeDeps = {
+    handleInbound: async (_ctx, text) => {
+      await (opts.richCoalesces ? coalescedDispatch(text) : bareDispatch(text))
+    },
+    handleAckOnly: async () => {},
+    handleRefusal: async () => {},
+    log: () => {},
+  }
+  bot.on('message:rich_message', ctx => handleRichMessageMessage(ctx, richDeps))
+
+  return { bot, flushed }
+}
+
+const BLOCKS = [{ type: 'paragraph', text: 'forwarded body from a bot' }]
+
+describe('outcome: forwarded rich message coalesces with a sibling inbound', () => {
+  beforeEach(() => {
+    resetUpdateCounters()
+    vi.useFakeTimers()
+  })
+  afterEach(() => vi.useRealTimers())
+
+  it('rich + text in the same window flush as ONE ordered turn (the fix)', async () => {
+    const { bot, flushed } = buildHarness({ richCoalesces: true })
+
+    await bot.handleUpdate(makeForwardedRichUpdate(9001, BLOCKS))
+    // A second inbound arrives 500ms later — inside the 1500ms window.
+    vi.advanceTimersByTime(500)
+    await bot.handleUpdate(makeTextUpdate(9002, 'and my own note about it'))
+
+    // Nothing flushed yet — the window is still open.
+    expect(flushed).toEqual([])
+
+    // Window closes 1500ms after the LAST message (sliding window).
+    vi.advanceTimersByTime(1500)
+
+    // ONE turn, both bodies, rich body first (arrival order preserved).
+    expect(flushed).toHaveLength(1)
+    expect(flushed[0]).toBe('forwarded body from a bot\nand my own note about it')
+  })
+
+  it('the pre-fix bare wiring would split them into TWO turns (bug characterization)', async () => {
+    const { bot, flushed } = buildHarness({ richCoalesces: false })
+
+    await bot.handleUpdate(makeForwardedRichUpdate(9003, BLOCKS))
+    // The rich message bypassed the window: it flushes immediately.
+    expect(flushed).toEqual(['forwarded body from a bot'])
+
+    vi.advanceTimersByTime(500)
+    await bot.handleUpdate(makeTextUpdate(9004, 'and my own note about it'))
+    vi.advanceTimersByTime(1500)
+
+    // Two separate turns — the fragmentation the fix eliminates.
+    expect(flushed).toEqual([
+      'forwarded body from a bot',
+      'and my own note about it',
+    ])
+  })
+})

package/telegram-plugin/tests/forwarded-rich-message.test.ts

@@ -0,0 +1,305 @@
+/**
+ * Outcome regression: forwarded-message body must reach the agent — never a
+ * placeholder (carrie history.db row message_id=944, 2026-07-24 06:03).
+ *
+ * THE BUG: a forwarded BOT message arrives as Bot API 10.1 `rich_message`
+ * content (the gateway sends everything via sendRichMessage) with NO
+ * top-level text/caption. Live gateway log (carrie, update_id=417526125):
+ *   content_keys=[forward_from,forward_date,rich_message] action=turn
+ * It matched no registered `message:*` handler, fell to the terminal
+ * catch-all, and the agent received
+ *   "(unhandled message content: forward_from)"
+ * instead of the forwarded token list. Two defects composed:
+ *   1. no `message:rich_message` registration (grammy ^1.44 supports it);
+ *   2. legacy `forward_*` wire keys were not in MESSAGE_ENVELOPE_KEYS, so
+ *      the placeholder was mislabeled with provenance, not content.
+ *
+ * These tests drive a REAL grammy 1.44 Bot through the REAL production
+ * modules (rich-message-handler + unhandled-message catch-all) in the
+ * gateway's registration order and assert the DELIVERED text — the outcome
+ * the agent actually receives. The key regression test was verified to FAIL
+ * on unfixed main (delivered text was the placeholder) and pass here.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Bot, type Context } from 'grammy'
+import type { Update } from 'grammy/types'
+import { makeMessageUpdate, resetUpdateCounters } from './update-factory.js'
+import { installUnhandledMessageCatchAll } from '../gateway/unhandled-message.js'
+import {
+  handleRichMessageMessage,
+  extractRichMessageText,
+  RICH_MESSAGE_EMPTY_TEXT,
+} from '../gateway/rich-message-handler.js'
+import type { MediaEnvelopeDeps } from '../gateway/media-message-handlers.js'
+import { parseForwardOrigin, buildForwardOriginMeta } from '../gateway/forward-origin.js'
+
+const UNHANDLED_PLACEHOLDER_RE = /^\(unhandled message content: /
+
+interface Delivered {
+  via: string
+  text: string
+}
+
+/** Wire a real grammy Bot in the gateway's registration order: message:text,
+ * message:rich_message (real production handler), terminal catch-all LAST. */
+function buildHarness() {
+  const delivered: Delivered[] = []
+  const logLines: string[] = []
+  const bot = new Bot('12345:TEST_TOKEN_NOT_REAL')
+  bot.botInfo = {
+    id: 999,
+    is_bot: true,
+    first_name: 'TestBot',
+    username: 'test_bot',
+    can_join_groups: true,
+    can_read_all_group_messages: false,
+    supports_inline_queries: false,
+    can_connect_to_business: false,
+    has_main_web_app: false,
+  }
+
+  bot.on('message:text', async ctx => {
+    delivered.push({ via: 'text', text: ctx.message.text })
+  })
+  const richDeps: MediaEnvelopeDeps = {
+    handleInbound: async (_ctx, text) => {
+      delivered.push({ via: 'rich_message', text })
+    },
+    handleAckOnly: async () => {},
+    handleRefusal: async () => {},
+    log: line => logLines.push(line),
+  }
+  bot.on('message:rich_message', ctx => handleRichMessageMessage(ctx, richDeps))
+  installUnhandledMessageCatchAll(
+    bot,
+    async (_ctx: Context, text: string) => {
+      delivered.push({ via: 'catch-all', text })
+    },
+    line => logLines.push(line),
+  )
+  return { bot, delivered, logLines }
+}
+
+/** The forwarded-bot-message shape observed live (update_id=417526125):
+ * forward_origin (modern) + legacy forward_from/forward_date siblings +
+ * rich_message content, NO top-level text/caption. */
+function makeForwardedRichUpdate(update_id: number, blocks: unknown[]): Update {
+  const originUser = { id: 8500000001, is_bot: true, first_name: 'Klanker', username: 'meken_klanker_bot' }
+  return {
+    update_id,
+    message: {
+      message_id: 944,
+      chat: { id: -1004223464247, type: 'supergroup', title: 'ProductOS', is_forum: true },
+      from: { id: 777, is_bot: false, first_name: 'Ken' },
+      date: 1784837003,
+      forward_origin: { type: 'user', date: 1784830000, sender_user: originUser },
+      forward_from: originUser,
+      forward_date: 1784830000,
+      rich_message: { blocks },
+    },
+  } as unknown as Update
+}
+
+const TOKEN_LIST_BLOCKS = [
+  { type: 'paragraph', text: 'Try these tokens' },
+  {
+    type: 'list',
+    items: [
+      { label: '-', blocks: [{ type: 'paragraph', text: [{ type: 'code', text: 'tok_alpha_123' }] }] },
+      { label: '-', blocks: [{ type: 'paragraph', text: [{ type: 'code', text: 'tok_beta_456' }] }] },
+    ],
+  },
+]
+
+describe('forwarded rich (bot) message — the row-944 regression oracle', () => {
+  beforeEach(() => resetUpdateCounters())
+
+  it('delivers the REAL forwarded body — not the unhandled placeholder, not empty', async () => {
+    const { bot, delivered } = buildHarness()
+    await bot.handleUpdate(makeForwardedRichUpdate(417526125, TOKEN_LIST_BLOCKS))
+
+    expect(delivered).toHaveLength(1)
+    const turn = delivered[0]
+    // Bug-catcher oracle: real content in, real content out.
+    expect(turn.text.length).toBeGreaterThan(0)
+    expect(turn.text).not.toMatch(UNHANDLED_PLACEHOLDER_RE)
+    expect(turn.text).not.toContain('forward_from')
+    // The actual forwarded body the agent must receive.
+    expect(turn.text).toContain('Try these tokens')
+    expect(turn.text).toContain('tok_alpha_123')
+    expect(turn.text).toContain('tok_beta_456')
+  })
+
+  it('forward-origin metadata CO-ARRIVES on the trusted attr lane (not injected into the body)', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = makeForwardedRichUpdate(417526126, TOKEN_LIST_BLOCKS)
+    await bot.handleUpdate(update)
+
+    // The same server-stamped forward_origin the enqueue path parses
+    // (gateway.ts → parseForwardOrigin → buildForwardOriginMeta → meta attrs).
+    const origin = parseForwardOrigin(
+      (update as unknown as { message: { forward_origin: never } }).message.forward_origin,
+    )
+    const meta = buildForwardOriginMeta([origin!])
+    expect(meta.forwarded_from).toBe('Klanker (@meken_klanker_bot)')
+    expect(meta.forwarded_from_type).toBe('user')
+    expect(meta.forwarded_date).toBeDefined()
+    // Trusted-lane separation (#3162): the delivered BODY carries no
+    // provenance strings — those live only in the channel attrs.
+    expect(delivered[0].text).not.toContain('Klanker')
+  })
+
+  it('a rich message with genuinely no extractable text still yields an honest turn', async () => {
+    const { bot, delivered } = buildHarness()
+    await bot.handleUpdate(
+      makeForwardedRichUpdate(417526127, [{ type: 'divider' }, { type: 'anchor', name: 'top' }]),
+    )
+    expect(delivered).toHaveLength(1)
+    // Divider renders as ---; a fully empty tree gets the honest fallback.
+    expect(delivered[0].via).toBe('rich_message')
+    expect(delivered[0].text).not.toMatch(UNHANDLED_PLACEHOLDER_RE)
+  })
+
+  it('a truly empty rich message delivers the named fallback, never the mislabeled placeholder', async () => {
+    const { bot, delivered } = buildHarness()
+    await bot.handleUpdate(makeForwardedRichUpdate(417526128, []))
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0].text).toBe(RICH_MESSAGE_EMPTY_TEXT)
+  })
+
+  it('a NON-forwarded rich message (bot-to-bot, rich DM) also delivers its body', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = {
+      update_id: 417526129,
+      message: {
+        message_id: 950,
+        chat: { id: 777, type: 'private' },
+        from: { id: 777, is_bot: false, first_name: 'Ken' },
+        date: 1784837100,
+        rich_message: { blocks: [{ type: 'heading', size: 2, text: 'Release plan' }, { type: 'paragraph', text: 'Ship Friday.' }] },
+      },
+    } as unknown as Update
+    await bot.handleUpdate(update)
+    expect(delivered[0].text).toContain('Release plan')
+    expect(delivered[0].text).toContain('Ship Friday.')
+  })
+})
+
+describe('working shapes stay unchanged (no regression on existing forwards)', () => {
+  beforeEach(() => resetUpdateCounters())
+
+  it('plain user-text forward: full body via message:text + co-arriving origin meta', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = makeMessageUpdate({ text: 'here is the brief I forwarded', update_id: 7001 })
+    const msg = (update as unknown as { message: Record<string, unknown> }).message
+    msg.forward_origin = {
+      type: 'user',
+      date: 1_700_000_000,
+      sender_user: { id: 424242, is_bot: false, first_name: 'Ken', last_name: 'Thompson' },
+    }
+    await bot.handleUpdate(update)
+
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0]).toMatchObject({ via: 'text', text: 'here is the brief I forwarded' })
+    const meta = buildForwardOriginMeta([parseForwardOrigin(msg.forward_origin as never)!])
+    expect(meta.forwarded_from).toBe('Ken Thompson')
+    expect(meta.forwarded_date).toBeDefined()
+  })
+
+  it('hidden_user forward: full body, type=hidden_user, NO forwarded_from_id', async () => {
+    const { bot, delivered } = buildHarness()
+    const update = makeMessageUpdate({ text: 'anon tip: check the logs', update_id: 7002 })
+    const msg = (update as unknown as { message: Record<string, unknown> }).message
+    msg.forward_origin = { type: 'hidden_user', date: 1_700_000_000, sender_user_name: 'Mystery Sender' }
+    await bot.handleUpdate(update)
+
+    expect(delivered[0].text).toBe('anon tip: check the logs')
+    const meta = buildForwardOriginMeta([parseForwardOrigin(msg.forward_origin as never)!])
+    expect(meta.forwarded_from).toBe('Mystery Sender')
+    expect(meta.forwarded_from_type).toBe('hidden_user')
+    expect(meta.forwarded_from_id).toBeUndefined()
+  })
+
+  it('channel caption/media forward: caption is the body and forwarded_message_id deep-links the post (G2)', () => {
+    // The photo handler's body contract is `caption ?? '(photo)'`
+    // (photo-message-handler.ts) — assert the origin-meta side here.
+    const origin = parseForwardOrigin({
+      type: 'channel',
+      date: 1_700_000_000,
+      message_id: 555,
+      chat: { id: -100400500, type: 'channel', title: 'Release Notes', username: 'relnotes' } as never,
+    })
+    const meta = buildForwardOriginMeta([origin!])
+    expect(meta.forwarded_from).toBe('Release Notes (@relnotes)')
+    expect(meta.forwarded_from_type).toBe('channel')
+    expect(meta.forwarded_message_id).toBe('555')
+  })
+})
+
+describe('rich block rendering — deterministic text extraction', () => {
+  it('renders headings, lists with checkboxes, pre blocks, quotes, and tables', () => {
+    const text = extractRichMessageText({
+      blocks: [
+        { type: 'heading', size: 1, text: 'Plan' },
+        {
+          type: 'list',
+          items: [
+            { label: '1.', blocks: [{ type: 'paragraph', text: 'first' }], has_checkbox: true, is_checked: true },
+            { label: '2.', blocks: [{ type: 'paragraph', text: 'second' }], has_checkbox: true },
+          ],
+        },
+        { type: 'pre', language: 'python', text: 'print(1)' },
+        { type: 'blockquote', blocks: [{ type: 'paragraph', text: 'quoted line' }], credit: 'someone' },
+        { type: 'table', cells: [[{ text: 'A', align: 'left', valign: 'top' }, { text: 'B', align: 'left', valign: 'top' }]] },
+        { type: 'photo', photo: [], caption: { text: 'the screenshot' } },
+      ],
+    })
+    expect(text).toContain('Plan')
+    expect(text).toContain('1. [x] first')
+    expect(text).toContain('2. [ ] second')
+    expect(text).toContain('```python\nprint(1)\n```')
+    expect(text).toContain('> quoted line')
+    expect(text).toContain('> — someone')
+    expect(text).toContain('A | B')
+    expect(text).toContain('[photo] the screenshot')
+  })
+
+  it('flattens nested inline rich text (bold/url/custom emoji/math) to content', () => {
+    const text = extractRichMessageText({
+      blocks: [{
+        type: 'paragraph',
+        text: [
+          'see ',
+          { type: 'bold', text: [{ type: 'url', text: 'the docs', url: 'https://x' }] },
+          ' ',
+          { type: 'custom_emoji', custom_emoji_id: '1', alternative_text: '👍' },
+          ' ',
+          { type: 'mathematical_expression', expression: 'E=mc^2' },
+        ],
+      }],
+    })
+    expect(text).toBe('see the docs 👍 E=mc^2')
+  })
+
+  it('an unknown future block type surfaces its text instead of vanishing', () => {
+    expect(extractRichMessageText({ blocks: [{ type: 'hologram', text: 'future words' }] }))
+      .toBe('future words')
+  })
+
+  it('malformed / hostile payloads return undefined instead of throwing', () => {
+    expect(extractRichMessageText(undefined)).toBeUndefined()
+    expect(extractRichMessageText('nope')).toBeUndefined()
+    expect(extractRichMessageText({ blocks: 'nope' })).toBeUndefined()
+    // Deep self-nesting stops at the recursion cap, no stack overflow.
+    const deep: { type: string; blocks: unknown[] } = { type: 'blockquote', blocks: [] }
+    let cur = deep
+    for (let i = 0; i < 200; i++) {
+      const next = { type: 'blockquote', blocks: [] as unknown[] }
+      cur.blocks.push(next)
+      cur = next
+    }
+    cur.blocks.push({ type: 'paragraph', text: 'buried' })
+    expect(() => extractRichMessageText({ blocks: [deep] })).not.toThrow()
+  })
+})

package/telegram-plugin/tests/gateway-handler-registration-wiring.test.ts

@@ -107,6 +107,7 @@ const GOLDEN_REGISTRATIONS: readonly string[] = [
   'on:message:checklist_tasks_done',
   'on:message:checklist_tasks_added',
   'on:message:pinned_message',
+  'on:message:rich_message',
   'helper:installUnhandledMessageCatchAll',
   'on:message_reaction',
   'catch',