@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
@@ -28,37 +28,54 @@ export function inspectSessionTarget(target, io, { includeSize = false } = {}) {
28
28
  if (/can't find (window|session)/i.test(String(e.stderr || ""))) return { backend: "tmux", present: false, state: "stopped" };
29
29
  throw e;
30
30
  }
31
- if (!rows.length) return { backend: "tmux", present: false, state: "stopped" };
32
- if (rows.length !== 1) throw new Error("session window has multiple panes; choose an unsplit agent window");
33
- const [paneId, dead, command, panePid, cols, rowsCount] = rows[0].split("\t");
34
- if (!/^%\d+$/.test(paneId) || !["0", "1"].includes(dead)) throw new Error("invalid tmux pane response");
35
- if (includeSize && ![cols, rowsCount].every(value => /^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value)))) {
36
- throw new Error("invalid tmux pane response");
37
- }
38
- let state = dead === "1" ? "stopped" : "unknown";
39
- if (dead === "0" && shells.has(command)) {
40
- // macOS tmux can report the wrapper shell while the harness is its child.
41
- // Only a shell with no non-shell descendants is a fallback prompt.
42
- if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
43
- const output = (io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,comm="], {
44
- encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
45
- });
46
- const processes = output.split("\n").map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean);
47
- const descendants = new Set([panePid]);
48
- let active = false;
49
- for (let changed = true; changed;) {
50
- changed = false;
51
- for (const [, pid, parent, name] of processes) {
52
- if (descendants.has(parent) && !descendants.has(pid)) {
53
- descendants.add(pid); changed = true;
54
- if (!shells.has(basename(name).replace(/^-/, ""))) active = true;
31
+ return createSessionPaneInspector(io)(rows, { includeSize });
32
+ }
33
+ /** Interpret one window's panes with the lifecycle's shell/descendant rule. A status read shares
34
+ * one inspector across windows so both successful and failed process scans cost one child. */
35
+ export function createSessionPaneInspector(io) {
36
+ let processRead;
37
+ const readProcesses = () => {
38
+ if (!processRead) {
39
+ try {
40
+ const output = (io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,comm="], {
41
+ encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
42
+ });
43
+ processRead = { rows: output.split("\n").map(line => line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean) };
44
+ } catch (error) { processRead = { error }; }
45
+ }
46
+ if (processRead.error) throw processRead.error;
47
+ return processRead.rows;
48
+ };
49
+ return (rows, { includeSize = false } = {}) => {
50
+ if (!rows.length) return { backend: "tmux", present: false, state: "stopped" };
51
+ if (rows.length !== 1) throw new Error("session window has multiple panes; choose an unsplit agent window");
52
+ const [paneId, dead, command, panePid, cols, rowsCount] = rows[0].split("\t");
53
+ if (!/^%\d+$/.test(paneId) || !["0", "1"].includes(dead)) throw new Error("invalid tmux pane response");
54
+ if (includeSize && ![cols, rowsCount].every(value => /^[1-9]\d*$/.test(value) && Number.isSafeInteger(Number(value)))) {
55
+ throw new Error("invalid tmux pane response");
56
+ }
57
+ let state = dead === "1" ? "stopped" : "unknown";
58
+ if (dead === "0" && shells.has(command)) {
59
+ // macOS tmux can report the wrapper shell while the harness is its child.
60
+ // Only a shell with no non-shell descendants is a fallback prompt.
61
+ if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
62
+ const processes = readProcesses();
63
+ const descendants = new Set([panePid]);
64
+ let active = false;
65
+ for (let changed = true; changed;) {
66
+ changed = false;
67
+ for (const [, pid, parent, name] of processes) {
68
+ if (descendants.has(parent) && !descendants.has(pid)) {
69
+ descendants.add(pid); changed = true;
70
+ if (!shells.has(basename(name).replace(/^-/, ""))) active = true;
71
+ }
55
72
  }
56
73
  }
74
+ state = active ? "unknown" : "shell";
57
75
  }
58
- state = active ? "unknown" : "shell";
59
- }
60
- return { backend: "tmux", present: dead === "0", state, paneId,
61
- ...(includeSize && dead === "0" ? { size: { cols: Number(cols), rows: Number(rowsCount) } } : {}) };
76
+ return { backend: "tmux", present: dead === "0", state, paneId,
77
+ ...(includeSize && dead === "0" ? { size: { cols: Number(cols), rows: Number(rowsCount) } } : {}) };
78
+ };
62
79
  }
63
80
  // Settling gives a large bracketed paste time before the single Enter. Screen
64
81
  // bytes are observations only: neither change nor silence proves acceptance
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.28.0",
11
+ "ref": "v1.29.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.12.2",
46
+ "ref": "oats-framework/v1.12.3",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.59.0",
3
+ "version": "0.60.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -0,0 +1,93 @@
1
+ /** The deployment's capability table: `oats capabilities --json`, held per
2
+ * deployment and keyed by the workspace state it describes, so a read costs
3
+ * a kernel run only when that state moved (or the caller forces a live one),
4
+ * never on every poll or view open. The holding rules (one flight per
5
+ * deployment, last good table kept with the failure next to it, retry after
6
+ * RETRY_MS, unbound prefetch bound by the same cycle's settle) are
7
+ * keyed-catalog.mjs's; this module is the kernel read, the key and the shape.
8
+ *
9
+ * A client makes its own catalog and owns it: nothing is held at module level, so two catalogs
10
+ * share no flight and no held entry. It takes the client's terms (client-terms.mjs), which the
11
+ * default kernel read words its refusals with, and an optional `exec` that read runs the CLI
12
+ * through (cli-adapter.mjs `runJson`'s `io.exec`). */
13
+ import { cliWorkspace } from './workspace-cli.mjs';
14
+ import { requireTerms } from './client-terms.mjs';
15
+ import { capabilitiesData, observationData } from './deployment-data.mjs';
16
+ import { soulCatalogKey } from './soul-catalog.mjs';
17
+ import { createKeyedCatalog } from './keyed-catalog.mjs';
18
+
19
+ export const CAPABILITY_CATALOG_RETRY_MS = 60_000;
20
+ /** The client's own transport/probe codes (workspace-cli.mjs); any other code on
21
+ * an ok:false result is the kernel's own refusal, reported verbatim. */
22
+ const LOCAL_CODES = new Set(['E_CLI_UNAVAILABLE', 'E_WORKSPACE_FEATURE', 'E_CLI_FAILED', 'E_CLI_PROTOCOL', 'E_CLI_TIMEOUT', 'E_CLI_OUTPUT_LIMIT']);
23
+
24
+ /** What the catalog table depends on, from `oats workspace status --json` as
25
+ * projected by workspaceStatusData. Member capabilities move with member
26
+ * commits and the workspace commit (the soul key carries those, plus the
27
+ * CLI); package capabilities move with package identity (id/version/commit/
28
+ * integrity, i.e. the lock rows); whether the lock is current moves with
29
+ * declaredPackages/unsynced/stale (oats-local.yaml or the lock changed). The
30
+ * lock fact itself has no hash, so the package rows are its identity and
31
+ * its path/lockfileVersion only mark a different lock file altogether.
32
+ * Names, warnings, problems, defaults and clones are deliberately not here:
33
+ * they change without the table changing. */
34
+ export function capabilityCatalogKey(cli, workspaceStatus) {
35
+ const ws = workspaceStatus || {};
36
+ return JSON.stringify([soulCatalogKey(cli, workspaceStatus),
37
+ (ws.packages || []).map(p => [p.id ?? null, p.version ?? null, p.commit ?? null, p.integrity ?? null]),
38
+ ws.declaredPackages ?? [], ws.unsynced ?? [], ws.stale ?? [],
39
+ ws.lock ? [ws.lock.path ?? null, ws.lock.lockfileVersion ?? null] : null]);
40
+ }
41
+
42
+ export function createCapabilityCatalog({ terms, exec, invoke = (cli, options) => exec ? cliWorkspace(cli, options, terms, { exec }) : cliWorkspace(cli, options, terms), now = () => Date.now() } = {}) {
43
+ requireTerms(terms, 'createCapabilityCatalog');
44
+ async function read(deployment, cli, options) {
45
+ let result;
46
+ try { result = await invoke(cli, { action: 'capabilities', context: deployment, ...options }); }
47
+ catch { return { value: null, reason: { code: 'E_CLI_FAILED', message: '', kernel: false } }; }
48
+ if (result?.ok !== true) {
49
+ const code = typeof result?.reason?.code === 'string' ? result.reason.code : 'E_CLI_FAILED';
50
+ return { value: null, reason: { code, message: String(result?.reason?.message || ''), kernel: !LOCAL_CODES.has(code) } };
51
+ }
52
+ try { return { value: capabilitiesData(result.document), observedAt: observationData(result.document).observedAt }; } // a malformed stamp is no stamp; the table stands
53
+ catch { return { value: null, reason: { code: 'E_CLI_PROTOCOL', message: '', kernel: false } }; }
54
+ }
55
+ const catalog = createKeyedCatalog({ read, retryMs: CAPABILITY_CATALOG_RETRY_MS, now });
56
+ const project = (deployment, entry) => entry && { key: entry.key, capabilities: entry.value, reason: entry.reason, at: entry.at, observedAt: entry.observedAt, stale: entry.stale, refreshing: catalog.refreshing(deployment) };
57
+ const key = (cli, workspaceStatus) => capabilityCatalogKey(cli, workspaceStatus);
58
+ /** Synchronous decision for this workspace state, as the soul catalog's: `entry` is what is held now and
59
+ * `pending` the read it started or joined (null when none), both projected. Never awaits. */
60
+ function settle(deployment, cli, workspaceStatus, options = {}) {
61
+ const { entry, pending } = catalog.settle(deployment, cli, key(cli, workspaceStatus), options);
62
+ return { entry: project(deployment, entry), pending: pending && pending.then(landed => project(deployment, landed)) };
63
+ }
64
+ return {
65
+ /** Cold cycle: start the read alongside the roster reads, before the key is known. */
66
+ prefetch(deployment, cli, options = {}) { return catalog.prefetch(deployment, cli, options); },
67
+ /** Bind this cycle's key: a read starts only when the held table is not for this state (or its
68
+ * failure is old enough to retry) and none is in flight. Never awaits. */
69
+ ensure(deployment, cli, workspaceStatus, options = {}) { catalog.settle(deployment, cli, key(cli, workspaceStatus), options); },
70
+ settle,
71
+ /** The held table, immediately, whenever it is a healthy answer — a table past HELD_TTL_MS
72
+ * included: then this request starts (or joins) one re-read behind it and the answer says
73
+ * `refreshing` (stale-while-revalidate, request-driven: a Workspace-tab visit never waits for
74
+ * an `oats capabilities` run while the key is unchanged, and nobody looking costs nothing).
75
+ * Awaited only when nothing healthy is held: a first read, a held failure (table behind it or
76
+ * not — the boundary shows it as a failure and today's Retry is a plain read, so it reads now
77
+ * whatever the retry window says; the window throttles background cycles only), or a forced
78
+ * live read (refresh: true → maxAge 0). */
79
+ async read(deployment, cli, workspaceStatus, { refresh = false, maxAge } = {}) {
80
+ const k = key(cli, workspaceStatus), options = maxAge !== undefined ? { maxAge } : {};
81
+ if (refresh) return project(deployment, await catalog.refresh(deployment, cli, k));
82
+ const { entry } = catalog.settle(deployment, cli, k, options);
83
+ if (!entry?.value || entry.reason) return project(deployment, await catalog.demand(deployment, cli, k, options));
84
+ if (entry.stale) void catalog.revalidate(deployment, cli, k, options)?.catch(() => {});
85
+ return project(deployment, entry);
86
+ },
87
+ /** Read-only view of what is held (tests and diagnostics); nothing reads it on the request path. */
88
+ held(deployment) { return project(deployment, catalog.held(deployment)); },
89
+ refreshing: catalog.refreshing,
90
+ forget: catalog.forget,
91
+ forgetAll: catalog.forgetAll,
92
+ };
93
+ }
@@ -0,0 +1,59 @@
1
+ /** A capability's facts as its page shows them, for any client: the "Comes from" rows and what it
2
+ * provides, projected from the catalog row (`oats capabilities`, or a soul's resolved capability in the
3
+ * same shape) and workspace status. Only reported facts: a fact the kernel did not report is no row, and
4
+ * nothing is invented. The page's own words are CAPABILITY_COPY, so no client writes its own. */
5
+ import { memberNames, capabilitySource } from './capability-rows.mjs';
6
+
7
+ const text = v => typeof v === 'string' && v ? v : null;
8
+ const list = v => Array.isArray(v) ? v : [];
9
+ const short = v => typeof v === 'string' && /^[0-9a-f]{40}$/i.test(v) ? v.slice(0, 7) : v;
10
+
11
+ /** The capability page's own words. `souls(n)` is the "Used by" count; `behind(n)` follows an instance count, joined with ` · `. */
12
+ export const CAPABILITY_COPY = Object.freeze({
13
+ comesFrom: 'Comes from',
14
+ provides: 'Provides',
15
+ usedBy: 'Used by',
16
+ unlistable: 'Not listable: a spawn of it would refuse.',
17
+ none: 'None',
18
+ noSoul: 'No soul here includes it.',
19
+ noInstance: 'No instance carries it yet.',
20
+ souls: n => `${n} soul${n === 1 ? '' : 's'}`,
21
+ behind: n => `${n} on an older version`,
22
+ });
23
+
24
+ /** Where a package comes from, in workspace status terms: the official catalog or a git source. */
25
+ export function packageOrigin(source) {
26
+ if (!text(source)) return null;
27
+ if (source.startsWith('catalog:')) return 'official catalog';
28
+ const git = /^git:(?:[a-z]+:\/\/)?(?:[^@/]+@)?([^/:@]+)/i.exec(source);
29
+ return git ? `git · ${git[1]}` : source;
30
+ }
31
+ /** sha256-<64 hex> → sha256:9f2c…a71e (the full value stays in the title). */
32
+ export function fingerprint(integrity) {
33
+ const m = /^sha256-([0-9a-f]{64})$/i.exec(integrity || '');
34
+ return m ? `sha256:${m[1].slice(0, 4)}…${m[1].slice(-4)}` : text(integrity);
35
+ }
36
+
37
+ /** One "Comes from" row, [label, value] or [label, value, full], or none when the value is not reported text.
38
+ * `full` (the whole value, where the row shows it shortened) is kept only when it says more than the value. */
39
+ const fact = (label, value, full) => !text(value) ? [] : [text(full) && full !== value ? [label, value, full] : [label, value]];
40
+
41
+ /** `{ origin, provides }`. `origin`: the "Comes from" rows, in order: a package's Package, Pinned (its version
42
+ * and where it comes from), Commit and Fingerprint (the integrity workspace status reports for it, else the
43
+ * resolved capability's); a member or external capability's Repository, Latest, Path, Fingerprint (the Git
44
+ * tree of its directory, kernel #217) and Owned when it is private. `provides`: [label, names] for Skills,
45
+ * Commands and Hooks, each only when the row carries it; names is an array, or null when the kernel could
46
+ * not list them (a spawn of it would refuse). `names`: memberNames(status), when the caller holds it. */
47
+ export function capabilityFacts(row, { status, names = memberNames(status) } = {}) {
48
+ let origin;
49
+ if (row.kind === 'package') {
50
+ const pkg = list(status?.packages).find(p => p.id === row.package), integrity = pkg?.integrity || row.resolved?.from?.integrity;
51
+ origin = [...fact('Package', row.package), ...fact('Pinned', [row.version, packageOrigin(pkg?.source)].filter(Boolean).join(' · ')),
52
+ ...fact('Commit', short(row.commit), row.commit), ...fact('Fingerprint', fingerprint(integrity), integrity)];
53
+ } else {
54
+ origin = [...fact('Repository', capabilitySource(row, names).label, row.repoKey), ...fact('Latest', short(row.commit), row.commit), ...fact('Path', row.path),
55
+ ...fact('Fingerprint', short(row.tree), row.tree), ...(row.private === true ? fact('Owned', 'this repo\'s souls only') : [])];
56
+ }
57
+ const provides = [['Skills', row.skills], ['Commands', row.commands], ['Hooks', row.hooks]].filter(([, names]) => names !== undefined);
58
+ return { origin, provides };
59
+ }
@@ -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.61.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, 61, 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. */
@@ -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"]] },
@@ -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