@attson/atwebpilot-mcp 0.0.79 → 0.0.80

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 查看已接入的会话、单独断开，或撤销信任。

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 };
 }
@@ -2460,16 +2486,16 @@ 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.
 `,
   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
 
@@ -2543,7 +2569,7 @@ var SKILL_TOOL = {
 // package.json
 var package_default = {
   name: "@attson/atwebpilot-mcp",
-  version: "0.0.79",
+  version: "0.0.80",
   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",
@@ -2744,9 +2770,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 +3465,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 +3482,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.80",
   "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",