@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
|
@@ -2,10 +2,11 @@
|
|
|
2
2
|
// call, the observer of every served deployment, the roster of other machines, the refresh loop,
|
|
3
3
|
// the liveness collector, and the two looks at the file system the switcher needs.
|
|
4
4
|
// Every child of this module is a read, except the changes (a stop or retire apply, a start or a
|
|
5
|
-
// restart) that the shared callers start through `changeExec`: those are never
|
|
6
|
-
//
|
|
7
|
-
//
|
|
8
|
-
//
|
|
5
|
+
// restart, a spawn apply) that the shared callers start through `changeExec`: those are never
|
|
6
|
+
// ended by the TUI of its own accord (only at a deadline their caller gives), and their output goes
|
|
7
|
+
// to two files of the run's own private directory, the only files this module writes. (Opening an
|
|
8
|
+
// agent's terminal starts the kernel's viewer, which is not a read and is not started here: it runs
|
|
9
|
+
// in a pane of the panel's private tmux server, lib/panel.mjs.)
|
|
9
10
|
// No function of this module decodes a kernel answer. Each one passes values between the shared
|
|
10
11
|
// functions (client.mjs), which decide what a roster, a row and a failed read are, once, for both
|
|
11
12
|
// clients: the TUI never writes "stopped" for a row and never builds the collector's input by hand.
|
|
@@ -198,7 +199,7 @@ const said = (error) => String(error?.message ?? error);
|
|
|
198
199
|
|
|
199
200
|
/** The reader of a run: its cycles over every served deployment, the roster of other machines,
|
|
200
201
|
* their children, and the way out.
|
|
201
|
-
* -> { start(), request({ live }), touch(), voidInFlight(), exec, stop(), children() }
|
|
202
|
+
* -> { start(), request({ live }), touch(), voidInFlight(), begun(), exec, stop(), children() }
|
|
202
203
|
*
|
|
203
204
|
* `cli` is probeKernel's record (`cli.bin` the absolute path of bin/oats.mjs). The reader keeps no
|
|
204
205
|
* answer of its own: what a run holds is the caller's store, asked for when it is needed.
|
|
@@ -210,7 +211,9 @@ const said = (error) => String(error?.message ?? error);
|
|
|
210
211
|
* nothing about a failed read (the shared failedEntry does). `number` is the
|
|
211
212
|
* cycle's: it grows by one per cycle and is never reused, and every deployment of
|
|
212
213
|
* one cycle answers under the same one, so a store can refuse an answer that
|
|
213
|
-
* arrives out of order; a cycle that emits nothing leaves a gap.
|
|
214
|
+
* arrives out of order; a cycle that emits nothing leaves a gap. `read: true`
|
|
215
|
+
* on an entry made from the kernel's answer, absent on one a failed read made
|
|
216
|
+
* (failedEntry may keep the entry held, so its shape does not say).
|
|
214
217
|
* getRoster() { remote: { remoteGroups, rosterAnswered, rosterFailure }, memory, notes }: what
|
|
215
218
|
* the store holds of the other machines now, and its two Maps of identities.
|
|
216
219
|
* onRoster(event) { collecting: true } when a roster read starts, and
|
|
@@ -230,15 +233,16 @@ const said = (error) => String(error?.message ?? error);
|
|
|
230
233
|
* list of options, `detached` is not one of them, and a child it starts stays in the TUI's group
|
|
231
234
|
* whatever it is asked. `run` below is the part of execFile's contract the shared readers use.
|
|
232
235
|
*
|
|
233
|
-
* ENDING A CHILD: only a read is ever ended. The viewer of an opened agent runs in the panel's
|
|
236
|
+
* ENDING A CHILD: only a read is ever ended by the reader. The viewer of an opened agent runs in the panel's
|
|
234
237
|
* private tmux server (lib/panel.mjs), and is no child of the reader. A KERNEL CALL THAT CHANGES SOMETHING (kind "change", `changeExec`) IS
|
|
235
|
-
* NEVER SIGNALLED BY THE
|
|
238
|
+
* NEVER SIGNALLED BY THE READER: a stop killed while it waits leaves a marker that refuses every
|
|
236
239
|
* later stop, and a killed start leaves its lock (#889, #890). So every child is remembered with
|
|
237
|
-
* its kind, and only kind "read" is ever
|
|
240
|
+
* its kind, and only kind "read" is ever ended by the reader's own decisions. A change is
|
|
241
|
+
* signalled only at a positive `timeout` its caller gives (see changeExec), never on the way out.
|
|
238
242
|
*
|
|
239
|
-
* `timers` are the loop's, the idle timer's
|
|
240
|
-
* is where a change's output is written (for tests): `files.dir()` makes the run's
|
|
241
|
-
* directory. */
|
|
243
|
+
* `timers` are the loop's, the idle timer's, the reads' time limits and a change's deadline (for
|
|
244
|
+
* tests). `files` is where a change's output is written (for tests): `files.dir()` makes the run's
|
|
245
|
+
* private directory. */
|
|
242
246
|
export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onRoster, env = process.env, clock = () => new Date().toISOString(), now = Date.now, spawn = nodeSpawn, timers = { setTimeout, clearTimeout }, collector = COLLECTOR, idleMs = 600_000, focusedMs = 5000, blurredMs = 30_000, rosterMs = 15_000, files = CHANGE_FILES }) {
|
|
243
247
|
/** child -> { kind, exited, giveUp, asked } for a read, { kind: "change", label, letGo } for a
|
|
244
248
|
* change: every child that has not ended and was not ended (a read) or let go (a change).
|
|
@@ -369,11 +373,20 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
369
373
|
return child;
|
|
370
374
|
}
|
|
371
375
|
/** THE EXEC OF A CHANGE: a stop or retire apply (the boundary's call with `detached: true`), a
|
|
372
|
-
* start or a restart (the shared cliStart's)
|
|
373
|
-
* a session of its own, outside every cycle: it is never
|
|
374
|
-
* signalled, not by `sever`, not by stop(),
|
|
375
|
-
*
|
|
376
|
-
*
|
|
376
|
+
* start or a restart (the shared cliStart's), a spawn apply (the shared spawn-apply's). execFile's
|
|
377
|
+
* signature for `node <bin> <argv…>`, in a session of its own, outside every cycle: it is never
|
|
378
|
+
* made void by voidInFlight() and never signalled by the reader, not by `sever`, not by stop(),
|
|
379
|
+
* not by voidInFlight(). A positive `timeout` its caller gives (the shared spawn apply on a
|
|
380
|
+
* kernel without worktree-event: its only deadline) is honoured as execFileInSession honours it
|
|
381
|
+
* (packages/client/cli-adapter.mjs): one timer of `timers`, and when it fires the child alone is
|
|
382
|
+
* sent `killSignal` (SIGTERM; `child.kill`, not its group), and the callback's error has
|
|
383
|
+
* `killed: true` even when the child then exits 0: never a clean answer after the timer fired.
|
|
384
|
+
* The timer is cleared when the child exits or does not start, and on the let-go: a TUI that has
|
|
385
|
+
* gone never kills a change. A zero, negative, missing or non-finite `timeout` arms nothing, as
|
|
386
|
+
* a stop, retire or start gives (the shared callers end their wait, never the child). On a
|
|
387
|
+
* worktree-event kernel the shared spawn-apply boundary gives no `timeout` and itself signals the
|
|
388
|
+
* child this returns at its deadline. `options.label` is the caller's `{ verb, name }`, kept for
|
|
389
|
+
* the line after leaving (`changes()`); neither it nor `timeout` nor `killSignal` is passed on.
|
|
377
390
|
* ITS OUTPUT GOES TO FILES, NEVER TO A PIPE. Before the spawn two files are opened in the run's
|
|
378
391
|
* private directory (made once, mode 0700, under the OS temp dir) and given to the child as its
|
|
379
392
|
* stdout and stderr; stdin is `ignore`. The TUI's own copies are closed after the spawn. So
|
|
@@ -382,7 +395,7 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
382
395
|
* each bounded by `maxBuffer` (over it: ERR_CHILD_PROCESS_STDIO_MAXBUFFER, as a read answers),
|
|
383
396
|
* deleted, and the callback is called as execFile calls it, with text (UTF-8).
|
|
384
397
|
* It throws after stop(): nothing new starts on the way out. Returns the child. */
|
|
385
|
-
function changeExec(bin, argv, { label = null, timeout
|
|
398
|
+
function changeExec(bin, argv, { label = null, timeout = 0, killSignal = "SIGTERM", maxBuffer = Infinity, encoding: _utf8, ...options }, callback) {
|
|
386
399
|
if (stopped) throw new Error("the reader has stopped");
|
|
387
400
|
if (changeDir === null) changeDir = files.dir();
|
|
388
401
|
const number = ++changeCount, paths = { stdout: join(changeDir, `${number}.out`), stderr: join(changeDir, `${number}.err`) };
|
|
@@ -400,11 +413,13 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
400
413
|
for (const name of ["stdout", "stderr"]) quietly(() => files.close(fds[name]));
|
|
401
414
|
}
|
|
402
415
|
const record = { kind: "change", label, letGo: false };
|
|
403
|
-
let over = false;
|
|
416
|
+
let over = false, timer = null, killed = false;
|
|
404
417
|
const forget = () => { for (const name of ["stdout", "stderr"]) quietly(() => files.unlink(paths[name])); };
|
|
418
|
+
const disarm = () => { if (timer !== null) { timers.clearTimeout(timer); timer = null; } };
|
|
405
419
|
function finish(error) {
|
|
406
420
|
if (over) return;
|
|
407
421
|
over = true;
|
|
422
|
+
disarm();
|
|
408
423
|
remembered.delete(child);
|
|
409
424
|
if (record.letGo) return; // stop() let it go: nobody waits for its answer any more
|
|
410
425
|
const read = {};
|
|
@@ -417,12 +432,17 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
417
432
|
forget();
|
|
418
433
|
callback(verdict ?? null, read.stdout, read.stderr);
|
|
419
434
|
}
|
|
420
|
-
|
|
421
|
-
child.once("
|
|
435
|
+
// Disarmed at `exit`, not only at `close`: after `exit` the pid is free to name another process.
|
|
436
|
+
child.once("exit", () => { disarm(); running.delete(child); });
|
|
437
|
+
child.once("close", (code, signal) => finish(!killed && code === 0 && signal === null ? null : failure({ code, signal, killed })));
|
|
422
438
|
child.on("error", (error) => { if (!child.pid) { running.delete(child); finish(error); } });
|
|
423
|
-
record.letItGo = () => { record.letGo = true; quietly(() => child.unref()); forget(); remembered.delete(child); };
|
|
439
|
+
record.letItGo = () => { record.letGo = true; disarm(); quietly(() => child.unref()); forget(); remembered.delete(child); };
|
|
424
440
|
remembered.set(child, record);
|
|
425
441
|
if (Number.isInteger(child.pid)) running.set(child, label);
|
|
442
|
+
if (Number.isFinite(timeout) && timeout > 0 && Number.isInteger(child.pid)) {
|
|
443
|
+
timer = timers.setTimeout(() => { timer = null; killed = true; quietly(() => child.kill(killSignal)); }, timeout);
|
|
444
|
+
timer?.unref?.();
|
|
445
|
+
}
|
|
426
446
|
return child;
|
|
427
447
|
}
|
|
428
448
|
|
|
@@ -516,7 +536,7 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
516
536
|
const printed = rows.length ? await collect(JSON.stringify(livenessInput(rows))) : null;
|
|
517
537
|
if (over()) return;
|
|
518
538
|
const instances = panelInstances(rows, livenessAnswers(rows, printed));
|
|
519
|
-
onEntry({ id, entry: observedEntry({ roster: answer.roster, workspaceStatus: answer.workspaceStatus, observedAt: answer.observedAt }, instances, at), number });
|
|
539
|
+
onEntry({ id, entry: observedEntry({ roster: answer.roster, workspaceStatus: answer.workspaceStatus, observedAt: answer.observedAt }, instances, at), number, read: true });
|
|
520
540
|
}
|
|
521
541
|
|
|
522
542
|
/** One cycle: the roster read is begun if it is due, then every served deployment is read, at
|
|
@@ -589,6 +609,11 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
589
609
|
rosterFlight = null;
|
|
590
610
|
endReads({ cycles: true });
|
|
591
611
|
},
|
|
612
|
+
/** The number of the last cycle begun, 0 before the first: a cycle numbered above it, and the
|
|
613
|
+
* roster read it begins, begin after this call. lib/main.mjs marks its retires in flight with
|
|
614
|
+
* it (a count, not the clock: a cycle asked for when a retire answers begins in the same
|
|
615
|
+
* millisecond, and must count as after it). */
|
|
616
|
+
begun() { return counter; },
|
|
592
617
|
/** See askedExec. */
|
|
593
618
|
exec: askedExec,
|
|
594
619
|
/** See changeExec. */
|
|
@@ -607,9 +632,10 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
607
632
|
observer.dispose();
|
|
608
633
|
clearIdle();
|
|
609
634
|
endReads();
|
|
610
|
-
// Every change is LET GO, never signalled: its
|
|
611
|
-
//
|
|
612
|
-
// private directory goes when it is
|
|
635
|
+
// Every change is LET GO, never signalled: its timer, if its caller gave it a deadline, is
|
|
636
|
+
// cleared, its handle no longer holds the process, and its two files are unlinked (the child
|
|
637
|
+
// goes on writing to them, and nothing is left behind). The private directory goes when it is
|
|
638
|
+
// empty.
|
|
613
639
|
for (const record of [...remembered.values()]) if (record.kind === "change") record.letItGo();
|
|
614
640
|
if (changeDir !== null) quietly(() => files.remove(changeDir));
|
|
615
641
|
},
|