113 lines
3.0 KiB
Markdown
113 lines
3.0 KiB
Markdown
# Mosaic Matrix Orchestrator Rail
|
|
|
|
Runtime-agnostic orchestration rail for delegating work to worker agents and enforcing
|
|
mechanical quality gates.
|
|
|
|
## Purpose
|
|
|
|
- Decouple orchestration from any single agent runtime feature set
|
|
- Persist state in repo-local `.mosaic/orchestrator/` files
|
|
- Emit structured events for Matrix transport and audit trails
|
|
- Enforce rails before marking tasks complete
|
|
|
|
## Components
|
|
|
|
- `protocol/` - JSON schemas for task/event payloads
|
|
- `dispatcher/` - MACP dispatch helpers for worktrees, command generation, results, and cleanup
|
|
- `controller/mosaic_orchestrator.py` - deterministic controller loop
|
|
- `adapters/` - runtime adapter guidance
|
|
|
|
## Repo Contract
|
|
|
|
The controller expects this layout in each bootstrapped repo:
|
|
|
|
```text
|
|
.mosaic/orchestrator/
|
|
config.json
|
|
tasks.json
|
|
state.json
|
|
events.ndjson
|
|
logs/
|
|
results/
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
From a bootstrapped repo:
|
|
|
|
```bash
|
|
~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
|
|
~/.config/mosaic/bin/mosaic-orchestrator-run --once
|
|
~/.config/mosaic/bin/mosaic-orchestrator-drain
|
|
```
|
|
|
|
Continuous loop:
|
|
|
|
```bash
|
|
~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
|
|
```
|
|
|
|
Sync from `docs/TASKS.md` to queue:
|
|
|
|
```bash
|
|
~/.config/mosaic/bin/mosaic-orchestrator-sync-tasks --apply
|
|
```
|
|
|
|
Set worker command when needed:
|
|
|
|
```bash
|
|
export MOSAIC_WORKER_EXEC="codex -p"
|
|
# or
|
|
export MOSAIC_WORKER_EXEC="opencode -p"
|
|
```
|
|
|
|
Publish new orchestrator events to Matrix:
|
|
|
|
```bash
|
|
~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
|
|
```
|
|
|
|
Consume Matrix task messages into `tasks.json`:
|
|
|
|
```bash
|
|
~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
|
|
```
|
|
|
|
## Matrix Note
|
|
|
|
This rail writes canonical events to `.mosaic/orchestrator/events.ndjson`.
|
|
The Matrix transport bridge publishes those events into the configured control room
|
|
and can consume task commands from that room.
|
|
|
|
Task injection message format (room text):
|
|
|
|
```text
|
|
!mosaic-task {"id":"TASK-123","title":"Fix bug","command":"echo run","quality_gates":["pnpm lint"]}
|
|
```
|
|
|
|
## MACP Notes
|
|
|
|
MACP-aware tasks add dispatch metadata on top of the existing queue model:
|
|
|
|
- `dispatch`: `exec`, `yolo`, or `acp`
|
|
- `type`: task category used for orchestration intent
|
|
- `worktree` / `branch`: task-specific git execution context
|
|
- `brief_path`: markdown brief consumed by runtime-backed dispatchers
|
|
- `result_path`: structured result JSON written under `.mosaic/orchestrator/`
|
|
|
|
Controller behavior remains backward compatible:
|
|
|
|
- Tasks without `dispatch` continue through the legacy shell execution path.
|
|
- Tasks with `dispatch` use the MACP dispatcher and can emit `task.gated` and `task.escalated`.
|
|
- `acp` dispatch is fail-safe in Phase 1: it escalates with `ACP dispatch requires OpenClaw integration (Phase 2)` instead of reporting success.
|
|
- `yolo` dispatch stages the brief in a temporary file so the brief body does not appear in process arguments.
|
|
|
|
Manual queue operations are exposed through:
|
|
|
|
```bash
|
|
mosaic macp submit ...
|
|
mosaic macp status
|
|
mosaic macp drain
|
|
mosaic macp history --task-id TASK-001
|
|
```
|