@jackwener/opencli 1.7.14 → 1.7.16

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

@@ -1,6 +1,24 @@
 import { Command } from 'commander';
 import type { CliCommand } from './registry.js';
 export type StructuredHelpFormat = 'yaml' | 'json';
+export interface ArgSpec {
+    name: string;
+    required?: true;
+    variadic?: true;
+    help?: string;
+    default?: unknown;
+    choices?: string[];
+}
+export interface OptionSpec {
+    name: string;
+    flags: string;
+    help?: string;
+    takes_value?: 'required' | 'optional';
+    required?: true;
+    default?: unknown;
+    choices?: string[];
+    negate?: true;
+}
 export declare function getRequestedHelpFormat(argv?: readonly string[]): StructuredHelpFormat | undefined;
 export declare function renderStructuredHelp(data: unknown, format: StructuredHelpFormat): string;
 export declare function wrapCommaList(items: readonly string[], opts?: {
@@ -29,11 +47,26 @@ export interface RootAdapterGroups {
     sites: readonly string[];
 }
 export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+export declare function commanderNamespaceHelpData(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): Record<string, unknown>;
+export declare function commanderCommandHelpData(namespaceRoot: Command, command: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function commanderGroupHelpData(namespaceRoot: Command, groupCommand: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function installCommanderNamespaceStructuredHelp(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): void;
 export declare function formatCommandListTerm(cmd: CliCommand): string;
 export declare function rootHelpData(program: Command, groups: RootAdapterGroups): Record<string, unknown>;
 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;

package/dist/src/help.js

@@ -28,6 +28,20 @@ const COMMON_OPTIONS = [
         help: 'display help for command',
     },
 ];
+const BROWSER_COMMON_OPTIONS = [
+    {
+        flags: '--window <mode>',
+        name: 'window',
+        help: 'Browser window mode: foreground or background',
+        choices: ['foreground', 'background'],
+    },
+    {
+        flags: '--keep-tab <bool>',
+        name: 'keep-tab',
+        help: 'Keep the browser tab lease after the command finishes',
+        choices: ['true', 'false'],
+    },
+];
 function normalizeStructuredHelpFormat(value) {
     const normalized = value?.toLowerCase();
     if (normalized === 'yaml' || normalized === 'yml')
@@ -125,6 +139,151 @@ function compactCommonOption(option) {
         ...('choices' in option ? { choices: option.choices } : {}),
     };
 }
+function compactCommanderArgument(arg) {
+    return {
+        name: arg.name(),
+        ...(arg.required ? { required: true } : {}),
+        ...(arg.variadic ? { variadic: true } : {}),
+        ...(arg.description ? { help: arg.description } : {}),
+        ...(arg.defaultValue !== undefined ? { default: arg.defaultValue } : {}),
+        ...(arg.argChoices?.length ? { choices: [...arg.argChoices] } : {}),
+    };
+}
+function compactCommanderOption(option) {
+    if (option.hidden)
+        return null;
+    return {
+        name: option.attributeName(),
+        flags: option.flags,
+        ...(option.description ? { help: option.description } : {}),
+        ...(option.required ? { takes_value: 'required' } : {}),
+        ...(option.optional ? { takes_value: 'optional' } : {}),
+        ...(option.mandatory ? { required: true } : {}),
+        ...(option.defaultValue !== undefined ? { default: option.defaultValue } : {}),
+        ...(option.argChoices?.length ? { choices: [...option.argChoices] } : {}),
+        ...(option.negate ? { negate: true } : {}),
+    };
+}
+function compactCommanderOptions(options) {
+    return options
+        .map(compactCommanderOption)
+        .filter((option) => option !== null);
+}
+function commanderPath(command) {
+    const parts = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        if (name)
+            parts.push(name);
+        current = current.parent;
+    }
+    return parts.reverse();
+}
+function commandPathFromRoot(namespaceRoot, command) {
+    const rootPath = commanderPath(namespaceRoot);
+    const commandPath = commanderPath(command);
+    return commandPath.slice(rootPath.length);
+}
+function collectLeafCommands(command) {
+    if (command.commands.length === 0)
+        return [command];
+    return command.commands.flatMap(child => collectLeafCommands(child));
+}
+function collectDescendantCommands(command) {
+    return command.commands.flatMap(child => [child, ...collectDescendantCommands(child)]);
+}
+function formatCommanderPositionals(args) {
+    return args
+        .map(arg => {
+        const name = `${arg.name()}${arg.variadic ? '...' : ''}`;
+        return arg.required ? `<${name}>` : `[${name}]`;
+    })
+        .join(' ');
+}
+function formatCommanderUsage(command, opts = {}) {
+    const path = commanderPath(command).join(' ');
+    const positionalText = formatCommanderPositionals(command.registeredArguments);
+    const hasOptions = compactCommanderOptions(command.options).length > 0
+        || (opts.namespaceRoot ? compactCommanderOptions(opts.namespaceRoot.options).length > 0 : false)
+        || (opts.globalCommand ? compactCommanderOptions(opts.globalCommand.options).length > 0 : false);
+    const optionText = hasOptions ? ' [options]' : '';
+    return `${path}${positionalText ? ` ${positionalText}` : ''}${optionText}`;
+}
+function compactCommanderCommand(namespaceRoot, command, opts = {}) {
+    const relativePath = commandPathFromRoot(namespaceRoot, command);
+    return {
+        name: relativePath.join(' '),
+        command: commanderPath(command).join(' '),
+        usage: formatCommanderUsage(command, { namespaceRoot, globalCommand: opts.globalCommand }),
+        description: command.description(),
+        ...(command.aliases().length ? { aliases: command.aliases() } : {}),
+        positionals: command.registeredArguments.map(compactCommanderArgument),
+        command_options: compactCommanderOptions(command.options),
+    };
+}
+export function commanderNamespaceHelpData(namespaceRoot, opts = {}) {
+    const leaves = collectLeafCommands(namespaceRoot)
+        .filter(command => command !== namespaceRoot)
+        .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+    return {
+        namespace: namespaceRoot.name(),
+        command: commanderPath(namespaceRoot).join(' '),
+        usage: `${commanderPath(namespaceRoot).join(' ')} <command> [args] [options]`,
+        description: opts.description ?? namespaceRoot.description(),
+        command_count: leaves.length,
+        commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
+        namespace_options: compactCommanderOptions(namespaceRoot.options),
+        ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+        structured_help: {
+            formats: ['yaml', 'json'],
+            usage: `${commanderPath(namespaceRoot).join(' ')} --help -f yaml`,
+        },
+    };
+}
+export function commanderCommandHelpData(namespaceRoot, command, opts = {}) {
+    return {
+        namespace: namespaceRoot.name(),
+        ...compactCommanderCommand(namespaceRoot, command, opts),
+        namespace_options: compactCommanderOptions(namespaceRoot.options),
+        ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+        structured_help: {
+            formats: ['yaml', 'json'],
+            usage: `${commanderPath(command).join(' ')} --help -f yaml`,
+        },
+    };
+}
+export function commanderGroupHelpData(namespaceRoot, groupCommand, opts = {}) {
+    const leaves = collectLeafCommands(groupCommand)
+        .filter(command => command !== groupCommand)
+        .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+    return {
+        namespace: namespaceRoot.name(),
+        group: commandPathFromRoot(namespaceRoot, groupCommand).join(' '),
+        command: commanderPath(groupCommand).join(' '),
+        usage: `${commanderPath(groupCommand).join(' ')} <command> [args] [options]`,
+        description: groupCommand.description(),
+        command_count: leaves.length,
+        commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
+        namespace_options: compactCommanderOptions(namespaceRoot.options),
+        ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+        structured_help: {
+            formats: ['yaml', 'json'],
+            usage: `${commanderPath(groupCommand).join(' ')} --help -f yaml`,
+        },
+    };
+}
+export function installCommanderNamespaceStructuredHelp(namespaceRoot, opts = {}) {
+    installStructuredHelp(namespaceRoot, () => commanderNamespaceHelpData(namespaceRoot, opts));
+    for (const command of collectDescendantCommands(namespaceRoot)) {
+        if (command.commands.length > 0) {
+            installStructuredHelp(command, () => commanderGroupHelpData(namespaceRoot, command, opts));
+        }
+        else {
+            installStructuredHelp(command, () => commanderCommandHelpData(namespaceRoot, command, opts));
+        }
+    }
+}
 function positionals(cmd) {
     return cmd.args.filter(arg => arg.positional);
 }
@@ -162,6 +321,7 @@ function compactCommand(cmd) {
         ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
         positionals: positionals(cmd).map(compactArg),
         command_options: commandOptions(cmd).map(compactArg),
+        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         example: formatCommandExample(cmd),
         ...(cmd.browserSession ? { browserSession: cmd.browserSession } : {}),
         ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
@@ -208,6 +368,7 @@ export function siteHelpData(site, commands) {
         command_count: unique.length,
         commands: unique.map(cmd => compactCommand(cmd)),
         common_options: COMMON_OPTIONS.map(compactCommonOption),
+        ...(unique.some(cmd => cmd.browser) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         next: [
             `opencli ${site} <command> --help -f yaml`,
             `opencli ${site} <command> -f yaml`,
@@ -219,6 +380,7 @@ export function commandHelpData(cmd) {
         site: cmd.site,
         ...compactCommand(cmd),
         common_options: COMMON_OPTIONS.map(compactCommonOption),
+        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
     };
 }
@@ -249,6 +411,15 @@ export function formatCommonOptionsHelpText() {
     });
     return ['Common options:', ...formatRows(rows)].join('\n');
 }
+export function formatBrowserCommonOptionsHelpText() {
+    const rows = BROWSER_COMMON_OPTIONS.map(option => {
+        const details = [option.help];
+        if ('choices' in option)
+            details.push(`choices: ${option.choices.join(', ')}`);
+        return [option.flags, details.join('  ')];
+    });
+    return ['Browser common options:', ...formatRows(rows)].join('\n');
+}
 export function formatSiteHelpText(site, commands) {
     const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
         .sort((a, b) => a.name.localeCompare(b.name));
@@ -261,6 +432,7 @@ export function formatSiteHelpText(site, commands) {
         ...formatRows(unique.map(cmd => [formatCommandListTerm(cmd), formatSiteCommandDescription(cmd)])),
         '',
         formatCommonOptionsHelpText(),
+        ...(unique.some(cmd => cmd.browser) ? ['', formatBrowserCommonOptionsHelpText()] : []),
         '',
         `Agent tip: use 'opencli ${site} --help -f yaml' to get all command args/options in one structured response.`,
         '',
@@ -289,6 +461,8 @@ export function formatCommandHelpText(cmd) {
         lines.push('Command options:', ...formatRows(optionRows), '');
     }
     lines.push(formatCommonOptionsHelpText(), '');
+    if (cmd.browser)
+        lines.push(formatBrowserCommonOptionsHelpText(), '');
     const meta = [];
     meta.push(`Access: ${cmd.access}`);
     meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);

package/dist/src/main.js

@@ -27,21 +27,11 @@ const __dirname = path.dirname(__filename);
 // Use findPackageRoot so the path works both in dev (src/main.ts) and prod (dist/src/main.js).
 const BUILTIN_CLIS = path.join(findPackageRoot(__filename), 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
-// ── Session lifecycle flags ──────────────────────────────────────────────
-// `--live` / `--focus` / `--reuse` are top-level-ish toggles that tweak the automation
-// window's lifecycle. We strip them from argv before Commander runs so they
-// can be placed anywhere and work on any subcommand (adapter or browser).
+// ── Browser reuse flag ───────────────────────────────────────────────────
+// `--reuse` is a runtime-level browser session override rather than an adapter
+// arg. Strip it before Commander runs and expose it through an explicit env
+// name. Window/keep-tab are registered on browser-backed commands directly.
 {
-    const liveIdx = process.argv.indexOf('--live');
-    if (liveIdx !== -1) {
-        process.env.OPENCLI_LIVE = '1';
-        process.argv.splice(liveIdx, 1);
-    }
-    const focusIdx = process.argv.indexOf('--focus');
-    if (focusIdx !== -1) {
-        process.env.OPENCLI_WINDOW_FOCUSED = '1';
-        process.argv.splice(focusIdx, 1);
-    }
     const reuseIdx = process.argv.findIndex(arg => arg === '--reuse' || arg.startsWith('--reuse='));
     if (reuseIdx !== -1) {
         const arg = process.argv[reuseIdx];

package/dist/src/runtime.d.ts

@@ -6,6 +6,7 @@ import type { IPage } from './types.js';
 export declare function getBrowserFactory(site?: string): new () => IBrowserFactory;
 export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
 export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;
+export type BrowserWindowMode = 'foreground' | 'background';
 /**
  * Timeout with seconds unit. Used for high-level command timeouts.
  */
@@ -28,6 +29,7 @@ export interface IBrowserFactory {
         cdpEndpoint?: string;
         contextId?: string;
         idleTimeout?: number;
+        windowMode?: BrowserWindowMode;
     }): Promise<IPage>;
     close(): Promise<void>;
 }
@@ -36,4 +38,5 @@ export declare function browserSession<T>(BrowserFactory: new () => IBrowserFact
     cdpEndpoint?: string;
     contextId?: string;
     idleTimeout?: number;
+    windowMode?: BrowserWindowMode;
 }): Promise<T>;

package/dist/src/runtime.js

@@ -54,6 +54,7 @@ export async function browserSession(BrowserFactory, fn, opts = {}) {
             cdpEndpoint: opts.cdpEndpoint,
             contextId: opts.contextId,
             idleTimeout: opts.idleTimeout,
+            windowMode: opts.windowMode,
         });
         return await fn(page);
     }