fix(browser): thread snapshot timeoutMs through agent tool and helpers by masatohoshino · Pull Request #75702 · openclaw/openclaw

masatohoshino · 2026-05-01T15:00:51Z

Fixes #72934.

Summary

Problem: browser action=snapshot consistently times out on macOS (issue [Bug]: Browser snapshot action consistently times out despite successful open/navigate #72934). open / navigate succeed, but every snapshot path times out — making the browser tool effectively unusable from agents.
Why it matters: the snapshot timeout passed by callers (and the implicit 20_000 ms default) is silently dropped at multiple layers, so neither the agent-supplied timeoutMs nor any sane default reaches the Chrome MCP / Playwright snapshot helpers.
What changed: thread one normalized timeoutMs from the agent tool input through browserSnapshot (client) → BrowserSnapshotPlan (/snapshot route plan) → /snapshot route → Chrome MCP take_snapshot / take_screenshot (labels) and Playwright snapshotAi / snapshotRole / snapshotAria / screenshotWithLabels helpers. Add DEFAULT_BROWSER_SNAPSHOT_TIMEOUT_MS = 20_000 and replace the previously hardcoded 20000 literal so the default value is unchanged. The default is now applied uniformly at the executeSnapshotAction boundary so it reaches both the direct client call and the proxied path; without this, the proxy path was effectively unbounded.
What did NOT change (scope boundary): act / click / navigate paths (already fixed in PR fix(browser): reset Chrome MCP session after navigate_page timeout #69733 / fix browser click timeouts for existing-session routes #63524); Linux/Ubuntu fault path Bug: browser tool times out despite CDP connection working (Playwright can connect directly) #72653 (likely a different root cause and explicitly out of scope per the bot triage); Chrome MCP / Playwright internals beyond passing timeoutMs to existing race / API options; extensions/browser/ boundary is preserved; docs/tools/browser.md is not touched. (CHANGELOG.md includes the required browser snapshot timeout fix entry, added in a separate follow-up commit per the Clawsweeper guidance.)

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes [Bug]: Browser snapshot action consistently times out despite successful open/navigate #72934
Related fix(browser): reset Chrome MCP session after navigate_page timeout #69733 (navigateChromeMcpPage timeout race — directly mirrored here for take_snapshot), Bug: browser tool times out despite CDP connection working (Playwright can connect directly) #72653 (Linux/all-action timeout — different root cause, out of scope)
This PR fixes a bug or regression

Root Cause (if applicable)

Root cause: the snapshot path in extensions/browser/ does not propagate timeoutMs end-to-end. Specifically: executeSnapshotAction never reads input.timeoutMs (and never injects the default), so the proxied snapshot request reaches the gateway with no timeoutMs at all; browserSnapshot (client) hardcodes timeoutMs: 20000 and has no opts.timeoutMs; BrowserSnapshotPlan has no timeoutMs field; takeChromeMcpSnapshot calls callTool without forwarding any options.timeoutMs, so the Promise.race + session reset added in PR fix(browser): reset Chrome MCP session after navigate_page timeout #69733 never engages for snapshot; snapshotRoleViaPlaywright / snapshotAriaViaPlaywright ignore caller timeouts (the role helper hardcodes 5000 ms; the aria helper has no timeout at all on Accessibility.getFullAXTree).
Missing detection / guardrail: there are no targeted tests asserting that an explicit timeoutMs from the agent tool reaches each snapshot helper; browser-tool.test.ts mocked browserSnapshot and never inspected timeout-related arguments.
Contributing context (if known): PR fix(browser): reset Chrome MCP session after navigate_page timeout #69733 added the timeoutMs race to callTool and used it for navigate_page, but did not extend the same wiring to take_snapshot or to the Playwright snapshot helpers — leaving the snapshot path silently subject to whatever the underlying Chrome MCP / Playwright operation chooses to do.

Regression Test Plan (if applicable)

Coverage level that should have caught this: [x] Unit test
Target test or file: extensions/browser/src/browser-tool.test.ts, extensions/browser/src/browser/client.test.ts, extensions/browser/src/browser/chrome-mcp.test.ts, extensions/browser/src/browser/routes/agent.snapshot.plan.test.ts, extensions/browser/src/browser/pw-tools-core.snapshot.test.ts.
Scenario the test should lock in: an explicit timeoutMs supplied by an agent must reach browserSnapshot (and the /snapshot query string), BrowserSnapshotPlan, takeChromeMcpSnapshot (where it must arm the callTool race), snapshotRoleViaPlaywright (must reach page.ariaSnapshot({ timeout })), snapshotAriaViaPlaywright (must race Accessibility.getFullAXTree), and the proxied browser snapshot path. The DEFAULT_BROWSER_SNAPSHOT_TIMEOUT_MS = 20_000 default is also locked in for both direct and (implicitly via executeSnapshotAction) proxied paths.
Why this is the smallest reliable guardrail: each new test asserts one seam; together they cover every layer where timeoutMs is dropped today, without requiring a real Chromium / Playwright session.
Existing test that already covers this: none — browser-request.timeout.test.ts covers browser.request local dispatches but not snapshot path; agent.snapshot.test.ts covers resolveTargetIdAfterNavigate only.
If no new test is added, why not: N/A (10 new test cases added across 5 files in this PR).

User-visible / Behavior Changes

Default snapshot timeout is unchanged in value (still 20_000 ms; the hardcoded literal is replaced by DEFAULT_BROWSER_SNAPSHOT_TIMEOUT_MS = 20_000). What does change is enforcement scope: the same 20_000 ms default that previously only applied to direct host snapshots now applies uniformly to the proxied node-target snapshot path as well — previously the proxy path silently had no per-request timeout for snapshot, leaving it subject to whatever Chrome MCP / Playwright happened to do. Caller-supplied timeoutMs is now honored end-to-end across all snapshot paths. No public schema change beyond BrowserSnapshotPlan gaining an optional timeoutMs field.

Diagram (if applicable)

Before:
agent input.timeoutMs ─┐
                       └─► executeSnapshotAction (drops timeoutMs)
                          └─► proxyRequest / browserSnapshot
                              └─► /snapshot route
                                  ├─► takeChromeMcpSnapshot (no timeoutMs → callTool race never armed)
                                  ├─► snapshotAiViaPlaywright (caller never passes timeoutMs)
                                  ├─► snapshotRoleViaPlaywright (no param; hardcoded 5000 ms)
                                  └─► snapshotAriaViaPlaywright (no param; unbounded getFullAXTree)
result: snapshot consistently times out, no actionable error, browser tool unusable

After:
agent input.timeoutMs ─► executeSnapshotAction (defaults to DEFAULT_BROWSER_SNAPSHOT_TIMEOUT_MS = 20_000)
                       ─► proxyRequest({ query: { timeoutMs }, timeoutMs }) / browserSnapshot({ timeoutMs })
                          └─► /snapshot route reads plan.timeoutMs
                              ├─► takeChromeMcpSnapshot({ timeoutMs }) → callTool race + session reset
                              ├─► snapshotAiViaPlaywright({ timeoutMs })
                              ├─► snapshotRoleViaPlaywright({ timeoutMs }) → page.ariaSnapshot({ timeout })
                              └─► snapshotAriaViaPlaywright({ timeoutMs }) → Accessibility.getFullAXTree raced
result: one normalized snapshot timeout reaches every layer; default value unchanged at 20_000 ms.

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No

Repro + Verification

Environment

OS: Linux (developer worktree, Ubuntu headless); upstream issue [Bug]: Browser snapshot action consistently times out despite successful open/navigate #72934 reports macOS Darwin 25.4.0 arm64
Runtime/container: Node 22, vitest 4.x
Model/provider: N/A (timeout propagation is provider-agnostic)
Integration/channel (if any): browser plugin
Relevant config (redacted): default browser config

Steps

Run focused tests: pnpm test extensions/browser/src/browser-tool.test.ts extensions/browser/src/browser/client.test.ts extensions/browser/src/browser/chrome-mcp.test.ts extensions/browser/src/browser/routes/agent.snapshot.plan.test.ts extensions/browser/src/browser/pw-tools-core.snapshot.test.ts.
Inspect new tests:
- client.test.ts — browserSnapshot writes timeoutMs into the /snapshot? query (explicit value + 20_000 default).
- agent.snapshot.plan.test.ts — resolveSnapshotPlan parses timeoutMs and rejects non-positive values.
- chrome-mcp.test.ts — takeChromeMcpSnapshot({ timeoutMs: 75 }) rejects with the take_snapshot race error after fake timers advance.
- browser-tool.test.ts — executeSnapshotAction passes input.timeoutMs to both the direct browserSnapshot call and the proxied callBrowserProxy (params.query.timeoutMs + params.timeoutMs); falls back to the default 20_000 ms when none is supplied.
- pw-tools-core.snapshot.test.ts — snapshotAriaViaPlaywright({ timeoutMs: 750 }) races Accessibility.getFullAXTree and rejects on timeout; snapshotRoleViaPlaywright({ refsMode: "aria", timeoutMs: 8888 }) forwards the value into page.ariaSnapshot({ mode: "ai", timeout: 8888 }).
Targeted formatter + lint coverage applies to the touched files (oxfmt + repo lint wrappers).

Expected

All targeted tests pass; the explicit timeoutMs is observable at every snapshot seam, and the default reaches both the direct and proxied paths.

Actual

95 / 95 tests pass across the 5 focused files.

Evidence

Failing test/log before + passing after — implicit (the new tests would have failed before this change since timeoutMs was never threaded through any of the asserted seams; e.g., the chrome-mcp.test.ts snapshot race test would never reject because takeChromeMcpSnapshot did not pass options.timeoutMs to callTool).
Real-behavior trace — see ## Real behavior proof section below.
Screenshot/recording
Perf numbers (if relevant)

Real behavior proof

Captured 2026-05-17 against branch pr/openclaw-browser-snapshot-timeout-propagation head 6646e1edb9 (= 3 commits on top of e6c1a6637a).

Behavior or issue addressed: the browser action=snapshot path used to ignore agent-supplied timeoutMs at every layer below the agent tool, so a slow or hung Chrome MCP / Playwright snapshot could only be cut short by the global request timeout. This PR threads timeoutMs from the agent tool input, through executeSnapshotAction, through the browserSnapshot HTTP client, through the /snapshot route plan resolver, through takeChromeMcpSnapshot, and through both Playwright helpers (snapshotAriaViaPlaywright Promise.race wrapper + snapshotRoleViaPlaywright Playwright ariaSnapshot({ timeout })) all the way to the leaf accessibility call. The Codex review asked for evidence that the parameter is honored by a real boundary rather than only by unit tests.

Real environment tested: Linux x86_64 local dev workspace (Node 22.22.2, pnpm 10.33.2). A real loopback Node http.createServer stands in for the OpenClaw browser agent's /snapshot route with a controlled per-request delay. The actual production browserSnapshot HTTP client from this PR's source (extensions/browser/src/browser/client.ts) is invoked against that real socket, so fetchBrowserJson exercises its real AbortController and the URL query carries the real serialized timeoutMs. Live Chromium was attempted but blocked on missing libasound.so.2 in this sandbox (cannot apt-install without sudo); the HTTP-client boundary is the next outermost real seam and is the one the agent tool actually reaches in production.

Exact steps or command run after this patch:

Start a real Node loopback HTTP server with a configurable delay.
Import the production browserSnapshot client from extensions/browser/src/browser/client.ts and call it with { format: "ai", timeoutMs: X } against the loopback server.
Vary (timeoutMs, server delay): baseline (no timeoutMs, fast server), tight timeoutMs against a slow server (expect abort near timeoutMs), and loose timeoutMs against a moderate server (expect success).
Capture client-side elapsed time, observed outcome (success / timed out after Xms), and the URL query the server actually received.

Concrete commands run on the branch:

$ OPENCLAW_HOME=/tmp/proof-openclaw-home \
    node node_modules/.bin/tsx scripts/proof-browser-snapshot-timeout.ts
$ CI=true pnpm test \
    extensions/browser/src/browser-tool.test.ts \
    extensions/browser/src/browser/chrome-mcp.test.ts \
    extensions/browser/src/browser/client.test.ts \
    extensions/browser/src/browser/pw-tools-core.snapshot.test.ts \
    extensions/browser/src/browser/routes/agent.snapshot.plan.test.ts
$ CI=true pnpm tsgo:extensions

Evidence after fix:

Terminal transcript from the HTTP-boundary probe (real Node socket, no mocks):

=== environment ===
Node:                    v22.22.2
HTTP boundary:           real loopback Node http.createServer with controlled delay
browserSnapshot import:  extensions/browser/src/browser/client.ts (this PR's source)
why not real Chromium:   headless shell missing libasound.so.2 in this env

=== baseline: no timeoutMs (default 20000ms), server delays 50ms ===
  input timeoutMs:       undefined (server delay: 50ms)
  elapsed_ms:            78.9
  outcome:               ok
  payload.targetId:      "live-test-target"
  payload.snapshot:      "h1 Snapshot timeout proof\nbutton Primary action\n"
  payload.stats.nodes:   17
  server saw request:    GET /snapshot
  server saw timeoutMs:  20000
  server saw format:     ai

=== explicit timeoutMs=9000, server delays 50ms (should succeed) ===
  input timeoutMs:       9000 (server delay: 50ms)
  elapsed_ms:            57.5
  outcome:               ok
  payload.targetId:      "live-test-target"
  payload.snapshot:      "h1 Snapshot timeout proof\nbutton Primary action\n"
  payload.stats.nodes:   17
  server saw request:    GET /snapshot
  server saw timeoutMs:  9000
  server saw format:     ai

=== explicit timeoutMs=300, server delays 2000ms (should abort on timeout) ===
  input timeoutMs:       300 (server delay: 2000ms)
  elapsed_ms:            310.0
  outcome:               threw (Error): Can't reach the OpenClaw browser control service (timed out after 300ms). If this is a sandboxed session, ensure the sandbox browser is running.
  server saw request:    GET /snapshot
  server saw timeoutMs:  300
  server saw format:     ai

=== explicit timeoutMs=1500, server delays 2500ms (should abort on timeout) ===
  input timeoutMs:       1500 (server delay: 2500ms)
  elapsed_ms:            1505.4
  outcome:               threw (Error): Can't reach the OpenClaw browser control service (timed out after 1500ms). If this is a sandboxed session, ensure the sandbox browser is running.
  server saw request:    GET /snapshot
  server saw timeoutMs:  1500
  server saw format:     ai

=== explicit timeoutMs=4000, server delays 500ms (should succeed) ===
  input timeoutMs:       4000 (server delay: 500ms)
  elapsed_ms:            506.6
  outcome:               ok
  payload.targetId:      "live-test-target"
  payload.snapshot:      "h1 Snapshot timeout proof\nbutton Primary action\n"
  payload.stats.nodes:   17
  server saw request:    GET /snapshot
  server saw timeoutMs:  4000
  server saw format:     ai

=== done ===

Focused-test summary on the rebased branch (5 files, 95 cases):

$ CI=true pnpm test \
    extensions/browser/src/browser-tool.test.ts \
    extensions/browser/src/browser/chrome-mcp.test.ts \
    extensions/browser/src/browser/client.test.ts \
    extensions/browser/src/browser/pw-tools-core.snapshot.test.ts \
    extensions/browser/src/browser/routes/agent.snapshot.plan.test.ts

 Test Files  5 passed (5)
      Tests  95 passed (95)
   Duration  2.66s
[test] passed 1 Vitest shard in 6.01s

Observed result after fix:

input `timeoutMs`	server delay	client-side elapsed	outcome
(none)	50ms	78.9ms	ok (URL carried default `timeoutMs=20000`)
9000	50ms	57.5ms	ok (URL carried `timeoutMs=9000`)
300	2000ms	310.0ms	threw `timed out after 300ms`
1500	2500ms	1505.4ms	threw `timed out after 1500ms`
4000	500ms	506.6ms	ok (URL carried `timeoutMs=4000`)

What this proves at the public HTTP-client boundary:

The agent-tool timeoutMs reaches the URL query of GET /snapshot?...&timeoutMs=X, so the downstream /snapshot route handler (already covered by agent.snapshot.plan.test.ts) has the value it needs to feed to takeChromeMcpSnapshot / snapshotAriaViaPlaywright / snapshotRoleViaPlaywright.
The client-side AbortController fires at the requested timeoutMs, not at the legacy default. Wall-clock elapsed tracks the input within ~10 ms (310ms for 300ms, 1505ms for 1500ms), and the thrown message names the exact value (timed out after 300ms, timed out after 1500ms), so a hung downstream cannot keep the agent waiting longer than the agent asked.
Both the request payload (timeoutMs=X in the URL query) and the response payload (the snapshot JSON: targetId, snapshot, stats) cross a real socket round-trip.

Combined with the 95 focused unit cases that already cover the downstream layers (/snapshot plan resolution, Chrome MCP callTool race, Playwright ariaSnapshot({ timeout }) forwarding, Promise.race wrapper for the Accessibility CDP call), the whole agent-input → leaf-call chain is now observably timeoutMs-honoring.

What was not tested:

Live Chromium / real Playwright ariaSnapshot on a real page — blocked on missing libasound.so.2 in this sandbox (apt-install requires sudo, not available here). The PR's Playwright leaf is covered by the in-tree vitest cases (pw-tools-core.snapshot.test.ts — including the races against an explicit timeoutMs and forwards an explicit timeoutMs into the role-aria Playwright ariaSnapshot call cases) and the wrapper logic is mechanically the same as the already-merged navigateChromeMcpPage model from PR fix(browser): reset Chrome MCP session after navigate_page timeout #69733.
macOS Linux 路 Bug: browser tool times out despite CDP connection working (Playwright can connect directly) #72653 (separately tracked, out of scope for this PR).
pnpm check:changed typecheck-all picked up two pre-existing typecheck errors in extensions/matrix/src/matrix/monitor/handler.ts (Property 'dmScope' does not exist, Cannot find name 'liveDmAllowFrom') that are introduced by upstream extensions/matrix/ advances after this PR's base e6c1a6637a (git log e6c1a6637a..upstream/main -- extensions/matrix/ lists 3 upstream commits, none touched by this PR). The browser-scoped focused tests above remain green.

Human Verification (required)

Verified scenarios:
- Direct browser action=snapshot path: executeSnapshotAction forwards input.timeoutMs to browserSnapshot({ timeoutMs }) and the resulting /snapshot? URL carries the value (default 20_000 when absent).
- Proxied path through callBrowserProxy: the gateway invocation receives params.query.timeoutMs AND params.timeoutMs so both the proxied HTTP request and the Chrome MCP race honor it (assertion locks in outer = inner + 5_000 ms slack).
- Chrome MCP layer: takeChromeMcpSnapshot arms the callTool race, matching the navigateChromeMcpPage model from PR fix(browser): reset Chrome MCP session after navigate_page timeout #69733.
- Playwright helpers: snapshotRoleViaPlaywright forwards timeoutMs to page.ariaSnapshot({ timeout }) / locator.ariaSnapshot({ timeout }); snapshotAriaViaPlaywright races the unbounded Accessibility.getFullAXTree call.
Edge cases checked:
- Missing / non-positive timeoutMs values fall through to the existing 20_000 ms default — covered by the agent.snapshot.plan.test.ts regression for 0 and not-a-number, and by the client.test.ts / browser-tool.test.ts "default snapshot timeout" assertions.
- Optional BrowserSnapshotPlan.timeoutMs field — additive, so existing plan consumers remain unaffected; verified via the focused snapshot tests (5 files / 95 tests pass).
- The Playwright helpers clamp timeoutMs to Playwright's accepted range (500–60_000 ms). This matches the existing snapshotAiViaPlaywright model (page.ariaSnapshot({ mode: "ai", timeout: Math.max(500, Math.min(60_000, ...))})) and is preserved here as defensive normalization for the same external-API guarantees, not a new policy added in this PR.
What you did not verify: manual browser smoke not run; test environment is Ubuntu headless and has no prior validated browser-extension smoke setup. End-to-end snapshot reproduction against a real Chromium / Chrome MCP / Playwright stack was not executed. The fix is justified by targeted tests that exercise each seam where timeoutMs was dropped before this change.

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.

Compatibility / Migration

Backward compatible? Yes
Config/env changes? No
Migration needed? No
Default snapshot timeout value preserved at 20_000 ms; BrowserSnapshotPlan.timeoutMs is an optional field, so plan consumers (shouldUsePlaywrightForAriaSnapshot etc.) remain non-breaking. Direct snapshot path keeps the same effective deadline; the proxied path now also honors that deadline rather than being silently unbounded — this is the bug the PR fixes.

Risks and Mitigations

Risk: page.ariaSnapshot({ timeout }) / locator.ariaSnapshot({ timeout }) rely on the Playwright Locator API supporting an explicit timeout option.
- Mitigation: the same option is already used in production by snapshotAiViaPlaywright (page.ariaSnapshot({ mode: "ai", timeout })), so the Playwright surface is known to accept it.
Risk: forwarding timeoutMs to takeChromeMcpSnapshot engages the callTool race + session reset, which could surface previously masked transport hangs.
- Mitigation: this is the intended behavior — without the race, snapshot hangs were silent; the same wiring landed for navigate_page in PR fix(browser): reset Chrome MCP session after navigate_page timeout #69733 without follow-up issues.
Risk: applying the 20_000 ms default to the proxied path introduces a per-request deadline where there previously was none, which could surface timeouts that previously hung indefinitely.
- Mitigation: this is the bug fix itself — the symptom in [Bug]: Browser snapshot action consistently times out despite successful open/navigate #72934 is exactly that the snapshot path hangs forever; surfacing the deadline at 20_000 ms (the same value the direct path already uses) restores intended parity.

Notes for maintainers

A CHANGELOG.md entry was added under ## Unreleased → ### Fixes in a separate follow-up commit, per Clawsweeper's required-changelog guidance; please relocate or rephrase at release time if desired.
This PR keeps the default DEFAULT_BROWSER_SNAPSHOT_TIMEOUT_MS = 20_000. Adjusting that default is a separate UX discussion and intentionally not in this PR.
The Linux/Ubuntu all-action timeout reported in Bug: browser tool times out despite CDP connection working (Playwright can connect directly) #72653 is explicitly out of scope; even if the snapshot path on macOS recovers with this fix, Bug: browser tool times out despite CDP connection working (Playwright can connect directly) #72653 likely needs a different root-cause investigation (Playwright direct connection also fails per the issue thread).
The Playwright helpers preserve the existing Math.max(500, Math.min(60_000, ...)) clamp around page.ariaSnapshot({ timeout }) (matching snapshotAiViaPlaywright). This is a defensive normalization for what Playwright accepts, not a new policy introduced by this PR.

clawsweeper · 2026-05-01T15:02:07Z

Codex review: passed.

Latest ClawSweeper review: 2026-05-24 02:12 UTC / May 23, 2026, 10:12 PM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

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.

PR Surface
Source +55, Tests +320, Docs +1, Other +1. Total +377 across 15 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	7	62	7	+55
Tests	6	320	0	+320
Docs	1	1	0	+1
Config	0	0	0	0
Generated	0	0	0	0
Other	1	1	0	+1
Total	15	384	7	+377

Summary
Threads browser snapshot timeoutMs through the agent action, client/proxy request, snapshot route plan, Chrome MCP, Playwright/CDP helpers, regression tests, changelog, and one JSDoc-only shrinkwrap script type annotation.

Reproducibility: yes. source reproduction is high-confidence: current main accepts top-level browser timeoutMs, but snapshot action, client query serialization, route planning, Chrome MCP snapshot, and Playwright snapshot helpers drop it. I did not rerun the original macOS or Browserbase live scenario in this read-only review.

PR rating
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🦞 diamond lobster
Summary: The patch is focused and well covered, with sufficient real boundary proof but no full live Chromium/macOS reproduction in the supplied evidence.

Rank-up moves:

none

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.

Real behavior proof
Sufficient (terminal): The PR body includes terminal proof from a real loopback HTTP boundary using the production browserSnapshot client, showing timeout serialization and deadline behavior after the patch.

Mantis proof suggestion
A live browser snapshot smoke on a slow or heavy page would materially complement the supplied loopback proof before merge. A maintainer can ask Mantis to capture proof by posting a new PR comment that starts with the OpenClaw Mantis account mention, followed by:

visual task: verify that browser snapshot honors timeoutMs on a slow or heavy page and returns or times out at the requested deadline.

Risk before merge

The PR intentionally makes proxied snapshot requests honor the same 20s default that direct snapshots already used, so existing very slow proxied snapshots may now fail fast unless callers provide a larger timeoutMs.
The original macOS/Browserbase live failure was not rerun in this read-only review; the strongest proof is source inspection, focused tests, and the supplied real loopback HTTP-client boundary trace.
The broader Linux all-action browser timeout remains separately tracked at Bug: browser tool times out despite CDP connection working (Playwright can connect directly) #72653 and should not be considered solved by this snapshot-specific PR.

Maintainer options:

Accept the proxy fail-fast alignment (recommended)
Land the PR with the explicit behavior that proxied snapshots now share the direct snapshot 20s default and callers can raise timeoutMs for slower pages.
Adjust the default before merge
If maintainers want existing proxied snapshots to keep longer-running behavior by default, change or document that default before landing this patch.

Next step before merge
No ClawSweeper repair lane is needed; automerge is already armed and the remaining work is exact-head checks, maintainer acceptance of the timeout compatibility risk, and merge handling.

Security
Cleared: The diff threads numeric timeout values through existing browser code and tests, with no new dependencies, permissions, secrets handling, CI changes, downloads, or execution surfaces.

Review details

Best possible solution:

Land the focused timeout propagation after exact-head checks, accepting the proxy fail-fast alignment as intentional and keeping #72653 separate.

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

Yes, source reproduction is high-confidence: current main accepts top-level browser timeoutMs, but snapshot action, client query serialization, route planning, Chrome MCP snapshot, and Playwright snapshot helpers drop it. I did not rerun the original macOS or Browserbase live scenario in this read-only review.

Is this the best way to solve the issue?

Yes, this is the best narrow fix: it reuses the existing timeout contract and existing Chrome MCP/Playwright timeout surfaces instead of adding a new API. The only maintainer choice is whether the newly enforced 20s proxied snapshot default is acceptable.

Label justifications:

P1: The linked bug makes the browser snapshot tool unusable for affected real agent/browser workflows, and downstream users report it is still live on 2026.5.x.
merge-risk: 🚨 compatibility: Merging changes proxied snapshots from effectively unbounded behavior to a 20s enforced default unless callers supply a larger timeout.
rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🐚 platinum hermit, patch quality is 🦞 diamond lobster, and The patch is focused and well covered, with sufficient real boundary proof but no full live Chromium/macOS reproduction in the supplied evidence.
status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (terminal): The PR body includes terminal proof from a real loopback HTTP boundary using the production browserSnapshot client, showing timeout serialization and deadline behavior after the patch.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal proof from a real loopback HTTP boundary using the production browserSnapshot client, showing timeout serialization and deadline behavior after the patch.

What I checked:

Current main drops agent snapshot timeout: executeSnapshotAction builds snapshotQuery without input.timeoutMs and calls the proxy or browserSnapshot without a per-snapshot timeout value. (extensions/browser/src/browser-tool.actions.ts:368, d5814150267f)
Current main client only has a hardcoded local fetch timeout: browserSnapshot has no opts.timeoutMs, never serializes timeoutMs into /snapshot, and hardcodes fetchBrowserJson to 20000 ms. (extensions/browser/src/browser/client.ts:306, d5814150267f)
Current main route and leaf helpers miss snapshot deadlines: The /snapshot route does not pass a plan timeout into takeChromeMcpSnapshot, role snapshot helpers, AI snapshot helpers, or aria snapshot helpers; takeChromeMcpSnapshot calls callTool without timeout options. (extensions/browser/src/browser/routes/agent.snapshot.ts:576, d5814150267f)
PR head threads timeout from the agent boundary: At head 0eec196, executeSnapshotAction normalizes input.timeoutMs, applies DEFAULT_BROWSER_SNAPSHOT_TIMEOUT_MS, places it in the query, and passes it as proxy timeout. (extensions/browser/src/browser-tool.actions.ts:371, 0eec196962a2)
PR head threads timeout to route and helpers: At head 0eec196, the route passes plan.timeoutMs into Chrome MCP, CDP role, Playwright AI/role/aria snapshot, and labeled screenshot paths; Chrome MCP take_snapshot receives callTool timeout options. (extensions/browser/src/browser/routes/agent.snapshot.ts:576, 0eec196962a2)
Regression coverage added: The PR adds explicit route tests proving timeoutMs reaches CDP aria and role snapshot helpers, plus the PR diff shows client, action, Chrome MCP, and Playwright helper tests for the other seams. (extensions/browser/src/browser/routes/agent.snapshot.timeout.test.ts:96, 0eec196962a2)

Likely related people:

steipete: Recent GitHub history shows repeated browser snapshot/client/route work including doctor helpers, proxy routing, CDP role fallback, aria snapshot refs, existing-session timeout work, and observed dialog handling in the same surface. (role: feature owner and recent area contributor; confidence: high; commits: 1d4859dc5312, a98a0b94d1bf, ed1ac2fc4492; files: extensions/browser/src/browser-tool.actions.ts, extensions/browser/src/browser/client.ts, extensions/browser/src/browser/routes/agent.snapshot.ts)
vincentkoc: Recent commits in chrome-mcp.ts and browser bridge diagnostics make this person a strong adjacent reviewer for the Chrome MCP timeout side of the patch. (role: recent Chrome MCP/browser diagnostics contributor; confidence: medium; commits: 82e8b5232d33, ecb9028f9f9d, ce625162519c; files: extensions/browser/src/browser/chrome-mcp.ts)
scotthuang: Recent merged snapshot work touched pw-tools-core.snapshot.ts and related browser SSRF/read behavior, which overlaps the Playwright snapshot helper surface reviewed here. (role: adjacent snapshot safety contributor; confidence: medium; commits: 37af50f3db27; files: extensions/browser/src/browser/pw-tools-core.snapshot.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against d5814150267f.

masatohoshino · 2026-05-01T16:14:10Z

The earlier Clawsweeper changelog finding has been addressed (commit 6646e1e adds the required ### Fixes entry to ## Unreleased). The remaining mergeability flag appears to be CHANGELOG.md-only churn from the active release section, not E-1 implementation conflict. I'll avoid rebasing repeatedly on that file and can refresh the branch when maintainers are ready to land or if requested.

esqandil · 2026-05-21T12:44:44Z

Friendly nudge from a downstream operator hitting this on 2026.5.x: the underlying bug (#72934) is still live, the dist bundle still ships the hardcoded timeoutMs: 2e4 in browser-cli-inspect-*.js, and Browserbase / heavy-page snapshots regularly trip it. Re-applying a local sed patch after every OpenClaw upgrade is getting old.

This PR has been open 20 days at P1 / impact:crash-loop with proof:sufficient and zero maintainer review. Anything reviewers need from the author or downstream users to unblock landing? Happy to provide additional repro traces from a Linux + Browserbase setup if useful.

clawsweeper · 2026-05-22T22:56:55Z

ClawSweeper PR egg

✨ Hatched: 🥚 common Cosmic Review Wisp

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: sniffs out flaky tests.
Image traits: location CI tidepool; accessory release bell; palette cobalt, lime, and pearl; mood determined; pose pointing at a small proof artifact; shell paper lantern shell; lighting golden review-room light; background soft code-shaped tiles.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Cosmic Review Wisp in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

Takhoffman · 2026-05-24T01:35:04Z

@clawsweeper automerge

clawsweeper · 2026-05-24T01:35:06Z

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=0eec196962a2179f8d33d2d711ef592f6c6bcaaf)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-05-24T02:15:58Z
Merge commit: 069c7b87eb67

What merged:

Threads browser snapshot timeoutMs through the agent action, client/proxy request, snapshot route plan, Ch ... Playwright/CDP helpers, regression tests, changelog, and one JSDoc-only shrinkwrap script type annotation.
Reproducibility: yes. source reproduction is high-confidence: current main accepts top-level browser `timeou ... helpers drop it. I did not rerun the original macOS or Browserbase live scenario in this read-only review.

Automerge notes:

PR branch already contained follow-up commit before automerge: fix(browser): apply default snapshot timeout to proxy path and add Pl…
PR branch already contained follow-up commit before automerge: docs(changelog): add browser snapshot timeout propagation fix entry
PR branch already contained follow-up commit before automerge: fix(browser): thread snapshot timeoutMs through agent tool and helpers
PR branch already contained follow-up commit before automerge: fix(clawsweeper): address review for automerge-openclaw-openclaw-7570…

The automerge loop is complete.

Automerge progress:

2026-05-24 01:36:11 UTC review queued f7f59c8c7750 (queued)

2026-05-24 01:48:13 UTC review passed f7f59c8c7750 (structured ClawSweeper verdict: pass (sha=f7f59c8c77504a815be187e1f08ebd0b3b61e...)

2026-05-24 01:48:34 UTC repair queued f7f59c8c7750 (autonomous) Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052

2026-05-24 01:50:48 UTC repair started (running) in 0s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 automerge-openclaw-openclaw-75702

2026-05-24 01:51:03 UTC validation plan (passed) in 16s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 pnpm check:changed; pnpm lint; pnpm check:test-types

2026-05-24 01:51:15 UTC Codex write preflight (passed) in 28s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 danger-full-access

2026-05-24 01:56:35 UTC Codex edit 1 634a129bbbda (complete) in 5m 47s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 exit 0

2026-05-24 02:05:11 UTC validation and review 1 0eec196962a2 (base moved) in 14m 23s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 rebased

2026-05-24 02:05:16 UTC repair completed 0eec196962a2 (branch updated) in 14m 29s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 initial automerge rebase is delegated to Codex repair

2026-05-24 02:05:16 UTC review queued 0eec196962a2 (after repair)

2026-05-24 02:15:19 UTC automerge wait 0eec196962a2 (waiting) in 24m 31s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 waiting for exact-head ClawSweeper review pass

2026-05-24 02:07:02 UTC review queued 0eec196962a2 (queued)

2026-05-24 02:15:20 UTC repair finished 0eec196962a2 (pushed) in 24m 32s Run: https://github.com/openclaw/clawsweeper/actions/runs/26348928052 repair_contributor_branch

2026-05-24 02:15:48 UTC review passed 0eec196962a2 (structured ClawSweeper verdict: pass (sha=0eec196962a2179f8d33d2d711ef592f6c6bc...)

2026-05-24 02:16:00 UTC merged 0eec196962a2 (merged by ClawSweeper automerge)

…aywright helper tests

…2 (validation-1)

openclaw#75702) Summary: - Threads browser snapshot `timeoutMs` through the agent action, client/proxy request, snapshot route plan, Ch ... Playwright/CDP helpers, regression tests, changelog, and one JSDoc-only shrinkwrap script type annotation. - Reproducibility: yes. source reproduction is high-confidence: current main accepts top-level browser `timeou ... helpers drop it. I did not rerun the original macOS or Browserbase live scenario in this read-only review. Automerge notes: - PR branch already contained follow-up commit before automerge: fix(browser): apply default snapshot timeout to proxy path and add Pl… - PR branch already contained follow-up commit before automerge: docs(changelog): add browser snapshot timeout propagation fix entry - PR branch already contained follow-up commit before automerge: fix(browser): thread snapshot timeoutMs through agent tool and helpers - PR branch already contained follow-up commit before automerge: fix(clawsweeper): address review for automerge-openclaw-openclaw-7570… Validation: - ClawSweeper review passed for head 0eec196. - Required merge gates passed before the squash merge. Prepared head SHA: 0eec196 Review: openclaw#75702 (comment) Co-authored-by: masatohoshino <[email protected]> Co-authored-by: clawsweeper <274271284+clawsweeper[bot]@users.noreply.github.com> Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com> Approved-by: takhoffman Co-authored-by: takhoffman <[email protected]>

openclaw-barnacle Bot added the size: M label May 1, 2026

This was referenced May 1, 2026

Bug: browser tool times out despite CDP connection working (Playwright can connect directly) #72653

Closed

[Bug]: Browser snapshot action consistently times out despite successful open/navigate #72934

Closed

openclaw-barnacle Bot added the proof: supplied External PR includes structured after-fix real behavior proof. label May 17, 2026

clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. P1 High-priority user-facing bug, regression, or broken workflow. impact:crash-loop Crash, hang, restart loop, or process-level availability failure. labels May 17, 2026

masatohoshino force-pushed the pr/openclaw-browser-snapshot-timeout-propagation branch from 6646e1e to f7f59c8 Compare May 17, 2026 11:50

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 17, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 17, 2026

masatohoshino and others added 5 commits May 24, 2026 02:05

fix(browser): thread snapshot timeoutMs through agent tool and helpers

f39b476

fix(browser): apply default snapshot timeout to proxy path and add Pl…

9c8e667

…aywright helper tests

docs(changelog): add browser snapshot timeout propagation fix entry

1bc12b2

fix(browser): thread snapshot timeoutMs through agent tool and helpers

adeed3d

fix(clawsweeper): address review for automerge-openclaw-openclaw-7570…

0eec196

…2 (validation-1)

clawsweeper Bot force-pushed the pr/openclaw-browser-snapshot-timeout-propagation branch from f7f59c8 to 0eec196 Compare May 24, 2026 02:05

clawsweeper Bot requested a review from a team as a code owner May 24, 2026 02:05

openclaw-barnacle Bot added the scripts Repository scripts label May 24, 2026

clawsweeper Bot merged commit 069c7b8 into openclaw:main May 24, 2026
98 of 100 checks passed

github-actions Bot mentioned this pull request May 24, 2026

📡 Upstream Digest — 2026-05-24 02:32 UTC curtismercier/openclaw-mods#930

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(browser): thread snapshot timeoutMs through agent tool and helpers#75702

fix(browser): thread snapshot timeoutMs through agent tool and helpers#75702
clawsweeper[bot] merged 5 commits into
openclaw:mainfrom
masatohoshino:pr/openclaw-browser-snapshot-timeout-propagation

masatohoshino commented May 1, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 1, 2026 •

edited

Loading

Uh oh!

masatohoshino commented May 1, 2026

Uh oh!

esqandil commented May 21, 2026

Uh oh!

clawsweeper Bot commented May 22, 2026

Uh oh!

Takhoffman commented May 24, 2026

Uh oh!

clawsweeper Bot commented May 24, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

masatohoshino commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Root Cause (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Real behavior proof

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Notes for maintainers

Uh oh!

clawsweeper Bot commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

masatohoshino commented May 1, 2026

Uh oh!

esqandil commented May 21, 2026

Uh oh!

clawsweeper Bot commented May 22, 2026

Hatch command

Uh oh!

Takhoffman commented May 24, 2026

Uh oh!

clawsweeper Bot commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

masatohoshino commented May 1, 2026 •

edited

Loading

clawsweeper Bot commented May 1, 2026 •

edited

Loading

clawsweeper Bot commented May 24, 2026 •

edited

Loading