@awebai/oats 0.69.18 → 0.69.20
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 +2 -2
- package/docs/capabilities.md +27 -14
- package/docs/container.md +416 -43
- 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 +52 -31
- package/docs/desktop.md +29 -6
- package/docs/execution-targets.md +32 -17
- package/docs/implementation.md +4 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +6 -4
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/release-notes/v0.69.20.md +325 -0
- package/docs/servers.md +6 -4
- package/docs/souls-and-instances.md +37 -13
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +17 -5
- package/docs/workspaces.md +13 -7
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/core.mjs +33 -197
- package/lib/hook-outcome.mjs +6 -0
- package/lib/host-run.mjs +24 -19
- package/lib/instance-lifecycle.mjs +3 -1
- package/lib/instance-listing.mjs +3 -2
- package/lib/launch-prompt-fixtures/README.md +6 -0
- package/lib/retire-admission.mjs +215 -0
- package/lib/servers.mjs +3 -0
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +130 -47
- package/lib/session-seen.mjs +3 -3
- package/package-catalog.json +3 -3
- package/package.json +3 -1
- package/packages/client/attributed-human.mjs +13 -0
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +2 -0
- package/packages/client/instance-lifecycle.mjs +6 -4
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/packages/client/lifecycle-confirmation.mjs +4 -2
- package/packages/client/lifecycle-contract.mjs +11 -6
- package/packages/client/remote-roster.mjs +4 -0
- package/packages/record/README.md +15 -2
- package/packages/record/docs/capture-service.md +14 -0
- package/packages/record/lib/canonical.mjs +2 -70
- package/packages/record/lib/capture-aw-unit.mjs +14 -3
- package/packages/record/lib/capture-aw.mjs +11 -5
- package/packages/record/lib/capture-health.mjs +16 -5
- package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/container.md
CHANGED
|
@@ -83,7 +83,7 @@ version and regenerate this directory's lock with
|
|
|
83
83
|
`npm install --package-lock-only --ignore-scripts`; review both files. Do not
|
|
84
84
|
use `--install-oats` or `--install-aw` against a running container.
|
|
85
85
|
|
|
86
|
-
The committed OATS 0.69.
|
|
86
|
+
The committed OATS 0.69.19 pin has `oats host run`, which the entrypoint
|
|
87
87
|
runs, and `oats schedule host install --register-only`. It supports
|
|
88
88
|
`env: { fromFile: ... }` and the operator's `oats harness token set` route.
|
|
89
89
|
Provision the token through the
|
|
@@ -110,7 +110,9 @@ the UID-only form proves startup and SSH support, not token access.
|
|
|
110
110
|
| `/etc/agent-login` | root:runtime-GID, 0750; `claude-token` root:runtime-GID, 0440 | Read-only |
|
|
111
111
|
| `/etc/agent-ssh/authorized_keys` | root-owned regular file, 0644 | Read-only |
|
|
112
112
|
| `/etc/resolv.conf` | Operator-provided resolver file | Read-only |
|
|
113
|
-
| `/tmp` | tmpfs, rw,nosuid,nodev,mode=1777 | Ephemeral |
|
|
113
|
+
| `/tmp` | tmpfs, rw,nosuid,nodev,size=AGENT_TMP_SIZE,mode=1777 | Ephemeral; bounded by the configured byte limit |
|
|
114
|
+
| `/etc/agent-trust/ca.pem` | Optional public CA file, read-only | Operator-provisioned extra trust; no private keys |
|
|
115
|
+
| `/mirrors` | Optional bare Git mirror directory, read-only | Operator-refreshed source snapshots, outside writable state |
|
|
114
116
|
|
|
115
117
|
All binds use `create_host_path: false`: a missing path fails startup.
|
|
116
118
|
`/state/home`, `/state/ssh` and `/state/deploy` are created 0700 by the agent.
|
|
@@ -141,16 +143,63 @@ Supply these plain variables to the bundle's env file:
|
|
|
141
143
|
| `AUTHORIZED_KEYS_FILE` | Absolute host public-key file. |
|
|
142
144
|
| `RESOLV_CONF_FILE` | Absolute host resolver file; always required. |
|
|
143
145
|
| `AGENT_PIDS`, `AGENT_MEMORY`, `AGENT_CPUS` | Positive limits; memory uses bytes, k, m or g. |
|
|
146
|
+
| `AGENT_TMP_SIZE` | Positive integer bytes from the shared configuration's `agents.tmpSize`; bounds the `/tmp` tmpfs. |
|
|
147
|
+
| `AGENT_CA_FILE` | Optional absolute public PEM path from `agents.caFile`; selects `compose.agent.trust.yaml`. |
|
|
148
|
+
| `AGENT_MIRRORS_DIR` | Optional absolute mirror directory from `agents.mirrorsDir`; selects `compose.agent.mirrors.yaml`. |
|
|
144
149
|
| `AGENTS_NETWORK`, `AGENT_IP` | Installer-created external network and container address. |
|
|
145
150
|
|
|
146
151
|
The bundle owns the network, resolver, forwarder, firewall and their bypass
|
|
147
152
|
checks. The agent service publishes no ports and sets no DNS or extra-hosts
|
|
148
153
|
override. It joins only the named external `agents` network. Its restart
|
|
149
|
-
policy is `unless-stopped`, its stop grace period is
|
|
154
|
+
policy is `unless-stopped`, its stop grace period is 50 seconds and its
|
|
150
155
|
healthcheck reads sshd's port
|
|
151
156
|
([The kernel's periodic work](#the-kernels-periodic-work)); security flags
|
|
152
157
|
are fixed in the service file.
|
|
153
158
|
|
|
159
|
+
Include `compose.agent.trust.yaml` only when `agents.caFile` is configured. It
|
|
160
|
+
adds one read-only mount at `/etc/agent-trust/ca.pem` and exactly two fixed
|
|
161
|
+
environment settings: `SSL_CERT_FILE` and `NODE_EXTRA_CA_CERTS`, both pointing
|
|
162
|
+
there before the supervisor starts. The file must contain only valid public CA
|
|
163
|
+
certificates, at most 64 KiB, with no private key. Go keeps its normal certificate
|
|
164
|
+
directories and Node extends its normal roots. The acceptance check validates
|
|
165
|
+
the file and the exact mount/environment pair; it permits no general environment
|
|
166
|
+
override. The broker and its Node verification child receive the same trust
|
|
167
|
+
settings. The immutable `/etc/profile.d/agent-trust.sh` also supplies the two
|
|
168
|
+
settings to the agent's captured login environment and tmux children when the
|
|
169
|
+
fixed CA file is readable. The image sources that same profile at the start of
|
|
170
|
+
the system bashrc, before its noninteractive return, for bash's SSH startup
|
|
171
|
+
path. sshd also fixes `BASH_ENV` to that profile for other noninteractive bash
|
|
172
|
+
commands; user environment and SSH rc overrides remain disabled. Without the
|
|
173
|
+
CA mount, the profile exports neither setting. Recreate the container after
|
|
174
|
+
changing a trust bundle so the broker, Node children and captured sessions all
|
|
175
|
+
start with the same approved anchors.
|
|
176
|
+
A successful probe using an explicit CA does not establish that the
|
|
177
|
+
real broker trusts it; prove that through the deployment's HTTPS registry.
|
|
178
|
+
|
|
179
|
+
Include `compose.agent.mirrors.yaml` only when `agents.mirrorsDir` is configured.
|
|
180
|
+
The operator provisions and refreshes the bare mirrors outside the container,
|
|
181
|
+
with no repository credentials, and the fragment mounts them read-only at
|
|
182
|
+
`/mirrors`. Keep both optional input sources outside every agent-writable bind
|
|
183
|
+
source, including symlink aliases: run acceptance on the Docker engine host so
|
|
184
|
+
it can resolve the actual sources. A CA file with multiple hardlinks is refused,
|
|
185
|
+
since a read-only bind cannot protect another writable link to the same file.
|
|
186
|
+
The wrapper renders the existing Git rewrite in
|
|
187
|
+
`/state/home/.gitconfig`:
|
|
188
|
+
|
|
189
|
+
```gitconfig
|
|
190
|
+
[url "file:///mirrors/github.com/"]
|
|
191
|
+
insteadOf = https://github.com/
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Retain the operator's exact source/ref/commit manifest and refresh time beside
|
|
195
|
+
the mirrors. A snapshot observes the last operator refresh; its presence does
|
|
196
|
+
not prove current membership or withdrawal freshness. The first deployment check
|
|
197
|
+
is `oats workspace status` with all members confirmed, followed by the actual
|
|
198
|
+
spawn preview. Do not enable all Git file transports or add a general Git-host
|
|
199
|
+
egress route to make that check pass. Kubernetes uses an explicit existing
|
|
200
|
+
`agents.kubernetes.mirrorsClaim` for the same read-only mount, separate from
|
|
201
|
+
state; it never turns the Compose directory into a hostPath.
|
|
202
|
+
|
|
154
203
|
```sh
|
|
155
204
|
docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
|
|
156
205
|
-f compose.yaml -f container/agent/compose.agent.yaml config
|
|
@@ -164,15 +213,57 @@ the override: the base has no `/work` mount. With multiple Compose files,
|
|
|
164
213
|
paths resolve relative to the first file; use absolute host paths. Container
|
|
165
214
|
down/upgrade preserves `/state`; the operator owns provisioning and rollback.
|
|
166
215
|
|
|
167
|
-
|
|
216
|
+
The image account and the runtime NSS entry use `/bin/bash` as the login shell.
|
|
217
|
+
This lets OATS capture a fresh login environment rather than inheriting the tmux
|
|
218
|
+
creator's environment after a failed shell capture.
|
|
168
219
|
|
|
169
|
-
|
|
170
|
-
|
|
220
|
+
Compose fixes the container hostname to `oats-agent`, so replacement keeps the
|
|
221
|
+
hostname used by cache locks. Container names and network addresses still belong
|
|
222
|
+
to the deployment wrapper. A lock written under a former ephemeral hostname may
|
|
223
|
+
need one manual cleanup after checking that its holder is no longer running.
|
|
171
224
|
|
|
172
|
-
|
|
173
|
-
|
|
225
|
+
## Broker delivery before launch
|
|
226
|
+
|
|
227
|
+
Container deployments use the in-container broker with session delivery. Before
|
|
228
|
+
any spawn or resume, the bootstrap wrapper writes the existing setting in the
|
|
229
|
+
deployment's `oats-local.yaml`:
|
|
230
|
+
|
|
231
|
+
```yaml
|
|
232
|
+
settings:
|
|
233
|
+
oats.aweb:
|
|
234
|
+
delivery: session
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
A contradictory existing value must stop bootstrap with a fix naming
|
|
238
|
+
`settings.oats.aweb.delivery`; correct the deployment setting before restarting
|
|
239
|
+
it. Verify the effective value with `oats inspect` or the spawn preview's
|
|
240
|
+
`settings.oats.aweb`. The image and Compose also declare `AWEB_DELIVERY=session`
|
|
241
|
+
to silence ambient channel extensions; that variable alone does not select the
|
|
242
|
+
provider setting. The image has no Claude channel plugin.
|
|
243
|
+
|
|
244
|
+
## OATS over SSH
|
|
245
|
+
|
|
246
|
+
The operator's SSH alias selects the key and verifies the provisioned SSH host
|
|
247
|
+
key. The isolated agents bridge has no host gateway, so use the operator's
|
|
248
|
+
existing Docker context as a stdio relay to port 2222 inside the container:
|
|
249
|
+
|
|
250
|
+
```sshconfig
|
|
251
|
+
Host team-agent
|
|
252
|
+
HostName oats-agent
|
|
253
|
+
User agent
|
|
254
|
+
Port 2222
|
|
255
|
+
IdentityFile <operator-key-path>
|
|
256
|
+
IdentitiesOnly yes
|
|
257
|
+
UserKnownHostsFile <provisioned-known-hosts-file>
|
|
258
|
+
StrictHostKeyChecking yes
|
|
259
|
+
ProxyCommand docker --context <operator-context> exec -i <container> node -e 'const s=require("node:net").connect(2222,"127.0.0.1");process.stdin.pipe(s);s.pipe(process.stdout);s.on("error",()=>process.exit(1));'
|
|
174
260
|
```
|
|
175
261
|
|
|
262
|
+
Provision the public host key in that known-hosts file before connecting. The
|
|
263
|
+
Docker context belongs only to the operator; the agent receives no engine socket,
|
|
264
|
+
additional network or published port. `ssh team-agent` then uses the same SSH
|
|
265
|
+
authentication and host-key checks as an ordinary SSH transport.
|
|
266
|
+
|
|
176
267
|
Register an already provisioned deployment, or connect it from the operator's
|
|
177
268
|
deployment using its source reference:
|
|
178
269
|
|
|
@@ -192,9 +283,11 @@ deployment for the schedule tick `oats host run` runs in the container
|
|
|
192
283
|
oats schedule host install --register-only --server team-agent
|
|
193
284
|
```
|
|
194
285
|
|
|
195
|
-
The
|
|
196
|
-
|
|
197
|
-
|
|
286
|
+
The legacy VM migration route copies an already admitted ordinary-member
|
|
287
|
+
identity's private state into `/state/seats/<alias>/.aw`; each spawn selects one
|
|
288
|
+
through the existing `identity.source` input. Treat that copy as credential
|
|
289
|
+
provisioning, keep it private, and do not use a team or namespace controller
|
|
290
|
+
identity:
|
|
198
291
|
|
|
199
292
|
```sh
|
|
200
293
|
oats spawn <soul> --server team-agent --harness claude --preview --provider oats.aweb identity.source=/state/seats/<alias>/.aw
|
|
@@ -250,47 +343,50 @@ aw workspace connect --service <the team's aweb server>
|
|
|
250
343
|
The commands are as `aw` 1.36.57 documents them in its own `--help`. The
|
|
251
344
|
sequences have not yet been run in a container.
|
|
252
345
|
|
|
253
|
-
Before it copies anything, the spawn checks
|
|
254
|
-
seat when one is missing:
|
|
346
|
+
Before it copies or locks anything, the spawn checks five things, and
|
|
347
|
+
refuses the seat with its fix when one is missing:
|
|
255
348
|
|
|
256
349
|
- `signing.key`, the member's key;
|
|
257
350
|
- the server: `aweb_url` in `workspace.yaml` (`aw workspace connect` writes
|
|
258
|
-
it);
|
|
351
|
+
it). The seat's service comes only from there: `OATS_AWEB_URL` is not read;
|
|
259
352
|
- the team: the deployment's default team, or else the active team in
|
|
260
|
-
`teams.yaml
|
|
353
|
+
`teams.yaml`;
|
|
354
|
+
- `teams.yaml` itself;
|
|
355
|
+
- a membership of that team in `teams.yaml`, matched as aw matches it. When
|
|
356
|
+
there is none, accept the team's invite (`aw id team accept-invite`) or
|
|
357
|
+
fetch its certificate (`aw id team fetch-cert`) in the seat's directory, or
|
|
358
|
+
make the seat's team the deployment's default.
|
|
261
359
|
|
|
262
|
-
The member's certificate under `team-certs/` is not checked at that
|
|
263
|
-
and the seat does not work without it: the spawn copies the seat,
|
|
264
|
-
it connects or reads the identity back, and removes the copy.
|
|
360
|
+
The member's certificate file under `team-certs/` is not checked at that
|
|
361
|
+
point, and the seat does not work without it: the spawn copies the seat,
|
|
362
|
+
fails when it connects or reads the identity back, and removes the copy.
|
|
265
363
|
|
|
266
364
|
One seat serves one instance at a time. The spawn writes
|
|
267
365
|
`.aw-retained-seat.json` beside the seat's `.aw` and refuses a second spawn
|
|
268
366
|
while the first instance's home exists; retiring that instance releases the
|
|
269
|
-
seat.
|
|
367
|
+
seat. Every change of that lock is one guarded step, using two private files
|
|
368
|
+
beside it, `.aw-retained-seat.json.guard` and `.aw-retained-seat.json.held`.
|
|
369
|
+
A change that was killed can leave one of them behind. The next spawn or
|
|
370
|
+
take-over then refuses, naming the file and its fix, and the next retire
|
|
371
|
+
reports it. Nothing removes such a file automatically. Two cases need the
|
|
372
|
+
operator:
|
|
270
373
|
|
|
271
374
|
- **The holder's home exists and its runtime is known to be dead.** Spawn
|
|
272
375
|
with `identity.takeOver=true`. If that runtime is in fact alive, there are
|
|
273
376
|
then two seats with one key; stop the old one.
|
|
274
|
-
- **The holder's home is
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
377
|
+
- **The holder's home is not on this host** (a home removed by hand, a volume
|
|
378
|
+
restored, or a home on another host that shares the seat). The spawn
|
|
379
|
+
refuses, naming the holder as the lock records it (instance, host, since
|
|
380
|
+
and home) and the release. A lock is never released by age. Once that seat
|
|
381
|
+
is confirmed gone, spawn with `identity.takeOver=true`, which clears the lock
|
|
382
|
+
with a warning, or remove the lock file the refusal names.
|
|
279
383
|
|
|
280
384
|
Retiring never revokes the member's certificate: on a server that is not the
|
|
281
385
|
hosted service, whoever holds the controller key removes a member
|
|
282
|
-
(`aw id team remove-member`).
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
- **A restart can lose the seat's identity.** A seat made this way may not
|
|
287
|
-
get `AWEB_IDENTITY_HOME` at a restart
|
|
288
|
-
([awebai/oats-aweb#226](https://github.com/awebai/oats-aweb/issues/226)).
|
|
289
|
-
Check `aw whoami` in the home after a restart; if it is not the seat, retire
|
|
290
|
-
the instance and spawn it again.
|
|
291
|
-
- **Do not interrupt a seat's spawn.** A spawn killed after it connected can
|
|
292
|
-
delete the standing identity's workspace at the server
|
|
293
|
-
([awebai/oats-aweb#228](https://github.com/awebai/oats-aweb/issues/228)).
|
|
386
|
+
(`aw id team remove-member`). A seat's spawn that fails or is killed never
|
|
387
|
+
deletes the standing identity's workspace at the server: its retire releases
|
|
388
|
+
the lock and prints the `aw workspace connect` that binds the identity back to
|
|
389
|
+
its seat.
|
|
294
390
|
|
|
295
391
|
The pinned OATS release supports this file-backed launch configuration:
|
|
296
392
|
|
|
@@ -302,6 +398,11 @@ launch-configs:
|
|
|
302
398
|
CLAUDE_CONFIG_DIR: /state/home/.claude
|
|
303
399
|
CLAUDE_CODE_OAUTH_TOKEN:
|
|
304
400
|
fromFile: /etc/agent-login/claude-token
|
|
401
|
+
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
|
|
402
|
+
DISABLE_UPDATES: "1"
|
|
403
|
+
DISABLE_FEEDBACK_COMMAND: "1"
|
|
404
|
+
ENABLE_CLAUDEAI_MCP_SERVERS: "false"
|
|
405
|
+
CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1"
|
|
305
406
|
```
|
|
306
407
|
|
|
307
408
|
Select it with `--launch-config team-claude`. The operator provisions only a
|
|
@@ -309,6 +410,47 @@ Select it with `--launch-config team-claude`. The operator provisions only a
|
|
|
309
410
|
by every agent in the same trust group; read-only mounting does not hide it
|
|
310
411
|
or narrow its authority. Never share the mount across trust groups.
|
|
311
412
|
|
|
413
|
+
For the optional external model role, the wrapper also writes
|
|
414
|
+
`{"skipWebFetchPreflight": true}` into `/state/home/.claude/settings.json`,
|
|
415
|
+
merging with any other supported settings. The literals above disable ancillary
|
|
416
|
+
Claude traffic; they do not prove that the pinned harness needs only
|
|
417
|
+
`api.anthropic.com`. Qualify a real authorized start and turn, retaining every
|
|
418
|
+
refused DNS/SNI name. Report an additional necessary host rather than adding it
|
|
419
|
+
automatically. Do not put `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` alongside
|
|
420
|
+
this login: those credentials take precedence over the setup-token input.
|
|
421
|
+
|
|
422
|
+
The [egress component](../container/agent/egress/README.md#optional-external-source-and-model-roles)
|
|
423
|
+
defines the two optional source/model routes and their operator-selected DNS
|
|
424
|
+
resolvers. Their boundary is exact SNI and a validated public destination;
|
|
425
|
+
it does not filter repository paths, HTTP authorities or data sent to a provider.
|
|
426
|
+
It limits which services are reachable, not which accounts on them. A credential
|
|
427
|
+
from any source, including an untrusted message, can allow an agent to push data
|
|
428
|
+
to a GitHub repository or send data to a model account controlled by that
|
|
429
|
+
credential's owner. Publishing needs a separate operator decision and a push
|
|
430
|
+
credential scoped to one repository; the network boundary does not enforce
|
|
431
|
+
that scope.
|
|
432
|
+
|
|
433
|
+
Direct source access is off by default. Operator-refreshed read-only mirrors
|
|
434
|
+
provide source reads without that outbound route. They avoid access to any
|
|
435
|
+
public GitHub repository, request-path disclosure in GitHub logs, and writes
|
|
436
|
+
limited only by credential scope. Mirrors reflect the last operator refresh;
|
|
437
|
+
direct access uses the configured remote source. Both routes remain supported.
|
|
438
|
+
The resolver input requires public IPv4 DNS and proxy UDP/TCP 53 access to it;
|
|
439
|
+
a cluster that mandates a private DNS resolver is not supported by this input.
|
|
440
|
+
The existing five-service ingress audit remains a separate admission gate.
|
|
441
|
+
|
|
442
|
+
### A knowledge credential
|
|
443
|
+
|
|
444
|
+
Agents that propose knowledge with `oats.okf` need a GitHub credential of
|
|
445
|
+
their own, never the maintainer's: whatever it may do, every agent in the
|
|
446
|
+
container may do. Give them an identity with the write role only on the
|
|
447
|
+
knowledge repository, its token in a file named by
|
|
448
|
+
`settings.oats.okf.github-token-file`, and keep the identity that merges to
|
|
449
|
+
the accepted branch outside the container. oats.okf's
|
|
450
|
+
[Bringing up a deployment's knowledge store](https://github.com/oats-project/oats-okf/blob/v6.2.0/README.md#bringing-up-a-deployments-knowledge-store)
|
|
451
|
+
(oats.okf 6.2 and later) has each step; run its
|
|
452
|
+
`oats okf setup --check` in the container to check them.
|
|
453
|
+
|
|
312
454
|
### After changing a credential
|
|
313
455
|
|
|
314
456
|
A resume starts an agent under the values its last start recorded. When the
|
|
@@ -381,17 +523,21 @@ What the image's files fix for that:
|
|
|
381
523
|
|
|
382
524
|
- **PID-only tini signals the Node supervisor.** It forwards TERM to host
|
|
383
525
|
run alone and keeps the wake broker alive until host run finishes stopping
|
|
384
|
-
the agents. Then it stops sshd and the broker in parallel
|
|
526
|
+
the agents. Then it stops sshd and the broker in parallel, allowing sshd three seconds
|
|
527
|
+
and the broker six seconds before escalation. The broker budget preserves
|
|
528
|
+
its channel children's five-second delivery drain. A broker or
|
|
385
529
|
host-run exit is reported and drains the other children before a nonzero
|
|
386
530
|
container exit, so
|
|
387
531
|
the restart policy can restart it. The broker runs as the agent uid; its
|
|
388
532
|
default state directory is `/state/home/.config/aw/wake`, so registrations
|
|
389
533
|
survive container replacement and it starts again even with no spawn.
|
|
390
|
-
- **`stop_grace_period:
|
|
391
|
-
10 seconds
|
|
392
|
-
killed at the timeout leaves agents
|
|
393
|
-
platform that does not read the Compose
|
|
394
|
-
in its container spec.
|
|
534
|
+
- **`stop_grace_period: 50s`** in the Compose service. Docker's default
|
|
535
|
+
10 seconds is shorter than the kernel and broker drains; each harness
|
|
536
|
+
alone gets 20 seconds. A container killed at the timeout leaves agents
|
|
537
|
+
that were not stopped in order. A platform that does not read the Compose
|
|
538
|
+
file needs the same stop timeout in its container spec. The 50-second
|
|
539
|
+
limit is the runtime's final failure boundary for stuck OS work; wake
|
|
540
|
+
delivery and model activity require separate evidence.
|
|
395
541
|
- **A healthcheck on sshd.** The supervisor reports an sshd exit; if
|
|
396
542
|
sshd ends, the agents and the tick go on and the operator's route is gone.
|
|
397
543
|
The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
|
|
@@ -461,7 +607,7 @@ variables. It resolves `AGENT_IMAGE` independently and requires that image's
|
|
|
461
607
|
ID, reference and start command, and its complete environment (printing only
|
|
462
608
|
names of differing variables). Other comparisons include supplementary
|
|
463
609
|
groups, namespace overrides, sysctls, published ports, resolver overrides
|
|
464
|
-
and the single network/address. The stop timeout must be
|
|
610
|
+
and the single network/address. The stop timeout must be 50 seconds and the
|
|
465
611
|
healthcheck the service file's, so a container made before either was set
|
|
466
612
|
is refused until it is recreated. The OCI runtime must match the daemon's
|
|
467
613
|
independently read default; shared memory stays at Docker's 64 MiB default,
|
|
@@ -492,3 +638,230 @@ fixtures. The SSH guard requires flat
|
|
|
492
638
|
`Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
|
|
493
639
|
equals-delimited keywords and quoted keywords. Follow the repository's
|
|
494
640
|
local check limits; full suites run in CI.
|
|
641
|
+
|
|
642
|
+
## Image CI and publication
|
|
643
|
+
|
|
644
|
+
[Team image](../.github/workflows/team-image.yml) builds `container/agent`
|
|
645
|
+
from the pull request's exact head commit, on an Ubuntu 24.04 amd64 runner.
|
|
646
|
+
It also supports a manual verification run at the selected ref. Actions are
|
|
647
|
+
pinned by commit, and the verification token has only `contents: read`.
|
|
648
|
+
After acceptance, verification also runs the real Docker export, Skopeo
|
|
649
|
+
compression and configuration-digest checks used before publication, without
|
|
650
|
+
a registry credential or any registry/release write.
|
|
651
|
+
|
|
652
|
+
Manual verification offers two additional proofs:
|
|
653
|
+
|
|
654
|
+
- `default_payload_proof` builds the registry context a second time without
|
|
655
|
+
the additive BuildKit mount and compares the full installed `/opt/agent`
|
|
656
|
+
payload: file paths, sizes, content hashes, modes, directories and link
|
|
657
|
+
targets. Image history and IDs may differ; payload differences fail.
|
|
658
|
+
- `packed_kernel` prepares a private context from the selected commit and
|
|
659
|
+
runs the image with that commit's own `npm pack` kernel. This job is
|
|
660
|
+
manual-only until the image owner's compatible final baseline lands.
|
|
661
|
+
Ordinary PR verification keeps the committed context in the meantime.
|
|
662
|
+
An incompatible baseline fails explicitly, with no registry-kernel fallback
|
|
663
|
+
and no wider lock allowance. The committed baseline needs final OATS
|
|
664
|
+
0.69.18+ and aw 1.36.59+ with the compatible exact runtime closure.
|
|
665
|
+
With the committed baseline, the packed job refuses; its positive real
|
|
666
|
+
packed-image acceptance is **NOT RUN** until that compatible baseline lands.
|
|
667
|
+
|
|
668
|
+
Packing disables lifecycle scripts and uses a private npm home/cache, empty
|
|
669
|
+
user/global configs and an explicit public registry. Every packed file must
|
|
670
|
+
be in the kernel's literal `package.json.files` list, including the explicitly
|
|
671
|
+
declared manifest and license. The tarball is checked against its SHA512
|
|
672
|
+
integrity and the exact checkout's regular Git files, sizes, bytes and modes;
|
|
673
|
+
links, unsafe paths and untracked/generated payloads refuse. The source
|
|
674
|
+
checkout stays unchanged.
|
|
675
|
+
|
|
676
|
+
Only the private image manifest changes to the fixed
|
|
677
|
+
`file:../oats-build-inputs/oats-pr-kernel.tgz` dependency. The same tarball is
|
|
678
|
+
provided in the closed context and a private host-side sibling directory,
|
|
679
|
+
so npm lock generation and the build resolve the same bytes. The existing
|
|
680
|
+
`npm ci --ignore-scripts` RUN gets a read-only context mount at
|
|
681
|
+
`/opt/oats-build-inputs`; no tarball COPY, build argument, new lifecycle
|
|
682
|
+
execution or runtime mount is added. The registry release context and its
|
|
683
|
+
strict metadata checks keep their own path. Both adapters protect every
|
|
684
|
+
unrelated CLI and lock entry, addition, removal and root/metadata field.
|
|
685
|
+
|
|
686
|
+
After the unmodified acceptance, the packed job checks the installed kernel's
|
|
687
|
+
exact own-file set, sizes, modes and hashes against the HEAD inventory in
|
|
688
|
+
the same accepted container. Version equality alone is insufficient: two
|
|
689
|
+
commits may share a version. Separately resolved nested dependencies remain
|
|
690
|
+
governed by the image lock. A changed inventory artifact or installed file
|
|
691
|
+
fails before digest preparation. The closed context, tarball, generated
|
|
692
|
+
manifest/lock, source inventory and build metadata are retained as artifacts;
|
|
693
|
+
npm config/cache are outside the uploaded context. Source SHA and
|
|
694
|
+
integrity/inventory/lock hashes are retained in those artifacts. Acceptance
|
|
695
|
+
reports the image ID in its log and passes it between workflow steps to bind
|
|
696
|
+
the export to the accepted image. These checks do not broaden the receipt's
|
|
697
|
+
supervisor, agent or containment claims.
|
|
698
|
+
|
|
699
|
+
The shared fixture, `.github/scripts/team-image-accept.sh`, starts the
|
|
700
|
+
committed Compose service on a disposable internal bridge with IPv6 off and
|
|
701
|
+
an isolated gateway (Docker Engine 28+). It provisions private state, a
|
|
702
|
+
throwaway SSH public key, a resolver file and an empty root:20001 0750 login
|
|
703
|
+
directory, waits for the service's SSH healthcheck, then runs the image's
|
|
704
|
+
unmodified `accept.sh --evidence target-amd64`. Cleanup removes the service,
|
|
705
|
+
network and fixture paths on success or failure. This is image acceptance;
|
|
706
|
+
it provisions no seat or inference token. The script's `NOT RUN` items
|
|
707
|
+
remain outside this check.
|
|
708
|
+
|
|
709
|
+
The `publish-team-image` job in
|
|
710
|
+
[Release](../.github/workflows/release.yml) waits for the existing `publish`
|
|
711
|
+
job, so npm publication and the GitHub Release precede the image. Its
|
|
712
|
+
single job-level `if: ${{ false }}` keeps publication disabled pending the
|
|
713
|
+
registry decision for the proposed `ghcr.io/oats-project/team-agent` target.
|
|
714
|
+
GHCR creates a new package as private by default. Verification remains
|
|
715
|
+
enabled. Enabling publication requires the registry decision and a reviewed
|
|
716
|
+
change to the switch.
|
|
717
|
+
|
|
718
|
+
Before enabling, the registry owner must complete these separately authorized
|
|
719
|
+
setup steps and include their evidence as a checklist in the enabling PR:
|
|
720
|
+
|
|
721
|
+
1. Push the approved digest from a verified run.
|
|
722
|
+
2. Set the package visibility to public.
|
|
723
|
+
3. Grant this repository's Actions write access.
|
|
724
|
+
4. Record the pinned-client observation that an unused exact version tag
|
|
725
|
+
returns `manifest unknown`.
|
|
726
|
+
|
|
727
|
+
Package creation is this manual setup step, never an automatic release-job
|
|
728
|
+
bootstrap. The job treats only `manifest unknown` as an absent tag. It refuses
|
|
729
|
+
`name unknown`, `denied`, authentication and transport errors. The registry
|
|
730
|
+
owner resolves bootstrap and access problems without broadening the matcher.
|
|
731
|
+
|
|
732
|
+
Publication requires a stable `vX.Y.Z` release tag (at least 0.69.18).
|
|
733
|
+
The release job copies only the tagged image's literal `.dockerignore`
|
|
734
|
+
allowlist into a private build context, sets its OATS dependency to exactly
|
|
735
|
+
`X.Y.Z`, and regenerates that copy's lock with npm scripts disabled and the
|
|
736
|
+
public registry selected explicitly. The source checkout and Dockerfile
|
|
737
|
+
stay unchanged. The committed aw pin must be a final version of at least
|
|
738
|
+
1.36.59 and match its lock; prereleases cannot pass the guard.
|
|
739
|
+
|
|
740
|
+
The generated lock may change only the OATS entry, its root dependency
|
|
741
|
+
specification and its own exact runtime dependencies. Other entries,
|
|
742
|
+
including aw, Claude and unrelated transitive packages, must remain equal
|
|
743
|
+
to the committed lock, including additions and removals. Registry version,
|
|
744
|
+
tarball URL and SHA512 integrity must match the new kernel and its exact
|
|
745
|
+
dependencies. A missing compatible committed baseline fails the build;
|
|
746
|
+
it does not widen the allowance. The image owner maintains that baseline.
|
|
747
|
+
The effective manifest, generated lock and source/version/integrity metadata
|
|
748
|
+
are retained as a run artifact. Lock regeneration is audited rather than
|
|
749
|
+
claimed to reproduce the entire image across retries.
|
|
750
|
+
|
|
751
|
+
After building the private context, the release job runs the existing real
|
|
752
|
+
acceptance and separately executes `oats version --json` in that same
|
|
753
|
+
container. The installed kernel must equal `X.Y.Z` before registry login.
|
|
754
|
+
The fixture records the accepted container's image ID. Export must inspect
|
|
755
|
+
that same ID, then use `docker save` on the immutable ID. Skopeo reads the
|
|
756
|
+
archive and compresses layers into a private directory, preserving its
|
|
757
|
+
Docker v2s2 manifest type. Docker's CLI negotiates the Engine API; Skopeo
|
|
758
|
+
uses no daemon connection. The release lane installs and verifies the
|
|
759
|
+
reviewed Ubuntu Skopeo package version `1.13.3+ds1-2ubuntu0.24.04.3`, whose
|
|
760
|
+
error text it parses; changing that input requires another review and real
|
|
761
|
+
preparation run. PR verification installs the available archive package
|
|
762
|
+
without an exact apt pin and records its version in the step summary.
|
|
763
|
+
|
|
764
|
+
Keeping the manifest type avoids rewriting configuration bytes. The
|
|
765
|
+
prepared configuration digest must equal the hash of the archive's raw
|
|
766
|
+
configuration, binding the manifest and root filesystem to the accepted
|
|
767
|
+
image. This binding uses archive bytes rather than assuming Docker's image
|
|
768
|
+
ID is a configuration digest. The classic store has real runner evidence;
|
|
769
|
+
the containerd store branch has fixture coverage and still needs a real run.
|
|
770
|
+
Skopeo [copies with preserved digests](https://github.com/containers/skopeo/blob/main/docs/skopeo-copy.1.md)
|
|
771
|
+
to `repository@sha256:...`.
|
|
772
|
+
|
|
773
|
+
The same manifest also gets the exact release retention tag `X.Y.Z`, with
|
|
774
|
+
no leading `v`, `latest`, major or minor aliases. Before any registry write,
|
|
775
|
+
a different digest at that tag is refused; a same-digest retry is idempotent.
|
|
776
|
+
Only an explicit manifest-not-found result permits creation. Authentication,
|
|
777
|
+
transport and other lookup errors fail closed. After copying the digest,
|
|
778
|
+
the job copies the same manifest to the absent version tag and verifies its
|
|
779
|
+
resolved digest. The release workflow serializes its own writes; this
|
|
780
|
+
preflight is not a registry compare-and-swap against independent writers.
|
|
781
|
+
Deployments, chart values, deploy/team and release receipts continue to use
|
|
782
|
+
the digest reference. The version tag is for retention and human inspection.
|
|
783
|
+
|
|
784
|
+
After the version tag is written, a failed final verification or receipt edit
|
|
785
|
+
requires manual recovery of that published digest: verify the existing tag
|
|
786
|
+
against the original run's retained build inputs and acceptance evidence, then
|
|
787
|
+
restore its owned receipt block. Use the original digest output/summary when
|
|
788
|
+
available; a failed final inspect may precede that output. A workflow rerun
|
|
789
|
+
rebuilds and can yield a different digest that correctly refuses. Never retag
|
|
790
|
+
to make the rerun pass.
|
|
791
|
+
|
|
792
|
+
The digest is a job output and appears in the run summary. An owned block
|
|
793
|
+
in the existing GitHub Release notes records the immutable image reference,
|
|
794
|
+
source tag and commit, installed kernel, generated lock hash and npm kernel
|
|
795
|
+
integrity. A retry replaces only that image's block, preserving other prose.
|
|
796
|
+
The receipt's PASS list covers image build, non-root user, read-only root,
|
|
797
|
+
sshd startup and image/configuration digest binding. Supervisor startup,
|
|
798
|
+
admitted-seat spawn, wake delivery, package sync, inference, mail/chat,
|
|
799
|
+
viewer, governance, platform containment and network/egress-bypass checks
|
|
800
|
+
remain **NOT RUN**. Version and lock checks do not prove supervisor startup
|
|
801
|
+
or agent readiness; those claims need direct acceptance coverage.
|
|
802
|
+
|
|
803
|
+
Only that job has `packages: write`; `contents: write` lets it replace its
|
|
804
|
+
owned receipt block. Among run-step environments, only the publish step
|
|
805
|
+
receives `GITHUB_TOKEN`. The SHA-pinned first-party checkout and setup-node
|
|
806
|
+
actions use their default action token inputs; checkout does not persist
|
|
807
|
+
credentials. The publish step stores
|
|
808
|
+
registry authentication in a private temporary file and removes it on exit.
|
|
809
|
+
It receives no npm publish credential. To roll back a deployed image, select
|
|
810
|
+
the previous reviewed digest in the deployment configuration.
|
|
811
|
+
|
|
812
|
+
## Egress component
|
|
813
|
+
|
|
814
|
+
The generic [egress image and service](../container/agent/egress/README.md) live
|
|
815
|
+
with the agent image. The deployment wrapper owns its allowlist and derives the
|
|
816
|
+
non-secret runtime policy from the shared deployment configuration and signer
|
|
817
|
+
profile when signer is declared. An optional derived `roles` array selects a
|
|
818
|
+
nonempty subset of aweb, logs, registry, secrets and signer, with exactly matching
|
|
819
|
+
targets and probe paths. Omission retains the five-role policy and output.
|
|
820
|
+
Signer `humanOrigin` is required with signer and refused without it. Registry
|
|
821
|
+
`authorityRecords` are required with registry and refused without it, independently
|
|
822
|
+
of signer: messaging-only namespaces still need exact `_awid` TXT evidence for
|
|
823
|
+
discovery and sender verification. The root-authoritative resolver has no
|
|
824
|
+
forwarding fallback. The proxy permits only the named API and registry routes and serves
|
|
825
|
+
only the declared public namespace authority records. Service custody keys,
|
|
826
|
+
PostgreSQL, Redis and the Docker socket stay outside the agent container.
|
|
827
|
+
|
|
828
|
+
Network membership, CNI enforcement and ingress Host/SNI agreement require runtime
|
|
829
|
+
proof before launching agents. An internal bridge, a NetworkPolicy object or a
|
|
830
|
+
healthy proxy alone does not prove the boundary. The [service descriptor](../container/agent/egress/descriptor.md)
|
|
831
|
+
supplies the wrapper mapping without a separate operator schema.
|
|
832
|
+
|
|
833
|
+
The [minimal Compose wrapper and refusing network preflight](../container/agent/egress/README.md#minimal-compose-wrapper-and-network-preflight)
|
|
834
|
+
own explicit agents/services IPAM, gateways, `AGENT_IP` and `EGRESS_ADDRESS`.
|
|
835
|
+
Preflight is read-only on the Linux engine host and refuses failed observations
|
|
836
|
+
or CIDR overlaps across every Docker IPAM entry, route table and link address.
|
|
837
|
+
Every role set keeps unlisted DNS/TLS refusal, alternate-network refusal, a live
|
|
838
|
+
host-gateway canary, direct upstream/backend denial and an explicit IPv4 IPAM
|
|
839
|
+
gateway. The report separates universal and declared controls. The Compose probe
|
|
840
|
+
accepts an optional derived `namePrefix` for its temporary containers and reports
|
|
841
|
+
`{name,image,network,created,absentVerified}` receipts on success and refusal.
|
|
842
|
+
Cleanup removes only an exact name whose per-attempt ownership label matches;
|
|
843
|
+
timeouts require inspection and never count as absence. A failed observation
|
|
844
|
+
refuses and reports the unverified name. The new `--json` mode returns
|
|
845
|
+
`{passed,receipts,error?}` on stdout, with exit 1 on refusal; the default PASS token
|
|
846
|
+
and stderr receipt lines remain available. See the
|
|
847
|
+
[Compose probe contract](../container/agent/egress/README.md#boundary-probe-on-an-existing-compose-deployment).
|
|
848
|
+
Stage public
|
|
849
|
+
sources before credentials; there is no codeload exception. Pin wrapper,
|
|
850
|
+
compiler/proxy image and probes to one reviewed commit and retain image digests.
|
|
851
|
+
|
|
852
|
+
The ingress probe keeps backend non-delivery witnesses for owned routes. A
|
|
853
|
+
wrapper may explicitly mark only the registry as external for verified-TLS 200
|
|
854
|
+
controls, without third-party refusal or backend-log claims. When signer is
|
|
855
|
+
declared, signer and human-surface ingress controls remain required.
|
|
856
|
+
`probeIngress` explicitly refuses a policy without signer before sending controls;
|
|
857
|
+
runtime role controls follow the compiler's canonical order for every declaration.
|
|
858
|
+
Deployment bundles default `team.registryRoute` to `external`; existing bundles serving a local registry
|
|
859
|
+
must select `local` and refuse a URL their service does not serve. See the
|
|
860
|
+
[route-mode contract](../container/agent/egress/README.md#ingress-admission-probe)
|
|
861
|
+
for the exact probe inputs and ownership checks.
|
|
862
|
+
|
|
863
|
+
For Kubernetes, liveness runs `node /usr/local/lib/agent-liveness.mjs` to check
|
|
864
|
+
the supervisor process. SSH on port 2222 is readiness: losing SSH must not
|
|
865
|
+
restart the whole team while its agents and broker are still running. The
|
|
866
|
+
container's 50-second termination window covers the kernel and supervisor
|
|
867
|
+
phases under the same [shutdown failure boundary](#the-kernels-periodic-work).
|
|
@@ -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.
|