@awebai/oats 0.52.0 → 0.54.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.
- package/README.md +2 -1
- package/bin/oats.mjs +314 -92
- package/docs/capabilities.md +66 -4
- package/docs/configuration.md +66 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +696 -60
- package/docs/desktop-instance-start.md +25 -12
- package/docs/execution-targets.md +1 -0
- package/docs/implementation.md +184 -12
- package/docs/integrations.md +6 -3
- package/docs/knowledge.md +2 -2
- package/docs/macos-test-runs.md +246 -0
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +210 -6
- package/docs/release-notes/v0.53.0.md +1288 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/schedules.md +7 -1
- package/docs/souls-and-instances.md +239 -16
- package/docs/tui.md +453 -21
- package/docs/upgrading.md +310 -0
- package/docs/workspaces.md +123 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +93 -4
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +569 -121
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +5 -6
- package/lib/instance-lifecycle.mjs +145 -18
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +226 -15
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +18 -5
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +404 -60
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +6 -35
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/workspace.mjs +75 -27
- package/package-catalog.json +4 -4
- package/package.json +2 -1
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/cli-adapter.mjs +16 -3
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-contract.mjs +4 -0
- package/packages/client/deployment-facts.mjs +71 -10
- package/packages/client/deployment-panel.mjs +49 -11
- package/packages/client/deployment-read-cli.mjs +7 -3
- package/packages/client/display-text.mjs +8 -2
- package/packages/client/instance-acts.mjs +46 -10
- package/packages/client/instance-events-contract.mjs +4 -2
- package/packages/client/instance-presentation.mjs +66 -2
- package/packages/client/instance-tree.mjs +23 -14
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-prompt-outcome.mjs +51 -16
- package/packages/client/lifecycle-contract.mjs +45 -4
- package/packages/client/liveness.mjs +14 -1
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/panel-views.mjs +18 -11
- package/packages/client/readiness-contract.mjs +3 -1
- package/packages/client/remote-address.mjs +34 -9
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +92 -6
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-contract.mjs +16 -4
- package/packages/client/spawn-messages.mjs +26 -3
- package/packages/client/spawn-preview-cli.mjs +8 -2
- package/packages/client/spawn-preview-contract.mjs +5 -1
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-views.mjs +39 -3
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +30 -12
- package/packages/tui/lib/actions.mjs +16 -1
- package/packages/tui/lib/client.mjs +32 -1
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +117 -46
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +44 -0
- package/packages/tui/lib/term/screen.mjs +16 -4
- package/packages/tui/lib/term/text.mjs +60 -0
- package/packages/tui/lib/term/tty.mjs +13 -3
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +230 -36
- package/packages/tui/lib/views/help.mjs +125 -13
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/skills/oats-getting-started/SKILL.md +8 -2
|
@@ -22,7 +22,8 @@
|
|
|
22
22
|
*
|
|
23
23
|
* These functions read no clock: the one time they stamp is `held.at`, and the same `held` gives the
|
|
24
24
|
* same answer. A remote deployment's panel is remote-roster.mjs `remotePanel`, made at `held.at`; what
|
|
25
|
-
* a remote roster's answer becomes is that module's
|
|
25
|
+
* a remote roster's answer becomes is that module's `remoteRosterState`, whose answer is the three
|
|
26
|
+
* roster values of `held`.
|
|
26
27
|
*
|
|
27
28
|
* `remembered` is the client's own store, passed in: this module calls its three reading methods and
|
|
28
29
|
* keeps nothing. `note(id)` answers the sentence left for a machine that moved to another workspace,
|
|
@@ -36,7 +37,7 @@ import { basename } from 'node:path';
|
|
|
36
37
|
import { remoteWorkspace, remotePanel } from './remote-roster.mjs';
|
|
37
38
|
import { readIdentity, attachment, buildViews, deploymentReason, deploymentReasonParts } from './workspace-views.mjs';
|
|
38
39
|
import { shortPath, deploymentLabel } from './deployment-label.mjs';
|
|
39
|
-
import { deploymentUnavailableText } from './deployment-facts.mjs';
|
|
40
|
+
import { deploymentUnavailableText, keptFailure } from './deployment-facts.mjs';
|
|
40
41
|
import { publicDeployment } from './deployment-panel.mjs';
|
|
41
42
|
import { teamMembers } from './team-members.mjs';
|
|
42
43
|
import { requireTerms } from './client-terms.mjs';
|
|
@@ -67,7 +68,9 @@ export function rememberedGroups(held) {
|
|
|
67
68
|
agentsRoot: undefined, workspace: null, souls: [], instances: [], retireFailures: [],
|
|
68
69
|
}));
|
|
69
70
|
}
|
|
70
|
-
|
|
71
|
+
/** Whether a kernel record (cli-locator.mjs) reads other machines: an accepted CLI whose `remote` lists
|
|
72
|
+
* `roster`. Without it a client makes no roster read (remote-roster.mjs `remoteRosterState`: "gated"). */
|
|
73
|
+
export const cliReadsRemotes = (cli) => !!cli.ok && !!cli.remote?.includes("roster");
|
|
71
74
|
const identityFeature = (held) => !!held.cli.features?.includes("workspace-identity");
|
|
72
75
|
/** One deployment's identity, attachment, machine label and reason. */
|
|
73
76
|
export function deploymentInfo(held, d, terms) {
|
|
@@ -77,7 +80,8 @@ export function deploymentInfo(held, d, terms) {
|
|
|
77
80
|
const live = observed?.status === "observed";
|
|
78
81
|
// A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`): its identity still places
|
|
79
82
|
// it in its view, but it is stale, not live, and says why. Still reachable: this computer's own deployment.
|
|
80
|
-
|
|
83
|
+
// Whether one is kept is deployment-facts.mjs `keptFailure`'s to say, never a test of the message.
|
|
84
|
+
const kept = live ? keptFailure(entry) : null;
|
|
81
85
|
const read = !live ? { status: "none" } : !identityFeature(held) ? { status: "feature" }
|
|
82
86
|
: observed.reachable?.identityInvalid ? { status: "invalid" } : readIdentity(observed.reachable);
|
|
83
87
|
const identity = read.status === "identity" ? read.identity : null;
|
|
@@ -85,9 +89,10 @@ export function deploymentInfo(held, d, terms) {
|
|
|
85
89
|
// Not observed (yet): the reading or unavailable sentence, never a silent empty.
|
|
86
90
|
const unavailable = live ? null : deploymentUnavailableText(observed || { status: "pending" }, terms);
|
|
87
91
|
return { id: d.id, local: true, machine: terms.thisMachine, path: d.id, label: shortPath(d.id, { home: held.home }), name: d.name,
|
|
88
|
-
live: live && !
|
|
92
|
+
live: live && !kept, reachable: live, ...(kept ? { stale: true } : {}), identityFrom: identity ? "reported" : null, identity, attach,
|
|
89
93
|
teamLabel: identity?.defaultTeam?.label ?? null,
|
|
90
|
-
...reasonFields(deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref, unavailable,
|
|
94
|
+
...reasonFields(deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref, unavailable,
|
|
95
|
+
...(kept ? { readError: kept.message, readErrorOrigin: kept.origin } : {}) }, terms)),
|
|
91
96
|
note: attach.note === "standalone" ? deploymentReason({ local: true, attach: { unattached: "standalone" } }, terms) : null };
|
|
92
97
|
}
|
|
93
98
|
const g = d.group, machine = g.label || g.server;
|
|
@@ -101,7 +106,7 @@ export function deploymentInfo(held, d, terms) {
|
|
|
101
106
|
const identity = read.status === "identity" ? read.identity : null;
|
|
102
107
|
const attach = attachment(identity);
|
|
103
108
|
const reason = reasonFields(deploymentReasonParts({ local: false, machine, sshHost: g.target?.sshHost, probe: g.probe, identityStatus: read.status, attach,
|
|
104
|
-
ref: identity?.ref, cliReadsRemotes: cliReadsRemotes(held), rosterError: g.remembered ? held.rosterFailure : null }, terms));
|
|
109
|
+
ref: identity?.ref, cliReadsRemotes: cliReadsRemotes(held.cli), rosterError: g.remembered ? held.rosterFailure : null }, terms));
|
|
105
110
|
const moved = held.remembered.note(g.id);
|
|
106
111
|
const standalone = attach.note === "standalone" ? deploymentReason({ local: false, attach: { unattached: "standalone" } }, terms) : null;
|
|
107
112
|
return { id: d.id, local: false, machine, path: g.target?.workspace || "", label: shortPath(g.target?.workspace || ""), name: d.name,
|
|
@@ -216,9 +221,10 @@ export function deploymentEntry(info, primary) {
|
|
|
216
221
|
|
|
217
222
|
/** One deployment's own panel, as served before views. */
|
|
218
223
|
export function deploymentPanel(held, ws) {
|
|
219
|
-
|
|
224
|
+
// Another machine's panel never says who made its `error`: the key is removed here whatever the panel carried.
|
|
225
|
+
if (ws?.remote) { const { errorOrigin: _sent, ...panel } = remotePanel(ws.group, held.at); return { ...panel, observedAt: null, refreshing: held.remoteCollecting }; }
|
|
220
226
|
const observed = ws ? held.snapshot.byWs.get(ws.id) : null;
|
|
221
|
-
const instances = observed?.instances || [];
|
|
227
|
+
const instances = observed?.instances || [], kept = keptFailure(observed);
|
|
222
228
|
return {
|
|
223
229
|
workspace: ws ? { id: ws.id, name: ws.name, team: null } : null,
|
|
224
230
|
team: null,
|
|
@@ -230,8 +236,9 @@ export function deploymentPanel(held, ws) {
|
|
|
230
236
|
refreshing: !!ws && held.observing.has(ws.id),
|
|
231
237
|
running: instances.filter((i) => i.running).length,
|
|
232
238
|
instances,
|
|
233
|
-
// A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`):
|
|
234
|
-
|
|
239
|
+
// A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`): its message, who made it
|
|
240
|
+
// (`errorOrigin`, "kernel" or absent) and its bounded cause. `error` is a string exactly when one is kept.
|
|
241
|
+
...(kept ? { error: kept.message, ...(kept.origin ? { errorOrigin: kept.origin } : {}) } : {}),
|
|
235
242
|
...(observed?.errorCause ? { errorCause: observed.errorCause } : {}),
|
|
236
243
|
};
|
|
237
244
|
}
|
|
@@ -14,7 +14,9 @@ export const absolute = v => typeof v === 'string' && v.startsWith('/') && v.len
|
|
|
14
14
|
const name = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(v);
|
|
15
15
|
const exact = (v, keys) => record(v) && Object.keys(v).every(k => keys.includes(k));
|
|
16
16
|
const states = ['pass', 'fail', 'unknown', 'not-applicable'];
|
|
17
|
-
|
|
17
|
+
// The URL alternative finds `://` first and looks behind it for the scheme, as display-text.mjs `UNSAFE`
|
|
18
|
+
// does and for its reason: time that grows with the length of the text, not with the square of a run.
|
|
19
|
+
const unsafe = /[\x00-\x08\x0b-\x1f\x7f]|:\/\/(?<=[a-z][a-z0-9+.-]*:\/\/)[^\s/]*@|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+/i;
|
|
18
20
|
function text(v, max = 1024) { if (typeof v !== 'string' || v.length > max) throw Error(); return unsafe.test(v) ? '[Detail withheld]' : v; }
|
|
19
21
|
const nullable = v => v == null ? null : text(v);
|
|
20
22
|
export function readinessSelector(v) {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
/** Which roster rows can be addressed, why a row can't, and the copy for a remote read or plan
|
|
2
2
|
* that the host (or this machine's router) refused. Shared by the renderer and the server. */
|
|
3
|
-
import { unsupportedSession } from './instance-presentation.mjs';
|
|
3
|
+
import { unsupportedSession, runtimeErrorSpeaker, HERDR_STAND_IN } from './instance-presentation.mjs';
|
|
4
4
|
import { displayLine, cleanLine, DETAIL_WITHHELD } from './display-text.mjs';
|
|
5
5
|
|
|
6
6
|
/** A local row, or a remote row the kernel reports addressable (routed by `--server <id> --home <abs>`).
|
|
@@ -28,18 +28,43 @@ export function unaddressableSentence(row) {
|
|
|
28
28
|
: `${shownLabel(label, true)} did not report this instance as reachable.`;
|
|
29
29
|
}
|
|
30
30
|
|
|
31
|
-
/**
|
|
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.
|
|
32
38
|
* `label` is the roster meta line's state segment; `sentence` is the row's title, accessible
|
|
33
|
-
* description and actions-menu reason.
|
|
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. */
|
|
34
56
|
export function rowReason(row) {
|
|
35
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.
|
|
36
62
|
const herdr = unsupportedSession(row);
|
|
37
|
-
if (herdr) return { key: 'herdr', label: 'Herdr no longer supported',
|
|
38
|
-
if (row.server && row.serverUnreached) return { key: 'unreached', label: `${label} not reached`,
|
|
39
|
-
|
|
40
|
-
if (row
|
|
41
|
-
if (
|
|
42
|
-
if (row.running == null) return { key: 'unknown', label: 'state unknown', sentence: row.runtimeError || `${row.instance}: status unknown` };
|
|
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`)) };
|
|
43
68
|
return null;
|
|
44
69
|
}
|
|
45
70
|
|
|
@@ -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
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { harnessOf } from "./harness-names.mjs";
|
|
2
|
-
import { unsupportedSession } from "./instance-presentation.mjs";
|
|
2
|
+
import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
|
|
3
|
+
import { madeByKernel } from "./kernel-made.mjs";
|
|
3
4
|
import { waitingOnYouData } from "./waiting-on-you.mjs";
|
|
4
5
|
/** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
|
|
5
6
|
export function remoteWorkspace(group) {
|
|
@@ -10,16 +11,41 @@ export function remoteWorkspace(group) {
|
|
|
10
11
|
};
|
|
11
12
|
}
|
|
12
13
|
|
|
13
|
-
/**
|
|
14
|
-
* the
|
|
15
|
-
|
|
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");
|
|
16
41
|
const ws = remoteWorkspace(group);
|
|
17
42
|
// A row's soul subtitle: its own group's soul list only, a string as the host reported it, never synthesized.
|
|
18
43
|
const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
|
|
19
44
|
// A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
|
|
20
|
-
const instances = (group.instances || []).map(({ runtime: _released, ...i }) => {
|
|
45
|
+
const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, ...i }) => {
|
|
21
46
|
const unsupported = unsupportedSession(i);
|
|
22
|
-
|
|
47
|
+
const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
|
|
48
|
+
const row = {
|
|
23
49
|
...i, server: group.server, savedRoute: i.savedRoute === true,
|
|
24
50
|
// The last roster read of this server failed: its rows are last-known, their state unknown.
|
|
25
51
|
serverUnreached: !group.probe.ok,
|
|
@@ -33,6 +59,7 @@ export function remotePanel(group, at = new Date().toISOString()) {
|
|
|
33
59
|
...(Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: waitingOnYouData(i.waitingOnYou) } : {}),
|
|
34
60
|
...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
|
|
35
61
|
};
|
|
62
|
+
return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
|
|
36
63
|
});
|
|
37
64
|
return {
|
|
38
65
|
workspace: { id: ws.id, name: ws.name, scope: ws.scope, team: null, server: ws.server,
|
|
@@ -59,6 +86,65 @@ export function unavailableGroups(groups, error) {
|
|
|
59
86
|
return groups.map((g) => ({ ...g, probe: { ok: false, error }, instances: (g.instances || []).map((i) => ({ ...i, running: null })) }));
|
|
60
87
|
}
|
|
61
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
|
+
|
|
62
148
|
export function spawnedWorkspace(groups, result) {
|
|
63
149
|
if (!result.server || !result.target) return undefined;
|
|
64
150
|
const group = groups.find((g) => g.server === result.server && g.registrationPresent
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
// Remote terminal addressing is an installed-CLI operation, never a renderer
|
|
2
|
+
// supplied SSH command, executable path, socket or server registration.
|
|
3
|
+
//
|
|
4
|
+
// Opening an agent's terminal with the kernel's own viewer (`oats session attach`): the arguments
|
|
5
|
+
// of the viewer for this machine and for another, whether its detach key can be used, and, for
|
|
6
|
+
// another machine, the preflight (`oats session inspect`) that runs before the viewer starts.
|
|
7
|
+
//
|
|
8
|
+
// A failed `prepareRemoteTerm` throws one of these, and `preflightFailure` reads any of them:
|
|
9
|
+
//
|
|
10
|
+
// code E_TERM_CONTEXT_CHANGED the caller's `signal` aborted or its `current()` turned false
|
|
11
|
+
// code E_TERM_REMOTE_NO_SSH, the preflight's own outcomes: terminal-contract.mjs has a
|
|
12
|
+
// E_TERM_REMOTE_UNREACHABLE, sentence for each
|
|
13
|
+
// E_TERM_PREPARE_TIMEOUT,
|
|
14
|
+
// E_TERM_REMOTE_NO_ANSWER,
|
|
15
|
+
// E_TERM_REMOTE_GONE, E_HERDR_REMOVED
|
|
16
|
+
// any other refusal envelope the kernel's refusal, or a host's relayed by it, with its
|
|
17
|
+
// `code` and `message` as given (E_TERM_OPEN_FAILED and a
|
|
18
|
+
// fixed message where it gave none)
|
|
19
|
+
// code unsupported-remote-operation, the installed CLI cannot do it: decided before any process
|
|
20
|
+
// unsupported-detach-key
|
|
21
|
+
// no code, or one that is not a string the target was invalid, the CLI did not start, or it
|
|
22
|
+
// answered no envelope
|
|
23
|
+
//
|
|
24
|
+
// Not loadable by a page: it reaches `node:` builtins through its runner.
|
|
25
|
+
import { requireRemoteSupport } from "./cli-locator.mjs";
|
|
26
|
+
import { runTerminalCommand } from './terminal-exec.mjs';
|
|
27
|
+
import { HERDR_REMOVED, terminalFailure, terminalMessage } from './terminal-contract.mjs';
|
|
28
|
+
|
|
29
|
+
/** The kernel feature of `session attach --detach-key` (docs/desktop-cli-api.md). */
|
|
30
|
+
export const DETACH_KEY_FEATURE = "session-attach-detach-key";
|
|
31
|
+
/** The kernel feature under which a roster group's `probe.features` is the host's own list
|
|
32
|
+
* (docs/desktop-cli-api.md, `probe.features`). Without it that key says nothing. */
|
|
33
|
+
const PROBE_FEATURES_FEATURE = "server-probe-features";
|
|
34
|
+
// Array.isArray, as in requireRemoteSupport: a string must not pass a gate that exists to fail closed.
|
|
35
|
+
const lists = (cli, feature) => cli?.ok === true && Array.isArray(cli.features) && cli.features.includes(feature);
|
|
36
|
+
|
|
37
|
+
/** This machine's CLI takes the key: an accepted probe (`cli.ok === true`) whose `features` is an
|
|
38
|
+
* array naming the feature. */
|
|
39
|
+
export function detachKeySupported(cli) {
|
|
40
|
+
return lists(cli, DETACH_KEY_FEATURE);
|
|
41
|
+
}
|
|
42
|
+
/** The key can be offered for a row on another machine: this machine's CLI takes it and relays what
|
|
43
|
+
* each host lists about itself, the group's last roster read succeeded, and the host's own list
|
|
44
|
+
* names the feature. `group` is a group of `oats server roster --json` as read. `features: null`,
|
|
45
|
+
* a missing key and a failed read are unknown, and unknown is not supported; nothing is decided
|
|
46
|
+
* from a refusal and nothing probes. For what a client offers only: `sessionAttachArgv` does not
|
|
47
|
+
* ask it, because the kernel refuses a host without the feature and starts no viewer. */
|
|
48
|
+
export function hostDetachKeySupported(cli, group) {
|
|
49
|
+
const probe = group?.probe;
|
|
50
|
+
return detachKeySupported(cli) && lists(cli, PROBE_FEATURES_FEATURE)
|
|
51
|
+
&& probe?.ok === true && Array.isArray(probe.features) && probe.features.includes(DETACH_KEY_FEATURE);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const coded = (code, message) => Object.assign(new Error(message), { code });
|
|
55
|
+
const herdrRemoved = message => coded('E_HERDR_REMOVED', message);
|
|
56
|
+
const unreachable = () => coded('E_TERM_REMOTE_UNREACHABLE', 'the remote server could not be reached');
|
|
57
|
+
/** The CLI's JSON envelope, or null when it printed none. */
|
|
58
|
+
function envelopeOf(stdout) {
|
|
59
|
+
let envelope;
|
|
60
|
+
try { envelope = JSON.parse(stdout); } catch { return null; }
|
|
61
|
+
return envelope?.schemaVersion === 1 && typeof envelope.ok === 'boolean' ? envelope : null;
|
|
62
|
+
}
|
|
63
|
+
/** What a refusal said, for each error `refusal` returns from its last line: the envelope's own
|
|
64
|
+
* `code`, `message` and `details.fix`, each null where it gave no string. Kept beside the error and
|
|
65
|
+
* not on it, so the error thrown has the properties it always had; read by `preflightFailure` only. */
|
|
66
|
+
const keptRefusals = new WeakMap();
|
|
67
|
+
const stringOrNull = value => (typeof value === 'string' ? value : null);
|
|
68
|
+
/** A refusal envelope as a coded error. The CLI reports ssh's own failure as E_SSH: a transport
|
|
69
|
+
* failure, unless its details say ssh never started on this computer (nothing to retry); a 0.31
|
|
70
|
+
* kernel's E_HERDR_REMOVED keeps its message; any other refusal keeps the host's code. */
|
|
71
|
+
function refusal(envelope) {
|
|
72
|
+
const { code, message, details } = envelope.error || {};
|
|
73
|
+
if (code === 'E_SSH' && details?.sshStarted === false) return coded('E_TERM_REMOTE_NO_SSH', 'ssh is not available on this computer');
|
|
74
|
+
if (code === 'E_SSH') return unreachable();
|
|
75
|
+
if (code === 'E_HERDR_REMOVED') return herdrRemoved(typeof message === 'string' && message ? message : HERDR_REMOVED);
|
|
76
|
+
const error = coded(typeof code === 'string' && code ? code : 'E_TERM_OPEN_FAILED', message || 'remote session inspection failed');
|
|
77
|
+
keptRefusals.set(error, { code: stringOrNull(code), message: stringOrNull(message), fix: stringOrNull(details?.fix) });
|
|
78
|
+
return error;
|
|
79
|
+
}
|
|
80
|
+
/** What a failed preflight says. `error` is what `prepareRemoteTerm` threw; `server` is the label a
|
|
81
|
+
* sentence names.
|
|
82
|
+
*
|
|
83
|
+
* code the terminal table's code for it (E_TERM_OPEN_FAILED for anything the table does not know)
|
|
84
|
+
* sentence the table's sentence, naming `server` where it has a place for one
|
|
85
|
+
* said null, or { code, message, fix }: what the kernel said (this machine's, or another
|
|
86
|
+
* host's relayed by it), only for a refusal kept as it came for which the table has no
|
|
87
|
+
* sentence of its own. Each is the envelope's own string or null, and `said` is null
|
|
88
|
+
* when all three are. Text from outside: a client draws `message` and `fix` with
|
|
89
|
+
* kernel-lines.mjs `kernelLines` and nothing else.
|
|
90
|
+
*
|
|
91
|
+
* Any other error has `said: null`, also one made by hand with a refusal's code and message: the
|
|
92
|
+
* message of a CLI that did not start holds a path and is never shown. */
|
|
93
|
+
export function preflightFailure(error, server) {
|
|
94
|
+
const code = terminalFailure(error?.code).code;
|
|
95
|
+
const kept = code === 'E_TERM_OPEN_FAILED' ? keptRefusals.get(error) : undefined;
|
|
96
|
+
const said = kept && (kept.code !== null || kept.message !== null || kept.fix !== null) ? { ...kept } : null;
|
|
97
|
+
return { code, sentence: terminalMessage(error?.code, server), said };
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** A remote terminal is its server and its absolute home: routed as `--server S --home H`, never by a bare name. */
|
|
101
|
+
export function remoteTargetKey(remote) {
|
|
102
|
+
if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(remote?.serverId || "")
|
|
103
|
+
|| !/^[a-z0-9][a-z0-9-]*$/.test(remote?.instance || "")) throw new Error("invalid remote terminal target");
|
|
104
|
+
if (typeof remote.home !== "string" || !remote.home.startsWith("/") || remote.home.includes("\0")) throw new Error("invalid remote terminal home");
|
|
105
|
+
return JSON.stringify(["remote", remote.serverId, remote.home]);
|
|
106
|
+
}
|
|
107
|
+
/** The arguments of the kernel's viewer (the binary is `cli.bin`), a new array each call.
|
|
108
|
+
*
|
|
109
|
+
* target { home } on this machine; { serverId, instance, home } on another (what
|
|
110
|
+
* `remoteTargetKey` admits, and it refuses as it always did)
|
|
111
|
+
* detachKey undefined for none; else a non-empty string, appended as `--detach-key <key>`
|
|
112
|
+
*
|
|
113
|
+
* The client holds no copy of the kernel's key grammar: a key the kernel does not accept is the
|
|
114
|
+
* kernel's refusal. A key for a CLI that does not take one throws `unsupported-detach-key`: a
|
|
115
|
+
* kernel without the feature ignores the flag and opens a viewer with no exit, so the flag is
|
|
116
|
+
* never tried (docs/desktop-cli-api.md). Its message is for a developer; a client decides what it
|
|
117
|
+
* offers with `detachKeySupported`. */
|
|
118
|
+
export function sessionAttachArgv(cli, target, { detachKey } = {}) {
|
|
119
|
+
let address;
|
|
120
|
+
if (target?.serverId !== undefined) {
|
|
121
|
+
remoteTargetKey(target);
|
|
122
|
+
address = ["--server", target.serverId, "--home", target.home];
|
|
123
|
+
} else {
|
|
124
|
+
if (typeof target?.home !== "string" || !target.home.startsWith("/") || target.home.includes("\0")) throw new Error("invalid session home");
|
|
125
|
+
address = ["--home", target.home];
|
|
126
|
+
}
|
|
127
|
+
if (detachKey === undefined) return ["session", "attach", ...address];
|
|
128
|
+
if (typeof detachKey !== "string" || !detachKey) throw new TypeError("a detach key is a non-empty string");
|
|
129
|
+
if (!detachKeySupported(cli)) throw Object.assign(new Error(`installed oats ${cli?.version || "unknown"} does not support session attach --detach-key; update the CLI`), { code: "unsupported-detach-key" });
|
|
130
|
+
return ["session", "attach", ...address, "--detach-key", detachKey];
|
|
131
|
+
}
|
|
132
|
+
/** The preflight of an attach on another machine, and the viewer to start after it: { binary, args }.
|
|
133
|
+
*
|
|
134
|
+
* run the whole run of the CLI, in the shape of terminal-exec.mjs `runTerminalCommand`; a
|
|
135
|
+
* caller that passes it owns the run, and `exec` is then not used
|
|
136
|
+
* exec what the default runner starts the CLI with, in `execFile`'s signature
|
|
137
|
+
* detachKey as `sessionAttachArgv` takes it. The viewer's arguments are built before the
|
|
138
|
+
* inspect runs, so a key that cannot be used starts no process; the inspect never
|
|
139
|
+
* carries the key. */
|
|
140
|
+
export async function prepareRemoteTerm(cli, remote, { exec, run = (binary, args, options) => runTerminalCommand(binary, args, options, exec), signal, current = () => true, detachKey } = {}) {
|
|
141
|
+
const check = () => { if (signal?.aborted || !current()) throw Object.assign(new Error('Terminal context changed'), { code: 'E_TERM_CONTEXT_CHANGED' }); };
|
|
142
|
+
check();
|
|
143
|
+
requireRemoteSupport(cli, "session");
|
|
144
|
+
const bin = cli.bin;
|
|
145
|
+
remoteTargetKey(remote);
|
|
146
|
+
const address = ["--server", remote.serverId, "--home", remote.home];
|
|
147
|
+
const args = sessionAttachArgv(cli, remote, { detachKey });
|
|
148
|
+
check(); // actual execution owner, not only IPC admission
|
|
149
|
+
let stdout;
|
|
150
|
+
try {
|
|
151
|
+
({ stdout } = await run(bin, ["session", "inspect", ...address, "--json"], {
|
|
152
|
+
encoding: "utf8", timeout: 20000, maxBuffer: 1024 * 1024, shell: false, ...(signal ? { signal } : {}),
|
|
153
|
+
}));
|
|
154
|
+
} catch (error) {
|
|
155
|
+
check();
|
|
156
|
+
const envelope = typeof error?.stdout === 'string' ? envelopeOf(error.stdout) : null;
|
|
157
|
+
if (envelope && !envelope.ok) throw refusal(envelope);
|
|
158
|
+
// Killed by execFile at the deadline: a stalled link outlives ssh's keepalives (about 45 s),
|
|
159
|
+
// so it is a timeout. A CLI that ended without a refusal, by a nonzero exit (255 included) or
|
|
160
|
+
// a signal of its own, gave no answer: ssh's own failures arrive as E_SSH, so this is more
|
|
161
|
+
// likely the local CLI. A CLI that never started keeps its own error.
|
|
162
|
+
if (error?.killed) throw coded('E_TERM_PREPARE_TIMEOUT', 'remote session inspection timed out');
|
|
163
|
+
if (Number.isInteger(error?.code) || error?.signal) throw coded('E_TERM_REMOTE_NO_ANSWER', 'the local oats gave no answer');
|
|
164
|
+
throw error;
|
|
165
|
+
}
|
|
166
|
+
check();
|
|
167
|
+
const envelope = envelopeOf(stdout);
|
|
168
|
+
if (!envelope) throw new Error("remote session inspection answered no envelope");
|
|
169
|
+
if (!envelope.ok) throw refusal(envelope);
|
|
170
|
+
// A 0.31 kernel refuses a Herdr-recorded instance; an older one still reports its live Herdr
|
|
171
|
+
// session. Neither is attached: the refusal keeps its code so the broker reports it.
|
|
172
|
+
if (envelope.result?.backend === 'herdr') throw herdrRemoved(HERDR_REMOVED);
|
|
173
|
+
if (envelope.result?.present !== true) throw coded('E_TERM_REMOTE_GONE', "remote terminal no longer exists");
|
|
174
|
+
return { binary: bin, args };
|
|
175
|
+
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Confirmed K6d input/data boundary. No kernel resolution or renderer key authority. */
|
|
2
|
-
import { retainedSpawnDetails } from './launch-prompt-outcome.mjs';
|
|
2
|
+
import { retainedSpawnDetails, launchFlagIgnored, flagIgnoredFact } from './launch-prompt-outcome.mjs';
|
|
3
3
|
import { harnessOf } from './harness-names.mjs';
|
|
4
4
|
import { record, previewSupported, previewSelector, previewChoices, previewTarget, previewData, previewFailure, MAX_HOOKS } from './spawn-preview-contract.mjs';
|
|
5
5
|
import { spawnDecision, sameSpawnDecision } from './spawn-decision.mjs';
|
|
@@ -74,7 +74,13 @@ export function spawnWakeOutcome(value, requested) {
|
|
|
74
74
|
if (value.saved === false && !error) return null;
|
|
75
75
|
return { requested: value.requested, saved: value.saved, error };
|
|
76
76
|
}
|
|
77
|
-
/** A qualified creation receipt, not executable terminal/session instructions.
|
|
77
|
+
/** A qualified creation receipt, not executable terminal/session instructions.
|
|
78
|
+
*
|
|
79
|
+
* `flagIgnored` (optional) is the one fact of the kernel's answer the receipt carries as text: a launched
|
|
80
|
+
* spawn where Claude Code ignored the channel option (launchFlagIgnored: `launchPrompts.status`
|
|
81
|
+
* "flag-ignored", with the answer's warnings as bounded display lines). Absent for any other status, for
|
|
82
|
+
* an answer without `launchPrompts`, and for a spawn that was not launched. It holds facts and no sentence.
|
|
83
|
+
* Every other warning of an apply stays a count (`warningCount`). */
|
|
78
84
|
export function spawnCreationReceipt(v, { target, preview, wakeRequested = false } = {}) {
|
|
79
85
|
const selected = previewTarget(target), expected = spawnDecision(preview?.decision, { effectiveRequired: true });
|
|
80
86
|
const decision = spawnDecision(v?.decision, { effectiveRequired: true });
|
|
@@ -93,10 +99,11 @@ export function spawnCreationReceipt(v, { target, preview, wakeRequested = false
|
|
|
93
99
|
wake = spawnWakeOutcome({ requested: true, saved: false, error: v.wakeScheduleError }, true);
|
|
94
100
|
}
|
|
95
101
|
if (!wake) return null;
|
|
102
|
+
const flagIgnored = v.launched ? launchFlagIgnored(v) : null;
|
|
96
103
|
return { instance: v.instance, agent: v.agent, home: v.home, agentsRoot: selected.selector.agentsRoot,
|
|
97
104
|
workspace: selected.workspace, server: null, repo: v.repo, work: v.work, branch: v.branch,
|
|
98
105
|
harness: harnessOf(v), model: v.model, launched: v.launched, replayed: v.replayed, decision,
|
|
99
|
-
warningCount: v.warnings.length, wake };
|
|
106
|
+
warningCount: v.warnings.length, wake, ...(flagIgnored ? { flagIgnored } : {}) };
|
|
100
107
|
}
|
|
101
108
|
/** Project the Desktop HTTP view again at the main/renderer trust boundaries. */
|
|
102
109
|
export function spawnApplyView(v, expected = {}) {
|
|
@@ -122,8 +129,13 @@ export function spawnApplyView(v, expected = {}) {
|
|
|
122
129
|
if (['complete', 'partial'].includes(v.status)) {
|
|
123
130
|
if (!record(v.receipt) || !Number.isInteger(v.receipt.warningCount) || v.receipt.warningCount < 0 || v.receipt.warningCount > 512
|
|
124
131
|
|| v.receipt.workspace !== target.workspace || v.receipt.agentsRoot !== target.selector.agentsRoot || v.receipt.server !== null) return null;
|
|
125
|
-
receipt
|
|
132
|
+
// The receipt is rebuilt from its own keys: the warnings are a count here, so `flagIgnored` is read from
|
|
133
|
+
// the receipt's key through the reader's decoder, never composed again. Tolerant: a value that does not
|
|
134
|
+
// decode is dropped, and the receipt stands.
|
|
135
|
+
receipt = spawnCreationReceipt({ ...v.receipt, warnings: Array(v.receipt.warningCount).fill(''), launchPrompts: undefined }, { target, preview, wakeRequested: v.wakeRequested });
|
|
126
136
|
if (!receipt) return null;
|
|
137
|
+
const flagIgnored = receipt.launched ? flagIgnoredFact(v.receipt.flagIgnored) : undefined;
|
|
138
|
+
if (flagIgnored) receipt.flagIgnored = flagIgnored;
|
|
127
139
|
const partial = v.wakeRequested && receipt.wake.saved !== true;
|
|
128
140
|
if ((v.status === 'partial') !== partial) return null;
|
|
129
141
|
if (partial) reason = receipt.wake.error ?? { code: 'E_WAKE_OUTCOME_UNKNOWN', message: WAKE_OUTCOME_UNKNOWN };
|