@awebai/oats 0.64.0 → 0.65.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 (36) hide show
  1. package/bin/oats.mjs +101 -4
  2. package/docs/desktop-cli-api.md +84 -2
  3. package/docs/desktop.md +14 -5
  4. package/docs/implementation.md +17 -3
  5. package/docs/release-notes/v0.65.0.md +187 -0
  6. package/docs/tui.md +416 -238
  7. package/docs/upgrading.md +1 -1
  8. package/docs/workspaces.md +124 -0
  9. package/lib/core.mjs +14 -4
  10. package/lib/deployments.mjs +325 -0
  11. package/lib/resolved-deployment.mjs +37 -0
  12. package/lib/workspace.mjs +2 -0
  13. package/package.json +1 -1
  14. package/packages/client/cli-locator.mjs +2 -2
  15. package/packages/client/deployment-label.mjs +2 -2
  16. package/packages/client/deployment-list-cli.mjs +98 -0
  17. package/packages/client/deployment-list.mjs +91 -0
  18. package/packages/client/keymap.mjs +106 -0
  19. package/packages/client/own-codes.mjs +2 -0
  20. package/packages/client/panel-views.mjs +1 -1
  21. package/packages/client/workspace-admission.mjs +2 -1
  22. package/packages/tui/README.md +4 -4
  23. package/packages/tui/lib/actions.mjs +29 -5
  24. package/packages/tui/lib/client.mjs +3 -1
  25. package/packages/tui/lib/config.mjs +21 -14
  26. package/packages/tui/lib/main.mjs +108 -31
  27. package/packages/tui/lib/model.mjs +71 -41
  28. package/packages/tui/lib/read.mjs +15 -45
  29. package/packages/tui/lib/store.mjs +158 -39
  30. package/packages/tui/lib/term/through.mjs +40 -18
  31. package/packages/tui/lib/views/act.mjs +17 -13
  32. package/packages/tui/lib/views/frame.mjs +418 -421
  33. package/packages/tui/lib/views/help.mjs +41 -19
  34. package/packages/tui/lib/views/instances.mjs +38 -9
  35. package/packages/tui/lib/views/switcher.mjs +65 -21
  36. package/skills/oats-getting-started/SKILL.md +6 -4
@@ -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 } 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,9 +73,13 @@ 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`).
77
84
  * `palette`: the palette while it is open (see `paletteOpened`), or null. `recent`: the ids of
78
85
  * the instances opened in this run, the latest first.
@@ -93,7 +100,7 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
93
100
  * agentsRoot, agent, reads, words }`, until its row is opened or two reads did not show it;
94
101
  * `previews` the number of the last preview read asked in the run, so that an answer to a prompt
95
102
  * 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 }) {
103
+ export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, platform, detachKey = defaultDetachKey(platform) }) {
97
104
  return Object.freeze({
98
105
  view: deployment === null ? "switcher" : "instances", back: deployment === null ? "switcher" : "instances",
99
106
  ctxs: Object.freeze(deployment === null ? [] : [deployment]), open: deployment,
@@ -101,15 +108,24 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
101
108
  remote: Object.freeze({ remoteGroups: Object.freeze([]), rosterAnswered: false, rosterFailure: null }), rosterAt: null,
102
109
  memory: new Map(), notes: new Map(), collecting: false, cli, home,
103
110
  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 }),
111
+ switcher: NO_SWITCHER,
112
+ listed: NO_LIST,
106
113
  helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
107
114
  leaderKey: backKeyId(detachKey), leader: null, palette: null, recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
108
115
  spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
116
+ notice: null,
109
117
  });
110
118
  }
111
119
 
112
120
  const next = (state, changes) => Object.freeze({ ...state, ...changes });
121
+
122
+ /** The switcher's own: the filter, the selection and the scroll; `line`, what it says above its rows
123
+ * of what happened (lib/model.mjs SWITCHER_LINES: "gone", or the answer of a Remove); `refused`,
124
+ * the path of a picked row that turned out not to be a deployment; `removing`, the Remove asked
125
+ * for, `{ path, read }` (the row and the read of input that asked), until it is answered or kept. */
126
+ const NO_SWITCHER = Object.freeze({ editing: false, query: "", selected: null, top: 0, loose: false, line: null, refused: null, removing: null });
127
+ /** This computer's deployments list before its first read. */
128
+ const NO_LIST = Object.freeze({ rows: Object.freeze([]), failure: null });
113
129
  const indexOf = (r, id) => (id === null ? -1 : r.index.get(id) ?? -1);
114
130
  /** Whether an item of the list is an instance: the only kind the selection stands on. */
115
131
  const isRow = (item) => item?.id !== undefined;
@@ -160,7 +176,7 @@ function rehomed(before, state) {
160
176
  }
161
177
 
162
178
  /** 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 }) });
179
+ 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
180
 
165
181
  /** After what the reader gave changed: when no view holds what was open any more (a machine that
166
182
  * is no longer listed), the switcher is shown and says so, and nothing is open. Else the
@@ -179,7 +195,7 @@ function settled(state, taken) {
179
195
  const places = new Map(taken.places); places.delete(taken.open);
180
196
  // A confirmation open over that view is closed with it: what it sent goes on.
181
197
  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 } };
198
+ 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
199
  }
184
200
  const before = roster(state);
185
201
  const unknown = new Set([...taken.unread.values()].flatMap((ids) => [...ids]));
@@ -219,7 +235,7 @@ function heard(state, { remote, memory, notes, at }) {
219
235
  /** Open the view of deployment `id`: the place the view left behind is kept, and found again
220
236
  * on the way back (the row, where the list and the detail were scrolled). A filter is not kept. */
221
237
  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 }) });
238
+ const shown = next(state, { view: "instances", back: "instances", switcher: Object.freeze({ ...state.switcher, editing: false, query: "", line: null, refused: null, removing: null }) });
223
239
  if (id === state.open) return shown;
224
240
  const places = new Map(state.places);
225
241
  if (state.open !== null) places.set(state.open, Object.freeze({ selected: state.selected, top: state.top, detailTop: state.detailTop }));
@@ -227,8 +243,9 @@ function opened(state, id) {
227
243
  return rehomed({ rows: [] }, next(shown, { open: id, places, focus: "list", filter: NO_FILTER, loose: false, ...place }));
228
244
  }
229
245
 
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. */
246
+ /** A picked row of this computer's deployments list that is a deployment (lib/read.mjs made it
247
+ * canonical and asked the shared rule): it is served from now on, pending until its first read,
248
+ * and opened. */
232
249
  function admitted(state, { admitted: id, at }) {
233
250
  if (state.ctxs.includes(id)) return opened(state, id);
234
251
  const joined = next(state, { ctxs: Object.freeze([...state.ctxs, id]), entries: new Map(state.entries).set(id, pendingEntry(null, at)) });
@@ -468,8 +485,10 @@ function moved(action, from, count, page) {
468
485
  }
469
486
 
470
487
  /** 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) {
488
+ * the open key opens the view of a workspace here, and asks the loop to admit a row of the list
489
+ * that is a deployment (a stale one does not open: its row says why). The remove key asks whether
490
+ * to remove the selected row of the list from it (see `removal`). */
491
+ function switched(state, action, page, event) {
473
492
  const stay = { state, effect: null };
474
493
  const s = switcher(state), sw = state.switcher;
475
494
  const put = (changes) => next(state, { switcher: Object.freeze({ ...sw, ...changes }) });
@@ -481,13 +500,14 @@ function switched(state, action, page) {
481
500
  return state.open === null ? stay : { state: next(put({ line: null, refused: null }), { view: "instances", back: "instances" }), effect: null };
482
501
  case "instances": return state.open === null ? stay : { state: next(put({ line: null, refused: null }), { view: "instances", back: "instances" }), effect: null };
483
502
  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));
503
+ // The rows of the pane the choices have: the lines above them take theirs, and the filter
504
+ // field one while it is shown (lib/model.mjs switcherHeight).
505
+ const count = s.items.length, height = switcherHeight(state, page, event.area);
486
506
  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
507
  const from = Math.max(0, s.keys.indexOf(s.selected));
488
508
  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
509
  // 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.
510
+ // scroll instead, so what stands above the first choice or under the last one is read.
491
511
  if (key === null || key === s.selected) {
492
512
  const top = windowOf({ top: moved(action, drawn, count, height), count, height }).top;
493
513
  return top === drawn ? stay : { state: put({ top, loose: true }), effect: null };
@@ -500,13 +520,49 @@ function switched(state, action, page) {
500
520
  case "open": {
501
521
  const item = s.items.find((each) => each.key !== undefined && each.key === s.selected);
502
522
  if (!item) return stay;
503
- if (item.path !== undefined) return { state: put({ refused: null }), effect: { admit: item.path } };
523
+ if (item.path !== undefined) return item.state === "ok" ? { state: put({ refused: null }), effect: { admit: item.path } } : stay;
504
524
  return item.primary === null ? stay : { state: opened(state, item.primary), effect: { refresh: { live: true } } };
505
525
  }
526
+ case "remove": {
527
+ const item = s.items.find((each) => each.key !== undefined && each.key === s.selected);
528
+ // The row asked about is the selected one from then on, whatever the list or the roster bring
529
+ // meanwhile; a question whose row is no longer the one marked goes (see `askedStill`).
530
+ 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 };
531
+ }
506
532
  default: return stay;
507
533
  }
508
534
  }
509
535
 
536
+ /** A key while the switcher asks whether to remove a row of this computer's deployments list
537
+ * (docs/tui.md, "The switcher"). Enter removes it: the loop runs `oats deployments remove`, and
538
+ * nothing on disk is touched. Esc keeps it, and so does every other key, which then does what it
539
+ * does. Enter and Esc are the keys themselves, as the question says them, not the actions the
540
+ * 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
541
+ * ask and press), and the question stands. A row the list no longer holds is not removed.
542
+ * -> { state, effect } for a key it answers, or null for one that goes on, with the question gone. */
543
+ function removal(state, event) {
544
+ const asked = state.switcher.removing, kept = next(state, { switcher: Object.freeze({ ...state.switcher, removing: null }) });
545
+ // The keys the question names, whatever the action table gives them (as a confirmation's are).
546
+ if (event.key === "escape") return { state: kept, effect: null };
547
+ if (event.key !== "enter") return null;
548
+ if (asked.read !== null && event.read === asked.read) return { state, effect: null };
549
+ const row = state.listed.rows.find((each) => each.path === asked.path);
550
+ return row ? { state: kept, effect: { remove: { path: row.path, name: row.name } } } : { state: kept, effect: null };
551
+ }
552
+
553
+ /** This computer's deployments list read (lib/main.mjs): its rows, or why the read failed, which
554
+ * keeps the rows of the last read that answered. */
555
+ function listedHeard(state, { rows, failure }) {
556
+ if (failure !== undefined) return { state: next(state, { listed: Object.freeze({ rows: state.listed.rows, failure: Object.freeze({ ...failure }) }) }), effect: null };
557
+ 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 };
558
+ }
559
+
560
+ /** A Remove answered (lib/main.mjs): the switcher says how, and the list is read again. */
561
+ function removedHeard(state, { name, ok, reason = null }) {
562
+ const line = Object.freeze(ok ? { removed: name } : { notRemoved: name, message: reason?.message ?? "" });
563
+ return { state: next(state, { switcher: Object.freeze({ ...state.switcher, line }) }), effect: { list: true } };
564
+ }
565
+
510
566
  /** (state, event) -> { state, effect }.
511
567
  * An event is a key, `{ key, text?, page, extent, room, cols }` (`key` a key id, `text` the
512
568
  * grapheme a text key typed; `page` the rows of the list pane and `cols` its width, and `extent`
@@ -514,9 +570,10 @@ function switched(state, action, page) {
514
570
  * store keeps no size); a paste, `{ paste: <text> }`; or what the loop read:
515
571
  * `{ id, entry, number }` (a served deployment's entry), `{ roster: { remote, memory, notes, at } }`
516
572
  * (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).
573
+ * run's retires in flight now), `{ listed: { rows } | { failure } }` (this computer's deployments
574
+ * list read, or why it was not), `{ admitted: <deployment>, at }` and `{ refused: <path> }` (what a
575
+ * picked row turned out to be), `{ removed: { path, name, ok, reason } }` (a Remove's answer) and
576
+ * `{ notListed: <reason> }` (the deployment the run started in was not added to the list).
520
577
  * Opening an agent gives five more: `{ prepared: { id, error? } }` (the preflight of another
521
578
  * machine's agent ended: `error` is what the shared prepareRemoteTerm threw), `{ given: true }`
522
579
  * (the loop gave the preflight up itself: a suspend), `{ shown: { id } }` (the panel has the
@@ -526,14 +583,47 @@ function switched(state, action, page) {
526
583
  * `{ back: true, read, rest }` (the leader was typed in the terminal, in that read of input;
527
584
  * `rest`: more bytes came after it in the same read).
528
585
  * 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
586
+ * any of `refresh: { live }` (read now), `list: true` (read this computer's deployments list
587
+ * again), `remove: { path, name }` (remove that row from it), `admit: <path>` (ask whether a picked
588
+ * row is a deployment), `close: <id>` (close the open
531
589
  * terminal; when an `open` comes with it, before that open), `open: <decision>` (open the agent's
532
590
  * terminal: the model's openDecision, with its target), `panel: <id>` (the preflight is over:
533
591
  * start the viewer it prepared in the panel) and `abandon: true` (give the preflight up); or null.
534
592
  * The line after an open stands until the next key that is bound to an action: a key bound to
535
593
  * nothing (a stray back key is no key at all) leaves it. */
536
594
  export function reduce(state, event, keymap = bindings(state.actions)) {
595
+ return askedStill(noticed(reduceStep(state, event, keymap)));
596
+ }
597
+
598
+ /** Whether the line under the sidebar's title stands now at every width (views/frame.mjs): in the
599
+ * Instances, Souls and Capabilities views, with the focus in the view's list and neither the
600
+ * palette nor the spawn prompt over it. The switcher draws none; a zoomed terminal has the whole
601
+ * screen; and under 80 columns the help, a confirmation, the palette, the spawn prompt, a detail
602
+ * with the focus and a terminal with the focus cover the whole screen, the sidebar too. */
603
+ function drawsOutcome(state) {
604
+ if (state.palette !== null || state.spawn !== null) return false;
605
+ if (state.view === "instances") return state.focus !== "detail" && state.terminal?.focus !== "terminal";
606
+ if (state.view === "souls") return state.souls.focus !== "detail";
607
+ if (state.view === "capabilities") return state.capabilities.focus !== "detail";
608
+ return false;
609
+ }
610
+ /** A notice waiting for a view that draws the line under the sidebar's title (`notice`), made the
611
+ * line there as soon as one is shown. */
612
+ function noticed(step) {
613
+ const s = step.state;
614
+ if (s.notice === null || !drawsOutcome(s)) return step;
615
+ return { ...step, state: next(s, { outcome: s.notice, notice: null }) };
616
+ }
617
+ /** A Remove asked stands only while its row is the switcher's selected choice: once the row is
618
+ * gone from the list or hidden by the filter, the selection is on another, and the question goes
619
+ * rather than ask about one row and remove another. */
620
+ function askedStill(step) {
621
+ const asked = step.state.switcher.removing;
622
+ if (asked === null || switcher(step.state).selected === `path\u0000${asked.path}`) return step;
623
+ return { ...step, state: next(step.state, { switcher: Object.freeze({ ...step.state.switcher, removing: null }) }) };
624
+ }
625
+
626
+ function reduceStep(state, event, keymap) {
537
627
  if (state.outcome !== null && typeof event.key === "string" && keymap.has(event.key)) state = next(state, { outcome: null });
538
628
  let step = reduced(state, event, keymap);
539
629
  // The tabs are the open workspace's: whatever opened another (or left it, gone), they all close,
@@ -570,7 +660,7 @@ const inGroup = (state, g) => state.tabs.filter((tab) => tab.group === g);
570
660
  /** Group `g`'s shown tab's id: the focused group's is the terminal's, the other's `aside`. */
571
661
  const shownOf = (state, g) => (g === state.group ? state.terminal?.id ?? null : state.aside);
572
662
  /** 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([]) });
663
+ const fullLine = (state) => Object.freeze({ said: TAB_WORDS.full(TAB_LIMIT, backKeyLabel(state.detachKey)), under: Object.freeze([]) });
574
664
 
575
665
  /** A new tab for an open decision (the model's openDecision), starting, in the focused group:
576
666
  * placed after its shown one (last, with none shown: an empty group's first) and shown, with the
@@ -923,18 +1013,26 @@ const both = (a, b) => (a === null ? b : b === null ? a : typeof b === "string"
923
1013
  * waits, with no timeout, for the key of LEADER's table that follows it IN A LATER READ, so a
924
1014
  * paste can never run a command: what comes in the leader's own read cancels it and is dropped.
925
1015
  * 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. */
1016
+ * cancels the leader and is dropped. The leader again, in a later read, is the leader's key
1017
+ * itself (twice): see `twice`. Answers the step, or `{ pass }`: the state the event goes on in,
1018
+ * when it is not the leader's. */
928
1019
  function leading(state, event, keymap) {
929
1020
  const l = state.leader;
930
1021
  // 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 };
1022
+ // when there was a rest (`rest`), it cancelled the leader. While the leader waits from an earlier
1023
+ // read it is the leader twice (the loop reads keys while the leader waits, so it hands on no
1024
+ // `{ back }` then; one that comes is the leader's key all the same).
1025
+ if (event.back !== undefined) {
1026
+ if (state.terminal?.focus !== "terminal") return { state, effect: null };
1027
+ if (l !== null && l.waiting && !sameRead(l, event)) return twice(next(state, { leader: leaderAt(event.read, false) }));
1028
+ return { state: next(state, { leader: leaderAt(event.read, event.rest !== true) }), effect: null };
1029
+ }
933
1030
  if (typeof event.key !== "string" && !("paste" in event)) return { pass: state };
934
1031
  if (l !== null && sameRead(l, event)) return { state: l.waiting ? next(state, { leader: leaderAt(l.read, false) }) : state, effect: null };
935
1032
  if (l !== null && l.waiting) {
936
1033
  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);
1034
+ if (event.key === state.leaderKey) return twice(after);
1035
+ const does = typeof event.key !== "string" ? undefined : LEADER_KEYS.get(event.key);
938
1036
  return does === undefined ? { state: after, effect: null } : led(after, does, event, keymap);
939
1037
  }
940
1038
  const plain = l === null ? state : next(state, { leader: null });
@@ -942,6 +1040,18 @@ function leading(state, event, keymap) {
942
1040
  return { pass: plain };
943
1041
  }
944
1042
 
1043
+ /** The leader twice (`state` is after it, its hint closed). While the open terminal has the focus,
1044
+ * which it keeps, the leader's own key goes to the agent: the effect `{ input: <bytes> }`, the
1045
+ * bytes a terminal sends for the back key (term/through.mjs backKeySequences, its first form:
1046
+ * ESC o for M-o, 0x1c for C-\\), which the loop types into the focused tab as it types what
1047
+ * passes through (lib/main.mjs), so an agent that reads that key still gets it. From any other
1048
+ * focus it does nothing else: the list is reached with the leader then Esc (LEADER). */
1049
+ function twice(state) {
1050
+ const inTerminal = state.terminal?.focus === "terminal" && state.view === "instances";
1051
+ // (A key outside the grammar has no bytes: tui.json refuses it, so it is never the leader.)
1052
+ return { state, effect: inTerminal && isBackKey(state.detachKey) ? { input: backKeySequences(state.detachKey)[0] } : null };
1053
+ }
1054
+
945
1055
  /** Whatever has the focus, settled, so the list has it: the palette closed, a confirmation closed
946
1056
  * (the loop told), the help and the views of this machine left, a filter field kept as Enter keeps
947
1057
  * it, the terminal and the detail left. -> { state, effect } */
@@ -966,7 +1076,7 @@ function toList(state) {
966
1076
  function toInstances(state) {
967
1077
  const settled = toList(state), s = settled.state;
968
1078
  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 };
1079
+ return { state: next(s, { view: "instances", back: "instances", switcher: Object.freeze({ ...s.switcher, line: null, refused: null, removing: null }) }), effect: settled.effect };
970
1080
  }
971
1081
 
972
1082
  /** What the leader's key does (LEADER's `does`), from wherever the focus was. From the terminal's
@@ -1149,7 +1259,11 @@ function reduced(state, event, keymap) {
1149
1259
  if (event.collecting !== undefined) return { state: event.collecting === state.collecting ? state : next(state, { collecting: event.collecting === true }), effect: null };
1150
1260
  // The rows stay where they are: only what they read changes.
1151
1261
  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 };
1262
+ if (event.listed !== undefined) return listedHeard(state, event.listed);
1263
+ if (event.removed !== undefined) return removedHeard(state, event.removed);
1264
+ // Shown once, in the line under the sidebar's title, as the line after an open is.
1265
+ // Held while nothing may draw such a line (the switcher, the help): it is said once a view that does is shown.
1266
+ if (event.notListed !== undefined) return { state: next(state, { notice: Object.freeze({ said: LIST_WORDS.notAdded(event.notListed?.message ?? ""), under: Object.freeze([]) }) }), effect: null };
1153
1267
  if (event.admitted !== undefined) return { state: admitted(state, event), effect: { refresh: { live: true } } };
1154
1268
  if (event.refused !== undefined) return { state: next(state, { switcher: Object.freeze({ ...state.switcher, refused: event.refused }) }), effect: null };
1155
1269
  if (event.souls !== undefined) return soulsHeard(state, event.souls);
@@ -1171,6 +1285,11 @@ function reduced(state, event, keymap) {
1171
1285
  if (typeof event.key !== "string" && !given) return stay;
1172
1286
  const action = given ? event.action : keymap.get(event.key);
1173
1287
  if (field) return edited(state, field, event, action);
1288
+ if (state.switcher.removing !== null) {
1289
+ const answered = state.view === "switcher" && !given ? removal(state, event) : null;
1290
+ if (answered) return answered;
1291
+ state = next(state, { switcher: Object.freeze({ ...state.switcher, removing: null }) });
1292
+ }
1174
1293
  if (state.view === "act" && state.act !== null) return inAct(state, event, action);
1175
1294
  const page = Math.max(1, Number.isInteger(event.page) ? event.page : 1);
1176
1295
  // A pane that scrolls on its own (the help, the detail) moves from where it is DRAWN: the top
@@ -1183,11 +1302,11 @@ function reduced(state, event, keymap) {
1183
1302
 
1184
1303
  switch (action) {
1185
1304
  case "quit": case "suspend": case "redraw": return { state, effect: action };
1186
- // In the switcher the folders of ~/Agents are listed again too.
1305
+ // In the switcher this computer's deployments list is read again too.
1187
1306
  // 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 } : {}) } };
1307
+ 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
1308
  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 } };
1309
+ case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { list: true } };
1191
1310
  case "palette": return { state: paletteOpened(state, event, "list"), effect: null };
1192
1311
  // Souls and Capabilities are views of this machine, whatever workspace is open, or none.
1193
1312
  case "souls": return soulsShown(state);
@@ -1204,7 +1323,7 @@ function reduced(state, event, keymap) {
1204
1323
  if (action === "instances") return state.open === null ? stay : { state: next(state, { view: "instances", back: "instances" }), effect: null };
1205
1324
  return MOVES.includes(action) ? { state: next(state, { helpTop: scrolled(state.helpTop) }), effect: null } : stay;
1206
1325
  }
1207
- if (state.view === "switcher") return switched(state, action, page);
1326
+ if (state.view === "switcher") return switched(state, action, page, event);
1208
1327
 
1209
1328
  if (action === "close") {
1210
1329
  // In this order: an open under way (another machine is asked first), a kept filter, the detail.
@@ -5,11 +5,18 @@
5
5
  // a paste, so a back key inside it is pasted, not taken). Pure: no IO; the clock is injected.
6
6
  //
7
7
  // The back key is tui.json's `open.detachKey`. Its grammar is THE TUI'S OWN: the keys it can take
8
- // back from a terminal and name in the footer. It began as the kernel's `--detach-key` grammar
8
+ // back from a terminal and name in the cheat sheet. It began as the kernel's `--detach-key` grammar
9
9
  // (lib/session-viewer.mjs) and keeps its set and its spelling, so a tui.json written for PR 4 means
10
10
  // the same key; it is not tied to the kernel's, which never sees this key any more.
11
11
  import { ESC_TIMEOUT_MS, PASTE_LIMIT, PASTE_PAUSE_MS, createKeyParser, keyId } from "./keys.mjs";
12
12
 
13
+ /** How long bytes held only as a beginning of the back key wait for the rest of it, in
14
+ * milliseconds: the back key counts only as ONE keypress (a terminal writes a key's bytes at
15
+ * once; a split read of them comes within this), so Esc and then `o` typed as two keys reach the
16
+ * agent as they were typed, and never as M-o. Bytes that may begin a paste's start marker wait
17
+ * the key parser's Esc timeout (ESC_TIMEOUT_MS) instead, as before. */
18
+ export const BACK_KEY_SPLIT_MS = 10;
19
+
13
20
  /** The keys that can be the back key: Control with a letter other than h, i and m (Backspace on
14
21
  * some terminals, Tab, Enter), or one of \ ] ^ _; Meta with a lowercase letter or a digit; or F1
15
22
  * to F12 with at most one of C-, M-, S-. Outside it, among others: Escape, and the ESC + C1
@@ -91,15 +98,20 @@ const decoder = () => new TextDecoder("utf-8", { fatal: false });
91
98
  * unwrapped) and, at most once per feed and last, `{ back: true, rest: <bytes> }` (the back key:
92
99
  * what came after it in the same read is no longer the agent's, and `rest` hands it on).
93
100
  * A read is never held back from the agent but for a beginning of the back key's own bytes, or of
94
- * a paste's start marker from its third byte: those wait for the next read, or until `expire()`
95
- * past `timeoutAt()` (the key parser's Esc timeout) hands them on as input. A paste is held until
101
+ * a paste's start marker from its third byte: those wait for the next read, or until `timeoutAt()`
102
+ * (BACK_KEY_SPLIT_MS for the back key's alone, the key parser's Esc timeout when they may begin a
103
+ * paste) hands them on as input, through `expire()` or the first read that comes later, which
104
+ * then never completes the back key with them. A paste is held until
96
105
  * its end marker; one that reaches PASTE_LIMIT is dropped whole, and one whose end has not come
97
106
  * when a read arrives PASTE_PAUSE_MS after the one before is given to the agent as what it held,
98
107
  * and that read is scanned anew, as the key parser abandons a stalled paste. */
99
108
  export function createThrough({ sequences, now }) {
100
109
  if (typeof now !== "function") throw new TypeError("createThrough needs an injected clock: { now: () => milliseconds }");
101
110
  const keys = sequences.map((seq) => Uint8Array.from(seq));
102
- let held = new Uint8Array(0), heldAt = 0;
111
+ /** The bytes held for the next read, since when, and how long they may wait: BACK_KEY_SPLIT_MS
112
+ * when they are held only as a beginning of the back key, ESC_TIMEOUT_MS when they may begin a
113
+ * paste's start marker (or its rest, see PASTE_HELD_FROM). */
114
+ let held = new Uint8Array(0), heldAt = 0, heldFor = ESC_TIMEOUT_MS;
103
115
  /** The paste being read: its content so far (null when none; only the tail that may begin the
104
116
  * end marker once it went past the limit), and whether it did. */
105
117
  let paste = null, over = false, lastFeed = 0;
@@ -172,21 +184,37 @@ export function createThrough({ sequences, now }) {
172
184
  out.push({ back: true, rest: data.subarray(i + key.length) });
173
185
  return;
174
186
  }
175
- // The read ends on what may be the beginning of the back key or of a paste: held.
176
- if (keys.some((seq) => begins(data, i, seq)) || (data.length - i >= PASTE_HELD_FROM && begins(data, i, PASTE_START))) {
187
+ // The read ends on what may be the beginning of the back key or of a paste: held, as long
188
+ // as the one it may begin allows (a paste's, when it may begin both).
189
+ const pasting = data.length - i >= PASTE_HELD_FROM && begins(data, i, PASTE_START);
190
+ if (pasting || keys.some((seq) => begins(data, i, seq))) {
177
191
  if (i > 0) out.push({ input: data.subarray(0, i) });
178
192
  held = Uint8Array.from(data.subarray(i));
179
193
  heldAt = now();
194
+ heldFor = pasting ? ESC_TIMEOUT_MS : BACK_KEY_SPLIT_MS;
180
195
  return;
181
196
  }
182
197
  }
183
198
  if (data.length) out.push({ input: data });
184
199
  }
185
200
 
201
+ /** The held bytes, once they waited as long as they may at `t`: handed on as input, as one event
202
+ * of their own (and noted, so a paste they begin is still raw), or nothing. */
203
+ function lapse(t) {
204
+ if (!held.length || t < heldAt + heldFor) return [];
205
+ const out = [{ input: held }];
206
+ held = new Uint8Array(0);
207
+ forwarded = handedOn(out);
208
+ return out;
209
+ }
210
+
186
211
  return {
187
212
  feed(bytes) {
188
213
  if (!(bytes instanceof Uint8Array)) throw new TypeError("feed expects bytes (a Uint8Array)");
189
- const out = [], t = now();
214
+ const t = now();
215
+ // Held bytes whose wait is over are the agent's before this read is looked at, whether or not
216
+ // expire() ran: a read that comes later never completes the back key with them (one keypress).
217
+ const late = lapse(t), out = [];
190
218
  let data = bytes;
191
219
  const soon = t - lastFeed < PASTE_PAUSE_MS;
192
220
  if (paste !== null && !soon) endPaste(out, paste);
@@ -195,7 +223,7 @@ export function createThrough({ sequences, now }) {
195
223
  lastFeed = t;
196
224
  if (paste !== null) {
197
225
  data = inPaste(out, data);
198
- if (paste !== null) return out;
226
+ if (paste !== null) return out; // nothing was held: a paste and held bytes never meet
199
227
  }
200
228
  if (held.length) { data = join(held, data); held = new Uint8Array(0); }
201
229
  // The rest of a start marker whose first bytes the last read handed on: the paste is raw.
@@ -203,22 +231,16 @@ export function createThrough({ sequences, now }) {
203
231
  if (raw === null && forwarded > 0 && soon) {
204
232
  const rest = PASTE_START.subarray(forwarded);
205
233
  if (at(data, 0, rest)) raw = { tail: new Uint8Array(0) };
206
- else if (begins(data, 0, rest)) { held = Uint8Array.from(data); heldAt = t; return out; }
234
+ else if (begins(data, 0, rest)) { held = Uint8Array.from(data); heldAt = t; heldFor = ESC_TIMEOUT_MS; return [...late, ...out]; }
207
235
  }
208
236
  forwarded = 0;
209
237
  if (raw !== null) data = inRaw(out, data);
210
238
  if (raw === null && data.length) scan(out, data);
211
239
  forwarded = handedOn(out);
212
240
  // Events are handed out as copies: the caller may keep them past the next read.
213
- return out.map((event) => (event.input ? { input: Uint8Array.from(event.input) } : event.rest ? { back: true, rest: Uint8Array.from(event.rest) } : event));
214
- },
215
- expire() {
216
- if (!held.length || now() < heldAt + ESC_TIMEOUT_MS) return [];
217
- const out = [{ input: held }];
218
- held = new Uint8Array(0);
219
- forwarded = handedOn(out);
220
- return out;
241
+ return [...late, ...out].map((event) => (event.input ? { input: Uint8Array.from(event.input) } : event.rest ? { back: true, rest: Uint8Array.from(event.rest) } : event));
221
242
  },
222
- timeoutAt() { return held.length ? heldAt + ESC_TIMEOUT_MS : null; },
243
+ expire() { return lapse(now()); },
244
+ timeoutAt() { return held.length ? heldAt + heldFor : null; },
223
245
  };
224
246
  }
@@ -1,7 +1,7 @@
1
1
  // The act view: one confirmation of a stop, a retire, a start or a restart, over the list of
2
2
  // instances (as the help is). Pure: no IO, no clock, no escape byte. (model, area) -> rows.
3
3
  // The content (lib/model.mjs actView) scrolls when it is taller than the area; the buttons keep
4
- // the area's last row. The TUI's own words are lit(); every shared sentence, the kernel's lines,
4
+ // the area's last rows. The TUI's own words are lit(); every shared sentence, the kernel's lines,
5
5
  // a name and a path go through shown(). Meaning never rests on colour alone: the button with the
6
6
  // focus is drawn between `>` and `<` as well as in reverse.
7
7
  import { EMPTY, lit, shown, shownLines, textOf } from "../term/text.mjs";
@@ -55,31 +55,35 @@ export function actRows(m, cols) {
55
55
  return rows.map((spans) => spans.map((span) => ({ ...span, col: span.col + LEFT })));
56
56
  }
57
57
 
58
- /** The buttons, one per offer of the confirmation and in its order, on one row; the one with the
59
- * focus between `>` and `<`. */
60
- function buttonRow(buttons, cols) {
61
- const spans = [];
62
- let col = LEFT;
58
+ /** The buttons, one per offer of the confirmation and in its order, the one with the focus between
59
+ * `>` and `<`: on one row when they fit, else on as many as they need, a button never split and
60
+ * never left out (the area beside the sidebar can be narrow, and every offer, the one with the
61
+ * focus among them, must be seen). A label wider than a row is cut there. */
62
+ function buttonRows(buttons, cols) {
63
+ const rows = [];
64
+ let row = [], col = LEFT;
63
65
  for (const button of buttons) {
64
66
  const label = button.focused ? `> ${button.label} <` : `[ ${button.label} ]`;
65
- if (col + label.length > cols) break;
66
- spans.push({ col, text: lit(label), width: label.length, ...(button.focused ? { style: FOCUSED } : {}) });
67
+ if (row.length && col + label.length > cols) { rows.push(row); row = []; col = LEFT; }
68
+ row.push({ col, text: lit(label), width: Math.max(0, Math.min(label.length, cols - col)), ...(button.focused ? { style: FOCUSED } : {}) });
67
69
  col += label.length + GAP;
68
70
  }
69
- return spans;
71
+ if (row.length) rows.push(row);
72
+ return rows;
70
73
  }
71
74
 
72
75
  /** `{ rows, extent, room }`: `size.rows` rows for an area `size.cols` wide: the content scrolled
73
- * to the confirmation's `top`, then an empty row and the buttons on the last row. `extent` and
74
- * `room` are the content's, for the store's scroll. */
76
+ * to the confirmation's `top`, then an empty row and the buttons on the last rows (buttonRows).
77
+ * `extent` and `room` are the content's, for the store's scroll. */
75
78
  export function act(m, size) {
76
79
  const rows = Array.from({ length: size.rows }, () => []);
77
- const room = Math.max(0, size.rows - 2);
80
+ const buttons = buttonRows(m.act.buttons, size.cols).slice(-Math.max(0, size.rows - 1));
81
+ const room = Math.max(0, size.rows - 1 - buttons.length);
78
82
  const all = actRows(m, size.cols);
79
83
  const win = windowOf({ top: m.act.top ?? 0, count: all.length, height: room });
80
84
  all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
81
85
  const note = cutNote(win.above, win.below);
82
86
  if (note && room > 0) rows[room - 1] = [{ col: LEFT, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEFT) }];
83
- if (size.rows > 0) rows[size.rows - 1] = buttonRow(m.act.buttons, size.cols);
87
+ buttons.forEach((spans, i) => { rows[size.rows - buttons.length + i] = spans; });
84
88
  return { rows, extent: all.length, room: Math.max(1, room) };
85
89
  }