@awebai/oats 0.69.23 → 0.70.0
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 +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/kernel-features.mjs +10 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/lib/errors.mjs
CHANGED
|
@@ -78,11 +78,14 @@ const SPAWN_REFUSAL_DETAILS = Object.freeze({
|
|
|
78
78
|
});
|
|
79
79
|
const spawnFailedDetails = (e) => (e?.details?.unconfirmed === true ? e.details : undefined);
|
|
80
80
|
/** The `details` of the answer to an error `e` of `oats spawn` (bin/oats.mjs spawnFail): the table's
|
|
81
|
-
* for a code it holds, a launch refusal's own (`E_LAUNCH_…`),
|
|
81
|
+
* for a code it holds, a launch refusal's own (`E_LAUNCH_…`), a session backend's (`E_BACKEND_…`), else
|
|
82
|
+
* spawnFailedDetails. */
|
|
82
83
|
export function spawnRefusalDetails(e) {
|
|
83
84
|
const code = kernelCode(e, null);
|
|
84
85
|
if (code && Object.hasOwn(SPAWN_REFUSAL_DETAILS, code)) return SPAWN_REFUSAL_DETAILS[code](e);
|
|
85
86
|
if (code?.startsWith("E_LAUNCH_")) return e.details;
|
|
87
|
+
// A session backend's refusal (lib/session-providers.mjs): the backend, and what it names.
|
|
88
|
+
if (code?.startsWith("E_BACKEND_")) return e.details;
|
|
86
89
|
return spawnFailedDetails(e);
|
|
87
90
|
}
|
|
88
91
|
/** `e` as a kernel error. One whose code an answer carries (isAnswerCode) is returned as it is. Any other is wrapped:
|
|
@@ -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
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/** The environment a capability's code runs with in an instance home (docs/capabilities.md, Commands
|
|
2
|
+
* and hooks): one builder for every lifecycle hook and for a session provider's commands
|
|
3
|
+
* (lib/session-providers.mjs), with the soul, team and kernel facts it is built from. A leaf: the
|
|
4
|
+
* hot reads (lib/hot-reads.mjs: `session inspect`, `status`) call a session provider without
|
|
5
|
+
* loading core.mjs, which imports these and re-exports what it exported. */
|
|
6
|
+
import { readFileSync, realpathSync } from "node:fs";
|
|
7
|
+
import { isAbsolute, join } from "node:path";
|
|
8
|
+
import { kernelNode } from "./stable-node.mjs";
|
|
9
|
+
import { teamsEnv } from "./teams.mjs";
|
|
10
|
+
import { PKG_ROOT } from "./version.mjs";
|
|
11
|
+
|
|
12
|
+
/** The canonical path of this kernel's CLI: what the home's shim points at, and OATS_CLI_BIN. */
|
|
13
|
+
export function kernelBin() { return realpathSync(join(PKG_ROOT, "bin", "oats.mjs")); }
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* A soul's STABLE identity for capability hooks (OATS_SOUL_ID): what a provider
|
|
17
|
+
* may key durable state on. Workspace soul: `<repo key>#<soul name>` — it does not
|
|
18
|
+
* change when the member commits (the per-commit soul directory does) or when the
|
|
19
|
+
* copy moves. Classic soul: the realpath of agents/<name>/soul, i.e. today's value,
|
|
20
|
+
* so 0.24 deployments are unchanged. Order: an explicit `soulId` (a prepared spawn),
|
|
21
|
+
* the home's recorded `instance.json.workspace.soul` (retire/launch of a workspace
|
|
22
|
+
* home), else the path.
|
|
23
|
+
*/
|
|
24
|
+
export function stableSoulId({ soulId, home, soulDir, agentName } = {}) {
|
|
25
|
+
if (typeof soulId === "string" && soulId) return soulId;
|
|
26
|
+
if (home) {
|
|
27
|
+
try {
|
|
28
|
+
const meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
|
|
29
|
+
const s = meta?.workspace?.soul;
|
|
30
|
+
if (typeof s?.id === "string" && s.id) return s.id;
|
|
31
|
+
if (typeof s?.repoKey === "string" && s.repoKey) return `${s.repoKey}#${meta.agent ?? agentName ?? ""}`;
|
|
32
|
+
} catch { /* not a workspace home */ }
|
|
33
|
+
}
|
|
34
|
+
if (soulDir) { try { return realpathSync(soulDir); } catch { return soulDir; } }
|
|
35
|
+
return "";
|
|
36
|
+
}
|
|
37
|
+
/** The soul directory an instance incarnates, as spawn recorded it (instance.json
|
|
38
|
+
* `soulDir`): a workspace soul's per-commit copy (agents/<soul>/souls/<commit12>) or
|
|
39
|
+
* the read-only soul inside a capability package. It is what every classic
|
|
40
|
+
* lifecycle hook and dispatched command sees as OATS_SOUL (captured hooks set
|
|
41
|
+
* none); instance homes carry no soul link. */
|
|
42
|
+
export function instanceSoulDir(home, meta = undefined) {
|
|
43
|
+
if (meta === undefined && home) { try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); } catch { meta = null; } }
|
|
44
|
+
return typeof meta?.soulDir === "string" && isAbsolute(meta.soulDir) ? meta.soulDir : undefined;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The team and workspace facts a lifecycle hook, command or provider check receives (workspace
|
|
48
|
+
* model only, lead decision c3-7): OATS_TEAM_SCOPE is the deployment directory; OATS_WORKSPACE_NAME /
|
|
49
|
+
* _KEY the workspace's name and canonical key; OATS_TEAM_NAME (the 0.25 `team:` block's name) is always
|
|
50
|
+
* empty, so an ambient value never reaches a hook.
|
|
51
|
+
*
|
|
52
|
+
* Team model v2 (docs/desktop-cli-api.md, The provider environment): `resolved.teams` are the soul's
|
|
53
|
+
* TeamRows here and `resolved.defaultTeam` its DefaultTeam; teamsEnv sets OATS_DEFAULT_TEAM(_ID,_FROM),
|
|
54
|
+
* OATS_TEAMS (mapped rows only) and OATS_TEAMS_SOURCE (`live`: the workspace + oats-local.yaml read now,
|
|
55
|
+
* or a fresh resolution; `recorded`: the spawn-time record). A provider LEAVES a joined team only on a
|
|
56
|
+
* `live` list. Teams not known (`resolved.teams` not an array): every team name unset. */
|
|
57
|
+
export function teamEnv(resolved) {
|
|
58
|
+
const ws = resolved?.workspace && typeof resolved.workspace === "object" ? resolved.workspace : {};
|
|
59
|
+
const known = Array.isArray(resolved?.teams);
|
|
60
|
+
return {
|
|
61
|
+
OATS_TEAM_NAME: "", OATS_TEAM_SCOPE: typeof ws.deployment === "string" ? ws.deployment : "",
|
|
62
|
+
...teamsEnv(known ? { teams: resolved.teams, defaultTeam: resolved.defaultTeam ?? null, source: resolved.teamsSource } : null),
|
|
63
|
+
OATS_WORKSPACE_NAME: typeof ws.name === "string" ? ws.name : "", OATS_WORKSPACE_KEY: typeof ws.key === "string" ? ws.key : "",
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
export function withoutAmbientHookFacts(env) {
|
|
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;
|
|
69
|
+
return rest;
|
|
70
|
+
}
|
|
71
|
+
/** The environment one capability's lifecycle hook runs with: the invoker's own
|
|
72
|
+
* (inherited, as for every hook; the kernel adds no credentials), plus the
|
|
73
|
+
* standard OATS_* variables (docs/capabilities.md, Commands and hooks) and the
|
|
74
|
+
* caller's `extraEnv`. One builder for every event, so the `worktree` runner
|
|
75
|
+
* (lib/worktree-hooks.mjs) hands its hooks exactly what every other hook gets. */
|
|
76
|
+
export function lifecycleHookEnv(event, cap, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
|
|
77
|
+
return {
|
|
78
|
+
// OATS_LAUNCH_PREVIEW is the kernel's to give (prepareLaunchHooks), never
|
|
79
|
+
// inherited: a real start's hook must not read an ambient one as a preview.
|
|
80
|
+
// Nor are OATS_HARNESS_EXECUTABLE and OATS_SPAWNER_HOME (spawn's
|
|
81
|
+
// callerSpawner): a hook started from inside an instance must not read its caller's.
|
|
82
|
+
...withoutAmbientHookFacts(process.env),
|
|
83
|
+
// OATS_INSTANCE_HOME is the runtime-neutral contract name for the
|
|
84
|
+
// instance home (absolute). OATS_HOME predates it and stays as a
|
|
85
|
+
// compatibility alias: shipped capability hooks read it
|
|
86
|
+
// (the official oats.aweb and oats.okf packages) and are versioned
|
|
87
|
+
// independently of this kernel. Neither is OATS_HOME_DIR, which is
|
|
88
|
+
// the package STORE root — do not conflate them.
|
|
89
|
+
OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
|
|
90
|
+
OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
|
|
91
|
+
OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
|
|
92
|
+
...teamEnv(resolved),
|
|
93
|
+
...extraEnv,
|
|
94
|
+
// Hooks also run through direct core callers (not only bin/oats).
|
|
95
|
+
// Author this from the running kernel, never PATH, ambient env or
|
|
96
|
+
// a caller's extraEnv: those may point at a different executable.
|
|
97
|
+
OATS_CLI_BIN: kernelBin(),
|
|
98
|
+
// The node a capability writes into anything that outlives its hook (lib/stable-node.mjs).
|
|
99
|
+
OATS_NODE_BIN: kernelNode().node,
|
|
100
|
+
OATS_SETTINGS: JSON.stringify(cap.settings || {}),
|
|
101
|
+
// Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
|
|
102
|
+
// manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
|
|
103
|
+
// soul-set value from a host-set one. {} when the home recorded none (spawned before 0.29).
|
|
104
|
+
OATS_SETTINGS_ORIGINS: JSON.stringify(cap.settingsOrigins || {}),
|
|
105
|
+
OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
|
|
106
|
+
};
|
|
107
|
+
}
|
package/lib/host-run.mjs
CHANGED
|
@@ -107,7 +107,8 @@ function sweepSaid(rows) {
|
|
|
107
107
|
* On the signal, in this order: no minute is armed any more; a tick or a sweep that runs is
|
|
108
108
|
* given 10 s to finish, then new admissions are fenced and owned children are cancelled
|
|
109
109
|
* within a further 5 s (a tick's wake job may start a home, so owned work ends before any
|
|
110
|
-
* home is stopped); one bounded listing; then every running home
|
|
110
|
+
* home is stopped); one bounded listing; then every running home, and every home on a session provider that OATS has
|
|
111
|
+
* not stopped (its session idle or in error included), is stopped, side by side, each by a child of its
|
|
111
112
|
* own (lib/host-stop-child.mjs: the stop `oats session restart` and a retire use, its record
|
|
112
113
|
* written first and asking for a resume, the harness given `stopGraceMs` and never escalated).
|
|
113
114
|
* The next start's sweep resumes those homes.
|
|
@@ -176,7 +177,10 @@ export async function hostRun({
|
|
|
176
177
|
// minute missed while this process did not run is never armed again.
|
|
177
178
|
const ticks = { run: 0, skipped: 0, failed: 0, noScope: 0 };
|
|
178
179
|
let ticking = null, sweeping = null, ticked;
|
|
179
|
-
|
|
180
|
+
// The shutdown's listing asks no session provider: it must answer within its few seconds while
|
|
181
|
+
// the host, and a provider's own server with it, go down. It needs no provider's answer: the
|
|
182
|
+
// stop covers every provider home OATS has not stopped, whatever its session reads.
|
|
183
|
+
const list = (options) => execute(["session", "resume", "--plan", "--without-provider-inspect", "--json"], options);
|
|
180
184
|
const arm = () => { disarm = timer(minute, MINUTE - (now() % MINUTE)); };
|
|
181
185
|
const minute = () => {
|
|
182
186
|
if (signal) return;
|
|
@@ -213,7 +217,11 @@ export async function hostRun({
|
|
|
213
217
|
await Promise.all([ticking, sweeping]);
|
|
214
218
|
const last = await list({ timeoutMs: 3000 });
|
|
215
219
|
if (last?.ok !== true) say(`listing failed ${failed(last)}: no instance is stopped`);
|
|
216
|
-
|
|
220
|
+
// Every running home, and every home on a session provider the listing answered (its row carries
|
|
221
|
+
// `backend`), idle or in error included: a provider restarts such a session on its next input,
|
|
222
|
+
// so the stop is what keeps input refused while the host goes down. A provider home OATS
|
|
223
|
+
// already stopped is idle for the stop, which changes nothing of it.
|
|
224
|
+
const homes = last?.ok === true ? (last.result?.rows ?? []).filter((row) => (row.outcome === OUTCOME.ALREADY_RUNNING || typeof row.backend === "string") && typeof row.home === "string").map((row) => row.home) : [];
|
|
217
225
|
if (homes.length) say(`stopping ${plural(homes.length, "running instance")}, each given ${stopGraceMs / 1000} s`);
|
|
218
226
|
// Side by side: each stop waits for its own harness, and the host's patience is one span for all.
|
|
219
227
|
const stopped = await Promise.all(homes.map(async (home) => {
|
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"];
|