@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.
Files changed (48) hide show
  1. package/bin/oats.mjs +78 -320
  2. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  3. package/docs/design/2026-10-29-warm-reader.md +261 -0
  4. package/docs/design/README.md +4 -0
  5. package/docs/desktop-cli-api.md +250 -12
  6. package/docs/execution-targets.md +11 -2
  7. package/docs/implementation.md +26 -8
  8. package/docs/integrations.md +1 -1
  9. package/docs/knowledge.md +14 -7
  10. package/docs/named-test-runs.md +4 -0
  11. package/docs/official-catalog.md +3 -3
  12. package/docs/packages.md +12 -12
  13. package/docs/release-notes/v0.69.6.md +165 -0
  14. package/docs/schedules.md +8 -1
  15. package/docs/tui.md +21 -4
  16. package/docs/upgrading.md +9 -5
  17. package/docs/workspaces.md +2 -2
  18. package/lib/argv.mjs +41 -0
  19. package/lib/automation-scope.mjs +6 -4
  20. package/lib/automations.mjs +61 -11
  21. package/lib/captured-context.mjs +12 -0
  22. package/lib/hot-reads.mjs +21 -15
  23. package/lib/install-stamp.mjs +61 -0
  24. package/lib/instance-events.mjs +8 -6
  25. package/lib/instance-listing.mjs +13 -5
  26. package/lib/kernel-features.mjs +10 -0
  27. package/lib/local-edit.mjs +1 -1
  28. package/lib/local-inputs.mjs +3 -0
  29. package/lib/member-clone.mjs +15 -11
  30. package/lib/read-call.mjs +143 -0
  31. package/lib/reader.mjs +203 -0
  32. package/lib/remote.mjs +47 -6
  33. package/lib/resolved-deployment.mjs +12 -4
  34. package/lib/roster-read.mjs +199 -0
  35. package/lib/session-input.mjs +35 -11
  36. package/lib/workspace-read.mjs +160 -0
  37. package/package-catalog.json +2 -2
  38. package/package.json +1 -1
  39. package/packages/client/cli-locator.mjs +1 -0
  40. package/packages/client/cli-probe-contract.mjs +4 -2
  41. package/packages/client/deployment-observer.mjs +8 -3
  42. package/packages/client/deployment-panel.mjs +17 -1
  43. package/packages/client/deployment-read-cli.mjs +48 -27
  44. package/packages/client/own-codes.mjs +3 -0
  45. package/packages/client/warm-reader.mjs +241 -0
  46. package/packages/tui/lib/client.mjs +2 -1
  47. package/packages/tui/lib/read.mjs +59 -11
  48. 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, the roster of other machines, the refresh loop,
3
- // the liveness collector, and the two looks at the file system the switcher needs.
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
- /** The shared observer, with the shared reader over this exec and no reader of the TUI's own: a
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: (kernel, options) => cliDeploymentRead(kernel, options, { exec, env }),
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 printed = rows.length ? await collect(JSON.stringify(livenessInput(rows))) : null;
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, livenessAnswers(rows, printed));
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 and every reading child ended (see `sever`), the roster's
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.3 # the installed CLI's catalog versions (below)
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.3`: write the part after the `/`) and
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