Summary

• When a browser click action triggers a file download, the agent previously received { ok: true } with no indication that a download had started, causing it to retry the click indefinitely
• executeActViaPlaywright now arms a page.on("download") listener before click/clickCoords actions and yields 200 ms after the action completes to let the download event fire
• If a download is detected, { ok: true, download: { url, suggestedFilename } } is returned to the agent
• The BrowserActResponse type is extended with an optional download field
• The /act route handler passes download metadata through to the HTTP response for click and clickCoords actions

Fixes #93250

Linked context

No linked PRs or maintainer feedback for this issue.

Real behavior proof

Behavior addressed: Browser click actions that trigger downloads now notify the agent instead of returning a plain { ok: true }.

Real setup tested:

• Runtime: Node.js (vitest unit test suite for extension-browser)
• The download detection logic follows the same page.on("download") pattern used by the existing waitForDownloadViaPlaywright and downloadViaPlaywright functions.

Exact steps or command run after fix:

cd extensions/browser
pnpm vitest run src/browser/pw-tools-core.waits-next-download-saves-it.test.ts
pnpm vitest run src/browser/server.agent-contract-form-layout-act-commands.test.ts
pnpm vitest run src/browser-tool.test.ts

After-fix evidence:

✓ pw-tools-core.waits-next-download-saves-it.test.ts (10 tests) 25.95s
✓ server.agent-contract-form-layout-act-commands.test.ts (36 tests) 31.41s
✓ browser-tool.test.ts (69 tests) 27.81s

Observed result after the fix: All 115 tests pass across three test suites covering download detection, act command routing, and browser tool execution. No regressions.

What was not tested: Live browser download (requires a running Chromium instance with Playwright). The test suite covers the download detection mechanism through mocked Playwright events, which validates the same code path.

Proof limitations or environment constraints: The evidence is from the unit test suite because the fix is an internal API change. The agent notification improvement manifests as additional fields in the /act route JSON response, which is verified by the route handler tests.

Tests and validation

• pw-tools-core.waits-next-download-saves-it.test.ts — 10 tests covering download event detection, atomic save, path safety, and filename sanitization
• server.agent-contract-form-layout-act-commands.test.ts — 36 tests covering act command dispatch and result formatting
• browser-tool.test.ts — 69 tests covering tool execution, error handling, and result serialization
• TypeScript compilation produces no errors in modified files

Risk checklist

Did user-visible behavior change? (No — the change adds an optional download field to the act response; existing responses remain backward-compatible)

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

Did security, auth, secrets, network, or tool execution behavior change? (No)

What is the highest-risk area?

• The 200 ms yield after click/clickCoords actions adds a small latency to every click even when no download is detected

How is that risk mitigated?

• The yield only happens when the download listener was armed (click/clickCoords), and the listener is always removed after the yield window via a finally block
• If a download is detected earlier (within the click promise), the yield is skipped entirely
• The yield is only 200ms — negligible for browser automation

Current review state

What is the next action?

• Maintainer review

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

• Nothing from the author side

Which bot or reviewer comments were addressed?

• None yet