@awebai/oats 0.69.16 → 0.69.18
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 +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +7 -0
- package/docs/container.md +172 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/desktop-cli-api.md +73 -33
- package/docs/desktop.md +40 -18
- package/docs/execution-targets.md +36 -33
- package/docs/implementation.md +7 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +7 -7
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +24 -19
- package/docs/release-notes/v0.69.17.md +49 -0
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/servers.md +3 -1
- package/docs/souls-and-instances.md +18 -16
- package/docs/trust-model.md +119 -0
- package/docs/upgrading.md +46 -21
- package/docs/workspaces.md +3 -3
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +24 -9
- package/lib/errors.mjs +1 -1
- package/lib/home-owner.mjs +25 -0
- package/lib/host-run-admission.mjs +21 -0
- package/lib/host-run-child.mjs +31 -0
- package/lib/host-run-work.mjs +150 -0
- package/lib/host-run.mjs +20 -11
- package/lib/instance-naming.mjs +26 -44
- package/lib/packages.mjs +0 -43
- package/lib/pi-bridge.mjs +18 -6
- package/lib/schedule.mjs +5 -3
- package/lib/servers.mjs +4 -3
- package/lib/session-end.mjs +9 -0
- package/lib/session-resume.mjs +19 -9
- package/lib/session-seen.mjs +13 -8
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +2 -2
- package/packages/client/above-tested-notice.mjs +30 -0
- package/packages/client/above-tested.mjs +225 -0
- package/packages/client/cli-locator.mjs +67 -52
- package/packages/client/deployment-label.mjs +4 -4
- package/packages/client/instance-name.mjs +5 -29
- package/packages/client/session-start.mjs +31 -3
- package/packages/client/workspace-choices.mjs +1 -1
- package/packages/client/workspace-views.mjs +1 -1
- package/packages/record/README.md +10 -8
- package/packages/record/lib/process-identity.mjs +14 -36
- package/packages/tui/lib/read.mjs +19 -3
- package/skills/oats-getting-started/SKILL.md +33 -4
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
/* What a client still does with an oats CLI above its tested bound (oats-project/oats#1879, option 3).
|
|
2
|
+
|
|
3
|
+
The locator accepts a released CLI of a later minor or major than the client's own release and flags it
|
|
4
|
+
`aboveTested` (cli-locator.mjs acceptProbe). This module names every operation that stays on then, each
|
|
5
|
+
with its reason, and DENIES EVERYTHING ELSE: an operation not named here, an operation added later
|
|
6
|
+
included, is held back until the Desktop is updated. A new operation is opened above the bound only by
|
|
7
|
+
adding it here, with a reason (the decision's condition 1).
|
|
8
|
+
|
|
9
|
+
Why these and not others: the four traced cases on #1879 (schedule edit at 0.40, Remove at 0.49 and
|
|
10
|
+
0.53, the Stop outcome at 0.52) all sit where the Desktop words a consequence itself or writes a whole
|
|
11
|
+
definition. What stays on is a read, a terminal, or a change fenced by the kernel's own answer: Spawn
|
|
12
|
+
applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour and
|
|
13
|
+
background report only an answer the Desktop reads in full (each fails closed on a shape it does not
|
|
14
|
+
know).
|
|
15
|
+
|
|
16
|
+
Enforcement is not the renderer's. Every place an operation enters the backend asks
|
|
17
|
+
`aboveTestedRefusal(cli, operation)` before any CLI process starts: each POST handler of
|
|
18
|
+
packages/desktop/server/oats-web.mjs by (route, action), and each caller in main that runs the CLI for
|
|
19
|
+
an effect (packages/desktop/main.mjs, session-resume-launch.mjs). The renderer reads the same table to
|
|
20
|
+
disable what would be refused, and never decides by itself.
|
|
21
|
+
|
|
22
|
+
An operation is a string: `POST <route> <action>` for an HTTP entry whose body names an action (the
|
|
23
|
+
action is the body's `action`, or `<kind>:<action>` for /api/automations), `POST <route>` for one that has
|
|
24
|
+
none, and `main <what>` for an entry outside HTTP. packages/desktop/test/above-tested-inventory.test.mjs
|
|
25
|
+
holds every POST route the server accepts, and every module that executes a command, to a class here.
|
|
26
|
+
|
|
27
|
+
Pure data; no node: imports, so the renderer shares it with the server. */
|
|
28
|
+
import { aboveTestedNotice, desktopReleaseUrl } from './above-tested-notice.mjs';
|
|
29
|
+
|
|
30
|
+
/** The refusal's code: the Desktop's own, never the kernel's. */
|
|
31
|
+
export const ABOVE_TESTED_CODE = 'cli-above-tested';
|
|
32
|
+
|
|
33
|
+
/** The reads that stay on, as a named set: every operation of class `read` is one of them. */
|
|
34
|
+
export const READS = Object.freeze({
|
|
35
|
+
status: 'the deployment observation (`oats status`, `oats workspace status`, the souls and capabilities catalogs)',
|
|
36
|
+
roster: 'the remote roster and the machines list',
|
|
37
|
+
inspect: 'what a soul, an instance or a capability is (`oats inspect`, `oats capabilities show`, the launch configurations)',
|
|
38
|
+
readiness: '`oats readiness`',
|
|
39
|
+
events: "an instance's events",
|
|
40
|
+
git: "an instance's Git state and diffs, and the forge reads beside them (they run gh, never oats)",
|
|
41
|
+
preview: 'the spawn and launch previews',
|
|
42
|
+
version: 'the `version --json` probe itself',
|
|
43
|
+
'warm reader': 'the warm `oats reader --stdio` the background reads go through',
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
const read = (name) => Object.freeze({ class: 'read', reason: READS[name], read: name });
|
|
47
|
+
const allowed = (reason) => Object.freeze({ class: 'allowed', reason });
|
|
48
|
+
const held = (reason) => Object.freeze({ class: 'held', reason });
|
|
49
|
+
|
|
50
|
+
const HELD_WRITE = 'it writes something an older Desktop may word or shape wrongly for a newer kernel';
|
|
51
|
+
|
|
52
|
+
/** Every operation, by its name (see the header for the form). Anything not here is held back. */
|
|
53
|
+
export const OPERATIONS = Object.freeze({
|
|
54
|
+
// ── Spawn: the preview the apply is bound to, and the apply that the kernel fences.
|
|
55
|
+
'POST /api/spawn prepare': allowed('Spawn: prepares the apply from the preview it is bound to'),
|
|
56
|
+
'POST /api/spawn apply': allowed('Spawn: applies only the decision its preview showed (--expect-decision); a drift is E_DECISION_STALE'),
|
|
57
|
+
'POST /api/spawn result': read('preview'),
|
|
58
|
+
'POST /api/spawn execution-server': held('an execution-server spawn is not fenced by --expect-decision'),
|
|
59
|
+
'POST /api/workspace-spawn-preview preview': allowed('Spawn: the preview, a read'),
|
|
60
|
+
'POST /api/workspace-spawn-preview suggest': allowed('Spawn: a suggested task, a read'),
|
|
61
|
+
'POST /api/workspace-spawn-preview suggest-name': allowed('Spawn: a suggested name, a read'),
|
|
62
|
+
// ── Start and Restart: an answer the Desktop reads in full, nothing worded by the Desktop.
|
|
63
|
+
'POST /api/start': allowed('Start: the kernel starts the session and answers what it started'),
|
|
64
|
+
'POST /api/restart': allowed('Restart: the kernel restarts the session and answers what it started'),
|
|
65
|
+
// ── An instance's own record.
|
|
66
|
+
'POST /api/instance-color': allowed("colour: one field of the instance's own record, the answer read in full"),
|
|
67
|
+
'POST /api/instance-background': allowed("background: one field of the instance's own record, the answer read in full"),
|
|
68
|
+
// ── Reads.
|
|
69
|
+
'POST /api/instance-git git': read('git'),
|
|
70
|
+
'POST /api/instance-git diff': read('git'),
|
|
71
|
+
'POST /api/instance-events read': read('events'),
|
|
72
|
+
'POST /api/workspace-readiness read': read('readiness'),
|
|
73
|
+
'POST /api/capabilities inspect': read('inspect'),
|
|
74
|
+
'POST /api/capabilities show': read('inspect'),
|
|
75
|
+
'POST /api/capabilities file': read('inspect'),
|
|
76
|
+
'POST /api/workspace-sync read': read('status'),
|
|
77
|
+
'POST /api/launch-configs list': read('inspect'),
|
|
78
|
+
'POST /api/launch-configs preview': read('preview'),
|
|
79
|
+
'POST /api/workspace-teams list': read('inspect'),
|
|
80
|
+
'POST /api/workspace-soul-teams show': read('inspect'),
|
|
81
|
+
'POST /api/automations trigger:list': read('status'),
|
|
82
|
+
'POST /api/automations trigger:status': read('status'),
|
|
83
|
+
'POST /api/automations schedule:list': read('status'),
|
|
84
|
+
'POST /api/forge-connections': read('git'),
|
|
85
|
+
'POST /api/instance-forge': read('git'),
|
|
86
|
+
'POST /api/forge-roster': read('git'),
|
|
87
|
+
'POST /api/instance-review-threads preview': read('git'),
|
|
88
|
+
'POST /api/models': read('preview'),
|
|
89
|
+
'POST /api/cli/reprobe': read('version'),
|
|
90
|
+
'POST /api/remote-roster/refresh': read('roster'),
|
|
91
|
+
'POST /api/window-state': read('status'),
|
|
92
|
+
'POST /api/windows': read('roster'),
|
|
93
|
+
'main deployments list': read('status'),
|
|
94
|
+
// ── Terminals.
|
|
95
|
+
'POST /api/instance-review-threads send': allowed("terminals: pastes the review threads into the agent's own terminal, as typing there does"),
|
|
96
|
+
'main terminal attach': allowed('terminals: attaches to a session the kernel names'),
|
|
97
|
+
'main terminal viewer': allowed('terminals: a linked, locked viewer of a session'),
|
|
98
|
+
'main terminal upload': allowed("terminals: files attached to the agent's own terminal, as a paste there does"),
|
|
99
|
+
// ── Held back: named so their reason is on record; anything unnamed is held back too.
|
|
100
|
+
'POST /api/instance-lifecycle plan': held('Stop and Remove: the dialog words what the kernel will do (the 0.49, 0.52 and 0.53 cases on #1879)'),
|
|
101
|
+
'POST /api/instance-lifecycle apply': held('Stop and Remove: the dialog words what the kernel will do (the 0.49, 0.52 and 0.53 cases on #1879)'),
|
|
102
|
+
'POST /api/retire': held('Remove'),
|
|
103
|
+
'POST /api/schedules': held('a schedule write replaces a whole definition (the 0.40 case on #1879)'),
|
|
104
|
+
'POST /api/automations schedule:enable': held(HELD_WRITE),
|
|
105
|
+
'POST /api/automations schedule:disable': held(HELD_WRITE),
|
|
106
|
+
'POST /api/automations schedule:test': held('runs the schedule'),
|
|
107
|
+
'POST /api/automations schedule:run': held('runs the schedule'),
|
|
108
|
+
'POST /api/automations schedule:reconcile': held(HELD_WRITE),
|
|
109
|
+
'POST /api/automations schedule:describe': held("writes the schedule's description"),
|
|
110
|
+
'POST /api/automations trigger:enable': held(HELD_WRITE),
|
|
111
|
+
'POST /api/automations trigger:disable': held(HELD_WRITE),
|
|
112
|
+
'POST /api/automations trigger:test': held('runs the trigger'),
|
|
113
|
+
'POST /api/automations trigger:describe': held("writes the trigger's description"),
|
|
114
|
+
'POST /api/workspace-sync sync': held('writes the lock'),
|
|
115
|
+
'POST /api/capabilities run': held('runs a provider operation'),
|
|
116
|
+
'POST /api/workspace-teams add': held(HELD_WRITE),
|
|
117
|
+
'POST /api/workspace-teams remove': held(HELD_WRITE),
|
|
118
|
+
'POST /api/workspace-teams default': held(HELD_WRITE),
|
|
119
|
+
'POST /api/workspace-soul-teams add': held(HELD_WRITE),
|
|
120
|
+
'POST /api/workspace-soul-teams remove': held(HELD_WRITE),
|
|
121
|
+
'POST /api/workspace-soul-teams default': held(HELD_WRITE),
|
|
122
|
+
'POST /api/workspace-soul-teams clear-default': held(HELD_WRITE),
|
|
123
|
+
'POST /api/launch-configs set': held(HELD_WRITE),
|
|
124
|
+
'POST /api/launch-configs remove': held(HELD_WRITE),
|
|
125
|
+
'POST /api/server-connect': held('connects a machine (and messaging) for the workspace'),
|
|
126
|
+
'POST /api/server-check': held('server check'),
|
|
127
|
+
'POST /api/server-remove': held('removes a machine'),
|
|
128
|
+
'POST /api/server-forget': held("forgets a remote row's saved route"),
|
|
129
|
+
'main session-resume': held('the launch sweep starts sessions the Desktop did not ask for'),
|
|
130
|
+
'main deployments add': held("writes this computer's deployments list"),
|
|
131
|
+
'main deployments import': held("writes this computer's deployments list"),
|
|
132
|
+
'main deployments remove': held("writes this computer's deployments list"),
|
|
133
|
+
'main workspace onboard': held('creates a deployment'),
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
/** Every module under packages/client/, packages/desktop/ and packages/desktop/server/ that starts a process,
|
|
137
|
+
* by the class of the most that it runs: a module that can run a held-back operation is `held`, and its
|
|
138
|
+
* reason says where that operation is refused. The inventory test finds such modules by what their code
|
|
139
|
+
* names (child_process, execFile, an injected exec, spawn or probe); an unclassified one fails it. */
|
|
140
|
+
export const CLI_MODULES = Object.freeze({
|
|
141
|
+
'packages/client/cli-adapter.mjs': held('every verb the backend runs; each is refused where it enters, the POST handlers of oats-web.mjs'),
|
|
142
|
+
'packages/client/cli-locator.mjs': read('version'),
|
|
143
|
+
'packages/client/deployment-list-cli.mjs': held("its add, import and remove write this computer's deployments list; refused in main (main deployments …)"),
|
|
144
|
+
'packages/client/deployment-read-cli.mjs': read('status'),
|
|
145
|
+
'packages/client/file-output-exec.mjs': held('the runner of the session resume sweep, refused in session-resume-launch.mjs (main session-resume)'),
|
|
146
|
+
'packages/client/lifecycle-cli.mjs': held('Stop and Remove; refused at POST /api/instance-lifecycle'),
|
|
147
|
+
'packages/client/session-attach.mjs': allowed('terminals: attach'),
|
|
148
|
+
'packages/client/session-resume-cli.mjs': held('the session resume sweep; refused in session-resume-launch.mjs (main session-resume)'),
|
|
149
|
+
'packages/client/spawn-apply-cli.mjs': allowed('Spawn apply, fenced by --expect-decision'),
|
|
150
|
+
'packages/client/spawn-preview-cli.mjs': allowed('Spawn preview, a read'),
|
|
151
|
+
'packages/client/terminal-exec.mjs': allowed('terminals: the run of an attach'),
|
|
152
|
+
'packages/client/tmux-status.mjs': read('status'),
|
|
153
|
+
'packages/client/warm-reader.mjs': read('warm reader'),
|
|
154
|
+
'packages/client/workspace-cli.mjs': held('its sync and onboard write; refused at POST /api/workspace-sync sync and in main (main workspace onboard)'),
|
|
155
|
+
'packages/desktop/forge-cli.mjs': read('git'),
|
|
156
|
+
'packages/desktop/instance-events-cli.mjs': read('events'),
|
|
157
|
+
'packages/desktop/local-tmux-io.mjs': allowed('terminals: the local tmux the viewers run on'),
|
|
158
|
+
'packages/desktop/login-path.mjs': read('version'),
|
|
159
|
+
'packages/desktop/main.mjs': held('runs the deployments list, onboard and the resume sweep; each refused where main calls it'),
|
|
160
|
+
'packages/desktop/readiness-cli.mjs': read('readiness'),
|
|
161
|
+
'packages/desktop/server-host.mjs': allowed("starts the Desktop's own backend server (a node process), not the CLI; the server's CLI runs are classified under packages/desktop/server/oats-web.mjs"),
|
|
162
|
+
'packages/desktop/terminal-attachments.mjs': allowed("terminals: files attached to an agent's terminal (main terminal upload)"),
|
|
163
|
+
'packages/desktop/terminal-io.mjs': allowed('terminals: the terminal broker'),
|
|
164
|
+
'packages/desktop/server/oats-web.mjs': held('the POST handlers, each refused by (route, action) before it runs anything'),
|
|
165
|
+
'packages/desktop/server/review-paste.mjs': allowed("terminals: the paste into the agent's own terminal"),
|
|
166
|
+
});
|
|
167
|
+
|
|
168
|
+
/** The operation's name, as OPERATIONS keys it: `POST <route> <action>`, `POST <route>` when the entry has
|
|
169
|
+
* no action. An action that is not a short printable word names no operation (held back). */
|
|
170
|
+
export function postOperation(route, action) {
|
|
171
|
+
if (action === undefined) return `POST ${route}`;
|
|
172
|
+
return `POST ${route} ${typeof action === 'string' && /^[a-z][a-z:-]{0,63}$/.test(action) ? action : '?'}`;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** The routes OPERATIONS names for a POST. */
|
|
176
|
+
const POST_ROUTES = Object.freeze([...new Set(Object.keys(OPERATIONS).filter((k) => k.startsWith('POST ')).map((k) => k.split(' ')[1]))]);
|
|
177
|
+
const INSTANCE_SEGMENT = /^[A-Za-z0-9._-]+$/;
|
|
178
|
+
|
|
179
|
+
/** Whether a POST to `path` is to a route OPERATIONS names: the route itself, or one instance under it
|
|
180
|
+
* (`<route>/<name>`, as `/api/start/<instance>`). The server asks it of every POST before it dispatches, so a
|
|
181
|
+
* route added without a classification is held back above the bound before its handler runs. */
|
|
182
|
+
export function postRouteClassified(path) {
|
|
183
|
+
return typeof path === 'string' && POST_ROUTES.some((route) => path === route
|
|
184
|
+
|| (path.startsWith(`${route}/`) && INSTANCE_SEGMENT.test(path.slice(route.length + 1))));
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** Whether `operation` stays on above the tested bound: a read, or allowed. False for anything else. */
|
|
188
|
+
export function permittedAboveTested(operation) {
|
|
189
|
+
const entry = Object.hasOwn(OPERATIONS, operation) ? OPERATIONS[operation] : null;
|
|
190
|
+
return entry?.class === 'read' || entry?.class === 'allowed';
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** The notice for an accepted CLI above the tested bound, or null when `cli` is not one: what the card's
|
|
194
|
+
* place shows, and what every refusal carries. */
|
|
195
|
+
export function aboveTestedState(cli) {
|
|
196
|
+
if (cli?.ok !== true || cli.aboveTested !== true || typeof cli.version !== 'string' || typeof cli.testedThrough !== 'string') return null;
|
|
197
|
+
return { message: aboveTestedNotice({ cliVersion: cli.version, testedThrough: cli.testedThrough }), release: desktopReleaseUrl(cli.version), version: cli.version };
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** The one gate: null, or the refusal of `operation` while `cli` is above its tested bound, carrying the
|
|
201
|
+
* notice sentence, the release to install and this module's own code. Called before any CLI process
|
|
202
|
+
* starts. A CLI whose flag is set but whose record is incomplete is refused too: no notice is invented,
|
|
203
|
+
* nothing runs. */
|
|
204
|
+
export function aboveTestedRefusal(cli, operation) {
|
|
205
|
+
if (cli?.aboveTested !== true || permittedAboveTested(operation)) return null;
|
|
206
|
+
const state = aboveTestedState(cli);
|
|
207
|
+
return { code: ABOVE_TESTED_CODE, message: state?.message ?? 'This Desktop is older than the installed oats CLI: install the OATS Desktop of its version.',
|
|
208
|
+
...(state ? { release: state.release } : {}), operation };
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/** The operation each roster act runs (instance-acts.mjs verbs): Stop and Remove open the lifecycle plan,
|
|
212
|
+
* Start and Restart their own route. `inspect` and `open` are reads and terminals, and run none of these. */
|
|
213
|
+
export const ACT_OPERATIONS = Object.freeze({ start: 'POST /api/start', restart: 'POST /api/restart',
|
|
214
|
+
stop: 'POST /api/instance-lifecycle plan', retire: 'POST /api/instance-lifecycle plan' });
|
|
215
|
+
|
|
216
|
+
/** A roster row's acts (instance-acts.mjs `instanceActs`) with each act held back above the tested bound made
|
|
217
|
+
* not enabled, its reason the notice sentence (`{ code, sentence }`, as an act's reason is read). The same
|
|
218
|
+
* answer otherwise. */
|
|
219
|
+
export function heldBackActs(offer, cli) {
|
|
220
|
+
if (cli?.aboveTested !== true || !Array.isArray(offer?.acts)) return offer;
|
|
221
|
+
return { ...offer, acts: offer.acts.map((act) => {
|
|
222
|
+
const refused = Object.hasOwn(ACT_OPERATIONS, act.verb) ? aboveTestedRefusal(cli, ACT_OPERATIONS[act.verb]) : null;
|
|
223
|
+
return refused && act.enabled ? { ...act, enabled: false, reason: { code: refused.code, sentence: refused.message } } : act;
|
|
224
|
+
}) };
|
|
225
|
+
}
|
|
@@ -13,8 +13,11 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver
|
|
17
|
-
//
|
|
16
|
+
// Desktop accepts desktopApi === 1 and a released semver at or above the floor
|
|
17
|
+
// (ACCEPT_RANGE.min). There is no ceiling: a CLI of a later minor than the
|
|
18
|
+
// client's own release (its TESTED BOUND, testedBound below) is accepted and
|
|
19
|
+
// flagged `aboveTested`, and the client then holds back every operation its
|
|
20
|
+
// allowlist does not name (above-tested.mjs, oats-project/oats#1879).
|
|
18
21
|
// API version — not source adjacency — is authoritative.
|
|
19
22
|
//
|
|
20
23
|
// Pure/injected: all process, fs and exec effects come through `io` so the
|
|
@@ -24,39 +27,34 @@ import { delimiter, isAbsolute, join } from "node:path";
|
|
|
24
27
|
import { harnessList } from "./harness-names.mjs";
|
|
25
28
|
|
|
26
29
|
export const DESKTOP_API = 1;
|
|
27
|
-
// The
|
|
28
|
-
//
|
|
29
|
-
//
|
|
30
|
-
//
|
|
31
|
-
//
|
|
32
|
-
//
|
|
33
|
-
//
|
|
34
|
-
//
|
|
35
|
-
//
|
|
36
|
-
//
|
|
37
|
-
//
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 70, 0] };
|
|
56
|
-
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
57
|
-
* rejection reason, the backend's /api status and the degradation card can
|
|
58
|
-
* never disagree with the numbers actually enforced above. */
|
|
59
|
-
export const ACCEPT_RANGE_TEXT = `>=${ACCEPT_RANGE.min.join(".")} <${ACCEPT_RANGE.maxExclusive.join(".")}`;
|
|
30
|
+
// The floor is hand-set: the first kernel the Desktop's feature gates let through (workspace-cli
|
|
31
|
+
// WORKSPACE_FEATURES, deployment-contract DEPLOYMENT_FEATURES); those gates stay the REAL gate.
|
|
32
|
+
//
|
|
33
|
+
// The upper bound is not spelled here, nor anywhere (oats-project/oats#1879, option 3). It is the
|
|
34
|
+
// TESTED BOUND: the minor of the client's own release version, which the caller passes in (the
|
|
35
|
+
// Desktop server its own manifest, packages/desktop/package.json; `oats tui` its kernel's
|
|
36
|
+
// package.json, which is the kernel it runs). Until 0.69.x it was an exclusive ceiling widened by
|
|
37
|
+
// hand at every minor, and every installed Desktop lost every action at each kernel minor until it
|
|
38
|
+
// was reinstalled. Now a CLI of a later minor or major is accepted with `aboveTested: true`, and
|
|
39
|
+
// only the operations above-tested.mjs allows stay on. The version-bump PR moves the bound with the
|
|
40
|
+
// manifests; nothing in release prep moves it by hand.
|
|
41
|
+
export const ACCEPT_RANGE = Object.freeze({ min: Object.freeze([0, 26, 0]) });
|
|
42
|
+
/** [major, minor] of a client's release version: the newest CLI minor it was tested with. A
|
|
43
|
+
* prerelease or build of a release counts as that release (0.70.0-rc.1 tests 0.70). null for a value
|
|
44
|
+
* that is not a version. */
|
|
45
|
+
export function testedBound(releaseVersion) {
|
|
46
|
+
const v = parseSemver(releaseVersion);
|
|
47
|
+
return v ? [v.nums[0], v.nums[1]] : null;
|
|
48
|
+
}
|
|
49
|
+
/** The bound as people read it: "X.Y". */
|
|
50
|
+
export const testedThroughText = (bound) => `${bound[0]}.${bound[1]}`;
|
|
51
|
+
/** The accepted range as humans read it, derived and never hand-spelled, so the probe rejection
|
|
52
|
+
* reason, the backend's /api/cli and the degradation card can never disagree with what is enforced:
|
|
53
|
+
* the floor, then the tested bound of `releaseVersion` (">=0.26.0, tested through 0.69"). */
|
|
54
|
+
export function acceptRangeText(releaseVersion) {
|
|
55
|
+
const bound = testedBound(releaseVersion);
|
|
56
|
+
return `>=${ACCEPT_RANGE.min.join(".")}${bound ? `, tested through ${testedThroughText(bound)}` : ""}`;
|
|
57
|
+
}
|
|
60
58
|
// The npm names of the oats CLI. `version --json` answers the first under either, until a later minor flips it.
|
|
61
59
|
export const PROBE_NAME = Object.freeze(["@awebai/oats", "@oats-project/oats"]);
|
|
62
60
|
// Spawn-time agent relations (--relation/--relative-to) AND the anchor
|
|
@@ -108,24 +106,38 @@ export function parseSemver(v) {
|
|
|
108
106
|
}
|
|
109
107
|
const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
|
|
110
108
|
|
|
111
|
-
/** Accept/reject one probe payload
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
|
|
109
|
+
/** Accept/reject one probe payload against the client's own release version (`testedVersion`,
|
|
110
|
+
* required: see ACCEPT_RANGE). Returns:
|
|
111
|
+
* { ok: true } a CLI of the tested minor or older, down to the floor;
|
|
112
|
+
* { ok: true, aboveTested: true, testedThrough: "X.Y" } a released CLI of a later minor or major;
|
|
113
|
+
* { ok: false, reason } refused, and { ok: false, reason, newerApi: true }
|
|
114
|
+
* when the payload's sole failure is a desktopApi
|
|
115
|
+
* above this client's: the Desktop is the older of the
|
|
116
|
+
* two (views/cli-status.mjs reads the flag, never the
|
|
117
|
+
* reason's words).
|
|
118
|
+
* Without a tested version it refuses: a caller that forgot it never falls back to "no bound". */
|
|
119
|
+
export function acceptProbe(payload, testedVersion) {
|
|
120
|
+
const bound = testedBound(testedVersion);
|
|
121
|
+
if (!bound) return { ok: false, reason: "no tested client version given: the probe is not judged without one" };
|
|
116
122
|
if (!payload || typeof payload !== "object") return { ok: false, reason: "no probe payload" };
|
|
117
123
|
if (payload.schemaVersion !== 1) return { ok: false, reason: `unexpected schemaVersion ${payload.schemaVersion}` };
|
|
118
124
|
if (!PROBE_NAME.includes(payload.name)) return { ok: false, reason: `not the oats CLI (name: ${payload.name || "missing"}, not ${PROBE_NAME.join(" or ")})` };
|
|
119
|
-
if (payload.desktopApi !== DESKTOP_API)
|
|
125
|
+
if (payload.desktopApi !== DESKTOP_API) {
|
|
126
|
+
// Another API, newer than this client's: the client is the older (the card's older-Desktop branch). Only an
|
|
127
|
+
// integer counts; every other check already passed.
|
|
128
|
+
const newer = Number.isSafeInteger(payload.desktopApi) && payload.desktopApi > DESKTOP_API;
|
|
129
|
+
return { ok: false, reason: `desktopApi ${payload.desktopApi ?? "missing"} (need ${DESKTOP_API})`, ...(newer ? { newerApi: true } : {}) };
|
|
130
|
+
}
|
|
120
131
|
const v = parseSemver(payload.version);
|
|
121
132
|
if (!v) return { ok: false, reason: `unparsable version "${payload.version}"` };
|
|
133
|
+
const range = acceptRangeText(testedVersion);
|
|
122
134
|
// Prerelease policy: prereleases are NOT accepted. Precedence-wise
|
|
123
135
|
// 0.18.0-rc.1 < 0.18.0 (below the minimum), and a prerelease of any
|
|
124
|
-
//
|
|
125
|
-
//
|
|
126
|
-
if (v.prerelease) return { ok: false, reason: `prerelease version ${payload.version} not accepted (need a released ${
|
|
127
|
-
if (cmp(v.nums, ACCEPT_RANGE.
|
|
128
|
-
if (
|
|
136
|
+
// version is not a released CLI — Desktop pairs with released kernels only,
|
|
137
|
+
// above its tested bound as below it.
|
|
138
|
+
if (v.prerelease) return { ok: false, reason: `prerelease version ${payload.version} not accepted (need a released ${range})` };
|
|
139
|
+
if (cmp(v.nums, ACCEPT_RANGE.min) < 0) return { ok: false, reason: `version ${payload.version} outside ${range}` };
|
|
140
|
+
if (v.nums[0] > bound[0] || (v.nums[0] === bound[0] && v.nums[1] > bound[1])) return { ok: true, aboveTested: true, testedThrough: testedThroughText(bound) };
|
|
129
141
|
return { ok: true };
|
|
130
142
|
}
|
|
131
143
|
|
|
@@ -212,11 +224,14 @@ export function cliRecord(payload, { bin, source }) {
|
|
|
212
224
|
* looks valid (review 53a20c7: a binary that prints a plausible probe and
|
|
213
225
|
* then fails/hangs must never become the mutation binary). Sources are
|
|
214
226
|
* evaluated lazily: expensive helpers never run once a candidate wins.
|
|
227
|
+
* `io.testedVersion` is the client's own release version (acceptProbe): required, and without it
|
|
228
|
+
* every candidate is refused.
|
|
215
229
|
* Returns:
|
|
216
|
-
* { ok:true, bin, source, version }
|
|
230
|
+
* { ok:true, bin, source, version, aboveTested?, testedThrough? } — the cliRecord, flagged when the
|
|
231
|
+
* CLI is of a later minor than the tested bound
|
|
217
232
|
* { ok:false, tried: [{path, source, reason}] } — stable diagnostics; an entry whose probe was
|
|
218
|
-
* refused only for
|
|
219
|
-
* `version` and `
|
|
233
|
+
* refused only for a newer desktopApi also has
|
|
234
|
+
* `version` and `newerApi: true` (acceptProbe)
|
|
220
235
|
*/
|
|
221
236
|
export async function discover(io, probe) {
|
|
222
237
|
const tried = [];
|
|
@@ -241,9 +256,9 @@ export async function discover(io, probe) {
|
|
|
241
256
|
tried.push({ path, source: src.source, reason: `probe failed: ${String(e.message || e).slice(0, 120)}` });
|
|
242
257
|
continue;
|
|
243
258
|
}
|
|
244
|
-
const a = acceptProbe(payload);
|
|
245
|
-
if (a.ok) return cliRecord(payload, { bin: path, source: src.source });
|
|
246
|
-
tried.push({ path, source: src.source, reason: a.reason, version: payload?.version, ...(a.
|
|
259
|
+
const a = acceptProbe(payload, io.testedVersion);
|
|
260
|
+
if (a.ok) return { ...cliRecord(payload, { bin: path, source: src.source }), ...(a.aboveTested === true ? { aboveTested: true, testedThrough: a.testedThrough } : {}) };
|
|
261
|
+
tried.push({ path, source: src.source, reason: a.reason, version: payload?.version, ...(a.newerApi === true ? { newerApi: true } : {}) });
|
|
247
262
|
}
|
|
248
263
|
}
|
|
249
264
|
return { ok: false, tried };
|
|
@@ -32,21 +32,21 @@ export function deploymentLabelParts(deployment, terms) {
|
|
|
32
32
|
return { machine, path };
|
|
33
33
|
}
|
|
34
34
|
|
|
35
|
-
/** `This Mac · ~/acme`, `
|
|
35
|
+
/** `This Mac · ~/acme`, `builder · ~/northwind`. */
|
|
36
36
|
export function deploymentLabel(deployment, terms) {
|
|
37
37
|
requireTerms(terms, 'deploymentLabel');
|
|
38
38
|
const { machine, path } = deploymentLabelParts(deployment, terms);
|
|
39
39
|
return path ? `${machine} · ${path}` : machine;
|
|
40
40
|
}
|
|
41
41
|
|
|
42
|
-
/** The last segment of a path ("/Users/
|
|
42
|
+
/** The last segment of a path ("/Users/alex/work/acme" → "acme"), or the last `n`. */
|
|
43
43
|
export function pathTail(path, n = 1) {
|
|
44
44
|
if (typeof path !== 'string' || !path) return '';
|
|
45
45
|
return path.split('/').filter(Boolean).slice(-n).join('/');
|
|
46
46
|
}
|
|
47
47
|
|
|
48
|
-
/** Each deployment's short name on screen (UI spec, #482): its machine ("This Mac", "
|
|
49
|
-
* machine holds two or more of the deployments, the machine and its path tail ("This Mac ·
|
|
48
|
+
/** Each deployment's short name on screen (UI spec, #482): its machine ("This Mac", "builder"); when one
|
|
49
|
+
* machine holds two or more of the deployments, the machine and its path tail ("This Mac · acme"),
|
|
50
50
|
* the last two segments when the tails collide. Never an id. Returns Map<deployment id, label>. */
|
|
51
51
|
export function machineLabels(deployments, terms) {
|
|
52
52
|
requireTerms(terms, 'machineLabels');
|
|
@@ -1,18 +1,11 @@
|
|
|
1
|
-
/** The instance-name rules of the clients. A typed name
|
|
2
|
-
*
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
* A soul's role is the last word of its name: `oats-desktop-expert` → `expert`, `code-reviewer` → `reviewer`,
|
|
6
|
-
* `cloner` → `cloner`. A package qualifier is dropped first (what follows the last `/` or `--`, as the
|
|
7
|
-
* identity marks read a name: renderer/identity-marks.mjs markText), so `acme-pkg--keeper` → `keeper`.
|
|
8
|
-
* A typed name gets the role once: `desktop-improvements` → `desktop-improvements-expert`, while
|
|
9
|
-
* `desktop-improvements-expert` and `expert` stay as typed; the kernel refuses a typed name that breaks its
|
|
10
|
-
* grammar (E_INSTANCE_NAME_INVALID).
|
|
1
|
+
/** The instance-name rules of the clients. A typed name goes to `oats spawn --name` as typed, lowercased: nothing
|
|
2
|
+
* is appended to it (the soul is shown beside the name). What to name an instance, `<descriptive>-<role>`, is
|
|
3
|
+
* oats.core's rule (oats-souls "Name the instance"), never this module's.
|
|
11
4
|
*
|
|
12
5
|
* The grammar itself, the kernel's `--name` check (explicitInstanceName: a slug of at most MAX_INSTANCE_NAME
|
|
13
6
|
* characters), is mirrored here for a client that must judge a name with no kernel call (the
|
|
14
|
-
* Desktop's `--instance` launch argument, a spawn's suggested name);
|
|
15
|
-
* check over the same cases.
|
|
7
|
+
* Desktop's `--instance` launch argument, a spawn's suggested name); test/client-instance-name.test.mjs drives
|
|
8
|
+
* the kernel's own check over the same cases.
|
|
16
9
|
* DOM-free and import-free, with no module state. */
|
|
17
10
|
|
|
18
11
|
/** The kernel's longest instance name (its MAX_INSTANCE_NAME). */
|
|
@@ -24,20 +17,3 @@ const INSTANCE_NAME = new RegExp(`^(?=.{1,${INSTANCE_NAME_MAX}}$)[a-z0-9]+(?:-[a
|
|
|
24
17
|
export function validInstanceName(name) {
|
|
25
18
|
return typeof name === 'string' && INSTANCE_NAME.test(name);
|
|
26
19
|
}
|
|
27
|
-
|
|
28
|
-
/** The role of a soul name: its last `-`-separated word after any package qualifier; '' when there is none. */
|
|
29
|
-
export function soulRole(soulName) {
|
|
30
|
-
if (typeof soulName !== 'string') return '';
|
|
31
|
-
const slash = soulName.lastIndexOf('/'), dashes = soulName.lastIndexOf('--');
|
|
32
|
-
const bare = soulName.slice(Math.max(slash < 0 ? 0 : slash + 1, dashes < 0 ? 0 : dashes + 2));
|
|
33
|
-
return bare.slice(bare.lastIndexOf('-') + 1);
|
|
34
|
-
}
|
|
35
|
-
|
|
36
|
-
/** `name` with the role of `soulName` as its suffix, unless it already ends in `-<role>` or is the role itself;
|
|
37
|
-
* the name as given when the soul has no role, and '' for no name (the kernel numbers it). */
|
|
38
|
-
export function nameWithRole(name, soulName) {
|
|
39
|
-
if (typeof name !== 'string' || !name) return '';
|
|
40
|
-
const role = soulRole(soulName);
|
|
41
|
-
if (!role || name === role || name.endsWith(`-${role}`)) return name;
|
|
42
|
-
return `${name}-${role}`;
|
|
43
|
-
}
|
|
@@ -86,6 +86,27 @@ export function verifiedLocalHome(row, deployments, realpath) {
|
|
|
86
86
|
return null;
|
|
87
87
|
}
|
|
88
88
|
|
|
89
|
+
/** How a start came by its session, as the kernel's receipt says (`reused`): a new window, a retained pane, or the
|
|
90
|
+
* adopted launch of an earlier start whose record was not written. */
|
|
91
|
+
const START_REUSED = Object.freeze(['new', 'pane', 'adopted']);
|
|
92
|
+
|
|
93
|
+
/** Whether `v` is the receipt of a completed start or restart of `row`, as the kernel answers one
|
|
94
|
+
* (docs/desktop-cli-api.md, `oats session start`: `{instance, agent, home, harness, backend, model, launchConfig,
|
|
95
|
+
* yolo, target, startedAt, restartCount, reused, warnings}`): the row's instance, in the row's home (the kernel
|
|
96
|
+
* answers with its real path: `canonical`, the verified local home), on the one backend there is, tmux, with its
|
|
97
|
+
* target (`{backend, session, window, socket}`, more keys allowed) and the other fields a start always carries.
|
|
98
|
+
* Read where the CLI is newer than this client was tested with, so a format it does not know is not taken for one. */
|
|
99
|
+
function startReceipt(v, row, canonical) {
|
|
100
|
+
const record = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
|
|
101
|
+
const text = (x) => typeof x === 'string' && x.length > 0;
|
|
102
|
+
return record(v) && v.instance === row.instance && text(v.home) && (v.home === row.home || (canonical !== null && v.home === canonical))
|
|
103
|
+
&& text(v.agent) && text(v.harness) && v.backend === 'tmux' && text(v.startedAt)
|
|
104
|
+
&& record(v.target) && v.target.backend === 'tmux' && text(v.target.session) && text(v.target.window)
|
|
105
|
+
&& text(v.target.socket) && v.target.socket.startsWith('/')
|
|
106
|
+
&& Number.isSafeInteger(v.restartCount) && v.restartCount >= 0 && START_REUSED.includes(v.reused)
|
|
107
|
+
&& Array.isArray(v.warnings) && v.warnings.every((w) => typeof w === 'string');
|
|
108
|
+
}
|
|
109
|
+
|
|
89
110
|
/** Start or restart one row.
|
|
90
111
|
* choices { model, launchConfig, harness, yolo }: the launch choices, each one argv value
|
|
91
112
|
* restart a restart (the kernel's one call, never a stop then a start)
|
|
@@ -109,8 +130,8 @@ export async function startInstance(cli, row, choices = {}, { restart = false, d
|
|
|
109
130
|
const gate = startGate(cli, row, { restart, choices }, terms);
|
|
110
131
|
if (gate) return refused(gate.code, gate.sentence, gate.detail ? { detail: gate.detail } : {});
|
|
111
132
|
const local = !row.server;
|
|
112
|
-
|
|
113
|
-
|
|
133
|
+
const canonical = local ? (verifyHome ? verifyHome(row) : verifiedLocalHome(row, deployments, realpath)) : null;
|
|
134
|
+
if (local && !canonical) return refused('E_HOME_UNVERIFIED', 'Instance home is outside the workspace instances layout');
|
|
114
135
|
let envelope;
|
|
115
136
|
// A call that could not be made, or failed on its way (an exec that throws, a rejected call), is uncertain like
|
|
116
137
|
// any answer this cannot read: the CLI may have begun the start. Its words are the rule's; the exception's text
|
|
@@ -119,7 +140,14 @@ export async function startInstance(cli, row, choices = {}, { restart = false, d
|
|
|
119
140
|
harnessFlag: harnessFlag(cli), yolo: choices.yolo, restart, workspaceDir: local ? dirname(row.agentsRoot) : localCwd, server: row.server },
|
|
120
141
|
{ ...(exec ? { exec } : {}), ...(after ? { after } : {}), ...(wait !== undefined ? { wait } : {}) }); }
|
|
121
142
|
catch { return { ok: false, outcome: 'uncertain', code: 'E_CLI_FAILED', sentence: CLI_FAILED, detail: null, ran: true }; }
|
|
122
|
-
if (envelope?.ok === true)
|
|
143
|
+
if (envelope?.ok === true) {
|
|
144
|
+
// Above the client's tested bound (#1879, cli-locator.mjs aboveTested) a start is reported started only on the
|
|
145
|
+
// receipt it knows (startReceipt): any other answer is an outcome not known, never a start, and nothing more
|
|
146
|
+
// is run. Within the bound the answer is taken as before.
|
|
147
|
+
if (cli?.aboveTested === true && !startReceipt(envelope.result, row, canonical))
|
|
148
|
+
return { ok: false, outcome: 'uncertain', code: 'E_CLI_PROTOCOL', sentence: null, detail: null, ran: true };
|
|
149
|
+
return { ok: true, result: envelope.result };
|
|
150
|
+
}
|
|
123
151
|
const code = typeof envelope?.error?.code === 'string' ? envelope.error.code : 'E_CLI_PROTOCOL';
|
|
124
152
|
const detail = displayLine(envelope?.error?.message);
|
|
125
153
|
if (CLAIM_STARTED_NOTHING_CODES.includes(code)) {
|
|
@@ -15,7 +15,7 @@ const short = (value, max = 256) => typeof value === "string" && value.length >
|
|
|
15
15
|
|
|
16
16
|
const machinesOf = (choice) => Array.isArray(choice?.machines) ? choice.machines.filter((m) => short(m)) : [];
|
|
17
17
|
|
|
18
|
-
/** The machines a choice's deployments are on, as one line (UI spec, #482): "This Mac ·
|
|
18
|
+
/** The machines a choice's deployments are on, as one line (UI spec, #482): "This Mac · builder", from
|
|
19
19
|
* the server's `machines`. Never a path or an id: without `machines` (an older server), nothing. */
|
|
20
20
|
export function workspaceChoicePlace(choice) {
|
|
21
21
|
return machinesOf(choice).join(" · ");
|
|
@@ -145,7 +145,7 @@ export function deploymentReason(d, terms) {
|
|
|
145
145
|
return deploymentReasonParts(d, terms)?.detail ?? null;
|
|
146
146
|
}
|
|
147
147
|
|
|
148
|
-
/** The last segment of a canonical key: github.com/
|
|
148
|
+
/** The last segment of a canonical key: github.com/example/app → app. */
|
|
149
149
|
const keyTail = key => String(key).split('/').filter(Boolean).pop() || String(key);
|
|
150
150
|
|
|
151
151
|
/** Build the views from the served deployments, in their served order (locals first, as given).
|
|
@@ -203,7 +203,7 @@ enter the record.
|
|
|
203
203
|
7fe2a1b4-9c3d-4e21-b0aa-1f2e3d4c5b6a
|
|
204
204
|
|
|
205
205
|
# never capture anything from this project's transcripts
|
|
206
|
-
**/-Users-
|
|
206
|
+
**/-Users-alex-private-project/**
|
|
207
207
|
|
|
208
208
|
# never capture one aw account's comm log
|
|
209
209
|
acme-secret
|
|
@@ -283,9 +283,12 @@ guarantees rest on that token:
|
|
|
283
283
|
provably stale and is reclaimed at once, without waiting out any threshold.
|
|
284
284
|
A holder is gone when its pid is gone, when its pid runs with another start
|
|
285
285
|
than the recorded one (the pid went to another process), or when the lock
|
|
286
|
-
was taken in another boot.
|
|
287
|
-
|
|
288
|
-
|
|
286
|
+
was taken in another kernel boot. Containers and PID sandboxes use the same
|
|
287
|
+
Linux kernel UUID; a container restart reclaims a lock when its recorded
|
|
288
|
+
pid is gone or has another start time. Old qualified Linux UUIDs compare as
|
|
289
|
+
their base UUID, so an upgrade does not reclaim a visible live holder.
|
|
290
|
+
Holder liveness assumes the reader can see the recorded pid in its PID
|
|
291
|
+
namespace; a shared boot string does not translate pids across namespaces. The
|
|
289
292
|
kernel judges its own claims by the same rule, with the same code
|
|
290
293
|
(`lib/process-identity.mjs`).
|
|
291
294
|
|
|
@@ -353,10 +356,9 @@ its registered worker too:
|
|
|
353
356
|
|
|
354
357
|
- An owner, a worker or a reclaimer is dead when its pid is gone, when its
|
|
355
358
|
pid runs with another start than the recorded one (the pid went to
|
|
356
|
-
another process), or when its record was taken in another boot.
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
hostname and whichever process holds the pid there. The host a record
|
|
359
|
+
another process), or when its record was taken in another kernel boot.
|
|
360
|
+
Container restarts use pid and process start on that same kernel; old
|
|
361
|
+
qualified UUIDs are compared as their base UUID. The host a record
|
|
360
362
|
names does not enter this judgement. One whose start cannot be read is
|
|
361
363
|
unknowable, and never dead.
|
|
362
364
|
- A record that names neither boot nor start, as an earlier version writes
|