@wezzard/mcp-relay 0.14.2 → 0.15.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.14.2",
3
+ "version": "0.15.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
@@ -4,10 +4,10 @@ The Model Context Protocol front end of the VM relay, packaged as a Claude Code
4
4
  plugin and as a pi package. [pi-vm-relay](https://github.com/WeZZard/pi-vm-relay),
5
5
  which gave pi a native `relay` tool directly, is retired; mcp-relay replaces
6
6
  it for both Claude Code and pi, the latter loaded through `pi-mcp-adapter`. It
7
- is an MCP server: fifteen `relay_*` tools, each with its own schema, title
7
+ is an MCP server: fourteen `relay_*` tools, each with its own schema, title
8
8
  and annotations, and the server's `instructions`. The user command, status,
9
9
  ships as one small command file per host (see "Commands"). There is no skill and no hook. Together they offer recorded,
10
- snapshot-evidenced commands and scripts in a fresh, dedicated VM, for any work
10
+ snapshot-evidenced scripts, commands included as shell scripts, in a fresh, dedicated VM, for any work
11
11
  the agent chooses to run there; a script drives the desktop or a browser
12
12
  through the software the image lists, such as cua-driver or Playwright. Nothing here executes local computer-use, spawns
13
13
  subagents, targets physical machines, records video, or attaches to existing
@@ -48,7 +48,7 @@ adds nothing Claude-Code-specific beyond the marketplace packaging and the
48
48
 
49
49
  | In pi-vm-relay (retired, native pi extension) | Here (MCP server) |
50
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 |
51
+ | a registered `relay` tool with thirteen actions | fourteen `relay_*` MCP tools from the server `relay`, each with its own schema, title and annotations |
52
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
53
  | `/relay-status` command | `/mcp-relay-status` in pi, `/mcp-relay:status` in Claude Code; it asks the assistant to call `relay_status` |
54
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 |
@@ -73,7 +73,7 @@ Or add this repository as a marketplace and install the plugin from it:
73
73
  /plugin install mcp-relay@mcp-relay
74
74
  ```
75
75
 
76
- Once loaded, the model sees the fifteen tools as
76
+ Once loaded, the model sees the fourteen tools as
77
77
  `mcp__plugin_mcp-relay_relay__relay_search`,
78
78
  `mcp__plugin_mcp-relay_relay__relay_probe`, and so on through
79
79
  `mcp__plugin_mcp-relay_relay__relay_status` (see "The tools" below for
@@ -128,20 +128,20 @@ and no `action` field, derived directly from the strict per-action contract in
128
128
  `target`, are unaffected). A call is mapped back to that contract's shape and
129
129
  dispatched exactly as the retired single `relay` tool was, so behaviour,
130
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.
131
+ split. One tool runs anything in a guest: `relay_script` runs a shell,
132
+ JavaScript, TypeScript or Python script, given inline or as a project file. A
133
+ command is a shell script. It takes the optional `reason`, `step`, `snapshots`,
134
+ `timeoutMs` and, for a shell script, `diagnostic`, and its evidence is
135
+ automatic: see "Runs" below.
135
136
 
136
- | Tool | Title | Replaces (`action`, `kind`) | Purpose |
137
+ | Tool | Title | Replaces (`action`) | Purpose |
137
138
  |---|---|---|---|
138
139
  | `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_probe` | Probe host and guest readiness | `probe` | Default `scope: "host"` reports host facts, service availability and every guest the session holds, with its state. `scope: "guest"` with `guest` checks Node.js, which staging requires, and reports as facts whether each `relay_script` language's runtime runs (`/bin/sh`, `node`, `tsx`, `python3`), the software the image lists in the catalog and whether runs take snapshots, on that guest, without installing, starting or claiming capture readiness. |
140
141
  | `relay_acquisition_capabilities` | Read acquisition capabilities | `acquisition-capabilities` | Read versioned acquisition options (VNC backends) without allocation or ownership recovery. |
141
142
  | `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
143
  | `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`). |
144
+ | `relay_script` | Run a guest script | `run` | One recorded guest script in `language` (`shell`, `javascript`, `typescript` or `python`); a command is a shell script. `inline: true` takes the script as `code`, up to 1 MiB; `inline: false` takes `localPath`, a file in the project folder. `diagnostic: true`, for a shell script only, records diagnosis or repair without screenshot evidence, including before staging. |
145
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
146
  | `relay_extract` | Extract declared outputs | `extract` | Pull only declared files or directories with source and host checksum verification. |
147
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. |
@@ -154,19 +154,21 @@ as a project file. Both take the optional `reason`, `step`, `snapshots` and
154
154
  `readOnlyHint`/`idempotentHint` are true for `relay_search`, `relay_probe`,
155
155
  `relay_acquisition_capabilities`, `relay_console_resolve`, `relay_image` and
156
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
157
+ `relay_release`, which destroy a guest's VM; `openWorldHint` is true only for
158
+ `relay_script`, whose guest code may reach the network.
159
+
160
+ `relay_command`, `relay_exec`, `relay_code`, `relay_run`, `relay_gate` and
161
+ `relay_tools` are gone (DC-23, DC-26, `docs/guest-code-runs.md` §10). A
162
+ command is a shell script: `{"argv":["ls","-al"]}` becomes
163
+ `{"language":"shell","inline":true,"code":"ls -al"}`. `relay_code` is
164
+ `relay_script` with `inline: true`. A run carries no kind. In place of
163
165
  `relay_run`'s forwarded MCP tool calls, a script drives cua-driver, Playwright
164
166
  or Chrome DevTools through their own libraries or command lines, as the image
165
167
  lists them; the relay no longer stages MCP servers in the guest.
166
168
 
167
169
  A run's result carries the execution identity and outcome, the derived step
168
170
  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
171
+ succeeded, the saved after-image as an MCP image content block. A run's
170
172
  result also carries the guest's bounded standard output and error. The full
171
173
  receipt stays in the evidence package.
172
174
 
@@ -199,16 +201,16 @@ tarball it checked.
199
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.
200
202
  - 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
203
  - 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.
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.
203
205
  - 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
206
 
205
207
  ## Runs
206
208
 
207
- `relay_command` runs one command and `relay_script` one script, each as one
208
- recorded operation:
209
+ `relay_script` runs one script as one recorded operation; a command is a
210
+ shell script:
209
211
 
210
212
  ```json
211
- {"guest":"login-test-1","argv":["/usr/bin/xdg-open","https://example.com"]}
213
+ {"guest":"login-test-1","language":"shell","inline":true,"code":"/usr/bin/xdg-open https://example.com"}
212
214
  {"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
215
  {"guest":"login-test-1","language":"typescript","inline":false,"localPath":"checks/login.ts"}
214
216
  ```
@@ -216,15 +218,18 @@ recorded operation:
216
218
  - **Evidence is automatic.** Every run is admitted by the guest receiver,
217
219
  journaled, and, when the image lists cua-driver, bracketed by a before and an
218
220
  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
221
+ is a shell script's first line (`shell <line>`), `code (<language>)` or
222
+ `script <file>`, and
220
223
  the expected result is "Exits with status 0". `reason`, `step` and
221
224
  `snapshots` are optional overrides; the default wait before the
222
225
  after-snapshot is 500 ms.
223
226
  - **Scripts.** A `relay_script` with `inline: true` streams its `code` to the
224
227
  guest with its hash; with `inline: false` its `localPath`, a file in the
225
228
  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
229
+ workspace: shell with `/bin/sh`, JavaScript with the guest's Node.js,
230
+ TypeScript with `tsx` or Node.js type stripping, Python with `python3`. The
231
+ script's exit status says whether it succeeded: a script that calls
232
+ cua-driver reads the driver's answer and exits nonzero on an error. A call that gives `code` and `localPath` other than
228
233
  as `inline` names is refused before anything reaches the guest.
229
234
  - **One interaction per run.** A run is one recorded operation; consecutive
230
235
  keystrokes may form an explicit text group with `snapshots.group`. A script
@@ -244,9 +249,9 @@ flight. They put the steps still queued, and every other file the host lacks,
244
249
  into one archive of their own, and copy the files the step downloads already
245
250
  brought instead of pulling them again. `relay_status` counts the steps whose
246
251
  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
252
+ group event and a diagnostic script do not invent an image. Execution and
248
253
  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
254
+ failed run into a successful one. The delivery identity leads the result
250
255
  text so it survives truncation. The design is `docs/screenshot-delivery.md`
251
256
  §10.
252
257
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: vm-relay-operator
3
3
  description: Operates one or more guest VMs through the relay's MCP tools for a task to run in a guest. Give it the task, the image to use and the outputs to bring home; it returns the verified package path and the separate evidence and execution outcomes.
4
- tools: mcp__plugin_mcp-relay_relay__relay_search, mcp__plugin_mcp-relay_relay__relay_probe, mcp__plugin_mcp-relay_relay__relay_acquisition_capabilities, mcp__plugin_mcp-relay_relay__relay_acquire, mcp__plugin_mcp-relay_relay__relay_stage, mcp__plugin_mcp-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
4
+ tools: mcp__plugin_mcp-relay_relay__relay_search, mcp__plugin_mcp-relay_relay__relay_probe, mcp__plugin_mcp-relay_relay__relay_acquisition_capabilities, mcp__plugin_mcp-relay_relay__relay_acquire, mcp__plugin_mcp-relay_relay__relay_stage, mcp__plugin_mcp-relay_relay__relay_script, mcp__plugin_mcp-relay_relay__relay_image, mcp__plugin_mcp-relay_relay__relay_extract, mcp__plugin_mcp-relay_relay__relay_finish, mcp__plugin_mcp-relay_relay__relay_release, mcp__plugin_mcp-relay_relay__relay_console_resolve, mcp__plugin_mcp-relay_relay__relay_console_open, mcp__plugin_mcp-relay_relay__relay_console_cancel, mcp__plugin_mcp-relay_relay__relay_status, Read, Glob, Grep
5
5
  model: sonnet
6
6
  ---
7
7
 
@@ -11,10 +11,10 @@ guest for each machine the task needs, and declare every output you will bring
11
11
  home as an extraction before any work. relay_acquire answers the guest's name,
12
12
  `guest`; name it in every later call on that guest. Several guests may run at
13
13
  once, and finishing one leaves the others running. Stage the runtime and the support the task needs.
14
- Run 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
14
+ Run everything with relay_script: a shell, JavaScript, TypeScript or Python
15
+ script, given inline (`inline: true`, `code`) or as a project file
16
+ (`inline: false`, `localPath`). A command is a shell script. Drive the desktop
17
+ and browsers from a script through the software the image lists, such as
18
18
  cua-driver's command line or Playwright; relay_probe with `scope: "guest"`
19
19
  reports the runtimes and the listed software. When the image lists cua-driver
20
20
  the relay snapshots every run, and it records each run as a step; add `reason`
@@ -27,7 +27,7 @@ shows it. If relay_image reports that the image was not attached, retry it
27
27
  with the same reference; never repeat input to obtain
28
28
  an image, and stop exploratory input if a required image is still
29
29
  uninspectable after two recovery calls. A failed operation keeps the VM:
30
- diagnose it, use relay_command with `diagnostic: true` if the user's task calls
30
+ diagnose it, use a shell relay_script with `diagnostic: true` if the user's task calls
31
31
  for repair, or relay_release. Never replay uncertain input. Do not open
32
32
  console viewing (relay_console_open) unless the user explicitly asked to
33
33
  watch.
@@ -956,28 +956,28 @@
956
956
  "src/archive.ts": "469ca411558db5696c8790d8a7132108d6705d4316c5a31a149f7472ddbef0ec",
957
957
  "src/config.ts": "3fbc475596ec0a1b6122ea963bf2769420a8a2a0e62fda55e66018fb3a6d53b3",
958
958
  "src/console.ts": "d8258173a24449c2a394289b14983b9575c5ce753ab267d4e13213f3abfcb72d",
959
- "src/core.ts": "7ccdd6dd6e4d059c9242a7dfb70164433e9ab785c0c9e02fe729fe2e4a0afba1",
959
+ "src/core.ts": "ea656be559f2a82cc76ab95a4c0f142df4d524fab35276d95aaa099ae537d38b",
960
960
  "src/doctor.ts": "7f509d7fd6c927a14e85110ad156efa879d9fa75e4e5f4af02b7f651cf66a8ab",
961
961
  "src/downloads.ts": "4f37b5bb4fac96f9260a3a87c83bacf715b9add5ae9926d3fe0994000c70a8dd",
962
962
  "src/environment.ts": "04bc2a82eb56c1b0d77dabc9db4b0af9331f18c14398e7370e31a0081914f019",
963
963
  "src/evidence-merge.ts": "2f2759e28e70595ef9284fec85e1d6082bf25e815d04f0a36a253c24bfb75110",
964
- "src/guest/image-evidence.ts": "e0d914cff90eac678818c49e60c7754e6bbb9b59861b9dcf8bc5b64c56ac2e52",
965
- "src/guest/receiver.ts": "187939653e3a7a463bfee98434f9dda07b64cb924b0395d5d7601f48a54f67b1",
964
+ "src/guest/image-evidence.ts": "9c5daaed5b33b9912021a91fd79a2e6d5be42c75d37761772a3bd2645d20a55e",
965
+ "src/guest/receiver.ts": "92fc8d3bfe95ed56d43cfe5b46eb196034ade5e4e9f58ed202465531458f697d",
966
966
  "src/image-presentation.ts": "64ca29a3444a04606cb783c81ac2d0f3136f9a9ac730ae9074156f0a63256c76",
967
967
  "src/images.ts": "734a30ba34cd80ef0b5c3791232f13b170b06d6d74c4b843d39566d2e09136d0",
968
- "src/manager.ts": "2c5547af6b83de0b8728a20f237ed143caa241c5b3dcd60a4d1e74580e18f6d2",
968
+ "src/manager.ts": "7e24a1eb66753698e6909406ef0a3dd1cef61ec096dc8301978f86214df976d5",
969
969
  "src/owner-lock.ts": "a99cbaba67b4aff0e646dc5d5967db4497ba6dbda83fb1838c55f0bf0f6e0367",
970
970
  "src/package.ts": "a52ed791813922e3ace9144706ddde8313a67d8580a3acd54a0799de3ebe44d2",
971
971
  "src/probe.ts": "40a123f725aad7c22fe63707dd2de99646cb1f307d7d660927e8ca2b973e9ce0",
972
972
  "src/registry.ts": "87478f1ceef0f06df9b28c064a817383ff153bdadd70e6d58b4a7ed464f66146",
973
973
  "src/review-data.ts": "2e873eb23612fd4502d84e65322006345f4e97bb679109b23dc4d26683200c19",
974
- "src/schema.ts": "c3b4e13fc5e8428f7dde363e3d5d659effb029fea1f164626552cdecbd03b075",
974
+ "src/schema.ts": "0141b2befc75fafa1bbe9914b34eab374a1204ce34f44af19f2100153805baf8",
975
975
  "src/search-diagnostics.ts": "cea037618c56f075d51155101ad1cc0314bfa67b174bdb070191e0ea5ea04679",
976
976
  "src/search.ts": "8aaf544fcb27e7e018bd976e1ba7d3c70c047aeda3182b3dce91873a901a245e",
977
- "src/server.ts": "9f8e6cbc4ea346f226f61f9f9860c5d10d4864eecf41a25af1713a3fb5a0691e",
978
- "src/surface.ts": "bd34b2b60aa8042276fbb27380c55c5b29c8474e5fe7427d37a111e6b3c1cd25",
977
+ "src/server.ts": "c3256d27248140a1072a924796ba9b7f0edbbe9b5c72bcdeea02a46734aaf5cd",
978
+ "src/surface.ts": "f7772fbafa613aaeba05e47d2def4975fb0ce75d1af067bde968f0e95775f81a",
979
979
  "src/transfer.ts": "009dfb72ebd41a5642ec02a48ab7b678bed75e5db8859acc15a45e7f0bd43462",
980
- "src/transport.ts": "28661615bd8f31635811c8c6b21d4d968bcd79b8c16c7a798f744dcf33c0f217",
980
+ "src/transport.ts": "08609fcf56ef9b60b867f7f86783c198b622f72e2b02f2562c5f1506ee1dc0bd",
981
981
  "src/typebox.ts": "7f071fbc67548c7d3701272dabe88a217812e12e41dfad76974ff08169fa1a7e",
982
982
  "src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da",
983
983
  "src/vm-service.ts": "f2a6bfa910484f42aa264dbe02012379c82b093a71645b33e8a8ccd968f4634d"
@@ -1,6 +1,6 @@
1
1
  {
2
- "server.mjs": "ffb1d595668b5a6d135088ccde3c2e67a48043c4ee1fdf49e4c0bf9d55687cb8",
3
- "receiver.mjs": "2c98de7231780391c6f958c054409d80318230bb009e529a4fc68ed34e34f09e",
2
+ "server.mjs": "94d0e19263eb7202808929768f0e85ecbbad361dec51b91732422d4e75708e33",
3
+ "receiver.mjs": "8b5b6fdd6cb789cdc4060e367a155cb42e7cf34187044c899789bf76b7bb0e14",
4
4
  "doctor.mjs": "32bcfbcf318ab72f81be6fa1d2106b7556e7978ed61bf0da0c79bc9f5da360d2",
5
5
  "review-data.mjs": "da7b6b35d060e09cfc445df4febda02a1a0c0f23d9b854866aed8d604cbb3993"
6
6
  }
package/dist/receiver.mjs CHANGED
@@ -830,7 +830,7 @@ function describe(value) {
830
830
  // src/guest/image-evidence.ts
831
831
  var safeId = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,159}$/.test(value);
832
832
  function afterRequested(request) {
833
- return !(request?.kind === "exec" && request.diagnostic === true) && request?.capture !== false && !["first", "member"].includes(request?.snapshots?.group?.phase ?? "");
833
+ return request?.diagnostic !== true && request?.capture !== false && !["first", "member"].includes(request?.snapshots?.group?.phase ?? "");
834
834
  }
835
835
  function validateImageEvidence(value, request, authoritativeSnapshots) {
836
836
  const fail = () => {
@@ -901,10 +901,9 @@ async function optionalJson(path) {
901
901
  function validate(request) {
902
902
  if (!safeId(request.executionId) || !safeId(request.sessionId) || !safeId(request.attemptId)) throw new Error("safe executionId, sessionId and attemptId are required");
903
903
  if (typeof request.because !== "string" || !request.because.trim() || request.because.length > 16384) throw new Error("nonblank because is required (maximum 16384 characters)");
904
- if (!["exec", "script", "code"].includes(request.kind)) throw new Error("kind must be exec, script or code");
905
904
  if (request.cwd !== void 0 && (!text(request.cwd) || !isAbsolute(request.cwd))) throw new Error("cwd must be an absolute path");
906
905
  if (request.timeoutMs !== void 0 && (!Number.isInteger(request.timeoutMs) || request.timeoutMs < 1 || request.timeoutMs > MAX_TIMEOUT_MS)) throw new Error("timeoutMs must be an integer from 1 to 3600000");
907
- if (request.diagnostic !== void 0 && (typeof request.diagnostic !== "boolean" || request.kind !== "exec")) throw new Error("diagnostic is allowed only for exec and must be boolean");
906
+ if (request.diagnostic !== void 0 && (typeof request.diagnostic !== "boolean" || request.language !== "shell")) throw new Error("diagnostic is allowed only for a shell script and must be boolean");
908
907
  if (request.step !== void 0 && (!request.step || !safeId(request.step.id) || !text(request.step.title) || request.step.expected !== void 0 && typeof request.step.expected !== "string" || request.step.inputMode !== void 0 && !["ordinary", "accessibility"].includes(request.step.inputMode))) throw new Error("invalid step metadata");
909
908
  const snapshots = request.snapshots;
910
909
  if (!snapshots || typeof snapshots !== "object" || Array.isArray(snapshots)) throw new Error("snapshots are required; no implicit interval");
@@ -916,11 +915,12 @@ function validate(request) {
916
915
  if (group.afterIntervalMs !== void 0 && !interval(group.afterIntervalMs)) throw new Error("invalid group afterIntervalMs");
917
916
  if (group.phase === "last" && !interval(group.afterIntervalMs ?? snapshots.afterIntervalMs)) throw new Error("last group member requires afterIntervalMs");
918
917
  } else if (!interval(snapshots.afterIntervalMs)) throw new Error("afterIntervalMs is required; no default");
919
- if (request.kind !== "code" && (!Array.isArray(request.argv) || request.argv.length === 0 || request.argv.length > 256 || !request.argv.every((arg, index) => typeof arg === "string" && !arg.includes("\0") && (index > 0 || arg.length > 0)))) throw new Error("argv must be a nonempty string vector without NULs (maximum 256 entries)");
920
- if (request.kind !== "exec" && !["javascript", "typescript", "python"].includes(request.language ?? "")) throw new Error("script/code language is required");
921
- if (request.kind === "code" && (typeof request.code !== "string" || !/^[a-f0-9]{64}$/.test(request.codeSha256 ?? ""))) throw new Error("code and its SHA-256 are required");
918
+ if (!["shell", "javascript", "typescript", "python"].includes(request.language ?? "")) throw new Error("language must be shell, javascript, typescript or python");
919
+ const inline = request.code !== void 0, file = request.remotePath !== void 0;
920
+ if (inline === file) throw new Error("a request holds either the script's code or its uploaded remotePath");
921
+ if (inline && (typeof request.code !== "string" || !/^[a-f0-9]{64}$/.test(request.codeSha256 ?? ""))) throw new Error("code and its SHA-256 are required");
922
922
  if (request.capture !== void 0 && typeof request.capture !== "boolean") throw new Error("capture must be boolean");
923
- if (request.kind === "script" && (!text(request.remotePath) || !isAbsolute(request.remotePath) || !/^[a-f0-9]{64}$/.test(request.scriptSha256 ?? ""))) throw new Error("absolute remotePath and script SHA-256 are required");
923
+ if (file && (!text(request.remotePath) || !isAbsolute(request.remotePath) || !/^[a-f0-9]{64}$/.test(request.scriptSha256 ?? ""))) throw new Error("absolute remotePath and script SHA-256 are required");
924
924
  }
925
925
  function groupAbsentFromProcessTable(group, table) {
926
926
  const lines = table.split("\n").map((line) => line.trim()).filter(Boolean);
@@ -1025,6 +1025,14 @@ async function runArgv(argv, options, onSpawn) {
1025
1025
  });
1026
1026
  });
1027
1027
  }
1028
+ async function executable(path) {
1029
+ try {
1030
+ await access(path, constants.X_OK);
1031
+ return true;
1032
+ } catch {
1033
+ return false;
1034
+ }
1035
+ }
1028
1036
  async function onPath(name) {
1029
1037
  for (const dir of (process.env.PATH ?? "").split(":")) {
1030
1038
  if (!dir) continue;
@@ -1036,7 +1044,11 @@ async function onPath(name) {
1036
1044
  }
1037
1045
  return false;
1038
1046
  }
1039
- async function interpreterArgv(language, path, find = onPath, node = { execPath: process.execPath, version: process.versions.node, strips: Boolean(process.features.typescript) }) {
1047
+ async function interpreterArgv(language, path, find = onPath, node = { execPath: process.execPath, version: process.versions.node, strips: Boolean(process.features.typescript) }, shell = executable) {
1048
+ if (language === "shell") {
1049
+ if (!await shell("/bin/sh")) throw new Error("the guest has no /bin/sh, so a shell script cannot run");
1050
+ return ["/bin/sh", path];
1051
+ }
1040
1052
  if (language === "python") {
1041
1053
  if (!await find("python3")) throw new Error("python3 is not on the guest's PATH, so a Python script cannot run; relay_probe scope=guest reports which runtimes the guest has");
1042
1054
  return ["python3", path];
@@ -1057,7 +1069,7 @@ async function captureWithDriver(outFile, driver, dispatch = runArgv) {
1057
1069
  async function receive(input, options = {}) {
1058
1070
  const request = input;
1059
1071
  const executionId = request && safeId(request.executionId) ? request.executionId : "unknown";
1060
- const evidenceMode = request?.kind === "exec" && request.diagnostic === true ? "diagnostic" : void 0;
1072
+ const evidenceMode = request?.diagnostic === true ? "diagnostic" : void 0;
1061
1073
  const uncaptured = request?.capture === false;
1062
1074
  const timeoutMs = request?.timeoutMs ?? 12e4;
1063
1075
  let imageEvidence = { status: afterRequested(request) ? "capture-unknown" : "not-requested", snapshots: [] };
@@ -1081,10 +1093,10 @@ async function receive(input, options = {}) {
1081
1093
  const operationPids = [];
1082
1094
  let pendingSpawn = false;
1083
1095
  const markLock = (active, settled = false) => durableJson(ownerPath, { pid: process.pid, executionId, active, operationPids, pendingSpawn, settled });
1084
- const runOwned = async (argv, dispatchOptions) => {
1096
+ const runOwned = async (argv2, dispatchOptions) => {
1085
1097
  pendingSpawn = true;
1086
1098
  await markLock(true);
1087
- const result = await runArgv(argv, dispatchOptions, async (pid) => {
1099
+ const result = await runArgv(argv2, dispatchOptions, async (pid) => {
1088
1100
  operationPids.push(pid);
1089
1101
  pendingSpawn = false;
1090
1102
  await markLock(true);
@@ -1096,6 +1108,7 @@ async function receive(input, options = {}) {
1096
1108
  };
1097
1109
  let reconcileGroup;
1098
1110
  let dispatchResult;
1111
+ let argv;
1099
1112
  const output = () => dispatchResult ? { stdout: bounded(dispatchResult.stdout), stderr: bounded(dispatchResult.stderr), timedOut: !!dispatchResult.timedOut, outputTruncated: !!dispatchResult.outputTruncated, terminationConfirmed: dispatchResult.terminationConfirmed } : {};
1100
1113
  try {
1101
1114
  await mkdir3(root, { recursive: true });
@@ -1186,7 +1199,7 @@ async function receive(input, options = {}) {
1186
1199
  imageEvidence = candidate;
1187
1200
  result = JSON.parse(JSON.stringify({ ...result, imageEvidence, evidenceMode, timeoutMs, ...output() }));
1188
1201
  if (result.outcome.kind !== "completed" || result.outcome.exitStatus.code !== 0) await reconcileGroup?.("operation failed or incomplete");
1189
- await store.putExecution({ executionId, ...ids, state: result.outcome.kind === "completed" ? "recorded" : result.outcome.kind, argv: request.argv, scriptId: request.scriptId, exitStatus: result.outcome.kind === "completed" ? result.outcome.exitStatus : void 0 });
1202
+ await store.putExecution({ executionId, ...ids, state: result.outcome.kind === "completed" ? "recorded" : result.outcome.kind, argv, scriptId: request.scriptId, exitStatus: result.outcome.kind === "completed" ? result.outcome.exitStatus : void 0 });
1190
1203
  await store.appendJournal({ kind: "execution-completion", ...ids, executionId, state: result.outcome.kind === "completed" ? "recorded" : result.outcome.kind, response: result }, { durable: true });
1191
1204
  await durableJson(receiptPath, result);
1192
1205
  return result;
@@ -1219,19 +1232,15 @@ async function receive(input, options = {}) {
1219
1232
  if (groups.active && (!group || group.groupId !== groups.active.groupId || request.sessionId !== groups.active.sessionId || request.attemptId !== groups.active.attemptId || group.phase === "first")) return await refuse("coalescing group is open; unrelated input is forbidden until its last member");
1220
1233
  if (!groups.active && group && (group.phase !== "first" || groups.used.includes(group.groupId))) return await refuse("coalescing group must begin with a fresh first member; group IDs cannot be reused");
1221
1234
  reconcileGroup = abandonGroup;
1222
- let argv = request.argv ?? [];
1223
1235
  try {
1224
- if (request.kind === "script") {
1236
+ if (request.remotePath !== void 0) {
1225
1237
  const info = await stat2(request.remotePath);
1226
1238
  if (!info.isFile() || info.size > MAX_SCRIPT_BYTES) throw new Error("script missing or exceeds size bound");
1227
1239
  if (hash(await readFile2(request.remotePath)) !== request.scriptSha256) throw new Error("script hash mismatch");
1228
- const expected = request.language === "python" ? "python3" : request.language === "typescript" ? "tsx" : "node";
1229
- if (argv.length !== 2 || argv[0].split("/").at(-1) !== expected || argv[1] !== request.remotePath) throw new Error("script argv must be [interpreter, verified remotePath]");
1230
1240
  argv = await interpreterArgv(request.language, request.remotePath);
1231
- } else if (request.kind === "code") {
1241
+ } else {
1232
1242
  if (hash(request.code) !== request.codeSha256) throw new Error("streamed code hash mismatch");
1233
- const extension = request.language === "python" ? "py" : request.language === "typescript" ? "ts" : "js";
1234
- const path = join3(root, "streamed", `${executionId}.${extension}`);
1243
+ const path = join3(root, "streamed", `${executionId}.${{ shell: "sh", python: "py", typescript: "ts", javascript: "js" }[request.language]}`);
1235
1244
  await mkdir3(dirname2(path), { recursive: true });
1236
1245
  const file = await open(path, "wx", 384);
1237
1246
  try {
@@ -1246,7 +1255,8 @@ async function receive(input, options = {}) {
1246
1255
  } catch (error) {
1247
1256
  return await refuse(message(error));
1248
1257
  }
1249
- await store.appendJournal({ kind: "execution-start", ...ids, executionId, state: "admitted", argv, cwd: request.cwd, step: request.step, evidenceMode, timeoutMs, ...uncaptured ? { capture: false } : {}, scriptIdentity: request.kind === "exec" ? void 0 : { sha256: request.kind === "code" ? request.codeSha256 : request.scriptSha256, language: request.language, remotePath: argv.at(-1) } }, { durable: true });
1258
+ const command = argv;
1259
+ await store.appendJournal({ kind: "execution-start", ...ids, executionId, state: "admitted", argv, cwd: request.cwd, step: request.step, evidenceMode, timeoutMs, ...uncaptured ? { capture: false } : {}, scriptIdentity: { sha256: request.remotePath === void 0 ? request.codeSha256 : request.scriptSha256, language: request.language, remotePath: argv.at(-1) } }, { durable: true });
1250
1260
  if (group?.phase === "first") {
1251
1261
  groups.active = { groupId: group.groupId, ...ids };
1252
1262
  groups.used.push(group.groupId);
@@ -1271,7 +1281,7 @@ async function receive(input, options = {}) {
1271
1281
  await markLock(true);
1272
1282
  try {
1273
1283
  const dispatchOptions = { cwd: request.cwd, env: process.env, timeoutMs };
1274
- dispatchResult = options.dispatch ? await options.dispatch(argv, dispatchOptions) : await runOwned(argv, dispatchOptions);
1284
+ dispatchResult = options.dispatch ? await options.dispatch(command, dispatchOptions) : await runOwned(command, dispatchOptions);
1275
1285
  return dispatchResult;
1276
1286
  } finally {
1277
1287
  if (dispatchResult && dispatchResult.terminationConfirmed !== false && !keepLock) {
@@ -1285,18 +1295,6 @@ async function receive(input, options = {}) {
1285
1295
  const diagnostic = captureFailure ?? engine.evidenceFailure ?? "missing required snapshot evidence";
1286
1296
  return await retain(response("uncertain", diagnostic));
1287
1297
  }
1288
- const driver = options.cuaDriver ?? process.env.RELAY_CUA_DRIVER;
1289
- if (request.kind === "exec" && driver && argv[0] === driver && argv[1] === "call" && outcome.exitStatus.code === 0) {
1290
- let value;
1291
- try {
1292
- value = JSON.parse(outcome.stdout ?? "");
1293
- } catch {
1294
- }
1295
- if (value && typeof value === "object" && (value.isError === true || value.error || typeof value.code === "string" && value.code.length > 0)) {
1296
- const diagnostic = `CUA structured failure: ${JSON.stringify(value)}`;
1297
- return await retain({ ...response(value.code === "desktop_escalation_required" ? "refused" : "uncertain", diagnostic), stdout: bounded(outcome.stdout), stderr: bounded(outcome.stderr) });
1298
- }
1299
- }
1300
1298
  const result = outcome.spawnError || outcome.timedOut || outcome.outputTruncated ? response("uncertain", outcome.spawnError ?? (outcome.timedOut ? "execution timed out" : "execution exceeded output bound")) : { executionId, outcome: { kind: "completed", exitStatus: outcome.exitStatus } };
1301
1299
  if (group?.phase === "last" && result.outcome.kind === "completed" && result.outcome.exitStatus.code === 0) {
1302
1300
  delete groups.active;
package/dist/server.mjs CHANGED
@@ -17572,12 +17572,12 @@ var Session = class {
17572
17572
  * persisted before transmission; a transport loss leaves the submission
17573
17573
  * inspectable as uncertain, never replayed.
17574
17574
  */
17575
- async exec(argv2, options = {}) {
17575
+ async exec(argv, options = {}) {
17576
17576
  const executionId = formatId(allocateId("execution"));
17577
17577
  const submission = {
17578
17578
  executionId,
17579
17579
  sessionId: this.sessionId,
17580
- argv: argv2,
17580
+ argv,
17581
17581
  submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
17582
17582
  state: "pending"
17583
17583
  };
@@ -17587,7 +17587,7 @@ var Session = class {
17587
17587
  attemptId: "attempt-1",
17588
17588
  kind: "exec",
17589
17589
  executionId,
17590
- argv: argv2,
17590
+ argv,
17591
17591
  cwd: options.cwd,
17592
17592
  step: options.step,
17593
17593
  snapshots: options.snapshots
@@ -17613,11 +17613,11 @@ var Session = class {
17613
17613
  const upload = await this.transport.upload(localPath, { remotePath });
17614
17614
  const executionId = formatId(allocateId("execution"));
17615
17615
  const interpreter = language2 === "python" ? "python3" : language2 === "typescript" ? "tsx" : "node";
17616
- const argv2 = [interpreter, ...options.interpreterArgs ?? [], remotePath];
17616
+ const argv = [interpreter, ...options.interpreterArgs ?? [], remotePath];
17617
17617
  const submission = {
17618
17618
  executionId,
17619
17619
  sessionId: this.sessionId,
17620
- argv: argv2,
17620
+ argv,
17621
17621
  submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
17622
17622
  state: "pending",
17623
17623
  script: {
@@ -17635,7 +17635,7 @@ var Session = class {
17635
17635
  executionId,
17636
17636
  remotePath,
17637
17637
  language: language2,
17638
- argv: argv2,
17638
+ argv,
17639
17639
  cwd: options.cwd,
17640
17640
  step: options.step,
17641
17641
  snapshots: options.snapshots,
@@ -18331,20 +18331,20 @@ async function inventory(root) {
18331
18331
  await walk(root);
18332
18332
  return result2;
18333
18333
  }
18334
- async function command(argv2, options = {}) {
18334
+ async function command(argv, options = {}) {
18335
18335
  options.signal?.throwIfAborted();
18336
18336
  return new Promise((resolve11, reject) => {
18337
- const child = spawn3(argv2[0], argv2.slice(1), { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"], signal: options.signal });
18337
+ const child = spawn3(argv[0], argv.slice(1), { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"], signal: options.signal });
18338
18338
  let stdout = "", stderr = "", size = 0;
18339
18339
  let failure2;
18340
18340
  const timer = setTimeout(() => {
18341
- failure2 = new Error(`Command timed out: ${argv2[0]}`);
18341
+ failure2 = new Error(`Command timed out: ${argv[0]}`);
18342
18342
  child.kill("SIGKILL");
18343
18343
  }, options.timeoutMs ?? 1e4);
18344
18344
  const consume = (channel, chunk) => {
18345
18345
  size += chunk.length;
18346
18346
  if (size > (options.maxBytes ?? 128 * 1024)) {
18347
- failure2 = new Error(`Command output exceeded limit: ${argv2[0]}`);
18347
+ failure2 = new Error(`Command output exceeded limit: ${argv[0]}`);
18348
18348
  child.kill("SIGKILL");
18349
18349
  return;
18350
18350
  }
@@ -18596,8 +18596,8 @@ var Transfer = class {
18596
18596
  }
18597
18597
  }
18598
18598
  }
18599
- async checked(argv2, timeoutMs2, signal) {
18600
- const framed = argv2[0] === this.node && argv2[1] === "-e" ? [argv2[0], argv2[1], `try { ${argv2[2]} } catch(error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode=1; }`, ...argv2.slice(3)] : argv2;
18599
+ async checked(argv, timeoutMs2, signal) {
18600
+ const framed = argv[0] === this.node && argv[1] === "-e" ? [argv[0], argv[1], `try { ${argv[2]} } catch(error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode=1; }`, ...argv.slice(3)] : argv;
18601
18601
  for (let attempt = 1; ; attempt++) {
18602
18602
  const result2 = await (signal ? this.vm.exec(this.name, framed, timeoutMs2, { signal, ...timeoutMs2 ? { timeoutMs: timeoutMs2 } : {} }) : this.vm.exec(this.name, framed, timeoutMs2));
18603
18603
  if (result2.code === 0) return result2.stdout;
@@ -18988,8 +18988,8 @@ var Transfer = class {
18988
18988
  await assertHostPath(localRoot, local);
18989
18989
  const staging = await mkdtemp(join7(local, ".relay-archive-"));
18990
18990
  try {
18991
- const argv2 = [this.node, "-e", ARCHIVE, remote, approvedRoot, archive, guestRoot, options.present ? "present" : "all", ...chunk.map((file) => file.path)];
18992
- const fact = JSON.parse(await this.checked(argv2, scanTimeoutMs(2 * (bytes ?? 0)), options.signal));
18991
+ const argv = [this.node, "-e", ARCHIVE, remote, approvedRoot, archive, guestRoot, options.present ? "present" : "all", ...chunk.map((file) => file.path)];
18992
+ const fact = JSON.parse(await this.checked(argv, scanTimeoutMs(2 * (bytes ?? 0)), options.signal));
18993
18993
  const size = fact?.bytes;
18994
18994
  if (fact?.path !== archive || !Number.isSafeInteger(size) || bytes !== void 0 && size !== bytes) throw new Error("Invalid remote archive fact");
18995
18995
  const staged = join7(staging, "archive");
@@ -19125,7 +19125,8 @@ var VmTransport = class {
19125
19125
  if (!this.because.trim()) throw new Error("Run execution intent is required");
19126
19126
  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,159}$/.test(request.executionId)) throw new Error("Invalid execution identity");
19127
19127
  this.response = void 0;
19128
- const payload = { ...request, because: this.because, timeoutMs: this.timeoutMs, ...this.diagnostic ? { diagnostic: true } : {}, ...this.capture ? {} : { capture: false } };
19128
+ const { kind: _kind, argv: _argv, ...framed } = request;
19129
+ const payload = { ...framed, because: this.because, timeoutMs: this.timeoutMs, ...this.diagnostic ? { diagnostic: true } : {}, ...this.capture ? {} : { capture: false } };
19129
19130
  const local = join8(this.hostRoot, "requests", `${request.executionId}.json`);
19130
19131
  const remote = join8(this.guestRoot, "requests", `${request.executionId}.json`);
19131
19132
  await assertHostPath(this.hostRoot, local, true);
@@ -19421,12 +19422,12 @@ async function analyze(root, options, files) {
19421
19422
  const actionReceipts = receipts.filter((r) => (r.actionId === id2 || executionId && r.executionId === executionId) && (r.actionId === void 0 || r.actionId === id2) && (r.executionId === void 0 || executionId === void 0 || r.executionId === executionId));
19422
19423
  execution2 = reconcileOutcome(execution2, actionReceipts);
19423
19424
  const completion = completions.get(id2);
19424
- const argv2 = events.find((e) => e.kind === "execution-start" && executionId && e.executionId === executionId && Array.isArray(e.argv))?.argv;
19425
+ const argv = events.find((e) => e.kind === "execution-start" && executionId && e.executionId === executionId && Array.isArray(e.argv))?.argv;
19425
19426
  details.set(stepId2, {
19426
19427
  at: source.writtenAt ?? before?.capturedAt,
19427
19428
  beforeAt: before?.capturedAt,
19428
19429
  afterAt: after?.capturedAt,
19429
- ...argv2?.every((w) => typeof w === "string") ? { argv: argv2 } : {},
19430
+ ...argv?.every((w) => typeof w === "string") ? { argv } : {},
19430
19431
  output: commandOutput(actionReceipts.find((r) => commandOutput(r)) ?? completion?.toolOutcome?.value)
19431
19432
  });
19432
19433
  const originalObserved = refusal?.diagnostic ?? completion?.diagnostic ?? (completion?.toolOutcome ? JSON.stringify(completion.toolOutcome) : void 0);
@@ -19609,13 +19610,13 @@ async function verifyDeliveredPackage(rootDir) {
19609
19610
 
19610
19611
  // src/probe.ts
19611
19612
  async function probeLocal(run = command, platform = process.platform) {
19612
- async function observe(argv2, parse7) {
19613
+ async function observe(argv, parse7) {
19613
19614
  try {
19614
- const result2 = await run(argv2);
19615
+ const result2 = await run(argv);
19615
19616
  if (result2.code) throw new Error(result2.stderr || `exit ${result2.code}`);
19616
- return { value: parse7(result2.stdout), source: argv2.join(" ") };
19617
+ return { value: parse7(result2.stdout), source: argv.join(" ") };
19617
19618
  } catch (error2) {
19618
- return { value: null, source: argv2.join(" "), diagnostic: String(error2) };
19619
+ return { value: null, source: argv.join(" "), diagnostic: String(error2) };
19619
19620
  }
19620
19621
  }
19621
19622
  const permissions = await observe(["cua-driver", "permissions", "status", "--json"], JSON.parse);
@@ -28000,7 +28001,7 @@ async function prepareImage(bytes, mimeType) {
28000
28001
  // src/guest/image-evidence.ts
28001
28002
  var safeId = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,159}$/.test(value);
28002
28003
  function afterRequested(request) {
28003
- return !(request?.kind === "exec" && request.diagnostic === true) && request?.capture !== false && !["first", "member"].includes(request?.snapshots?.group?.phase ?? "");
28004
+ return request?.diagnostic !== true && request?.capture !== false && !["first", "member"].includes(request?.snapshots?.group?.phase ?? "");
28004
28005
  }
28005
28006
  function validateImageEvidence(value, request, authoritativeSnapshots) {
28006
28007
  const fail2 = () => {
@@ -28736,6 +28737,7 @@ async function refreshEvidenceState(incoming, destination, archiveRoot, options
28736
28737
  }
28737
28738
 
28738
28739
  // src/manager.ts
28740
+ var SCRIPT_EXTENSIONS = { shell: "sh", javascript: "js", typescript: "ts", python: "py" };
28739
28741
  var RENEWAL_WINDOW_MS = 15 * 6e4;
28740
28742
  var MIN_RENEWAL_MS = 0.1 * 36e5;
28741
28743
  var DEFAULT_AFTER_INTERVAL_MS = 500;
@@ -28754,7 +28756,7 @@ async function settleEach(work) {
28754
28756
  const failed = (await Promise.allSettled(work)).find((result2) => result2.status === "rejected");
28755
28757
  if (failed) throw failed.reason;
28756
28758
  }
28757
- var instructions = "This server offers fifteen tools for guests, VMs that run the work you choose to run there: relay_search, relay_probe, relay_acquisition_capabilities, relay_acquire, relay_stage, the run tools relay_command and relay_script, relay_image, relay_extract, relay_finish, relay_release, relay_console_resolve, relay_console_open, relay_console_cancel and relay_status. relay_command runs one command; relay_script runs a JavaScript, TypeScript or Python script, given inline or as a project file, and the script drives whatever the image lists, such as cua-driver, Playwright or Chrome DevTools, through their own libraries or command lines. Staging needs only Node.js in the guest, and a run takes before and after snapshots only when the image lists capture software (cua-driver). Evidence is automatic, and a run's after-image is returned as pending and downloaded in the background, so call relay_image with the imageId when you need to see it. Acquire one guest for each machine your work needs; several guests may run at once, up to the session's limit that relay_status reports. relay_acquire answers each guest's name, `guest`, and every call that acts on a guest names it with `guest`. Calls on different guests run at the same time; calls on one guest keep their order. Work each guest in order: relay_probe, then relay_acquire, then relay_stage, then relay_command or relay_script, then relay_image or relay_extract as needed, then relay_finish or relay_release; finishing or releasing one guest leaves the others running. Always call relay_finish or relay_release explicitly for every guest before you return an answer; ending the session never finishes a guest: it pauses lease renewal and keeps the VMs or, where the relay is set up to, releases them, and the backend's own expiry is the last-resort safeguard. A refused, uncertain or nonzero operation keeps the VM so you can diagnose and submit a corrected operation; never replay input whose effect is uncertain. A tool result, an attached image or a verified evidence package, is evidence for a human reviewer, never the review itself. The relay never targets a physical or local display and offers no video or spawn API. Every tool's text result is capped at 50 KiB / 2000 lines; a larger result is retained whole in a local file the result names.";
28759
+ var instructions = "This server offers fourteen tools for guests, VMs that run the work you choose to run there: relay_search, relay_probe, relay_acquisition_capabilities, relay_acquire, relay_stage, the run tool relay_script, relay_image, relay_extract, relay_finish, relay_release, relay_console_resolve, relay_console_open, relay_console_cancel and relay_status. relay_script runs a shell, JavaScript, TypeScript or Python script, given inline or as a project file; a command is a shell script, and the script drives whatever the image lists, such as cua-driver, Playwright or Chrome DevTools, through their own libraries or command lines. Staging needs only Node.js in the guest, and a run takes before and after snapshots only when the image lists capture software (cua-driver). Evidence is automatic, and a run's after-image is returned as pending and downloaded in the background, so call relay_image with the imageId when you need to see it. Acquire one guest for each machine your work needs; several guests may run at once, up to the session's limit that relay_status reports. relay_acquire answers each guest's name, `guest`, and every call that acts on a guest names it with `guest`. Calls on different guests run at the same time; calls on one guest keep their order. Work each guest in order: relay_probe, then relay_acquire, then relay_stage, then relay_script, then relay_image or relay_extract as needed, then relay_finish or relay_release; finishing or releasing one guest leaves the others running. Always call relay_finish or relay_release explicitly for every guest before you return an answer; ending the session never finishes a guest: it pauses lease renewal and keeps the VMs or, where the relay is set up to, releases them, and the backend's own expiry is the last-resort safeguard. A refused, uncertain or nonzero operation keeps the VM so you can diagnose and submit a corrected operation; never replay input whose effect is uncertain. A tool result, an attached image or a verified evidence package, is evidence for a human reviewer, never the review itself. The relay never targets a physical or local display and offers no video or spawn API. Every tool's text result is capped at 50 KiB / 2000 lines; a larger result is retained whole in a local file the result names.";
28758
28760
  var NO_OWNED_LEASE = "This session owns no lease: it holds no guest, so nothing was released. Each server process has its own session identity (a new random one unless MCP_RELAY_SESSION sets it); a lease acquired under another identity is not visible here. Restart the server with that MCP_RELAY_SESSION to reconcile and release it, or let the backend TTL expire it.";
28759
28761
  var RelayManager = class {
28760
28762
  constructor(options) {
@@ -28772,8 +28774,8 @@ var RelayManager = class {
28772
28774
  this.registry = options.registry ?? new Registry(this.environment ? { managedRoot: this.environment.profile.relayStateDir } : {});
28773
28775
  this.root = join13(this.environment?.profile.relayStateDir ?? options.stateRoot ?? relayStateRoot(), hash(options.sessionId).slice(0, 32));
28774
28776
  this.channel = {
28775
- exec: async (name, argv2, timeoutMs2 = 18e4, options2) => {
28776
- const result2 = await this.vm.exec(name, { argv: argv2, timeout: Math.ceil(timeoutMs2 / 1e3) }, { timeoutMs: options2?.timeoutMs ?? timeoutMs2 + 3e4, signal: options2?.signal });
28777
+ exec: async (name, argv, timeoutMs2 = 18e4, options2) => {
28778
+ const result2 = await this.vm.exec(name, { argv, timeout: Math.ceil(timeoutMs2 / 1e3) }, { timeoutMs: options2?.timeoutMs ?? timeoutMs2 + 3e4, signal: options2?.signal });
28777
28779
  return { stdout: result2.output, stderr: result2.output, code: result2.rc };
28778
28780
  },
28779
28781
  push: (name, local_path, remote_path) => this.vm.push(name, { local_path, remote_path }),
@@ -29347,10 +29349,10 @@ var Guest = class {
29347
29349
  async probe() {
29348
29350
  const e = this.current();
29349
29351
  const checks = [];
29350
- for (const [name, language2, argv2] of [["node", "javascript", [e.node ?? "node", "--version"]], ["tsx", "typescript", ["tsx", "--version"]], ["python3", "python", ["python3", "--version"]]]) {
29352
+ for (const [name, language2, argv] of [["node", "javascript", [e.node ?? "node", "--version"]], ["tsx", "typescript", ["tsx", "--version"]], ["python3", "python", ["python3", "--version"]], ["sh", "shell", ["/bin/sh", "-c", "exit 0"]]]) {
29351
29353
  const required2 = name === "node";
29352
29354
  try {
29353
- const r = await this.m.channel.exec(e.lease.vm, [...argv2], 1e4);
29355
+ const r = await this.m.channel.exec(e.lease.vm, [...argv], 1e4);
29354
29356
  checks.push({ name, language: language2, required: required2, ...r, ready: r.code === 0 });
29355
29357
  } catch (error2) {
29356
29358
  checks.push({ name, language: language2, required: required2, ready: false, diagnostic: String(error2) });
@@ -29368,7 +29370,7 @@ var Guest = class {
29368
29370
  software = { image: e.image, diagnostic: `The image catalog could not be read: ${message(error2)}` };
29369
29371
  }
29370
29372
  const snapshots2 = e.capture === void 0 && !e.staged ? { taken: null, reason: "Decided at relay_stage: runs take snapshots only when the image lists capture software (cua-driver)." } : this.snapshotFacts(e);
29371
- const facts = { scope: "guest", guest: this.name, observedAt: (/* @__PURE__ */ new Date()).toISOString(), owned: this.status(), checks, software, snapshots: snapshots2, note: "A ready runtime means its --version exited 0. Listed software is what the catalog says the image holds; it never proves that a program runs, that a browser renders on the display or that capture works.", captureVerified: false, browserVerified: false };
29373
+ const facts = { scope: "guest", guest: this.name, observedAt: (/* @__PURE__ */ new Date()).toISOString(), owned: this.status(), checks, software, snapshots: snapshots2, note: "A ready runtime means its --version, or for /bin/sh `exit 0`, exited 0. Listed software is what the catalog says the image holds; it never proves that a program runs, that a browser renders on the display or that capture works.", captureVerified: false, browserVerified: false };
29372
29374
  await this.log("guest-readiness", void 0, facts);
29373
29375
  return facts;
29374
29376
  }
@@ -29683,7 +29685,7 @@ VM state: ${JSON.stringify(this.status())}`, { cause: error2 });
29683
29685
  const e = this.current();
29684
29686
  if (e.delivered) throw new Error("Evidence already sealed; release this VM explicitly");
29685
29687
  if (input.resetRecording || e.pendingReset) await this.resetRecording();
29686
- if (e.staged && (input.workspace || input.files?.length)) throw new Error("Runtime already staged; use relay_command with diagnostic: true for repairs, or stage with only corrected executable paths");
29688
+ if (e.staged && (input.workspace || input.files?.length)) throw new Error("Runtime already staged; use a shell relay_script with diagnostic: true for repairs, or stage with only corrected executable paths");
29687
29689
  const project = resolve9(this.m.options.project);
29688
29690
  const files = [];
29689
29691
  for (const file of input.files ?? []) files.push({ local: await this.m.projectPath(file.local, "files[].local"), path: file.path });
@@ -29762,7 +29764,7 @@ VM state: ${JSON.stringify(this.status())}`, { cause: error2 });
29762
29764
  } catch (error2) {
29763
29765
  if (signal?.aborted) throw error2;
29764
29766
  const waited = Date.now() - since;
29765
- if (waited + retryMs > waitMs) throw new Error(`relay_stage waited ${Math.round(waited / 1e3)} s for ${e.image}'s cua-driver to take a screenshot, which each run's before and after snapshots need, and it never did: ${message(error2)}. Diagnose or start it with relay_command and diagnostic: true, such as \`${cuaDriver} serve\` on Linux, then call relay_stage again.`, { cause: error2 });
29767
+ if (waited + retryMs > waitMs) throw new Error(`relay_stage waited ${Math.round(waited / 1e3)} s for ${e.image}'s cua-driver to take a screenshot, which each run's before and after snapshots need, and it never did: ${message(error2)}. Diagnose or start it with a shell relay_script and diagnostic: true, such as \`${cuaDriver} serve\` on Linux, then call relay_stage again.`, { cause: error2 });
29766
29768
  await new Promise((done) => {
29767
29769
  const timer = setTimeout(done, retryMs);
29768
29770
  signal?.addEventListener("abort", () => {
@@ -29782,11 +29784,11 @@ VM state: ${JSON.stringify(this.status())}`, { cause: error2 });
29782
29784
  const e = this.current();
29783
29785
  const timeoutMs2 = input.timeoutMs ?? 12e4;
29784
29786
  if (!Number.isSafeInteger(timeoutMs2) || timeoutMs2 < 1 || timeoutMs2 > 36e5) throw new Error("timeoutMs must be an integer from 1 to 3600000");
29785
- if (input.diagnostic && input.kind !== "exec") throw new Error("diagnostic is only supported for relay_command");
29787
+ if (input.diagnostic && input.language !== "shell") throw new Error("Only a shell script may be diagnostic, because a diagnostic run goes through vm-service without the receiver");
29786
29788
  if (e.delivered) throw new Error("Evidence already sealed; release this VM explicitly");
29787
29789
  if (input.diagnostic) return this.diagnostic(input, timeoutMs2, signal);
29788
- if (e.pendingReset) throw new Error("Recording reset is pending; retry stage to reconcile it, or use relay_command with diagnostic: true");
29789
- if (!e.staged || !this.session || !this.transport) throw new Error("Use relay_stage before a run, or relay_command with diagnostic: true for setup diagnosis and repair");
29790
+ if (e.pendingReset) throw new Error("Recording reset is pending; retry stage to reconcile it, or use a shell relay_script with diagnostic: true");
29791
+ if (!e.staged || !this.session || !this.transport) throw new Error("Use relay_stage before a run, or a shell relay_script with diagnostic: true for setup diagnosis and repair");
29790
29792
  const record3 = this.derive(e, input);
29791
29793
  await this.save();
29792
29794
  this.transport.because = record3.because;
@@ -29795,20 +29797,14 @@ VM state: ${JSON.stringify(this.status())}`, { cause: error2 });
29795
29797
  this.transport.signal = signal;
29796
29798
  const options = { step: record3.step, snapshots: record3.snapshots, cwd: join13(e.guestRoot, "workspace") };
29797
29799
  let result2;
29798
- if (input.kind === "exec") {
29799
- if (!input.argv?.length) throw new Error("relay_command requires argv");
29800
- result2 = await this.session.exec(input.argv, options);
29801
- } else if (input.kind === "script") {
29802
- if (!input.language) throw new Error("relay_script requires language");
29803
- if (input.inline) {
29804
- if (typeof input.code !== "string" || input.localPath !== void 0) throw new Error("relay_script with inline: true takes the script as code, and no localPath");
29805
- result2 = await this.session.runCode(input.code, input.language, options);
29806
- } else {
29807
- if (!input.localPath || input.code !== void 0) throw new Error("relay_script with inline: false takes the script file as localPath, and no code");
29808
- const local = await this.m.projectPath(input.localPath, "localPath");
29809
- result2 = await this.session.runScript(local, join13(e.guestRoot, "scripts", `${randomUUID6()}.${input.language === "python" ? "py" : input.language === "typescript" ? "ts" : "js"}`), input.language, options);
29810
- }
29811
- } else throw new Error("Unknown operation kind");
29800
+ if (input.inline) {
29801
+ if (typeof input.code !== "string" || input.localPath !== void 0) throw new Error("relay_script with inline: true takes the script as code, and no localPath");
29802
+ result2 = await this.session.runCode(input.code, input.language, options);
29803
+ } else {
29804
+ if (!input.localPath || input.code !== void 0) throw new Error("relay_script with inline: false takes the script file as localPath, and no code");
29805
+ const local = await this.m.projectPath(input.localPath, "localPath");
29806
+ result2 = await this.session.runScript(local, join13(e.guestRoot, "scripts", `${randomUUID6()}.${SCRIPT_EXTENSIONS[input.language]}`), input.language, options);
29807
+ }
29812
29808
  const outcome = result2.outcome;
29813
29809
  if (outcome.kind !== "completed" || outcome.exitStatus.code !== 0 || outcome.exitStatus.signal) {
29814
29810
  await this.log("execution-failed", record3.because, result2);
@@ -29823,19 +29819,20 @@ VM state: ${JSON.stringify(this.status())}`, { cause: error2 });
29823
29819
  }
29824
29820
  /**
29825
29821
  * The step record for a run, from the call itself: a title such as
29826
- * `exec node -e …`, an expected result, an input mode, a default
29822
+ * `shell ls -al`, `code (python)` or `script check.py`, an expected result, an input mode, a default
29827
29823
  * after-snapshot wait and a reason. Anything the caller gave overrides it.
29828
29824
  */
29829
29825
  derive(e, input) {
29830
29826
  const seq = e.runSeq = (e.runSeq ?? 0) + 1;
29831
29827
  const stepId2 = (prefix) => `${prefix.replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^[^A-Za-z0-9]+/, "").slice(0, 100) || "run"}-${seq}`;
29832
- const title = input.step?.title ?? (input.kind === "exec" ? `exec ${(input.argv ?? []).map((arg, index) => index === 0 ? arg.split("/").at(-1) : arg).join(" ")}` : input.inline ? `code (${input.language ?? "unknown"})` : `script ${input.localPath?.split("/").at(-1) ?? ""}`).slice(0, 500);
29828
+ const firstLine = input.code?.split("\n").find((line) => line.trim())?.trim();
29829
+ const title = input.step?.title ?? (input.inline ? input.language === "shell" && firstLine ? `shell ${firstLine}` : `code (${input.language})` : `script ${input.localPath?.split("/").at(-1) ?? ""}`).slice(0, 500);
29833
29830
  const snapshots2 = { ...input.snapshots ?? {} };
29834
29831
  const group = snapshots2.group;
29835
29832
  if (!group ? snapshots2.afterIntervalMs === void 0 : group.phase === "last" && group.afterIntervalMs === void 0 && snapshots2.afterIntervalMs === void 0) Object.assign(snapshots2, { afterIntervalMs: DEFAULT_AFTER_INTERVAL_MS });
29836
29833
  return {
29837
29834
  because: input.because ?? `Relay ${title} (no reason given)`.slice(0, 4e3),
29838
- step: { id: input.step?.id ?? stepId2(input.kind === "exec" ? "exec" : input.inline ? "code" : "script"), title: title || input.kind, expected: input.step?.expected ?? "Exits with status 0", inputMode: input.step?.inputMode ?? "ordinary" },
29835
+ step: { id: input.step?.id ?? stepId2(input.inline ? "code" : "script"), title: title || "script", expected: input.step?.expected ?? "Exits with status 0", inputMode: input.step?.inputMode ?? "ordinary" },
29839
29836
  snapshots: snapshots2
29840
29837
  };
29841
29838
  }
@@ -30163,15 +30160,17 @@ VM state: ${JSON.stringify(this.status())}`, { cause: error2 });
30163
30160
  }
30164
30161
  async diagnostic(input, timeoutMs2, signal) {
30165
30162
  const e = this.current();
30166
- if (!input.argv?.length || input.snapshots?.group) throw new Error("Diagnostic exec requires argv and cannot join a snapshot group");
30163
+ if (input.language !== "shell" || input.snapshots?.group) throw new Error("A diagnostic run is a shell script and cannot join a snapshot group");
30164
+ const script = input.inline ? input.code : await readFile9(await this.m.projectPath(input.localPath ?? "", "localPath"), "utf8");
30165
+ if (typeof script !== "string") throw new Error("relay_script with inline: true takes the script as code, and no localPath");
30167
30166
  const executionId = `diagnostic-${randomUUID6()}`;
30168
30167
  const { guest: _guest, ...requested } = input;
30169
- const request = { executionId, at: (/* @__PURE__ */ new Date()).toISOString(), evidenceMode: "diagnostic", timeoutMs: timeoutMs2, ...requested };
30168
+ const argv = e.staged ? ["/bin/sh", "-c", 'cd "$1" || exit; shift; exec "$@"', "relay-diagnostic", join13(e.guestRoot, "workspace"), "/bin/sh", "-c", script] : ["/bin/sh", "-c", script];
30169
+ const request = { executionId, at: (/* @__PURE__ */ new Date()).toISOString(), evidenceMode: "diagnostic", timeoutMs: timeoutMs2, ...requested, argv };
30170
30170
  await jsonFile(join13(e.hostRoot, "host", "diagnostics", `${executionId}.request.json`), request);
30171
30171
  let result2;
30172
30172
  try {
30173
- const argv2 = e.staged ? ["/bin/sh", "-c", 'cd "$1" || exit; shift; exec "$@"', "relay-diagnostic", join13(e.guestRoot, "workspace"), ...input.argv] : input.argv;
30174
- const r = await this.m.channel.exec(e.lease.vm, argv2, timeoutMs2, { signal });
30173
+ const r = await this.m.channel.exec(e.lease.vm, argv, timeoutMs2, { signal });
30175
30174
  result2 = { executionId, outcome: { kind: "completed", exitStatus: { code: r.code, signal: null } }, output: r.stdout, outputStreams: "stdout and stderr combined" };
30176
30175
  } catch (error2) {
30177
30176
  result2 = { executionId, outcome: { kind: "uncertain", diagnostic: String(error2) }, output: "", outputStreams: "stdout and stderr combined" };
@@ -30355,8 +30354,7 @@ var imageTarget = typebox_exports.Union([
30355
30354
  typebox_exports.Object({ source: typebox_exports.Literal("application"), name: typebox_exports.String({ minLength: 1, maxLength: 101 }), path: typebox_exports.Optional(typebox_exports.String({ minLength: 1, maxLength: 4096 })) }, closed2),
30356
30355
  typebox_exports.Object({ source: typebox_exports.Literal("reference"), imageId: typebox_exports.String({ pattern: "^image-[a-f0-9]{64}$" }) }, closed2)
30357
30356
  ]);
30358
- var argv = typebox_exports.Array(typebox_exports.String(), { minItems: 1, maxItems: 256 });
30359
- var language = StringEnum(["javascript", "typescript", "python"]);
30357
+ var language = StringEnum(["shell", "javascript", "typescript", "python"]);
30360
30358
  var timeoutMs = typebox_exports.Optional(typebox_exports.Integer({ minimum: 1, maximum: 36e5, description: "Execution timeout in milliseconds, default 120000, maximum 3600000. Independent of snapshot delay and lease TTL." }));
30361
30359
  var runBase = { action: typebox_exports.Literal("run"), guest, reason: optionalReason, step: typebox_exports.Optional(step), snapshots: typebox_exports.Optional(snapshots), timeoutMs };
30362
30360
  var relayContract = typebox_exports.Union([
@@ -30385,15 +30383,14 @@ var relayContract = typebox_exports.Union([
30385
30383
  nodePath: typebox_exports.Optional(typebox_exports.String({ description: "Guest Node executable, default node; use image nvm path if needed." })),
30386
30384
  cuaDriver: typebox_exports.Optional(typebox_exports.String({ description: "Guest CUA executable; OS default when omitted." }))
30387
30385
  }, closed2),
30388
- typebox_exports.Object({ ...runBase, kind: typebox_exports.Literal("exec"), argv, diagnostic: typebox_exports.Optional(typebox_exports.Boolean({ description: "Explicit command diagnosis or repair without screenshot evidence, including before staging. Commands and outcomes remain recorded. Never claim visual verification." })) }, closed2),
30389
- // One branch for relay_script: `inline` selects which of `code` and `localPath` the call gives, checked in validateRelayInput.
30386
+ // The one run branch, relay_script (DC-26): `inline` selects which of `code` and `localPath` the call gives, and `diagnostic` needs `shell`, both checked in validateRelayInput.
30390
30387
  typebox_exports.Object({
30391
30388
  ...runBase,
30392
- kind: typebox_exports.Literal("script"),
30393
30389
  language,
30394
30390
  inline: typebox_exports.Boolean({ description: "true: the script is `code`, given inline. false: the script is the host file `localPath`. Give exactly the one that inline names." }),
30395
30391
  code: typebox_exports.Optional(typebox_exports.String({ maxLength: 1048576, description: "With inline: true, the script itself, up to 1 MiB." })),
30396
- localPath: typebox_exports.Optional(typebox_exports.String({ minLength: 1, description: "With inline: false, a host script file in the project folder: relative to it, or absolute inside it; no symlinks." }))
30392
+ localPath: typebox_exports.Optional(typebox_exports.String({ minLength: 1, description: "With inline: false, a host script file in the project folder: relative to it, or absolute inside it; no symlinks." })),
30393
+ diagnostic: typebox_exports.Optional(typebox_exports.Boolean({ description: "Shell scripts only: explicit diagnosis or repair without screenshot evidence, including before staging. The script and its outcome remain recorded. Never claim visual verification." }))
30397
30394
  }, closed2),
30398
30395
  typebox_exports.Object({ action: typebox_exports.Literal("image"), guest, target: imageTarget }, closed2),
30399
30396
  typebox_exports.Object({ action: typebox_exports.Literal("extract"), guest, names: typebox_exports.Array(typebox_exports.String()) }, closed2),
@@ -30411,28 +30408,25 @@ for (const branch of relayContract.anyOf) {
30411
30408
  var parameterObject = typebox_exports.Object({
30412
30409
  action: StringEnum(["search", "probe", "acquire", "stage", "run", "image", "extract", "finish", "release", "acquisition-capabilities", "console-resolve", "console-open", "console-cancel"]),
30413
30410
  ...projected
30414
- }, { ...closed2, anyOf: relayContract.anyOf, description: "Select exactly one action. Each closed branch defines allowed fields. Run selects a kind; console-open requires reason, expected and userRequested=true. No default action." });
30411
+ }, { ...closed2, anyOf: relayContract.anyOf, description: "Select exactly one action. Each closed branch defines allowed fields. Run takes a script; console-open requires reason, expected and userRequested=true. No default action." });
30415
30412
  var relayParameters = typebox_exports.Unsafe(parameterObject);
30416
- function branchFor(action, kind) {
30417
- const found = relayContract.anyOf.find((branch) => {
30418
- const properties = branch.properties;
30419
- if (properties.action.const !== action) return false;
30420
- return kind === void 0 ? properties.kind === void 0 : properties.kind?.const === kind;
30421
- });
30422
- if (!found) throw new Error(`No contract branch for action ${action}${kind ? ` kind ${kind}` : ""}`);
30413
+ function branchFor(action) {
30414
+ const found = relayContract.anyOf.find((branch) => branch.properties.action.const === action);
30415
+ if (!found) throw new Error(`No contract branch for action ${action}`);
30423
30416
  return found;
30424
30417
  }
30425
- function toolInputSchema(action, kind) {
30426
- const raw = JSON.parse(JSON.stringify(branchFor(action, kind)));
30427
- const { action: _action, kind: _kind, ...properties } = raw.properties;
30428
- const required2 = (raw.required ?? []).filter((key) => key !== "action" && key !== "kind");
30418
+ function toolInputSchema(action) {
30419
+ const raw = JSON.parse(JSON.stringify(branchFor(action)));
30420
+ const { action: _action, ...properties } = raw.properties;
30421
+ const required2 = (raw.required ?? []).filter((key) => key !== "action");
30429
30422
  return { type: raw.type, properties, ...required2.length ? { required: required2 } : {}, additionalProperties: raw.additionalProperties ?? false };
30430
30423
  }
30431
30424
  function validateRelayInput(value) {
30432
- if (!Check2(relayContract, value)) throw new Error("Invalid relay input: action is required; a call that acts on a guest names it with guest, the name relay_acquire answered; console-open requires nonblank reason. Supply only the fields for the selected action and run kind.");
30425
+ if (!Check2(relayContract, value)) throw new Error("Invalid relay input: action is required; a call that acts on a guest names it with guest, the name relay_acquire answered; console-open requires nonblank reason. Supply only the fields for the selected action.");
30433
30426
  if (value.action === "probe" && value.scope === "guest" && value.guest === void 0) throw new Error('Invalid relay input: relay_probe with scope "guest" names the guest to probe with guest, the name relay_acquire answered.');
30434
- if (value.action === "run" && value.kind === "exec" && value.diagnostic && value.snapshots?.group) throw new Error("Diagnostic commands cannot join snapshot groups.");
30435
- if (value.action === "run" && value.kind === "script") {
30427
+ if (value.action === "run") {
30428
+ if (value.diagnostic && value.language !== "shell") throw new Error("Invalid relay input: only a shell script may be diagnostic, because a diagnostic run goes through vm-service without the receiver.");
30429
+ if (value.diagnostic && value.snapshots?.group) throw new Error("Diagnostic scripts cannot join snapshot groups.");
30436
30430
  const given = value.inline ? value.code : value.localPath, other = value.inline ? value.localPath : value.code;
30437
30431
  if (given === void 0 || other !== void 0) throw new Error(value.inline ? "Invalid relay input: relay_script with inline: true takes the script as code, and no localPath." : "Invalid relay input: relay_script with inline: false takes the script file as localPath, and no code.");
30438
30432
  }
@@ -30445,7 +30439,6 @@ import { tmpdir as tmpdir2 } from "node:os";
30445
30439
  import { randomUUID as randomUUID7 } from "node:crypto";
30446
30440
  var readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
30447
30441
  var acts = (openWorld, destructive = false) => ({ readOnlyHint: false, destructiveHint: destructive, idempotentHint: false, openWorldHint: openWorld });
30448
- var runShared = "Evidence is automatic, as for relay_command, whose optional `reason`, `step`, `snapshots` and `timeoutMs` it shares.";
30449
30442
  var relayTools = [
30450
30443
  {
30451
30444
  name: "relay_search",
@@ -30459,7 +30452,7 @@ var relayTools = [
30459
30452
  action: "probe",
30460
30453
  title: "Probe host and guest readiness",
30461
30454
  annotations: readOnly,
30462
- description: 'Read-only host and service facts, used to pick an image; it reports current owned state on its own, so call it again after context compaction rather than trusting earlier messages. Default `scope: "host"` reports host permissions and activity, VM service availability, and every guest this session holds with its state, not guest readiness. `scope: "guest"` with `guest` (an already-acquired guest) reports whether Node.js, which staging requires, is available, and, as facts, whether each relay_script language\'s runtime runs (`node`, `tsx`, `python3`), the software the image lists in the catalog, and whether this lease\'s runs take snapshots, without installing or starting anything, and never claims capture readiness. Acquire one guest for each machine the work needs; several may run at once. Continue each guest in order: relay_acquire, relay_stage, relay_command or relay_script, relay_image/relay_extract, then relay_finish or relay_release, called explicitly for every guest before you return.'
30455
+ description: 'Read-only host and service facts, used to pick an image; it reports current owned state on its own, so call it again after context compaction rather than trusting earlier messages. Default `scope: "host"` reports host permissions and activity, VM service availability, and every guest this session holds with its state, not guest readiness. `scope: "guest"` with `guest` (an already-acquired guest) reports whether Node.js, which staging requires, is available, and, as facts, whether each relay_script language\'s runtime runs (`/bin/sh`, `node`, `tsx`, `python3`), the software the image lists in the catalog, and whether this lease\'s runs take snapshots, without installing or starting anything, and never claims capture readiness. Acquire one guest for each machine the work needs; several may run at once. Continue each guest in order: relay_acquire, relay_stage, relay_script, relay_image/relay_extract, then relay_finish or relay_release, called explicitly for every guest before you return.'
30463
30456
  },
30464
30457
  {
30465
30458
  name: "relay_acquisition_capabilities",
@@ -30473,7 +30466,7 @@ var relayTools = [
30473
30466
  action: "acquire",
30474
30467
  title: "Acquire a VM",
30475
30468
  annotations: acts(false),
30476
- description: "Acquire one fresh VM, a guest, and start its ownership heartbeat. The result's `guest` is the guest's name in this session, such as `login-test-1`; every later call on this guest names it with `guest`. Requires `task` (a short slug), `image` (a key from relay_probe or relay_search) and `extractions`: every output you intend to bring home, declared before any work (`[]` is allowed; nothing is extracted automatically). Optional `ttlHours` (default 4), `env` (a credential pack, never baked into images), `fullWorkspace` (opt in to deliver the whole workspace) and `vnc` (default false; only prepares console-sharing capacity, never opens a viewer). Acquire one guest for each machine the work needs: several guests may run at once, each with its own lease, evidence and finish, up to the session's limit (relay_status reports `maxGuests`, MCP_RELAY_MAX_GUESTS, default 4); an acquisition beyond it is refused with the names of the guests held. When the host is at capacity, such as at its limit on running macOS VMs, the acquisition waits for it, asking again every 15 s for up to MCP_RELAY_CAPACITY_WAIT (30 minutes by default), and the result's `waitedForCapacityMs` says how long it waited; once the wait runs out it is refused with the backend's reason and the time waited. The backend's other refusals pass through at once. Continue with relay_stage, relay_command or relay_script, relay_image/relay_extract, then relay_finish or relay_release explicitly before you return; a failed step keeps the VM for repair rather than replaying uncertain input."
30469
+ description: "Acquire one fresh VM, a guest, and start its ownership heartbeat. The result's `guest` is the guest's name in this session, such as `login-test-1`; every later call on this guest names it with `guest`. Requires `task` (a short slug), `image` (a key from relay_probe or relay_search) and `extractions`: every output you intend to bring home, declared before any work (`[]` is allowed; nothing is extracted automatically). Optional `ttlHours` (default 4), `env` (a credential pack, never baked into images), `fullWorkspace` (opt in to deliver the whole workspace) and `vnc` (default false; only prepares console-sharing capacity, never opens a viewer). Acquire one guest for each machine the work needs: several guests may run at once, each with its own lease, evidence and finish, up to the session's limit (relay_status reports `maxGuests`, MCP_RELAY_MAX_GUESTS, default 4); an acquisition beyond it is refused with the names of the guests held. When the host is at capacity, such as at its limit on running macOS VMs, the acquisition waits for it, asking again every 15 s for up to MCP_RELAY_CAPACITY_WAIT (30 minutes by default), and the result's `waitedForCapacityMs` says how long it waited; once the wait runs out it is refused with the backend's reason and the time waited. The backend's other refusals pass through at once. Continue with relay_stage, relay_script, relay_image/relay_extract, then relay_finish or relay_release explicitly before you return; a failed step keeps the VM for repair rather than replaying uncertain input."
30477
30470
  },
30478
30471
  {
30479
30472
  name: "relay_stage",
@@ -30482,21 +30475,12 @@ var relayTools = [
30482
30475
  annotations: acts(false),
30483
30476
  description: "Push and hash-check the guest runtime, plus an optional workspace and support files (`files`, landing under `support/`), onto the acquired guest that `guest` names. `workspace` and each `files[].local` lie in the project folder, relative to it or absolute inside it, with no symlinks. Staging needs only Node.js in the guest (`nodePath`, default `node`); an image without it is refused, because the relay pushes no runtime. Runs take before and after snapshots only when the image lists capture software (cua-driver); otherwise their records have none, and the result's `snapshots` says which. When the image lists cua-driver, staging waits up to 120 s for it to take a screenshot, since the image starts its daemon at login, and refuses if it never does. `cuaDriver` names the guest cua-driver the snapshots use. A failed stage can be retried; once staged, only corrected executable paths may be resubmitted, and staging does not prove capture readiness. `resetRecording: true` archives the current recording's evidence and starts a fresh recording on the same VM; it refuses while a receiver lock is held."
30484
30477
  },
30485
- {
30486
- name: "relay_command",
30487
- action: "run",
30488
- kind: "exec",
30489
- title: "Run a guest command",
30490
- annotations: acts(true),
30491
- description: "Run one guest command (`argv`) as one recorded operation; never hide several interactions in one call. Evidence is automatic: the relay records a step derived from the command and, when the image lists cua-driver, snapshots the display before and after. Optional `reason` (intent, never authorization), `step` (`id`, `title`, `expected`, `inputMode`) and `snapshots.afterIntervalMs` (default 500 ms) enrich or tune the record; consecutive keystrokes may form an explicit text group with `snapshots.group` (`first`/`member`/`last`). `timeoutMs` bounds execution (default 120000, up to 3600000). The result carries the outcome and bounded stdout/stderr; it names the after-snapshot as `pending` with its `imageId` while the image downloads in the background, so call relay_image with that `imageId` to see it. A refused, uncertain or nonzero result keeps the VM; never replay input whose effect is uncertain. `diagnostic: true` records a diagnosis or repair without snapshots, even before relay_stage; it is never visual verification, and its result has one `output` field with stdout and stderr combined."
30492
- },
30493
30478
  {
30494
30479
  name: "relay_script",
30495
30480
  action: "run",
30496
- kind: "script",
30497
30481
  title: "Run a guest script",
30498
30482
  annotations: acts(true),
30499
- description: `Run one guest script as this call's single recorded operation; the script drives whatever the image lists, such as cua-driver, Playwright or Chrome DevTools, through their own libraries or command lines. ${runShared} Requires \`language\` (\`javascript\`, \`typescript\` or \`python\`) and \`inline\`: with \`inline: true\` give the script itself as \`code\` (up to 1 MiB); with \`inline: false\` give \`localPath\`, a host file in the project folder (relative to it or absolute inside it, with no symlinks). Give exactly the one \`inline\` names; any other call is refused. It runs in the staged workspace: JavaScript with the guest's Node.js, TypeScript with \`tsx\` from the guest's PATH or else the guest Node.js's own type stripping (22.6 or later), and Python with \`python3\` from the guest's PATH (relay_probe scope=guest reports which run); a missing runtime refuses the run before it starts.`
30483
+ description: "Run one guest script as one recorded operation; never hide several interactions in one call. A command is a shell script. The script drives whatever the image lists, such as cua-driver, Playwright or Chrome DevTools, through their own libraries or command lines, and its exit status says whether it succeeded, so a script that calls cua-driver checks the driver's answer itself. Requires `language` (`shell`, `javascript`, `typescript` or `python`) and `inline`: with `inline: true` give the script itself as `code` (up to 1 MiB); with `inline: false` give `localPath`, a host file in the project folder (relative to it or absolute inside it, with no symlinks). Give exactly the one `inline` names; any other call is refused. It runs in the staged workspace: shell with `/bin/sh`, JavaScript with the guest's Node.js, TypeScript with `tsx` from the guest's PATH or else the guest Node.js's own type stripping (22.6 or later), and Python with `python3` from the guest's PATH (relay_probe scope=guest reports which run); a missing runtime refuses the run before it starts. Evidence is automatic: the relay records a step derived from the call and, when the image lists cua-driver, snapshots the display before and after. Optional `reason` (intent, never authorization), `step` (`id`, `title`, `expected`, `inputMode`) and `snapshots.afterIntervalMs` (default 500 ms) enrich or tune the record; consecutive keystrokes may form an explicit text group with `snapshots.group` (`first`/`member`/`last`). `timeoutMs` bounds execution (default 120000, up to 3600000). The result carries the outcome and bounded stdout/stderr; it names the after-snapshot as `pending` with its `imageId` while the image downloads in the background, so call relay_image with that `imageId` to see it. A refused, uncertain or nonzero result keeps the VM; never replay input whose effect is uncertain. `diagnostic: true`, for shell scripts only, records a diagnosis or repair without snapshots, even before relay_stage, running the script as `/bin/sh -c`; it is never visual verification, and its result has one `output` field with stdout and stderr combined."
30500
30484
  },
30501
30485
  {
30502
30486
  name: "relay_image",
@@ -30549,12 +30533,12 @@ var relayTools = [
30549
30533
  }
30550
30534
  ];
30551
30535
  function relayToolInputSchema(tool) {
30552
- return toolInputSchema(tool.action, tool.kind);
30536
+ return toolInputSchema(tool.action);
30553
30537
  }
30554
30538
  function relayToolInput(name, args) {
30555
30539
  const tool = relayTools.find((candidate) => candidate.name === name);
30556
30540
  if (!tool) throw new Error(`Unknown relay tool: ${name}`);
30557
- return { action: tool.action, ...tool.kind ? { kind: tool.kind } : {}, ...args };
30541
+ return { action: tool.action, ...args };
30558
30542
  }
30559
30543
  var relayResultKind = "relay-image-result-v1";
30560
30544
  async function renderRelayResult(value, resultRoot = join14(tmpdir2(), "mcp-relay-results"), indent = 2) {
@@ -30644,7 +30628,7 @@ async function relayCall(host, raw, options = {}) {
30644
30628
 
30645
30629
  // src/server.ts
30646
30630
  var SERVER_NAME = "relay";
30647
- var SERVER_VERSION = true ? "0.14.2" : JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
30631
+ var SERVER_VERSION = true ? "0.15.0" : JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8")).version;
30648
30632
  var STATUS_TOOL = "relay_status";
30649
30633
  var PLUGIN_TOOL_PREFIX = "mcp__plugin_mcp-relay_relay__";
30650
30634
  var message2 = (error2) => error2 instanceof Error ? error2.message : String(error2);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wezzard/mcp-relay",
3
- "version": "0.14.2",
3
+ "version": "0.15.0",
4
4
  "type": "module",
5
5
  "description": "MCP server and Claude Code plugin. Runs an agent's code on fresh, isolated VMs, several at once, each run recorded with evidence",
6
6
  "license": "MIT",
package/pi-mcp.json CHANGED
@@ -1 +1 @@
1
- {"mcpServers":{"relay":{"command":"npx","args":["-y","@wezzard/mcp-relay@0.14.2"],"lifecycle":"lazy-keep-alive","requestTimeoutMs":3900000,"directTools":true,"toolPrefix":"none"}}}
1
+ {"mcpServers":{"relay":{"command":"npx","args":["-y","@wezzard/mcp-relay@0.15.0"],"lifecycle":"lazy-keep-alive","requestTimeoutMs":3900000,"directTools":true,"toolPrefix":"none"}}}