@awebai/oats 0.69.17 → 0.69.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +7 -0
- package/docs/container.md +172 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/desktop-cli-api.md +73 -33
- package/docs/desktop.md +40 -18
- package/docs/execution-targets.md +36 -33
- package/docs/implementation.md +7 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +7 -7
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +24 -19
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/servers.md +3 -1
- package/docs/souls-and-instances.md +18 -16
- package/docs/trust-model.md +119 -0
- package/docs/upgrading.md +39 -19
- package/docs/workspaces.md +3 -3
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +24 -9
- package/lib/errors.mjs +1 -1
- package/lib/home-owner.mjs +25 -0
- package/lib/host-run-admission.mjs +21 -0
- package/lib/host-run-child.mjs +31 -0
- package/lib/host-run-work.mjs +150 -0
- package/lib/host-run.mjs +20 -11
- package/lib/instance-naming.mjs +26 -44
- package/lib/packages.mjs +0 -43
- package/lib/pi-bridge.mjs +18 -6
- package/lib/schedule.mjs +5 -3
- package/lib/servers.mjs +4 -3
- package/lib/session-end.mjs +9 -0
- package/lib/session-resume.mjs +19 -9
- package/lib/session-seen.mjs +13 -8
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +2 -2
- package/packages/client/above-tested-notice.mjs +30 -0
- package/packages/client/above-tested.mjs +225 -0
- package/packages/client/cli-locator.mjs +67 -52
- package/packages/client/deployment-label.mjs +4 -4
- package/packages/client/instance-name.mjs +5 -29
- package/packages/client/session-start.mjs +31 -3
- package/packages/client/workspace-choices.mjs +1 -1
- package/packages/client/workspace-views.mjs +1 -1
- package/packages/record/README.md +10 -8
- package/packages/record/lib/process-identity.mjs +14 -36
- package/packages/tui/lib/read.mjs +19 -3
- package/skills/oats-getting-started/SKILL.md +33 -4
|
@@ -218,23 +218,6 @@ export function processLiveness(record) {
|
|
|
218
218
|
|
|
219
219
|
// ---------- the boot a record was taken in ----------
|
|
220
220
|
|
|
221
|
-
/** What says this process runs in a container: a file each runtime puts in its containers, or the
|
|
222
|
-
* variable Kubernetes sets in every pod. Docker writes `/.dockerenv`, Podman `/run/.containerenv`. */
|
|
223
|
-
const CONTAINER_FILES = ["/.dockerenv", "/run/.containerenv"];
|
|
224
|
-
const inContainer = (exists, env) => CONTAINER_FILES.some((file) => exists(file)) || Boolean(env.KUBERNETES_SERVICE_HOST);
|
|
225
|
-
|
|
226
|
-
/** When PID 1 started, as this process sees PID 1: field 22 of `/proc/1/stat`, in clock ticks after
|
|
227
|
-
* the kernel's boot, as the digits the kernel printed; null when the file cannot be read or does
|
|
228
|
-
* not hold it. The fields are counted after the last ")": the name (field 2) may hold spaces and
|
|
229
|
-
* parentheses. */
|
|
230
|
-
function initStart(read) {
|
|
231
|
-
try {
|
|
232
|
-
const stat = read("/proc/1/stat"), named = stat.lastIndexOf(")");
|
|
233
|
-
const start = named < 0 ? undefined : stat.slice(named + 1).trim().split(/\s+/)[19];
|
|
234
|
-
return typeof start === "string" && /^\d+$/.test(start) ? start : null;
|
|
235
|
-
} catch { return null; }
|
|
236
|
-
}
|
|
237
|
-
|
|
238
221
|
/** macOS's boot time, from the system's sysctl (systemTool), never one the caller's PATH names: a
|
|
239
222
|
* PATH without /usr/sbin, or with another sysctl first, must not change or lose the boot id. */
|
|
240
223
|
function systemSysctl() {
|
|
@@ -246,24 +229,16 @@ function systemSysctl() {
|
|
|
246
229
|
* process the kernel may have recorded: the sessions, their terminal server, a sweep.
|
|
247
230
|
* - macOS: the boot time (`sysctl -n kern.boottime`, its `sec`/`usec`).
|
|
248
231
|
* - Linux: the kernel's boot id (`/proc/sys/kernel/random/boot_id`).
|
|
249
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
* it ends, so its start is the same for every process of one run and another in the next; the
|
|
253
|
-
* boot id keeps a start apart from the same number of ticks after another kernel boot. When
|
|
254
|
-
* PID 1's start cannot be read there, the boot id alone: the sweep then counts a home's starts
|
|
255
|
-
* across the runs and applies the in-boot clause across them, so it starts less, never more.
|
|
256
|
-
* PID 1's start is read only in a container. A process in a PID namespace of its own on a host (a
|
|
257
|
-
* command a harness runs in a sandbox) reads that namespace's PID 1, which is not the machine's,
|
|
258
|
-
* and it is on the host's boot all the same.
|
|
232
|
+
* A container and a sandbox share the kernel's boot. Their environment, marker files and PID 1
|
|
233
|
+
* cannot change this identity: a holder's pid and processStart distinguish a dead or reused pid
|
|
234
|
+
* on that kernel. Old records that qualified the UUID are read by sameBoot below.
|
|
259
235
|
* Each is read from the kernel without privileges and written nowhere. */
|
|
260
|
-
export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"),
|
|
236
|
+
export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"), sysctl = systemSysctl } = {}) {
|
|
261
237
|
try {
|
|
262
238
|
if (platform === "linux") {
|
|
263
239
|
const id = read("/proc/sys/kernel/random/boot_id").trim();
|
|
264
240
|
if (!id) return null;
|
|
265
|
-
|
|
266
|
-
return start === null ? id : `${id}:${start}`;
|
|
241
|
+
return id;
|
|
267
242
|
}
|
|
268
243
|
if (platform === "darwin") { const m = /sec = (\d+), usec = (\d+)/.exec(sysctl()); return m ? `${m[1]}.${m[2]}` : null; }
|
|
269
244
|
} catch { /* unknown */ }
|
|
@@ -272,12 +247,15 @@ export function bootId({ platform = process.platform, read = (p) => readFileSync
|
|
|
272
247
|
let processBoot;
|
|
273
248
|
/** bootId, read once per process: a process never outlives its boot. */
|
|
274
249
|
export const thisBoot = () => (processBoot === undefined ? (processBoot = bootId()) : processBoot);
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
*
|
|
280
|
-
export const
|
|
250
|
+
// Only the historical Linux UUID:PID1-start format is normalized. Opaque boot identities (macOS
|
|
251
|
+
// included) keep their exact comparison. This does not rewrite records held by another process.
|
|
252
|
+
const linuxKernelBoot = (id) => typeof id === "string" ? id.replace(/^([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}):\d+$/i, "$1") : id;
|
|
253
|
+
/** True only for two known identities of the same kernel boot, including old qualified Linux IDs.
|
|
254
|
+
* Qualification never proves a live holder gone during an upgrade; pid/start still decide. */
|
|
255
|
+
export const sameBoot = (a, b) => typeof a === "string" && a !== "" && typeof b === "string" && b !== "" && linuxKernelBoot(a) === linuxKernelBoot(b);
|
|
256
|
+
/** Whether the two known identities establish another kernel boot. Without either boot the
|
|
257
|
+
* reader must judge the process itself; a missing/unreadable start remains unknown, never gone. */
|
|
258
|
+
export const takenInAnotherBoot = (boot) => (holder) => Boolean(boot) && typeof holder.bootId === "string" && holder.bootId !== "" && !sameBoot(holder.bootId, boot);
|
|
281
259
|
|
|
282
260
|
/** Whether a lock record names the boot it was taken in or its holder's start (`bootId`,
|
|
283
261
|
* `processStart`), whatever their values. */
|
|
@@ -106,7 +106,8 @@ export function admitDeployment(path, io = {}) {
|
|
|
106
106
|
|
|
107
107
|
/** Run the kernel once with `version --json` and make its record:
|
|
108
108
|
* -> Promise<{ ok: true, cli } | { ok: false, reason }>, never rejected.
|
|
109
|
-
* The answer is read with the shared parseProbeStdout and judged by the shared acceptProbe
|
|
109
|
+
* The answer is read with the shared parseProbeStdout and judged by the shared acceptProbe, against
|
|
110
|
+
* `testedVersion` (KERNEL_VERSION: the kernel it ships with); an
|
|
110
111
|
* accepted one becomes `cliRecord(payload, { bin, source: "tui" })`, the record every shared gate
|
|
111
112
|
* reads. `reason` is acceptProbe's own when it refused, and one of the TUI's four when there was
|
|
112
113
|
* no answer to judge. A nonzero exit or a timeout is a refusal even when stdout looks valid: a
|
|
@@ -115,7 +116,7 @@ export function admitDeployment(path, io = {}) {
|
|
|
115
116
|
* the caller shows it as it shows any kernel text.
|
|
116
117
|
* NOT detached, unlike every later child: it runs before the terminal is taken, and a Ctrl+C then
|
|
117
118
|
* must end it with the TUI. `timeoutMs` is for tests. */
|
|
118
|
-
export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = nodeExecFile, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
|
|
119
|
+
export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = nodeExecFile, timeoutMs = PROBE_TIMEOUT_MS, testedVersion = KERNEL_VERSION } = {}) {
|
|
119
120
|
return new Promise((done) => {
|
|
120
121
|
const refuse = (reason) => done({ ok: false, reason });
|
|
121
122
|
try {
|
|
@@ -123,7 +124,10 @@ export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = no
|
|
|
123
124
|
if (error) return refuse(typeof error.syscall === "string" && error.syscall.startsWith("spawn") ? "it did not start" : error.killed === true ? `it did not answer within ${timeoutMs / 1000} seconds` : "it failed");
|
|
124
125
|
const payload = parseProbeStdout(stdout);
|
|
125
126
|
if (!payload) return refuse("it answered something that is not a version record");
|
|
126
|
-
const verdict = acceptProbe(payload);
|
|
127
|
+
const verdict = acceptProbe(payload, testedVersion);
|
|
128
|
+
// A kernel newer than the TUI's own is not the kernel it shipped with: the TUI holds nothing back
|
|
129
|
+
// (it has no allowlist), so it refuses it, as before the Desktop's soft ceiling (#1879).
|
|
130
|
+
if (verdict.ok && verdict.aboveTested) return refuse(`version ${payload.version} is newer than this TUI's kernel ${testedVersion}`);
|
|
127
131
|
return verdict.ok ? done({ ok: true, cli: cliRecord(payload, { bin, source: "tui" }) }) : refuse(verdict.reason);
|
|
128
132
|
});
|
|
129
133
|
} catch { refuse("it did not start"); }
|
|
@@ -161,6 +165,18 @@ export const CHANGE_FILES = Object.freeze({
|
|
|
161
165
|
},
|
|
162
166
|
});
|
|
163
167
|
|
|
168
|
+
/** The version of the kernel's own package (its package.json, beside bin/, as KERNEL_BIN): the TUI's tested
|
|
169
|
+
* version, which the shared acceptProbe requires (cli-locator.mjs). The kernel the TUI runs is this one, so it is
|
|
170
|
+
* never above it. Read once, by the bounded read a change's output is read with (no other read of node:fs); null
|
|
171
|
+
* when the manifest cannot be read or is over 1 MiB: the probe then refuses, as acceptProbe does without one. */
|
|
172
|
+
export const KERNEL_VERSION = (() => {
|
|
173
|
+
try {
|
|
174
|
+
const { text, over } = CHANGE_FILES.read(fileURLToPath(new URL("../../../package.json", import.meta.url)), 1024 * 1024);
|
|
175
|
+
const version = over ? null : JSON.parse(text).version;
|
|
176
|
+
return typeof version === "string" ? version : null;
|
|
177
|
+
} catch { return null; }
|
|
178
|
+
})();
|
|
179
|
+
|
|
164
180
|
/** A child that did not end well, as execFile reports one: the facts on an Error, and no text of the child's. */
|
|
165
181
|
const failure = (facts) => Object.assign(new Error("the child did not end with an answer"), facts);
|
|
166
182
|
/** A child the reader ended itself: its time limit, or the reader giving it up. As execFile's timeout. */
|
|
@@ -533,7 +533,7 @@ installed CLI's catalog:
|
|
|
533
533
|
node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
|
|
534
534
|
```
|
|
535
535
|
|
|
536
|
-
It prints the two refs, for example `oats-framework/v1.
|
|
536
|
+
It prints the two refs, for example `oats-framework/v1.25.0 v1.41.0`. If the
|
|
537
537
|
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
538
538
|
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
539
539
|
skill: stop, and tell the person to wait for the next OATS
|
|
@@ -548,7 +548,9 @@ its skills, so it puts none on the computer; each agent gets its own;
|
|
|
548
548
|
from 0.5.0 it bundles none, and the setting is harmless, so set it
|
|
549
549
|
whatever the version). Never install `@awebai/claude-skills` in that pi
|
|
550
550
|
folder: its skills would load in every agent there, and each agent gets
|
|
551
|
-
its own skills from OATS. Codex
|
|
551
|
+
its own skills from OATS. Codex has no channel of its own: it is woken by
|
|
552
|
+
the host wake broker, which the person starts in step 9, item 6, before the
|
|
553
|
+
setup expert is spawned. Claude's aweb channel
|
|
552
554
|
plugin still carries one skill of its own, until aweb ships it without
|
|
553
555
|
(a known gap). The pi entry, which matches `npm:@awebai/pi` alone or with
|
|
554
556
|
`@` and a version, never another `@awebai/pi-…` package, and prints it so
|
|
@@ -768,8 +770,8 @@ name: acme
|
|
|
768
770
|
members:
|
|
769
771
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
770
772
|
packages:
|
|
771
|
-
oats.framework: v1.
|
|
772
|
-
oats.aweb: v1.
|
|
773
|
+
oats.framework: v1.25.0 # the installed CLI's catalog versions (below)
|
|
774
|
+
oats.aweb: v1.41.0 # messaging: agent identities, mail and chat
|
|
773
775
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
774
776
|
defaults:
|
|
775
777
|
capabilities:
|
|
@@ -1046,6 +1048,33 @@ readiness still reports a problem.
|
|
|
1046
1048
|
their own agent whether that name is in the group (its agent reads
|
|
1047
1049
|
`oats aweb roster --label L`); the fix (a new invite and a name for this
|
|
1048
1050
|
machine) is the workspace owner's. Never take the other machine's name.
|
|
1051
|
+
6. **Codex, or `delivery: session`: the wake broker runs before the spawn.**
|
|
1052
|
+
Skip this item when the setup expert's harness is Claude or pi and the
|
|
1053
|
+
effective `oats.aweb` settings (the soul's or this host's) don't set
|
|
1054
|
+
`delivery: session`: its own channel wakes it (step 4). Any other setup
|
|
1055
|
+
expert is woken only by the host wake broker, and oats.aweb refuses to
|
|
1056
|
+
spawn or start it while no broker runs (`wake-daemon-not-running`). The
|
|
1057
|
+
broker is the person's own user service, so it is theirs to start. Open
|
|
1058
|
+
their own terminal ("How to work") running this, with `D` filled in:
|
|
1059
|
+
|
|
1060
|
+
```text
|
|
1061
|
+
cd "D" && oats aweb wake install
|
|
1062
|
+
```
|
|
1063
|
+
|
|
1064
|
+
In a container, or on a machine with neither launchd nor systemd (the
|
|
1065
|
+
command answers `E_WAKE_UNSUPPORTED`), there is no service to install:
|
|
1066
|
+
the line is `aw wake run`, kept running as a supervised process.
|
|
1067
|
+
|
|
1068
|
+
Then check it yourself:
|
|
1069
|
+
|
|
1070
|
+
```bash
|
|
1071
|
+
cd "D" && oats aweb wake status --json
|
|
1072
|
+
```
|
|
1073
|
+
|
|
1074
|
+
Go on to step 10 only when it reports `"daemon": { "running": true }`.
|
|
1075
|
+
Otherwise stop, spawn nothing, and tell the person what the status
|
|
1076
|
+
shows.
|
|
1077
|
+
|
|
1049
1078
|
The setup expert does the rest of this machine's messaging
|
|
1050
1079
|
(`/oats-host-delivery`).
|
|
1051
1080
|
|