@awebai/oats 0.56.0 → 0.57.1

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 (64) hide show
  1. package/bin/oats.mjs +18 -10
  2. package/docs/configuration.md +17 -27
  3. package/docs/desktop-cli-api.md +59 -3
  4. package/docs/desktop.md +25 -4
  5. package/docs/execution-targets.md +6 -1
  6. package/docs/implementation.md +106 -5
  7. package/docs/integrations.md +8 -4
  8. package/docs/knowledge.md +93 -38
  9. package/docs/official-catalog.md +3 -3
  10. package/docs/packages.md +12 -12
  11. package/docs/release-notes/v0.57.0.md +283 -0
  12. package/docs/release-notes/v0.57.1.md +275 -0
  13. package/docs/schedules.md +8 -3
  14. package/docs/servers.md +18 -0
  15. package/docs/souls-and-instances.md +126 -15
  16. package/docs/tui.md +333 -95
  17. package/docs/workspaces.md +2 -2
  18. package/lib/core.mjs +439 -126
  19. package/lib/instance-lifecycle.mjs +45 -9
  20. package/lib/session-viewer.mjs +29 -4
  21. package/lib/worktree.mjs +23 -2
  22. package/package-catalog.json +2 -2
  23. package/package.json +1 -1
  24. package/packages/client/cli-adapter.mjs +9 -7
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/composed-gate.mjs +34 -0
  27. package/packages/client/inspect-boundary.mjs +157 -0
  28. package/packages/client/inspect-cache.mjs +86 -0
  29. package/packages/client/instance-lifecycle.mjs +10 -3
  30. package/packages/client/keyed-catalog.mjs +132 -0
  31. package/packages/client/launch-prompt-outcome.mjs +1 -1
  32. package/packages/client/launch-view.mjs +46 -0
  33. package/packages/client/session-attach.mjs +7 -5
  34. package/packages/client/soul-catalog.mjs +77 -0
  35. package/packages/client/soul-colors.mjs +31 -0
  36. package/packages/client/soul-facts.mjs +85 -0
  37. package/packages/client/soul-rows.mjs +48 -0
  38. package/packages/client/spawn-apply-cli.mjs +11 -6
  39. package/packages/client/spawn-apply.mjs +212 -0
  40. package/packages/client/spawn-messages.mjs +131 -85
  41. package/packages/client/spawn-preview-contract.mjs +3 -0
  42. package/packages/client/spawn-preview-facts.mjs +119 -0
  43. package/packages/client/spawn-preview.mjs +152 -0
  44. package/packages/client/spawn-transaction.mjs +136 -0
  45. package/packages/tui/README.md +43 -13
  46. package/packages/tui/lib/actions.mjs +18 -2
  47. package/packages/tui/lib/client.mjs +4 -0
  48. package/packages/tui/lib/config.mjs +9 -14
  49. package/packages/tui/lib/main.mjs +241 -55
  50. package/packages/tui/lib/model.mjs +230 -29
  51. package/packages/tui/lib/panel.mjs +955 -0
  52. package/packages/tui/lib/read.mjs +134 -24
  53. package/packages/tui/lib/store.mjs +184 -31
  54. package/packages/tui/lib/term/capture.mjs +260 -0
  55. package/packages/tui/lib/term/screen.mjs +44 -8
  56. package/packages/tui/lib/term/style.mjs +78 -6
  57. package/packages/tui/lib/term/text.mjs +24 -4
  58. package/packages/tui/lib/term/through.mjs +213 -0
  59. package/packages/tui/lib/term/tty.mjs +7 -60
  60. package/packages/tui/lib/views/act.mjs +85 -0
  61. package/packages/tui/lib/views/frame.mjs +153 -37
  62. package/packages/tui/lib/views/help.mjs +22 -14
  63. package/skills/oats-getting-started/SKILL.md +4 -3
  64. package/packages/tui/lib/open.mjs +0 -45
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, and opens an
16
- agent's terminal. It changes nothing in a deployment.** The registered
17
- machines are the ones `oats server list` names. It follows the instances
18
- as they start, stop and wait for you. It cannot stop, start, restart or
19
- retire an agent, spawn one, or add, check or remove a machine: [what it
20
- does not do yet](#what-this-version-does-not-do) names the `oats` command
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
@@ -78,7 +78,7 @@ runs.
78
78
 
79
79
  ```
80
80
  oats acme-platform +1 machine 4 running 1 needs input 2 stopped
81
- 1 Instances 2 Souls 3 Capabilities read 14:03:27
81
+ Instances Souls Capabilities read 14:03:27
82
82
  ──────────────────────────────────────────────┬─────────────────────────────────────────────────
83
83
  This machine │ api-lead
84
84
  ▾ ● backend-lead claude │ soul tech-lead
@@ -91,7 +91,7 @@ runs.
91
91
  │
92
92
  ○ reviewer-api stopped │
93
93
  ──────────────────────────────────────────────┴─────────────────────────────────────────────────
94
- / filter Tab detail r refresh w workspaces ? help q quit
94
+ / filter Tab detail r refresh w workspaces 1-3 views ? help q quit
95
95
  ```
96
96
 
97
97
  - **The header** has the workspace's name, then what the view holds of
@@ -102,10 +102,14 @@ runs.
102
102
  every row of the view: instances running, instances that need input,
103
103
  stopped, state unknown, and rows the kernel reported that were withheld (a
104
104
  home outside its soul's directory, or one reported twice). A count of zero
105
- is left out. The second row names the views; `2 Souls` and
106
- `3 Capabilities` are dim because they cannot be opened yet. On the right
107
- is the time of the read of this machine that the screen shows: it moves
108
- with every read.
105
+ is left out. The second row names the views, `Instances Souls
106
+ Capabilities`: the open one is drawn in reverse video, and `Souls` and
107
+ `Capabilities` are dim because they cannot be opened yet. Their keys,
108
+ `1`, `2` and `3`, are not drawn beside the names: the help names each,
109
+ and the footer names the three as one hint, `1-3 views`, which a narrow
110
+ footer gives up right after the acts. `2` and `3` say what to run
111
+ instead. On the right is the time of the read
112
+ of this machine that the screen shows: it moves with every read.
109
113
  - **The list** is the roster the Desktop draws: the same groups in the same
110
114
  order, from the same code. An instance that others were spawned from
111
115
  comes first, and the ones below it are indented under it; instances
@@ -127,29 +131,9 @@ runs.
127
131
  branch, team, parent, when it last started, and its home. From 80
128
132
  columns up it stands beside the list; on a narrower terminal `Tab` opens
129
133
  it as a page.
130
- - **Opening an agent.** `Enter` on an instance that runs gives your terminal
131
- to that agent's own terminal, through `oats session attach`: you see what
132
- the agent shows, and what you type goes to it. `Ctrl+\` brings `oats tui`
133
- back, and the agent keeps running. The key is yours to change
134
- ([`tui.json`](#change-the-keys-tuijson)), and the footer names it whenever
135
- `Enter` would open.
136
- - Inside tmux the agent opens in the same pane. `oats tui` makes no window
137
- and no split.
138
- - After the return the instances are read again at once, and one line
139
- says what happened: that you left and the agent keeps running, that it
140
- could not be opened, or that the connection to its machine ended. When
141
- the agent's own terminal ended while you were in it, you are back with
142
- no line: the list shows the agent as it now is.
143
- - What `oats session attach` printed when it failed stands under that line
144
- in quotation marks. It is not said who printed it: OATS, tmux and ssh
145
- all can.
146
- - `Enter` on an instance that cannot be opened opens nothing and says why:
147
- it does not run, whether it runs is not known, the detail's reason holds
148
- it, or its machine's OATS is older than 0.51.0 and has no key to leave a
149
- viewer.
150
- - For each time you open an agent, one line of tmux's own stays on your
151
- screen and is there after you quit: `[detached (from session …)]`, or
152
- `[exited]`.
134
+ - **Opening an agent.** `Enter` on an instance that runs opens its terminal
135
+ beside the list, where the detail was: see
136
+ [Open an agent's terminal](#open-an-agents-terminal).
153
137
 
154
138
  **A view of more than one deployment** (this machine and another, or two
155
139
  deployments on one machine) is one list, grouped as the Desktop groups it:
@@ -238,6 +222,78 @@ The next read that succeeds shows the machines as they then report.
238
222
  Names are cut by terminal cells with `…` (`...` in ASCII) when they do not
239
223
  fit; the detail shows them whole.
240
224
 
225
+ ## Open an agent's terminal
226
+
227
+ ```
228
+ oats acme-platform 2 running
229
+ Instances Souls Capabilities read 14:03:27
230
+ ──────────────────────────────────────┬─────────────────────────────────────────
231
+ > ● backend-lead claude │ backend-lead
232
+ ● docs-writer claude │$ make docs
233
+ │Building the reference...
234
+ │
235
+ ──────────────────────────────────────┴─────────────────────────────────────────
236
+ C-\ back to the list
237
+ ```
238
+
239
+ - **`Enter` on an instance that runs** opens its terminal on the right of
240
+ the body, where the detail was, with the list on the left. Its top row
241
+ names the agent (and `on <machine>` for one of another machine); under it
242
+ is the agent's screen, as the agent draws it, in its own colours.
243
+ - **The terminal has the focus.** What you type, what you paste and every
244
+ key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
245
+ among them, but for **the back key** (`Ctrl+\` unless
246
+ [`tui.json`](#change-the-keys-tuijson) names another). The back key gives
247
+ the focus to the list. While the terminal has the focus the footer names
248
+ only that key: `C-\ back to the list`. A back key inside a paste is
249
+ pasted, not taken.
250
+ - **With the list focused** the terminal stays open, and the agent's screen
251
+ is still drawn as it changes. The footer names the keys for it:
252
+ `Enter focus terminal` on its row, `z zoom` and `c close terminal`.
253
+ - `Enter` on the open terminal's row gives it the focus again.
254
+ - `z` gives it the focus and the whole body: the header and the footer
255
+ stay, the list is hidden. The back key brings the list back beside it.
256
+ - `c` closes it: the agent keeps running, and the right side is the
257
+ detail again.
258
+ - `Tab` shows the detail in its place until `Tab` or `Esc`. Nothing of
259
+ the terminal is drawn meanwhile, and its screen is read afresh when it
260
+ shows again.
261
+ - **One terminal is open at a time.** `Enter` on another instance that runs
262
+ closes the open one and opens that one.
263
+ - **Under 80 columns** the terminal is always shown with the whole body
264
+ when it has the focus. With the list focused the list is shown alone; the
265
+ terminal stays open, unseen, and `Enter focus terminal` in the footer
266
+ shows it again. Beside the list the terminal is never narrower than 40
267
+ columns.
268
+ - **A terminal also closes by itself** when its viewer ends: the agent's
269
+ window ended, its session went away, or the link to its machine dropped.
270
+ It closes within a second of that (tmux tells `oats tui` of a viewer's
271
+ end once a second). The instances are then read again at once, and one line above the panes
272
+ says what happened: that it could not be opened, that the connection to
273
+ its machine ended, or that the viewer ended without saying why. What the
274
+ viewer printed on its error output stands under that line in quotation
275
+ marks, without saying who printed it: OATS, tmux and ssh all can. When
276
+ the viewer ended cleanly there is no line, and a terminal you closed
277
+ yourself says nothing. **A terminal is never opened again by itself**:
278
+ `Enter` opens it.
279
+ - **`Enter` on an instance that cannot be opened** opens nothing and says
280
+ why: it does not run, whether it runs is not known, or the detail's
281
+ reason holds it. An agent on another machine is asked first whether it
282
+ can be opened (`Esc` gives that up); a machine whose OATS cannot open its
283
+ sessions is said then.
284
+ - **No scrollback but the viewer's own, and no mouse.** The panel shows
285
+ what the agent's window shows now; what has scrolled away is reached as
286
+ the agent's own terminal reaches it.
287
+ - **How it works.** The terminal is the kernel's own viewer,
288
+ `oats session attach`, run in a pane of a tmux server private to this run
289
+ of `oats tui`: its socket is in a directory of the run's own (mode 0700,
290
+ under the system's temporary directory), it reads no tmux configuration
291
+ of yours, and it has no prefix key, no key binding and no status line.
292
+ `oats tui` reads that pane's screen when tmux says it changed, never on a
293
+ timer: an idle terminal costs no frame. Inside tmux nothing changes: the
294
+ agent opens in the TUI's panel, and `oats tui` makes no window and no
295
+ split in your tmux.
296
+
241
297
  ## The switcher
242
298
 
243
299
  `w` opens the switcher: what this run can show, over the whole body of the
@@ -305,6 +361,94 @@ view to go back to, and `Esc` and `1` do not close the switcher. The same
305
361
  holds after a start outside every deployment, which opens the switcher with
306
362
  nothing open.
307
363
 
364
+ ## Stopping, starting, restarting and retiring
365
+
366
+ With an instance selected, a capital letter acts on it, always after a
367
+ confirmation:
368
+
369
+ | Key | Does |
370
+ |---|---|
371
+ | `X` | stops it: its session ends, and its home, work and launch are kept |
372
+ | `D` | retires it |
373
+ | `S` | starts a stopped instance as it was last launched |
374
+ | `R` | restarts a running instance as it was last launched |
375
+
376
+ The rules are the Desktop's, from the readers both clients share: an
377
+ instance offers what the Desktop offers for it, and nothing else. One that
378
+ is still being spawned, and one its machine reports it cannot reach, offers
379
+ none; one whose spawn stopped half way offers only to be retired; a running
380
+ one offers restart and not start, a stopped one start and not restart. The
381
+ footer names the keys the selected instance offers now, after `Enter`, and
382
+ on a narrow terminal they are the first hints it gives up. A key for an act
383
+ the instance does not offer opens nothing, and the line above the panes
384
+ says why. The keys are yours to change in
385
+ [`tui.json`](#change-the-keys-tuijson): the actions are `stop`, `retire`,
386
+ `start` and `restart`.
387
+
388
+ **The confirmation** opens over the list, with the focus on `Cancel`.
389
+ `Left`/`Right` and `Tab`/`Shift+Tab` move between its buttons and `Enter`
390
+ presses one. No letter moves the focus, and an `Enter` that arrives in the
391
+ same read of input as the move onto the act's button is ignored, so pasted
392
+ text can open a confirmation but never act in it. `Esc` closes it. `q` and
393
+ `Ctrl+C` still quit. The help (`?`) is not shown over a confirmation.
394
+
395
+ - **Stop and retire read the kernel's plan first** (`oats instance stop
396
+ <instance> --plan`, `oats retire <instance> --plan`) and show what the act
397
+ will do, in the Desktop's words. `Space` switches the plan's choice (for a
398
+ stop: whether the instances spawned from it stop too), which reads a new
399
+ plan. The act's button applies exactly the plan on the screen: when the
400
+ instance changed since, the kernel refuses it and the confirmation shows
401
+ the new plan. For an agent on another machine the plan is read through
402
+ that machine's kernel, and a machine that does not answer gives no plan:
403
+ the confirmation says so.
404
+ - **`Review again`** reads the plan again. **`Check again`** asks what
405
+ became of an apply whose answer did not come, or came in a form
406
+ `oats tui` cannot read: it never applies a second time.
407
+ - **Start and restart have no plan.** The confirmation says what will
408
+ happen and shows the agent's home (and its machine). A restart ends the
409
+ agent's session and starts it again: what it is doing is interrupted.
410
+ Both run `oats session start --home <home>` (or `restart`) with the launch
411
+ recorded for the instance and no choice of harness, model or
412
+ configuration: for those, run `oats session start --home <home>` with
413
+ its options yourself.
414
+ - Once an act has answered, the confirmation shows the answer, and the list
415
+ is read again at once.
416
+
417
+ **One act at a time per instance from this `oats tui`.** While a start or
418
+ restart it sent is still running, whether or not the confirmation is still
419
+ open, no act of that instance opens: the line says
420
+ `The start of <name> is still running.` While a stop or retire it sent is
421
+ still running, another stop or retire from it is refused, with the time
422
+ the running one started.
423
+
424
+ **An act you sent runs to its end.** Closing the confirmation, quitting,
425
+ `Ctrl+Z`, a signal to `oats tui`, or the terminal going away never ends
426
+ it: `oats tui` sends no signal to the kernel command it started, which runs
427
+ in a session of its own and writes to files of its own (below), never to
428
+ `oats tui`. When you leave while one is still running, one line per act is
429
+ printed after the screen is left, on standard error, when that is a
430
+ terminal or a file:
431
+
432
+ oats: the stop of dev-1 is still running; `oats status` shows its result.
433
+
434
+ The exit status never depends on it.
435
+
436
+ **Limits.**
437
+
438
+ - Another `oats tui`, the Desktop, and `oats` run by hand can act on the
439
+ same instance. The kernel's answers hold: from OATS 0.52.0 a stop and a
440
+ retire of one instance refuse each other before either changes anything.
441
+ A stop or a retire does not see a start in flight, and a start does not
442
+ see a retire in flight
443
+ ([#866](https://github.com/awebai/oats/issues/866)).
444
+ - An `oats tui` started again knows nothing of the acts an earlier one
445
+ sent: `Check again` there answers that the plan expired, the list shows
446
+ what the kernel reports, and against an earlier one's start still running
447
+ the kernel's start lock is the only guard.
448
+ - An agent on a machine whose OATS is older than 0.52.0: a stop interrupted
449
+ there can leave `.oats-stop-pending.json` in the agent's home, and then
450
+ the agent can be started but not stopped while that file exists.
451
+
308
452
  ## Keys
309
453
 
310
454
  | Key | Does |
@@ -318,10 +462,17 @@ nothing open.
318
462
  | `/` | filter |
319
463
  | `r` | read now |
320
464
  | `1` | the Instances view |
465
+ | `2`, `3` | the Souls and Capabilities views: not in this version, so a line says what to run instead |
321
466
  | `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 |
467
+ | `Enter` | in the list of instances, opens the selected agent's terminal beside the list, or gives it the focus when it is the open one; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
468
+ | `z` | gives the open terminal the focus and the whole body |
469
+ | `c` | closes the open terminal; the agent keeps running |
470
+ | `Ctrl+\` | while a terminal has the focus, the back key: the focus goes to the list ([`tui.json`](#change-the-keys-tuijson) can name another) |
471
+ | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
472
+ | `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
473
+ | `Space` | in a confirmation, switches the plan's choice |
323
474
  | `?` | 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 |
475
+ | `Esc` | closes, in this order: a confirmation, the help, the filter field, a kept filter, then the detail or the switcher |
325
476
  | `q`, `Ctrl+C` | quits, with status 0 (a SIGINT from outside answers 130) |
326
477
  | `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns, redraws and reads at once |
327
478
  | `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
@@ -336,8 +487,9 @@ where it is, and the list returns to it at the next key that moves it.
336
487
 
337
488
  The help screen is generated from the table the program acts on, so it
338
489
  always lists the keys that work, with the marks and with what this version
339
- does not do. The movement keys scroll it. While `oats tui` has the screen,
340
- `Ctrl+\` does nothing.
490
+ does not do. The movement keys scroll it. While a terminal has the focus
491
+ the table's keys are the agent's: the back key alone is the TUI's. With the
492
+ list focused the back key does nothing.
341
493
 
342
494
  **The filter.** `/` opens a field on the last row. What you type narrows the
343
495
  list to the instances whose name, soul or repository contains it, with the
@@ -371,10 +523,12 @@ never writes it. With no file the keys are the ones above.
371
523
  do not name keeps its keys.
372
524
  - The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
373
525
  `collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
374
- `workspaces`, `open`, `help`, `close`, `quit`, `suspend` and `redraw`.
375
- `workspaces` (`w`) opens the switcher and `open` (`enter`) opens the
376
- selected agent's terminal in the list of instances and the selected row
377
- in the switcher. In an open filter field `Enter` keeps the filter,
526
+ `souls`, `capabilities`, `workspaces`, `open`, `zoom`, `close-terminal`,
527
+ `stop`, `retire`, `start`, `restart`, `help`, `close`, `quit`, `suspend`
528
+ and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
529
+ opens the selected agent's terminal in the list of instances and the
530
+ selected row in the switcher. `zoom` (`z`) and `close-terminal` (`c`) act
531
+ on the open terminal. In an open filter field `Enter` keeps the filter,
378
532
  whatever key `open` has.
379
533
  - A key is written as the help shows it, in lower case: `q`, `G`, `?`,
380
534
  `space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
@@ -383,12 +537,15 @@ never writes it. With no file the keys are the ones above.
383
537
  and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
384
538
  keys of their own.
385
539
  - `ascii: true` is `--ascii`.
386
- - `open.detachKey` is the key that leaves an agent's terminal, written as
387
- `oats session attach --detach-key` takes it: `C-\` when you name none.
388
- [Execution targets](execution-targets.md) has the keys that can be chosen.
389
- `oats tui` does not check it: a key OATS refuses is said when you open an
390
- agent. A key that tmux's copy mode binds leaves the viewer once that mode
391
- is left.
540
+ - `open.detachKey` is **the back key**: the key that takes the focus from
541
+ an agent's terminal back to the list, `C-\` when you name none. It is
542
+ `oats tui`'s own and never reaches the agent or the kernel. It is one of
543
+ these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
544
+ terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
545
+ `]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
546
+ alone or with one of `C-`, `M-`, `S-` (`C-F5`). These are the keys a
547
+ `tui.json` written for an earlier version could name, with the same
548
+ meaning for the key.
392
549
 
393
550
  **A file it cannot honour stops the start.** Each problem is one line on
394
551
  stderr, the status is 1 and nothing is drawn; it resolves no conflict and
@@ -401,9 +558,7 @@ guesses nothing. It refuses:
401
558
  | is not one JSON object | `it is not valid JSON`, `it is not one JSON object` |
402
559
  | has a setting other than `keys`, `ascii` and `open`, or one of the wrong kind | `unknown setting …`, `keys must be an object`, `ascii must be true or false`, `open must be an object` |
403
560
  | has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
404
- | gives `open.detachKey` something that is not 1 to 16 printable ASCII characters | `open.detachKey must be 1 to 16 printable ASCII characters` |
405
- | gives `open.detachKey` a value that begins with `-` | `open.detachKey cannot begin with -` |
406
- | gives `open.detachKey` a value the help would draw as another key (a run of spaces, a space at an end) | `open.detachKey is a key the help cannot name` |
561
+ | gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
407
562
  | names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
408
563
  | names an action that does not exist | `unknown action …`, with the list of actions |
409
564
  | gives an action something that is not a list of strings | `… must be a list of key ids` |
@@ -461,29 +616,88 @@ with the Desktop (`packages/client/`).
461
616
  `oats-local.yaml`. An entry that is a link is not followed. When a folder
462
617
  is opened, that one directory is asked again.
463
618
  - **Opening an agent runs one more command,** `oats session attach --home
464
- <home> --detach-key <key>`, by the same kernel, with your terminal as its
465
- terminal. For an agent on another machine `oats session inspect --server
466
- <id> --home <home> --json` is asked first (20 seconds), then `oats session
467
- attach --server <id> --home <home> --detach-key <key>`. Nothing is read
468
- while the agent has the terminal, and the return reads at once.
619
+ <home>`, by the same kernel, in a pane of the run's private tmux server
620
+ ([above](#open-an-agents-terminal)), with no key of its own. For an agent
621
+ on another machine `oats session inspect --server <id> --home <home>
622
+ --json` is asked first (20 seconds), then `oats session attach --server
623
+ <id> --home <home>`. The reads go on while a terminal is open, and the end
624
+ of a viewer reads at once.
625
+ - **The private tmux server** is `tmux` found on `PATH`, 3.2 or later. It
626
+ is started at the first open of a run, with `-f /dev/null` and the
627
+ environment's `TMUX` and `TMUX_PANE` removed, and its socket in the run's
628
+ own directory. The control client that `oats tui` keeps for the run
629
+ starts it, with `exit-unattached` set in the same command. Its first window is a keeper: it
630
+ watches `alive`, a FIFO in the run's directory (0600, made with the
631
+ system's `mkfifo`) that `oats tui` holds open for writing until it ends.
632
+ When `oats tui` is gone, whatever ended it and at any moment, the keeper
633
+ kills the server. The keeper needs two things from the base system,
634
+ found on `PATH` like `tmux`.
635
+ - **`mkfifo`** makes `alive`. Without it an open is refused: the line
636
+ says the terminal could not be opened, with what was said under it.
637
+ - **A way to tell that the server is still its parent.** The keeper reads
638
+ that from `/proc` where the system has one (Linux), and otherwise asks
639
+ `ps -o ppid= -p` (macOS). With neither (no `/proc`, and no `ps` or one
640
+ that refuses `-p`, like BusyBox's), the keeper kills nothing. A normal
641
+ end is not affected. An `oats tui` killed with SIGKILL can then leave
642
+ its private server running, with the open terminal's viewer still
643
+ attached to the agent, until you end it with `tmux -S
644
+ <run directory>/tmux kill-server`. The next run's sweep leaves that
645
+ directory alone while its socket answers.
646
+
647
+ Each open is a window of the server, whose process is the viewer itself,
648
+ with no shell between them. It is closed with `kill-pane`, which hangs up
649
+ the viewer's terminal: the viewer gets SIGHUP at once and removes its own
650
+ session on the agents' server. The viewer's error output goes to a file
651
+ of the run's directory (0600), read back when it ends and deleted. Its
652
+ exit status is the one tmux keeps for a pane whose process ended
653
+ (`remain-on-exit`), which the server reports to `oats tui` within a
654
+ second; `oats tui` then closes that pane. What the terminal
655
+ shows is captured into `capture` in that directory, which the server
656
+ writes and `oats tui` reads back, so nothing an agent prints passes
657
+ through the stream on which `oats tui` reads the server's answers. An
658
+ answer the server would never give ends that stream, and the open
659
+ terminal closes with it. The server is ended
660
+ on every way out a process can handle. At its start a run also removes
661
+ what a run that is gone left (below), and nothing else: it signals
662
+ nothing.
469
663
  - **Every read runs in a session of its own** and is ended when the TUI
470
664
  ends, on every way out a process can handle (for SIGKILL see
471
- [below](#what-it-changes-in-your-terminal-and-restores)). The viewer
472
- shares your terminal, and is ended first when `oats tui` is ended while an
473
- agent has the terminal. A read that was
665
+ [below](#what-it-changes-in-your-terminal-and-restores)). An open
666
+ terminal's viewer ends with the private server. A read that was
474
667
  running when the TUI is suspended is dropped, not shown: its answer could
475
668
  arrive cut. That holds for the read of the other machines too. The return
476
669
  reads again.
477
- - It runs no command that changes a deployment or a registration, and it
478
- writes no file.
670
+ - **Stopping, starting, restarting and retiring runs the kernel's own
671
+ commands**, by the same kernel: for a stop or a retire, the plan
672
+ (`oats instance stop <instance> --plan --json`, `oats retire <instance>
673
+ --plan --json`; 30 seconds, 45 for another machine), a read like the
674
+ others, then, when you press the act, the apply of that plan
675
+ (`--plan-revision`, `--idempotency-key`); for a start or a restart,
676
+ `oats session start` or `oats session restart --home <home> --json`. An
677
+ agent on another machine is reached with `--server <id>`. An apply, a
678
+ start and a restart are changes: each runs in a session of its own, with
679
+ no time limit and no signal from `oats tui`, and its output goes to two
680
+ files in a directory of `oats tui`'s own (made with mode 0700 under the
681
+ system's temporary directory), read back when it ends and deleted. On the
682
+ way out the files of a change still running are deleted (it goes on
683
+ writing to them), and the directory is removed. `oats tui` waits for an
684
+ apply's answer for 10 minutes and for a start's for 60 seconds; then it
685
+ says so, and the change goes on.
686
+ - It runs no other command that changes a deployment or a registration, and
687
+ it writes no other file but the private server's: its socket `tmux`, the
688
+ keeper's FIFO `alive`, `capture` (the open terminal's screen, which the
689
+ server writes there for `oats tui` to read), and `owner.json` (`{ "tool":
690
+ "oats-tui", "pid": …, "started": … }`), which lets a later run tell a
691
+ directory a run that is gone left. A run that ends normally removes all
692
+ four. A later run removes such a directory, these four files included, when its `pid` is not alive
693
+ and its socket answers no tmux; it looks only at directories named `oats-tui-*` in the
694
+ system's temporary directory, yours, of mode 0700, holding that file.
479
695
 
480
696
  ## What this version does not do
481
697
 
482
698
  | To | Run |
483
699
  |---|---|
484
- | stop an agent | `oats instance stop <instance>` |
485
- | start or restart an agent | `oats session start --home <home>` |
486
- | retire an agent | `oats retire <instance>` |
700
+ | start an agent with another harness or model | `oats session start --home <home>` with its options |
487
701
  | see souls, spawn an agent | `oats souls`, `oats spawn <soul>` |
488
702
  | see capabilities | `oats capabilities` |
489
703
  | add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
@@ -507,7 +721,8 @@ version:
507
721
  names the machine (`on garnet`) and carries the time.
508
722
  - Souls and Capabilities, when they come, are this machine's.
509
723
  - There is no sorting and no mouse, and a deployment's heading cannot be
510
- folded.
724
+ folded. An open terminal has no scrollback but the viewer's own.
725
+ - One terminal is open at a time; tabs of several come in a later version.
511
726
  - With an OATS older than 0.52.0, after an interrupted stop the instance can
512
727
  be started and then cannot be stopped while `.oats-stop-pending.json` exists
513
728
  in its home.
@@ -525,6 +740,17 @@ This is the complete list. On start, in this order:
525
740
  On the way out, the reverse: bracketed paste off, autowrap on, the style
526
741
  reset (`CSI 0m`), the cursor shown, the alternate screen left, raw mode off.
527
742
 
743
+ While it draws:
744
+
745
+ - **every frame is one synchronized update**: it begins with
746
+ `CSI ?2026h` and ends with `CSI ?2026l`, so a terminal that knows the
747
+ mode shows the frame whole and one that does not ignores it. The mode is
748
+ set and reset inside each frame and is never left on; a frame with
749
+ nothing to change writes nothing;
750
+ - **while an agent's terminal has the focus the cursor is shown**
751
+ (`CSI ?25h`) where the agent's is, when the agent shows one, and hidden
752
+ again (`CSI ?25l`) when the focus leaves it.
753
+
528
754
  Two of these have a reason worth stating:
529
755
 
530
756
  - **Autowrap is off** so that no row can wrap when your terminal and the
@@ -551,15 +777,11 @@ It stops the whole foreground process group, as a `Ctrl+Z` does for any
551
777
  other program, so `oats tui` started through a wrapper (`sh -c`, `npx`)
552
778
  suspends as one job.
553
779
 
554
- **While an agent has the terminal** `oats tui` has put the terminal back in
555
- full, as for a suspend, and draws nothing. The viewer is OATS's own: it sets
556
- what it needs, the mouse for scrolling among it, and puts that back when it
557
- ends. Then `oats tui` sets its modes again. A SIGQUIT does not end
558
- `oats tui` while an agent has the terminal (a second `Ctrl+\`, pressed as the
559
- viewer leaves, is that signal). SIGINT, SIGTERM and SIGHUP end the viewer
560
- first and then `oats tui`, with the status of the table above. A viewer
561
- that has not ended 3 seconds after it was asked, or at a second signal, is
562
- left as it is, and `oats tui` ends without it.
780
+ **While an agent's terminal is open** the terminal stays `oats tui`'s: the
781
+ viewer draws into the private server's pane, never into your terminal, and
782
+ `oats tui` draws what that pane shows. Every way out in the table above ends
783
+ the private server and with it the viewer, with that status. A suspend
784
+ leaves the server and its viewer running; `fg` draws the terminal afresh.
563
785
 
564
786
  `Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
565
787
  a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
@@ -572,20 +794,28 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
572
794
  stayed in the alternate screen until `tput rmcup`. Nothing else is left in
573
795
  tmux: `oats tui` creates no session, window, option or key binding.
574
796
  Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
575
- read that was in flight runs to its own end. After a SIGKILL while an agent
576
- has the terminal, the viewer still has it: leave it with the key and you are
577
- in your shell.
797
+ read that was in flight runs to its own end. An open terminal's private
798
+ server is ended by its keeper as soon as `oats tui` is gone, so the viewer's
799
+ terminal hangs up and the viewer removes its own session. A stopped `oats tui`
800
+ (`Ctrl+Z`, SIGSTOP) still holds the keeper's FIFO, so its server is left
801
+ alone. The next run removes the directory that is left, with its `tmux`,
802
+ `alive`, `capture` and `owner.json`.
578
803
 
579
804
  ## What it never does
580
805
 
581
806
  - It switches on **no mouse reporting, no focus reporting, no keyboard
582
- protocol, no keypad or cursor-key mode and no synchronized output**.
807
+ protocol and no keypad or cursor-key mode**, and leaves no synchronized
808
+ update on between frames.
583
809
  - It writes **no window title, no clipboard sequence, no bell**, and no query
584
810
  that expects the terminal to reply.
585
- - It uses **only your terminal's own sixteen colours** and bold, dim,
586
- underline and reverse: no 256-colour or RGB value and no background fill,
587
- so your theme stays the theme. With `NO_COLOR` set and not empty it uses no
588
- colour at all. Nothing is told by colour alone.
811
+ - **Its own words and marks use only your terminal's own sixteen colours**
812
+ and bold, dim, underline and reverse: no 256-colour or RGB value and no
813
+ background fill, so your theme stays the theme. An open terminal shows
814
+ the agent's screen in the agent's own colours (256-colour and RGB
815
+ included) and attributes: those are the agent's. With `NO_COLOR` set and
816
+ not empty it uses no colour at all, the agent's included; the agent's
817
+ bold, underline, reverse and the like stay. Nothing is told by colour
818
+ alone.
589
819
  - It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
590
820
  `LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
591
821
  no emoji. When the locale is not UTF-8, a character outside ASCII in text
@@ -601,17 +831,25 @@ in your shell.
601
831
  shared home's (`packages/client/`), and the TUI writes none of its own
602
832
  for a speaker. They never stand before a withheld text: a reason that is
603
833
  withheld is `[withheld]` alone.
604
- - It changes nothing in tmux: no option, key binding, server, session,
605
- window or pane. Its probe only lists panes. An agent's terminal is opened
606
- by `oats session attach`, which makes its own viewer session on the
607
- agents' tmux server and removes it; `oats tui` builds no viewer and runs
608
- no tmux command for it.
609
- - It starts no daemon, opens no socket and writes no file. The processes it
610
- starts are the reads above and, when you open an agent, the viewer; none
611
- outlives it on every way out a process can handle, except a viewer that
612
- does not end when asked (see
613
- [above](#what-it-changes-in-your-terminal-and-restores)); after SIGKILL a
614
- read in flight runs to its own end, and a viewer stays until you leave it.
834
+ - It changes nothing in your tmux or the agents': no option, key binding,
835
+ server, session, window or pane. Its probe only lists panes. An agent's
836
+ own session is started, ended or restarted only by the kernel's commands
837
+ of an act you confirmed
838
+ ([above](#stopping-starting-restarting-and-retiring)), and an agent's
839
+ terminal is opened by `oats session attach`, which makes its own viewer
840
+ session on the agents' tmux server and removes it. The one tmux server
841
+ `oats tui` runs is its own private one
842
+ ([above](#open-an-agents-terminal)), and it never looks at another's
843
+ socket but to ask whether a dead run's still answers.
844
+ - It starts no daemon, and writes no file but the output of a change and
845
+ its private server's own, in its own directory
846
+ ([above](#what-it-reads-and-what-it-runs)). The processes it starts are
847
+ the reads above, when you open an agent its private tmux server and the
848
+ viewer in it, and the acts you confirm. No read, server or viewer
849
+ outlives it on every way out a process can handle; after SIGKILL a read
850
+ in flight runs to its own end, and the private server and its viewer end
851
+ by themselves. An act you confirmed is never ended by `oats tui`: it runs
852
+ to its own end.
615
853
 
616
854
  ## Errors
617
855
 
@@ -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.1 # bare version → resolves through the official catalog
58
- oats.okf: v5.1.0
57
+ oats.framework: v1.12.0 # 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