@awebai/oats 0.69.4 → 0.69.6
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 +141 -364
- package/docs/configuration.md +12 -0
- package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
- package/docs/design/2026-10-29-warm-reader.md +261 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +258 -13
- package/docs/execution-targets.md +36 -5
- package/docs/implementation.md +34 -9
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +18 -8
- package/docs/named-test-runs.md +4 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.5.md +146 -0
- package/docs/release-notes/v0.69.6.md +165 -0
- package/docs/schedules.md +8 -1
- package/docs/tui.md +23 -5
- package/docs/upgrading.md +20 -5
- package/docs/workspaces.md +2 -2
- package/lib/agents-root.mjs +51 -0
- package/lib/argv.mjs +41 -0
- package/lib/automation-api.mjs +7 -0
- package/lib/automation-scope.mjs +37 -0
- package/lib/automations.mjs +63 -12
- package/lib/captured-context.mjs +12 -0
- package/lib/compile-cache.mjs +36 -0
- package/lib/core.mjs +39 -1348
- package/lib/deployment-path.mjs +127 -0
- package/lib/deployments.mjs +2 -2
- package/lib/drift.mjs +95 -0
- package/lib/hot-reads.mjs +137 -0
- package/lib/install-stamp.mjs +61 -0
- package/lib/instance-address.mjs +21 -0
- package/lib/instance-events.mjs +8 -6
- package/lib/instance-lifecycle.mjs +4 -16
- package/lib/instance-listing.mjs +738 -0
- package/lib/instance-resolution.mjs +5 -166
- package/lib/kernel-features.mjs +10 -0
- package/lib/local-edit.mjs +1 -1
- package/lib/local-inputs.mjs +3 -0
- package/lib/materialize.mjs +2 -87
- package/lib/member-clone.mjs +192 -0
- package/lib/package-catalog.mjs +93 -0
- package/lib/packages.mjs +4 -24
- package/lib/read-call.mjs +143 -0
- package/lib/reader.mjs +203 -0
- package/lib/remote.mjs +47 -6
- package/lib/reserved-launch-env.mjs +20 -0
- package/lib/resolved-deployment.mjs +13 -5
- package/lib/roster-read.mjs +199 -0
- package/lib/schedule.mjs +5 -29
- package/lib/semver.mjs +12 -0
- package/lib/servers.mjs +10 -12
- package/lib/session-end.mjs +3 -2
- package/lib/session-input.mjs +35 -11
- package/lib/session-inspect.mjs +219 -0
- package/lib/soul-listing.mjs +216 -0
- package/lib/status-words.mjs +30 -0
- package/lib/version.mjs +9 -0
- package/lib/workspace-read.mjs +160 -0
- package/lib/write-file-atomic.mjs +28 -0
- package/package-catalog.json +4 -4
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +1 -0
- package/packages/client/cli-probe-contract.mjs +4 -2
- package/packages/client/deployment-observer.mjs +8 -3
- package/packages/client/deployment-panel.mjs +17 -1
- package/packages/client/deployment-read-cli.mjs +48 -27
- package/packages/client/own-codes.mjs +3 -0
- package/packages/client/warm-reader.mjs +241 -0
- package/packages/tui/lib/client.mjs +2 -1
- package/packages/tui/lib/read.mjs +59 -11
- package/packages/tui/lib/store.mjs +7 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
|
@@ -2,9 +2,10 @@
|
|
|
2
2
|
* list (awebai/oats#1390; lib/deployments.mjs listResolved).
|
|
3
3
|
*
|
|
4
4
|
* The resolvers report the deployment directory they found: `loadLocal` (lib/workspace.mjs) the
|
|
5
|
-
* directory of the oats-local.yaml its walk up found, as spelled; `ensureRoot` (lib/
|
|
5
|
+
* directory of the oats-local.yaml its walk up found, as spelled; `ensureRoot` (lib/agents-root.mjs) the
|
|
6
6
|
* directory of the canonical agents root, `canonical`. The observer is called once, when the
|
|
7
|
-
* process exits,
|
|
7
|
+
* process exits (or, in a process answering many reads, when each read ends: lib/read-call.mjs), with
|
|
8
|
+
* the root the command settled on: the first canonical one reported, else the
|
|
8
9
|
* first one, and whether it is canonical. So a command that resolves its canonical root is compared
|
|
9
10
|
* with that root, never with an earlier spelling of the same deployment. Nothing happens until the
|
|
10
11
|
* CLI sets an observer for this process (the commands in its one table): library callers and tests
|
|
@@ -14,11 +15,18 @@
|
|
|
14
15
|
let observer = null;
|
|
15
16
|
const reported = { canonical: null, spelled: null };
|
|
16
17
|
|
|
17
|
-
/** Observe the deployment this process resolves; called once, at exit.
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
/** Observe the deployment this process resolves; called once, at exit. `atExit: false`: the caller
|
|
19
|
+
* settles it itself (settleResolvedDeployment), as a process answering many reads does at the end of
|
|
20
|
+
* each one (lib/read-call.mjs). */
|
|
21
|
+
export function observeResolvedDeployment(fn, { atExit = true } = {}) {
|
|
22
|
+
if (!observer && atExit) process.once("exit", settleResolvedDeployment);
|
|
20
23
|
observer = fn;
|
|
21
24
|
}
|
|
25
|
+
/** Forget what the resolvers reported, keeping the observer: the start of one read in a process that
|
|
26
|
+
* answers many (lib/read-call.mjs). */
|
|
27
|
+
export function resetResolvedDeployment() {
|
|
28
|
+
reported.canonical = reported.spelled = null;
|
|
29
|
+
}
|
|
22
30
|
|
|
23
31
|
/** A resolver found the deployment directory `dir` (`canonical`: its canonical spelling). */
|
|
24
32
|
export function resolvedDeployment(dir, { canonical = false } = {}) {
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
/** lib/roster-read.mjs — `oats status`, the roster read (awebai/oats#1630): the deployment's agents and
|
|
2
|
+
* instances, each instance's workspace drift, and its workspace identity. One implementation behind the
|
|
3
|
+
* CLI (bin/oats.mjs status) and a process that answers it many times (lib/read-call.mjs, whose header
|
|
4
|
+
* describes the context and the answer). `statusAnswer(ctx)` is the `--json` answer, a bare document
|
|
5
|
+
* (never an envelope) or a failure envelope; `statusView(ctx)` the data bin's text renderer reads. A
|
|
6
|
+
* leaf a hot read loads (lib/hot-reads.mjs): never core.mjs. Kernel-private, not exported from `./core`. */
|
|
7
|
+
import { readFileSync } from "node:fs";
|
|
8
|
+
import { dirname, join } from "node:path";
|
|
9
|
+
import { ensureRoot } from "./agents-root.mjs";
|
|
10
|
+
import { legacyCapturedHomes, legacyLocalAgents, listInstances } from "./instance-listing.mjs";
|
|
11
|
+
import { KERNEL_FEATURES } from "./kernel-features.mjs";
|
|
12
|
+
import { readLockIfPresent } from "./packages.mjs";
|
|
13
|
+
import { answerWarnings, refuse, runRead } from "./read-call.mjs";
|
|
14
|
+
import { lastObservedCommit, parseRepoRef, peekAtCommit } from "./remote.mjs";
|
|
15
|
+
import { readSessionViewer } from "./session-viewer.mjs";
|
|
16
|
+
import { teamModel } from "./teams.mjs";
|
|
17
|
+
import { loadLocal, memberRowByKey } from "./workspace.mjs";
|
|
18
|
+
|
|
19
|
+
/** `oats status --json`: → `{ exit, answer, stderr }` (lib/read-call.mjs). `ctx.team`: `--team` was given. */
|
|
20
|
+
export function statusAnswer(ctx) {
|
|
21
|
+
return runRead(ctx, async (call) => ({ answer: statusDocument(call, await statusFacts(call, ctx)) }));
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** `oats status` in text mode: → `{ exit, answer, view, stderr }`, `view` `{ root, agents, ws, problems }`
|
|
25
|
+
* (`ws`: statusDrift's answer) when it did not refuse, `answer` the failure envelope when it did. */
|
|
26
|
+
export function statusView(ctx) {
|
|
27
|
+
return runRead(ctx, async (call) => ({ view: await statusFacts(call, ctx) }));
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** The problems doctor and status share for a v2 deployment: what OATS 0.25 left
|
|
31
|
+
* under local-agents/ (named, never read), and the captured homes under the agents root
|
|
32
|
+
* (`records`: legacyCapturedHomes'). */
|
|
33
|
+
export function legacyLayoutProblems(root, { records } = {}) {
|
|
34
|
+
return [legacyLocalAgents(root), legacyCapturedHomes(root, { records })].filter(Boolean);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
async function statusFacts(call, { dir, team = false }) {
|
|
38
|
+
if (team) refuse("E_BAD_ARGS", "status --team was removed with the classic team scope: `oats status` in the deployment lists every instance, and `oats workspace status` shows the members");
|
|
39
|
+
let root;
|
|
40
|
+
try { root = ensureRoot(dir); }
|
|
41
|
+
catch (e) { if (e?.code === "E_NO_DEPLOYMENT") refuse("E_NO_DEPLOYMENT", e.message, e.details ?? e.provenance); throw e; }
|
|
42
|
+
// Each home's instance.json, as the listing read it: parsed once for the whole read.
|
|
43
|
+
const records = new Map();
|
|
44
|
+
const data = listInstances(root, undefined, undefined, { records });
|
|
45
|
+
const ws = await statusDrift(data, call, dir);
|
|
46
|
+
const problems = legacyLayoutProblems(root, { records });
|
|
47
|
+
return { root, agents: data, ws, problems };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function statusDocument(call, { root, agents: data, ws, problems }) {
|
|
51
|
+
// The soul key (feature launch-preference): what souls.launch and `oats soul teams <key>` use —
|
|
52
|
+
// from the instances' records, so it needs no remote.
|
|
53
|
+
for (const a of data) a.key = agentSoulKey(a);
|
|
54
|
+
if (ws) for (const a of data) {
|
|
55
|
+
const stamp = ws.souls.get(a.name);
|
|
56
|
+
if (stamp) a.soulSource = { repoKey: stamp.repoKey, commit: stamp.commit, path: stamp.path, ...(stamp.current ? { current: stamp.current, status: stamp.current === stamp.commit ? "current" : "moved" } : {}) };
|
|
57
|
+
for (const i of a.instances || []) {
|
|
58
|
+
const key = i.home ?? `${a.name}/${i.instance}`;
|
|
59
|
+
const rows = ws.drift.get(key);
|
|
60
|
+
if (rows) i.modules = rows.map((r) => ({ name: r.module, from: r.from, commit: r.recorded?.commit ?? null, current: r.current, status: r.status, ...(r.reason ? { reason: r.reason } : {}) }));
|
|
61
|
+
const s = ws.soul.get(key);
|
|
62
|
+
if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}), ...(s.package ? { package: s.package, version: s.version, currentVersion: s.current?.version ?? null } : {}) };
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
const observation = call.maxAge === null ? {} : { observation: call.observation() };
|
|
66
|
+
// `features` (feature server-probe-features): this kernel's own list, as `version --json` answers
|
|
67
|
+
// it, so a remote roster relays the host's without probing it. Never part of a reused observation.
|
|
68
|
+
return { root, agents: data, ...observation, features: KERNEL_FEATURES, sessionViewer: readSessionViewer(), ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery, call.remoteOptions) } } : {}), ...(problems.length ? { problems } : {}), ...answerWarnings() };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Workspace drift for `oats status` (decision 17: shown, not prevented). ONE discovery over
|
|
72
|
+
* the remotes serves every instance; `driftOf` compares each instance's recorded modules to
|
|
73
|
+
* the members' current state (and package modules to the lock), `soulDriftOf` the instance's
|
|
74
|
+
* recorded SOUL SOURCE (instance.json.workspace.soul) to its member's current commit. Offline →
|
|
75
|
+
* { unreachable }. Returns null when the deployment is not a workspace deployment (no
|
|
76
|
+
* oats-local.yaml). `souls` maps each workspace soul NAME (agents/<name>/.oats-soul-source.json
|
|
77
|
+
* present) to its stamp — the roster's `repo:` column for a workspace soul. */
|
|
78
|
+
async function statusDrift(data, call, dir) {
|
|
79
|
+
let ctx;
|
|
80
|
+
try { ctx = loadLocal(dir); }
|
|
81
|
+
catch (e) {
|
|
82
|
+
if (e?.code === "E_LOCAL_MISSING") return null;
|
|
83
|
+
// A 0.25 oats-config.yaml inside the deployment: the typed migration error, never a stack.
|
|
84
|
+
if (e?.code === "E_CONFIG_BROKEN") refuse(e.code, e.message, e.details);
|
|
85
|
+
throw e;
|
|
86
|
+
}
|
|
87
|
+
const hasModules = (i) => i.modules && typeof i.modules === "object" && Object.keys(i.modules).length > 0;
|
|
88
|
+
const hasSoul = (i) => i.workspace && typeof i.workspace === "object" && i.workspace.soul && typeof i.workspace.soul === "object" && typeof i.workspace.soul.repoKey === "string";
|
|
89
|
+
// Workspace souls of this roster: the stamp ensureWorkspaceSoul leaves beside the soul pointer.
|
|
90
|
+
const souls = new Map();
|
|
91
|
+
for (const a of data) {
|
|
92
|
+
if (!a.dir) continue;
|
|
93
|
+
try { const stamp = JSON.parse(readFileSync(join(a.dir, ".oats-soul-source.json"), "utf8")); if (stamp && typeof stamp.repoKey === "string") souls.set(a.name, { repoKey: stamp.repoKey, commit: typeof stamp.commit === "string" ? stamp.commit : null, path: stamp.path ?? null, ...(typeof stamp.package === "string" ? { package: stamp.package, version: stamp.version ?? null } : {}) }); }
|
|
94
|
+
catch { /* not a workspace soul (classic, or an unreadable stamp) */ }
|
|
95
|
+
}
|
|
96
|
+
const anything = data.some((a) => (a.instances || []).some((i) => hasModules(i) || hasSoul(i)));
|
|
97
|
+
if (!anything) return { drift: new Map(), soul: new Map(), souls, unreachable: null, local: ctx.local, discovery: null };
|
|
98
|
+
const deploymentDir = dirname(ctx.path);
|
|
99
|
+
let lock = null;
|
|
100
|
+
try { lock = readLockIfPresent(deploymentDir); } catch { lock = null; }
|
|
101
|
+
let discovery;
|
|
102
|
+
// The standalone view (decisions 10/25) is a discovery too: drift of a standalone
|
|
103
|
+
// instance is computed against its member's current state, not reported "unreachable".
|
|
104
|
+
try { const { discoverOrStandalone } = await import("./member-clone.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: call.remoteOptions() }); }
|
|
105
|
+
catch (e) {
|
|
106
|
+
const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
|
|
107
|
+
return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) }, local: ctx.local, discovery: null };
|
|
108
|
+
}
|
|
109
|
+
const { driftOf, soulDriftOf } = await import("./drift.mjs");
|
|
110
|
+
const drift = new Map();
|
|
111
|
+
const soul = new Map();
|
|
112
|
+
for (const a of data) for (const i of a.instances || []) {
|
|
113
|
+
const key = i.home ?? `${a.name}/${i.instance}`;
|
|
114
|
+
if (hasModules(i)) { try { drift.set(key, driftOf(i, discovery, { lock })); } catch { /* an unreadable module record shows as no drift rows */ } }
|
|
115
|
+
if (hasSoul(i)) { try { const row = soulDriftOf(i, discovery); if (row) soul.set(key, row); } catch { /* an unreadable soul record shows as no soul row */ } }
|
|
116
|
+
}
|
|
117
|
+
// The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
|
|
118
|
+
// First match per key, as `find` gave, from indexes built once (not a scan per agent).
|
|
119
|
+
const packageSoulAt = new Map();
|
|
120
|
+
for (const p of discovery.packageSouls || []) { const k = `${p.package}\0${p.path}`; if (!packageSoulAt.has(k)) packageSoulAt.set(k, p); }
|
|
121
|
+
for (const [, stamp] of souls) {
|
|
122
|
+
if (typeof stamp.package === "string") { const now = packageSoulAt.get(`${stamp.package}\0${stamp.path}`); if (now) stamp.current = now.commit; continue; }
|
|
123
|
+
const member = memberRowByKey(discovery.members, stamp.repoKey);
|
|
124
|
+
if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
|
|
125
|
+
}
|
|
126
|
+
return { drift, soul, souls, unreachable: null, local: ctx.local, discovery };
|
|
127
|
+
}
|
|
128
|
+
/** The deployment's workspace identity in `oats status --json` (feature workspace-identity), read
|
|
129
|
+
* OFFLINE. `key` is the workspace HOST's canonical repo key (parseRepoRef(...).key) and `ref` the
|
|
130
|
+
* reference as oats-local.yaml writes it. The host is the one this run observed, else the one this
|
|
131
|
+
* machine's parsed cache knows: `ref` itself when the cache holds its workspace file, or the host its
|
|
132
|
+
* cached oats-membership.yaml names when `ref` is a member ("workspace"). A member whose host is not
|
|
133
|
+
* known keys as itself ("member"); a ref nothing is known of is taken as the host, as the schema
|
|
134
|
+
* defines `workspace:` ("workspace"). The team model resolves as teamModel resolves it (the default is
|
|
135
|
+
* the local one the workspace allows, else the workspace's; a committed team wins a collision) over the shared teams of, in order, the workspace
|
|
136
|
+
* file this run observed (`teamsFrom: "observed"`), the cached file ("cache": no git process), or none
|
|
137
|
+
* ("local"). `standalone` is the CONFIGURED standalone view only (oats-local.yaml `standalone:`): it
|
|
138
|
+
* reads no workspace file, so its local teams are the whole team model. A run that fell back to the
|
|
139
|
+
* standalone view (the host unreadable) is not: its team model is the workspace's, and its
|
|
140
|
+
* discovery is the member's, never the host's key. */
|
|
141
|
+
function workspaceIdentity(local, discovery, remoteOptions) {
|
|
142
|
+
const ref = local.workspace;
|
|
143
|
+
const standalone = typeof local.standalone === "string" && local.standalone !== "";
|
|
144
|
+
const observed = discovery && discovery.standalone !== true && discovery.workspace ? discovery : null;
|
|
145
|
+
const cached = observed ? null : cachedWorkspace(ref, remoteOptions);
|
|
146
|
+
const keyOf = (r) => { try { return parseRepoRef(r).key; } catch { return null; } };
|
|
147
|
+
let key, keyFrom;
|
|
148
|
+
if (observed) [key, keyFrom] = [observed.key, "workspace"];
|
|
149
|
+
else if (cached && cached.host === null) [key, keyFrom] = [keyOf(ref), "member"];
|
|
150
|
+
else [key, keyFrom] = [keyOf(cached?.host ?? ref), "workspace"];
|
|
151
|
+
if (key === null) keyFrom = null; // a reference parseRepoRef refuses: unusable, never matched
|
|
152
|
+
let shared = null, teamsFrom = "local";
|
|
153
|
+
if (!standalone) {
|
|
154
|
+
if (observed) [shared, teamsFrom] = [observed.workspace, "observed"];
|
|
155
|
+
else if (cached?.file) [shared, teamsFrom] = [cached.file, "cache"];
|
|
156
|
+
}
|
|
157
|
+
const model = teamModel(shared, local);
|
|
158
|
+
// A soul with no souls: default of its own lives here (team model 3: the local default the workspace allows, else the workspace's).
|
|
159
|
+
const deploymentDefault = model.localDefault ?? model.workspaceDefault;
|
|
160
|
+
const labels = [...model.labels.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
|
|
161
|
+
return {
|
|
162
|
+
key, ref, keyFrom, standalone,
|
|
163
|
+
defaultTeam: deploymentDefault === null ? null : { label: deploymentDefault, team: model.labels.get(deploymentDefault)?.team ?? null },
|
|
164
|
+
teams: Object.fromEntries(labels.map((l) => [l, model.labels.get(l).team])),
|
|
165
|
+
teamsFrom,
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
/** What this machine's parsed cache knows of the workspace `ref` names (the values observeWorkspace and
|
|
169
|
+
* confirmMembership stored, each at its repo's last observed commit): { host, file } — `host` the ref
|
|
170
|
+
* of the workspace host, `file` its workspace file or null — when `ref` is the host (its workspace file
|
|
171
|
+
* is cached) or a member whose cached oats-membership.yaml names it (discoverOrStandalone follows the
|
|
172
|
+
* same backlink). A member's backlink is cached whether its own workspace slot was observed (missing)
|
|
173
|
+
* or never was (the host's discovery confirmed it). { host: null, file: null } for a ref cached as
|
|
174
|
+
* having no workspace file and no backlink; null when nothing is known. */
|
|
175
|
+
export function cachedWorkspace(ref, remoteOptions) {
|
|
176
|
+
const options = remoteOptions();
|
|
177
|
+
const cached = (r, item) => {
|
|
178
|
+
const commit = lastObservedCommit(r, options);
|
|
179
|
+
const value = commit ? peekAtCommit(r, commit, item, options) : undefined;
|
|
180
|
+
return value && typeof value === "object" ? value : null;
|
|
181
|
+
};
|
|
182
|
+
const fileOf = (read) => (read && !read.missing && !read.problems && read.value && typeof read.value === "object" ? read.value : null);
|
|
183
|
+
const read = cached(ref, "workspace");
|
|
184
|
+
if (read && !read.missing) return { host: ref, file: fileOf(read) };
|
|
185
|
+
const membership = cached(ref, "membership");
|
|
186
|
+
const host = membership?.kind === "ok" && typeof membership.value?.workspace === "string" ? membership.value.workspace : null;
|
|
187
|
+
if (host !== null) return { host, file: fileOf(cached(host, "workspace")) };
|
|
188
|
+
return read ? { host: null, file: null } : null;
|
|
189
|
+
}
|
|
190
|
+
/** A roster agent's soul key: the qualified name of a package soul, else the recorded agent (soul) name;
|
|
191
|
+
* null when no instance records a workspace soul. Exactly soulKeyOf for the soul it was spawned from. */
|
|
192
|
+
function agentSoulKey(a) {
|
|
193
|
+
for (const i of a.instances || []) {
|
|
194
|
+
const soul = i?.workspace?.soul;
|
|
195
|
+
if (!soul || typeof soul !== "object") continue;
|
|
196
|
+
return soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : (typeof i.agent === "string" ? i.agent : a.name);
|
|
197
|
+
}
|
|
198
|
+
return null;
|
|
199
|
+
}
|
package/lib/schedule.mjs
CHANGED
|
@@ -33,14 +33,15 @@ import { noteRuntimeName } from "./deprecation.mjs";
|
|
|
33
33
|
import { herdrSettingRemoved } from "./errors.mjs";
|
|
34
34
|
import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
|
|
35
35
|
import { pollSourced, tickTriggers } from "./triggers.mjs";
|
|
36
|
-
import {
|
|
37
|
-
import {
|
|
38
|
-
import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, shq, shellWord, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, sessionServerGone, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
|
|
36
|
+
import { SCHEDULE_NAME_RE, HOST_NAME_RE, readSnapshot, hostOf, trusted, parseOwner, MODEL_RE, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
|
|
37
|
+
import { MAX_INSTANCE_NAME, shq, shellWord, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, sessionServerGone, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
|
|
39
38
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
40
39
|
import { readStartExited } from "./session-end.mjs";
|
|
40
|
+
import { childEnv, scopeAutomations } from "./automation-scope.mjs";
|
|
41
|
+
export { SCHEDULE_API } from "./automation-api.mjs";
|
|
42
|
+
export { childEnv, scopeAutomations } from "./automation-scope.mjs";
|
|
41
43
|
|
|
42
44
|
export const SCHEDULE_FILE = "oats-schedules.json";
|
|
43
|
-
export const SCHEDULE_API = 2;
|
|
44
45
|
const ID_RE = SCHEDULE_NAME_RE;
|
|
45
46
|
const HARNESSES = new Set(["pi", "claude", "codex"]);
|
|
46
47
|
const MESSAGE_MAX = 256 * 1024;
|
|
@@ -545,22 +546,6 @@ export function findHomesInScope(ws, instance) {
|
|
|
545
546
|
function scheduleBlock(def, minute) {
|
|
546
547
|
return `\n\n## Scheduled run\n\nThis instance was launched by OATS schedule "${def.workspace?.qid ?? def.id}" for ${minute.toISOString()} (cron "${def.cron}" in ${def.tz}). It is disposable: finish the task above, bring your memory files up to date, and end with \`oats retire --self\`.\n`;
|
|
547
548
|
}
|
|
548
|
-
/** The environment a scheduler-launched oats child runs with: the caller's
|
|
549
|
-
* frozen instance identity and capability snapshot removed (a tick or run-now
|
|
550
|
-
* may be invoked from inside an unrelated instance; dispatch belongs to the
|
|
551
|
-
* job's cwd and explicit selectors, never to that caller), host configuration
|
|
552
|
-
* such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
|
|
553
|
-
export function childEnv() {
|
|
554
|
-
const env = { ...process.env };
|
|
555
|
-
for (const key of [...RESERVED_LAUNCH_ENV,
|
|
556
|
-
"OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
|
|
557
|
-
"OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
|
|
558
|
-
"OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
|
|
559
|
-
"OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
|
|
560
|
-
"OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
|
|
561
|
-
]) delete env[key];
|
|
562
|
-
return env;
|
|
563
|
-
}
|
|
564
549
|
/** The deployment a spawn job runs in (module contract §5, decision 7): the
|
|
565
550
|
* scope's oats-local.yaml. An unreadable one is reported (E_WORKSPACE_SCHEMA)
|
|
566
551
|
* by the spawn, never answered some other way. */
|
|
@@ -937,15 +922,6 @@ export function tickWorkspace(ws, { now = new Date(), firedAt = now, io, reg, ws
|
|
|
937
922
|
return considered;
|
|
938
923
|
}
|
|
939
924
|
|
|
940
|
-
/** One scope's automations context (lib/automations.mjs automationContext) with its oats-local.yaml;
|
|
941
|
-
* an unreadable oats-local.yaml means no workspace automations (the local jobs still run). */
|
|
942
|
-
export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map() } = {}) {
|
|
943
|
-
let local = null;
|
|
944
|
-
try { local = loadLocal(ws).local; } catch { local = null; }
|
|
945
|
-
const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local });
|
|
946
|
-
const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf });
|
|
947
|
-
return Object.assign(ctx, { ws, local });
|
|
948
|
-
}
|
|
949
925
|
/** A stored minute key as a time, or null when it is not one. */
|
|
950
926
|
function minuteTime(key) {
|
|
951
927
|
const t = typeof key === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(key) ? Date.parse(`${key}:00Z`) : NaN;
|
package/lib/semver.mjs
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/** The order of two kernel or package versions. A leaf (awebai/oats#1630): `oats workspace status`
|
|
2
|
+
* compares versions without loading servers.mjs, which imports it and re-exports it. */
|
|
3
|
+
|
|
4
|
+
export function compareSemver(a, b) {
|
|
5
|
+
const pa = String(a).split(/[.-]/).map((x) => Number.parseInt(x, 10));
|
|
6
|
+
const pb = String(b).split(/[.-]/).map((x) => Number.parseInt(x, 10));
|
|
7
|
+
for (let i = 0; i < 3; i++) {
|
|
8
|
+
const d = (pa[i] || 0) - (pb[i] || 0);
|
|
9
|
+
if (d) return d;
|
|
10
|
+
}
|
|
11
|
+
return 0;
|
|
12
|
+
}
|
package/lib/servers.mjs
CHANGED
|
@@ -25,11 +25,14 @@ import { parseStrictJson } from "./canonical-json.mjs";
|
|
|
25
25
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
26
26
|
import { readWaitingClaim } from "./instance-events.mjs";
|
|
27
27
|
import { readRetireState } from "./retire-state.mjs";
|
|
28
|
+
import { SESSION_END } from "./session-resume-contract.mjs";
|
|
28
29
|
import { paletteColor } from "./instance-color.mjs";
|
|
29
30
|
import { withDirLock } from "./dir-lock.mjs";
|
|
30
|
-
import { shellWord } from "./
|
|
31
|
+
import { shellWord } from "./shell-word.mjs";
|
|
31
32
|
import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
|
|
32
33
|
import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, readLoginFrame } from "./login-environment.mjs";
|
|
34
|
+
import { compareSemver } from "./semver.mjs";
|
|
35
|
+
export { compareSemver } from "./semver.mjs";
|
|
33
36
|
|
|
34
37
|
const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
|
|
35
38
|
export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
|
|
@@ -529,16 +532,6 @@ export const SESSION_REMOTE_VERSION = "0.22.2";
|
|
|
529
532
|
* moves to 0.22.2 with that release. */
|
|
530
533
|
export const MIN_REMOTE_VERSION = "0.22.1";
|
|
531
534
|
|
|
532
|
-
export function compareSemver(a, b) {
|
|
533
|
-
const pa = String(a).split(/[.-]/).map((x) => Number.parseInt(x, 10));
|
|
534
|
-
const pb = String(b).split(/[.-]/).map((x) => Number.parseInt(x, 10));
|
|
535
|
-
for (let i = 0; i < 3; i++) {
|
|
536
|
-
const d = (pa[i] || 0) - (pb[i] || 0);
|
|
537
|
-
if (d) return d;
|
|
538
|
-
}
|
|
539
|
-
return 0;
|
|
540
|
-
}
|
|
541
|
-
|
|
542
535
|
// ---------------------------------------------------------------- snapshots
|
|
543
536
|
|
|
544
537
|
export function snapshotPath(serverId, instance) {
|
|
@@ -913,6 +906,11 @@ const rowRetire = (i) => {
|
|
|
913
906
|
/** `sameWork` (feature instance-same-work) as `background`: relayed ONLY when the host's row says
|
|
914
907
|
* `sameWork: true`, the one value a row carries; anything else, and a host that omits it, is absent. */
|
|
915
908
|
const rowSameWork = (i) => (i.sameWork === true ? { sameWork: true } : {});
|
|
909
|
+
/** `sessionEnd` (feature session-resume, #1628) as `retire` is: relayed ONLY when the host's row has the
|
|
910
|
+
* key, which a host whose kernel predates the feature never sends, so its rows say nothing. A value that
|
|
911
|
+
* is not one of the contract's (lib/session-resume-contract.mjs SESSION_END) drops the key. */
|
|
912
|
+
const SESSION_ENDS = new Set(Object.values(SESSION_END));
|
|
913
|
+
const rowSessionEnd = (i) => (SESSION_ENDS.has(i.sessionEnd) ? { sessionEnd: i.sessionEnd } : {});
|
|
916
914
|
|
|
917
915
|
/** The bounds a host's `features` list must meet to be relayed (feature server-probe-features). */
|
|
918
916
|
export const HOST_FEATURES_MAX = 256;
|
|
@@ -1015,7 +1013,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
1015
1013
|
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
|
|
1016
1014
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
1017
1015
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
1018
|
-
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i),
|
|
1016
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i), ...rowSessionEnd(i),
|
|
1019
1017
|
// Every row the host reports is addressed by its home, saved
|
|
1020
1018
|
// route or not; savedRoute says only that it was spawned from here.
|
|
1021
1019
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
package/lib/session-end.mjs
CHANGED
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
* - `.oats-start-exited`: the window a spawn or a start made writes it when the harness exits,
|
|
5
5
|
* `{"startId":"<id>","status":<n>}` (the harness's exit status). A kernel before 0.69 wrote the
|
|
6
6
|
* start id alone on one line, and only from a start's window.
|
|
7
|
-
* - `.oats-stop.json`: `oats instance stop` / `oats session stop`,
|
|
8
|
-
* startId }`; `startId` (0.69) is the
|
|
7
|
+
* - `.oats-stop.json`: `oats instance stop` / `oats session stop`, a retire and a restart (before
|
|
8
|
+
* they end the session), `{ instance, at, stop, retained, startId }`; `startId` (0.69) is the
|
|
9
|
+
* start the stop ended, null when the home had none.
|
|
9
10
|
* A reboot or a killed tmux server leaves neither file for the start that was running: that is a
|
|
10
11
|
* lost session, the one a resume brings back. Dependency-free: status, start --resume and the
|
|
11
12
|
* schedule runner read the files through here. */
|
package/lib/session-input.mjs
CHANGED
|
@@ -56,6 +56,9 @@ export function inspectSessionTarget(target, io, { includeSize = false, includeP
|
|
|
56
56
|
const state = createSessionPaneInspector(io)(rows, { includeSize, name: target.window });
|
|
57
57
|
return includePanes ? { ...state, panes: rows.length } : state;
|
|
58
58
|
}
|
|
59
|
+
/** The shell/descendant rule's answer when the process table cannot establish it (#1641): unknown,
|
|
60
|
+
* never a fallback shell, with the reason status carries as `runtimeError`. */
|
|
61
|
+
const unestablished = (why) => new Error(`${why}, so whether the harness runs cannot be told`);
|
|
59
62
|
/** Interpret one window's panes: resolve the agent's pane (resolveAgentPane, `name` the window's
|
|
60
63
|
* instance name), then judge that pane alone with the lifecycle's shell/descendant rule; the other
|
|
61
64
|
* panes never make it unknown. Each row is `id, dead, command, pid[, cols, rows], mark` (the mark may
|
|
@@ -63,17 +66,27 @@ export function inspectSessionTarget(target, io, { includeSize = false, includeP
|
|
|
63
66
|
* process scans cost one child. */
|
|
64
67
|
export function createSessionPaneInspector(io) {
|
|
65
68
|
let processRead;
|
|
69
|
+
// Rows are `{ pid, ppid, name }`, `name` "" when ps printed none. A line that is not a process row
|
|
70
|
+
// is never dropped silently: `malformed` keeps the snapshot from proving a fallback shell.
|
|
66
71
|
const readProcesses = () => {
|
|
67
72
|
if (!processRead) {
|
|
68
73
|
try {
|
|
69
74
|
const output = (io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,comm="], {
|
|
70
75
|
encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
|
|
71
76
|
});
|
|
72
|
-
|
|
77
|
+
const rows = [];
|
|
78
|
+
let malformed = false;
|
|
79
|
+
for (const line of output.split("\n")) {
|
|
80
|
+
if (!line.trim()) continue;
|
|
81
|
+
const row = line.trim().match(/^(\d+)\s+(\d+)(?:\s+(.*))?$/);
|
|
82
|
+
if (row) rows.push({ pid: row[1], ppid: row[2], name: row[3] ?? "" });
|
|
83
|
+
else malformed = true;
|
|
84
|
+
}
|
|
85
|
+
processRead = { rows, malformed };
|
|
73
86
|
} catch (error) { processRead = { error }; }
|
|
74
87
|
}
|
|
75
88
|
if (processRead.error) throw processRead.error;
|
|
76
|
-
return processRead
|
|
89
|
+
return processRead;
|
|
77
90
|
};
|
|
78
91
|
return (rows, { includeSize = false, name } = {}) => {
|
|
79
92
|
if (!rows.length) return { backend: "tmux", present: false, state: "stopped" };
|
|
@@ -95,26 +108,37 @@ export function createSessionPaneInspector(io) {
|
|
|
95
108
|
// A missing tmux label can still be a fallback shell. Only the pane's
|
|
96
109
|
// own comm can establish that; an optional failed read stays unknown.
|
|
97
110
|
try {
|
|
98
|
-
const own = readProcesses().find((
|
|
99
|
-
shell = own ? isShellProcess(own
|
|
111
|
+
const own = readProcesses().rows.find((p) => p.pid === panePid);
|
|
112
|
+
shell = own ? isShellProcess(own.name) : false;
|
|
100
113
|
} catch { /* missing process information is not proof of a fallback shell */ }
|
|
101
114
|
}
|
|
102
115
|
if (dead === "0" && shell) {
|
|
103
|
-
//
|
|
104
|
-
//
|
|
116
|
+
// tmux names the pane's foreground process group's leader: the launch's own shell
|
|
117
|
+
// (default-shell -c) while the harness runs as its child, on macOS and Linux alike.
|
|
118
|
+
// Only the pane's own process, in the snapshot as a shell, with no non-shell
|
|
119
|
+
// descendant, is a fallback prompt. A live non-shell process is the harness running;
|
|
120
|
+
// anything else is unknown, never the prompt (#1641).
|
|
105
121
|
if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
|
|
106
|
-
const processes = readProcesses();
|
|
122
|
+
const { rows: processes, malformed } = readProcesses();
|
|
123
|
+
const own = processes.find((p) => p.pid === panePid);
|
|
124
|
+
// A ps that cannot see the pane (another PID namespace, a sandbox) or a pane respawned since
|
|
125
|
+
// tmux answered.
|
|
126
|
+
if (!own) throw unestablished(`the process table has no process ${panePid}, the agent's pane's own`);
|
|
107
127
|
const descendants = new Set([panePid]);
|
|
108
|
-
let active =
|
|
128
|
+
let active = !isShellProcess(own.name) && own.name !== "", unnamed = own.name === "" ? own.pid : null;
|
|
109
129
|
for (let changed = true; changed;) {
|
|
110
130
|
changed = false;
|
|
111
|
-
for (const
|
|
112
|
-
if (descendants.has(
|
|
131
|
+
for (const { pid, ppid, name } of processes) {
|
|
132
|
+
if (descendants.has(ppid) && !descendants.has(pid)) {
|
|
113
133
|
descendants.add(pid); changed = true;
|
|
114
|
-
if (
|
|
134
|
+
if (name === "") unnamed ??= pid;
|
|
135
|
+
else if (!isShellProcess(name)) active = true;
|
|
115
136
|
}
|
|
116
137
|
}
|
|
117
138
|
}
|
|
139
|
+
if (!active && unnamed !== null) throw unestablished(`process ${unnamed} in the agent's pane has no command name in the process table`);
|
|
140
|
+
// A line that is not a process row may be one of the pane's processes.
|
|
141
|
+
if (!active && malformed) throw unestablished("the process table has a line that is not a process");
|
|
118
142
|
state = active ? "unknown" : "shell";
|
|
119
143
|
}
|
|
120
144
|
return { backend: "tmux", present: dead === "0", state, paneId,
|