@awebai/oats 0.55.0 → 0.56.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 +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +4 -4
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.55.1.md +45 -0
  16. package/docs/release-notes/v0.56.0.md +699 -0
  17. package/docs/servers.md +21 -5
  18. package/docs/souls-and-instances.md +8 -4
  19. package/docs/tui.md +99 -26
  20. package/docs/upgrading.md +4 -1
  21. package/docs/workspaces.md +26 -6
  22. package/lib/automations.mjs +3 -4
  23. package/lib/bounded-read.mjs +18 -0
  24. package/lib/capability-show.mjs +13 -2
  25. package/lib/claim.mjs +3 -4
  26. package/lib/core.mjs +480 -152
  27. package/lib/errors.mjs +39 -0
  28. package/lib/harness-trust-write.mjs +119 -40
  29. package/lib/harness-trust.mjs +31 -18
  30. package/lib/instance-inspect.mjs +160 -11
  31. package/lib/instance-lifecycle.mjs +47 -30
  32. package/lib/packages.mjs +8 -5
  33. package/lib/pi-bridge.mjs +18 -19
  34. package/lib/remote.mjs +88 -51
  35. package/lib/retire-output.mjs +9 -4
  36. package/lib/schedule.mjs +3 -4
  37. package/lib/servers.mjs +39 -6
  38. package/lib/session-viewer.mjs +25 -1
  39. package/lib/triggers.mjs +3 -4
  40. package/lib/workspace.mjs +6 -6
  41. package/lib/worktree.mjs +10 -6
  42. package/lib/write-through-private-file.mjs +26 -0
  43. package/package-catalog.json +3 -3
  44. package/package.json +1 -1
  45. package/packages/client/cli-adapter.mjs +108 -13
  46. package/packages/client/cli-locator.mjs +16 -14
  47. package/packages/client/deployment-panel.mjs +4 -3
  48. package/packages/client/display-text.mjs +2 -1
  49. package/packages/client/instance-events-contract.mjs +4 -3
  50. package/packages/client/instance-lifecycle.mjs +228 -0
  51. package/packages/client/instance-presentation.mjs +9 -0
  52. package/packages/client/instance-tree.mjs +10 -8
  53. package/packages/client/kernel-lines.mjs +3 -3
  54. package/packages/client/launch-contract.mjs +11 -0
  55. package/packages/client/lifecycle-cli.mjs +12 -6
  56. package/packages/client/lifecycle-confirmation.mjs +407 -0
  57. package/packages/client/lifecycle-contract.mjs +6 -2
  58. package/packages/client/own-codes.mjs +1 -0
  59. package/packages/client/panel-views.mjs +39 -2
  60. package/packages/client/readiness-contract.mjs +2 -2
  61. package/packages/client/remote-roster.mjs +50 -5
  62. package/packages/client/roster-sections.mjs +3 -3
  63. package/packages/client/session-start.mjs +98 -0
  64. package/packages/client/start-gate.mjs +46 -0
  65. package/packages/client/start-messages.mjs +17 -0
  66. package/packages/client/workspace-views.mjs +2 -2
  67. package/packages/record/README.md +4 -0
  68. package/packages/record/bin/recall.mjs +3 -2
  69. package/packages/tui/README.md +10 -6
  70. package/packages/tui/lib/actions.mjs +4 -2
  71. package/packages/tui/lib/client.mjs +5 -2
  72. package/packages/tui/lib/config.mjs +39 -9
  73. package/packages/tui/lib/main.mjs +83 -13
  74. package/packages/tui/lib/model.mjs +116 -11
  75. package/packages/tui/lib/open.mjs +45 -0
  76. package/packages/tui/lib/read.mjs +46 -10
  77. package/packages/tui/lib/store.mjs +64 -9
  78. package/packages/tui/lib/term/tty.mjs +71 -12
  79. package/packages/tui/lib/views/frame.mjs +115 -33
  80. package/packages/tui/lib/views/help.mjs +37 -8
  81. package/skills/oats-getting-started/SKILL.md +6 -3
@@ -2,6 +2,7 @@ import { harnessOf } from "./harness-names.mjs";
2
2
  import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
3
3
  import { madeByKernel } from "./kernel-made.mjs";
4
4
  import { waitingOnYouData } from "./waiting-on-you.mjs";
5
+ import { readIdentity } from "./workspace-views.mjs";
5
6
  /** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
6
7
  export function remoteWorkspace(group) {
7
8
  return {
@@ -97,10 +98,11 @@ const rosterError = (message) => ({ code: "E_REMOTE_ROSTER", message });
97
98
  * previous: { remoteGroups, rosterAnswered, rosterFailure }
98
99
  * outcome: { gated: true } no accepted CLI, or one that does not read other machines
99
100
  * (panel-views.mjs `cliReadsRemotes`): the read was not made
100
- * | { envelope } what the CLI answered (cli-adapter.mjs `cliRemoteRoster`)
101
+ * | { envelope, asked? } what the CLI answered (cli-adapter.mjs `cliRemoteRoster`); `asked`
102
+ * when the read passed workspace keys (#1124): { keys, keyOf }
101
103
  * | { thrown: string } the read failed: the message of what was thrown
102
104
  * at: the caller's time, the one `remotePanel` stamps
103
- * -> { remoteGroups, rosterAnswered, rosterFailure, reported }
105
+ * -> { remoteGroups, rosterAnswered, rosterFailure, reported, kept? }
104
106
  *
105
107
  * `remoteGroups` is the last readable roster: an answer replaces it only when every group of it can be
106
108
  * projected (`remotePanel`), and a failed read keeps the groups held, each marked not reached
@@ -108,6 +110,15 @@ const rosterError = (message) => ({ code: "E_REMOTE_ROSTER", message });
108
110
  * sentence, kept only while none has. `reported` is what the client hands to its memory of identities
109
111
  * (remote-identity-memory.mjs `observeIdentities`): the groups of an `ok` envelope, else null.
110
112
  *
113
+ * An answer read with workspace keys (`asked`) holds only the groups the kernel probed: those registered
114
+ * for one of `keys`, those of unknown workspace and those known only from saved routes. It replaces
115
+ * those. A held registered group it does not list, and whose last-known key (`keyOf(group)`:
116
+ * `lastKnownKey`) is one the read did not ask for, was not probed: it is kept as it was last read, after the answer's
117
+ * groups, and named in `kept` (its id, in order), so the caller keeps its read time (`keptReadTimes`).
118
+ * A held group whose key is unknown, or is one of `keys`, or that is known only from saved routes
119
+ * (`registrationPresent` false: the kernel always probes those), and that the answer does not list is
120
+ * gone, as after any answer. `reported` then holds the kept groups too, so the memory keeps their identities.
121
+ *
111
122
  * The sentence of a thrown read carries the message of an error from outside the client: a client
112
123
  * shows it through `displayLine` (display-text.mjs) only.
113
124
  *
@@ -130,6 +141,17 @@ export function remoteRosterState(previous, outcome, at) {
130
141
  const incoming = env.ok && Array.isArray(env.result?.groups)
131
142
  ? env.result.groups : unavailableGroups(previous.remoteGroups, env.error || rosterError(ROSTER_UNAVAILABLE));
132
143
  for (const group of incoming) remotePanel(group, at); // validate before replacing the last readable roster
144
+ if (env.ok && outcome.asked) {
145
+ const listed = new Set(incoming.map((g) => g?.id)), keys = new Set(outcome.asked.keys);
146
+ // Only a registered group can be outside the read: one known only from saved routes is always probed.
147
+ const kept = previous.remoteGroups.filter((g) => {
148
+ if (listed.has(g.id) || g.registrationPresent !== true) return false;
149
+ const key = outcome.asked.keyOf(g);
150
+ return key !== null && !keys.has(key);
151
+ });
152
+ const groups = [...incoming, ...kept];
153
+ return { remoteGroups: groups, rosterAnswered: true, rosterFailure: null, reported: groups, kept: kept.map((g) => g.id) };
154
+ }
133
155
  if (env.ok) return { remoteGroups: incoming, rosterAnswered: true, rosterFailure: null, reported: incoming };
134
156
  return { remoteGroups: incoming, rosterAnswered: previous.rosterAnswered,
135
157
  rosterFailure: previous.rosterAnswered ? previous.rosterFailure : env.error?.message || ROSTER_UNAVAILABLE, reported: null };
@@ -139,10 +161,33 @@ export function remoteRosterState(previous, outcome, at) {
139
161
  }
140
162
  }
141
163
 
142
- /** The panel of each group, keyed as a client's snapshot keys it: [[`remote:<group id>`, panel], …], every one made at `at`. */
143
- export function remotePanelEntries(remoteGroups, at) {
164
+ /** The panel of each group, keyed as a client's snapshot keys it: [[`remote:<group id>`, panel], …], every one made at `at`,
165
+ * except a group kept from an earlier read (`readAt`, a Map of group id → its read time: `keptReadTimes`), which is
166
+ * stamped with the time it was read: a read that did not probe it never makes it look newer. */
167
+ export function remotePanelEntries(remoteGroups, at, readAt = null) {
144
168
  requireTime(at, "remotePanelEntries");
145
- return remoteGroups.map((group) => { const panel = remotePanel(group, at); return [panel.workspace.id, panel]; });
169
+ return remoteGroups.map((group) => { const panel = remotePanel(group, readAt?.get(group.id) ?? at); return [panel.workspace.id, panel]; });
170
+ }
171
+
172
+ /** The workspace key a held group was last known by (#1124): the key its last reached read reported,
173
+ * else the one remembered for it (`remembered.get`, remote-identity-memory.mjs `identityMemory`), else
174
+ * null: unknown. Any reported key counts, member-derived included: a registration records the key the
175
+ * host reports, whatever its `keyFrom`. */
176
+ export function lastKnownKey(group, remembered) {
177
+ const reported = group?.probe?.ok === true ? readIdentity(group.workspace) : { status: "none" };
178
+ if (reported.status === "identity") return typeof reported.identity.key === "string" ? reported.identity.key : null;
179
+ const key = remembered?.get(group?.id)?.workspace?.key;
180
+ return typeof key === "string" ? key : null;
181
+ }
182
+
183
+ /** The read time of each kept group after one outcome (#1124): `times` is the Map held before it,
184
+ * `state` what `remoteRosterState` answered, `answeredAt` the time of the answer before this one (when a
185
+ * group first kept was last read). Only an answer changes it: a kept group keeps its time, or takes
186
+ * `answeredAt` when it was read by that answer; a group read now has none. A failed read, which marks
187
+ * every held group not reached, changes nothing; a gated one holds no group. */
188
+ export function keptReadTimes(times, state, answeredAt) {
189
+ if (!state.reported) return state.remoteGroups.length ? times : new Map();
190
+ return new Map((state.kept || []).map((id) => [id, times.get(id) ?? answeredAt]));
146
191
  }
147
192
 
148
193
  export function spawnedWorkspace(groups, result) {
@@ -19,10 +19,10 @@ export const primaryDeployment = deployments => (Array.isArray(deployments) && (
19
19
 
20
20
  /** A deployment's state, in words (never colour alone): `{ key, text, detail }`.
21
21
  * live: reached (or, on this computer, observed) now. stale: this computer's deployment whose last
22
- * re-read failed (its rows are the last observation). remembered: not reached, its workspace is the
23
- * last report. not reached / not observed: with why. */
22
+ * re-read failed, or a machine the last roster read did not ask for (#1124): its rows are the last
23
+ * observation. remembered: not reached, its workspace is the last report. not reached / not observed: with why. */
24
24
  export function deploymentState(d) {
25
- // This computer's deployment whose last re-read failed: its rows are the last observation.
25
+ // Its rows are the last observation: a failed re-read here, or a machine outside a filtered roster read.
26
26
  if (d?.stale) return { key: 'stale', text: 'stale', detail: d.reason || '' };
27
27
  if (d?.reachable) return { key: 'live', text: 'live', detail: '' };
28
28
  if (d?.identityFrom === 'remembered') {
@@ -0,0 +1,98 @@
1
+ /** The start and restart rule of an existing instance (#855, 5a-2): whether a row can be started now
2
+ * (`startGate`), the home a local start launches in (`verifiedLocalHome`), and the start itself
3
+ * (`startInstance`). A client decides through these and words nothing of its own for them, except the codes
4
+ * the rule leaves to it (below). Every function that words a sentence takes the client's `terms`
5
+ * (client-terms.mjs) and refuses a call without them. No state.
6
+ *
7
+ * A failed start is one of two outcomes, and the words are "nothing was started", never "nothing happened"
8
+ * (a restart that lost the race has already run its own stop, and a start may have written its pending receipt):
9
+ * refused this request started nothing: every refusal of the gate and of the home check, and the
10
+ * kernel's STARTED_NOTHING_CODES;
11
+ * uncertain anything else: no envelope, any other code, and E_START_UNCONFIRMED, the end of the wait
12
+ * for a start that goes on (cli-adapter.mjs cliStart: no deadline, START_WAIT_MS). That code
13
+ * carries no sentence: each client words it (the Desktop: renderer/start-unconfirmed.mjs).
14
+ * After any failed start, refused or uncertain, the client reads the row again before it offers anything. */
15
+ import { basename, dirname, sep } from 'node:path';
16
+ import { cliStart } from './cli-adapter.mjs';
17
+ import { harnessFlag } from './harness-names.mjs';
18
+ import { startGate } from './start-gate.mjs';
19
+ import { retainedSpawnDetails } from './launch-prompt-outcome.mjs';
20
+ import { displayLine } from './display-text.mjs';
21
+ import { requireTerms } from './client-terms.mjs';
22
+
23
+ /** The gate is page-safe and lives apart (start-gate.mjs); a client takes it from here, with the rest of the rule. */
24
+ export { startGate };
25
+
26
+ /** The kernel's codes for a start that started nothing: the home's start lock is held, or an earlier start's
27
+ * pane is still a shell without its completion marker (E_SESSION_START_BUSY); the instance was seen running,
28
+ * or its window appeared during the start (E_SESSION_RUNNING). Some places that raise E_SESSION_RUNNING come
29
+ * after the kernel has written the start's pending receipt, or after a restart's stop: nothing was started,
30
+ * not nothing happened. A code joins only when every place the kernel raises it in a start launches nothing. */
31
+ export const STARTED_NOTHING_CODES = Object.freeze(['E_SESSION_START_BUSY', 'E_SESSION_RUNNING']);
32
+
33
+ /** The two kernel codes' own sentences, for a client that words by code. The kernel's message is the
34
+ * answer's `detail`, through the display filter. E_SESSION_START_BUSY says no more than busy: the kernel answers
35
+ * it for a start lock that is there, which a start that ended without removing it leaves behind too. */
36
+ const STARTED_NOTHING = Object.freeze({
37
+ E_SESSION_START_BUSY: 'OATS refused this start as busy. Nothing was started.',
38
+ E_SESSION_RUNNING: 'This instance is already running. Nothing was started.',
39
+ });
40
+ const CLI_FAILED = 'The start could not be confirmed: the call to the OATS CLI failed. Refresh its status before starting it again.';
41
+
42
+ /** The home a local start launches in, or null. It is DERIVED and VERIFIED, never trusted from roster data
43
+ * alone: the exact home the kernel's status reported for this row in one of `deployments` (`[{ id, remote,
44
+ * instances }]`: a deployment's directory and the rows it reported), canonicalizing to …/instances/<name>
45
+ * inside that deployment's canonical directory. `realpath` is the caller's; this reads no file system of its
46
+ * own. A server's row has no local home. */
47
+ export function verifiedLocalHome(row, deployments, realpath) {
48
+ if (!row?.home || typeof row.home !== 'string' || row.server) return null;
49
+ let real;
50
+ try { real = realpath(row.home); } catch { return null; }
51
+ if (basename(real) !== String(row.instance) || basename(dirname(real)) !== 'instances') return null;
52
+ for (const w of deployments || []) {
53
+ if (w.remote) continue;
54
+ if (!(w.instances || []).some(i => !i.server && i.instance === row.instance && i.home === row.home)) continue;
55
+ let scope;
56
+ try { scope = realpath(w.id); } catch { continue; }
57
+ if (real.startsWith(scope.endsWith(sep) ? scope : scope + sep)) return real;
58
+ }
59
+ return null;
60
+ }
61
+
62
+ /** Start or restart one row.
63
+ * choices { model, launchConfig, harness, yolo }: the launch choices, each one argv value
64
+ * restart a restart (the kernel's one call, never a stop then a start)
65
+ * localCwd where a server's start runs from (this machine's own directory)
66
+ * verifyHome(row) -> canonical home | null the caller's local home check; default verifiedLocalHome over
67
+ * `deployments` and `realpath`
68
+ * start the CLI call (cli-adapter.mjs cliStart, with its own session and its wait); `exec`, `after` and
69
+ * `wait` pass to it
70
+ * -> { ok: true, result } | { ok: false, outcome, code, sentence, detail, ran, incomplete? }
71
+ * `ran`: whether the CLI was called (E_CLI_FAILED: the call was made and failed; whether the CLI began is not
72
+ * known). `sentence` is null for a code the client words (E_START_UNCONFIRMED) and
73
+ * for one it does not know: it then shows `detail`, the kernel's message through the display filter.
74
+ * `incomplete`: a start that stopped at a launch prompt (E_SPAWN_INCOMPLETE) and names this row, decoded. */
75
+ export async function startInstance(cli, row, choices = {}, { restart = false, deployments = [], realpath, localCwd, verifyHome, start = cliStart, exec, after, wait, terms } = {}) {
76
+ requireTerms(terms, 'startInstance');
77
+ const refused = (code, sentence, more = {}) => ({ ok: false, outcome: 'refused', code, sentence, detail: null, ran: false, ...more });
78
+ const gate = startGate(cli, row, { restart, choices }, terms);
79
+ if (gate) return refused(gate.code, gate.sentence, gate.detail ? { detail: gate.detail } : {});
80
+ const local = !row.server;
81
+ if (local && !(verifyHome ? verifyHome(row) : verifiedLocalHome(row, deployments, realpath)))
82
+ return refused('E_HOME_UNVERIFIED', 'Instance home is outside the workspace instances layout');
83
+ let envelope;
84
+ // A call that could not be made, or failed on its way (an exec that throws, a rejected call), is uncertain like
85
+ // any answer this cannot read: the CLI may have begun the start. Its words are the rule's; the exception's text
86
+ // is no kernel's message, and is not passed on as `detail`.
87
+ try { envelope = await start(cli.bin, { home: row.home, model: choices.model, launchConfig: choices.launchConfig, harness: choices.harness,
88
+ harnessFlag: harnessFlag(cli), yolo: choices.yolo, restart, workspaceDir: local ? dirname(row.agentsRoot) : localCwd, server: row.server },
89
+ { ...(exec ? { exec } : {}), ...(after ? { after } : {}), ...(wait !== undefined ? { wait } : {}) }); }
90
+ catch { return { ok: false, outcome: 'uncertain', code: 'E_CLI_FAILED', sentence: CLI_FAILED, detail: null, ran: true }; }
91
+ if (envelope?.ok === true) return { ok: true, result: envelope.result };
92
+ const code = typeof envelope?.error?.code === 'string' ? envelope.error.code : 'E_CLI_PROTOCOL';
93
+ const detail = displayLine(envelope?.error?.message);
94
+ const kept = code === 'E_SPAWN_INCOMPLETE' ? retainedSpawnDetails(envelope.error.details) : null;
95
+ return { ok: false, outcome: STARTED_NOTHING_CODES.includes(code) ? 'refused' : 'uncertain', code,
96
+ sentence: Object.hasOwn(STARTED_NOTHING, code) ? STARTED_NOTHING[code] : null, detail, ran: true,
97
+ ...(kept?.launchPrompts && kept.instance === row.instance ? { incomplete: kept } : {}) };
98
+ }
@@ -0,0 +1,46 @@
1
+ /** The start rule's gate (#855, 5a-2): whether a row can be started, or restarted, now. Its own module, apart from
2
+ * session-start.mjs (which re-exports it, and is where a client takes it from), because the Desktop's page decides
3
+ * by it too and a page loads no Node builtin: this module imports none, and none of its imports does
4
+ * (packages/desktop/test/inventory.test.mjs). Every sentence takes the client's `terms`. No state. */
5
+ import { canAddressRemote, unaddressableSentence } from './remote-address.mjs';
6
+ import { displayLine } from './display-text.mjs';
7
+ import { requireTerms } from './client-terms.mjs';
8
+
9
+ const STATE_UNKNOWN = 'Could not verify whether this instance is running. Refresh its status before starting.';
10
+ const has = (list, name) => Array.isArray(list) && list.includes(name);
11
+
12
+ /** Why this row cannot be started (or restarted) now, or null. The first rule that applies, in this order:
13
+ * 1 `not-in-roster` the caller holds no such row (it passes the current row, or null);
14
+ * 2 `already-running` running, and not a restart (a client offers its terminal instead);
15
+ * 3 `state-unknown` its state is not known stopped, and this is not a restart of a running row: unknown is
16
+ * not stopped. `detail` is the row's own runtime error through the display filter, when
17
+ * it has one, for the client to show with its speaker;
18
+ * 4 E_SNAPSHOT_UNKNOWN a server's row the kernel does not report addressable;
19
+ * 5 `cli-unavailable` / `unsupported-start-option` / `unsupported-remote-operation` no accepted CLI, no
20
+ * session-start, or (a server's row) no remote session-start;
21
+ * 6 `unsupported-start-option` a restart without session-restart (a server's row: also remote);
22
+ * 7 `unsupported-start-option` a launch choice (launchConfig, harness, yolo) without launch-config (a
23
+ * server's row: also remote). The word that selects no configuration is a choice like
24
+ * any other: no refusal of its own.
25
+ * -> null | { code, sentence, detail? } */
26
+ export function startGate(cli, row, { restart = false, choices = {} } = {}, terms) {
27
+ requireTerms(terms, 'startGate');
28
+ const refused = (code, sentence, more = {}) => ({ code, sentence, ...more });
29
+ if (!row) return refused('not-in-roster', 'This instance is no longer in this workspace. Refresh the workspace roster.');
30
+ const running = row.running === true, remote = !!row.server;
31
+ if (running && !restart) return refused('already-running', 'This instance is already running.');
32
+ if (row.running !== false && !(restart && running)) {
33
+ const detail = displayLine(row.runtimeError);
34
+ return refused('state-unknown', STATE_UNKNOWN, detail ? { detail } : {});
35
+ }
36
+ if (!canAddressRemote(row)) return refused('E_SNAPSHOT_UNKNOWN', unaddressableSentence(row));
37
+ if (cli?.ok !== true || !has(cli.features, 'session-start'))
38
+ return refused(cli?.ok === true ? 'unsupported-start-option' : 'cli-unavailable', `Starting an existing instance needs an updated OATS CLI. ${displayLine(cli?.install) || 'Update OATS and retry.'}`);
39
+ if (remote && !has(cli.remote, 'session-start')) return refused('unsupported-remote-operation', 'Update the OATS CLI to enable starting instances on a server.');
40
+ if (restart && (!has(cli.features, 'session-restart') || (remote && !has(cli.remote, 'session-restart'))))
41
+ return refused('unsupported-start-option', 'Update OATS to restart with another harness or configuration.');
42
+ if ([choices?.launchConfig, choices?.harness, choices?.yolo].some(v => v !== undefined)
43
+ && (!has(cli.features, 'launch-config') || (remote && !has(cli.remote, 'launch-config'))))
44
+ return refused('unsupported-start-option', 'Update OATS to change the launch configuration.');
45
+ return null;
46
+ }
@@ -0,0 +1,17 @@
1
+ /** What a client says, in its own words, of a start it could not make: a start, a restart or a launch
2
+ * preview of an existing home that the kernel refused. One sentence per refusal code a client has words
3
+ * for; every other refusal reads as the kernel's message, as before.
4
+ *
5
+ * A sentence names the Start dialog's own two controls (its Launch configuration list and that list's
6
+ * entry for the bare harness), never a machine: it is the same for a home on this computer and on a
7
+ * server. It holds no part of the kernel's message, which a client shows under it, attributed and through
8
+ * the display filter (display-text.mjs). No kernel text is parsed or compared to choose it: the code alone.
9
+ * Not on the stable surface. */
10
+ const SENTENCES = Object.freeze({
11
+ // Several launch configurations are declared for the harness a start named, none is the default, and the
12
+ // start named no configuration.
13
+ E_LAUNCH_CONFIG_AMBIGUOUS: 'More than one launch configuration is declared for the chosen harness, and none is the default. Choose one under Launch configuration, or choose "No launch configuration" to run the harness as installed.',
14
+ });
15
+
16
+ /** The client's sentence for a start's refusal `code`, or null when it has none. */
17
+ export const startRefusalSentence = code => (typeof code === 'string' && Object.hasOwn(SENTENCES, code) ? SENTENCES[code] : null);
@@ -74,10 +74,10 @@ const LAST_READ_FAILED = 'This deployment\'s last read failed. It shows what was
74
74
  *
75
75
  * origin the line detail
76
76
  * "kernel" a line "<own sentence> OATS says: <line>"
77
- * "kernel" "[Detail withheld]" "<own sentence> [Detail withheld]"
77
+ * "kernel" "[withheld]" "<own sentence> [withheld]"
78
78
  * "kernel" nothing to show "<own sentence>"
79
79
  * none a line "This deployment's last read failed: <line>. It shows what was last observed."
80
- * none "[Detail withheld]" "This deployment's last read failed: [Detail withheld]. It shows what was last observed."
80
+ * none "[withheld]" "This deployment's last read failed: [withheld]. It shows what was last observed."
81
81
  * none nothing to show "<own sentence>"
82
82
  *
83
83
  * The kernel's words stand apart, after the client's sentence and the speaker's lead
@@ -79,6 +79,10 @@ turn-record recall --reindex # full rebuild of the derived in
79
79
 
80
80
  Store root: `--root`, else `$TURN_RECORD_ROOT`, else `~/.turn-record`.
81
81
 
82
+ `recall --show` refuses a turn hidden by its author's tombstone, including a
83
+ session event whose tombstone lives in another stream. It emits no turn payload
84
+ and exits with status 1, as it does for a missing turn.
85
+
82
86
  **The `node` that `setup` writes down.** The hooks and the watcher's unit name
83
87
  a `node` by its path, and only `setup` run again rewrites them. Which path
84
88
  depends on how it is run:
@@ -61,8 +61,9 @@ try {
61
61
  console.error(`no turn ${args.show}`);
62
62
  process.exitCode = 1; return;
63
63
  }
64
- // Tombstoned turns are hidden from tool output, id lookup included.
65
- if (store.hiddenIds(byId).has(args.show)) {
64
+ // Session targets are absent from the bulk union: evaluate the claims
65
+ // against the resolved turn so id lookup respects their tombstones too.
66
+ if (store.claimHides(store.tombstoneClaims(byId), turn)) {
66
67
  console.error(`turn ${args.show} is tombstoned`);
67
68
  process.exitCode = 1; return;
68
69
  }
@@ -5,8 +5,8 @@ for people who work in terminals and on machines with no display. It ships
5
5
  inside `@awebai/oats` and is never published on its own.
6
6
 
7
7
  **It is a preview.** This version shows a workspace's instances, on this
8
- machine and on the other machines registered on it, in one list, and follows
9
- them; it changes nothing. While it is a preview its screens and its
8
+ machine and on the other machines registered on it, in one list, follows
9
+ them, and opens an agent's terminal; it changes nothing in a deployment. While it is a preview its screens and its
10
10
  configuration file may change without notice.
11
11
 
12
12
  [`docs/tui.md`](../../docs/tui.md) is the reference: how to start it, what the
@@ -23,6 +23,7 @@ never does.
23
23
  | `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
24
24
  | `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
25
25
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
26
+ | `lib/open.mjs` | the viewer of an opened agent: `oats session attach` run by the same kernel on the user's terminal, and the end of its standard error kept |
26
27
  | `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 child, and the two looks at the file system the switcher needs (the entries of `~/Agents`, and whether a picked folder is a deployment) |
27
28
  | `lib/store.mjs` | the state and `reduce(state, event)`: pure |
28
29
  | `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 |
@@ -31,7 +32,7 @@ never does.
31
32
  | `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
32
33
  | `lib/term/style.mjs` | style values: the sixteen ANSI colours and four attributes |
33
34
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
34
- | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
35
+ | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, the lend of the terminal to a viewer, one write per frame |
35
36
  | `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help |
36
37
 
37
38
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
@@ -48,8 +49,10 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
48
49
  the shared readers give reaches the screen through `shown()`.
49
50
  - The store holds no size and no cell: a key event carries the height of the
50
51
  panes as the last frame drew them.
51
- - Every child process runs in a session of its own and is ended on every way
52
- out; this version starts only reads.
52
+ - Every read runs in a session of its own and is ended on every way out.
53
+ The one child that is not a read is the viewer (`lib/open.mjs`): it shares
54
+ the user's terminal, the guard lends it the terminal, and it is ended first
55
+ on every way out while it has it.
53
56
  - The screen takes safe text only. Text the TUI did not write goes through
54
57
  `shown()`; `lit()` is for the TUI's own words and refuses anything the
55
58
  display filter would change, a run of spaces included, so a row is spans
@@ -57,7 +60,8 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
57
60
 
58
61
  Tests: `node --test packages/tui/test/*.test.mjs`, the root tests
59
62
  `test/tui-*.test.mjs`, and the end-to-end tests in a real tmux on a private
60
- socket (`test/tui-terminal.test.mjs`). All of them need the root's install
63
+ socket (`test/tui-terminal.test.mjs`, and `test/tui-open-terminal.test.mjs`
64
+ for opening an agent, with a second private server for the agents). All of them need the root's install
61
65
  (`npm ci` at the repository root). The package has no dependency of its own,
62
66
  but one of its tests runs the real kernel, which has: "KERNEL_BIN is this
63
67
  install's own bin/oats.mjs, and its `version --json` is a record the probe
@@ -2,6 +2,8 @@
2
2
  // both read it, so the help cannot name a key the program does not act on. `keys` are key ids
3
3
  // (term/keys.mjs keyId); they are the part a user's tui.json replaces (config.mjs), so everything
4
4
  // that acts on a key or names one reads the EFFECTIVE table it is handed, never this constant.
5
+ // An action that does one thing in the list of instances and another in the switcher (`open`)
6
+ // says so in `views`: what it does in each, in the order the help lists them.
5
7
  export const ACTIONS = Object.freeze([
6
8
  { id: "up", keys: ["up", "k"], label: "up" },
7
9
  { id: "down", keys: ["down", "j"], label: "down" },
@@ -16,13 +18,13 @@ export const ACTIONS = Object.freeze([
16
18
  { id: "refresh", keys: ["r"], label: "refresh" },
17
19
  { id: "instances", keys: ["1"], label: "instances" },
18
20
  { id: "workspaces", keys: ["w"], label: "workspaces" },
19
- { id: "open-workspace", keys: ["enter"], label: "open" },
21
+ { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"]] },
20
22
  { id: "help", keys: ["?"], label: "help" },
21
23
  { id: "close", keys: ["escape"], label: "close" },
22
24
  { id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
23
25
  { id: "suspend", keys: ["ctrl+z"], label: "suspend" },
24
26
  { id: "redraw", keys: ["ctrl+l"], label: "redraw" },
25
- ].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]) })));
27
+ ].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]), ...(action.views ? { views: Object.freeze(action.views.map((view) => Object.freeze([...view]))) } : {}) })));
26
28
 
27
29
  /** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
28
30
  export function bindings(actions = ACTIONS) {
@@ -13,7 +13,7 @@ export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
13
13
  export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
14
14
  export { createRefreshLoop } from "../../client/refresh-loop.mjs";
15
15
  export { rosterRows, livenessInput, livenessAnswers, panelInstances, pendingEntry, failedEntry, observedEntry } from "../../client/deployment-panel.mjs";
16
- export { panelData, cliReadsRemotes, workspaceChoices, viewModel } from "../../client/panel-views.mjs";
16
+ export { panelData, cliReadsRemotes, workspaceChoices, viewModel, deployments } from "../../client/panel-views.mjs";
17
17
  export { remoteRosterState } from "../../client/remote-roster.mjs";
18
18
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
19
19
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
@@ -22,7 +22,10 @@ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterIn
22
22
  export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
23
23
  export { runtimeState, runtimeCounts, originLead } from "../../client/instance-presentation.mjs";
24
24
  export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
25
- export { instanceActs } from "../../client/instance-acts.mjs";
25
+ export { instanceActs, openAct } from "../../client/instance-acts.mjs";
26
+ export { sessionAttachArgv, prepareRemoteTerm, detachKeySupported, hostDetachKeySupported, preflightFailure, DETACH_KEY_FEATURE } from "../../client/session-attach.mjs";
27
+ export { attachExit } from "../../client/attach-exit.mjs";
28
+ export { kernelLines } from "../../client/kernel-lines.mjs";
26
29
  export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
27
30
  export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
28
31
 
@@ -1,4 +1,5 @@
1
- // The user's key file, tui.json: which keys do what, and whether the screen is drawn in ASCII.
1
+ // The user's key file, tui.json: which keys do what, whether the screen is drawn in ASCII, and the
2
+ // key that leaves an agent's terminal.
2
3
  // Read once at start and never written. A file that is wrong in any way is refused whole, each
3
4
  // problem as one line that says what to change: the TUI resolves no conflict and guesses nothing
4
5
  // (there is no "last wins"), because a key that silently does something else is worse than a
@@ -16,7 +17,14 @@ export const CONFIG_LIMIT = 64 * 1024;
16
17
 
17
18
  const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
18
19
  const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
19
- const SETTINGS = "the settings are keys and ascii";
20
+ const SETTINGS = "the settings are keys, ascii and open";
21
+ /** The key that leaves an agent's terminal when tui.json names none: the kernel's suggested key. */
22
+ export const DETACH_KEY = "C-\\";
23
+ /** A detach key as tui.json may hold it: 1 to 16 printable ASCII characters. Its grammar is the
24
+ * kernel's, never checked here: a key the kernel refuses is said when an agent is opened. */
25
+ const DETACH_KEY_TEXT = /^[\x20-\x7e]{1,16}$/;
26
+ /** An action id this program had and has no more, with what it is called now. */
27
+ const RENAMED = Object.freeze({ "open-workspace": "open" });
20
28
  const KEY_IDS = "key ids look like q, ctrl+c, shift+tab, f5, space";
21
29
  /** A name from the file is echoed only when it is this: it cannot move a cursor or fill a screen. */
22
30
  const PLAIN_NAME = /^[\x21-\x7e]{1,40}$/;
@@ -43,7 +51,8 @@ export function configPath(env, home) {
43
51
  }
44
52
 
45
53
  /** What tui.json says, checked: `value` is the file already parsed, `defaults` the action table.
46
- * Pure. Answers `{ ok: true, actions, ascii }` or `{ ok: false, problems }`.
54
+ * Pure. Answers `{ ok: true, actions, ascii, detachKey }` or `{ ok: false, problems }`:
55
+ * `detachKey` is `open.detachKey`, or DETACH_KEY when the file names none.
47
56
  *
48
57
  * `actions` is a frozen table shaped exactly like `defaults` (same order, ids and labels, frozen
49
58
  * rows with frozen `keys`) in which the list of each action the file names REPLACES that action's
@@ -60,6 +69,7 @@ export function effectiveConfig(value, defaults = ACTIONS) {
60
69
  for (const [setting, given] of Object.entries(value)) {
61
70
  if (setting === "keys") { if (!isObject(given)) return { ok: false, problems: ['keys must be an object, like {"quit": ["q"]}'] }; }
62
71
  else if (setting === "ascii") { if (typeof given !== "boolean") return { ok: false, problems: ["ascii must be true or false"] }; }
72
+ else if (setting === "open") { const refused = openProblem(given); if (refused) return { ok: false, problems: [refused] }; }
63
73
  else return { ok: false, problems: [`${plain(setting) ? `unknown setting ${setting}` : "a setting whose name cannot be shown is unknown"}; ${SETTINGS}`] };
64
74
  }
65
75
 
@@ -80,7 +90,9 @@ export function effectiveConfig(value, defaults = ACTIONS) {
80
90
  // where the file gives it. (Two of them clashing is a defect of the table, said the same way.)
81
91
  for (const action of defaults) if (!named.has(action.id)) for (const key of action.keys) claim(key, action.id);
82
92
  for (const [id, list] of lists) {
83
- if (!ids.has(id)) {
93
+ if (!ids.has(id) && Object.hasOwn(RENAMED, id) && ids.has(RENAMED[id])) {
94
+ problems.push(`${id} is called ${RENAMED[id]} now; rename it`);
95
+ } else if (!ids.has(id)) {
84
96
  problems.push(`${plain(id) ? `unknown action ${id}` : "an action id that cannot be shown is unknown"}; the actions are ${[...ids].filter(plain).join(", ")}`);
85
97
  } else if (!Array.isArray(list) || !list.every((key) => typeof key === "string")) {
86
98
  problems.push(`${say(id)} must be a list of key ids, like ["q", "ctrl+c"]`);
@@ -97,7 +109,24 @@ export function effectiveConfig(value, defaults = ACTIONS) {
97
109
 
98
110
  const actions = Object.freeze(defaults.map((action) => Object.freeze({ ...action, keys: Object.freeze([...(named.get(action.id) ?? action.keys)]) })));
99
111
  try { bindings(actions); } catch { return { ok: false, problems: ["a key is given to two actions; a key does one thing"] }; }
100
- return { ok: true, actions, ascii: value.ascii === true };
112
+ return { ok: true, actions, ascii: value.ascii === true, detachKey: value.open?.detachKey ?? DETACH_KEY };
113
+ }
114
+
115
+ /** What is wrong with the `open` setting, or null. It holds one member, `detachKey`: a string of 1
116
+ * to 16 printable ASCII characters, handed to `oats session attach --detach-key` as it is. Its
117
+ * grammar is the kernel's. Two things that are not grammar are refused here: a value that begins
118
+ * with `-`, which the kernel would read as another flag and refuse in that flag's words (no key of
119
+ * its grammar begins with one), and a value the display filter would change, which the footer and
120
+ * the help would draw as another key. */
121
+ function openProblem(given) {
122
+ if (!isObject(given)) return 'open must be an object, like {"detachKey": "F12"}';
123
+ for (const [member, key] of Object.entries(given)) {
124
+ if (member !== "detachKey") return `${plain(member) ? `unknown member ${member} of open` : "a member of open whose name cannot be shown is unknown"}; open has detachKey`;
125
+ if (typeof key !== "string" || !DETACH_KEY_TEXT.test(key)) return 'open.detachKey must be 1 to 16 printable ASCII characters, like "F12"';
126
+ if (key.startsWith("-")) return "open.detachKey cannot begin with -";
127
+ if (displayLine(key) !== key) return "open.detachKey is a key the help cannot name; give a key whose characters can be shown";
128
+ }
129
+ return null;
101
130
  }
102
131
 
103
132
  /** The file system as loadConfig needs it. `stat` follows symbolic links and answers null for a
@@ -126,9 +155,10 @@ const NODE_IO = Object.freeze({
126
155
  },
127
156
  });
128
157
 
129
- /** Read tui.json, once. Answers `{ ok: true, actions, ascii, path }`, or `{ ok: false, lines }`:
130
- * the complete lines to print (no trailing newline), after which the TUI must not start.
131
- * No file is the defaults: `actions` is ACTIONS itself and `ascii` is false.
158
+ /** Read tui.json, once. Answers `{ ok: true, actions, ascii, detachKey, path }`, or
159
+ * `{ ok: false, lines }`: the complete lines to print (no trailing newline), after which the TUI
160
+ * must not start. No file is the defaults: `actions` is ACTIONS itself, `ascii` is false and
161
+ * `detachKey` is DETACH_KEY.
132
162
  *
133
163
  * `io` is the file system (node:fs when omitted): `io.stat(path)` answers `{ file, size }` after
134
164
  * following symbolic links, or null when the path does not exist, and throws for anything else;
@@ -141,7 +171,7 @@ export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO }
141
171
  const refused = (problems) => ({ ok: false, lines: listed(problems).map((problem) => `oats: \`oats tui\` cannot use ${PLAIN_PATH.test(path) ? path : "its configuration file"}: ${problem} (E_TUI_CONFIG)`) });
142
172
  let found, text, value;
143
173
  try { found = io.stat(path); } catch (error) { return refused([unreadable(error)]); }
144
- if (found === null) return { ok: true, actions: ACTIONS, ascii: false, path };
174
+ if (found === null) return { ok: true, actions: ACTIONS, ascii: false, detachKey: DETACH_KEY, path };
145
175
  if (found.file !== true) return refused(["it is not a regular file"]);
146
176
  if (!(typeof found.size === "number" && found.size <= CONFIG_LIMIT)) return refused([TOO_LARGE]); // read only what is known to fit
147
177
  try { text = io.read(path); } catch (error) { return refused([error?.code === "EFBIG" ? TOO_LARGE : unreadable(error)]); }