@askjo/camofox-browser 1.4.0 → 1.4.1

package/lib/metrics.js

@@ -0,0 +1,99 @@
+// Prometheus metrics for camofox-browser.
+// Isolated in lib/ to keep process.env out of server.js (OpenClaw scanner rule).
+import client from 'prom-client';
+
+const register = new client.Registry();
+client.collectDefaultMetrics({ register });
+
+// --- Counters ---
+
+export const requestsTotal = new client.Counter({
+  name: 'jo_browser_requests_total',
+  help: 'Total HTTP requests by action and status',
+  labelNames: ['action', 'status'],
+  registers: [register],
+});
+
+export const tabLockTimeoutsTotal = new client.Counter({
+  name: 'jo_browser_tab_lock_timeouts_total',
+  help: 'Tab lock queue timeouts resulting in 503',
+  registers: [register],
+});
+
+// --- Histograms ---
+
+export const requestDuration = new client.Histogram({
+  name: 'jo_browser_request_duration_seconds',
+  help: 'Request duration in seconds by action',
+  labelNames: ['action'],
+  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60],
+  registers: [register],
+});
+
+export const pageLoadDuration = new client.Histogram({
+  name: 'jo_browser_page_load_duration_seconds',
+  help: 'Page load duration in seconds',
+  buckets: [0.5, 1, 2, 5, 10, 20, 30, 60],
+  registers: [register],
+});
+
+// --- Gauges ---
+
+export const activeTabsGauge = new client.Gauge({
+  name: 'jo_browser_active_tabs',
+  help: 'Current number of open browser tabs',
+  registers: [register],
+});
+
+export const tabLockQueueDepth = new client.Gauge({
+  name: 'jo_browser_tab_lock_queue_depth',
+  help: 'Current number of requests waiting for a tab lock',
+  registers: [register],
+});
+
+export const memoryUsageBytes = new client.Gauge({
+  name: 'jo_browser_memory_usage_bytes',
+  help: 'Process RSS memory usage in bytes',
+  registers: [register],
+});
+
+// Periodic memory reporter
+const MEMORY_INTERVAL_MS = 30_000;
+let memoryTimer = null;
+
+export function startMemoryReporter() {
+  if (memoryTimer) return;
+  const report = () => memoryUsageBytes.set(process.memoryUsage().rss);
+  report();
+  memoryTimer = setInterval(report, MEMORY_INTERVAL_MS);
+  memoryTimer.unref(); // don't keep process alive
+}
+
+export function stopMemoryReporter() {
+  if (memoryTimer) { clearInterval(memoryTimer); memoryTimer = null; }
+}
+
+// Helper: derive a short action name from Express route
+export function actionFromReq(req) {
+  const method = req.method;
+  const path = req.route?.path || req.path;
+  // POST /tabs -> create_tab, DELETE /tabs/:tabId -> delete_tab, etc.
+  if (path === '/tabs' && method === 'POST') return 'create_tab';
+  if (path === '/tabs/:tabId' && method === 'DELETE') return 'delete_tab';
+  if (path === '/tabs/group/:listItemId' && method === 'DELETE') return 'delete_tab_group';
+  if (path === '/sessions/:userId' && method === 'DELETE') return 'delete_session';
+  if (path === '/sessions/:userId/cookies' && method === 'POST') return 'set_cookies';
+  if (path === '/tabs/open' && method === 'POST') return 'open_url';
+  if (path === '/tabs' && method === 'GET') return 'list_tabs';
+  // /tabs/:tabId/<action>
+  const m = path.match(/^\/tabs\/:tabId\/(\w+)$/);
+  if (m) return m[1]; // navigate, snapshot, click, type, scroll, etc.
+  // legacy compat routes
+  if (['/start', '/stop', '/navigate', '/snapshot', '/act'].includes(path)) return path.slice(1);
+  if (path === '/youtube/transcript') return 'youtube_transcript';
+  if (path === '/health') return 'health';
+  if (path === '/metrics') return 'metrics';
+  return `${method.toLowerCase()}_${path.replace(/[/:]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+}
+
+export { register };

package/lib/proxy.js

@@ -0,0 +1,19 @@
+function decodeProxyCredential(value) {
+  if (!value) return value;
+
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function normalizePlaywrightProxy(proxy) {
+  if (!proxy) return proxy;
+
+  return {
+    ...proxy,
+    username: decodeProxyCredential(proxy.username),
+    password: decodeProxyCredential(proxy.password),
+  };
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "camofox-browser",
   "name": "Camofox Browser",
   "description": "Anti-detection browser automation for AI agents using Camoufox (Firefox-based)",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "configSchema": {
     "type": "object",
     "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "type": "module",
   "main": "server.js",
@@ -66,6 +66,7 @@
     "playwright": "^1.50.0",
     "playwright-core": "^1.58.0",
     "playwright-extra": "^4.3.6",
+    "prom-client": "^15.1.3",
     "puppeteer-extra-plugin-stealth": "^2.11.2"
   },
   "devDependencies": {

package/plugin.ts

@@ -449,7 +449,7 @@ export default function register(api: PluginApi) {
       const userId = ctx.agentId || fallbackUserId;
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/evaluate`, {
         method: "POST",
-        body: { userId, expression },
+        body: JSON.stringify({ userId, expression }),
       });
       return toToolResult(result);
     },

package/server.js

@@ -5,6 +5,7 @@ import crypto from 'crypto';
 import os from 'os';
 import { expandMacro } from './lib/macros.js';
 import { loadConfig } from './lib/config.js';
+import { normalizePlaywrightProxy } from './lib/proxy.js';
 import { windowSnapshot } from './lib/snapshot.js';
 import {
   MAX_DOWNLOAD_INLINE_BYTES,
@@ -15,6 +16,12 @@ import {
   extractPageImages,
 } from './lib/downloads.js';
 import { detectYtDlp, hasYtDlp, ytDlpTranscript, parseJson3, parseVtt, parseXml } from './lib/youtube.js';
+import {
+  register as metricsRegister,
+  requestsTotal, requestDuration, pageLoadDuration,
+  activeTabsGauge, tabLockQueueDepth,
+  tabLockTimeoutsTotal, startMemoryReporter, actionFromReq,
+} from './lib/metrics.js';
 
 const CONFIG = loadConfig();
 
@@ -37,20 +44,34 @@ function log(level, msg, fields = {}) {
 const app = express();
 app.use(express.json({ limit: '100kb' }));
 
-// Request logging middleware
+// Request logging + metrics middleware
 app.use((req, res, next) => {
-  if (req.path === '/health') return next();
   const reqId = crypto.randomUUID().slice(0, 8);
   req.reqId = reqId;
   req.startTime = Date.now();
+
   const userId = req.body?.userId || req.query?.userId || '-';
-  log('info', 'req', { reqId, method: req.method, path: req.path, userId });
+  if (req.path !== '/health') {
+    log('info', 'req', { reqId, method: req.method, path: req.path, userId });
+  }
+
+  const action = actionFromReq(req);
+  const done = requestDuration.startTimer({ action });
+
   const origEnd = res.end.bind(res);
   res.end = function (...args) {
     const ms = Date.now() - req.startTime;
-    log('info', 'res', { reqId, status: res.statusCode, ms });
+    const isErrorStatus = res.statusCode >= 400;
+    requestsTotal.labels(action, isErrorStatus ? 'error' : 'success').inc();
+    done();
+
+    if (req.path !== '/health') {
+      log('info', 'res', { reqId, status: res.statusCode, ms });
+    }
+
     return origEnd(...args);
   };
+
   next();
 });
 
@@ -243,9 +264,12 @@ class TabLock {
       entry.timer = setTimeout(() => {
         const idx = this.queue.indexOf(entry);
         if (idx !== -1) this.queue.splice(idx, 1);
+        tabLockTimeoutsTotal.inc();
+        refreshTabLockQueueDepth();
         reject(new Error('Tab lock queue timeout'));
       }, timeoutMs);
       this.queue.push(entry);
+      refreshTabLockQueueDepth();
       this._tryNext();
     });
   }
@@ -253,6 +277,7 @@ class TabLock {
   release() {
     this.active = false;
     this._tryNext();
+    refreshTabLockQueueDepth();
   }
 
   _tryNext() {
@@ -260,6 +285,7 @@ class TabLock {
     this.active = true;
     const entry = this.queue.shift();
     clearTimeout(entry.timer);
+    refreshTabLockQueueDepth();
     entry.resolve();
   }
 
@@ -270,6 +296,7 @@ class TabLock {
       entry.reject(new Error('Tab destroyed'));
     }
     this.queue = [];
+    refreshTabLockQueueDepth();
   }
 }
 
@@ -463,6 +490,7 @@ async function launchBrowserInstance() {
     proxy: proxy,
     geoip: !!proxy,
   });
+  options.proxy = normalizePlaywrightProxy(options.proxy);
   
   browser = await firefox.launch(options);
   log('info', 'camoufox launched');
@@ -612,6 +640,7 @@ function destroyTab(session, tabId) {
   if (lock) {
     lock.drain();
     tabLocks.delete(tabId);
+    refreshTabLockQueueDepth();
   }
   for (const [listItemId, group] of session.tabGroups) {
     if (group.has(tabId)) {
@@ -620,6 +649,7 @@ function destroyTab(session, tabId) {
       safePageClose(tabState.page);
       group.delete(tabId);
       if (group.size === 0) session.tabGroups.delete(listItemId);
+      refreshActiveTabsGauge();
       return true;
     }
   }
@@ -657,6 +687,27 @@ function createTabState(page) {
   };
 }
 
+function refreshActiveTabsGauge() {
+  activeTabsGauge.set(getTotalTabCount());
+}
+
+function refreshTabLockQueueDepth() {
+  let queued = 0;
+  for (const lock of tabLocks.values()) {
+    if (lock?.queue) queued += lock.queue.length;
+  }
+  tabLockQueueDepth.set(queued);
+}
+
+async function withPageLoadDuration(action, fn) {
+  const end = pageLoadDuration.startTimer();
+  try {
+    return await fn();
+  } finally {
+    end();
+  }
+}
+
 
 
 async function waitForPageReady(page, options = {}) {
@@ -1205,6 +1256,11 @@ app.get('/health', (req, res) => {
   });
 });
 
+app.get('/metrics', async (_req, res) => {
+  res.set('Content-Type', metricsRegister.contentType);
+  res.send(await metricsRegister.metrics());
+});
+
 // Create new tab
 app.post('/tabs', async (req, res) => {
   try {
@@ -1235,11 +1291,12 @@ app.post('/tabs', async (req, res) => {
       const tabState = createTabState(page);
       attachDownloadListener(tabState, tabId);
       group.set(tabId, tabState);
+      refreshActiveTabsGauge();
       
       if (url) {
         const urlErr = validateUrl(url);
         if (urlErr) throw Object.assign(new Error(urlErr), { statusCode: 400 });
-        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        await withPageLoadDuration('open_url', () => page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }));
         tabState.visitedUrls.add(url);
       }
       
@@ -1303,6 +1360,7 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
           attachDownloadListener(tabState, tabId, log);
           const group = getTabGroup(session, resolvedSessionKey);
           group.set(tabId, tabState);
+          refreshActiveTabsGauge();
           log('info', 'tab auto-created on navigate', { reqId: req.reqId, tabId, userId });
         }
       } else {
@@ -1311,7 +1369,7 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
       tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
       
       let targetUrl = url;
-      if (macro) {
+      if (macro && macro !== '__NO__' && macro !== 'none' && macro !== 'null') {
         targetUrl = expandMacro(macro, query) || url;
       }
       
@@ -1321,7 +1379,7 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
       if (urlErr) throw new Error(urlErr);
       
       return await withTabLock(tabId, async () => {
-        await tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        await withPageLoadDuration('navigate', () => tabState.page.goto(targetUrl, { waitUntil: 'domcontentloaded', timeout: 30000 }));
         tabState.visitedUrls.add(targetUrl);
         tabState.lastSnapshot = null;
         
@@ -1342,8 +1400,8 @@ app.post('/tabs/:tabId/navigate', async (req, res) => {
     res.json(result);
   } catch (err) {
     log('error', 'navigate failed', { reqId: req.reqId, tabId, error: err.message });
-    const status = err.message && err.message.startsWith('Blocked URL scheme') ? 400 : 500;
-    if (status === 400) {
+    const is400 = err.message && (err.message.startsWith('Blocked URL scheme') || err.message === 'url or macro required');
+    if (is400) {
       return res.status(400).json({ error: safeError(err) });
     }
     handleRouteError(err, req, res);
@@ -1778,7 +1836,17 @@ app.post('/tabs/:tabId/back', async (req, res) => {
     tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
     const result = await withTabLock(tabId, async () => {
-      await tabState.page.goBack({ timeout: 10000 });
+      try {
+        await tabState.page.goBack({ timeout: 10000 });
+      } catch (navErr) {
+        // NS_BINDING_CANCELLED_OLD_LOAD: Firefox cancels the old load when going back.
+        // The navigation itself succeeded — just the prior page's load was interrupted.
+        if (navErr.message && navErr.message.includes('NS_BINDING_CANCELLED')) {
+          log('info', 'goBack cancelled old load (expected)', { reqId: req.reqId, tabId });
+        } else {
+          throw navErr;
+        }
+      }
       tabState.refs = await buildRefs(tabState.page);
       return { ok: true, url: tabState.page.url() };
     });
@@ -2014,10 +2082,11 @@ app.delete('/tabs/:tabId', async (req, res) => {
       await clearTabDownloads(found.tabState);
       await safePageClose(found.tabState.page);
       found.group.delete(req.params.tabId);
-      { const _l = tabLocks.get(req.params.tabId); if (_l) _l.drain(); tabLocks.delete(req.params.tabId); }
+      { const _l = tabLocks.get(req.params.tabId); if (_l) _l.drain(); tabLocks.delete(req.params.tabId); refreshTabLockQueueDepth(); }
       if (found.group.size === 0) {
         session.tabGroups.delete(found.listItemId);
       }
+      refreshActiveTabsGauge();
       log('info', 'tab closed', { reqId: req.reqId, tabId: req.params.tabId, userId });
     }
     res.json({ ok: true });
@@ -2037,9 +2106,15 @@ app.delete('/tabs/group/:listItemId', async (req, res) => {
       for (const [tabId, tabState] of group) {
         await clearTabDownloads(tabState);
         await safePageClose(tabState.page);
-        tabLocks.delete(tabId);
+        const lock = tabLocks.get(tabId);
+        if (lock) {
+          lock.drain();
+          tabLocks.delete(tabId);
+        }
       }
       session.tabGroups.delete(req.params.listItemId);
+      refreshTabLockQueueDepth();
+      refreshActiveTabsGauge();
       log('info', 'tab group closed', { reqId: req.reqId, listItemId: req.params.listItemId, userId });
     }
     res.json({ ok: true });
@@ -2058,6 +2133,18 @@ app.delete('/sessions/:userId', async (req, res) => {
       await clearSessionDownloads(session);
       await session.context.close();
       sessions.delete(userId);
+      // Remove any lingering tab locks for the session
+      for (const [listItemId, group] of session.tabGroups) {
+        for (const tabId of group.keys()) {
+          const lock = tabLocks.get(tabId);
+          if (lock) {
+            lock.drain();
+            tabLocks.delete(tabId);
+          }
+        }
+      }
+      refreshTabLockQueueDepth();
+      refreshActiveTabsGauge();
       log('info', 'session closed', { userId });
     }
     if (sessions.size === 0) scheduleBrowserIdleShutdown();
@@ -2076,6 +2163,7 @@ setInterval(() => {
       clearSessionDownloads(session).catch(() => {});
       session.context.close().catch(() => {});
       sessions.delete(userId);
+      refreshActiveTabsGauge();
       log('info', 'session expired', { userId });
     }
   }
@@ -2083,6 +2171,7 @@ setInterval(() => {
   if (sessions.size === 0) {
     scheduleBrowserIdleShutdown();
   }
+  refreshTabLockQueueDepth();
 }, 60_000);
 
 // Per-tab inactivity reaper — close tabs idle for TAB_INACTIVITY_MS
@@ -2103,6 +2192,8 @@ setInterval(() => {
             safePageClose(tabState.page);
             group.delete(tabId);
             { const _l = tabLocks.get(tabId); if (_l) _l.drain(); tabLocks.delete(tabId); }
+            refreshTabLockQueueDepth();
+            refreshActiveTabsGauge();
           }
         } else {
           tabState._lastReaperCheck = now;
@@ -2198,8 +2289,9 @@ app.post('/tabs/open', async (req, res) => {
     const tabState = createTabState(page);
     attachDownloadListener(tabState, tabId, log);
     group.set(tabId, tabState);
+    refreshActiveTabsGauge();
     
-    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    await withPageLoadDuration('open_url', () => page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }));
     tabState.visitedUrls.add(url);
     
     log('info', 'openclaw tab opened', { reqId: req.reqId, tabId, url: page.url() });
@@ -2242,7 +2334,21 @@ app.post('/stop', async (req, res) => {
       cleanupTasks.push(clearSessionDownloads(session));
     }
     await Promise.all(cleanupTasks);
+    for (const session of sessions.values()) {
+      for (const [, group] of session.tabGroups) {
+        for (const tabId of group.keys()) {
+          const lock = tabLocks.get(tabId);
+          if (lock) {
+            lock.drain();
+            tabLocks.delete(tabId);
+          }
+        }
+      }
+    }
+    tabLocks.clear();
     sessions.clear();
+    refreshActiveTabsGauge();
+    refreshTabLockQueueDepth();
     res.json({ ok: true, stopped: true, profile: 'camoufox' });
   } catch (err) {
     res.status(500).json({ ok: false, error: safeError(err) });
@@ -2273,7 +2379,7 @@ app.post('/navigate', async (req, res) => {
     tabState.toolCalls++; tabState.consecutiveTimeouts = 0;
     
     const result = await withTabLock(targetId, async () => {
-      await tabState.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+      await withPageLoadDuration('navigate', () => tabState.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }));
       tabState.visitedUrls.add(url);
       tabState.lastSnapshot = null;
       
@@ -2641,6 +2747,7 @@ async function gracefulShutdown(signal) {
   forceTimeout.unref();
 
   server.close();
+  stopMemoryReporter();
 
   for (const [userId, session] of sessions) {
     await session.context.close().catch(() => {});
@@ -2654,12 +2761,16 @@ process.on('SIGINT', () => gracefulShutdown('SIGINT'));
 
 const PORT = CONFIG.port;
 const server = app.listen(PORT, async () => {
+  startMemoryReporter();
+  refreshActiveTabsGauge();
+  refreshTabLockQueueDepth();
   log('info', 'server started', { port: PORT, pid: process.pid, nodeVersion: process.version });
   // Pre-warm browser so first request doesn't eat a 6-7s cold start
   try {
     const start = Date.now();
     await ensureBrowser();
     log('info', 'browser pre-warmed', { ms: Date.now() - start });
+    scheduleBrowserIdleShutdown();
   } catch (err) {
     log('error', 'browser pre-warm failed (will retry on first request)', { error: err.message });
   }