@attson/atwebpilot-mcp 0.0.78 → 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.78",
+  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",
@@ -2595,39 +2621,58 @@ var MCP_VERSION = package_default.version;
 
 // src/pairing-presenter.ts
 import { randomUUID } from "crypto";
+function isCodexClient(server) {
+  return server.getClientVersion?.()?.name.toLowerCase().includes("codex") ?? false;
+}
 function createPairingPresenter(server, fallbackOpenUrl) {
   let presentedUrl = null;
   const runFallback = async (url) => {
-    if (!fallbackOpenUrl) return;
+    if (!fallbackOpenUrl) return false;
     try {
       await fallbackOpenUrl(url);
+      return true;
     } catch (error) {
-      presentedUrl = null;
       console.error(
         `[atwebpilot-mcp] failed to open pairing page ${url}:`,
         error instanceof Error ? error.message : String(error)
       );
+      return false;
     }
   };
-  return (url) => {
-    if (presentedUrl === url) return;
-    presentedUrl = url;
-    if (!server.getClientCapabilities()?.elicitation?.url) {
-      void runFallback(url);
-      return;
-    }
+  const requestHostPresentation = (url, fallbackOnFailure) => {
     void server.elicitInput({
       mode: "url",
       message: "Open AtWebPilot in the browser to approve this pairing request.",
       url,
       elicitationId: `atwebpilot-pairing-${randomUUID()}`
-    }).catch((error) => {
+    }).catch(async (error) => {
       if (!server.transport) return;
       console.error(
-        "[atwebpilot-mcp] URL elicitation failed; falling back to the system browser:",
+        fallbackOnFailure ? "[atwebpilot-mcp] URL elicitation failed; falling back to the system browser:" : "[atwebpilot-mcp] URL elicitation failed:",
         error instanceof Error ? error.message : String(error)
       );
-      return runFallback(url);
+      if (fallbackOnFailure && await runFallback(url)) return;
+      presentedUrl = null;
+    });
+  };
+  return (url) => {
+    if (presentedUrl === url) return;
+    presentedUrl = url;
+    const supportsUrlElicitation = Boolean(server.getClientCapabilities()?.elicitation?.url);
+    if (isCodexClient(server)) {
+      void runFallback(url).then((opened) => {
+        if (opened || !server.transport) return;
+        if (supportsUrlElicitation) requestHostPresentation(url, false);
+        else presentedUrl = null;
+      });
+      return;
+    }
+    if (supportsUrlElicitation) {
+      requestHostPresentation(url, true);
+      return;
+    }
+    void runFallback(url).then((opened) => {
+      if (!opened) presentedUrl = null;
     });
   };
 }
@@ -2725,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") {
@@ -2800,6 +2844,9 @@ function createMcpServer(deps, state = DEFAULT_STATE, options = {}) {
   return server;
 }
 
+// src/ensure-hub.ts
+import { readFile } from "fs/promises";
+
 // src/loopback-ws-hub.ts
 import { WebSocketServer, WebSocket } from "ws";
 import {
@@ -3418,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;
@@ -3427,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?.();
@@ -3444,6 +3497,57 @@ function createHubEnsurer(d) {
     bound: () => bundle != null
   };
 }
+var DESKTOP_ENV_KEYS = [
+  "DISPLAY",
+  "WAYLAND_DISPLAY",
+  "XDG_RUNTIME_DIR",
+  "DBUS_SESSION_BUS_ADDRESS",
+  "XAUTHORITY"
+];
+function processId(field, status) {
+  const match = new RegExp(`^${field}:\\s+(\\d+)`, "m").exec(status);
+  if (!match) return null;
+  const value = Number(match[1]);
+  return Number.isSafeInteger(value) ? value : null;
+}
+function copyDesktopVariables(target, serialized) {
+  for (const entry of serialized.split("\0")) {
+    const separator = entry.indexOf("=");
+    if (separator <= 0) continue;
+    const key = entry.slice(0, separator);
+    if (!DESKTOP_ENV_KEYS.includes(key) || target[key]) continue;
+    const value = entry.slice(separator + 1);
+    if (value) target[key] = value;
+  }
+}
+async function resolveDesktopOpenEnvironment(options = {}) {
+  const environment = { ...options.baseEnv ?? process.env };
+  if ((options.platform ?? process.platform) !== "linux") return environment;
+  const expectedUid = options.uid ?? process.getuid?.();
+  const readTextFile = options.readTextFile ?? ((path) => readFile(path, "utf8"));
+  const seen = /* @__PURE__ */ new Set();
+  let pid = options.parentPid ?? process.ppid;
+  const maxDepth = options.maxDepth ?? 12;
+  for (let depth = 0; depth < maxDepth && pid > 1 && !seen.has(pid); depth += 1) {
+    seen.add(pid);
+    let status;
+    try {
+      status = await readTextFile(`/proc/${pid}/status`);
+    } catch {
+      break;
+    }
+    const ownerUid = processId("Uid", status);
+    if (expectedUid !== void 0 && ownerUid !== expectedUid) break;
+    try {
+      copyDesktopVariables(environment, await readTextFile(`/proc/${pid}/environ`));
+    } catch {
+    }
+    const parentPid = processId("PPid", status);
+    if (parentPid === null || parentPid === pid) break;
+    pid = parentPid;
+  }
+  return environment;
+}
 function openCommands(url) {
   if (process.platform === "darwin") return [{ command: "open", args: [url] }];
   if (process.platform === "win32") {
@@ -3457,10 +3561,14 @@ function openCommands(url) {
     { command: "gio", args: ["open", url] }
   ];
 }
-async function runOpenCommand({ command, args }) {
+async function runOpenCommand({ command, args }, environment) {
   const { spawn } = await import("child_process");
   await new Promise((resolve, reject) => {
-    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    const child = spawn(command, args, {
+      stdio: "ignore",
+      detached: true,
+      env: environment
+    });
     let settled = false;
     const finish = (error) => {
       if (settled) return;
@@ -3483,9 +3591,10 @@ async function runOpenCommand({ command, args }) {
 }
 async function defaultOpenUrl(url) {
   const errors = [];
+  const environment = await resolveDesktopOpenEnvironment();
   for (const candidate of openCommands(url)) {
     try {
-      await runOpenCommand(candidate);
+      await runOpenCommand(candidate, environment);
       return;
     } catch (error) {
       errors.push(error instanceof Error ? error.message : String(error));

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.78",
+  "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",