@awebai/oats 0.51.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
package/docs/tui.md ADDED
@@ -0,0 +1,584 @@
1
+ # OATS TUI (preview)
2
+
3
+ `oats tui` is the OATS terminal client: one full-screen, keyboard-only program
4
+ for people who work in terminals and on machines with no display, such as a
5
+ build host reached over ssh. The [OATS Desktop](desktop.md) is the client for
6
+ people who want a window; `oats tui` is the same kind of client for a
7
+ terminal. It ships inside the `oats` package: there is nothing else to
8
+ install.
9
+
10
+ ## It is a preview
11
+
12
+ `oats tui` is marked **preview**. That means:
13
+
14
+ - **This version shows a workspace's instances, on this machine and on the
15
+ other machines registered on this machine, in one list, and changes
16
+ nothing.** The registered machines are the ones `oats server list` names.
17
+ It follows the instances as they start, stop and wait for you. It cannot
18
+ open an agent's terminal, stop, start, restart or retire one, spawn one,
19
+ or add, check or remove a machine: [what it does not do
20
+ yet](#what-this-version-does-not-do) names the `oats` command for each.
21
+ - **Its screens and its configuration file may change without notice** while
22
+ it is a preview.
23
+ - **It leaves preview when three things hold:** the readers it shares with
24
+ the Desktop are in their shared home (`packages/client/`), a person has
25
+ used it for a working day, and both maintainers agree to drop the mark.
26
+
27
+ Every other `oats` word keeps its contract. Nothing gates on `oats tui`:
28
+ `oats version --json` lists no feature for it.
29
+
30
+ ## Start it
31
+
32
+ ```bash
33
+ oats tui # in or under a deployment, in a terminal of 80x24 or more
34
+ oats tui --dir <path> # the deployment at or above <path>
35
+ oats tui --ascii # rules and marks in ASCII, whatever the locale
36
+ oats tui --help # the usage; needs no terminal
37
+ ```
38
+
39
+ **Which deployment.** It starts from `--dir` (also `--dir=<path>`), else
40
+ from the directory you are in, and walks up to the first directory that
41
+ holds a regular `oats-local.yaml`. That directory is the deployment, and
42
+ the view it opens is that deployment's workspace: its instances on this
43
+ machine and on every registered machine that reports the same workspace.
44
+ Another deployment is opened from [the switcher](#the-switcher), in the
45
+ same run.
46
+
47
+ **Outside every deployment.** Started with no `--dir` in a directory that
48
+ is in no deployment, it looks directly inside `~/Agents`. When a deployment
49
+ is there it starts with the switcher, and nothing is open until you open a
50
+ row. When none is there it prints one line (`E_NO_DEPLOYMENT`) and exits 1
51
+ without touching the terminal. With `--dir`, nothing is offered in place of
52
+ a path that is in no deployment: the same line, and exit 1.
53
+
54
+ **From inside an agent's pane it still reads the deployment you asked
55
+ for.** An instance session carries variables that make a kernel command
56
+ answer for that instance (`OATS_INSTANCE_HOME` and seven others).
57
+ `oats tui` removes all eight from its own environment before it starts
58
+ anything. Two of them, `OATS_RESOLUTION` and `OATS_DEPLOYMENT`, are set only
59
+ in a home captured before OATS 0.26: there `oats` refuses every command but
60
+ `version`, this one included, with a line that names the variable and says
61
+ what to do.
62
+
63
+ It needs a terminal on both stdin and stdout, and a `TERM` that is set and is
64
+ not `dumb`. It draws from 60×15 up; on a smaller terminal it shows one line
65
+ with the size found and the size needed, and draws the view again, as it
66
+ was, as soon as the terminal is large enough. It follows a resize.
67
+
68
+ `--dir`, `--ascii` and `--help` are the only arguments. `--server` is
69
+ refused like any other argument (`E_BAD_ARGS`): no machine is named at the
70
+ start. It reads every machine registered on this machine.
71
+
72
+ **Start it again after you upgrade OATS.** It asks the kernel it shipped
73
+ with for its version once, at the start, and does not ask again while it
74
+ runs.
75
+
76
+ ## What it shows
77
+
78
+ ```
79
+ oats acme-platform +1 machine 4 running 1 needs input 2 stopped
80
+ 1 Instances 2 Souls 3 Capabilities read 14:03:27
81
+ ──────────────────────────────────────────────┬─────────────────────────────────────────────────
82
+ This machine │ api-lead
83
+ ▾ ● backend-lead claude │ soul tech-lead
84
+ ● backend-dev-auth claude !│ machine garnet
85
+ │ state running
86
+ ○ docs-writer stopped │ harness claude, claude-opus-5-5 (soul)
87
+ garnet read 14:03:21 │ work worktree, agents/api-lead
88
+ >▾ ● api-lead claude │ home …agents/tech-lead/instances/api-lead
89
+ ● api-dev-export claude │
90
+ │
91
+ ○ reviewer-api stopped │
92
+ ──────────────────────────────────────────────┴─────────────────────────────────────────────────
93
+ / filter Tab detail r refresh w workspaces ? help q quit
94
+ ```
95
+
96
+ - **The header** has the workspace's name, then what the view holds of
97
+ other machines, then the counts. Beside a deployment of this machine the
98
+ other machines are counted: `+1 machine`, `+2 machines`. A view that holds
99
+ no deployment of this machine names its one machine, `on garnet`, or
100
+ counts them when there are two or more, `2 machines`. The counts are over
101
+ every row of the view: instances running, instances that need input,
102
+ stopped, state unknown, and rows the kernel reported that were withheld (a
103
+ home outside its soul's directory, or one reported twice). A count of zero
104
+ is left out. The second row names the views; `2 Souls` and
105
+ `3 Capabilities` are dim because they cannot be opened yet. On the right
106
+ is the time of the read of this machine that the screen shows: it moves
107
+ with every read.
108
+ - **The list** is the roster the Desktop draws: the same groups in the same
109
+ order, from the same code. An instance that others were spawned from
110
+ comes first, and the ones below it are indented under it; instances
111
+ related to no other follow, after an empty row.
112
+ - **Each row** has a mark for its state, the name, then the harness when it
113
+ runs, else its state in a word, then `!` when it needs input.
114
+ - **The detail** shows the selected instance: its soul, its state, and
115
+ under it the reason when there is one, after the words that say who gave
116
+ it: `OATS says:` for a kernel (this machine's, or the instance's
117
+ machine's as this machine's kernel relayed it),
118
+ `oats tui's terminal check says:` for the check of the terminals, and
119
+ `oats tui's read of other machines says:` for the read of the other
120
+ machines. Three reasons stand without such words. The sentence about a
121
+ session backend OATS no longer has, when the instance's kernel is too old
122
+ to give its own, stands as it is. A reason whose speaker is not known is
123
+ shown in quotation marks, and names nobody. A reason that is withheld is
124
+ `[withheld]` alone. Then it shows what it needs from you with how long
125
+ it has waited and its own message, harness and model, work mode and
126
+ branch, team, parent, when it last started, and its home. From 80
127
+ columns up it stands beside the list; on a narrower terminal `Tab` opens
128
+ it as a page.
129
+
130
+ **A view of more than one deployment** (this machine and another, or two
131
+ deployments on one machine) is one list, grouped as the Desktop groups it:
132
+
133
+ - **Each deployment has a heading**, and its instances stand under it,
134
+ grouped as above. The heading is `This machine` or the machine's name,
135
+ with the end of the deployment's path when one machine holds two of the
136
+ view. A heading cannot be selected or folded: the movement keys pass over
137
+ it. A view of one deployment has no heading.
138
+ - **A machine that answered carries the time its rows were read** on its
139
+ heading, at the right: `read 14:03:21`. A row of another machine shows
140
+ what its host reported at that time.
141
+ - **A deployment that is not live carries its state and a short reason**
142
+ on its heading, and no time: `garnet remembered Not reached`. The rows
143
+ a machine last reported are kept when it is not reached, and each of them
144
+ reads `unknown`, with the `?` mark, in the list and in the detail:
145
+ nothing reads as stopped, or as running, that is only not reached.
146
+ - **A deployment that is not live and has no rows** is named after the
147
+ others: the machine, the deployment's path, its state and the short
148
+ reason on one row, and the whole reason on the rows under it.
149
+ - **A deployment's note** is a sentence of the shared rules about that
150
+ deployment, such as `garnet now reports workspace other.` for a machine
151
+ that reported another workspace before, or that a deployment's teams are
152
+ local only. It stands under the deployment's heading. In a view of one
153
+ deployment, which has no heading, it stands above the list.
154
+ - **The detail has a `machine` line**, the machine the selected instance is
155
+ on. When that deployment is not live, the whole sentence that says why
156
+ follows it.
157
+
158
+ **A view that holds no deployment of this machine** says so in its header:
159
+ `oats other on garnet` for one machine, `2 machines` after the name for
160
+ two or more. The time in the header is then the time the machines' rows
161
+ were read. A view of one machine has no heading, so its state, when it is
162
+ not live, is said above the list with the reason, as for a deployment of
163
+ this machine. When no row of that machine is kept either, nothing is drawn
164
+ under the reason: no list and no detail.
165
+
166
+ **A machine that has not answered in this run is not in its workspace's
167
+ list.** `oats tui` keeps nothing on disk, so it cannot tell which workspace
168
+ a machine belongs to before the machine has said so in this run. Such a
169
+ machine is listed in [the switcher](#the-switcher) by its own name, under
170
+ `Not matched to a workspace`. The OATS Desktop, which remembers what each
171
+ machine last reported, can place it. Once a machine has answered, it stays
172
+ in its workspace for the rest of the run, also while it is not reached.
173
+
174
+ | Mark | ASCII | Means |
175
+ |---|---|---|
176
+ | `●` | `*` | running |
177
+ | `○` | `-` | stopped |
178
+ | `◌` | `~` | stopped, with a shell left in its terminal |
179
+ | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
180
+ | `◆` | `#` | held by a spawn or a retire that is not finished |
181
+ | `▾` `▸` | `v` `>` | has instances below it: shown, folded away |
182
+ | `!` | `!` | needs input |
183
+ | `!N` | `!N` | N instances folded away below it need input |
184
+ | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
185
+ | `*` | `*` | in the switcher: the workspace that is open |
186
+
187
+ Every state has a mark of its own shape, so nothing is told by colour alone.
188
+
189
+ **When a read fails,** what the view then shows is one rule, shared with the
190
+ Desktop, and `oats tui` decides none of it. Depending on the failure the
191
+ last rows stay as they were; or they stay and are marked `stale`, with the
192
+ time of the last read that succeeded (a remote that could not be read
193
+ again); or the
194
+ deployment is `not observed` and no row is drawn. A state that is not live
195
+ is said in words above the list, with the reason on rows of its own. When
196
+ the kernel refused the read and no rows are kept, the reason says so and
197
+ quotes it: `OATS answered with an error (<code>). It says: <message>`. When
198
+ the last rows are kept as `stale`, the reason says so and then quotes the
199
+ kernel:
200
+ `This deployment's last read failed. It shows what was last observed. OATS says: <message>`.
201
+ Any other reason is the reader's own sentence.
202
+
203
+ **When the read of the other machines fails,** this machine's rows are not
204
+ touched: they are read on their own. What is shown of the machines depends
205
+ on whether that read has succeeded before in this run:
206
+
207
+ | The read failed | The view shows |
208
+ |---|---|
209
+ | 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 |
210
+ | after it succeeded once | each machine keeps its place and its heading, with its state and a short reason in place of the time; its rows are kept and read `unknown` |
211
+
212
+ The next read that succeeds shows the machines as they then report.
213
+
214
+ Names are cut by terminal cells with `…` (`...` in ASCII) when they do not
215
+ fit; the detail shows them whole.
216
+
217
+ ## The switcher
218
+
219
+ `w` opens the switcher: what this run can show, over the whole body of the
220
+ screen.
221
+
222
+ ```
223
+ oats workspaces
224
+ 1 Instances 2 Souls 3 Capabilities
225
+ ────────────────────────────────────────────────────────────────────────────────
226
+ > * acme-platform This machine · garnet
227
+ ledger quartz
228
+ Not matched to a workspace
229
+ basalt ssh needs a prompt
230
+ On this machine, not opened
231
+ acme-docs ~/Agents/acme-docs
232
+ sandbox ~/Agents/sandbox
233
+
234
+
235
+
236
+ ────────────────────────────────────────────────────────────────────────────────
237
+ Enter open / filter r refresh Esc close ? help q quit
238
+ ```
239
+
240
+ It lists, in this order:
241
+
242
+ - **The workspaces this run knows**, one row each: the name, the machines
243
+ its deployments are on, and at the right edge how many of its deployments
244
+ are not live (`1 deployment not live`). A workspace here is what the
245
+ rules shared with the Desktop make of the deployments opened in this run
246
+ and of what the registered machines answered: the ones that report the
247
+ same workspace are one row. `*` marks the workspace that is open.
248
+ - **`Not matched to a workspace`**: what those rules matched to no
249
+ workspace, each by its own name with a short reason. A machine that has
250
+ not answered in this run is listed here.
251
+ - **`On this machine, not opened`**: the deployments directly inside
252
+ `~/Agents` that this run has not opened, each by its folder's name and
253
+ its path. Nothing is read from one before it is picked. `~/Agents` is
254
+ looked at up to its first 200 entries; when it holds more, a last row says
255
+ `More folders than are listed here.`
256
+
257
+ | Key | Does |
258
+ |---|---|
259
+ | `Up` `k`, `Down` `j`, `g` `Home`, `G` `End`, `PageUp`, `PageDown` | move the selection among the rows; a heading is passed over |
260
+ | `Enter` | opens the selected row |
261
+ | `/` | filters the rows by what they show: a name, the machines, a path |
262
+ | `r` | reads now, and lists `~/Agents` again |
263
+ | `Esc` | clears a kept filter; else closes the switcher, back to the view that was open |
264
+ | `1` | closes the switcher, back to the view that was open |
265
+
266
+ **Enter on a workspace** opens its view. **Enter on a folder** opens that
267
+ deployment in this run: from then on it is read with the others, and its
268
+ workspace is the open view. A folder that stopped being a deployment since
269
+ it was listed is not opened: its row says
270
+ `Not an OATS deployment any more.` where its path stood.
271
+
272
+ **Each view keeps its place while the run lasts:** the selected instance,
273
+ where its list and its detail were scrolled, and what was folded away are
274
+ found again when the view is opened again. A filter is not kept from one
275
+ view to another, and nothing is kept after the run ends.
276
+
277
+ **When the open workspace stops being listed** (it was a machine, and the
278
+ kernel's answer stopped naming it), the switcher is shown with
279
+ `That workspace is no longer listed.` Until a row is opened there is no
280
+ view to go back to, and `Esc` and `1` do not close the switcher. The same
281
+ holds after a start outside every deployment, which opens the switcher with
282
+ nothing open.
283
+
284
+ ## Keys
285
+
286
+ | Key | Does |
287
+ |---|---|
288
+ | `Up` `k`, `Down` `j` | move the selection; with the detail focused, scroll it |
289
+ | `g` `Home`, `G` `End` | first row, last row |
290
+ | `PageUp`, `PageDown` | one page |
291
+ | `Left` `h` | fold the instances below the row away; on a row with none, or already folded, go to its parent |
292
+ | `Right` `l` | show them again; on a row already open, go to its first child |
293
+ | `Tab` | move between the list and the detail; under 80 columns, open and close the detail page |
294
+ | `/` | filter |
295
+ | `r` | read now |
296
+ | `1` | the Instances view |
297
+ | `w` | opens [the switcher](#the-switcher) |
298
+ | `Enter` | in the switcher, opens the selected row |
299
+ | `?` | opens the help; `?` again closes it |
300
+ | `Esc` | closes, in this order: the help, the filter field, a kept filter, then the detail or the switcher |
301
+ | `q`, `Ctrl+C` | quits, with status 0 (a SIGINT from outside answers 130) |
302
+ | `Ctrl+Z` | suspends: the shell gets the terminal back as it was; `fg` returns, redraws and reads at once |
303
+ | `Ctrl+L` | redraws the whole screen, and sets the terminal's modes again if something reset them |
304
+
305
+ The selection stands on instances only, and in the switcher on its rows: a
306
+ heading, a reason and a note are passed over. What stands above the first
307
+ instance or under the last one comes into view with it. When a movement key
308
+ has no instance to go to (the selection is on the first or the last one, or
309
+ the list has none), it scrolls the list instead, so the rows after the last
310
+ instance can always be read, however many they are. The selection stays
311
+ where it is, and the list returns to it at the next key that moves it.
312
+
313
+ In the list of instances `Enter` does nothing. The help screen is generated
314
+ from the table the program acts on, so it always lists the keys that work,
315
+ with the marks and with what this version does not do. The movement keys
316
+ scroll it. `Ctrl+\` does nothing.
317
+
318
+ **The filter.** `/` opens a field on the last row. What you type narrows the
319
+ list to the instances whose name, soul or repository contains it, with the
320
+ instances they were spawned from, whatever is folded away. In the field
321
+ every printable key is text, so `q` and `j` can be typed; `Backspace`
322
+ removes a character, `Enter` keeps the filter and returns to the list
323
+ (the last row then shows it as `/text`), `Esc` clears it. `Ctrl+C`, `Ctrl+Z`
324
+ and `Ctrl+L` still do what they do. The filter holds at most 200
325
+ characters. The switcher has a filter of its own, with the same field: it
326
+ narrows the rows to the ones whose name, machines or path contain the text.
327
+
328
+ **Pasted text is never read as keys.** A paste into the list is dropped
329
+ whole. A paste into the filter field adds its first line, and only when
330
+ that line is plain text; otherwise it adds nothing.
331
+
332
+ The mouse is never needed and never captured: your terminal's own selection
333
+ and scrolling keep working.
334
+
335
+ ## Change the keys: `tui.json`
336
+
337
+ `oats tui` reads `$XDG_CONFIG_HOME/oats/tui.json` when `XDG_CONFIG_HOME` is
338
+ an absolute path, else `~/.config/oats/tui.json`, once, at the start. It
339
+ never writes it. With no file the keys are the ones above.
340
+
341
+ ```json
342
+ { "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false }
343
+ ```
344
+
345
+ - `keys.<action>` is the list of keys of that action. It **replaces** the
346
+ action's keys; an empty list leaves the action with no key. An action you
347
+ do not name keeps its keys.
348
+ - The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
349
+ `collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
350
+ `workspaces`, `open-workspace`, `help`, `close`, `quit`, `suspend` and
351
+ `redraw`. `workspaces` (`w`) opens the switcher and `open-workspace`
352
+ (`enter`) opens its selected row. In an open filter field `Enter` keeps
353
+ the filter, whatever key `open-workspace` has.
354
+ - A key is written as the help shows it, in lower case: `q`, `G`, `?`,
355
+ `space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
356
+ `ctrl+c`, `alt+x`, `shift+tab`, `ctrl+alt+up`. Modifiers come in the order
357
+ `ctrl+`, `alt+`, `shift+`. A terminal sends `Ctrl+H`, `Ctrl+I`, `Ctrl+J`
358
+ and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
359
+ keys of their own.
360
+ - `ascii: true` is `--ascii`.
361
+
362
+ **A file it cannot honour stops the start.** Each problem is one line on
363
+ stderr, the status is 1 and nothing is drawn; it resolves no conflict and
364
+ guesses nothing. It refuses:
365
+
366
+ | The file | The line says |
367
+ |---|---|
368
+ | is not a regular file (a link to one is read), or cannot be read | `it is not a regular file`, `it cannot be read` |
369
+ | is larger than 64 KiB | `it is larger than 64 KiB` |
370
+ | is not one JSON object | `it is not valid JSON`, `it is not one JSON object` |
371
+ | has a setting other than `keys` and `ascii`, or one of the wrong kind | `unknown setting …`, `keys must be an object`, `ascii must be true or false` |
372
+ | names an action that does not exist | `unknown action …`, with the list of actions |
373
+ | gives an action something that is not a list of strings | `… must be a list of key ids` |
374
+ | has a string that is not a key | `the key … of … is not a key id` |
375
+ | names a key whose character cannot be shown (a bidi override, a combining mark on a space) | `… is a key the help cannot name` |
376
+ | gives one key to two actions, your lists and the kept keys together | `the key … is given to … and to …; a key does one thing` |
377
+ | leaves `quit` with no key | `quit has no key; give it one` |
378
+
379
+ A name from the file is repeated in a line only when it is plain printable
380
+ ASCII of at most 40 characters. More than twenty problems are counted, not
381
+ listed.
382
+
383
+ ## What it reads, and what it runs
384
+
385
+ `oats tui` decodes no kernel answer itself: it runs the readers it shares
386
+ with the Desktop (`packages/client/`).
387
+
388
+ - **Every read of a deployment is two kernel commands**,
389
+ `oats status --json` and `oats workspace status --json` for that
390
+ deployment, run with **the kernel it shipped with** (the `bin/oats.mjs` of
391
+ the same install, with the Node that runs the TUI), never an `oats` found
392
+ on `PATH`. Each has 30 seconds and 4 MiB.
393
+ - **Then one probe of the terminals**: a small program of the shared readers
394
+ asks tmux which instances have a live pane (`tmux list-panes`, and `ps`
395
+ for what runs in them). It has 30 seconds. An instance the kernel itself
396
+ reported as unknown is not probed and stays unknown.
397
+ - **Every deployment opened in the run is read each time**, at most two at
398
+ a time.
399
+ - **How often:** 5 seconds after the last read ended; 30 seconds once ten
400
+ minutes have passed without a key; at once on `r`, on the return from a
401
+ suspend and when a row is opened in the switcher. Every read asks tmux
402
+ anew and reads the instances anew, and the time in the header is that
403
+ read's. What a read in the background may reuse is the kernel's own look
404
+ at the workspace's remotes, for up to 60 seconds; `r` asks the kernel to
405
+ look again.
406
+ - **The other machines are one more read**, `oats server roster --json`,
407
+ by the same kernel: one answer for every machine registered on this
408
+ machine. It has 60 seconds and 4 MiB.
409
+ - It is begun together with a read of this machine and never waited for:
410
+ a machine that answers slowly does not hold this machine's rows.
411
+ - One runs at a time. While one is on its way, `r` reads this machine
412
+ again and starts no second one.
413
+ - The next one begins no sooner than 15 seconds after the last one
414
+ ended. Once ten minutes have passed without a key that is 30 seconds,
415
+ because the reads of this machine it begins with are then 30 seconds
416
+ apart.
417
+ - It begins at once, when none is on its way, on `r`, on the return from
418
+ a suspend and when a row is opened in the switcher.
419
+ - A kernel whose version record lists no read of other machines is never
420
+ asked for one, and no other machine is shown.
421
+ - **Two looks at the file system serve the switcher**, and neither reads a
422
+ file's content. At a start outside every deployment with no `--dir`, when
423
+ the switcher opens, and on `r` in it, the entries of `~/Agents` are
424
+ listed: at most 200, and each directory among them is asked for a regular
425
+ `oats-local.yaml`. An entry that is a link is not followed. When a folder
426
+ is opened, that one directory is asked again.
427
+ - **Every child runs in a session of its own** and is ended when the TUI
428
+ ends, on every way out a process can handle (for SIGKILL see
429
+ [below](#what-it-changes-in-your-terminal-and-restores)). A read that was
430
+ running when the TUI is suspended is dropped, not shown: its answer could
431
+ arrive cut. That holds for the read of the other machines too. The return
432
+ reads again.
433
+ - It reads only. It runs no command that changes a deployment or a
434
+ registration, and it writes no file.
435
+
436
+ ## What this version does not do
437
+
438
+ | To | Run |
439
+ |---|---|
440
+ | open an agent's terminal | `oats session attach --home <home>` (the detail shows the home) |
441
+ | stop an agent | `oats instance stop <instance>` |
442
+ | start or restart an agent | `oats session start --home <home>` |
443
+ | retire an agent | `oats retire <instance>` |
444
+ | see souls, spawn an agent | `oats souls`, `oats spawn <soul>` |
445
+ | see capabilities | `oats capabilities` |
446
+ | add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
447
+ | check a machine | `oats server check <id>` |
448
+ | remove a machine | `oats server remove <id>` |
449
+ | open a deployment outside `~/Agents` | `oats tui --dir <path>` |
450
+
451
+ The help screen (`?`) names the same commands. What else holds for this
452
+ version:
453
+
454
+ - **It keeps nothing on disk.** A machine it has not reached in this run is
455
+ listed by its own name, in no workspace. What is folded away and each
456
+ view's place last as long as the run, and no filter is saved.
457
+ - **Of this machine's deployments, the switcher lists only the ones opened
458
+ in this run and the ones directly inside `~/Agents`.** Any other is
459
+ opened with `oats tui --dir <path>`.
460
+ - **A row of another machine shows what its host reported at the last
461
+ read,** not what is true at this moment. The time of that read is on the
462
+ machine's heading. A view of one machine has no heading: there the header
463
+ names the machine (`on garnet`) and carries the time.
464
+ - Souls and Capabilities, when they come, are this machine's.
465
+ - There is no sorting and no mouse, and a deployment's heading cannot be
466
+ folded.
467
+
468
+ ## What it changes in your terminal, and restores
469
+
470
+ This is the complete list. On start, in this order:
471
+
472
+ 1. raw mode on the terminal (keys arrive unbuffered and unechoed);
473
+ 2. the alternate screen (`CSI ?1049h`), so your scrollback is untouched;
474
+ 3. the cursor hidden (`CSI ?25l`);
475
+ 4. autowrap off (`CSI ?7l`);
476
+ 5. bracketed paste on (`CSI ?2004h`).
477
+
478
+ On the way out, the reverse: bracketed paste off, autowrap on, the style
479
+ reset (`CSI 0m`), the cursor shown, the alternate screen left, raw mode off.
480
+
481
+ Two of these have a reason worth stating:
482
+
483
+ - **Autowrap is off** so that no row can wrap when your terminal and the
484
+ TUI's width table disagree about how wide a character is (some emoji and
485
+ some scripts). Each row is positioned on its own and erased to its end, so
486
+ a disagreement stays inside its row.
487
+ - **Bracketed paste is on** so that the terminal marks pasted text as a
488
+ paste, and the TUI can drop it instead of acting on it.
489
+
490
+ The terminal is restored after every way out that a process can handle:
491
+
492
+ | Way out | Exit status |
493
+ |---|---|
494
+ | `q` or `Ctrl+C` | 0 |
495
+ | an internal error (its message is printed after the alternate screen is left) | 1 |
496
+ | SIGINT | 130 |
497
+ | SIGTERM | 143 |
498
+ | SIGHUP, or the terminal going away | 129 |
499
+ | SIGQUIT | 131 |
500
+
501
+ A suspend (`Ctrl+Z`, or SIGTSTP from outside) restores the terminal in full
502
+ before the process stops, and sets the same modes again when it continues.
503
+ It stops the whole foreground process group, as a `Ctrl+Z` does for any
504
+ other program, so `oats tui` started through a wrapper (`sh -c`, `npx`)
505
+ suspends as one job.
506
+
507
+ `Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
508
+ a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
509
+ 130. A script that wraps `oats tui` meets that difference.
510
+
511
+ **SIGKILL cannot be handled.** No process can restore a terminal after
512
+ SIGKILL: the terminal is left in the alternate screen with the cursor hidden
513
+ and autowrap off. Run `reset`. Inside tmux also run `tput rmcup`: measured
514
+ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
515
+ stayed in the alternate screen until `tput rmcup`. Nothing else is left in
516
+ tmux: `oats tui` creates no session, window, option or key binding.
517
+ Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
518
+ read that was in flight runs to its own end. It only reads.
519
+
520
+ ## What it never does
521
+
522
+ - It switches on **no mouse reporting, no focus reporting, no keyboard
523
+ protocol, no keypad or cursor-key mode and no synchronized output**.
524
+ - It writes **no window title, no clipboard sequence, no bell**, and no query
525
+ that expects the terminal to reply.
526
+ - It uses **only your terminal's own sixteen colours** and bold, dim,
527
+ underline and reverse: no 256-colour or RGB value and no background fill,
528
+ so your theme stays the theme. With `NO_COLOR` set and not empty it uses no
529
+ colour at all. Nothing is told by colour alone.
530
+ - It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
531
+ `LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
532
+ no emoji. When the locale is not UTF-8, a character outside ASCII in text
533
+ it shows is drawn as `?`.
534
+ - It **never writes an escape byte to anything that is not a terminal**.
535
+ - It **never writes text it did not author straight to the terminal.** A
536
+ terminal acts on what is written to it, so every string from a kernel
537
+ answer, a repository, an agent or another machine passes one filter before
538
+ it is drawn: text holding a control character or a secret shape is shown
539
+ as `[withheld]`, and bidi controls, invisible characters and C1 controls
540
+ are replaced. The screen accepts only text that went through that filter
541
+ or the TUI's own words. The words that name who gave a reason are the
542
+ shared home's (`packages/client/`), and the TUI writes none of its own
543
+ for a speaker. They never stand before a withheld text: a reason that is
544
+ withheld is `[withheld]` alone.
545
+ - It changes nothing in tmux: no option, key binding, server, session,
546
+ window or pane. Its probe only lists panes.
547
+ - It starts no daemon, opens no socket and writes no file. The processes it
548
+ starts are the reads above, and none outlives it on every way out a
549
+ process can handle; after SIGKILL a read in flight runs to its own end.
550
+
551
+ ## Errors
552
+
553
+ | Error | When | What to do |
554
+ |---|---|---|
555
+ | `E_NO_TERMINAL` | stdin or stdout is not a terminal, or `TERM` is unset, empty or `dumb`. One line on stderr, nothing on stdout, exit 1 | run it in a terminal; `oats status` prints the instances once |
556
+ | `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 |
557
+ | `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` |
558
+ | `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 |
559
+ | `E_NO_DEPLOYMENT` | no directory at or above the start holds an `oats-local.yaml`; and, for a start without `--dir`, `~/Agents` holds no deployment. One line on stderr, exit 1 | `oats tui --dir <path>`, or `cd` into the deployment |
560
+ | `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 |
561
+
562
+ These lines are written before the terminal is touched, in this order: the
563
+ arguments, the terminal, `tui.json`, the deployment, the kernel. None of the
564
+ codes on stderr appears in a JSON envelope. A path is repeated in a line
565
+ only when it is plain printable ASCII.
566
+
567
+ ## Where it has been run
568
+
569
+ So far `oats tui` has been run in tmux only: not in a terminal emulator
570
+ without tmux, and not over ssh.
571
+ The automated tests run the real `oats tui` in tmux (a pane is a real
572
+ terminal: keys and screen are bytes through a pty), on a private tmux server.
573
+ Other terminals and multiplexers are untested so far: that is a statement
574
+ about the tests, not a list of what is supported. If it misbehaves in yours,
575
+ that is a bug worth reporting, with the terminal's name and `TERM`.
576
+
577
+ Another machine is reached only through the kernel's own read
578
+ (`oats server roster`): `oats tui` opens no connection of its own.
579
+
580
+ With a registered machine it has been run only against one that did not
581
+ answer: the switcher lists it by its own name with the reason, and its view
582
+ says that it was not reached. A machine that answers is drawn in the
583
+ automated tests, from the kernel's answer handed to the client; so far no
584
+ person has checked one in a real terminal.