@awebai/oats 0.58.0 → 0.60.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 (63) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +80 -8
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +18 -2
  5. package/docs/implementation.md +3 -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/release-notes/v0.60.0.md +104 -0
  12. package/docs/servers.md +4 -1
  13. package/docs/souls-and-instances.md +21 -0
  14. package/docs/tui.md +753 -119
  15. package/docs/workspaces.md +2 -2
  16. package/lib/core.mjs +258 -57
  17. package/lib/read-ahead-worker.mjs +119 -0
  18. package/lib/read-ahead.mjs +115 -0
  19. package/lib/retire-state.mjs +33 -0
  20. package/lib/servers.mjs +9 -1
  21. package/lib/session-input.mjs +53 -26
  22. package/package-catalog.json +3 -3
  23. package/package.json +1 -1
  24. package/packages/client/capability-catalog.mjs +93 -0
  25. package/packages/client/capability-facts.mjs +59 -0
  26. package/packages/client/capability-rows.mjs +121 -0
  27. package/packages/client/catalog-messages.mjs +12 -0
  28. package/packages/client/cli-locator.mjs +2 -2
  29. package/packages/client/deployment-data.mjs +4 -0
  30. package/packages/client/deployment-panel.mjs +3 -0
  31. package/packages/client/instance-acts.mjs +23 -8
  32. package/packages/client/instance-presentation.mjs +3 -2
  33. package/packages/client/instance-tree.mjs +84 -39
  34. package/packages/client/lifecycle-confirmation.mjs +9 -3
  35. package/packages/client/remote-roster.mjs +4 -1
  36. package/packages/client/retire-in-flight.mjs +65 -0
  37. package/packages/client/retire-state.mjs +30 -0
  38. package/packages/client/soul-catalog.mjs +8 -0
  39. package/packages/client/soul-facts.mjs +7 -0
  40. package/packages/client/spawn-apply.mjs +13 -4
  41. package/packages/client/spawn-messages.mjs +8 -0
  42. package/packages/client/subsequence-score.mjs +15 -0
  43. package/packages/tui/README.md +23 -10
  44. package/packages/tui/lib/actions.mjs +63 -5
  45. package/packages/tui/lib/client.mjs +17 -1
  46. package/packages/tui/lib/config.mjs +7 -2
  47. package/packages/tui/lib/main.mjs +364 -82
  48. package/packages/tui/lib/model.mjs +614 -57
  49. package/packages/tui/lib/panel.mjs +436 -125
  50. package/packages/tui/lib/read.mjs +52 -26
  51. package/packages/tui/lib/store.mjs +1025 -65
  52. package/packages/tui/lib/term/keys.mjs +9 -2
  53. package/packages/tui/lib/term/text.mjs +4 -0
  54. package/packages/tui/lib/term/through.mjs +12 -1
  55. package/packages/tui/lib/views/capabilities.mjs +239 -0
  56. package/packages/tui/lib/views/frame.mjs +433 -99
  57. package/packages/tui/lib/views/help.mjs +61 -15
  58. package/packages/tui/lib/views/instances.mjs +43 -25
  59. package/packages/tui/lib/views/palette.mjs +66 -0
  60. package/packages/tui/lib/views/souls.mjs +270 -0
  61. package/packages/tui/lib/views/spawn.mjs +301 -0
  62. package/packages/tui/lib/views/split.mjs +29 -0
  63. package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/tui.md CHANGED
@@ -12,12 +12,14 @@ 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, 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
15
+ other machines registered on this machine, in one list, opens agents'
16
+ terminals as tabs, in one group or two ([Splits](#splits)), spawns an agent
17
+ on this machine, and stops, starts, restarts
18
+ and retires an agent after a confirmation.** The registered machines are
19
+ the ones `oats server list` names. It follows the instances as they
20
+ start, stop and wait for you. It cannot spawn an agent on another machine
21
+ or with another harness, model or task, start one with another harness or
22
+ model, or add, check or remove a machine: [what it does not do
21
23
  yet](#what-this-version-does-not-do) names the `oats` command for each.
22
24
  - **Its screens and its configuration file may change without notice** while
23
25
  it is a preview.
@@ -77,24 +79,24 @@ runs.
77
79
  ## What it shows
78
80
 
79
81
  ```
80
- oats acme-platform +1 machine 4 running 1 needs input 2 stopped
81
- Instances Souls Capabilities read 14:03:27
82
- ──────────────────────────────────────────────┬─────────────────────────────────────────────────
83
- This machine │ api-lead
84
- ▾ ● backend-lead claude │ soul tech-lead
85
- ● backend-dev-auth claude !│ machine garnet
86
- │ state running
87
- ○ docs-writer stopped │ harness claude, claude-opus-5-5 (soul)
88
- garnet read 14:03:21 │ work worktree, agents/api-lead
89
- >▾ ● api-lead claude │ home …agents/tech-lead/instances/api-lead
90
- ● api-dev-export claude │
91
- │
92
- ○ reviewer-api stopped │
93
- ──────────────────────────────────────────────┴─────────────────────────────────────────────────
94
- / filter Tab detail r refresh w workspaces 1-3 views ? help q quit
82
+ fixture 3 stopped
83
+ Instances Souls Capabilities read 20:02:02
84
+ ──────────────────────────────────────┬─────────────────────────────────────────
85
+ > ■ dev ·2 │ dev
86
+ ■ reviewer ·1 │ dev fixture soul.
87
+ │ from ws
88
+ │ works works in directory
89
+ │ harness
90
+ │ Harness Pi
91
+ │ Model Pi's default model
92
+ │ Chosen by no preference set: the
93
+ │ host default
94
+ │ instances here
95
+ │ ○ alpha ○ beta
96
+ │ i shows them in the Instances view.
95
97
  ```
96
98
 
97
- - **The header** has the workspace's name, then what the view holds of
99
+ - **The header** starts with the workspace's name, then what the view holds of
98
100
  other machines, then the counts. Beside a deployment of this machine the
99
101
  other machines are counted: `+1 machine`, `+2 machines`. A view that holds
100
102
  no deployment of this machine names its one machine, `on garnet`, or
@@ -103,19 +105,34 @@ runs.
103
105
  stopped, state unknown, and rows the kernel reported that were withheld (a
104
106
  home outside its soul's directory, or one reported twice). A count of zero
105
107
  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.
108
+ Capabilities`, the open one drawn in reverse video. `1`, `2` and `3`
109
+ open them in the list, and [the leader](#the-leader) then `1`, `2` or `3`
110
+ from anywhere; the leader's hint, [the palette](#the-palette) and the
111
+ help name those keys. [The Souls view](#the-souls-view) lists the open
112
+ workspace's souls, and [the Capabilities view](#the-capabilities-view)
113
+ its capabilities. On the right is the time of the read of this machine
114
+ that the screen shows: it moves with every read.
115
+ - **The footer** is one row of keys from the first column, with no rule
116
+ above it. It names `C-\ commands` first, in every focus: the leader,
117
+ which reaches every action. Then come the actions that apply now, as many
118
+ as fit, `help` and `quit` last; a narrow footer gives the others up first.
119
+ While the leader waits for its key the row is the leader's hint.
113
120
  - **The list** is the roster the Desktop draws: the same groups in the same
114
- order, from the same code. An instance that others were spawned from
115
- comes first, and the ones below it are indented under it; instances
116
- related to no other follow, after an empty row.
117
- - **Each row** has a mark for its state, the name, then the harness when it
118
- runs, else its state in a word, then `!` when it needs input.
121
+ order, from the same code. It is in name order, by each group's top
122
+ instance, so starting or stopping an instance moves nothing. An instance
123
+ that others were spawned from has them indented under it, and keeps its
124
+ place when it gains or loses one. An empty row stands between each run
125
+ of instances related to no other and the group before or after it. The
126
+ indent alone says which instance is under which: no mark is drawn for
127
+ it. A row whose instances are folded away (`h`) says how many after its
128
+ name: `+1`.
129
+ - **Each row** is the mark of its state and the name, then `!` at the
130
+ right when it needs input. The harness and the state in words are in
131
+ the detail. A row has a word, dim, only where its mark cannot say it: the
132
+ state of a home a spawn or a retire holds (`Retire didn't finish`), or
133
+ the shared words for why an instance cannot be reached or opened:
134
+ `gone from garnet`, `garnet not reached`, `not reachable on garnet`,
135
+ `Herdr no longer supported`, `state unknown`.
119
136
  - **The detail** shows the selected instance: its soul, its state, and
120
137
  under it the reason when there is one, after the words that say who gave
121
138
  it: `OATS says:` for a kernel (this machine's, or the instance's
@@ -132,8 +149,8 @@ runs.
132
149
  columns up it stands beside the list; on a narrower terminal `Tab` opens
133
150
  it as a page.
134
151
  - **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).
152
+ beside the list, where the detail was, as a tab: see
153
+ [Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
137
154
 
138
155
  **A view of more than one deployment** (this machine and another, or two
139
156
  deployments on one machine) is one list, grouped as the Desktop groups it:
@@ -143,14 +160,22 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
143
160
  with the end of the deployment's path when one machine holds two of the
144
161
  view. A heading cannot be selected or folded: the movement keys pass over
145
162
  it. A view of one deployment has no heading.
146
- - **A machine that answered carries the time its rows were read** on its
147
- heading, at the right: `read 14:03:21`. A row of another machine shows
148
- what its host reported at that time.
163
+ - **A machine's heading is its name.** When its rows were read at another
164
+ time than the one in the header, that time stands at the right of the
165
+ heading: `read 14:03:21`. A row of another machine shows what its host
166
+ reported at that time.
149
167
  - **A deployment that is not live carries its state and a short reason**
150
168
  on its heading, and no time: `garnet remembered Not reached`. The rows
151
169
  a machine last reported are kept when it is not reached, and each of them
152
- reads `unknown`, with the `?` mark, in the list and in the detail:
153
- nothing reads as stopped, or as running, that is only not reached.
170
+ reads `garnet not reached`, with the `?` mark, in the list and in the
171
+ detail: nothing reads as stopped, or as running, that is only not
172
+ reached.
173
+ - **An instance gone from its machine** is one this computer keeps a route
174
+ to, which its machine no longer has. It reads `gone from garnet`, with
175
+ the `?` mark, in the list and in the detail. The detail says so in a
176
+ sentence, with the command that removes it from this computer:
177
+ `oats server forget <id> --instance <name>`. It cannot be opened,
178
+ and `Enter` says why in the same sentence.
154
179
  - **A deployment that is not live and has no rows** is named after the
155
180
  others: the machine, the deployment's path, its state and the short
156
181
  reason on one row, and the whole reason on the rows under it.
@@ -164,7 +189,7 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
164
189
  follows it.
165
190
 
166
191
  **A view that holds no deployment of this machine** says so in its header:
167
- `oats other on garnet` for one machine, `2 machines` after the name for
192
+ `other on garnet` for one machine, `2 machines` after the name for
168
193
  two or more. The time in the header is then the time the machines' rows
169
194
  were read. A view of one machine has no heading, so its state, when it is
170
195
  not live, is said above the list with the reason, as for a deployment of
@@ -185,8 +210,8 @@ in its workspace for the rest of the run, also while it is not reached.
185
210
  | `○` | `-` | stopped |
186
211
  | `◌` | `~` | stopped, with a shell left in its terminal |
187
212
  | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
188
- | `◆` | `#` | held by a spawn or a retire that is not finished |
189
- | `▾` `▸` | `v` `>` | has instances below it: shown, folded away |
213
+ | `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
214
+ | `+n` | `+n` | after a name: n instances folded away below it |
190
215
  | `!` | `!` | needs input |
191
216
  | `!N` | `!N` | N instances folded away below it need input |
192
217
  | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
@@ -194,6 +219,25 @@ in its workspace for the rest of the run, also while it is not reached.
194
219
 
195
220
  Every state has a mark of its own shape, so nothing is told by colour alone.
196
221
 
222
+ <a id="held-rows"></a>**A held row** says in its word what holds it, by the
223
+ Desktop's rule:
224
+
225
+ - `Setting up worktree…`: a spawn is running its worktree setup.
226
+ - `Spawn didn't finish`: a spawn left the home for a retire to clean up.
227
+ - `Retiring…`: a retire is in progress, never shown as a failure. OATS
228
+ reports it running, or cannot tell whether the process holding it still
229
+ runs; or the instance's OATS does not report a retire's state yet and
230
+ the instance has a retire pending; or this `oats tui` sent the retire and
231
+ has not read the list since its answer. A retire the kernel refused, or
232
+ whose plan had changed, runs nothing: the row reads as the list says at
233
+ once.
234
+ - `Retire failed`: a self-retire's completion recorded an error. The detail
235
+ gives its reason after `OATS says:`, in OATS's words with its code,
236
+ through the display filter. With a code and no message, the reason is
237
+ its code after `OATS says:`, the same way.
238
+ - `Retire didn't finish`: a scheduled completion is gone and left no
239
+ outcome.
240
+
197
241
  **When a read fails,** what the view then shows is one rule, shared with the
198
242
  Desktop, and `oats tui` decides none of it. Depending on the failure the
199
243
  last rows stay as they were; or they stay and are marked `stale`, with the
@@ -215,63 +259,75 @@ on whether that read has succeeded before in this run:
215
259
  | The read failed | The view shows |
216
260
  |---|---|
217
261
  | before it ever succeeded in this run | after the list and an empty row, the row `Other machines were not read.` and under it the failure: `Remote roster unavailable: <message>`, or the kernel's own message when it answered with an error |
218
- | after it succeeded once | each machine keeps its place and its heading, with its state and a short reason in place of the time; its rows are kept and read `unknown` |
262
+ | after it succeeded once | each machine keeps its place and its heading, with its state and a short reason in place of the time; its rows are kept and read `<machine> not reached` |
219
263
 
220
264
  The next read that succeeds shows the machines as they then report.
221
265
 
222
266
  Names are cut by terminal cells with `…` (`...` in ASCII) when they do not
223
- fit; the detail shows them whole.
267
+ fit; the detail shows them whole. The TUI's own words end the same way:
268
+ **Retiring…** reads `Retiring...` in ASCII.
224
269
 
225
270
  ## Open an agent's terminal
226
271
 
227
272
  ```
228
- oats acme-platform 2 running
273
+ acme-platform 2 running
229
274
  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
275
+ ──────────────────────────────┬─────────────────────────────────────────────────
276
+ > ● backend-lead │ backend-lead
277
+ ● docs-writer │$ make docs
278
+ │Building the reference...
279
+ │
280
+ │
281
+ C-\ commands C-\ C-\ back to the list
237
282
  ```
238
283
 
239
284
  - **`Enter` on an instance that runs** opens its terminal on the right of
240
285
  the body, where the detail was, with the list on the left. Its top row
241
286
  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.
287
+ is the agent's screen, as the agent draws it, in its own colours. While a
288
+ terminal is open the list keeps 30 columns at most, also while the
289
+ detail stands in the terminal's place, and a name longer than its row is
290
+ cut with `…` (`...` in ASCII).
243
291
  - **The terminal has the focus.** What you type, what you paste and every
244
292
  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.
293
+ among them, but for **[the leader](#the-leader)** (`Ctrl+\` unless
294
+ [`tui.json`](#change-the-keys-tuijson) names another), the one key the
295
+ TUI takes from the agent. The leader twice gives the focus to the list;
296
+ the leader then another key does what that key does from anywhere. While
297
+ the terminal has the focus the footer names it, and the leader twice:
298
+ `C-\ commands C-\ C-\ back to the list`. A leader inside a bracketed
299
+ paste is pasted, not taken.
250
300
  - **With the list focused** the terminal stays open, and the agent's screen
251
301
  is still drawn as it changes. The footer names the keys for it:
252
302
  `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.
303
+ - `Enter` on the shown terminal's row gives it the focus again.
254
304
  - `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.
305
+ stay, the list is hidden. The leader twice brings the list back beside
306
+ it, and the leader then `z` zooms it out and in without leaving it.
307
+ - `c` closes it: the agent keeps running. The tab beside it is shown;
308
+ with no other tab the right side is the detail again.
258
309
  - `Tab` shows the detail in its place until `Tab` or `Esc`. Nothing of
259
310
  the terminal is drawn meanwhile, and its screen is read afresh when it
260
311
  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.
312
+ - **Up to four terminals are open at a time, each a tab.** `Enter` on
313
+ another instance that runs opens its terminal in a new tab, and the
314
+ others stay open: see [Tabs](#tabs).
263
315
  - **Under 80 columns** the terminal is always shown with the whole body
264
316
  when it has the focus. With the list focused the list is shown alone; the
265
317
  terminal stays open, unseen, and `Enter focus terminal` in the footer
266
318
  shows it again. Beside the list the terminal is never narrower than 40
267
319
  columns.
268
- - **A terminal also closes by itself** when its viewer ends: the agent's
320
+ - **A terminal also closes by itself** when its viewer ends, shown or
321
+ hidden ([which tab is shown then](#tabs)): the agent's
269
322
  window ended, its session went away, or the link to its machine dropped.
270
323
  It closes within a second of that (tmux tells `oats tui` of a viewer's
271
324
  end once a second), or a second more when tmux took a moment more to
272
325
  have the viewer's exit status: once tmux has reported the viewer ended,
273
326
  `oats tui` waits ten seconds at most for that status, and closes the
274
- terminal without it when it has not come. The instances are then read again at once, and one line above the panes
327
+ terminal without it when it has not come. A tmux built with libutempter
328
+ (Ubuntu's and Debian's are) can lose that status: while it waits,
329
+ `oats tui` has tmux look for it again once a second, so the terminal
330
+ still closes within a second or two with the line its status calls for. The instances are then read again at once, and one line above the panes
275
331
  says what happened: that it could not be opened, that the connection to
276
332
  its machine ended, or that the viewer ended without saying why. What the
277
333
  viewer printed on its error output stands under that line in quotation
@@ -281,7 +337,7 @@ fit; the detail shows them whole.
281
337
  `Enter` opens it.
282
338
  - **`Enter` on an instance that cannot be opened** opens nothing and says
283
339
  why: it does not run, whether it runs is not known, or the detail's
284
- reason holds it. An agent on another machine is asked first whether it
340
+ reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
285
341
  can be opened (`Esc` gives that up); a machine whose OATS cannot open its
286
342
  sessions is said then.
287
343
  - **No scrollback but the viewer's own, and no mouse.** The panel shows
@@ -297,14 +353,335 @@ fit; the detail shows them whole.
297
353
  agent opens in the TUI's panel, and `oats tui` makes no window and no
298
354
  split in your tmux.
299
355
 
356
+ ## Tabs
357
+
358
+ ```
359
+ acme-platform 3 running
360
+ Instances Souls Capabilities read 14:03:27
361
+ ──────────────────────────────┬─────────────────────────────────────────────────
362
+ > ● backend-lead │ backend-lead docs-writer• qa-runner
363
+ ● docs-writer │$ make test
364
+ ● qa-runner │ok 41 of 41
365
+ │
366
+ │
367
+ C-\ commands C-\ C-\ back to the list
368
+ ```
369
+
370
+ Each terminal open in the panel is a tab, and the panel holds up to four.
371
+
372
+ - **The tab strip** is the panel's top row: each tab's agent, in the order
373
+ the tabs were opened. With one tab the row reads as
374
+ [above](#open-an-agents-terminal), the agent's name alone.
375
+ - **The shown tab** is the one whose screen the panel draws. Its name is
376
+ in reverse video while the terminal has the focus, and bold otherwise.
377
+ - **The other tabs are hidden**, their names plain. A hidden tab whose
378
+ agent wrote since it was last shown has `•` after its name (`*` in
379
+ ASCII); the mark goes when the tab is shown. A hidden tab's screen is
380
+ not read: only that its agent wrote.
381
+ - **An agent of another machine** reads `<name>`, then a dim
382
+ `on <machine>`.
383
+ - **A strip longer than its row is cut** in this order: the hidden tabs'
384
+ `on <machine>`, then the hidden tabs' names, each to an equal share of
385
+ what the shown tab leaves, with `…` (`...` in ASCII), then the shown
386
+ tab's `on <machine>`; then the hidden tabs farthest from the shown one
387
+ are left out of the row (they stay open). The shown tab's name stays
388
+ whole while the row can hold it.
389
+ - **Opening.** `Enter` on a row, an instance in
390
+ [the palette](#the-palette), the leader then `Up` or `Down`, and a
391
+ [spawn](#spawning-an-agent)'s new agent open a terminal the same way:
392
+ - an instance that has a tab: that tab is shown, with the focus in it;
393
+ - any other: a new tab, after the shown one, is shown with the focus in
394
+ it. The other tabs stay open.
395
+ - **One open at a time.** While a tab is starting, or an agent of another
396
+ machine is asked whether it can be opened, another open does nothing,
397
+ and neither does a key that shows another tab.
398
+ - **At four tabs nothing closes by itself.** The open does nothing, and
399
+ the line above the panes says `4 terminals are open; close one with C-\ w.`
400
+ (with your leader, when [`tui.json`](#change-the-keys-tuijson) names
401
+ another). A tab still starting, and an agent of another machine while
402
+ it is asked, hold a place among the four. An instance that cannot be
403
+ opened says why, as it does with no tab open.
404
+ - **Switching.** `[` and `]` in the Instances view, from the list or the
405
+ detail, show the tab before or after the shown one; the footer names them
406
+ (`[/] tab`) after the terminal's keys while two tabs or more are open, and
407
+ gives them up after the acts, `workspaces`, `refresh` and `close`, before
408
+ `detail`. The leader then
409
+ `Left` or `Right` does the same from any focus, and from another view
410
+ goes to the Instances view first.
411
+ - The strip does not wrap: on the first tab `[` does nothing, and on the
412
+ last `]`; the leader then `Left` or `Right` there leaves even the focus
413
+ where it was.
414
+ - The focus does not move: in the terminal it stays in the terminal,
415
+ zoomed or not, and in the list it stays in the list.
416
+ - **Showing a tab selects its instance's row** in the list and brings it
417
+ into view: a filter that hides the row is cleared, and an instance
418
+ folded over it is opened.
419
+ - **The palette** lists the instances most recently opened or shown first,
420
+ as the Desktop's does. When the first of them is the shown tab's, the
421
+ palette opens with the second selected, so the palette then `Enter` goes
422
+ back to the terminal shown before it.
423
+ - **Closing.** The leader then `w`, or `c` in the Instances view, closes the
424
+ shown tab: its agent keeps running. The tab to its right is shown, else
425
+ the one to its left.
426
+ - After the leader then `w` from a terminal, the tab shown next has the
427
+ focus, and is zoomed when the one closed was. After `c`, or the leader
428
+ then `w` from anywhere else, the terminal does not take the focus.
429
+ - Closing the last tab closes the panel: the right side is the detail
430
+ again, and the list has the focus.
431
+ - **A tab that closes by itself**, when its viewer ends, says so on the line
432
+ above the panes in the words [above](#open-an-agents-terminal), for that
433
+ tab's agent (no line when it ended cleanly).
434
+ - The shown tab: the tab to its right is shown, else the one to its left,
435
+ and the list takes the focus.
436
+ - A hidden tab: the shown tab and the focus stay as they were.
437
+ - **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole body.
438
+ The strip stays its top row, and the other tabs stay open.
439
+ - **The tabs are the open workspace's.** Opening another workspace in
440
+ [the switcher](#the-switcher) closes them all, and so does the open
441
+ workspace no longer being listed; their agents keep running. Coming back
442
+ opens none of them again.
443
+
444
+ ## Splits
445
+
446
+ ```
447
+ acme-platform 3 running
448
+ Instances Souls Capabilities read 14:03:27
449
+ ──────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────
450
+ ● backend-lead │ backend-lead docs-writer │ qa-runner
451
+ ● docs-writer │$ git log --oneline -2 │$ make test
452
+ > ● qa-runner │4be1c0d Fix the reader │ok 41 of 41
453
+ │9a03e7f Add the roster │
454
+ │ │
455
+ C-\ commands C-\ C-\ back to the list
456
+ ```
457
+
458
+ The panel can be split in two **groups**, side by side or one above the
459
+ other. Each group is a panel of [tabs](#tabs) of its own: a strip, a shown
460
+ tab and the marks of its hidden ones.
461
+
462
+ - **Splitting.** The leader then `|` splits the panel side by side, and the
463
+ leader then `-` one above the other; in the Instances view `|` and `-`
464
+ do the same without the leader. The tabs open stay in the first group
465
+ (left, or top). The second group starts empty and is the focused group.
466
+ - A split needs a tab open, and none starting.
467
+ - **There are at most two groups.** With two, the split keys do nothing,
468
+ and the line above the panes says `The panel has two groups already.`
469
+ - **Each group needs 40 columns side by side, and 8 rows one above the
470
+ other**, its strip counted. The panel beside the list then needs 81
471
+ columns (a terminal of 112), or 17 rows. A split that would leave a
472
+ group smaller does nothing, and the line says so:
473
+ `No room to split side by side: each group needs 40 columns.` or
474
+ `No room to split one above the other: each group needs 8 rows.`
475
+ - **What is drawn.** A rule separates the groups. Both groups' shown tabs
476
+ are drawn as their agents write; hidden tabs only set their marks.
477
+ - The focused group's strip is drawn as with one group: its shown tab in
478
+ reverse while its terminal has the focus, bold otherwise. The other
479
+ group's shown tab is bold, never in reverse, so one terminal at a time
480
+ reads as the one you type into.
481
+ - **An empty group** says `Enter on an agent opens it here`, in reverse
482
+ while it is the focused group, and the leader's keys to go to the other
483
+ group or to close it. It never takes keys: while it is the focused
484
+ group, the keys are the list's.
485
+ - A resize gives each group its share and reaches every tab's window in
486
+ it. **When the terminal becomes too small for both groups,** the split
487
+ stays and the focused group is drawn alone; the other group's shown tab
488
+ is not drawn, only marked, until there is room again.
489
+ - **Under 80 columns** the terminal's focus gives the whole body to both
490
+ groups, and the list's focus shows the list alone, as with one group.
491
+ - **Zoom** (`z`, or the leader then `z`) gives the focused group's shown
492
+ terminal the whole body, and the same key brings the split back. With
493
+ the empty group focused it does nothing.
494
+ - **Opening.** `Enter`, the palette, the leader then `Up`/`Down` and a
495
+ spawn open as with one group:
496
+ - an instance that has a tab, in either group: that tab is shown in its
497
+ group, and that group takes the focus;
498
+ - any other: a new tab in the focused group, after its shown tab, or as
499
+ the first tab of the empty group.
500
+ - **The four tabs are counted across both groups.** At four, the line
501
+ says `4 terminals are open; close one with C-\ w.` as with one group.
502
+ - **Moving between the groups.** The leader then `Tab` from a terminal goes
503
+ to the other group's shown terminal, or to the other group when it is
504
+ empty. From the list it goes to the focused group's terminal, or, with
505
+ the focused group empty, to the other group's. Showing a tab selects its
506
+ row in the list. `[`, `]` and the leader then `Left`/`Right` show the tab
507
+ before or after within the focused group only.
508
+ - **Moving a tab.** The leader then `m` moves the focused group's shown tab
509
+ to the other group, after that group's shown tab, and shows it there with
510
+ the focus. The group it leaves shows its neighbour, or stays, empty.
511
+ - **Closing.** Closing a tab (`c`, or the leader then `w`) shows its
512
+ neighbour in its group: the tab to its right, else the one to its left.
513
+ - **A group's last tab closed removes the group:** the other takes the
514
+ whole panel and the focus. When the other group was empty, the panel
515
+ closes, as when the last tab of the only group closes.
516
+ - The leader then `x` closes the focused group while it is empty: the
517
+ other takes the whole panel and is the focused group, and the keys stay
518
+ the list's. With tabs in the group, `x` does nothing.
519
+ - **A tab that closes by itself** shows its neighbour in its group. A
520
+ group's last tab closing by itself removes the group, and the list
521
+ takes the focus; when what is left is an empty group, the panel closes.
522
+ - **The palette** lists `Split right` and `Split down` while there is one
523
+ group, then `Move tab to the other group` while the focused group shows a
524
+ tab, or `Close the empty group` while it is empty.
525
+ - **Another workspace** closes every tab and the split.
526
+ - The split cannot be resized or nested, and is not kept from one run to
527
+ the next.
528
+
529
+ ## The Souls view
530
+
531
+ `2`, or the leader then `2`, shows the souls of the open workspace: the
532
+ ones `oats spawn` can make an instance of here, as the OATS Desktop lists
533
+ them, from the same code.
534
+
535
+ ```
536
+ acme-platform 2 running 1 stopped
537
+ Instances Souls Capabilities read 14:03:27
538
+ ──────────────────────────────────────┬─────────────────────────────────────────
539
+ > ■ dev ·2 │ dev
540
+ ■ ops ! │ Builds and ships the platform.
541
+ ■ reviewer ·1 │
542
+ │ from oats-core
543
+ │ works works in its own worktree
544
+ ```
545
+
546
+ - **A row** is the soul's colour mark (`■`, `#` in ASCII; its colour is the
547
+ Desktop's for that soul, uncoloured when it has none), its name, and a
548
+ count of its instances on this machine, `·2`. A soul a spawn here would
549
+ refuse is drawn dim, with `!` after its name. The list keys move, and `/`
550
+ filters by name, description or where the soul comes from.
551
+ - **The detail** beside it, top to bottom: the name and the description;
552
+ where it comes from (its member, or its package and version); where it
553
+ works; why a spawn here would be refused, when it would be; the harness
554
+ and model a spawn would use and where that choice is set (a launch
555
+ problem as the kernel reports it); its teams, the default first; its
556
+ capabilities; and its instances on this machine, eight at most and then
557
+ `+n`. `Enter` gives the detail the focus (under 80 columns it takes the
558
+ list's place), and the movement keys then scroll it.
559
+ - **`i`**, or `Enter` in the detail, shows that soul's instances in the
560
+ Instances view: an exact filter, shown where a kept filter stands in
561
+ the footer, `soul dev`.
562
+ An instance of another soul whose name holds `dev` is not listed. `Esc`
563
+ clears it, and `/` replaces it with a text filter.
564
+ - **`r`** reads the souls again; while a read is under way it starts
565
+ nothing. `Esc` closes the detail, then clears a kept filter, then goes
566
+ back to the instances.
567
+ - **When it reads:** the first time the view is shown, never before: a run
568
+ that never shows it, nor [the Capabilities
569
+ view](#the-capabilities-view) or [the spawn prompt](#spawning-an-agent),
570
+ which need the souls too, never runs `oats souls`. After that, a read of the
571
+ workspace reads the souls again only when the workspace changed (its
572
+ commit, a member's, its externals), and `r` does. While the first read is
573
+ under way the view says `Reading souls…`. A read that fails says why,
574
+ with `r` to try again; one that fails after a good one keeps the souls it
575
+ had, under a heading that says it failed and when the souls were read;
576
+ the selected soul's detail says why in full, under its name.
577
+ - **What is kept:** the selected soul and the filter, when the view is left
578
+ and shown again, for the run.
579
+ - **Only this machine's:** the view lists the souls of a workspace of this
580
+ machine. With none open it says so.
581
+
582
+ `n` or `N` spawns an agent of the selected soul: [Spawning an
583
+ agent](#spawning-an-agent).
584
+
585
+ ## The Capabilities view
586
+
587
+ `3`, or the leader then `3`, shows the capabilities of the open workspace:
588
+ the ones its repositories and its packages offer, as the OATS Desktop lists
589
+ them, from the same code.
590
+
591
+ ```
592
+ acme-platform 3 running
593
+ Instances Souls Capabilities read 14:03:27
594
+ ──────────────────────────────────────┬─────────────────────────────────────────
595
+ Workspace owned │ aweb Messaging
596
+ oats · member repo · host │ Messaging over aweb, mail and chat,
597
+ > aweb Messaging │ for every instance of the workspace.
598
+ tools · member repo │
599
+ notes │ Comes from
600
+ Packages │ Repository oats
601
+ oats-okf · package · v1.2.0 │ Latest bbbbbbb
602
+ okf-knowledge Knowledge │ Path capabilities/aweb
603
+ │
604
+ │ Provides
605
+ │ Skills oats-aweb, aweb-messaging
606
+ │ Hooks SessionStart
607
+ │
608
+ │ Used by 2 souls
609
+ │ ■ dev ·2 · 1 on an older version
610
+ │ ■ reviewer ·1
611
+ ```
612
+
613
+ - **The list** is in the Desktop's sections: Workspace owned, Repo owned
614
+ and Packages. A section with no capability is not drawn, so Repo owned
615
+ stands only when the workspace has one. Under a section each repository
616
+ or package has a dim heading, its name and a note: `oats · member repo ·
617
+ host` (`-` in ASCII). A row is the capability's name, then its layer's
618
+ label, dim, when it has one: `Knowledge`, `Messaging`, `Tasks`. The list
619
+ keys move among the capabilities and pass over the headings. `/` filters
620
+ by name, and a group or a section the filter leaves empty is hidden. A
621
+ workspace with none says so, and that `oats capabilities` says why.
622
+ - **The detail** beside it, top to bottom:
623
+ - the name, its layer's label and the description;
624
+ - **Comes from**, a label and a value a line: for a repository's
625
+ capability its repository, its latest commit, its path and its
626
+ fingerprint, and for a repo-owned one that it is that repository's
627
+ souls' only; for a package's, the package, the version it is pinned to
628
+ and where that comes from, the commit and the fingerprint;
629
+ - **Provides**: its skills, commands and hooks, each kind the kernel
630
+ reports with its names; a kind it could not list says `Not listable: a
631
+ spawn of it would refuse.`, and one with no name `None`;
632
+ - **Used by**, with the count of souls beside it: one line per soul, its
633
+ colour mark (as in the Souls view), its name, a dim count of its
634
+ instances on this machine that carry the capability, `·2` (`x2` in
635
+ ASCII; `·0` too), and, when some of them are on an older version of
636
+ it, `· 1 on an older version` in the warning style. Eight at most, then
637
+ `+n`. With an OATS that reports what each soul is composed of (the
638
+ `souls-capabilities` feature, 0.45.0), these are the souls that include
639
+ it, and with none it says `No soul here includes it.` With an older
640
+ OATS they are the souls whose instances carry it, and with none it says
641
+ `No instance carries it yet.` A soul the souls catalog does not list is
642
+ drawn uncoloured. With the feature, until the souls are read it says
643
+ `Reading souls…`, and a read of them that fails says why, in the
644
+ warning style.
645
+ - **`Enter`** gives the detail the focus (under 80 columns it takes the
646
+ list's place), with a mark, `>` in reverse video, on the first soul of
647
+ Used by. `Up` and `Down` move the mark among the listed souls, and the
648
+ detail scrolls to keep it in sight. Past the first or the last soul, and
649
+ with the other movement keys, the detail scrolls; with no soul listed
650
+ every movement key scrolls it. `Enter` on the marked soul shows it in
651
+ [the Souls view](#the-souls-view), selected; on a soul the souls catalog
652
+ does not list it does nothing. `Tab` moves between the list and the
653
+ detail.
654
+ - **`r`** reads the capabilities again; while a read is under way it starts
655
+ nothing. `Esc` closes the detail, then clears a kept filter, then goes
656
+ back to the instances.
657
+ - **When it reads:** the first time the view is shown, never before: a run
658
+ that never shows it never runs `oats capabilities`. It reads the souls
659
+ too, for Used by, when they were not read yet. After that, a read of the
660
+ workspace reads the capabilities again only when the workspace changed
661
+ (its commit, a member's, its externals, its packages or its lock), and
662
+ `r` does. While the first read is under way the view says `Reading
663
+ capabilities…`. A read that fails says why, `Couldn't read this
664
+ workspace's capabilities:` and the message, with `r` to try again; one
665
+ that fails after a good one keeps the capabilities it had, under a
666
+ heading that says it failed and when they were read; the selected
667
+ capability's detail says why in full, under its name.
668
+ - **What is kept:** the selected capability and the filter, when the view
669
+ is left and shown again, for the run.
670
+ - **Only this machine's:** the view lists the capabilities of a workspace of
671
+ this machine. With none open it says so.
672
+
673
+ [The palette](#the-palette) lists the capabilities once they are read,
674
+ each with where it comes from; choosing one shows this view with it
675
+ selected.
676
+
300
677
  ## The switcher
301
678
 
302
679
  `w` opens the switcher: what this run can show, over the whole body of the
303
680
  screen.
304
681
 
305
682
  ```
306
- oats workspaces
307
- 1 Instances 2 Souls 3 Capabilities
683
+ workspaces
684
+ Instances Souls Capabilities
308
685
  ────────────────────────────────────────────────────────────────────────────────
309
686
  > * acme-platform This machine · garnet
310
687
  ledger quartz
@@ -316,8 +693,8 @@ screen.
316
693
 
317
694
 
318
695
 
319
- ────────────────────────────────────────────────────────────────────────────────
320
- Enter open / filter r refresh Esc close ? help q quit
696
+
697
+ C-\ commands Enter open / filter r refresh Esc close ? help q quit
321
698
  ```
322
699
 
323
700
  It lists, in this order:
@@ -379,8 +756,13 @@ confirmation:
379
756
  The rules are the Desktop's, from the readers both clients share: an
380
757
  instance offers what the Desktop offers for it, and nothing else. One that
381
758
  is still being spawned, and one its machine reports it cannot reach, offers
382
- none; one whose spawn stopped half way offers only to be retired; a running
383
- one offers restart and not start, a stopped one start and not restart. The
759
+ none; one whose spawn stopped half way, and one whose retire failed or
760
+ didn't finish, offers only to be retired; a running one offers restart and
761
+ not start, a stopped one start and not restart. One that is `Retiring…`
762
+ offers no start, stop, restart or open: `D` still opens its retire
763
+ confirmation, but the footer does not name it, since the kernel refuses a
764
+ second retire while one runs and it is needed only when the first one's
765
+ holder can't be read. The
384
766
  footer names the keys the selected instance offers now, after `Enter`, and
385
767
  on a narrow terminal they are the first hints it gives up. A key for an act
386
768
  the instance does not offer opens nothing, and the line above the panes
@@ -452,6 +834,82 @@ The exit status never depends on it.
452
834
  there can leave `.oats-stop-pending.json` in the agent's home, and then
453
835
  the agent can be started but not stopped while that file exists.
454
836
 
837
+ ## Spawning an agent
838
+
839
+ `n` spawns an agent of a soul of the open workspace, on this machine, with
840
+ one screen to read and one `Enter` to press.
841
+
842
+ - **`n`** in the list of instances (or the leader then `n`, from any focus,
843
+ a terminal's too) opens the soul picker over the list: the souls of
844
+ [the Souls view](#the-souls-view), read with `oats souls` if they were
845
+ not read yet (`Reading souls…` until then). Typing filters them with the
846
+ palette's subsequence match; `Up`/`Down` move, `Enter` picks the selected
847
+ soul, `Esc` closes. A soul a spawn here would refuse is listed with `!`
848
+ and why, and cannot be picked.
849
+ - **`N`** (or the leader then `N`) spawns another of the selected instance's
850
+ soul (from a terminal's focus, that terminal's instance): it opens the
851
+ preview at once. In the Souls view `n` and `N` both open the preview of
852
+ the selected soul. The palette lists `Spawn an agent` and, with an
853
+ instance selected whose soul the catalog lists, `Spawn another <soul>`.
854
+ - **The preview** is the OATS Desktop's, read with the kernel's
855
+ `oats spawn <soul> --preview --json` and worded by the same shared
856
+ readers: the name the agent will have, its home, where it works, its
857
+ harness and model and where that choice was made, its team, its
858
+ relationship, its worktree setup, where it runs; then the launch-prompt
859
+ policy, the capabilities' warnings and the modules, each folded to one
860
+ row.
861
+ - **One focus ring:** `Spawn` (where the focus starts), `name`, `child of`
862
+ (when an instance of this machine was selected), then each folded part.
863
+ `Tab` moves along it, `Shift+Tab` back. `Enter` does what the focus says,
864
+ and the footer names it:
865
+ - on `Spawn`, spawns what the preview shows;
866
+ - on `name`, keeps the name typed and reads the preview again with it:
867
+ the instance is named `<soul>-<name>` (`--purpose`). Only the letters,
868
+ digits and dashes of a name are typed; `Esc` puts back the name the
869
+ preview was read with;
870
+ - on `child of`, switches between no parent and the instance that was
871
+ selected when the prompt opened, and reads the preview again;
872
+ - on a folded part, opens or closes it.
873
+
874
+ `Esc` on any other focus gives it to `Spawn`; on `Spawn` it goes back to
875
+ the picker (to the list for `N` and from the Souls view). The movement
876
+ keys scroll a preview taller than the screen.
877
+ - **Nothing else is chosen here:** the harness and the model are the
878
+ soul's and this machine's launch preferences (`oats soul launch set`),
879
+ and there is no task: the new agent starts with none, and you type to it
880
+ in its terminal.
881
+ - **A paste cannot spawn.** An `Enter` in the same read of input as the
882
+ key that opened the prompt does nothing; `Enter` on `Spawn` spawns only
883
+ once the preview was read for exactly the choices shown, a frame that
884
+ shows it ready with its `Spawn` button was written to the terminal, and
885
+ only from a read of input later than that frame. A pasted `n`, a soul's
886
+ name and two `Enter`s stop at the preview.
887
+ - **`n` and `N` are of the view they are pressed in**: the leader's too.
888
+ From the Souls view (its list, its filter or its detail) both are of its
889
+ selected soul, whatever the list of instances has selected.
890
+ - **One spawn at a time.** While one is under way the line above the
891
+ panes says `Spawning <name>…`, and the TUI goes on working: `n` and `N`
892
+ say a spawn is under way and open nothing.
893
+ - **Only on this machine.** On another machine's row or workspace `n` and
894
+ `N` (from their keys, the leader or the palette) say that spawning on
895
+ another machine is not offered here, and that `oats spawn` there makes
896
+ one.
897
+
898
+ **What follows the spawn** is said in the shared words, the Desktop's, and
899
+ the TUI adds only what to do next, naming its keys or an `oats` command:
900
+
901
+ | Outcome | What follows |
902
+ |---|---|
903
+ | created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the list in a new [tab](#tabs), with the focus in it. With four tabs open the line says it was created, then `4 terminals are open; close one with C-\ w.`, and nothing opens. Not running after two reads: the line says it is not visible yet, and nothing opens later by itself |
904
+ | created, but not started, or its wake not saved, or not finished | the line says so; nothing opens. A home the spawn left reads as [held](#held-rows) |
905
+ | not known (the answer was lost, or still running at the deadline) | the line says so, and `C` checks its result once, without spawning again: it is offered only then |
906
+ | its cleanup is owed | the line says so and names the retire |
907
+ | refused, rolled back, never submitted, or changed since you looked | the preview again, read anew, with the line in it: change the choices or press `Enter` again |
908
+
909
+ **Quitting with a spawn under way** lets it go: the spawn finishes, or the
910
+ kernel's own limits bound it; `oats tui` neither waits for it nor ends it.
911
+ The line after leaving says so and names `oats status` to see it.
912
+
455
913
  ## Keys
456
914
 
457
915
  | Key | Does |
@@ -465,13 +923,20 @@ The exit status never depends on it.
465
923
  | `/` | filter |
466
924
  | `r` | read now |
467
925
  | `1` | the Instances view |
468
- | `2`, `3` | the Souls and Capabilities views: not in this version, so a line says what to run instead |
926
+ | `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
927
+ | `3` | [the Capabilities view](#the-capabilities-view); `Esc` or `1` goes back |
469
928
  | `w` | opens [the switcher](#the-switcher) |
470
- | `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 |
471
- | `z` | gives the open terminal the focus and the whole body |
472
- | `c` | closes the open terminal; the agent keeps running |
473
- | `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) |
929
+ | `Enter` | in the list of instances, opens the selected agent's terminal in a new [tab](#tabs) beside the list, or shows its tab when it has one, with the focus in it; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
930
+ | `z` | gives the shown terminal the focus and the whole body |
931
+ | `c` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
932
+ | `[`, `]` | in the Instances view, shows the tab before or after the shown one |
933
+ | `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
934
+ | `Ctrl+\` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
935
+ | `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
474
936
  | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
937
+ | `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
938
+ | `N` | spawns another of the selected instance's soul: its preview |
939
+ | `C` | checks the result of a spawn whose outcome is not known, while one is |
475
940
  | `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
476
941
  | `Space` | in a confirmation, switches the plan's choice |
477
942
  | `?` | opens the help; `?` again closes it |
@@ -489,10 +954,95 @@ instance can always be read, however many they are. The selection stays
489
954
  where it is, and the list returns to it at the next key that moves it.
490
955
 
491
956
  The help screen is generated from the table the program acts on, so it
492
- always lists the keys that work, with the marks and with what this version
493
- does not do. The movement keys scroll it. While a terminal has the focus
494
- the table's keys are the agent's: the back key alone is the TUI's. With the
495
- list focused the back key does nothing.
957
+ always lists the keys that work, the leader's among them, with the marks
958
+ and with what this version does not do. The movement keys scroll it. While
959
+ a terminal has the focus the table's keys are the agent's: the leader alone
960
+ is the TUI's.
961
+
962
+ ### The leader
963
+
964
+ Every action is reached by keys from every focus, a terminal's too: the
965
+ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
966
+
967
+ | The leader, then | Does |
968
+ |---|---|
969
+ | `k` or `Space` | opens [the palette](#the-palette) |
970
+ | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
971
+ | `Up`, `Down` | opens the terminal of the instance before or after, in the list as it is drawn, the focus in it: from the shown terminal's instance, or from the selection when none is open. It shows the instance's tab when it has one, else opens a new [tab](#tabs). Rows that cannot be opened are passed over, and the list does not wrap |
972
+ | `Left`, `Right` | shows the tab before or after the shown one; the strip does not wrap, and the focus stays where it was |
973
+ | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole body |
974
+ | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
975
+ | `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
976
+ | `Tab` | goes to the other group's terminal (or to the other group, when it is empty); from the list, to the focused group's |
977
+ | `m` | with two groups, moves the shown tab to the other group, and goes there |
978
+ | `x` | closes the focused group while it is empty |
979
+ | `X`, `R`, `S`, `D` | stop, restart, start, retire, [after a confirmation](#stopping-starting-restarting-and-retiring): from a terminal's focus on that terminal's instance, which has the focus again when the confirmation closes |
980
+ | `n`, `N` | [spawns an agent](#spawning-an-agent); `N` of the shown terminal's soul from its focus |
981
+ | `/` | the filter |
982
+ | `o` | [the switcher](#the-switcher) |
983
+ | `?` | the help |
984
+ | `Esc`, or the leader again | gives the list the focus; with the list focused, only closes the hint |
985
+
986
+ - **While the leader waits** for its key the footer row is its hint, which
987
+ names these keys (`z` and `w` only while a terminal is open, `Left` and
988
+ `Right` only with two tabs or more, `|` and `-` while the panel has one
989
+ group, `Tab` with two, then `m` while the focused group shows a tab or
990
+ `x` while it is empty). It waits
991
+ with no time limit. A key not in the table cancels it and is dropped:
992
+ nothing is typed.
993
+ - **Only a key in a later read counts.** A key that came in the same read of
994
+ input as the leader cancels it and is dropped, with the rest of that
995
+ read, so a paste can never run a command. In a terminal the bytes before
996
+ the leader in that read still go to the agent. A leader inside a
997
+ bracketed paste is pasted text.
998
+ - **In the list no leader is needed:** the plain keys work as they always
999
+ have, and the leader works there too.
1000
+ - **What was open under it is settled first,** from whatever view: a
1001
+ filter field keeps its filter, as `Enter` does, and a confirmation
1002
+ closes. `Up`, `Down`, `Left`, `Right`, `z`, `w`, the split's keys and the acts then go to
1003
+ the Instances view, from Souls, Capabilities, the help or the switcher
1004
+ too; with no workspace open they do nothing, and `Left`, `Right`, `z` and
1005
+ `w` do nothing with no terminal open.
1006
+ - **The table is fixed** in this version: `keys` in `tui.json` rebinds the
1007
+ plain keys, and `open.detachKey` the leader.
1008
+
1009
+ ### The palette
1010
+
1011
+ The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
1012
+ over a list, as the OATS Desktop's ⌘K does. It takes the body, and while it
1013
+ is open no terminal is drawn and the TUI reads the keys.
1014
+
1015
+ - **It lists, in this order:** the instances that can be opened, the most
1016
+ recently opened or shown in this run first (when the first is the shown tab's,
1017
+ the second is selected as it opens), then the list's order, each with its
1018
+ state mark, its name and, for another machine, `on <machine>`; the souls
1019
+ of the open workspace, once they were read (by [the Souls
1020
+ view](#the-souls-view), the Capabilities view or a spawn), and choosing
1021
+ one shows the Souls view with it selected; its capabilities, once [the
1022
+ Capabilities view](#the-capabilities-view) has read them, each with where
1023
+ it comes from, dim, and choosing one shows that view with it selected
1024
+ (the palette never reads either); the views, Instances, Souls and
1025
+ Capabilities; the acts the
1026
+ instance offers now (the shown terminal's when the palette was opened from
1027
+ its focus, else the selected one's), with `Spawn another <soul>` once the
1028
+ catalog lists its soul; then Spawn an agent, Workspaces, Refresh and Help, and [the split's](#splits)
1029
+ rows where each applies.
1030
+ Each row says at its right edge what kind it is: `instance`, `soul`,
1031
+ `capability`, `view`, `act` or `command`.
1032
+ - **Typing filters it** with the Desktop's subsequence match, a prefix
1033
+ first: each kind keeps the rows that match, the best first.
1034
+ `Backspace` removes a character, and a paste adds its first line.
1035
+ `Up`/`Down` (and `PageUp`/`PageDown`) move, `Enter` runs the selected
1036
+ row, `Esc` closes it.
1037
+ - **Running a row** settles what was open under the palette, as the leader
1038
+ does: an instance shows its tab, or opens its terminal in a new one, in
1039
+ the Instances view, the focus in it ([Tabs](#tabs)); an act opens its
1040
+ confirmation; a view shows
1041
+ it; a command does what its key does.
1042
+ - **An `Enter` in the same read as the palette's opening runs nothing**, so
1043
+ a paste cannot open it and run a row.
1044
+ - Closed, it gives the focus back to the terminal it was opened from.
1045
+ Recency is kept for the run only: nothing is written.
496
1046
 
497
1047
  **The filter.** `/` opens a field on the last row. What you type narrows the
498
1048
  list to the instances whose name, soul or repository contains it, with the
@@ -526,12 +1076,18 @@ never writes it. With no file the keys are the ones above.
526
1076
  do not name keeps its keys.
527
1077
  - The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
528
1078
  `collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
529
- `souls`, `capabilities`, `workspaces`, `open`, `zoom`, `close-terminal`,
530
- `stop`, `retire`, `start`, `restart`, `help`, `close`, `quit`, `suspend`
531
- and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
532
- opens the selected agent's terminal in the list of instances and the
533
- selected row in the switcher. `zoom` (`z`) and `close-terminal` (`c`) act
534
- on the open terminal. In an open filter field `Enter` keeps the filter,
1079
+ `souls`, `capabilities`, `workspaces`, `palette`, `open`, `soul-instances`, `zoom`, `close-terminal`,
1080
+ `tab-previous`, `tab-next`, `split-right`, `split-down`, `group-next`, `tab-move`,
1081
+ `group-close`, `stop`, `retire`, `start`, `restart`, `spawn`, `spawn-another`,
1082
+ `spawn-check`, `help`, `close`, `quit`, `suspend` and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
1083
+ opens the selected agent's terminal in the list of instances, the
1084
+ selected row in the switcher and the detail in the Souls view;
1085
+ `soul-instances` (`i`) shows the selected soul's instances. `zoom` (`z`) and `close-terminal` (`c`) act
1086
+ on the shown terminal, and `tab-previous` (`[`) and `tab-next` (`]`) show
1087
+ the tab before and after it. `split-right` (`|`) and `split-down` (`-`)
1088
+ [split](#splits) the panel; `group-next`, `tab-move` and `group-close`
1089
+ have no key of their own by default (the leader then `Tab`, `m` and `x`
1090
+ reach them). In an open filter field `Enter` keeps the filter,
535
1091
  whatever key `open` has.
536
1092
  - A key is written as the help shows it, in lower case: `q`, `G`, `?`,
537
1093
  `space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
@@ -540,9 +1096,11 @@ never writes it. With no file the keys are the ones above.
540
1096
  and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
541
1097
  keys of their own.
542
1098
  - `ascii: true` is `--ascii`.
543
- - `open.detachKey` is **the back key**: the key that takes the focus from
544
- an agent's terminal back to the list, `C-\` when you name none. It is
545
- `oats tui`'s own and never reaches the agent or the kernel. It is one of
1099
+ - `open.detachKey` is **[the leader](#the-leader)**, `C-\` when you name
1100
+ none. It is `oats tui`'s own and never reaches the agent or the kernel.
1101
+ It is read as a key wherever the TUI reads keys, so it may not be a key
1102
+ an action has: `C-l` is `redraw`'s `Ctrl+L`, `C-k` the palette's
1103
+ `Ctrl+K`, `C-j` is `Enter`. It is one of
546
1104
  these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
547
1105
  terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
548
1106
  `]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
@@ -562,6 +1120,7 @@ guesses nothing. It refuses:
562
1120
  | 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` |
563
1121
  | has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
564
1122
  | gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
1123
+ | gives `open.detachKey` a key an action has | `open.detachKey … is read as …, the key of …; give the leader a key no action has, or give … another` |
565
1124
  | names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
566
1125
  | names an action that does not exist | `unknown action …`, with the list of actions |
567
1126
  | gives an action something that is not a list of strings | `… must be a list of key ids` |
@@ -597,6 +1156,22 @@ with the Desktop (`packages/client/`).
597
1156
  read's. What a read in the background may reuse is the kernel's own look
598
1157
  at the workspace's remotes, for up to 60 seconds; `r` asks the kernel to
599
1158
  look again.
1159
+ - **The souls are one more read**, `oats souls --json` for the open
1160
+ workspace, by the same kernel, with 60 seconds and 4 MiB: only once [the
1161
+ Souls view](#the-souls-view), [the Capabilities
1162
+ view](#the-capabilities-view) or [the spawn prompt](#spawning-an-agent)
1163
+ was shown, then only when the workspace changed, and on `r` in the Souls
1164
+ view.
1165
+ - **The capabilities are one more read**, `oats capabilities --json` for
1166
+ the open workspace, read as the souls are: by the same kernel, with 60
1167
+ seconds and 4 MiB, only once [the Capabilities
1168
+ view](#the-capabilities-view) was shown, then only when the workspace
1169
+ changed (its packages and its lock count too), and on `r` there.
1170
+ - **A spawn's preview is one more read**, `oats spawn <soul> --preview
1171
+ --json` with the choices shown, by the same kernel, with 30 seconds: only
1172
+ while [the spawn prompt](#spawning-an-agent) is open, and again when a
1173
+ choice changes. An answer is reused for a minute, as the Desktop reuses
1174
+ it, until a spawn is applied or the workspace changes.
600
1175
  - **The other machines are one more read**, `oats server roster --json`,
601
1176
  by the same kernel: one answer for every machine registered on this
602
1177
  machine. It has 60 seconds and 4 MiB.
@@ -642,13 +1217,41 @@ with the Desktop (`packages/client/`).
642
1217
  `ps -o ppid= -p` (macOS). With neither (no `/proc`, and no `ps` or one
643
1218
  that refuses `-p`, like BusyBox's), the keeper kills nothing. A normal
644
1219
  end is not affected. An `oats tui` killed with SIGKILL can then leave
645
- its private server running, with the open terminal's viewer still
646
- attached to the agent, until you end it with `tmux -S
1220
+ its private server running, with its tabs' viewers still
1221
+ attached to their agents, until you end it with `tmux -S
647
1222
  <run directory>/tmux kill-server`. The next run's sweep leaves that
648
1223
  directory alone while its socket answers.
649
1224
 
650
- Each open is a window of the server, whose process is the viewer itself,
651
- with no shell between them. It is closed with `kill-pane`, which hangs up
1225
+ Each tab is a window of the server, whose process is the viewer itself,
1226
+ with no shell between them. Beside the keeper it holds up to four. Up
1227
+ to two are displayed, each group's shown tab ([Splits](#splits)), and
1228
+ every tab has its group's size: a resize resizes each tab's window in the
1229
+ groups drawn. Only the displayed tabs' panes are captured, and only the
1230
+ focused group's shown tab is typed into.
1231
+
1232
+ **A tab that is not drawn sends no output, from its mark on.** A hidden
1233
+ tab is heard until it prints: its first output captures nothing, sets its
1234
+ mark, and pauses its pane for `oats tui`'s control client
1235
+ (`refresh-client -A '%<pane>:pause'`, tmux 3.2 and later). From then on tmux sends none of
1236
+ that pane's output until the tab is displayed again, so a hidden agent
1237
+ that prints without pause costs one chunk of output each time its tab is
1238
+ hidden, and a quiet one nothing. The panel hidden as a whole (another
1239
+ view or an overlay over it, or the list alone under 80 columns) pauses
1240
+ its displayed tabs the same way. A
1241
+ paused pane is still read by the private server, so its screen stays
1242
+ current and its viewer never waits. A tab displayed again is continued
1243
+ (`:continue`) before it is captured: tmux restarts its output from where
1244
+ the pane is then, so the first frame is the pane's screen as it is, and
1245
+ nothing written meanwhile is replayed. `pause`, not `off`: from tmux 3.4
1246
+ on, a pane the control client has turned off is no longer read at all, so
1247
+ its viewer would stall and its screen go stale. Measured with a hidden tab
1248
+ printing without pause, `oats tui` takes about 0.4% of a core instead of
1249
+ 11%, and the private server 9% instead of 14%.
1250
+
1251
+ The panel refuses a fifth open (`E_PANEL_FULL`, an open
1252
+ still under way counted) and a second open while one is under way
1253
+ (`E_PANEL_BUSY`); the TUI asks for neither, since it refuses such an open
1254
+ itself ([Tabs](#tabs)). It is closed with `kill-pane`, which hangs up
652
1255
  the viewer's terminal: the viewer gets SIGHUP at once and removes its own
653
1256
  session on the agents' server. The viewer's error output goes to a file
654
1257
  of the run's directory (0600), read back when it ends and deleted. Its
@@ -658,22 +1261,28 @@ with the Desktop (`packages/client/`).
658
1261
  before it has that status (3.4 does, when the viewer's terminal hangs up a
659
1262
  moment before its process is reaped): `oats tui` then waits for the
660
1263
  status, which follows at the next report, for ten seconds at most (2.5
661
- on tmux 3.2, which never says which signal ended a pane). A pane whose
1264
+ on tmux 3.2, which never says which signal ended a pane). A tmux built
1265
+ with libutempter can lose a status for good: as it destroys a pane at
1266
+ the hang-up, libutempter holds back SIGCHLD while its helper runs, and
1267
+ tmux, which reaps only on a SIGCHLD, leaves a viewer that exited in that
1268
+ moment unreaped (tmux 3.4). So while `oats tui` waits it sends the server
1269
+ `run-shell true` at once and every second: that child's end makes tmux
1270
+ reap the viewer too, and its status follows at the next report. A pane whose
662
1271
  status has not come by then is taken as ended without one, and closed:
663
1272
  the terminal closes with the line that the viewer ended without saying
664
- why. What the terminal
1273
+ why. What the shown terminal
665
1274
  shows is captured into `capture` in that directory, which the server
666
1275
  writes and `oats tui` reads back, so nothing an agent prints passes
667
1276
  through the stream on which `oats tui` reads the server's answers. An
668
- answer the server would never give ends that stream, and the open
669
- terminal closes with it. The server is ended
1277
+ answer the server would never give ends that stream, and every tab
1278
+ closes with it. The server is ended
670
1279
  on every way out a process can handle. At its start a run also removes
671
1280
  what a run that is gone left (below), and nothing else: it signals
672
1281
  nothing.
673
1282
  - **Every read runs in a session of its own** and is ended when the TUI
674
1283
  ends, on every way out a process can handle (for SIGKILL see
675
- [below](#what-it-changes-in-your-terminal-and-restores)). An open
676
- terminal's viewer ends with the private server. A read that was
1284
+ [below](#what-it-changes-in-your-terminal-and-restores)). Every tab's
1285
+ viewer ends with the private server. A read that was
677
1286
  running when the TUI is suspended is dropped, not shown: its answer could
678
1287
  arrive cut. That holds for the read of the other machines too. The return
679
1288
  reads again.
@@ -693,9 +1302,24 @@ with the Desktop (`packages/client/`).
693
1302
  writing to them), and the directory is removed. `oats tui` waits for an
694
1303
  apply's answer for 10 minutes and for a start's for 60 seconds; then it
695
1304
  says so, and the change goes on.
1305
+ - **A spawn runs the kernel's own `oats spawn`**, as the Desktop does: the
1306
+ prepare (a read, with the choices on screen) and then the apply of the
1307
+ decision on screen (`--expect-decision`, `--idempotency-key`), a change
1308
+ like the acts', with its output in the same directory. It has the
1309
+ deadline the shared apply gives it, as the Desktop's has: 60 seconds,
1310
+ more for each worktree setup a capability runs. Past it, the spawn is
1311
+ sent SIGTERM (by `oats tui`, through the shared apply), and on an OATS
1312
+ that rolls a spawn back on it, SIGKILL 20 seconds later if it still
1313
+ runs: the outcome is then not known, and `C` checks it. Those timers are
1314
+ the run's: once `oats tui` has gone, no deadline of a spawn it let go
1315
+ signals it, and none keeps the process waiting. The shared apply
1316
+ writes the task file `oats spawn --task-file` reads, empty, under the
1317
+ system's temporary directory (`oats-desktop-task-*`, mode 0600), and
1318
+ removes it when the spawn answers; a spawn let go on the way out leaves
1319
+ it.
696
1320
  - It runs no other command that changes a deployment or a registration, and
697
1321
  it writes no other file but the private server's: its socket `tmux`, the
698
- keeper's FIFO `alive`, `capture` (the open terminal's screen, which the
1322
+ keeper's FIFO `alive`, `capture` (the shown terminal's screen, which the
699
1323
  server writes there for `oats tui` to read), and `owner.json` (`{ "tool":
700
1324
  "oats-tui", "pid": …, "started": … }`), which lets a later run tell a
701
1325
  directory a run that is gone left. A run that ends normally removes all
@@ -708,8 +1332,9 @@ with the Desktop (`packages/client/`).
708
1332
  | To | Run |
709
1333
  |---|---|
710
1334
  | start an agent with another harness or model | `oats session start --home <home>` with its options |
711
- | see souls, spawn an agent | `oats souls`, `oats spawn <soul>` |
712
- | see capabilities | `oats capabilities` |
1335
+ | spawn an agent on another machine | `oats spawn <soul> --server <id>` |
1336
+ | spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
1337
+ | see a capability's skills and files | `oats capabilities show <name>` |
713
1338
  | add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
714
1339
  | check a machine | `oats server check <id>` |
715
1340
  | remove a machine | `oats server remove <id>` |
@@ -727,12 +1352,17 @@ version:
727
1352
  opened with `oats tui --dir <path>`.
728
1353
  - **A row of another machine shows what its host reported at the last
729
1354
  read,** not what is true at this moment. The time of that read is on the
730
- machine's heading. A view of one machine has no heading: there the header
731
- names the machine (`on garnet`) and carries the time.
732
- - Souls and Capabilities, when they come, are this machine's.
1355
+ machine's heading when it is not the header's time. A view of one machine
1356
+ has no heading: there the header names the machine (`on garnet`) and
1357
+ carries the time.
1358
+ - The Souls and Capabilities views list a workspace of this machine's
1359
+ souls and capabilities: both are this machine's.
733
1360
  - There is no sorting and no mouse, and a deployment's heading cannot be
734
1361
  folded. An open terminal has no scrollback but the viewer's own.
735
- - One terminal is open at a time; tabs of several come in a later version.
1362
+ - Up to four terminals are open at a time, as tabs, in at most two
1363
+ groups. The split cannot be resized or nested, a tab moves only between
1364
+ the two groups, and no tab or split is kept from one run to the next, or
1365
+ across a switch of workspace.
736
1366
  - With an OATS older than 0.52.0, after an interrupted stop the instance can
737
1367
  be started and then cannot be stopped while `.oats-stop-pending.json` exists
738
1368
  in its home.
@@ -789,9 +1419,10 @@ suspends as one job.
789
1419
 
790
1420
  **While an agent's terminal is open** the terminal stays `oats tui`'s: the
791
1421
  viewer draws into the private server's pane, never into your terminal, and
792
- `oats tui` draws what that pane shows. Every way out in the table above ends
793
- the private server and with it the viewer, with that status. A suspend
794
- leaves the server and its viewer running; `fg` draws the terminal afresh.
1422
+ `oats tui` draws what the displayed tabs' panes show. Every way out in the
1423
+ table above ends the private server and with it every tab's viewer, with
1424
+ that status. A suspend
1425
+ leaves the server and its viewers running; `fg` draws the terminal afresh.
795
1426
 
796
1427
  `Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
797
1428
  a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
@@ -804,9 +1435,9 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
804
1435
  stayed in the alternate screen until `tput rmcup`. Nothing else is left in
805
1436
  tmux: `oats tui` creates no session, window, option or key binding.
806
1437
  Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
807
- read that was in flight runs to its own end. An open terminal's private
808
- server is ended by its keeper as soon as `oats tui` is gone, so the viewer's
809
- terminal hangs up and the viewer removes its own session. A stopped `oats tui`
1438
+ read that was in flight runs to its own end. The open terminals' private
1439
+ server is ended by its keeper as soon as `oats tui` is gone, so each tab's
1440
+ viewer has its terminal hung up and removes its own session. A stopped `oats tui`
810
1441
  (`Ctrl+Z`, SIGSTOP) still holds the keeper's FIFO, so its server is left
811
1442
  alone. The next run removes the directory that is left, with its `tmux`,
812
1443
  `alive`, `capture` and `owner.json`.
@@ -853,13 +1484,16 @@ alone. The next run removes the directory that is left, with its `tmux`,
853
1484
  socket but to ask whether a dead run's still answers.
854
1485
  - It starts no daemon, and writes no file but the output of a change and
855
1486
  its private server's own, in its own directory
1487
+ ([above](#what-it-reads-and-what-it-runs)), and a spawn's empty task file
856
1488
  ([above](#what-it-reads-and-what-it-runs)). The processes it starts are
857
1489
  the reads above, when you open an agent its private tmux server and the
858
- viewer in it, and the acts you confirm. No read, server or viewer
1490
+ viewers in it, one for each tab, and the acts you confirm. No read, server or viewer
859
1491
  outlives it on every way out a process can handle; after SIGKILL a read
860
- in flight runs to its own end, and the private server and its viewer end
1492
+ in flight runs to its own end, and the private server and its viewers end
861
1493
  by themselves. An act you confirmed is never ended by `oats tui`: it runs
862
- to its own end.
1494
+ to its own end. A spawn is ended only at its deadline, while `oats tui`
1495
+ runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
1496
+ and never after it.
863
1497
 
864
1498
  ## Errors
865
1499