nebula-ai-plugin-telegram 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# nebula-ai-plugin-telegram
+
+Telegram channel for **nebula**. DM your bot from any phone; the agent replies —
+with the **same** policy → simulation → approval gates, surfaced as inline-keyboard
+approvals so you can authorize material-risk actions from your pocket.
+
+## Highlights
+
+- **Long-poll outbound only** — works without exposing an inbound port.
+- **Allowlisted DMs** — only configured `allowedUserIds` reach the brain.
+- **Reactions as feedback** — 👀 on processing start, 👍 on success, 👎 on error.
+- **Per-chat debounce** — a 600ms quiet window collapses fragmented typing into one turn.
+- **Rate-limited** — 30 messages / 60s per user via token bucket.
+- **Inline-keyboard approvals** — the operator approves risky tool calls from their phone.
+
+## Quickstart
+
+```bash
+# either: set TELEGRAM_BOT_TOKEN (+ optional TELEGRAM_CHAT_ID) in your env
+# or:     nebula telegram setup     # one-time interactive: bot token + allowed user IDs
+nebula                              # start the TUI; the listener boots automatically
+# DM your bot from your phone — the agent replies.
+```
+
+## Install
+
+Auto-installed with [`nebula-treasury`](https://www.npmjs.com/package/nebula-treasury).
+Or directly: `bun add nebula-ai-plugin-telegram`.
+
+Built on [grammy](https://grammy.dev) (TS-first, bun-compatible). See the
+[root README](https://github.com/rstfulzz/nebula#readme).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "nebula-ai-plugin-telegram",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Telegram channel for nebula — long-poll bot, debounced dispatch, inline-keyboard approvals, allowlist",
+  "license": "MIT",
+  "homepage": "https://github.com/rstfulzz/nebula",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rstfulzz/nebula.git",
+    "directory": "packages/plugin-telegram"
+  },
+  "bugs": {
+    "url": "https://github.com/rstfulzz/nebula/issues"
+  },
+  "keywords": [
+    "nebula",
+    "ai",
+    "agent",
+    "telegram",
+    "grammy",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "nebula-ai-core": "0.1.0",
+    "grammy": "^1.42.0",
+    "zod": "^3.23.8"
+  }
+}

package/src/approval-keyboard.ts

@@ -0,0 +1,108 @@
+// Inline-keyboard approval for tool calls when the active session is on TG.
+//
+// Pattern from hermes telegram.py:1080-1132 (button layout) + 1462-1473
+// (callback re-validation). 4 buttons in 2 rows: Once / Session / Always /
+// Deny. Callback data format: `ea:<once|session|always|deny>:<approvalId>`.
+//
+// The handler re-validates the clicker against `allowedUserIds` because
+// inline-keyboard buttons are visible to any chat-member but only authorized
+// users may click. One-shot pop pattern: the resolver Map drops the entry
+// after the first match so a stale double-click can't re-resolve.
+
+import type { InlineKeyboardMarkup } from 'grammy/types'
+
+export type ApprovalChoice = 'once' | 'session' | 'always' | 'deny'
+
+export const APPROVAL_CALLBACK_PREFIX = 'ea'
+
+export function buildApprovalKeyboard(approvalId: string): InlineKeyboardMarkup {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Allow Once', callback_data: makeCallbackData('once', approvalId) },
+        { text: '✅ Session', callback_data: makeCallbackData('session', approvalId) },
+      ],
+      [
+        { text: '✅ Always', callback_data: makeCallbackData('always', approvalId) },
+        { text: '❌ Deny', callback_data: makeCallbackData('deny', approvalId) },
+      ],
+    ],
+  }
+}
+
+function makeCallbackData(choice: ApprovalChoice, approvalId: string): string {
+  // 64-byte callback_data limit — approvalId must stay short. We use a
+  // monotonic counter (e.g. `a-12345`) so well within budget.
+  return `${APPROVAL_CALLBACK_PREFIX}:${choice}:${approvalId}`
+}
+
+export interface ParsedCallback {
+  choice: ApprovalChoice
+  approvalId: string
+}
+
+export function parseCallbackData(data: string | undefined): ParsedCallback | null {
+  if (!data) return null
+  const parts = data.split(':')
+  if (parts.length !== 3) return null
+  if (parts[0] !== APPROVAL_CALLBACK_PREFIX) return null
+  const choice = parts[1]
+  const approvalId = parts[2]
+  if (
+    !approvalId ||
+    (choice !== 'once' && choice !== 'session' && choice !== 'always' && choice !== 'deny')
+  ) {
+    return null
+  }
+  return { choice: choice as ApprovalChoice, approvalId }
+}
+
+export type ResolveOutcome =
+  | { kind: 'resolved'; approvalId: string; choice: ApprovalChoice; clicker: number }
+  | { kind: 'unauthorized'; approvalId: string; clicker: number }
+  | { kind: 'unknown-approval'; approvalId: string; clicker: number }
+  | { kind: 'malformed' }
+
+export interface HandleCallbackInput {
+  callbackData: string | undefined
+  fromUserId: number
+  allowedUserIds: number[]
+  pendingApprovals: Map<string, (choice: ApprovalChoice) => void>
+}
+
+/**
+ * Decide what to do with a `callback_query`. The bot handler should call this
+ * pure function then `answerCallbackQuery` based on the outcome.
+ */
+export function handleApprovalCallback(input: HandleCallbackInput): ResolveOutcome {
+  const parsed = parseCallbackData(input.callbackData)
+  if (!parsed) return { kind: 'malformed' }
+
+  if (input.allowedUserIds.length > 0 && !input.allowedUserIds.includes(input.fromUserId)) {
+    return { kind: 'unauthorized', approvalId: parsed.approvalId, clicker: input.fromUserId }
+  }
+
+  const resolver = input.pendingApprovals.get(parsed.approvalId)
+  if (!resolver) {
+    return { kind: 'unknown-approval', approvalId: parsed.approvalId, clicker: input.fromUserId }
+  }
+
+  // One-shot pop closes the race against double-clicks
+  input.pendingApprovals.delete(parsed.approvalId)
+  resolver(parsed.choice)
+  return {
+    kind: 'resolved',
+    approvalId: parsed.approvalId,
+    choice: parsed.choice,
+    clicker: input.fromUserId,
+  }
+}
+
+/**
+ * Mint a new approval id. Monotonic counter as a string so callback_data
+ * stays short. Caller seeds and increments.
+ */
+export function makeApprovalIdFactory(): () => string {
+  let next = 1
+  return () => `a-${next++}`
+}

package/src/chunking.ts

@@ -0,0 +1,63 @@
+// Long-message chunking with (1/N) (2/N) suffix.
+//
+// Pattern from hermes telegram.py:829-836. Telegram's hard limit is 4096
+// characters per message. We split at 4000 (leave room for the suffix) and
+// attach `(1/N)` `(2/N)` `(N/N)` to each chunk. We avoid breaking inside
+// fenced code blocks so the runtime grammar stays intact across chunks.
+
+const DEFAULT_MAX_LEN = 4000
+
+export interface SplitOpts {
+  maxLen?: number
+  /** Add `(1/N)` suffixes to multi-chunk output. Default true. */
+  numbered?: boolean
+}
+
+export function splitMessage(text: string, opts: SplitOpts = {}): string[] {
+  const maxLen = opts.maxLen ?? DEFAULT_MAX_LEN
+  const numbered = opts.numbered ?? true
+
+  if (text.length <= maxLen) return [text]
+
+  const chunks: string[] = []
+  let cursor = 0
+  while (cursor < text.length) {
+    let end = Math.min(cursor + maxLen, text.length)
+
+    // Avoid splitting inside a fenced code block — if there's an unclosed
+    // ``` between cursor and end, back up to the last newline before end.
+    if (end < text.length) {
+      const segment = text.slice(cursor, end)
+      const fencesInSegment = (segment.match(/```/g) || []).length
+      if (fencesInSegment % 2 === 1) {
+        const lastNewline = text.lastIndexOf('\n', end - 1)
+        if (lastNewline > cursor) end = lastNewline
+      } else {
+        // Prefer to split on word boundary when possible
+        const lastSpace = text.lastIndexOf(' ', end)
+        const lastNewline = text.lastIndexOf('\n', end)
+        const splitAt = Math.max(lastSpace, lastNewline)
+        if (splitAt > cursor + Math.floor(maxLen / 2)) {
+          end = splitAt
+        }
+      }
+    }
+
+    chunks.push(text.slice(cursor, end))
+    cursor = end
+    // Skip the leading whitespace at the new cursor (we split on it)
+    while (cursor < text.length && (text[cursor] === ' ' || text[cursor] === '\n')) cursor++
+  }
+
+  if (!numbered || chunks.length === 1) return chunks
+  const total = chunks.length
+  return chunks.map((c, i) => `${c} (${i + 1}/${total})`)
+}
+
+/**
+ * If a chunk is going through MarkdownV2 mode, the parens in `(N/N)` need to
+ * be escaped. Hermes telegram.py:836.
+ */
+export function escapeChunkSuffixForMarkdownV2(text: string): string {
+  return text.replace(/\s\((\d+)\/(\d+)\)$/, ' \\($1/$2\\)')
+}

package/src/commands.ts

@@ -0,0 +1,28 @@
+/**
+ * Builds the Telegram BotCommand list registered via `bot.api.setMyCommands`.
+ * Sourced from the shared `nebula-ai-core` registry, filtered to
+ * surfaces:['tg']. Telegram clips command names to 32 chars and descriptions
+ * to 256, so we trim defensively. Argument hints are folded into the
+ * description because grammY's BotCommand has no separate hint field.
+ */
+
+import { commandsForSurface } from 'nebula-ai-core'
+
+export interface TelegramBotCommand {
+  command: string
+  description: string
+}
+
+const NAME_LIMIT = 32
+const DESC_LIMIT = 256
+
+export function buildTelegramCommands(): TelegramBotCommand[] {
+  const out: TelegramBotCommand[] = []
+  for (const c of commandsForSurface('tg')) {
+    const name = c.name.slice(0, NAME_LIMIT)
+    const hint = c.argHint ? ` <${c.argHint}>` : ''
+    const description = `${c.description}${hint}`.slice(0, DESC_LIMIT)
+    out.push({ command: name, description })
+  }
+  return out
+}

package/src/debounce.ts

@@ -0,0 +1,105 @@
+// Per-chat fragment buffer with adaptive quiet-period.
+//
+// Pattern from hermes telegram.py:2257: 600ms default quiet period; bump to
+// 2000ms when the last fragment is >= 4000 chars (TG client splitting a long
+// paste into adjacent updates). Carries sender metadata through the flush
+// boundary so the dispatcher gets correct username/displayName attribution.
+
+export interface DebounceOpts {
+  /** Quiet-period in ms before flushing. Default 600. */
+  quietPeriodMs?: number
+  /** Adaptive delay when last fragment is >= adaptiveSplitThreshold. Default 2000. */
+  adaptiveDelayMs?: number
+  /** Char length that triggers adaptive delay. Default 4000. */
+  adaptiveSplitThreshold?: number
+  /** Max chars to buffer per chat before forced flush. Default 6000. */
+  maxBufferChars?: number
+}
+
+export interface BufferedFragment {
+  text: string
+  messageId: number
+  ts: number
+  userId: number
+  username: string | null
+  displayName: string | null
+}
+
+export interface FlushedBatch {
+  /** Joined text with newline separators. */
+  text: string
+  /** Latest message id in the burst (used for reactions). */
+  latestMessageId: number
+  /** Earliest fragment timestamp. */
+  firstFragmentTs: number
+  /** Count of fragments coalesced. */
+  fragmentCount: number
+  /** Sender userId from the latest fragment. */
+  userId: number
+  /** Sender username (no `@`) from the latest fragment, or null. */
+  username: string | null
+  /** Sender display name from the latest fragment, or null. */
+  displayName: string | null
+}
+
+export class DebounceBuffer {
+  private readonly quietPeriodMs: number
+  private readonly adaptiveDelayMs: number
+  private readonly adaptiveSplitThreshold: number
+  private readonly maxBufferChars: number
+  private readonly chats = new Map<
+    number,
+    { fragments: BufferedFragment[]; timer: ReturnType<typeof setTimeout> | null }
+  >()
+  private readonly onFlush: (chatId: number, batch: FlushedBatch) => void
+
+  constructor(onFlush: (chatId: number, batch: FlushedBatch) => void, opts: DebounceOpts = {}) {
+    this.quietPeriodMs = opts.quietPeriodMs ?? 600
+    this.adaptiveDelayMs = opts.adaptiveDelayMs ?? 2000
+    this.adaptiveSplitThreshold = opts.adaptiveSplitThreshold ?? 4000
+    this.maxBufferChars = opts.maxBufferChars ?? 6000
+    this.onFlush = onFlush
+  }
+
+  push(chatId: number, frag: BufferedFragment): void {
+    const entry = this.chats.get(chatId) ?? { fragments: [], timer: null }
+    entry.fragments.push(frag)
+    if (entry.timer) clearTimeout(entry.timer)
+    const totalChars = entry.fragments.reduce((n, f) => n + f.text.length, 0)
+    if (totalChars >= this.maxBufferChars) {
+      this.chats.set(chatId, entry)
+      this.flush(chatId)
+      return
+    }
+    const delay =
+      frag.text.length >= this.adaptiveSplitThreshold ? this.adaptiveDelayMs : this.quietPeriodMs
+    entry.timer = setTimeout(() => this.flush(chatId), delay)
+    this.chats.set(chatId, entry)
+  }
+
+  flush(chatId: number): void {
+    const entry = this.chats.get(chatId)
+    if (!entry) return
+    if (entry.timer) clearTimeout(entry.timer)
+    if (entry.fragments.length === 0) {
+      this.chats.delete(chatId)
+      return
+    }
+    const last = entry.fragments[entry.fragments.length - 1]!
+    const batch: FlushedBatch = {
+      text: entry.fragments.map(f => f.text).join('\n'),
+      latestMessageId: last.messageId,
+      firstFragmentTs: entry.fragments[0]!.ts,
+      fragmentCount: entry.fragments.length,
+      userId: last.userId,
+      username: last.username,
+      displayName: last.displayName,
+    }
+    this.chats.delete(chatId)
+    this.onFlush(chatId, batch)
+  }
+
+  flushAll(): void {
+    for (const chatId of [...this.chats.keys()]) this.flush(chatId)
+  }
+}

package/src/format.ts

@@ -0,0 +1,64 @@
+/**
+ * Brain-prompt channel formatting. Mirrors plugin-comms's `<channel source=...>`
+ * envelope so the brain can pattern-match across A2A and TG surfaces.
+ *
+ * Inbound message text from TG is UNTRUSTED user content. We wrap it in
+ * channel tags so prompt-injection attempts stay quoted and the brain treats
+ * the content as data, not instruction.
+ */
+export interface FormatTelegramChannelInput {
+  chatId: number
+  username: string | null
+  displayName: string | null
+  text: string
+}
+
+export function formatTelegramChannel(input: FormatTelegramChannelInput): string {
+  const user = input.username ?? input.displayName ?? `id:${input.chatId}`
+  const safeUser = escapeAttr(user)
+  const safeText = escapeText(input.text)
+  return `<channel source="telegram" chat="${input.chatId}" user="${safeUser}">${safeText}</channel>`
+}
+
+/**
+ * Inverse of `formatTelegramChannel`: strip the channel envelope and return
+ * the raw inner text. Used by the gateway's TG slot to feed bypass-command
+ * parsing the un-wrapped string (the wrapper would make `parseBypassCommand`'s
+ * `startsWith('/')` check fail and silently drop `/yolo` etc).
+ *
+ * v0.22.0: extracted into plugin-telegram so the regex source lives next to
+ * its forward counterpart `formatTelegramChannel`. If we ever change the
+ * envelope shape (add fields, swap quoting), both stay in sync.
+ *
+ * Returns the input unchanged when there is no envelope (idempotent — safe to
+ * call on already-stripped or non-TG input).
+ */
+const CHANNEL_ENVELOPE_RE = /^<channel[^>]*>([\s\S]*)<\/channel>$/
+export function stripTelegramChannelEnvelope(text: string): string {
+  return text.replace(CHANNEL_ENVELOPE_RE, '$1')
+}
+
+/**
+ * One-line preview of an inbound TG message for TUI rows + activity log.
+ * Truncated to 80 chars; never includes the bot token or any envelope bytes.
+ */
+export function formatInboundPreview(input: FormatTelegramChannelInput): string {
+  const user = input.username ?? input.displayName ?? `id:${input.chatId}`
+  const oneLine = input.text.replace(/\s+/g, ' ').trim()
+  const cut = oneLine.length > 80 ? `${oneLine.slice(0, 77)}...` : oneLine
+  return `tg @${user}: ${cut}`
+}
+
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+function escapeText(s: string): string {
+  // Only escape angle brackets so the brain can't be tricked by literal
+  // </channel> in user content. Ampersands stay raw to preserve readability.
+  return s.replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}

package/src/guidance.ts

@@ -0,0 +1,20 @@
+/**
+ * Brain-prompt fragment appended ONLY when telegram is loaded. Mirrors the
+ * `MARKETPLACE_GUIDANCE` and `ONCHAIN_GUIDANCE` patterns in plugin-comms /
+ * plugin-onchain.
+ *
+ * Goal: tune the brain's tone for phone-screen consumption when responding to
+ * a TG-sourced turn. Without this, replies leak laptop-style markdown tables
+ * and 200-line code blocks that render as garbage in TG.
+ */
+export const TELEGRAM_GUIDANCE = `# Telegram channel
+When you receive a turn whose channel is \`<channel source="telegram" ...>\`, you are responding into a phone-app surface. Apply these constraints:
+
+- Keep responses short. Most TG users read on a phone screen.
+- No markdown tables. TG renders them as raw pipes.
+- No long code blocks (>20 lines). Summarize or attach a file via \`agent.send_file\` if the comms plugin is loaded.
+- Tool-call output is fine but truncate aggressively before quoting it back.
+- Reactions (eye/thumbs-up/thumbs-down) are added by the gateway; do not put emojis at the start of replies.
+- Operator may DM through TG even when their laptop is closed. Treat every TG message as authoritative; do not gate on operator confirmation.
+
+When the channel source is \`stdin\` (operator typing in the local TUI), full markdown is fine since laptops render it.`

package/src/index.ts

@@ -0,0 +1,125 @@
+/**
+ * nebula-ai-plugin-telegram
+ *
+ * Long-poll Telegram bot listener. Operator DMs `@nebula_<name>_bot` from any
+ * phone; the agent (running in Mantle Sandbox or local) replies via the same
+ * brain that handles stdin TUI turns.
+ *
+ * Required side-band ctx (`(ctx as any).telegram` field set by chat.tsx in
+ * local mode or build-runtime.ts in sandbox mode):
+ *
+ *   - botToken, allowedUserIds, agentName
+ *   - dispatchUserMessage: invoked per debounced inbound; runs brain.infer
+ *   - onProcessingStart, onProcessingEnd: optional hooks for TUI surfacing
+ *
+ * Without `ctx.telegram`, the plugin registers nothing (graceful no-op for
+ * unit-test loaders).
+ */
+import type { NativePlugin } from 'nebula-ai-core'
+import { TelegramListener } from './listener'
+import type { TelegramRuntimeContext } from './types'
+
+export type {
+  TelegramRuntimeContext,
+  TelegramDispatchInput,
+  TelegramDispatchResult,
+  TelegramInboundEvent,
+  TelegramToolEvent,
+} from './types'
+export { ProgressTracker, PROGRESS_EDIT_INTERVAL } from './progress'
+export {
+  TelegramListener,
+  TELEGRAM_ALLOWED_UPDATES,
+  capForTelegram,
+  formatApprovalResolution,
+} from './listener'
+export { buildSessionKey, sanitizeAgentName } from './session-key'
+export {
+  formatTelegramChannel,
+  formatInboundPreview,
+  stripTelegramChannelEnvelope,
+} from './format'
+export { RateLimiter } from './limits'
+export { sanitizeInbound, type SanitizeReason, type SanitizeResult } from './sanitize'
+export { formatPairingMessage } from './pairing-flow'
+export {
+  ActiveSessionTracker,
+  BYPASS_COMMANDS,
+  parseBypassCommand,
+  type ActiveSession,
+  type BypassCommand,
+  type ParsedBypass,
+} from './session-state'
+export { buildTelegramCommands, type TelegramBotCommand } from './commands'
+export {
+  type ApprovalChoice,
+  APPROVAL_CALLBACK_PREFIX,
+  buildApprovalKeyboard,
+  handleApprovalCallback,
+  makeApprovalIdFactory,
+  parseCallbackData,
+  type ParsedCallback,
+  type ResolveOutcome,
+} from './approval-keyboard'
+export {
+  escapeMarkdownV2,
+  formatMarkdownV2,
+  isMarkdownParseError,
+  stripMarkdownV2,
+} from './markdown'
+export { escapeChunkSuffixForMarkdownV2, splitMessage, type SplitOpts } from './chunking'
+export type { TelegramApprovalBridge, ApprovalChoiceKind } from './types'
+export { DebounceBuffer } from './debounce'
+export {
+  sendWithRetry,
+  classifyError,
+  isRetryable,
+  isTimeout,
+  isReplyNotFound,
+  isThreadNotFound,
+  RETRYABLE_PATTERNS,
+  TIMEOUT_PATTERNS,
+  DELIVERY_FAILURE_NOTICE,
+} from './retry'
+export {
+  acquireTelegramTokenLock,
+  BotTokenLockedError,
+  clearStaleTelegramTokenLock,
+  clearWebhookBeforePolling,
+  classifyStartFailure,
+  TELEGRAM_TOKEN_LOCK_SCOPE,
+  type StartFailure,
+  type StartFailureKind,
+  type TokenLock,
+  type AcquireTokenLockOpts,
+} from './recovery'
+export {
+  reactProcessing,
+  reactSuccess,
+  reactError,
+  REACTION_PROCESSING,
+  REACTION_OK,
+  REACTION_ERR,
+} from './reactions'
+export { TELEGRAM_GUIDANCE } from './guidance'
+export { startTypingLoop, TYPING_REFRESH_INTERVAL_MS } from './typing'
+
+const plugin: NativePlugin = {
+  name: 'telegram',
+  register: ctx => {
+    const tg = (ctx as unknown as { telegram?: TelegramRuntimeContext }).telegram
+    if (!tg) return
+    const listener = new TelegramListener(tg)
+    ctx.registerListener({
+      name: 'telegram-bot',
+      start: async () => {
+        await listener.start()
+      },
+      stop: async () => {
+        await listener.stop()
+      },
+    } as never)
+  },
+}
+
+export default plugin

package/src/limits.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-user token-bucket rate limiter. Defends against a compromised allowed
+ * user account spamming the brain (and burning compute credits).
+ *
+ * Default: 30 messages per 60 seconds. Excess get dropped + a 👎 reaction (the
+ * listener handles the reaction; this module just answers shouldDrop).
+ */
+export interface RateLimiterOpts {
+  /** Bucket capacity per user. Default 30. */
+  capacity?: number
+  /** Refill window in ms. Default 60_000. */
+  windowMs?: number
+}
+
+interface Bucket {
+  /** Remaining tokens. */
+  tokens: number
+  /** Unix-ms timestamp of the last refill. */
+  lastRefill: number
+}
+
+export class RateLimiter {
+  private readonly capacity: number
+  private readonly windowMs: number
+  private readonly buckets = new Map<number, Bucket>()
+
+  constructor(opts: RateLimiterOpts = {}) {
+    this.capacity = opts.capacity ?? 30
+    this.windowMs = opts.windowMs ?? 60_000
+  }
+
+  /**
+   * Returns true if this user's message should be DROPPED (bucket empty).
+   * Side-effect: consumes one token if not dropped.
+   */
+  shouldDrop(userId: number, now: number = Date.now()): boolean {
+    const b = this.buckets.get(userId) ?? { tokens: this.capacity, lastRefill: now }
+    // Refill proportional to elapsed time
+    const elapsed = now - b.lastRefill
+    if (elapsed > 0) {
+      const refill = Math.floor((elapsed / this.windowMs) * this.capacity)
+      if (refill > 0) {
+        b.tokens = Math.min(this.capacity, b.tokens + refill)
+        b.lastRefill = now
+      }
+    }
+    if (b.tokens <= 0) {
+      this.buckets.set(userId, b)
+      return true
+    }
+    b.tokens -= 1
+    this.buckets.set(userId, b)
+    return false
+  }
+
+  reset(userId?: number): void {
+    if (userId === undefined) this.buckets.clear()
+    else this.buckets.delete(userId)
+  }
+}