mirror of https://github.com/callstack/agent-device.git synced 2026-09-14 20:06:34 +08:00

Files

T

Michał Pierzchała 67b813c55b fix(web): launch npm and the managed backend through node, not .cmd shims (#2033 )

On Windows every `--platform web` command failed with `spawn EINVAL`: the
managed backend resolved to `node_modules/.bin/agent-browser.cmd` and was
spawned with `shell: false`, which Node refuses for `.bat`/`.cmd` since the
CVE-2024-27980 fix. `web setup` failed earlier still — a bare `npm` is not
spawnable on Windows, where npm ships as `npm.cmd`.

`runManagedAgentBrowser` is now the only path that executes the backend. Entry
resolution, the Node runtime, the managed environment, and the spawn all live
behind it, so setup, doctor, and the provider cannot reintroduce the shim. The
entry comes from the installed package's declared `bin` rather than a hard-coded
path, which is the part of this worth being precise about.

npm is untouched on macOS and Linux, which were never broken: setup still spawns
`npm` from PATH. Only Windows resolves npm's own `npm-cli.js` — from an
`npm_execpath` that really is npm's launcher, else the copy bundled beside
`node` — and fails with the existing actionable TOOL_MISSING when neither is
there. Setup also pins `--no-global` so an ambient `npm_config_global` cannot
redirect the install out of the managed prefix.

The published status shape is unchanged: `binaryPath` still names npm's console
shim, now informational rather than the spawned command, and `entryScript` plus
`packageDir` are additive.

Closes #2022


Claude-Session: https://claude.ai/code/session_01LMS3BidXb3F4HSr26vvQmG

Co-authored-by: Claude <noreply@anthropic.com>

2026-08-25 17:59:44 +02:00

2.0 KiB

Raw Permalink Blame History

Web Backend

Web automation uses a managed agent-browser backend as an implementation detail.

Runtime web commands resolve the backend only from the state-dir managed install at tools/agent-browser/<version>.
Normal --platform web commands do not install the managed backend on first use. If the backend is missing, they fail with a setup hint.
Use agent-device web setup before first web automation and in CI/sandbox bootstrap steps.
Use agent-device web doctor to run the backend health check.
The managed install respects --state-dir / AGENT_DEVICE_STATE_DIR.
Web automation requires Node 24+ while the rest of agent-device keeps its Node 22 baseline.
Every backend call spawns the package's declared bin entry with the current Node runtime, never the node_modules/.bin console shim: Windows ships that shim as .cmd, which child_process.spawn refuses without a shell (CVE-2024-27980 hardening), and a shell would reintroduce argument-quoting hazards. runManagedAgentBrowser is the only path that executes the backend. Setup spawns npm from PATH as before, except on Windows, where a bare npm is not spawnable and npm's own npm-cli.js runs under the current Node instead.

Default first-run flow:

agent-device web setup
agent-device open "https://example.com" --platform web
agent-device snapshot -i --platform web
agent-device viewport 1280 900 --platform web
agent-device screenshot ./artifacts/web-full.png --platform web --fullscreen
agent-device network dump 25 --platform web
agent-device close --platform web

Do not document direct agent-browser commands as agent-device features. Web network dump is the narrow exception: it adapts agent-browser network requests to the existing agent-device network evidence shape. Browser-specific network routing/interception/HAR, CDP, React web, tabs, downloads, auth vaults, and profiling stay out of the minimal web surface until there is an explicit agent-device command design for them.

2.0 KiB Raw Permalink Blame History

Web Backend

2.0 KiB

Raw Permalink Blame History