@askjo/camofox-browser 1.1.2 → 1.3.0

package/Dockerfile

@@ -31,8 +31,14 @@ RUN apt-get update && apt-get install -y \
     ca-certificates \
     curl \
     unzip \
+    # yt-dlp runtime dependency
+    python3-minimal \
     && rm -rf /var/lib/apt/lists/*
 
+# Install yt-dlp for YouTube transcript extraction (no browser needed)
+RUN curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp \
+    && chmod +x /usr/local/bin/yt-dlp
+
 # Pre-bake Camoufox browser binary into image
 # This avoids downloading at runtime and pins the version
 # Note: unzip returns exit code 1 for warnings (Unicode filenames), so we use || true and verify
@@ -57,4 +63,4 @@ ENV CAMOFOX_PORT=3000
 
 EXPOSE 3000
 
-CMD ["node", "server.js"]
+CMD ["sh", "-c", "node --max-old-space-size=${MAX_OLD_SPACE_SIZE:-128} server.js"]

package/README.md

@@ -32,13 +32,25 @@ This project wraps that engine in a REST API built for agents: accessibility sna
 - **C++ Anti-Detection** - bypasses Google, Cloudflare, and most bot detection
 - **Element Refs** - stable `e1`, `e2`, `e3` identifiers for reliable interaction
 - **Token-Efficient** - accessibility snapshots are ~90% smaller than raw HTML
+- **Runs on Anything** - lazy browser launch + idle shutdown keeps memory at ~40MB when idle. Designed to share a box with the rest of your stack — Raspberry Pi, $5 VPS, shared Railway infra.
 - **Session Isolation** - separate cookies/storage per user
 - **Cookie Import** - inject Netscape-format cookie files for authenticated browsing
 - **Proxy + GeoIP** - route traffic through residential proxies with automatic locale/timezone
 - **Structured Logging** - JSON log lines with request IDs for production observability
+- **YouTube Transcripts** - extract captions from any YouTube video via yt-dlp, no API key needed
 - **Search Macros** - `@google_search`, `@youtube_search`, `@amazon_search`, `@reddit_subreddit`, and 10 more
+- **Snapshot Screenshots** - include a base64 PNG screenshot alongside the accessibility snapshot
+- **Large Page Handling** - automatic snapshot truncation with offset-based pagination
 - **Deploy Anywhere** - Docker, Fly.io, Railway
 
+## Optional Dependencies
+
+| Dependency | Purpose | Install |
+|-----------|---------|---------|
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | YouTube transcript extraction (fast path) | `pip install yt-dlp` or `brew install yt-dlp` |
+
+The Docker image includes yt-dlp. For local dev, install it for the `/youtube/transcript` endpoint. Without it, the endpoint falls back to a slower browser-based method.
+
 ## Quick Start
 
 ### OpenClaw Plugin
@@ -251,7 +263,7 @@ curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `GET` | `/tabs/:id/snapshot` | Accessibility snapshot with element refs |
+| `GET` | `/tabs/:id/snapshot` | Accessibility snapshot with element refs. Query params: `includeScreenshot=true` (add base64 PNG), `offset=N` (paginate large snapshots) |
 | `POST` | `/tabs/:id/click` | Click element by ref or CSS selector |
 | `POST` | `/tabs/:id/type` | Type text into element |
 | `POST` | `/tabs/:id/press` | Press a keyboard key |
@@ -264,6 +276,21 @@ curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
 | `POST` | `/tabs/:id/forward` | Go forward |
 | `POST` | `/tabs/:id/refresh` | Refresh page |
 
+### YouTube Transcript
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/youtube/transcript` | Extract captions from a YouTube video |
+
+```bash
+curl -X POST http://localhost:9377/youtube/transcript \
+  -H 'Content-Type: application/json' \
+  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "languages": ["en"]}'
+# → { "status": "ok", "transcript": "[00:18] ♪ We're no strangers to love ♪\n...", "video_title": "...", "total_words": 548 }
+```
+
+Uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) when available (fast, no browser needed). Falls back to a browser-based intercept method if yt-dlp is not installed — this is slower and less reliable due to YouTube ad pre-rolls.
+
 ### Server
 
 | Method | Endpoint | Description |
@@ -294,6 +321,13 @@ Reddit macros return JSON directly (no HTML parsing needed):
 | `CAMOFOX_API_KEY` | Enable cookie import endpoint (disabled if unset) | - |
 | `CAMOFOX_ADMIN_KEY` | Required for `POST /stop` | - |
 | `CAMOFOX_COOKIES_DIR` | Directory for cookie files | `~/.camofox/cookies` |
+| `MAX_SESSIONS` | Max concurrent browser sessions | `50` |
+| `MAX_TABS_PER_SESSION` | Max tabs per session | `10` |
+| `SESSION_TIMEOUT_MS` | Session inactivity timeout | `1800000` (30min) |
+| `BROWSER_IDLE_TIMEOUT_MS` | Kill browser when idle (0 = never) | `300000` (5min) |
+| `HANDLER_TIMEOUT_MS` | Max time for any handler | `30000` (30s) |
+| `MAX_CONCURRENT_PER_USER` | Concurrent request cap per user | `3` |
+| `MAX_OLD_SPACE_SIZE` | Node.js V8 heap limit (MB) | `128` |
 | `PROXY_HOST` | Proxy hostname or IP | - |
 | `PROXY_PORT` | Proxy port | - |
 | `PROXY_USERNAME` | Proxy auth username | - |
@@ -311,7 +345,7 @@ Browser Instance (Camoufox)
         └── Tab (amazon.com)
 ```
 
-Sessions auto-expire after 30 minutes of inactivity.
+Sessions auto-expire after 30 minutes of inactivity. The browser itself shuts down after 5 minutes with no active sessions, and relaunches on the next request.
 
 ## Testing
 

package/lib/config.js

@@ -15,6 +15,8 @@ function loadConfig() {
     adminKey: process.env.CAMOFOX_ADMIN_KEY || '',
     apiKey: process.env.CAMOFOX_API_KEY || '',
     cookiesDir: process.env.CAMOFOX_COOKIES_DIR || join(os.homedir(), '.camofox', 'cookies'),
+    handlerTimeoutMs: parseInt(process.env.HANDLER_TIMEOUT_MS) || 30000,
+    maxConcurrentPerUser: parseInt(process.env.MAX_CONCURRENT_PER_USER) || 3,
     proxy: {
       host: process.env.PROXY_HOST || '',
       port: process.env.PROXY_PORT || '',

package/lib/launcher.js

@@ -14,12 +14,14 @@ const startProcess = cp.spawn;
  * @param {string} opts.pluginDir - Directory containing server.js
  * @param {number} opts.port - Port number for the server
  * @param {object} opts.env - Environment variables to pass to the subprocess
+ * @param {string[]} [opts.nodeArgs] - Extra Node.js CLI flags (e.g. --max-old-space-size=128)
  * @param {{ info: (msg: string) => void, error: (msg: string) => void }} opts.log - Logger
  * @returns {import('child_process').ChildProcess}
  */
-function launchServer({ pluginDir, port, env, log }) {
+function launchServer({ pluginDir, port, env, nodeArgs, log }) {
   const serverPath = join(pluginDir, 'server.js');
-  const proc = startProcess('node', [serverPath], {
+  const args = [...(nodeArgs || []), serverPath];
+  const proc = startProcess('node', args, {
     cwd: pluginDir,
     env: {
       ...env,

package/lib/snapshot.js

@@ -0,0 +1,41 @@
+/**
+ * Snapshot windowing — truncate large accessibility snapshots while
+ * preserving pagination/navigation links at the tail.
+ */
+
+const MAX_SNAPSHOT_CHARS = 80000;  // ~20K tokens
+const SNAPSHOT_TAIL_CHARS = 5000;  // keep last ~5K for pagination/nav links
+
+/**
+ * Return a window of the snapshot YAML.
+ *  offset=0 (default): head chunk + tail (pagination/nav).
+ *  offset=N: chars N..N+budget from the full snapshot.
+ *  Always appends pagination tail so nav refs are available in every chunk.
+ */
+function windowSnapshot(yaml, offset = 0) {
+  if (!yaml) return { text: '', truncated: false, totalChars: 0, offset: 0 };
+  const total = yaml.length;
+  if (total <= MAX_SNAPSHOT_CHARS) return { text: yaml, truncated: false, totalChars: total, offset: 0 };
+
+  const contentBudget = MAX_SNAPSHOT_CHARS - SNAPSHOT_TAIL_CHARS - 200; // room for marker
+  const tail = yaml.slice(-SNAPSHOT_TAIL_CHARS);
+  const clampedOffset = Math.min(Math.max(0, offset), total - SNAPSHOT_TAIL_CHARS);
+  const chunk = yaml.slice(clampedOffset, clampedOffset + contentBudget);
+  const chunkEnd = clampedOffset + contentBudget;
+  const hasMore = chunkEnd < total - SNAPSHOT_TAIL_CHARS;
+
+  const marker = hasMore
+    ? `\n[... truncated at char ${chunkEnd} of ${total}. Call snapshot with offset=${chunkEnd} to see more. Pagination links below. ...]\n`
+    : '\n';
+
+  return {
+    text: chunk + marker + tail,
+    truncated: true,
+    totalChars: total,
+    offset: clampedOffset,
+    hasMore,
+    nextOffset: hasMore ? chunkEnd : null
+  };
+}
+
+module.exports = { windowSnapshot, MAX_SNAPSHOT_CHARS, SNAPSHOT_TAIL_CHARS };

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.0.11",
+  "version": "1.0.12",
   "configSchema": {
     "type": "object",
     "properties": {
@@ -19,6 +19,31 @@
         "type": "boolean",
         "description": "Auto-start the camofox-browser server with the Gateway",
         "default": true
+      },
+      "maxSessions": {
+        "type": "number",
+        "description": "Maximum concurrent browser sessions (server default: 50)",
+        "default": 5
+      },
+      "maxTabsPerSession": {
+        "type": "number",
+        "description": "Maximum tabs per session (server default: 10)",
+        "default": 3
+      },
+      "sessionTimeoutMs": {
+        "type": "number",
+        "description": "Session inactivity timeout in milliseconds (server default: 1800000)",
+        "default": 600000
+      },
+      "browserIdleTimeoutMs": {
+        "type": "number",
+        "description": "Kill browser after this many ms with no sessions (0 = never)",
+        "default": 300000
+      },
+      "maxOldSpaceSize": {
+        "type": "number",
+        "description": "Node.js V8 heap limit in MB",
+        "default": 128
       }
     },
     "additionalProperties": false
@@ -34,6 +59,26 @@
     },
     "autoStart": {
       "label": "Auto-start server with Gateway"
+    },
+    "maxSessions": {
+      "label": "Max Sessions",
+      "placeholder": "5"
+    },
+    "maxTabsPerSession": {
+      "label": "Max Tabs per Session",
+      "placeholder": "3"
+    },
+    "sessionTimeoutMs": {
+      "label": "Session Timeout (ms)",
+      "placeholder": "600000"
+    },
+    "browserIdleTimeoutMs": {
+      "label": "Browser Idle Timeout (ms)",
+      "placeholder": "300000"
+    },
+    "maxOldSpaceSize": {
+      "label": "Node Heap Limit (MB)",
+      "placeholder": "128"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camofox-browser",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "main": "server.js",
   "license": "MIT",
@@ -26,7 +26,9 @@
     "clawdbot",
     "moltbot",
     "playwright",
-    "firefox"
+    "firefox",
+    "youtube",
+    "transcript"
   ],
   "engines": {
     "node": ">=18"
@@ -63,6 +65,7 @@
     "puppeteer-extra-plugin-stealth": "^2.11.2"
   },
   "devDependencies": {
-    "jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "pngjs": "^7.0.0"
   }
 }

package/plugin.ts

@@ -29,10 +29,15 @@ interface PluginConfig {
   url?: string;
   autoStart?: boolean;
   port?: number;
+  maxSessions?: number;
+  maxTabsPerSession?: number;
+  sessionTimeoutMs?: number;
+  browserIdleTimeoutMs?: number;
+  maxOldSpaceSize?: number;
 }
 
 interface ToolResult {
-  content: Array<{ type: string; text: string }>;
+  content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
 }
 
 interface HealthCheckResult {
@@ -109,10 +114,16 @@ let serverProcess: ChildProcess | null = null;
 async function startServer(
   pluginDir: string,
   port: number,
-  log: PluginApi["log"]
+  log: PluginApi["log"],
+  pluginCfg?: PluginConfig
 ): Promise<ChildProcess> {
   const cfg = loadConfig();
-  const proc = launchServer({ pluginDir, port, env: cfg.serverEnv, log });
+  const env: Record<string, string> = { ...cfg.serverEnv };
+  if (pluginCfg?.maxSessions != null) env.MAX_SESSIONS = String(pluginCfg.maxSessions);
+  if (pluginCfg?.maxTabsPerSession != null) env.MAX_TABS_PER_SESSION = String(pluginCfg.maxTabsPerSession);
+  if (pluginCfg?.sessionTimeoutMs != null) env.SESSION_TIMEOUT_MS = String(pluginCfg.sessionTimeoutMs);
+  if (pluginCfg?.browserIdleTimeoutMs != null) env.BROWSER_IDLE_TIMEOUT_MS = String(pluginCfg.browserIdleTimeoutMs);
+  const proc = launchServer({ pluginDir, port, env, log, nodeArgs: pluginCfg?.maxOldSpaceSize != null ? [`--max-old-space-size=${pluginCfg.maxOldSpaceSize}`] : undefined });
 
   proc.on("error", (err: Error) => {
     log?.error?.(`Server process error: ${err.message}`);
@@ -194,7 +205,7 @@ export default function register(api: PluginApi) {
         api.log?.info?.(`Camoufox server already running at ${baseUrl}`);
       } else {
         try {
-          serverProcess = await startServer(pluginDir, port, api.log);
+          serverProcess = await startServer(pluginDir, port, api.log, cfg);
         } catch (err) {
           api.log?.error?.(`Failed to auto-start server: ${(err as Error).message}`);
         }
@@ -227,19 +238,30 @@ export default function register(api: PluginApi) {
   api.registerTool((ctx: ToolContext) => ({
     name: "camofox_snapshot",
     description:
-      "Get accessibility snapshot of a Camoufox page with element refs (e1, e2, etc.) for interaction. Use with camofox_create_tab.",
+      "Get accessibility snapshot of a Camoufox page with element refs (e1, e2, etc.) for interaction, plus a visual screenshot. " +
+      "Large pages are truncated with pagination links preserved at the bottom. " +
+      "If the response includes hasMore=true and nextOffset, call again with that offset to see more content.",
     parameters: {
       type: "object",
       properties: {
         tabId: { type: "string", description: "Tab identifier" },
+        offset: { type: "number", description: "Character offset for paginated snapshots. Use nextOffset from a previous truncated response." },
       },
       required: ["tabId"],
     },
     async execute(_id, params) {
-      const { tabId } = params as { tabId: string };
+      const { tabId, offset } = params as { tabId: string; offset?: number };
       const userId = ctx.agentId || fallbackUserId;
-      const result = await fetchApi(baseUrl, `/tabs/${tabId}/snapshot?userId=${userId}`);
-      return toToolResult(result);
+      const qs = offset ? `&offset=${offset}` : '';
+      const result = await fetchApi(baseUrl, `/tabs/${tabId}/snapshot?userId=${userId}&includeScreenshot=true${qs}`) as Record<string, unknown>;
+      const content: ToolResult["content"] = [
+        { type: "text", text: JSON.stringify({ url: result.url, refsCount: result.refsCount, snapshot: result.snapshot, truncated: result.truncated, totalChars: result.totalChars, hasMore: result.hasMore, nextOffset: result.nextOffset }, null, 2) },
+      ];
+      const screenshot = result.screenshot as { data?: string; mimeType?: string } | undefined;
+      if (screenshot?.data) {
+        content.push({ type: "image", data: screenshot.data, mimeType: screenshot.mimeType || "image/png" });
+      }
+      return { content };
     },
   }));
 
@@ -499,7 +521,7 @@ export default function register(api: PluginApi) {
             return;
           }
           try {
-            serverProcess = await startServer(pluginDir, port, api.log);
+            serverProcess = await startServer(pluginDir, port, api.log, cfg);
           } catch (err) {
             api.log?.error?.(`Failed to start server: ${(err as Error).message}`);
           }
@@ -622,7 +644,7 @@ export default function register(api: PluginApi) {
             }
             try {
               console.log(`Starting camofox server on port ${port}...`);
-              serverProcess = await startServer(pluginDir, port, api.log);
+              serverProcess = await startServer(pluginDir, port, api.log, cfg);
               console.log(`Camoufox server started at ${baseUrl}`);
             } catch (err) {
               console.error(`Failed to start server: ${(err as Error).message}`);

package/run.sh

@@ -32,6 +32,6 @@ fi
 
 echo "Starting camofox-browser on http://localhost:$CAMOFOX_PORT (with auto-reload)"
 echo "Logs: /tmp/camofox-browser.log"
-nodemon --watch server.js --exec "node server.js" 2>&1 | while IFS= read -r line; do
+nodemon --watch server.js --exec "node --max-old-space-size=128 server.js" 2>&1 | while IFS= read -r line; do
   echo "[$(date '+%Y-%m-%d %H:%M:%S')] $line"
 done | tee -a /tmp/camofox-browser.log