feat(telegram): add durable support through Phase 5

[Maximooch]

Summary

• add a transport-neutral chat execution seam and durable channel contracts without putting Telegram logic in PenguinCore
• add optional python-telegram-bot==22.6 support for DMs, allowlisted groups, forum topics, commands, bounded media, streaming previews, and explicit outbound artifacts
• add request-scoped remote permission caps, granular allow/ask/deny categories, resumable one-shot/session approvals, /permissions, and direct question replies/buttons
• preserve approval prompts through terminal states and stop Telegram turns after a denied or expired approval instead of accumulating serial waits
• add SQLite-backed bindings, ingress/outbox leases, deduplication, lane ordering, retries, dead letters, polling ownership, supergroup migration, and authenticated webhooks
• add default-deny config, setup/operator documentation, package checks, and Python 3.9–3.12 Telegram contract CI

See context/tasks/penguin-telegram.md and docs/docs/usage/telegram.md.

Security

• Telegram is disabled and deny-by-default; authorization uses numeric Telegram IDs
• bot and webhook credentials are environment-only and redacted from status/errors
• remote permissions cannot exceed Penguin's instance policy; YOLO mode is rejected
• unauthorized updates are dropped before durable admission
• outbound files require the explicit, approval-gated publish_artifact tool and are revalidated at send time

The supplied bot token is not committed or fixtured. A local polling smoke test used environment configuration, and the credential will be rotated before production use.

Verification

• focused channel/Telegram/runtime gate: 233 passed
• repository suite: 2,494 passed, 3 skipped; the five reported failures plus one explicitly deselected test reproduce on clean HEAD under the same environment
• Ruff check/format for the new channel and Telegram surface: passed
• changed Python syntax and critical undefined-name checks: passed apart from a pre-existing FastAPI forward-annotation lint finding
• fresh wheel and sdist build: passed
• Twine archive checks and fresh-wheel imports: passed
• generic credential scans across source, wheel, and sdist: zero matches
• live Telegram smoke: user-confirmed for polling, DM startup, pairing, and the approval flow

Stack and scope

This draft targets fix/multi-agent-runtime (PR #82), which is the branch the worktree was created from, so the Telegram diff remains isolated. Phases 6–8—voice/TTS, broader media/reactions, proactive scheduling, and final Hermes parity hardening—remain explicitly deferred.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
penguin	Ready	Preview	Aug 11, 2026 9:53pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3843cd5a-76da-4e75-94cb-1bb88de0c1a9

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}