feat(browser): support evaluate timeouts for existing sessions (#103181)

HOYALIM · steipete · web-flow · commit 8a4463eef1b9 · 2026-07-11T15:23:52.000-07:00
* fix(browser): honor evaluate timeout for existing sessions

Signed-off-by: Ho Lim &lt;subhoya@gmail.com&gt;

* docs(browser): align existing-session evaluate timeouts

---------

Signed-off-by: Ho Lim &lt;subhoya@gmail.com&gt;
Co-authored-by: Peter Steinberger &lt;steipete@gmail.com&gt;
diff --git a/docs/cli/browser.md b/docs/cli/browser.md
@@ -255,7 +255,7 @@ Current existing-session limits:
 - `click` is left-click only.
 - `type` does not support `slowly=true`.
 - `press` does not support `delayMs`.
-- `hover`, `scrollintoview`, `drag`, `select`, `fill`, and `evaluate` reject per-call timeout overrides.
+- `hover`, `scrollintoview`, `drag`, `select`, and `fill` reject per-call timeout overrides; `evaluate` accepts `--timeout-ms`.
 - `select` supports one value only.
 - `wait --load networkidle` is not supported (works on managed and raw/remote CDP profiles).
 - File uploads require `--ref` / `--input-ref`, do not support CSS `--element`, and support one file at a time.
diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md
@@ -756,7 +756,6 @@ Look for:
     - `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 type does not support timeoutMs overrides.` → omit `timeoutMs` for `act:type` on `profile="user"` / Chrome MCP existing-session profiles, or use a managed/CDP browser profile when a custom timeout is required.
-    - `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/docs/tools/browser.md b/docs/tools/browser.md
@@ -786,7 +786,7 @@ directory.
 Compared to the managed `openclaw` profile, existing-session drivers are more constrained:
 
 - **Screenshots** - page captures and `--ref` element captures work; CSS `--element` selectors do not. Playwright is not required for page or ref-based element screenshots. (`--full-page` cannot combine with `--ref` or `--element` on any profile, not just existing-session.)
-- **Actions** - `click`, `type`, `hover`, `scrollIntoView`, `drag`, and `select` require snapshot refs (no CSS selectors). `click-coords` clicks visible viewport coordinates and does not require a snapshot ref. `click` is left-button only (no button overrides or modifiers). `type` does not support `slowly=true`; use `fill` or `press`. `press` does not support `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill`, and `evaluate` do not support per-call `timeoutMs` overrides. `select` accepts a single value. `batch` is not supported; send actions individually.
+- **Actions** - `click`, `type`, `hover`, `scrollIntoView`, `drag`, and `select` require snapshot refs (no CSS selectors). `click-coords` clicks visible viewport coordinates and does not require a snapshot ref. `click` is left-button only (no button overrides or modifiers). `type` does not support `slowly=true`; use `fill` or `press`. `press` does not support `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, and `fill` do not support per-call `timeoutMs` overrides; `evaluate` does. `select` accepts a single value. `batch` is not supported; send actions individually.
 - **Wait / upload / dialog** - `wait --url` supports exact, substring, and glob patterns (same as managed); `wait --load networkidle` is not supported on existing-session profiles (it works on managed and raw/remote CDP profiles). Upload hooks require `ref` or `inputRef`, one file at a time, no CSS `element`. Dialog hooks do not support timeout overrides or `dialogId`.
 - **Dialog visibility** - Managed browser action responses include `blockedByDialog` and `browserState.dialogs.pending` when an action opens a modal dialog; snapshots also include pending dialog state. Respond with `browser dialog --accept/--dismiss --dialog-id <id>` while a dialog is pending. Dialogs handled outside OpenClaw appear under `browserState.dialogs.recent`.
 - **Managed-only features** - PDF export, download interception, and `responsebody` still require the managed browser path.
diff --git a/extensions/browser/skills/browser-automation/SKILL.md b/extensions/browser/skills/browser-automation/SKILL.md
@@ -79,7 +79,7 @@ Use `profile="user"` only when existing cookies/login matter. This attaches to t
 
 On macOS, `action="importprofile"` is the alternative when the agent should use an isolated managed browser with cookies copied from a real Chrome-family profile. First use `action="profiles"` and inspect `systemProfiles`, then import into a fresh managed profile name. Import asks for one Keychain/Touch ID consent prompt. It copies cookies, not local storage or IndexedDB; device-bound session credentials (DBSC) mean some Google sessions may still require re-authentication.
 
-For `profile="user"` and other existing-session profiles, omit `timeoutMs` on `act:type`, `evaluate`, `hover`, `scrollIntoView`, `drag`, `select`, and `fill`; that driver rejects per-call timeout overrides for those actions.
+For `profile="user"` and other existing-session profiles, omit `timeoutMs` on `act:type`, `hover`, `scrollIntoView`, `drag`, `select`, and `fill`; that driver rejects per-call timeout overrides for those actions. `act:evaluate` accepts `timeoutMs`.
 
 ## Google Meet Notes
 
diff --git a/extensions/browser/src/browser-tool-description.ts b/extensions/browser/src/browser-tool-description.ts
@@ -8,7 +8,7 @@ export function describeBrowserTool(opts: {
     "Browser choice: omit profile to use the configured default (normally the isolated OpenClaw-managed `openclaw` browser).",
     "When existing logins/cookies matter, use action=profiles to inspect available profiles, then select the appropriate profile by name. Do not assume a profile name. Use only when the task requires an existing session and the user has authorized it.",
     "Use action=importprofile on macOS to copy cookies from an authorized Chrome-family system profile into a fresh managed profile; this may show a Keychain consent prompt.",
-    "For Chrome MCP existing-session profiles, omit timeoutMs on act:type, evaluate, hover, scrollIntoView, drag, select, and fill; that driver rejects per-call timeout overrides for those actions.",
+    "For Chrome MCP existing-session profiles, omit timeoutMs on act:type, hover, scrollIntoView, drag, select, and fill; that driver rejects per-call timeout overrides for those actions. act:evaluate supports timeoutMs.",
     '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 tab operations, targetId also accepts tabId handles (t1) and labels from action=tabs.",
     "For multi-step browser work, login checks, stale refs, duplicate tabs, or Google Meet flows, use the bundled browser-automation skill when it is available.",
diff --git a/extensions/browser/src/browser-tool.actions.ts b/extensions/browser/src/browser-tool.actions.ts
@@ -90,7 +90,6 @@ function existingSessionRejectsActTimeout(request: BrowserActRequest): boolean {
     case "drag":
     case "select":
     case "fill":
-    case "evaluate":
       return true;
     default:
       return false;
diff --git a/extensions/browser/src/browser-tool.test.ts b/extensions/browser/src/browser-tool.test.ts
@@ -523,6 +523,7 @@ describe("browser tool description", () => {
     expect(tool.description).toContain("Do not assume a profile name");
     expect(tool.description).not.toContain('profile="user"');
     expect(tool.description).toContain("omit timeoutMs on act:type");
+    expect(tool.description).toContain("act:evaluate supports timeoutMs");
     expect(tool.description).toContain("existing-session profiles");
     expect(tool.description).toContain("browser-automation skill");
     expect(tool.description).toContain("trigger ref with paths in the same upload call");
@@ -1898,6 +1899,32 @@ describe("browser tool act compatibility", () => {
     expect(opts.profile).toBe("user");
   });
 
+  it("injects configured action timeout for existing-session evaluate actions", async () => {
+    setResolvedBrowserProfiles({
+      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
+    });
+    configMocks.loadConfig.mockReturnValue({ browser: { actionTimeoutMs: 45_000 } });
+
+    const tool = createBrowserTool();
+    await tool.execute?.("call-1", {
+      action: "act",
+      profile: "user",
+      target: "host",
+      request: {
+        kind: "evaluate",
+        fn: "() => 1 + 1",
+      },
+    });
+
+    const request = lastMockCallArg<{ kind?: string; fn?: string; timeoutMs?: number }>(
+      browserActionsMocks.browserAct,
+      1,
+    );
+    const opts = lastMockCallArg<{ profile?: string }>(browserActionsMocks.browserAct, 2);
+    expect(request).toEqual({ kind: "evaluate", fn: "() => 1 + 1", timeoutMs: 45_000 });
+    expect(opts.profile).toBe("user");
+  });
+
   it("passes configured act timeout through node proxy with transport slack", async () => {
     mockSingleBrowserProxyNode();
     configMocks.loadConfig.mockReturnValue({
diff --git a/extensions/browser/src/browser/routes/agent.act.existing-session-navigation-guard.test.ts b/extensions/browser/src/browser/routes/agent.act.existing-session-navigation-guard.test.ts
@@ -234,6 +234,24 @@ describe("existing-session interaction navigation guard", () => {
     );
   });
 
+  it("forwards evaluate timeoutMs to Chrome MCP existing-session execution", async () => {
+    chromeMcpMocks.evaluateChromeMcpScript.mockResolvedValueOnce(42 as never);
+
+    const response = await runAction(
+      { kind: "evaluate", fn: "() => 1 + 1", timeoutMs: 60_000 },
+      null,
+    );
+
+    expect(response.statusCode).toBe(200);
+    expect(chromeMcpMocks.evaluateChromeMcpScript).toHaveBeenCalledOnce();
+    expect(chromeMcpMocks.evaluateChromeMcpScript).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fn: "() => 1 + 1",
+        timeoutMs: 60_000,
+      }),
+    );
+  });
+
   it("normalizes ref-scoped statement-body evaluate sources before Chrome MCP execution", async () => {
     chromeMcpMocks.evaluateChromeMcpScript.mockResolvedValueOnce("Ada" as never);
 
diff --git a/extensions/browser/src/browser/routes/agent.act.ts b/extensions/browser/src/browser/routes/agent.act.ts
@@ -335,7 +335,7 @@ function getExistingSessionUnsupportedMessage(action: BrowserActRequest): string
         ? EXISTING_SESSION_LIMITS.act.waitNetworkIdle
         : null;
     case "evaluate":
-      return action.timeoutMs !== undefined ? EXISTING_SESSION_LIMITS.act.evaluateTimeout : null;
+      return null;
     case "batch":
       return EXISTING_SESSION_LIMITS.act.batch;
     case "resize":
diff --git a/extensions/browser/src/browser/routes/existing-session-limits.ts b/extensions/browser/src/browser/routes/existing-session-limits.ts
@@ -27,7 +27,6 @@ export const EXISTING_SESSION_LIMITS = {
     selectTimeout: "existing-session select does not support timeoutMs overrides.",
     fillTimeout: "existing-session fill does not support timeoutMs overrides.",
     waitNetworkIdle: "existing-session wait does not support loadState=networkidle yet.",
-    evaluateTimeout: "existing-session evaluate does not support timeoutMs overrides.",
     batch: "existing-session batch is not supported yet; send actions individually.",
   },
   hooks: {
