crewbus 10.0.12 → 11.3.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/AGENTS.template.md +4 -4
- package/CHANGELOG.md +135 -0
- package/README.md +69 -44
- package/TEAM.template.md +1 -1
- package/bin/crewbus-hook.js +22 -5
- package/bin/crewbus-mcp.js +56 -48
- package/bin/crewbus.js +459 -238
- package/bin/lib/channels.js +1 -1
- package/bin/lib/export.js +1 -1
- package/bin/lib/groups.js +1 -5
- package/bin/lib/identity.js +90 -128
- package/bin/lib/launch.js +63 -8
- package/bin/lib/relay.js +25 -42
- package/bin/lib/spawn.js +155 -162
- package/bin/lib/store.js +2 -2
- package/bin/lib/web.js +49 -46
- package/claude-plugin/skills/crewbus/SKILL.md +1 -1
- package/docs/APPROVALS.md +8 -8
- package/docs/AUDIT_EXPORT.md +7 -7
- package/docs/CERT_READINESS.md +5 -5
- package/docs/COMPATIBILITY.md +6 -2
- package/docs/CONSOLIDATOR.md +6 -6
- package/docs/CONTROL_PLANE_SPEC.md +3 -3
- package/docs/CREWS.md +58 -55
- package/docs/DELIVERY.md +11 -8
- package/docs/GROUPS.md +8 -8
- package/docs/IDENTITY.md +6 -6
- package/docs/LEAD_ASSIGN.md +2 -73
- package/docs/LONG_RUNS.md +3 -3
- package/docs/M1_CLI_DRAFT.md +7 -7
- package/docs/ORCHESTRATOR.md +87 -0
- package/docs/PAIRING.md +7 -7
- package/docs/QUICKSTART.md +81 -70
- package/docs/RBAC.md +84 -73
- package/docs/TENANCY.md +10 -10
- package/docs/THREAT_MODEL.md +3 -3
- package/docs/VERIFIER.md +10 -10
- package/docs/VERSION_SKEW.md +1 -1
- package/documentation.html +33 -24
- package/examples/hermes-pairing.md +3 -3
- package/examples/t3-pairing.md +1 -1
- package/index.html +6 -6
- package/opencode/plugins/dm-watch.js +1 -1
- package/opencode/tools/dm-send.js +1 -1
- package/package.json +27 -2
- package/packages/contracts/harness.json +15 -1
- package/packages/contracts/launch.json +2 -3
- package/packages/contracts/pairing.json +3 -3
package/docs/DELIVERY.md
CHANGED
|
@@ -46,7 +46,10 @@ the OS recycles pids and a dead worker could read as "running". Status
|
|
|
46
46
|
now also resolves the process start time (`ps` elapsed on unix,
|
|
47
47
|
`Get-Process` on Windows, 60s memo) and compares it against the recorded
|
|
48
48
|
`spawnedAt` (±120s skew): a live pid whose process started *after* the
|
|
49
|
-
spawn is a stranger, and `alive` flips to false.
|
|
49
|
+
spawn is a stranger, and `alive` flips to false. `spawnedAt` is the launch
|
|
50
|
+
time of the currently recorded pid — it is set at spawn and refreshed on
|
|
51
|
+
every respawn, so a live replacement is not mistaken for a recycled pid.
|
|
52
|
+
The original registration time stays in `firstSeen`. The verdict rides along
|
|
50
53
|
as `aliveVerified` (`true` corroborated, `false` contradicted, `null`
|
|
51
54
|
unverifiable on this platform — the old kill-0 verdict stands). The
|
|
52
55
|
override needs positive evidence (start time after spawn + skew), so a
|
|
@@ -63,7 +66,7 @@ Long briefs die mid-way; re-deriving progress from files wastes the
|
|
|
63
66
|
resume. Workers checkpoint every few steps (or before anything risky):
|
|
64
67
|
|
|
65
68
|
```sh
|
|
66
|
-
crewbus send --from <you> --to
|
|
69
|
+
crewbus send --from <you> --to orchestrator --reply <brief-id> --checkpoint --body "done X / next Y"
|
|
67
70
|
```
|
|
68
71
|
|
|
69
72
|
(`dm_send` takes `checkpoint: true`; same on the opencode `dm-send`
|
|
@@ -89,7 +92,7 @@ of restarting. Checkpoints are unverified progress: they never feed
|
|
|
89
92
|
|
|
90
93
|
`pool` briefs all workers up front, boots at most `--pool-size`
|
|
91
94
|
concurrently, and replaces exits until N total — but the supervision loop
|
|
92
|
-
runs inside the invoking CLI process. If that process dies (
|
|
95
|
+
runs inside the invoking CLI process. If that process dies (orchestrator restart,
|
|
93
96
|
shutdown, supervision-window timeout), `pool-resume --id <pool> --from
|
|
94
97
|
<you>` re-attaches: it reconciles every launched worker (replied → done,
|
|
95
98
|
live → re-adopted, dead w/o reply → done with a `respawn` hint), then
|
|
@@ -98,7 +101,7 @@ by id, never duplicated; one supervisor at a time via an advisory pool
|
|
|
98
101
|
lock (TTL expiry lets a later attach take over after a crash).
|
|
99
102
|
`finishedAt` marks true completion only — a timed-out pool stays
|
|
100
103
|
resumable. Pools created before the resumable schema (no queue cursor)
|
|
101
|
-
are refused with guidance.
|
|
104
|
+
are refused with guidance. Orchestrator-only.
|
|
102
105
|
|
|
103
106
|
Windows note: console-less detached `cmd.exe` wrappers linger up to ~60s
|
|
104
107
|
after their payload exits, so natural-exit detection on `shell:true`
|
|
@@ -122,10 +125,10 @@ nobody accepted. The reassign pattern:
|
|
|
122
125
|
|
|
123
126
|
```sh
|
|
124
127
|
# what is still open — and how long has it waited?
|
|
125
|
-
crewbus inbox --from
|
|
128
|
+
crewbus inbox --from orchestrator --unacked --older-than 10m
|
|
126
129
|
|
|
127
130
|
# the brief is a file: re-brief a fresh worker on the same thread
|
|
128
|
-
crewbus send --from
|
|
131
|
+
crewbus send --from orchestrator --to w9 --reply <brief-id> --body "picking this up (w3 went silent)"
|
|
129
132
|
|
|
130
133
|
# the dead watcher's mail, if any, can be replayed
|
|
131
134
|
crewbus redeliver --from w3 --all
|
|
@@ -177,7 +180,7 @@ terminates everything when the whole run is lost.
|
|
|
177
180
|
has no pre-set flag (its id arrives in the first stream event — the
|
|
178
181
|
residual window is milliseconds); codex relies on `thread.started`;
|
|
179
182
|
cursor/agy offer neither.
|
|
180
|
-
- **Respawn (`respawn --from
|
|
183
|
+
- **Respawn (`respawn --from orchestrator --to <worker>`).** Reboots one dead
|
|
181
184
|
worker in its *same* harness conversation: `opencode run --session`,
|
|
182
185
|
`claude -p --resume` (+ `CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1` so a
|
|
183
186
|
killed turn continues), `codex exec resume`, `grok -r`, agy
|
|
@@ -188,7 +191,7 @@ terminates everything when the whole run is lost.
|
|
|
188
191
|
prompt can't attach files). Refuses live workers unless `--force`
|
|
189
192
|
(kills first, own-crew scoped like `spawn-kill`); refuses unknown,
|
|
190
193
|
never-captured, and pre-capture-era workers with re-brief guidance.
|
|
191
|
-
Attempts count on the binding; `--dry-run` previews.
|
|
194
|
+
Attempts count on the binding; `--dry-run` previews. Orchestrator-only.
|
|
192
195
|
|
|
193
196
|
## Poll discipline (long runs)
|
|
194
197
|
|
package/docs/GROUPS.md
CHANGED
|
@@ -9,7 +9,7 @@ is replaced by the commands below.
|
|
|
9
9
|
|
|
10
10
|
```sh
|
|
11
11
|
crewbus group create team-a --add a1,a2,a3
|
|
12
|
-
crewbus send --from
|
|
12
|
+
crewbus send --from orchestrator --to-group team-a --subject "variant: regularity" --body "..."
|
|
13
13
|
crewbus gather --batch <batch> # briefs + replies + telemetry footer + contributing groups
|
|
14
14
|
```
|
|
15
15
|
|
|
@@ -20,7 +20,7 @@ crewbus gather --batch <batch> # briefs + replies + telemetry footer + contrib
|
|
|
20
20
|
## Replies carry artifacts
|
|
21
21
|
|
|
22
22
|
```sh
|
|
23
|
-
crewbus send --from e1 --to
|
|
23
|
+
crewbus send --from e1 --to orchestrator --reply <brief-id> --artifact out/a1.json --body "done"
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
`--artifact <path-or-url>` (max 500 chars) is stored on the message and
|
|
@@ -29,8 +29,8 @@ shown by `inbox` / `gather` / `thread`.
|
|
|
29
29
|
## Verify, then record the result
|
|
30
30
|
|
|
31
31
|
```sh
|
|
32
|
-
crewbus ack --from
|
|
33
|
-
crewbus result record --group team-a --msg <reply-id> --artifact out/a1.json --from
|
|
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
34
|
crewbus result show --group team-a
|
|
35
35
|
crewbus result list [--group team-a] [--json]
|
|
36
36
|
```
|
|
@@ -45,7 +45,7 @@ unless `--force` (which prints a warning to stderr).
|
|
|
45
45
|
|
|
46
46
|
```sh
|
|
47
47
|
crewbus race start --group team-a --batch <batch> [--timeout 60000] [--json]
|
|
48
|
-
crewbus race close --group team-a --from
|
|
48
|
+
crewbus race close --group team-a --from orchestrator [--kill]
|
|
49
49
|
```
|
|
50
50
|
|
|
51
51
|
`race start` reports the winner (recorded result whose `msgId` is in the
|
|
@@ -91,17 +91,17 @@ block assumes:
|
|
|
91
91
|
|
|
92
92
|
- **Peer-direct for questions.** `crewbus send --from you --to-group
|
|
93
93
|
<group> --subject "..." --body "..."` reaches every member of
|
|
94
|
-
another group. Ask the group that owns a thing first; the
|
|
94
|
+
another group. Ask the group that owns a thing first; the orchestrator is
|
|
95
95
|
for approvals (`--priority high`) and scope disputes only.
|
|
96
96
|
- **Channels are the shared read surface.** `crewbus channel tail
|
|
97
97
|
grp-<group>` shows a group's briefs + mirrored progress; reads need
|
|
98
98
|
no token. Channel *posting* is member-scoped (default-on, no flag):
|
|
99
99
|
a worker may post to `grp-<group>` only when it is a MEMBER of that
|
|
100
|
-
group — board channels and foreign groups
|
|
100
|
+
group — board channels and foreign groups are orchestrator-only
|
|
101
101
|
(see docs/RBAC.md).
|
|
102
102
|
- **Boot habit.** `crewbus agents` + `crewbus group list` once at
|
|
103
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
|
|
104
|
+
a discovery command will work star-topology through the orchestrator — that
|
|
105
105
|
is a failure of the brief, not the worker.
|
|
106
106
|
- **Scope questions stay lanes-first.** "Stay in your lane" prevents
|
|
107
107
|
collisions; "DM the group that owns a thing" prevents silos. A
|
package/docs/IDENTITY.md
CHANGED
|
@@ -58,8 +58,8 @@ crewbus token status --from alice [--json]
|
|
|
58
58
|
|
|
59
59
|
## Mover (rename / team change)
|
|
60
60
|
|
|
61
|
-
1. Offboard the old name (
|
|
62
|
-
`register --offboard old-name --from
|
|
61
|
+
1. Offboard the old name (orchestrator, token-checked):
|
|
62
|
+
`register --offboard old-name --from orchestrator`
|
|
63
63
|
2. Register the new name: `register --from new-name`
|
|
64
64
|
3. History stays: DMs to/from the old name remain on disk and in `--all`
|
|
65
65
|
dumps for audit.
|
|
@@ -68,16 +68,16 @@ crewbus token status --from alice [--json]
|
|
|
68
68
|
|
|
69
69
|
```
|
|
70
70
|
# kill one identity's live tokens (identity stays, they must re-register):
|
|
71
|
-
crewbus token revoke --from
|
|
71
|
+
crewbus token revoke --from orchestrator --target bob [--reason "laptop lost"]
|
|
72
72
|
|
|
73
73
|
# full deprovision (revokes tokens + marks offboarded, inbox preserved):
|
|
74
|
-
crewbus register --offboard bob --from
|
|
74
|
+
crewbus register --offboard bob --from orchestrator
|
|
75
75
|
```
|
|
76
76
|
|
|
77
77
|
- Revoked callers get: `token for "bob" is revoked — re-register...`.
|
|
78
78
|
- Offboarded callers get: `agent "bob" is offboarded — sends ... refused`.
|
|
79
79
|
- Re-register after revoke mints fresh (no dead token needed);
|
|
80
|
-
offboarded names stay refused until
|
|
80
|
+
offboarded names stay refused until the orchestrator re-onboards them.
|
|
81
81
|
|
|
82
82
|
## Sync hygiene
|
|
83
83
|
|
|
@@ -160,7 +160,7 @@ Compaction amnesia used to mint throwaway identities (`unknown` on the board,
|
|
|
160
160
|
miss does it print the `crewbus recover` instruction — never a "you are
|
|
161
161
|
unknown" blessing.
|
|
162
162
|
- **Bindings survive daily traffic:** register stores `sessionId`; later
|
|
163
|
-
sessionless sends/re-registers/
|
|
163
|
+
sessionless sends/re-registers/orchestrator touches must NOT wipe it
|
|
164
164
|
(`mergeAgentDoc` deletes undefined patch keys — callers add `sessionId`
|
|
165
165
|
to the patch only when given). Heartbeats merge field-by-field and never
|
|
166
166
|
touch unrelated fields.
|
package/docs/LEAD_ASSIGN.md
CHANGED
|
@@ -1,74 +1,3 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Moved
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
This architecture is modeled after decentralized multi-agent coordination patterns (e.g. Minecraft multi-agent peer collaboration):
|
|
6
|
-
- **Peers** communicate directly, self-organize strategy, and write findings to shared ambient memory (the board / Workbench).
|
|
7
|
-
- An **Observer** (`lead`) monitors health, chases failures/timeouts, fail-closes approvals, and verifies claims against actual artifacts.
|
|
8
|
-
- The **Boss** sets the objective and monitors milestones asynchronously without micromanaging execution.
|
|
9
|
-
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
## 1. The Lane Model
|
|
13
|
-
|
|
14
|
-
| Lane | Actor | Authority & Responsibilities |
|
|
15
|
-
|---|---|---|
|
|
16
|
-
| **Boss** | User / Calling Session | • Sets the objective and mission parameters.<br>• Reads progress via dashboard, status commands, or milestone DMs.<br>• Resolves out-of-scope mission changes or irreconcilable disputes.<br>• Never routes routine peer messages. |
|
|
17
|
-
| **Lead** | Autonomous Board Coordinator (`lead`) | • **Observer Role**: Environment repairs, TTL chasing, respawn health (`spawn-status --all`, `respawn`).<br>• **Approvals**: Decides on irreversible/high-risk actions (`fail-closed`).<br>• **Verification**: Audits worker claims against actual files/logs before aggregating.<br>• **Milestones**: Relays aggregate outcomes back to the boss.<br>• *Never* settles peer strategy disputes or does workers' implementation tasks. |
|
|
18
|
-
| **Peers** | Worker Agents (`sec-1`, `sec-2`, ...) | • Own task strategy, execution, and local decisions.<br>• Direct peer-to-peer DMs for targeted cooperation and rescue calls.<br>• Post lessons and artifacts directly to the board Workbench.<br>• Checkpoint progress along threads.<br>• Consult groups first; escalate to lead only for scope/approvals. |
|
|
19
|
-
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
## 2. CLI Control: `--lead auto`
|
|
23
|
-
|
|
24
|
-
When spawning workers with `crewbus spawn`:
|
|
25
|
-
|
|
26
|
-
```sh
|
|
27
|
-
# Default: auto-provisions or reuses the observer lead coordinator
|
|
28
|
-
crewbus spawn --from boss --count 3 --harness opencode --body "Implement feature X"
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
### Architecture:
|
|
32
|
-
- **`auto` (default and only mode)**:
|
|
33
|
-
- Auto-provisions or reuses the board's standing `lead` lane.
|
|
34
|
-
- Workers' brief prompts pin reply targets and approval requests to `--to lead`.
|
|
35
|
-
- The autonomous observer coordinator runs on the `lead` lane to monitor health and approvals.
|
|
36
|
-
- Crewbus requires a coding harness (`opencode`, `claude`, `codex`, `grok`, `antigravity`, `cursor`); unmanaged/generic shell execution is not supported.
|
|
37
|
-
|
|
38
|
-
---
|
|
39
|
-
|
|
40
|
-
## 3. Provisioning & Collision Rules
|
|
41
|
-
|
|
42
|
-
1. **First-Claim-Wins**:
|
|
43
|
-
- On a fresh board without a `lead` agent, `provisionAutoLead` mints the `lead` identity with `role: "lead"`.
|
|
44
|
-
- The token is saved to `logs/lead.token` according to the token-file convention.
|
|
45
|
-
2. **Reuse Standing Coordinators**:
|
|
46
|
-
- If an active coordinator is already running (live PID on the `lead` lane), subsequent `spawn` bursts reuse the standing coordinator rather than duplicating it.
|
|
47
|
-
- Workers from new bursts are transferred to the lead lane (`spawnedBy: "lead"`), preserving own-crew RBAC permissions for health tracking and `spawn-kill`.
|
|
48
|
-
3. **Offboarded Safety**:
|
|
49
|
-
- If the `lead` lane has been marked `offboarded: true` (deliberate teardown), auto-provisioning is skipped with a loud warning.
|
|
50
|
-
4. **Boss Detachment**:
|
|
51
|
-
- If `from === "lead"`, auto-provisioning skips into self-bootstrap mode to prevent recursion.
|
|
52
|
-
5. **Lead Revive (`crewbus spawn --count 0`)**:
|
|
53
|
-
- When the coordinator died (crash, reboot, budget reap), the crew still has
|
|
54
|
-
its briefs/threads on the board — but nobody triaging. `--count 0` boots
|
|
55
|
-
NOTHING except the auto-coordinator lane: zero worker boots, zero DMs
|
|
56
|
-
delivered; the mission text you pass becomes the coordinator's reminder
|
|
57
|
-
of what the crew was on about (worker threads and scope live on the board).
|
|
58
|
-
- Requires `--lead board` (the default under a coding harness); worker
|
|
59
|
-
operands (`--to`/`--to-file`/`--to-group`) are refused — this path has no
|
|
60
|
-
worker operands. A standing coordinator is reused, never duplicated;
|
|
61
|
-
an offboarded lane skips with a loud warning, same as any burst.
|
|
62
|
-
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
## 4. Prompt Engineering
|
|
66
|
-
|
|
67
|
-
- **Workers (`buildSpawnPrompt`)**:
|
|
68
|
-
- Directs completion summaries, checkpoints, and approval requests to `--to lead`.
|
|
69
|
-
- Informs the worker that the spawner stepped back to boss and reads progress via the lead.
|
|
70
|
-
- Reinforces peer-first habits: consult groups before escalating to the lead.
|
|
71
|
-
- **Coordinator (`buildCoordinatorPrompt`)**:
|
|
72
|
-
- Injected with the verbatim mission text from the boss.
|
|
73
|
-
- Lists worker brief IDs for easy threading and reply tracking.
|
|
74
|
-
- Enforces polling discipline (`listen` / `inbox --digest`), fail-closed approval timeouts, and maximum 2 respawn attempts per lane before escalating stalls to the boss.
|
|
3
|
+
This guide moved to [ORCHESTRATOR.md](ORCHESTRATOR.md).
|
package/docs/LONG_RUNS.md
CHANGED
|
@@ -14,7 +14,7 @@ the board.
|
|
|
14
14
|
2. Tokens persist themselves: every register/mint/rotate writes
|
|
15
15
|
`.crewbus/logs/<agent>.token` (0600). Workers re-read it after any
|
|
16
16
|
restart or compaction instead of re-registering (re-registering a
|
|
17
|
-
claimed name fails). Truly lost it?
|
|
17
|
+
claimed name fails). Truly lost it? The orchestrator runs `token revoke --target
|
|
18
18
|
<name>`, worker re-registers fresh. Never commit or post token files;
|
|
19
19
|
`prune`/export skip `*.token`.
|
|
20
20
|
3. Poll digest-first: `inbox --unacked --digest`, full reads only on
|
|
@@ -43,10 +43,10 @@ the board.
|
|
|
43
43
|
|---|---|
|
|
44
44
|
| Post-compaction amnesia | Identity card is auto-injected (hook compact / opencode plugin); unknown who you are? run `crewbus recover` — read-only candidate ranking (session binding → token-file↔tokenHash → cwd), then follow the printed resume script |
|
|
45
45
|
| Landed as "unknown" | Sentinel names ("unknown"/"me"/"you") never mint (register/send refuse them). Run `crewbus recover [--session <id>]` to re-find your real identity; only then re-register your true name |
|
|
46
|
-
| Token lost entirely |
|
|
46
|
+
| Token lost entirely | Orchestrator `token revoke --target`, worker re-registers |
|
|
47
47
|
| Worker silent | `spawn-status`: no reply → read its log; re-brief or `respawn` |
|
|
48
48
|
| Supervisor gone | `pool-resume --id`; stale locks expire via TTL |
|
|
49
|
-
| Reboot | `doctor` → `spawn-status --all` (stale pids read dead, not running) → `respawn`/`pool-resume`; dead coordinator: `crewbus spawn --count 0 --body "<what the crew was on>"` (C9
|
|
49
|
+
| Reboot | `doctor` → `spawn-status --all` (stale pids read dead, not running) → `respawn`/`pool-resume`; dead coordinator: `crewbus spawn --count 0 --body "<what the crew was on>"` (C9 orchestrator revive, workers untouched) |
|
|
50
50
|
| Primary relay down | `relay promote` on the standby (see `docs/HA.md`) |
|
|
51
51
|
|
|
52
52
|
## Bottom line
|
package/docs/M1_CLI_DRAFT.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# M1 CLI draft — `launch` wizard, `harnesses`, `relay pair qr`, serve pairing flags
|
|
2
2
|
|
|
3
|
-
Status: SHIPPED (
|
|
3
|
+
Status: SHIPPED (orchestrator wired `cmdServe` 2026-10-06). Paste §1 into `bin/crewbus.js` USAGE and §2
|
|
4
4
|
into `README.md` after the spawn section ("Running workers (spawn)").
|
|
5
5
|
§1d is now live: `serve --advertise-routes --pair-qrcode` shipped in `cmdServe`;
|
|
6
6
|
`POST /api/launch` + `GET /api/harnesses` + `GET /api/routes` shipped in both
|
|
@@ -32,8 +32,8 @@ Flag verification (role-prompt list vs implementation):
|
|
|
32
32
|
| `--yes` | In shipped USAGE line; no separate consume in `cmdLaunch` (confirm lives in spawn delegation). Keep the token, do not invent semantics |
|
|
33
33
|
| `--permission full` | Needs `--i-understand-danger` (else plan invalid) |
|
|
34
34
|
| `harnesses [detect --json]` | Shipped (`cmdHarnesses`; `detect` optional, bare `harnesses` works) |
|
|
35
|
-
| `relay pair qr --from
|
|
36
|
-
| `serve --advertise-routes <url,url> --pair-qrcode` | SHIPPED in `cmdServe` (advertised at `relay.json`, `GET /healthz`, `GET /api/routes`; `--pair-qrcode` needs `--from
|
|
35
|
+
| `relay pair qr --from orchestrator [--label --ttl --routes --json]` | Shipped (`qr` branch of `cmdRelayPair`); prints `crewbus://pair` URL, secret in `#fragment` only |
|
|
36
|
+
| `serve --advertise-routes <url,url> --pair-qrcode` | SHIPPED in `cmdServe` (advertised at `relay.json`, `GET /healthz`, `GET /api/routes`; `--pair-qrcode` needs `--from orchestrator`, same mint + audit as `relay pair`) |
|
|
37
37
|
|
|
38
38
|
## 1. USAGE text blocks (paste-ready)
|
|
39
39
|
|
|
@@ -48,7 +48,7 @@ Flag verification (role-prompt list vs implementation):
|
|
|
48
48
|
the interactive confirm; --json prints the crewId/batch/workers shape.)
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
Notes for the
|
|
51
|
+
Notes for the orchestrator (do not paste): `--body-file <path>` is also accepted
|
|
52
52
|
(read into the brief before validation); `--target` is `local` (hardcoded —
|
|
53
53
|
fleet goes through `crew dispatch`); `--permission full` additionally
|
|
54
54
|
requires `--i-understand-danger`.
|
|
@@ -65,7 +65,7 @@ requires `--i-understand-danger`.
|
|
|
65
65
|
### 1c. `crewbus relay pair qr` (shipped — keep verbatim)
|
|
66
66
|
|
|
67
67
|
```text
|
|
68
|
-
crewbus relay pair qr --from
|
|
68
|
+
crewbus relay pair qr --from orchestrator [--label <device>] [--ttl 10m] [--routes <url,url>] [--json]
|
|
69
69
|
(prints the one-time crewbus://pair URL (secret in #fragment, never
|
|
70
70
|
query) alongside the plain pairing token. Scan/paste into the mobile
|
|
71
71
|
or desktop client to pair.)
|
|
@@ -158,7 +158,7 @@ surface to keep citing is the resume column: cursor/antigravity
|
|
|
158
158
|
report `resume: false` in `harnesses` output by design (see §2 wording
|
|
159
159
|
above), matching the existing "no" rows.
|
|
160
160
|
|
|
161
|
-
## 4. Paste checklist for the
|
|
161
|
+
## 4. Paste checklist for the orchestrator
|
|
162
162
|
|
|
163
163
|
1. USAGE: §1a–c already shipped in `bin/crewbus.js` — no paste needed.
|
|
164
164
|
§1d only after `cmdServe` gains `--advertise-routes`/`--pair-qrcode`.
|
|
@@ -167,7 +167,7 @@ above), matching the existing "no" rows.
|
|
|
167
167
|
3. COMPATIBILITY.md: no edit (per §3).
|
|
168
168
|
4. Never touched (per role): `bin/crewbus.js`, `package.json`, tests —
|
|
169
169
|
this draft only *adds* `docs/M1_CLI_DRAFT.md`.
|
|
170
|
-
UPDATE (
|
|
170
|
+
UPDATE (orchestrator, 2026-10-06): serve + web wiring landed after the draft —
|
|
171
171
|
`bin/crewbus.js` (`cmdServe` flags, `/api/routes`, `/api/harnesses`,
|
|
172
172
|
`/api/launch`, USAGE), `bin/lib/web.js` (`handleApiLaunch`,
|
|
173
173
|
`/api/harnesses`, `/api/routes`, `/api/launch`), `package.json`
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Orchestrator & Worker Lane Model
|
|
2
|
+
|
|
3
|
+
Crewbus separates **spawning** from **leading** with exactly two roles.
|
|
4
|
+
`spawn` provisions the board's single **orchestrator** and boots the workers;
|
|
5
|
+
the orchestrator owns the crew, while workers collaborate peer-to-peer.
|
|
6
|
+
|
|
7
|
+
- **Workers** communicate directly, self-organize strategy, and write
|
|
8
|
+
findings to shared ambient memory (the board / Workbench).
|
|
9
|
+
- The **orchestrator** monitors health, chases failures/timeouts, fail-closes
|
|
10
|
+
approvals, verifies claims against actual artifacts, and posts the aggregate.
|
|
11
|
+
- The **user/operator** runs `crewbus spawn` with a brief and a worker count.
|
|
12
|
+
There is no separate `boss`, `admin`, `lead`, or `auditor` identity.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 1. The Lane Model
|
|
17
|
+
|
|
18
|
+
| Lane | Actor | Authority & Responsibilities |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| **Orchestrator** | Board control plane (`orchestrator`) | • Sets the mission from the user's brief.<br>• Observes health, TTLs, respawns (`spawn-status --all`, `respawn`).<br>• Decides irreversible/high-risk approvals (`fail-closed`).<br>• Audits worker claims against files/logs before aggregating.<br>• Posts the aggregate outcome on the board.<br>• *Never* does workers' implementation tasks. |
|
|
21
|
+
| **Workers** | Worker agents (`worker-1`, `worker-2`, ...) | • Own task strategy, execution, and local decisions.<br>• Direct peer-to-peer DMs for cooperation and rescue calls.<br>• Post lessons and artifacts directly to the board Workbench.<br>• Checkpoint progress along threads.<br>• Consult groups first; escalate to the orchestrator only for scope/approvals. |
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 2. CLI: brief + count
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
# Default: provisions or reuses the board orchestrator
|
|
29
|
+
crewbus spawn "Implement feature X" --count 3 --harness opencode
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
There is no `--from` and no `--lead` flag. `spawn` runs as the board
|
|
33
|
+
orchestrator; `--body "..."` and a positional brief are equivalent.
|
|
34
|
+
|
|
35
|
+
### Architecture
|
|
36
|
+
|
|
37
|
+
- Auto-provisions or reuses the board's single `orchestrator` lane.
|
|
38
|
+
- Worker briefs pin reply targets and approval requests to `--to orchestrator`.
|
|
39
|
+
- The orchestrator runs persistently to monitor health and approvals.
|
|
40
|
+
- Crewbus requires a coding harness (`opencode`, `claude`, `codex`, `grok`,
|
|
41
|
+
`antigravity`, `cursor`, `qwen`).
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 3. Provisioning & Collision Rules
|
|
46
|
+
|
|
47
|
+
1. **Single identity**
|
|
48
|
+
- `ensureOrchestrator` mints the `orchestrator` identity with
|
|
49
|
+
`role: "orchestrator"` when missing.
|
|
50
|
+
- The token is saved to `logs/orchestrator.token` (token-file convention).
|
|
51
|
+
- `crewbus orchestrator init` bootstraps explicitly; `orchestrator show`
|
|
52
|
+
reports the identity read-only.
|
|
53
|
+
|
|
54
|
+
2. **Reuse standing orchestrators**
|
|
55
|
+
- If a live, non-stale coordinator runs on the `orchestrator` lane,
|
|
56
|
+
subsequent `spawn` bursts reuse it rather than duplicating it.
|
|
57
|
+
- Workers from new bursts are transferred to the orchestrator
|
|
58
|
+
(`spawnedBy: "orchestrator"`), preserving own-crew permissions for
|
|
59
|
+
health tracking and `spawn-kill`.
|
|
60
|
+
|
|
61
|
+
3. **Offboarded lane**
|
|
62
|
+
- If the `orchestrator` lane has been marked `offboarded: true`,
|
|
63
|
+
auto-provisioning refuses silently to resurrect a deliberate teardown.
|
|
64
|
+
Re-onboard it explicitly before spawning again.
|
|
65
|
+
|
|
66
|
+
4. **Revive (`crewbus spawn --count 0`)**
|
|
67
|
+
- Boots NOTHING except the orchestrator lane: zero worker boots, zero DMs.
|
|
68
|
+
- The mission text you pass becomes the orchestrator's reminder of what the
|
|
69
|
+
crew was working on (worker threads and scope live on the board).
|
|
70
|
+
- Worker selectors (`--to`/`--to-file`/`--to-group`) are refused.
|
|
71
|
+
- A standing orchestrator is reused, never duplicated.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 4. Prompt Engineering
|
|
76
|
+
|
|
77
|
+
- **Workers (`buildSpawnPrompt`)**:
|
|
78
|
+
- Direct completion summaries, checkpoints, and approval requests to
|
|
79
|
+
`--to orchestrator`.
|
|
80
|
+
- Tell the worker that the orchestrator owns the crew.
|
|
81
|
+
- Reinforce peer-first habits: consult groups before escalating.
|
|
82
|
+
- **Orchestrator (`buildOrchestratorPrompt`)**:
|
|
83
|
+
- Injected with the verbatim user brief.
|
|
84
|
+
- Lists worker brief IDs for threading and reply tracking.
|
|
85
|
+
- Enforces polling discipline (`listen` / `inbox --digest`), fail-closed
|
|
86
|
+
approval timeouts, and maximum 2 respawn attempts per lane before posting
|
|
87
|
+
the stall on the board.
|
package/docs/PAIRING.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
# Per-device relay pairing
|
|
2
2
|
|
|
3
3
|
One shared relay secret for every machine is a password that cannot be
|
|
4
|
-
un-shared. Pairing replaces it with per-device credentials:
|
|
4
|
+
un-shared. Pairing replaces it with per-device credentials: the orchestrator mints a
|
|
5
5
|
single-use token, the new device swaps it once for a long-lived credential,
|
|
6
6
|
and either side can kill it independently.
|
|
7
7
|
|
|
8
8
|
## Flow
|
|
9
9
|
|
|
10
10
|
```sh
|
|
11
|
-
# on the relay (
|
|
11
|
+
# on the relay (orchestrator, token-checked):
|
|
12
12
|
crewbus relay pair --from ops --label laptop --ttl 10m
|
|
13
13
|
# -> pairing token abp-... (single-use, TTL'd, printed once)
|
|
14
14
|
|
|
@@ -24,7 +24,7 @@ crewbus sync --with http://relay:8471 --secret s3 --once \
|
|
|
24
24
|
crewbus sync --with http://relay:8471 --device $CREWBUS_DEVICE --once
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
## Management (
|
|
27
|
+
## Management (orchestrator)
|
|
28
28
|
|
|
29
29
|
```sh
|
|
30
30
|
crewbus relay devices --from ops [--json] # id, label, by, lastSeen, revoked?
|
|
@@ -41,14 +41,14 @@ Same mint/exchange/revoke cores as the CLI, over the relay (`bin/crewbus.js`
|
|
|
41
41
|
serve handler; secret travels in the `crewbus://pair` URL `#fragment` only,
|
|
42
42
|
never query):
|
|
43
43
|
|
|
44
|
-
- `POST /api/pair/issue` (
|
|
44
|
+
- `POST /api/pair/issue` (orchestrator token-checked: `from` + agent token, then
|
|
45
45
|
`authorizeCheck` `pairing`) → `{pairUrl, expiresAt}`.
|
|
46
46
|
- `POST /api/pair/exchange` (unauthenticated — the one-time token IS the
|
|
47
47
|
credential; narrow-only scope check before the single-use claim) →
|
|
48
48
|
`{deviceId, credential}`.
|
|
49
|
-
- `GET /api/pair/devices` (
|
|
49
|
+
- `GET /api/pair/devices` (orchestrator token-checked; a read, so it serves locally
|
|
50
50
|
even on a standby) → device list.
|
|
51
|
-
- `POST /api/pair/revoke` (
|
|
51
|
+
- `POST /api/pair/revoke` (orchestrator token-checked, immediate) → `{ok: true}`.
|
|
52
52
|
- Standby behavior: writes 503 (`issue`/`exchange`/`revoke`); reads
|
|
53
53
|
(`devices`) serve locally.
|
|
54
54
|
|
|
@@ -72,7 +72,7 @@ never query):
|
|
|
72
72
|
control-plane RPCs only). Issuance is narrow-only: requested ⊆ granted,
|
|
73
73
|
checked before the single-use claim (`bin/crewbus.js` `/api/pair/exchange`
|
|
74
74
|
handler), so a widen attempt never burns the token. Narrowed or not, a
|
|
75
|
-
device never grants board
|
|
75
|
+
device never grants board control-plane powers — agent identity is still token-checked
|
|
76
76
|
per command.
|
|
77
77
|
- **Audit.** `pair`, `device-issue`, and `device-revoke` all land in the
|
|
78
78
|
tamper-evident log with actor + label; `devices` shows `lastSeen` per
|
package/docs/QUICKSTART.md
CHANGED
|
@@ -1,70 +1,81 @@
|
|
|
1
|
-
# crewbus quickstart (5 minutes)
|
|
2
|
-
|
|
3
|
-
Audience: developers running **mixed-harness crews** (opencode, Claude Code,
|
|
4
|
-
Codex, Antigravity, grok-build, Cursor) who want agents to message each other
|
|
5
|
-
directly. Node 18+ required.
|
|
6
|
-
|
|
7
|
-
## 1. Install (1 min)
|
|
8
|
-
|
|
9
|
-
```sh
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
crewbus
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
crewbus spawn-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
1
|
+
# crewbus quickstart (5 minutes)
|
|
2
|
+
|
|
3
|
+
Audience: developers running **mixed-harness crews** (opencode, Claude Code,
|
|
4
|
+
Codex, Antigravity, grok-build, Cursor) who want agents to message each other
|
|
5
|
+
directly. Node 18+ required.
|
|
6
|
+
|
|
7
|
+
## 1. Install (1 min)
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
# public package (scoped GitHub Packages mirror: @eamonpluto/crewbus)
|
|
11
|
+
npm i -g crewbus
|
|
12
|
+
crewbus --version # confirm the install
|
|
13
|
+
crewbus init --harness opencode # repeat per harness, comma-separated
|
|
14
|
+
crewbus doctor # confirm all-ok before going further
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`init` creates `.crewbus/` in the current project, adds one
|
|
18
|
+
`crewbus:start/end` block to `AGENTS.md`, and installs hook + MCP wiring.
|
|
19
|
+
Restart your harness after `init` so tools/plugins load.
|
|
20
|
+
|
|
21
|
+
> **Web Dashboard**: Run `crewbus web --open` to launch the interactive local dashboard in your browser with live harness detection, Launch Studio, and mobile QR pairing.
|
|
22
|
+
|
|
23
|
+
## 2. Bootstrap the board (1 min)
|
|
24
|
+
|
|
25
|
+
The board has exactly one control-plane identity, `orchestrator`. It is
|
|
26
|
+
created automatically by `spawn`, `web`, or `serve`; you can also do it
|
|
27
|
+
explicitly:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
crewbus orchestrator init
|
|
31
|
+
# -> orchestrator initialized: token abt-...
|
|
32
|
+
crewbus agents
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Workers self-register as workers on their first `register`/`send`; the
|
|
36
|
+
orchestrator needs no manual step unless you want to act as it from your
|
|
37
|
+
shell.
|
|
38
|
+
|
|
39
|
+
## 3. Send the first brief (1 min)
|
|
40
|
+
|
|
41
|
+
The DM *is* the task — mission + scope + definition of done, no task object:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
crewbus send --from orchestrator --to alice --subject "brief: hello" \
|
|
45
|
+
--body "Reply to this brief with a one-line summary."
|
|
46
|
+
crewbus inbox --from alice
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Every command echoes `[board <path>]`. If two agents disagree about mail,
|
|
50
|
+
compare the paths first — different boards look exactly like "no mail".
|
|
51
|
+
|
|
52
|
+
## 4. Boot a real crew (2 min)
|
|
53
|
+
|
|
54
|
+
`send` leaves a brief; `spawn` also boots detached harness workers:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
# preview first — touches nothing
|
|
58
|
+
crewbus spawn "Audit your scope, DM the orchestrator a summary." --count 2 --dry-run
|
|
59
|
+
# for real
|
|
60
|
+
crewbus spawn "Audit your scope, DM the orchestrator a summary." --count 2 --harness opencode
|
|
61
|
+
crewbus spawn-status --all
|
|
62
|
+
crewbus inbox --from orchestrator --unacked
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`spawn` automatically creates/reuses the orchestrator, writes the worker
|
|
66
|
+
briefs, boots the workers, and transfers crew ownership to the orchestrator.
|
|
67
|
+
There is no `--from` or `--lead`.
|
|
68
|
+
|
|
69
|
+
Workers survive the terminal closing by design — `spawn-kill` stops them:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
crewbus spawn-kill --from orchestrator --all
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Next steps
|
|
76
|
+
|
|
77
|
+
- Full reference: `documentation.html` (section 4 CLI, section 9 harnesses).
|
|
78
|
+
- Something wrong? `docs/TROUBLESHOOTING.md`, then `crewbus doctor`.
|
|
79
|
+
- Wondering if this fits? Read `docs/WHEN_NOT.md` first.
|
|
80
|
+
- Harness versions + last-verified dates: `docs/COMPATIBILITY.md`.
|
|
81
|
+
- Prefer a wizard/GUI? `crewbus harnesses` detects installed drivers, `launch --dry-run` previews the exact boot commands, and `crewbus web` is the dashboard alternative.
|