agentbrowse 0.0.1

package/AGENTS.md

@@ -0,0 +1,47 @@
+# Using agentbrowse (for AI agents)
+
+You can drive a real browser from the shell with `agentbrowse`. Prefer it over guessing at URLs or asking the user to click things.
+
+## Mental model
+
+- A **session** is a live browser that persists between your commands. Run `agentbrowse open <url>` once, then `read`, `click`, `find`, `fill`, `submit` operate on that same page. The session keeps cookies and scroll/DOM state.
+- Default session is `default`. Use `--session <id>` to keep independent sessions (e.g. one per site or task).
+- When done, run `agentbrowse stop` to free the browser. It also self-stops after a few minutes idle.
+
+## The loop you'll usually run
+
+```bash
+agentbrowse open https://docs.example.com   # go somewhere
+agentbrowse read                            # read it (clean markdown, token-bounded)
+agentbrowse links --filter api              # find where to go next (numbered)
+agentbrowse click 3                         # follow link #3
+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.
+- **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.
+
+## Authentication
+
+Do **not** try to type passwords. If a page needs login, tell the user to run:
+
+```bash
+agentbrowse login https://site/login --session <id>
+```
+
+A real browser opens for them to log in; the session is then saved and you can operate headlessly. Never put credentials in command arguments.
+
+## Site manifests
+
+If a `site.agent.json` exists for the target, you get named shortcuts:
+
+```bash
+agentbrowse --site ./site.agent.json <command> [args...]
+```
+
+These run predefined multi-step flows (open → type → submit → read) and return the final read output. Check the manifest's `commands` for what's available.

package/README.md

@@ -0,0 +1,71 @@
+# agentbrowse
+
+**Drive any website from the terminal — built for AI coding agents.**
+
+Agents (Claude Code, Codex, …) are great at running CLIs and clumsy at clicking through web UIs. `agentbrowse` gives them a clean, parseable surface: open a page, read it as token-bounded markdown, follow links, fill and submit forms, and operate behind a login — all from terminal commands, with a persistent browser session that survives across invocations.
+
+> There is no separate web interface to wire up. The agent runs `agentbrowse` and gets structured output back.
+
+## Install
+
+```bash
+npm install -g agentbrowse
+# first run downloads the browser:
+npx playwright install chromium
+```
+
+## Quickstart
+
+```bash
+agentbrowse open https://example.com    # navigate the session
+agentbrowse read                        # current page as clean markdown
+agentbrowse links                       # numbered, followable links
+agentbrowse click "Learn more"          # click by visible text...
+agentbrowse click 2                     # ...or by a number from links/find
+agentbrowse read --json                 # structured output for machines
+agentbrowse stop                        # end the session (frees the browser)
+```
+
+`read`/`links` accept an optional URL to open first, so `agentbrowse read https://x.com` is "open then read" in one step.
+
+## How it works
+
+A **background browser daemon** (auto-spawned per session, local socket only) holds a live Playwright page, so state persists between separate commands — `open`, then later `click`, then `read`, all hit the same page. The daemon self-stops after inactivity.
+
+Sessions are isolated by `--session <id>` (default `default`), each with its own cookies and saved auth.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `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 |
+| `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 |
+| `login <url>` | Open a real browser to authenticate once; persists the session for headless reuse |
+| `session save\|load\|clear` | Manage saved auth/session state |
+| `stop` | Stop the session's browser daemon |
+
+Add `--json` to any command for structured output. Errors go to **stderr** as `{ "error": { code, message } }` with a non-zero exit code (2 usage, 3 navigation, 4 target-not-found, 5 daemon).
+
+## Authentication
+
+`agentbrowse login https://site/login` opens a **real browser window** for *you* to log in (handling SSO, MFA, captchas an agent can't). On success it saves the session's cookies locally (`~/.webcli/sessions/<id>/`, gitignored); the agent then operates headlessly with that session. **Credentials are typed into the browser by a human — never passed as CLI arguments.**
+
+## Site manifests (optional)
+
+Point `agentbrowse` at a `site.agent.json` to expose named, high-level commands for a specific site:
+
+```bash
+agentbrowse --site ./notion.agent.json search "roadmap"
+```
+
+A manifest declares `pages`, `selectors`, and `commands` as ordered steps with `{pages.*}` / `{selectors.*}` / `{arg}` / `${ENV}` interpolation. Schema version: `webcli-manifest-v0`. See `AGENTS.md` for the agent-usage guide and the manifest format.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,857 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/daemon/client.ts
+import net from "net";
+import path2 from "path";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+// src/daemon/protocol.ts
+function encode(msg) {
+  return JSON.stringify(msg) + "\n";
+}
+var _seq = 0;
+function nextId() {
+  return String(++_seq);
+}
+var LineBuffer = class {
+  buf = "";
+  push(chunk) {
+    this.buf += chunk;
+    const lines = [];
+    let idx;
+    while ((idx = this.buf.indexOf("\n")) >= 0) {
+      lines.push(this.buf.slice(0, idx));
+      this.buf = this.buf.slice(idx + 1);
+    }
+    return lines;
+  }
+};
+
+// src/daemon/paths.ts
+import os from "os";
+import path from "path";
+function socketPath(sessionId, platform = process.platform) {
+  if (platform === "win32") return `\\\\.\\pipe\\webcli-${sessionId}`;
+  return path.join(os.tmpdir(), `webcli-${sessionId}.sock`);
+}
+function profileDir(sessionId, home = process.env.WEBCLI_HOME || os.homedir()) {
+  return path.join(home, ".webcli", "sessions", sessionId);
+}
+
+// src/daemon/client.ts
+function trySend(sockPath, req) {
+  return new Promise((resolve, reject) => {
+    const conn = net.connect(sockPath);
+    const buf = new LineBuffer();
+    let settled = false;
+    conn.on("connect", () => conn.write(encode(req)));
+    conn.on("data", (chunk) => {
+      const lines = buf.push(chunk.toString());
+      if (lines.length && !settled) {
+        settled = true;
+        resolve(JSON.parse(lines[0]));
+        conn.end();
+      }
+    });
+    conn.on("error", (e) => {
+      if (!settled) {
+        settled = true;
+        reject(e);
+      }
+    });
+  });
+}
+function daemonCommand(sessionId) {
+  const here = fileURLToPath(import.meta.url);
+  if (here.endsWith(".ts")) {
+    const cliEntry = path2.resolve(path2.dirname(here), "..", "cli.ts");
+    return { cmd: process.execPath, args: ["--import", "tsx", cliEntry, "__daemon", sessionId] };
+  }
+  return { cmd: process.execPath, args: [here, "__daemon", sessionId] };
+}
+function canConnect(sockPath) {
+  return new Promise((resolve) => {
+    const c = net.connect(sockPath);
+    c.on("connect", () => {
+      c.end();
+      resolve(true);
+    });
+    c.on("error", () => resolve(false));
+  });
+}
+async function waitForSocket(sockPath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await canConnect(sockPath)) return;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error(`daemon for socket ${sockPath} did not start within ${timeoutMs}ms`);
+}
+async function spawnDaemon(sessionId, sockPath) {
+  const { cmd, args } = daemonCommand(sessionId);
+  const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+  child.unref();
+  await waitForSocket(sockPath, 15e3);
+}
+async function sendRequest(sessionId, req, opts = {}) {
+  const sockPath = socketPath(sessionId);
+  const autoSpawn = opts.autoSpawn !== false;
+  try {
+    return await trySend(sockPath, req);
+  } catch (e) {
+    if (!autoSpawn) throw e;
+    await spawnDaemon(sessionId, sockPath);
+    return await trySend(sockPath, req);
+  }
+}
+
+// src/commands/errors.ts
+var EXIT = {
+  ok: 0,
+  internal: 1,
+  usage: 2,
+  navigation: 3,
+  targetNotFound: 4,
+  daemon: 5
+};
+var WebcliError = class extends Error {
+  constructor(code, message, exitCode, hint) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.hint = hint;
+    this.name = "WebcliError";
+  }
+  code;
+  exitCode;
+  hint;
+};
+var DAEMON_CODE_EXIT = {
+  bad_args: EXIT.usage,
+  unknown_cmd: EXIT.usage,
+  target_not_found: EXIT.targetNotFound,
+  exec_error: EXIT.navigation
+};
+function fromDaemon(res) {
+  const e = res.error ?? { code: "unknown", message: "request failed" };
+  return new WebcliError(e.code, e.message, DAEMON_CODE_EXIT[e.code] ?? EXIT.internal, e.hint);
+}
+function formatError(err2) {
+  if (err2 instanceof WebcliError) {
+    return JSON.stringify({ error: { code: err2.code, message: err2.message, hint: err2.hint } });
+  }
+  return JSON.stringify({ error: { code: "internal", message: err2.message } });
+}
+
+// src/commands/open.ts
+async function runOpen(opts) {
+  const res = await sendRequest(opts.session, { id: nextId(), cmd: "open", args: { url: opts.url } });
+  if (!res.ok) throw fromDaemon(res);
+  const d = res.data;
+  if (opts.json) return JSON.stringify(d, null, 2);
+  return `opened [${d.status}] ${d.title}
+---
+url: ${d.url}`;
+}
+
+// src/core/bound.ts
+function boundText(text, maxChars, page) {
+  const totalPages = Math.max(1, Math.ceil(text.length / maxChars));
+  const clamped = Math.min(Math.max(1, page), totalPages);
+  const start = (clamped - 1) * maxChars;
+  const slice = text.slice(start, start + maxChars);
+  return {
+    text: slice,
+    page: clamped,
+    totalPages,
+    truncated: totalPages > 1
+  };
+}
+
+// src/core/output.ts
+function footer(state) {
+  const fields = state.fields.length ? ` | fields: ${state.fields.join(", ")}` : "";
+  return `
+---
+url: ${state.url} | title: ${state.title} | links: ${state.links}${fields}`;
+}
+
+// src/commands/read.ts
+async function runRead(opts) {
+  if (opts.url) {
+    const opened = await sendRequest(opts.session, { id: nextId(), cmd: "open", args: { url: opts.url } });
+    if (!opened.ok) throw fromDaemon(opened);
+  }
+  const res = await sendRequest(opts.session, { id: nextId(), cmd: "read" });
+  if (!res.ok) throw fromDaemon(res);
+  const data = res.data;
+  const bounded = boundText(data.markdown, opts.maxChars, opts.page);
+  const state = { url: data.url, title: data.title, links: data.links, fields: data.fields };
+  if (opts.json) {
+    return JSON.stringify(
+      {
+        title: data.title,
+        markdown: bounded.text,
+        page: bounded.page,
+        totalPages: bounded.totalPages,
+        truncated: bounded.truncated,
+        state
+      },
+      null,
+      2
+    );
+  }
+  const note = bounded.truncated ? `
+[truncated: page ${bounded.page}/${bounded.totalPages}, use --page ${Math.min(bounded.page + 1, bounded.totalPages)}]` : "";
+  return bounded.text + note + footer(state);
+}
+
+// src/commands/links.ts
+async function runLinks(opts) {
+  if (opts.url) {
+    const opened = await sendRequest(opts.session, { id: nextId(), cmd: "open", args: { url: opts.url } });
+    if (!opened.ok) throw fromDaemon(opened);
+  }
+  const res = await sendRequest(opts.session, {
+    id: nextId(),
+    cmd: "links",
+    args: opts.filter ? { filter: opts.filter } : {}
+  });
+  if (!res.ok) throw fromDaemon(res);
+  const data = res.data;
+  if (opts.json) return JSON.stringify({ url: data.url, links: data.links }, null, 2);
+  if (data.links.length === 0) return "(no links found)";
+  return data.links.map((l) => `${l.n}. ${l.text}  ->  ${l.href}`).join("\n");
+}
+
+// src/commands/stop.ts
+async function runStop(session) {
+  try {
+    const res = await sendRequest(session, { id: nextId(), cmd: "stop" }, { autoSpawn: false });
+    return res.ok ? `stopped session '${session}'` : `error: ${res.error?.message ?? "stop failed"}`;
+  } catch {
+    return `no daemon running for session '${session}'`;
+  }
+}
+
+// src/commands/interact.ts
+function stateLine(d) {
+  return `---
+url: ${d.url}${d.title ? ` | title: ${d.title}` : ""}`;
+}
+async function runClick(opts) {
+  const res = await sendRequest(opts.session, { id: nextId(), cmd: "click", args: { target: opts.target } });
+  if (!res.ok) throw fromDaemon(res);
+  const d = res.data;
+  return opts.json ? JSON.stringify(d, null, 2) : `clicked: ${opts.target}
+${stateLine(d)}`;
+}
+async function runFind(opts) {
+  const res = await sendRequest(opts.session, { id: nextId(), cmd: "find", args: { text: opts.text } });
+  if (!res.ok) throw fromDaemon(res);
+  const d = res.data;
+  if (opts.json) return JSON.stringify(d, null, 2);
+  if (d.matches.length === 0) return `(no matches for "${opts.text}")`;
+  return d.matches.map((m) => `${m.n}. <${m.tag}> ${m.text}`).join("\n");
+}
+async function runType(opts) {
+  const res = await sendRequest(opts.session, {
+    id: nextId(),
+    cmd: "type",
+    args: { selector: opts.selector, text: opts.text }
+  });
+  if (!res.ok) throw fromDaemon(res);
+  return opts.json ? JSON.stringify(res.data, null, 2) : `typed into ${opts.selector}`;
+}
+async function runFill(opts) {
+  const res = await sendRequest(opts.session, { id: nextId(), cmd: "fill", args: { fields: opts.fields } });
+  if (!res.ok) throw fromDaemon(res);
+  const d = res.data;
+  return opts.json ? JSON.stringify(d, null, 2) : `filled: ${d.filled.join(", ")}`;
+}
+async function runSubmit(opts) {
+  const res = await sendRequest(opts.session, {
+    id: nextId(),
+    cmd: "submit",
+    args: opts.form ? { form: opts.form } : {}
+  });
+  if (!res.ok) throw fromDaemon(res);
+  const d = res.data;
+  return opts.json ? JSON.stringify(d, null, 2) : `submitted
+${stateLine(d)}`;
+}
+
+// src/commands/login.ts
+import readline from "readline";
+import { chromium } from "playwright";
+
+// src/core/session.ts
+import fs from "fs";
+import path3 from "path";
+function stateFilePath(session) {
+  return path3.join(profileDir(session), "storageState.json");
+}
+function hasState(session) {
+  return fs.existsSync(stateFilePath(session));
+}
+function loadStatePath(session) {
+  return hasState(session) ? stateFilePath(session) : void 0;
+}
+function ensureStatePath(session) {
+  const p = stateFilePath(session);
+  fs.mkdirSync(path3.dirname(p), { recursive: true });
+  return p;
+}
+function clearState(session) {
+  const p = stateFilePath(session);
+  if (fs.existsSync(p)) {
+    fs.rmSync(p);
+    return true;
+  }
+  return false;
+}
+
+// src/commands/login.ts
+function waitForEnter() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(
+    (resolve) => rl.question("Log in in the browser window, then press Enter here... ", () => {
+      rl.close();
+      resolve();
+    })
+  );
+}
+async function runLogin(opts) {
+  const browser = await chromium.launch({ headless: opts.headless ?? false });
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.goto(opts.url, { waitUntil: "domcontentloaded" });
+    if (opts.driveForTest) await opts.driveForTest(page);
+    if (opts.until) {
+      await page.waitForURL((u) => u.toString().includes(opts.until), {
+        timeout: opts.timeoutMs ?? 12e4
+      });
+    } else {
+      await waitForEnter();
+    }
+    const statePath = ensureStatePath(opts.session);
+    await context.storageState({ path: statePath });
+    return `logged in \u2014 session '${opts.session}' saved`;
+  } finally {
+    await browser.close();
+    try {
+      await sendRequest(opts.session, { id: nextId(), cmd: "stop" }, { autoSpawn: false });
+    } catch {
+    }
+  }
+}
+
+// src/commands/session.ts
+async function runSessionSave(session) {
+  try {
+    const res = await sendRequest(session, { id: nextId(), cmd: "savestate" }, { autoSpawn: false });
+    return res.ok ? `saved session '${session}'` : `error: ${res.error?.message ?? "save failed"}`;
+  } catch {
+    return `no daemon running for session '${session}' (nothing to save)`;
+  }
+}
+async function runSessionLoad(session) {
+  try {
+    await sendRequest(session, { id: nextId(), cmd: "stop" }, { autoSpawn: false });
+  } catch {
+  }
+  return hasState(session) ? `session '${session}' will load its saved state on the next command` : `no saved state for session '${session}'`;
+}
+async function runSessionClear(session) {
+  try {
+    await sendRequest(session, { id: nextId(), cmd: "stop" }, { autoSpawn: false });
+  } catch {
+  }
+  return clearState(session) ? `cleared session '${session}'` : `no saved state for session '${session}'`;
+}
+
+// src/manifest/load.ts
+import fs2 from "fs";
+import path4 from "path";
+
+// src/manifest/schema.ts
+import Ajv from "ajv";
+var MANIFEST_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["schemaVersion", "name", "baseUrl", "commands"],
+  properties: {
+    schemaVersion: { const: "webcli-manifest-v0" },
+    name: { type: "string", minLength: 1 },
+    baseUrl: { type: "string", minLength: 1 },
+    auth: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        type: { enum: ["headed-login", "recipe"] },
+        loginUrl: { type: "string" },
+        recipe: { type: "array", items: { type: "object" } }
+      }
+    },
+    selectors: { type: "object", additionalProperties: { type: "string" } },
+    pages: { type: "object", additionalProperties: { type: "string" } },
+    commands: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: false,
+        required: ["steps"],
+        properties: {
+          args: { type: "array", items: { type: "string" } },
+          steps: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                open: { type: "string" },
+                click: { type: "string" },
+                find: { type: "string" },
+                type: {
+                  type: "object",
+                  additionalProperties: false,
+                  required: ["selector", "text"],
+                  properties: { selector: { type: "string" }, text: { type: "string" } }
+                },
+                fill: { type: "object", additionalProperties: { type: "string" } },
+                submit: { type: ["boolean", "string"] },
+                read: { type: "boolean" },
+                links: { type: "boolean" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+var ajv = new Ajv({ allErrors: true, allowUnionTypes: true });
+var validate = ajv.compile(MANIFEST_SCHEMA);
+function validateManifest(obj) {
+  const valid = validate(obj);
+  const errors = (validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? ""}`.trim());
+  return { valid: !!valid, errors };
+}
+
+// src/manifest/load.ts
+function resolveManifestPath(value) {
+  if (fs2.existsSync(value)) return value;
+  const named = path4.resolve(process.cwd(), `${value}.agent.json`);
+  if (fs2.existsSync(named)) return named;
+  throw new Error(`manifest not found: '${value}' (looked for the file and ${value}.agent.json)`);
+}
+function loadManifest(filePath) {
+  const obj = JSON.parse(fs2.readFileSync(filePath, "utf8"));
+  const { valid, errors } = validateManifest(obj);
+  if (!valid) throw new Error(`invalid manifest ${filePath}: ${errors.join("; ")}`);
+  return obj;
+}
+
+// src/manifest/run.ts
+function interpolate(template, ctx) {
+  return template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, env) => process.env[env] ?? "").replace(/\{([^}]+)\}/g, (_, raw) => {
+    const key = raw.trim();
+    if (key.startsWith("pages.")) return ctx.manifest.pages?.[key.slice(6)] ?? "";
+    if (key.startsWith("selectors.")) return ctx.manifest.selectors?.[key.slice(10)] ?? "";
+    return ctx.args[key] ?? "";
+  });
+}
+var send = async (session, cmd, args) => {
+  const res = await sendRequest(session, { id: nextId(), cmd, args });
+  if (!res.ok) throw fromDaemon(res);
+  return res;
+};
+async function runCommand(manifest, name, argv, session) {
+  const cmd = manifest.commands[name];
+  if (!cmd) {
+    throw new Error(`unknown command '${name}' in manifest '${manifest.name}'`);
+  }
+  const args = {};
+  (cmd.args ?? []).forEach((argName, i) => {
+    args[argName] = argv[i] ?? "";
+  });
+  const ctx = { manifest, args };
+  let lastOutput = "";
+  for (const step of cmd.steps) {
+    if (step.open !== void 0) {
+      const url = new URL(interpolate(step.open, ctx), manifest.baseUrl).toString();
+      await send(session, "open", { url });
+    } else if (step.click !== void 0) {
+      await send(session, "click", { target: interpolate(step.click, ctx) });
+    } else if (step.find !== void 0) {
+      await send(session, "find", { text: interpolate(step.find, ctx) });
+    } else if (step.type !== void 0) {
+      await send(session, "type", {
+        selector: interpolate(step.type.selector, ctx),
+        text: interpolate(step.type.text, ctx)
+      });
+    } else if (step.fill !== void 0) {
+      const fields = {};
+      for (const [k, v] of Object.entries(step.fill)) fields[k] = interpolate(v, ctx);
+      await send(session, "fill", { fields });
+    } else if (step.submit !== void 0) {
+      await send(session, "submit", typeof step.submit === "string" ? { form: interpolate(step.submit, ctx) } : {});
+    } else if (step.read) {
+      const res = await send(session, "read", {});
+      lastOutput = res.data?.markdown ?? "";
+    } else if (step.links) {
+      const res = await send(session, "links", {});
+      lastOutput = JSON.stringify(res.data?.links ?? []);
+    }
+  }
+  return lastOutput;
+}
+
+// src/daemon/server.ts
+import net2 from "net";
+import fs3 from "fs";
+import { chromium as chromium2 } from "playwright";
+
+// src/core/markdown.ts
+import { JSDOM } from "jsdom";
+import { Readability } from "@mozilla/readability";
+import TurndownService from "turndown";
+function htmlToMarkdown(html, baseUrl) {
+  const dom = new JSDOM(html, { url: baseUrl });
+  const doc = dom.window.document;
+  for (const a of Array.from(doc.querySelectorAll("a[href]"))) {
+    const href = a.getAttribute("href");
+    if (href) {
+      try {
+        a.setAttribute("href", new dom.window.URL(href, baseUrl).toString());
+      } catch {
+      }
+    }
+  }
+  const article = new Readability(doc).parse();
+  const contentHtml = article?.content ?? doc.body?.innerHTML ?? "";
+  const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
+  turndown.remove(["script", "style", "noscript"]);
+  return turndown.turndown(contentHtml).trim();
+}
+
+// src/core/links.ts
+import { JSDOM as JSDOM2 } from "jsdom";
+function extractLinks(html, baseUrl, filter) {
+  const dom = new JSDOM2(html, { url: baseUrl });
+  const needle = filter?.toLowerCase();
+  const out = [];
+  for (const a of Array.from(dom.window.document.querySelectorAll("a[href]"))) {
+    const rawHref = a.getAttribute("href") ?? "";
+    if (rawHref.startsWith("#") || rawHref.trim() === "") continue;
+    const text = (a.textContent ?? "").replace(/\s+/g, " ").trim();
+    if (!text) continue;
+    let href;
+    try {
+      href = new dom.window.URL(rawHref, baseUrl).toString();
+    } catch {
+      continue;
+    }
+    if (needle && !`${text} ${href}`.toLowerCase().includes(needle)) continue;
+    out.push({ n: out.length + 1, text, href });
+  }
+  return out;
+}
+
+// src/core/target.ts
+function looksLikeSelector(s) {
+  const t = s.trim();
+  if (/^[.#[]/.test(t)) return true;
+  if (/[>[\]]/.test(t)) return true;
+  if (/^[a-zA-Z][\w-]*\.[\w-]+$/.test(t)) return true;
+  return false;
+}
+function resolveLocator(page, target) {
+  if (looksLikeSelector(target)) return page.locator(target).first();
+  return page.getByText(target, { exact: false }).first();
+}
+function resolveField(page, ref) {
+  if (looksLikeSelector(ref)) return page.locator(ref).first();
+  return page.locator(`[name="${ref}"]`).first();
+}
+
+// src/daemon/server.ts
+function ok(req, data) {
+  return { id: req.id, ok: true, data };
+}
+function err(req, code, message) {
+  return { id: req.id, ok: false, error: { code, message } };
+}
+async function startDaemon(sessionId, opts = {}) {
+  const idleMs = opts.idleMs ?? Number(process.env.WEBCLI_IDLE_MS ?? 3e5);
+  const browser = await chromium2.launch({ headless: true });
+  const statePath = loadStatePath(sessionId);
+  const context = await browser.newContext(statePath ? { storageState: statePath } : {});
+  const page = await context.newPage();
+  let lastRefs = [];
+  const settle = () => page.waitForLoadState("domcontentloaded").catch(() => {
+  });
+  async function dispatch(req) {
+    try {
+      switch (req.cmd) {
+        case "open": {
+          const url = String(req.args?.url ?? "");
+          if (!url) return err(req, "bad_args", "open requires a url");
+          const resp = await page.goto(url, { waitUntil: "domcontentloaded" });
+          return ok(req, { title: await page.title(), url: page.url(), status: resp?.status() ?? 0 });
+        }
+        case "read": {
+          const html = await page.content();
+          const url = page.url();
+          return ok(req, {
+            markdown: htmlToMarkdown(html, url),
+            url,
+            title: await page.title(),
+            links: extractLinks(html, url).length,
+            fields: []
+          });
+        }
+        case "links": {
+          const html = await page.content();
+          const filter = req.args?.filter ? String(req.args.filter) : void 0;
+          const links = extractLinks(html, page.url(), filter);
+          lastRefs = links.map((l) => ({ kind: "link", href: l.href }));
+          return ok(req, { links, url: page.url() });
+        }
+        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();
+          lastRefs = matches.map((locator) => ({ kind: "element", locator }));
+          const items = await Promise.all(
+            matches.map(async (loc, i) => ({
+              n: i + 1,
+              tag: await loc.evaluate((el) => el.tagName.toLowerCase()).catch(() => "?"),
+              text: (await loc.textContent().catch(() => "") ?? "").replace(/\s+/g, " ").trim().slice(0, 120)
+            }))
+          );
+          return ok(req, { matches: items, url: page.url() });
+        }
+        case "click": {
+          const target = String(req.args?.target ?? "");
+          if (!target) return err(req, "bad_args", "click requires a target");
+          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`);
+            if (ref.kind === "link") {
+              await page.goto(ref.href, { waitUntil: "domcontentloaded" });
+            } else {
+              await ref.locator.click();
+              await settle();
+            }
+          } else {
+            const loc = resolveLocator(page, target);
+            if (await loc.count() === 0) return err(req, "target_not_found", `no element matching: ${target}`);
+            await loc.click();
+            await settle();
+          }
+          return ok(req, { url: page.url(), title: await page.title() });
+        }
+        case "type": {
+          const selector = String(req.args?.selector ?? "");
+          const text = String(req.args?.text ?? "");
+          if (!selector) return err(req, "bad_args", "type requires a selector");
+          const loc = resolveField(page, selector);
+          if (await loc.count() === 0) return err(req, "target_not_found", `no field matching: ${selector}`);
+          await loc.fill(text);
+          return ok(req, { typed: selector, url: page.url() });
+        }
+        case "fill": {
+          const fields = req.args?.fields ?? {};
+          const filled = [];
+          for (const [name, value] of Object.entries(fields)) {
+            const loc = resolveField(page, name);
+            if (await loc.count() === 0) return err(req, "target_not_found", `no field matching: ${name}`);
+            await loc.fill(String(value));
+            filled.push(name);
+          }
+          return ok(req, { filled, url: page.url() });
+        }
+        case "submit": {
+          const formSel = req.args?.form ? String(req.args.form) : void 0;
+          const submitBtn = page.locator('button[type="submit"], input[type="submit"]').first();
+          if (await submitBtn.count() > 0) {
+            await submitBtn.click();
+          } else {
+            const form = formSel ? page.locator(formSel).first() : page.locator("form").first();
+            if (await form.count() === 0) return err(req, "target_not_found", "no form to submit");
+            await form.evaluate((f) => f.requestSubmit());
+          }
+          await settle();
+          return ok(req, { url: page.url(), title: await page.title() });
+        }
+        case "savestate": {
+          const p = ensureStatePath(sessionId);
+          await context.storageState({ path: p });
+          return ok(req, { saved: p });
+        }
+        case "stop":
+          return ok(req, { stopping: true });
+        default:
+          return err(req, "unknown_cmd", `unknown command: ${req.cmd}`);
+      }
+    } catch (e) {
+      return err(req, "exec_error", e.message);
+    }
+  }
+  const sockPath = socketPath(sessionId);
+  if (process.platform !== "win32" && fs3.existsSync(sockPath)) {
+    try {
+      fs3.unlinkSync(sockPath);
+    } catch {
+    }
+  }
+  let stopping = false;
+  async function stop() {
+    if (stopping) return;
+    stopping = true;
+    if (idleTimer) clearTimeout(idleTimer);
+    await new Promise((r) => server.close(() => r()));
+    await browser.close();
+    if (process.platform !== "win32" && fs3.existsSync(sockPath)) {
+      try {
+        fs3.unlinkSync(sockPath);
+      } catch {
+      }
+    }
+  }
+  let idleTimer;
+  function resetIdle() {
+    if (idleTimer) clearTimeout(idleTimer);
+    if (idleMs > 0) {
+      idleTimer = setTimeout(() => void stop(), idleMs);
+      idleTimer.unref();
+    }
+  }
+  const server = net2.createServer((conn) => {
+    const buf = new LineBuffer();
+    conn.on("data", async (chunk) => {
+      for (const line of buf.push(chunk.toString())) {
+        let req;
+        try {
+          req = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        const res = await dispatch(req);
+        conn.write(encode(res));
+        resetIdle();
+        if (req.cmd === "stop") {
+          conn.end();
+          void stop();
+        }
+      }
+    });
+    conn.on("error", () => {
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(sockPath, () => resolve());
+  });
+  resetIdle();
+  return { socket: sockPath, stop };
+}
+
+// src/cli.ts
+async function emit(produce) {
+  try {
+    process.stdout.write(await produce() + "\n");
+  } catch (e) {
+    process.stderr.write(formatError(e) + "\n");
+    process.exitCode = e instanceof WebcliError ? e.exitCode : EXIT.internal;
+  }
+}
+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");
+  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(
+    (url, opts, cmd) => emit(
+      () => runRead({ session: session(cmd), json: !!opts.json, maxChars: opts.maxChars, page: opts.page, url })
+    )
+  );
+  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("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(" ") }))
+  );
+  program.command("click").description("Click by visible text, a number from links/find, or a CSS selector.").argument("<target...>", "text, #number, or selector").option("--json", "structured JSON output", false).action(
+    (target, opts, cmd) => emit(() => runClick({ session: session(cmd), json: !!opts.json, target: target.join(" ") }))
+  );
+  program.command("type").description("Type text into a field (CSS selector or bare field name).").argument("<selector>", "field selector or name").argument("<text...>", "text to type").option("--json", "structured JSON output", false).action(
+    (selector, text, opts, cmd) => emit(
+      () => runType({ session: session(cmd), json: !!opts.json, selector, text: text.join(" ") })
+    )
+  );
+  program.command("fill").description("Fill one or more form fields.").option(
+    "-f, --field <name=value>",
+    "form field (repeatable)",
+    (v, acc) => {
+      acc.push(v);
+      return acc;
+    },
+    []
+  ).option("--json", "structured JSON output", false).action((opts, cmd) => {
+    const fields = {};
+    for (const pair of opts.field) {
+      const i = pair.indexOf("=");
+      if (i > 0) fields[pair.slice(0, i)] = pair.slice(i + 1);
+    }
+    return emit(() => runFill({ session: session(cmd), json: !!opts.json, fields }));
+  });
+  program.command("submit").description("Submit the current form (or a specific one by selector).").argument("[form]", "optional form selector").option("--json", "structured JSON output", false).action((form, opts, cmd) => emit(() => runSubmit({ session: session(cmd), json: !!opts.json, form })));
+  program.command("login").description("Open a real browser to log in once; persists the session for headless reuse.").argument("<url>", "login page URL").option("--until <text>", "auto-finish when the URL contains this (else waits for Enter)").action((url, opts, cmd) => emit(() => runLogin({ session: session(cmd), url, until: opts.until })));
+  const sessionCmd = program.command("session").description("Manage saved session/auth state.");
+  sessionCmd.command("save").description("Persist the running daemon's cookies/localStorage.").action((_o, cmd) => emit(() => runSessionSave(session(cmd))));
+  sessionCmd.command("load").description("Reload saved state into the session.").action((_o, cmd) => emit(() => runSessionLoad(session(cmd))));
+  sessionCmd.command("clear").description("Delete saved state for the session.").action((_o, cmd) => emit(() => runSessionClear(session(cmd))));
+  program.command("stop").description("Stop the session's background browser daemon.").action((_opts, cmd) => emit(() => runStop(session(cmd))));
+  const daemonCmd = new Command("__daemon").argument("<sessionId>").action(async (sessionId) => {
+    await startDaemon(sessionId);
+  });
+  program.addCommand(daemonCmd, { hidden: true });
+  return program;
+}
+async function dispatchSite(argv) {
+  let site = "";
+  let session = "default";
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--site") site = argv[++i] ?? "";
+    else if (argv[i] === "--session") session = argv[++i] ?? "default";
+    else rest.push(argv[i]);
+  }
+  const [command, ...cmdArgs] = rest;
+  if (!command) throw new WebcliError("usage", "usage: agentbrowse --site <manifest> <command> [args...]", EXIT.usage);
+  const manifest = loadManifest(resolveManifestPath(site));
+  process.stdout.write(await runCommand(manifest, command, cmdArgs, session) + "\n");
+}
+var isMain = process.argv[1]?.endsWith("cli.ts") || process.argv[1]?.endsWith("cli.js");
+if (isMain) {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--site")) {
+    dispatchSite(argv).catch((e) => {
+      process.stderr.write(formatError(e) + "\n");
+      process.exitCode = e instanceof WebcliError ? e.exitCode : EXIT.usage;
+    });
+  } else {
+    buildProgram().parseAsync(process.argv);
+  }
+}
+export {
+  buildProgram,
+  dispatchSite
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "agentbrowse",
+  "version": "0.0.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": {
+    "commander": "^12.1.0",
+    "playwright": "^1.45.0",
+    "jsdom": "^24.1.0",
+    "@mozilla/readability": "^0.5.0",
+    "turndown": "^7.2.0",
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "tsup": "^8.1.0",
+    "tsx": "^4.16.0",
+    "vitest": "^2.0.0",
+    "@types/node": "^20.14.0",
+    "@types/jsdom": "^21.1.0",
+    "@types/turndown": "^5.0.4"
+  }
+}