@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
@@ -11,11 +11,11 @@
11
11
  // functions (client.mjs), which decide what a roster, a row and a failed read are, once, for both
12
12
  // clients: the TUI never writes "stopped" for a row and never builds the collector's input by hand.
13
13
  import { execFile as nodeExecFile, spawn as nodeSpawn } from "node:child_process";
14
- import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, opendirSync, readSync, realpathSync, rmdirSync, statSync, unlinkSync } from "node:fs";
14
+ import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, realpathSync, rmdirSync, statSync, unlinkSync } from "node:fs";
15
15
  import { tmpdir } from "node:os";
16
- import { basename, dirname, join } from "node:path";
16
+ import { dirname, join } from "node:path";
17
17
  import { fileURLToPath } from "node:url";
18
- import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, deploymentsInside, failedEntry, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
18
+ import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, failedEntry, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
19
19
 
20
20
  /** A path made canonical: what the shared start rule checks a local home with (session-start.mjs
21
21
  * verifiedLocalHome). Throws for a path that cannot be resolved; the rule answers that as no home. */
@@ -61,26 +61,13 @@ export function leaveInstance(env) {
61
61
  /** A step that must not stop the ones after it: a child, a stream or a directory that is already gone. */
62
62
  const quietly = (act) => { try { return act(); } catch { return undefined; } };
63
63
 
64
- /** The filesystem the three functions below read when they are given none. findDeployment: one
64
+ /** The filesystem the two functions below read when they are given none. findDeployment: one
65
65
  * realpath and one stat of the start, then one lstat per directory. A symbolic link named
66
- * oats-local.yaml is not a deployment's file (lstat does not follow it).
67
- * `list(dir, limit)` is the look inside a folder the shared deploymentsInside asks for:
68
- * -> { entries: [{ name, isDirectory }], limited }. It reads at most `limit` entries, and one more
69
- * only to say whether the folder holds more (`limited`), so a folder of any size costs a bounded
70
- * read. `isDirectory` is the entry's own type: a link to a directory is not a directory, and
71
- * nothing is followed. It throws for a folder that cannot be opened; the shared function answers
72
- * that as a folder that holds nothing. */
66
+ * oats-local.yaml is not a deployment's file (lstat does not follow it). */
73
67
  const DEPLOYMENT_IO = Object.freeze({
74
68
  realpath: (path) => realpathSync(path),
75
69
  isDirectory: (path) => statSync(path).isDirectory(),
76
70
  isDeployment: (dir) => lstatSync(join(dir, "oats-local.yaml")).isFile(),
77
- list: (dir, limit) => {
78
- const handle = opendirSync(dir), entries = [];
79
- try {
80
- for (let entry; entries.length < limit && (entry = handle.readSync());) entries.push({ name: entry.name, isDirectory: entry.isDirectory() });
81
- return { entries, limited: entries.length >= limit && handle.readSync() !== null };
82
- } finally { quietly(() => handle.closeSync()); }
83
- },
84
71
  });
85
72
 
86
73
  /** The deployment `start` is in: (start directory, io?) -> { ok: true, deployment } | { ok: false, dir }.
@@ -102,34 +89,9 @@ export function findDeployment(start, io = {}) {
102
89
  }
103
90
  }
104
91
 
105
- /** The deployments the switcher offers unasked: those directly inside `<home>/Agents` that this run
106
- * does not serve. (home, served, io?) -> { offered: [{ path, name }], limited }.
107
- * Which folders are deployments, their order and the limit of the look are the shared
108
- * deploymentsInside's; this adds only what a run knows. Each path is made canonical (io.realpath)
109
- * BEFORE it is compared with `served`, whose ids are canonical: a `~/Agents` reached through a
110
- * link would otherwise offer a deployment the run already shows. One that cannot be resolved (it
111
- * went away since the look) is left out, and so is a second folder that leads to the same place.
112
- * `name` is the folder's name as it was listed, `path` the canonical one to admit. `limited` says
113
- * the folder holds more entries than were read. Nothing is read from any deployment: an offered
114
- * one is read when it is picked. Never throws: a missing or unreadable `~/Agents` offers nothing. */
115
- export function offeredDeployments(home, served, io = {}) {
116
- try {
117
- const { realpath, isDeployment, list } = { ...DEPLOYMENT_IO, ...io };
118
- const inside = deploymentsInside(join(home, "Agents"), { list, isDeployment });
119
- const taken = new Set(served), offered = [];
120
- for (const listed of inside.paths) {
121
- const path = quietly(() => realpath(listed));
122
- if (typeof path !== "string" || taken.has(path)) continue;
123
- taken.add(path);
124
- offered.push({ path, name: basename(listed) });
125
- }
126
- return { offered, limited: inside.limited };
127
- } catch { return { offered: [], limited: false }; }
128
- }
129
-
130
92
  /** Whether `path` is a deployment NOW: (path, io?) -> { ok: true, deployment } | { ok: false }.
131
- * Asked when an offered deployment is picked: the offer is as old as the last look, and the
132
- * folder may have stopped being a deployment since. The path is made canonical (io.realpath) and
93
+ * Asked when a row of this computer's deployments list is picked: the row is as old as the last
94
+ * read of the list, and the folder may have stopped being a deployment since. The path is made canonical (io.realpath) and
133
95
  * the shared validateWorkspace is asked about that directory itself. Unlike findDeployment it
134
96
  * walks nowhere: a folder that is no longer a deployment must not open the one above it in its
135
97
  * place. `deployment` is the canonical path, the id a served deployment has. Never throws. */
@@ -167,6 +129,14 @@ export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = no
167
129
  });
168
130
  }
169
131
 
132
+ /** The exec of the one kernel call made before the terminal is taken but the probe: the read of
133
+ * this computer's deployments list at a start outside every deployment (the shared
134
+ * cliDeploymentList's `io.exec`). execFile's signature for `node <bin> <argv…>`, as the probe
135
+ * runs the kernel, and NOT detached, as the probe is not: a Ctrl+C then ends it with the TUI. */
136
+ export function startExec(bin, argv, options, callback) {
137
+ return nodeExecFile(process.execPath, [bin, ...argv], options, callback);
138
+ }
139
+
170
140
  /** Where a change's output goes (createReader `files`). `dir()` makes the run's private directory
171
141
  * (mkdtemp: mode 0700, under the OS temp dir); `open` makes one file in it for the child alone
172
142
  * (0600, refused if it is there); `read(path, max)` reads back at most `max` bytes and one more,
@@ -9,11 +9,11 @@
9
9
  // removed, and nothing here decides what a failed read means or which view a deployment is in.
10
10
  // Selection is an identity (the shared `instanceId`), never an index, so it survives every read;
11
11
  // the rows it moves among are the model's, in drawn order.
12
- import { ACTIONS, LEADER_KEYS, bindings } from "./actions.mjs";
12
+ import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys } from "./actions.mjs";
13
13
  import { collapseKey, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
14
- import { DETACH_KEY } from "./config.mjs";
15
- import { BUTTON_ORDER, SPAWN_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher } from "./model.mjs";
16
- import { backKeyId } from "./term/through.mjs";
14
+ import { defaultDetachKey } from "./config.mjs";
15
+ import { BUTTON_ORDER, SPAWN_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, LIST_WORDS } from "./model.mjs";
16
+ import { backKeyId, backKeySequences, isBackKey } from "./term/through.mjs";
17
17
  import { windowOf } from "./views/scroll.mjs";
18
18
  import { SPLIT_MIN, splitFits } from "./views/split.mjs";
19
19
 
@@ -53,7 +53,10 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
53
53
  * on purpose (see `scrolledList`); the switcher has its own.
54
54
  * `selected`, `top`, `detailTop` are the open view's; `places` keeps them for
55
55
  * the views left behind, and `collapsed` holds every view's keys (each carries its `open`).
56
- * `back`: the view under the help. `offered`: the deployments of `~/Agents` not served.
56
+ * `back`: the view under the help. `listed`: this computer's deployments list as it was last read
57
+ * (awebai/oats#1390): `rows`, the shared reader's `{ path, name, state }` in the kernel's order, of
58
+ * the last read that answered, and `failure`, the reason (`{ code, message }`) the last read failed
59
+ * with, or null once one answered. The switcher offers the rows this run does not serve.
57
60
  * `opening`: the agent of another machine whose terminal is being opened, or null:
58
61
  * `{ id, phase: "preflight", name, machine, routed }` while that machine is asked whether its
59
62
  * session is there; `name`, `machine` and `routed` are the row's as it was when Enter was
@@ -70,10 +73,17 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
70
73
  * "terminal" while what is typed goes to the agent and "list" while the TUI reads keys, and `zoom`
71
74
  * true while it has the whole body (only with the terminal's focus).
72
75
  * `outcome`: the line after an open (the model's `{ said, under }`), shown above the panes until
73
- * the next key bound to an action, or null.
74
- * `detachKey`: tui.json's `open.detachKey`, the leader (docs/tui.md, "The leader"), and
75
- * `leaderKey` the key id it is read as where the TUI reads keys (term/through.mjs backKeyId).
76
+ * the next key bound to an action, or null. `notice`: such a line that came while no view that
77
+ * draws one at every width was shown (the switcher, the help, a detail or a terminal with the
78
+ * focus: see `drawsOutcome`), held until one is; or null.
79
+ * It is the add of the deployment the run started in, refused.
80
+ * `detachKey`: tui.json's `open.detachKey`, the leader (docs/tui.md, "The leader"; without one,
81
+ * `platform`'s default, config.mjs defaultDetachKey), and `leaderKey` the key id it is read as
82
+ * where the TUI reads keys (term/through.mjs backKeyId).
76
83
  * `leader`: `{ read, waiting }` from the leader's read on, or null (see `leading`).
84
+ * `keyboard`: the flags the terminal confirmed for the kitty keyboard protocol (lib/main.mjs, the
85
+ * event `{ keyboard }`), or null while it has not; `chords`: the chords of `platform`, key id ->
86
+ * `does` (actions.mjs chordKeys), read only while `keyboard` is not null (see `leading`).
77
87
  * `palette`: the palette while it is open (see `paletteOpened`), or null. `recent`: the ids of
78
88
  * the instances opened in this run, the latest first.
79
89
  * `act`: the confirmation open in the act view (see `actOpened`), or null; `acted` counts the
@@ -93,7 +103,7 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
93
103
  * agentsRoot, agent, reads, words }`, until its row is opened or two reads did not show it;
94
104
  * `previews` the number of the last preview read asked in the run, so that an answer to a prompt
95
105
  * already closed is never taken by the next one. */
96
- export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, detachKey = DETACH_KEY }) {
106
+ export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, platform = process.platform, detachKey = defaultDetachKey(platform) }) {
97
107
  return Object.freeze({
98
108
  view: deployment === null ? "switcher" : "instances", back: deployment === null ? "switcher" : "instances",
99
109
  ctxs: Object.freeze(deployment === null ? [] : [deployment]), open: deployment,
@@ -101,15 +111,24 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
101
111
  remote: Object.freeze({ remoteGroups: Object.freeze([]), rosterAnswered: false, rosterFailure: null }), rosterAt: null,
102
112
  memory: new Map(), notes: new Map(), collecting: false, cli, home,
103
113
  selected: null, collapsed: new Set(), filter: NO_FILTER, focus: "list", top: 0, loose: false, detailTop: 0, places: new Map(), unread: new Map(),
104
- switcher: Object.freeze({ editing: false, query: "", selected: null, top: 0, loose: false, line: null, refused: null }),
105
- offered: Object.freeze({ offered: Object.freeze([]), limited: false }),
114
+ switcher: NO_SWITCHER,
115
+ listed: NO_LIST,
106
116
  helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
107
- leaderKey: backKeyId(detachKey), leader: null, palette: null, recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
117
+ leaderKey: backKeyId(detachKey), leader: null, keyboard: null, chords: chordKeys(platform === "darwin", actions), palette: null, recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
108
118
  spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
119
+ notice: null,
109
120
  });
110
121
  }
111
122
 
112
123
  const next = (state, changes) => Object.freeze({ ...state, ...changes });
124
+
125
+ /** The switcher's own: the filter, the selection and the scroll; `line`, what it says above its rows
126
+ * of what happened (lib/model.mjs SWITCHER_LINES: "gone", or the answer of a Remove); `refused`,
127
+ * the path of a picked row that turned out not to be a deployment; `removing`, the Remove asked
128
+ * for, `{ path, read }` (the row and the read of input that asked), until it is answered or kept. */
129
+ const NO_SWITCHER = Object.freeze({ editing: false, query: "", selected: null, top: 0, loose: false, line: null, refused: null, removing: null });
130
+ /** This computer's deployments list before its first read. */
131
+ const NO_LIST = Object.freeze({ rows: Object.freeze([]), failure: null });
113
132
  const indexOf = (r, id) => (id === null ? -1 : r.index.get(id) ?? -1);
114
133
  /** Whether an item of the list is an instance: the only kind the selection stands on. */
115
134
  const isRow = (item) => item?.id !== undefined;
@@ -160,7 +179,7 @@ function rehomed(before, state) {
160
179
  }
161
180
 
162
181
  /** The switcher, shown: over whatever view was there. `said`: a line of its own to show. */
163
- const toSwitcher = (state, said = null) => next(state, { view: "switcher", switcher: Object.freeze({ ...state.switcher, editing: false, loose: false, line: said, refused: null }) });
182
+ const toSwitcher = (state, said = null) => next(state, { view: "switcher", switcher: Object.freeze({ ...state.switcher, editing: false, loose: false, line: said, refused: null, removing: null }) });
164
183
 
165
184
  /** After what the reader gave changed: when no view holds what was open any more (a machine that
166
185
  * is no longer listed), the switcher is shown and says so, and nothing is open. Else the
@@ -179,7 +198,7 @@ function settled(state, taken) {
179
198
  const places = new Map(taken.places); places.delete(taken.open);
180
199
  // A confirmation open over that view is closed with it: what it sent goes on.
181
200
  const dismiss = taken.act !== null ? { dismiss: taken.act.n } : {};
182
- return { state: toSwitcher(next(taken, { open: null, places, selected: null, top: 0, loose: false, detailTop: 0, focus: "list", filter: NO_FILTER, back: "switcher", act: null }), "gone"), effect: { offer: true, ...dismiss } };
201
+ return { state: toSwitcher(next(taken, { open: null, places, selected: null, top: 0, loose: false, detailTop: 0, focus: "list", filter: NO_FILTER, back: "switcher", act: null }), "gone"), effect: { list: true, ...dismiss } };
183
202
  }
184
203
  const before = roster(state);
185
204
  const unknown = new Set([...taken.unread.values()].flatMap((ids) => [...ids]));
@@ -219,7 +238,7 @@ function heard(state, { remote, memory, notes, at }) {
219
238
  /** Open the view of deployment `id`: the place the view left behind is kept, and found again
220
239
  * on the way back (the row, where the list and the detail were scrolled). A filter is not kept. */
221
240
  function opened(state, id) {
222
- const shown = next(state, { view: "instances", back: "instances", switcher: Object.freeze({ ...state.switcher, editing: false, query: "", line: null, refused: null }) });
241
+ const shown = next(state, { view: "instances", back: "instances", switcher: Object.freeze({ ...state.switcher, editing: false, query: "", line: null, refused: null, removing: null }) });
223
242
  if (id === state.open) return shown;
224
243
  const places = new Map(state.places);
225
244
  if (state.open !== null) places.set(state.open, Object.freeze({ selected: state.selected, top: state.top, detailTop: state.detailTop }));
@@ -227,8 +246,9 @@ function opened(state, id) {
227
246
  return rehomed({ rows: [] }, next(shown, { open: id, places, focus: "list", filter: NO_FILTER, loose: false, ...place }));
228
247
  }
229
248
 
230
- /** A picked folder of `~/Agents` that is a deployment (lib/read.mjs made it canonical and asked
231
- * the shared rule): it is served from now on, pending until its first read, and opened. */
249
+ /** A picked row of this computer's deployments list that is a deployment (lib/read.mjs made it
250
+ * canonical and asked the shared rule): it is served from now on, pending until its first read,
251
+ * and opened. */
232
252
  function admitted(state, { admitted: id, at }) {
233
253
  if (state.ctxs.includes(id)) return opened(state, id);
234
254
  const joined = next(state, { ctxs: Object.freeze([...state.ctxs, id]), entries: new Map(state.entries).set(id, pendingEntry(null, at)) });
@@ -468,8 +488,10 @@ function moved(action, from, count, page) {
468
488
  }
469
489
 
470
490
  /** A key in the switcher. The selection moves among the choices (a heading is passed over);
471
- * the open key opens the view of a workspace here, and asks the loop to admit a folder. */
472
- function switched(state, action, page) {
491
+ * the open key opens the view of a workspace here, and asks the loop to admit a row of the list
492
+ * that is a deployment (a stale one does not open: its row says why). The remove key asks whether
493
+ * to remove the selected row of the list from it (see `removal`). */
494
+ function switched(state, action, page, event) {
473
495
  const stay = { state, effect: null };
474
496
  const s = switcher(state), sw = state.switcher;
475
497
  const put = (changes) => next(state, { switcher: Object.freeze({ ...sw, ...changes }) });
@@ -481,13 +503,14 @@ function switched(state, action, page) {
481
503
  return state.open === null ? stay : { state: next(put({ line: null, refused: null }), { view: "instances", back: "instances" }), effect: null };
482
504
  case "instances": return state.open === null ? stay : { state: next(put({ line: null, refused: null }), { view: "instances", back: "instances" }), effect: null };
483
505
  case "up": case "down": case "top": case "bottom": case "page-up": case "page-down": {
484
- // The rows of the pane the choices have: the line that says what happened takes one (lib/model.mjs).
485
- const count = s.items.length, height = Math.max(1, page - (sw.line ? 1 : 0));
506
+ // The rows of the pane the choices have: the lines above them take theirs, and the filter
507
+ // field one while it is shown (lib/model.mjs switcherHeight).
508
+ const count = s.items.length, height = switcherHeight(state, page, event.area);
486
509
  const drawn = windowOf({ top: sw.top, count, height, keep: sw.loose ? -1 : s.items.findIndex((item) => item.key !== undefined && item.key === s.selected) }).top;
487
510
  const from = Math.max(0, s.keys.indexOf(s.selected));
488
511
  const key = s.keys.length ? s.keys[Math.min(Math.max(0, moved(action, from, s.keys.length, page)), s.keys.length - 1)] : null;
489
512
  // No choice to go to in that direction (the first, the last, or none at all): the rows
490
- // scroll instead, so a line under the last choice (that the folder holds more) is read.
513
+ // scroll instead, so what stands above the first choice or under the last one is read.
491
514
  if (key === null || key === s.selected) {
492
515
  const top = windowOf({ top: moved(action, drawn, count, height), count, height }).top;
493
516
  return top === drawn ? stay : { state: put({ top, loose: true }), effect: null };
@@ -500,13 +523,49 @@ function switched(state, action, page) {
500
523
  case "open": {
501
524
  const item = s.items.find((each) => each.key !== undefined && each.key === s.selected);
502
525
  if (!item) return stay;
503
- if (item.path !== undefined) return { state: put({ refused: null }), effect: { admit: item.path } };
526
+ if (item.path !== undefined) return item.state === "ok" ? { state: put({ refused: null }), effect: { admit: item.path } } : stay;
504
527
  return item.primary === null ? stay : { state: opened(state, item.primary), effect: { refresh: { live: true } } };
505
528
  }
529
+ case "remove": {
530
+ const item = s.items.find((each) => each.key !== undefined && each.key === s.selected);
531
+ // The row asked about is the selected one from then on, whatever the list or the roster bring
532
+ // meanwhile; a question whose row is no longer the one marked goes (see `askedStill`).
533
+ return item?.path === undefined ? stay : { state: put({ selected: item.key, removing: Object.freeze({ path: item.path, read: event.read ?? null }), line: null, refused: null }), effect: null };
534
+ }
506
535
  default: return stay;
507
536
  }
508
537
  }
509
538
 
539
+ /** A key while the switcher asks whether to remove a row of this computer's deployments list
540
+ * (docs/tui.md, "The switcher"). Enter removes it: the loop runs `oats deployments remove`, and
541
+ * nothing on disk is touched. Esc keeps it, and so does every other key, which then does what it
542
+ * does. Enter and Esc are the keys themselves, as the question says them, not the actions the
543
+ * user's tui.json may have moved. Enter in the same read of input as the key that asked is not taken (a paste cannot both
544
+ * ask and press), and the question stands. A row the list no longer holds is not removed.
545
+ * -> { state, effect } for a key it answers, or null for one that goes on, with the question gone. */
546
+ function removal(state, event) {
547
+ const asked = state.switcher.removing, kept = next(state, { switcher: Object.freeze({ ...state.switcher, removing: null }) });
548
+ // The keys the question names, whatever the action table gives them (as a confirmation's are).
549
+ if (event.key === "escape") return { state: kept, effect: null };
550
+ if (event.key !== "enter") return null;
551
+ if (asked.read !== null && event.read === asked.read) return { state, effect: null };
552
+ const row = state.listed.rows.find((each) => each.path === asked.path);
553
+ return row ? { state: kept, effect: { remove: { path: row.path, name: row.name } } } : { state: kept, effect: null };
554
+ }
555
+
556
+ /** This computer's deployments list read (lib/main.mjs): its rows, or why the read failed, which
557
+ * keeps the rows of the last read that answered. */
558
+ function listedHeard(state, { rows, failure }) {
559
+ if (failure !== undefined) return { state: next(state, { listed: Object.freeze({ rows: state.listed.rows, failure: Object.freeze({ ...failure }) }) }), effect: null };
560
+ return { state: next(state, { listed: Object.freeze({ rows: Object.freeze(rows.map((row) => Object.freeze({ path: row.path, name: row.name, state: row.state }))), failure: null }) }), effect: null };
561
+ }
562
+
563
+ /** A Remove answered (lib/main.mjs): the switcher says how, and the list is read again. */
564
+ function removedHeard(state, { name, ok, reason = null }) {
565
+ const line = Object.freeze(ok ? { removed: name } : { notRemoved: name, message: reason?.message ?? "" });
566
+ return { state: next(state, { switcher: Object.freeze({ ...state.switcher, line }) }), effect: { list: true } };
567
+ }
568
+
510
569
  /** (state, event) -> { state, effect }.
511
570
  * An event is a key, `{ key, text?, page, extent, room, cols }` (`key` a key id, `text` the
512
571
  * grapheme a text key typed; `page` the rows of the list pane and `cols` its width, and `extent`
@@ -514,9 +573,10 @@ function switched(state, action, page) {
514
573
  * store keeps no size); a paste, `{ paste: <text> }`; or what the loop read:
515
574
  * `{ id, entry, number }` (a served deployment's entry), `{ roster: { remote, memory, notes, at } }`
516
575
  * (one outcome of the roster read), `{ collecting }`, `{ retiring: <Set of instanceIds> }` (this
517
- * run's retires in flight now), `{ offered: { offered, limited } }` (the
518
- * deployments of `~/Agents` not served), `{ admitted: <deployment>, at }` and `{ refused: <path> }`
519
- * (what a picked folder turned out to be).
576
+ * run's retires in flight now), `{ listed: { rows } | { failure } }` (this computer's deployments
577
+ * list read, or why it was not), `{ admitted: <deployment>, at }` and `{ refused: <path> }` (what a
578
+ * picked row turned out to be), `{ removed: { path, name, ok, reason } }` (a Remove's answer) and
579
+ * `{ notListed: <reason> }` (the deployment the run started in was not added to the list).
520
580
  * Opening an agent gives five more: `{ prepared: { id, error? } }` (the preflight of another
521
581
  * machine's agent ended: `error` is what the shared prepareRemoteTerm threw), `{ given: true }`
522
582
  * (the loop gave the preflight up itself: a suspend), `{ shown: { id } }` (the panel has the
@@ -526,14 +586,47 @@ function switched(state, action, page) {
526
586
  * `{ back: true, read, rest }` (the leader was typed in the terminal, in that read of input;
527
587
  * `rest`: more bytes came after it in the same read).
528
588
  * An effect is something only the loop can do: "quit", "suspend", "redraw", or an object with
529
- * any of `refresh: { live }` (read now), `offer: true` (list `~/Agents` again),
530
- * `admit: <path>` (ask whether a picked folder is a deployment), `close: <id>` (close the open
589
+ * any of `refresh: { live }` (read now), `list: true` (read this computer's deployments list
590
+ * again), `remove: { path, name }` (remove that row from it), `admit: <path>` (ask whether a picked
591
+ * row is a deployment), `close: <id>` (close the open
531
592
  * terminal; when an `open` comes with it, before that open), `open: <decision>` (open the agent's
532
593
  * terminal: the model's openDecision, with its target), `panel: <id>` (the preflight is over:
533
594
  * start the viewer it prepared in the panel) and `abandon: true` (give the preflight up); or null.
534
595
  * The line after an open stands until the next key that is bound to an action: a key bound to
535
596
  * nothing (a stray back key is no key at all) leaves it. */
536
597
  export function reduce(state, event, keymap = bindings(state.actions)) {
598
+ return askedStill(noticed(reduceStep(state, event, keymap)));
599
+ }
600
+
601
+ /** Whether the line under the sidebar's title stands now at every width (views/frame.mjs): in the
602
+ * Instances, Souls and Capabilities views, with the focus in the view's list and neither the
603
+ * palette nor the spawn prompt over it. The switcher draws none; a zoomed terminal has the whole
604
+ * screen; and under 80 columns the help, a confirmation, the palette, the spawn prompt, a detail
605
+ * with the focus and a terminal with the focus cover the whole screen, the sidebar too. */
606
+ function drawsOutcome(state) {
607
+ if (state.palette !== null || state.spawn !== null) return false;
608
+ if (state.view === "instances") return state.focus !== "detail" && state.terminal?.focus !== "terminal";
609
+ if (state.view === "souls") return state.souls.focus !== "detail";
610
+ if (state.view === "capabilities") return state.capabilities.focus !== "detail";
611
+ return false;
612
+ }
613
+ /** A notice waiting for a view that draws the line under the sidebar's title (`notice`), made the
614
+ * line there as soon as one is shown. */
615
+ function noticed(step) {
616
+ const s = step.state;
617
+ if (s.notice === null || !drawsOutcome(s)) return step;
618
+ return { ...step, state: next(s, { outcome: s.notice, notice: null }) };
619
+ }
620
+ /** A Remove asked stands only while its row is the switcher's selected choice: once the row is
621
+ * gone from the list or hidden by the filter, the selection is on another, and the question goes
622
+ * rather than ask about one row and remove another. */
623
+ function askedStill(step) {
624
+ const asked = step.state.switcher.removing;
625
+ if (asked === null || switcher(step.state).selected === `path\u0000${asked.path}`) return step;
626
+ return { ...step, state: next(step.state, { switcher: Object.freeze({ ...step.state.switcher, removing: null }) }) };
627
+ }
628
+
629
+ function reduceStep(state, event, keymap) {
537
630
  if (state.outcome !== null && typeof event.key === "string" && keymap.has(event.key)) state = next(state, { outcome: null });
538
631
  let step = reduced(state, event, keymap);
539
632
  // The tabs are the open workspace's: whatever opened another (or left it, gone), they all close,
@@ -570,7 +663,7 @@ const inGroup = (state, g) => state.tabs.filter((tab) => tab.group === g);
570
663
  /** Group `g`'s shown tab's id: the focused group's is the terminal's, the other's `aside`. */
571
664
  const shownOf = (state, g) => (g === state.group ? state.terminal?.id ?? null : state.aside);
572
665
  /** The cap's line: every tab is taken, and how to free one (the leader's close). */
573
- const fullLine = (state) => Object.freeze({ said: TAB_WORDS.full(TAB_LIMIT, state.detachKey), under: Object.freeze([]) });
666
+ const fullLine = (state) => Object.freeze({ said: TAB_WORDS.full(TAB_LIMIT, backKeyLabel(state.detachKey)), under: Object.freeze([]) });
574
667
 
575
668
  /** A new tab for an open decision (the model's openDecision), starting, in the focused group:
576
669
  * placed after its shown one (last, with none shown: an empty group's first) and shown, with the
@@ -923,25 +1016,55 @@ const both = (a, b) => (a === null ? b : b === null ? a : typeof b === "string"
923
1016
  * waits, with no timeout, for the key of LEADER's table that follows it IN A LATER READ, so a
924
1017
  * paste can never run a command: what comes in the leader's own read cancels it and is dropped.
925
1018
  * The key that follows is one key: the rest of its read is dropped too. A key not in the table
926
- * cancels the leader and is dropped. Answers the step, or `{ pass }`: the state the event goes on
927
- * in, when it is not the leader's. */
1019
+ * cancels the leader and is dropped. The leader again, in a later read, is the leader's key
1020
+ * itself (twice): see `twice`. Answers the step, or `{ pass }`: the state the event goes on in,
1021
+ * when it is not the leader's. */
928
1022
  function leading(state, event, keymap) {
929
1023
  const l = state.leader;
930
1024
  // The leader typed in a terminal: the rest of that read is never the agent's (lib/main.mjs), and
931
- // when there was a rest (`rest`), it cancelled the leader.
932
- if (event.back !== undefined) return { state: state.terminal?.focus === "terminal" ? next(state, { leader: leaderAt(event.read, event.rest !== true) }) : state, effect: null };
1025
+ // when there was a rest (`rest`), it cancelled the leader. While the leader waits from an earlier
1026
+ // read it is the leader twice (the loop reads keys while the leader waits, so it hands on no
1027
+ // `{ back }` then; one that comes is the leader's key all the same).
1028
+ if (event.back !== undefined) {
1029
+ if (state.terminal?.focus !== "terminal") return { state, effect: null };
1030
+ if (l !== null && l.waiting && !sameRead(l, event)) return twice(next(state, { leader: leaderAt(event.read, false) }));
1031
+ return { state: next(state, { leader: leaderAt(event.read, event.rest !== true) }), effect: null };
1032
+ }
1033
+ // A chord typed in a terminal (term/through.mjs): the leader then its key, at once.
1034
+ if (event.chord !== undefined) {
1035
+ if (state.keyboard === null || state.terminal?.focus !== "terminal") return { state, effect: null };
1036
+ return led(l === null ? state : next(state, { leader: null }), event.chord, event, keymap);
1037
+ }
933
1038
  if (typeof event.key !== "string" && !("paste" in event)) return { pass: state };
934
1039
  if (l !== null && sameRead(l, event)) return { state: l.waiting ? next(state, { leader: leaderAt(l.read, false) }) : state, effect: null };
935
1040
  if (l !== null && l.waiting) {
936
1041
  const after = next(state, { leader: leaderAt(event.read, false) });
937
- const does = typeof event.key !== "string" ? undefined : event.key === state.leaderKey ? "list" : LEADER_KEYS.get(event.key);
1042
+ if (event.key === state.leaderKey) return twice(after);
1043
+ const does = typeof event.key !== "string" ? undefined : LEADER_KEYS.get(event.key);
938
1044
  return does === undefined ? { state: after, effect: null } : led(after, does, event, keymap);
939
1045
  }
940
1046
  const plain = l === null ? state : next(state, { leader: null });
941
1047
  if (event.key === state.leaderKey) return { state: next(plain, { leader: leaderAt(event.read, true) }), effect: null };
1048
+ // THE CHORDS (docs/tui.md, "Chords"): while the terminal confirms the kitty keyboard protocol, a
1049
+ // chord does what the leader then its key does, from whatever was open. While the leader waits it
1050
+ // is a key not in the leader's table (above): it cancels the leader and is dropped.
1051
+ const chord = state.keyboard === null || typeof event.key !== "string" ? undefined : state.chords.get(event.key);
1052
+ if (chord !== undefined) return led(plain, chord, event, keymap);
942
1053
  return { pass: plain };
943
1054
  }
944
1055
 
1056
+ /** The leader twice (`state` is after it, its hint closed). While the open terminal has the focus,
1057
+ * which it keeps, the leader's own key goes to the agent: the effect `{ input: <bytes> }`, the
1058
+ * bytes a terminal sends for the back key (term/through.mjs backKeySequences, its first form:
1059
+ * ESC o for M-o, 0x1c for C-\\), which the loop types into the focused tab as it types what
1060
+ * passes through (lib/main.mjs), so an agent that reads that key still gets it. From any other
1061
+ * focus it does nothing else: the list is reached with the leader then Esc (LEADER). */
1062
+ function twice(state) {
1063
+ const inTerminal = state.terminal?.focus === "terminal" && state.view === "instances";
1064
+ // (A key outside the grammar has no bytes: tui.json refuses it, so it is never the leader.)
1065
+ return { state, effect: inTerminal && isBackKey(state.detachKey) ? { input: backKeySequences(state.detachKey)[0] } : null };
1066
+ }
1067
+
945
1068
  /** Whatever has the focus, settled, so the list has it: the palette closed, a confirmation closed
946
1069
  * (the loop told), the help and the views of this machine left, a filter field kept as Enter keeps
947
1070
  * it, the terminal and the detail left. -> { state, effect } */
@@ -966,7 +1089,7 @@ function toList(state) {
966
1089
  function toInstances(state) {
967
1090
  const settled = toList(state), s = settled.state;
968
1091
  if (s.view !== "switcher" || s.open === null) return settled;
969
- return { state: next(s, { view: "instances", back: "instances", switcher: Object.freeze({ ...s.switcher, line: null, refused: null }) }), effect: settled.effect };
1092
+ return { state: next(s, { view: "instances", back: "instances", switcher: Object.freeze({ ...s.switcher, line: null, refused: null, removing: null }) }), effect: settled.effect };
970
1093
  }
971
1094
 
972
1095
  /** What the leader's key does (LEADER's `does`), from wherever the focus was. From the terminal's
@@ -1137,6 +1260,8 @@ function reduced(state, event, keymap) {
1137
1260
  if (lead.pass === undefined) return lead;
1138
1261
  state = lead.pass;
1139
1262
  const stay = { state, effect: null };
1263
+ // The terminal confirmed the kitty keyboard protocol (lib/main.mjs): the chords are read from now on.
1264
+ if (event.keyboard !== undefined) return { state: next(state, { keyboard: event.keyboard }), effect: null };
1140
1265
  if (event.acted !== undefined) return acted(state, event.acted);
1141
1266
  if (event.prepared !== undefined) return prepared(state, event.prepared);
1142
1267
  if (event.given !== undefined) return state.opening?.phase === "preflight" ? { state: next(state, { opening: null }), effect: null } : stay;
@@ -1149,7 +1274,11 @@ function reduced(state, event, keymap) {
1149
1274
  if (event.collecting !== undefined) return { state: event.collecting === state.collecting ? state : next(state, { collecting: event.collecting === true }), effect: null };
1150
1275
  // The rows stay where they are: only what they read changes.
1151
1276
  if (event.retiring !== undefined) return { state: next(state, { retiring: new Set(event.retiring) }), effect: null };
1152
- if (event.offered !== undefined) return { state: next(state, { offered: Object.freeze({ offered: Object.freeze([...event.offered.offered]), limited: event.offered.limited === true }) }), effect: null };
1277
+ if (event.listed !== undefined) return listedHeard(state, event.listed);
1278
+ if (event.removed !== undefined) return removedHeard(state, event.removed);
1279
+ // Shown once, in the line under the sidebar's title, as the line after an open is.
1280
+ // Held while nothing may draw such a line (the switcher, the help): it is said once a view that does is shown.
1281
+ if (event.notListed !== undefined) return { state: next(state, { notice: Object.freeze({ said: LIST_WORDS.notAdded(event.notListed?.message ?? ""), under: Object.freeze([]) }) }), effect: null };
1153
1282
  if (event.admitted !== undefined) return { state: admitted(state, event), effect: { refresh: { live: true } } };
1154
1283
  if (event.refused !== undefined) return { state: next(state, { switcher: Object.freeze({ ...state.switcher, refused: event.refused }) }), effect: null };
1155
1284
  if (event.souls !== undefined) return soulsHeard(state, event.souls);
@@ -1171,6 +1300,11 @@ function reduced(state, event, keymap) {
1171
1300
  if (typeof event.key !== "string" && !given) return stay;
1172
1301
  const action = given ? event.action : keymap.get(event.key);
1173
1302
  if (field) return edited(state, field, event, action);
1303
+ if (state.switcher.removing !== null) {
1304
+ const answered = state.view === "switcher" && !given ? removal(state, event) : null;
1305
+ if (answered) return answered;
1306
+ state = next(state, { switcher: Object.freeze({ ...state.switcher, removing: null }) });
1307
+ }
1174
1308
  if (state.view === "act" && state.act !== null) return inAct(state, event, action);
1175
1309
  const page = Math.max(1, Number.isInteger(event.page) ? event.page : 1);
1176
1310
  // A pane that scrolls on its own (the help, the detail) moves from where it is DRAWN: the top
@@ -1183,11 +1317,11 @@ function reduced(state, event, keymap) {
1183
1317
 
1184
1318
  switch (action) {
1185
1319
  case "quit": case "suspend": case "redraw": return { state, effect: action };
1186
- // In the switcher the folders of ~/Agents are listed again too.
1320
+ // In the switcher this computer's deployments list is read again too.
1187
1321
  // In the Souls view it reads the souls again, and nothing else; in the Capabilities view, the capabilities.
1188
- case "refresh": return state.view === "souls" ? inSouls(state, action, event, page, scrolled) : state.view === "capabilities" ? inCapabilities(state, action, event, page, scrolled) : { state, effect: { refresh: { live: true }, ...((state.view === "help" ? state.back : state.view) === "switcher" ? { offer: true } : {}) } };
1322
+ case "refresh": return state.view === "souls" ? inSouls(state, action, event, page, scrolled) : state.view === "capabilities" ? inCapabilities(state, action, event, page, scrolled) : { state, effect: { refresh: { live: true }, ...((state.view === "help" ? state.back : state.view) === "switcher" ? { list: true } : {}) } };
1189
1323
  case "help": return { state: next(state, state.view === "help" ? { view: state.back } : { view: "help", back: state.view, helpTop: 0 }), effect: null };
1190
- case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { offer: true } };
1324
+ case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { list: true } };
1191
1325
  case "palette": return { state: paletteOpened(state, event, "list"), effect: null };
1192
1326
  // Souls and Capabilities are views of this machine, whatever workspace is open, or none.
1193
1327
  case "souls": return soulsShown(state);
@@ -1204,7 +1338,7 @@ function reduced(state, event, keymap) {
1204
1338
  if (action === "instances") return state.open === null ? stay : { state: next(state, { view: "instances", back: "instances" }), effect: null };
1205
1339
  return MOVES.includes(action) ? { state: next(state, { helpTop: scrolled(state.helpTop) }), effect: null } : stay;
1206
1340
  }
1207
- if (state.view === "switcher") return switched(state, action, page);
1341
+ if (state.view === "switcher") return switched(state, action, page, event);
1208
1342
 
1209
1343
  if (action === "close") {
1210
1344
  // In this order: an open under way (another machine is asked first), a kept filter, the detail.