@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
|
+
/** Sandbox allowances (docs/capabilities.md "Sandbox allowances"): what a session provider may
|
|
2
|
+
* widen its harness's sandbox by, for one launch. The kernel builds the list; the provider writes
|
|
3
|
+
* it and nothing else. Two kinds of entry, and where each may come from:
|
|
4
|
+
*
|
|
5
|
+
* - `domains`: exact hosts. Only the capability that fills the instance's messaging, knowledge or
|
|
6
|
+
* tasks slot may contribute one, only by a manifest line `sandboxDomains: [{ "setting": "<key>" }]`
|
|
7
|
+
* that names one of its own settings. The setting's value is a URL (the kernel takes its host),
|
|
8
|
+
* a bare host, or a map from team id to one of those, of which only the entries of the
|
|
9
|
+
* instance's own teams are taken. A line on any other capability refuses the launch, never
|
|
10
|
+
* drops the line. A line may instead be `{ "settingFile": "<key>", "urls": "<JSON pointer>" }`:
|
|
11
|
+
* the setting's value is the path of a JSON file of the deployment, and the hosts are those
|
|
12
|
+
* of every string at the pointer (readSettingFileHosts, with its bounds). Nothing at run time
|
|
13
|
+
* (hook output, an environment variable, a task, a launch argument) can add a host.
|
|
14
|
+
* - `write`: exact absolute paths, the kernel's own, never a capability's: the deployment's events
|
|
15
|
+
* directory (sandboxEventsDir), which the kernel creates before the launch
|
|
16
|
+
* (ensureSandboxWritePaths): an allowance on a path that does not exist does not let a
|
|
17
|
+
* sandboxed agent create it.
|
|
18
|
+
*
|
|
19
|
+
* The values are the DEPLOYMENT'S: a resolution's `slots` and `payloads` (what a spawn preview
|
|
20
|
+
* shows), never a file inside an instance home, which a sandboxed agent can write. For an existing
|
|
21
|
+
* home, which deployment and which soul are resolved is the home's PATH'S to say
|
|
22
|
+
* (lib/instance-resolution.mjs homeSandboxSource), never its instance.json's; the one thing read
|
|
23
|
+
* from the home is the list of its modules, which can only leave a host out (homeSandboxAllowances).
|
|
24
|
+
*
|
|
25
|
+
* A leaf: no import of the kernel's heavy modules. Every refusal is E_BACKEND_SANDBOX_HOST, with
|
|
26
|
+
* `details: { capability, setting?, host? }`. */
|
|
27
|
+
import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync } from "node:fs";
|
|
28
|
+
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
|
|
29
|
+
import { parseStrictJson } from "./canonical-json.mjs";
|
|
30
|
+
import { oatsError } from "./errors.mjs";
|
|
31
|
+
|
|
32
|
+
/** The slots whose provider may declare `sandboxDomains`. */
|
|
33
|
+
export const SANDBOX_SLOTS = ["messaging", "knowledge", "tasks"];
|
|
34
|
+
/** At most this many lines in one manifest. */
|
|
35
|
+
export const MAX_SANDBOX_LINES = 16;
|
|
36
|
+
const SETTING_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
|
|
37
|
+
/** A host as an allowlist takes it: DNS labels (letters, digits, hyphens; no wildcard, no
|
|
38
|
+
* underscore), at most 253 characters, or a dotted IPv4 address, which the same pattern covers. */
|
|
39
|
+
const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
|
|
40
|
+
const HOST_RE = new RegExp(`^${LABEL}(?:\\.${LABEL})*$`);
|
|
41
|
+
/** `scheme://[userinfo@]host[:port][/path][?query][#fragment]`, the authority kept as written: WHATWG
|
|
42
|
+
* URL drops a port that is the scheme's default, and the entry carries a port only when the URL names one. */
|
|
43
|
+
const URL_RE = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)(?:[/?#].*)?$/i;
|
|
44
|
+
|
|
45
|
+
/** A `settingFile` line's file: at most this many bytes, and this many hosts. */
|
|
46
|
+
export const SETTING_FILE_MAX_BYTES = 64 * 1024, SETTING_FILE_MAX_HOSTS = 16;
|
|
47
|
+
/** A JSON pointer (RFC 6901) of at most 16 segments, of which at most one is `*`: every key of the
|
|
48
|
+
* object, or every element of the array, at that place. */
|
|
49
|
+
const pointerSegments = (pointer) => {
|
|
50
|
+
if (typeof pointer !== "string" || !pointer.startsWith("/") || pointer.length > 400) return null;
|
|
51
|
+
const segments = pointer.slice(1).split("/");
|
|
52
|
+
if (segments.length > 16 || segments.some((s) => s === "" || /~(?![01])/.test(s)) || segments.filter((s) => s === "*").length > 1) return null;
|
|
53
|
+
return segments.map((s) => (s === "*" ? { any: true } : { key: s.replace(/~1/g, "/").replace(/~0/g, "~") }));
|
|
54
|
+
};
|
|
55
|
+
/** A git remote in scp form, `user@host:path` or `host.name:path`: its host. Only a `settingFile`'s
|
|
56
|
+
* strings are read so. `host:<port number>` is a bare host with its port, never this; and without
|
|
57
|
+
* a user the host must have a dot, so that `C:/dir` or `name:path` is no remote. */
|
|
58
|
+
const SCP_REMOTE_RE = /^(?:[A-Za-z0-9._-]+@([A-Za-z0-9.-]+)|([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+)):(?!\/\/)(?![0-9]{1,5}$)[^\s]+$/;
|
|
59
|
+
|
|
60
|
+
const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
61
|
+
const refuse = (message, details) => Object.assign(oatsError("E_BACKEND_SANDBOX_HOST", message), { details });
|
|
62
|
+
|
|
63
|
+
/** `manifest.sandboxDomains` as the kernel reads it → `{ lines: [{ setting, optional }], problems:
|
|
64
|
+
* [string] }`. A line is `{ "setting": "<key>" }`, with `"optional": true` when the session works
|
|
65
|
+
* without that host (its absence is then no reason for a provider to refuse a launch).
|
|
66
|
+
* Total: it never throws. A manifest without the key has no lines and no problems. A problem is a
|
|
67
|
+
* refusal wherever the lines are used (sandboxAllowances): a line is never dropped. */
|
|
68
|
+
export function sandboxDomainsOf(manifest) {
|
|
69
|
+
const declared = manifest?.sandboxDomains;
|
|
70
|
+
if (declared === undefined) return { lines: [], problems: [] };
|
|
71
|
+
if (!Array.isArray(declared) || declared.length < 1 || declared.length > MAX_SANDBOX_LINES) return { lines: [], problems: [`sandboxDomains must list 1 to ${MAX_SANDBOX_LINES} entries`] };
|
|
72
|
+
const lines = [], problems = [];
|
|
73
|
+
declared.forEach((line, i) => {
|
|
74
|
+
const keys = isObject(line) ? Object.keys(line) : [];
|
|
75
|
+
if (isObject(line) && Object.hasOwn(line, "settingFile")) {
|
|
76
|
+
if (typeof line.settingFile !== "string" || !SETTING_KEY_RE.test(line.settingFile) || keys.some((k) => k !== "settingFile" && k !== "urls") || !pointerSegments(line.urls)) problems.push(`sandboxDomains[${i}] must be { "settingFile": "<one of the capability's setting keys>", "urls": "<a JSON pointer, at most one * segment>" }`);
|
|
77
|
+
else if (lines.some((l) => (l.settingFile ?? l.setting) === line.settingFile)) problems.push(`sandboxDomains[${i}] names the setting ${line.settingFile} a second time`);
|
|
78
|
+
else lines.push({ settingFile: line.settingFile, urls: line.urls });
|
|
79
|
+
return;
|
|
80
|
+
}
|
|
81
|
+
if (!isObject(line) || typeof line.setting !== "string" || !SETTING_KEY_RE.test(line.setting) || keys.some((k) => k !== "setting" && k !== "optional") || (line.optional !== undefined && typeof line.optional !== "boolean")) problems.push(`sandboxDomains[${i}] must be { "setting": "<one of the capability's setting keys>", "optional"?: true }`);
|
|
82
|
+
else if (lines.some((l) => (l.settingFile ?? l.setting) === line.setting)) problems.push(`sandboxDomains[${i}] names the setting ${line.setting} a second time`);
|
|
83
|
+
else lines.push({ setting: line.setting, optional: line.optional === true });
|
|
84
|
+
});
|
|
85
|
+
if (!SANDBOX_SLOTS.includes(manifest?.layer)) problems.push(`sandboxDomains is for a capability whose layer is ${SANDBOX_SLOTS.join(", ")}: this one declares ${manifest?.layer === undefined ? "none" : JSON.stringify(manifest.layer)}`);
|
|
86
|
+
return { lines, problems };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** The host of a setting's value, as an allowlist entry → `{ host }`, or `{ problem }` saying why
|
|
90
|
+
* the value gives none. The value is a URL (anything with `://`: its host is taken) or a bare host
|
|
91
|
+
* (`host` or `host:port`). The entry is a bare host: lower case, no wildcard, scheme or path; its
|
|
92
|
+
* port only when the value names one. A value that carries credentials is refused whole: nothing
|
|
93
|
+
* of it is quoted. */
|
|
94
|
+
export function sandboxHostOf(value, { userName = false } = {}) {
|
|
95
|
+
if (typeof value !== "string" || !value.trim()) return { problem: "is not a URL or a host" };
|
|
96
|
+
const text = value.trim();
|
|
97
|
+
const m = URL_RE.exec(text);
|
|
98
|
+
if (!m && /[/?#\s]/.test(text)) return { problem: "is neither a URL with a scheme and a host nor a bare host" };
|
|
99
|
+
const authority = m ? m[2] : text;
|
|
100
|
+
// A user name alone is no credential (a git remote carries one), where the caller reads such values.
|
|
101
|
+
const user = authority.includes("@") ? authority.slice(0, authority.lastIndexOf("@")) : null;
|
|
102
|
+
if (user !== null && !(userName && m && /^[A-Za-z0-9._-]+$/.test(user))) return { problem: "is a URL that carries credentials" };
|
|
103
|
+
const hostPort = user === null ? authority : authority.slice(user.length + 1);
|
|
104
|
+
const at = hostPort.lastIndexOf(":");
|
|
105
|
+
const [name, port] = at >= 0 && !hostPort.endsWith("]") ? [hostPort.slice(0, at), hostPort.slice(at + 1)] : [hostPort, null];
|
|
106
|
+
const host = name.toLowerCase();
|
|
107
|
+
if (!host) return { problem: "is a URL without a host" };
|
|
108
|
+
if (host.includes("*")) return { problem: `names a wildcard host (${host}): an allowance is one exact host` };
|
|
109
|
+
if (host.length > 253 || !HOST_RE.test(host)) return { problem: "names a host that is no plain DNS name or IPv4 address" };
|
|
110
|
+
if (port !== null && (!/^[0-9]{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535)) return { problem: "names a port that is no port number" };
|
|
111
|
+
return { host: port === null ? host : `${host}:${Number(port)}` };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** The hosts a `settingFile` line gives → `{ hosts: [host] }`, `{ unread: "<why>" }` when the file
|
|
115
|
+
* gives none this kernel will use (missing, not a regular file, too large, no strict JSON, more
|
|
116
|
+
* than SETTING_FILE_MAX_HOSTS hosts: the launch goes on without them, and readiness names it), or
|
|
117
|
+
* `{ refused: "<why>" }` when the path itself is one no allowance may be read from.
|
|
118
|
+
*
|
|
119
|
+
* `path`: the setting's value. `within`: the deployment's directory. `outside`: directories inside
|
|
120
|
+
* it that are never a source (its instance homes, the paths the allowances make writable). The
|
|
121
|
+
* path must be inside `within` and outside each of those, as its REAL path, with no symbolic link
|
|
122
|
+
* anywhere along it below the deployment: a link planted in a parent directory cannot move the
|
|
123
|
+
* read to a file a sandboxed agent can write. The file is opened without following a link, as a
|
|
124
|
+
* regular file, and read once, at most SETTING_FILE_MAX_BYTES.
|
|
125
|
+
*
|
|
126
|
+
* A string at the pointer gives a host when it is a URL with a plain host (a user name is allowed,
|
|
127
|
+
* as git remotes carry one; a password is not) or a git remote in scp form (`git@host:path`);
|
|
128
|
+
* another string is skipped and counted in `skippedValues`. */
|
|
129
|
+
export function readSettingFileHosts({ path, pointer, within, outside = [] }) {
|
|
130
|
+
if (typeof path !== "string" || !path.trim()) return { unread: "the setting names no file" };
|
|
131
|
+
let root;
|
|
132
|
+
try { root = realpathSync(within); } catch (e) { return { refused: `the deployment's directory cannot be resolved (${e.code ?? e.message})` }; }
|
|
133
|
+
// The path as written, under the deployment's real directory. An absolute path may spell the
|
|
134
|
+
// deployment through a link; it is re-rooted at the FIRST place it enters the deployment, the
|
|
135
|
+
// outermost of its ancestors whose real path is the deployment's, and from there down no link
|
|
136
|
+
// is allowed. Outermost, never nearest: a link below the deployment that leads back to it (one
|
|
137
|
+
// an agent makes in its home) is then part of what must be link-free, not a new root. And the
|
|
138
|
+
// same whichever spelling the caller knows the deployment by (a spawn's `--dir`, a start's real
|
|
139
|
+
// path): both read the same file, or both refuse.
|
|
140
|
+
const written = resolve(isAbsolute(path) ? path : resolve(within, path));
|
|
141
|
+
let entered = null;
|
|
142
|
+
for (let dir = dirname(written); ; dir = dirname(dir)) {
|
|
143
|
+
try { if (realpathSync(dir) === root) entered = dir; } catch { /* not there: the file is not either, said below */ }
|
|
144
|
+
if (dirname(dir) === dir) break;
|
|
145
|
+
}
|
|
146
|
+
const rel = entered === null ? null : relative(entered, written);
|
|
147
|
+
const below = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : null;
|
|
148
|
+
if (!below) return { refused: `${path} is not inside the deployment (${root}): a host is read only from the deployment's own files` };
|
|
149
|
+
const target = resolve(root, below);
|
|
150
|
+
const inside = (dir) => { const rel = relative(dir, target); return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)); };
|
|
151
|
+
const forbidden = outside.map((dir) => { try { return realpathSync(dir); } catch { return resolve(dir); } }).find(inside);
|
|
152
|
+
if (forbidden) return { refused: `${path} is inside ${forbidden}, which a session's agent can write: a host is never read from there` };
|
|
153
|
+
let real;
|
|
154
|
+
try { real = realpathSync(target); } catch (e) { return e.code === "ENOENT" || e.code === "ENOTDIR" ? { unread: `${target} does not exist` } : { unread: `${target} cannot be read (${e.code ?? e.message})` }; }
|
|
155
|
+
if (real !== target) return { refused: `${path} reaches its file through a symbolic link (${target} is ${real}): a host is read only from a path with no link along it` };
|
|
156
|
+
let fd;
|
|
157
|
+
try { fd = openSync(target, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0)); } catch (e) { return { unread: `${target} cannot be opened (${e.code ?? e.message})` }; }
|
|
158
|
+
let doc;
|
|
159
|
+
try {
|
|
160
|
+
const st = fstatSync(fd);
|
|
161
|
+
if (!st.isFile()) return { unread: `${target} is not a regular file` };
|
|
162
|
+
// Another name of the same file could be in a place a session's agent can write. (What this
|
|
163
|
+
// sees is a second name that exists NOW: one made, written through and removed before this
|
|
164
|
+
// read is not seen. The file's own mode and place are what keep it from that.)
|
|
165
|
+
if (st.nlink > 1) return { unread: `${target} has more than one hard link` };
|
|
166
|
+
if (st.size > SETTING_FILE_MAX_BYTES) return { unread: `${target} is larger than ${SETTING_FILE_MAX_BYTES / 1024} KiB` };
|
|
167
|
+
const buffer = Buffer.alloc(SETTING_FILE_MAX_BYTES + 1);
|
|
168
|
+
let length = 0;
|
|
169
|
+
for (let n; length < buffer.length && (n = readSync(fd, buffer, length, buffer.length - length, null)) > 0;) length += n;
|
|
170
|
+
if (length > SETTING_FILE_MAX_BYTES) return { unread: `${target} is larger than ${SETTING_FILE_MAX_BYTES / 1024} KiB` };
|
|
171
|
+
try { doc = parseStrictJson(buffer.subarray(0, length), { maxBytes: SETTING_FILE_MAX_BYTES }); } catch { return { unread: `${target} is not strict JSON` }; }
|
|
172
|
+
} catch (e) { return { unread: `${target} cannot be read (${e.code ?? e.message})` }; }
|
|
173
|
+
finally { closeSync(fd); }
|
|
174
|
+
// Every value at the pointer.
|
|
175
|
+
let values = [doc];
|
|
176
|
+
for (const segment of pointerSegments(pointer) ?? []) {
|
|
177
|
+
values = values.flatMap((v) => {
|
|
178
|
+
if (segment.any) return Array.isArray(v) ? v : v !== null && typeof v === "object" ? Object.values(v) : [];
|
|
179
|
+
if (Array.isArray(v)) return /^(0|[1-9][0-9]*)$/.test(segment.key) && Number(segment.key) < v.length ? [v[Number(segment.key)]] : [];
|
|
180
|
+
return v !== null && typeof v === "object" && Object.hasOwn(v, segment.key) ? [v[segment.key]] : [];
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
const hosts = [];
|
|
184
|
+
let skippedValues = 0;
|
|
185
|
+
for (const value of values) {
|
|
186
|
+
const scp = typeof value === "string" ? SCP_REMOTE_RE.exec(value.trim()) : null;
|
|
187
|
+
const { host } = scp ? sandboxHostOf(scp[1] ?? scp[2]) : sandboxHostOf(value, { userName: true });
|
|
188
|
+
if (!host) skippedValues += 1;
|
|
189
|
+
else if (!hosts.includes(host)) hosts.push(host);
|
|
190
|
+
}
|
|
191
|
+
if (hosts.length > SETTING_FILE_MAX_HOSTS) return { unread: `${target} names ${hosts.length} hosts, more than the ${SETTING_FILE_MAX_HOSTS} one file may give` };
|
|
192
|
+
return { hosts, skippedValues };
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/** The path the kernel itself allows a sandboxed session to write: the deployment's events
|
|
196
|
+
* directory (`<deployment>/.agents/events`, where lib/instance-events.mjs appends a home's events
|
|
197
|
+
* and `oats instance attention` its claim), under the deployment's REAL path. `deployment` is the
|
|
198
|
+
* caller's, established outside any instance home. */
|
|
199
|
+
export function sandboxEventsDir(deployment) {
|
|
200
|
+
let real;
|
|
201
|
+
try { real = realpathSync(deployment); } catch { real = resolve(deployment); }
|
|
202
|
+
return join(real, ".agents", "events");
|
|
203
|
+
}
|
|
204
|
+
/** What ensureSandboxWritePaths would refuse of `write`, without creating anything (a readiness
|
|
205
|
+
* read): a path that exists and is not a real directory at exactly that path, or whose nearest
|
|
206
|
+
* existing ancestor is reached through a link → the refusal, or null. */
|
|
207
|
+
export function sandboxWritePathsRefusal(write) {
|
|
208
|
+
for (const { path } of write ?? []) {
|
|
209
|
+
// The nearest ancestor that is THERE, a link that leads nowhere included (lstat, which does
|
|
210
|
+
// not follow one): a launch would refuse that link, so a read does.
|
|
211
|
+
const there = (at) => { try { lstatSync(at); return true; } catch { return false; } };
|
|
212
|
+
let ancestor = path;
|
|
213
|
+
while (!there(ancestor) && dirname(ancestor) !== ancestor) ancestor = dirname(ancestor);
|
|
214
|
+
let sound;
|
|
215
|
+
try { sound = realpathSync(ancestor) === ancestor && (ancestor !== path || lstatSync(path).isDirectory()); } catch { sound = false; }
|
|
216
|
+
if (!sound) return refuse(`the session's sandbox may not be allowed to write ${path}: it is reached through a symbolic link, or is no directory; nothing was created or launched`, { capability: null, setting: null, host: null, path });
|
|
217
|
+
}
|
|
218
|
+
return null;
|
|
219
|
+
}
|
|
220
|
+
/** Make the `write` paths of an allowance exist, right before the launch that is handed them, and
|
|
221
|
+
* hold each to what it must be: a real directory at exactly that path, reached through no symbolic
|
|
222
|
+
* link. A path that is anything else is refused (E_BACKEND_SANDBOX_HOST): an allowance on it would
|
|
223
|
+
* let the session write wherever the link leads. */
|
|
224
|
+
export function ensureSandboxWritePaths(write) {
|
|
225
|
+
for (const { path } of write ?? []) {
|
|
226
|
+
// Nothing is created through a link: what a read would refuse is refused before anything is made.
|
|
227
|
+
const refused = sandboxWritePathsRefusal([{ path }]);
|
|
228
|
+
if (refused) throw refused;
|
|
229
|
+
try {
|
|
230
|
+
mkdirSync(path, { recursive: true });
|
|
231
|
+
if (realpathSync(path) !== path || !lstatSync(path).isDirectory()) throw Object.assign(new Error("it is reached through a symbolic link, or is no directory"), { code: "ELOOP" });
|
|
232
|
+
} catch (e) {
|
|
233
|
+
throw refuse(`the session's sandbox may not be allowed to write ${path}: ${e.code === "ELOOP" ? e.message : `it cannot be made (${e.code ?? e.message})`}; nothing was created or launched`, { capability: null, setting: null, host: null, path });
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
/** The allowances of a launch of an EXISTING home (a start, a restart; readiness): the deployment's
|
|
238
|
+
* resolution for the home's soul (`source`: lib/instance-resolution.mjs homeSandboxSource, which
|
|
239
|
+
* takes the deployment and the soul from where the home is, never from what is in it), with hosts
|
|
240
|
+
* only for the capabilities that are also the home's modules (`moduleNames`, the home's own
|
|
241
|
+
* record: it can only leave a host of that resolution out, never add one). `home`: its real path. */
|
|
242
|
+
export function homeSandboxAllowances({ source, home, moduleNames }) {
|
|
243
|
+
const eventsDir = sandboxEventsDir(source.deployment);
|
|
244
|
+
return sandboxAllowances({ modules: source.modules, slots: source.slots, payloads: source.payloads, teams: source.teams, defaultTeam: source.defaultTeam ?? null, eventsDir, only: moduleNames, deployment: source.deployment, outside: [dirname(dirname(dirname(home))), eventsDir] });
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** What a provider's launch is handed of the allowances: the three lists, each host with the
|
|
248
|
+
* capability and the setting that asked for it, never the kernel's own notes (a host's `team`,
|
|
249
|
+
* `skipped`, `unread`), which are for the answer and for readiness. */
|
|
250
|
+
export const sandboxLaunchInput = ({ domains, write, missing }) => ({ domains: domains.map(({ host, capability, setting }) => ({ host, capability, setting })), write, missing });
|
|
251
|
+
|
|
252
|
+
/** The allowances of one launch → `{ domains: [{ host, capability, setting, team? }], write: [{ path, reason }],
|
|
253
|
+
* missing: [{ capability, setting, team, defaultTeam, optional? }] }` (`sandboxLaunchInput` is what a
|
|
254
|
+
* provider is handed of it). `missing`: what a line names and the deployment's configuration does
|
|
255
|
+
* not hold: a team of the instance with no entry in a map (`team`: its id), or a setting with no
|
|
256
|
+
* value at all (`team: null`). `defaultTeam` is true on the row of the soul's default team and on
|
|
257
|
+
* a row with `team: null`, false on another team's; `optional: true` on a row of a line declared
|
|
258
|
+
* so. The kernel adds no host for those and refuses nothing: a provider that would sandbox the
|
|
259
|
+
* session refuses on a row that is not optional and whose `defaultTeam` is true (without its
|
|
260
|
+
* default team's service the agent has no messaging at all), since only it knows its mode; the
|
|
261
|
+
* other rows are for readiness.
|
|
262
|
+
*
|
|
263
|
+
* `modules`: the instance's capabilities, `[{ name, manifest }]`. `slots`: `{ messaging, knowledge,
|
|
264
|
+
* tasks }`, each the name of the capability that fills it, or null. `payloads`: `{ <capability>:
|
|
265
|
+
* { <setting>: value } }`, the deployment's effective settings, and `origins` (`{ <capability>: {
|
|
266
|
+
* <JSON pointer>: { kind } } }`, a resolution's `payloadOrigins`) where each came from. `teams`: the instance's team ids
|
|
267
|
+
* (the `team` of each row of the resolution's `teams`) and `defaultTeam`, the id of the soul's
|
|
268
|
+
* default team there, or null. `eventsDir`: the deployment's events
|
|
269
|
+
* directory, absolute. `deployment` and `outside`: where a `settingFile` line's file may be (inside
|
|
270
|
+
* the first, outside each of the second: readSettingFileHosts); `unread: [{ capability, setting,
|
|
271
|
+
* reason }]`, in the answer only when there is one, names each such file that gave no host, or
|
|
272
|
+
* values in it that were skipped. `only`, when given (a start of an existing home): the names of the home's
|
|
273
|
+
* own modules; a slot's provider of the deployment that is not one of them contributes no host
|
|
274
|
+
* and is named in `skipped: [{ capability, reason }]`, which is in the answer only then.
|
|
275
|
+
*
|
|
276
|
+
* Refused (E_BACKEND_SANDBOX_HOST), naming the capability and what it asked for: a malformed
|
|
277
|
+
* declaration; a capability that declares the line and fills none of the three slots; a setting
|
|
278
|
+
* a line names whose value was given to this spawn alone (origin `spawn`); a setting whose value
|
|
279
|
+
* is set and gives no plain host. A setting with no value contributes no host and is
|
|
280
|
+
* listed in `missing`. Of a map (team id → URL or host) only the entries of the instance's teams
|
|
281
|
+
* are read: another team's entry is neither taken nor judged, and a team without an entry
|
|
282
|
+
* contributes no host and is listed in `missing`.
|
|
283
|
+
* Hosts are deduplicated: the first capability, in `modules` order, to ask for one is named. */
|
|
284
|
+
export function sandboxAllowances({ modules = [], slots = {}, payloads = {}, origins = {}, teams = [], defaultTeam = null, eventsDir, only, deployment, outside = [] }) {
|
|
285
|
+
const domains = [], skipped = [], missing = [], unread = [];
|
|
286
|
+
for (const { name, manifest } of modules) {
|
|
287
|
+
if (manifest?.sandboxDomains === undefined) continue;
|
|
288
|
+
const { lines, problems } = sandboxDomainsOf(manifest);
|
|
289
|
+
const slot = SANDBOX_SLOTS.find((s) => slots?.[s] === name);
|
|
290
|
+
// One entry per value a line names: the setting's own, or each of the instance's teams' in a map.
|
|
291
|
+
const asked = lines.filter((l) => l.setting !== undefined).flatMap(({ setting, optional }) => {
|
|
292
|
+
const value = isObject(payloads?.[name]) && Object.hasOwn(payloads[name], setting) ? payloads[name][setting] : undefined;
|
|
293
|
+
if (!isObject(value)) return [{ setting, optional, team: null, value }];
|
|
294
|
+
return teams.filter((team, i) => typeof team === "string" && teams.indexOf(team) === i).map((team) => ({ setting, optional, team, value: Object.hasOwn(value, team) ? value[team] : undefined }));
|
|
295
|
+
});
|
|
296
|
+
if (!slot) {
|
|
297
|
+
// Named with the host it asked for, where its setting gives one.
|
|
298
|
+
const first = asked.map((l) => ({ setting: l.setting, host: sandboxHostOf(l.value).host ?? null })).find((l) => l.host) ?? { setting: asked[0]?.setting ?? null, host: null };
|
|
299
|
+
throw refuse(`capability ${name} declares sandboxDomains${first.host ? ` (the host ${first.host}, from its setting ${first.setting})` : ""}, and it is not this instance's ${SANDBOX_SLOTS.join(", ")} provider: only the capability that fills one of those slots may add a host to a session's sandbox; nothing was launched`, { capability: name, setting: first.setting, host: first.host });
|
|
300
|
+
}
|
|
301
|
+
if (only && !only.includes(name)) { skipped.push({ capability: name, reason: `the deployment's ${slot} provider is ${name}, which is not one of this home's modules: its hosts are not allowed here (respawn the instance to take the deployment's composition)` }); continue; }
|
|
302
|
+
// A value given to one spawn (`--provider <capability> <setting>=…`) is a launch's own
|
|
303
|
+
// argument, never the deployment's configuration: no host comes from it, and it is not passed
|
|
304
|
+
// over in silence either (the next start would resolve another host without a word).
|
|
305
|
+
const pointer = (setting) => `/${String(setting).replace(/~/g, "~0").replace(/\//g, "~1")}`;
|
|
306
|
+
const perSpawn = lines.map((l) => l.setting ?? l.settingFile).find((setting) => Object.entries(isObject(origins?.[name]) ? origins[name] : {}).some(([at, origin]) => (at === pointer(setting) || at.startsWith(`${pointer(setting)}/`)) && origin?.kind === "spawn"));
|
|
307
|
+
if (perSpawn !== undefined) throw refuse(`capability ${name} asks to allow the host of its setting ${perSpawn}, and this spawn was given that setting itself (--provider ${name} ${perSpawn}=…): a host comes from the deployment's configuration (the soul, the workspace, oats-local.yaml), never from a launch's own arguments; set it there, or leave it out of this spawn; nothing was launched`, { capability: name, setting: perSpawn, host: null });
|
|
308
|
+
if (problems.length) throw refuse(`capability ${name} declares a sandboxDomains this kernel cannot use: ${problems.join("; ")}; nothing was launched`, { capability: name, setting: null, host: null });
|
|
309
|
+
for (const { setting, optional, team, value } of asked) {
|
|
310
|
+
if (value === undefined || value === null || value === "") { missing.push({ capability: name, setting, team, defaultTeam: team === null || team === defaultTeam, ...(optional ? { optional: true } : {}) }); continue; }
|
|
311
|
+
const { host, problem } = sandboxHostOf(value);
|
|
312
|
+
if (!host) throw refuse(`capability ${name} asks to allow the host of its setting ${setting}${team === null ? "" : ` for team ${team}`}, whose value ${problem}; nothing was launched`, { capability: name, setting, host: null, ...(team === null ? {} : { team }) });
|
|
313
|
+
// A host from a map says whose it is: the team's id. The team is one the instance MAY join
|
|
314
|
+
// (a row of the resolution's `teams`), which is not to say it has.
|
|
315
|
+
if (!domains.some((d) => d.host === host)) domains.push({ host, capability: name, setting, ...(team === null ? {} : { team }) });
|
|
316
|
+
}
|
|
317
|
+
// A `settingFile` line: the hosts of a file of the deployment. A path that may not be read
|
|
318
|
+
// from refuses; a file that gives nothing is named, and the launch goes on without its hosts.
|
|
319
|
+
for (const { settingFile: setting, urls } of lines.filter((l) => l.settingFile !== undefined)) {
|
|
320
|
+
const path = isObject(payloads?.[name]) ? payloads[name][setting] : undefined;
|
|
321
|
+
const read = readSettingFileHosts({ path, pointer: urls, within: deployment, outside });
|
|
322
|
+
if (read.refused) throw refuse(`capability ${name} asks to allow the hosts in the file its setting ${setting} names, and ${read.refused}; nothing was launched`, { capability: name, setting, host: null });
|
|
323
|
+
if (read.unread) { unread.push({ capability: name, setting, reason: read.unread }); continue; }
|
|
324
|
+
for (const host of read.hosts) if (!domains.some((d) => d.host === host)) domains.push({ host, capability: name, setting });
|
|
325
|
+
if (read.skippedValues) unread.push({ capability: name, setting, reason: `${read.skippedValues} ${read.skippedValues === 1 ? "value" : "values"} at ${urls} ${read.skippedValues === 1 ? "is" : "are"} no URL with a plain host, and ${read.skippedValues === 1 ? "was" : "were"} skipped` });
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
return { domains, write: [{ path: eventsDir, reason: "oats events" }], missing, ...(skipped.length ? { skipped } : {}), ...(unread.length ? { unread } : {}) };
|
|
329
|
+
}
|
package/lib/schedule.mjs
CHANGED
|
@@ -610,8 +610,8 @@ export function resolveScheduledAgent(ws, def) {
|
|
|
610
610
|
/** The save-time check of a local spawn job's soul (`add`, `update`): refuse what `oats spawn`
|
|
611
611
|
* would refuse. A soul already under the agents root is accepted without a child, so offline
|
|
612
612
|
* adds and stale cached souls stay accepted; any other name goes through spawn's own preview,
|
|
613
|
-
* with the job's selectors (a selector the run needs, such as its repo, would
|
|
614
|
-
* the preview's checks). */
|
|
613
|
+
* with the job's selectors (a selector the run needs, such as its repo or its yolo, would
|
|
614
|
+
* otherwise fail the preview's checks). */
|
|
615
615
|
function confirmScheduledSoul(ws, def, io) {
|
|
616
616
|
const { root, discover } = resolveScheduledAgent(ws, def);
|
|
617
617
|
if (findAgent(root, def.agent)) return;
|
|
@@ -704,7 +704,9 @@ export function workspaceSpawnContext(ws) {
|
|
|
704
704
|
catch (e) { return { kind: "local", local: null, dir: ws, error: { code: e.code || "E_WORKSPACE_SCHEMA", message: e.message } }; }
|
|
705
705
|
}
|
|
706
706
|
/** The `oats spawn` selectors a spawn job's run passes (beside its purpose, task and launch
|
|
707
|
-
*
|
|
707
|
+
* flag), its yolo among them, so a preview checks what the run will: one builder for the run
|
|
708
|
+
* and its previews. (The yolo is the run's own: a session provider's check is asked with the
|
|
709
|
+
* launch that is planned, and one that launches only in full mode refuses a job by it.)
|
|
708
710
|
* Every value travels as ONE `--flag=value` token. */
|
|
709
711
|
function spawnSelectorArgs(opts) {
|
|
710
712
|
const argv = [];
|
|
@@ -713,6 +715,7 @@ function spawnSelectorArgs(opts) {
|
|
|
713
715
|
if (opts.model) argv.push(`--model=${opts.model}`);
|
|
714
716
|
if (opts.backend) argv.push(`--backend=${opts.backend}`);
|
|
715
717
|
if (opts.repo) argv.push(`--repo=${opts.repo}`);
|
|
718
|
+
if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
|
|
716
719
|
return argv;
|
|
717
720
|
}
|
|
718
721
|
/** The kernel's own `oats spawn <agent> --preview --json` in the deployment, with the job's
|
|
@@ -751,7 +754,6 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
|
|
|
751
754
|
// the soul is the one positional, and an option-shaped one is refused.
|
|
752
755
|
if (String(agent.name).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(agent.name)} is not a soul name`, { field: "agent" });
|
|
753
756
|
const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json", ...spawnSelectorArgs(opts)];
|
|
754
|
-
if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
|
|
755
757
|
if (opts.launch === false) argv.push("--no-launch");
|
|
756
758
|
// The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
|
|
757
759
|
mkdirSync(join(stateDir(ws), "tasks"), { recursive: true });
|
package/lib/servers.mjs
CHANGED
|
@@ -37,6 +37,7 @@ import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, read
|
|
|
37
37
|
import { compareSemver } from "./semver.mjs";
|
|
38
38
|
import { SESSION_PROVIDERS_FEATURE, SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
|
|
39
39
|
import { relayedProviderRow, withoutRelayedEndpoint } from "./session-providers.mjs";
|
|
40
|
+
import { readModuleCopy } from "./home-integrity.mjs";
|
|
40
41
|
import { sameRepo } from "./repo-moves.mjs";
|
|
41
42
|
import { OATS_PACKAGE_NAME } from "./version.mjs";
|
|
42
43
|
import { readRemoteBoard } from "./instance-board.mjs";
|
|
@@ -1149,6 +1150,14 @@ const rowBoard = (i) => (Object.hasOwn(i, "board") ? { board: readRemoteBoard(i.
|
|
|
1149
1150
|
/** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
|
|
1150
1151
|
* key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
|
|
1151
1152
|
* only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
|
|
1153
|
+
/** `moduleCopy` (a provider home's: which copy of its modules its kernel runs, and whether the home's
|
|
1154
|
+
* record of them is the receipt's; lib/home-integrity.mjs) as `retire` is: relayed ONLY when the
|
|
1155
|
+
* host's row has the key and this kernel's own read takes its value. A tmux home's row, and a
|
|
1156
|
+
* host whose kernel predates it, say nothing. */
|
|
1157
|
+
const rowModuleCopy = (i) => {
|
|
1158
|
+
const moduleCopy = Object.hasOwn(i, "moduleCopy") ? readModuleCopy(i.moduleCopy) : undefined;
|
|
1159
|
+
return moduleCopy ? { moduleCopy } : {};
|
|
1160
|
+
};
|
|
1152
1161
|
const rowRetire = (i) => {
|
|
1153
1162
|
const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
|
|
1154
1163
|
return retire ? { retire } : {};
|
|
@@ -1271,7 +1280,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
1271
1280
|
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null, ...(relayedProviderRow(i) ?? {}),
|
|
1272
1281
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
1273
1282
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
1274
|
-
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
|
|
1283
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowModuleCopy(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
|
|
1275
1284
|
// Every row the host reports is addressed by its home, saved
|
|
1276
1285
|
// route or not; savedRoute says only that it was spawned from here.
|
|
1277
1286
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
package/lib/session-inspect.mjs
CHANGED
|
@@ -4,12 +4,13 @@
|
|
|
4
4
|
* provider's own answer. A leaf (awebai/oats#1630): `oats session inspect` reads it without loading core.mjs, which
|
|
5
5
|
* imports these helpers and re-exports what it exported. */
|
|
6
6
|
import { realPathOrNearest, canonicalHomePath } from "./real-path.mjs";
|
|
7
|
-
import { existsSync, readFileSync
|
|
8
|
-
import { isAbsolute, join, resolve,
|
|
9
|
-
import {
|
|
7
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
8
|
+
import { isAbsolute, join, resolve, basename } from "node:path";
|
|
9
|
+
import { RETIRE_BASELINE_VERSION, findRetirementBaseline, instancesRetirementRoot, isPlainObject, legacyRetirementBaselinePath, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, retirementBaselinePath } from "./session-receipt.mjs";
|
|
10
10
|
import { inspectSessionTarget } from "./session-input.mjs";
|
|
11
11
|
import { liveWaiting } from "./instance-events.mjs";
|
|
12
12
|
import { oatsError, herdrInstanceRemoved } from "./errors.mjs";
|
|
13
|
+
import { receiptTrust, trustedRecord } from "./home-integrity.mjs";
|
|
13
14
|
import { homeSessionProvider, isSessionProviderName, inspectProviderSession, launchSentOf, providerEndpointDifferences, providerRuntimeOf, unsettledLaunchSaid } from "./session-providers.mjs";
|
|
14
15
|
|
|
15
16
|
/** A cleanup descriptor is usable only if it can DRIVE the retry, so it is checked
|
|
@@ -29,76 +30,6 @@ import { homeSessionProvider, isSessionProviderName, inspectProviderSession, lau
|
|
|
29
30
|
*
|
|
30
31
|
* Anything else reads as ABSENT — no more retryable than a missing marker — so the
|
|
31
32
|
* home fails closed by default and `--force` can clear it. */
|
|
32
|
-
function isPlainObject(v) { return !!v && typeof v === "object" && !Array.isArray(v); }
|
|
33
|
-
|
|
34
|
-
// The stored digests are versioned apart (`digestVersion`, BASELINE_DIGEST_VERSION): this version
|
|
35
|
-
// also gates runtime, directory-home and provider-exclusion authority, so a bump would refuse them all.
|
|
36
|
-
const RETIRE_BASELINE_VERSION = 2;
|
|
37
|
-
|
|
38
|
-
function retirementStateRoot(home) {
|
|
39
|
-
// Independent of the bytes it authenticates, but colocated with the agent's
|
|
40
|
-
// already instance-owned storage rather than the source repository or user
|
|
41
|
-
// config home. Retiring <instances>/<name> never removes this sibling.
|
|
42
|
-
return instancesRetirementRoot(dirname(home));
|
|
43
|
-
}
|
|
44
|
-
/** The retirement state of the homes in the instances directory `instances`. */
|
|
45
|
-
function instancesRetirementRoot(instances) {
|
|
46
|
-
return join(instances, ".oats-retirement");
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
/** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
|
|
50
|
-
* is a symlink is not followed: its parent's on-disk spelling and its name as given (a home
|
|
51
|
-
* exchanged for a symlink is not the home it points at). */
|
|
52
|
-
function receiptHomeIdentity(home) {
|
|
53
|
-
let st;
|
|
54
|
-
try { st = lstatSync(home); } catch { /* not there: spelled as the nearest existing ancestor */ }
|
|
55
|
-
return st && !st.isSymbolicLink() ? canonicalHomePath(home) : join(canonicalHomePath(dirname(home)), basename(home));
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
/** Whether a receipt's recorded home is this home, whatever spelling either was written in.
|
|
59
|
-
* `current` is the home as the caller resolves it for the comparison. */
|
|
60
|
-
function receiptRecordsHome(baseline, current) {
|
|
61
|
-
return typeof baseline?.home === "string" && receiptHomeIdentity(baseline.home) === current;
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
function retirementBaselineFile(identity) {
|
|
65
|
-
return join(retirementStateRoot(identity), "baselines", `${createHash("sha256").update(identity).digest("hex")}.json`);
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
/** Where a spawn writes a home's receipt: keyed by its canonical identity. */
|
|
69
|
-
export function retirementBaselinePath(home) {
|
|
70
|
-
return retirementBaselineFile(receiptHomeIdentity(home));
|
|
71
|
-
}
|
|
72
|
-
|
|
73
|
-
/** Where a kernel before 0.49.0 wrote it: keyed by the parent's realpath in the spawn's own
|
|
74
|
-
* spelling, which on a case-insensitive filesystem need not be the on-disk one. */
|
|
75
|
-
function legacyRetirementBaselinePath(home) {
|
|
76
|
-
return retirementBaselineFile(join(realPathOrNearest(dirname(home)), basename(home)));
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
/** The receipt every reader uses: the canonical one if it exists, else one an earlier kernel left
|
|
80
|
-
* under this caller's spelling, else the canonical path (absent). Read-only: a receipt found at the
|
|
81
|
-
* legacy key is used where it is, never moved, copied or rewritten elsewhere.
|
|
82
|
-
*
|
|
83
|
-
* Limits. A legacy receipt written under spelling S is found only from S, or from the canonical
|
|
84
|
-
* spelling when that is S: a third spelling of such a home misses it (address the home as
|
|
85
|
-
* `oats status` prints it, the spawn's spelling). Receipts outlive retire, so a reused name can
|
|
86
|
-
* leave an earlier incarnation's receipt behind; the canonical one wins, which is right for every
|
|
87
|
-
* home spawned from 0.49.0 on. It is wrong in one case: two incarnations of the same name, both
|
|
88
|
-
* spawned by a kernel before 0.49.0 under different spellings, the earlier one under the canonical
|
|
89
|
-
* spelling. The later home then reads the earlier one's receipt. Its stale endpoint disagrees with
|
|
90
|
-
* instance.json (E_RUNTIME_AUTHORITY_MISMATCH) unless the later incarnation sits at the same
|
|
91
|
-
* endpoint, where session control already targets the right session. Retire finds the home
|
|
92
|
-
* fingerprint changed and preserves the home, less the stale receipt's disposable roots; a
|
|
93
|
-
* directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
|
|
94
|
-
* file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
|
|
95
|
-
* incarnation's. */
|
|
96
|
-
export function findRetirementBaseline(home) {
|
|
97
|
-
const canonical = retirementBaselinePath(home);
|
|
98
|
-
if (existsSync(canonical)) return canonical;
|
|
99
|
-
const legacy = legacyRetirementBaselinePath(home);
|
|
100
|
-
return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
|
|
101
|
-
}
|
|
102
33
|
|
|
103
34
|
/** Herdr (removed in 0.31.0) is recognised in a home only to refuse: its instance.json records a
|
|
104
35
|
* Herdr session target or `backend: "herdr"`, or its independent receipt records a session target
|
|
@@ -107,7 +38,6 @@ function recordsHerdr(meta, baseline) {
|
|
|
107
38
|
return (isPlainObject(meta) && (meta.sessionTarget !== undefined || meta.backend === "herdr"))
|
|
108
39
|
|| (isPlainObject(baseline?.runtime) && baseline.runtime.sessionTarget !== undefined);
|
|
109
40
|
}
|
|
110
|
-
function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } }
|
|
111
41
|
/** Refuse any session operation on a home opened in Herdr, from its files as they are (either may be
|
|
112
42
|
* missing or unreadable): before any receipt validation, so the refusal is never an endpoint error. */
|
|
113
43
|
function refuseHerdrHome(home) {
|
|
@@ -241,10 +171,24 @@ function instanceSessionTarget(home, { absentMeta } = {}) {
|
|
|
241
171
|
if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
|
|
242
172
|
const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
|
|
243
173
|
if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
|
|
174
|
+
// A home that is being spawned: its receipt is there (a directory home's is written before the
|
|
175
|
+
// spawn's hooks run; planned, never launched) and its record is still the one its files were
|
|
176
|
+
// composed with (lib/materialize.mjs: its modules, and no agent, no launch, no backend yet).
|
|
177
|
+
// The spawn's hooks, and a provider's readiness check, run in between. Nothing contradicts
|
|
178
|
+
// anything: the session is not recorded yet, and a read says so (a presence read that a hook
|
|
179
|
+
// sets off lands here on every spawn).
|
|
180
|
+
const composedOnly = meta.agent === undefined && meta.launch === undefined && meta.backend === undefined && meta.tmux === undefined;
|
|
181
|
+
if (composedOnly && (authority.planned ? !authority.planned.launchSent : authority.launched !== true)) {
|
|
182
|
+
// (Whether that spawn still runs is not told here: one that ended before its record reads the same.)
|
|
183
|
+
throw oatsError("E_SESSION_UNAVAILABLE", `${basename(home)} is being spawned, or its spawn ended before its record was written: its session ${authority.planned ? `is planned on ${authority.planned.backend}` : "is planned"}, and its record is not there yet`);
|
|
184
|
+
}
|
|
244
185
|
if (!launchStateAgrees(meta, authority) || !endpointAgrees(meta, authority)) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
|
|
245
186
|
// `unsettled`: a launch that was sent to the home's provider and never recorded, whether the home
|
|
246
187
|
// was launched before or not: `{ backend, provider, launchSent }`, or null. The one place that says so.
|
|
247
188
|
const recorded = authority.session ?? authority.planned ?? null;
|
|
189
|
+
// A provider home's capability rows (settings, hook commands) are its receipt's, never its own
|
|
190
|
+
// record's, which its agent can write (lib/home-integrity.mjs): every verb reads them here.
|
|
191
|
+
meta = trustedRecord(meta, receiptTrust(baseline, home));
|
|
248
192
|
return { home, target: authority.tmux ? { backend: "tmux", ...authority.tmux } : undefined, meta,
|
|
249
193
|
...(authority.session ? { session: authority.session } : {}), ...(authority.planned ? { planned: authority.planned } : {}),
|
|
250
194
|
unsettled: recorded?.launchSent ? { backend: recorded.backend, provider: recorded.provider, launchSent: recorded.launchSent } : null };
|
|
@@ -317,4 +261,5 @@ export function inspectInstanceSession(home, { io, absentMeta } = {}) {
|
|
|
317
261
|
* fallback shell nor a dead pane. Only such a session can be waiting on a human. */
|
|
318
262
|
function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
|
|
319
263
|
|
|
320
|
-
|
|
264
|
+
// (The receipt's own primitives are lib/session-receipt.mjs's, exported here as they were.)
|
|
265
|
+
export { RETIRE_BASELINE_VERSION, findRetirementBaseline, retirementBaselinePath, authorityMismatch, endpointAgrees, harnessRunning, providerHomeOf, providerMayWait, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };
|