feat(fleet): F4 Phase 2a — Matrix CS-API connector client + factory #618

jason.woltje · 2026-06-22T08:18:34Z

jason.woltje commented

2026-06-22 08:18:34 +00:00

F4 Phase 2a — Matrix CS-API connector client + factory (#616)

The Matrix connector behind the F4 abstraction (#617). Speaks the Matrix client-server API directly over HTTPS (injectable fetch, no SDK) — homeserver-agnostic (Conduit default, Synapse alt).

What it does

MatrixConnector implements OrchestratorConnector:
- send → PUT …/rooms/{room}/send/m.room.message/{txn} (thread-aware via m.thread), 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 against the configured user).
Pure helpers buildMessageBody + parseSyncResponse make send/receive unit-testable without running the loop or a live homeserver.
registerMatrixConnector(env) registers the factory; access token from MATRIX_ACCESS_TOKEN, never the roster.

Verification

13 Matrix + 7 registry = 20 connector tests green (send PUT shape + event_id; non-2xx → not-delivered; health reachable/authed/mismatch/unreachable; sync parse incl. self-echo skip + threads; factory build + missing-block guard). tsc/eslint/prettier clean.
Still a self-contained connectors/ module — no fleet.ts changes.

Stacking

Stacked on #617 (F4 Phase 1 — the types/registry). Merge order: #617 → this. Rebases onto main after #617 lands (the #617 commit drops, leaving the Matrix-client diff).

Remaining Phase 2 (follow-ups)

init/configure connector-selection UX + roster-parse wiring (touches fleet.ts — after #615 lands to avoid churn); systemd launch wiring so the orchestrator boots on the chosen connector; Conduit deploy guide.

🤖 Generated with Claude Code

## F4 Phase 2a — Matrix CS-API connector client + factory (#616) The Matrix connector behind the F4 abstraction (#617). Speaks the **Matrix client-server API** directly over HTTPS (injectable fetch, no SDK) — homeserver-agnostic (Conduit default, Synapse alt). ### What it does - **`MatrixConnector implements OrchestratorConnector`**: - `send` → `PUT …/rooms/{room}/send/m.room.message/{txn}` (thread-aware via `m.thread`), 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 against the configured user). - Pure helpers **`buildMessageBody` + `parseSyncResponse`** make send/receive unit-testable without running the loop or a live homeserver. - **`registerMatrixConnector(env)`** registers the factory; access token from **`MATRIX_ACCESS_TOKEN`**, never the roster. ### Verification - **13 Matrix + 7 registry = 20 connector tests** green (send PUT shape + event_id; non-2xx → not-delivered; health reachable/authed/mismatch/unreachable; sync parse incl. self-echo skip + threads; factory build + missing-block guard). tsc/eslint/prettier clean. - Still a **self-contained `connectors/` module** — no `fleet.ts` changes. ### Stacking Stacked on **#617** (F4 Phase 1 — the types/registry). **Merge order: #617 → this.** Rebases onto main after #617 lands (the #617 commit drops, leaving the Matrix-client diff). ### Remaining Phase 2 (follow-ups) init/configure connector-selection UX + roster-parse wiring (touches `fleet.ts` — after #615 lands to avoid churn); systemd launch wiring so the orchestrator boots on the chosen connector; Conduit deploy guide. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jason.woltje added 2 commits 2026-06-22 08:18:35 +00:00

feat(fleet): F4 Phase 1 — orchestrator chat connector abstraction + Matrix design (#616 )

ci/woodpecker/push/ci Pipeline was canceled

Details

ci/woodpecker/pr/ci Pipeline was canceled

Details

85a93428eb

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

feat(fleet): F4 Phase 2a — Matrix CS-API connector client + factory (#616 )

ci/woodpecker/push/ci Pipeline is pending

Details

ci/woodpecker/pr/ci Pipeline is pending

Details

aefcc9b5c0

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