Run a guest script
relay_scriptRun one shell, JavaScript, TypeScript, or Python script inside a disposable VM guest as a single recorded operation to drive Playwright, Chrome DevTools, or similar tools, with snapshot evidence.
Instructions
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"guest": "<guest>",
"language": "<language>",
"inline": "<inline>"
},
"name": "relay_script"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | With inline: true, the script itself, up to 1 MiB. | |
| step | No | Optional step record overrides; any field left out is derived from the call. | |
| guest | Yes | The guest this call acts on: the name relay_acquire answered. | |
| inline | Yes | true: the script is `code`, given inline. false: the script is the host file `localPath`. Give exactly the one that inline names. | |
| reason | No | Optional intent, retained as evidence. Default: derived from the call. | |
| language | Yes | ||
| localPath | No | With inline: false, a host script file in the project folder: relative to it, or absolute inside it; no symlinks. | |
| snapshots | No | Optional. Consecutive keystrokes may form an explicit text group (first/member/last); only first gets a before-snapshot and only last an after-snapshot. | |
| timeoutMs | No | Execution timeout in milliseconds, default 120000, maximum 3600000. Independent of snapshot delay and lease TTL. | |
| diagnostic | No | Shell scripts only: explicit diagnosis or repair without screenshot evidence, including before staging. The script and its outcome remain recorded. Never claim visual verification. |