feat(telegram): support multiple bot accounts per gateway

[chenmingwei23]

What is the problem?

Users who want to run specialized bots (e.g. different personas, topic-focused assistants, or access-scoped bots) currently need separate gateway processes per bot. Each process has its own memory footprint (~200MB), its own config directory, and its own lifecycle management. This is operationally heavy for what is conceptually a single agent platform serving multiple front-ends.

Why this issue matters

A single gateway process already multiplexes Slack, Discord, Webex, and other channels. Telegram is the only channel locked to a 1:1 token:gateway ratio. Power users who want to expose different capabilities via different bot handles (e.g. a general assistant, a finance bot, and a domain-specific bot) are forced into N independent processes with duplicated config, duplicated memory, and no shared session management.

How the fix solves it

Adds telegram.accounts — a named map of bot accounts, each with its own bot_token, allowed_user_ids, and forum settings. One gateway starts one polling loop per account. Sessions are naturally isolated: named accounts use telegram:{account_id} as the channel namespace in the session key, while the default account keeps the bare telegram prefix for backward compatibility.

Agent routing: a new telegram_account field on the agent config binds an agent to a specific account. Messages on that bot route to the bound agent (workspace, memory store, model). Unbound accounts route to the default agent.

Backward compatible: when telegram.accounts is absent, the existing single-token config (telegram.bot_token) is auto-wrapped as a "default" account with zero behavioral change. Existing configs work unchanged.

The accounts config pattern is channel-agnostic by design and can be extended to Discord, Slack, and other channels in future PRs.

Config example

{
  "telegram": {
    "enabled": true,
    "accounts": {
      "main": { "bot_token": "...", "allowed_user_ids": [123] },
      "finance": { "bot_token": "...", "allowed_user_ids": [123, 456] }
    }
  },
  "agents": {
    "default": { "kiro_agent": "kirocrew", "workspace": "default", "telegram_account": "main" },
    "finance": { "kiro_agent": "kirocrew", "workspace": "finance", "telegram_account": "finance" }
  }
}

What tests we did

• All 207 existing Telegram tests pass (zero regressions)
• 9 new tests covering: config parsing, backward compat (single token wraps as default), explicit accounts taking precedence, session key isolation between accounts, agent binding
• isort, flake8, mypy all clean
• Manual verification that resolved_accounts() correctly synthesizes the legacy path

Other suggestions

• Future PRs can extend the same accounts pattern to Discord (discord.accounts) and other channels with minimal effort — the session key builder already accepts arbitrary channel names.
• Dashboard UI for managing multiple accounts (adding/removing tokens, viewing connected status per account) would be a natural follow-up.

[github-actions]

GPT 5.6 Review — ✅ human override accepted

Human judgment by @chenmingwei23 overrides the GPT 5.6 finding for 381d53bbe194577d814ac7a0001f48d850a77cfb; the recorded reason is authoritative for this commit.

This comment is updated in place on each push.

The model was not re-run because an authorized human decision supersedes it.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 381d53bbe194577d814ac7a0001f48d850a77cfb: <one-sentence reason>

[github-actions]

Design Review (Fable 5) — 🟡 CONCERNS

Advisory design-level review of 381d53bbe194577d814ac7a0001f48d850a77cfb — updated in place on each push; does not block merge.

Design-Verdict: CONCERNS

Named accounts ship half-integrated: an unregistered persisted session-key shape, silent per-account failures, and feature gaps all keyed on a magic "default" string.

Watch

• New persisted key shape outside the registry. Named accounts mint telegram.{id}: session keys while CHANNEL_SESSION_NAMESPACES is untouched (the diff's own TODO admits it) → is_channel_session_key/parse_session_key reject them → no dashboard chat slots, telemetry "other", no autonudge. Once these keys are persisted to history, later registering the namespace or changing the separator needs a data migration — this is the PR's one-way door and it ships as a TODO rather than a decision.
• Non-default accounts fail invisibly. telegram_connected / telegram_connect_error and status callbacks are set only if account_id == "default", and _parse_telegram_accounts silently drops malformed entries → a revoked token or typo on the second bot leaves it dead with only a log line, in a feature whose entire purpose is running several bots. No per-account health surface = no failure story on the fallible path.
• Inverted binding allows ambiguity. Routing scans agents.* for telegram_account == account_id; two agents naming the same account resolve by dict insertion order, silently. accounts.<id>.agent would make the one-to-one relation structural — and the "channel-agnostic pattern" claim doesn't hold when each future channel needs its own agent-config field.
• Phantom per-account knob. TelegramAccountConfig.soft_threshold_pct is parsed and documented per-account, but the dispatcher still reads the global cfg.telegram.soft_threshold_pct — dead config surface that's hard to retract once users set it. Also: config schema and session-key behavior changed with no docs/system-specs/modules/messaging.md update in the commit.

Suggestions

• Register telegram.{id} (or pick the final key grammar) in CHANNEL_SESSION_NAMESPACES in this PR, before the first named-account session is persisted — it's a data change per the spec, not a follow-up.
• Move the binding to accounts.<id>.agent and drop telegram_account from agent config before this becomes public schema.

[DESIGN-REVIEWED] 381d53b

[chenmingwei23]

/ai-review override gpt 773a614: accounts.bot_token has identical security posture as the existing telegram.bot_token field (also in config.json with the same sensitive=True metadata). The field exists for convenience alongside the recommended .env path, matching the established pattern.

[github-actions]

AI-review override not recorded: 773a614221a1b380c17b41f393d1a016ebd8379b is not the current PR head. Re-run the command with 7aa8c0327ed5e7e5207175b4120b8d7bc7caa03d.

[chenmingwei23]

/ai-review override gpt 381d53b: The field carries sensitive=True metadata (line 3840), which is the same mechanism the existing telegram.bot_token uses for masking in the /api/config response. Dynamic-path masking for nested fields is a config-API concern orthogonal to this PR.

[github-actions]

Human judgment recorded

@chenmingwei23 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for 381d53bbe194577d814ac7a0001f48d850a77cfb.

The field carries sensitive=True metadata (line 3840), which is the same mechanism the existing telegram.bot_token uses for masking in the /api/config response. Dynamic-path masking for nested fields is a config-API concern orthogonal to this PR.

This decision applies only to this commit. A new push requires a new judgment.

[github-actions]

Opus 5 Review — ✅ no blocking findings

Reviewed 381d53bbe194577d814ac7a0001f48d850a77cfb — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 381d53b

Verdict parsed from the review's SHA-scoped output markers for commit 381d53bbe194577d814ac7a0001f48d850a77cfb.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 381d53bbe194577d814ac7a0001f48d850a77cfb: <one-sentence reason>

[iamwhatever]

This one definitely require additional control configured, specifically governance management. Please check the way to turn this one off with simple config as the enterprise may not want this thing for security reason.