browser-attach 0.0.0-stage → 0.1.2

package/bundle/browser-attach.mjs

@@ -0,0 +1,1451 @@
+#!/usr/bin/env node
+import { createRequire as __attachCreateRequire } from 'node:module'; const require = __attachCreateRequire(import.meta.url);
+
+// packages/bridge/dist/cli/main.js
+import { parseArgs } from "node:util";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join7 } from "node:path";
+import { homedir as homedir5 } from "node:os";
+
+// packages/bridge/dist/cli/commands.js
+import { readFileSync as readFileSync3, copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { basename, dirname as dirname3, extname, join as join4, resolve } from "node:path";
+import { homedir as homedir4 } from "node:os";
+
+// packages/bridge/dist/tool-descriptions.js
+var Descriptions = {
+  snapshot: "Capture an interactables snapshot of the active tab. Returns refs you can use with click/type/hover/etc. is_new flags appear on elements that weren't in the previous snapshot.",
+  view: `Reading-order markdown view of the page (iframes included) mixing text and [eN] refs. The canonical "see this page" tool. Over the size budget it returns an outline, the part around the viewport and a file path holding the whole view (grep it: control lines carry their refs). ref: one element's subtree. offset: page through. Plain-text and JSON documents come back as raw text. Screenshots: browser_screenshot.`,
+  screenshot: "Screenshot of the visible viewport (JPEG, max 1024px wide), one element (ref: cropped) or the whole page (full). annotate draws each visible interactable's ref on the image and lists them, so a ref can be picked from the picture. Costs far more context than browser_view; use it when the text is not enough (icons, charts, canvas, layout). To click a point seen in it: x = origin.x + image x * scale (same for y), or click the ref of an annotated box. A background agent tab is brought to the front of the agent window first.",
+  find: "Search the page view for text or a regex (names, roles, values, text) and return the matching lines with their refs, a little context and the enclosing sections. Cheaper than a full view on large pages.",
+  navigate: "Navigate the tab to a URL and wait for it to load. Returns URL, title, the interactable count and the first interactables of the new page; call browser_view to read it.",
+  click: "Click an element by ref (preferred) or by x/y viewport point. Synthetic events; no CDP. Returns effects (mutations, focus, dialog), the page URL/title, and newly appeared interactables; a click that loads a new page waits for it (navigated:true).",
+  type: "Type into an input. Pass `text` for what to type. `clear:true` empties the field first; `submit:true` presses Enter after (a resulting page load is waited for). Returns effects and newly appeared interactables.",
+  press_key: "Press a keyboard key. Use for keys not typeable as text (Enter, Tab, ArrowDown, Escape, F5, \u2026). A resulting page load is waited for.",
+  select: "Pick option(s) from a <select> by ref or x/y. Pass option `values` (labels also match).",
+  hover: "Hover over an element (ref or x/y). Useful for revealing tooltips and menu drop-downs; returns the newly appeared interactables.",
+  upload_file: "Upload base64-encoded file(s) to an <input type=file> (ref, or x/y on its button/label). Provide payloads inline.",
+  wait_for: "Wait until a condition holds: text appears, ref exists, URL matches, or an outgoing request URL matches. Plain sleep if no condition is set.",
+  scroll: "Scroll the page. Relative (dx/dy), absolute (y), into-view (ref), or sweep mode (until:page_end with pauses for lazy load).",
+  tabs: "Tab management: list, switch, new, close. Tabs are scoped to this MCP session: new tabs open in a window of their own for this session, and every tool reaches only tabs this session opened (or tabs opened from them).",
+  network_log: "Get recent network entries (fetch + XHR) for the active tab. Captured via in-page monkey-patch.",
+  eval_js: "Evaluate a JS expression or statement body (use return) in the page MAIN world, which sees page JS variables. Use only for things the other tools can't do. On pages that forbid eval (strict CSP, Trusted Types) or sandboxed pages (raw files), it falls back to a user-script world: DOM only, no page JS variables; the result's world field says which ran. Errors thrown by the expression are reported.",
+  inspect: "Read fields (text, value, tag, role, html, attributes, \u2026) from an element by ref. Useful for checking state after an interaction.",
+  get_cookie: "Read cookies for a URL (defaults to active tab). Optionally filter by exact name.",
+  request: "Make an HTTP request from the page context (carries the page's cookies / auth). Use for API calls that need the user's session.",
+  batch: "Run a sequence of tool calls in one round trip. Stops on error by default, or on any tool that invalidates refs (navigate, tab switch)."
+};
+
+// packages/bridge/dist/paths.js
+import { homedir } from "node:os";
+import { join } from "node:path";
+var env = () => process.env;
+var home = () => env().HOME || homedir();
+var cacheDir = () => env().BROWSER_ATTACH_CACHE_DIR || join(env().XDG_CACHE_HOME || join(home(), ".cache"), "browser-attach");
+var configDir = () => env().BROWSER_ATTACH_CONFIG_DIR || join(env().XDG_CONFIG_HOME || join(home(), ".config"), "browser-attach");
+var runtimeDir = () => env().BROWSER_ATTACH_RUNTIME_DIR || (env().XDG_RUNTIME_DIR ? join(env().XDG_RUNTIME_DIR, "browser-attach") : join(cacheDir(), "run"));
+var configPath = () => join(configDir(), "config.json");
+var socketPath = (port) => process.platform === "win32" ? `\\\\.\\pipe\\browser-attach-${(env().USERNAME || "user").replace(/[^\w.-]/g, "")}-${port}` : join(runtimeDir(), `daemon-${port}.sock`);
+var logPath = (port) => join(cacheDir(), `daemon-${port}.log`);
+var SESSION_NAME = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,63}$/;
+
+// packages/bridge/dist/daemon/config.js
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname, join as join2 } from "node:path";
+var NUMBERS = ["idleExitMs", "sessionTtlMs", "outMaxMB"];
+var DEFAULTS = { idleExitMs: 2 * 36e5, sessionTtlMs: 30 * 6e4, outMaxMB: 200 };
+function readConfig(path = configPath()) {
+  try {
+    const c = JSON.parse(readFileSync(path, "utf8"));
+    return c && typeof c === "object" ? c : {};
+  } catch {
+    return {};
+  }
+}
+function migrateLegacyConfig(path = configPath()) {
+  if (existsSync(path))
+    return false;
+  const legacy = join2(process.env.XDG_CONFIG_HOME || join2(process.env.HOME || homedir2(), ".config"), "jev-browser", "config.json");
+  if (!existsSync(legacy))
+    return false;
+  const old = readConfig(legacy), config = {};
+  for (const key of NUMBERS)
+    if (typeof old[key] === "number")
+      config[key] = old[key];
+  writeConfig(config, path);
+  return true;
+}
+function writeConfig(config, path = configPath()) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+  renameSync(tmp, path);
+}
+function setConfig(config, assignment) {
+  const i = assignment.indexOf("=");
+  if (i < 1)
+    throw new Error(`expected KEY=VALUE, got ${JSON.stringify(assignment)}`);
+  const key = assignment.slice(0, i), value = assignment.slice(i + 1);
+  if (!NUMBERS.includes(key))
+    throw new Error(`unknown setting ${key}; settings: ${NUMBERS.join(", ")}`);
+  const n2 = Number(value);
+  if (!Number.isFinite(n2) || n2 < 0)
+    throw new Error(`${key} must be a number >= 0`);
+  return { ...config, [key]: n2 };
+}
+
+// packages/bridge/dist/cli/format.js
+var s = (v) => typeof v === "string" ? v : "";
+var q = (v) => JSON.stringify(s(v));
+var n = (v) => typeof v === "number" ? v : void 0;
+var fileLine = (path) => `\u2192 ${path}`;
+var clip = (text, max) => text.length > max ? text.slice(0, max - 1) + "\u2026" : text;
+function change(verb, r) {
+  const parts = [`${verb} ok`];
+  if (r.navigated)
+    parts.push(`navigated \u2192 ${s(r.url)} ${q(r.title)}`);
+  else if (r.same_document)
+    parts.push(`url \u2192 ${s(r.url)}`);
+  if (r.loading)
+    parts.push("still loading");
+  if (r.navigation_error)
+    parts.push(`navigation error ${s(r.navigation_error)}`);
+  if (Array.isArray(r.opened_tabs) && r.opened_tabs.length)
+    parts.push(`opened tab ${r.opened_tabs.join(", ")} (browser-attach tabs)`);
+  const e = r.effects;
+  if (e?.dialog_opened)
+    parts.push("a dialog opened");
+  else if (e && !r.navigated && !e.url_changed && !e.target_subtree_changed && e.added_nodes === 0 && e.removed_nodes === 0)
+    parts.push("no visible change");
+  if (typeof r.typed === "string" && verb.startsWith("type"))
+    parts.push(`typed ${q(clip(r.typed, 80))}`);
+  if (typeof r.target === "string")
+    parts.push(`hit ${r.target}`);
+  if (n(r.interactables) !== void 0)
+    parts.push(`${r.interactables} refs`);
+  const lines2 = [parts.join(" \xB7 ")];
+  const fresh = Array.isArray(r.new) ? r.new : [];
+  if (fresh.length || r.more_new)
+    lines2.push(`new: ${fresh.join(" \xB7 ")}${r.more_new ? ` (+${r.more_new}: browser-attach view)` : ""}`);
+  if (r.note)
+    lines2.push(`note: ${s(r.note)}`);
+  return lines2;
+}
+function view(r) {
+  const lines2 = [];
+  const size = [n(r.lines) !== void 0 ? `${r.lines} lines` : "", n(r.actions) !== void 0 ? `${r.actions} refs` : "", n(r.chars) !== void 0 ? `${r.chars.toLocaleString("en-US")} chars` : ""].filter(Boolean);
+  lines2.push([`${q(r.title)} ${s(r.url)}`, ...size].join(" \xB7 "));
+  if (r.from !== void 0)
+    lines2[0] += ` \xB7 lines ${r.from}-${r.to}${r.next_offset ? ` (next: --offset ${r.next_offset})` : ""}`;
+  if (r.outline) {
+    lines2.push("outline:");
+    for (const line of s(r.outline).split("\n"))
+      lines2.push(`  ${line}`);
+  }
+  if (typeof r.content === "string") {
+    if (r.shown)
+      lines2.push(`lines ${r.shown[0]}-${r.shown[1]}:`);
+    lines2.push(r.content);
+  }
+  if (r.file)
+    lines2.push(fileLine(s(r.file)));
+  return { lines: lines2, file: s(r.file) || void 0 };
+}
+function shot(r) {
+  const image = r.image ?? {};
+  const origin = r.origin ?? { x: 0, y: 0 };
+  const off = (v) => v ? `${v} + ` : "";
+  const parts = [`shot ${image.width}x${image.height} ${r.mode}${r.ref ? ` ${s(r.ref)}` : ""}`, `${(n(image.bytes) ?? 0).toLocaleString("en-US")} bytes`];
+  if (r.mode === "full")
+    parts.push(`page ${r.pageHeight}px in ${r.segments} captures${r.truncated ? ", truncated" : ""}`);
+  if (r.clipped)
+    parts.push("clipped to the viewport");
+  parts.push(r.mode === "full" ? `scale ${r.scale} (page y = image y * ${r.scale}; scroll there before click --xy)` : `click --xy ${off(origin.x)}X*${r.scale},${off(origin.y)}Y*${r.scale} (viewport ${r.viewportWidth}x${r.viewportHeight})`);
+  parts.push(`${q(r.title)} ${s(r.url)}`);
+  const lines2 = [parts.join(" \xB7 ")];
+  const marks = Array.isArray(r.marks) ? r.marks : void 0;
+  if (marks) {
+    lines2.push(`${marks.length} refs drawn${r.moreMarks ? ` (+${r.moreMarks} not drawn)` : ""} (click <ref>):`);
+    for (const m of marks)
+      lines2.push(`  ${m}`);
+  }
+  return { lines: lines2 };
+}
+function find(term, r) {
+  const lines2 = [`find ${q(term)}: ${r.matches} match${r.matches === 1 ? "" : "es"}${r.shown !== r.matches ? ` (showing ${r.shown})` : ""} in ${q(r.title)} \xB7 ${r.lines} lines`];
+  if (typeof r.results === "string" && r.results)
+    lines2.push(r.results);
+  if (r.hint)
+    lines2.push(s(r.hint));
+  if (r.file)
+    lines2.push(fileLine(s(r.file)));
+  return { lines: lines2, file: s(r.file) || void 0 };
+}
+function tabs(r) {
+  const list = r.tabs ?? [];
+  if (!list.length)
+    return ["no tabs in this session (browser-attach open <url>)"];
+  return list.map((t) => `${t.id === r.active ? "*" : " "} ${t.id} ${q(clip(s(t.title), 80))} ${s(t.url)}`);
+}
+function evalResult(r) {
+  if (r.file)
+    return { lines: [`eval: ${(n(r.chars) ?? 0).toLocaleString("en-US")} chars of JSON`, ...r.preview ? [`preview: ${clip(s(r.preview).replace(/\s+/g, " "), 300)}`] : [], fileLine(s(r.file))], file: s(r.file) };
+  const text = JSON.stringify(r.value);
+  return { lines: [text === void 0 ? "undefined" : text.length > 200 ? JSON.stringify(r.value, null, 2) : text] };
+}
+var NEXT = {
+  STALE_REF: "The page re-rendered: get fresh refs with browser-attach view or browser-attach find <text>.",
+  NOT_FOUND: "Get fresh refs with browser-attach view or browser-attach find <text>.",
+  NO_SESSION_TAB: "Open a tab first: browser-attach open <url>.",
+  TAB_NOT_OWNED: "List the tabs of this session: browser-attach tabs.",
+  UNCERTAIN_STATE: "Check the page with browser-attach view, then act again.",
+  EXTENSION_NOT_CONNECTED: "Open Chrome with the extension loaded; check with browser-attach status.",
+  EXTENSION_OUTDATED: "Reload the extension from the current build (chrome://extensions).",
+  QUEUE_TIMEOUT: "Earlier calls of this session are slow; check browser-attach sessions, or use another session with -s.",
+  QUEUE_FULL: "Wait for the queued calls of this session to finish.",
+  DAEMON_EXITED: "Check the page with browser-attach view before acting again."
+};
+var nextStep = (code) => NEXT[code];
+var INFRA = /* @__PURE__ */ new Set(["EXTENSION_NOT_CONNECTED", "EXTENSION_OUTDATED", "PORT_IN_USE", "DAEMON_START_FAILED", "DAEMON_OUTDATED", "DAEMON_EXITED", "DAEMON_BUSY", "DAEMON_RESTARTED", "NO_DAEMON_ENTRY", "RPC_MISMATCH", "BRIDGE_DISCONNECT", "NOT_RUNNING"]);
+function exitCode(code) {
+  if (code === "USAGE")
+    return 2;
+  if (INFRA.has(code))
+    return 3;
+  if (code === "TIMEOUT" || code === "QUEUE_TIMEOUT")
+    return 5;
+  return 1;
+}
+
+// packages/bridge/dist/cli/skill.js
+var SKILL = `---
+name: browser-attach
+description: Drive the user's real Chrome (logged-in sessions) with the \`browser-attach\` CLI - open pages, read them, click and type. Use for any web interaction, or for reading pages that need the user's browser.
+allowed-tools: Bash(browser-attach:*), Read, Grep
+---
+# browser-attach: the user's Chrome from the shell
+
+Each Claude Code session gets its own tabs automatically (each in its own Chrome window); other sessions cannot see them.
+
+## Loop
+1. \`browser-attach open <url>\` (new tab) or \`browser-attach goto <url>\` (current tab). Both print the page like \`view\`.
+2. Read the page: \`browser-attach view\`. Small pages print inline; big pages print an outline and a file path (\`\u2192 /path/view-0002-host.md\`).
+   Every control line in the file carries its ref, e.g. \`- button: "Submit" [e12]\`.
+   Find things with the **Grep tool** on that file (pattern \`Submit\`), or read a range with the **Read tool** (offset/limit; the outline gives line numbers).
+   Or ask browser-attach: \`browser-attach find Submit\`, \`browser-attach find --regex 'button: "(Save|Submit)'\`, \`browser-attach view --ref e40\` (one subtree).
+3. Act with refs: \`browser-attach click e12\`, \`browser-attach type e7 "text" --submit\`, \`browser-attach select e9 value\`, \`browser-attach press Enter\`.
+   Results are one to three lines: navigation, dialogs, up to 20 new elements. View again only when you need more.
+4. Refs go stale when the page re-renders: on \`STALE_REF\`, run \`browser-attach view\` or \`browser-attach find\` again.
+
+## Rules
+- Use the Read/Grep tools on browser-attach's files. Don't pipe or redirect its output (\`| grep\`, \`> file\`), don't prefix environment variables (\`VAR=x browser-attach\`), don't \`cd\` first: each of these triggers a permission prompt.
+- Screenshots only when the text is not enough (icons, charts, canvas, layout, "what does it look like"); \`view\` is cheaper and gives refs. \`browser-attach shot\` writes a JPEG of the viewport and prints its path; Read it to look.
+  \`shot --ref e12\`: just that element. \`shot --full\`: the whole page (stitched, at most 10 screens). \`shot --annotate\`: every visible control boxed with its ref, refs listed below the path; use it for icon-only buttons, then \`browser-attach click <ref>\`.
+  Without annotate, click a point seen in the image with \`browser-attach click --xy X,Y\` in CSS pixels: multiply image pixels by the scale the shot line prints (plus the printed offset for --ref crops).
+- Upload local files: \`browser-attach upload e5 ./report.pdf\`.
+- Subagents share your tabs; give a subagent its own with \`-s <name>\` on every command.
+- \`browser-attach close\` when finished (closes this session's tabs). Errors print \`error CODE: message\` and the next step.
+
+## More
+\`browser-attach help\`, \`browser-attach <command> --help\`. Exit codes: 0 ok, 1 tool error, 2 usage, 3 browser/daemon unavailable, 5 timeout.
+`;
+
+// packages/bridge/dist/cli/setup.js
+import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { dirname as dirname2, join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+var home2 = () => process.env.HOME || process.env.USERPROFILE || homedir3();
+function extensionDir() {
+  if (process.env.BROWSER_ATTACH_EXTENSION_DIR)
+    return process.env.BROWSER_ATTACH_EXTENSION_DIR;
+  if (process.platform === "win32")
+    return join3(process.env.LOCALAPPDATA || join3(home2(), "AppData", "Local"), "browser-attach", "extension");
+  return join3(process.env.XDG_DATA_HOME || join3(home2(), ".local", "share"), "browser-attach", "extension");
+}
+function packagedExtensionDir() {
+  const here = dirname2(fileURLToPath(import.meta.url));
+  return [join3(here, "extension"), join3(here, "..", "..", "..", "extension", "dist")].find((d) => existsSync2(join3(d, "manifest.json")));
+}
+function extensionVersion(dir) {
+  try {
+    return JSON.parse(readFileSync2(join3(dir, "manifest.json"), "utf8")).version;
+  } catch {
+    return void 0;
+  }
+}
+function copyExtension(src, dest) {
+  rmSync(dest, { recursive: true, force: true });
+  mkdirSync2(dest, { recursive: true });
+  cpSync(src, dest, { recursive: true, filter: (p) => !p.endsWith(".map") });
+}
+function permissionRules(platform = process.platform) {
+  const rules = ["Skill(browser-attach)", "Bash(browser-attach:*)", "Read(~/.cache/browser-attach/**)"];
+  if (platform === "win32")
+    rules.push("PowerShell(browser-attach *)");
+  return rules;
+}
+function mergePermissions(path, rules) {
+  let settings = {};
+  const exists = existsSync2(path);
+  if (exists) {
+    const text = readFileSync2(path, "utf8");
+    if (text.trim()) {
+      try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+          throw new Error("not a JSON object");
+        settings = parsed;
+      } catch (e) {
+        return { status: "invalid", added: [], detail: e.message };
+      }
+    }
+  }
+  const perms = settings.permissions;
+  if (perms !== void 0 && (!perms || typeof perms !== "object" || Array.isArray(perms)))
+    return { status: "invalid", added: [], detail: '"permissions" is not an object' };
+  const allow = perms?.allow;
+  if (allow !== void 0 && !Array.isArray(allow))
+    return { status: "invalid", added: [], detail: '"permissions.allow" is not an array' };
+  const current = allow ?? [];
+  const added = rules.filter((r) => !current.includes(r));
+  if (!added.length)
+    return { status: "unchanged", added };
+  settings.permissions = { ...perms, allow: [...current, ...added] };
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, JSON.stringify(settings, null, 2) + "\n");
+  return { status: exists ? "updated" : "created", added };
+}
+
+// packages/bridge/dist/cli/commands.js
+import { createInterface } from "node:readline/promises";
+var CliError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
+var usage = (message) => new CliError("USAGE", message);
+var str = (o, k) => typeof o[k] === "string" ? o[k] : void 0;
+function int(o, k) {
+  const v = str(o, k);
+  if (v === void 0)
+    return void 0;
+  const n2 = Number(v);
+  if (!Number.isFinite(n2))
+    throw usage(`--${k} needs a number, got ${JSON.stringify(v)}`);
+  return n2;
+}
+function arg(args, i, name) {
+  const v = args[i];
+  if (v === void 0)
+    throw usage(`missing <${name}>`);
+  return v;
+}
+function xy(o) {
+  const v = str(o, "xy");
+  if (v === void 0)
+    return void 0;
+  const m = /^\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*$/.exec(v);
+  if (!m)
+    throw usage(`--xy takes X,Y in CSS pixels, got ${JSON.stringify(v)}`);
+  return { x: Number(m[1]), y: Number(m[2]) };
+}
+var tabbed = (ctx, input) => ctx.tab !== void 0 ? { ...input, tabId: ctx.tab } : input;
+var outMode = (o) => o.inline ? "inline" : o.file ? "file" : void 0;
+function target(args, o, verb) {
+  const point = xy(o);
+  if (point)
+    return point;
+  return { ref: arg(args, 0, `ref (or --xy X,Y for ${verb})`) };
+}
+async function viewAfter(ctx, o, tabId) {
+  const v = view(await ctx.call("view", tabId !== void 0 ? { tabId } : tabbed(ctx, {}), outMode(o)));
+  return { lines: v.lines, files: v.file ? [v.file] : [] };
+}
+var MIME = { ".pdf": "application/pdf", ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".txt": "text/plain", ".csv": "text/csv", ".json": "application/json", ".html": "text/html", ".zip": "application/zip", ".doc": "application/msword", ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" };
+var UPLOAD_MAX = 50 * 1024 * 1024;
+var VIEW_OPTS = { inline: { type: "boolean" }, file: { type: "boolean" }, "no-view": { type: "boolean" } };
+var COMMANDS = [
+  // ── page ──
+  {
+    name: "open",
+    group: "page",
+    usage: ["open <url> [--no-view] [--inline|--file]"],
+    summary: "Open a URL in a new tab of this session and print the page.",
+    tool: "navigate",
+    options: VIEW_OPTS,
+    example: "browser-attach open https://example.com",
+    async run(ctx, args, o) {
+      const url = arg(args, 0, "url");
+      const tab = await ctx.call("tabs", { action: "new" });
+      const nav = await ctx.call("navigate", { url, tabId: tab.tabId });
+      const head = change(`open tab ${tab.tabId}`, nav);
+      if (o["no-view"])
+        return { lines: head, result: nav };
+      const v = await viewAfter(ctx, o, tab.tabId);
+      return { ...v, lines: [head[0], ...v.lines], result: nav };
+    }
+  },
+  {
+    name: "goto",
+    group: "page",
+    usage: ["goto <url> [--no-view] [--inline|--file]"],
+    summary: "Navigate the current tab and print the page.",
+    tool: "navigate",
+    options: VIEW_OPTS,
+    async run(ctx, args, o) {
+      const nav = await ctx.call("navigate", tabbed(ctx, { url: arg(args, 0, "url") }));
+      const head = change("goto", nav);
+      if (o["no-view"])
+        return { lines: head, result: nav };
+      const v = await viewAfter(ctx, o);
+      return { ...v, lines: [head[0], ...v.lines], result: nav };
+    }
+  },
+  {
+    name: "back",
+    group: "page",
+    usage: ["back [--no-view]"],
+    summary: "Go back in the tab history and print the page.",
+    options: VIEW_OPTS,
+    async run(ctx, _a, o) {
+      return history(ctx, o, "history.back()", "back");
+    }
+  },
+  {
+    name: "reload",
+    group: "page",
+    usage: ["reload [--no-view]"],
+    summary: "Reload the current tab and print the page.",
+    options: VIEW_OPTS,
+    async run(ctx, _a, o) {
+      return history(ctx, o, "location.reload()", "reload");
+    }
+  },
+  {
+    name: "view",
+    group: "page",
+    usage: ["view [--ref eN] [--inline|--file] [--offset LINE] [--budget CHARS]"],
+    summary: "Read the page: inline when small, else an outline and a file whose lines carry their refs.",
+    tool: "view",
+    options: { ref: { type: "string" }, inline: { type: "boolean" }, file: { type: "boolean" }, offset: { type: "string" }, budget: { type: "string" } },
+    example: "browser-attach view --ref e40",
+    async run(ctx, _a, o) {
+      const r = await ctx.call("view", tabbed(ctx, { ref: str(o, "ref"), offset: int(o, "offset"), budget: int(o, "budget") }), outMode(o));
+      const v = view(r);
+      return { lines: v.lines, files: v.file ? [v.file] : [], result: r };
+    }
+  },
+  {
+    name: "find",
+    group: "page",
+    usage: ["find <text> [--ref eN] [--max N] [-C N]", "find --regex <pattern> [...]"],
+    summary: "Search the page view; matching lines with refs, context and enclosing sections.",
+    tool: "find",
+    options: { regex: { type: "string" }, ref: { type: "string" }, max: { type: "string" }, context: { type: "string", short: "C" } },
+    example: 'browser-attach find "Add to cart"',
+    async run(ctx, args, o) {
+      const regex = str(o, "regex"), text = regex === void 0 ? arg(args, 0, "text") : void 0;
+      const r = await ctx.call("find", tabbed(ctx, { text, regex, ref: str(o, "ref"), maxResults: int(o, "max"), context: int(o, "context") }));
+      const f = find(regex ?? text, r);
+      return { lines: f.lines, files: f.file ? [f.file] : [], result: r, exit: r.matches ? 0 : 1 };
+    }
+  },
+  {
+    name: "shot",
+    group: "page",
+    usage: ["shot [--ref eN] [--full] [--annotate] [--out PATH] [--width N] [--quality Q] [--png]"],
+    summary: "Screenshot to a file (Read it to look): the viewport, one element (--ref) or the whole page (--full); --annotate boxes every visible control with its ref.",
+    tool: "screenshot",
+    options: { ref: { type: "string" }, full: { type: "boolean" }, annotate: { type: "boolean" }, out: { type: "string" }, width: { type: "string" }, quality: { type: "string" }, png: { type: "boolean" } },
+    example: "browser-attach shot --annotate",
+    async run(ctx, _a, o) {
+      const quality = int(o, "quality");
+      const r = await ctx.call("screenshot", tabbed(ctx, {
+        ref: str(o, "ref"),
+        full: o.full ? true : void 0,
+        annotate: o.annotate ? true : void 0,
+        maxWidth: int(o, "width"),
+        // --quality takes 0.1-1 or a percentage.
+        quality: quality === void 0 ? void 0 : quality > 1 ? quality / 100 : quality,
+        format: o.png ? "png" : void 0
+      }));
+      const image = r.image;
+      if (!image?.file)
+        throw new CliError("SCREENSHOT_FAILED", "no screenshot file was written");
+      let path = image.file;
+      const out = str(o, "out");
+      if (out) {
+        path = resolve(out);
+        mkdirSync3(dirname3(path), { recursive: true });
+        copyFileSync(image.file, path);
+      }
+      const s2 = shot(r);
+      return { lines: [s2.lines[0], fileLine(path), ...s2.lines.slice(1)], files: [path], result: r };
+    }
+  },
+  {
+    name: "inspect",
+    group: "page",
+    usage: ["inspect <ref> [field...]"],
+    summary: "Read fields of an element (default: text value role name).",
+    tool: "inspect",
+    async run(ctx, args) {
+      const ref = arg(args, 0, "ref"), fields = args.length > 1 ? args.slice(1) : ["text", "value", "role", "name"];
+      const r = await ctx.call("inspect", tabbed(ctx, { ref, fields }));
+      const values = r.values ?? {};
+      return { lines: [`inspect ${ref}`, ...Object.entries(values).map(([k, v]) => `${k}: ${typeof v === "string" ? JSON.stringify(v.length > 500 ? v.slice(0, 499) + "\u2026" : v) : JSON.stringify(v)}`)], result: r };
+    }
+  },
+  {
+    name: "eval",
+    group: "page",
+    usage: ["eval <expression> [--await]", "eval --file script.js [--await]"],
+    summary: "Evaluate JavaScript in the page; big results go to a file.",
+    tool: "eval_js",
+    options: { await: { type: "boolean" }, file: { type: "string" }, inline: { type: "boolean" } },
+    async run(ctx, args, o) {
+      const file = str(o, "file");
+      const expression = file ? readFileSync3(resolve(file), "utf8") : arg(args, 0, "expression");
+      const r = await ctx.call("eval_js", tabbed(ctx, { expression, awaitPromise: o.await ? true : void 0 }), o.inline ? "inline" : void 0);
+      const e = evalResult(r);
+      return { lines: e.lines, files: e.file ? [e.file] : [], result: r };
+    }
+  },
+  {
+    name: "net",
+    group: "page",
+    usage: ["net [--since MS] [--limit N]"],
+    summary: "Recent fetch/XHR entries of the tab, written to a JSONL file.",
+    tool: "network_log",
+    options: { since: { type: "string" }, limit: { type: "string" } },
+    async run(ctx, _a, o) {
+      const r = await ctx.call("network_log", tabbed(ctx, { sinceMs: int(o, "since"), limit: int(o, "limit") }));
+      const last = (r.last ?? []).map((e) => `  ${e.method ?? ""} ${e.status ?? ""} ${e.url ?? ""}`.trimEnd());
+      return { lines: [`net: ${r.count} entries${last.length ? ", last:" : ""}`, ...last, ...r.file ? [fileLine(r.file)] : []], files: r.file ? [r.file] : [], result: r };
+    }
+  },
+  // ── act ──
+  {
+    name: "click",
+    group: "act",
+    usage: ["click <ref> [--right|--middle] [--double]", "click --xy X,Y"],
+    summary: "Click an element by ref (or a viewport point).",
+    tool: "click",
+    options: { xy: { type: "string" }, right: { type: "boolean" }, middle: { type: "boolean" }, double: { type: "boolean" } },
+    example: "browser-attach click e12",
+    async run(ctx, args, o) {
+      const t = target(args, o, "click");
+      const r = await ctx.call("click", tabbed(ctx, { ...t, button: o.right ? "right" : o.middle ? "middle" : void 0, double: o.double ? true : void 0 }));
+      return { lines: change(`click ${t.ref ?? `${t.x},${t.y}`}`, r), result: r };
+    }
+  },
+  {
+    name: "type",
+    group: "act",
+    usage: ["type <ref> <text> [--clear] [--submit]", "type <ref> --text-file PATH"],
+    summary: "Type into a field.",
+    tool: "type",
+    options: { clear: { type: "boolean" }, submit: { type: "boolean" }, "text-file": { type: "string" } },
+    example: 'browser-attach type e7 "hello world" --submit',
+    async run(ctx, args, o) {
+      const ref = arg(args, 0, "ref"), file = str(o, "text-file");
+      const text = file ? readFileSync3(resolve(file), "utf8") : arg(args, 1, "text");
+      const r = await ctx.call("type", tabbed(ctx, { ref, text, clear: o.clear ? true : void 0, submit: o.submit ? true : void 0 }));
+      return { lines: change(`type ${ref}`, r), result: r };
+    }
+  },
+  {
+    name: "press",
+    group: "act",
+    usage: ["press <key> [--mod ctrl,shift]"],
+    summary: "Press a key (Enter, Tab, ArrowDown, Escape, ...).",
+    tool: "press_key",
+    options: { mod: { type: "string" } },
+    async run(ctx, args, o) {
+      const key = arg(args, 0, "key"), modifiers = str(o, "mod")?.split(",").map((m) => m.trim()).filter(Boolean);
+      const r = await ctx.call("press_key", tabbed(ctx, { key, modifiers }));
+      return { lines: change(`press ${modifiers?.length ? modifiers.join("+") + "+" : ""}${key}`, r), result: r };
+    }
+  },
+  {
+    name: "select",
+    group: "act",
+    usage: ["select <ref> <value>..."],
+    summary: "Pick option(s) of a <select> (values or labels).",
+    tool: "select",
+    options: { xy: { type: "string" } },
+    async run(ctx, args, o) {
+      const point = xy(o), t = point ?? { ref: arg(args, 0, "ref") }, values = point ? args : args.slice(1);
+      if (!values.length)
+        throw usage("missing <value>");
+      const r = await ctx.call("select", tabbed(ctx, { ...t, values }));
+      return { lines: change(`select ${t.ref ?? "point"}`, r), result: r };
+    }
+  },
+  {
+    name: "hover",
+    group: "act",
+    usage: ["hover <ref>", "hover --xy X,Y"],
+    summary: "Hover an element (menus, tooltips).",
+    tool: "hover",
+    options: { xy: { type: "string" } },
+    async run(ctx, args, o) {
+      const t = target(args, o, "hover");
+      const r = await ctx.call("hover", tabbed(ctx, t));
+      return { lines: change(`hover ${t.ref ?? `${t.x},${t.y}`}`, r), result: r };
+    }
+  },
+  {
+    name: "upload",
+    group: "act",
+    usage: ["upload <ref> <path>..."],
+    summary: "Upload local files to an <input type=file>.",
+    tool: "upload_file",
+    options: { xy: { type: "string" } },
+    async run(ctx, args, o) {
+      const point = xy(o), t = point ?? { ref: arg(args, 0, "ref") }, paths = point ? args : args.slice(1);
+      if (!paths.length)
+        throw usage("missing <path>");
+      const files = paths.map((p) => {
+        const path = resolve(p);
+        let data;
+        try {
+          data = readFileSync3(path);
+        } catch (e) {
+          throw new CliError("FILE_NOT_FOUND", `cannot read ${path}: ${e.message}`);
+        }
+        if (data.length > UPLOAD_MAX)
+          throw new CliError("FILE_TOO_LARGE", `${path} is over ${UPLOAD_MAX / 1024 / 1024} MB`);
+        return { name: basename(path), data: data.toString("base64"), mimeType: MIME[extname(path).toLowerCase()] };
+      });
+      const r = await ctx.call("upload_file", tabbed(ctx, { ...t, files }));
+      return { lines: [`upload ok \xB7 ${r.count ?? files.length} file(s): ${(r.names ?? files.map((f) => f.name)).join(", ")}`], result: r };
+    }
+  },
+  {
+    name: "wait",
+    group: "act",
+    usage: ["wait [--text T] [--ref eN] [--url PATTERN] [--request PATTERN] [--ms N]"],
+    summary: "Wait for text, a ref, a URL or a request (plain sleep without a condition).",
+    tool: "wait_for",
+    options: { text: { type: "string" }, ref: { type: "string" }, url: { type: "string" }, request: { type: "string" }, ms: { type: "string" } },
+    async run(ctx, _a, o) {
+      const r = await ctx.call("wait_for", tabbed(ctx, { text: str(o, "text"), refExists: str(o, "ref"), urlPattern: str(o, "url"), requestPattern: str(o, "request"), timeoutMs: int(o, "ms") }));
+      return { lines: [`wait ${r.matched ?? "ok"}${r.elapsedMs !== void 0 ? ` after ${r.elapsedMs} ms` : ""}`], result: r };
+    }
+  },
+  {
+    name: "scroll",
+    group: "act",
+    usage: ["scroll [--dy N] [--dx N] [--y N] [--to eN] [--end]"],
+    summary: "Scroll the page, an element into view, or to the end (lazy loading).",
+    tool: "scroll",
+    options: { dy: { type: "string" }, dx: { type: "string" }, y: { type: "string" }, to: { type: "string" }, end: { type: "boolean" } },
+    async run(ctx, _a, o) {
+      const input = { dy: int(o, "dy") ?? (o.end || str(o, "to") || str(o, "y") || str(o, "dx") ? void 0 : 600), dx: int(o, "dx"), y: int(o, "y"), ref: str(o, "to"), until: o.end ? "page_end" : void 0 };
+      const r = await ctx.call("scroll", tabbed(ctx, input));
+      return { lines: [`scroll ${r.scrolled === false ? "did not move" : "ok"} \xB7 at ${r.scrollX ?? 0},${r.scrollY ?? 0}${r.steps !== void 0 ? ` \xB7 ${r.steps} steps` : ""}${r.stop_reason ? ` \xB7 ${r.stop_reason}` : ""}`], result: r };
+    }
+  },
+  // ── tabs ──
+  {
+    name: "tabs",
+    group: "tabs",
+    usage: ["tabs", "tabs new [url]", "tabs switch <id>", "tabs close [id]"],
+    summary: "List, open, switch or close this session's tabs.",
+    tool: "tabs",
+    async run(ctx, args) {
+      const sub = args[0] ?? "list";
+      if (sub === "list") {
+        const r = await ctx.call("tabs", { action: "list" });
+        return { lines: tabs(r), result: r };
+      }
+      if (sub === "new") {
+        const r = await ctx.call("tabs", { action: "new" });
+        if (!args[1])
+          return { lines: [`tab ${r.tabId} opened (current)`], result: r };
+        const nav = await ctx.call("navigate", { url: args[1], tabId: r.tabId });
+        return { lines: change(`tab ${r.tabId} opened`, nav), result: nav };
+      }
+      const id = sub === "close" && args[1] === void 0 ? void 0 : Number(arg(args, 1, "id"));
+      if (id !== void 0 && !Number.isInteger(id))
+        throw usage(`tab ids are numbers, got ${JSON.stringify(args[1])}`);
+      if (sub === "switch") {
+        const r = await ctx.call("tabs", { action: "switch", tabId: id });
+        return { lines: [`tab ${id} is current`], result: r };
+      }
+      if (sub === "close") {
+        const tabId = id ?? (await ctx.call("tabs", { action: "list" })).active;
+        if (tabId === void 0)
+          throw new CliError("NO_SESSION_TAB", "no current tab to close");
+        const r = await ctx.call("tabs", { action: "close", tabId });
+        return { lines: [`tab ${tabId} closed`], result: r };
+      }
+      throw usage(`unknown tabs action ${JSON.stringify(sub)} (list, new, switch, close)`);
+    }
+  },
+  // ── admin ──
+  {
+    name: "status",
+    group: "admin",
+    usage: ["status"],
+    summary: "Daemon, extension and this session.",
+    async run(ctx) {
+      let st = await ctx.request("status");
+      for (let i = 0; i < 6 && !st.extension.connected; i++) {
+        await new Promise((r) => setTimeout(r, 500));
+        st = await ctx.request("status");
+      }
+      const ext = st.extension, sessions = st.sessions, me = sessions.find((s2) => s2.name === ctx.session);
+      const lines2 = [
+        `daemon pid ${st.pid} \xB7 build ${st.build} \xB7 port ${st.port} \xB7 up ${Math.round(st.uptimeMs / 1e3)} s \xB7 ${sessions.length} session(s), ${st.clients} client(s), ${st.peers} MCP peer(s)`,
+        ext.connected ? `extension connected \xB7 v${ext.version ?? "?"} \xB7 agent protocol ${ext.agentProtocol ?? "none"}${ext.agentProtocol !== ext.expectedAgentProtocol ? ` (expected ${ext.expectedAgentProtocol}: reload the extension)` : ""}` : `extension not connected: open chrome://extensions, enable Developer mode, Load unpacked: ${extensionHint()}`,
+        `session ${ctx.session}: ${me ? `${me.tabs} tab(s), idle ${Math.round(me.idleMs / 1e3)} s${me.uncertain ? ", uncertain (view first)" : ""}` : "not open yet"}`,
+        `files ${st.outDir} \xB7 log ${st.log}`
+      ];
+      return { lines: lines2, result: st };
+    }
+  },
+  {
+    name: "sessions",
+    group: "admin",
+    usage: ["sessions"],
+    summary: "Sessions of the daemon with their tabs and idle time.",
+    async run(ctx) {
+      const list = await ctx.existing("sessions");
+      if (!list)
+        return { lines: ["daemon not running"], result: [] };
+      if (!list.length)
+        return { lines: ["no sessions"], result: list };
+      return { lines: list.map((s2) => `${s2.name === ctx.session ? "*" : " "} ${s2.name} \xB7 ${s2.kind} \xB7 ${s2.tabs} tab(s) \xB7 idle ${Math.round(s2.idleMs / 1e3)} s${s2.busy ? " \xB7 busy" : ""}${s2.queued ? ` \xB7 ${s2.queued} queued` : ""}`), result: list };
+    }
+  },
+  {
+    name: "close",
+    group: "admin",
+    usage: ["close [--all]"],
+    summary: "End this session (or all): close its tabs, delete its files.",
+    options: { all: { type: "boolean" } },
+    async run(ctx, _a, o) {
+      const r = await ctx.existing("session.close", o.all ? { all: true } : { name: ctx.session });
+      if (!r)
+        return { lines: ["daemon not running: nothing to close"], result: { closed: [] } };
+      return { lines: [r.closed.length ? `closed ${r.closed.join(", ")}` : `no session ${ctx.session}`], result: r };
+    }
+  },
+  {
+    name: "daemon",
+    group: "admin",
+    usage: ["daemon start|stop|restart|status", "daemon stop [--force] [--close-tabs]", "daemon logs [-n LINES]"],
+    summary: "Manage the background daemon (normally started automatically).",
+    options: { force: { type: "boolean" }, "close-tabs": { type: "boolean" }, lines: { type: "string", short: "n" } },
+    async run(ctx, args, o) {
+      const sub = args[0] ?? "status";
+      if (sub === "start") {
+        const h = await ctx.startDaemon();
+        return { lines: [`daemon running \xB7 pid ${h.pid} \xB7 build ${h.build} \xB7 port ${h.port}`], result: h };
+      }
+      if (sub === "stop" || sub === "restart") {
+        const stopped = await ctx.stopDaemon({ force: !!o.force, closeTabs: !!o["close-tabs"] });
+        if (sub === "stop")
+          return { lines: [stopped ? "daemon stopped" : "daemon not running"], result: { stopped } };
+        const h = await ctx.startDaemon();
+        return { lines: [`daemon restarted \xB7 pid ${h.pid} \xB7 build ${h.build}`], result: h };
+      }
+      if (sub === "status")
+        return COMMANDS.find((c) => c.name === "status").run(ctx, [], o);
+      if (sub === "logs") {
+        let text = "";
+        try {
+          text = readFileSync3(logPath(ctx.port), "utf8");
+        } catch {
+          return { lines: [`no log yet (${logPath(ctx.port)})`] };
+        }
+        const n2 = Math.max(1, Number(str(o, "lines") ?? 50) || 50);
+        return { lines: [...text.trimEnd().split("\n").slice(-n2), fileLine(logPath(ctx.port))], files: [logPath(ctx.port)] };
+      }
+      throw usage(`unknown daemon action ${JSON.stringify(sub)}`);
+    }
+  },
+  {
+    name: "config",
+    group: "admin",
+    usage: ["config show", "config set KEY=VALUE...", "config unset KEY..."],
+    summary: "Daemon configuration settings (idleExitMs, sessionTtlMs, outMaxMB).",
+    async run(ctx, args) {
+      const sub = args[0] ?? "show";
+      migrateLegacyConfig();
+      if (sub === "show")
+        return { lines: [`${configPath()}:`, JSON.stringify(readConfig(), null, 2)], result: readConfig() };
+      if (sub !== "set" && sub !== "unset")
+        throw usage(`unknown config action ${JSON.stringify(sub)}`);
+      if (args.length < 2)
+        throw usage(`config ${sub} needs at least one ${sub === "set" ? "KEY=VALUE" : "KEY"}`);
+      let c = readConfig();
+      try {
+        for (const a of args.slice(1))
+          c = setConfig(c, sub === "set" ? a : `${a}=`);
+      } catch (e) {
+        throw usage(e.message);
+      }
+      if (sub === "unset")
+        for (const a of args.slice(1))
+          delete c[a];
+      writeConfig(c);
+      const reloaded = await ctx.existing("config.reload").catch(() => null);
+      const keys = args.slice(1).map((a) => a.split("=")[0]);
+      return { lines: [`${sub === "set" ? "set" : "unset"} ${keys.join(", ")} in ${configPath()}${reloaded ? " (daemon reloaded)" : ""}`], result: { keys } };
+    }
+  },
+  {
+    name: "extension",
+    group: "admin",
+    usage: ["extension path"],
+    summary: "Folder to load in chrome://extensions (Load unpacked).",
+    async run(_ctx, args) {
+      const sub = args[0] ?? "path";
+      if (sub !== "path")
+        throw usage(`unknown extension action ${JSON.stringify(sub)}`);
+      const dir = extensionDir();
+      if (!existsSync3(join4(dir, "manifest.json")))
+        return { lines: [`${dir} (not installed yet: run browser-attach setup)`], files: [dir], result: { path: dir, installed: false }, exit: 1 };
+      return { lines: [dir], files: [dir], result: { path: dir, installed: true, version: extensionVersion(dir) } };
+    }
+  },
+  {
+    name: "setup",
+    group: "admin",
+    usage: ["setup [--yes] [--no-permissions] [--claude-dir DIR]"],
+    summary: "One-time, repeatable setup: skill, extension folder, Claude Code permissions.",
+    options: { yes: { type: "boolean", short: "y" }, "no-permissions": { type: "boolean" }, "claude-dir": { type: "string" } },
+    async run(_ctx, _a, o) {
+      const user = process.env.HOME || process.env.USERPROFILE || homedir4();
+      const claudeDir = str(o, "claude-dir") ? resolve(str(o, "claude-dir")) : join4(user, ".claude");
+      const lines2 = [];
+      let failed = false;
+      const step = (label, fn) => {
+        try {
+          lines2.push(`ok    ${label}: ${fn()}`);
+        } catch (e) {
+          failed = true;
+          lines2.push(`FAIL  ${label}: ${e.message}`);
+        }
+      };
+      step("skill", () => {
+        const dirs = [join4(claudeDir, "skills", "browser-attach"), join4(user, ".agents", "skills", "browser-attach")];
+        for (const d of dirs)
+          writeSkill(d);
+        return dirs.map((d) => join4(d, "SKILL.md")).join(", ");
+      });
+      step("extension", () => {
+        const src = packagedExtensionDir(), dest = extensionDir();
+        if (!src)
+          throw new Error("this install has no packaged extension (source checkout without a build: npm run build)");
+        copyExtension(src, dest);
+        return `v${extensionVersion(dest) ?? "?"} copied to ${dest}`;
+      });
+      if (o["no-permissions"])
+        lines2.push("skip  permissions: --no-permissions");
+      else {
+        const path = join4(claudeDir, "settings.json"), rules = permissionRules();
+        if (!o.yes && process.stdin.isTTY && !await confirm(`Add ${rules.length} allow rules to ${path}?`))
+          lines2.push("skip  permissions: declined");
+        else
+          step("permissions", () => {
+            const r = mergePermissions(path, rules);
+            if (r.status === "invalid") {
+              failed = true;
+              return `${path} not changed (${r.detail}); add by hand to permissions.allow: ${rules.join(", ")}`;
+            }
+            return r.status === "unchanged" ? `already in ${path}` : `${r.status} ${path} (+${r.added.length})`;
+          });
+      }
+      const dir = extensionDir();
+      lines2.push("", "Next:", "  1. Open chrome://extensions and turn on Developer mode (top right).", `  2. Load unpacked, pick this folder: ${dir}`, "     (after upgrading browser-attach, run setup again, then press Reload on the extension card)", '  3. Optional: on the extension card, turn on "Allow User Scripts" (eval_js on strict-CSP pages).', "  4. Run: browser-attach status");
+      return { lines: lines2, files: [dir], result: { extension: dir, failed }, exit: failed ? 1 : 0 };
+    }
+  },
+  {
+    name: "skill",
+    group: "admin",
+    usage: ["skill install [--dir DIR]", "skill path", "skill show"],
+    summary: "Install the Claude Code skill (~/.claude/skills/browser-attach/SKILL.md).",
+    options: { dir: { type: "string" } },
+    async run(_ctx, args, o) {
+      const sub = args[0] ?? "path";
+      const dir = str(o, "dir") ? resolve(str(o, "dir")) : join4(process.env.HOME || homedir4(), ".claude", "skills", "browser-attach");
+      const path = join4(dir, "SKILL.md");
+      if (sub === "show")
+        return { lines: [SKILL.trimEnd()] };
+      if (sub === "path")
+        return { lines: [existsSync3(path) ? path : `${path} (not installed: browser-attach skill install)`], files: [path] };
+      if (sub === "install") {
+        writeSkill(dir);
+        return { lines: [`skill installed`, fileLine(path), 'Allow the skill, the CLI and its files once in ~/.claude/settings.json: permissions.allow += "Skill(browser-attach)", "Bash(browser-attach:*)", "Read(~/.cache/browser-attach/**)"'], files: [path] };
+      }
+      throw usage(`unknown skill action ${JSON.stringify(sub)}`);
+    }
+  }
+];
+function writeSkill(dir) {
+  mkdirSync3(dir, { recursive: true });
+  writeFileSync3(join4(dir, "SKILL.md"), SKILL);
+}
+function extensionHint() {
+  const dir = extensionDir();
+  return existsSync3(join4(dir, "manifest.json")) ? dir : `${dir} (not installed yet: run browser-attach setup)`;
+}
+async function confirm(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return !/^n/i.test((await rl.question(`${question} [Y/n] `)).trim());
+  } finally {
+    rl.close();
+  }
+}
+async function history(ctx, o, expression, verb) {
+  await ctx.call("eval_js", tabbed(ctx, { expression: `setTimeout(() => ${expression}, 0), true` }));
+  await ctx.call("wait_for", tabbed(ctx, { timeoutMs: 1200 }));
+  if (o["no-view"])
+    return { lines: [`${verb} ok`] };
+  const v = await viewAfter(ctx, o);
+  return { ...v, lines: [`${verb} ok`, ...v.lines] };
+}
+var commandNamed = (name) => COMMANDS.find((c) => c.name === name);
+var toolDescription = (c) => c.tool ? Descriptions[c.tool] : void 0;
+
+// packages/bridge/dist/daemon/client.js
+import { spawn } from "node:child_process";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, openSync, closeSync } from "node:fs";
+import { dirname as dirname5, join as join6 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+
+// packages/bridge/dist/daemon/rpc.js
+import { connect } from "node:net";
+var RpcFailure = class extends Error {
+  code;
+  short_term;
+  constructor(code, message, short_term = true) {
+    super(message);
+    this.code = code;
+    this.short_term = short_term;
+  }
+};
+function lines(socket, onLine) {
+  let buffer = "";
+  socket.setEncoding("utf8");
+  socket.on("data", (chunk) => {
+    buffer += chunk;
+    for (let i = buffer.indexOf("\n"); i >= 0; i = buffer.indexOf("\n")) {
+      const line = buffer.slice(0, i);
+      buffer = buffer.slice(i + 1);
+      if (!line.trim())
+        continue;
+      let value;
+      try {
+        value = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      onLine(value);
+    }
+  });
+}
+var RpcClient = class _RpcClient {
+  socket;
+  next = 1;
+  pending = /* @__PURE__ */ new Map();
+  closed = false;
+  constructor(socket) {
+    this.socket = socket;
+    lines(socket, (value) => {
+      const r = value;
+      const p = this.pending.get(r.id);
+      if (!p)
+        return;
+      this.pending.delete(r.id);
+      if (r.ok)
+        p.resolve(r.result);
+      else
+        p.reject(new RpcFailure(r.error.code, r.error.message, r.error.short_term));
+    });
+    socket.on("close", () => {
+      this.closed = true;
+      for (const [id, p] of this.pending) {
+        this.pending.delete(id);
+        p.reject(new RpcFailure("DAEMON_EXITED", "The daemon exited during the call; the action may or may not have run. Check the page with view."));
+      }
+    });
+    socket.on("error", () => {
+    });
+  }
+  /** Connects to `path`; rejects with the socket error (ENOENT, ECONNREFUSED). */
+  static connect(path, timeoutMs = 2e3) {
+    return new Promise((resolve2, reject) => {
+      const socket = connect(path);
+      const timer = setTimeout(() => {
+        socket.destroy();
+        reject(Object.assign(new Error("connect timeout"), { code: "ETIMEDOUT" }));
+      }, timeoutMs);
+      socket.once("connect", () => {
+        clearTimeout(timer);
+        resolve2(new _RpcClient(socket));
+      });
+      socket.once("error", (e) => {
+        clearTimeout(timer);
+        reject(e);
+      });
+    });
+  }
+  get isClosed() {
+    return this.closed;
+  }
+  request(method, params = {}) {
+    if (this.closed)
+      return Promise.reject(new RpcFailure("DAEMON_EXITED", "The daemon connection is closed."));
+    const id = this.next++;
+    return new Promise((resolve2, reject) => {
+      this.pending.set(id, { resolve: resolve2, reject });
+      this.socket.write(JSON.stringify({ id, method, params }) + "\n");
+    });
+  }
+  close() {
+    this.socket.end();
+    this.socket.destroySoon?.();
+  }
+};
+
+// packages/bridge/dist/daemon/version.js
+import { readFileSync as readFileSync4 } from "node:fs";
+import { dirname as dirname4, join as join5 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var DAEMON_RPC = 1;
+var cached;
+function buildInfo() {
+  if (cached)
+    return cached;
+  if (process.env.BROWSER_ATTACH_BUILD_ID)
+    return cached = { build: process.env.BROWSER_ATTACH_BUILD_ID, version: "0.0.0" };
+  const here = dirname4(fileURLToPath2(import.meta.url));
+  for (const path of [join5(here, "build.json"), join5(here, "..", "build.json")]) {
+    try {
+      const b = JSON.parse(readFileSync4(path, "utf8"));
+      if (typeof b.build === "string")
+        return cached = { build: b.build, version: typeof b.version === "string" ? b.version : "0.0.0" };
+    } catch {
+    }
+  }
+  return cached = { build: "dev", version: "0.0.0" };
+}
+
+// packages/bridge/dist/daemon/port.js
+import { execFileSync } from "node:child_process";
+import { readFileSync as readFileSync5, readdirSync, readlinkSync } from "node:fs";
+function windowsListeningPid(port) {
+  let text = "";
+  try {
+    text = execFileSync("netstat", ["-ano", "-p", "TCP"], { encoding: "utf8", timeout: 5e3, windowsHide: true });
+  } catch {
+    return null;
+  }
+  for (const row of text.split("\n")) {
+    const f = row.trim().split(/\s+/);
+    if (f[0] === "TCP" && f[1]?.endsWith(`:${port}`) && f[3] === "LISTENING" && /^\d+$/.test(f[4] ?? ""))
+      return Number(f[4]);
+  }
+  return null;
+}
+function listeningPid(port) {
+  if (process.platform === "win32")
+    return windowsListeningPid(port);
+  const hex = port.toString(16).toUpperCase().padStart(4, "0");
+  const inodes = /* @__PURE__ */ new Set();
+  for (const table of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+    let text = "";
+    try {
+      text = readFileSync5(table, "utf8");
+    } catch {
+      continue;
+    }
+    for (const row of text.split("\n").slice(1)) {
+      const f = row.trim().split(/\s+/);
+      if (f[1]?.endsWith(`:${hex}`) && f[3] === "0A" && f[9])
+        inodes.add(f[9]);
+    }
+  }
+  if (!inodes.size)
+    return null;
+  let pids = [];
+  try {
+    pids = readdirSync("/proc").filter((p) => /^\d+$/.test(p));
+  } catch {
+    return null;
+  }
+  for (const pid of pids) {
+    let fds = [];
+    try {
+      fds = readdirSync(`/proc/${pid}/fd`);
+    } catch {
+      continue;
+    }
+    for (const fd of fds) {
+      try {
+        const m = /^socket:\[(\d+)\]$/.exec(readlinkSync(`/proc/${pid}/fd/${fd}`));
+        if (m && inodes.has(m[1]))
+          return Number(pid);
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+function commandOf(pid) {
+  if (process.platform === "win32") {
+    try {
+      return /^"([^"]+)"/.exec(execFileSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], { encoding: "utf8", timeout: 5e3, windowsHide: true }).trim())?.[1] ?? "";
+    } catch {
+      return "";
+    }
+  }
+  try {
+    return readFileSync5(`/proc/${pid}/cmdline`, "utf8").split("\0").filter(Boolean).join(" ").slice(0, 200);
+  } catch {
+    return "";
+  }
+}
+
+// packages/bridge/dist/daemon/client.js
+var EXIT_PORT_IN_USE = 10;
+var delay = (ms) => new Promise((r) => setTimeout(r, ms));
+function daemonEntry() {
+  if (process.env.BROWSER_ATTACH_DAEMON_ENTRY)
+    return process.env.BROWSER_ATTACH_DAEMON_ENTRY;
+  const here = dirname5(fileURLToPath3(import.meta.url));
+  for (const path of [join6(here, "bridge.mjs"), join6(here, "..", "index.js")])
+    if (existsSync4(path))
+      return path;
+  throw new RpcFailure("NO_DAEMON_ENTRY", `Cannot find the daemon script next to ${here}; set BROWSER_ATTACH_DAEMON_ENTRY.`, false);
+}
+async function tryConnect(port) {
+  try {
+    return await RpcClient.connect(socketPath(port));
+  } catch (e) {
+    const code = e.code;
+    if (code === "ENOENT" || code === "ECONNREFUSED" || code === "ETIMEDOUT")
+      return null;
+    throw e;
+  }
+}
+async function startDaemon(port, timeoutMs) {
+  mkdirSync4(runtimeDir(), { recursive: true, mode: 448 });
+  mkdirSync4(cacheDir(), { recursive: true, mode: 448 });
+  const out = openSync(logPath(port), "a", 384);
+  let exit = null;
+  try {
+    const child = spawn(process.execPath, [daemonEntry(), "daemon", "--port", String(port)], { detached: true, stdio: ["ignore", out, out], env: process.env });
+    child.on("exit", (code) => {
+      exit = code ?? -1;
+    });
+    child.unref();
+  } finally {
+    closeSync(out);
+  }
+  const deadline = Date.now() + timeoutMs;
+  let lostRace = 0;
+  while (Date.now() < deadline) {
+    await delay(100);
+    const c = await tryConnect(port);
+    if (c)
+      return c;
+    if (exit === EXIT_PORT_IN_USE) {
+      if (++lostRace > 15)
+        break;
+    } else if (exit !== null)
+      throw new RpcFailure("DAEMON_START_FAILED", `The daemon exited with code ${exit} while starting; see ${logPath(port)}.`, false);
+  }
+  if (exit === EXIT_PORT_IN_USE || await tryConnect(port) === null && listeningPid(port))
+    throw portInUse(port);
+  throw new RpcFailure("DAEMON_START_FAILED", `The daemon did not open its socket within ${Math.round(timeoutMs / 1e3)} s; see ${logPath(port)}.`, false);
+}
+function portInUse(port) {
+  const pid = listeningPid(port);
+  const who = pid ? `pid ${pid}${commandOf(pid) ? ` (${commandOf(pid)})` : ""}` : "another process";
+  const ours = !!pid && /browser-attach|bridge\.mjs/.test(commandOf(pid));
+  const hint = ours ? "That is another browser-attach daemon (a different install or user); stop it with `browser-attach daemon stop` there, then retry." : "If browser-attach runs on the other side of WSL/Windows, its daemon holds the port: the Chrome extension connects to one daemon only, so use browser-attach there or stop it with `browser-attach daemon stop`. Otherwise stop the program that holds it.";
+  return new RpcFailure("PORT_IN_USE", `Port ${port} is held by ${who}. ${hint}`, false);
+}
+async function waitGone(port, timeoutMs = 5e3) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const c = await tryConnect(port);
+    if (!c)
+      return;
+    c.close();
+    await delay(100);
+  }
+}
+async function ensureDaemon(opts) {
+  const { build, version } = buildInfo();
+  const helloParams = { client: opts.client, version, build, rpc: DAEMON_RPC, session: opts.session, persistent: opts.persistent ?? true, cwd: process.cwd(), caller: { pid: process.ppid } };
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const rpc = await tryConnect(opts.port) ?? await startDaemon(opts.port, opts.startTimeoutMs ?? 5e3);
+    let hello;
+    try {
+      hello = await rpc.request("hello", helloParams);
+    } catch (e) {
+      if (!(e instanceof RpcFailure && e.code === "RPC_MISMATCH")) {
+        rpc.close();
+        throw e;
+      }
+      const st = await rpc.request("status").catch(() => ({ busy: true }));
+      if (st.busy) {
+        rpc.close();
+        throw new RpcFailure("DAEMON_OUTDATED", "The running daemon is of an incompatible version and busy. Run `browser-attach daemon restart --force` (running tasks are lost).", false);
+      }
+      await rpc.request("shutdown", { restart: true }).catch(() => {
+      });
+      rpc.close();
+      await waitGone(opts.port);
+      opts.note?.("note: restarted an incompatible daemon");
+      continue;
+    }
+    if (hello.build === build || build === "dev" || attempt > 0)
+      return { rpc, hello };
+    if (hello.busy) {
+      opts.note?.(`note: the daemon is build ${hello.build}, this client ${build}; it restarts when idle (browser-attach daemon restart)`);
+      return { rpc, hello };
+    }
+    await rpc.request("shutdown", { restart: true }).catch(() => {
+    });
+    rpc.close();
+    await waitGone(opts.port);
+    opts.note?.(`note: restarted the daemon (build ${hello.build} -> ${build})`);
+  }
+  throw new RpcFailure("DAEMON_START_FAILED", "Could not reach a daemon.", false);
+}
+var connectExisting = tryConnect;
+
+// packages/bridge/dist/cli/main.js
+var DEFAULT_PORT = 17329;
+var GLOBAL = {
+  session: { type: "string", short: "s" },
+  tab: { type: "string", short: "t" },
+  json: { type: "boolean" },
+  quiet: { type: "boolean", short: "q" },
+  port: { type: "string" },
+  help: { type: "boolean", short: "h" }
+};
+var TAKES_VALUE = /* @__PURE__ */ new Set(["-s", "--session", "-t", "--tab", "--port"]);
+function resolveSession(flag, env2 = process.env) {
+  if (flag)
+    return flag;
+  if (env2.BROWSER_ATTACH_SESSION)
+    return env2.BROWSER_ATTACH_SESSION;
+  const cc = env2.CLAUDE_CODE_SESSION_ID?.replace(/[^A-Za-z0-9]/g, "");
+  if (cc)
+    return `cc-${cc.slice(0, 8)}`;
+  return "default";
+}
+function commandIndex(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--")
+      return i + 1 < argv.length ? i + 1 : -1;
+    if (TAKES_VALUE.has(a)) {
+      i++;
+      continue;
+    }
+    if (!a.startsWith("-") || a === "-")
+      return i;
+  }
+  return -1;
+}
+async function main(argv, io = { out: (s2) => {
+  process.stdout.write(s2 + "\n");
+}, err: (s2) => {
+  process.stderr.write(s2 + "\n");
+} }) {
+  const at = commandIndex(argv);
+  const name = at >= 0 ? argv[at] : void 0;
+  if (!name || name === "help") {
+    const topic = name === "help" ? argv[at + 1] : void 0;
+    const cmd2 = topic ? commandNamed(topic) : void 0;
+    if (topic && !cmd2) {
+      io.err(`error USAGE: no command ${topic}`);
+      return 2;
+    }
+    io.out(cmd2 ? commandHelp(cmd2) : overview());
+    return name || argv.some((a) => a === "-h" || a === "--help") ? 0 : 2;
+  }
+  const cmd = commandNamed(name);
+  if (!cmd) {
+    io.err(`error USAGE: unknown command ${JSON.stringify(name)}. Commands: ${COMMANDS.map((c) => c.name).join(", ")} (browser-attach help)`);
+    return 2;
+  }
+  let values, positionals;
+  try {
+    const parsed = parseArgs({ args: [...argv.slice(0, at), ...argv.slice(at + 1)], options: { ...GLOBAL, ...cmd.options }, allowPositionals: true, strict: true });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (e) {
+    io.err(`error USAGE: ${e.message.replace(/\. To specify a positional argument.*$/s, "")}`);
+    io.err(`usage: ${cmd.usage.map((u) => `browser-attach ${u}`).join("\n       ")}`);
+    return 2;
+  }
+  if (values.help) {
+    io.out(commandHelp(cmd));
+    return 0;
+  }
+  const portText = values.port ?? process.env.BROWSER_ATTACH_PORT ?? process.env.BROWSER_ATTACH_PORT;
+  const port = portText === void 0 ? DEFAULT_PORT : Number(portText);
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    io.err(`error USAGE: invalid port ${portText}`);
+    return 2;
+  }
+  const session = resolveSession(values.session);
+  if (!SESSION_NAME.test(session)) {
+    io.err(`error USAGE: invalid session name ${JSON.stringify(session)} (A-Z a-z 0-9 . _ -, up to 64)`);
+    return 2;
+  }
+  let tab;
+  if (values.tab !== void 0) {
+    tab = Number(values.tab);
+    if (!Number.isInteger(tab)) {
+      io.err(`error USAGE: -t takes a tab id, got ${JSON.stringify(values.tab)}`);
+      return 2;
+    }
+  }
+  let rpc = null, hello = null;
+  const note = (line) => {
+    if (!values.json && !values.quiet)
+      io.err(line);
+  };
+  const connect2 = async () => {
+    if (rpc && !rpc.isClosed)
+      return rpc;
+    const r = await ensureDaemon({ port, client: "cli", session, note });
+    rpc = r.rpc;
+    hello = r.hello;
+    if (!hello.extension.connected)
+      note("waiting for the Chrome extension to connect\u2026");
+    return rpc;
+  };
+  const ctx = {
+    port,
+    session,
+    tab,
+    call: async (tool, input, out) => (await connect2()).request("call", { tool, input: clean(input), ...out ? { out } : {} }),
+    request: async (method, params = {}) => (await connect2()).request(method, params),
+    async existing(method, params = {}) {
+      const c = await connectExisting(port);
+      if (!c)
+        return null;
+      try {
+        await c.request("hello", { client: "cli", rpc: DAEMON_RPC }).catch(() => {
+        });
+        return await c.request(method, params);
+      } finally {
+        c.close();
+      }
+    },
+    async stopDaemon(params) {
+      const c = await connectExisting(port);
+      if (!c)
+        return false;
+      try {
+        await c.request("shutdown", params);
+      } finally {
+        c.close();
+      }
+      for (let i = 0; i < 50 && await isRunning(port); i++)
+        await new Promise((r) => setTimeout(r, 100));
+      return true;
+    },
+    async startDaemon() {
+      await connect2();
+      return hello;
+    }
+  };
+  try {
+    const output = await cmd.run(ctx, positionals, values);
+    print(output, values, io);
+    return output.exit ?? 0;
+  } catch (e) {
+    const code = e instanceof CliError || e instanceof RpcFailure ? e.code : typeof e.code === "string" ? e.code : "INTERNAL";
+    const message = e instanceof Error ? e.message : String(e);
+    if (values.json)
+      io.out(JSON.stringify({ ok: false, error: { code, message } }));
+    else {
+      io.err(`error ${code}: ${message}`);
+      if (code === "USAGE")
+        io.err(`usage: ${cmd.usage.map((u) => `browser-attach ${u}`).join("\n       ")}`);
+      else if (nextStep(code))
+        io.err(`next: ${nextStep(code)}`);
+    }
+    return exitCode(code);
+  } finally {
+    rpc?.close();
+  }
+}
+async function isRunning(port) {
+  const c = await connectExisting(port);
+  c?.close();
+  return !!c;
+}
+var clean = (input) => Object.fromEntries(Object.entries(input).filter(([, v]) => v !== void 0));
+function print(output, values, io) {
+  if (values.json) {
+    io.out(JSON.stringify({ ok: true, summary: output.lines[0] ?? "", ...output.files?.length ? { file: output.files[0], files: output.files } : {}, result: output.result ?? null }));
+    return;
+  }
+  if (values.quiet) {
+    io.out(output.files?.[0] ?? output.lines[0] ?? "");
+    return;
+  }
+  for (const line of output.lines)
+    io.out(line);
+}
+var GROUPS = [["page", "Page"], ["act", "Act"], ["tabs", "Tabs"], ["admin", "Admin"]];
+function overview() {
+  const width = Math.max(...COMMANDS.map((c) => c.name.length));
+  const lines2 = [
+    "browser-attach \u2014 drive the user's Chrome (via the extension) from the shell.",
+    "usage: browser-attach [-s SESSION] [-t TAB] [--json] [--quiet] <command> [args]   (browser-attach <command> --help)",
+    ""
+  ];
+  for (const [group, title] of GROUPS) {
+    lines2.push(`${title}:`);
+    for (const c of COMMANDS.filter((x) => x.group === group))
+      lines2.push(`  ${c.name.padEnd(width)}  ${c.summary}`);
+  }
+  lines2.push("", 'Output: a summary line, a few lines, and file paths after "\u2192 " (read them with the Read/Grep tools; every control line carries its [ref]).', 'Session: -s NAME, else $BROWSER_ATTACH_SESSION, else one per Claude Code session, else "default". Each session sees only its own tabs.', "Exit codes: 0 ok, 1 tool error, 2 usage, 3 browser/daemon unavailable, 5 timeout.");
+  if (process.env.CLAUDECODE) {
+    const skill = join7(process.env.HOME || homedir5(), ".claude", "skills", "browser-attach", "SKILL.md");
+    lines2.push(`Agent skill: ${existsSync5(skill) ? skill : "not installed (browser-attach skill install)"}`);
+  }
+  return lines2.join("\n");
+}
+function commandHelp(c) {
+  const lines2 = c.usage.map((u, i) => `${i ? "       " : "usage: "}browser-attach ${u}`);
+  lines2.push("", c.summary);
+  const tool = toolDescription(c);
+  if (tool)
+    lines2.push("", `(${c.tool}) ${tool}`);
+  if (c.example)
+    lines2.push("", `example: ${c.example}`);
+  lines2.push("", "global: -s SESSION, -t TAB (a tab of this session; default: current), --json, --quiet, --port N");
+  return lines2.join("\n");
+}
+
+// packages/bridge/dist/cli/bin.js
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}, (e) => {
+  process.stderr.write(`error INTERNAL: ${e instanceof Error ? e.stack ?? e.message : String(e)}
+`);
+  process.exitCode = 1;
+});