Skip to content

fix(browser): expose managed download actions in agent browser tool#93859

Closed
LeonidasLux wants to merge 1 commit into
openclaw:mainfrom
LeonidasLux:fix/issue-93250-Bug---No-notification-when-br
Closed

fix(browser): expose managed download actions in agent browser tool#93859
LeonidasLux wants to merge 1 commit into
openclaw:mainfrom
LeonidasLux:fix/issue-93250-Bug---No-notification-when-br

Conversation

@LeonidasLux

@LeonidasLux LeonidasLux commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

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, causing them to keep retrying different download strategies.
  • 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.

Fixes #93250

Linked context

Real behavior proof

Behavior addressed: Agent-facing browser tool now exposes download and waitfordownload actions that reach the existing managed browser download endpoints.

Real setup tested: Local OpenClaw built from source

  • Runtime: node v24.1.0

Exact steps or command run after fix:

# 1. Build and verify CLI exposes both commands
pnpm build && node openclaw.mjs browser --help | grep -E "(download|waitfordownload)"

# 2. Verify command help
node openclaw.mjs browser download --help
node openclaw.mjs browser waitfordownload --help

# 3. Run regression tests
pnpm test extensions/browser/src/browser-tool.test.ts \
  extensions/browser/src/browser/client-actions-core.downloads.test.ts \
  -- --reporter=verbose

# 4. Format and lint
pnpm exec oxfmt --check --threads=1 \
  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/client-actions-core.ts \
  extensions/browser/src/browser/client-actions-core.downloads.test.ts \
  extensions/browser/src/browser/client-actions.ts \
  extensions/browser/src/browser/constants.ts

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/client-actions.ts \
  extensions/browser/src/browser/constants.ts

After-fix evidence:

$ node openclaw.mjs browser --help | grep -E "(download|wait)"
  download                  Click a ref and save the resulting download
  waitfordownload           Wait for the next download (and save it)

$ node openclaw.mjs browser download --help
Usage: openclaw browser download [options]
Click a ref and save the resulting download

$ node openclaw.mjs browser waitfordownload --help
Usage: openclaw browser waitfordownload [options]
Wait for the next download (and save it)

Test run:

Test Files  2 passed (2)
     Tests  79 passed (79)
  Duration  29.56s

Format check: All matched files use the correct format.
Lint check: 0 warnings, 0 errors

Observed result after the fix: The agent-facing browser tool action enum now includes download and waitfordownload. The CLI exposes both commands. Tests pass for host client routing, node proxy routing, timeout propagation, and parameter validation.

What was not tested: A live Chromium download in a real browser session. This PR relies on the existing browser-side download implementation (which has its own test coverage) and adds the missing agent tool contract/routing coverage. The existing lower-level download routes (POST /download, POST /wait/download) are unchanged.

Proof limitations or environment constraints: No real browser instance was available in the test environment. The CLI verification was done with OPENCLAW_STATE_DIR pointed at an empty temp directory with no browser profiles configured, but the CLI command registration and tool schema validation do not require an active browser.

Tests and validation

# Targeted regression tests
pnpm test extensions/browser/src/browser-tool.test.ts \
  extensions/browser/src/browser/client-actions-core.downloads.test.ts

# Full extension typecheck (memory-constrained, ran targeted subset)
# oxlint passed for all 11 changed files (0 warnings, 0 errors)
# oxfmt passed for all 11 changed files

git diff --check  # passed

Coverage scenarios:

  • download host client routing (ref + path + timeoutMs)
  • waitfordownload host client routing (path + timeoutMs + profile)
  • download node proxy routing (timeout transport scaling: 30s wait + 5s slack → 35s proxy, 40s gateway)
  • waitfordownload node proxy routing
  • default download wait timeout for node proxy (120s + 5s slack)
  • required ref/path validation for download action
  • default download request timeout for host client (120s wait + 5s slack = 125s)
  • explicit timeout propagation for host client download

Risk checklist

Did user-visible behavior change? (Yes — agents can now use action="download" and action="waitfordownload" in the browser tool)

Did config, environment, or migration behavior change? (No)

Did security, auth, secrets, network, or tool execution behavior change? (Yes — exposes existing managed browser download endpoints through the agent tool)

What is the highest-risk area?

  • Exposing managed downloads through the agent browser tool could let agents save files unexpectedly.

How is that risk mitigated?

  • The action uses existing managed browser endpoints and their path/profile constraints.
  • Unsupported existing-session profiles remain blocked by the browser server (501 response).
  • Saved paths are constrained to the configured downloads root directory.
  • Long download waits are not cut short by outer transport timeouts (host client and node proxy transport timeouts scale from the effective download wait with slack).

Current review state

What is the next action?

  • Maintainer review

What is still waiting on author, maintainer, CI, or external proof?

  • CI checks on the PR (lint, typecheck, test shards)
  • Real behavior proof CI validation (field extraction from PR body)

Which bot or reviewer comments were addressed?

@LeonidasLux
fix(browser): expose managed download actions in agent browser tool
2637038 
Add download and waitfordownload actions to the agent-facing browser tool
schema, routing, and client helpers so agents can capture downloaded file
paths after clicking a snapshot ref or waiting for a pending download.
The underlying browser control API already supports /download and
/wait/download; this change wires them into the agent tool surface.

- Add download/waitfordownload to BROWSER_TOOL_ACTIONS enum in schema
- Add path field to BrowserToolSchema for output path control
- Add browserDownload/browserWaitForDownload client action helpers
- Add download proxy timeout resolution with transport slack
- Route both actions through host client and node browser proxy
- Update tool description in browser-tool.ts and plugin-registration.ts
- Document agent-facing download actions in browser-control.md
- Add regression coverage for host and node proxy download routing

Fixes openclaw#93250
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: M proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 17, 2026
This was referenced Jun 17, 2026
Closed
Closed
Merged
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. labels Jun 19, 2026
@clawsweeper

clawsweeper Bot commented Jun 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed June 19, 2026, 9:23 PM ET / 01:23 UTC.

Summary
The branch adds browser tool download and waitfordownload actions, client helper exports, timeout routing, docs, and regression tests over the existing managed download endpoints.

PR surface: Source +163, Tests +283, Docs +6. Total +452 across 11 files.

Reproducibility: yes. at source level: current main has managed /download and /wait/download routes, but the browser tool schema and dispatcher do not expose download or waitfordownload. I did not run a live browser download in this read-only review.

Review metrics: 1 noteworthy metric.

  • Agent Tool Actions: 2 added. The PR expands the model-facing browser capability surface, so maintainer review should notice the new security-boundary exposure before merge.

Stored data model
Persistent data-model change detected: serialized state: extensions/browser/src/browser/client-actions-core.downloads.test.ts, serialized state: extensions/browser/src/browser/client-actions-core.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #93250
Summary: This PR is one candidate fix for the canonical browser download feedback gap; current main is still missing the agent-facing action surface and overlapping open PRs are not yet safe supersession targets.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Add redacted live proof from a running Gateway/browser session for both new actions; screenshots, recordings, terminal output, copied live output, linked artifacts, or redacted logs are acceptable when they show the behavior.
  • [P1] Show that saved paths remain under the managed downloads root and existing-session profiles still reject unsupported interception; redact private information such as IP addresses, API keys, phone numbers, and non-public endpoints.
  • After proof is added, update the PR body to trigger re-review; if it does not, ask a maintainer to comment @clawsweeper re-review.

Proof guidance:

  • [P1] Needs stronger real behavior proof before merge: The PR body has terminal CLI help and unit/seam test output, but it explicitly says no live Chromium download in a real browser session was verified, so the changed real behavior is not proven yet. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Mantis proof suggestion
A real browser/Gateway download proof would materially help review because the change is a live browser capability, not only schema text. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify browser tool download and waitfordownload actions save files and return constrained paths in a real Gateway/browser session.

Risk before merge

  • [P1] The PR exposes existing managed browser file-download endpoints as model-facing tool actions, so maintainers need to explicitly accept the downloads-root and existing-session profile restrictions as the security boundary.
  • [P1] The supplied proof is CLI help plus unit/seam output and explicitly does not include a live Chromium download in a real browser session.
  • [P1] Overlapping open PRs feat(browser): add agent download actions #74411 and fix(browser): notify agent when click triggers download #93307 target the same linked issue, so maintainers still need to choose one canonical landing path.

Maintainer options:

  1. Require Live Browser Proof (recommended)
    Ask for redacted proof from a running Gateway/browser session showing download and waitfordownload saving files under the managed downloads root and returning the path before merge.
  2. Accept The Download Boundary
    Maintainers may explicitly accept that the existing downloads root, path validation, and existing-session 501 behavior are the intended security boundary for model-facing download actions.
  3. Choose One Canonical Branch
    If another overlapping PR becomes proof-positive and clean first, use that branch as the landing path and close the remaining duplicate implementations after merge.

Next step before merge

  • [P1] The remaining actions are contributor live proof, maintainer security-boundary acceptance, and canonical PR selection rather than a narrow automated code repair.

Security
Cleared: No concrete path-bypass, dependency, workflow, secret-handling, or supply-chain defect was found; the remaining concern is maintainer acceptance of the model-facing download boundary.

Review details

Best possible solution:

Land one canonical browser-plugin fix after redacted live Gateway/browser proof shows both new actions save files under the managed downloads root and return paths while preserving profile restrictions.

Do we have a high-confidence way to reproduce the issue?

Yes, at source level: current main has managed /download and /wait/download routes, but the browser tool schema and dispatcher do not expose download or waitfordownload. I did not run a live browser download in this read-only review.

Is this the best way to solve the issue?

Likely yes at the code boundary: reusing the existing managed download endpoints is cleaner than sampling click side effects after /act. Maintainers still need to choose the canonical API shape and require live proof for the selected branch.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against e0ec42e0e0e2.

Label changes

Label justifications:

  • P2: This is a normal-priority browser automation reliability fix with limited browser-plugin blast radius and active candidate implementations.
  • merge-risk: 🚨 security-boundary: The diff exposes managed file-download capability through model-facing browser tool actions, making path and profile constraints merge-critical.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR body has terminal CLI help and unit/seam test output, but it explicitly says no live Chromium download in a real browser session was verified, so the changed real behavior is not proven yet. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed

PR surface:

Source +163, Tests +283, Docs +6. Total +452 across 11 files.

View PR surface stats
Area Files Added Removed Net
Source 8 166 3 +163
Tests 2 283 0 +283
Docs 1 6 0 +6
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 11 455 3 +452

What I checked:

Likely related people:

  • steipete: GitHub history shows repeated browser tool, browser schema, managed download helper, route, timeout, and docs work across the central files this PR extends. (role: feature-history owner; confidence: high; commits: a982f798ca20, ce56fc176a6f, 383531da96be; files: extensions/browser/src/browser-tool.ts, extensions/browser/src/browser-tool.schema.ts, extensions/browser/src/browser/routes/agent.act.download.ts)
  • vincentkoc: Recent live history touches the agent-facing browser tool and schema surfaces, including top-level act field handling and related browser-node behavior. (role: recent area contributor; confidence: medium; commits: 75cdf22152de, 12b8db34ee1a, b0998f7d152d; files: extensions/browser/src/browser-tool.ts, extensions/browser/src/browser-tool.schema.ts, docs/tools/browser-control.md)
  • joshavant: Prior browser /act route consolidation is adjacent to the agent route/result contract involved in the download-feedback issue. (role: adjacent route contract contributor; confidence: medium; commits: f096fc440686; files: extensions/browser/src/browser/routes/agent.act.download.ts, docs/tools/browser-control.md)
  • jesse-merhi: Prior merged work hardened the managed browser download output path family that this PR relies on for the saved file boundary. (role: download output hardening contributor; confidence: medium; commits: a9377fe6679b; files: extensions/browser/src/browser/routes/agent.act.download.ts, extensions/browser/src/browser/pw-tools-core.downloads.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@LeonidasLux
LeonidasLux deleted the fix/issue-93250-Bug---No-notification-when-br branch June 20, 2026 02:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. proof: supplied External PR includes structured after-fix real behavior proof. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. size: M status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: No notification when browser click triggers a download – agent keeps retrying

1 participant

@LeonidasLux