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
|
@@ -6,8 +6,8 @@
|
|
|
6
6
|
"note": "Same validation as CLI launch wizard. Thin over bootWorker (local) or remoteSpawn (per relay). dryRun previews exact commands without booting.",
|
|
7
7
|
"request": {
|
|
8
8
|
"required": ["harness", "body"],
|
|
9
|
-
"optional": ["board", "count", "prefix", "to", "subject", "priority", "model", "maxTurns", "allowTools", "permission", "isolate", "worktree", "branch", "lifetime", "budgetTokens", "budgetMinutes", "timeout", "target", "dryRun"
|
|
10
|
-
"defaults": { "count": 1, "permission": "supervised", "lifetime": "oneshot", "target": "local", "dryRun": false
|
|
9
|
+
"optional": ["board", "count", "prefix", "to", "subject", "priority", "model", "models", "orchestratorModel", "maxTurns", "allowTools", "permission", "isolate", "worktree", "branch", "lifetime", "budgetTokens", "budgetMinutes", "timeout", "target", "dryRun"],
|
|
10
|
+
"defaults": { "count": 1, "permission": "supervised", "lifetime": "oneshot", "target": "local", "dryRun": false },
|
|
11
11
|
"constraints": {
|
|
12
12
|
"harness": "one of harness.json drivers",
|
|
13
13
|
"body": "max 8000 chars (MAX_BODY_CHARS)",
|
|
@@ -15,7 +15,6 @@
|
|
|
15
15
|
"permission": "supervised|autoEdits|auto|full",
|
|
16
16
|
"lifetime": "oneshot|persistent",
|
|
17
17
|
"priority": "high|normal",
|
|
18
|
-
"lead": "auto|board|none",
|
|
19
18
|
"target": "local | {relays:[{url,weight}]}"
|
|
20
19
|
},
|
|
21
20
|
"permissionMapping": {
|
|
@@ -16,10 +16,10 @@
|
|
|
16
16
|
"treat pairing URLs + abd- creds as passwords (no screenshots/logs/bug reports)"
|
|
17
17
|
],
|
|
18
18
|
"endpoints": {
|
|
19
|
-
"issue": "POST /api/pair/issue (
|
|
19
|
+
"issue": "POST /api/pair/issue (orchestrator, token-checked; body {label?, ttl?, scopes?}) -> {pairUrl, expiresAt}",
|
|
20
20
|
"exchange": "POST /api/pair/exchange (body {pairToken, label?, scopes?}) -> {deviceId, credential (abd-..., once only)}; requested scopes must be subset of granted (narrow-only, never widen)",
|
|
21
|
-
"devices": "GET /api/pair/devices (
|
|
22
|
-
"revoke": "POST /api/pair/revoke (
|
|
21
|
+
"devices": "GET /api/pair/devices (orchestrator) -> [{id, label, by, lastSeen, revoked?}]",
|
|
22
|
+
"revoke": "POST /api/pair/revoke (orchestrator; body {deviceId}) -> immediate 403 on next use"
|
|
23
23
|
},
|
|
24
24
|
"scopes": ["launch:spawn", "launch:kill", "mail:send", "mail:inbox", "mail:ack", "fleet:read", "admin:pair", "admin:revoke"],
|
|
25
25
|
"defaultScope": "full device (today's secret-equivalent) unless narrowed at exchange",
|
package/docs/DESKTOP_SPIKE.md
DELETED
|
@@ -1,223 +0,0 @@
|
|
|
1
|
-
# M4 desktop spike — Tauri vs Electron (decision record)
|
|
2
|
-
|
|
3
|
-
Status: DECIDED — **Tauri** (confirms `docs/CONTROL_PLANE_SPEC.md` §4.3 preference).
|
|
4
|
-
Scaffold: `apps/desktop/` (static, hand-written on a machine with NO Rust
|
|
5
|
-
toolchain — nothing here has been compiled; see `apps/desktop/README.md`).
|
|
6
|
-
|
|
7
|
-
Sources read for this spike (2026-10-06):
|
|
8
|
-
|
|
9
|
-
- `docs/CONTROL_PLANE_SPEC.md` §4.3 (Desktop: same web UI via local scheme,
|
|
10
|
-
main owns sidecar `node bin/crewbus.js serve --port 0` on loopback, SSH
|
|
11
|
-
tunnels, pairing window, background service, `Local environment` toggle
|
|
12
|
-
for remote-only) + §5 (IA: Boards → Crews → Workers; digest-first; no
|
|
13
|
-
engine, no cross-board queries, no secret sync, no mutation auto-replay,
|
|
14
|
-
no silent loopback fallback).
|
|
15
|
-
- `packages/client-runtime/README.md` + `index.js`/`supervisor.js`/`auth.js`:
|
|
16
|
-
runtime-agnostic Supervisor (single retry owner, jittered backoff, 5min
|
|
17
|
-
cap), route-walk (`fetchAdvertisedRoutes`/`walkRoutes`, loopback only with
|
|
18
|
-
`allowLoopback: true` — desktop-sidecar-only flag), `parsePairUrl()`
|
|
19
|
-
(secret from `#fragment` only, query secrets throw), narrow-only scopes,
|
|
20
|
-
cache with explicitly-retried mutation queue.
|
|
21
|
-
- Pairing fragment rule (frozen M0): `packages/contracts/pairing.json`
|
|
22
|
-
(`pairUrlRules`: secret in FRAGMENT only, one-time link per device, treat
|
|
23
|
-
URLs + `abd-` creds as passwords) + `bin/lib/launch.js` `buildPairUrl()`
|
|
24
|
-
(`crewbus://pair?env=…&routes=…&caps=…#<abp-…>`) + `docs/M1_CLI_DRAFT.md`
|
|
25
|
-
§1c–d (`relay pair qr`, `serve --advertise-routes --pair-qrcode`, same
|
|
26
|
-
mint + audit as `relay pair`).
|
|
27
|
-
- `bin/lib/web.js` `renderBoardHtml()` + `cmdWeb`: single-file dashboard,
|
|
28
|
-
no build step; AppRoot shell (Boards/Crews/Fleet/Channels/Triage/Approvals/
|
|
29
|
-
Results/Audit/Settings, top bar with harness quick-pick + `#conn-dot` +
|
|
30
|
-
`Ctrl+K`); reads open (`GET /api/board|fleet|channels|results|audit`,
|
|
31
|
-
`/api/inbox`, `/api/harnesses`, `/api/routes`), writes JSON-only +
|
|
32
|
-
token-checked (`POST /api/launch|kill|ack|approve`); 5s poll; tokens in
|
|
33
|
-
tab memory. This is what the desktop shell embeds — no UI duplication.
|
|
34
|
-
|
|
35
|
-
## 1. What the shell embeds
|
|
36
|
-
|
|
37
|
-
`cmdWeb` binds `--host` (default `127.0.0.1`) + `--port` (`0` = random, the
|
|
38
|
-
actual address is printed on stdout), serves `GET /` → `renderBoardHtml()`
|
|
39
|
-
+ the `/api/*` set above, and blocks until SIGINT. The desktop shell therefore
|
|
40
|
-
needs no board UI of its own: it owns a loopback sidecar process, learns its
|
|
41
|
-
actual `127.0.0.1:PORT`, and points a webview at it. All IA (§5), RBAC, and
|
|
42
|
-
contract behavior ride along unchanged.
|
|
43
|
-
|
|
44
|
-
Spike finding (verified in source): `serve`'s `GET /` is currently a
|
|
45
|
-
**plaintext relay banner** (`bin/crewbus.js` ~L4896), NOT the dashboard —
|
|
46
|
-
`renderBoardHtml()` is served by `web` only. So "same web UI via sidecar
|
|
47
|
-
`serve`" needs one additive endpoint (M4b owns it): `serve` should answer
|
|
48
|
-
`GET /` with the same `renderBoardHtml()` body `web` serves (same loopback
|
|
49
|
-
trust zone, pure reuse, allowed — "zero-dep core gains only additive
|
|
50
|
-
endpoints"). Until that lands, the scaffold's supervisor spawns `serve`
|
|
51
|
-
per spec and the shell degrades gracefully (status line says what it is
|
|
52
|
-
waiting for). No second sidecar, no forked UI.
|
|
53
|
-
|
|
54
|
-
## 2. Evaluation
|
|
55
|
-
|
|
56
|
-
### (a) Sidecar ownership (`node bin/crewbus.js serve --port 0` loopback lifecycle)
|
|
57
|
-
|
|
58
|
-
- Tauri: Rust supervisor spawns system `node` with fixed args, reads stdout
|
|
59
|
-
for the first `http://127.0.0.1:PORT`, holds the child handle, kills it on
|
|
60
|
-
window close / toggle-off, restarts with backoff. `--port 0` means the port
|
|
61
|
-
is *learned*, never configured — both shells must parse it. Tauri's
|
|
62
|
-
plugin-shell `spawn` scope pins the exact binary + arg prefix, so the
|
|
63
|
-
supervisor cannot be repurposed into an arbitrary command runner.
|
|
64
|
-
- Electron: same lifecycle in Node (trivially easy — it IS Node), but the
|
|
65
|
-
main process has no capability boundary: any RCE in the renderer-adjacent
|
|
66
|
-
main preload chain inherits full `child_process`. Ownership is easier to
|
|
67
|
-
write, harder to confine.
|
|
68
|
-
|
|
69
|
-
Edge for Tauri (confinement), with one cost: the sidecar needs a **system
|
|
70
|
-
`node` ≥ 18 on PATH** — Tauri does not ship a JS runtime. Recorded as a
|
|
71
|
-
build/packaging prerequisite, not a blocker (the fleet already assumes node).
|
|
72
|
-
|
|
73
|
-
### (b) Webview loading the local dashboard
|
|
74
|
-
|
|
75
|
-
- Tauri: system webview (WebView2 / WKWebView / WebKitGTK), CSP in
|
|
76
|
-
`tauri.conf.json` pinned to `http://127.0.0.1:*` + `http://localhost:*`,
|
|
77
|
-
dashboard loaded in an `<iframe>` so *zero* dashboard code is duplicated —
|
|
78
|
-
`renderBoardHtml()` stays the single implementation. No bundled Chromium.
|
|
79
|
-
- Electron: bundled Chromium — pixel-identical rendering everywhere, but the
|
|
80
|
-
shell ships a whole browser to display a localhost page, and the renderer
|
|
81
|
-
bridge (`ipcRenderer`/`contextBridge`) is a perennial CVE surface for an
|
|
82
|
-
app whose page already does everything over plain `fetch`.
|
|
83
|
-
|
|
84
|
-
Edge for Tauri (no duplicated browser, smaller surface). Residual risk:
|
|
85
|
-
WebKitGTK lag on Linux — accepted, dashboard is plain HTML + 5s poll.
|
|
86
|
-
|
|
87
|
-
### (c) Pairing-window flow (render `crewbus://pair` QR from `--pair-qrcode` output, fragment-secret hygiene)
|
|
88
|
-
|
|
89
|
-
Flow is identical either way: supervisor mints via `serve --pair-qrcode`
|
|
90
|
-
(same mint + audit as `relay pair`), captures the
|
|
91
|
-
`crewbus://pair?env=…&routes=…&caps=…#<abp-…>` stdout line, hands **only the
|
|
92
|
-
in-memory string** to a second window that renders the QR client-side.
|
|
93
|
-
Hygiene rules (from `pairing.json` + `parsePairUrl()`), enforced in the
|
|
94
|
-
scaffold's `pair.js` comments:
|
|
95
|
-
|
|
96
|
-
1. Secret travels in `#fragment` only — never query (fragments never leave
|
|
97
|
-
the client; `parsePairUrl()` throws on query secrets).
|
|
98
|
-
2. The full URL is never logged, persisted, or screenshotted — strip the
|
|
99
|
-
fragment before any status line; one-time link per device.
|
|
100
|
-
3. The shell never stores the `abp-` token — exchange swaps it once for
|
|
101
|
-
`abd-…` (narrow-only scopes) held in the client-runtime auth store
|
|
102
|
-
(OS keychain via Tauri `stronghold`/keyring on the toolchain machine;
|
|
103
|
-
memory store in the spike).
|
|
104
|
-
|
|
105
|
-
No differentiator on capability — slight edge for Tauri: the pair window is
|
|
106
|
-
a declaratively scoped second webview (`pair.html`, `visible: false` until
|
|
107
|
-
invoked) with no Node access, whereas Electron needs explicit
|
|
108
|
-
`BrowserWindow` hardening per window.
|
|
109
|
-
|
|
110
|
-
### (d) Background-service story
|
|
111
|
-
|
|
112
|
-
Spec wants the desktop to act as an environment that survives window close
|
|
113
|
-
(sidecar keeps serving; mobile pairs against it). Neither framework is an
|
|
114
|
-
OS service manager — both need per-OS registration:
|
|
115
|
-
|
|
116
|
-
- Windows: Task Scheduler entry / WinSW wrapper; macOS: `launchd` plist;
|
|
117
|
-
Linux: `systemd --user` unit. `apps/desktop/README.md` records all three.
|
|
118
|
-
- Tauri adds: single-instance plugin (second launch focuses, never double-
|
|
119
|
-
spawns the sidecar) + autostart plugin. Electron adds: same via
|
|
120
|
-
`app.requestSingleInstanceLock()` + `app.setLoginItemSettings()`.
|
|
121
|
-
|
|
122
|
-
Rough parity; Tauri's smaller resident footprint matters more for an
|
|
123
|
-
always-on sidecar host. Edge for Tauri (weakly).
|
|
124
|
-
|
|
125
|
-
### (e) Packaging size / signer burden
|
|
126
|
-
|
|
127
|
-
- Tauri: ~8–15 MB installer (system webview + ~2 MB Rust supervisor);
|
|
128
|
-
signing/notarization identical paperwork but a far smaller artifact to
|
|
129
|
-
ship and update (updater deltas stay tiny).
|
|
130
|
-
- Electron: ~80–150 MB per platform (bundled Chromium + Node), three
|
|
131
|
-
platform builds of a full browser to sign, notarize, and push through
|
|
132
|
-
the updater on every release.
|
|
133
|
-
|
|
134
|
-
Strong edge for Tauri. For a localhost dashboard host, shipping a second
|
|
135
|
-
browser is pure burden.
|
|
136
|
-
|
|
137
|
-
### (f) Fit with zero-dep Node core + `packages/client-runtime`
|
|
138
|
-
|
|
139
|
-
- The core stays zero-dep either way: the sidecar is stock
|
|
140
|
-
`bin/crewbus.js`, spawned, not bundled — neither framework touches `bin/`
|
|
141
|
-
or `packages/`.
|
|
142
|
-
- `packages/client-runtime` is runtime-agnostic ESM with injected
|
|
143
|
-
`fetch`/timers/storage. Tauri's frontend is plain ESM (`src/main.js`
|
|
144
|
-
imports it at build time on a toolchain machine; the spike keeps the
|
|
145
|
-
shell dependency-free and notes the import point). Electron could
|
|
146
|
-
`require()` it in main, but that drags Node-only patterns into the shell
|
|
147
|
-
the runtime was designed to avoid (`node-adapter.js` is deliberately NOT
|
|
148
|
-
re-exported from `index.js`). Tauri's split — Rust owns the process,
|
|
149
|
-
ESM owns the policy — matches the runtime's injection design better.
|
|
150
|
-
|
|
151
|
-
Edge for Tauri.
|
|
152
|
-
|
|
153
|
-
## 3. Decision
|
|
154
|
-
|
|
155
|
-
**Tauri wins 5–0–1 (one parity). Confirm the spec preference — no overturn.**
|
|
156
|
-
|
|
157
|
-
| Criterion | Winner | Why in one line |
|
|
158
|
-
|---|---|---|
|
|
159
|
-
| (a) sidecar ownership | Tauri | spawn scope pins binary+args; lifetime in Rust, not in a web page |
|
|
160
|
-
| (b) local dashboard | Tauri | system webview + iframe reuse; no second browser |
|
|
161
|
-
| (c) pairing window | Tauri (slight) | scoped second webview, no per-window Node hardening |
|
|
162
|
-
| (d) background service | Tie (Tauri weakly) | both need OS registration; Tauri is the lighter resident |
|
|
163
|
-
| (e) packaging/signing | Tauri (strong) | ~10 MB vs ~100 MB to sign, ship, and update |
|
|
164
|
-
| (f) core/runtime fit | Tauri | external-node sidecar keeps core zero-dep; ESM injection fits a web shell |
|
|
165
|
-
|
|
166
|
-
## 4. Consequences
|
|
167
|
-
|
|
168
|
-
1. Builds require a toolchain machine (Rust stable + Node ≥ 18 + Tauri CLI
|
|
169
|
-
+ platform webview SDKs) — this repo machine has none, so `apps/desktop/`
|
|
170
|
-
is an uncompiled static scaffold. `npm install` was deliberately NOT run
|
|
171
|
-
(no `node_modules`, no lockfile).
|
|
172
|
-
2. Runtime requires system `node` ≥ 18 on PATH for the sidecar. The
|
|
173
|
-
installer story must either assert it at first run or vendor node next
|
|
174
|
-
to the binary (M5 packaging question below).
|
|
175
|
-
3. M4b owns the sidecar test surface + the additive `serve GET /` dashboard
|
|
176
|
-
route (§1 finding). This scaffold adds no repo tests.
|
|
177
|
-
4. `Local environment` toggle semantics (spec §4.3): remote-only mode stops
|
|
178
|
-
the sidecar process WITHOUT deleting board state — stopping `serve`
|
|
179
|
-
touches nothing under `.crewbus/` (it only reads/writes live); the board
|
|
180
|
-
directory is never removed. Implemented as `stop_sidecar` + documented
|
|
181
|
-
in `apps/desktop/README.md`.
|
|
182
|
-
5. No remote capability is granted anywhere in the scaffold (capability file
|
|
183
|
-
allows `http` fetch to loopback only, `shell` spawn of the pinned sidecar
|
|
184
|
-
command only, no `fs` scope at all).
|
|
185
|
-
|
|
186
|
-
## 5. Scaffold map (see `apps/desktop/README.md` for build/run)
|
|
187
|
-
|
|
188
|
-
- `apps/desktop/package.json` — scripts (`dev`/`build`/`test`/`tauri`),
|
|
189
|
-
deps listed (`@tauri-apps/api`, `@tauri-apps/cli`), never installed here.
|
|
190
|
-
- `apps/desktop/src-tauri/tauri.conf.json` — product/identifier, `frontendDist
|
|
191
|
-
../src`, main + hidden pair windows, loopback-pinned CSP, bundle metadata.
|
|
192
|
-
- `apps/desktop/src-tauri/capabilities/main.json` — loopback-only grant:
|
|
193
|
-
core default, shell spawn of `node bin/crewbus.js serve --port 0` only,
|
|
194
|
-
http fetch to `127.0.0.1`/`localhost` only, no fs, no remote.
|
|
195
|
-
- `apps/desktop/src-tauri/Cargo.toml` + `src-tauri/src/main.rs` — Rust
|
|
196
|
-
supervisor stub (spawn/parse-port/emit/stop, single-instance note).
|
|
197
|
-
UNCOMPILED — validate with `npm run tauri build` on a toolchain machine.
|
|
198
|
-
- `apps/desktop/src/index.html` + `src/main.js` — shell page: connection dot
|
|
199
|
-
(5s `/api/board` poll, same signal as the dashboard's `#conn-dot`), Local
|
|
200
|
-
environment toggle, pair-window button, sidecar-URL resolution
|
|
201
|
-
(`?dashboard=` → Tauri `dashboard-ready` event → manual entry), dashboard
|
|
202
|
-
in `<iframe>` (its UI is reused, never duplicated).
|
|
203
|
-
- `apps/desktop/src/pair.html` + `src/pair.js` — pair-QR window placeholder:
|
|
204
|
-
paste/capture of the `crewbus://pair…#abp-…` URL, fragment-hygiene rules,
|
|
205
|
-
QR box placeholder (wire a QR renderer on the toolchain machine).
|
|
206
|
-
- `apps/desktop/scripts/check.mjs` — static self-check (`npm test`): every
|
|
207
|
-
JSON parses, every cross-referenced path exists. This is the M4 desktop
|
|
208
|
-
verify hook until M4b's sidecar tests land.
|
|
209
|
-
|
|
210
|
-
## 6. Open questions for M5 (mobile + hardening)
|
|
211
|
-
|
|
212
|
-
1. `serve GET /` dashboard route (§1): M4b confirms shape + test, or the
|
|
213
|
-
supervisor must target `web --port 0` for the iframe while keeping
|
|
214
|
-
`serve` for relay — decide before M5 pairs phones against desktops.
|
|
215
|
-
2. Vendor node vs assert node: does the installer bundle a node binary
|
|
216
|
-
(size/signer cost) or refuse to start without system node ≥ 18?
|
|
217
|
-
3. QR renderer choice for the pair window (no-dep canvas encoder vs a pinned
|
|
218
|
-
dependency) + `stronghold`/keyring binding for the `abd-…` auth store.
|
|
219
|
-
4. `advertiseEnv()` routes for a laptop desktop (LAN/Tailscale hints via
|
|
220
|
-
`serve --advertise-routes`) so M5 route-walk has something to prove.
|
|
221
|
-
5. Icon set + updater signing certs per OS (needs the toolchain machine;
|
|
222
|
-
`npm run tauri icon` + CI secrets).
|
|
223
|
-
6. WebKitGTK floor version for the Linux shell (oldest distro to support).
|