openclaw/extensions/telegram/AGENTS.md

# Telegram Plugin Guide

Read this before any change under `extensions/telegram/`. These are intentional
maintainer decisions and review-binding invariants, not incidental
implementation details. Also read `extensions/AGENTS.md` for the plugin
boundary rules.

Verified against Telegram Bot API 10.2, July 14 2026.

## Reliability Invariants

### Core drain contracts (do not re-implement in Telegram)

Owned by `src/channels/message/ingress-drain.ts` (+ claim-owner, retry-policy).
Proof: `src/channels/message/ingress-drain.test.ts`,
`ingress-claim-owner.test.ts`, `ingress-retry-policy.test.ts`.

- Completed rows tombstone via `complete()`, never `delete`.
- Complete at turn adoption, not settle. Deferred holds the claim; watchdog
  stays armed through deferral; dead-letter reason `handler-timeout`.
- One retry policy: attempt floor **and** age gate (defaults 8 / 24h).
- Claim refresh heartbeat while dispatching/deferred (`claimLeaseMs / 3`).
- Never silently complete on transient failure — release/fail via disposition.
- Pre-adoption supersede tombstones; post-adoption interruption is core-owned
  (reply-run registry / queue interrupt).

### Telegram-owned (transport + channel policy)

- Durable-before-ack on both transports. Polling: ingress worker advances its
  offset only after the parent's committed spool enqueue
  (`writeTelegramSpooledUpdate`). Webhook: respond 200 only after the spool
  write; non-200 on write failure is the redelivery contract.
- `update_id`↔event-id encoding and per-chat/topic lane derivation stay in
  `telegram-ingress-spool.ts` / sequential-key.
- Polling and webhook both: enqueue then pump
  `createTelegramTransportIngressDrain(...).drainOnce()` — no private claim
  loops.
- Stall timeout: `OPENCLAW_TELEGRAM_SPOOLED_HANDLER_TIMEOUT_MS` →
  `adoptionStallTimeoutMs` (default 5 min) via
  `resolveTelegramAdoptionStallTimeoutMs`.
- Non-retryable classifier: `telegram-ingress-non-retryable.ts`
  (missing harness, dispatch-dedupe rollback).
- Supersede predicate: `telegram-ingress-supersede.ts` — only abort text /
  authorized-looking explicit commands (and ambient room_event pending) may
  supersede pre-adoption work. Normal messages never supersede.
- room_event ambient work shares the sequential lane so a later user turn can
  supersede it pre-adoption; adopted user turns are never touched (core drain
  supersede is pre-adoption only).
- No per-message full-store writes. Hot-path SQLite writes are per-entry.
  Rewriting a cache on every send or read stalls the event loop, and that
  stall masquerades as a polling stall (the sent-message-cache regression).
- Transport error classification. The getUpdates worker retries Bot API 5xx
  and 429 locally, honoring `parameters.retry_after`; 401/404 stay fatal; 409
  must propagate to the parent session, which owns webhook-conflict recovery.
  Bot API errors carry `error_code`, not `.code`; parse non-2xx bodies
  defensively (a 502 HTML page is not JSON).
- Send funnel parity. The durable funnel (`send.ts`) and the streaming funnel
  (`bot/delivery.*`) must degrade identically: rich-entity 400 falls back to
  plain text, caption parse 400 falls back to a plain caption, quote-not-found
  400 falls back to a legacy reply. New recoveries go into the shared
  predicates (`send-error-predicates.ts`, `reply-parameters.ts`), never into
  one funnel only.
- Outbound flood waits honor `retry_after` up to
  `TELEGRAM_OUTBOUND_RETRY_AFTER_CAP_MS`; do not re-clamp Telegram sends to the
  generic channel retry ceiling.
- Webhook security ordering. The secret header is validated first
  (constant-time compare, single-header enforcement, connection close on 401);
  the request rate limit budgets only failed-auth attempts so Telegram's own
  delivery is never throttled.
- Every owned undici transport gets closed on all exit paths: polling session,
  webhook shutdown and startup failure, probe-cache eviction.

## Streaming

- Do not reintroduce `sendMessageDraft` for answer streaming. Telegram drafts
  are ephemeral 30-second previews in private chats; final delivery still
  requires a separate `sendMessage`. OpenClaw uses `sendMessage` plus
  `editMessageText`, then finalizes in place so the user sees one persistent
  answer.
- Streaming owns one visible preview message. Edit it forward. Do not send an
  extra final bubble unless the final edit genuinely failed.
- Keep the first-preview debounce. If a provider sends token-sized deltas,
  coalesce them into cumulative preview text instead of removing the debounce.
- Respect Telegram limits in the Telegram layer. Text over 4096 chars chains
  into continuation messages. Polls keep the current Bot API 12-option cap.

## Telegram API Ownership

- Prefer grammY primitives and Telegram-native helpers when they model the
  behavior directly. Avoid custom Bot API wrappers for behavior grammY already
  owns.
- Throttling is bot-token scoped. All Telegram API clients for the same token
  share one grammY `apiThrottler()` instance.
- Do not silently retry failed topic sends without topic metadata. A
  wrong-surface success is worse than a loud Telegram error.
- DM topics and forum topics are distinct. `direct_messages_topic_id` and
  `message_thread_id` are not interchangeable.

## Context And Authorization

- Reply context comes from OpenClaw-observed messages. Bot API updates expose
  `reply_to_message`, but there is no arbitrary `getMessage(chat, id)`
  hydration path later.
- Current local chat context must outrank stale reply ancestry in the prompt.
  Old replied-to messages should not look like the active conversation.
- The group history window is always on for groups and bounded by
  `historyLimit`. Do not reintroduce prompt-history gating modes; that
  regression blinded ambient rooms.
- The group history window is rolling. Use self-entry watermark selection for
  "since your last reply" views; do not reintroduce destructive clears because
  room events are not persisted to the session and cleared context is
  unrecoverable.
- Pairing is DM-only. Group and topic authorization need explicit config
  allowlists.
- Telegram allowlists use numeric sender IDs. Usernames are optional, mutable,
  and not a reliable arbitrary-user lookup key in the Bot API.
- Group and channel visible replies are policy-controlled. Normal room replies
  stay private unless `messages.groupChat.visibleReplies: "automatic"` is set
  or the agent explicitly calls `message.send`.

## Interactive Surfaces

- Native callbacks stay structured. Approval, native command, plugin, select,
  and multiselect callbacks must not fall through as raw callback text.
- Preserve callback values exactly, including delimiters such as `env|prod`.
- Native slash commands should remain fast-pathable before full workspace and
  agent-turn setup.

## Review Standard

- Telegram behavior PRs need real Telegram proof when they touch transport,
  streaming, topics, callbacks, authorization, or reply context. Prefer the
  bot-to-bot QA lane or an equivalent live Telegram probe over synthetic-only
  validation.
- Reliability PRs (spool, drain, retry, ack, offset paths) need crash-window
  or restart-replay test proof, not just happy-path tests.