@askjo/camoufox-browser 1.0.11 → 1.0.12

package/README.md

@@ -82,7 +82,7 @@ npm start                    # Default port 3000
 ```bash
 curl -X POST http://localhost:3000/tabs \
   -H "Content-Type: application/json" \
-  -d '{"userId": "user1", "listItemId": "conv1", "url": "https://example.com"}'
+  -d '{"userId": "user1", "sessionKey": "conv1", "url": "https://example.com"}'
 ```
 
 ### Get Page Snapshot (with element refs)
@@ -159,16 +159,16 @@ Navigate supports these macros for common sites:
 ```
 Browser Instance
 └── User Session (BrowserContext) - isolated cookies/storage
-    ├── Tab Group (listItemId: "conv1") - conversation A
+    ├── Tab Group (sessionKey: "conv1") - conversation A
     │   ├── Tab (google.com)
     │   └── Tab (github.com)
-    └── Tab Group (listItemId: "conv2") - conversation B
+    └── Tab Group (sessionKey: "conv2") - conversation B
         └── Tab (amazon.com)
 ```
 
 - One browser instance shared across users
 - Separate BrowserContext per user (isolated cookies/storage)
-- Tabs grouped by `listItemId` (conversation/task)
+- Tabs grouped by `sessionKey` (conversation/task)
 - 30-minute session timeout with automatic cleanup
 
 ## Running Locally

package/SKILL.md

@@ -55,7 +55,7 @@ Check health: `curl http://localhost:9377/health`
 ```bash
 curl -X POST http://localhost:9377/tabs \
   -H "Content-Type: application/json" \
-  -d '{"userId": "openclaw", "listItemId": "task1", "url": "https://example.com"}'
+  -d '{"userId": "openclaw", "sessionKey": "task1", "url": "https://example.com"}'
 ```
 
 Save the `tabId` from the response for subsequent requests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askjo/camoufox-browser",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation",
   "main": "server-camoufox.js",
   "license": "MIT",

package/plugin.ts

@@ -53,14 +53,25 @@ interface CliContext {
   };
 }
 
+interface ToolContext {
+  sessionKey?: string;
+  agentId?: string;
+  workspaceDir?: string;
+  sandboxed?: boolean;
+}
+
+type ToolDefinition = {
+  name: string;
+  description: string;
+  parameters: object;
+  execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
+};
+
+type ToolFactory = (ctx: ToolContext) => ToolDefinition | ToolDefinition[] | null | undefined;
+
 interface PluginApi {
   registerTool: (
-    tool: {
-      name: string;
-      description: string;
-      parameters: object;
-      execute: (id: string, params: Record<string, unknown>) => Promise<ToolResult>;
-    },
+    tool: ToolDefinition | ToolFactory,
     options?: { optional?: boolean }
   ) => void;
   registerCommand: (cmd: {
@@ -198,29 +209,29 @@ export default function register(api: PluginApi) {
     })();
   }
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_create_tab",
     description:
       "PREFERRED: Create a new browser tab using Camoufox anti-detection browser. Use camoufox tools instead of Chrome/built-in browser - they bypass bot detection on Google, Amazon, LinkedIn, etc. 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"],
+      required: ["url"],
     },
     async execute(_id, params) {
+      const sessionKey = ctx.sessionKey || "default";
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, "/tabs", {
         method: "POST",
-        body: JSON.stringify(params),
+        body: JSON.stringify({ ...params, userId, sessionKey }),
       });
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_snapshot",
     description:
       "Get accessibility snapshot of a Camoufox page with element refs (e1, e2, etc.) for interaction. Use with camoufox_create_tab.",
@@ -228,66 +239,66 @@ export default function register(api: PluginApi) {
       type: "object",
       properties: {
         tabId: { type: "string", description: "Tab identifier" },
-        userId: { type: "string", description: "User identifier" },
       },
-      required: ["tabId", "userId"],
+      required: ["tabId"],
     },
     async execute(_id, params) {
-      const { tabId, userId } = params as { tabId: string; userId: string };
+      const { tabId } = params as { tabId: string };
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/snapshot?userId=${userId}`);
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_click",
     description: "Click an element in a Camoufox tab 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"],
+      required: ["tabId"],
     },
     async execute(_id, params) {
-      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/click`, {
         method: "POST",
-        body: JSON.stringify(body),
+        body: JSON.stringify({ ...rest, userId }),
       });
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_type",
     description: "Type text into an element in a Camoufox tab.",
     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"],
+      required: ["tabId", "text"],
     },
     async execute(_id, params) {
-      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/type`, {
         method: "POST",
-        body: JSON.stringify(body),
+        body: JSON.stringify({ ...rest, userId }),
       });
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_navigate",
     description:
       "Navigate a Camoufox tab to a URL or use a search macro (@google_search, @youtube_search, etc.). Preferred over Chrome for sites with bot detection.",
@@ -295,7 +306,6 @@ export default function register(api: PluginApi) {
       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",
@@ -318,95 +328,94 @@ export default function register(api: PluginApi) {
         },
         query: { type: "string", description: "Search query (when using macro)" },
       },
-      required: ["tabId", "userId"],
+      required: ["tabId"],
     },
     async execute(_id, params) {
-      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/navigate`, {
         method: "POST",
-        body: JSON.stringify(body),
+        body: JSON.stringify({ ...rest, userId }),
       });
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_scroll",
     description: "Scroll a Camoufox 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"],
+      required: ["tabId", "direction"],
     },
     async execute(_id, params) {
-      const { tabId, ...body } = params as { tabId: string } & Record<string, unknown>;
+      const { tabId, ...rest } = params as { tabId: string } & Record<string, unknown>;
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/scroll`, {
         method: "POST",
-        body: JSON.stringify(body),
+        body: JSON.stringify({ ...rest, userId }),
       });
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_screenshot",
     description: "Take a screenshot of a Camoufox page.",
     parameters: {
       type: "object",
       properties: {
         tabId: { type: "string", description: "Tab identifier" },
-        userId: { type: "string", description: "User identifier" },
       },
-      required: ["tabId", "userId"],
+      required: ["tabId"],
     },
     async execute(_id, params) {
-      const { tabId, userId } = params as { tabId: string; userId: string };
+      const { tabId } = params as { tabId: string };
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs/${tabId}/screenshot?userId=${userId}`);
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_close_tab",
     description: "Close a Camoufox browser tab.",
     parameters: {
       type: "object",
       properties: {
         tabId: { type: "string", description: "Tab identifier" },
-        userId: { type: "string", description: "User identifier" },
       },
-      required: ["tabId", "userId"],
+      required: ["tabId"],
     },
     async execute(_id, params) {
-      const { tabId, userId } = params as { tabId: string; userId: string };
+      const { tabId } = params as { tabId: string };
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs/${tabId}?userId=${userId}`, {
         method: "DELETE",
       });
       return toToolResult(result);
     },
-  });
+  }));
 
-  api.registerTool({
+  api.registerTool((ctx: ToolContext) => ({
     name: "camoufox_list_tabs",
     description: "List all open Camoufox tabs for a user.",
     parameters: {
       type: "object",
-      properties: {
-        userId: { type: "string", description: "User identifier" },
-      },
-      required: ["userId"],
+      properties: {},
+      required: [],
     },
-    async execute(_id, params) {
-      const { userId } = params as { userId: string };
+    async execute(_id, _params) {
+      const userId = ctx.agentId || "openclaw";
       const result = await fetchApi(baseUrl, `/tabs?userId=${userId}`);
       return toToolResult(result);
     },
-  });
+  }));
 
   api.registerCommand({
     name: "camoufox",

package/server-camoufox.js

@@ -10,8 +10,9 @@ const app = express();
 app.use(express.json({ limit: '5mb' }));
 
 let browser = null;
-// userId -> { context, tabGroups: Map<listItemId, Map<tabId, TabState>>, lastAccess }
+// userId -> { context, tabGroups: Map<sessionKey, Map<tabId, TabState>>, lastAccess }
 // TabState = { page, refs: Map<refId, {role, name, nth}>, visitedUrls: Set, toolCalls: number }
+// Note: sessionKey was previously called listItemId - both are accepted for backward compatibility
 const sessions = new Map();
 
 const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 min
@@ -364,13 +365,15 @@ app.get('/health', async (req, res) => {
 // Create new tab
 app.post('/tabs', async (req, res) => {
   try {
-    const { userId, listItemId, url } = req.body;
-    if (!userId || !listItemId) {
-      return res.status(400).json({ error: 'userId and listItemId required' });
+    const { userId, sessionKey, listItemId, url } = 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 session = await getSession(userId);
-    const group = getTabGroup(session, listItemId);
+    const group = getTabGroup(session, resolvedSessionKey);
     
     const page = await session.context.newPage();
     const tabId = crypto.randomUUID();
@@ -382,7 +385,7 @@ app.post('/tabs', async (req, res) => {
       tabState.visitedUrls.add(url);
     }
     
-    console.log(`Tab ${tabId} created for user ${userId}, listItem ${listItemId}`);
+    console.log(`Tab ${tabId} created for user ${userId}, session ${resolvedSessionKey}`);
     res.json({ tabId, url: page.url() });
   } catch (err) {
     console.error('Create tab error:', err);
@@ -844,7 +847,8 @@ app.get('/tabs/:tabId/stats', async (req, res) => {
     const { tabState, listItemId } = found;
     res.json({
       tabId: req.params.tabId,
-      listItemId,
+      sessionKey: listItemId,
+      listItemId, // Legacy compatibility
       url: tabState.page.url(),
       visitedUrls: Array.from(tabState.visitedUrls),
       toolCalls: tabState.toolCalls,