@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.
- package/README.md +3 -1
- package/bin/oats.mjs +407 -123
- package/docs/capabilities.md +75 -6
- package/docs/configuration.md +200 -91
- package/docs/desktop-cli-api.md +1563 -113
- package/docs/desktop-instance-start.md +69 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +145 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +238 -17
- package/docs/integrations.md +13 -9
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/macos-test-runs.md +246 -0
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +225 -11
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +97 -4
- package/docs/souls-and-instances.md +332 -40
- package/docs/tui.md +584 -0
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +278 -49
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +1282 -289
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +45 -17
- package/lib/instance-lifecycle.mjs +306 -57
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +236 -9
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- 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 +125 -22
- package/lib/schedule.mjs +73 -24
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/system-tools.mjs +39 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +54 -30
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +4 -4
- package/package.json +8 -2
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +561 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +72 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +95 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +180 -0
- package/packages/client/deployment-read-cli.mjs +57 -0
- package/packages/client/display-text.mjs +50 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +90 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +76 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +86 -0
- package/packages/client/instance-tree.mjs +462 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +200 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +413 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +48 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +293 -0
- package/packages/client/readiness-contract.mjs +174 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +151 -0
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +153 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +195 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +142 -0
- package/packages/client/spawn-preview-cli.mjs +38 -0
- package/packages/client/spawn-preview-contract.mjs +318 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +183 -0
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +64 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +44 -0
- package/packages/tui/lib/client.mjs +35 -0
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +176 -0
- 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 +367 -0
- package/packages/tui/lib/term/screen.mjs +134 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +109 -0
- package/packages/tui/lib/term/tty.mjs +178 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +256 -0
- package/packages/tui/lib/views/help.mjs +140 -0
- 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/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +30 -23
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
// OATS desktop — CLI locator/probe (Desktop CLI API v1).
|
|
2
|
+
//
|
|
3
|
+
// The app's ONLY path to lifecycle mutations is a compatible installed
|
|
4
|
+
// `oats` CLI (desktop-dist contract). This module finds it:
|
|
5
|
+
//
|
|
6
|
+
// discovery order (first acceptable candidate wins):
|
|
7
|
+
// 1. persisted user-selected absolute executable
|
|
8
|
+
// 2. OATS_DESKTOP_OATS_BIN (test/development only)
|
|
9
|
+
// 3. the app process PATH
|
|
10
|
+
// 4. npm global-prefix candidates
|
|
11
|
+
// 5. login-shell `command -v oats` with a timeout
|
|
12
|
+
//
|
|
13
|
+
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
|
+
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
|
+
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.54.0 (the band is
|
|
17
|
+
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
|
+
// API version — not source adjacency — is authoritative.
|
|
19
|
+
//
|
|
20
|
+
// Pure/injected: all process, fs and exec effects come through `io` so the
|
|
21
|
+
// discovery matrix and acceptance rules are unit-testable and
|
|
22
|
+
// mutation-checkable without a real CLI.
|
|
23
|
+
import { delimiter, isAbsolute, join } from "node:path";
|
|
24
|
+
import { harnessList } from "./harness-names.mjs";
|
|
25
|
+
|
|
26
|
+
export const DESKTOP_API = 1;
|
|
27
|
+
// The accepted band is per-minor and widened DELIBERATELY, once per kernel
|
|
28
|
+
// minor, after confirming the Desktop v1 surface (`version --json` probe,
|
|
29
|
+
// `spawn --json`, `okf harvest --json` — test/cli-json-contract.test.mjs) is
|
|
30
|
+
// unchanged. It must always admit the kernel version shipped by the SAME
|
|
31
|
+
// release: Desktop and the kernel are built from one tag, so a band that
|
|
32
|
+
// excluded its own kernel would ship an app that degrades to observation-only
|
|
33
|
+
// against the CLI it was released with (the 0.19.0 readiness blocker).
|
|
34
|
+
// Rebased to >=0.22.0 <0.23.0 for the OATS rename (v0.22.0, first release
|
|
35
|
+
// under the new name): the CLI binary and probe name changed to `oats` /
|
|
36
|
+
// `@awebai/oats`, so the pre-rename band pointed at versions that will never
|
|
37
|
+
// exist under the new name. The Desktop v1 surface is UNCHANGED across that
|
|
38
|
+
// kernel bump (`version --json`, `spawn --json`, `okf harvest --json` —
|
|
39
|
+
// test/cli-json-contract.test.mjs), so DESKTOP_API stays 1.
|
|
40
|
+
// Widened through 0.24.x for the retained-execution first cut. Desktop CLI API
|
|
41
|
+
// v1 and the 0.22.x floor remain unchanged; individual capability/refusal gates
|
|
42
|
+
// still apply. Version acceptance does not assert captured UI/backend parity.
|
|
43
|
+
// Widened through 0.25.x for the workspace model (v0.25.0): the Desktop v1
|
|
44
|
+
// surface (`version --json` probe, `spawn --json`, the retained lifecycle
|
|
45
|
+
// verbs — test/cli-json-contract.test.mjs) is unchanged; the removed verbs
|
|
46
|
+
// (`catalog`, install/use/…) surface as typed E_USAGE through the adapter.
|
|
47
|
+
// Widened through 0.26.x for package-approval removal (F2b, maintainer
|
|
48
|
+
// decision): the floor is 0.25.8 — not 0.26.0 — because main's kernel keeps
|
|
49
|
+
// reporting 0.25.8 until 0.26.0 is tagged, and the Desktop must run against
|
|
50
|
+
// it. The REAL gate is the positive `packages-no-approval` feature fence
|
|
51
|
+
// (workspace-cli WORKSPACE_FEATURES, deployment-contract DEPLOYMENT_FEATURES):
|
|
52
|
+
// released 0.25.x kernels lack it and get the "update OATS" state.
|
|
53
|
+
// Widened through 0.43.x for the 0.43.0 release: schedule and trigger rows
|
|
54
|
+
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
55
|
+
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
56
|
+
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
57
|
+
export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0, 54, 0] };
|
|
58
|
+
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
59
|
+
* rejection reason, the backend's /api status and the degradation card can
|
|
60
|
+
* never disagree with the numbers actually enforced above. */
|
|
61
|
+
export const ACCEPT_RANGE_TEXT = `>=${ACCEPT_RANGE.min.join(".")} <${ACCEPT_RANGE.maxExclusive.join(".")}`;
|
|
62
|
+
export const PROBE_NAME = "@awebai/oats";
|
|
63
|
+
// Spawn-time agent relations (--relation/--relative-to) AND the anchor
|
|
64
|
+
// qualifier (--relative-root, a later contract addition in the same
|
|
65
|
+
// unreleased feature) gate on ONE floor: the first release carrying BOTH.
|
|
66
|
+
// Older v1 CLIs IGNORE unknown spawn options and still succeed, so a
|
|
67
|
+
// pre-relations CLI would silently spawn an UNRELATED instance — and a
|
|
68
|
+
// hypothetical relations-only CLI would silently DISCARD --relative-root
|
|
69
|
+
// and link the wrong same-named anchor (review cbd5bb3 blocker). No
|
|
70
|
+
// released CLI carries relations without the qualifier (0.18.x releases to
|
|
71
|
+
// date predate both, and they merge together), so one floor covers the
|
|
72
|
+
// whole related-spawn surface; if the kernel ever ships them separately
|
|
73
|
+
// this must split into two probed capabilities. 0.18.5 released WITHOUT
|
|
74
|
+
// the feature, so the floor is the NEXT release — the first one containing
|
|
75
|
+
// feature/agent-relations. Confirmed at PR time (one-constant change).
|
|
76
|
+
export const RELATIONS_MIN = [0, 18, 6];
|
|
77
|
+
|
|
78
|
+
/** Whether an ACCEPTED v1 CLI version also supports spawn-time relations. */
|
|
79
|
+
export function supportsRelations(version) {
|
|
80
|
+
const v = parseSemver(version);
|
|
81
|
+
return !!v && !v.prerelease && cmp(v.nums, RELATIONS_MIN) >= 0;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Fail-closed gate for RELATED spawns (invariant-bearing, importable so the
|
|
85
|
+
* regression exercises this exact layer): returns an Error to THROW when a
|
|
86
|
+
* relation/anchor was requested but the accepted CLI predates relation
|
|
87
|
+
* support, else null. */
|
|
88
|
+
export function relationSupportError(cliState, { relation, relativeTo } = {}) {
|
|
89
|
+
// "unrelated" (or empty) is the DEFAULT, not a related spawn — the adapter
|
|
90
|
+
// normalizes it to absence (spawnArgv) and forwards no flags, so it must
|
|
91
|
+
// keep working across the full accepted v1 range (review 9425d6a). A
|
|
92
|
+
// supplied relativeTo still gates: the adapter rejects the mismatched pair.
|
|
93
|
+
const rel = relation === "unrelated" || relation === "" ? undefined : relation;
|
|
94
|
+
if (!rel && !relativeTo) return null;
|
|
95
|
+
if (cliState?.ok && supportsRelations(cliState.version)) return null;
|
|
96
|
+
const err = new Error(`spawn-time relations require oats >= ${RELATIONS_MIN.join(".")} — installed ${cliState?.version || "none"} would silently spawn an unrelated instance`);
|
|
97
|
+
err.code = "cli-no-relations";
|
|
98
|
+
return err;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// ---- acceptance --------------------------------------------------------
|
|
102
|
+
|
|
103
|
+
export function parseSemver(v) {
|
|
104
|
+
// Capture prerelease presence: semver precedence puts 0.18.0-rc.1 BELOW
|
|
105
|
+
// 0.18.0, so a prerelease of the minimum version is OUTSIDE >=0.18.0.
|
|
106
|
+
const m = String(v || "").match(/^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/);
|
|
107
|
+
if (!m) return null;
|
|
108
|
+
return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], prerelease: !!m[4] };
|
|
109
|
+
}
|
|
110
|
+
const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
|
|
111
|
+
|
|
112
|
+
/** Accept/reject one probe payload. Returns { ok } or { ok:false, reason }. */
|
|
113
|
+
export function acceptProbe(payload) {
|
|
114
|
+
if (!payload || typeof payload !== "object") return { ok: false, reason: "no probe payload" };
|
|
115
|
+
if (payload.schemaVersion !== 1) return { ok: false, reason: `unexpected schemaVersion ${payload.schemaVersion}` };
|
|
116
|
+
if (payload.name !== PROBE_NAME) return { ok: false, reason: `not the oats CLI (name: ${payload.name || "missing"})` };
|
|
117
|
+
if (payload.desktopApi !== DESKTOP_API) return { ok: false, reason: `desktopApi ${payload.desktopApi ?? "missing"} (need ${DESKTOP_API})` };
|
|
118
|
+
const v = parseSemver(payload.version);
|
|
119
|
+
if (!v) return { ok: false, reason: `unparsable version "${payload.version}"` };
|
|
120
|
+
// Prerelease policy: prereleases are NOT accepted. Precedence-wise
|
|
121
|
+
// 0.18.0-rc.1 < 0.18.0 (below the minimum), and a prerelease of any
|
|
122
|
+
// in-range version is not a released CLI — Desktop pairs with released
|
|
123
|
+
// kernels only.
|
|
124
|
+
if (v.prerelease) return { ok: false, reason: `prerelease version ${payload.version} not accepted (need a released ${ACCEPT_RANGE_TEXT})` };
|
|
125
|
+
if (cmp(v.nums, ACCEPT_RANGE.min) < 0 || cmp(v.nums, ACCEPT_RANGE.maxExclusive) >= 0) {
|
|
126
|
+
return { ok: false, reason: `version ${payload.version} outside ${ACCEPT_RANGE_TEXT}` };
|
|
127
|
+
}
|
|
128
|
+
return { ok: true };
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** stdout must be exactly one JSON document (the CLI contract). */
|
|
132
|
+
export function parseProbeStdout(stdout) {
|
|
133
|
+
try {
|
|
134
|
+
const doc = JSON.parse(String(stdout));
|
|
135
|
+
return doc && typeof doc === "object" ? doc : null;
|
|
136
|
+
} catch { return null; }
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
// ---- discovery -----------------------------------------------------------
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* Candidate absolute paths as LAZY thunks in contract order, each tagged
|
|
143
|
+
* with its source. Sources are evaluated only when discovery reaches them
|
|
144
|
+
* (review 53a20c7: the npm-prefix and login-shell helpers cost seconds —
|
|
145
|
+
* they must not run when an earlier candidate already wins) and each
|
|
146
|
+
* expensive source is invoked AT MOST ONCE.
|
|
147
|
+
* io = {
|
|
148
|
+
* persisted: () => string|null — user-chosen absolute path
|
|
149
|
+
* env: Record<string,string|undefined> — process env
|
|
150
|
+
* isExecutableFile: (p) => boolean — X_OK regular file
|
|
151
|
+
* npmGlobalBin: () => string|null|Promise — npm prefix -g /bin (slow)
|
|
152
|
+
* loginShellWhich: () => string|null|Promise — login-shell command -v (slow)
|
|
153
|
+
* }
|
|
154
|
+
*/
|
|
155
|
+
export function candidateSources(io) {
|
|
156
|
+
const abs = (p) => (typeof p === "string" && p && isAbsolute(p) ? p : null);
|
|
157
|
+
const sources = [
|
|
158
|
+
{ source: "persisted", paths: () => [abs(io.persisted?.())] },
|
|
159
|
+
// test/development only — never documented for end users
|
|
160
|
+
{ source: "env", paths: () => [abs(io.env?.OATS_DESKTOP_OATS_BIN)] },
|
|
161
|
+
{ source: "path", paths: () => String(io.env?.PATH || "").split(delimiter).filter(Boolean).map((dir) => abs(join(dir, "oats"))) },
|
|
162
|
+
{ source: "npm-global", paths: async () => { const bin = await io.npmGlobalBin?.(); return [abs(bin && join(bin, "oats"))]; } },
|
|
163
|
+
{ source: "login-shell", paths: async () => [abs(await io.loginShellWhich?.())] },
|
|
164
|
+
];
|
|
165
|
+
return sources;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** Eager candidate list — for tests/diagnostics only (evaluates everything). */
|
|
169
|
+
export async function candidates(io) {
|
|
170
|
+
const out = [];
|
|
171
|
+
for (const s of candidateSources(io)) {
|
|
172
|
+
for (const p of await s.paths()) if (p) out.push({ path: p, source: s.source });
|
|
173
|
+
}
|
|
174
|
+
return out;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The kernel record of an ACCEPTED probe payload: what every gate of this home reads (`bin`, `version`,
|
|
179
|
+
* the API integers, `features`, `remote`). A field is kept only in the form its gate reads: a list
|
|
180
|
+
* when the payload has a list, an API integer only at the value that is gated on. `discover` answers
|
|
181
|
+
* this for the candidate that wins. A client that probes one known kernel reads the answer with
|
|
182
|
+
* `parseProbeStdout`, accepts it with `acceptProbe`, and makes its record with this: it does not
|
|
183
|
+
* call `acceptProbe` itself, so a payload that was not accepted must not reach it.
|
|
184
|
+
*/
|
|
185
|
+
export function cliRecord(payload, { bin, source }) {
|
|
186
|
+
return { ok: true, bin, source, version: payload.version,
|
|
187
|
+
...(harnessList(payload) ? { harnesses: harnessList(payload) } : {}),
|
|
188
|
+
...(Array.isArray(payload.sessionBackends) ? { sessionBackends: payload.sessionBackends } : {}),
|
|
189
|
+
...(Array.isArray(payload.launchOptions) ? { launchOptions: payload.launchOptions } : {}),
|
|
190
|
+
...([1, 2].includes(payload.scheduleApi) ? { scheduleApi: payload.scheduleApi } : {}),
|
|
191
|
+
...(payload.operationsApi === 2 ? { operationsApi: 2 } : {}),
|
|
192
|
+
...(payload.lifecycleApi === 1 ? { lifecycleApi: 1 } : {}),
|
|
193
|
+
...(payload.readinessApi === 2 ? { readinessApi: 2 } : {}),
|
|
194
|
+
...(payload.spawnPreviewApi === 2 ? { spawnPreviewApi: 2 } : {}),
|
|
195
|
+
...(payload.spawnApplyApi === 1 ? { spawnApplyApi: 1 } : {}),
|
|
196
|
+
...(payload.eventsApi === 2 ? { eventsApi: 2 } : {}),
|
|
197
|
+
...(payload.scheduleHistoryApi === 3 ? { scheduleHistoryApi: 3 } : {}),
|
|
198
|
+
...(payload.workspaceApi === 2 ? { workspaceApi: 2 } : {}),
|
|
199
|
+
...(payload.automationsApi === 1 ? { automationsApi: 1 } : {}),
|
|
200
|
+
...(payload.capabilityShowApi === 1 ? { capabilityShowApi: 1 } : {}),
|
|
201
|
+
...(Array.isArray(payload.features) ? { features: payload.features } : {}),
|
|
202
|
+
...(Array.isArray(payload.remote) ? { remote: payload.remote } : {}) };
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* Discover the first acceptable CLI. `probe(path)` runs `<path> version
|
|
207
|
+
* --json` (execFile, absolute binary, no shell) and resolves { stdout } on
|
|
208
|
+
* CLEAN exit — it must REJECT on nonzero exit or timeout even when stdout
|
|
209
|
+
* looks valid (review 53a20c7: a binary that prints a plausible probe and
|
|
210
|
+
* then fails/hangs must never become the mutation binary). Sources are
|
|
211
|
+
* evaluated lazily: expensive helpers never run once a candidate wins.
|
|
212
|
+
* Returns:
|
|
213
|
+
* { ok:true, bin, source, version }
|
|
214
|
+
* { ok:false, tried: [{path, source, reason}] } — stable diagnostics
|
|
215
|
+
*/
|
|
216
|
+
export async function discover(io, probe) {
|
|
217
|
+
const tried = [];
|
|
218
|
+
const seen = new Set();
|
|
219
|
+
for (const src of candidateSources(io)) {
|
|
220
|
+
let paths = [];
|
|
221
|
+
try { paths = (await src.paths()).filter(Boolean); }
|
|
222
|
+
catch { continue; /* source itself failed — e.g. npm missing */ }
|
|
223
|
+
for (const raw of paths) {
|
|
224
|
+
let path = raw;
|
|
225
|
+
try { path = io.canonicalize ? io.canonicalize(path) : path; } catch { /* keep as-is */ }
|
|
226
|
+
if (seen.has(path)) continue;
|
|
227
|
+
seen.add(path);
|
|
228
|
+
if (!io.isExecutableFile(path)) { tried.push({ path, source: src.source, reason: "not an executable file" }); continue; }
|
|
229
|
+
let payload = null;
|
|
230
|
+
try {
|
|
231
|
+
const r = await probe(path);
|
|
232
|
+
payload = parseProbeStdout(r.stdout);
|
|
233
|
+
} catch (e) {
|
|
234
|
+
// Probe REJECTED (nonzero exit, timeout, spawn failure) — the
|
|
235
|
+
// candidate is out even if it printed a plausible payload first.
|
|
236
|
+
tried.push({ path, source: src.source, reason: `probe failed: ${String(e.message || e).slice(0, 120)}` });
|
|
237
|
+
continue;
|
|
238
|
+
}
|
|
239
|
+
const a = acceptProbe(payload);
|
|
240
|
+
if (a.ok) return cliRecord(payload, { bin: path, source: src.source });
|
|
241
|
+
tried.push({ path, source: src.source, reason: a.reason, version: payload?.version });
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
return { ok: false, tried };
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** Remote routing arrived within API v1; older accepted CLIs lack it. */
|
|
248
|
+
export function requireRemoteSupport(cli, operation) {
|
|
249
|
+
// Array.isArray, not optional chaining alone: String.prototype.includes
|
|
250
|
+
// would let a probe answering remote: "spawn" (a string) pass a gate that
|
|
251
|
+
// exists to fail closed (servers review N1).
|
|
252
|
+
if (!Array.isArray(cli?.remote) || !cli.remote.includes(operation)) throw Object.assign(new Error(`installed oats ${cli?.version || "unknown"} does not support remote ${operation}; update the CLI`), { code: "unsupported-remote-operation" });
|
|
253
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/* oats desktop — the gate-relevant identity of a CLI probe (server + renderer).
|
|
2
|
+
|
|
3
|
+
Every capability gate in the app (spawn, schedules, automations, inspect,
|
|
4
|
+
the capabilities catalog…) is keyed on the probe payload, and every
|
|
5
|
+
subscriber treats "the probe changed" as "the CLI changed": caches are
|
|
6
|
+
wiped, catalogs re-fetched, cards repainted. A window-focus reprobe of the
|
|
7
|
+
SAME binary returns a payload that is identical in every gate-relevant
|
|
8
|
+
field yet never byte-identical — `probedAt` is minted per probe and the
|
|
9
|
+
`tried`/`source` diagnostics describe how the locator got there, not what
|
|
10
|
+
it found. Comparing payloads by this signature instead of by identity is
|
|
11
|
+
what makes a no-change reprobe a no-op end to end.
|
|
12
|
+
|
|
13
|
+
Pure data; no node: imports so the renderer can share it with the server. */
|
|
14
|
+
|
|
15
|
+
/** Top-level fields that legitimately differ between two probes of the same
|
|
16
|
+
* CLI and therefore never participate in the signature. */
|
|
17
|
+
export const PROBE_DIAGNOSTIC_FIELDS = Object.freeze(['probedAt', 'tried', 'source']);
|
|
18
|
+
const DIAGNOSTIC = new Set(PROBE_DIAGNOSTIC_FIELDS);
|
|
19
|
+
|
|
20
|
+
/* Object keys are sorted at every depth so the serialization order a
|
|
21
|
+
* producer happens to use can never fake a change; array order IS meaning
|
|
22
|
+
* (features/harnesses are ordered lists) and is kept. `undefined` members
|
|
23
|
+
* vanish exactly as JSON.stringify would drop them. */
|
|
24
|
+
function canonical(value, top) {
|
|
25
|
+
if (value === undefined) return null;
|
|
26
|
+
if (value === null || typeof value !== 'object') return value;
|
|
27
|
+
if (Array.isArray(value)) return value.map(v => canonical(v, false));
|
|
28
|
+
const out = {};
|
|
29
|
+
for (const key of Object.keys(value).sort()) {
|
|
30
|
+
if (top && DIAGNOSTIC.has(key)) continue;
|
|
31
|
+
if (value[key] !== undefined) out[key] = canonical(value[key], false);
|
|
32
|
+
}
|
|
33
|
+
return out;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** JSON string over the gate-relevant fields of a probe/status payload.
|
|
37
|
+
* null/undefined (probe not settled) → 'null', distinct from any payload,
|
|
38
|
+
* including `{}`. */
|
|
39
|
+
export function probeSignature(state) {
|
|
40
|
+
return state == null ? 'null' : JSON.stringify(canonical(state, true));
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** True when `after` describes a different CLI/capability set than `before`
|
|
44
|
+
* in any gate-relevant field. */
|
|
45
|
+
export function probeChanged(before, after) {
|
|
46
|
+
return probeSignature(before) !== probeSignature(after);
|
|
47
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/** A client's own terms: the words a shared sentence uses where it names the client that shows it.
|
|
2
|
+
* The tables of this home hold one explanation per code for every client, and some of those sentences
|
|
3
|
+
* name the client ("this Desktop"), what to update when the client is the old one, or the machine it
|
|
4
|
+
* runs on. A table takes the terms as an argument and builds the sentence from them, so two clients
|
|
5
|
+
* show the same explanation, each in its own words.
|
|
6
|
+
*
|
|
7
|
+
* clientTerms({ name, self, selfInitial, update, thisMachine }) -> the same five, frozen
|
|
8
|
+
*
|
|
9
|
+
* name the client, as a sentence names it "… than Desktop can show."
|
|
10
|
+
* self where a sentence says "this client" "… a workspace this Desktop can't read."
|
|
11
|
+
* selfInitial the same, opening a sentence "This Desktop can't read …"
|
|
12
|
+
* update what to update when the client is the old one "Update OATS Desktop."
|
|
13
|
+
* thisMachine the label of the machine the client runs on; a label, and it opens sentences, so the
|
|
14
|
+
* client capitalises it "This Mac"
|
|
15
|
+
*
|
|
16
|
+
* Nothing has a default, here or in a table: a client says its five terms once and passes them at every
|
|
17
|
+
* call. This home holds none of its own and imports no client's.
|
|
18
|
+
*
|
|
19
|
+
* No state: no list of the objects made is kept. A table knows terms by what the object itself carries, a
|
|
20
|
+
* private field of a class this module does not export; a copy, a spread or a hand-built object has none.
|
|
21
|
+
* Only `clientTerms` can make one: the class is reachable from nowhere else (its prototype names no
|
|
22
|
+
* constructor), and what it stores is what was checked, each value read from the caller once. */
|
|
23
|
+
import { cleanLine } from './display-text.mjs';
|
|
24
|
+
|
|
25
|
+
const KEYS = Object.freeze(['name', 'self', 'selfInitial', 'update', 'thisMachine']);
|
|
26
|
+
|
|
27
|
+
class ClientTerms {
|
|
28
|
+
#made = true;
|
|
29
|
+
/** `checked`: the five values `clientTerms` read and checked. Never the caller's own object. */
|
|
30
|
+
constructor(checked) { for (const key of KEYS) this[key] = checked[key]; Object.freeze(this); }
|
|
31
|
+
static made(value) { return typeof value === 'object' && value !== null && #made in value; }
|
|
32
|
+
}
|
|
33
|
+
// Without this, `terms.constructor` would hand the class to anyone holding terms, and `new` on it would
|
|
34
|
+
// give an object that carries the field and none of the checks.
|
|
35
|
+
delete ClientTerms.prototype.constructor;
|
|
36
|
+
Object.freeze(ClientTerms.prototype); Object.freeze(ClientTerms);
|
|
37
|
+
|
|
38
|
+
/** The terms of one client. Throws a TypeError that names the key when one is missing, empty, not a
|
|
39
|
+
* string or not one display line (display-text.mjs `cleanLine`), and when a key is not one of the five. */
|
|
40
|
+
export function clientTerms(values) {
|
|
41
|
+
if (typeof values !== 'object' || values === null || Array.isArray(values)) throw new TypeError('clientTerms: pass an object with name, self, selfInitial, update and thisMachine');
|
|
42
|
+
for (const key of Reflect.ownKeys(values)) if (!KEYS.includes(key)) throw new TypeError(`clientTerms: ${String(key)} is not a term (the terms are ${KEYS.join(', ')})`);
|
|
43
|
+
// Each value is read once, and that reading is what is checked and kept: a getter that answers
|
|
44
|
+
// differently the second time has no second time.
|
|
45
|
+
const checked = {};
|
|
46
|
+
for (const key of KEYS) {
|
|
47
|
+
if (!Object.hasOwn(values, key)) throw new TypeError(`clientTerms: ${key} is missing`);
|
|
48
|
+
const value = values[key];
|
|
49
|
+
if (!cleanLine(value)) throw new TypeError(`clientTerms: ${key} must be a string of one display line, and not empty`);
|
|
50
|
+
checked[key] = value;
|
|
51
|
+
}
|
|
52
|
+
return new ClientTerms(checked);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** What a table calls first: the terms as given, or a TypeError when they are absent or are not an
|
|
56
|
+
* object `clientTerms` returned. `table` names the function that was called without them. */
|
|
57
|
+
export function requireTerms(terms, table) {
|
|
58
|
+
if (!ClientTerms.made(terms)) throw new TypeError(`${table}: terms must be the object clientTerms() returned`);
|
|
59
|
+
return terms;
|
|
60
|
+
}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/** Native workspace-v2 read contract. No filesystem discovery or generation adapters. */
|
|
2
|
+
export const DEPLOYMENT_FEATURES = Object.freeze(['workspace-v2', 'instance-modules', 'served-identity', 'packages-no-approval']);
|
|
3
|
+
export const deploymentRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
4
|
+
/** The code of a kernel error envelope, as the deployment reader admits one (deployment-read-cli.mjs): the one
|
|
5
|
+
* test of its shape. A reason the reader marks `origin: 'kernel'` always carries such a code, and the sentence
|
|
6
|
+
* that attributes a reason to the kernel (deployment-facts.mjs) asks for both. */
|
|
7
|
+
export const deploymentErrorCode = value => typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(value);
|
|
8
|
+
|
|
9
|
+
/* Spec D: why a remote read failed (kernel E_REMOTE_UNREADABLE `details.reason`, e.g. "cache", "network",
|
|
10
|
+
* "timeout"), bounded. Only the reason and the host of `details.url` cross; never paths, pids, locks or the
|
|
11
|
+
* cache dir (the kernel's `message` already names those, and is shown as given). */
|
|
12
|
+
const CAUSE_REASON = /^[a-z][a-z-]{0,31}$/;
|
|
13
|
+
const CAUSE_HOST = /^(?:[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?|\[[0-9A-Fa-f:.]{2,45}\])$/;
|
|
14
|
+
function causeHost(url) {
|
|
15
|
+
if (typeof url !== 'string' || !url || url.length > 2048) return null;
|
|
16
|
+
let host = null;
|
|
17
|
+
try { host = new URL(url).hostname; } catch { host = /^[^@\s/]+@([^:\s/]+):/.exec(url)?.[1] ?? null; } // scp-like git@host:path
|
|
18
|
+
return host && CAUSE_HOST.test(host) ? host.toLowerCase() : null;
|
|
19
|
+
}
|
|
20
|
+
/** The kernel's failure details → { reason, host? } | null. */
|
|
21
|
+
export function remoteFailureCause(details) {
|
|
22
|
+
if (!deploymentRecord(details) || typeof details.reason !== 'string' || !CAUSE_REASON.test(details.reason)) return null;
|
|
23
|
+
const host = causeHost(details.url);
|
|
24
|
+
return host ? { reason: details.reason, host } : { reason: details.reason };
|
|
25
|
+
}
|
|
26
|
+
/** `/api/panel` errorCause, re-validated by the renderer with its keys exact: { code, reason, host? } | null. */
|
|
27
|
+
export function panelErrorCause(value) {
|
|
28
|
+
if (!deploymentRecord(value) || Object.keys(value).some(k => !['code', 'reason', 'host'].includes(k))) return null;
|
|
29
|
+
if (typeof value.code !== 'string' || !/^E_[A-Z0-9_]{1,64}$/.test(value.code) || typeof value.reason !== 'string' || !CAUSE_REASON.test(value.reason)) return null;
|
|
30
|
+
if (value.host !== undefined && (typeof value.host !== 'string' || !CAUSE_HOST.test(value.host))) return null;
|
|
31
|
+
return value.host === undefined ? { code: value.code, reason: value.reason } : { code: value.code, reason: value.reason, host: value.host };
|
|
32
|
+
}
|
|
33
|
+
export function deploymentFailure(code, feature = null) {
|
|
34
|
+
const messages = {
|
|
35
|
+
E_CLI_UNAVAILABLE: 'Choose a compatible installed OATS CLI to observe this deployment.',
|
|
36
|
+
E_DEPLOYMENT_FEATURE: `The installed OATS CLI does not advertise the required feature: ${feature || 'workspace-v2'}.`,
|
|
37
|
+
E_BAD_ARGS: 'Select one registered deployment for this read.',
|
|
38
|
+
E_CLI_FAILED: 'The installed OATS CLI could not read this deployment.',
|
|
39
|
+
E_CLI_PROTOCOL: 'The installed OATS CLI returned an invalid deployment observation.',
|
|
40
|
+
E_CLI_TIMEOUT: 'The deployment observation exceeded its time limit.',
|
|
41
|
+
E_CLI_OUTPUT_LIMIT: 'The deployment observation exceeded its size limit.',
|
|
42
|
+
E_DEPLOYMENT_SCOPE: 'The kernel observation does not match the selected deployment.',
|
|
43
|
+
E_DEPLOYMENT_STALE: 'The deployment or CLI changed while the observation was being read.',
|
|
44
|
+
E_DEPLOYMENT_BUSY: 'A deployment observation is already in progress. Try again.',
|
|
45
|
+
};
|
|
46
|
+
const known = Object.hasOwn(messages, code) ? code : 'E_CLI_FAILED';
|
|
47
|
+
return { ok: false, reason: { code: known, message: messages[known], ...(feature ? { feature } : {}) } };
|
|
48
|
+
}
|
|
49
|
+
/** Probe facts come from version --json, never from the status document.
|
|
50
|
+
* The advertised API integer and feature must both be present. */
|
|
51
|
+
export function deploymentReadGate(cli, action) {
|
|
52
|
+
if (cli?.ok !== true) return deploymentFailure('E_CLI_UNAVAILABLE');
|
|
53
|
+
if (!['status', 'workspace-status'].includes(action)) return deploymentFailure('E_BAD_ARGS');
|
|
54
|
+
if (cli.workspaceApi !== 2) return deploymentFailure('E_DEPLOYMENT_FEATURE', 'workspace-v2');
|
|
55
|
+
const features = Array.isArray(cli.features) ? cli.features : [];
|
|
56
|
+
const required = action === 'status' ? DEPLOYMENT_FEATURES : ['workspace-v2', 'packages-no-approval'];
|
|
57
|
+
for (const name of required) if (!features.includes(name)) return deploymentFailure('E_DEPLOYMENT_FEATURE', name);
|
|
58
|
+
return null;
|
|
59
|
+
}
|
|
60
|
+
/** Bounded observation reuse (kernel feature observe-max-age): the read-only verbs status,
|
|
61
|
+
* workspace status, souls, capabilities and inspect accept `--max-age <seconds>` (0 = live,
|
|
62
|
+
* N = the kernel may reuse remote-head observations up to N seconds old). The flag exists
|
|
63
|
+
* only when the probe declares the feature: an older kernel would refuse it as unknown, so
|
|
64
|
+
* the argv is byte-identical to the flagless one whenever the feature is absent. Mutating
|
|
65
|
+
* verbs never take it; that refusal is each adapter's. Bounded to one day: a larger value
|
|
66
|
+
* has no product meaning and a non-integer would not be one clean argv token. */
|
|
67
|
+
export const OBSERVE_MAX_AGE_FEATURE = 'observe-max-age';
|
|
68
|
+
export const validMaxAge = v => v === undefined || (Number.isSafeInteger(v) && v >= 0 && v <= 86400);
|
|
69
|
+
export function maxAgeArgv(features, maxAge) {
|
|
70
|
+
if (maxAge === undefined || !Array.isArray(features) || !features.includes(OBSERVE_MAX_AGE_FEATURE)) return [];
|
|
71
|
+
return ['--max-age', String(maxAge)];
|
|
72
|
+
}
|