@awebai/oats 0.66.0 → 0.68.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 (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
@@ -18,6 +18,9 @@
18
18
  * remoteCollecting, // boolean: the remote roster is being read
19
19
  * home, // string: the user's home directory, for the short label
20
20
  * at, // string: the ISO time of this call
21
+ * learned, // optional: Map<deployment path, identity read> (deployment-identity.mjs
22
+ * // `cliDeploymentIdentity` answers) of this computer's deployments, read before
23
+ * // they were observed: see `deploymentInfo` and `listedViews`
21
24
  * }
22
25
  *
23
26
  * These functions read no clock: the one time they stamp is `held.at`, and the same `held` gives the
@@ -42,6 +45,7 @@ import { publicDeployment } from './deployment-panel.mjs';
42
45
  import { teamMembers } from './team-members.mjs';
43
46
  import { requireTerms } from './client-terms.mjs';
44
47
  import { ROSTER_WORKSPACE_KEY } from './cli-adapter.mjs';
48
+ import { waitingClaim } from './waiting-on-you.mjs';
45
49
 
46
50
  /** Roots come ONLY from the kernel's observed `status.root`; before (or
47
51
  * without) an observation there is nothing to act on. No layout guess. */
@@ -73,6 +77,13 @@ export function rememberedGroups(held) {
73
77
  * `roster`. Without it a client makes no roster read (remote-roster.mjs `remoteRosterState`: "gated"). */
74
78
  export const cliReadsRemotes = (cli) => !!cli.ok && !!cli.remote?.includes("roster");
75
79
  const identityFeature = (held) => !!held.cli.features?.includes("workspace-identity");
80
+ /** What a projected `workspace` object (deployment-data.mjs) says of the identity: readIdentity's
81
+ * classification, `feature` when the CLI reports no identities, `invalid` when the projection marked it. */
82
+ const identityRead = (held, workspace) => (!identityFeature(held) ? { status: "feature" }
83
+ : workspace?.identityInvalid ? { status: "invalid" } : readIdentity(workspace));
84
+ /** The identity read learned of this computer's deployment `id` before it was observed (`held.learned`):
85
+ * the answer when the read answered, else null (not read, or the read failed). */
86
+ const learnedOf = (held, id) => { const read = held.learned?.get?.(id); return read?.ok === true ? read : null; };
76
87
  /** One deployment's identity, attachment, machine label and reason. */
77
88
  export function deploymentInfo(held, d, terms) {
78
89
  requireTerms(terms, 'deploymentInfo');
@@ -83,14 +94,16 @@ export function deploymentInfo(held, d, terms) {
83
94
  // it in its view, but it is stale, not live, and says why. Still reachable: this computer's own deployment.
84
95
  // Whether one is kept is deployment-facts.mjs `keptFailure`'s to say, never a test of the message.
85
96
  const kept = live ? keptFailure(entry) : null;
86
- const read = !live ? { status: "none" } : !identityFeature(held) ? { status: "feature" }
87
- : observed.reachable?.identityInvalid ? { status: "invalid" } : readIdentity(observed.reachable);
97
+ // Not observed (yet, or its read failed): the identity an identity read learned of it, when one did, places it
98
+ // in its view (`identityFrom: "learned"`); it stays not live, with its reading or unavailable sentence.
99
+ const learned = live ? null : learnedOf(held, d.id);
100
+ const read = live ? identityRead(held, observed.reachable) : learned ? identityRead(held, learned.workspace) : { status: "none" };
88
101
  const identity = read.status === "identity" ? read.identity : null;
89
102
  const attach = attachment(identity);
90
103
  // Not observed (yet): the reading or unavailable sentence, never a silent empty.
91
104
  const unavailable = live ? null : deploymentUnavailableText(observed || { status: "pending" }, terms);
92
105
  return { id: d.id, local: true, machine: terms.thisMachine, path: d.id, label: shortPath(d.id, { home: held.home }), name: d.name,
93
- live: live && !kept, reachable: live, ...(kept ? { stale: true } : {}), identityFrom: identity ? "reported" : null, identity, attach,
106
+ live: live && !kept, reachable: live, ...(kept ? { stale: true } : {}), identityFrom: identity ? (live ? "reported" : "learned") : null, identity, attach,
94
107
  teamLabel: identity?.defaultTeam?.label ?? null,
95
108
  ...reasonFields(deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref, unavailable,
96
109
  ...(kept ? { readError: kept.message, readErrorOrigin: kept.origin } : {}) }, terms)),
@@ -121,17 +134,58 @@ export function deploymentInfo(held, d, terms) {
121
134
  export function reasonFields(parts) {
122
135
  return parts ? { reason: parts.detail, short: parts.short, fix: parts.fix } : { reason: null, short: null, fix: [] };
123
136
  }
124
- /** The views and the per-deployment facts they rest on: `{ views, infos: Map<deploymentId, info> }`. */
125
- export function viewModel(held, terms) {
126
- requireTerms(terms, 'viewModel');
127
- const infos = new Map(deployments(held).map((d) => [d.id, deploymentInfo(held, d, terms)]));
128
- const views = buildViews([...infos.values()]).map((v) => {
137
+ /** buildViews' views over `infos`, each unattached one with its deployment's reason, short reason and ref. */
138
+ function viewsOver(infos) {
139
+ return buildViews([...infos.values()]).map((v) => {
129
140
  const unattachedReason = v.unattached ? infos.get(v.primary)?.reason ?? null : null;
130
141
  const unattachedShort = v.unattached ? infos.get(v.primary)?.short ?? null : null;
131
142
  const ref = v.unattached ? infos.get(v.primary)?.identity?.ref ?? null : null;
132
143
  return { ...v, ...(unattachedReason ? { reason: unattachedReason } : {}), ...(unattachedShort ? { short: unattachedShort } : {}), ...(ref ? { ref } : {}) };
133
144
  });
134
- return { views, infos };
145
+ }
146
+ /** The views and the per-deployment facts they rest on: `{ views, infos: Map<deploymentId, info> }`. */
147
+ export function viewModel(held, terms) {
148
+ requireTerms(terms, 'viewModel');
149
+ const infos = new Map(deployments(held).map((d) => [d.id, deploymentInfo(held, d, terms)]));
150
+ return { views: viewsOver(infos), infos };
151
+ }
152
+
153
+ /** Why an identity read of a listed deployment failed, as reason parts: `Timed out` for the read's time limit
154
+ * (a read that never began before its caller's budget ran out is answered the same), else `Not read`; the
155
+ * sentence is the unavailable one (deployment-facts.mjs), the kernel's words set apart when it gave them. */
156
+ function identityFailure(reason, terms) {
157
+ return { short: reason?.code === "E_CLI_TIMEOUT" ? "Timed out" : "Not read", detail: deploymentUnavailableText({ status: "unavailable", reason: reason || {} }, terms), fix: [] };
158
+ }
159
+ /** One row of this computer's deployments list (deployment-list.mjs: `{ path, name }`) that the client does not
160
+ * serve, as a switcher matches it: an info of `deploymentInfo`'s shape, never live or reachable, `listed: true`,
161
+ * named by the row (its folder's name, a local name to buildViews), with the identity an identity read learned
162
+ * of it (`held.learned`) and `read`: "pending" (no answer yet), "read" or "failed". Its reason says why it is not
163
+ * matched: the read's failure, or the shared reason of an identity that attaches to no workspace; none while it
164
+ * is pending or when it attaches. */
165
+ export function listedInfo(held, row, terms) {
166
+ requireTerms(terms, 'listedInfo');
167
+ const answer = held.learned?.get?.(row.path) ?? null, learned = answer?.ok === true ? answer : null;
168
+ const read = learned ? identityRead(held, learned.workspace) : { status: "none" };
169
+ const identity = read.status === "identity" ? read.identity : null;
170
+ const attach = attachment(identity);
171
+ const parts = answer === null ? null : !learned ? identityFailure(answer.reason, terms)
172
+ : deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref }, terms);
173
+ return { id: row.path, local: true, listed: true, machine: terms.thisMachine, path: row.path, label: shortPath(row.path, { home: held.home }), name: row.name,
174
+ live: false, reachable: false, identityFrom: identity ? "learned" : null, identity, attach, teamLabel: identity?.defaultTeam?.label ?? null,
175
+ read: answer === null ? "pending" : learned ? "read" : "failed", ...reasonFields(parts), note: null };
176
+ }
177
+ /** The switcher's views (#482): `viewModel`'s, with this computer's listed deployments the client does not serve
178
+ * matched in by the same rule (buildViews, over the served deployments first, then these). `listed`: the list's
179
+ * rows (`{ path, name }`), in its order; a row the client serves is passed over. A listed deployment whose
180
+ * identity attaches joins its workspace's view, or makes one; the others are `unmatched`, in order, each
181
+ * `listedInfo`'s answer. `{ views, infos, unmatched }`: `infos` holds the served deployments' and the matched
182
+ * listed ones'. Only a switcher reads this: a listed deployment is in no panel and no route. */
183
+ export function listedViews(held, listed, terms) {
184
+ requireTerms(terms, 'listedViews');
185
+ const model = viewModel(held, terms);
186
+ const offered = (Array.isArray(listed) ? listed : []).filter((row) => !model.infos.has(row?.path)).map((row) => listedInfo(held, row, terms));
187
+ const infos = new Map([...model.infos, ...offered.filter((info) => !info.attach.unattached).map((info) => [info.id, info])]);
188
+ return { views: viewsOver(infos), infos, unmatched: offered.filter((info) => info.attach.unattached) };
135
189
  }
136
190
  /** The view a selector names: a view id, or a deployment id (answered with the view that holds it, so
137
191
  * a selection saved before views opens its view). No selector means the first view. `model` is a
@@ -306,14 +360,25 @@ export function panelData(held, wsId, terms) {
306
360
  };
307
361
  }
308
362
 
363
+ /** Whether deployment `d` (a `deployments` entry) is live and current and one of its instance rows has a
364
+ * claim a row may show (waiting-on-you.mjs `waitingClaim`). Its rows are its own panel's
365
+ * (`deploymentPanel`: a local entry's rows, a remote group's), read from what the client holds. Not live
366
+ * (`info.live`: a stale or kept-failure local entry, a kept or unreached remote group, a deployment not
367
+ * observed) is never waiting: what it last said is unknown now. */
368
+ const deploymentWaits = (held, d, info) => info?.live === true && (deploymentPanel(held, d).instances || []).some((row) => waitingClaim(row) !== null);
369
+
309
370
  /** The switcher's list: views, not deployments. Each names its deployments (a client lets a caller
310
- * select any of these ids); an unattached view keeps today's remote fields and says why. `model` is a
311
- * view model already built for this call (`viewModel`); without one, it is built here. */
371
+ * select any of these ids); an unattached view keeps today's remote fields and says why. `waiting`
372
+ * (boolean): some deployment of the view is live and has an instance that needs input
373
+ * (`deploymentWaits`), from what the client holds, with no read: a view the client does not serve has no
374
+ * row here, and so no dot. `model` is a view model already built for this call (`viewModel`); without
375
+ * one, it is built here. */
312
376
  export function workspaceChoices(held, terms, model) {
313
377
  requireTerms(terms, 'workspaceChoices');
314
378
  if (model === undefined) model = viewModel(held, terms);
379
+ const served = deployments(held);
315
380
  return model.views.map((v) => {
316
- const primary = deployments(held).find((w) => w.id === v.primary);
381
+ const primary = served.find((w) => w.id === v.primary);
317
382
  const remoteOnly = v.deployments.every((id) => !model.infos.get(id)?.local);
318
383
  // Without the CLI's workspace-identity feature nothing can match: every deployment keeps its own entry, listed as
319
384
  // before views, not as "not matched" (each deployment's own reason still says why).
@@ -324,6 +389,7 @@ export function workspaceChoices(held, terms, model) {
324
389
  // The switcher's one-liner (UI spec, #482): the machines, in order and once each, and how many deployments aren't live.
325
390
  machines: [...new Set(v.deployments.map((id) => model.infos.get(id)?.machine).filter(Boolean))],
326
391
  notLive: v.deployments.filter((id) => !model.infos.get(id)?.live).length,
392
+ waiting: v.deployments.some((id) => { const d = served.find((w) => w.id === id); return !!d && deploymentWaits(held, d, model.infos.get(id)); }),
327
393
  ...(v.key ? { key: v.key } : {}), ...(unmatched ? { unattached: true } : {}), ...(unmatched && v.reason ? { reason: v.reason } : {}), ...(unmatched && v.short ? { short: v.short } : {}), ...(unmatched && v.ref ? { ref: v.ref } : {}),
328
394
  ...(remoteOnly && primary?.remote ? { server: primary.server, remote: true } : {}) };
329
395
  });
@@ -0,0 +1,32 @@
1
+ /** The suggested name's rules on the Desktop's side (feature spawn-suggest-name, awebai/oats#1421 §3 "The Desktop's use
2
+ * of it"). The kernel chooses the name (`spawn --preview --suggest-name`); these say when the dialog asks, how it
3
+ * remembers an answer, and how it says a numbered one. */
4
+ import { HARNESS_NAMES } from './harness-names.mjs';
5
+
6
+ /** The debounce before the dialog asks: it only keeps typing from making one read per keystroke. */
7
+ export const SUGGEST_DEBOUNCE_MS = 300;
8
+ /** The words a task needs before the dialog asks while it is typed (more than six). Spawn asks whatever the length. */
9
+ export const SUGGEST_MIN_WORDS = 7;
10
+
11
+ /** The words of `text`: whitespace-separated runs that hold a letter or a digit. */
12
+ export const taskWords = text => (String(text ?? '').match(/\S+/g) || []).filter(w => /[\p{L}\p{N}]/u.test(w)).length;
13
+
14
+ /** What an answer is remembered by: the exact task text, the soul (its root and name) and, for a spawn on another
15
+ * machine, that machine (`target`, its server id; null on this computer), so one host's answer never names another's. */
16
+ export const namingKey = (selector, text, target = null) => JSON.stringify([selector?.agentsRoot ?? null, selector?.soul ?? null, String(text ?? ''), target || null]);
17
+
18
+ const harnessName = harness => HARNESS_NAMES[harness] ?? (typeof harness === 'string' && harness ? harness : 'the harness');
19
+ /** Why a spawn was numbered, in the Desktop's words. The kernel's `message` is never shown: it can carry an exit
20
+ * code or a signal. */
21
+ export function numberedWords(reason, harness) {
22
+ switch (reason) {
23
+ case 'no-task': return 'there is no task to name it from';
24
+ case 'unsupported-harness': return `${harnessName(harness)} doesn't suggest names`;
25
+ case 'timeout': return 'naming took longer than 20 seconds';
26
+ case 'harness-failed': return `${harnessName(harness)} couldn't be asked for a name`;
27
+ case 'invalid-reply': return `${harnessName(harness)} gave no usable name`;
28
+ default: return 'it could not be named from its task';
29
+ }
30
+ }
31
+ /** "Named <instance>: <why>." for a spawn that was numbered. */
32
+ export const numberedLine = (instance, reason, harness) => `Named ${instance}: ${numberedWords(reason, harness)}.`;
@@ -1,7 +1,8 @@
1
1
  /** Fixed read-only API2 argv. Never dispatch API1 or fall back to spawn. */
2
2
  import { execFile } from 'node:child_process';
3
- import { parseEnvelope } from './cli-adapter.mjs';
4
- import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv } from './spawn-preview-contract.mjs';
3
+ import { parseEnvelope, writeTaskFile } from './cli-adapter.mjs';
4
+ import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv, suggestSupported, suggestTask, absolute,
5
+ instanceSuggestSupported, instanceSuggestRequest, instanceSuggestion } from './spawn-preview-contract.mjs';
5
6
  /** A refusal, in the kernel's own shape (`{ code, message, details: { fix } }`). `previewFailure` decides what of the
6
7
  * kernel's travels: its message when that is printable and within the bound, and its `fix` only beside that message.
7
8
  * No other key of `details` travels. */
@@ -9,24 +10,39 @@ function failure(code, message, kernelFix) {
9
10
  const { fix, ...error } = previewFailure(code, null, message, kernelFix).reason;
10
11
  return { schemaVersion: 1, ok: false, error: fix === undefined ? error : { ...error, details: { fix } } };
11
12
  }
12
- /** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
13
+ /** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`).
14
+ * With `task`, the read is a suggest read (feature spawn-suggest-name, awebai/oats#1421 §3): `--suggest-name` with the
15
+ * task in a private temporary `--task-file` (as the apply passes it), removed on every path, and never with a name or a
16
+ * purpose. `signal` ends it: the CLI gets SIGTERM, which ends the kernel's naming call with it, and the read answers
17
+ * `E_SUPERSEDED`. */
13
18
  export function cliSpawnPreview(cli, options = {}, io = {}) {
14
19
  // Defense at the actual exec owner as well as at HTTP admission.
15
20
  if (!previewSupported(cli)) return Promise.resolve(failure('E_PREVIEW_UNAVAILABLE'));
16
21
  const target = previewTarget(options.target), choices = previewChoices(options.choices);
17
- if (!target || !choices || Object.keys(options).some(k => !['target', 'choices', 'maxAge'].includes(k))) return Promise.resolve(failure('E_BAD_ARGS'));
22
+ if (!target || !choices || Object.keys(options).some(k => !['target', 'choices', 'maxAge', 'task', 'signal'].includes(k))) return Promise.resolve(failure('E_BAD_ARGS'));
23
+ const suggest = options.task !== undefined;
24
+ if (suggest && !suggestSupported(cli)) return Promise.resolve(failure('E_PREVIEW_UNAVAILABLE'));
25
+ if (suggest && (!suggestTask(options.task) || choices.name !== undefined || choices.purpose !== undefined)) return Promise.resolve(failure('E_BAD_ARGS'));
26
+ const signal = options.signal;
27
+ if (signal !== undefined && !(signal instanceof AbortSignal)) return Promise.resolve(failure('E_BAD_ARGS'));
28
+ if (signal?.aborted) return Promise.resolve(failure('E_SUPERSEDED'));
18
29
  // Feature spawn-preview-max-age: reuse member heads the kernel observed within maxAge seconds. Only
19
30
  // where the CLI advertises it (an older kernel refuses the flag); prepare never passes it. The apply's own
20
31
  // --max-age is spawn-apply-max-age's (spawn-apply-cli.mjs).
21
32
  const maxAge = options.maxAge;
22
33
  if (maxAge !== undefined && (!Number.isInteger(maxAge) || maxAge < 1 || maxAge > 3600)) return Promise.resolve(failure('E_BAD_ARGS'));
23
34
  const reuse = maxAge !== undefined && Array.isArray(cli.features) && cli.features.includes('spawn-preview-max-age') ? ['--max-age', String(maxAge)] : [];
24
- const argv = ['spawn', target.selector.soul, '--dir', target.context, '--agents-root', target.selector.agentsRoot, '--preview', ...choiceArgv(choices, cli), ...reuse, '--json'];
35
+ let taskFile = null;
36
+ if (suggest) { try { taskFile = writeTaskFile(options.task, io); } catch { return Promise.resolve(failure('E_CLI_FAILED')); } }
37
+ const naming = taskFile ? ['--suggest-name', '--task-file', taskFile.file] : [];
38
+ const argv = ['spawn', target.selector.soul, '--dir', target.context, '--agents-root', target.selector.agentsRoot, '--preview', ...naming, ...choiceArgv(choices, cli), ...reuse, '--json'];
25
39
  const env = { ...(io.env ?? process.env) };
26
40
  for (const k of ['PI_AGENTS_ROOT', 'OATS_DEPLOYMENT', 'OATS_RESOLUTION', 'OATS_PREVIEW_PREFLIGHT_BUDGET_MS']) delete env[k];
27
- return new Promise(resolve => {
41
+ return new Promise(done => {
42
+ const resolve = v => { taskFile?.cleanup(); done(v); };
28
43
  try {
29
- (io.exec ?? execFile)(cli.bin, argv, { cwd: target.context, env, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
44
+ (io.exec ?? execFile)(cli.bin, argv, { cwd: target.context, env, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024, ...(signal ? { signal } : {}) }, (err, stdout) => {
45
+ if (err?.name === 'AbortError' || signal?.aborted) return resolve(failure('E_SUPERSEDED'));
30
46
  if (err?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
31
47
  if (err?.killed) return resolve(failure('E_CLI_TIMEOUT'));
32
48
  const doc = parseEnvelope(stdout);
@@ -37,3 +53,38 @@ export function cliSpawnPreview(cli, options = {}, io = {}) {
37
53
  } catch { resolve(failure('E_CLI_FAILED')); }
38
54
  });
39
55
  }
56
+
57
+ /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): a name for a spawn on another
58
+ * machine, chosen here through this computer's harness and model. `request` is the dialog's (instanceSuggestRequest),
59
+ * `dir` the local deployment whose launch configurations the kernel reads. The task travels in a private temporary
60
+ * `--task-file`, removed on every path; never `--launch-config` (the dialog's configurations are the host's) and never
61
+ * `--server` (the kernel refuses it: the name is decided here). `signal` ends it as it ends a suggest read. Answers the
62
+ * kernel's envelope with its result re-validated (instanceSuggestion), or a failure in the kernel's shape. */
63
+ export function cliInstanceSuggestName(cli, { request, dir, signal } = {}, io = {}) {
64
+ if (!instanceSuggestSupported(cli)) return Promise.resolve(failure('E_UNSUPPORTED_OPTION'));
65
+ const asked = instanceSuggestRequest(request);
66
+ if (!asked || !absolute(dir) || signal !== undefined && !(signal instanceof AbortSignal)) return Promise.resolve(failure('E_BAD_ARGS'));
67
+ if (signal?.aborted) return Promise.resolve(failure('E_SUPERSEDED'));
68
+ let taskFile;
69
+ try { taskFile = writeTaskFile(asked.task, io); } catch { return Promise.resolve(failure('E_CLI_FAILED')); }
70
+ const argv = ['instance', 'suggest-name', '--soul', asked.soul, '--task-file', taskFile.file,
71
+ ...(asked.harness ? ['--harness', asked.harness] : []), ...(asked.model ? ['--model', asked.model] : []), '--dir', dir, '--json'];
72
+ const env = { ...(io.env ?? process.env) };
73
+ for (const k of ['PI_AGENTS_ROOT', 'OATS_DEPLOYMENT', 'OATS_RESOLUTION', 'OATS_PREVIEW_PREFLIGHT_BUDGET_MS']) delete env[k];
74
+ return new Promise(done => {
75
+ const resolve = v => { taskFile.cleanup(); done(v); };
76
+ try {
77
+ // The kernel bounds its call at 20 s (NAMING_TIMEOUT_MS) and its output at 4 KiB; this deadline adds the process's own start.
78
+ (io.exec ?? execFile)(cli.bin, argv, { cwd: dir, env, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 64 * 1024, ...(signal ? { signal } : {}) }, (err, stdout) => {
79
+ if (err?.name === 'AbortError' || signal?.aborted) return resolve(failure('E_SUPERSEDED'));
80
+ if (err?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
81
+ if (err?.killed) return resolve(failure('E_CLI_TIMEOUT'));
82
+ const doc = parseEnvelope(stdout);
83
+ if (doc?.ok === false) return resolve(failure(doc.error?.code, doc.error?.message, doc.error?.details?.fix));
84
+ if (err) return resolve(failure('E_CLI_FAILED'));
85
+ const result = doc?.ok === true ? instanceSuggestion(doc.result) : null;
86
+ resolve(result ? { schemaVersion: 1, ok: true, result } : failure('E_CLI_PROTOCOL'));
87
+ });
88
+ } catch { resolve(failure('E_CLI_FAILED')); }
89
+ });
90
+ }
@@ -128,6 +128,59 @@ function modulesOf(v, projected, composedFrom) {
128
128
  }
129
129
  export const previewSupported = cli => cli?.ok === true && absolute(cli.bin) && cli.spawnPreviewApi === 2
130
130
  && Array.isArray(cli.features) && cli.features.includes('spawn-preview-2');
131
+ /** Feature spawn-suggest-name (awebai/oats#1421 §3): `spawn --preview --suggest-name` also chooses the name, from the
132
+ * task, through the soul's harness. The Desktop asks only where it can also pass the name back (`spawn-name`). */
133
+ export const SUGGEST_NAME_FEATURE = 'spawn-suggest-name';
134
+ export const suggestSupported = cli => previewSupported(cli) && cli.features.includes(SUGGEST_NAME_FEATURE) && cli.features.includes('spawn-name');
135
+ /** Why a suggest read was numbered: the kernel's closed set. */
136
+ export const NAMING_REASONS = ['no-task', 'unsupported-harness', 'timeout', 'harness-failed', 'invalid-reply'];
137
+ /** The task a suggest read carries: the apply's bound (spawnPrepareInput), never blank. */
138
+ export const suggestTask = v => typeof v === 'string' && !v.includes('\0') && v.length <= 32768 && new TextEncoder().encode(v).byteLength <= 32768 && !!v.trim();
139
+ /** The preview's `naming`, or null when it is malformed. `suggested` names its harness and model (null: the harness's
140
+ * default); `numbered` names its reason. The kernel's `message` is not projected: it can carry an exit code or a
141
+ * signal, and the Desktop says the reason in its own words. */
142
+ export function namingOf(v) {
143
+ if (!record(v) || !Number.isSafeInteger(v.ms) || v.ms < 0) return null;
144
+ if (v.source === 'suggested') return name(v.harness) && (v.model === null || safe(v.model, 256) && !!v.model)
145
+ ? { source: 'suggested', ms: v.ms, harness: v.harness, model: v.model } : null;
146
+ if (v.source === 'numbered') return NAMING_REASONS.includes(v.reason) ? { source: 'numbered', reason: v.reason, ms: v.ms } : null;
147
+ return null;
148
+ }
149
+ /** How long the kernel's naming call may take (its own bound, the preview's and the apply's): an apply that also names
150
+ * its instance (`--suggest-name`) may take this much longer, and a caller's deadline allows for it. */
151
+ export const NAMING_TIMEOUT_MS = 20_000;
152
+ /** Feature instance-suggest-name (awebai/oats#1490 §2): `oats instance suggest-name` names, on this computer, a spawn that
153
+ * lands on another machine. The Desktop asks only where it can pass the name on (`spawn-name`). */
154
+ export const INSTANCE_SUGGEST_FEATURE = 'instance-suggest-name';
155
+ export const instanceSuggestSupported = cli => cli?.ok === true && absolute(cli.bin) && Array.isArray(cli.features)
156
+ && cli.features.includes(INSTANCE_SUGGEST_FEATURE) && cli.features.includes('spawn-name');
157
+ /** Feature spawn-apply-suggest-name (awebai/oats#1490 §3): an apply with `--suggest-name` names its instance itself, on the
158
+ * machine that spawns. Routed, the host must advertise it too: the route refuses the flag toward one that doesn't. */
159
+ export const APPLY_SUGGEST_FEATURE = 'spawn-apply-suggest-name';
160
+ /** The harnesses a suggest-name call may name (codex answers numbered, `unsupported-harness`, with no call). */
161
+ export const SUGGEST_HARNESSES = ['claude', 'pi', 'codex'];
162
+ /** The exact name a suggestion gives: the kernel's slug, within its cap. */
163
+ const SUGGESTED = new RegExp(`^(?=.{1,${INSTANCE_NAME_MAX}}$)[a-z0-9]+(?:-[a-z0-9]+)*$`);
164
+ /** `oats instance suggest-name`'s answer, `{ name?, naming }`, or null when it is malformed: `naming` as a preview's
165
+ * (namingOf), and `name` exactly when it was suggested. */
166
+ export function instanceSuggestion(v) {
167
+ if (!record(v) || Object.keys(v).some(k => !['name', 'naming'].includes(k))) return null;
168
+ const naming = namingOf(v.naming);
169
+ if (!naming) return null;
170
+ if (naming.source === 'suggested') return typeof v.name === 'string' && SUGGESTED.test(v.name) ? { name: v.name, naming } : null;
171
+ return Object.hasOwn(v, 'name') ? null : { naming };
172
+ }
173
+ /** The request of the dialog's suggest-name read: `{ action: 'suggest-name', soul, task, harness?, model? }`, or null.
174
+ * The soul is only a name (the host's, which needn't exist here); the model goes only with pi, the one harness whose
175
+ * naming follows it. */
176
+ export function instanceSuggestRequest(v) {
177
+ if (!exact(v, ['action', 'soul', 'task', 'harness', 'model']) || v.action !== 'suggest-name' || !soulName(v.soul) || !suggestTask(v.task)) return null;
178
+ if (v.harness !== undefined && !SUGGEST_HARNESSES.includes(v.harness)) return null;
179
+ if (v.model !== undefined && (v.harness !== 'pi' || !arg(v.model, 256))) return null;
180
+ return { action: 'suggest-name', soul: v.soul, task: v.task, ...(v.harness !== undefined ? { harness: v.harness } : {}), ...(v.model !== undefined ? { model: v.model } : {}) };
181
+ }
182
+ /** A soul's name as the kernel reads one: `<soul>`, `<package>/<soul>` or `<package>--<soul>`. */
183
+ const soulName = v => typeof v === 'string' && v.length <= 256 && v.split('/').length <= 2 && v.split('/').every(name);
131
184
  export function previewSelector(v) {
132
185
  return exact(v, ['soul', 'agentsRoot']) && name(v.soul) && absolute(v.agentsRoot) ? { soul: v.soul, agentsRoot: v.agentsRoot } : null;
133
186
  }
@@ -234,6 +287,7 @@ const errors = {
234
287
  E_CLI_TIMEOUT: 'The spawn preview timed out.', E_CLI_OUTPUT_LIMIT: 'The spawn preview exceeded its output limit.',
235
288
  E_CLI_PROTOCOL: 'The CLI returned an invalid or mismatched API 2 preview.', E_CLI_FAILED: 'The installed CLI could not complete the preview.',
236
289
  E_FORBIDDEN_FRAME: 'This frame cannot request a spawn preview.',
290
+ E_SUPERSEDED: 'A newer naming request replaced this one.',
237
291
  };
238
292
  const KERNEL_CODE = /^E_[A-Z0-9_]{1,63}$/;
239
293
  /** A kernel refusal keeps its own code and message (bounded, printable): the
@@ -304,6 +358,10 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
304
358
  const launchPromptAnswers = Object.hasOwn(v, 'launchPromptAnswers') ? launchPromptAnswersOf(v.launchPromptAnswers) : undefined;
305
359
  if (launchPromptAnswers === null) return null;
306
360
  const worktreeHooks = worktreeHooksOf(v.worktreeHooks);
361
+ // Feature spawn-suggest-name: how the name was chosen, on a suggest read only. A malformed one refuses the preview: its
362
+ // name is then not known to be the one a `--name` preview would give.
363
+ const naming = Object.hasOwn(v, 'naming') ? namingOf(v.naming) : undefined;
364
+ if (naming === null) return null;
307
365
  // Only reports carry `problem`: a preview that would hit one refuses with the error instead.
308
366
  if (Object.hasOwn(v, 'launch') && (launch === undefined || launch.problem !== null || launch.effective.harness !== e.harness || launch.effective.model !== e.model
309
367
  || launch.effective.launchConfig !== e.launchConfig)) return null;
@@ -315,6 +373,7 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
315
373
  preflight: { status: v.preflight.status, budgetMs: v.preflight.budgetMs, elapsedMs: v.preflight.elapsedMs }, messaging, teams, modules,
316
374
  ...(defaultTeam !== undefined ? { defaultTeam } : {}), ...(launch ? { launch } : {}),
317
375
  ...(launchPromptAnswers ? { launchPromptAnswers } : {}),
376
+ ...(naming ? { naming } : {}),
318
377
  // Capability warnings (0.49.0): the kernel's message strings, tolerant and idempotent (a malformed list reads as none,
319
378
  // never refuses the preview); absent on an older kernel. Shown only: the apply binds nothing on them.
320
379
  ...(Object.hasOwn(v, 'warnings') ? { warnings: previewWarningsOf(v.warnings) } : {}) };
@@ -77,13 +77,17 @@ function previewModules(modules) {
77
77
  return { core, caps };
78
78
  }
79
79
 
80
- export function previewFacts(data, { name = null, runsOn = null, cli = null } = {}) {
80
+ /** `unnamed`: what the Name fact says with no name yet. Given (the dialog's 'named from its task', where it will ask the
81
+ * kernel for one, feature spawn-suggest-name), the preview's numbered name is not the one Spawn creates: the facts
82
+ * derived from it, the home and the new branch, are left out until there is a name. */
83
+ export function previewFacts(data, { name = null, runsOn = null, cli = null, unnamed } = {}) {
81
84
  const preview = data && typeof data === 'object' ? data : {};
82
- const identity = [name ? { label: 'Name', text: name } : { label: 'Name', text: 'numbered by the kernel', muted: true }];
83
- const home = homeText(preview.home, preview.subject?.dir);
85
+ const pending = !name && unnamed !== undefined;
86
+ const identity = [name ? { label: 'Name', text: name } : { label: 'Name', text: unnamed ?? 'numbered by the kernel', muted: true }];
87
+ const home = pending ? null : homeText(preview.home, preview.subject?.dir);
84
88
  if (home) identity.push({ label: 'Home', text: home.text, title: home.title });
85
89
  const facts = [], fact = (label, parts, extra = {}) => { facts.push({ label, ...extra, parts }); };
86
- const worktree = preview.work === 'worktree' && preview.branch ? worktreeText(preview) : null;
90
+ const worktree = preview.work === 'worktree' && preview.branch && !pending ? worktreeText(preview) : null;
87
91
  if (worktree) fact('Works in', [{ text: worktree.lead }, { text: worktree.branch, mono: true }, ...(worktree.tail ? [{ text: worktree.tail }] : [])]);
88
92
  else if (preview.work) fact('Works in', [{ text: worksInText(preview.work) }]);
89
93
  if (preview.harness) {
@@ -13,9 +13,10 @@
13
13
  * refused there (E_DECISION_STALE, read as drifted), never applied. */
14
14
  import { dirname } from 'node:path';
15
15
  import { performance } from 'node:perf_hooks';
16
- import { cliSpawnPreview } from './spawn-preview-cli.mjs';
16
+ import { cliSpawnPreview, cliInstanceSuggestName } from './spawn-preview-cli.mjs';
17
17
  import { admitInstance } from './instance-admission.mjs';
18
- import { absolute, record, previewSelector, previewChoices, previewSupported, previewFailure, previewData, previewComposedFrom } from './spawn-preview-contract.mjs';
18
+ import { absolute, record, previewSelector, previewChoices, previewSupported, previewFailure, previewData, previewComposedFrom, suggestSupported, suggestTask,
19
+ instanceSuggestSupported, instanceSuggestRequest, instanceSuggestion } from './spawn-preview-contract.mjs';
19
20
  /** One preview's flights: its two-slot budget (`slots`), the flights in the air per invoker (`byInvoker`, where
20
21
  * exact duplicates coalesce), and the monotonic clock that stamps each flight's start (`started`). The cache is
21
22
  * given the same clock: it orders flight starts against invalidations, so a flight that started before its
@@ -139,10 +140,85 @@ export function createSpawnPreviewBoundary({ invoke = cliSpawnPreview, cache = n
139
140
  } catch { return previewFailure('E_CLI_FAILED'); }
140
141
  };
141
142
  }
143
+ /** The suggest read (feature spawn-suggest-name, awebai/oats#1421 §3): a preview that also names the instance from its
144
+ * task, `{ action: 'suggest', selector, choices, task }`, with no name or purpose among the choices. It has its own
145
+ * lane, outside the previews' two slots: ONE read per workspace, and a newer one ends the older (its CLI gets
146
+ * SIGTERM, which ends the kernel's naming call too) and the older answers E_SUPERSEDED. Nothing of it is cached here
147
+ * (the dialog caches by task), except that a suggested answer IS the preview of `--name <instance>` (the kernel's
148
+ * contract), so it is held as that preview's answer, for the dialog's next read and for prepare. */
149
+ export function createSpawnSuggestBoundary({ invoke = cliSpawnPreview, cache = null, maxAge = null, flights, exec } = {}) {
150
+ if (!flights?.clock) throw missing('createSpawnSuggestBoundary', 'flights (createSpawnPreviewFlights)');
151
+ if (cache && cache.clock !== flights.clock) throw new TypeError('createSpawnSuggestBoundary: the cache must run on the flights\' clock');
152
+ const lanes = new Map(), io = exec ? [{ exec }] : [];
153
+ return async function suggest(request, getContext) {
154
+ let lane = null, workspace = null;
155
+ try {
156
+ if (!record(request) || request.action !== 'suggest' || Object.keys(request).some(k => !['action', 'selector', 'choices', 'task'].includes(k))) return previewFailure('E_BAD_ARGS');
157
+ const selector = previewSelector(request.selector), choices = previewChoices(request.choices);
158
+ if (!selector || !choices || !suggestTask(request.task) || choices.name !== undefined || choices.purpose !== undefined) return previewFailure('E_BAD_ARGS');
159
+ const context = getContext(), selected = admitSpawnSelection(selector, choices, context);
160
+ if (selected.error) return previewFailure(selected.error);
161
+ const { target, identity, cli } = selected;
162
+ if (!suggestSupported(cli)) return previewFailure('E_UNSUPPORTED_OPTION', target);
163
+ workspace = target.workspace;
164
+ lanes.get(workspace)?.abort();
165
+ lane = new AbortController(); lanes.set(workspace, lane);
166
+ const startedAt = flights.clock();
167
+ const reuse = maxAge !== null && cli.features.includes('spawn-preview-max-age') ? { maxAge } : {};
168
+ const envelope = await invoke(cli, { target, choices, task: request.task, signal: lane.signal, ...reuse }, ...io);
169
+ if (lane.signal.aborted) return previewFailure('E_SUPERSEDED', target);
170
+ if (envelope?.schemaVersion !== 1 || envelope.ok !== true) return previewFailure(envelope?.error?.code, target, envelope?.error?.message, envelope?.error?.details?.fix);
171
+ const data = previewData(envelope.result, target, { composedFrom: previewComposedFrom(cli) });
172
+ if (!data?.naming) return previewFailure('E_CLI_PROTOCOL', target);
173
+ const current = admitSpawnSelection(selector, choices, getContext());
174
+ if (current.identity !== identity) return previewFailure('E_TARGET_CHANGED', target);
175
+ const result = { spawnPreviewViewApi: 1, status: 'available', target, data, reason: null };
176
+ if (cache && data.naming.source === 'suggested') {
177
+ // The choices as a read of `--name <instance>` admits them (previewChoices's order), so its identity is the same.
178
+ const namedChoices = previewChoices({ ...choices, name: data.instance }), named = namedChoices && admitSpawnSelection(selector, namedChoices, getContext());
179
+ if (named && !named.error) { const { naming, ...plain } = data; cache.set(named.identity, workspace, { ...result, data: plain }, startedAt); }
180
+ }
181
+ return result;
182
+ } catch { return previewFailure('E_CLI_FAILED'); }
183
+ finally { if (lane && lanes.get(workspace) === lane) lanes.delete(workspace); }
184
+ };
185
+ }
186
+ /** The suggest-name read (feature instance-suggest-name, awebai/oats#1490 §2): a name, chosen on this computer, for a spawn
187
+ * on another machine, `{ action: 'suggest-name', soul, task, harness?, model? }` (instanceSuggestRequest). It is addressed
188
+ * to one of this computer's deployments, whose launch configurations the kernel reads (`--dir`); nothing of the soul is
189
+ * admitted here (it is the host's). One read per deployment: a newer one ends the older (its CLI gets SIGTERM, which ends
190
+ * the kernel's naming call too) and the older answers E_SUPERSEDED. Nothing is cached here (the dialog caches by task).
191
+ * Answers `{ spawnPreviewViewApi: 1, status: 'available', workspace, data: { name?, naming }, reason: null }`. */
192
+ export function createInstanceSuggestBoundary({ invoke = cliInstanceSuggestName, exec } = {}) {
193
+ const lanes = new Map(), io = exec ? [{ exec }] : [];
194
+ return async function suggestName(request, getContext) {
195
+ let lane = null, workspace = null;
196
+ try {
197
+ const asked = instanceSuggestRequest(request);
198
+ if (!asked) return previewFailure('E_BAD_ARGS');
199
+ const { workspace: w, cli } = getContext();
200
+ if (!w || typeof w.id !== 'string' || !w.id || !absolute(w.scope)) return previewFailure('E_WORKSPACE_UNKNOWN');
201
+ if (w.remote || w.server) return previewFailure('unsupported-remote-operation');
202
+ if (!instanceSuggestSupported(cli)) return previewFailure('E_UNSUPPORTED_OPTION');
203
+ workspace = w.id;
204
+ lanes.get(workspace)?.abort();
205
+ lane = new AbortController(); lanes.set(workspace, lane);
206
+ const envelope = await invoke(cli, { request: asked, dir: w.scope, signal: lane.signal }, ...io);
207
+ if (lane.signal.aborted) return previewFailure('E_SUPERSEDED');
208
+ if (envelope?.schemaVersion !== 1 || envelope.ok !== true) return previewFailure(envelope?.error?.code, null, envelope?.error?.message, envelope?.error?.details?.fix);
209
+ const data = instanceSuggestion(envelope.result);
210
+ if (!data) return previewFailure('E_CLI_PROTOCOL');
211
+ return { spawnPreviewViewApi: 1, status: 'available', workspace, data, reason: null };
212
+ } catch { return previewFailure('E_CLI_FAILED'); }
213
+ finally { if (lane && lanes.get(workspace) === lane) lanes.delete(workspace); }
214
+ };
215
+ }
142
216
  export const PREVIEW_MAX_AGE_S = 60;
143
- /** One client's spawn preview: `{ read, prepareRead, cache }`.
217
+ /** One client's spawn preview: `{ read, prepareRead, suggest, cache }`.
144
218
  * read the dialog's read, through the cache; its kernel reads may reuse recent member heads (maxAge,
145
219
  * where the CLI declares spawn-preview-max-age)
220
+ * suggest the suggest read (createSpawnSuggestBoundary): its own lane, one per workspace, the newer ending the older
221
+ * suggestName the suggest-name read (createInstanceSuggestBoundary): a name chosen here for a spawn on another machine
146
222
  * prepareRead prepare's read (spawn-apply.mjs createSpawnApplyBoundary's `read`), through the same cache,
147
223
  * taking a held answer up to `prepareReuseMs` old (PREPARE_REUSE_MS), never with maxAge; a reusing
148
224
  * read and a live one never coalesce
@@ -159,6 +235,8 @@ export function createSpawnPreview({ invoke = cliSpawnPreview, exec, now = () =>
159
235
  return {
160
236
  read: createSpawnPreviewBoundary({ invoke, cache, maxAge, heldMs: ttlMs, flights, exec }),
161
237
  prepareRead: createSpawnPreviewBoundary({ invoke, cache, heldMs: prepareReuseMs, flights, exec }),
238
+ suggest: createSpawnSuggestBoundary({ invoke, cache, maxAge, flights, exec }),
239
+ suggestName: createInstanceSuggestBoundary({ exec }),
162
240
  cache: { invalidate: workspace => cache.invalidate(workspace), size: () => cache.size() },
163
241
  };
164
242
  }
@@ -33,7 +33,10 @@ export function teamMembers({ deployments = [], groups = [] }) {
33
33
  for (const row of rows.filter(r => team(r))) members.push(member(row, { deployment, server: group.server, serverLabel: label }));
34
34
  servers.push({ server: group.server, label, group: group.id, deployment: deployment.id, reached: group.probe?.ok === true,
35
35
  error: group.probe?.ok === true ? null : text(group.probe?.error?.message) ?? 'Server is unreachable',
36
- registered: group.registrationPresent === true });
36
+ registered: group.registrationPresent === true,
37
+ // The host's own kernel features as this computer's CLI relays them (server-probe-features): a list only
38
+ // when this read reached it and the list is one, else null (unknown, which is not supported).
39
+ features: group.probe?.ok === true && Array.isArray(group.probe.features) ? [...group.probe.features] : null });
37
40
  // A failed group holding no rows (last-known or current) is a server we have nothing to show for.
38
41
  if (group.probe?.ok !== true && !rows.length) notReached.push({ server: group.server, label, deployment: deployment.id });
39
42
  }
@@ -0,0 +1,25 @@
1
+ /** The workspace the leader's ↑ and ↓ move to (keymap.mjs `workspace-previous`, `workspace-next`): the
2
+ * next openable row of the sidebar's list of workspaces, as each client draws it, in one direction. Both
3
+ * clients read it; each draws its own list and opens what this answers.
4
+ *
5
+ * Pure: arguments in, a key out, nothing changed. A page loads this module: it imports nothing. */
6
+
7
+ /**
8
+ * The key of the next row with `openable` true from the row `currentKey`, in the direction `step`
9
+ * (+1, down the list; −1, up it), or null at an end: the list does not wrap. Rows that are not
10
+ * openable are passed over. With `currentKey` not among the rows (null included: nothing is open, or
11
+ * what is open is not listed), the first openable row for +1 and the last for −1, or null when none is.
12
+ * @param {{ key: string, openable: boolean }[]} rows the list as drawn, in its order
13
+ * @param {string | null} currentKey the row the client is on
14
+ * @param {1 | -1} step
15
+ * @returns {string | null}
16
+ */
17
+ export function workspaceStep(rows, currentKey, step) {
18
+ const list = Array.isArray(rows) ? rows : [];
19
+ const at = currentKey === null || currentKey === undefined ? -1 : list.findIndex((row) => row?.key === currentKey);
20
+ const dir = step < 0 ? -1 : 1;
21
+ for (let i = at === -1 ? (dir === 1 ? 0 : list.length - 1) : at + dir; i >= 0 && i < list.length; i += dir) {
22
+ if (list[i]?.openable === true) return list[i].key;
23
+ }
24
+ return null;
25
+ }
@@ -20,16 +20,16 @@ never does.
20
20
  | path | contents |
21
21
  |---|---|
22
22
  | `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
23
- | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList` |
23
+ | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList`; a resize and the keys typed to an agent told to the store (`passed`), which ends a line of one key |
24
24
  | `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one. The keys shared with the Desktop are not written here: the leader's table and the plain keys of the list come from `packages/client/keymap.mjs`, and `test/keymap.test.mjs` fails on a row of the shared table the TUI does not handle |
25
- | `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`) |
25
+ | `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`, Ctrl+X on every platform) |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
27
27
  | `lib/panel.mjs` | the open terminals, as tabs: the run's private tmux server (one control client, one window per tab, up to `MAX_TERMINALS`, each at the size its caller gives), the kernel's `oats session attach` in a pane of each, captures of the displayed tabs only (up to `MAX_SHOWN`, one per group of a split) when tmux says their pane changed, a hidden tab's output marking it, keys typed into the shown tab, and the sweep of what a dead run left; the only module that runs tmux (THE TABS in its header) |
28
- | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
29
- | `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test) |
30
- | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows, by calling the shared readers: pure, no cell position |
28
+ | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the identity reads of this computer's listed deployments the run has not opened (`createIdentityReads`: one at a time, under a budget, never on a timer), the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
29
+ | `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test), and each workspace's memory for the run (THE MEMORY OF A WORKSPACE: its place, its palette recency, and its tabs as it was left, opened again one at a time when it is opened again); the list of workspaces' focus and cursor, and the leader's moves between workspaces (the shared `workspaceStep`) |
30
+ | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows (a workspace and a line per deployment of it, matched by the shared `listedViews` over the served deployments and the identities the reads learned), and from those the list of workspaces (`workspaceList`: one row per workspace the switcher offers, by name, and its dot from what this run observes; `listWindow`: five rows at most), by calling the shared readers: pure, no cell position |
31
31
  | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock; under the kitty keyboard protocol it reads a `CSI … u` key as its legacy bytes read, a chord as its own id |
32
- | `lib/term/kitty.mjs` | the kitty keyboard protocol: the flags asked for, a `CSI … u` key read, and the bytes the same key sends without the protocol (`legacyBytes`), which is what an agent is typed |
32
+ | `lib/term/kitty.mjs` | the kitty keyboard protocol: the flags asked for, a `CSI … u` key read, and the bytes the same key sends without the protocol (`legacyBytes`), which is what an agent is typed; and the chords a terminal sends the same way without it (`legacyChordText`: Alt with a letter or a digit, the Alt and Alt+Shift arrows), which the TUI takes in every terminal |
33
33
  | `lib/term/width.mjs` | the cells a grapheme takes |
34
34
  | `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
35
35
  | `lib/term/style.mjs` | style values: the TUI's own (the sixteen ANSI colours and four attributes) and an agent's (its colours, 256 and RGB included, and attributes, from a capture) |
@@ -37,7 +37,7 @@ never does.
37
37
  | `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, a chord and a bracketed paste out of them and, under the kitty keyboard protocol, types every other key as its legacy bytes |
38
38
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
39
39
  | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame; the kitty keyboard protocol pushed, asked about and popped on every way out |
40
- | `lib/views/` | pure functions from the model and a size to rows of spans: the frame (the sidebar: its title, the accordion of the three views and the cheat sheet; the main area beside it), 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
+ | `lib/views/` | pure functions from the model and a size to rows of spans: the frame (the sidebar: the list of workspaces (`workspaces.mjs`) or its title, the accordion of the three views and the cheat sheet; the main area beside it), 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`) |
41
41
 
42
42
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
43
43