@awebai/oats 0.57.1 → 0.59.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +24 -11
- package/docs/configuration.md +2 -1
- package/docs/desktop-cli-api.md +105 -17
- package/docs/desktop.md +30 -3
- package/docs/execution-targets.md +15 -0
- package/docs/implementation.md +2 -0
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +4 -4
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.58.0.md +107 -0
- package/docs/release-notes/v0.59.0.md +288 -0
- package/docs/servers.md +4 -1
- package/docs/souls-and-instances.md +30 -0
- package/docs/tui.md +653 -117
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +227 -46
- package/lib/read-ahead-worker.mjs +119 -0
- package/lib/read-ahead.mjs +115 -0
- package/lib/retire-state.mjs +33 -0
- package/lib/servers.mjs +9 -1
- package/lib/session-input.mjs +14 -4
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/instance-acts.mjs +23 -8
- package/packages/client/instance-presentation.mjs +3 -2
- package/packages/client/instance-tree.mjs +84 -39
- package/packages/client/lifecycle-confirmation.mjs +9 -3
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/remote-roster.mjs +4 -1
- package/packages/client/retire-in-flight.mjs +65 -0
- package/packages/client/retire-state.mjs +30 -0
- package/packages/client/spawn-apply-cli.mjs +8 -2
- package/packages/client/spawn-apply.mjs +20 -7
- package/packages/client/spawn-preview-cli.mjs +2 -1
- package/packages/client/spawn-preview.mjs +30 -18
- package/packages/record/lib/directory-identity.mjs +14 -0
- package/packages/record/lib/native-history.mjs +6 -5
- package/packages/tui/README.md +23 -10
- package/packages/tui/lib/actions.mjs +63 -5
- package/packages/tui/lib/client.mjs +12 -1
- package/packages/tui/lib/config.mjs +7 -2
- package/packages/tui/lib/main.mjs +315 -82
- package/packages/tui/lib/model.mjs +523 -56
- package/packages/tui/lib/panel.mjs +519 -144
- package/packages/tui/lib/read.mjs +52 -26
- package/packages/tui/lib/store.mjs +908 -65
- package/packages/tui/lib/term/keys.mjs +9 -2
- package/packages/tui/lib/term/text.mjs +4 -0
- package/packages/tui/lib/term/through.mjs +12 -1
- package/packages/tui/lib/views/frame.mjs +394 -95
- package/packages/tui/lib/views/help.mjs +54 -13
- package/packages/tui/lib/views/instances.mjs +43 -25
- package/packages/tui/lib/views/palette.mjs +61 -0
- package/packages/tui/lib/views/souls.mjs +268 -0
- package/packages/tui/lib/views/spawn.mjs +299 -0
- package/packages/tui/lib/views/split.mjs +29 -0
- 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
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
81
|
-
Instances Souls Capabilities
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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**
|
|
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
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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; the Capabilities view says what it will hold and what
|
|
113
|
+
to run until then, `oats capabilities`. On the right is the time of the
|
|
114
|
+
read of this machine 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.
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
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
|
|
147
|
-
|
|
148
|
-
|
|
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 `
|
|
153
|
-
nothing reads as stopped, or as running, that is only not
|
|
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
|
-
`
|
|
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
|
|
189
|
-
|
|
|
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,60 +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 `
|
|
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
|
-
|
|
273
|
+
acme-platform 2 running
|
|
229
274
|
Instances Souls Capabilities read 14:03:27
|
|
230
|
-
|
|
231
|
-
>
|
|
232
|
-
|
|
233
|
-
|
|
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
|
|
246
|
-
[`tui.json`](#change-the-keys-tuijson) names another)
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
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
|
|
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
|
|
256
|
-
|
|
257
|
-
|
|
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
|
-
- **
|
|
262
|
-
|
|
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
|
|
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
|
-
end once a second)
|
|
324
|
+
end once a second), or a second more when tmux took a moment more to
|
|
325
|
+
have the viewer's exit status: once tmux has reported the viewer ended,
|
|
326
|
+
`oats tui` waits ten seconds at most for that status, and closes the
|
|
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
|
|
272
331
|
says what happened: that it could not be opened, that the connection to
|
|
273
332
|
its machine ended, or that the viewer ended without saying why. What the
|
|
274
333
|
viewer printed on its error output stands under that line in quotation
|
|
@@ -278,7 +337,7 @@ fit; the detail shows them whole.
|
|
|
278
337
|
`Enter` opens it.
|
|
279
338
|
- **`Enter` on an instance that cannot be opened** opens nothing and says
|
|
280
339
|
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
|
|
340
|
+
reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
|
|
282
341
|
can be opened (`Esc` gives that up); a machine whose OATS cannot open its
|
|
283
342
|
sessions is said then.
|
|
284
343
|
- **No scrollback but the viewer's own, and no mouse.** The panel shows
|
|
@@ -294,14 +353,238 @@ fit; the detail shows them whole.
|
|
|
294
353
|
agent opens in the TUI's panel, and `oats tui` makes no window and no
|
|
295
354
|
split in your tmux.
|
|
296
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 leader then
|
|
406
|
+
`Left` or `Right` does the same from any focus, and from another view
|
|
407
|
+
goes to the Instances view first.
|
|
408
|
+
- The strip does not wrap: on the first tab `[` does nothing, and on the
|
|
409
|
+
last `]`; the leader then `Left` or `Right` there leaves even the focus
|
|
410
|
+
where it was.
|
|
411
|
+
- The focus does not move: in the terminal it stays in the terminal,
|
|
412
|
+
zoomed or not, and in the list it stays in the list.
|
|
413
|
+
- **Showing a tab selects its instance's row** in the list and brings it
|
|
414
|
+
into view: a filter that hides the row is cleared, and an instance
|
|
415
|
+
folded over it is opened.
|
|
416
|
+
- **The palette** lists the instances most recently opened or shown first,
|
|
417
|
+
as the Desktop's does. When the first of them is the shown tab's, the
|
|
418
|
+
palette opens with the second selected, so the palette then `Enter` goes
|
|
419
|
+
back to the terminal shown before it.
|
|
420
|
+
- **Closing.** The leader then `w`, or `c` in the Instances view, closes the
|
|
421
|
+
shown tab: its agent keeps running. The tab to its right is shown, else
|
|
422
|
+
the one to its left.
|
|
423
|
+
- After the leader then `w` from a terminal, the tab shown next has the
|
|
424
|
+
focus, and is zoomed when the one closed was. After `c`, or the leader
|
|
425
|
+
then `w` from anywhere else, the terminal does not take the focus.
|
|
426
|
+
- Closing the last tab closes the panel: the right side is the detail
|
|
427
|
+
again, and the list has the focus.
|
|
428
|
+
- **A tab that closes by itself**, when its viewer ends, says so on the line
|
|
429
|
+
above the panes in the words [above](#open-an-agents-terminal), for that
|
|
430
|
+
tab's agent (no line when it ended cleanly).
|
|
431
|
+
- The shown tab: the tab to its right is shown, else the one to its left,
|
|
432
|
+
and the list takes the focus.
|
|
433
|
+
- A hidden tab: the shown tab and the focus stay as they were.
|
|
434
|
+
- **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole body.
|
|
435
|
+
The strip stays its top row, and the other tabs stay open.
|
|
436
|
+
- **The tabs are the open workspace's.** Opening another workspace in
|
|
437
|
+
[the switcher](#the-switcher) closes them all, and so does the open
|
|
438
|
+
workspace no longer being listed; their agents keep running. Coming back
|
|
439
|
+
opens none of them again.
|
|
440
|
+
|
|
441
|
+
## Splits
|
|
442
|
+
|
|
443
|
+
```
|
|
444
|
+
acme-platform 3 running
|
|
445
|
+
Instances Souls Capabilities read 14:03:27
|
|
446
|
+
──────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────
|
|
447
|
+
● backend-lead │ backend-lead docs-writer │ qa-runner
|
|
448
|
+
● docs-writer │$ git log --oneline -2 │$ make test
|
|
449
|
+
> ● qa-runner │4be1c0d Fix the reader │ok 41 of 41
|
|
450
|
+
│9a03e7f Add the roster │
|
|
451
|
+
│ │
|
|
452
|
+
C-\ commands C-\ C-\ back to the list
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
The panel can be split in two **groups**, side by side or one above the
|
|
456
|
+
other. Each group is a panel of [tabs](#tabs) of its own: a strip, a shown
|
|
457
|
+
tab and the marks of its hidden ones.
|
|
458
|
+
|
|
459
|
+
- **Splitting.** The leader then `|` splits the panel side by side, and the
|
|
460
|
+
leader then `-` one above the other; in the Instances view `|` and `-`
|
|
461
|
+
do the same without the leader. The tabs open stay in the first group
|
|
462
|
+
(left, or top). The second group starts empty and is the focused group.
|
|
463
|
+
- A split needs a tab open, and none starting.
|
|
464
|
+
- **There are at most two groups.** With two, the split keys do nothing,
|
|
465
|
+
and the line above the panes says `The panel has two groups already.`
|
|
466
|
+
- **Each group needs 40 columns side by side, and 8 rows one above the
|
|
467
|
+
other**, its strip counted. The panel beside the list then needs 81
|
|
468
|
+
columns (a terminal of 112), or 17 rows. A split that would leave a
|
|
469
|
+
group smaller does nothing, and the line says so:
|
|
470
|
+
`No room to split side by side: each group needs 40 columns.` or
|
|
471
|
+
`No room to split one above the other: each group needs 8 rows.`
|
|
472
|
+
- **What is drawn.** A rule separates the groups. Both groups' shown tabs
|
|
473
|
+
are drawn as their agents write; hidden tabs only set their marks.
|
|
474
|
+
- The focused group's strip is drawn as with one group: its shown tab in
|
|
475
|
+
reverse while its terminal has the focus, bold otherwise. The other
|
|
476
|
+
group's shown tab is bold, never in reverse, so one terminal at a time
|
|
477
|
+
reads as the one you type into.
|
|
478
|
+
- **An empty group** says `Enter on an agent opens it here`, in reverse
|
|
479
|
+
while it is the focused group, and the leader's keys to go to the other
|
|
480
|
+
group or to close it. It never takes keys: while it is the focused
|
|
481
|
+
group, the keys are the list's.
|
|
482
|
+
- A resize gives each group its share and reaches every tab's window in
|
|
483
|
+
it. **When the terminal becomes too small for both groups,** the split
|
|
484
|
+
stays and the focused group is drawn alone; the other group's shown tab
|
|
485
|
+
is not drawn, only marked, until there is room again.
|
|
486
|
+
- **Under 80 columns** the terminal's focus gives the whole body to both
|
|
487
|
+
groups, and the list's focus shows the list alone, as with one group.
|
|
488
|
+
- **Zoom** (`z`, or the leader then `z`) gives the focused group's shown
|
|
489
|
+
terminal the whole body, and the same key brings the split back. With
|
|
490
|
+
the empty group focused it does nothing.
|
|
491
|
+
- **Opening.** `Enter`, the palette, the leader then `Up`/`Down` and a
|
|
492
|
+
spawn open as with one group:
|
|
493
|
+
- an instance that has a tab, in either group: that tab is shown in its
|
|
494
|
+
group, and that group takes the focus;
|
|
495
|
+
- any other: a new tab in the focused group, after its shown tab, or as
|
|
496
|
+
the first tab of the empty group.
|
|
497
|
+
- **The four tabs are counted across both groups.** At four, the line
|
|
498
|
+
says `4 terminals are open; close one with C-\ w.` as with one group.
|
|
499
|
+
- **Moving between the groups.** The leader then `Tab` from a terminal goes
|
|
500
|
+
to the other group's shown terminal, or to the other group when it is
|
|
501
|
+
empty. From the list it goes to the focused group's terminal, or, with
|
|
502
|
+
the focused group empty, to the other group's. Showing a tab selects its
|
|
503
|
+
row in the list. `[`, `]` and the leader then `Left`/`Right` show the tab
|
|
504
|
+
before or after within the focused group only.
|
|
505
|
+
- **Moving a tab.** The leader then `m` moves the focused group's shown tab
|
|
506
|
+
to the other group, after that group's shown tab, and shows it there with
|
|
507
|
+
the focus. The group it leaves shows its neighbour, or stays, empty.
|
|
508
|
+
- **Closing.** Closing a tab (`c`, or the leader then `w`) shows its
|
|
509
|
+
neighbour in its group: the tab to its right, else the one to its left.
|
|
510
|
+
- **A group's last tab closed removes the group:** the other takes the
|
|
511
|
+
whole panel and the focus. When the other group was empty, the panel
|
|
512
|
+
closes, as when the last tab of the only group closes.
|
|
513
|
+
- The leader then `x` closes the focused group while it is empty: the
|
|
514
|
+
other takes the whole panel and is the focused group, and the keys stay
|
|
515
|
+
the list's. With tabs in the group, `x` does nothing.
|
|
516
|
+
- **A tab that closes by itself** shows its neighbour in its group. A
|
|
517
|
+
group's last tab closing by itself removes the group, and the list
|
|
518
|
+
takes the focus; when what is left is an empty group, the panel closes.
|
|
519
|
+
- **The palette** lists `Split right` and `Split down` while there is one
|
|
520
|
+
group, then `Move tab to the other group` while the focused group shows a
|
|
521
|
+
tab, or `Close the empty group` while it is empty.
|
|
522
|
+
- **Another workspace** closes every tab and the split.
|
|
523
|
+
- The split cannot be resized or nested, and is not kept from one run to
|
|
524
|
+
the next.
|
|
525
|
+
|
|
526
|
+
## The Souls view
|
|
527
|
+
|
|
528
|
+
`2`, or the leader then `2`, shows the souls of the open workspace: the
|
|
529
|
+
ones `oats spawn` can make an instance of here, as the OATS Desktop lists
|
|
530
|
+
them, from the same code.
|
|
531
|
+
|
|
532
|
+
```
|
|
533
|
+
acme-platform 2 running 1 stopped
|
|
534
|
+
Instances Souls Capabilities read 14:03:27
|
|
535
|
+
──────────────────────────────────────┬─────────────────────────────────────────
|
|
536
|
+
> ■ dev ·2 │ dev
|
|
537
|
+
■ ops ! │ Builds and ships the platform.
|
|
538
|
+
■ reviewer ·1 │
|
|
539
|
+
│ from oats-core
|
|
540
|
+
│ works works in its own worktree
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
- **A row** is the soul's colour mark (`■`, `#` in ASCII; its colour is the
|
|
544
|
+
Desktop's for that soul, uncoloured when it has none), its name, and a
|
|
545
|
+
count of its instances on this machine, `·2`. A soul a spawn here would
|
|
546
|
+
refuse is drawn dim, with `!` after its name. The list keys move, and `/`
|
|
547
|
+
filters by name, description or where the soul comes from.
|
|
548
|
+
- **The detail** beside it, top to bottom: the name and the description;
|
|
549
|
+
where it comes from (its member, or its package and version); where it
|
|
550
|
+
works; why a spawn here would be refused, when it would be; the harness
|
|
551
|
+
and model a spawn would use and where that choice is set (a launch
|
|
552
|
+
problem as the kernel reports it); its teams, the default first; its
|
|
553
|
+
capabilities; and its instances on this machine, eight at most and then
|
|
554
|
+
`+n`. `Enter` gives the detail the focus (under 80 columns it takes the
|
|
555
|
+
list's place), and the movement keys then scroll it.
|
|
556
|
+
- **`i`**, or `Enter` in the detail, shows that soul's instances in the
|
|
557
|
+
Instances view: an exact filter, shown where a kept filter stands in
|
|
558
|
+
the footer, `soul dev`.
|
|
559
|
+
An instance of another soul whose name holds `dev` is not listed. `Esc`
|
|
560
|
+
clears it, and `/` replaces it with a text filter.
|
|
561
|
+
- **`r`** reads the souls again; while a read is under way it starts
|
|
562
|
+
nothing. `Esc` closes the detail, then clears a kept filter, then goes
|
|
563
|
+
back to the instances.
|
|
564
|
+
- **When it reads:** the first time the view is shown, never before: a run
|
|
565
|
+
that never shows it never runs `oats souls`. After that, a read of the
|
|
566
|
+
workspace reads the souls again only when the workspace changed (its
|
|
567
|
+
commit, a member's, its externals), and `r` does. While the first read is
|
|
568
|
+
under way the view says `Reading souls…`. A read that fails says why,
|
|
569
|
+
with `r` to try again; one that fails after a good one keeps the souls it
|
|
570
|
+
had, under a heading that says it failed and when the souls were read;
|
|
571
|
+
the selected soul's detail says why in full, under its name.
|
|
572
|
+
- **What is kept:** the selected soul and the filter, when the view is left
|
|
573
|
+
and shown again, for the run.
|
|
574
|
+
- **Only this machine's:** the view lists the souls of a workspace of this
|
|
575
|
+
machine. With none open it says so.
|
|
576
|
+
|
|
577
|
+
`n` or `N` spawns an agent of the selected soul: [Spawning an
|
|
578
|
+
agent](#spawning-an-agent).
|
|
579
|
+
|
|
297
580
|
## The switcher
|
|
298
581
|
|
|
299
582
|
`w` opens the switcher: what this run can show, over the whole body of the
|
|
300
583
|
screen.
|
|
301
584
|
|
|
302
585
|
```
|
|
303
|
-
|
|
304
|
-
|
|
586
|
+
workspaces
|
|
587
|
+
Instances Souls Capabilities
|
|
305
588
|
────────────────────────────────────────────────────────────────────────────────
|
|
306
589
|
> * acme-platform This machine · garnet
|
|
307
590
|
ledger quartz
|
|
@@ -313,8 +596,8 @@ screen.
|
|
|
313
596
|
|
|
314
597
|
|
|
315
598
|
|
|
316
|
-
|
|
317
|
-
Enter open / filter r refresh Esc close ? help q quit
|
|
599
|
+
|
|
600
|
+
C-\ commands Enter open / filter r refresh Esc close ? help q quit
|
|
318
601
|
```
|
|
319
602
|
|
|
320
603
|
It lists, in this order:
|
|
@@ -376,8 +659,13 @@ confirmation:
|
|
|
376
659
|
The rules are the Desktop's, from the readers both clients share: an
|
|
377
660
|
instance offers what the Desktop offers for it, and nothing else. One that
|
|
378
661
|
is still being spawned, and one its machine reports it cannot reach, offers
|
|
379
|
-
none; one whose spawn stopped half way
|
|
380
|
-
|
|
662
|
+
none; one whose spawn stopped half way, and one whose retire failed or
|
|
663
|
+
didn't finish, offers only to be retired; a running one offers restart and
|
|
664
|
+
not start, a stopped one start and not restart. One that is `Retiring…`
|
|
665
|
+
offers no start, stop, restart or open: `D` still opens its retire
|
|
666
|
+
confirmation, but the footer does not name it, since the kernel refuses a
|
|
667
|
+
second retire while one runs and it is needed only when the first one's
|
|
668
|
+
holder can't be read. The
|
|
381
669
|
footer names the keys the selected instance offers now, after `Enter`, and
|
|
382
670
|
on a narrow terminal they are the first hints it gives up. A key for an act
|
|
383
671
|
the instance does not offer opens nothing, and the line above the panes
|
|
@@ -449,6 +737,82 @@ The exit status never depends on it.
|
|
|
449
737
|
there can leave `.oats-stop-pending.json` in the agent's home, and then
|
|
450
738
|
the agent can be started but not stopped while that file exists.
|
|
451
739
|
|
|
740
|
+
## Spawning an agent
|
|
741
|
+
|
|
742
|
+
`n` spawns an agent of a soul of the open workspace, on this machine, with
|
|
743
|
+
one screen to read and one `Enter` to press.
|
|
744
|
+
|
|
745
|
+
- **`n`** in the list of instances (or the leader then `n`, from any focus,
|
|
746
|
+
a terminal's too) opens the soul picker over the list: the souls of
|
|
747
|
+
[the Souls view](#the-souls-view), read with `oats souls` if they were
|
|
748
|
+
not read yet (`Reading souls…` until then). Typing filters them with the
|
|
749
|
+
palette's subsequence match; `Up`/`Down` move, `Enter` picks the selected
|
|
750
|
+
soul, `Esc` closes. A soul a spawn here would refuse is listed with `!`
|
|
751
|
+
and why, and cannot be picked.
|
|
752
|
+
- **`N`** (or the leader then `N`) spawns another of the selected instance's
|
|
753
|
+
soul (from a terminal's focus, that terminal's instance): it opens the
|
|
754
|
+
preview at once. In the Souls view `n` and `N` both open the preview of
|
|
755
|
+
the selected soul. The palette lists `Spawn an agent` and, with an
|
|
756
|
+
instance selected whose soul the catalog lists, `Spawn another <soul>`.
|
|
757
|
+
- **The preview** is the OATS Desktop's, read with the kernel's
|
|
758
|
+
`oats spawn <soul> --preview --json` and worded by the same shared
|
|
759
|
+
readers: the name the agent will have, its home, where it works, its
|
|
760
|
+
harness and model and where that choice was made, its team, its
|
|
761
|
+
relationship, its worktree setup, where it runs; then the launch-prompt
|
|
762
|
+
policy, the capabilities' warnings and the modules, each folded to one
|
|
763
|
+
row.
|
|
764
|
+
- **One focus ring:** `Spawn` (where the focus starts), `name`, `child of`
|
|
765
|
+
(when an instance of this machine was selected), then each folded part.
|
|
766
|
+
`Tab` moves along it, `Shift+Tab` back. `Enter` does what the focus says,
|
|
767
|
+
and the footer names it:
|
|
768
|
+
- on `Spawn`, spawns what the preview shows;
|
|
769
|
+
- on `name`, keeps the name typed and reads the preview again with it:
|
|
770
|
+
the instance is named `<soul>-<name>` (`--purpose`). Only the letters,
|
|
771
|
+
digits and dashes of a name are typed; `Esc` puts back the name the
|
|
772
|
+
preview was read with;
|
|
773
|
+
- on `child of`, switches between no parent and the instance that was
|
|
774
|
+
selected when the prompt opened, and reads the preview again;
|
|
775
|
+
- on a folded part, opens or closes it.
|
|
776
|
+
|
|
777
|
+
`Esc` on any other focus gives it to `Spawn`; on `Spawn` it goes back to
|
|
778
|
+
the picker (to the list for `N` and from the Souls view). The movement
|
|
779
|
+
keys scroll a preview taller than the screen.
|
|
780
|
+
- **Nothing else is chosen here:** the harness and the model are the
|
|
781
|
+
soul's and this machine's launch preferences (`oats soul launch set`),
|
|
782
|
+
and there is no task: the new agent starts with none, and you type to it
|
|
783
|
+
in its terminal.
|
|
784
|
+
- **A paste cannot spawn.** An `Enter` in the same read of input as the
|
|
785
|
+
key that opened the prompt does nothing; `Enter` on `Spawn` spawns only
|
|
786
|
+
once the preview was read for exactly the choices shown, a frame that
|
|
787
|
+
shows it ready with its `Spawn` button was written to the terminal, and
|
|
788
|
+
only from a read of input later than that frame. A pasted `n`, a soul's
|
|
789
|
+
name and two `Enter`s stop at the preview.
|
|
790
|
+
- **`n` and `N` are of the view they are pressed in**: the leader's too.
|
|
791
|
+
From the Souls view (its list, its filter or its detail) both are of its
|
|
792
|
+
selected soul, whatever the list of instances has selected.
|
|
793
|
+
- **One spawn at a time.** While one is under way the line above the
|
|
794
|
+
panes says `Spawning <name>…`, and the TUI goes on working: `n` and `N`
|
|
795
|
+
say a spawn is under way and open nothing.
|
|
796
|
+
- **Only on this machine.** On another machine's row or workspace `n` and
|
|
797
|
+
`N` (from their keys, the leader or the palette) say that spawning on
|
|
798
|
+
another machine is not offered here, and that `oats spawn` there makes
|
|
799
|
+
one.
|
|
800
|
+
|
|
801
|
+
**What follows the spawn** is said in the shared words, the Desktop's, and
|
|
802
|
+
the TUI adds only what to do next, naming its keys or an `oats` command:
|
|
803
|
+
|
|
804
|
+
| Outcome | What follows |
|
|
805
|
+
|---|---|
|
|
806
|
+
| 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 |
|
|
807
|
+
| 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) |
|
|
808
|
+
| 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 |
|
|
809
|
+
| its cleanup is owed | the line says so and names the retire |
|
|
810
|
+
| 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 |
|
|
811
|
+
|
|
812
|
+
**Quitting with a spawn under way** lets it go: the spawn finishes, or the
|
|
813
|
+
kernel's own limits bound it; `oats tui` neither waits for it nor ends it.
|
|
814
|
+
The line after leaving says so and names `oats status` to see it.
|
|
815
|
+
|
|
452
816
|
## Keys
|
|
453
817
|
|
|
454
818
|
| Key | Does |
|
|
@@ -462,13 +826,20 @@ The exit status never depends on it.
|
|
|
462
826
|
| `/` | filter |
|
|
463
827
|
| `r` | read now |
|
|
464
828
|
| `1` | the Instances view |
|
|
465
|
-
| `2
|
|
829
|
+
| `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
|
|
830
|
+
| `3` | the Capabilities view, which says what it will hold and what to run until then; `Esc` or `1` goes back |
|
|
466
831
|
| `w` | opens [the switcher](#the-switcher) |
|
|
467
|
-
| `Enter` | in the list of instances, opens the selected agent's terminal beside the list, or
|
|
468
|
-
| `z` | gives the
|
|
469
|
-
| `c` | closes the
|
|
470
|
-
| `
|
|
832
|
+
| `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 |
|
|
833
|
+
| `z` | gives the shown terminal the focus and the whole body |
|
|
834
|
+
| `c` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
835
|
+
| `[`, `]` | in the Instances view, shows the tab before or after the shown one |
|
|
836
|
+
| `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
|
|
837
|
+
| `Ctrl+\` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
|
|
838
|
+
| `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
|
|
471
839
|
| `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
|
|
840
|
+
| `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
|
|
841
|
+
| `N` | spawns another of the selected instance's soul: its preview |
|
|
842
|
+
| `C` | checks the result of a spawn whose outcome is not known, while one is |
|
|
472
843
|
| `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
|
|
473
844
|
| `Space` | in a confirmation, switches the plan's choice |
|
|
474
845
|
| `?` | opens the help; `?` again closes it |
|
|
@@ -486,10 +857,91 @@ instance can always be read, however many they are. The selection stays
|
|
|
486
857
|
where it is, and the list returns to it at the next key that moves it.
|
|
487
858
|
|
|
488
859
|
The help screen is generated from the table the program acts on, so it
|
|
489
|
-
always lists the keys that work,
|
|
490
|
-
does not do. The movement keys scroll it. While
|
|
491
|
-
the table's keys are the agent's: the
|
|
492
|
-
|
|
860
|
+
always lists the keys that work, the leader's among them, with the marks
|
|
861
|
+
and with what this version does not do. The movement keys scroll it. While
|
|
862
|
+
a terminal has the focus the table's keys are the agent's: the leader alone
|
|
863
|
+
is the TUI's.
|
|
864
|
+
|
|
865
|
+
### The leader
|
|
866
|
+
|
|
867
|
+
Every action is reached by keys from every focus, a terminal's too: the
|
|
868
|
+
leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
|
|
869
|
+
|
|
870
|
+
| The leader, then | Does |
|
|
871
|
+
|---|---|
|
|
872
|
+
| `k` or `Space` | opens [the palette](#the-palette) |
|
|
873
|
+
| `1`, `2`, `3` | the Instances, Souls and Capabilities views |
|
|
874
|
+
| `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 |
|
|
875
|
+
| `Left`, `Right` | shows the tab before or after the shown one; the strip does not wrap, and the focus stays where it was |
|
|
876
|
+
| `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole body |
|
|
877
|
+
| `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
878
|
+
| `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
|
|
879
|
+
| `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 |
|
|
880
|
+
| `m` | with two groups, moves the shown tab to the other group, and goes there |
|
|
881
|
+
| `x` | closes the focused group while it is empty |
|
|
882
|
+
| `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 |
|
|
883
|
+
| `n`, `N` | [spawns an agent](#spawning-an-agent); `N` of the shown terminal's soul from its focus |
|
|
884
|
+
| `/` | the filter |
|
|
885
|
+
| `o` | [the switcher](#the-switcher) |
|
|
886
|
+
| `?` | the help |
|
|
887
|
+
| `Esc`, or the leader again | gives the list the focus; with the list focused, only closes the hint |
|
|
888
|
+
|
|
889
|
+
- **While the leader waits** for its key the footer row is its hint, which
|
|
890
|
+
names these keys (`z` and `w` only while a terminal is open, `Left` and
|
|
891
|
+
`Right` only with two tabs or more, `|` and `-` while the panel has one
|
|
892
|
+
group, `Tab` with two, then `m` while the focused group shows a tab or
|
|
893
|
+
`x` while it is empty). It waits
|
|
894
|
+
with no time limit. A key not in the table cancels it and is dropped:
|
|
895
|
+
nothing is typed.
|
|
896
|
+
- **Only a key in a later read counts.** A key that came in the same read of
|
|
897
|
+
input as the leader cancels it and is dropped, with the rest of that
|
|
898
|
+
read, so a paste can never run a command. In a terminal the bytes before
|
|
899
|
+
the leader in that read still go to the agent. A leader inside a
|
|
900
|
+
bracketed paste is pasted text.
|
|
901
|
+
- **In the list no leader is needed:** the plain keys work as they always
|
|
902
|
+
have, and the leader works there too.
|
|
903
|
+
- **What was open under it is settled first,** from whatever view: a
|
|
904
|
+
filter field keeps its filter, as `Enter` does, and a confirmation
|
|
905
|
+
closes. `Up`, `Down`, `Left`, `Right`, `z`, `w`, the split's keys and the acts then go to
|
|
906
|
+
the Instances view, from Souls, Capabilities, the help or the switcher
|
|
907
|
+
too; with no workspace open they do nothing, and `Left`, `Right`, `z` and
|
|
908
|
+
`w` do nothing with no terminal open.
|
|
909
|
+
- **The table is fixed** in this version: `keys` in `tui.json` rebinds the
|
|
910
|
+
plain keys, and `open.detachKey` the leader.
|
|
911
|
+
|
|
912
|
+
### The palette
|
|
913
|
+
|
|
914
|
+
The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
|
|
915
|
+
over a list, as the OATS Desktop's ⌘K does. It takes the body, and while it
|
|
916
|
+
is open no terminal is drawn and the TUI reads the keys.
|
|
917
|
+
|
|
918
|
+
- **It lists, in this order:** the instances that can be opened, the most
|
|
919
|
+
recently opened or shown in this run first (when the first is the shown tab's,
|
|
920
|
+
the second is selected as it opens), then the list's order, each with its
|
|
921
|
+
state mark, its name and, for another machine, `on <machine>`; the souls
|
|
922
|
+
of the open workspace, once [the Souls view](#the-souls-view) has read
|
|
923
|
+
them (choosing one shows that view with it selected; the palette never
|
|
924
|
+
reads them); the views, Instances, Souls and Capabilities; the acts the
|
|
925
|
+
instance offers now (the shown terminal's when the palette was opened from
|
|
926
|
+
its focus, else the selected one's), with `Spawn another <soul>` once the
|
|
927
|
+
catalog lists its soul; then Spawn an agent, Workspaces, Refresh and Help, and [the split's](#splits)
|
|
928
|
+
rows where each applies.
|
|
929
|
+
Each row says at its right edge what kind it is: `instance`, `soul`,
|
|
930
|
+
`view`, `act` or `command`.
|
|
931
|
+
- **Typing filters it** with the Desktop's subsequence match, a prefix
|
|
932
|
+
first: each kind keeps the rows that match, the best first.
|
|
933
|
+
`Backspace` removes a character, and a paste adds its first line.
|
|
934
|
+
`Up`/`Down` (and `PageUp`/`PageDown`) move, `Enter` runs the selected
|
|
935
|
+
row, `Esc` closes it.
|
|
936
|
+
- **Running a row** settles what was open under the palette, as the leader
|
|
937
|
+
does: an instance shows its tab, or opens its terminal in a new one, in
|
|
938
|
+
the Instances view, the focus in it ([Tabs](#tabs)); an act opens its
|
|
939
|
+
confirmation; a view shows
|
|
940
|
+
it; a command does what its key does.
|
|
941
|
+
- **An `Enter` in the same read as the palette's opening runs nothing**, so
|
|
942
|
+
a paste cannot open it and run a row.
|
|
943
|
+
- Closed, it gives the focus back to the terminal it was opened from.
|
|
944
|
+
Recency is kept for the run only: nothing is written.
|
|
493
945
|
|
|
494
946
|
**The filter.** `/` opens a field on the last row. What you type narrows the
|
|
495
947
|
list to the instances whose name, soul or repository contains it, with the
|
|
@@ -523,12 +975,18 @@ never writes it. With no file the keys are the ones above.
|
|
|
523
975
|
do not name keeps its keys.
|
|
524
976
|
- The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
|
|
525
977
|
`collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
|
|
526
|
-
`souls`, `capabilities`, `workspaces`, `open`, `zoom`, `close-terminal`,
|
|
527
|
-
`
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
selected
|
|
531
|
-
|
|
978
|
+
`souls`, `capabilities`, `workspaces`, `palette`, `open`, `soul-instances`, `zoom`, `close-terminal`,
|
|
979
|
+
`tab-previous`, `tab-next`, `split-right`, `split-down`, `group-next`, `tab-move`,
|
|
980
|
+
`group-close`, `stop`, `retire`, `start`, `restart`, `spawn`, `spawn-another`,
|
|
981
|
+
`spawn-check`, `help`, `close`, `quit`, `suspend` and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
|
|
982
|
+
opens the selected agent's terminal in the list of instances, the
|
|
983
|
+
selected row in the switcher and the detail in the Souls view;
|
|
984
|
+
`soul-instances` (`i`) shows the selected soul's instances. `zoom` (`z`) and `close-terminal` (`c`) act
|
|
985
|
+
on the shown terminal, and `tab-previous` (`[`) and `tab-next` (`]`) show
|
|
986
|
+
the tab before and after it. `split-right` (`|`) and `split-down` (`-`)
|
|
987
|
+
[split](#splits) the panel; `group-next`, `tab-move` and `group-close`
|
|
988
|
+
have no key of their own by default (the leader then `Tab`, `m` and `x`
|
|
989
|
+
reach them). In an open filter field `Enter` keeps the filter,
|
|
532
990
|
whatever key `open` has.
|
|
533
991
|
- A key is written as the help shows it, in lower case: `q`, `G`, `?`,
|
|
534
992
|
`space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
|
|
@@ -537,9 +995,11 @@ never writes it. With no file the keys are the ones above.
|
|
|
537
995
|
and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
|
|
538
996
|
keys of their own.
|
|
539
997
|
- `ascii: true` is `--ascii`.
|
|
540
|
-
- `open.detachKey` is **the
|
|
541
|
-
|
|
542
|
-
|
|
998
|
+
- `open.detachKey` is **[the leader](#the-leader)**, `C-\` when you name
|
|
999
|
+
none. It is `oats tui`'s own and never reaches the agent or the kernel.
|
|
1000
|
+
It is read as a key wherever the TUI reads keys, so it may not be a key
|
|
1001
|
+
an action has: `C-l` is `redraw`'s `Ctrl+L`, `C-k` the palette's
|
|
1002
|
+
`Ctrl+K`, `C-j` is `Enter`. It is one of
|
|
543
1003
|
these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
|
|
544
1004
|
terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
|
|
545
1005
|
`]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
|
|
@@ -559,6 +1019,7 @@ guesses nothing. It refuses:
|
|
|
559
1019
|
| 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` |
|
|
560
1020
|
| has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
|
|
561
1021
|
| gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
|
|
1022
|
+
| 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` |
|
|
562
1023
|
| names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
|
|
563
1024
|
| names an action that does not exist | `unknown action …`, with the list of actions |
|
|
564
1025
|
| gives an action something that is not a list of strings | `… must be a list of key ids` |
|
|
@@ -594,6 +1055,15 @@ with the Desktop (`packages/client/`).
|
|
|
594
1055
|
read's. What a read in the background may reuse is the kernel's own look
|
|
595
1056
|
at the workspace's remotes, for up to 60 seconds; `r` asks the kernel to
|
|
596
1057
|
look again.
|
|
1058
|
+
- **The souls are one more read**, `oats souls --json` for the open
|
|
1059
|
+
workspace, by the same kernel, with 60 seconds and 4 MiB: only once [the
|
|
1060
|
+
Souls view](#the-souls-view) was shown, then only when the workspace
|
|
1061
|
+
changed, and on `r` there.
|
|
1062
|
+
- **A spawn's preview is one more read**, `oats spawn <soul> --preview
|
|
1063
|
+
--json` with the choices shown, by the same kernel, with 30 seconds: only
|
|
1064
|
+
while [the spawn prompt](#spawning-an-agent) is open, and again when a
|
|
1065
|
+
choice changes. An answer is reused for a minute, as the Desktop reuses
|
|
1066
|
+
it, until a spawn is applied or the workspace changes.
|
|
597
1067
|
- **The other machines are one more read**, `oats server roster --json`,
|
|
598
1068
|
by the same kernel: one answer for every machine registered on this
|
|
599
1069
|
machine. It has 60 seconds and 4 MiB.
|
|
@@ -639,31 +1109,72 @@ with the Desktop (`packages/client/`).
|
|
|
639
1109
|
`ps -o ppid= -p` (macOS). With neither (no `/proc`, and no `ps` or one
|
|
640
1110
|
that refuses `-p`, like BusyBox's), the keeper kills nothing. A normal
|
|
641
1111
|
end is not affected. An `oats tui` killed with SIGKILL can then leave
|
|
642
|
-
its private server running, with
|
|
643
|
-
attached to
|
|
1112
|
+
its private server running, with its tabs' viewers still
|
|
1113
|
+
attached to their agents, until you end it with `tmux -S
|
|
644
1114
|
<run directory>/tmux kill-server`. The next run's sweep leaves that
|
|
645
1115
|
directory alone while its socket answers.
|
|
646
1116
|
|
|
647
|
-
Each
|
|
648
|
-
with no shell between them.
|
|
1117
|
+
Each tab is a window of the server, whose process is the viewer itself,
|
|
1118
|
+
with no shell between them. Beside the keeper it holds up to four. Up
|
|
1119
|
+
to two are displayed, each group's shown tab ([Splits](#splits)), and
|
|
1120
|
+
every tab has its group's size: a resize resizes each tab's window in the
|
|
1121
|
+
groups drawn. Only the displayed tabs' panes are captured, and only the
|
|
1122
|
+
focused group's shown tab is typed into.
|
|
1123
|
+
|
|
1124
|
+
**A tab that is not drawn sends no output, from its mark on.** A hidden
|
|
1125
|
+
tab is heard until it prints: its first output captures nothing, sets its
|
|
1126
|
+
mark, and pauses its pane for `oats tui`'s control client
|
|
1127
|
+
(`refresh-client -A '%<pane>:pause'`, tmux 3.2 and later). From then on tmux sends none of
|
|
1128
|
+
that pane's output until the tab is displayed again, so a hidden agent
|
|
1129
|
+
that prints without pause costs one chunk of output each time its tab is
|
|
1130
|
+
hidden, and a quiet one nothing. The panel hidden as a whole (another
|
|
1131
|
+
view or an overlay over it, or the list alone under 80 columns) pauses
|
|
1132
|
+
its displayed tabs the same way. A
|
|
1133
|
+
paused pane is still read by the private server, so its screen stays
|
|
1134
|
+
current and its viewer never waits. A tab displayed again is continued
|
|
1135
|
+
(`:continue`) before it is captured: tmux restarts its output from where
|
|
1136
|
+
the pane is then, so the first frame is the pane's screen as it is, and
|
|
1137
|
+
nothing written meanwhile is replayed. `pause`, not `off`: from tmux 3.4
|
|
1138
|
+
on, a pane the control client has turned off is no longer read at all, so
|
|
1139
|
+
its viewer would stall and its screen go stale. Measured with a hidden tab
|
|
1140
|
+
printing without pause, `oats tui` takes about 0.4% of a core instead of
|
|
1141
|
+
11%, and the private server 9% instead of 14%.
|
|
1142
|
+
|
|
1143
|
+
The panel refuses a fifth open (`E_PANEL_FULL`, an open
|
|
1144
|
+
still under way counted) and a second open while one is under way
|
|
1145
|
+
(`E_PANEL_BUSY`); the TUI asks for neither, since it refuses such an open
|
|
1146
|
+
itself ([Tabs](#tabs)). It is closed with `kill-pane`, which hangs up
|
|
649
1147
|
the viewer's terminal: the viewer gets SIGHUP at once and removes its own
|
|
650
1148
|
session on the agents' server. The viewer's error output goes to a file
|
|
651
1149
|
of the run's directory (0600), read back when it ends and deleted. Its
|
|
652
1150
|
exit status is the one tmux keeps for a pane whose process ended
|
|
653
1151
|
(`remain-on-exit`), which the server reports to `oats tui` within a
|
|
654
|
-
second; `oats tui` then closes that pane.
|
|
1152
|
+
second; `oats tui` then closes that pane. tmux can report a pane ended
|
|
1153
|
+
before it has that status (3.4 does, when the viewer's terminal hangs up a
|
|
1154
|
+
moment before its process is reaped): `oats tui` then waits for the
|
|
1155
|
+
status, which follows at the next report, for ten seconds at most (2.5
|
|
1156
|
+
on tmux 3.2, which never says which signal ended a pane). A tmux built
|
|
1157
|
+
with libutempter can lose a status for good: as it destroys a pane at
|
|
1158
|
+
the hang-up, libutempter holds back SIGCHLD while its helper runs, and
|
|
1159
|
+
tmux, which reaps only on a SIGCHLD, leaves a viewer that exited in that
|
|
1160
|
+
moment unreaped (tmux 3.4). So while `oats tui` waits it sends the server
|
|
1161
|
+
`run-shell true` at once and every second: that child's end makes tmux
|
|
1162
|
+
reap the viewer too, and its status follows at the next report. A pane whose
|
|
1163
|
+
status has not come by then is taken as ended without one, and closed:
|
|
1164
|
+
the terminal closes with the line that the viewer ended without saying
|
|
1165
|
+
why. What the shown terminal
|
|
655
1166
|
shows is captured into `capture` in that directory, which the server
|
|
656
1167
|
writes and `oats tui` reads back, so nothing an agent prints passes
|
|
657
1168
|
through the stream on which `oats tui` reads the server's answers. An
|
|
658
|
-
answer the server would never give ends that stream, and
|
|
659
|
-
|
|
1169
|
+
answer the server would never give ends that stream, and every tab
|
|
1170
|
+
closes with it. The server is ended
|
|
660
1171
|
on every way out a process can handle. At its start a run also removes
|
|
661
1172
|
what a run that is gone left (below), and nothing else: it signals
|
|
662
1173
|
nothing.
|
|
663
1174
|
- **Every read runs in a session of its own** and is ended when the TUI
|
|
664
1175
|
ends, on every way out a process can handle (for SIGKILL see
|
|
665
|
-
[below](#what-it-changes-in-your-terminal-and-restores)).
|
|
666
|
-
|
|
1176
|
+
[below](#what-it-changes-in-your-terminal-and-restores)). Every tab's
|
|
1177
|
+
viewer ends with the private server. A read that was
|
|
667
1178
|
running when the TUI is suspended is dropped, not shown: its answer could
|
|
668
1179
|
arrive cut. That holds for the read of the other machines too. The return
|
|
669
1180
|
reads again.
|
|
@@ -683,9 +1194,24 @@ with the Desktop (`packages/client/`).
|
|
|
683
1194
|
writing to them), and the directory is removed. `oats tui` waits for an
|
|
684
1195
|
apply's answer for 10 minutes and for a start's for 60 seconds; then it
|
|
685
1196
|
says so, and the change goes on.
|
|
1197
|
+
- **A spawn runs the kernel's own `oats spawn`**, as the Desktop does: the
|
|
1198
|
+
prepare (a read, with the choices on screen) and then the apply of the
|
|
1199
|
+
decision on screen (`--expect-decision`, `--idempotency-key`), a change
|
|
1200
|
+
like the acts', with its output in the same directory. It has the
|
|
1201
|
+
deadline the shared apply gives it, as the Desktop's has: 60 seconds,
|
|
1202
|
+
more for each worktree setup a capability runs. Past it, the spawn is
|
|
1203
|
+
sent SIGTERM (by `oats tui`, through the shared apply), and on an OATS
|
|
1204
|
+
that rolls a spawn back on it, SIGKILL 20 seconds later if it still
|
|
1205
|
+
runs: the outcome is then not known, and `C` checks it. Those timers are
|
|
1206
|
+
the run's: once `oats tui` has gone, no deadline of a spawn it let go
|
|
1207
|
+
signals it, and none keeps the process waiting. The shared apply
|
|
1208
|
+
writes the task file `oats spawn --task-file` reads, empty, under the
|
|
1209
|
+
system's temporary directory (`oats-desktop-task-*`, mode 0600), and
|
|
1210
|
+
removes it when the spawn answers; a spawn let go on the way out leaves
|
|
1211
|
+
it.
|
|
686
1212
|
- It runs no other command that changes a deployment or a registration, and
|
|
687
1213
|
it writes no other file but the private server's: its socket `tmux`, the
|
|
688
|
-
keeper's FIFO `alive`, `capture` (the
|
|
1214
|
+
keeper's FIFO `alive`, `capture` (the shown terminal's screen, which the
|
|
689
1215
|
server writes there for `oats tui` to read), and `owner.json` (`{ "tool":
|
|
690
1216
|
"oats-tui", "pid": …, "started": … }`), which lets a later run tell a
|
|
691
1217
|
directory a run that is gone left. A run that ends normally removes all
|
|
@@ -698,7 +1224,8 @@ with the Desktop (`packages/client/`).
|
|
|
698
1224
|
| To | Run |
|
|
699
1225
|
|---|---|
|
|
700
1226
|
| start an agent with another harness or model | `oats session start --home <home>` with its options |
|
|
701
|
-
|
|
|
1227
|
+
| spawn an agent on another machine | `oats spawn <soul> --server <id>` |
|
|
1228
|
+
| spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
|
|
702
1229
|
| see capabilities | `oats capabilities` |
|
|
703
1230
|
| add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
|
|
704
1231
|
| check a machine | `oats server check <id>` |
|
|
@@ -717,12 +1244,17 @@ version:
|
|
|
717
1244
|
opened with `oats tui --dir <path>`.
|
|
718
1245
|
- **A row of another machine shows what its host reported at the last
|
|
719
1246
|
read,** not what is true at this moment. The time of that read is on the
|
|
720
|
-
machine's heading. A view of one machine
|
|
721
|
-
names the machine (`on garnet`) and
|
|
722
|
-
|
|
1247
|
+
machine's heading when it is not the header's time. A view of one machine
|
|
1248
|
+
has no heading: there the header names the machine (`on garnet`) and
|
|
1249
|
+
carries the time.
|
|
1250
|
+
- The Souls view lists a workspace of this machine's souls, and
|
|
1251
|
+
Capabilities, when it comes, is this machine's too.
|
|
723
1252
|
- There is no sorting and no mouse, and a deployment's heading cannot be
|
|
724
1253
|
folded. An open terminal has no scrollback but the viewer's own.
|
|
725
|
-
-
|
|
1254
|
+
- Up to four terminals are open at a time, as tabs, in at most two
|
|
1255
|
+
groups. The split cannot be resized or nested, a tab moves only between
|
|
1256
|
+
the two groups, and no tab or split is kept from one run to the next, or
|
|
1257
|
+
across a switch of workspace.
|
|
726
1258
|
- With an OATS older than 0.52.0, after an interrupted stop the instance can
|
|
727
1259
|
be started and then cannot be stopped while `.oats-stop-pending.json` exists
|
|
728
1260
|
in its home.
|
|
@@ -779,9 +1311,10 @@ suspends as one job.
|
|
|
779
1311
|
|
|
780
1312
|
**While an agent's terminal is open** the terminal stays `oats tui`'s: the
|
|
781
1313
|
viewer draws into the private server's pane, never into your terminal, and
|
|
782
|
-
`oats tui` draws what
|
|
783
|
-
the private server and with it
|
|
784
|
-
|
|
1314
|
+
`oats tui` draws what the displayed tabs' panes show. Every way out in the
|
|
1315
|
+
table above ends the private server and with it every tab's viewer, with
|
|
1316
|
+
that status. A suspend
|
|
1317
|
+
leaves the server and its viewers running; `fg` draws the terminal afresh.
|
|
785
1318
|
|
|
786
1319
|
`Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
|
|
787
1320
|
a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
|
|
@@ -794,9 +1327,9 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
|
|
|
794
1327
|
stayed in the alternate screen until `tput rmcup`. Nothing else is left in
|
|
795
1328
|
tmux: `oats tui` creates no session, window, option or key binding.
|
|
796
1329
|
Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
|
|
797
|
-
read that was in flight runs to its own end.
|
|
798
|
-
server is ended by its keeper as soon as `oats tui` is gone, so
|
|
799
|
-
terminal
|
|
1330
|
+
read that was in flight runs to its own end. The open terminals' private
|
|
1331
|
+
server is ended by its keeper as soon as `oats tui` is gone, so each tab's
|
|
1332
|
+
viewer has its terminal hung up and removes its own session. A stopped `oats tui`
|
|
800
1333
|
(`Ctrl+Z`, SIGSTOP) still holds the keeper's FIFO, so its server is left
|
|
801
1334
|
alone. The next run removes the directory that is left, with its `tmux`,
|
|
802
1335
|
`alive`, `capture` and `owner.json`.
|
|
@@ -843,13 +1376,16 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
843
1376
|
socket but to ask whether a dead run's still answers.
|
|
844
1377
|
- It starts no daemon, and writes no file but the output of a change and
|
|
845
1378
|
its private server's own, in its own directory
|
|
1379
|
+
([above](#what-it-reads-and-what-it-runs)), and a spawn's empty task file
|
|
846
1380
|
([above](#what-it-reads-and-what-it-runs)). The processes it starts are
|
|
847
1381
|
the reads above, when you open an agent its private tmux server and the
|
|
848
|
-
|
|
1382
|
+
viewers in it, one for each tab, and the acts you confirm. No read, server or viewer
|
|
849
1383
|
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
|
|
1384
|
+
in flight runs to its own end, and the private server and its viewers end
|
|
851
1385
|
by themselves. An act you confirmed is never ended by `oats tui`: it runs
|
|
852
|
-
to its own end.
|
|
1386
|
+
to its own end. A spawn is ended only at its deadline, while `oats tui`
|
|
1387
|
+
runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
|
|
1388
|
+
and never after it.
|
|
853
1389
|
|
|
854
1390
|
## Errors
|
|
855
1391
|
|