fix(browser): clarify existing-session timeout limits

steipete · steipete · commit aa21d4ea7e9a · 2026-04-24T08:27:12.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,6 +30,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Browser/tool: tell agents not to pass per-call `timeoutMs` on existing-session evaluate and other Chrome MCP actions that reject timeout overrides.
 - Voice-call/Telnyx: preserve inbound/outbound callback metadata and read transcription text from Telnyx's current `transcription_data` payload.
 - Codex harness: send verbose tool progress to chat channels for native app-server runs, matching the Pi harness `/verbose on` and `/verbose full` behavior. (#70966) Thanks @jalehman.
 - Codex models: fetch paginated Codex app-server model catalogs, mark truncated `/codex models` output, and keep ChatGPT OAuth defaults on the `openai-codex/gpt-5.5` route instead of the OpenAI API-key route.
diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
@@ -482,6 +482,7 @@ Common signatures:
 - `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP upload hooks need snapshot refs, not CSS selectors.
 - `existing-session file uploads currently support one file at a time.` → send one upload per call on Chrome MCP profiles.
 - `existing-session dialog handling does not support timeoutMs.` → dialog hooks on Chrome MCP profiles do not support timeout overrides.
+- `existing-session evaluate does not support timeoutMs overrides.` → omit `timeoutMs` for `act:evaluate` on `profile="user"` / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
 - `response body is not supported for existing-session profiles yet.` → `responsebody` still requires a managed browser or raw CDP profile.
 - stale viewport / dark-mode / locale / offline overrides on attach-only or remote CDP profiles → run `openclaw browser stop --browser-profile <name>` to close the active control session and release Playwright/CDP emulation state without restarting the whole gateway.
 
diff --git a/extensions/browser/src/browser-tool.test.ts b/extensions/browser/src/browser-tool.test.ts
@@ -299,6 +299,16 @@ async function runSnapshotToolCall(params: {
   await tool.execute?.("call-1", { action: "snapshot", target: "host", ...params });
 }
 
+describe("browser tool description", () => {
+  it("warns agents about existing-session act timeout limits", () => {
+    const tool = createBrowserTool();
+
+    expect(tool.description).toContain('profile="user"');
+    expect(tool.description).toContain("omit timeoutMs on act:evaluate");
+    expect(tool.description).toContain("existing-session profiles");
+  });
+});
+
 describe("browser tool snapshot maxChars", () => {
   registerBrowserToolAfterEachReset();
 
diff --git a/extensions/browser/src/browser-tool.ts b/extensions/browser/src/browser-tool.ts
@@ -382,6 +382,7 @@ export function createBrowserTool(opts?: {
       "Control the browser via OpenClaw's browser control server (status/start/stop/profiles/tabs/open/snapshot/screenshot/actions).",
       "Browser choice: omit profile by default for the isolated OpenClaw-managed browser (`openclaw`).",
       'For the logged-in user browser, use profile="user". A supported Chromium-based browser (v144+) must be running on the selected host or browser node. Use only when existing logins/cookies matter and the user is present.',
+      'For profile="user" or other existing-session profiles, omit timeoutMs on act:evaluate, hover, scrollIntoView, drag, select, and fill; that driver rejects per-call timeout overrides for those actions.',
       'When a node-hosted browser proxy is available, the tool may auto-route to it. Pin a node with node=<id|name> or target="node".',
       "When using refs from snapshot (e.g. e12), keep the same tab: prefer passing targetId from the snapshot response into subsequent actions (act/click/type/etc).",
       'For stable, self-resolving refs across calls, use snapshot with refs="aria" (Playwright aria-ref ids). Default refs="role" are role+name-based.',
