chrome-relay 0.7.1 → 0.7.2

package/dist/cli.js

@@ -445,6 +445,9 @@ function parseChromeSnapshotArgs(input) {
   const diff = optBool(obj, "diff", TOOL_NAMES.SNAPSHOT);
   if (diff !== void 0)
     out.diff = diff;
+  const elide = optBool(obj, "elide", TOOL_NAMES.SNAPSHOT);
+  if (elide !== void 0)
+    out.elide = elide;
   return out;
 }
 function parseChromeScreenshotArgs(input) {
@@ -585,16 +588,19 @@ function parseChromeNetworkArgs(input) {
   if (action === "har") {
     const withBodies = optBool(obj, "withBodies");
     const bestEffortBodies = optBool(obj, "bestEffortBodies");
+    const rawHeadersHar = optBool(obj, "rawHeaders");
     return {
       ...target,
       action: "har",
       ...withBodies !== void 0 ? { withBodies } : {},
       ...bestEffortBodies !== void 0 ? { bestEffortBodies } : {},
+      ...rawHeadersHar !== void 0 ? { rawHeaders: rawHeadersHar } : {},
       ...parseFilter(obj)
     };
   }
   if (action === "read") {
-    return { ...target, action: "read", ...parseFilter(obj) };
+    const rawHeaders = optBool(obj, "rawHeaders");
+    return { ...target, action: "read", ...rawHeaders !== void 0 ? { rawHeaders } : {}, ...parseFilter(obj) };
   }
   throw new RelayError({
     code: "invalid_arguments",
@@ -1419,7 +1425,7 @@ var init_dist = __esm({
 import { Command } from "commander";
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.7.1" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.7.2" : "0.0.0-dev";
 
 // src/commands/shared.ts
 init_dist();
@@ -1836,15 +1842,20 @@ async function runDoctor() {
       console.log(`Tip: run "chrome-relay install" to refresh manifests for every detected browser.`);
     }
     let serverReachable = false;
+    let connected = {};
     try {
       const response = await fetch(`http://127.0.0.1:${DEFAULT_HTTP_PORT}/ping`);
       serverReachable = response.ok;
+      if (response.ok) connected = await response.json();
     } catch {
       serverReachable = false;
     }
     console.log(`Allowed extension IDs: ${formatKnownExtensionIds()}`);
     console.log(`Local bridge reachable: ${serverReachable ? "yes" : "no"}`);
-    if (!serverReachable) {
+    if (serverReachable) {
+      const flavor = connected.extensionId === CHROME_WEB_STORE_EXTENSION_ID ? "Chrome Web Store" : connected.extensionId === LOCAL_UNPACKED_EXTENSION_ID ? "local unpacked (dev)" : connected.extensionId === LEGACY_DEV_EXTENSION_ID ? "legacy dev" : connected.extensionId ? "unknown id" : "id not reported (pre-0.8 host still running \u2014 restart Chrome or run chrome-relay update)";
+      console.log(`Connected extension: ${connected.extensionVersion ?? "?"} \u2014 ${flavor}${connected.extensionId ? ` (${connected.extensionId})` : ""}`);
+    } else {
       console.log(`Tip: load the extension in one of the detected browsers so it can launch the native host.`);
     }
     return allHealthy;
@@ -1856,6 +1867,11 @@ async function runDoctor() {
 
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.7.2": [
+    "Fix (Windows): `chrome-relay update` now resolves the installed binary with `where` (Windows has no `which`), picks the spawnable `.cmd`/`.exe` over the extensionless npm shim, and re-execs it through a shell with the path quoted. Pre-0.7.2 the `which` call always failed on Windows, so update skipped the post-install manifest refresh and re-fired the cli-outdated nudge \u2014 the same loop fixed on macOS/Linux in 0.5.21, now closed on Windows too.",
+    "Fix (Windows): `screencast stop --gif/--mp4` detected ffmpeg with `which`, which doesn't exist on Windows, so the stitch step failed with `external_dependency_missing` even when ffmpeg was on PATH. Now uses `where` on win32. No change to the macOS/Linux path.",
+    "No extension change. Both fixes are CLI-only; existing 0.7.x extensions work unchanged."
+  ],
   "0.7.1": [
     "Fix: `wait` failed with `invalid_arguments: got 0 conditions` when invoked through the CLI. Root cause: the CLI transmitted the PARSED tool args over the bridge, and chrome_wait's parser transforms its shape ({selector} -> {condition}), so the extension re-parsed a shape it doesn't accept. The CLI now validates locally but transmits raw args \u2014 parsers run on the same raw shape at both ends, as designed. No extension change needed; 0.7.0 extensions work."
   ],
@@ -2051,6 +2067,23 @@ function listReleaseNotesSince(since) {
 }
 
 // src/commands/install-update.ts
+function whichBinary(spawnSync2, name) {
+  const tool = process.platform === "win32" ? "where" : "which";
+  const res = spawnSync2(tool, [name]);
+  if (res.status !== 0) return null;
+  const lines = (res.stdout?.toString() ?? "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  if (lines.length === 0) return null;
+  if (process.platform === "win32") {
+    return lines.find((l) => /\.(cmd|bat|exe)$/i.test(l)) ?? lines[0];
+  }
+  return lines[0];
+}
+function spawnCli(spawnSync2, bin, args, opts = {}) {
+  if (process.platform === "win32") {
+    return spawnSync2(`"${bin}"`, args, { ...opts, shell: true });
+  }
+  return spawnSync2(bin, args, opts);
+}
 function registerInstallUpdate(program) {
   program.command("install").description("Install and register the local Chrome Relay host.").action(async () => {
     await runInstall();
@@ -2093,22 +2126,21 @@ function registerInstallUpdate(program) {
         process.stdout.write(JSON.stringify(out, null, 2) + "\n");
         process.exit(1);
       }
-      const which = spawnSync2("which", ["chrome-relay"]);
-      const newBin = which.stdout?.toString().trim();
-      if (which.status === 0 && newBin) {
-        const versionOut = spawnSync2(newBin, ["--version"]);
+      const newBin = whichBinary(spawnSync2, "chrome-relay");
+      if (newBin) {
+        const versionOut = spawnCli(spawnSync2, newBin, ["--version"]);
         const newVersion = (versionOut.stdout?.toString() ?? "").trim();
         out.binary.path = newBin;
         if (newVersion && newVersion !== fromVersion) {
           out.updatedTo = newVersion;
-          const install2 = spawnSync2(newBin, ["install"], { stdio: "inherit" });
+          const install2 = spawnCli(spawnSync2, newBin, ["install"], { stdio: "inherit" });
           if (install2.status !== 0) {
             out.warnings.push({
               code: "install_refresh_failed",
               message: `Update installed the new package but \`${newBin} install\` exited ${install2.status}. Run it manually to refresh the native host manifest.`
             });
           }
-          const rn = spawnSync2(newBin, ["release-notes", "--since", fromVersion]);
+          const rn = spawnCli(spawnSync2, newBin, ["release-notes", "--since", fromVersion]);
           try {
             const parsed = JSON.parse(rn.stdout?.toString() ?? "");
             if (Array.isArray(parsed.changes)) {
@@ -2130,7 +2162,7 @@ function registerInstallUpdate(program) {
       } else {
         out.warnings.push({
           code: "update_not_verified",
-          message: `Install completed but \`which chrome-relay\` did not return a path. Could not verify the active binary changed.`
+          message: `Install completed but \`${process.platform === "win32" ? "where" : "which"} chrome-relay\` did not return a path. Could not verify the active binary changed.`
         });
       }
     }
@@ -2161,7 +2193,7 @@ function registerNavigation(ctx) {
     await run("get_windows_and_tabs", {});
   });
   tabOpt(
-    program.command("navigate <url>").description("Navigate a tab to a URL. Use --tab <id> to target an existing tab.").option("--new", "open in a new tab").option("--active", "activate the tab after navigating (default: background \u2014 no focus theft)").addHelpText(
+    program.command("navigate <url>").description("Navigate a tab to a URL. Use --tab <id> to target an existing tab.").option("--new", "open in a new tab").option("--active", "activate the tab after navigating (default: background, no focus theft)").addHelpText(
       "after",
       `
 
@@ -2171,7 +2203,7 @@ Examples:
   chrome-relay navigate "https://chrome-relay.kushalsm.com" --new              # open in a new background tab
   chrome-relay navigate "https://chrome-relay.kushalsm.com" --new --active     # open new tab AND show it to the user
 
-By default chrome-relay never steals focus \u2014 navigated tabs (new or
+By default chrome-relay never steals focus. Navigated tabs (new or
 existing) stay in whatever state they're in. Pass --active when you
 actually want the user looking at the page.
 `
@@ -2220,7 +2252,7 @@ Examples:
   chrome-relay click 'button[aria-label="Save"]'
   chrome-relay click --tab 123 --x 1327 --y 771
 
-Prefer @refs from \`chrome-relay snapshot\` \u2014 they carry their own tab and
+Prefer @refs from \`chrome-relay snapshot\`. They carry their own tab and
 survive DOM churn (backendNodeId + role/name heal). CSS selectors for
 elements you know statically. Coordinates for canvas/SVG chart internals
 where no DOM handle exists. See docs/clicking-strategies.md.
@@ -2273,10 +2305,10 @@ Examples:
   chrome-relay type "appended into already-focused element"
 
 When to pick which:
-  fill   \u2014 plain <input>, <textarea>, <select>, React-controlled inputs (atomic write).
-  type   \u2014 contenteditable, Draft.js, Lexical, ProseMirror (trusted text commit).
-  keys   \u2014 Enter, Tab, Esc, arrows, modifier chords (single key press).
-  js     \u2014 anything else.
+  fill: plain <input>, <textarea>, <select>, React-controlled inputs (atomic write).
+  type: contenteditable, Draft.js, Lexical, ProseMirror (trusted text commit).
+  keys: Enter, Tab, Esc, arrows, modifier chords (single key press).
+  js: anything else.
 `
     )
   ).action(async (text, opts) => {
@@ -2333,7 +2365,7 @@ import { writeFileSync } from "fs";
 import { structuredPatch } from "diff";
 function printSnapshotDiff(current, prevText) {
   if (prevText === null) {
-    process.stderr.write("[chrome-relay] no previous snapshot for this tab \u2014 showing full output.\n");
+    process.stderr.write("[chrome-relay] no previous snapshot for this tab. Showing full output.\n");
     process.stdout.write(current + "\n");
     return;
   }
@@ -2375,17 +2407,17 @@ function exitWithError(error) {
 function registerCapture(ctx) {
   const { program, withBase, run } = ctx;
   tabOpt(
-    program.command("snapshot").description("Page snapshot with actionable @refs \u2014 accessibility tree + cursor-interactive sweep, compact text.").option("-i, --interactive", "only ref-bearing elements (buttons, links, inputs, named content, clickables)").option("-d, --depth <n>", "truncate the tree at this depth", (v) => Number(v)).option("-s, --scope <css>", "restrict to the subtree of the first CSS match").option("-u, --urls", "include link hrefs as url= attrs").option("--diff", "print only what changed since the previous snapshot of this tab (~100 tokens instead of a re-read)").option("--json", "structured output: { title, url, tabId, nodes, refs }").addHelpText(
+    program.command("snapshot").description("Page snapshot with actionable @refs. Accessibility tree plus cursor-interactive sweep, compact text.").option("-i, --interactive", "only ref-bearing elements (buttons, links, inputs, named content, clickables)").option("-d, --depth <n>", "truncate the tree at this depth", (v) => Number(v)).option("-s, --scope <css>", "restrict to the subtree of the first CSS match").option("-u, --urls", "include link hrefs as url= attrs").option("--diff", "print only what changed since the previous snapshot of this tab (~100 tokens instead of a re-read)").option("--no-elide", "print every row of long identical-shape runs (default keeps 10 + a count marker)").option("--json", "structured output: { title, url, tabId, nodes, refs }").addHelpText(
       "after",
       `
 
 Examples:
   chrome-relay snapshot -i                 # see the page, get @refs
-  chrome-relay click @e12                  # act on a ref \u2014 no --tab needed
+  chrome-relay click @e12                  # act on a ref, no --tab needed
   chrome-relay snapshot -i -s "#main"      # scope to a subtree
   chrome-relay snapshot --json             # machine-readable envelope
 
-The core loop: snapshot -i \u2192 click/fill @eN \u2192 snapshot -i again after the
+The core loop: snapshot -i -> click/fill @eN -> snapshot -i again after the
 page changes. Refs carry their own tab and heal across DOM churn
 (backendNodeId fast path + role/name re-find); a dead ref returns
 error.code = stale_ref, which means: re-run snapshot.
@@ -2398,6 +2430,7 @@ error.code = stale_ref, which means: re-run snapshot.
     if (opts.scope) extras.scope = opts.scope;
     if (opts.urls) extras.urls = true;
     if (opts.diff) extras.diff = true;
+    if (opts.elide === false) extras.elide = false;
     try {
       const result = await callTool("chrome_snapshot", withBase(opts, extras));
       if (opts.diff && !opts.json) {
@@ -2411,7 +2444,7 @@ error.code = stale_ref, which means: re-run snapshot.
     }
   });
   tabOpt(
-    program.command("screenshot").description("Capture a screenshot of any tab without activating it.").option("--full", "capture beyond the viewport (full page)").option("--bbox <rect>", "capture a region: 'x,y,width,height' (pixels)").option("--selector <css>", "capture the bounding box of a CSS selector").option("--padding <px>", "pixels of padding around --selector region", (v) => Number(v)).option("--max-edge <px>", "downscale so longer edge \u2264 this many pixels (no default; opt-in)", (v) => Number(v)).option("-o, --out <path>", "save image to path (base64 PNG decoded)").addHelpText(
+    program.command("screenshot").description("Capture a screenshot of any tab without activating it.").option("--full", "capture beyond the viewport (full page)").option("--bbox <rect>", "capture a region: 'x,y,width,height' (pixels)").option("--selector <css>", "capture the bounding box of a CSS selector").option("--padding <px>", "pixels of padding around --selector region", (v) => Number(v)).option("--max-edge <px>", "downscale so longer edge is at most this many pixels (no default; opt-in)", (v) => Number(v)).option("-o, --out <path>", "save image to path (base64 PNG decoded)").addHelpText(
       "after",
       `
 
@@ -2453,7 +2486,7 @@ full-tab screenshot when an agent only needs to see one component.
     }
   });
   tabOpt(
-    program.command("read").description("[deprecated \u2014 use `snapshot`] Alias for the unified snapshot.").option("-i, --interactive", "only ref-bearing elements").option("--json", "structured output")
+    program.command("read").description("[deprecated: use `snapshot`] Alias for the unified snapshot.").option("-i, --interactive", "only ref-bearing elements").option("--json", "structured output")
   ).action(async (opts) => {
     process.stderr.write("[chrome-relay] deprecated: `read` is now an alias for `snapshot` (new output format). Use `chrome-relay snapshot`.\n");
     const extras = {};
@@ -2466,7 +2499,7 @@ full-tab screenshot when an agent only needs to see one component.
     }
   });
   tabOpt(
-    program.command("ax").description("[deprecated \u2014 use `snapshot`] Alias for the unified snapshot.").option("-i, --interactive-only", "only ref-bearing elements").option("--root <role>", "(ignored \u2014 use `snapshot --scope <css>`)").option("--include-subframes", "(ignored \u2014 snapshot is top-frame only)").option("--json", "structured output")
+    program.command("ax").description("[deprecated: use `snapshot`] Alias for the unified snapshot.").option("-i, --interactive-only", "only ref-bearing elements").option("--root <role>", "(ignored: use `snapshot --scope <css>`)").option("--include-subframes", "(ignored: snapshot is top-frame only)").option("--json", "structured output")
   ).action(async (opts) => {
     process.stderr.write("[chrome-relay] deprecated: `ax` is now an alias for `snapshot` (new output format, one ref space). Use `chrome-relay snapshot`.\n");
     const extras = {};
@@ -2479,7 +2512,7 @@ full-tab screenshot when an agent only needs to see one component.
     }
   });
   tabOpt(
-    program.command("click-ax").description("[deprecated \u2014 use `click @eN`] Click by raw backendDOMNodeId (from `snapshot --json` refs).").requiredOption("--node <id>", "backendDOMNodeId from `chrome-relay ax`", (v) => Number(v)).addHelpText(
+    program.command("click-ax").description("[deprecated: use `click @eN`] Click by raw backendDOMNodeId (from `snapshot --json` refs).").requiredOption("--node <id>", "backendDOMNodeId from `chrome-relay ax`", (v) => Number(v)).addHelpText(
       "after",
       `
 
@@ -2585,10 +2618,10 @@ Notes:
       if (opts.gif || opts.mp4) {
         const fps = typeof opts.fps === "number" ? opts.fps : 15;
         const { spawnSync: spawnSync2 } = await import("child_process");
-        const which = spawnSync2("which", ["ffmpeg"]);
+        const which = spawnSync2(process.platform === "win32" ? "where" : "which", ["ffmpeg"]);
         if (which.status !== 0) {
           if (opts.allowMissingFfmpeg) {
-            process.stderr.write("[chrome-relay] ffmpeg not on PATH \u2014 skipping --gif/--mp4 (allow-missing-ffmpeg).\n");
+            process.stderr.write("[chrome-relay] ffmpeg not on PATH. Skipping --gif/--mp4 (allow-missing-ffmpeg).\n");
             return;
           }
           const { RelayError: RelayError2 } = await Promise.resolve().then(() => (init_dist(), dist_exports));
@@ -2654,7 +2687,7 @@ Notes:
 init_dist();
 var CONSOLE_BUFFER_MAX_KB = Math.round(CONSOLE_BUFFER_MAX_BYTES / 1024);
 function netFilterOpts(cmd) {
-  return cmd.option("--filter <substr>", "url substring filter").option("--status <bucket>", "ok | redirect | client_error | server_error | failed").option("--method <verb>", "exact method, e.g. POST").option("--limit <n>", "cap response length", (v) => Number(v));
+  return cmd.option("--filter <substr>", "url substring filter").option("--status <bucket>", "ok | redirect | client_error | server_error | failed").option("--method <verb>", "exact method, e.g. POST").option("--limit <n>", "cap response length", (v) => Number(v)).option("--raw-headers", "include sensitive header values (cookies, auth, tokens). REDACTED by default so output is safe to paste");
 }
 function netFilterArgs(opts) {
   const a = {};
@@ -2662,6 +2695,7 @@ function netFilterArgs(opts) {
   if (opts.status) a.status = opts.status;
   if (opts.method) a.method = opts.method;
   if (typeof opts.limit === "number") a.limit = opts.limit;
+  if (opts.rawHeaders) a.rawHeaders = true;
   return a;
 }
 function registerSessions(ctx) {
@@ -2802,8 +2836,8 @@ Privacy:
   share with the agent invoking chrome-relay.
 
 Notes:
-  Bodies are NOT eagerly buffered \u2014 Chrome GCs response bodies ~30s after
-  the request finishes. Use \`--body <id>\` or \`har --with-bodies\` promptly.
+  Bodies are NOT eagerly buffered. Chrome GCs response bodies ~30s after
+  the request finishes. Use \`network body <requestId>\` or \`network har --with-bodies\` promptly.
   WebSocket frames and SSE streams are out of scope.
 `
   ).action(async (opts) => {
@@ -2815,7 +2849,7 @@ Notes:
     await run("chrome_network", withBase(opts, netFilterArgs(opts)));
   });
   tabOpt(
-    network.command("body <requestId>").description("Fetch the response body for one request (lazy; may fail if GC'd).").option("--head <bytes>", "truncate to first N bytes", (v) => Number(v)).option("--full", "return the full body \u2014 default truncates to 8 KB")
+    network.command("body <requestId>").description("Fetch the response body for one request (lazy; may fail if GC'd).").option("--head <bytes>", "truncate to first N bytes", (v) => Number(v)).option("--full", "return the full body. Default truncates to 8 KB")
   ).action(async (requestId, opts) => {
     const extras = { action: "body", requestId };
     if (opts.full) extras.full = true;
@@ -2823,7 +2857,7 @@ Notes:
     await run("chrome_network", withBase(opts, extras));
   });
   tabOpt(netFilterOpts(
-    network.command("har").description("Emit HAR-compatible JSON for the captured entries.").option("--with-bodies", "fetch response bodies before emitting; strict by default \u2014 fails if any body cannot be fetched").option("--best-effort-bodies", "with --with-bodies: keep the HAR even when some bodies are missing/errored (legacy behavior); per-entry _chrome_relay.bodyState/bodyError records what failed")
+    network.command("har").description("Emit HAR-compatible JSON for the captured entries.").option("--with-bodies", "fetch response bodies before emitting; strict by default, fails if any body cannot be fetched").option("--best-effort-bodies", "with --with-bodies: keep the HAR even when some bodies are missing/errored (legacy behavior); per-entry _chrome_relay.bodyState/bodyError records what failed")
   )).action(async (opts) => {
     const extras = { ...netFilterArgs(opts), action: "har" };
     if (opts.withBodies) extras.withBodies = true;
@@ -2871,11 +2905,11 @@ Notes:
 init_dist();
 import { readFileSync } from "fs";
 function coreSkillText() {
-  if (true) return '# Chrome Relay\n\nDrives the user\'s real Chrome through a Chrome extension + local native host. Prefer it when logged-in browser state (auth cookies, sessions, installed extensions) matters.\n\n## Setup\n\n1. [Chrome extension](https://chromewebstore.google.com/detail/chrome-relay/cpdiapbifblhlcpnmlmfpgfjlacebokb)\n2. CLI:\n   ```sh\n   pnpm add -g chrome-relay\n   chrome-relay install\n   chrome-relay doctor\n   ```\n\nVerify CLI \u2265 0.7.0 \u2014 wait/get/batch/`snapshot --diff` landed there (0.6.0 brought the snapshot/@ref loop; \u2265 0.5.20 fixed a silent click bug on Radix/React-Aria UIs):\n```sh\nchrome-relay --version\n```\n\n## The core loop\n\n```sh\nchrome-relay tabs                             # find or create a tab\nchrome-relay navigate "https://kushalsm.com" --new   # background tab by default\nchrome-relay snapshot --tab 1234 -i           # see the page: actionable elements get @refs\nchrome-relay click @e12                       # act on refs \u2014 no --tab, no selector\nchrome-relay fill @e14 "hello"\nchrome-relay wait --text "Saved" --tab 1234   # block until the page reacts\nchrome-relay snapshot --tab 1234 --diff       # print only what changed (~100 tokens)\n```\n\nSnapshot output is compact indented text (~1\u201315 KB for most pages) \u2014 read it directly, no jq needed:\n\n```\n- link "Hacker News" [ref=e4]\n- textbox "Search" [ref=e41]: current value\n- checkbox "Remember me" [checked, ref=e42]\n- clickable "Open card" [ref=e88]        \u2190 cursor-pointer div the AX tree missed\n```\n\n**Refs carry their own tab.** `click @e12` acts on the tab that produced e12, never the active tab \u2014 safe while the user keeps browsing. A contradicting `--tab` errors with `target_conflict`.\n\n**Ref lifetime.** Refs survive same-page DOM churn (cached backendNodeId, healed by role+name re-find when nodes are replaced) but die on real navigation. A dead ref returns `error.code = stale_ref` \u2192 re-run `snapshot`.\n\n**Interception.** Ref clicks hit-test the point first: if an overlay / sticky header / modal owns it, you get `error.code = click_intercepted` naming the interceptor \u2014 dismiss it or scroll, then retry. The click was NOT delivered. `fill`/`type` skip this check (covered inputs are still writable).\n\n## Tool surface\n\n| Command | What it does |\n|---|---|\n| `tabs` | List windows + tabs with their `tabId`s |\n| `navigate <url>` | Open in current tab. `--new` opens in a **background** tab (default). `--active` brings it to foreground. `--tab <id>` retargets an existing tab. |\n| `snapshot --tab <id> -i` | Page snapshot with actionable `@refs` \u2014 accessibility tree + cursor-interactive sweep, one ref space, compact text. `-d N` depth cap, `-s <css>` scope to subtree, `-u` include hrefs, `--diff` print only changes since the last snapshot, `--json` structured envelope with the refs map. |\n| `wait <css\\|@ref>` / `wait --text` / `--url <glob>` / `--load networkidle` / `--fn <js>` | Block until a condition holds (one per call, default 10s, max 25s). `wait 1500` just sleeps. On timeout the error includes current page state. |\n| `get text\\|value\\|attr\\|count\\|title\\|url <target>` | One value, plain to stdout \u2014 no full snapshot. `get text @e12`, `get attr @e7 href`, `get count ".row"`. |\n| `batch \'[{"name":"chrome_...","args":{...}}, ...]\'` | N tool calls in ONE round-trip, sequential, bail-on-error by default. Use wire tool names. |\n| `skills get core` | Print this playbook, version-matched to the installed binary. |\n| `click <@ref \\| selector> --tab <id>` | Trusted hover + press + release at element center (`pointerType: "mouse"`). Refs need no `--tab`. |\n| `click --x N --y N --tab <id>` | Coordinate-mode click \u2014 for canvas/SVG chart internals with no DOM handle. |\n| `hover <@ref \\| selector \\| --x --y>` | Pointer move only \u2014 fires `:hover` styles. |\n| `fill <@ref \\| selector> <value>` | Atomic value write into `<input>`/`<textarea>`/`<select>`. Bypasses React\'s value tracker. Refs reach inside shadow DOM (selectors can\'t). |\n| `type <text> [-s <@ref \\| selector>]` | CDP `Input.insertText`. Use for contenteditable / Draft.js / Lexical / ProseMirror. **Appends** at caret; clear the input first if it had a value. |\n| `keys <chord> --tab <id>` | Single key or chord: `Enter`, `Tab`, `Escape`, `Cmd+K`, `Shift+ArrowDown`. |\n| `js <code> --tab <id>` | `Runtime.evaluate` in MAIN world. Use `return` for the value. Top-level `await` works. |\n| `screenshot --tab <id> -o <path>` | PNG. `--full` captures beyond viewport. `--max-edge N` resizes. |\n| `screencast --tab <id> -o <path>` | Record a tab via CDP (paint-driven). Requires an active tab. |\n| `network --tab <id>` | HTTP request/response ring buffer, last 200 per tab. `network read --request-id <id>` for bodies. |\n| `console --tab <id>` | `console.log/warn/error` + page exceptions, last 200. |\n| `viewport` | Emulate device viewport, DPR, mobile flag, touch, UA. |\n| `workspace` / `group` | Manage named windows / tab-groups so multiple agents can drive separate windows. |\n| `switch <tabId>` / `close <tabIds...>` | Activate or close tabs |\n| `self-reload` | Restart the extension\'s service worker after a rebuild |\n| `release-notes --since <ver>` / `update` | Queryable changelog; agent-readable JSON. |\n| `call <tool> [json]` | Raw pass-through for any internal tool. |\n| `read` / `ax` / `click-ax` | **Deprecated** \u2014 aliases for `snapshot` / `click @ref`. Will be removed; don\'t use in new work. |\n\n## Picking the right text tool\n\n| Target element | Tool |\n|---|---|\n| `<input>`, `<textarea>`, `<select>` (including React-controlled, shadow DOM) | `fill @ref` |\n| `[contenteditable]`, `role="textbox"`, Draft.js / Lexical / ProseMirror, X compose, LinkedIn DM, new Reddit composer | `type` |\n| Submit, navigate menus, modifier shortcuts | `keys` |\n| Combobox / autocomplete option selection | `type` into filter \u2192 `keys ArrowDown` \u2192 `keys Enter` ([why](references/patterns.md)) |\n| Framework-internal pokes, scraping, custom widgets | `js` |\n\n## Element addressing \u2014 the fallback ladder\n\n1. **`@ref` from `snapshot -i`** \u2014 default. Covers buttons/links/inputs, named content, cursor-pointer div-soup (the sweep), and shadow DOM.\n2. **CSS selector** \u2014 when you know the selector statically and don\'t need a snapshot.\n3. **`js` probe \u2192 coordinate click** \u2014 canvas internals and SVG chart segments (anonymous `<path>` elements have no DOM handle anywhere):\n   ```sh\n   chrome-relay js --tab 1234 "const r = document.querySelector(\'svg path\').getBoundingClientRect(); return {x: r.x + r.width/2, y: r.y + r.height/2}"\n   chrome-relay click --tab 1234 --x 312 --y 218\n   ```\n\n## Don\'t poll \u2014 wait\n\nA snapshot after every action wastes turns. The cheap loop on a changing page:\n\n```sh\nchrome-relay click @e12\nchrome-relay wait --text "Saved" --tab 1234     # or wait <selector> / --url / --load\nchrome-relay snapshot --tab 1234 --diff         # only the changes, refs included\n```\n\n## Top gotchas\n\n1. **`type` appends** \u2014 it inserts at the caret. If the input had a value (autosaved draft, default text), clear it first via `js` or `keys` (Cmd+A then Backspace).\n2. **Refs die on navigation** \u2014 `stale_ref` means the page changed under you; re-snapshot. Don\'t retry the same ref.\n3. **Coords go stale fast** \u2014 read `getBoundingClientRect`, scroll/reflow, then click \u2192 you hit the wrong element. For autocomplete popups especially, use keyboard nav, not coord clicks.\n4. **Click "succeeded" but nothing happened** \u2014 first diagnostic: `document.elementFromPoint(x, y)`. If it returns a wrapper or form background, your coords are wrong. If it returns the right element but state didn\'t change, you\'re likely on chrome-relay <0.5.20 \u2014 upgrade.\n\nMore recipes: [references/patterns.md](references/patterns.md)\nFailure modes: [references/troubleshooting.md](references/troubleshooting.md)\n\n## Operational guidance\n\n- **Don\'t give up early.** A failing click is information, not a stop signal. Attach a document-level listener with `capture:true` and watch what fires:\n  ```sh\n  chrome-relay js --tab 1234 "\n    [\'pointerdown\',\'mousedown\',\'click\'].forEach(t =>\n      document.addEventListener(t, e => console.log(t, e.target.tagName, e.target.className), {capture:true})\n    );\n    return \'listening\'\n  "\n  # do the action, then:\n  chrome-relay console --tab 1234\n  ```\n- **Don\'t echo secrets.** When extracting tokens / API keys via `js`, write the result directly to a file. Never `echo $TOKEN` or interpolate into shell strings \u2014 it ends up in scrollback, logs, and tool transcripts.\n- **Capture before irreversible actions** (form submit, send message, account change). Save the screenshot path.\n\n## Guardrails\n\n- Errors are structured: branch on `relayError.code` (`stale_ref`, `click_intercepted`, `element_not_found`, `target_conflict`, `timeout`), not on message text.\n- If a flag is unclear, `chrome-relay <command> --help` is authoritative \u2014 these docs lag.';
+  if (true) return '# Chrome Relay\n\nDrives the user\'s real Chrome through a Chrome extension + local native host. Prefer it when logged-in browser state (auth cookies, sessions, installed extensions) matters.\n\n## Setup\n\n1. [Chrome extension](https://chromewebstore.google.com/detail/chrome-relay/cpdiapbifblhlcpnmlmfpgfjlacebokb)\n2. CLI:\n   ```sh\n   pnpm add -g chrome-relay\n   chrome-relay install\n   chrome-relay doctor\n   ```\n\nVerify CLI >= 0.7.0. wait/get/batch/`snapshot --diff` landed there. 0.6.0 brought the snapshot/@ref loop. >= 0.5.20 fixed a silent click bug on Radix/React-Aria UIs:\n```sh\nchrome-relay --version\n```\n\n## The core loop\n\n```sh\nchrome-relay tabs                             # find or create a tab\nchrome-relay navigate "https://kushalsm.com" --new   # background tab by default\nchrome-relay snapshot --tab 1234 -i           # see the page: actionable elements get @refs\nchrome-relay click @e12                       # act on refs, no --tab, no selector\nchrome-relay fill @e14 "hello"\nchrome-relay wait --text "Saved" --tab 1234   # block until the page reacts\nchrome-relay snapshot --tab 1234 --diff       # print only what changed (~100 tokens)\n```\n\nSnapshot output is compact indented text, usually 1 to 15 KB for most pages. Read it directly, no jq needed:\n\n```\n- link "Hacker News" [ref=e4]\n- textbox "Search" [ref=e41]: current value\n- checkbox "Remember me" [checked, ref=e42]\n- clickable "Open card" [ref=e88]        # cursor-pointer div the AX tree missed\n```\n\n**Refs carry their own tab.** `click @e12` acts on the tab that produced e12, never the active tab. Safe while the user keeps browsing. A contradicting `--tab` errors with `target_conflict`.\n\n**Ref lifetime.** Refs survive same-page DOM churn (cached backendNodeId, healed by role+name re-find when nodes are replaced) but die on real navigation. A dead ref returns `error.code = stale_ref`. Re-run `snapshot`.\n\n**Interception.** Ref clicks hit-test the point first. If an overlay / sticky header / modal owns it, you get `error.code = click_intercepted` naming the interceptor. Dismiss it or scroll, then retry. The click was NOT delivered. `fill`/`type` skip this check (covered inputs are still writable).\n\n## Tool surface\n\n| Command | What it does |\n|---|---|\n| `tabs` | List windows + tabs with their `tabId`s |\n| `navigate <url>` | Open in current tab. `--new` opens in a **background** tab (default). `--active` brings it to foreground. `--tab <id>` retargets an existing tab. |\n| `snapshot --tab <id> -i` | Page snapshot with actionable `@refs`: accessibility tree plus cursor-interactive sweep, one ref space, compact text. `-d N` depth cap, `-s <css>` scope to subtree, `-u` include hrefs, `--diff` print only changes since the last snapshot, `--json` structured envelope with the refs map. |\n| `wait <css\\|@ref>` / `wait --text` / `--url <glob>` / `--load networkidle` / `--fn <js>` | Block until a condition holds (one per call, default 10s, max 25s). `wait 1500` just sleeps. On timeout the error includes current page state. |\n| `get text\\|value\\|attr\\|count\\|title\\|url <target>` | One value, plain to stdout. No full snapshot. `get text @e12`, `get attr @e7 href`, `get count ".row"`. |\n| `batch \'[{"name":"chrome_...","args":{...}}, ...]\'` | N tool calls in ONE round-trip, sequential, bail-on-error by default. Use wire tool names. |\n| `skills get core` | Print this playbook, version-matched to the installed binary. |\n| `click <@ref \\| selector> --tab <id>` | Trusted hover + press + release at element center (`pointerType: "mouse"`). Refs need no `--tab`. |\n| `click --x N --y N --tab <id>` | Coordinate-mode click for canvas/SVG chart internals with no DOM handle. |\n| `hover <@ref \\| selector \\| --x --y>` | Pointer move only. Fires `:hover` styles. |\n| `fill <@ref \\| selector> <value>` | Atomic value write into `<input>`/`<textarea>`/`<select>`. Bypasses React\'s value tracker. Refs reach inside shadow DOM (selectors can\'t). |\n| `type <text> [-s <@ref \\| selector>]` | CDP `Input.insertText`. Use for contenteditable / Draft.js / Lexical / ProseMirror. **Appends** at caret; clear the input first if it had a value. |\n| `keys <chord> --tab <id>` | Single key or chord: `Enter`, `Tab`, `Escape`, `Cmd+K`, `Shift+ArrowDown`. |\n| `js <code> --tab <id>` | `Runtime.evaluate` in MAIN world. Use `return` for the value. Top-level `await` works. |\n| `screenshot --tab <id> -o <path>` | PNG. `--full` captures beyond viewport. `--max-edge N` resizes. |\n| `screencast --tab <id> -o <path>` | Record a tab via CDP (paint-driven). Requires an active tab. |\n| `network --tab <id>` | HTTP request/response ring buffer, last 200 per tab. `network body <requestId>` fetches a body while Chrome still has it. `network har --with-bodies` exports a HAR with bodies. |\n| `console --tab <id>` | `console.log/warn/error` + page exceptions, last 200. |\n| `viewport` | Emulate device viewport, DPR, mobile flag, touch, UA. |\n| `workspace` / `group` | Manage named windows / tab-groups so multiple agents can drive separate windows. |\n| `switch <tabId>` / `close <tabIds...>` | Activate or close tabs |\n| `self-reload` | Restart the extension\'s service worker after a rebuild |\n| `release-notes --since <ver>` / `update` | Queryable changelog; agent-readable JSON. |\n| `call <tool> [json]` | Raw pass-through for any internal tool. |\n| `read` / `ax` / `click-ax` | **Deprecated**. Aliases for `snapshot` / `click @ref`. Will be removed; don\'t use in new work. |\n\n## Picking the right text tool\n\n| Target element | Tool |\n|---|---|\n| `<input>`, `<textarea>`, `<select>` (including React-controlled, shadow DOM) | `fill @ref` |\n| `[contenteditable]`, `role="textbox"`, Draft.js / Lexical / ProseMirror, X compose, LinkedIn DM, new Reddit composer | `type` |\n| Submit, navigate menus, modifier shortcuts | `keys` |\n| Combobox / autocomplete option selection | `type` into filter, then `keys ArrowDown`, then `keys Enter` ([why](references/patterns.md)) |\n| Framework-internal pokes, scraping, custom widgets | `js` |\n\n## Element addressing: the fallback ladder\n\n1. **`@ref` from `snapshot -i`**: default. Covers buttons/links/inputs, named content, cursor-pointer div-soup (the sweep), and shadow DOM.\n2. **CSS selector**: when you know the selector statically and don\'t need a snapshot.\n3. **`js` probe, then coordinate click**: canvas internals and SVG chart segments (anonymous `<path>` elements have no DOM handle anywhere):\n   ```sh\n   chrome-relay js --tab 1234 "const r = document.querySelector(\'svg path\').getBoundingClientRect(); return {x: r.x + r.width/2, y: r.y + r.height/2}"\n   chrome-relay click --tab 1234 --x 312 --y 218\n   ```\n\n## Don\'t poll. Wait.\n\nA snapshot after every action wastes turns. The cheap loop on a changing page:\n\n```sh\nchrome-relay click @e12\nchrome-relay wait --text "Saved" --tab 1234     # or wait <selector> / --url / --load\nchrome-relay snapshot --tab 1234 --diff         # only the changes, refs included\n```\n\n## Top gotchas\n\n0. **`snapshot -i` is for ACTING, not fact extraction.** It prints ref-bearing elements only. Non-interactive values (dashboard metrics, paragraph text, chart labels) drop out. Measured live: a Cloudflare Pages metrics page lost all its numbers under `-i`. To READ facts, use full `snapshot`, `get text <target>`, or a `js` projection.\n1. **`type` appends.** It inserts at the caret. If the input had a value (autosaved draft, default text), clear it first via `js` or `keys` (Cmd+A then Backspace).\n2. **Refs die on navigation.** `stale_ref` means the page changed under you; re-snapshot. Don\'t retry the same ref.\n3. **Coords go stale fast.** Read `getBoundingClientRect`, scroll/reflow, then click, and you hit the wrong element. For autocomplete popups especially, use keyboard nav, not coord clicks.\n4. **Click "succeeded" but nothing happened.** First diagnostic: `document.elementFromPoint(x, y)`. If it returns a wrapper or form background, your coords are wrong. If it returns the right element but state didn\'t change, you\'re likely on chrome-relay <0.5.20. Upgrade.\n\nMore recipes: [references/patterns.md](references/patterns.md)\nFailure modes: [references/troubleshooting.md](references/troubleshooting.md)\n\n## Operational guidance\n\n- **Don\'t give up early.** A failing click is information, not a stop signal. Attach a document-level listener with `capture:true` and watch what fires:\n  ```sh\n  chrome-relay js --tab 1234 "\n    [\'pointerdown\',\'mousedown\',\'click\'].forEach(t =>\n      document.addEventListener(t, e => console.log(t, e.target.tagName, e.target.className), {capture:true})\n    );\n    return \'listening\'\n  "\n  # do the action, then:\n  chrome-relay console --tab 1234\n  ```\n- **Don\'t echo secrets.** When extracting tokens / API keys via `js`, write the result directly to a file. Never `echo $TOKEN` or interpolate into shell strings. It ends up in scrollback, logs, and tool transcripts.\n- **Redact `network` output.** Request/response headers carry cookies, auth/CSRF tokens, account and project IDs. Never paste raw `chrome-relay network` output into chat, docs, issues, or commits. Filter to the fields you need (url, status, timings) or redact headers first.\n- **Capture before irreversible actions** (form submit, send message, account change). Save the screenshot path.\n\n## Guardrails\n\n- Errors are structured: branch on `relayError.code` (`stale_ref`, `click_intercepted`, `element_not_found`, `target_conflict`, `timeout`), not on message text.\n- If a flag is unclear, `chrome-relay <command> --help` is authoritative. These docs lag.';
   try {
     return readFileSync(new URL("../../../../skills/chrome-relay/SKILL.md", import.meta.url), "utf8").replace(/^---\n[\s\S]*?\n---\n/, "").replace(/<!--[\s\S]*?-->\n*/, "").trim();
   } catch {
-    return "core skill unavailable in this build \u2014 see https://chrome-relay.kushalsm.com/skill.md";
+    return "core skill unavailable in this build. See https://chrome-relay.kushalsm.com/skill.md";
   }
 }
 function exitWithError2(error) {
@@ -2928,7 +2962,7 @@ need a follow-up probe.
     if (typeof opts.timeout === "number") extras.timeoutMs = opts.timeout;
     await run(TOOL_NAMES.WAIT, withBase(opts, extras));
   });
-  const get = program.command("get").description("One value, plain to stdout \u2014 no full snapshot.").addHelpText(
+  const get = program.command("get").description("One value, plain to stdout. No full snapshot.").addHelpText(
     "after",
     `
 
@@ -2991,7 +3025,7 @@ Examples:
 
 One HTTP POST, one native-messaging message, sequential execution in the
 extension. Tool names are the wire names (chrome_navigate, chrome_snapshot,
-chrome_click_element, ... \u2014 see \`chrome-relay call --help\`). Amortizes CLI
+chrome_click_element, ...; see \`chrome-relay call --help\`). Amortizes CLI
 startup across N actions. Nested batches are rejected.
 `
   ).action(async (json, opts) => {
@@ -3038,7 +3072,7 @@ startup across N actions. Nested batches are rejected.
       exitWithError2(error);
     }
   });
-  const skills = program.command("skills [verb] [name]").description("Agent playbooks shipped inside the CLI \u2014 always version-matched to the binary.").addHelpText(
+  const skills = program.command("skills [verb] [name]").description("Agent playbooks shipped inside the CLI. Always version-matched to the binary.").addHelpText(
     "after",
     `
 
@@ -3046,13 +3080,13 @@ Examples:
   chrome-relay skills            # list available skills
   chrome-relay skills get core   # print the core usage guide
 
-The same guide is hosted at https://chrome-relay.kushalsm.com/skill.md \u2014
-the binary copy is authoritative for the version you have installed.
+The same guide is hosted at https://chrome-relay.kushalsm.com/skill.md.
+The binary copy is authoritative for the version you have installed.
 `
   );
   skills.action(async (verb, name) => {
     if (!verb || verb === "list") {
-      process.stdout.write("core \u2014 the Chrome Relay agent playbook (snapshot/@ref loop, text-tool table, gotchas)\n");
+      process.stdout.write("core: the Chrome Relay agent playbook (snapshot/@ref loop, text-tool table, gotchas)\n");
       return;
     }
     if (verb === "get" && (name === "core" || name === void 0)) {
@@ -3068,7 +3102,7 @@ the binary copy is authoritative for the version you have installed.
 // src/program.ts
 function buildProgram() {
   const program = new Command();
-  program.name("chrome-relay").description("Your agent drives the Chrome you're signed into \u2014 reads pages, clicks buttons, fills forms from any shell.").version(CHROME_RELAY_VERSION).showHelpAfterError().option("--workspace <name>", "target the active tab in a named workspace window (works at top level too)").option("--group <name>", "target the active tab in a named tab-group (works at top level too)").enablePositionalOptions().addHelpText(
+  program.name("chrome-relay").description("Your agent drives the Chrome you're signed into. Reads pages, clicks buttons, fills forms from any shell.").version(CHROME_RELAY_VERSION).showHelpAfterError().option("--workspace <name>", "target the active tab in a named workspace window (works at top level too)").option("--group <name>", "target the active tab in a named tab-group (works at top level too)").enablePositionalOptions().addHelpText(
     "after",
     `
 
@@ -3076,7 +3110,7 @@ The core loop:
   chrome-relay tabs
   chrome-relay navigate "https://chrome-relay.kushalsm.com" --new      # background tab
   chrome-relay snapshot --tab <tabId> -i                 # actionable elements get @refs
-  chrome-relay click @e12                                # act on a ref \u2014 no --tab needed
+  chrome-relay click @e12                                # act on a ref, no --tab needed
   chrome-relay fill @e14 "value"
   chrome-relay snapshot --tab <tabId> -i                 # re-look after the page changes
 
@@ -3090,8 +3124,8 @@ Also:
 
 Notes:
   Refs come from snapshot and carry their own tab. Tools attach via CDP and
-  run on backgrounded tabs without stealing focus. Errors are structured \u2014
-  branch on relayError.code (stale_ref means: re-run snapshot).
+  run on backgrounded tabs without stealing focus. Errors are structured.
+  Branch on relayError.code (stale_ref means: re-run snapshot).
 `
   );
   const baseArgs = makeBaseArgs(program);

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.7.1" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.7.2" : "0.0.0-dev";
 export {
   CHROME_RELAY_VERSION
 };

package/dist/native-host.js

@@ -56,7 +56,7 @@ function toBridgeError(unknownErr, fallbackTool) {
 }
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.7.1" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.7.2" : "0.0.0-dev";
 
 // src/release-notes.ts
 function compareSemver(a, b) {
@@ -104,7 +104,8 @@ var RelayHttpServer = class {
       ok: true,
       port: this.port,
       cliVersion: CHROME_RELAY_VERSION,
-      extensionVersion: this.bridge.getExtensionVersion() ?? null
+      extensionVersion: this.bridge.getExtensionVersion() ?? null,
+      extensionId: this.bridge.getExtensionId() ?? null
     }));
     this.app.post("/call", async (request, reply) => {
       if (request.headers.origin) {
@@ -154,12 +155,17 @@ var ExtensionBridge = class {
   pending = /* @__PURE__ */ new Map();
   readyWaiters = /* @__PURE__ */ new Set();
   ready = false;
-  // Extension version captured from `bridge.ready`. Read by the HTTP server
-  // to compute the cli-outdated notice on each tool call.
+  // Extension version + id captured from `bridge.ready`. Version feeds the
+  // cli-outdated notice; the id tells doctor WHICH extension owns the bridge
+  // (store vs unpacked dev — they race for the port when both are loaded).
   extensionVersion;
+  extensionId;
   getExtensionVersion() {
     return this.extensionVersion;
   }
+  getExtensionId() {
+    return this.extensionId;
+  }
   handleMessage(message) {
     if (message.type === "bridge.ready") {
       this.handleReady(message);
@@ -182,6 +188,7 @@ var ExtensionBridge = class {
   handleReady(message) {
     this.ready = true;
     this.extensionVersion = message.payload?.version;
+    this.extensionId = message.payload?.extensionId;
     for (const notify of this.readyWaiters) {
       notify();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-relay",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,7 +16,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run"
   },
-  "description": "Your agent drives the Chrome you're signed into — read pages, click buttons, fill forms from any shell. No robot browser, no cookie export, no focus stealing.",
+  "description": "Your agent drives the Chrome you're signed into. Read pages, click buttons, fill forms from any shell. No robot browser, no cookie export, no focus stealing.",
   "keywords": [
     "chrome",
     "browser",