@wezzard/mcp-relay 0.15.0 → 0.17.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 +60 -27
- package/agents/vm-relay-operator.md +4 -3
- package/dist/build-info.json +13 -11
- package/dist/doctor.mjs +109 -54
- package/dist/integrity.json +2 -2
- package/dist/server.mjs +434 -196
- package/package.json +1 -1
- package/pi-mcp.json +1 -1
package/README.md
CHANGED
|
@@ -7,11 +7,10 @@ it for both Claude Code and pi, the latter loaded through `pi-mcp-adapter`. It
|
|
|
7
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 scripts, commands included as shell scripts, in a fresh, dedicated VM
|
|
11
|
-
the agent chooses to run there; a script drives the desktop or a browser
|
|
12
|
-
through the software the image lists, such as cua-driver or Playwright. Nothing here executes local computer-use, spawns
|
|
13
|
-
subagents,
|
|
14
|
-
browsers.
|
|
10
|
+
snapshot-evidenced scripts, commands included as shell scripts, in a fresh, dedicated VM or on a
|
|
11
|
+
durable machine, a real Mac leased whole, for any work the agent chooses to run there; a script drives the desktop or a browser
|
|
12
|
+
through the software the image lists, such as cua-driver or Playwright. Nothing here executes local computer-use on the relay's own host, spawns
|
|
13
|
+
subagents, records video, or attaches to existing browsers.
|
|
15
14
|
|
|
16
15
|
The project was named mcp-vm-relay before v0.12.0. The npm package is now
|
|
17
16
|
`@wezzard/mcp-relay`, the plugin and its marketplace are `mcp-relay`, and every
|
|
@@ -19,10 +18,19 @@ The project was named mcp-vm-relay before v0.12.0. The npm package is now
|
|
|
19
18
|
default state directory moved with the name, so finish or release a lease the
|
|
20
19
|
old relay owns before upgrading.
|
|
21
20
|
|
|
21
|
+
From v0.16.0 the relay's backend is machine-service, vm-service under its new
|
|
22
|
+
name. The relay asks for `/machines` paths, which vm-service never served, and
|
|
23
|
+
refuses a service whose `/health` does not answer `machine-service`. A selected
|
|
24
|
+
environment profile must be at `schemaVersion` 2 with `machctlPath`; a profile
|
|
25
|
+
at version 1 or with `vmctlPath` is refused with its fix in the error (DC-27).
|
|
26
|
+
The relay's own names do not change: `MCP_RELAY_*`, `VM_ENVIRONMENT_FILE`,
|
|
27
|
+
`VM_RELAY_*` and the state directories. Release every lease before switching,
|
|
28
|
+
as machine-service's installer requires.
|
|
29
|
+
|
|
22
30
|
## How it is built
|
|
23
31
|
|
|
24
32
|
The relay implementation lives in this repository: the manager
|
|
25
|
-
(`src/manager.ts`), the
|
|
33
|
+
(`src/manager.ts`), the machine-service client, the registry with its OS-level lock,
|
|
26
34
|
the guest transfer and transport, the evidence package and its state merge, the
|
|
27
35
|
selected-environment profile, the console and saved-image contracts, the strict
|
|
28
36
|
tool contract (`src/schema.ts`), the action dispatch and bounded result
|
|
@@ -53,7 +61,7 @@ adds nothing Claude-Code-specific beyond the marketplace packaging and the
|
|
|
53
61
|
| `/relay-status` command | `/mcp-relay-status` in pi, `/mcp-relay:status` in Claude Code; it asks the assistant to call `relay_status` |
|
|
54
62
|
| 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
63
|
| 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
|
|
64
|
+
| 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
65
|
| 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
66
|
|
|
59
67
|
## Install
|
|
@@ -106,7 +114,7 @@ without a Claude Code plugin or pi package wrapper.
|
|
|
106
114
|
|
|
107
115
|
Node 22+, Python 3 with `fcntl` for the registry lock, and for VM execution an
|
|
108
116
|
Apple-silicon Mac with Tart, a running
|
|
109
|
-
[
|
|
117
|
+
[machine-service](https://github.com/WeZZard/vm-service) (formerly vm-service) and prepared guest images.
|
|
110
118
|
Check readiness with `node dist/doctor.mjs`. It does not acquire a VM or
|
|
111
119
|
establish guest UI readiness. Staging and runs assume no software in the guest
|
|
112
120
|
but Node.js, which runs the relay's own guest code; `relay_stage` refuses an
|
|
@@ -117,7 +125,7 @@ gap. Snapshots need cua-driver with capture permission; on Linux, native X11
|
|
|
117
125
|
and `serve --no-overlay`. `relay_script` runs JavaScript with the guest's
|
|
118
126
|
Node.js, TypeScript with `tsx` and Python with `python3`, each from the guest's
|
|
119
127
|
`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
|
|
128
|
+
as cua-driver, Playwright or a browser. Console viewing needs the machine-service guest-sharing backend and its
|
|
121
129
|
guest preparation; see `docs/console.md` here.
|
|
122
130
|
|
|
123
131
|
## The tools
|
|
@@ -149,7 +157,7 @@ automatic: see "Runs" below.
|
|
|
149
157
|
| `relay_console_resolve` | Resolve console status | `console-resolve` | Resolve non-secret console status for the guest's lease and environment. |
|
|
150
158
|
| `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
159
|
| `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
|
|
160
|
+
| `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
161
|
|
|
154
162
|
`readOnlyHint`/`idempotentHint` are true for `relay_search`, `relay_probe`,
|
|
155
163
|
`relay_acquisition_capabilities`, `relay_console_resolve`, `relay_image` and
|
|
@@ -198,10 +206,10 @@ tarball it checked.
|
|
|
198
206
|
- 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.
|
|
199
207
|
- 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.
|
|
200
208
|
- 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.
|
|
201
|
-
- While the session is live, the relay tracks the lease's own deadline (its start plus `ttlHours`) and renews
|
|
209
|
+
- 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.
|
|
202
210
|
- 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.
|
|
203
211
|
- 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.
|
|
204
|
-
- A shell `relay_script` with `diagnostic: true` records diagnosis or repair without screenshots, for explicitly requested diagnosis when capture is unavailable. It runs through
|
|
212
|
+
- 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.
|
|
205
213
|
- 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.
|
|
206
214
|
|
|
207
215
|
## Runs
|
|
@@ -293,19 +301,40 @@ Failed or uncertain launches retain ownership; resolve or cancel the attempt
|
|
|
293
301
|
rather than replaying it. Console tests use mocked backends; no live viewer,
|
|
294
302
|
installation or platform acceptance is claimed here.
|
|
295
303
|
|
|
304
|
+
## Durable machines
|
|
305
|
+
|
|
306
|
+
`relay_acquire` takes `machine` in place of `image` to lease a durable machine,
|
|
307
|
+
a real Mac that machine-service exposes, such as `Build-Mac-1`. Every other
|
|
308
|
+
tool works on it as on a VM ([docs/durable-machines.md](docs/durable-machines.md)).
|
|
309
|
+
|
|
310
|
+
- The relay finds the instance that owns the machine as `machctl list` does:
|
|
311
|
+
the loopback instance, then every `machine-service` registration of the
|
|
312
|
+
Consul agent at `CONSUL_HTTP_ADDR` (default `http://127.0.0.1:8500`). A Mac
|
|
313
|
+
without its own Consul agent points `CONSUL_HTTP_ADDR` at one, for example
|
|
314
|
+
through an SSH tunnel.
|
|
315
|
+
- Every call carries the lease's `lease_id`, files go as bytes, and the relay
|
|
316
|
+
stages under the lease's workspace, which machine-service removes at release.
|
|
317
|
+
- Runs take snapshots only while the Mac's cua-driver daemon (`CuaDriver.app`,
|
|
318
|
+
`com.trycua.driver`) holds Screen Recording, read with
|
|
319
|
+
`cua-driver permissions status --json` in the lease. machine-service's own
|
|
320
|
+
permissions are not read, and it needs no Screen Recording grant.
|
|
321
|
+
- A durable machine is on the home network and not isolated from it, a CI job
|
|
322
|
+
may share its desktop, and it has no console.
|
|
323
|
+
|
|
296
324
|
## Selected environments
|
|
297
325
|
|
|
298
|
-
Set `VM_ENVIRONMENT_FILE` to a profile
|
|
299
|
-
endpoint, an image repository, a Tart store and separate service, image and
|
|
326
|
+
Set `VM_ENVIRONMENT_FILE` to a profile, at `schemaVersion` 2 with
|
|
327
|
+
`machctlPath`, that binds a loopback machine-service endpoint, an image repository, a Tart store and separate service, image and
|
|
300
328
|
relay state directories together. The profile is validated before use, is
|
|
301
329
|
authoritative over the individual `MCP_RELAY_*` variables, and an invalid
|
|
302
330
|
selection fails rather than falling back. Leases are bound to their backend and
|
|
303
331
|
store: an owned lease restored under a different environment fails before any
|
|
304
332
|
backend operation, and destruction is verified with the selected Tart binary
|
|
305
333
|
and `TART_HOME`. `docs/selected-environments.md` documents the schema. The
|
|
306
|
-
bundle the profile exports to subprocesses is the canonical one
|
|
307
|
-
defines, so its relay entries
|
|
308
|
-
`VM_RELAY_URL` names and the three runtimes
|
|
334
|
+
bundle the profile exports to subprocesses is the canonical one machine-service
|
|
335
|
+
defines, with `MACHCTL` and the `MACHINE_SERVICE_*` names, so its relay entries
|
|
336
|
+
keep the `VM_RELAY_STATE_DIR` and `VM_RELAY_URL` names and the three runtimes
|
|
337
|
+
agree; this server reads its own
|
|
309
338
|
settings from the profile.
|
|
310
339
|
|
|
311
340
|
## Evidence and cleanup
|
|
@@ -327,7 +356,7 @@ destroying the VM; a failed delivery removes only the derived files it created
|
|
|
327
356
|
and retains the VM for a corrected attempt. Cleanup checks the read-only host
|
|
328
357
|
Tart inventory (the selected one, when an environment is selected) before
|
|
329
358
|
claiming destruction. Leases default to 4 hours, renewed 15 minutes at a
|
|
330
|
-
time up to that TTL; the
|
|
359
|
+
time up to that TTL; the machine-service reaper is the final backstop for process death.
|
|
331
360
|
|
|
332
361
|
Relay evidence has no size limit (owner decision PS-D12): screenshots are
|
|
333
362
|
delivered as captured, never scaled, compressed, deduplicated or budgeted, and
|
|
@@ -342,17 +371,18 @@ keeps the VM for a retry after space is freed.
|
|
|
342
371
|
|
|
343
372
|
- `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.
|
|
344
373
|
- `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.
|
|
345
|
-
- `MCP_RELAY_URL`: the loopback
|
|
346
|
-
- `
|
|
374
|
+
- `MCP_RELAY_URL`: the loopback machine-service origin, default `http://localhost:6240`. Non-loopback servers and redirects are refused; a durable machine's instance on another Mac is reached only when Consul lists it.
|
|
375
|
+
- `CONSUL_HTTP_ADDR`: the Consul agent that lists machine-service instances, for durable machines; default `http://127.0.0.1:8500`.
|
|
376
|
+
- `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`.
|
|
347
377
|
- `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.
|
|
348
|
-
- `MCP_RELAY_CAPACITY_WAIT`: how many seconds `relay_acquire` waits when the host is at capacity, such as at
|
|
378
|
+
- `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.
|
|
349
379
|
- `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.
|
|
350
380
|
- `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.
|
|
351
381
|
- `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.
|
|
352
382
|
- `MCP_RELAY_SHUTDOWN_GRACE_MS`: how long a session end waits for an in-flight operation, and with `MCP_RELAY_ON_EXIT=release` for the guests' releases, before cancelling it; default 120000.
|
|
353
383
|
- `MCP_RELAY_PYTHON`: the Python 3 used for the registry lock; default `python3` on PATH.
|
|
354
384
|
- `VM_ENVIRONMENT_FILE`: a selected environment profile; it overrides the URL, state directory and registry above and binds the Tart store.
|
|
355
|
-
- Guest files go to `/var/tmp/<UTC-timestamp>-mcp-relay-<task
|
|
385
|
+
- Guest files go to `/var/tmp/<UTC-timestamp>-mcp-relay-<task>/` on a VM and to `<lease workspace>/work/mcp-relay-<task>/` on a durable machine, with the runtime in `receiver.mjs`, support in `support/` and work in `workspace/`.
|
|
356
386
|
|
|
357
387
|
## Development
|
|
358
388
|
|
|
@@ -364,9 +394,12 @@ npm run setup:dev -- /absolute/path/to/built/relay-driver
|
|
|
364
394
|
npm run check # build, typecheck, tests
|
|
365
395
|
```
|
|
366
396
|
|
|
367
|
-
Three tests need
|
|
368
|
-
|
|
369
|
-
|
|
397
|
+
Three tests need something outside this repository and skip with a message
|
|
398
|
+
when it is absent: the console fixture regeneration needs a historical
|
|
399
|
+
`../vm-service` checkout with the Python backend (or
|
|
400
|
+
`VM_SERVICE_PYTHON_BACKEND`); the environment parity test needs
|
|
401
|
+
machine-service's `machctl` (`MACHCTL`, `PATH`, or a release build in
|
|
402
|
+
`../machine-service/rust`) and `../pilot-images`; and the shared catalog text
|
|
370
403
|
corpus needs `../pilot-images`. The JPEG and WebP presentation fixtures in
|
|
371
404
|
`tests/fixtures/` were encoded once from the test's spatial PNG with a codec
|
|
372
405
|
outside this repository and are committed, because the core carries none.
|
|
@@ -379,7 +412,7 @@ npm run test:e2e
|
|
|
379
412
|
|
|
380
413
|
This runs `claude --print` with the plugin loaded from this checkout
|
|
381
414
|
(`--plugin-dir`), the model limited to the relay's tools, and the server pointed
|
|
382
|
-
at a loopback stand-in for
|
|
415
|
+
at a loopback stand-in for machine-service (`tests/e2e/fixture-service.ts`), which
|
|
383
416
|
keeps leases as records, runs the relay's own Node and transfer commands
|
|
384
417
|
locally, and fakes the desktop capture driver. Four cases run, each a separate
|
|
385
418
|
headless session: the status call (which also proves the server is pointed at
|
|
@@ -412,7 +445,7 @@ separate, explicit step.
|
|
|
412
445
|
|
|
413
446
|
Pushing the tag triggers
|
|
414
447
|
[`.github/workflows/release.yml`](.github/workflows/release.yml), which
|
|
415
|
-
rebuilds `
|
|
448
|
+
rebuilds `machctl`, checks the working build against a fresh one, and publishes
|
|
416
449
|
to npm using [trusted publishing](https://docs.npmjs.com/trusted-publishers)
|
|
417
450
|
(OIDC — no `NPM_TOKEN` secret involved), then creates the matching GitHub
|
|
418
451
|
release.
|
|
@@ -5,8 +5,9 @@ tools: mcp__plugin_mcp-relay_relay__relay_search, mcp__plugin_mcp-relay_relay__r
|
|
|
5
5
|
model: sonnet
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
Work in a dedicated fresh VM
|
|
9
|
-
|
|
8
|
+
Work in a dedicated fresh VM, or on a durable machine (a real Mac named with
|
|
9
|
+
`machine`), through the relay's MCP tools. Probe first to pick the image the
|
|
10
|
+
task needs, or use the durable machine the task names. Acquire one
|
|
10
11
|
guest for each machine the task needs, and declare every output you will bring
|
|
11
12
|
home as an extraction before any work. relay_acquire answers the guest's name,
|
|
12
13
|
`guest`; name it in every later call on that guest. Several guests may run at
|
|
@@ -35,5 +36,5 @@ watch.
|
|
|
35
36
|
Call relay_finish or relay_release explicitly for every guest before you
|
|
36
37
|
return; the session ending never finishes a guest. Report the verified package path, the
|
|
37
38
|
delivery result, the snapshot completeness and the execution outcome as
|
|
38
|
-
separate facts. Do not claim human review. Do not use
|
|
39
|
+
separate facts. Do not claim human review. Do not use machine-service or
|
|
39
40
|
relay-driver directly.
|
package/dist/build-info.json
CHANGED
|
@@ -954,32 +954,34 @@
|
|
|
954
954
|
"node_modules/zod/v4/mini/parse.js": "b87374f4e821d583f699d83e4b74ac59e4a5a782c510959187a0ba209145d76b",
|
|
955
955
|
"node_modules/zod/v4/mini/schemas.js": "5614339bbec6b9be13ed1809e1215fe44d78e99f5f0eee848c0bb3b25dc1c9b6",
|
|
956
956
|
"src/archive.ts": "469ca411558db5696c8790d8a7132108d6705d4316c5a31a149f7472ddbef0ec",
|
|
957
|
+
"src/capture-gate.ts": "6757d7329b62e5b093323eddc779ee13722a0da24ab659649a23a2e70c4fbd56",
|
|
957
958
|
"src/config.ts": "3fbc475596ec0a1b6122ea963bf2769420a8a2a0e62fda55e66018fb3a6d53b3",
|
|
958
959
|
"src/console.ts": "d8258173a24449c2a394289b14983b9575c5ce753ab267d4e13213f3abfcb72d",
|
|
959
|
-
"src/core.ts": "
|
|
960
|
-
"src/
|
|
960
|
+
"src/core.ts": "dd889fda6af982ab47b40b346e7fbc41a213b6d258d3d5fe56cd8c5373221159",
|
|
961
|
+
"src/discovery.ts": "80db010052e9a37a00c5f5c1bb525fc95d8026c68ef9cd307eab0e4ec1d48920",
|
|
962
|
+
"src/doctor.ts": "8249e9fa78b679e9ef7fd30f617bf07848961346101d3b64c42f779cfb042671",
|
|
961
963
|
"src/downloads.ts": "4f37b5bb4fac96f9260a3a87c83bacf715b9add5ae9926d3fe0994000c70a8dd",
|
|
962
|
-
"src/environment.ts": "
|
|
964
|
+
"src/environment.ts": "5770e966e49d78ae069614078c667f94e70074b150f83111049529ff613aa215",
|
|
963
965
|
"src/evidence-merge.ts": "2f2759e28e70595ef9284fec85e1d6082bf25e815d04f0a36a253c24bfb75110",
|
|
964
966
|
"src/guest/image-evidence.ts": "9c5daaed5b33b9912021a91fd79a2e6d5be42c75d37761772a3bd2645d20a55e",
|
|
965
967
|
"src/guest/receiver.ts": "92fc8d3bfe95ed56d43cfe5b46eb196034ade5e4e9f58ed202465531458f697d",
|
|
966
968
|
"src/image-presentation.ts": "64ca29a3444a04606cb783c81ac2d0f3136f9a9ac730ae9074156f0a63256c76",
|
|
967
969
|
"src/images.ts": "734a30ba34cd80ef0b5c3791232f13b170b06d6d74c4b843d39566d2e09136d0",
|
|
968
|
-
"src/
|
|
970
|
+
"src/machine-service.ts": "e6464c58882b9886af88e49645fdadb5beac46299dd358d9b022be942dcff0bb",
|
|
971
|
+
"src/manager.ts": "62fd73c86d66f0135f6fa718f6f307ce0c2b3dbb7fe9a3b95275219b54b2de4e",
|
|
969
972
|
"src/owner-lock.ts": "a99cbaba67b4aff0e646dc5d5967db4497ba6dbda83fb1838c55f0bf0f6e0367",
|
|
970
973
|
"src/package.ts": "a52ed791813922e3ace9144706ddde8313a67d8580a3acd54a0799de3ebe44d2",
|
|
971
974
|
"src/probe.ts": "40a123f725aad7c22fe63707dd2de99646cb1f307d7d660927e8ca2b973e9ce0",
|
|
972
975
|
"src/registry.ts": "87478f1ceef0f06df9b28c064a817383ff153bdadd70e6d58b4a7ed464f66146",
|
|
973
976
|
"src/review-data.ts": "2e873eb23612fd4502d84e65322006345f4e97bb679109b23dc4d26683200c19",
|
|
974
|
-
"src/schema.ts": "
|
|
977
|
+
"src/schema.ts": "7f68a85c9593fc2ad1455efd6e757c43f8ed591293fd820f1a08408db17c1912",
|
|
975
978
|
"src/search-diagnostics.ts": "cea037618c56f075d51155101ad1cc0314bfa67b174bdb070191e0ea5ea04679",
|
|
976
979
|
"src/search.ts": "8aaf544fcb27e7e018bd976e1ba7d3c70c047aeda3182b3dce91873a901a245e",
|
|
977
|
-
"src/server.ts": "
|
|
978
|
-
"src/surface.ts": "
|
|
979
|
-
"src/transfer.ts": "
|
|
980
|
-
"src/transport.ts": "
|
|
980
|
+
"src/server.ts": "bff4c09c29890aa62175ead36d9cfd6f8fa7334d2ee0929b51a0371d38c5df1c",
|
|
981
|
+
"src/surface.ts": "25681325cb01dfb04524bca8e0e5f3d4b4795d3db814384c7d1e9a8ec831eb16",
|
|
982
|
+
"src/transfer.ts": "f27d65c0b42f9933e6a7f950f56111b84c644e8739bab44805aebfb54d77e320",
|
|
983
|
+
"src/transport.ts": "35df20b321f52c4a371f1e29923e957e7c85d58001e2864f0fd13c2c2838945f",
|
|
981
984
|
"src/typebox.ts": "7f071fbc67548c7d3701272dabe88a217812e12e41dfad76974ff08169fa1a7e",
|
|
982
|
-
"src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da"
|
|
983
|
-
"src/vm-service.ts": "f2a6bfa910484f42aa264dbe02012379c82b093a71645b33e8a8ccd968f4634d"
|
|
985
|
+
"src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da"
|
|
984
986
|
}
|
|
985
987
|
}
|
package/dist/doctor.mjs
CHANGED
|
@@ -45,14 +45,15 @@ 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
|
-
|
|
50
|
+
import { createHash as createHash2 } from "node:crypto";
|
|
51
|
+
var MachineServiceError = class extends Error {
|
|
51
52
|
constructor(message, status, responseBody, options) {
|
|
52
53
|
super(message, options);
|
|
53
54
|
this.status = status;
|
|
54
55
|
this.responseBody = responseBody;
|
|
55
|
-
this.name = "
|
|
56
|
+
this.name = "MachineServiceError";
|
|
56
57
|
}
|
|
57
58
|
status;
|
|
58
59
|
responseBody;
|
|
@@ -60,7 +61,7 @@ var VmServiceError = class extends Error {
|
|
|
60
61
|
capacity = false;
|
|
61
62
|
};
|
|
62
63
|
function capacityRefusal(error) {
|
|
63
|
-
if (!(error instanceof
|
|
64
|
+
if (!(error instanceof MachineServiceError) || error.status !== 409 || !error.responseBody) return false;
|
|
64
65
|
let body;
|
|
65
66
|
try {
|
|
66
67
|
body = JSON.parse(error.responseBody);
|
|
@@ -69,11 +70,16 @@ function capacityRefusal(error) {
|
|
|
69
70
|
}
|
|
70
71
|
if (!body || typeof body !== "object") return false;
|
|
71
72
|
const { error: reason, outcome } = body;
|
|
72
|
-
return typeof reason === "string" &&
|
|
73
|
+
return typeof reason === "string" && /^(macOS VM limit reached|durable machine leased|durable machine unavailable)/.test(reason) && outcome !== "uncertain";
|
|
74
|
+
}
|
|
75
|
+
var SERVICE_NAME = "machine-service";
|
|
76
|
+
function expectMachineService(health, origin) {
|
|
77
|
+
if (health.service === SERVICE_NAME) return;
|
|
78
|
+
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.`);
|
|
73
79
|
}
|
|
74
|
-
var AcquireIndeterminateError = class extends
|
|
80
|
+
var AcquireIndeterminateError = class extends MachineServiceError {
|
|
75
81
|
constructor(purpose, cause) {
|
|
76
|
-
super(`Acquisition outcome unknown for purpose '${purpose}'; reconcile GET /
|
|
82
|
+
super(`Acquisition outcome unknown for purpose '${purpose}'; reconcile GET /machines before retrying or ending the enclosure`, void 0, void 0, { cause });
|
|
77
83
|
this.purpose = purpose;
|
|
78
84
|
this.name = "AcquireIndeterminateError";
|
|
79
85
|
}
|
|
@@ -86,11 +92,19 @@ function positive(value, label) {
|
|
|
86
92
|
function record(value) {
|
|
87
93
|
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
88
94
|
}
|
|
95
|
+
function named(value) {
|
|
96
|
+
const fields = value;
|
|
97
|
+
if (record(value) && fields.kind === "durable" && typeof fields.vm !== "string" && typeof fields.name === "string") fields.vm = fields.name;
|
|
98
|
+
return value;
|
|
99
|
+
}
|
|
89
100
|
function isLease(value) {
|
|
90
101
|
if (!record(value)) return false;
|
|
102
|
+
if (named(value).kind === "durable") {
|
|
103
|
+
return ["vm", "purpose", "lease_id", "workspace"].every((k) => typeof value[k] === "string" && value[k] !== "") && value.image === null && value.image_kind === null && value.state === "leased" && ["created_at", "ttl_expires_at"].every((k) => typeof value[k] === "number" && Number.isFinite(value[k]));
|
|
104
|
+
}
|
|
91
105
|
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
106
|
}
|
|
93
|
-
var
|
|
107
|
+
var MachineService = class {
|
|
94
108
|
baseUrl;
|
|
95
109
|
environment;
|
|
96
110
|
timeoutMs;
|
|
@@ -103,8 +117,8 @@ var VmService = class {
|
|
|
103
117
|
if (options.environment && url.origin !== new URL(options.environment.profile.vmServiceUrl).origin) throw new TypeError("Backend endpoint does not match the selected environment");
|
|
104
118
|
const host = url.hostname.replace(/^\[|\]$/g, "");
|
|
105
119
|
const loopback = host === "localhost" || host === "::1" || isIP(host) === 4 && host.startsWith("127.");
|
|
106
|
-
if (!loopback || !["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
|
|
107
|
-
throw new TypeError("
|
|
120
|
+
if (!loopback && !options.listed || !["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash || url.pathname !== "/") {
|
|
121
|
+
throw new TypeError("machine-service baseUrl must be a loopback HTTP(S) origin, or one Consul lists as machine-service, without credentials, path, query or fragment");
|
|
108
122
|
}
|
|
109
123
|
this.baseUrl = url.origin;
|
|
110
124
|
this.timeoutMs = positive(options.timeoutMs ?? 66e4, "timeoutMs");
|
|
@@ -114,8 +128,10 @@ var VmService = class {
|
|
|
114
128
|
health(options = {}) {
|
|
115
129
|
return this.request("/health", void 0, options);
|
|
116
130
|
}
|
|
117
|
-
list(options = {}) {
|
|
118
|
-
|
|
131
|
+
async list(options = {}) {
|
|
132
|
+
const list = await this.request("/machines", void 0, options);
|
|
133
|
+
if (record(list.machines)) Object.values(list.machines).forEach(named);
|
|
134
|
+
return list;
|
|
119
135
|
}
|
|
120
136
|
images(options = {}) {
|
|
121
137
|
return this.request("/images", void 0, options);
|
|
@@ -139,11 +155,11 @@ var VmService = class {
|
|
|
139
155
|
try {
|
|
140
156
|
return await this.request(path, body, options);
|
|
141
157
|
} catch (error) {
|
|
142
|
-
throw new
|
|
158
|
+
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
159
|
}
|
|
144
160
|
}
|
|
145
|
-
get(vm, options = {}) {
|
|
146
|
-
return this.request(this.path(vm), void 0, options);
|
|
161
|
+
async get(vm, options = {}) {
|
|
162
|
+
return named(await this.request(this.path(vm), void 0, options));
|
|
147
163
|
}
|
|
148
164
|
/**
|
|
149
165
|
* Cancellation before dispatch prevents allocation. Once dispatched we deliberately
|
|
@@ -158,12 +174,12 @@ var VmService = class {
|
|
|
158
174
|
const timeoutMs = positive(options.timeoutMs ?? this.acquireTimeoutMs, "timeoutMs");
|
|
159
175
|
try {
|
|
160
176
|
const lease = await this.request("/acquire", body, { timeoutMs });
|
|
161
|
-
if (!isLease(lease)) throw new
|
|
177
|
+
if (!isLease(lease)) throw new MachineServiceError("Invalid machine-service acquire response");
|
|
162
178
|
return lease;
|
|
163
179
|
} catch (error) {
|
|
164
|
-
const safeError = body.vnc ? new
|
|
165
|
-
if (safeError instanceof
|
|
166
|
-
if (error instanceof
|
|
180
|
+
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;
|
|
181
|
+
if (safeError instanceof MachineServiceError) safeError.capacity = capacityRefusal(error);
|
|
182
|
+
if (error instanceof MachineServiceError && error.status !== void 0 && error.status >= 400 && error.status < 500) throw safeError;
|
|
167
183
|
throw new AcquireIndeterminateError(body.purpose, safeError);
|
|
168
184
|
}
|
|
169
185
|
}
|
|
@@ -176,36 +192,76 @@ var VmService = class {
|
|
|
176
192
|
pull(vm, body, options = {}) {
|
|
177
193
|
return this.request(this.path(vm, "pull"), body, options);
|
|
178
194
|
}
|
|
179
|
-
heartbeat(vm, body = {}, options = {}) {
|
|
180
|
-
return this.request(this.path(vm, "heartbeat"), body, options);
|
|
195
|
+
async heartbeat(vm, body = {}, options = {}) {
|
|
196
|
+
return named(await this.request(this.path(vm, "heartbeat"), body, options));
|
|
181
197
|
}
|
|
182
198
|
release(vm, body = {}, options = {}) {
|
|
183
199
|
return this.request(this.path(vm, "release"), body, options);
|
|
184
200
|
}
|
|
201
|
+
/**
|
|
202
|
+
* Push one file as bytes, `PUT /machines/<name>/files` (FD-4): the instance
|
|
203
|
+
* checks the digest before it writes, so a client on another Mac needs no
|
|
204
|
+
* host path the instance could read (DC-31).
|
|
205
|
+
*/
|
|
206
|
+
async pushBytes(vm, body, options = {}) {
|
|
207
|
+
const sha256 = createHash2("sha256").update(body.bytes).digest("hex");
|
|
208
|
+
const response = await this.fetchBounded(this.filesPath(vm, body.remote_path, body.lease_id), { method: "PUT", headers: { "Content-Type": "application/octet-stream", "X-Content-SHA256": sha256 }, body: new Uint8Array(body.bytes) }, options, this.maxResponseBytes);
|
|
209
|
+
const answer = this.json(response.path, response.text);
|
|
210
|
+
if (answer.sha256 !== sha256 || answer.bytes !== body.bytes.length) throw new MachineServiceError(`machine-service ${response.path}: the instance stored ${answer.bytes} bytes with SHA-256 ${answer.sha256}, not what was sent`);
|
|
211
|
+
return answer;
|
|
212
|
+
}
|
|
213
|
+
/** Pull one file as bytes, `GET /machines/<name>/files`; refused unless the bytes match the digest the instance states (DC-31). */
|
|
214
|
+
async pullBytes(vm, body, options = {}) {
|
|
215
|
+
const response = await this.fetchBounded(this.filesPath(vm, body.remote_path, body.lease_id), { method: "GET" }, options, body.maxBytes);
|
|
216
|
+
if (response.contentType !== "application/octet-stream") throw new MachineServiceError(`machine-service ${response.path}: expected one file, got ${response.contentType ?? "no content type"}`);
|
|
217
|
+
const digest = createHash2("sha256").update(response.bytes).digest("hex");
|
|
218
|
+
if (!response.sha256 || digest !== response.sha256.toLowerCase()) throw new MachineServiceError(`machine-service ${response.path}: the bytes' SHA-256 ${digest} differs from the stated ${response.sha256 ?? "none"}`);
|
|
219
|
+
return response.bytes;
|
|
220
|
+
}
|
|
221
|
+
filesPath(vm, remote, lease_id) {
|
|
222
|
+
const query = new URLSearchParams({ ...lease_id ? { lease_id } : {}, path: remote });
|
|
223
|
+
return `${this.path(vm, "files")}?${query}`;
|
|
224
|
+
}
|
|
185
225
|
path(vm, action) {
|
|
186
226
|
if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(vm)) throw new TypeError("Invalid VM name");
|
|
187
|
-
return `/
|
|
227
|
+
return `/machines/${encodeURIComponent(vm)}${action ? `/${action}` : ""}`;
|
|
188
228
|
}
|
|
189
229
|
async request(path, body, options) {
|
|
230
|
+
const response = await this.fetchBounded(path, {
|
|
231
|
+
method: body === void 0 ? "GET" : "POST",
|
|
232
|
+
headers: body === void 0 ? {} : { "Content-Type": "application/json" },
|
|
233
|
+
...body === void 0 ? {} : { body: JSON.stringify(body) }
|
|
234
|
+
}, options, this.maxResponseBytes);
|
|
235
|
+
return this.json(path, response.text);
|
|
236
|
+
}
|
|
237
|
+
json(path, text) {
|
|
238
|
+
try {
|
|
239
|
+
return JSON.parse(text);
|
|
240
|
+
} catch (cause) {
|
|
241
|
+
throw new MachineServiceError(`machine-service ${path}: invalid JSON response`, void 0, void 0, { cause });
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
/** One request whose answer is read up to `maxBytes`; an error answer is read up to 4 KiB and thrown with its status. */
|
|
245
|
+
async fetchBounded(path, init, options, maxBytes) {
|
|
190
246
|
options.signal?.throwIfAborted();
|
|
191
247
|
const timeoutMs = positive(options.timeoutMs ?? this.timeoutMs, "timeoutMs");
|
|
192
248
|
const controller = new AbortController();
|
|
193
249
|
const abort = () => controller.abort(options.signal?.reason);
|
|
194
250
|
options.signal?.addEventListener("abort", abort, { once: true });
|
|
195
|
-
const timer = setTimeout(() => controller.abort(new
|
|
251
|
+
const timer = setTimeout(() => controller.abort(new MachineServiceError(`machine-service ${path} timed out after ${timeoutMs}ms`)), timeoutMs);
|
|
196
252
|
try {
|
|
197
253
|
const response = await fetch(`${this.baseUrl}${path}`, {
|
|
198
|
-
method:
|
|
199
|
-
headers: { ...
|
|
200
|
-
...body === void 0 ? {} : { body:
|
|
254
|
+
method: init.method,
|
|
255
|
+
headers: { ...init.headers, ...this.environment ? { "X-VM-Environment-Fingerprint": this.environment.identity.fingerprint } : {} },
|
|
256
|
+
...init.body === void 0 ? {} : { body: init.body },
|
|
201
257
|
signal: controller.signal,
|
|
202
258
|
redirect: "error"
|
|
203
|
-
// Do not let a
|
|
259
|
+
// Do not let a service redirect to another host.
|
|
204
260
|
});
|
|
205
261
|
const reader = response.body?.getReader();
|
|
206
262
|
const chunks = [];
|
|
207
263
|
let size = 0;
|
|
208
|
-
const bound = response.ok ?
|
|
264
|
+
const bound = response.ok ? maxBytes : Math.min(4096, maxBytes);
|
|
209
265
|
let truncated = false;
|
|
210
266
|
if (reader) {
|
|
211
267
|
try {
|
|
@@ -225,18 +281,14 @@ var VmService = class {
|
|
|
225
281
|
reader.releaseLock();
|
|
226
282
|
}
|
|
227
283
|
}
|
|
228
|
-
const
|
|
229
|
-
if (!response.ok) throw new
|
|
230
|
-
if (truncated) throw new
|
|
231
|
-
|
|
232
|
-
return JSON.parse(text);
|
|
233
|
-
} catch (cause) {
|
|
234
|
-
throw new VmServiceError(`vm-service ${path}: invalid JSON response`, void 0, void 0, { cause });
|
|
235
|
-
}
|
|
284
|
+
const bytes = Buffer.concat(chunks), text = bytes.toString("utf8");
|
|
285
|
+
if (!response.ok) throw new MachineServiceError(`machine-service ${path}: HTTP ${response.status}: ${text}${truncated ? " [truncated]" : ""}`, response.status, text);
|
|
286
|
+
if (truncated) throw new MachineServiceError(`machine-service ${path}: response exceeds ${bound} bytes`);
|
|
287
|
+
return { path, bytes, text, contentType: response.headers.get("content-type") ?? void 0, sha256: response.headers.get("x-content-sha256") ?? void 0 };
|
|
236
288
|
} catch (cause) {
|
|
237
289
|
if (controller.signal.aborted) throw controller.signal.reason;
|
|
238
|
-
if (cause instanceof
|
|
239
|
-
throw new
|
|
290
|
+
if (cause instanceof MachineServiceError) throw cause;
|
|
291
|
+
throw new MachineServiceError(`machine-service ${path}: request failed`, void 0, void 0, { cause });
|
|
240
292
|
} finally {
|
|
241
293
|
clearTimeout(timer);
|
|
242
294
|
options.signal?.removeEventListener("abort", abort);
|
|
@@ -256,12 +308,13 @@ import { isAbsolute as isAbsolute2, join as join2, normalize } from "node:path";
|
|
|
256
308
|
|
|
257
309
|
// src/environment.ts
|
|
258
310
|
import { accessSync, constants, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
|
|
259
|
-
import { createHash as
|
|
311
|
+
import { createHash as createHash3 } from "node:crypto";
|
|
260
312
|
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
|
|
261
313
|
import { homedir } from "node:os";
|
|
262
314
|
import { isIP as isIP2 } from "node:net";
|
|
263
|
-
var paths = ["imageRepository", "tartHome", "serviceStateDir", "imageStateDir", "relayStateDir", "
|
|
315
|
+
var paths = ["imageRepository", "tartHome", "serviceStateDir", "imageStateDir", "relayStateDir", "machctlPath", "tartPath"];
|
|
264
316
|
var mutable = ["tartHome", "serviceStateDir", "imageStateDir", "relayStateDir"];
|
|
317
|
+
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
318
|
function canonicalPath(value) {
|
|
266
319
|
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
320
|
let ancestor = resolve(value);
|
|
@@ -322,19 +375,20 @@ function loadEnvironment(path, env = process.env, home = env.HOME ?? homedir())
|
|
|
322
375
|
} else if (text[i] === "{" || text[i] === "[") depth++;
|
|
323
376
|
else if (text[i] === "}" || text[i] === "]") depth--;
|
|
324
377
|
}
|
|
378
|
+
if (raw && typeof raw === "object" && !Array.isArray(raw) && (raw.schemaVersion === 1 || Object.hasOwn(raw, "vmctlPath"))) throw new Error(LEGACY_PROFILE);
|
|
325
379
|
const fields = ["schemaVersion", "id", "vmServiceUrl", ...paths].sort();
|
|
326
380
|
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
381
|
const p = raw;
|
|
328
|
-
if (p.schemaVersion !==
|
|
329
|
-
const profile = { schemaVersion:
|
|
382
|
+
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");
|
|
383
|
+
const profile = { schemaVersion: 2, id: p.id, vmServiceUrl: endpoint(p.vmServiceUrl) };
|
|
330
384
|
for (const key of paths) profile[key] = canonicalPath(p[key]);
|
|
331
385
|
if (!statSync(profile.imageRepository).isDirectory() || !statSync(join(profile.imageRepository, "images")).isDirectory()) throw new Error("Selected imageRepository must contain images/");
|
|
332
|
-
for (const key of ["
|
|
386
|
+
for (const key of ["machctlPath", "tartPath"]) {
|
|
333
387
|
if (!statSync(profile[key]).isFile()) throw new Error(`${key} must be a regular executable file`);
|
|
334
388
|
accessSync(profile[key], constants.X_OK);
|
|
335
389
|
}
|
|
336
390
|
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"];
|
|
391
|
+
const names = ["machine-service", "vm-service", "pilot-images", "mcp-relay", "mcp-vm-relay"];
|
|
338
392
|
const defaults = [join(canonicalPath(home), ".tart"), ...names.map((n) => join(state, n)), ...names.map((n) => join(canonicalPath(home), ".local/state", n))].map(canonicalPath);
|
|
339
393
|
for (const key of mutable) {
|
|
340
394
|
const value = profile[key];
|
|
@@ -347,7 +401,7 @@ function loadEnvironment(path, env = process.env, home = env.HOME ?? homedir())
|
|
|
347
401
|
for (const other of mutable) if (key !== other && overlaps(value, profile[other])) throw new Error("Environment mutable roots must be disjoint");
|
|
348
402
|
}
|
|
349
403
|
const ordered = Object.fromEntries(Object.keys(profile).sort().map((k) => [k, profile[k]]));
|
|
350
|
-
const fingerprint =
|
|
404
|
+
const fingerprint = createHash3("sha256").update(JSON.stringify(ordered), "utf8").digest("hex");
|
|
351
405
|
const identity = Object.freeze({
|
|
352
406
|
id: profile.id,
|
|
353
407
|
fingerprint,
|
|
@@ -373,13 +427,13 @@ function environmentVariables(selected) {
|
|
|
373
427
|
VM_ENVIRONMENT_FINGERPRINT: selected.identity.fingerprint,
|
|
374
428
|
PILOT_REPO: p.imageRepository,
|
|
375
429
|
TART_HOME: p.tartHome,
|
|
376
|
-
|
|
430
|
+
MACHINE_SERVICE_STATE: p.serviceStateDir,
|
|
377
431
|
PILOT_IMAGES_STATE_DIR: p.imageStateDir,
|
|
378
432
|
VM_RELAY_STATE_DIR: p.relayStateDir,
|
|
379
433
|
VM_RELAY_URL: p.vmServiceUrl,
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
434
|
+
MACHINE_SERVICE_HOST: url.hostname.replace(/^\[|\]$/g, ""),
|
|
435
|
+
MACHINE_SERVICE_PORT: String(Number(p.vmServiceUrl.match(/:([0-9]+)$/)[1])),
|
|
436
|
+
MACHCTL: p.machctlPath,
|
|
383
437
|
TART: p.tartPath
|
|
384
438
|
};
|
|
385
439
|
}
|
|
@@ -744,7 +798,7 @@ async function installationReport(options = {}) {
|
|
|
744
798
|
return process.versions.node;
|
|
745
799
|
});
|
|
746
800
|
await check("host", async () => {
|
|
747
|
-
if (process.platform !== "darwin" || process.arch !== "arm64") throw Error("The supported local Tart/
|
|
801
|
+
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
802
|
return `${process.platform}/${process.arch}`;
|
|
749
803
|
});
|
|
750
804
|
await check("python", async () => {
|
|
@@ -777,15 +831,16 @@ async function installationReport(options = {}) {
|
|
|
777
831
|
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
832
|
return "Read-only local inventory available";
|
|
779
833
|
});
|
|
780
|
-
await check("
|
|
781
|
-
const vm = options.vm ?? new
|
|
834
|
+
await check("machine-service", async () => {
|
|
835
|
+
const vm = options.vm ?? new MachineService({ baseUrl: environment?.profile.vmServiceUrl ?? process.env.MCP_RELAY_URL, environment });
|
|
782
836
|
const health = await vm.health({ timeoutMs: 5e3 });
|
|
783
837
|
if (!health.ok) throw Error("Service health check failed");
|
|
784
|
-
|
|
838
|
+
expectMachineService(health, vm.baseUrl);
|
|
839
|
+
if (environment && !matchesEnvironment(health.environment, environment)) throw Error("machine-service environment identity mismatch");
|
|
785
840
|
const images = await vm.images({ timeoutMs: 5e3 });
|
|
786
841
|
await vm.list({ timeoutMs: 5e3 });
|
|
787
842
|
const available = Object.entries(images.images).filter(([, v]) => v.base_available).map(([k]) => k);
|
|
788
|
-
if (!available.length) throw Error("
|
|
843
|
+
if (!available.length) throw Error("machine-service is running but has no available golden images. Provision a supported image in the backend.");
|
|
789
844
|
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
845
|
});
|
|
791
846
|
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." };
|