chrome-relay 0.6.0 → 0.7.0

package/dist/cli.js

@@ -442,6 +442,9 @@ function parseChromeSnapshotArgs(input) {
   const urls = optBool(obj, "urls", TOOL_NAMES.SNAPSHOT);
   if (urls !== void 0)
     out.urls = urls;
+  const diff = optBool(obj, "diff", TOOL_NAMES.SNAPSHOT);
+  if (diff !== void 0)
+    out.diff = diff;
   return out;
 }
 function parseChromeScreenshotArgs(input) {
@@ -910,6 +913,170 @@ var init_multi = __esm({
   }
 });
 
+// ../protocol/dist/limits.js
+var DEFAULT_TOOL_CALL_TIMEOUT_MS, DEFAULT_PING_TIMEOUT_MS, DEFAULT_READY_TIMEOUT_MS, DEFAULT_EVAL_TIMEOUT_MS, DEFAULT_BODY_PREVIEW_BYTES, DEFAULT_WAIT_TIMEOUT_MS, MAX_WAIT_TIMEOUT_MS, WAIT_POLL_INTERVAL_MS, NETWORKIDLE_QUIET_MS, MAX_BATCH_COMMANDS, MAX_BATCH_BYTES, NETWORK_BUFFER_MAX_ENTRIES, NETWORK_BUFFER_MAX_BYTES, CONSOLE_BUFFER_MAX_ENTRIES, CONSOLE_BUFFER_MAX_BYTES, CONSOLE_ENTRY_TEXT_MAX_CHARS, CONSOLE_ENTRY_STACK_MAX_CHARS;
+var init_limits = __esm({
+  "../protocol/dist/limits.js"() {
+    "use strict";
+    DEFAULT_TOOL_CALL_TIMEOUT_MS = 3e4;
+    DEFAULT_PING_TIMEOUT_MS = 2e3;
+    DEFAULT_READY_TIMEOUT_MS = 15e3;
+    DEFAULT_EVAL_TIMEOUT_MS = 15e3;
+    DEFAULT_BODY_PREVIEW_BYTES = 8 * 1024;
+    DEFAULT_WAIT_TIMEOUT_MS = 1e4;
+    MAX_WAIT_TIMEOUT_MS = 25e3;
+    WAIT_POLL_INTERVAL_MS = 100;
+    NETWORKIDLE_QUIET_MS = 500;
+    MAX_BATCH_COMMANDS = 50;
+    MAX_BATCH_BYTES = 9e5;
+    NETWORK_BUFFER_MAX_ENTRIES = 200;
+    NETWORK_BUFFER_MAX_BYTES = 512 * 1024;
+    CONSOLE_BUFFER_MAX_ENTRIES = 200;
+    CONSOLE_BUFFER_MAX_BYTES = 256 * 1024;
+    CONSOLE_ENTRY_TEXT_MAX_CHARS = 1e3;
+    CONSOLE_ENTRY_STACK_MAX_CHARS = 1e3;
+  }
+});
+
+// ../protocol/dist/args/loop.js
+function parseChromeWaitArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.WAIT);
+  const target = parseTargetArgs(obj, TOOL_NAMES.WAIT);
+  const candidates = [];
+  const selector = optString(obj, "selector", TOOL_NAMES.WAIT);
+  if (selector)
+    candidates.push({ kind: "selector", selector });
+  const ref = optString(obj, "ref", TOOL_NAMES.WAIT);
+  if (ref)
+    candidates.push({ kind: "ref", ref });
+  const text = optString(obj, "text", TOOL_NAMES.WAIT);
+  if (text)
+    candidates.push({ kind: "text", text });
+  const urlGlob = optString(obj, "urlGlob", TOOL_NAMES.WAIT);
+  if (urlGlob)
+    candidates.push({ kind: "url", urlGlob });
+  const load = optString(obj, "load", TOOL_NAMES.WAIT);
+  if (load) {
+    if (!LOAD_STATES.has(load)) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${TOOL_NAMES.WAIT}: \`load\` must be one of load | domcontentloaded | networkidle (got ${load}).`,
+        tool: TOOL_NAMES.WAIT,
+        phase: "parse_arguments",
+        details: { received: load },
+        retryable: false
+      });
+    }
+    candidates.push({ kind: "load", state: load });
+  }
+  const fn = optString(obj, "fn", TOOL_NAMES.WAIT);
+  if (fn)
+    candidates.push({ kind: "fn", fn });
+  if (candidates.length !== 1) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.WAIT}: pass exactly one condition (selector | ref | text | urlGlob | load | fn); got ${candidates.length}.`,
+      tool: TOOL_NAMES.WAIT,
+      phase: "parse_arguments",
+      details: { received: candidates.map((c) => c.kind) },
+      retryable: false
+    });
+  }
+  const timeoutRaw = optPositiveNumber(obj, "timeoutMs", TOOL_NAMES.WAIT) ?? DEFAULT_WAIT_TIMEOUT_MS;
+  return {
+    ...target,
+    condition: candidates[0],
+    timeoutMs: Math.min(timeoutRaw, MAX_WAIT_TIMEOUT_MS)
+  };
+}
+function parseChromeBatchArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.BATCH);
+  if (!Array.isArray(obj.commands) || obj.commands.length === 0) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.BATCH}: \`commands\` must be a non-empty array of { name, args? }.`,
+      tool: TOOL_NAMES.BATCH,
+      phase: "parse_arguments",
+      details: { received: obj.commands },
+      retryable: false
+    });
+  }
+  if (obj.commands.length > MAX_BATCH_COMMANDS) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.BATCH}: at most ${MAX_BATCH_COMMANDS} commands per batch (got ${obj.commands.length}).`,
+      tool: TOOL_NAMES.BATCH,
+      phase: "parse_arguments",
+      details: { received: obj.commands.length },
+      retryable: false
+    });
+  }
+  const commands = obj.commands.map((c, i) => {
+    const cmd = asObject(c, TOOL_NAMES.BATCH);
+    const name = requireString(cmd, "name", TOOL_NAMES.BATCH);
+    if (name === TOOL_NAMES.BATCH) {
+      throw new RelayError({
+        code: "invalid_arguments",
+        message: `${TOOL_NAMES.BATCH}: command ${i} nests a batch inside a batch \u2014 not supported.`,
+        tool: TOOL_NAMES.BATCH,
+        phase: "parse_arguments",
+        details: { index: i },
+        retryable: false
+      });
+    }
+    return { name, args: cmd.args ?? {} };
+  });
+  return { commands, bail: optBool(obj, "bail", TOOL_NAMES.BATCH) ?? true };
+}
+function parseChromeGetArgs(input) {
+  const obj = asObject(input, TOOL_NAMES.GET);
+  const target = parseTargetArgs(obj, TOOL_NAMES.GET);
+  const what = requireString(obj, "what", TOOL_NAMES.GET);
+  if (!GET_WHATS.has(what)) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.GET}: \`what\` must be one of text | value | attr | count | title | url (got ${what}).`,
+      tool: TOOL_NAMES.GET,
+      phase: "parse_arguments",
+      details: { received: what },
+      retryable: false
+    });
+  }
+  if (what === "title" || what === "url") {
+    return { ...target, what };
+  }
+  if (what === "count") {
+    return { ...target, what, selector: requireString(obj, "selector", TOOL_NAMES.GET) };
+  }
+  const selector = optString(obj, "selector", TOOL_NAMES.GET);
+  const ref = optString(obj, "ref", TOOL_NAMES.GET);
+  if ((selector ? 1 : 0) + (ref ? 1 : 0) !== 1) {
+    throw new RelayError({
+      code: "invalid_arguments",
+      message: `${TOOL_NAMES.GET} ${what}: pass exactly one of \`selector\` or \`ref\`.`,
+      tool: TOOL_NAMES.GET,
+      phase: "parse_arguments",
+      details: { received: { selector, ref } },
+      retryable: false
+    });
+  }
+  if (what === "attr") {
+    return { ...target, what, attrName: requireString(obj, "attrName", TOOL_NAMES.GET), selector, ref };
+  }
+  return { ...target, what, selector, ref };
+}
+var LOAD_STATES, GET_WHATS;
+var init_loop = __esm({
+  "../protocol/dist/args/loop.js"() {
+    "use strict";
+    init_limits();
+    init_dist();
+    init_shared();
+    LOAD_STATES = /* @__PURE__ */ new Set(["load", "domcontentloaded", "networkidle"]);
+    GET_WHATS = /* @__PURE__ */ new Set(["text", "value", "attr", "count", "title", "url"]);
+  }
+});
+
 // ../protocol/dist/args/index.js
 function parseToolArgs(name, input) {
   switch (name) {
@@ -957,6 +1124,12 @@ function parseToolArgs(name, input) {
       return parseChromeScreencastArgs(input);
     case "chrome_snapshot":
       return parseChromeSnapshotArgs(input);
+    case "chrome_wait":
+      return parseChromeWaitArgs(input);
+    case "chrome_batch":
+      return parseChromeBatchArgs(input);
+    case "chrome_get":
+      return parseChromeGetArgs(input);
   }
   const exhaustive = name;
   return exhaustive;
@@ -970,33 +1143,16 @@ var init_args = __esm({
     init_network();
     init_simple();
     init_multi();
+    init_loop();
     init_navigate();
     init_hover();
     init_network();
     init_simple();
+    init_loop();
     init_multi();
   }
 });
 
-// ../protocol/dist/limits.js
-var DEFAULT_TOOL_CALL_TIMEOUT_MS, DEFAULT_PING_TIMEOUT_MS, DEFAULT_READY_TIMEOUT_MS, DEFAULT_EVAL_TIMEOUT_MS, DEFAULT_BODY_PREVIEW_BYTES, NETWORK_BUFFER_MAX_ENTRIES, NETWORK_BUFFER_MAX_BYTES, CONSOLE_BUFFER_MAX_ENTRIES, CONSOLE_BUFFER_MAX_BYTES, CONSOLE_ENTRY_TEXT_MAX_CHARS, CONSOLE_ENTRY_STACK_MAX_CHARS;
-var init_limits = __esm({
-  "../protocol/dist/limits.js"() {
-    "use strict";
-    DEFAULT_TOOL_CALL_TIMEOUT_MS = 3e4;
-    DEFAULT_PING_TIMEOUT_MS = 2e3;
-    DEFAULT_READY_TIMEOUT_MS = 15e3;
-    DEFAULT_EVAL_TIMEOUT_MS = 15e3;
-    DEFAULT_BODY_PREVIEW_BYTES = 8 * 1024;
-    NETWORK_BUFFER_MAX_ENTRIES = 200;
-    NETWORK_BUFFER_MAX_BYTES = 512 * 1024;
-    CONSOLE_BUFFER_MAX_ENTRIES = 200;
-    CONSOLE_BUFFER_MAX_BYTES = 256 * 1024;
-    CONSOLE_ENTRY_TEXT_MAX_CHARS = 1e3;
-    CONSOLE_ENTRY_STACK_MAX_CHARS = 1e3;
-  }
-});
-
 // ../protocol/dist/snapshot.js
 function parseRefToken(input) {
   const m = REF_TOKEN.exec(input.trim());
@@ -1085,13 +1241,19 @@ __export(dist_exports, {
   DEFAULT_PING_TIMEOUT_MS: () => DEFAULT_PING_TIMEOUT_MS,
   DEFAULT_READY_TIMEOUT_MS: () => DEFAULT_READY_TIMEOUT_MS,
   DEFAULT_TOOL_CALL_TIMEOUT_MS: () => DEFAULT_TOOL_CALL_TIMEOUT_MS,
+  DEFAULT_WAIT_TIMEOUT_MS: () => DEFAULT_WAIT_TIMEOUT_MS,
   LEGACY_DEV_EXTENSION_ID: () => LEGACY_DEV_EXTENSION_ID,
   LOCAL_UNPACKED_EXTENSION_ID: () => LOCAL_UNPACKED_EXTENSION_ID,
+  MAX_BATCH_BYTES: () => MAX_BATCH_BYTES,
+  MAX_BATCH_COMMANDS: () => MAX_BATCH_COMMANDS,
+  MAX_WAIT_TIMEOUT_MS: () => MAX_WAIT_TIMEOUT_MS,
   NATIVE_HOST_NAME: () => NATIVE_HOST_NAME,
+  NETWORKIDLE_QUIET_MS: () => NETWORKIDLE_QUIET_MS,
   NETWORK_BUFFER_MAX_BYTES: () => NETWORK_BUFFER_MAX_BYTES,
   NETWORK_BUFFER_MAX_ENTRIES: () => NETWORK_BUFFER_MAX_ENTRIES,
   RelayError: () => RelayError,
   TOOL_NAMES: () => TOOL_NAMES,
+  WAIT_POLL_INTERVAL_MS: () => WAIT_POLL_INTERVAL_MS,
   asObject: () => asObject,
   coerceTabId: () => coerceTabId,
   formatRefToken: () => formatRefToken,
@@ -1101,12 +1263,14 @@ __export(dist_exports, {
   optPositiveNumber: () => optPositiveNumber,
   optString: () => optString,
   parseChromeAxArgs: () => parseChromeAxArgs,
+  parseChromeBatchArgs: () => parseChromeBatchArgs,
   parseChromeClickArgs: () => parseChromeClickArgs,
   parseChromeClickAxArgs: () => parseChromeClickAxArgs,
   parseChromeCloseTabsArgs: () => parseChromeCloseTabsArgs,
   parseChromeConsoleArgs: () => parseChromeConsoleArgs,
   parseChromeEvaluateArgs: () => parseChromeEvaluateArgs,
   parseChromeFillArgs: () => parseChromeFillArgs,
+  parseChromeGetArgs: () => parseChromeGetArgs,
   parseChromeGroupArgs: () => parseChromeGroupArgs,
   parseChromeHoverArgs: () => parseChromeHoverArgs,
   parseChromeKeyboardArgs: () => parseChromeKeyboardArgs,
@@ -1120,6 +1284,7 @@ __export(dist_exports, {
   parseChromeSwitchTabArgs: () => parseChromeSwitchTabArgs,
   parseChromeTypeArgs: () => parseChromeTypeArgs,
   parseChromeViewportArgs: () => parseChromeViewportArgs,
+  parseChromeWaitArgs: () => parseChromeWaitArgs,
   parseChromeWorkspaceArgs: () => parseChromeWorkspaceArgs,
   parseGetWindowsAndTabsArgs: () => parseGetWindowsAndTabsArgs,
   parseRefToken: () => parseRefToken,
@@ -1209,7 +1374,17 @@ var init_dist = __esm({
       // Unified page snapshot (adoption-spec Change 1) — AX tree + cursor-
       // interactive sweep, one ref space, compact text rendered CLI-side.
       // Supersedes chrome_read_page and chrome_ax, which now alias to it.
-      SNAPSHOT: "chrome_snapshot"
+      SNAPSHOT: "chrome_snapshot",
+      // Adoption-spec Change 3 — block until a condition holds (selector/@ref
+      // visible, text present, URL glob, load state, JS truthy).
+      WAIT: "chrome_wait",
+      // Adoption-spec Change 5 — run N tool calls in one round-trip,
+      // sequentially, bail-on-error by default. Amortizes CLI startup + the
+      // HTTP/native-messaging hop.
+      BATCH: "chrome_batch",
+      // Adoption-spec Change 6 — one value (text/value/attr/count/title/url)
+      // without paying for a full snapshot.
+      GET: "chrome_get"
     };
     RelayError = class extends Error {
       code;
@@ -1244,7 +1419,7 @@ var init_dist = __esm({
 import { Command } from "commander";
 
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.6.0" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.7.0" : "0.0.0-dev";
 
 // src/commands/shared.ts
 init_dist();
@@ -1681,6 +1856,15 @@ async function runDoctor() {
 
 // src/release-notes.ts
 var RELEASE_NOTES = {
+  "0.7.0": [
+    "`wait` \u2014 block until a condition holds: `wait <css|@ref>` (exists and visible), `wait --text <s>`, `wait --url <glob>`, `wait --load load|domcontentloaded|networkidle`, `wait --fn <js>`, or `wait <ms>` for a plain sleep. One condition per call; default 10s, capped 25s (under the transport timeout, so waits always resolve in their own round-trip). Timeout errors include the page's current state so no follow-up probe is needed.",
+    "`snapshot --diff` \u2014 print only what changed since this tab's previous snapshot (unified hunks + an additions/removals count; ~100 tokens instead of a full re-read). The full snapshot is still taken and the ref map still refreshes \u2014 refs in the diff are current and clickable.",
+    "`get text|value|attr|count|title|url <target>` \u2014 one value, plain on stdout, no snapshot. Targets are @refs or CSS selectors; built for $(...) substitution.",
+    "`batch` \u2014 run up to 50 tool calls in ONE round-trip (one HTTP POST, one native-messaging message, sequential in the extension). Bail-on-error by default, `--no-bail` to continue; per-command result envelopes; nested batches rejected.",
+    "`skills get core` \u2014 the agent playbook is now inlined in the binary, always version-matched. `chrome-relay skills` lists; the same guide is hosted at https://chrome-relay.kushalsm.com/skill.md.",
+    "Top-level --help rewritten around the snapshot -> @ref loop (the old read -> selector flow was stale). Example URLs across help/docs now point at real pages.",
+    "Extension + CLI must both be 0.7.0 for wait/get/batch/--diff \u2014 an older extension returns unsupported_tool (update at chrome://extensions)."
+  ],
   "0.6.0": [
     "Unified `snapshot` with actionable @refs. `chrome-relay snapshot -i` renders the page as compact text (~4-5x smaller than the old `read -i`; 14 KB on the HN front page) \u2014 accessibility tree merged with a cursor-interactive sweep that catches div-soup clickables (cursor:pointer, onclick, tabindex, contenteditable) the AX tree misses. Every element gets a browser-unique @eN ref.",
     'Refs are actionable everywhere: `click @e12`, `fill @e14 "v"`, `hover @e3`, `type -s @e7`. A ref carries its tab \u2014 no --tab needed, a contradicting --tab is target_conflict, so an agent can never click into the page the user is reading. Resolution is backendNodeId fast-path with role+name+nth healing on same-page DOM churn (healed clicks report `healed: true`). Refs reach inside shadow DOM, where CSS selectors can\'t.',
@@ -1979,10 +2163,10 @@ function registerNavigation(ctx) {
       `
 
 Examples:
-  chrome-relay navigate "https://example.com"                    # navigate current tab
-  chrome-relay navigate --tab 123 "https://example.com"          # navigate an existing tab
-  chrome-relay navigate "https://example.com" --new              # open in a new background tab
-  chrome-relay navigate "https://example.com" --new --active     # open new tab AND show it to the user
+  chrome-relay navigate "https://chrome-relay.kushalsm.com"                    # navigate current tab
+  chrome-relay navigate --tab 123 "https://chrome-relay.kushalsm.com"          # navigate an existing tab
+  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
 existing) stay in whatever state they're in. Pass --active when you
@@ -1993,7 +2177,7 @@ actually want the user looking at the page.
     if (/^\d+$/.test(url)) {
       process.stderr.write(
         `navigate expects a URL, but "${url}" looks like a tab ID.
-Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate --tab ${url} https://example.com" to navigate it.
+Use "chrome-relay switch ${url}" to activate that tab, or "chrome-relay navigate --tab ${url} https://chrome-relay.kushalsm.com" to navigate it.
 `
       );
       process.exit(1);
@@ -2052,8 +2236,8 @@ where no DOM handle exists. See docs/clicking-strategies.md.
       `
 
 Examples:
-  chrome-relay fill @e4 "kushal@example.com"
-  chrome-relay fill 'input[name="email"]' "kushal@example.com"
+  chrome-relay fill @e4 "kushal@kushalsm.com"
+  chrome-relay fill 'input[name="email"]' "kushal@kushalsm.com"
 `
     )
   ).action(async (target, value, opts) => {
@@ -2143,6 +2327,32 @@ tooltip appearance, etc.) that a bare click would skip past too quickly.
 // src/commands/capture.ts
 init_dist();
 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.stdout.write(current + "\n");
+    return;
+  }
+  if (prevText === current) {
+    process.stdout.write("no changes since last snapshot\n");
+    return;
+  }
+  const patch = structuredPatch("prev", "current", prevText, current, "", "", { context: 3 });
+  let added = 0;
+  let removed = 0;
+  for (const hunk of patch.hunks) {
+    process.stdout.write(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@
+`);
+    for (const line of hunk.lines) {
+      if (line.startsWith("+")) added++;
+      else if (line.startsWith("-")) removed++;
+      process.stdout.write(line + "\n");
+    }
+  }
+  process.stdout.write(`${added} addition${added === 1 ? "" : "s"}, ${removed} removal${removed === 1 ? "" : "s"}
+`);
+}
 function printSnapshot(result, asJson) {
   if (asJson) {
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
@@ -2162,7 +2372,7 @@ 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("--json", "structured output: { title, url, tabId, nodes, refs }").addHelpText(
+    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(
       "after",
       `
 
@@ -2184,8 +2394,14 @@ error.code = stale_ref, which means: re-run snapshot.
     if (typeof opts.depth === "number") extras.depth = opts.depth;
     if (opts.scope) extras.scope = opts.scope;
     if (opts.urls) extras.urls = true;
+    if (opts.diff) extras.diff = true;
     try {
       const result = await callTool("chrome_snapshot", withBase(opts, extras));
+      if (opts.diff && !opts.json) {
+        const data = result;
+        printSnapshotDiff(renderSnapshot(data), data.prevText ?? null);
+        return;
+      }
       printSnapshot(result, opts.json === true);
     } catch (error) {
       exitWithError(error);
@@ -2568,7 +2784,7 @@ Notes:
 
 Examples:
   chrome-relay network --tab 123                              # last ${NETWORK_BUFFER_MAX_ENTRIES} requests
-  chrome-relay network --tab 123 --filter api.example.com      # url substring
+  chrome-relay network --tab 123 --filter api.kushalsm.com      # url substring
   chrome-relay network --tab 123 --status failed
   chrome-relay network --tab 123 --method POST
   chrome-relay network body <requestId> --tab 123              # lazy body fetch
@@ -2648,27 +2864,231 @@ Notes:
   });
 }
 
+// src/commands/loop.ts
+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.';
+  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";
+  }
+}
+function exitWithError2(error) {
+  if (error instanceof RelayError) {
+    process.stderr.write(error.message + "\n");
+    process.stderr.write(JSON.stringify({ relayError: error.toBridgeError() }, null, 2) + "\n");
+  } else {
+    process.stderr.write((error instanceof Error ? error.message : String(error)) + "\n");
+  }
+  process.exit(1);
+}
+function registerLoop(ctx) {
+  const { program, withBase, run } = ctx;
+  tabOpt(
+    program.command("wait [target]").description("Block until a condition holds: a selector/@ref is visible, text appears, the URL matches, the page loads, or a JS expression is truthy. Pass a number to just sleep.").option("--text <s>", "body text contains <s>").option("--url <glob>", "URL matches glob (** crosses /, * doesn't)").option("--load <state>", "load | domcontentloaded | networkidle").option("--fn <js>", "JS expression in the page; waits until truthy").option("--timeout <ms>", "max wait (default 10000, capped 25000)", (v) => Number(v)).addHelpText(
+      "after",
+      `
+
+Examples:
+  chrome-relay wait @e12                       # ref resolves and has a box
+  chrome-relay wait ".results" --tab 42        # selector exists and visible
+  chrome-relay wait --text "Welcome" --tab 42
+  chrome-relay wait --url "**/dashboard" --tab 42
+  chrome-relay wait --load networkidle --tab 42
+  chrome-relay wait --fn "window.__APP_READY === true" --tab 42
+  chrome-relay wait 1500                       # plain sleep, no tab needed
+
+Exactly one condition per call. On timeout the error includes the page's
+current state (url, readyState, whether the selector exists) so you don't
+need a follow-up probe.
+`
+    )
+  ).action(async (target, opts) => {
+    if (target && /^\d+$/.test(target)) {
+      const ms = Number(target);
+      await new Promise((r) => setTimeout(r, ms));
+      process.stdout.write(JSON.stringify({ satisfied: true, sleptMs: ms }) + "\n");
+      return;
+    }
+    const extras = {};
+    if (target) {
+      const ref = parseRefToken(target);
+      if (ref) extras.ref = ref;
+      else extras.selector = target;
+    }
+    if (opts.text) extras.text = opts.text;
+    if (opts.url) extras.urlGlob = opts.url;
+    if (opts.load) extras.load = opts.load;
+    if (opts.fn) extras.fn = opts.fn;
+    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(
+    "after",
+    `
+
+Examples:
+  chrome-relay get text @e12
+  chrome-relay get value 'input[name="email"]' --tab 42
+  chrome-relay get attr @e7 href
+  chrome-relay get count ".result" --tab 42
+  chrome-relay get title --tab 42
+  chrome-relay get url --tab 42
+`
+  );
+  const printValue = async (args) => {
+    try {
+      const result = await callTool(TOOL_NAMES.GET, args);
+      const v = result.value;
+      process.stdout.write((v === null || v === void 0 ? "" : String(v)) + "\n");
+    } catch (error) {
+      exitWithError2(error);
+    }
+  };
+  const addressArgs = (target) => {
+    const ref = parseRefToken(target);
+    return ref ? { ref } : { selector: target };
+  };
+  for (const what of ["text", "value"]) {
+    tabOpt(
+      get.command(`${what} <target>`).description(`${what === "text" ? "Visible text" : "Input value"} of a @ref or CSS selector.`)
+    ).action(async (target, opts) => {
+      await printValue(withBase(opts, { what, ...addressArgs(target) }));
+    });
+  }
+  tabOpt(
+    get.command("attr <target> <name>").description("Attribute value of a @ref or CSS selector.")
+  ).action(async (target, name, opts) => {
+    await printValue(withBase(opts, { what: "attr", attrName: name, ...addressArgs(target) }));
+  });
+  tabOpt(get.command("count <selector>").description("Number of elements matching a CSS selector.")).action(
+    async (selector, opts) => {
+      await printValue(withBase(opts, { what: "count", selector }));
+    }
+  );
+  tabOpt(get.command("title").description("Page title.")).action(async (opts) => {
+    await printValue(withBase(opts, { what: "title" }));
+  });
+  tabOpt(get.command("url").description("Page URL.")).action(async (opts) => {
+    await printValue(withBase(opts, { what: "url" }));
+  });
+  program.command("batch [json]").description("Run multiple tool calls in ONE round-trip, sequentially. JSON array of {name, args}, inline or via --stdin.").option("--stdin", "read the JSON array from stdin").option("--no-bail", "keep going after a failed command (default stops at first error)").addHelpText(
+    "after",
+    `
+
+Examples:
+  chrome-relay batch '[
+    {"name":"chrome_navigate","args":{"url":"https://chrome-relay.kushalsm.com","newTab":true}},
+    {"name":"chrome_wait","args":{"load":"load"}},
+    {"name":"chrome_snapshot","args":{"interactiveOnly":true}}
+  ]'
+  cat commands.json | chrome-relay batch --stdin
+
+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
+startup across N actions. Nested batches are rejected.
+`
+  ).action(async (json, opts) => {
+    try {
+      let raw = json;
+      if (opts.stdin) {
+        raw = readFileSync(0, "utf8");
+      }
+      if (!raw) {
+        throw new RelayError({
+          code: "invalid_arguments",
+          message: "chrome-relay batch: pass a JSON array inline or via --stdin.",
+          tool: TOOL_NAMES.BATCH,
+          phase: "parse_arguments",
+          retryable: false
+        });
+      }
+      if (Buffer.byteLength(raw, "utf8") > MAX_BATCH_BYTES) {
+        throw new RelayError({
+          code: "invalid_arguments",
+          message: `chrome-relay batch: input exceeds ${MAX_BATCH_BYTES} bytes (native-messaging frame safety). Split the batch.`,
+          tool: TOOL_NAMES.BATCH,
+          phase: "parse_arguments",
+          retryable: false
+        });
+      }
+      let commands;
+      try {
+        commands = JSON.parse(raw);
+      } catch (e) {
+        throw new RelayError({
+          code: "invalid_arguments",
+          message: `chrome-relay batch: input is not valid JSON (${e instanceof Error ? e.message : e}).`,
+          tool: TOOL_NAMES.BATCH,
+          phase: "parse_arguments",
+          retryable: false
+        });
+      }
+      const result = await callTool(TOOL_NAMES.BATCH, { commands, bail: opts.bail !== false });
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      const failed = result.results?.some((r) => !r.ok);
+      if (failed) process.exit(1);
+    } catch (error) {
+      exitWithError2(error);
+    }
+  });
+  const skills = program.command("skills [verb] [name]").description("Agent playbooks shipped inside the CLI \u2014 always version-matched to the binary.").addHelpText(
+    "after",
+    `
+
+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.
+`
+  );
+  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");
+      return;
+    }
+    if (verb === "get" && (name === "core" || name === void 0)) {
+      process.stdout.write(coreSkillText() + "\n");
+      return;
+    }
+    process.stderr.write(`Unknown skill command: ${verb}${name ? ` ${name}` : ""}. Try \`chrome-relay skills\` or \`chrome-relay skills get core\`.
+`);
+    process.exit(1);
+  });
+}
+
 // src/program.ts
 function buildProgram() {
   const program = new Command();
-  program.name("chrome-relay").description("Connect your local Chrome browser to coding agents through a local bridge.").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 \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(
     "after",
     `
 
-Common agent flow:
+The core loop:
   chrome-relay tabs
-  chrome-relay navigate --tab <tabId> "https://example.com"
-  chrome-relay read --tab <tabId> -i
-  chrome-relay click --tab <tabId> "<selector>"
-  chrome-relay fill --tab <tabId> "<selector>" "value"
-  chrome-relay type --tab <tabId> -s "<selector>" "text into rich editor"
+  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 fill @e14 "value"
+  chrome-relay snapshot --tab <tabId> -i                 # re-look after the page changes
+
+Also:
+  chrome-relay wait --tab <tabId> --text "Welcome"       # selector/@ref/text/url/load/fn
+  chrome-relay get text @e12                             # one value, no full snapshot
   chrome-relay keys --tab <tabId> Enter
   chrome-relay js --tab <tabId> "return document.title"
   chrome-relay screenshot --tab <tabId> -o evidence.png
+  chrome-relay skills get core                           # the agent playbook, version-matched
 
 Notes:
-  navigate takes a URL. Use --tab to target an existing tab.
-  Tools attach via CDP and run on backgrounded tabs without stealing focus.
+  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).
 `
   );
   const baseArgs = makeBaseArgs(program);
@@ -2683,6 +3103,7 @@ Notes:
   registerInput(ctx);
   registerCapture(ctx);
   registerSessions(ctx);
+  registerLoop(ctx);
   return program;
 }
 

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var CHROME_RELAY_VERSION = true ? "0.6.0" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.7.0" : "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.6.0" : "0.0.0-dev";
+var CHROME_RELAY_VERSION = true ? "0.7.0" : "0.0.0-dev";
 
 // src/release-notes.ts
 function compareSemver(a, b) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-relay",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,16 +16,24 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run"
   },
-  "description": "Connect your local Chrome browser to coding agents through a local bridge.",
-  "keywords": ["chrome", "browser", "automation", "agents", "native-messaging"],
+  "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",
+    "automation",
+    "agents",
+    "native-messaging"
+  ],
   "license": "MIT",
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
+    "diff": "^7.0.0",
     "fastify": "^5.3.2"
   },
   "devDependencies": {
     "@chrome-relay/protocol": "workspace:*",
+    "@types/diff": "^7",
     "tsup": "^8.4.0",
     "vitest": "^3.0.0"
   }