@awebai/oats 0.69.5 → 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 +78 -320
- 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 +250 -12
- package/docs/execution-targets.md +11 -2
- package/docs/implementation.md +26 -8
- package/docs/integrations.md +1 -1
- package/docs/knowledge.md +14 -7
- package/docs/named-test-runs.md +4 -0
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.69.6.md +165 -0
- package/docs/schedules.md +8 -1
- package/docs/tui.md +21 -4
- package/docs/upgrading.md +9 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +41 -0
- package/lib/automation-scope.mjs +6 -4
- package/lib/automations.mjs +61 -11
- package/lib/captured-context.mjs +12 -0
- package/lib/hot-reads.mjs +21 -15
- package/lib/install-stamp.mjs +61 -0
- package/lib/instance-events.mjs +8 -6
- package/lib/instance-listing.mjs +13 -5
- package/lib/kernel-features.mjs +10 -0
- package/lib/local-edit.mjs +1 -1
- package/lib/local-inputs.mjs +3 -0
- package/lib/member-clone.mjs +15 -11
- package/lib/read-call.mjs +143 -0
- package/lib/reader.mjs +203 -0
- package/lib/remote.mjs +47 -6
- package/lib/resolved-deployment.mjs +12 -4
- package/lib/roster-read.mjs +199 -0
- package/lib/session-input.mjs +35 -11
- package/lib/workspace-read.mjs +160 -0
- package/package-catalog.json +2 -2
- 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/skills/oats-getting-started/SKILL.md +2 -2
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// The effects of the TUI: finding the deployment, the kernel's record, one exec for every kernel
|
|
2
|
-
// call, the observer of every served deployment
|
|
3
|
-
// the
|
|
2
|
+
// call, the observer of every served deployment and the warm reader it reads through, the roster of
|
|
3
|
+
// other machines, the refresh loop, the liveness collector (for a kernel without status-liveness),
|
|
4
|
+
// and the two looks at the file system the switcher needs.
|
|
4
5
|
// Every child of this module is a read, except the changes (a stop or retire apply, a start or a
|
|
5
6
|
// restart, a spawn apply) that the shared callers start through `changeExec`: those are never
|
|
6
7
|
// ended by the TUI of its own accord (only at a deadline their caller gives), and their output goes
|
|
@@ -15,7 +16,7 @@ import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, realp
|
|
|
15
16
|
import { tmpdir } from "node:os";
|
|
16
17
|
import { dirname, join } from "node:path";
|
|
17
18
|
import { fileURLToPath } from "node:url";
|
|
18
|
-
import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentIdentity, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, failedEntry, identityReadable, identityTimedOut, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
|
|
19
|
+
import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentIdentity, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, createWarmReader, failedEntry, identityReadable, identityTimedOut, kernelLiveness, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
|
|
19
20
|
|
|
20
21
|
/** A path made canonical: what the shared start rule checks a local home with (session-start.mjs
|
|
21
22
|
* verifiedLocalHome). Throws for a path that cannot be resolved; the rule answers that as no home. */
|
|
@@ -310,9 +311,11 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
310
311
|
remembered.set(child, record);
|
|
311
312
|
return child;
|
|
312
313
|
}
|
|
313
|
-
/** End the reads remembered: every one, or (`cycles`) only those a cycle or the roster started
|
|
314
|
+
/** End the reads remembered: every one, or (`cycles`) only those a cycle or the roster started; and
|
|
315
|
+
* every cycle's read the warm reader still holds (cycleRead). */
|
|
314
316
|
function endReads({ cycles = false } = {}) {
|
|
315
317
|
for (const record of [...remembered.values()]) if (record.kind === "read" && !(cycles && record.asked)) record.giveUp(ended());
|
|
318
|
+
for (const abandon of [...abandons]) abandon();
|
|
316
319
|
}
|
|
317
320
|
|
|
318
321
|
/** The exec handed to the shared readers: execFile's signature, for `node <bin> <argv…>` (see
|
|
@@ -416,12 +419,53 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
416
419
|
return child;
|
|
417
420
|
}
|
|
418
421
|
|
|
419
|
-
/**
|
|
422
|
+
/** THE WARM READER (packages/client warm-reader.mjs, whose rules are the one client's of the contract):
|
|
423
|
+
* one `oats reader --stdio` of this kernel answers the background reads (--max-age > 0) while it is
|
|
424
|
+
* ready; every other read, and every read before its hello or after it ends, is the shared
|
|
425
|
+
* cliDeploymentRead over this exec and environment, today's read. It starts as every kernel child of
|
|
426
|
+
* the TUI does: `node <bin> …`, in a session of its own (`run`), with the module's stdio. No onStale:
|
|
427
|
+
* the TUI never probes again, so a changed install leaves it on the CLI reads for the rest of its run
|
|
428
|
+
* (the TUI itself runs from that install; starting it again is the fix). Its lifeline is the TUI's
|
|
429
|
+
* hold of its stdin: stop() closes it, and so does the TUI's death. Not a remembered child: it is no
|
|
430
|
+
* read of a cycle, and is never signalled by voidInFlight(). */
|
|
431
|
+
const warm = createWarmReader({ spawn: (file, args, options) => spawn(process.execPath, [file, ...args], { ...options, detached: true }) });
|
|
432
|
+
// On the way out, by stop() or at process exit, nothing new starts: a read the reader still held
|
|
433
|
+
// goes to the shared CLI read, whose exec then refuses.
|
|
434
|
+
const endWarm = () => { stopped = true; warm.stop(); };
|
|
435
|
+
process.once("exit", endWarm);
|
|
436
|
+
/** The cycles' reads the warm reader holds: each one's `abandon`, which answers it now. */
|
|
437
|
+
const abandons = new Set();
|
|
438
|
+
/** A CYCLE'S READ IS MADE VOID WITH ITS CYCLE, as a CLI read's child is ended with it (endReads).
|
|
439
|
+
* A read the warm reader holds is a request inside it, not a child the TUI can end; so a read of a
|
|
440
|
+
* cycle already void (or after stop()) is never sent to it, and voidInFlight() and stop() answer
|
|
441
|
+
* a read it still holds now, each as the shared CLI read whose exec refuses: a failed read, which
|
|
442
|
+
* such a cycle never emits, and no child. The reader's own answer, when it comes, is dropped, and
|
|
443
|
+
* the CLI fallback it keeps refuses too, whenever it runs. So the refresh loop is released at once,
|
|
444
|
+
* and nothing a void cycle asked for runs. */
|
|
445
|
+
function cycleRead(kernel, options) {
|
|
446
|
+
// Its exec is bound to the cycle it belongs to: the shared reader keeps a held read's CLI fallback,
|
|
447
|
+
// which may run after a later cycle began (the reader ends late), and must refuse then too.
|
|
448
|
+
const mine = flight;
|
|
449
|
+
const own = (bin, argv, opts, callback) => {
|
|
450
|
+
if (mine !== epoch) throw new Error("this read was given up before it started");
|
|
451
|
+
return exec(bin, argv, opts, callback);
|
|
452
|
+
};
|
|
453
|
+
const given = () => cliDeploymentRead(kernel, options, { exec: own, env });
|
|
454
|
+
if (stopped || mine !== epoch) return given();
|
|
455
|
+
return new Promise((resolve, reject) => {
|
|
456
|
+
const abandon = () => { abandons.delete(abandon); resolve(given()); };
|
|
457
|
+
abandons.add(abandon);
|
|
458
|
+
warm.read(kernel, options, { exec: own, env }).then(
|
|
459
|
+
(answer) => { if (abandons.delete(abandon)) resolve(answer); },
|
|
460
|
+
(error) => { if (abandons.delete(abandon)) reject(error); });
|
|
461
|
+
});
|
|
462
|
+
}
|
|
463
|
+
/** The shared observer, with the shared readers over this exec and no reader of the TUI's own: a
|
|
420
464
|
* failed read has the same reasons here as in the Desktop. It admits a deployment of the cycle
|
|
421
465
|
* now running and no other. */
|
|
422
466
|
const observer = createDeploymentObserver({
|
|
423
467
|
getContext: (id) => (served.includes(id) ? { deployment: id, cli, revision: 0 } : null),
|
|
424
|
-
read:
|
|
468
|
+
read: cycleRead,
|
|
425
469
|
});
|
|
426
470
|
|
|
427
471
|
/** Run the collector with `input` on stdin: what it printed, or null when it exited nonzero, was
|
|
@@ -496,16 +540,18 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
496
540
|
|
|
497
541
|
/** One deployment of a cycle: its two kernel reads, then the collector over its rows. It emits
|
|
498
542
|
* exactly once, unless the reader was stopped or the cycle made void meanwhile: then it emits
|
|
499
|
-
* nothing and starts nothing more.
|
|
543
|
+
* nothing and starts nothing more. A kernel with feature status-liveness (`kernelLiveness`, on the
|
|
544
|
+
* record this cycle read with) gives rows that are the liveness reading: no collector runs, and
|
|
545
|
+
* each row is the kernel's. */
|
|
500
546
|
async function readDeployment(id, { live, at, number, over }) {
|
|
501
547
|
const answer = await observer.observe(id, { maxAge: live ? 0 : BACKGROUND_MAX_AGE });
|
|
502
548
|
if (over()) return;
|
|
503
549
|
if (!answer.ok) return void onEntry({ id, entry: failedEntry(getEntry(id), answer.reason, at), number });
|
|
504
550
|
const rows = rosterRows(answer.roster, cli);
|
|
505
551
|
// No rows, no collector: livenessAnswers([], null) is [].
|
|
506
|
-
const
|
|
552
|
+
const answers = kernelLiveness(cli) ? [] : livenessAnswers(rows, rows.length ? await collect(JSON.stringify(livenessInput(rows))) : null);
|
|
507
553
|
if (over()) return;
|
|
508
|
-
const instances = panelInstances(rows,
|
|
554
|
+
const instances = panelInstances(rows, answers);
|
|
509
555
|
onEntry({ id, entry: observedEntry({ roster: answer.roster, workspaceStatus: answer.workspaceStatus, observedAt: answer.observedAt }, instances, at), number, read: true });
|
|
510
556
|
}
|
|
511
557
|
|
|
@@ -592,14 +638,16 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
|
|
|
592
638
|
* this run still waits for them: for the line after leaving. Answers after stop() too. */
|
|
593
639
|
changes() { return [...running].map(([child, label]) => ({ pid: child.pid, label })); },
|
|
594
640
|
/** Leave: synchronous and idempotent, safe before start(). The loop and the idle timer are
|
|
595
|
-
* stopped, the observer disposed
|
|
596
|
-
* included. A cycle in flight ends without emitting and without starting anything, and so
|
|
641
|
+
* stopped, the observer disposed, the warm reader's stdin closed (it ends) and every reading
|
|
642
|
+
* child ended (see `sever`), the roster's included. A cycle in flight ends without emitting and without starting anything, and so
|
|
597
643
|
* does a roster read; the follow-up the shared loop still runs after a stop does nothing. */
|
|
598
644
|
stop() {
|
|
599
645
|
stopped = true;
|
|
600
646
|
rosterFlight = null;
|
|
601
647
|
loop.stop();
|
|
602
648
|
observer.dispose();
|
|
649
|
+
endWarm();
|
|
650
|
+
process.off("exit", endWarm);
|
|
603
651
|
clearIdle();
|
|
604
652
|
endReads();
|
|
605
653
|
// Every change is LET GO, never signalled: its timer, if its caller gave it a deadline, is
|
|
@@ -350,7 +350,7 @@ name: acme
|
|
|
350
350
|
members:
|
|
351
351
|
- git:github.com/acme/acme-oats # the host is a member too
|
|
352
352
|
packages:
|
|
353
|
-
oats.framework: v1.16.
|
|
353
|
+
oats.framework: v1.16.4 # the installed CLI's catalog versions (below)
|
|
354
354
|
oats.aweb: v1.32.1 # messaging, and tasks: agent identities, mail, chat and tasks
|
|
355
355
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
356
356
|
defaults:
|
|
@@ -365,7 +365,7 @@ defaultTeam: acme # every soul starts in this team
|
|
|
365
365
|
|
|
366
366
|
- **The versions** are the installed CLI's catalog's:
|
|
367
367
|
`"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
|
|
368
|
-
(for example `oats-framework/v1.16.
|
|
368
|
+
(for example `oats-framework/v1.16.4`: write the part after the `/`) and
|
|
369
369
|
`packages."oats.aweb".ref`, but never below `v1.31.0`: that release
|
|
370
370
|
carries `oats.aweb-tasks`, and a bare version resolves through the
|
|
371
371
|
catalog's tag convention even when the installed catalog names an older
|