@wezzard/mcp-relay 0.0.0-stage → 0.14.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.
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "mcp-relay",
3
+ "description": "The mcp-relay Claude Code plugin",
4
+ "owner": {
5
+ "name": "WeZZard"
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "mcp-relay",
10
+ "source": "./",
11
+ "description": "The mcp-relay MCP server: runs an agent's code on fresh, isolated VMs, several at once, each run recorded with evidence"
12
+ }
13
+ ]
14
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "mcp-relay",
3
+ "version": "0.14.0",
4
+ "description": "Runs an agent's code on fresh, isolated VMs, several at once, each run recorded with evidence",
5
+ "author": {
6
+ "name": "WeZZard"
7
+ },
8
+ "repository": "https://github.com/WeZZard/mcp-relay"
9
+ }
package/.mcp.json ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "mcpServers": {
3
+ "relay": {
4
+ "type": "stdio",
5
+ "command": "node",
6
+ "args": ["${CLAUDE_PLUGIN_ROOT}/dist/server.mjs"],
7
+ "env": { "MCP_RELAY_PROJECT": "${CLAUDE_PROJECT_DIR}" }
8
+ }
9
+ }
10
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 WeZZard
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,422 @@
1
- # Temporary Holding Version
1
+ # mcp-relay
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The Model Context Protocol front end of the VM relay, packaged as a Claude Code
4
+ plugin and as a pi package. [pi-vm-relay](https://github.com/WeZZard/pi-vm-relay),
5
+ which gave pi a native `relay` tool directly, is retired; mcp-relay replaces
6
+ it for both Claude Code and pi, the latter loaded through `pi-mcp-adapter`. It
7
+ is an MCP server: fifteen `relay_*` tools, each with its own schema, title
8
+ and annotations, and the server's `instructions`. The user command, status,
9
+ ships as one small command file per host (see "Commands"). There is no skill and no hook. Together they offer recorded,
10
+ snapshot-evidenced commands and 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.
15
+
16
+ The project was named mcp-vm-relay before v0.12.0. The npm package is now
17
+ `@wezzard/mcp-relay`, the plugin and its marketplace are `mcp-relay`, and every
18
+ `MCP_VM_RELAY_*` variable is now `MCP_RELAY_*`; the old names are not read. The
19
+ default state directory moved with the name, so finish or release a lease the
20
+ old relay owns before upgrading.
21
+
22
+ ## How it is built
23
+
24
+ The relay implementation lives in this repository: the manager
25
+ (`src/manager.ts`), the vm-service client, the registry with its OS-level lock,
26
+ the guest transfer and transport, the evidence package and its state merge, the
27
+ selected-environment profile, the console and saved-image contracts, the strict
28
+ tool contract (`src/schema.ts`), the action dispatch and bounded result
29
+ rendering (`src/surface.ts`), and the guest program, the receiver
30
+ (`src/guest/receiver.ts`). It was inherited from
31
+ [pi-vm-relay](https://github.com/WeZZard/pi-vm-relay) at commit 8990123,
32
+ synchronized with its implementation through commit 0d69fc7 before that
33
+ project's retirement, and is maintained here as mcp-relay's own
34
+ implementation from then on. `src/server.ts` binds the core to MCP over
35
+ standard input and output.
36
+
37
+ The committed `dist/` holds `server.mjs` (the MCP server with the core bundled
38
+ in), the guest bundle the manager stages (`receiver.mjs`) and the doctor. Compiled [relay-driver](https://github.com/WeZZard/relay-driver)
39
+ code, the recorded-execution and evidence substrate, is bundled with hashes and
40
+ provenance in `dist/build-info.json`. Consumers load `dist/`; no build, SDK
41
+ checkout or network fetch happens at install time.
42
+
43
+ The Claude Code plugin and pi both reach this same server as plain MCP: pi
44
+ through `pi-mcp-adapter` (see "Use with pi" below), Claude Code by starting it
45
+ directly. Every tool's identity, schema and contract are shared; the plugin
46
+ adds nothing Claude-Code-specific beyond the marketplace packaging and the
47
+ `vm-relay-operator` agent definition.
48
+
49
+ | In pi-vm-relay (retired, native pi extension) | Here (MCP server) |
50
+ |---|---|
51
+ | a registered `relay` tool with thirteen actions | fifteen `relay_*` MCP tools from the server `relay`, each with its own schema, title and annotations |
52
+ | doctrine injected before each agent turn | the server's MCP `instructions`, plus a compact version in the `relay_probe` and `relay_acquire` descriptions for clients that do not surface `instructions` |
53
+ | `/relay-status` command | `/mcp-relay-status` in pi, `/mcp-relay:status` in Claude Code; it asks the assistant to call `relay_status` |
54
+ | 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
+ | 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 |
57
+ | 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
+
59
+ ## Install
60
+
61
+ ### Use with Claude Code
62
+
63
+ Try it from a checkout:
64
+
65
+ ```sh
66
+ claude --plugin-dir /path/to/mcp-relay
67
+ ```
68
+
69
+ Or add this repository as a marketplace and install the plugin from it:
70
+
71
+ ```
72
+ /plugin marketplace add WeZZard/mcp-relay
73
+ /plugin install mcp-relay@mcp-relay
74
+ ```
75
+
76
+ Once loaded, the model sees the fifteen tools as
77
+ `mcp__plugin_mcp-relay_relay__relay_search`,
78
+ `mcp__plugin_mcp-relay_relay__relay_probe`, and so on through
79
+ `mcp__plugin_mcp-relay_relay__relay_status` (see "The tools" below for
80
+ the full table). The `vm-relay-operator` agent definition allows them by those
81
+ names. The server can also be configured directly in a project's `.mcp.json`
82
+ with `node /path/to/mcp-relay/dist/server.mjs`, in which case the tools are
83
+ `mcp__relay__relay_search` and so on.
84
+
85
+ ### Use with pi
86
+
87
+ ```sh
88
+ pi install npm:@wezzard/mcp-relay
89
+ ```
90
+
91
+ This needs `pi-mcp-adapter` installed. The tools appear as `relay_search`,
92
+ `relay_probe`, and so on through `relay_status`, with no host-specific
93
+ prefix (`pi-mcp.json` sets `toolPrefix: "none"`). The package also
94
+ ships a pi prompt template for the command, `/mcp-relay-status`.
95
+
96
+ ### Use with npx
97
+
98
+ ```sh
99
+ npx -y @wezzard/mcp-relay
100
+ ```
101
+
102
+ This runs the MCP server directly on stdio, for a client that speaks MCP
103
+ without a Claude Code plugin or pi package wrapper.
104
+
105
+ ### Prerequisites
106
+
107
+ Node 22+, Python 3 with `fcntl` for the registry lock, and for VM execution an
108
+ Apple-silicon Mac with Tart, a running
109
+ [vm-service](https://github.com/WeZZard/vm-service) and prepared guest images.
110
+ Check readiness with `node dist/doctor.mjs`. It does not acquire a VM or
111
+ establish guest UI readiness. Staging and runs assume no software in the guest
112
+ but Node.js, which runs the relay's own guest code; `relay_stage` refuses an
113
+ image without it. A run takes before and after snapshots only when the image
114
+ lists capture software, cua-driver (catalog ids `bundle:com.trycua.driver` and
115
+ `dpkg:cua-driver`); otherwise its record has no snapshots, and that is not a
116
+ gap. Snapshots need cua-driver with capture permission; on Linux, native X11
117
+ and `serve --no-overlay`. `relay_script` runs JavaScript with the guest's
118
+ Node.js, TypeScript with `tsx` and Python with `python3`, each from the guest's
119
+ `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
121
+ guest preparation; see `docs/console.md` here.
122
+
123
+ ## The tools
124
+
125
+ Each tool's `inputSchema` is a plain object with no root `anyOf`/`oneOf`/`allOf`
126
+ and no `action` field, derived directly from the strict per-action contract in
127
+ `src/schema.ts` (nested unions inside a property, such as `relay_image`'s
128
+ `target`, are unaffected). A call is mapped back to that contract's shape and
129
+ dispatched exactly as the retired single `relay` tool was, so behaviour,
130
+ results, image blocks and `isError` semantics are unchanged from before this
131
+ split. Two tools run anything in a guest: `relay_command` runs one command, and
132
+ `relay_script` runs a JavaScript, TypeScript or Python script, given inline or
133
+ as a project file. Both take the optional `reason`, `step`, `snapshots` and
134
+ `timeoutMs`, and their evidence is automatic: see "Runs" below.
135
+
136
+ | Tool | Title | Replaces (`action`, `kind`) | Purpose |
137
+ |---|---|---|---|
138
+ | `relay_search` | Search installed applications | `search` | Find installed applications from image inventories by name and optional OS. |
139
+ | `relay_probe` | Probe host and guest readiness | `probe` | Default `scope: "host"` reports host facts, service availability and every guest the session holds, with its state. `scope: "guest"` with `guest` checks Node.js, which staging requires, and reports as facts whether each `relay_script` language's runtime runs (`node`, `tsx`, `python3`), the software the image lists in the catalog and whether runs take snapshots, on that guest, without installing, starting or claiming capture readiness. |
140
+ | `relay_acquisition_capabilities` | Read acquisition capabilities | `acquisition-capabilities` | Read versioned acquisition options (VNC backends) without allocation or ownership recovery. |
141
+ | `relay_acquire` | Acquire a VM | `acquire` | Register the task, acquire a fresh VM, a guest, on the network `MCP_RELAY_GUEST_NETWORK` names and start its heartbeat; declare outputs before work. Answers `guest`, the guest's name in the session, which every later call on it names. Optional `vnc` prepares sharing without opening a viewer. |
142
+ | `relay_stage` | Stage the guest runtime | `stage` | Push and hash-check the runtime, support files and an opt-in workspace, all from the project folder. Needs only Node.js in the guest, and reports whether runs take snapshots (only when the image lists cua-driver). Failed staging can be retried; a staged runtime accepts corrected executable paths; `resetRecording: true` archives the recording and starts a new one on the same VM. |
143
+ | `relay_command` | Run a guest command | `run`, `exec` | One recorded guest command (`argv`). `diagnostic: true` records command diagnosis or repair without screenshot evidence, including before staging. Was `relay_exec`. |
144
+ | `relay_script` | Run a guest script | `run`, `script` | One recorded guest script in `language` (`javascript`, `typescript` or `python`). `inline: true` takes the script as `code`, up to 1 MiB (was `relay_code`); `inline: false` takes `localPath`, a file in the project folder (was `relay_script`). |
145
+ | `relay_image` | Retrieve a saved image | `image` | Retrieve one saved display image, declared application image or immutable image reference without input, capture, directory export or acquisition. |
146
+ | `relay_extract` | Extract declared outputs | `extract` | Pull only declared files or directories with source and host checksum verification. |
147
+ | `relay_finish` | Finish and deliver evidence | `finish` | Extract the guest's declared outputs, deliver and verify its snapshot package, destroy its VM and unregister it; the session's other guests keep running. |
148
+ | `relay_release` | Release the VM | `release` | Retain the guest's available evidence and abandon or destroy its VM; the other guests keep running. When this session holds no guest, the result is an error that says nothing was released. |
149
+ | `relay_console_resolve` | Resolve console status | `console-resolve` | Resolve non-secret console status for the guest's lease and environment. |
150
+ | `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
+ | `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. |
153
+
154
+ `readOnlyHint`/`idempotentHint` are true for `relay_search`, `relay_probe`,
155
+ `relay_acquisition_capabilities`, `relay_console_resolve`, `relay_image` and
156
+ `relay_status`; `destructiveHint` is true only for `relay_finish` and
157
+ `relay_release`, which destroy a guest's VM; `openWorldHint` is true only for the
158
+ two run tools, whose guest code may reach the network.
159
+
160
+ `relay_exec`, `relay_code`, `relay_run`, `relay_gate` and `relay_tools` are
161
+ gone (DC-23, `docs/guest-code-runs.md` §10). `relay_exec` is `relay_command`,
162
+ and `relay_code` is `relay_script` with `inline: true`. In place of
163
+ `relay_run`'s forwarded MCP tool calls, a script drives cua-driver, Playwright
164
+ or Chrome DevTools through their own libraries or command lines, as the image
165
+ lists them; the relay no longer stages MCP servers in the guest.
166
+
167
+ A run's result carries the execution identity and outcome, the derived step
168
+ record, and, when the snapshot plan captured the after phase and delivery
169
+ succeeded, the saved after-image as an MCP image content block. A command's
170
+ result also carries the guest's bounded standard output and error. The full
171
+ receipt stays in the evidence package.
172
+
173
+ ## Commands
174
+
175
+ The command asks the assistant to call one relay tool and report the answer.
176
+ It changes nothing itself.
177
+
178
+ | Command in pi | Command in Claude Code | Arguments | Purpose |
179
+ |---|---|---|---|
180
+ | `/mcp-relay-status` | `/mcp-relay:status` | none | Calls `relay_status` and reports this session's guests and their leases as they are. Read-only. |
181
+
182
+ It is not an MCP prompt. pi's MCP adapter can only name a prompt
183
+ `/mcp__<package>__<server>__<prompt>`, so each host gets its own command file
184
+ instead: pi prompt templates in `pi-prompts/` (listed in `package.json` under
185
+ `pi.prompts`) and Claude Code plugin commands in `commands/`. Both are
186
+ generated by `npm run build` from `scripts/host-commands.mjs`; do not edit them
187
+ by hand. CI and the release workflow check the packed tarball with
188
+ `scripts/verify-package.mjs`: the generated files must match their source, pi's
189
+ glob must select exactly the one template, and the packed server must start
190
+ without the prompts capability. The release publishes and attaches the same
191
+ tarball it checked.
192
+
193
+ ## Ownership, failure and recovery
194
+
195
+ - One server session holds several guests at once, up to `MCP_RELAY_MAX_GUESTS` (4 by default). `relay_acquire` names each guest, such as `login-test-1`, and every tool that acts on a guest takes that name as `guest`. Each guest keeps its own lease and heartbeat, its own evidence folder under `relay-evidence/`, its own background downloads, owner lock and registry row, and its own finish or release; finishing or releasing one leaves the others running. Calls on different guests run at the same time; calls on one guest keep their order. An acquisition beyond the limit is refused with the names of the guests held; the backend's own limits, such as two macOS VMs per host, still hold. An acquisition the host refuses for capacity waits for it, up to `MCP_RELAY_CAPACITY_WAIT`, then refuses with the backend's reason and the time waited; a waiting guest counts against the limit, and the backend's other refusals pass through at once.
196
+ - An operation failure retains the VM so the agent can inspect, repair and submit a new operation. Failed and uncertain operations are never automatically replayed.
197
+ - Use `finish` to deliver evidence and release, or `release` to abandon explicitly. A declared output that was never produced is recorded as incomplete (`incompleteExtractions`) rather than failing `finish`. A failed delivery retains the VM; a release failure retains ownership until destruction is verified.
198
+ - When the session ends (the client closes the server's standard input, a write to its standard output fails, it is signalled with SIGTERM, SIGINT or SIGHUP, or the process that started it goes away), `MCP_RELAY_ON_EXIT` says what happens to the guests. With `release`, the relay releases every guest the session holds through its own release path, keeping the evidence the host can still pull, then exits; an operation already in flight completes first, all within the shutdown grace period, after which a guest still held is released directly in one bounded attempt. A guest whose release fails keeps its record and stops renewing, so its lease ends within its last 15-minute window. With `pause`, the default, the relay renews each guest's lease once for the rest of its TTL, then renewal pauses and the recording detaches; no VM is destroyed and is retained until its TTL for an explicit finish or release. A `finish` or `release` already in flight completes first, for up to the shutdown grace period; after that the operation is cancelled and renewal pauses without it. The backend TTL and grace period handle abandoned leases. Status reports the last confirmed expiration time.
199
+ - While the session is live, the relay tracks the lease's own deadline (its start plus `ttlHours`) and renews 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.
200
+ - A restarted server with the same `MCP_RELAY_SESSION` reconciles each guest's durable ownership and reattaches its recording session without replaying prior work; every guest keeps its name. A session state written by a relay before several guests is restored as one guest named from its task. Context compaction does not reset VM state; `probe` reports the owned state without relying on earlier messages.
201
+ - A run tool's `timeoutMs` defaults to 120,000 ms and accepts integers up to 3,600,000 ms. It bounds command execution, not the snapshot delay or the lease lifetime. A timeout reports confirmed termination or uncertainty and keeps the VM available.
202
+ - `relay_command` with `diagnostic: true` records command diagnosis or repair without screenshots, for explicitly requested diagnosis when capture is unavailable. Before staging it runs through vm-service in the guest's default directory; after staging in the recording workspace. It cannot join a snapshot group and is not visual verification.
203
+ - After diagnosing damaged recording state, `relay_stage` with `resetRecording: true` archives the old recording and starts a new recording session in the same VM. An existing receiver lock refuses the reset until its operation is reconciled. Prior evidence paths remain in the owned status.
204
+
205
+ ## Runs
206
+
207
+ `relay_command` runs one command and `relay_script` one script, each as one
208
+ recorded operation:
209
+
210
+ ```json
211
+ {"guest":"login-test-1","argv":["/usr/bin/xdg-open","https://example.com"]}
212
+ {"guest":"login-test-1","language":"python","inline":true,"code":"import subprocess\nprint(subprocess.run(['cua-driver','call','list_apps'],capture_output=True,text=True).stdout)"}
213
+ {"guest":"login-test-1","language":"typescript","inline":false,"localPath":"checks/login.ts"}
214
+ ```
215
+
216
+ - **Evidence is automatic.** Every run is admitted by the guest receiver,
217
+ journaled, and, when the image lists cua-driver, bracketed by a before and an
218
+ after display snapshot. The step record is derived from the call: the title
219
+ is the command (`exec <argv>`), `code (<language>)` or `script <file>`, and
220
+ the expected result is "Exits with status 0". `reason`, `step` and
221
+ `snapshots` are optional overrides; the default wait before the
222
+ after-snapshot is 500 ms.
223
+ - **Scripts.** A `relay_script` with `inline: true` streams its `code` to the
224
+ guest with its hash; with `inline: false` its `localPath`, a file in the
225
+ project folder, is pushed hash-checked. The script runs in the staged
226
+ workspace: JavaScript with the guest's Node.js, TypeScript with `tsx`,
227
+ Python with `python3`. A call that gives `code` and `localPath` other than
228
+ as `inline` names is refused before anything reaches the guest.
229
+ - **One interaction per run.** A run is one recorded operation; consecutive
230
+ keystrokes may form an explicit text group with `snapshots.group`. A script
231
+ that drives several interactions records them as one step.
232
+ - **Outcomes.** A refused, uncertain or nonzero run is an error result and
233
+ keeps the VM. Nothing is ever replayed.
234
+
235
+ ## Saved images
236
+
237
+ A run tool names its saved after-image whenever the snapshot plan captures that
238
+ phase: a standalone event or a text group's last event. The result does not
239
+ wait for the image. Its `imageDelivery` is `pending` with the image identity
240
+ (`imageId`, `originalPath`, hash and size). In the background, one download at
241
+ a time, the relay brings each step's evidence to the host as one archive: its
242
+ before- and after-images and its receiver and action records. `relay_finish` and `relay_release` wait only for the download in
243
+ flight. They put the steps still queued, and every other file the host lacks,
244
+ into one archive of their own, and copy the files the step downloads already
245
+ brought instead of pulling them again. `relay_status` counts the steps whose
246
+ download a lifecycle operation took over as `coalesced`. A first or intermediate
247
+ group event and a diagnostic command do not invent an image. Execution and
248
+ image delivery are independent outcomes: a pending image does not turn a
249
+ failed command into a successful one. The delivery identity leads the result
250
+ text so it survives truncation. The design is `docs/screenshot-delivery.md`
251
+ §10.
252
+
253
+ `relay_image` shows a saved image. Asked for an image whose download is still
254
+ queued or running, it waits for that download within its own deadline. It
255
+ retrieves the same saved image through one closed selector; it never repeats input, creates a capture, exports the
256
+ consumer directory or acquires a VM:
257
+
258
+ ```json
259
+ {"target":{"source":"display","sessionId":"<recording-session>","executionId":"<saved-execution>","phase":"after"}}
260
+ {"target":{"source":"application","name":"screens","path":"login/step-1.png"}}
261
+ {"target":{"source":"reference","imageId":"image-<64 lowercase hex digits>"}}
262
+ ```
263
+
264
+ - Display selection needs `before` or `after`; a phase the plan did not request returns `not-requested`. Application selection needs an acquisition-time declaration: a directory declaration takes one relative file path, a file declaration omits `path`. A reference resolves to the same original bytes or an explicit failure.
265
+ - Originals are limited to 64 MiB, 40,000,000 decoded pixels and 32,768 pixels per dimension; PNG, JPEG and WebP are accepted. The preview is at most 2,000 × 2,000 pixels and 4 MiB of base64. **Presentation differs from pi here:** pi resizes through its own image helper, while this core has no codec dependency. A PNG original is decoded and, when it exceeds the preview bounds, resampled in-process (area averaging, `node:zlib`); a JPEG or WebP original has its container validated and passes through unchanged when within bounds, and is reported `presentation-unavailable` otherwise. No EXIF orientation is applied; dimensions are those stored. The presentation receipt records the policy, the original and preview dimensions, the MIME type, hash, size and whether bytes were transformed, beside the untouched original.
266
+ - Each delivery has a 90-second deadline and a shared budget of three byte-transfer attempts. Only transient transfer failures are retried; authorization, unsafe-path, capture, format and integrity failures are not. Recommend at most two explicit recovery calls for the same reference; if a required image still cannot be inspected, stop exploratory input and finish or release.
267
+ - Immutable catalog entries bind each reference to the owner, enclosure, backend and original identity. A closed or sealed guest returns `stale-reference`; delivered originals remain readable with the host's file tools. Finalization materializes verified originals at canonical snapshot paths and preserves prior state when merging guest evidence.
268
+ - Attachment means the block was included in the result; it does not prove the model inspected it or that a human reviewed it.
269
+
270
+ ## Live console viewing
271
+
272
+ Acquisition never opens a viewer. `relay_acquisition_capabilities` reads the
273
+ backend's VNC options; `relay_acquire` with `vnc: true` checks OS availability
274
+ and requires a ready console and lease identity in the response.
275
+ `relay_console_open` is permitted only following an explicit user request,
276
+ requires `userRequested: true`, `console_id`, `attempt_id`, `reason` and
277
+ `expected`, and opens on the declared service host, not on a remote client.
278
+ `relay_console_resolve` refreshes the non-secret observation;
279
+ `relay_console_cancel` closes managed viewing resources and never releases the
280
+ VM. Console status `ready` is guest preflight, not launch
281
+ success; transport connection, authentication, displayed pixels and human
282
+ confirmation are separate observations that console actions never establish.
283
+ On macOS the human must choose Standard sharing of the existing console, not a
284
+ new Log In session or a High Performance display; the relay never confirms
285
+ that selection, and `server_enforced_view_only: false` with `session_binding:
286
+ viewer-selection-unverified` remain limitations after transport connects.
287
+ Failed or uncertain launches retain ownership; resolve or cancel the attempt
288
+ rather than replaying it. Console tests use mocked backends; no live viewer,
289
+ installation or platform acceptance is claimed here.
290
+
291
+ ## Selected environments
292
+
293
+ Set `VM_ENVIRONMENT_FILE` to a profile that binds a loopback vm-service
294
+ endpoint, an image repository, a Tart store and separate service, image and
295
+ relay state directories together. The profile is validated before use, is
296
+ authoritative over the individual `MCP_RELAY_*` variables, and an invalid
297
+ selection fails rather than falling back. Leases are bound to their backend and
298
+ store: an owned lease restored under a different environment fails before any
299
+ backend operation, and destruction is verified with the selected Tart binary
300
+ and `TART_HOME`. `docs/selected-environments.md` documents the schema. The
301
+ bundle the profile exports to subprocesses is the canonical one vm-service
302
+ defines, so its relay entries keep the `VM_RELAY_STATE_DIR` and
303
+ `VM_RELAY_URL` names and the three runtimes agree; this server reads its own
304
+ settings from the profile.
305
+
306
+ ## Evidence and cleanup
307
+
308
+ Default output is `relay-evidence/<unique-task>/` under the project, with
309
+ `state/` (the guest journal, action records, receipts and snapshot PNGs),
310
+ `host/` (reasons, submissions, transfer facts, receipts, diagnostics, image
311
+ deliveries and lifecycle events), `extractions/` (declared files, including the
312
+ page captures), `manifest.json`, which checksums everything, and `OPENING.txt`.
313
+ The package is the raw evidence only; pi-secretary's computer-use extension
314
+ shows its steps and verdicts beside the agent's session. The steps and verdicts
315
+ are derived from the evidence when you review it, so an earlier package is reviewed with today's rules.
316
+ A program that reads relay packages gets the same derivation from
317
+ `@wezzard/mcp-relay/review-data`: `await reviewData(<directory>)` returns the
318
+ steps (with each snapshot's package path), the verdicts and their reasons. No network, VM or external assets are
319
+ needed. Diagnostic commands appear in the review data
320
+ as command-only steps without screenshots. `finish` verifies the package before
321
+ destroying the VM; a failed delivery removes only the derived files it created
322
+ and retains the VM for a corrected attempt. Cleanup checks the read-only host
323
+ Tart inventory (the selected one, when an environment is selected) before
324
+ claiming destruction. Leases default to 4 hours, renewed 15 minutes at a
325
+ time up to that TTL; the vm-service reaper is the final backstop for process death.
326
+
327
+ Relay evidence has no size limit (owner decision PS-D12): screenshots are
328
+ delivered as captured, never scaled, compressed, deduplicated or budgeted, and
329
+ the relay state is delivered whatever its total size or file count. Only what a
330
+ client stages into the guest is bounded (512 MiB and 10,000 files per staging
331
+ request), and a single image original must be at most 64 MiB to be valid. Before
332
+ `finish` pulls the relay state it checks that the evidence volume has room for
333
+ it; when it does not, `finish` fails before pulling, names the shortfall and
334
+ keeps the VM for a retry after space is freed.
335
+
336
+ ## Configuration
337
+
338
+ - `MCP_RELAY_PROJECT`: the project directory (the plugin passes Claude Code's). Evidence lands under `relay-evidence/<task>/` there. Every host file the relay reads, `relay_stage`'s `workspace` and `files[].local` and `relay_script`'s `localPath`, lies in this folder: a relative path resolves against it, an absolute path must already lie in it, and a path through a symlink is refused.
339
+ - `MCP_RELAY_SESSION`: an explicit session identity. By default each server process takes a fresh random one; a stable identity lets a restarted server reconcile and reattach the guests of the same identity.
340
+ - `MCP_RELAY_URL`: the loopback vm-service origin, default `http://localhost:6240`. Non-loopback servers, redirects and physical targets are refused.
341
+ - `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`.
342
+ - `MCP_RELAY_ON_EXIT`: what the end of a session does to its guests, `pause` (the default: renewal pauses and the VMs are kept for an explicit finish or release) or `release` (every guest is released, then the server exits). An application that owns its tasks' machines, such as The Desk, sets `release`. Any other value stops the server at startup.
343
+ - `MCP_RELAY_CAPACITY_WAIT`: how many seconds `relay_acquire` waits when the host is at capacity, such as at 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.
344
+ - `MCP_RELAY_MAX_GUESTS`: the most guests one session holds at once, a positive integer, default 4. Any other value stops the server at startup.
345
+ - `MCP_RELAY_STATE_DIR`: host state, otherwise `$XDG_STATE_HOME/mcp-relay` or `~/.local/state/mcp-relay`, one subdirectory per session, with one `guests/<guest>/` folder per guest holding its ownership record and owner lock.
346
+ - `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.
347
+ - `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.
348
+ - `MCP_RELAY_PYTHON`: the Python 3 used for the registry lock; default `python3` on PATH.
349
+ - `VM_ENVIRONMENT_FILE`: a selected environment profile; it overrides the URL, state directory and registry above and binds the Tart store.
350
+ - Guest files go to `/var/tmp/<UTC-timestamp>-mcp-relay-<task>/`, with the runtime in `receiver.mjs`, support in `support/` and work in `workspace/`.
351
+
352
+ ## Development
353
+
354
+ Build relay-driver using its own instructions, then in this checkout:
355
+
356
+ ```sh
357
+ npm ci
358
+ npm run setup:dev -- /absolute/path/to/built/relay-driver
359
+ npm run check # build, typecheck, tests
360
+ ```
361
+
362
+ Three tests need a sibling checkout beside this repository and skip with a
363
+ message when it is absent: the console fixture regeneration and the
364
+ environment parity test need `../vm-service`, and the shared catalog text
365
+ corpus needs `../pilot-images`. The JPEG and WebP presentation fixtures in
366
+ `tests/fixtures/` were encoded once from the test's spatial PNG with a codec
367
+ outside this repository and are committed, because the core carries none.
368
+
369
+ ### End-to-end with headless Claude Code
370
+
371
+ ```sh
372
+ npm run test:e2e
373
+ ```
374
+
375
+ This runs `claude --print` with the plugin loaded from this checkout
376
+ (`--plugin-dir`), the model limited to the relay's tools, and the server pointed
377
+ at a loopback stand-in for vm-service (`tests/e2e/fixture-service.ts`), which
378
+ keeps leases as records, runs the relay's own Node and transfer commands
379
+ locally, and fakes the desktop capture driver. Four cases run, each a separate
380
+ headless session: the status call (which also proves the server is pointed at
381
+ the stand-in before anything is acquired), an invalid call refused by the
382
+ contract, a full acquire, stage, exec, finish lifecycle with a verified package,
383
+ and a lease abandoned when the session ends, which is retained with its renewal
384
+ paused rather than released. What is checked is what happened on disk and at
385
+ the service, not what the model said. The suite needs `claude` on PATH with an
386
+ account and spends a few model turns per case, so it is not part of `npm test`.
387
+
388
+ The relay-driver links are development-only. The tests run the manager, the
389
+ guest programs and the shipped server against fixture HTTP services, fixture
390
+ MCP servers built with the MCP SDK and a real MCP client over stdio; no VM, desktop or user
391
+ registry is touched. Commit the regenerated `dist/` with source changes.
392
+
393
+ ## Releasing
394
+
395
+ Cut a release with:
396
+
397
+ ```sh
398
+ node scripts/bump.mjs X.Y.Z && git push --follow-tags
399
+ ```
400
+
401
+ `scripts/bump.mjs` sets `X.Y.Z` as the version in `package.json`,
402
+ `.claude-plugin/plugin.json` and the pinned `pi-mcp.json` arg, refreshes
403
+ `package-lock.json`, rebuilds `dist/`, commits `Release vX.Y.Z` and creates the
404
+ annotated tag `vX.Y.Z`. It refuses to run against a dirty working tree or a
405
+ malformed version, and it never pushes — `git push --follow-tags` is a
406
+ separate, explicit step.
407
+
408
+ Pushing the tag triggers
409
+ [`.github/workflows/release.yml`](.github/workflows/release.yml), which
410
+ rebuilds `vmctl`, checks the working build against a fresh one, and publishes
411
+ to npm using [trusted publishing](https://docs.npmjs.com/trusted-publishers)
412
+ (OIDC — no `NPM_TOKEN` secret involved), then creates the matching GitHub
413
+ release.
414
+
415
+ Trusted publishing has to be configured on npmjs.com, and npm requires the
416
+ package to already exist before you can do that. The **first** publish must
417
+ therefore be done by hand (`npm publish --access public` from a maintainer's
418
+ machine) before its trusted publisher can be configured for this workflow.
419
+
420
+ ## License
421
+
422
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: vm-relay-operator
3
+ description: Operates one or more guest VMs through the relay's MCP tools for a task to run in a guest. Give it the task, the image to use and the outputs to bring home; it returns the verified package path and the separate evidence and execution outcomes.
4
+ tools: mcp__plugin_mcp-relay_relay__relay_search, mcp__plugin_mcp-relay_relay__relay_probe, mcp__plugin_mcp-relay_relay__relay_acquisition_capabilities, mcp__plugin_mcp-relay_relay__relay_acquire, mcp__plugin_mcp-relay_relay__relay_stage, mcp__plugin_mcp-relay_relay__relay_command, mcp__plugin_mcp-relay_relay__relay_script, mcp__plugin_mcp-relay_relay__relay_image, mcp__plugin_mcp-relay_relay__relay_extract, mcp__plugin_mcp-relay_relay__relay_finish, mcp__plugin_mcp-relay_relay__relay_release, mcp__plugin_mcp-relay_relay__relay_console_resolve, mcp__plugin_mcp-relay_relay__relay_console_open, mcp__plugin_mcp-relay_relay__relay_console_cancel, mcp__plugin_mcp-relay_relay__relay_status, Read, Glob, Grep
5
+ model: sonnet
6
+ ---
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
10
+ guest for each machine the task needs, and declare every output you will bring
11
+ home as an extraction before any work. relay_acquire answers the guest's name,
12
+ `guest`; name it in every later call on that guest. Several guests may run at
13
+ once, and finishing one leaves the others running. Stage the runtime and the support the task needs.
14
+ Run commands with relay_command and scripts with relay_script: a JavaScript,
15
+ TypeScript or Python script, given inline (`inline: true`, `code`) or as a
16
+ project file (`inline: false`, `localPath`). Drive the desktop and browsers
17
+ from a command or script through the software the image lists, such as
18
+ cua-driver's command line or Playwright; relay_probe with `scope: "guest"`
19
+ reports the runtimes and the listed software. When the image lists cua-driver
20
+ the relay snapshots every run, and it records each run as a step; add `reason`
21
+ and `step` when they help a reviewer. Split the work into single recorded
22
+ events, one run each; do not hide an interaction sequence in one script.
23
+
24
+ Inspect the after-image of each run before choosing the next step: a run
25
+ names it as `pending` with an `imageId`, and relay_image with that `imageId`
26
+ shows it. If relay_image reports that the image was not attached, retry it
27
+ with the same reference; never repeat input to obtain
28
+ an image, and stop exploratory input if a required image is still
29
+ uninspectable after two recovery calls. A failed operation keeps the VM:
30
+ diagnose it, use relay_command with `diagnostic: true` if the user's task calls
31
+ for repair, or relay_release. Never replay uncertain input. Do not open
32
+ console viewing (relay_console_open) unless the user explicitly asked to
33
+ watch.
34
+
35
+ Call relay_finish or relay_release explicitly for every guest before you
36
+ return; the session ending never finishes a guest. Report the verified package path, the
37
+ 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
+ relay-driver directly.
@@ -0,0 +1,4 @@
1
+ ---
2
+ description: "Report this session's guests and their VM leases exactly as the relay_status tool sees them. Read-only."
3
+ ---
4
+ Call the `relay_status` tool once, with no arguments, and report its answer to the user exactly as it is. Do not act on any guest from here: `relay_finish` and `relay_release` are separate relay actions.
@@ -0,0 +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.