Structured Extract

POST /tabs/:tabId/extract — by @mvanhorn (#70)

Every agent that uses camofox-browser eventually writes the same code: take an accessibility snapshot, find the refs you care about, parse the name field out of each line by hand, coerce strings to numbers or booleans, trim whitespace. The extract endpoint collapses that into one request with a JSON Schema.

Pass a schema with x-ref hints pointing at snapshot refs, get back a typed object with coercion handled. No LLM, no inference, no external calls — just "look up these refs and coerce them to these types." Think the deterministic half of Stagehand's extract().

POST /tabs/:tabId/extract
{
  "schema": {
    "type": "object",
    "properties": {
      "title":   { "type": "string",  "x-ref": "e1" },
      "price":   { "type": "number",  "x-ref": "e3" },
      "inStock": { "type": "boolean", "x-ref": "e4" }
    }
  }
}
→ { "ok": true, "data": { "title": "Widget", "price": 29.99, "inStock": true } }

Session Tracing

POST /tabs with trace: true — by @mvanhorn (#68)

Every major competitor ships session capture — Steel Browser rebuilt its replay stack around MP4, Browserbase leads its observability docs with video replay, AWS Bedrock AgentCore stores recordings in S3. Camofox shipped structured logs and single-shot screenshots, which wasn't enough to reconstruct what the agent actually saw during a multi-step run.

Playwright's recordVideo doesn't work on Firefox (it uses a Chrome-only CDP method). So this uses context.tracing instead, which actually gives you more than video: screenshots + DOM snapshots + network + JS stacks + console output, all in one zip you open with npx playwright show-trace.

Pass trace: true when creating a tab. When the session closes, the trace is flushed to disk. List and download traces via /sessions/:userId/traces. TTL + size-cap sweep runs on startup. Trace directories are SHA-256-hashed per user. Default off, opt-in per session.

OpenAPI Docs

GET /docs — (#78, inspired by @mvanhorn's #69)

Auto-generated spec from @openapi JSDoc annotations on all 31 routes via swagger-jsdoc. Interactive docs at /docs using swagger-stripey. Drift-proof: tests fail if you add a route without @openapi or remove a route but leave the annotation. Legacy endpoints (/act, /navigate, /snapshot, /start, /stop) marked deprecated.

Crash & Hang Telemetry (on by default)

Browser automation fails in ways that are hard to predict — Cloudflare challenges, site redesigns breaking selectors, redirect loops, renderer crashes. The scope is wide and the failure modes are diverse. Without telemetry, the only signal is "it didn't work."

This is on by default, and that's deliberate. The failure surface of headless browser automation is enormous — every site is different, anti-bot measures change weekly, and edge cases compound across browsers, OSes, and network conditions. We can't make camofox rock-solid without knowing what actually breaks in the wild. We invested heavily in anonymization (see below) so we could make this the default responsibly. If you disagree with the tradeoff, one env var turns it off.

The crash reporter gives us structured data on which sites fail, how they fail, and how often, so we can prioritize fixes for the patterns that actually affect users. It files GitHub Issues automatically — on this repo — when:

• Uncaught exceptions crash the process
• Event loop stalls exceed 5 seconds (watchdog detection, with sleep/suspend suppression so laptop lids don't trigger false reports)
• Frustration patterns — 3+ consecutive failures (timeout, dead context, navigation abort) on the same tab

Each report is structured into sections designed for fast triage:

Environment — version, Node version, platform, uptime.

Resources — Node RSS + heap, browser process RSS (the one everyone misses — the browser OOMs, not Node), open file descriptors, active libuv handles, browser context count, active tab count. This is the difference between "it crashed" and "it crashed because 47 tabs consumed 4GB."

Hang Details — operation name, duration, time spent waiting for the tab lock vs. time in the actual operation, document.readyState at timeout (instantly tells you which layer is stuck: loading = network, interactive = heavy JS, complete = Playwright waitUntil condition not met, unresponsive = renderer crashed), in-flight request count.

Anti-Bot Detection — automatically classifies whether a hang was caused by bot detection rather than a camofox bug. Identifies the provider (Cloudflare, DataDome, PerimeterX, Distil, Sucuri, Akamai) from response headers, reports the HTTP status, redirect chain length + status codes, and response body size. Bot-detected hangs get a bot-detection label so they're filtered out of real bug triage.

Proxy — whether a proxy was configured, type (HTTP/SOCKS5), whether auth was configured, and classified error codes (ERR_PROXY_CONNECTION_FAILED, ERR_TUNNEL_CONNECTION_FAILED, ERR_PROXY_AUTH_REQUESTED, ERR_PROXY_TLS) — no IPs, hostnames, ports, or credentials.

Stall Details — event-loop stall duration, last Express route handler, active handles/requests, heap delta during the stall (positive = memory pressure, negative = GC was the cause).

What it never captures:

• Page content, DOM, screenshots, cookies, headers, request/response bodies
• User-entered data, form fields, credentials
• Proxy IPs, hostnames, ports, or credentials
• Environment variables or system configuration
• Session traces — even if tracing is enabled, traces stay on disk and are never sent to the reporter

How URLs are anonymized:

• Public infrastructure (Cloudflare, Google, GitHub, npm) preserved verbatim so we can identify which CDNs cause problems
• All other domains → stable HMAC hash (site-a1b2c3d4) — same hash across reports for correlation, not reversible to the original
• Paths → depth only (•/•/•), query params → count only (?[3]). No keys, values, or path content ever included
• Tokens, secrets, API keys → <token>. IPs, emails → redacted

How it works:

• Reports filed as GitHub Issues via dedicated GitHub App (issues-only permissions, no PAT needed)
• Rate limited to 10/hour, deduplicated by stack signature (same crash = comment on existing issue, not a new one)
• Fully overridable: Set your own GitHub App credentials in the crashReporter section of camofox.config.json to route reports to your org's private repo instead
• Disable with CAMOFOX_CRASH_REPORT_ENABLED=false

Fixes & Improvements

• session:destroying event: New lifecycle event fires before context.close(), while the Playwright context is still alive — use it for persistence checkpoints. The existing session:destroyed still fires after cleanup for backward compatibility. By @nobita2041 (#75)
• CI overhaul: GitHub Actions with full browser-backed test suite, Node 24 only, parallel unit + e2e jobs. CI initially set up by @hnshah

Discussions

We've turned on Discussions on the repo.

Thank You

Thanks to @mvanhorn for structured extract and session tracing, @nobita2041 for the session lifecycle fix, and @hnshah for getting CI off the ground.