@attson/atwebpilot-mcp 0.0.79 → 0.0.81

package/README.md

@@ -17,11 +17,11 @@ Claude Code：
 **不需要手填端口。** 从 Plan 33 起是配对流程：
 
 1. 会话启动时**不绑任何端口** —— 不碰网页的会话零副作用。
-2. AI 第一次调 `list_tabs` / `pairing_status` 时才绑一个空闲端口，通过 MCP URL elicitation 请宿主打开配对页，并立即返回 `pairing_required + pair_url`，不阻塞等待；不支持该能力的宿主回退到系统默认浏览器。
-3. 你在浏览器里点「允许」，扩展即接入；AI 用轻量 `pairing_status` 确认连接后再读取 tab，不重复阻塞式调用。
+2. AI 第一次调 `list_tabs` 时才绑一个空闲端口，通过 MCP URL elicitation 请宿主打开配对页；不支持该能力的宿主回退到系统默认浏览器。`list_tabs` 最多等待 45 秒。
+3. 你在浏览器里点「允许」，扩展即接入；同一次 `list_tabs` 调用直接返回 tab，AI 无需让你回复「已连接」。只有等待超时才返回 `pairing_required + pair_url`；`pairing_status` 始终是立即返回的非阻塞状态检查。
 4. 之后本机的会话都免确认（信任是安装级的）；端口能复用时连配对页都不会弹。
 
-若宿主和系统都未弹出浏览器，可直接打开返回结果中的 `pair_url`。授权成功只以扩展实际建立连接并发送 `HELLO` 为准；打开配对页本身不代表已连接。
+若宿主和系统都未弹出浏览器，可在超时结果中打开 `pair_url`。授权成功只以扩展实际建立连接并发送 `HELLO` 为准；打开配对页本身不代表已连接。
 
 多个 Codex / Claude Code 会话可以同时接入同一个浏览器，各自一条连接。可在扩展设置 →
 Coordinator 查看已接入的会话、单独断开，或撤销信任。
@@ -51,6 +51,7 @@ listen 端口的能力，所以方向只能如此。这也是配对页存在的
 - 控制面 5 个：`pairing_status / list_tabs / open_session / close_session / get_quota`
 - 发现 1 个：`browser_discoverTools` —— 已知工具时直接传 `enable: [...]`，已知分组时直接传 `enableGroups: ["export", ...]`，也可用 `profile: "core" | "full"` 切换整套工具面；只有这些都未知时才不带参数读取目录。选中的工具会加入本进程的 `tools/list`（发送 `tools/list_changed`），并始终返回完整 schema，包括已经启用的工具。
 - 同轮执行桥 1 个：`browser_call({session_id, tool, args})` —— 某些宿主虽已刷新 `tools/list`，却不会在当前模型轮次注入新工具。AI 可在 `discoverTools` 后立刻通过该桥执行，不需要让用户回复“继续”；下一轮看到原生工具后仍优先使用原生工具。
+- 批量编排 1 个：`browser_runSteps({session_id, steps, return_bindings?})` —— 在步骤和参数已经明确时，把 1–20 个 safe/caution 工具合并为一次 MCP 调用；`${binding}` 可引用前序结果。整批先做工具支持、权限和配额预检，dangerous、脚本、截图、下载与 tab 生命周期操作保持单步。
 - 执行面在浏览器连接前不进入 `tools/list`；连接确认后加载默认 **core 31 个** `browser_*`。其余 20 个由 AI 按需 `discoverTools` 拉取，用户不用配置。
 - 不暴露 `askUser`（MCP 会话没有人在侧边栏应答）和 `attachTab` / `detachTab`（目标 tab 已由 `open_session` 绑定）。
 
@@ -66,7 +67,7 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 
 | 值 | 效果 |
 |---|---|
-| `core`（默认） | 连接前仅控制面、发现工具与同轮执行桥；连接后再列出 31 个核心工具 |
+| `core`（默认） | 连接前仅控制面、发现工具、同轮执行桥与批量编排；连接后再列出 31 个核心工具 |
 | `full` | 连接前同上；连接后列出全部 51 个原生工具 |
 
 无法识别的值（包括已移除的 `parity`）按 `core` 处理，并往 stderr 打一条提示。

package/dist/index.js

@@ -953,7 +953,7 @@ var CONTROL_TOOLS = [
   },
   {
     name: "list_tabs",
-    description: "List browser tabs. If pairing is needed, opens the pair page and immediately returns pairing_required with its URL; wait for user approval, then call pairing_status instead of retrying this tool.",
+    description: "List browser tabs. On first use, opens the pairing page and waits up to 45 seconds for authorization, normally returning connected tabs in the same call. Returns pairing_required with the URL only on timeout.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false }
   },
   {
@@ -2325,7 +2325,18 @@ function locate(source, offset) {
   return { line, col };
 }
 
+// src/pairing-errors.ts
+var PairingWaitTimeoutError = class extends Error {
+  constructor(timeoutMs, pairUrl) {
+    super(
+      `\u7B49\u5F85\u6D4F\u89C8\u5668\u6388\u6743\u8D85\u65F6\uFF08${Math.ceil(timeoutMs / 1e3)} \u79D2\uFF09\u3002` + (pairUrl ? `\u8BF7\u6253\u5F00\u914D\u5BF9\u9875 ${pairUrl} \u5B8C\u6210\u6388\u6743\u540E\u91CD\u8BD5\u3002` : "")
+    );
+    this.name = "PairingWaitTimeoutError";
+  }
+};
+
 // src/handlers.ts
+var LIST_TABS_PAIRING_TIMEOUT_MS = 45e3;
 function singleWorkerId(c, pairUrl) {
   const workers = c.workers.list();
   if (workers.length === 0) {
@@ -2349,17 +2360,32 @@ async function handlePairingStatus(deps) {
   if (!pairUrl) throw new Error("PAIRING_REQUIRED: \u914D\u5BF9\u670D\u52A1\u5DF2\u542F\u52A8\uFF0C\u4F46\u914D\u5BF9\u9875\u5C1A\u4E0D\u53EF\u7528");
   return { status: "pairing_required", pair_url: pairUrl };
 }
-async function handleListTabs(deps) {
+async function handleListTabs(deps, onPairingRequired, timeoutMs = LIST_TABS_PAIRING_TIMEOUT_MS) {
   const { coordinator } = await deps.ensure();
   const workers = coordinator.workers.list();
   if (workers.length > 1) {
     throw new Error("\u68C0\u6D4B\u5230\u591A\u4E2A\u6D4F\u89C8\u5668\u8FDE\u5165\uFF1Bv1 \u4EC5\u652F\u6301\u5355 worker\uFF0C\u8BF7\u53EA\u4FDD\u7559\u4E00\u4E2A\u8FDE\u63A5");
   }
-  const worker = workers[0];
+  let worker = workers[0];
   if (!worker) {
     const pairUrl = deps.pairUrl();
     if (!pairUrl) throw new Error("PAIRING_REQUIRED: \u914D\u5BF9\u670D\u52A1\u5DF2\u542F\u52A8\uFF0C\u4F46\u914D\u5BF9\u9875\u5C1A\u4E0D\u53EF\u7528");
-    return { status: "pairing_required", pair_url: pairUrl, tabs: [] };
+    try {
+      await deps.waitForWorker(timeoutMs, onPairingRequired);
+    } catch (error) {
+      if (error instanceof PairingWaitTimeoutError) {
+        return { status: "pairing_required", pair_url: pairUrl, tabs: [] };
+      }
+      throw error;
+    }
+    const connectedWorkers = coordinator.workers.list();
+    if (connectedWorkers.length > 1) {
+      throw new Error("\u68C0\u6D4B\u5230\u591A\u4E2A\u6D4F\u89C8\u5668\u8FDE\u5165\uFF1Bv1 \u4EC5\u652F\u6301\u5355 worker\uFF0C\u8BF7\u53EA\u4FDD\u7559\u4E00\u4E2A\u8FDE\u63A5");
+    }
+    worker = connectedWorkers[0];
+    if (!worker) {
+      return { status: "pairing_required", pair_url: pairUrl, tabs: [] };
+    }
   }
   return { status: "connected", tabs: worker.available_tabs };
 }
@@ -2388,7 +2414,7 @@ var NON_BUILTIN_CAPABILITY = {
   listTabs: "tab:open",
   openTab: "tab:open"
 };
-async function handleBrowserTool(deps, gen, args) {
+async function prepareBrowserTool(deps, gen, args) {
   const { coordinator, hub } = await deps.ensure();
   const session_id = String(args.session_id);
   const session = coordinator.sessions.get(session_id);
@@ -2403,23 +2429,20 @@ async function handleBrowserTool(deps, gen, args) {
     const unsafe = highestSeverity(runStaticScan(source)) === "dangerous";
     const v = coordinator.validateCall({ session_id, kind: "runJS", unsafe });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    coordinator.recordCall(session_id, v.dangerous);
     const requestedTimeout = toolArgs.timeoutMs;
-    const jsResult = await hub.exec(session.worker_id, {
+    return {
+      coordinator,
+      hub,
       session_id,
+      worker_id: session.worker_id,
       tab_id: session.tab_id,
       step: {
         kind: "js",
         source,
         ...typeof requestedTimeout === "number" && Number.isInteger(requestedTimeout) && requestedTimeout > 0 ? { timeoutMs: requestedTimeout } : {}
-      }
-    });
-    if (!jsResult.ok) {
-      throw new Error(
-        jsResult.error ? `${jsResult.error.code}: ${jsResult.error.message}` : "EXEC failed"
-      );
-    }
-    return jsResult.return ?? null;
+      },
+      dangerous: v.dangerous
+    };
   }
   if (tool === "switchToTab" || tool === "closeTab") {
     const boundTabId = Number.parseInt(session.tab_id, 10);
@@ -2429,10 +2452,11 @@ async function handleBrowserTool(deps, gen, args) {
     toolArgs.tabId = boundTabId;
   }
   const override = NON_BUILTIN_CAPABILITY[tool];
+  let dangerous;
   if (override) {
     const v = coordinator.validateCall({ session_id, kind: "capability", capability: override });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    coordinator.recordCall(session_id, v.dangerous);
+    dangerous = v.dangerous;
   } else {
     const raw = toolArgs;
     const v = coordinator.validateCall({
@@ -2444,13 +2468,321 @@ async function handleBrowserTool(deps, gen, args) {
       recorderArmsBodies: tool === "recorderConfig" ? raw.bodies === true : void 0
     });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    coordinator.recordCall(session_id, v.dangerous);
+    dangerous = v.dangerous;
   }
-  const result = await hub.exec(session.worker_id, { session_id, tab_id: session.tab_id, step: { kind: "tool", tool, args: toolArgs } });
+  return {
+    coordinator,
+    hub,
+    session_id,
+    worker_id: session.worker_id,
+    tab_id: session.tab_id,
+    step: { kind: "tool", tool, args: toolArgs },
+    dangerous
+  };
+}
+async function handleBrowserTool(deps, gen, args) {
+  const prepared = await prepareBrowserTool(deps, gen, args);
+  prepared.coordinator.recordCall(prepared.session_id, prepared.dangerous);
+  const result = await prepared.hub.exec(prepared.worker_id, {
+    session_id: prepared.session_id,
+    tab_id: prepared.tab_id,
+    step: prepared.step
+  });
   if (!result.ok) throw new Error(result.error ? `${result.error.code}: ${result.error.message}` : "EXEC failed");
   return result.return ?? null;
 }
 
+// src/browser-run-steps.ts
+var BROWSER_RUN_STEPS_TOOL = {
+  name: "browser_runSteps",
+  description: "Run 1-20 enabled safe/caution browser tools sequentially in one MCP call. Supports ${binding} references and returns only the final result plus requested bindings.",
+  inputSchema: {
+    type: "object",
+    required: ["session_id", "steps"],
+    properties: {
+      session_id: { type: "string", description: "Session id from open_session" },
+      steps: {
+        type: "array",
+        minItems: 1,
+        maxItems: 20,
+        items: {
+          type: "object",
+          required: ["tool", "args"],
+          properties: {
+            tool: {
+              type: "string",
+              description: "Enabled browser tool name; browser_ prefix is optional"
+            },
+            args: {
+              type: "object",
+              description: "Tool arguments excluding session_id; may reference earlier ${bindings}",
+              additionalProperties: true
+            },
+            bind_result_to: {
+              type: "string",
+              pattern: "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      return_bindings: {
+        type: "array",
+        items: {
+          type: "string",
+          pattern: "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+        },
+        uniqueItems: true
+      }
+    },
+    additionalProperties: false
+  }
+};
+var BINDING_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+var BLOCKED_BATCH_TOOLS = /* @__PURE__ */ new Set([
+  "browser_downloadImage",
+  "browser_downloadSpreadsheet",
+  "browser_openTab",
+  "browser_closeTab",
+  "browser_switchToTab"
+]);
+var CAPABILITY_SENSITIVE_FIELDS = /* @__PURE__ */ new Map([
+  ["browser_httpRequest", ["withCredentials"]],
+  ["browser_drop", ["files"]],
+  ["browser_recorderConfig", ["bodies"]]
+]);
+function runStepsPreflightError(message) {
+  return {
+    ok: false,
+    phase: "preflight",
+    completed: 0,
+    error: { message },
+    bindings: {}
+  };
+}
+async function handleBrowserRunSteps(deps, args, context) {
+  const sessionId = typeof args.session_id === "string" ? args.session_id : "";
+  if (!sessionId) throw new Error("InvalidArgs: browser_runSteps requires session_id");
+  if (!Array.isArray(args.steps) || args.steps.length < 1 || args.steps.length > 20) {
+    throw new Error("InvalidArgs: browser_runSteps requires 1-20 steps");
+  }
+  const steps = args.steps.map(parseStep);
+  const requested = parseReturnBindings(args.return_bindings);
+  const bindings = /* @__PURE__ */ Object.create(null);
+  let result = null;
+  const bindingIssue = validateBindingPlan(steps, requested);
+  if (bindingIssue) {
+    return preflightFailure(steps, bindingIssue.index, bindingIssue.message);
+  }
+  const { coordinator } = await deps.ensure();
+  const quota = coordinator.quotaFor(sessionId);
+  if (!quota) throw new Error(`session ${sessionId} not found`);
+  const remainingSteps = quota.max_steps - quota.steps_used;
+  if (steps.length > remainingSteps) {
+    const failedIndex = Math.max(0, remainingSteps);
+    return preflightFailure(
+      steps,
+      failedIndex,
+      `Session has only ${remainingSteps} steps remaining; batch requires ${steps.length}`
+    );
+  }
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const name = browserToolName(step.tool);
+    const generated = context.tools.get(name);
+    try {
+      assertAvailable(name, step.tool, generated, context);
+      if (generated.stepKind === "js" || generated.resultKind === "image" || BLOCKED_BATCH_TOOLS.has(name)) {
+        throw new Error(`Tool ${name} is not allowed in browser_runSteps`);
+      }
+      for (const field of CAPABILITY_SENSITIVE_FIELDS.get(name) ?? []) {
+        if (bindingReferences(step.args[field]).length > 0) {
+          throw new Error(
+            `Capability-sensitive field ${field} cannot reference bindings in browser_runSteps`
+          );
+        }
+      }
+      const prepared = await prepareBrowserTool(deps, generated, {
+        ...step.args,
+        session_id: sessionId
+      });
+      if (prepared.dangerous) {
+        throw new Error("Dangerous tool is not allowed in browser_runSteps");
+      }
+    } catch (error) {
+      return {
+        ok: false,
+        phase: "preflight",
+        completed: 0,
+        failed_step: { index, tool: name },
+        error: { message: error instanceof Error ? error.message : String(error) },
+        bindings: {}
+      };
+    }
+  }
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    const name = browserToolName(step.tool);
+    const generated = context.tools.get(name);
+    assertAvailable(name, step.tool, generated, context);
+    const resolvedArgs = resolveBindings(step.args, bindings);
+    try {
+      result = await handleBrowserTool(deps, generated, { ...resolvedArgs, session_id: sessionId });
+    } catch (error) {
+      return {
+        ok: false,
+        phase: "execution",
+        completed: index,
+        failed_step: { index, tool: name },
+        error: { message: error instanceof Error ? error.message : String(error) },
+        bindings: selectBindings(requested, bindings, false)
+      };
+    }
+    if (step.bind_result_to) bindings[step.bind_result_to] = result;
+  }
+  return {
+    ok: true,
+    completed: steps.length,
+    result,
+    bindings: selectBindings(requested, bindings, true)
+  };
+}
+function preflightFailure(steps, index, message) {
+  const boundedIndex = Math.min(Math.max(index, 0), steps.length - 1);
+  return {
+    ok: false,
+    phase: "preflight",
+    completed: 0,
+    failed_step: {
+      index: boundedIndex,
+      tool: browserToolName(steps[boundedIndex].tool)
+    },
+    error: { message },
+    bindings: {}
+  };
+}
+function parseReturnBindings(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.some((name) => typeof name !== "string")) {
+    throw new Error("InvalidArgs: return_bindings must be an array of binding names");
+  }
+  return value;
+}
+function validateBindingPlan(steps, requested) {
+  const declared = /* @__PURE__ */ new Set();
+  for (let index = 0; index < steps.length; index++) {
+    const step = steps[index];
+    for (const name of bindingReferences(step.args)) {
+      if (!declared.has(name)) {
+        return {
+          index,
+          message: `InvalidArgs: binding ${name} must be declared by an earlier step`
+        };
+      }
+    }
+    if (step.bind_result_to) {
+      if (!BINDING_NAME.test(step.bind_result_to)) {
+        return { index, message: `InvalidArgs: invalid binding name ${step.bind_result_to}` };
+      }
+      if (declared.has(step.bind_result_to)) {
+        return { index, message: `InvalidArgs: duplicate binding ${step.bind_result_to}` };
+      }
+      declared.add(step.bind_result_to);
+    }
+  }
+  const seenRequested = /* @__PURE__ */ new Set();
+  for (const name of requested) {
+    if (!BINDING_NAME.test(name)) {
+      return { index: 0, message: `InvalidArgs: invalid return binding ${name}` };
+    }
+    if (seenRequested.has(name)) {
+      return { index: 0, message: `InvalidArgs: duplicate return binding ${name}` };
+    }
+    if (!declared.has(name)) {
+      return { index: 0, message: `InvalidArgs: unknown return binding ${name}` };
+    }
+    seenRequested.add(name);
+  }
+  return null;
+}
+function bindingReferences(value) {
+  if (typeof value === "string") {
+    return [...value.matchAll(/\$\{([^}]+)\}/g)].map((match) => match[1]);
+  }
+  if (Array.isArray(value)) return value.flatMap(bindingReferences);
+  if (value && typeof value === "object") {
+    return Object.values(value).flatMap(bindingReferences);
+  }
+  return [];
+}
+function assertAvailable(name, rawName, generated, context) {
+  if (!generated) throw new Error(`Unknown browser tool: ${rawName}`);
+  if (!context.advertised.has(name)) {
+    throw new Error(`${name} is not enabled; call browser_discoverTools first`);
+  }
+  if (context.supported && !generated.builtinTools.every((tool) => context.supported.has(tool))) {
+    throw new Error(`${name} is not supported by the connected browser extension`);
+  }
+}
+function parseStep(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("InvalidArgs: each browser_runSteps step must be an object");
+  }
+  const raw = value;
+  if (typeof raw.tool !== "string" || raw.tool.trim() === "") {
+    throw new Error("InvalidArgs: each browser_runSteps step requires tool");
+  }
+  if (!raw.args || typeof raw.args !== "object" || Array.isArray(raw.args)) {
+    throw new Error("InvalidArgs: each browser_runSteps step requires object args");
+  }
+  if (raw.bind_result_to !== void 0 && typeof raw.bind_result_to !== "string") {
+    throw new Error("InvalidArgs: bind_result_to must be a binding name");
+  }
+  return {
+    tool: raw.tool,
+    args: raw.args,
+    ...typeof raw.bind_result_to === "string" ? { bind_result_to: raw.bind_result_to } : {}
+  };
+}
+function browserToolName(raw) {
+  const name = raw.trim();
+  return name.startsWith("browser_") ? name : `browser_${name}`;
+}
+function resolveBindings(value, bindings) {
+  if (typeof value === "string") {
+    const exact = value.match(/^\$\{([^}]+)\}$/);
+    if (exact) return requireBinding(exact[1], bindings);
+    return value.replace(/\$\{([^}]+)\}/g, (_match, name) => {
+      const bound = requireBinding(name, bindings);
+      return typeof bound === "string" ? bound : JSON.stringify(bound);
+    });
+  }
+  if (Array.isArray(value)) return value.map((item) => resolveBindings(item, bindings));
+  if (value && typeof value === "object") {
+    const resolved = {};
+    for (const [key, item] of Object.entries(value)) {
+      resolved[key] = resolveBindings(item, bindings);
+    }
+    return resolved;
+  }
+  return value;
+}
+function requireBinding(name, bindings) {
+  if (!(name in bindings)) throw new Error(`InvalidArgs: binding ${name} is not available`);
+  return bindings[name];
+}
+function selectBindings(requested, bindings, requireAll) {
+  const selected = {};
+  for (const name of requested) {
+    if (!(name in bindings)) {
+      if (requireAll) throw new Error(`InvalidArgs: unknown return binding ${name}`);
+      continue;
+    }
+    selected[name] = bindings[name];
+  }
+  return selected;
+}
+
 // src/skill-bundle.ts
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
@@ -2460,16 +2792,17 @@ var SKILL_DESCRIPTION = "Strategy + scenarios + safety rails for driving the AtW
 var TOPICS = {
   quickstart: `# AtWebPilot quickstart
 
-1. Call list_tabs once. If it returns pairing_required, show pair_url and wait for the user to approve.
-2. After approval, call pairing_status. Do not retry list_tabs while status is unchanged.
-3. Call list_tabs when connected, choose a tab, then open_session with its tab_id.
+1. Call list_tabs once. On first use it opens the pairing page and waits for authorization, then normally returns connected tabs in the same call.
+2. If list_tabs times out and returns pairing_required, show pair_url and wait for browser approval. Use pairing_status for a later non-blocking status check; do not ask the user to reply just to continue.
+3. Choose a returned tab, then call open_session with its tab_id.
 4. For interaction use browser_getPageInfo then browser_takeSnapshot; for broad reading use browser_createPageIndex.
-5. Prefer purpose-built tools and verified results. Use browser_discoverTools only for capabilities outside the connected core surface. Its response always includes the selected schemas. If a newly enabled native tool is not visible in the current turn, call it immediately with browser_call; do not ask the user to send "continue".
-6. Close the session when finished.
+5. When 2-20 safe/caution steps and their arguments are already known, use browser_runSteps to execute them in one MCP call. Keep dangerous actions and steps needing intermediate inspection as separate calls.
+6. Prefer purpose-built tools and verified results. Use browser_discoverTools only for capabilities outside the connected core surface. Its response always includes the selected schemas. If a newly enabled native tool is not visible in the current turn, call it immediately with browser_call; do not ask the user to send "continue".
+7. Close the session when finished.
 `,
   pairing: `# AtWebPilot pairing
 
-list_tabs and pairing_status never wait for browser authorization. A pairing_required result includes pair_url. Show that URL once and wait for the user to approve in the browser. Then call pairing_status; only call list_tabs after it reports connected. Never poll list_tabs or inspect the pair-page HTML.
+list_tabs opens the pairing page when needed and waits up to 45 seconds for the extension's HELLO, so successful authorization normally returns connected tabs in the same call. pairing_status remains immediate and non-blocking. A pairing_required result from list_tabs means the bounded wait expired; show pair_url once and use pairing_status for a later check. Never ask the user to reply merely to continue, poll list_tabs, or inspect the pair-page HTML.
 `,
   reading: `# AtWebPilot reading
 
@@ -2511,9 +2844,11 @@ function readSkillBundle(rawTopic = "quickstart") {
   }
   if (cached == null) {
     try {
-      cached = readFileSync(locateSkillFile(), "utf-8");
+      cached = `${TOPICS.quickstart}
+${readFileSync(locateSkillFile(), "utf-8")}`;
     } catch {
-      cached = `# ${SKILL_NAME}
+      cached = `${TOPICS.quickstart}
+# ${SKILL_NAME}
 
 ${SKILL_DESCRIPTION}
 
@@ -2543,7 +2878,7 @@ var SKILL_TOOL = {
 // package.json
 var package_default = {
   name: "@attson/atwebpilot-mcp",
-  version: "0.0.79",
+  version: "0.0.81",
   license: "Apache-2.0",
   description: "MCP server for the atwebpilot browser extension - let Codex or Claude Code drive your browser.",
   homepage: "https://github.com/attson/atwebpilot#readme",
@@ -2698,6 +3033,7 @@ function buildToolList(deps, state = DEFAULT_STATE) {
     ...CONTROL_TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
     { name: DISCOVER_TOOL.name, description: DISCOVER_TOOL.description, inputSchema: DISCOVER_TOOL.inputSchema },
     { name: BROWSER_CALL_TOOL.name, description: BROWSER_CALL_TOOL.description, inputSchema: BROWSER_CALL_TOOL.inputSchema },
+    { name: BROWSER_RUN_STEPS_TOOL.name, description: BROWSER_RUN_STEPS_TOOL.description, inputSchema: BROWSER_RUN_STEPS_TOOL.inputSchema },
     ...browser.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
   ];
 }
@@ -2737,6 +3073,24 @@ async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChang
     if (name === BROWSER_CALL_TOOL.name) {
       return handleBrowserCall(deps, args, state);
     }
+    if (name === BROWSER_RUN_STEPS_TOOL.name) {
+      let result;
+      try {
+        result = await handleBrowserRunSteps(deps, args, {
+          tools: BROWSER_BY_NAME,
+          advertised: state.advertised,
+          supported: workerToolSupport(deps)
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("PAIRING_REQUIRED")) {
+          const pairUrl = deps.pairUrl();
+          if (pairUrl) onPairingRequired?.(pairUrl);
+        }
+        result = runStepsPreflightError(message);
+      }
+      return result.ok ? ok(result) : { ...ok(result), isError: true };
+    }
     if (name === "pairing_status") {
       const result = await handlePairingStatus(deps);
       if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
@@ -2744,9 +3098,8 @@ async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChang
       return ok(result);
     }
     if (name === "list_tabs") {
-      const result = await handleListTabs(deps);
+      const result = await handleListTabs(deps, onPairingRequired);
       if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
-      else onPairingRequired?.(result.pair_url);
       return ok(result);
     }
     if (name === "open_session") {
@@ -3440,6 +3793,14 @@ function createHubEnsurer(d) {
       );
     }
     if (pairUrlValue) await onWaiting?.(pairUrlValue);
+    const connectedAfterPresentation = connectedWorkerId(coordinator);
+    if (connectedAfterPresentation) return connectedAfterPresentation;
+    if (pendingDenial) {
+      pendingDenial = false;
+      throw new Error(
+        "\u7528\u6237\u62D2\u7EDD\u4E86\u6D4F\u89C8\u5668\u914D\u5BF9\u6388\u6743\u3002" + (pairUrlValue ? `\u914D\u5BF9\u9875\uFF1A${pairUrlValue}` : "")
+      );
+    }
     if (workerWait) return workerWait.promise;
     let resolve;
     let reject;
@@ -3449,9 +3810,7 @@ function createHubEnsurer(d) {
     });
     const timer = setTimeout(() => {
       finishWorkerWait({
-        error: new Error(
-          `\u7B49\u5F85\u6D4F\u89C8\u5668\u6388\u6743\u8D85\u65F6\uFF08${Math.ceil(timeoutMs / 1e3)} \u79D2\uFF09\u3002` + (pairUrlValue ? `\u8BF7\u6253\u5F00\u914D\u5BF9\u9875 ${pairUrlValue} \u5B8C\u6210\u6388\u6743\u540E\u91CD\u8BD5\u3002` : "")
-        )
+        error: new PairingWaitTimeoutError(timeoutMs, pairUrlValue)
       });
     }, timeoutMs);
     timer.unref?.();

package/dist/skill/SKILL.md

@@ -13,8 +13,9 @@ When this skill is loaded, you can drive any open tab through these tools
 ### Control plane
 
 - `pairing_status` — start/check pairing without waiting. When it reports
-  `pairing_required`, show `pair_url` once and wait for browser approval.
-- `list_tabs` — enumerate Chrome tabs you can operate on. Entries carry `busy`
+  `pairing_required`, show `pair_url` once; use it only as a later status check.
+- `list_tabs` — on first use, open the pairing page and wait up to 45 seconds
+  for browser authorization, normally returning tabs from the same call. Entries carry `busy`
   and `busy_label` when **another** Claude Code session is already driving that
   tab, and `mine` for tabs you hold. This is advisory — nothing blocks you — but
   contending for a tab another agent is typing into is rarely what you want.
@@ -87,7 +88,7 @@ compatibility path; use the native tool once the host exposes it.
 
 ## Recommended flow
 
-1. **先建立连接**：调一次 `list_tabs`；若返回 `pairing_required`，展示 `pair_url` 并等待用户批准。批准后只调 `pairing_status`，它报告 `connected` 后再调 `list_tabs`，不要轮询 `list_tabs`。
+1. **先建立连接**：调一次 `list_tabs`；首次配对时它会打开授权页并等待最多 45 秒，授权成功后同一次调用直接返回 tab，不要让用户回复「已连接」。只有超时才会返回 `pairing_required`；此时展示 `pair_url`，稍后用非阻塞的 `pairing_status` 检查，不要轮询 `list_tabs`。
 2. **探查先于操作**：每次进入新页面，先 `getPageInfo` 确认位置，再 `takeSnapshot`（要点击/填表）或 `createPageIndex`（要读内容/抽字段）；`snapshotDOM` / `querySelector` 属于 legacy-dom 组，只在需要分析整页结构时通过 `browser_discoverTools` 启用。
 3. **最少充分验证**：危险或不可逆操作保持单步；多个独立字段用 `fillForm`。工具已返回 `verified` 或明确后置状态时，不要再用 `runJS` 重复验证。
 4. **dangerous 工具会被人工审核**：调用前用 `extractText` 给用户看上下文，让审批更顺。
@@ -260,12 +261,13 @@ not the whole history.
 Several Claude Code sessions can be attached to the same browser at once, each
 through its own connection. Two consequences worth knowing:
 
-- **Pairing is non-blocking.** `list_tabs` lazily binds the port and opens a
-  confirmation page, then immediately returns `pairing_required` with
-  `pair_url`. Ask the user to click Allow. After they confirm, call
-  `pairing_status`; call `list_tabs` again only when it reports `connected`.
-  Never inspect the pair-page HTML or retry `list_tabs` while state is unchanged.
-  Once approved, later sessions on that machine connect silently.
+- **Pairing continues in the same call.** `list_tabs` lazily binds the port,
+  opens a confirmation page, and waits up to 45 seconds for the extension's
+  `HELLO`. Successful approval returns connected tabs directly; do not ask the
+  user to reply just to continue. On timeout it returns `pairing_required` with
+  `pair_url`; use non-blocking `pairing_status` for a later check. Never inspect
+  the pair-page HTML or poll `list_tabs`. Once approved, later sessions on that
+  machine connect silently.
 - **Pick a free tab.** `list_tabs` marks tabs held by other sessions as `busy`.
   Prefer an unowned tab, or open your own — two agents typing into one form
   produces failures that look like your own tool calls not working.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attson/atwebpilot-mcp",
-  "version": "0.0.79",
+  "version": "0.0.81",
   "license": "Apache-2.0",
   "description": "MCP server for the atwebpilot browser extension - let Codex or Claude Code drive your browser.",
   "homepage": "https://github.com/attson/atwebpilot#readme",