@askjo/camofox-browser 1.6.0 → 1.7.1

package/README.md

@@ -3,20 +3,24 @@
   <h1>camofox-browser</h1>
   <p><strong>Anti-detection browser server for AI agents, powered by Camoufox</strong></p>
   <p>
-    <a href="https://github.com/jo-inc/camofox-browser/actions"><img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build" /></a>
-    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a>
-    <a href="https://camoufox.com"><img src="https://img.shields.io/badge/engine-Camoufox-red" alt="Camoufox" /></a>
-    <a href="https://hub.docker.com"><img src="https://img.shields.io/badge/docker-ready-blue" alt="Docker" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+    <a href="https://github.com/jo-inc/camofox-browser/stargazers"><img src="https://img.shields.io/github/stars/jo-inc/camofox-browser" alt="GitHub stars" /></a>
+    <a href="https://www.npmjs.com/package/camofox-browser"><img src="https://img.shields.io/npm/v/camofox-browser" alt="npm version" /></a>
+    <a href="https://github.com/jo-inc/camofox-browser/commits"><img src="https://img.shields.io/github/last-commit/jo-inc/camofox-browser" alt="GitHub last commit" /></a>
   </p>
   <p>
     Standing on the mighty shoulders of <a href="https://camoufox.com">Camoufox</a> - a Firefox fork with fingerprint spoofing at the C++ level.
-    <br/><br/>
-    The same engine behind <a href="https://askjo.ai?ref=camofox">Jo</a> — an AI assistant that doesn't need you to babysit it. Runs half on your Mac, half on a dedicated cloud machine that only you use. Available on macOS, Telegram, and WhatsApp. <a href="https://askjo.ai?ref=camofox">Try the beta free →</a>
   </p>
 </div>
 
 <br/>
 
+> <a href="https://askjo.ai?ref=camofox"><img src="jo-logo.png" alt="Jo" width="80" height="80" align="left" /></a>
+>
+> Built by the team behind <a href="https://askjo.ai?ref=camofox"><strong>jo — a personal AI agent</strong></a> that runs half on your Mac, half on a dedicated cloud machine just for you — with zero maintenance needed. Available on macOS, Telegram, WhatsApp, and email. <a href="https://askjo.ai?ref=camofox">Try the beta free →</a>
+
+<br/>
+
 ```bash
 git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
 npm install && npm start
@@ -51,6 +55,10 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 - **DOM Image Extraction** - list `<img>` src/alt and optionally return inline data URLs
 - **Deploy Anywhere** - Docker, Fly.io, Railway
 - **VNC Interactive Login** - log into sites visually via noVNC, export storage state for agent reuse
+- **OpenAPI Docs** - auto-generated spec at [`/openapi.json`](http://localhost:9377/openapi.json) and interactive docs at [`/docs`](http://localhost:9377/docs)
+- **Structured Extract** - `POST /tabs/:tabId/extract` with a JSON Schema that maps properties to snapshot refs via `x-ref`
+- **Session Tracing** - opt-in per-session Playwright trace capture (screenshots + DOM snapshots + network) with API endpoints to list, fetch, and delete trace zips
+- **Crash Reporter** - automatic [anonymized crash/hang reporting](lib/reporter.js#L28-L290) via GitHub Issues. Identifies which sites cause failures and common failure patterns. Private domains are HMAC-hashed, paths/params stripped, tokens/IPs redacted. Opt-out with `CAMOFOX_CRASH_REPORT_ENABLED=false`.
 
 ## Optional Dependencies
 
@@ -103,11 +111,11 @@ make up ARCH=x86_64
 make up VERSION=135.0.1 RELEASE=beta.24
 ```
 
-Note: `make fetch` (or `make build`) must be run first — the Dockerfile expects pre-downloaded binaries in `dist/`.
+> **⚠️ Do not run `docker build` directly.** The Dockerfile uses bind mounts to pull pre-downloaded binaries from `dist/`. Always use `make up` (or `make fetch` then `make build`) — it downloads the binaries first.
 
 ### Fly.io / Railway
 
-`fly.toml` and `railway.toml` are included. Deploy with `fly deploy` or connect the repo to Railway.
+`railway.toml` is included. For Fly.io or other remote CI, you'll need a Dockerfile that downloads binaries at build time instead of using bind mounts — see [jo-browser](https://github.com/jo-inc/jo-browser) for an example.
 
 ## Usage
 
@@ -193,6 +201,48 @@ By default, camofox persists each user's cookies and localStorage to `~/.camofox
 
 Override the directory with `CAMOFOX_PROFILE_DIR` or set `"profileDir"` in the persistence plugin config. To disable persistence, set `"persistence": { "enabled": false }` in `camofox.config.json`.
 
+### Session Tracing
+
+Capture a Playwright trace of every action in a session: page screenshots, DOM snapshots, network requests, and console output. Output is a single `.zip` file you can open in Playwright's built-in Trace Viewer.
+
+Opt-in per session by passing `trace: true` when opening the first tab:
+
+```bash
+curl -X POST http://localhost:9377/tabs \
+  -H 'Content-Type: application/json' \
+  -d '{"userId":"agent1","sessionKey":"task1","url":"https://example.com","trace":true}'
+```
+
+The trace is written when the session closes. Close the session to flush it, then list, fetch, and view:
+
+```bash
+# Close the session to flush the trace
+curl -X DELETE http://localhost:9377/sessions/agent1
+
+# List trace files
+curl http://localhost:9377/sessions/agent1/traces
+# {"traces":[{"filename":"trace-2026-04-18T04-05-00-...zip","sizeBytes":42810,"createdAt":...}]}
+
+# Download (Content-Type: application/zip)
+curl http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip > session.zip
+
+# View it in Playwright's Trace Viewer
+npx playwright show-trace session.zip
+
+# Delete
+curl -X DELETE http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip
+```
+
+Why traces instead of video: Camoufox is Firefox-based, and Playwright's `recordVideo` is Chromium-only. Traces work on Firefox and give you more than video (network + DOM + console + screenshots).
+
+Tracing cannot be toggled on an existing session. `DELETE /sessions/:userId` first if you need to change the flag.
+
+Storage defaults to `~/.camofox/traces/<hashed-userId>/` and is swept on server startup:
+
+- `CAMOFOX_TRACES_DIR` - base directory (default: `~/.camofox/traces`)
+- `CAMOFOX_TRACES_MAX_BYTES` - max size per trace, removed at next startup if exceeded (default: 50MB)
+- `CAMOFOX_TRACES_TTL_HOURS` - traces older than this are removed at next startup (default: 24)
+
 #### Standalone server usage
 
 ```bash
@@ -262,6 +312,60 @@ When a proxy is configured:
 - Browser fingerprint (language, timezone, coordinates) is consistent with the proxy location
 - Without a proxy, defaults to `en-US`, `America/Los_Angeles`, San Francisco coordinates
 
+### Crash Reporter
+
+Browser automation fails in ways that are hard to predict — Cloudflare challenges, site redesigns breaking selectors, redirect loops, dialog storms, renderer crashes. The scope is wide and the failure modes are diverse. Without telemetry, the only signal is "it didn't work."
+
+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 when:
+
+- **Uncaught exceptions** crash the process
+- **Event loop stalls** exceed 5 seconds (watchdog detection)
+- **Frustration patterns** — 3+ consecutive failures (timeout, dead context, navigation abort) on the same tab
+
+Each report includes the failure type, stack trace, tab health counters (HTTP status histogram, console errors, request failures, redirect depth), and the target URL — all anonymized.
+
+#### Privacy
+
+All reported data goes through paranoid anonymization ([`lib/reporter.js` L28–290](lib/reporter.js#L28-L290)) before leaving the process:
+
+- **URLs** — well-known public domains (Google, Amazon, Reddit, Cloudflare, etc.) are shown verbatim so we can identify which sites cause problems. Private/unknown domains are replaced with a stable HMAC hash (`site-a1b2c3d4`) — same hash across reports for correlation, but not reversible to the original domain. Path segments become `•/•/•` (depth only). Query params become `?[3]` (count only). No keys, values, or path content is ever included.
+- **File paths** → stripped to filename only (`<path>/server.js`)
+- **Tokens, secrets, API keys** → `<token>`
+- **IPs, emails, env vars** → redacted
+- **Docker/Fly machine IDs** → `<id>`
+- **Tab health** — pure counters (crash count, error count, status code histogram). No page content, no URLs, no user data.
+
+Duplicate issues are detected by stack signature and get a `+1` comment instead of a new issue.
+
+Uses a dedicated GitHub App ([Camofox Crash/Stuck Reporter](https://github.com/apps/camofox-crash-stuck-reporter)) with issues-only permissions — no PAT or configuration required.
+
+```bash
+# Disable crash reporting
+export CAMOFOX_CRASH_REPORT_ENABLED=false
+
+# Report to a different repo (default: jo-inc/camofox-browser)
+export CAMOFOX_CRASH_REPORT_REPO=your-org/your-repo
+
+# Adjust rate limit (default: 10 per hour)
+export CAMOFOX_CRASH_REPORT_RATE_LIMIT=5
+```
+
+#### Reporting to your own repo
+
+By default, reports go to `jo-inc/camofox-browser`. To file issues in your own repo instead, create a GitHub App:
+
+1. Go to **Settings → Developer settings → GitHub Apps → New GitHub App**
+2. Set permissions: **Repository → Issues → Read & Write**. Uncheck **Webhook → Active**.
+3. Click **Generate a private key** — downloads a `.pem` file
+4. Install the app on your target repo (Install App → select repo)
+5. Note your **App ID** (number on the app's settings page) and **Installation ID** (from the URL after installing: `github.com/settings/installations/{id}`)
+6. Base64-encode the private key and split it into two halves:
+   ```bash
+   base64 < your-app.pem | tr -d '\n' | fold -w $(($(base64 < your-app.pem | tr -d '\n' | wc -c) / 2)) | head -2
+   ```
+7. Replace `_GH_APP_ID`, `_GH_INSTALL_ID`, `_K_A`, and `_K_B` in `lib/reporter.js` with your values
+8. Set `CAMOFOX_CRASH_REPORT_REPO=your-org/your-repo`
+
 ### Structured Logging
 
 All log output is JSON (one object per line) for easy parsing by log aggregators:
@@ -381,6 +485,9 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `CAMOFOX_ADMIN_KEY` | Required for `POST /stop` | - |
 | `CAMOFOX_COOKIES_DIR` | Directory for cookie files | `~/.camofox/cookies` |
 | `CAMOFOX_PROFILE_DIR` | Directory for persisted session profiles | `~/.camofox/profiles` |
+| `CAMOFOX_TRACES_DIR` | Directory for session trace zips | `~/.camofox/traces` |
+| `CAMOFOX_TRACES_MAX_BYTES` | Max size per trace, removed on next startup if exceeded | `52428800` (50MB) |
+| `CAMOFOX_TRACES_TTL_HOURS` | Traces older than this are swept on startup | `24` |
 | `MAX_SESSIONS` | Max concurrent browser sessions | `50` |
 | `MAX_TABS_PER_SESSION` | Max tabs per session | `10` |
 | `SESSION_TIMEOUT_MS` | Session inactivity timeout | `1800000` (30min) |
@@ -399,6 +506,9 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `PROXY_COUNTRY` | Target country for proxy geo-targeting | - |
 | `PROXY_STATE` | Target state/region for proxy geo-targeting | - |
 | `TAB_INACTIVITY_MS` | Close tabs idle longer than this | `300000` (5min) |
+| `CAMOFOX_CRASH_REPORT_ENABLED` | Enable anonymized crash/hang reporter (`false` to disable) | `true` |
+| `CAMOFOX_CRASH_REPORT_REPO` | GitHub repo for issue reports | `jo-inc/camofox-browser` |
+| `CAMOFOX_CRASH_REPORT_RATE_LIMIT` | Max reports per hour | `10` |
 | `ENABLE_VNC` | Enable VNC plugin for interactive browser access (`1`) | - |
 | `VNC_PASSWORD` | Password for VNC access (recommended in production) | - |
 | `NOVNC_PORT` | noVNC web UI port | `6080` |

package/camofox.config.json

@@ -6,5 +6,13 @@
     "youtube": { "enabled": true },
     "persistence": { "enabled": true },
     "vnc": { "resolution": "1920x1080" }
+  },
+  "crashReporter": {
+    "appId": "3503870",
+    "installationId": "127089401",
+    "repo": "jo-inc/camofox-browser",
+    "userAgent": "camofox-crash-reporter",
+    "keyA": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb2dJQkFBS0NBUUVBMDRQRDBWWkNRb1pYdkpCNmYwUHdGRk1scEVzbjF2blFYaHJNSkxlSDdBWElmdGhCCmtpbElUb0xNeWFCVU9aWEdUbXNNYnE2MEd5R1p4RGFQVSt4bGRQdmc2Y2QrUElUNmxSbjB2TCsrd2FNT0llMDQKUEdrallSWW1YZzhqZHFCNEhQcmlKbkQwa2srU0EwVUxBYm5jUHVhTitKNEVFYjBDZUZQRUpzNEJqd0dvcENZMwpaM1VBS2ZBVjh5Slpzc3JVM0lvVlBzckc4dHVnRFhya3JTc2Y0K1Jmdm5lejRibGk1YXJKQ1h3cXJPVE0xRERNCk9mUFhOMENQMWNIWW1XL1p0TVNiRlpsbFRobVdMb05NUXNNdlFEZ3lmWjRXbG9rL1doaWVhTWttWFB6YzFuUkkKMVltNCs0YzZVS2kzOURFSS9MODA5RUZ6OHU0K2lnN1dzaEdsZHdJREFRQUJBb0lCQVFDcC8xQWw4cjhrZXBjUApqY3QyZCtNQVl1ZHhDWnFHbEplYzJzclNnOU94cGVCRDJvbXc4SThWMHRqSEFKNVEvZ2k1UkI1azR2TU1qMC9uCnZMWXJqR2Jxdy9vN3lzT3gzbXNMNVNXbmdqRE5yc0NRRWZuTnkrN01mQ0h3SFJpeW9qeUhoamkzRHJmeTFCTVYKbjZzK0F1UjZoWkQ3amZ6VlNPVXdVcHJuV1ZFMVhuaVBaZmZSd29BQmxEQi92Zm9wWWZpKzhKaXpYQTNVaytlMwp1TEdIZHc2bzJlUkp1bW90RFBubWtsVkVSKy8vcUZpa1BqTGJBSHprNGRTM3hkMWF1ZEFUNU5hczdiUkhGeXFoCkt2eGk2blM4cTAzanBIS0JMQ0hsN212Y1JQUWhYek1XcHVQblVsNGpvRFVDQ0RITG5CcWNmZ3FjTnlzOGhuSkIKaFpueE5pbGhBb0dCQVBKNm04QXo5KytnbzZjMGoxNnFsSXk3V3NyU0liSW80bXZSUEtRc0lnQUxOYTB3TXluNgozWms3NHlTdWJVaWY5c0pwM0pCNFEzdlBqVm",
+    "keyB": "9pSHBDaVZ3ZEttNFFLeC9mMVJITUtCTzVDOFlHK0VsaTlUSWllCkVjWFJMN2VyUmpValIvNjJoZVAvVG96ZXdPckxYbHFlVEEySEJ2S2RJbTFrL2ozNnlWNFVUdm1SQW9HQkFOOVAKSkRpWCt4Y083RnMwOUxxWlYxRFVhK1Rja1RQR1BMMVdlelBEeHc0M0lLVERyL2F1RWs0Mm1pK0NYY0huQk5CagpDT0Y3bEVhRTVENzdVVlZFL3JxR0E3dGdLVER3M2N5cDhQb2x3T1IwK01LUmh5MFpjeG1wcFhlb1dlZm9LVEJaCmtyQjlRbXZrZTMvdWhHUWNqemt3M2dxcE1QRmdFdFlNUUdBY3RtcUhBb0dCQUtobGNnbFhqaGJERHlTdUlldHkKdDl2TXVjOGxnL1ZBNDQ1Ukw3WXNXQ2lEb0hGNGllL2JvMDRxQXlPVVo1MEtTc3JWempJZTgyN213NW9YRy9jQwpaMEpQRkJYdGp0YXJaVEFuZ3lrZElMQWtHb1c2WVk1M2lJeERMTXAzamppVkdnalJKY2NqcForN2kyc0VkYkNsClF0Z2FNRDhKMWNEM1pJSVN5d29sUEh1aEFuOHYrZERPVjlpYUc1cXIvYlNXWWx0Z0FrTXI2RGRKNkUwa1lIQVgKcnZnVlRNSzJvMVFxcXp0RHlYZFd2YXRtL1RzTGlqdGVOaTZrOStnUm4relpaUGxWR1hXenkvVU5qcklZUm1wLwpVNTBkZUFQNXlVcEJaalpVVFI0L2x1dTU1eWJ5UEV4SG5xR21qRy84REVKbFA3MkZpL29vVURFenFuQmhqRUJJClplTExBb0dBWUQxSkp2S0d5U2NtZWVCU0J3TTRlSUF2b3RCMWR2L0NvaThDNVR2Z1F6QWRySE1BTGhIbDNtbVEKajJ3ZnpPOFlEbW45ZmdreDVvVTMyWjJNQTEyVS9mQklJLzVFYWFLK045MVVJanlFUHd1ZU42emR3c0MwT0NXWQovTVYyaFI3dlk1bmN5SUxubG1yRHNRU3htTzIrZmFhUlAxQUVtUit5aUpOUUw2ZlE1RGc9Ci0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg=="
   }
 }

package/lib/config.js

@@ -5,9 +5,22 @@
  * flag plugin.ts or server.js for env-harvesting (env + network in same file).
  */
 
-import { join } from 'path';
+import { join, dirname } from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
 import os from 'os';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = join(__dirname, '..');
+
+/** Read crashReporter section from camofox.config.json (if present). */
+function readCrashReporterConfig() {
+  try {
+    const raw = readFileSync(join(ROOT_DIR, 'camofox.config.json'), 'utf-8');
+    return JSON.parse(raw).crashReporter || {};
+  } catch { return {}; }
+}
+
 /**
  * Parse PROXY_PORTS env var into an array of port numbers.
  * Supports range ("10001-10010") or comma-separated ("10001,10002,10003").
@@ -47,6 +60,9 @@ function loadConfig() {
     apiKey: process.env.CAMOFOX_API_KEY || '',
     cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
     profileDir: process.env.CAMOFOX_PROFILE_DIR || join(os.homedir(), '.camofox', 'profiles'),
+    tracesDir: process.env.CAMOFOX_TRACES_DIR || join(os.homedir(), '.camofox', 'traces'),
+    tracesMaxBytes: parseInt(process.env.CAMOFOX_TRACES_MAX_BYTES || String(50 * 1024 * 1024), 10),
+    tracesTtlHours: parseInt(process.env.CAMOFOX_TRACES_TTL_HOURS || '24', 10),
     handlerTimeoutMs: parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000,
     maxConcurrentPerUser: parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3,
     sessionTimeoutMs: parseInt(process.env.SESSION_TIMEOUT_MS) || 600000,
@@ -82,6 +98,9 @@ function loadConfig() {
       CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY,
       CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY,
       CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR,
+      CAMOFOX_TRACES_DIR: process.env.CAMOFOX_TRACES_DIR,
+      CAMOFOX_TRACES_MAX_BYTES: process.env.CAMOFOX_TRACES_MAX_BYTES,
+      CAMOFOX_TRACES_TTL_HOURS: process.env.CAMOFOX_TRACES_TTL_HOURS,
       PROXY_STRATEGY: process.env.PROXY_STRATEGY,
       PROXY_PROVIDER: process.env.PROXY_PROVIDER,
       PROXY_HOST: process.env.PROXY_HOST,
@@ -97,6 +116,12 @@ function loadConfig() {
       PROXY_ZIP: process.env.PROXY_ZIP,
       PROXY_SESSION_DURATION_MINUTES: process.env.PROXY_SESSION_DURATION_MINUTES,
     },
+    // Crash reporter (opt-in, uses embedded GitHub App credentials)
+    // Crash reporter (opt-in, credentials from camofox.config.json)
+    crashReportEnabled:   process.env.CAMOFOX_CRASH_REPORT_ENABLED !== 'false',
+    crashReportRepo:      process.env.CAMOFOX_CRASH_REPORT_REPO,
+    crashReportRateLimit: parseInt(process.env.CAMOFOX_CRASH_REPORT_RATE_LIMIT, 10) || 10,
+    crashReporterConfig:  readCrashReporterConfig(),
   };
 }
 

package/lib/extract.js

@@ -0,0 +1,74 @@
+const SUPPORTED_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object', 'null']);
+
+export function validateSchema(schema) {
+  if (!schema || typeof schema !== 'object') {
+    return { ok: false, error: 'schema must be an object' };
+  }
+  if (schema.type !== 'object') {
+    return { ok: false, error: 'top-level schema must have type: object' };
+  }
+  if (!schema.properties || typeof schema.properties !== 'object') {
+    return { ok: false, error: 'schema must have a properties object' };
+  }
+  for (const [prop, def] of Object.entries(schema.properties)) {
+    if (!def || typeof def !== 'object') {
+      return { ok: false, error: `property "${prop}" must be an object` };
+    }
+    if (def.type && !SUPPORTED_TYPES.has(def.type)) {
+      return { ok: false, error: `property "${prop}" has unsupported type "${def.type}"` };
+    }
+  }
+  return { ok: true };
+}
+
+function coerceValue(raw, type) {
+  if (raw == null) return null;
+  if (type === 'string' || !type) return String(raw).trim();
+  if (type === 'number') {
+    const n = parseFloat(String(raw).replace(/[^0-9.eE+-]/g, ''));
+    return Number.isFinite(n) ? n : null;
+  }
+  if (type === 'integer') {
+    const n = parseInt(String(raw).replace(/[^0-9-]/g, ''), 10);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (type === 'boolean') {
+    const s = String(raw).toLowerCase().trim();
+    if (s === 'true' || s === 'yes' || s === '1') return true;
+    if (s === 'false' || s === 'no' || s === '0') return false;
+    return null;
+  }
+  return raw;
+}
+
+function extractFromRef(refs, refId) {
+  const info = refs.get(refId);
+  if (!info) return null;
+  return info.name || null;
+}
+
+export function extractDeterministic({ schema, refs }) {
+  const check = validateSchema(schema);
+  if (!check.ok) throw new Error(check.error);
+
+  const result = {};
+  for (const [prop, def] of Object.entries(schema.properties)) {
+    const refId = def['x-ref'];
+
+    let value = null;
+    if (refId) {
+      value = extractFromRef(refs, refId);
+      if (value != null && def.type && def.type !== 'object') {
+        value = coerceValue(value, def.type);
+      }
+    }
+
+    if (value == null && Array.isArray(schema.required) && schema.required.includes(prop)) {
+      throw new Error(`required property "${prop}" could not be extracted (x-ref=${refId || 'n/a'})`);
+    }
+
+    result[prop] = value;
+  }
+
+  return result;
+}

package/lib/openapi.js

@@ -0,0 +1,100 @@
+/**
+ * OpenAPI spec generation via swagger-jsdoc + docs UI (swagger-stripey).
+ *
+ * swagger-jsdoc scans JSDoc `@openapi` comments on route handlers in server.js
+ * (and any file passed in `apis`) to build the spec at startup.
+ * Docs UI lives in docs/api.html (swagger-stripey: Stripe-style 3-panel renderer).
+ *
+ * Usage:
+ *   import { mountDocs } from './lib/openapi.js';
+ *   // After all routes are registered:
+ *   mountDocs(app);
+ */
+
+import swaggerJsdoc from 'swagger-jsdoc';
+import express from 'express';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let version = 'unknown';
+try {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  version = pkg.version;
+} catch { /* ignore */ }
+
+const swaggerDefinition = {
+  openapi: '3.0.3',
+  info: {
+    title: 'camofox-browser',
+    version,
+    description:
+      'Anti-detection browser automation server for AI agents. ' +
+      'Accessibility snapshots, element refs, session isolation, cookie import, proxy rotation, and structured logs.',
+    license: { name: 'MIT', url: 'https://opensource.org/licenses/MIT' },
+    contact: { name: 'Jo Inc', url: 'https://askjo.ai', email: 'oss@askjo.ai' },
+  },
+  servers: [{ url: 'http://localhost:9377', description: 'Local development' }],
+  tags: [
+    { name: 'System', description: 'Server health, metrics, and status.' },
+    { name: 'Tabs', description: 'Create, list, inspect, and destroy browser tabs.' },
+    { name: 'Navigation', description: 'Navigate tabs to URLs or via search macros.' },
+    { name: 'Interaction', description: 'Click, type, scroll, press keys, evaluate JS.' },
+    { name: 'Content', description: 'Accessibility snapshots, screenshots, links, images, downloads.' },
+    { name: 'Sessions', description: 'Per-user session state: cookies, teardown.' },
+    { name: 'Browser', description: 'Global browser lifecycle (start/stop).' },
+    { name: 'Legacy', description: 'OpenClaw-compatible endpoints (deprecated).' },
+  ],
+  components: {
+    securitySchemes: {
+      BearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        description: 'Bearer token matching CAMOFOX_API_KEY.',
+      },
+    },
+    schemas: {
+      Error: {
+        type: 'object',
+        required: ['error'],
+        properties: { error: { type: 'string' } },
+      },
+    },
+  },
+};
+
+/**
+ * Mount GET /openapi.json and GET /docs on the Express app.
+ * Call AFTER all routes are registered so swagger-jsdoc can scan them.
+ *
+ * @param {import('express').Application} app
+ * @param {Object} [opts]
+ * @param {string[]} [opts.apis] - Glob patterns for files with @openapi JSDoc (default: ['./server.js'])
+ */
+export function mountDocs(app, opts = {}) {
+  const apis = opts.apis || ['./server.js'];
+
+  const spec = swaggerJsdoc({
+    definition: swaggerDefinition,
+    apis,
+  });
+
+  app.get('/openapi.json', (_req, res) => {
+    res.json(spec);
+  });
+
+  // Serve docs static assets (api.html, fox.png, openapi.json)
+  const docsDir = join(__dirname, '..', 'docs');
+  app.use('/docs', express.static(docsDir, { index: 'api.html' }));
+
+  // Also serve fox.png at root for backward compat with old Swagger UI HTML
+  app.get('/fox.png', (_req, res) => {
+    res.sendFile(join(docsDir, 'fox.png'));
+  });
+
+  return spec;
+}
+
+export { swaggerDefinition };

package/lib/plugins.js

@@ -17,6 +17,7 @@
  *   SESSION LIFECYCLE
  *     session:creating        { userId, contextOptions }       — mutate context options
  *     session:created         { userId, context }              — after context stored
+ *     session:destroying      { userId, reason }               — before context close (context still alive)
  *     session:destroyed       { userId, reason }               — after cleanup
  *     session:expired         { userId, idleMs }               — reaper triggered
  *