agentbrowse 0.0.3 → 0.1.1

package/AGENTS.md

@@ -21,7 +21,8 @@ agentbrowse read --page 2                    # next chunk if it was truncated
 ## Rules that make this reliable
 
 - **Read with `--json`** when you need to parse: `read --json` gives `{ title, markdown, page, totalPages, state }`. Every command's text output ends with a `url | title | links` footer so you always know where you are.
-- **Targeting `click`/`type`**, in priority order: (1) visible text — `click "Sign in"`; (2) a number from the last `links`/`find` — `click 2`; (3) a CSS selector — `click "button.primary"`. Bare words are treated as visible text; use explicit CSS for elements without text.
+- **Prefer `snapshot` for acting.** `snapshot` returns every actionable element as `[ref] role "name" (state)` — e.g. `[3] button "Search"`. Then act by ref: `click 3`, `type 2 "shoes"`. Refs resolve by role+name, so they survive CSS/DOM changes — far more reliable than selectors. If the page changed and a ref is stale, the tool returns a **fresh snapshot** in the error (`stale_ref`); just re-pick from it.
+- **Other `click`/`type` targeting**, in priority order: (1) a `snapshot` ref — `click 3`; (2) visible text — `click "Sign in"`; (3) a number from the last `links`/`find`; (4) a CSS selector — `click "button.primary"`. Bare words are visible text; use explicit CSS for elements without text.
 - **Forms:** `fill -f email=me@x.com -f password=...` then `submit`. Or `type <field> <text>` for one field. Fields match by `name`, or pass a CSS selector.
 - **Truncation:** `read` is capped (`--max-chars`, default 8000). If `truncated`, request `--page 2`, etc. Don't assume you've seen the whole page from page 1.
 - **Errors:** non-zero exit codes mean failure; the reason is on **stderr** as `{ "error": { code, message } }`. `4` = target not found (re-run `links`/`find` to get fresh numbers), `3` = navigation problem, `2` = bad usage, `5` = daemon problem.

package/README.md

@@ -41,8 +41,9 @@ Sessions are isolated by `--session <id>` (default `default`), each with its own
 | `open <url>` | Navigate the session to a URL |
 | `read [url]` | Current page (or open `<url>` first) as token-bounded markdown (`--max-chars`, `--page`) |
 | `links [url]` | Numbered, followable links (`--filter`) |
-| `find <text>` | Locate elements by visible text; numbers reusable by `click` |
-| `click <target>` | Click by visible text, a number from `links`/`find`, or a CSS selector |
+| `snapshot [url]` | **Accessibility-tree view**: every actionable element with a stable `[ref]`, role, name, state (`--filter`, `--max`, `--json`). The robust way to act |
+| `find <text>` | Locate elements by visible text (falls back to accessible name); numbers reusable by `click` |
+| `click <target>` | Click by a `snapshot` ref (robust), visible text, a `links`/`find` number, or a CSS selector |
 | `type <field> <text>` | Type into a field (CSS selector or bare `name`) |
 | `fill -f name=value …` | Fill form fields |
 | `submit [form]` | Submit the current form |

package/dist/cli.js

@@ -3,6 +3,52 @@
 // src/cli.ts
 import { Command } from "commander";
 
+// package.json
+var package_default = {
+  name: "agentbrowse",
+  version: "0.1.1",
+  description: "Agent-browser CLI: drive any website from the terminal.",
+  type: "module",
+  bin: {
+    agentbrowse: "dist/cli.js"
+  },
+  files: [
+    "dist",
+    "AGENTS.md"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  scripts: {
+    build: "tsup",
+    dev: "tsx src/cli.ts",
+    test: "vitest run",
+    "test:watch": "vitest",
+    prepublishOnly: "npm run build && npm test"
+  },
+  dependencies: {
+    "@mozilla/readability": "^0.6.0",
+    ajv: "^8.17.1",
+    commander: "^12.1.0",
+    jsdom: "^24.1.0",
+    playwright: "^1.45.0",
+    turndown: "^7.2.0"
+  },
+  devDependencies: {
+    "@types/jsdom": "^21.1.0",
+    "@types/node": "^20.14.0",
+    "@types/turndown": "^5.0.4",
+    tsup: "^8.1.0",
+    tsx: "^4.16.0",
+    typescript: "^5.5.0",
+    vitest: "^2.0.0"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/mandarwagh9/agentbrowse.git"
+  }
+};
+
 // src/daemon/client.ts
 import net from "net";
 import path2 from "path";
@@ -134,6 +180,7 @@ var DAEMON_CODE_EXIT = {
   bad_args: EXIT.usage,
   unknown_cmd: EXIT.usage,
   target_not_found: EXIT.targetNotFound,
+  stale_ref: EXIT.targetNotFound,
   exec_error: EXIT.navigation
 };
 function fromDaemon(res) {
@@ -228,6 +275,31 @@ async function runLinks(opts) {
   return data.links.map((l) => `${l.n}. ${l.text}  ->  ${l.href}`).join("\n");
 }
 
+// src/commands/snapshot.ts
+async function runSnapshot(opts) {
+  if (opts.url) {
+    const o = await sendRequest(opts.session, { id: nextId(), cmd: "open", args: { url: opts.url } });
+    if (!o.ok) throw fromDaemon(o);
+  }
+  const res = await sendRequest(opts.session, {
+    id: nextId(),
+    cmd: "snapshot",
+    args: { filter: opts.filter, max: opts.max }
+  });
+  if (!res.ok) throw fromDaemon(res);
+  const d = res.data;
+  if (opts.json) return JSON.stringify(d, null, 2);
+  const lines = d.elements.map((e) => {
+    const state = [e.disabled ? "disabled" : "", e.checked ? "checked" : ""].filter(Boolean).join(" ");
+    return `[${e.ref}] ${e.role.padEnd(9)} "${e.name}"${e.href ? `  -> ${e.href}` : ""}${state ? `  (${state})` : ""}`;
+  });
+  const more = d.total > d.elements.length ? `
+(+${d.total - d.elements.length} more \u2014 narrow with --filter)` : "";
+  return `${lines.join("\n") || "(no actionable elements)"}${more}
+---
+snapshot v${d.version} | url: ${d.url} | ${d.elements.length} actionable elements`;
+}
+
 // src/commands/stop.ts
 async function runStop(session) {
   try {
@@ -568,6 +640,60 @@ function extractLinks(html, baseUrl, filter) {
   return out;
 }
 
+// src/core/snapshot.ts
+var ACTIONABLE = /* @__PURE__ */ new Set([
+  "link",
+  "button",
+  "textbox",
+  "searchbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab",
+  "switch",
+  "slider",
+  "spinbutton",
+  "option"
+]);
+var LINE = /^\s*-\s+([a-z][\w-]*)(?:\s+"((?:[^"\\]|\\.)*)")?(?:\s+\[([^\]]*)\])?:?\s*$/;
+var URL2 = /^\s*-\s+\/url:\s*"?([^"\n]*?)"?\s*$/;
+function parseAriaSnapshot(yaml) {
+  const out = [];
+  const counts = /* @__PURE__ */ new Map();
+  for (const raw of yaml.split("\n")) {
+    const url = raw.match(URL2);
+    if (url) {
+      const last = out[out.length - 1];
+      if (last && last.role === "link") last.href = url[1];
+      continue;
+    }
+    const m = raw.match(LINE);
+    if (!m) continue;
+    const role = m[1];
+    const name = (m[2] ?? "").replace(/\\"/g, '"');
+    const states = (m[3] ?? "").split(/[\s,]+/).filter(Boolean);
+    const actionable = ACTIONABLE.has(role);
+    const el = { role, name, actionable, nth: 0 };
+    for (const s of states) {
+      if (s === "disabled") el.disabled = true;
+      else if (s === "checked") el.checked = true;
+      else if (s.startsWith("level=")) el.level = Number(s.slice(6));
+    }
+    if (actionable) {
+      const key = `${role} ${name}`;
+      const n = counts.get(key) ?? 0;
+      el.nth = n;
+      counts.set(key, n + 1);
+    }
+    out.push(el);
+  }
+  return out;
+}
+
 // src/core/target.ts
 function looksLikeSelector(s) {
   const t = s.trim();
@@ -599,6 +725,39 @@ async function startDaemon(sessionId, opts = {}) {
   const context = await browser.newContext(statePath ? { storageState: statePath } : {});
   const page = await context.newPage();
   let lastRefs = [];
+  let snapshotVersion = 0;
+  let snapshotRefs = /* @__PURE__ */ new Map();
+  page.on("framenavigated", (f) => {
+    if (f === page.mainFrame()) snapshotVersion++;
+  });
+  async function freshSnapshot(filter, max = 150) {
+    const yaml = await page.locator("body").ariaSnapshot();
+    const all = parseAriaSnapshot(yaml).filter((e) => e.actionable);
+    const f = filter?.toLowerCase();
+    const shown = all.filter((e) => !f || `${e.role} ${e.name}`.toLowerCase().includes(f)).slice(0, max);
+    snapshotRefs = /* @__PURE__ */ new Map();
+    const elements = shown.map((e, i) => {
+      const ref = i + 1;
+      snapshotRefs.set(ref, { role: e.role, name: e.name, nth: e.nth });
+      return { ref, role: e.role, name: e.name, href: e.href, disabled: e.disabled, checked: e.checked };
+    });
+    return { elements, total: all.length };
+  }
+  async function staleRef(req) {
+    const fresh = await freshSnapshot();
+    return {
+      id: req.id,
+      ok: false,
+      error: { code: "stale_ref", message: "snapshot is stale; use the fresh refs" },
+      data: { version: snapshotVersion, url: page.url(), elements: fresh.elements }
+    };
+  }
+  function refLocator(target) {
+    if (!/^\d+$/.test(target)) return null;
+    const entry = snapshotRefs.get(parseInt(target, 10));
+    if (!entry) return null;
+    return page.getByRole(entry.role, { name: entry.name, exact: true }).nth(entry.nth);
+  }
   const settle = () => page.waitForLoadState("domcontentloaded").catch(() => {
   });
   async function dispatch(req) {
@@ -631,7 +790,16 @@ async function startDaemon(sessionId, opts = {}) {
         case "find": {
           const text = String(req.args?.text ?? "");
           if (!text) return err(req, "bad_args", "find requires text");
-          const matches = await page.getByText(text, { exact: false }).all();
+          let matches = await page.getByText(text, { exact: false }).all();
+          if (matches.length === 0) {
+            const needle = text.toLowerCase();
+            const named = parseAriaSnapshot(await page.locator("body").ariaSnapshot()).filter(
+              (e) => e.actionable && e.name.toLowerCase().includes(needle)
+            );
+            matches = named.map(
+              (e) => page.getByRole(e.role, { name: e.name, exact: true }).nth(e.nth)
+            );
+          }
           lastRefs = matches.map((locator) => ({ kind: "element", locator }));
           const items = await Promise.all(
             matches.map(async (loc, i) => ({
@@ -645,6 +813,13 @@ async function startDaemon(sessionId, opts = {}) {
         case "click": {
           const target = String(req.args?.target ?? "");
           if (!target) return err(req, "bad_args", "click requires a target");
+          const snapLoc = refLocator(target);
+          if (snapLoc) {
+            if (await snapLoc.count() === 0) return staleRef(req);
+            await snapLoc.click();
+            await settle();
+            return ok(req, { url: page.url(), title: await page.title() });
+          }
           if (/^\d+$/.test(target)) {
             const ref = lastRefs[parseInt(target, 10) - 1];
             if (!ref) return err(req, "target_not_found", `no ref #${target}; run links or find first`);
@@ -666,6 +841,12 @@ async function startDaemon(sessionId, opts = {}) {
           const selector = String(req.args?.selector ?? "");
           const text = String(req.args?.text ?? "");
           if (!selector) return err(req, "bad_args", "type requires a selector");
+          const snapField = refLocator(selector);
+          if (snapField) {
+            if (await snapField.count() === 0) return staleRef(req);
+            await snapField.fill(text);
+            return ok(req, { typed: selector, url: page.url() });
+          }
           const loc = resolveField(page, selector);
           if (await loc.count() === 0) return err(req, "target_not_found", `no field matching: ${selector}`);
           await loc.fill(text);
@@ -695,6 +876,12 @@ async function startDaemon(sessionId, opts = {}) {
           await settle();
           return ok(req, { url: page.url(), title: await page.title() });
         }
+        case "snapshot": {
+          const filter = req.args?.filter ? String(req.args.filter) : void 0;
+          const max = Number(req.args?.max ?? 150);
+          const { elements, total } = await freshSnapshot(filter, max);
+          return ok(req, { version: snapshotVersion, url: page.url(), elements, total });
+        }
         case "savestate": {
           const p = ensureStatePath(sessionId);
           await context.storageState({ path: p });
@@ -779,7 +966,7 @@ async function emit(produce) {
 }
 function buildProgram() {
   const program = new Command();
-  program.name("agentbrowse").description("Agent-browser CLI: drive any website from the terminal.").version("0.0.1").option("--session <id>", "session name (isolated browser + cookies)", "default");
+  program.name("agentbrowse").description("Agent-browser CLI: drive any website from the terminal.").version(package_default.version).option("--session <id>", "session name (isolated browser + cookies)", "default");
   const session = (cmd) => cmd.optsWithGlobals().session;
   program.command("open").description("Navigate the session's browser to a URL.").argument("<url>", "URL to open").option("--json", "structured JSON output", false).action((url, opts, cmd) => emit(() => runOpen({ session: session(cmd), json: !!opts.json, url })));
   program.command("read").description("Read the current page (or open <url> first) as token-bounded markdown.").argument("[url]", "optional URL to open before reading").option("--json", "structured JSON output", false).option("--max-chars <n>", "max characters per page", (v) => parseInt(v, 10), 8e3).option("--page <n>", "page number when output is truncated", (v) => parseInt(v, 10), 1).action(
@@ -790,6 +977,9 @@ function buildProgram() {
   program.command("links").description("List navigable links on the current page (or open <url> first).").argument("[url]", "optional URL to open before listing").option("--json", "structured JSON output", false).option("--filter <text>", "case-insensitive substring filter").action(
     (url, opts, cmd) => emit(() => runLinks({ session: session(cmd), json: !!opts.json, filter: opts.filter, url }))
   );
+  program.command("snapshot").description("List actionable elements (accessibility tree) with refs for click/type.").argument("[url]", "optional URL to open before snapshotting").option("--json", "structured JSON output", false).option("--filter <text>", "case-insensitive substring filter").option("--max <n>", "max elements", (v) => parseInt(v, 10), 150).action(
+    (url, opts, cmd) => emit(() => runSnapshot({ session: session(cmd), json: !!opts.json, filter: opts.filter, max: opts.max, url }))
+  );
   program.command("find").description("Find elements on the current page by visible text (numbers reusable by click).").argument("<text...>", "visible text to search for").option("--json", "structured JSON output", false).action(
     (text, opts, cmd) => emit(() => runFind({ session: session(cmd), json: !!opts.json, text: text.join(" ") }))
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentbrowse",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "description": "Agent-browser CLI: drive any website from the terminal.",
   "type": "module",
   "bin": {