@wezzard/mcp-relay 0.14.2 → 0.16.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/.claude-plugin/plugin.json +1 -1
- package/README.md +66 -48
- package/agents/vm-relay-operator.md +7 -7
- package/dist/build-info.json +13 -13
- package/dist/doctor.mjs +43 -35
- package/dist/integrity.json +3 -3
- package/dist/receiver.mjs +31 -33
- package/dist/server.mjs +135 -143
- package/package.json +1 -1
- package/pi-mcp.json +1 -1
package/README.md
CHANGED
|
@@ -4,10 +4,10 @@ The Model Context Protocol front end of the VM relay, packaged as a Claude Code
|
|
|
4
4
|
plugin and as a pi package. [pi-vm-relay](https://github.com/WeZZard/pi-vm-relay),
|
|
5
5
|
which gave pi a native `relay` tool directly, is retired; mcp-relay replaces
|
|
6
6
|
it for both Claude Code and pi, the latter loaded through `pi-mcp-adapter`. It
|
|
7
|
-
is an MCP server:
|
|
7
|
+
is an MCP server: fourteen `relay_*` tools, each with its own schema, title
|
|
8
8
|
and annotations, and the server's `instructions`. The user command, status,
|
|
9
9
|
ships as one small command file per host (see "Commands"). There is no skill and no hook. Together they offer recorded,
|
|
10
|
-
snapshot-evidenced commands
|
|
10
|
+
snapshot-evidenced scripts, commands included as shell scripts, in a fresh, dedicated VM, for any work
|
|
11
11
|
the agent chooses to run there; a script drives the desktop or a browser
|
|
12
12
|
through the software the image lists, such as cua-driver or Playwright. Nothing here executes local computer-use, spawns
|
|
13
13
|
subagents, targets physical machines, records video, or attaches to existing
|
|
@@ -19,10 +19,19 @@ The project was named mcp-vm-relay before v0.12.0. The npm package is now
|
|
|
19
19
|
default state directory moved with the name, so finish or release a lease the
|
|
20
20
|
old relay owns before upgrading.
|
|
21
21
|
|
|
22
|
+
From v0.16.0 the relay's backend is machine-service, vm-service under its new
|
|
23
|
+
name. The relay asks for `/machines` paths, which vm-service never served, and
|
|
24
|
+
refuses a service whose `/health` does not answer `machine-service`. A selected
|
|
25
|
+
environment profile must be at `schemaVersion` 2 with `machctlPath`; a profile
|
|
26
|
+
at version 1 or with `vmctlPath` is refused with its fix in the error (DC-27).
|
|
27
|
+
The relay's own names do not change: `MCP_RELAY_*`, `VM_ENVIRONMENT_FILE`,
|
|
28
|
+
`VM_RELAY_*` and the state directories. Release every lease before switching,
|
|
29
|
+
as machine-service's installer requires.
|
|
30
|
+
|
|
22
31
|
## How it is built
|
|
23
32
|
|
|
24
33
|
The relay implementation lives in this repository: the manager
|
|
25
|
-
(`src/manager.ts`), the
|
|
34
|
+
(`src/manager.ts`), the machine-service client, the registry with its OS-level lock,
|
|
26
35
|
the guest transfer and transport, the evidence package and its state merge, the
|
|
27
36
|
selected-environment profile, the console and saved-image contracts, the strict
|
|
28
37
|
tool contract (`src/schema.ts`), the action dispatch and bounded result
|
|
@@ -48,12 +57,12 @@ adds nothing Claude-Code-specific beyond the marketplace packaging and the
|
|
|
48
57
|
|
|
49
58
|
| In pi-vm-relay (retired, native pi extension) | Here (MCP server) |
|
|
50
59
|
|---|---|
|
|
51
|
-
| a registered `relay` tool with thirteen actions |
|
|
60
|
+
| a registered `relay` tool with thirteen actions | fourteen `relay_*` MCP tools from the server `relay`, each with its own schema, title and annotations |
|
|
52
61
|
| doctrine injected before each agent turn | the server's MCP `instructions`, plus a compact version in the `relay_probe` and `relay_acquire` descriptions for clients that do not surface `instructions` |
|
|
53
62
|
| `/relay-status` command | `/mcp-relay-status` in pi, `/mcp-relay:status` in Claude Code; it asks the assistant to call `relay_status` |
|
|
54
63
|
| prompt-composed guest operator | the `vm-relay-operator` agent definition (Claude Code only), limited to the relay's tools and read-only file tools |
|
|
55
64
|
| typed image blocks in a run result, with pi's `tool_result` hook keeping the error flag | MCP image content blocks in the tool result, with the MCP `isError` flag set beside them |
|
|
56
|
-
| session shutdown pauses lease renewal | the same when the server's stdio closes or it is signalled: renewal pauses after one final renewal for the rest of the lease's TTL, the recording detaches, the VM is retained until that TTL for an explicit `relay_finish` or `relay_release`, and the
|
|
65
|
+
| session shutdown pauses lease renewal | the same when the server's stdio closes or it is signalled: renewal pauses after one final renewal for the rest of the lease's TTL, the recording detaches, the VM is retained until that TTL for an explicit `relay_finish` or `relay_release`, and the machine-service TTL is the backstop |
|
|
57
66
|
| the settled agent pauses renewal | none: MCP has no such hook, so the instructions and each run tool's description say "finish or release before you return" |
|
|
58
67
|
|
|
59
68
|
## Install
|
|
@@ -73,7 +82,7 @@ Or add this repository as a marketplace and install the plugin from it:
|
|
|
73
82
|
/plugin install mcp-relay@mcp-relay
|
|
74
83
|
```
|
|
75
84
|
|
|
76
|
-
Once loaded, the model sees the
|
|
85
|
+
Once loaded, the model sees the fourteen tools as
|
|
77
86
|
`mcp__plugin_mcp-relay_relay__relay_search`,
|
|
78
87
|
`mcp__plugin_mcp-relay_relay__relay_probe`, and so on through
|
|
79
88
|
`mcp__plugin_mcp-relay_relay__relay_status` (see "The tools" below for
|
|
@@ -106,7 +115,7 @@ without a Claude Code plugin or pi package wrapper.
|
|
|
106
115
|
|
|
107
116
|
Node 22+, Python 3 with `fcntl` for the registry lock, and for VM execution an
|
|
108
117
|
Apple-silicon Mac with Tart, a running
|
|
109
|
-
[
|
|
118
|
+
[machine-service](https://github.com/WeZZard/vm-service) (formerly vm-service) and prepared guest images.
|
|
110
119
|
Check readiness with `node dist/doctor.mjs`. It does not acquire a VM or
|
|
111
120
|
establish guest UI readiness. Staging and runs assume no software in the guest
|
|
112
121
|
but Node.js, which runs the relay's own guest code; `relay_stage` refuses an
|
|
@@ -117,7 +126,7 @@ gap. Snapshots need cua-driver with capture permission; on Linux, native X11
|
|
|
117
126
|
and `serve --no-overlay`. `relay_script` runs JavaScript with the guest's
|
|
118
127
|
Node.js, TypeScript with `tsx` and Python with `python3`, each from the guest's
|
|
119
128
|
`PATH`; the relay installs none of them, nor the software a script drives, such
|
|
120
|
-
as cua-driver, Playwright or a browser. Console viewing needs the
|
|
129
|
+
as cua-driver, Playwright or a browser. Console viewing needs the machine-service guest-sharing backend and its
|
|
121
130
|
guest preparation; see `docs/console.md` here.
|
|
122
131
|
|
|
123
132
|
## The tools
|
|
@@ -128,20 +137,20 @@ and no `action` field, derived directly from the strict per-action contract in
|
|
|
128
137
|
`target`, are unaffected). A call is mapped back to that contract's shape and
|
|
129
138
|
dispatched exactly as the retired single `relay` tool was, so behaviour,
|
|
130
139
|
results, image blocks and `isError` semantics are unchanged from before this
|
|
131
|
-
split.
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
`timeoutMs
|
|
140
|
+
split. One tool runs anything in a guest: `relay_script` runs a shell,
|
|
141
|
+
JavaScript, TypeScript or Python script, given inline or as a project file. A
|
|
142
|
+
command is a shell script. It takes the optional `reason`, `step`, `snapshots`,
|
|
143
|
+
`timeoutMs` and, for a shell script, `diagnostic`, and its evidence is
|
|
144
|
+
automatic: see "Runs" below.
|
|
135
145
|
|
|
136
|
-
| Tool | Title | Replaces (`action
|
|
146
|
+
| Tool | Title | Replaces (`action`) | Purpose |
|
|
137
147
|
|---|---|---|---|
|
|
138
148
|
| `relay_search` | Search installed applications | `search` | Find installed applications from image inventories by name and optional OS. |
|
|
139
|
-
| `relay_probe` | Probe host and guest readiness | `probe` | Default `scope: "host"` reports host facts, service availability and every guest the session holds, with its state. `scope: "guest"` with `guest` checks Node.js, which staging requires, and reports as facts whether each `relay_script` language's runtime runs (`node`, `tsx`, `python3`), the software the image lists in the catalog and whether runs take snapshots, on that guest, without installing, starting or claiming capture readiness. |
|
|
149
|
+
| `relay_probe` | Probe host and guest readiness | `probe` | Default `scope: "host"` reports host facts, service availability and every guest the session holds, with its state. `scope: "guest"` with `guest` checks Node.js, which staging requires, and reports as facts whether each `relay_script` language's runtime runs (`/bin/sh`, `node`, `tsx`, `python3`), the software the image lists in the catalog and whether runs take snapshots, on that guest, without installing, starting or claiming capture readiness. |
|
|
140
150
|
| `relay_acquisition_capabilities` | Read acquisition capabilities | `acquisition-capabilities` | Read versioned acquisition options (VNC backends) without allocation or ownership recovery. |
|
|
141
151
|
| `relay_acquire` | Acquire a VM | `acquire` | Register the task, acquire a fresh VM, a guest, on the network `MCP_RELAY_GUEST_NETWORK` names and start its heartbeat; declare outputs before work. Answers `guest`, the guest's name in the session, which every later call on it names. Optional `vnc` prepares sharing without opening a viewer. |
|
|
142
152
|
| `relay_stage` | Stage the guest runtime | `stage` | Push and hash-check the runtime, support files and an opt-in workspace, all from the project folder. Needs only Node.js in the guest, and reports whether runs take snapshots (only when the image lists cua-driver). Failed staging can be retried; a staged runtime accepts corrected executable paths; `resetRecording: true` archives the recording and starts a new one on the same VM. |
|
|
143
|
-
| `
|
|
144
|
-
| `relay_script` | Run a guest script | `run`, `script` | One recorded guest script in `language` (`javascript`, `typescript` or `python`). `inline: true` takes the script as `code`, up to 1 MiB (was `relay_code`); `inline: false` takes `localPath`, a file in the project folder (was `relay_script`). |
|
|
153
|
+
| `relay_script` | Run a guest script | `run` | One recorded guest script in `language` (`shell`, `javascript`, `typescript` or `python`); a command is a shell script. `inline: true` takes the script as `code`, up to 1 MiB; `inline: false` takes `localPath`, a file in the project folder. `diagnostic: true`, for a shell script only, records diagnosis or repair without screenshot evidence, including before staging. |
|
|
145
154
|
| `relay_image` | Retrieve a saved image | `image` | Retrieve one saved display image, declared application image or immutable image reference without input, capture, directory export or acquisition. |
|
|
146
155
|
| `relay_extract` | Extract declared outputs | `extract` | Pull only declared files or directories with source and host checksum verification. |
|
|
147
156
|
| `relay_finish` | Finish and deliver evidence | `finish` | Extract the guest's declared outputs, deliver and verify its snapshot package, destroy its VM and unregister it; the session's other guests keep running. |
|
|
@@ -149,24 +158,26 @@ as a project file. Both take the optional `reason`, `step`, `snapshots` and
|
|
|
149
158
|
| `relay_console_resolve` | Resolve console status | `console-resolve` | Resolve non-secret console status for the guest's lease and environment. |
|
|
150
159
|
| `relay_console_open` | Open console viewing | `console-open` | Open explicitly user-requested viewing on the service host, with `console_id`, `attempt_id`, `userRequested: true`, `reason` and `expected`. |
|
|
151
160
|
| `relay_console_cancel` | Cancel console viewing | `console-cancel` | Cancel the identified viewing attempt without releasing the VM. |
|
|
152
|
-
| `relay_status` | Show relay status | (unchanged) | Every guest this session holds, by name, each with its lease: backend binding, guest state, renewal state, console observation, last error, staging state and evidence path; plus `maxGuests`, the project directory, the
|
|
161
|
+
| `relay_status` | Show relay status | (unchanged) | Every guest this session holds, by name, each with its lease: backend binding, guest state, renewal state, console observation, last error, staging state and evidence path; plus `maxGuests`, the project directory, the machine-service origin and the selected environment. `active` is false when no guest's lease is being renewed. |
|
|
153
162
|
|
|
154
163
|
`readOnlyHint`/`idempotentHint` are true for `relay_search`, `relay_probe`,
|
|
155
164
|
`relay_acquisition_capabilities`, `relay_console_resolve`, `relay_image` and
|
|
156
165
|
`relay_status`; `destructiveHint` is true only for `relay_finish` and
|
|
157
|
-
`relay_release`, which destroy a guest's VM; `openWorldHint` is true only for
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
`relay_exec`, `relay_code`, `relay_run`, `relay_gate` and
|
|
161
|
-
gone (DC-23, `docs/guest-code-runs.md` §10).
|
|
162
|
-
|
|
166
|
+
`relay_release`, which destroy a guest's VM; `openWorldHint` is true only for
|
|
167
|
+
`relay_script`, whose guest code may reach the network.
|
|
168
|
+
|
|
169
|
+
`relay_command`, `relay_exec`, `relay_code`, `relay_run`, `relay_gate` and
|
|
170
|
+
`relay_tools` are gone (DC-23, DC-26, `docs/guest-code-runs.md` §10). A
|
|
171
|
+
command is a shell script: `{"argv":["ls","-al"]}` becomes
|
|
172
|
+
`{"language":"shell","inline":true,"code":"ls -al"}`. `relay_code` is
|
|
173
|
+
`relay_script` with `inline: true`. A run carries no kind. In place of
|
|
163
174
|
`relay_run`'s forwarded MCP tool calls, a script drives cua-driver, Playwright
|
|
164
175
|
or Chrome DevTools through their own libraries or command lines, as the image
|
|
165
176
|
lists them; the relay no longer stages MCP servers in the guest.
|
|
166
177
|
|
|
167
178
|
A run's result carries the execution identity and outcome, the derived step
|
|
168
179
|
record, and, when the snapshot plan captured the after phase and delivery
|
|
169
|
-
succeeded, the saved after-image as an MCP image content block. A
|
|
180
|
+
succeeded, the saved after-image as an MCP image content block. A run's
|
|
170
181
|
result also carries the guest's bounded standard output and error. The full
|
|
171
182
|
receipt stays in the evidence package.
|
|
172
183
|
|
|
@@ -196,19 +207,19 @@ tarball it checked.
|
|
|
196
207
|
- An operation failure retains the VM so the agent can inspect, repair and submit a new operation. Failed and uncertain operations are never automatically replayed.
|
|
197
208
|
- Use `finish` to deliver evidence and release, or `release` to abandon explicitly. A declared output that was never produced is recorded as incomplete (`incompleteExtractions`) rather than failing `finish`. A failed delivery retains the VM; a release failure retains ownership until destruction is verified.
|
|
198
209
|
- When the session ends (the client closes the server's standard input, a write to its standard output fails, it is signalled with SIGTERM, SIGINT or SIGHUP, or the process that started it goes away), `MCP_RELAY_ON_EXIT` says what happens to the guests. With `release`, the relay releases every guest the session holds through its own release path, keeping the evidence the host can still pull, then exits; an operation already in flight completes first, all within the shutdown grace period, after which a guest still held is released directly in one bounded attempt. A guest whose release fails keeps its record and stops renewing, so its lease ends within its last 15-minute window. With `pause`, the default, the relay renews each guest's lease once for the rest of its TTL, then renewal pauses and the recording detaches; no VM is destroyed and is retained until its TTL for an explicit finish or release. A `finish` or `release` already in flight completes first, for up to the shutdown grace period; after that the operation is cancelled and renewal pauses without it. The backend TTL and grace period handle abandoned leases. Status reports the last confirmed expiration time.
|
|
199
|
-
- While the session is live, the relay tracks the lease's own deadline (its start plus `ttlHours`) and renews
|
|
210
|
+
- While the session is live, the relay tracks the lease's own deadline (its start plus `ttlHours`) and renews machine-service only 15 minutes ahead at a time, never past that deadline, and stops renewing at it. A client that crashes without ending its session therefore leaves its VM leased for at most about 15 minutes, plus the backend's grace period, rather than its whole TTL.
|
|
200
211
|
- A restarted server with the same `MCP_RELAY_SESSION` reconciles each guest's durable ownership and reattaches its recording session without replaying prior work; every guest keeps its name. A session state written by a relay before several guests is restored as one guest named from its task. Context compaction does not reset VM state; `probe` reports the owned state without relying on earlier messages.
|
|
201
212
|
- A run tool's `timeoutMs` defaults to 120,000 ms and accepts integers up to 3,600,000 ms. It bounds command execution, not the snapshot delay or the lease lifetime. A timeout reports confirmed termination or uncertainty and keeps the VM available.
|
|
202
|
-
- `
|
|
213
|
+
- A shell `relay_script` with `diagnostic: true` records diagnosis or repair without screenshots, for explicitly requested diagnosis when capture is unavailable. It runs through machine-service as `/bin/sh -c <script>`, a script file read on the host first: before staging in the guest's default directory, after staging in the recording workspace. Only a shell script may be diagnostic, because no receiver or Node.js is involved. It cannot join a snapshot group and is not visual verification.
|
|
203
214
|
- After diagnosing damaged recording state, `relay_stage` with `resetRecording: true` archives the old recording and starts a new recording session in the same VM. An existing receiver lock refuses the reset until its operation is reconciled. Prior evidence paths remain in the owned status.
|
|
204
215
|
|
|
205
216
|
## Runs
|
|
206
217
|
|
|
207
|
-
`
|
|
208
|
-
|
|
218
|
+
`relay_script` runs one script as one recorded operation; a command is a
|
|
219
|
+
shell script:
|
|
209
220
|
|
|
210
221
|
```json
|
|
211
|
-
{"guest":"login-test-1","
|
|
222
|
+
{"guest":"login-test-1","language":"shell","inline":true,"code":"/usr/bin/xdg-open https://example.com"}
|
|
212
223
|
{"guest":"login-test-1","language":"python","inline":true,"code":"import subprocess\nprint(subprocess.run(['cua-driver','call','list_apps'],capture_output=True,text=True).stdout)"}
|
|
213
224
|
{"guest":"login-test-1","language":"typescript","inline":false,"localPath":"checks/login.ts"}
|
|
214
225
|
```
|
|
@@ -216,15 +227,18 @@ recorded operation:
|
|
|
216
227
|
- **Evidence is automatic.** Every run is admitted by the guest receiver,
|
|
217
228
|
journaled, and, when the image lists cua-driver, bracketed by a before and an
|
|
218
229
|
after display snapshot. The step record is derived from the call: the title
|
|
219
|
-
is
|
|
230
|
+
is a shell script's first line (`shell <line>`), `code (<language>)` or
|
|
231
|
+
`script <file>`, and
|
|
220
232
|
the expected result is "Exits with status 0". `reason`, `step` and
|
|
221
233
|
`snapshots` are optional overrides; the default wait before the
|
|
222
234
|
after-snapshot is 500 ms.
|
|
223
235
|
- **Scripts.** A `relay_script` with `inline: true` streams its `code` to the
|
|
224
236
|
guest with its hash; with `inline: false` its `localPath`, a file in the
|
|
225
237
|
project folder, is pushed hash-checked. The script runs in the staged
|
|
226
|
-
workspace: JavaScript with the guest's Node.js,
|
|
227
|
-
|
|
238
|
+
workspace: shell with `/bin/sh`, JavaScript with the guest's Node.js,
|
|
239
|
+
TypeScript with `tsx` or Node.js type stripping, Python with `python3`. The
|
|
240
|
+
script's exit status says whether it succeeded: a script that calls
|
|
241
|
+
cua-driver reads the driver's answer and exits nonzero on an error. A call that gives `code` and `localPath` other than
|
|
228
242
|
as `inline` names is refused before anything reaches the guest.
|
|
229
243
|
- **One interaction per run.** A run is one recorded operation; consecutive
|
|
230
244
|
keystrokes may form an explicit text group with `snapshots.group`. A script
|
|
@@ -244,9 +258,9 @@ flight. They put the steps still queued, and every other file the host lacks,
|
|
|
244
258
|
into one archive of their own, and copy the files the step downloads already
|
|
245
259
|
brought instead of pulling them again. `relay_status` counts the steps whose
|
|
246
260
|
download a lifecycle operation took over as `coalesced`. A first or intermediate
|
|
247
|
-
group event and a diagnostic
|
|
261
|
+
group event and a diagnostic script do not invent an image. Execution and
|
|
248
262
|
image delivery are independent outcomes: a pending image does not turn a
|
|
249
|
-
failed
|
|
263
|
+
failed run into a successful one. The delivery identity leads the result
|
|
250
264
|
text so it survives truncation. The design is `docs/screenshot-delivery.md`
|
|
251
265
|
§10.
|
|
252
266
|
|
|
@@ -290,17 +304,18 @@ installation or platform acceptance is claimed here.
|
|
|
290
304
|
|
|
291
305
|
## Selected environments
|
|
292
306
|
|
|
293
|
-
Set `VM_ENVIRONMENT_FILE` to a profile
|
|
294
|
-
endpoint, an image repository, a Tart store and separate service, image and
|
|
307
|
+
Set `VM_ENVIRONMENT_FILE` to a profile, at `schemaVersion` 2 with
|
|
308
|
+
`machctlPath`, that binds a loopback machine-service endpoint, an image repository, a Tart store and separate service, image and
|
|
295
309
|
relay state directories together. The profile is validated before use, is
|
|
296
310
|
authoritative over the individual `MCP_RELAY_*` variables, and an invalid
|
|
297
311
|
selection fails rather than falling back. Leases are bound to their backend and
|
|
298
312
|
store: an owned lease restored under a different environment fails before any
|
|
299
313
|
backend operation, and destruction is verified with the selected Tart binary
|
|
300
314
|
and `TART_HOME`. `docs/selected-environments.md` documents the schema. The
|
|
301
|
-
bundle the profile exports to subprocesses is the canonical one
|
|
302
|
-
defines, so its relay entries
|
|
303
|
-
`VM_RELAY_URL` names and the three runtimes
|
|
315
|
+
bundle the profile exports to subprocesses is the canonical one machine-service
|
|
316
|
+
defines, with `MACHCTL` and the `MACHINE_SERVICE_*` names, so its relay entries
|
|
317
|
+
keep the `VM_RELAY_STATE_DIR` and `VM_RELAY_URL` names and the three runtimes
|
|
318
|
+
agree; this server reads its own
|
|
304
319
|
settings from the profile.
|
|
305
320
|
|
|
306
321
|
## Evidence and cleanup
|
|
@@ -322,7 +337,7 @@ destroying the VM; a failed delivery removes only the derived files it created
|
|
|
322
337
|
and retains the VM for a corrected attempt. Cleanup checks the read-only host
|
|
323
338
|
Tart inventory (the selected one, when an environment is selected) before
|
|
324
339
|
claiming destruction. Leases default to 4 hours, renewed 15 minutes at a
|
|
325
|
-
time up to that TTL; the
|
|
340
|
+
time up to that TTL; the machine-service reaper is the final backstop for process death.
|
|
326
341
|
|
|
327
342
|
Relay evidence has no size limit (owner decision PS-D12): screenshots are
|
|
328
343
|
delivered as captured, never scaled, compressed, deduplicated or budgeted, and
|
|
@@ -337,10 +352,10 @@ keeps the VM for a retry after space is freed.
|
|
|
337
352
|
|
|
338
353
|
- `MCP_RELAY_PROJECT`: the project directory (the plugin passes Claude Code's). Evidence lands under `relay-evidence/<task>/` there. Every host file the relay reads, `relay_stage`'s `workspace` and `files[].local` and `relay_script`'s `localPath`, lies in this folder: a relative path resolves against it, an absolute path must already lie in it, and a path through a symlink is refused.
|
|
339
354
|
- `MCP_RELAY_SESSION`: an explicit session identity. By default each server process takes a fresh random one; a stable identity lets a restarted server reconcile and reattach the guests of the same identity.
|
|
340
|
-
- `MCP_RELAY_URL`: the loopback
|
|
341
|
-
- `MCP_RELAY_GUEST_NETWORK`: the network every guest is acquired on, `nat` (the default) or `internet`. With `internet`,
|
|
355
|
+
- `MCP_RELAY_URL`: the loopback machine-service origin, default `http://localhost:6240`. Non-loopback servers, redirects and physical targets are refused.
|
|
356
|
+
- `MCP_RELAY_GUEST_NETWORK`: the network every guest is acquired on, `nat` (the default) or `internet`. With `internet`, machine-service gives a guest that reaches the internet and reaches neither this host nor any private network; an application that hosts agents sets it. The agent cannot choose it: `relay_acquire` takes no network. Any other value stops the server at startup and refuses every acquisition, and a machine-service that cannot give `internet` refuses the acquisition with its own reason, never falling back to `nat`.
|
|
342
357
|
- `MCP_RELAY_ON_EXIT`: what the end of a session does to its guests, `pause` (the default: renewal pauses and the VMs are kept for an explicit finish or release) or `release` (every guest is released, then the server exits). An application that owns its tasks' machines, such as The Desk, sets `release`. Any other value stops the server at startup.
|
|
343
|
-
- `MCP_RELAY_CAPACITY_WAIT`: how many seconds `relay_acquire` waits when the host is at capacity, such as at
|
|
358
|
+
- `MCP_RELAY_CAPACITY_WAIT`: how many seconds `relay_acquire` waits when the host is at capacity, such as at machine-service's limit of two running macOS VMs, asking again every 15 s; default 1800, and 0 for not at all. Any other value stops the server at startup.
|
|
344
359
|
- `MCP_RELAY_MAX_GUESTS`: the most guests one session holds at once, a positive integer, default 4. Any other value stops the server at startup.
|
|
345
360
|
- `MCP_RELAY_STATE_DIR`: host state, otherwise `$XDG_STATE_HOME/mcp-relay` or `~/.local/state/mcp-relay`, one subdirectory per session, with one `guests/<guest>/` folder per guest holding its ownership record and owner lock.
|
|
346
361
|
- `MCP_RELAY_REGISTRY`: an explicit task registry file; otherwise an existing compatible `~/AGENTS.md` VM table, or a private managed `registry.md` in the state directory.
|
|
@@ -359,9 +374,12 @@ npm run setup:dev -- /absolute/path/to/built/relay-driver
|
|
|
359
374
|
npm run check # build, typecheck, tests
|
|
360
375
|
```
|
|
361
376
|
|
|
362
|
-
Three tests need
|
|
363
|
-
|
|
364
|
-
|
|
377
|
+
Three tests need something outside this repository and skip with a message
|
|
378
|
+
when it is absent: the console fixture regeneration needs a historical
|
|
379
|
+
`../vm-service` checkout with the Python backend (or
|
|
380
|
+
`VM_SERVICE_PYTHON_BACKEND`); the environment parity test needs
|
|
381
|
+
machine-service's `machctl` (`MACHCTL`, `PATH`, or a release build in
|
|
382
|
+
`../machine-service/rust`) and `../pilot-images`; and the shared catalog text
|
|
365
383
|
corpus needs `../pilot-images`. The JPEG and WebP presentation fixtures in
|
|
366
384
|
`tests/fixtures/` were encoded once from the test's spatial PNG with a codec
|
|
367
385
|
outside this repository and are committed, because the core carries none.
|
|
@@ -374,7 +392,7 @@ npm run test:e2e
|
|
|
374
392
|
|
|
375
393
|
This runs `claude --print` with the plugin loaded from this checkout
|
|
376
394
|
(`--plugin-dir`), the model limited to the relay's tools, and the server pointed
|
|
377
|
-
at a loopback stand-in for
|
|
395
|
+
at a loopback stand-in for machine-service (`tests/e2e/fixture-service.ts`), which
|
|
378
396
|
keeps leases as records, runs the relay's own Node and transfer commands
|
|
379
397
|
locally, and fakes the desktop capture driver. Four cases run, each a separate
|
|
380
398
|
headless session: the status call (which also proves the server is pointed at
|
|
@@ -407,7 +425,7 @@ separate, explicit step.
|
|
|
407
425
|
|
|
408
426
|
Pushing the tag triggers
|
|
409
427
|
[`.github/workflows/release.yml`](.github/workflows/release.yml), which
|
|
410
|
-
rebuilds `
|
|
428
|
+
rebuilds `machctl`, checks the working build against a fresh one, and publishes
|
|
411
429
|
to npm using [trusted publishing](https://docs.npmjs.com/trusted-publishers)
|
|
412
430
|
(OIDC — no `NPM_TOKEN` secret involved), then creates the matching GitHub
|
|
413
431
|
release.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: vm-relay-operator
|
|
3
3
|
description: Operates one or more guest VMs through the relay's MCP tools for a task to run in a guest. Give it the task, the image to use and the outputs to bring home; it returns the verified package path and the separate evidence and execution outcomes.
|
|
4
|
-
tools: mcp__plugin_mcp-relay_relay__relay_search, mcp__plugin_mcp-relay_relay__relay_probe, mcp__plugin_mcp-relay_relay__relay_acquisition_capabilities, mcp__plugin_mcp-relay_relay__relay_acquire, mcp__plugin_mcp-relay_relay__relay_stage, mcp__plugin_mcp-
|
|
4
|
+
tools: mcp__plugin_mcp-relay_relay__relay_search, mcp__plugin_mcp-relay_relay__relay_probe, mcp__plugin_mcp-relay_relay__relay_acquisition_capabilities, mcp__plugin_mcp-relay_relay__relay_acquire, mcp__plugin_mcp-relay_relay__relay_stage, mcp__plugin_mcp-relay_relay__relay_script, mcp__plugin_mcp-relay_relay__relay_image, mcp__plugin_mcp-relay_relay__relay_extract, mcp__plugin_mcp-relay_relay__relay_finish, mcp__plugin_mcp-relay_relay__relay_release, mcp__plugin_mcp-relay_relay__relay_console_resolve, mcp__plugin_mcp-relay_relay__relay_console_open, mcp__plugin_mcp-relay_relay__relay_console_cancel, mcp__plugin_mcp-relay_relay__relay_status, Read, Glob, Grep
|
|
5
5
|
model: sonnet
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -11,10 +11,10 @@ guest for each machine the task needs, and declare every output you will bring
|
|
|
11
11
|
home as an extraction before any work. relay_acquire answers the guest's name,
|
|
12
12
|
`guest`; name it in every later call on that guest. Several guests may run at
|
|
13
13
|
once, and finishing one leaves the others running. Stage the runtime and the support the task needs.
|
|
14
|
-
Run
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
from a
|
|
14
|
+
Run everything with relay_script: a shell, JavaScript, TypeScript or Python
|
|
15
|
+
script, given inline (`inline: true`, `code`) or as a project file
|
|
16
|
+
(`inline: false`, `localPath`). A command is a shell script. Drive the desktop
|
|
17
|
+
and browsers from a script through the software the image lists, such as
|
|
18
18
|
cua-driver's command line or Playwright; relay_probe with `scope: "guest"`
|
|
19
19
|
reports the runtimes and the listed software. When the image lists cua-driver
|
|
20
20
|
the relay snapshots every run, and it records each run as a step; add `reason`
|
|
@@ -27,7 +27,7 @@ shows it. If relay_image reports that the image was not attached, retry it
|
|
|
27
27
|
with the same reference; never repeat input to obtain
|
|
28
28
|
an image, and stop exploratory input if a required image is still
|
|
29
29
|
uninspectable after two recovery calls. A failed operation keeps the VM:
|
|
30
|
-
diagnose it, use
|
|
30
|
+
diagnose it, use a shell relay_script with `diagnostic: true` if the user's task calls
|
|
31
31
|
for repair, or relay_release. Never replay uncertain input. Do not open
|
|
32
32
|
console viewing (relay_console_open) unless the user explicitly asked to
|
|
33
33
|
watch.
|
|
@@ -35,5 +35,5 @@ watch.
|
|
|
35
35
|
Call relay_finish or relay_release explicitly for every guest before you
|
|
36
36
|
return; the session ending never finishes a guest. Report the verified package path, the
|
|
37
37
|
delivery result, the snapshot completeness and the execution outcome as
|
|
38
|
-
separate facts. Do not claim human review. Do not use
|
|
38
|
+
separate facts. Do not claim human review. Do not use machine-service or
|
|
39
39
|
relay-driver directly.
|
package/dist/build-info.json
CHANGED
|
@@ -956,30 +956,30 @@
|
|
|
956
956
|
"src/archive.ts": "469ca411558db5696c8790d8a7132108d6705d4316c5a31a149f7472ddbef0ec",
|
|
957
957
|
"src/config.ts": "3fbc475596ec0a1b6122ea963bf2769420a8a2a0e62fda55e66018fb3a6d53b3",
|
|
958
958
|
"src/console.ts": "d8258173a24449c2a394289b14983b9575c5ce753ab267d4e13213f3abfcb72d",
|
|
959
|
-
"src/core.ts": "
|
|
960
|
-
"src/doctor.ts": "
|
|
959
|
+
"src/core.ts": "dd889fda6af982ab47b40b346e7fbc41a213b6d258d3d5fe56cd8c5373221159",
|
|
960
|
+
"src/doctor.ts": "8249e9fa78b679e9ef7fd30f617bf07848961346101d3b64c42f779cfb042671",
|
|
961
961
|
"src/downloads.ts": "4f37b5bb4fac96f9260a3a87c83bacf715b9add5ae9926d3fe0994000c70a8dd",
|
|
962
|
-
"src/environment.ts": "
|
|
962
|
+
"src/environment.ts": "5770e966e49d78ae069614078c667f94e70074b150f83111049529ff613aa215",
|
|
963
963
|
"src/evidence-merge.ts": "2f2759e28e70595ef9284fec85e1d6082bf25e815d04f0a36a253c24bfb75110",
|
|
964
|
-
"src/guest/image-evidence.ts": "
|
|
965
|
-
"src/guest/receiver.ts": "
|
|
964
|
+
"src/guest/image-evidence.ts": "9c5daaed5b33b9912021a91fd79a2e6d5be42c75d37761772a3bd2645d20a55e",
|
|
965
|
+
"src/guest/receiver.ts": "92fc8d3bfe95ed56d43cfe5b46eb196034ade5e4e9f58ed202465531458f697d",
|
|
966
966
|
"src/image-presentation.ts": "64ca29a3444a04606cb783c81ac2d0f3136f9a9ac730ae9074156f0a63256c76",
|
|
967
967
|
"src/images.ts": "734a30ba34cd80ef0b5c3791232f13b170b06d6d74c4b843d39566d2e09136d0",
|
|
968
|
-
"src/
|
|
968
|
+
"src/machine-service.ts": "777fac0552e2aa63910b6e224c787cf0b2696e7652eab0a734c7c772de3eddf3",
|
|
969
|
+
"src/manager.ts": "440c06f3cd42b5f8031e0dca43088225175ca64a956c85e88890e39b8b3ea291",
|
|
969
970
|
"src/owner-lock.ts": "a99cbaba67b4aff0e646dc5d5967db4497ba6dbda83fb1838c55f0bf0f6e0367",
|
|
970
971
|
"src/package.ts": "a52ed791813922e3ace9144706ddde8313a67d8580a3acd54a0799de3ebe44d2",
|
|
971
972
|
"src/probe.ts": "40a123f725aad7c22fe63707dd2de99646cb1f307d7d660927e8ca2b973e9ce0",
|
|
972
973
|
"src/registry.ts": "87478f1ceef0f06df9b28c064a817383ff153bdadd70e6d58b4a7ed464f66146",
|
|
973
974
|
"src/review-data.ts": "2e873eb23612fd4502d84e65322006345f4e97bb679109b23dc4d26683200c19",
|
|
974
|
-
"src/schema.ts": "
|
|
975
|
+
"src/schema.ts": "110d65d59a2ad3bcd3a35de188f68804dcada9c92702630aaf9de029ba77b5a5",
|
|
975
976
|
"src/search-diagnostics.ts": "cea037618c56f075d51155101ad1cc0314bfa67b174bdb070191e0ea5ea04679",
|
|
976
977
|
"src/search.ts": "8aaf544fcb27e7e018bd976e1ba7d3c70c047aeda3182b3dce91873a901a245e",
|
|
977
|
-
"src/server.ts": "
|
|
978
|
-
"src/surface.ts": "
|
|
979
|
-
"src/transfer.ts": "
|
|
980
|
-
"src/transport.ts": "
|
|
978
|
+
"src/server.ts": "bff4c09c29890aa62175ead36d9cfd6f8fa7334d2ee0929b51a0371d38c5df1c",
|
|
979
|
+
"src/surface.ts": "f7772fbafa613aaeba05e47d2def4975fb0ce75d1af067bde968f0e95775f81a",
|
|
980
|
+
"src/transfer.ts": "f27d65c0b42f9933e6a7f950f56111b84c644e8739bab44805aebfb54d77e320",
|
|
981
|
+
"src/transport.ts": "35df20b321f52c4a371f1e29923e957e7c85d58001e2864f0fd13c2c2838945f",
|
|
981
982
|
"src/typebox.ts": "7f071fbc67548c7d3701272dabe88a217812e12e41dfad76974ff08169fa1a7e",
|
|
982
|
-
"src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da"
|
|
983
|
-
"src/vm-service.ts": "f2a6bfa910484f42aa264dbe02012379c82b093a71645b33e8a8ccd968f4634d"
|
|
983
|
+
"src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da"
|
|
984
984
|
}
|
|
985
985
|
}
|
package/dist/doctor.mjs
CHANGED
|
@@ -45,14 +45,14 @@ async function command(argv, options = {}) {
|
|
|
45
45
|
});
|
|
46
46
|
}
|
|
47
47
|
|
|
48
|
-
// src/
|
|
48
|
+
// src/machine-service.ts
|
|
49
49
|
import { isIP } from "node:net";
|
|
50
|
-
var
|
|
50
|
+
var MachineServiceError = class extends Error {
|
|
51
51
|
constructor(message, status, responseBody, options) {
|
|
52
52
|
super(message, options);
|
|
53
53
|
this.status = status;
|
|
54
54
|
this.responseBody = responseBody;
|
|
55
|
-
this.name = "
|
|
55
|
+
this.name = "MachineServiceError";
|
|
56
56
|
}
|
|
57
57
|
status;
|
|
58
58
|
responseBody;
|
|
@@ -60,7 +60,7 @@ var VmServiceError = class extends Error {
|
|
|
60
60
|
capacity = false;
|
|
61
61
|
};
|
|
62
62
|
function capacityRefusal(error) {
|
|
63
|
-
if (!(error instanceof
|
|
63
|
+
if (!(error instanceof MachineServiceError) || error.status !== 409 || !error.responseBody) return false;
|
|
64
64
|
let body;
|
|
65
65
|
try {
|
|
66
66
|
body = JSON.parse(error.responseBody);
|
|
@@ -71,9 +71,14 @@ function capacityRefusal(error) {
|
|
|
71
71
|
const { error: reason, outcome } = body;
|
|
72
72
|
return typeof reason === "string" && reason.startsWith("macOS VM limit reached") && outcome !== "uncertain";
|
|
73
73
|
}
|
|
74
|
-
var
|
|
74
|
+
var SERVICE_NAME = "machine-service";
|
|
75
|
+
function expectMachineService(health, origin) {
|
|
76
|
+
if (health.service === SERVICE_NAME) return;
|
|
77
|
+
throw new Error(`The service at ${origin} answers as ${JSON.stringify(health.service ?? null)}, not ${SERVICE_NAME}. This relay speaks only machine-service's /machines API: install machine-service, which replaced vm-service.`);
|
|
78
|
+
}
|
|
79
|
+
var AcquireIndeterminateError = class extends MachineServiceError {
|
|
75
80
|
constructor(purpose, cause) {
|
|
76
|
-
super(`Acquisition outcome unknown for purpose '${purpose}'; reconcile GET /
|
|
81
|
+
super(`Acquisition outcome unknown for purpose '${purpose}'; reconcile GET /machines before retrying or ending the enclosure`, void 0, void 0, { cause });
|
|
77
82
|
this.purpose = purpose;
|
|
78
83
|
this.name = "AcquireIndeterminateError";
|
|
79
84
|
}
|
|
@@ -90,7 +95,7 @@ function isLease(value) {
|
|
|
90
95
|
if (!record(value)) return false;
|
|
91
96
|
return ["vm", "purpose", "image"].every((k) => typeof value[k] === "string" && value[k] !== "") && ["macos", "linux"].includes(String(value.image_kind)) && ["pending", "provisioning", "running", "releasing"].includes(String(value.state)) && ["created_at", "ttl_expires_at"].every((k) => typeof value[k] === "number" && Number.isFinite(value[k])) && ["cpu", "memory_mb", "disk_gb", "grace_until"].every((k) => value[k] === null || typeof value[k] === "number") && ["env", "ip"].every((k) => value[k] === null || typeof value[k] === "string") && typeof value.warned === "boolean";
|
|
92
97
|
}
|
|
93
|
-
var
|
|
98
|
+
var MachineService = class {
|
|
94
99
|
baseUrl;
|
|
95
100
|
environment;
|
|
96
101
|
timeoutMs;
|
|
@@ -104,7 +109,7 @@ var VmService = class {
|
|
|
104
109
|
const host = url.hostname.replace(/^\[|\]$/g, "");
|
|
105
110
|
const loopback = host === "localhost" || host === "::1" || isIP(host) === 4 && host.startsWith("127.");
|
|
106
111
|
if (!loopback || !["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
|
|
107
|
-
throw new TypeError("
|
|
112
|
+
throw new TypeError("machine-service baseUrl must be a loopback HTTP(S) origin without credentials, path, query or fragment");
|
|
108
113
|
}
|
|
109
114
|
this.baseUrl = url.origin;
|
|
110
115
|
this.timeoutMs = positive(options.timeoutMs ?? 66e4, "timeoutMs");
|
|
@@ -115,7 +120,7 @@ var VmService = class {
|
|
|
115
120
|
return this.request("/health", void 0, options);
|
|
116
121
|
}
|
|
117
122
|
list(options = {}) {
|
|
118
|
-
return this.request("/
|
|
123
|
+
return this.request("/machines", void 0, options);
|
|
119
124
|
}
|
|
120
125
|
images(options = {}) {
|
|
121
126
|
return this.request("/images", void 0, options);
|
|
@@ -139,7 +144,7 @@ var VmService = class {
|
|
|
139
144
|
try {
|
|
140
145
|
return await this.request(path, body, options);
|
|
141
146
|
} catch (error) {
|
|
142
|
-
throw new
|
|
147
|
+
throw new MachineServiceError(`Console API unavailable or request outcome unknown${error instanceof MachineServiceError && error.status ? ` (HTTP ${error.status})` : ""}; resolve before another open`, error instanceof MachineServiceError ? error.status : void 0);
|
|
143
148
|
}
|
|
144
149
|
}
|
|
145
150
|
get(vm, options = {}) {
|
|
@@ -158,12 +163,12 @@ var VmService = class {
|
|
|
158
163
|
const timeoutMs = positive(options.timeoutMs ?? this.acquireTimeoutMs, "timeoutMs");
|
|
159
164
|
try {
|
|
160
165
|
const lease = await this.request("/acquire", body, { timeoutMs });
|
|
161
|
-
if (!isLease(lease)) throw new
|
|
166
|
+
if (!isLease(lease)) throw new MachineServiceError("Invalid machine-service acquire response");
|
|
162
167
|
return lease;
|
|
163
168
|
} catch (error) {
|
|
164
|
-
const safeError = body.vnc ? new
|
|
165
|
-
if (safeError instanceof
|
|
166
|
-
if (error instanceof
|
|
169
|
+
const safeError = body.vnc ? new MachineServiceError(`VNC acquisition refused or outcome unknown${error instanceof MachineServiceError && error.status ? ` (HTTP ${error.status})` : ""}; inspect capabilities and reconcile ownership`, error instanceof MachineServiceError ? error.status : void 0) : error;
|
|
170
|
+
if (safeError instanceof MachineServiceError) safeError.capacity = capacityRefusal(error);
|
|
171
|
+
if (error instanceof MachineServiceError && error.status !== void 0 && error.status >= 400 && error.status < 500) throw safeError;
|
|
167
172
|
throw new AcquireIndeterminateError(body.purpose, safeError);
|
|
168
173
|
}
|
|
169
174
|
}
|
|
@@ -184,7 +189,7 @@ var VmService = class {
|
|
|
184
189
|
}
|
|
185
190
|
path(vm, action) {
|
|
186
191
|
if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(vm)) throw new TypeError("Invalid VM name");
|
|
187
|
-
return `/
|
|
192
|
+
return `/machines/${encodeURIComponent(vm)}${action ? `/${action}` : ""}`;
|
|
188
193
|
}
|
|
189
194
|
async request(path, body, options) {
|
|
190
195
|
options.signal?.throwIfAborted();
|
|
@@ -192,7 +197,7 @@ var VmService = class {
|
|
|
192
197
|
const controller = new AbortController();
|
|
193
198
|
const abort = () => controller.abort(options.signal?.reason);
|
|
194
199
|
options.signal?.addEventListener("abort", abort, { once: true });
|
|
195
|
-
const timer = setTimeout(() => controller.abort(new
|
|
200
|
+
const timer = setTimeout(() => controller.abort(new MachineServiceError(`machine-service ${path} timed out after ${timeoutMs}ms`)), timeoutMs);
|
|
196
201
|
try {
|
|
197
202
|
const response = await fetch(`${this.baseUrl}${path}`, {
|
|
198
203
|
method: body === void 0 ? "GET" : "POST",
|
|
@@ -226,17 +231,17 @@ var VmService = class {
|
|
|
226
231
|
}
|
|
227
232
|
}
|
|
228
233
|
const text = Buffer.concat(chunks).toString("utf8");
|
|
229
|
-
if (!response.ok) throw new
|
|
230
|
-
if (truncated) throw new
|
|
234
|
+
if (!response.ok) throw new MachineServiceError(`machine-service ${path}: HTTP ${response.status}: ${text}${truncated ? " [truncated]" : ""}`, response.status, text);
|
|
235
|
+
if (truncated) throw new MachineServiceError(`machine-service ${path}: response exceeds ${bound} bytes`);
|
|
231
236
|
try {
|
|
232
237
|
return JSON.parse(text);
|
|
233
238
|
} catch (cause) {
|
|
234
|
-
throw new
|
|
239
|
+
throw new MachineServiceError(`machine-service ${path}: invalid JSON response`, void 0, void 0, { cause });
|
|
235
240
|
}
|
|
236
241
|
} catch (cause) {
|
|
237
242
|
if (controller.signal.aborted) throw controller.signal.reason;
|
|
238
|
-
if (cause instanceof
|
|
239
|
-
throw new
|
|
243
|
+
if (cause instanceof MachineServiceError) throw cause;
|
|
244
|
+
throw new MachineServiceError(`machine-service ${path}: request failed`, void 0, void 0, { cause });
|
|
240
245
|
} finally {
|
|
241
246
|
clearTimeout(timer);
|
|
242
247
|
options.signal?.removeEventListener("abort", abort);
|
|
@@ -260,8 +265,9 @@ import { createHash as createHash2 } from "node:crypto";
|
|
|
260
265
|
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
|
|
261
266
|
import { homedir } from "node:os";
|
|
262
267
|
import { isIP as isIP2 } from "node:net";
|
|
263
|
-
var paths = ["imageRepository", "tartHome", "serviceStateDir", "imageStateDir", "relayStateDir", "
|
|
268
|
+
var paths = ["imageRepository", "tartHome", "serviceStateDir", "imageStateDir", "relayStateDir", "machctlPath", "tartPath"];
|
|
264
269
|
var mutable = ["tartHome", "serviceStateDir", "imageStateDir", "relayStateDir"];
|
|
270
|
+
var LEGACY_PROFILE = "Environment profile is from before the machine-service rename, which reads only schemaVersion 2 with machctlPath: a profile at schemaVersion 1 or with vmctlPath is refused. Rename vmctlPath to machctlPath, naming the machctl executable, and set schemaVersion to 2.";
|
|
265
271
|
function canonicalPath(value) {
|
|
266
272
|
if (typeof value !== "string" || !isAbsolute(value) || !value.trim() || /[\x00-\x1f\x7f\uD800-\uDFFF]/u.test(value)) throw new Error("Environment paths must be absolute and contain no control characters");
|
|
267
273
|
let ancestor = resolve(value);
|
|
@@ -322,19 +328,20 @@ function loadEnvironment(path, env = process.env, home = env.HOME ?? homedir())
|
|
|
322
328
|
} else if (text[i] === "{" || text[i] === "[") depth++;
|
|
323
329
|
else if (text[i] === "}" || text[i] === "]") depth--;
|
|
324
330
|
}
|
|
331
|
+
if (raw && typeof raw === "object" && !Array.isArray(raw) && (raw.schemaVersion === 1 || Object.hasOwn(raw, "vmctlPath"))) throw new Error(LEGACY_PROFILE);
|
|
325
332
|
const fields = ["schemaVersion", "id", "vmServiceUrl", ...paths].sort();
|
|
326
333
|
if (!raw || typeof raw !== "object" || Array.isArray(raw) || JSON.stringify(Object.keys(raw).sort()) !== JSON.stringify(fields)) throw new Error("Environment profile has missing or unknown fields");
|
|
327
334
|
const p = raw;
|
|
328
|
-
if (p.schemaVersion !==
|
|
329
|
-
const profile = { schemaVersion:
|
|
335
|
+
if (p.schemaVersion !== 2 || typeof p.id !== "string" || !/^[a-z0-9][a-z0-9-]{0,47}$/.test(p.id)) throw new Error("Invalid environment schemaVersion or id");
|
|
336
|
+
const profile = { schemaVersion: 2, id: p.id, vmServiceUrl: endpoint(p.vmServiceUrl) };
|
|
330
337
|
for (const key of paths) profile[key] = canonicalPath(p[key]);
|
|
331
338
|
if (!statSync(profile.imageRepository).isDirectory() || !statSync(join(profile.imageRepository, "images")).isDirectory()) throw new Error("Selected imageRepository must contain images/");
|
|
332
|
-
for (const key of ["
|
|
339
|
+
for (const key of ["machctlPath", "tartPath"]) {
|
|
333
340
|
if (!statSync(profile[key]).isFile()) throw new Error(`${key} must be a regular executable file`);
|
|
334
341
|
accessSync(profile[key], constants.X_OK);
|
|
335
342
|
}
|
|
336
343
|
const state = env.XDG_STATE_HOME ? canonicalPath(env.XDG_STATE_HOME) : join(canonicalPath(home), ".local/state");
|
|
337
|
-
const names = ["vm-service", "pilot-images", "mcp-relay", "mcp-vm-relay"];
|
|
344
|
+
const names = ["machine-service", "vm-service", "pilot-images", "mcp-relay", "mcp-vm-relay"];
|
|
338
345
|
const defaults = [join(canonicalPath(home), ".tart"), ...names.map((n) => join(state, n)), ...names.map((n) => join(canonicalPath(home), ".local/state", n))].map(canonicalPath);
|
|
339
346
|
for (const key of mutable) {
|
|
340
347
|
const value = profile[key];
|
|
@@ -373,13 +380,13 @@ function environmentVariables(selected) {
|
|
|
373
380
|
VM_ENVIRONMENT_FINGERPRINT: selected.identity.fingerprint,
|
|
374
381
|
PILOT_REPO: p.imageRepository,
|
|
375
382
|
TART_HOME: p.tartHome,
|
|
376
|
-
|
|
383
|
+
MACHINE_SERVICE_STATE: p.serviceStateDir,
|
|
377
384
|
PILOT_IMAGES_STATE_DIR: p.imageStateDir,
|
|
378
385
|
VM_RELAY_STATE_DIR: p.relayStateDir,
|
|
379
386
|
VM_RELAY_URL: p.vmServiceUrl,
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
387
|
+
MACHINE_SERVICE_HOST: url.hostname.replace(/^\[|\]$/g, ""),
|
|
388
|
+
MACHINE_SERVICE_PORT: String(Number(p.vmServiceUrl.match(/:([0-9]+)$/)[1])),
|
|
389
|
+
MACHCTL: p.machctlPath,
|
|
383
390
|
TART: p.tartPath
|
|
384
391
|
};
|
|
385
392
|
}
|
|
@@ -744,7 +751,7 @@ async function installationReport(options = {}) {
|
|
|
744
751
|
return process.versions.node;
|
|
745
752
|
});
|
|
746
753
|
await check("host", async () => {
|
|
747
|
-
if (process.platform !== "darwin" || process.arch !== "arm64") throw Error("The supported local Tart/
|
|
754
|
+
if (process.platform !== "darwin" || process.arch !== "arm64") throw Error("The supported local Tart/machine-service backend requires an Apple-silicon Mac. Ubuntu is a guest, not a substitute host.");
|
|
748
755
|
return `${process.platform}/${process.arch}`;
|
|
749
756
|
});
|
|
750
757
|
await check("python", async () => {
|
|
@@ -777,15 +784,16 @@ async function installationReport(options = {}) {
|
|
|
777
784
|
if (r.code !== 0 || !Array.isArray(JSON.parse(r.stdout))) throw Error("Install Tart and ensure tart list --format json works; required for independent destruction verification.");
|
|
778
785
|
return "Read-only local inventory available";
|
|
779
786
|
});
|
|
780
|
-
await check("
|
|
781
|
-
const vm = options.vm ?? new
|
|
787
|
+
await check("machine-service", async () => {
|
|
788
|
+
const vm = options.vm ?? new MachineService({ baseUrl: environment?.profile.vmServiceUrl ?? process.env.MCP_RELAY_URL, environment });
|
|
782
789
|
const health = await vm.health({ timeoutMs: 5e3 });
|
|
783
790
|
if (!health.ok) throw Error("Service health check failed");
|
|
784
|
-
|
|
791
|
+
expectMachineService(health, vm.baseUrl);
|
|
792
|
+
if (environment && !matchesEnvironment(health.environment, environment)) throw Error("machine-service environment identity mismatch");
|
|
785
793
|
const images = await vm.images({ timeoutMs: 5e3 });
|
|
786
794
|
await vm.list({ timeoutMs: 5e3 });
|
|
787
795
|
const available = Object.entries(images.images).filter(([, v]) => v.base_available).map(([k]) => k);
|
|
788
|
-
if (!available.length) throw Error("
|
|
796
|
+
if (!available.length) throw Error("machine-service is running but has no available golden images. Provision a supported image in the backend.");
|
|
789
797
|
return `HTTP API reachable; available images: ${available.join(", ")}. This inventory does not prove guest readiness. Use relay probe scope=guest for executable checks; capture and browser behavior require separate checks. Staging alone is not readiness.`;
|
|
790
798
|
});
|
|
791
799
|
return { formatVersion: 1, ready: checks.every((c) => c.ok), environment: environment?.identity, stateDirectory: environment?.profile.relayStateDir ?? relayStateRoot(), checks, note: "Read-only host/API prerequisite check. No VM acquired, input sent, screenshot captured or permissions changed. Claude Code (or another MCP client) must be installed separately." };
|