@awebai/oats 0.69.24 → 0.70.1
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 +62 -6
- package/docs/capabilities.md +374 -18
- package/docs/capability-manifest.schema.json +30 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
- package/docs/design/2026-11-21-human-ids-contract.md +342 -0
- package/docs/design/README.md +2 -0
- package/docs/desktop-cli-api.md +111 -4
- package/docs/execution-targets.md +24 -1
- package/docs/implementation.md +26 -3
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/release-notes/v0.70.1.md +70 -0
- package/docs/schedules.md +42 -3
- package/docs/souls-and-instances.md +12 -0
- package/docs/trust-model.md +8 -1
- package/docs/upgrading.md +16 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +10 -1
- package/lib/core.mjs +408 -66
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +2 -1
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +64 -10
- package/lib/instance-listing.mjs +5 -1
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/remote.mjs +33 -1
- package/lib/retire-admission.mjs +7 -0
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +6 -4
- package/lib/servers.mjs +10 -1
- package/lib/session-inspect.mjs +20 -75
- package/lib/session-providers.mjs +68 -19
- package/lib/session-receipt.mjs +93 -0
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package.json +1 -1
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
/** What the kernel runs of a provider home (docs/capabilities.md "What the kernel trusts in a
|
|
2
|
+
* provider home"; the contract's D16 rule 3).
|
|
3
|
+
*
|
|
4
|
+
* A home on a session provider can be written by its own agent: the provider may run the harness
|
|
5
|
+
* in a sandbox that still writes the home, and the kernel that runs the home's hooks and its
|
|
6
|
+
* provider's commands runs outside any sandbox, as the operator, WHILE that agent runs. So for
|
|
7
|
+
* such a home the kernel runs nothing that is in the home, and takes no capability setting from it:
|
|
8
|
+
*
|
|
9
|
+
* - the kernel keeps its OWN copy of the home's modules, outside the home, beside the home's
|
|
10
|
+
* receipt (`<instances>/.oats-retirement/modules/<hash of the home>/<store>/<capability>/`):
|
|
11
|
+
* made by the spawn from the copies it materialised, before the provider is asked anything
|
|
12
|
+
* and before any hook of the spawn runs.
|
|
13
|
+
* `oats instance upgrade` makes a new one beside it (another `<store>`) and the receipt's one
|
|
14
|
+
* write then names it, with the rows that go with it: an upgrade that fails before that write
|
|
15
|
+
* leaves the old copy and the old rows, together; after it, the new ones. Every hook,
|
|
16
|
+
* every command of the provider, every readiness check and every dispatched command of such a
|
|
17
|
+
* home is run from there, and its manifests are read there. The copies in the home are the
|
|
18
|
+
* agent's own (its skills, what its harness runs inside its sandbox): the kernel never runs
|
|
19
|
+
* them, so nothing the agent does to them, at any moment, changes what the kernel runs;
|
|
20
|
+
* - the home's receipt (lib/session-receipt.mjs) carries its `composition`: which store holds
|
|
21
|
+
* the kernel's copies, which modules the home has and where each came from, and the
|
|
22
|
+
* capability rows the spawn resolved from the
|
|
23
|
+
* deployment (settings, their origins, levels, and the hook commands, which name the kernel's
|
|
24
|
+
* copy). A capability's row is the receipt's, never instance.json's `capabilityRuntime`.
|
|
25
|
+
*
|
|
26
|
+
* Why a copy and not a check: a copy in the home that is hashed and then run can be exchanged
|
|
27
|
+
* between the two by the session that writes the home, for as long as the command takes to
|
|
28
|
+
* start and for as long as it runs.
|
|
29
|
+
*
|
|
30
|
+
* A tmux home is unchanged, and why: its agent already runs unsandboxed as the operator, and can
|
|
31
|
+
* do directly whatever a module it rewrote could. This protects nothing against an agent that
|
|
32
|
+
* can write outside its home: a provider that sandboxes keeps `<instances>/.oats-retirement/`
|
|
33
|
+
* unwritable.
|
|
34
|
+
*
|
|
35
|
+
* A leaf: it reads and copies files, and knows nothing of sessions or of core.mjs. */
|
|
36
|
+
import { cpSync, lstatSync, mkdirSync, readdirSync, rmSync } from "node:fs";
|
|
37
|
+
import { randomBytes } from "node:crypto";
|
|
38
|
+
import { basename, dirname, join, sep } from "node:path";
|
|
39
|
+
import { homeModulesStore, homeReceipt, isPlainObject, readJsonOrUndefined } from "./session-receipt.mjs";
|
|
40
|
+
|
|
41
|
+
/** What a row's `moduleCopy.differs` may name: capability ids (the manifest grammar's), each of
|
|
42
|
+
* at most this length, and at most this many. */
|
|
43
|
+
const MODULE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
|
|
44
|
+
const MODULE_COPY_ID_MAX = 200, MODULE_COPY_IDS_MAX = 200;
|
|
45
|
+
/** The version of a receipt's `composition`. */
|
|
46
|
+
export const COMPOSITION_VERSION = 1;
|
|
47
|
+
const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
48
|
+
/** Where a home keeps ITS copy of capability `id` (the agent's own). */
|
|
49
|
+
const homeModuleDir = (home, id) => join(home, ".oats", "modules", id);
|
|
50
|
+
const STORE_RE = /^[a-f0-9]{12}$/;
|
|
51
|
+
/** Where the kernel keeps its copy of capability `id` of the home `home`, which is what it runs:
|
|
52
|
+
* in the store the home's receipt names (`trust`: providerHomeTrust's answer, read here when it
|
|
53
|
+
* is not given). A path that does not exist when the receipt names no store. */
|
|
54
|
+
export function kernelModuleDir(home, id, trust = providerHomeTrust(home)) {
|
|
55
|
+
return kernelModuleDirIn(home, trust?.composition?.store ?? "-", id);
|
|
56
|
+
}
|
|
57
|
+
/** The same, in the store named `store`: the one a receipt is about to name (an upgrade's new
|
|
58
|
+
* one), or named before (the one an undo goes back to). */
|
|
59
|
+
export const kernelModuleDirIn = (home, store, id) => join(homeModulesStore(home), store, id);
|
|
60
|
+
/** The home a module copy belongs to, when `dir` is `<home>/.oats/modules/<id>`: `{ home, id }`,
|
|
61
|
+
* else null (a deployment's own module store, a soul's tree, the kernel's own copy). */
|
|
62
|
+
export function homeOfModuleCopy(dir) {
|
|
63
|
+
if (typeof dir !== "string" || basename(dirname(dir)) !== "modules" || basename(dirname(dirname(dir))) !== ".oats") return null;
|
|
64
|
+
return { home: dirname(dirname(dirname(dir))), id: basename(dir) };
|
|
65
|
+
}
|
|
66
|
+
/** A shell word as the kernel renders one (lib/core.mjs shq): what a path looks like inside a hook command. */
|
|
67
|
+
const shellEscaped = (text) => text.replace(/'/g, `'\\''`);
|
|
68
|
+
/** A capability row whose hook commands name the home's copies → the row with them naming the
|
|
69
|
+
* kernel's copies: the path of the home's modules directory, where a rendered command holds it
|
|
70
|
+
* (`node '<home>/.oats/modules/<id>/<script>' …`), becomes the store's. */
|
|
71
|
+
function repointed(home, row, store, earlier) {
|
|
72
|
+
if (!isPlainObject(row?.hooks)) return row;
|
|
73
|
+
const to = shellEscaped(`${join(homeModulesStore(home), store)}${sep}`);
|
|
74
|
+
// From the home's copies (a row a spawn or an upgrade has just resolved), and from the store an
|
|
75
|
+
// earlier receipt named (a row of a module an upgrade did not move).
|
|
76
|
+
const from = [`${join(home, ".oats", "modules")}${sep}`, ...(earlier ? [`${join(homeModulesStore(home), earlier)}${sep}`] : [])].map(shellEscaped);
|
|
77
|
+
const hooks = Object.fromEntries(Object.entries(row.hooks).map(([event, command]) => [event, typeof command === "string" ? from.reduce((text, prefix) => text.split(prefix).join(to), command) : command]));
|
|
78
|
+
return { ...row, hooks };
|
|
79
|
+
}
|
|
80
|
+
/** The capability rows a receipt holds, naming the copies in `store`, from the rows a spawn or an
|
|
81
|
+
* upgrade resolved (`earlier`: the store the home's receipt named until now). */
|
|
82
|
+
const storedRows = (home, rows, store, earlier = null) => JSON.parse(JSON.stringify(rows ?? [])).map((row) => repointed(home, row, store, earlier));
|
|
83
|
+
/** A new store for a home's kernel copies: its name, and its directory, made. */
|
|
84
|
+
function newStore(home) {
|
|
85
|
+
const store = randomBytes(6).toString("hex"), dir = join(homeModulesStore(home), store);
|
|
86
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
87
|
+
return { store, dir };
|
|
88
|
+
}
|
|
89
|
+
/** Copy a module's tree into a store: links as links, never followed, and nothing overwritten.
|
|
90
|
+
* A `.git` at the module's root is left out: the digest a module is verified by passes over it
|
|
91
|
+
* (lib/remote.mjs contentDigest), so what the kernel keeps is exactly what was verified. */
|
|
92
|
+
function copyModule(from, to) {
|
|
93
|
+
cpSync(from, to, { recursive: true, verbatimSymlinks: true, errorOnExist: true, force: false, filter: (source) => source !== join(from, ".git") });
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Take away the kernel's copies of a home's modules, every store of them: a retire's and a
|
|
97
|
+
* spawn's rollback's last act on them, and a spawn's first (whatever an earlier home of that
|
|
98
|
+
* path left). */
|
|
99
|
+
export function removeModulesStore(home) {
|
|
100
|
+
rmSync(homeModulesStore(home), { recursive: true, force: true });
|
|
101
|
+
}
|
|
102
|
+
/** Take away every store of a home's kernel copies but the ones its receipt names: the one the
|
|
103
|
+
* kernel runs from, and the one before it (`composition.previous`), which an undo goes back to.
|
|
104
|
+
* Called only once a move is COMPLETE (its receipt written, and nothing left that could put the
|
|
105
|
+
* earlier receipt back): what it removes is what no receipt names any more and none will again
|
|
106
|
+
* (the store before the previous one, after a move; the newer one, after an undo), and what an
|
|
107
|
+
* earlier move that was interrupted had made and never named. */
|
|
108
|
+
export function pruneModulesStores(home) {
|
|
109
|
+
const composition = providerHomeTrust(home)?.composition;
|
|
110
|
+
if (!composition) return;
|
|
111
|
+
const keep = new Set([composition.store, ...(composition.previous ? [composition.previous.store] : [])]);
|
|
112
|
+
let names;
|
|
113
|
+
try { names = readdirSync(homeModulesStore(home)); } catch { return; }
|
|
114
|
+
for (const name of names) if (!keep.has(name)) rmSync(join(homeModulesStore(home), name), { recursive: true, force: true });
|
|
115
|
+
}
|
|
116
|
+
/** The composition an upgrade leaves a provider home, with the kernel's copies for it in a NEW
|
|
117
|
+
* store, beside the one the receipt names now: each module in `moved` copied from
|
|
118
|
+
* `source(id)` (the copy the upgrade has just found to be the one it verified against the lock:
|
|
119
|
+
* by default the home's own), every other module copied from the kernel's own current copy;
|
|
120
|
+
* `modules` (`{ <id>: { from?, commit? } }`) and `rows` are what the upgrade derived. Its
|
|
121
|
+
* `previous` is the composition the receipt names now (its store, modules and rows), which an
|
|
122
|
+
* undo goes back to. Nothing the receipt names is touched: the caller's ONE write of the
|
|
123
|
+
* receipt is what makes the new store and the new rows the home's, together. Throws, with the
|
|
124
|
+
* new store removed, when a copy cannot be made. */
|
|
125
|
+
export function upgradedComposition(home, trust, { moved, modules, rows, source = (id) => homeModuleDir(home, id) }) {
|
|
126
|
+
const { store, dir } = newStore(home);
|
|
127
|
+
try {
|
|
128
|
+
for (const id of Object.keys(modules).sort(byCodeUnit)) copyModule(moved.has(id) ? source(id) : kernelModuleDir(home, id, trust), join(dir, id));
|
|
129
|
+
} catch (e) { rmSync(dir, { recursive: true, force: true }); throw e; }
|
|
130
|
+
const { store: earlier, modules: earlierModules, capabilityRuntime: earlierRows } = trust.composition;
|
|
131
|
+
return { version: COMPOSITION_VERSION, store, modules, capabilityRuntime: storedRows(home, rows, store, earlier).filter((row) => Object.hasOwn(modules, row?.id)),
|
|
132
|
+
previous: { store: earlier, modules: earlierModules, capabilityRuntime: earlierRows } };
|
|
133
|
+
}
|
|
134
|
+
/** Take away the store `store` of a home's kernel copies, unless the home's receipt names it (as
|
|
135
|
+
* the one it runs from, or the previous one): what a move that failed had made, and nothing else. */
|
|
136
|
+
export function removeUnnamedStore(home, store) {
|
|
137
|
+
const composition = providerHomeTrust(home)?.composition;
|
|
138
|
+
if (!store || composition?.store === store || composition?.previous?.store === store) return;
|
|
139
|
+
rmSync(join(homeModulesStore(home), store), { recursive: true, force: true });
|
|
140
|
+
}
|
|
141
|
+
/** The composition an undo goes back to: the one the receipt keeps as `previous` (its store, which
|
|
142
|
+
* is still there, with its modules and rows), with no `previous` of its own; null when the
|
|
143
|
+
* receipt keeps none. Nothing is copied: the one write of the receipt names that store again. */
|
|
144
|
+
export function previousComposition(trust) {
|
|
145
|
+
const previous = trust?.composition?.previous;
|
|
146
|
+
return previous ? { version: COMPOSITION_VERSION, store: previous.store, modules: previous.modules, capabilityRuntime: previous.capabilityRuntime } : null;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/** A provider home's composition, as its spawn records it in the receipt, with the kernel's own
|
|
150
|
+
* copy of every module put in place: `{ version, store, modules: { <id>: { from?, commit? } },
|
|
151
|
+
* capabilityRuntime: [<row>] }` (an upgrade adds `previous: { store, modules, capabilityRuntime }`,
|
|
152
|
+
* the one it replaced). The modules are the directories under `<home>/.oats/modules/`
|
|
153
|
+
* as they are now, and `from` and `commit` (where each came from: what an upgrade moves it
|
|
154
|
+
* from) are the home's record's as it is now. A spawn calls this ONCE, at its first write of
|
|
155
|
+
* the receipt, which in every work mode is before its provider is asked to launch, so before
|
|
156
|
+
* the home's agent exists; every later write of that spawn keeps what this recorded (lib/core.mjs
|
|
157
|
+
* writeRetirementBaseline). `rows` are the capability rows the spawn resolved. Throws when a
|
|
158
|
+
* copy cannot be made: a spawn that cannot keep what it made records nothing. */
|
|
159
|
+
export function compositionOf(home, rows) {
|
|
160
|
+
const root = join(home, ".oats", "modules");
|
|
161
|
+
const recorded = readJsonOrUndefined(join(home, "instance.json"))?.modules;
|
|
162
|
+
const modules = {};
|
|
163
|
+
let names;
|
|
164
|
+
try { names = readdirSync(root).sort(byCodeUnit); } catch (e) { if (e?.code !== "ENOENT") throw e; names = []; }
|
|
165
|
+
removeModulesStore(home);
|
|
166
|
+
const { store, dir } = newStore(home);
|
|
167
|
+
for (const id of names) {
|
|
168
|
+
if (!lstatSync(join(root, id)).isDirectory()) continue;
|
|
169
|
+
copyModule(join(root, id), join(dir, id));
|
|
170
|
+
const source = isPlainObject(recorded) && Object.hasOwn(recorded, id) && isPlainObject(recorded[id]) ? recorded[id] : null;
|
|
171
|
+
modules[id] = { ...(isPlainObject(source?.from) ? { from: JSON.parse(JSON.stringify(source.from)) } : {}), ...(typeof source?.commit === "string" ? { commit: source.commit } : {}) };
|
|
172
|
+
}
|
|
173
|
+
return { version: COMPOSITION_VERSION, store, modules, capabilityRuntime: storedRows(home, rows, store) };
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
const validPair = (c) => isPlainObject(c) && typeof c.store === "string" && STORE_RE.test(c.store) && isPlainObject(c.modules) && Array.isArray(c.capabilityRuntime)
|
|
177
|
+
&& Object.values(c.modules).every((m) => isPlainObject(m))
|
|
178
|
+
&& c.capabilityRuntime.every((row) => isPlainObject(row) && typeof row.id === "string");
|
|
179
|
+
function validComposition(c) {
|
|
180
|
+
return isPlainObject(c) && c.version === COMPOSITION_VERSION && validPair(c) && (c.previous === undefined || (validPair(c.previous) && c.previous.store !== c.store));
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** What a home's receipt says the kernel runs of it:
|
|
184
|
+
* - null: the receipt names no session provider (a tmux home), or there is none for this home:
|
|
185
|
+
* the home is read and run as it always was;
|
|
186
|
+
* - `{ composition }`: a provider home, with what its spawn recorded;
|
|
187
|
+
* - `{ problem }` (one sentence): a provider home whose receipt holds no composition this kernel
|
|
188
|
+
* reads. A kernel from before this rule spawned it; nothing of it is run.
|
|
189
|
+
* The receipt is read each time: it is the record, and an upgrade may have rewritten it. */
|
|
190
|
+
export function providerHomeTrust(home) {
|
|
191
|
+
const baseline = homeReceipt(home);
|
|
192
|
+
return baseline ? receiptTrust(baseline, home) : null;
|
|
193
|
+
}
|
|
194
|
+
/** providerHomeTrust, of a receipt its caller has read and found to be this home's. */
|
|
195
|
+
export function receiptTrust(baseline, home) {
|
|
196
|
+
if (!isPlainObject(baseline?.runtime) || typeof baseline.runtime.provider !== "string") return null;
|
|
197
|
+
if (validComposition(baseline.composition)) return { composition: baseline.composition };
|
|
198
|
+
return { problem: `${basename(home)} is on a session provider and its receipt records nothing of what it was spawned with (a kernel from before the receipt recorded it spawned the home, or the receipt was rewritten): none of its capabilities is run. Retire it with --force (oats retire ${basename(home)} --force: its retire hooks cannot be identified, so none is run, and what its capabilities left outside is cleaned up with their own tooling), then spawn it again` };
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** Why the kernel runs nothing of capability `id` in a provider home → one sentence that names
|
|
202
|
+
* the module, or null when it may: the receipt records the module and the kernel holds its copy
|
|
203
|
+
* of it. Null for a home that is no provider home (`trust` null: providerHomeTrust's answer,
|
|
204
|
+
* read here when it is not given). */
|
|
205
|
+
export function moduleCopyProblem(home, id, trust = providerHomeTrust(home)) {
|
|
206
|
+
if (!trust) return null;
|
|
207
|
+
if (trust.problem) return trust.problem;
|
|
208
|
+
if (!Object.hasOwn(trust.composition.modules, id)) return `capability ${id} is not one ${basename(home)} was spawned with (its receipt records no such module): nothing of it is run`;
|
|
209
|
+
const dir = kernelModuleDir(home, id, trust);
|
|
210
|
+
let kept = false;
|
|
211
|
+
try { kept = lstatSync(dir).isDirectory(); } catch { /* not there */ }
|
|
212
|
+
return kept ? null : `the kernel's copy of capability ${id} for ${basename(home)} is not at ${dir}: nothing of the capability is run. Retire the instance (oats retire ${basename(home)}; where the capability has a retire hook, which then cannot be run, the retire says so and only --force removes the home), then spawn it again`;
|
|
213
|
+
}
|
|
214
|
+
/** Why the kernel launches nothing in a provider home → the first module's problem
|
|
215
|
+
* (moduleCopyProblem), or null. */
|
|
216
|
+
export function homeModulesProblem(home, trust = providerHomeTrust(home)) {
|
|
217
|
+
if (!trust) return null;
|
|
218
|
+
if (trust.problem) return trust.problem;
|
|
219
|
+
for (const id of Object.keys(trust.composition.modules).sort(byCodeUnit)) {
|
|
220
|
+
const problem = moduleCopyProblem(home, id, trust);
|
|
221
|
+
if (problem) return problem;
|
|
222
|
+
}
|
|
223
|
+
return null;
|
|
224
|
+
}
|
|
225
|
+
/** The directory the kernel runs capability `id` of `home` from: its own copy for a provider
|
|
226
|
+
* home, the home's for any other. */
|
|
227
|
+
export function runDirOf(home, id, trust = providerHomeTrust(home)) {
|
|
228
|
+
return trust ? kernelModuleDir(home, id, trust) : homeModuleDir(home, id);
|
|
229
|
+
}
|
|
230
|
+
/** For a caller that holds a directory it is about to run a file of: why it may not → a
|
|
231
|
+
* sentence, when `dir` is a provider home's OWN copy (`<home>/.oats/modules/<id>`), which the
|
|
232
|
+
* kernel never runs; null for any other directory (the kernel's copy, a tmux home's copy, a
|
|
233
|
+
* deployment's module store). A guard: every caller is given the kernel's copy to begin with. */
|
|
234
|
+
export function moduleCopyProblemAt(dir) {
|
|
235
|
+
const at = homeOfModuleCopy(dir);
|
|
236
|
+
if (!at || !providerHomeTrust(at.home)) return null;
|
|
237
|
+
return `${dir} is ${basename(at.home)}'s own copy of capability ${at.id}, and ${basename(at.home)} is on a session provider: the kernel runs its own copy of it (${kernelModuleDir(at.home, at.id)}), never the home's`;
|
|
238
|
+
}
|
|
239
|
+
/** What a provider home's row says of its modules' copies → `{ runs: "kernel-copy", homeCopy:
|
|
240
|
+
* "same" | "differs", differs: [<module id>] }`, or undefined for a home that is no provider home
|
|
241
|
+
* or whose receipt holds no composition. `runs`: which copy the kernel runs. `homeCopy` compares
|
|
242
|
+
* RECORDS only, with nothing hashed and no file of a copy read: the home's own record of each
|
|
243
|
+
* module (instance.json `modules.<id>`: its `from` and `commit`) against the receipt's. They
|
|
244
|
+
* differ after an upgrade that was interrupted between moving the home's copies and writing the
|
|
245
|
+
* receipt, and whenever the home's record was rewritten; `differs` names the modules, those
|
|
246
|
+
* only one of the two names included (capability ids only, at most 200: a name the home's
|
|
247
|
+
* record gives that is none is counted in `homeCopy` and not named). Whether a home copy's FILES are the kernel's is
|
|
248
|
+
* `oats readiness --home`'s `kernelCopies`. */
|
|
249
|
+
export function moduleCopyReport(meta, trust) {
|
|
250
|
+
if (!trust?.composition) return undefined;
|
|
251
|
+
const recorded = trust.composition.modules, own = isPlainObject(meta?.modules) ? meta.modules : {};
|
|
252
|
+
const same = (id) => Object.hasOwn(recorded, id) && Object.hasOwn(own, id) && isPlainObject(own[id])
|
|
253
|
+
&& JSON.stringify(sorted(own[id].from ?? null)) === JSON.stringify(sorted(recorded[id].from ?? null)) && (own[id].commit ?? null) === (recorded[id].commit ?? null);
|
|
254
|
+
const differing = [...new Set([...Object.keys(recorded), ...Object.keys(own)])].filter((id) => !same(id));
|
|
255
|
+
// The names are the home's own to choose (the keys of its record): only capability ids are
|
|
256
|
+
// named, and no more than a row may carry; `homeCopy` says "differs" whatever is named.
|
|
257
|
+
const differs = differing.filter((id) => MODULE_ID_RE.test(id) && id.length <= MODULE_COPY_ID_MAX).sort(byCodeUnit).slice(0, MODULE_COPY_IDS_MAX);
|
|
258
|
+
return { runs: "kernel-copy", homeCopy: differing.length ? "differs" : "same", differs };
|
|
259
|
+
}
|
|
260
|
+
/** A row's `moduleCopy` as another kernel reported it (a remote roster's row), read by this
|
|
261
|
+
* kernel's own rule → the value, or undefined when it is not one: exactly the three keys,
|
|
262
|
+
* `runs: "kernel-copy"`, `homeCopy` one of the two words, `differs` a list of at most 200
|
|
263
|
+
* capability ids, empty when `homeCopy` is `same`. */
|
|
264
|
+
export function readModuleCopy(value) {
|
|
265
|
+
if (!isPlainObject(value) || Object.keys(value).sort().join() !== "differs,homeCopy,runs" || value.runs !== "kernel-copy") return undefined;
|
|
266
|
+
if (!Array.isArray(value.differs) || value.differs.length > MODULE_COPY_IDS_MAX || !value.differs.every((id) => typeof id === "string" && id.length <= MODULE_COPY_ID_MAX && MODULE_ID_RE.test(id))) return undefined;
|
|
267
|
+
if (value.homeCopy !== "same" && value.homeCopy !== "differs") return undefined;
|
|
268
|
+
if (value.homeCopy === "same" && value.differs.length) return undefined;
|
|
269
|
+
return { runs: "kernel-copy", homeCopy: value.homeCopy, differs: [...value.differs] };
|
|
270
|
+
}
|
|
271
|
+
/** A JSON value with every object's keys in one order, for a comparison by text. */
|
|
272
|
+
function sorted(value) {
|
|
273
|
+
if (Array.isArray(value)) return value.map(sorted);
|
|
274
|
+
if (!isPlainObject(value)) return value;
|
|
275
|
+
return Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, sorted(value[key])]));
|
|
276
|
+
}
|
|
277
|
+
/** Whether a provider home's receipt records a module `id`: true for a home that is no provider
|
|
278
|
+
* home (every module of its record counts, as before). */
|
|
279
|
+
export function recordsModule(trust, id) {
|
|
280
|
+
return !trust || (!!trust.composition && Object.hasOwn(trust.composition.modules, id));
|
|
281
|
+
}
|
|
282
|
+
/** The fields of a capability row that the receipt decides, for a hook or a command of a provider
|
|
283
|
+
* home: whatever a caller's row says of them is replaced (trustedCapability). */
|
|
284
|
+
const ROW_FIELDS = ["layer", "level", "settings", "settingsOrigins", "hooks", "requiredHooks", "environment", "environmentNamespaces", "missingRequires", "trust", "executable"];
|
|
285
|
+
/** A capability row as the kernel may use it in a provider home → `{ cap }`: the caller's row
|
|
286
|
+
* with every field the receipt decides replaced by the receipt's (an absent one made absent), or
|
|
287
|
+
* `{ cap, problem }` when the receipt records no such capability: nothing of it is run. For a
|
|
288
|
+
* home that is no provider home, `{ cap }` as given. */
|
|
289
|
+
export function trustedCapability(home, cap, trust) {
|
|
290
|
+
if (!trust) return { cap };
|
|
291
|
+
const row = trustedRow(trust, cap.id);
|
|
292
|
+
if (!row) return { cap, problem: trust.problem ?? `capability ${cap.id} is not one ${basename(home)} was spawned with (its receipt records no row for it): nothing of it is run` };
|
|
293
|
+
return { cap: { ...cap, ...Object.fromEntries(ROW_FIELDS.map((k) => [k, row[k]])) } };
|
|
294
|
+
}
|
|
295
|
+
/** A home's record as the kernel may use it: for a provider home its `capabilityRuntime` is the
|
|
296
|
+
* receipt's, and so is `providers` (each capability's settings, which is where an upgrade reads
|
|
297
|
+
* them), whatever instance.json says; both absent when the receipt holds no composition (the
|
|
298
|
+
* home then records no hooks this kernel can identify). Any other home's record as given. */
|
|
299
|
+
export function trustedRecord(meta, trust) {
|
|
300
|
+
if (!trust || !isPlainObject(meta)) return meta;
|
|
301
|
+
const { capabilityRuntime: _rows, providers: _settings, ...rest } = meta;
|
|
302
|
+
if (!trust.composition) return rest;
|
|
303
|
+
const rows = trust.composition.capabilityRuntime;
|
|
304
|
+
return { ...rest, capabilityRuntime: rows, providers: Object.fromEntries(rows.map((row) => [row.id, isPlainObject(row.settings) ? row.settings : {}])) };
|
|
305
|
+
}
|
|
306
|
+
/** A provider home's record with what an upgrade reads of each module: the module set is the
|
|
307
|
+
* receipt's (a module the record adds or leaves out is refused: `{ problem }`), and each
|
|
308
|
+
* module's `from` and `commit` are the receipt's where it records them. `{ meta }` otherwise;
|
|
309
|
+
* `{ meta }` as given for a home that is no provider home. */
|
|
310
|
+
export function trustedModuleRecords(home, meta, trust) {
|
|
311
|
+
if (!trust?.composition || !isPlainObject(meta?.modules)) return { meta };
|
|
312
|
+
const recorded = trust.composition.modules;
|
|
313
|
+
const added = Object.keys(meta.modules).filter((id) => !Object.hasOwn(recorded, id)).sort(byCodeUnit);
|
|
314
|
+
const dropped = Object.keys(recorded).filter((id) => !Object.hasOwn(meta.modules, id)).sort(byCodeUnit);
|
|
315
|
+
if (added.length || dropped.length) return { problem: `the modules ${basename(home)}'s own record names are not the ones its receipt records (${[added.length ? `the record adds ${added.join(", ")}` : "", dropped.length ? `the record leaves out ${dropped.join(", ")}` : ""].filter(Boolean).join("; ")}). Retire the instance and spawn it again` };
|
|
316
|
+
const modules = Object.fromEntries(Object.entries(meta.modules).map(([id, row]) => [id, { ...row, ...(recorded[id].from ? { from: recorded[id].from } : {}), ...(recorded[id].commit ? { commit: recorded[id].commit } : {}) }]));
|
|
317
|
+
return { meta: { ...meta, modules } };
|
|
318
|
+
}
|
|
319
|
+
/** The capability row the kernel uses for `id` in a provider home: the receipt's, or undefined
|
|
320
|
+
* when it records none. */
|
|
321
|
+
export function trustedRow(trust, id) {
|
|
322
|
+
return trust?.composition?.capabilityRuntime.find((row) => row.id === id);
|
|
323
|
+
}
|
|
324
|
+
/** A home's capability rows as the kernel may use them: the receipt's for a provider home (none
|
|
325
|
+
* when its receipt holds no composition), else the rows of the home's own record. */
|
|
326
|
+
export function capabilityRuntimeOf(home, meta, trust = providerHomeTrust(home)) {
|
|
327
|
+
if (!trust) return Array.isArray(meta?.capabilityRuntime) ? meta.capabilityRuntime : [];
|
|
328
|
+
return trust.composition ? trust.composition.capabilityRuntime : [];
|
|
329
|
+
}
|
package/lib/hook-env.mjs
CHANGED
|
@@ -64,7 +64,8 @@ export function teamEnv(resolved) {
|
|
|
64
64
|
};
|
|
65
65
|
}
|
|
66
66
|
export function withoutAmbientHookFacts(env) {
|
|
67
|
-
|
|
67
|
+
// (OATS_PREVIOUS_BACKEND: a launch hook's, from the home's receipt; absent means a first launch.)
|
|
68
|
+
const { OATS_LAUNCH_PREVIEW: _ambient, OATS_HARNESS_EXECUTABLE: _inherited, OATS_SPAWNER_HOME: _spawner, OATS_PREVIOUS_BACKEND: _previous, ...rest } = env;
|
|
68
69
|
return rest;
|
|
69
70
|
}
|
|
70
71
|
/** The environment one capability's lifecycle hook runs with: the invoker's own
|
package/lib/instance-events.mjs
CHANGED
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
* home the way the caller did: `admit` has proved every returned row is this
|
|
43
43
|
* one home's, so its `home` is the address that was asked about, and a consumer
|
|
44
44
|
* that checks "the rows' home is the home I asked for" keeps holding. */
|
|
45
|
-
import {
|
|
45
|
+
import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, writeSync } from "node:fs";
|
|
46
46
|
import { createHash } from "node:crypto";
|
|
47
47
|
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
48
48
|
import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
|
|
@@ -184,6 +184,35 @@ function workspaceLogPath(given, home, meta) {
|
|
|
184
184
|
return join(realOrNearest(deployment), ".agents", "events", `${agent}--${instance}.jsonl`);
|
|
185
185
|
}
|
|
186
186
|
|
|
187
|
+
/** THE ONE WRITE OF AN EVENT ROW: `eventLog.appendRow(path, line)` appends one line to the log
|
|
188
|
+
* at `path`, to that file and to no other. Every event-log write of the kernel goes through it,
|
|
189
|
+
* and it is a seam: a test replaces `eventLog.appendRow` to hold, fail or follow one row's write,
|
|
190
|
+
* with the log's path and the row's text together (test/helpers/fs-gate-preload.mjs `appendEventRow`).
|
|
191
|
+
*
|
|
192
|
+
* The open never follows a symbolic link at the log's own name (O_NOFOLLOW, so a dangling one
|
|
193
|
+
* creates nothing either) and never waits on a FIFO, and what it opened must be a regular file
|
|
194
|
+
* with one name, checked on the descriptor the line is then written to: there is no instant
|
|
195
|
+
* between the check and the write in which the file can be exchanged. Both logs are in places an
|
|
196
|
+
* agent can write (its home; the deployment's events directory, which a session provider's
|
|
197
|
+
* sandbox is allowed to write, lib/sandbox-allowances.mjs), and the kernel that appends runs
|
|
198
|
+
* outside any sandbox: a link planted there, symbolic or hard, would otherwise carry its line
|
|
199
|
+
* into any file of the operator's, and a row holds text its agent chose. The reader refuses the
|
|
200
|
+
* same files (readLog). Throws with why; the directory is made when it is missing. */
|
|
201
|
+
export const eventLog = {
|
|
202
|
+
appendRow(path, line) {
|
|
203
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
204
|
+
let fd;
|
|
205
|
+
try { fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0), 0o666); }
|
|
206
|
+
catch (e) { throw e?.code === "ELOOP" ? new Error("the log is a symbolic link, which is never written through") : e; }
|
|
207
|
+
try {
|
|
208
|
+
const stat = fstatSync(fd);
|
|
209
|
+
if (!stat.isFile()) throw new Error("the log is not a regular file");
|
|
210
|
+
if (stat.nlink > 1) throw new Error("the log has a second name (a hard link), so a line would be written into another file too");
|
|
211
|
+
writeSync(fd, line);
|
|
212
|
+
} finally { closeSync(fd); }
|
|
213
|
+
},
|
|
214
|
+
};
|
|
215
|
+
|
|
187
216
|
/** The one address of the home a caller named, in any spelling: the real home, its
|
|
188
217
|
* instance name and incarnation, its two logs, and `asked`, the caller's spelling. `known`: the
|
|
189
218
|
* home's record as the caller already read it (a JSON object), else it is read here. */
|
|
@@ -233,8 +262,7 @@ function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
|
|
|
233
262
|
for (const path of [...(workspaceOnly ? [] : [a.homeLog]), a.workspaceLog]) {
|
|
234
263
|
try {
|
|
235
264
|
if (path === a.homeLog && !existsSync(a.home)) { results.push({ path, ok: false, reason: "home absent" }); continue; }
|
|
236
|
-
|
|
237
|
-
appendFileSync(path, line);
|
|
265
|
+
eventLog.appendRow(path, line);
|
|
238
266
|
results.push({ path, ok: true });
|
|
239
267
|
} catch (e) { results.push({ path, ok: false, reason: e.message }); }
|
|
240
268
|
}
|
|
@@ -509,8 +537,7 @@ export function recordStartBoundary(given, { startId, startedAt, ...data }) {
|
|
|
509
537
|
const results = paths.filter((_, i) => !found[i]).map((path) => {
|
|
510
538
|
try {
|
|
511
539
|
if (path === a.homeLog && !existsSync(home)) return { path, ok: false, reason: "home absent" };
|
|
512
|
-
|
|
513
|
-
appendFileSync(path, line);
|
|
540
|
+
eventLog.appendRow(path, line);
|
|
514
541
|
return { path, ok: true };
|
|
515
542
|
} catch (e) { return { path, ok: false, reason: e.message }; }
|
|
516
543
|
});
|
package/lib/instance-git.mjs
CHANGED
|
@@ -59,6 +59,15 @@ export const INSTANCE_GIT_API = 1;
|
|
|
59
59
|
/** The setting that keeps Git from running the `core.fsmonitor` command a repository's
|
|
60
60
|
* configuration names, which it asks whenever it reads the index of a work tree. */
|
|
61
61
|
export const NO_FILE_MONITOR = ["-c", "core.fsmonitor=false"];
|
|
62
|
+
/** For every Git the kernel runs over the trees of a home on a session provider, or over their
|
|
63
|
+
* repository: neither the `core.fsmonitor` command nor any hook the repository's configuration
|
|
64
|
+
* or its `hooks` directory names is run. Such a home's agent may be able to write a tree's `.git`
|
|
65
|
+
* pointer, and its repository's configuration and hooks; Git would run what they name outside
|
|
66
|
+
* any sandbox, as the operator (the contract's D16 rule 6). A read by this module, and a retire's
|
|
67
|
+
* Git, already run so for every home (READ_ONLY_GIT, lib/core.mjs RETIRE_GIT_FLAGS); these are
|
|
68
|
+
* for the writes: a spawn's `git worktree add` and its rollback, and `oats worktree add|remove`.
|
|
69
|
+
* A tmux home's are unchanged: its hooks (a `post-checkout`) run as before. */
|
|
70
|
+
export const PROVIDER_TREE_GIT = [...NO_FILE_MONITOR, "-c", "core.hooksPath=/dev/null"];
|
|
62
71
|
const READ_ONLY_GIT = ["--no-optional-locks",
|
|
63
72
|
...NO_FILE_MONITOR, "-c", "core.hooksPath=/dev/null", "-c", "diff.external=", "-c", "core.pager=cat",
|
|
64
73
|
"-c", "core.untrackedCache=false", "-c", "index.threads=1", "-c", "safe.bareRepository=explicit"];
|
package/lib/instance-inspect.mjs
CHANGED
|
@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
|
|
|
14
14
|
import { accessSync, constants as fsConstants, existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
|
|
15
15
|
import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
16
16
|
import { capabilityManifests, skillEntriesIn, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, previewLaunchEnvironment, removedLaunchEnv, homeDeclaredLaunchEnv, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
|
|
17
|
-
import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
|
|
17
|
+
import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, homeSandboxSource, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
|
|
18
18
|
import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
|
|
19
19
|
import { kernelCompatibility, unsafeRelPath } from "./resolve.mjs";
|
|
20
20
|
import { compareCodepoints, decodeText, FILES_PER_SKILL, SKILL_DOC_BUDGET, skillDocDescription, TEXT_LIMIT } from "./capability-show.mjs";
|
|
@@ -34,7 +34,10 @@ import { readInstancePin } from "./instance-pin.mjs";
|
|
|
34
34
|
/** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
|
|
35
35
|
const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
|
|
36
36
|
import { parseStrictJson } from "./canonical-json.mjs";
|
|
37
|
-
import { checkProviderSession, homeSessionProvider, offeredSessionProviders, sessionProvidersOf } from "./session-providers.mjs";
|
|
37
|
+
import { checkProviderSession, homeSessionProvider, offeredSessionProviders, recordsSessionProvider, sessionProvidersOf } from "./session-providers.mjs";
|
|
38
|
+
import { capabilityRuntimeOf, kernelModuleDir, moduleCopyProblemAt, providerHomeTrust, runDirOf } from "./home-integrity.mjs";
|
|
39
|
+
import { treeDisagreement } from "./tree-copy.mjs";
|
|
40
|
+
import { homeSandboxAllowances, sandboxWritePathsRefusal } from "./sandbox-allowances.mjs";
|
|
38
41
|
import { sameRepo } from "./repo-moves.mjs";
|
|
39
42
|
import { kernelNode } from "./stable-node.mjs";
|
|
40
43
|
|
|
@@ -93,11 +96,17 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
|
|
|
93
96
|
meta = upgradeHomeMeta(meta, realHome);
|
|
94
97
|
// Only the home's own module copies: without <home>/.oats/modules the kernel's
|
|
95
98
|
// manifest lookup would fall through to a classic config chain — never here.
|
|
99
|
+
// A provider home's modules are the ones its receipt records, read from the kernel's copies of
|
|
100
|
+
// them (lib/home-integrity.mjs): a home whose own modules directory or record of them is gone
|
|
101
|
+
// is read the same.
|
|
102
|
+
const trust = providerHomeTrust(realHome), trustedRows = trust ? capabilityRuntimeOf(realHome, meta, trust) : [];
|
|
96
103
|
let manifests = {}; const loadProblems = [];
|
|
97
|
-
|
|
104
|
+
// (A provider home whose receipt holds no composition lists no module: it says why, and what to do.)
|
|
105
|
+
if (trust?.problem) loadProblems.push({ code: "module-copy-untrusted", message: trust.problem });
|
|
106
|
+
if (trust || existsSync(join(realHome, ".oats", "modules"))) {
|
|
98
107
|
try { manifests = capabilityManifests(realHome); } catch (e) { loadProblems.push({ code: "module-manifest-invalid", message: e.message }); }
|
|
99
108
|
}
|
|
100
|
-
const modules = obj(meta.modules) ? meta.modules : {};
|
|
109
|
+
const modules = trust ? Object.fromEntries(Object.entries(trust.composition?.modules ?? {}).map(([id, m]) => [id, { from: m.from ?? null }])) : obj(meta.modules) ? meta.modules : {};
|
|
101
110
|
const agentsRoot = dirname(dirname(dirname(realHome)));
|
|
102
111
|
const deployment = dirname(agentsRoot);
|
|
103
112
|
// The deployment's removed team keys (team model 3) refuse every reader of its oats-local.yaml, before
|
|
@@ -149,9 +158,11 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
|
|
|
149
158
|
soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems],
|
|
150
159
|
...(obj(ws.soul?.package) && typeof ws.soul.package.id === "string" ? { package: { id: ws.soul.package.id, soul: ws.soul.name ?? meta.agent, version: ws.soul.package.version ?? null, commit: ws.soul.package.commit ?? ws.soul.commit ?? null, integrity: ws.soul.package.digest ?? null } } : {}) },
|
|
151
160
|
workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
161
|
+
// (A provider home's modules are run from the kernel's copies of them: lib/home-integrity.mjs.)
|
|
162
|
+
modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: runDirOf(realHome, name, trust) })),
|
|
163
|
+
// (A provider home's settings are its receipt's rows', never its own record's: lib/home-integrity.mjs.)
|
|
164
|
+
payloads: trust ? Object.fromEntries(trustedRows.map((c) => [c.id, obj(c.settings) ? c.settings : {}])) : obj(meta.providers) ? meta.providers : {},
|
|
165
|
+
payloadOrigins: Object.fromEntries((trust ? trustedRows : Array.isArray(meta.capabilities) ? meta.capabilities : []).filter((c) => c && typeof c.id === "string").map((c) => [c.id, obj(c.settingsOrigins) ? c.settingsOrigins : {}])),
|
|
155
166
|
slots, slotsFrom: Object.fromEntries(LAYERS.map((l) => [l, obj(ws.layers?.[l]) ? ws.layers[l].from ?? null : null])), discovery, discoveryError, resolutionError: null,
|
|
156
167
|
lock: null, prepared: null,
|
|
157
168
|
};
|
|
@@ -709,12 +720,16 @@ function moduleExecutable(dir, script) {
|
|
|
709
720
|
* directory, the script contained in it (moduleExecutable), one JSON `request` on stdin, the
|
|
710
721
|
* environment providerEnv's for the request's `settings`, SIGKILL at `timeoutMs`, at most
|
|
711
722
|
* BINDING_LIMITS of stdout, decoded as exactly one strict JSON document (whitespace around it
|
|
712
|
-
* allowed).
|
|
723
|
+
* allowed). A provider home's OWN copy is never run (the kernel runs its copy of it,
|
|
724
|
+
* lib/home-integrity.mjs, which a caller is handed as `dir`): "no-executable", with `problem`.
|
|
725
|
+
* → { doc } or { failure: "no-command" | "no-executable" (script) | "incomplete"
|
|
713
726
|
* (timedOut, signal, overflow) | "exit" (status) | "invalid" }. The caller judges the document. */
|
|
714
727
|
export function runModuleCommand(t, mod, dir, command, request, { timeoutMs = 30000 } = {}) {
|
|
715
728
|
const spec = command ? mod.manifest?.commands?.[command] : null;
|
|
716
729
|
if (typeof spec !== "string" || !spec.trim()) return { failure: "no-command" };
|
|
717
730
|
const [script, ...args] = spec.trim().split(/\s+/);
|
|
731
|
+
const untrusted = dir ? moduleCopyProblemAt(dir) : null;
|
|
732
|
+
if (untrusted) return { failure: "no-executable", script, problem: untrusted };
|
|
718
733
|
const file = dir ? moduleExecutable(dir, script) : null;
|
|
719
734
|
if (!file) return { failure: "no-executable", script };
|
|
720
735
|
// The environment is providerEnv's: ambient OATS_/OAS_/PI_ identity removed, the rest
|
|
@@ -748,7 +763,7 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
|
|
|
748
763
|
input: { context: { kind: "workspace", workspace: t.workspace.key, deployment: t.deployment, soul: t.soul.name, instance: t.meta?.instance ?? null, home: t.home }, action: { kind: "readiness" } } };
|
|
749
764
|
const run = runModuleCommand(t, mod, dir, check, request, { timeoutMs });
|
|
750
765
|
if (run.failure === "no-command") return unavailable("provider-not-qualified", `${mod.name} declares binding.check but no command ${JSON.stringify(check)}`);
|
|
751
|
-
if (run.failure === "no-executable") return unavailable("resource-not-found", `${mod.name}: the check executable ${run.script} is unavailable`);
|
|
766
|
+
if (run.failure === "no-executable") return unavailable("resource-not-found", run.problem ?? `${mod.name}: the check executable ${run.script} is unavailable`);
|
|
752
767
|
if (run.failure === "incomplete") return unavailable("provider-unavailable", `${mod.name} check did not complete${run.timedOut || run.signal ? " in time" : ""}`);
|
|
753
768
|
if (run.failure === "exit") return unavailable("provider-unavailable", `${mod.name} check exited ${run.status}`);
|
|
754
769
|
const invalid = () => unavailable("provider-unavailable", `${mod.name} check answered invalid binding data`);
|
|
@@ -830,6 +845,10 @@ export const PROVIDER_CHECK_BUDGET_MS = 60_000;
|
|
|
830
845
|
/** `oats readiness --json` on the workspace model. */
|
|
831
846
|
export async function readinessDocument(t, { selector = null, remoteOptions, catalog = null, budgetMs = PROVIDER_CHECK_BUDGET_MS } = {}) {
|
|
832
847
|
const installed = [], configured = [], member = [], providers = [];
|
|
848
|
+
// A provider home whose receipt holds no composition (lib/home-integrity.mjs): the kernel runs
|
|
849
|
+
// none of its capabilities, so it lists no module below. It is not ready, and says why.
|
|
850
|
+
const untrusted = t.home ? providerHomeTrust(t.home)?.problem : null;
|
|
851
|
+
if (untrusted) installed.push(item(t.soul.name, "fail", { producer: "instance modules", code: "module-copy-untrusted", reason: untrusted, remedy: `oats retire ${t.subject.instance} --force, then spawn it again (its retire hooks cannot be identified, so --force removes the home without running them)` }));
|
|
833
852
|
const cap = (id) => ({ capability: { id } });
|
|
834
853
|
if (t.resolutionError && !isTeamRefusal(t.resolutionError)) {
|
|
835
854
|
installed.push(item(t.soul.name, "fail", { producer: "workspace resolution", code: t.resolutionError.code, reason: t.resolutionError.message, evidence: t.resolutionError.details, remedy: "oats sync (the lock must provide every package capability the soul resolves)" }));
|
|
@@ -922,9 +941,44 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
|
|
|
922
941
|
return { capability: { id }, checks: Object.fromEntries(Object.keys(checks).map((name) => [name, of(name).length ? roll(of(name)) : "not-applicable"])),
|
|
923
942
|
ownReady: statuses.length > 0 && statuses.every((s) => s === "pass" || s === "not-applicable") };
|
|
924
943
|
});
|
|
944
|
+
// A home on a session provider: what its next launch may widen its harness's sandbox by
|
|
945
|
+
// (lib/sandbox-allowances.mjs), computed as a start computes it, from the deployment's
|
|
946
|
+
// configuration as it is now. Each host with the capability and the setting that asked for it,
|
|
947
|
+
// each path with its reason, what is missing and what was left out; or why there is none.
|
|
948
|
+
let sandbox;
|
|
949
|
+
if (t.home && recordsSessionProvider(t.meta)) {
|
|
950
|
+
const source = await homeSandboxSource(t.home, { remoteOptions });
|
|
951
|
+
if (source.unavailable) sandbox = { unavailable: source.unavailable };
|
|
952
|
+
else {
|
|
953
|
+
try {
|
|
954
|
+
sandbox = homeSandboxAllowances({ source, home: realpathSync(t.home), moduleNames: Object.keys(obj(t.meta.modules) ? t.meta.modules : {}) });
|
|
955
|
+
// What a start would refuse of the paths, read without creating one.
|
|
956
|
+
const refused = sandboxWritePathsRefusal(sandbox.write);
|
|
957
|
+
if (refused) throw refused;
|
|
958
|
+
}
|
|
959
|
+
catch (e) { if (e?.code !== "E_BACKEND_SANDBOX_HOST") throw e; sandbox = { refused: { code: e.code, message: e.message, details: e.details ?? null } }; }
|
|
960
|
+
}
|
|
961
|
+
}
|
|
962
|
+
// A home on a session provider: the kernel runs its own copies of the home's modules, never the
|
|
963
|
+
// home's (lib/home-integrity.mjs). This says which of the home's own copies differ from the
|
|
964
|
+
// ones the kernel runs: what the agent or its harness uses is then not what the kernel runs.
|
|
965
|
+
// It changes nothing the kernel does, and is compared here only, never on the status path.
|
|
966
|
+
let kernelCopies;
|
|
967
|
+
if (t.home) {
|
|
968
|
+
const trust = providerHomeTrust(t.home);
|
|
969
|
+
if (trust?.composition) {
|
|
970
|
+
const differing = [];
|
|
971
|
+
for (const capability of Object.keys(trust.composition.modules).sort()) {
|
|
972
|
+
const compared = treeDisagreement(kernelModuleDir(t.home, capability, trust), join(t.home, ".oats", "modules", capability));
|
|
973
|
+
if (compared.entries.length) differing.push({ capability, differs: true });
|
|
974
|
+
else if (!compared.complete) differing.push({ capability, differs: null });
|
|
975
|
+
}
|
|
976
|
+
kernelCopies = { store: trust.composition.store, differing };
|
|
977
|
+
}
|
|
978
|
+
}
|
|
925
979
|
const subjectBlockers = Object.entries(checks).flatMap(([name, c]) => c.items.filter((i) => i.required && !i.capability && i.status !== "pass" && i.status !== "not-applicable").map((i) => ({ check: name, subject: i.subject, status: i.status })));
|
|
926
980
|
for (const g of byCapability) g.ready = g.ownReady && subjectBlockers.length === 0;
|
|
927
|
-
return { readinessApi: READINESS_API, subject: t.subject, selector, at: new Date().toISOString(), checks,
|
|
981
|
+
return { readinessApi: READINESS_API, subject: t.subject, selector, at: new Date().toISOString(), checks, ...(sandbox ? { sandbox } : {}), ...(kernelCopies ? { kernelCopies } : {}),
|
|
928
982
|
summary: { ready: requiredStatuses.length > 0 && requiredStatuses.every((s) => s === "pass" || s === "not-applicable"), required: requiredStatuses.length,
|
|
929
983
|
pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length, byCapability, subjectBlockers },
|
|
930
984
|
notes: ["ready means every REQUIRED check passes; it is never inferred from an empty set",
|
package/lib/instance-listing.mjs
CHANGED
|
@@ -24,6 +24,7 @@ import { identityHolderState, recordSeen } from "./session-seen.mjs";
|
|
|
24
24
|
import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
|
|
25
25
|
import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot, providerMayWait } from "./session-inspect.mjs";
|
|
26
26
|
import { INSPECT_MANY_MAX, sessionProviderTimeout, homeSessionProvider, recordsSessionProvider, inspectManyGroup, inspectProviderSession, inspectProviderSessions, rowSession, unsettledLaunchSaid } from "./session-providers.mjs";
|
|
27
|
+
import { moduleCopyReport, providerHomeTrust } from "./home-integrity.mjs";
|
|
27
28
|
import { SESSION_END } from "./session-resume-contract.mjs";
|
|
28
29
|
|
|
29
30
|
/** OATS 0.25 and earlier homed local souls and capability-defined agents at
|
|
@@ -298,7 +299,10 @@ function providerRow(home, meta) {
|
|
|
298
299
|
const recorded = s.session ?? s.planned;
|
|
299
300
|
// A record that names a session provider beside a receipt that authorises a tmux session, or none.
|
|
300
301
|
if (!recorded) return unreachable("E_RUNTIME_AUTHORITY_MISMATCH: instance metadata records a session provider and its independent session receipt does not");
|
|
301
|
-
|
|
302
|
+
// `moduleCopy` (lib/home-integrity.mjs moduleCopyReport): which copy of its modules the kernel
|
|
303
|
+
// runs, and whether the home's own record of them is the receipt's. Records only: nothing is hashed.
|
|
304
|
+
const moduleCopy = moduleCopyReport(meta, providerHomeTrust(home));
|
|
305
|
+
const fields = { backend: recorded.backend, session: rowSession(recorded.provider, recorded.endpoint ?? null), tmux: null, open: null, ...(moduleCopy ? { moduleCopy } : {}) };
|
|
302
306
|
// A launch that was sent and never recorded: unknown, never stopped (lib/session-providers.mjs launchSentOf).
|
|
303
307
|
if (s.unsettled) return unreachable(unsettledLaunchSaid(basename(home), s.unsettled.backend, s.unsettled.launchSent), fields.session);
|
|
304
308
|
if (!s.session) return { fields: { ...fields, running: false, runtimeState: "stopped" } };
|