crewbus 10.0.11 → 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 +151 -0
- package/README.md +713 -706
- package/TEAM.template.md +1 -1
- package/bin/crewbus-hook.js +22 -5
- package/bin/crewbus-mcp.js +56 -48
- package/bin/crewbus.js +486 -355
- 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 +92 -152
- package/bin/lib/launch.js +128 -30
- package/bin/lib/qrcode.js +2971 -0
- package/bin/lib/relay.js +26 -54
- package/bin/lib/spawn.js +241 -194
- package/bin/lib/store.js +2 -2
- package/bin/lib/web.js +277 -59
- 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 +120 -120
- package/docs/COMPATIBILITY.md +196 -194
- package/docs/CONSOLIDATOR.md +6 -6
- package/docs/CONTROL_PLANE_SPEC.md +12 -14
- package/docs/CREWS.md +16 -13
- package/docs/DELIVERY.md +213 -210
- package/docs/GROUPS.md +8 -8
- package/docs/HA.md +151 -151
- package/docs/IDENTITY.md +6 -6
- package/docs/LEAD_ASSIGN.md +3 -85
- package/docs/LONG_RUNS.md +3 -3
- package/docs/M1_CLI_DRAFT.md +9 -9
- package/docs/ORCHESTRATOR.md +87 -0
- package/docs/PAIRING.md +7 -7
- package/docs/QUICKSTART.md +24 -13
- package/docs/RBAC.md +84 -73
- package/docs/SPLIT.md +82 -82
- package/docs/TENANCY.md +10 -10
- package/docs/THREAT_MODEL.md +68 -69
- package/docs/VERIFIER.md +10 -10
- package/docs/VERSION_SKEW.md +57 -57
- package/documentation.html +37 -29
- package/examples/hermes-pairing.md +3 -3
- package/examples/t3-pairing.md +1 -1
- package/index.html +13 -14
- package/opencode/plugins/dm-watch.js +1 -1
- package/opencode/tools/dm-send.js +4 -13
- package/package.json +75 -50
- package/packages/client-runtime/README.md +40 -40
- package/packages/contracts/harness.json +108 -111
- package/packages/contracts/launch.json +2 -3
- package/packages/contracts/pairing.json +3 -3
- package/docs/DESKTOP_SPIKE.md +0 -223
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
|
@@ -7,7 +7,9 @@ directly. Node 18+ required.
|
|
|
7
7
|
## 1. Install (1 min)
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
|
+
# public package (scoped GitHub Packages mirror: @eamonpluto/crewbus)
|
|
10
11
|
npm i -g crewbus
|
|
12
|
+
crewbus --version # confirm the install
|
|
11
13
|
crewbus init --harness opencode # repeat per harness, comma-separated
|
|
12
14
|
crewbus doctor # confirm all-ok before going further
|
|
13
15
|
```
|
|
@@ -16,25 +18,30 @@ crewbus doctor # confirm all-ok before going further
|
|
|
16
18
|
`crewbus:start/end` block to `AGENTS.md`, and installs hook + MCP wiring.
|
|
17
19
|
Restart your harness after `init` so tools/plugins load.
|
|
18
20
|
|
|
19
|
-
> **
|
|
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.
|
|
20
22
|
|
|
21
|
-
## 2.
|
|
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:
|
|
22
28
|
|
|
23
29
|
```sh
|
|
24
|
-
crewbus
|
|
25
|
-
|
|
30
|
+
crewbus orchestrator init
|
|
31
|
+
# -> orchestrator initialized: token abt-...
|
|
26
32
|
crewbus agents
|
|
27
33
|
```
|
|
28
34
|
|
|
29
|
-
|
|
30
|
-
|
|
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.
|
|
31
38
|
|
|
32
39
|
## 3. Send the first brief (1 min)
|
|
33
40
|
|
|
34
41
|
The DM *is* the task — mission + scope + definition of done, no task object:
|
|
35
42
|
|
|
36
43
|
```sh
|
|
37
|
-
crewbus send --from
|
|
44
|
+
crewbus send --from orchestrator --to alice --subject "brief: hello" \
|
|
38
45
|
--body "Reply to this brief with a one-line summary."
|
|
39
46
|
crewbus inbox --from alice
|
|
40
47
|
```
|
|
@@ -48,17 +55,21 @@ compare the paths first — different boards look exactly like "no mail".
|
|
|
48
55
|
|
|
49
56
|
```sh
|
|
50
57
|
# preview first — touches nothing
|
|
51
|
-
crewbus spawn
|
|
52
|
-
# for real
|
|
53
|
-
crewbus spawn
|
|
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
|
|
54
61
|
crewbus spawn-status --all
|
|
55
|
-
crewbus inbox --from
|
|
62
|
+
crewbus inbox --from orchestrator --unacked
|
|
56
63
|
```
|
|
57
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
|
+
|
|
58
69
|
Workers survive the terminal closing by design — `spawn-kill` stops them:
|
|
59
70
|
|
|
60
71
|
```sh
|
|
61
|
-
crewbus spawn-kill --from
|
|
72
|
+
crewbus spawn-kill --from orchestrator --all
|
|
62
73
|
```
|
|
63
74
|
|
|
64
75
|
## Next steps
|
|
@@ -67,4 +78,4 @@ crewbus spawn-kill --from lead --all
|
|
|
67
78
|
- Something wrong? `docs/TROUBLESHOOTING.md`, then `crewbus doctor`.
|
|
68
79
|
- Wondering if this fits? Read `docs/WHEN_NOT.md` first.
|
|
69
80
|
- Harness versions + last-verified dates: `docs/COMPATIBILITY.md`.
|
|
70
|
-
- Prefer a wizard/GUI? `crewbus harnesses` detects installed drivers, `launch --dry-run` previews the exact boot commands, and `crewbus web` is the dashboard alternative.
|
|
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.
|
package/docs/RBAC.md
CHANGED
|
@@ -1,73 +1,84 @@
|
|
|
1
|
-
# RBAC + per-board ACLs + group-scoped send permissions
|
|
2
|
-
|
|
3
|
-
Zero-dependency, file-local. Composes with
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
## Roles
|
|
9
|
-
|
|
10
|
-
Agent records carry `role` in `{
|
|
11
|
-
|
|
12
|
-
-
|
|
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
|
-
- Relay: `POST /api/spawn
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
`
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
- `
|
|
62
|
-
|
|
63
|
-
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
1
|
+
# RBAC + per-board ACLs + group-scoped send permissions
|
|
2
|
+
|
|
3
|
+
Zero-dependency, file-local. Composes with tokens: `checkToken()` proves WHO
|
|
4
|
+
you are; `authorize()` decides WHAT your role may do. `authorize()` is a
|
|
5
|
+
SEPARATE function called AFTER `checkToken()` passes — never before, never
|
|
6
|
+
instead, never merged into token code.
|
|
7
|
+
|
|
8
|
+
## Roles
|
|
9
|
+
|
|
10
|
+
Agent records carry `role` in `{orchestrator, worker}`.
|
|
11
|
+
|
|
12
|
+
- **orchestrator** — the board's single control-plane identity. It owns the
|
|
13
|
+
crew: spawn/respawn/kill, approvals, verification, groups, channels, ACLs,
|
|
14
|
+
pairing, and every worker action. `spawn` (and `web`/`serve`) bootstrap it
|
|
15
|
+
automatically as the agent named `orchestrator`, with its token at
|
|
16
|
+
`logs/orchestrator.token`.
|
|
17
|
+
- **worker** — the data plane. Send/inbox/ack/redeliver/lock, artifacts,
|
|
18
|
+
lessons, member-scoped channel posts, and reads. No control-plane actions.
|
|
19
|
+
- Every self-registering agent is a **worker**. Only
|
|
20
|
+
`ensureOrchestrator`/`crewbus orchestrator init` mints the orchestrator.
|
|
21
|
+
- Records with any other or missing role are treated as **worker** (an
|
|
22
|
+
unknown role can never gain control-plane powers).
|
|
23
|
+
|
|
24
|
+
## Permission matrix
|
|
25
|
+
|
|
26
|
+
| action | orchestrator | worker |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| send / inbox / ack / redeliver / lock (scoped) | yes | yes |
|
|
29
|
+
| spawn / respawn / pool / spawn-kill / group manage / result record / race close | yes | NO |
|
|
30
|
+
| channel post | yes (anywhere) | members-only: the channel's own group (`grp-<group>` where the caller is a member) |
|
|
31
|
+
| launch (same RBAC + audit as spawn) | yes | NO |
|
|
32
|
+
| relay pair issue / devices / revoke (`pairing`) | yes | NO |
|
|
33
|
+
| prune / acl set / role-grant / offboard / group restrict / serve `--allow-remote-spawn` / import / snapshot / quota / legal hold | yes | NO |
|
|
34
|
+
| reads (gather / thread / log / channel tail / group show / result show / spawn-status / agents / hold status) | yes | yes |
|
|
35
|
+
|
|
36
|
+
Notes:
|
|
37
|
+
|
|
38
|
+
- Reads not listed above default-allow (fail-closed only for writes).
|
|
39
|
+
- `spawn-kill` is orchestrator-only; the orchestrator owns every crew.
|
|
40
|
+
- `lock release` still requires ownership even when acquire is allowed.
|
|
41
|
+
- MCP twins: `dm_send`→`send`, `dm_inbox`→`inbox`, `dm_ack`→`ack`,
|
|
42
|
+
`dm_channel_post`→`channel-post` (member-scoped like the CLI),
|
|
43
|
+
`dm_gather`/`dm_channel_tail` are identity-less reads.
|
|
44
|
+
- Relay: `POST /api/spawn`→`spawn`, `POST /api/launch`→`spawn`,
|
|
45
|
+
`POST /api/kill`→`spawn-kill` (403 on denial); pair endpoints→`pairing`.
|
|
46
|
+
Remote control-plane actions run as the relay board's orchestrator; the
|
|
47
|
+
relay secret or a device credential with `launch:spawn` is the auth
|
|
48
|
+
boundary.
|
|
49
|
+
- Device-scope layer: transport credential scopes (`requireScope` in
|
|
50
|
+
`bin/lib/relay.js`) compose UNDER role checks — a narrowed device can only
|
|
51
|
+
further restrict, never widen, what the agent token's role allows.
|
|
52
|
+
- `prune` and `group create/add/remove` keep the bare operator path (no
|
|
53
|
+
`--from`) open; with `--from` the caller is token-checked and authorized.
|
|
54
|
+
`serve --allow-remote-spawn` with `--from` requires the orchestrator.
|
|
55
|
+
|
|
56
|
+
## Per-board ACLs
|
|
57
|
+
|
|
58
|
+
`board.json` gains `acl: {defaultRole, frozen?}`.
|
|
59
|
+
|
|
60
|
+
- `acl set --from orchestrator [--default-role worker] [--freeze|--unfreeze]`
|
|
61
|
+
(orchestrator-only). `acl show [--json]` is read-only.
|
|
62
|
+
- Every new registration is a worker; `defaultRole` stays `worker`.
|
|
63
|
+
- Frozen boards refuse new registrations (including first-send auto-mint),
|
|
64
|
+
except by orchestrator grant (`register --from orchestrator --for <new>`).
|
|
65
|
+
|
|
66
|
+
## Group-scoped send permissions
|
|
67
|
+
|
|
68
|
+
- `group restrict <name> --from orchestrator` sets `restricted: true`
|
|
69
|
+
(`group unrestrict` clears it). Orchestrator-only. The flag survives
|
|
70
|
+
member edits.
|
|
71
|
+
- Sends with `--to-group` (or `to_group` / relay `to_group`) to a restricted
|
|
72
|
+
group are refused unless the caller is the orchestrator or a group member.
|
|
73
|
+
- Pattern: curate a private crew (`group create elite --add a,b`), then
|
|
74
|
+
`group restrict elite --from orchestrator`; outsiders get a loud refusal,
|
|
75
|
+
members + the orchestrator keep working.
|
|
76
|
+
|
|
77
|
+
## Bootstrap and migration
|
|
78
|
+
|
|
79
|
+
- Fresh boards: `spawn`, `web`, or `serve` ensure the orchestrator; or run
|
|
80
|
+
`crewbus orchestrator init` explicitly (prints the token once).
|
|
81
|
+
- Existing boards with roles outside `{orchestrator, worker}` are treated as
|
|
82
|
+
worker-only; mint the orchestrator with `crewbus orchestrator init`.
|
|
83
|
+
- `crewbus orchestrator show` reports the identity, live pid, and token path
|
|
84
|
+
without booting anything.
|
package/docs/SPLIT.md
CHANGED
|
@@ -1,82 +1,82 @@
|
|
|
1
|
-
# Split: `bin/crewbus.js` → `bin/lib/*.js`
|
|
2
|
-
|
|
3
|
-
Status: landed. `bin/crewbus.js` is a dispatcher that intentionally
|
|
4
|
-
retains the `cmd*` wrappers, `USAGE`, `main()`, and the opencode
|
|
5
|
-
tool/plugin embeds; domain logic lives in the 13 lib modules
|
|
6
|
-
(`bin/lib/` holds channels, export, groups, identity, launch, mail,
|
|
7
|
-
relay, spawn, store, sync, tokenfile, web, workbench; import block,
|
|
8
|
-
`bin/crewbus.js` lines 44–56). No behavior change is intended, with one deliberate exception recorded in CHANGELOG (parseRecipients full-version canonicalization).
|
|
9
|
-
|
|
10
|
-
## Module map
|
|
11
|
-
|
|
12
|
-
| File | Responsibility (per file header) | Key exports |
|
|
13
|
-
|---|---|---|
|
|
14
|
-
| `bin/lib/store.js` | Board filesystem layer: constants, board resolution, JSON IO, `clean*` validators, HLC | `BOARD_VERSION`, `MAX_BODY_CHARS`, `MAX_RECIPIENTS`, `MAX_SPAWN`, `BROADCAST_AFTER`, `boardDir`, `dirs`, `ensureBoard`, `readJson`, `writeJson`, `writeExclusiveJson`, `clean*` (`cleanSubject`, `cleanGroupName`, `cleanChannelName`, `cleanWebName`, …), `nextHlc`, `stampSyncDoc`, `hlcCompare` |
|
|
15
|
-
| `bin/lib/identity.js` | Tokens + RBAC: mint/verify, salted hashes, ACLs, `authorize` | `mintToken`, `hashToken`, `checkToken`, `ensureSender`, `sanitizeAgentForSync`, `mergeSyncedAgent`, `VALID_ROLES`, `authorize`, `authorizeCheck`, `authorizeThrow`, `touchAgent` |
|
|
16
|
-
| `bin/lib/sync.js` | Sync engine + outbound client: union-by-id merge, HLC LWW, tombstones, per-peer cursors | `SYNC_SUBS`, `SYNC_UNION`, `SYNC_LWW`, `syncRound`, `syncWalk`, `httpJson`, `relayAuthEntries`, `crewSurvey`, `splitByWeight`, `readSyncState`, `tombstoneIdForRel` |
|
|
17
|
-
| `bin/lib/relay.js` | Relay serve-side: secrets, device/pairing creds, OIDC, remote spawn/kill cores, per-call device scope gate | `relaySecretFromArgs`, `requireRelaySecret`, `requireRelayClientCert`, `readRelayState`, `tryAcquireFence`, `remoteSpawn`, `newPairToken`, `newDeviceCred`, `verifyOidcJwt`, `requireScope` |
|
|
18
|
-
| `bin/lib/spawn.js` | Worker boot / spawn: prompts, harness targets, env scrub, pid liveness | `bootWorker`, `buildSpawnPrompt`, `buildSpawnTarget`, `scrubChildEnv`, `parseAllowEnv`, `workerStatus`, `pidAlive`, `killWorkers`, `provisionWorktree`, `provisionBranch` |
|
|
19
|
-
| `bin/lib/launch.js` | Launch planning + harness detect + pair-URL helpers; pure helpers only, monolith keeps cmd wrappers | `LAUNCH_PERMISSIONS`, `LAUNCH_LIFETIMES`, `LAUNCH_PRIORITIES`, `PAIR_SCOPES`, `LAUNCH_DRIVER_FALLBACK`, `launchDrivers`, `probeBinary`, `detectHarnessBinaries`, `validateLaunchPlan`, `buildPairUrl`, `advertiseEnv` |
|
|
20
|
-
| `bin/lib/export.js` | Backup/restore/quotas/storage + audit chain + legal hold | `doExportToFile`, `collectBoardFiles`, `encryptBackupPayload`, `decryptBackupPayload`, `readBoardQuotas`, `enforce*Quota`, `holdActive`, `readHold`, `appendChainRecord`, `verifyChainRecords`, `spoolAuditEvent`, `snapshotStamp` |
|
|
21
|
-
| `bin/lib/mail.js` | DMs + delivery: send-path expansion, broadcast manifest, visible reads, digest, ack, verifier, thread/prune/listen/redeliver cores | `deliverDMs`, `readDMs`, `readVisible`, `parseRecipients`, `recordBroadcastManifest`, `ackedIds`, `runVerifier`, `signMessage`, `verifyMessageSig`, `checkSendRateLimit` |
|
|
22
|
-
| `bin/lib/groups.js` | Groups + outcomes: group docs, expansion, telemetry, batch gather, results, races | `readGroup`, `expandGroups`, `expandGroupsOrFail`, `collectBatch`, `groupTelemetryData`, `gatherTelemetry`, `readResultRecord`, `writeResultRecord`, `findFirstVerifiedReply` |
|
|
23
|
-
| `bin/lib/channels.js` | Shared channels + locks: log IO, per-reader cursors, digest/summarize, group mirrors, advisory locks, channel text-merge | `appendChannelPost`, `readChannelPosts`, `tailChannelPosts`, `parseChannelText`, `mergeChannelText`, `mirrorToGroupChannels`, `acquireLockDoc`, `releaseLockDoc` |
|
|
24
|
-
| `bin/lib/web.js` | Dashboard + API: snapshots, HTML render, ack/kill/launch handlers, `cmdWeb`; control-plane additions: `handleApiLaunch`, `POST /api/launch`, `GET /api/harnesses\|routes\|holds\|quotas`, Holds/Quotas/AppRoot sections | `boardSnapshot`, `fleetSnapshot`, `channelsSnapshot`, `resultsSnapshot`, `auditSnapshot`, `renderBoardHtml`, `handleApiAck`, `handleApiKill`, `handleApiLaunch`, `cmdWeb` |
|
|
25
|
-
| `bin/lib/tokenfile.js` | Token-file convention for long runs: save/re-read agent tokens across compaction/restart amnesia (0600 best-effort); standalone, no local imports (cycle-free) | `tokenFilePath`, `saveTokenFile`, `loadTokenFile` |
|
|
26
|
-
| `bin/lib/workbench.js` | Artifacts + lessons (compound-memory layer): artifact objects with deps/adoption/verification edges, scoped lessons, spawn-brief Workbench block, gather metrics; pure helpers, monolith keeps `cmdArtifact`/`cmdLesson` | `publishArtifact`, `adoptArtifact`, `verifyArtifact`, `readArtifactById`, `listArtifacts`, `listLessons`, `postLesson`, `selectLessons`, `renderWorkbenchBlock`, `workbenchMetrics`, `cleanArtifactId`, `cleanLessonScope`, `parseArtifactDeps`, `ARTIFACT_ID_RE` |
|
|
27
|
-
|
|
28
|
-
Full export lists: see the import block at the top of `bin/crewbus.js`
|
|
29
|
-
(lines 44–56). Entry-point `cmd*` functions (e.g. `cmdSend`, `cmdSync`,
|
|
30
|
-
`cmdServe`) stay in the monolith; lib modules carry the computation helpers
|
|
31
|
-
those verbs call.
|
|
32
|
-
|
|
33
|
-
## Dependency rules
|
|
34
|
-
|
|
35
|
-
- `store` ← everyone. All lib modules may import from `store.js`; `store.js`
|
|
36
|
-
imports only node builtins.
|
|
37
|
-
- Top-level side-effect-free: every `bin/lib/*.js` module must contain only
|
|
38
|
-
imports + consts + function declarations at top level — no top-level I/O
|
|
39
|
-
or calls — so import evaluation order is never hazardous.
|
|
40
|
-
- Deferred-call cycles allowed (safe only because tops are side-effect-free
|
|
41
|
-
and every cross-module use is inside function bodies, never at import
|
|
42
|
-
time):
|
|
43
|
-
- `identity` ↔ `groups` via `mail` (`identity.js` imports `readGroup`
|
|
44
|
-
from `groups.js`; `groups.js` imports `readDMs`/`findMessageById` from
|
|
45
|
-
`mail.js`; `mail.js` imports `writeAgentFile` from `identity.js`).
|
|
46
|
-
- `sync` ↔ `relay` (`sync.js` imports `parseDeviceCred` from `relay.js`;
|
|
47
|
-
`relay.js` imports `httpJson` from `sync.js`).
|
|
48
|
-
- Canonical homes for duplicated helpers (keep exactly one; delete the rest
|
|
49
|
-
in favor of these):
|
|
50
|
-
- `clean*` validators → `store.js`.
|
|
51
|
-
- Channel text merge (`parseChannelText`, `mergeChannelText`) →
|
|
52
|
-
`channels.js` (`sync.js` imports them from there).
|
|
53
|
-
- `handleApiKill` → `web.js` (dedup done — `relay.js` re-exports
|
|
54
|
-
`handleApiKill` from `web.js`).
|
|
55
|
-
- HLC (`nextHlc`, `stampSyncDoc`, `hlcCompare`) → `store.js`.
|
|
56
|
-
- Out-of-monolith surfaces: `packages/client-runtime/` (shared retry/route/auth/cache core for desktop/mobile shells) and `apps/
|
|
57
|
-
|
|
58
|
-
## How to add a command
|
|
59
|
-
|
|
60
|
-
1. Add the `cmd*` wrapper + `main()` switch case (+ `USAGE` text) in
|
|
61
|
-
`bin/crewbus.js` (dispatcher owns CLI parsing and flag handling).
|
|
62
|
-
2. Put reusable logic in the owning `bin/lib/*.js` module (table above);
|
|
63
|
-
keep the new lib code side-effect-free at top level.
|
|
64
|
-
3. Add tests under `test/` covering the new path (`npm test` runs
|
|
65
|
-
`test/crewbus.*.mjs` — smoke, harness, compact, tokenfile, digest,
|
|
66
|
-
control-plane, launch, web-launch, pair-api, web-panel, web-approot,
|
|
67
|
-
client-runtime, runtime-wiring,
|
|
68
|
-
grok-hooks, holds-quotas, approval-protocol, approvals-init,
|
|
69
|
-
approvals-web — plus `test/fault-injection.mjs` + `test/integration.mjs`;
|
|
70
|
-
see root `package.json` `scripts.test`).
|
|
71
|
-
|
|
72
|
-
## Embeds note
|
|
73
|
-
|
|
74
|
-
The `OPENCODE_TOOL_DM_SEND` / `OPENCODE_PLUGIN_DM_WATCH` template literals
|
|
75
|
-
stay in `bin/crewbus.js` (populated from `opencode/tools/dm-send.js` +
|
|
76
|
-
`opencode/plugins/dm-watch.js`). `sync-embeds.mjs` is unaffected by this
|
|
77
|
-
split — keep running `node sync-embeds.mjs --check` after edits.
|
|
78
|
-
|
|
79
|
-
## MCP note
|
|
80
|
-
|
|
81
|
-
`bin/crewbus-mcp.js` is still standalone (own copies, no `bin/lib/*`
|
|
82
|
-
imports). Sharing lib modules with the MCP server is future work, NOT done.
|
|
1
|
+
# Split: `bin/crewbus.js` → `bin/lib/*.js`
|
|
2
|
+
|
|
3
|
+
Status: landed. `bin/crewbus.js` is a dispatcher that intentionally
|
|
4
|
+
retains the `cmd*` wrappers, `USAGE`, `main()`, and the opencode
|
|
5
|
+
tool/plugin embeds; domain logic lives in the 13 lib modules
|
|
6
|
+
(`bin/lib/` holds channels, export, groups, identity, launch, mail,
|
|
7
|
+
relay, spawn, store, sync, tokenfile, web, workbench; import block,
|
|
8
|
+
`bin/crewbus.js` lines 44–56). No behavior change is intended, with one deliberate exception recorded in CHANGELOG (parseRecipients full-version canonicalization).
|
|
9
|
+
|
|
10
|
+
## Module map
|
|
11
|
+
|
|
12
|
+
| File | Responsibility (per file header) | Key exports |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| `bin/lib/store.js` | Board filesystem layer: constants, board resolution, JSON IO, `clean*` validators, HLC | `BOARD_VERSION`, `MAX_BODY_CHARS`, `MAX_RECIPIENTS`, `MAX_SPAWN`, `BROADCAST_AFTER`, `boardDir`, `dirs`, `ensureBoard`, `readJson`, `writeJson`, `writeExclusiveJson`, `clean*` (`cleanSubject`, `cleanGroupName`, `cleanChannelName`, `cleanWebName`, …), `nextHlc`, `stampSyncDoc`, `hlcCompare` |
|
|
15
|
+
| `bin/lib/identity.js` | Tokens + RBAC: mint/verify, salted hashes, ACLs, `authorize` | `mintToken`, `hashToken`, `checkToken`, `ensureSender`, `sanitizeAgentForSync`, `mergeSyncedAgent`, `VALID_ROLES`, `authorize`, `authorizeCheck`, `authorizeThrow`, `touchAgent` |
|
|
16
|
+
| `bin/lib/sync.js` | Sync engine + outbound client: union-by-id merge, HLC LWW, tombstones, per-peer cursors | `SYNC_SUBS`, `SYNC_UNION`, `SYNC_LWW`, `syncRound`, `syncWalk`, `httpJson`, `relayAuthEntries`, `crewSurvey`, `splitByWeight`, `readSyncState`, `tombstoneIdForRel` |
|
|
17
|
+
| `bin/lib/relay.js` | Relay serve-side: secrets, device/pairing creds, OIDC, remote spawn/kill cores, per-call device scope gate | `relaySecretFromArgs`, `requireRelaySecret`, `requireRelayClientCert`, `readRelayState`, `tryAcquireFence`, `remoteSpawn`, `newPairToken`, `newDeviceCred`, `verifyOidcJwt`, `requireScope` |
|
|
18
|
+
| `bin/lib/spawn.js` | Worker boot / spawn: prompts, harness targets, env scrub, pid liveness | `bootWorker`, `buildSpawnPrompt`, `buildSpawnTarget`, `scrubChildEnv`, `parseAllowEnv`, `workerStatus`, `pidAlive`, `killWorkers`, `provisionWorktree`, `provisionBranch` |
|
|
19
|
+
| `bin/lib/launch.js` | Launch planning + harness detect + pair-URL helpers; pure helpers only, monolith keeps cmd wrappers | `LAUNCH_PERMISSIONS`, `LAUNCH_LIFETIMES`, `LAUNCH_PRIORITIES`, `PAIR_SCOPES`, `LAUNCH_DRIVER_FALLBACK`, `launchDrivers`, `probeBinary`, `detectHarnessBinaries`, `validateLaunchPlan`, `buildPairUrl`, `advertiseEnv` |
|
|
20
|
+
| `bin/lib/export.js` | Backup/restore/quotas/storage + audit chain + legal hold | `doExportToFile`, `collectBoardFiles`, `encryptBackupPayload`, `decryptBackupPayload`, `readBoardQuotas`, `enforce*Quota`, `holdActive`, `readHold`, `appendChainRecord`, `verifyChainRecords`, `spoolAuditEvent`, `snapshotStamp` |
|
|
21
|
+
| `bin/lib/mail.js` | DMs + delivery: send-path expansion, broadcast manifest, visible reads, digest, ack, verifier, thread/prune/listen/redeliver cores | `deliverDMs`, `readDMs`, `readVisible`, `parseRecipients`, `recordBroadcastManifest`, `ackedIds`, `runVerifier`, `signMessage`, `verifyMessageSig`, `checkSendRateLimit` |
|
|
22
|
+
| `bin/lib/groups.js` | Groups + outcomes: group docs, expansion, telemetry, batch gather, results, races | `readGroup`, `expandGroups`, `expandGroupsOrFail`, `collectBatch`, `groupTelemetryData`, `gatherTelemetry`, `readResultRecord`, `writeResultRecord`, `findFirstVerifiedReply` |
|
|
23
|
+
| `bin/lib/channels.js` | Shared channels + locks: log IO, per-reader cursors, digest/summarize, group mirrors, advisory locks, channel text-merge | `appendChannelPost`, `readChannelPosts`, `tailChannelPosts`, `parseChannelText`, `mergeChannelText`, `mirrorToGroupChannels`, `acquireLockDoc`, `releaseLockDoc` |
|
|
24
|
+
| `bin/lib/web.js` | Dashboard + API: snapshots, HTML render, ack/kill/launch handlers, `cmdWeb`; control-plane additions: `handleApiLaunch`, `POST /api/launch`, `GET /api/harnesses\|routes\|holds\|quotas`, Holds/Quotas/AppRoot sections | `boardSnapshot`, `fleetSnapshot`, `channelsSnapshot`, `resultsSnapshot`, `auditSnapshot`, `renderBoardHtml`, `handleApiAck`, `handleApiKill`, `handleApiLaunch`, `cmdWeb` |
|
|
25
|
+
| `bin/lib/tokenfile.js` | Token-file convention for long runs: save/re-read agent tokens across compaction/restart amnesia (0600 best-effort); standalone, no local imports (cycle-free) | `tokenFilePath`, `saveTokenFile`, `loadTokenFile` |
|
|
26
|
+
| `bin/lib/workbench.js` | Artifacts + lessons (compound-memory layer): artifact objects with deps/adoption/verification edges, scoped lessons, spawn-brief Workbench block, gather metrics; pure helpers, monolith keeps `cmdArtifact`/`cmdLesson` | `publishArtifact`, `adoptArtifact`, `verifyArtifact`, `readArtifactById`, `listArtifacts`, `listLessons`, `postLesson`, `selectLessons`, `renderWorkbenchBlock`, `workbenchMetrics`, `cleanArtifactId`, `cleanLessonScope`, `parseArtifactDeps`, `ARTIFACT_ID_RE` |
|
|
27
|
+
|
|
28
|
+
Full export lists: see the import block at the top of `bin/crewbus.js`
|
|
29
|
+
(lines 44–56). Entry-point `cmd*` functions (e.g. `cmdSend`, `cmdSync`,
|
|
30
|
+
`cmdServe`) stay in the monolith; lib modules carry the computation helpers
|
|
31
|
+
those verbs call.
|
|
32
|
+
|
|
33
|
+
## Dependency rules
|
|
34
|
+
|
|
35
|
+
- `store` ← everyone. All lib modules may import from `store.js`; `store.js`
|
|
36
|
+
imports only node builtins.
|
|
37
|
+
- Top-level side-effect-free: every `bin/lib/*.js` module must contain only
|
|
38
|
+
imports + consts + function declarations at top level — no top-level I/O
|
|
39
|
+
or calls — so import evaluation order is never hazardous.
|
|
40
|
+
- Deferred-call cycles allowed (safe only because tops are side-effect-free
|
|
41
|
+
and every cross-module use is inside function bodies, never at import
|
|
42
|
+
time):
|
|
43
|
+
- `identity` ↔ `groups` via `mail` (`identity.js` imports `readGroup`
|
|
44
|
+
from `groups.js`; `groups.js` imports `readDMs`/`findMessageById` from
|
|
45
|
+
`mail.js`; `mail.js` imports `writeAgentFile` from `identity.js`).
|
|
46
|
+
- `sync` ↔ `relay` (`sync.js` imports `parseDeviceCred` from `relay.js`;
|
|
47
|
+
`relay.js` imports `httpJson` from `sync.js`).
|
|
48
|
+
- Canonical homes for duplicated helpers (keep exactly one; delete the rest
|
|
49
|
+
in favor of these):
|
|
50
|
+
- `clean*` validators → `store.js`.
|
|
51
|
+
- Channel text merge (`parseChannelText`, `mergeChannelText`) →
|
|
52
|
+
`channels.js` (`sync.js` imports them from there).
|
|
53
|
+
- `handleApiKill` → `web.js` (dedup done — `relay.js` re-exports
|
|
54
|
+
`handleApiKill` from `web.js`).
|
|
55
|
+
- HLC (`nextHlc`, `stampSyncDoc`, `hlcCompare`) → `store.js`.
|
|
56
|
+
- Out-of-monolith surfaces: `packages/client-runtime/` (shared retry/route/auth/cache core for desktop/mobile shells) and `apps/mobile` consume `bin/` over HTTP (sidecar/spawn + dashboard fetch), never import it.
|
|
57
|
+
|
|
58
|
+
## How to add a command
|
|
59
|
+
|
|
60
|
+
1. Add the `cmd*` wrapper + `main()` switch case (+ `USAGE` text) in
|
|
61
|
+
`bin/crewbus.js` (dispatcher owns CLI parsing and flag handling).
|
|
62
|
+
2. Put reusable logic in the owning `bin/lib/*.js` module (table above);
|
|
63
|
+
keep the new lib code side-effect-free at top level.
|
|
64
|
+
3. Add tests under `test/` covering the new path (`npm test` runs
|
|
65
|
+
`test/crewbus.*.mjs` — smoke, harness, compact, tokenfile, digest,
|
|
66
|
+
control-plane, launch, web-launch, pair-api, web-panel, web-approot,
|
|
67
|
+
client-runtime, runtime-wiring, mobile-client,
|
|
68
|
+
grok-hooks, holds-quotas, approval-protocol, approvals-init,
|
|
69
|
+
approvals-web — plus `test/fault-injection.mjs` + `test/integration.mjs`;
|
|
70
|
+
see root `package.json` `scripts.test`).
|
|
71
|
+
|
|
72
|
+
## Embeds note
|
|
73
|
+
|
|
74
|
+
The `OPENCODE_TOOL_DM_SEND` / `OPENCODE_PLUGIN_DM_WATCH` template literals
|
|
75
|
+
stay in `bin/crewbus.js` (populated from `opencode/tools/dm-send.js` +
|
|
76
|
+
`opencode/plugins/dm-watch.js`). `sync-embeds.mjs` is unaffected by this
|
|
77
|
+
split — keep running `node sync-embeds.mjs --check` after edits.
|
|
78
|
+
|
|
79
|
+
## MCP note
|
|
80
|
+
|
|
81
|
+
`bin/crewbus-mcp.js` is still standalone (own copies, no `bin/lib/*`
|
|
82
|
+
imports). Sharing lib modules with the MCP server is future work, NOT done.
|
package/docs/TENANCY.md
CHANGED
|
@@ -11,7 +11,7 @@ inboxes, no tenant-aware routing — a board IS the tenant boundary.
|
|
|
11
11
|
access to the board files can read everything on that board (tokens stop
|
|
12
12
|
CLI-level `--from` spoofing, not local file tampering) — separate
|
|
13
13
|
directories per trust zone.
|
|
14
|
-
- Name the tenant: `quota set --from
|
|
14
|
+
- Name the tenant: `quota set --from orchestrator --tenant acme` stores
|
|
15
15
|
`tenant: "acme"` in `board.json`. `quota show` and `storage --json`
|
|
16
16
|
report it. It is a label, not an enforcement mechanism; the directory
|
|
17
17
|
is the enforcement.
|
|
@@ -21,10 +21,10 @@ inboxes, no tenant-aware routing — a board IS the tenant boundary.
|
|
|
21
21
|
`board export` is the tenant-move vehicle:
|
|
22
22
|
|
|
23
23
|
```
|
|
24
|
-
# on board A (
|
|
25
|
-
crewbus board export --from
|
|
24
|
+
# on board A (orchestrator)
|
|
25
|
+
crewbus board export --from orchestrator --out ./acme.abbackup.json
|
|
26
26
|
# creates board B
|
|
27
|
-
crewbus board import --from
|
|
27
|
+
crewbus board import --from orchestrator --in ./acme.abbackup.json --into <dir-B> --force
|
|
28
28
|
```
|
|
29
29
|
|
|
30
30
|
Exports are encrypted with AES-256-GCM (key = 32-byte hex/base64 used raw,
|
|
@@ -40,28 +40,28 @@ warning, encrypt the file, store it like a password).
|
|
|
40
40
|
unlimited).
|
|
41
41
|
|
|
42
42
|
```
|
|
43
|
-
crewbus quota set --from
|
|
44
|
-
crewbus quota set --from
|
|
45
|
-
crewbus quota set --from
|
|
43
|
+
crewbus quota set --from orchestrator --max-bytes 10mb --max-agents 50 --max-channels 20
|
|
44
|
+
crewbus quota set --from orchestrator --max-bytes unlimited # clear one
|
|
45
|
+
crewbus quota set --from orchestrator --clear # clear all
|
|
46
46
|
crewbus quota show [--json]
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
Enforcement is check-then-write, best-effort (races under parallel writers
|
|
50
50
|
may overshoot; the single-writer case refuses loudly BEFORE the write):
|
|
51
51
|
|
|
52
|
-
- `register` (including
|
|
52
|
+
- `register` (including orchestrator grants) refuses new identities at `maxAgents`
|
|
53
53
|
(re-registering an existing name never counts as new).
|
|
54
54
|
- `send` refuses when the estimated new mail would push total board bytes
|
|
55
55
|
past `maxBytes`.
|
|
56
56
|
- `channel post` refuses on `maxBytes`; `channel create` refuses at
|
|
57
57
|
`maxChannels`.
|
|
58
|
-
- `quota-set` is
|
|
58
|
+
- `quota-set` is orchestrator-only; `quota show` and `storage [--json]` are reads
|
|
59
59
|
(`storage --json` reports `quotas`/`tenant`/`quota` limit-vs-actual).
|
|
60
60
|
|
|
61
61
|
## Scheduled snapshots (no daemon)
|
|
62
62
|
|
|
63
63
|
```
|
|
64
|
-
crewbus snapshot schedule --from
|
|
64
|
+
crewbus snapshot schedule --from orchestrator --every 24h --keep 7 --out-dir /var/backups/ab
|
|
65
65
|
crewbus snapshot run # from cron / systemd / Task Scheduler
|
|
66
66
|
```
|
|
67
67
|
|