@awebai/oats 0.58.0 → 0.59.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.
Files changed (53) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +68 -3
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +11 -0
  5. package/docs/implementation.md +2 -0
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +4 -4
  8. package/docs/official-catalog.md +4 -4
  9. package/docs/packages.md +14 -14
  10. package/docs/release-notes/v0.59.0.md +288 -0
  11. package/docs/servers.md +4 -1
  12. package/docs/souls-and-instances.md +21 -0
  13. package/docs/tui.md +644 -118
  14. package/docs/workspaces.md +2 -2
  15. package/lib/core.mjs +216 -42
  16. package/lib/read-ahead-worker.mjs +119 -0
  17. package/lib/read-ahead.mjs +115 -0
  18. package/lib/retire-state.mjs +33 -0
  19. package/lib/servers.mjs +9 -1
  20. package/lib/session-input.mjs +14 -4
  21. package/package-catalog.json +3 -3
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-data.mjs +4 -0
  25. package/packages/client/deployment-panel.mjs +3 -0
  26. package/packages/client/instance-acts.mjs +23 -8
  27. package/packages/client/instance-presentation.mjs +3 -2
  28. package/packages/client/instance-tree.mjs +84 -39
  29. package/packages/client/lifecycle-confirmation.mjs +9 -3
  30. package/packages/client/remote-roster.mjs +4 -1
  31. package/packages/client/retire-in-flight.mjs +65 -0
  32. package/packages/client/retire-state.mjs +30 -0
  33. package/packages/client/spawn-apply.mjs +13 -4
  34. package/packages/tui/README.md +23 -10
  35. package/packages/tui/lib/actions.mjs +63 -5
  36. package/packages/tui/lib/client.mjs +12 -1
  37. package/packages/tui/lib/config.mjs +7 -2
  38. package/packages/tui/lib/main.mjs +315 -82
  39. package/packages/tui/lib/model.mjs +523 -56
  40. package/packages/tui/lib/panel.mjs +436 -125
  41. package/packages/tui/lib/read.mjs +52 -26
  42. package/packages/tui/lib/store.mjs +908 -65
  43. package/packages/tui/lib/term/keys.mjs +9 -2
  44. package/packages/tui/lib/term/text.mjs +4 -0
  45. package/packages/tui/lib/term/through.mjs +12 -1
  46. package/packages/tui/lib/views/frame.mjs +394 -95
  47. package/packages/tui/lib/views/help.mjs +54 -13
  48. package/packages/tui/lib/views/instances.mjs +43 -25
  49. package/packages/tui/lib/views/palette.mjs +61 -0
  50. package/packages/tui/lib/views/souls.mjs +268 -0
  51. package/packages/tui/lib/views/spawn.mjs +299 -0
  52. package/packages/tui/lib/views/split.mjs +29 -0
  53. 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 ended by the TUI,
6
- // and their output goes to two files of the run's own private directory, the only files this
7
- // module writes. (Opening an agent's terminal starts the kernel's viewer, which is not a read and
8
- // is not started here: it runs in a pane of the panel's private tmux server, lib/panel.mjs.)
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 TUI: a stop killed while it waits leaves a marker that refuses every
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 signalled.
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 and the children's time limits (for tests). `files`
240
- * is where a change's output is written (for tests): `files.dir()` makes the run's private
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). execFile's signature for `node <bin> <argv…>`, in
373
- * a session of its own, outside every cycle: it is never made void by voidInFlight() and never
374
- * signalled, not by `sever`, not by stop(), not at a time limit (a `timeout` given is not
375
- * armed: the shared callers end their wait, never the child). `options.label` is the caller's
376
- * `{ verb, name }`, kept for the line after leaving (`changes()`), and is not passed on.
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: _never, maxBuffer = Infinity, encoding: _utf8, ...options }, callback) {
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
- child.once("exit", () => { running.delete(child); });
421
- child.once("close", (code, signal) => finish(code === 0 && signal === null ? null : failure({ code, signal, killed: false })));
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 handle no longer holds the process, and its two
611
- // files are unlinked (the child goes on writing to them, and nothing is left behind). The
612
- // private directory goes when it is empty.
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
  },