@awebai/oats 0.66.0 → 0.67.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/bin/oats.mjs +66 -13
  2. package/docs/capabilities.md +4 -4
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/desktop-cli-api.md +217 -6
  5. package/docs/desktop.md +101 -22
  6. package/docs/implementation.md +6 -5
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-lane.md +16 -0
  10. package/docs/release-notes/v0.67.0.md +366 -0
  11. package/docs/release-notes/v0.67.1.md +64 -0
  12. package/docs/servers.md +3 -2
  13. package/docs/souls-and-instances.md +20 -3
  14. package/docs/tui.md +570 -176
  15. package/docs/upgrading.md +107 -25
  16. package/docs/workspaces.md +1 -1
  17. package/lib/capability-contract.mjs +2 -2
  18. package/lib/core.mjs +126 -54
  19. package/lib/instance-color.mjs +58 -0
  20. package/lib/instance-inspect.mjs +107 -23
  21. package/lib/instance-lifecycle.mjs +21 -1
  22. package/lib/instance-naming.mjs +187 -0
  23. package/lib/instance-resolution.mjs +5 -1
  24. package/lib/materialize.mjs +62 -11
  25. package/lib/servers.mjs +15 -6
  26. package/lib/soul-composition.mjs +7 -3
  27. package/package-catalog.json +1 -1
  28. package/package.json +1 -1
  29. package/packages/client/cli-adapter.mjs +37 -5
  30. package/packages/client/cli-locator.mjs +2 -2
  31. package/packages/client/composed-gate.mjs +10 -2
  32. package/packages/client/deployment-data.mjs +5 -0
  33. package/packages/client/deployment-identity.mjs +40 -0
  34. package/packages/client/deployment-panel.mjs +3 -1
  35. package/packages/client/inspect-boundary.mjs +11 -7
  36. package/packages/client/inspect-cache.mjs +2 -2
  37. package/packages/client/instance-name.mjs +28 -0
  38. package/packages/client/instance-presentation.mjs +11 -0
  39. package/packages/client/keymap.mjs +85 -24
  40. package/packages/client/keys-file.mjs +122 -0
  41. package/packages/client/own-codes.mjs +4 -2
  42. package/packages/client/panel-views.mjs +62 -9
  43. package/packages/client/spawn-naming.mjs +31 -0
  44. package/packages/client/spawn-preview-cli.mjs +22 -7
  45. package/packages/client/spawn-preview-contract.mjs +24 -0
  46. package/packages/client/spawn-preview-facts.mjs +8 -4
  47. package/packages/client/spawn-preview.mjs +47 -2
  48. package/packages/tui/README.md +3 -3
  49. package/packages/tui/lib/actions.mjs +57 -14
  50. package/packages/tui/lib/client.mjs +8 -4
  51. package/packages/tui/lib/config.mjs +50 -9
  52. package/packages/tui/lib/main.mjs +40 -13
  53. package/packages/tui/lib/model.mjs +167 -63
  54. package/packages/tui/lib/read.mjs +53 -1
  55. package/packages/tui/lib/store.mjs +148 -54
  56. package/packages/tui/lib/term/keys.mjs +19 -5
  57. package/packages/tui/lib/term/kitty.mjs +36 -11
  58. package/packages/tui/lib/term/through.mjs +61 -28
  59. package/packages/tui/lib/views/frame.mjs +158 -79
  60. package/packages/tui/lib/views/help.mjs +109 -26
  61. package/packages/tui/lib/views/instances.mjs +59 -20
  62. package/packages/tui/lib/views/palette.mjs +14 -4
  63. package/packages/tui/lib/views/souls.mjs +2 -2
  64. package/packages/tui/lib/views/switcher.mjs +6 -1
  65. package/skills/oats-getting-started/SKILL.md +13 -8
@@ -1,22 +1,23 @@
1
1
  // What is typed through to an agent's terminal (docs/tui.md, "Open an agent's terminal"). While
2
2
  // a terminal has the focus the TUI reads no keys: the bytes the outer terminal sends go to the
3
- // agent exactly as they came, and the scanner here looks for two things only, the back key's own
4
- // bytes (which take the focus back to the list) and a bracketed paste (which goes to the agent as
5
- // a paste, so a back key inside it is pasted, not taken). Under the kitty keyboard protocol
6
- // (docs/tui.md, "Chords") it also takes the chords, and types every other key as the bytes it
7
- // sends without the protocol (see createThrough). Pure: no IO; the clock is injected.
3
+ // agent exactly as they came, and the scanner here looks for three things only: the back key's own
4
+ // bytes (which take the focus back to the list), a bracketed paste (which goes to the agent as a
5
+ // paste, so a back key inside it is pasted, not taken) and the chords (docs/tui.md, "Chords"): the
6
+ // Alt+Shift arrows in every state, and under the kitty keyboard protocol the Ctrl+Alt ones too (or,
7
+ // when keys.json chose that family, the Ctrl+Shift ones), every other key then typed as the bytes it sends without the protocol (see createThrough). Pure:
8
+ // no IO; the clock is injected.
8
9
  //
9
10
  // The back key is tui.json's `open.detachKey`. Its grammar is THE TUI'S OWN: the keys it can take
10
11
  // back from a terminal and name in the cheat sheet. It began as the kernel's `--detach-key` grammar
11
12
  // (lib/session-viewer.mjs) and keeps its set and its spelling, so a tui.json written for PR 4 means
12
13
  // the same key; it is not tied to the kernel's, which never sees this key any more.
13
14
  import { ESC_TIMEOUT_MS, PASTE_LIMIT, PASTE_PAUSE_MS, createKeyParser, keyId, legacyEvents } from "./keys.mjs";
14
- import { confirmed, kittyId, kittyKey, legacyBytes, legacySequence } from "./kitty.mjs";
15
+ import { LEGACY_CHORDS, confirmed, kittyId, kittyKey, legacyBytes, legacyChord, legacySequence } from "./kitty.mjs";
15
16
 
16
- /** How long bytes held only as a beginning of the back key wait for the rest of it, in
17
- * milliseconds: the back key counts only as ONE keypress (a terminal writes a key's bytes at
18
- * once; a split read of them comes within this), so Esc and then `o` typed as two keys reach the
19
- * agent as they were typed, and never as M-o. Bytes that may begin a paste's start marker wait
17
+ /** How long bytes held only as a beginning of the back key (or of an Alt+Shift arrow chord, see
18
+ * createThrough) wait for the rest of it, in milliseconds: the back key counts only as ONE
19
+ * keypress (a terminal writes a key's bytes at once; a split read of them comes within this), so
20
+ * Esc and then `o` typed as two keys reach the agent as they were typed, and never as M-o. Bytes that may begin a paste's start marker wait
20
21
  * the key parser's Esc timeout (ESC_TIMEOUT_MS) instead, as before. */
21
22
  export const BACK_KEY_SPLIT_MS = 10;
22
23
 
@@ -104,33 +105,52 @@ const decoder = () => new TextDecoder("utf-8", { fatal: false });
104
105
  * the agent's, and `rest` hands it on) or `{ chord: <does>, rest: <bytes> }` (a chord, the same).
105
106
  *
106
107
  * UNDER THE PROTOCOL (`keyboard` the confirmed flags, term/kitty.mjs; docs/tui.md, "Chords") the
107
- * scanner reads every `CSI` sequence typed. A `u` key is a chord when its id is one of `chords`
108
- * (a Map of key id to the `does` it names), else the bytes it sends without the protocol
109
- * (legacyBytes), which are the back key when they read as `leader` (the back key's key id,
110
- * backKeyId), with no timing: Alt+O is one sequence and Esc is another. Any other sequence is
108
+ * scanner reads every `CSI` sequence typed. A `u` key is a chord when its id (kittyId, a Ctrl+Alt or
109
+ * a Ctrl+Shift chord's) is one of `chords` (a Map of key id to the `does` it names), else the bytes it sends
110
+ * without the protocol (legacyBytes), which are the back key when they read as `leader` (the back
111
+ * key's key id, backKeyId) and the key has no id of its own (kittyId: Ctrl+Shift+X, whose legacy
112
+ * byte is Ctrl+X's, is typed, never the back key), with no timing: Alt+O is one sequence and Esc is another. Any other sequence is
111
113
  * the same, made legacy where the protocol changed it (legacySequence: the modifier, F1 to F4).
112
114
  * What is not a sequence goes to the agent as it came. Nothing is timed: a sequence a read ends
113
115
  * inside, or a lone ESC (which no key sends under the protocol), waits for the next read however
114
116
  * late it comes; one longer than SEQUENCE_HELD is no key and goes on as it came.
115
- * Without it (`keyboard` null or "asking") nothing of that is read, and what follows holds. While
117
+ * A Ctrl+Shift chord is read only so, from its event's Shift bit: a Ctrl+Shift letter that is not
118
+ * among `chords` (every one under the default family) is typed as Ctrl and the letter
119
+ * (`CSI 100;6u` is 0x04, the agent's Ctrl+D), and a C0 byte typed is never a chord.
120
+ * The legacy bytes are read as the key they are: an Alt+Shift arrow among `chords`
121
+ * (term/kitty.mjs LEGACY_CHORDS) is the chord however the protocol reports the lock keys in its
122
+ * modifier (legacyParams: `CSI 1 ; 68 A` with Caps Lock is `CSI 1 ; 4 A`), and so is a keypad
123
+ * arrow whose legacy bytes are that sequence.
124
+ * Without it (`keyboard` null or "asking") no `CSI u` key is read and no key is made legacy, and
125
+ * what follows holds. While
116
126
  * "asking", the answer may arrive split across reads, and over a slow link late: a read that ends
117
127
  * in what may begin it (ESC, `ESC [`, `ESC [ ?` and digits) is held until `answerBy` (the clock time
118
128
  * the run stops waiting for it), at least the key parser's Esc timeout. A later read that does not
119
129
  * go on with the answer comes after them: within BACK_KEY_SPLIT_MS joined to them as before (the
120
130
  * back key, a paste), later handed on after them, as a key of its own, so they never make the back
121
131
  * key with it. giveUp() hands on what is held for the answer.
122
- * A read is never held back from the agent but for a beginning of the back key's own bytes, or of
123
- * a paste's start marker from its third byte: those wait for the next read, or until `timeoutAt()`
124
- * (BACK_KEY_SPLIT_MS for the back key's alone, the key parser's Esc timeout when they may begin a
125
- * paste) hands them on as input, through `expire()` or the first read that comes later, which
126
- * then never completes the back key with them. A paste is held until
127
- * its end marker; one that reaches PASTE_LIMIT is dropped whole, and one whose end has not come
132
+ * A Control back key's byte right after ESC in a read is Ctrl+Alt with that key (ESC 0x18 is
133
+ * Ctrl+Alt+X), as the key parser reads it: the agent's, never the back key.
134
+ * The Alt+Shift arrow chords among `chords` are taken as the back key is: their one legacy
135
+ * sequence exactly (`CSI 1 ; 4 A` to `D`, nothing but Alt and Shift in the modifier), with what
136
+ * came after it in the read handed on as the rest.
137
+ * A read is never held back from the agent but for a beginning of the back key's own bytes or of
138
+ * such a chord's, or of a paste's start marker from its third byte: those wait for the next read,
139
+ * or until `timeoutAt()` (BACK_KEY_SPLIT_MS for a key's alone, the key parser's Esc timeout when
140
+ * they may begin a paste) hands them on as input, through `expire()` or the first read that comes
141
+ * later, which then never completes the key with them. An Alt+Shift arrow chord is one keypress,
142
+ * as the back key is: its bytes split across reads within BACK_KEY_SPLIT_MS are the chord, and
143
+ * split further apart they reach the agent as they came (Alt+Shift+Up for the agent's program),
144
+ * so a key of the agent's that begins as one does (Esc, `ESC [ 1`) waits no longer than that for
145
+ * its sake. A paste is held until its end marker; one that reaches PASTE_LIMIT is dropped whole, and one whose end has not come
128
146
  * when a read arrives PASTE_PAUSE_MS after the one before is given to the agent as what it held,
129
147
  * and that read is scanned anew, as the key parser abandons a stalled paste. */
130
148
  export function createThrough({ sequences, now, keyboard = null, leader = null, chords = new Map(), answerBy = null }) {
131
149
  if (typeof now !== "function") throw new TypeError("createThrough needs an injected clock: { now: () => milliseconds }");
132
150
  if (!(keyboard === null || keyboard === "asking" || confirmed(keyboard))) throw new TypeError("keyboard is null, \"asking\" or flags that hold flag 1");
133
151
  const keys = sequences.map((seq) => Uint8Array.from(seq));
152
+ /** The Alt+Shift arrow chords, `[bytes, does]`: their legacy sequence, read without the protocol. */
153
+ const arrows = [...chords].filter(([id]) => legacyChord(id)).map(([id, does]) => [escaped(`[1;4${LEGACY_CHORDS[id]}`), does]);
134
154
  let kb = keyboard;
135
155
  /** The bytes held for the next read, since when, and how long they may wait: BACK_KEY_SPLIT_MS
136
156
  * when they are held only as a beginning of the back key, ESC_TIMEOUT_MS when they may begin a
@@ -212,17 +232,25 @@ export function createThrough({ sequences, now, keyboard = null, leader = null,
212
232
  kb = confirmed(answer.flags) ? answer.flags : null;
213
233
  return scan(out, data.subarray(answer.end));
214
234
  }
215
- const key = keys.find((seq) => seq[0] === b && at(data, i, seq));
235
+ // A Control back key right after ESC is Ctrl+Alt with it (ESC 0x18 is Ctrl+Alt+X), never the
236
+ // back key: it goes to the agent as it came, as the key parser reads it as ctrl+alt+x.
237
+ const key = keys.find((seq) => seq[0] === b && at(data, i, seq) && !(seq.length === 1 && i > 0 && data[i - 1] === ESC));
216
238
  if (key) {
217
239
  if (i > 0) out.push({ input: data.subarray(0, i) });
218
240
  out.push({ back: true, rest: data.subarray(i + key.length) });
219
241
  return;
220
242
  }
221
- // The read ends on what may be the beginning of the back key, of a paste or of the answer
222
- // awaited: held, as long as the longest that it may begin allows.
243
+ const arrow = b === ESC ? arrows.find(([seq]) => at(data, i, seq)) : undefined;
244
+ if (arrow) {
245
+ if (i > 0) out.push({ input: data.subarray(0, i) });
246
+ out.push({ chord: arrow[1], rest: data.subarray(i + arrow[0].length) });
247
+ return;
248
+ }
249
+ // The read ends on what may be the beginning of the back key, of an Alt+Shift arrow chord, of
250
+ // a paste or of the answer awaited: held, as long as the longest that it may begin allows.
223
251
  const pasting = data.length - i >= PASTE_HELD_FROM && begins(data, i, PASTE_START);
224
252
  const answering = kb === "asking" && answerBegins(data, i);
225
- const keying = keys.some((seq) => begins(data, i, seq));
253
+ const keying = keys.some((seq) => begins(data, i, seq)) || arrows.some(([seq]) => begins(data, i, seq));
226
254
  if (pasting || answering || keying) {
227
255
  if (i > 0) out.push({ input: data.subarray(0, i) });
228
256
  held = Uint8Array.from(data.subarray(i));
@@ -260,16 +288,21 @@ export function createThrough({ sequences, now, keyboard = null, leader = null,
260
288
  handOn(i);
261
289
  from = end;
262
290
  i = end - 1;
263
- let bytes;
291
+ let bytes, own = null;
264
292
  if (final === "u") {
265
293
  if (/^\?\d{1,3}$/.test(params)) continue; // the protocol's answer again: never the agent's
266
294
  const key = kittyKey(params), id = kittyId(key);
267
295
  if (id !== null && chords.has(id)) { out.push({ chord: chords.get(id), rest: data.subarray(end) }); return; }
296
+ own = id;
268
297
  bytes = legacyBytes(key, kb);
269
298
  } else bytes = legacySequence(params, final);
270
299
  if (bytes === null) continue; // a key that sends nothing without the protocol: nothing
271
- const events = leader === null ? [] : legacyEvents(bytes);
272
- if (events.length === 1 && keyId(events[0]) === leader) { out.push({ back: true, rest: data.subarray(end) }); return; }
300
+ // What the bytes read as without the protocol: the back key, or an Alt+Shift arrow chord. A
301
+ // key with an id of its own (kittyId: Ctrl+Shift or Ctrl+Alt with a letter) is never the back
302
+ // key, though its legacy bytes may read as it (Ctrl+Shift+X is 0x18, as Ctrl+X): it types them.
303
+ const events = legacyEvents(bytes), id = events.length === 1 ? keyId(events[0]) : null;
304
+ if (id !== null && id === leader && own === null) { out.push({ back: true, rest: data.subarray(end) }); return; }
305
+ if (legacyChord(id) && chords.has(id)) { out.push({ chord: chords.get(id), rest: data.subarray(end) }); return; }
273
306
  out.push({ input: bytes });
274
307
  }
275
308
  handOn(data.length);
@@ -10,12 +10,12 @@
10
10
  // whole width, and the detail and every overlay are a page over the whole screen. There is no
11
11
  // header and no footer. The TUI's own words are lit(); everything else is shown(). Meaning never
12
12
  // rests on colour alone: what is dim or bold also says what it is in words or by a mark.
13
- import { LEADER, backKeyLabel, keyLabel } from "../actions.mjs";
13
+ import { LEADER, backKeyLabel, keyLabel, keysTogether } from "../actions.mjs";
14
14
  import { lit, ownEllipsis, shown, shownLines, textOf } from "../term/text.mjs";
15
15
  import { style } from "../term/style.mjs";
16
16
  import { act } from "./act.mjs";
17
17
  import { detail } from "./detail.mjs";
18
- import { help, keyText } from "./help.mjs";
18
+ import { help, keyText, paletteGroupKeys } from "./help.mjs";
19
19
  import { instances, measured } from "./instances.mjs";
20
20
  import { textWidth } from "../term/width.mjs";
21
21
  import { palette } from "./palette.mjs";
@@ -65,7 +65,7 @@ const FOCUSED = style({ bold: true, reverse: true });
65
65
 
66
66
  const clamp = (n, low, high) => Math.min(Math.max(n, low), high);
67
67
  const tooSmall = (size) => size.cols < MIN_SIZE.cols || size.rows < MIN_SIZE.rows;
68
- /** The leader's label, spelt for people (`Alt+O`, `Ctrl+\`): tui.json's open.detachKey is the
68
+ /** The leader's label, spelt for people (`Ctrl+X` by default, `Alt+O`): tui.json's open.detachKey is the
69
69
  * user's, so it is text from outside. */
70
70
  const leaderText = (m) => keyText(backKeyLabel(m.detachKey));
71
71
 
@@ -280,12 +280,16 @@ function types(m) {
280
280
  }
281
281
 
282
282
  /** THE CHEAT SHEET (docs/tui.md, "The cheat sheet"): the keys that apply now, one per row, the
283
- * leader first in every focus (`Alt+O commands`), then the palette, `help` and `quit` last. While
283
+ * leader first in every focus (`Ctrl+X commands`), then the palette, `help` and `quit` last. While
284
284
  * the leader waits for its key it is the leader's hint (leaderHints). While what is typed goes to
285
- * the agent the TUI reads the leader only: the leader then Esc gives the list the focus, and the
286
- * leader twice types the leader into the terminal. In the palette, the spawn prompt (spawnHints),
287
- * a confirmation, the filter field, the help and the switcher, how to work them: the keys they
288
- * read are their own, so they are the TUI's words, but for the confirmation's close key and the
285
+ * the agent the TUI reads the leader and the chords only: the leader then Esc gives the list the
286
+ * focus, and the leader twice types the leader into the terminal; while the terminal confirms the
287
+ * kitty keyboard protocol the chords lead there (docs/tui.md, "Chords"; chordHints), the leader's
288
+ * hints after them, and the leader is the last given up; without it the leader's lead, and the
289
+ * Alt+Shift arrows, the chords that come then, follow them (the first given up). In the palette
290
+ * (its group keys last, where the TUI has them, so the first given up: paletteGroups), the spawn prompt
291
+ * (spawnHints), a confirmation, the filter field, the help and the switcher, how to work them: the
292
+ * keys they read are their own, so they are the TUI's words, but for the confirmation's close key and the
289
293
  * field's clear, which are the user's. Else it is small: a view's list or its detail names what
290
294
  * Enter does now, and the rest stays the leader's hint's, the palette's and the help's. In the list
291
295
  * of instances Enter is `open` while it would open the selected agent's terminal and `focus
@@ -294,8 +298,9 @@ function types(m) {
294
298
  * from the list and the soul's instances from the detail; in the Capabilities view the detail,
295
299
  * and from it the marked soul. With the detail's focus the key that goes back to the list
296
300
  * (`Tab back`) comes before it, and `spawn` after it where it spawns (the list of instances, the
297
- * Souls view of a workspace of this machine). An action with no key (tui.json may unbind one) has
298
- * no hint. The views have no hint: the accordion names their keys. When rows are short the sheet
301
+ * Souls view of a workspace of this machine), then in the Instances view `workspaces` (the
302
+ * switcher). An action with no key (tui.json may unbind one) has no hint. The views have no
303
+ * hint: the accordion names their keys. When rows are short the sheet
299
304
  * gives up rows from its end (keptHints), down to the leader alone. */
300
305
  function cheatSheet(m) {
301
306
  const action = (id) => (m.actions ?? []).find((a) => a.id === id && a.keys.length);
@@ -309,9 +314,10 @@ function cheatSheet(m) {
309
314
  const listing = !["help", "switcher", "souls", "capabilities"].includes(m.view);
310
315
  if (listing && m.terminal?.focus === "terminal" && !m.palette && !m.spawn) {
311
316
  const label = backKeyLabel(m.detachKey), list = keyLabel(LEADER.find((entry) => entry.does === "list").keys[0]);
312
- return led([made("list", keyText(`${label} ${list}`), "the list"), made("again", keyText(`${label} ${label}`), types(m))]);
317
+ const leader = [made("list", keyText(`${label} ${list}`), "the list"), made("again", keyText(`${label} ${label}`), types(m))];
318
+ return m.kitty ? [...chordHints(m), ...led(leader)] : [...led(leader), ...chordHints(m)];
313
319
  }
314
- if (m.palette) return led([own("run", "Enter", "run"), own("move", "Up/Down", "move"), own("close", "Esc", "close")]);
320
+ if (m.palette) return led([own("run", "Enter", "run"), own("move", "Up/Down", "move"), own("close", "Esc", "close"), paletteGroups(m)]);
315
321
  if (m.spawn) return led(spawnHints(m.spawn, m.ascii));
316
322
  if (m.view !== "help" && filter?.editing) return led([own("keep", "Enter", "keep"), hint("close", "clear")]);
317
323
  if (m.view === "act" && m.act) {
@@ -331,7 +337,35 @@ function cheatSheet(m) {
331
337
  : capability?.detail ? (capability.focus !== "detail" ? [hint("open", "detail")] : capability.mark >= 0 ? [hint("open", "soul")] : []) : [];
332
338
  const detailed = soul ? soul.focus === "detail" && Boolean(soul.detail) : capability ? capability.focus === "detail" && Boolean(capability.detail) : listing && m.focus === "detail";
333
339
  const spawns = listing || (soul && soul.local !== false);
334
- return led([hint("palette"), ...(detailed ? [hint("detail", "back")] : []), ...enter, ...(spawns ? [hint("spawn")] : []), hint("help"), hint("quit")]);
340
+ return led([hint("palette"), ...(detailed ? [hint("detail", "back")] : []), ...enter, ...(spawns ? [hint("spawn")] : []), ...(listing ? [hint("workspaces")] : []), hint("help"), hint("quit")]);
341
+ }
342
+
343
+ /** The palette's own keys as one hint (docs/tui.md, "The palette"): the first row of the group
344
+ * before and of the next, `Alt+Shift+Up/Down group` (keysTogether), from the model's
345
+ * `paletteKeys` (views/help.mjs paletteGroupKeys); null where the TUI has none (macOS). */
346
+ function paletteGroups(m) {
347
+ const pair = paletteGroupKeys(m.paletteKeys);
348
+ return pair === null ? null : own("group", keysTogether(pair), "group");
349
+ }
350
+
351
+ /** The chords a terminal's cheat sheet names under the kitty keyboard protocol, in this order, a
352
+ * pair as one hint, each with the TUI's word: what is reached most from a terminal. */
353
+ const SHEET_CHORDS = Object.freeze([
354
+ Object.freeze([["palette"], "palette"]),
355
+ Object.freeze([["previous", "next"], "agent"]),
356
+ Object.freeze([["tab-previous", "tab-next"], "tab"]),
357
+ Object.freeze([["close-terminal"], "close"]),
358
+ Object.freeze([["zoom"], "zoom"]),
359
+ ]);
360
+ /** The chord hints of a terminal's focus (docs/tui.md, "Chords"): those of SHEET_CHORDS read now
361
+ * (the model's `chords`: tui.json may have taken a key; without the protocol the Alt+Shift
362
+ * arrows alone), the tabs' only
363
+ * with two tabs or more, as the leader's hint has them. A pair's keys share their modifiers:
364
+ * `Alt+Shift+Up/Down` (keysTogether). They stand in a block of their own (cheatRows). */
365
+ function chordHints(m) {
366
+ const keyOf = new Map((m.chords ?? []).map(([key, does]) => [does, key]));
367
+ return SHEET_CHORDS.filter(([list]) => list.every((does) => keyOf.has(does)) && (list[0] !== "tab-previous" || (m.tabs?.length ?? 0) > 1))
368
+ .map(([list, word]) => ({ ...made(`chord-${list[0]}`, keyText(keysTogether(list.map((does) => keyOf.get(does)))), word), block: "chords" }));
335
369
  }
336
370
 
337
371
  /** The spawn prompt's hints (docs/tui.md, "Spawning an agent"): the keys the prompt reads are its
@@ -373,26 +407,49 @@ function leaderHints(m) {
373
407
  ];
374
408
  }
375
409
 
376
- /** The hints that stand in `count` rows: given up from the end, down to the leader alone; the
377
- * leader's hint keeps its last, the list's, while it has two rows. */
410
+ /** The hints that stand in `count` rows: given up from the end, down to the leader alone (givenUp);
411
+ * the leader's hint keeps its last, the list's, while it has two rows. */
378
412
  function keptHints(m, hints, count) {
379
413
  if (count >= hints.length) return hints;
380
414
  if (m.leader && count >= 2) return [...hints.slice(0, count - 1), hints.at(-1)];
381
- return hints.slice(0, Math.max(1, count));
415
+ let kept = hints;
416
+ while (kept.length > Math.max(1, count)) kept = givenUp(kept);
417
+ return kept;
418
+ }
419
+ /** `hints` with one given up: the last but the leader's (`commands`), which goes last of all. In a
420
+ * sheet that leads with the leader that is the last; in one that leads with the chords (a
421
+ * terminal's, under the kitty keyboard protocol) the leader stays after them. */
422
+ function givenUp(hints) {
423
+ const at = hints.findLastIndex((h) => h.id !== "leader");
424
+ return at < 0 ? hints.slice(0, -1) : [...hints.slice(0, at), ...hints.slice(at + 1)];
382
425
  }
383
426
 
384
427
  /** The cheat sheet's rows, `cols` wide: each hint's key in bold from the margin, and what it does
385
- * in a column of its own after the widest key; a word is cut at the edge. */
428
+ * in a column of its own after the widest key; a word is cut at the edge. The hints of a `block`
429
+ * (the chords') have a column of their own, after their own widest key, and as far left as
430
+ * leaves their words whole: those words are the TUI's own and short, where their keys are long
431
+ * (`Alt+Shift+Left/Right` in the 30 cells beside a terminal). */
386
432
  function cheatRows(hints, cols) {
387
433
  const edge = cols - MARGIN;
388
- const widest = hints.reduce((most, h) => Math.max(most, h.key.width), 0);
389
- const wordCol = Math.min(MARGIN + widest + GAP, Math.max(MARGIN + 1, edge - 6));
390
- return hints.map((h) => [
391
- { col: MARGIN, text: h.key.text, style: BOLD, width: Math.max(0, Math.min(h.key.width, wordCol - 1 - MARGIN)) },
392
- ...h.word.spans.map((span) => ({ ...span, col: wordCol + span.col, width: Math.max(0, Math.min(span.width, edge - wordCol - span.col)) })),
393
- ].filter((span) => span.width > 0));
434
+ const columns = new Map();
435
+ for (const h of hints) {
436
+ const c = columns.get(h.block) ?? { widest: 0, word: 6 };
437
+ columns.set(h.block, { widest: Math.max(c.widest, h.key.width), word: h.block === undefined ? c.word : Math.max(c.word, h.word.width) });
438
+ }
439
+ return hints.map((h) => {
440
+ const c = columns.get(h.block), wordCol = Math.min(MARGIN + c.widest + GAP, Math.max(MARGIN + 1, edge - c.word));
441
+ return [
442
+ { col: MARGIN, text: h.key.text, style: BOLD, width: Math.max(0, Math.min(h.key.width, wordCol - 1 - MARGIN)) },
443
+ ...h.word.spans.map((span) => ({ ...span, col: wordCol + span.col, width: Math.max(0, Math.min(span.width, edge - wordCol - span.col)) })),
444
+ ].filter((span) => span.width > 0);
445
+ });
394
446
  }
395
447
 
448
+ /** The cheat sheet a title row carries (withKeys): without the kitty keyboard protocol the
449
+ * Alt+Shift arrows follow the leader's hints in the sheet's rows, but a title row keeps to the
450
+ * leader's; under it the chords lead there as in the rows. */
451
+ const titleSheet = (m) => cheatSheet(m).filter((h) => m.kitty || h.block !== "chords");
452
+
396
453
  /** An overlay's or a detail page's first row on a narrow terminal, where it has the whole screen:
397
454
  * its essential keys (the cheat sheet's, but for the leader, the palette, help and quit) at the
398
455
  * right, dim, as many as fit after what the row holds, given up from the end. With `first`, the
@@ -406,8 +463,9 @@ function withKeys(given, hints, cols, { skip = ["leader", "palette", "help", "qu
406
463
  // What the row holds ends where its text does: a span may be given more cells than its text takes.
407
464
  const end = row.reduce((most, span) => (span.text !== undefined ? Math.max(most, span.col + Math.min(span.width ?? Infinity, textWidth(textOf(span.text)))) : most), 0);
408
465
  let kept = keys;
409
- // Given up from the end; with `last`, the last is kept as long as one other is (the leader's `Esc`).
410
- while (kept.length && end + GAP + widthOf(kept) > cols - MARGIN) kept = last && kept.length > 1 ? [...kept.slice(0, -2), kept.at(-1)] : kept.slice(0, -1);
466
+ // Given up from the end, the leader last (givenUp); with `last`, the last is kept as long as one
467
+ // other is (the leader's `Esc`).
468
+ while (kept.length && end + GAP + widthOf(kept) > cols - MARGIN) kept = last && kept.length > 1 ? [...kept.slice(0, -2), kept.at(-1)] : givenUp(kept);
411
469
  const spans = [];
412
470
  let col = cols - MARGIN - widthOf(kept);
413
471
  for (const h of kept) {
@@ -514,7 +572,7 @@ function framed(m, size) {
514
572
  const overlay = (drawn) => {
515
573
  if (g.wide) { sidebar(m, g, rows, listOf(m, g)); barred(m, rows, g.listCols); }
516
574
  drawn.forEach((spans, i) => { if (i < size.rows) rows[i] = [...rows[i], ...placed(spans, main.col)]; });
517
- if (!g.wide) rows[0] = withKeys(rows[0], cheatSheet(m), cols);
575
+ if (!g.wide) rows[0] = withKeys(rows[0], titleSheet(m), cols);
518
576
  };
519
577
 
520
578
  // The palette, whatever is under it.
@@ -539,7 +597,7 @@ function framed(m, size) {
539
597
  }
540
598
  // The help, under its top row (readRow).
541
599
  if (m.view === "help") {
542
- const drawn = help(m.actions, { cols: main.cols, rows: size.rows - 1 }, { top: m.helpTop, ascii: m.ascii, detachKey: m.detachKey, chords: m.chords ?? null });
600
+ const drawn = help(m.actions, { cols: main.cols, rows: size.rows - 1 }, { top: m.helpTop, ascii: m.ascii, detachKey: m.detachKey, chords: m.chords ?? null, chordsLead: m.kitty === true, paletteKeys: m.paletteKeys ?? null, keys: m.keys ?? null });
543
601
  overlay([readRow(m), ...drawn.rows]);
544
602
  return { rows, page: Math.max(1, g.page), extent: drawn.extent, room: Math.max(1, size.rows - 1) };
545
603
  }
@@ -584,7 +642,7 @@ function framed(m, size) {
584
642
  // Over the whole screen no cheat sheet is drawn: the terminal's title row, the TUI's own, carries
585
643
  // its keys at the right instead (the leader, then Esc for the list), and while the leader waits,
586
644
  // the leader's hint, as many as fit, its last (`Esc the list`) kept.
587
- if (zoomed) rows[area.title] = m.leader ? withKeys(rows[area.title], leaderHints(m), cols, { skip: [], last: true }) : withKeys(rows[area.title], cheatSheet(m), cols, { skip: ["again"] });
645
+ if (zoomed) rows[area.title] = m.leader ? withKeys(rows[area.title], leaderHints(m), cols, { skip: [], last: true }) : withKeys(rows[area.title], titleSheet(m), cols, { skip: ["again"] });
588
646
  // The focused group's terminal, when it shows one: the agent's cursor, where the agent has it,
589
647
  // while what is typed goes to the agent.
590
648
  const shownArea = area !== null && area.id !== null && m.terminal ? { title: area.title, top: area.top, col: area.col, cols: area.cols, rows: area.rows, whole: area.whole } : null;
@@ -679,25 +737,41 @@ function terminalAt(m, size, g) {
679
737
 
680
738
  /** A hidden tab's mark for output since it was last shown (docs/tui.md, "Tabs"). */
681
739
  const ACTIVITY = "\u2022";
682
-
683
- /** The tab strip (docs/tui.md, "Tabs"), the panel's top row with two tabs or more: each tab in
684
- * order as ` name ` (and ` on machine`, dim, for another machine's agent), the shown one bold, in
685
- * reverse while what is typed goes to it, a hidden one plain with `•` after its name when its
686
- * agent wrote since it was shown. What does not fit is cut in this order: the hidden tabs'
687
- * machines, then their names, each to an equal share of what the shown tab leaves with `…`, then
688
- * the shown tab's machine, then the hidden tabs farthest from the shown one are left out. The
689
- * shown tab's name stays whole while the row can hold it. */
740
+ /** What stands between a tab's agent and its machine, another machine's: ` · ` (` - ` in ASCII). */
741
+ const tabDot = (ascii) => (ascii ? "-" : "\u00b7");
742
+ /** The divider between two tabs: one dim cell. */
743
+ const tabDivider = (ascii) => (ascii ? "|" : "\u2502");
744
+ /** The shown tab's own mark, which no style is needed to read: brackets in place of its side cells. */
745
+ const SHOWN_SIDES = Object.freeze(["[", "]"]);
746
+ /** A hidden tab's look: dim. Its activity mark is not: it is what a glance looks for. */
747
+ const HIDDEN = DIM;
748
+ /** The machine of the shown tab while what is typed goes to it: dim, in the tab's reverse video. */
749
+ const FOCUSED_DIM = style({ dim: true, reverse: true });
750
+
751
+ /** THE TAB BAR (docs/tui.md, "Tabs"), the top row of a group's region whenever it shows a tab, one
752
+ * or many, as a terminal's own tabs read: each tab in order, a dim `│` (`|` in ASCII) between two.
753
+ * A tab is its agent's name with a cell on each side, `•` (`*` in ASCII) after the name of a hidden
754
+ * one whose agent wrote since it was shown, and ` · <machine>` dim (` - ` in ASCII) inside it for
755
+ * another machine's agent. The shown tab reads as the front one: `[` and `]` stand in its side
756
+ * cells (a mark no style is needed for: it holds under NO_COLOR and in ASCII), its name is bold,
757
+ * and the whole tab is in reverse video while what is typed goes to it; a hidden tab is dim.
758
+ * What does not fit is cut in this order: the hidden tabs' machines, then their names, each to an
759
+ * equal share of what the shown tab leaves with `…`, then the shown tab's machine, then the hidden
760
+ * tabs farthest from the shown one are left out (each takes its divider with it). The shown tab's
761
+ * name stays whole while the row can hold it, and is cut last. */
690
762
  function stripRow(given, area, { focused, ascii }) {
691
- const mark = ascii ? "*" : ACTIVITY;
692
- const tabs = given.map((tab) => ({ ...tab, name: measured(tab.name), machine: tab.machine === null ? null : measured(tab.machine), mark: !tab.shown && tab.activity }));
693
- const machineCells = (tab) => (tab.machine ? 1 + ON.length + 1 + tab.machine.width : 0);
763
+ const mark = ascii ? "*" : ACTIVITY, dot = tabDot(ascii);
764
+ const tabs = given.map((tab) => ({ ...tab, name: measured(tab.name), machine: tab.machine ? measured(tab.machine) : null, mark: !tab.shown && tab.activity === true }));
765
+ const machineCells = (tab) => (tab.machine ? 3 + tab.machine.width : 0);
694
766
  const cellsOf = (tab, { machine, name = tab.name.width, dropped = false }) => (dropped ? 0 : 1 + name + (tab.mark ? 1 : 0) + (machine ? machineCells(tab) : 0) + 1);
695
- const total = (plan) => tabs.reduce((sum, tab, i) => sum + cellsOf(tab, plan[i]), 0);
696
767
  const plan = tabs.map((tab) => ({ machine: true, name: tab.name.width, dropped: false }));
697
- const fits = () => total(plan) <= area.cols;
698
- const shown = tabs.findIndex((tab) => tab.shown);
699
- // The least a hidden tab is drawn in: a cell of its name (the cut mark), its mark, a cell each side.
700
- const least = (tab) => 3 + (tab.mark ? 1 : 0);
768
+ // Each drawn tab after the first has its divider before it.
769
+ const total = () => tabs.reduce((sum, tab, i) => sum + cellsOf(tab, plan[i]), 0) + Math.max(0, plan.filter((p) => !p.dropped).length - 1);
770
+ const fits = () => total() <= area.cols;
771
+ const shown = Math.max(0, tabs.findIndex((tab) => tab.shown));
772
+ // The least a hidden tab is drawn in: a cell of its name (the cut mark), its mark, a cell each
773
+ // side, and its divider.
774
+ const least = (tab) => 4 + (tab.mark ? 1 : 0);
701
775
  // The shown tab's cells are taken first; the hidden ones share the rest equally. Those that do
702
776
  // not get even their least are left out, the farthest from the shown tab first.
703
777
  const share = () => {
@@ -705,42 +779,56 @@ function stripRow(given, area, { focused, ascii }) {
705
779
  const near = tabs.map((tab, i) => i).filter((i) => i !== shown).sort((a, b) => Math.abs(a - shown) - Math.abs(b - shown) || a - b);
706
780
  const kept = [];
707
781
  for (const i of near) { plan[i].dropped = left - least(tabs[i]) < 0; if (!plan[i].dropped) { kept.push(i); left -= least(tabs[i]); } }
708
- const room = area.cols - cellsOf(tabs[shown], plan[shown]), each = Math.floor(room / Math.max(1, kept.length));
782
+ const room = area.cols - cellsOf(tabs[shown], plan[shown]) - kept.length, each = Math.floor(room / Math.max(1, kept.length));
709
783
  for (const i of kept) plan[i].name = Math.max(1, Math.min(tabs[i].name.width, each - 2 - (tabs[i].mark ? 1 : 0)));
710
784
  while (!fits() && kept.length) plan[kept.pop()].dropped = true;
711
785
  };
712
786
  if (!fits()) tabs.forEach((tab, i) => { if (i !== shown) plan[i].machine = false; });
713
787
  if (!fits()) share();
714
- if (plan.some((p) => p.dropped) && plan[shown].machine && tabs[shown].machine) { plan[shown].machine = false; plan.forEach((p) => { p.dropped = false; }); share(); }
788
+ if ((!fits() || plan.some((p) => p.dropped)) && plan[shown].machine && tabs[shown].machine) { plan[shown].machine = false; plan.forEach((p) => { p.dropped = false; }); share(); }
789
+ // A shown name wider than the row itself: cut, its brackets kept.
790
+ if (cellsOf(tabs[shown], plan[shown]) > area.cols) plan[shown].name = Math.max(1, area.cols - 2);
791
+ const cut = (tab, p) => (p.name < tab.name.width ? shownLines(textOf(tab.name.text), p.name, 1, { ascii })[0] ?? lit("") : tab.name.text);
715
792
  const row = [];
716
- let col = area.col;
717
793
  const end = area.col + area.cols;
794
+ let col = area.col, first = true;
795
+ // `text` null is a blank cell (a hidden tab's side): its cells are passed over.
796
+ const put = (text, width, look) => {
797
+ const w = Math.max(0, Math.min(width, end - col));
798
+ if (w > 0 && text !== null) row.push({ col, text, width: w, ...(look ? { style: look } : {}) });
799
+ col += width;
800
+ };
718
801
  tabs.forEach((tab, i) => {
719
- if (col >= end || plan[i].dropped) return;
720
- const p = plan[i], width = Math.min(cellsOf(tab, p), end - col);
721
- const style = tab.shown ? (focused ? FOCUSED : BOLD) : null;
722
- const name = p.name < tab.name.width ? shownLines(textOf(tab.name.text), p.name, 1, { ascii })[0] ?? lit("") : tab.name.text;
723
- const nameWidth = Math.min(p.name, textWidth(textOf(name)), end - col - 1);
724
- // In reverse, as T1's title: the name with a cell on each side; its machine stays dim.
725
- if (tab.shown && focused) row.push({ col, width: Math.min(nameWidth + 2, end - col), style: FOCUSED });
726
- if (nameWidth > 0) row.push({ col: col + 1, text: name, width: nameWidth, ...(style ? { style } : {}) });
727
- let at = col + 1 + nameWidth;
728
- if (tab.mark && at < end) { row.push({ col: at, text: lit(mark), width: 1 }); at += 1; }
729
- if (p.machine && tab.machine && at + 1 + ON.length + 1 < end) {
730
- row.push({ col: at + 1, text: lit(ON), style: DIM, width: ON.length });
731
- row.push({ col: at + 2 + ON.length, text: tab.machine.text, style: DIM, width: Math.max(0, Math.min(tab.machine.width, end - (at + 2 + ON.length))) });
802
+ const p = plan[i];
803
+ if (p.dropped || col >= end) return;
804
+ if (!first) put(lit(tabDivider(ascii)), 1, DIM);
805
+ first = false;
806
+ if (col >= end) return;
807
+ const front = tab.shown, reversed = front && focused;
808
+ const look = front ? (reversed ? FOCUSED : BOLD) : HIDDEN;
809
+ // In reverse while what is typed goes to it: the whole tab, its sides and machine included.
810
+ if (reversed) row.push({ col, width: Math.max(0, Math.min(cellsOf(tab, p), end - col)), style: FOCUSED });
811
+ const [left, right] = front ? SHOWN_SIDES.map((side) => lit(side)) : [null, null];
812
+ put(left, 1, look);
813
+ const name = cut(tab, p);
814
+ put(name, Math.min(p.name, textWidth(textOf(name))), look);
815
+ if (tab.mark) put(lit(mark), 1, null);
816
+ if (p.machine && tab.machine) {
817
+ const machineLook = reversed ? FOCUSED_DIM : DIM;
818
+ put(null, 1, null);
819
+ put(lit(dot), 1, machineLook);
820
+ put(null, 1, null);
821
+ put(tab.machine.text, tab.machine.width, machineLook);
732
822
  }
733
- col += width;
823
+ put(right, 1, look);
734
824
  });
735
825
  return row;
736
826
  }
737
827
 
738
- /** The open terminal's rows from its title row: the agent's name (and its machine, when it is
739
- * another's), in reverse while what is typed goes to it (with two tabs or more, the tab strip:
740
- * stripRow), then the shown agent's screen as the last capture made it (lib/panel.mjs,
741
- * term/capture.mjs: spans of the agent's own text and styles), each row placed at the terminal's
742
- * first column and kept inside its cells. */
743
- /** What an empty group shows (docs/tui.md, "Splits"), under an empty strip row: that Enter on an
828
+ /** The open terminal's rows from its top row: the tab bar (stripRow), then the shown agent's
829
+ * screen as the last capture made it (lib/panel.mjs, term/capture.mjs: spans of the agent's own
830
+ * text and styles), each row placed at the terminal's first column and kept inside its cells. */
831
+ /** What an empty group shows (docs/tui.md, "Splits"), under an empty tab bar row: that Enter on an
744
832
  * agent in the list opens it here, in reverse while it is the focused group, then the leader's
745
833
  * keys for the groups. */
746
834
  const EMPTY_HINT = "Enter on an agent opens it here";
@@ -764,18 +852,9 @@ function regionRows(m, area) {
764
852
  // The focused group's shown tab is in reverse while what is typed goes to it; the other group's
765
853
  // is bold, never in reverse, so one terminal at a time reads as focused (T3).
766
854
  const focused = area.focused && m.terminal?.focus === "terminal";
767
- const tab = group.tabs.find((each) => each.shown) ?? { name: m.terminal?.name, machine: m.terminal?.routed ? m.terminal.machine : null };
768
- const name = measured(tab.name);
769
- let title = [];
770
- if (group.tabs.length > 1) title = stripRow(group.tabs, area, { focused, ascii: m.ascii });
771
- else {
772
- if (focused) title.push({ col: area.col, width: Math.min(area.cols, name.width + 2), style: FOCUSED });
773
- title.push({ col: area.col + 1, text: name.text, style: focused ? FOCUSED : BOLD, width: Math.max(0, Math.min(name.width, area.cols - 2)) });
774
- if (tab.machine) {
775
- const where = measured(tab.machine), at = area.col + name.width + 3;
776
- if (at + ON.length + 1 < area.col + area.cols) title.push({ col: at, text: lit(ON), style: DIM, width: ON.length }, { col: at + ON.length + 1, text: where.text, style: DIM, width: Math.max(0, area.col + area.cols - (at + ON.length + 1)) });
777
- }
778
- }
855
+ // A model made by hand may name its terminal and no tabs: its one tab is that terminal.
856
+ const tabs = group.tabs.length ? group.tabs : [{ name: m.terminal?.name, machine: m.terminal?.routed ? m.terminal.machine : null, shown: true, activity: false }];
857
+ const title = stripRow(tabs, area, { focused, ascii: m.ascii });
779
858
  const screenOf = area.focused ? m.screen : m.screens?.get(group.shown) ?? null;
780
859
  const lines = screenOf?.lines ?? [];
781
860
  const body = Array.from({ length: area.rows }, (_, r) => (lines[r] ?? [])