@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/remote.mjs
CHANGED
|
@@ -139,6 +139,11 @@
|
|
|
139
139
|
* unref'd while idle and ended by session.close();
|
|
140
140
|
* - `maxAge` (seconds): > 0 lets observeRemote reuse a recorded head observation
|
|
141
141
|
* (the observation store below) no older than that;
|
|
142
|
+
* - `offline` (true): the session NEVER reaches a remote. A head is the one this host last
|
|
143
|
+
* observed (its record, of any age); a commit, a tree and a file are read only when the cache
|
|
144
|
+
* holds them. Whatever is not there is E_REMOTE_UNREADABLE { reason: "not-cached" } naming the
|
|
145
|
+
* repository: no ls-remote and no fetch is ever run, and nothing is recorded. What it reads is
|
|
146
|
+
* the configuration as this host last read it (OFFLINE, below);
|
|
142
147
|
* - the head observations used, for the `observation` output block;
|
|
143
148
|
* - `deadline` (DEADLINE; the deployment reads `oats status` and `oats workspace status` only, READ_REMOTE_BUDGET_MS
|
|
144
149
|
* after their session starts): every remote step gets what is left of it, not its own default — each git call's
|
|
@@ -164,6 +169,13 @@
|
|
|
164
169
|
* under `maxAge`, only when key, ref args and urlDigest all match, and never in place of
|
|
165
170
|
* a live observation that failed.
|
|
166
171
|
*
|
|
172
|
+
* OFFLINE (`createReadSession({ offline: true })`): for a read that must not depend on the network
|
|
173
|
+
* or change with it (the sandbox allowances of a session provider's start: lib/instance-resolution.mjs
|
|
174
|
+
* homeSandboxSource). Its three refusals, each before any git process that could reach a remote:
|
|
175
|
+
* a head never observed on this host (observeInSession), a commit the cache does not hold
|
|
176
|
+
* (ensureCommit), a file whose blob the cache does not hold (ensureBlobs). Local git reads of the
|
|
177
|
+
* cache (peel, ls-tree, cat-file) are what they always are.
|
|
178
|
+
*
|
|
167
179
|
* VERIFIED STORE (`treeVerification`; kernel-private, not a contract):
|
|
168
180
|
* `<cacheRoot>/.verified/<sha256([key, commit, dir, digest])>.json` records that the tree `dir` of
|
|
169
181
|
* (repo key, commit), read from this cache, had the content digest `digest`:
|
|
@@ -1080,8 +1092,10 @@ function pinRef(oid) { return `refs/oats/commits/${oid}`; }
|
|
|
1080
1092
|
|
|
1081
1093
|
class ReadSession {
|
|
1082
1094
|
constructor({ maxAge = 0, now = Date.now, fingerprint = null, treeIndexBudget = TREE_INDEX_BUDGET, parsedLimits = null, batchTimeoutMs = GIT_TIMEOUT_MS,
|
|
1083
|
-
cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null, v0AdvertisementBudget = V0_ADVERTISEMENT_BUDGET } = {}) {
|
|
1095
|
+
cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null, v0AdvertisementBudget = V0_ADVERTISEMENT_BUDGET, offline = false } = {}) {
|
|
1084
1096
|
if (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > MAX_AGE_LIMIT) throw new TypeError(`maxAge must be an integer from 0 to ${MAX_AGE_LIMIT}`);
|
|
1097
|
+
if (typeof offline !== "boolean") throw new TypeError("offline must be true or false");
|
|
1098
|
+
this.offline = offline; // never reach a remote: the module header's OFFLINE
|
|
1085
1099
|
if (deadline !== null && !Number.isFinite(deadline)) throw new TypeError("deadline must be null or a time in Date.now() milliseconds");
|
|
1086
1100
|
this.maxAge = maxAge;
|
|
1087
1101
|
this.now = now;
|
|
@@ -1187,6 +1201,11 @@ class ReadSession {
|
|
|
1187
1201
|
* `fingerprint`, `treeIndexBudget`, `parsedLimits`, `batchTimeoutMs`, `cacheWriteWaitMs`, `fetchTimeoutMs`,
|
|
1188
1202
|
* `v0AdvertisementBudget`. */
|
|
1189
1203
|
export function createReadSession(options = {}) { return new ReadSession(options); }
|
|
1204
|
+
/** What an offline session (the module header's OFFLINE) answers for what this host's cache does not
|
|
1205
|
+
* hold: the repository is named, and nothing was asked of it. */
|
|
1206
|
+
function notCached(ref, what, extra = {}) {
|
|
1207
|
+
return fail("E_REMOTE_UNREADABLE", `cannot read ${displayRepoRef(ref.url)} without reaching it: ${what}. Any oats command that reads the workspace (oats status, oats spawn --preview) brings it to this host`, { url: ref.url, key: ref.key, reason: "not-cached", ...extra });
|
|
1208
|
+
}
|
|
1190
1209
|
/** An observation the command no longer wants (its session closed, or its prefetch abandoned): never adopted
|
|
1191
1210
|
* by a caller that is still reading, so its shape only has to be a typed remote failure. */
|
|
1192
1211
|
function abandonedError() {
|
|
@@ -1599,6 +1618,8 @@ async function ensureCommit(ref, oid, options) {
|
|
|
1599
1618
|
};
|
|
1600
1619
|
const present = await usable(repoHandle(dir, options.exec ?? runGit, session));
|
|
1601
1620
|
if (present) return { repo: repoHandle(dir, options.exec ?? runGit, session), commit: remember(present) };
|
|
1621
|
+
// Offline: what the cache does not hold is not fetched.
|
|
1622
|
+
if (session?.offline) throw notCached(ref, `this host's cache does not hold its commit ${oid}`, { commit: oid });
|
|
1602
1623
|
// Every write below (init, config, fetch, pin) holds the cache's cross-process write lock; a process that
|
|
1603
1624
|
// waited for it finds what the holder fetched.
|
|
1604
1625
|
return withCacheWriteLock(ref, dir, "fetch", session, async ({ waited }) => {
|
|
@@ -1878,6 +1899,7 @@ const fetchFailure = (repo, ref, error, commit) => unreadable(ref, error, { comm
|
|
|
1878
1899
|
* a caller that reads it). Every fetch first removes the temporary files earlier fetches left in the object
|
|
1879
1900
|
* store, by their age (removeStaleTemporaryFiles). → { stdout, stderr } */
|
|
1880
1901
|
async function fetchInto(repo, ref, args, { what, commit, input, raw = false } = {}) {
|
|
1902
|
+
if (repo.session?.offline) throw notCached(ref, `this read never fetches${commit ? ` (commit ${commit})` : ""}`, commit ? { commit } : {});
|
|
1881
1903
|
const started = Date.now();
|
|
1882
1904
|
removeStaleTemporaryFiles(repo);
|
|
1883
1905
|
let lastError;
|
|
@@ -1917,6 +1939,8 @@ async function ensureBlobs(repo, ref, commit, entries) {
|
|
|
1917
1939
|
await withCacheLock(repo.dir, async () => {
|
|
1918
1940
|
let sizes = await blobSizes(repo, oids); // another read may have fetched them meanwhile
|
|
1919
1941
|
let wanted = oids.filter((o) => sizes.get(o) === null);
|
|
1942
|
+
// Offline: a file the cache does not hold is not fetched.
|
|
1943
|
+
if (wanted.length && repo.session?.offline) throw notCached(ref, `this host's cache does not hold ${wanted.length === 1 ? "a file" : `${wanted.length} files`} of its commit ${commit}`, { commit });
|
|
1920
1944
|
if (wanted.length) await withCacheWriteLock(ref, repo.dir, "fetch", repo.session, async ({ waited }) => {
|
|
1921
1945
|
if (waited) { // another process may have fetched them while this one waited
|
|
1922
1946
|
sizes = await blobSizes(repo, oids);
|
|
@@ -2079,6 +2103,13 @@ async function observeInSession(ref, args, at, options, session, prefetch = null
|
|
|
2079
2103
|
try {
|
|
2080
2104
|
// A prefetch given up while it queued (or a session closed meanwhile) runs no git at all.
|
|
2081
2105
|
if (session.closed || prefetch?.abandoned) throw abandonedError();
|
|
2106
|
+
if (session.offline) {
|
|
2107
|
+
// The head this host last observed, of any age, when the cache still holds it: never a live one.
|
|
2108
|
+
const record = readObservation(root, ref, atArgs, session, { anyAge: true });
|
|
2109
|
+
if (!record) throw notCached(ref, "this host has not observed it yet");
|
|
2110
|
+
const reused = { key: ref.key, url: ref.url, commit: record.commit, ref: record.ref, observedAt: record.observedAt, reused: true };
|
|
2111
|
+
return { ...reused, commit: (await ensureCommit(ref, record.commit, options)).commit };
|
|
2112
|
+
}
|
|
2082
2113
|
if (session.maxAge > 0) {
|
|
2083
2114
|
const record = readObservation(root, ref, atArgs, session);
|
|
2084
2115
|
if (record) {
|
|
@@ -2160,6 +2191,7 @@ const V0_FINAL_REASONS = new Set(["timeout", "auth", "not-found", "cache"]);
|
|
|
2160
2191
|
async function observeLive(ref, args, at, options) {
|
|
2161
2192
|
const exec = options.exec ?? runGit;
|
|
2162
2193
|
const session = sessionOf(options);
|
|
2194
|
+
if (session?.offline) throw notCached(ref, "this read never observes a remote");
|
|
2163
2195
|
const signal = session?.signal;
|
|
2164
2196
|
// Every git call takes what is left of the session's deadline, if it has one (sessionExec).
|
|
2165
2197
|
const run = (argv, extra = {}) => sessionExec(exec, session, argv, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}), ...extra });
|
|
@@ -21,4 +21,11 @@ export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME
|
|
|
21
21
|
// lib/system-tools.mjs).
|
|
22
22
|
"OATS_TEST_CGROUP", "OATS_TEST_SYSTEMD_BOOTED", "OATS_TEST_SYSTEM_TOOL_DIRS",
|
|
23
23
|
// The test seam of #1421 §3: the naming call's time limit (lib/instance-naming.mjs NAMING_TIMEOUT_MS).
|
|
24
|
-
"OATS_TEST_NAMING_TIMEOUT_MS"
|
|
24
|
+
"OATS_TEST_NAMING_TIMEOUT_MS",
|
|
25
|
+
// The test seams of the session-provider contract: the timeout of every provider call
|
|
26
|
+
// (lib/session-providers.mjs sessionProviderTimeout) and how long a lost session's resume waits
|
|
27
|
+
// for its last run's processes to leave the home (lib/provider-resume.mjs resumeQuietWait). Each
|
|
28
|
+
// only shortens: a value above the kernel's own limit is that limit.
|
|
29
|
+
"OATS_TEST_SESSION_PROVIDER_TIMEOUT_MS", "OATS_TEST_PROVIDER_RESUME_WAIT_MS",
|
|
30
|
+
// The test seam of a provider home's write orders: the point at which the kernel dies (lib/core.mjs dieAt).
|
|
31
|
+
"OATS_TEST_PROVIDER_DIE_AT", "OATS_TEST_PROVIDER_LEADER_DELAY_MS", "OATS_TEST_PROVIDER_KILL_KERNEL"]);
|
package/lib/retire-admission.mjs
CHANGED
|
@@ -4,6 +4,8 @@ import { existsSync, readFileSync } from "node:fs";
|
|
|
4
4
|
import { join } from "node:path";
|
|
5
5
|
import { directoryRollbackPath, isCapturedHome, readHomeRecord, unreadableRecordSaid } from "./instance-listing.mjs";
|
|
6
6
|
import { isPlainObject } from "./session-inspect.mjs";
|
|
7
|
+
import { recordsSessionProvider } from "./session-providers.mjs";
|
|
8
|
+
import { providerHomeTrust } from "./home-integrity.mjs";
|
|
7
9
|
import { processLiveness } from "./worktree-hooks.mjs";
|
|
8
10
|
import { lifecycleBusy, oatsError } from "./errors.mjs";
|
|
9
11
|
|
|
@@ -160,7 +162,16 @@ export function retireCleanupAdmission(home, name, { force = false } = {}, readW
|
|
|
160
162
|
// Compensation metadata is the SPAWN's, from whichever record survived — never
|
|
161
163
|
// a failed retry's report, which says nothing about what still needs undoing.
|
|
162
164
|
if (!liveMeta?.capabilityMeta && quarantine?.cleanup?.capabilityMeta) meta.capabilityMeta = quarantine.cleanup.capabilityMeta;
|
|
163
|
-
|
|
165
|
+
// A provider home's capability rows (which retire hooks it owes, and their commands) are its
|
|
166
|
+
// receipt's, never its own record's or its rollback marker's, which its agent can write
|
|
167
|
+
// (lib/home-integrity.mjs). A receipt with no composition leaves none: the hooks cannot be
|
|
168
|
+
// identified, and the retire says so as for a home that records none.
|
|
169
|
+
const trust = providerHomeTrust(home);
|
|
170
|
+
if (trust) { if (trust.composition) meta.capabilityRuntime = trust.composition.capabilityRuntime; else delete meta.capabilityRuntime; }
|
|
171
|
+
// A home on a session provider keeps what its own record says of its launch: its receipt is the
|
|
172
|
+
// authority for it, and a rollback marker is written `launched: false` whatever the provider had
|
|
173
|
+
// answered by then, which would set the record against the receipt and refuse every retire.
|
|
174
|
+
if (quarantine && typeof quarantine.cleanup.launched === "boolean" && !recordsSessionProvider(liveMeta)) {
|
|
164
175
|
meta.launched = quarantine.cleanup.launched;
|
|
165
176
|
meta.tmux = quarantine.cleanup.tmux;
|
|
166
177
|
meta.sessionTarget = quarantine.cleanup.sessionTarget;
|
|
@@ -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
|
@@ -35,6 +35,7 @@ import { herdrSettingRemoved } from "./errors.mjs";
|
|
|
35
35
|
import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
|
|
36
36
|
import { pollSourced, tickTriggers } from "./triggers.mjs";
|
|
37
37
|
import { SCHEDULE_NAME_RE, HOST_NAME_RE, readSnapshot, hostOf, trusted, parseOwner, MODEL_RE, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
|
|
38
|
+
import { SESSION_PROVIDER_NAME_RE } from "./kernel-features.mjs";
|
|
38
39
|
import { MAX_INSTANCE_NAME, shq, shellWord, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, sessionServerGone, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
|
|
39
40
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
40
41
|
import { readStartExited } from "./session-end.mjs";
|
|
@@ -487,7 +488,9 @@ export function validateDefinition(ws, def, { checkAgent = true, backendSource,
|
|
|
487
488
|
}
|
|
488
489
|
if (def.repo !== undefined) { if (typeof def.repo !== "string" || !def.repo.trim() || def.repo.startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "repo: the work repository path, as oats spawn --repo", { field: "repo" }); out.repo = def.repo; }
|
|
489
490
|
if (def.backend === "herdr") throw herdrBackendRefusal(backendSource ?? `${definitionsPath(ws)} sets jobs.${id}.backend`);
|
|
490
|
-
|
|
491
|
+
// tmux, or a session provider of the soul's capabilities (lib/session-providers.mjs): a name here;
|
|
492
|
+
// the run's spawn resolves it against the instance's modules (E_BACKEND_UNKNOWN, E_BACKEND_HARNESS).
|
|
493
|
+
if (def.backend !== undefined) { if (typeof def.backend !== "string" || !SESSION_PROVIDER_NAME_RE.test(def.backend)) throw scheduleError("E_SCHEDULE_INVALID", "backend: tmux, or a session provider's name (1 to 40 lowercase letters, digits and dashes)", { field: "backend" }); out.backend = def.backend; }
|
|
491
494
|
if (def.purpose !== undefined) { if (typeof def.purpose !== "string" || !/^[a-z0-9-]{1,40}$/.test(def.purpose)) throw scheduleError("E_SCHEDULE_INVALID", "purpose: lowercase letters, digits and dashes", { field: "purpose" }); out.purpose = def.purpose; }
|
|
492
495
|
// A run spawns <agent>-<purpose|id>-<YYYYMMDDHHMM>; instance names are at most
|
|
493
496
|
// MAX_INSTANCE_NAME characters, so refuse here what would fail at every firing.
|
|
@@ -646,8 +649,12 @@ export function observeHome(home, io) {
|
|
|
646
649
|
const retiring = existsSync(retirePendingMarkerPath(home));
|
|
647
650
|
try {
|
|
648
651
|
const s = (io?.inspect || inspectInstanceSession)(home);
|
|
649
|
-
|
|
652
|
+
// A home on a session provider (its inspect answer carries `session`): a wake never starts it
|
|
653
|
+
// (performWake). Its session in error (`shell`) is no startup phase: an input recovers it.
|
|
654
|
+
const provider = s.session !== undefined && s.session !== null ? { provider: true } : {};
|
|
655
|
+
if (s.present && s.state !== "shell") return { outcome: "active", ...provider, ...(retiring ? { note: "retiring" } : {}) };
|
|
650
656
|
if (retiring) return { outcome: "active", note: "retiring: home present, teardown pending" };
|
|
657
|
+
if (provider.provider) return { outcome: "stopped", ...provider };
|
|
651
658
|
// A shell right after `session start` is that launch's startup phase
|
|
652
659
|
// until its wrapper writes the exit marker for the launch id; only then
|
|
653
660
|
// (or with no start receipt at all) is a shell a finished harness.
|
|
@@ -915,7 +922,10 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve,
|
|
|
915
922
|
if (seen.outcome === "ended") return { kind: "wake", action: "skipped", reason: "home is gone", pending: false };
|
|
916
923
|
if (seen.outcome === "unknown") return { kind: "wake", action: "skipped", reason: `cannot observe the session: ${seen.error}`, pending: true };
|
|
917
924
|
if (seen.outcome === "starting") return { kind: "wake", action: "skipped", reason: "session is starting; delivery pending", pending: true };
|
|
918
|
-
|
|
925
|
+
// A home on a session provider is never started by a wake: the wake is its session's input, which
|
|
926
|
+
// the kernel refuses (E_SESSION_NOT_RUNNING, before any provider call) for a home OATS stopped,
|
|
927
|
+
// and which the provider answers for any other.
|
|
928
|
+
if (seen.outcome === "stopped" && !seen.provider) {
|
|
919
929
|
if (!startIfStopped) return { kind: "wake", action: "skipped", reason: "session stopped; it is started again only at the next due minute; delivery pending", pending: true };
|
|
920
930
|
if (!canStart) return { kind: "wake", action: "skipped", reason: "host busy: starting this session needs a launch slot; delivery pending", pending: true };
|
|
921
931
|
// The slot is persisted BEFORE the start call and kept on a start
|
|
@@ -945,7 +955,7 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve,
|
|
|
945
955
|
// Delivery custody: name the instance ONLY when the input result names it; the home's current incarnation at record time.
|
|
946
956
|
return { kind: "wake", action: "delivered", pending: false, ...(typeof r?.instance === "string" ? { instance: r.instance } : {}), home: def.home, incarnation: incarnationOfHome(def.home) };
|
|
947
957
|
}
|
|
948
|
-
catch (e) { return { kind: "wake", action: "skipped", reason: `input refused: ${e.message}`, pending: true }; }
|
|
958
|
+
catch (e) { return { kind: "wake", action: "skipped", reason: `input refused: ${e.message}`, ...(seen.provider && typeof e?.code === "string" ? { errorCode: e.code } : {}), pending: true }; }
|
|
949
959
|
}
|
|
950
960
|
|
|
951
961
|
/** A held run as the tick records it: `held.since` is the first skip's time, kept on
|