Auto-merge upstream openclaw/openclaw

Author: friuns2

CHANGELOG.md

@@ -63,6 +63,7 @@ Docs: https://docs.openclaw.ai
 - ACP/stream relay: pass parent delivery context to ACP stream relay system events so `streamTo="parent"` updates route to the correct thread or topic instead of falling back to the main DM. (#57056) Thanks @pingren.
 - Agents/sessions: preserve announce `threadId` when `sessions.list` fallback rehydrates agent-to-agent announce targets so final announce messages stay in the originating thread/topic. (#63506) Thanks @SnowSky1.
 - Browser/plugin SDK: route browser auth, profile, host-inspection, and doctor readiness helpers through browser plugin public facades so core compatibility helpers stop carrying duplicate runtime implementations. (#63957) Thanks @joshavant.
+- Browser/act: centralize `/act` request normalization and execution dispatch while adding stable machine-readable route-level error codes for invalid requests, selector misuse, evaluate-disabled gating, target mismatch, and existing-session unsupported actions. (#63977) Thanks @joshavant.
 
 ## 2026.4.9
 

docs/tools/browser.md

@@ -576,6 +576,27 @@ Notes:
 - If `gateway.auth.mode` is `none` or `trusted-proxy`, these loopback browser
   routes do not inherit those identity-bearing modes; keep them loopback-only.
 
+### `/act` error contract
+
+`POST /act` uses a structured error response for route-level validation and
+policy failures:
+
+```json
+{ "error": "<message>", "code": "ACT_*" }
+```
+
+Current `code` values:
+
+- `ACT_KIND_REQUIRED` (HTTP 400): `kind` is missing or unrecognized.
+- `ACT_INVALID_REQUEST` (HTTP 400): action payload failed normalization or validation.
+- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` was used with an unsupported action kind.
+- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (or `wait --fn`) is disabled by config.
+- `ACT_TARGET_ID_MISMATCH` (HTTP 403): top-level or batched `targetId` conflicts with request target.
+- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): action is not supported for existing-session profiles.
+
+Other runtime failures may still return `{ "error": "<message>" }` without a
+`code` field.
+
 ### Playwright requirement
 
 Some features (navigate/act/AI snapshot/role snapshot, element screenshots,

extensions/browser/src/browser/act-policy.ts

@@ -0,0 +1,44 @@
+export const ACT_MAX_BATCH_ACTIONS = 100;
+export const ACT_MAX_BATCH_DEPTH = 5;
+export const ACT_MAX_CLICK_DELAY_MS = 5_000;
+export const ACT_MAX_WAIT_TIME_MS = 30_000;
+
+const ACT_MIN_TIMEOUT_MS = 500;
+const ACT_MAX_INTERACTION_TIMEOUT_MS = 60_000;
+const ACT_MAX_WAIT_TIMEOUT_MS = 120_000;
+const ACT_DEFAULT_INTERACTION_TIMEOUT_MS = 8_000;
+const ACT_DEFAULT_WAIT_TIMEOUT_MS = 20_000;
+
+export function normalizeActBoundedNonNegativeMs(
+  value: number | undefined,
+  fieldName: string,
+  maxMs: number,
+): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${fieldName} must be >= 0`);
+  }
+  const normalized = Math.floor(value);
+  if (normalized > maxMs) {
+    throw new Error(`${fieldName} exceeds maximum of ${maxMs}ms`);
+  }
+  return normalized;
+}
+
+export function resolveActInteractionTimeoutMs(timeoutMs?: number): number {
+  const normalized =
+    typeof timeoutMs === "number" && Number.isFinite(timeoutMs)
+      ? Math.floor(timeoutMs)
+      : ACT_DEFAULT_INTERACTION_TIMEOUT_MS;
+  return Math.max(ACT_MIN_TIMEOUT_MS, Math.min(ACT_MAX_INTERACTION_TIMEOUT_MS, normalized));
+}
+
+export function resolveActWaitTimeoutMs(timeoutMs?: number): number {
+  const normalized =
+    typeof timeoutMs === "number" && Number.isFinite(timeoutMs)
+      ? Math.floor(timeoutMs)
+      : ACT_DEFAULT_WAIT_TIMEOUT_MS;
+  return Math.max(ACT_MIN_TIMEOUT_MS, Math.min(ACT_MAX_WAIT_TIMEOUT_MS, normalized));
+}

extensions/browser/src/browser/pw-ai.ts

@@ -29,6 +29,7 @@ export {
   dragViaPlaywright,
   emulateMediaViaPlaywright,
   evaluateViaPlaywright,
+  executeActViaPlaywright,
   fillFormViaPlaywright,
   getConsoleMessagesViaPlaywright,
   getNetworkRequestsViaPlaywright,