@awebai/oats 0.64.0 → 0.66.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +109 -11
  3. package/docs/desktop-cli-api.md +88 -5
  4. package/docs/desktop.md +14 -5
  5. package/docs/implementation.md +26 -3
  6. package/docs/integrations.md +1 -1
  7. package/docs/official-catalog.md +2 -2
  8. package/docs/packages.md +7 -7
  9. package/docs/release-notes/v0.65.0.md +187 -0
  10. package/docs/release-notes/v0.66.0.md +183 -0
  11. package/docs/servers.md +2 -2
  12. package/docs/tui.md +548 -249
  13. package/docs/upgrading.md +1 -1
  14. package/docs/workspaces.md +132 -1
  15. package/lib/core.mjs +14 -4
  16. package/lib/deployments.mjs +341 -0
  17. package/lib/resolved-deployment.mjs +37 -0
  18. package/lib/workspace.mjs +2 -0
  19. package/package-catalog.json +2 -2
  20. package/package.json +1 -1
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/deployment-label.mjs +2 -2
  23. package/packages/client/deployment-list-cli.mjs +98 -0
  24. package/packages/client/deployment-list.mjs +91 -0
  25. package/packages/client/keymap.mjs +133 -0
  26. package/packages/client/machine-contract.mjs +1 -5
  27. package/packages/client/own-codes.mjs +2 -0
  28. package/packages/client/panel-views.mjs +1 -1
  29. package/packages/client/workspace-admission.mjs +2 -1
  30. package/packages/record/bin/setup.mjs +10 -2
  31. package/packages/record/docs/capture-service.md +45 -6
  32. package/packages/record/lib/capture-service-install.mjs +6 -95
  33. package/packages/record/lib/capture-setup-write.mjs +233 -0
  34. package/packages/tui/README.md +10 -9
  35. package/packages/tui/lib/actions.mjs +89 -64
  36. package/packages/tui/lib/client.mjs +4 -1
  37. package/packages/tui/lib/config.mjs +184 -36
  38. package/packages/tui/lib/main.mjs +161 -40
  39. package/packages/tui/lib/model.mjs +73 -41
  40. package/packages/tui/lib/read.mjs +15 -45
  41. package/packages/tui/lib/store.mjs +174 -40
  42. package/packages/tui/lib/term/keys.mjs +135 -33
  43. package/packages/tui/lib/term/kitty.mjs +198 -0
  44. package/packages/tui/lib/term/through.mjs +160 -24
  45. package/packages/tui/lib/term/tty.mjs +43 -12
  46. package/packages/tui/lib/views/act.mjs +17 -13
  47. package/packages/tui/lib/views/frame.mjs +418 -421
  48. package/packages/tui/lib/views/help.mjs +90 -29
  49. package/packages/tui/lib/views/instances.mjs +38 -9
  50. package/packages/tui/lib/views/switcher.mjs +65 -21
  51. package/skills/oats-getting-started/SKILL.md +102 -32
@@ -0,0 +1,233 @@
1
+ // Checked publication for setup-owned files. Kept separate from service policy
2
+ // so other setup callers can share preflight, ancestry and durability guards.
3
+ import fs from "node:fs";
4
+ import { randomUUID } from "node:crypto";
5
+ import { dirname } from "node:path";
6
+
7
+ const identity = stat => [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
8
+ function parents(path) {
9
+ const records = [];
10
+ for (let directory = dirname(path); ; directory = dirname(directory)) {
11
+ let stat;
12
+ try { stat = fs.lstatSync(directory); }
13
+ catch (error) { if (error.code !== "ENOENT") throw error; }
14
+ if (stat) {
15
+ let target = null;
16
+ if (stat.isSymbolicLink()) {
17
+ try { target = fs.statSync(directory); }
18
+ catch (error) { if (error.code !== "ENOENT") throw error; }
19
+ }
20
+ // Even a dangling ancestor link has an identity to retain. Its missing
21
+ // target must not turn a later retargeting into ordinary directory creation.
22
+ records.push([directory, `${stat.dev}:${stat.ino}:${stat.mode}`, stat.isSymbolicLink() ? fs.readlinkSync(directory) : null,
23
+ target ? `${target.dev}:${target.ino}:${target.mode}` : null]);
24
+ } else records.push([directory, null, null, null]);
25
+ if (dirname(directory) === directory) return records;
26
+ }
27
+ }
28
+
29
+ export function captureSetupSnapshot(path) {
30
+ const ancestry = parents(path);
31
+ let stat;
32
+ try { stat = fs.lstatSync(path); }
33
+ catch (error) { if (error.code === "ENOENT") return { path, kind: "absent", parents: ancestry }; throw error; }
34
+ const before = identity(stat);
35
+ let bytes, link;
36
+ if (stat.isSymbolicLink()) link = fs.readlinkSync(path);
37
+ else {
38
+ if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error(`refusing nonregular or oversized setup target ${path}`);
39
+ const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
40
+ let failure;
41
+ try {
42
+ if (identity(fs.fstatSync(fd)) !== before) throw new Error(`setup target changed while opening ${path}`);
43
+ bytes = fs.readFileSync(fd);
44
+ if (identity(fs.fstatSync(fd)) !== before) throw new Error(`setup target changed while reading ${path}`);
45
+ } catch (error) { failure = error; }
46
+ try { fs.closeSync(fd); }
47
+ catch (error) {
48
+ if (failure) throw new AggregateError([failure, error], `${failure.message}; setup target close failed: ${error.message}`, { cause: failure });
49
+ throw error;
50
+ }
51
+ if (failure) throw failure;
52
+ }
53
+ if (identity(fs.lstatSync(path)) !== before) throw new Error(`setup target changed while reading ${path}`);
54
+ return { path, kind: link === undefined ? "file" : "link", identity: before, bytes, link, parents: ancestry };
55
+ }
56
+
57
+ function recheckParents(snapshot, current, createdParents = new Map()) {
58
+ if (snapshot.parents.some(record => {
59
+ const expected = record[1] === null ? createdParents.get(record[0]) ?? record : record;
60
+ return !current.parents.some(now => JSON.stringify(now) === JSON.stringify(expected));
61
+ }))
62
+ throw new Error(`setup target parent changed since preflight: ${snapshot.path}; re-run setup`);
63
+ }
64
+ export function recheckCaptureSetup(snapshot, createdParents = new Map()) {
65
+ recheckParents(snapshot, { parents: parents(snapshot.path) }, createdParents);
66
+ const current = captureSetupSnapshot(snapshot.path);
67
+ recheckParents(snapshot, current, createdParents);
68
+ if (current.kind !== snapshot.kind || current.identity !== snapshot.identity || current.link !== snapshot.link ||
69
+ (snapshot.bytes && !snapshot.bytes.equals(current.bytes))) throw new Error(`setup target changed since preflight: ${snapshot.path}; re-run setup`);
70
+ }
71
+
72
+ // Service apply also checks ancestry after its own expected target changes.
73
+ export function recheckCaptureSetupParents(snapshot, createdParents = new Map(), current = { parents: parents(snapshot.path) }) {
74
+ recheckParents(snapshot, current, createdParents);
75
+ }
76
+
77
+ const directoryIdentity = stat => `${stat.dev}:${stat.ino}:${stat.mode}`;
78
+ // Rename may change ctime. The final path must still name the written inode,
79
+ // mode, size and mtime; pre-rename checks retain the complete identity.
80
+ const publishedIdentity = stat => [directoryIdentity(stat), stat.size, stat.mtimeMs].join(":");
81
+
82
+ // The fourth argument is private fs-operation fault injection. Production has
83
+ // no switch for it. Snapshots and createdParents retain their caller semantics.
84
+ export function writeCaptureSetup(snapshot, contents, createdParents = new Map(), operations = fs) {
85
+ let stage = "preflight recheck", published = false, cause;
86
+ let temporary, temporaryIdentity, temporaryPublishedIdentity, temporaryNode, fileFd = null, directoryFd = null, writing = false;
87
+ const cleanupErrors = [], madeParents = [];
88
+ const recheck = () => recheckCaptureSetup(snapshot, createdParents);
89
+ const recheckAncestry = () => recheckCaptureSetupParents(snapshot, createdParents);
90
+ const changed = path => new Error(`setup publication identity changed: ${path}; re-run setup`);
91
+ // Detach before close: a close error does not authorize retrying a descriptor
92
+ // whose state may be unknown (and whose number might since have been reused).
93
+ const closeFile = () => { const fd = fileFd; fileFd = null; operations.closeSync(fd); };
94
+ const closeDirectory = () => { const fd = directoryFd; directoryFd = null; operations.closeSync(fd); };
95
+ const checkDirectory = path => {
96
+ recheckAncestry();
97
+ const descriptor = operations.fstatSync(directoryFd), current = operations.statSync(path);
98
+ if (!descriptor.isDirectory() || directoryIdentity(descriptor) !== directoryIdentity(current)) throw changed(path);
99
+ recheckAncestry();
100
+ };
101
+ const openDirectory = path => {
102
+ recheckAncestry();
103
+ // Existing approved ancestor links remain allowed: both their link and
104
+ // resolved identities are retained by the ancestry recheck.
105
+ directoryFd = operations.openSync(path, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY);
106
+ checkDirectory(path);
107
+ };
108
+ const checkTemporary = () => {
109
+ recheckAncestry();
110
+ const descriptor = operations.fstatSync(fileFd);
111
+ let current;
112
+ try { current = operations.lstatSync(temporary); }
113
+ catch (error) { if (error.code === "ENOENT") throw changed(temporary); throw error; }
114
+ if (!descriptor.isFile() || (descriptor.mode & 0o777) !== 0o600 ||
115
+ directoryIdentity(descriptor) !== temporaryNode || identity(descriptor) !== identity(current)) throw changed(temporary);
116
+ temporaryIdentity = identity(descriptor);
117
+ temporaryPublishedIdentity = publishedIdentity(descriptor);
118
+ recheckAncestry();
119
+ };
120
+ try {
121
+ recheck();
122
+ // Missing ancestors are evidence, not permission to adopt an intervening
123
+ // mkdir/link. Publish each new directory entry durably before its child.
124
+ for (const record of [...snapshot.parents].reverse()) {
125
+ if (record[1] !== null || createdParents.has(record[0])) continue;
126
+ stage = `create parent ${record[0]}`;
127
+ recheck();
128
+ operations.mkdirSync(record[0]);
129
+ madeParents.push(record[0]);
130
+ const stat = operations.lstatSync(record[0]);
131
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw changed(record[0]);
132
+ createdParents.set(record[0], [record[0], directoryIdentity(stat), null, null]);
133
+ try {
134
+ const parent = dirname(record[0]);
135
+ stage = `created-parent directory open ${parent}`;
136
+ openDirectory(parent);
137
+ stage = `created-parent directory fsync ${parent}`;
138
+ operations.fsyncSync(directoryFd);
139
+ checkDirectory(parent);
140
+ stage = `created-parent directory close ${parent}`;
141
+ closeDirectory();
142
+ } catch (error) {
143
+ // A failed durability step must not silently authorize another caller
144
+ // to reuse this directory through the shared per-apply map.
145
+ createdParents.delete(record[0]);
146
+ throw error;
147
+ }
148
+ }
149
+ stage = "temporary recheck";
150
+ recheck();
151
+ temporary = `${snapshot.path}.tmp-${randomUUID()}`;
152
+ stage = "temporary open";
153
+ fileFd = operations.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
154
+ const opened = operations.fstatSync(fileFd);
155
+ temporaryNode = directoryIdentity(opened);
156
+ temporaryIdentity = identity(opened);
157
+ checkTemporary();
158
+ recheck();
159
+ stage = "temporary write";
160
+ writing = true;
161
+ operations.writeFileSync(fileFd, contents);
162
+ checkTemporary();
163
+ writing = false;
164
+ stage = "file fsync";
165
+ operations.fsyncSync(fileFd);
166
+ checkTemporary();
167
+ recheck();
168
+ stage = "file close";
169
+ closeFile();
170
+ stage = "publication directory open";
171
+ openDirectory(dirname(snapshot.path));
172
+ stage = "rename recheck";
173
+ recheck();
174
+ if (identity(operations.lstatSync(temporary)) !== temporaryIdentity) throw changed(temporary);
175
+ checkDirectory(dirname(snapshot.path));
176
+ stage = "rename";
177
+ operations.renameSync(temporary, snapshot.path);
178
+ published = true;
179
+ stage = "directory fsync";
180
+ checkDirectory(dirname(snapshot.path));
181
+ if (publishedIdentity(operations.lstatSync(snapshot.path)) !== temporaryPublishedIdentity) throw changed(snapshot.path);
182
+ operations.fsyncSync(directoryFd);
183
+ checkDirectory(dirname(snapshot.path));
184
+ if (publishedIdentity(operations.lstatSync(snapshot.path)) !== temporaryPublishedIdentity) throw changed(snapshot.path);
185
+ stage = "directory close";
186
+ closeDirectory();
187
+ } catch (error) {
188
+ cause = error;
189
+ if (stage === "rename" && !published) {
190
+ // A refused rename normally leaves the saved target intact. If that
191
+ // cannot be re-established, report uncertainty rather than rollback.
192
+ try { recheck(); } catch { published = true; }
193
+ }
194
+ } finally {
195
+ // Capture partial-write identity through the still-owned descriptor before
196
+ // closing, so a write fault can clean its own scratch without adopting a
197
+ // substituted pathname. Do not refresh identity after a completed write.
198
+ if (fileFd !== null) {
199
+ if (writing) {
200
+ try {
201
+ const stat = operations.fstatSync(fileFd);
202
+ if (directoryIdentity(stat) === temporaryNode) temporaryIdentity = identity(stat);
203
+ } catch (error) { cleanupErrors.push(error); }
204
+ }
205
+ try { closeFile(); } catch (error) { cleanupErrors.push(error); }
206
+ }
207
+ if (directoryFd !== null) {
208
+ try { closeDirectory(); } catch (error) { cleanupErrors.push(error); }
209
+ }
210
+ if (!published && temporaryIdentity !== undefined) {
211
+ let safe = false;
212
+ // A refused ancestor replacement revokes pathname cleanup. Never remove
213
+ // the new target after rename, even if a later sync/close/recheck failed.
214
+ try { recheckAncestry(); safe = true; }
215
+ catch (error) { cleanupErrors.push(error); } // cleanup was refused, not silently successful
216
+ if (safe) {
217
+ try {
218
+ if (identity(operations.lstatSync(temporary)) === temporaryIdentity) operations.unlinkSync(temporary);
219
+ } catch (error) { if (error.code !== "ENOENT") cleanupErrors.push(error); }
220
+ }
221
+ }
222
+ }
223
+ if (cause || cleanupErrors.length) {
224
+ const primary = cause ?? cleanupErrors.shift();
225
+ const state = published ? "publication may have occurred; durability was not established" : "target was not published by this write";
226
+ const cleanup = cleanupErrors.length ? `; cleanup failed: ${cleanupErrors.map(error => error.message).join("; ")}` : "";
227
+ const error = new Error(`setup write failed for ${snapshot.path} at ${stage}: ${primary.message}; ${state}${cleanup}`, { cause: primary });
228
+ Object.assign(error, { path: snapshot.path, stage, published, cleanupErrors,
229
+ applied: [...madeParents.map(path => `created setup parent ${path} (write failed at ${stage}; inspect its durability)`),
230
+ ...(published ? [`${snapshot.path}: publication may have occurred at ${stage}; durability was not established`] : [])] });
231
+ throw error;
232
+ }
233
+ }
@@ -20,23 +20,24 @@ never does.
20
20
  | path | contents |
21
21
  |---|---|
22
22
  | `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
23
- | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel) and the loop: events through `reduce`, effects out, the frame drawn |
24
- | `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
25
- | `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
23
+ | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList` |
24
+ | `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one. The keys shared with the Desktop are not written here: the leader's table and the plain keys of the list come from `packages/client/keymap.mjs`, and `test/keymap.test.mjs` fails on a row of the shared table the TUI does not handle |
25
+ | `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`) |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
27
27
  | `lib/panel.mjs` | the open terminals, as tabs: the run's private tmux server (one control client, one window per tab, up to `MAX_TERMINALS`, each at the size its caller gives), the kernel's `oats session attach` in a pane of each, captures of the displayed tabs only (up to `MAX_SHOWN`, one per group of a split) when tmux says their pane changed, a hidden tab's output marking it, keys typed into the shown tab, and the sweep of what a dead run left; the only module that runs tmux (THE TABS in its header) |
28
- | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), and the two looks at the file system the switcher needs (the entries of `~/Agents`, and whether a picked folder is a deployment) |
28
+ | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
29
29
  | `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test) |
30
30
  | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows, by calling the shared readers: pure, no cell position |
31
- | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
31
+ | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock; under the kitty keyboard protocol it reads a `CSI … u` key as its legacy bytes read, a chord as its own id |
32
+ | `lib/term/kitty.mjs` | the kitty keyboard protocol: the flags asked for, a `CSI … u` key read, and the bytes the same key sends without the protocol (`legacyBytes`), which is what an agent is typed |
32
33
  | `lib/term/width.mjs` | the cells a grapheme takes |
33
34
  | `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
34
35
  | `lib/term/style.mjs` | style values: the TUI's own (the sixteen ANSI colours and four attributes) and an agent's (its colours, 256 and RGB included, and attributes, from a capture) |
35
36
  | `lib/term/capture.mjs` | a pane's capture (`capture-pane -e -N`) to rows of cells: characters and an allowlist of SGR, every other sequence and control dropped |
36
- | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key and a bracketed paste out of them |
37
+ | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key, a chord and a bracketed paste out of them and, under the kitty keyboard protocol, types every other key as its legacy bytes |
37
38
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
38
- | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
39
- | `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the Capabilities view (`capabilities.mjs`), the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
39
+ | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame; the kitty keyboard protocol pushed, asked about and popped on every way out |
40
+ | `lib/views/` | pure functions from the model and a size to rows of spans: the frame (the sidebar: its title, the accordion of the three views and the cheat sheet; the main area beside it), the list, the detail, the Capabilities view (`capabilities.mjs`), the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
40
41
 
41
42
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
42
43
 
@@ -46,7 +47,7 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
46
47
  one dynamic import where `bin/oats.mjs` dispatches the word.
47
48
  - Only `term/screen.mjs` and `term/tty.mjs` write an ESC byte in a string,
48
49
  and only they write to the terminal. `term/through.mjs` (the back key's
49
- bytes) and `lib/panel.mjs` (the paste marks it types into the agent's
50
+ bytes), `term/kitty.mjs` (a key's legacy bytes) and `lib/panel.mjs` (the paste marks it types into the agent's
50
51
  pane) hold theirs as numbers. Views are pure: no IO, no clock, no escape
51
52
  bytes.
52
53
  - No function of this package decodes a kernel answer, groups or orders
@@ -5,101 +5,112 @@
5
5
  // An action that does one thing in the list of instances and another in the switcher (`open`)
6
6
  // says so in `views`: what it does in each, in the order the help lists them. An action of one
7
7
  // view only (the four acts) names that view, so the help says where it acts.
8
+ // The keys the TUI shares with the Desktop are not written here: an action with no `keys` of its own
9
+ // takes its default keys from the shared keymap (packages/client/keymap.mjs PLAIN_KEYS), and the
10
+ // leader's table is the shared one (LEADER, below). What only the TUI has (q, Ctrl+C, Ctrl+Z, Ctrl+L,
11
+ // Ctrl+K, Tab, Esc, Delete, C, i) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
12
+ import { CHORDS, LEADER_TABLE, plainKeys } from "./client.mjs";
13
+ import { isBackKey } from "./term/through.mjs";
14
+
8
15
  export const ACTIONS = Object.freeze([
9
- { id: "up", keys: ["up", "k"], label: "up" },
10
- { id: "down", keys: ["down", "j"], label: "down" },
11
- { id: "top", keys: ["g", "home"], label: "first" },
12
- { id: "bottom", keys: ["G", "end"], label: "last" },
13
- { id: "page-up", keys: ["pageup"], label: "page up" },
14
- { id: "page-down", keys: ["pagedown"], label: "page down" },
15
- { id: "collapse", keys: ["left", "h"], label: "collapse, or go to the parent" },
16
- { id: "expand", keys: ["right", "l"], label: "expand, or go to the first child" },
16
+ { id: "up", label: "up" },
17
+ { id: "down", label: "down" },
18
+ { id: "top", label: "first" },
19
+ { id: "bottom", label: "last" },
20
+ { id: "page-up", label: "page up" },
21
+ { id: "page-down", label: "page down" },
22
+ { id: "collapse", label: "collapse, or go to the parent" },
23
+ { id: "expand", label: "expand, or go to the first child" },
17
24
  { id: "detail", keys: ["tab"], label: "detail" },
18
- { id: "filter", keys: ["/"], label: "filter" },
19
- { id: "refresh", keys: ["r"], label: "refresh" },
20
- // The views by their number. The header names the views and never draws a digit against a name
21
- // (docs/tui.md, "The header"): the digits are named here, so in the help and the footer.
22
- { id: "instances", keys: ["1"], label: "instances" },
23
- { id: "souls", keys: ["2"], label: "souls" },
24
- { id: "capabilities", keys: ["3"], label: "capabilities" },
25
- { id: "workspaces", keys: ["w"], label: "workspaces" },
25
+ { id: "filter", label: "filter" },
26
+ { id: "refresh", label: "refresh" },
27
+ // The views by their number. The sidebar names the views, each with its key at the right of its row
28
+ // (docs/tui.md, "What it shows"): the digits are named here, so in the help and the sidebar.
29
+ { id: "instances", label: "instances" },
30
+ { id: "souls", label: "souls" },
31
+ { id: "capabilities", label: "capabilities" },
32
+ { id: "workspaces", label: "workspaces" },
26
33
  // The palette (docs/tui.md, "The palette"): from every focus it is the leader and then `k`.
27
34
  { id: "palette", keys: ["ctrl+k"], label: "palette" },
28
- { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal as a tab beside the list, or show its tab when it has one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"], ["souls", "show the selected soul's detail, and from the detail its instances, in the Souls view"], ["capabilities", "show the selected capability's detail, and from the detail the marked soul that uses it, in the Capabilities view"]] },
35
+ { id: "open", label: "open", views: [["instances", "open the selected agent's terminal as a tab beside the list, or show its tab when it has one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"], ["souls", "show the selected soul's detail, and from the detail its instances, in the Souls view"], ["capabilities", "show the selected capability's detail, and from the detail the marked soul that uses it, in the Capabilities view"]] },
36
+ // The switcher's Remove (docs/tui.md, "The switcher"; awebai/oats#1390): a row of this computer's
37
+ // deployments list, after a confirmation; nothing on disk is touched. Delete, and no letter: a new
38
+ // default key that a user's tui.json already gives to another action would make that file refused
39
+ // at the start (config.mjs claims every default first), and the free letters are the ones a
40
+ // tui.json is likeliest to use (`x` and `m` among them, see the split below).
41
+ { id: "remove", keys: ["delete"], label: "remove", views: [["switcher", "remove the selected row of this computer's list of deployments, after a confirmation; its folder stays"]] },
29
42
  // The Souls view (docs/tui.md, "The Souls view"): the selected soul's instances, in the
30
43
  // Instances view, filtered by that soul.
31
44
  { id: "soul-instances", keys: ["i"], label: "instances", views: [["souls", "the selected soul's instances, in the Instances view"]] },
32
45
  // The open terminal, from the list (docs/tui.md, "Open an agent's terminal"). While the terminal
33
46
  // has the focus the TUI takes no key but the leader (tui.json's open.detachKey), so neither of
34
47
  // these is ever read there: the leader's table has its own (LEADER).
35
- { id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader twice brings the list back"]] },
36
- { id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the shown terminal and show its neighbour; the agent keeps running"]] },
37
- { id: "tab-previous", keys: ["["], label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
38
- { id: "tab-next", keys: ["]"], label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
48
+ { id: "zoom", label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader then Esc brings the list back"]] },
49
+ { id: "close-terminal", label: "close terminal", views: [["instances", "close the shown terminal and show its neighbour; the agent keeps running"]] },
50
+ { id: "tab-previous", label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
51
+ { id: "tab-next", label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
39
52
  // The split (docs/tui.md, "Splits"): two groups of tabs at most, side by side or one above the
40
53
  // other. `group-next`, `tab-move` and `group-close` have no key of their own here by default
41
54
  // (Tab is the detail's, and `m` and `x` are often a tui.json's): the leader's are.
42
- { id: "split-right", keys: ["|"], label: "split right", views: [["instances", "split the panel side by side; the new group, on the right, is empty and focused"]] },
43
- { id: "split-down", keys: ["-"], label: "split down", views: [["instances", "split the panel one above the other; the new group, below, is empty and focused"]] },
55
+ { id: "split-right", label: "split right", views: [["instances", "split the panel side by side; the new group, on the right, is empty and focused"]] },
56
+ { id: "split-down", label: "split down", views: [["instances", "split the panel one above the other; the new group, below, is empty and focused"]] },
44
57
  { id: "group-next", keys: [], label: "next group", views: [["instances", "go to the other group's terminal, or to the focused group's from the list"]] },
45
58
  { id: "tab-move", keys: [], label: "move tab", views: [["instances", "move the shown tab to the other group, and go there"]] },
46
59
  { id: "group-close", keys: [], label: "close group", views: [["instances", "close the focused group while it is empty"]] },
47
60
  // The four acts on an instance: each opens a confirmation, and nothing is done before a move and
48
61
  // a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
49
- { id: "stop", keys: ["X"], label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
50
- { id: "retire", keys: ["D"], label: "retire", views: [["instances", "retire the selected agent, after a confirmation"]] },
51
- { id: "start", keys: ["S"], label: "start", views: [["instances", "start the selected agent as it was last launched, after a confirmation"]] },
52
- { id: "restart", keys: ["R"], label: "restart", views: [["instances", "restart the selected agent as it was last launched, after a confirmation"]] },
62
+ { id: "stop", label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
63
+ { id: "retire", label: "retire", views: [["instances", "retire the selected agent, after a confirmation"]] },
64
+ { id: "start", label: "start", views: [["instances", "start the selected agent as it was last launched, after a confirmation"]] },
65
+ { id: "restart", label: "restart", views: [["instances", "restart the selected agent as it was last launched, after a confirmation"]] },
53
66
  // A spawn (docs/tui.md, "Spawning an agent"): a prompt over the list, the soul picked, the
54
67
  // shared preview, and one Enter. Only on this machine's workspace, one spawn at a time.
55
- { id: "spawn", keys: ["n"], label: "spawn", views: [["instances", "spawn an agent: pick its soul, then the preview, and Enter spawns it"], ["souls", "spawn an agent of the selected soul: the preview, and Enter spawns it"]] },
56
- { id: "spawn-another", keys: ["N"], label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
68
+ { id: "spawn", label: "spawn", views: [["instances", "spawn an agent: pick its soul, then the preview, and Enter spawns it"], ["souls", "spawn an agent of the selected soul: the preview, and Enter spawns it"]] },
69
+ { id: "spawn-another", label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
57
70
  // Offered only while a spawn's outcome is not known: it asks the kernel once, never spawns again.
58
71
  { id: "spawn-check", keys: ["C"], label: "check spawn", views: [["instances", "check the result of a spawn whose outcome is not known, while one is"]] },
59
- { id: "help", keys: ["?"], label: "help" },
72
+ { id: "help", label: "help" },
60
73
  { id: "close", keys: ["escape"], label: "close" },
61
74
  { id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
62
75
  { id: "suspend", keys: ["ctrl+z"], label: "suspend" },
63
76
  { id: "redraw", keys: ["ctrl+l"], label: "redraw" },
64
- ].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]), ...(action.views ? { views: Object.freeze(action.views.map((view) => Object.freeze([...view]))) } : {}) })));
77
+ ].map(({ keys, ...action }) => Object.freeze({ id: action.id, keys: Object.freeze([...(keys ?? plainKeys(action.id))]), ...action, ...(action.views ? { views: Object.freeze(action.views.map((view) => Object.freeze([...view]))) } : {}) })));
65
78
 
66
79
  /** THE LEADER'S TABLE (docs/tui.md, "The leader"): the keys read after the leader (tui.json's
67
- * open.detachKey) and what each does, from every focus. Fixed: tui.json's `keys` rebinds the plain
68
- * keys of ACTIONS only. `does` is an action id of ACTIONS, or one of the leader's own: `previous`
69
- * and `next` (the instance before or after the shown terminal's, or the selection's: its tab
70
- * shown, or opened as a new one, with the focus in it) and `list` (the list's focus). The leader pressed again is `list` too: it is
71
- * the user's key, so it is not in this table. `terminal`: named in the hint only while a terminal
72
- * is open, and nothing without one (the hint names the tab keys only with two tabs or more). */
73
- export const LEADER = Object.freeze([
74
- { keys: ["k", "space"], does: "palette", label: "palette" },
75
- { keys: ["1"], does: "instances", label: "instances" },
76
- { keys: ["2"], does: "souls", label: "souls" },
77
- { keys: ["3"], does: "capabilities", label: "capabilities" },
78
- { keys: ["up"], does: "previous", label: "previous instance" },
79
- { keys: ["down"], does: "next", label: "next instance" },
80
- { keys: ["z"], does: "zoom", label: "zoom", terminal: true },
81
- { keys: ["w"], does: "close-terminal", label: "close terminal", terminal: true },
82
- { keys: ["left"], does: "tab-previous", label: "previous tab", terminal: true },
83
- { keys: ["right"], does: "tab-next", label: "next tab", terminal: true },
84
- { keys: ["|"], does: "split-right", label: "split right", terminal: true },
85
- { keys: ["-"], does: "split-down", label: "split down", terminal: true },
86
- { keys: ["tab"], does: "group-next", label: "next group", terminal: true },
87
- { keys: ["m"], does: "tab-move", label: "move tab", terminal: true },
88
- { keys: ["x"], does: "group-close", label: "close group", terminal: true },
89
- { keys: ["X"], does: "stop", label: "stop" },
90
- { keys: ["R"], does: "restart", label: "restart" },
91
- { keys: ["S"], does: "start", label: "start" },
92
- { keys: ["D"], does: "retire", label: "retire" },
93
- { keys: ["n"], does: "spawn", label: "spawn" },
94
- { keys: ["N"], does: "spawn-another", label: "spawn another" },
95
- { keys: ["/"], does: "filter", label: "filter" },
96
- { keys: ["o"], does: "workspaces", label: "workspaces" },
97
- { keys: ["?"], does: "help", label: "help" },
98
- { keys: ["escape"], does: "list", label: "the list" },
99
- ].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
80
+ * open.detachKey) and what each does, from every focus. It is the shared one, the Desktop's too
81
+ * (packages/client/keymap.mjs LEADER_TABLE), in its order, with its labels and its `terminal`
82
+ * rows: named in the hint only while a terminal is open, and nothing without one. What the TUI
83
+ * adds to a row is its own, keyed by `does`: the hint's filters (views/frame.mjs leaderHints:
84
+ * the tab keys only with two tabs or more, the split's only where they apply). Fixed: tui.json's
85
+ * `keys` rebinds the plain keys of ACTIONS only. Each `does` is handled by the TUI
86
+ * (leaderHandles); the leader pressed again is not in the table, as it is the user's key: from the
87
+ * open terminal's focus it types the leader's own bytes into the agent, the focus staying there,
88
+ * and from any other focus it only closes the hint (lib/store.mjs `twice`). */
89
+ export const LEADER = LEADER_TABLE;
90
+ /** What the leader does that no action of ACTIONS does (lib/store.mjs `led`): `previous` and
91
+ * `next` (the instance before or after the shown terminal's, or the selection's: its tab shown,
92
+ * or opened as a new one, with the focus in it) and `list` (the list's focus, which Esc gives). */
93
+ export const LEADER_OWN = Object.freeze(["previous", "next", "list"]);
94
+ /** Whether the TUI acts on `does`, a `does` of the shared leader table: it is one of the leader's
95
+ * own (LEADER_OWN), or the id of an action of ACTIONS, which lib/store.mjs `led` runs as its key
96
+ * runs it, or in its own way from the leader (the terminal's keys, the acts, the spawns). A
97
+ * `does` the TUI does not handle is a failure of packages/tui/test/keymap.test.mjs, never a
98
+ * key that does nothing. */
99
+ export const leaderHandles = (does) => LEADER_OWN.includes(does) || ACTIONS.some((action) => action.id === does);
100
100
  /** key id -> what the leader then does (LEADER's `does`). */
101
101
  export const LEADER_KEYS = new Map(LEADER.flatMap((entry) => entry.keys.map((key) => [key, entry.does])));
102
102
 
103
+ /** THE CHORDS (docs/tui.md, "Chords"): key id -> `does`, the shared ones (packages/client/keymap.mjs
104
+ * CHORDS) on macOS (`isMac`) or elsewhere, each doing what the leader then its key does
105
+ * (lib/store.mjs `led`). Read only while the terminal confirms the kitty keyboard protocol, which
106
+ * alone sends them. Left out: a chord with `cmd+` (a terminal never passes macOS's Command to a
107
+ * program), and one whose key an action of `actions` binds (a user's tui.json keeps its key).
108
+ * Each `does` is one the TUI handles (leaderHandles): packages/tui/test/chords.test.mjs. */
109
+ export function chordKeys(isMac, actions = ACTIONS) {
110
+ const bound = new Set(actions.flatMap((action) => action.keys));
111
+ return new Map(CHORDS.map((entry) => [isMac ? entry.mac : entry.other, entry.does]).filter(([key, does]) => !key.startsWith("cmd+") && !bound.has(key) && leaderHandles(does)));
112
+ }
113
+
103
114
  /** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
104
115
  export function bindings(actions = ACTIONS) {
105
116
  const map = new Map();
@@ -118,3 +129,17 @@ export function keyLabel(key) {
118
129
  const name = NAMES[last] ?? (/^f\d+$/.test(last) ? last.toUpperCase() : parts.length && last.length === 1 ? last.toUpperCase() : last);
119
130
  return [...parts.map((part) => NAMES[part] ?? part), name].join("+");
120
131
  }
132
+
133
+ /** The modifiers of the back key's grammar (term/through.mjs BACK_KEY) as a person reads them. */
134
+ const BACK_MODIFIERS = Object.freeze({ C: "Ctrl", M: "Alt", S: "Shift" });
135
+ /** A back key (tui.json's open.detachKey, the leader) as the cheat sheet and the help name it, spelt
136
+ * for people as keyLabel spells a key id: `C-\\` is `Ctrl+\\`, `C-x` is `Ctrl+X`, `M-o` is `Alt+O`,
137
+ * `M-5` is `Alt+5`, `F12` is `F12`, `S-F5` is `Shift+F5`. A letter is written as a capital, which
138
+ * never means Shift (the grammar has lowercase Meta letters only). Pure. A value outside the
139
+ * grammar is answered as it was given (tui.json refuses it; a view draws it as text from outside). */
140
+ export function backKeyLabel(key) {
141
+ if (!isBackKey(key)) return key;
142
+ const [, mod, rest] = /^(?:([CMS])-)?(.+)$/.exec(key);
143
+ const name = rest.length === 1 ? rest.toUpperCase() : rest;
144
+ return mod ? `${BACK_MODIFIERS[mod]}+${name}` : name;
145
+ }
@@ -9,6 +9,8 @@ import { clientTerms } from "../../client/client-terms.mjs";
9
9
  export { displayLine, DETAIL_WITHHELD } from "../../client/display-text.mjs";
10
10
  export { parseProbeStdout, acceptProbe, cliRecord } from "../../client/cli-locator.mjs";
11
11
  export { cliDeploymentRead } from "../../client/deployment-read-cli.mjs";
12
+ export { cliDeploymentList } from "../../client/deployment-list-cli.mjs";
13
+ export { deploymentsListSupported } from "../../client/deployment-list.mjs";
12
14
  export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
13
15
  export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
14
16
  export { createRefreshLoop } from "../../client/refresh-loop.mjs";
@@ -33,7 +35,7 @@ export { createRetiresInFlight, retiringRows } from "../../client/retire-in-flig
33
35
  export { startGate, startInstance } from "../../client/session-start.mjs";
34
36
  export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
35
37
  export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
36
- export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
38
+ export { validateWorkspace } from "../../client/workspace-admission.mjs";
37
39
  export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
38
40
  export { soulRows } from "../../client/soul-rows.mjs";
39
41
  export { soulFacts, spawnRefusal, soulMatches } from "../../client/soul-facts.mjs";
@@ -48,6 +50,7 @@ export { subsequenceScore } from "../../client/subsequence-score.mjs";
48
50
  export { createCapabilityCatalog, capabilityCatalogKey } from "../../client/capability-catalog.mjs";
49
51
  export { memberNames, capabilitySource, groupCapabilities, hostKeyOf, capabilitySections, matchCapabilities, soulsComposition, rosterAgentName, layerLabel, capabilityUsers } from "../../client/capability-rows.mjs";
50
52
  export { capabilityFacts, CAPABILITY_COPY } from "../../client/capability-facts.mjs";
53
+ export { CHORDS, LEADER_TABLE, PLAIN_KEYS, leaderKey, plainKeys } from "../../client/keymap.mjs";
51
54
 
52
55
  /** The words a shared sentence uses where it names the client that shows it (client-terms.mjs).
53
56
  * Made once, here: every shared function that takes `terms` is passed this constant, and refuses