Implements the Matrix connector behind the F4 abstraction (stacked on #617).
Speaks the Matrix client-server API directly over HTTPS (injectable fetch, no
SDK) so it is homeserver-agnostic (Conduit default, Synapse alt).
- MatrixConnector implements OrchestratorConnector:
- send → PUT /_matrix/client/v3/rooms/{room}/send/m.room.message/{txn}
(thread-aware via m.thread relation), returns event_id.
- subscribe → /sync long-poll loop driven by the pure parseSyncResponse
(skips the orchestrator's own echoes; carries threadId).
- health → /_matrix/client/versions (reachable) + /account/whoami (authed).
- Pure helpers buildMessageBody + parseSyncResponse → send/receive unit-testable.
- registerMatrixConnector(env) registers the factory; the access token comes from
MATRIX_ACCESS_TOKEN, never the roster.
Verified: 13 Matrix + 7 registry = 20 connector tests green; tsc/eslint/prettier
clean. Still a self-contained connectors/ module (no fleet.ts changes).
Stacked on #617 (F4 Phase 1). Merge order: #617 -> this; rebases onto main after.
Refs #616, #613
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83
From the north-star (#613) orchestrator-chat-connector decision: make the
orchestrator's chat channel a pluggable, user-chosen connector (tmux | discord
| matrix peers) and add Matrix (local homeserver) — starting with the small
uniform abstraction so connectors drop in without touching fleet core.
Phase 1 (this PR — design + scaffold):
- src/fleet/connectors/types.ts: OrchestratorConnector interface (send /
subscribe / health per the Lead's spec) + message/config types; thread-aware
via optional threadId so Matrix threads + the future first-party Mosaic
Discord plugin fit without an interface change. DEFAULT_CONNECTOR_KIND=tmux.
- src/fleet/connectors/registry.ts: extensible factory registry;
resolveConnectorKind defaults tmux (back-compat); createConnector throws
ConnectorNotImplementedError until Phase 2 registers factories.
- roster.schema.json: optional connector block (tmux|discord|matrix; matrix
homeserver/user/room). Secrets via env (gateway pattern), never the roster.
- docs/fleet/f4-matrix-connector.md: interface, config, Matrix client-server API
mapping, Conduit-default local homeserver, phasing, back-compat.
Self-contained connectors/ module — NO fleet.ts changes, so independent of the
in-flight stacked fleet-config PR (#615).
Verified: 7 connector tests green; tsc/eslint/prettier/sanitize clean; schema
valid JSON.
Refs #616, #613
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EsgTQzV5YUGk1JtCLP4B83
