AGENTS.md@browse · git:20261117.8e00433 · 2026-11-17 · sha256 0f97e39223eee98b
AGENTS.md@browse git:20261117.8e00433A
Immutable. This exact content never changes and is served at /api/v1/blob/0f97e39223eee98b.
# browse: caveman-browse browser driver `browse/` is a consumer copy of the public [`JuliusBrussee/caveman-browse`](https://github.com/JuliusBrussee/caveman-browse) repository. Do Browse product work there. Edit this copy only for pinned integration with this repo or an explicit sync. Accessibility-compressor work stays in this repo, in `engine/compressors/axtree.go`, because the engine lives here. What it is: a local stdio MCP server for agents. It reads a real Chrome accessibility tree, compresses it with the engine's forced-only `a11y` compressor, acts on `uid` handles and recovers the byte-exact original AX payload through CCR. Every saving is `inferred`, never `verified`. ## Layout - `session.go`: MCP tool handlers (`browser_snapshot`, `browser_act`, `browser_eval`, `browser_recover`), engine and CCR integration, the uid target cache. - `cdp.go`: chromedp-backed dedicated Chrome driver and the bounded actionability recipe. - `cmd/caveman-browse/`: the stdio MCP binary and the direct CLI (`snapshot`, `act`, `eval`, `recover`, `close`). - `bin/caveman-browse.mjs`, `package.json`: the npm launcher. - `BENCHMARK.md`: the benchmark contract and the Playwright comparison. ## Build and test (from the repo root) - `go build ./browse/cmd/caveman-browse` and `go test ./browse/...` (no browser needed). - `CAVEMAN_BROWSE_CHROME=/path/to/Chrome go test -tags=integration ./browse/...` runs the CDP contract against a real Chrome. - `pnpm --filter caveman-browse test` runs the launcher tests. ## Invariants - **The uid map is `browser_snapshot`'s contract.** On engine pass-through (no recovery handle, because the tree did not shrink or there is no store) the tool fails closed with `cave_browser_snapshot_uncompressed` and keeps the prior page's uids. It must never dump the raw AX tree into `uids` or wipe the target cache (issue #140). - **An `<iframe>` is a leaf.** `Accessibility.getFullAXTree` returns one frame at a time, so an iframe's `childId` points at a document missing from the payload. The `a11y` compressor treats an unresolvable `childId` as a leaf. Keep Chrome's default Site Isolation (`site-per-process`); do not disable it to "fix" cross-origin iframes. - **Network and browser dependencies stay here.** This package may import CDP and network code; `mcp/` must not. - **Honest token accounting.** `tokens_after` equals the exact agent-visible result cost and `view_tokens` the serializer output cost. Snapshot output is compact indented text, not JSON lines. A `query` keeps at most 12 top matches plus ancestors, and recovery metadata lists only uids actually shown. Keep the token budgets in `BENCHMARK.md` executable as tests. - **An action is not a settled page.** CDP acknowledgement is not application settlement: non-wait actions return `settled:false`, and only a focused re-snapshot proves state. - **Bounded scope.** The actionability layer targets same-origin dashboards and predictable design-system controls, not parity with the open web. - **Fail closed.** Unknown handles and actions return `cave_` error codes. Navigation allows `http(s)`, `about:blank` and bounded `data:text/html`, and rejects `file:`, `javascript:` and privileged Chrome schemes. - **Direct CLI state.** Direct CLI Chrome is detached so separate `snapshot`, `act` and `eval` processes share one target; `close` must end it. A fresh `CAVEMAN_HOME` must work, and state writes stay atomic with mode `0600`. See the root [AGENTS.md](../AGENTS.md).