@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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-relay",
3
- "version": "0.15.0",
3
+ "version": "0.17.0",
4
4
  "description": "Runs an agent's code on fresh, isolated VMs, several at once, each run recorded with evidence",
5
5
  "author": {
6
6
  "name": "WeZZard"
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, for any work
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, targets physical machines, records video, or attaches to existing
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 vm-service client, the registry with its OS-level lock,
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 vm-service TTL is the backstop |
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
- [vm-service](https://github.com/WeZZard/vm-service) and prepared guest images.
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 vm-service guest-sharing backend and its
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 VM service origin and the selected environment. `active` is false when no guest's lease is being renewed. |
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 vm-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.
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 vm-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.
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 that binds a loopback vm-service
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 vm-service
307
- defines, so its relay entries keep the `VM_RELAY_STATE_DIR` and
308
- `VM_RELAY_URL` names and the three runtimes agree; this server reads its own
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 vm-service reaper is the final backstop for process death.
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 vm-service origin, default `http://localhost:6240`. Non-loopback servers, redirects and physical targets are refused.
346
- - `MCP_RELAY_GUEST_NETWORK`: the network every guest is acquired on, `nat` (the default) or `internet`. With `internet`, vm-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 vm-service that cannot give `internet` refuses the acquisition with its own reason, never falling back to `nat`.
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 vm-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.
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>/`, with the runtime in `receiver.mjs`, support in `support/` and work in `workspace/`.
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 a sibling checkout beside this repository and skip with a
368
- message when it is absent: the console fixture regeneration and the
369
- environment parity test need `../vm-service`, and the shared catalog text
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 vm-service (`tests/e2e/fixture-service.ts`), which
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 `vmctl`, checks the working build against a fresh one, and publishes
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 through the relay's MCP tools. Probe first to
9
- pick the image the task needs. Acquire one
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 vm-service or
39
+ separate facts. Do not claim human review. Do not use machine-service or
39
40
  relay-driver directly.
@@ -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": "ea656be559f2a82cc76ab95a4c0f142df4d524fab35276d95aaa099ae537d38b",
960
- "src/doctor.ts": "7f509d7fd6c927a14e85110ad156efa879d9fa75e4e5f4af02b7f651cf66a8ab",
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": "04bc2a82eb56c1b0d77dabc9db4b0af9331f18c14398e7370e31a0081914f019",
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/manager.ts": "7e24a1eb66753698e6909406ef0a3dd1cef61ec096dc8301978f86214df976d5",
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": "0141b2befc75fafa1bbe9914b34eab374a1204ce34f44af19f2100153805baf8",
977
+ "src/schema.ts": "7f68a85c9593fc2ad1455efd6e757c43f8ed591293fd820f1a08408db17c1912",
975
978
  "src/search-diagnostics.ts": "cea037618c56f075d51155101ad1cc0314bfa67b174bdb070191e0ea5ea04679",
976
979
  "src/search.ts": "8aaf544fcb27e7e018bd976e1ba7d3c70c047aeda3182b3dce91873a901a245e",
977
- "src/server.ts": "c3256d27248140a1072a924796ba9b7f0edbbe9b5c72bcdeea02a46734aaf5cd",
978
- "src/surface.ts": "f7772fbafa613aaeba05e47d2def4975fb0ce75d1af067bde968f0e95775f81a",
979
- "src/transfer.ts": "009dfb72ebd41a5642ec02a48ab7b678bed75e5db8859acc15a45e7f0bd43462",
980
- "src/transport.ts": "08609fcf56ef9b60b867f7f86783c198b622f72e2b02f2562c5f1506ee1dc0bd",
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/vm-service.ts
48
+ // src/machine-service.ts
49
49
  import { isIP } from "node:net";
50
- var VmServiceError = class extends Error {
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 = "VmServiceError";
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 VmServiceError) || error.status !== 409 || !error.responseBody) return false;
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" && reason.startsWith("macOS VM limit reached") && outcome !== "uncertain";
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 VmServiceError {
80
+ var AcquireIndeterminateError = class extends MachineServiceError {
75
81
  constructor(purpose, cause) {
76
- super(`Acquisition outcome unknown for purpose '${purpose}'; reconcile GET /vms before retrying or ending the enclosure`, void 0, void 0, { cause });
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 VmService = class {
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("vm-service baseUrl must be a loopback HTTP(S) origin without credentials, path, query or fragment");
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
- return this.request("/vms", void 0, options);
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 VmServiceError(`Console API unavailable or request outcome unknown${error instanceof VmServiceError && error.status ? ` (HTTP ${error.status})` : ""}; resolve before another open`, error instanceof VmServiceError ? error.status : void 0);
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 VmServiceError("Invalid vm-service acquire response");
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 VmServiceError(`VNC acquisition refused or outcome unknown${error instanceof VmServiceError && error.status ? ` (HTTP ${error.status})` : ""}; inspect capabilities and reconcile ownership`, error instanceof VmServiceError ? error.status : void 0) : error;
165
- if (safeError instanceof VmServiceError) safeError.capacity = capacityRefusal(error);
166
- if (error instanceof VmServiceError && error.status !== void 0 && error.status >= 400 && error.status < 500) throw safeError;
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 `/vms/${encodeURIComponent(vm)}${action ? `/${action}` : ""}`;
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 VmServiceError(`vm-service ${path} timed out after ${timeoutMs}ms`)), timeoutMs);
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: body === void 0 ? "GET" : "POST",
199
- headers: { ...body === void 0 ? {} : { "Content-Type": "application/json" }, ...this.environment ? { "X-VM-Environment-Fingerprint": this.environment.identity.fingerprint } : {} },
200
- ...body === void 0 ? {} : { body: JSON.stringify(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 loopback service redirect to remote hosts.
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 ? this.maxResponseBytes : Math.min(4096, this.maxResponseBytes);
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 text = Buffer.concat(chunks).toString("utf8");
229
- if (!response.ok) throw new VmServiceError(`vm-service ${path}: HTTP ${response.status}: ${text}${truncated ? " [truncated]" : ""}`, response.status, text);
230
- if (truncated) throw new VmServiceError(`vm-service ${path}: response exceeds ${bound} bytes`);
231
- try {
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 VmServiceError) throw cause;
239
- throw new VmServiceError(`vm-service ${path}: request failed`, void 0, void 0, { cause });
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 createHash2 } from "node:crypto";
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", "vmctlPath", "tartPath"];
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 !== 1 || typeof p.id !== "string" || !/^[a-z0-9][a-z0-9-]{0,47}$/.test(p.id)) throw new Error("Invalid environment schemaVersion or id");
329
- const profile = { schemaVersion: 1, id: p.id, vmServiceUrl: endpoint(p.vmServiceUrl) };
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 ["vmctlPath", "tartPath"]) {
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 = createHash2("sha256").update(JSON.stringify(ordered), "utf8").digest("hex");
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
- VM_SERVICE_STATE: p.serviceStateDir,
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
- VM_SERVICE_HOST: url.hostname.replace(/^\[|\]$/g, ""),
381
- VM_SERVICE_PORT: String(Number(p.vmServiceUrl.match(/:([0-9]+)$/)[1])),
382
- VMCTL: p.vmctlPath,
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/vm-service backend requires an Apple-silicon Mac. Ubuntu is a guest, not a substitute host.");
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("vm-service", async () => {
781
- const vm = options.vm ?? new VmService({ baseUrl: environment?.profile.vmServiceUrl ?? process.env.MCP_RELAY_URL, environment });
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
- if (environment && !matchesEnvironment(health.environment, environment)) throw Error("VM service environment identity mismatch");
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("vm-service is running but has no available golden images. Provision a supported image in the backend.");
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." };