@wezzard/mcp-relay 0.18.0 → 0.20.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.18.0",
3
+ "version": "0.20.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
@@ -112,9 +112,14 @@ without a Claude Code plugin or pi package wrapper.
112
112
 
113
113
  ### Prerequisites
114
114
 
115
- Node 22+, Python 3 with `fcntl` for the registry lock, and for VM execution an
116
- Apple-silicon Mac with Tart, a running
117
- [machine-service](https://github.com/WeZZard/vm-service) (formerly vm-service) and prepared guest images.
115
+ Node 22+, Python 3 with `fcntl` for the registry lock, and a running
116
+ [machine-service](https://github.com/WeZZard/vm-service) (formerly vm-service) with prepared guest images.
117
+ The relay runs on macOS and on Ubuntu. Only a local Tart/machine-service
118
+ backend needs an Apple-silicon Mac with Tart; on any other host, such as
119
+ Ubuntu, the relay is a client of an instance on another host, and verifies a
120
+ VM's destruction in that instance's `/machines` inventory instead of a local
121
+ Tart inventory. Bonjour discovery uses `dns-sd` on macOS and Avahi's
122
+ `avahi-browse` on Linux, or the relay's own multicast query when Avahi is absent.
118
123
  Check readiness with `node dist/doctor.mjs`. It does not acquire a VM or
119
124
  establish guest UI readiness. Staging and runs assume no software in the guest
120
125
  but Node.js, which runs the relay's own guest code; `relay_stage` refuses an
@@ -301,10 +306,26 @@ Failed or uncertain launches retain ownership; resolve or cancel the attempt
301
306
  rather than replaying it. Console tests use mocked backends; no live viewer,
302
307
  installation or platform acceptance is claimed here.
303
308
 
309
+ ## Every instance
310
+
311
+ The relay asks every machine-service instance on the network, found as
312
+ `machctl list` finds them, so a Mac whose own instance offers nothing still
313
+ sees the Macs that host the VMs ([docs/instances.md](docs/instances.md)).
314
+
315
+ - `relay_search` names, for each installation, the instances that offer it,
316
+ each with its `machine_id` and its catalog generation, and lists every
317
+ instance asked; an instance that did not answer is listed as unreachable.
318
+ - `relay_probe` and `relay_acquisition_capabilities` answer per instance.
319
+ - `relay_acquire` with `image` chooses an instance that offers the image and
320
+ has capacity, says which and why in `chosen`, and passes a capacity refusal
321
+ to the next instance. Every later call on the guest goes to that instance.
322
+ - `instance` narrows any of these to one instance, by its name, a former name,
323
+ its `machine_id` or its origin. A selected environment asks only its own.
324
+
304
325
  ## Durable machines
305
326
 
306
327
  `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
328
+ a real Mac that machine-service exposes, such as `Mac-A`. Every other
308
329
  tool works on it as on a VM ([docs/durable-machines.md](docs/durable-machines.md)).
309
330
 
310
331
  - The relay finds the instance that owns the machine as `machctl list` does:
@@ -315,12 +336,20 @@ tool works on it as on a VM ([docs/durable-machines.md](docs/durable-machines.md
315
336
  instance found is used only once its `/health` confirms its ID.
316
337
  - Every call carries the lease's `lease_id`, files go as bytes, and the relay
317
338
  stages under the lease's workspace, which machine-service removes at release.
339
+ - When machine-service reports `machine_id`, the relay saves it and can resume
340
+ the same lease after the Mac is renamed or its address changes. Requests keep
341
+ using the name the lease was granted under. Older services keep the existing
342
+ name and origin checks.
343
+ - A durable 404 never proves release. The relay finds the owner again and
344
+ verifies that its machine record no longer names the lease. An unreachable
345
+ owner leaves the lease retained with guest state `unknown`.
318
346
  - Runs take snapshots only while the Mac's cua-driver daemon (`CuaDriver.app`,
319
347
  `com.trycua.driver`) holds Screen Recording, read with
320
348
  `cua-driver permissions status --json` in the lease. machine-service's own
321
349
  permissions are not read, and it needs no Screen Recording grant.
322
- - A durable machine is on the home network and not isolated from it, a CI job
323
- may share its desktop, and it has no console.
350
+ - A durable machine is on the home network and not isolated from it, and it has
351
+ no console. A CI job on it holds its lease like any other client, so it never
352
+ shares the desktop with a lease.
324
353
 
325
354
  ## Selected environments
326
355
 
@@ -355,8 +384,8 @@ needed. Diagnostic commands appear in the review data
355
384
  as command-only steps without screenshots. `finish` verifies the package before
356
385
  destroying the VM; a failed delivery removes only the derived files it created
357
386
  and retains the VM for a corrected attempt. Cleanup checks the read-only host
358
- Tart inventory (the selected one, when an environment is selected) before
359
- claiming destruction. Leases default to 4 hours, renewed 15 minutes at a
387
+ Tart inventory (the selected one, when an environment is selected; on a host
388
+ with no local Tart, the instance's `/machines` inventory) before claiming destruction. Leases default to 4 hours, renewed 15 minutes at a
360
389
  time up to that TTL; the machine-service reaper is the final backstop for process death.
361
390
 
362
391
  Relay evidence has no size limit (owner decision PS-D12): screenshots are
@@ -372,8 +401,8 @@ keeps the VM for a retry after space is freed.
372
401
 
373
402
  - `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.
374
403
  - `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.
375
- - `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 discovery finds it.
376
- - `MACHINE_SERVICE_DISCOVERY`: how durable machines' instances are found, `bonjour` (the default) or `consul`, as for machine-service and machctl.
404
+ - `MCP_RELAY_URL`: the loopback machine-service origin, default `http://localhost:6240`. Non-loopback servers and redirects are refused; an instance on another Mac is reached only when discovery finds it.
405
+ - `MACHINE_SERVICE_DISCOVERY`: how the other instances are found, `bonjour` (the default: `dns-sd -Z` on macOS, `avahi-browse` on Linux, else the relay's own multicast query) or `consul`, as for machine-service and machctl.
377
406
  - `CONSUL_HTTP_ADDR`: the Consul agent that lists machine-service instances, in Consul mode; default `http://127.0.0.1:8500`.
378
407
  - `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`.
379
408
  - `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.
@@ -396,13 +425,20 @@ npm run setup:dev -- /absolute/path/to/built/relay-driver
396
425
  npm run check # build, typecheck, tests
397
426
  ```
398
427
 
428
+ The tests start from an empty environment (`scripts/test.mjs`): nothing in
429
+ your shell, such as `VM_ENVIRONMENT_FILE`, `MCP_RELAY_URL`, `MACHCTL`, `TART`
430
+ or `TART_HOME`, reaches them, and a relay a test starts is refused the
431
+ installed instance's origin. Only variables named `MCP_RELAY_TEST_*` pass, as
432
+ the tests' own inputs. Run a single file the same way:
433
+ `node scripts/test.mjs tests/server.test.ts`.
434
+
399
435
  Three tests need something outside this repository and skip with a message
400
436
  when it is absent: the console fixture regeneration needs a historical
401
437
  `../vm-service` checkout with the Python backend (or
402
- `VM_SERVICE_PYTHON_BACKEND`); the environment parity test needs
403
- machine-service's `machctl` (`MACHCTL`, `PATH`, or a release build in
404
- `../machine-service/rust`) and `../pilot-images`; and the shared catalog text
405
- corpus needs `../pilot-images`. The JPEG and WebP presentation fixtures in
438
+ `MCP_RELAY_TEST_PYTHON_BACKEND`); the environment parity test needs a
439
+ `machctl` built from source (`MCP_RELAY_TEST_MACHCTL`, or a release build in
440
+ `../machine-service/rust`; never one on PATH) and `../pilot-images`; and the
441
+ shared catalog text corpus needs `../pilot-images`. The JPEG and WebP presentation fixtures in
406
442
  `tests/fixtures/` were encoded once from the test's spatial PNG with a codec
407
443
  outside this repository and are committed, because the core carries none.
408
444
 
@@ -422,8 +458,11 @@ the stand-in before anything is acquired), an invalid call refused by the
422
458
  contract, a full acquire, stage, exec, finish lifecycle with a verified package,
423
459
  and a lease abandoned when the session ends, which is retained with its renewal
424
460
  paused rather than released. What is checked is what happened on disk and at
425
- the service, not what the model said. The suite needs `claude` on PATH with an
426
- account and spends a few model turns per case, so it is not part of `npm test`.
461
+ the service, not what the model said. Each session has its own HOME and
462
+ `CLAUDE_CONFIG_DIR`, so only the plugin under test loads. The suite needs the
463
+ Claude Code executable named by `MCP_RELAY_TEST_CLAUDE` and a credential in
464
+ `MCP_RELAY_TEST_ANTHROPIC_API_KEY` or `MCP_RELAY_TEST_CLAUDE_CODE_OAUTH_TOKEN`,
465
+ and spends a few model turns per case, so it is not part of `npm test`.
427
466
 
428
467
  The relay-driver links are development-only. The tests run the manager, the
429
468
  guest programs and the shipped server against fixture HTTP services, fixture
package/dist/NOTICE.txt CHANGED
@@ -1 +1 @@
1
- This distribution includes compiled @wezzard/relay-driver-core, @wezzard/relay-driver-host-sdk and @wezzard/relay-driver-remote-runtime code (https://github.com/WeZZard/relay-driver), the Model Context Protocol TypeScript SDK, and Ajv with ajv-formats (MIT). See build-info.json for source hashes and versions. The relay implementation was inherited from pi-vm-relay (https://github.com/WeZZard/pi-vm-relay) at commit 8990123, synchronized with its implementation through commit 0d69fc7 before that project's retirement, and has been maintained here as mcp-relay's own implementation from then on.
1
+ This distribution includes compiled @wezzard/relay-driver-core, @wezzard/relay-driver-host-sdk and @wezzard/relay-driver-remote-runtime code (https://github.com/WeZZard/relay-driver), the Model Context Protocol TypeScript SDK, Ajv with ajv-formats, and the ws WebSocket library (MIT). See build-info.json for source hashes and versions. The relay implementation was inherited from pi-vm-relay (https://github.com/WeZZard/pi-vm-relay) at commit 8990123, synchronized with its implementation through commit 0d69fc7 before that project's retirement, and has been maintained here as mcp-relay's own implementation from then on.
@@ -799,6 +799,20 @@
799
799
  "node_modules/typebox/build/value/shared/union_priority_sort.mjs": "cd3beabc02d254660e6e9b4647f7b54706955d27ad6df8200de756248599b50e",
800
800
  "node_modules/typebox/build/value/shared/union_score_select.mjs": "48ac87f8b950b98655383ad35ef6027f5f13d75523d4c33de3cdfcc3d623af29",
801
801
  "node_modules/typebox/build/value/value.mjs": "4e2948390e27c53f0a63bcd4813cd7517daf1a9cb5719ec86751f81cacc0ac52",
802
+ "node_modules/ws/lib/buffer-util.js": "4e996b0c29f30bb094d836a2a563aceebaf3e8692a1e3d5bb4a01a233029732f",
803
+ "node_modules/ws/lib/constants.js": "391e823142b8b370e55a2fd32b022deaf03b8415c56000009674ebc86a0b4f86",
804
+ "node_modules/ws/lib/event-target.js": "c45d3c6e12d170c860c0c3f1a050aa0f864d9806632b609a1e607d675aba128c",
805
+ "node_modules/ws/lib/extension.js": "852564f0f6b460287043803eae732666fb5610f676874354fc89f06aa4e986ed",
806
+ "node_modules/ws/lib/limiter.js": "e0469d4b83f6ba764b15f80e1766b75c136fbff68f048f4c050f0b1c7f065f69",
807
+ "node_modules/ws/lib/permessage-deflate.js": "16a91536988a53c23047ee5882392068728a839a244178c3b09b8c54982f58b0",
808
+ "node_modules/ws/lib/receiver.js": "a6ada33c9a2d54eaf595824b821ea89ca2c6395f89aa06755c52142148274884",
809
+ "node_modules/ws/lib/sender.js": "b343e24310aeb924e713767fb7cd445bccf4f3cc3504ceb2c56ce76b89c1cf45",
810
+ "node_modules/ws/lib/stream.js": "a56fcb6e2b152097ee820b6f5410b1f71e59819b45d08d9f8bda588fe39070ec",
811
+ "node_modules/ws/lib/subprotocol.js": "be3f6323d6f549568577dcba9004c1479d95c65a7abb0fe0c582875b9fac0b7c",
812
+ "node_modules/ws/lib/validation.js": "41ce8e83d0d434132e1704895fedb91f6703a701b42d91c80954ab29b2845593",
813
+ "node_modules/ws/lib/websocket-server.js": "6d8dd89a841748c80445fd5fcdb5ba8005369b53cc3525135e11304c8b9c55e5",
814
+ "node_modules/ws/lib/websocket.js": "9b7bd84b9a95e5bfa66de2dd0ba21aa69ac21013d04c39db066acca66504618b",
815
+ "node_modules/ws/wrapper.mjs": "fe154662301fd558f935f9c217fccbe7a7dac02ff39e648a000589403ff27c7f",
802
816
  "node_modules/zod-to-json-schema/dist/esm/Options.js": "11bfc58fbf69f3044798d1871b10d1c11951bb51c1a35636ebfcad9c04c0a950",
803
817
  "node_modules/zod-to-json-schema/dist/esm/Refs.js": "cefaaa074df0750b62ae164cfe77818eb86ff54d220d9ae39da323af6bd8c845",
804
818
  "node_modules/zod-to-json-schema/dist/esm/errorMessages.js": "7ea991477cf69f1f096db2ebf1148cb1dfa3e2e25253cf6f15da3ab5cdbfa40c",
@@ -953,35 +967,37 @@
953
967
  "node_modules/zod/v4/mini/iso.js": "24acf58a401645baaab9846987e5387cdf7c9e659e2e0aa3b3b6b8ac5555a5ed",
954
968
  "node_modules/zod/v4/mini/parse.js": "b87374f4e821d583f699d83e4b74ac59e4a5a782c510959187a0ba209145d76b",
955
969
  "node_modules/zod/v4/mini/schemas.js": "5614339bbec6b9be13ed1809e1215fe44d78e99f5f0eee848c0bb3b25dc1c9b6",
956
- "src/archive.ts": "469ca411558db5696c8790d8a7132108d6705d4316c5a31a149f7472ddbef0ec",
970
+ "src/archive.ts": "1368e3fea858572f3b68932a2fe1a62186f82fce52f0f4c171f74e6dbb52c152",
957
971
  "src/capture-gate.ts": "6757d7329b62e5b093323eddc779ee13722a0da24ab659649a23a2e70c4fbd56",
958
- "src/config.ts": "3fbc475596ec0a1b6122ea963bf2769420a8a2a0e62fda55e66018fb3a6d53b3",
972
+ "src/config.ts": "74a8545f0bec0b13de6ac9ae9ba8f3a6cf1ebc9810ed03f8983365c1f43ecece",
959
973
  "src/console.ts": "d8258173a24449c2a394289b14983b9575c5ce753ab267d4e13213f3abfcb72d",
960
- "src/core.ts": "dd889fda6af982ab47b40b346e7fbc41a213b6d258d3d5fe56cd8c5373221159",
961
- "src/discovery.ts": "cd66b470615f7e2bf1d5d2cdf8065b6e0ec601a0929f7be063bc18bfcfbc342d",
962
- "src/doctor.ts": "8249e9fa78b679e9ef7fd30f617bf07848961346101d3b64c42f779cfb042671",
974
+ "src/core.ts": "49915615db2971ec7a503ecc956f0d7334fa3b63303ef18aa8f9410307ad195b",
975
+ "src/discovery.ts": "c3c3bdfecf2aa34c44532d504e92fcdb321dd2feca51f3f235d403c04c8dc99f",
976
+ "src/doctor.ts": "3d7ebd3214bceb6121446a5a50b42d96a7635ac8c5ea6240cc9cb33f34ab1912",
963
977
  "src/downloads.ts": "4f37b5bb4fac96f9260a3a87c83bacf715b9add5ae9926d3fe0994000c70a8dd",
964
978
  "src/environment.ts": "5770e966e49d78ae069614078c667f94e70074b150f83111049529ff613aa215",
965
979
  "src/evidence-merge.ts": "2f2759e28e70595ef9284fec85e1d6082bf25e815d04f0a36a253c24bfb75110",
966
- "src/guest/image-evidence.ts": "9c5daaed5b33b9912021a91fd79a2e6d5be42c75d37761772a3bd2645d20a55e",
967
- "src/guest/receiver.ts": "92fc8d3bfe95ed56d43cfe5b46eb196034ade5e4e9f58ed202465531458f697d",
980
+ "src/guest/image-evidence.ts": "807cc35aa2c4cf06ee7ebfaa336bc5e293ce2660da80b3443f5ed1a1c9af71a5",
981
+ "src/guest/receiver.ts": "b8a5b26a1079dbf34193245215f249dd95c7dbdffe5aacd6aeb603aa77c94afe",
968
982
  "src/image-presentation.ts": "64ca29a3444a04606cb783c81ac2d0f3136f9a9ac730ae9074156f0a63256c76",
969
983
  "src/images.ts": "415bfb37966a60ef3e407236295b9aeeb314f7fb33de55a6ada512cff6661908",
970
- "src/machine-service.ts": "1f7c63d295b2551728f975451bd1ab29a57cf4cab9f16510b7e3fcd1a6160205",
971
- "src/manager.ts": "7bbff05dd7d3c3c98f2d71e72834e1e08b0c96a963fb76876895537d75436749",
972
- "src/mdns.ts": "b85df92dfe3cd0807725a3115ecfdd21d1530a98528b6a55454370d6e4baf98c",
984
+ "src/machine-service.ts": "65c093a7f78203d89a75939c49f33efba3b742edca6c770f7307b213ae59c625",
985
+ "src/manager.ts": "637c4b1505e920fe323cf18dc2ceb5a70a637d148a500d0a6bea51a37e45e2ba",
986
+ "src/mdns.ts": "d81886a6004b01490bb5b40ad81b9a8944bcee80945b5b1c346307c188515d44",
973
987
  "src/owner-lock.ts": "a99cbaba67b4aff0e646dc5d5967db4497ba6dbda83fb1838c55f0bf0f6e0367",
974
988
  "src/package.ts": "a52ed791813922e3ace9144706ddde8313a67d8580a3acd54a0799de3ebe44d2",
975
989
  "src/probe.ts": "40a123f725aad7c22fe63707dd2de99646cb1f307d7d660927e8ca2b973e9ce0",
976
990
  "src/registry.ts": "87478f1ceef0f06df9b28c064a817383ff153bdadd70e6d58b4a7ed464f66146",
991
+ "src/relay-client.ts": "7e66223599c3fb7bf1061176f68c8755035048821fc4ce0a04dc31083882ef38",
992
+ "src/relay-session.ts": "b88942c95738f896e1fb7be6213fb6a849baa23c4dcb8bef39474b5a11a0a604",
977
993
  "src/review-data.ts": "2e873eb23612fd4502d84e65322006345f4e97bb679109b23dc4d26683200c19",
978
- "src/schema.ts": "7f68a85c9593fc2ad1455efd6e757c43f8ed591293fd820f1a08408db17c1912",
994
+ "src/schema.ts": "00cf26a824569f4ccaa1756f838db13f7859b13eb15ce8140832299352d093ef",
979
995
  "src/search-diagnostics.ts": "cea037618c56f075d51155101ad1cc0314bfa67b174bdb070191e0ea5ea04679",
980
- "src/search.ts": "8aaf544fcb27e7e018bd976e1ba7d3c70c047aeda3182b3dce91873a901a245e",
981
- "src/server.ts": "bff4c09c29890aa62175ead36d9cfd6f8fa7334d2ee0929b51a0371d38c5df1c",
982
- "src/surface.ts": "25681325cb01dfb04524bca8e0e5f3d4b4795d3db814384c7d1e9a8ec831eb16",
983
- "src/transfer.ts": "f27d65c0b42f9933e6a7f950f56111b84c644e8739bab44805aebfb54d77e320",
984
- "src/transport.ts": "35df20b321f52c4a371f1e29923e957e7c85d58001e2864f0fd13c2c2838945f",
996
+ "src/search.ts": "d131e439525d283e0585904622c8d2ecb00708f9775f419256ffd28f7b2d32a2",
997
+ "src/server.ts": "d279f5dfb27074609b108cbf605e4ed45c1b21c3a86868ff68b9dd9b7beb269a",
998
+ "src/surface.ts": "41c7f7e7d422611fec56b56f82145ec584885c023108e69c3075e58f73b6230f",
999
+ "src/transfer.ts": "f7a7aba3dca7821e4777e8560b1710ff13875fbf455e24da24f9c18eeb447a52",
1000
+ "src/transport.ts": "4a197433f229bf5c9fb324243694aba6bbd3cd79b41922d887cff7e651a0276b",
985
1001
  "src/typebox.ts": "7f071fbc67548c7d3701272dabe88a217812e12e41dfad76974ff08169fa1a7e",
986
1002
  "src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da"
987
1003
  }