@awebai/oats 0.69.19 → 0.69.21
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 +28 -5
- package/docs/capabilities.md +27 -14
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +218 -18
- package/docs/desktop-cli-api.md +105 -11
- package/docs/desktop.md +122 -65
- package/docs/implementation.md +3 -2
- 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-notes/v0.69.20.md +325 -0
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/servers.md +9 -3
- package/docs/souls-and-instances.md +15 -2
- package/docs/upgrading.md +17 -5
- package/docs/workspaces.md +13 -7
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +1 -0
- package/lib/core.mjs +36 -198
- package/lib/hook-outcome.mjs +6 -0
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +19 -1
- package/lib/instance-listing.mjs +11 -6
- package/lib/instance-pin.mjs +59 -0
- package/lib/kernel-features.mjs +1 -1
- package/lib/launch-prompt-fixtures/README.md +6 -0
- package/lib/retire-admission.mjs +215 -0
- package/lib/servers.mjs +11 -3
- package/package-catalog.json +3 -3
- package/package.json +1 -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/lifecycle-confirmation.mjs +4 -2
- package/packages/client/lifecycle-contract.mjs +11 -6
- package/packages/client/remote-roster.mjs +4 -0
- package/packages/client/roster-row-facts.mjs +50 -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 +211 -28
package/bin/oats.mjs
CHANGED
|
@@ -83,7 +83,7 @@ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = aw
|
|
|
83
83
|
const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
|
|
84
84
|
const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
|
|
85
85
|
const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
|
|
86
|
-
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
86
|
+
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
87
87
|
const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
|
|
88
88
|
const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
|
|
89
89
|
const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
|
|
@@ -1453,8 +1453,8 @@ async function instanceCmd() {
|
|
|
1453
1453
|
if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
|
|
1454
1454
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1455
1455
|
if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
|
|
1456
|
-
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1457
|
-
if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1456
|
+
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1457
|
+
if (!["git", "diff", "stop", "events", "color", "background", "pin", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1458
1458
|
dropAmbientRoot();
|
|
1459
1459
|
if (sub === "events") {
|
|
1460
1460
|
// K7: typed producer events, bounded window; nothing inferred.
|
|
@@ -1528,6 +1528,25 @@ async function instanceCmd() {
|
|
|
1528
1528
|
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
1529
1529
|
}
|
|
1530
1530
|
}
|
|
1531
|
+
if (sub === "pin") {
|
|
1532
|
+
// Feature instance-pin: presentation only, so no plan; addressed as `instance background` addresses an instance.
|
|
1533
|
+
const homeOpt = flag("home");
|
|
1534
|
+
if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1535
|
+
const pinUsage = "usage: oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1536
|
+
// The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
|
|
1537
|
+
const words = [];
|
|
1538
|
+
for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
|
|
1539
|
+
if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${pinUsage}`);
|
|
1540
|
+
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
1541
|
+
try {
|
|
1542
|
+
const r = setInstancePin(dirFlag(), root, name, { home: homeOpt, pinned: words[0] === "on" });
|
|
1543
|
+
if (JSON_MODE) { jsonOk(r); return; }
|
|
1544
|
+
console.log(`${r.instance}: ${r.pinned ? "pinned" : "not pinned"}${r.changed ? "" : " (unchanged)"}`);
|
|
1545
|
+
return;
|
|
1546
|
+
} catch (e) {
|
|
1547
|
+
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
1548
|
+
}
|
|
1549
|
+
}
|
|
1531
1550
|
if (sub === "same-work") {
|
|
1532
1551
|
// Feature instance-same-work: presentation only, so no plan; addressed as color addresses an instance.
|
|
1533
1552
|
const homeOpt = flag("home");
|
|
@@ -3012,7 +3031,7 @@ function retireCmd() {
|
|
|
3012
3031
|
dropAmbientRoot();
|
|
3013
3032
|
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
3014
3033
|
try {
|
|
3015
|
-
const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
|
|
3034
|
+
const plan = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") });
|
|
3016
3035
|
if (args.includes("--json")) { jsonOk(plan); return; }
|
|
3017
3036
|
console.log(`retire ${name} — plan ${plan.planRevision}`);
|
|
3018
3037
|
console.log(` session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? (plan.facts.work.detached ? "detached" : "a ref OATS carries no branch name for")}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
|
|
@@ -3061,7 +3080,7 @@ function retireCmd() {
|
|
|
3061
3080
|
// its extra trees as it names them (the retire refuses as stale rather than move or remove one
|
|
3062
3081
|
// that no longer reads that way when it gets to them).
|
|
3063
3082
|
revalidate = () => {
|
|
3064
|
-
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
|
|
3083
|
+
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") }); } catch (e) { planFailure = e; throw e; }
|
|
3065
3084
|
if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
|
|
3066
3085
|
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
|
|
3067
3086
|
};
|
|
@@ -5245,6 +5264,10 @@ Usage:
|
|
|
5245
5264
|
oats instance background <instance> on|off [--home <abs>] [--json]
|
|
5246
5265
|
whether clients list the instance under
|
|
5247
5266
|
Background, presentation only
|
|
5267
|
+
oats instance pin <instance> on|off [--home <abs>] [--json]
|
|
5268
|
+
pin the instance at the top of its machine's
|
|
5269
|
+
list; shared, as every viewer of the machine
|
|
5270
|
+
reads it from the home
|
|
5248
5271
|
oats instance same-work <instance> on|off [--home <abs>] [--json]
|
|
5249
5272
|
record that this instance does the same work as
|
|
5250
5273
|
its parent (on needs a recorded parent); clients
|
package/docs/capabilities.md
CHANGED
|
@@ -157,6 +157,7 @@ A self-contained package has an `oats.json`:
|
|
|
157
157
|
reads what there is to undo from the home and from the service it
|
|
158
158
|
registered with, and answers `meta: { retired: false, reason:
|
|
159
159
|
"nothing-to-delete" }` when there is nothing: that is a complete cleanup.
|
|
160
|
+
Every other explicit `retired: false` outcome is an incomplete cleanup.
|
|
160
161
|
- A capability declaring a **required** spawn hook should declare a `retire` hook
|
|
161
162
|
too. Without one, OATS has no way to undo what the spawn hook did and no way to
|
|
162
163
|
know whether it did anything, so a failure quarantines the home rather than
|
|
@@ -183,18 +184,30 @@ A self-contained package has an `oats.json`:
|
|
|
183
184
|
the branch gone (a damaged ref, a failed read), the retry stays incomplete
|
|
184
185
|
with `git branch <b>: could not verify whether it still exists (…)`. A retry that still cannot
|
|
185
186
|
finish keeps the home again, names what is outstanding, and exits nonzero.
|
|
186
|
-
-
|
|
187
|
-
|
|
188
|
-
`
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
187
|
+
- **A home whose retire hooks cannot run is refused before anything is stopped,
|
|
188
|
+
run or removed, children included.** The same admission rule applies to
|
|
189
|
+
`oats retire --plan`, the Desktop's Remove plan and every apply path.
|
|
190
|
+
`E_UNIDENTIFIED_INSTANCE_HOME` names the cause, the recorded capabilities
|
|
191
|
+
that may have left state, and the manual-cleanup remedy. No current
|
|
192
|
+
deployment configuration can prove what an old home registered.
|
|
193
|
+
A normal home needs its recorded `capabilityRuntime` and a context repository
|
|
194
|
+
to run its hooks. The context is its recorded `repo`, or the repository Git
|
|
195
|
+
identifies for its own worktree when the record names none. An explicit
|
|
196
|
+
capability set with no retire hooks proves that none is owed. A captured home from before 0.26 cannot run its hooks:
|
|
197
|
+
only an explicit empty captured `hookOrder`, with no capability metadata,
|
|
198
|
+
hook intents, hook failures or lifecycle marked `*-cleanup-required`,
|
|
199
|
+
proves that no capability's spawn hook ran. Missing
|
|
200
|
+
information proves nothing.
|
|
201
|
+
- The **escape hatch is `oats retire <instance> --force`**. This includes
|
|
202
|
+
homes spawned before `capabilityRuntime`, captured homes without proof of
|
|
203
|
+
no spawn hooks, a home without a usable record or cleanup descriptor, and
|
|
204
|
+
a home whose recorded retire hooks have no context repository. Inspect the
|
|
205
|
+
home and clean up external identities and memberships with the provider's
|
|
206
|
+
tooling first. Force can remove the home while leaving that state active;
|
|
207
|
+
its output keeps the warnings about hooks that did not run and state that
|
|
208
|
+
was not revoked. An unreadable `instance.json` still refuses even with
|
|
209
|
+
force. A forced self-retirement carries the force choice into its deferred
|
|
210
|
+
completion. A usable cleanup descriptor can drive the normal retry. Usable
|
|
198
211
|
means it satisfies the versioned cleanup contract the rollback writes, checked
|
|
199
212
|
to the depth the retry consumes it: `version`, a context `repo`, a recognised
|
|
200
213
|
`work` mode (plus a `branch` for `worktree` — an unknown mode would skip the
|
|
@@ -245,7 +258,7 @@ A self-contained package has an `oats.json`:
|
|
|
245
258
|
verifiably alive (its pid runs with the recorded start time):
|
|
246
259
|
- `oats status` gives the home's row `spawnInProgress: true` and no
|
|
247
260
|
`rollbackIncomplete`;
|
|
248
|
-
- `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--force` included;
|
|
261
|
+
- `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--plan` and `--force` included;
|
|
249
262
|
- `oats session start` refuses it as any quarantined home
|
|
250
263
|
(`E_INSTANCE_RETIRING`).
|
|
251
264
|
|
|
@@ -320,7 +333,7 @@ A self-contained package has an `oats.json`:
|
|
|
320
333
|
- an exact name that is `.oats`, `.agents` or `.claude`, or that starts
|
|
321
334
|
with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
|
|
322
335
|
`.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
|
|
323
|
-
`.oats-background` or `.oats-same-work`: the top-level entries the kernel
|
|
336
|
+
`.oats-background`, `.oats-pinned` or `.oats-same-work`: the top-level entries the kernel
|
|
324
337
|
itself writes in an instance home;
|
|
325
338
|
- a prefix that starts with `.oats-`.
|
|
326
339
|
|
|
@@ -374,7 +374,7 @@
|
|
|
374
374
|
"description": "Home entries the kernel owns cannot be declared.",
|
|
375
375
|
"anyOf": [
|
|
376
376
|
{"pattern": "^\\.(?:oats|agents|claude)$"},
|
|
377
|
-
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|same-work)"},
|
|
377
|
+
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work)"},
|
|
378
378
|
{"pattern": "^\\.oats-.*\\*$"}
|
|
379
379
|
]
|
|
380
380
|
}
|
package/docs/container.md
CHANGED
|
@@ -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
|
|
174
235
|
```
|
|
175
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));'
|
|
260
|
+
```
|
|
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
|
|
@@ -305,6 +398,11 @@ launch-configs:
|
|
|
305
398
|
CLAUDE_CONFIG_DIR: /state/home/.claude
|
|
306
399
|
CLAUDE_CODE_OAUTH_TOKEN:
|
|
307
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"
|
|
308
406
|
```
|
|
309
407
|
|
|
310
408
|
Select it with `--launch-config team-claude`. The operator provisions only a
|
|
@@ -312,6 +410,47 @@ Select it with `--launch-config team-claude`. The operator provisions only a
|
|
|
312
410
|
by every agent in the same trust group; read-only mounting does not hide it
|
|
313
411
|
or narrow its authority. Never share the mount across trust groups.
|
|
314
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
|
+
|
|
315
454
|
### After changing a credential
|
|
316
455
|
|
|
317
456
|
A resume starts an agent under the values its last start recorded. When the
|
|
@@ -384,17 +523,21 @@ What the image's files fix for that:
|
|
|
384
523
|
|
|
385
524
|
- **PID-only tini signals the Node supervisor.** It forwards TERM to host
|
|
386
525
|
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
|
|
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
|
|
388
529
|
host-run exit is reported and drains the other children before a nonzero
|
|
389
530
|
container exit, so
|
|
390
531
|
the restart policy can restart it. The broker runs as the agent uid; its
|
|
391
532
|
default state directory is `/state/home/.config/aw/wake`, so registrations
|
|
392
533
|
survive container replacement and it starts again even with no spawn.
|
|
393
|
-
- **`stop_grace_period:
|
|
394
|
-
10 seconds
|
|
395
|
-
killed at the timeout leaves agents
|
|
396
|
-
platform that does not read the Compose
|
|
397
|
-
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.
|
|
398
541
|
- **A healthcheck on sshd.** The supervisor reports an sshd exit; if
|
|
399
542
|
sshd ends, the agents and the tick go on and the operator's route is gone.
|
|
400
543
|
The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
|
|
@@ -464,7 +607,7 @@ variables. It resolves `AGENT_IMAGE` independently and requires that image's
|
|
|
464
607
|
ID, reference and start command, and its complete environment (printing only
|
|
465
608
|
names of differing variables). Other comparisons include supplementary
|
|
466
609
|
groups, namespace overrides, sysctls, published ports, resolver overrides
|
|
467
|
-
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
|
|
468
611
|
healthcheck the service file's, so a container made before either was set
|
|
469
612
|
is refused until it is recreated. The OCI runtime must match the daemon's
|
|
470
613
|
independently read default; shared memory stays at Docker's 64 MiB default,
|
|
@@ -665,3 +808,60 @@ credentials. The publish step stores
|
|
|
665
808
|
registry authentication in a private temporary file and removes it on exit.
|
|
666
809
|
It receives no npm publish credential. To roll back a deployed image, select
|
|
667
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).
|