@askjo/camoufox-browser 1.0.0

package/fly.toml

@@ -0,0 +1,29 @@
+app = "jo-camoufox-browser"
+primary_region = "sjc"
+
+[build]
+  dockerfile = "Dockerfile.camoufox"
+
+# Internal-only service (Fly private network)
+[[services]]
+  internal_port = 3000
+  protocol = "tcp"
+  auto_stop_machines = false
+  auto_start_machines = true
+  min_machines_running = 1
+
+  [[services.ports]]
+    port = 3000
+
+  [[services.http_checks]]
+    interval = 30000
+    timeout = 5000
+    path = "/health"
+
+[[vm]]
+  memory = "4gb"
+  cpu_kind = "shared"
+  cpus = 2
+
+[env]
+  NODE_ENV = "production"

package/jest.config.js

@@ -0,0 +1,41 @@
+module.exports = {
+  testEnvironment: 'node',
+  testTimeout: 60000, // 60 seconds per test
+  
+  // Run tests sequentially to avoid resource conflicts
+  maxWorkers: 1,
+  
+  // Test file patterns
+  testMatch: [
+    '**/tests/**/*.test.js'
+  ],
+  
+  // Ignore patterns
+  testPathIgnorePatterns: [
+    '/node_modules/'
+  ],
+  
+  // Setup and teardown
+  globalSetup: undefined,
+  globalTeardown: undefined,
+  
+  // Verbose output
+  verbose: true,
+  
+  // Fail fast on first error (useful for CI)
+  bail: process.env.CI ? 1 : 0,
+  
+  // Coverage settings (optional)
+  collectCoverage: false,
+  coverageDirectory: 'coverage',
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '/tests/'
+  ],
+  
+  // Reporter settings
+  reporters: [
+    'default',
+    ...(process.env.CI ? [['jest-junit', { outputDirectory: 'test-results' }]] : [])
+  ]
+};

package/lib/macros.js

@@ -0,0 +1,30 @@
+const MACROS = {
+  '@google_search': (query) => `https://www.google.com/search?q=${encodeURIComponent(query || '')}`,
+  '@youtube_search': (query) => `https://www.youtube.com/results?search_query=${encodeURIComponent(query || '')}`,
+  '@amazon_search': (query) => `https://www.amazon.com/s?k=${encodeURIComponent(query || '')}`,
+  '@reddit_search': (query) => `https://www.reddit.com/search/?q=${encodeURIComponent(query || '')}`,
+  '@wikipedia_search': (query) => `https://en.wikipedia.org/wiki/Special:Search?search=${encodeURIComponent(query || '')}`,
+  '@twitter_search': (query) => `https://twitter.com/search?q=${encodeURIComponent(query || '')}`,
+  '@yelp_search': (query) => `https://www.yelp.com/search?find_desc=${encodeURIComponent(query || '')}`,
+  '@spotify_search': (query) => `https://open.spotify.com/search/${encodeURIComponent(query || '')}`,
+  '@netflix_search': (query) => `https://www.netflix.com/search?q=${encodeURIComponent(query || '')}`,
+  '@linkedin_search': (query) => `https://www.linkedin.com/search/results/all/?keywords=${encodeURIComponent(query || '')}`,
+  '@instagram_search': (query) => `https://www.instagram.com/explore/tags/${encodeURIComponent(query || '')}`,
+  '@tiktok_search': (query) => `https://www.tiktok.com/search?q=${encodeURIComponent(query || '')}`,
+  '@twitch_search': (query) => `https://www.twitch.tv/search?term=${encodeURIComponent(query || '')}`
+};
+
+function expandMacro(macro, query) {
+  const macroFn = MACROS[macro];
+  return macroFn ? macroFn(query) : null;
+}
+
+function getSupportedMacros() {
+  return Object.keys(MACROS);
+}
+
+module.exports = {
+  expandMacro,
+  getSupportedMacros,
+  MACROS
+};

package/openclaw.plugin.json

@@ -0,0 +1,31 @@
+{
+  "id": "camoufox-browser",
+  "name": "Camoufox Browser",
+  "description": "Anti-detection browser automation for AI agents using Camoufox (Firefox-based)",
+  "version": "1.0.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Camoufox browser server URL",
+        "default": "http://localhost:9377"
+      },
+      "autoStart": {
+        "type": "boolean",
+        "description": "Auto-start the camoufox-browser server with the Gateway",
+        "default": false
+      }
+    },
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "url": {
+      "label": "Server URL",
+      "placeholder": "http://localhost:9377"
+    },
+    "autoStart": {
+      "label": "Auto-start server"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@askjo/camoufox-browser",
+  "version": "1.0.0",
+  "description": "Headless browser automation server for AI agents - REST API with anti-detection, element refs, and session isolation",
+  "main": "server-camoufox.js",
+  "openclaw": {
+    "extensions": ["plugin.ts"]
+  },
+  "scripts": {
+    "start": "node server-camoufox.js",
+    "start:chrome": "node server.js",
+    "test": "jest --runInBand --forceExit",
+    "test:e2e": "jest --runInBand --forceExit tests/e2e",
+    "test:live": "RUN_LIVE_TESTS=1 jest --runInBand --forceExit tests/live",
+    "test:debug": "DEBUG_SERVER=1 jest --runInBand --forceExit",
+    "postinstall": "npx camoufox-js fetch || true"
+  },
+  "dependencies": {
+    "camoufox-js": "^0.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^4.18.2",
+    "playwright": "^1.50.0",
+    "playwright-core": "^1.58.0",
+    "playwright-extra": "^4.3.6",
+    "puppeteer-extra-plugin-stealth": "^2.11.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/plugin.ts

@@ -0,0 +1,312 @@
+/**
+ * Camoufox Browser - OpenClaw Plugin
+ *
+ * Provides browser automation tools using the Camoufox anti-detection browser.
+ * Run the server separately: npm start (or ./run-camoufox.sh -p PORT)
+ */
+
+import { spawn, ChildProcess } from "child_process";
+import { join } from "path";
+
+interface PluginConfig {
+  url?: string;
+  autoStart?: boolean;
+}
+
+interface PluginApi {
+  registerTool: (tool: {
+    name: string;
+    description: string;
+    parameters: object;
+    optional?: boolean;
+    handler: (params: Record<string, unknown>) => Promise<unknown>;
+  }) => void;
+  registerCommand: (cmd: {
+    name: string;
+    description: string;
+    handler: (args: string[]) => Promise<void>;
+  }) => void;
+  config: PluginConfig;
+  log: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+let serverProcess: ChildProcess | null = null;
+
+async function fetchApi(
+  baseUrl: string,
+  path: string,
+  options: RequestInit = {}
+): Promise<unknown> {
+  const url = `${baseUrl}${path}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`${res.status}: ${text}`);
+  }
+  return res.json();
+}
+
+export default function register(api: PluginApi) {
+  const baseUrl = api.config.url || "http://localhost:9377";
+
+  api.registerTool({
+    name: "camoufox_create_tab",
+    description:
+      "Create a new browser tab. Returns tabId for subsequent operations.",
+    parameters: {
+      type: "object",
+      properties: {
+        userId: { type: "string", description: "User identifier for session isolation" },
+        listItemId: { type: "string", description: "Conversation/task identifier for tab grouping" },
+        url: { type: "string", description: "Initial URL to navigate to" },
+      },
+      required: ["userId", "url"],
+    },
+    optional: true,
+    handler: async (params) => {
+      return fetchApi(baseUrl, "/tabs", {
+        method: "POST",
+        body: JSON.stringify(params),
+      });
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_snapshot",
+    description:
+      "Get accessibility snapshot of a page with element refs (e1, e2, etc.) for interaction.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        userId: { type: "string", description: "User identifier" },
+      },
+      required: ["tabId", "userId"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { tabId, userId } = params as { tabId: string; userId: string };
+      return fetchApi(baseUrl, `/tabs/${tabId}/snapshot?userId=${userId}`);
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_click",
+    description: "Click an element by ref (e.g., e1) or CSS selector.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        userId: { type: "string", description: "User identifier" },
+        ref: { type: "string", description: "Element ref from snapshot (e.g., e1)" },
+        selector: { type: "string", description: "CSS selector (alternative to ref)" },
+      },
+      required: ["tabId", "userId"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      return fetchApi(baseUrl, `/tabs/${tabId}/click`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      });
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_type",
+    description: "Type text into an element.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        userId: { type: "string", description: "User identifier" },
+        ref: { type: "string", description: "Element ref from snapshot (e.g., e2)" },
+        selector: { type: "string", description: "CSS selector (alternative to ref)" },
+        text: { type: "string", description: "Text to type" },
+        pressEnter: { type: "boolean", description: "Press Enter after typing" },
+      },
+      required: ["tabId", "userId", "text"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      return fetchApi(baseUrl, `/tabs/${tabId}/type`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      });
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_navigate",
+    description:
+      "Navigate to a URL or use a search macro (@google_search, @youtube_search, etc.).",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        userId: { type: "string", description: "User identifier" },
+        url: { type: "string", description: "URL to navigate to" },
+        macro: {
+          type: "string",
+          description: "Search macro (e.g., @google_search, @youtube_search)",
+          enum: [
+            "@google_search",
+            "@youtube_search",
+            "@amazon_search",
+            "@reddit_search",
+            "@wikipedia_search",
+            "@twitter_search",
+            "@yelp_search",
+            "@spotify_search",
+            "@netflix_search",
+            "@linkedin_search",
+            "@instagram_search",
+            "@tiktok_search",
+            "@twitch_search",
+          ],
+        },
+        query: { type: "string", description: "Search query (when using macro)" },
+      },
+      required: ["tabId", "userId"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      return fetchApi(baseUrl, `/tabs/${tabId}/navigate`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      });
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_scroll",
+    description: "Scroll the page.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        userId: { type: "string", description: "User identifier" },
+        direction: { type: "string", enum: ["up", "down", "left", "right"] },
+        amount: { type: "number", description: "Pixels to scroll" },
+      },
+      required: ["tabId", "userId", "direction"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      return fetchApi(baseUrl, `/tabs/${tabId}/scroll`, {
+        method: "POST",
+        body: JSON.stringify(body),
+      });
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_screenshot",
+    description: "Take a screenshot of the current page.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        userId: { type: "string", description: "User identifier" },
+      },
+      required: ["tabId", "userId"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { tabId, userId } = params as { tabId: string; userId: string };
+      return fetchApi(baseUrl, `/tabs/${tabId}/screenshot?userId=${userId}`);
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_close_tab",
+    description: "Close a browser tab.",
+    parameters: {
+      type: "object",
+      properties: {
+        tabId: { type: "string", description: "Tab identifier" },
+        userId: { type: "string", description: "User identifier" },
+      },
+      required: ["tabId", "userId"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { tabId, userId } = params as { tabId: string; userId: string };
+      return fetchApi(baseUrl, `/tabs/${tabId}?userId=${userId}`, {
+        method: "DELETE",
+      });
+    },
+  });
+
+  api.registerTool({
+    name: "camoufox_list_tabs",
+    description: "List all open tabs for a user.",
+    parameters: {
+      type: "object",
+      properties: {
+        userId: { type: "string", description: "User identifier" },
+      },
+      required: ["userId"],
+    },
+    optional: true,
+    handler: async (params) => {
+      const { userId } = params as { userId: string };
+      return fetchApi(baseUrl, `/tabs?userId=${userId}`);
+    },
+  });
+
+  api.registerCommand({
+    name: "camoufox",
+    description: "Camoufox browser server control (status, start, stop)",
+    handler: async (args) => {
+      const subcommand = args[0] || "status";
+      switch (subcommand) {
+        case "status":
+          try {
+            const health = await fetchApi(baseUrl, "/health");
+            api.log.info(`Camoufox server at ${baseUrl}: ${JSON.stringify(health)}`);
+          } catch (e) {
+            api.log.error(`Camoufox server at ${baseUrl}: not reachable`);
+          }
+          break;
+        case "start":
+          if (serverProcess) {
+            api.log.info("Camoufox server already running");
+            return;
+          }
+          const pluginDir = __dirname;
+          serverProcess = spawn("npm", ["start"], {
+            cwd: pluginDir,
+            stdio: "inherit",
+            detached: true,
+          });
+          api.log.info(`Started camoufox-browser server (pid: ${serverProcess.pid})`);
+          break;
+        case "stop":
+          if (serverProcess) {
+            serverProcess.kill();
+            serverProcess = null;
+            api.log.info("Stopped camoufox-browser server");
+          } else {
+            api.log.info("No managed server process running");
+          }
+          break;
+        default:
+          api.log.error(`Unknown subcommand: ${subcommand}. Use: status, start, stop`);
+      }
+    },
+  });
+}

package/run-camoufox.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Local development script for camoufox-browser
+# Usage: ./run-camoufox.sh [-p port]
+# Example: ./run-camoufox.sh -p 3001
+
+PORT=3000
+while getopts "p:" opt; do
+  case $opt in
+    p) PORT="$OPTARG" ;;
+    *) echo "Usage: $0 [-p port]"; exit 1 ;;
+  esac
+done
+export PORT
+
+# Install deps if needed
+if [ ! -d "node_modules" ]; then
+    echo "Installing dependencies..."
+    npm install
+fi
+
+# Check if camoufox browser is installed
+if ! npx camoufox-js --version &> /dev/null 2>&1; then
+    echo "Fetching Camoufox browser..."
+    npx camoufox-js fetch
+fi
+
+# Install nodemon globally if not available
+if ! command -v nodemon &> /dev/null; then
+    echo "Installing nodemon..."
+    npm install -g nodemon
+fi
+
+echo "Starting camoufox-browser on http://localhost:$PORT (with auto-reload)"
+echo "Logs: /tmp/camoufox-browser.log"
+nodemon --watch server-camoufox.js --exec "node server-camoufox.js" 2>&1 | while IFS= read -r line; do
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $line"
+done | tee -a /tmp/camoufox-browser.log