@awebai/oats 0.58.0 → 0.60.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 +1 -1
- package/docs/desktop-cli-api.md +80 -8
- package/docs/desktop.md +30 -3
- package/docs/execution-targets.md +18 -2
- package/docs/implementation.md +3 -0
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +4 -4
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.59.0.md +288 -0
- package/docs/release-notes/v0.60.0.md +104 -0
- package/docs/servers.md +4 -1
- package/docs/souls-and-instances.md +21 -0
- package/docs/tui.md +753 -119
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +258 -57
- package/lib/read-ahead-worker.mjs +119 -0
- package/lib/read-ahead.mjs +115 -0
- package/lib/retire-state.mjs +33 -0
- package/lib/servers.mjs +9 -1
- package/lib/session-input.mjs +53 -26
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/capability-catalog.mjs +93 -0
- package/packages/client/capability-facts.mjs +59 -0
- package/packages/client/capability-rows.mjs +121 -0
- package/packages/client/catalog-messages.mjs +12 -0
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/instance-acts.mjs +23 -8
- package/packages/client/instance-presentation.mjs +3 -2
- package/packages/client/instance-tree.mjs +84 -39
- package/packages/client/lifecycle-confirmation.mjs +9 -3
- package/packages/client/remote-roster.mjs +4 -1
- package/packages/client/retire-in-flight.mjs +65 -0
- package/packages/client/retire-state.mjs +30 -0
- package/packages/client/soul-catalog.mjs +8 -0
- package/packages/client/soul-facts.mjs +7 -0
- package/packages/client/spawn-apply.mjs +13 -4
- package/packages/client/spawn-messages.mjs +8 -0
- package/packages/client/subsequence-score.mjs +15 -0
- package/packages/tui/README.md +23 -10
- package/packages/tui/lib/actions.mjs +63 -5
- package/packages/tui/lib/client.mjs +17 -1
- package/packages/tui/lib/config.mjs +7 -2
- package/packages/tui/lib/main.mjs +364 -82
- package/packages/tui/lib/model.mjs +614 -57
- package/packages/tui/lib/panel.mjs +436 -125
- package/packages/tui/lib/read.mjs +52 -26
- package/packages/tui/lib/store.mjs +1025 -65
- package/packages/tui/lib/term/keys.mjs +9 -2
- package/packages/tui/lib/term/text.mjs +4 -0
- package/packages/tui/lib/term/through.mjs +12 -1
- package/packages/tui/lib/views/capabilities.mjs +239 -0
- package/packages/tui/lib/views/frame.mjs +433 -99
- package/packages/tui/lib/views/help.mjs +61 -15
- package/packages/tui/lib/views/instances.mjs +43 -25
- package/packages/tui/lib/views/palette.mjs +66 -0
- package/packages/tui/lib/views/souls.mjs +270 -0
- package/packages/tui/lib/views/spawn.mjs +301 -0
- package/packages/tui/lib/views/split.mjs +29 -0
- package/skills/oats-getting-started/SKILL.md +2 -2
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/** The threads of read-ahead.mjs: one planner and its readers. They only read,
|
|
2
|
+
* and only to bring files into the page cache: every result and every error
|
|
3
|
+
* is dropped. Nothing they do is part of a digest.
|
|
4
|
+
*
|
|
5
|
+
* The planner walks each root of a job in the order the digest will read it
|
|
6
|
+
* and hands each regular file to a free reader. It never gets more than the
|
|
7
|
+
* window (`windowKiB`, `windowFiles`) ahead of what the digest has read
|
|
8
|
+
* (CONSUMED_KIB, CONSUMED_FILES, which read-ahead.mjs counts), so the cache
|
|
9
|
+
* it fills is read before it can be evicted. A file larger than the window
|
|
10
|
+
* is passed over: the digest reads it itself, as one sequential read. A job
|
|
11
|
+
* ends when the digest finishes and moves JOB on; whatever is still queued
|
|
12
|
+
* is then dropped. */
|
|
13
|
+
import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync } from "node:fs";
|
|
14
|
+
import { sep } from "node:path";
|
|
15
|
+
import { parentPort, workerData, Worker } from "node:worker_threads";
|
|
16
|
+
import { CTL } from "./read-ahead.mjs";
|
|
17
|
+
|
|
18
|
+
const ctl = workerData.ctl;
|
|
19
|
+
const current = (job) => Atomics.load(ctl, CTL.JOB) === job;
|
|
20
|
+
|
|
21
|
+
if (workerData.role === "reader") {
|
|
22
|
+
// One read at a time, through one reused buffer: a reader holds CHUNK bytes, whatever the file's size.
|
|
23
|
+
const CHUNK = 1 << 20;
|
|
24
|
+
const buffer = Buffer.allocUnsafe(CHUNK);
|
|
25
|
+
// O_NONBLOCK: a FIFO put in a file's place since the planner's lstat never blocks the open.
|
|
26
|
+
const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
|
|
27
|
+
parentPort.on("message", ({ job, path }) => {
|
|
28
|
+
if (current(job)) {
|
|
29
|
+
const inFlight = Atomics.add(ctl, CTL.IN_FLIGHT, 1) + 1;
|
|
30
|
+
if (inFlight > Atomics.load(ctl, CTL.MAX_IN_FLIGHT)) Atomics.store(ctl, CTL.MAX_IN_FLIGHT, inFlight);
|
|
31
|
+
try {
|
|
32
|
+
const fd = openSync(path, flags);
|
|
33
|
+
try { if (fstatSync(fd).isFile()) while (current(job) && readSync(fd, buffer, 0, CHUNK, null) > 0); }
|
|
34
|
+
finally { closeSync(fd); }
|
|
35
|
+
} catch { /* the digest reads this file itself, and reports what it finds */ }
|
|
36
|
+
Atomics.sub(ctl, CTL.IN_FLIGHT, 1);
|
|
37
|
+
}
|
|
38
|
+
parentPort.postMessage(0);
|
|
39
|
+
});
|
|
40
|
+
} else {
|
|
41
|
+
const { readers: count, windowKiB, windowFiles } = workerData;
|
|
42
|
+
const readers = [];
|
|
43
|
+
const free = [];
|
|
44
|
+
let wake = null;
|
|
45
|
+
const woken = () => { const w = wake; wake = null; w?.(); };
|
|
46
|
+
for (let i = 0; i < count; i++) {
|
|
47
|
+
const reader = new Worker(new URL(import.meta.url), { workerData: { role: "reader", ctl } });
|
|
48
|
+
reader.on("error", () => {}); // a reader that fails is one reader fewer
|
|
49
|
+
reader.on("message", () => { free.push(reader); woken(); });
|
|
50
|
+
readers.push(reader);
|
|
51
|
+
free.push(reader);
|
|
52
|
+
}
|
|
53
|
+
const SEP = Buffer.from(sep);
|
|
54
|
+
const join = (dir, name) => Buffer.concat([dir, SEP, name]);
|
|
55
|
+
// The digest's order of a directory's names (fingerprintTrees): their bytes,
|
|
56
|
+
// or, for the legacy stored digest, their text by localeCompare.
|
|
57
|
+
const names = (dir, order) => {
|
|
58
|
+
const list = readdirSync(dir, { encoding: "buffer" });
|
|
59
|
+
return order === "locale"
|
|
60
|
+
? list.map((bytes) => ({ bytes, name: bytes.toString("utf8") })).sort((a, b) => a.name.localeCompare(b.name)).map((e) => e.bytes)
|
|
61
|
+
: list.sort(Buffer.compare);
|
|
62
|
+
};
|
|
63
|
+
// The regular files under `root` in walk order, with their sizes, passing
|
|
64
|
+
// over what the digest passes over. An entry that cannot be read is skipped.
|
|
65
|
+
function* files(root, { order, excludeRoot, excludePaths }) {
|
|
66
|
+
let st;
|
|
67
|
+
try { st = lstatSync(root); } catch { return; }
|
|
68
|
+
if (st.isFile()) { yield [root, st.size]; return; }
|
|
69
|
+
if (!st.isDirectory()) return;
|
|
70
|
+
const walk = function* (dir, rel) {
|
|
71
|
+
let list;
|
|
72
|
+
try { list = names(dir, order); } catch { return; }
|
|
73
|
+
for (const name of list) {
|
|
74
|
+
const childRel = rel ? Buffer.concat([rel, SEP, name]) : name;
|
|
75
|
+
if ((!rel && excludeRoot.has(name.toString("utf8"))) || (excludePaths.size && excludePaths.has(childRel.toString("hex")))) continue;
|
|
76
|
+
const path = join(dir, name);
|
|
77
|
+
let entry;
|
|
78
|
+
try { entry = lstatSync(path); } catch { continue; }
|
|
79
|
+
if (entry.isDirectory()) yield* walk(path, childRel);
|
|
80
|
+
else if (entry.isFile()) yield [path, entry.size];
|
|
81
|
+
}
|
|
82
|
+
};
|
|
83
|
+
yield* walk(root, null);
|
|
84
|
+
}
|
|
85
|
+
const kib = (bytes) => Math.ceil(bytes / 1024);
|
|
86
|
+
// Resolves when a reader is free or the digest has read more, or after a
|
|
87
|
+
// short while in any case, so that a job that ended is seen.
|
|
88
|
+
const progress = () => new Promise((resolve) => {
|
|
89
|
+
wake = resolve;
|
|
90
|
+
const waited = Atomics.waitAsync(ctl, CTL.CONSUMED_KIB, Atomics.load(ctl, CTL.CONSUMED_KIB), 20);
|
|
91
|
+
(waited.async ? waited.value : Promise.resolve()).then(() => { if (wake === resolve) woken(); });
|
|
92
|
+
});
|
|
93
|
+
let running = Promise.resolve();
|
|
94
|
+
parentPort.on("message", (job) => {
|
|
95
|
+
running = running.then(() => plan(job)).catch(() => {});
|
|
96
|
+
});
|
|
97
|
+
async function plan({ job, roots, order, excludeRoot, excludePaths }) {
|
|
98
|
+
const options = { order, excludeRoot: new Set(excludeRoot), excludePaths: new Set(excludePaths) };
|
|
99
|
+
let plannedKiB = 0, plannedFiles = 0;
|
|
100
|
+
for (const root of roots) {
|
|
101
|
+
for (const [path, size] of files(Buffer.from(root), options)) {
|
|
102
|
+
if (!current(job)) return;
|
|
103
|
+
plannedKiB += kib(size); plannedFiles++;
|
|
104
|
+
if (kib(size) > windowKiB) continue;
|
|
105
|
+
for (;;) {
|
|
106
|
+
if (!current(job)) return;
|
|
107
|
+
const aheadKiB = plannedKiB - Atomics.load(ctl, CTL.CONSUMED_KIB), aheadFiles = plannedFiles - Atomics.load(ctl, CTL.CONSUMED_FILES);
|
|
108
|
+
if (free.length && aheadKiB <= windowKiB && aheadFiles <= windowFiles) {
|
|
109
|
+
if (aheadKiB > Atomics.load(ctl, CTL.MAX_AHEAD_KIB)) Atomics.store(ctl, CTL.MAX_AHEAD_KIB, aheadKiB);
|
|
110
|
+
if (aheadFiles > Atomics.load(ctl, CTL.MAX_AHEAD_FILES)) Atomics.store(ctl, CTL.MAX_AHEAD_FILES, aheadFiles);
|
|
111
|
+
break;
|
|
112
|
+
}
|
|
113
|
+
await progress();
|
|
114
|
+
}
|
|
115
|
+
free.pop().postMessage({ job, path });
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
/** Read-ahead for the tree digests (fingerprintTrees): while a digest reads a
|
|
2
|
+
* tree, file by file, on the calling thread, worker threads read the files it
|
|
3
|
+
* will read next, several at once, so that its own reads come from the page
|
|
4
|
+
* cache. A digest of a cold tree of many small files is otherwise bound by
|
|
5
|
+
* the latency of one read at a time (#1247).
|
|
6
|
+
*
|
|
7
|
+
* It changes nothing the digest computes. The digest reads every byte it
|
|
8
|
+
* hashes itself, with the same calls, in the same order, and an error is the
|
|
9
|
+
* error its own read meets: the readers' results and errors are dropped. A
|
|
10
|
+
* recovery copy's verification therefore still reads the copy's own bytes.
|
|
11
|
+
* A read-ahead that cannot start, falls behind or stops costs speed only, and
|
|
12
|
+
* the caller never waits for it: it stays synchronous.
|
|
13
|
+
*
|
|
14
|
+
* Bounds: at most `readers` files are read at once (one per reader thread),
|
|
15
|
+
* each through one reused 1 MiB buffer, so the threads hold `readers` MiB.
|
|
16
|
+
* The planner never runs more than `windowKiB` of file bytes or
|
|
17
|
+
* `windowFiles` files ahead of what the digest has read, so what it brings
|
|
18
|
+
* into the cache is read soon after; a file larger than the window is left
|
|
19
|
+
* to the digest. The page cache is the kernel's, reclaimable, not this
|
|
20
|
+
* process's memory. */
|
|
21
|
+
import { availableParallelism } from "node:os";
|
|
22
|
+
import { Worker } from "node:worker_threads";
|
|
23
|
+
|
|
24
|
+
/** The shared counters (an Int32Array over a SharedArrayBuffer). */
|
|
25
|
+
export const CTL = { JOB: 0, CONSUMED_KIB: 1, CONSUMED_FILES: 2, IN_FLIGHT: 3, MAX_IN_FLIGHT: 4, MAX_AHEAD_KIB: 5, MAX_AHEAD_FILES: 6 };
|
|
26
|
+
const CTL_LENGTH = 7;
|
|
27
|
+
|
|
28
|
+
const defaults = () => ({ enabled: true, readers: Math.min(4, Math.max(2, availableParallelism())), windowKiB: 64 * 1024, windowFiles: 4096 });
|
|
29
|
+
let settings = defaults();
|
|
30
|
+
// undefined: not started yet; null: could not start, and is not tried again.
|
|
31
|
+
let pool;
|
|
32
|
+
let active = false;
|
|
33
|
+
let unnotifiedKiB = 0, unnotifiedFiles = 0;
|
|
34
|
+
|
|
35
|
+
function started() {
|
|
36
|
+
if (pool !== undefined) return pool;
|
|
37
|
+
try {
|
|
38
|
+
const ctl = new Int32Array(new SharedArrayBuffer(CTL_LENGTH * Int32Array.BYTES_PER_ELEMENT));
|
|
39
|
+
const planner = new Worker(new URL("./read-ahead-worker.mjs", import.meta.url), {
|
|
40
|
+
// Not the process's own flags (an --import preload, a profiler): the threads only read.
|
|
41
|
+
execArgv: [],
|
|
42
|
+
workerData: { role: "planner", ctl, readers: settings.readers, windowKiB: settings.windowKiB, windowFiles: settings.windowFiles },
|
|
43
|
+
});
|
|
44
|
+
planner.on("error", () => { if (pool?.planner === planner) pool = null; });
|
|
45
|
+
// Never what keeps the process alive.
|
|
46
|
+
planner.unref();
|
|
47
|
+
pool = { planner, ctl };
|
|
48
|
+
} catch {
|
|
49
|
+
pool = null;
|
|
50
|
+
}
|
|
51
|
+
return pool;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Run `fn` (a digest of `roots`, paths as text or bytes, read in this order)
|
|
55
|
+
* with the files of `roots` read ahead → what `fn` returns. The walk is the
|
|
56
|
+
* digest's: `order` "bytes" (the names' bytes) or "locale" (their text by
|
|
57
|
+
* localeCompare, the legacy stored digest), passing over `excludeRoot` (top-level
|
|
58
|
+
* names, as text) and `excludePaths` (paths under a root, as bytes). Inside
|
|
59
|
+
* another read-ahead, `fn` simply runs: that one already reads its files. */
|
|
60
|
+
export function readingAhead(roots, { order = "bytes", excludeRoot = [], excludePaths = [] } = {}, fn) {
|
|
61
|
+
if (active || !settings.enabled) return fn();
|
|
62
|
+
const p = started();
|
|
63
|
+
if (!p) return fn();
|
|
64
|
+
const { ctl, planner } = p;
|
|
65
|
+
for (const i of [CTL.CONSUMED_KIB, CTL.CONSUMED_FILES, CTL.MAX_IN_FLIGHT, CTL.MAX_AHEAD_KIB, CTL.MAX_AHEAD_FILES]) Atomics.store(ctl, i, 0);
|
|
66
|
+
const job = Atomics.add(ctl, CTL.JOB, 1) + 1;
|
|
67
|
+
try {
|
|
68
|
+
planner.postMessage({ job, roots: roots.map((root) => Buffer.from(root)), order, excludeRoot: [...excludeRoot], excludePaths: excludePaths.map((path) => Buffer.from(path).toString("hex")) });
|
|
69
|
+
} catch {
|
|
70
|
+
return fn();
|
|
71
|
+
}
|
|
72
|
+
active = true;
|
|
73
|
+
unnotifiedKiB = 0; unnotifiedFiles = 0;
|
|
74
|
+
try {
|
|
75
|
+
return fn();
|
|
76
|
+
} finally {
|
|
77
|
+
active = false;
|
|
78
|
+
// The job ends: the planner stops, and the readers drop what is queued.
|
|
79
|
+
Atomics.add(ctl, CTL.JOB, 1);
|
|
80
|
+
Atomics.notify(ctl, CTL.CONSUMED_KIB);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Tell the read-ahead that the digest has read a file of `bytes` bytes. */
|
|
85
|
+
export function readAheadConsumed(bytes) {
|
|
86
|
+
if (!active) return;
|
|
87
|
+
const { ctl } = pool;
|
|
88
|
+
const kib = Math.ceil(bytes / 1024);
|
|
89
|
+
Atomics.add(ctl, CTL.CONSUMED_KIB, kib);
|
|
90
|
+
Atomics.add(ctl, CTL.CONSUMED_FILES, 1);
|
|
91
|
+
// The planner is woken once per eighth of the window read, not per file: a
|
|
92
|
+
// wake costs the digest's thread more than a small file's read.
|
|
93
|
+
unnotifiedKiB += kib; unnotifiedFiles++;
|
|
94
|
+
if (unnotifiedKiB >= settings.windowKiB / 8 || unnotifiedFiles >= settings.windowFiles / 8) {
|
|
95
|
+
unnotifiedKiB = 0; unnotifiedFiles = 0;
|
|
96
|
+
Atomics.notify(ctl, CTL.CONSUMED_KIB);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** For tests: the defaults with `options` over them (a new pool starts with
|
|
101
|
+
* them); with none, the defaults. */
|
|
102
|
+
export function configureReadAhead(options) {
|
|
103
|
+
settings = { ...defaults(), ...options };
|
|
104
|
+
if (pool) pool.planner.terminate().catch(() => {});
|
|
105
|
+
pool = undefined;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** For tests: the highest number of files read at once, and the most the
|
|
109
|
+
* planner ran ahead of the digest (KiB and files), in the last read-ahead.
|
|
110
|
+
* → undefined when no read-ahead has run. */
|
|
111
|
+
export function readAheadStats() {
|
|
112
|
+
if (!pool) return undefined;
|
|
113
|
+
const { ctl } = pool;
|
|
114
|
+
return { maxInFlight: Atomics.load(ctl, CTL.MAX_IN_FLIGHT), maxAheadKiB: Atomics.load(ctl, CTL.MAX_AHEAD_KIB), maxAheadFiles: Atomics.load(ctl, CTL.MAX_AHEAD_FILES), readers: settings.readers, windowKiB: settings.windowKiB, windowFiles: settings.windowFiles };
|
|
115
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/** A status row's `retire` (feature status-retire-state): whether a retire of the home runs, could
|
|
2
|
+
* not be told, failed or was interrupted. The kernel's row reads it from the facts beside the home
|
|
3
|
+
* (lib/core.mjs retireStateOf); a remote row relays the host's (lib/servers.mjs). Both go through
|
|
4
|
+
* readRetireState, so a value either shows as this module reads it or not at all. */
|
|
5
|
+
import { retireRefusedReason } from "./instance-events.mjs";
|
|
6
|
+
|
|
7
|
+
export const RETIRE_STATES = ["running", "unknown", "failed", "interrupted"];
|
|
8
|
+
/** The code a `failed` state may carry: a kernel code's shape. Any other is left out. */
|
|
9
|
+
export const RETIRE_STATE_CODE_RE = /^E_[A-Z0-9_]+$/;
|
|
10
|
+
const ISO_INSTANT = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$/;
|
|
11
|
+
/** Whether `at` is an instant exactly as `toISOString()` gives it, and one that exists. */
|
|
12
|
+
export const isInstant = (at) => typeof at === "string" && ISO_INSTANT.test(at) && !Number.isNaN(Date.parse(at)) && new Date(at).toISOString() === at;
|
|
13
|
+
|
|
14
|
+
/** `value` as a row's `retire` → `{ state, since, self, code?, message? }`, or undefined when it is
|
|
15
|
+
* none: an object whose `state` is one of RETIRE_STATES, whose `since` is an instant as
|
|
16
|
+
* `toISOString()` gives it, and whose `self` is a boolean. `since` is required: the Desktop drops
|
|
17
|
+
* a value without one, and a failed retire would then read as one still running. `code` and
|
|
18
|
+
* `message` belong to `failed` only, and are strings or absent, never null: `code` when it has a
|
|
19
|
+
* kernel code's shape; `message` on one line and at most the length of a retire's one-line reason
|
|
20
|
+
* (retireRefusedReason), and left out when it is empty. */
|
|
21
|
+
export function readRetireState(value) {
|
|
22
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
|
|
23
|
+
const { state, since, self, code, message } = value;
|
|
24
|
+
if (!RETIRE_STATES.includes(state) || !isInstant(since) || typeof self !== "boolean") return undefined;
|
|
25
|
+
const line = state === "failed" && typeof message === "string" ? retireRefusedReason(message) : "";
|
|
26
|
+
return {
|
|
27
|
+
state,
|
|
28
|
+
since,
|
|
29
|
+
self,
|
|
30
|
+
...(state === "failed" && typeof code === "string" && RETIRE_STATE_CODE_RE.test(code) ? { code } : {}),
|
|
31
|
+
...(line ? { message: line } : {}),
|
|
32
|
+
};
|
|
33
|
+
}
|
package/lib/servers.mjs
CHANGED
|
@@ -24,6 +24,7 @@ import { basename, join, resolve } from "node:path";
|
|
|
24
24
|
import { parseStrictJson } from "./canonical-json.mjs";
|
|
25
25
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
26
26
|
import { readWaitingClaim } from "./instance-events.mjs";
|
|
27
|
+
import { readRetireState } from "./retire-state.mjs";
|
|
27
28
|
import { withDirLock } from "./dir-lock.mjs";
|
|
28
29
|
import { shellWord } from "./core.mjs";
|
|
29
30
|
import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
|
|
@@ -870,6 +871,13 @@ const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k,
|
|
|
870
871
|
* omits it, and absent ("not reported") must stay distinct from null ("no claim"). The
|
|
871
872
|
* value passes the kernel's own read rule again; anything it refuses is null. */
|
|
872
873
|
const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: readWaitingClaim(i.waitingOnYou) } : {});
|
|
874
|
+
/** `retire` (feature status-retire-state) the same way, relayed ONLY when the host's row has the
|
|
875
|
+
* key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
|
|
876
|
+
* only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
|
|
877
|
+
const rowRetire = (i) => {
|
|
878
|
+
const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
|
|
879
|
+
return retire ? { retire } : {};
|
|
880
|
+
};
|
|
873
881
|
|
|
874
882
|
/** The bounds a host's `features` list must meet to be relayed (feature server-probe-features). */
|
|
875
883
|
export const HOST_FEATURES_MAX = 256;
|
|
@@ -962,7 +970,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
962
970
|
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
|
|
963
971
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
964
972
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
965
|
-
...rowFacts(i), ...rowWaiting(i),
|
|
973
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i),
|
|
966
974
|
// Every row the host reports is addressed by its home, saved
|
|
967
975
|
// route or not; savedRoute says only that it was spawned from here.
|
|
968
976
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
package/lib/session-input.mjs
CHANGED
|
@@ -13,42 +13,69 @@ function tmux(target, args, { exec = execFileSync, input, timeout = 10000, killS
|
|
|
13
13
|
stdio: ["pipe", "pipe", "pipe"],
|
|
14
14
|
});
|
|
15
15
|
}
|
|
16
|
-
|
|
16
|
+
// Public inspection opts into window geometry; input and other session operations
|
|
17
|
+
// retain their existing transport result and do not depend on size parsing.
|
|
18
|
+
export function inspectSessionTarget(target, io, { includeSize = false } = {}) {
|
|
19
|
+
const format = "#{pane_id}\t#{pane_dead}\t#{pane_current_command}\t#{pane_pid}"
|
|
20
|
+
+ (includeSize ? "\t#{window_width}\t#{window_height}" : "");
|
|
17
21
|
let rows;
|
|
18
22
|
try {
|
|
19
|
-
|
|
23
|
+
const output = tmux(target, ["list-panes", "-t", `=${target.session}:=${target.window}`, "-F", format], io);
|
|
24
|
+
// Preserve dimension whitespace for validation, and the original parsing for other callers.
|
|
25
|
+
rows = (includeSize ? output : output.trim()).split("\n").filter(Boolean);
|
|
20
26
|
} catch (e) {
|
|
21
27
|
// A missing window on a reachable server is absence. A lost socket is not.
|
|
22
28
|
if (/can't find (window|session)/i.test(String(e.stderr || ""))) return { backend: "tmux", present: false, state: "stopped" };
|
|
23
29
|
throw e;
|
|
24
30
|
}
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
31
|
+
return createSessionPaneInspector(io)(rows, { includeSize });
|
|
32
|
+
}
|
|
33
|
+
/** Interpret one window's panes with the lifecycle's shell/descendant rule. A status read shares
|
|
34
|
+
* one inspector across windows so both successful and failed process scans cost one child. */
|
|
35
|
+
export function createSessionPaneInspector(io) {
|
|
36
|
+
let processRead;
|
|
37
|
+
const readProcesses = () => {
|
|
38
|
+
if (!processRead) {
|
|
39
|
+
try {
|
|
40
|
+
const output = (io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,comm="], {
|
|
41
|
+
encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
|
|
42
|
+
});
|
|
43
|
+
processRead = { rows: output.split("\n").map(line => line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean) };
|
|
44
|
+
} catch (error) { processRead = { error }; }
|
|
45
|
+
}
|
|
46
|
+
if (processRead.error) throw processRead.error;
|
|
47
|
+
return processRead.rows;
|
|
48
|
+
};
|
|
49
|
+
return (rows, { includeSize = false } = {}) => {
|
|
50
|
+
if (!rows.length) return { backend: "tmux", present: false, state: "stopped" };
|
|
51
|
+
if (rows.length !== 1) throw new Error("session window has multiple panes; choose an unsplit agent window");
|
|
52
|
+
const [paneId, dead, command, panePid, cols, rowsCount] = rows[0].split("\t");
|
|
53
|
+
if (!/^%\d+$/.test(paneId) || !["0", "1"].includes(dead)) throw new Error("invalid tmux pane response");
|
|
54
|
+
if (includeSize && ![cols, rowsCount].every(value => /^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value)))) {
|
|
55
|
+
throw new Error("invalid tmux pane response");
|
|
56
|
+
}
|
|
57
|
+
let state = dead === "1" ? "stopped" : "unknown";
|
|
58
|
+
if (dead === "0" && shells.has(command)) {
|
|
59
|
+
// macOS tmux can report the wrapper shell while the harness is its child.
|
|
60
|
+
// Only a shell with no non-shell descendants is a fallback prompt.
|
|
61
|
+
if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
|
|
62
|
+
const processes = readProcesses();
|
|
63
|
+
const descendants = new Set([panePid]);
|
|
64
|
+
let active = false;
|
|
65
|
+
for (let changed = true; changed;) {
|
|
66
|
+
changed = false;
|
|
67
|
+
for (const [, pid, parent, name] of processes) {
|
|
68
|
+
if (descendants.has(parent) && !descendants.has(pid)) {
|
|
69
|
+
descendants.add(pid); changed = true;
|
|
70
|
+
if (!shells.has(basename(name).replace(/^-/, ""))) active = true;
|
|
71
|
+
}
|
|
46
72
|
}
|
|
47
73
|
}
|
|
74
|
+
state = active ? "unknown" : "shell";
|
|
48
75
|
}
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
76
|
+
return { backend: "tmux", present: dead === "0", state, paneId,
|
|
77
|
+
...(includeSize && dead === "0" ? { size: { cols: Number(cols), rows: Number(rowsCount) } } : {}) };
|
|
78
|
+
};
|
|
52
79
|
}
|
|
53
80
|
// Settling gives a large bracketed paste time before the single Enter. Screen
|
|
54
81
|
// bytes are observations only: neither change nor silence proves acceptance
|
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.2.
|
|
6
|
+
"ref": "v5.2.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.29.0",
|
|
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.12.
|
|
46
|
+
"ref": "oats-framework/v1.12.3",
|
|
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.60.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",
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/** The deployment's capability table: `oats capabilities --json`, held per
|
|
2
|
+
* deployment and keyed by the workspace state it describes, so a read costs
|
|
3
|
+
* a kernel run only when that state moved (or the caller forces a live one),
|
|
4
|
+
* never on every poll or view open. The holding rules (one flight per
|
|
5
|
+
* deployment, last good table kept with the failure next to it, retry after
|
|
6
|
+
* RETRY_MS, unbound prefetch bound by the same cycle's settle) are
|
|
7
|
+
* keyed-catalog.mjs's; this module is the kernel read, the key and the shape.
|
|
8
|
+
*
|
|
9
|
+
* A client makes its own catalog and owns it: nothing is held at module level, so two catalogs
|
|
10
|
+
* share no flight and no held entry. It takes the client's terms (client-terms.mjs), which the
|
|
11
|
+
* default kernel read words its refusals with, and an optional `exec` that read runs the CLI
|
|
12
|
+
* through (cli-adapter.mjs `runJson`'s `io.exec`). */
|
|
13
|
+
import { cliWorkspace } from './workspace-cli.mjs';
|
|
14
|
+
import { requireTerms } from './client-terms.mjs';
|
|
15
|
+
import { capabilitiesData, observationData } from './deployment-data.mjs';
|
|
16
|
+
import { soulCatalogKey } from './soul-catalog.mjs';
|
|
17
|
+
import { createKeyedCatalog } from './keyed-catalog.mjs';
|
|
18
|
+
|
|
19
|
+
export const CAPABILITY_CATALOG_RETRY_MS = 60_000;
|
|
20
|
+
/** The client's own transport/probe codes (workspace-cli.mjs); any other code on
|
|
21
|
+
* an ok:false result is the kernel's own refusal, reported verbatim. */
|
|
22
|
+
const LOCAL_CODES = new Set(['E_CLI_UNAVAILABLE', 'E_WORKSPACE_FEATURE', 'E_CLI_FAILED', 'E_CLI_PROTOCOL', 'E_CLI_TIMEOUT', 'E_CLI_OUTPUT_LIMIT']);
|
|
23
|
+
|
|
24
|
+
/** What the catalog table depends on, from `oats workspace status --json` as
|
|
25
|
+
* projected by workspaceStatusData. Member capabilities move with member
|
|
26
|
+
* commits and the workspace commit (the soul key carries those, plus the
|
|
27
|
+
* CLI); package capabilities move with package identity (id/version/commit/
|
|
28
|
+
* integrity, i.e. the lock rows); whether the lock is current moves with
|
|
29
|
+
* declaredPackages/unsynced/stale (oats-local.yaml or the lock changed). The
|
|
30
|
+
* lock fact itself has no hash, so the package rows are its identity and
|
|
31
|
+
* its path/lockfileVersion only mark a different lock file altogether.
|
|
32
|
+
* Names, warnings, problems, defaults and clones are deliberately not here:
|
|
33
|
+
* they change without the table changing. */
|
|
34
|
+
export function capabilityCatalogKey(cli, workspaceStatus) {
|
|
35
|
+
const ws = workspaceStatus || {};
|
|
36
|
+
return JSON.stringify([soulCatalogKey(cli, workspaceStatus),
|
|
37
|
+
(ws.packages || []).map(p => [p.id ?? null, p.version ?? null, p.commit ?? null, p.integrity ?? null]),
|
|
38
|
+
ws.declaredPackages ?? [], ws.unsynced ?? [], ws.stale ?? [],
|
|
39
|
+
ws.lock ? [ws.lock.path ?? null, ws.lock.lockfileVersion ?? null] : null]);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function createCapabilityCatalog({ terms, exec, invoke = (cli, options) => exec ? cliWorkspace(cli, options, terms, { exec }) : cliWorkspace(cli, options, terms), now = () => Date.now() } = {}) {
|
|
43
|
+
requireTerms(terms, 'createCapabilityCatalog');
|
|
44
|
+
async function read(deployment, cli, options) {
|
|
45
|
+
let result;
|
|
46
|
+
try { result = await invoke(cli, { action: 'capabilities', context: deployment, ...options }); }
|
|
47
|
+
catch { return { value: null, reason: { code: 'E_CLI_FAILED', message: '', kernel: false } }; }
|
|
48
|
+
if (result?.ok !== true) {
|
|
49
|
+
const code = typeof result?.reason?.code === 'string' ? result.reason.code : 'E_CLI_FAILED';
|
|
50
|
+
return { value: null, reason: { code, message: String(result?.reason?.message || ''), kernel: !LOCAL_CODES.has(code) } };
|
|
51
|
+
}
|
|
52
|
+
try { return { value: capabilitiesData(result.document), observedAt: observationData(result.document).observedAt }; } // a malformed stamp is no stamp; the table stands
|
|
53
|
+
catch { return { value: null, reason: { code: 'E_CLI_PROTOCOL', message: '', kernel: false } }; }
|
|
54
|
+
}
|
|
55
|
+
const catalog = createKeyedCatalog({ read, retryMs: CAPABILITY_CATALOG_RETRY_MS, now });
|
|
56
|
+
const project = (deployment, entry) => entry && { key: entry.key, capabilities: entry.value, reason: entry.reason, at: entry.at, observedAt: entry.observedAt, stale: entry.stale, refreshing: catalog.refreshing(deployment) };
|
|
57
|
+
const key = (cli, workspaceStatus) => capabilityCatalogKey(cli, workspaceStatus);
|
|
58
|
+
/** Synchronous decision for this workspace state, as the soul catalog's: `entry` is what is held now and
|
|
59
|
+
* `pending` the read it started or joined (null when none), both projected. Never awaits. */
|
|
60
|
+
function settle(deployment, cli, workspaceStatus, options = {}) {
|
|
61
|
+
const { entry, pending } = catalog.settle(deployment, cli, key(cli, workspaceStatus), options);
|
|
62
|
+
return { entry: project(deployment, entry), pending: pending && pending.then(landed => project(deployment, landed)) };
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
/** Cold cycle: start the read alongside the roster reads, before the key is known. */
|
|
66
|
+
prefetch(deployment, cli, options = {}) { return catalog.prefetch(deployment, cli, options); },
|
|
67
|
+
/** Bind this cycle's key: a read starts only when the held table is not for this state (or its
|
|
68
|
+
* failure is old enough to retry) and none is in flight. Never awaits. */
|
|
69
|
+
ensure(deployment, cli, workspaceStatus, options = {}) { catalog.settle(deployment, cli, key(cli, workspaceStatus), options); },
|
|
70
|
+
settle,
|
|
71
|
+
/** The held table, immediately, whenever it is a healthy answer — a table past HELD_TTL_MS
|
|
72
|
+
* included: then this request starts (or joins) one re-read behind it and the answer says
|
|
73
|
+
* `refreshing` (stale-while-revalidate, request-driven: a Workspace-tab visit never waits for
|
|
74
|
+
* an `oats capabilities` run while the key is unchanged, and nobody looking costs nothing).
|
|
75
|
+
* Awaited only when nothing healthy is held: a first read, a held failure (table behind it or
|
|
76
|
+
* not — the boundary shows it as a failure and today's Retry is a plain read, so it reads now
|
|
77
|
+
* whatever the retry window says; the window throttles background cycles only), or a forced
|
|
78
|
+
* live read (refresh: true → maxAge 0). */
|
|
79
|
+
async read(deployment, cli, workspaceStatus, { refresh = false, maxAge } = {}) {
|
|
80
|
+
const k = key(cli, workspaceStatus), options = maxAge !== undefined ? { maxAge } : {};
|
|
81
|
+
if (refresh) return project(deployment, await catalog.refresh(deployment, cli, k));
|
|
82
|
+
const { entry } = catalog.settle(deployment, cli, k, options);
|
|
83
|
+
if (!entry?.value || entry.reason) return project(deployment, await catalog.demand(deployment, cli, k, options));
|
|
84
|
+
if (entry.stale) void catalog.revalidate(deployment, cli, k, options)?.catch(() => {});
|
|
85
|
+
return project(deployment, entry);
|
|
86
|
+
},
|
|
87
|
+
/** Read-only view of what is held (tests and diagnostics); nothing reads it on the request path. */
|
|
88
|
+
held(deployment) { return project(deployment, catalog.held(deployment)); },
|
|
89
|
+
refreshing: catalog.refreshing,
|
|
90
|
+
forget: catalog.forget,
|
|
91
|
+
forgetAll: catalog.forgetAll,
|
|
92
|
+
};
|
|
93
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/** A capability's facts as its page shows them, for any client: the "Comes from" rows and what it
|
|
2
|
+
* provides, projected from the catalog row (`oats capabilities`, or a soul's resolved capability in the
|
|
3
|
+
* same shape) and workspace status. Only reported facts: a fact the kernel did not report is no row, and
|
|
4
|
+
* nothing is invented. The page's own words are CAPABILITY_COPY, so no client writes its own. */
|
|
5
|
+
import { memberNames, capabilitySource } from './capability-rows.mjs';
|
|
6
|
+
|
|
7
|
+
const text = v => typeof v === 'string' && v ? v : null;
|
|
8
|
+
const list = v => Array.isArray(v) ? v : [];
|
|
9
|
+
const short = v => typeof v === 'string' && /^[0-9a-f]{40}$/i.test(v) ? v.slice(0, 7) : v;
|
|
10
|
+
|
|
11
|
+
/** The capability page's own words. `souls(n)` is the "Used by" count; `behind(n)` follows an instance count, joined with ` · `. */
|
|
12
|
+
export const CAPABILITY_COPY = Object.freeze({
|
|
13
|
+
comesFrom: 'Comes from',
|
|
14
|
+
provides: 'Provides',
|
|
15
|
+
usedBy: 'Used by',
|
|
16
|
+
unlistable: 'Not listable: a spawn of it would refuse.',
|
|
17
|
+
none: 'None',
|
|
18
|
+
noSoul: 'No soul here includes it.',
|
|
19
|
+
noInstance: 'No instance carries it yet.',
|
|
20
|
+
souls: n => `${n} soul${n === 1 ? '' : 's'}`,
|
|
21
|
+
behind: n => `${n} on an older version`,
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
/** Where a package comes from, in workspace status terms: the official catalog or a git source. */
|
|
25
|
+
export function packageOrigin(source) {
|
|
26
|
+
if (!text(source)) return null;
|
|
27
|
+
if (source.startsWith('catalog:')) return 'official catalog';
|
|
28
|
+
const git = /^git:(?:[a-z]+:\/\/)?(?:[^@/]+@)?([^/:@]+)/i.exec(source);
|
|
29
|
+
return git ? `git · ${git[1]}` : source;
|
|
30
|
+
}
|
|
31
|
+
/** sha256-<64 hex> → sha256:9f2c…a71e (the full value stays in the title). */
|
|
32
|
+
export function fingerprint(integrity) {
|
|
33
|
+
const m = /^sha256-([0-9a-f]{64})$/i.exec(integrity || '');
|
|
34
|
+
return m ? `sha256:${m[1].slice(0, 4)}…${m[1].slice(-4)}` : text(integrity);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** One "Comes from" row, [label, value] or [label, value, full], or none when the value is not reported text.
|
|
38
|
+
* `full` (the whole value, where the row shows it shortened) is kept only when it says more than the value. */
|
|
39
|
+
const fact = (label, value, full) => !text(value) ? [] : [text(full) && full !== value ? [label, value, full] : [label, value]];
|
|
40
|
+
|
|
41
|
+
/** `{ origin, provides }`. `origin`: the "Comes from" rows, in order: a package's Package, Pinned (its version
|
|
42
|
+
* and where it comes from), Commit and Fingerprint (the integrity workspace status reports for it, else the
|
|
43
|
+
* resolved capability's); a member or external capability's Repository, Latest, Path, Fingerprint (the Git
|
|
44
|
+
* tree of its directory, kernel #217) and Owned when it is private. `provides`: [label, names] for Skills,
|
|
45
|
+
* Commands and Hooks, each only when the row carries it; names is an array, or null when the kernel could
|
|
46
|
+
* not list them (a spawn of it would refuse). `names`: memberNames(status), when the caller holds it. */
|
|
47
|
+
export function capabilityFacts(row, { status, names = memberNames(status) } = {}) {
|
|
48
|
+
let origin;
|
|
49
|
+
if (row.kind === 'package') {
|
|
50
|
+
const pkg = list(status?.packages).find(p => p.id === row.package), integrity = pkg?.integrity || row.resolved?.from?.integrity;
|
|
51
|
+
origin = [...fact('Package', row.package), ...fact('Pinned', [row.version, packageOrigin(pkg?.source)].filter(Boolean).join(' · ')),
|
|
52
|
+
...fact('Commit', short(row.commit), row.commit), ...fact('Fingerprint', fingerprint(integrity), integrity)];
|
|
53
|
+
} else {
|
|
54
|
+
origin = [...fact('Repository', capabilitySource(row, names).label, row.repoKey), ...fact('Latest', short(row.commit), row.commit), ...fact('Path', row.path),
|
|
55
|
+
...fact('Fingerprint', short(row.tree), row.tree), ...(row.private === true ? fact('Owned', 'this repo\'s souls only') : [])];
|
|
56
|
+
}
|
|
57
|
+
const provides = [['Skills', row.skills], ['Commands', row.commands], ['Hooks', row.hooks]].filter(([, names]) => names !== undefined);
|
|
58
|
+
return { origin, provides };
|
|
59
|
+
}
|