@awebai/oats 0.57.1 → 0.59.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 (61) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +2 -1
  3. package/docs/desktop-cli-api.md +105 -17
  4. package/docs/desktop.md +30 -3
  5. package/docs/execution-targets.md +15 -0
  6. package/docs/implementation.md +2 -0
  7. package/docs/integrations.md +2 -2
  8. package/docs/knowledge.md +4 -4
  9. package/docs/official-catalog.md +4 -4
  10. package/docs/packages.md +14 -14
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/release-notes/v0.59.0.md +288 -0
  13. package/docs/servers.md +4 -1
  14. package/docs/souls-and-instances.md +30 -0
  15. package/docs/tui.md +653 -117
  16. package/docs/workspaces.md +2 -2
  17. package/lib/core.mjs +227 -46
  18. package/lib/read-ahead-worker.mjs +119 -0
  19. package/lib/read-ahead.mjs +115 -0
  20. package/lib/retire-state.mjs +33 -0
  21. package/lib/servers.mjs +9 -1
  22. package/lib/session-input.mjs +14 -4
  23. package/package-catalog.json +3 -3
  24. package/package.json +1 -1
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/deployment-data.mjs +4 -0
  27. package/packages/client/deployment-panel.mjs +3 -0
  28. package/packages/client/instance-acts.mjs +23 -8
  29. package/packages/client/instance-presentation.mjs +3 -2
  30. package/packages/client/instance-tree.mjs +84 -39
  31. package/packages/client/lifecycle-confirmation.mjs +9 -3
  32. package/packages/client/panel-views.mjs +1 -1
  33. package/packages/client/remote-roster.mjs +4 -1
  34. package/packages/client/retire-in-flight.mjs +65 -0
  35. package/packages/client/retire-state.mjs +30 -0
  36. package/packages/client/spawn-apply-cli.mjs +8 -2
  37. package/packages/client/spawn-apply.mjs +20 -7
  38. package/packages/client/spawn-preview-cli.mjs +2 -1
  39. package/packages/client/spawn-preview.mjs +30 -18
  40. package/packages/record/lib/directory-identity.mjs +14 -0
  41. package/packages/record/lib/native-history.mjs +6 -5
  42. package/packages/tui/README.md +23 -10
  43. package/packages/tui/lib/actions.mjs +63 -5
  44. package/packages/tui/lib/client.mjs +12 -1
  45. package/packages/tui/lib/config.mjs +7 -2
  46. package/packages/tui/lib/main.mjs +315 -82
  47. package/packages/tui/lib/model.mjs +523 -56
  48. package/packages/tui/lib/panel.mjs +519 -144
  49. package/packages/tui/lib/read.mjs +52 -26
  50. package/packages/tui/lib/store.mjs +908 -65
  51. package/packages/tui/lib/term/keys.mjs +9 -2
  52. package/packages/tui/lib/term/text.mjs +4 -0
  53. package/packages/tui/lib/term/through.mjs +12 -1
  54. package/packages/tui/lib/views/frame.mjs +394 -95
  55. package/packages/tui/lib/views/help.mjs +54 -13
  56. package/packages/tui/lib/views/instances.mjs +43 -25
  57. package/packages/tui/lib/views/palette.mjs +61 -0
  58. package/packages/tui/lib/views/souls.mjs +268 -0
  59. package/packages/tui/lib/views/spawn.mjs +299 -0
  60. package/packages/tui/lib/views/split.mjs +29 -0
  61. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -8,16 +8,19 @@
8
8
  import {
9
9
  TERMS, panelData, displayLine, DETAIL_WITHHELD, originLead, instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree,
10
10
  hasInstanceChildren, heldHome, rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts,
11
- waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText, instanceActs,
11
+ waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText, instanceActs, rowReason,
12
12
  identityMemory, viewModel, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath,
13
13
  openAct, deployments as heldDeployments, attachExit, preflightFailure, kernelLines,
14
- startGate, launchFlagIgnored, flagIgnoredNotice, retainedStartMessage,
14
+ startGate, launchFlagIgnored, flagIgnoredNotice, retainedStartMessage, retiringRows, soulRows, soulFacts, spawnRefusal,
15
+ defaultSpawnChoices, spawnProblem, outcomeWords, previewFacts, deploymentLabel,
15
16
  } from "./client.mjs";
16
- import { shownLines } from "./term/text.mjs";
17
+ import { LEADER, keyLabel } from "./actions.mjs";
18
+ import { ownEllipsis, shownLines } from "./term/text.mjs";
17
19
  import { textWidth } from "./term/width.mjs";
18
20
  import { windowOf } from "./views/scroll.mjs";
21
+ import { SOUL_COLOURS } from "./views/souls.mjs";
19
22
 
20
- /** The widest the state column of the list may be, in cells. */
23
+ /** The widest the word column of the list may be, in cells. */
21
24
  export const WORD_MAX = 20;
22
25
  /** The most rows one sentence takes inside the list (a deployment's note, a reason). */
23
26
  const SENTENCE_ROWS = 4;
@@ -43,7 +46,8 @@ export function heldOf(state, at) {
43
46
 
44
47
  /** The panel of the view that holds `state.open`: the composition the Desktop's own panel is
45
48
  * served from (panel-views.mjs `panelData`), so nothing of it is put together by hand here.
46
- * Null while nothing is open (a run started outside a deployment, before a pick). */
49
+ * Null while nothing is open (a run started outside a deployment, before a pick). Its rows are
50
+ * as read: this run's retires in flight are put on them by `build` alone. */
47
51
  export function panelOf(state, at) {
48
52
  return state.open === null ? null : panelData(heldOf(state, at), state.open, TERMS);
49
53
  }
@@ -56,18 +60,38 @@ export function clockTime(iso) {
56
60
  return text(iso) && Number.isFinite(at.getTime()) ? `${pad(at.getHours())}:${pad(at.getMinutes())}:${pad(at.getSeconds())}` : null;
57
61
  }
58
62
 
63
+ /** The deployments of other machines whose rows the last roster outcome read (their group's probe
64
+ * answered), by the ids the shared `deployments` gives them, which a row's `deployment.id` carries:
65
+ * what a roster outcome covers of this run's retires in flight (lib/main.mjs). */
66
+ export function reachedMachines(state, at) {
67
+ return new Set(heldDeployments(heldOf(state, at)).filter((w) => w.remote && w.group?.probe?.ok === true).map((w) => w.id));
68
+ }
69
+
59
70
  /** A row's state in a word: the one the kernel or the collector reported on the row, else the
60
71
  * shared word for what is known of it (running, stopped, unknown). A row kept from a machine
61
72
  * that was not reached (the shared home marks it) still carries the word of its last report,
62
73
  * which is not its state now: it gets the shared word, so nothing reads as stopped, or as
63
74
  * running, that is only not reached. */
64
75
  const stateWord = (row) => (text(row.runtimeState) && row.serverUnreached !== true ? row.runtimeState : runtimeState(row));
65
- /** What a list row shows at its right edge: a held home's state, the harness of a running
66
- * instance, else its state. */
67
- function wordOf(row) {
76
+ /** The word a list row shows beside its name, or null: only what its mark cannot say. That is a
77
+ * held home's state (Retiring… while a retire runs, or this run's own is in flight), else the
78
+ * shared label of the reason the row can't be reached or opened (remote-address.mjs rowReason:
79
+ * `gone from <machine>`, `<machine> not reached`, `state unknown`, …). A row that runs, is
80
+ * stopped, or keeps a shell has no word: its mark says it, and its harness is in the detail. */
81
+ function wordOf(row, ascii) {
82
+ const held = heldHome(row);
83
+ return held ? ownEllipsis(held.state, ascii) : rowReason(row)?.label ?? null;
84
+ }
85
+ /** The detail's state: the list's word when it is a held home's state or the label of a reason
86
+ * the row can't be reached (a row gone from its machine reads `gone from <machine>`, not
87
+ * `unknown`); else the word the kernel or the collector reported, else the shared word. The
88
+ * reason that says only that the state is not known gives way to the kernel's own word for it
89
+ * (`unreachable`), which says more. */
90
+ function detailState(row, ascii) {
68
91
  const held = heldHome(row);
69
- if (held) return held.state;
70
- return row.running === true && text(row.harness) ? row.harness : stateWord(row);
92
+ if (held) return ownEllipsis(held.state, ascii);
93
+ const reason = rowReason(row);
94
+ return reason && reason.key !== "unknown" ? reason.label : stateWord(row);
71
95
  }
72
96
  /** Which mark a row carries: the shared word, `held` for a home the kernel holds, and `shell`
73
97
  * for a stopped instance whose terminal still has a shell in it. */
@@ -77,8 +101,10 @@ function markOf(row) {
77
101
  return word === "stopped" && row.runtimeState === "shell" ? "shell" : word;
78
102
  }
79
103
 
80
- /** The group of instances that are related to no other, as the shared grouping names it. */
81
- const SINGLES = "independent";
104
+ /** The key prefix of each run of instances related to no other, as the shared grouping names it
105
+ * (`independent:<id>`). Read by key, not by label: a cluster whose root is named `independent` has that
106
+ * label too, and its key is `cluster:<n>:independent`. */
107
+ const SINGLES = "independent:";
82
108
 
83
109
  /** Everything of a state that does not depend on a width: the panel, the rows as the shared
84
110
  * grouping orders them, the headings, and what stands after the sections. */
@@ -87,31 +113,57 @@ function build(state, at) {
87
113
  // No view holds what was open (a machine that is no longer listed): the store shows the
88
114
  // switcher for it; nothing is drawn from this answer.
89
115
  const gone = panel !== null && !panel.workspace;
90
- const instances = panel?.instances ?? [], deployments = panel?.deployments ?? [];
116
+ // A row whose retire this run sent and has not read since reads as retiring (#1247): every answer
117
+ // below, the acts included, is made from these rows.
118
+ const instances = retiringRows(panel?.instances ?? [], state.retiring), deployments = panel?.deployments ?? [];
91
119
  const multi = isMultiDeployment(deployments);
92
- const query = state.filter.query, filtering = query.trim() !== "";
120
+ // The filter: the text typed after `/`, or the exact soul filter the Souls view's `i` sets
121
+ // (`soul`: the names an instance's soul may carry), matched by the shared walk all the same.
122
+ const query = state.filter.query, soul = state.filter.soul ?? null, filtering = query.trim() !== "" || soul !== null;
93
123
  // The section (deployment) each row is drawn in, read from the shared split itself: the
94
124
  // sections of all rows. A collapse hides, and rolls up, only rows of its own section, as in the
95
125
  // Desktop: a parent's name can resolve to a row of another deployment of the view.
96
- const sectionOf = new Map();
97
- for (const part of rosterSections(instances, instances, deployments, TERMS)) for (const group of part.groups) for (const cluster of group.clusters) for (const row of cluster.instances) sectionOf.set(instanceId(row), part.deployment?.id ?? null);
126
+ // `ordered`: every row in that order, whatever is filtered or folded (the palette's).
127
+ const sectionOf = new Map(), ordered = [];
128
+ for (const part of rosterSections(instances, instances, deployments, TERMS)) for (const group of part.groups) for (const cluster of group.clusters) for (const row of cluster.instances) { sectionOf.set(instanceId(row), part.deployment?.id ?? null); ordered.push(row); }
98
129
  const section = (row) => sectionOf.get(instanceId(row)) ?? null;
99
- const matched = filterInstanceTree(instances, query);
130
+ const matched = soul !== null ? filterInstanceTree(instances, soul.name, (row) => soul.names.includes(row.agent)) : filterInstanceTree(instances, query);
100
131
  const visible = matched.filter((i) => instanceVisibleInTree(i, instances, state.collapsed, state.open, filtering, { section }));
101
132
  const sections = rosterSections(instances, visible, deployments, TERMS);
133
+ // How many instances each collapse folds away under its row: every descendant of the row in its
134
+ // own section, as the shared walk finds them when it is asked with that collapse alone (so a
135
+ // fold further down hides none of them from the count). A filter folds nothing away.
136
+ const folded = new Map();
137
+ if (!filtering) for (const row of visible) {
138
+ const key = collapseKey(state.open, instanceId(row));
139
+ if (!state.collapsed.has(key)) continue;
140
+ const alone = new Set([key]);
141
+ folded.set(instanceId(row), instances.filter((other) => !instanceVisibleInTree(other, instances, alone, state.open, false, { section })).length);
142
+ }
102
143
  const stale = (row) => rowStale(row, deployments);
144
+ const primary = primaryDeployment(deployments), said = deploymentState(primary);
145
+ const live = primary !== null && said.key === "live";
146
+ // The time of the read the screen shows: the cycle's own (`generatedAt`), never
147
+ // `observedAt`, which is when the kernel last looked at the workspace's remotes and is up
148
+ // to a minute older on a read in the background. Nothing drawn here comes from the remotes.
149
+ // In a view whose primary is a machine it is the time of the last roster read (heldOf).
150
+ const readAt = live ? clockTime(panel.generatedAt) : null;
103
151
 
104
152
  // The list, top to bottom, before any width. A section that has a label (a view of two or more
105
153
  // deployments) starts with its heading and the deployment's note; then the groups in the order
106
- // given, every cluster's members in order, with one gap before the group of single instances
107
- // when rows of the section came before it.
154
+ // given, every cluster's members in order, with one gap at every boundary between a run of single
155
+ // instances and a cluster, both ways (#1262).
108
156
  const parts = [], rows = [];
109
157
  const heading = (deployment, label, path = null) => {
110
- const said = deploymentState(deployment), live = said.key === "live";
158
+ const its = deploymentState(deployment), up = its.key === "live";
159
+ // A machine's rows are what it reported at the last roster read: that time stands on its
160
+ // heading only when the header's time is another, so the heading of a machine read with
161
+ // this one is its name alone. A deployment that is not live has its state and short reason
162
+ // in the shared words instead, and no time.
163
+ const read = up && deployment.local === false ? clockTime(state.rosterAt) : null;
111
164
  return {
112
- kind: "heading", label, path, state: live ? null : said.text, short: live || !text(deployment.short) ? null : deployment.short,
113
- // A machine's rows are what it reported at the last roster read.
114
- readAt: live && deployment.local === false ? clockTime(state.rosterAt) : null,
165
+ kind: "heading", label, path, state: up ? null : its.text, short: up || !text(deployment.short) ? null : deployment.short,
166
+ readAt: read !== readAt ? read : null,
115
167
  };
116
168
  };
117
169
  for (const part of sections) {
@@ -119,34 +171,35 @@ function build(state, at) {
119
171
  parts.push(heading(part.deployment, part.label));
120
172
  if (text(part.deployment.note)) parts.push({ kind: "sentence", value: part.deployment.note });
121
173
  }
122
- let drawn = 0;
174
+ let previous = null; // whether the group drawn last was a run of single instances
123
175
  for (const group of part.groups) {
124
- if (group.key === SINGLES && drawn) parts.push({ kind: "gap" });
176
+ // A gap at every boundary between a run of single instances and a cluster, both ways (#1262).
177
+ const singles = group.key.startsWith(SINGLES);
178
+ if (previous !== null && singles !== previous) parts.push({ kind: "gap" });
179
+ previous = singles;
125
180
  for (const cluster of group.clusters) for (const row of cluster.instances) {
126
181
  const item = { kind: "row", row, id: instanceId(row), depth: Number.isInteger(row.depth) ? row.depth : 0 };
127
- parts.push(item); rows.push(item); drawn++;
182
+ parts.push(item); rows.push(item);
128
183
  }
129
184
  }
130
185
  }
131
186
  // A deployment of the view that is not live and has no row is in no section: it is named
132
187
  // after them, with its state, and its reason on rows of its own.
133
188
  if (multi) for (const deployment of deployments) {
134
- const said = deploymentState(deployment);
135
- if (said.key === "live" || sections.some((part) => part.deployment?.id === deployment.id)) continue;
189
+ const its = deploymentState(deployment);
190
+ if (its.key === "live" || sections.some((part) => part.deployment?.id === deployment.id)) continue;
136
191
  parts.push(heading(deployment, deployment.machine, deployment.label));
137
- if (text(said.detail)) parts.push({ kind: "sentence", value: said.detail });
192
+ if (text(its.detail)) parts.push({ kind: "sentence", value: its.detail });
138
193
  if (text(deployment.note)) parts.push({ kind: "sentence", value: deployment.note });
139
194
  }
140
195
  // The roster read failed and no answer has arrived yet: there is no machine to say it.
141
196
  // It is about no row above it: an empty row sets it apart when something stands there.
142
197
  if (state.remote.rosterFailure !== null) parts.push(...(parts.length ? [{ kind: "gap" }] : []), { kind: "own", words: ROSTER_FAILED }, { kind: "sentence", value: state.remote.rosterFailure });
143
198
 
144
- const primary = primaryDeployment(deployments), said = deploymentState(primary);
145
199
  // The entry of this machine's deployment, when the view's primary is one: only it is ever
146
200
  // pending, withholds homes, or holds nothing after a failed read. A machine's panel has none.
147
201
  const status = panel?.deployment?.status ?? null;
148
202
  const local = panel !== null && !!panel.deployment;
149
- const live = primary !== null && said.key === "live";
150
203
  const counted = runtimeCounts(instances);
151
204
  const waiting = instances.filter((row) => waitingClaim(row, { stale: stale(row) })).length;
152
205
  const withheld = Array.isArray(panel?.deployment?.withheld) ? panel.deployment.withheld.length : 0;
@@ -158,7 +211,7 @@ function build(state, at) {
158
211
  // observed, nor for a machine that is not live and has no row kept. Each has only its reason.
159
212
  const observed = panel !== null && !gone && (local ? status === "observed" : live || instances.length > 0);
160
213
  return {
161
- panel, gone, instances, deployments, multi, parts, rows, filtering, stale, section, live, observed,
214
+ panel, gone, instances, ordered, deployments, multi, parts, rows, filtering, stale, section, live, observed, folded,
162
215
  below: waitingRollup(instances, state.collapsed, state.open, { filtering, stale, section }),
163
216
  status,
164
217
  workspace: text(panel?.workspace?.name) ? panel.workspace.name : "",
@@ -173,11 +226,7 @@ function build(state, at) {
173
226
  ...Object.entries(counted).slice(1).map(([word, n]) => ({ n, word, shared: true })),
174
227
  { n: withheld, word: "withheld", shared: false },
175
228
  ].filter((count) => count.n > 0),
176
- // The time of the read the screen shows: the cycle's own (`generatedAt`), never
177
- // `observedAt`, which is when the kernel last looked at the workspace's remotes and is up
178
- // to a minute older on a read in the background. Nothing drawn here comes from the remotes.
179
- // In a view whose primary is a machine it is the time of the last roster read (heldOf).
180
- readAt: live ? clockTime(panel.generatedAt) : null,
229
+ readAt,
181
230
  // A deployment that is not live says so above the list, with why. Before the first answer
182
231
  // the list holds the TUI's own line instead: the shared sentence for that moment names an
183
232
  // installed CLI, and the TUI runs its own kernel.
@@ -193,7 +242,7 @@ function build(state, at) {
193
242
  empty: status === "pending" ? "reading" : !observed ? null : !instances.length ? "none" : !rows.length ? "nomatch" : null,
194
243
  // As wide as the widest word among all the rows of the list, so the column does not move
195
244
  // while the list scrolls.
196
- wordWidth: Math.min(WORD_MAX, rows.reduce((widest, { row }) => Math.max(widest, textWidth(displayLine(wordOf(row)) ?? "")), 0)),
245
+ wordWidth: Math.min(WORD_MAX, rows.reduce((widest, { row }) => Math.max(widest, textWidth(displayLine(wordOf(row, state.ascii)) ?? "")), 0)),
197
246
  };
198
247
  }
199
248
 
@@ -224,14 +273,14 @@ function flatten(base, cols, ascii) {
224
273
  * from read it again without asking the shared home again (its grouping walks the whole roster
225
274
  * for each row). The state's values are never changed in place, so their identity says whether
226
275
  * they changed. The flattening for the last width asked is kept beside it. */
227
- const MADE_FROM = ["entries", "remote", "memory", "notes", "rosterAt", "collecting", "ctxs", "open", "collapsed", "cli", "home"];
276
+ const MADE_FROM = ["entries", "remote", "memory", "notes", "rosterAt", "collecting", "ctxs", "open", "collapsed", "cli", "home", "retiring", "ascii"];
228
277
  let kept = null;
229
278
  /** The roster of a state: the rows in drawn order and what the header says, for a list pane
230
279
  * `cols` wide. Only `items` and `index` depend on the width; `rows`, the instances in drawn
231
280
  * order, do not. `at` stamps a machine's panel before any roster outcome was taken, which
232
281
  * never shows; it is passed on. */
233
282
  export function roster(state, at = new Date(0).toISOString(), cols = ANY_WIDTH) {
234
- const same = kept && MADE_FROM.every((name) => kept.state[name] === state[name]) && kept.state.filter.query === state.filter.query;
283
+ const same = kept && MADE_FROM.every((name) => kept.state[name] === state[name]) && kept.state.filter.query === state.filter.query && kept.state.filter.soul === state.filter.soul;
235
284
  if (!same) kept = { state, base: build(state, at), flat: null };
236
285
  if (!kept.flat || kept.flat.cols !== cols || kept.flat.ascii !== state.ascii) kept.flat = { cols, ascii: state.ascii, ...flatten(kept.base, cols, state.ascii) };
237
286
  return { ...kept.base, items: kept.flat.items, index: kept.flat.index };
@@ -244,13 +293,18 @@ export function disclosure(state, r, item) {
244
293
  return !r.filtering && state.collapsed.has(collapseKey(state.open, item.id)) ? "closed" : "open";
245
294
  }
246
295
 
296
+ /** One row of the list: its mark, its name, the word its mark cannot say (or null), whether it
297
+ * waits, and on a folded row only, how many instances are folded away under it (`folded`) and how
298
+ * many of those wait (`below`). A row that is not folded says nothing of its children: they
299
+ * stand under it, indented. */
247
300
  function listRow(state, r, item) {
248
- const fold = disclosure(state, r, item);
301
+ const closed = disclosure(state, r, item) === "closed";
249
302
  return {
250
303
  id: item.id, name: item.row.instance, depth: item.depth, selected: item.id === state.selected,
251
- disclosure: fold, mark: markOf(item.row), word: wordOf(item.row),
304
+ mark: markOf(item.row), word: wordOf(item.row, state.ascii),
252
305
  waiting: waitingClaim(item.row, { stale: r.stale(item.row) }) !== null,
253
- below: fold === "closed" ? r.below.get(item.id)?.length ?? 0 : 0,
306
+ folded: closed ? r.folded.get(item.id) ?? 0 : 0,
307
+ below: closed ? r.below.get(item.id)?.length ?? 0 : 0,
254
308
  };
255
309
  }
256
310
 
@@ -288,11 +342,35 @@ export const OPEN_WORDS = Object.freeze({
288
342
  notRunning: (name) => [{ shown: name }, { own: " is not running, so it has no terminal to open." }],
289
343
  stateUnknown: (name) => [{ own: "Whether " }, { shown: name }, { own: " runs is not known, so it is not opened." }],
290
344
  });
291
- /** The line of a view that is not in this version (its key: 2, 3), with what to run instead: the
292
- * help's commands (views/help.mjs VIEWS), in the TUI's own words. */
345
+ /** The tabs' own words (docs/tui.md, "Tabs"): at the cap, how many are open and the leader's key
346
+ * that closes the shown one. */
347
+ const LEADER_CLOSE = LEADER.find((entry) => entry.does === "close-terminal").keys[0];
348
+ export const TAB_WORDS = Object.freeze({
349
+ full: (limit, leader) => [{ own: `${limit} terminals are open; close one with ` }, { own: `${leader} ${keyLabel(LEADER_CLOSE)}`, whole: true }, { own: "." }],
350
+ });
351
+ /** The lines of a split that is not made (docs/tui.md, "Splits"): a second split, and a panel too
352
+ * small for two groups (`min` views/split.mjs SPLIT_MIN). */
353
+ export const SPLIT_WORDS = Object.freeze({
354
+ twice: () => [{ own: "The panel has two groups already." }],
355
+ small: (dir, min) => [{ own: dir === "right" ? `No room to split side by side: each group needs ${min.cols} columns.` : `No room to split one above the other: each group needs ${min.rows} rows.` }],
356
+ });
357
+ /** The groups of the panel as the frame draws them (docs/tui.md, "Splits"): one, or two with a
358
+ * split, each `{ tabs, shown }`: its tabs in the strip's order (`{ id, name, machine, routed,
359
+ * shown, activity }`, `machine` only for another machine's) and its shown tab's id, or null for
360
+ * an empty group. */
361
+ function groupsOf(state) {
362
+ return Array.from({ length: state.split === null ? 1 : 2 }, (_, g) => {
363
+ const shown = g === state.group ? state.terminal?.id ?? null : state.aside;
364
+ const tabs = state.tabs.filter((tab) => tab.group === g).map((tab) => ({ id: tab.id, name: tab.name, machine: tab.routed ? tab.machine : null, routed: tab.routed, shown: tab.id === shown, activity: tab.activity }));
365
+ return { tabs, shown };
366
+ });
367
+ }
368
+ /** The body of a view of this machine that is not in this version (Capabilities): what it will
369
+ * hold, and what to run until then, the help's commands (views/help.mjs VIEWS), in the TUI's own
370
+ * words; each command is whole, never broken over two rows. */
371
+ const command = (text) => Object.freeze({ own: `\`${text}\``, whole: true });
293
372
  export const NOT_BUILT = Object.freeze({
294
- souls: Object.freeze({ said: Object.freeze([{ own: "Souls are not in this version: `oats souls` lists them, and `oats spawn <soul>` makes an instance of one." }]), under: Object.freeze([]) }),
295
- capabilities: Object.freeze({ said: Object.freeze([{ own: "Capabilities are not in this version: `oats capabilities` lists them." }]), under: Object.freeze([]) }),
373
+ capabilities: Object.freeze({ said: Object.freeze([{ own: "This view will list the capabilities this machine has. It is not in this version: " }, command("oats capabilities"), { own: " lists them." }]), under: Object.freeze([]) }),
296
374
  });
297
375
  /** A sentence from outside (a reason of the shared home's, the preflight table's), as a text
298
376
  * under the line: drawn as the detail draws a reason, wrapped on the reason's rows, never as one
@@ -384,7 +462,7 @@ function detailOf(state, r, item, now, acts) {
384
462
  const said = of ? deploymentState(of) : null;
385
463
  if (said && said.key !== "live") add("", said.detail, "wrap");
386
464
  }
387
- add("state", heldHome(row)?.state ?? stateWord(row)); // the word of its list row, harness apart
465
+ add("state", detailState(row, state.ascii));
388
466
  const held = acts.blocked ?? acts.limited;
389
467
  // The row's own text stands under its state, in the form that says who made it. Who made it is
390
468
  // the shared home's to say, in two ways, and the TUI writes no word and no sentence of its own
@@ -399,10 +477,12 @@ function detailOf(state, r, item, now, acts) {
399
477
  // in front never change the answer; a closing quotation mark can, for a text that ends in a
400
478
  // secret's name and its sign, and that text is then withheld.)
401
479
  add("", rowText(row, acts), "wrap");
402
- // What holds the row, when that is a sentence of the shared home's and not the row's text: a
403
- // reason with an `origin` is the row's text, and so is one whose sentence is that text. Either
404
- // stands once, under the state.
405
- if (held && held.origin === undefined && held.sentence !== row.runtimeError) add("held", held.sentence, "wrap");
480
+ // What holds the row, when that is not the row's text, said as `spoken` says it. A held home's
481
+ // reason (code `held`) is never the row's text: the shared home's sentence, or a failed retire's
482
+ // words of the kernel's (#1247), whose speaker `spoken` names. Any other reason is the row's text
483
+ // when it carries an `origin`, or when its sentence is that text: either stands once, under the state.
484
+ const own = held && (held.code === "held" || (held.origin === undefined && held.sentence !== row.runtimeError));
485
+ if (own) add("held", reasonSpoken(held), "wrap");
406
486
  const claim = waitingClaim(row, { stale: r.stale(row) });
407
487
  if (claim) {
408
488
  add("needs", `${waitingLabel(claim)}, ${waitedText(claim.since, now)}`);
@@ -458,6 +538,101 @@ export function switcher(state, at = new Date(0).toISOString()) {
458
538
  };
459
539
  }
460
540
 
541
+ /** The house fuzzy matcher of the Desktop's palette, the same function
542
+ * (packages/desktop/renderer/overlay-picker.mjs subsequenceScore): the TUI cannot import the
543
+ * Desktop's renderer, and test/tui-palette.test.mjs holds the two to the same answers. Lower is
544
+ * better, null is no match, and a prefix match gets a strong (negative) bonus. */
545
+ export function subsequenceScore(text, query) {
546
+ const t = String(text).toLowerCase();
547
+ const s = String(query).toLowerCase();
548
+ let ti = 0, gaps = 0;
549
+ for (const ch of s) {
550
+ const found = t.indexOf(ch, ti);
551
+ if (found < 0) return null;
552
+ gaps += found - ti; ti = found + 1;
553
+ }
554
+ return gaps + (t.startsWith(s) ? -100 : 0);
555
+ }
556
+
557
+ /** The palette's views and commands, each a row's label and the action it runs. */
558
+ const PALETTE_VIEWS = Object.freeze([["instances", "Instances"], ["souls", "Souls"], ["capabilities", "Capabilities"]]);
559
+ const PALETTE_COMMANDS = Object.freeze([["spawn", "Spawn an agent"], ["workspaces", "Workspaces"], ["refresh", "Refresh"], ["help", "Help"]]);
560
+ const PALETTE_SPLIT = Object.freeze({
561
+ one: Object.freeze([["split-right", "Split right"], ["split-down", "Split down"]]),
562
+ shown: Object.freeze([["tab-move", "Move tab to the other group"]]),
563
+ empty: Object.freeze([["group-close", "Close the empty group"]]),
564
+ });
565
+ const PALETTE_ACTS = Object.freeze({ stop: "Stop", restart: "Restart", retire: "Retire", start: "Start" });
566
+
567
+ /** THE PALETTE'S ROWS (docs/tui.md, "The palette"), in this order: the instances that can be
568
+ * opened (the most recently opened in this run first, then the shared order), the souls of the
569
+ * open workspace once its catalog was read, the views, the acts
570
+ * the palette's instance offers (the open terminal's, when the palette came from its focus; else
571
+ * the selected one) and, once the catalog lists its soul, another of that soul, then spawning an
572
+ * agent, workspaces, refresh and help, and the split's that apply. With a query, each group keeps the rows the
573
+ * Desktop's subsequence score matches, the best first (a prefix first); a tie keeps that order.
574
+ * A row: `{ key, kind, label, does?, id?, name?, machine?, mark? }`; `selected` is the key the
575
+ * selection stands on (the first row when the palette's own is not listed). */
576
+ export function paletteItems(state, at = new Date(0).toISOString()) {
577
+ const p = state.palette;
578
+ if (p === null) return { items: [], selected: null };
579
+ const groups = [];
580
+ if (state.open !== null) {
581
+ const r = roster(state, at);
582
+ const recent = new Map(state.recent.map((id, i) => [id, i]));
583
+ const rank = (row) => recent.get(instanceId(row)) ?? Infinity;
584
+ const openable = r.ordered.filter((row) => openDecision(state, row, instanceActs(row)).open);
585
+ groups.push(openable.map((row, i) => ({ row, i })).sort((a, b) => rank(a.row) - rank(b.row) || a.i - b.i).map(({ row }) => {
586
+ const machine = elsewhere(row) ? row.deployment?.machine ?? row.server : null;
587
+ return { key: `instance\u0000${instanceId(row)}`, kind: "instance", label: row.instance, id: instanceId(row), name: row.instance, machine, mark: markOf(row), text: `${row.instance} ${machine ?? ""}` };
588
+ }));
589
+ }
590
+ // The souls of the open workspace, once its catalog was read (the Souls view opened): choosing
591
+ // one shows the Souls view with it selected. A palette never reads the catalog.
592
+ groups.push(soulsOf(state).all.map((row) => ({ key: `soul\u0000${row.name}`, kind: "soul", label: row.name, name: row.name, text: row.name })));
593
+ groups.push(PALETTE_VIEWS.map(([does, label]) => ({ key: `view\u0000${does}`, kind: "view", label, does, text: label })));
594
+ const id = p.from === "terminal" && state.terminal !== null ? state.terminal.id : state.selected;
595
+ const row = id === null || state.open === null ? null : roster(state, at).instances.find((each) => instanceId(each) === id) ?? null;
596
+ if (row !== null && state.opening === null) {
597
+ const acts = instanceActs(row);
598
+ const another = !elsewhere(row) && state.ctxs.includes(state.open) ? soulOfAgent(state, state.open, row.agent) : null;
599
+ groups.push([
600
+ ...ACT_VERBS.filter((verb) => actDecision(state, row, acts, verb).open)
601
+ .map((verb) => ({ key: `act\u0000${verb}`, kind: "act", label: PALETTE_ACTS[verb], does: verb, id: instanceId(row), name: row.instance, text: `${PALETTE_ACTS[verb]} ${row.instance}` })),
602
+ // Another of its soul (N), once the catalog lists that soul: the row names the soul.
603
+ ...(another ? [{ key: "act\u0000spawn-another", kind: "act", label: "Spawn another", does: "spawn-another", id: instanceId(row), name: another.name, text: `Spawn another ${another.name}` }] : []),
604
+ ]);
605
+ }
606
+ // The split's, after them, where each applies (docs/tui.md, "Splits"): a split while there is one
607
+ // group, and with two the move of the shown tab, or the close of the focused group while it is
608
+ // empty. A split there is no room for says so when it is run.
609
+ const splitting = state.tabs.length > 0 && state.opening === null && !state.tabs.some((tab) => tab.status === "starting");
610
+ const SPLIT = splitting ? (state.split === null ? PALETTE_SPLIT.one : state.terminal !== null ? PALETTE_SPLIT.shown : PALETTE_SPLIT.empty) : [];
611
+ groups.push([...PALETTE_COMMANDS, ...SPLIT].map(([does, label]) => ({ key: `command\u0000${does}`, kind: "command", label, does, text: label })));
612
+ const query = p.query.trim();
613
+ const items = groups.flatMap((group) => (query === ""
614
+ ? group
615
+ : group.map((item, i) => ({ item, i, score: subsequenceScore(item.text, query) })).filter((each) => each.score !== null).sort((a, b) => a.score - b.score || a.i - b.i).map(({ item }) => item)));
616
+ // With nothing chosen yet, the first row; but in the palette as it opens (no query), when the
617
+ // first row is the shown tab's instance (the most recent), the second instance: the palette and
618
+ // Enter go back to the terminal before it, as the Desktop's recent group does.
619
+ const first = p.query === "" && items[0]?.kind === "instance" && items[0].id === state.terminal?.id && items[1]?.kind === "instance" ? items[1] : items[0];
620
+ return { items, selected: items.some((item) => item.key === p.selected) ? p.selected : first?.key ?? null };
621
+ }
622
+ /** The palette as the view draws it, in a body `page` rows tall: its query on the first row, and
623
+ * under it the window of its rows that holds the selection (whose last row says what is cut off,
624
+ * when something is: scroll.mjs windowOf keeps it). */
625
+ function paletteView(state, page, at) {
626
+ const list = paletteItems(state, at), height = Math.max(1, page - 1);
627
+ const selected = list.items.findIndex((item) => item.key === list.selected);
628
+ const win = windowOf({ top: 0, count: list.items.length, height, keep: selected });
629
+ return {
630
+ query: state.palette.query, from: state.palette.from,
631
+ rows: list.items.slice(win.top, win.top + win.size).map((item) => ({ ...item, selected: item.key === list.selected })),
632
+ above: win.above, below: win.below, empty: list.items.length === 0,
633
+ };
634
+ }
635
+
461
636
  /** What the views draw for a state. For the Instances view, in a list pane `page` rows tall and
462
637
  * `cols` wide: the header's facts, the rows of the window with their marks, and the selected
463
638
  * instance's detail. For the switcher, in a pane `page` rows tall: the window of its rows. Only
@@ -465,12 +640,26 @@ export function switcher(state, at = new Date(0).toISOString()) {
465
640
  export function model(state, { page, now, at, cols }) {
466
641
  const r = roster(state, at, cols);
467
642
  const common = {
468
- view: state.view, focus: state.focus, ascii: state.ascii, actions: state.actions, filter: state.filter,
643
+ view: state.view, focus: state.focus, ascii: state.ascii, actions: state.actions,
644
+ // The filter of the view shown: the Souls view has one of its own.
645
+ filter: state.view === "souls" ? state.souls.filter : state.filter,
469
646
  workspace: r.workspace, machines: r.machines, here: r.here, machine: r.machine, counts: r.counts, readAt: r.readAt, notice: r.notice, note: r.note, empty: r.empty, observed: r.observed,
470
647
  detailTop: state.detailTop, helpTop: state.helpTop, open: state.open !== null,
471
- detachKey: state.detachKey, opening: state.opening, outcome: state.outcome, openable: false, actable: [],
648
+ detachKey: state.detachKey, opening: state.opening, openable: false, actable: [],
472
649
  terminal: state.terminal, onTerminal: false,
650
+ // The panel's groups (views/frame.mjs), the split and the focused group; the panel stands while
651
+ // any tab is open. `tabs` is the focused group's strip: each tab in order, the shown one marked,
652
+ // a hidden one's activity. A strip is drawn with two tabs or more; one reads as a title row.
653
+ split: state.split, group: state.group, panelOpen: state.tabs.length > 0, groups: groupsOf(state),
654
+ tabs: groupsOf(state)[state.group].tabs,
473
655
  act: state.view === "act" && state.act ? actView(state) : null,
656
+ // The leader waits for its key (the footer is its hint), and the palette, while it is open.
657
+ leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, page, at),
658
+ body: state.view === "capabilities" ? NOT_BUILT.capabilities : null,
659
+ souls: state.view === "souls" ? soulsView(state, page, at) : null,
660
+ spawn: state.spawn === null ? null : spawnView(state, page, at),
661
+ // The line above the panes: the last outcome, else a spawn under way (outcomeOf).
662
+ outcome: outcomeOf(state),
474
663
  };
475
664
  // The view under the help, or under a confirmation, decides what the header says.
476
665
  const under = state.view === "help" || state.view === "act" ? state.back : state.view;
@@ -506,8 +695,9 @@ export function model(state, { page, now, at, cols }) {
506
695
  openable: decision?.open === true && state.opening === null,
507
696
  onTerminal: row !== null && state.terminal !== null && state.terminal.id === instanceId(row),
508
697
  // The acts whose key opens a confirmation now, read from the same instanceActs answer: the
509
- // footer names them. A key not named still answers, with the line that says why.
510
- actable: row && state.opening === null ? ACT_VERBS.filter((verb) => actDecision(state, row, acts, verb).open) : [],
698
+ // footer names them. A key not named still answers, with the line that says why. A secondary
699
+ // act (Retire while a retire runs) opens on its key and is not named.
700
+ actable: row && state.opening === null ? ACT_VERBS.filter((verb) => !acts.acts.some((each) => each.verb === verb && each.secondary) && actDecision(state, row, acts, verb).open) : [],
511
701
  switcher: null,
512
702
  };
513
703
  }
@@ -696,3 +886,280 @@ export function actView(state) {
696
886
  const buttons = a.offers.map((offer) => ({ id: offer, label: buttonLabel(offer, a.verb, a.phase), focused: offer === a.focus }));
697
887
  return { title, lines, buttons, top: a.top };
698
888
  }
889
+
890
+ // ── THE SOULS VIEW (docs/tui.md, "The Souls view") ───────────────────────────────────────────────
891
+
892
+ /** The sentence of a catalog read that failed: the Desktop's own (packages/desktop/renderer/views/
893
+ * spawn.mjs catalogReasonText), copied until the shared home has it; the kernel's message in it is
894
+ * text from outside, which the view draws through the display filter. */
895
+ export function catalogFailure(reason) {
896
+ const message = typeof reason?.message === "string" && reason.message ? reason.message : "";
897
+ return message ? `Couldn't read this workspace's souls: ${message}` : "Couldn't read this workspace's souls.";
898
+ }
899
+
900
+ /** The names an instance's soul (its row's `agent`) may carry for a soul row: its name, and for a
901
+ * package soul the kernel's key and its qualified name. The exact soul filter matches these. */
902
+ export function soulNames(row) {
903
+ return [...new Set([row.name, row.key, row.qualifiedName].filter(text))];
904
+ }
905
+
906
+ /** Whether a soul row matches the Souls view's filter: its name, its description or where it comes
907
+ * from contains the text, case aside, as the Desktop's soul grid filters (views/spawn.mjs). */
908
+ const soulMatches = (row, needle) => [row.name, row.description, row.repoName].some((value) => String(value || "").toLowerCase().includes(needle));
909
+
910
+ /** The souls of the open workspace as the store and the view read them: the shared rows
911
+ * (soul-rows.mjs soulRows) of the catalog the loop holds for it, filtered by the view's own
912
+ * filter. Only a workspace of this machine has souls here (`local`). `held` is what the loop
913
+ * holds of its catalog (`{ entry, reading }`), `rows` the rows the filter keeps, `selected` the
914
+ * row the selection stands on: the store's, while it is listed, else the first. */
915
+ export function soulsOf(state) {
916
+ const { local, deployment, held, all } = catalogOf(state, state.open);
917
+ const needle = state.souls.filter.query.trim().toLowerCase();
918
+ const rows = needle ? all.filter((row) => soulMatches(row, needle)) : all;
919
+ const selected = rows.find((row) => row.name === state.souls.selected) ?? rows[0] ?? null;
920
+ return { local, deployment, held, all, rows, selected };
921
+ }
922
+
923
+ /** The souls of workspace `id` (one of this machine's, or nothing): its observed deployment, what
924
+ * the loop holds of its catalog, and the shared rows of that catalog. */
925
+ function catalogOf(state, id) {
926
+ const local = id !== null && state.ctxs.includes(id);
927
+ const entry = local ? state.entries.get(id) ?? null : null;
928
+ const deployment = entry?.deployment?.status === "observed" ? entry.deployment : null;
929
+ const held = local ? state.souls.held.get(id) ?? null : null;
930
+ const all = deployment && Array.isArray(held?.entry?.souls) ? soulRows(deployment, held.entry.souls) : [];
931
+ return { local, deployment, held, all };
932
+ }
933
+
934
+ /** The most instances the detail names; the rest are counted, `+n`. */
935
+ const INSTANCES_NAMED = 8;
936
+
937
+ /** This machine's instances of a soul in the open workspace, in the list's order: the rows of
938
+ * another machine are not counted, since the view is of this machine's souls. */
939
+ function instancesOf(state, at, row) {
940
+ const names = soulNames(row);
941
+ return roster(state, at).ordered.filter((each) => !elsewhere(each) && names.includes(each.agent));
942
+ }
943
+
944
+ /** Where a soul comes from, in one value: the member it is in, and for a package soul the package
945
+ * and its version (the shared row's `repoName` already names the package when no member does). */
946
+ function soulFrom(row) {
947
+ if (row.soulKind !== "package" || !text(row.package)) return row.repoName;
948
+ const pkg = `package ${row.package}${text(row.version) ? ` ${row.version}` : ""}`;
949
+ return row.repoName === `package ${row.package}` || !text(row.repoName) ? pkg : `${row.repoName} · ${pkg}`;
950
+ }
951
+
952
+ /** The selected soul's detail, from its row and the shared facts (soul-facts.mjs soulFacts, with
953
+ * no inspection): nothing of a soul is worded here but the labels the view puts beside them. */
954
+ function soulDetail(state, at, row) {
955
+ const facts = soulFacts(row, null, state.cli, TERMS);
956
+ const teams = Array.isArray(row.teams) && row.teams.length
957
+ ? [...row.teams].sort((a, b) => (b.default === true) - (a.default === true)).map((team) => ({ label: team.label, default: team.default === true || team.label === row.defaultTeam?.label }))
958
+ : null;
959
+ const capabilities = Array.isArray(row.capabilities) && row.capabilities.length ? row.capabilities.map((c) => c.name) : null;
960
+ const here = instancesOf(state, at, row);
961
+ return {
962
+ name: row.name, description: row.description ?? "", from: soulFrom(row), works: facts.work, refusal: facts.refusalLine,
963
+ harness: { rows: facts.rows, notes: facts.notes, problem: facts.problem },
964
+ teams, capabilities,
965
+ instances: { shown: here.slice(0, INSTANCES_NAMED).map((each) => ({ name: each.instance, mark: markOf(each) })), more: Math.max(0, here.length - INSTANCES_NAMED) },
966
+ };
967
+ }
968
+
969
+ /** What the Souls view draws, in a list pane `page` rows tall (views/souls.mjs): the state of the
970
+ * catalog, the window of its rows, and the selected soul's detail. A failed re-read keeps the
971
+ * rows it held, and says so on a heading above them, as a machine's heading says it. */
972
+ function soulsView(state, page, at) {
973
+ const s = soulsOf(state), v = state.souls;
974
+ const base = { local: s.local, failure: null, heading: null, list: [], above: 0, below: 0, focus: v.focus, filter: v.filter, detail: null, detailTop: v.detailTop };
975
+ if (!s.local) return { ...base, state: "none" };
976
+ const entry = s.held?.entry ?? null, reason = entry?.reason ?? null;
977
+ if (!Array.isArray(entry?.souls)) {
978
+ // Nothing held: the first read is in flight (or the deployment not read yet), or it failed.
979
+ return reason && !s.held.reading ? { ...base, state: "failed", failure: catalogFailure(reason) } : { ...base, state: "reading" };
980
+ }
981
+ const heading = reason ? { label: "Souls", path: null, state: null, short: catalogFailure(reason), readAt: clockTime(entry.observedAt) } : null;
982
+ const state_ = !s.all.length ? "none" : !s.rows.length ? "nomatch" : "rows";
983
+ const height = Math.max(1, page - (heading ? 1 : 0));
984
+ const at_ = s.selected ? s.rows.indexOf(s.selected) : -1;
985
+ const win = windowOf({ top: v.top, count: s.rows.length, height, keep: v.loose ? -1 : at_ });
986
+ const count = (row) => instancesOf(state, at, row).length;
987
+ return {
988
+ ...base, state: state_, heading,
989
+ list: s.rows.slice(win.top, win.top + win.size).map((row) => ({
990
+ name: row.name, color: SOUL_COLOURS[row.color] ?? null, count: count(row), refused: spawnRefusal(row, state.cli) !== null, selected: row === s.selected,
991
+ })),
992
+ above: win.above, below: win.below,
993
+ // The heading has room for little of a failed re-read's sentence: the detail holds it whole,
994
+ // as a machine's full reason stands in the detail of each of its rows.
995
+ detail: s.selected ? { ...soulDetail(state, at, s.selected), failure: heading ? heading.short : null } : null,
996
+ };
997
+ }
998
+
999
+ // ── SPAWNING (docs/tui.md, "Spawning an agent"; Spec 6-spawn) ───────────────────────────────────
1000
+
1001
+ /** A shared sentence as parts the outcome line wraps (views/frame.mjs partRows): each word is
1002
+ * text from outside, and the gaps between them are the TUI's. */
1003
+ const sentenceParts = (text) => String(text ?? "").split(/ +/).filter(Boolean).flatMap((word, i) => (i ? [{ own: " " }, { shown: word }] : [{ shown: word }]));
1004
+ /** The label of the first key the effective table gives action `id`, or the action's id. */
1005
+ const keyOf = (actions, id) => { const a = actions.find((each) => each.id === id && each.keys.length); return a ? keyLabel(a.keys[0]) : id; };
1006
+
1007
+ /** The TUI's own words around a spawn, as parts the way ACT_WORDS are. Every fact of a spawn (what
1008
+ * happened, what the preview holds, why a soul can't be spawned) is the shared home's
1009
+ * (spawn-messages.mjs, spawn-preview-facts.mjs, soul-facts.mjs): the TUI words only what follows a
1010
+ * fact (`next`, naming its own keys), and the prompt around them. */
1011
+ export const SPAWN_WORDS = Object.freeze({
1012
+ /** From the press of Enter until the outcome. */
1013
+ spawning: (name) => [{ own: "Spawning " }, { shown: name }, { own: "\u2026" }],
1014
+ checking: (name) => [{ own: "Checking the spawn of " }, { shown: name }, { own: "\u2026" }],
1015
+ /** n or N while a spawn is under way: one at a time. */
1016
+ busy: (name) => [{ own: "The spawn of " }, { shown: name }, { own: " is still under way: one spawn at a time." }],
1017
+ /** n or N on another machine's row or workspace (#855: remote spawn is out of scope here). */
1018
+ remote: () => [{ own: "Spawning on another machine is not offered here;" }, { own: " " }, command("oats spawn"), { own: " there makes one." }],
1019
+ /** N on a row whose soul the workspace's catalog does not list. */
1020
+ noSoul: (soul) => [{ own: "The soul " }, { shown: soul }, { own: " isn't in this workspace's catalog: there is nothing to spawn." }],
1021
+ });
1022
+
1023
+ /** THE TUI'S WORDS FOR WHAT FOLLOWS A SPAWN'S FACT, one entry per SPAWN_NEXT code
1024
+ * (spawn-messages.mjs): each names a key of the effective table, or an `oats` command
1025
+ * (test/tui-... pins that every code has one). `(instance, actions)` -> parts. */
1026
+ export const SPAWN_NEXT_WORDS = Object.freeze({
1027
+ "change-options": () => [{ own: "Change the choices with Tab and Enter." }],
1028
+ "review-again": () => [{ own: "Check the preview and press Enter again." }],
1029
+ "check-result": (_, actions) => [{ own: `Press ${keyOf(actions, "spawn-check")} to check before spawning again.` }],
1030
+ "update-oats": () => [{ own: "Update OATS with" }, { own: " " }, command("oats update"), { own: ", then try again." }],
1031
+ "choose-workspace": (_, actions) => [{ own: `Choose it again with ${keyOf(actions, "workspaces")}.` }],
1032
+ "sync-workspace": () => [{ own: "Run" }, { own: " " }, command("oats sync"), { own: " in the workspace, then try again." }],
1033
+ details: () => [{ own: "The details below say more." }],
1034
+ retire: (instance, actions) => [{ own: "Retire " }, { shown: instance ?? "it" }, { own: ` with ${keyOf(actions, "retire")} to finish its cleanup.` }],
1035
+ "view-schedules": () => [command("oats schedule list"), { own: " shows its schedules." }],
1036
+ "open-from-list": (_, actions) => [{ own: `Open it from the list with ${keyOf(actions, "open")}.` }],
1037
+ });
1038
+
1039
+ /** A spawn's words as the outcome line (or the prompt's) says them, `{ said, under }`: the shared
1040
+ * fact, then the TUI's words for its `next`; under them the shared `detail` (the code and the
1041
+ * kernel's message) where the next act is to read it. `words`: spawnProblem's or outcomeWords'. */
1042
+ export function spawnLine(words, instance, actions) {
1043
+ if (!words) return null;
1044
+ const next = words.next && Object.hasOwn(SPAWN_NEXT_WORDS, words.next) ? SPAWN_NEXT_WORDS[words.next](words.instance ?? instance, actions) : [];
1045
+ return { said: [...sentenceParts(words.fact), ...(next.length ? [{ own: " " }, ...next] : [])], under: words.next === "details" && words.detail ? [words.detail] : [] };
1046
+ }
1047
+
1048
+ /** The line above the panes: the last outcome; else, while a spawn is under way, what it does. */
1049
+ export function outcomeOf(state) {
1050
+ if (state.outcome !== null) return state.outcome;
1051
+ const s = state.spawning;
1052
+ return s ? { said: (s.phase === "checking" ? SPAWN_WORDS.checking : SPAWN_WORDS.spawning)(s.name), under: [] } : null;
1053
+ }
1054
+
1055
+ /** The choices a prompt asks the preview for: the shared defaults, the name typed (`--purpose`),
1056
+ * and the parent when "child of" is on. Nothing else is offered here (out of scope: harness,
1057
+ * model, work mode, teams). */
1058
+ export function spawnChoices(p) {
1059
+ return {
1060
+ ...defaultSpawnChoices(),
1061
+ ...(p.name ? { purpose: p.name } : {}),
1062
+ ...(p.child && p.anchor ? { relation: { kind: "child", anchor: { instance: p.anchor.instance, agent: p.anchor.agent, agentsRoot: p.anchor.agentsRoot, server: null } } } : {}),
1063
+ };
1064
+ }
1065
+ /** The choices as one value, to tell whether the preview on screen was read for them. */
1066
+ export const spawnChoicesKey = (p) => JSON.stringify(spawnChoices(p));
1067
+ /** The soul a preview is read for, as the shared preview selects it. */
1068
+ export const spawnSelector = (p) => ({ soul: p.soul.name, agentsRoot: p.soul.agentsRoot });
1069
+
1070
+ /** What the spawn boundaries admit a request of workspace `id` against (their `getContext()`),
1071
+ * asked at every admission: the deployment as the shared `deployments` lists it, the kernel
1072
+ * record, its souls (the catalog's shared rows) and its rows now. */
1073
+ export function spawnContext(state, id, at) {
1074
+ const held = heldOf(state, at);
1075
+ const workspace = heldDeployments(held).find((w) => w.id === id) ?? null;
1076
+ return { workspace, cli: state.cli, agents: catalogOf(state, id).all, instances: workspace ? rowsOf(held, id) : [] };
1077
+ }
1078
+
1079
+ /** The soul row of workspace `id` an instance's soul (its row's `agent`) names, or null. */
1080
+ export function soulOfAgent(state, id, agent) {
1081
+ return catalogOf(state, id).all.find((row) => soulNames(row).includes(agent)) ?? null;
1082
+ }
1083
+
1084
+ /** The picker's rows: the souls of the prompt's workspace, filtered by the query with the palette's
1085
+ * subsequence score (the best first, a tie in the catalog's order). `selected` is the soul the
1086
+ * selection stands on: the prompt's, while it is listed, else the first. */
1087
+ export function spawnPickerItems(state) {
1088
+ const p = state.spawn, c = catalogOf(state, p.workspace), query = p.query.trim();
1089
+ const items = (query === "" ? c.all : c.all.map((row, i) => ({ row, i, score: subsequenceScore(row.name, query) })).filter((each) => each.score !== null).sort((a, b) => a.score - b.score || a.i - b.i).map(({ row }) => row))
1090
+ .map((row) => ({ name: row.name, row, refused: spawnRefusal(row, state.cli) !== null }));
1091
+ return { catalog: c, items, selected: items.some((item) => item.name === p.selected) ? p.selected : items[0]?.name ?? null };
1092
+ }
1093
+
1094
+ /** The folded parts a preview's data has, in order: the launch-prompt policy, the capabilities'
1095
+ * warnings and the modules, where it carries them (previewFacts makes `prompts`, `warnings` and
1096
+ * `modules` of exactly these). */
1097
+ const foldKeys = (data) => (data ? [
1098
+ ...(data.launchPromptAnswers ? ["prompts"] : []),
1099
+ ...(Array.isArray(data.warnings) && data.warnings.length ? ["warnings"] : []),
1100
+ ...(Array.isArray(data.modules) ? ["modules"] : []),
1101
+ ] : []);
1102
+ /** Each fold of a preview, one row until opened: the labels and the one-line summaries are the
1103
+ * TUI's; what they fold is the shared facts'. */
1104
+ function spawnFolds(data, facts) {
1105
+ const caps = facts?.modules?.caps.length ?? 0, core = facts?.modules?.core.filter((slot) => slot.module).length ?? 0;
1106
+ const made = {
1107
+ prompts: { label: "Launch prompts", summary: "what the launcher answers for this home" },
1108
+ warnings: { label: "Warnings", summary: `${facts?.warnings.length ?? 0} from its capabilities; they block nothing` },
1109
+ modules: { label: "Modules", summary: `${core} core, ${caps} other capabilit${caps === 1 ? "y" : "ies"}` },
1110
+ };
1111
+ return foldKeys(data).map((key) => ({ key, ...made[key] }));
1112
+ }
1113
+ /** The preview's focus ring, in Tab's order: Spawn, the name, child of (when offered), each fold. */
1114
+ export const spawnRing = (p) => ["spawn", "name", ...(p.anchor ? ["child"] : []), ...foldKeys(p.data).map((key) => `fold:${key}`)];
1115
+
1116
+ /** The row of the instance a spawn created (`arriving`), as the Desktop's spawn jobs find it
1117
+ * (spawn-jobs.mjs `observe`): its workspace's rows holding exactly one of that instance, home,
1118
+ * root and soul, on this machine. Null while there is none. */
1119
+ export function spawnedRow(state, a, at = new Date(0).toISOString()) {
1120
+ const same = rowsOf(heldOf(state, at), a.workspace).filter((row) => row.instance === a.instance && row.home === a.home && row.agentsRoot === a.agentsRoot
1121
+ && (a.agent === null || a.agent === undefined || row.agent === a.agent) && !row.server);
1122
+ return same.length === 1 ? same[0] : null;
1123
+ }
1124
+
1125
+ /** The preview's facts as the shared home words them: the name typed, else the kernel's; where
1126
+ * it runs in the Desktop's words for the deployment (deployment-label.mjs). Null before an answer. */
1127
+ function spawnFacts(state, p, at) {
1128
+ if (!p.data) return null;
1129
+ const workspace = heldDeployments(heldOf(state, at)).find((w) => w.id === p.workspace) ?? null;
1130
+ return previewFacts(p.data, { name: p.name || p.data.instance || null, runsOn: workspace ? deploymentLabel(workspace, TERMS) : null, cli: state.cli });
1131
+ }
1132
+ /** Whether the preview on screen is the one Enter on Spawn would spawn: read, and for the choices shown. */
1133
+ export const spawnReady = (p) => p.step === "preview" && p.status === "shown" && p.data !== null && p.readKey === spawnChoicesKey(p);
1134
+
1135
+ /** The prompt as views/spawn.mjs draws it (that file has the shape), in a body `page` rows tall. */
1136
+ function spawnView(state, page, at) {
1137
+ const p = state.spawn;
1138
+ if (p.step === "picker") {
1139
+ const list = spawnPickerItems(state), c = list.catalog, entry = c.held?.entry ?? null;
1140
+ const height = Math.max(1, page - 2), at_ = list.items.findIndex((item) => item.name === list.selected);
1141
+ const win = windowOf({ top: 0, count: list.items.length, height, keep: at_ });
1142
+ const reading = !Array.isArray(entry?.souls), failed = reading && entry?.reason && !c.held?.reading;
1143
+ return {
1144
+ step: "picker", query: p.query,
1145
+ rows: list.items.slice(win.top, win.top + win.size).map((item) => ({ name: item.name, refused: item.refused, refusal: item.refused ? soulFacts(item.row, null, state.cli, TERMS).refusalLine : null, selected: item.name === list.selected })),
1146
+ above: win.above, below: win.below,
1147
+ state: failed ? "failed" : reading ? "reading" : !c.all.length ? "none" : !list.items.length ? "nomatch" : "rows",
1148
+ failure: failed ? catalogFailure(entry.reason) : null,
1149
+ };
1150
+ }
1151
+ const facts = spawnFacts(state, p, at), ring = spawnRing(p);
1152
+ const focus = ring.includes(p.focus) ? p.focus : "spawn";
1153
+ const folds = spawnFolds(p.data, facts).map((fold) => ({ ...fold, open: p.folds.includes(fold.key), focused: focus === `fold:${fold.key}` }));
1154
+ const problem = p.problem ?? (p.status === "failed" ? spawnLine(spawnProblem(p.reason, "preview"), p.name || null, state.actions) : null);
1155
+ const ready = spawnReady(p);
1156
+ const enter = focus === "spawn" ? (ready ? "spawn" : p.status === "failed" && p.soul !== null ? "read again" : null)
1157
+ : focus === "name" ? "keep the name"
1158
+ : focus === "child" ? (p.child ? "no parent" : "child of")
1159
+ : folds.find((fold) => fold.focused)?.open ? "close" : "open";
1160
+ return {
1161
+ step: "preview", soul: p.soul?.name ?? null, status: p.status, facts, problem,
1162
+ fields: { name: { text: p.name, focused: focus === "name" }, child: { offered: p.anchor !== null, on: p.child, label: p.anchor?.instance ?? null, focused: focus === "child" } },
1163
+ focus, folds, enter, ready, top: p.top,
1164
+ };
1165
+ }