@attson/atwebpilot-mcp 0.0.56 → 0.0.57

package/README.md

@@ -6,14 +6,22 @@
 
     claude mcp add atwebpilot --scope user -- npx -y @attson/atwebpilot-mcp
 
-可选环境变量：
+然后[下载 release zip](https://github.com/attson/atwebpilot/releases/latest) 加载已解压扩展。
+
+**不需要手填端口。** 从 Plan 33 起是配对流程：
+
+1. 会话启动时**不绑任何端口** —— 不碰网页的会话零副作用。
+2. AI 第一次调 `list_tabs` / `browser_*` 时才绑一个空闲端口，并自动打开配对页。
+3. 你在浏览器里点「允许」，扩展即接入，重试那次调用即可。
+4. 之后本机的会话都免确认（信任是安装级的）；端口能复用时连配对页都不会弹。
+
+多个 Claude Code 会话可以同时接入同一个浏览器，各自一条连接。可在扩展设置 →
+Coordinator 查看已接入的会话、单独断开，或撤销信任。
 
-- `ATWEBPILOT_WS_PORT`（默认 8787）：本地 ws 监听端口
-- `ATWEBPILOT_WS_TOKEN`（可选）：扩展连接时要求 `bearer.<token>` 子协议
+可选环境变量：
 
-然后[下载 release zip](https://github.com/attson/atwebpilot/releases/latest) 加载已解压扩展，
-在扩展设置 → Coordinator 子页填 `ws://127.0.0.1:8787/worker` → 连接。新会话 Claude 调
-`list_tabs` 即可看到当前标签页。
+- `ATWEBPILOT_WS_PORT`：固定端口（默认是自动选一个空闲端口并复用上次的）
+- `ATWEBPILOT_WS_TOKEN`：要求扩展带 `bearer.<token>` 子协议
 
 ## 给开发者：本地 monorepo
 
@@ -21,6 +29,15 @@
 
 环境变量同上，路径用 `tsx src/index.ts` 直跑（包内 `start` script 已封）。
 
+## 多会话
+
+每个 MCP server 进程是 WS **服务端**，扩展是**客户端** —— MV3 service worker 没有
+listen 端口的能力，所以方向只能如此。这也是配对页存在的原因：服务端没法主动找到浏览器，
+只能由它把自己的端口**告知**扩展。
+
+扩展侧维护一个连接池，每个已配对会话一条连接。`list_tabs` 会告诉你哪些 tab 正被**别的**
+会话占用（`busy` / `busy_label`）——只是提示，不拦截；AI 看到占用通常直接 `openTab` 开一个新的就行。
+
 ## 工具面
 
 - 控制面 4 个：`list_tabs / open_session / close_session / get_quota`

package/dist/index.js

@@ -217,6 +217,14 @@ var StepSchema = z4.object({
   tool: z4.string(),
   args: z4.unknown()
 });
+var DerivedTabFields = {
+  /** true when the receiving connection owns this tab */
+  mine: z4.boolean().optional(),
+  /** true when some *other* connection owns it */
+  busy: z4.boolean().optional(),
+  /** the owning session's label, present only when busy */
+  busy_label: z4.string().optional()
+};
 var HelloSchema = z4.object({
   ...EnvelopeFields,
   type: z4.literal("HELLO"),
@@ -239,7 +247,8 @@ var HelloSchema = z4.object({
     z4.object({
       tab_id: z4.string(),
       url: z4.string(),
-      title: z4.string().optional()
+      title: z4.string().optional(),
+      ...DerivedTabFields
     })
   ),
   saved_tools: z4.array(
@@ -390,6 +399,24 @@ var SidepanelStateReplySchema = z4.object({
     lastSystemNote: z4.string().optional()
   }).optional()
 });
+var SessionOpenedSchema = z4.object({
+  ...EnvelopeFields,
+  type: z4.literal("SESSION_OPENED"),
+  session_id: z4.string(),
+  tab_id: z4.string()
+});
+var TabsUpdateSchema = z4.object({
+  ...EnvelopeFields,
+  type: z4.literal("TABS_UPDATE"),
+  tabs: z4.array(
+    z4.object({
+      tab_id: z4.string(),
+      url: z4.string(),
+      title: z4.string().optional(),
+      ...DerivedTabFields
+    })
+  )
+});
 var ClientToServerSchema = z4.discriminatedUnion("type", [
   HelloSchema,
   PingSchema,
@@ -399,7 +426,8 @@ var ClientToServerSchema = z4.discriminatedUnion("type", [
   SessionEventSchema,
   StateSnapshotSchema,
   ChatEventSchema,
-  SidepanelStateReplySchema
+  SidepanelStateReplySchema,
+  TabsUpdateSchema
 ]);
 var ServerToClientSchema = z4.discriminatedUnion("type", [
   WelcomeSchema,
@@ -409,7 +437,8 @@ var ServerToClientSchema = z4.discriminatedUnion("type", [
   CloseSessionSchema,
   StartChatSessionSchema,
   AbortSessionSchema,
-  ReadSidepanelStateSchema
+  ReadSidepanelStateSchema,
+  SessionOpenedSchema
 ]);
 var ProtocolMessageSchema = z4.union([ClientToServerSchema, ServerToClientSchema]);
 
@@ -818,8 +847,12 @@ var Coordinator = class {
   catalog;
   dispatcher;
   hub;
+  clock;
+  idGen;
   constructor(deps) {
     this.hub = deps.hub;
+    this.clock = deps.clock;
+    this.idGen = deps.idGen;
     this.sessions = new SessionManager(deps.clock, deps.idGen);
     this.workers = new WorkerRegistry(deps.clock);
     this.catalog = new Catalog(this.workers);
@@ -841,7 +874,17 @@ var Coordinator = class {
   }
   // === Session lifecycle ===
   openSession(input) {
-    return this.sessions.open(input);
+    const session = this.sessions.open(input);
+    void this.hub.send(session.worker_id, {
+      type: "SESSION_OPENED",
+      nonce: this.idGen.next("nonce"),
+      ts: this.clock.now(),
+      protocol_version: PROTOCOL_VERSION,
+      session_id: session.id,
+      tab_id: session.tab_id
+    }).catch(() => {
+    });
+    return session;
   }
   closeSession(id) {
     this.sessions.close(id);
@@ -873,232 +916,6 @@ var Coordinator = class {
   }
 };
 
-// src/loopback-ws-hub.ts
-import { WebSocketServer, WebSocket } from "ws";
-var HEARTBEAT_INTERVAL_MS = 2e4;
-var DEFAULT_KEEPALIVE_INTERVAL_MS = 15e3;
-var LoopbackWSHub = class {
-  constructor(opts) {
-    this.opts = opts;
-    this.execTimeoutMs = opts.execTimeoutMs ?? 3e4;
-    this.keepaliveIntervalMs = opts.keepaliveIntervalMs ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
-    this.wss = new WebSocketServer({
-      port: opts.port,
-      path: "/worker",
-      handleProtocols: (protocols) => [...protocols][0] ?? false
-    });
-    this.wss.on("connection", (socket, req) => this.onConnection(socket, req));
-  }
-  opts;
-  wss;
-  byWorker = /* @__PURE__ */ new Map();
-  workerOf = /* @__PURE__ */ new Map();
-  pending = /* @__PURE__ */ new Map();
-  msgHandlers = [];
-  disconnectHandlers = [];
-  execTimeoutMs;
-  keepaliveIntervalMs;
-  keepaliveTimers = /* @__PURE__ */ new Map();
-  ready() {
-    return new Promise((resolve) => {
-      const addr = this.wss.address();
-      if (addr) return resolve(addr.port);
-      this.wss.on(
-        "listening",
-        () => resolve(this.wss.address().port)
-      );
-    });
-  }
-  close() {
-    for (const p of this.pending.values()) {
-      clearTimeout(p.timer);
-      p.reject(new Error("hub closing"));
-    }
-    this.pending.clear();
-    for (const timer of this.keepaliveTimers.values()) clearInterval(timer);
-    this.keepaliveTimers.clear();
-    for (const socket of this.wss.clients) {
-      socket.terminate();
-    }
-    return new Promise((resolve) => this.wss.close(() => resolve()));
-  }
-  tokenOk(req) {
-    if (!this.opts.token) return true;
-    const offered = String(req.headers["sec-websocket-protocol"] ?? "").split(",").map((s) => s.trim());
-    return offered.includes(`bearer.${this.opts.token}`);
-  }
-  onConnection(socket, req) {
-    if (!this.tokenOk(req)) {
-      socket.close(4401, "bad token");
-      return;
-    }
-    socket.on("message", (raw) => this.onMessageRaw(socket, raw.toString()));
-    socket.on("close", () => this.onSocketClose(socket));
-    socket.on("error", () => {
-    });
-  }
-  onMessageRaw(socket, raw) {
-    let parsed;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      return;
-    }
-    const r = ClientToServerSchema.safeParse(parsed);
-    if (!r.success) return;
-    const msg = r.data;
-    if (msg.type === "HELLO") {
-      const existingSocket = this.byWorker.get(msg.worker_id);
-      if (existingSocket && existingSocket !== socket) {
-        this.workerOf.delete(existingSocket);
-        for (const [req_id, p] of [...this.pending]) {
-          if (p.worker_id === msg.worker_id) {
-            clearTimeout(p.timer);
-            this.pending.delete(req_id);
-            p.reject(new Error(`worker ${msg.worker_id} reconnected, exec cancelled`));
-          }
-        }
-        existingSocket.terminate();
-      }
-      this.byWorker.set(msg.worker_id, socket);
-      this.workerOf.set(socket, msg.worker_id);
-      this.rawSend(socket, {
-        type: "WELCOME",
-        nonce: this.opts.idGen.next("nonce"),
-        ts: this.opts.clock.now(),
-        protocol_version: PROTOCOL_VERSION,
-        server_time: this.opts.clock.now(),
-        heartbeat_interval_ms: HEARTBEAT_INTERVAL_MS
-      });
-      this.startKeepalive(socket);
-      for (const h of this.msgHandlers) h(msg.worker_id, msg);
-      return;
-    }
-    if (msg.type === "RESULT") {
-      const p = this.pending.get(msg.req_id);
-      if (p) {
-        clearTimeout(p.timer);
-        this.pending.delete(msg.req_id);
-        p.resolve(msg);
-      }
-      return;
-    }
-    if (msg.type === "PING") {
-      this.rawSend(socket, {
-        type: "PONG",
-        nonce: this.opts.idGen.next("nonce"),
-        ts: this.opts.clock.now(),
-        protocol_version: PROTOCOL_VERSION,
-        echo_nonce: msg.nonce
-      });
-    }
-    const wid = this.workerOf.get(socket);
-    if (wid) {
-      for (const h of this.msgHandlers) h(wid, msg);
-    }
-  }
-  onSocketClose(socket) {
-    this.stopKeepalive(socket);
-    const wid = this.workerOf.get(socket);
-    if (!wid) return;
-    this.workerOf.delete(socket);
-    this.byWorker.delete(wid);
-    for (const [req_id, p] of [...this.pending]) {
-      if (p.worker_id === wid) {
-        clearTimeout(p.timer);
-        this.pending.delete(req_id);
-        p.reject(new Error(`worker ${wid} disconnected`));
-      }
-    }
-    for (const h of this.disconnectHandlers) h(wid);
-  }
-  startKeepalive(socket) {
-    if (this.keepaliveIntervalMs <= 0) return;
-    if (this.keepaliveTimers.has(socket)) return;
-    const timer = setInterval(() => {
-      if (socket.readyState !== WebSocket.OPEN) return;
-      this.rawSend(socket, {
-        type: "PONG",
-        nonce: this.opts.idGen.next("nonce"),
-        ts: this.opts.clock.now(),
-        protocol_version: PROTOCOL_VERSION,
-        echo_nonce: "server-keepalive"
-      });
-    }, this.keepaliveIntervalMs);
-    if (typeof timer.unref === "function") {
-      timer.unref();
-    }
-    this.keepaliveTimers.set(socket, timer);
-  }
-  stopKeepalive(socket) {
-    const timer = this.keepaliveTimers.get(socket);
-    if (!timer) return;
-    clearInterval(timer);
-    this.keepaliveTimers.delete(socket);
-  }
-  rawSend(socket, msg) {
-    const r = ServerToClientSchema.safeParse(msg);
-    if (!r.success) {
-      console.error("[hub] outgoing failed schema", r.error);
-      return;
-    }
-    if (socket.readyState === WebSocket.OPEN) {
-      socket.send(JSON.stringify(msg));
-    }
-  }
-  exec(worker_id, params) {
-    const socket = this.byWorker.get(worker_id);
-    if (!socket)
-      return Promise.reject(new Error(`worker ${worker_id} not connected`));
-    const req_id = this.opts.idGen.next("req");
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        this.pending.delete(req_id);
-        reject(
-          new Error(`EXEC ${req_id} timeout after ${this.execTimeoutMs}ms`)
-        );
-      }, this.execTimeoutMs);
-      this.pending.set(req_id, { resolve, reject, timer, worker_id });
-      this.rawSend(socket, {
-        type: "EXEC",
-        nonce: this.opts.idGen.next("nonce"),
-        ts: this.opts.clock.now(),
-        protocol_version: PROTOCOL_VERSION,
-        req_id,
-        session_id: params.session_id,
-        tab_id: params.tab_id,
-        step: { kind: "tool", tool: params.step.tool, args: params.step.args }
-      });
-      if (this.byWorker.get(worker_id) !== socket) {
-        clearTimeout(timer);
-        this.pending.delete(req_id);
-        reject(new Error(`worker ${worker_id} disconnected`));
-      }
-    });
-  }
-  async send(worker_id, msg) {
-    const socket = this.byWorker.get(worker_id);
-    if (!socket) throw new Error(`worker ${worker_id} not connected`);
-    this.rawSend(socket, msg);
-  }
-  onMessage(handler) {
-    this.msgHandlers.push(handler);
-  }
-  onDisconnect(handler) {
-    this.disconnectHandlers.push(handler);
-  }
-  connectedWorkers() {
-    return [...this.byWorker.keys()];
-  }
-  // Intentionally fire-and-forget: actual cleanup (byWorker/workerOf removal and
-  // pending-exec rejection) happens asynchronously via the socket's close event.
-  // v1 callers do not await this method.
-  async disconnect(worker_id, _reason) {
-    const socket = this.byWorker.get(worker_id);
-    if (socket) socket.close();
-  }
-};
-
 // src/mcp-server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -2040,31 +1857,39 @@ function readToolMode(env) {
 }
 
 // src/handlers.ts
-function singleWorkerId(c) {
+function singleWorkerId(c, pairUrl) {
   const workers = c.workers.list();
-  if (workers.length === 0) throw new Error("\u6CA1\u6709\u6D4F\u89C8\u5668\u8FDE\u5165\uFF0C\u8BF7\u5728\u6269\u5C55\u8BBE\u7F6E\u9875\u586B ws://127.0.0.1:<port>/worker \u8FDE\u63A5");
+  if (workers.length === 0) {
+    throw new Error(
+      "\u6CA1\u6709\u6D4F\u89C8\u5668\u8FDE\u5165\u3002\u5DF2\u4E3A\u4F60\u6253\u5F00\u914D\u5BF9\u9875" + (pairUrl ? ` ${pairUrl}` : "") + "\uFF0C\u5728\u6D4F\u89C8\u5668\u91CC\u786E\u8BA4\u540E\u91CD\u8BD5\u672C\u6B21\u8C03\u7528\u3002\uFF08\u5982\u679C\u9ED8\u8BA4\u6D4F\u89C8\u5668\u4E0D\u662F\u88C5\u4E86\u6269\u5C55\u7684\u90A3\u4E2A\uFF0C\u8BF7\u628A\u8BE5\u5730\u5740\u7C98\u8D34\u8FC7\u53BB\u6253\u5F00\uFF09"
+    );
+  }
   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");
   return workers[0].id;
 }
-function handleListTabs(deps) {
-  const w = deps.coordinator.workers.get(singleWorkerId(deps.coordinator));
+async function handleListTabs(deps) {
+  const { coordinator } = await deps.ensure();
+  const w = coordinator.workers.get(singleWorkerId(coordinator, deps.pairUrl()));
   return { tabs: w.available_tabs };
 }
-function handleOpenSession(deps, args) {
-  const worker_id = singleWorkerId(deps.coordinator);
+async function handleOpenSession(deps, args) {
+  const { coordinator } = await deps.ensure();
+  const worker_id = singleWorkerId(coordinator, deps.pairUrl());
   const tab_id = String(args.tab_id);
   const requested = Array.isArray(args.capabilities) ? args.capabilities.map(String).filter(isCapability) : [];
   const scope = new Set(requested.length ? requested : CAPABILITIES);
   const idle_timeout_ms = typeof args.idle_timeout_min === "number" ? args.idle_timeout_min * 6e4 : void 0;
-  const s = deps.coordinator.openSession({ ai_client_fingerprint: "mcp-local", worker_id, tab_id, scope, idle_timeout_ms });
+  const s = coordinator.openSession({ ai_client_fingerprint: "mcp-local", worker_id, tab_id, scope, idle_timeout_ms });
   return { session_id: s.id };
 }
-function handleCloseSession(deps, args) {
-  deps.coordinator.closeSession(String(args.session_id));
+async function handleCloseSession(deps, args) {
+  const { coordinator } = await deps.ensure();
+  coordinator.closeSession(String(args.session_id));
   return { ok: true };
 }
-function handleGetQuota(deps, args) {
-  const q = deps.coordinator.quotaFor(String(args.session_id));
+async function handleGetQuota(deps, args) {
+  const { coordinator } = await deps.ensure();
+  const q = coordinator.quotaFor(String(args.session_id));
   if (!q) throw new Error(`session ${String(args.session_id)} not found`);
   return q;
 }
@@ -2073,18 +1898,19 @@ var NON_BUILTIN_CAPABILITY = {
   openTab: "tab:open"
 };
 async function handleBrowserTool(deps, gen, args) {
+  const { coordinator, hub } = await deps.ensure();
   const session_id = String(args.session_id);
-  const session = deps.coordinator.sessions.get(session_id);
+  const session = coordinator.sessions.get(session_id);
   if (!session) throw new Error(`session ${session_id} not found`);
   const { session_id: _omit, ...toolArgs } = args;
   const tool = gen.builtinTool;
   if (gen.stepKind === "js") {
     const source = String(toolArgs.source ?? "");
     if (!source) throw new Error("browser_runJS: source required");
-    const v = deps.coordinator.validateCall({ session_id, kind: "runJS", unsafe: true });
+    const v = coordinator.validateCall({ session_id, kind: "runJS", unsafe: true });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    deps.coordinator.recordCall(session_id, v.dangerous);
-    const jsResult = await deps.hub.exec(session.worker_id, {
+    coordinator.recordCall(session_id, v.dangerous);
+    const jsResult = await hub.exec(session.worker_id, {
       session_id,
       tab_id: session.tab_id,
       step: { kind: "js", source }
@@ -2098,12 +1924,12 @@ async function handleBrowserTool(deps, gen, args) {
   }
   const override = NON_BUILTIN_CAPABILITY[gen.builtinTool];
   if (override) {
-    const v = deps.coordinator.validateCall({ session_id, kind: "capability", capability: override });
+    const v = coordinator.validateCall({ session_id, kind: "capability", capability: override });
     if (!v.ok) throw new Error(`${v.error.code}: ${v.error.message}`);
-    deps.coordinator.recordCall(session_id, v.dangerous);
+    coordinator.recordCall(session_id, v.dangerous);
   } else {
     const raw = toolArgs;
-    const v = deps.coordinator.validateCall({
+    const v = coordinator.validateCall({
       session_id,
       kind: "extension_tool",
       tool,
@@ -2112,9 +1938,9 @@ 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}`);
-    deps.coordinator.recordCall(session_id, v.dangerous);
+    coordinator.recordCall(session_id, v.dangerous);
   }
-  const result = await deps.hub.exec(session.worker_id, { session_id, tab_id: session.tab_id, step: { kind: "tool", tool, args: toolArgs } });
+  const result = await hub.exec(session.worker_id, { session_id, tab_id: session.tab_id, step: { kind: "tool", tool, args: toolArgs } });
   if (!result.ok) throw new Error(result.error ? `${result.error.code}: ${result.error.message}` : "EXEC failed");
   return result.return ?? null;
 }
@@ -2186,8 +2012,9 @@ var LEGACY_TOOLS = [
   "readStorage"
 ];
 function workerToolSupport(deps) {
-  if (!deps) return void 0;
-  const workers = deps.coordinator.workers.list();
+  const bundle = deps?.peek();
+  if (!bundle) return void 0;
+  const workers = bundle.coordinator.workers.list();
   if (workers.length === 0) return void 0;
   const supported = workers[0].supported_tools;
   return supported ?? new Set(LEGACY_TOOLS);
@@ -2218,10 +2045,10 @@ async function dispatchCall(deps, name, args) {
       const bundle = readSkillBundle();
       return { content: [{ type: "text", text: bundle.content }] };
     }
-    if (name === "list_tabs") return ok(handleListTabs(deps));
-    if (name === "open_session") return ok(handleOpenSession(deps, args));
-    if (name === "close_session") return ok(handleCloseSession(deps, args));
-    if (name === "get_quota") return ok(handleGetQuota(deps, args));
+    if (name === "list_tabs") return ok(await handleListTabs(deps));
+    if (name === "open_session") return ok(await handleOpenSession(deps, args));
+    if (name === "close_session") return ok(await handleCloseSession(deps, args));
+    if (name === "get_quota") return ok(await handleGetQuota(deps, args));
     const gen = BROWSER_BY_NAME.get(name);
     if (gen) return toolResult(gen, await handleBrowserTool(deps, gen, args));
     return fail2(`unknown tool: ${name}`);
@@ -2239,6 +2066,318 @@ function createMcpServer(deps) {
   return server;
 }
 
+// src/loopback-ws-hub.ts
+import { WebSocketServer, WebSocket } from "ws";
+import { createServer } from "http";
+
+// ../shared/src/pairing/types.ts
+var GRACEFUL_CLOSE_CODE = 4e3;
+var GRACEFUL_CLOSE_REASON = "server-shutting-down";
+
+// src/pair-page.ts
+function renderPairPage(payload) {
+  const json = JSON.stringify(payload).replace(/</g, "\\u003c");
+  return `<!doctype html>
+<meta charset="utf-8">
+<title>AtWebPilot \u914D\u5BF9</title>
+<body style="font:14px/1.6 system-ui,sans-serif;padding:2rem;max-width:32rem;margin:auto;color:#222">
+<h1 style="font-size:1.1rem;margin:0 0 1rem">AtWebPilot \u914D\u5BF9</h1>
+<p id="atwebpilot-status">\u6B63\u5728\u8054\u7CFB\u6269\u5C55\u2026</p>
+<p style="color:#666;font-size:13px">\u4F1A\u8BDD\uFF1A${escapeHtml(payload.label)} \xB7 pid ${payload.pid} \xB7 \u7AEF\u53E3 ${payload.port}</p>
+<p style="color:#666;font-size:13px">\u6CA1\u6709\u53CD\u5E94\uFF1F\u8BF7\u786E\u8BA4\u8FD9\u4E2A\u6D4F\u89C8\u5668\u5DF2\u5B89\u88C5\u5E76\u542F\u7528 AtWebPilot \u6269\u5C55\uFF0C\u7136\u540E\u5237\u65B0\u672C\u9875\u3002</p>
+<script>
+(function () {
+  var payload = ${json};
+  window.postMessage({ source: "atwebpilot-pair", payload: payload }, "*");
+  window.addEventListener("message", function (e) {
+    if (!e.data || e.data.source !== "atwebpilot-pair-result") return;
+    var el = document.getElementById("atwebpilot-status");
+    if (e.data.ok) {
+      el.textContent = e.data.trusted ? "\u5DF2\u4FE1\u4EFB\uFF0C\u8FDE\u63A5\u4E2D\u2026" : "\u5DF2\u8FDE\u63A5";
+      setTimeout(function () { window.close(); }, 1200);
+    } else {
+      el.textContent = "\u5DF2\u62D2\u7EDD\u3002\u53EF\u4EE5\u5173\u95ED\u672C\u9875\u3002";
+    }
+  });
+})();
+</script>
+`;
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+// src/loopback-ws-hub.ts
+var HEARTBEAT_INTERVAL_MS = 2e4;
+var DEFAULT_KEEPALIVE_INTERVAL_MS = 15e3;
+var LoopbackWSHub = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.execTimeoutMs = opts.execTimeoutMs ?? 3e4;
+    this.keepaliveIntervalMs = opts.keepaliveIntervalMs ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
+    this.http = createServer((req, res) => this.onHttpRequest(req, res));
+    this.readyPromise = new Promise((resolve, reject) => {
+      this.http.once("listening", () => resolve(this.http.address().port));
+      this.http.once("error", (err) => {
+        reject(
+          err.code === "EADDRINUSE" ? new Error(
+            `port ${opts.port} is already in use \u2014 another atwebpilot-mcp may be running; set ATWEBPILOT_WS_PORT to choose another port`
+          ) : err
+        );
+      });
+    });
+    this.wss = new WebSocketServer({
+      server: this.http,
+      path: "/worker",
+      handleProtocols: (protocols) => [...protocols][0] ?? false
+    });
+    this.wss.on("connection", (socket, req) => this.onConnection(socket, req));
+    this.http.on("error", () => void 0);
+    this.wss.on("error", () => void 0);
+    this.http.listen(opts.port);
+  }
+  opts;
+  http;
+  wss;
+  /** Settled by the constructor so ready() cannot race the listen outcome. */
+  readyPromise;
+  byWorker = /* @__PURE__ */ new Map();
+  workerOf = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  msgHandlers = [];
+  disconnectHandlers = [];
+  execTimeoutMs;
+  keepaliveIntervalMs;
+  keepaliveTimers = /* @__PURE__ */ new Map();
+  ready() {
+    return this.readyPromise;
+  }
+  /** Serves the pairing page; everything else is a 404. */
+  onHttpRequest(req, res) {
+    const path = (req.url ?? "").split("?")[0];
+    if (path !== "/pair") {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("not found");
+      return;
+    }
+    const payload = this.opts.pairPayload?.();
+    if (!payload) {
+      res.writeHead(503, { "content-type": "text/plain; charset=utf-8" });
+      res.end("pairing unavailable");
+      return;
+    }
+    res.writeHead(200, {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store"
+    });
+    res.end(renderPairPage(payload));
+  }
+  /**
+   * Tells connected extensions this shutdown is deliberate, so they drop the
+   * endpoint instead of retrying it for the rest of the browser session.
+   */
+  async shutdown() {
+    for (const socket of this.wss.clients) {
+      try {
+        socket.close(GRACEFUL_CLOSE_CODE, GRACEFUL_CLOSE_REASON);
+      } catch {
+      }
+    }
+    await new Promise((r) => setTimeout(r, 50));
+    await this.close();
+  }
+  close() {
+    for (const p of this.pending.values()) {
+      clearTimeout(p.timer);
+      p.reject(new Error("hub closing"));
+    }
+    this.pending.clear();
+    for (const timer of this.keepaliveTimers.values()) clearInterval(timer);
+    this.keepaliveTimers.clear();
+    for (const socket of this.wss.clients) {
+      socket.terminate();
+    }
+    return new Promise(
+      (resolve) => this.wss.close(() => this.http.close(() => resolve()))
+    );
+  }
+  tokenOk(req) {
+    if (!this.opts.token) return true;
+    const offered = String(req.headers["sec-websocket-protocol"] ?? "").split(",").map((s) => s.trim());
+    return offered.includes(`bearer.${this.opts.token}`);
+  }
+  onConnection(socket, req) {
+    if (!this.tokenOk(req)) {
+      socket.close(4401, "bad token");
+      return;
+    }
+    socket.on("message", (raw) => this.onMessageRaw(socket, raw.toString()));
+    socket.on("close", () => this.onSocketClose(socket));
+    socket.on("error", () => {
+    });
+  }
+  onMessageRaw(socket, raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    const r = ClientToServerSchema.safeParse(parsed);
+    if (!r.success) return;
+    const msg = r.data;
+    if (msg.type === "HELLO") {
+      const existingSocket = this.byWorker.get(msg.worker_id);
+      if (existingSocket && existingSocket !== socket) {
+        this.workerOf.delete(existingSocket);
+        for (const [req_id, p] of [...this.pending]) {
+          if (p.worker_id === msg.worker_id) {
+            clearTimeout(p.timer);
+            this.pending.delete(req_id);
+            p.reject(new Error(`worker ${msg.worker_id} reconnected, exec cancelled`));
+          }
+        }
+        existingSocket.terminate();
+      }
+      this.byWorker.set(msg.worker_id, socket);
+      this.workerOf.set(socket, msg.worker_id);
+      this.rawSend(socket, {
+        type: "WELCOME",
+        nonce: this.opts.idGen.next("nonce"),
+        ts: this.opts.clock.now(),
+        protocol_version: PROTOCOL_VERSION,
+        server_time: this.opts.clock.now(),
+        heartbeat_interval_ms: HEARTBEAT_INTERVAL_MS
+      });
+      this.startKeepalive(socket);
+      for (const h of this.msgHandlers) h(msg.worker_id, msg);
+      return;
+    }
+    if (msg.type === "RESULT") {
+      const p = this.pending.get(msg.req_id);
+      if (p) {
+        clearTimeout(p.timer);
+        this.pending.delete(msg.req_id);
+        p.resolve(msg);
+      }
+      return;
+    }
+    if (msg.type === "PING") {
+      this.rawSend(socket, {
+        type: "PONG",
+        nonce: this.opts.idGen.next("nonce"),
+        ts: this.opts.clock.now(),
+        protocol_version: PROTOCOL_VERSION,
+        echo_nonce: msg.nonce
+      });
+    }
+    const wid = this.workerOf.get(socket);
+    if (wid) {
+      for (const h of this.msgHandlers) h(wid, msg);
+    }
+  }
+  onSocketClose(socket) {
+    this.stopKeepalive(socket);
+    const wid = this.workerOf.get(socket);
+    if (!wid) return;
+    this.workerOf.delete(socket);
+    this.byWorker.delete(wid);
+    for (const [req_id, p] of [...this.pending]) {
+      if (p.worker_id === wid) {
+        clearTimeout(p.timer);
+        this.pending.delete(req_id);
+        p.reject(new Error(`worker ${wid} disconnected`));
+      }
+    }
+    for (const h of this.disconnectHandlers) h(wid);
+  }
+  startKeepalive(socket) {
+    if (this.keepaliveIntervalMs <= 0) return;
+    if (this.keepaliveTimers.has(socket)) return;
+    const timer = setInterval(() => {
+      if (socket.readyState !== WebSocket.OPEN) return;
+      this.rawSend(socket, {
+        type: "PONG",
+        nonce: this.opts.idGen.next("nonce"),
+        ts: this.opts.clock.now(),
+        protocol_version: PROTOCOL_VERSION,
+        echo_nonce: "server-keepalive"
+      });
+    }, this.keepaliveIntervalMs);
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+    this.keepaliveTimers.set(socket, timer);
+  }
+  stopKeepalive(socket) {
+    const timer = this.keepaliveTimers.get(socket);
+    if (!timer) return;
+    clearInterval(timer);
+    this.keepaliveTimers.delete(socket);
+  }
+  rawSend(socket, msg) {
+    const r = ServerToClientSchema.safeParse(msg);
+    if (!r.success) {
+      console.error("[hub] outgoing failed schema", r.error);
+      return;
+    }
+    if (socket.readyState === WebSocket.OPEN) {
+      socket.send(JSON.stringify(msg));
+    }
+  }
+  exec(worker_id, params) {
+    const socket = this.byWorker.get(worker_id);
+    if (!socket)
+      return Promise.reject(new Error(`worker ${worker_id} not connected`));
+    const req_id = this.opts.idGen.next("req");
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(req_id);
+        reject(
+          new Error(`EXEC ${req_id} timeout after ${this.execTimeoutMs}ms`)
+        );
+      }, this.execTimeoutMs);
+      this.pending.set(req_id, { resolve, reject, timer, worker_id });
+      this.rawSend(socket, {
+        type: "EXEC",
+        nonce: this.opts.idGen.next("nonce"),
+        ts: this.opts.clock.now(),
+        protocol_version: PROTOCOL_VERSION,
+        req_id,
+        session_id: params.session_id,
+        tab_id: params.tab_id,
+        step: { kind: "tool", tool: params.step.tool, args: params.step.args }
+      });
+      if (this.byWorker.get(worker_id) !== socket) {
+        clearTimeout(timer);
+        this.pending.delete(req_id);
+        reject(new Error(`worker ${worker_id} disconnected`));
+      }
+    });
+  }
+  async send(worker_id, msg) {
+    const socket = this.byWorker.get(worker_id);
+    if (!socket) throw new Error(`worker ${worker_id} not connected`);
+    this.rawSend(socket, msg);
+  }
+  onMessage(handler) {
+    this.msgHandlers.push(handler);
+  }
+  onDisconnect(handler) {
+    this.disconnectHandlers.push(handler);
+  }
+  connectedWorkers() {
+    return [...this.byWorker.keys()];
+  }
+  // Intentionally fire-and-forget: actual cleanup (byWorker/workerOf removal and
+  // pending-exec rejection) happens asynchronously via the socket's close event.
+  // v1 callers do not await this method.
+  async disconnect(worker_id, _reason) {
+    const socket = this.byWorker.get(worker_id);
+    if (socket) socket.close();
+  }
+};
+
 // src/wire.ts
 function helloToWorker(h, now) {
   return {
@@ -2265,6 +2404,11 @@ function installWire(hub, coordinator, clock) {
       case "PING":
         coordinator.heartbeatWorker(worker_id);
         break;
+      case "TABS_UPDATE": {
+        const w = coordinator.workers.get(worker_id);
+        if (w) w.available_tabs = msg.tabs.map((t) => ({ ...t }));
+        break;
+      }
       default:
         break;
     }
@@ -2272,19 +2416,150 @@ function installWire(hub, coordinator, clock) {
   hub.onDisconnect((worker_id) => coordinator.unregisterWorker(worker_id));
 }
 
+// src/identity.ts
+import { mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+import { randomBytes, randomUUID } from "crypto";
+var FILE = "identity.json";
+function defaultIdentityDir() {
+  return join2(homedir(), ".atwebpilot");
+}
+function read(dir) {
+  try {
+    const raw = readFileSync2(join2(dir, FILE), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.installId !== "string" || typeof parsed.secret !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function write(dir, data) {
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  writeFileSync(join2(dir, FILE), `${JSON.stringify(data, null, 2)}
+`, { mode: 384 });
+}
+function loadOrCreateIdentity(dir = defaultIdentityDir()) {
+  const existing = read(dir);
+  if (existing) return { installId: existing.installId, secret: existing.secret };
+  const created = {
+    installId: `inst_${randomUUID().replace(/-/g, "").slice(0, 16)}`,
+    secret: randomBytes(24).toString("base64url")
+  };
+  write(dir, created);
+  return { installId: created.installId, secret: created.secret };
+}
+function loadLastPort(dir = defaultIdentityDir()) {
+  const existing = read(dir);
+  return typeof existing?.lastPort === "number" ? existing.lastPort : void 0;
+}
+function saveLastPort(port, dir = defaultIdentityDir()) {
+  const existing = read(dir);
+  const base = existing ?? { ...loadOrCreateIdentity(dir) };
+  write(dir, { ...base, lastPort: port });
+}
+function processInfo(cwd = process.cwd()) {
+  const home = homedir();
+  const label = home && cwd.startsWith(home) ? `~${cwd.slice(home.length)}` : cwd;
+  return {
+    sessionId: `sess_${randomUUID().replace(/-/g, "").slice(0, 12)}`,
+    label,
+    pid: process.pid
+  };
+}
+
+// src/ensure-hub.ts
+function createHubEnsurer(d) {
+  let bundle = null;
+  let inflight = null;
+  let pairUrlValue = null;
+  let opened = false;
+  const info = d.processInfo ?? processInfo();
+  async function bind() {
+    const identity = loadOrCreateIdentity(d.identityDir);
+    const preferred = d.explicitPort ?? loadLastPort(d.identityDir) ?? 0;
+    let hub;
+    let port;
+    const pairPayload = () => ({
+      v: 1,
+      installId: identity.installId,
+      secret: identity.secret,
+      sessionId: info.sessionId,
+      label: info.label,
+      pid: info.pid,
+      port
+    });
+    try {
+      hub = new LoopbackWSHub({ ...common(), port: preferred, pairPayload });
+      port = await hub.ready();
+    } catch (e) {
+      if (d.explicitPort != null) throw e;
+      hub = new LoopbackWSHub({ ...common(), port: 0, pairPayload });
+      port = await hub.ready();
+    }
+    saveLastPort(port, d.identityDir);
+    const coordinator = new Coordinator({ hub, clock: d.clock, idGen: d.idGen });
+    installWire(hub, coordinator, d.clock);
+    pairUrlValue = `http://127.0.0.1:${port}/pair`;
+    return { coordinator, hub, port };
+    function common() {
+      return { token: d.token, clock: d.clock, idGen: d.idGen };
+    }
+  }
+  async function ensure() {
+    if (bundle) return bundle;
+    inflight ??= bind().then((b2) => {
+      bundle = b2;
+      return b2;
+    });
+    const b = await inflight;
+    if (!opened) {
+      opened = true;
+      if (pairUrlValue) d.openUrl?.(pairUrlValue);
+    }
+    return b;
+  }
+  return {
+    ensure,
+    peek: () => bundle,
+    pairUrl: () => pairUrlValue,
+    bound: () => bundle != null
+  };
+}
+function defaultOpenUrl(url) {
+  void import("child_process").then(({ spawn }) => {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+      spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+    } catch {
+    }
+  });
+}
+
 // src/index.ts
 async function main() {
-  const port = Number(process.env.ATWEBPILOT_WS_PORT ?? 8787);
+  const explicitPort = process.env.ATWEBPILOT_WS_PORT ? Number(process.env.ATWEBPILOT_WS_PORT) : void 0;
   const token = process.env.ATWEBPILOT_WS_TOKEN || void 0;
   const clock = new DefaultClock();
   const idGen = new DefaultIdGen();
-  const hub = new LoopbackWSHub({ port, token, clock, idGen });
-  await hub.ready();
-  const coordinator = new Coordinator({ hub, clock, idGen });
-  installWire(hub, coordinator, clock);
-  const server = createMcpServer({ coordinator, hub });
+  const deps = createHubEnsurer({
+    clock,
+    idGen,
+    explicitPort,
+    token,
+    openUrl: defaultOpenUrl
+  });
+  const server = createMcpServer(deps);
   await server.connect(new StdioServerTransport());
-  console.error(`[atwebpilot-mcp] ws://127.0.0.1:${port}/worker ready; stdio MCP connected`);
+  console.error("[atwebpilot-mcp] stdio MCP connected; ws port binds on first browser use");
+  const shutdown = () => {
+    const bundle = deps.peek();
+    void (bundle?.hub.shutdown?.() ?? Promise.resolve()).finally(() => process.exit(0));
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+  process.stdin.on("close", shutdown);
 }
 main().catch((e) => {
   console.error("[atwebpilot-mcp] fatal", e);

package/package.json

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