lean-browser-use 0.0.0-stage → 0.1.0

package/proof/benchmark.json

@@ -0,0 +1,166 @@
+{
+  "version": 1,
+  "measured": "2026-10-25",
+  "conditions": {
+    "task": "Open https://news.ycombinator.com, read the titles and comment counts of the top 5 stories, then open https://example.com and read its h1. Both arms found that example.com has no h1 and reported the page title.",
+    "arms": {
+      "plain": "Browser work in the main session.",
+      "runner": "Same task through the lean-browser-use skill and fresh runner, with the package installed project-scoped in a scratch project."
+    },
+    "models": "Main session claude-sonnet-5-5 in both arms; runner subagent claude-haiku-5-5.",
+    "tools": "In-app Browser pane tools (mcp__Claude_Browser__*); lean-browser-use measure 0.1.0 over each arm transcripts.",
+    "method": "One paired run. Per-step values are median input-context tokens; task values sum input-context tokens across browser steps, including main-session browser steps in the runner arm. Whole-run context totals cover every call in each arm. Counts include fresh input, cache creation and cache read tokens; output is separate.",
+    "one_paired_run": true
+  },
+  "arms": {
+    "plain": {
+      "step_tokens": 188487,
+      "task_tokens": 1506374,
+      "browser_steps": {
+        "main": 8
+      },
+      "whole_run": {
+        "calls": 14,
+        "fresh_input": 28,
+        "cache_creation": 129118,
+        "cache_read": 2528144,
+        "context_total": 2657290,
+        "output": 2188
+      }
+    },
+    "runner": {
+      "step_tokens": 59725,
+      "task_tokens": 725151,
+      "browser_steps": {
+        "main": 1,
+        "runner": 9
+      },
+      "whole_run": {
+        "calls": 23,
+        "fresh_input": 46,
+        "cache_creation": 195388,
+        "cache_read": 2651358,
+        "context_total": 2846792,
+        "output": 5905,
+        "model_split": {
+          "main_claude_sonnet_5_5": {
+            "calls": 11,
+            "context_total": 2134331,
+            "output": 2968
+          },
+          "runner_claude_haiku_5_5": {
+            "calls": 12,
+            "context_total": 712461,
+            "output": 2937
+          }
+        }
+      }
+    }
+  },
+  "derived": {
+    "whole_run_ratio": 0.93,
+    "delta_percent": 7.13,
+    "break_even_browser_steps": 15.54,
+    "estimate": true
+  },
+  "small_task": {
+    "measured": "2026-10-25",
+    "task": "Open https://example.com, read the page title and the first sentence of the body, close the tab. Claude in Chrome tools in both tests, same Chrome profile, scratch folders under the same user config.",
+    "test_a_native": {
+      "calls": 6,
+      "context_total": 1133195,
+      "output": 734,
+      "browser_steps": {
+        "main": 4,
+        "median": 189084,
+        "total": 757290
+      },
+      "model": "claude-sonnet-5-5"
+    },
+    "test_b_package": {
+      "calls": 10,
+      "context_total": 1241361,
+      "output": 2846,
+      "main": {
+        "calls": 5,
+        "context_total": 956151,
+        "model": "claude-sonnet-5-5"
+      },
+      "runner": {
+        "calls": 5,
+        "context_total": 285210,
+        "model": "claude-haiku-5-5"
+      },
+      "browser_steps": {
+        "main": 1,
+        "runner": 4,
+        "runner_median": 58057,
+        "runner_total": 226289,
+        "main_step": 190532
+      }
+    },
+    "derived": {
+      "per_step_ratio": 3.26,
+      "whole_run_ratio": 0.91,
+      "whole_run_delta_percent": 9.55
+    }
+  },
+  "cost_usd": {
+    "pricing_source": "https://platform.claude.com/docs/en/about-claude/pricing",
+    "pricing_read": "2026-10-25",
+    "price_unit": "usd_per_million_tokens",
+    "prices": {
+      "claude-sonnet-5-5": {
+        "input": 2,
+        "cache_write_5m": 2.5,
+        "cache_read": 0.1,
+        "output": 10
+      },
+      "claude-haiku-5-5": {
+        "input": 0.1,
+        "cache_write_5m": 0.125,
+        "cache_read": 0.01,
+        "output": 0.5,
+        "max_prompt_tokens": 100000
+      }
+    },
+    "cache_write_assumed": "5m",
+    "method": "List API prices applied per model call, then summed by arm. Recorded arm totals and model splits are quoted to four decimal places; split rounding may differ from the arm total.",
+    "run1": {
+      "plain": {
+        "total": 0.5975,
+        "model_split": {
+          "claude-sonnet-5-5": 0.5975
+        }
+      },
+      "runner": {
+        "total": 0.5787,
+        "model_split": {
+          "claude-sonnet-5-5": 0.5629,
+          "claude-haiku-5-5": 0.0157
+        }
+      }
+    },
+    "run2": {
+      "plain": {
+        "total": 0.5779,
+        "model_split": {
+          "claude-sonnet-5-5": 0.5779
+        }
+      },
+      "runner": {
+        "total": 0.4319,
+        "model_split": {
+          "claude-sonnet-5-5": 0.4215,
+          "claude-haiku-5-5": 0.0104
+        }
+      }
+    },
+    "derived": {
+      "run1_percent": -3.15,
+      "run2_percent": -25.26,
+      "pooled_percent": -14.02,
+      "best_percent": 25.26
+    }
+  }
+}

package/proof/results.json

@@ -0,0 +1,241 @@
+{
+  "version": 1,
+  "rows": [
+    {
+      "id": "runtime_dependencies",
+      "claim": "Runtime dependencies",
+      "value": 0,
+      "unit": "dependencies",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "node scripts/proof.mjs"
+    },
+    {
+      "id": "tests_passing",
+      "claim": "Passing Node tests, including Python suite checks",
+      "value": 258,
+      "unit": "tests",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "node --test test/"
+    },
+    {
+      "id": "tests_failing",
+      "claim": "Failing Node tests at measurement time",
+      "value": 0,
+      "unit": "tests",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "node --test test/"
+    },
+    {
+      "id": "guard_rules",
+      "claim": "Blocking guard rules verified by the suite",
+      "value": 7,
+      "unit": "rules",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "node --test test/"
+    },
+    {
+      "id": "guard_ms_median",
+      "claim": "Median wall time per guard via its shim over 50 calls",
+      "value": {
+        "pick-guard": 40.624,
+        "retry-guard": 42.568,
+        "batch-nudge": 45.23
+      },
+      "unit": "ms",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "node scripts/proof.mjs"
+    },
+    {
+      "id": "install_ms",
+      "claim": "Install wall time into a new temporary config directory",
+      "value": 58.872,
+      "unit": "ms",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "node scripts/proof.mjs"
+    },
+    {
+      "id": "tarball_bytes",
+      "claim": "Packed tarball size reported before this proof refresh",
+      "value": 83399,
+      "unit": "bytes",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "npm pack --dry-run --json"
+    },
+    {
+      "id": "tarball_files",
+      "claim": "Files in the packed tarball",
+      "value": 76,
+      "unit": "files",
+      "measured": "2026-10-25",
+      "expires": "2027-01-25",
+      "how": "npm pack --dry-run --json"
+    },
+    {
+      "id": "paired_step_tokens_plain",
+      "claim": "Plain session median input-context tokens per browser step",
+      "value": 188487,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_step_tokens_runner",
+      "claim": "Runner median input-context tokens per browser step",
+      "value": 59725,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_step_ratio",
+      "claim": "Plain-to-runner median browser-step token ratio",
+      "value": 3.16,
+      "unit": "ratio",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_task_tokens_plain",
+      "claim": "Plain arm total browser-step tokens",
+      "value": 1506374,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_task_tokens_runner_arm",
+      "claim": "Runner arm total browser-step tokens",
+      "value": 725151,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_task_ratio",
+      "claim": "Plain-to-runner arm total browser-step tokens ratio",
+      "value": 2.08,
+      "unit": "ratio",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_run_tokens_plain",
+      "claim": "Plain arm whole-run input-context tokens",
+      "value": 2657290,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_run_tokens_runner_arm",
+      "claim": "Runner arm whole-run input-context tokens",
+      "value": 2846792,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_run_ratio",
+      "claim": "Plain-to-runner whole-run input-context token ratio",
+      "value": 0.93,
+      "unit": "ratio",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_break_even_steps",
+      "claim": "Estimated break-even browser steps (an estimate from two data points; no run longer than 9 browser steps was measured)",
+      "value": 15.54,
+      "unit": "steps",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_small_run_tokens_plain",
+      "claim": "Small task (one page, 4 browser steps), native Claude in Chrome: whole-run input-context tokens",
+      "value": 1133195,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_small_run_tokens_runner_arm",
+      "claim": "Small task (one page), with the package, main session plus runner: whole-run input-context tokens",
+      "value": 1241361,
+      "unit": "tokens",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_small_run_ratio",
+      "claim": "Small task: plain-to-package whole-run input-context token ratio",
+      "value": 0.91,
+      "unit": "ratio",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_small_step_ratio",
+      "claim": "Small task: plain median browser step to runner median browser step token ratio",
+      "value": 3.26,
+      "unit": "ratio",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_cost_usd_plain",
+      "claim": "Run 1 plain arm dollar cost at list API prices",
+      "value": 0.5975,
+      "unit": "usd",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_cost_usd_runner_arm",
+      "claim": "Run 1 runner arm dollar cost at list API prices",
+      "value": 0.5787,
+      "unit": "usd",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_small_cost_usd_plain",
+      "claim": "Run 2 plain arm dollar cost at list API prices",
+      "value": 0.5779,
+      "unit": "usd",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_small_cost_usd_runner_arm",
+      "claim": "Run 2 runner arm dollar cost at list API prices",
+      "value": 0.4319,
+      "unit": "usd",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_cost_best_saving_percent",
+      "claim": "Best dollar saving in two measured runs on one setup",
+      "value": 25.26,
+      "unit": "percent",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    },
+    {
+      "id": "paired_cost_pooled_saving_percent",
+      "claim": "Pooled dollar saving across two measured runs on one setup",
+      "value": 14.02,
+      "unit": "percent",
+      "measured": "2026-10-25",
+      "how": "see docs/benchmark.md"
+    }
+  ]
+}

package/reader/README.md

@@ -0,0 +1,48 @@
+# Compile-once page reader
+
+The reader turns a public page into an extraction spec. Later reads run the spec as code. Embedded JSON extraction uses the Python standard library. CSS extraction and browser fetching use Crawl4AI, which you install yourself:
+
+```sh
+python3 -m pip install crawl4ai
+```
+
+Use Python 3. The installer copies these files only when you pass `--with-reader`.
+
+## Compile, run, list
+
+Choose a command that reads a prompt from stdin and prints extraction JSON on stdout. For example:
+
+```sh
+export READER_COMPILE_CMD='claude -p'
+reader/reader compile package --url 'https://www.npmjs.com/package/{name}' --param name=react --want 'name, version, license'
+reader/reader run npm-package --param name=react
+reader/reader ls
+```
+
+`READER_COMPILE_CMD` is split with `shlex` and executed directly. Shell expansion and shell pipelines are not used. A command may be another agent CLI, a script calling an API, or a local model. Compile and self-heal require this variable; a valid compiled spec runs without it. Add `--example` with a JSON object to anchor the compile to an observed row. Page text is untrusted data.
+
+A failed extraction gets one self-heal. `--no-heal` reports the extraction failure directly. Fetches accept public HTTP and HTTPS destinations, check redirects and browser requests, and refuse private addresses. Use the browser runner for pages that need your login.
+
+## Files and state
+
+Bundled specs are in `specs/`. `READER_SPECS_DIR` selects a different spec directory. Successful reads and healed overrides live under `~/.cache/lean-browser-use/reader`, or `READER_STATE_DIR`. Runs preserve the bundled spec files. `READER_CRAWL4AI_PYTHON` selects the Python executable with Crawl4AI installed.
+
+To add a spec, compile a known public URL with the fields you need and an observed example. Verify the JSON result against the page. Keep a public fixture and an offline regression check beside the spec. The bundled pricing fixture is a captured test page, not current pricing guidance.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Completed |
+| 2 | Usage, unset compile command, or refused target |
+| 10 | Fetch failed |
+| 11 | Compile failed |
+| 12 | Extraction failed after the allowed heal |
+
+## Offline checks
+
+```sh
+python3 -m unittest discover -s reader -p 'test_*.py'
+```
+
+The suite uses the standard library. Crawl4AI and local socket integration checks skip with a reason when their capability is unavailable. Mocked subprocess contracts and embedded JSON extraction still run.