switchroom 0.12.28 → 0.13.0

package/telegram-plugin/gateway/prefix-warmup.ts

@@ -0,0 +1,123 @@
+/**
+ * Prefix-cache warmup turn — opt-in cold-start TTFO optimization.
+ *
+ * Per cold-start TTFO RFC (docs/rfcs/cold-start-ttfo.md, PR #1589),
+ * Option A. On every bridge-up after a restart, synthesize a synthetic
+ * inbound (`__WARMUP_PING__`, meta.source="warmup") and deliver it to
+ * the just-registered bridge. Claude processes the message — paying
+ * the full cold-cache cost on the synthetic turn — and responds
+ * `NO_REPLY` per the in-prompt instruction. The existing NO_REPLY
+ * suppression at `gateway.ts:5949` swallows the outbound.
+ *
+ * By the time the user's REAL next message arrives, Anthropic's prefix
+ * cache is warm and the user-perceived TTFO drops 4-8s on average.
+ *
+ * Phase 1 (this file): minimum-viable warmup. AGENT.md is NOT modified
+ * — the warmup TEXT carries the NO_REPLY instruction inline. Agent
+ * compliance is best-effort; non-compliant agents will emit a real
+ * reply to the primary chat (acceptable UX cost gated behind opt-in
+ * env var). Cooldown prevents the gymbro-style bridge-churn case from
+ * burning OAuth quota on every flap.
+ *
+ * Kill switch: `SWITCHROOM_PREFIX_WARMUP=1` opt-in (default OFF).
+ *
+ * Future PR (Phase 2): suppress 👀 reaction + progress card for
+ * meta.source="warmup" inbound; tag for Hindsight exclusion.
+ */
+
+import type { IpcClient } from './ipc-server.js'
+import type { InboundMessage } from './ipc-protocol.js'
+
+// Per cold-start RFC open-question #4: cooldown anchored on bridge-up
+// time; conservative 5-minute window catches gymbro-style 6-reconnects-
+// per-UAT-cycle without dropping legitimate every-restart warmups.
+const WARMUP_COOLDOWN_MS = 5 * 60_000
+
+const lastWarmupAtPerAgent = new Map<string, number>()
+
+export const WARMUP_TEXT =
+  '__WARMUP_PING__\n\nThis is a system prefix-cache warmup (not from a user). ' +
+  'Respond with exactly `NO_REPLY` and nothing else. ' +
+  'The gateway will suppress the response — no message will be sent to anyone.'
+
+export interface WarmupCtx {
+  readonly selfAgent: string
+  readonly client: IpcClient
+  readonly resolveBootTarget: () =>
+    | { chatId: string; threadId?: number | undefined }
+    | null
+  readonly log?: (line: string) => void
+  readonly now?: () => number
+}
+
+/**
+ * Fire a prefix-cache warmup if conditions are met. Idempotent within
+ * the cooldown window. Returns true when a warmup was actually sent.
+ *
+ * Conditions:
+ *   1. `SWITCHROOM_PREFIX_WARMUP=1` env var set (opt-in).
+ *   2. Cooldown elapsed for this agent (default 5 min).
+ *   3. A boot chat target resolves (no point warming without a chat).
+ *
+ * The warmup is delivered to `client.send()` directly — it bypasses
+ * the gateway's `handleInbound`, which gates on a real Telegram
+ * Context object. The bridge forwards to claude exactly as it would a
+ * Telegram message.
+ */
+export function maybeFireWarmup(ctx: WarmupCtx): boolean {
+  if (process.env.SWITCHROOM_PREFIX_WARMUP !== '1') return false
+
+  const log = ctx.log ?? ((line: string) => process.stderr.write(line))
+  const now = (ctx.now ?? Date.now)()
+
+  const lastAt = lastWarmupAtPerAgent.get(ctx.selfAgent) ?? 0
+  if (now - lastAt < WARMUP_COOLDOWN_MS) {
+    log(
+      `telegram gateway: prefix-warmup skipped agent=${ctx.selfAgent} ` +
+        `reason=cooldown last=${Math.round((now - lastAt) / 1000)}s ago\n`,
+    )
+    return false
+  }
+
+  const target = ctx.resolveBootTarget()
+  if (!target) {
+    log(
+      `telegram gateway: prefix-warmup skipped agent=${ctx.selfAgent} ` +
+        `reason=no-boot-chat-target\n`,
+    )
+    return false
+  }
+
+  const msg: InboundMessage = {
+    type: 'inbound',
+    chatId: target.chatId,
+    ...(target.threadId !== undefined ? { threadId: target.threadId } : {}),
+    messageId: 0, // synthetic — never matches a real Telegram message
+    user: 'switchroom-warmup',
+    userId: 0,
+    ts: Math.floor(now / 1000),
+    text: WARMUP_TEXT,
+    meta: { source: 'warmup' },
+  }
+
+  try {
+    ctx.client.send(msg)
+    lastWarmupAtPerAgent.set(ctx.selfAgent, now)
+    log(
+      `telegram gateway: prefix-warmup fired agent=${ctx.selfAgent} ` +
+        `chat=${target.chatId} thread=${target.threadId ?? '-'}\n`,
+    )
+    return true
+  } catch (err) {
+    log(
+      `telegram gateway: prefix-warmup send threw agent=${ctx.selfAgent}: ` +
+        `${(err as Error).message}\n`,
+    )
+    return false
+  }
+}
+
+/** Test hook: reset the cooldown state. */
+export function __resetForTests(): void {
+  lastWarmupAtPerAgent.clear()
+}

package/telegram-plugin/stream-reply-handler.ts

@@ -514,7 +514,9 @@ export async function handleStreamReply(
       threadId,
       parseMode,
       disableLinkPreview: deps.disableLinkPreview,
-      throttleMs: deps.throttleMs ?? 600,
+      // PR B: pass undefined when caller didn't override, so draft-stream's
+      // transport-aware default (300 ms draft / 1000 ms message) wins.
+      ...(deps.throttleMs != null ? { throttleMs: deps.throttleMs } : {}),
       retry: deps.retry,
       ...(replyToMessageId != null ? { replyToMessageId } : {}),
       ...(args.quote_text != null && replyToMessageId != null ? { quoteText: args.quote_text } : {}),

package/telegram-plugin/tests/draft-stream.test.ts

@@ -749,4 +749,457 @@ describe('createDraftStream — draft transport', () => {
     expect(callCount).toBeGreaterThan(1) // draft update + failed clear attempt
   })
 
+  // ─── PR A observability: gw-trace stream-start / stream-end ───────────
+  describe('gw-trace stream-start / stream-end', () => {
+    let captured: string[] = []
+    let originalWrite: typeof process.stderr.write
+
+    beforeEach(() => {
+      captured = []
+      originalWrite = process.stderr.write
+      process.stderr.write = ((chunk: string | Uint8Array) => {
+        const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+        captured.push(text)
+        return true
+      }) as typeof process.stderr.write
+    })
+    afterEach(() => {
+      process.stderr.write = originalWrite
+    })
+
+    it('emits stream-start with resolved transport=draft on dm + draftApi', async () => {
+      const m = makeMock()
+      const draftApi = vi.fn(async () => ({ ok: true }))
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 1000,
+        previewTransport: 'draft',
+        sendMessageDraft: draftApi,
+        chatId: 'chat-X',
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toBeDefined()
+      expect(trace).toContain('transport=draft')
+      expect(trace).toContain('reason=draft')
+      expect(trace).toContain('api=available')
+      expect(trace).toContain('chatId=chat-X')
+      await stream.finalize()
+    })
+
+    it('emits stream-start with reason=auto-non-dm when isPrivateChat is false', async () => {
+      const m = makeMock()
+      const draftApi = vi.fn(async () => ({ ok: true }))
+      createDraftStream(m.send, m.edit, {
+        throttleMs: 1000,
+        previewTransport: 'auto',
+        isPrivateChat: false,
+        sendMessageDraft: draftApi,
+        chatId: 'chat-Y',
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toBeDefined()
+      expect(trace).toContain('transport=message')
+      expect(trace).toContain('reason=auto-non-dm')
+    })
+
+    it('emits stream-end with fire counts on finalize', async () => {
+      const m = makeMock()
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'message',
+      })
+      void stream.update('first')
+      await microtaskFlush()
+      await stream.finalize()
+      const trace = captured.find((c) => c.includes('gw-trace stream-end'))
+      expect(trace).toBeDefined()
+      expect(trace).toContain('transport=message')
+      expect(trace).toMatch(/sends=[1-9]/)
+      expect(trace).toContain('firstFireMs=')
+      expect(trace).toContain('durationMs=')
+    })
+
+    it('SWITCHROOM_STREAM_TRACES=0 suppresses both traces', async () => {
+      const prev = process.env.SWITCHROOM_STREAM_TRACES
+      process.env.SWITCHROOM_STREAM_TRACES = '0'
+      try {
+        const m = makeMock()
+        const stream = createDraftStream(m.send, m.edit, {
+          throttleMs: 50,
+          previewTransport: 'message',
+        })
+        await stream.finalize()
+        expect(captured.find((c) => c.includes('gw-trace stream-'))).toBeUndefined()
+      } finally {
+        if (prev === undefined) delete process.env.SWITCHROOM_STREAM_TRACES
+        else process.env.SWITCHROOM_STREAM_TRACES = prev
+      }
+    })
+  })
+
+  // ─── PR B: transport-aware throttle defaults ──────────────────────────
+  describe('transport-aware throttle defaults (PR B)', () => {
+    let captured: string[] = []
+    let originalWrite: typeof process.stderr.write
+
+    beforeEach(() => {
+      captured = []
+      originalWrite = process.stderr.write
+      process.stderr.write = ((chunk: string | Uint8Array) => {
+        const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+        captured.push(text)
+        return true
+      }) as typeof process.stderr.write
+    })
+    afterEach(() => {
+      process.stderr.write = originalWrite
+    })
+
+    it('draft transport defaults to 300ms throttle (sub-second)', () => {
+      const m = makeMock()
+      const draftApi = vi.fn(async () => ({ ok: true }))
+      createDraftStream(m.send, m.edit, {
+        previewTransport: 'draft',
+        sendMessageDraft: draftApi,
+        chatId: 'c1',
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toBeDefined()
+      expect(trace).toContain('throttleMs=300')
+    })
+
+    it('message transport defaults to 1000ms throttle', () => {
+      const m = makeMock()
+      createDraftStream(m.send, m.edit, {
+        previewTransport: 'message',
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toBeDefined()
+      expect(trace).toContain('throttleMs=1000')
+    })
+
+    it('auto + DM + draftApi resolves to draft default (300ms)', () => {
+      const m = makeMock()
+      const draftApi = vi.fn(async () => ({ ok: true }))
+      createDraftStream(m.send, m.edit, {
+        previewTransport: 'auto',
+        isPrivateChat: true,
+        sendMessageDraft: draftApi,
+        chatId: 'c1',
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toContain('throttleMs=300')
+    })
+
+    it('auto + non-DM resolves to message default (1000ms)', () => {
+      const m = makeMock()
+      const draftApi = vi.fn(async () => ({ ok: true }))
+      createDraftStream(m.send, m.edit, {
+        previewTransport: 'auto',
+        isPrivateChat: false,
+        sendMessageDraft: draftApi,
+        chatId: 'c1',
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toContain('throttleMs=1000')
+    })
+
+    it('explicit config.throttleMs wins over transport default', () => {
+      const m = makeMock()
+      const draftApi = vi.fn(async () => ({ ok: true }))
+      createDraftStream(m.send, m.edit, {
+        previewTransport: 'draft',
+        sendMessageDraft: draftApi,
+        chatId: 'c1',
+        throttleMs: 500,
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toContain('throttleMs=500')
+    })
+
+    it('explicit override below MIN_THROTTLE_MS is floored at 250', () => {
+      const m = makeMock()
+      createDraftStream(m.send, m.edit, {
+        previewTransport: 'message',
+        throttleMs: 100,
+      })
+      const trace = captured.find((c) => c.includes('gw-trace stream-start'))
+      expect(trace).toContain('throttleMs=250')
+    })
+  })
+
+  // ─── PR C: persist-then-continue chain at 25s / 4000-char boundary ───
+  describe('persist-chain (PR C)', () => {
+    let captured: string[] = []
+    let originalWrite: typeof process.stderr.write
+
+    beforeEach(() => {
+      // Outer describe sets useFakeTimers; keep that and drive time with
+      // advanceTimersByTimeAsync. The size-trigger doesn't need time at
+      // all (it fires on tail length); the time-trigger tests advance.
+      captured = []
+      originalWrite = process.stderr.write
+      process.stderr.write = ((chunk: string | Uint8Array) => {
+        const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+        captured.push(text)
+        return true
+      }) as typeof process.stderr.write
+    })
+    afterEach(() => {
+      process.stderr.write = originalWrite
+    })
+
+    it('size-trigger: persist fires when tail crosses persistSizeLimit', async () => {
+      const m = makeMock()
+      const sendMessageDraft = vi.fn(async () => {})
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'draft',
+        sendMessageDraft,
+        chatId: 'chat-size',
+        persistSizeLimit: 200, // small for tests
+      })
+
+      // First update: 100 chars, below threshold. Drafts.
+      void stream.update('a'.repeat(100))
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      // Second update: 250 chars total, tail exceeds 200 → size persist.
+      void stream.update('a'.repeat(250))
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      await microtaskFlush(20)
+      await stream.finalize()
+
+      const persistLine = captured.find((c) => c.includes('gw-trace stream-persist'))
+      expect(persistLine).toBeDefined()
+      expect(persistLine).toContain('reason=size')
+      expect(m.sendCalls.length).toBeGreaterThan(0)
+    })
+
+    it('time-trigger: persist fires after persistIntervalMs elapsed', async () => {
+      const m = makeMock()
+      const sendMessageDraft = vi.fn(async () => {})
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'draft',
+        sendMessageDraft,
+        chatId: 'chat-time',
+        persistIntervalMs: 200, // small for tests
+      })
+
+      void stream.update('first chunk text')
+      await microtaskFlush(20)
+      // Advance past the time trigger.
+      vi.advanceTimersByTime(250); await microtaskFlush(20)
+      void stream.update('first chunk text continues')
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      await microtaskFlush(20)
+      await stream.finalize()
+
+      const persistLine = captured.find((c) => c.includes('gw-trace stream-persist'))
+      expect(persistLine).toBeDefined()
+      expect(persistLine).toContain('reason=time')
+    })
+
+    it('persist bumps persists counter in stream-end trace', async () => {
+      const m = makeMock()
+      const sendMessageDraft = vi.fn(async () => {})
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'draft',
+        sendMessageDraft,
+        chatId: 'chat-2',
+        persistSizeLimit: 100,
+      })
+
+      void stream.update('x'.repeat(50))
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      void stream.update('x'.repeat(150))
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      await microtaskFlush(20)
+      await stream.finalize()
+
+      const endLine = captured.find((c) => c.includes('gw-trace stream-end'))
+      expect(endLine).toBeDefined()
+      expect(endLine).toMatch(/persists=[1-9]/)
+    })
+
+    it('finalize only materializes the unpersisted tail (no duplicate)', async () => {
+      const m = makeMock()
+      const sendMessageDraft = vi.fn(async () => {})
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'draft',
+        sendMessageDraft,
+        chatId: 'chat-3',
+        persistSizeLimit: 200,
+      })
+
+      void stream.update('a'.repeat(100))
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      void stream.update('a'.repeat(250)) // size trigger fires
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      await microtaskFlush(20)
+      const persistsBefore = m.sendCalls.length
+      expect(persistsBefore).toBeGreaterThan(0)
+
+      // Now add a small tail and finalize. The tail-only send should
+      // be much smaller than 250 — only post-persist content.
+      void stream.update('a'.repeat(250) + 'tail')
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(300); await microtaskFlush(20)
+      await stream.finalize()
+
+      const lastSend = m.sendCalls[m.sendCalls.length - 1]
+      expect(lastSend).toBeDefined()
+      // Without PR C, finalize would re-send the entire 250+ chars.
+      expect(lastSend!.text.length).toBeLessThan(50)
+    })
+
+    it('message-transport stream has persists=0 (no chunking)', async () => {
+      const m = makeMock()
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'message',
+      })
+      void stream.update('z'.repeat(3000))
+      await microtaskFlush(20)
+      await stream.finalize()
+      const endLine = captured.find((c) => c.includes('gw-trace stream-end'))
+      expect(endLine).toContain('persists=0')
+    })
+  })
+
+  // ─── PR D: 429 + non-true return fallback robustness ──────────────────
+  describe('429 + non-true fallback (PR D)', () => {
+    it('429 on draft falls back to message transport (no further draft fires)', async () => {
+      const m = makeMock()
+      let draftCalls = 0
+      const sendMessageDraft = vi.fn(async () => {
+        draftCalls++
+        const err = new Error('sendMessageDraft: Too Many Requests: retry after 3') as Error & {
+          error_code?: number
+          method?: string
+          parameters?: { retry_after?: number }
+        }
+        err.error_code = 429
+        err.method = 'sendMessageDraft'
+        err.parameters = { retry_after: 3 }
+        throw err
+      })
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'draft',
+        sendMessageDraft,
+        chatId: 'chat-429',
+      })
+
+      void stream.update('hello')
+      await microtaskFlush(20)
+      expect(draftCalls).toBe(1)
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(3500)
+      await microtaskFlush(20)
+      await stream.finalize()
+      expect(m.sendCalls.length).toBeGreaterThanOrEqual(1)
+      // sendMessageDraft was NOT called again after the 429.
+      expect(draftCalls).toBe(1)
+    })
+
+    it('non-true (false) return from sendMessageDraft triggers fallback', async () => {
+      const m = makeMock()
+      let draftCalls = 0
+      const sendMessageDraft = vi.fn(async () => {
+        draftCalls++
+        return false
+      })
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'draft',
+        sendMessageDraft,
+        chatId: 'chat-nonbool',
+      })
+      void stream.update('content')
+      await microtaskFlush(20)
+      expect(draftCalls).toBe(1)
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(100)
+      await microtaskFlush(20)
+      await stream.finalize()
+      // Subsequent updates / finalize do NOT re-invoke sendMessageDraft.
+      expect(draftCalls).toBe(1)
+      expect(m.sendCalls.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it('undefined return is treated as success (does not trigger fallback)', async () => {
+      // grammY's typed wrapper sometimes returns void/undefined on
+      // success. We must not false-positive fallback on those.
+      const m = makeMock()
+      let draftCalls = 0
+      const sendMessageDraft = vi.fn(async () => {
+        draftCalls++
+        return undefined
+      })
+      const stream = createDraftStream(m.send, m.edit, {
+        throttleMs: 50,
+        previewTransport: 'draft',
+        sendMessageDraft,
+        chatId: 'chat-undef',
+      })
+      void stream.update('first')
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(100)
+      void stream.update('second')
+      await microtaskFlush(20)
+      vi.advanceTimersByTime(100)
+      await microtaskFlush(20)
+      await stream.finalize()
+      expect(draftCalls).toBeGreaterThan(1)
+    })
+
+    it('429 path increments fallbacks counter (visible in stream-end trace)', async () => {
+      const captured: string[] = []
+      const originalWrite = process.stderr.write
+      process.stderr.write = ((chunk: string | Uint8Array) => {
+        const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+        captured.push(text)
+        return true
+      }) as typeof process.stderr.write
+      try {
+        const m = makeMock()
+        const sendMessageDraft = vi.fn(async () => {
+          const err = new Error('429') as Error & {
+            error_code?: number
+            method?: string
+            parameters?: { retry_after?: number }
+          }
+          err.error_code = 429
+          err.method = 'sendMessageDraft'
+          err.parameters = { retry_after: 2 }
+          throw err
+        })
+        const stream = createDraftStream(m.send, m.edit, {
+          throttleMs: 50,
+          previewTransport: 'draft',
+          sendMessageDraft,
+          chatId: 'chat-429-trace',
+        })
+        void stream.update('text')
+        await microtaskFlush(20)
+        vi.advanceTimersByTime(3000)
+        await stream.finalize()
+        const endLine = captured.find((c) => c.includes('gw-trace stream-end'))
+        expect(endLine).toBeDefined()
+        expect(endLine).toMatch(/fallbacks=[1-9]/)
+      } finally {
+        process.stderr.write = originalWrite
+      }
+    })
+  })
+
 })

package/telegram-plugin/tests/draft-transport.test.ts

@@ -9,6 +9,8 @@ import {
   shouldFallbackFromDraftTransport,
   allocateDraftId,
   __resetDraftIdForTests,
+  extractDraft429RetryAfterSecs,
+  isDraft429,
 } from '../draft-transport.js'
 
 describe('DRAFT_METHOD_UNAVAILABLE_RE', () => {
@@ -139,3 +141,71 @@ describe('allocateDraftId', () => {
     expect(allocateDraftId()).toBe(1)
   })
 })
+
+// ─── PR D: 429 + non-True helpers ──────────────────────────────────────
+
+describe('extractDraft429RetryAfterSecs (PR D)', () => {
+  it('returns retry_after on a grammY 429', () => {
+    const err = { error_code: 429, parameters: { retry_after: 7 } }
+    expect(extractDraft429RetryAfterSecs(err)).toBe(7)
+  })
+
+  it('returns null on non-429 error_code', () => {
+    const err = { error_code: 400, parameters: { retry_after: 7 } }
+    expect(extractDraft429RetryAfterSecs(err)).toBeNull()
+  })
+
+  it('returns null when retry_after is missing', () => {
+    const err = { error_code: 429 }
+    expect(extractDraft429RetryAfterSecs(err)).toBeNull()
+  })
+
+  it('returns null when retry_after is non-positive', () => {
+    expect(extractDraft429RetryAfterSecs({ error_code: 429, parameters: { retry_after: 0 } })).toBeNull()
+    expect(extractDraft429RetryAfterSecs({ error_code: 429, parameters: { retry_after: -1 } })).toBeNull()
+  })
+
+  it('returns null on primitive errors', () => {
+    expect(extractDraft429RetryAfterSecs(null)).toBeNull()
+    expect(extractDraft429RetryAfterSecs(undefined)).toBeNull()
+    expect(extractDraft429RetryAfterSecs('boom')).toBeNull()
+    expect(extractDraft429RetryAfterSecs(42)).toBeNull()
+  })
+})
+
+describe('isDraft429 (PR D)', () => {
+  it('returns true when 429 carries method=sendMessageDraft', () => {
+    const err = {
+      error_code: 429,
+      parameters: { retry_after: 5 },
+      method: 'sendMessageDraft',
+    }
+    expect(isDraft429(err)).toBe(true)
+  })
+
+  it('returns true when 429 description mentions sendMessageDraft', () => {
+    const err = {
+      error_code: 429,
+      parameters: { retry_after: 5 },
+      description: 'sendMessageDraft: Too Many Requests: retry after 5',
+    }
+    expect(isDraft429(err)).toBe(true)
+  })
+
+  it('returns false on 429 from a different method', () => {
+    const err = {
+      error_code: 429,
+      parameters: { retry_after: 5 },
+      method: 'sendMessage',
+    }
+    expect(isDraft429(err)).toBe(false)
+  })
+
+  it('returns false on non-429 errors even when mentioning sendMessageDraft', () => {
+    const err = {
+      error_code: 400,
+      description: 'sendMessageDraft: bad request',
+    }
+    expect(isDraft429(err)).toBe(false)
+  })
+})