stack/docs/fleet/f4-matrix-connector.md

F4 — Orchestrator chat connector + Matrix (local homeserver)

Issue: #616 · Doctrine: docs/fleet/north-star.md (#613) — orchestrator-chat-connector decision. Status: Phase 1 (abstraction + scaffold) in this PR; Phase 2+ are follow-ups (below).

Goal

The fleet orchestrator is the operator's single point of contact. The north-star makes the chat channel a user-chosen connector — tmux today, Discord live ("Mos"), with Matrix / Telegram / Slack configurable. F4 adds Matrix (local homeserver) as a peer connector and, first, the small connector abstraction that makes connectors pluggable without touching fleet core.

The abstraction (Phase 1 — this PR)

Connectors implement one small, uniform interface (src/fleet/connectors/types.ts):

interface OrchestratorConnector {
  readonly kind: 'tmux' | 'discord' | 'matrix';
  send(message: OutboundMessage): Promise<SendResult>; // orchestrator → human
  subscribe(handler: (m: InboundMessage) => void): Unsubscribe; // human → orchestrator
  health(): Promise<ConnectorHealth>; // reachable + authenticated
}

• send / subscribe / health — the only surface fleet core depends on. SendResult is the ack half; health() is the liveness half.
• Thread-aware by metadata — OutboundMessage.threadId / InboundMessage.threadId are optional, so thread-capable connectors (Matrix rooms/threads, the future first-party Mosaic Discord plugin) fit without an interface change.
• Registry (registry.ts) — implementations register a factory by kind; createConnector(config) resolves one from roster config. Phase 1 ships the registry + resolveConnectorKind (defaults tmux when a roster declares no connector — back-compat); the factories land in Phase 2.

Config model

A roster may carry an optional connector block (roster.schema.json); absent ⇒ tmux.

connector:
  kind: matrix # tmux | discord | matrix
  matrix:
    homeserver_url: https://matrix.example.internal
    user_id: '@mos:example.internal'
    room_id: '!abc:example.internal'

Secrets are never in the roster. MATRIX_ACCESS_TOKEN / DISCORD_BOT_TOKEN come from the environment (the gateway env-config pattern that already masks them). The sanitization gate would reject a token committed to a shipped file anyway.

Matrix connector (Phase 2)

The connector speaks the Matrix client-server API directly over HTTPS (fetch — no SDK needed for MVP), so it is homeserver-agnostic:

Op	Matrix CS-API
send	PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}
subscribe	GET /_matrix/client/v3/sync (long-poll, since token) → room timeline
health	GET /_matrix/client/versions (reachable) + …/account/whoami (authed)
threads	m.thread relations ↔ threadId

Local homeserver (infra, not connector code)

Strategic default: a self-hosted homeserver on our own infra — no third-party gateway.

• Default: Conduit (Rust, single binary, low resource) — trivial to stand up for a fleet/dev homeserver.
• Alternative: Synapse (mature, feature-complete) for scale.

The connector only needs homeserver_url + user_id + room_id + an access token, so the homeserver choice is a deployment concern (a Phase-2 deploy guide), not connector code.

Phasing

Phase	Scope	This PR
1	Connector interface + types, registry + kind resolution, roster connector schema, doc	✅ yes
2	Matrix CS-API client (fetch-based send/sync/health) + registered factory + tests	follow
2	fleet init / configure connector-selection UX; roster parse wires the block	follow
2	systemd launch wiring so the orchestrator starts on the chosen connector	follow
3	Conduit deploy guide; first-party Mosaic Discord (threads) registers as a connector	follow

Back-compat & boundaries

• Existing rosters (no connector) resolve to tmux — zero change.
• Fleet core never branches on connector kind; it depends only on the interface.
• Cross-host reach rides the federation layer (W1), not a bespoke broker (north-star assumption).
• Phase 1 touches no fleet.ts core (a self-contained connectors/ module), so it is independent of the in-flight fleet-config PRs.