@awebai/oats 0.65.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 +8 -7
- package/docs/desktop-cli-api.md +5 -4
- package/docs/implementation.md +10 -1
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.66.0.md +183 -0
- package/docs/servers.md +2 -2
- package/docs/tui.md +137 -16
- package/docs/upgrading.md +1 -1
- package/docs/workspaces.md +9 -2
- package/lib/deployments.mjs +21 -5
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/keymap.mjs +36 -9
- package/packages/client/machine-contract.mjs +1 -5
- 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 +7 -6
- package/packages/tui/lib/actions.mjs +65 -64
- package/packages/tui/lib/client.mjs +1 -0
- package/packages/tui/lib/config.mjs +167 -26
- package/packages/tui/lib/main.mjs +53 -9
- package/packages/tui/lib/model.mjs +2 -0
- package/packages/tui/lib/store.mjs +18 -3
- 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 +128 -14
- package/packages/tui/lib/term/tty.mjs +43 -12
- package/packages/tui/lib/views/frame.mjs +1 -1
- package/packages/tui/lib/views/help.mjs +52 -13
- package/skills/oats-getting-started/SKILL.md +96 -28
package/docs/tui.md
CHANGED
|
@@ -357,7 +357,9 @@ fit; the detail shows them whole. The TUI's own words end the same way:
|
|
|
357
357
|
key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
|
|
358
358
|
among them, but for **[the leader](#the-leader)** (`Alt+O`, `Ctrl+\` on
|
|
359
359
|
macOS, unless [`tui.json`](#change-the-keys-tuijson) names another), the
|
|
360
|
-
one key the TUI takes from the agent
|
|
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
|
|
361
363
|
focus to the list; the leader twice types the leader into the agent; the
|
|
362
364
|
leader then another key does what that key does from anywhere. While the
|
|
363
365
|
terminal has the focus the cheat sheet names those three:
|
|
@@ -1060,6 +1062,7 @@ The line after leaving says so and names `oats status` to see it.
|
|
|
1060
1062
|
| `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
|
|
1061
1063
|
| `Alt+O` (`Ctrl+\` on macOS) | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
|
|
1062
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 |
|
|
1063
1066
|
| `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
|
|
1064
1067
|
| `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
|
|
1065
1068
|
| `N` | spawns another of the selected instance's soul: its preview |
|
|
@@ -1081,12 +1084,12 @@ instance can always be read, however many they are. The selection stays
|
|
|
1081
1084
|
where it is, and the list returns to it at the next key that moves it.
|
|
1082
1085
|
|
|
1083
1086
|
The help screen is generated from the table the program acts on, so it
|
|
1084
|
-
always lists the keys that work, the leader's among them, the
|
|
1085
|
-
and the spawn prompt's, with the
|
|
1086
|
-
do. Its top row has the time of the read and the count of withheld rows
|
|
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
|
|
1087
1090
|
([What it shows](#what-it-shows)). The movement keys scroll it. While
|
|
1088
1091
|
a terminal has the focus the table's keys are the agent's: the leader alone
|
|
1089
|
-
is the TUI's.
|
|
1092
|
+
is the TUI's, with the chords while your terminal sends them.
|
|
1090
1093
|
|
|
1091
1094
|
### The leader
|
|
1092
1095
|
|
|
@@ -1140,7 +1143,9 @@ to use Option as Meta.
|
|
|
1140
1143
|
two keys reaches the agent unchanged: in vim that is "leave insert mode,
|
|
1141
1144
|
open a line". Over a slow link two keys typed apart can arrive in one
|
|
1142
1145
|
read and act as the leader, and one `Alt+O` can arrive split and reach
|
|
1143
|
-
the agent as `Esc` and `o`.
|
|
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.
|
|
1144
1149
|
- **In the list no leader is needed:** the plain keys work as they always
|
|
1145
1150
|
have, and the leader works there too.
|
|
1146
1151
|
- **What was open under it is settled first,** from whatever view: a
|
|
@@ -1152,6 +1157,70 @@ to use Option as Meta.
|
|
|
1152
1157
|
- **The table is fixed** in this version: `keys` in `tui.json` rebinds the
|
|
1153
1158
|
plain keys, and `open.detachKey` the leader.
|
|
1154
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
|
+
|
|
1155
1224
|
### The palette
|
|
1156
1225
|
|
|
1157
1226
|
The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
|
|
@@ -1218,9 +1287,12 @@ and scrolling keep working.
|
|
|
1218
1287
|
|
|
1219
1288
|
## Change the keys: `tui.json`
|
|
1220
1289
|
|
|
1221
|
-
`oats tui` reads
|
|
1222
|
-
|
|
1223
|
-
|
|
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.
|
|
1224
1296
|
|
|
1225
1297
|
```json
|
|
1226
1298
|
{ "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
|
|
@@ -1293,6 +1365,47 @@ A name from the file is repeated in a line only when it is plain printable
|
|
|
1293
1365
|
ASCII of at most 40 characters. More than twenty problems are counted, not
|
|
1294
1366
|
listed.
|
|
1295
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
|
+
|
|
1296
1409
|
## What it reads, and what it runs
|
|
1297
1410
|
|
|
1298
1411
|
`oats tui` decodes no kernel answer itself: it runs the readers it shares
|
|
@@ -1508,7 +1621,7 @@ with the Desktop (`packages/client/`).
|
|
|
1508
1621
|
| spawn an agent on another machine | `oats spawn <soul> --server <id>` |
|
|
1509
1622
|
| spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
|
|
1510
1623
|
| see a capability's skills and files | `oats capabilities show <name>` |
|
|
1511
|
-
| 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>` |
|
|
1512
1625
|
| check a machine | `oats server check <id>` |
|
|
1513
1626
|
| remove a machine | `oats server remove <id>` |
|
|
1514
1627
|
| open a deployment that is not listed | `oats tui --dir <path>` |
|
|
@@ -1550,10 +1663,15 @@ This is the complete list. On start, in this order:
|
|
|
1550
1663
|
2. the alternate screen (`CSI ?1049h`), so your scrollback is untouched;
|
|
1551
1664
|
3. the cursor hidden (`CSI ?25l`);
|
|
1552
1665
|
4. autowrap off (`CSI ?7l`);
|
|
1553
|
-
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)).
|
|
1554
1671
|
|
|
1555
|
-
On the way out, the reverse:
|
|
1556
|
-
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.
|
|
1557
1675
|
|
|
1558
1676
|
While it draws:
|
|
1559
1677
|
|
|
@@ -1620,10 +1738,11 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
1620
1738
|
## What it never does
|
|
1621
1739
|
|
|
1622
1740
|
- It switches on **no mouse reporting, no focus reporting, no keyboard
|
|
1623
|
-
protocol
|
|
1624
|
-
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.
|
|
1625
1744
|
- It writes **no window title, no clipboard sequence, no bell**, and no query
|
|
1626
|
-
that expects the terminal to reply.
|
|
1745
|
+
that expects the terminal to reply but the kitty keyboard protocol's.
|
|
1627
1746
|
- **Its own words and marks use only your terminal's own sixteen colours**
|
|
1628
1747
|
and bold, dim, underline and reverse: no 256-colour or RGB value and no
|
|
1629
1748
|
background fill, so your theme stays the theme. An open terminal shows
|
|
@@ -1682,6 +1801,8 @@ alone. The next run removes the directory that is left, with its `tmux`,
|
|
|
1682
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 |
|
|
1683
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` |
|
|
1684
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 |
|
|
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 |
|
|
1685
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 |
|
|
1686
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 |
|
|
1687
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 |
|
package/docs/upgrading.md
CHANGED
|
@@ -93,7 +93,7 @@ Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
|
|
|
93
93
|
release. Read 0.62.0's Upgrade section and keep this order: install the
|
|
94
94
|
Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
|
|
95
95
|
`>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`, the 0.64.0
|
|
96
|
-
Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`), then that
|
|
96
|
+
Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`, the 0.66.0 Desktop `>=0.26.0 <0.67.0`), then that
|
|
97
97
|
release's CLI and matching pi bridge. Only **after
|
|
98
98
|
installing that CLI**, run its setup conversion once per user on each host,
|
|
99
99
|
from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
|
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.13.
|
|
57
|
+
oats.framework: v1.13.4 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.2.1
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -697,7 +697,9 @@ only. Which deployments a client has open stays with that client.
|
|
|
697
697
|
nothing.
|
|
698
698
|
- `oats deployments add [<dir>]`, which the clients run when they open a
|
|
699
699
|
deployment, and people by hand. It lists the deployment at or above `<dir>`
|
|
700
|
-
(default: the current directory)
|
|
700
|
+
(default: the current directory): the nearest directory whose
|
|
701
|
+
`oats-local.yaml` is a regular file, not a link. A directory or a link of
|
|
702
|
+
that name is not a deployment's file and is passed over.
|
|
701
703
|
- **Every kernel command that resolves a deployment that is not listed yet**
|
|
702
704
|
lists it (`via: cli`): `status`, `spawn`, `sync`, `session`, `doctor`,
|
|
703
705
|
`retire` and the others that read a local deployment, from inside an
|
|
@@ -717,6 +719,11 @@ only. Which deployments a client has open stays with that client.
|
|
|
717
719
|
answer and exit status are the same whether or not it listed anything.
|
|
718
720
|
- A command routed with `--server` never lists anything: the host's path is
|
|
719
721
|
not this computer's.
|
|
722
|
+
- A deployment under a temporary directory (`os.tmpdir()`, `/tmp`,
|
|
723
|
+
`/private/tmp` or `/var/folders`, each compared after realpath) is never
|
|
724
|
+
listed this way, since test fixtures live there and would stay in the list
|
|
725
|
+
as `missing`; `oats deployments add`, `oats onboard` and a client opening it
|
|
726
|
+
still list one.
|
|
720
727
|
- A deployment inside a linked Git worktree or submodule is listed by the
|
|
721
728
|
first command that resolves its instance root (`status`, `spawn`,
|
|
722
729
|
`session` and the like), not by `sync`, `doctor` and the other
|
package/lib/deployments.mjs
CHANGED
|
@@ -23,8 +23,8 @@
|
|
|
23
23
|
*/
|
|
24
24
|
|
|
25
25
|
import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, statSync } from "node:fs";
|
|
26
|
-
import { homedir } from "node:os";
|
|
27
|
-
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
26
|
+
import { homedir, tmpdir } from "node:os";
|
|
27
|
+
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
28
28
|
import { canonicalDeploymentPath } from "./core.mjs";
|
|
29
29
|
import { withDirLock } from "./dir-lock.mjs";
|
|
30
30
|
import { writeFileAtomic } from "./packages.mjs";
|
|
@@ -242,11 +242,12 @@ export function listDeployments() {
|
|
|
242
242
|
return { deploymentsApi: DEPLOYMENTS_API, file: deploymentsFile(), deployments, imports: doc.imports };
|
|
243
243
|
}
|
|
244
244
|
|
|
245
|
-
/** The deployment at or above `dir`: the first directory walking up
|
|
246
|
-
* (
|
|
245
|
+
/** The deployment at or above `dir`: the first directory walking up whose oats-local.yaml is a
|
|
246
|
+
* regular file, not a link (the rule a client admits a deployment by, and the list's `ok`), or
|
|
247
|
+
* null. Anything else of that name (a directory, a link) is passed over (awebai/oats#1397). */
|
|
247
248
|
export function deploymentAtOrAbove(dir) {
|
|
248
249
|
for (let d = resolve(dir); ; d = dirname(d)) {
|
|
249
|
-
try { lstatSync(join(d, "oats-local.yaml"))
|
|
250
|
+
try { if (lstatSync(join(d, "oats-local.yaml")).isFile()) return d; } catch { /* not here */ }
|
|
250
251
|
if (dirname(d) === d) return null;
|
|
251
252
|
}
|
|
252
253
|
}
|
|
@@ -297,6 +298,17 @@ function inGitFileWorkTree(dir) {
|
|
|
297
298
|
}
|
|
298
299
|
}
|
|
299
300
|
|
|
301
|
+
/** The temporary directories, as the auto-add knows them (awebai/oats#1397): os.tmpdir(), /tmp,
|
|
302
|
+
* /private/tmp and /var/folders (macOS's per-user ones), each by its realpath. */
|
|
303
|
+
export const TEMPORARY_DIRECTORIES = Object.freeze(["/tmp", "/private/tmp", "/var/folders"]);
|
|
304
|
+
/** Whether the real path `real` is one of the temporary directories or under one. */
|
|
305
|
+
export function underTemporaryDirectory(real) {
|
|
306
|
+
return [tmpdir(), ...TEMPORARY_DIRECTORIES].some((dir) => {
|
|
307
|
+
const top = canonicalHomePath(dir);
|
|
308
|
+
return dirname(top) !== top && (real === top || real.startsWith(top + sep)); // a TMPDIR of / is not taken
|
|
309
|
+
});
|
|
310
|
+
}
|
|
311
|
+
|
|
300
312
|
/** The auto-add of awebai/oats#1390 (amendment and its performance budget): `root`, the deployment
|
|
301
313
|
* directory the command itself resolved (`canonical`: the root ensureRoot canonicalized), is
|
|
302
314
|
* listed when it is not. A listed deployment (live or tombstoned) costs one lock-free bounded read
|
|
@@ -305,6 +317,9 @@ function inGitFileWorkTree(dir) {
|
|
|
305
317
|
* to the commands that resolve its canonical root, from lstat alone: its stored path is the
|
|
306
318
|
* primary checkout's, which only Git can tell;
|
|
307
319
|
* - another spelling of a listed deployment (a link, /var for /private/var) costs a realpath;
|
|
320
|
+
* - an unlisted root whose realpath is under a temporary directory is never listed by it
|
|
321
|
+
* (awebai/oats#1397): test fixtures live there, and would stay in the list as `missing`. An
|
|
322
|
+
* explicit add, onboard and the imports still list such a root;
|
|
308
323
|
* - only an unlisted deployment is canonicalized (a Git probe) and tries the lock once (no wait:
|
|
309
324
|
* busy skips, the next command tries again) to add it `via: cli`.
|
|
310
325
|
* Best effort and silent: it never throws or prints. → `"listed" | "added" | "skipped"`. */
|
|
@@ -318,6 +333,7 @@ export function listResolved(root, { canonical = false } = {}) {
|
|
|
318
333
|
const real = canonicalHomePath(root);
|
|
319
334
|
if (known(real)) return "listed";
|
|
320
335
|
if (!canonical && real !== root && inGitFileWorkTree(real)) return "skipped";
|
|
336
|
+
if (underTemporaryDirectory(real)) return "skipped";
|
|
321
337
|
const path = canonicalListPath(root);
|
|
322
338
|
if (known(path)) return "listed";
|
|
323
339
|
return updateDeployments((d, now) => (addRow(d, path, "cli", now, { revive: false }) ? "added" : "listed"), { wait: 0 });
|
package/package-catalog.json
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.30.0",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
"oats.framework": {
|
|
45
45
|
"url": "https://github.com/awebai/oats.git",
|
|
46
|
-
"ref": "oats-framework/v1.13.
|
|
46
|
+
"ref": "oats-framework/v1.13.4",
|
|
47
47
|
"path": "oats-package"
|
|
48
48
|
}
|
|
49
49
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.66.0",
|
|
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",
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.67.0 (the band is
|
|
17
17
|
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
18
|
// API version — not source adjacency — is authoritative.
|
|
19
19
|
//
|
|
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
|
|
|
52
52
|
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
53
53
|
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
54
54
|
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
55
|
-
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0,
|
|
55
|
+
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 67, 0] };
|
|
56
56
|
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
57
57
|
* rejection reason, the backend's /api status and the degradation card can
|
|
58
58
|
* never disagree with the numbers actually enforced above. */
|
|
@@ -1,18 +1,22 @@
|
|
|
1
|
-
/** The keys both clients share: the leader, the table read after it,
|
|
2
|
-
* of instances. Written down once, here; the Desktop
|
|
3
|
-
*
|
|
4
|
-
* test/keymap
|
|
1
|
+
/** The keys both clients share: the leader, the table read after it, the plain keys of the list
|
|
2
|
+
* of instances, and the chords. Written down once, here; the Desktop and the TUI read their defaults
|
|
3
|
+
* from it (packages/tui/lib/actions.mjs LEADER is LEADER_TABLE, and the TUI's test
|
|
4
|
+
* packages/tui/test/keymap.test.mjs fails on a `does` the TUI does not handle).
|
|
5
5
|
*
|
|
6
6
|
* Pure data and readers: no state, no DOM, no imports. Every value is frozen.
|
|
7
7
|
*
|
|
8
8
|
* Key ids are the TUI's spelling (packages/tui/lib/term/keys.mjs keyId): one character as itself,
|
|
9
9
|
* case kept (`n`, `N`, `|`, `?`, `/`, `-`); named keys `up` `down` `left` `right` `tab` `escape`
|
|
10
|
-
* `space` `enter` `home` `end` `pageup` `pagedown`; modifiers as `ctrl+` / `alt+`
|
|
10
|
+
* `space` `enter` `home` `end` `pageup` `pagedown`; modifiers as `ctrl+` / `alt+` / `shift+`
|
|
11
|
+
* prefixes, in that order. A chord adds two: `shift+` with Ctrl and a letter (`ctrl+shift+k`, which
|
|
12
|
+
* the TUI reads only under the kitty keyboard protocol), and `cmd+`, first, for macOS's Command
|
|
13
|
+
* (`cmd+k`, the Desktop's ⌘K), which a terminal never passes to a program.
|
|
11
14
|
*
|
|
12
|
-
* leaderKey(isMac)
|
|
13
|
-
* leaderDoes(key)
|
|
14
|
-
* plainKeys(does)
|
|
15
|
-
* leaderRows()
|
|
15
|
+
* leaderKey(isMac) -> the leader's key id on that platform "ctrl+\\" / "alt+o"
|
|
16
|
+
* leaderDoes(key) -> what the leader then does for a key id, or null
|
|
17
|
+
* plainKeys(does) -> the plain key ids of an action (empty when it has none)
|
|
18
|
+
* leaderRows() -> LEADER_TABLE
|
|
19
|
+
* chordKey(does, isMac) -> the chord's key id on that platform, or null
|
|
16
20
|
*
|
|
17
21
|
* `does` names an action, not a client's code: each client maps it to its own. */
|
|
18
22
|
|
|
@@ -82,6 +86,23 @@ export const PLAIN_KEYS = Object.freeze([
|
|
|
82
86
|
{ does: "help", keys: ["?"] },
|
|
83
87
|
].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
|
|
84
88
|
|
|
89
|
+
/** The chords: one key that does what the leader then a key does, the Desktop's direct chords whose
|
|
90
|
+
* action the TUI has too, per platform (`mac`, `other`). The Desktop's DEFAULT_KEYMAP reads these
|
|
91
|
+
* entries from here (docs/desktop-keyboard.md). The TUI takes the `other` ones, and the `mac` ones
|
|
92
|
+
* without `cmd+`, while the terminal confirms the kitty keyboard protocol (docs/tui.md, "Chords"),
|
|
93
|
+
* as extras: the leader stays the key that always works. The Desktop's Ctrl+1/2/3 (the stages) are
|
|
94
|
+
* the Desktop's own and are not here. */
|
|
95
|
+
export const CHORDS = Object.freeze([
|
|
96
|
+
{ does: "palette", mac: "cmd+k", other: "ctrl+shift+k" },
|
|
97
|
+
{ does: "spawn", mac: "cmd+p", other: "ctrl+shift+p" },
|
|
98
|
+
{ does: "tab-next", mac: "ctrl+tab", other: "ctrl+tab" },
|
|
99
|
+
{ does: "tab-previous", mac: "ctrl+shift+tab", other: "ctrl+shift+tab" },
|
|
100
|
+
{ does: "close-terminal", mac: "cmd+w", other: "ctrl+shift+w" },
|
|
101
|
+
{ does: "filter", mac: "cmd+f", other: "ctrl+shift+f" },
|
|
102
|
+
{ does: "split-right", mac: "cmd+\\", other: "ctrl+shift+e" },
|
|
103
|
+
{ does: "split-down", mac: "cmd+shift+\\", other: "ctrl+shift+o" },
|
|
104
|
+
].map((entry) => Object.freeze({ ...entry })));
|
|
105
|
+
|
|
85
106
|
const NONE = Object.freeze([]);
|
|
86
107
|
|
|
87
108
|
/** The leader's key id on macOS (`true`) or elsewhere. */
|
|
@@ -104,3 +125,9 @@ export function plainKeys(does) {
|
|
|
104
125
|
export function leaderRows() {
|
|
105
126
|
return LEADER_TABLE;
|
|
106
127
|
}
|
|
128
|
+
|
|
129
|
+
/** The key id of the chord that does `does` on macOS (`true`) or elsewhere, or null when none does. */
|
|
130
|
+
export function chordKey(does, isMac) {
|
|
131
|
+
const entry = CHORDS.find((each) => each.does === does);
|
|
132
|
+
return entry === undefined ? null : isMac ? entry.mac : entry.other;
|
|
133
|
+
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/* oats desktop — a workspace's own machines (#517): the gates, the Add a machine
|
|
1
|
+
/* oats desktop — a workspace's own machines (#517): the gates, the Add a machine Name default and field
|
|
2
2
|
rules, and the step rows of `oats server connect --json` and `oats aweb connect --json` as the CLI
|
|
3
3
|
sends them (docs/desktop-cli-api.md; interface §2 and §4).
|
|
4
4
|
|
|
@@ -37,10 +37,6 @@ export function machineName(host, deploymentDir) {
|
|
|
37
37
|
return `${host}-${basename(deploymentDir)}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-{2,}/g, '-')
|
|
38
38
|
.replace(/^-+/, '').slice(0, 64).replace(/-+$/, '');
|
|
39
39
|
}
|
|
40
|
-
/** The default Folder on that machine: `~/Agents/<this deployment dir basename>`. */
|
|
41
|
-
export function machineFolder(deploymentDir) {
|
|
42
|
-
return `~/Agents/${basename(deploymentDir)}`;
|
|
43
|
-
}
|
|
44
40
|
|
|
45
41
|
/** The first field that the kernel would refuse, as `{ field, text }`, or null. */
|
|
46
42
|
export function machineFieldProblem({ id, host, folder }) {
|
|
@@ -31,7 +31,8 @@ import { captureDefaultRootPlan } from "../lib/capture-default-roots.mjs";
|
|
|
31
31
|
import { captureCommandPass } from "../lib/capture-command-output.mjs";
|
|
32
32
|
import { captureCommandEntry } from "../lib/capture-command.mjs";
|
|
33
33
|
import { IgnoreError, loadIgnore } from "../lib/ignore.mjs";
|
|
34
|
-
import { preflightCaptureService, applyCaptureService
|
|
34
|
+
import { preflightCaptureService, applyCaptureService } from "../lib/capture-service-install.mjs";
|
|
35
|
+
import { captureSetupSnapshot, recheckCaptureSetup, writeCaptureSetup } from "../lib/capture-setup-write.mjs";
|
|
35
36
|
import { captureRemedyCommand } from "../lib/capture-health.mjs";
|
|
36
37
|
|
|
37
38
|
// The node written into what outlives this process: the hooks and the
|
|
@@ -243,7 +244,14 @@ try {
|
|
|
243
244
|
for (const { snapshot, contents } of hooks) {
|
|
244
245
|
if (!contents) console.log(`hooks: ${snapshot.path} already installed`);
|
|
245
246
|
else if (dry) console.log(`hooks: would install Stop+SessionEnd capture in ${snapshot.path}`);
|
|
246
|
-
else {
|
|
247
|
+
else {
|
|
248
|
+
try { writeCaptureSetup(snapshot, contents, createdParents); }
|
|
249
|
+
catch (error) {
|
|
250
|
+
if (error.published) summary.hooks.push(`${snapshot.path} (publication may have occurred at ${oneLine(error.stage)}; durability was not established)`);
|
|
251
|
+
throw error;
|
|
252
|
+
}
|
|
253
|
+
summary.hooks.push(snapshot.path); console.log(`hooks: installed Stop+SessionEnd capture in ${snapshot.path}`);
|
|
254
|
+
}
|
|
247
255
|
}
|
|
248
256
|
if (dry) console.log("dry run: no first capture pass");
|
|
249
257
|
else {
|
|
@@ -1533,8 +1533,11 @@ the first pass still uses the running Node. These are user-manager definitions,
|
|
|
1533
1533
|
not deployment automation timers. No external wrapper is removed.
|
|
1534
1534
|
|
|
1535
1535
|
The setup coordinator prepares hook edits in memory, then
|
|
1536
|
-
`capture-service-install.mjs`
|
|
1537
|
-
applicable manager state before any
|
|
1536
|
+
`capture-service-install.mjs` uses `capture-setup-write.mjs` to snapshot every
|
|
1537
|
+
named service target and inspects applicable manager state before any
|
|
1538
|
+
service/file/hook/capture mutation. The shared module owns checked setup
|
|
1539
|
+
publication independently of manager policy; the service module retains its
|
|
1540
|
+
snapshot/recheck/write exports for existing callers.
|
|
1538
1541
|
Snapshots retain regular-file bytes and identity or the symlink's own identity
|
|
1539
1542
|
and target, plus ancestor identities and explicit missing-ancestor records. Reads are limited to 1 MiB per target;
|
|
1540
1543
|
unknown reads, nonregular targets and unsupported manager output refuse.
|
|
@@ -1574,6 +1577,11 @@ Apply rechecks file/ancestor identities and manager ownership/enablement.
|
|
|
1574
1577
|
Replaced bytes or symlinks are saved nonoverwriting in a reported datable
|
|
1575
1578
|
`<root>/service-backups/<date>-<unique-id>/` directory. Symlink backups
|
|
1576
1579
|
preserve the link instead of reading or removing an external wrapper target.
|
|
1580
|
+
Backup bytes and directory/symlink entries are not fsynced and cannot be relied
|
|
1581
|
+
on as power-loss-safe recovery. Durability of a replacement does not establish
|
|
1582
|
+
backup durability; this is tracked separately in
|
|
1583
|
+
[backup durability follow-up #1410](https://github.com/awebai/oats/issues/1410).
|
|
1584
|
+
|
|
1577
1585
|
An ancestor absent at preflight must remain absent until this apply creates it.
|
|
1578
1586
|
Creation proceeds one directory at a time without recursive adoption of an
|
|
1579
1587
|
existing path; each created non-link directory's identity is retained in a
|
|
@@ -1581,9 +1589,35 @@ per-apply map shared by subsequent service and hook writes. Newly introduced
|
|
|
1581
1589
|
directories or links are not accepted as extra ancestry. Existing ancestor
|
|
1582
1590
|
identities and observed symlink targets remain binding. The extra metadata
|
|
1583
1591
|
checks and directory creation do not establish an atomic filesystem operation.
|
|
1584
|
-
Each
|
|
1585
|
-
|
|
1586
|
-
|
|
1592
|
+
Each setup hook, service definition and pending-marker write uses the same
|
|
1593
|
+
checked publisher. It creates an exclusive 0600 temporary file, checks its
|
|
1594
|
+
open descriptor against the pathname, writes the complete contents and fsyncs
|
|
1595
|
+
the file before rename. After rechecking the saved target, temporary file and
|
|
1596
|
+
ancestors, it renames and fsyncs the containing directory through a checked
|
|
1597
|
+
directory descriptor. Newly created ancestor entries are synced in their
|
|
1598
|
+
containing directories, from the first missing parent toward the target,
|
|
1599
|
+
before creating the next child. A directory whose entry sync/open/close failed
|
|
1600
|
+
is not authorized for reuse by a subsequent write through the per-apply map.
|
|
1601
|
+
Required directory fsync failures, including an unsupported operation, refuse;
|
|
1602
|
+
there is no fallback that reports durability without the required sync.
|
|
1603
|
+
|
|
1604
|
+
A failure reports the target and stage, retains the primary cause and any
|
|
1605
|
+
scratch/descriptor cleanup failure, and exits nonzero. Before publication,
|
|
1606
|
+
the writer preserves the old target and removes only scratch whose saved
|
|
1607
|
+
identity and unchanged ancestry still prove ownership. Changed ancestry or a
|
|
1608
|
+
substituted temporary file revokes pathname cleanup; an interrupted/refused
|
|
1609
|
+
write can leave its original temporary file. After rename, a failed sync,
|
|
1610
|
+
close or identity recheck reports that publication may have occurred and
|
|
1611
|
+
durability was not established. It neither unlinks the new target nor claims
|
|
1612
|
+
rollback. A refused rename whose original target cannot be re-established is
|
|
1613
|
+
reported with the same uncertainty.
|
|
1614
|
+
|
|
1615
|
+
These are ordered filesystem durability operations, subject to the filesystem
|
|
1616
|
+
and storage device honoring fsync. Recording and injected I/O-fault fixtures
|
|
1617
|
+
check process-visible bytes, identities, permissions, failures and ordering;
|
|
1618
|
+
they do not reproduce or prove survival of a physical power loss. This setup
|
|
1619
|
+
publisher does not change ordinary capture transaction sync policy or the
|
|
1620
|
+
pending marker's activation/removal lifecycle.
|
|
1587
1621
|
An expected manager unmask can remove only the saved named `/dev/null` link;
|
|
1588
1622
|
other observed replacements refuse. These checks detect observed races, not
|
|
1589
1623
|
an OS-wide atomic transaction over files and managers.
|
|
@@ -1654,7 +1688,12 @@ never as "nothing happened". After a service failure, `service changed` lines
|
|
|
1654
1688
|
name, in order, what the failed apply had already changed: the replacement
|
|
1655
1689
|
backup directory, each manager action completed (units stopped, disabled or
|
|
1656
1690
|
unmasked, a job booted out), each definition written, and the pending-activation
|
|
1657
|
-
marker written or a stale one removed.
|
|
1691
|
+
marker written or a stale one removed. A failed publication also retains any
|
|
1692
|
+
created-parent evidence and names a possibly published target and its failed
|
|
1693
|
+
stage in these lines. A hook published before a later durability failure is
|
|
1694
|
+
listed under `hooks written` with the same uncertainty and stage, rather than
|
|
1695
|
+
reported as `none`. These annotations describe possible changes, not successful
|
|
1696
|
+
durability or rollback. Setup has no `--json` mode.
|
|
1658
1697
|
|
|
1659
1698
|
Fake-manager and isolated CLI fixtures exercise this ordering and refusal
|
|
1660
1699
|
contract. Real-manager cases live in `test/capture-service-real-darwin.test.mjs`
|