@zonease/aiworker-cli 0.10.2 → 0.10.4
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/README.md +143 -60
- package/aiworker-bun.js +588 -680
- package/package.json +1 -1
- package/web/fleet/assets/index-bti7BCPc.js +1372 -0
- package/web/fleet/index.html +1 -1
- package/web/worker/assets/{index-K99vOXUf.js → index-DMK6sJoi.js} +193 -307
- package/web/worker/index.html +1 -1
- package/web/fleet/assets/index-RizR7tk6.js +0 -1486
package/README.md
CHANGED
|
@@ -7,48 +7,105 @@ Self-hosted, lightweight **Project Brain + Worker/Fleet aggregation runtime**.
|
|
|
7
7
|
- **Worker** owns the Project Brain (filesystem is the source of truth), worker.db, and conversations. External executors (Codex / Claude Code / Hermes / OpenClaw / Cursor, etc.) are invoked through a thin adapter only.
|
|
8
8
|
- **Gateway is an optional control plane**: a single worker runs without one. With multiple workers, the gateway aggregates presence, routing, and audit — it never holds brain or conversation data.
|
|
9
9
|
|
|
10
|
+
## Why AIWorker exists
|
|
11
|
+
|
|
12
|
+
AIWorker is not trying to be a smarter coding assistant or a new executor
|
|
13
|
+
platform. If all you need is a better one-off chat or coding agent, use Codex,
|
|
14
|
+
Claude Code, Cursor, Hermes, OpenClaw, or another executor directly.
|
|
15
|
+
|
|
16
|
+
Use AIWorker when you already trust external executors, but need to run them as
|
|
17
|
+
durable, governed workers bound to a real business scope:
|
|
18
|
+
|
|
19
|
+
- **Project Brain as an owned asset**: each worker has a filesystem-first,
|
|
20
|
+
reviewable, portable brain for scope identity, persona, policy, memories,
|
|
21
|
+
rollups, and brain skills.
|
|
22
|
+
- **Governed self-iteration**: an executor can propose durable brain changes,
|
|
23
|
+
but memory and brain-skill writes must pass admission, approval,
|
|
24
|
+
secret-scan, provenance, and audit.
|
|
25
|
+
- **Bring your own executor**: AIWorker does not replace the executor's tool
|
|
26
|
+
loop, MCP, plugins, sandbox, native sessions, auth, or model routing. It
|
|
27
|
+
wraps them with scope context, persistence, observation, and governance.
|
|
28
|
+
- **Worker/Fleet operations**: one worker can run alone; many workers can be
|
|
29
|
+
aggregated by a gateway for presence, routing, logs, approvals, cron, and
|
|
30
|
+
audit without copying brain, conversations, or secrets into fleet.db.
|
|
31
|
+
|
|
32
|
+
In short: AIWorker turns existing AI agents into self-hosted, scope-bound,
|
|
33
|
+
auditable business workers. The competitive edge is not "better model output";
|
|
34
|
+
it is durable Project Brain plus governance and fleet operations around the
|
|
35
|
+
executors customers already use.
|
|
36
|
+
|
|
37
|
+
## Who needs AIWorker
|
|
38
|
+
|
|
39
|
+
AIWorker is a good fit when you want AI agents to behave less like disposable
|
|
40
|
+
chat windows and more like managed workers tied to real work.
|
|
41
|
+
|
|
42
|
+
- **Teams that already use AI executors** and want durable scope memory,
|
|
43
|
+
policy, persona, and reviewable brain files around them.
|
|
44
|
+
- **Operators running agents for business scopes**, such as a code repository,
|
|
45
|
+
hiring pipeline, finance period, support queue, compliance folder, or
|
|
46
|
+
operational runbook.
|
|
47
|
+
- **Organizations that need governance before self-learning**, where memory or
|
|
48
|
+
brain-skill changes can be proposed by an agent but must be reviewed,
|
|
49
|
+
approved, and audited.
|
|
50
|
+
- **People running more than one worker**, where presence, routing, logs,
|
|
51
|
+
approvals, schedules, and enrollment need one control plane without moving
|
|
52
|
+
private brain or conversation data into that control plane.
|
|
53
|
+
- **Customers who need to keep their own data local**, while still using the
|
|
54
|
+
executor, model, auth, and tool ecosystem they already trust.
|
|
55
|
+
|
|
56
|
+
If you only need a one-off coding session, a single chat, or a better model
|
|
57
|
+
answer, AIWorker is probably more infrastructure than you need.
|
|
58
|
+
|
|
59
|
+
## Topology
|
|
60
|
+
|
|
10
61
|
```text
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
62
|
+
Operator / Admin
|
|
63
|
+
runs `aiworker fleet ...`
|
|
64
|
+
|
|
|
65
|
+
| WebSocket control traffic
|
|
66
|
+
| basicauth + device token
|
|
67
|
+
v
|
|
68
|
+
+--------------------------------------------------------------------------------+
|
|
69
|
+
| AIWorker Gateway (optional control plane) |
|
|
70
|
+
| |
|
|
71
|
+
| fleet.db stores: worker pointers, presence, enrollment state, audit events |
|
|
72
|
+
| fleet.db does not store: Project Brain, conversations, worker secrets |
|
|
73
|
+
+---------------------------+----------------------------+-----------------------+
|
|
74
|
+
| |
|
|
75
|
+
| WS relay / routing | WS relay / routing
|
|
76
|
+
v v
|
|
77
|
+
+----------------------+ +----------------------+
|
|
78
|
+
| Worker A | | Worker B ... N |
|
|
79
|
+
| owns its own data | | owns its own data |
|
|
80
|
+
+----------------------+ +----------------------+
|
|
81
|
+
|
|
82
|
+
A single worker can also run without the gateway:
|
|
83
|
+
|
|
84
|
+
+--------------------------------------------------------------------------------+
|
|
85
|
+
| One worker data plane |
|
|
86
|
+
| |
|
|
87
|
+
| Project Brain (filesystem) worker.db |
|
|
88
|
+
| - SOUL / USER / MEMORY - identity and config |
|
|
89
|
+
| - memories and governance - conversations and messages |
|
|
90
|
+
| - managed native skill - encrypted local state |
|
|
91
|
+
| projection manifest |
|
|
92
|
+
| - native skill files in |
|
|
93
|
+
| .agents / .claude |
|
|
94
|
+
| - policy and capabilities |
|
|
95
|
+
| - admission proposals |
|
|
96
|
+
| |
|
|
97
|
+
| AIWorker thin adapter |
|
|
98
|
+
| - adds scope context and governance |
|
|
99
|
+
| - observes run / stream / cancel / resume |
|
|
100
|
+
| - does not replace the executor tool loop |
|
|
101
|
+
| |
|
|
102
|
+
| External executor |
|
|
103
|
+
| - Codex / Claude Code / Hermes / OpenClaw / Cursor / ACP / MCP / HTTP |
|
|
104
|
+
| - keeps its own MCP, skills, plugins, auth, sandbox, and native sessions |
|
|
105
|
+
+--------------------------------------------------------------------------------+
|
|
49
106
|
```
|
|
50
107
|
|
|
51
|
-
A single worker can run standalone — the gateway is needed only when you want to aggregate multiple workers. The control plane and the data plane are physically isolated: fleet.db never stores brain / conversations / secrets, and worker.db is never reverse-fetched by the gateway. Full architecture and dual-view
|
|
108
|
+
A single worker can run standalone — the gateway is needed only when you want to aggregate multiple workers. The control plane and the data plane are physically isolated: fleet.db never stores brain / conversations / secrets, and worker.db is never reverse-fetched by the gateway. Full architecture and dual-view diagrams: [`docs/architecture.md`](docs/architecture.md). Production-readiness notes and remaining boundaries: [`docs/governance-node-status.md`](docs/governance-node-status.md).
|
|
52
109
|
|
|
53
110
|
---
|
|
54
111
|
|
|
@@ -60,22 +117,37 @@ bun install -g @zonease/aiworker-cli
|
|
|
60
117
|
# or `npx` / `npm install -g` (Bun is still required at runtime)
|
|
61
118
|
```
|
|
62
119
|
|
|
63
|
-
The CLI is Bun-native. The first
|
|
120
|
+
The CLI is Bun-native. The first worker initialization mints a master key and writes it to the worker-local `.env` (project workers use `<project>/.aiworker/local/.env`; explicit/user homes use `<AIWORKER_HOME>/.env`). **The master key must be backed up offline at the org level** — if it is lost, worker.db / fleet.db cannot be decrypted and every worker must re-enroll.
|
|
64
121
|
|
|
65
122
|
Full install and per-platform binaries: [`docs/deployment.md`](docs/deployment.md).
|
|
66
123
|
|
|
67
124
|
---
|
|
68
125
|
|
|
126
|
+
## CLI discovery
|
|
127
|
+
|
|
128
|
+
`aiworker --help` is intentionally short and shows the first-run path. Use
|
|
129
|
+
`aiworker commands` for the complete command index, or scoped help for a role:
|
|
130
|
+
|
|
131
|
+
```sh
|
|
132
|
+
aiworker --help
|
|
133
|
+
aiworker commands
|
|
134
|
+
aiworker worker --help
|
|
135
|
+
aiworker fleet --help
|
|
136
|
+
aiworker gateway --help
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
69
141
|
## Start a worker (single host, no gateway)
|
|
70
142
|
|
|
71
143
|
The most common path: turn the current business directory into a worker scope, start a local server + admin UI, and chat through the CLI. **No fleet credentials required.**
|
|
72
144
|
|
|
73
145
|
```sh
|
|
74
146
|
cd ~/code/my-project
|
|
75
|
-
aiworker up --soul developer # one shot: init +
|
|
147
|
+
aiworker up --soul developer # one shot: init + doctor + executor readiness + serve
|
|
76
148
|
```
|
|
77
149
|
|
|
78
|
-
`aiworker up` lays down the Project Brain layout under `<cwd>/.aiworker/` (worker.db, master key, persona,
|
|
150
|
+
`aiworker up` lays down the Project Brain layout under `<cwd>/.aiworker/` (worker.db, master key, persona, policy, memories, native skill projection manifest) and projects managed `aiworker-*` executor-native skills under `.agents/skills` and `.claude/skills`. It then runs preflight checks, reports executor readiness, and starts the worker HTTP/admin server (default `:9217`). It does not choose an executor for you; use `aiworker executor select --engine <id> --apply` for that. Pick a Soul from `developer` / `hr-recruiting` / `finance-ops` / `qa-reviewer` / `general-assistant` — Souls shape persona / risk preferences / default brief sections; governance kernel behavior is the same across all Souls.
|
|
79
151
|
|
|
80
152
|
Step-by-step alternative:
|
|
81
153
|
|
|
@@ -95,6 +167,11 @@ After it is running:
|
|
|
95
167
|
- Bearer token: `<scope>/.aiworker/local/bootstrap-token.txt`. REST calls must include `Authorization: Bearer <token>`.
|
|
96
168
|
- Brain and conversations stay local. The only outbound traffic is whatever the external executor itself talks to (its own LLM provider).
|
|
97
169
|
|
|
170
|
+
New worker-local `.env` files reserve commented gateway enrollment examples.
|
|
171
|
+
`aiworker doctor` also reports gateway enrollment as standalone/configured and
|
|
172
|
+
prints the exact `aiworker env ...` commands when enrollment is optional but not
|
|
173
|
+
yet configured.
|
|
174
|
+
|
|
98
175
|
Full CLI reference: [`docs/cli.md`](docs/cli.md).
|
|
99
176
|
|
|
100
177
|
---
|
|
@@ -130,14 +207,16 @@ The most common path — the worker side carries no fleet credentials, the opera
|
|
|
130
207
|
```sh
|
|
131
208
|
# Worker side:
|
|
132
209
|
aiworker init --soul developer
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
"AIWORKER_DISPLAY_NAME=my-laptop" \
|
|
136
|
-
>> .aiworker/local/.env
|
|
210
|
+
aiworker env gateway-url wss://your-gateway.example/
|
|
211
|
+
aiworker env display-name my-laptop
|
|
137
212
|
aiworker serve
|
|
138
213
|
# stdout prints an OTP, e.g. YDCR-ZD8M
|
|
139
214
|
```
|
|
140
215
|
|
|
216
|
+
`aiworker init` also leaves commented `AIWORKER_GATEWAY_URL` /
|
|
217
|
+
`AIWORKER_DISPLAY_NAME` examples in the worker-local `.env`; keep them
|
|
218
|
+
commented unless you intentionally configure gateway enrollment.
|
|
219
|
+
|
|
141
220
|
```sh
|
|
142
221
|
# Operator side:
|
|
143
222
|
aiworker fleet enroll list # see pending OTPs
|
|
@@ -234,8 +313,8 @@ See [`docs/deployment.md`](docs/deployment.md).
|
|
|
234
313
|
|---|---|
|
|
235
314
|
| `AIWORKER_MASTER_KEY` | 64 hex; AES master key for worker / gateway databases; **must be backed up offline** |
|
|
236
315
|
| `INTERNAL_SHARED_SECRET` | Remote-operator bearer when the gateway is exposed publicly or off loopback (≥16 chars) |
|
|
237
|
-
| `AIWORKER_GATEWAY_URL` |
|
|
238
|
-
| `AIWORKER_DISPLAY_NAME` |
|
|
316
|
+
| `AIWORKER_GATEWAY_URL` | Optional worker-side gateway URL (path + basicauth); set with `aiworker env gateway-url <url>` |
|
|
317
|
+
| `AIWORKER_DISPLAY_NAME` | Optional worker label in the fleet list (defaults to hostname / worker id); set with `aiworker env display-name <name>` |
|
|
239
318
|
| `AIWORKER_HOME` | Explicit worker state root; project scope auto-resolves to `<project>/.aiworker/local` |
|
|
240
319
|
| `AIWORKER_ADMIN_EXTERNAL_AUTH` | Set to `1` if `/admin/*` is fronted by Caddy / Cloudflare Access / Logto / etc. |
|
|
241
320
|
|
|
@@ -245,14 +324,13 @@ Full list: `apps/api/.env.example` + `ops/compose/.env.example`, or [`docs/archi
|
|
|
245
324
|
|
|
246
325
|
## More
|
|
247
326
|
|
|
248
|
-
- [`docs/architecture.md`](docs/architecture.md) —
|
|
249
|
-
- [`docs/governance-node-status.md`](docs/governance-node-status.md) —
|
|
327
|
+
- [`docs/architecture.md`](docs/architecture.md) — system layout, data flow, security model, Brain governance boundary, full env table
|
|
328
|
+
- [`docs/governance-node-status.md`](docs/governance-node-status.md) — production-readiness checklist and remaining boundaries
|
|
250
329
|
- [`docs/gateway.md`](docs/gateway.md) — WS protocol (METHODS / EVENTS) and the four enrollment paths
|
|
251
330
|
- [`docs/deployment.md`](docs/deployment.md) — three deployment shapes runbook + troubleshooting + backup checklist
|
|
252
331
|
- [`docs/deployment-public-https.md`](docs/deployment-public-https.md) — public-internet Cloudflare + Caddy overlay (including the BUG-007 fail-closed fix)
|
|
253
332
|
- [`docs/executor-engines.md`](docs/executor-engines.md) — per-engine auth/install
|
|
254
333
|
- [`docs/cli.md`](docs/cli.md) — full CLI reference
|
|
255
|
-
- [`scripts/governance-kernel-harness.ts`](scripts/governance-kernel-harness.ts) — Brain Governance Kernel regression harness (compact / full × source-local / cli-release-local)
|
|
256
334
|
- [`docs/changelog.md`](docs/changelog.md) — release history and end-to-end test notes
|
|
257
335
|
|
|
258
336
|
---
|
|
@@ -265,24 +343,29 @@ cd aiworker && bun install
|
|
|
265
343
|
bun run typecheck && bun run lint && bun run test
|
|
266
344
|
```
|
|
267
345
|
|
|
268
|
-
|
|
346
|
+
For local development, run focused package checks while iterating and the full
|
|
347
|
+
gate before publishing or merging. Planning notes, implementation history, and
|
|
348
|
+
release records live in [`docs/plan/`](docs/plan/), [`docs/task/`](docs/task/),
|
|
349
|
+
and [`docs/changelog.md`](docs/changelog.md).
|
|
269
350
|
|
|
270
351
|
---
|
|
271
352
|
|
|
272
353
|
## Status
|
|
273
354
|
|
|
274
|
-
> Before going to production, read the
|
|
355
|
+
> Before going to production, read the readiness table and remaining-boundary
|
|
356
|
+
> section in [`docs/governance-node-status.md`](docs/governance-node-status.md).
|
|
357
|
+
> Before 1.0.0, CLI / API / config shapes may still change.
|
|
275
358
|
|
|
276
|
-
CLI npm latest: **0.10.
|
|
359
|
+
CLI npm latest: **0.10.4**.
|
|
277
360
|
|
|
278
361
|
| Module | Status |
|
|
279
362
|
|---|---|
|
|
280
|
-
| Worker
|
|
281
|
-
| Brain
|
|
282
|
-
| Governance
|
|
283
|
-
|
|
|
284
|
-
|
|
|
285
|
-
| Cross-scope
|
|
363
|
+
| Worker and Fleet operations: control plane, enrollment, executor adapters, webhooks, schedules, per-tool approvals, hot reload | ✅ Production |
|
|
364
|
+
| Project Brain governance: reviewed memory changes, secret scanning, provenance events, canonical memory boundary, bypass checks | ✅ GA |
|
|
365
|
+
| Governance regression coverage: 800+ checks across source and packaged CLI, plus long-running worker REST regression | ✅ GA |
|
|
366
|
+
| Memory-write automation | ✅ MVP (`memory-add` is available; other proposal types are rejected until implemented) |
|
|
367
|
+
| Optional LLM-backed Brain reviewer | 🔜 opt-in; default is observe-only heuristic review |
|
|
368
|
+
| Cross-scope runtime isolation | 🔜 currently convention / filesystem only |
|
|
286
369
|
| Web SPA pending UI / Multi-host HA | 🔜 Stage-2 |
|
|
287
370
|
|
|
288
371
|
---
|