@awebai/oats 0.65.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 (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
@@ -15,7 +15,7 @@ import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, realp
15
15
  import { tmpdir } from "node:os";
16
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, failedEntry, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
18
+ import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentIdentity, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, failedEntry, identityReadable, identityTimedOut, 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. */
@@ -613,3 +613,55 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
613
613
  children() { return [...remembered.keys()].map((child) => child.pid).filter((pid) => Number.isInteger(pid)); },
614
614
  };
615
615
  }
616
+
617
+ /** The most time the identity reads of one run take together, in ms: two reads at their own limit
618
+ * (packages/client deployment-read-cli.mjs DEPLOYMENT_READ_TIMEOUT, 30 s each). */
619
+ export const IDENTITY_BUDGET_MS = 60_000;
620
+
621
+ /** THE IDENTITY READS (docs/tui.md, "The switcher"): what the switcher learns of the deployments of this
622
+ * computer's list that the run does not serve, so that one of them is matched to its workspace before it
623
+ * is opened (#482). -> { start(paths), stop() }
624
+ * `start(paths)` reads each path's identity through the shared cliDeploymentIdentity (`oats status --dir
625
+ * <path> --json`, the read an opened deployment gets, with its own time limit, `--max-age` as a background
626
+ * cycle's), ONE AT A TIME, in order, and calls `onRead({ path, read })` with each answer as it comes:
627
+ * nothing waits for them, and the screen is drawn before the first. They take IDENTITY_BUDGET_MS at most
628
+ * together: when it runs out the read in flight is ended, and it and every read not begun answer the
629
+ * shared timed-out failure (identityTimedOut). A new `start` ends the run before it, whose answers are
630
+ * then dropped, and so does `stop()`. With a kernel that reports no workspace identities
631
+ * (identityReadable), or no path, nothing is read.
632
+ * Nothing here runs on a timer: a run starts only when its caller says, and the caller says so at the
633
+ * start and when the switcher is opened or refreshed (lib/main.mjs), never from the refresh loop.
634
+ * `exec` is the reader's asked exec (createReader `exec`): every read is a child of kind "read" in a
635
+ * session of its own, ended on every way out, and ended through the run's signal here. */
636
+ export function createIdentityReads({ cli, exec, env, onRead, timers = globalThis, budgetMs = IDENTITY_BUDGET_MS, read = cliDeploymentIdentity }) {
637
+ let run = null;
638
+ function stop() {
639
+ if (run === null) return;
640
+ run.gone = true;
641
+ run.controller.abort();
642
+ run = null;
643
+ }
644
+ async function start(paths) {
645
+ stop();
646
+ // No exec of the reader's, nothing is read: the shared reader would start its own child otherwise.
647
+ if (typeof exec !== "function" || !identityReadable(cli) || !Array.isArray(paths) || !paths.length) return;
648
+ const mine = run = { controller: new AbortController(), gone: false, spent: false };
649
+ const timer = timers.setTimeout(() => { mine.spent = true; mine.controller.abort(); }, budgetMs);
650
+ timer?.unref?.();
651
+ const own = (bin, argv, options, callback) => exec(bin, argv, { ...options, signal: mine.controller.signal }, callback);
652
+ try {
653
+ for (const path of paths) {
654
+ if (mine.gone) return;
655
+ let answer = mine.spent ? identityTimedOut() : await read(cli, path, { maxAge: BACKGROUND_MAX_AGE }, { exec: own, env });
656
+ if (mine.gone) return;
657
+ // A read the budget ended answers whatever its ending made of it: it timed out.
658
+ if (mine.spent && !answer?.ok) answer = identityTimedOut();
659
+ onRead({ path, read: answer });
660
+ }
661
+ } finally {
662
+ timers.clearTimeout(timer);
663
+ if (run === mine) run = null;
664
+ }
665
+ }
666
+ return { start: (paths) => start(paths).catch(() => {}), stop };
667
+ }
@@ -9,10 +9,10 @@
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, backKeyLabel, bindings } from "./actions.mjs";
13
- import { collapseKey, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
12
+ import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys, chordsRead, paletteKeys } from "./actions.mjs";
13
+ import { CHORDS, chordFamilyFrom, collapseKey, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
14
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";
15
+ import { BUTTON_ORDER, SPAWN_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, workspaceOf, LIST_WORDS } from "./model.mjs";
16
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";
@@ -57,6 +57,10 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
57
57
  * (awebai/oats#1390): `rows`, the shared reader's `{ path, name, state }` in the kernel's order, of
58
58
  * the last read that answered, and `failure`, the reason (`{ code, message }`) the last read failed
59
59
  * with, or null once one answered. The switcher offers the rows this run does not serve.
60
+ * `identities`: what the identity reads learned of the rows of that list (lib/main.mjs), path ->
61
+ * `{ ok: true, workspace }` or `{ ok: false, reason }` (deployment-identity.mjs), the last answer for
62
+ * each, kept for the run: the switcher matches a listed deployment to its workspace by it, and a
63
+ * deployment opened from there is in its workspace's view before its first read (lib/model.mjs heldOf).
60
64
  * `opening`: the agent of another machine whose terminal is being opened, or null:
61
65
  * `{ id, phase: "preflight", name, machine, routed }` while that machine is asked whether its
62
66
  * session is there; `name`, `machine` and `routed` are the row's as it was when Enter was
@@ -78,11 +82,20 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
78
82
  * focus: see `drawsOutcome`), held until one is; or null.
79
83
  * It is the add of the deployment the run started in, refused.
80
84
  * `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
85
+ * the default, C-x on every platform: config.mjs defaultDetachKey), and `leaderKey` the key id it is read as
82
86
  * where the TUI reads keys (term/through.mjs backKeyId).
83
87
  * `leader`: `{ read, waiting }` from the leader's read on, or null (see `leading`).
84
- * `palette`: the palette while it is open (see `paletteOpened`), or null. `recent`: the ids of
85
- * the instances opened in this run, the latest first.
88
+ * `keyboard`: the flags the terminal confirmed for the kitty keyboard protocol (lib/main.mjs, the
89
+ * event `{ keyboard }`), or null while it has not; `chords`: the chords of `platform`, key id ->
90
+ * `does` (actions.mjs chordKeys), in the family keys.json chose, every one read while `keyboard`
91
+ * is not null, and the Alt+Shift arrows alone while it is null (actions.mjs chordsRead; see
92
+ * `leading`). `keysRead`: what keys.json said at the start (lib/config.mjs loadKeys, the shared
93
+ * reader's frozen `{ family, why }`; no file when none is given): the family `chords` are bound
94
+ * in, and why it is the default when the file did not choose it. The help names both.
95
+ * `palette`: the palette while it is open (see `paletteOpened`), or null; `paletteKeys` its own
96
+ * keys on `platform`, key id -> `does` (actions.mjs paletteKeys: none on macOS), which win over
97
+ * every other key while it is open. `recent`: the ids of the instances opened in this run, the
98
+ * latest first.
86
99
  * `act`: the confirmation open in the act view (see `actOpened`), or null; `acted` counts the
87
100
  * confirmations opened in this run, so an answer for one that was closed is told apart.
88
101
  * `starting`: id -> `{ verb, since }` of this run's starts and restarts whose child is still
@@ -100,7 +113,7 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
100
113
  * agentsRoot, agent, reads, words }`, until its row is opened or two reads did not show it;
101
114
  * `previews` the number of the last preview read asked in the run, so that an answer to a prompt
102
115
  * already closed is never taken by the next one. */
103
- export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, platform, detachKey = defaultDetachKey(platform) }) {
116
+ export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, platform = process.platform, detachKey = defaultDetachKey(platform), keysRead = NO_KEYS_FILE }) {
104
117
  return Object.freeze({
105
118
  view: deployment === null ? "switcher" : "instances", back: deployment === null ? "switcher" : "instances",
106
119
  ctxs: Object.freeze(deployment === null ? [] : [deployment]), open: deployment,
@@ -109,15 +122,17 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
109
122
  memory: new Map(), notes: new Map(), collecting: false, cli, home,
110
123
  selected: null, collapsed: new Set(), filter: NO_FILTER, focus: "list", top: 0, loose: false, detailTop: 0, places: new Map(), unread: new Map(),
111
124
  switcher: NO_SWITCHER,
112
- listed: NO_LIST,
125
+ listed: NO_LIST, identities: new Map(),
113
126
  helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
114
- leaderKey: backKeyId(detachKey), leader: null, palette: null, recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
127
+ leaderKey: backKeyId(detachKey), leader: null, keyboard: null, keysRead, chords: chordKeys(platform === "darwin", actions, CHORDS, keysRead.family), palette: null, paletteKeys: paletteKeys(platform === "darwin"), recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
115
128
  spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
116
129
  notice: null,
117
130
  });
118
131
  }
119
132
 
120
133
  const next = (state, changes) => Object.freeze({ ...state, ...changes });
134
+ /** keys.json's answer when the run read none (a test's state): no file, the default family. */
135
+ const NO_KEYS_FILE = chordFamilyFrom(null);
121
136
 
122
137
  /** The switcher's own: the filter, the selection and the scroll; `line`, what it says above its rows
123
138
  * of what happened (lib/model.mjs SWITCHER_LINES: "gone", or the answer of a Remove); `refused`,
@@ -195,7 +210,7 @@ function settled(state, taken) {
195
210
  const places = new Map(taken.places); places.delete(taken.open);
196
211
  // A confirmation open over that view is closed with it: what it sent goes on.
197
212
  const dismiss = taken.act !== null ? { dismiss: taken.act.n } : {};
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 } };
213
+ 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, identify: true, ...dismiss } };
199
214
  }
200
215
  const before = roster(state);
201
216
  const unknown = new Set([...taken.unread.values()].flatMap((ids) => [...ids]));
@@ -252,6 +267,50 @@ function admitted(state, { admitted: id, at }) {
252
267
  return opened(joined, id);
253
268
  }
254
269
 
270
+ /** The deployments of a workspace picked in the switcher that were on this computer's list and not served
271
+ * (lib/main.mjs asked each whether it is a deployment now): `admitted` are served from now on, pending
272
+ * until their first read, which the identity read already placed in their workspace's view; then the
273
+ * workspace opens on the first of `opens` (its deployments, this machine's first) that is served or is
274
+ * another machine's (the workspace already open stays open, its place and tabs kept). A folder refused is not served; when nothing of the workspace can be opened the
275
+ * switcher stays, and the list is read again, so its rows say what the folders are now. */
276
+ function joinedHeard(state, { admitted: ids, opens, at }) {
277
+ const added = ids.filter((id) => !state.ctxs.includes(id));
278
+ const entries = new Map(state.entries);
279
+ for (const id of added) entries.set(id, pendingEntry(null, at));
280
+ const joined = added.length ? next(state, { ctxs: Object.freeze([...state.ctxs, ...added]), entries }) : state;
281
+ const target = opens.find((id) => joined.ctxs.includes(id) || !id.startsWith("/")) ?? null;
282
+ if (target === null) return { state: joined, effect: { list: true } };
283
+ // The workspace already open (from another machine's deployment) stays where its list was, and keeps its tabs (reduceStep).
284
+ const same = state.open !== null && workspaceOf(joined, target) === workspaceOf(state, state.open);
285
+ const shown = opened(joined, target);
286
+ return { state: same ? next(shown, { selected: state.selected, top: state.top, detailTop: state.detailTop }) : shown, effect: { refresh: { live: true } } };
287
+ }
288
+
289
+ /** The deployments a choice of the switcher stands for: a workspace's, a listed row's path, an unmatched
290
+ * view's primary (lib/model.mjs switcher). */
291
+ const choiceDeployments = (item) => item.opens ?? [item.path ?? item.primary].filter(Boolean);
292
+
293
+ /** The switcher's selection after `after` changed its rows: kept while its choice is listed; else on the
294
+ * choice that now holds a deployment the selected one stood for (a listed row whose workspace a read
295
+ * learned is in that workspace's row from then on, and back on its own row when a later answer takes
296
+ * that away), so Enter opens what was selected. */
297
+ function reselected(before, after) {
298
+ const was = switcher(before);
299
+ if (was.selected === null) return after;
300
+ const now = switcher(after);
301
+ if (now.keys.includes(was.selected)) return after;
302
+ const ids = choiceDeployments(was.items.find((item) => item.key === was.selected));
303
+ const found = now.items.find((item) => item.key !== undefined && choiceDeployments(item).some((id) => ids.includes(id)));
304
+ return found ? next(after, { switcher: Object.freeze({ ...after.switcher, selected: found.key, loose: false }) }) : after;
305
+ }
306
+
307
+ /** What an identity read learned of a deployment of this computer's list (lib/main.mjs): kept for the run,
308
+ * the last answer for each path; an answer replaces the one before it. The switcher's selection
309
+ * follows the deployment it stood on (`reselected`). */
310
+ function identityHeard(state, { path, read }) {
311
+ return { state: reselected(state, next(state, { identities: new Map(state.identities).set(path, read) })), effect: null };
312
+ }
313
+
255
314
  /** The filter's text changed. */
256
315
  function queried(state, query) {
257
316
  if (query === state.filter.query) return state;
@@ -503,7 +562,7 @@ function switched(state, action, page, event) {
503
562
  // The rows of the pane the choices have: the lines above them take theirs, and the filter
504
563
  // field one while it is shown (lib/model.mjs switcherHeight).
505
564
  const count = s.items.length, height = switcherHeight(state, page, event.area);
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;
565
+ const drawn = switcherWindow(s.items, sw.loose ? null : s.selected, { top: sw.top, height }).top;
507
566
  const from = Math.max(0, s.keys.indexOf(s.selected));
508
567
  const key = s.keys.length ? s.keys[Math.min(Math.max(0, moved(action, from, s.keys.length, page)), s.keys.length - 1)] : null;
509
568
  // No choice to go to in that direction (the first, the last, or none at all): the rows
@@ -512,15 +571,18 @@ function switched(state, action, page, event) {
512
571
  const top = windowOf({ top: moved(action, drawn, count, height), count, height }).top;
513
572
  return top === drawn ? stay : { state: put({ top, loose: true }), effect: null };
514
573
  }
515
- const at = s.items.findIndex((item) => item.key === key);
516
- // The headings above the first choice come into the pane with it, and what stands under the last one.
517
- const top = windowOf({ top: key === s.keys[0] ? 0 : key === s.keys.at(-1) ? count : drawn, count, height, keep: at }).top;
574
+ // The headings above the first choice come into the pane with it, and what stands under the last one;
575
+ // a workspace's indicator lines come in with it while they fit (lib/model.mjs switcherWindow).
576
+ const top = switcherWindow(s.items, key, { top: key === s.keys[0] ? 0 : key === s.keys.at(-1) ? count : drawn, height }).top;
518
577
  return { state: put({ selected: key, top, loose: false }), effect: null };
519
578
  }
520
579
  case "open": {
521
580
  const item = s.items.find((each) => each.key !== undefined && each.key === s.selected);
522
581
  if (!item) return stay;
523
582
  if (item.path !== undefined) return item.state === "ok" ? { state: put({ refused: null }), effect: { admit: item.path } } : stay;
583
+ // A workspace with deployments of this computer's list that this run does not serve: each is asked
584
+ // whether it is a deployment now, and served from then on (`joinedHeard`), before the workspace opens.
585
+ if (item.join?.length) return { state: put({ refused: null }), effect: { join: Object.freeze({ paths: item.join, opens: item.opens }) } };
524
586
  return item.primary === null ? stay : { state: opened(state, item.primary), effect: { refresh: { live: true } } };
525
587
  }
526
588
  case "remove": {
@@ -572,7 +634,10 @@ function removedHeard(state, { name, ok, reason = null }) {
572
634
  * (one outcome of the roster read), `{ collecting }`, `{ retiring: <Set of instanceIds> }` (this
573
635
  * run's retires in flight now), `{ listed: { rows } | { failure } }` (this computer's deployments
574
636
  * 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
637
+ * picked row turned out to be), `{ joined: { admitted, opens }, at }` (which listed deployments of a
638
+ * workspace picked in the switcher are deployments now, and the ones it may open, in order),
639
+ * `{ identity: { path, read } }` (what an identity read answered of a row of the list),
640
+ * `{ removed: { path, name, ok, reason } }` (a Remove's answer) and
576
641
  * `{ notListed: <reason> }` (the deployment the run started in was not added to the list).
577
642
  * Opening an agent gives five more: `{ prepared: { id, error? } }` (the preflight of another
578
643
  * machine's agent ended: `error` is what the shared prepareRemoteTerm threw), `{ given: true }`
@@ -584,8 +649,10 @@ function removedHeard(state, { name, ok, reason = null }) {
584
649
  * `rest`: more bytes came after it in the same read).
585
650
  * An effect is something only the loop can do: "quit", "suspend", "redraw", or an object with
586
651
  * 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
652
+ * again; with `identify: true`, then read the identities of its rows this run does not serve),
653
+ * `remove: { path, name }` (remove that row from it), `admit: <path>` (ask whether a picked
654
+ * row is a deployment), `join: { paths, opens }` (ask that of each of a picked workspace's listed
655
+ * deployments, then answer `joined`), `close: <id>` (close the open
589
656
  * terminal; when an `open` comes with it, before that open), `open: <decision>` (open the agent's
590
657
  * terminal: the model's openDecision, with its target), `panel: <id>` (the preflight is over:
591
658
  * start the viewer it prepared in the panel) and `abandon: true` (give the preflight up); or null.
@@ -627,8 +694,11 @@ function reduceStep(state, event, keymap) {
627
694
  if (state.outcome !== null && typeof event.key === "string" && keymap.has(event.key)) state = next(state, { outcome: null });
628
695
  let step = reduced(state, event, keymap);
629
696
  // The tabs are the open workspace's: whatever opened another (or left it, gone), they all close,
630
- // and the split with them.
631
- if (step.state.open !== state.open && (step.state.tabs.length || step.state.split !== null)) {
697
+ // and the split with them. Another deployment of the same workspace opened (its deployment of this
698
+ // machine, once served, in place of another machine's) keeps them.
699
+ const moved = step.state.open !== state.open && (step.state.tabs.length || step.state.split !== null);
700
+ const was = moved && step.state.open !== null ? workspaceOf(state, state.open) : null;
701
+ if (moved && (was === null || workspaceOf(step.state, step.state.open) !== was)) {
632
702
  const ids = step.state.tabs.map((tab) => tab.id);
633
703
  step = { state: next(step.state, { tabs: Object.freeze([]), terminal: null, ...NO_SPLIT }), effect: ids.length ? both(step.effect, { close: ids }) : step.effect };
634
704
  }
@@ -737,17 +807,27 @@ function ungrouped(state, g, focus) {
737
807
  return showTab(one, left, { focus, zoom: false });
738
808
  }
739
809
 
740
- /** The tab before or after the shown one (`step` -1 or 1) in the focused group shown, without
741
- * wrapping and never into the other group: at either end
742
- * nothing moves, nor while a tab is still starting (it is the shown one until the panel has its
743
- * window). The focus stays where it was, and so does the zoom. */
744
- function tabStepped(state, step, { focus = state.terminal?.focus ?? "list", zoom = state.terminal?.zoom ?? false } = {}) {
810
+ /** The tab of the focused group that `pick` names, shown: `pick(count, at)` answers its place
811
+ * among the group's `count` tabs, `at` the shown one's. Never into the other group, and nothing
812
+ * moves when there is no such tab, when it is the shown one, or while a tab is still starting (it
813
+ * is the shown one until the panel has its window). The focus stays where it was, and so does
814
+ * the zoom. */
815
+ function tabPicked(state, pick, { focus = state.terminal?.focus ?? "list", zoom = state.terminal?.zoom ?? false } = {}) {
745
816
  const t = state.terminal;
746
817
  if (t === null || state.tabs.some((tab) => tab.status === "starting")) return { state, effect: null };
747
- const mine = inGroup(state, state.group), at = mine.findIndex((tab) => tab.id === t.id) + step;
748
- if (at < 0 || at >= mine.length) return { state, effect: null };
749
- return showTab(state, mine[at].id, { focus, zoom });
750
- }
818
+ const mine = inGroup(state, state.group), from = mine.findIndex((tab) => tab.id === t.id), to = pick(mine.length, from);
819
+ if (!(to >= 0 && to < mine.length) || to === from) return { state, effect: null };
820
+ return showTab(state, mine[to].id, { focus, zoom });
821
+ }
822
+ /** The tab each of these `does` shows (tabPicked): `tab-previous` and `tab-next` (the leader's Left
823
+ * and Right, the list's keys) the one before or after the shown one, without wrapping, and the
824
+ * chords' `tab-1` to `tab-8` (actions.mjs CHORD_OWN) the Nth, `tab-9` the last. */
825
+ const TAB_PICKS = Object.freeze({
826
+ __proto__: null,
827
+ "tab-previous": (count, at) => at - 1,
828
+ "tab-next": (count, at) => at + 1,
829
+ ...Object.fromEntries(Array.from({ length: 9 }, (_, i) => [`tab-${i + 1}`, i === 8 ? (count) => count - 1 : () => i])),
830
+ });
751
831
 
752
832
  /** The preflight of another machine's agent ended. Given up meanwhile (Esc, a suspend, a second
753
833
  * open): dropped. Failed: the line that says so, unless it is the person's own giving up. Else
@@ -1027,6 +1107,12 @@ function leading(state, event, keymap) {
1027
1107
  if (l !== null && l.waiting && !sameRead(l, event)) return twice(next(state, { leader: leaderAt(event.read, false) }));
1028
1108
  return { state: next(state, { leader: leaderAt(event.read, event.rest !== true) }), effect: null };
1029
1109
  }
1110
+ // A chord typed in a terminal (term/through.mjs): the leader then its key, at once. Only one
1111
+ // that is read now (chordsRead): the scanner takes no other.
1112
+ if (event.chord !== undefined) {
1113
+ if (state.terminal?.focus !== "terminal" || ![...chordsRead(state.chords, state.keyboard !== null).values()].includes(event.chord)) return { state, effect: null };
1114
+ return led(l === null ? state : next(state, { leader: null }), event.chord, event, keymap);
1115
+ }
1030
1116
  if (typeof event.key !== "string" && !("paste" in event)) return { pass: state };
1031
1117
  if (l !== null && sameRead(l, event)) return { state: l.waiting ? next(state, { leader: leaderAt(l.read, false) }) : state, effect: null };
1032
1118
  if (l !== null && l.waiting) {
@@ -1037,13 +1123,23 @@ function leading(state, event, keymap) {
1037
1123
  }
1038
1124
  const plain = l === null ? state : next(state, { leader: null });
1039
1125
  if (event.key === state.leaderKey) return { state: next(plain, { leader: leaderAt(event.read, true) }), effect: null };
1126
+ // THE PALETTE'S OWN KEYS (docs/tui.md, "The palette"): while it is open they are its, before any
1127
+ // chord (Alt+Shift+Down and Up are the chords `next` and `previous` too): inPalette reads them.
1128
+ // A chord typed in a terminal (`{ chord }`, above) never comes then: the terminal has no focus.
1129
+ if (state.palette !== null && typeof event.key === "string" && state.paletteKeys.has(event.key)) return { pass: plain };
1130
+ // THE CHORDS (docs/tui.md, "Chords"): a chord does what the leader then its key does, from
1131
+ // whatever was open: every one while the terminal confirms the kitty keyboard protocol, the
1132
+ // Alt+Shift arrows without it too (chordsRead). While the leader waits it is a key not in the
1133
+ // leader's table (above): it cancels the leader and is dropped.
1134
+ const chord = typeof event.key !== "string" ? undefined : chordsRead(state.chords, state.keyboard !== null).get(event.key);
1135
+ if (chord !== undefined) return led(plain, chord, event, keymap);
1040
1136
  return { pass: plain };
1041
1137
  }
1042
1138
 
1043
1139
  /** The leader twice (`state` is after it, its hint closed). While the open terminal has the focus,
1044
1140
  * which it keeps, the leader's own key goes to the agent: the effect `{ input: <bytes> }`, the
1045
1141
  * 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
1142
+ * 0x18 for C-x, the default; ESC o for M-o), which the loop types into the focused tab as it types what
1047
1143
  * passes through (lib/main.mjs), so an agent that reads that key still gets it. From any other
1048
1144
  * focus it does nothing else: the list is reached with the leader then Esc (LEADER). */
1049
1145
  function twice(state) {
@@ -1079,12 +1175,14 @@ function toInstances(state) {
1079
1175
  return { state: next(s, { view: "instances", back: "instances", switcher: Object.freeze({ ...s.switcher, line: null, refused: null, removing: null }) }), effect: settled.effect };
1080
1176
  }
1081
1177
 
1082
- /** What the leader's key does (LEADER's `does`), from wherever the focus was. From the terminal's
1083
- * focus the acts are the open terminal's instance's and give the focus back when their
1178
+ /** What the leader's key does (LEADER's `does`), or a chord (actions.mjs chordKeys: the same
1179
+ * `does`, and the chords' own `tab-1` to `tab-9`), from wherever the focus was. From the
1180
+ * terminal's focus the acts are the open terminal's instance's and give the focus back when their
1084
1181
  * confirmation closes, zoom zooms it in or out, and the palette gives it back when it is closed;
1085
- * Up and Down go from the open terminal's instance. Every other key first gives the focus to
1086
- * the list, then does what its action does there; the terminal's keys and the acts first go to
1087
- * the Instances view, from any view (toInstances). */
1182
+ * Up and Down go from the open terminal's instance; the tabs' (Left, Right, tab-N) keep the focus
1183
+ * where it was. Every other key first gives the focus to the list, then does what its action does
1184
+ * there; the terminal's keys and the acts first go to the Instances view, from any view
1185
+ * (toInstances). */
1088
1186
  function led(state, does, event, keymap) {
1089
1187
  const stay = { state, effect: null }, t = state.terminal;
1090
1188
  const inTerminal = t?.focus === "terminal" && state.view === "instances";
@@ -1101,13 +1199,14 @@ function led(state, does, event, keymap) {
1101
1199
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1102
1200
  }
1103
1201
  // The tabs, from any focus: the one shown next keeps the focus and the zoom it had.
1104
- if (does === "tab-previous" || does === "tab-next") {
1105
- // At either end, or while a tab starts, nothing at all: not even the settling, which would
1106
- // take the focus from the terminal.
1107
- if (tabStepped(state, does === "tab-previous" ? -1 : 1).effect === null) return stay;
1202
+ const pick = TAB_PICKS[does];
1203
+ if (pick !== undefined) {
1204
+ // At either end, with no such tab, on the shown one or while a tab starts, nothing at all: not
1205
+ // even the settling, which would take the focus from the terminal.
1206
+ if (tabPicked(state, pick).effect === null) return stay;
1108
1207
  const settledState = toInstances(state);
1109
1208
  if (settledState.state.view !== "instances") return stay;
1110
- const step = tabStepped(settledState.state, does === "tab-previous" ? -1 : 1, { focus: inTerminal ? "terminal" : "list", zoom: inTerminal && t.zoom });
1209
+ const step = tabPicked(settledState.state, pick, { focus: inTerminal ? "terminal" : "list", zoom: inTerminal && t.zoom });
1111
1210
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1112
1211
  }
1113
1212
  // The split's keys, from any focus: nothing at all when they do not apply (splitRefused).
@@ -1138,7 +1237,8 @@ function led(state, does, event, keymap) {
1138
1237
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1139
1238
  }
1140
1239
  const settledState = toList(state);
1141
- const { key, text, ...rest } = event;
1240
+ // The action alone: neither the key nor a chord that ran it is read again.
1241
+ const { key, text, chord, ...rest } = event;
1142
1242
  const step = reduced(settledState.state, { ...rest, action: does }, keymap);
1143
1243
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1144
1244
  }
@@ -1184,9 +1284,12 @@ function paletteClosed(state) {
1184
1284
  /** The keys that move the palette's selection: named keys only, so every letter is the query's. */
1185
1285
  const PALETTE_MOVES = Object.freeze({ up: "up", down: "down", pageup: "page-up", pagedown: "page-down" });
1186
1286
  /** A key or a paste while the palette is open. Text and a paste's first line go to the query,
1187
- * Backspace takes a grapheme off it, Up and Down (and PageUp, PageDown) move among its rows,
1188
- * Enter runs the selected row, Esc (or its own key again) closes it; quit, suspend and redraw keep
1189
- * their actions. Every other key does nothing. */
1287
+ * Backspace takes a grapheme off it, Up and Down (and PageUp, PageDown) move among its rows that
1288
+ * can be selected (a group's label row is passed over), its own keys (`paletteKeys`, read before
1289
+ * every other key, a key a tui.json binds to an action too) to the first row of the next group or
1290
+ * of the one before, wrapping (model.mjs paletteStep), Enter runs the selected row, Esc (or its
1291
+ * own key again) closes it; quit, suspend and redraw keep their actions. Every other key does
1292
+ * nothing. */
1190
1293
  function inPalette(state, event, keymap) {
1191
1294
  const p = state.palette, stay = { state, effect: null };
1192
1295
  const put = (changes) => next(state, { palette: Object.freeze({ ...p, ...changes }) });
@@ -1195,10 +1298,12 @@ function inPalette(state, event, keymap) {
1195
1298
  if (typeof event.text === "string") return query(typed(p.query, event.text, { key: true }));
1196
1299
  const action = keymap.get(event.key);
1197
1300
  if (event.key === "backspace") return query([...GRAPHEMES.segment(p.query)].map((g) => g.segment).slice(0, -1).join(""));
1301
+ const group = state.paletteKeys.get(event.key);
1302
+ if (group !== undefined) { const to = paletteStep(paletteItems(state), group); return to === null ? stay : { state: put({ selected: to }), effect: null }; }
1198
1303
  if (event.key === "escape" || action === "close" || action === "palette") return { state: paletteClosed(state), effect: null };
1199
1304
  if (action === "quit" || action === "suspend" || action === "redraw") return { state, effect: action };
1200
1305
  const list = paletteItems(state);
1201
- const keys = list.items.map((item) => item.key);
1306
+ const keys = list.items.filter((item) => item.kind !== "group").map((item) => item.key);
1202
1307
  if (Object.hasOwn(PALETTE_MOVES, event.key)) {
1203
1308
  if (!keys.length) return stay;
1204
1309
  const page = Math.max(1, (Number.isInteger(event.page) ? event.page : 1) - 1);
@@ -1247,6 +1352,8 @@ function reduced(state, event, keymap) {
1247
1352
  if (lead.pass === undefined) return lead;
1248
1353
  state = lead.pass;
1249
1354
  const stay = { state, effect: null };
1355
+ // The terminal confirmed the kitty keyboard protocol (lib/main.mjs): the chords are read from now on.
1356
+ if (event.keyboard !== undefined) return { state: next(state, { keyboard: event.keyboard }), effect: null };
1250
1357
  if (event.acted !== undefined) return acted(state, event.acted);
1251
1358
  if (event.prepared !== undefined) return prepared(state, event.prepared);
1252
1359
  if (event.given !== undefined) return state.opening?.phase === "preflight" ? { state: next(state, { opening: null }), effect: null } : stay;
@@ -1265,6 +1372,8 @@ function reduced(state, event, keymap) {
1265
1372
  // Held while nothing may draw such a line (the switcher, the help): it is said once a view that does is shown.
1266
1373
  if (event.notListed !== undefined) return { state: next(state, { notice: Object.freeze({ said: LIST_WORDS.notAdded(event.notListed?.message ?? ""), under: Object.freeze([]) }) }), effect: null };
1267
1374
  if (event.admitted !== undefined) return { state: admitted(state, event), effect: { refresh: { live: true } } };
1375
+ if (event.joined !== undefined) return joinedHeard(state, { ...event.joined, at: event.at });
1376
+ if (event.identity !== undefined) return identityHeard(state, event.identity);
1268
1377
  if (event.refused !== undefined) return { state: next(state, { switcher: Object.freeze({ ...state.switcher, refused: event.refused }) }), effect: null };
1269
1378
  if (event.souls !== undefined) return soulsHeard(state, event.souls);
1270
1379
  if (event.capabilities !== undefined) return capabilitiesHeard(state, event.capabilities);
@@ -1304,9 +1413,9 @@ function reduced(state, event, keymap) {
1304
1413
  case "quit": case "suspend": case "redraw": return { state, effect: action };
1305
1414
  // In the switcher this computer's deployments list is read again too.
1306
1415
  // In the Souls view it reads the souls again, and nothing else; in the Capabilities view, the capabilities.
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 } : {}) } };
1416
+ 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, identify: true } : {}) } };
1308
1417
  case "help": return { state: next(state, state.view === "help" ? { view: state.back } : { view: "help", back: state.view, helpTop: 0 }), effect: null };
1309
- case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { list: true } };
1418
+ case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { list: true, identify: true } };
1310
1419
  case "palette": return { state: paletteOpened(state, event, "list"), effect: null };
1311
1420
  // Souls and Capabilities are views of this machine, whatever workspace is open, or none.
1312
1421
  case "souls": return soulsShown(state);
@@ -1338,7 +1447,7 @@ function reduced(state, event, keymap) {
1338
1447
  case "filter": return { state: rehomed(roster(state), next(state, { focus: "list", filter: Object.freeze({ editing: true, query: state.filter.query }) })), effect: null };
1339
1448
  case "open": return at < 0 ? stay : openAgent(state, r.items[at].row);
1340
1449
  case "zoom": case "close-terminal": return terminalKey(state, action);
1341
- case "tab-previous": case "tab-next": return tabStepped(state, action === "tab-previous" ? -1 : 1);
1450
+ case "tab-previous": case "tab-next": return tabPicked(state, TAB_PICKS[action]);
1342
1451
  case "split-right": case "split-down": case "group-next": case "tab-move": case "group-close": {
1343
1452
  const refused = splitRefused(state, action, event.panel);
1344
1453
  return refused === true ? { state, effect: null } : refused !== null ? { state: next(state, { outcome: refused }), effect: null } : splitKey(state, action, false);