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

jason.woltje · 2026-06-22T08:12:06Z

jason.woltje commented

2026-06-22 08:12:06 +00:00

F4 Phase 1 — orchestrator chat connector abstraction + Matrix design (closes #616 Phase 1)

From the north-star (#613) orchestrator-chat-connector decision. Phase 1 establishes the pluggable connector abstraction (your stated goal) + the Matrix design; the live Matrix wire + UX are Phase 2 follow-ups (scoped in the doc).

What's in it

connectors/types.ts — OrchestratorConnector with exactly your interface: send / subscribe / health. Thread-aware via optional threadId so Matrix threads and the future first-party Mosaic Discord plugin (threads) drop in with no interface change. SendResult = ack; health() = liveness.
connectors/registry.ts — extensible factory registry; resolveConnectorKind defaults tmux (existing rosters unchanged — 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 (the gateway pattern), never the roster.
docs/fleet/f4-matrix-connector.md — interface, config model, Matrix client-server API mapping (fetch-based, homeserver-agnostic), Conduit-default local homeserver (Synapse alt), phasing, back-compat.

Design choices (Lead-aligned)

Connectors are peers; fleet core depends only on the interface, never branches on kind.
Matrix talks the CS-API directly (no SDK) → dependency-light + homeserver-agnostic.
Local homeserver is an infra/deploy concern (Phase-2 guide), not connector code.

Verification

7 connector tests green; tsc/eslint/prettier/sanitize clean; schema valid JSON.

Independence

No fleet.ts changes — a self-contained connectors/ module, so this is independent of the stacked #615 (no rebase coupling). Branches from current main.

Phase 2+ (follow-ups, in the doc)

Matrix CS-API client + factory; fleet init/configure connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector.

🤖 Generated with Claude Code

## F4 Phase 1 — orchestrator chat connector abstraction + Matrix design (closes #616 Phase 1) From the north-star (#613) orchestrator-chat-connector decision. Phase 1 establishes the **pluggable connector abstraction** (your stated goal) + the Matrix design; the live Matrix wire + UX are Phase 2 follow-ups (scoped in the doc). ### What's in it - **`connectors/types.ts`** — `OrchestratorConnector` with exactly your interface: **`send` / `subscribe` / `health`**. Thread-aware via optional `threadId` so Matrix threads **and the future first-party Mosaic Discord plugin (threads)** drop in with no interface change. `SendResult` = ack; `health()` = liveness. - **`connectors/registry.ts`** — extensible factory registry; `resolveConnectorKind` defaults **tmux** (existing rosters unchanged — 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** (the gateway pattern), never the roster. - **`docs/fleet/f4-matrix-connector.md`** — interface, config model, Matrix **client-server API** mapping (fetch-based, homeserver-agnostic), **Conduit-default** local homeserver (Synapse alt), phasing, back-compat. ### Design choices (Lead-aligned) - Connectors are **peers**; fleet core depends only on the interface, never branches on kind. - Matrix talks the CS-API directly (no SDK) → dependency-light + homeserver-agnostic. - Local homeserver is an **infra/deploy** concern (Phase-2 guide), not connector code. ### Verification - **7 connector tests** green; tsc/eslint/prettier/**sanitize** clean; schema valid JSON. ### Independence **No `fleet.ts` changes** — a self-contained `connectors/` module, so this is independent of the stacked #615 (no rebase coupling). Branches from current main. ### Phase 2+ (follow-ups, in the doc) Matrix CS-API client + factory; `fleet init`/`configure` connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jason.woltje added 1 commit 2026-06-22 08:12:07 +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