@awebai/oats 0.69.12 → 0.69.15
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 +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
package/docs/capabilities.md
CHANGED
|
@@ -142,6 +142,14 @@ A self-contained package has an `oats.json`:
|
|
|
142
142
|
Doctor without `--soul` reads every member and locked package capability
|
|
143
143
|
from this machine's cache only. What the cache cannot answer is reported as
|
|
144
144
|
unchecked (`hook-events-unchecked` in its information), never as no warning.
|
|
145
|
+
- **A retire hook must be safe to run when its spawn hook did not finish, and
|
|
146
|
+
when it has run before.** It runs after a spawn that was killed while the
|
|
147
|
+
spawn hook ran (below), which may have registered everything, something or
|
|
148
|
+
nothing, and then gets an empty `OATS_META`: the spawn hook never answered
|
|
149
|
+
its receipt. It runs again on every retry of an incomplete cleanup. It
|
|
150
|
+
reads what there is to undo from the home and from the service it
|
|
151
|
+
registered with, and answers `meta: { retired: false, reason:
|
|
152
|
+
"nothing-to-delete" }` when there is nothing: that is a complete cleanup.
|
|
145
153
|
- A capability declaring a **required** spawn hook should declare a `retire` hook
|
|
146
154
|
too. Without one, OATS has no way to undo what the spawn hook did and no way to
|
|
147
155
|
know whether it did anything, so a failure quarantines the home rather than
|
|
@@ -169,7 +177,17 @@ A self-contained package has an `oats.json`:
|
|
|
169
177
|
with `git branch <b>: could not verify whether it still exists (…)`. A retry that still cannot
|
|
170
178
|
finish keeps the home again, names what is outstanding, and exits nonzero.
|
|
171
179
|
- The **escape hatch is `oats retire <instance> --force`**, for a home OATS cannot
|
|
172
|
-
identify at all: no `instance.json` and no **usable** cleanup descriptor
|
|
180
|
+
identify at all: no `instance.json` and no **usable** cleanup descriptor, or an
|
|
181
|
+
`instance.json` that does not say which retire hooks to run and no usable
|
|
182
|
+
descriptor beside it. Such a record names no repository (`repo`), which the
|
|
183
|
+
retire hooks are run for, and does not show (`capabilityRuntime`) that no
|
|
184
|
+
capability has a retire hook: the stub a spawn leaves when it is killed
|
|
185
|
+
before its record, where no marker was written before its hooks (a spawn by
|
|
186
|
+
a kernel before this rule, or a marker since removed). Retire refuses it
|
|
187
|
+
with `E_UNIDENTIFIED_INSTANCE_HOME` before anything is stopped, run or
|
|
188
|
+
removed: the spawn hooks may have registered an identity that only the
|
|
189
|
+
retire hooks would release. Clean up by hand what the capabilities
|
|
190
|
+
registered, then `--force` removes the home, running no hook. Usable
|
|
173
191
|
means it satisfies the versioned cleanup contract the rollback writes, checked
|
|
174
192
|
to the depth the retry consumes it: `version`, a context `repo`, a recognised
|
|
175
193
|
`work` mode (plus a `branch` for `worktree` — an unknown mode would skip the
|
|
@@ -187,17 +205,34 @@ A self-contained package has an `oats.json`:
|
|
|
187
205
|
success, and every Git step it records must be re-run and verified. A retry that resolves no
|
|
188
206
|
capabilities — a hand-edited descriptor, or config drift since the spawn — is an
|
|
189
207
|
incomplete cleanup, not a clean one, and the home stays.
|
|
190
|
-
- **A spawn in progress** (0.49.0). A
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
leaves a home `oats retire` can clean up
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
208
|
+
- **A spawn in progress** (0.49.0). A spawn writes the same marker before
|
|
209
|
+
the first hook whose effects a retire would have to undo, so a parent
|
|
210
|
+
killed from there on (SIGKILL, a container stop, a dropped connection)
|
|
211
|
+
leaves a home `oats retire` can clean up:
|
|
212
|
+
- before its first **spawn hook**, in every work mode, when a capability
|
|
213
|
+
with a spawn hook also has a retire hook. Until the spawn writes its
|
|
214
|
+
final `instance.json`, the home's record is a stub that names neither the
|
|
215
|
+
repository nor the capabilities, and the marker is the only record of
|
|
216
|
+
which retire hooks to run. Its `outstanding.hooks` holds the retire hooks
|
|
217
|
+
of every capability with a spawn hook; once the spawn hooks have
|
|
218
|
+
answered, the marker is written again with their receipt
|
|
219
|
+
(`cleanup.capabilityMeta`, a retire hook's `OATS_META`). Its `cleanup`
|
|
220
|
+
also holds the record's `workspace`, `teams` and `defaultTeam`, so the
|
|
221
|
+
retire hooks get the team and workspace environment a retire of a whole
|
|
222
|
+
home gives them;
|
|
223
|
+
- before its first [`worktree` hook](#the-worktree-event), for a `work:
|
|
224
|
+
worktree` spawn that fires them. Its `outstanding` holds the retire
|
|
225
|
+
hooks of the capabilities whose spawn hooks ran, plus the Git steps
|
|
226
|
+
`worktree` and `branch` (a `work: worktree` marker written before the
|
|
227
|
+
spawn hooks holds those Git steps too).
|
|
228
|
+
|
|
229
|
+
It adds an optional top-level `inProgress: { pid,
|
|
230
|
+
processStart, startedAt, branch?, baseOid?, hookPgid?, hookStart? }`: the
|
|
231
|
+
spawning process, identified by its pid and start time, the branch of the
|
|
232
|
+
work and, for a `work: worktree` spawn, the commit the spawn created it at,
|
|
233
|
+
and the process group of the worktree hook running. The spawn removes the marker
|
|
234
|
+
once its final `instance.json` is written, before it takes the final
|
|
235
|
+
baseline; a failure's compensation replaces it in one rename.
|
|
201
236
|
Such a marker satisfies every rule above, so a reader that does not know
|
|
202
237
|
`inProgress` reads it as a quarantine. While the spawning process is
|
|
203
238
|
verifiably alive (its pid runs with the recorded start time):
|
|
@@ -693,7 +728,10 @@ instance session they are the session's.
|
|
|
693
728
|
soul-set value from a host-set one there, and never reads `soul.yaml` for it;
|
|
694
729
|
a home with none recorded gives `{}`. A final JSON line may return `meta`,
|
|
695
730
|
`brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
|
|
696
|
-
launch hook's preview answer may add `volatileEnv` (below). A
|
|
731
|
+
launch hook's preview answer may add `volatileEnv` (below). A retire hook's
|
|
732
|
+
`warning` is in the retire's `warnings` and, as a `retire-warning` event, in
|
|
733
|
+
the instance's workspace log, readable with `oats instance events` after the
|
|
734
|
+
home is gone ([Events](desktop-cli-api.md#events)). A **spawn or
|
|
697
735
|
launch hook** may also return an `env` object for the launched process;
|
|
698
736
|
returning `env` from a retire or [worktree](#the-worktree-event) hook is an
|
|
699
737
|
explicit contract error.
|
|
@@ -865,6 +903,13 @@ Spawn order is by capability name; retirement reverses successful
|
|
|
865
903
|
spawn order. Hooks run from the instance's own copy
|
|
866
904
|
(`<home>/.oats/modules/<cap>/`).
|
|
867
905
|
|
|
906
|
+
A retire hook must be safe to run again, and safe to run beside itself. A
|
|
907
|
+
retire whose process is killed while one of its retire hooks runs leaves that
|
|
908
|
+
hook running. A later retire takes the home's claim over, does not run again
|
|
909
|
+
the hooks the claim records as finished
|
|
910
|
+
([one retire at a time](desktop-cli-api.md#retire-hooks-in-claim)), and runs
|
|
911
|
+
the unfinished one again, possibly while the first run of it is still going.
|
|
912
|
+
|
|
868
913
|
### A declared name is the provider's
|
|
869
914
|
|
|
870
915
|
A variable a capability declares in `environment` is the capability's to
|
package/docs/configuration.md
CHANGED
|
@@ -64,7 +64,7 @@ refused (`E_WORKSPACE_SCHEMA`).
|
|
|
64
64
|
| `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
|
|
65
65
|
| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
|
|
66
66
|
| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
|
|
67
|
-
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). |
|
|
67
|
+
| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). An entry is matched by exact name only, so one whose soul was renamed or moved (a removed package pin, for example) names no soul and keeps nothing off: it fails open, and the soul becomes spawnable again under its new name, unlike a stale `souls.launch` key, which fails closed. Run `oats doctor` after any rename or removal: it reports such an entry as `disabled-soul-unmatched`, with the nearest souls ([what doctor reports](desktop-cli-api.md#launch-preferences)). |
|
|
68
68
|
| `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
|
|
69
69
|
| `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
|
|
70
70
|
| `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
|
|
@@ -289,7 +289,7 @@ instance's terminal and press Enter yourself.
|
|
|
289
289
|
An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
|
|
290
290
|
(a bare name looked up on `PATH`, or a path relative to the directory of the
|
|
291
291
|
file that declares it), `args` (literal, no shell), `env` (a literal string, or
|
|
292
|
-
`{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
|
|
292
|
+
`{ fromEnv: NAME }` or `{ fromFile: /absolute/path }` resolved on the host at start), `model`, `yolo` and
|
|
293
293
|
`default` (0.32; see [the harness default](#the-harness-default)). A launch
|
|
294
294
|
configuration is a host choice: a soul never names one.
|
|
295
295
|
|
|
@@ -450,7 +450,7 @@ launch: { harness: claude, model: claude-opus-5-5 }
|
|
|
450
450
|
souls:
|
|
451
451
|
launch:
|
|
452
452
|
"*": personal # a launch configuration, for every soul here
|
|
453
|
-
oats-expert: { harness: claude, model: claude-opus-5-5 }
|
|
453
|
+
oats-engineering-expert: { harness: claude, model: claude-opus-5-5 }
|
|
454
454
|
oats.engineering/code-reviewer: { harness: codex } # a package soul
|
|
455
455
|
```
|
|
456
456
|
|
|
@@ -552,6 +552,64 @@ source variable must be set on the host (`E_LAUNCH_ENV_MISSING`, before
|
|
|
552
552
|
anything is created or stopped), and only the harness's pane receives it.
|
|
553
553
|
`list` and `preview` redact every environment value, literals included.
|
|
554
554
|
|
|
555
|
+
`{ fromFile: /absolute/path }` reads a regular UTF-8 file on the host that
|
|
556
|
+
starts the harness, at every start. The source is limited to 64 KiB, including
|
|
557
|
+
any final newline; larger files are refused before reading their contents.
|
|
558
|
+
It removes exactly one trailing LF or
|
|
559
|
+
CRLF; an empty file is allowed. Invalid UTF-8 and NUL are refused. A leading
|
|
560
|
+
UTF-8 BOM is preserved as part of the value. `fromFile` is for credential
|
|
561
|
+
values; directory selectors (`HOME`, `PATH`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`,
|
|
562
|
+
`PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`) require a literal or
|
|
563
|
+
`{ fromEnv: NAME }`. A missing, unreadable or
|
|
564
|
+
non-regular file refuses with `E_LAUNCH_ENV_MISSING`. The message names the
|
|
565
|
+
file and the reason (including encoding, NUL or size failures), then names
|
|
566
|
+
`oats harness token set <harness> --server <id>` or operator provisioning on
|
|
567
|
+
that host. The token command is a separate provisioning feature.
|
|
568
|
+
|
|
569
|
+
```yaml
|
|
570
|
+
launch-configs:
|
|
571
|
+
subscription:
|
|
572
|
+
harness: claude
|
|
573
|
+
env:
|
|
574
|
+
CLAUDE_CODE_OAUTH_TOKEN: { fromFile: /etc/agent-login/claude-token }
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
For server credentials, [harness token commands](servers.md#harness-credentials)
|
|
578
|
+
deliver an existing setup-token or API key through the separate operator
|
|
579
|
+
route, with `--stdin`. Bind the receiver's server-side file in the launch
|
|
580
|
+
configuration, for example
|
|
581
|
+
`CLAUDE_CODE_OAUTH_TOKEN: { fromFile: /srv/oats-team/team/login/claude-token }`.
|
|
582
|
+
For Codex use `OPENAI_API_KEY`; for pi use the selected provider's env
|
|
583
|
+
variable. The token command does not choose a provider or edit this binding.
|
|
584
|
+
A replacement is read at the next start; existing sessions are not restarted.
|
|
585
|
+
|
|
586
|
+
**Claude login credentials.** At a Claude start, OATS checks for
|
|
587
|
+
`$CLAUDE_CONFIG_DIR/.credentials.json`, or `$HOME/.claude/.credentials.json`
|
|
588
|
+
when no config directory is selected, using the launch's effective environment.
|
|
589
|
+
If OATS sets `CLAUDE_CODE_OAUTH_TOKEN` through a literal, either reference kind,
|
|
590
|
+
or a capability's launch contribution, it refuses with
|
|
591
|
+
`E_CLAUDE_LOGIN_CREDENTIAL`, naming the exact credential file it found. An
|
|
592
|
+
empty value counts. Remove the `/login`
|
|
593
|
+
credential from that Claude configuration and use `oats harness token set
|
|
594
|
+
claude` to provision an inference-only token. Without an OATS-set token, a
|
|
595
|
+
personal `/login` credential is allowed silently. An inherited token does not
|
|
596
|
+
select the token route.
|
|
597
|
+
Other harnesses are unaffected. Spawn preview and apply check the predictable
|
|
598
|
+
configuration before creating a home, worktree or identity. A selector supplied
|
|
599
|
+
by a capability hook is checked after its launch environment is known, and
|
|
600
|
+
every actual launch checks its final pane again. On macOS, Claude's `/login`
|
|
601
|
+
credential lives in the Keychain; this file check does not inspect it.
|
|
602
|
+
|
|
603
|
+
Both reference kinds use `OATS_LAUNCH_REF_<NAME>` aliases. Their values are
|
|
604
|
+
absent from process arguments, tmux command lines, recipes, events and logs.
|
|
605
|
+
The kernel hands them to the pane through a per-start file in the instance
|
|
606
|
+
home, created exclusively with mode 0600; the launcher reads and deletes it
|
|
607
|
+
before executing the pane command. A failed dispatch removes it. Retirement
|
|
608
|
+
recovery excludes leftover handoff files. Each subsequent start removes
|
|
609
|
+
abandoned handoffs before dispatch, even when the new launch has no references. The start environment records only
|
|
610
|
+
keyed digests of reference values, including file references, so a resume
|
|
611
|
+
refuses a changed value; an ordinary start adopts a rotated file.
|
|
612
|
+
|
|
555
613
|
**The instance's `oats`.** Every launch (`oats spawn`, `session start`,
|
|
556
614
|
`session restart`, locally or through `--server`) writes `<home>/.oats/bin/oats`,
|
|
557
615
|
a link to the launching kernel's `bin/oats.mjs`, and runs the harness with
|
|
@@ -693,8 +751,8 @@ oats doctor # this deployment's files and the lock
|
|
|
693
751
|
```
|
|
694
752
|
|
|
695
753
|
Environment: `OATS_REMOTE_CACHE` relocates the fetch cache (which also holds
|
|
696
|
-
the bounded parsed-read cache
|
|
697
|
-
it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
|
|
754
|
+
the bounded parsed-read cache, the observations `--max-age` reuses and the
|
|
755
|
+
records of verified package trees; all of it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
|
|
698
756
|
catalog file. The read verbs (`status`, `workspace status`, `souls`,
|
|
699
757
|
`capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
|
|
700
758
|
`spawn --preview`), and a spawn apply bound by `--expect-decision`, take
|
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# Agent team container
|
|
2
|
+
|
|
3
|
+
`container/agent/` supplies an agent image and a Compose service for one
|
|
4
|
+
team's trust group. It runs non-root sshd on port 2222; the operator uses the
|
|
5
|
+
existing [server route](servers.md) to connect, preview and spawn. The
|
|
6
|
+
entrypoint creates private state directories and host keys, then starts
|
|
7
|
+
sshd. Deployment setup and seat admission belong to the operator.
|
|
8
|
+
|
|
9
|
+
## Configuration contract
|
|
10
|
+
|
|
11
|
+
The same inputs apply to a Compose service or a platform's container spec:
|
|
12
|
+
|
|
13
|
+
| Input | Purpose |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| Deployment repository and commit | Operator provisions `/state/deploy`; its `oats-lock.json` pins packages and souls. Record the source and lock commits in the receipt. |
|
|
16
|
+
| aweb/AWID endpoints and team identifier | Deployment configuration; the platform's egress allowlist admits the endpoints. |
|
|
17
|
+
| Operator SSH public key | Read-only `authorized_keys` mount. |
|
|
18
|
+
| Resource limits | Runtime pids, memory and CPU limits. |
|
|
19
|
+
| Approved mounts | Explicit list, checked against the running container. |
|
|
20
|
+
| Egress destination list | Platform's resolver/forwarder configuration, outside the agent container. |
|
|
21
|
+
| Harness launch environment | Non-secret literals or file references, resolved at process start. |
|
|
22
|
+
|
|
23
|
+
Credentials never go in the image, build arguments, Compose environment, env
|
|
24
|
+
files or OATS configuration literals. The operator provisions ordinary
|
|
25
|
+
member seats and an inference-only Claude setup-token. Team/controller keys,
|
|
26
|
+
owner authority and service credentials stay outside the container. A
|
|
27
|
+
`/login` credential or a copy of `~/.claude` must never enter it.
|
|
28
|
+
|
|
29
|
+
## Build and upgrade
|
|
30
|
+
|
|
31
|
+
From a checkout at the reviewed commit:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
env -i PATH="$PATH" docker build --platform linux/arm64 \
|
|
35
|
+
-t oats-agent:reviewed container/agent
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Use `linux/amd64` on the target builder. The Dockerfile pins Node 22 Debian
|
|
39
|
+
Bookworm slim by its multi-architecture index digest; the committed
|
|
40
|
+
`package.json` and `package-lock.json` pin the CLI versions and npm integrity
|
|
41
|
+
hashes. `npm ci --ignore-scripts` installs the dependency closure. Only
|
|
42
|
+
`@awebai/aw` is rebuilt with lifecycle scripts, in a build step without a
|
|
43
|
+
network. Claude's matching native binary is linked directly from its locked
|
|
44
|
+
platform package, without running its installer. Each CLI's version command
|
|
45
|
+
must succeed during the build.
|
|
46
|
+
|
|
47
|
+
`libnss-wrapper` is the extra OS package needed for arbitrary UID support.
|
|
48
|
+
No credentials or SSH host keys are baked in. The build context allowlist
|
|
49
|
+
excludes everything except the image's five inputs.
|
|
50
|
+
|
|
51
|
+
A derived image may add reviewed OS tools with `USER root` and `RUN`, then
|
|
52
|
+
restore `USER agent`. Those build steps use the system passwd/group database.
|
|
53
|
+
The entrypoint enables nss_wrapper only after generating the runtime
|
|
54
|
+
database; SSH command environments also enable it. An overridden entrypoint
|
|
55
|
+
or `docker exec` uses system NSS, so an arbitrary numeric UID may have no
|
|
56
|
+
name there. Use the SSH route for commands that require the `agent` mapping.
|
|
57
|
+
|
|
58
|
+
CLIs upgrade only by building and selecting a new image. Global npm installs
|
|
59
|
+
fail on the read-only root. To update the OATS pin, change its one dependency
|
|
60
|
+
version and regenerate this directory's lock with
|
|
61
|
+
`npm install --package-lock-only --ignore-scripts`; review both files. Do not
|
|
62
|
+
use `--install-oats` or `--install-aw` against a running container.
|
|
63
|
+
|
|
64
|
+
The committed OATS 0.69.14 pin supports `env: { fromFile: ... }` and the
|
|
65
|
+
operator's `oats harness token set` route. Provision the token through the
|
|
66
|
+
[harness credential route](servers.md#harness-credentials) and collect live
|
|
67
|
+
acceptance evidence before claiming the two-seat inference milestone.
|
|
68
|
+
|
|
69
|
+
## Mounts and UID
|
|
70
|
+
|
|
71
|
+
The provisioner creates host directories with the runtime UID and GID.
|
|
72
|
+
The Compose defaults are `20001:20001`; use an explicit non-root UID:GID in
|
|
73
|
+
the target service so the group-readable token is readable.
|
|
74
|
+
|
|
75
|
+
The image also starts with a numeric UID alone, such as
|
|
76
|
+
`docker run --user 20001`. When that UID has no image passwd entry, Docker
|
|
77
|
+
assigns GID 0. The wrapper names that runtime group `agent`, and new files
|
|
78
|
+
in `/state` have GID 0. Such a run cannot read a root:20001 0750 login
|
|
79
|
+
directory or its 0440 token. Use `--user 20001:20001` for the team login;
|
|
80
|
+
the UID-only form proves startup and SSH support, not token access.
|
|
81
|
+
|
|
82
|
+
| Container path | Host ownership and mode | Access |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| `/state` | Runtime UID:GID, 0700 | Read/write; persistent |
|
|
85
|
+
| `/work` (optional) | Runtime UID:GID, 0700 | Read/write |
|
|
86
|
+
| `/etc/agent-login` | root:runtime-GID, 0750; `claude-token` root:runtime-GID, 0440 | Read-only |
|
|
87
|
+
| `/etc/agent-ssh/authorized_keys` | root-owned regular file, 0644 | Read-only |
|
|
88
|
+
| `/etc/resolv.conf` | Operator-provided resolver file | Read-only |
|
|
89
|
+
| `/tmp` | tmpfs, rw,nosuid,nodev,mode=1777 | Ephemeral |
|
|
90
|
+
|
|
91
|
+
All binds use `create_host_path: false`: a missing path fails startup.
|
|
92
|
+
`/state/home`, `/state/ssh` and `/state/deploy` are created 0700 by the agent.
|
|
93
|
+
`HOME=/state/home`. nss_wrapper reads passwd/group files generated in
|
|
94
|
+
`/state/ssh`, mapping the name `agent` to the actual UID/GID. The root
|
|
95
|
+
filesystem and `/etc/passwd` remain read-only. SSH sessions receive the same
|
|
96
|
+
mapping and HOME. The `agent` user has no sudo.
|
|
97
|
+
|
|
98
|
+
Host keys persist in `/state/ssh`; agents in the trust group can read them.
|
|
99
|
+
sshd accepts only `agent` public-key authentication, with PAM, password and
|
|
100
|
+
keyboard-interactive authentication off. Forwarding is disabled: OATS's
|
|
101
|
+
ControlMaster multiplexing uses SSH command/session channels and needs no
|
|
102
|
+
TCP, agent or X11 forwarding. The operator's jump host must separately permit
|
|
103
|
+
the ProxyJump connection to the container.
|
|
104
|
+
|
|
105
|
+
## Compose integration
|
|
106
|
+
|
|
107
|
+
Supply these plain variables to the bundle's env file:
|
|
108
|
+
|
|
109
|
+
| Variable | Meaning |
|
|
110
|
+
| --- | --- |
|
|
111
|
+
| `TEAM` | Container name suffix: `oats-agent-${TEAM}`; service key is `agent`. |
|
|
112
|
+
| `AGENT_IMAGE` | Reviewed image tag or digest. |
|
|
113
|
+
| `AGENT_UID`, `AGENT_GID` | Runtime IDs; both default to 20001. |
|
|
114
|
+
| `TEAM_STATE_DIR` | Absolute host directory for `/state`. |
|
|
115
|
+
| `TEAM_WORK_DIR` | Optional absolute host directory for `/work`. |
|
|
116
|
+
| `TEAM_LOGIN_DIR` | Absolute host directory containing `claude-token`. |
|
|
117
|
+
| `AUTHORIZED_KEYS_FILE` | Absolute host public-key file. |
|
|
118
|
+
| `RESOLV_CONF_FILE` | Absolute host resolver file; always required. |
|
|
119
|
+
| `AGENT_PIDS`, `AGENT_MEMORY`, `AGENT_CPUS` | Positive limits; memory uses bytes, k, m or g. |
|
|
120
|
+
| `AGENTS_NETWORK`, `AGENT_IP` | Installer-created external network and container address. |
|
|
121
|
+
|
|
122
|
+
The bundle owns the network, resolver, forwarder, firewall and their bypass
|
|
123
|
+
checks. The agent service publishes no ports and sets no DNS or extra-hosts
|
|
124
|
+
override. It joins only the named external `agents` network. Its restart
|
|
125
|
+
policy is `unless-stopped`; security flags are fixed in the service file.
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
|
|
129
|
+
-f compose.yaml -f container/agent/compose.agent.yaml config
|
|
130
|
+
docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
|
|
131
|
+
-f compose.yaml -f container/agent/compose.agent.yaml up -d
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
When `TEAM_WORK_DIR` is set, append
|
|
135
|
+
`-f container/agent/compose.agent.work.yaml` to both commands. Otherwise omit
|
|
136
|
+
the override: the base has no `/work` mount. With multiple Compose files,
|
|
137
|
+
paths resolve relative to the first file; use absolute host paths. Container
|
|
138
|
+
down/upgrade preserves `/state`; the operator owns provisioning and rollback.
|
|
139
|
+
|
|
140
|
+
## OATS over SSH
|
|
141
|
+
|
|
142
|
+
The operator's SSH alias selects the key, host-key verification, port 2222
|
|
143
|
+
and jump route. The equivalent connection is:
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
ssh -J <provisioner>@<host> -p 2222 agent@<container-ip>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Register an already provisioned deployment, or connect it from the operator's
|
|
150
|
+
deployment using its source reference:
|
|
151
|
+
|
|
152
|
+
```sh
|
|
153
|
+
oats server add team-agent --ssh <ssh-alias> --workspace /state/deploy \
|
|
154
|
+
--oats /usr/local/bin/oats --path /usr/local/bin:/usr/bin:/bin
|
|
155
|
+
oats server connect team-agent --ssh <ssh-alias> --dir /state/deploy \
|
|
156
|
+
--oats /usr/local/bin/oats --path /usr/local/bin:/usr/bin:/bin
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Use public HTTPS package pins unless a separate reviewed credential route
|
|
160
|
+
is provisioned. Verify `server connect` reports ready. The operator places
|
|
161
|
+
two independently admitted ordinary-member identities at
|
|
162
|
+
`/state/seats/<alias>/.aw`; each spawn selects one:
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
oats spawn <soul> --server team-agent --harness claude --preview --provider oats.aweb identity.source=/state/seats/<alias>/.aw
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Preview runs no provider hook and does not validate a missing seat. Apply
|
|
169
|
+
only after reviewing it and provisioning its seat; use the same arguments
|
|
170
|
+
without `--preview`. Keep the team and controller keys outside the container.
|
|
171
|
+
|
|
172
|
+
The pinned OATS release supports this file-backed launch configuration:
|
|
173
|
+
|
|
174
|
+
```yaml
|
|
175
|
+
launch-configs:
|
|
176
|
+
team-claude:
|
|
177
|
+
harness: claude
|
|
178
|
+
env:
|
|
179
|
+
CLAUDE_CONFIG_DIR: /state/home/.claude
|
|
180
|
+
CLAUDE_CODE_OAUTH_TOKEN:
|
|
181
|
+
fromFile: /etc/agent-login/claude-token
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Select it with `--launch-config team-claude`. The operator provisions only a
|
|
185
|
+
`claude setup-token` result through the supported token route. It is readable
|
|
186
|
+
by every agent in the same trust group; read-only mounting does not hide it
|
|
187
|
+
or narrow its authority. Never share the mount across trust groups.
|
|
188
|
+
|
|
189
|
+
## The kernel's periodic work
|
|
190
|
+
|
|
191
|
+
The image's entrypoint starts sshd and nothing else. A container has no
|
|
192
|
+
launchd and no systemd user manager, so in it nothing resumes the sessions
|
|
193
|
+
that were lost when it last stopped, nothing runs the schedule tick, and
|
|
194
|
+
nothing stops the agents in order when the runtime stops it: they are killed
|
|
195
|
+
with the container and read `lost`.
|
|
196
|
+
|
|
197
|
+
`oats host run`
|
|
198
|
+
([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)) is the
|
|
199
|
+
kernel command that does those three things in one foreground process. The
|
|
200
|
+
image's pinned OATS does not have it, and the image does not run it. An operator can run it by hand in a
|
|
201
|
+
container whose OATS has it, and the entrypoint of a derived image can end
|
|
202
|
+
in it. What such an entrypoint has to respect:
|
|
203
|
+
|
|
204
|
+
- **`oats host run` is the process the runtime's signal must reach and
|
|
205
|
+
wait for.** Under `tini -g` that is tini's direct child: start sshd in the
|
|
206
|
+
background, then `exec oats host run`. `tini -g` signals its child's
|
|
207
|
+
process group; the OATS tmux server and the harnesses under it are in
|
|
208
|
+
sessions of their own, outside that group, so they run until `oats host
|
|
209
|
+
run` stops them. Measured with tini 0.19.0 and tmux 3.3a.
|
|
210
|
+
- **The runtime's stop timeout must be longer than the stop.** On SIGTERM
|
|
211
|
+
`oats host run` waits for a tick that is running, lists the instances and
|
|
212
|
+
gives each harness `--stop-grace` seconds (default 20). Docker's default
|
|
213
|
+
stop timeout is 10 seconds.
|
|
214
|
+
- **It does not supervise sshd.** If sshd ends while it runs, the agents and
|
|
215
|
+
the tick go on and the operator's route is gone.
|
|
216
|
+
- **The tmux server a resume starts gets its environment**, its `PATH`
|
|
217
|
+
included.
|
|
218
|
+
|
|
219
|
+
It ticks the deployments the container's host schedule registry lists. To
|
|
220
|
+
register one where no timer can be installed:
|
|
221
|
+
|
|
222
|
+
```sh
|
|
223
|
+
oats schedule host install --register-only --dir /state/deploy
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
([schedules.md](schedules.md#without-a-host-timer)). Plain `host install`
|
|
227
|
+
fails in a container after registering, since there is no systemd user
|
|
228
|
+
manager. Over the route (`--server team-agent`) the option is refused
|
|
229
|
+
(`E_REMOTE_INCOMPATIBLE`, nothing sent) unless the container's OATS
|
|
230
|
+
advertises `schedule-host-register-only`; the image's pin does not.
|
|
231
|
+
|
|
232
|
+
## Acceptance and evidence
|
|
233
|
+
|
|
234
|
+
The host needs Docker and Node 22.5+. Export the same plain variables used for
|
|
235
|
+
Compose, then run:
|
|
236
|
+
|
|
237
|
+
```sh
|
|
238
|
+
container/agent/accept.sh "oats-agent-${TEAM}" --evidence local
|
|
239
|
+
container/agent/accept.sh "oats-agent-${TEAM}" --evidence target-amd64
|
|
240
|
+
container/agent/accept.sh "oats-agent-${TEAM}" --evidence live-lab \
|
|
241
|
+
--claude /state/deploy/agents/<soul>/instances/<instance>
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Choose the label matching the actual run. `local` accepts the builder's
|
|
245
|
+
architecture; the other labels require amd64 and root:GID 0750
|
|
246
|
+
login-directory metadata, plus root:GID 0440 when a token is present.
|
|
247
|
+
If the token file is absent, its check reports `NOT RUN` and acceptance
|
|
248
|
+
continues; `claude -p` is skipped until the token exists. Do not create a
|
|
249
|
+
placeholder token. Local fixtures never use a real login.
|
|
250
|
+
Run the live Claude mode separately for each admitted instance home;
|
|
251
|
+
the home is an evidence label and an `instance.json` existence check. The
|
|
252
|
+
probe runs from a private temporary directory under `/tmp`, removed on
|
|
253
|
+
success or failure, with `--setting-sources user`. It uses the container's
|
|
254
|
+
user settings, excluding the instance's project settings, hooks and
|
|
255
|
+
`CLAUDE.md`, so the probe does not clear that live instance's waiting claim.
|
|
256
|
+
It reads the token only inside the container and requires the exact inference
|
|
257
|
+
response. It records no raw Claude output.
|
|
258
|
+
|
|
259
|
+
The script compares inspect settings and the exact bind list to the exported
|
|
260
|
+
variables. It resolves `AGENT_IMAGE` independently and requires that image's
|
|
261
|
+
ID, reference and start command, and its complete environment (printing only
|
|
262
|
+
names of differing variables). Other comparisons include supplementary
|
|
263
|
+
groups, namespace overrides, sysctls, published ports, resolver overrides
|
|
264
|
+
and the single network/address. The OCI runtime must match the daemon's
|
|
265
|
+
independently read default; shared memory stays at Docker's 64 MiB default,
|
|
266
|
+
the OOM killer stays enabled, and device cgroup rules stay empty. The total
|
|
267
|
+
memory-plus-swap setting is absent or Docker's default of twice the memory
|
|
268
|
+
limit; unlimited swap is refused.
|
|
269
|
+
It checks the process's UID/GID/supplementary groups/capabilities/no-new-privileges
|
|
270
|
+
and non-root sshd's banner, scans `/` as container root (pruning `/proc`,
|
|
271
|
+
`/sys`, `/dev` and the agent-scanned `/state`, `/tmp`, `/run`, `/work`),
|
|
272
|
+
and scans those trees plus writable `/dev/shm` and `/dev/mqueue` as the agent
|
|
273
|
+
for `.credentials.json`. When a token is present, it checks
|
|
274
|
+
that the token is readable and not writable. It proves a global npm install fails using an
|
|
275
|
+
offline local package. Scan errors fail acceptance. The root inspection
|
|
276
|
+
process receives no added capabilities. Token provenance still needs the
|
|
277
|
+
operator's receipt: permissions and successful inference cannot distinguish
|
|
278
|
+
all credential classes.
|
|
279
|
+
|
|
280
|
+
A successful script run covers those checks only. The complete platform
|
|
281
|
+
receipt also needs `server connect`, both admitted-seat spawn previews and
|
|
282
|
+
applies, the source/lock commit, viewer, package sync, the bundle's network
|
|
283
|
+
and bypass evidence, mail/chat exchange, governance refusals and any broker
|
|
284
|
+
checks. Record target evidence separately from local evidence. Container
|
|
285
|
+
startup and a local preview do not establish two running agents.
|
|
286
|
+
|
|
287
|
+
`test/agent-container.test.mjs` pins the image, Compose and SSH security
|
|
288
|
+
settings and rejects weakened inspect fixtures. The SSH guard requires flat
|
|
289
|
+
`Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
|
|
290
|
+
equals-delimited keywords and quoted keywords. Follow the repository's
|
|
291
|
+
local check limits; full suites run in CI.
|
|
@@ -294,6 +294,8 @@ Each entry's manifests, souls and integrity are read at the observed commit →
|
|
|
294
294
|
`{ lock, changes: [{ id, from, to, commit }] }` (`to: null`: no longer declared).
|
|
295
295
|
|
|
296
296
|
- A branch is `E_PACKAGE_INTEGRITY { why: "branch" }`.
|
|
297
|
+
- A manifest whose `package` is not the entry's key is `E_PACKAGE_INTEGRITY { why: "package-id" }`,
|
|
298
|
+
fresh or already locked.
|
|
297
299
|
- An unchanged version, source and path is re-verified: a moved commit or different integrity,
|
|
298
300
|
capabilities or souls is `E_PACKAGE_INTEGRITY`.
|
|
299
301
|
- A malformed package is `E_PACKAGE_MANIFEST`.
|