crewbus 11.3.1 → 11.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +11 -0
- package/README.md +2 -2
- package/bin/lib/web.js +5 -4
- package/docs/APPROVALS.md +20 -61
- package/docs/ARCHITECTURE.md +113 -0
- package/docs/AUDIT_EXPORT.md +9 -104
- package/docs/CERT_READINESS.md +13 -120
- package/docs/COMPATIBILITY.md +65 -0
- package/docs/CONSOLIDATOR.md +8 -43
- package/docs/CONTROL_PLANE_SPEC.md +16 -340
- package/docs/CREWS.md +9 -54
- package/docs/DELIVERY.md +2 -0
- package/docs/EXPERIMENTS.md +7 -52
- package/docs/GROUPS.md +13 -109
- package/docs/HA.md +15 -151
- package/docs/IDENTITY.md +10 -162
- package/docs/ISOLATION.md +22 -39
- package/docs/LIMITS.md +12 -21
- package/docs/LONG_RUNS.md +10 -56
- package/docs/OIDC_TLS.md +8 -69
- package/docs/ORCHESTRATOR.md +8 -82
- package/docs/PAIRING.md +2 -0
- package/docs/QUICKSTART.md +10 -75
- package/docs/RBAC.md +10 -80
- package/docs/SECURITY.md +111 -0
- package/docs/SHARED_RESPONSIBILITY.md +8 -32
- package/docs/SPLIT.md +13 -82
- package/docs/STORAGE.md +9 -63
- package/docs/TENANCY.md +8 -74
- package/docs/THREAT_MODEL.md +16 -68
- package/docs/TROUBLESHOOTING.md +16 -27
- package/docs/VERIFIER.md +8 -50
- package/docs/VERSION_SKEW.md +13 -57
- package/docs/WHEN_NOT.md +11 -35
- package/documentation.html +198 -4
- package/index.html +4 -4
- package/package.json +1 -1
- package/packages/client-runtime/auth.js +7 -3
- package/packages/client-runtime/routes.js +3 -0
package/docs/CONSOLIDATOR.md
CHANGED
|
@@ -1,47 +1,12 @@
|
|
|
1
|
-
# Consolidator
|
|
1
|
+
# Consolidator Pattern
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
seeds the main crews' briefs.
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#workflow`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#workflow)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
---
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
# group A works a batch; its replies land threaded on the brief
|
|
12
|
-
batch="<batch-id from the send echo>"
|
|
9
|
+
## Consolidator Pattern
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
# the orchestrator briefs group B with A's findings attached
|
|
18
|
-
crewbus send --from orchestrator --to-group team-b --subject "variant: build on team-a" --body "<paste summary>"
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
What the script does (all via the CLI, token-checked like any agent):
|
|
22
|
-
|
|
23
|
-
1. `gather --batch <batch> --json` — the reduce step: brief(s) + every
|
|
24
|
-
reply, oldest first.
|
|
25
|
-
2. Builds an extractive summary: brief count, reply count, first line of
|
|
26
|
-
each reply, artifact references (`send --artifact`), per-sender counts.
|
|
27
|
-
3. `send --from gateway --to orchestrator --reply <first-brief> --subject "RESULT: <batch>"`
|
|
28
|
-
— the handoff, threaded so `thread --id` shows the full chain.
|
|
29
|
-
4. `channel post grp-team-a` — mirrors the summary to the group-scoped
|
|
30
|
-
channel, so late joiners and sibling groups can `channel tail` it.
|
|
31
|
-
`channel post` creates `grp-<group>` on first use; `group channel
|
|
32
|
-
<name>` shows the mapping and post count.
|
|
33
|
-
|
|
34
|
-
## Conventions
|
|
35
|
-
|
|
36
|
-
- **One consolidator per batch.** Name it `gateway` or `<group>-gateway`
|
|
37
|
-
so `gather` transcripts stay readable.
|
|
38
|
-
- **Summaries are untrusted peer data** like any DM: they render with the
|
|
39
|
-
`[untrusted peer:...]` envelope. Verify before building on them —
|
|
40
|
-
ideally `ack --verify "<checker>"` on the underlying replies first and
|
|
41
|
-
only consolidate verified results (`result record`).
|
|
42
|
-
- **Keep the summary short.** The script caps each reply at its first line
|
|
43
|
-
(200 chars); for long transcripts prefer `channel summarize <chan>`
|
|
44
|
-
or `inbox --digest --max-chars <n>` at the receiving end instead.
|
|
45
|
-
- For racing groups, run the consolidator on the **winner only**
|
|
46
|
-
(`race start` finds the first verified result; `race close --kill`
|
|
47
|
-
stops the losers), then feed the winner's summary to the next stage.
|
|
11
|
+
- An observer pattern where a dedicated worker synthesizes and reconciles work from multiple parallel task workers.
|
|
12
|
+
- Gathers thread deliverables using `crewbus gather <brief-id>`.
|
|
@@ -1,340 +1,16 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
> Pick board → pick harness (detected, version-checked) → set agent count +
|
|
18
|
-
> names → write task brief → set permission/isolation → preview dry-run →
|
|
19
|
-
> launch locally or to the fleet → watch triage/approvals/results →
|
|
20
|
-
> kill/respawn/ack from the same surface.
|
|
21
|
-
|
|
22
|
-
No harness terminal required. Harnesses become executors behind the bus;
|
|
23
|
-
the board remains shared memory. The DM is still the task — this plane
|
|
24
|
-
adds no workflow engine, no cross-board queries, no hosted proxy tier.
|
|
25
|
-
|
|
26
|
-
## 1. Current state (CrewBus v7.0.0 baseline → v10.0.0 live release)
|
|
27
|
-
|
|
28
|
-
### 1.1 Board layout (`bin/lib/store.js`)
|
|
29
|
-
|
|
30
|
-
`BOARD_VERSION = 2` (schema version; unrelated to package version).
|
|
31
|
-
Resolution: `--board` flag > `--global` (`~/.crewbus/boards/default`) >
|
|
32
|
-
`CREWBUS_DIR` env > walk-up `findBoardUpward()` > `./.crewbus`
|
|
33
|
-
(`init` always plants where you stand).
|
|
34
|
-
|
|
35
|
-
```
|
|
36
|
-
.crewbus/
|
|
37
|
-
board.json {name, version:2, createdAt, acl?, quotas?, tenant?, caps?}
|
|
38
|
-
agents/<name>.json {name, firstSeen, lastSeen, sessionId?, lastDir?,
|
|
39
|
-
spawnedPid?, spawnedAt?, spawnedBy?, briefId?,
|
|
40
|
-
spawnedWorktree?, spawnedBranch?, spawnedLifetime?,
|
|
41
|
-
tokenHash, salt, expiresAt?, rotatedAt?, service?,
|
|
42
|
-
offboarded?, role?}
|
|
43
|
-
dm/<to>/<id>.json {id, from, to, body, at, subject?, replyTo?, batch?,
|
|
44
|
-
checkpoint?, priority?, senderType?, sig?, fwd?}
|
|
45
|
-
broadcast/<batch>.json ONE file for fan-outs over 20 + @all
|
|
46
|
-
delivered/<agent>/<id>.json push markers (exclusive-create claims)
|
|
47
|
-
acked/<agent>/<id>.json accept markers
|
|
48
|
-
cursors/<agent>.json fast-forward pointers
|
|
49
|
-
groups/<name>.json named recipient sets (+ restricted?, telemetry, result)
|
|
50
|
-
channels/<name>.log.jsonl append-only shared logs
|
|
51
|
-
locks/ results/ tombstones/ revoked/ holds/
|
|
52
|
-
logs/<worker>-<stamp>.log + .prompt.md + <agent>.token (0600)
|
|
53
|
-
worker-sessions/<name>.json harness session binding (machine-local, NEVER synced)
|
|
54
|
-
sync-state/ relay.json index/broadcasts.json (derived, never synced)
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Constants: `MAX_BODY_CHARS=8000`, `MAX_RECIPIENTS=10000`, `MAX_SPAWN=20`,
|
|
58
|
-
`BROADCAST_AFTER=20`, send rate 30/min/agent, thread `fwd` depth max 5,
|
|
59
|
-
10s dedupe window (`bin/lib/store.js`, `docs/LIMITS.md`).
|
|
60
|
-
### 1.2 CLI verbs (`bin/crewbus.js` dispatcher + `bin/lib/*`)
|
|
61
|
-
|
|
62
|
-
| Verb | Key flags | Lib owner |
|
|
63
|
-
|---|---|---|
|
|
64
|
-
| `init [--harness opencode,claude,codex,antigravity,grok,cursor]` | `--global --board --force --no-opencode --portable` | monolith `cmdInit` |
|
|
65
|
-
| `register --from <you>` | `--session --token --role --expires-in --service --offboard --for` | `identity.js` |
|
|
66
|
-
| `send --from --to --body` | `--subject --reply --priority --checkpoint --sender-type --to-group --no-rate-limit --yes` | `mail.js` |
|
|
67
|
-
| `inbox --from` | `--after --unacked --digest --grep --priority --json` | `mail.js` |
|
|
68
|
-
| `listen --from` | `--timeout --watch` | `mail.js` |
|
|
69
|
-
| `ack --id\|--all` | `--verify "<cmd>"` machine-verification hook | `mail.js` |
|
|
70
|
-
| `spawn --from (--to\|--count --prefix) --body` | `--harness --cmd --cwd --worktree --branch --oneshot\|--persistent --model --max-turns --allow-tools --max-spawn --budget-tokens --budget-minutes --timeout --isolate --workdir-root --sender-type --auto --dry-run` | `spawn.js` |
|
|
71
|
-
| `spawn-status --all\|--to` / `spawn-kill --all\|--to` / `respawn --to` / `stop --all` / `pool --count --pool-size` | `--json --force` | `spawn.js` + monolith |
|
|
72
|
-
| `serve --port` | `--secret --allow-remote-spawn --allow-cmd --workdir-root --weight --standby --relay-interval --promote-on-miss --fence --tls-* --mtls-* --oidc-* --audit-forward` | `relay.js` |
|
|
73
|
-
| `sync --with <url>` | `--once --interval --dry-run --secret --device --pair-token --bearer --mtls-cert --mtls-key --insecure` | `sync.js` |
|
|
74
|
-
| `relay pair|devices|revoke-device|status|promote` | `--from --label --ttl` | `relay.js` |
|
|
75
|
-
| `crew survey|dispatch` | `--relays --weights --count --prefix` (mirrors spawn flags) | `sync.js` |
|
|
76
|
-
| `doctor` | `--harness --board` (wiring presence, not live behavior) | monolith |
|
|
77
|
-
| `web --port` | `--host` (localhost default) | `web.js` |
|
|
78
|
-
| `token rotate|status|revoke`, `acl set|show`, `group create|add|remove|show|list|delete|restrict`, `channel create|post|tail`, `result record|show|list`, `race start|close`, `lock acquire|release`, `prune --older-than`, `board export|import`, `snapshot schedule|run`, `quota set|show`, `storage`, `log [--audit] [--verify]` | per-command | `identity/groups/channels/export.js` |
|
|
79
|
-
|
|
80
|
-
Hook helper: `bin/crewbus-hook.js`
|
|
81
|
-
(`session-start|poll --style|wait|monitor|compact`).
|
|
82
|
-
MCP server: `bin/crewbus-mcp.js` (`dm_send/dm_inbox/dm_ack/dm_gather/
|
|
83
|
-
dm_register/dm_agents/dm_channel_post/dm_channel_tail/...`).
|
|
84
|
-
Opencode embeds: `opencode/tools/dm-send.js` + `opencode/plugins/dm-watch.js`
|
|
85
|
-
(`node sync-embeds.mjs --check` after edits).
|
|
86
|
-
|
|
87
|
-
### 1.3 Web dashboard today (`bin/lib/web.js`)
|
|
88
|
-
|
|
89
|
-
Single `renderBoardHtml()` + snapshots
|
|
90
|
-
(`boardSnapshot/fleetSnapshot/channelsSnapshot/resultsSnapshot/auditSnapshot`).
|
|
91
|
-
Reads open; writes token-checked JSON-only:
|
|
92
|
-
|
|
93
|
-
```
|
|
94
|
-
GET /api/board /api/fleet /api/channels /api/results /api/audit
|
|
95
|
-
GET /api/inbox?agent=<name>&unacked=1&limit=50
|
|
96
|
-
POST /api/kill {from, token, to[]|all:true}
|
|
97
|
-
POST /api/ack {from, token, id|all:true}
|
|
98
|
-
POST /api/approve {from, token, id, decision}
|
|
99
|
-
GET /api/events (SSE)
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
5s poll. Kill/ack need the same CLI token; tokens stay in the tab.
|
|
103
|
-
Missing: launch wizard, harness picker, pairing UI, route management.
|
|
104
|
-
|
|
105
|
-
### 1.4 Identity + RBAC (`bin/lib/identity.js`, `docs/RBAC.md`, `docs/IDENTITY.md`)
|
|
106
|
-
|
|
107
|
-
First claim wins (`writeExclusiveJson`); salted `tokenHash+salt`, never
|
|
108
|
-
plaintext; `expiresAt/rotatedAt/service/offboarded`; `revoked/` union
|
|
109
|
-
(copy-if-missing, never undone). Secrets stripped on sync/push/serve/JSON
|
|
110
|
-
output; local secrets always win merges. Roles `{orchestrator, worker}`
|
|
111
|
-
(the board bootstraps one orchestrator; self-registrations are workers); `checkToken()` THEN
|
|
112
|
-
`authorize()` — never merged, never reordered. Leads kill own crew only;
|
|
113
|
-
auditors read-only; `acl {defaultRole, frozen}` per board; `group restrict`
|
|
114
|
-
for private crews.
|
|
115
|
-
|
|
116
|
-
### 1.5 Sync + relay + HA (`bin/lib/sync.js`, `bin/lib/relay.js`, `docs/HA.md`, `docs/PAIRING.md`)
|
|
117
|
-
|
|
118
|
-
`SYNC_SUBS=[dm,broadcast,delivered,acked,cursors,agents,groups,tombstones,
|
|
119
|
-
channels,revoked,holds]`; `SYNC_UNION` copy-if-missing; `SYNC_LWW` HLC
|
|
120
|
-
`(hlc,v)`; channel line-merge; per-peer cursor + 60s overlap;
|
|
121
|
-
`RELAY_CAPS=[hlc,tombstones,channels,revoked,holds,tls,mtls,oidc,standby,
|
|
122
|
-
audit-forward]`; manifest negotiates, legacy = 4.0 baseline, `SUB_CAP_NOTE`
|
|
123
|
-
wording on degrade. Secrets: `x-crewbus-secret` / `?secret=` constant-time;
|
|
124
|
-
`/api/spawn|kill` opt-in; remote `--cmd` allowlist; `cwd` under
|
|
125
|
-
`--workdir-root`; `relay pair` single-use `abp-…` → device `abd-…`
|
|
126
|
-
(relay-local, never synced/exported, hashed at rest, revocable, audited).
|
|
127
|
-
Standby: one writer, pull loop, `503 + X-Relay-Role: standby` on writes,
|
|
128
|
-
`/healthz` `{role,primary,lagMs,...}`, manual `relay promote` recommended,
|
|
129
|
-
`--promote-on-miss` + `--fence` opt-in. Transport = operator mesh VPN
|
|
130
|
-
(Tailscale recommended, never a dependency). Weighted crews: `crew survey`
|
|
131
|
-
(role/weight/workers/lag) + `crew dispatch` largest-remainder split.
|
|
132
|
-
### 1.6 Seven-harness matrix (`spawn.js`, `docs/COMPATIBILITY.md`)
|
|
133
|
-
|
|
134
|
-
`buildSpawnTarget()` maps harness → `{exe, args, shell, stdinPath?}`.
|
|
135
|
-
`bootWorker()` writes the prompt file, launches detached with
|
|
136
|
-
`CREWBUS_DIR/CREWBUS_AGENT` (secrets scrubbed), records pid + binding,
|
|
137
|
-
lazily fills `worker-sessions/<name>.json` (machine-local, NEVER synced).
|
|
138
|
-
|
|
139
|
-
| Harness | Spawn | Brief | Session capture | Respawn |
|
|
140
|
-
|---|---|---|---|---|
|
|
141
|
-
| opencode | `run --file <brief> --format json` | file | early stream event | `run --session <id>` |
|
|
142
|
-
| claude | `-p --output-format json --session-id <uuid> --allowedTools ...` | stdin | preassigned + log | `-p --resume <id>` + resume-interrupted env |
|
|
143
|
-
| codex | `exec --json -c approval_policy="never" --dangerously-bypass-hook-trust` | stdin + positional | `thread.started.thread_id` | `exec <opts> resume <id> "<catchup>"` |
|
|
144
|
-
| grok | `--prompt-file -s <uuid> --output-format json` | file | preassigned (end-of-run log) | `--prompt-file <catchup> -r <id>` |
|
|
145
|
-
| antigravity | `--print --mode accept-edits` | inline | none | `-p "<catchup>" --conversation <id>` (rare) |
|
|
146
|
-
| cursor | `cursor-agent -p --force --trust` | inline | none | `-p --force --resume <id>` (rare) |
|
|
147
|
-
|
|
148
|
-
`--auto` per harness: opencode auto-approve, claude `--dangerously-skip-permissions`, codex `--dangerously-bypass-approvals-and-sandbox`, grok `--permission-mode bypassPermissions --always-approve`, cursor `--yolo`, agy `--dangerously-skip-permissions`.
|
|
149
|
-
Requires `--i-understand-danger` (or TTY `yes`) + sandbox warning
|
|
150
|
-
(`docs/ISOLATION.md`). cursor/agy resume = honestly unsupported until
|
|
151
|
-
vendors emit stable ids. `doctor` checks wiring presence, not live behavior.
|
|
152
|
-
Windows: native `.exe` binaries launch directly via `resolveHarnessExe` with `shell: false` (exact PID tracking, immediate unbuffered stdio); legacy `.cmd` shims route safely through `resolveShellShot`.
|
|
153
|
-
|
|
154
|
-
### 1.7 Extension points (where the plane hooks in)
|
|
155
|
-
|
|
156
|
-
| Plane feature | Exact hook |
|
|
157
|
-
|---|---|
|
|
158
|
-
| `launch` wizard | wrap `bootWorker()` + `remoteSpawn`; preview via `formatSpawnCmd()`; NEVER a new spawn path |
|
|
159
|
-
| `harnesses detect` | `buildSpawnTarget()` arg knowledge + `doctor` checks + `<binary> --version` probes (tolerant) |
|
|
160
|
-
| Harness picker UI | `GET /api/harnesses` over `packages/contracts/harness.json` + live detect |
|
|
161
|
-
| `pair qr` / mobile pairing | wrap `newPairToken()`; QR encodes `crewbus://pair?...#abp-…` (fragment secret) |
|
|
162
|
-
| Routes / env identity | extend `relay.json` + `/healthz` with `envId + advertisedRoutes + capabilities` |
|
|
163
|
-
| `POST /api/launch` | same validation as wizard → `bootWorker` local or `remoteSpawn` per relay |
|
|
164
|
-
| Web Dashboard | standalone loopback dashboard via `crewbus web [--open]` with /pair route |
|
|
165
|
-
| Mobile client | `GET /api/*` + `POST /api/launch|kill|ack|approve` + `/sync/wait`; no FS access |
|
|
166
|
-
| Scoped device creds | extend `parseDeviceCred` + `requireRelaySecret` → `requireScope(rpc)` |
|
|
167
|
-
## 2. t3Code lessons (reference: `pingdotgg/t3code`)
|
|
168
|
-
|
|
169
|
-
### 2.1 Provider abstraction — normalize at the adapter
|
|
170
|
-
|
|
171
|
-
Orchestration never branches on provider. Driver = integration kind;
|
|
172
|
-
instance = one config + account lifecycle; route work by instance.
|
|
173
|
-
Quirks quarantined per adapter: opencode 1.x (server per thread) vs 2.x
|
|
174
|
-
(server per instance + per-thread MCP entry + deny-others); Claude
|
|
175
|
-
multi-account via `CLAUDE_CONFIG_DIR` instances; Codex `/goal` multi-turn
|
|
176
|
-
+ non-blocking questions; Antigravity profile isolation + ambient cred
|
|
177
|
-
stripping + immutable releases; Grok probes never auth as a side effect;
|
|
178
|
-
capabilities describe what the provider CAN do (no-rollback rejects
|
|
179
|
-
revert BEFORE touching files).
|
|
180
|
-
|
|
181
|
-
### 2.2 Ownership + settings
|
|
182
|
-
|
|
183
|
-
Execution belongs to the environment owning the workspace; clients control
|
|
184
|
-
over RPC; shared client-runtime; RPC contract is the version boundary;
|
|
185
|
-
subscriptions send only viewed state; event log is source of truth.
|
|
186
|
-
Client prefs stay in client; env defaults + project overrides on server;
|
|
187
|
-
`All environments` = bulk edit, not a durable global.
|
|
188
|
-
|
|
189
|
-
### 2.3 UI layout (spec-ui brief, landed)
|
|
190
|
-
|
|
191
|
-
Sidebar: Pinned / Active / Settled + Snoozed + Archived; drag rows to
|
|
192
|
-
change state; 5s Undo toast; `Ctrl+K` palette + message search; drag files
|
|
193
|
-
to attach. New crew keeps project + harness/mode unless dest overrides;
|
|
194
|
-
`No project` scratch; background-send; multi-harness fanout. Composer:
|
|
195
|
-
chips for files/crews, queue-vs-steer, mobile offline queue. Picker in
|
|
196
|
-
heading: remembers harness + options, project overrides, honest fallbacks
|
|
197
|
-
(Grok→Supervised, OpenCode/Antigravity→ask). Permission modes per crew:
|
|
198
|
-
Supervised / Auto-accept edits / Auto / Full access.
|
|
199
|
-
### 2.4 Connection + remote + auth
|
|
200
|
-
|
|
201
|
-
One retry owner (jittered backoff, 5min cap); foreground probes before
|
|
202
|
-
reconnect; registry per environment; transport-health vs data-freshness
|
|
203
|
-
separated; offline-readable cache; mutations never auto-replayed. Env
|
|
204
|
-
stable ID across restarts; advertised endpoints are hints; ordered routes
|
|
205
|
-
first-that-works + preflight + cooldown; learned LAN/tailnet routes;
|
|
206
|
-
pairing secret in URL FRAGMENT never query; clients use advertised caps.
|
|
207
|
-
Env issues own sessions; per-RPC scope checks; pairing narrows scopes only;
|
|
208
|
-
creation response alone returns raw credential; DPoP binds proof key.
|
|
209
|
-
|
|
210
|
-
## 3. Shared contract (FROZEN — M0 exit)
|
|
211
|
-
|
|
212
|
-
Lives in `packages/contracts/`. All four surfaces implement against it.
|
|
213
|
-
|
|
214
|
-
### 3.1 Harness adapters (`harness.json`)
|
|
215
|
-
|
|
216
|
-
One entry per driver: `{driver, displayName, binary, versionProbe,
|
|
217
|
-
briefDelivery: file|stdin|inline, sessionCapture: preassigned|log|none,
|
|
218
|
-
resume: true|false, capabilities:{...}, permissionMap:{...}}`.
|
|
219
|
-
cursor/agy ship `resume:false` + `sessionCapture:none` — UIs render
|
|
220
|
-
`resume unsupported` instead of faking continuity.
|
|
221
|
-
|
|
222
|
-
### 3.2 Launch RPC (`launch.json` + `POST /api/launch`)
|
|
223
|
-
|
|
224
|
-
Request: `{board?, harness, count, prefix?, to?, body, subject?,
|
|
225
|
-
priority?, model?, maxTurns?, allowTools?, permission:
|
|
226
|
-
supervised|autoEdits|auto|full, isolate?, worktree?|branch?,
|
|
227
|
-
oneshot|persistent, budgetTokens?, budgetMinutes?, timeout?,
|
|
228
|
-
target: local|relays[{url,weight}], dryRun?}`.
|
|
229
|
-
Response: `{crewId, batch, workers[{name,pid?,replyId,relay?}], warnings[]}`.
|
|
230
|
-
Permission mapping: supervised = no `--auto`; autoEdits = harness middle
|
|
231
|
-
ground or supervised + loud note; auto = `--auto` + sandbox warning;
|
|
232
|
-
full = `--auto --i-understand-danger` + isolate recommended.
|
|
233
|
-
|
|
234
|
-
### 3.3 Env identity + routes
|
|
235
|
-
|
|
236
|
-
`relay.json` + `/healthz` gain `{envId (stable uuid), advertisedRoutes[],
|
|
237
|
-
capabilities[]}`. `GET /api/routes` lists ordered routes. Clients walk
|
|
238
|
-
first-that-works, preflight earlier routes, learn LAN/tailnet, never fall
|
|
239
|
-
back to loopback silently.
|
|
240
|
-
|
|
241
|
-
### 3.4 Pairing (`pairing.json`)
|
|
242
|
-
|
|
243
|
-
`POST /api/pair/issue` (orchestrator) → one-time
|
|
244
|
-
`crewbus://pair?env=<id>&routes=<json>&caps=<…>#<abp-…>` (secret in
|
|
245
|
-
FRAGMENT; QR renders the same). `POST /api/pair/exchange` swaps once for
|
|
246
|
-
`abd-…` with requested scopes ⊆ granted (narrow-only). Devices relay-local,
|
|
247
|
-
hashed at rest, revocable, audited, never synced/exported.
|
|
248
|
-
|
|
249
|
-
### 3.5 Auth scopes
|
|
250
|
-
|
|
251
|
-
Device creds gain `scopes[]` (default = today's full device). New pairs
|
|
252
|
-
request narrowed (`launch:spawn/kill`, `mail:send/inbox/ack`, `fleet:read`,
|
|
253
|
-
`admin:pair/revoke`). `requireRelaySecret` → `requireScope(rpc)`. Agent
|
|
254
|
-
tokens + RBAC (`checkToken` then `authorize`) unchanged.
|
|
255
|
-
|
|
256
|
-
### 3.6 Board caps
|
|
257
|
-
|
|
258
|
-
`board.json` gains `caps[]` (subset of `RELAY_CAPS + [launch]`).
|
|
259
|
-
Mixed-version peers degrade with `SUB_CAP_NOTE` wording, never 500.
|
|
260
|
-
## 4. Surfaces (same IA, same contract)
|
|
261
|
-
|
|
262
|
-
### 4.1 CLI (`bin/`, zero-dep stays)
|
|
263
|
-
|
|
264
|
-
`crewbus launch` wizard (TTY prompts; `--yes/--json/--dry-run` headless):
|
|
265
|
-
board → `harnesses detect` table (binary? version? flags? auth?) →
|
|
266
|
-
harness → count/prefix/names → brief (8000-char guard + split guidance) →
|
|
267
|
-
model/turns/tools → permission segmented → isolate/worktree/lifetime/
|
|
268
|
-
budget/timeout → target (local or `crew survey` fleet + weights) →
|
|
269
|
-
dry-run preview (`formatSpawnCmd`) → launch. Thin over
|
|
270
|
-
`bootWorker`/`remoteSpawn`. New: `harnesses [detect --json]`,
|
|
271
|
-
`pair [issue|qr|devices|revoke]`, `serve --advertise-routes --pair-qrcode`.
|
|
272
|
-
Every existing verb untouched.
|
|
273
|
-
|
|
274
|
-
### 4.2 Web dashboard (evolve `bin/lib/web.js`, no build step v1)
|
|
275
|
-
|
|
276
|
-
AppRoot: left nav (Boards, Crews, Fleet, Channels, Triage, Approvals,
|
|
277
|
-
Results, Audit, Settings); top bar (env/board picker + harness picker +
|
|
278
|
-
connection dot + `Ctrl+K`); center launch panel (harness cards with detect
|
|
279
|
-
state, count stepper, brief composer, permission segmented, dry-run diff);
|
|
280
|
-
right inspector (state/pid/reply/acked/log tail/session id + kill/respawn/
|
|
281
|
-
ack). Reuse snapshot shapes; add `GET /api/harnesses`, `GET /api/routes`,
|
|
282
|
-
`POST /api/launch`, `POST /api/pair/issue|exchange`. Poll 5s → SSE later.
|
|
283
|
-
Tokens in tab memory (opt-in persist).
|
|
284
|
-
|
|
285
|
-
### 4.3 Web Dashboard & Pair (`crewbus web`)
|
|
286
|
-
|
|
287
|
-
Same web UI via local scheme; main owns sidecar
|
|
288
|
-
(`node bin/crewbus.js serve --port 0` loopback), SSH tunnels, pairing
|
|
289
|
-
window, background service; `Local environment` toggle for remote-only
|
|
290
|
-
(no state deletion). One-day Tauri-vs-Electron spike in Phase 0.
|
|
291
|
-
|
|
292
|
-
### 4.4 Mobile (`apps/mobile`, Expo, remote-only v1)
|
|
293
|
-
|
|
294
|
-
QR pair → ordered + learned routes → triage/approve/kill/launch cards;
|
|
295
|
-
offline inbox/draft cache + explicitly-retried mutation queue (never
|
|
296
|
-
auto-replayed); biometric credential store; no local exec; long-poll +
|
|
297
|
-
foreground refresh v1 (no FCM).
|
|
298
|
-
|
|
299
|
-
## 5. Information architecture (all GUIs)
|
|
300
|
-
|
|
301
|
-
Boards (tenants, one dir each) → Crews (launch groups) → Workers;
|
|
302
|
-
Triage (unacked, digest-first); Approvals (high-priority, approve/deny);
|
|
303
|
-
Channels / Groups / Results & races / Fleet / Audit / Settings.
|
|
304
|
-
Do: digest-first, per-sender order, `[untrusted peer]` envelopes, Undo
|
|
305
|
-
toasts, `Ctrl+K` everything. Don't: workflow engine, cross-board queries,
|
|
306
|
-
secret sync, mutation auto-replay, silent loopback fallback.
|
|
307
|
-
|
|
308
|
-
## 6. Repo shape + milestones
|
|
309
|
-
|
|
310
|
-
```
|
|
311
|
-
crewbus/ bin/ + bin/lib/* (additive only)
|
|
312
|
-
packages/contracts/ harness.json launch.json pairing.json board-caps.json
|
|
313
|
-
packages/client-runtime/ supervisor, routes, auth store, cache, hooks
|
|
314
|
-
apps/mobile/
|
|
315
|
-
docs/CONTROL_PLANE_SPEC.md (this file)
|
|
316
|
-
test/crewbus.control-plane.mjs
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
M0 contract freeze + M1 CLI launch shipped (`2a1015c`) → M2 web AppRoot shipped (`3715344`) + M3 client-runtime shipped (`46e8989`) → M4 desktop shipped (`2972b1c`) → M5 mobile shipped (`7569ddd`) → M6 hardening as M6-lite scope enforcement / standby pair-503s / dashboard live refresh shipped (`0893026`) plus this M6 docs tail (COMPATIBILITY refresh + version-skew matrix, no code changes).
|
|
320
|
-
|
|
321
|
-
## 7. Test plan
|
|
322
|
-
|
|
323
|
-
`npm test` stays green throughout. New `test/crewbus.control-plane.mjs`:
|
|
324
|
-
every COMPATIBILITY harness has a contracts entry with required fields;
|
|
325
|
-
launch schema round-trips; pairing URL keeps secret in fragment;
|
|
326
|
-
scope exchange narrows-only; caps degrade with `SUB_CAP_NOTE` wording;
|
|
327
|
-
`launch --dry-run` previews exact commands without booting.
|
|
328
|
-
|
|
329
|
-
## 8. Risks
|
|
330
|
-
|
|
331
|
-
cursor/agy session ids (report unsupported, never fake); mobile sockets
|
|
332
|
-
(foreground re-probe + queued mutations); Windows `cmd.exe` ~60s tails
|
|
333
|
-
(size supervision windows); secrets UX (QR + fragment + biometric +
|
|
334
|
-
`devices` lastSeen review); version skew (caps, never 500); scope discipline
|
|
335
|
-
(no engine, no cross-board search, no hosted proxy).
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
1
|
+
# Control Plane Specification
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#control-plane`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#control-plane)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Control Plane Architecture
|
|
10
|
+
|
|
11
|
+
- Governed by frozen v1 contracts in `packages/contracts/`:
|
|
12
|
+
- `launch.json` (Launch requests and permission mapping)
|
|
13
|
+
- `harness.json` (7 AI harness drivers and CLI flags)
|
|
14
|
+
- `pairing.json` (QR and relay pairing with fragment secrets)
|
|
15
|
+
- `board-caps.json` (Feature negotiation and capability degradation)
|
|
16
|
+
- Implemented via `crewbus launch`, `crewbus harnesses detect`, `crewbus web`, and `packages/client-runtime/`.
|
package/docs/CREWS.md
CHANGED
|
@@ -1,58 +1,13 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Mixed-Harness Crews & Relays
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
(largest remainder). Standbys and unreachable relays skip loudly — they never
|
|
7
|
-
silently absorb workers.
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#control-plane`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#control-plane)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
---
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
crewbus crew survey --relays http://r1:8471,http://r2:8471 [--json]
|
|
13
|
-
# http://r1:8471 role=primary weight=3 workers=2 lagMs=- uptimeSec=400
|
|
14
|
-
# http://r2:8471 role=primary weight=1 workers=0 lagMs=- uptimeSec=390
|
|
15
|
-
```
|
|
9
|
+
## Fleet Coordination
|
|
16
10
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
crewbus crew dispatch --from orchestrator \
|
|
21
|
-
--relays http://r1:8471,http://r2:8471 --weights 3,1 \
|
|
22
|
-
--count 4 --prefix w --harness opencode \
|
|
23
|
-
--body "Triage batch 7…" --secret s3 [--dry-run]
|
|
24
|
-
# dispatched 3/3 to http://r1:8471 [weight 3]
|
|
25
|
-
# w-1 pid 7436 reply msg-…
|
|
26
|
-
# dispatched 1/1 to http://r2:8471 [weight 1]
|
|
27
|
-
# w-4 pid 4668 reply msg-…
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
Flags mirror `spawn` (`--harness/--cmd/--cwd/--model/--max-turns/
|
|
31
|
-
--allow-tools/--auto/--subject/--priority/--sender-type/--keep-env/
|
|
32
|
-
--allow-env`, budgets stay local-only). `--model` also takes a comma list
|
|
33
|
-
(`a,b,c`) cycled in worker order. `--dry-run` prints the shares
|
|
34
|
-
without booting.
|
|
35
|
-
|
|
36
|
-
Remote boots run as each relay board's orchestrator. The relay secret or a
|
|
37
|
-
device credential with `launch:spawn` is the auth boundary; replies land on
|
|
38
|
-
each relay's board — `sync` them back or `gather` per relay.
|
|
39
|
-
|
|
40
|
-
## Credentials per relay
|
|
41
|
-
|
|
42
|
-
Repeat `--relay-auth <url-prefix>=<cred>` for relays that don't share one
|
|
43
|
-
secret (`abd-…` values go out as device credentials, anything else as the
|
|
44
|
-
shared secret; longest prefix wins). Bare `--secret` / `--device` /
|
|
45
|
-
`CREWBUS_*` apply to every relay. Pair each relay first
|
|
46
|
-
(`relay pair`, see `docs/PAIRING.md`) and you never share a secret at all.
|
|
47
|
-
|
|
48
|
-
## Properties
|
|
49
|
-
|
|
50
|
-
- **Weights are preferences, not quotas.** A relay that goes unreachable or
|
|
51
|
-
standby mid-dispatch is skipped; its share is *not* re-dealt (no double
|
|
52
|
-
boot) — the summary shows what landed where, and you re-dispatch the rest.
|
|
53
|
-
- **Standbys never boot.** They refuse writes with 503; dispatch skips them
|
|
54
|
-
loudly rather than queueing into a replica.
|
|
55
|
-
- **Deterministic shares.** Same weights + count always split the same way,
|
|
56
|
-
so `--dry-run` predicts the real run and tests can assert distributions.
|
|
57
|
-
- **Audited both ends.** The caller's board records `crew-dispatch` (relays,
|
|
58
|
-
count, shares); each relay records its own `remote-spawn` audit trail.
|
|
11
|
+
- Spawning mixed-harness crews: `--harness claude,opencode,codex`.
|
|
12
|
+
- Dynamic model selection per worker: `--model a,b,c`.
|
|
13
|
+
- Weighted relay dispatching and survey queries.
|
package/docs/DELIVERY.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
> **Unified Documentation:** See [`documentation.html#delivery`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#delivery) and [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md).
|
|
2
|
+
|
|
1
3
|
# Delivery semantics
|
|
2
4
|
|
|
3
5
|
How the bus behaves when things go wrong. Read this before building
|
package/docs/EXPERIMENTS.md
CHANGED
|
@@ -1,56 +1,11 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Benchmarking & Ablation Experiments
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#scale-limits`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#scale-limits)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/COMPATIBILITY.md`](file:///C:/Users/Surface/Documents/crewbus/docs/COMPATIBILITY.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
---
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
script checker. Verifier: the checker script, exit 0/1.
|
|
11
|
-
2. **Small formal proofs** — toy theorems with a machine-checkable proof
|
|
12
|
-
(Lean or a purpose-built checker). Verifier: the checker.
|
|
13
|
-
3. **TDD code tasks** — a failing test suite ships with the task; the agent
|
|
14
|
-
edit must turn it green without breaking the rest. Verifier: the suite.
|
|
15
|
-
4. **One cross-dependency task** — lateral messaging should help here if it
|
|
16
|
-
helps anywhere: subproblems with discovered couplings (e.g. part A's
|
|
17
|
-
interface choice constrains part B), where workers must negotiate the
|
|
18
|
-
seam. Verifier: joint test suite + seam contract check.
|
|
9
|
+
## Benchmark Suites
|
|
19
10
|
|
|
20
|
-
|
|
21
|
-
experiment. Suggested: `ack --verify "<command>"`-style hooks so acceptance
|
|
22
|
-
can be automatic (see review §4.2).
|
|
23
|
-
|
|
24
|
-
## Conditions (ablate the structure)
|
|
25
|
-
|
|
26
|
-
- single agent (baseline)
|
|
27
|
-
- native subagents of one harness (vendor baseline)
|
|
28
|
-
- orchestrator script (fan-out, collect, no lateral mail)
|
|
29
|
-
- crewbus DMs only
|
|
30
|
-
- DMs plus shared channel (`channel post` / `tail`)
|
|
31
|
-
- plus consolidator (a reference reducer worker summarizing group findings)
|
|
32
|
-
|
|
33
|
-
## Scaling curves
|
|
34
|
-
|
|
35
|
-
Group sizes 1 / 4 / 16 / 64 / 256 against: success rate, wall-clock time,
|
|
36
|
-
and cost (tokens + compute). Repeat every cell — agent runs are noisy, so
|
|
37
|
-
report means with spread, never single runs.
|
|
38
|
-
|
|
39
|
-
## Message audit rubric
|
|
40
|
-
|
|
41
|
-
Sample messages from each run and classify each as:
|
|
42
|
-
|
|
43
|
-
- **useful** — changed a decision, carried a result, prevented rework;
|
|
44
|
-
- **redundant** — restated known state, duplicate, noise;
|
|
45
|
-
- **harmful** — wrong direction, stale pointer acted on, prompt-injected.
|
|
46
|
-
|
|
47
|
-
Report the mix per condition: a win on success rate with 80% redundant
|
|
48
|
-
traffic is a different finding than a lean win.
|
|
49
|
-
|
|
50
|
-
## Reporting policy (negative results required)
|
|
51
|
-
|
|
52
|
-
Publish negative results. If P2P does not beat a simple orchestrator, say
|
|
53
|
-
so — the project keeps a defensible smaller claim (best cross-harness
|
|
54
|
-
messaging layer) and the field learns something. File every run as:
|
|
55
|
-
task + verifier + condition + group size + repeats + success/time/cost +
|
|
56
|
-
message-audit sample, with hardware and model versions pinned.
|
|
11
|
+
- Run `npm run bench` and `npm run bench:load` to measure local board latency and throughput.
|