@awebai/oats 0.69.23 → 0.69.24
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 +56 -17
- package/docs/capabilities.md +353 -5
- package/docs/capability-manifest.schema.json +36 -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 +320 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +257 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +5 -1
- 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/souls-and-instances.md +45 -0
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +13 -5
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1176 -181
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +97 -8
- 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/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +28 -4
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/lib/errors.mjs
CHANGED
|
@@ -78,11 +78,14 @@ const SPAWN_REFUSAL_DETAILS = Object.freeze({
|
|
|
78
78
|
});
|
|
79
79
|
const spawnFailedDetails = (e) => (e?.details?.unconfirmed === true ? e.details : undefined);
|
|
80
80
|
/** The `details` of the answer to an error `e` of `oats spawn` (bin/oats.mjs spawnFail): the table's
|
|
81
|
-
* for a code it holds, a launch refusal's own (`E_LAUNCH_…`),
|
|
81
|
+
* for a code it holds, a launch refusal's own (`E_LAUNCH_…`), a session backend's (`E_BACKEND_…`), else
|
|
82
|
+
* spawnFailedDetails. */
|
|
82
83
|
export function spawnRefusalDetails(e) {
|
|
83
84
|
const code = kernelCode(e, null);
|
|
84
85
|
if (code && Object.hasOwn(SPAWN_REFUSAL_DETAILS, code)) return SPAWN_REFUSAL_DETAILS[code](e);
|
|
85
86
|
if (code?.startsWith("E_LAUNCH_")) return e.details;
|
|
87
|
+
// A session backend's refusal (lib/session-providers.mjs): the backend, and what it names.
|
|
88
|
+
if (code?.startsWith("E_BACKEND_")) return e.details;
|
|
86
89
|
return spawnFailedDetails(e);
|
|
87
90
|
}
|
|
88
91
|
/** `e` as a kernel error. One whose code an answer carries (isAnswerCode) is returned as it is. Any other is wrapped:
|
package/lib/hook-env.mjs
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/** The environment a capability's code runs with in an instance home (docs/capabilities.md, Commands
|
|
2
|
+
* and hooks): one builder for every lifecycle hook and for a session provider's commands
|
|
3
|
+
* (lib/session-providers.mjs), with the soul, team and kernel facts it is built from. A leaf: the
|
|
4
|
+
* hot reads (lib/hot-reads.mjs: `session inspect`, `status`) call a session provider without
|
|
5
|
+
* loading core.mjs, which imports these and re-exports what it exported. */
|
|
6
|
+
import { readFileSync, realpathSync } from "node:fs";
|
|
7
|
+
import { isAbsolute, join } from "node:path";
|
|
8
|
+
import { kernelNode } from "./stable-node.mjs";
|
|
9
|
+
import { teamsEnv } from "./teams.mjs";
|
|
10
|
+
import { PKG_ROOT } from "./version.mjs";
|
|
11
|
+
|
|
12
|
+
/** The canonical path of this kernel's CLI: what the home's shim points at, and OATS_CLI_BIN. */
|
|
13
|
+
export function kernelBin() { return realpathSync(join(PKG_ROOT, "bin", "oats.mjs")); }
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* A soul's STABLE identity for capability hooks (OATS_SOUL_ID): what a provider
|
|
17
|
+
* may key durable state on. Workspace soul: `<repo key>#<soul name>` — it does not
|
|
18
|
+
* change when the member commits (the per-commit soul directory does) or when the
|
|
19
|
+
* copy moves. Classic soul: the realpath of agents/<name>/soul, i.e. today's value,
|
|
20
|
+
* so 0.24 deployments are unchanged. Order: an explicit `soulId` (a prepared spawn),
|
|
21
|
+
* the home's recorded `instance.json.workspace.soul` (retire/launch of a workspace
|
|
22
|
+
* home), else the path.
|
|
23
|
+
*/
|
|
24
|
+
export function stableSoulId({ soulId, home, soulDir, agentName } = {}) {
|
|
25
|
+
if (typeof soulId === "string" && soulId) return soulId;
|
|
26
|
+
if (home) {
|
|
27
|
+
try {
|
|
28
|
+
const meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
|
|
29
|
+
const s = meta?.workspace?.soul;
|
|
30
|
+
if (typeof s?.id === "string" && s.id) return s.id;
|
|
31
|
+
if (typeof s?.repoKey === "string" && s.repoKey) return `${s.repoKey}#${meta.agent ?? agentName ?? ""}`;
|
|
32
|
+
} catch { /* not a workspace home */ }
|
|
33
|
+
}
|
|
34
|
+
if (soulDir) { try { return realpathSync(soulDir); } catch { return soulDir; } }
|
|
35
|
+
return "";
|
|
36
|
+
}
|
|
37
|
+
/** The soul directory an instance incarnates, as spawn recorded it (instance.json
|
|
38
|
+
* `soulDir`): a workspace soul's per-commit copy (agents/<soul>/souls/<commit12>) or
|
|
39
|
+
* the read-only soul inside a capability package. It is what every classic
|
|
40
|
+
* lifecycle hook and dispatched command sees as OATS_SOUL (captured hooks set
|
|
41
|
+
* none); instance homes carry no soul link. */
|
|
42
|
+
export function instanceSoulDir(home, meta = undefined) {
|
|
43
|
+
if (meta === undefined && home) { try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); } catch { meta = null; } }
|
|
44
|
+
return typeof meta?.soulDir === "string" && isAbsolute(meta.soulDir) ? meta.soulDir : undefined;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The team and workspace facts a lifecycle hook, command or provider check receives (workspace
|
|
48
|
+
* model only, lead decision c3-7): OATS_TEAM_SCOPE is the deployment directory; OATS_WORKSPACE_NAME /
|
|
49
|
+
* _KEY the workspace's name and canonical key; OATS_TEAM_NAME (the 0.25 `team:` block's name) is always
|
|
50
|
+
* empty, so an ambient value never reaches a hook.
|
|
51
|
+
*
|
|
52
|
+
* Team model v2 (docs/desktop-cli-api.md, The provider environment): `resolved.teams` are the soul's
|
|
53
|
+
* TeamRows here and `resolved.defaultTeam` its DefaultTeam; teamsEnv sets OATS_DEFAULT_TEAM(_ID,_FROM),
|
|
54
|
+
* OATS_TEAMS (mapped rows only) and OATS_TEAMS_SOURCE (`live`: the workspace + oats-local.yaml read now,
|
|
55
|
+
* or a fresh resolution; `recorded`: the spawn-time record). A provider LEAVES a joined team only on a
|
|
56
|
+
* `live` list. Teams not known (`resolved.teams` not an array): every team name unset. */
|
|
57
|
+
export function teamEnv(resolved) {
|
|
58
|
+
const ws = resolved?.workspace && typeof resolved.workspace === "object" ? resolved.workspace : {};
|
|
59
|
+
const known = Array.isArray(resolved?.teams);
|
|
60
|
+
return {
|
|
61
|
+
OATS_TEAM_NAME: "", OATS_TEAM_SCOPE: typeof ws.deployment === "string" ? ws.deployment : "",
|
|
62
|
+
...teamsEnv(known ? { teams: resolved.teams, defaultTeam: resolved.defaultTeam ?? null, source: resolved.teamsSource } : null),
|
|
63
|
+
OATS_WORKSPACE_NAME: typeof ws.name === "string" ? ws.name : "", OATS_WORKSPACE_KEY: typeof ws.key === "string" ? ws.key : "",
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
export function withoutAmbientHookFacts(env) {
|
|
67
|
+
const { OATS_LAUNCH_PREVIEW: _ambient, OATS_HARNESS_EXECUTABLE: _inherited, OATS_SPAWNER_HOME: _spawner, ...rest } = env;
|
|
68
|
+
return rest;
|
|
69
|
+
}
|
|
70
|
+
/** The environment one capability's lifecycle hook runs with: the invoker's own
|
|
71
|
+
* (inherited, as for every hook; the kernel adds no credentials), plus the
|
|
72
|
+
* standard OATS_* variables (docs/capabilities.md, Commands and hooks) and the
|
|
73
|
+
* caller's `extraEnv`. One builder for every event, so the `worktree` runner
|
|
74
|
+
* (lib/worktree-hooks.mjs) hands its hooks exactly what every other hook gets. */
|
|
75
|
+
export function lifecycleHookEnv(event, cap, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
|
|
76
|
+
return {
|
|
77
|
+
// OATS_LAUNCH_PREVIEW is the kernel's to give (prepareLaunchHooks), never
|
|
78
|
+
// inherited: a real start's hook must not read an ambient one as a preview.
|
|
79
|
+
// Nor are OATS_HARNESS_EXECUTABLE and OATS_SPAWNER_HOME (spawn's
|
|
80
|
+
// callerSpawner): a hook started from inside an instance must not read its caller's.
|
|
81
|
+
...withoutAmbientHookFacts(process.env),
|
|
82
|
+
// OATS_INSTANCE_HOME is the runtime-neutral contract name for the
|
|
83
|
+
// instance home (absolute). OATS_HOME predates it and stays as a
|
|
84
|
+
// compatibility alias: shipped capability hooks read it
|
|
85
|
+
// (the official oats.aweb and oats.okf packages) and are versioned
|
|
86
|
+
// independently of this kernel. Neither is OATS_HOME_DIR, which is
|
|
87
|
+
// the package STORE root — do not conflate them.
|
|
88
|
+
OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
|
|
89
|
+
OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
|
|
90
|
+
OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
|
|
91
|
+
...teamEnv(resolved),
|
|
92
|
+
...extraEnv,
|
|
93
|
+
// Hooks also run through direct core callers (not only bin/oats).
|
|
94
|
+
// Author this from the running kernel, never PATH, ambient env or
|
|
95
|
+
// a caller's extraEnv: those may point at a different executable.
|
|
96
|
+
OATS_CLI_BIN: kernelBin(),
|
|
97
|
+
// The node a capability writes into anything that outlives its hook (lib/stable-node.mjs).
|
|
98
|
+
OATS_NODE_BIN: kernelNode().node,
|
|
99
|
+
OATS_SETTINGS: JSON.stringify(cap.settings || {}),
|
|
100
|
+
// Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
|
|
101
|
+
// manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
|
|
102
|
+
// soul-set value from a host-set one. {} when the home recorded none (spawned before 0.29).
|
|
103
|
+
OATS_SETTINGS_ORIGINS: JSON.stringify(cap.settingsOrigins || {}),
|
|
104
|
+
OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
|
|
105
|
+
};
|
|
106
|
+
}
|
package/lib/host-run.mjs
CHANGED
|
@@ -107,7 +107,8 @@ function sweepSaid(rows) {
|
|
|
107
107
|
* On the signal, in this order: no minute is armed any more; a tick or a sweep that runs is
|
|
108
108
|
* given 10 s to finish, then new admissions are fenced and owned children are cancelled
|
|
109
109
|
* within a further 5 s (a tick's wake job may start a home, so owned work ends before any
|
|
110
|
-
* home is stopped); one bounded listing; then every running home
|
|
110
|
+
* home is stopped); one bounded listing; then every running home, and every home on a session provider that OATS has
|
|
111
|
+
* not stopped (its session idle or in error included), is stopped, side by side, each by a child of its
|
|
111
112
|
* own (lib/host-stop-child.mjs: the stop `oats session restart` and a retire use, its record
|
|
112
113
|
* written first and asking for a resume, the harness given `stopGraceMs` and never escalated).
|
|
113
114
|
* The next start's sweep resumes those homes.
|
|
@@ -176,7 +177,10 @@ export async function hostRun({
|
|
|
176
177
|
// minute missed while this process did not run is never armed again.
|
|
177
178
|
const ticks = { run: 0, skipped: 0, failed: 0, noScope: 0 };
|
|
178
179
|
let ticking = null, sweeping = null, ticked;
|
|
179
|
-
|
|
180
|
+
// The shutdown's listing asks no session provider: it must answer within its few seconds while
|
|
181
|
+
// the host, and a provider's own server with it, go down. It needs no provider's answer: the
|
|
182
|
+
// stop covers every provider home OATS has not stopped, whatever its session reads.
|
|
183
|
+
const list = (options) => execute(["session", "resume", "--plan", "--without-provider-inspect", "--json"], options);
|
|
180
184
|
const arm = () => { disarm = timer(minute, MINUTE - (now() % MINUTE)); };
|
|
181
185
|
const minute = () => {
|
|
182
186
|
if (signal) return;
|
|
@@ -213,7 +217,11 @@ export async function hostRun({
|
|
|
213
217
|
await Promise.all([ticking, sweeping]);
|
|
214
218
|
const last = await list({ timeoutMs: 3000 });
|
|
215
219
|
if (last?.ok !== true) say(`listing failed ${failed(last)}: no instance is stopped`);
|
|
216
|
-
|
|
220
|
+
// Every running home, and every home on a session provider the listing answered (its row carries
|
|
221
|
+
// `backend`), idle or in error included: a provider restarts such a session on its next input,
|
|
222
|
+
// so the stop is what keeps input refused while the host goes down. A provider home OATS
|
|
223
|
+
// already stopped is idle for the stop, which changes nothing of it.
|
|
224
|
+
const homes = last?.ok === true ? (last.result?.rows ?? []).filter((row) => (row.outcome === OUTCOME.ALREADY_RUNNING || typeof row.backend === "string") && typeof row.home === "string").map((row) => row.home) : [];
|
|
217
225
|
if (homes.length) say(`stopping ${plural(homes.length, "running instance")}, each given ${stopGraceMs / 1000} s`);
|
|
218
226
|
// Side by side: each stop waits for its own harness, and the host's patience is one span for all.
|
|
219
227
|
const stopped = await Promise.all(homes.map(async (home) => {
|
package/lib/instance-inspect.mjs
CHANGED
|
@@ -34,6 +34,7 @@ import { readInstancePin } from "./instance-pin.mjs";
|
|
|
34
34
|
/** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
|
|
35
35
|
const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
|
|
36
36
|
import { parseStrictJson } from "./canonical-json.mjs";
|
|
37
|
+
import { checkProviderSession, homeSessionProvider, offeredSessionProviders, sessionProvidersOf } from "./session-providers.mjs";
|
|
37
38
|
import { sameRepo } from "./repo-moves.mjs";
|
|
38
39
|
import { kernelNode } from "./stable-node.mjs";
|
|
39
40
|
|
|
@@ -524,6 +525,9 @@ export function inspectDocument(t, { kernel }) {
|
|
|
524
525
|
return {
|
|
525
526
|
operationsApi: INSPECT_OPERATIONS_API, kernel, subject: t.subject, workspace: t.workspace,
|
|
526
527
|
souls: [soulRow(t)], layers, capabilities,
|
|
528
|
+
// Feature session-providers: the session backends this soul's (or home's) capabilities supply
|
|
529
|
+
// beside the kernel's own, what `--backend` takes here: [{ name, capability }].
|
|
530
|
+
...sessionProviderKeys(t),
|
|
527
531
|
// The capabilities the soul turned off (feature desktop-facts): its `off` over a workspace/team entry
|
|
528
532
|
// (reason "off"), or a `<slot>: none` that dropped a workspace default (reason "slot-none", slot).
|
|
529
533
|
capabilitiesOff: (t.turnedOff || []).map(({ name, reason, slot, overrides }) => ({ id: name, off: true, from: "soul", reason, ...(slot ? { slot } : {}), overrides })),
|
|
@@ -674,6 +678,14 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
|
|
|
674
678
|
({ subject, status, required, reason: bounded(reason), producer, evidence, remedy: bounded(remedy), ...rest,
|
|
675
679
|
...(Array.isArray(rest.problems) ? { problems: rest.problems.map((p) => (obj(p) && typeof p.message === "string" ? { ...p, message: bounded(p.message) } : p)) } : {}) });
|
|
676
680
|
|
|
681
|
+
/** `sessionProviders` of an inspect answer: the session backends the target's capabilities supply
|
|
682
|
+
* and a spawn can select there, `[{ name, capability }]` sorted by name (lib/session-providers.mjs
|
|
683
|
+
* offeredSessionProviders over the target's modules). A malformed declaration is none: what is
|
|
684
|
+
* wrong with it is `oats capabilities show`'s to say. */
|
|
685
|
+
function sessionProviderKeys(t) {
|
|
686
|
+
const { providers } = offeredSessionProviders((t.modules || []).filter((x) => x.manifest).map((x) => ({ id: x.name, manifest: x.manifest })));
|
|
687
|
+
return { sessionProviders: providers.map(({ name, capability }) => ({ name, capability })) };
|
|
688
|
+
}
|
|
677
689
|
/** The team/workspace facts a provider receives, as hooks get them (teamEnv), and the soul's name and
|
|
678
690
|
* stable id as its hooks and dispatched commands get them. Every ambient OATS_* is removed first. */
|
|
679
691
|
function providerEnv(t, capability, settings) {
|
|
@@ -870,6 +882,38 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
|
|
|
870
882
|
}
|
|
871
883
|
else providers.push(item(mod.name, "unknown", { producer: "provider binding check", result: null, problems: out.problems, reason: out.problems[0]?.message ?? null, ...cap(mod.name) }));
|
|
872
884
|
}
|
|
885
|
+
// A session provider's own readiness (lib/session-providers.mjs, the optional `check` command),
|
|
886
|
+
// relayed verbatim as a providers item, as a binding check is. For a home: the provider it runs
|
|
887
|
+
// on, required. For a soul: every provider its capabilities offer, not required (the soul can
|
|
888
|
+
// launch on tmux); a member capability's runs from a spawned home, as its binding check does.
|
|
889
|
+
for (const mod of t.modules) {
|
|
890
|
+
const offered = Object.values(sessionProvidersOf(mod.manifest).providers).filter((p) => p.commands.check);
|
|
891
|
+
for (const provider of offered) {
|
|
892
|
+
const onIt = t.home ? t.meta?.backend === provider.name && t.meta?.session?.provider === mod.name : false;
|
|
893
|
+
if (t.home && !onIt) continue;
|
|
894
|
+
const subject = `${mod.name} session backend ${provider.name}`;
|
|
895
|
+
const push = (status, rest) => providers.push(item(subject, status, { required: !!t.home, producer: "session provider check", ...rest, ...cap(mod.name) }));
|
|
896
|
+
const unknown = (code, message) => push("unknown", { result: null, problems: [{ code, message }], reason: message });
|
|
897
|
+
if (Date.now() >= deadline) { unknown("time-budget-exhausted", `time budget exhausted: the providers check stops after ${Math.round(budgetMs / 1000)} s per readiness read`); continue; }
|
|
898
|
+
let binding;
|
|
899
|
+
if (t.home) {
|
|
900
|
+
const found = homeSessionProvider(t.home, t.meta, mod.name, provider.name);
|
|
901
|
+
if (found.problem) { unknown("resource-not-found", found.problem); continue; }
|
|
902
|
+
binding = found.binding;
|
|
903
|
+
} else {
|
|
904
|
+
let dir = null;
|
|
905
|
+
if (mod.module && t.lock) { try { dir = await ensureModuleTree(t.deployment, mod.module, t.lock, { catalog, remoteOptions }); } catch (e) { unknown(e.code || "provider-unavailable", e.message); continue; } }
|
|
906
|
+
if (!dir) { unknown("resource-not-found", `${mod.name}: a member module runs from a spawned home; inspect an instance (--home) for its check`); continue; }
|
|
907
|
+
const settings = obj(t.payloads[mod.name]) ? t.payloads[mod.name] : {};
|
|
908
|
+
binding = { home: null, meta: {}, capability: mod.name, name: provider.name, provider, moduleDir: dir, cap: { id: mod.name, settings }, digest: null,
|
|
909
|
+
env: { ...providerEnv(t, mod.name, settings), OATS_EVENT: "session", OATS_BACKEND: provider.name } };
|
|
910
|
+
}
|
|
911
|
+
const checked = checkProviderSession(binding, { home: t.home ?? null, soul: t.home ? null : t.soul.name, settings: binding.cap.settings }, { timeoutMs: Math.max(1, Math.min(20_000, deadline - Date.now())) });
|
|
912
|
+
if (checked.unavailable) { unknown("provider-unavailable", checked.unavailable); continue; }
|
|
913
|
+
const status = PROVIDER_STATUS_ITEM[checked.result.status];
|
|
914
|
+
push(status, { result: checked.result, reason: status === "pass" ? null : checked.result.problems[0]?.message ?? `the provider reports ${checked.result.status}` });
|
|
915
|
+
}
|
|
916
|
+
}
|
|
873
917
|
const checks = { installed: { status: roll(installed), items: installed }, configured: { status: roll(configured), items: configured }, member: { status: roll(member), items: member }, providers: { status: roll(providers), items: providers } };
|
|
874
918
|
const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
|
|
875
919
|
const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
|
|
@@ -138,7 +138,9 @@ export function setInstanceRelatedWork(ctx, root, name, { home, on }) {
|
|
|
138
138
|
* parentage is the only relation the kernel knows; it is reported as such. */
|
|
139
139
|
export function descendantsOf(root, name) {
|
|
140
140
|
const rows = [];
|
|
141
|
-
|
|
141
|
+
// One listing, and no session provider asked: only names and records are read here.
|
|
142
|
+
const listed = listInstances(root, undefined, undefined, { askProviders: false });
|
|
143
|
+
for (const a of listAgents(root)) for (const i of listed.filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
|
|
142
144
|
const home = join(a._dir, "instances", inst.instance);
|
|
143
145
|
const meta = otherRecord(home);
|
|
144
146
|
if (meta) rows.push({ instance: inst.instance, agent: a.name, home, parent: meta.parentInstance ?? null });
|
|
@@ -161,6 +163,9 @@ export function descendantsOf(root, name) {
|
|
|
161
163
|
return out; // deepest first
|
|
162
164
|
}
|
|
163
165
|
|
|
166
|
+
/** What the session's inspect said of its activity (`running`: true, false, or null for not known),
|
|
167
|
+
* kept beside the facts for planStop's `midTask` and never part of a plan's JSON. */
|
|
168
|
+
const REPORTED_RUNNING = Symbol("reportedRunning");
|
|
164
169
|
/** `state` is the session backend's word: "shell"/"stopped"/"not-launched" are
|
|
165
170
|
* idle; "unknown" means a NON-shell process is running whose identity tmux
|
|
166
171
|
* cannot name (the ordinary case for a launched harness). "Could not be
|
|
@@ -168,7 +173,7 @@ export function descendantsOf(root, name) {
|
|
|
168
173
|
* the kernel code of what failed, never a system error's (E_SESSION_UNAVAILABLE
|
|
169
174
|
* for one that has none; workFacts: E_GIT_FAILED). */
|
|
170
175
|
function sessionFacts(home) {
|
|
171
|
-
try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true }; }
|
|
176
|
+
try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true, [REPORTED_RUNNING]: s.running ?? null }; }
|
|
172
177
|
catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: kernelCode(e, "E_SESSION_UNAVAILABLE") }; }
|
|
173
178
|
}
|
|
174
179
|
/** The instances attached to `tree`, a tree of the home of the instance `name` under `root` (its
|
|
@@ -233,7 +238,14 @@ export function planStop(ctx, root, name, { home, recursive = true, [OWN_HOLDING
|
|
|
233
238
|
const targets = [...kids.map((kid) => targetFacts(kid, otherRecord(kid.home), own)), targetFacts({ ...me, instance: name, depth: 0 }, targetRecord(me.home), own)];
|
|
234
239
|
// Reported activity: a running session or dirty work is mid-task; when the
|
|
235
240
|
// session could not be established and work is not observed, say unknown.
|
|
236
|
-
|
|
241
|
+
// A session provider's session says its activity itself (its inspect's `running`): true is
|
|
242
|
+
// activity, and one that is there and reports none (null) is not reported as activity: unknown.
|
|
243
|
+
// (A tmux pane's state "unknown" is a process tmux cannot name, the ordinary launched harness:
|
|
244
|
+
// activity, as before.)
|
|
245
|
+
const onProvider = (s) => s.established && s.present === true && s.backend !== null && s.backend !== "tmux";
|
|
246
|
+
const unknownActivity = (s) => onProvider(s) && s[REPORTED_RUNNING] === null;
|
|
247
|
+
const active = (s) => (onProvider(s) ? s[REPORTED_RUNNING] === true : running(s));
|
|
248
|
+
for (const t of targets) t.midTask = active(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || unknownActivity(t.session) || !t.work.observed) ? "unknown" : false;
|
|
237
249
|
const safety = targets.map((t) => [t.home, t.session.state, t.session.present, t.launched, t.retiring]);
|
|
238
250
|
const ambiguousEdges = (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason }));
|
|
239
251
|
const plan = { lifecycleApi: LIFECYCLE_API, action: "stop", instance: name, home: me.home, recursive, at: new Date().toISOString(),
|
package/lib/instance-listing.mjs
CHANGED
|
@@ -8,7 +8,7 @@ import { readFileSync, readdirSync, lstatSync, existsSync, statSync, openSync, c
|
|
|
8
8
|
import { join, dirname, resolve, basename } from "node:path";
|
|
9
9
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
10
10
|
import { createSessionPaneInspector, AGENT_PANE_OPTION } from "./session-input.mjs";
|
|
11
|
-
import { liveSession, validWaitingMessage } from "./instance-events.mjs";
|
|
11
|
+
import { liveSession, liveWaiting, validWaitingMessage } from "./instance-events.mjs";
|
|
12
12
|
import { readBoardRow } from "./instance-board.mjs";
|
|
13
13
|
import { processLiveness } from "./worktree-hooks.mjs";
|
|
14
14
|
import { shownHolder } from "./claim.mjs";
|
|
@@ -19,10 +19,12 @@ import { readInstanceBackground } from "./instance-background.mjs";
|
|
|
19
19
|
import { readInstancePin } from "./instance-pin.mjs";
|
|
20
20
|
import { relatedWorkHeld } from "./instance-related-work.mjs";
|
|
21
21
|
import { readSpawnedBy } from "./spawned-by.mjs";
|
|
22
|
-
import { sessionEndOf } from "./session-end.mjs";
|
|
22
|
+
import { HOST_STOP_REASON, lostReasonOf, sessionEndOf } from "./session-end.mjs";
|
|
23
23
|
import { identityHolderState, recordSeen } from "./session-seen.mjs";
|
|
24
24
|
import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
|
|
25
|
-
import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot } from "./session-inspect.mjs";
|
|
25
|
+
import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot, providerMayWait } from "./session-inspect.mjs";
|
|
26
|
+
import { INSPECT_MANY_MAX, sessionProviderTimeout, homeSessionProvider, recordsSessionProvider, inspectManyGroup, inspectProviderSession, inspectProviderSessions, rowSession, unsettledLaunchSaid } from "./session-providers.mjs";
|
|
27
|
+
import { SESSION_END } from "./session-resume-contract.mjs";
|
|
26
28
|
|
|
27
29
|
/** OATS 0.25 and earlier homed local souls and capability-defined agents at
|
|
28
30
|
* <scope>/local-agents/ (and <root>/local-agents|tmp-agents). The kernel never reads,
|
|
@@ -278,10 +280,79 @@ function statusTmuxPanes(snapshot, socket, session, io) {
|
|
|
278
280
|
return { ...snapshot, panes, windowIds };
|
|
279
281
|
} catch (e) { return { error: tmuxFailure(e, "tmux list-panes failed") }; }
|
|
280
282
|
}
|
|
283
|
+
/** The row of a home on a session provider, before its provider has been asked: the kernel's own
|
|
284
|
+
* facts, under the receipt's authority (instanceSessionTarget). → `{ fields, ask? }`: `fields` the
|
|
285
|
+
* row's `backend`, `session`, `tmux` (null), `open`, `running`, `runtimeState` (`unknown`, `shell`,
|
|
286
|
+
* `stopped` or `unreachable`; always there) and, for a home OATS stopped, `sessionEnd`; `ask`
|
|
287
|
+
* (`{ binding, endpoint }`) for a session the provider must be asked about.
|
|
288
|
+
* `session` is `{ provider }` and, on this host only, the endpoint's thread id (rowSession): the
|
|
289
|
+
* endpoint itself is never on a row (`oats session inspect --home` answers it, locally).
|
|
290
|
+
* A home OATS stopped, and one never launched, answer without the provider. A stopped home's
|
|
291
|
+
* `sessionEnd` is its stop receipt's (lib/session-end.mjs): `lost` when `oats host run`'s shutdown
|
|
292
|
+
* stopped it, which a resume brings back, else `stopped`. A receipt or a module copy that cannot
|
|
293
|
+
* be used is unknown (`unreachable`, with the reason), never stopped. */
|
|
294
|
+
function providerRow(home, meta) {
|
|
295
|
+
const unreachable = (why, session) => ({ fields: { backend: meta.backend, session: session ?? rowSession(typeof meta.session?.provider === "string" ? meta.session.provider : null, null), tmux: null, open: null, running: null, runtimeState: "unreachable", runtimeError: why } });
|
|
296
|
+
let s;
|
|
297
|
+
try { s = instanceSessionTarget(home); } catch (e) { return unreachable(`${typeof e?.code === "string" ? e.code : "E_SESSION_UNAVAILABLE"}: ${e?.message ?? e}`); }
|
|
298
|
+
const recorded = s.session ?? s.planned;
|
|
299
|
+
// A record that names a session provider beside a receipt that authorises a tmux session, or none.
|
|
300
|
+
if (!recorded) return unreachable("E_RUNTIME_AUTHORITY_MISMATCH: instance metadata records a session provider and its independent session receipt does not");
|
|
301
|
+
const fields = { backend: recorded.backend, session: rowSession(recorded.provider, recorded.endpoint ?? null), tmux: null, open: null };
|
|
302
|
+
// A launch that was sent and never recorded: unknown, never stopped (lib/session-providers.mjs launchSentOf).
|
|
303
|
+
if (s.unsettled) return unreachable(unsettledLaunchSaid(basename(home), s.unsettled.backend, s.unsettled.launchSent), fields.session);
|
|
304
|
+
if (!s.session) return { fields: { ...fields, running: false, runtimeState: "stopped" } };
|
|
305
|
+
if (s.session.stoppedAt !== null) return { fields: { ...fields, running: false, runtimeState: "stopped", sessionEnd: lostReasonOf(home, s.meta) === HOST_STOP_REASON ? SESSION_END.LOST : SESSION_END.STOPPED } };
|
|
306
|
+
const found = homeSessionProvider(home, s.meta, s.session.provider, s.session.backend);
|
|
307
|
+
if (found.problem) return unreachable(found.problem, fields.session);
|
|
308
|
+
return { fields: { ...fields, running: null, runtimeState: "unreachable" }, ask: { binding: found.binding, endpoint: s.session.endpoint } };
|
|
309
|
+
}
|
|
310
|
+
/** The time one listing gives all its session providers together: a provider that hangs costs a
|
|
311
|
+
* status, a sweep or a plan this much at most, however many homes it has. */
|
|
312
|
+
const PROVIDER_LISTING_BUDGET_MS = 30_000;
|
|
313
|
+
/** Ask the providers about `asks` ([{ row, home, binding, endpoint, mayEnd }]) and write each answer
|
|
314
|
+
* into its row: one `inspectMany` call per group of homes that share one module copy, provider and
|
|
315
|
+
* settings (inspectManyGroup), at most INSPECT_MANY_MAX homes a call, and one `inspect` per home
|
|
316
|
+
* where a provider declares none (or its batch was bad: inspectProviderSessions). A provider that
|
|
317
|
+
* fails, refuses or answers outside the contract's words leaves the row unknown: `running: null`,
|
|
318
|
+
* `runtimeState: "unreachable"`. A session that is gone on a home OATS did not stop is a lost
|
|
319
|
+
* one (`sessionEnd: "lost"`, where the row may say how its session ended: `mayEnd`), which the
|
|
320
|
+
* sweep resumes under the home's cap. All the asks of one listing share PROVIDER_LISTING_BUDGET_MS. */
|
|
321
|
+
function answerProviderRows(asks, io) {
|
|
322
|
+
const deadline = Date.now() + PROVIDER_LISTING_BUDGET_MS;
|
|
323
|
+
// Each call's timeout: the verb's own (and a test's seam), never past what the listing has left.
|
|
324
|
+
const timeoutFor = () => Math.min(sessionProviderTimeout("inspect"), deadline - Date.now());
|
|
325
|
+
const groups = new Map(), single = [];
|
|
326
|
+
for (const ask of asks) {
|
|
327
|
+
const key = inspectManyGroup(ask.binding);
|
|
328
|
+
if (key === null) single.push(ask);
|
|
329
|
+
else groups.set(key, [...(groups.get(key) ?? []), ask]);
|
|
330
|
+
}
|
|
331
|
+
const answer = (ask, inspected) => {
|
|
332
|
+
if (inspected.unavailable) { Object.assign(ask.row, { running: null, runtimeState: "unreachable", runtimeError: inspected.unavailable }); return; }
|
|
333
|
+
const { state, running, open } = inspected.observed;
|
|
334
|
+
Object.assign(ask.row, { running, runtimeState: state, open });
|
|
335
|
+
delete ask.row.runtimeError;
|
|
336
|
+
// A producer's claim, read while the session is there and not in error (an idle session can be
|
|
337
|
+
// the one waiting on a person); the receipt already agreed (providerRow).
|
|
338
|
+
if (providerMayWait(inspected.observed)) ask.row.waitingOnYou = liveWaiting(ask.home);
|
|
339
|
+
if (inspected.observed.present === false && ask.mayEnd) ask.row.sessionEnd = SESSION_END.LOST;
|
|
340
|
+
};
|
|
341
|
+
for (const ask of single) { const timeoutMs = timeoutFor(); answer(ask, timeoutMs > 0 ? inspectProviderSession(ask.binding, ask.endpoint, { io, timeoutMs }) : { unavailable: "the time this listing gives its session providers was spent before this one was asked" }); }
|
|
342
|
+
for (const members of groups.values()) {
|
|
343
|
+
for (let at = 0; at < members.length; at += INSPECT_MANY_MAX) {
|
|
344
|
+
const chunk = members.slice(at, at + INSPECT_MANY_MAX);
|
|
345
|
+
inspectProviderSessions(chunk, { io, timeoutFor }).forEach((inspected, i) => answer(chunk[i], inspected));
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
}
|
|
281
349
|
/** `records`, when given, a Map the listing fills with each home's record as read (home → the JSON
|
|
282
350
|
* object its instance.json holds, before upgradeHomeMeta), for the rest of the same read to reuse
|
|
283
|
-
* instead of reading the file again (legacyCapturedHomes).
|
|
284
|
-
|
|
351
|
+
* instead of reading the file again (legacyCapturedHomes).
|
|
352
|
+
* `askProviders: false` (the host's shutdown listing): no session provider is asked. A provider
|
|
353
|
+
* home whose provider would be asked reads `running: null`, `runtimeState: "unreachable"`, with a
|
|
354
|
+
* `runtimeError` that says so: the listing then depends on no provider's answer, or time. */
|
|
355
|
+
export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { records, askProviders = true } = {}) {
|
|
285
356
|
// Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
|
|
286
357
|
// socket, never the ambient $TMUX server: one window read and one pane read per socket/session,
|
|
287
358
|
// plus one lazy process scan for shell descendants, independent of the number of homes.
|
|
@@ -294,6 +365,9 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
294
365
|
return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
|
|
295
366
|
};
|
|
296
367
|
const inspectPanes = createSessionPaneInspector(io);
|
|
368
|
+
// The homes on a session provider whose provider must be asked: asked together once every row is
|
|
369
|
+
// read (answerProviderRows), so that one call can answer for a provider's whole group.
|
|
370
|
+
const providerAsks = [];
|
|
297
371
|
const tmuxByEndpoint = new Map();
|
|
298
372
|
const windowsOf = (session, socket) => {
|
|
299
373
|
const key = JSON.stringify([socket ?? null, session]);
|
|
@@ -318,9 +392,14 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
318
392
|
const { rollbackIncomplete, spawnInProgress, retirePending, retire } = readRetireFacts(home);
|
|
319
393
|
// A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
|
|
320
394
|
// A home whose record cannot be read is listed, never observed: where its session is, is in the record.
|
|
395
|
+
const herdr = record.state !== "unreadable" && recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)));
|
|
396
|
+
// A home on a session provider is never read through tmux: its row is the kernel's facts
|
|
397
|
+
// and, where the provider must be asked, its answer (below, once every row is read).
|
|
398
|
+
const provided = record.state === "record" && !herdr && recordsSessionProvider(meta) ? providerRow(home, meta) : null;
|
|
321
399
|
const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
|
|
322
|
-
:
|
|
400
|
+
: herdr
|
|
323
401
|
? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
|
|
402
|
+
: provided ? (({ sessionEnd: _own, ...fields }) => fields)(provided.fields)
|
|
324
403
|
: tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
|
|
325
404
|
// A home that records no socket and no launch (--no-launch) reads the default server only
|
|
326
405
|
// by default: that server's missing socket says nothing about it, and stays "not running".
|
|
@@ -363,7 +442,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
363
442
|
// Feature session-resume: how the last session of a launched home that does not run ended
|
|
364
443
|
// (lib/session-end.mjs): lost, stopped or exited. Absent while it runs or reads unknown, for a
|
|
365
444
|
// home never launched, and for one being set up, retired or quarantined.
|
|
366
|
-
|
|
445
|
+
// A home on a session provider reads it from its receipt (providerRow): `lost` for one stopped
|
|
446
|
+
// with the host, which a resume brings back, `stopped` for one an operator stopped; a session
|
|
447
|
+
// OATS did not stop has none.
|
|
448
|
+
const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? (provided ? provided.fields.sessionEnd ?? null : sessionEndOf(home, meta)) : null;
|
|
367
449
|
// Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
|
|
368
450
|
// null, after the record so that nothing in instance.json stands in for it.
|
|
369
451
|
// Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
|
|
@@ -376,7 +458,13 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
376
458
|
// Feature instance-board: the agent's board (lib/instance-board.mjs), null for a home with no board
|
|
377
459
|
// file: its facts, and the questions of its current session, by the same read of the log as the claim.
|
|
378
460
|
const board = readBoardRow(home, { session, ...recordMeta });
|
|
379
|
-
|
|
461
|
+
// `backend`: `tmux` for a home on the kernel's own backend, a session provider's name otherwise
|
|
462
|
+
// (liveness carries it, with `session`); absent for a home whose record cannot be read and
|
|
463
|
+
// for one opened in Herdr, whose record says what it says.
|
|
464
|
+
const row = { ...recorded, ...claims, home, instance: e.name, ...(record.state === "record" && !herdr && !provided ? { backend: "tmux" } : {}), ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(related ? { relatedWork: true } : {}), ...(related?.parent ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, board, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
465
|
+
if (provided?.ask && askProviders) providerAsks.push({ row, home, ...provided.ask, mayEnd: meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending });
|
|
466
|
+
else if (provided?.ask) row.runtimeError = "its session provider was not asked (a listing that asks no provider)";
|
|
467
|
+
return row;
|
|
380
468
|
|
|
381
469
|
});
|
|
382
470
|
};
|
|
@@ -401,6 +489,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
401
489
|
out.push({ name, kind: "capability", capability: cap, description: cap ? `capability agent (${cap})` : "capability agent", dir, instances, ...(retireFailures.length ? { retireFailures } : {}) });
|
|
402
490
|
seen.add(name);
|
|
403
491
|
}
|
|
492
|
+
if (providerAsks.length) answerProviderRows(providerAsks, io);
|
|
404
493
|
// Feature session-resume: what this local listing saw of each home's session, for the sweep
|
|
405
494
|
// (lib/session-seen.mjs). It never changes the listing, and never throws or prints.
|
|
406
495
|
recordSeen(root, out.flatMap((a) => a.instances || []));
|
package/lib/kernel-features.mjs
CHANGED
|
@@ -8,7 +8,16 @@ import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
|
|
|
8
8
|
/** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
|
|
9
9
|
* its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
|
|
10
10
|
export const SPAWN_TASK_STDIN_FEATURE = "spawn-task-stdin";
|
|
11
|
-
|
|
11
|
+
/** Session providers (lib/session-providers.mjs): a session backend a capability supplies, beside the
|
|
12
|
+
* kernel's built-in ones. A host that lists this takes `--backend <provider>`, records and answers
|
|
13
|
+
* provider homes; one that does not refuses such a home's session verbs. */
|
|
14
|
+
export const SESSION_PROVIDERS_FEATURE = "session-providers";
|
|
15
|
+
/** The kernel's built-in session backends: `sessionBackends` in `oats version --json`. A session
|
|
16
|
+
* provider is never listed there: it is a capability's, named by the homes and souls that have it. */
|
|
17
|
+
export const BUILTIN_SESSION_BACKENDS = Object.freeze(["tmux"]);
|
|
18
|
+
/** A session provider's name, and what `--backend` takes. */
|
|
19
|
+
export const SESSION_PROVIDER_NAME_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
|
|
20
|
+
export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "instance-related-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE, "instance-board", SESSION_PROVIDERS_FEATURE]);
|
|
12
21
|
/** The agent's board (feature instance-board, lib/instance-board.mjs): `boardApi` in the probe, the board
|
|
13
22
|
* file and the board commands' answers. */
|
|
14
23
|
export const BOARD_API = 1;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** CLI startup's Node floor. No imports or effects: this must load before the kernel. */
|
|
2
|
+
export function nodeVersionFailure(found) {
|
|
3
|
+
if (Number(found.split(".")[0]) >= 22) return null;
|
|
4
|
+
return { schemaVersion: 1, ok: false, error: {
|
|
5
|
+
code: "E_NODE_UNSUPPORTED",
|
|
6
|
+
message: `oats needs Node.js 22 or later; this is Node.js ${found}`,
|
|
7
|
+
details: { found, minimum: "22" },
|
|
8
|
+
} };
|
|
9
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/** Private entry point of lib/session-providers.mjs (callSessionProvider); no CLI or provider
|
|
2
|
+
* contract. The kernel runs every command of a session provider through this process, started in
|
|
3
|
+
* a process group of its own, of which it is the leader:
|
|
4
|
+
*
|
|
5
|
+
* node provider-call-child.mjs <group file | -> <provider script> [arguments…]
|
|
6
|
+
*
|
|
7
|
+
* - With a group file, it records who it is there first (`{ pid, processStart }`, created
|
|
8
|
+
* exclusively), outside the home, and only then runs the provider. A kernel that finds the call
|
|
9
|
+
* of a kernel that was killed ends this group by that record before it settles anything the
|
|
10
|
+
* call may still do (lib/core.mjs endProviderCall). A file that is already there is that
|
|
11
|
+
* kernel's word that the call is void: the provider is not run. Nor is it once the call's own
|
|
12
|
+
* record (the group file's name without `.group`) is gone: that kernel has ended the call and
|
|
13
|
+
* taken its records away, the void one last.
|
|
14
|
+
* - The provider's script runs in this group, with this process's stdin, stdout and stderr: its
|
|
15
|
+
* request and its answer pass through untouched. A provider runs its own helpers in the group
|
|
16
|
+
* and never detaches them.
|
|
17
|
+
* - A signal to end it (the kernel's timeout sends SIGTERM) ends the whole group, by SIGKILL.
|
|
18
|
+
*
|
|
19
|
+
* It exits as the provider's script did. 125: the call was void or could not be recorded, and
|
|
20
|
+
* nothing was run. 126: the script could not be started. */
|
|
21
|
+
import { spawn } from "node:child_process";
|
|
22
|
+
import { existsSync, linkSync, rmSync, writeFileSync } from "node:fs";
|
|
23
|
+
import { processStartToken } from "../packages/record/lib/process-identity.mjs";
|
|
24
|
+
|
|
25
|
+
const [groupFile, script, ...args] = process.argv.slice(2);
|
|
26
|
+
const endGroup = () => process.kill(0, "SIGKILL");
|
|
27
|
+
// A test's seam (reserved launch environment): this leader starts late, as on a loaded host.
|
|
28
|
+
const late = Number(process.env.OATS_TEST_PROVIDER_LEADER_DELAY_MS);
|
|
29
|
+
delete process.env.OATS_TEST_PROVIDER_LEADER_DELAY_MS;
|
|
30
|
+
if (Number.isFinite(late) && late > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(late, 10_000));
|
|
31
|
+
for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(signal, endGroup);
|
|
32
|
+
|
|
33
|
+
if (groupFile !== "-") {
|
|
34
|
+
const processStart = processStartToken(process.pid);
|
|
35
|
+
// Without its start time the record could not tell this group from a later one of the same id.
|
|
36
|
+
if (!processStart) process.exit(125);
|
|
37
|
+
// Published whole, by an exclusive link from a file of its own: a reader never finds it half
|
|
38
|
+
// written, whenever this process ends (lib/core.mjs publishExclusive, the same rule).
|
|
39
|
+
const own = `${groupFile}.${process.pid}.tmp`;
|
|
40
|
+
try {
|
|
41
|
+
writeFileSync(own, `${JSON.stringify({ pid: process.pid, processStart })}\n`, { flag: "wx", mode: 0o600 });
|
|
42
|
+
linkSync(own, groupFile);
|
|
43
|
+
} catch { rmSync(own, { force: true }); process.exit(125); } // already there (void), or not writable: nothing is run
|
|
44
|
+
rmSync(own, { force: true });
|
|
45
|
+
if (!existsSync(groupFile.slice(0, -".group".length))) { rmSync(groupFile, { force: true }); process.exit(125); }
|
|
46
|
+
}
|
|
47
|
+
// A test's seam (reserved launch environment): the kernel that waits for this command ends
|
|
48
|
+
// while its provider's command runs, shortly after it started and read its request
|
|
49
|
+
// (lib/provider-test-seams.mjs).
|
|
50
|
+
const endsKernel = process.env.OATS_TEST_PROVIDER_KILL_KERNEL !== undefined;
|
|
51
|
+
delete process.env.OATS_TEST_PROVIDER_KILL_KERNEL;
|
|
52
|
+
const kernel = process.ppid;
|
|
53
|
+
const child = spawn(process.execPath, [script, ...args], { stdio: "inherit" });
|
|
54
|
+
if (endsKernel) setTimeout(() => process.kill(kernel, "SIGKILL"), 150);
|
|
55
|
+
child.on("error", () => process.exit(126));
|
|
56
|
+
child.on("close", (code, signal) => {
|
|
57
|
+
if (!signal) process.exit(code ?? 1);
|
|
58
|
+
for (const handled of ["SIGTERM", "SIGINT", "SIGHUP"]) process.removeAllListeners(handled);
|
|
59
|
+
process.kill(process.pid, signal);
|
|
60
|
+
});
|