@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.
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +33 -28
- package/agents/vm-relay-operator.md +6 -6
- package/dist/build-info.json +8 -8
- package/dist/integrity.json +2 -2
- package/dist/receiver.mjs +31 -33
- package/dist/server.mjs +75 -91
- package/package.json +1 -1
- package/pi-mcp.json +1 -1
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:
|
|
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
|
|
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 |
|
|
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
|
|
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.
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
`timeoutMs
|
|
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
|
|
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
|
-
| `
|
|
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
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
`relay_exec`, `relay_code`, `relay_run`, `relay_gate` and
|
|
161
|
-
gone (DC-23, `docs/guest-code-runs.md` §10).
|
|
162
|
-
|
|
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
|
|
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
|
-
- `
|
|
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
|
-
`
|
|
208
|
-
|
|
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","
|
|
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
|
|
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,
|
|
227
|
-
|
|
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
|
|
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
|
|
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-
|
|
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
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
from a
|
|
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
|
|
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.
|
package/dist/build-info.json
CHANGED
|
@@ -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": "
|
|
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": "
|
|
965
|
-
"src/guest/receiver.ts": "
|
|
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": "
|
|
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": "
|
|
974
|
+
"src/schema.ts": "0141b2befc75fafa1bbe9914b34eab374a1204ce34f44af19f2100153805baf8",
|
|
975
975
|
"src/search-diagnostics.ts": "cea037618c56f075d51155101ad1cc0314bfa67b174bdb070191e0ea5ea04679",
|
|
976
976
|
"src/search.ts": "8aaf544fcb27e7e018bd976e1ba7d3c70c047aeda3182b3dce91873a901a245e",
|
|
977
|
-
"src/server.ts": "
|
|
978
|
-
"src/surface.ts": "
|
|
977
|
+
"src/server.ts": "c3256d27248140a1072a924796ba9b7f0edbbe9b5c72bcdeea02a46734aaf5cd",
|
|
978
|
+
"src/surface.ts": "f7772fbafa613aaeba05e47d2def4975fb0ce75d1af067bde968f0e95775f81a",
|
|
979
979
|
"src/transfer.ts": "009dfb72ebd41a5642ec02a48ab7b678bed75e5db8859acc15a45e7f0bd43462",
|
|
980
|
-
"src/transport.ts": "
|
|
980
|
+
"src/transport.ts": "08609fcf56ef9b60b867f7f86783c198b622f72e2b02f2562c5f1506ee1dc0bd",
|
|
981
981
|
"src/typebox.ts": "7f071fbc67548c7d3701272dabe88a217812e12e41dfad76974ff08169fa1a7e",
|
|
982
982
|
"src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da",
|
|
983
983
|
"src/vm-service.ts": "f2a6bfa910484f42aa264dbe02012379c82b093a71645b33e8a8ccd968f4634d"
|
package/dist/integrity.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"server.mjs": "
|
|
3
|
-
"receiver.mjs": "
|
|
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
|
|
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.
|
|
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 (
|
|
920
|
-
|
|
921
|
-
if (
|
|
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 (
|
|
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?.
|
|
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 (
|
|
1096
|
+
const runOwned = async (argv2, dispatchOptions) => {
|
|
1085
1097
|
pendingSpawn = true;
|
|
1086
1098
|
await markLock(true);
|
|
1087
|
-
const result = await runArgv(
|
|
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
|
|
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.
|
|
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
|
|
1241
|
+
} else {
|
|
1232
1242
|
if (hash(request.code) !== request.codeSha256) throw new Error("streamed code hash mismatch");
|
|
1233
|
-
const
|
|
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
|
-
|
|
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(
|
|
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(
|
|
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
|
|
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
|
|
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
|
|
17616
|
+
const argv = [interpreter, ...options.interpreterArgs ?? [], remotePath];
|
|
17617
17617
|
const submission = {
|
|
17618
17618
|
executionId,
|
|
17619
17619
|
sessionId: this.sessionId,
|
|
17620
|
-
argv
|
|
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
|
|
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(
|
|
18334
|
+
async function command(argv, options = {}) {
|
|
18335
18335
|
options.signal?.throwIfAborted();
|
|
18336
18336
|
return new Promise((resolve11, reject) => {
|
|
18337
|
-
const child = spawn3(
|
|
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: ${
|
|
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: ${
|
|
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(
|
|
18600
|
-
const framed =
|
|
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
|
|
18992
|
-
const fact = JSON.parse(await this.checked(
|
|
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
|
|
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
|
|
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
|
-
...
|
|
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(
|
|
19613
|
+
async function observe(argv, parse7) {
|
|
19613
19614
|
try {
|
|
19614
|
-
const result2 = await run(
|
|
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:
|
|
19617
|
+
return { value: parse7(result2.stdout), source: argv.join(" ") };
|
|
19617
19618
|
} catch (error2) {
|
|
19618
|
-
return { value: null, source:
|
|
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
|
|
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
|
|
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,
|
|
28776
|
-
const result2 = await this.vm.exec(name, { argv
|
|
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,
|
|
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, [...
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
29789
|
-
if (!e.staged || !this.session || !this.transport) throw new Error("Use relay_stage before a run, or
|
|
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.
|
|
29799
|
-
if (
|
|
29800
|
-
result2 = await this.session.
|
|
29801
|
-
} else
|
|
29802
|
-
if (!input.
|
|
29803
|
-
|
|
29804
|
-
|
|
29805
|
-
|
|
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
|
-
* `
|
|
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
|
|
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.
|
|
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 (
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
30417
|
-
const found = relayContract.anyOf.find((branch) =>
|
|
30418
|
-
|
|
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
|
|
30426
|
-
const raw = JSON.parse(JSON.stringify(branchFor(action
|
|
30427
|
-
const { action: _action,
|
|
30428
|
-
const required2 = (raw.required ?? []).filter((key) => key !== "action"
|
|
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
|
|
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"
|
|
30435
|
-
|
|
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,
|
|
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,
|
|
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:
|
|
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
|
|
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, ...
|
|
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.
|
|
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.
|
|
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.
|
|
1
|
+
{"mcpServers":{"relay":{"command":"npx","args":["-y","@wezzard/mcp-relay@0.15.0"],"lifecycle":"lazy-keep-alive","requestTimeoutMs":3900000,"directTools":true,"toolPrefix":"none"}}}
|