@jackwener/opencli 1.7.15 → 1.7.16

package/dist/src/cli.js

@@ -313,7 +313,7 @@ async function resolveStoredBrowserTarget(page, scope = DEFAULT_BROWSER_WORKSPAC
     return resolveBrowserTargetInSession(page, defaultPage, { scope, source: 'saved' });
 }
 /** Create a browser page for browser commands. Uses a dedicated browser workspace for session persistence. */
-async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE, contextId) {
+async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE, contextId, opts = {}) {
     const { BrowserBridge } = await import('./browser/index.js');
     const bridge = new BrowserBridge();
     // Idle timeout: how long the browser workspace lease stays alive between commands
@@ -325,6 +325,7 @@ async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE,
         workspace,
         ...(contextId && { contextId }),
         ...(idleTimeout && idleTimeout > 0 && { idleTimeout }),
+        windowMode: opts.windowMode ?? getBrowserWindowMode(undefined, 'foreground'),
     });
     const targetScope = getBrowserScope(workspace, contextId);
     const resolvedTargetPage = targetPage
@@ -338,6 +339,43 @@ async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE,
     }
     return page;
 }
+function getBrowserWindowMode(command, defaultMode) {
+    const optionRaw = getCommandOption(command, 'window');
+    if (optionRaw !== undefined && optionRaw !== '') {
+        if (optionRaw === 'foreground' || optionRaw === 'background')
+            return optionRaw;
+        throw new Error(`--window must be one of: foreground, background. Received: "${String(optionRaw)}"`);
+    }
+    const envRaw = process.env.OPENCLI_WINDOW;
+    if (envRaw !== undefined && envRaw !== '') {
+        if (envRaw === 'foreground' || envRaw === 'background')
+            return envRaw;
+        throw new Error(`OPENCLI_WINDOW must be one of: foreground, background. Received: "${envRaw}"`);
+    }
+    return defaultMode;
+}
+function parseBrowserBoolean(name, raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    throw new Error(`${name} must be one of: true, false. Received: "${String(raw)}"`);
+}
+function getBrowserKeepTab(command, defaultValue) {
+    return parseBrowserBoolean('--keep-tab', getCommandOption(command, 'keepTab'))
+        ?? parseBrowserBoolean('OPENCLI_KEEP_TAB', process.env.OPENCLI_KEEP_TAB)
+        ?? defaultValue;
+}
+function hasExplicitBrowserWindowOption(command) {
+    const raw = getCommandOption(command, 'window');
+    return raw !== undefined && raw !== '';
+}
+function hasExplicitBrowserKeepTabOption(command) {
+    const raw = getCommandOption(command, 'keepTab');
+    return raw !== undefined && raw !== '';
+}
 function addBrowserTabOption(command) {
     return command.option('--tab <targetId>', BROWSER_TAB_OPTION_DESCRIPTION);
 }
@@ -583,6 +621,8 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     const browser = program
         .command('browser')
         .option('--workspace <name>', 'Browser workspace to use (default: browser:default; bound tabs use bound:<name>)')
+        .option('--window <mode>', 'Browser window mode: foreground or background')
+        .option('--keep-tab <bool>', 'Keep the browser tab lease after the command finishes')
         .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
     const originalBrowserDescription = browser.description();
     /**
@@ -646,12 +686,20 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     /** Wrap browser actions with error handling and optional --json output */
     function browserAction(fn) {
         return async (...args) => {
+            let page = null;
+            let shouldReleasePage = false;
             try {
                 const command = args.at(-1) instanceof Command ? args.at(-1) : undefined;
                 const targetPage = getBrowserTargetId(command);
                 const workspace = getBrowserWorkspace(command);
                 const contextId = getBrowserContextId(command);
-                const page = await getBrowserPage(targetPage, workspace, contextId);
+                const windowMode = getBrowserWindowMode(command, 'foreground');
+                const keepTab = getBrowserKeepTab(command, true);
+                shouldReleasePage = !keepTab && !workspace.startsWith('bound:');
+                if (workspace.startsWith('bound:') && (hasExplicitBrowserWindowOption(command) || hasExplicitBrowserKeepTabOption(command))) {
+                    log.warn('--window/--keep-tab ignored for bound:* workspaces; bound tabs are user-owned.');
+                }
+                page = await getBrowserPage(targetPage, workspace, contextId, { windowMode });
                 await fn(page, ...args);
             }
             catch (err) {
@@ -699,6 +747,14 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                 }
                 process.exitCode = EXIT_CODES.GENERIC_ERROR;
             }
+            finally {
+                if (shouldReleasePage && page?.closeWindow) {
+                    await page.closeWindow().catch((err) => {
+                        if (process.env.OPENCLI_VERBOSE)
+                            log.warn(`[browser] Failed to release tab lease: ${getErrorMessage(err)}`);
+                    });
+                }
+            }
         };
     }
     browser.command('bind')
@@ -2611,6 +2667,8 @@ cli({
     });
     // ── Plugin management ──────────────────────────────────────────────────────
     const pluginCmd = program.command('plugin').description('Manage opencli plugins');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalPluginDescription = pluginCmd.description();
     pluginCmd
         .command('install')
         .description('Install a plugin from a git repository')
@@ -2797,6 +2855,8 @@ cli({
     });
     // ── Built-in: adapter management ─────────────────────────────────────────
     const adapterCmd = program.command('adapter').description('Manage CLI adapters');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalAdapterDescription = adapterCmd.description();
     adapterCmd
         .command('status')
         .description('Show which sites have local overrides vs using official baseline')
@@ -2905,6 +2965,8 @@ cli({
     });
     // ── Built-in: browser profile selection ──────────────────────────────────
     const profileCmd = program.command('profile').description('Manage Browser Bridge Chrome profiles');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalProfileDescription = profileCmd.description();
     profileCmd
         .command('list')
         .description('List Chrome profiles connected through the Browser Bridge extension')
@@ -2982,6 +3044,8 @@ cli({
     });
     // ── Built-in: daemon ──────────────────────────────────────────────────────
     const daemonCmd = program.command('daemon').description('Manage the opencli daemon');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalDaemonDescription = daemonCmd.description();
     daemonCmd
         .command('status')
         .description('Show daemon status')
@@ -3107,6 +3171,10 @@ cli({
     const adapterGroups = { external: externalNames, apps, sites };
     const adapterNameSet = new Set([...externalNames, ...siteNames]);
     installCommanderNamespaceStructuredHelp(browser, { globalCommand: program, description: originalBrowserDescription });
+    installCommanderNamespaceStructuredHelp(daemonCmd, { globalCommand: program, description: originalDaemonDescription });
+    installCommanderNamespaceStructuredHelp(pluginCmd, { globalCommand: program, description: originalPluginDescription });
+    installCommanderNamespaceStructuredHelp(adapterCmd, { globalCommand: program, description: originalAdapterDescription });
+    installCommanderNamespaceStructuredHelp(profileCmd, { globalCommand: program, description: originalProfileDescription });
     program.configureHelp({
         visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
     });

package/dist/src/cli.test.js

@@ -349,13 +349,23 @@ describe('createProgram root help descriptions', () => {
             expect(data.command).toBe('opencli browser');
             expect(data.description).toBe('Browser control — navigate, click, type, extract, wait (no LLM needed)');
             expect(data.command_count).toBeGreaterThan(20);
-            expect(data.namespace_options).toMatchObject([
-                {
+            expect(data.namespace_options).toEqual(expect.arrayContaining([
+                expect.objectContaining({
                     name: 'workspace',
                     flags: '--workspace <name>',
                     takes_value: 'required',
-                },
-            ]);
+                }),
+                expect.objectContaining({
+                    name: 'window',
+                    flags: '--window <mode>',
+                    takes_value: 'required',
+                }),
+                expect.objectContaining({
+                    name: 'keepTab',
+                    flags: '--keep-tab <bool>',
+                    takes_value: 'required',
+                }),
+            ]));
             expect(data.global_options).toEqual(expect.arrayContaining([
                 expect.objectContaining({
                     name: 'version',
@@ -421,7 +431,7 @@ describe('createProgram root help descriptions', () => {
                 usage: 'opencli browser tab close [targetId] [options]',
                 positionals: [{ name: 'targetId', help: 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"' }],
             });
-            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace']);
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace', 'window', 'keepTab']);
             expect(data.structured_help).toMatchObject({
                 usage: 'opencli browser tab --help -f yaml',
             });
@@ -450,13 +460,113 @@ describe('createProgram root help descriptions', () => {
                 },
             });
             expect(data.command_options.map((option) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
-            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace']);
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['workspace', 'window', 'keepTab']);
             expect(data.global_options.map((option) => option.name)).toContain('profile');
         }
         finally {
             process.argv = argv;
         }
     });
+    it('renders daemon namespace structured help with leaves and global options', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const daemon = program.commands.find(cmd => cmd.name() === 'daemon');
+            expect(daemon).toBeTruthy();
+            process.argv = ['node', 'opencli', 'daemon', '--help', '-f', 'yaml'];
+            const data = yaml.load(daemon.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'daemon',
+                command: 'opencli daemon',
+                usage: 'opencli daemon <command> [args] [options]',
+                description: 'Manage the opencli daemon',
+                command_count: 3,
+                namespace_options: [],
+                structured_help: { usage: 'opencli daemon --help -f yaml' },
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['restart', 'status', 'stop']);
+            expect(data.global_options.map((option) => option.name)).toEqual(expect.arrayContaining(['version', 'profile']));
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders plugin namespace structured help with positional + option leaves', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const plugin = program.commands.find(cmd => cmd.name() === 'plugin');
+            expect(plugin).toBeTruthy();
+            process.argv = ['node', 'opencli', 'plugin', '--help', '-f', 'yaml'];
+            const data = yaml.load(plugin.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'plugin',
+                command: 'opencli plugin',
+                description: 'Manage opencli plugins',
+                namespace_options: [],
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['create', 'install', 'list', 'uninstall', 'update']);
+            const update = data.commands.find((cmd) => cmd.name === 'update');
+            expect(update).toMatchObject({
+                usage: 'opencli plugin update [name] [options]',
+                positionals: [{ name: 'name' }],
+            });
+            expect(update.command_options.map((option) => option.name)).toEqual(['all']);
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders adapter namespace structured help preserving original description after applyRootSubcommandSummaries', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const adapter = program.commands.find(cmd => cmd.name() === 'adapter');
+            expect(adapter).toBeTruthy();
+            process.argv = ['node', 'opencli', 'adapter', '--help', '-f', 'yaml'];
+            const data = yaml.load(adapter.helpInformation());
+            // applyRootSubcommandSummaries() rewrites .description() to a child-name listing;
+            // structured help must surface the original product description via the snapshot.
+            expect(data.description).toBe('Manage CLI adapters');
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['eject', 'reset', 'status']);
+            const reset = data.commands.find((cmd) => cmd.name === 'reset');
+            expect(reset).toMatchObject({
+                usage: 'opencli adapter reset [site] [options]',
+                positionals: [{ name: 'site' }],
+            });
+            expect(reset.command_options.map((option) => option.name)).toEqual(['all']);
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
+    it('renders profile namespace structured help including required positionals', () => {
+        const argv = process.argv;
+        try {
+            const program = createProgram('', '');
+            const profile = program.commands.find(cmd => cmd.name() === 'profile');
+            expect(profile).toBeTruthy();
+            process.argv = ['node', 'opencli', 'profile', '--help', '-f', 'yaml'];
+            const data = yaml.load(profile.helpInformation());
+            expect(data).toMatchObject({
+                namespace: 'profile',
+                description: 'Manage Browser Bridge Chrome profiles',
+                command_count: 3,
+            });
+            expect(data.commands.map((cmd) => cmd.name)).toEqual(['list', 'rename', 'use']);
+            const rename = data.commands.find((cmd) => cmd.name === 'rename');
+            expect(rename).toMatchObject({
+                usage: 'opencli profile rename <contextId> <alias> [options]',
+                positionals: [
+                    { name: 'contextId', required: true },
+                    { name: 'alias', required: true },
+                ],
+            });
+        }
+        finally {
+            process.argv = argv;
+        }
+    });
 });
 describe('resolveBrowserVerifyInvocation', () => {
     it('prefers the built entry declared in package metadata', () => {
@@ -727,6 +837,8 @@ describe('browser tab targeting commands', () => {
         stderrSpy.mockClear();
         mockBrowserConnect.mockClear();
         mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        delete process.env.OPENCLI_WINDOW;
+        delete process.env.OPENCLI_KEEP_TAB;
         mockBindTab.mockReset().mockResolvedValue({
             workspace: 'bound:default',
             page: 'tab-2',
@@ -759,6 +871,7 @@ describe('browser tab targeting commands', () => {
             screenshot: vi.fn().mockResolvedValue('base64-shot'),
             annotatedScreenshot: vi.fn().mockResolvedValue('annotated-base64-shot'),
             readNetworkCapture: vi.fn().mockResolvedValue([]),
+            closeWindow: vi.fn().mockResolvedValue(undefined),
             waitForDownload: vi.fn().mockResolvedValue({
                 downloaded: true,
                 filename: '/tmp/receipt.pdf',
@@ -801,8 +914,27 @@ describe('browser tab targeting commands', () => {
     it('runs browser commands against an explicit bound workspace', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'state']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default', windowMode: 'foreground' });
+        expect(browserState.page?.snapshot).toHaveBeenCalled();
+    });
+    it('passes browser --window through Commander options without relying on env pre-processing', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--window', 'background', 'state']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'browser:default', windowMode: 'background' });
+        expect(browserState.page?.snapshot).toHaveBeenCalled();
+    });
+    it('releases non-bound browser tab leases when --keep-tab=false', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--keep-tab', 'false', 'state']);
+        expect(browserState.page?.snapshot).toHaveBeenCalled();
+        expect(browserState.page?.closeWindow).toHaveBeenCalled();
+    });
+    it('does not auto-release explicit bound workspaces when --keep-tab=false', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', '--keep-tab', 'false', 'state']);
         expect(browserState.page?.snapshot).toHaveBeenCalled();
+        expect(browserState.page?.closeWindow).not.toHaveBeenCalled();
+        expect(stderrSpy.mock.calls.flat().join('')).toContain('--window/--keep-tab ignored for bound:* workspaces');
     });
     it('passes the opt-in AX source to browser state', async () => {
         const program = createProgram('', '');

package/dist/src/commanderAdapter.js

@@ -48,6 +48,11 @@ export function registerCommandToProgram(siteCmd, cmd) {
         .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
         .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
         .option('-v, --verbose', 'Debug output', false);
+    if (cmd.browser) {
+        subCmd
+            .option('--window <mode>', 'Browser window mode: foreground or background')
+            .option('--keep-tab <bool>', 'Keep the browser tab lease after the command finishes');
+    }
     const originalHelpInformation = subCmd.helpInformation.bind(subCmd);
     subCmd.helpInformation = ((contextOptions) => {
         const format = getRequestedHelpFormat();
@@ -102,6 +107,8 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 prepared: true,
                 ...(typeof globals.profile === 'string' && globals.profile.trim() ? { profile: globals.profile.trim() } : {}),
                 ...(typeof optionsRecord.trace === 'string' && optionsRecord.trace !== 'off' ? { trace: optionsRecord.trace } : {}),
+                ...(cmd.browser && typeof optionsRecord.window === 'string' ? { windowMode: optionsRecord.window } : {}),
+                ...(cmd.browser && typeof optionsRecord.keepTab === 'string' ? { keepTab: optionsRecord.keepTab } : {}),
             });
             if (result === null || result === undefined) {
                 return;

package/dist/src/doctor.js

@@ -271,8 +271,8 @@ export function renderBrowserDoctorReport(report) {
                         ? `tab ${session.preferredTabId}`
                         : `window ${session.windowId ?? 'unknown'}`;
                     const mode = session.ownership ?? (session.owned === false ? 'borrowed' : 'owned');
-                    const surface = session.surface ? `, surface=${session.surface}` : '';
-                    lines.push(styleText('dim', `  • ${session.workspace ?? 'default'} → ${target}, mode=${mode}${surface}, tabs=${session.tabCount ?? 0}, idle=${idle}`));
+                    const windowRole = session.windowRole ? `, window=${session.windowRole}` : '';
+                    lines.push(styleText('dim', `  • ${session.workspace ?? 'default'} → ${target}, mode=${mode}${windowRole}, tabs=${session.tabCount ?? 0}, idle=${idle}`));
                 }
             }
         }

package/dist/src/doctor.test.js

@@ -116,13 +116,13 @@ describe('doctor report rendering', () => {
                     windowId: 2,
                     preferredTabId: 42,
                     ownership: 'borrowed',
-                    surface: 'borrowed-user-tab',
+                    windowRole: 'borrowed-user',
                     tabCount: 1,
                     idleMsRemaining: null,
                 },
             ],
         }));
-        expect(text).toContain('bound:default → tab 42, mode=borrowed, surface=borrowed-user-tab, tabs=1, idle=none');
+        expect(text).toContain('bound:default → tab 42, mode=borrowed, window=borrowed-user, tabs=1, idle=none');
     });
     it('renders connected profiles and groups sessions by profile', () => {
         const text = strip(renderBrowserDoctorReport({
@@ -140,7 +140,7 @@ describe('doctor report rendering', () => {
                     windowId: 2,
                     preferredTabId: 42,
                     ownership: 'borrowed',
-                    surface: 'borrowed-user-tab',
+                    windowRole: 'borrowed-user',
                     tabCount: 1,
                     idleMsRemaining: null,
                 },
@@ -150,7 +150,7 @@ describe('doctor report rendering', () => {
                     windowId: 1,
                     preferredTabId: 10,
                     ownership: 'owned',
-                    surface: 'dedicated-container',
+                    windowRole: 'automation',
                     tabCount: 1,
                     idleMsRemaining: 1000,
                 },

package/dist/src/execution.d.ts

@@ -16,6 +16,8 @@ export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs,
     prepared?: boolean;
     profile?: string;
     trace?: string;
+    keepTab?: string;
+    windowMode?: string;
     onTraceExport?: (trace: ObservationExportResult) => void;
 }): Promise<unknown>;
 export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;

package/dist/src/execution.js

@@ -215,6 +215,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             const browserReuse = resolveBrowserSessionReuse(cmd);
             const workspace = resolveBrowserWorkspace(cmd, browserReuse);
             const idleTimeout = browserReuse === 'site' ? INTERACTIVE_BROWSER_IDLE_TIMEOUT_SECONDS : undefined;
+            const keepTab = resolveKeepTab(browserReuse, opts.keepTab);
+            const windowMode = resolveBrowserWindowMode('background', opts.windowMode);
             result = await browserSession(BrowserFactory, async (page) => {
                 const observation = traceMode === 'off'
                     ? null
@@ -281,9 +283,6 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         throw wrapped;
                     }
                 }
-                // --live / OPENCLI_LIVE=1 keeps the current automation tab lease after
-                // the command finishes, so agents (or humans) can inspect the page state.
-                const keepOpen = browserReuse !== 'none' || process.env.OPENCLI_LIVE === '1' || process.env.OPENCLI_LIVE === 'true';
                 try {
                     const browserTimeout = userTimeoutSec !== null
                         ? userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS
@@ -304,7 +303,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     // Adapter commands are one-shot — release the current tab lease immediately
                     // instead of waiting for the 30s idle timeout. The automation container
                     // window stays open for reuse.
-                    if (!keepOpen)
+                    if (!keepTab)
                         await page.closeWindow?.().catch(() => { });
                     return result;
                 }
@@ -329,11 +328,11 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     // Release the tab lease on failure too — without this, the lease lingers
                     // until the extension's idle timer fires (unreliable on Windows where
                     // MV3 service workers may be suspended before setTimeout triggers).
-                    if (!keepOpen)
+                    if (!keepTab)
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { workspace, cdpEndpoint, contextId, idleTimeout });
+            }, { workspace, cdpEndpoint, contextId, idleTimeout, windowMode });
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes
@@ -459,6 +458,32 @@ function resolveBrowserWorkspace(cmd, reuse) {
         return `site:${cmd.site}`;
     return `site:${cmd.site}:${crypto.randomUUID()}`;
 }
+function normalizeBooleanOption(name, raw) {
+    if (raw === undefined || raw === '')
+        return null;
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    throw new ArgumentError(`${name} must be one of: true, false. Received: "${String(raw)}"`);
+}
+function resolveKeepTab(reuse, rawOption) {
+    return normalizeBooleanOption('--keep-tab', rawOption)
+        ?? normalizeBooleanOption('OPENCLI_KEEP_TAB', process.env.OPENCLI_KEEP_TAB)
+        ?? reuse !== 'none';
+}
+function normalizeWindowMode(name, raw) {
+    if (raw === undefined || raw === '')
+        return null;
+    if (raw === 'foreground' || raw === 'background')
+        return raw;
+    throw new ArgumentError(`${name} must be one of: foreground, background. Received: "${String(raw)}"`);
+}
+function resolveBrowserWindowMode(defaultMode = 'background', rawOption) {
+    return normalizeWindowMode('--window', rawOption)
+        ?? normalizeWindowMode('OPENCLI_WINDOW', process.env.OPENCLI_WINDOW)
+        ?? defaultMode;
+}
 /**
  * Resolve the user-controllable `--timeout` arg, in seconds.
  *

package/dist/src/execution.test.js

@@ -157,8 +157,8 @@ describe('executeCommand — non-browser timeout', () => {
         await executeCommand(cmd, {});
         await executeCommand(cmd, {});
         expect(sessionOpts).toHaveLength(2);
-        expect(sessionOpts[0]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600 });
-        expect(sessionOpts[1]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600 });
+        expect(sessionOpts[0]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600, windowMode: 'background' });
+        expect(sessionOpts[1]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600, windowMode: 'background' });
         expect(closeWindow).not.toHaveBeenCalled();
         vi.restoreAllMocks();
     });
@@ -187,6 +187,8 @@ describe('executeCommand — non-browser timeout', () => {
         expect(sessionOpts[0]?.workspace).not.toBe(sessionOpts[1]?.workspace);
         expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
         expect(sessionOpts[1]?.idleTimeout).toBeUndefined();
+        expect(sessionOpts[0]?.windowMode).toBe('background');
+        expect(sessionOpts[1]?.windowMode).toBe('background');
         expect(closeWindow).toHaveBeenCalledTimes(2);
         vi.restoreAllMocks();
     });
@@ -372,18 +374,18 @@ describe('executeCommand — non-browser timeout', () => {
         expect(closeWindow).toHaveBeenCalledTimes(1);
         vi.restoreAllMocks();
     });
-    it('skips closeWindow when OPENCLI_LIVE=1 (success path)', async () => {
+    it('skips closeWindow when OPENCLI_KEEP_TAB=true (success path)', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
-        const prev = process.env.OPENCLI_LIVE;
-        process.env.OPENCLI_LIVE = '1';
+        const prev = process.env.OPENCLI_KEEP_TAB;
+        process.env.OPENCLI_KEEP_TAB = 'true';
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-live-success', access: 'read',
-                description: 'test closeWindow skipped with --live on success',
+                name: 'browser-keep-tab-success', access: 'read',
+                description: 'test closeWindow skipped with --keep-tab on success',
                 browser: true,
                 strategy: Strategy.PUBLIC,
                 func: async () => [{ ok: true }],
@@ -393,24 +395,24 @@ describe('executeCommand — non-browser timeout', () => {
         }
         finally {
             if (prev === undefined)
-                delete process.env.OPENCLI_LIVE;
+                delete process.env.OPENCLI_KEEP_TAB;
             else
-                process.env.OPENCLI_LIVE = prev;
+                process.env.OPENCLI_KEEP_TAB = prev;
             vi.restoreAllMocks();
         }
     });
-    it('skips closeWindow when OPENCLI_LIVE=1 (failure path)', async () => {
+    it('skips closeWindow when OPENCLI_KEEP_TAB=true (failure path)', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
-        const prev = process.env.OPENCLI_LIVE;
-        process.env.OPENCLI_LIVE = '1';
+        const prev = process.env.OPENCLI_KEEP_TAB;
+        process.env.OPENCLI_KEEP_TAB = 'true';
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-live-failure', access: 'read',
-                description: 'test closeWindow skipped with --live on failure',
+                name: 'browser-keep-tab-failure', access: 'read',
+                description: 'test closeWindow skipped with --keep-tab on failure',
                 browser: true,
                 strategy: Strategy.PUBLIC,
                 func: async () => { throw new Error('adapter failure'); },
@@ -420,12 +422,37 @@ describe('executeCommand — non-browser timeout', () => {
         }
         finally {
             if (prev === undefined)
-                delete process.env.OPENCLI_LIVE;
+                delete process.env.OPENCLI_KEEP_TAB;
             else
-                process.env.OPENCLI_LIVE = prev;
+                process.env.OPENCLI_KEEP_TAB = prev;
             vi.restoreAllMocks();
         }
     });
+    it('lets browser common options override adapter window and keep-tab defaults', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        const sessionOpts = [];
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+            sessionOpts.push(opts ?? {});
+            return fn(mockPage);
+        });
+        const cmd = cli({
+            site: 'test-execution',
+            name: 'browser-window-options', access: 'read',
+            description: 'test browser common options',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => [{ ok: true }],
+        });
+        await executeCommand(cmd, {}, false, {
+            windowMode: 'foreground',
+            keepTab: 'true',
+        });
+        expect(sessionOpts[0]).toMatchObject({ windowMode: 'foreground' });
+        expect(closeWindow).not.toHaveBeenCalled();
+        vi.restoreAllMocks();
+    });
     it('does not re-run custom validation when args are already prepared', async () => {
         const validateArgs = vi.fn();
         const cmd = {

package/dist/src/external-clis.yaml

@@ -54,3 +54,27 @@
   tags: [vercel, deployment, serverless, frontend, devops]
   install:
     default: "npm install -g vercel"
+
+- name: tg-cli
+  binary: tg
+  description: "Telegram CLI — local-first sync, search, export via MTProto for AI agents"
+  homepage: "https://github.com/jackwener/tg-cli"
+  tags: [telegram, messaging, search, export, ai-agent]
+  install:
+    default: "uv tool install kabi-tg-cli"
+
+- name: discord-cli
+  binary: discord
+  description: "Discord CLI — local-first sync, search, export via SQLite for AI agents"
+  homepage: "https://github.com/jackwener/discord-cli"
+  tags: [discord, messaging, search, export, ai-agent]
+  install:
+    default: "uv tool install kabi-discord-cli"
+
+- name: wx-cli
+  binary: wx
+  description: "WeChat local data CLI — sessions, messages, search, contacts, export for AI agents"
+  homepage: "https://github.com/jackwener/wx-cli"
+  tags: [wechat, messaging, search, export, ai-agent]
+  install:
+    default: "npm install -g @jackwener/wx-cli"

package/dist/src/help.d.ts

@@ -66,6 +66,7 @@ export declare function rootHelpData(program: Command, groups: RootAdapterGroups
 export declare function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown>;
 export declare function commandHelpData(cmd: CliCommand): Record<string, unknown>;
 export declare function formatCommonOptionsHelpText(): string;
+export declare function formatBrowserCommonOptionsHelpText(): string;
 export declare function formatSiteHelpText(site: string, commands: readonly CliCommand[]): string;
 export declare function formatCommandHelpText(cmd: CliCommand): string;
 export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;