feat: Matrix transport support

[n-haminger]

Summary

Add Matrix as a first-class messaging transport alongside Telegram — laying the foundation for making ductor a truly transport-agnostic agent framework.

What is Matrix?

Matrix is an open, decentralized communication protocol for real-time messaging. Unlike Telegram, Matrix is:

• Self-hostable — run your own homeserver with full data sovereignty
• Federated — servers talk to each other, no single point of failure
• End-to-end encrypted — via the Olm/Megolm protocol
• Open standard — no vendor lock-in, multiple client implementations (Element, FluffyChat, etc.)

Why Matrix?

• Users running ductor on private infrastructure often prefer self-hosted communication
• E2EE support means agent conversations stay private even on shared servers
• The decentralized architecture aligns with ductor's "runs on your machine" philosophy
• Matrix rooms can be used for multi-user agent access without Telegram group limitations

Foundation for more transports

This PR introduces a transport registry pattern (transport_registry.py + BotProtocol interface) that makes adding new transports straightforward. Adding Discord, Slack, or any other messaging platform requires only:

1. A bot implementation conforming to BotProtocol
2. A transport adapter for MessageBus delivery
3. A one-line entry in _TRANSPORT_FACTORIES

All orchestrator logic, session management, CLI execution, and automation systems remain transport-agnostic.

Changes

Core Transport Layer

• ductor_bot/matrix/ — Full Matrix transport: bot, sender, transport, buttons, media, credentials, typing, formatting, startup
• ductor_bot/transport_registry.py — Transport factory dispatch
• ductor_bot/bot/protocol.py — Shared BotProtocol interface
• ductor_bot/config.py — MatrixConfig, transport field, media_files_days rename

Features

• Segment-based streaming (Matrix doesn't support message editing)
• Clean chat: tool/system markers suppressed, only reasoning + final summary visible
• Reaction-based buttons (emoji digits, since Matrix has no inline keyboards)
• E2EE support via matrix-nio[e2e]
• Incoming media handling (images, audio, video, files)
• Full command parity (!// prefix)

Transport-Neutral Refactoring

• telegram_tools/ → media_tools/ (scans both telegram_files/ and matrix_files/)
• telegram_files_days → media_files_days (backwards-compatible)
• Setup wizard supports transport selection during onboarding
• create_agent.py supports --transport matrix for sub-agents
• Transport-neutral identity text and documentation

Documentation (14 files updated)

• README.md, docs/config.md, docs/architecture.md, docs/system_overview.md
• Module docs: bot.md, matrix.md, bus.md, orchestrator.md, cron.md, logging.md, multiagent.md
• Guides: installation.md, developer_quickstart.md, automation.md

Test plan

• All existing tests pass (891+ tests, pre-existing failures excluded)
• Matrix bot starts and connects to homeserver
• Text messages, commands, streaming work via Matrix
• File send/receive works (images, audio, documents)
• Tool/system markers suppressed in Matrix chat
• Telegram transport unaffected (default behavior preserved)
• media_files_days backwards-compatible with telegram_files_days
• Sub-agent creation with --transport matrix works
• E2EE room communication (requires matrix-nio[e2e])

🤖 Generated with Claude Code

[PleasePrompto]

Hey n-haminger, thanks for the support! 😄
I’ll take a closer look at Matrix first, and then I’m planning to take over the integration from you.

Quick note:
If you’d like to appear as a contributor, you’ll need to change your email address when creating the PR. Otherwise, you won’t be listed as one. Github will then assign it automatically!

[n-haminger]

Hey n-haminger, thanks for the support! 😄
I’ll take a closer look at Matrix first, and then I’m planning to take over the integration from you.

Quick note:
If you’d like to appear as a contributor, you’ll need to change your email address when creating the PR. Otherwise, you won’t be listed as one. Github will then assign it automatically!

Thank you for the note, I think now the right email address should be assigned.

[PleasePrompto]

Great work on the Matrix transport! 🎉 The implementation is solid — streaming, reactions, media, group mentions, typing indicators — all working well.

I've merged this and then restructured the entire messenger layer on top of your work to create a transport plugin architecture that makes it easy to add more messengers in the future (Discord, Slack, etc.).

What changed

Architecture (messenger/ module)

Your code lived in bot/ (Telegram) and matrix/ (Matrix) as separate top-level modules. I moved everything into a unified messenger/ package:

messenger/
├── protocol.py          # BotProtocol — 7 methods any transport must implement
├── notifications.py     # NotificationService — 2-method protocol (notify, notify_all)
├── registry.py          # Transport factory registry (no if/else, just a dict)
├── commands.py          # Shared command classification (direct/orchestrator/multiagent)
├── callback_router.py   # Shared button/selector callback routing
├── send_opts.py         # BaseSendOpts base class
├── capabilities.py      # Feature matrix per transport (buttons, reactions, editing...)
├── multi.py             # MultiBotAdapter for parallel transport operation
├── telegram/            # All Telegram code (was bot/)
└── matrix/              # All Matrix code (was matrix/)

Adding a new transport now requires

1. Implement BotProtocol in messenger/discord/bot.py
2. Implement TransportAdapter for envelope delivery
3. One line in registry.py: _TRANSPORT_FACTORIES["discord"] = _create_discord
4. SessionKey.for_transport("discord", chat_id) works automatically

Zero changes needed in orchestrator, session, cron, webhook, or heartbeat code.

Session isolation

SessionKey now uses transport-prefixed storage keys (tg:123, mx:456) with factory methods:

SessionKey.telegram(chat_id, topic_id)
SessionKey.matrix(chat_id)
SessionKey.for_transport("discord", chat_id)

New feature: /interrupt

Built on top of your !stop concurrency fix (the create_task + LockPool pattern). /interrupt sends SIGINT instead of SIGTERM — cancels the current tool execution without killing the agent session. Works on both Telegram and Matrix. Also added bare-word triggers: esc, interrupt, skip, überspringen.

Code quality

• Removed dead code across 11 files (381 deletions)
• Deduplicated shared utilities (file browser, command sets)
• Fixed all mypy errors (18 → 0) without type: ignore workarounds
• Fixed all ruff lint errors without noqa comments
• Fixed Matrix bugs: message replay, stop_all across transports, Docker file paths, missing awaits
• Extracted MatrixStreamEditor class from inline streaming logic
• 3284 tests passing

Thanks for the contribution — the Matrix support is a great addition to ductor!