1. What it does: the channel adapter

A channel, in Metnos, is an adapter: it converts an external interface (local CLI, Telegram bot, voice, in the future Signal) into a stream of messages spoken to the runtime, and returns the responses back. Nothing more. All the conversational logic — planning, execution, vaglio — lives in the runtime; the channel is a bidirectional pipe.

The choice to treat the channel as an adapter (and not as a distinct module for each integration) is what makes it possible to start with two channels (CLI + Telegram) and add more without touching the core. See ch. 6 of the Architecture: the channel sits in layer 1 (Gateway), together with authentication and routing.

2. The Protocol and the types

In runtime/channels/__init__.py the channel is a typing.Protocol with two minimal methods and a name property. No base class, no inheritance: any object that exposes the right shape is a channel.

@runtime_checkable
class Channel(Protocol):
 name: str
 def send(self, recipient: str, message: OutboundMessage) -> dict:...
 def poll(self) -> list[InboundMessage]:...

The two message types are dataclass(frozen=True):

The frozenness prevents the dispatcher from modifying an incoming message: whoever wants to enrich it creates a new object. It is a deliberate choice: a message that has arrived is a historical fact, not a scratch pad.

3. Telegram as the first implementation

runtime/channels/telegram.py implements the protocol via the Bot API. No external library: just urllib + json. Coherent with the self-host principle (ch. 4 Architecture): the bot queries outbound on api.telegram.org, no open ports, no public IP.

Configuration (in order of precedence):

1. Constructor parameters: TelegramChannel(token=, default_chat_id=, credentials_path=, state_path=).
2. Environment variables: TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID.
3. File ~/.config/metnos/credentials.env (chmod 600), dotenv format.

Methods:

• send(recipient, message) → POST sendMessage to api.telegram.org. If buttons, it builds an inline_keyboard. Returns {ok, result?, error?, status_code?}.
• poll(timeout_s=25) → long-poll getUpdates with internal offset; returns only the message and edited_message entries with a text field. The callback_query events (clicked buttons) are handled by the dedicated dispatcher (see ch. 6 and 9).

4. Long-poll and offset persistence

getUpdates is called in long-poll mode: the Telegram server keeps the connection open for up to 25 seconds if there are no updates. No busy-loop, no useless load, minimal latency when a message arrives.

The offset (the update_id of the last update seen) is kept in memory. To survive restarts (systemd restart, crash, new code deploy) it is also written to disk in ~/.local/state/metnos/telegram_offset. Round-trip verified in test (telegram_offset_persistito_round_trip); a corrupted file falls back to "offset = none" without crashing (telegram_offset_state_corrotto_torna_none).

Persistence is optional: state_path=False disables it (useful in tests). Without persistence, after a restart the bot sees again the last pending messages on Telegram and risks double replies. With persistence, the first poll after the restart starts from offset = last_seen + 1 and Telegram does not redeliver already-acknowledged messages.

5. Daemon: the loop poll → run_turn → send

runtime/channels/daemon.py contains ChannelDaemon: a single process that cycles poll → for each message: handle → (run_turn) → send. No threading. The calls to run_turn are synchronous. Typical latency for a local turn: 2-15 s.

The daemon does not «know» that the channel is Telegram: it works on the Channel Protocol. When Signal arrives, the same daemon starts with a different instance.

Error discipline (test daemon_run_turn_eccezione_non_crasha_loop):

• Exception in poll: log + sleep 5 s + retry on the next tick. No crash.
• Exception in run_turn: caught, reply to the sender with (internal error:...), the daemon continues.
• Exception in send: caught by TelegramChannel._call, returns dict {ok: False, error}. The turn is already closed on the runtime side; the user must retry.

Modes (CLI python3 -m channels.daemon):

• --dry-run: logs the responses but does not send them. Useful to observe the runtime's behaviour without real effects.
• --no-bootstrap: disables the auto-pair of the default_chat_id (ch. 7). Needed for multi-user setups, where Roberto too pairs explicitly with a code.
• -v: log at DEBUG level.

6. Inline buttons and approval rendering

OutboundMessage.buttons is a matrix list[list[dict]]. Each dict has text and data; data ends up in the callback_data of the Telegram button.

The component that produces the approval cards is in runtime/channels/approval.py: render_approval_card(ApprovalRequest) returns an OutboundMessage with the «3-line card» of the dialog manager (see approval_ux). Three forms modulated by recurrence:

• Full (3 lines, default for rare requests): imperative question + object/source/destination + class and reversibility.
• Medium (2 lines, for requests seen 3-7 times): question with inline meta + object.
• Short (1 line, for requests seen 8+ times): compact button-friendly form.

The dispatching of callbacks (clicking "Approve" resolves the token into a pending request and applies the decision) is handled by the daemon via approval_registry.resolve (see approval_ux).

7. Relationship with pairing

The daemon does not accept messages from anyone. For each InboundMessage it consults pairing.get_pairing(channel, sender_id) (see pairing):

• If the sender is paired: the daemon proceeds with run_turn, except in the autonomy_level == "ReadOnly" case in which it replies with a polite message and does not perform actions (LEVEL_BLOCKS_RUN in daemon.py).
• If the sender is the default_chat_id and no other pairing exists on that channel: automatic bootstrap at Full (_try_bootstrap). Without this, at install time Roberto would have to generate a code for himself — useless step in dev.
• Otherwise: rejects with «I do not recognise you; ask Roberto for a pairing code» (constant UNPAIRED_REPLY).

The /pair <code> command on the channel is intercepted before the pairing check — that is its very purpose. Every message from a paired sender also updates the last_seen via pairing.touch_last_seen, useful for audit and to detect dormant accounts to revoke.

8. Distribution: systemd user unit

The daemon runs as a user unit, not as a system service: no root, no privileges. The template file is in /opt/metnos/systemd/metnos-telegram-daemon.service. Explicit hardening:

• NoNewPrivileges=true
• ProtectSystem=strict + ReadWritePaths limited to ~/.local/state/metnos and ~/.local/share/metnos
• PrivateTmp=true, ProtectKernelTunables, ProtectKernelModules, ProtectControlGroups, RestrictNamespaces, RestrictRealtime, LockPersonality
• Output to journald: journalctl --user -u metnos-telegram-daemon -f

Restart=on-failure with 5s backoff. The user linger is required for the service to stay active without an interactive login: loginctl enable-linger $USER (sudo required the first time). The README in /opt/metnos/systemd/README.md has the full procedure.

9. HTTP as alternative channel

Since Metnos exposes a second HTTP server on port 8770 with three agent-side routes: POST /agent/turn (run_turn execution with SSE or JSON), GET /agent/devices/me, GET /agent/health and GET /.well-known/metnos.json. See http_api for the details.

The relationship between channel and http_api is deliberate:

• Telegram — primary dialogue channel. Long-poll, mobile-first, well-trodden UX.
• HTTP — alternative channel for (a) the host browser dashboard, (b) the Rust client on a paired PC, (c) curl/script automations. run_turn receives channel="http" and goes through the same gates (vaglio, policy) as Telegram.
• No formal HTTPChannel: the poll-based channels model is incompatible with request/response. POST /agent/turn calls run_turn directly.

Multi-user: the /start <token> command accepted by the Telegram daemon completes the guest pairing issued from the /admin/users panel of the HTTP API. The send_messages supports to_user="lucia" and via_channel="auto": it resolves through users.resolve_recipients, with cross-user vaglio applied for non-host actors.

10. Limits and deferrals to +

• One channel per process: the daemon manages one channel at a time. For CLI + Telegram in parallel two instances are needed (two systemd units). Adequate for now; a richer multi-channel abstraction will arrive when three or more channels are active.
• Callback dispatcher active: the inline buttons are rendered (ch. 6) and the daemon dispatcher resolves clicks via approval_registry.resolve (see approval_ux).
• No file/voice/photo: text only. poll explicitly filters out messages that have no text. Photos will be handled by downloading the attachment to workspace/inbox/ and passing the path to the runtime; voice notes via local whisper.cpp (ch. 4 Architecture, open-source-first principle).
• No webhook: long-poll only. Webhooks would require a public IP or a proxy — and Metnos chooses to have neither.
• Throttling: none. Telegram rate-limits bots to ~30 msg/s on the free plan; for now we are largely below that. If needed, a token bucket at send level would suffice.
• No per-sender rate-limit: a paired sender can flood the daemon. With an active vaglio this becomes relevant; for now the pairing cardinality is low (one or a few family members).