lean-browser-use 0.0.0-stage → 0.1.0

package/docs/install.md

@@ -0,0 +1,78 @@
+# Install and manage
+
+Use Node 20 or newer. From a terminal:
+
+```sh
+npx lean-browser-use
+```
+
+The installer prints its plan, then asks `Proceed? [Y/n]` on a terminal. Non-interactive runs proceed automatically; `--yes` also skips the prompt. Undo the install with `npx lean-browser-use --uninstall`.
+
+## Choose the target
+
+The config directory is selected by `--claude-dir DIR`, then `$CLAUDE_CONFIG_DIR`, then `~/.claude`. `--project` targets `./.claude` in the current project. Use one explicit target choice per invocation.
+
+```sh
+npx lean-browser-use install --project
+npx lean-browser-use install --claude-dir ./sandbox-config --dry
+npx lean-browser-use install --with-reader --yes
+```
+
+| Install flag | Effect |
+| --- | --- |
+| `--claude-dir DIR` | Use the named Claude config directory. |
+| `--project` | Install into the current project's `.claude`. |
+| `--no-hooks` | Copy the hooks and print registration to paste by hand; skip the settings merge. |
+| `--with-reader` | Also copy the optional reader and SearXNG files. |
+| `--dry` | Print the real plan while leaving files unchanged. |
+| `--yes` | Proceed after the plan without an interactive confirmation. |
+| `--help` | Print command usage. |
+| `--version` | Print the package version. |
+
+## Files and settings
+
+Here `<cfg>` means the selected config directory.
+
+| Destination | Contents |
+| --- | --- |
+| `<cfg>/skills/lean-browser-use/` | Method entrypoint and focused references. |
+| `<cfg>/agents/aun-browser-runner.md` | Browser subagent definition. |
+| `<cfg>/lean-browser-use/hooks/` | Guard scripts and registration source. |
+| `<cfg>/lean-browser-use/briefs/` | Browser and cheap-helper packet templates. |
+| `<cfg>/lean-browser-use/reader/` | Optional compile-once reader and specs. |
+| `<cfg>/lean-browser-use/searxng/` | Optional search script and container configuration. |
+| `<cfg>/lean-browser-use/manifest.json` | Install-time hashes, created directories, and settings changes. |
+| `<cfg>/settings.json` | Merged hook registrations, preserving other settings and hooks. |
+| `<cfg>/settings.json.lean-browser-use.bak` | Backup of existing settings, written only if the backup is absent. |
+
+Repeated installs avoid duplicate registrations. The installer substitutes real hook paths into the registration template. It never installs third-party tools, runs a vendor login, contacts the network, or prints secrets. Optional tool installation belongs to the user; see [reader](reader.md) and [search](search.md).
+
+## Activate and inspect
+
+Start a fresh Claude Code session so it can discover the installed skill and agent. Ask it to use `lean-browser-use` for a browser task. Pick your Chrome profile by name when logged-in work needs it. A Chrome connection and tool permissions come from your own Claude Code setup.
+
+```sh
+npx lean-browser-use doctor
+npx lean-browser-use doctor --claude-dir ./sandbox-config --json
+```
+
+Doctor checks installed file hashes, registered hook paths, executable shims, and synthetic hook responses. Edited files are reported. Its capability table explains what Python, `crwl`, Docker, Claude Code, and local transcripts enable; missing optional tools are capabilities to add, not installation errors. JSON output has `ok` and `checks`, each with `id`, `status`, and `detail`. Hook behavior on your Claude Code version is confirmed by `lean-browser-use doctor`.
+
+## Measure and remove
+
+```sh
+npx lean-browser-use measure --dir ./transcripts --since 2026-10-25 --json
+npx lean-browser-use uninstall --claude-dir ./sandbox-config --dry
+npx lean-browser-use uninstall --claude-dir ./sandbox-config
+```
+
+`measure` defaults to the selected config directory's `projects` folder; `--dir` overrides it, `--since YYYY-MM-DD` filters timestamps, and `--json` returns structured results. See [the meter](measure.md).
+
+Uninstall compares each file with its install-time hash. It removes matching files, preserves and lists edited files, removes only its hook entries from settings, and removes only empty directories this install created. It refuses traversal, absolute manifest paths, and symlink entries. The manifest is removed last. Follow printed manual steps for registration pasted by hand. For a project install, point uninstall and doctor at `--claude-dir ./.claude`.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Success. |
+| 1 | A check failed. |
+| 2 | Usage error or refused target; a missing uninstall manifest names its path. |
+| 3 | Uninstall preserved edited files. |

package/docs/measure.md

@@ -0,0 +1,53 @@
+# Measure browser context
+
+Run the meter on your own Claude Code transcripts:
+
+```sh
+lean-browser-use measure
+lean-browser-use measure --dir ./transcripts --since 2026-10-25 --json
+```
+
+The default directory is the selected Claude config directory's `projects` folder. The meter walks JSONL files recursively, including subagent transcripts. `--dir` selects another tree, `--since YYYY-MM-DD` filters line timestamps, and `--json` returns the same measurements in structured form.
+
+## What counts
+
+A browser step is a unique assistant `message.id` with a browser `tool_use` block. Recognized prefixes are `mcp__claude-in-chrome__`, `mcp__Claude_Browser__`, `mcp__Control_Chrome__`, `mcp__playwright__`, and `mcp__chrome-devtools__`. A batch counts once, even when it contains many browser actions.
+
+For each step the meter adds `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. An assistant message can appear on several transcript lines. The meter keeps the largest total for that id as final usage, preserving the browser-step classification across its lines.
+
+A line belongs to the runner group when `isSidechain` is true or its file path contains `/subagents/`. Other lines belong to main. Unreadable lines are skipped and counted in `skipped_lines`.
+
+## Read the result
+
+| Field | Meaning |
+| --- | --- |
+| Group | Main session or runner. |
+| Steps | Distinct assistant messages using browser tools. |
+| Median | Typical input-context tokens per step. |
+| p90 | Input-context tokens near the upper end of the observed steps. |
+| Total | Sum of input-context tokens across browser steps. |
+| `reread_share` | Cache-read plus cache-creation tokens divided by total input-context tokens. |
+| `ratio` | Main median divided by runner median, reported when each has at least 3 steps. |
+| `skipped_lines` | Transcript lines the meter could not read. |
+
+The default output is a short table for main and runner, followed by summary information. With an empty transcript tree it prints `no browser steps found` and exits 0. Generate a real example from the synthetic fixtures with:
+
+```sh
+node bin/lean-browser-use.mjs measure --dir test/fixtures/transcripts
+```
+
+Output from the synthetic fixtures, not a token-saving claim:
+
+```text
+group   steps   median   p90   total   reread_share
+main    3       400      600   1200    0.5000
+runner  3       200      300   600     0.5000
+ratio   2
+skipped_lines   1
+```
+
+This is a context-volume comparison, not a currency bill. Cached tokens can have different pricing. Different jobs, model behavior, and transcript coverage also affect the result. Compare similar work and keep the counts beside the ratio. The meter prints counts and token values, never message text or tool inputs, and makes no network calls.
+
+## Package measurements
+
+[proof/results.json](../proof/results.json) measures the package: tarball size, file count, dependencies, passing tests, guard timings, install time, and covered guard rules. Reproduce it with `npm run proof`. These generated rows give their command, measurement date, and expiry. An expired row warns during `npm run check`; expiry does not block checks or a release. The twenty paired benchmark rows are copied or derived from the saved run in [proof/benchmark.json](../proof/benchmark.json), carry no expiry, and are never re-measured by the proof script. Read [the benchmark](benchmark.md) for conditions, exact counts, and reproduction steps. They give a ballpark for that run; use the meter on your own transcripts to compare your work.

package/docs/reader.md

@@ -0,0 +1,39 @@
+# Compile once, run as code
+
+The page reader extracts repeatable fields from public pages. A model writes the extraction spec during compilation. Successful later runs fetch and extract with code, without a model call. Validation can trigger one self-heal when a page changes.
+
+Copy the companion with `npx lean-browser-use --with-reader`. The examples below run from a repository checkout; installed copies live under the chosen config directory's `lean-browser-use/reader/`.
+
+## Prepare the reader
+
+Python 3 runs the reader. Crawl4AI supplies CSS extraction and the browser fetch fallback. The user installs it separately with `pip install crawl4ai` in their chosen Python environment. See the [reader guide](../reader/README.md) for interpreter discovery and offline tests.
+
+Choose a command that reads a prompt on stdin and prints schema JSON on stdout. For example:
+
+```sh
+export READER_COMPILE_CMD='claude -p'
+reader/reader compile packages --url 'https://www.npmjs.com/package/{name}' \
+  --param name=react --want 'Name, version, license, repository URL'
+reader/reader run packages --param name=zod
+reader/reader ls
+```
+
+The compile command is parsed with `shlex` and run without a shell. It can be an agent CLI, an API client script, or a local model command. The reader supplies the prompt on stdin. An unset `READER_COMPILE_CMD` makes compilation or self-heal exit 2 with setup guidance. Running an already compiled valid spec needs neither the variable nor a model.
+
+## Verify and reuse
+
+Give `compile` an observed `--example` row when possible. Verify the resulting values independently before reusing the spec. The bundled [pricing spec](../reader/specs/claude-pricing.json) and [package spec](../reader/specs/npm-package.json) include their provenance; saved fixtures demonstrate extraction, while current public values require a fresh read.
+
+`run` returns `rows` and fetch metadata. `ls` shows available specs and their state. Use `--no-heal` to keep a run to code-only extraction even when validation fails. A successful heal is stored in runtime state, preserving shipped specs. `READER_SPECS_DIR` selects specs and `READER_STATE_DIR` selects state.
+
+Only public HTTP and HTTPS pages are eligible. Private targets and authenticated browsing belong outside this reader. Use the user-selected browser route for logged-in work.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Success. |
+| 2 | Usage error, refused target, or missing compile command when needed. |
+| 10 | Fetch failed. |
+| 11 | Compile failed. |
+| 12 | Extraction failed after self-heal or with `--no-heal`. |
+
+Preserve the error and fall through to an eligible route from the [route table](../skills/lean-browser-use/references/route-by-job.md). Avoid repeating an unchanged failed fetch.

package/docs/search.md

@@ -0,0 +1,16 @@
+# Find links, then read pages
+
+Use search when the URLs are unknown. The optional `searx` script returns links from a SearXNG instance so a helper or runner can read the selected pages in a packet. SearXNG is a self-hosted search service; hosting and upstream availability depend on your environment.
+
+Install the companion files with `npx lean-browser-use --with-reader`. Docker is a separate user-provided capability. From a repository checkout:
+
+```sh
+bash searxng/deploy.sh
+searxng/searx 'browser automation documentation'
+```
+
+The default endpoint is `http://127.0.0.1:8888`. `SEARXNG_URL` selects another instance. The compose configuration binds to loopback; expose it to a private network only as a deliberate deployment choice. The deployment script keeps its generated secret in `${XDG_CONFIG_HOME:-$HOME/.config}/lean-browser-use/searxng-secret.env` with restricted permissions. Keep that file out of briefs and reports.
+
+Search finds candidate URLs. A search snippet is a discovery aid; read the selected page and save the requested fields as evidence. Batch independent public reads within a helper session or a subagent-runner session. See the [helper packet](../briefs/helper-read.md).
+
+This repository ships configuration and a container reference. SearXNG itself is AGPL-3.0 and is not bundled here. See [the companion guide](../searxng/README.md) and [credits](../CREDITS.md).

package/hooks/batch-nudge.mjs

@@ -0,0 +1,14 @@
+import { browser, native, shortName, probe, stateFile, readState, writeState, input, guard } from './common.mjs';
+
+guard(() => {
+  const p = input();
+  if (p.hook_event_name !== 'PostToolUse' || (!browser(p.tool_name) && !native(p.tool_name))) return;
+  const id = p.agent_id || p.session_id;
+  if (!id) return;
+  const file = stateFile('batch', id);
+  const state = readState(file);
+  const reset = probe(p.tool_name) || shortName(p.tool_name) === 'browser_batch';
+  state.streak = reset ? 0 : (state.streak || 0) + 1;
+  writeState(file, state);
+  if (state.streak === 3) process.stderr.write('Chain these actions into one browser_batch; return the needed fields together.\n');
+});

package/hooks/batch-nudge.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+d=$(cd "$(dirname "$0")" && pwd) || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+[ -f "$d/batch-nudge.mjs" ] || exit 0
+node "$d/batch-nudge.mjs" "$@"
+status=$?
+[ "$status" -eq 2 ] && exit 2
+exit 0

package/hooks/common.mjs

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash, randomBytes } from 'node:crypto';
+
+export const hash = data => createHash('sha256').update(String(data)).digest('hex');
+export const browser = name => /^mcp__(claude-in-chrome|Claude_Browser|Control_Chrome)__/.test(name || '');
+export const native = name => /^mcp__(computer-use|cua-driver)__/.test(name || '');
+export const shortName = name => String(name || '').split('__').at(-1);
+const probes = new Set(['list_connected_browsers', 'tabs_context_mcp', 'tabs_context', 'read_console_messages', 'read_network_requests', 'shortcuts_list', 'preview_list', 'preview_logs', 'preview_stop', 'list_tabs', 'get_current_tab', 'list_apps', 'list_windows']);
+export const probe = name => probes.has(shortName(name)) || shortName(name).startsWith('tabs_context');
+export function responseText(value) {
+  if (typeof value === 'string') return value.trim();
+  if (value == null) return '';
+  if (Array.isArray(value)) return value.map(responseText).join('\n').trim();
+  if (Array.isArray(value.content)) return responseText(value.content);
+  if (typeof value.text === 'string') return value.text.trim();
+  return JSON.stringify(value);
+}
+export function isError(value) {
+  if (value && typeof value === 'object' && (value.isError || value.is_error || Object.hasOwn(value, 'error'))) return true;
+  return /^error/i.test(responseText(value));
+}
+export const fruitless = value => isError(value) || /^(?:\[\]|\{\}|null|not found)?$/i.test(responseText(value));
+export function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${stable(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+function secureDir(dir) {
+  let current = path.parse(path.resolve(dir)).root;
+  for (const part of path.resolve(dir).slice(current.length).split(path.sep)) {
+    current = path.join(current, part);
+    try { if (fs.lstatSync(current).isSymbolicLink()) throw new Error('Unsafe state'); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.chmodSync(dir, 0o700);
+}
+export function stateFile(kind, id) {
+  const cfg = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  const dir = process.env.LBU_STATE_DIR || path.join(cfg, 'lean-browser-use', 'state');
+  secureDir(dir);
+  const subdir = path.join(dir, kind);
+  secureDir(subdir);
+  for (const name of fs.readdirSync(subdir)) {
+    const file = path.join(subdir, name);
+    const stat = fs.lstatSync(file);
+    if (stat.isFile() && Date.now() - stat.mtimeMs > 86400000) fs.unlinkSync(file);
+  }
+  const file = path.join(subdir, hash(id).slice(0, 24));
+  try { if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Unsafe state'); }
+  catch (e) { if (e.code !== 'ENOENT') throw e; }
+  return file;
+}
+export function readState(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return {}; throw e; }
+}
+export function writeState(file, value) {
+  const tmp = `${file}.${randomBytes(6).toString('hex')}`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+    fs.renameSync(tmp, file);
+  } finally { try { fs.unlinkSync(tmp); } catch {} }
+}
+export function input() { return JSON.parse(fs.readFileSync(0, 'utf8')); }
+export function block(message) { process.stderr.write(`${message}\n`); process.exitCode = 2; }
+export function guard(run) {
+  try { run(); } catch { process.exitCode = 0; }
+}

package/hooks/hooks.settings.json

@@ -0,0 +1,58 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__claude-in-chrome__.*|mcp__Claude_Browser__.*|mcp__Control_Chrome__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${HOOKS_DIR}/pick-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__claude-in-chrome__.*|mcp__Claude_Browser__.*|mcp__Control_Chrome__.*|mcp__computer-use__.*|mcp__cua-driver__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${HOOKS_DIR}/retry-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "mcp__claude-in-chrome__select_browser|mcp__claude-in-chrome__switch_browser|mcp__claude-in-chrome__tabs_close_mcp",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${HOOKS_DIR}/pick-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__claude-in-chrome__.*|mcp__Claude_Browser__.*|mcp__Control_Chrome__.*|mcp__computer-use__.*|mcp__cua-driver__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${HOOKS_DIR}/retry-guard.sh\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__claude-in-chrome__.*|mcp__Claude_Browser__.*|mcp__Control_Chrome__.*|mcp__computer-use__.*|mcp__cua-driver__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${HOOKS_DIR}/batch-nudge.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pick-guard.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import { browser, shortName, probe, isError, stateFile, readState, writeState, input, block, guard } from './common.mjs';
+
+const message = 'List connected browsers, ask the user to pick by profile name, then select that browser. For the in-app pane, record the pick with node pick-guard.mjs --pick <label> --session <id>. A runner re-picks only the deviceId named in its brief.';
+guard(() => {
+  const args = process.argv.slice(2);
+  if (args.length) {
+    const session = args[args.indexOf('--session') + 1];
+    if (!args.includes('--session') || !session || session.startsWith('--')) return block(message);
+    const file = stateFile('pick', session);
+    if (args.includes('--reset')) { if (fs.existsSync(file)) fs.unlinkSync(file); return; }
+    const label = args[args.indexOf('--pick') + 1];
+    if (!args.includes('--pick') || !label || label.startsWith('--')) return block(message);
+    writeState(file, { picked: true });
+    return;
+  }
+  const p = input();
+  if (!browser(p.tool_name) || probe(p.tool_name)) return;
+  if (!p.session_id) return block(message);
+  const file = stateFile('pick', p.session_id);
+  const name = shortName(p.tool_name);
+  const selecting = ['select_browser', 'switch_browser'].includes(name);
+  if (p.hook_event_name === 'PostToolUse') {
+    if (name === 'tabs_close_mcp') { if (fs.existsSync(file)) fs.unlinkSync(file); }
+    else if (selecting && !isError(p.tool_response)) writeState(file, { picked: true });
+  } else if (p.hook_event_name === 'PreToolUse' && !selecting && !readState(file).picked) block(message);
+});

package/hooks/pick-guard.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+d=$(cd "$(dirname "$0")" && pwd) || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+[ -f "$d/pick-guard.mjs" ] || exit 0
+node "$d/pick-guard.mjs" "$@"
+status=$?
+[ "$status" -eq 2 ] && exit 2
+exit 0

package/hooks/retry-guard.mjs

@@ -0,0 +1,69 @@
+import { browser, native, shortName, probe, fruitless, isError, responseText, stable, hash, stateFile, readState, writeState, input, block, guard } from './common.mjs';
+
+export function waitSeconds(name, args) {
+  const code = String(args.code || args.javascript || args.script || args.text || '');
+  const isWait = args.action === 'wait' || /wait|sleep/i.test(name) || Object.hasOwn(args, 'duration') || Object.hasOwn(args, 'ms') ||
+    (name === 'javascript_tool' && /sleep|timeout|waitFor/i.test(code));
+  if (!isWait) return null;
+  if (Number.isFinite(Number(args.ms))) return Math.max(0, Number(args.ms) / 1000);
+  if (Number.isFinite(Number(args.duration))) return Math.max(0, Number(args.duration));
+  const delays = [...code.matchAll(/(?:setTimeout\s*\([^,]*,\s*|(?:sleep|waitFor|timeout)\s*\(\s*)(\d+)/gi)].map(m => Number(m[1]) / 1000);
+  if (delays.length) return Math.max(...delays);
+  // An unbounded scripted delay consumes the budget instead of bypassing it.
+  return 60;
+}
+const empty = () => ({ waits: 0, nav: '', navCount: 0, origin: '', fruitless: 0, readKey: '', readCount: 0, text: '', nativeKey: '', nativeError: '', nativeCount: 0 });
+function origin(url) { try { return new URL(url).origin; } catch { return ''; } }
+guard(() => {
+  const p = input();
+  if ((!browser(p.tool_name) && !native(p.tool_name)) || probe(p.tool_name)) return;
+  const id = p.agent_id || p.session_id;
+  if (!id || !['PreToolUse', 'PostToolUse'].includes(p.hook_event_name)) return;
+  const file = stateFile('retry', id);
+  const data = readState(file);
+  data.tabs ||= {};
+  const args = p.tool_input || {};
+  const tab = String(args.tabId ?? '-');
+  let s = Object.hasOwn(data.tabs, tab) ? data.tabs[tab] : empty();
+  const name = shortName(p.tool_name);
+  const key = hash(`${p.tool_name}:${stable(args)}`);
+  const wait = waitSeconds(name, args);
+  const nav = name === 'navigate' || args.action === 'navigate';
+  const url = String(args.url || '');
+  const read = /^(read_page|find|get_page_text|get_page_content|javascript_tool|read|screenshot)$/.test(name) && wait === null;
+  const targeted = /click|type|fill/.test(name) || /click|type|fill/.test(args.action || '');
+  const movedOrigin = nav && origin(url) && s.origin && origin(url) !== s.origin;
+  if (p.hook_event_name === 'PreToolUse') {
+    if (browser(p.tool_name) && (movedOrigin || targeted)) s = empty();
+    if (native(p.tool_name) && s.nativeKey === key && s.nativeCount >= 2) return block('Stop and report the repeated native error. Choose a new approach before trying again.');
+    if (wait !== null && s.waits + wait > (Number(process.env.LBU_WAIT_CAP_SECONDS) || 60)) return block('Wait for an element, not for time. Stop and report if the page stays unchanged.');
+    if (s.fruitless >= 2 && (wait !== null || nav || (read && s.readKey === key && s.readCount >= 2))) return block('Stop and report the fruitless reads. Use the supplied read code once or choose a different query.');
+    if (nav && s.nav === url && s.navCount >= 2) return block('Stop and report the repeated navigation. Use the supplied read code once.');
+    if (wait !== null) s.waits += wait;
+    if (nav) { s.navCount = s.nav === url ? s.navCount + 1 : 1; s.nav = url; s.origin = origin(url); }
+    else { s.nav = ''; s.navCount = 0; }
+  } else {
+    if (native(p.tool_name)) {
+      const error = hash(responseText(p.tool_response));
+      if (isError(p.tool_response)) {
+        s.nativeCount = s.nativeKey === key && s.nativeError === error ? s.nativeCount + 1 : 1;
+        s.nativeKey = key; s.nativeError = error;
+      } else { s.nativeCount = 0; s.nativeKey = ''; }
+    }
+    if (read) {
+      const text = hash(responseText(p.tool_response));
+      if (fruitless(p.tool_response)) {
+        s.fruitless += 1;
+        s.readCount = s.readKey === key ? s.readCount + 1 : 1;
+        s.readKey = key;
+      } else {
+        if (text !== s.text) s = empty();
+        s.fruitless = 0; s.readCount = 0; s.text = text;
+      }
+    } else if (wait === null && !nav && !native(p.tool_name)) { s.fruitless = 0; s.readCount = 0; }
+  }
+  Object.defineProperty(data.tabs, tab, { value: s, enumerable: true, configurable: true, writable: true });
+  // Bound state even when a session sees many tabs.
+  for (const old of Object.keys(data.tabs).slice(0, -64)) delete data.tabs[old];
+  writeState(file, data);
+});

package/hooks/retry-guard.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+d=$(cd "$(dirname "$0")" && pwd) || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+[ -f "$d/retry-guard.mjs" ] || exit 0
+node "$d/retry-guard.mjs" "$@"
+status=$?
+[ "$status" -eq 2 ] && exit 2
+exit 0

package/llms.txt

@@ -0,0 +1,40 @@
+# lean-browser-use
+
+> Cut browser use cost by about 25% in Claude Code: fresh runner subagent, bulk reads, three guards and a token meter. One npx command
+
+Install: `npx lean-browser-use`
+
+Two measured runs cost 3.15% and 25.26% less with the package at list API prices, about 14.02% less pooled. About 25% cheaper is the rounded best of those two runs on one setup. Savings vary with model, task and session size; measure your own transcripts. A browser step re-reads about 3x fewer tokens per browser step. Everything run 1 read totalled 2,657,290 tokens in the plain arm and 2,846,792 in the runner arm: about 7% higher overall. Model, task and session size affect cost. The rough token break-even of about 16 browser steps is an estimate.
+
+## Docs
+
+- [Dollar costs, browser-step savings, whole-run totals, estimated break-even, and reproduction](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/benchmark.md)
+
+- [Installation, flags, health checks, and removal](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/install.md)
+- [How routing, packets, verification, and cleanup work](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/how-it-works.md)
+- [Guard rules, registration, and payload checks](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/guards.md)
+- [How to measure main and runner browser context](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/measure.md)
+
+## Reference
+
+- [Skill entrypoint and task routing](https://github.com/aunysillyme/lean-browser-use/blob/main/skills/lean-browser-use/SKILL.md)
+- [Route table with a complete subagent-only path](https://github.com/aunysillyme/lean-browser-use/blob/main/skills/lean-browser-use/references/route-by-job.md)
+- [Profile selection and logged-in tab handoff](https://github.com/aunysillyme/lean-browser-use/blob/main/skills/lean-browser-use/references/logged-in-run.md)
+- [Runner execution and evidence contract](https://github.com/aunysillyme/lean-browser-use/blob/main/agents/aun-browser-runner.md)
+- [Browser read packet template](https://github.com/aunysillyme/lean-browser-use/blob/main/briefs/browser-read.md)
+- [Cheap-helper read packet template](https://github.com/aunysillyme/lean-browser-use/blob/main/briefs/helper-read.md)
+- [Repository commands and tested rules](https://github.com/aunysillyme/lean-browser-use/blob/main/AGENTS.md)
+- [Package measurements and reproduction commands](https://github.com/aunysillyme/lean-browser-use/blob/main/proof/results.json)
+- [Public concept names and provenance](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/PROVENANCE.md)
+
+## Reader and search companions
+
+- [Compile-once reader setup and command contract](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/reader.md)
+- [SearXNG setup and link discovery](https://github.com/aunysillyme/lean-browser-use/blob/main/docs/search.md)
+- [Upstream contributions and licenses](https://github.com/aunysillyme/lean-browser-use/blob/main/CREDITS.md)
+- [Contribution workflow and useful changes](https://github.com/aunysillyme/lean-browser-use/blob/main/CONTRIBUTING.md)
+
+## Part of a set
+
+- [lean-browser-use: Cut browser use cost by about 25% in Claude Code: fresh runner subagent, bulk reads, three guards and a token meter. One npx command](https://github.com/aunysillyme/lean-browser-use/blob/main/README.md)
+- [lean-computer-use: Background Mac computer control for AI agents: desk tools, a fresh runner subagent, retry guards and a transcript token meter, installed with one command](https://github.com/aunysillyme/lean-computer-use)

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "lean-browser-use",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cut browser use cost by about 25% in Claude Code: fresh runner subagent, bulk reads, three guards and a token meter. One npx command",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "lean-browser-use": "bin/lean-browser-use.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "agents",
+    "briefs",
+    "hooks",
+    "reader",
+    "searxng",
+    "proof",
+    "docs",
+    "!docs/trailer.gif",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CREDITS.md",
+    "llms.txt"
+  ],
+  "scripts": {
+    "test": "node --test test/",
+    "check": "node scripts/check.mjs",
+    "proof": "node scripts/proof.mjs"
+  },
+  "repository": "git+https://github.com/aunysillyme/lean-browser-use.git",
+  "homepage": "https://github.com/aunysillyme/lean-browser-use#readme",
+  "bugs": {
+    "url": "https://github.com/aunysillyme/lean-browser-use/issues"
+  },
+  "funding": "https://github.com/sponsors/aunysillyme",
+  "keywords": [
+    "browser-use",
+    "browser-automation",
+    "claude-code",
+    "ai-agents",
+    "subagent",
+    "token-efficiency",
+    "mcp",
+    "claude-in-chrome",
+    "web-scraping",
+    "hooks",
+    "llm-cost",
+    "context-window",
+    "claude-code-hooks",
+    "claude-code-subagent",
+    "browser-agent",
+    "token-usage",
+    "agent-skill",
+    "crawl4ai",
+    "searxng"
+  ]
+}