@web-auto/camo 0.1.24 → 0.1.26

package/src/services/browser-service/internal/BrowserSession.js

@@ -37,6 +37,7 @@ export class BrowserSession {
     exitNotified = false;
     constructor(options) {
         this.options = options;
+        this.maxTabs = Math.max(5, Math.floor(Number(options.maxTabs ?? 5) || 5));
         const profileId = options.profileId || 'default';
         const root = resolveProfilesRoot();
         this.profileDir = path.join(root, profileId);
@@ -69,6 +70,7 @@ export class BrowserSession {
             recordLastKnownUrl: (url) => { if (url)
                 this.lastKnownUrl = url; },
             isHeadless: () => this.options.headless === true,
+            getMaxTabs: () => this.maxTabs,
         });
         this.navigation = new BrowserSessionNavigation({
             ensurePrimaryPage: () => this.pageManager.ensurePrimaryPage(),
@@ -147,7 +149,10 @@ export class BrowserSession {
         const existing = this.context.pages();
         this.page = existing.length ? existing[0] : await this.context.newPage();
         this.setupPageHooks(this.page);
-        this.context.on('page', (p) => this.setupPageHooks(p));
+        this.context.on('page', (p) => {
+            this.setupPageHooks(p);
+            this.enforceMaxTabs();
+        });
         if (this.viewportManager.isFollowingWindow()) {
             await this.viewportManager.refreshFromWindow(this.page).catch(() => { });
         }
@@ -158,6 +163,33 @@ export class BrowserSession {
     setupPageHooks(page) {
         this.pageHooks.setupPageHooks(page);
     }
+
+    async enforceMaxTabs() {
+        try {
+            const ctx = this.context;
+            if (!ctx) return;
+            const pages = ctx.pages().filter((p) => !p.isClosed());
+            if (pages.length <= this.maxTabs) return;
+            const activePage = this.getActivePage();
+            const excess = pages.length - this.maxTabs;
+            const closable = pages
+                .filter((p) => p !== activePage)
+                .sort((a, b) => {
+                    const aUrl = a.url() || '';
+                    const bUrl = b.url() || '';
+                    const aScore = (aUrl.includes('captcha') || aUrl === 'about:blank') ? 1 : 0;
+                    const bScore = (bUrl.includes('captcha') || bUrl === 'about:blank') ? 1 : 0;
+                    if (aScore !== bScore) return bScore - aScore;
+                    return 0;
+                });
+            const toClose = closable.slice(0, Math.min(excess, closable.length));
+            for (const page of toClose) {
+                try {
+                    await page.close({ runBeforeUnload: false });
+                } catch { /* ignore */ }
+            }
+        } catch { /* ignore enforcement errors */ }
+    }
     addRuntimeEventObserver(observer) {
         return this.runtimeEvents.addObserver(observer);
     }
@@ -301,4 +333,4 @@ export class BrowserSession {
         this.onExit?.(this.options.profileId);
     }
 }
-//# sourceMappingURL=BrowserSession.js.map
+//# sourceMappingURL=BrowserSession.js.map

package/src/services/browser-service/internal/browser-session/input-ops.js

@@ -1,4 +1,39 @@
 import { isTimeoutLikeError } from './utils.js';
+import { resolveInputMode } from './utils.js';
+
+async function createCDPSession(page) {
+    const context = page.context();
+    return context.newCDPSession(page);
+}
+
+async function cdpMouseClick(cdp, x, y, button = 'left', delay = 50) {
+    const normalizedButton = button === 'left' ? 'left' : button === 'right' ? 'right' : button === 'middle' ? 'middle' : 'left';
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mousePressed',
+        x: Math.round(x),
+        y: Math.round(y),
+        button: normalizedButton,
+        clickCount: 1
+    });
+    if (delay > 0) {
+        await new Promise(r => setTimeout(r, delay));
+    }
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mouseReleased',
+        x: Math.round(x),
+        y: Math.round(y),
+        button: normalizedButton,
+        clickCount: 1
+    });
+}
+
+async function cdpMouseMove(cdp, x, y) {
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mouseMoved',
+        x: Math.round(x),
+        y: Math.round(y)
+    });
+}
 
 async function readInteractiveViewport(page) {
     const fallback = page.viewportSize?.() || null;
@@ -39,9 +74,34 @@ export class BrowserSessionInputOps {
         this.withInputActionLock = withInputActionLock;
         const envMode = String(process.env.CAMO_SCROLL_INPUT_MODE || '').trim().toLowerCase();
         this.wheelMode = envMode === 'keyboard' ? 'keyboard' : 'wheel';
+        this.inputMode = resolveInputMode();
     }
     async mouseClick(opts) {
         const page = await this.ensurePrimaryPage();
+
+        if (this.inputMode === 'cdp') {
+            const { x, y, button = 'left', clicks = 1, delay = 50 } = opts;
+            let cdp = null;
+            try {
+                cdp = await createCDPSession(page);
+                for (let i = 0; i < clicks; i++) {
+                    if (i > 0) {
+                        await new Promise(r => setTimeout(r, 100 + Math.random() * 100));
+                    }
+                    await this.withInputActionLock(async () => {
+                        await this.runInputAction(page, 'mouse:click(cdp)', async () => {
+                            await cdpMouseClick(cdp, x, y, button, delay);
+                        });
+                    });
+                }
+            } finally {
+                if (cdp) {
+                    await cdp.detach().catch(() => {});
+                }
+            }
+            return;
+        }
+
         await this.withInputActionLock(async () => {
             await this.runInputAction(page, 'input:ready', (activePage) => this.ensureInputReady(activePage));
             const { x, y, button = 'left', clicks = 1, delay = 50, nudgeBefore = false } = opts;

package/src/services/browser-service/internal/browser-session/input-pipeline.js

@@ -1,4 +1,4 @@
-import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs, shouldSkipBringToFront } from './utils.js';
+import { resolveInputActionMaxAttempts, resolveInputActionTimeoutMs, resolveInputMode, resolveInputRecoveryBringToFrontTimeoutMs, resolveInputRecoveryDelayMs, resolveInputReadySettleMs, shouldSkipBringToFront } from './utils.js';
 import { ensurePageRuntime } from '../pageRuntime.js';
 export class BrowserInputPipeline {
     ensurePrimaryPage;
@@ -9,6 +9,8 @@ export class BrowserInputPipeline {
     }
     inputActionTail = Promise.resolve();
     async ensureInputReady(page) {
+        if (resolveInputMode() === 'cdp')
+            return;
         if (this.isHeadless())
             return;
         if (shouldSkipBringToFront()) {

package/src/services/browser-service/internal/browser-session/page-management.js

@@ -3,14 +3,95 @@ import { ensurePageRuntime } from '../pageRuntime.js';
 import { resolveNavigationWaitUntil, normalizeUrl, shouldSkipBringToFront } from './utils.js';
 export class BrowserSessionPageManagement {
     deps;
+    trackedPages = [];
+    trackedPageListeners = new WeakSet();
+    trackedPageState = new WeakMap();
+    static NEW_PAGE_FORCE_ALIVE_MS = 15_000;
+    static ACTIVE_PAGE_FORCE_ALIVE_MS = 5_000;
     constructor(deps) {
         this.deps = deps;
     }
+    safeIsClosed(page) {
+        if (!page)
+            return true;
+        try {
+            return page.isClosed();
+        }
+        catch {
+            return true;
+        }
+    }
+    markTrackedPage(page, forceAliveMs = 0) {
+        if (!page)
+            return null;
+        const prev = this.trackedPageState.get(page);
+        const next = {
+            closed: false,
+            forceAliveUntil: Math.max(Number(prev?.forceAliveUntil || 0), forceAliveMs > 0 ? Date.now() + forceAliveMs : 0),
+        };
+        this.trackedPageState.set(page, next);
+        return page;
+    }
+    isTrackedPageAlive(page) {
+        if (!page)
+            return false;
+        const state = this.trackedPageState.get(page);
+        if (state?.closed === true)
+            return false;
+        if (!this.safeIsClosed(page))
+            return true;
+        return Number(state?.forceAliveUntil || 0) > Date.now();
+    }
+    rememberPage(page, options = {}) {
+        if (!page)
+            return null;
+        this.markTrackedPage(page, Math.max(0, Number(options.forceAliveMs || 0) || 0));
+        if (this.safeIsClosed(page) && !this.isTrackedPageAlive(page))
+            return null;
+        if (!this.trackedPages.includes(page)) {
+            this.trackedPages.push(page);
+        }
+        if (typeof page.on === 'function' && !this.trackedPageListeners.has(page)) {
+            page.on('close', () => {
+                this.trackedPageState.set(page, {
+                    closed: true,
+                    forceAliveUntil: 0,
+                });
+                this.trackedPages = this.trackedPages.filter((item) => item !== page && !item.isClosed());
+            });
+            this.trackedPageListeners.add(page);
+        }
+        return page;
+    }
+    collectPages(ctx) {
+        const active = this.deps.getActivePage();
+        if (active) {
+            this.rememberPage(active, {
+                forceAliveMs: BrowserSessionPageManagement.ACTIVE_PAGE_FORCE_ALIVE_MS,
+            });
+        }
+        const merged = [...ctx.pages(), ...this.trackedPages, ...(active ? [active] : [])];
+        const seen = new Set();
+        const pages = [];
+        for (const page of merged) {
+            const tracked = this.trackedPages.includes(page) || page === active;
+            const alive = tracked ? this.isTrackedPageAlive(page) : !this.safeIsClosed(page);
+            if (!page || !alive || seen.has(page))
+                continue;
+            seen.add(page);
+            pages.push(page);
+            this.rememberPage(page);
+        }
+        this.trackedPages = this.trackedPages.filter((page) => page && this.isTrackedPageAlive(page));
+        return pages;
+    }
     async openPageViaContext(ctx, beforeCount) {
         try {
-            const page = await ctx.newPage();
+            const page = this.rememberPage(await ctx.newPage(), {
+                forceAliveMs: BrowserSessionPageManagement.NEW_PAGE_FORCE_ALIVE_MS,
+            });
             await page.waitForLoadState('domcontentloaded', { timeout: 1500 }).catch(() => null);
-            const after = ctx.pages().filter((p) => !p.isClosed()).length;
+            const after = this.collectPages(ctx).length;
             if (after > beforeCount) {
                 return page;
             }
@@ -24,8 +105,10 @@ export class BrowserSessionPageManagement {
         for (let attempt = 1; attempt <= 3; attempt += 1) {
             const waitPage = ctx.waitForEvent('page', { timeout: 1200 }).catch(() => null);
             await opener.keyboard.press(shortcut).catch(() => null);
-            const page = await waitPage;
-            const pagesNow = ctx.pages().filter((p) => !p.isClosed());
+            const page = this.rememberPage(await waitPage, {
+                forceAliveMs: BrowserSessionPageManagement.NEW_PAGE_FORCE_ALIVE_MS,
+            });
+            const pagesNow = this.collectPages(ctx);
             const after = pagesNow.length;
             if (page && after > beforeCount)
                 return page;
@@ -54,6 +137,7 @@ export class BrowserSessionPageManagement {
         const ctx = this.deps.ensureContext();
         const existing = this.deps.getActivePage();
         if (existing) {
+            this.rememberPage(existing);
             try {
                 await this.deps.ensurePageViewport(existing);
             }
@@ -62,7 +146,9 @@ export class BrowserSessionPageManagement {
             }
             return existing;
         }
-        const page = await ctx.newPage();
+        const page = this.rememberPage(await ctx.newPage(), {
+            forceAliveMs: BrowserSessionPageManagement.NEW_PAGE_FORCE_ALIVE_MS,
+        });
         this.deps.setActivePage(page);
         this.deps.setupPageHooks(page);
         try {
@@ -88,14 +174,7 @@ export class BrowserSessionPageManagement {
     }
     listPages() {
         const ctx = this.deps.ensureContext();
-        // Filter out closed pages AND pages that are effectively blank (about:newtab/about:blank)
-        const pages = ctx.pages().filter((p) => {
-            if (p.isClosed()) return false;
-            const url = p.url();
-            // Filter out blank placeholder pages
-            if (url === 'about:newtab' || url === 'about:blank') return false;
-            return true;
-        });
+        const pages = this.collectPages(ctx);
         const active = this.deps.getActivePage();
         return pages.map((p, index) => ({
             index,
@@ -103,9 +182,16 @@ export class BrowserSessionPageManagement {
             active: active === p,
         }));
     }
-    async newPage(url, options = {}) {
-        const ctx = this.deps.ensureContext();
-        const isMac = process.platform === 'darwin';
+  async newPage(url, options = {}) {
+    const ctx = this.deps.ensureContext();
+    const maxTabs = typeof this.deps.getMaxTabs === 'function' ? this.deps.getMaxTabs() : null;
+    if (Number.isFinite(maxTabs) && maxTabs >= 1) {
+      const pages = this.collectPages(ctx);
+      if (pages.length >= maxTabs) {
+        throw new Error(`max_tabs_exceeded:${maxTabs}`);
+      }
+    }
+    const isMac = process.platform === 'darwin';
         const shortcut = isMac ? 'Meta+t' : 'Control+t';
         let page = null;
         const opener = this.deps.getActivePage() || ctx.pages()[0];
@@ -114,21 +200,23 @@ export class BrowserSessionPageManagement {
         if (!shouldSkipBringToFront()) {
             await opener.bringToFront().catch(() => null);
         }
-        const before = ctx.pages().filter((p) => !p.isClosed()).length;
+        const before = this.collectPages(ctx).length;
         if (!options?.strictShortcut) {
             page = await this.openPageViaContext(ctx, before);
         }
         if (!page) {
             page = await this.openPageViaShortcut(ctx, opener, shortcut, before);
         }
-        let after = ctx.pages().filter((p) => !p.isClosed()).length;
+        let after = this.collectPages(ctx).length;
         if (!page || after <= before) {
             const waitPage = ctx.waitForEvent('page', { timeout: 1200 }).catch(() => null);
             const osShortcutOk = this.tryOsNewTabShortcut();
             if (osShortcutOk) {
-                page = await waitPage;
+                page = this.rememberPage(await waitPage, {
+                    forceAliveMs: BrowserSessionPageManagement.NEW_PAGE_FORCE_ALIVE_MS,
+                });
             }
-            const pagesNow = ctx.pages().filter((p) => !p.isClosed());
+            const pagesNow = this.collectPages(ctx);
             after = pagesNow.length;
             if (!page && after > before) {
                 page = pagesNow[pagesNow.length - 1] || null;
@@ -137,9 +225,9 @@ export class BrowserSessionPageManagement {
         if (!page || after <= before) {
             if (!options?.strictShortcut) {
                 page = await this.openPageViaContext(ctx, before);
-                after = ctx.pages().filter((p) => !p.isClosed()).length;
+                after = this.collectPages(ctx).length;
                 if (!page && after > before) {
-                    const pagesNow = ctx.pages().filter((p) => !p.isClosed());
+                    const pagesNow = this.collectPages(ctx);
                     page = pagesNow[pagesNow.length - 1] || null;
                 }
             }
@@ -148,6 +236,9 @@ export class BrowserSessionPageManagement {
             throw new Error('new_tab_failed');
         }
         this.deps.setupPageHooks(page);
+        this.rememberPage(page, {
+            forceAliveMs: BrowserSessionPageManagement.NEW_PAGE_FORCE_ALIVE_MS,
+        });
         this.deps.setActivePage(page);
         try {
             await this.deps.ensurePageViewport(page);
@@ -174,12 +265,12 @@ export class BrowserSessionPageManagement {
             await ensurePageRuntime(page);
             this.deps.recordLastKnownUrl(url);
         }
-        const pages = ctx.pages().filter((p) => !p.isClosed());
+        const pages = this.collectPages(ctx);
         return { index: Math.max(0, pages.indexOf(page)), url: page.url() };
     }
     async switchPage(index) {
         const ctx = this.deps.ensureContext();
-        const pages = ctx.pages().filter((p) => !p.isClosed());
+        const pages = this.collectPages(ctx);
         const idx = Number(index);
         if (!Number.isFinite(idx) || idx < 0 || idx >= pages.length) {
             throw new Error(`invalid_page_index: ${index}`);
@@ -206,7 +297,7 @@ export class BrowserSessionPageManagement {
     }
     async closePage(index) {
         const ctx = this.deps.ensureContext();
-        const pages = ctx.pages().filter((p) => !p.isClosed());
+        const pages = this.collectPages(ctx);
         if (pages.length === 0) {
             return { closedIndex: -1, activeIndex: -1, total: 0 };
         }
@@ -217,39 +308,10 @@ export class BrowserSessionPageManagement {
             throw new Error(`invalid_page_index: ${index}`);
         }
         const page = pages[closedIndex];
-        const beforeUrl = page.url();
-        
-        // Try to close the page
-        try {
-            await page.close({ runBeforeUnload: false });
-        } catch (e) {
-            // Ignore close errors
-        }
-        
-        // Wait for close to take effect
-        await new Promise(r => setTimeout(r, 100));
-        
-        // Check if actually closed
-        let remaining = ctx.pages().filter((p) => !p.isClosed());
-        
-        // If still same count, the page might not have closed properly
-        // Try navigating to about:blank first then close
-        if (remaining.length === pages.length) {
-            try {
-                await page.goto('about:blank', { timeout: 500 }).catch(() => {});
-                await page.close({ runBeforeUnload: false }).catch(() => {});
-                await new Promise(r => setTimeout(r, 100));
-                remaining = ctx.pages().filter((p) => !p.isClosed());
-            } catch (e) {
-                // Ignore
-            }
-        }
-        
-        // Final check - filter out pages that look like closed tabs (about:newtab)
-        remaining = remaining.filter(p => {
-            const url = p.url();
-            return url !== 'about:newtab' && url !== 'about:blank';
-        });
+        this.trackedPageState.set(page, { closed: true, forceAliveUntil: 0 });
+        await page.close().catch(() => { });
+        this.trackedPages = this.trackedPages.filter((item) => item !== page && !item.isClosed());
+        const remaining = this.collectPages(ctx);
         const nextIndex = remaining.length === 0 ? -1 : Math.min(Math.max(0, closedIndex - 1), remaining.length - 1);
         if (nextIndex >= 0) {
             const nextPage = remaining[nextIndex];

package/src/services/browser-service/internal/browser-session/page-management.test.js

@@ -103,3 +103,46 @@ test('newPage falls back to shortcut path in strictShortcut mode', async () => {
     assert.equal(result.index, 1);
     assert.equal(getActivePage(), created);
 });
+
+test('listPages keeps track of newly created pages even when context.pages stays stale', async () => {
+    const opener = createPage('opener');
+    const created = createPage('created');
+    const pages = [opener];
+    const { management, getActivePage } = createManagement({
+        pages,
+        activePage: opener,
+        ctxNewPage: async () => created,
+        waitForEvent: async () => null,
+    });
+    const result = await management.newPage();
+    assert.equal(result.index, 1);
+    assert.equal(result.url, 'https://example.com/created');
+    assert.equal(getActivePage(), created);
+    const listed = management.listPages();
+    assert.deepEqual(listed, [
+        { index: 0, url: 'https://example.com/opener', active: false },
+        { index: 1, url: 'https://example.com/created', active: true },
+    ]);
+});
+
+test('listPages keeps a just-created page visible briefly even if page reports closed immediately', async () => {
+    const opener = createPage('opener');
+    const created = createPage('created');
+    const pages = [opener];
+    const { management } = createManagement({
+        pages,
+        activePage: opener,
+        ctxNewPage: async () => {
+            created.closed = true;
+            return created;
+        },
+        waitForEvent: async () => null,
+    });
+    const result = await management.newPage();
+    assert.equal(result.index, 1);
+    const listed = management.listPages();
+    assert.deepEqual(listed, [
+        { index: 0, url: 'https://example.com/opener', active: false },
+        { index: 1, url: 'https://example.com/created', active: true },
+    ]);
+});

package/src/services/browser-service/internal/browser-session/utils.js

@@ -46,6 +46,12 @@ export function isTimeoutLikeError(error) {
     const message = String(error?.message || error || '').toLowerCase();
     return message.includes('timed out') || message.includes('timeout');
 }
+
+export function resolveInputMode() {
+    const raw = String(process.env.CAMO_INPUT_MODE ?? '').trim().toLowerCase();
+    return raw === 'cdp' ? 'cdp' : 'playwright';
+}
+
 export function normalizeUrl(raw) {
     try {
         const url = new URL(raw);

package/src/services/controller/controller.js

@@ -224,7 +224,7 @@ export class UiController {
     }
     const args = ['create', '--profile', payload.profile];
     if (payload.url) args.push('--url', payload.url);
-    if (payload.headless !== undefined) args.push('--headless', String(payload.headless));
+    if (payload.headless === false) args.push('--no-headless');
     if (payload.keepOpen !== undefined) args.push('--keep-open', String(payload.keepOpen));
     return this.runCliCommand('session-manager', args);
   }

package/src/services/controller/transport.js

@@ -21,11 +21,18 @@ export function createTransport({ env = process.env, defaults = {}, debugLog = n
       ? options.timeoutMs
       : 20000;
     const profileId = (args?.profileId || args?.profile || args?.sessionId || '').toString();
+    const senderMeta = {
+      source: String(options?.source || env.CAMO_COMMAND_SOURCE || 'controller').trim() || 'controller',
+      cwd: String(options?.cwd || env.CAMO_COMMAND_CWD || process.cwd()).trim() || process.cwd(),
+      pid: Number(options?.pid || env.CAMO_COMMAND_PID || process.pid) || process.pid,
+      ppid: Number(options?.ppid || env.CAMO_COMMAND_PPID || process.ppid) || process.ppid,
+      argv: Array.isArray(options?.argv) ? options.argv.map((item) => String(item)) : process.argv.slice(),
+    };
     debugLog?.('browserServiceCommand:start', { action, profileId, timeoutMs });
     const res = await fetch(`${getBrowserHttpBase()}/command`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ action, args }),
+      body: JSON.stringify({ action, args, meta: { sender: senderMeta } }),
       signal: AbortSignal.timeout ? AbortSignal.timeout(timeoutMs) : undefined,
     });
 

package/src/utils/args.mjs

@@ -10,6 +10,7 @@ export function ensureUrlScheme(rawUrl) {
   if (typeof rawUrl !== 'string') return rawUrl;
   const trimmed = rawUrl.trim();
   if (!trimmed) return trimmed;
+  if (/^(about|chrome|file|data|blob|javascript):/i.test(trimmed)) return trimmed;
   if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(trimmed)) return trimmed;
   return `https://${trimmed}`;
 }

package/src/utils/browser-service.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { BROWSER_SERVICE_URL, loadConfig, setRepoRoot } from './config.mjs';
 import { touchSessionActivity } from '../lifecycle/session-registry.mjs';
 import { buildResolvedSessionView, resolveSessionViewByProfile } from '../lifecycle/session-view.mjs';
+import { buildCommandSenderMeta } from './command-log.mjs';
 
 const require = createRequire(import.meta.url);
 const DEFAULT_API_TIMEOUT_MS = 90000;
@@ -117,12 +118,23 @@ function shouldTrackSessionActivity(action, payload) {
 
 export async function callAPI(action, payload = {}, options = {}) {
   const timeoutMs = resolveApiTimeoutMs(options);
+  const senderMeta = buildCommandSenderMeta({
+    source: String(options?.source || payload?.__commandSource || 'browser-service-client').trim() || 'browser-service-client',
+    cwd: String(options?.cwd || payload?.__commandCwd || process.cwd()).trim() || process.cwd(),
+    pid: Number(options?.pid || payload?.__commandPid || process.pid) || process.pid,
+    ppid: Number(options?.ppid || payload?.__commandPpid || process.ppid) || process.ppid,
+    argv: Array.isArray(options?.argv)
+      ? options.argv
+      : Array.isArray(payload?.__commandArgv)
+        ? payload.__commandArgv
+        : process.argv.slice(),
+  });
   let r;
   try {
     r = await fetch(`${BROWSER_SERVICE_URL}/command`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ action, args: payload }),
+      body: JSON.stringify({ action, args: payload, meta: { sender: senderMeta } }),
       signal: AbortSignal.timeout(timeoutMs),
     });
   } catch (error) {

package/src/utils/command-log.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_DIR, ensureDir } from './config.mjs';
+
+export const COMMAND_LOG_DIR = path.join(CONFIG_DIR, 'logs');
+export const COMMAND_LOG_FILE = path.join(COMMAND_LOG_DIR, 'command-log.jsonl');
+
+function safeSerialize(value) {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return { text: String(value) };
+  }
+}
+
+function normalizeMeta(meta = {}) {
+  const sender = meta?.sender && typeof meta.sender === 'object' ? meta.sender : {};
+  return {
+    source: String(meta?.source || '').trim() || 'unknown',
+    cwd: String(meta?.cwd || sender?.cwd || '').trim() || process.cwd(),
+    pid: Number(meta?.pid || sender?.pid || process.pid) || process.pid,
+    ppid: Number(meta?.ppid || sender?.ppid || process.ppid) || process.ppid,
+    argv: Array.isArray(meta?.argv) ? meta.argv.map((item) => String(item)) : undefined,
+    sender: {
+      source: String(sender?.source || meta?.source || '').trim() || 'unknown',
+      cwd: String(sender?.cwd || meta?.cwd || '').trim() || process.cwd(),
+      pid: Number(sender?.pid || meta?.pid || process.pid) || process.pid,
+      ppid: Number(sender?.ppid || meta?.ppid || process.ppid) || process.ppid,
+      argv: Array.isArray(sender?.argv) ? sender.argv.map((item) => String(item)) : undefined,
+    },
+  };
+}
+
+export function appendCommandLog(entry = {}) {
+  try {
+    ensureDir(COMMAND_LOG_DIR);
+    const meta = normalizeMeta(entry?.meta || {});
+    const line = {
+      ts: new Date().toISOString(),
+      action: String(entry?.action || '').trim() || null,
+      profileId: String(entry?.profileId || '').trim() || null,
+      command: String(entry?.command || '').trim() || null,
+      args: Array.isArray(entry?.args) ? entry.args.map((item) => String(item)) : undefined,
+      payload: safeSerialize(entry?.payload),
+      meta,
+    };
+    fs.appendFileSync(COMMAND_LOG_FILE, `${JSON.stringify(line)}\n`, 'utf8');
+    return line;
+  } catch {
+    return null;
+  }
+}
+
+export function buildCommandSenderMeta(overrides = {}) {
+  return {
+    source: String(overrides?.source || '').trim() || 'unknown',
+    cwd: String(overrides?.cwd || '').trim() || process.cwd(),
+    pid: Number(overrides?.pid || process.pid) || process.pid,
+    ppid: Number(overrides?.ppid || process.ppid) || process.ppid,
+    argv: Array.isArray(overrides?.argv) ? overrides.argv.map((item) => String(item)) : process.argv.slice(),
+  };
+}

package/src/utils/help.mjs

@@ -26,7 +26,7 @@ CONFIG:
 
 BROWSER CONTROL:
   init                                      Ensure camoufox + ensure browser-service daemon
-  start [profileId] [--url <url>] [--headless] [--devtools] [--record] [--record-name <name>] [--record-output <path>] [--record-overlay|--no-record-overlay] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h>]
+  start [profileId] [--url <url>] [--no-headless|--visible] [--devtools] [--record] [--record-name <name>] [--record-output <path>] [--record-overlay|--no-record-overlay] [--alias <name>] [--idle-timeout <duration>] [--width <w> --height <h> --max-tabs <n>]
   stop [profileId]
   stop --id <instanceId>                    Stop by instance id
   stop --alias <alias>                      Stop by alias
@@ -108,8 +108,8 @@ EXAMPLES:
   camo profile create myprofile
   camo profile default myprofile
   camo start --url https://example.com --alias main
-  camo start worker-1 --headless --alias shard1 --idle-timeout 45m
-  camo start worker-1 --devtools
+  camo start worker-1 --alias shard1 --idle-timeout 45m
+  camo start worker-1 --visible --devtools
   camo start worker-1 --record --record-name xhs-debug --record-output ./logs/xhs-debug.jsonl --record-overlay
   camo start myprofile --width 1920 --height 1020
   camo highlight-mode on