@awebai/oats 0.69.20 → 0.69.22
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/bin/oats.mjs +26 -3
- package/docs/capabilities.md +1 -1
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +311 -4
- package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
- package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
- package/docs/desktop-cli-api.md +80 -0
- package/docs/desktop.md +404 -177
- package/docs/implementation.md +15 -2
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/official-catalog.md +44 -1
- package/docs/packages.md +2 -2
- package/docs/release-lane.md +8 -6
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/release-notes/v0.69.22.md +221 -0
- package/docs/servers.md +5 -1
- package/docs/souls-and-instances.md +11 -0
- package/docs/tui.md +44 -4
- package/docs/upgrading.md +16 -5
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +1 -0
- package/lib/core.mjs +5 -3
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +16 -0
- package/lib/instance-listing.mjs +8 -4
- package/lib/instance-pin.mjs +59 -0
- package/lib/kernel-features.mjs +1 -1
- package/lib/servers.mjs +8 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/above-tested.mjs +3 -2
- package/packages/client/capability-list.mjs +69 -0
- package/packages/client/capability-origin.mjs +54 -0
- package/packages/client/cli-adapter.mjs +9 -1
- package/packages/client/deployment-data.mjs +3 -0
- package/packages/client/deployment-panel.mjs +2 -0
- package/packages/client/home-board.mjs +50 -0
- package/packages/client/instance-pin.mjs +28 -0
- package/packages/client/instance-record-outcome.mjs +31 -0
- package/packages/client/instance-tree.mjs +62 -20
- package/packages/client/keymap.mjs +11 -3
- package/packages/client/remote-roster.mjs +8 -1
- package/packages/client/roster-row-facts.mjs +50 -0
- package/packages/client/roster-sections.mjs +10 -7
- package/packages/client/soul-role.mjs +44 -0
- package/packages/client/waiting-on-you.mjs +10 -0
- package/packages/tui/lib/actions.mjs +11 -4
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/main.mjs +16 -2
- package/packages/tui/lib/model.mjs +48 -5
- package/packages/tui/lib/store.mjs +28 -2
- package/skills/oats-getting-started/SKILL.md +283 -30
package/bin/oats.mjs
CHANGED
|
@@ -83,7 +83,7 @@ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = aw
|
|
|
83
83
|
const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
|
|
84
84
|
const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
|
|
85
85
|
const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
|
|
86
|
-
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
86
|
+
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
87
87
|
const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
|
|
88
88
|
const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
|
|
89
89
|
const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
|
|
@@ -1453,8 +1453,8 @@ async function instanceCmd() {
|
|
|
1453
1453
|
if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
|
|
1454
1454
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1455
1455
|
if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
|
|
1456
|
-
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1457
|
-
if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1456
|
+
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1457
|
+
if (!["git", "diff", "stop", "events", "color", "background", "pin", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1458
1458
|
dropAmbientRoot();
|
|
1459
1459
|
if (sub === "events") {
|
|
1460
1460
|
// K7: typed producer events, bounded window; nothing inferred.
|
|
@@ -1528,6 +1528,25 @@ async function instanceCmd() {
|
|
|
1528
1528
|
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
1529
1529
|
}
|
|
1530
1530
|
}
|
|
1531
|
+
if (sub === "pin") {
|
|
1532
|
+
// Feature instance-pin: presentation only, so no plan; addressed as `instance background` addresses an instance.
|
|
1533
|
+
const homeOpt = flag("home");
|
|
1534
|
+
if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1535
|
+
const pinUsage = "usage: oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1536
|
+
// The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
|
|
1537
|
+
const words = [];
|
|
1538
|
+
for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
|
|
1539
|
+
if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${pinUsage}`);
|
|
1540
|
+
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
1541
|
+
try {
|
|
1542
|
+
const r = setInstancePin(dirFlag(), root, name, { home: homeOpt, pinned: words[0] === "on" });
|
|
1543
|
+
if (JSON_MODE) { jsonOk(r); return; }
|
|
1544
|
+
console.log(`${r.instance}: ${r.pinned ? "pinned" : "not pinned"}${r.changed ? "" : " (unchanged)"}`);
|
|
1545
|
+
return;
|
|
1546
|
+
} catch (e) {
|
|
1547
|
+
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
1548
|
+
}
|
|
1549
|
+
}
|
|
1531
1550
|
if (sub === "same-work") {
|
|
1532
1551
|
// Feature instance-same-work: presentation only, so no plan; addressed as color addresses an instance.
|
|
1533
1552
|
const homeOpt = flag("home");
|
|
@@ -5245,6 +5264,10 @@ Usage:
|
|
|
5245
5264
|
oats instance background <instance> on|off [--home <abs>] [--json]
|
|
5246
5265
|
whether clients list the instance under
|
|
5247
5266
|
Background, presentation only
|
|
5267
|
+
oats instance pin <instance> on|off [--home <abs>] [--json]
|
|
5268
|
+
pin the instance at the top of its machine's
|
|
5269
|
+
list; shared, as every viewer of the machine
|
|
5270
|
+
reads it from the home
|
|
5248
5271
|
oats instance same-work <instance> on|off [--home <abs>] [--json]
|
|
5249
5272
|
record that this instance does the same work as
|
|
5250
5273
|
its parent (on needs a recorded parent); clients
|
package/docs/capabilities.md
CHANGED
|
@@ -333,7 +333,7 @@ A self-contained package has an `oats.json`:
|
|
|
333
333
|
- an exact name that is `.oats`, `.agents` or `.claude`, or that starts
|
|
334
334
|
with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
|
|
335
335
|
`.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
|
|
336
|
-
`.oats-background` or `.oats-same-work`: the top-level entries the kernel
|
|
336
|
+
`.oats-background`, `.oats-pinned` or `.oats-same-work`: the top-level entries the kernel
|
|
337
337
|
itself writes in an instance home;
|
|
338
338
|
- a prefix that starts with `.oats-`.
|
|
339
339
|
|
|
@@ -374,7 +374,7 @@
|
|
|
374
374
|
"description": "Home entries the kernel owns cannot be declared.",
|
|
375
375
|
"anyOf": [
|
|
376
376
|
{"pattern": "^\\.(?:oats|agents|claude)$"},
|
|
377
|
-
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|same-work)"},
|
|
377
|
+
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work)"},
|
|
378
378
|
{"pattern": "^\\.oats-.*\\*$"}
|
|
379
379
|
]
|
|
380
380
|
}
|
package/docs/container.md
CHANGED
|
@@ -19,7 +19,9 @@ container is one trust group ([trust-model.md](trust-model.md)):
|
|
|
19
19
|
rewrite the launch configurations in `/state/deploy` and the schedule
|
|
20
20
|
registry in `/state/home`, rewrite the wake registrations under
|
|
21
21
|
`/state/home/.config/aw/wake`, and stop sshd, `oats host run`, the wake
|
|
22
|
-
broker or its supervisor.
|
|
22
|
+
broker or its supervisor. With the optional bb server, each agent can also
|
|
23
|
+
read and drive every bb thread and read bb's database
|
|
24
|
+
([A bb server for the team](#a-bb-server-for-the-team)).
|
|
23
25
|
- **It holds one team, never several.** Agents that must not be able to read
|
|
24
26
|
each other's identities or affect each other's work get separate
|
|
25
27
|
containers. Nothing in OATS makes sharing one safe.
|
|
@@ -106,7 +108,9 @@ the UID-only form proves startup and SSH support, not token access.
|
|
|
106
108
|
| Container path | Host ownership and mode | Access |
|
|
107
109
|
| --- | --- | --- |
|
|
108
110
|
| `/state` | Runtime UID:GID, 0700 | Read/write; persistent |
|
|
111
|
+
| `/outbox` (optional) | Runtime UID:dedicated outbox-GID, 2750 (setgid); operator-owned parent | Read/write export queue shared with every agent |
|
|
109
112
|
| `/work` (optional) | Runtime UID:GID, 0700 | Read/write |
|
|
113
|
+
| `/inputs` (optional) | Operator-provisioned directory, readable by runtime UID:GID | Read-only; shared with every agent in the trust group |
|
|
110
114
|
| `/etc/agent-login` | root:runtime-GID, 0750; `claude-token` root:runtime-GID, 0440 | Read-only |
|
|
111
115
|
| `/etc/agent-ssh/authorized_keys` | root-owned regular file, 0644 | Read-only |
|
|
112
116
|
| `/etc/resolv.conf` | Operator-provided resolver file | Read-only |
|
|
@@ -139,6 +143,9 @@ Supply these plain variables to the bundle's env file:
|
|
|
139
143
|
| `AGENT_UID`, `AGENT_GID` | Runtime IDs; both default to 20001. |
|
|
140
144
|
| `TEAM_STATE_DIR` | Absolute host directory for `/state`. |
|
|
141
145
|
| `TEAM_WORK_DIR` | Optional absolute host directory for `/work`. |
|
|
146
|
+
| `TEAM_INPUT_DIR` | Optional absolute host directory for `/inputs`; selects `compose.agent.inputs.yaml`. |
|
|
147
|
+
| `TEAM_OUTBOX_DIR` | Optional absolute host export-queue directory for `/outbox`; selects `compose.agent.outbox.yaml`. |
|
|
148
|
+
| `TEAM_OUTBOX_GID` | Dedicated non-root numeric supplementary group for `/outbox`, distinct from `AGENT_GID`; required with `TEAM_OUTBOX_DIR`. |
|
|
142
149
|
| `TEAM_LOGIN_DIR` | Absolute host directory containing `claude-token`. |
|
|
143
150
|
| `AUTHORIZED_KEYS_FILE` | Absolute host public-key file. |
|
|
144
151
|
| `RESOLV_CONF_FILE` | Absolute host resolver file; always required. |
|
|
@@ -147,6 +154,7 @@ Supply these plain variables to the bundle's env file:
|
|
|
147
154
|
| `AGENT_CA_FILE` | Optional absolute public PEM path from `agents.caFile`; selects `compose.agent.trust.yaml`. |
|
|
148
155
|
| `AGENT_MIRRORS_DIR` | Optional absolute mirror directory from `agents.mirrorsDir`; selects `compose.agent.mirrors.yaml`. |
|
|
149
156
|
| `AGENTS_NETWORK`, `AGENT_IP` | Installer-created external network and container address. |
|
|
157
|
+
| `AGENT_BB` | Optional; exactly `1` when `compose.agent.bb.yaml` is included, for acceptance. `AGENT_IMAGE` is then an image built from `container/agent-bb`. |
|
|
150
158
|
|
|
151
159
|
The bundle owns the network, resolver, forwarder, firewall and their bypass
|
|
152
160
|
checks. The agent service publishes no ports and sets no DNS or extra-hosts
|
|
@@ -176,10 +184,15 @@ start with the same approved anchors.
|
|
|
176
184
|
A successful probe using an explicit CA does not establish that the
|
|
177
185
|
real broker trusts it; prove that through the deployment's HTTPS registry.
|
|
178
186
|
|
|
187
|
+
Include `compose.agent.bb.yaml` only for a team that runs a bb server. It sets
|
|
188
|
+
exactly one fixed environment entry, `AGENT_BB: "1"`, and adds no mount, port,
|
|
189
|
+
network or capability
|
|
190
|
+
([A bb server for the team](#a-bb-server-for-the-team)).
|
|
191
|
+
|
|
179
192
|
Include `compose.agent.mirrors.yaml` only when `agents.mirrorsDir` is configured.
|
|
180
193
|
The operator provisions and refreshes the bare mirrors outside the container,
|
|
181
194
|
with no repository credentials, and the fragment mounts them read-only at
|
|
182
|
-
`/mirrors`. Keep
|
|
195
|
+
`/mirrors`. Keep all optional input sources outside every agent-writable bind
|
|
183
196
|
source, including symlink aliases: run acceptance on the Docker engine host so
|
|
184
197
|
it can resolve the actual sources. A CA file with multiple hardlinks is refused,
|
|
185
198
|
since a read-only bind cannot protect another writable link to the same file.
|
|
@@ -213,6 +226,71 @@ the override: the base has no `/work` mount. With multiple Compose files,
|
|
|
213
226
|
paths resolve relative to the first file; use absolute host paths. Container
|
|
214
227
|
down/upgrade preserves `/state`; the operator owns provisioning and rollback.
|
|
215
228
|
|
|
229
|
+
For provider input folders, provision one readable host directory outside every
|
|
230
|
+
agent-writable bind source, including symlink aliases. Set `TEAM_INPUT_DIR`
|
|
231
|
+
and append `-f container/agent/compose.agent.inputs.yaml` to both Compose
|
|
232
|
+
commands above. For example, with the bundle's other plain variables supplied:
|
|
233
|
+
|
|
234
|
+
```sh
|
|
235
|
+
TEAM_INPUT_DIR=/srv/example-team/inputs docker compose -p "oats-team-${TEAM}" \
|
|
236
|
+
--env-file <plain-env-file> -f compose.yaml \
|
|
237
|
+
-f container/agent/compose.agent.yaml \
|
|
238
|
+
-f container/agent/compose.agent.inputs.yaml up -d
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
The operator creates and populates the directory first; a missing source fails
|
|
242
|
+
startup without creating a host directory. The fragment adds only a read-only
|
|
243
|
+
bind at `/inputs`. Omit the fragment and unset `TEAM_INPUT_DIR` to run the base
|
|
244
|
+
without `/inputs`; pass the same reviewed variables to `accept.sh`.
|
|
245
|
+
Acceptance checks the running container's exact approved mounts, its environment
|
|
246
|
+
against the reviewed image, directory readability and a refused write. It also
|
|
247
|
+
checks that the base has no `/inputs`. Team-image CI exercises both forms and
|
|
248
|
+
checks missing-source startup failure without host-path creation, using a
|
|
249
|
+
synthetic input directory readable by the agent group and a private outbox
|
|
250
|
+
subdirectory, with no publisher credentials. Credential scans cover these trees
|
|
251
|
+
as the agent, since root without DAC capabilities cannot read their private
|
|
252
|
+
subdirectories.
|
|
253
|
+
|
|
254
|
+
The input folder is ambient to the container's trust group: every agent in the
|
|
255
|
+
container can read everything in it. If only one agent may read an input, that
|
|
256
|
+
agent needs its own container. Publication happens at a connector or job boundary
|
|
257
|
+
outside the agent container. Publisher credentials stay outside it too. This fragment
|
|
258
|
+
provides a generic bind only; provider authorization and publication are separate
|
|
259
|
+
integration concerns.
|
|
260
|
+
|
|
261
|
+
For an export queue, the operator provisions `TEAM_OUTBOX_DIR` under an
|
|
262
|
+
operator-owned parent, with ownership `AGENT_UID:TEAM_OUTBOX_GID` and mode
|
|
263
|
+
2750 (setgid). Keep its resolved source separate from `/state`, optional
|
|
264
|
+
`/work`, and all read-only input sources. Supply a dedicated non-root numeric
|
|
265
|
+
`TEAM_OUTBOX_GID` distinct from `AGENT_GID` and append
|
|
266
|
+
`-f container/agent/compose.agent.outbox.yaml` to both Compose commands.
|
|
267
|
+
For example, with both optional folders:
|
|
268
|
+
|
|
269
|
+
```sh
|
|
270
|
+
TEAM_INPUT_DIR=/srv/example-team/inputs \
|
|
271
|
+
TEAM_OUTBOX_DIR=/srv/example-team/outbox TEAM_OUTBOX_GID=20002 \
|
|
272
|
+
docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
|
|
273
|
+
-f compose.yaml -f container/agent/compose.agent.yaml \
|
|
274
|
+
-f container/agent/compose.agent.inputs.yaml \
|
|
275
|
+
-f container/agent/compose.agent.outbox.yaml up -d
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
The outbox fragment adds only a read/write `/outbox` bind and its numeric
|
|
279
|
+
supplementary group; it does not alter `/state` or the entrypoint's umask
|
|
280
|
+
077. Files inherit the directory's outbox group. The integrations submit
|
|
281
|
+
helper makes reports and manifests 0640; OATS does not set publication modes.
|
|
282
|
+
Acceptance creates and removes its own probe, checks its group, and checks
|
|
283
|
+
that `/state` remains 0700. CI also checks that the base has no `/outbox`
|
|
284
|
+
and that a missing source fails startup without creating a host directory.
|
|
285
|
+
Omit the fragment and unset both outbox variables when no queue is needed.
|
|
286
|
+
|
|
287
|
+
The outbox is an export queue, not an isolation boundary: every agent in the
|
|
288
|
+
container can write and read it. Durable work stays in `/state`. The publisher
|
|
289
|
+
reads the outbox read-only in its own namespace; the publisher and its ledger
|
|
290
|
+
are outside OATS. No publisher mount or credentials are added to the agent
|
|
291
|
+
container. The exact approved writable binds are `/state`, optional `/work`
|
|
292
|
+
and optional `/outbox`.
|
|
293
|
+
|
|
216
294
|
The image account and the runtime NSS entry use `/bin/bash` as the login shell.
|
|
217
295
|
This lets OATS capture a fresh login environment rather than inheriting the tmux
|
|
218
296
|
creator's environment after a failed shell capture.
|
|
@@ -525,7 +603,9 @@ What the image's files fix for that:
|
|
|
525
603
|
run alone and keeps the wake broker alive until host run finishes stopping
|
|
526
604
|
the agents. Then it stops sshd and the broker in parallel, allowing sshd three seconds
|
|
527
605
|
and the broker six seconds before escalation. The broker budget preserves
|
|
528
|
-
its channel children's five-second delivery drain.
|
|
606
|
+
its channel children's five-second delivery drain. With a bb server, bb is
|
|
607
|
+
stopped in that same step, with eight seconds, so it runs until host run
|
|
608
|
+
has stopped the agents. A broker or
|
|
529
609
|
host-run exit is reported and drains the other children before a nonzero
|
|
530
610
|
container exit, so
|
|
531
611
|
the restart policy can restart it. The broker runs as the agent uid; its
|
|
@@ -575,6 +655,223 @@ or, in the container, `oats schedule host install --register-only --dir
|
|
|
575
655
|
systemd user manager. The registry is in `/state/home`, so it persists
|
|
576
656
|
across container runs.
|
|
577
657
|
|
|
658
|
+
## A bb server for the team
|
|
659
|
+
|
|
660
|
+
[bb](https://github.com/get-bb/bb) (npm `bb-app`, MIT) is a server that runs
|
|
661
|
+
coding agents as threads and shows them in a web, desktop and phone app. A
|
|
662
|
+
team can run one bb server in its container, supervised beside the wake
|
|
663
|
+
broker, sshd and `oats host run`. It is opt-in: a container that does not
|
|
664
|
+
ask for it runs exactly as before, and the team image holds no bb.
|
|
665
|
+
|
|
666
|
+
The server is unused until agents are spawned with the bb session provider,
|
|
667
|
+
which arrives with a later kernel. Until then it starts, listens and holds
|
|
668
|
+
no thread of OATS's.
|
|
669
|
+
|
|
670
|
+
**This is experimental.** The bb image (`container/agent-bb`),
|
|
671
|
+
`compose.agent.bb.yaml` and the relay will move to the bb package repository
|
|
672
|
+
once it exists. There is no compatibility promise on those paths, on
|
|
673
|
+
`AGENT_BB` or on the image's recipe, so that move will not be a breaking
|
|
674
|
+
change.
|
|
675
|
+
|
|
676
|
+
### Turning it on
|
|
677
|
+
|
|
678
|
+
Two things, together:
|
|
679
|
+
|
|
680
|
+
1. **The derived image.** `container/agent-bb/` builds on a team image and
|
|
681
|
+
adds only `bb-app`, at the one version its committed `package.json` and
|
|
682
|
+
`package-lock.json` pin, installed with `npm ci --ignore-scripts`: no
|
|
683
|
+
lifecycle script, no rebuild, no OS package. bb's native modules are the
|
|
684
|
+
prebuilt ones in its locked packages. It keeps the team image's
|
|
685
|
+
entrypoint, user, `HOME` and environment, and bb runs the Claude Code that
|
|
686
|
+
image already holds, `/usr/local/bin/claude`: the derived image adds no
|
|
687
|
+
second one. It is about 280 MB larger.
|
|
688
|
+
|
|
689
|
+
```sh
|
|
690
|
+
docker build --platform linux/amd64 \
|
|
691
|
+
--build-arg AGENT_IMAGE=oats-agent:reviewed \
|
|
692
|
+
-t oats-agent-bb:reviewed container/agent-bb
|
|
693
|
+
```
|
|
694
|
+
|
|
695
|
+
Select it with `AGENT_IMAGE`. To change bb's version, change its one
|
|
696
|
+
dependency version, regenerate that directory's lock with npm 11 or later
|
|
697
|
+
(`npm install --package-lock-only --ignore-scripts`; npm 10 drops the
|
|
698
|
+
`libc` field of platform packages, and `npm ci` then also installs their
|
|
699
|
+
musl builds), review both files and build a new image.
|
|
700
|
+
|
|
701
|
+
2. **The fragment.** Append `-f container/agent/compose.agent.bb.yaml` to
|
|
702
|
+
the Compose commands. It sets `AGENT_BB: "1"` and nothing else. Export
|
|
703
|
+
`AGENT_BB=1` with the other variables when you run acceptance.
|
|
704
|
+
|
|
705
|
+
bb's version is pinned in this image's `container/agent-bb/package.json`.
|
|
706
|
+
When the bb session provider arrives, its `version` setting in the
|
|
707
|
+
deployment is a second pin, and its `E_BACKEND_VERSION` check, at readiness
|
|
708
|
+
and at launch, is what keeps the two equal.
|
|
709
|
+
|
|
710
|
+
The supervisor reads `AGENT_BB` once, at start. Unset or empty, it does
|
|
711
|
+
what it did before. Any value but `1` is refused at start. Nothing else
|
|
712
|
+
about bb is configurable: its arguments, its address and its environment
|
|
713
|
+
are fixed in the image.
|
|
714
|
+
|
|
715
|
+
### What runs
|
|
716
|
+
|
|
717
|
+
After the broker is ready and before sshd and host run, the supervisor
|
|
718
|
+
starts `bb-app --no-in-app-updates --server-bind-host 127.0.0.1`. Its
|
|
719
|
+
environment is the supervisor's own plus two entries:
|
|
720
|
+
|
|
721
|
+
- `BB_TELEMETRY=false`: telemetry is off.
|
|
722
|
+
- `CLAUDE_CODE_OAUTH_TOKEN`, read from `/etc/agent-login/claude-token` when
|
|
723
|
+
that file exists, so bb's Claude threads use the team's inference token.
|
|
724
|
+
The supervisor reads the file once and gives the value to bb alone: never
|
|
725
|
+
to the broker, sshd or host run, never in an argument or a log line. With
|
|
726
|
+
no file, or an empty one, bb starts without the variable. The file must
|
|
727
|
+
hold the token on one line: a token with whitespace inside it (a space, a
|
|
728
|
+
tab, a line break) is refused at start, before any child, since bb would report ready while
|
|
729
|
+
every model call failed.
|
|
730
|
+
|
|
731
|
+
bb reads its environment once, when it starts. After replacing the token,
|
|
732
|
+
restart the container; restart the agents as
|
|
733
|
+
[After changing a credential](#after-changing-a-credential) says.
|
|
734
|
+
|
|
735
|
+
In a team container, spawn bb agents with `--yolo` (bb's full mode): the
|
|
736
|
+
container is the boundary, as it is for tmux agents there. bb's sandboxed
|
|
737
|
+
modes need bubblewrap, which the image does not carry; without it every
|
|
738
|
+
command waits for a person in bb, so an agent cannot answer mail unattended.
|
|
739
|
+
|
|
740
|
+
bb keeps its data in its default directory, `/state/home/.bb`. It needs no
|
|
741
|
+
getbb.app account. At start it looks up `getbb.app` and
|
|
742
|
+
`registry.npmjs.org`; the egress boundary refuses both and bb works without
|
|
743
|
+
them, so neither needs an allowlist entry. A thread's model calls go through
|
|
744
|
+
the egress boundary as an agent's do.
|
|
745
|
+
|
|
746
|
+
Push notifications need a service outside the container. Keep them off:
|
|
747
|
+
|
|
748
|
+
```sh
|
|
749
|
+
ssh team-agent bb plugin disable push-notifications
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
### Trust
|
|
753
|
+
|
|
754
|
+
bb's API has no login. It listens on the container's loopback only: on
|
|
755
|
+
ports 38886 (the server) and 38887 (its host daemon), and on one more
|
|
756
|
+
loopback port that bb picks at each start. The service publishes no port.
|
|
757
|
+
Inside the container that changes what the trust group shares
|
|
758
|
+
([One team, one trust group](#one-team-one-trust-group)):
|
|
759
|
+
|
|
760
|
+
- Any agent can read and drive every bb thread: read it, send it a message,
|
|
761
|
+
start one, stop one.
|
|
762
|
+
- Any agent can read bb's database under `/state/home/.bb`. It holds every
|
|
763
|
+
conversation of every thread. It is on `/state`, so it outlives the
|
|
764
|
+
container and is in any copy of the volume, and OATS never trims it
|
|
765
|
+
([Where conversations are stored](#where-conversations-are-stored)).
|
|
766
|
+
- The token in bb's environment is the one every agent can already read.
|
|
767
|
+
- Any agent, one in a sandboxed bb thread included, can write every other
|
|
768
|
+
thread's storage: the threads of one bb share bb's thread-storage
|
|
769
|
+
directory under `/state/home/.bb`, and bb's own sandbox settings leave
|
|
770
|
+
the whole thread-storage directory writable. (They keep bb's database and
|
|
771
|
+
auth files read-only to a sandboxed thread.)
|
|
772
|
+
- bb's sandboxed permission modes (`auto`, `accept-edits`) are not a
|
|
773
|
+
security boundary. They limit accidents, not a determined agent: an agent
|
|
774
|
+
in such a mode can write its own instance home, which holds code that OATS
|
|
775
|
+
and the harness later run outside the sandbox. Treat an agent in a
|
|
776
|
+
sandboxed mode as able to do what any agent in the container can. OATS
|
|
777
|
+
counts no harness's sandbox as a boundary
|
|
778
|
+
([What OATS does not promise](trust-model.md#what-oats-does-not-promise)).
|
|
779
|
+
|
|
780
|
+
One bb serves one container. Never share one across teams, and never point
|
|
781
|
+
two containers at one `/state`.
|
|
782
|
+
|
|
783
|
+
### Reaching it
|
|
784
|
+
|
|
785
|
+
bb listens only inside the container, and sshd's forwarding stays off. The
|
|
786
|
+
operator reaches bb over the SSH route they already have
|
|
787
|
+
([OATS over SSH](#oats-over-ssh)), with a small relay that runs on the
|
|
788
|
+
operator's machine. It is in the checkout, never in an image, and needs only
|
|
789
|
+
Node and `ssh`:
|
|
790
|
+
|
|
791
|
+
```sh
|
|
792
|
+
node container/agent-bb/relay.mjs --ssh team-agent --listen 48886
|
|
793
|
+
```
|
|
794
|
+
|
|
795
|
+
It listens on `127.0.0.1:48886` and nowhere else; it refuses any other
|
|
796
|
+
address. Each connection becomes one SSH command channel to the container,
|
|
797
|
+
whose command pipes to bb on `127.0.0.1:38886` there. The relay keeps up to
|
|
798
|
+
nine channels on one SSH connection of its own (sshd allows ten sessions per
|
|
799
|
+
connection) and opens a separate connection for each one beyond that. If that
|
|
800
|
+
shared connection ends, it starts it again; meanwhile new connections work,
|
|
801
|
+
each on a connection of its own. TERM or Ctrl+C closes the listener and
|
|
802
|
+
every channel. Use one local port per team.
|
|
803
|
+
|
|
804
|
+
- **Desktop app, on the same machine.** Server menu, Add Server,
|
|
805
|
+
`http://127.0.0.1:48886`. Add one server per team and name it. Nothing
|
|
806
|
+
is set in bb.
|
|
807
|
+
- **Phone, or another machine.** Serve the relay's port under HTTPS on your
|
|
808
|
+
own tailnet, one port per team (Tailscale Serve:
|
|
809
|
+
`tailscale serve --bg --https=443 http://127.0.0.1:48886`). bb refuses a
|
|
810
|
+
name it was not told about, so set it once, over the SSH route:
|
|
811
|
+
|
|
812
|
+
```sh
|
|
813
|
+
ssh team-agent bb-app config set BB_APP_URL 'https://<name>[:port]'
|
|
814
|
+
```
|
|
815
|
+
|
|
816
|
+
Then add one Direct profile per team in the app, with that URL.
|
|
817
|
+
|
|
818
|
+
**Whoever reaches the relay's port, or that name, runs commands in that
|
|
819
|
+
team's container**: bb starts agents and terminals for anyone who can talk to
|
|
820
|
+
it. So the operator's machine, and the tailnet's access rules for that name,
|
|
821
|
+
become part of the team's boundary. Never use Tailscale Funnel or any public
|
|
822
|
+
address for it, and never make the relay listen wider.
|
|
823
|
+
|
|
824
|
+
The relay's `127.0.0.1` port, like bb's own in the container, has no
|
|
825
|
+
login: every local user of the operator's machine can reach it, and so can
|
|
826
|
+
run commands in the team's container. Run the relay only on a machine whose
|
|
827
|
+
only user is the operator.
|
|
828
|
+
|
|
829
|
+
### Limits
|
|
830
|
+
|
|
831
|
+
bb counts toward the container's limits. Add to `AGENT_MEMORY` and
|
|
832
|
+
`AGENT_PIDS` about 650 MB and 180 pids for bb itself, and about 200 MB and
|
|
833
|
+
30 pids for each live thread.
|
|
834
|
+
|
|
835
|
+
### When it fails
|
|
836
|
+
|
|
837
|
+
- **`AGENT_BB=1` on an image without bb.** The supervisor refuses at start,
|
|
838
|
+
before any child: one line naming `container/agent-bb`, exit 1. Select the
|
|
839
|
+
derived image.
|
|
840
|
+
- **bb is not ready.** The supervisor polls the host daemon's status
|
|
841
|
+
(`http://127.0.0.1:38887/status`) until it says `connected: true` and the
|
|
842
|
+
bb process it started is still alive, for up to 30 seconds. A bb that
|
|
843
|
+
exits first, a timeout, or a status that already answers before bb starts
|
|
844
|
+
fails the container start: neither sshd nor host run starts, the exit is
|
|
845
|
+
nonzero and the restart policy starts the container again. An unreadable
|
|
846
|
+
token file, or one whose token has whitespace inside it, fails the start
|
|
847
|
+
too, before any child.
|
|
848
|
+
- **bb ends later.** That is not a container failure. The supervisor
|
|
849
|
+
writes `agent-supervisor: bb exited (<code or signal>)`, removes what bb's
|
|
850
|
+
launcher left running, and starts bb again after 1 second, doubling to 60
|
|
851
|
+
seconds, and from 1 second again once a bb has stayed up five minutes.
|
|
852
|
+
sshd, the broker, host run and the agents keep running. A thread's
|
|
853
|
+
process ends with its bb, and the thread itself is kept: the next bb lists
|
|
854
|
+
it idle, and a message to it (`bb thread tell`) starts a new turn. bb's
|
|
855
|
+
own lookups of provider versions (`npm view`) are the one thing seen to
|
|
856
|
+
outlive a killed bb, until their own lookup fails or times out; they hold no
|
|
857
|
+
port.
|
|
858
|
+
- **Stopping.** Host run goes first, as without bb, and bb keeps running
|
|
859
|
+
while it stops the agents. Then sshd, the broker and bb are stopped side by
|
|
860
|
+
side; bb gets SIGTERM and eight seconds before SIGKILL. A bb that had to be
|
|
861
|
+
killed, or that ended while host run was still stopping agents, makes the
|
|
862
|
+
stop a failed one. The whole order fits the 50-second stop grace: at most
|
|
863
|
+
35 seconds for host run and 8 for the slowest of the three.
|
|
864
|
+
|
|
865
|
+
### What was run
|
|
866
|
+
|
|
867
|
+
Run on amd64, in the real image under the Compose flags: the build, bb ready
|
|
868
|
+
at start, a bb restart after `kill` and after `kill -9`, each followed by a
|
|
869
|
+
new turn in a thread made before it (on a mock model; after the `kill -9`
|
|
870
|
+
the thread's Claude process was gone within a second), the ordered stop,
|
|
871
|
+
acceptance with the fragment, and the relay with the real `ssh` (the bb web
|
|
872
|
+
page and API through it). **NOT RUN:** arm64; a real Claude token or a real
|
|
873
|
+
model; Tailscale Serve; the desktop and phone apps; push notifications.
|
|
874
|
+
|
|
578
875
|
## Acceptance and evidence
|
|
579
876
|
|
|
580
877
|
The host needs Docker and Node 22.5+. Export the same plain variables used for
|
|
@@ -607,7 +904,12 @@ variables. It resolves `AGENT_IMAGE` independently and requires that image's
|
|
|
607
904
|
ID, reference and start command, and its complete environment (printing only
|
|
608
905
|
names of differing variables). Other comparisons include supplementary
|
|
609
906
|
groups, namespace overrides, sysctls, published ports, resolver overrides
|
|
610
|
-
and the single network/address.
|
|
907
|
+
and the single network/address. With `AGENT_BB=1` exported it admits the bb
|
|
908
|
+
fragment's one environment entry, reads the container's listening TCP
|
|
909
|
+
sockets and requires every one to be on a loopback address except sshd's
|
|
910
|
+
port 2222, with bb's two ports among them, and requires `bb --version` to
|
|
911
|
+
equal `container/agent-bb`'s pin. Without it, a container that has `AGENT_BB`
|
|
912
|
+
set is refused. The stop timeout must be 50 seconds and the
|
|
611
913
|
healthcheck the service file's, so a container made before either was set
|
|
612
914
|
is refused until it is recreated. The OCI runtime must match the daemon's
|
|
613
915
|
independently read default; shared memory stays at Docker's 64 MiB default,
|
|
@@ -706,6 +1008,11 @@ network and fixture paths on success or failure. This is image acceptance;
|
|
|
706
1008
|
it provisions no seat or inference token. The script's `NOT RUN` items
|
|
707
1009
|
remain outside this check.
|
|
708
1010
|
|
|
1011
|
+
The same job then builds `container/agent-bb` from the image it just
|
|
1012
|
+
accepted, with no registry in between, and runs the same fixture and the
|
|
1013
|
+
same unmodified acceptance once more with `compose.agent.bb.yaml`. The bb
|
|
1014
|
+
image is not exported or published.
|
|
1015
|
+
|
|
709
1016
|
The `publish-team-image` job in
|
|
710
1017
|
[Release](../.github/workflows/release.yml) waits for the existing `publish`
|
|
711
1018
|
job, so npm publication and the GitHub Release precede the image. Its
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Kernel test ownership and real-path evidence
|
|
2
|
+
|
|
3
|
+
K2 of the second systemic review, findings 13.14, 13.16 and 13.21. This
|
|
4
|
+
records explicit removals and replacements; it does not claim a source-text
|
|
5
|
+
match proved behaviour.
|
|
6
|
+
|
|
7
|
+
## Removed optional native tests
|
|
8
|
+
|
|
9
|
+
These three tests ran a provider or `aw` directly, never kernel consumption:
|
|
10
|
+
|
|
11
|
+
- `test/oats-aweb-hook-1-10.test.mjs`, “real aw fixture: unattached grant
|
|
12
|
+
home reports the released custody locator error”.
|
|
13
|
+
- `test/oats-aweb-hook-1-13.test.mjs`, “real aw 1.36.33 custody preflight
|
|
14
|
+
reports needs-configuration instead of faking a pass”.
|
|
15
|
+
- The same file's “real aw fixture: unattached grant home reports the released
|
|
16
|
+
custody locator error”.
|
|
17
|
+
|
|
18
|
+
Ordinary kernel CI provisioned neither `AW_REAL_CLI_BIN` nor
|
|
19
|
+
`AW_REAL_GRANT_FIXTURE`, so these were normally skipped, not successful native
|
|
20
|
+
regressions. The locator case was also duplicated inside the kernel. The
|
|
21
|
+
provider package owns these native paths. All three have released counterparts
|
|
22
|
+
at `v1.43.0` (commit `00f60a241cfb5bc5aa6acbf1ebcb111756ee8fa0`), in its
|
|
23
|
+
[`test/oats-aweb-hook-1-13.test.mjs`](https://github.com/awebai/oats-aweb/blob/v1.43.0/test/oats-aweb-hook-1-13.test.mjs):
|
|
24
|
+
|
|
25
|
+
| Removed kernel case | Released covering test |
|
|
26
|
+
| --- | --- |
|
|
27
|
+
| hook-1-10 unattached locator | “real aw fixture: unattached grant home reports the released custody locator error” (line 212) |
|
|
28
|
+
| hook-1-13 custody preflight | “real aw at the floor: custody preflight reports needs-configuration instead of faking a pass” (line 194) |
|
|
29
|
+
| hook-1-13 unattached locator | The same released locator test (line 212) |
|
|
30
|
+
|
|
31
|
+
The outcome assertions match the released source, independently checked with
|
|
32
|
+
`git show v1.43.0:test/oats-aweb-hook-1-13.test.mjs`. Their removal makes no
|
|
33
|
+
claim that those package opt-ins run in CI. Admission floors differ: the
|
|
34
|
+
released custody test accepts 1.36.32+ and its locator test 1.36.13+, while
|
|
35
|
+
the removed kernel copies required 1.36.33+. Future kernel tests titled `real aw`/`real-aw` fail
|
|
36
|
+
the root gate if skipped; the count, file and title are reported.
|
|
37
|
+
|
|
38
|
+
No version-named suite is retired by this change. Their substantive provider
|
|
39
|
+
assertions must be transferred and present in the pinned mirrored release,
|
|
40
|
+
and K1's kernel retire-hook contract test must land, before that retirement.
|
|
41
|
+
|
|
42
|
+
## Removed provider-source checks from the steward guidance test
|
|
43
|
+
|
|
44
|
+
The following checks read implementation text in the provider mirror. They
|
|
45
|
+
were removed because they did not execute the advertised behaviour:
|
|
46
|
+
|
|
47
|
+
- Literal spelling of the setup check's `console.log(JSON.stringify(...))`.
|
|
48
|
+
- Literal `predictedTeam` assignment and signup return-object spelling.
|
|
49
|
+
- Presence of the setup policy/default-preservation throw statements.
|
|
50
|
+
|
|
51
|
+
These groups are the content at lines 136–138, 152–153 and 227–229 of the
|
|
52
|
+
spec's pinned source, kernel `3a5503c2993a307a0bb48d0b41dcab7d175adc27`.
|
|
53
|
+
Their line numbers moved in later main commits. Other provider-source checks
|
|
54
|
+
(the four-code loop, root construction, invite output and floor extraction)
|
|
55
|
+
remain; this change claims no blanket conversion of the steward file.
|
|
56
|
+
|
|
57
|
+
The prose test “getting-started: a join never runs aw team ensure”, at the
|
|
58
|
+
original 3a5503c2 lines 541–549, remains. It guards the documented workflow
|
|
59
|
+
contract in [the getting-started skill](../../skills/oats-getting-started/SKILL.md):
|
|
60
|
+
team creation belongs only to step 5 for a new workspace; joining an existing
|
|
61
|
+
workspace must not create a second team. The broker-before-spawn and later
|
|
62
|
+
souls.launch/reviewer-model guidance guards also remain, separately; the
|
|
63
|
+
launch-preference contract is documented in
|
|
64
|
+
[the launch preference design](2026-09-28-soul-launch-preference.md).
|
|
65
|
+
|
|
66
|
+
## Container checks
|
|
67
|
+
|
|
68
|
+
The entrypoint test now checks command/argument structure (one final `exec`
|
|
69
|
+
to the installed supervisor, NSS export and host-key command) and the Docker
|
|
70
|
+
`COPY` instruction, instead of matching word fragments.
|
|
71
|
+
|
|
72
|
+
The auth test invokes the real acceptance orchestration through an injected
|
|
73
|
+
Docker subprocess boundary. Its strict double returns nonzero and prints
|
|
74
|
+
unexpected argv. It checks the complete emitted Claude command, scratch-cwd
|
|
75
|
+
program and absence of a Docker `--workdir` pointing at the instance. This
|
|
76
|
+
pins orchestration argv; it captures and asserts the simulated report rather
|
|
77
|
+
than printing fixture PASS receipts, and does not claim Docker accepted it. Team-image CI
|
|
78
|
+
owns real image/container acceptance. Production still defaults to
|
|
79
|
+
`spawnSync`, and the CLI calls the orchestration exactly as before.
|
|
80
|
+
|
|
81
|
+
The provider's `test/kernel-module-boundary.test.mjs` remains a legitimate
|
|
82
|
+
static module boundary check and is not removed or weakened by this work.
|