@awebai/oats 0.49.0 → 0.51.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 +150 -34
- package/docs/capabilities.md +172 -2
- package/docs/capability-manifest.schema.json +42 -0
- package/docs/configuration.md +97 -0
- package/docs/desktop-cli-api.md +268 -22
- package/docs/desktop.md +13 -0
- package/docs/execution-targets.md +120 -9
- package/docs/implementation.md +26 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +20 -7
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/schedules.md +228 -15
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +92 -8
- package/docs/workspaces.md +2 -2
- package/lib/capability-show.mjs +14 -1
- package/lib/claim.mjs +126 -0
- package/lib/core.mjs +428 -102
- package/lib/instance-events.mjs +3 -7
- package/lib/instance-git.mjs +8 -5
- package/lib/instance-inspect.mjs +44 -15
- package/lib/refused-text.mjs +17 -0
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/schedule.mjs +8 -2
- package/lib/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +521 -60
- package/lib/worktree-hooks.mjs +24 -9
- package/lib/worktree.mjs +14 -86
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/lib/worktree-hooks.mjs
CHANGED
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
* is a test seam, not a setting. */
|
|
18
18
|
import { spawn as spawnProcess, execFileSync, spawnSync } from "node:child_process";
|
|
19
19
|
import { closeSync, existsSync, fchmodSync, mkdirSync, openSync, readFileSync, realpathSync, writeSync } from "node:fs";
|
|
20
|
-
import { dirname, join } from "node:path";
|
|
20
|
+
import { dirname, isAbsolute, join } from "node:path";
|
|
21
21
|
import { terminateGroup, watchGroup, TERM_GRACE_MS } from "./process-group.mjs";
|
|
22
22
|
|
|
23
23
|
export const WORKTREE_HOOK_TIMEOUT_MS = 30 * 60 * 1000;
|
|
@@ -36,12 +36,25 @@ export const interruptExitStatus = (signal) => 128 + (SIGNAL_NUMBERS[signal] ??
|
|
|
36
36
|
// ---------- process identity: a pid is verified by its start time ----------
|
|
37
37
|
|
|
38
38
|
/** Where a start time is read: /proc when this host has procfs, else `ps`. The test seam
|
|
39
|
-
* OATS_TEST_PROCESS_START_PS
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
39
|
+
* OATS_TEST_PROCESS_START_PS (not a setting; a launch configuration cannot set it) takes the `ps`
|
|
40
|
+
* path on any host: `1` runs the system `ps`, an absolute path runs that file as `ps`, and any
|
|
41
|
+
* other value reads no start at all (psProgram). */
|
|
42
|
+
const readsProc = () => process.env.OATS_TEST_PROCESS_START_PS === undefined && existsSync("/proc/self/stat");
|
|
43
|
+
/** `ps` runs with a fixed environment, nothing inherited. Its PATH is the system directories only,
|
|
44
|
+
* never the caller's: what `ps` reports is the identity a claim is held or taken over on, so the
|
|
45
|
+
* caller's PATH must not choose the program, and a caller whose PATH holds no `ps` reads the same
|
|
46
|
+
* start as any other. `lstart` is local time in the locale's format, and two readers with another
|
|
47
|
+
* TZ or LANG would otherwise read one live process's start differently, and take it for another. */
|
|
48
|
+
const PS_ENV = Object.freeze({ PATH: "/usr/bin:/bin", LC_ALL: "C", TZ: "UTC" });
|
|
49
|
+
/** The `ps` a start is read with → { file, name } | { reason }: the system one, or the file the
|
|
50
|
+
* test seam names by absolute path, run directly (no shell). A seam that names neither is never a
|
|
51
|
+
* fallback to /proc or to a `ps` found on PATH; nor is a named file that cannot be run (readStart). */
|
|
52
|
+
function psProgram() {
|
|
53
|
+
const seam = process.env.OATS_TEST_PROCESS_START_PS;
|
|
54
|
+
if (seam === undefined || seam === "1") return { file: "ps", name: "ps" };
|
|
55
|
+
if (isAbsolute(seam)) return { file: seam, name: `the ps OATS_TEST_PROCESS_START_PS names (${seam})` };
|
|
56
|
+
return { reason: `OATS_TEST_PROCESS_START_PS is ${JSON.stringify(seam)}, neither 1 nor an absolute path` };
|
|
57
|
+
}
|
|
45
58
|
|
|
46
59
|
/** Whether `pid` exists, from the kernel itself: kill(pid, 0). ESRCH is gone; EPERM (another user's
|
|
47
60
|
* process) and success are "exists"; anything else is unknown. Never from how procfs or `ps`
|
|
@@ -68,9 +81,11 @@ function readStart(pid) {
|
|
|
68
81
|
const start = fields[19]; // field 22 overall: after pid, comm and the 19 before it
|
|
69
82
|
return /^[0-9]+$/.test(start ?? "") ? { state: "alive", token: `proc:${start}` } : { state: "unknown", reason: `/proc/${pid}/stat has no start time` };
|
|
70
83
|
}
|
|
71
|
-
const
|
|
84
|
+
const ps = psProgram();
|
|
85
|
+
if (ps.reason) return { state: "unknown", reason: ps.reason };
|
|
86
|
+
const r = spawnSync(ps.file, ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], env: PS_ENV, timeout: 10_000 });
|
|
72
87
|
const out = String(r.stdout ?? "").trim(), err = String(r.stderr ?? "").trim();
|
|
73
|
-
if (r.error) return { state: "unknown", reason:
|
|
88
|
+
if (r.error) return { state: "unknown", reason: `${ps.name} could not be run (${r.error.code || r.error.message})` };
|
|
74
89
|
if (r.status === 0 && out) return { state: "alive", token: `ps:${out}` };
|
|
75
90
|
return { state: "unknown", reason: `ps -o lstart= -p ${pid} answered ${r.status === null ? `signal ${r.signal}` : `exit ${r.status}`}${err ? `: ${err.split("\n")[0]}` : out ? " with output" : " with no output"}` };
|
|
76
91
|
}
|
package/lib/worktree.mjs
CHANGED
|
@@ -27,8 +27,8 @@ import { recordedTeams } from "./teams.mjs";
|
|
|
27
27
|
import { canonicalCloneKey, memberCloneOf } from "./instance-resolution.mjs";
|
|
28
28
|
import { loadLocal } from "./workspace.mjs";
|
|
29
29
|
import { GIT_FETCH_TIMEOUT_MS } from "./remote.mjs";
|
|
30
|
-
import { randomBytes } from "node:crypto";
|
|
31
30
|
import { terminateGroup, watchGroup } from "./process-group.mjs";
|
|
31
|
+
import { CLAIM_WAIT_MS, acquireClaim, recordInClaim, releaseClaim } from "./claim.mjs";
|
|
32
32
|
import {
|
|
33
33
|
cloneOfMember, instanceSoulDir, isCapturedHome, isWorkspaceHome, capturedHomeRefusal, preWorkspaceHome, lifecycleHookEnv,
|
|
34
34
|
retirePendingMarkerPath, stableSoulId, workspaceOf,
|
|
@@ -348,101 +348,29 @@ function withPurposeClaim(home, purpose, fn) {
|
|
|
348
348
|
return withClaim(lock, fn, { busy });
|
|
349
349
|
}
|
|
350
350
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
const pauseSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
|
354
|
-
function readClaim(path) {
|
|
355
|
-
try { const o = JSON.parse(readFileSync(path, "utf8")); return o && typeof o === "object" ? o : { unreadable: true }; }
|
|
356
|
-
catch (e) { return e.code === "ENOENT" ? null : { unreadable: true }; }
|
|
357
|
-
}
|
|
358
|
-
|
|
359
|
-
/** Run `fn` holding the claim file `path`. Exported for its tests.
|
|
351
|
+
/** Run `fn` holding the claim file `path` (lib/claim.mjs: how a claim is taken, taken over from a
|
|
352
|
+
* dead holder and released). Exported for its tests.
|
|
360
353
|
*
|
|
361
|
-
*
|
|
362
|
-
*
|
|
363
|
-
*
|
|
364
|
-
*
|
|
365
|
-
* is removed under a second claim,
|
|
366
|
-
* `<path>.reclaim-<owner nonce>`, taken by this same protocol. Its holder re-reads `path` and
|
|
367
|
-
* removes it only if it still names that owner. Nothing else removes another's claim: its
|
|
368
|
-
* owner never releases it, and a new acquirer cannot write over an existing file. Two takeovers
|
|
369
|
-
* of one dead owner are therefore serialized, and neither removes a claim made after it read.
|
|
370
|
-
* A takeover cut short leaves its own claim behind, which the next takeover takes over in
|
|
371
|
-
* turn, up to CLAIM_MAX_DEPTH nested levels.
|
|
372
|
-
* - The holder's running git step (`gitPid`, `gitStart`; trackedGit) is in the claim. A takeover
|
|
373
|
-
* ends it first (endRecordedGit) and refuses, keeping the claim, if it cannot be ended.
|
|
374
|
-
* - Released by unlinking `path`, only while it still names this holding.
|
|
375
|
-
* - An unreadable claim file is never removed: the command is refused as busy, naming the file. */
|
|
354
|
+
* The holder's running git step (`gitPid`, `gitStart`; trackedGit) is in the claim. A takeover
|
|
355
|
+
* ends it first (endRecordedGit) and refuses, keeping the claim, if it cannot be ended.
|
|
356
|
+
* `fn({ track, warnings })`; → Promise of what `fn` returns. An error with `keepClaim` leaves the
|
|
357
|
+
* claim held, for the step it names. */
|
|
376
358
|
export async function withClaim(path, fn, { busy, waitMs = CLAIM_WAIT_MS } = {}) {
|
|
377
359
|
const warnings = [];
|
|
378
|
-
const me = acquireClaim(path, {
|
|
360
|
+
const me = acquireClaim(path, {
|
|
361
|
+
busy, waitMs, warnings,
|
|
362
|
+
ownStartUnreadable: (_reason, at) => Object.assign(busy(null), { message: `this process's start time cannot be read, so it cannot hold ${at} verifiably; nothing was done` }),
|
|
363
|
+
unreadableClaim: (at) => Object.assign(busy(null), { message: `${at} is not a readable claim; inspect it and remove it if no oats worktree command holds it; nothing was done` }),
|
|
364
|
+
endHolderStep: (holder, at) => ({ ...endRecordedGit(holder, at), details: { gitPid: holder.gitPid, gitStart: holder.gitStart ?? null } }),
|
|
365
|
+
});
|
|
379
366
|
// Record (or clear) the holder's running git step in the claim; only its live holder writes it.
|
|
380
|
-
const track = (gitStep) =>
|
|
381
|
-
const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
|
|
382
|
-
writeFileSync(tmp, JSON.stringify({ ...me, ...(gitStep ?? {}) }) + "\n", { mode: 0o600 });
|
|
383
|
-
renameSync(tmp, path);
|
|
384
|
-
};
|
|
367
|
+
const track = (gitStep) => recordInClaim(path, me, gitStep);
|
|
385
368
|
let keep = false;
|
|
386
369
|
try { return await fn({ track, warnings }); }
|
|
387
370
|
catch (e) { keep = e?.keepClaim === true; throw e; }
|
|
388
371
|
finally { if (!keep) releaseClaim(path, me); }
|
|
389
372
|
}
|
|
390
373
|
|
|
391
|
-
function acquireClaim(path, opts, depth) {
|
|
392
|
-
const { busy, waitMs } = opts;
|
|
393
|
-
const self = selfIdentity();
|
|
394
|
-
if (!self.processStart) throw Object.assign(busy(null), { message: `this process's start time cannot be read, so it cannot hold ${path} verifiably; nothing was done` });
|
|
395
|
-
const me = { ...self, nonce: randomBytes(16).toString("hex"), at: new Date().toISOString() };
|
|
396
|
-
const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
|
|
397
|
-
writeFileSync(tmp, JSON.stringify(me) + "\n", { mode: 0o600 });
|
|
398
|
-
try {
|
|
399
|
-
const deadline = Date.now() + waitMs;
|
|
400
|
-
for (;;) {
|
|
401
|
-
try { linkSync(tmp, path); return me; }
|
|
402
|
-
catch (e) { if (e.code !== "EEXIST") throw e; }
|
|
403
|
-
const holder = readClaim(path);
|
|
404
|
-
if (holder === null) continue; // released in between
|
|
405
|
-
if (holder.unreadable) throw Object.assign(busy(null), { message: `${path} is not a readable claim; inspect it and remove it if no oats worktree command holds it; nothing was done` });
|
|
406
|
-
const live = processLiveness(holder);
|
|
407
|
-
// Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
|
|
408
|
-
if (live.state === "unknown") throw busy(holder, live.reason, path);
|
|
409
|
-
if (live.state === "gone") {
|
|
410
|
-
if (depth >= CLAIM_MAX_DEPTH || typeof holder.nonce !== "string" || !/^[0-9a-f]{32}$/.test(holder.nonce)) throw busy(holder, null, path);
|
|
411
|
-
takeOver(path, holder, opts, depth);
|
|
412
|
-
continue;
|
|
413
|
-
}
|
|
414
|
-
if (Date.now() >= deadline) throw busy(holder, null, path);
|
|
415
|
-
pauseSync(50);
|
|
416
|
-
}
|
|
417
|
-
} finally {
|
|
418
|
-
try { unlinkSync(tmp); } catch { /* gone */ }
|
|
419
|
-
}
|
|
420
|
-
}
|
|
421
|
-
|
|
422
|
-
/** Remove `path`, held by the dead `holder`, under the claim that serializes takeovers of it. */
|
|
423
|
-
function takeOver(path, holder, opts, depth) {
|
|
424
|
-
const reclaim = `${path}.reclaim-${holder.nonce}`;
|
|
425
|
-
const me = acquireClaim(reclaim, opts, depth + 1);
|
|
426
|
-
try {
|
|
427
|
-
const now = readClaim(path);
|
|
428
|
-
if (now?.nonce === holder.nonce) {
|
|
429
|
-
const ended = endRecordedGit(now, path);
|
|
430
|
-
if (ended.owed) {
|
|
431
|
-
const e = opts.busy(now);
|
|
432
|
-
throw Object.assign(e, { message: `${ended.owed}; ${path} is kept and nothing was done — ${ended.remedy}`, details: { ...e.details, gitPid: now.gitPid, gitStart: now.gitStart ?? null } });
|
|
433
|
-
}
|
|
434
|
-
if (ended.warning) opts.warnings?.push(ended.warning);
|
|
435
|
-
unlinkSync(path);
|
|
436
|
-
}
|
|
437
|
-
} finally {
|
|
438
|
-
releaseClaim(reclaim, me);
|
|
439
|
-
}
|
|
440
|
-
}
|
|
441
|
-
|
|
442
|
-
function releaseClaim(path, me) {
|
|
443
|
-
if (readClaim(path)?.nonce === me.nonce) { try { unlinkSync(path); } catch { /* gone */ } }
|
|
444
|
-
}
|
|
445
|
-
|
|
446
374
|
/** A `creating` record whose adder may still run: its start cannot be read. Never rolled back on
|
|
447
375
|
* that; the refusal names the pid and the record's exact path, the way out once the pid is
|
|
448
376
|
* checked by hand. */
|
package/package-catalog.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"packages": {
|
|
4
4
|
"oats.okf": {
|
|
5
5
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
6
|
-
"ref": "v5.0.
|
|
6
|
+
"ref": "v5.0.1",
|
|
7
7
|
"path": "oats-package"
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.24.1",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
"oats.framework": {
|
|
45
45
|
"url": "https://github.com/awebai/oats.git",
|
|
46
|
-
"ref": "oats-framework/v1.
|
|
46
|
+
"ref": "oats-framework/v1.9.1",
|
|
47
47
|
"path": "oats-package"
|
|
48
48
|
}
|
|
49
49
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.51.0",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -60,7 +60,7 @@ members:
|
|
|
60
60
|
- git:github.com/acme/agents # the host is a member too
|
|
61
61
|
- git:github.com/acme/platform
|
|
62
62
|
packages:
|
|
63
|
-
oats.framework: v1.
|
|
63
|
+
oats.framework: v1.9.1 # bare versions resolve through the official catalog
|
|
64
64
|
oats.okf: v4.1.1
|
|
65
65
|
defaults:
|
|
66
66
|
capabilities: { oats.core: { from: package } }
|