Summary

• Problem: the agent-facing browser tool did not expose the managed browser download helpers even though the CLI/control API already supported /download and /wait/download.
• Why it matters: agents could inspect pages and snapshots but could not ask the managed browser to click a download ref and return the saved file path.
• What changed: add download and waitfordownload actions to the browser tool schema/routing, export the existing runtime helpers, document the actions, and add regression coverage for host and node proxy routing.
• What did NOT change (scope boundary): existing-session download interception remains managed-only; this does not bypass the browser server's existing 501/unsupported behavior for profiles that cannot intercept downloads.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes N/A
• Related Feature: Browser download capture — return downloaded files to agent context #38519, feat: expose download and waitForDownload actions in browser agent tool #12378
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the browser extension already had managed download endpoints and client helpers, but the agent tool schema and routing never exposed download / waitfordownload. During implementation, the new action routing also needed to align outer transport timeouts with browser-side download waits instead of keeping the older fixed 20s HTTP/proxy timeout.
• Missing detection / guardrail: there was no agent-tool regression test asserting download action routing or transport timeout propagation.
• Contributing context (if known): prior PR feat: expose download and waitForDownload actions in browser agent tool #12378 attempted a similar action surface but did not land.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/browser/src/browser-tool.test.ts, extensions/browser/src/browser/client-actions-core.downloads.test.ts
• Scenario the test should lock in: agent browser actions route download and waitfordownload through the host client or node proxy, preserve request bodies, require explicit ref/path where needed, and give long download waits enough outer transport timeout.
• Why this is the smallest reliable guardrail: the browser-side download implementation already exists; the risk here is the agent tool contract and proxy/client timeout handoff.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Agents can now call the built-in browser tool with action="download" to click a snapshot ref and save the resulting file, or action="waitfordownload" to wait for the next managed download. Results include the saved download path returned by the existing browser control API.

Diagram (if applicable)

Before:
[agent browser tool] -> [snapshot/action helpers only] -> [no download action]

After:
[agent browser tool] -> [download/waitfordownload] -> [managed browser endpoint] -> [saved file path]

Security Impact (required)

• New permissions/capabilities? (Yes/No) Yes
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) Yes
• Command/tool execution surface changed? (Yes/No) Yes
• Data access scope changed? (Yes/No) Yes
• If any Yes, explain risk + mitigation: this exposes existing managed browser download endpoints through the agent tool. It keeps the existing browser server/profile capability checks, keeps existing-session download interception managed-only, and constrains saved paths to the browser download path handling already used by the control API.

Repro + Verification

Environment

• OS: Linux 6.8.0-55-generic x86_64
• Runtime/container: Node v24.13.0, pnpm 10.33.0
• Model/provider: N/A
• Integration/channel (if any): Browser plugin / built-in browser tool
• Relevant config (redacted): default managed browser action routing; node proxy tests use mocked browser-capable nodes

Steps

1. Create the browser tool.
2. Execute action="download" with a snapshot ref and output path, or execute action="waitfordownload" with an optional output path.
3. For node targets, route the request through browser.proxy and preserve both body timeout and outer transport timeout.

Expected

• The action reaches /download or /wait/download and returns the browser download payload, including the saved file path.
• Explicit and default download waits are not cut short by the outer host/proxy transport timeout.

Actual

• Implemented behavior matches expected in unit/seam tests.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Verification run locally:

pnpm test extensions/browser/src/browser-tool.test.ts extensions/browser/src/browser/client-actions-core.downloads.test.ts -- --reporter=verbose
# passed: 2 files, 56 tests

NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed
# passed: 2 shards, 854 passed, 1 skipped

pnpm docs:check-mdx
# passed

pnpm exec oxfmt --check --threads=1 CHANGELOG.md docs/tools/browser-control.md extensions/browser/plugin-registration.ts extensions/browser/src/browser-runtime.ts extensions/browser/src/browser-tool.runtime.ts extensions/browser/src/browser-tool.schema.ts extensions/browser/src/browser-tool.test.ts extensions/browser/src/browser-tool.ts extensions/browser/src/browser/constants.ts extensions/browser/src/browser/client-actions-core.ts extensions/browser/src/browser/client-actions-core.downloads.test.ts
# passed

git diff --check
# passed

NODE_OPTIONS=--max-old-space-size=2048 node scripts/run-oxlint.mjs --tsconfig tsconfig.oxlint.extensions.json extensions/browser/plugin-registration.ts extensions/browser/src/browser-runtime.ts extensions/browser/src/browser-tool.runtime.ts extensions/browser/src/browser-tool.schema.ts extensions/browser/src/browser-tool.ts extensions/browser/src/browser-tool.test.ts extensions/browser/src/browser/client-actions-core.ts extensions/browser/src/browser/client-actions-core.downloads.test.ts extensions/browser/src/browser/constants.ts
# passed: 0 warnings, 0 errors

Note: pnpm check:changed passed conflict-marker checks, changelog attribution checks, extension production typecheck, and extension test typecheck, then local broad lint:extensions was terminated by tsgolint with SIGTERM on an 8 GB host. I used the targeted repo lint wrapper above to avoid exceeding the host memory limit.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: host-client download routing; host-client wait-for-download routing; node proxy download routing; node proxy wait-for-download routing; default 120s download wait transport timeout; explicit 30s download wait transport timeout; required ref/path validation; docs/format/lint/typecheck coverage listed above.
• Edge cases checked: omitted timeoutMs uses the browser-side default download wait plus transport slack; explicit timeoutMs scales both proxy and gateway waits; existing-session managed-only scope is documented and unchanged.
• What you did not verify: a live Chromium download in a real browser session; this PR relies on the existing browser-side download implementation and adds the missing agent tool contract/routing coverage.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: exposing downloads through the agent browser tool could let agents save files unexpectedly.
  • Mitigation: the action uses existing managed browser endpoints and their path/profile constraints; unsupported existing-session profiles remain blocked by the browser server.
• Risk: long download waits could be cut short by outer transport timeouts.
  • Mitigation: host client and node proxy transport timeouts now scale from the effective download wait with slack, with tests for explicit and default waits.