@awebai/oats 0.64.0 → 0.66.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/README.md +11 -5
- package/bin/oats.mjs +109 -11
- package/docs/desktop-cli-api.md +88 -5
- package/docs/desktop.md +14 -5
- package/docs/implementation.md +26 -3
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.65.0.md +187 -0
- package/docs/release-notes/v0.66.0.md +183 -0
- package/docs/servers.md +2 -2
- package/docs/tui.md +548 -249
- package/docs/upgrading.md +1 -1
- package/docs/workspaces.md +132 -1
- package/lib/core.mjs +14 -4
- package/lib/deployments.mjs +341 -0
- package/lib/resolved-deployment.mjs +37 -0
- package/lib/workspace.mjs +2 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-label.mjs +2 -2
- package/packages/client/deployment-list-cli.mjs +98 -0
- package/packages/client/deployment-list.mjs +91 -0
- package/packages/client/keymap.mjs +133 -0
- package/packages/client/machine-contract.mjs +1 -5
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/workspace-admission.mjs +2 -1
- package/packages/record/bin/setup.mjs +10 -2
- package/packages/record/docs/capture-service.md +45 -6
- package/packages/record/lib/capture-service-install.mjs +6 -95
- package/packages/record/lib/capture-setup-write.mjs +233 -0
- package/packages/tui/README.md +10 -9
- package/packages/tui/lib/actions.mjs +89 -64
- package/packages/tui/lib/client.mjs +4 -1
- package/packages/tui/lib/config.mjs +184 -36
- package/packages/tui/lib/main.mjs +161 -40
- package/packages/tui/lib/model.mjs +73 -41
- package/packages/tui/lib/read.mjs +15 -45
- package/packages/tui/lib/store.mjs +174 -40
- package/packages/tui/lib/term/keys.mjs +135 -33
- package/packages/tui/lib/term/kitty.mjs +198 -0
- package/packages/tui/lib/term/through.mjs +160 -24
- package/packages/tui/lib/term/tty.mjs +43 -12
- package/packages/tui/lib/views/act.mjs +17 -13
- package/packages/tui/lib/views/frame.mjs +418 -421
- package/packages/tui/lib/views/help.mjs +90 -29
- package/packages/tui/lib/views/instances.mjs +38 -9
- package/packages/tui/lib/views/switcher.mjs +65 -21
- package/skills/oats-getting-started/SKILL.md +102 -32
package/docs/tui.md
CHANGED
|
@@ -48,11 +48,27 @@ Another deployment is opened from [the switcher](#the-switcher), in the
|
|
|
48
48
|
same run.
|
|
49
49
|
|
|
50
50
|
**Outside every deployment.** Started with no `--dir` in a directory that
|
|
51
|
-
is in no deployment, it
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
51
|
+
is in no deployment, it reads this computer's list of deployments,
|
|
52
|
+
`oats deployments --json` ([This computer's
|
|
53
|
+
deployments](workspaces.md#this-computers-deployments)), through the kernel
|
|
54
|
+
it shipped with. When the list holds a row it starts with the switcher, and
|
|
55
|
+
nothing is open until you open a row. When the list holds none it prints
|
|
56
|
+
one line (`E_NO_DEPLOYMENT`) and exits 1 without touching the terminal, and
|
|
57
|
+
when the list cannot be read it prints the kernel's code and message
|
|
58
|
+
instead, which say what to do. With `--dir`, nothing is offered in place of
|
|
59
|
+
a path that is in no deployment: the `E_NO_DEPLOYMENT` line that names
|
|
60
|
+
`--dir`, and exit 1.
|
|
61
|
+
|
|
62
|
+
**Opening a deployment lists it.** The deployment a run starts in, from
|
|
63
|
+
where you are or from `--dir`, is added to this computer's list once, as the
|
|
64
|
+
TUI's (`oats deployments add <path> --via tui --json`), also when you had
|
|
65
|
+
removed it from the list. It is best effort: a failure opens nothing less,
|
|
66
|
+
and is said once, in the line under the title, in the kernel's words. When
|
|
67
|
+
it comes while the switcher, the help, a confirmation, the palette, the
|
|
68
|
+
spawn prompt, a detail or a terminal has the screen or the focus, it is said
|
|
69
|
+
once a view's list has the focus again, so no screen that covers the
|
|
70
|
+
sidebar hides it. A deployment opened from the switcher is
|
|
71
|
+
on the list already.
|
|
56
72
|
|
|
57
73
|
**From inside an agent's pane it still reads the deployment you asked
|
|
58
74
|
for.** An instance session carries variables that make a kernel command
|
|
@@ -79,44 +95,82 @@ runs.
|
|
|
79
95
|
## What it shows
|
|
80
96
|
|
|
81
97
|
```
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
>
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
98
|
+
acme-platform │ dev
|
|
99
|
+
│ soul dev
|
|
100
|
+
Instances 1 │ state running
|
|
101
|
+
> ● dev │ harness claude, claude-opus-5-5 (so…
|
|
102
|
+
│ work worktree, agents/dev
|
|
103
|
+
● reviewer !│ team eng
|
|
104
|
+
○ helper │ started 11:00
|
|
105
|
+
──────────────────────────────────────│ home …oy/agents/dev/instances/dev
|
|
106
|
+
Souls 2 │
|
|
107
|
+
Capabilities 3 │
|
|
108
|
+
──────────────────────────────────────│
|
|
109
|
+
Alt+O commands │
|
|
110
|
+
Ctrl+K palette │
|
|
111
|
+
Enter open │
|
|
112
|
+
n spawn │
|
|
113
|
+
? help │
|
|
114
|
+
q quit │
|
|
115
|
+
│
|
|
116
|
+
│
|
|
97
117
|
```
|
|
98
118
|
|
|
99
|
-
|
|
100
|
-
|
|
119
|
+
The screen is the sidebar on the left and the main area on the right, with
|
|
120
|
+
a rule between them over every row. There is no header and no footer. From
|
|
121
|
+
80 columns the sidebar takes about half the width (36 to 60 columns, 30
|
|
122
|
+
while a terminal is open); under 80 columns it has the whole width.
|
|
123
|
+
|
|
124
|
+
- **The title** is the sidebar's first row: the workspace's name, then what
|
|
125
|
+
the view holds of other machines. Beside a deployment of this machine the
|
|
101
126
|
other machines are counted: `+1 machine`, `+2 machines`. A view that holds
|
|
102
127
|
no deployment of this machine names its one machine, `on garnet`, or
|
|
103
|
-
counts them when there are two or more, `2 machines`.
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
128
|
+
counts them when there are two or more, `2 machines`. While
|
|
129
|
+
[the switcher](#the-switcher) is shown the title is `workspaces`.
|
|
130
|
+
- **Under the title** stands what the view needs to say first, wrapped to
|
|
131
|
+
the sidebar's width: a deployment's state when it is not live, with
|
|
132
|
+
`since …` and its reason on rows of its own; the note of a view of one
|
|
133
|
+
deployment; and the line that says what happened after an open, an act or
|
|
134
|
+
a spawn. Then an empty row.
|
|
135
|
+
- **The views** follow as an accordion, always in this order: `Instances`,
|
|
136
|
+
`Souls`, `Capabilities`, each with its key dim at the right edge. The open
|
|
137
|
+
view's heading is bold and its list stands under it, with a rule between
|
|
138
|
+
it and the views before and after it. `1`, `2` and `3` open them in the
|
|
139
|
+
list, and [the leader](#the-leader) then `1`, `2` or `3` from anywhere;
|
|
140
|
+
the leader's hint, [the palette](#the-palette) and the help name those
|
|
141
|
+
keys. [The Souls view](#the-souls-view) lists the open workspace's souls,
|
|
142
|
+
and [the Capabilities view](#the-capabilities-view) its capabilities. A
|
|
143
|
+
workspace with no instances reads `No agents yet: n spawns one`, with the
|
|
144
|
+
key `spawn` has (`No agents yet.` when it has none).
|
|
145
|
+
- **The cheat sheet** comes last, under a rule: a few keys, one per row,
|
|
146
|
+
the key in bold and what it does beside it. Its first row is always the
|
|
147
|
+
leader, `Alt+O commands`, which reaches every action; then
|
|
148
|
+
`Ctrl+K palette`. In a view's list it names what `Enter` does now
|
|
149
|
+
(`open`, `focus terminal` on the row whose terminal is open, `detail`
|
|
150
|
+
in the Souls and Capabilities views), then `n spawn` where it spawns,
|
|
151
|
+
and `? help` and `q quit` last; with the detail's focus `Tab back`
|
|
152
|
+
comes before `Enter`. The other keys (the acts, `/`, `Tab`, `r`, `w`,
|
|
153
|
+
and a terminal's `z`, `c`, `[` and `]`) are not listed there:
|
|
154
|
+
the leader's hint, the palette and the help name them. While the
|
|
155
|
+
terminal has the focus, in an overlay and in the filter field it names
|
|
156
|
+
the keys that work them. While the leader waits for its key the rows are
|
|
157
|
+
the leader's hint.
|
|
158
|
+
Everything flows from the top, so empty rows are at the bottom. On a
|
|
159
|
+
short screen the list keeps its rows first: the cheat sheet gives up rows
|
|
160
|
+
from its end, down to the leader alone, then the empty row under the
|
|
161
|
+
title goes, and the list scrolls in what is left.
|
|
162
|
+
- **The main area** holds the selected row's detail, an
|
|
163
|
+
[open terminal](#open-an-agents-terminal), or an overlay: the switcher,
|
|
164
|
+
the palette, the spawn prompt, the help or a confirmation. From 80
|
|
165
|
+
columns an overlay covers the main area and the sidebar stays beside it,
|
|
166
|
+
its cheat sheet naming the overlay's keys. Under 80 columns the detail
|
|
167
|
+
and every overlay cover the whole screen, and their first row carries
|
|
168
|
+
their keys at the right, dim: the detail's `Tab back` first.
|
|
169
|
+
- **The counts and the time of the read are not on the screen.** The help's
|
|
170
|
+
top row has the time of the read of this machine that the screen shows,
|
|
171
|
+
`read 14:03:27`, which moves with every read, and how many rows the
|
|
172
|
+
kernel reported that were withheld (a home outside its soul's directory,
|
|
173
|
+
or one reported twice), `2 withheld`, when there are any.
|
|
120
174
|
- **The list** is the roster the Desktop draws: the same groups in the same
|
|
121
175
|
order, from the same code. It is in name order, by each group's top
|
|
122
176
|
instance, so starting or stopping an instance moves nothing. An instance
|
|
@@ -132,7 +186,11 @@ runs.
|
|
|
132
186
|
state of a home a spawn or a retire holds (`Retire didn't finish`), or
|
|
133
187
|
the shared words for why an instance cannot be reached or opened:
|
|
134
188
|
`gone from garnet`, `garnet not reached`, `not reachable on garnet`,
|
|
135
|
-
`Herdr no longer supported`, `state unknown`.
|
|
189
|
+
`Herdr no longer supported`, `state unknown`. The words stand in a
|
|
190
|
+
column of their own. The name comes first: on a narrow sidebar, where
|
|
191
|
+
the column would leave the name less than 16 cells, the word is cut to
|
|
192
|
+
what the name leaves, or left out when that is under 6 cells; the mark
|
|
193
|
+
and the detail still say it.
|
|
136
194
|
- **The detail** shows the selected instance: its soul, its state, and
|
|
137
195
|
under it the reason when there is one, after the words that say who gave
|
|
138
196
|
it: `OATS says:` for a kernel (this machine's, or the instance's
|
|
@@ -150,10 +208,10 @@ runs.
|
|
|
150
208
|
link, either way, as the Desktop reads them: `sibling of a`, `sibling of
|
|
151
209
|
a and b`, `sibling of a, b and c`. They are read inside the instance's
|
|
152
210
|
own deployment, and a name that is no instance there, or two of them, is
|
|
153
|
-
not shown. From 80 columns up it stands beside the
|
|
154
|
-
terminal `Tab` opens it as a page.
|
|
211
|
+
not shown. From 80 columns up it stands beside the sidebar; on a narrower
|
|
212
|
+
terminal `Tab` opens it as a page over the whole screen.
|
|
155
213
|
- **Opening an agent.** `Enter` on an instance that runs opens its terminal
|
|
156
|
-
beside the
|
|
214
|
+
beside the sidebar, where the detail was, as a tab: see
|
|
157
215
|
[Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
|
|
158
216
|
|
|
159
217
|
**A view of more than one deployment** (this machine and another, or two
|
|
@@ -165,9 +223,9 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
|
|
|
165
223
|
view. A heading cannot be selected or folded: the movement keys pass over
|
|
166
224
|
it. A view of one deployment has no heading.
|
|
167
225
|
- **A machine's heading is its name.** When its rows were read at another
|
|
168
|
-
time than the one
|
|
169
|
-
heading: `read 14:03:21`. A row of another
|
|
170
|
-
reported at that time.
|
|
226
|
+
time than this machine's (the one on the help's top row), that time
|
|
227
|
+
stands at the right of the heading: `read 14:03:21`. A row of another
|
|
228
|
+
machine shows what its host reported at that time.
|
|
171
229
|
- **A deployment that is not live carries its state and a short reason**
|
|
172
230
|
on its heading, and no time: `garnet remembered Not reached`. The rows
|
|
173
231
|
a machine last reported are kept when it is not reached, and each of them
|
|
@@ -187,21 +245,21 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
|
|
|
187
245
|
deployment, such as `garnet now reports workspace other.` for a machine
|
|
188
246
|
that reported another workspace before, or that a deployment's teams are
|
|
189
247
|
local only. It stands under the deployment's heading. In a view of one
|
|
190
|
-
deployment, which has no heading, it stands
|
|
248
|
+
deployment, which has no heading, it stands under the title.
|
|
191
249
|
- **The detail has a `machine` line**, the machine the selected instance is
|
|
192
250
|
on. When that deployment is not live, the whole sentence that says why
|
|
193
251
|
follows it.
|
|
194
252
|
|
|
195
|
-
**A view that holds no deployment of this machine** says so in its
|
|
253
|
+
**A view that holds no deployment of this machine** says so in its title:
|
|
196
254
|
`other on garnet` for one machine, `2 machines` after the name for
|
|
197
|
-
two or more. The time
|
|
198
|
-
were read. A view of one machine has no heading, so its state, when it
|
|
199
|
-
not live, is said
|
|
200
|
-
this machine. When no row of that machine is kept either, nothing is drawn
|
|
255
|
+
two or more. The time on the help's top row is then the time the machines'
|
|
256
|
+
rows were read. A view of one machine has no heading, so its state, when it
|
|
257
|
+
is not live, is said under the title with the reason, as for a deployment
|
|
258
|
+
of this machine. When no row of that machine is kept either, nothing is drawn
|
|
201
259
|
under the reason: no list and no detail.
|
|
202
260
|
|
|
203
261
|
**A machine that has not answered in this run is not in its workspace's
|
|
204
|
-
list.** `oats tui` keeps nothing on disk, so it cannot tell which workspace
|
|
262
|
+
list.** `oats tui` keeps nothing on disk of its own, so it cannot tell which workspace
|
|
205
263
|
a machine belongs to before the machine has said so in this run. Such a
|
|
206
264
|
machine is listed in [the switcher](#the-switcher) by its own name, under
|
|
207
265
|
`Not matched to a workspace`. The OATS Desktop, which remembers what each
|
|
@@ -248,7 +306,7 @@ last rows stay as they were; or they stay and are marked `stale`, with the
|
|
|
248
306
|
time of the last read that succeeded (a remote that could not be read
|
|
249
307
|
again); or the
|
|
250
308
|
deployment is `not observed` and no row is drawn. A state that is not live
|
|
251
|
-
is said in words
|
|
309
|
+
is said in words under the title, with the reason on rows of its own. When
|
|
252
310
|
the kernel refused the read and no rows are kept, the reason says so and
|
|
253
311
|
quotes it: `OATS answered with an error (<code>). It says: <message>`. When
|
|
254
312
|
the last rows are kept as `stale`, the reason says so and then quotes the
|
|
@@ -274,53 +332,65 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
274
332
|
## Open an agent's terminal
|
|
275
333
|
|
|
276
334
|
```
|
|
277
|
-
acme-platform
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
> ● backend-lead │
|
|
281
|
-
● docs-writer
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
335
|
+
acme-platform │ backend-lead
|
|
336
|
+
│$ make docs
|
|
337
|
+
Instances 1 │Building the reference...
|
|
338
|
+
> ● backend-lead │
|
|
339
|
+
● docs-writer │
|
|
340
|
+
──────────────────────────────│
|
|
341
|
+
Souls 2 │
|
|
342
|
+
Capabilities 3 │
|
|
343
|
+
──────────────────────────────│
|
|
344
|
+
Alt+O commands │
|
|
345
|
+
Alt+O Esc the list │
|
|
346
|
+
Alt+O Alt+O types Alt+O │
|
|
286
347
|
```
|
|
287
348
|
|
|
288
349
|
- **`Enter` on an instance that runs** opens its terminal on the right of
|
|
289
|
-
the
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
terminal is open the
|
|
350
|
+
the sidebar, where the detail was, over every row. Its top row names the
|
|
351
|
+
agent (and `on <machine>` for one of another machine); under it is the
|
|
352
|
+
agent's screen, as the agent draws it, in its own colours. While a
|
|
353
|
+
terminal is open the sidebar keeps 30 columns at most, also while the
|
|
293
354
|
detail stands in the terminal's place, and a name longer than its row is
|
|
294
355
|
cut with `…` (`...` in ASCII).
|
|
295
356
|
- **The terminal has the focus.** What you type, what you paste and every
|
|
296
357
|
key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
|
|
297
|
-
among them, but for **[the leader](#the-leader)** (`Ctrl+\`
|
|
298
|
-
[`tui.json`](#change-the-keys-tuijson) names another), the
|
|
299
|
-
TUI takes from the agent
|
|
300
|
-
|
|
301
|
-
the
|
|
302
|
-
|
|
303
|
-
|
|
358
|
+
among them, but for **[the leader](#the-leader)** (`Alt+O`, `Ctrl+\` on
|
|
359
|
+
macOS, unless [`tui.json`](#change-the-keys-tuijson) names another), the
|
|
360
|
+
one key the TUI takes from the agent, and the [chords](#chords) while your
|
|
361
|
+
terminal sends them. Under the kitty keyboard protocol every key reaches
|
|
362
|
+
the agent as the bytes it sends without it. The leader then `Esc` gives the
|
|
363
|
+
focus to the list; the leader twice types the leader into the agent; the
|
|
364
|
+
leader then another key does what that key does from anywhere. While the
|
|
365
|
+
terminal has the focus the cheat sheet names those three:
|
|
366
|
+
`Alt+O commands`, `Alt+O Esc the list`, `Alt+O Alt+O types Alt+O`. A
|
|
367
|
+
leader inside a bracketed paste is pasted, not taken.
|
|
304
368
|
- **With the list focused** the terminal stays open, and the agent's screen
|
|
305
|
-
is still drawn as it changes. The
|
|
306
|
-
|
|
369
|
+
is still drawn as it changes. The cheat sheet names `Enter focus terminal`
|
|
370
|
+
on its row; the leader's hint names `z zoom` and `w close terminal`.
|
|
307
371
|
- `Enter` on the shown terminal's row gives it the focus again.
|
|
308
|
-
- `z` gives it the focus and the whole
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
- `c` closes it
|
|
312
|
-
with no other tab the right side
|
|
372
|
+
- `z` gives it the focus and the whole screen: the sidebar is hidden. The
|
|
373
|
+
leader then `Esc` brings the sidebar back beside it, and the leader then
|
|
374
|
+
`z` zooms it out and in without leaving it.
|
|
375
|
+
- `c` closes it, and the leader then `w` from anywhere: the agent keeps
|
|
376
|
+
running. The tab beside it is shown; with no other tab the right side
|
|
377
|
+
is the detail again.
|
|
313
378
|
- `Tab` shows the detail in its place until `Tab` or `Esc`. Nothing of
|
|
314
379
|
the terminal is drawn meanwhile, and its screen is read afresh when it
|
|
315
380
|
shows again.
|
|
316
381
|
- **Up to four terminals are open at a time, each a tab.** `Enter` on
|
|
317
382
|
another instance that runs opens its terminal in a new tab, and the
|
|
318
383
|
others stay open: see [Tabs](#tabs).
|
|
319
|
-
- **Under 80 columns** the terminal is always shown with the whole
|
|
320
|
-
when it has the focus. With the list focused the
|
|
321
|
-
terminal stays open, unseen, and `Enter focus terminal` in the
|
|
322
|
-
shows it again. Beside the
|
|
323
|
-
columns.
|
|
384
|
+
- **Under 80 columns** the terminal is always shown with the whole screen
|
|
385
|
+
when it has the focus. With the list focused the sidebar is shown alone;
|
|
386
|
+
the terminal stays open, unseen, and `Enter focus terminal` in the cheat
|
|
387
|
+
sheet shows it again. Beside the sidebar the terminal is never narrower
|
|
388
|
+
than 40 columns: with less room it has the whole screen too.
|
|
389
|
+
- **With the whole screen** (zoomed, or a narrow terminal) no cheat sheet is
|
|
390
|
+
drawn. The terminal's title row carries the keys at its right, dim:
|
|
391
|
+
`Alt+O commands Alt+O Esc the list`, and while the leader waits, the
|
|
392
|
+
leader's hint, as many keys as fit, `Esc the list` last. The agent's
|
|
393
|
+
screen keeps every row under it.
|
|
324
394
|
- **A terminal also closes by itself** when its viewer ends, shown or
|
|
325
395
|
hidden ([which tab is shown then](#tabs)): the agent's
|
|
326
396
|
window ended, its session went away, or the link to its machine dropped.
|
|
@@ -331,7 +401,7 @@ C-\ commands C-\ C-\ back to the list
|
|
|
331
401
|
terminal without it when it has not come. A tmux built with libutempter
|
|
332
402
|
(Ubuntu's and Debian's are) can lose that status: while it waits,
|
|
333
403
|
`oats tui` has tmux look for it again once a second, so the terminal
|
|
334
|
-
still closes within a second or two with the line its status calls for. The instances are then read again at once, and
|
|
404
|
+
still closes within a second or two with the line its status calls for. The instances are then read again at once, and the line under the title
|
|
335
405
|
says what happened: that it could not be opened, that the connection to
|
|
336
406
|
its machine ended, or that the viewer ended without saying why. What the
|
|
337
407
|
viewer printed on its error output stands under that line in quotation
|
|
@@ -360,15 +430,19 @@ C-\ commands C-\ C-\ back to the list
|
|
|
360
430
|
## Tabs
|
|
361
431
|
|
|
362
432
|
```
|
|
363
|
-
acme-platform
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
> ● backend-lead │
|
|
367
|
-
● docs-writer
|
|
368
|
-
● qa-runner │
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
433
|
+
acme-platform │ backend-lead docs-writer• qa-runner
|
|
434
|
+
│$ make test
|
|
435
|
+
Instances 1 │ok 41 of 41
|
|
436
|
+
> ● backend-lead │
|
|
437
|
+
● docs-writer │
|
|
438
|
+
● qa-runner │
|
|
439
|
+
──────────────────────────────│
|
|
440
|
+
Souls 2 │
|
|
441
|
+
Capabilities 3 │
|
|
442
|
+
──────────────────────────────│
|
|
443
|
+
Alt+O commands │
|
|
444
|
+
Alt+O Esc the list │
|
|
445
|
+
Alt+O Alt+O types Alt+O │
|
|
372
446
|
```
|
|
373
447
|
|
|
374
448
|
Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
@@ -400,16 +474,15 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
400
474
|
machine is asked whether it can be opened, another open does nothing,
|
|
401
475
|
and neither does a key that shows another tab.
|
|
402
476
|
- **At four tabs nothing closes by itself.** The open does nothing, and
|
|
403
|
-
the line
|
|
477
|
+
the line under the title says `4 terminals are open; close one with Alt+O w.`
|
|
404
478
|
(with your leader, when [`tui.json`](#change-the-keys-tuijson) names
|
|
405
479
|
another). A tab still starting, and an agent of another machine while
|
|
406
480
|
it is asked, hold a place among the four. An instance that cannot be
|
|
407
481
|
opened says why, as it does with no tab open.
|
|
408
482
|
- **Switching.** `[` and `]` in the Instances view, from the list or the
|
|
409
|
-
detail, show the tab before or after the shown one; the
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
`detail`. The leader then
|
|
483
|
+
detail, show the tab before or after the shown one; the help names them,
|
|
484
|
+
and the leader's hint names the leader's own while two tabs or more are
|
|
485
|
+
open. The leader then
|
|
413
486
|
`Left` or `Right` does the same from any focus, and from another view
|
|
414
487
|
goes to the Instances view first.
|
|
415
488
|
- The strip does not wrap: on the first tab `[` does nothing, and on the
|
|
@@ -433,13 +506,13 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
433
506
|
- Closing the last tab closes the panel: the right side is the detail
|
|
434
507
|
again, and the list has the focus.
|
|
435
508
|
- **A tab that closes by itself**, when its viewer ends, says so on the line
|
|
436
|
-
|
|
509
|
+
under the title in the words [above](#open-an-agents-terminal), for that
|
|
437
510
|
tab's agent (no line when it ended cleanly).
|
|
438
511
|
- The shown tab: the tab to its right is shown, else the one to its left,
|
|
439
512
|
and the list takes the focus.
|
|
440
513
|
- A hidden tab: the shown tab and the focus stay as they were.
|
|
441
|
-
- **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole
|
|
442
|
-
The strip stays its top row, and the other tabs stay open.
|
|
514
|
+
- **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole
|
|
515
|
+
screen. The strip stays its top row, and the other tabs stay open.
|
|
443
516
|
- **The tabs are the open workspace's.** Opening another workspace in
|
|
444
517
|
[the switcher](#the-switcher) closes them all, and so does the open
|
|
445
518
|
workspace no longer being listed; their agents keep running. Coming back
|
|
@@ -448,15 +521,19 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
|
|
|
448
521
|
## Splits
|
|
449
522
|
|
|
450
523
|
```
|
|
451
|
-
acme-platform
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
● backend-lead │
|
|
455
|
-
● docs-writer
|
|
456
|
-
> ● qa-runner │
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
524
|
+
acme-platform │ backend-lead docs-writer │ qa-runner
|
|
525
|
+
│$ git log --oneline -2 │$ make test
|
|
526
|
+
Instances 1 │4be1c0d Fix the reader │ok 41 of 41
|
|
527
|
+
● backend-lead │9a03e7f Add the roster │
|
|
528
|
+
● docs-writer │ │
|
|
529
|
+
> ● qa-runner │ │
|
|
530
|
+
──────────────────────────────│ │
|
|
531
|
+
Souls 2 │ │
|
|
532
|
+
Capabilities 3 │ │
|
|
533
|
+
──────────────────────────────│ │
|
|
534
|
+
Alt+O commands │ │
|
|
535
|
+
Alt+O Esc the list │ │
|
|
536
|
+
Alt+O Alt+O types Alt+O │ │
|
|
460
537
|
```
|
|
461
538
|
|
|
462
539
|
The panel can be split in two **groups**, side by side or one above the
|
|
@@ -469,9 +546,9 @@ tab and the marks of its hidden ones.
|
|
|
469
546
|
(left, or top). The second group starts empty and is the focused group.
|
|
470
547
|
- A split needs a tab open, and none starting.
|
|
471
548
|
- **There are at most two groups.** With two, the split keys do nothing,
|
|
472
|
-
and the line
|
|
549
|
+
and the line under the title says `The panel has two groups already.`
|
|
473
550
|
- **Each group needs 40 columns side by side, and 8 rows one above the
|
|
474
|
-
other**, its strip counted. The panel beside the
|
|
551
|
+
other**, its strip counted. The panel beside the sidebar then needs 81
|
|
475
552
|
columns (a terminal of 112), or 17 rows. A split that would leave a
|
|
476
553
|
group smaller does nothing, and the line says so:
|
|
477
554
|
`No room to split side by side: each group needs 40 columns.` or
|
|
@@ -490,10 +567,10 @@ tab and the marks of its hidden ones.
|
|
|
490
567
|
it. **When the terminal becomes too small for both groups,** the split
|
|
491
568
|
stays and the focused group is drawn alone; the other group's shown tab
|
|
492
569
|
is not drawn, only marked, until there is room again.
|
|
493
|
-
- **Under 80 columns** the terminal's focus gives the whole
|
|
494
|
-
groups, and the list's focus shows the
|
|
570
|
+
- **Under 80 columns** the terminal's focus gives the whole screen to both
|
|
571
|
+
groups, and the list's focus shows the sidebar alone, as with one group.
|
|
495
572
|
- **Zoom** (`z`, or the leader then `z`) gives the focused group's shown
|
|
496
|
-
terminal the whole
|
|
573
|
+
terminal the whole screen, and the same key brings the split back. With
|
|
497
574
|
the empty group focused it does nothing.
|
|
498
575
|
- **Opening.** `Enter`, the palette, the leader then `Up`/`Down` and a
|
|
499
576
|
spawn open as with one group:
|
|
@@ -502,7 +579,7 @@ tab and the marks of its hidden ones.
|
|
|
502
579
|
- any other: a new tab in the focused group, after its shown tab, or as
|
|
503
580
|
the first tab of the empty group.
|
|
504
581
|
- **The four tabs are counted across both groups.** At four, the line
|
|
505
|
-
says `4 terminals are open; close one with
|
|
582
|
+
says `4 terminals are open; close one with Alt+O w.` as with one group.
|
|
506
583
|
- **Moving between the groups.** The leader then `Tab` from a terminal goes
|
|
507
584
|
to the other group's shown terminal, or to the other group when it is
|
|
508
585
|
empty. From the list it goes to the focused group's terminal, or, with
|
|
@@ -537,14 +614,23 @@ ones `oats spawn` can make an instance of here, as the OATS Desktop lists
|
|
|
537
614
|
them, from the same code.
|
|
538
615
|
|
|
539
616
|
```
|
|
540
|
-
acme-platform
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
617
|
+
acme-platform │ dev
|
|
618
|
+
│ Builds and ships the platform.
|
|
619
|
+
Instances 1 │ from oats-core
|
|
620
|
+
──────────────────────────────────────│ works works in its own worktree
|
|
621
|
+
Souls 2 │ harness
|
|
622
|
+
> ■ dev ·2 │ No default harness: you choose one
|
|
623
|
+
■ ops ! │ when you launch it.
|
|
624
|
+
■ reviewer ·1 │ instances here
|
|
625
|
+
──────────────────────────────────────│ ● dev-1 ● dev-2
|
|
626
|
+
Capabilities 3 │ i shows them in the Instances view.
|
|
627
|
+
──────────────────────────────────────│
|
|
628
|
+
Alt+O commands │
|
|
629
|
+
Ctrl+K palette │
|
|
630
|
+
Enter detail │
|
|
631
|
+
n spawn │
|
|
632
|
+
? help │
|
|
633
|
+
q quit │
|
|
548
634
|
```
|
|
549
635
|
|
|
550
636
|
- **A row** is the soul's colour mark (`■`, `#` in ASCII; its colour is the
|
|
@@ -559,10 +645,10 @@ them, from the same code.
|
|
|
559
645
|
problem as the kernel reports it); its teams, the default first; its
|
|
560
646
|
capabilities; and its instances on this machine, eight at most and then
|
|
561
647
|
`+n`. `Enter` gives the detail the focus (under 80 columns it takes the
|
|
562
|
-
|
|
648
|
+
whole screen), and the movement keys then scroll it.
|
|
563
649
|
- **`i`**, or `Enter` in the detail, shows that soul's instances in the
|
|
564
|
-
Instances view: an exact filter,
|
|
565
|
-
the
|
|
650
|
+
Instances view: an exact filter, named where a kept filter stands, on
|
|
651
|
+
the view's heading: `Instances soul dev`.
|
|
566
652
|
An instance of another soul whose name holds `dev` is not listed. `Esc`
|
|
567
653
|
clears it, and `/` replaces it with a text filter.
|
|
568
654
|
- **`r`** reads the souls again; while a read is under way it starts
|
|
@@ -593,25 +679,26 @@ the ones its repositories and its packages offer, as the OATS Desktop lists
|
|
|
593
679
|
them, from the same code.
|
|
594
680
|
|
|
595
681
|
```
|
|
596
|
-
acme-platform
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
682
|
+
acme-platform │ aweb Messaging
|
|
683
|
+
│ Messaging over aweb, mail and chat,
|
|
684
|
+
Instances 1 │ for every instance of the workspace.
|
|
685
|
+
Souls 2 │
|
|
686
|
+
──────────────────────────────────────│ Comes from
|
|
687
|
+
Capabilities 3 │ Repository oats
|
|
688
|
+
Workspace owned │ Latest bbbbbbb
|
|
689
|
+
oats · member repo · host │ Path capabilities/aweb
|
|
690
|
+
> aweb Messaging │
|
|
691
|
+
tools · member repo │ Provides
|
|
692
|
+
notes │ Skills oats-aweb, aweb-messaging
|
|
693
|
+
Packages │ Hooks SessionStart
|
|
694
|
+
oats-okf · package · v1.2.0 │
|
|
695
|
+
okf-knowledge Knowledge │ Used by 2 souls
|
|
696
|
+
──────────────────────────────────────│ ■ dev ·2 · 1 on an older version
|
|
697
|
+
Alt+O commands │ ■ reviewer ·1
|
|
698
|
+
Ctrl+K palette │
|
|
699
|
+
Enter detail │
|
|
700
|
+
? help │
|
|
701
|
+
q quit │
|
|
615
702
|
```
|
|
616
703
|
|
|
617
704
|
- **The list** is in the Desktop's sections: Workspace owned, Repo owned
|
|
@@ -647,7 +734,7 @@ them, from the same code.
|
|
|
647
734
|
`Reading souls…`, and a read of them that fails says why, in the
|
|
648
735
|
warning style.
|
|
649
736
|
- **`Enter`** gives the detail the focus (under 80 columns it takes the
|
|
650
|
-
|
|
737
|
+
whole screen), with a mark, `>` in reverse video, on the first soul of
|
|
651
738
|
Used by. `Up` and `Down` move the mark among the listed souls, and the
|
|
652
739
|
detail scrolls to keep it in sight. Past the first or the last soul, and
|
|
653
740
|
with the other movement keys, the detail scrolls; with no soul listed
|
|
@@ -680,25 +767,25 @@ selected.
|
|
|
680
767
|
|
|
681
768
|
## The switcher
|
|
682
769
|
|
|
683
|
-
`w` opens the switcher: what this run can show, over the
|
|
684
|
-
|
|
770
|
+
`w` opens the switcher: what this run can show, over the main area. The
|
|
771
|
+
sidebar's title says `workspaces` and no view is open; under 80 columns the
|
|
772
|
+
switcher covers the whole screen.
|
|
685
773
|
|
|
686
774
|
```
|
|
687
|
-
workspaces
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
C-\ commands Enter open / filter r refresh Esc close ? help q quit
|
|
775
|
+
workspaces │ > * acme-platform This machine · garnet
|
|
776
|
+
│ ledger quartz
|
|
777
|
+
Instances 1 │ Not matched to a workspace
|
|
778
|
+
Souls 2 │ basalt ssh needs a prompt
|
|
779
|
+
Capabilities 3 │ On this machine, not opened
|
|
780
|
+
────────────────────────────────────────────────│ acme-docs ~/acme-docs
|
|
781
|
+
Alt+O commands │ sandbox Not found.
|
|
782
|
+
Ctrl+K palette │
|
|
783
|
+
Enter open │
|
|
784
|
+
/ filter │
|
|
785
|
+
r refresh │
|
|
786
|
+
Esc close │
|
|
787
|
+
? help │
|
|
788
|
+
q quit │
|
|
702
789
|
```
|
|
703
790
|
|
|
704
791
|
It lists, in this order:
|
|
@@ -712,27 +799,63 @@ It lists, in this order:
|
|
|
712
799
|
- **`Not matched to a workspace`**: what those rules matched to no
|
|
713
800
|
workspace, each by its own name with a short reason. A machine that has
|
|
714
801
|
not answered in this run is listed here.
|
|
715
|
-
- **`On this machine, not opened`**: the
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
802
|
+
- **`On this machine, not opened`**: the rows of this computer's list of
|
|
803
|
+
deployments (`oats deployments`) that this run has not opened, in the
|
|
804
|
+
list's order, each by its folder's name and its path. Nothing is read from
|
|
805
|
+
one before it is picked. A row that cannot be opened says why where its
|
|
806
|
+
path stood, and does not open:
|
|
807
|
+
|
|
808
|
+
| The row says | The list's state |
|
|
809
|
+
|---|---|
|
|
810
|
+
| `Not found.` | `missing`: the folder is gone, or on a volume that is not mounted |
|
|
811
|
+
| `Not an OATS deployment any more.` | `not-a-deployment`: the folder has no `oats-local.yaml` |
|
|
812
|
+
| `Can't be read.` | `unreadable`: the check failed, for example for a permission |
|
|
813
|
+
|
|
814
|
+
The list is read when the switcher opens, on `r` in it and after a
|
|
815
|
+
Remove. When a read fails, the rows of the last read stay, under a line
|
|
816
|
+
that says the list could not be read, with the kernel's message.
|
|
720
817
|
|
|
721
818
|
| Key | Does |
|
|
722
819
|
|---|---|
|
|
723
820
|
| `Up` `k`, `Down` `j`, `g` `Home`, `G` `End`, `PageUp`, `PageDown` | move the selection among the rows; a heading is passed over |
|
|
724
821
|
| `Enter` | opens the selected row |
|
|
725
822
|
| `/` | filters the rows by what they show: a name, the machines, a path |
|
|
726
|
-
| `r` | reads now, and
|
|
727
|
-
| `
|
|
823
|
+
| `r` | reads now, and reads this computer's list of deployments again |
|
|
824
|
+
| `Delete` | on a row of `On this machine, not opened`, asks whether to remove it from this computer's list; the cheat sheet names it while such a row is selected |
|
|
825
|
+
| `Esc` | while a Remove is asked, keeps the row; else clears a kept filter; else closes the switcher, back to the view that was open |
|
|
728
826
|
| `1` | closes the switcher, back to the view that was open |
|
|
729
827
|
|
|
730
|
-
**Enter on a workspace** opens its view. **Enter on a
|
|
731
|
-
deployment in this run: from then on it is read with the others,
|
|
732
|
-
workspace is the open view. A folder that stopped being a deployment
|
|
733
|
-
|
|
828
|
+
**Enter on a workspace** opens its view. **Enter on a row of the list**
|
|
829
|
+
opens that deployment in this run: from then on it is read with the others,
|
|
830
|
+
and its workspace is the open view. A folder that stopped being a deployment
|
|
831
|
+
since the list was read is not opened: its row says
|
|
734
832
|
`Not an OATS deployment any more.` where its path stood.
|
|
735
833
|
|
|
834
|
+
**Remove** takes a row off this computer's list
|
|
835
|
+
(`oats deployments remove <path>`); nothing on disk is touched, and the
|
|
836
|
+
folder stays. `Delete` on the row asks first, above the rows:
|
|
837
|
+
|
|
838
|
+
```
|
|
839
|
+
Remove the selected row from this computer's list?
|
|
840
|
+
Enter removes it; other keys keep it. Its folder stays.
|
|
841
|
+
```
|
|
842
|
+
|
|
843
|
+
`Enter` removes it, and the list is read again; `Esc`, or any other key,
|
|
844
|
+
keeps it (the other key then does what it does). These are the keys
|
|
845
|
+
themselves, whatever your `tui.json` gives `open` and `close`. The question
|
|
846
|
+
is about the row marked when it was asked: when a read of the list no longer
|
|
847
|
+
holds that row, the question goes. An `Enter` that came in
|
|
848
|
+
the same read of input as the `Delete` is not taken. What the kernel
|
|
849
|
+
answered stands above the rows: that the row was removed, or why it was not,
|
|
850
|
+
in the kernel's words. A removed deployment is not listed again by the
|
|
851
|
+
kernel on its own; opening it with `oats tui --dir <path>` lists it again.
|
|
852
|
+
A workspace this run has open has no Remove here.
|
|
853
|
+
|
|
854
|
+
`Delete` is the key and no letter is: a new default key that your
|
|
855
|
+
[`tui.json`](#change-the-keys-tuijson) already gives to another action
|
|
856
|
+
would make the file refused at the start. To use another key, give it to
|
|
857
|
+
`remove` there, for example `{ "keys": { "remove": ["x"] } }`.
|
|
858
|
+
|
|
736
859
|
**Each view keeps its place while the run lasts:** the selected instance,
|
|
737
860
|
where its list and its detail were scrolled, and what was folded away are
|
|
738
861
|
found again when the view is opened again. A filter is not kept from one
|
|
@@ -764,17 +887,18 @@ none; one whose spawn stopped half way, and one whose retire failed or
|
|
|
764
887
|
didn't finish, offers only to be retired; a running one offers restart and
|
|
765
888
|
not start, a stopped one start and not restart. One that is `Retiring…`
|
|
766
889
|
offers no start, stop, restart or open: `D` still opens its retire
|
|
767
|
-
confirmation,
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
the instance does not offer opens nothing, and the line above the panes
|
|
890
|
+
confirmation, which is needed only when the first retire's holder can't be
|
|
891
|
+
read, since the kernel refuses a second retire while one runs. The
|
|
892
|
+
palette offers the acts the selected instance offers now, and the leader's
|
|
893
|
+
hint and the help name their keys. A key for an act
|
|
894
|
+
the instance does not offer opens nothing, and the line under the title
|
|
773
895
|
says why. The keys are yours to change in
|
|
774
896
|
[`tui.json`](#change-the-keys-tuijson): the actions are `stop`, `retire`,
|
|
775
897
|
`start` and `restart`.
|
|
776
898
|
|
|
777
|
-
**The confirmation** opens over the
|
|
899
|
+
**The confirmation** opens over the main area, with the focus on `Cancel`;
|
|
900
|
+
the cheat sheet names its keys (under 80 columns it covers the whole screen,
|
|
901
|
+
its keys on its first row).
|
|
778
902
|
`Left`/`Right` and `Tab`/`Shift+Tab` move between its buttons and `Enter`
|
|
779
903
|
presses one. No letter moves the focus, and an `Enter` that arrives in the
|
|
780
904
|
same read of input as the move onto the act's button is ignored, so pasted
|
|
@@ -844,7 +968,7 @@ The exit status never depends on it.
|
|
|
844
968
|
one screen to read and one `Enter` to press.
|
|
845
969
|
|
|
846
970
|
- **`n`** in the list of instances (or the leader then `n`, from any focus,
|
|
847
|
-
a terminal's too) opens the soul picker over the
|
|
971
|
+
a terminal's too) opens the soul picker over the main area: the souls of
|
|
848
972
|
[the Souls view](#the-souls-view), read with `oats souls` if they were
|
|
849
973
|
not read yet (`Reading souls…` until then). Typing filters them with the
|
|
850
974
|
palette's subsequence match; `Up`/`Down` move, `Enter` picks the selected
|
|
@@ -865,7 +989,7 @@ one screen to read and one `Enter` to press.
|
|
|
865
989
|
- **One focus ring:** `Spawn` (where the focus starts), `name`, `child of`
|
|
866
990
|
(when an instance of this machine was selected), then each folded part.
|
|
867
991
|
`Tab` moves along it, `Shift+Tab` back. `Enter` does what the focus says,
|
|
868
|
-
and the
|
|
992
|
+
and the cheat sheet names it:
|
|
869
993
|
- on `Spawn`, spawns what the preview shows;
|
|
870
994
|
- on `name`, keeps the name typed and reads the preview again with it:
|
|
871
995
|
the instance is named `<soul>-<name>` (`--purpose`). Only the letters,
|
|
@@ -891,8 +1015,8 @@ one screen to read and one `Enter` to press.
|
|
|
891
1015
|
- **`n` and `N` are of the view they are pressed in**: the leader's too.
|
|
892
1016
|
From the Souls view (its list, its filter or its detail) both are of its
|
|
893
1017
|
selected soul, whatever the list of instances has selected.
|
|
894
|
-
- **One spawn at a time.** While one is under way the line
|
|
895
|
-
|
|
1018
|
+
- **One spawn at a time.** While one is under way the line under the
|
|
1019
|
+
title says `Spawning <name>…`, and the TUI goes on working: `n` and `N`
|
|
896
1020
|
say a spawn is under way and open nothing.
|
|
897
1021
|
- **Only on this machine.** On another machine's row or workspace `n` and
|
|
898
1022
|
`N` (from their keys, the leader or the palette) say that spawning on
|
|
@@ -904,7 +1028,7 @@ the TUI adds only what to do next, naming its keys or an `oats` command:
|
|
|
904
1028
|
|
|
905
1029
|
| Outcome | What follows |
|
|
906
1030
|
|---|---|
|
|
907
|
-
| created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the
|
|
1031
|
+
| created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the sidebar 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 Alt+O w.`, and nothing opens. Not running after two reads: the line says it is not visible yet, and nothing opens later by itself |
|
|
908
1032
|
| 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) |
|
|
909
1033
|
| 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 |
|
|
910
1034
|
| its cleanup is owed | the line says so and names the retire |
|
|
@@ -930,13 +1054,15 @@ The line after leaving says so and names `oats status` to see it.
|
|
|
930
1054
|
| `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
|
|
931
1055
|
| `3` | [the Capabilities view](#the-capabilities-view); `Esc` or `1` goes back |
|
|
932
1056
|
| `w` | opens [the switcher](#the-switcher) |
|
|
933
|
-
| `
|
|
934
|
-
| `
|
|
1057
|
+
| `Delete` | in the switcher, asks whether to remove the selected row from this computer's list of deployments; `Enter` removes it |
|
|
1058
|
+
| `Enter` | in the list of instances, opens the selected agent's terminal in a new [tab](#tabs) beside the sidebar, 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 |
|
|
1059
|
+
| `z` | gives the shown terminal the focus and the whole screen |
|
|
935
1060
|
| `c` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
936
1061
|
| `[`, `]` | in the Instances view, shows the tab before or after the shown one |
|
|
937
1062
|
| `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
|
|
938
|
-
| `Ctrl+\` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
|
|
1063
|
+
| `Alt+O` (`Ctrl+\` on macOS) | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
|
|
939
1064
|
| `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
|
|
1065
|
+
| `Ctrl+Shift+K`, `Ctrl+Tab` and the other [chords](#chords) | where your terminal sends them, what the leader then a key does, from every focus |
|
|
940
1066
|
| `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
|
|
941
1067
|
| `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
|
|
942
1068
|
| `N` | spawns another of the selected instance's soul: its preview |
|
|
@@ -958,15 +1084,23 @@ instance can always be read, however many they are. The selection stays
|
|
|
958
1084
|
where it is, and the list returns to it at the next key that moves it.
|
|
959
1085
|
|
|
960
1086
|
The help screen is generated from the table the program acts on, so it
|
|
961
|
-
always lists the keys that work, the leader's among them,
|
|
962
|
-
|
|
1087
|
+
always lists the keys that work, the leader's among them, the chords while
|
|
1088
|
+
your terminal sends them, the palette's and the spawn prompt's, with the
|
|
1089
|
+
marks and with what this version does not do. Its top row has the time of the read and the count of withheld rows
|
|
1090
|
+
([What it shows](#what-it-shows)). The movement keys scroll it. While
|
|
963
1091
|
a terminal has the focus the table's keys are the agent's: the leader alone
|
|
964
|
-
is the TUI's.
|
|
1092
|
+
is the TUI's, with the chords while your terminal sends them.
|
|
965
1093
|
|
|
966
1094
|
### The leader
|
|
967
1095
|
|
|
968
1096
|
Every action is reached by keys from every focus, a terminal's too: the
|
|
969
|
-
leader
|
|
1097
|
+
leader (tui.json's `open.detachKey`), then one plain key. The leader is
|
|
1098
|
+
`Alt+O` on Linux and Windows and `Ctrl+\` on macOS, unless
|
|
1099
|
+
[`tui.json`](#change-the-keys-tuijson) names another key, `C-\` among
|
|
1100
|
+
them. `Alt+O` is reached with one hand on every keyboard layout, where
|
|
1101
|
+
`Ctrl+\` is a stretch on most and needs AltGr on many. macOS keeps
|
|
1102
|
+
`Ctrl+\` because its terminals type `ø` for Option+O unless they are set
|
|
1103
|
+
to use Option as Meta.
|
|
970
1104
|
|
|
971
1105
|
| The leader, then | Does |
|
|
972
1106
|
|---|---|
|
|
@@ -974,7 +1108,7 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
|
|
|
974
1108
|
| `1`, `2`, `3` | the Instances, Souls and Capabilities views |
|
|
975
1109
|
| `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 |
|
|
976
1110
|
| `Left`, `Right` | shows the tab before or after the shown one; the strip does not wrap, and the focus stays where it was |
|
|
977
|
-
| `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole
|
|
1111
|
+
| `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
|
|
978
1112
|
| `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
|
|
979
1113
|
| `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
|
|
980
1114
|
| `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 |
|
|
@@ -985,13 +1119,17 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
|
|
|
985
1119
|
| `/` | the filter |
|
|
986
1120
|
| `o` | [the switcher](#the-switcher) |
|
|
987
1121
|
| `?` | the help |
|
|
988
|
-
| `Esc
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
`
|
|
993
|
-
|
|
994
|
-
`
|
|
1122
|
+
| `Esc` | gives the list the focus |
|
|
1123
|
+
| the leader again | types the leader into the terminal that has the focus, which keeps it; with the list focused, only closes the hint |
|
|
1124
|
+
|
|
1125
|
+
- **While the leader waits** for its key the cheat sheet's rows are its
|
|
1126
|
+
hint: `Alt+O then`, then a row per key, `Esc the list` last. It names
|
|
1127
|
+
these keys but `n` and `N` (`z` and `w` only while a terminal is open,
|
|
1128
|
+
`Left` and `Right` only with two tabs or more, `|` and `-` while the
|
|
1129
|
+
panel has one group, `Tab` with two, then `m` while the focused group
|
|
1130
|
+
shows a tab or `x` while it is empty, and the leader again while a
|
|
1131
|
+
terminal has the focus). On a short screen it gives up rows before its
|
|
1132
|
+
last. It waits
|
|
995
1133
|
with no time limit. A key not in the table cancels it and is dropped:
|
|
996
1134
|
nothing is typed.
|
|
997
1135
|
- **Only a key in a later read counts.** A key that came in the same read of
|
|
@@ -999,6 +1137,15 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
|
|
|
999
1137
|
read, so a paste can never run a command. In a terminal the bytes before
|
|
1000
1138
|
the leader in that read still go to the agent. A leader inside a
|
|
1001
1139
|
bracketed paste is pasted text.
|
|
1140
|
+
- **In a terminal `Alt+O` is one keypress only.** A terminal sends `Alt+O`
|
|
1141
|
+
as `Esc` then `o`. Those bytes count as the leader when they arrive in
|
|
1142
|
+
one read, or split across reads within 10 ms. An `Esc` then `o` typed as
|
|
1143
|
+
two keys reaches the agent unchanged: in vim that is "leave insert mode,
|
|
1144
|
+
open a line". Over a slow link two keys typed apart can arrive in one
|
|
1145
|
+
read and act as the leader, and one `Alt+O` can arrive split and reach
|
|
1146
|
+
the agent as `Esc` and `o`. Under the kitty keyboard protocol
|
|
1147
|
+
([Chords](#chords)) there is no timing: `Alt+O` is one sequence and `Esc`
|
|
1148
|
+
another, so each is told exactly, in a terminal and in the list.
|
|
1002
1149
|
- **In the list no leader is needed:** the plain keys work as they always
|
|
1003
1150
|
have, and the leader works there too.
|
|
1004
1151
|
- **What was open under it is settled first,** from whatever view: a
|
|
@@ -1010,11 +1157,79 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
|
|
|
1010
1157
|
- **The table is fixed** in this version: `keys` in `tui.json` rebinds the
|
|
1011
1158
|
plain keys, and `open.detachKey` the leader.
|
|
1012
1159
|
|
|
1160
|
+
### Chords
|
|
1161
|
+
|
|
1162
|
+
Where your terminal lets them through, the OATS Desktop's Ctrl+Shift chords
|
|
1163
|
+
work in `oats tui` too, as extras: each does what the leader then a key
|
|
1164
|
+
does, from every focus, a terminal's too, and never reaches the agent. The
|
|
1165
|
+
leader stays the key that always works, and the cheat sheet does not name
|
|
1166
|
+
the chords.
|
|
1167
|
+
|
|
1168
|
+
| Chord (Linux and Windows) | Does: the leader then |
|
|
1169
|
+
|---|---|
|
|
1170
|
+
| `Ctrl+Shift+K` | `k`, the palette |
|
|
1171
|
+
| `Ctrl+Shift+P` | `n`, spawn an agent |
|
|
1172
|
+
| `Ctrl+Tab`, `Ctrl+Shift+Tab` | `Right`, `Left`: the next or the previous tab |
|
|
1173
|
+
| `Ctrl+Shift+W` | `w`, close the shown terminal |
|
|
1174
|
+
| `Ctrl+Shift+F` | `/`, the filter |
|
|
1175
|
+
| `Ctrl+Shift+E`, `Ctrl+Shift+O` | `\|`, `-`: split right, split down |
|
|
1176
|
+
|
|
1177
|
+
On macOS the Desktop's chords hold ⌘, which a terminal never passes to a
|
|
1178
|
+
program: there `Ctrl+Tab` and `Ctrl+Shift+Tab` are the only chords. The
|
|
1179
|
+
chords are the Desktop's (`CHORDS` in `packages/client/keymap.mjs`), and the
|
|
1180
|
+
TUI keeps no copy. The Desktop's Ctrl+1, Ctrl+2 and Ctrl+3 (its stages) are
|
|
1181
|
+
its own.
|
|
1182
|
+
|
|
1183
|
+
- **Only where the terminal says it can.** A terminal sends these keys apart
|
|
1184
|
+
from `Ctrl+K`, `Ctrl+P` and the others only under the kitty keyboard
|
|
1185
|
+
protocol. As it takes the terminal, `oats tui` asks for the protocol with
|
|
1186
|
+
flags 1 and 4 (`CSI > 5 u`) and asks the terminal which flags it has
|
|
1187
|
+
(`CSI ? u`). Only when the answer holds flag 1 does it read the protocol,
|
|
1188
|
+
take the chords and list them in the help. With no answer within 2
|
|
1189
|
+
seconds, or one without flag 1, it pops the protocol, and the rest of the
|
|
1190
|
+
run is as without it. The answer may come split and late over a slow
|
|
1191
|
+
link, so until it comes (at most those 2 seconds) an `Esc` pressed on its
|
|
1192
|
+
own may wait for the next key or for the wait's end, as it may begin the
|
|
1193
|
+
answer. foot, Ghostty, kitty, Alacritty and WezTerm answer.
|
|
1194
|
+
GNOME Terminal and the other VTE terminals, and Terminal.app, do not:
|
|
1195
|
+
there the chords are absent.
|
|
1196
|
+
- **Your terminal may take some first.** foot takes Ctrl+Shift+C, V, R, N,
|
|
1197
|
+
O, U, Z, X and Q for itself, so `Ctrl+Shift+O` never reaches `oats tui`
|
|
1198
|
+
there. The help says so.
|
|
1199
|
+
- **Every other key reads as it does without the protocol.** `Ctrl+Shift+L`
|
|
1200
|
+
is `Ctrl+L`, `Ctrl+Enter` is `Enter`, and so on: the protocol only adds
|
|
1201
|
+
the chords, and tells `Alt+O` from `Esc` then `o` exactly
|
|
1202
|
+
([The leader](#the-leader)).
|
|
1203
|
+
- **An agent gets what it gets without the protocol.** Every key typed
|
|
1204
|
+
into an agent's terminal is turned back into the bytes the same key sends
|
|
1205
|
+
without it, the legacy encoding of xterm and the terminals that follow it:
|
|
1206
|
+
text, Shift, Ctrl, Alt, Esc, Tab, Enter, Backspace, the arrows, the
|
|
1207
|
+
function keys and the keypad, with their modifiers. The TUI types those
|
|
1208
|
+
bytes into the agent's viewer (`tmux attach` on the agents' server). It
|
|
1209
|
+
changes no tmux setting, `extended-keys` included, so the agent's program
|
|
1210
|
+
gets the same bytes as before. A key that sends nothing without the
|
|
1211
|
+
protocol (F13 and above, the media keys) is not typed.
|
|
1212
|
+
- **One limit: Shift with Alt or Ctrl on a key that is not a letter.** With
|
|
1213
|
+
flag 4 the terminal says which character Shift makes on your layout, and
|
|
1214
|
+
the TUI types exactly that. A terminal that confirms flag 1 alone does not
|
|
1215
|
+
say, and then the TUI uses the US layout's character for the 21 keys that
|
|
1216
|
+
are not letters (`Shift+Alt+2` is `Alt+@`), which your layout may not
|
|
1217
|
+
make.
|
|
1218
|
+
- **It is always popped** (`CSI < u`): on every way out
|
|
1219
|
+
([below](#what-it-changes-in-your-terminal-and-restores)), at a suspend
|
|
1220
|
+
(and pushed again on return), and before any other program is given the
|
|
1221
|
+
terminal: the shell at a suspend is the only one `oats tui` ever gives
|
|
1222
|
+
it to.
|
|
1223
|
+
|
|
1013
1224
|
### The palette
|
|
1014
1225
|
|
|
1015
1226
|
The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
|
|
1016
|
-
over a list, as the OATS Desktop's ⌘K does.
|
|
1017
|
-
|
|
1227
|
+
over a list, as the OATS Desktop's ⌘K does. From 80 columns it covers the
|
|
1228
|
+
main area and the sidebar stays beside it, its cheat sheet naming the
|
|
1229
|
+
palette's keys (`Enter run`, `Up/Down move`, `Esc close`); under 80 columns
|
|
1230
|
+
it covers the whole screen, with those keys on its first row. While it is
|
|
1231
|
+
open no terminal is drawn and the TUI reads the keys. The help lists its
|
|
1232
|
+
keys under The palette.
|
|
1018
1233
|
|
|
1019
1234
|
- **It lists, in this order:** the instances that can be opened, the most
|
|
1020
1235
|
recently opened or shown in this run first (when the first is the shown tab's,
|
|
@@ -1050,15 +1265,18 @@ is open no terminal is drawn and the TUI reads the keys.
|
|
|
1050
1265
|
- Closed, it gives the focus back to the terminal it was opened from.
|
|
1051
1266
|
Recency is kept for the run only: nothing is written.
|
|
1052
1267
|
|
|
1053
|
-
**The filter.** `/` opens a field on the
|
|
1268
|
+
**The filter.** `/` opens a field on the open view's heading: while you
|
|
1269
|
+
type, the heading is `/` and the text. What you type narrows the
|
|
1054
1270
|
list to the instances whose name, soul or repository contains it, with the
|
|
1055
1271
|
instances they were spawned from, whatever is folded away. In the field
|
|
1056
1272
|
every printable key is text, so `q` and `j` can be typed; `Backspace`
|
|
1057
1273
|
removes a character, `Enter` keeps the filter and returns to the list
|
|
1058
|
-
(the
|
|
1274
|
+
(the heading then names it after the view's name, `Instances /text`),
|
|
1275
|
+
`Esc` clears it. `Ctrl+C`, `Ctrl+Z`
|
|
1059
1276
|
and `Ctrl+L` still do what they do. The filter holds at most 200
|
|
1060
|
-
characters. The switcher has a filter of its own
|
|
1061
|
-
|
|
1277
|
+
characters. The switcher has a filter of its own: its field stands on a
|
|
1278
|
+
row of its own above its list while it is typed or kept, and it narrows the
|
|
1279
|
+
rows to the ones whose name, machines or path contain the text.
|
|
1062
1280
|
|
|
1063
1281
|
**Pasted text is never read as keys.** A paste into the list is dropped
|
|
1064
1282
|
whole. A paste into the filter field adds its first line, and only when
|
|
@@ -1069,9 +1287,12 @@ and scrolling keep working.
|
|
|
1069
1287
|
|
|
1070
1288
|
## Change the keys: `tui.json`
|
|
1071
1289
|
|
|
1072
|
-
`oats tui` reads
|
|
1073
|
-
|
|
1074
|
-
|
|
1290
|
+
`oats tui` reads `~/.oats/config/tui.json` once, at the start: beside the
|
|
1291
|
+
kernel's own files, so it is `$OATS_HOME_DIR/config/tui.json` when
|
|
1292
|
+
`OATS_HOME_DIR` is set (the same rule as this computer's list of
|
|
1293
|
+
deployments). `XDG_CONFIG_HOME` is not read for it. It never writes the file,
|
|
1294
|
+
except to [move it](#the-move-from-configoats) from where earlier versions
|
|
1295
|
+
read it. With no file the keys are the ones above.
|
|
1075
1296
|
|
|
1076
1297
|
```json
|
|
1077
1298
|
{ "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
|
|
@@ -1085,7 +1306,7 @@ never writes it. With no file the keys are the ones above.
|
|
|
1085
1306
|
`souls`, `capabilities`, `workspaces`, `palette`, `open`, `soul-instances`, `zoom`, `close-terminal`,
|
|
1086
1307
|
`tab-previous`, `tab-next`, `split-right`, `split-down`, `group-next`, `tab-move`,
|
|
1087
1308
|
`group-close`, `stop`, `retire`, `start`, `restart`, `spawn`, `spawn-another`,
|
|
1088
|
-
`spawn-check`, `help`, `close`, `quit`, `suspend` and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
|
|
1309
|
+
`spawn-check`, `remove`, `help`, `close`, `quit`, `suspend` and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
|
|
1089
1310
|
opens the selected agent's terminal in the list of instances, the
|
|
1090
1311
|
selected row in the switcher and the detail in the Souls view;
|
|
1091
1312
|
`soul-instances` (`i`) shows the selected soul's instances. `zoom` (`z`) and `close-terminal` (`c`) act
|
|
@@ -1093,7 +1314,8 @@ never writes it. With no file the keys are the ones above.
|
|
|
1093
1314
|
the tab before and after it. `split-right` (`|`) and `split-down` (`-`)
|
|
1094
1315
|
[split](#splits) the panel; `group-next`, `tab-move` and `group-close`
|
|
1095
1316
|
have no key of their own by default (the leader then `Tab`, `m` and `x`
|
|
1096
|
-
reach them).
|
|
1317
|
+
reach them). `remove` (`delete`) asks whether to remove the selected row
|
|
1318
|
+
of this computer's list of deployments, in the switcher. In an open filter field `Enter` keeps the filter,
|
|
1097
1319
|
whatever key `open` has.
|
|
1098
1320
|
- A key is written as the help shows it, in lower case: `q`, `G`, `?`,
|
|
1099
1321
|
`space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
|
|
@@ -1102,12 +1324,16 @@ never writes it. With no file the keys are the ones above.
|
|
|
1102
1324
|
and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
|
|
1103
1325
|
keys of their own.
|
|
1104
1326
|
- `ascii: true` is `--ascii`.
|
|
1105
|
-
- `open.detachKey` is **[the leader](#the-leader)
|
|
1106
|
-
|
|
1327
|
+
- `open.detachKey` is **[the leader](#the-leader)**. When you name none
|
|
1328
|
+
it is `M-o` (`Alt+O`) on Linux and Windows and `C-\` (`Ctrl+\`) on
|
|
1329
|
+
macOS; `C-\` stays a key you can name on every platform. It is
|
|
1330
|
+
`oats tui`'s own: it never reaches the kernel, and it reaches the agent
|
|
1331
|
+
only when you press it twice in the agent's terminal.
|
|
1107
1332
|
It is read as a key wherever the TUI reads keys, so it may not be a key
|
|
1108
1333
|
an action has: `C-l` is `redraw`'s `Ctrl+L`, `C-k` the palette's
|
|
1109
|
-
`Ctrl+K`, `C-j` is `Enter`.
|
|
1110
|
-
|
|
1334
|
+
`Ctrl+K`, `C-j` is `Enter`. That holds for the default too: a file that
|
|
1335
|
+
gives `alt+o` to an action on Linux or Windows names another leader as
|
|
1336
|
+
well. It is one of these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
|
|
1111
1337
|
terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
|
|
1112
1338
|
`]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
|
|
1113
1339
|
alone or with one of `C-`, `M-`, `S-` (`C-F5`). These are the keys a
|
|
@@ -1126,7 +1352,7 @@ guesses nothing. It refuses:
|
|
|
1126
1352
|
| 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` |
|
|
1127
1353
|
| has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
|
|
1128
1354
|
| gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
|
|
1129
|
-
| gives `open.detachKey
|
|
1355
|
+
| gives `open.detachKey`, or the default leader, a key an action has | `open.detachKey … is read as …, the key of …; give the leader a key no action has, or give … another`, or `the default leader … is read as …` with the same end when the file names no leader |
|
|
1130
1356
|
| names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
|
|
1131
1357
|
| names an action that does not exist | `unknown action …`, with the list of actions |
|
|
1132
1358
|
| gives an action something that is not a list of strings | `… must be a list of key ids` |
|
|
@@ -1139,6 +1365,47 @@ A name from the file is repeated in a line only when it is plain printable
|
|
|
1139
1365
|
ASCII of at most 40 characters. More than twenty problems are counted, not
|
|
1140
1366
|
listed.
|
|
1141
1367
|
|
|
1368
|
+
### The move from `.config/oats`
|
|
1369
|
+
|
|
1370
|
+
Earlier versions read `$XDG_CONFIG_HOME/oats/tui.json` when
|
|
1371
|
+
`XDG_CONFIG_HOME` is set, not empty and an absolute path, else
|
|
1372
|
+
`~/.config/oats/tui.json`: the old file. Before it reads the new one, every
|
|
1373
|
+
start looks at both:
|
|
1374
|
+
|
|
1375
|
+
| Old file | New file | `oats tui` |
|
|
1376
|
+
|---|---|---|
|
|
1377
|
+
| there | not there | copies the old file's bytes to the new path, then renames the old file `tui.json.migrated` beside it, then reads the new one |
|
|
1378
|
+
| there | there | refuses: `<old> is no longer read: the TUI reads <new>. Copy what you need into <new>, then remove <old>` |
|
|
1379
|
+
| not there | there | reads the new one |
|
|
1380
|
+
| not there | not there | uses the defaults |
|
|
1381
|
+
|
|
1382
|
+
- "There" means an entry is at that path: a symbolic link counts, a link to
|
|
1383
|
+
nothing included, so a link to nothing as the old file is reported rather
|
|
1384
|
+
than guessed at.
|
|
1385
|
+
- The copy is the file's bytes, not its settings: a file the TUI cannot use
|
|
1386
|
+
is moved as it is, then refused against the new path like any other. The
|
|
1387
|
+
new file is made with mode `0600`, and the directories it needs with
|
|
1388
|
+
`0700`. It is written to a file of its own beside its path, then put in
|
|
1389
|
+
place, by a hard link, so it is never half written and never written
|
|
1390
|
+
over another file.
|
|
1391
|
+
- A link as the old file is renamed itself, not followed: what it points at
|
|
1392
|
+
is copied, and its target is left as it was.
|
|
1393
|
+
- When the move cannot be made, nothing is left half done and the start
|
|
1394
|
+
stops: `cannot move <old> to <new> (<reason>); move it yourself`. The
|
|
1395
|
+
reason is a link to nothing, not a regular file, larger than 64 KiB,
|
|
1396
|
+
`tui.json.migrated is there already` (a backup is never written over),
|
|
1397
|
+
`this file system has no hard links` (FAT, exFAT, some network mounts:
|
|
1398
|
+
there the file cannot be put in place whole without a risk of writing over
|
|
1399
|
+
another, so it is not moved), or the code of the error, as `EACCES`. When the rename fails after the copy is
|
|
1400
|
+
made, the copy is deleted first.
|
|
1401
|
+
- To move it yourself, put the file at the new path and remove the old one
|
|
1402
|
+
(or rename it to anything but `tui.json`).
|
|
1403
|
+
- Two runs that start at once move it once. The one that finds a new file
|
|
1404
|
+
placed by the other since it looked asks again: once its old file is gone
|
|
1405
|
+
it reads the new one; while an old file is still there (the other's, not
|
|
1406
|
+
yet renamed, or its own, with another `XDG_CONFIG_HOME`) it refuses as for
|
|
1407
|
+
both files, and never reads settings it was not moving: start it again.
|
|
1408
|
+
|
|
1142
1409
|
## What it reads, and what it runs
|
|
1143
1410
|
|
|
1144
1411
|
`oats tui` decodes no kernel answer itself: it runs the readers it shares
|
|
@@ -1158,8 +1425,8 @@ with the Desktop (`packages/client/`).
|
|
|
1158
1425
|
- **How often:** 5 seconds after the last read ended; 30 seconds once ten
|
|
1159
1426
|
minutes have passed without a key; at once on `r`, on the return from a
|
|
1160
1427
|
suspend and when a row is opened in the switcher. Every read asks tmux
|
|
1161
|
-
anew and reads the instances anew, and the time
|
|
1162
|
-
read's. What a read in the background may reuse is the kernel's own look
|
|
1428
|
+
anew and reads the instances anew, and the time on the help's top row is
|
|
1429
|
+
that read's. What a read in the background may reuse is the kernel's own look
|
|
1163
1430
|
at the workspace's remotes, for up to 60 seconds; `r` asks the kernel to
|
|
1164
1431
|
look again.
|
|
1165
1432
|
- **The souls are one more read**, `oats souls --json` for the open
|
|
@@ -1193,12 +1460,22 @@ with the Desktop (`packages/client/`).
|
|
|
1193
1460
|
a suspend and when a row is opened in the switcher.
|
|
1194
1461
|
- A kernel whose version record lists no read of other machines is never
|
|
1195
1462
|
asked for one, and no other machine is shown.
|
|
1196
|
-
- **
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1463
|
+
- **This computer's list of deployments is the kernel's**, read and changed
|
|
1464
|
+
through the same kernel, with 15 seconds and 4 MiB each, from `/`:
|
|
1465
|
+
- `oats deployments --json`, at a start outside every deployment with no
|
|
1466
|
+
`--dir` (before the terminal is taken), when the switcher opens, on `r`
|
|
1467
|
+
in it and after a Remove. One runs at a time: one asked for while one is
|
|
1468
|
+
on its way runs after it, however many times it was asked, and the
|
|
1469
|
+
answer taken is that later one's.
|
|
1470
|
+
- `oats deployments add <path> --via tui --json`, once a run, for the
|
|
1471
|
+
deployment it started in, from that deployment.
|
|
1472
|
+
- `oats deployments remove <path> --json`, for a Remove you confirmed.
|
|
1473
|
+
|
|
1474
|
+
An add and a remove are changes: `oats tui` never ends one, and one still
|
|
1475
|
+
running as it leaves is named in one line after the screen is left.
|
|
1476
|
+
- **One look at the file system serves the switcher**, and it reads no
|
|
1477
|
+
file's content: when a row of the list is opened, that one directory is
|
|
1478
|
+
asked for a regular `oats-local.yaml`.
|
|
1202
1479
|
- **Opening an agent runs one more command,** `oats session attach --home
|
|
1203
1480
|
<home>`, by the same kernel, in a pane of the run's private tmux server
|
|
1204
1481
|
([above](#open-an-agents-terminal)), with no key of its own. For an agent
|
|
@@ -1242,7 +1519,7 @@ with the Desktop (`packages/client/`).
|
|
|
1242
1519
|
that pane's output until the tab is displayed again, so a hidden agent
|
|
1243
1520
|
that prints without pause costs one chunk of output each time its tab is
|
|
1244
1521
|
hidden, and a quiet one nothing. The panel hidden as a whole (another
|
|
1245
|
-
view or an overlay over it, or the
|
|
1522
|
+
view or an overlay over it, or the sidebar alone under 80 columns) pauses
|
|
1246
1523
|
its displayed tabs the same way. A
|
|
1247
1524
|
paused pane is still read by the private server, so its screen stays
|
|
1248
1525
|
current and its viewer never waits. A tab displayed again is continued
|
|
@@ -1305,7 +1582,10 @@ with the Desktop (`packages/client/`).
|
|
|
1305
1582
|
files in a directory of `oats tui`'s own (made with mode 0700 under the
|
|
1306
1583
|
system's temporary directory), read back when it ends and deleted. On the
|
|
1307
1584
|
way out the files of a change still running are deleted (it goes on
|
|
1308
|
-
writing to them), and the directory is removed.
|
|
1585
|
+
writing to them), and the directory is removed. A run ended by SIGKILL
|
|
1586
|
+
removes nothing: with a kernel that lists this computer's deployments,
|
|
1587
|
+
the add at the start has made the directory, and when no terminal was
|
|
1588
|
+
opened in that run it holds no `owner.json`, so no later run removes it. `oats tui` waits for an
|
|
1309
1589
|
apply's answer for 10 minutes and for a start's for 60 seconds; then it
|
|
1310
1590
|
says so, and the change goes on.
|
|
1311
1591
|
- **A spawn runs the kernel's own `oats spawn`**, as the Desktop does: the
|
|
@@ -1341,26 +1621,28 @@ with the Desktop (`packages/client/`).
|
|
|
1341
1621
|
| spawn an agent on another machine | `oats spawn <soul> --server <id>` |
|
|
1342
1622
|
| spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
|
|
1343
1623
|
| see a capability's skills and files | `oats capabilities show <name>` |
|
|
1344
|
-
| add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
|
|
1624
|
+
| add a machine to this workspace | `oats server connect <id> --ssh <alias> --dir <path on that machine>` |
|
|
1345
1625
|
| check a machine | `oats server check <id>` |
|
|
1346
1626
|
| remove a machine | `oats server remove <id>` |
|
|
1347
|
-
| open a deployment
|
|
1627
|
+
| open a deployment that is not listed | `oats tui --dir <path>` |
|
|
1348
1628
|
| open an agent in a tmux window or split of its own | `oats session attach --home <home>` in that window (the detail shows the home) |
|
|
1349
1629
|
|
|
1350
1630
|
The help screen (`?`) names the same commands. What else holds for this
|
|
1351
1631
|
version:
|
|
1352
1632
|
|
|
1353
|
-
- **It keeps nothing on disk
|
|
1354
|
-
|
|
1355
|
-
|
|
1633
|
+
- **It keeps nothing on disk of its own; opening a deployment lists it**
|
|
1634
|
+
on this computer's list, which is the kernel's. A machine it has not
|
|
1635
|
+
reached in this run is listed by its own name, in no workspace. What is
|
|
1636
|
+
folded away and each view's place last as long as the run, and no filter
|
|
1637
|
+
is saved.
|
|
1356
1638
|
- **Of this machine's deployments, the switcher lists only the ones opened
|
|
1357
|
-
in this run and the ones
|
|
1358
|
-
|
|
1639
|
+
in this run and the ones on this computer's list.** Any other is opened
|
|
1640
|
+
with `oats tui --dir <path>`, which lists it.
|
|
1359
1641
|
- **A row of another machine shows what its host reported at the last
|
|
1360
1642
|
read,** not what is true at this moment. The time of that read is on the
|
|
1361
|
-
machine's heading when it is not the
|
|
1362
|
-
has no heading: there the
|
|
1363
|
-
carries the time.
|
|
1643
|
+
machine's heading when it is not the time of this machine's read. A view
|
|
1644
|
+
of one machine has no heading: there the title names the machine
|
|
1645
|
+
(`on garnet`) and the help's top row carries the time.
|
|
1364
1646
|
- The Souls and Capabilities views list a workspace of this machine's
|
|
1365
1647
|
souls and capabilities: both are this machine's.
|
|
1366
1648
|
- There is no sorting and no mouse, and a deployment's heading cannot be
|
|
@@ -1381,10 +1663,15 @@ This is the complete list. On start, in this order:
|
|
|
1381
1663
|
2. the alternate screen (`CSI ?1049h`), so your scrollback is untouched;
|
|
1382
1664
|
3. the cursor hidden (`CSI ?25l`);
|
|
1383
1665
|
4. autowrap off (`CSI ?7l`);
|
|
1384
|
-
5. bracketed paste on (`CSI ?2004h`)
|
|
1666
|
+
5. bracketed paste on (`CSI ?2004h`);
|
|
1667
|
+
6. the kitty keyboard protocol pushed, with flags 1 and 4 (`CSI > 5 u`), and
|
|
1668
|
+
the terminal asked which flags it has (`CSI ? u`); a terminal that does
|
|
1669
|
+
not know the protocol ignores both. With no answer in 2 seconds it is
|
|
1670
|
+
popped ([Chords](#chords)).
|
|
1385
1671
|
|
|
1386
|
-
On the way out, the reverse:
|
|
1387
|
-
reset (`CSI 0m`), the cursor shown, the
|
|
1672
|
+
On the way out, the reverse: the protocol popped (`CSI < u`), bracketed
|
|
1673
|
+
paste off, autowrap on, the style reset (`CSI 0m`), the cursor shown, the
|
|
1674
|
+
alternate screen left, raw mode off.
|
|
1388
1675
|
|
|
1389
1676
|
While it draws:
|
|
1390
1677
|
|
|
@@ -1451,10 +1738,11 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
1451
1738
|
## What it never does
|
|
1452
1739
|
|
|
1453
1740
|
- It switches on **no mouse reporting, no focus reporting, no keyboard
|
|
1454
|
-
protocol
|
|
1455
|
-
update on between
|
|
1741
|
+
protocol but the kitty one with flags 1 and 4 ([Chords](#chords)), and no
|
|
1742
|
+
keypad or cursor-key mode**, and leaves no synchronized update on between
|
|
1743
|
+
frames.
|
|
1456
1744
|
- It writes **no window title, no clipboard sequence, no bell**, and no query
|
|
1457
|
-
that expects the terminal to reply.
|
|
1745
|
+
that expects the terminal to reply but the kitty keyboard protocol's.
|
|
1458
1746
|
- **Its own words and marks use only your terminal's own sixteen colours**
|
|
1459
1747
|
and bold, dim, underline and reverse: no 256-colour or RGB value and no
|
|
1460
1748
|
background fill, so your theme stays the theme. An open terminal shows
|
|
@@ -1500,6 +1788,10 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
1500
1788
|
to its own end. A spawn is ended only at its deadline, while `oats tui`
|
|
1501
1789
|
runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
|
|
1502
1790
|
and never after it.
|
|
1791
|
+
- It **changes this computer's list of deployments only through the
|
|
1792
|
+
kernel** (`oats deployments add` and `remove`,
|
|
1793
|
+
[above](#what-it-reads-and-what-it-runs)), and never reads or writes the
|
|
1794
|
+
list's file itself.
|
|
1503
1795
|
|
|
1504
1796
|
## Errors
|
|
1505
1797
|
|
|
@@ -1509,11 +1801,18 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
1509
1801
|
| `E_BAD_ARGS` | `oats tui --json`: it is interactive and has no JSON form. The usual failure envelope, exit 1 | `oats status --json` is the machine view |
|
|
1510
1802
|
| `E_BAD_ARGS` | any argument other than `--dir <path>`, `--ascii` and `--help`, or `--dir` with no path. One line on stderr with the usage, exit 1 | `oats tui --help` |
|
|
1511
1803
|
| `E_TUI_CONFIG` | `tui.json` cannot be honoured. One line per problem on stderr, exit 1 | fix the file as the line says, or remove it |
|
|
1512
|
-
| `
|
|
1804
|
+
| `E_TUI_CONFIG` | the [old `tui.json`](#the-move-from-configoats) and the new one are both there: `` `oats tui`: <old> is no longer read: the TUI reads <new>. Copy what you need into <new>, then remove <old> ``. One line on stderr, exit 1 | as the line says |
|
|
1805
|
+
| `E_TUI_CONFIG` | the [old `tui.json`](#the-move-from-configoats) could not be moved: `` `oats tui` cannot move <old> to <new> (<reason>); move it yourself ``. One line on stderr, exit 1 | move it yourself: the file at the new path, the old one removed |
|
|
1806
|
+
| `E_NO_DEPLOYMENT` | with `--dir`, no directory at or above it holds an `oats-local.yaml`: `no OATS deployment at or above <dir>`. One line on stderr, exit 1 | `oats tui --dir <path>` with a deployment, or `cd` into one |
|
|
1807
|
+
| `E_NO_DEPLOYMENT` | without `--dir`, no directory at or above the start holds an `oats-local.yaml`, and this computer's list of deployments holds none: `no deployment at or above <dir>, and this computer's list of deployments holds none (E_NO_DEPLOYMENT): \`oats tui --dir <path>\` opens one (and lists it), \`oats onboard <dir> --workspace <ref>\` creates one`. One line on stderr, exit 1 | as the line says |
|
|
1808
|
+
| the kernel's code (`E_DEPLOYMENTS_BUSY`, `E_DEPLOYMENTS_INVALID`, `E_DEPLOYMENTS_VERSION`, …) | without `--dir` and outside every deployment, this computer's list of deployments could not be read: `` `oats tui` could not read this computer's list of deployments (<code>): <the kernel's message> ``. One line on stderr, exit 1 | what the kernel's message says |
|
|
1513
1809
|
| `E_TUI_KERNEL` | the kernel it shipped with did not answer `version --json` with a record it accepts; the line gives the reason. One line on stderr, exit 1 | reinstall `oats`: the client and the kernel are one package |
|
|
1514
1810
|
|
|
1515
1811
|
These lines are written before the terminal is touched, in this order: the
|
|
1516
|
-
arguments, the terminal, `tui.json`, the deployment, the kernel
|
|
1812
|
+
arguments, the terminal, `tui.json`, the deployment, the kernel, and then,
|
|
1813
|
+
for a start without `--dir` outside every deployment, this computer's list of
|
|
1814
|
+
deployments, which is read through that kernel. A `--dir` that is in no
|
|
1815
|
+
deployment is answered before the kernel is asked. None of the
|
|
1517
1816
|
codes on stderr appears in a JSON envelope. A path is repeated in a line
|
|
1518
1817
|
only when it is plain printable ASCII.
|
|
1519
1818
|
|