crewbus 11.3.1 → 11.5.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 +21 -0
- package/README.md +2 -2
- package/bin/lib/web.js +1903 -1704
- package/docs/APPROVALS.md +28 -58
- 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 +199 -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
|
@@ -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.
|
package/docs/GROUPS.md
CHANGED
|
@@ -1,109 +1,13 @@
|
|
|
1
|
-
# Groups
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
crewbus group create
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
`gather --batch` prints a telemetry footer
|
|
17
|
-
(`msgs, ~tokens (chars/4), contributing groups`) and the same fields in
|
|
18
|
-
`--json` (`contributingGroups`, `telemetry`).
|
|
19
|
-
|
|
20
|
-
## Replies carry artifacts
|
|
21
|
-
|
|
22
|
-
```sh
|
|
23
|
-
crewbus send --from e1 --to orchestrator --reply <brief-id> --artifact out/a1.json --body "done"
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
`--artifact <path-or-url>` (max 500 chars) is stored on the message and
|
|
27
|
-
shown by `inbox` / `gather` / `thread`.
|
|
28
|
-
|
|
29
|
-
## Verify, then record the result
|
|
30
|
-
|
|
31
|
-
```sh
|
|
32
|
-
crewbus ack --from orchestrator --id <reply-id> --verify "node test/check.mjs --input out/a1.json"
|
|
33
|
-
crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from orchestrator
|
|
34
|
-
crewbus result show --group team-a
|
|
35
|
-
crewbus result list [--group team-a] [--json]
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
`results/<group>.json` holds ONE record
|
|
39
|
-
`{group, artifact, by, msgId, verifierOutput, at}` — first verified
|
|
40
|
-
result wins. Only verified messages are recordable: the ack marker
|
|
41
|
-
`acked/*/<msgId>.json` must carry `verified:true`, else recording fails
|
|
42
|
-
unless `--force` (which prints a warning to stderr).
|
|
43
|
-
|
|
44
|
-
## Race mode
|
|
45
|
-
|
|
46
|
-
```sh
|
|
47
|
-
crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
|
|
48
|
-
crewbus race close --group team-a --from orchestrator [--kill]
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
`race start` reports the winner (recorded result whose `msgId` is in the
|
|
52
|
-
batch, else the first verified ack on a batch reply) or "no verified
|
|
53
|
-
result yet". `--timeout` polls instead of checking once; there is no
|
|
54
|
-
daemon. `race close` DMs "race closed by X" to every other member and,
|
|
55
|
-
with `--kill`, terminates their spawned pids.
|
|
56
|
-
|
|
57
|
-
## Status + telemetry
|
|
58
|
-
|
|
59
|
-
```sh
|
|
60
|
-
crewbus group status team-a [--json] # running (pid alive), replies, verified, spend
|
|
61
|
-
crewbus group telemetry team-a [--json] # {messages, tokensEst, wallClockMs, members, verifiedCount}
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
Spend = message count + wall-clock since the group `createdAt` +
|
|
65
|
-
token estimate (`chars/4` over member bodies+subjects). `createdAt` is
|
|
66
|
-
backfilled from the group file mtime for pre-existing groups.
|
|
67
|
-
|
|
68
|
-
## Attribution (agents in several groups)
|
|
69
|
-
|
|
70
|
-
- A reply attributes via its chain: `--reply <msg-id>` → root brief →
|
|
71
|
-
batch → group(s) whose members appear in the transcript.
|
|
72
|
-
- `gather --batch` shows `contributing groups` (groups with ≥1 message
|
|
73
|
-
from a member in the transcript).
|
|
74
|
-
- `result record` **requires `--group` explicitly** — there is no
|
|
75
|
-
auto-assign. When an agent is in several groups, the recorder decides
|
|
76
|
-
which group the result counts for.
|
|
77
|
-
|
|
78
|
-
## Cross-group collaboration
|
|
79
|
-
|
|
80
|
-
Groups share one board, so any member can already read anything. The
|
|
81
|
-
thing that decides whether groups actually collaborate is whether the
|
|
82
|
-
brief tells them the map. Since v10.0.x every `spawn` brief carries a
|
|
83
|
-
**Crew:** block (see `buildCrewContext` in `bin/lib/spawn.js`): your
|
|
84
|
-
group(s) + members + lane, the sibling groups of the same spawn +
|
|
85
|
-
members, their group channels, and the peer-DM norm. Groups from
|
|
86
|
-
unrelated concurrent briefs are deliberately NOT enumerated — they
|
|
87
|
-
collapse to a count (`N other groups exist on this board`), so
|
|
88
|
-
cross-task rosters stay discoverable (`crewbus group list`) without
|
|
89
|
-
becoming prompt noise or a misleading invitation. Conventions that
|
|
90
|
-
block assumes:
|
|
91
|
-
|
|
92
|
-
- **Peer-direct for questions.** `crewbus send --from you --to-group
|
|
93
|
-
<group> --subject "..." --body "..."` reaches every member of
|
|
94
|
-
another group. Ask the group that owns a thing first; the orchestrator is
|
|
95
|
-
for approvals (`--priority high`) and scope disputes only.
|
|
96
|
-
- **Channels are the shared read surface.** `crewbus channel tail
|
|
97
|
-
grp-<group>` shows a group's briefs + mirrored progress; reads need
|
|
98
|
-
no token. Channel *posting* is member-scoped (default-on, no flag):
|
|
99
|
-
a worker may post to `grp-<group>` only when it is a MEMBER of that
|
|
100
|
-
group — board channels and foreign groups are orchestrator-only
|
|
101
|
-
(see docs/RBAC.md).
|
|
102
|
-
- **Boot habit.** `crewbus agents` + `crewbus group list` once at
|
|
103
|
-
start, so a worker knows who else is here. A worker that never runs
|
|
104
|
-
a discovery command will work star-topology through the orchestrator — that
|
|
105
|
-
is a failure of the brief, not the worker.
|
|
106
|
-
- **Scope questions stay lanes-first.** "Stay in your lane" prevents
|
|
107
|
-
collisions; "DM the group that owns a thing" prevents silos. A
|
|
108
|
-
brief should name both the boundary *and* the bridge.
|
|
109
|
-
|
|
1
|
+
# Groups & Member-Scoped Channels
|
|
2
|
+
|
|
3
|
+
> **Consolidated Documentation:** This guide has been consolidated into the unified crewbus documentation:
|
|
4
|
+
> - Interactive Single-Page Guide: [`documentation.html#layout`](file:///C:/Users/Surface/Documents/crewbus/documentation.html#layout)
|
|
5
|
+
> - Canonical Markdown Reference: [`docs/ARCHITECTURE.md`](file:///C:/Users/Surface/Documents/crewbus/docs/ARCHITECTURE.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Groups & Channels
|
|
10
|
+
|
|
11
|
+
- Group creation: `crewbus group create <name> --members a,b,c`.
|
|
12
|
+
- Scoped channels: `grp-<name>` channels permit postings only from members of that group.
|
|
13
|
+
- Context isolation: Task-scoped briefs include relevant groups only, preventing cross-task leaks.
|