Telegram channel

Telegram is the first channel: your agent in a private chat, authenticated, throttled, and approval-capable.

Inbound

• Long polling (getUpdates, 25s timeout). The offset persists in the state store and advances only after dispatch: at-least-once delivery, deduplicated by offset. A crash re-delivers the tail; consumers are idempotent.

• Authentication is an allowlist. Private chats only, and the sender’s numeric id must be in telegram.allow_user_ids, for messages and button presses. Usernames are never trusted. Unauthorized traffic gets no reply, one rate-limited stderr note per minute, and an audit row.

• Commands route locally, never reaching the engine:

  Command	Action
  /start, /help	What the bot can do
  /status	Session, strand, budgets, queue
  /new	Start a fresh session
  /stop	Abort the running turn

  Any other /word gets unknown command: /word. Plain text goes to the engine as a prompt. Text only in M2: file uploads arrive in a later milestone.

Outbound

• The delivery boundary is idle. No per-token streaming to chat; instead you get a typing action every 4s plus one editable progress message (edits throttled to one per 3s, last 3 notes buffered).
• Final answers chunk politely: at most 3800 characters per message, split at paragraph boundaries, unbalanced code fences closed per chunk, sends spaced at least 1s apart.
• Plain text only. Engine markdown is never interpreted as Telegram entities.

Approval cards

An engine ask renders as: question, the first 20 lines of detail, and an expiry, with an Allow / Deny inline keyboard. A decision answers the engine ask, writes the audit entry, and edits the card to [Approved] / [Denied] / [Expired] with the keyboard removed.

Secrets

The bot token never lives in ka-agent.toml; the config names it (token_secret), and the secret store resolves it:

1. $KA_AGENT_SECRET_TELEGRAM_BOT_TOKEN (the name uppercased), or
2. <data>/secrets/telegram.bot_token: a 0600 file, single line.

A bad token gets one ! [auth] message to the known chat, then the channel exits. Network errors back off 1s to 60s.