@awebai/oats 0.59.0 → 0.60.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 (35) hide show
  1. package/docs/desktop-cli-api.md +12 -5
  2. package/docs/execution-targets.md +7 -2
  3. package/docs/implementation.md +1 -0
  4. package/docs/integrations.md +1 -1
  5. package/docs/official-catalog.md +2 -2
  6. package/docs/packages.md +7 -7
  7. package/docs/release-notes/v0.60.0.md +104 -0
  8. package/docs/tui.md +123 -15
  9. package/docs/workspaces.md +1 -1
  10. package/lib/core.mjs +42 -15
  11. package/lib/session-input.mjs +45 -28
  12. package/package-catalog.json +2 -2
  13. package/package.json +1 -1
  14. package/packages/client/capability-catalog.mjs +93 -0
  15. package/packages/client/capability-facts.mjs +59 -0
  16. package/packages/client/capability-rows.mjs +121 -0
  17. package/packages/client/catalog-messages.mjs +12 -0
  18. package/packages/client/cli-locator.mjs +2 -2
  19. package/packages/client/soul-catalog.mjs +8 -0
  20. package/packages/client/soul-facts.mjs +7 -0
  21. package/packages/client/spawn-messages.mjs +8 -0
  22. package/packages/client/subsequence-score.mjs +15 -0
  23. package/packages/tui/README.md +1 -1
  24. package/packages/tui/lib/actions.mjs +1 -1
  25. package/packages/tui/lib/client.mjs +7 -2
  26. package/packages/tui/lib/main.mjs +58 -9
  27. package/packages/tui/lib/model.mjs +136 -46
  28. package/packages/tui/lib/store.mjs +133 -16
  29. package/packages/tui/lib/views/capabilities.mjs +239 -0
  30. package/packages/tui/lib/views/frame.mjs +55 -20
  31. package/packages/tui/lib/views/help.mjs +9 -4
  32. package/packages/tui/lib/views/palette.mjs +9 -4
  33. package/packages/tui/lib/views/souls.mjs +6 -4
  34. package/packages/tui/lib/views/spawn.mjs +5 -3
  35. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -12,7 +12,7 @@
12
12
  import { homedir } from "node:os";
13
13
  import { resolve } from "node:path";
14
14
  import { bindings } from "./actions.mjs";
15
- import { TERMS, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
15
+ import { TERMS, capabilityCatalogKey, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
16
16
  import { loadConfig } from "./config.mjs";
17
17
  import { ACT_WORDS, actContext, actCwd, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
18
18
  import { createPanel, sweep } from "./panel.mjs";
@@ -77,12 +77,13 @@ function errorLines(error) {
77
77
  * run's private directory (the reader's change output and the panel's tmux server share it), and
78
78
  * `removeDir` removes it on the way out once both have removed their files; `sweep` removes what
79
79
  * runs that are gone left of theirs (lib/panel.mjs). `createSoulCatalog` is the shared home's
80
- * catalog of a workspace's souls, replaceable so a test can count its reads; the three spawn
80
+ * catalog of a workspace's souls, and `createCapabilityCatalog` its table of capabilities, each
81
+ * replaceable so a test can count its reads; the three spawn
81
82
  * factories are the shared home's preview, apply boundary and transaction, replaceable so a test
82
83
  * can answer them. */
83
84
  const EFFECTS = Object.freeze({ loadConfig, findDeployment, probeKernel, createReader, offeredDeployments, admitDeployment, prepareRemoteTerm, createPanel, sweep,
84
85
  runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
85
- createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction });
86
+ createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction });
86
87
 
87
88
  /** The timers a run lends the shared spawn: the apply's deadline and its grace (the boundary's
88
89
  * `applyTimer`), the boundary's wait for an answer (`timer`) and the transaction's polls
@@ -257,12 +258,51 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
257
258
  const deployment = state.entries.get(id)?.deployment;
258
259
  return deployment?.status === "observed" ? soulCatalogKey(probe.cli, deployment.workspaceStatus) : null;
259
260
  }
260
- /** `r` in the Souls view: what is held for the workspace is forgotten and settled again, so one
261
- * read starts; never a second while one is in flight. */
261
+ /** `r` in the Souls view, as `r` in the Capabilities view: one live read, never a second while one
262
+ * is in flight. What is held stays held beside it (the shared catalog's refresh), so a read that
263
+ * fails keeps the last good souls under the failure, as a failed read of the workspace's moved key
264
+ * does. */
262
265
  function rereadSouls(id) {
263
- if (souls.refreshing(id)) return;
264
- souls.forget(id);
265
- settleSouls(id);
266
+ const deployment = state.entries.get(id)?.deployment;
267
+ if (ended || deployment?.status !== "observed" || souls.refreshing(id)) return;
268
+ let pending;
269
+ try { pending = souls.refresh(id, probe.cli, deployment.workspaceStatus); } catch { return; } // the reader has stopped
270
+ heard({ souls: { id, entry: souls.held(id), reading: true } });
271
+ pending.then((landed) => { if (landed?.key === soulsKeyNow(id)) heard({ souls: { id, entry: landed, reading: souls.refreshing(id) } }); }, () => {});
272
+ }
273
+
274
+ // THE CAPABILITIES (docs/tui.md, "The Capabilities view"; Spec 7): as the souls, one table per run,
275
+ // the shared home's, over the reader's exec (its `oats capabilities` a read of kind "read", ended on
276
+ // every way out), settled for the open workspace with its own `workspace status`, so read only when
277
+ // nothing is held for the workspace as it is now (capabilityCatalogKey), and never before the
278
+ // Capabilities view was first shown. Its "Used by" reads the souls catalog above, settled with it.
279
+ const capabilities = effects.createCapabilityCatalog({ terms: TERMS, exec: reader.exec });
280
+ /** The table of workspace `id` settled now, and the store told what is held and whether a read is
281
+ * in flight; once that read lands, told again, when it is of the workspace as it is now. */
282
+ function settleCapabilities(id) {
283
+ const deployment = state.entries.get(id)?.deployment;
284
+ if (ended || deployment?.status !== "observed") return;
285
+ let settled;
286
+ try { settled = capabilities.settle(id, probe.cli, deployment.workspaceStatus); } catch { return; } // the reader has stopped
287
+ const { entry, pending } = settled;
288
+ heard({ capabilities: { id, entry, reading: pending !== null } });
289
+ if (pending) pending.then((landed) => { if (landed?.key === capabilitiesKeyNow(id)) heard({ capabilities: { id, entry: landed, reading: capabilities.refreshing(id) } }); }, () => {});
290
+ }
291
+ /** The table's key for the workspace as the loop holds it now, or null when it is not observed. */
292
+ function capabilitiesKeyNow(id) {
293
+ const deployment = state.entries.get(id)?.deployment;
294
+ return deployment?.status === "observed" ? capabilityCatalogKey(probe.cli, deployment.workspaceStatus) : null;
295
+ }
296
+ /** `r` in the Capabilities view: one live read, never a second while one is in flight. What is
297
+ * held stays held beside it (the shared catalog's refresh), so a read that fails keeps the last
298
+ * good table under the failure, as a failed read of the workspace's moved key does. */
299
+ function rereadCapabilities(id) {
300
+ const deployment = state.entries.get(id)?.deployment;
301
+ if (ended || deployment?.status !== "observed" || capabilities.refreshing(id)) return;
302
+ let pending;
303
+ try { pending = capabilities.read(id, probe.cli, deployment.workspaceStatus, { refresh: true }); } catch { return; } // the reader has stopped
304
+ heard({ capabilities: { id, entry: capabilities.held(id), reading: true } });
305
+ pending.then((landed) => { if (landed?.key === capabilitiesKeyNow(id)) heard({ capabilities: { id, entry: landed, reading: capabilities.refreshing(id) } }); }, () => {});
266
306
  }
267
307
 
268
308
  // THE SPAWN (docs/tui.md, "Spawning an agent"; Spec 6-spawn). One preview, one apply boundary and
@@ -327,12 +367,14 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
327
367
  }
328
368
 
329
369
  /** What the reader gave, into the state, and the screen after it. A read of the open workspace,
330
- * once the Souls view was shown, settles its catalog: read again only when the workspace moved. */
370
+ * once the Souls view (or the Capabilities view, or a spawn) wanted its catalog, settles it, and
371
+ * once the Capabilities view was shown its table: each read again only when its key moved. */
331
372
  function heard(event) {
332
373
  if (ended) return;
333
374
  guard.attempt(() => {
334
375
  if (took(reduce(state, event, keymap))) return;
335
376
  if (event.entry !== undefined && event.id === state.open && state.souls.wanted) settleSouls(event.id);
377
+ if (event.entry !== undefined && event.id === state.open && state.capabilities.wanted) settleCapabilities(event.id);
336
378
  guard.draw();
337
379
  });
338
380
  }
@@ -367,6 +409,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
367
409
  if (effect.refresh) refresh(effect.refresh);
368
410
  if (effect.souls === "settle" && state.open !== null) settleSouls(state.open);
369
411
  if (effect.souls === "reread" && state.open !== null) rereadSouls(state.open);
412
+ if (effect.capabilities === "settle" && state.open !== null) settleCapabilities(state.open);
413
+ if (effect.capabilities === "reread" && state.open !== null) rereadCapabilities(state.open);
370
414
  if (effect.spawnPreview) previewRead(effect.spawnPreview);
371
415
  if (effect.spawn) spawnNow(effect.spawn);
372
416
  if (effect.spawnCheck) checkSpawn();
@@ -584,6 +628,11 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
584
628
  // This frame is written (the guard makes one only to write it): a ready preview on it is
585
629
  // seen, and Enter on Spawn is taken from the next read of input on (the paste guard).
586
630
  if (made.armed && state.spawn !== null) state = reduce(state, { spawnDrawn: { n: state.spawn.n, read: reads } }, keymap).state;
631
+ // The preview's window as painted, which keeps a focused fold in sight: the store's `top`
632
+ // from now on, so the next movement key goes on from what is on the screen.
633
+ if (made.drawnTop !== undefined && state.spawn !== null) state = reduce(state, { spawnTop: { n: state.spawn.n, top: made.drawnTop } }, keymap).state;
634
+ // The capability detail's window as painted, which keeps the marked soul in sight: the same.
635
+ if (made.capabilitiesTop !== undefined) state = reduce(state, { capabilitiesTop: made.capabilitiesTop }, keymap).state;
587
636
  return bytes;
588
637
  },
589
638
  onInput(bytes) {
@@ -12,7 +12,9 @@ import {
12
12
  identityMemory, viewModel, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath,
13
13
  openAct, deployments as heldDeployments, attachExit, preflightFailure, kernelLines,
14
14
  startGate, launchFlagIgnored, flagIgnoredNotice, retainedStartMessage, retiringRows, soulRows, soulFacts, spawnRefusal,
15
- defaultSpawnChoices, spawnProblem, outcomeWords, previewFacts, deploymentLabel,
15
+ defaultSpawnChoices, spawnProblem, outcomeWords, previewFacts, deploymentLabel, subsequenceScore, soulMatches, soulCatalogFailure, catalogFailure,
16
+ memberNames, capabilitySource, groupCapabilities, hostKeyOf, capabilitySections, matchCapabilities, soulsComposition, rosterAgentName, layerLabel, capabilityUsers,
17
+ capabilityFacts, CAPABILITY_COPY,
16
18
  } from "./client.mjs";
17
19
  import { LEADER, keyLabel } from "./actions.mjs";
18
20
  import { ownEllipsis, shownLines } from "./term/text.mjs";
@@ -365,13 +367,8 @@ function groupsOf(state) {
365
367
  return { tabs, shown };
366
368
  });
367
369
  }
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. */
370
+ /** A command in a line of the TUI's own: whole, never broken over two rows. */
371
371
  const command = (text) => Object.freeze({ own: `\`${text}\``, whole: true });
372
- export const NOT_BUILT = 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([]) }),
374
- });
375
372
  /** A sentence from outside (a reason of the shared home's, the preflight table's), as a text
376
373
  * under the line: drawn as the detail draws a reason, wrapped on the reason's rows, never as one
377
374
  * unbroken part (a part is a name). */
@@ -538,22 +535,6 @@ export function switcher(state, at = new Date(0).toISOString()) {
538
535
  };
539
536
  }
540
537
 
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
538
  /** The palette's views and commands, each a row's label and the action it runs. */
558
539
  const PALETTE_VIEWS = Object.freeze([["instances", "Instances"], ["souls", "Souls"], ["capabilities", "Capabilities"]]);
559
540
  const PALETTE_COMMANDS = Object.freeze([["spawn", "Spawn an agent"], ["workspaces", "Workspaces"], ["refresh", "Refresh"], ["help", "Help"]]);
@@ -566,12 +547,12 @@ const PALETTE_ACTS = Object.freeze({ stop: "Stop", restart: "Restart", retire: "
566
547
 
567
548
  /** THE PALETTE'S ROWS (docs/tui.md, "The palette"), in this order: the instances that can be
568
549
  * 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
550
+ * open workspace once its catalog was read, its capabilities once theirs was, the views, the acts
570
551
  * the palette's instance offers (the open terminal's, when the palette came from its focus; else
571
552
  * the selected one) and, once the catalog lists its soul, another of that soul, then spawning an
572
553
  * agent, workspaces, refresh and help, and the split's that apply. With a query, each group keeps the rows the
573
554
  * 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
555
+ * A row: `{ key, kind, label, does?, id?, name?, machine?, mark?, capability?, source? }`; `selected` is the key the
575
556
  * selection stands on (the first row when the palette's own is not listed). */
576
557
  export function paletteItems(state, at = new Date(0).toISOString()) {
577
558
  const p = state.palette;
@@ -590,6 +571,14 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
590
571
  // The souls of the open workspace, once its catalog was read (the Souls view opened): choosing
591
572
  // one shows the Souls view with it selected. A palette never reads the catalog.
592
573
  groups.push(soulsOf(state).all.map((row) => ({ key: `soul\u0000${row.name}`, kind: "soul", label: row.name, name: row.name, text: row.name })));
574
+ // The capabilities of the open workspace, once its catalog was read (the Capabilities view opened):
575
+ // choosing one shows that view with it selected. Each says where it comes from (a package's and a
576
+ // member's may share a name).
577
+ const c = capabilitiesOf(state), names = memberNames(c.status);
578
+ groups.push(c.all.map((row) => {
579
+ const capability = capabilityKey(row, names);
580
+ return { key: `capability\u0000${capability}`, kind: "capability", label: row.name, name: row.name, capability, source: capabilitySource(row, names).label, text: row.name };
581
+ }));
593
582
  groups.push(PALETTE_VIEWS.map(([does, label]) => ({ key: `view\u0000${does}`, kind: "view", label, does, text: label })));
594
583
  const id = p.from === "terminal" && state.terminal !== null ? state.terminal.id : state.selected;
595
584
  const row = id === null || state.open === null ? null : roster(state, at).instances.find((each) => instanceId(each) === id) ?? null;
@@ -642,7 +631,7 @@ export function model(state, { page, now, at, cols }) {
642
631
  const common = {
643
632
  view: state.view, focus: state.focus, ascii: state.ascii, actions: state.actions,
644
633
  // The filter of the view shown: the Souls view has one of its own.
645
- filter: state.view === "souls" ? state.souls.filter : state.filter,
634
+ filter: state.view === "souls" ? state.souls.filter : state.view === "capabilities" ? state.capabilities.filter : state.filter,
646
635
  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,
647
636
  detailTop: state.detailTop, helpTop: state.helpTop, open: state.open !== null,
648
637
  detachKey: state.detachKey, opening: state.opening, openable: false, actable: [],
@@ -655,8 +644,8 @@ export function model(state, { page, now, at, cols }) {
655
644
  act: state.view === "act" && state.act ? actView(state) : null,
656
645
  // The leader waits for its key (the footer is its hint), and the palette, while it is open.
657
646
  leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, page, at),
658
- body: state.view === "capabilities" ? NOT_BUILT.capabilities : null,
659
647
  souls: state.view === "souls" ? soulsView(state, page, at) : null,
648
+ capabilities: state.view === "capabilities" ? capabilitiesView(state, page, at) : null,
660
649
  spawn: state.spawn === null ? null : spawnView(state, page, at),
661
650
  // The line above the panes: the last outcome, else a spawn under way (outcomeOf).
662
651
  outcome: outcomeOf(state),
@@ -889,24 +878,14 @@ export function actView(state) {
889
878
 
890
879
  // ── THE SOULS VIEW (docs/tui.md, "The Souls view") ───────────────────────────────────────────────
891
880
 
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
881
  /** 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. */
882
+ * package soul the kernel's key, its qualified name and its name in the roster, `<package>--<soul>`
883
+ * (the shared rosterAgentName: the agent directory a package soul's instances are made under). The
884
+ * exact soul filter, the count of a soul's instances and "Used by" match these. */
902
885
  export function soulNames(row) {
903
- return [...new Set([row.name, row.key, row.qualifiedName].filter(text))];
886
+ return [...new Set([row.name, row.key, row.qualifiedName, rosterAgentName(row)].filter(text))];
904
887
  }
905
888
 
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
889
  /** The souls of the open workspace as the store and the view read them: the shared rows
911
890
  * (soul-rows.mjs soulRows) of the catalog the loop holds for it, filtered by the view's own
912
891
  * filter. Only a workspace of this machine has souls here (`local`). `held` is what the loop
@@ -914,8 +893,9 @@ const soulMatches = (row, needle) => [row.name, row.description, row.repoName].s
914
893
  * row the selection stands on: the store's, while it is listed, else the first. */
915
894
  export function soulsOf(state) {
916
895
  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;
896
+ // The Souls view's filter is the Desktop's soul grid's (soulMatches), on the trimmed text.
897
+ const query = state.souls.filter.query.trim();
898
+ const rows = query ? all.filter((row) => soulMatches(row, query)) : all;
919
899
  const selected = rows.find((row) => row.name === state.souls.selected) ?? rows[0] ?? null;
920
900
  return { local, deployment, held, all, rows, selected };
921
901
  }
@@ -976,9 +956,9 @@ function soulsView(state, page, at) {
976
956
  const entry = s.held?.entry ?? null, reason = entry?.reason ?? null;
977
957
  if (!Array.isArray(entry?.souls)) {
978
958
  // 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" };
959
+ return reason && !s.held.reading ? { ...base, state: "failed", failure: soulCatalogFailure(reason) } : { ...base, state: "reading" };
980
960
  }
981
- const heading = reason ? { label: "Souls", path: null, state: null, short: catalogFailure(reason), readAt: clockTime(entry.observedAt) } : null;
961
+ const heading = reason ? { label: "Souls", path: null, state: null, short: soulCatalogFailure(reason), readAt: clockTime(entry.observedAt) } : null;
982
962
  const state_ = !s.all.length ? "none" : !s.rows.length ? "nomatch" : "rows";
983
963
  const height = Math.max(1, page - (heading ? 1 : 0));
984
964
  const at_ = s.selected ? s.rows.indexOf(s.selected) : -1;
@@ -996,6 +976,116 @@ function soulsView(state, page, at) {
996
976
  };
997
977
  }
998
978
 
979
+ // ── THE CAPABILITIES VIEW (docs/tui.md, "The Capabilities view"; Spec 7) ──────────────────────────
980
+
981
+ /** A capability's identity in the view: its source's key and its name, since a package's capability
982
+ * and a member's may share a name (Spec 7, Settled 8). */
983
+ export const capabilityKey = (row, names) => `${capabilitySource(row, names).key}\u0000${row.name}`;
984
+
985
+ /** The view's sections, in the order they stand (the Desktop's): Workspace owned, Repo owned, Packages. */
986
+ const SECTION_ORDER = Object.freeze(["workspace", "repo", "packages"]);
987
+
988
+ /** The capabilities of the open workspace as the store and the view read them: the rows of the
989
+ * catalog the loop holds for it (`held`, `{ entry, reading }`), filtered by the view's own filter
990
+ * (the shared matchCapabilities), in the shared sections (capabilitySections) and groups
991
+ * (groupCapabilities), as `items` in drawn order: `{ section }` (a section's heading), `{ group, note }`
992
+ * (a repository's or a package's), and `{ key, row }` (a capability). A section or a group with no
993
+ * row is not listed. `keys` are the capabilities in order, `selected` the key the selection stands
994
+ * on (the store's while it is listed, else the first) and `row` its row; `heading` whether a failed
995
+ * re-read's heading stands above the rows. Only a workspace of this machine has them (`local`). */
996
+ export function capabilitiesOf(state) {
997
+ const id = state.open, local = id !== null && state.ctxs.includes(id);
998
+ const entry = local ? state.entries.get(id) ?? null : null;
999
+ const deployment = entry?.deployment?.status === "observed" ? entry.deployment : null;
1000
+ const held = local ? state.capabilities.held.get(id) ?? null : null;
1001
+ const status = deployment?.workspaceStatus ?? null;
1002
+ const listed = deployment !== null && Array.isArray(held?.entry?.capabilities?.capabilities);
1003
+ const all = listed ? held.entry.capabilities.capabilities : [];
1004
+ const names = memberNames(status), hostKey = hostKeyOf(status);
1005
+ const sections = capabilitySections(matchCapabilities(all, state.capabilities.filter.query));
1006
+ const items = [];
1007
+ for (const section of SECTION_ORDER) {
1008
+ if (!sections[section].length) continue;
1009
+ items.push({ section });
1010
+ for (const group of groupCapabilities(sections[section], names, hostKey)) {
1011
+ items.push({ group: group.name, note: group.note });
1012
+ for (const row of group.rows) items.push({ key: capabilityKey(row, names), row });
1013
+ }
1014
+ }
1015
+ const keys = items.filter((item) => item.key !== undefined).map((item) => item.key);
1016
+ const selected = keys.includes(state.capabilities.selected) ? state.capabilities.selected : keys[0] ?? null;
1017
+ const row = selected === null ? null : items.find((item) => item.key === selected).row;
1018
+ return { local, deployment, status, held, listed, all, items, keys, selected, row, heading: listed && Boolean(held.entry.reason) };
1019
+ }
1020
+ /** The rows the list of capabilities has in a pane `page` rows tall: a failed re-read's heading takes one. */
1021
+ export const capabilitiesHeight = (c, page) => Math.max(1, page - (c.heading ? 1 : 0));
1022
+
1023
+ /** "Used by" of capability `row` (capability-rows.mjs capabilityUsers): with the kernel's
1024
+ * souls-capabilities, the souls of the open workspace's catalog whose composition includes it; before
1025
+ * it, the souls whose instances carry it. `instances` are this machine's rows of the open workspace.
1026
+ * Each user is drawn by its catalog row (soulOfAgent maps an instance's agent name to it): its name
1027
+ * and colour, and the soul Enter shows in the Souls view (`soul`, null when no row matches); `count`
1028
+ * its instances carrying the capability, and `behind` the shared words for those on an older
1029
+ * version, or null. Until the souls catalog is read the souls are not known (`reading`, or `failed`
1030
+ * with its sentence): nothing claims that no soul includes it. */
1031
+ export function capabilityUsersOf(state, at, row) {
1032
+ const composition = soulsComposition(state.cli), souls = catalogOf(state, state.open), entry = souls.held?.entry ?? null;
1033
+ const none = { shown: [], more: 0, count: null, empty: null, failure: null };
1034
+ if (composition && !Array.isArray(entry?.souls)) return { ...none, state: entry?.reason && !souls.held.reading ? "failed" : "reading", failure: entry?.reason && !souls.held.reading ? soulCatalogFailure(entry.reason) : null };
1035
+ const instances = roster(state, at).ordered.filter((each) => !elsewhere(each) && each.deployment?.id === state.open);
1036
+ const users = capabilityUsers(row, { souls: souls.all, instances, composition }).map(({ soul, carrying, behind }) => {
1037
+ const found = composition ? soul : soulOfAgent(state, state.open, soul.name);
1038
+ return { name: found?.name ?? soul.name, color: found ? SOUL_COLOURS[found.color] ?? null : null, count: carrying.length, behind: behind > 0 ? CAPABILITY_COPY.behind(behind) : null, soul: found?.name ?? null };
1039
+ });
1040
+ return {
1041
+ ...none, state: "known", shown: users.slice(0, INSTANCES_NAMED), more: Math.max(0, users.length - INSTANCES_NAMED), count: CAPABILITY_COPY.souls(users.length),
1042
+ empty: users.length ? null : composition ? CAPABILITY_COPY.noSoul : CAPABILITY_COPY.noInstance,
1043
+ };
1044
+ }
1045
+
1046
+ /** The selected capability's detail, from its row and the shared facts (capability-facts.mjs
1047
+ * capabilityFacts) in the shared words (CAPABILITY_COPY): nothing of a capability is worded here. A
1048
+ * kind of Provides the kernel could not list (`names` null) says CAPABILITY_COPY.unlistable, and one
1049
+ * with no name CAPABILITY_COPY.none. `comesFrom` holds the facts' "Comes from" rows as `{ label,
1050
+ * value }`, the shortened value (not `origin`: in this package that names a reason's speaker, which
1051
+ * test/tui-boundary.test.mjs holds to originLead). */
1052
+ function capabilityDetail(state, at, c) {
1053
+ const row = c.row, { origin, provides } = capabilityFacts(row, { status: c.status });
1054
+ return {
1055
+ name: row.name, layer: text(row.layer) ? layerLabel(row.layer) : null, description: row.description ?? "",
1056
+ words: { comesFrom: CAPABILITY_COPY.comesFrom, provides: CAPABILITY_COPY.provides, usedBy: CAPABILITY_COPY.usedBy },
1057
+ comesFrom: origin.map(([label, value]) => ({ label, value })),
1058
+ provides: provides.map(([label, names]) => ({ label, names: names ?? [], said: names === null ? CAPABILITY_COPY.unlistable : names.length ? null : CAPABILITY_COPY.none })),
1059
+ used: capabilityUsersOf(state, at, row),
1060
+ };
1061
+ }
1062
+
1063
+ /** What the Capabilities view draws, in a list pane `page` rows tall (views/capabilities.mjs): the
1064
+ * state of the catalog, the window of its items, and the selected capability's detail with the soul
1065
+ * of "Used by" that has the detail's mark (`mark`, an index of its listed souls). A failed re-read
1066
+ * keeps the rows it held, under a heading that says so, as the Souls view's does. */
1067
+ function capabilitiesView(state, page, at) {
1068
+ const c = capabilitiesOf(state), v = state.capabilities;
1069
+ const base = { local: c.local, failure: null, heading: null, list: [], above: 0, below: 0, focus: v.focus, filter: v.filter, detail: null, detailTop: v.detailTop, keep: !v.detailLoose, mark: v.mark };
1070
+ if (!c.local) return { ...base, state: "none" };
1071
+ const entry = c.held?.entry ?? null, reason = entry?.reason ?? null;
1072
+ if (!c.listed) return reason && !c.held.reading ? { ...base, state: "failed", failure: catalogFailure("capabilities", reason) } : { ...base, state: "reading" };
1073
+ const heading = c.heading ? { label: "Capabilities", path: null, state: null, short: catalogFailure("capabilities", reason), readAt: clockTime(entry.observedAt) } : null;
1074
+ const state_ = !c.all.length ? "none" : !c.keys.length ? "nomatch" : "rows";
1075
+ const at_ = c.items.findIndex((item) => item.key !== undefined && item.key === c.selected);
1076
+ const win = windowOf({ top: v.top, count: c.items.length, height: capabilitiesHeight(c, page), keep: v.loose ? -1 : at_ });
1077
+ const detail = c.row ? capabilityDetail(state, at, c) : null;
1078
+ return {
1079
+ ...base, state: state_, heading,
1080
+ list: c.items.slice(win.top, win.top + win.size).map((item) => (item.key === undefined ? item
1081
+ : { name: item.row.name, layer: text(item.row.layer) ? layerLabel(item.row.layer) : null, selected: item.key === c.selected })),
1082
+ above: win.above, below: win.below,
1083
+ detail: detail && { ...detail, failure: heading ? heading.short : null },
1084
+ // The mark stands on a listed soul only: the store keeps it inside them.
1085
+ mark: detail && v.focus === "detail" && detail.used.shown.length ? Math.min(v.mark, detail.used.shown.length - 1) : -1,
1086
+ };
1087
+ }
1088
+
999
1089
  // ── SPAWNING (docs/tui.md, "Spawning an agent"; Spec 6-spawn) ───────────────────────────────────
1000
1090
 
1001
1091
  /** A shared sentence as parts the outcome line wraps (views/frame.mjs partRows): each word is
@@ -1145,7 +1235,7 @@ function spawnView(state, page, at) {
1145
1235
  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
1236
  above: win.above, below: win.below,
1147
1237
  state: failed ? "failed" : reading ? "reading" : !c.all.length ? "none" : !list.items.length ? "nomatch" : "rows",
1148
- failure: failed ? catalogFailure(entry.reason) : null,
1238
+ failure: failed ? soulCatalogFailure(entry.reason) : null,
1149
1239
  };
1150
1240
  }
1151
1241
  const facts = spawnFacts(state, p, at), ring = spawnRing(p);