@attson/atwebpilot-mcp 0.0.80 → 0.0.82

package/README.md

@@ -2,12 +2,15 @@
 
 让 Codex 或 Claude Code 经一个本地 ws 中继驱动 atwebpilot 浏览器扩展操作网页（读 / 写 / 采）。
 
-## 给用户：一行装
+## 给用户：安装
 
 Codex：
 
+    npx -y @attson/atwebpilot-mcp --install-codex-skill
     codex mcp add atwebpilot -- npx -y @attson/atwebpilot-mcp
 
+第一条命令把正式 Skill 安装到用户级 `~/.agents/skills/atwebpilot-browser/`，让 Codex 在真实网页验收、截图、调试、读取或交互任务中主动发现 AtWebPilot；它不会修改任何项目的 `AGENTS.md`。内容相同时重复执行是幂等的；若目标被手工修改会拒绝覆盖，确认替换时显式加 `--force`。安装后新开 Codex 会话。
+
 Claude Code：
 
     claude mcp add atwebpilot --scope user -- npx -y @attson/atwebpilot-mcp
@@ -17,8 +20,8 @@ Claude Code：
 **不需要手填端口。** 从 Plan 33 起是配对流程：
 
 1. 会话启动时**不绑任何端口** —— 不碰网页的会话零副作用。
-2. AI 第一次调 `list_tabs` 时才绑一个空闲端口，通过 MCP URL elicitation 请宿主打开配对页；不支持该能力的宿主回退到系统默认浏览器。`list_tabs` 最多等待 45 秒。
-3. 你在浏览器里点「允许」，扩展即接入；同一次 `list_tabs` 调用直接返回 tab，AI 无需让你回复「已连接」。只有等待超时才返回 `pairing_required + pair_url`；`pairing_status` 始终是立即返回的非阻塞状态检查。
+2. AI 第一次调 `browser_start` 时才绑一个空闲端口，通过 MCP URL elicitation 请宿主打开配对页；不支持该能力的宿主回退到系统默认浏览器。`browser_start` 最多等待 45 秒。
+3. 你在浏览器里点「允许」，扩展即接入；唯一 tab 可确定时同一次 `browser_start` 调用直接返回 ready session，多个候选时返回 `select_tab`，AI 带选中的 `tab_id` 再调用一次。无需让你回复「已连接」。只有等待超时才返回 `pairing_required + pair_url`；`pairing_status` 始终是立即返回的非阻塞状态检查。
 4. 之后本机的会话都免确认（信任是安装级的）；端口能复用时连配对页都不会弹。
 
 若宿主和系统都未弹出浏览器，可在超时结果中打开 `pair_url`。授权成功只以扩展实际建立连接并发送 `HELLO` 为准；打开配对页本身不代表已连接。
@@ -30,6 +33,7 @@ Coordinator 查看已接入的会话、单独断开，或撤销信任。
 
 - `ATWEBPILOT_WS_PORT`：固定端口（默认是自动选一个空闲端口并复用上次的）
 - `ATWEBPILOT_WS_TOKEN`：要求扩展带 `bearer.<token>` 子协议
+- `ATWEBPILOT_CODEX_SKILLS_DIR`：覆盖 Codex Skill 安装根目录（默认 `~/.agents/skills`）
 
 ## 给开发者：本地 monorepo
 
@@ -48,9 +52,10 @@ listen 端口的能力，所以方向只能如此。这也是配对页存在的
 
 ## 工具面
 
-- 控制面 5 个：`pairing_status / list_tabs / open_session / close_session / get_quota`
+- 控制面 6 个：`browser_start / pairing_status / list_tabs / open_session / close_session / get_quota`。常规网页任务从 `browser_start` 开始；`list_tabs` / `open_session` 保留为底层兼容入口。
 - 发现 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 +71,7 @@ hover / uploadFile / scroll / waitFor`）；`browser_storage` 也不会列出，
 
 | 值 | 效果 |
 |---|---|
-| `core`（默认） | 连接前仅控制面、发现工具与同轮执行桥；连接后再列出 31 个核心工具 |
+| `core`（默认） | 连接前仅控制面、发现工具、同轮执行桥与批量编排；连接后再列出 31 个核心工具 |
 | `full` | 连接前同上；连接后列出全部 51 个原生工具 |
 
 无法识别的值（包括已移除的 `parity`）按 `core` 处理，并往 stderr 打一条提示。

package/dist/index.js

@@ -946,6 +946,20 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprot
 
 // src/control-tools.ts
 var CONTROL_TOOLS = [
+  {
+    name: "browser_start",
+    description: "Primary entry point for a live web page in the user's existing Chrome: localhost, screenshots/UI smoke, authenticated interaction, or console/network debugging. Pairs if needed and returns a ready session or tab candidates.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tab_id: { type: "string", description: "Exact id from browser_start/list_tabs" },
+        url: { type: "string", description: "Exact URL of an open tab" },
+        capabilities: { type: "array", items: { type: "string" }, description: "Optional capability scope" },
+        idle_timeout_min: { type: "number", description: "Optional idle timeout in minutes" }
+      },
+      additionalProperties: false
+    }
+  },
   {
     name: "pairing_status",
     description: "Start or check browser pairing without waiting. Returns connected or pairing_required with the pair URL.",
@@ -2389,6 +2403,53 @@ async function handleListTabs(deps, onPairingRequired, timeoutMs = LIST_TABS_PAI
   }
   return { status: "connected", tabs: worker.available_tabs };
 }
+function selectionResult(tabs, message) {
+  return { status: "select_tab", tabs, message };
+}
+async function handleBrowserStart(deps, args, onPairingRequired, timeoutMs = LIST_TABS_PAIRING_TIMEOUT_MS) {
+  const listed = await handleListTabs(deps, onPairingRequired, timeoutMs);
+  if (listed.status === "pairing_required") return listed;
+  const tabId = typeof args.tab_id === "string" && args.tab_id.length > 0 ? args.tab_id : void 0;
+  const url = typeof args.url === "string" && args.url.length > 0 ? args.url : void 0;
+  let selected;
+  if (tabId) {
+    selected = listed.tabs.find((tab) => tab.tab_id === tabId);
+    if (!selected) {
+      throw new Error(`InvalidArgs: browser_start tab_id ${JSON.stringify(tabId)} is not available`);
+    }
+    if (url && selected.url !== url) {
+      throw new Error("InvalidArgs: browser_start tab_id and url must identify the same tab");
+    }
+  } else if (url) {
+    const matches = listed.tabs.filter((tab) => tab.url === url);
+    if (matches.length === 1) {
+      [selected] = matches;
+    } else if (matches.length > 1) {
+      return selectionResult(
+        matches,
+        "Multiple tabs have that exact URL. Choose one and call browser_start again with tab_id."
+      );
+    } else {
+      return selectionResult(
+        listed.tabs,
+        "No exact URL match. Choose a tab and call browser_start again with tab_id."
+      );
+    }
+  } else if (listed.tabs.length === 1) {
+    [selected] = listed.tabs;
+  } else {
+    return selectionResult(
+      listed.tabs,
+      "Choose a tab and call browser_start again with tab_id."
+    );
+  }
+  const opened = await handleOpenSession(deps, {
+    tab_id: selected.tab_id,
+    ...Array.isArray(args.capabilities) ? { capabilities: args.capabilities } : {},
+    ...typeof args.idle_timeout_min === "number" ? { idle_timeout_min: args.idle_timeout_min } : {}
+  });
+  return { status: "ready", session_id: opened.session_id, tab: selected };
+}
 async function handleOpenSession(deps, args) {
   const { coordinator } = await deps.ensure();
   const worker_id = singleWorkerId(coordinator, deps.pairUrl());
@@ -2414,7 +2475,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);
@@ -2429,23 +2490,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);
@@ -2455,10 +2513,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({
@@ -2470,13 +2529,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";
@@ -2486,12 +2853,13 @@ var SKILL_DESCRIPTION = "Strategy + scenarios + safety rails for driving the AtW
 var TOPICS = {
   quickstart: `# AtWebPilot quickstart
 
-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.
+1. Call browser_start once. On first use it opens the pairing page and waits for authorization; when one tab is unambiguous it returns a ready session in the same call.
+2. If browser_start returns select_tab, call browser_start again with one returned tab_id. list_tabs and open_session remain lower-level compatibility tools.
+3. If browser_start 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.
 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
 
@@ -2537,9 +2905,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}
 
@@ -2569,7 +2939,7 @@ var SKILL_TOOL = {
 // package.json
 var package_default = {
   name: "@attson/atwebpilot-mcp",
-  version: "0.0.80",
+  version: "0.0.82",
   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",
@@ -2678,6 +3048,7 @@ function createPairingPresenter(server, fallbackOpenUrl) {
 }
 
 // src/mcp-server.ts
+var MCP_INSTRUCTIONS = "Use AtWebPilot for tasks that require inspecting, testing, debugging, screenshotting, reading, or interacting with a live web page in the user's existing Chrome, including localhost and authenticated pages. Start with browser_start. When AtWebPilot is available, use it before probing or launching Playwright, Puppeteer, or Chrome remote debugging. Do not start the browser for pure code editing or static source analysis that does not require observing a live page.";
 var ALL_BROWSER_TOOLS = generateBrowserTools("full");
 var BROWSER_BY_NAME = new Map(ALL_BROWSER_TOOLS.map((t) => [t.name, t]));
 function createToolState(mode) {
@@ -2724,6 +3095,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 }))
   ];
 }
@@ -2763,6 +3135,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);
@@ -2774,6 +3164,11 @@ async function dispatchCall(deps, name, args, state = DEFAULT_STATE, onListChang
       if (result.status === "connected") await revealBrowserSurface(state, onListChanged);
       return ok(result);
     }
+    if (name === "browser_start") {
+      const result = await handleBrowserStart(deps, args, onPairingRequired);
+      if (result.status !== "pairing_required") await revealBrowserSurface(state, onListChanged);
+      return ok(result);
+    }
     if (name === "open_session") {
       const result = await handleOpenSession(deps, args);
       await revealBrowserSurface(state, onListChanged);
@@ -2826,7 +3221,10 @@ async function revealBrowserSurface(state, onListChanged) {
 function createMcpServer(deps, state = DEFAULT_STATE, options = {}) {
   const server = new Server(
     { name: "atwebpilot-mcp", version: MCP_VERSION },
-    { capabilities: { tools: { listChanged: true }, logging: {} } }
+    {
+      capabilities: { tools: { listChanged: true }, logging: {} },
+      instructions: MCP_INSTRUCTIONS
+    }
   );
   const presentPairing = createPairingPresenter(server, options.fallbackOpenUrl);
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: buildToolList(deps, state) }));
@@ -3603,8 +4001,103 @@ async function defaultOpenUrl(url) {
   throw new Error(errors.join("; ") || "no browser opener available");
 }
 
+// src/skill-installer.ts
+import { access, mkdir, readFile as readFile2, rename, unlink, writeFile } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var SKILL_DIRECTORY_NAME = "atwebpilot-browser";
+function isMissing(error) {
+  return error?.code === "ENOENT";
+}
+async function atomicWrite(targetFile, content) {
+  const temporaryFile = `${targetFile}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temporaryFile, content, { encoding: "utf8", mode: 420, flag: "wx" });
+    await rename(temporaryFile, targetFile);
+  } catch (error) {
+    await unlink(temporaryFile).catch(() => void 0);
+    throw error;
+  }
+}
+async function installCodexSkill(options) {
+  let source;
+  try {
+    source = await readFile2(options.sourceFile, "utf8");
+  } catch (error) {
+    if (isMissing(error)) {
+      throw new Error(`Skill source is missing: ${options.sourceFile}`);
+    }
+    throw error;
+  }
+  const targetDirectory = join3(options.skillsRoot, SKILL_DIRECTORY_NAME);
+  const targetFile = join3(targetDirectory, "SKILL.md");
+  let existing;
+  try {
+    existing = await readFile2(targetFile, "utf8");
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+  if (existing === source) return { status: "unchanged", targetFile };
+  if (existing !== void 0 && !options.force) {
+    throw new Error(
+      `Codex Skill already exists with different content at ${targetFile}; rerun with --force to overwrite it.`
+    );
+  }
+  await mkdir(targetDirectory, { recursive: true });
+  await atomicWrite(targetFile, source);
+  return {
+    status: existing === void 0 ? "installed" : "overwritten",
+    targetFile
+  };
+}
+function defaultCodexSkillsRoot(env = process.env, homeDirectory = homedir2()) {
+  return env.ATWEBPILOT_CODEX_SKILLS_DIR || join3(homeDirectory, ".agents", "skills");
+}
+async function resolveBundledSkillFile(moduleUrl = import.meta.url) {
+  const here = dirname2(fileURLToPath2(moduleUrl));
+  const candidates = [
+    join3(here, "skill", "SKILL.md"),
+    join3(here, "../../../skill/SKILL.md")
+  ];
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new Error(`Skill source is missing; checked: ${candidates.join(", ")}`);
+}
+async function runSkillInstallCommand(args, overrides = {}) {
+  if (!args.includes("--install-codex-skill")) return { handled: false };
+  const supported = /* @__PURE__ */ new Set(["--install-codex-skill", "--force"]);
+  const unknown = args.filter((arg) => !supported.has(arg));
+  if (unknown.length > 0) {
+    throw new Error(`Unknown option for Skill installation: ${unknown.join(", ")}`);
+  }
+  const sourceFile = overrides.sourceFile ?? await resolveBundledSkillFile();
+  const skillsRoot = overrides.skillsRoot ?? defaultCodexSkillsRoot();
+  const result = await installCodexSkill({
+    sourceFile,
+    skillsRoot,
+    force: args.includes("--force")
+  });
+  return { handled: true, result };
+}
+
 // src/index.ts
 async function main() {
+  const args = process.argv.slice(2);
+  const install = await runSkillInstallCommand(args);
+  if (install.handled) {
+    process.stdout.write(`Codex Skill ${install.result.status}: ${install.result.targetFile}
+`);
+    return;
+  }
+  if (args.length > 0) {
+    throw new Error(`Unknown option: ${args.join(", ")}`);
+  }
   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();

package/dist/skill/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: atwebpilot-browser
+description: Use AtWebPilot when a task requires inspecting, testing, debugging, screenshotting, reading, or interacting with a live web page in the user's existing Chrome, including localhost and authenticated pages. Do not use it for pure code editing or static source analysis that does not require observing a live page.
+---
+
 # atwebpilot-browser skill
 
 A reusable strategy for agents that drive AtWebPilot's browser extension via
@@ -12,6 +17,10 @@ When this skill is loaded, you can drive any open tab through these tools
 
 ### Control plane
 
+- `browser_start({ tab_id?, url? })` — primary entry point for live-page work.
+  It pairs when needed and returns a ready session when exactly one tab can be
+  selected safely. When it returns `select_tab`, call it again with one listed
+  `tab_id`; it never guesses between tabs.
 - `pairing_status` — start/check pairing without waiting. When it reports
   `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
@@ -88,7 +97,7 @@ compatibility path; use the native tool once the host exposes it.
 
 ## Recommended flow
 
-1. **先建立连接**：调一次 `list_tabs`；首次配对时它会打开授权页并等待最多 45 秒，授权成功后同一次调用直接返回 tab，不要让用户回复「已连接」。只有超时才会返回 `pairing_required`；此时展示 `pair_url`，稍后用非阻塞的 `pairing_status` 检查，不要轮询 `list_tabs`。
+1. **先建立连接**：调一次 `browser_start`；首次配对时它会打开授权页并等待最多 45 秒，唯一 tab 可确定时同一次调用直接返回 ready session。返回 `select_tab` 时带 `tab_id` 再调一次；只有超时才会返回 `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` 给用户看上下文，让审批更顺。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attson/atwebpilot-mcp",
-  "version": "0.0.80",
+  "version": "0.0.82",
   "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",