@awebai/oats 0.59.0 → 0.61.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 (43) hide show
  1. package/README.md +14 -18
  2. package/bin/oats.mjs +42 -10
  3. package/docs/configuration.md +9 -0
  4. package/docs/desktop-cli-api.md +40 -10
  5. package/docs/desktop.md +7 -0
  6. package/docs/execution-targets.md +7 -2
  7. package/docs/first-team.md +8 -0
  8. package/docs/implementation.md +1 -0
  9. package/docs/integrations.md +1 -1
  10. package/docs/official-catalog.md +2 -2
  11. package/docs/packages.md +7 -7
  12. package/docs/release-notes/v0.60.0.md +104 -0
  13. package/docs/release-notes/v0.61.0.md +155 -0
  14. package/docs/tui.md +133 -19
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +42 -15
  17. package/lib/session-input.mjs +45 -28
  18. package/package-catalog.json +2 -2
  19. package/package.json +1 -1
  20. package/packages/client/capability-catalog.mjs +93 -0
  21. package/packages/client/capability-facts.mjs +59 -0
  22. package/packages/client/capability-rows.mjs +121 -0
  23. package/packages/client/catalog-messages.mjs +12 -0
  24. package/packages/client/cli-locator.mjs +2 -2
  25. package/packages/client/instance-presentation.mjs +10 -0
  26. package/packages/client/instance-tree.mjs +48 -6
  27. package/packages/client/soul-catalog.mjs +8 -0
  28. package/packages/client/soul-facts.mjs +7 -0
  29. package/packages/client/spawn-messages.mjs +8 -0
  30. package/packages/client/subsequence-score.mjs +15 -0
  31. package/packages/tui/README.md +1 -1
  32. package/packages/tui/lib/actions.mjs +1 -1
  33. package/packages/tui/lib/client.mjs +9 -4
  34. package/packages/tui/lib/main.mjs +58 -9
  35. package/packages/tui/lib/model.mjs +150 -50
  36. package/packages/tui/lib/store.mjs +133 -16
  37. package/packages/tui/lib/views/capabilities.mjs +239 -0
  38. package/packages/tui/lib/views/frame.mjs +55 -20
  39. package/packages/tui/lib/views/help.mjs +9 -4
  40. package/packages/tui/lib/views/palette.mjs +13 -4
  41. package/packages/tui/lib/views/souls.mjs +6 -4
  42. package/packages/tui/lib/views/spawn.mjs +5 -3
  43. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -0,0 +1,121 @@
1
+ /** A capability row as both clients read it: the pure rules over `oats capabilities` rows, workspace
2
+ * status and the roster's module rows that the Desktop's Capabilities view and capability page draw
3
+ * from. Which source a row comes from and the group it sits in, the view's sections and search, who
4
+ * uses it ("Used by"), and a core capability's name. Nothing here makes DOM; nothing is resolved,
5
+ * joined across the non-collapse boundary, or inferred. */
6
+
7
+ const list = value => Array.isArray(value) ? value : [];
8
+ const text = value => typeof value === 'string' && value ? value : null;
9
+ /** A member's display name from workspace status; the key's tail otherwise. */
10
+ export function memberNames(status) {
11
+ const names = new Map();
12
+ for (const member of list(status?.members)) if (text(member.key)) names.set(member.key, text(member.name) || member.key.split('/').pop());
13
+ return names;
14
+ }
15
+ /** The source a capability row came from, in the kernel's own kind. */
16
+ export function capabilitySource(row, names = new Map()) {
17
+ if (row.kind === 'package') return { kind: 'package', key: `package:${row.package}`, label: text(row.package) || row.name };
18
+ if (row.kind === 'member') return { kind: 'member', key: `member:${row.repoKey}`, label: names.get(row.repoKey) || String(row.repoKey || '').split('/').pop() || 'member' };
19
+ return { kind: 'external', key: `external:${row.repoKey || row.origin}`, label: String(row.repoKey || row.origin || 'external').split('/').pop() };
20
+ }
21
+ /** Souls whose instances carry this capability as a recorded module, from
22
+ * the roster's own module rows; moved = the kernel reported drift. "Used by" before the kernel
23
+ * reported each soul's composition (souls-capabilities); soulsUsing is the rule with it. */
24
+ export function capabilityUse(instances, name) {
25
+ const souls = new Map(); let moved = 0;
26
+ for (const instance of list(instances)) {
27
+ const rows = Array.isArray(instance.modules) ? instance.modules : Object.entries(instance.modules || {}).map(([key, row]) => ({ name: key, ...row }));
28
+ const row = rows.find(module => module?.name === name);
29
+ if (!row) continue;
30
+ if (row.status === 'moved') moved++;
31
+ const soul = text(instance.agent);
32
+ if (soul && !souls.has(soul)) souls.set(soul, { name: soul, agentsRoot: instance.agentsRoot });
33
+ }
34
+ return { souls: [...souls.values()], moved };
35
+ }
36
+ /** The CLI feature under which every `oats souls` row reports its composed capabilities
37
+ * (deployment-data.mjs soulCapabilitiesOf): "Used by" is then the souls whose composition includes
38
+ * the capability, not only the souls whose live instances recorded it. */
39
+ export const SOULS_CAPABILITIES_FEATURE = 'souls-capabilities';
40
+ export const soulsComposition = cli => list(cli?.features).includes(SOULS_CAPABILITIES_FEATURE);
41
+ /** A soul's agent name in the roster (an instance's `agent`): a package soul's is the kernel's
42
+ * `<package>--<soul>`, the package id with every character outside [a-z0-9-] as '-'
43
+ * (lib/workspace.mjs packageSoulAgentName); every other soul's is its name. */
44
+ export function rosterAgentName(soul) {
45
+ if (soul?.soulKind === 'package' && text(soul.package)) return `${soul.package.replace(/[^a-z0-9-]/g, '-')}--${soul.name}`;
46
+ return soul?.name;
47
+ }
48
+ /** Whether a soul's composition entry is this catalog row: the same name, kind and origin (the repository
49
+ * for a member capability, the package for a package one). A repo-owned row matches the same way; an
50
+ * external row never does (the kernel reports no external entry). */
51
+ export function composes(entry, row) {
52
+ if (!entry || entry.name !== row?.name || entry.kind !== row.kind) return false;
53
+ return row.kind === 'package' ? !!text(row.package) && entry.package === row.package : !!text(row.repoKey) && entry.repoKey === row.repoKey;
54
+ }
55
+ /** The souls (the `oats souls` rows the Souls tab shows) whose composition includes this row; a soul that
56
+ * did not resolve (`capabilities: null`) is never counted. */
57
+ export function soulsUsing(souls, row) {
58
+ return list(souls).filter(soul => Array.isArray(soul?.capabilities) && soul.capabilities.some(entry => composes(entry, row)));
59
+ }
60
+ /** The repository group a member or external capability sits in, as the Souls tab groups souls:
61
+ * the workspace host's repository first, then the other members by name, then one "external"
62
+ * group for every source outside the member repos (a package, never listed here, keeps its own).
63
+ * `hostKey`: workspace status's workspace.key. */
64
+ export function capabilityGroup(row, names = new Map(), hostKey = null) {
65
+ const source = capabilitySource(row, names);
66
+ // A package group (the Packages section) names its pinned version: "package · v1.2.0".
67
+ if (source.kind === 'package') return { key: source.key, rank: 3, icon: 'package', name: source.label, note: ['package', text(row.version) ? `v${row.version}` : null].filter(Boolean).join(' · '), mono: true };
68
+ if (source.kind !== 'member') return { key: 'external', rank: 2, icon: 'external', name: 'external', note: 'not in a member repo', mono: false };
69
+ const host = !!hostKey && row.repoKey === hostKey;
70
+ return { key: source.key, rank: host ? 0 : 1, icon: 'repo', name: source.label, note: host ? 'member repo · host' : 'member repo', mono: true };
71
+ }
72
+ /** Rows in their repository groups, in the Souls tab's order: [{ key, rank, icon, name, note, mono, rows }]. */
73
+ export function groupCapabilities(rows, names = new Map(), hostKey = null) {
74
+ const groups = new Map();
75
+ for (const row of list(rows)) {
76
+ const group = capabilityGroup(row, names, hostKey);
77
+ if (!groups.has(group.key)) groups.set(group.key, { ...group, rows: [] });
78
+ groups.get(group.key).rows.push(row);
79
+ }
80
+ return [...groups.values()].sort((a, b) => a.rank - b.rank || a.name.localeCompare(b.name));
81
+ }
82
+ /** The workspace host's repository key, from workspace status (null when not reported). */
83
+ export const hostKeyOf = status => text(status?.workspace?.key);
84
+ /** The view search: capability names containing the query, case-insensitive. */
85
+ export function matchCapabilities(rows, query = '') {
86
+ const needle = String(query || '').trim().toLowerCase();
87
+ return needle ? list(rows).filter(row => String(row.name).toLowerCase().includes(needle)) : list(rows);
88
+ }
89
+ /** The Capabilities view's three sections, from the catalog rows' own facts:
90
+ * workspace owned (listed to every soul), packages, and repo owned (the
91
+ * kernel's private: true, usable only by that repository's souls). */
92
+ export function capabilitySections(rows) {
93
+ const all = list(rows);
94
+ return {
95
+ workspace: all.filter(row => row.kind !== 'package' && row.private !== true),
96
+ packages: all.filter(row => row.kind === 'package'),
97
+ repo: all.filter(row => row.kind !== 'package' && row.private === true),
98
+ };
99
+ }
100
+ const LAYERS = { knowledge: 'Knowledge', messaging: 'Messaging', tasks: 'Tasks' };
101
+ /** A core capability's name in the UI (Knowledge, Messaging, Tasks), else the layer verbatim. */
102
+ export const layerLabel = layer => LAYERS[layer] || layer;
103
+
104
+ /** An instance's recorded module row for a capability (its `modules`, a list or a map by name), or null. */
105
+ function moduleRow(instance, name) {
106
+ const rows = Array.isArray(instance.modules) ? instance.modules : Object.entries(instance.modules || {}).map(([key, row]) => ({ name: key, ...row }));
107
+ return rows.find(m => m?.name === name) || null;
108
+ }
109
+ /** "Used by" (the capability page's table): with `composition` (souls-capabilities) the souls whose composition
110
+ * includes the row (soulsUsing), before it the souls whose instances carry it (capabilityUse). Each with
111
+ * `carrying`, its instances that carry the module (the roster's agent name, a package soul's being
112
+ * `<package>--<soul>`, within the soul's agents root), and `behind`, how many of those report it moved. */
113
+ export function capabilityUsers(row, { souls, instances, composition } = {}) {
114
+ const users = composition ? soulsUsing(souls, row) : capabilityUse(instances, row.name).souls;
115
+ return users.map(soul => {
116
+ const agent = composition ? rosterAgentName(soul) : soul.name;
117
+ const carrying = list(instances).filter(i => i.agent === agent && i.agentsRoot === soul.agentsRoot && moduleRow(i, row.name));
118
+ const behind = carrying.filter(i => moduleRow(i, row.name)?.status === 'moved').length;
119
+ return { soul, carrying, behind };
120
+ });
121
+ }
@@ -0,0 +1,12 @@
1
+ /** The sentence of a failed catalog read (a held entry's `reason`), the same in every client and for
2
+ * every catalog a client shows: the souls (soul-catalog.mjs) and the capabilities
3
+ * (capability-catalog.mjs). The noun is one of those two, so no client words a third catalog its own
4
+ * way. The kernel's message in it is text from outside: a client draws it through its display
5
+ * filter. */
6
+ const NOUNS = Object.freeze(['souls', 'capabilities']);
7
+
8
+ export function catalogFailure(noun, reason) {
9
+ if (!NOUNS.includes(noun)) throw new TypeError(`catalogFailure: noun must be one of ${NOUNS.join(', ')}`);
10
+ const message = typeof reason?.message === 'string' && reason.message ? reason.message : '';
11
+ return message ? `Couldn't read this workspace's ${noun}: ${message}` : `Couldn't read this workspace's ${noun}.`;
12
+ }
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.60.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.62.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
52
52
  // carry a `description` for every kind and `<kind> update <id> --description`
53
53
  // sets one (feature `automation-descriptions`, which gates the Desktop's
54
54
  // summary writes). The Desktop v1 surface is otherwise unchanged.
55
- export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 60, 0] };
55
+ export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 62, 0] };
56
56
  /** The band as humans read it — derived, never hand-spelled, so the probe
57
57
  * rejection reason, the backend's /api status and the degradation card can
58
58
  * never disagree with the numbers actually enforced above. */
@@ -15,6 +15,16 @@ export function byRuntimeState(a, b) {
15
15
  return RUNTIME_ORDER[runtimeState(a)] - RUNTIME_ORDER[runtimeState(b)] || String(a.instance).localeCompare(String(b.instance));
16
16
  }
17
17
 
18
+ /** The words for an instance's siblings (#1312; the list `instanceSiblings` answers, instance-tree.mjs):
19
+ * null for none, else `sibling of a`, `sibling of a and b`, `sibling of a, b and c`, the names in the
20
+ * order given. The same in every client. */
21
+ export function siblingText(siblings) {
22
+ const names = (siblings || []).map((s) => s.instance);
23
+ if (!names.length) return null;
24
+ const list = names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
25
+ return `sibling of ${list}`;
26
+ }
27
+
18
28
  /** The stand-in `unsupportedSession` writes for an older kernel's Herdr row: the one text of a row that is
19
29
  * this home's own sentence. Not on the stable surface. */
20
30
  export const HERDR_STAND_IN = `E_HERDR_REMOVED: ${HERDR_REMOVED}`;
@@ -11,16 +11,25 @@ export function collapseKey(workspace, instance) {
11
11
  return `${workspace || ""}\u0000${instance}`;
12
12
  }
13
13
 
14
+ /** An instance's explicit sibling link, as an array of instance names: the one reader of the kernel's
15
+ * `siblingInstance` (string | absent, set only when a sibling relation was declared against a ROOT
16
+ * instance — a sibling of a non-root simply shares the anchor's `parentInstance`). Normalized to an
17
+ * array so callers are shape-agnostic; self-links and non-strings are dropped. The sidebar's
18
+ * `instanceLinks`, `instanceSiblings` and the Desktop's Deployments graph all read the field here. */
19
+ export function siblingLinksOf(instance) {
20
+ const raw = instance.siblingInstance;
21
+ if (typeof raw !== "string" || !raw || raw === instance.instance) return [];
22
+ return [raw];
23
+ }
24
+
14
25
  /** Names an instance is directly related to (undirected edge endpoints):
15
- * its spawn parent plus its explicit sibling link. Kernel contract
16
- * (feature/agent-relations, final): `parentInstance` and `siblingInstance`
17
- * (string, only set when a sibling relation was declared against a ROOT
18
- * instance — a sibling of a non-root simply shares the anchor's parent).
19
- * Absent fields contribute no edges. */
26
+ * its spawn parent plus its explicit sibling link (`siblingLinksOf`). Kernel
27
+ * contract (feature/agent-relations, final): `parentInstance` and
28
+ * `siblingInstance`. Absent fields contribute no edges. */
20
29
  export function instanceLinks(instance) {
21
30
  const out = [];
22
31
  if (instance.parentInstance) out.push(instance.parentInstance);
23
- if (instance.siblingInstance) out.push(instance.siblingInstance);
32
+ out.push(...siblingLinksOf(instance));
24
33
  return out.filter((name) => name && name !== instance.instance);
25
34
  }
26
35
 
@@ -65,6 +74,39 @@ function rosterOrder(a, b) {
65
74
  return String(a.instance).localeCompare(String(b.instance)) || (ia < ib ? -1 : ia > ib ? 1 : 0);
66
75
  }
67
76
 
77
+ /** Each instance's siblings by EXPLICIT link (#1312): Y is X's sibling when X's sibling link
78
+ * (`siblingLinksOf`) resolves to Y (`resolveLinkId` over `instances`), or Y's resolves to X. So both
79
+ * ends of a link name each other. Direct links only (a chain C→B→A gives B [A, C], A [B], C [B]; A and
80
+ * C are not inferred), self excluded, de-duplicated by instanceId, each list in the roster's order
81
+ * (`rosterOrder`). Instances that share a parent are not siblings here (their relation is "under
82
+ * <parent>"), and `relation`/`relativeTo` are not read: they record how an instance was spawned, not a
83
+ * current relation. Pass one deployment's FULL roster, never a filtered list: dropping rows can turn an
84
+ * ambiguous name into a false unique one. Returns Map<instanceId, instance[]>; an instance with no
85
+ * sibling is absent from the map. */
86
+ export function instanceSiblings(instances) {
87
+ const byId = new Map(instances.map((i) => [instanceId(i), i]));
88
+ const byName = new Map();
89
+ for (const i of instances) {
90
+ if (!byName.has(i.instance)) byName.set(i.instance, []);
91
+ byName.get(i.instance).push(i);
92
+ }
93
+ const ids = new Map(); // id -> Set of sibling ids
94
+ const add = (a, b) => {
95
+ if (!ids.has(a)) ids.set(a, new Set());
96
+ ids.get(a).add(b);
97
+ };
98
+ for (const i of instances) {
99
+ const id = instanceId(i);
100
+ for (const name of siblingLinksOf(i)) {
101
+ const other = resolveLinkId(i, name, byName);
102
+ if (!other || other === id) continue;
103
+ add(id, other);
104
+ add(other, id);
105
+ }
106
+ }
107
+ return new Map([...ids].map(([id, set]) => [id, [...set].map((s) => byId.get(s)).sort(rosterOrder)]));
108
+ }
109
+
68
110
  /** Group instances into agent CLUSTERS — connected components of the
69
111
  * undirected relation graph (parent/child spawn edges + sibling links).
70
112
  * Unrelated instances are single-node clusters. Within a cluster the
@@ -58,6 +58,13 @@ export function createSoulCatalog({ terms, exec, invoke = (cli, options) => exec
58
58
  const pending = catalog.revalidate(deployment, cli, key, options);
59
59
  return pending && pending.then(project);
60
60
  }
61
+ /** A LIVE read for this workspace state (maxAge 0), asked for by the user (the TUI's `r`): one read under
62
+ * the state's key, or the live same-key read in flight, joined. What is held stays held beside it, so a
63
+ * read that fails lands as the held souls with its `reason` next to them, as a failed read of a moved key
64
+ * does. Resolves with the landed, projected entry. */
65
+ function refresh(deployment, cli, workspaceStatus) {
66
+ return catalog.refresh(deployment, cli, soulCatalogKey(cli, workspaceStatus)).then(project);
67
+ }
61
68
  return {
62
69
  /** The catalog for this workspace state, reading it only when needed. */
63
70
  async observe(deployment, cli, workspaceStatus, options = {}) {
@@ -67,6 +74,7 @@ export function createSoulCatalog({ terms, exec, invoke = (cli, options) => exec
67
74
  /** Synchronous decision for this workspace state: what is held now, and what (if anything) is still coming. */
68
75
  settle,
69
76
  revalidate,
77
+ refresh,
70
78
  /** Start an unbound read when nothing usable is held and nothing is in flight; null when nothing started. */
71
79
  prefetch(deployment, cli, options = {}) { const flight = catalog.prefetch(deployment, cli, options); return flight && flight.then(project); },
72
80
  refreshing: catalog.refreshing,
@@ -40,6 +40,13 @@ export function spawnRefusal(agent, cli) {
40
40
  }
41
41
  /** The line a soul a spawn here would refuse carries, beside its disabled Spawn. */
42
42
  export const cantSpawnLine = refusal => `Can't spawn here · ${refusal}`;
43
+ /** Whether a soul row matches a client's soul filter: its name, its description or where it comes from
44
+ * (`repoName`) contains the query, case aside. An empty query matches every row; whether to trim it is the
45
+ * client's. */
46
+ export function soulMatches(row, query) {
47
+ const needle = String(query).toLowerCase();
48
+ return [row.name, row.description, row.repoName].some((value) => String(value || '').toLowerCase().includes(needle));
49
+ }
43
50
 
44
51
  /** What a launch problem of a soul's report means, in the client's words: the report is the launch a spawn
45
52
  * that names none would get, and each problem is what the kernel reports of that spawn: why it would be
@@ -10,6 +10,7 @@
10
10
  import { displayLine } from './display-text.mjs';
11
11
  import { ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
12
12
  import { retainedSpawnMessage } from './launch-prompt-outcome.mjs';
13
+ import { catalogFailure } from './catalog-messages.mjs';
13
14
 
14
15
  const UNMATCHED = 'E_LAUNCH_PREFERENCE_UNMATCHED';
15
16
 
@@ -125,6 +126,13 @@ export function spawnProblem(reason, stage = 'preview') {
125
126
  return { fact: words.fact, next: words.next, code, detail: message ? `${code} · ${message}` : code };
126
127
  }
127
128
 
129
+ /** The sentence of a soul catalog read that failed (a held entry's `reason`), the same in every client:
130
+ * catalog-messages.mjs's, with the noun "souls". The kernel's message in it is text from outside: a
131
+ * client draws it through its display filter. */
132
+ export function soulCatalogFailure(reason) {
133
+ return catalogFailure('souls', reason);
134
+ }
135
+
128
136
  /** The spawn catalog's state, for the soul chooser. */
129
137
  export function catalogProblem(catalog) {
130
138
  if (!catalog) return '';
@@ -0,0 +1,15 @@
1
+ // The house fuzzy matcher, one copy for every client (the Desktop's palette and Quick Open, the TUI's
2
+ // palette and switcher): simple subsequence scoring — lower is better, null means no match, a prefix
3
+ // match gets a strong (negative) bonus. (No-match is null, NOT -1: the prefix bonus makes real scores
4
+ // negative, and the palette's legacy `sc < 0` no-match filter silently dropped exact prefix matches.)
5
+ export function subsequenceScore(text, query) {
6
+ const t = String(text).toLowerCase();
7
+ const s = String(query).toLowerCase();
8
+ let ti = 0, gaps = 0;
9
+ for (const ch of s) {
10
+ const found = t.indexOf(ch, ti);
11
+ if (found < 0) return null;
12
+ gaps += found - ti; ti = found + 1;
13
+ }
14
+ return gaps + (t.startsWith(s) ? -100 : 0);
15
+ }
@@ -36,7 +36,7 @@ never does.
36
36
  | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key and a bracketed paste out of them |
37
37
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
38
38
  | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
39
- | `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
39
+ | `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the Capabilities view (`capabilities.mjs`), the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
40
40
 
41
41
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
42
42
 
@@ -25,7 +25,7 @@ export const ACTIONS = Object.freeze([
25
25
  { id: "workspaces", keys: ["w"], label: "workspaces" },
26
26
  // The palette (docs/tui.md, "The palette"): from every focus it is the leader and then `k`.
27
27
  { id: "palette", keys: ["ctrl+k"], label: "palette" },
28
- { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal as a tab beside the list, or show its tab when it has one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"], ["souls", "show the selected soul's detail, and from the detail its instances, in the Souls view"]] },
28
+ { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal as a tab beside the list, or show its tab when it has one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"], ["souls", "show the selected soul's detail, and from the detail its instances, in the Souls view"], ["capabilities", "show the selected capability's detail, and from the detail the marked soul that uses it, in the Capabilities view"]] },
29
29
  // The Souls view (docs/tui.md, "The Souls view"): the selected soul's instances, in the
30
30
  // Instances view, filtered by that soul.
31
31
  { id: "soul-instances", keys: ["i"], label: "instances", views: [["souls", "the selected soul's instances, in the Instances view"]] },
@@ -18,9 +18,9 @@ export { remoteRosterState } from "../../client/remote-roster.mjs";
18
18
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
19
19
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
20
20
  export { shortPath, deploymentLabel } from "../../client/deployment-label.mjs";
21
- export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome } from "../../client/instance-tree.mjs";
21
+ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings } from "../../client/instance-tree.mjs";
22
22
  export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
23
- export { runtimeState, runtimeCounts, originLead } from "../../client/instance-presentation.mjs";
23
+ export { runtimeState, runtimeCounts, originLead, siblingText } from "../../client/instance-presentation.mjs";
24
24
  export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
25
25
  export { instanceActs, openAct } from "../../client/instance-acts.mjs";
26
26
  export { rowReason } from "../../client/remote-address.mjs";
@@ -36,13 +36,18 @@ export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
36
36
  export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
37
37
  export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
38
38
  export { soulRows } from "../../client/soul-rows.mjs";
39
- export { soulFacts, spawnRefusal } from "../../client/soul-facts.mjs";
39
+ export { soulFacts, spawnRefusal, soulMatches } from "../../client/soul-facts.mjs";
40
40
  export { createSpawnPreview } from "../../client/spawn-preview.mjs";
41
41
  export { defaultSpawnChoices } from "../../client/spawn-preview-contract.mjs";
42
42
  export { createSpawnApplyBoundary } from "../../client/spawn-apply.mjs";
43
43
  export { createSpawnTransaction } from "../../client/spawn-transaction.mjs";
44
- export { spawnProblem, outcomeWords, SPAWN_NEXT } from "../../client/spawn-messages.mjs";
44
+ export { spawnProblem, outcomeWords, SPAWN_NEXT, soulCatalogFailure } from "../../client/spawn-messages.mjs";
45
+ export { catalogFailure } from "../../client/catalog-messages.mjs";
45
46
  export { previewFacts } from "../../client/spawn-preview-facts.mjs";
47
+ export { subsequenceScore } from "../../client/subsequence-score.mjs";
48
+ export { createCapabilityCatalog, capabilityCatalogKey } from "../../client/capability-catalog.mjs";
49
+ export { memberNames, capabilitySource, groupCapabilities, hostKeyOf, capabilitySections, matchCapabilities, soulsComposition, rosterAgentName, layerLabel, capabilityUsers } from "../../client/capability-rows.mjs";
50
+ export { capabilityFacts, CAPABILITY_COPY } from "../../client/capability-facts.mjs";
46
51
 
47
52
  /** The words a shared sentence uses where it names the client that shows it (client-terms.mjs).
48
53
  * Made once, here: every shared function that takes `terms` is passed this constant, and refuses
@@ -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) {