mirror of
https://github.com/callstack/agent-device.git
synced 2026-09-14 20:06:34 +08:00
Michał Pierzchała
67b813c55b
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>
35 lines
2.0 KiB
Markdown
35 lines
2.0 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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.
|