gauntlet

# Gauntlet Run Browser Control against uncurated live websites, fix general root causes as you hit them, lock each fix in with a minimal offline regression test, and always finish with a **Simplify** pass so new capabilities never accumulate site-specific hacks or bloated files. ```ts ┌─────────────────────────────────────────────────────────────────────┐ │ │ ▼ │ [1. Gauntlet] ──► [2. Autoresearch] ──► [3. Simplify] ──► [4. Harvest] ─┘ Real-site Latency, token & Compress code, Promote recurring field tasks round-trip profile remove hacks UI flows to CLIs ``` ## Workflow ### 1. Gauntlet — Adversarial Real-Site Field Pass 1. Create a dedicated session (`browser-control session new "🧭 gauntlet"`) and pick 4–6 diverse live sites that stress different web patterns (never perform destructive/irreversible actions like placing an order): - **Portal UI libraries**: `https://ui.shadcn.com/docs/components/radix/select` (Radix `<button role="combobox">`, body-portaled `[role="listbox"]` / `[role="option"]`) - **Complex web apps**: `https://github.com/Effect-TS/effect/issues` (Primer `[role="menu"]` / `[role="menuitemradio"]`, filter dialogs, `snapshot({ delta: true })`) - **Dense SPAs & e-commerce / booking**: `https://resy.com`, `https://www.ubereats.com` (top-level `<header>` search bars, carousels, focus-locked modals, deep card lists) - **Layout tables & prose**: `https://news.ycombinator.com`, `https://en.wikipedia.org`, `https://www.npmjs.com` - **Web Components & Shadow DOM**: `https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot`, `https://www.reddit.com/r/typescript/` 2. Drive each task through the public agent interface (`snapshot()`, `ref("eN")`, `screenshotWithLabels()`, `network`). 3. Whenever a step fails, times out, misses an interactive control, emits duplicate lines, or forces a blind `waitForTimeout` sleep: - Inspect the live DOM in the session to find the **general DOM, W3C ARIA, or CDP root cause**. - **Never** hardcode site-specific domain names or CSS class names. Express every rule in terms of standard HTML tags, ARIA roles/attributes, computed styles, or DOM structure. - Fix the root cause in `src/` (or `extension/src/`), add a minimal offline HTML regression check to `scripts/check-snapshot.ts` or `test/`, deploy to `/Users/kit/.browser-control/current-runtime` (`pnpm runtime:prepare` + `pnpm runtime:select` + `browser-control relay restart`), and re-verify on the live site. ### 2. Autoresearch — Speed, Token & Round-Trip Check Measure across the gauntlet sites: - **Wall-clock latency (`ms`)** per `snapshot()` call (target: `15–40 ms` on standard pages, `< 180 ms` on 9,000-node Shadow DOM pages). - **Token footprint (`chars` / `lines`)**: eliminate duplicate `heading` + `link` pairs, redundant `listitem` / `p` wrappers, and layout-table noise. - **Avoidable round-trips & sleeps**: prefer event-driven settle (`MutationObserver`, `Emulation.setFocusEmulationEnabled`) over manual `waitForTimeout` padding. ### 3. Simplify — Mandatory Coherence & Compression Pass After fixing gauntlet findings, always run a `simplify` pass before finishing: - Remove any ad-hoc branches, dead flags, or overlapping helpers introduced during debugging. - Keep module boundaries clean (`src/snapshot.ts` owns DOM inspection and input helpers; `src/execute.ts` owns `ExecuteSandbox` and page recovery). - Run the full verification gate: ```bash pnpm exec tsx scripts/check-snapshot.ts pnpm check:locals && pnpm check:unused && pnpm audit:duplicates pnpm test ``` ### 4. Harvest — UI-to-API Promotion (Optional) When testing a multi-step workflow (like Uber Eats or Resy), verify that `network.start()` + `network.stop()` produces a clean `.endpoints` digest and that `BrowserControlClient.origin(url, { session, headers, handoffOnAuthFailure: true })` can drive the JSON API directly in one turn. Always delete temporary gauntlet sessions (`browser-control session delete "🧭 gauntlet"`) when finished.