@awebai/oats 0.57.0 → 0.57.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/configuration.md +17 -27
- package/docs/desktop.md +14 -0
- package/docs/execution-targets.md +6 -1
- package/docs/implementation.md +7 -1
- package/docs/integrations.md +3 -1
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/servers.md +18 -0
- package/docs/tui.md +214 -87
- package/docs/workspaces.md +1 -1
- package/lib/session-viewer.mjs +29 -4
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +11 -6
- package/packages/client/spawn-apply.mjs +212 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +152 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/tui/README.md +32 -11
- package/packages/tui/lib/actions.mjs +10 -1
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +165 -57
- package/packages/tui/lib/model.mjs +28 -24
- package/packages/tui/lib/panel.mjs +955 -0
- package/packages/tui/lib/read.mjs +5 -14
- package/packages/tui/lib/store.mjs +77 -30
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/frame.mjs +126 -40
- package/packages/tui/lib/views/help.mjs +12 -10
- package/skills/oats-getting-started/SKILL.md +3 -2
- package/packages/tui/lib/open.mjs +0 -45
package/docs/tui.md
CHANGED
|
@@ -78,7 +78,7 @@ runs.
|
|
|
78
78
|
|
|
79
79
|
```
|
|
80
80
|
oats acme-platform +1 machine 4 running 1 needs input 2 stopped
|
|
81
|
-
|
|
81
|
+
Instances Souls Capabilities read 14:03:27
|
|
82
82
|
──────────────────────────────────────────────┬─────────────────────────────────────────────────
|
|
83
83
|
This machine │ api-lead
|
|
84
84
|
▾ ● backend-lead claude │ soul tech-lead
|
|
@@ -91,7 +91,7 @@ runs.
|
|
|
91
91
|
│
|
|
92
92
|
○ reviewer-api stopped │
|
|
93
93
|
──────────────────────────────────────────────┴─────────────────────────────────────────────────
|
|
94
|
-
/ filter Tab detail r refresh w workspaces ? help q quit
|
|
94
|
+
/ filter Tab detail r refresh w workspaces 1-3 views ? help q quit
|
|
95
95
|
```
|
|
96
96
|
|
|
97
97
|
- **The header** has the workspace's name, then what the view holds of
|
|
@@ -102,10 +102,14 @@ runs.
|
|
|
102
102
|
every row of the view: instances running, instances that need input,
|
|
103
103
|
stopped, state unknown, and rows the kernel reported that were withheld (a
|
|
104
104
|
home outside its soul's directory, or one reported twice). A count of zero
|
|
105
|
-
is left out. The second row names the views
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
105
|
+
is left out. The second row names the views, `Instances Souls
|
|
106
|
+
Capabilities`: the open one is drawn in reverse video, and `Souls` and
|
|
107
|
+
`Capabilities` are dim because they cannot be opened yet. Their keys,
|
|
108
|
+
`1`, `2` and `3`, are not drawn beside the names: the help names each,
|
|
109
|
+
and the footer names the three as one hint, `1-3 views`, which a narrow
|
|
110
|
+
footer gives up right after the acts. `2` and `3` say what to run
|
|
111
|
+
instead. On the right is the time of the read
|
|
112
|
+
of this machine that the screen shows: it moves with every read.
|
|
109
113
|
- **The list** is the roster the Desktop draws: the same groups in the same
|
|
110
114
|
order, from the same code. An instance that others were spawned from
|
|
111
115
|
comes first, and the ones below it are indented under it; instances
|
|
@@ -127,29 +131,9 @@ runs.
|
|
|
127
131
|
branch, team, parent, when it last started, and its home. From 80
|
|
128
132
|
columns up it stands beside the list; on a narrower terminal `Tab` opens
|
|
129
133
|
it as a page.
|
|
130
|
-
- **Opening an agent.** `Enter` on an instance that runs
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
back, and the agent keeps running. The key is yours to change
|
|
134
|
-
([`tui.json`](#change-the-keys-tuijson)), and the footer names it whenever
|
|
135
|
-
`Enter` would open.
|
|
136
|
-
- Inside tmux the agent opens in the same pane. `oats tui` makes no window
|
|
137
|
-
and no split.
|
|
138
|
-
- After the return the instances are read again at once, and one line
|
|
139
|
-
says what happened: that you left and the agent keeps running, that it
|
|
140
|
-
could not be opened, or that the connection to its machine ended. When
|
|
141
|
-
the agent's own terminal ended while you were in it, you are back with
|
|
142
|
-
no line: the list shows the agent as it now is.
|
|
143
|
-
- What `oats session attach` printed when it failed stands under that line
|
|
144
|
-
in quotation marks. It is not said who printed it: OATS, tmux and ssh
|
|
145
|
-
all can.
|
|
146
|
-
- `Enter` on an instance that cannot be opened opens nothing and says why:
|
|
147
|
-
it does not run, whether it runs is not known, the detail's reason holds
|
|
148
|
-
it, or its machine's OATS is older than 0.51.0 and has no key to leave a
|
|
149
|
-
viewer.
|
|
150
|
-
- For each time you open an agent, one line of tmux's own stays on your
|
|
151
|
-
screen and is there after you quit: `[detached (from session …)]`, or
|
|
152
|
-
`[exited]`.
|
|
134
|
+
- **Opening an agent.** `Enter` on an instance that runs opens its terminal
|
|
135
|
+
beside the list, where the detail was: see
|
|
136
|
+
[Open an agent's terminal](#open-an-agents-terminal).
|
|
153
137
|
|
|
154
138
|
**A view of more than one deployment** (this machine and another, or two
|
|
155
139
|
deployments on one machine) is one list, grouped as the Desktop groups it:
|
|
@@ -238,6 +222,78 @@ The next read that succeeds shows the machines as they then report.
|
|
|
238
222
|
Names are cut by terminal cells with `…` (`...` in ASCII) when they do not
|
|
239
223
|
fit; the detail shows them whole.
|
|
240
224
|
|
|
225
|
+
## Open an agent's terminal
|
|
226
|
+
|
|
227
|
+
```
|
|
228
|
+
oats acme-platform 2 running
|
|
229
|
+
Instances Souls Capabilities read 14:03:27
|
|
230
|
+
──────────────────────────────────────┬─────────────────────────────────────────
|
|
231
|
+
> ● backend-lead claude │ backend-lead
|
|
232
|
+
● docs-writer claude │$ make docs
|
|
233
|
+
│Building the reference...
|
|
234
|
+
│
|
|
235
|
+
──────────────────────────────────────┴─────────────────────────────────────────
|
|
236
|
+
C-\ back to the list
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
- **`Enter` on an instance that runs** opens its terminal on the right of
|
|
240
|
+
the body, where the detail was, with the list on the left. Its top row
|
|
241
|
+
names the agent (and `on <machine>` for one of another machine); under it
|
|
242
|
+
is the agent's screen, as the agent draws it, in its own colours.
|
|
243
|
+
- **The terminal has the focus.** What you type, what you paste and every
|
|
244
|
+
key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
|
|
245
|
+
among them, but for **the back key** (`Ctrl+\` unless
|
|
246
|
+
[`tui.json`](#change-the-keys-tuijson) names another). The back key gives
|
|
247
|
+
the focus to the list. While the terminal has the focus the footer names
|
|
248
|
+
only that key: `C-\ back to the list`. A back key inside a paste is
|
|
249
|
+
pasted, not taken.
|
|
250
|
+
- **With the list focused** the terminal stays open, and the agent's screen
|
|
251
|
+
is still drawn as it changes. The footer names the keys for it:
|
|
252
|
+
`Enter focus terminal` on its row, `z zoom` and `c close terminal`.
|
|
253
|
+
- `Enter` on the open terminal's row gives it the focus again.
|
|
254
|
+
- `z` gives it the focus and the whole body: the header and the footer
|
|
255
|
+
stay, the list is hidden. The back key brings the list back beside it.
|
|
256
|
+
- `c` closes it: the agent keeps running, and the right side is the
|
|
257
|
+
detail again.
|
|
258
|
+
- `Tab` shows the detail in its place until `Tab` or `Esc`. Nothing of
|
|
259
|
+
the terminal is drawn meanwhile, and its screen is read afresh when it
|
|
260
|
+
shows again.
|
|
261
|
+
- **One terminal is open at a time.** `Enter` on another instance that runs
|
|
262
|
+
closes the open one and opens that one.
|
|
263
|
+
- **Under 80 columns** the terminal is always shown with the whole body
|
|
264
|
+
when it has the focus. With the list focused the list is shown alone; the
|
|
265
|
+
terminal stays open, unseen, and `Enter focus terminal` in the footer
|
|
266
|
+
shows it again. Beside the list the terminal is never narrower than 40
|
|
267
|
+
columns.
|
|
268
|
+
- **A terminal also closes by itself** when its viewer ends: the agent's
|
|
269
|
+
window ended, its session went away, or the link to its machine dropped.
|
|
270
|
+
It closes within a second of that (tmux tells `oats tui` of a viewer's
|
|
271
|
+
end once a second). The instances are then read again at once, and one line above the panes
|
|
272
|
+
says what happened: that it could not be opened, that the connection to
|
|
273
|
+
its machine ended, or that the viewer ended without saying why. What the
|
|
274
|
+
viewer printed on its error output stands under that line in quotation
|
|
275
|
+
marks, without saying who printed it: OATS, tmux and ssh all can. When
|
|
276
|
+
the viewer ended cleanly there is no line, and a terminal you closed
|
|
277
|
+
yourself says nothing. **A terminal is never opened again by itself**:
|
|
278
|
+
`Enter` opens it.
|
|
279
|
+
- **`Enter` on an instance that cannot be opened** opens nothing and says
|
|
280
|
+
why: it does not run, whether it runs is not known, or the detail's
|
|
281
|
+
reason holds it. An agent on another machine is asked first whether it
|
|
282
|
+
can be opened (`Esc` gives that up); a machine whose OATS cannot open its
|
|
283
|
+
sessions is said then.
|
|
284
|
+
- **No scrollback but the viewer's own, and no mouse.** The panel shows
|
|
285
|
+
what the agent's window shows now; what has scrolled away is reached as
|
|
286
|
+
the agent's own terminal reaches it.
|
|
287
|
+
- **How it works.** The terminal is the kernel's own viewer,
|
|
288
|
+
`oats session attach`, run in a pane of a tmux server private to this run
|
|
289
|
+
of `oats tui`: its socket is in a directory of the run's own (mode 0700,
|
|
290
|
+
under the system's temporary directory), it reads no tmux configuration
|
|
291
|
+
of yours, and it has no prefix key, no key binding and no status line.
|
|
292
|
+
`oats tui` reads that pane's screen when tmux says it changed, never on a
|
|
293
|
+
timer: an idle terminal costs no frame. Inside tmux nothing changes: the
|
|
294
|
+
agent opens in the TUI's panel, and `oats tui` makes no window and no
|
|
295
|
+
split in your tmux.
|
|
296
|
+
|
|
241
297
|
## The switcher
|
|
242
298
|
|
|
243
299
|
`w` opens the switcher: what this run can show, over the whole body of the
|
|
@@ -406,8 +462,12 @@ The exit status never depends on it.
|
|
|
406
462
|
| `/` | filter |
|
|
407
463
|
| `r` | read now |
|
|
408
464
|
| `1` | the Instances view |
|
|
465
|
+
| `2`, `3` | the Souls and Capabilities views: not in this version, so a line says what to run instead |
|
|
409
466
|
| `w` | opens [the switcher](#the-switcher) |
|
|
410
|
-
| `Enter` | in the list of instances, opens the selected agent's terminal; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
|
|
467
|
+
| `Enter` | in the list of instances, opens the selected agent's terminal beside the list, or gives it the focus when it is the open one; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
|
|
468
|
+
| `z` | gives the open terminal the focus and the whole body |
|
|
469
|
+
| `c` | closes the open terminal; the agent keeps running |
|
|
470
|
+
| `Ctrl+\` | while a terminal has the focus, the back key: the focus goes to the list ([`tui.json`](#change-the-keys-tuijson) can name another) |
|
|
411
471
|
| `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
|
|
412
472
|
| `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
|
|
413
473
|
| `Space` | in a confirmation, switches the plan's choice |
|
|
@@ -427,8 +487,9 @@ where it is, and the list returns to it at the next key that moves it.
|
|
|
427
487
|
|
|
428
488
|
The help screen is generated from the table the program acts on, so it
|
|
429
489
|
always lists the keys that work, with the marks and with what this version
|
|
430
|
-
does not do. The movement keys scroll it. While
|
|
431
|
-
|
|
490
|
+
does not do. The movement keys scroll it. While a terminal has the focus
|
|
491
|
+
the table's keys are the agent's: the back key alone is the TUI's. With the
|
|
492
|
+
list focused the back key does nothing.
|
|
432
493
|
|
|
433
494
|
**The filter.** `/` opens a field on the last row. What you type narrows the
|
|
434
495
|
list to the instances whose name, soul or repository contains it, with the
|
|
@@ -462,10 +523,12 @@ never writes it. With no file the keys are the ones above.
|
|
|
462
523
|
do not name keeps its keys.
|
|
463
524
|
- The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
|
|
464
525
|
`collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
|
|
465
|
-
`
|
|
466
|
-
`
|
|
467
|
-
|
|
468
|
-
|
|
526
|
+
`souls`, `capabilities`, `workspaces`, `open`, `zoom`, `close-terminal`,
|
|
527
|
+
`stop`, `retire`, `start`, `restart`, `help`, `close`, `quit`, `suspend`
|
|
528
|
+
and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
|
|
529
|
+
opens the selected agent's terminal in the list of instances and the
|
|
530
|
+
selected row in the switcher. `zoom` (`z`) and `close-terminal` (`c`) act
|
|
531
|
+
on the open terminal. In an open filter field `Enter` keeps the filter,
|
|
469
532
|
whatever key `open` has.
|
|
470
533
|
- A key is written as the help shows it, in lower case: `q`, `G`, `?`,
|
|
471
534
|
`space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
|
|
@@ -474,12 +537,15 @@ never writes it. With no file the keys are the ones above.
|
|
|
474
537
|
and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
|
|
475
538
|
keys of their own.
|
|
476
539
|
- `ascii: true` is `--ascii`.
|
|
477
|
-
- `open.detachKey` is the key
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
540
|
+
- `open.detachKey` is **the back key**: the key that takes the focus from
|
|
541
|
+
an agent's terminal back to the list, `C-\` when you name none. It is
|
|
542
|
+
`oats tui`'s own and never reaches the agent or the kernel. It is one of
|
|
543
|
+
these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
|
|
544
|
+
terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
|
|
545
|
+
`]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
|
|
546
|
+
alone or with one of `C-`, `M-`, `S-` (`C-F5`). These are the keys a
|
|
547
|
+
`tui.json` written for an earlier version could name, with the same
|
|
548
|
+
meaning for the key.
|
|
483
549
|
|
|
484
550
|
**A file it cannot honour stops the start.** Each problem is one line on
|
|
485
551
|
stderr, the status is 1 and nothing is drawn; it resolves no conflict and
|
|
@@ -492,9 +558,7 @@ guesses nothing. It refuses:
|
|
|
492
558
|
| is not one JSON object | `it is not valid JSON`, `it is not one JSON object` |
|
|
493
559
|
| has a setting other than `keys`, `ascii` and `open`, or one of the wrong kind | `unknown setting …`, `keys must be an object`, `ascii must be true or false`, `open must be an object` |
|
|
494
560
|
| has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
|
|
495
|
-
| gives `open.detachKey`
|
|
496
|
-
| gives `open.detachKey` a value that begins with `-` | `open.detachKey cannot begin with -` |
|
|
497
|
-
| gives `open.detachKey` a value the help would draw as another key (a run of spaces, a space at an end) | `open.detachKey is a key the help cannot name` |
|
|
561
|
+
| gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
|
|
498
562
|
| names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
|
|
499
563
|
| names an action that does not exist | `unknown action …`, with the list of actions |
|
|
500
564
|
| gives an action something that is not a list of strings | `… must be a list of key ids` |
|
|
@@ -552,16 +616,54 @@ with the Desktop (`packages/client/`).
|
|
|
552
616
|
`oats-local.yaml`. An entry that is a link is not followed. When a folder
|
|
553
617
|
is opened, that one directory is asked again.
|
|
554
618
|
- **Opening an agent runs one more command,** `oats session attach --home
|
|
555
|
-
<home
|
|
556
|
-
terminal
|
|
557
|
-
<id> --home <home>
|
|
558
|
-
|
|
559
|
-
|
|
619
|
+
<home>`, by the same kernel, in a pane of the run's private tmux server
|
|
620
|
+
([above](#open-an-agents-terminal)), with no key of its own. For an agent
|
|
621
|
+
on another machine `oats session inspect --server <id> --home <home>
|
|
622
|
+
--json` is asked first (20 seconds), then `oats session attach --server
|
|
623
|
+
<id> --home <home>`. The reads go on while a terminal is open, and the end
|
|
624
|
+
of a viewer reads at once.
|
|
625
|
+
- **The private tmux server** is `tmux` found on `PATH`, 3.2 or later. It
|
|
626
|
+
is started at the first open of a run, with `-f /dev/null` and the
|
|
627
|
+
environment's `TMUX` and `TMUX_PANE` removed, and its socket in the run's
|
|
628
|
+
own directory. The control client that `oats tui` keeps for the run
|
|
629
|
+
starts it, with `exit-unattached` set in the same command. Its first window is a keeper: it
|
|
630
|
+
watches `alive`, a FIFO in the run's directory (0600, made with the
|
|
631
|
+
system's `mkfifo`) that `oats tui` holds open for writing until it ends.
|
|
632
|
+
When `oats tui` is gone, whatever ended it and at any moment, the keeper
|
|
633
|
+
kills the server. The keeper needs two things from the base system,
|
|
634
|
+
found on `PATH` like `tmux`.
|
|
635
|
+
- **`mkfifo`** makes `alive`. Without it an open is refused: the line
|
|
636
|
+
says the terminal could not be opened, with what was said under it.
|
|
637
|
+
- **A way to tell that the server is still its parent.** The keeper reads
|
|
638
|
+
that from `/proc` where the system has one (Linux), and otherwise asks
|
|
639
|
+
`ps -o ppid= -p` (macOS). With neither (no `/proc`, and no `ps` or one
|
|
640
|
+
that refuses `-p`, like BusyBox's), the keeper kills nothing. A normal
|
|
641
|
+
end is not affected. An `oats tui` killed with SIGKILL can then leave
|
|
642
|
+
its private server running, with the open terminal's viewer still
|
|
643
|
+
attached to the agent, until you end it with `tmux -S
|
|
644
|
+
<run directory>/tmux kill-server`. The next run's sweep leaves that
|
|
645
|
+
directory alone while its socket answers.
|
|
646
|
+
|
|
647
|
+
Each open is a window of the server, whose process is the viewer itself,
|
|
648
|
+
with no shell between them. It is closed with `kill-pane`, which hangs up
|
|
649
|
+
the viewer's terminal: the viewer gets SIGHUP at once and removes its own
|
|
650
|
+
session on the agents' server. The viewer's error output goes to a file
|
|
651
|
+
of the run's directory (0600), read back when it ends and deleted. Its
|
|
652
|
+
exit status is the one tmux keeps for a pane whose process ended
|
|
653
|
+
(`remain-on-exit`), which the server reports to `oats tui` within a
|
|
654
|
+
second; `oats tui` then closes that pane. What the terminal
|
|
655
|
+
shows is captured into `capture` in that directory, which the server
|
|
656
|
+
writes and `oats tui` reads back, so nothing an agent prints passes
|
|
657
|
+
through the stream on which `oats tui` reads the server's answers. An
|
|
658
|
+
answer the server would never give ends that stream, and the open
|
|
659
|
+
terminal closes with it. The server is ended
|
|
660
|
+
on every way out a process can handle. At its start a run also removes
|
|
661
|
+
what a run that is gone left (below), and nothing else: it signals
|
|
662
|
+
nothing.
|
|
560
663
|
- **Every read runs in a session of its own** and is ended when the TUI
|
|
561
664
|
ends, on every way out a process can handle (for SIGKILL see
|
|
562
|
-
[below](#what-it-changes-in-your-terminal-and-restores)).
|
|
563
|
-
|
|
564
|
-
agent has the terminal. A read that was
|
|
665
|
+
[below](#what-it-changes-in-your-terminal-and-restores)). An open
|
|
666
|
+
terminal's viewer ends with the private server. A read that was
|
|
565
667
|
running when the TUI is suspended is dropped, not shown: its answer could
|
|
566
668
|
arrive cut. That holds for the read of the other machines too. The return
|
|
567
669
|
reads again.
|
|
@@ -582,7 +684,14 @@ with the Desktop (`packages/client/`).
|
|
|
582
684
|
apply's answer for 10 minutes and for a start's for 60 seconds; then it
|
|
583
685
|
says so, and the change goes on.
|
|
584
686
|
- It runs no other command that changes a deployment or a registration, and
|
|
585
|
-
it writes no other file
|
|
687
|
+
it writes no other file but the private server's: its socket `tmux`, the
|
|
688
|
+
keeper's FIFO `alive`, `capture` (the open terminal's screen, which the
|
|
689
|
+
server writes there for `oats tui` to read), and `owner.json` (`{ "tool":
|
|
690
|
+
"oats-tui", "pid": …, "started": … }`), which lets a later run tell a
|
|
691
|
+
directory a run that is gone left. A run that ends normally removes all
|
|
692
|
+
four. A later run removes such a directory, these four files included, when its `pid` is not alive
|
|
693
|
+
and its socket answers no tmux; it looks only at directories named `oats-tui-*` in the
|
|
694
|
+
system's temporary directory, yours, of mode 0700, holding that file.
|
|
586
695
|
|
|
587
696
|
## What this version does not do
|
|
588
697
|
|
|
@@ -612,7 +721,8 @@ version:
|
|
|
612
721
|
names the machine (`on garnet`) and carries the time.
|
|
613
722
|
- Souls and Capabilities, when they come, are this machine's.
|
|
614
723
|
- There is no sorting and no mouse, and a deployment's heading cannot be
|
|
615
|
-
folded.
|
|
724
|
+
folded. An open terminal has no scrollback but the viewer's own.
|
|
725
|
+
- One terminal is open at a time; tabs of several come in a later version.
|
|
616
726
|
- With an OATS older than 0.52.0, after an interrupted stop the instance can
|
|
617
727
|
be started and then cannot be stopped while `.oats-stop-pending.json` exists
|
|
618
728
|
in its home.
|
|
@@ -630,6 +740,17 @@ This is the complete list. On start, in this order:
|
|
|
630
740
|
On the way out, the reverse: bracketed paste off, autowrap on, the style
|
|
631
741
|
reset (`CSI 0m`), the cursor shown, the alternate screen left, raw mode off.
|
|
632
742
|
|
|
743
|
+
While it draws:
|
|
744
|
+
|
|
745
|
+
- **every frame is one synchronized update**: it begins with
|
|
746
|
+
`CSI ?2026h` and ends with `CSI ?2026l`, so a terminal that knows the
|
|
747
|
+
mode shows the frame whole and one that does not ignores it. The mode is
|
|
748
|
+
set and reset inside each frame and is never left on; a frame with
|
|
749
|
+
nothing to change writes nothing;
|
|
750
|
+
- **while an agent's terminal has the focus the cursor is shown**
|
|
751
|
+
(`CSI ?25h`) where the agent's is, when the agent shows one, and hidden
|
|
752
|
+
again (`CSI ?25l`) when the focus leaves it.
|
|
753
|
+
|
|
633
754
|
Two of these have a reason worth stating:
|
|
634
755
|
|
|
635
756
|
- **Autowrap is off** so that no row can wrap when your terminal and the
|
|
@@ -656,15 +777,11 @@ It stops the whole foreground process group, as a `Ctrl+Z` does for any
|
|
|
656
777
|
other program, so `oats tui` started through a wrapper (`sh -c`, `npx`)
|
|
657
778
|
suspends as one job.
|
|
658
779
|
|
|
659
|
-
**While an agent
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
viewer leaves, is that signal). SIGINT, SIGTERM and SIGHUP end the viewer
|
|
665
|
-
first and then `oats tui`, with the status of the table above. A viewer
|
|
666
|
-
that has not ended 3 seconds after it was asked, or at a second signal, is
|
|
667
|
-
left as it is, and `oats tui` ends without it.
|
|
780
|
+
**While an agent's terminal is open** the terminal stays `oats tui`'s: the
|
|
781
|
+
viewer draws into the private server's pane, never into your terminal, and
|
|
782
|
+
`oats tui` draws what that pane shows. Every way out in the table above ends
|
|
783
|
+
the private server and with it the viewer, with that status. A suspend
|
|
784
|
+
leaves the server and its viewer running; `fg` draws the terminal afresh.
|
|
668
785
|
|
|
669
786
|
`Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
|
|
670
787
|
a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
|
|
@@ -677,20 +794,28 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
|
|
|
677
794
|
stayed in the alternate screen until `tput rmcup`. Nothing else is left in
|
|
678
795
|
tmux: `oats tui` creates no session, window, option or key binding.
|
|
679
796
|
Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
|
|
680
|
-
read that was in flight runs to its own end.
|
|
681
|
-
|
|
682
|
-
|
|
797
|
+
read that was in flight runs to its own end. An open terminal's private
|
|
798
|
+
server is ended by its keeper as soon as `oats tui` is gone, so the viewer's
|
|
799
|
+
terminal hangs up and the viewer removes its own session. A stopped `oats tui`
|
|
800
|
+
(`Ctrl+Z`, SIGSTOP) still holds the keeper's FIFO, so its server is left
|
|
801
|
+
alone. The next run removes the directory that is left, with its `tmux`,
|
|
802
|
+
`alive`, `capture` and `owner.json`.
|
|
683
803
|
|
|
684
804
|
## What it never does
|
|
685
805
|
|
|
686
806
|
- It switches on **no mouse reporting, no focus reporting, no keyboard
|
|
687
|
-
protocol
|
|
807
|
+
protocol and no keypad or cursor-key mode**, and leaves no synchronized
|
|
808
|
+
update on between frames.
|
|
688
809
|
- It writes **no window title, no clipboard sequence, no bell**, and no query
|
|
689
810
|
that expects the terminal to reply.
|
|
690
|
-
-
|
|
691
|
-
underline and reverse: no 256-colour or RGB value and no
|
|
692
|
-
so your theme stays the theme.
|
|
693
|
-
|
|
811
|
+
- **Its own words and marks use only your terminal's own sixteen colours**
|
|
812
|
+
and bold, dim, underline and reverse: no 256-colour or RGB value and no
|
|
813
|
+
background fill, so your theme stays the theme. An open terminal shows
|
|
814
|
+
the agent's screen in the agent's own colours (256-colour and RGB
|
|
815
|
+
included) and attributes: those are the agent's. With `NO_COLOR` set and
|
|
816
|
+
not empty it uses no colour at all, the agent's included; the agent's
|
|
817
|
+
bold, underline, reverse and the like stay. Nothing is told by colour
|
|
818
|
+
alone.
|
|
694
819
|
- It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
|
|
695
820
|
`LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
|
|
696
821
|
no emoji. When the locale is not UTF-8, a character outside ASCII in text
|
|
@@ -706,23 +831,25 @@ in your shell.
|
|
|
706
831
|
shared home's (`packages/client/`), and the TUI writes none of its own
|
|
707
832
|
for a speaker. They never stand before a withheld text: a reason that is
|
|
708
833
|
withheld is `[withheld]` alone.
|
|
709
|
-
- It changes nothing in tmux
|
|
710
|
-
session, window or pane. Its probe only lists panes. An agent's
|
|
711
|
-
session is started, ended or restarted only by the kernel's commands
|
|
712
|
-
an act you confirmed
|
|
834
|
+
- It changes nothing in your tmux or the agents': no option, key binding,
|
|
835
|
+
server, session, window or pane. Its probe only lists panes. An agent's
|
|
836
|
+
own session is started, ended or restarted only by the kernel's commands
|
|
837
|
+
of an act you confirmed
|
|
713
838
|
([above](#stopping-starting-restarting-and-retiring)), and an agent's
|
|
714
839
|
terminal is opened by `oats session attach`, which makes its own viewer
|
|
715
|
-
session on the agents' tmux server and removes it
|
|
716
|
-
|
|
717
|
-
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
when
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
runs to its own end
|
|
840
|
+
session on the agents' tmux server and removes it. The one tmux server
|
|
841
|
+
`oats tui` runs is its own private one
|
|
842
|
+
([above](#open-an-agents-terminal)), and it never looks at another's
|
|
843
|
+
socket but to ask whether a dead run's still answers.
|
|
844
|
+
- It starts no daemon, and writes no file but the output of a change and
|
|
845
|
+
its private server's own, in its own directory
|
|
846
|
+
([above](#what-it-reads-and-what-it-runs)). The processes it starts are
|
|
847
|
+
the reads above, when you open an agent its private tmux server and the
|
|
848
|
+
viewer in it, and the acts you confirm. No read, server or viewer
|
|
849
|
+
outlives it on every way out a process can handle; after SIGKILL a read
|
|
850
|
+
in flight runs to its own end, and the private server and its viewer end
|
|
851
|
+
by themselves. An act you confirmed is never ended by `oats tui`: it runs
|
|
852
|
+
to its own end.
|
|
726
853
|
|
|
727
854
|
## Errors
|
|
728
855
|
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
57
|
+
oats.framework: v1.12.0 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.2.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
package/lib/session-viewer.mjs
CHANGED
|
@@ -54,8 +54,12 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
|
|
|
54
54
|
if (!inspectSessionTarget(target, { exec }).present) throw new Error("session no longer exists");
|
|
55
55
|
// UTF-8 mode (-u) like the shared session helper: a service without a
|
|
56
56
|
// UTF-8 locale (launchd) otherwise mangles tmux output.
|
|
57
|
+
// Each call in a session and process group of its own (`detached`): a hang-up, termination or
|
|
58
|
+
// interrupt sent to the attach's group (a pty hang-up once a wrapping shell has died, a C-c)
|
|
59
|
+
// must not kill a call in flight, the cleanup's kill-session first of all (#1243). The client the
|
|
60
|
+
// attach spawns is not one of these: it stays in the terminal's foreground group.
|
|
57
61
|
const run = (args) => exec("tmux", ["-u", "-S", target.socket, ...args], {
|
|
58
|
-
encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
|
|
62
|
+
encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"], detached: true,
|
|
59
63
|
}).trim();
|
|
60
64
|
const viewer = `oatsview-${process.pid}-${randomUUID().slice(0, 8)}`;
|
|
61
65
|
// A keyed viewer reads a table of its own, named as its session: a binding in the locked table
|
|
@@ -80,6 +84,10 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
|
|
|
80
84
|
// Session-scoped on the temporary viewer: the agents' own session and
|
|
81
85
|
// the operator's tmux settings are untouched.
|
|
82
86
|
run(["set-option", "-t", viewer, "status", "off"]);
|
|
87
|
+
// When the agent's window ends (a retire), the viewer has no window left and tmux destroys it.
|
|
88
|
+
// The viewer's client must then leave, not be moved: under an operator's `detach-on-destroy off`
|
|
89
|
+
// tmux would switch it to another session, another agent's terminal (#1237).
|
|
90
|
+
run(["set-option", "-t", viewer, "detach-on-destroy", "on"]);
|
|
83
91
|
run(["unbind-key", "-a", "-q", "-T", table]);
|
|
84
92
|
for (const binding of MOUSE_BINDINGS) run(["bind-key", "-T", table, ...binding]);
|
|
85
93
|
// The key is its own argv element, after the grammar admitted it.
|
|
@@ -126,17 +134,32 @@ function holdQuit() {
|
|
|
126
134
|
* SESSION_DETACHED_EXIT when `detachKey` was given and ended the attach. */
|
|
127
135
|
export async function attachSessionTarget(target, { detachKey } = {}) {
|
|
128
136
|
if (detachKey !== undefined) { requireDetachKey(detachKey); holdQuit(); }
|
|
129
|
-
|
|
137
|
+
// HUP, TERM and INT are held from before the viewer session exists until its cleanup has
|
|
138
|
+
// finished: one that arrives in between, early or late, finds a listener and not the default
|
|
139
|
+
// action, which would end Node with the session left on the agents' server (#1243). Node runs
|
|
140
|
+
// the listener only between synchronous runs, so it may find no viewer yet, or no client.
|
|
141
|
+
let viewer = null;
|
|
130
142
|
let child;
|
|
143
|
+
let stopped = false;
|
|
131
144
|
let quit = false;
|
|
132
|
-
const stop = () => { viewer
|
|
145
|
+
const stop = () => { stopped = true; viewer?.cleanup(); child?.kill(); };
|
|
133
146
|
const signals = ["SIGHUP", "SIGTERM", "SIGINT"];
|
|
134
147
|
for (const sig of signals) process.on(sig, stop);
|
|
148
|
+
// A preparation that fails has already removed what it made.
|
|
149
|
+
try { viewer = prepareSessionViewer(target, { detachKey }); }
|
|
150
|
+
catch (e) { for (const sig of signals) process.removeListener(sig, stop); throw e; }
|
|
135
151
|
// Until the client has exited, a QUIT stops the attach as the other signals do, with status 1.
|
|
136
152
|
// Unless the key's binding has already run: then the client is on its way out, the QUIT is the
|
|
137
153
|
// key pressed again, and the attach ends as a detach.
|
|
138
154
|
if (detachKey !== undefined) onQuit = () => { if (viewer.detached()) return; quit = true; stop(); };
|
|
139
155
|
try {
|
|
156
|
+
// A signal received during the synchronous preparation is dispatched only in a poll phase of
|
|
157
|
+
// the event loop. Two setImmediate hops run at least one, wherever this attach was called
|
|
158
|
+
// from, so such a signal stops the attach here, before a client takes the terminal: one loop
|
|
159
|
+
// turn per attach. Stopped by then, the viewer ended without the key, and with no client to
|
|
160
|
+
// set the marker a keyed viewer answers 0 too; a QUIT answers 1, as it does with a client.
|
|
161
|
+
for (let hop = 0; hop < 2; hop++) await new Promise((resolve) => setImmediate(resolve));
|
|
162
|
+
if (stopped) return quit ? 1 : 0;
|
|
140
163
|
const code = await new Promise((resolve, reject) => {
|
|
141
164
|
child = spawn(viewer.binary, viewer.args, { env: viewer.env, stdio: "inherit" });
|
|
142
165
|
child.once("error", reject);
|
|
@@ -148,7 +171,9 @@ export async function attachSessionTarget(target, { detachKey } = {}) {
|
|
|
148
171
|
// The client has exited (or never started): a QUIT from here on changes nothing. One that
|
|
149
172
|
// arrives during the calls below waits for them, so cleanup completes and the status stands.
|
|
150
173
|
onQuit = null;
|
|
151
|
-
for (const sig of signals) process.removeListener(sig, stop);
|
|
152
174
|
viewer.cleanup();
|
|
175
|
+
// Only now: a HUP, TERM or INT that arrived during the cleanup was taken by the listener, and
|
|
176
|
+
// its calls, in groups of their own, ran to the end. The status stands.
|
|
177
|
+
for (const sig of signals) process.removeListener(sig, stop);
|
|
153
178
|
}
|
|
154
179
|
}
|
package/package-catalog.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.57.
|
|
3
|
+
"version": "0.57.1",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -500,11 +500,13 @@ export function launchChoiceArgv({ launchConfig, harness, model, yolo, harnessFl
|
|
|
500
500
|
|
|
501
501
|
/** `execFile`'s shape, return and errors, for a child in a session of its own (`detached`: a new session and
|
|
502
502
|
* process group). `execFile` drops `detached`, so this is the `exec` a kernel caller of this home uses for a
|
|
503
|
-
* stop or retire apply and a
|
|
504
|
-
* ends the child with `killSignal` (SIGTERM) when `timeout` (0: none) passes or an output passes
|
|
505
|
-
* and calls back once the child's streams close: `(null, stdout, stderr)` on a clean exit; else an
|
|
506
|
-
* `code` (the exit status, or a system code), `killed` and `signal`, or the overflow's own error,
|
|
507
|
-
* is ERR_CHILD_PROCESS_STDIO_MAXBUFFER.
|
|
503
|
+
* stop or retire apply, a start and a spawn apply. Like `execFile` it collects stdout and stderr (`encoding`,
|
|
504
|
+
* default utf8), ends the child with `killSignal` (SIGTERM) when `timeout` (0: none) passes or an output passes
|
|
505
|
+
* `maxBuffer`, and calls back once the child's streams close: `(null, stdout, stderr)` on a clean exit; else an
|
|
506
|
+
* Error with `code` (the exit status, or a system code), `killed` and `signal`, or the overflow's own error,
|
|
507
|
+
* whose `code` is ERR_CHILD_PROCESS_STDIO_MAXBUFFER. A child its `timeout` killed is never a clean exit, even
|
|
508
|
+
* when it then exits 0: the Error has `killed: true`, and stdout and stderr are still passed (execFile's kill
|
|
509
|
+
* destroys them first). stdin is a pipe, as `execFile`'s, that nobody writes. */
|
|
508
510
|
export function execFileInSession(bin, argv, options = {}, callback = () => {}) {
|
|
509
511
|
const { cwd, env, encoding = "utf8", timeout = 0, maxBuffer = 1024 * 1024, killSignal = "SIGTERM" } = options;
|
|
510
512
|
const child = spawn(bin, argv, { cwd, env, shell: false, detached: true, windowsHide: true });
|
|
@@ -515,7 +517,7 @@ export function execFileInSession(bin, argv, options = {}, callback = () => {})
|
|
|
515
517
|
function exit(code = null, signal = null) {
|
|
516
518
|
if (exited) return; exited = true; clearTimeout(timer);
|
|
517
519
|
const stdout = text("stdout"), stderr = text("stderr");
|
|
518
|
-
if (!ex && code === 0 && signal === null) { callback(null, stdout, stderr); return; }
|
|
520
|
+
if (!ex && !killed && code === 0 && signal === null) { callback(null, stdout, stderr); return; }
|
|
519
521
|
const cmd = [bin, ...argv].join(" ");
|
|
520
522
|
if (!ex) ex = Object.assign(new Error(`Command failed: ${cmd}\n${stderr}`), { code, killed: child.killed || killed, signal });
|
|
521
523
|
ex.cmd = cmd; callback(ex, stdout, stderr);
|
|
@@ -643,7 +645,7 @@ export async function cliCapability(bin, { action, context, server, soul, agents
|
|
|
643
645
|
if (!validMaxAge(maxAge)) bad('Invalid observation age');
|
|
644
646
|
// --instructions (feature soul-composed-instructions) composes a soul's AGENTS.md: inspect --soul only; a CLI that
|
|
645
647
|
// does not advertise it gets the flagless argv. Routed with --server, the caller asks only for a host whose roster
|
|
646
|
-
// row names the feature (
|
|
648
|
+
// row names the feature (inspect-boundary.mjs, composed-gate.mjs): a host without it refuses the flag.
|
|
647
649
|
if (instructions && (action !== 'inspect' || !soul || home)) bad('Composed instructions belong to a soul inspection');
|
|
648
650
|
const composed = instructions && Array.isArray(features) && features.includes('soul-composed-instructions') ? ['--instructions'] : [];
|
|
649
651
|
// --skills (feature soul-skills) adds the soul's own skills (souls[0].skills): inspect --soul only, gated the same
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/** When a soul field the host composes or reports is asked for: the composed AGENTS.md (feature
|
|
2
|
+
* soul-composed-instructions, `inspect --soul --instructions`) and the soul's own skills (feature soul-skills,
|
|
3
|
+
* `inspect --soul --skills`, `souls[0].skills`). The one gate module for both, shared by the renderer (whether the
|
|
4
|
+
* soul page asks) and the server (whether the ask reaches the CLI); DOM-free so the server can import it.
|
|
5
|
+
*
|
|
6
|
+
* A local soul: this computer's CLI advertises the feature. A routed soul (`--server`): the host answers, so this
|
|
7
|
+
* computer's CLI must also relay what each host reports about itself (feature server-probe-features: the roster
|
|
8
|
+
* group's `probe.features`, the host's own `version --json` features), and the host's list must name the feature.
|
|
9
|
+
* Only an array counts: `features: null` (an older host, or a list the kernel would not relay) and a group with no
|
|
10
|
+
* `features` key (a failed roster read) are unknown, and unknown is not supported. Never decided from a refusal
|
|
11
|
+
* (`E_REMOTE_INCOMPATIBLE`) and never by probing: the roster row is the answer. */
|
|
12
|
+
export const COMPOSED_FEATURE = 'soul-composed-instructions';
|
|
13
|
+
export const SKILLS_FEATURE = 'soul-skills';
|
|
14
|
+
export const PROBE_FEATURES_FEATURE = 'server-probe-features';
|
|
15
|
+
|
|
16
|
+
const advertises = (cli, feature) => !!cli?.ok && Array.isArray(cli.features) && cli.features.includes(feature);
|
|
17
|
+
/** A roster group's host advertises `feature`: its last roster read succeeded and its own list names it. Only the
|
|
18
|
+
* host's half: each caller pairs it with this CLI's routed gate for that feature. */
|
|
19
|
+
export function hostAdvertises(group, feature) {
|
|
20
|
+
const probe = group?.probe;
|
|
21
|
+
return probe?.ok === true && Array.isArray(probe.features) && probe.features.includes(feature);
|
|
22
|
+
}
|
|
23
|
+
/** This computer's CLI composes a soul's AGENTS.md on request. */
|
|
24
|
+
export const composedSupported = cli => advertises(cli, COMPOSED_FEATURE);
|
|
25
|
+
/** This computer's CLI can route the request and relays the hosts' own feature lists in the roster. */
|
|
26
|
+
export const routedComposedSupported = cli => composedSupported(cli) && advertises(cli, PROBE_FEATURES_FEATURE);
|
|
27
|
+
/** A roster group's host composes: its last roster read succeeded and its own list names the feature. */
|
|
28
|
+
export const hostComposes = (cli, group) => routedComposedSupported(cli) && hostAdvertises(group, COMPOSED_FEATURE);
|
|
29
|
+
/** This computer's CLI reports a soul's own skills on request. */
|
|
30
|
+
export const skillsSupported = cli => advertises(cli, SKILLS_FEATURE);
|
|
31
|
+
/** This computer's CLI can route the skills request and relays the hosts' own feature lists in the roster. */
|
|
32
|
+
export const routedSkillsSupported = cli => skillsSupported(cli) && advertises(cli, PROBE_FEATURES_FEATURE);
|
|
33
|
+
/** A roster group's host reports a soul's skills: its last roster read succeeded and its own list names the feature. */
|
|
34
|
+
export const hostReportsSkills = (cli, group) => routedSkillsSupported(cli) && hostAdvertises(group, SKILLS_FEATURE);
|