@awebai/oats 0.51.0 → 0.53.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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -0,0 +1,151 @@
1
+ /** Which roster rows can be addressed, why a row can't, and the copy for a remote read or plan
2
+ * that the host (or this machine's router) refused. Shared by the renderer and the server. */
3
+ import { unsupportedSession, runtimeErrorSpeaker, HERDR_STAND_IN } from './instance-presentation.mjs';
4
+ import { displayLine, cleanLine, DETAIL_WITHHELD } from './display-text.mjs';
5
+
6
+ /** A local row, or a remote row the kernel reports addressable (routed by `--server <id> --home <abs>`).
7
+ * A local OATS before 0.31 reports no `addressable` at all: a row it spawned keeps its saved route. */
8
+ export const canAddressRemote = row => !!row && (!row.server || row.addressable === true
9
+ || (row.addressable === undefined && row.savedRoute === true));
10
+
11
+ /** The server's registration label as the roster reports it, else its id. */
12
+ export const serverLabel = row => row?.repoName || row?.server || '';
13
+
14
+ /** The server's label as a sentence shows it: one display line (display-text.mjs), so the sentence is one
15
+ * too. A label with nothing to show, or a withheld one, reads "the server", the words the fixed sentences
16
+ * already use. For the sentence only: routing, comparison and requests keep the label and the server id
17
+ * as they are. `first`: the label opens the sentence. */
18
+ export const shownLabel = (label, first = false) => {
19
+ const line = displayLine(label);
20
+ return line === null || line === DETAIL_WITHHELD ? first ? 'The server' : 'the server' : line;
21
+ };
22
+
23
+ /** Why a remote row is refused when the kernel does not report it addressable. */
24
+ export function unaddressableSentence(row) {
25
+ const label = serverLabel(row);
26
+ if (row.missingRemotely === true) return `${row.instance} is no longer on ${shownLabel(label)}. Remove it from this computer with: oats server forget ${row.server} --instance ${row.instance}`;
27
+ return row.addressable === undefined ? `This computer's OATS does not report whether ${shownLabel(label)} can reach this instance. Update OATS here.`
28
+ : `${shownLabel(label, true)} did not report this instance as reachable.`;
29
+ }
30
+
31
+ /** The `origin` of a reason whose sentence is a row's text that reached `rowReason` beside no speaker (no
32
+ * `runtimeErrorOrigin`, or a value that is none of the three; a text that is not a string). It stands
33
+ * for a text nobody attributed: it names no speaker, and instance-presentation.mjs `originLead` has no
34
+ * words for it. Written here and nowhere else, never read from a row or an answer. */
35
+ const UNATTRIBUTED = 'unattributed';
36
+
37
+ /** Why a row can't be opened, as `{key, label, sentence, origin?}`, or null when nothing stands in the way.
38
+ * `label` is the roster meta line's state segment; `sentence` is the row's title, accessible
39
+ * description and actions-menu reason.
40
+ *
41
+ * **`origin` is there exactly when the sentence is not this home's own, and whoever writes such a
42
+ * sentence sets it in the same expression.** Here that is `quoted()`, the one expression that puts the
43
+ * row's `runtimeError` in a reason: it answers the text and its `origin` together, the row's
44
+ * `runtimeErrorOrigin` when that names one of the three speakers (instance-presentation.mjs), else
45
+ * "unattributed". That can be so for the keys `herdr`, `unreached` and `unknown`. A sentence written
46
+ * here (`own(…)`: `missing`, `unaddressable`, a row with no text of its own) has no `origin`.
47
+ *
48
+ * A client hangs its display filter on the key: a sentence with an `origin` is text from outside, shown
49
+ * through display-text.mjs `displayLine` and after the speaker's words when the value names one; a
50
+ * sentence with none is this home's own, shown as written, never under a speaker's name. So a missing
51
+ * `origin` can never hide a text from outside: no path here picks the row's text without one.
52
+ *
53
+ * The Herdr stand-in (instance-presentation.mjs `HERDR_STAND_IN`) is the one text of a row with no
54
+ * `origin`: it is this home's sentence also where a panel's row holds it as its `runtimeError`
55
+ * (remote-roster.mjs `remotePanel` writes it there), beside no speaker. */
56
+ export function rowReason(row) {
57
+ const label = serverLabel(row);
58
+ const quoted = () => ({ sentence: row.runtimeError, origin: runtimeErrorSpeaker(row) ?? UNATTRIBUTED });
59
+ const own = (sentence) => ({ sentence });
60
+ // What unsupportedSession answers is the row's own text or the stand-in. The stand-in's bytes beside no
61
+ // speaker are this home's sentence; any other text the row holds is quoted, with or without a speaker.
62
+ const herdr = unsupportedSession(row);
63
+ if (herdr) return { key: 'herdr', label: 'Herdr no longer supported', ...(herdr === row.runtimeError && (herdr !== HERDR_STAND_IN || runtimeErrorSpeaker(row)) ? quoted() : own(herdr)) };
64
+ if (row.server && row.serverUnreached) return { key: 'unreached', label: `${label} not reached`, ...(row.runtimeError ? quoted() : own(`${label} was not reached.`)) };
65
+ if (row.server && row.missingRemotely === true) return { key: 'missing', label: `gone from ${label}`, ...own(unaddressableSentence(row)) };
66
+ if (!canAddressRemote(row)) return { key: 'unaddressable', label: `not reachable on ${label}`, ...own(unaddressableSentence(row)) };
67
+ if (row.running == null) return { key: 'unknown', label: 'state unknown', ...(row.runtimeError ? quoted() : own(`${row.instance}: status unknown`)) };
68
+ return null;
69
+ }
70
+
71
+ const HEADLINES = {
72
+ E_REMOTE_INCOMPATIBLE: label => `${shownLabel(label, true)} runs an OATS that can't do this yet.`,
73
+ E_SNAPSHOT_UNKNOWN: label => `${shownLabel(label, true)} doesn't list this instance any more.`,
74
+ E_HOME_MISMATCH: label => `${shownLabel(label, true)} answered for a different instance. Nothing was changed.`,
75
+ E_AMBIGUOUS: label => `${shownLabel(label, true)} answered for a different instance. Nothing was changed.`,
76
+ // Transport: ssh itself failed, or this machine's own deadline on the remote read passed.
77
+ E_SSH: label => `Couldn't reach ${shownLabel(label)}.`,
78
+ E_CLI_TIMEOUT: label => `Couldn't reach ${shownLabel(label)}.`,
79
+ };
80
+ /** The headline for a remote failure: the table's, else the view's own sentence for the code. The
81
+ * server's label is shown as one display line, so a headline is always one. */
82
+ export const remoteHeadline = (code, label, fallback) => Object.hasOwn(HEADLINES, code) ? HEADLINES[code](label) : fallback;
83
+
84
+ export const readingFrom = label => `Reading from ${label}…`;
85
+
86
+ /** A host's E_REMOTE_INCOMPATIBLE for a panel read (the context panel's Soul tab and teams): the server,
87
+ * what it can't show and what to upgrade. `what`: "soul", "teams". */
88
+ export const incompatibleSentence = (label, what) =>
89
+ `${shownLabel(label, true)} runs an OATS that can't show this instance's ${what} here (it needs the operations feature). Update OATS on ${shownLabel(label)}.`;
90
+
91
+ /** Why an instance inspection for a remote row is not sent (an Error for a failed block: the sentence, and
92
+ * the code when there is one), or null. A row the kernel does not report addressable says why; this
93
+ * computer's OATS without remote operations can't route it. A local row is never blocked. */
94
+ export function remoteInspectBlock(row, cli) {
95
+ if (!row?.server) return null;
96
+ if (!canAddressRemote(row)) return new Error(unaddressableSentence(row));
97
+ if (!Array.isArray(cli?.remote) || !cli.remote.includes('operations')) {
98
+ const { message, code, detail } = unroutableReason(serverLabel(row));
99
+ return Object.assign(new Error(message), { code, detail });
100
+ }
101
+ return null;
102
+ }
103
+
104
+ /** The error a view's loading state shows for a failed read: the relayed remote reason when the request's
105
+ * error carries one (re-validated where it was received), as an Error with its code and detail; else the
106
+ * error as it came. `what` ("soul", "teams") words a host's E_REMOTE_INCOMPATIBLE for the panel read
107
+ * (incompatibleSentence); without it the relayed headline stands. */
108
+ export function relayedFailure(error, label, what = null) {
109
+ const reason = error?.reason;
110
+ if (!reason || typeof reason.message !== 'string') return error;
111
+ const message = what && reason.code === 'E_REMOTE_INCOMPATIBLE' ? incompatibleSentence(label, what) : reason.message;
112
+ return Object.assign(new Error(message), { code: reason.code, detail: reason.detail ?? null });
113
+ }
114
+
115
+ const CODE = /^E_[A-Z0-9_]{1,64}$/;
116
+ const MAX_MESSAGE = 512;
117
+ /** A code in the kernel's code shape. */
118
+ export const kernelCode = v => typeof v === 'string' && CODE.test(v);
119
+
120
+ /** A failure's Details line as nodes: its code, and the kernel's own message when a host sent one. The
121
+ * code and the colon are text. The message is alone inside a <bdi>, as a text node: its bidirectional
122
+ * layout is isolated from the text around it. Only a message that is already a display line is shown. */
123
+ export function codeLineNodes(doc, reason) {
124
+ const code = typeof reason?.code === 'string' && reason.code ? reason.code : null;
125
+ if (!code) return [];
126
+ if (!cleanLine(reason.detail)) return [doc.createTextNode(code)];
127
+ const field = doc.createElement('bdi'); field.append(doc.createTextNode(reason.detail));
128
+ return [doc.createTextNode(`${code}: `), field];
129
+ }
130
+
131
+ /** A host's (or the remote transport's) refusal: the kernel's code verbatim, a headline, and the
132
+ * kernel's message as the detail, through the display filter (one line, or withheld). Null for anything
133
+ * not shaped like a kernel error. */
134
+ export function hostReason(error, label, fallback) {
135
+ if (!kernelCode(error?.code)) return null;
136
+ return { code: error.code, message: remoteHeadline(error.code, label, fallback), detail: displayLine(error.message), remote: true };
137
+ }
138
+
139
+ /** This machine's OATS has no `remote` entry for the operation: nothing was sent. */
140
+ export const unroutableReason = label => ({ code: 'unsupported-remote-operation',
141
+ message: `This computer's OATS can't route this to ${shownLabel(label)}. Update OATS here.`, detail: null, remote: true });
142
+
143
+ /** Re-validate a relayed remote reason (server → main → renderer), or null. Its message and its detail
144
+ * are each already a display line (what the filter would return for them), within their limits. */
145
+ export function remoteReason(v) {
146
+ if (!v || typeof v !== 'object' || Array.isArray(v) || Object.keys(v).some(k => !['code', 'message', 'detail', 'remote'].includes(k))
147
+ || v.remote !== true || !(kernelCode(v.code) || v.code === 'unsupported-remote-operation')
148
+ || !cleanLine(v.message) || v.message.length > MAX_MESSAGE
149
+ || !(v.detail === null || cleanLine(v.detail))) return null;
150
+ return { code: v.code, message: v.message, detail: v.detail, remote: true };
151
+ }
@@ -0,0 +1,94 @@
1
+ /** What a client remembers of the machines its roster answers reported (#482; #855, 3a): the last
2
+ * workspace identity each remote roster group reported, keyed by the group id (`<server>:<targetKey>`,
3
+ * the kernel's own group key), and the sentence left for a machine that moved to another workspace.
4
+ * A machine that stops answering keeps its place in its workspace through it ("not reached",
5
+ * identityFrom "remembered": panel-views.mjs `deploymentInfo`). A fresh report always wins. Only
6
+ * remote groups are remembered: memory never attaches a local deployment.
7
+ *
8
+ * No state. The memory and the notes are two Maps the client holds and passes in:
9
+ *
10
+ * memory: Map<group id, { server, label, targetKey, path, workspace, reportedAt }>
11
+ * notes: Map<group id, string> the sentence for a machine that moved to another workspace
12
+ *
13
+ * `observeIdentities` answers new Maps and changes neither. Where a client keeps them between calls,
14
+ * and whether on disk, is its own: the Desktop's file is packages/desktop/server/remote-identity.mjs.
15
+ * Nothing here caps the memory: an answer drops every group it no longer lists, so the memory is
16
+ * never larger than the roster answer. */
17
+ import { readIdentity, attachment, viewId } from './workspace-views.mjs';
18
+
19
+ const GROUP_ID = /^[a-z0-9][a-z0-9-]{0,63}:[A-Za-z0-9._-]{1,128}$/;
20
+ const SERVER = /^[a-z0-9][a-z0-9-]{0,63}$/;
21
+ const text = v => typeof v === 'string' && v.length > 0 && v.length <= 2048 && !v.includes('\0');
22
+
23
+ /** A remembered entry read from outside the client (a file): the entry as the memory keeps it, or null
24
+ * when the id or any field of `raw` is not what `observeIdentities` would have stored. */
25
+ export function entryOf(id, raw) {
26
+ if (!GROUP_ID.test(id) || !raw || typeof raw !== 'object') return null;
27
+ const { server, label, targetKey, path, workspace, reportedAt } = raw;
28
+ if (!SERVER.test(server ?? '') || !text(label) || !text(targetKey) || id !== `${server}:${targetKey}` || !text(path) || !path.startsWith('/')
29
+ || !text(reportedAt) || Number.isNaN(Date.parse(reportedAt))) return null;
30
+ const read = readIdentity(workspace);
31
+ if (read.status !== 'identity') return null;
32
+ return { server, label, targetKey, path, workspace: read.identity, reportedAt };
33
+ }
34
+
35
+ const sameIdentity = (a, b) => JSON.stringify(a) === JSON.stringify(b);
36
+ /** The view an identity attaches to, or null (an unattached identity has no workspace view). */
37
+ const viewOf = identity => { const a = attachment(identity); return a.unattached ? null : viewId(a.key, a.team); };
38
+ /** The name the move note gives the new workspace: the last segment of its key. */
39
+ const workspaceName = identity => identity?.key ? String(identity.key).split('/').filter(Boolean).pop() : null;
40
+
41
+ /**
42
+ * One roster answer: remember each fresh report, note a move, and drop the memory (and the note) of
43
+ * every group the answer no longer lists. Only a group that was reached (`probe.ok === true`), whose id
44
+ * and server have the kernel's form, whose path is absolute and whose workspace reads as an identity
45
+ * (a `key` field) is a report; a failed probe changes nothing, and its group is kept while listed. A
46
+ * report equal to what is remembered (identity, label, path) changes nothing. A report that moves the
47
+ * group to another view leaves its note.
48
+ *
49
+ * A group whose id or server is not in the kernel's form (GROUP_ID and SERVER above: a lower-case server
50
+ * name, and `<server>:<targetKey>`) is never remembered, and says nothing of it: a client's fixture
51
+ * needs the real forms, or its machine leaves its view the first time it does not answer.
52
+ *
53
+ * `groups` is what remote-roster.mjs `remoteRosterState` answers as `reported`; `at` is the caller's
54
+ * time, kept as each new entry's `reportedAt`.
55
+ * @param {{ memory: Map, notes: Map }} held
56
+ * @param {Array<{id, server, label, target:{workspace}, probe, workspace}>} groups
57
+ * @returns {{ memory: Map, notes: Map, changed: boolean }} new Maps; `changed` says the memory changed
58
+ * (a client that keeps it on disk writes then).
59
+ */
60
+ export function observeIdentities({ memory, notes }, groups, at) {
61
+ if (typeof at !== 'string' || !at) throw new TypeError('observeIdentities: at must be the time of the call, a non-empty string');
62
+ const next = new Map(memory), nextNotes = new Map(notes);
63
+ let changed = false;
64
+ const listed = new Set(groups.map(g => g.id));
65
+ for (const id of [...next.keys()]) if (!listed.has(id)) { next.delete(id); nextNotes.delete(id); changed = true; }
66
+ for (const g of groups) {
67
+ if (g?.probe?.ok !== true || !GROUP_ID.test(g.id ?? '') || !SERVER.test(g.server ?? '')) continue;
68
+ const read = readIdentity(g.workspace);
69
+ if (read.status !== 'identity') continue;
70
+ const targetKey = g.id.slice(g.server.length + 1);
71
+ const path = g.target?.workspace;
72
+ if (!text(path) || !path.startsWith('/')) continue;
73
+ const previous = next.get(g.id);
74
+ if (previous && sameIdentity(previous.workspace, read.identity) && previous.label === (g.label || g.server) && previous.path === path) continue;
75
+ if (previous && !sameIdentity(previous.workspace, read.identity) && viewOf(previous.workspace) !== viewOf(read.identity)) {
76
+ const name = workspaceName(read.identity);
77
+ nextNotes.set(g.id, name ? `${g.label || g.server} now reports workspace ${name}.` : `${g.label || g.server} now reports another workspace.`);
78
+ }
79
+ next.set(g.id, { server: g.server, label: text(g.label) ? g.label : g.server, targetKey, path, workspace: read.identity, reportedAt: at });
80
+ changed = true;
81
+ }
82
+ return { memory: next, notes: nextNotes, changed };
83
+ }
84
+
85
+ /** The three readers panel-views.mjs takes as `held.remembered`, over one memory and its notes. They
86
+ * read and change nothing: `get(id)` is the remembered entry of a group, or null; `note(id)` the move
87
+ * sentence of a group, or null; `all()` every remembered entry, each with its `id`. */
88
+ export function identityMemory({ memory, notes }) {
89
+ return {
90
+ get: id => memory.get(id) ?? null,
91
+ note: id => notes.get(id) ?? null,
92
+ all: () => [...memory.entries()].map(([id, e]) => ({ id, ...e })),
93
+ };
94
+ }
@@ -0,0 +1,153 @@
1
+ import { harnessOf } from "./harness-names.mjs";
2
+ import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
3
+ import { madeByKernel } from "./kernel-made.mjs";
4
+ import { waitingOnYouData } from "./waiting-on-you.mjs";
5
+ /** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
6
+ export function remoteWorkspace(group) {
7
+ return {
8
+ id: `remote:${group.id}`, name: group.label || group.server,
9
+ scope: group.target.workspace, roots: [], team: null, remote: true,
10
+ server: group.server, registrationPresent: group.registrationPresent, group,
11
+ };
12
+ }
13
+
14
+ /** The time a caller gives, or a TypeError when it gave none: this module reads no clock. `table` names
15
+ * the function that was called without it (as client-terms.mjs `requireTerms` does for terms). */
16
+ function requireTime(at, table) {
17
+ if (typeof at !== "string" || !at) throw new TypeError(`${table}: at must be the time of the call, a non-empty string`);
18
+ return at;
19
+ }
20
+
21
+ /** A remote deployment's panel. `at` is the time the panel is made, an ISO string, and is required: the
22
+ * caller holds the time of its call (panel-views.mjs passes `held.at`) and no clock is read here.
23
+ *
24
+ * A row is the host's row, spread whole, so a row with a `runtimeError` gets its speaker here
25
+ * (`runtimeErrorOrigin`; instance-presentation.mjs names the three) and any other row gets none: a
26
+ * `runtimeErrorOrigin` a host sent never survives, on any path. Which text it is decides:
27
+ *
28
+ * a Herdr row "kernel" for the host's own reason, no key for the stand-in
29
+ * a reached server the host's row text: "kernel" (a host's OATS, relayed)
30
+ * a server not reached, an error the "kernel": the mark of kernel-made.mjs, set where the roster's
31
+ * installed CLI printed answer is parsed (cli-adapter.mjs `cliRemoteRoster`)
32
+ * a server not reached, any other "roster-read": written while the roster was read (a read
33
+ * error, or none ("Server is that threw, a timeout, an answer that is not the contract's)
34
+ * unreachable")
35
+ *
36
+ * No code and no message is read to decide it. The mark is on the error object: a group is held and
37
+ * passed back as it was answered (`remoteRosterState`), and a copy of its `probe.error` reads as
38
+ * "roster-read", never as the kernel's. */
39
+ export function remotePanel(group, at) {
40
+ requireTime(at, "remotePanel");
41
+ const ws = remoteWorkspace(group);
42
+ // A row's soul subtitle: its own group's soul list only, a string as the host reported it, never synthesized.
43
+ const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
44
+ // A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
45
+ const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, ...i }) => {
46
+ const unsupported = unsupportedSession(i);
47
+ const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
48
+ const row = {
49
+ ...i, server: group.server, savedRoute: i.savedRoute === true,
50
+ // The last roster read of this server failed: its rows are last-known, their state unknown.
51
+ serverUnreached: !group.probe.ok,
52
+ home: i.home, agentsRoot: i.agentsRoot || group.agentsRoot,
53
+ workspace: group.target.workspace, repoName: group.label || group.server,
54
+ harness: harnessOf({ runtime: _released, ...i }) || null, model: i.model || null, description: described(i.agent),
55
+ running: group.probe.ok ? i.running : null,
56
+ runtimeError: group.probe.ok ? i.runtimeError : group.probe.error?.message || "Server is unreachable",
57
+ tmux: i.tmux || null, git: i.git || null, task: i.task || "", next: i.next || "",
58
+ // Needs input: only a remote kernel with the feature reports it — validated, never synthesized when absent.
59
+ ...(Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: waitingOnYouData(i.waitingOnYou) } : {}),
60
+ ...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
61
+ };
62
+ return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
63
+ });
64
+ return {
65
+ workspace: { id: ws.id, name: ws.name, scope: ws.scope, team: null, server: ws.server,
66
+ remote: true, registrationPresent: ws.registrationPresent === true },
67
+ team: null, generatedAt: at,
68
+ running: instances.filter((i) => i.running).length, instances,
69
+ error: group.probe.ok ? null : group.probe.error?.message || "Server is unreachable",
70
+ };
71
+ }
72
+
73
+ export function remoteAgents(group) {
74
+ if (!group.registrationPresent || !group.probe.ok) return [];
75
+ return (group.souls || []).map(({ runtime: _released, ...a }) => ({
76
+ ...a, server: group.server, remote: true,
77
+ agentsRoot: a.agentsRoot || group.agentsRoot,
78
+ workspace: group.target.workspace, repoName: group.label || group.server,
79
+ // The reported default harness only (a pre-0.27 host's `runtime` is read as it); never a guessed pi.
80
+ harness: harnessOf({ runtime: _released, ...a }) || null, backend: a.backend || "tmux", work: a.work || "checkout",
81
+ kind: a.kind || "persistent", description: a.description || "",
82
+ }));
83
+ }
84
+
85
+ export function unavailableGroups(groups, error) {
86
+ return groups.map((g) => ({ ...g, probe: { ok: false, error }, instances: (g.instances || []).map((i) => ({ ...i, running: null })) }));
87
+ }
88
+
89
+ /** The roster read's failure in words, and as the error an unavailable group carries. */
90
+ const ROSTER_UNAVAILABLE = "Remote roster unavailable";
91
+ const rosterError = (message) => ({ code: "E_REMOTE_ROSTER", message });
92
+
93
+ /**
94
+ * What one outcome of `oats server roster --json` makes of the roster a client holds. No state: the
95
+ * client keeps the three values between reads and passes them back as `previous`.
96
+ *
97
+ * previous: { remoteGroups, rosterAnswered, rosterFailure }
98
+ * outcome: { gated: true } no accepted CLI, or one that does not read other machines
99
+ * (panel-views.mjs `cliReadsRemotes`): the read was not made
100
+ * | { envelope } what the CLI answered (cli-adapter.mjs `cliRemoteRoster`)
101
+ * | { thrown: string } the read failed: the message of what was thrown
102
+ * at: the caller's time, the one `remotePanel` stamps
103
+ * -> { remoteGroups, rosterAnswered, rosterFailure, reported }
104
+ *
105
+ * `remoteGroups` is the last readable roster: an answer replaces it only when every group of it can be
106
+ * projected (`remotePanel`), and a failed read keeps the groups held, each marked not reached
107
+ * (`unavailableGroups`). `rosterAnswered` says an answer arrived; `rosterFailure` is the failure's
108
+ * sentence, kept only while none has. `reported` is what the client hands to its memory of identities
109
+ * (remote-identity-memory.mjs `observeIdentities`): the groups of an `ok` envelope, else null.
110
+ *
111
+ * The sentence of a thrown read carries the message of an error from outside the client: a client
112
+ * shows it through `displayLine` (display-text.mjs) only.
113
+ *
114
+ * What stays the caller's: one read at a time, when it runs, and dropping an answer that was read
115
+ * with a kernel record that is no longer the accepted one. And its own `try`/`catch` around the read
116
+ * and around what it does with `reported`: if that step throws after the caller took the new state, the
117
+ * caller takes `{ thrown: <message> }` next, so the groups it just took are marked not reached.
118
+ */
119
+ export function remoteRosterState(previous, outcome, at) {
120
+ requireTime(at, "remoteRosterState");
121
+ if (outcome.gated) return { remoteGroups: [], rosterAnswered: false, rosterFailure: previous.rosterFailure, reported: null };
122
+ /** A read with no answer to keep: the groups held, marked; the sentence only while no answer has ever arrived. */
123
+ const failed = (message) => ({
124
+ remoteGroups: unavailableGroups(previous.remoteGroups, rosterError(message)), rosterAnswered: previous.rosterAnswered,
125
+ rosterFailure: previous.rosterAnswered ? previous.rosterFailure : message, reported: null,
126
+ });
127
+ if (!Object.hasOwn(outcome, "envelope")) return failed(`${ROSTER_UNAVAILABLE}: ${outcome.thrown}`);
128
+ try {
129
+ const env = outcome.envelope;
130
+ const incoming = env.ok && Array.isArray(env.result?.groups)
131
+ ? env.result.groups : unavailableGroups(previous.remoteGroups, env.error || rosterError(ROSTER_UNAVAILABLE));
132
+ for (const group of incoming) remotePanel(group, at); // validate before replacing the last readable roster
133
+ if (env.ok) return { remoteGroups: incoming, rosterAnswered: true, rosterFailure: null, reported: incoming };
134
+ return { remoteGroups: incoming, rosterAnswered: previous.rosterAnswered,
135
+ rosterFailure: previous.rosterAnswered ? previous.rosterFailure : env.error?.message || ROSTER_UNAVAILABLE, reported: null };
136
+ } catch (e) {
137
+ // An answer that cannot be read, or a group of it that cannot be projected: as a read that threw.
138
+ return failed(`${ROSTER_UNAVAILABLE}: ${e.message}`);
139
+ }
140
+ }
141
+
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) {
144
+ requireTime(at, "remotePanelEntries");
145
+ return remoteGroups.map((group) => { const panel = remotePanel(group, at); return [panel.workspace.id, panel]; });
146
+ }
147
+
148
+ export function spawnedWorkspace(groups, result) {
149
+ if (!result.server || !result.target) return undefined;
150
+ const group = groups.find((g) => g.server === result.server && g.registrationPresent
151
+ && g.target.sshHost === result.target.sshHost && g.target.workspace === result.target.workspace);
152
+ return group ? remoteWorkspace(group).id : undefined;
153
+ }
@@ -0,0 +1,80 @@
1
+ /** A view's deployments and its roster, from the panel's facts alone (#482): which deployment
2
+ * deployment-level surfaces read, a deployment's state in words, which rows are held from a stale
3
+ * deployment, and the roster split into one section per deployment when a view has two or more.
4
+ *
5
+ * A deployment is `{ id, machine, path, label, local, reachable, identityFrom, primary, stale?, reason? }`
6
+ * and a row carries `deployment: { id }`. Nothing is derived from a host name or a path beyond the
7
+ * display label. A view with one deployment has one section and no heading. */
8
+ import { rosterGroups } from './instance-tree.mjs';
9
+ import { machineLabelParts } from './deployment-label.mjs';
10
+ import { requireTerms } from './client-terms.mjs';
11
+
12
+ const text = (v, max = 4096) => typeof v === 'string' && v.length > 0 && v.length <= max;
13
+
14
+ /** Grouping and "On …" lines apply only to a view of two or more deployments. */
15
+ export const isMultiDeployment = deployments => Array.isArray(deployments) && deployments.length >= 2;
16
+
17
+ /** The deployment deployment-level surfaces read and act on: the one marked primary, else the first. */
18
+ export const primaryDeployment = deployments => (Array.isArray(deployments) && (deployments.find(d => d?.primary) || deployments[0])) || null;
19
+
20
+ /** A deployment's state, in words (never colour alone): `{ key, text, detail }`.
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. */
24
+ export function deploymentState(d) {
25
+ // This computer's deployment whose last re-read failed: its rows are the last observation.
26
+ if (d?.stale) return { key: 'stale', text: 'stale', detail: d.reason || '' };
27
+ if (d?.reachable) return { key: 'live', text: 'live', detail: '' };
28
+ if (d?.identityFrom === 'remembered') {
29
+ return { key: 'remembered', text: 'remembered', detail: ['Last report, not live now.', d.reason].filter(Boolean).join(' ') };
30
+ }
31
+ // This computer's own deployment is not "reached": it is observed or not, the reason says why
32
+ // (still reading, or the kernel's refusal).
33
+ if (d?.local) return { key: 'unobserved', text: 'not observed', detail: d.reason || '' };
34
+ return { key: 'unreached', text: 'not reached', detail: d?.reason || '' };
35
+ }
36
+
37
+ /** The deployment a row belongs to, by the id the panel tagged it with (null when untagged). */
38
+ const rowDeployment = row => (text(row?.deployment?.id) ? row.deployment.id : null);
39
+
40
+ /** Whether a row is held from its deployment's last observation (the deployment is stale): its
41
+ * Start and actions wait for a current read, as for a stale roster. */
42
+ export const rowStale = (row, deployments) => {
43
+ const id = rowDeployment(row);
44
+ return !!id && Array.isArray(deployments) && deployments.some(d => d?.id === id && d.stale);
45
+ };
46
+
47
+ /** The sidebar roster's sections. One deployment (or none reported): a single section with no
48
+ * heading whose groups are exactly the relation clusters the roster always drew. Two or more: one
49
+ * section per deployment, in the panel's order, each with its own clusters (relations are recorded
50
+ * within one deployment); a row without a known deployment (a pending spawn) joins the primary's.
51
+ * Sections with no visible row are left out. Each is labelled by its machine, with the path tail
52
+ * only when one machine holds two (deployment-label.mjs machineLabels), in the client's terms
53
+ * (client-terms.mjs: the label of a deployment that names no machine). Returns
54
+ * `[{ deployment|null, label|null, groups }]`, a group being `{ key, label, clusters }` as before. */
55
+ export function rosterSections(instances, visible, deployments, terms) {
56
+ requireTerms(terms, 'rosterSections');
57
+ const groupsOf = (all, shown) => rosterGroups(all, shown); // the relation groups the palette lists too
58
+ if (!isMultiDeployment(deployments)) return [{ deployment: null, label: null, groups: groupsOf(instances, visible) }];
59
+ const sectionOf = splitByDeployment(deployments);
60
+ const all = sectionOf(instances), shown = sectionOf(visible), labels = machineLabelParts(deployments, terms);
61
+ const label = ({ machine, tail }) => (tail ? `${machine} · ${tail}` : machine);
62
+ return deployments.map(d => ({ deployment: d, parts: labels.get(d.id), all: all.get(d.id), shown: shown.get(d.id) }))
63
+ .filter(s => s.shown.length)
64
+ .map(s => ({ deployment: s.deployment, label: label(s.parts), machine: s.parts.machine, tail: s.parts.tail, groups: groupsOf(s.all, s.shown) }));
65
+ }
66
+
67
+ /** `rows → Map<deployment id, rows>` over the given deployments; an unknown or missing deployment
68
+ * id goes to the primary deployment. */
69
+ export function splitByDeployment(deployments) {
70
+ const primary = primaryDeployment(deployments)?.id;
71
+ const ids = new Set(deployments.map(d => d.id));
72
+ return rows => {
73
+ const out = new Map(deployments.map(d => [d.id, []]));
74
+ for (const row of rows || []) {
75
+ const id = rowDeployment(row);
76
+ out.get(id && ids.has(id) ? id : primary)?.push(row);
77
+ }
78
+ return out;
79
+ };
80
+ }