Compare commits
2 Commits
feat/f4-ma
...
feat/f4-ma
| Author | SHA1 | Date | |
|---|---|---|---|
| aefcc9b5c0 | |||
| 85a93428eb |
@@ -4,23 +4,6 @@
|
|||||||
variables:
|
variables:
|
||||||
- &node_image 'node:22-alpine'
|
- &node_image 'node:22-alpine'
|
||||||
- &enable_pnpm 'corepack enable'
|
- &enable_pnpm 'corepack enable'
|
||||||
# Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
|
|
||||||
# the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
|
|
||||||
# images (gateway/appservice/web do not depend on @mosaicstack/mosaic). Releases
|
|
||||||
# (tags) always build everything. Exclude-list keeps the default SAFE: any
|
|
||||||
# non-excluded change still builds, so no transitive dep can silently go stale.
|
|
||||||
# (Woodpecker: `when` entries are OR'd; `path` applies to push/PR only — hence
|
|
||||||
# the separate `event: tag` entry.)
|
|
||||||
- &image_build_when
|
|
||||||
- event: tag
|
|
||||||
- event: [push, manual]
|
|
||||||
branch: main
|
|
||||||
path:
|
|
||||||
exclude:
|
|
||||||
- 'packages/mosaic/**'
|
|
||||||
- 'docs/**'
|
|
||||||
- '**/*.md'
|
|
||||||
- '.woodpecker/**'
|
|
||||||
|
|
||||||
when:
|
when:
|
||||||
- branch: [main]
|
- branch: [main]
|
||||||
@@ -43,15 +26,6 @@ steps:
|
|||||||
|
|
||||||
publish-npm:
|
publish-npm:
|
||||||
image: *node_image
|
image: *node_image
|
||||||
# Publish only when a publishable package changed (or on a release tag); a
|
|
||||||
# pure-docs merge runs no publish. Cheap step, but gated for cleanliness.
|
|
||||||
when:
|
|
||||||
- event: tag
|
|
||||||
- event: [push, manual]
|
|
||||||
branch: main
|
|
||||||
path:
|
|
||||||
include:
|
|
||||||
- 'packages/**'
|
|
||||||
environment:
|
environment:
|
||||||
NPM_TOKEN:
|
NPM_TOKEN:
|
||||||
from_secret: gitea_token
|
from_secret: gitea_token
|
||||||
@@ -117,7 +91,6 @@ steps:
|
|||||||
|
|
||||||
build-gateway:
|
build-gateway:
|
||||||
image: gcr.io/kaniko-project/executor:debug
|
image: gcr.io/kaniko-project/executor:debug
|
||||||
when: *image_build_when
|
|
||||||
environment:
|
environment:
|
||||||
REGISTRY_USER:
|
REGISTRY_USER:
|
||||||
from_secret: gitea_username
|
from_secret: gitea_username
|
||||||
@@ -143,7 +116,6 @@ steps:
|
|||||||
|
|
||||||
build-appservice:
|
build-appservice:
|
||||||
image: gcr.io/kaniko-project/executor:debug
|
image: gcr.io/kaniko-project/executor:debug
|
||||||
when: *image_build_when
|
|
||||||
environment:
|
environment:
|
||||||
REGISTRY_USER:
|
REGISTRY_USER:
|
||||||
from_secret: gitea_username
|
from_secret: gitea_username
|
||||||
@@ -169,7 +141,6 @@ steps:
|
|||||||
|
|
||||||
build-web:
|
build-web:
|
||||||
image: gcr.io/kaniko-project/executor:debug
|
image: gcr.io/kaniko-project/executor:debug
|
||||||
when: *image_build_when
|
|
||||||
environment:
|
environment:
|
||||||
REGISTRY_USER:
|
REGISTRY_USER:
|
||||||
from_secret: gitea_username
|
from_secret: gitea_username
|
||||||
|
|||||||
@@ -59,14 +59,6 @@ Active workstream is **W1 — Federation v1**. Workers should:
|
|||||||
|
|
||||||
- Status: implemented + tested. Closes R13: `mosaic update` now re-seeds the framework (data-safe MOSAIC_SYNC_ONLY) after the CLI install so shipped launcher/runtime changes activate; `--relaunch` restarts rostered agents; `--no-reseed` opts out. Detail: scratchpads/f3-m3-update-reseed.md.
|
- Status: implemented + tested. Closes R13: `mosaic update` now re-seeds the framework (data-safe MOSAIC_SYNC_ONLY) after the CLI install so shipped launcher/runtime changes activate; `--relaunch` restarts rostered agents; `--no-reseed` opts out. Detail: scratchpads/f3-m3-update-reseed.md.
|
||||||
|
|
||||||
## Fleet-polish bundle — boot-survival symmetry (#611) — feat/fleet-polish-bundle
|
|
||||||
|
|
||||||
- Status: MERGED to main. disable-on-remove (boot-resurrection bug, TDD) + add-enable + init-R5 hard guarantee. 4 new + 147 existing fleet tests green. Detail: scratchpads/fleet-polish-bundle.md.
|
|
||||||
|
|
||||||
## Fleet enhancer role + two-agent floor (#614) — feat/fleet-enhancer-floor
|
|
||||||
|
|
||||||
- Status: MERGED to main. enhancer added to 4 presets; init guarantees 1 orchestrator + >=1 enhancer; remove protects the sole enhancer; enhancer role doc. 155 fleet tests green. Detail: scratchpads/fleet-enhancer-floor.md.
|
|
||||||
|
|
||||||
## F4 — Orchestrator chat connector + Matrix (#616) — feat/f4-matrix-connector
|
## F4 — Orchestrator chat connector + Matrix (#616) — feat/f4-matrix-connector
|
||||||
|
|
||||||
- Status: Phase 1 done (abstraction + scaffold). Connector interface (send/subscribe/health) + registry + roster connector schema + design doc; tmux default/back-compat; matrix/discord factories are Phase 2. 7 tests green; no fleet.ts changes. Detail: scratchpads/f4-matrix-connector.md.
|
- Status: Phase 1 done (abstraction + scaffold). Connector interface (send/subscribe/health) + registry + roster connector schema + design doc; tmux default/back-compat; matrix factory + CS-API client landed (Phase 2a, #617-stacked); 20 connector tests green; no fleet.ts changes (independent of #615). Detail: scratchpads/f4-matrix-connector.md.
|
||||||
|
|||||||
@@ -73,37 +73,6 @@ diff-sanity → squash-merge → verify), **decide-and-inform** cadence, and a d
|
|||||||
this model. See `mosaicstack-aiguide` whitepapers 01 (inter-agent comms) and 03
|
this model. See `mosaicstack-aiguide` whitepapers 01 (inter-agent comms) and 03
|
||||||
(orchestration model) for the rationale.
|
(orchestration model) for the rationale.
|
||||||
|
|
||||||
## Fleet roster — the two-agent floor and the role library
|
|
||||||
|
|
||||||
A fleet is **never a single agent**. The minimum viable fleet is **two**:
|
|
||||||
|
|
||||||
| Role | Mandate | Boundaries |
|
|
||||||
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
||||||
| **Orchestrator** | The user's **single point of contact**. Owns the general flow, keeps agentic actions on-target, and **adds/removes agents from the fleet at will** to meet goals and user needs. Exactly **one** per fleet (the existing R5 invariant). | Delegates source work; never the sole worker. |
|
|
||||||
| **Enhancer** | The fleet's **continuous-improvement loop**. Monitors fleet activity, analyzes for enhancements/optimizations, builds a **plan of remediation**, and — **with the orchestrator** — upgrades fleet capability: tool creation/repair, skills, harness improvements, and **bug reports filed to Mosaic Stack** for proper remediation. Recommends which agents are needed. | **Does not code, review code, or perform delivery tasks.** Improvement and diagnosis only. |
|
|
||||||
|
|
||||||
> **Why two, not one:** the orchestrator drives delivery; the enhancer makes the fleet
|
|
||||||
> _get better at delivering_ over time. The enhancer is how the fleet self-heals its tools,
|
|
||||||
> skills, and harnesses, and how real defects flow back to Mosaic Stack as bug reports.
|
|
||||||
> Together they are the irreducible core — every other role is added on demand.
|
|
||||||
|
|
||||||
A **general** fleet starts at this floor: the orchestrator (advised by the enhancer)
|
|
||||||
materializes whatever roles prove necessary over the mission's life. Specialized presets
|
|
||||||
(coding, research, etc.) seed additional roles up front, but all reduce to the same two-agent
|
|
||||||
spine plus an on-demand **role library**:
|
|
||||||
|
|
||||||
| Role profile | Purpose |
|
|
||||||
| ------------------- | --------------------------------------------------------------------------------- |
|
|
||||||
| **orchestrator** | point of contact, flow control, fleet composition (1 per fleet) |
|
|
||||||
| **enhancer** | fleet monitoring, optimization, tool/skill/harness upgrades, upstream bug reports |
|
|
||||||
| **coder** | implementation (worker; stops at PR-open) |
|
|
||||||
| **code review** | independent code review gate |
|
|
||||||
| **security review** | security/auth/secret review gate |
|
|
||||||
| **research** | investigation, synthesis, options analysis |
|
|
||||||
| **board** | deliberation panel — moonshot, contrarian, technical, business, financial lenses |
|
|
||||||
| **operations** | infra, deploy, health, incident response |
|
|
||||||
| _…extensible_ | new profiles added as missions demand (orchestrator + enhancer decide) |
|
|
||||||
|
|
||||||
## Invariants — "maximal vision, incremental delivery, zero foreclosure"
|
## Invariants — "maximal vision, incremental delivery, zero foreclosure"
|
||||||
|
|
||||||
Every artifact, starting Phase 2, MUST:
|
Every artifact, starting Phase 2, MUST:
|
||||||
@@ -133,7 +102,7 @@ Every artifact, starting Phase 2, MUST:
|
|||||||
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||||
| 0–1 | tmux PoC, hardening, published CLI v0.0.34 (#565–#568) | ✅ done |
|
| 0–1 | tmux PoC, hardening, published CLI v0.0.34 (#565–#568) | ✅ done |
|
||||||
| **2 — Observability** | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts | ▶ now |
|
| **2 — Observability** | `fleet ps` (host+tenant aware join), heartbeat protocol + dogfood stub answers it, `agent watch` (read-only), `agent send --verify` receipts | ▶ now |
|
||||||
| 3 — Real runtimes | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: **orchestrator + enhancer**; ephemeral workers per lane) | planned |
|
| 3 — Real runtimes | claude/codex/pi/opencode answer heartbeat; **hybrid lifecycle** (core always-on: orchestrator+reviewer; ephemeral workers per lane) | planned |
|
||||||
| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning | planned |
|
| 4 — Unified definition | one agent schema in gateway; `mosaic agent --new` → materialized per-tenant session; uid-tenant provisioning | planned |
|
||||||
| 5 — Control plane | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity | planned |
|
| 5 — Control plane | federation-backed cross-host × cross-tenant fleet view; **webUI** (surface chosen then) for MVP-X1 parity | planned |
|
||||||
|
|
||||||
@@ -152,28 +121,6 @@ Every artifact, starting Phase 2, MUST:
|
|||||||
runtime-bin on PATH (baked into the pane command) + boot-survival (`enable` + linger),
|
runtime-bin on PATH (baked into the pane command) + boot-survival (`enable` + linger),
|
||||||
which `fleet init` should automate.
|
which `fleet init` should automate.
|
||||||
|
|
||||||
## Decisions of record (2026-06-22, with Jason)
|
|
||||||
|
|
||||||
- **Two-agent floor:** every fleet has, at minimum, an **orchestrator** and an **enhancer**.
|
|
||||||
The orchestrator is the user's point of contact and composes the fleet; the enhancer runs the
|
|
||||||
continuous-improvement loop (monitor → analyze → remediate → upgrade tools/skills/harness →
|
|
||||||
file Mosaic Stack bug reports) and **does not code or review**.
|
|
||||||
- **Role library:** orchestrator, enhancer, coder, code review, security review, research,
|
|
||||||
board (moonshot/contrarian/technical/business/financial), operations — extensible; the
|
|
||||||
orchestrator (advised by the enhancer) adds roles as missions demand.
|
|
||||||
- **Orchestrator chat connector:** the orchestrator is reachable over a user-chosen connector
|
|
||||||
(tmux now; Telegram/Discord/Matrix/Slack configurable). Validated live: **"Mos" orchestrator
|
|
||||||
on Discord** via the Claude Code discord channel plugin (w-jarvis).
|
|
||||||
|
|
||||||
## Future enhancements (north-star, post-MVP — not on the MVP track)
|
|
||||||
|
|
||||||
- **Mosaic Claude Discord Plugin** — a first-party Mosaic Discord connector that properly
|
|
||||||
implements the basic Discord functions **and native Discord threads**. Threads let a user
|
|
||||||
separate conversation topics with the orchestrator (the pattern proven by the Hermes agent).
|
|
||||||
A major enhancement over the current third-party channel plugin; **not required for the MVP**,
|
|
||||||
but a committed north-star target. `ASSUMPTION:` ships as a Mosaic-owned plugin so the fleet
|
|
||||||
controls Discord UX (threads, reactions, attachments, per-thread context) end-to-end.
|
|
||||||
|
|
||||||
## Assumptions (veto-able)
|
## Assumptions (veto-able)
|
||||||
|
|
||||||
- `ASSUMPTION:` first-class runtimes = claude, codex, pi, opencode; a "role" (analyst,
|
- `ASSUMPTION:` first-class runtimes = claude, codex, pi, opencode; a "role" (analyst,
|
||||||
|
|||||||
@@ -17,3 +17,14 @@
|
|||||||
## Phase 2+ (follow-ups, in the doc)
|
## Phase 2+ (follow-ups, in the doc)
|
||||||
|
|
||||||
Matrix CS-API client (fetch send/sync/health) + factory; init/configure connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector.
|
Matrix CS-API client (fetch send/sync/health) + factory; init/configure connector-selection UX + roster-parse wiring; systemd launch wiring; Conduit deploy guide; first-party Mosaic Discord (threads) as a connector.
|
||||||
|
|
||||||
|
## Phase 2a (feat/f4-matrix-client, stacked on #617) — Matrix CS-API client
|
||||||
|
|
||||||
|
- `src/fleet/connectors/matrix.ts`: `MatrixConnector implements OrchestratorConnector` over the Matrix
|
||||||
|
client-server API (injectable fetch, no SDK). `send` → PUT m.room.message (thread-aware); `subscribe`
|
||||||
|
→ /sync long-poll loop using the pure `parseSyncResponse`; `health` → /versions + /whoami.
|
||||||
|
`registerMatrixConnector(env)` registers the factory (token from MATRIX_ACCESS_TOKEN, never roster).
|
||||||
|
- Pure helpers `buildMessageBody` + `parseSyncResponse` make send/receive unit-testable.
|
||||||
|
- 13 Matrix tests + 7 registry = 20 connector tests green; tsc/eslint/prettier clean.
|
||||||
|
- Remaining Phase 2: init/configure connector-selection UX + roster-parse wiring (touches fleet.ts —
|
||||||
|
after #615); systemd launch wiring; Conduit deploy guide.
|
||||||
|
|||||||
@@ -1,26 +0,0 @@
|
|||||||
# Fleet enhancer role + two-agent floor (#614)
|
|
||||||
|
|
||||||
- **Issue:** #614 · **Branch:** `feat/fleet-enhancer-floor` (stacked on #612 `feat/fleet-polish-bundle`)
|
|
||||||
- **Doctrine:** `docs/fleet/north-star.md` (PR #613) — every fleet = orchestrator + enhancer minimum.
|
|
||||||
|
|
||||||
## Changes
|
|
||||||
|
|
||||||
- **Presets** (general, coding, research, hybrid): add `enhancer` (claude, `class: enhancer`,
|
|
||||||
`persistent_persona: true`) as a core always-on agent alongside the orchestrator. minimal/local-canary
|
|
||||||
unchanged.
|
|
||||||
- **fleet.ts**: `countEnhancers` helper; init guarantee extended — non-minimal profiles must yield
|
|
||||||
exactly 1 orchestrator AND >=1 enhancer (hard-fail otherwise); `removeAgentFromRoster` refuses to drop
|
|
||||||
the sole enhancer (symmetric with the sole-orchestrator guard) so the floor holds at runtime, not just init.
|
|
||||||
- **Role doc**: `framework/fleet/roles/enhancer.md` — the enhancer mandate (monitor → analyze → plan →
|
|
||||||
upgrade tools/skills/harness WITH orchestrator → file Mosaic Stack bug reports) + boundaries (does NOT
|
|
||||||
code or review).
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
- 155 fleet tests green (new: countEnhancers; remove-sole-enhancer guard; remove-allows-when-another;
|
|
||||||
init two-agent-floor; every-non-minimal-preset-has-enhancer; updated preset rosters). tsc/eslint/
|
|
||||||
prettier/sanitize clean. TDD on the init guarantee + remove protection.
|
|
||||||
|
|
||||||
## Stacking
|
|
||||||
|
|
||||||
Built on #612's init-R5 code. PR shows #612 + enhancer until #612 merges; then rebase onto main → clean.
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
# Fleet-polish bundle — boot-survival symmetry (#611)
|
|
||||||
|
|
||||||
- **Issue:** #611 · **Branch:** `feat/fleet-polish-bundle` · From the Lead's Codex symmetry-gap finding.
|
|
||||||
|
|
||||||
## Three fixes
|
|
||||||
|
|
||||||
1. **disable-on-remove (BUG, TDD).** `fleet remove` stopped + deleted roster/env/heartbeat but never
|
|
||||||
`systemctl --user disable mosaic-agent@NAME.service` → a removed-but-enabled unit could resurrect on
|
|
||||||
reboot pointing at deleted config. Fix: `buildSystemdDisableCommand` + disable in `remove`
|
|
||||||
(best-effort, gated on !--keep-files).
|
|
||||||
2. **add-enable.** `fleet add` now enables the new agent's unit for boot-survival (best-effort,
|
|
||||||
independent of --start) — symmetry with disable-on-remove.
|
|
||||||
3. **init-R5 guarantee.** `fleet init --write` now FAILS HARD when a non-minimal profile doesn't yield
|
|
||||||
exactly one orchestrator (was a soft warning). `minimal` (sanctioned no-orchestrator) still allowed.
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
- 4 new tests (disable builder; remove-invokes-disable; add-invokes-enable; init general → exactly 1
|
|
||||||
orchestrator) + 147 existing fleet tests green (151 total). tsc/eslint/prettier clean.
|
|
||||||
- TDD on the disable bug per contract.
|
|
||||||
@@ -15,10 +15,6 @@ agents:
|
|||||||
runtime: claude
|
runtime: claude
|
||||||
class: orchestrator
|
class: orchestrator
|
||||||
persistent_persona: true
|
persistent_persona: true
|
||||||
- name: enhancer
|
|
||||||
runtime: claude
|
|
||||||
class: enhancer
|
|
||||||
persistent_persona: true
|
|
||||||
- name: coder0
|
- name: coder0
|
||||||
runtime: pi
|
runtime: pi
|
||||||
class: implementer
|
class: implementer
|
||||||
|
|||||||
@@ -15,10 +15,6 @@ agents:
|
|||||||
runtime: claude
|
runtime: claude
|
||||||
class: orchestrator
|
class: orchestrator
|
||||||
persistent_persona: true
|
persistent_persona: true
|
||||||
- name: enhancer
|
|
||||||
runtime: claude
|
|
||||||
class: enhancer
|
|
||||||
persistent_persona: true
|
|
||||||
- name: generalist
|
- name: generalist
|
||||||
runtime: pi
|
runtime: pi
|
||||||
class: worker
|
class: worker
|
||||||
|
|||||||
@@ -15,10 +15,6 @@ agents:
|
|||||||
runtime: claude
|
runtime: claude
|
||||||
class: orchestrator
|
class: orchestrator
|
||||||
persistent_persona: true
|
persistent_persona: true
|
||||||
- name: enhancer
|
|
||||||
runtime: claude
|
|
||||||
class: enhancer
|
|
||||||
persistent_persona: true
|
|
||||||
- name: coder0
|
- name: coder0
|
||||||
runtime: pi
|
runtime: pi
|
||||||
class: implementer
|
class: implementer
|
||||||
|
|||||||
@@ -15,10 +15,6 @@ agents:
|
|||||||
runtime: claude
|
runtime: claude
|
||||||
class: orchestrator
|
class: orchestrator
|
||||||
persistent_persona: true
|
persistent_persona: true
|
||||||
- name: enhancer
|
|
||||||
runtime: claude
|
|
||||||
class: enhancer
|
|
||||||
persistent_persona: true
|
|
||||||
- name: researcher0
|
- name: researcher0
|
||||||
runtime: pi
|
runtime: pi
|
||||||
class: researcher
|
class: researcher
|
||||||
|
|||||||
@@ -1,41 +0,0 @@
|
|||||||
# Enhancer — fleet role definition
|
|
||||||
|
|
||||||
The **enhancer** is one half of the fleet's two-agent floor: every fleet runs, at
|
|
||||||
minimum, an **orchestrator** and an **enhancer**. The orchestrator drives delivery;
|
|
||||||
the enhancer makes the fleet _get better at delivering_ over time.
|
|
||||||
|
|
||||||
It is a **core, always-on** agent (`class: enhancer`, `persistent_persona: true`),
|
|
||||||
not an ephemeral per-lane worker.
|
|
||||||
|
|
||||||
## Mandate
|
|
||||||
|
|
||||||
The enhancer runs the fleet's **continuous-improvement loop**:
|
|
||||||
|
|
||||||
1. **Monitor** fleet activity — agents, heartbeats, sessions, throughput, failures.
|
|
||||||
2. **Analyze** for enhancements and optimizations — friction, gaps, recurring defects,
|
|
||||||
missing or broken tools, skill/harness shortfalls.
|
|
||||||
3. **Plan** a remediation: a concrete improvement with rationale and expected effect.
|
|
||||||
4. **Upgrade fleet capability — with the orchestrator** — tool creation/repair, skills,
|
|
||||||
harness improvements. The orchestrator owns fleet composition; the enhancer advises and
|
|
||||||
implements improvements to the _means of production_, not the product.
|
|
||||||
5. **File upstream bug reports** to Mosaic Stack for real defects, so they flow back to the
|
|
||||||
framework for proper remediation rather than being patched over locally.
|
|
||||||
6. **Recommend which agents are needed** — advise the orchestrator on roles to add/remove as
|
|
||||||
the mission evolves.
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
- **Does NOT write product/source code.**
|
|
||||||
- **Does NOT review code** (that is the code-review / security-review roles).
|
|
||||||
- **Does NOT perform delivery tasks.**
|
|
||||||
|
|
||||||
Improvement and diagnosis only. When the enhancer finds work that requires coding or review,
|
|
||||||
it files it (bug report / recommendation) and the orchestrator materializes the right worker.
|
|
||||||
|
|
||||||
## Why two, not one
|
|
||||||
|
|
||||||
The orchestrator alone optimizes for _this_ delivery; the enhancer optimizes for _every future_
|
|
||||||
delivery — self-healing the fleet's tools, skills, and harnesses, and routing real defects
|
|
||||||
upstream. Together they are the irreducible core; every other role is added on demand.
|
|
||||||
|
|
||||||
> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).
|
|
||||||
@@ -14,13 +14,11 @@ import {
|
|||||||
buildEnableLingerCommand,
|
buildEnableLingerCommand,
|
||||||
buildFleetServiceCommand,
|
buildFleetServiceCommand,
|
||||||
buildSystemdEnableCommand,
|
buildSystemdEnableCommand,
|
||||||
buildSystemdDisableCommand,
|
|
||||||
buildSystemdShowCommand,
|
buildSystemdShowCommand,
|
||||||
buildTmuxListPanesCommand,
|
buildTmuxListPanesCommand,
|
||||||
buildTmuxListSessionsCommand,
|
buildTmuxListSessionsCommand,
|
||||||
classifySendResult,
|
classifySendResult,
|
||||||
countOrchestrators,
|
countOrchestrators,
|
||||||
countEnhancers,
|
|
||||||
detectDrift,
|
detectDrift,
|
||||||
enableFleetUnits,
|
enableFleetUnits,
|
||||||
FLEET_PROFILES,
|
FLEET_PROFILES,
|
||||||
@@ -985,129 +983,6 @@ describe('fleet ps — drift detection', () => {
|
|||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
describe('fleet-polish bundle — boot-survival symmetry', () => {
|
|
||||||
async function rosterHome(agents: string): Promise<string> {
|
|
||||||
const home = await tempDir();
|
|
||||||
await mkdir(join(home, 'fleet'), { recursive: true });
|
|
||||||
await writeFile(join(home, 'fleet', 'roster.yaml'), agents);
|
|
||||||
return home;
|
|
||||||
}
|
|
||||||
|
|
||||||
it('buildSystemdDisableCommand returns the systemctl --user disable array', () => {
|
|
||||||
expect(buildSystemdDisableCommand('mosaic-agent@coder0.service')).toEqual([
|
|
||||||
'systemctl',
|
|
||||||
'--user',
|
|
||||||
'disable',
|
|
||||||
'mosaic-agent@coder0.service',
|
|
||||||
]);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('fleet remove DISABLES the unit so a removed agent cannot resurrect on boot', async () => {
|
|
||||||
const home = await rosterHome(
|
|
||||||
[
|
|
||||||
'version: 1',
|
|
||||||
'transport: tmux',
|
|
||||||
'agents:',
|
|
||||||
' - name: orchestrator',
|
|
||||||
' runtime: pi',
|
|
||||||
' class: orchestrator',
|
|
||||||
' - name: coder0',
|
|
||||||
' runtime: codex',
|
|
||||||
' class: worker',
|
|
||||||
].join('\n') + '\n',
|
|
||||||
);
|
|
||||||
const calls: string[][] = [];
|
|
||||||
const runner: CommandRunner = async (command, args) => {
|
|
||||||
calls.push([command, ...args]);
|
|
||||||
return { stdout: '', stderr: '', exitCode: 0 };
|
|
||||||
};
|
|
||||||
const program = new Command();
|
|
||||||
program.exitOverride();
|
|
||||||
registerFleetCommand(program, { runner, mosaicHome: home });
|
|
||||||
try {
|
|
||||||
await program.parseAsync(['node', 'mosaic', 'fleet', 'remove', 'coder0']);
|
|
||||||
expect(calls).toContainEqual([
|
|
||||||
'systemctl',
|
|
||||||
'--user',
|
|
||||||
'disable',
|
|
||||||
'mosaic-agent@coder0.service',
|
|
||||||
]);
|
|
||||||
// stop must still happen too
|
|
||||||
expect(calls).toContainEqual(['systemctl', '--user', 'stop', 'mosaic-agent@coder0.service']);
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it('fleet add ENABLES the new agent unit for boot-survival', async () => {
|
|
||||||
const home = await rosterHome(
|
|
||||||
['version: 1', 'transport: tmux', 'agents:', ' - name: coder0', ' runtime: codex'].join(
|
|
||||||
'\n',
|
|
||||||
) + '\n',
|
|
||||||
);
|
|
||||||
const calls: string[][] = [];
|
|
||||||
const runner: CommandRunner = async (command, args) => {
|
|
||||||
calls.push([command, ...args]);
|
|
||||||
return { stdout: '', stderr: '', exitCode: 0 };
|
|
||||||
};
|
|
||||||
const program = new Command();
|
|
||||||
program.exitOverride();
|
|
||||||
registerFleetCommand(program, { runner, mosaicHome: home });
|
|
||||||
try {
|
|
||||||
await program.parseAsync([
|
|
||||||
'node',
|
|
||||||
'mosaic',
|
|
||||||
'fleet',
|
|
||||||
'add',
|
|
||||||
'coder1',
|
|
||||||
'--runtime',
|
|
||||||
'codex',
|
|
||||||
'--class',
|
|
||||||
'worker',
|
|
||||||
'--no-start',
|
|
||||||
]);
|
|
||||||
expect(calls).toContainEqual([
|
|
||||||
'systemctl',
|
|
||||||
'--user',
|
|
||||||
'enable',
|
|
||||||
'mosaic-agent@coder1.service',
|
|
||||||
]);
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it('fleet init --write enforces the two-agent floor (1 orchestrator + >=1 enhancer)', async () => {
|
|
||||||
// The general profile must yield exactly one orchestrator AND at least one
|
|
||||||
// enhancer; the guarantee is enforced (not just warned). Happy path writes cleanly.
|
|
||||||
const home = await tempDir();
|
|
||||||
const program = new Command();
|
|
||||||
program.exitOverride();
|
|
||||||
registerFleetCommand(program, {
|
|
||||||
runner: async () => ({ stdout: '', stderr: '', exitCode: 0 }),
|
|
||||||
mosaicHome: home,
|
|
||||||
});
|
|
||||||
try {
|
|
||||||
await program.parseAsync([
|
|
||||||
'node',
|
|
||||||
'mosaic',
|
|
||||||
'fleet',
|
|
||||||
'init',
|
|
||||||
'--profile',
|
|
||||||
'general',
|
|
||||||
'--write',
|
|
||||||
]);
|
|
||||||
const written = await readFile(join(home, 'fleet', 'roster.yaml'), 'utf8');
|
|
||||||
const orchestrators = (written.match(/class:\s*orchestrator/g) ?? []).length;
|
|
||||||
const enhancers = (written.match(/class:\s*enhancer/g) ?? []).length;
|
|
||||||
expect(orchestrators).toBe(1);
|
|
||||||
expect(enhancers).toBeGreaterThanOrEqual(1);
|
|
||||||
} finally {
|
|
||||||
await rm(home, { recursive: true, force: true });
|
|
||||||
}
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
describe('fleet install — auto-enable units for boot-survival', () => {
|
describe('fleet install — auto-enable units for boot-survival', () => {
|
||||||
it('buildSystemdEnableCommand and buildEnableLingerCommand return correct command arrays', () => {
|
it('buildSystemdEnableCommand and buildEnableLingerCommand return correct command arrays', () => {
|
||||||
expect(buildSystemdEnableCommand('mosaic-tmux-holder.service')).toEqual([
|
expect(buildSystemdEnableCommand('mosaic-tmux-holder.service')).toEqual([
|
||||||
@@ -2313,63 +2188,47 @@ describe('fleet preset rosters', () => {
|
|||||||
},
|
},
|
||||||
);
|
);
|
||||||
|
|
||||||
it('general preset: orchestrator + enhancer + one generalist worker', async () => {
|
it('general preset: orchestrator + one generalist worker', async () => {
|
||||||
const roster = await loadFleetRoster(join(examplesDir, 'general.yaml'));
|
const roster = await loadFleetRoster(join(examplesDir, 'general.yaml'));
|
||||||
expect(roster.agents.map((a) => a.name)).toEqual(['orchestrator', 'enhancer', 'generalist']);
|
expect(roster.agents.map((a) => a.name)).toEqual(['orchestrator', 'generalist']);
|
||||||
expect(roster.agents.find((a) => a.name === 'orchestrator')?.runtime).toBe('claude');
|
expect(roster.agents.find((a) => a.name === 'orchestrator')?.runtime).toBe('claude');
|
||||||
expect(roster.agents.find((a) => a.name === 'enhancer')?.className).toBe('enhancer');
|
|
||||||
expect(roster.agents.find((a) => a.name === 'generalist')?.runtime).toBe('pi');
|
expect(roster.agents.find((a) => a.name === 'generalist')?.runtime).toBe('pi');
|
||||||
});
|
});
|
||||||
|
|
||||||
it('coding preset: orchestrator + enhancer + coder0 + coder1 + reviewer', async () => {
|
it('coding preset: orchestrator + coder0 + coder1 + reviewer', async () => {
|
||||||
const roster = await loadFleetRoster(join(examplesDir, 'coding.yaml'));
|
const roster = await loadFleetRoster(join(examplesDir, 'coding.yaml'));
|
||||||
expect(roster.agents.map((a) => a.name)).toEqual([
|
expect(roster.agents.map((a) => a.name)).toEqual([
|
||||||
'orchestrator',
|
'orchestrator',
|
||||||
'enhancer',
|
|
||||||
'coder0',
|
'coder0',
|
||||||
'coder1',
|
'coder1',
|
||||||
'reviewer',
|
'reviewer',
|
||||||
]);
|
]);
|
||||||
});
|
});
|
||||||
|
|
||||||
it('research preset: orchestrator + enhancer + researcher0 + researcher1 + analyst', async () => {
|
it('research preset: orchestrator + researcher0 + researcher1 + analyst', async () => {
|
||||||
const roster = await loadFleetRoster(join(examplesDir, 'research.yaml'));
|
const roster = await loadFleetRoster(join(examplesDir, 'research.yaml'));
|
||||||
expect(roster.agents.map((a) => a.name)).toEqual([
|
expect(roster.agents.map((a) => a.name)).toEqual([
|
||||||
'orchestrator',
|
'orchestrator',
|
||||||
'enhancer',
|
|
||||||
'researcher0',
|
'researcher0',
|
||||||
'researcher1',
|
'researcher1',
|
||||||
'analyst',
|
'analyst',
|
||||||
]);
|
]);
|
||||||
});
|
});
|
||||||
|
|
||||||
it('hybrid preset: orchestrator + enhancer + coder0 + researcher0 + reviewer', async () => {
|
it('hybrid preset: orchestrator + coder0 + researcher0 + reviewer', async () => {
|
||||||
const roster = await loadFleetRoster(join(examplesDir, 'hybrid.yaml'));
|
const roster = await loadFleetRoster(join(examplesDir, 'hybrid.yaml'));
|
||||||
expect(roster.agents.map((a) => a.name)).toEqual([
|
expect(roster.agents.map((a) => a.name)).toEqual([
|
||||||
'orchestrator',
|
'orchestrator',
|
||||||
'enhancer',
|
|
||||||
'coder0',
|
'coder0',
|
||||||
'researcher0',
|
'researcher0',
|
||||||
'reviewer',
|
'reviewer',
|
||||||
]);
|
]);
|
||||||
});
|
});
|
||||||
|
|
||||||
it('every non-minimal preset carries an enhancer (two-agent floor)', async () => {
|
|
||||||
for (const preset of ['general', 'coding', 'research', 'hybrid'] as FleetProfile[]) {
|
|
||||||
const roster = await loadFleetRoster(join(examplesDir, `${preset}.yaml`));
|
|
||||||
expect(countOrchestrators(roster)).toBe(1);
|
|
||||||
expect(countEnhancers(roster)).toBeGreaterThanOrEqual(1);
|
|
||||||
expect(roster.agents.find((a) => a.className === 'enhancer')?.runtime).toBe('claude');
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
it('worker agents in new presets use pi runtime with model_hint openai-codex/gpt-5.5:high', async () => {
|
it('worker agents in new presets use pi runtime with model_hint openai-codex/gpt-5.5:high', async () => {
|
||||||
for (const preset of ['general', 'coding', 'research', 'hybrid'] as FleetProfile[]) {
|
for (const preset of ['general', 'coding', 'research', 'hybrid'] as FleetProfile[]) {
|
||||||
const roster = await loadFleetRoster(join(examplesDir, `${preset}.yaml`));
|
const roster = await loadFleetRoster(join(examplesDir, `${preset}.yaml`));
|
||||||
// Core agents (orchestrator + enhancer) run claude; only ephemeral workers are pi.
|
const workers = roster.agents.filter((a) => a.name !== 'orchestrator');
|
||||||
const workers = roster.agents.filter(
|
|
||||||
(a) => a.className !== 'orchestrator' && a.className !== 'enhancer',
|
|
||||||
);
|
|
||||||
for (const worker of workers) {
|
for (const worker of workers) {
|
||||||
expect(worker.runtime).toBe('pi');
|
expect(worker.runtime).toBe('pi');
|
||||||
expect(worker.modelHint).toBe('openai-codex/gpt-5.5:high');
|
expect(worker.modelHint).toBe('openai-codex/gpt-5.5:high');
|
||||||
@@ -2511,43 +2370,6 @@ describe('fleet add/remove — pure helpers', () => {
|
|||||||
expect(updated.agents.map((a) => a.name)).toEqual(['orchestrator2', 'coder0']);
|
expect(updated.agents.map((a) => a.name)).toEqual(['orchestrator2', 'coder0']);
|
||||||
});
|
});
|
||||||
|
|
||||||
it('countEnhancers counts enhancer-class agents (two-agent floor)', () => {
|
|
||||||
const roster: FleetRoster = {
|
|
||||||
...baseRoster,
|
|
||||||
agents: [
|
|
||||||
{ name: 'orchestrator', runtime: 'claude', className: 'orchestrator' },
|
|
||||||
{ name: 'enhancer', runtime: 'claude', className: 'enhancer' },
|
|
||||||
{ name: 'coder0', runtime: 'codex', className: 'worker' },
|
|
||||||
],
|
|
||||||
};
|
|
||||||
expect(countEnhancers(roster)).toBe(1);
|
|
||||||
expect(countEnhancers(baseRoster)).toBe(0);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('removeAgentFromRoster throws when removing the sole enhancer (two-agent floor)', () => {
|
|
||||||
const roster: FleetRoster = {
|
|
||||||
...baseRoster,
|
|
||||||
agents: [
|
|
||||||
{ name: 'orchestrator', runtime: 'claude', className: 'orchestrator' },
|
|
||||||
{ name: 'enhancer', runtime: 'claude', className: 'enhancer' },
|
|
||||||
],
|
|
||||||
};
|
|
||||||
expect(() => removeAgentFromRoster(roster, 'enhancer')).toThrow('sole enhancer');
|
|
||||||
});
|
|
||||||
|
|
||||||
it('removeAgentFromRoster allows removing an enhancer when another remains', () => {
|
|
||||||
const roster: FleetRoster = {
|
|
||||||
...baseRoster,
|
|
||||||
agents: [
|
|
||||||
{ name: 'orchestrator', runtime: 'claude', className: 'orchestrator' },
|
|
||||||
{ name: 'enhancer', runtime: 'claude', className: 'enhancer' },
|
|
||||||
{ name: 'enhancer2', runtime: 'claude', className: 'enhancer' },
|
|
||||||
],
|
|
||||||
};
|
|
||||||
const updated = removeAgentFromRoster(roster, 'enhancer');
|
|
||||||
expect(updated.agents.map((a) => a.name)).toEqual(['orchestrator', 'enhancer2']);
|
|
||||||
});
|
|
||||||
|
|
||||||
it('serializeRosterToYaml produces YAML that round-trips through loadFleetRoster', async () => {
|
it('serializeRosterToYaml produces YAML that round-trips through loadFleetRoster', async () => {
|
||||||
const yaml = serializeRosterToYaml(baseRoster);
|
const yaml = serializeRosterToYaml(baseRoster);
|
||||||
expect(typeof yaml).toBe('string');
|
expect(typeof yaml).toBe('string');
|
||||||
|
|||||||
@@ -227,15 +227,6 @@ export function buildSystemdEnableCommand(unit: string): string[] {
|
|||||||
return ['systemctl', '--user', 'enable', unit];
|
return ['systemctl', '--user', 'enable', unit];
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Returns the systemctl --user disable command for a given unit.
|
|
||||||
* Used by `fleet remove` so a removed agent's enabled unit cannot resurrect on
|
|
||||||
* boot pointing at deleted config (boot-survival symmetry with enable-on-add).
|
|
||||||
*/
|
|
||||||
export function buildSystemdDisableCommand(unit: string): string[] {
|
|
||||||
return ['systemctl', '--user', 'disable', unit];
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the loginctl enable-linger command for a given user.
|
* Returns the loginctl enable-linger command for a given user.
|
||||||
* Linger allows user systemd services to survive logout.
|
* Linger allows user systemd services to survive logout.
|
||||||
@@ -881,33 +872,20 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
|||||||
await mkdir(dirname(destination), { recursive: true });
|
await mkdir(dirname(destination), { recursive: true });
|
||||||
await writeFile(destination, content);
|
await writeFile(destination, content);
|
||||||
|
|
||||||
// Guarantee the two-agent floor: exactly one orchestrator AND at least
|
// Validate: exactly one orchestrator required (R5) — friendly summary on success.
|
||||||
// one enhancer for every profile except the sanctioned no-orchestrator
|
|
||||||
// `minimal` preset. A mismatch means a corrupted/edited preset — fail hard
|
|
||||||
// rather than write a malformed fleet.
|
|
||||||
const written = await loadFleetRoster(destination);
|
const written = await loadFleetRoster(destination);
|
||||||
const orchCount = countOrchestrators(written);
|
const orchCount = countOrchestrators(written);
|
||||||
const enhancerCount = countEnhancers(written);
|
if (orchCount !== 1) {
|
||||||
if (profile === 'minimal') {
|
process.stderr.write(
|
||||||
|
`Warning: fleet roster at ${destination} has ${orchCount} orchestrator agent(s) (expected exactly 1).\n`,
|
||||||
|
);
|
||||||
console.log(
|
console.log(
|
||||||
`Initialized ${profile} fleet: ${written.agents.length} agent(s) (no orchestrator). Next: mosaic fleet install`,
|
`Initialized ${profile} fleet: ${written.agents.length} agent(s). Next: mosaic fleet install`,
|
||||||
);
|
|
||||||
} else if (orchCount !== 1) {
|
|
||||||
throw new Error(
|
|
||||||
`Fleet init failed: the "${profile}" roster has ${orchCount} orchestrator agent(s), ` +
|
|
||||||
`expected exactly 1 (R5). The preset may be corrupted — re-install the framework.`,
|
|
||||||
);
|
|
||||||
} else if (enhancerCount < 1) {
|
|
||||||
throw new Error(
|
|
||||||
`Fleet init failed: the "${profile}" roster has no enhancer agent. Every fleet keeps an ` +
|
|
||||||
`orchestrator + enhancer minimum (two-agent floor). The preset may be corrupted — ` +
|
|
||||||
`re-install the framework.`,
|
|
||||||
);
|
);
|
||||||
} else {
|
} else {
|
||||||
const workerCount = written.agents.length - 1 - enhancerCount;
|
const workerCount = written.agents.length - 1;
|
||||||
console.log(
|
console.log(
|
||||||
`Initialized ${profile} fleet: 1 orchestrator + ${enhancerCount} enhancer(s) + ` +
|
`Initialized ${profile} fleet: 1 orchestrator + ${workerCount} agent(s). Next: mosaic fleet install`,
|
||||||
`${workerCount} worker(s). Next: mosaic fleet install`,
|
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
@@ -1240,24 +1218,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
|||||||
|
|
||||||
console.log(`Added ${name} (${opts.runtime}/${opts.class}) to the fleet.`);
|
console.log(`Added ${name} (${opts.runtime}/${opts.class}) to the fleet.`);
|
||||||
|
|
||||||
// Enable the unit for boot-survival (non-fatal) — symmetry with
|
|
||||||
// disable-on-remove. Independent of --start so a queued agent still
|
|
||||||
// survives a reboot once its unit exists.
|
|
||||||
try {
|
|
||||||
const enableResult = await runner(
|
|
||||||
...splitCommand(buildSystemdEnableCommand(`mosaic-agent@${name}.service`)),
|
|
||||||
);
|
|
||||||
if (enableResult.exitCode !== 0) {
|
|
||||||
process.stderr.write(
|
|
||||||
`Warning: could not enable mosaic-agent@${name}.service: ${enableResult.stderr || enableResult.stdout || 'non-zero exit'}\n`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(
|
|
||||||
`Warning: enable command failed for ${name}: ${err instanceof Error ? err.message : String(err)}\n`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (opts.start !== false) {
|
if (opts.start !== false) {
|
||||||
await runChecked(runner, buildFleetServiceCommand('start', name));
|
await runChecked(runner, buildFleetServiceCommand('start', name));
|
||||||
console.log(`Started mosaic-agent@${name}.service.`);
|
console.log(`Started mosaic-agent@${name}.service.`);
|
||||||
@@ -1294,26 +1254,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
|
|||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
// Disable the unit (non-fatal) so an enabled instance cannot resurrect on
|
|
||||||
// boot pointing at the now-deleted config — boot-survival symmetry with
|
|
||||||
// enable-on-add. Skipped only when --keep-files keeps the config in place.
|
|
||||||
if (!opts.keepFiles) {
|
|
||||||
try {
|
|
||||||
const disableResult = await runner(
|
|
||||||
...splitCommand(buildSystemdDisableCommand(`mosaic-agent@${name}.service`)),
|
|
||||||
);
|
|
||||||
if (disableResult.exitCode !== 0) {
|
|
||||||
process.stderr.write(
|
|
||||||
`Warning: could not disable mosaic-agent@${name}.service: ${disableResult.stderr || disableResult.stdout || 'non-zero exit'}\n`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
} catch (err) {
|
|
||||||
process.stderr.write(
|
|
||||||
`Warning: disable command failed for ${name}: ${err instanceof Error ? err.message : String(err)}\n`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// Write updated roster
|
// Write updated roster
|
||||||
await writeFile(rosterPath, serializeRosterToYaml(updatedRoster));
|
await writeFile(rosterPath, serializeRosterToYaml(updatedRoster));
|
||||||
|
|
||||||
@@ -1954,15 +1894,6 @@ export function countOrchestrators(roster: FleetRoster): number {
|
|||||||
return roster.agents.filter((a) => a.className === 'orchestrator').length;
|
return roster.agents.filter((a) => a.className === 'orchestrator').length;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Count enhancer agents in a parsed roster. The two-agent floor (north-star)
|
|
||||||
* requires every non-minimal fleet to carry at least one enhancer alongside the
|
|
||||||
* sole orchestrator.
|
|
||||||
*/
|
|
||||||
export function countEnhancers(roster: FleetRoster): number {
|
|
||||||
return roster.agents.filter((a) => a.className === 'enhancer').length;
|
|
||||||
}
|
|
||||||
|
|
||||||
/** Valid runtime identifiers for fleet agents. */
|
/** Valid runtime identifiers for fleet agents. */
|
||||||
export const VALID_FLEET_RUNTIMES: readonly string[] = [
|
export const VALID_FLEET_RUNTIMES: readonly string[] = [
|
||||||
'pi',
|
'pi',
|
||||||
@@ -2005,15 +1936,6 @@ export function removeAgentFromRoster(roster: FleetRoster, name: string): FleetR
|
|||||||
`Cannot remove agent "${name}": it is the sole orchestrator. Add another orchestrator first (R5).`,
|
`Cannot remove agent "${name}": it is the sole orchestrator. Add another orchestrator first (R5).`,
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
// Two-agent floor: never drop the last enhancer (the continuous-improvement
|
|
||||||
// loop). Symmetric with the sole-orchestrator guard.
|
|
||||||
const remainingEnhancerCount = remaining.filter((a) => a.className === 'enhancer').length;
|
|
||||||
if (remainingEnhancerCount === 0 && agent.className === 'enhancer') {
|
|
||||||
throw new Error(
|
|
||||||
`Cannot remove agent "${name}": it is the sole enhancer. Every fleet keeps at least one ` +
|
|
||||||
`enhancer (two-agent floor). Add another enhancer first.`,
|
|
||||||
);
|
|
||||||
}
|
|
||||||
return {
|
return {
|
||||||
...roster,
|
...roster,
|
||||||
agents: remaining,
|
agents: remaining,
|
||||||
|
|||||||
184
packages/mosaic/src/fleet/connectors/matrix.spec.ts
Normal file
184
packages/mosaic/src/fleet/connectors/matrix.spec.ts
Normal file
@@ -0,0 +1,184 @@
|
|||||||
|
import { describe, it, expect, beforeEach } from 'vitest';
|
||||||
|
import {
|
||||||
|
MatrixConnector,
|
||||||
|
buildMessageBody,
|
||||||
|
parseSyncResponse,
|
||||||
|
registerMatrixConnector,
|
||||||
|
type FetchLike,
|
||||||
|
} from './matrix.js';
|
||||||
|
import { createConnector, _resetConnectorRegistry } from './registry.js';
|
||||||
|
import type { MatrixConnectorConfig } from './types.js';
|
||||||
|
|
||||||
|
const CONFIG: MatrixConnectorConfig = {
|
||||||
|
homeserverUrl: 'https://matrix.internal/',
|
||||||
|
userId: '@mos:internal',
|
||||||
|
roomId: '!room:internal',
|
||||||
|
};
|
||||||
|
|
||||||
|
/** A fetch mock that returns queued responses and records calls. */
|
||||||
|
function mockFetch(responses: Array<{ ok?: boolean; status?: number; body?: unknown }>): {
|
||||||
|
fetchImpl: FetchLike;
|
||||||
|
calls: Array<{ url: string; method?: string; body?: string }>;
|
||||||
|
} {
|
||||||
|
const calls: Array<{ url: string; method?: string; body?: string }> = [];
|
||||||
|
let i = 0;
|
||||||
|
const fetchImpl: FetchLike = async (url, init) => {
|
||||||
|
calls.push({ url, method: init?.method, body: init?.body });
|
||||||
|
const r = responses[Math.min(i, responses.length - 1)] ?? {};
|
||||||
|
i += 1;
|
||||||
|
return {
|
||||||
|
ok: r.ok ?? true,
|
||||||
|
status: r.status ?? 200,
|
||||||
|
json: async () => r.body ?? {},
|
||||||
|
text: async () => JSON.stringify(r.body ?? {}),
|
||||||
|
};
|
||||||
|
};
|
||||||
|
return { fetchImpl, calls };
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('buildMessageBody', () => {
|
||||||
|
it('builds an m.text event', () => {
|
||||||
|
expect(buildMessageBody({ text: 'hi' })).toEqual({ msgtype: 'm.text', body: 'hi' });
|
||||||
|
});
|
||||||
|
it('adds an m.thread relation when threadId is set', () => {
|
||||||
|
expect(buildMessageBody({ text: 'hi', threadId: '$evt' })).toEqual({
|
||||||
|
msgtype: 'm.text',
|
||||||
|
body: 'hi',
|
||||||
|
'm.relates_to': { rel_type: 'm.thread', event_id: '$evt' },
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('parseSyncResponse', () => {
|
||||||
|
it('extracts operator messages and skips the orchestrator’s own echoes', () => {
|
||||||
|
const data = {
|
||||||
|
next_batch: 's2',
|
||||||
|
rooms: {
|
||||||
|
join: {
|
||||||
|
'!room:internal': {
|
||||||
|
timeline: {
|
||||||
|
events: [
|
||||||
|
{
|
||||||
|
type: 'm.room.message',
|
||||||
|
sender: '@jason:internal',
|
||||||
|
origin_server_ts: 1_700_000_000_000,
|
||||||
|
content: { body: 'status?' },
|
||||||
|
},
|
||||||
|
{
|
||||||
|
type: 'm.room.message',
|
||||||
|
sender: '@mos:internal', // self — skipped
|
||||||
|
origin_server_ts: 1_700_000_001_000,
|
||||||
|
content: { body: 'working on it' },
|
||||||
|
},
|
||||||
|
{ type: 'm.reaction', sender: '@jason:internal', content: {} }, // non-message
|
||||||
|
],
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
const msgs = parseSyncResponse(data, '!room:internal', '@mos:internal');
|
||||||
|
expect(msgs).toHaveLength(1);
|
||||||
|
expect(msgs[0]).toMatchObject({ text: 'status?', sender: '@jason:internal' });
|
||||||
|
expect(msgs[0]!.ts).toBe(new Date(1_700_000_000_000).toISOString());
|
||||||
|
});
|
||||||
|
|
||||||
|
it('carries threadId through thread-relments', () => {
|
||||||
|
const data = {
|
||||||
|
rooms: {
|
||||||
|
join: {
|
||||||
|
'!room:internal': {
|
||||||
|
timeline: {
|
||||||
|
events: [
|
||||||
|
{
|
||||||
|
type: 'm.room.message',
|
||||||
|
sender: '@jason:internal',
|
||||||
|
origin_server_ts: 1,
|
||||||
|
content: {
|
||||||
|
body: 'in thread',
|
||||||
|
'm.relates_to': { rel_type: 'm.thread', event_id: '$root' },
|
||||||
|
},
|
||||||
|
},
|
||||||
|
],
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
expect(parseSyncResponse(data, '!room:internal', '@mos:internal')[0]!.threadId).toBe('$root');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('returns [] for an empty/foreign sync', () => {
|
||||||
|
expect(parseSyncResponse({}, '!room:internal', '@mos:internal')).toEqual([]);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('MatrixConnector', () => {
|
||||||
|
it('throws without an access token', () => {
|
||||||
|
expect(() => new MatrixConnector(CONFIG, { accessToken: '' })).toThrow(/access token/i);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('send PUTs an m.text event and returns the event id', async () => {
|
||||||
|
const { fetchImpl, calls } = mockFetch([{ body: { event_id: '$abc' } }]);
|
||||||
|
const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
|
||||||
|
const res = await c.send({ text: 'pong' }, 1234);
|
||||||
|
expect(res).toEqual({ delivered: true, messageId: '$abc' });
|
||||||
|
expect(calls[0]!.method).toBe('PUT');
|
||||||
|
expect(calls[0]!.url).toContain(
|
||||||
|
'/_matrix/client/v3/rooms/!room%3Ainternal/send/m.room.message/mosaic-1234-1',
|
||||||
|
);
|
||||||
|
expect(JSON.parse(calls[0]!.body!)).toEqual({ msgtype: 'm.text', body: 'pong' });
|
||||||
|
});
|
||||||
|
|
||||||
|
it('send reports not-delivered on a non-2xx', async () => {
|
||||||
|
const { fetchImpl } = mockFetch([{ ok: false, status: 403 }]);
|
||||||
|
const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
|
||||||
|
const res = await c.send({ text: 'x' });
|
||||||
|
expect(res.delivered).toBe(false);
|
||||||
|
expect(res.error).toContain('403');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('health reports reachable + authenticated when whoami matches', async () => {
|
||||||
|
const { fetchImpl } = mockFetch([
|
||||||
|
{ body: { versions: ['v1.11'] } }, // /versions
|
||||||
|
{ body: { user_id: '@mos:internal' } }, // /whoami
|
||||||
|
]);
|
||||||
|
const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
|
||||||
|
const h = await c.health();
|
||||||
|
expect(h.reachable).toBe(true);
|
||||||
|
expect(h.authenticated).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('health flags auth mismatch', async () => {
|
||||||
|
const { fetchImpl } = mockFetch([
|
||||||
|
{ body: {} },
|
||||||
|
{ body: { user_id: '@someone-else:internal' } },
|
||||||
|
]);
|
||||||
|
const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
|
||||||
|
const h = await c.health();
|
||||||
|
expect(h.reachable).toBe(true);
|
||||||
|
expect(h.authenticated).toBe(false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('health reports unreachable when /versions fails', async () => {
|
||||||
|
const { fetchImpl } = mockFetch([{ ok: false, status: 502 }]);
|
||||||
|
const c = new MatrixConnector(CONFIG, { accessToken: 'tok', fetchImpl });
|
||||||
|
const h = await c.health();
|
||||||
|
expect(h.reachable).toBe(false);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('registerMatrixConnector', () => {
|
||||||
|
beforeEach(() => _resetConnectorRegistry());
|
||||||
|
|
||||||
|
it('registers a matrix factory createConnector can build', () => {
|
||||||
|
registerMatrixConnector({ MATRIX_ACCESS_TOKEN: 'tok' } as NodeJS.ProcessEnv);
|
||||||
|
const c = createConnector({ kind: 'matrix', matrix: CONFIG });
|
||||||
|
expect(c.kind).toBe('matrix');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('the factory rejects config missing the matrix block', () => {
|
||||||
|
registerMatrixConnector({ MATRIX_ACCESS_TOKEN: 'tok' } as NodeJS.ProcessEnv);
|
||||||
|
expect(() => createConnector({ kind: 'matrix' })).toThrow(/missing the .matrix. block/i);
|
||||||
|
});
|
||||||
|
});
|
||||||
246
packages/mosaic/src/fleet/connectors/matrix.ts
Normal file
246
packages/mosaic/src/fleet/connectors/matrix.ts
Normal file
@@ -0,0 +1,246 @@
|
|||||||
|
/**
|
||||||
|
* Matrix connector (F4 Phase 2) — speaks the Matrix client-server API directly
|
||||||
|
* over HTTPS so it is homeserver-agnostic (Conduit default, Synapse alt). No
|
||||||
|
* SDK: a small injectable fetch keeps it dependency-light and unit-testable.
|
||||||
|
*
|
||||||
|
* The access token is supplied by the caller (from the environment —
|
||||||
|
* MATRIX_ACCESS_TOKEN — per the gateway secret pattern), never the roster.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import {
|
||||||
|
type OrchestratorConnector,
|
||||||
|
type OutboundMessage,
|
||||||
|
type InboundMessage,
|
||||||
|
type SendResult,
|
||||||
|
type ConnectorHealth,
|
||||||
|
type MatrixConnectorConfig,
|
||||||
|
type Unsubscribe,
|
||||||
|
} from './types.js';
|
||||||
|
import { registerConnector } from './registry.js';
|
||||||
|
|
||||||
|
/** Minimal fetch surface — avoids a lib.dom dependency and is trivial to mock. */
|
||||||
|
export interface FetchLike {
|
||||||
|
(
|
||||||
|
url: string,
|
||||||
|
init?: { method?: string; headers?: Record<string, string>; body?: string },
|
||||||
|
): Promise<{
|
||||||
|
ok: boolean;
|
||||||
|
status: number;
|
||||||
|
json: () => Promise<unknown>;
|
||||||
|
text: () => Promise<string>;
|
||||||
|
}>;
|
||||||
|
}
|
||||||
|
|
||||||
|
export interface MatrixConnectorOptions {
|
||||||
|
accessToken: string;
|
||||||
|
/** Injectable fetch (defaults to global fetch). */
|
||||||
|
fetchImpl?: FetchLike;
|
||||||
|
/** Long-poll timeout for /sync, ms. */
|
||||||
|
syncTimeoutMs?: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Build the `m.room.message` event content, threading when a threadId is set. */
|
||||||
|
export function buildMessageBody(message: OutboundMessage): Record<string, unknown> {
|
||||||
|
const content: Record<string, unknown> = {
|
||||||
|
msgtype: 'm.text',
|
||||||
|
body: message.text,
|
||||||
|
};
|
||||||
|
if (message.threadId) {
|
||||||
|
content['m.relates_to'] = { rel_type: 'm.thread', event_id: message.threadId };
|
||||||
|
}
|
||||||
|
return content;
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Shape of the bits of a /sync response we consume. */
|
||||||
|
interface SyncResponse {
|
||||||
|
next_batch?: string;
|
||||||
|
rooms?: {
|
||||||
|
join?: Record<
|
||||||
|
string,
|
||||||
|
{
|
||||||
|
timeline?: {
|
||||||
|
events?: Array<{
|
||||||
|
type?: string;
|
||||||
|
sender?: string;
|
||||||
|
origin_server_ts?: number;
|
||||||
|
content?: {
|
||||||
|
body?: string;
|
||||||
|
['m.relates_to']?: { rel_type?: string; event_id?: string };
|
||||||
|
};
|
||||||
|
}>;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
>;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Extract inbound operator messages from a /sync response for one room,
|
||||||
|
* skipping the orchestrator's own echoes. Pure — the testable core of receive.
|
||||||
|
*/
|
||||||
|
export function parseSyncResponse(
|
||||||
|
data: unknown,
|
||||||
|
roomId: string,
|
||||||
|
selfUserId: string,
|
||||||
|
): InboundMessage[] {
|
||||||
|
const sync = data as SyncResponse;
|
||||||
|
const events = sync.rooms?.join?.[roomId]?.timeline?.events ?? [];
|
||||||
|
const out: InboundMessage[] = [];
|
||||||
|
for (const ev of events) {
|
||||||
|
if (ev.type !== 'm.room.message') continue;
|
||||||
|
if (!ev.sender || ev.sender === selfUserId) continue; // skip our own messages
|
||||||
|
const body = ev.content?.body;
|
||||||
|
if (typeof body !== 'string') continue;
|
||||||
|
const rel = ev.content?.['m.relates_to'];
|
||||||
|
out.push({
|
||||||
|
text: body,
|
||||||
|
sender: ev.sender,
|
||||||
|
ts: new Date(ev.origin_server_ts ?? 0).toISOString(),
|
||||||
|
...(rel?.rel_type === 'm.thread' && rel.event_id ? { threadId: rel.event_id } : {}),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
return out;
|
||||||
|
}
|
||||||
|
|
||||||
|
export class MatrixConnector implements OrchestratorConnector {
|
||||||
|
readonly kind = 'matrix' as const;
|
||||||
|
private readonly fetchImpl: FetchLike;
|
||||||
|
private readonly token: string;
|
||||||
|
private readonly syncTimeoutMs: number;
|
||||||
|
private txnCounter = 0;
|
||||||
|
private stopped = false;
|
||||||
|
|
||||||
|
constructor(
|
||||||
|
private readonly config: MatrixConnectorConfig,
|
||||||
|
opts: MatrixConnectorOptions,
|
||||||
|
) {
|
||||||
|
this.token = opts.accessToken;
|
||||||
|
this.fetchImpl = opts.fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
|
||||||
|
this.syncTimeoutMs = opts.syncTimeoutMs ?? 30_000;
|
||||||
|
if (!this.token) {
|
||||||
|
throw new Error('MatrixConnector requires an access token (set MATRIX_ACCESS_TOKEN).');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private url(path: string): string {
|
||||||
|
return `${this.config.homeserverUrl.replace(/\/$/, '')}${path}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
private authHeaders(): Record<string, string> {
|
||||||
|
return { Authorization: `Bearer ${this.token}`, 'Content-Type': 'application/json' };
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Monotonic, unique-per-instance transaction id for idempotent sends. */
|
||||||
|
private nextTxnId(nowMs: number): string {
|
||||||
|
this.txnCounter += 1;
|
||||||
|
return `mosaic-${nowMs}-${this.txnCounter}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
async send(message: OutboundMessage, nowMs = Date.now()): Promise<SendResult> {
|
||||||
|
const txnId = this.nextTxnId(nowMs);
|
||||||
|
const path = `/_matrix/client/v3/rooms/${encodeURIComponent(
|
||||||
|
this.config.roomId,
|
||||||
|
)}/send/m.room.message/${encodeURIComponent(txnId)}`;
|
||||||
|
try {
|
||||||
|
const res = await this.fetchImpl(this.url(path), {
|
||||||
|
method: 'PUT',
|
||||||
|
headers: this.authHeaders(),
|
||||||
|
body: JSON.stringify(buildMessageBody(message)),
|
||||||
|
});
|
||||||
|
if (!res.ok) {
|
||||||
|
return { delivered: false, error: `Matrix send failed: HTTP ${res.status}` };
|
||||||
|
}
|
||||||
|
const json = (await res.json()) as { event_id?: string };
|
||||||
|
return { delivered: true, ...(json.event_id ? { messageId: json.event_id } : {}) };
|
||||||
|
} catch (err) {
|
||||||
|
return { delivered: false, error: err instanceof Error ? err.message : String(err) };
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
subscribe(handler: (message: InboundMessage) => void): Unsubscribe {
|
||||||
|
this.stopped = false;
|
||||||
|
let since: string | undefined;
|
||||||
|
const loop = async (): Promise<void> => {
|
||||||
|
while (!this.stopped) {
|
||||||
|
try {
|
||||||
|
const q = new URLSearchParams({ timeout: String(this.syncTimeoutMs) });
|
||||||
|
if (since) q.set('since', since);
|
||||||
|
const res = await this.fetchImpl(this.url(`/_matrix/client/v3/sync?${q.toString()}`), {
|
||||||
|
method: 'GET',
|
||||||
|
headers: this.authHeaders(),
|
||||||
|
});
|
||||||
|
if (!res.ok) {
|
||||||
|
await this.backoff();
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
const data = await res.json();
|
||||||
|
since = (data as SyncResponse).next_batch ?? since;
|
||||||
|
for (const msg of parseSyncResponse(data, this.config.roomId, this.config.userId)) {
|
||||||
|
handler(msg);
|
||||||
|
}
|
||||||
|
} catch {
|
||||||
|
await this.backoff();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
void loop();
|
||||||
|
return () => {
|
||||||
|
this.stopped = true;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
private backoff(): Promise<void> {
|
||||||
|
return new Promise((resolve) => setTimeout(resolve, 2_000));
|
||||||
|
}
|
||||||
|
|
||||||
|
async health(): Promise<ConnectorHealth> {
|
||||||
|
try {
|
||||||
|
const versions = await this.fetchImpl(this.url('/_matrix/client/versions'), {
|
||||||
|
method: 'GET',
|
||||||
|
});
|
||||||
|
if (!versions.ok) {
|
||||||
|
return {
|
||||||
|
reachable: false,
|
||||||
|
authenticated: false,
|
||||||
|
detail: `versions HTTP ${versions.status}`,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
const who = await this.fetchImpl(this.url('/_matrix/client/v3/account/whoami'), {
|
||||||
|
method: 'GET',
|
||||||
|
headers: this.authHeaders(),
|
||||||
|
});
|
||||||
|
if (!who.ok) {
|
||||||
|
return { reachable: true, authenticated: false, detail: `whoami HTTP ${who.status}` };
|
||||||
|
}
|
||||||
|
const json = (await who.json()) as { user_id?: string };
|
||||||
|
const authenticated = json.user_id === this.config.userId;
|
||||||
|
return {
|
||||||
|
reachable: true,
|
||||||
|
authenticated,
|
||||||
|
lastSeen: new Date().toISOString(),
|
||||||
|
...(authenticated
|
||||||
|
? {}
|
||||||
|
: { detail: `whoami user ${json.user_id} != ${this.config.userId}` }),
|
||||||
|
};
|
||||||
|
} catch (err) {
|
||||||
|
return {
|
||||||
|
reachable: false,
|
||||||
|
authenticated: false,
|
||||||
|
detail: err instanceof Error ? err.message : String(err),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Register the Matrix connector factory. The token is read from the environment
|
||||||
|
* (MATRIX_ACCESS_TOKEN) at build time, never the roster.
|
||||||
|
*/
|
||||||
|
export function registerMatrixConnector(env: NodeJS.ProcessEnv = process.env): void {
|
||||||
|
registerConnector('matrix', (config) => {
|
||||||
|
if (!config.matrix) {
|
||||||
|
throw new Error('Matrix connector config missing the `matrix` block (homeserver/user/room).');
|
||||||
|
}
|
||||||
|
return new MatrixConnector(config.matrix, { accessToken: env['MATRIX_ACCESS_TOKEN'] ?? '' });
|
||||||
|
});
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user