@awebai/oats 0.69.17 → 0.69.19
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 +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +8 -1
- package/docs/container.md +345 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +100 -53
- package/docs/desktop.md +53 -24
- package/docs/execution-targets.md +66 -48
- package/docs/implementation.md +8 -7
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +7 -7
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +30 -23
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/servers.md +5 -3
- package/docs/souls-and-instances.md +51 -27
- package/docs/trust-model.md +119 -0
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +45 -19
- package/docs/workspaces.md +3 -3
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +26 -11
- package/lib/errors.mjs +1 -1
- package/lib/home-owner.mjs +25 -0
- package/lib/host-run-admission.mjs +21 -0
- package/lib/host-run-child.mjs +31 -0
- package/lib/host-run-work.mjs +150 -0
- package/lib/host-run.mjs +43 -29
- package/lib/instance-naming.mjs +26 -44
- package/lib/packages.mjs +0 -43
- package/lib/pi-bridge.mjs +18 -6
- package/lib/schedule.mjs +5 -3
- package/lib/servers.mjs +4 -3
- package/lib/session-end.mjs +9 -0
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +144 -51
- package/lib/session-seen.mjs +16 -11
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +4 -2
- package/packages/client/above-tested-notice.mjs +30 -0
- package/packages/client/above-tested.mjs +225 -0
- package/packages/client/cli-locator.mjs +67 -52
- package/packages/client/deployment-label.mjs +4 -4
- package/packages/client/instance-name.mjs +5 -29
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/packages/client/session-start.mjs +31 -3
- package/packages/client/workspace-choices.mjs +1 -1
- package/packages/client/workspace-views.mjs +1 -1
- package/packages/record/README.md +10 -8
- package/packages/record/lib/process-identity.mjs +14 -36
- package/packages/tui/lib/read.mjs +19 -3
- package/skills/oats-getting-started/SKILL.md +33 -4
package/README.md
CHANGED
|
@@ -271,7 +271,7 @@ It is optional: agents run, message each other and follow their schedules whethe
|
|
|
271
271
|
|
|
272
272
|
3. **Answer its questions.** It asks everything in one round and lists the changes it will make to your computer; say yes to them. After that you only approve the GitHub login and type a password or token if one is asked for.
|
|
273
273
|
|
|
274
|
-
Your agent then installs OATS, OATS Desktop and
|
|
274
|
+
Your agent then installs OATS and what it needs, and OATS Desktop unless you decline it: the Desktop is optional, and the terminal UI (`oats tui`) or the command line work without it. It creates a private GitHub repository for your agents' shared setup (the workspace), creates the group your agents message each other in (on [aweb](https://aweb.ai), with no sign-up), and starts the **setup expert**, an agent that adapts the defaults with you. OATS Desktop, if you kept it, opens on it. Allow 5 to 10 minutes.
|
|
275
275
|
|
|
276
276
|
**To join a workspace a teammate already runs,** say instead *"Join our OATS workspace at \<its GitHub repository\>, following https://github.com/oats-project/oats"*. Your teammate's agent makes you an invite, which your teammate passes to you privately; your agent tells you when to paste it.
|
|
277
277
|
|
package/bin/oats.mjs
CHANGED
|
@@ -1423,11 +1423,12 @@ async function instanceUpgradeCmd(name, bail) {
|
|
|
1423
1423
|
} catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
|
|
1424
1424
|
}
|
|
1425
1425
|
|
|
1426
|
-
/** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a
|
|
1427
|
-
*
|
|
1428
|
-
* (lib/core.mjs suggestSpawnName).
|
|
1426
|
+
/** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a
|
|
1427
|
+
* --suggest-name spawn would get, chosen here for a spawn that may land on another machine
|
|
1428
|
+
* (lib/core.mjs suggestSpawnName). --soul is optional, shape-checked when given and unused for the
|
|
1429
|
+
* name. Never routed: --server is refused before the route dispatch. */
|
|
1429
1430
|
async function instanceSuggestNameCmd(bail) {
|
|
1430
|
-
const usage = "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
|
|
1431
|
+
const usage = "usage: oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
|
|
1431
1432
|
// A flag's value as given, the empty text included (`--task ""` is an empty task, not a missing one).
|
|
1432
1433
|
const value = (name) => {
|
|
1433
1434
|
const i = args.indexOf(`--${name}`);
|
|
@@ -1437,7 +1438,6 @@ async function instanceSuggestNameCmd(bail) {
|
|
|
1437
1438
|
return v;
|
|
1438
1439
|
};
|
|
1439
1440
|
const soul = value("soul"), task = value("task"), taskFile = value("task-file");
|
|
1440
|
-
if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
|
|
1441
1441
|
if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
|
|
1442
1442
|
let text = task;
|
|
1443
1443
|
if (taskFile !== undefined) { try { text = readFileSync(taskFile, "utf8"); } catch (e) { return bail("E_BAD_ARGS", `--task-file ${taskFile} cannot be read (${e.code || "error"})`); } }
|
|
@@ -5086,8 +5086,8 @@ Usage:
|
|
|
5086
5086
|
includes the decision revision for confirmation
|
|
5087
5087
|
[--suggest-name] no --name, --purpose or --expect-decision: the
|
|
5088
5088
|
soul's harness, on the machine that spawns, names
|
|
5089
|
-
the instance for its task (
|
|
5090
|
-
made unique); else it is numbered, and
|
|
5089
|
+
the instance for its task (the model's whole
|
|
5090
|
+
<work>-<role>, made unique); else it is numbered, and
|
|
5091
5091
|
naming.reason says why (claude and pi); on a
|
|
5092
5092
|
preview or an apply
|
|
5093
5093
|
[--expect-decision <rev>] bind apply to the previewed decision; drift refuses
|
|
@@ -5249,13 +5249,14 @@ Usage:
|
|
|
5249
5249
|
record that this instance does the same work as
|
|
5250
5250
|
its parent (on needs a recorded parent); clients
|
|
5251
5251
|
draw the parent line for it; off removes it
|
|
5252
|
-
oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi]
|
|
5252
|
+
oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi]
|
|
5253
5253
|
[--model <m>] [--launch-config <n>] [--dir <d>] [--json]
|
|
5254
|
-
a name for a spawn
|
|
5255
|
-
|
|
5256
|
-
|
|
5257
|
-
|
|
5258
|
-
|
|
5254
|
+
a name for a spawn by this machine's harness, as a
|
|
5255
|
+
preview's --suggest-name chooses it (the model's whole
|
|
5256
|
+
<work>-<role>), not made unique (where it lands decides
|
|
5257
|
+
that); else numbered, and naming.reason says why.
|
|
5258
|
+
--soul is optional, checked as a soul name's shape and
|
|
5259
|
+
not used for the name. Reads only this machine's launch
|
|
5259
5260
|
configurations; writes and reserves nothing; no --server
|
|
5260
5261
|
oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
|
|
5261
5262
|
[--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
|
package/docs/capabilities.md
CHANGED
|
@@ -32,6 +32,13 @@ its skills flat into `<home>/.agents/skills/<skill>/`), and the instance's `AGEN
|
|
|
32
32
|
generated without changing the canonical soul. Nothing is installed or
|
|
33
33
|
activated at a deployment.
|
|
34
34
|
|
|
35
|
+
Trust is decided once, where the workspace declares the member or the
|
|
36
|
+
package. When the kernel later reports a capability as trusted, it has
|
|
37
|
+
checked only that what it is about to run is the copy made at spawn and where
|
|
38
|
+
that copy came from. It judges nothing about the code, and the copy is in the
|
|
39
|
+
home its agent can write, so the check is no defence against that agent
|
|
40
|
+
([trust-model.md](trust-model.md)).
|
|
41
|
+
|
|
35
42
|
## Manifest
|
|
36
43
|
|
|
37
44
|
A self-contained package has an `oats.json`:
|
|
@@ -1181,7 +1188,7 @@ own configuration.
|
|
|
1181
1188
|
naming the release, not with a schema error.
|
|
1182
1189
|
3. The blast radius is every soul that composes the capability, on every host
|
|
1183
1190
|
below the release: one capability can stop every developer soul of a
|
|
1184
|
-
workspace from spawning, as in
|
|
1191
|
+
workspace from spawning, as in lab-oats-workspace#22, where one capability
|
|
1185
1192
|
took down every developer soul.
|
|
1186
1193
|
4. To limit it, put the hook in a small capability composed only by the souls
|
|
1187
1194
|
that need the setup.
|
package/docs/container.md
CHANGED
|
@@ -8,6 +8,26 @@ then runs `oats host run`
|
|
|
8
8
|
([The kernel's periodic work](#the-kernels-periodic-work)). Deployment setup
|
|
9
9
|
and seat admission belong to the operator.
|
|
10
10
|
|
|
11
|
+
## One team, one trust group
|
|
12
|
+
|
|
13
|
+
The service runs every agent, sshd and `oats host run` as one user, so the
|
|
14
|
+
container is one trust group ([trust-model.md](trust-model.md)):
|
|
15
|
+
|
|
16
|
+
- **It is the unit of compromise.** If one agent in it is subverted, treat
|
|
17
|
+
every agent, seat and credential in it as subverted. Each agent can read
|
|
18
|
+
every seat under `/state/seats`, the Claude token and sshd's host keys,
|
|
19
|
+
rewrite the launch configurations in `/state/deploy` and the schedule
|
|
20
|
+
registry in `/state/home`, rewrite the wake registrations under
|
|
21
|
+
`/state/home/.config/aw/wake`, and stop sshd, `oats host run`, the wake
|
|
22
|
+
broker or its supervisor.
|
|
23
|
+
- **It holds one team, never several.** Agents that must not be able to read
|
|
24
|
+
each other's identities or affect each other's work get separate
|
|
25
|
+
containers. Nothing in OATS makes sharing one safe.
|
|
26
|
+
- **Its Git credentials must not reach the workspace's own code.** A
|
|
27
|
+
workspace member is used at its latest commit, so an agent that can push to
|
|
28
|
+
a member's default branch changes what every deployment of that workspace
|
|
29
|
+
runs ([trust-model.md](trust-model.md#code-from-outside-the-group)).
|
|
30
|
+
|
|
11
31
|
## Configuration contract
|
|
12
32
|
|
|
13
33
|
The same inputs apply to a Compose service or a platform's container spec:
|
|
@@ -48,7 +68,7 @@ must succeed during the build.
|
|
|
48
68
|
|
|
49
69
|
`libnss-wrapper` is the extra OS package needed for arbitrary UID support.
|
|
50
70
|
No credentials or SSH host keys are baked in. The build context allowlist
|
|
51
|
-
excludes everything except the image
|
|
71
|
+
excludes everything except the explicitly listed image inputs.
|
|
52
72
|
|
|
53
73
|
A derived image may add reviewed OS tools with `USER root` and `RUN`, then
|
|
54
74
|
restore `USER agent`. Those build steps use the system passwd/group database.
|
|
@@ -184,6 +204,97 @@ Preview runs no provider hook and does not validate a missing seat. Apply
|
|
|
184
204
|
only after reviewing it and provisioning its seat; use the same arguments
|
|
185
205
|
without `--preview`. Keep the team and controller keys outside the container.
|
|
186
206
|
|
|
207
|
+
### Making a seat
|
|
208
|
+
|
|
209
|
+
`identity.source` is the legacy route of `oats.aweb`: the spawn copies an
|
|
210
|
+
existing aweb identity into the new home and connects it. It is the route
|
|
211
|
+
that works in a container today, and it stays labelled legacy until the
|
|
212
|
+
package has a route that admits a seat itself.
|
|
213
|
+
|
|
214
|
+
A seat is the `.aw` directory of one admitted team member. On both routes
|
|
215
|
+
below the seat's signing key is created in the container, over the SSH
|
|
216
|
+
route, so it is on `/state` and never leaves it; the team's controller key
|
|
217
|
+
stays outside. Which route applies depends on who holds that controller key.
|
|
218
|
+
|
|
219
|
+
**A team whose controller key the operator holds** (a self-hosted server, or
|
|
220
|
+
a team the operator brought). The seat asks, the controller admits it, the
|
|
221
|
+
seat fetches its certificate:
|
|
222
|
+
|
|
223
|
+
```sh
|
|
224
|
+
# 1. In the container, once per seat. Prints the add-member command.
|
|
225
|
+
mkdir -p /state/seats/<alias> && cd /state/seats/<alias>
|
|
226
|
+
aw id team request --create-local-key --team <team>:<domain> --name <alias>
|
|
227
|
+
|
|
228
|
+
# 2. Outside the container, where the team's controller key is: run the
|
|
229
|
+
# printed `aw id team add-member` command. It answers a certificate id.
|
|
230
|
+
|
|
231
|
+
# 3. In the container, in the same directory:
|
|
232
|
+
aw id team fetch-cert --team <team> --namespace <domain> --cert-id <certificate-id>
|
|
233
|
+
aw workspace connect --service <the team's aweb server>
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
An invite cannot be used here: a token made with the operator's own
|
|
237
|
+
controller key is redeemed only on the machine that holds that key
|
|
238
|
+
(`aw id team accept-invite --help`).
|
|
239
|
+
|
|
240
|
+
**A team hosted by the aweb service.** The service holds the controller key
|
|
241
|
+
and issues an invite token (`aw_inv_…`); the seat redeems it:
|
|
242
|
+
|
|
243
|
+
```sh
|
|
244
|
+
# In the container, once per seat:
|
|
245
|
+
mkdir -p /state/seats/<alias> && cd /state/seats/<alias>
|
|
246
|
+
aw id team accept-invite <token> --name <alias>
|
|
247
|
+
aw workspace connect --service <the team's aweb server>
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
The commands are as `aw` 1.36.57 documents them in its own `--help`. The
|
|
251
|
+
sequences have not yet been run in a container.
|
|
252
|
+
|
|
253
|
+
Before it copies or locks anything, the spawn checks five things, and
|
|
254
|
+
refuses the seat with its fix when one is missing:
|
|
255
|
+
|
|
256
|
+
- `signing.key`, the member's key;
|
|
257
|
+
- the server: `aweb_url` in `workspace.yaml` (`aw workspace connect` writes
|
|
258
|
+
it). The seat's service comes only from there: `OATS_AWEB_URL` is not read;
|
|
259
|
+
- the team: the deployment's default team, or else the active team in
|
|
260
|
+
`teams.yaml`;
|
|
261
|
+
- `teams.yaml` itself;
|
|
262
|
+
- a membership of that team in `teams.yaml`, matched as aw matches it. When
|
|
263
|
+
there is none, accept the team's invite (`aw id team accept-invite`) or
|
|
264
|
+
fetch its certificate (`aw id team fetch-cert`) in the seat's directory, or
|
|
265
|
+
make the seat's team the deployment's default.
|
|
266
|
+
|
|
267
|
+
The member's certificate file under `team-certs/` is not checked at that
|
|
268
|
+
point, and the seat does not work without it: the spawn copies the seat,
|
|
269
|
+
fails when it connects or reads the identity back, and removes the copy.
|
|
270
|
+
|
|
271
|
+
One seat serves one instance at a time. The spawn writes
|
|
272
|
+
`.aw-retained-seat.json` beside the seat's `.aw` and refuses a second spawn
|
|
273
|
+
while the first instance's home exists; retiring that instance releases the
|
|
274
|
+
seat. Every change of that lock is one guarded step, using two private files
|
|
275
|
+
beside it, `.aw-retained-seat.json.guard` and `.aw-retained-seat.json.held`.
|
|
276
|
+
A change that was killed can leave one of them behind. The next spawn or
|
|
277
|
+
take-over then refuses, naming the file and its fix, and the next retire
|
|
278
|
+
reports it. Nothing removes such a file automatically. Two cases need the
|
|
279
|
+
operator:
|
|
280
|
+
|
|
281
|
+
- **The holder's home exists and its runtime is known to be dead.** Spawn
|
|
282
|
+
with `identity.takeOver=true`. If that runtime is in fact alive, there are
|
|
283
|
+
then two seats with one key; stop the old one.
|
|
284
|
+
- **The holder's home is not on this host** (a home removed by hand, a volume
|
|
285
|
+
restored, or a home on another host that shares the seat). The spawn
|
|
286
|
+
refuses, naming the holder as the lock records it (instance, host, since
|
|
287
|
+
and home) and the release. A lock is never released by age. Once that seat
|
|
288
|
+
is confirmed gone, spawn with `identity.takeOver=true`, which clears the lock
|
|
289
|
+
with a warning, or remove the lock file the refusal names.
|
|
290
|
+
|
|
291
|
+
Retiring never revokes the member's certificate: on a server that is not the
|
|
292
|
+
hosted service, whoever holds the controller key removes a member
|
|
293
|
+
(`aw id team remove-member`). A seat's spawn that fails or is killed never
|
|
294
|
+
deletes the standing identity's workspace at the server: its retire releases
|
|
295
|
+
the lock and prints the `aw workspace connect` that binds the identity back to
|
|
296
|
+
its seat.
|
|
297
|
+
|
|
187
298
|
The pinned OATS release supports this file-backed launch configuration:
|
|
188
299
|
|
|
189
300
|
```yaml
|
|
@@ -201,11 +312,50 @@ Select it with `--launch-config team-claude`. The operator provisions only a
|
|
|
201
312
|
by every agent in the same trust group; read-only mounting does not hide it
|
|
202
313
|
or narrow its authority. Never share the mount across trust groups.
|
|
203
314
|
|
|
315
|
+
### After changing a credential
|
|
316
|
+
|
|
317
|
+
A resume starts an agent under the values its last start recorded. When the
|
|
318
|
+
value behind a reference has changed, such as a new token in
|
|
319
|
+
`/etc/agent-login/claude-token`, every resume of that home is refused with
|
|
320
|
+
`E_LAUNCH_ENV_CHANGED`, by the sweep and by hand
|
|
321
|
+
([execution-targets.md](execution-targets.md#resume-after-a-shutdown)). The
|
|
322
|
+
agents do not come back when the container restarts, and host run's log
|
|
323
|
+
shows them as `refused`.
|
|
324
|
+
|
|
325
|
+
So after replacing a referenced credential, start each agent once yourself.
|
|
326
|
+
An ordinary start does not compare; it uses the new value and records it:
|
|
327
|
+
|
|
328
|
+
```sh
|
|
329
|
+
# In the container:
|
|
330
|
+
oats session restart --home <abs> # an agent that runs
|
|
331
|
+
oats session start --home <abs> # one that is stopped
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
An ordinary start begins a new conversation; it does not resume the earlier
|
|
335
|
+
one.
|
|
336
|
+
|
|
337
|
+
### Where conversations are stored
|
|
338
|
+
|
|
339
|
+
With `CLAUDE_CONFIG_DIR: /state/home/.claude`, Claude Code writes each
|
|
340
|
+
session's transcript under that directory. It holds what the agents read and
|
|
341
|
+
wrote, tool output included: mail they opened, and the results of calls made
|
|
342
|
+
on their behalf.
|
|
343
|
+
|
|
344
|
+
- It is one directory for every agent of the container, and every agent can
|
|
345
|
+
read it ([One team, one trust group](#one-team-one-trust-group)).
|
|
346
|
+
- It is on `/state`, so it outlives the container and is in any copy of the
|
|
347
|
+
volume.
|
|
348
|
+
- OATS neither trims nor deletes it. Retiring an instance removes its home,
|
|
349
|
+
not its transcripts. The operator decides how long they are kept and
|
|
350
|
+
removes them.
|
|
351
|
+
|
|
204
352
|
## The kernel's periodic work
|
|
205
353
|
|
|
206
354
|
A container has no launchd and no systemd user manager, so no timer runs
|
|
207
|
-
the kernel's periodic work in it.
|
|
208
|
-
|
|
355
|
+
the kernel's periodic work in it. After the entrypoint prepares NSS and
|
|
356
|
+
SSH host keys, an image-local Node supervisor starts `aw wake run`. It waits
|
|
357
|
+
for `aw wake status --json` to report `daemon_running: true` and name that
|
|
358
|
+
live child's PID as `daemon_pid`, then starts sshd and `oats host run`
|
|
209
359
|
([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)), one
|
|
210
360
|
foreground process that lasts as long as the container.
|
|
211
361
|
|
|
@@ -216,31 +366,36 @@ foreground process that lasts as long as the container.
|
|
|
216
366
|
deployments the container's host schedule registry lists and lists the
|
|
217
367
|
instances. With no deployment registered it ticks nothing and says so.
|
|
218
368
|
- **On the runtime's SIGTERM** (`docker stop`, `docker restart`, a Compose
|
|
219
|
-
`down` or a recreate) it starts no further minute
|
|
220
|
-
|
|
369
|
+
`down` or a recreate) it starts no further minute. Active launch work gets
|
|
370
|
+
10 seconds to finish naturally; then a private admission fence prevents
|
|
371
|
+
further schedule, trigger, wake or resume launches and owned children get
|
|
372
|
+
a 5-second cancellation phase. An interrupted launch stays `unknown` and
|
|
373
|
+
needs reconciliation; a timeout does not prove that nothing ran. Host run
|
|
374
|
+
then lists and stops every running agent side by side: SIGTERM to the
|
|
221
375
|
harness and a wait of 20 seconds, never escalated. Each home's stop record
|
|
222
376
|
says it was stopped with the host, so the home reads `lost` and the next
|
|
223
|
-
start's sweep resumes it. Then it exits 0 and the
|
|
377
|
+
start's sweep resumes it. Then it exits 0 and the supervisor stops the
|
|
378
|
+
broker. Work that cannot be killed retains the host-run claim; the runtime's
|
|
379
|
+
final kill is a failed stop, never proof of an ordered shutdown.
|
|
224
380
|
- **Its progress** is one line per event on standard error, beside sshd's
|
|
225
381
|
log, in `docker logs`.
|
|
226
382
|
|
|
227
383
|
What the image's files fix for that:
|
|
228
384
|
|
|
229
|
-
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
alive and the pane had received nothing.
|
|
385
|
+
- **PID-only tini signals the Node supervisor.** It forwards TERM to host
|
|
386
|
+
run alone and keeps the wake broker alive until host run finishes stopping
|
|
387
|
+
the agents. Then it stops sshd and the broker in parallel. A broker or
|
|
388
|
+
host-run exit is reported and drains the other children before a nonzero
|
|
389
|
+
container exit, so
|
|
390
|
+
the restart policy can restart it. The broker runs as the agent uid; its
|
|
391
|
+
default state directory is `/state/home/.config/aw/wake`, so registrations
|
|
392
|
+
survive container replacement and it starts again even with no spawn.
|
|
238
393
|
- **`stop_grace_period: 45s`** in the Compose service. Docker's default is
|
|
239
394
|
10 seconds, shorter than the 20 seconds each harness is given; a container
|
|
240
395
|
killed at the timeout leaves agents that were not stopped in order. A
|
|
241
396
|
platform that does not read the Compose file needs the same stop timeout
|
|
242
397
|
in its container spec.
|
|
243
|
-
- **A healthcheck on sshd.**
|
|
398
|
+
- **A healthcheck on sshd.** The supervisor reports an sshd exit; if
|
|
244
399
|
sshd ends, the agents and the tick go on and the operator's route is gone.
|
|
245
400
|
The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
|
|
246
401
|
second timeout, 3 retries, 10 second start period), so the container then
|
|
@@ -258,8 +413,10 @@ What the image's files fix for that:
|
|
|
258
413
|
|
|
259
414
|
`oats host run` refuses to start while another one holds the container's
|
|
260
415
|
lock (`E_HOST_RUN_BUSY`); the container then exits 1 and the restart policy
|
|
261
|
-
starts it again. A lock left by an earlier run
|
|
262
|
-
|
|
416
|
+
starts it again. A lock left by an earlier run is taken over when its pid
|
|
417
|
+
is gone or has another process start time. A visible live holder, or a
|
|
418
|
+
holder whose start cannot be read, stays held; see
|
|
419
|
+
[Session recovery](execution-targets.md#which-losses-come-back).
|
|
263
420
|
|
|
264
421
|
The schedule tick covers only registered deployments. Register the
|
|
265
422
|
deployment once, after `server connect`
|
|
@@ -338,3 +495,173 @@ fixtures. The SSH guard requires flat
|
|
|
338
495
|
`Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
|
|
339
496
|
equals-delimited keywords and quoted keywords. Follow the repository's
|
|
340
497
|
local check limits; full suites run in CI.
|
|
498
|
+
|
|
499
|
+
## Image CI and publication
|
|
500
|
+
|
|
501
|
+
[Team image](../.github/workflows/team-image.yml) builds `container/agent`
|
|
502
|
+
from the pull request's exact head commit, on an Ubuntu 24.04 amd64 runner.
|
|
503
|
+
It also supports a manual verification run at the selected ref. Actions are
|
|
504
|
+
pinned by commit, and the verification token has only `contents: read`.
|
|
505
|
+
After acceptance, verification also runs the real Docker export, Skopeo
|
|
506
|
+
compression and configuration-digest checks used before publication, without
|
|
507
|
+
a registry credential or any registry/release write.
|
|
508
|
+
|
|
509
|
+
Manual verification offers two additional proofs:
|
|
510
|
+
|
|
511
|
+
- `default_payload_proof` builds the registry context a second time without
|
|
512
|
+
the additive BuildKit mount and compares the full installed `/opt/agent`
|
|
513
|
+
payload: file paths, sizes, content hashes, modes, directories and link
|
|
514
|
+
targets. Image history and IDs may differ; payload differences fail.
|
|
515
|
+
- `packed_kernel` prepares a private context from the selected commit and
|
|
516
|
+
runs the image with that commit's own `npm pack` kernel. This job is
|
|
517
|
+
manual-only until the image owner's compatible final baseline lands.
|
|
518
|
+
Ordinary PR verification keeps the committed context in the meantime.
|
|
519
|
+
An incompatible baseline fails explicitly, with no registry-kernel fallback
|
|
520
|
+
and no wider lock allowance. The committed baseline needs final OATS
|
|
521
|
+
0.69.18+ and aw 1.36.59+ with the compatible exact runtime closure.
|
|
522
|
+
With the committed baseline, the packed job refuses; its positive real
|
|
523
|
+
packed-image acceptance is **NOT RUN** until that compatible baseline lands.
|
|
524
|
+
|
|
525
|
+
Packing disables lifecycle scripts and uses a private npm home/cache, empty
|
|
526
|
+
user/global configs and an explicit public registry. Every packed file must
|
|
527
|
+
be in the kernel's literal `package.json.files` list, including the explicitly
|
|
528
|
+
declared manifest and license. The tarball is checked against its SHA512
|
|
529
|
+
integrity and the exact checkout's regular Git files, sizes, bytes and modes;
|
|
530
|
+
links, unsafe paths and untracked/generated payloads refuse. The source
|
|
531
|
+
checkout stays unchanged.
|
|
532
|
+
|
|
533
|
+
Only the private image manifest changes to the fixed
|
|
534
|
+
`file:../oats-build-inputs/oats-pr-kernel.tgz` dependency. The same tarball is
|
|
535
|
+
provided in the closed context and a private host-side sibling directory,
|
|
536
|
+
so npm lock generation and the build resolve the same bytes. The existing
|
|
537
|
+
`npm ci --ignore-scripts` RUN gets a read-only context mount at
|
|
538
|
+
`/opt/oats-build-inputs`; no tarball COPY, build argument, new lifecycle
|
|
539
|
+
execution or runtime mount is added. The registry release context and its
|
|
540
|
+
strict metadata checks keep their own path. Both adapters protect every
|
|
541
|
+
unrelated CLI and lock entry, addition, removal and root/metadata field.
|
|
542
|
+
|
|
543
|
+
After the unmodified acceptance, the packed job checks the installed kernel's
|
|
544
|
+
exact own-file set, sizes, modes and hashes against the HEAD inventory in
|
|
545
|
+
the same accepted container. Version equality alone is insufficient: two
|
|
546
|
+
commits may share a version. Separately resolved nested dependencies remain
|
|
547
|
+
governed by the image lock. A changed inventory artifact or installed file
|
|
548
|
+
fails before digest preparation. The closed context, tarball, generated
|
|
549
|
+
manifest/lock, source inventory and build metadata are retained as artifacts;
|
|
550
|
+
npm config/cache are outside the uploaded context. Source SHA and
|
|
551
|
+
integrity/inventory/lock hashes are retained in those artifacts. Acceptance
|
|
552
|
+
reports the image ID in its log and passes it between workflow steps to bind
|
|
553
|
+
the export to the accepted image. These checks do not broaden the receipt's
|
|
554
|
+
supervisor, agent or containment claims.
|
|
555
|
+
|
|
556
|
+
The shared fixture, `.github/scripts/team-image-accept.sh`, starts the
|
|
557
|
+
committed Compose service on a disposable internal bridge with IPv6 off and
|
|
558
|
+
an isolated gateway (Docker Engine 28+). It provisions private state, a
|
|
559
|
+
throwaway SSH public key, a resolver file and an empty root:20001 0750 login
|
|
560
|
+
directory, waits for the service's SSH healthcheck, then runs the image's
|
|
561
|
+
unmodified `accept.sh --evidence target-amd64`. Cleanup removes the service,
|
|
562
|
+
network and fixture paths on success or failure. This is image acceptance;
|
|
563
|
+
it provisions no seat or inference token. The script's `NOT RUN` items
|
|
564
|
+
remain outside this check.
|
|
565
|
+
|
|
566
|
+
The `publish-team-image` job in
|
|
567
|
+
[Release](../.github/workflows/release.yml) waits for the existing `publish`
|
|
568
|
+
job, so npm publication and the GitHub Release precede the image. Its
|
|
569
|
+
single job-level `if: ${{ false }}` keeps publication disabled pending the
|
|
570
|
+
registry decision for the proposed `ghcr.io/oats-project/team-agent` target.
|
|
571
|
+
GHCR creates a new package as private by default. Verification remains
|
|
572
|
+
enabled. Enabling publication requires the registry decision and a reviewed
|
|
573
|
+
change to the switch.
|
|
574
|
+
|
|
575
|
+
Before enabling, the registry owner must complete these separately authorized
|
|
576
|
+
setup steps and include their evidence as a checklist in the enabling PR:
|
|
577
|
+
|
|
578
|
+
1. Push the approved digest from a verified run.
|
|
579
|
+
2. Set the package visibility to public.
|
|
580
|
+
3. Grant this repository's Actions write access.
|
|
581
|
+
4. Record the pinned-client observation that an unused exact version tag
|
|
582
|
+
returns `manifest unknown`.
|
|
583
|
+
|
|
584
|
+
Package creation is this manual setup step, never an automatic release-job
|
|
585
|
+
bootstrap. The job treats only `manifest unknown` as an absent tag. It refuses
|
|
586
|
+
`name unknown`, `denied`, authentication and transport errors. The registry
|
|
587
|
+
owner resolves bootstrap and access problems without broadening the matcher.
|
|
588
|
+
|
|
589
|
+
Publication requires a stable `vX.Y.Z` release tag (at least 0.69.18).
|
|
590
|
+
The release job copies only the tagged image's literal `.dockerignore`
|
|
591
|
+
allowlist into a private build context, sets its OATS dependency to exactly
|
|
592
|
+
`X.Y.Z`, and regenerates that copy's lock with npm scripts disabled and the
|
|
593
|
+
public registry selected explicitly. The source checkout and Dockerfile
|
|
594
|
+
stay unchanged. The committed aw pin must be a final version of at least
|
|
595
|
+
1.36.59 and match its lock; prereleases cannot pass the guard.
|
|
596
|
+
|
|
597
|
+
The generated lock may change only the OATS entry, its root dependency
|
|
598
|
+
specification and its own exact runtime dependencies. Other entries,
|
|
599
|
+
including aw, Claude and unrelated transitive packages, must remain equal
|
|
600
|
+
to the committed lock, including additions and removals. Registry version,
|
|
601
|
+
tarball URL and SHA512 integrity must match the new kernel and its exact
|
|
602
|
+
dependencies. A missing compatible committed baseline fails the build;
|
|
603
|
+
it does not widen the allowance. The image owner maintains that baseline.
|
|
604
|
+
The effective manifest, generated lock and source/version/integrity metadata
|
|
605
|
+
are retained as a run artifact. Lock regeneration is audited rather than
|
|
606
|
+
claimed to reproduce the entire image across retries.
|
|
607
|
+
|
|
608
|
+
After building the private context, the release job runs the existing real
|
|
609
|
+
acceptance and separately executes `oats version --json` in that same
|
|
610
|
+
container. The installed kernel must equal `X.Y.Z` before registry login.
|
|
611
|
+
The fixture records the accepted container's image ID. Export must inspect
|
|
612
|
+
that same ID, then use `docker save` on the immutable ID. Skopeo reads the
|
|
613
|
+
archive and compresses layers into a private directory, preserving its
|
|
614
|
+
Docker v2s2 manifest type. Docker's CLI negotiates the Engine API; Skopeo
|
|
615
|
+
uses no daemon connection. The release lane installs and verifies the
|
|
616
|
+
reviewed Ubuntu Skopeo package version `1.13.3+ds1-2ubuntu0.24.04.3`, whose
|
|
617
|
+
error text it parses; changing that input requires another review and real
|
|
618
|
+
preparation run. PR verification installs the available archive package
|
|
619
|
+
without an exact apt pin and records its version in the step summary.
|
|
620
|
+
|
|
621
|
+
Keeping the manifest type avoids rewriting configuration bytes. The
|
|
622
|
+
prepared configuration digest must equal the hash of the archive's raw
|
|
623
|
+
configuration, binding the manifest and root filesystem to the accepted
|
|
624
|
+
image. This binding uses archive bytes rather than assuming Docker's image
|
|
625
|
+
ID is a configuration digest. The classic store has real runner evidence;
|
|
626
|
+
the containerd store branch has fixture coverage and still needs a real run.
|
|
627
|
+
Skopeo [copies with preserved digests](https://github.com/containers/skopeo/blob/main/docs/skopeo-copy.1.md)
|
|
628
|
+
to `repository@sha256:...`.
|
|
629
|
+
|
|
630
|
+
The same manifest also gets the exact release retention tag `X.Y.Z`, with
|
|
631
|
+
no leading `v`, `latest`, major or minor aliases. Before any registry write,
|
|
632
|
+
a different digest at that tag is refused; a same-digest retry is idempotent.
|
|
633
|
+
Only an explicit manifest-not-found result permits creation. Authentication,
|
|
634
|
+
transport and other lookup errors fail closed. After copying the digest,
|
|
635
|
+
the job copies the same manifest to the absent version tag and verifies its
|
|
636
|
+
resolved digest. The release workflow serializes its own writes; this
|
|
637
|
+
preflight is not a registry compare-and-swap against independent writers.
|
|
638
|
+
Deployments, chart values, deploy/team and release receipts continue to use
|
|
639
|
+
the digest reference. The version tag is for retention and human inspection.
|
|
640
|
+
|
|
641
|
+
After the version tag is written, a failed final verification or receipt edit
|
|
642
|
+
requires manual recovery of that published digest: verify the existing tag
|
|
643
|
+
against the original run's retained build inputs and acceptance evidence, then
|
|
644
|
+
restore its owned receipt block. Use the original digest output/summary when
|
|
645
|
+
available; a failed final inspect may precede that output. A workflow rerun
|
|
646
|
+
rebuilds and can yield a different digest that correctly refuses. Never retag
|
|
647
|
+
to make the rerun pass.
|
|
648
|
+
|
|
649
|
+
The digest is a job output and appears in the run summary. An owned block
|
|
650
|
+
in the existing GitHub Release notes records the immutable image reference,
|
|
651
|
+
source tag and commit, installed kernel, generated lock hash and npm kernel
|
|
652
|
+
integrity. A retry replaces only that image's block, preserving other prose.
|
|
653
|
+
The receipt's PASS list covers image build, non-root user, read-only root,
|
|
654
|
+
sshd startup and image/configuration digest binding. Supervisor startup,
|
|
655
|
+
admitted-seat spawn, wake delivery, package sync, inference, mail/chat,
|
|
656
|
+
viewer, governance, platform containment and network/egress-bypass checks
|
|
657
|
+
remain **NOT RUN**. Version and lock checks do not prove supervisor startup
|
|
658
|
+
or agent readiness; those claims need direct acceptance coverage.
|
|
659
|
+
|
|
660
|
+
Only that job has `packages: write`; `contents: write` lets it replace its
|
|
661
|
+
owned receipt block. Among run-step environments, only the publish step
|
|
662
|
+
receives `GITHUB_TOKEN`. The SHA-pinned first-party checkout and setup-node
|
|
663
|
+
actions use their default action token inputs; checkout does not persist
|
|
664
|
+
credentials. The publish step stores
|
|
665
|
+
registry authentication in a private temporary file and removes it on exit.
|
|
666
|
+
It receives no npm publish credential. To roll back a deployed image, select
|
|
667
|
+
the previous reviewed digest in the deployment configuration.
|
|
@@ -305,8 +305,14 @@ Each entry's manifests, souls and integrity are read at the observed commit →
|
|
|
305
305
|
### 4.3 Trust and removed APIs
|
|
306
306
|
|
|
307
307
|
There is no approval step or record: declaring a package in `packages:` is the trust decision, and the
|
|
308
|
-
lock pins commit and integrity. `oats sync --approve` is `E_BAD_ARGS`.
|
|
309
|
-
|
|
308
|
+
lock pins commit and integrity. `oats sync --approve` is `E_BAD_ARGS`.
|
|
309
|
+
|
|
310
|
+
Pre-workspace package-install, requirement, OAS-migration and config-merge APIs are not
|
|
311
|
+
exported from `lib/packages.mjs`. Named imports fail at module loading; namespace imports do not
|
|
312
|
+
contain those names. Use workspace `packages:`
|
|
313
|
+
plus `oats sync`; capability requirements and configuration belong to their provider, not the
|
|
314
|
+
removed package-install/config-merge APIs. The live `lockedPackageCapabilities` in `lib/resolve.mjs`
|
|
315
|
+
and `packageSpecIdentity` in `lib/core.mjs` are separate APIs and remain available.
|
|
310
316
|
|
|
311
317
|
---
|
|
312
318
|
|
|
@@ -25,8 +25,8 @@ Local `oats-local.yaml` (the deployment's per-machine file, never committed):
|
|
|
25
25
|
|
|
26
26
|
```yaml
|
|
27
27
|
teams:
|
|
28
|
-
|
|
29
|
-
defaultTeam:
|
|
28
|
+
builder-oats: { team: builder-oats:ana.aweb.ai } # a local (personal) team: label → provider id
|
|
29
|
+
defaultTeam: builder-oats
|
|
30
30
|
souls:
|
|
31
31
|
disabled: [...]
|
|
32
32
|
teams: # the extra teams each soul's instances MAY join here
|
|
@@ -35,4 +35,4 @@ Hosts that ran workspace automations before 0.30 must add their `trust` lines. T
|
|
|
35
35
|
notes say so. No host of ours runs one today, so there's nothing to migrate.
|
|
36
36
|
|
|
37
37
|
## Unblocks
|
|
38
|
-
The okf review trigger on
|
|
38
|
+
The okf review trigger on an operator's host: it runs once that host trusts it.
|