@askjo/camofox-browser 1.6.0 → 1.7.0

package/server.js

@@ -3,6 +3,7 @@ import { VirtualDisplay } from 'camoufox-js/dist/virtdisplay.js';
 import { firefox } from 'playwright-core';
 import express from 'express';
 import crypto from 'crypto';
+import fs from 'fs';
 import os from 'os';
 import { expandMacro } from './lib/macros.js';
 import { loadConfig } from './lib/config.js';
@@ -19,6 +20,11 @@ import {
   getDownloadsList,
 } from './lib/downloads.js';
 import { extractPageImages } from './lib/images.js';
+import { extractDeterministic, validateSchema as validateExtractSchema } from './lib/extract.js';
+import {
+  ensureTracesDir, resolveTracePath, tracePathFor, makeTraceFilename,
+  listUserTraces, statTrace, deleteTrace, sweepOldTraces,
+} from './lib/tracing.js';
 
 import {
   initMetrics, getRegister, isMetricsEnabled, createMetric,
@@ -27,9 +33,29 @@ import {
 import { actionFromReq, classifyError } from './lib/request-utils.js';
 import { cleanupOrphanedTempFiles } from './lib/tmp-cleanup.js';
 import { coalesceInflight } from './lib/inflight.js';
+import { createReporter, createTabHealthTracker } from './lib/reporter.js';
+import { mountDocs } from './lib/openapi.js';
 
 const CONFIG = loadConfig();
 
+// --- Crash reporter (opt-in, anonymized GitHub issues) ---
+import { readFileSync } from 'fs';
+const _pkgVersion = (() => { try { return JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version; } catch { return 'unknown'; } })();
+const reporter = createReporter({ ...CONFIG, version: _pkgVersion });
+reporter.startWatchdog(5000, () => {
+  const summary = [];
+  for (const [userId, session] of sessions) {
+    const urls = [];
+    for (const group of session.tabGroups.values()) {
+      for (const tab of group.values()) {
+        try { if (tab.page) urls.push(tab.page.url()); } catch {}
+      }
+    }
+    summary.push({ userId, urls });
+  }
+  return { sessions: sessions.size, summary };
+});
+
 // --- Plugin event bus ---
 const pluginEvents = createPluginEvents();
 
@@ -168,10 +194,81 @@ function validateUrl(url) {
 //
 // SECURITY:
 // Cookie injection moves this from "anonymous browsing" to "authenticated browsing".
-// By default, this endpoint is protected by CAMOFOX_API_KEY.
-// For local development convenience, when CAMOFOX_API_KEY is NOT set, we allow
-// unauthenticated cookie import ONLY from loopback (127.0.0.1 / ::1) and ONLY
-// when NODE_ENV != production.
+/**
+ * @openapi
+ * /sessions/{userId}/cookies:
+ *   post:
+ *     tags: [Sessions]
+ *     summary: Import cookies into a user session
+ *     description: Import cookies for authenticated browsing. Requires BearerAuth in production.
+ *     security:
+ *       - BearerAuth: []
+ *     parameters:
+ *       - name: userId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Session owner identifier.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [cookies]
+ *             properties:
+ *               cookies:
+ *                 type: array
+ *                 maxItems: 500
+ *                 items:
+ *                   type: object
+ *                   required: [name, value, domain]
+ *                   properties:
+ *                     name:
+ *                       type: string
+ *                     value:
+ *                       type: string
+ *                     domain:
+ *                       type: string
+ *                     path:
+ *                       type: string
+ *                     expires:
+ *                       type: number
+ *                     httpOnly:
+ *                       type: boolean
+ *                     secure:
+ *                       type: boolean
+ *                     sameSite:
+ *                       type: string
+ *                       enum: [Strict, Lax, None]
+ *     responses:
+ *       200:
+ *         description: Cookies imported.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 userId:
+ *                   type: string
+ *                 count:
+ *                   type: integer
+ *       400:
+ *         description: Invalid cookie data.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       403:
+ *         description: Forbidden.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/sessions/:userId/cookies', express.json({ limit: '512kb' }), async (req, res) => {
   try {
     if (CONFIG.apiKey) {
@@ -726,6 +823,16 @@ async function closeSession(userId, session, {
     await clearSessionDownloads(session).catch(() => {});
   }
 
+  await pluginEvents.emitAsync('session:destroying', { userId: key, reason });
+  if (session.tracePath) {
+    try {
+      await session.context.tracing.stop({ path: session.tracePath });
+      log('info', 'tracing saved', { userId: key, path: session.tracePath });
+    } catch (err) {
+      log('warn', 'tracing.stop failed', { userId: key, error: err.message });
+    }
+  }
+
   await session.context.close().catch(() => {});
   sessions.delete(key);
   await pluginEvents.emitAsync('session:destroyed', { userId: key, reason });
@@ -744,7 +851,7 @@ async function closeAllSessions(reason, { clearDownloads = true, clearLocks = tr
   }
 }
 
-async function getSession(userId) {
+async function getSession(userId, { trace = false } = {}) {
   const key = normalizeUserId(userId);
   let session = sessions.get(key);
   
@@ -794,8 +901,21 @@ async function getSession(userId) {
       }
       await pluginEvents.emitAsync('session:creating', { userId: key, contextOptions });
       const context = await b.newContext(contextOptions);
-      
-      const created = { context, tabGroups: new Map(), lastAccess: Date.now(), proxySessionId: sessionProxy?.sessionId || null };
+
+      let tracePath = null;
+      if (trace) {
+        const traceDir = ensureTracesDir(CONFIG.tracesDir, key);
+        tracePath = tracePathFor(CONFIG.tracesDir, key, makeTraceFilename());
+        try {
+          await context.tracing.start({ screenshots: true, snapshots: true, sources: false });
+          log('info', 'tracing enabled for session', { userId: key, traceDir, tracePath });
+        } catch (err) {
+          log('warn', 'tracing.start failed; session will not be traced', { userId: key, error: err.message });
+          tracePath = null;
+        }
+      }
+
+      const created = { context, tabGroups: new Map(), lastAccess: Date.now(), proxySessionId: sessionProxy?.sessionId || null, tracePath };
       sessions.set(key, created);
       await pluginEvents.emitAsync('session:created', { userId: key, context });
       log('info', 'session created', {
@@ -889,7 +1009,6 @@ function handleRouteError(err, req, res, extraFields = {}) {
   }
   // Lock queue timeout = tab is stuck. Destroy immediately.
   if (userId && isTabLockQueueTimeout(err)) {
-    const tabId = req.body?.tabId || req.query?.tabId || req.params?.tabId;
     const session = sessions.get(normalizeUserId(userId));
     if (session && tabId) {
       destroyTab(session, tabId, 'lock_queue', userId);
@@ -900,6 +1019,34 @@ function handleRouteError(err, req, res, extraFields = {}) {
   if (isTabDestroyedError(err)) {
     return res.status(410).json({ error: 'Tab was destroyed. Open a new tab.', ...extraFields });
   }
+  // --- Frustration detection: report when a tab hits a streak of failures ---
+  // Individual failures are noise. 3+ consecutive = the site is persistently broken.
+  const FRUSTRATION_TYPES = new Set(['timeout', 'dead_context', 'nav_aborted']);
+  if (FRUSTRATION_TYPES.has(failureType) && userId && tabId) {
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, tabId);
+    if (found) {
+      const ts = found.tabState;
+      ts.consecutiveFailures = (ts.consecutiveFailures || 0) + 1;
+      if (!ts.failureJournal) ts.failureJournal = [];
+      ts.failureJournal.push({ type: failureType, action, at: Date.now() });
+      if (ts.failureJournal.length > 20) ts.failureJournal = ts.failureJournal.slice(-20);
+
+      if (ts.consecutiveFailures === 3) {
+        reporter.reportHang(action, req.startTime ? Date.now() - req.startTime : 0, {
+          error: err,
+          url: ts.lastRequestedUrl || undefined,
+          healthSnapshot: ts.healthTracker ? ts.healthTracker.snapshot() : undefined,
+          context: {
+            failureType,
+            consecutiveFailures: ts.consecutiveFailures,
+            toolCalls: ts.toolCalls,
+            journal: ts.failureJournal.map(j => `${j.type}:${j.action}`),
+          },
+        });
+      }
+    }
+  }
   sendError(res, err, extraFields);
 }
 
@@ -980,6 +1127,7 @@ function findTab(session, tabId) {
 }
 
 function createTabState(page) {
+  const healthTracker = createTabHealthTracker(page);
   return {
     page,
     refs: new Map(),
@@ -987,6 +1135,9 @@ function createTabState(page) {
     downloads: [],
     toolCalls: 0,
     consecutiveTimeouts: 0,
+    consecutiveFailures: 0,
+    failureJournal: [],
+    healthTracker,
     lastSnapshot: null,
     lastRequestedUrl: null,
     googleRetryCount: 0,
@@ -1509,6 +1660,47 @@ async function refreshTabRefs(tabState, options = {}) {
 }
 
 
+/**
+ * @openapi
+ * /health:
+ *   get:
+ *     tags: [System]
+ *     summary: Health check
+ *     description: Detailed health with tab/session counts and failure tracking.
+ *     responses:
+ *       200:
+ *         description: Healthy.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 engine:
+ *                   type: string
+ *                 browserConnected:
+ *                   type: boolean
+ *                 browserRunning:
+ *                   type: boolean
+ *                 activeTabs:
+ *                   type: integer
+ *                 activeSessions:
+ *                   type: integer
+ *                 consecutiveFailures:
+ *                   type: integer
+ *       503:
+ *         description: Unhealthy or recovering.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 recovering:
+ *                   type: boolean
+ */
 app.get('/health', (req, res) => {
   if (healthState.isRecovering) {
     return res.status(503).json({ ok: false, engine: 'camoufox', recovering: true });
@@ -1537,6 +1729,27 @@ app.get('/health', (req, res) => {
   });
 });
 
+/**
+ * @openapi
+ * /metrics:
+ *   get:
+ *     tags: [System]
+ *     summary: Prometheus metrics
+ *     description: Returns Prometheus text exposition format. Requires PROMETHEUS_ENABLED=1.
+ *     responses:
+ *       200:
+ *         description: Prometheus metrics.
+ *         content:
+ *           text/plain:
+ *             schema:
+ *               type: string
+ *       404:
+ *         description: Metrics disabled.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/metrics', async (_req, res) => {
   const reg = getRegister();
   if (!reg) {
@@ -1548,17 +1761,85 @@ app.get('/metrics', async (_req, res) => {
 });
 
 // Create new tab
+/**
+ * @openapi
+ * /tabs:
+ *   post:
+ *     tags: [Tabs]
+ *     summary: Create a new tab
+ *     description: Creates a tab in the given session. Optionally navigates to an initial URL.
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, sessionKey]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *                 description: Session owner.
+ *               sessionKey:
+ *                 type: string
+ *                 description: Tab group identifier.
+ *               listItemId:
+ *                 type: string
+ *                 description: Legacy alias for sessionKey.
+ *               url:
+ *                 type: string
+ *                 description: Optional initial URL.
+ *               trace:
+ *                 type: boolean
+ *                 description: Enable Playwright tracing for this session (screenshots, DOM snapshots, network). Must be set on first tab creation; cannot be added to an existing session.
+ *     responses:
+ *       200:
+ *         description: Tab created.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 tabId:
+ *                   type: string
+ *                 url:
+ *                   type: string
+ *       400:
+ *         description: Missing required fields.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       429:
+ *         description: Tab limit reached.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       409:
+ *         description: Cannot enable tracing on an existing session.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs', async (req, res) => {
   try {
-    const { userId, sessionKey, listItemId, url } = req.body;
+    const { userId, sessionKey, listItemId, url, trace } = req.body;
     // Accept both sessionKey (preferred) and listItemId (legacy) for backward compatibility
     const resolvedSessionKey = sessionKey || listItemId;
     if (!userId || !resolvedSessionKey) {
       return res.status(400).json({ error: 'userId and sessionKey required' });
     }
-    
+
     const result = await withTimeout((async () => {
-      const session = await getSession(userId);
+      const existing = sessions.get(normalizeUserId(userId));
+      if (trace && existing && !existing.tracePath) {
+        throw Object.assign(
+          new Error('trace must be set on session creation. DELETE /sessions/:userId first to restart with tracing.'),
+          { statusCode: 409 },
+        );
+      }
+      const session = await getSession(userId, { trace: !!trace });
       
       let totalTabs = 0;
       for (const group of session.tabGroups.values()) totalTabs += group.size;
@@ -1601,6 +1882,61 @@ app.post('/tabs', async (req, res) => {
 });
 
 // Navigate
+/**
+ * @openapi
+ * /tabs/{tabId}/navigate:
+ *   post:
+ *     tags: [Navigation]
+ *     summary: Navigate a tab to a URL or macro
+ *     description: Navigate to a URL or expand a search macro. Auto-creates tab if not found.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               url:
+ *                 type: string
+ *               macro:
+ *                 type: string
+ *                 description: Search macro (e.g. @google_search).
+ *               query:
+ *                 type: string
+ *                 description: Search query for macro.
+ *               sessionKey:
+ *                 type: string
+ *               listItemId:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Navigation result with snapshot.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/navigate', async (req, res) => {
   const tabId = req.params.tabId;
   
@@ -1638,7 +1974,7 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
       } else {
         tabState = found.tabState;
       }
-      tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+      tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
       
       let targetUrl = url;
       if (macro && macro !== '__NO__' && macro !== 'none' && macro !== 'null') {
@@ -1749,6 +2085,69 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
 });
 
 // Snapshot
+/**
+ * @openapi
+ * /tabs/{tabId}/snapshot:
+ *   get:
+ *     tags: [Content]
+ *     summary: Accessibility snapshot
+ *     description: Returns accessibility tree with element refs. Supports pagination via offset.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: format
+ *         in: query
+ *         schema:
+ *           type: string
+ *           enum: [text, json]
+ *           default: text
+ *       - name: offset
+ *         in: query
+ *         schema:
+ *           type: integer
+ *         description: Character offset for paginated retrieval.
+ *       - name: includeScreenshot
+ *         in: query
+ *         schema:
+ *           type: string
+ *           enum: ['true', 'false']
+ *     responses:
+ *       200:
+ *         description: Snapshot.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 url:
+ *                   type: string
+ *                 snapshot:
+ *                   type: string
+ *                 refsCount:
+ *                   type: integer
+ *                 truncated:
+ *                   type: boolean
+ *                 totalChars:
+ *                   type: integer
+ *                 hasMore:
+ *                   type: boolean
+ *                 nextOffset:
+ *                   type: integer
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/tabs/:tabId/snapshot', async (req, res) => {
   try {
     const userId = req.query.userId;
@@ -1760,7 +2159,7 @@ app.get('/tabs/:tabId/snapshot', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
 
     // Cached chunk retrieval for offset>0 requests
     if (offset > 0 && tabState.lastSnapshot) {
@@ -1889,6 +2288,50 @@ app.get('/tabs/:tabId/snapshot', async (req, res) => {
 });
 
 // Wait for page ready
+/**
+ * @openapi
+ * /tabs/{tabId}/wait:
+ *   post:
+ *     tags: [Interaction]
+ *     summary: Wait for a selector or timeout
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               selector:
+ *                 type: string
+ *               timeout:
+ *                 type: integer
+ *                 description: Max wait in ms.
+ *     responses:
+ *       200:
+ *         description: Wait completed.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/wait', async (req, res) => {
   try {
     const { userId, timeout = 10000, waitForNetwork = true } = req.body;
@@ -1907,6 +2350,64 @@ app.post('/tabs/:tabId/wait', async (req, res) => {
 });
 
 // Click
+/**
+ * @openapi
+ * /tabs/{tabId}/click:
+ *   post:
+ *     tags: [Interaction]
+ *     summary: Click an element
+ *     description: Click by element ref, CSS selector, or coordinates.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               ref:
+ *                 type: string
+ *                 description: Element ref ID (e.g. "e3").
+ *               selector:
+ *                 type: string
+ *                 description: CSS selector fallback.
+ *               doubleClick:
+ *                 type: boolean
+ *               coordinates:
+ *                 type: object
+ *                 properties:
+ *                   x:
+ *                     type: number
+ *                   y:
+ *                     type: number
+ *     responses:
+ *       200:
+ *         description: Click result with optional post-action snapshot.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/click', async (req, res) => {
   const tabId = req.params.tabId;
   
@@ -1918,7 +2419,7 @@ app.post('/tabs/:tabId/click', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     if (!ref && !selector) {
       return res.status(400).json({ error: 'ref or selector required' });
@@ -2079,6 +2580,61 @@ app.post('/tabs/:tabId/click', async (req, res) => {
 });
 
 // Type
+/**
+ * @openapi
+ * /tabs/{tabId}/type:
+ *   post:
+ *     tags: [Interaction]
+ *     summary: Type text into an element
+ *     description: Types text into a focused element or a specific ref/selector.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, text]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               ref:
+ *                 type: string
+ *               selector:
+ *                 type: string
+ *               text:
+ *                 type: string
+ *               clear:
+ *                 type: boolean
+ *                 description: Clear field before typing.
+ *               submit:
+ *                 type: boolean
+ *                 description: Press Enter after typing.
+ *     responses:
+ *       200:
+ *         description: Type result.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/type', async (req, res) => {
   const tabId = req.params.tabId;
   
@@ -2089,7 +2645,7 @@ app.post('/tabs/:tabId/type', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     if (mode !== 'fill' && mode !== 'keyboard') {
       return res.status(400).json({ error: "mode must be 'fill' or 'keyboard'" });
@@ -2161,6 +2717,48 @@ app.post('/tabs/:tabId/type', async (req, res) => {
 });
 
 // Press key
+/**
+ * @openapi
+ * /tabs/{tabId}/press:
+ *   post:
+ *     tags: [Interaction]
+ *     summary: Press a keyboard key
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, key]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               key:
+ *                 type: string
+ *                 description: Key name (e.g. "Enter", "Escape", "Tab").
+ *     responses:
+ *       200:
+ *         description: Key pressed.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/press', async (req, res) => {
   const tabId = req.params.tabId;
   
@@ -2171,7 +2769,7 @@ app.post('/tabs/:tabId/press', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     await withTabLock(tabId, async () => {
       await tabState.page.keyboard.press(key);
@@ -2186,6 +2784,51 @@ app.post('/tabs/:tabId/press', async (req, res) => {
 });
 
 // Scroll
+/**
+ * @openapi
+ * /tabs/{tabId}/scroll:
+ *   post:
+ *     tags: [Interaction]
+ *     summary: Scroll the page
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               direction:
+ *                 type: string
+ *                 description: '"up" or "down" (default "down").'
+ *               amount:
+ *                 type: integer
+ *                 description: Pixels to scroll.
+ *     responses:
+ *       200:
+ *         description: Scroll result.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/scroll', async (req, res) => {
   try {
     const { userId, direction = 'down', amount = 500 } = req.body;
@@ -2194,7 +2837,7 @@ app.post('/tabs/:tabId/scroll', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     const isVertical = direction === 'up' || direction === 'down';
     const delta = (direction === 'up' || direction === 'left') ? -amount : amount;
@@ -2210,6 +2853,47 @@ app.post('/tabs/:tabId/scroll', async (req, res) => {
 });
 
 // Back
+/**
+ * @openapi
+ * /tabs/{tabId}/back:
+ *   post:
+ *     tags: [Navigation]
+ *     summary: Go back
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Navigated back.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 url:
+ *                   type: string
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/back', async (req, res) => {
   const tabId = req.params.tabId;
   
@@ -2220,7 +2904,7 @@ app.post('/tabs/:tabId/back', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     const result = await withTabLock(tabId, async () => {
       try {
@@ -2246,6 +2930,47 @@ app.post('/tabs/:tabId/back', async (req, res) => {
 });
 
 // Forward
+/**
+ * @openapi
+ * /tabs/{tabId}/forward:
+ *   post:
+ *     tags: [Navigation]
+ *     summary: Go forward
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Navigated forward.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 url:
+ *                   type: string
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/forward', async (req, res) => {
   const tabId = req.params.tabId;
   
@@ -2256,7 +2981,7 @@ app.post('/tabs/:tabId/forward', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     const result = await withTabLock(tabId, async () => {
       await tabState.page.goForward({ timeout: 10000 });
@@ -2272,6 +2997,47 @@ app.post('/tabs/:tabId/forward', async (req, res) => {
 });
 
 // Refresh
+/**
+ * @openapi
+ * /tabs/{tabId}/refresh:
+ *   post:
+ *     tags: [Navigation]
+ *     summary: Refresh page
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Page refreshed.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 url:
+ *                   type: string
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/refresh', async (req, res) => {
   const tabId = req.params.tabId;
   
@@ -2282,7 +3048,7 @@ app.post('/tabs/:tabId/refresh', async (req, res) => {
     if (!found) return res.status(404).json({ error: 'Tab not found' });
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     const result = await withTabLock(tabId, async () => {
       await tabState.page.reload({ timeout: 30000 });
@@ -2298,6 +3064,49 @@ app.post('/tabs/:tabId/refresh', async (req, res) => {
 });
 
 // Get links
+/**
+ * @openapi
+ * /tabs/{tabId}/links:
+ *   get:
+ *     tags: [Content]
+ *     summary: Extract page links
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Links extracted.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 links:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       text:
+ *                         type: string
+ *                       href:
+ *                         type: string
+ *                       ref:
+ *                         type: string
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/tabs/:tabId/links', async (req, res) => {
   try {
     const userId = req.query.userId;
@@ -2311,7 +3120,7 @@ app.get('/tabs/:tabId/links', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     const allLinks = await tabState.page.evaluate(() => {
       const links = [];
@@ -2339,6 +3148,49 @@ app.get('/tabs/:tabId/links', async (req, res) => {
 });
 
 // Get captured downloads
+/**
+ * @openapi
+ * /tabs/{tabId}/downloads:
+ *   get:
+ *     tags: [Content]
+ *     summary: List tab downloads
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Downloads list.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 downloads:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       filename:
+ *                         type: string
+ *                       url:
+ *                         type: string
+ *                       state:
+ *                         type: string
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/tabs/:tabId/downloads', async (req, res) => {
   try {
     const userId = req.query.userId;
@@ -2368,6 +3220,51 @@ app.get('/tabs/:tabId/downloads', async (req, res) => {
 });
 
 // Get image elements from current page
+/**
+ * @openapi
+ * /tabs/{tabId}/images:
+ *   get:
+ *     tags: [Content]
+ *     summary: Extract page images
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Images extracted.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 images:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       src:
+ *                         type: string
+ *                       alt:
+ *                         type: string
+ *                       width:
+ *                         type: integer
+ *                       height:
+ *                         type: integer
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/tabs/:tabId/images', async (req, res) => {
   try {
     const userId = req.query.userId;
@@ -2394,6 +3291,46 @@ app.get('/tabs/:tabId/images', async (req, res) => {
 });
 
 // Screenshot
+/**
+ * @openapi
+ * /tabs/{tabId}/screenshot:
+ *   get:
+ *     tags: [Content]
+ *     summary: Take a screenshot
+ *     description: Returns a base64-encoded PNG screenshot.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Screenshot.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 screenshot:
+ *                   type: object
+ *                   properties:
+ *                     data:
+ *                       type: string
+ *                     mimeType:
+ *                       type: string
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/tabs/:tabId/screenshot', async (req, res) => {
   try {
     const userId = req.query.userId;
@@ -2414,6 +3351,53 @@ app.get('/tabs/:tabId/screenshot', async (req, res) => {
 });
 
 // Stats
+/**
+ * @openapi
+ * /tabs/{tabId}/stats:
+ *   get:
+ *     tags: [Tabs]
+ *     summary: Tab statistics
+ *     description: Returns tab metadata including URL, tool call count, visited URLs, download/failure counts.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Tab stats.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 tabId:
+ *                   type: string
+ *                 url:
+ *                   type: string
+ *                 toolCalls:
+ *                   type: integer
+ *                 visitedUrls:
+ *                   type: array
+ *                   items:
+ *                     type: string
+ *                 downloadCount:
+ *                   type: integer
+ *                 consecutiveFailures:
+ *                   type: integer
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/tabs/:tabId/stats', async (req, res) => {
   try {
     const userId = req.query.userId;
@@ -2439,6 +3423,56 @@ app.get('/tabs/:tabId/stats', async (req, res) => {
 });
 
 // Evaluate JavaScript in page context
+/**
+ * @openapi
+ * /tabs/{tabId}/evaluate:
+ *   post:
+ *     tags: [Interaction]
+ *     summary: Evaluate JavaScript in tab
+ *     description: Runs arbitrary JS in the page context and returns the result.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, expression]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               expression:
+ *                 type: string
+ *                 description: JavaScript expression to evaluate.
+ *     responses:
+ *       200:
+ *         description: Evaluation result.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 result: {}
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/:tabId/evaluate', express.json({ limit: '1mb' }), async (req, res) => {
   try {
     const { userId, expression } = req.body;
@@ -2451,7 +3485,7 @@ app.post('/tabs/:tabId/evaluate', express.json({ limit: '1mb' }), async (req, re
 
     session.lastAccess = Date.now();
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
 
     pluginEvents.emit('tab:evaluate', { userId, tabId: req.params.tabId, expression });
     const result = await tabState.page.evaluate(expression);
@@ -2465,7 +3499,192 @@ app.post('/tabs/:tabId/evaluate', express.json({ limit: '1mb' }), async (req, re
   }
 });
 
+// Structured extraction using JSON Schema with x-ref hints
+/**
+ * @openapi
+ * /tabs/{tabId}/extract:
+ *   post:
+ *     tags: [Content]
+ *     summary: Structured data extraction via JSON Schema
+ *     description: |
+ *       Extracts structured data from the current page using a JSON Schema whose properties
+ *       carry `x-ref` hints pointing at snapshot element refs (e.g. `e1`, `e2`).  
+ *       Call `GET /tabs/{tabId}/snapshot` first to populate the ref table.
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, schema]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               schema:
+ *                 type: object
+ *                 description: |
+ *                   JSON Schema with `type: "object"` and a `properties` map.  
+ *                   Each property may include `x-ref` (a snapshot element ref) and an optional
+ *                   `type` (`string`, `number`, `integer`, `boolean`).
+ *                 required: [type, properties]
+ *                 properties:
+ *                   type:
+ *                     type: string
+ *                     enum: [object]
+ *                   properties:
+ *                     type: object
+ *                     additionalProperties:
+ *                       type: object
+ *                       properties:
+ *                         type:
+ *                           type: string
+ *                           enum: [string, number, integer, boolean, object, "null"]
+ *                         x-ref:
+ *                           type: string
+ *                           description: Snapshot element ref (e.g. `e1`).
+ *                   required:
+ *                     type: array
+ *                     items:
+ *                       type: string
+ *                     description: Property names that must resolve to a non-null value.
+ *     responses:
+ *       200:
+ *         description: Extraction succeeded.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 data:
+ *                   type: object
+ *                   description: Extracted key-value pairs matching the input schema.
+ *       400:
+ *         description: Missing userId, missing schema, or invalid schema.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       409:
+ *         description: No refs available — call snapshot first.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 error:
+ *                   type: string
+ *                 snapshot:
+ *                   type: string
+ *                   nullable: true
+ *       422:
+ *         description: Extraction failed (e.g. required ref not found).
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 error:
+ *                   type: string
+ *                 snapshot:
+ *                   type: string
+ *                   nullable: true
+ *       500:
+ *         description: Internal server error.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+app.post('/tabs/:tabId/extract', express.json({ limit: '256kb' }), async (req, res) => {
+  try {
+    const { userId, schema } = req.body;
+    if (!userId) return res.status(400).json({ error: 'userId is required' });
+    if (!schema) return res.status(400).json({ error: 'schema is required' });
+
+    const check = validateExtractSchema(schema);
+    if (!check.ok) return res.status(400).json({ error: check.error });
+
+    const session = sessions.get(normalizeUserId(userId));
+    const found = session && findTab(session, req.params.tabId);
+    if (!found) return res.status(404).json({ error: 'Tab not found' });
+
+    session.lastAccess = Date.now();
+    const { tabState } = found;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+
+    if (!tabState.refs || tabState.refs.size === 0) {
+      return res.status(409).json({
+        error: 'no refs available — call GET /tabs/:tabId/snapshot first to build the ref table',
+        snapshot: tabState.lastSnapshot || null,
+      });
+    }
+
+    try {
+      const data = extractDeterministic({ schema, refs: tabState.refs });
+      log('info', 'extract', { reqId: req.reqId, tabId: req.params.tabId, userId, keys: Object.keys(data) });
+      res.json({ ok: true, data });
+    } catch (extractErr) {
+      log('warn', 'extract failed', { reqId: req.reqId, error: extractErr.message });
+      res.status(422).json({ ok: false, error: extractErr.message, snapshot: tabState.lastSnapshot || null });
+    }
+  } catch (err) {
+    failuresTotal.labels(classifyError(err), 'extract').inc();
+    log('error', 'extract error', { reqId: req.reqId, error: err.message });
+    res.status(500).json({ error: safeError(err) });
+  }
+});
+
 // Close tab
+/**
+ * @openapi
+ * /tabs/{tabId}:
+ *   delete:
+ *     tags: [Tabs]
+ *     summary: Close a tab
+ *     parameters:
+ *       - name: tabId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Tab closed.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.delete('/tabs/:tabId', async (req, res) => {
   try {
     const userId = req.query.userId || req.body?.userId;
@@ -2492,6 +3711,42 @@ app.delete('/tabs/:tabId', async (req, res) => {
 });
 
 // Close tab group
+/**
+ * @openapi
+ * /tabs/group/{listItemId}:
+ *   delete:
+ *     tags: [Tabs]
+ *     summary: Close all tabs in a group
+ *     parameters:
+ *       - name: listItemId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Group closed.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 closed:
+ *                   type: integer
+ *       404:
+ *         description: Session not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.delete('/tabs/group/:listItemId', async (req, res) => {
   try {
     const userId = req.query.userId || req.body?.userId;
@@ -2520,7 +3775,254 @@ app.delete('/tabs/group/:listItemId', async (req, res) => {
   }
 });
 
+// List trace files for a session
+/**
+ * @openapi
+ * /sessions/{userId}/traces:
+ *   get:
+ *     tags: [Sessions]
+ *     summary: List trace files
+ *     description: Returns all Playwright trace zip files for the given user session, sorted newest first.
+ *     security:
+ *       - BearerAuth: []
+ *     parameters:
+ *       - name: userId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Session owner identifier.
+ *     responses:
+ *       200:
+ *         description: Trace list.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 traces:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       filename:
+ *                         type: string
+ *                       sizeBytes:
+ *                         type: integer
+ *                       createdAt:
+ *                         type: number
+ *                       modifiedAt:
+ *                         type: number
+ *       403:
+ *         description: Forbidden.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Server error.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+app.get('/sessions/:userId/traces', authMiddleware(), async (req, res) => {
+  try {
+    const userId = normalizeUserId(req.params.userId);
+    const traces = await listUserTraces(CONFIG.tracesDir, userId);
+    res.json({ traces });
+  } catch (err) {
+    log('error', 'list traces failed', { error: err.message });
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// Stream one trace file
+/**
+ * @openapi
+ * /sessions/{userId}/traces/{filename}:
+ *   get:
+ *     tags: [Sessions]
+ *     summary: Download a trace file
+ *     description: Streams a Playwright trace zip for viewing in trace.playwright.dev.
+ *     security:
+ *       - BearerAuth: []
+ *     parameters:
+ *       - name: userId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Session owner identifier.
+ *       - name: filename
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Trace zip filename.
+ *     responses:
+ *       200:
+ *         description: Trace zip stream.
+ *         content:
+ *           application/zip:
+ *             schema:
+ *               type: string
+ *               format: binary
+ *       400:
+ *         description: Invalid filename.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Trace not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       403:
+ *         description: Forbidden.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Server error.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+app.get('/sessions/:userId/traces/:filename', authMiddleware(), async (req, res) => {
+  try {
+    const userId = normalizeUserId(req.params.userId);
+    const full = resolveTracePath(CONFIG.tracesDir, userId, req.params.filename);
+    if (!full) return res.status(400).json({ error: 'invalid filename' });
+    const st = await statTrace(full);
+    if (!st) return res.status(404).json({ error: 'not found' });
+    res.setHeader('Content-Type', 'application/zip');
+    res.setHeader('Content-Length', String(st.size));
+    const stream = fs.createReadStream(full);
+    stream.on('error', (err) => {
+      if (!res.headersSent) res.status(404).json({ error: 'not found' });
+      else res.destroy();
+    });
+    stream.pipe(res);
+  } catch (err) {
+    log('error', 'stream trace failed', { error: err.message });
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// Delete one trace file
+/**
+ * @openapi
+ * /sessions/{userId}/traces/{filename}:
+ *   delete:
+ *     tags: [Sessions]
+ *     summary: Delete a trace file
+ *     description: Removes a specific Playwright trace zip from the server.
+ *     security:
+ *       - BearerAuth: []
+ *     parameters:
+ *       - name: userId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Session owner identifier.
+ *       - name: filename
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Trace zip filename.
+ *     responses:
+ *       200:
+ *         description: Trace deleted.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *       400:
+ *         description: Invalid filename.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Trace not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       403:
+ *         description: Forbidden.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       500:
+ *         description: Server error.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
+app.delete('/sessions/:userId/traces/:filename', authMiddleware(), async (req, res) => {
+  try {
+    const userId = normalizeUserId(req.params.userId);
+    const full = resolveTracePath(CONFIG.tracesDir, userId, req.params.filename);
+    if (!full) return res.status(400).json({ error: 'invalid filename' });
+    try {
+      await deleteTrace(full);
+    } catch (err) {
+      if (err.code === 'ENOENT') return res.status(404).json({ error: 'not found' });
+      throw err;
+    }
+    res.json({ ok: true });
+  } catch (err) {
+    log('error', 'delete trace failed', { error: err.message });
+    res.status(500).json({ error: err.message });
+  }
+});
+
 // Close session
+/**
+ * @openapi
+ * /sessions/{userId}:
+ *   delete:
+ *     tags: [Sessions]
+ *     summary: Destroy a user session
+ *     description: Closes all tabs and cleans up state for the given userId.
+ *     parameters:
+ *       - name: userId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Session destroyed.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 closed:
+ *                   type: integer
+ *       404:
+ *         description: Session not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.delete('/sessions/:userId', async (req, res) => {
   try {
     const userId = normalizeUserId(req.params.userId);
@@ -2605,6 +4107,34 @@ setInterval(() => {
 // =============================================================================
 
 // GET / - Status (passive — does not launch browser)
+/**
+ * @openapi
+ * /:
+ *   get:
+ *     tags: [System]
+ *     summary: Server status
+ *     description: Returns basic server liveness and browser state.
+ *     responses:
+ *       200:
+ *         description: Server status.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 enabled:
+ *                   type: boolean
+ *                 running:
+ *                   type: boolean
+ *                 engine:
+ *                   type: string
+ *                 browserConnected:
+ *                   type: boolean
+ *                 browserRunning:
+ *                   type: boolean
+ */
 app.get('/', (req, res) => {
   const running = browser !== null && (browser.isConnected?.() ?? false);
   res.json({ 
@@ -2618,6 +4148,45 @@ app.get('/', (req, res) => {
 });
 
 // GET /tabs - List all tabs (OpenClaw expects this)
+/**
+ * @openapi
+ * /tabs:
+ *   get:
+ *     tags: [Tabs]
+ *     summary: List open tabs
+ *     description: Returns all tabs for a given userId.
+ *     parameters:
+ *       - name: userId
+ *         in: query
+ *         schema:
+ *           type: string
+ *         description: Filter by session owner.
+ *     responses:
+ *       200:
+ *         description: Tab list.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 running:
+ *                   type: boolean
+ *                 tabs:
+ *                   type: array
+ *                   items:
+ *                     type: object
+ *                     properties:
+ *                       tabId:
+ *                         type: string
+ *                       targetId:
+ *                         type: string
+ *                       url:
+ *                         type: string
+ *                       title:
+ *                         type: string
+ *                       listItemId:
+ *                         type: string
+ */
 app.get('/tabs', async (req, res) => {
   try {
     const userId = req.query.userId;
@@ -2648,6 +4217,41 @@ app.get('/tabs', async (req, res) => {
 });
 
 // POST /tabs/open - Open tab (alias for POST /tabs, OpenClaw format)
+/**
+ * @openapi
+ * /tabs/open:
+ *   post:
+ *     tags: [Legacy]
+ *     summary: Open tab (OpenClaw format)
+ *     deprecated: true
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, url]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               url:
+ *                 type: string
+ *               listItemId:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Tab opened.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/tabs/open', async (req, res) => {
   try {
     const { url, userId, listItemId = 'default' } = req.body;
@@ -2700,6 +4304,32 @@ app.post('/tabs/open', async (req, res) => {
 });
 
 // POST /start - Start browser (OpenClaw expects this)
+/**
+ * @openapi
+ * /start:
+ *   post:
+ *     tags: [Browser]
+ *     summary: Start browser
+ *     description: Ensures the browser process is running. Idempotent.
+ *     responses:
+ *       200:
+ *         description: Browser started.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 profile:
+ *                   type: string
+ *       500:
+ *         description: Launch failed.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/start', async (req, res) => {
   try {
     await ensureBrowser();
@@ -2711,6 +4341,36 @@ app.post('/start', async (req, res) => {
 });
 
 // POST /stop - Stop browser (OpenClaw expects this)
+/**
+ * @openapi
+ * /stop:
+ *   post:
+ *     tags: [Browser]
+ *     summary: Stop browser
+ *     description: Stops the browser and closes all sessions. Requires x-admin-key header.
+ *     security:
+ *       - BearerAuth: []
+ *     responses:
+ *       200:
+ *         description: Browser stopped.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 ok:
+ *                   type: boolean
+ *                 stopped:
+ *                   type: boolean
+ *                 profile:
+ *                   type: string
+ *       403:
+ *         description: Forbidden.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/stop', async (req, res) => {
   try {
     const adminKey = req.headers['x-admin-key'];
@@ -2729,6 +4389,48 @@ app.post('/stop', async (req, res) => {
 });
 
 // POST /navigate - Navigate (OpenClaw format with targetId in body)
+/**
+ * @openapi
+ * /navigate:
+ *   post:
+ *     tags: [Legacy]
+ *     summary: Navigate (OpenClaw format)
+ *     description: Navigate with targetId in body instead of path param.
+ *     deprecated: true
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, url]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               targetId:
+ *                 type: string
+ *               url:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Navigation result.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/navigate', async (req, res) => {
   try {
     const { targetId, url, userId } = req.body;
@@ -2749,7 +4451,7 @@ app.post('/navigate', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     const result = await withTabLock(targetId, async () => {
       await withPageLoadDuration('navigate', () => tabState.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }));
@@ -2774,6 +4476,58 @@ app.post('/navigate', async (req, res) => {
 });
 
 // GET /snapshot - Snapshot (OpenClaw format with query params)
+/**
+ * @openapi
+ * /snapshot:
+ *   get:
+ *     tags: [Legacy]
+ *     summary: Snapshot (OpenClaw format)
+ *     description: Snapshot with targetId/userId as query params.
+ *     deprecated: true
+ *     parameters:
+ *       - name: targetId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: userId
+ *         in: query
+ *         required: true
+ *         schema:
+ *           type: string
+ *       - name: format
+ *         in: query
+ *         schema:
+ *           type: string
+ *       - name: offset
+ *         in: query
+ *         schema:
+ *           type: integer
+ *       - name: includeScreenshot
+ *         in: query
+ *         schema:
+ *           type: string
+ *           enum: ['true', 'false']
+ *     responses:
+ *       200:
+ *         description: Snapshot.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.get('/snapshot', async (req, res) => {
   try {
     const { targetId, userId, format = 'text' } = req.query;
@@ -2789,7 +4543,7 @@ app.get('/snapshot', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
 
     // Cached chunk retrieval
     if (offset > 0 && tabState.lastSnapshot) {
@@ -2884,6 +4638,61 @@ app.get('/snapshot', async (req, res) => {
 
 // POST /act - Combined action endpoint (OpenClaw format)
 // Routes to click/type/scroll/press/etc based on 'kind' parameter
+/**
+ * @openapi
+ * /act:
+ *   post:
+ *     tags: [Legacy]
+ *     summary: Combined action (OpenClaw format)
+ *     description: Routes to click/type/scroll/press/etc based on "kind" parameter.
+ *     deprecated: true
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [userId, kind]
+ *             properties:
+ *               userId:
+ *                 type: string
+ *               kind:
+ *                 type: string
+ *                 description: 'Action kind: click, type, scroll, press, key, select_option, drag, hover, screenshot, wait, back, forward.'
+ *               targetId:
+ *                 type: string
+ *               ref:
+ *                 type: string
+ *               selector:
+ *                 type: string
+ *               text:
+ *                 type: string
+ *               key:
+ *                 type: string
+ *               direction:
+ *                 type: string
+ *               url:
+ *                 type: string
+ *     responses:
+ *       200:
+ *         description: Action result.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       400:
+ *         description: Bad request.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ *       404:
+ *         description: Tab not found.
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/Error'
+ */
 app.post('/act', async (req, res) => {
   try {
     const { kind, targetId, userId, ...params } = req.body;
@@ -2902,7 +4711,7 @@ app.post('/act', async (req, res) => {
     }
     
     const { tabState } = found;
-    tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
+    tabState.toolCalls++; tabState.consecutiveTimeouts = 0; tabState.consecutiveFailures = 0;
     
     const result = await withTabLock(targetId, async () => {
       switch (kind) {
@@ -3119,6 +4928,7 @@ setInterval(async () => {
 process.on('uncaughtException', (err) => {
   pluginEvents.emit('browser:error', { error: err });
   log('error', 'uncaughtException', { error: err.message, stack: err.stack });
+  reporter.reportCrash(err);
   process.exit(1);
 });
 process.on('unhandledRejection', (reason) => {
@@ -3191,6 +5001,9 @@ const pluginCtx = {
 };
 const loadedPlugins = await loadPlugins(app, pluginCtx);
 
+// --- OpenAPI docs (after all routes are registered) ---
+mountDocs(app);
+
 const server = app.listen(PORT, async () => {
   startMemoryReporter();
   refreshActiveTabsGauge();
@@ -3205,6 +5018,14 @@ const server = app.listen(PORT, async () => {
   if (tmpCleanup.removed > 0) {
     log('info', 'cleaned up orphaned camoufox temp files', tmpCleanup);
   }
+  const traceSweep = sweepOldTraces({
+    baseDir: CONFIG.tracesDir,
+    ttlMs: CONFIG.tracesTtlHours * 3600 * 1000,
+    maxBytesPerFile: CONFIG.tracesMaxBytes,
+  });
+  if (traceSweep.removedTtl > 0 || traceSweep.removedOversized > 0) {
+    log('info', 'swept old traces', traceSweep);
+  }
   // Pre-warm browser so first request doesn't eat a 6-7s cold start
   try {
     const start = Date.now();