switchroom 0.21.3 → 0.21.5

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

@@ -5,8 +5,10 @@
  * standalone foreman bot before its retirement.
  *
  * What lives here:
- *   - `installTgPostLogger` / `installRichMarkdownGuard` — the grammy API
- *     transformers every outbound call transits.
+ *   - `installTgPostLogger` / `installRichMarkdownGuard` /
+ *     `installSystemMessageObserver` — the grammy API transformers every
+ *     outbound call transits. This layer, not any caller-side wrapper, is the
+ *     one seam no `ctx.*` helper or raw `bot.api.*` call can bypass.
  *   - `makeSwitchroomExec` / `makeSwitchroomExecCombined` — factory fns for
  *     the switchroom CLI exec helpers (callers pass their own CLI path / config
  *     env so each process can be configured independently).
@@ -292,6 +294,121 @@ export function installRichMarkdownGuard(bot: Bot): void {
   })
 }
 
+// ─── outbound send observation (#4571 / #4599) ────────────────────────────
+
+/**
+ * The call-site metadata a send observer wants but the wire payload cannot
+ * supply. Structurally the same shape as `ObservedCallOpts` in
+ * `gateway/system-message-observer.ts`; declared here so this module keeps its
+ * no-imports-from-gateway rule.
+ */
+export interface TgSendContext {
+  chat_id?: string
+  threadId?: number
+  /** The caller's own label for what this send IS (`activity-summary.send`). */
+  verb?: string
+}
+
+const sendContextStore = new AsyncLocalStorage<TgSendContext | undefined>()
+
+/**
+ * Publish the enclosing call's `{chat_id, threadId, verb}` to the API
+ * transformer layer for the duration of `fn`'s async chain. `gateway.ts`'s
+ * `robustApiCall` wraps every call it issues; anything sent outside it (a
+ * `ctx.reply*` helper, a raw `bot.api.*`) simply observes with no verb.
+ */
+export function withTgSendContext<T>(ctx: TgSendContext | undefined, fn: () => T): T {
+  return sendContextStore.run(ctx, fn)
+}
+
+/** Exposed for the transformer (and tests). Undefined outside a wrapped call. */
+export function _getTgSendContext(): TgSendContext | undefined {
+  return sendContextStore.getStore()
+}
+
+/**
+ * Install the card-history send observer as a grammy API TRANSFORMER — the
+ * real universal outbound seam (#4599).
+ *
+ * #4571 hooked the observer onto `gateway.ts`'s `robustApiCall`, and
+ * `system-message-observer.ts` claimed that was "the ONE chokepoint every
+ * gateway outbound already goes through … enforced by the
+ * `check-bot-api-wrapping` lint guard". That claim was false on both halves.
+ * grammY's `ctx.*` sugar builds the payload and calls `bot.api.*` directly, so
+ * `switchroomReply` (`gateway.ts`, the helper every SLASH-COMMAND card answers
+ * through — `/usage`, `/model`, `/auth`, `/approvals`, `/start`, `/help`) sends
+ * via `ctx.replyWithRichMessage` and never transits `robustApiCall` at all; and
+ * the lint guard could not have caught it, because its verb pattern matched
+ * only `(bot|lockedBot|ctx)\.api\.<verb>` — it never mentioned `sendRichMessage`
+ * and structurally cannot match a `ctx.replyWith*` helper.
+ *
+ * Measured, not inferred: on a live agent's buffer the `/usage` card at id
+ * 20938 left NO row, while the `tg-post` transformer in this very file logged
+ * its `sendRichMessage` POST. The transformer layer SAW the send the recorder
+ * missed. That is the whole argument for moving here: grammy resolves this
+ * chain immediately around the HTTP POST, below every helper, every `ctx.*`
+ * shorthand, `lockedBot`, and `bot.api.raw` — there is no call shape that
+ * reaches Telegram without passing through it, so no future verb can silently
+ * opt out the way `switchroomReply` did.
+ *
+ * `observe` is injected rather than imported: this module must not depend on
+ * anything under `gateway/` (see the file header). The caller keeps ownership
+ * of the history writers, the `isGatewayMain && HISTORY_ENABLED` gate, and the
+ * empty-body alarm.
+ *
+ * Only a RESOLVED, `ok:true` response is observed. grammy hands this chain the
+ * raw `ApiResponse` and converts `{ok:false}` into a thrown `GrammyError` only
+ * after the chain returns (see `installTgPostLogger`'s docblock), so a
+ * rejection arrives here as a resolved body and must be skipped — recording a
+ * Telegram error object as a card body is exactly the empty-row failure #4576
+ * was. Non-message results (`getUpdates` arrays, `getMe`, `true` from
+ * `answerCallbackQuery`) are filtered by the observer's own shape test.
+ *
+ * Pure observation: the response is returned untouched and nothing here can
+ * throw into the send path.
+ */
+export function installSystemMessageObserver(
+  bot: Bot,
+  observe: (result: unknown, opts?: TgSendContext) => void,
+): void {
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    const res = await prev(method, payload, signal)
+    try {
+      const r = res as unknown as { ok?: boolean; result?: unknown }
+      if (r != null && typeof r === 'object' && r.ok === true) {
+        observe(r.result, resolveSendContext(payload))
+      }
+    } catch {
+      /* observing a send must never break the send */
+    }
+    return res
+  })
+}
+
+/**
+ * Merge the caller-published context with what the outbound PAYLOAD itself
+ * carries. The context wins where both exist (it is the caller's own intent);
+ * the payload is what keeps an unwrapped `ctx.reply*` send attributable to a
+ * chat and topic at all. The response's own `chat.id` still outranks both
+ * downstream — this is only the fallback tier.
+ */
+function resolveSendContext(payload: unknown): TgSendContext | undefined {
+  const ctx = sendContextStore.getStore()
+  const p = (payload ?? {}) as Record<string, unknown>
+  const rawChat = p.chat_id
+  const chat_id =
+    ctx?.chat_id ??
+    (typeof rawChat === 'string' || typeof rawChat === 'number' ? String(rawChat) : undefined)
+  const rawThread = p.message_thread_id
+  const threadId = ctx?.threadId ?? (typeof rawThread === 'number' ? rawThread : undefined)
+  if (chat_id == null && threadId == null && ctx?.verb == null) return undefined
+  return {
+    ...(chat_id != null ? { chat_id } : {}),
+    ...(threadId != null ? { threadId } : {}),
+    ...(ctx?.verb != null ? { verb: ctx.verb } : {}),
+  }
+}
+
 // ─── robustApiCall factory: REMOVED (#3863) ───────────────────────────────
 //
 // `createRobustApiCall` used to live here as a second `createRetryApiCall`

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

@@ -49,8 +49,13 @@ 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 { Bot, Context } from 'grammy'
+import {
+  installRichMarkdownGuard,
+  installSystemMessageObserver,
+  makeSwitchroomReply,
+  withTgSendContext,
+} from '../shared/bot-runtime.js'
 import { installSentTextCapture } from '../shared/sent-text-capture.js'
 import { richMessage } from '../rich-send.js'
 
@@ -317,6 +322,170 @@ describe('#4576: the stored card body is NOT empty — real sendRichMessage resp
   })
 })
 
+describe('#4599: the SLASH-COMMAND card path is recorded too', () => {
+  const BOT_INFO = {
+    id: 123456, is_bot: true as const, 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,
+  }
+
+  /**
+   * The gateway's REAL transformer stack with the observer installed exactly
+   * where gateway.ts installs it (after `installSentTextCapture`), transport
+   * stubbed to answer with the true `Message.RichMessageMessage` shape echoing
+   * the markdown that was actually POSTed.
+   *
+   * `editMessageText` re-uses the `message_id` in the payload, so an edit
+   * returns the id it edited — the shape the observer's send-vs-edit rule
+   * depends on.
+   */
+  function makeCardBot(observe: (result: unknown, opts?: { verb?: string }) => void) {
+    let nextId = 30_000
+    const posted: string[] = []
+    const fakeFetch = (async (_url: unknown, init: { body?: string } | undefined) => {
+      const payload = JSON.parse(String(init?.body ?? '{}')) as Record<string, unknown>
+      posted.push(String(payload.__method__ ?? ''))
+      const rich = payload.rich_message as { markdown?: unknown } | undefined
+      const id = typeof payload.message_id === 'number' ? payload.message_id : nextId++
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({
+          ok: true,
+          result: {
+            message_id: id,
+            date: 0,
+            chat: { id: Number(CHAT), type: 'private' },
+            ...(typeof rich?.markdown === 'string'
+              ? { rich_message: { blocks: [{ type: 'paragraph', text: { text: rich.markdown } }] } }
+              : { text: String(payload.text ?? '') }),
+          },
+        }),
+      } as unknown as Response
+    }) as unknown as typeof fetch
+
+    const bot = new Bot('123456:TEST_TOKEN', { botInfo: BOT_INFO, client: { fetch: fakeFetch } })
+    installRichMarkdownGuard(bot)
+    installSentTextCapture(bot)
+    installSystemMessageObserver(bot, observe)
+    return { bot, posted }
+  }
+
+  /** A grammy Context for an inbound `/usage`, as the command handler receives it. */
+  function makeCtx(bot: Bot): Context {
+    return new Context(
+      {
+        update_id: 1,
+        message: {
+          message_id: 20_930,
+          date: 0,
+          chat: { id: Number(CHAT), type: 'private' as const },
+          from: { id: 111, is_bot: false, first_name: 'Alice' },
+          text: '/usage',
+        },
+      } as never,
+      bot.api,
+      BOT_INFO,
+    )
+  }
+
+  it('a /usage card sent via switchroomReply leaves exactly one non-empty row', async () => {
+    // THE #4599 DEFECT, pinned. `switchroomReply` answers every slash command
+    // through `ctx.replyWithRichMessage`, which builds its own payload and calls
+    // `bot.api.*` directly — it never transits `robustApiCall`, where the #4571
+    // recorder was hooked. Measured on a live agent: the `/usage` card at id
+    // 20938 left no row, so a quote-reply to it resolved to nothing. A recorder
+    // that only sees `robustApiCall` cannot pass this test.
+    const observe = makeObserver()
+    const { bot } = makeCardBot(observe)
+    const switchroomReply = makeSwitchroomReply(() => undefined)
+    const BODY = 'Usage this week — Opus 41 percent, Sonnet 12 percent'
+
+    await switchroomReply(makeCtx(bot), BODY, { html: true })
+
+    const cards = query({ chat_id: CHAT, limit: 50, include_system: true }).filter(
+      (r) => r.role === 'system',
+    )
+    expect(cards).toHaveLength(1)
+    expect(cards[0]!.text).toBe(BODY)
+
+    // …and the quote-reply the operator actually makes now resolves.
+    const resolved = resolveReplyToFromBuffer({
+      replyToMessageId: cards[0]!.message_id,
+      replyToText: undefined,
+      replyToTextEscaped: undefined,
+      historyEnabled: true,
+      replyToTextMax: REPLY_TO_TEXT_MAX,
+      lookup: boundLookup,
+    })
+    expect(resolved.replyToRole).toBe('system')
+    expect(resolved.replyToText).toBe(BODY)
+  })
+
+  it('the PLAIN ctx.reply branch of switchroomReply is recorded as well', async () => {
+    const observe = makeObserver()
+    const { bot } = makeCardBot(observe)
+    const switchroomReply = makeSwitchroomReply(() => undefined)
+
+    await switchroomReply(makeCtx(bot), 'plain notice, no markdown', {})
+
+    const cards = query({ chat_id: CHAT, limit: 50, include_system: true }).filter(
+      (r) => r.role === 'system',
+    )
+    expect(cards).toHaveLength(1)
+    expect(cards[0]!.text).toBe('plain notice, no markdown')
+  })
+
+  it('a wrapped send keeps its verb → kind, and its edits do NOT add a second row', async () => {
+    // The behaviour the move must PRESERVE: `robustApiCall` publishes its verb
+    // through `withTgSendContext`, so the 117 live `role='system'` rows keep
+    // their `kind` (`activity-summary`, `worker-feed`, …) instead of degrading
+    // to null now that the recorder no longer sits on that wrapper.
+    let clock = 1_000
+    const observe = makeObserver(() => clock)
+    const { bot } = makeCardBot(observe)
+
+    const sent = await withTgSendContext({ chat_id: CHAT, verb: 'activity-summary.send' }, () =>
+      bot.api.sendRichMessage(Number(CHAT), richMessage('Working — 3 tools')),
+    )
+    const id = (sent as { message_id: number }).message_id
+
+    clock += 60_000
+    await withTgSendContext({ chat_id: CHAT, verb: 'activity-summary.edit' }, () =>
+      bot.api.editMessageText(Number(CHAT), id, richMessage('Working — 11 tools')),
+    )
+
+    const cards = query({ chat_id: CHAT, limit: 50, include_system: true }).filter(
+      (r) => r.role === 'system',
+    )
+    expect(cards).toHaveLength(1)
+    expect(cards[0]!.message_id).toBe(id)
+    expect(cards[0]!.kind).toBe('activity-summary')
+    expect(cards[0]!.text).toBe('Working — 11 tools')
+  })
+
+  it('a Telegram REJECTION is never recorded as a card', async () => {
+    // grammy resolves the transformer chain with the raw `{ok:false}` body and
+    // only throws afterwards, so a failed send reaches the observer as a
+    // RESOLVED response. Recording its error object would be #4576 all over.
+    const observe = makeObserver()
+    const failFetch = (async () =>
+      ({
+        ok: true,
+        status: 200,
+        json: async () => ({ ok: false, error_code: 400, description: 'chat not found' }),
+      }) as unknown as Response) as unknown as typeof fetch
+    const bot = new Bot('123456:TEST_TOKEN', { botInfo: BOT_INFO, client: { fetch: failFetch } })
+    installSystemMessageObserver(bot, observe)
+
+    await expect(
+      bot.api.sendRichMessage(Number(CHAT), richMessage('never lands')),
+    ).rejects.toThrow()
+    expect(query({ chat_id: CHAT, limit: 50, include_system: true })).toHaveLength(0)
+  })
+})
+
 describe('the card lane does not pollute normal history reads', () => {
   it('query() (get_recent_messages) lists the conversation, never the cards', () => {
     const observe = makeObserver()