ghost-bridge 1.0.2 → 1.2.0

package/README.md

@@ -16,6 +16,8 @@ Most browser-capable AI tools start a separate browser. Ghost Bridge connects AI
 - Inspect page structure, text, screenshots, errors, and network traffic
 - Search and extract script sources, even in production bundles
 - Click, type, scroll, and submit forms on the current page
+- Locate elements by role/name, label, placeholder, text, test ID, or CSS across open Shadow DOM and same-origin iframes
+- Run `locate → act → wait → snapshot` as one browser call instead of model-driven polling
 - Bind multiple Chrome tabs as named targets and operate them independently
 - Share one Chrome transport across multiple MCP clients
 
@@ -94,7 +96,9 @@ Typical prompts:
 | `capture_screenshot` | Visual inspection and UI debugging |
 | `get_page_content` | Text, HTML, and structured DOM extraction |
 | `get_interactive_snapshot` | Find clickable and editable elements |
-| `dispatch_action` | Click, fill, press, scroll, hover, select |
+| `dispatch_action` | Locate, act, wait, and verify in one call; supports semantic locators and batches |
+| `eval_script` | Execute JavaScript, wait for returned promises, and cap arbitrary output |
+| `page_request` | Send an authenticated page-context request and wait for the response in one call |
 | `bind_tab` | Bind a Chrome tab as a named target such as `cases` or `app` |
 | `unbind_tab` | Remove a named target binding |
 | `list_targets` | Show named targets and their per-tab session status |
@@ -113,16 +117,71 @@ Typical prompts:
 
 Recommended flow:
 
-1. Start with `inspect_page`
-2. Use `capture_screenshot` for visual issues
+1. When the target is describable, call `dispatch_action` directly with a semantic `locator`
+2. Use `inspect_page` when the page is unfamiliar or a locator is ambiguous; its compact response includes actionable refs
+3. Use `capture_screenshot` for visual issues
    Default is optimized for transfer with JPEG; switch to `png` for pixel-level checks
-3. Use `get_page_content` for DOM or text extraction
-4. Use `get_interactive_snapshot` before `dispatch_action`
+4. Use `get_page_content` for DOM or text extraction
+5. Put consecutive fills/clicks into one `dispatch_action.actions` call; add `waitFor` to the action that changes state and `snapshotAfter` when the resulting UI is needed
+
+Round-trip-efficient examples:
+
+```json
+{
+  "target": "app",
+  "actions": [
+    {
+      "locator": { "role": "textbox", "label": "Email" },
+      "action": "fill",
+      "value": "user@example.com"
+    },
+    {
+      "locator": { "role": "textbox", "label": "Password" },
+      "action": "fill",
+      "value": "secret"
+    },
+    {
+      "locator": { "role": "button", "name": "Sign in" },
+      "action": "click",
+      "waitFor": {
+        "type": "element",
+        "locator": { "text": "Signed in" },
+        "state": "visible",
+        "timeoutMs": 10000
+      }
+    }
+  ],
+  "snapshotAfter": true
+}
+```
+
+Locator fields are `css`, `testId`, `role` + `name`, `label`, `placeholder`, `text`, `match`, and zero-based `nth`. Matching is exact by default. Ghost Bridge refuses ambiguous action targets and returns compact candidates instead of silently choosing the first element.
+
+`waitFor` supports:
+
+- `element`: `visible`, `hidden`, `attached`, `detached`, or `enabled`
+- `url`: `contains` or `equals`
+- `networkIdle`: optional `idleMs`
+- `expression`: a truthy JavaScript expression, including a returned Promise
+
+Polling happens inside the extension at a short interval, so it does not create repeated model/tool turns. Each condition defaults to 10 seconds and is capped at 30 seconds. The whole batch has a hard deadline of at most 60 seconds; once reached, remaining actions are not executed. Fixed `waitMs` remains for compatibility but defaults to zero.
+
+For API calls that need the page's login state, prefer `page_request`. If custom asynchronous JavaScript is still needed, return the promise from `eval_script` instead of storing a result on `window` and polling it in another tool call:
+
+```javascript
+(async () => {
+  const response = await fetch('/api/items', { credentials: 'include' })
+  const data = await response.json()
+  return data.items.map(({ id, name }) => ({ id, name }))
+})()
+```
 
 Notes:
 
 - Use `bind_tab` when a workflow spans multiple pages. For example, bind a checklist page as `cases` and a business page as `app`, then call tools with `target: "cases"` or `target: "app"`.
 - All browser tools accept an optional `target` parameter. When named targets are bound, `dispatch_action` requires `target` so refs from one page are not accidentally used on another page.
+- Semantic locators traverse open Shadow DOM and readable same-origin iframes. Cross-origin iframe DOM is not accessible and is skipped explicitly.
+- `get_page_content` reports iframe counters and uses contiguous `offset`/`maxLength` slices, so pagination does not duplicate or skip the hidden middle of a head/tail truncation.
 - Use `pin_current_tab` when you are debugging a page and need to switch to other tabs without changing the AI target. Use `unpin_tab` to restore the original follow-focused-tab behavior.
 - `list_network_requests` and `get_network_detail` automatically summarize `data:` URLs and very long URLs so inline images or oversized query strings do not overwhelm model context
 

package/dist/server.js

@@ -28536,11 +28536,185 @@ var packageJsonPath = path.resolve(__dirname, "../package.json");
 var packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
 var GHOST_BRIDGE_VERSION = packageJson.version;
 
+// src/bridge-utils.js
+var DEFAULT_DISPATCH_TIMEOUT_MS = 3e4;
+var MAX_DISPATCH_TIMEOUT_MS = 6e4;
+function jsonText(data) {
+  return typeof data === "string" ? data : JSON.stringify(data);
+}
+function compact(value) {
+  if (Array.isArray(value)) {
+    const cleaned = value.map(compact).filter((item) => item !== void 0);
+    return cleaned.length ? cleaned : void 0;
+  }
+  if (value && typeof value === "object") {
+    const cleaned = {};
+    for (const [key, item] of Object.entries(value)) {
+      const compacted = compact(item);
+      if (compacted !== void 0) cleaned[key] = compacted;
+    }
+    return Object.keys(cleaned).length ? cleaned : void 0;
+  }
+  if (value === null || value === "") return void 0;
+  return value;
+}
+function out(data) {
+  return jsonText(compact(data));
+}
+function clampNumber(value, fallback, min, max) {
+  const number3 = Number(value);
+  if (!Number.isFinite(number3)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(number3)));
+}
+function buildTruncatedOutput(text, retainedChars) {
+  const headLength = Math.ceil(retainedChars * 0.8);
+  const tailLength = Math.max(0, retainedChars - headLength);
+  const omitted = Math.max(0, text.length - headLength - tailLength);
+  return out({
+    truncated: true,
+    originalLength: text.length,
+    content: `${text.slice(0, headLength)}
+... [\u5DF2\u7701\u7565 ${omitted} \u4E2A\u5B57\u7B26] ...
+${tailLength ? text.slice(-tailLength) : ""}`,
+    hint: "\u9700\u8981\u66F4\u591A\u7ED3\u679C\u65F6\u8BF7\u6536\u7A84\u8FD4\u56DE\u5B57\u6BB5\uFF1B\u4E0D\u8981\u901A\u8FC7\u8FDE\u7EED\u8F6E\u8BE2\u5206\u7247\u83B7\u53D6\u5927\u5BF9\u8C61"
+  });
+}
+function boundedOut(data, maxLength, { defaultLength = 8e3, maxAllowed = 5e4 } = {}) {
+  const text = out(data) ?? "undefined";
+  const limit = clampNumber(maxLength, defaultLength, 200, maxAllowed);
+  if (text.length <= limit) return text;
+  let low = 0;
+  let high = text.length;
+  let best = buildTruncatedOutput(text, 0);
+  if (best.length > limit) {
+    return JSON.stringify({ truncated: true });
+  }
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    const candidate = buildTruncatedOutput(text, middle);
+    if (candidate.length <= limit) {
+      best = candidate;
+      low = middle + 1;
+    } else {
+      high = middle - 1;
+    }
+  }
+  return best;
+}
+function calculateDispatchBudget(args = {}) {
+  const steps = Array.isArray(args.actions) ? args.actions : [args];
+  if (!steps.length || steps.length > 20) throw new Error("actions \u6570\u91CF\u5FC5\u987B\u5728 1-20 \u4E4B\u95F4");
+  const totalLegacyWaitMs = steps.reduce(
+    (sum, step) => sum + clampNumber(step.waitMs, 0, 0, 3e3),
+    0
+  );
+  const totalConditionWaitMs = steps.reduce(
+    (sum, step) => sum + (step.waitFor ? clampNumber(step.waitFor.timeoutMs, 1e4, 100, 3e4) : 0),
+    0
+  );
+  const estimatedActionMs = steps.length * 750;
+  const snapshotMs = args.snapshotAfter ? 2e3 : 0;
+  const estimatedExecutionMs = 2e3 + estimatedActionMs + totalLegacyWaitMs + totalConditionWaitMs + snapshotMs;
+  const explicitTimeout = args.timeoutMs === void 0 ? null : clampNumber(args.timeoutMs, DEFAULT_DISPATCH_TIMEOUT_MS, 1e3, MAX_DISPATCH_TIMEOUT_MS);
+  if (explicitTimeout === null && estimatedExecutionMs > MAX_DISPATCH_TIMEOUT_MS) {
+    throw new Error(
+      `\u6279\u5904\u7406\u6700\u574F\u6267\u884C\u9884\u7B97 ${estimatedExecutionMs}ms \u8D85\u8FC7 ${MAX_DISPATCH_TIMEOUT_MS}ms\uFF1B\u8BF7\u51CF\u5C11\u52A8\u4F5C/\u7B49\u5F85\u6570\u91CF\u3001\u7F29\u77ED waitFor.timeoutMs\uFF0C\u6216\u663E\u5F0F\u8BBE\u7F6E\u8F83\u5C0F\u7684\u6574\u4F53 timeoutMs \u8BA9\u6279\u5904\u7406\u6309\u622A\u6B62\u65F6\u95F4\u505C\u6B62`
+    );
+  }
+  const executionTimeoutMs = explicitTimeout ?? Math.max(5e3, Math.min(MAX_DISPATCH_TIMEOUT_MS, estimatedExecutionMs));
+  return {
+    steps,
+    estimatedExecutionMs,
+    executionTimeoutMs,
+    serverTimeoutMs: executionTimeoutMs + 5e3
+  };
+}
+
+// src/tool-schemas.js
+var LOCATOR_REF = { $ref: "#/$defs/locator" };
+var WAIT_FOR_REF = { $ref: "#/$defs/wait" };
+var LOCATOR_DEFINITION = {
+  type: "object",
+  description: "\u591A\u5B57\u6BB5\u540C\u65F6\u6EE1\u8DB3\uFF1B\u9ED8\u8BA4 exact\uFF0C\u6B67\u4E49\u65F6\u7528 nth \u6216\u6536\u7A84\u6761\u4EF6\u3002",
+  properties: {
+    css: { type: "string", description: "CSS \u9009\u62E9\u5668" },
+    testId: { type: "string", description: "data-testid" },
+    role: { type: "string", description: "ARIA/\u9690\u5F0F role" },
+    name: { type: "string", description: "\u53EF\u8BBF\u95EE\u540D\u79F0" },
+    label: { type: "string", description: "\u8868\u5355 label/aria-label" },
+    placeholder: { type: "string" },
+    text: { type: "string", description: "\u5143\u7D20\u6587\u672C" },
+    nth: { type: "integer", minimum: 0, description: "\u4ECE 0 \u5F00\u59CB" },
+    match: { enum: ["exact", "contains"], description: "\u9ED8\u8BA4 exact" }
+  }
+};
+var WAIT_FOR_DEFINITION = {
+  type: "object",
+  description: "\u52A8\u4F5C\u540E\u5728\u6269\u5C55\u5185\u90E8\u7B49\u5F85\uFF0C\u4E0D\u589E\u52A0\u6A21\u578B\u5F80\u8FD4\u3002",
+  properties: {
+    type: { enum: ["element", "url", "networkIdle", "expression"] },
+    locator: { ...LOCATOR_REF, description: "element \u6761\u4EF6\u7684\u5B9A\u4F4D\u5668\uFF1B\u7701\u7565\u65F6\u590D\u7528\u52A8\u4F5C locator" },
+    state: { enum: ["visible", "hidden", "attached", "detached", "enabled"], description: "element \u9ED8\u8BA4 visible" },
+    contains: { type: "string", description: "URL \u5305\u542B" },
+    equals: { type: "string", description: "URL \u7B49\u4E8E" },
+    idleMs: { type: "number", minimum: 100, maximum: 1e4, description: "networkIdle \u7A7A\u95F2\u65F6\u95F4" },
+    expression: { type: "string", description: "JS \u771F\u503C\u8868\u8FBE\u5F0F\uFF0C\u53EF\u8FD4\u56DE Promise" },
+    timeoutMs: { type: "number", minimum: 100, maximum: 3e4, description: "\u9ED8\u8BA4 10000" }
+  },
+  required: ["type"]
+};
+var ACTION_PROPERTIES = {
+  ref: { type: "string" },
+  selector: { type: "string" },
+  locator: LOCATOR_REF,
+  action: { enum: ["click", "fill", "press", "scroll", "select", "hover", "focus"] },
+  value: { type: "string" },
+  key: { type: "string" },
+  deltaX: { type: "number" },
+  deltaY: { type: "number" },
+  waitMs: { type: "number", minimum: 0, maximum: 3e3 },
+  waitFor: WAIT_FOR_REF
+};
+var ACTION_DEFINITION = {
+  type: "object",
+  properties: ACTION_PROPERTIES,
+  required: ["action"]
+};
+var DISPATCH_ACTION_TOOL = {
+  name: "dispatch_action",
+  description: "\u5B9A\u4F4D\u2192\u64CD\u4F5C\u2192\u7B49\u5F85\u2192\u5FEB\u7167\u4E00\u6B21\u5B8C\u6210\u3002\u5355\u52A8\u4F20 ref/selector/locator+action\uFF0C\u6279\u91CF\u4F20 actions\uFF1Bfill/select \u7528 value\uFF0Cpress \u7528 key\u3002",
+  inputSchema: {
+    type: "object",
+    $defs: {
+      locator: LOCATOR_DEFINITION,
+      wait: WAIT_FOR_DEFINITION,
+      action: ACTION_DEFINITION
+    },
+    properties: {
+      target: { type: "string" },
+      ...ACTION_PROPERTIES,
+      timeoutMs: { type: "number", minimum: 1e3, maximum: 6e4 },
+      actions: {
+        type: "array",
+        minItems: 1,
+        maxItems: 20,
+        items: { $ref: "#/$defs/action" }
+      },
+      stopOnError: { type: "boolean" },
+      snapshotAfter: { type: "boolean" },
+      snapshotSelector: { type: "string" },
+      snapshotMaxElements: { type: "number" }
+    }
+  }
+};
+
 // src/server.js
 var BASE_PORT = Number(process.env.GHOST_BRIDGE_PORT || 33333);
 var DEFAULT_WS_TOKEN = "ghost-bridge-local";
 var WS_TOKEN = process.env.GHOST_BRIDGE_TOKEN || DEFAULT_WS_TOKEN;
 var RESPONSE_TIMEOUT = 8e3;
+var DEFAULT_EVAL_OUTPUT_LENGTH = 8e3;
+var MAX_EVAL_OUTPUT_LENGTH = 5e4;
 var PORT_INFO_FILE = process.env.GHOST_BRIDGE_PORT_INFO || path2.join(os.tmpdir(), "ghost-bridge-port.json");
 var SERVER_STARTED_AT = (/* @__PURE__ */ new Date()).toISOString();
 var SERVER_ENTRY_PATH = fileURLToPath2(import.meta.url);
@@ -29128,27 +29302,9 @@ async function askChrome(command, params = {}, options = {}) {
     });
   });
 }
-function jsonText(data) {
-  return typeof data === "string" ? data : JSON.stringify(data);
-}
-function compact(value) {
-  if (Array.isArray(value)) {
-    const cleaned = value.map(compact).filter((v) => v !== void 0);
-    return cleaned.length ? cleaned : void 0;
-  }
-  if (value && typeof value === "object") {
-    const cleaned = {};
-    for (const [k, v] of Object.entries(value)) {
-      const c = compact(v);
-      if (c !== void 0) cleaned[k] = c;
-    }
-    return Object.keys(cleaned).length ? cleaned : void 0;
-  }
-  if (value === null || value === "") return void 0;
-  return value;
-}
-function out(data) {
-  return jsonText(compact(data));
+function truncateUrl(url2, maxLen = 200) {
+  if (typeof url2 !== "string" || url2.length <= maxLen) return url2;
+  return url2.slice(0, maxLen) + "\u2026";
 }
 function shrinkListTabs(res, { fullUrl } = {}) {
   if (!res || !Array.isArray(res.tabs)) return res;
@@ -29230,7 +29386,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: "inspect_page",
-      description: "\u9875\u9762\u5206\u6790\u5165\u53E3\uFF1A\u8FD4\u56DE\u5143\u6570\u636E\u3001\u7ED3\u6784\u8BA1\u6570\u4E0E\u53EF\u4EA4\u4E92\u5143\u7D20\u6570\u91CF\uFF08\u7D27\u51D1\u6A21\u5F0F\uFF09\u3002\u9700\u8981\u5B8C\u6574 page/interactive \u6570\u636E\u4F20 detail:true\u3002",
+      description: "\u9875\u9762\u5206\u6790\u5165\u53E3\uFF1A\u4E00\u6B21\u8FD4\u56DE\u5143\u6570\u636E\u3001\u7ED3\u6784\u8BA1\u6570\u548C\u5C11\u91CF\u53EF\u76F4\u63A5\u64CD\u4F5C\u7684\u5143\u7D20 ref\uFF0C\u901A\u5E38\u65E0\u9700\u518D\u8C03\u7528 get_interactive_snapshot\u3002detail:true \u8FD4\u56DE\u5B8C\u6574\u7ED3\u6784\u3002",
       inputSchema: {
         type: "object",
         properties: {
@@ -29245,7 +29401,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
           maxElements: {
             type: "number",
-            description: "detail \u6A21\u5F0F\u4E0B\u53EF\u4EA4\u4E92\u5143\u7D20\u4E0A\u9650\uFF0C\u9ED8\u8BA4 30"
+            description: "\u8FD4\u56DE\u53EF\u4EA4\u4E92\u5143\u7D20\u4E0A\u9650\uFF0C\u9ED8\u8BA4 20"
+          },
+          includeElements: {
+            type: "boolean",
+            description: "\u7D27\u51D1\u6A21\u5F0F\u662F\u5426\u9644\u5E26\u53EF\u64CD\u4F5C\u5143\u7D20\uFF0C\u9ED8\u8BA4 true"
           },
           detail: {
             type: "boolean",
@@ -29395,13 +29555,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "eval_script",
-      description: "\u5728\u76EE\u6807\u9875\u6267\u884C\u53EA\u8BFB JS \u8868\u8FBE\u5F0F\uFF08\u8C28\u614E\u4F7F\u7528\uFF09\u3002",
+      description: "\u5728\u76EE\u6807\u9875\u6267\u884C JS\u3002\u9AD8\u6210\u672C\u5DE5\u5177\uFF1A\u540C\u4E00\u76EE\u6807\u7684\u8BFB\u53D6/\u64CD\u4F5C\u5E94\u5408\u5E76\u8FDB\u4E00\u6B21 code\uFF1B\u5F02\u6B65\u4EE3\u7801\u76F4\u63A5\u8FD4\u56DE Promise\uFF0C\u672C\u5DE5\u5177\u9ED8\u8BA4\u7B49\u5F85\u5B8C\u6210\uFF0C\u7981\u6B62\u5199 window \u4E34\u65F6\u53D8\u91CF\u540E\u518D\u6B21\u8F6E\u8BE2\u3002\u7ED3\u679C\u9ED8\u8BA4\u6700\u591A 8000 \u5B57\u7B26\u3002",
       inputSchema: {
         type: "object",
-        properties: { target: TARGET_ARG, code: { type: "string" } },
+        properties: {
+          target: TARGET_ARG,
+          code: { type: "string", description: "JS \u8868\u8FBE\u5F0F\uFF1B\u5F02\u6B65\u793A\u4F8B\uFF1A(async()=>await fetch(...).then(r=>r.json()))()" },
+          awaitPromise: { type: "boolean", description: "\u7B49\u5F85 Promise \u5B8C\u6210\uFF0C\u9ED8\u8BA4 true" },
+          timeoutMs: { type: "number", description: "Promise \u7B49\u5F85\u4E0A\u9650\uFF0C\u9ED8\u8BA4 10000\uFF0C\u6700\u5927 30000" },
+          maxOutputLength: { type: "number", description: "\u5E8F\u5217\u5316\u7ED3\u679C\u5B57\u7B26\u4E0A\u9650\uFF0C\u9ED8\u8BA4 8000\uFF0C\u6700\u5927 50000" }
+        },
         required: ["code"]
       }
     },
+    {
+      name: "page_request",
+      description: "\u4F7F\u7528\u5F53\u524D\u9875\u9762\u767B\u5F55\u6001\u53D1\u8D77 fetch \u5E76\u7B49\u5F85\u54CD\u5E94\uFF0C\u4E00\u6B21\u8FD4\u56DE\u7ED3\u679C\uFF1B\u9875\u9762\u63A5\u53E3\u8C03\u7528\u4F18\u5148\u7528\u5B83\uFF0C\u907F\u514D eval_script \u53D1\u8D77\u8BF7\u6C42\u540E\u518D\u8F6E\u8BE2\u3002",
+      inputSchema: {
+        type: "object",
+        properties: {
+          target: TARGET_ARG,
+          url: { type: "string", description: "\u76F8\u5BF9\u6216\u7EDD\u5BF9 HTTP(S) URL" },
+          method: { type: "string", description: "\u9ED8\u8BA4 GET" },
+          headers: { type: "object", description: "\u8BF7\u6C42\u5934" },
+          body: { description: "\u5B57\u7B26\u4E32\u6216 JSON \u5BF9\u8C61\uFF1B\u5BF9\u8C61\u4F1A\u81EA\u52A8 JSON.stringify" },
+          responseType: { type: "string", enum: ["auto", "json", "text"], description: "\u9ED8\u8BA4 auto" },
+          timeoutMs: { type: "number", description: "\u9ED8\u8BA4 10000\uFF0C\u6700\u5927 30000" },
+          maxOutputLength: { type: "number", description: "\u54CD\u5E94\u5185\u5BB9\u5B57\u7B26\u4E0A\u9650\uFF0C\u9ED8\u8BA4 8000\uFF0C\u6700\u5927 50000" }
+        },
+        required: ["url"]
+      }
+    },
     {
       name: "list_network_requests",
       description: "\u5217\u51FA\u6355\u83B7\u7684\u7F51\u7EDC\u8BF7\u6C42\uFF0C\u652F\u6301 URL/\u65B9\u6CD5/\u72B6\u6001/\u7C7B\u578B\u8FC7\u6EE4\uFF1B\u8D85\u957F URL \u81EA\u52A8\u6458\u8981\u3002",
@@ -29481,7 +29665,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "get_page_content",
-      description: "\u63D0\u53D6\u9875\u9762\u6587\u672C/HTML/\u7ED3\u6784\u5316\u6570\u636E\uFF0C\u6BD4\u622A\u56FE\u8F7B\u91CF\u3002\u9ED8\u8BA4\u4E0A\u9650 8000 \u5B57\u7B26\uFF1B\u4E0D\u591F\u65F6\u8C03\u5927 maxLength \u6216\u7528 offset \u7FFB\u9875\u3001selector \u6536\u7A84\u3002\u4E0D\u53CD\u6620 CSS\uFF0C\u4E0D\u542B iframe\u3002",
+      description: "\u63D0\u53D6\u9875\u9762\u6587\u672C/HTML/\u7ED3\u6784\u5316\u6570\u636E\uFF0C\u6BD4\u622A\u56FE\u8F7B\u91CF\u3002text \u6A21\u5F0F\u9012\u5F52\u6536\u96C6\u540C\u6E90 iframe \u6587\u672C\uFF08\u9002\u5408\u6587\u6863\u7C7B\u9875\u9762\uFF09\u3002\u9ED8\u8BA4\u4E0A\u9650 8000 \u5B57\u7B26\uFF1B\u4E0D\u591F\u65F6\u8C03\u5927 maxLength \u6216\u7528 offset \u7FFB\u9875\u3001selector \u6536\u7A84\u3002\u4E0D\u53CD\u6620 CSS\u3002",
       inputSchema: {
         type: "object",
         properties: {
@@ -29512,7 +29696,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "get_interactive_snapshot",
-      description: "\u626B\u63CF\u53EF\u89C1\u53EF\u4EA4\u4E92\u5143\u7D20\uFF0C\u8FD4\u56DE\u5E26 ref \u7684\u7CBE\u7B80\u5217\u8868\u4F9B dispatch_action \u4F7F\u7528\uFF08\u5148\u5FEB\u7167\u540E\u64CD\u4F5C\uFF09\u3002\u9ED8\u8BA4 30 \u4E2A\uFF0C\u9700\u8981\u66F4\u591A\u4F20 maxElements \u6216\u7528 selector \u6536\u7A84\u3002\u652F\u6301 Shadow DOM\u3002",
+      description: "\u5F53\u65E0\u6CD5\u76F4\u63A5\u5199\u51FA\u8BED\u4E49 locator \u65F6\uFF0C\u626B\u63CF\u53EF\u89C1\u53EF\u4EA4\u4E92\u5143\u7D20\u5E76\u8FD4\u56DE ref\u3002\u9ED8\u8BA4 30 \u4E2A\uFF0C\u9700\u8981\u66F4\u591A\u4F20 maxElements \u6216\u7528 selector \u6536\u7A84\u3002\u652F\u6301 Shadow DOM\u3002",
       inputSchema: {
         type: "object",
         properties: {
@@ -29532,45 +29716,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         }
       }
     },
-    {
-      name: "dispatch_action",
-      description: "\u5BF9 get_interactive_snapshot \u8FD4\u56DE\u7684 ref \u6267\u884C\u64CD\u4F5C\uFF1Aclick/fill/press/scroll/select/hover/focus\u3002\u26A0\uFE0F \u5FC5\u987B\u5148\u5FEB\u7167\u62FF ref\uFF1B\u64CD\u4F5C\u540E\u5EFA\u8BAE\u590D\u67E5\u9875\u9762\u72B6\u6001\u3002",
-      inputSchema: {
-        type: "object",
-        properties: {
-          target: TARGET_ARG,
-          ref: {
-            type: "string",
-            description: "\u5143\u7D20 ref\uFF0C\u5982 'e1'\uFF08\u6765\u81EA get_interactive_snapshot\uFF09"
-          },
-          action: {
-            type: "string",
-            enum: ["click", "fill", "press", "scroll", "select", "hover", "focus"]
-          },
-          value: {
-            type: "string",
-            description: "fill \u7684\u6587\u672C / select \u7684 option value"
-          },
-          key: {
-            type: "string",
-            description: "press \u6309\u952E\uFF0C\u9ED8\u8BA4 'Enter'"
-          },
-          deltaX: {
-            type: "number",
-            description: "\u6C34\u5E73\u6EDA\u52A8\u91CF\uFF0C\u9ED8\u8BA4 0"
-          },
-          deltaY: {
-            type: "number",
-            description: "\u5782\u76F4\u6EDA\u52A8\u91CF\uFF0C\u9ED8\u8BA4 300\uFF08\u6B63\u6570\u5411\u4E0B\uFF09"
-          },
-          waitMs: {
-            type: "number",
-            description: "\u64CD\u4F5C\u540E\u7B49\u5F85 ms\uFF0C\u9ED8\u8BA4 500\uFF0C\u6700\u5927 3000"
-          }
-        },
-        required: ["ref", "action"]
-      }
-    }
+    DISPATCH_ACTION_TOOL
   ]
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -29578,7 +29724,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const args = request.params.arguments || {};
   try {
     if (name === "inspect_page") {
-      const { target, selector, includeInteractive = true, maxElements = 30, detail = false } = args;
+      const { target, selector, includeInteractive = true, maxElements = 20, includeElements = true, detail = false } = args;
       const snapshot = await askChrome("inspectPageSnapshot", {
         target,
         selector,
@@ -29593,13 +29739,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const interactiveCount = Array.isArray(interactive?.elements) ? interactive.elements.length : Array.isArray(interactive) ? interactive.length : void 0;
       const summary = {
         title: page?.metadata?.title,
-        url: page?.metadata?.url,
+        url: truncateUrl(page?.metadata?.url),
         description: page?.metadata?.description,
         links,
         buttons,
         forms,
         interactiveCount
       };
+      const elements = includeElements && Array.isArray(interactive?.elements) ? interactive.elements : void 0;
       return {
         content: [
           {
@@ -29609,10 +29756,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 summary,
                 page,
                 interactive,
-                nextStepHint: "\u89C6\u89C9\u7528 capture_screenshot\uFF1B\u70B9\u51FB/\u8F93\u5165\u7528 get_interactive_snapshot + dispatch_action\uFF1B\u8BF7\u6C42/\u6027\u80FD\u7528 list_network_requests / perf_metrics\u3002"
+                nextStepHint: "\u89C6\u89C9\u7528 capture_screenshot\uFF1B\u70B9\u51FB/\u8F93\u5165\u4F18\u5148\u7528 dispatch_action \u8BED\u4E49 locator\uFF0C\u5F53\u524D refs \u4E5F\u53EF\u76F4\u63A5\u4F7F\u7528\uFF1B\u8BF7\u6C42/\u6027\u80FD\u7528 list_network_requests / perf_metrics\u3002"
               } : {
                 summary,
-                nextStepHint: "\u4F20 detail:true \u67E5\u770B\u5B8C\u6574 page/interactive\uFF1B\u89C6\u89C9\u7528 capture_screenshot\uFF1B\u4EA4\u4E92\u5148 get_interactive_snapshot \u518D dispatch_action\u3002"
+                interactive: elements ? { viewport: interactive?.viewport, elements } : void 0,
+                nextStepHint: "\u53EF\u76F4\u63A5\u7528 interactive.elements \u7684 ref \u8C03 dispatch_action\uFF1B\u8FDE\u7EED\u52A8\u4F5C\u653E\u8FDB actions\uFF0C\u64CD\u4F5C\u540E\u9700\u7EE7\u7EED\u5B9A\u4F4D\u65F6\u4F20 snapshotAfter:true\u3002"
               }
             )
           }
@@ -29758,8 +29906,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: "text", text: out(res) }] };
     }
     if (name === "eval_script") {
-      const res = await askChrome("eval", { target: args.target, code: args.code });
-      return { content: [{ type: "text", text: out(res) }] };
+      const timeoutMs = clampNumber(args.timeoutMs, 1e4, 100, 3e4);
+      const res = await askChrome("eval", {
+        target: args.target,
+        code: args.code,
+        awaitPromise: args.awaitPromise !== false,
+        timeoutMs
+      }, { timeoutMs: timeoutMs + 3e3 });
+      return { content: [{ type: "text", text: boundedOut(res, args.maxOutputLength) }] };
+    }
+    if (name === "page_request") {
+      const timeoutMs = clampNumber(args.timeoutMs, 1e4, 100, 3e4);
+      const maxOutputLength = clampNumber(args.maxOutputLength, DEFAULT_EVAL_OUTPUT_LENGTH, 200, MAX_EVAL_OUTPUT_LENGTH);
+      const res = await askChrome("pageRequest", {
+        target: args.target,
+        url: args.url,
+        method: args.method,
+        headers: args.headers,
+        body: args.body,
+        responseType: args.responseType,
+        timeoutMs,
+        maxOutputLength
+      }, { timeoutMs: timeoutMs + 3e3 });
+      return { content: [{ type: "text", text: boundedOut(res, maxOutputLength) }] };
     }
     if (name === "list_network_requests") {
       const { target, filter, method, status, resourceType, limit, priorityMode = "debug" } = args;
@@ -29807,6 +29976,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     if (name === "get_page_content") {
       const { target, mode = "text", selector, maxLength = 8e3, offset = 0, includeMetadata = true } = args;
+      const safeMaxLength = clampNumber(maxLength, 8e3, 1, 5e4);
+      const safeOffset = clampNumber(offset, 0, 0, 1e8);
       const validModes = ["text", "html", "structured"];
       if (mode && !validModes.includes(mode)) {
         return {
@@ -29816,22 +29987,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           }]
         };
       }
-      if (offset > 0 && mode === "text") {
-        const selectorExpr = selector ? `(document.querySelector(${JSON.stringify(selector)}) || document.body)` : "document.body";
-        const code = `(function(){try{var text=(${selectorExpr}).innerText||"";var start=${offset};var end=${offset + maxLength};return {content:text.slice(start,end),offset:start,totalLength:text.length,hasMore:text.length>end};}catch(e){return {error:e.message}}})()`;
-        const res2 = await askChrome("eval", { target, code });
-        return { content: [{ type: "text", text: out(res2) }] };
-      }
-      if (offset > 0 && mode === "html") {
-        const res2 = await askChrome("getPageContent", { target, mode, selector, maxLength: offset + maxLength, includeMetadata: false });
-        if (typeof res2?.content === "string") {
-          res2.content = res2.content.slice(offset, offset + maxLength);
-          res2.offset = offset;
-          res2.hasMore = (res2.contentLength || 0) > offset + maxLength;
-        }
-        return { content: [{ type: "text", text: out(res2) }] };
+      const res = await askChrome("getPageContent", {
+        target,
+        mode,
+        selector,
+        maxLength: safeMaxLength,
+        offset: safeOffset,
+        includeMetadata
+      });
+      if (typeof res?.metadata?.url === "string" && res.metadata.url.length > 200) {
+        res.metadata.url = truncateUrl(res.metadata.url);
+        res.metadata.urlTruncated = true;
       }
-      const res = await askChrome("getPageContent", { target, mode, selector, maxLength, includeMetadata });
       return { content: [{ type: "text", text: out(res) }] };
     }
     if (name === "get_interactive_snapshot") {
@@ -29840,8 +30007,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: "text", text: out(res) }] };
     }
     if (name === "dispatch_action") {
-      const { target, ref, action, value, key, deltaX, deltaY, waitMs } = args;
-      const res = await askChrome("dispatchAction", { target, ref, action, value, key, deltaX, deltaY, waitMs }, { timeoutMs: 1e4 });
+      const budget = calculateDispatchBudget(args);
+      const res = await askChrome(
+        "dispatchAction",
+        { ...args, timeoutMs: budget.executionTimeoutMs },
+        { timeoutMs: budget.serverTimeoutMs }
+      );
       return { content: [{ type: "text", text: out(res) }] };
     }
     return { content: [{ type: "text", text: `\u672A\u77E5\u5DE5\u5177\uFF1A${name}` }] };