@awebai/oats 0.56.0 → 0.57.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 +18 -10
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +11 -4
- package/docs/implementation.md +99 -4
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +136 -25
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/instance-lifecycle.mjs +10 -3
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/tui/README.md +16 -7
- package/packages/tui/lib/actions.mjs +8 -1
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +91 -13
- package/packages/tui/lib/model.mjs +202 -5
- package/packages/tui/lib/read.mjs +132 -13
- package/packages/tui/lib/store.mjs +110 -4
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +38 -8
- package/packages/tui/lib/views/help.mjs +11 -5
- package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/tui.md
CHANGED
|
@@ -12,13 +12,13 @@ install.
|
|
|
12
12
|
`oats tui` is marked **preview**. That means:
|
|
13
13
|
|
|
14
14
|
- **This version shows a workspace's instances, on this machine and on the
|
|
15
|
-
other machines registered on this machine, in one list,
|
|
16
|
-
|
|
17
|
-
machines are the ones `oats server list`
|
|
18
|
-
as they start, stop and wait for you. It
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
for each.
|
|
15
|
+
other machines registered on this machine, in one list, opens an agent's
|
|
16
|
+
terminal, and stops, starts, restarts and retires an agent after a
|
|
17
|
+
confirmation.** The registered machines are the ones `oats server list`
|
|
18
|
+
names. It follows the instances as they start, stop and wait for you. It
|
|
19
|
+
cannot spawn an agent, start one with another harness or model, or add,
|
|
20
|
+
check or remove a machine: [what it does not do
|
|
21
|
+
yet](#what-this-version-does-not-do) names the `oats` command for each.
|
|
22
22
|
- **Its screens and its configuration file may change without notice** while
|
|
23
23
|
it is a preview.
|
|
24
24
|
- **It leaves preview when three things hold:** the readers it shares with
|
|
@@ -305,6 +305,94 @@ view to go back to, and `Esc` and `1` do not close the switcher. The same
|
|
|
305
305
|
holds after a start outside every deployment, which opens the switcher with
|
|
306
306
|
nothing open.
|
|
307
307
|
|
|
308
|
+
## Stopping, starting, restarting and retiring
|
|
309
|
+
|
|
310
|
+
With an instance selected, a capital letter acts on it, always after a
|
|
311
|
+
confirmation:
|
|
312
|
+
|
|
313
|
+
| Key | Does |
|
|
314
|
+
|---|---|
|
|
315
|
+
| `X` | stops it: its session ends, and its home, work and launch are kept |
|
|
316
|
+
| `D` | retires it |
|
|
317
|
+
| `S` | starts a stopped instance as it was last launched |
|
|
318
|
+
| `R` | restarts a running instance as it was last launched |
|
|
319
|
+
|
|
320
|
+
The rules are the Desktop's, from the readers both clients share: an
|
|
321
|
+
instance offers what the Desktop offers for it, and nothing else. One that
|
|
322
|
+
is still being spawned, and one its machine reports it cannot reach, offers
|
|
323
|
+
none; one whose spawn stopped half way offers only to be retired; a running
|
|
324
|
+
one offers restart and not start, a stopped one start and not restart. The
|
|
325
|
+
footer names the keys the selected instance offers now, after `Enter`, and
|
|
326
|
+
on a narrow terminal they are the first hints it gives up. A key for an act
|
|
327
|
+
the instance does not offer opens nothing, and the line above the panes
|
|
328
|
+
says why. The keys are yours to change in
|
|
329
|
+
[`tui.json`](#change-the-keys-tuijson): the actions are `stop`, `retire`,
|
|
330
|
+
`start` and `restart`.
|
|
331
|
+
|
|
332
|
+
**The confirmation** opens over the list, with the focus on `Cancel`.
|
|
333
|
+
`Left`/`Right` and `Tab`/`Shift+Tab` move between its buttons and `Enter`
|
|
334
|
+
presses one. No letter moves the focus, and an `Enter` that arrives in the
|
|
335
|
+
same read of input as the move onto the act's button is ignored, so pasted
|
|
336
|
+
text can open a confirmation but never act in it. `Esc` closes it. `q` and
|
|
337
|
+
`Ctrl+C` still quit. The help (`?`) is not shown over a confirmation.
|
|
338
|
+
|
|
339
|
+
- **Stop and retire read the kernel's plan first** (`oats instance stop
|
|
340
|
+
<instance> --plan`, `oats retire <instance> --plan`) and show what the act
|
|
341
|
+
will do, in the Desktop's words. `Space` switches the plan's choice (for a
|
|
342
|
+
stop: whether the instances spawned from it stop too), which reads a new
|
|
343
|
+
plan. The act's button applies exactly the plan on the screen: when the
|
|
344
|
+
instance changed since, the kernel refuses it and the confirmation shows
|
|
345
|
+
the new plan. For an agent on another machine the plan is read through
|
|
346
|
+
that machine's kernel, and a machine that does not answer gives no plan:
|
|
347
|
+
the confirmation says so.
|
|
348
|
+
- **`Review again`** reads the plan again. **`Check again`** asks what
|
|
349
|
+
became of an apply whose answer did not come, or came in a form
|
|
350
|
+
`oats tui` cannot read: it never applies a second time.
|
|
351
|
+
- **Start and restart have no plan.** The confirmation says what will
|
|
352
|
+
happen and shows the agent's home (and its machine). A restart ends the
|
|
353
|
+
agent's session and starts it again: what it is doing is interrupted.
|
|
354
|
+
Both run `oats session start --home <home>` (or `restart`) with the launch
|
|
355
|
+
recorded for the instance and no choice of harness, model or
|
|
356
|
+
configuration: for those, run `oats session start --home <home>` with
|
|
357
|
+
its options yourself.
|
|
358
|
+
- Once an act has answered, the confirmation shows the answer, and the list
|
|
359
|
+
is read again at once.
|
|
360
|
+
|
|
361
|
+
**One act at a time per instance from this `oats tui`.** While a start or
|
|
362
|
+
restart it sent is still running, whether or not the confirmation is still
|
|
363
|
+
open, no act of that instance opens: the line says
|
|
364
|
+
`The start of <name> is still running.` While a stop or retire it sent is
|
|
365
|
+
still running, another stop or retire from it is refused, with the time
|
|
366
|
+
the running one started.
|
|
367
|
+
|
|
368
|
+
**An act you sent runs to its end.** Closing the confirmation, quitting,
|
|
369
|
+
`Ctrl+Z`, a signal to `oats tui`, or the terminal going away never ends
|
|
370
|
+
it: `oats tui` sends no signal to the kernel command it started, which runs
|
|
371
|
+
in a session of its own and writes to files of its own (below), never to
|
|
372
|
+
`oats tui`. When you leave while one is still running, one line per act is
|
|
373
|
+
printed after the screen is left, on standard error, when that is a
|
|
374
|
+
terminal or a file:
|
|
375
|
+
|
|
376
|
+
oats: the stop of dev-1 is still running; `oats status` shows its result.
|
|
377
|
+
|
|
378
|
+
The exit status never depends on it.
|
|
379
|
+
|
|
380
|
+
**Limits.**
|
|
381
|
+
|
|
382
|
+
- Another `oats tui`, the Desktop, and `oats` run by hand can act on the
|
|
383
|
+
same instance. The kernel's answers hold: from OATS 0.52.0 a stop and a
|
|
384
|
+
retire of one instance refuse each other before either changes anything.
|
|
385
|
+
A stop or a retire does not see a start in flight, and a start does not
|
|
386
|
+
see a retire in flight
|
|
387
|
+
([#866](https://github.com/awebai/oats/issues/866)).
|
|
388
|
+
- An `oats tui` started again knows nothing of the acts an earlier one
|
|
389
|
+
sent: `Check again` there answers that the plan expired, the list shows
|
|
390
|
+
what the kernel reports, and against an earlier one's start still running
|
|
391
|
+
the kernel's start lock is the only guard.
|
|
392
|
+
- An agent on a machine whose OATS is older than 0.52.0: a stop interrupted
|
|
393
|
+
there can leave `.oats-stop-pending.json` in the agent's home, and then
|
|
394
|
+
the agent can be started but not stopped while that file exists.
|
|
395
|
+
|
|
308
396
|
## Keys
|
|
309
397
|
|
|
310
398
|
| Key | Does |
|
|
@@ -319,9 +407,12 @@ nothing open.
|
|
|
319
407
|
| `r` | read now |
|
|
320
408
|
| `1` | the Instances view |
|
|
321
409
|
| `w` | opens [the switcher](#the-switcher) |
|
|
322
|
-
| `Enter` | in the list of instances, opens the selected agent's terminal; in the switcher, opens the selected row |
|
|
410
|
+
| `Enter` | in the list of instances, opens the selected agent's terminal; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
|
|
411
|
+
| `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
|
|
412
|
+
| `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
|
|
413
|
+
| `Space` | in a confirmation, switches the plan's choice |
|
|
323
414
|
| `?` | opens the help; `?` again closes it |
|
|
324
|
-
| `Esc` | closes, in this order: the help, the filter field, a kept filter, then the detail or the switcher |
|
|
415
|
+
| `Esc` | closes, in this order: a confirmation, the help, the filter field, a kept filter, then the detail or the switcher |
|
|
325
416
|
| `q`, `Ctrl+C` | quits, with status 0 (a SIGINT from outside answers 130) |
|
|
326
417
|
| `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns, redraws and reads at once |
|
|
327
418
|
| `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
|
|
@@ -474,16 +565,30 @@ with the Desktop (`packages/client/`).
|
|
|
474
565
|
running when the TUI is suspended is dropped, not shown: its answer could
|
|
475
566
|
arrive cut. That holds for the read of the other machines too. The return
|
|
476
567
|
reads again.
|
|
477
|
-
-
|
|
478
|
-
|
|
568
|
+
- **Stopping, starting, restarting and retiring runs the kernel's own
|
|
569
|
+
commands**, by the same kernel: for a stop or a retire, the plan
|
|
570
|
+
(`oats instance stop <instance> --plan --json`, `oats retire <instance>
|
|
571
|
+
--plan --json`; 30 seconds, 45 for another machine), a read like the
|
|
572
|
+
others, then, when you press the act, the apply of that plan
|
|
573
|
+
(`--plan-revision`, `--idempotency-key`); for a start or a restart,
|
|
574
|
+
`oats session start` or `oats session restart --home <home> --json`. An
|
|
575
|
+
agent on another machine is reached with `--server <id>`. An apply, a
|
|
576
|
+
start and a restart are changes: each runs in a session of its own, with
|
|
577
|
+
no time limit and no signal from `oats tui`, and its output goes to two
|
|
578
|
+
files in a directory of `oats tui`'s own (made with mode 0700 under the
|
|
579
|
+
system's temporary directory), read back when it ends and deleted. On the
|
|
580
|
+
way out the files of a change still running are deleted (it goes on
|
|
581
|
+
writing to them), and the directory is removed. `oats tui` waits for an
|
|
582
|
+
apply's answer for 10 minutes and for a start's for 60 seconds; then it
|
|
583
|
+
says so, and the change goes on.
|
|
584
|
+
- It runs no other command that changes a deployment or a registration, and
|
|
585
|
+
it writes no other file.
|
|
479
586
|
|
|
480
587
|
## What this version does not do
|
|
481
588
|
|
|
482
589
|
| To | Run |
|
|
483
590
|
|---|---|
|
|
484
|
-
|
|
|
485
|
-
| start or restart an agent | `oats session start --home <home>` |
|
|
486
|
-
| retire an agent | `oats retire <instance>` |
|
|
591
|
+
| start an agent with another harness or model | `oats session start --home <home>` with its options |
|
|
487
592
|
| see souls, spawn an agent | `oats souls`, `oats spawn <soul>` |
|
|
488
593
|
| see capabilities | `oats capabilities` |
|
|
489
594
|
| add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
|
|
@@ -601,17 +706,23 @@ in your shell.
|
|
|
601
706
|
shared home's (`packages/client/`), and the TUI writes none of its own
|
|
602
707
|
for a speaker. They never stand before a withheld text: a reason that is
|
|
603
708
|
withheld is `[withheld]` alone.
|
|
604
|
-
- It changes nothing in tmux: no option, key binding, server,
|
|
605
|
-
window or pane. Its probe only lists panes. An agent's
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
[above](#what-it-
|
|
614
|
-
|
|
709
|
+
- It changes nothing in tmux itself: no option, key binding, server,
|
|
710
|
+
session, window or pane. Its probe only lists panes. An agent's own
|
|
711
|
+
session is started, ended or restarted only by the kernel's commands of
|
|
712
|
+
an act you confirmed
|
|
713
|
+
([above](#stopping-starting-restarting-and-retiring)), and an agent's
|
|
714
|
+
terminal is opened by `oats session attach`, which makes its own viewer
|
|
715
|
+
session on the agents' tmux server and removes it; `oats tui` builds no
|
|
716
|
+
viewer and runs no tmux command for either.
|
|
717
|
+
- It starts no daemon, opens no socket and writes no file but the output of
|
|
718
|
+
a change, in its own directory ([above](#what-it-reads-and-what-it-runs)).
|
|
719
|
+
The processes it starts are the reads above, when you open an agent the
|
|
720
|
+
viewer, and the acts you confirm. No read and no viewer outlives it on
|
|
721
|
+
every way out a process can handle, except a viewer that does not end
|
|
722
|
+
when asked (see [above](#what-it-changes-in-your-terminal-and-restores));
|
|
723
|
+
after SIGKILL a read in flight runs to its own end, and a viewer stays
|
|
724
|
+
until you leave it. An act you confirmed is never ended by `oats tui`: it
|
|
725
|
+
runs to its own end.
|
|
615
726
|
|
|
616
727
|
## Errors
|
|
617
728
|
|
package/docs/workspaces.md
CHANGED
|
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.10.
|
|
58
|
-
oats.okf: v5.
|
|
57
|
+
oats.framework: v1.10.2 # bare version → resolves through the official catalog
|
|
58
|
+
oats.okf: v5.2.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
61
61
|
teams: # SHARED teams: the same provider team for everyone
|