@jackwener/opencli 1.7.15 → 1.7.17

package/dist/src/execution.test.js

@@ -136,7 +136,7 @@ describe('executeCommand — non-browser timeout', () => {
         });
         vi.restoreAllMocks();
     });
-    it('reuses a site-scoped browser workspace and keeps the tab lease open', async () => {
+    it('reuses a persistent site browser session and keeps the tab lease open', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         const sessionOpts = [];
@@ -147,22 +147,24 @@ describe('executeCommand — non-browser timeout', () => {
         });
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-site', access: 'read',
-            description: 'test site-scoped browser reuse',
+            name: 'site-session-persistent', access: 'read',
+            description: 'test persistent site session',
             browser: true,
             strategy: Strategy.PUBLIC,
-            browserSession: { reuse: 'site' },
+            siteSession: 'persistent',
             func: async () => [{ ok: true }],
         });
         await executeCommand(cmd, {});
-        await executeCommand(cmd, {});
+        await executeCommand(cmd, {}, false, { keepTab: 'false' });
         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({ session: 'site:test-execution', windowMode: 'background', siteSession: 'persistent' });
+        expect(sessionOpts[1]).toMatchObject({ session: 'site:test-execution', windowMode: 'background', siteSession: 'persistent' });
+        expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
+        expect(sessionOpts[1]?.idleTimeout).toBeUndefined();
         expect(closeWindow).not.toHaveBeenCalled();
         vi.restoreAllMocks();
     });
-    it('keeps default browser commands on one-shot workspaces', async () => {
+    it('keeps default browser commands on one-shot adapter sessions', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         const sessionOpts = [];
@@ -173,8 +175,8 @@ describe('executeCommand — non-browser timeout', () => {
         });
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-default', access: 'read',
-            description: 'test default one-shot browser workspace',
+            name: 'site-session-default', access: 'read',
+            description: 'test default one-shot browser session',
             browser: true,
             strategy: Strategy.PUBLIC,
             func: async () => [{ ok: true }],
@@ -182,15 +184,17 @@ describe('executeCommand — non-browser timeout', () => {
         await executeCommand(cmd, {});
         await executeCommand(cmd, {});
         expect(sessionOpts).toHaveLength(2);
-        expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
-        expect(sessionOpts[1]?.workspace).toMatch(/^site:test-execution:/);
-        expect(sessionOpts[0]?.workspace).not.toBe(sessionOpts[1]?.workspace);
+        expect(sessionOpts[0]?.session).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[1]?.session).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[0]?.session).not.toBe(sessionOpts[1]?.session);
         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();
     });
-    it('lets user --reuse none override adapter reuse metadata', async () => {
+    it('lets user --site-session ephemeral override adapter persistent metadata', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         const sessionOpts = [];
@@ -199,33 +203,27 @@ describe('executeCommand — non-browser timeout', () => {
             sessionOpts.push(opts ?? {});
             return fn(mockPage);
         });
-        const prev = process.env.OPENCLI_BROWSER_REUSE;
-        process.env.OPENCLI_BROWSER_REUSE = 'none';
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-reuse-override-none', access: 'read',
-                description: 'test user reuse override',
+                name: 'site-session-override-ephemeral', access: 'read',
+                description: 'test user site-session override',
                 browser: true,
                 strategy: Strategy.PUBLIC,
-                browserSession: { reuse: 'site' },
+                siteSession: 'persistent',
                 func: async () => [{ ok: true }],
             });
-            await executeCommand(cmd, {});
+            await executeCommand(cmd, {}, false, { siteSession: 'ephemeral' });
             expect(sessionOpts).toHaveLength(1);
-            expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
+            expect(sessionOpts[0]?.session).toMatch(/^site:test-execution:/);
             expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
             expect(closeWindow).toHaveBeenCalledTimes(1);
         }
         finally {
-            if (prev === undefined)
-                delete process.env.OPENCLI_BROWSER_REUSE;
-            else
-                process.env.OPENCLI_BROWSER_REUSE = prev;
             vi.restoreAllMocks();
         }
     });
-    it('skips repeated domain pre-navigation for site-reused browser sessions', async () => {
+    it('skips repeated domain pre-navigation for persistent site sessions', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const goto = vi.fn().mockResolvedValue(undefined);
         const mockPage = {
@@ -237,12 +235,12 @@ describe('executeCommand — non-browser timeout', () => {
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-skip-prenav', access: 'read',
+            name: 'site-session-skip-prenav', access: 'read',
             description: 'test reused same-domain tabs do not reset conversation state',
             browser: true,
             strategy: Strategy.COOKIE,
             domain: 'grok.com',
-            browserSession: { reuse: 'site' },
+            siteSession: 'persistent',
             func: async () => [{ ok: true }],
         });
         await executeCommand(cmd, {});
@@ -250,7 +248,7 @@ describe('executeCommand — non-browser timeout', () => {
         expect(closeWindow).not.toHaveBeenCalled();
         vi.restoreAllMocks();
     });
-    it('keeps explicit path pre-navigation for site-reused browser sessions', async () => {
+    it('keeps explicit path pre-navigation for persistent site sessions', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const goto = vi.fn().mockResolvedValue(undefined);
         const mockPage = {
@@ -262,13 +260,13 @@ describe('executeCommand — non-browser timeout', () => {
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-path-prenav', access: 'read',
+            name: 'site-session-path-prenav', access: 'read',
             description: 'test explicit path pre-navigation still runs',
             browser: true,
             strategy: Strategy.COOKIE,
             domain: 'example.com',
             navigateBefore: 'https://example.com/dashboard',
-            browserSession: { reuse: 'site' },
+            siteSession: 'persistent',
             func: async () => [{ ok: true }],
         });
         await executeCommand(cmd, {});
@@ -372,18 +370,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 +391,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 +418,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;

package/dist/src/help.js

@@ -28,6 +28,26 @@ 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: '--site-session <mode>',
+        name: 'site-session',
+        help: 'Adapter site session lifecycle: ephemeral or persistent',
+        choices: ['ephemeral', 'persistent'],
+    },
+    {
+        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')
@@ -307,8 +327,9 @@ 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.siteSession ? { siteSession: cmd.siteSession } : {}),
         ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
         ...(cmd.columns?.length ? { columns: cmd.columns } : {}),
     };
@@ -353,6 +374,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`,
@@ -364,6 +386,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'],
     };
 }
@@ -394,6 +417,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));
@@ -406,6 +438,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.`,
         '',
@@ -434,6 +467,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,35 +27,6 @@ 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).
-{
-    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];
-        const value = arg.startsWith('--reuse=')
-            ? arg.slice('--reuse='.length)
-            : process.argv[reuseIdx + 1];
-        if (value !== 'none' && value !== 'site') {
-            process.stderr.write(`--reuse must be one of: none, site. Received: "${value ?? ''}"\n`);
-            process.exit(EXIT_CODES.USAGE_ERROR);
-        }
-        process.env.OPENCLI_BROWSER_REUSE = value;
-        process.argv.splice(reuseIdx, arg.startsWith('--reuse=') ? 1 : 2);
-    }
-}
 // ── Ultra-fast path: lightweight commands bypass full discovery ──────────
 // These are high-frequency or trivial paths that must not pay the startup tax.
 const argv = process.argv.slice(2);

package/dist/src/manifest-types.d.ts

@@ -36,8 +36,6 @@ export interface ManifestEntry {
     sourceFile?: string;
     /** Pre-navigation control — see CliCommand.navigateBefore */
     navigateBefore?: boolean | string;
-    /** Browser session lifecycle defaults — see CliCommand.browserSession */
-    browserSession?: {
-        reuse?: 'none' | 'site';
-    };
+    /** Site session lifecycle defaults — see CliCommand.siteSession */
+    siteSession?: 'ephemeral' | 'persistent';
 }

package/dist/src/observation/artifact.js

@@ -141,7 +141,7 @@ function renderSummary(session, events, opts) {
         `traceId: ${yamlScalar(session.id)}`,
         `status: ${opts.status}`,
         `contextId: ${yamlScalar(session.scope.contextId ?? 'default')}`,
-        `workspace: ${yamlScalar(session.scope.workspace)}`,
+        `session: ${yamlScalar(session.scope.session)}`,
         ...(session.scope.target ? [`target: ${yamlScalar(session.scope.target)}`] : []),
         ...(session.scope.site ? [`site: ${yamlScalar(session.scope.site)}`] : []),
         ...(session.scope.command ? [`command: ${yamlScalar(session.scope.command)}`] : []),

package/dist/src/observation/artifact.test.js

@@ -17,7 +17,7 @@ describe('observation artifact', () => {
             id: 'trace-1',
             scope: {
                 contextId: 'work',
-                workspace: 'site:demo',
+                session: 'site:demo',
                 site: 'demo',
                 command: 'demo/run',
                 adapterSourcePath: '/tmp/clis/demo/run.js',
@@ -69,7 +69,7 @@ describe('observation artifact', () => {
             expiresAt: expect.any(String),
             scope: {
                 contextId: 'work',
-                workspace: 'site:demo',
+                session: 'site:demo',
                 site: 'demo',
                 command: 'demo/run',
                 adapterSourcePath: '/tmp/clis/demo/run.js',
@@ -107,7 +107,7 @@ describe('observation artifact', () => {
         fs.writeFileSync(path.join(oldTraceDir, 'trace.jsonl'), '{}\n', 'utf-8');
         const session = new ObservationSession({
             id: 'new-trace',
-            scope: { contextId: 'work', workspace: 'site:demo' },
+            scope: { contextId: 'work', session: 'site:demo' },
             now: () => Date.parse('2026-05-03T00:00:00.000Z'),
         });
         session.record({ stream: 'action', name: 'command', phase: 'start' });

package/dist/src/observation/events.d.ts

@@ -1,7 +1,7 @@
 export type ObservationStream = 'action' | 'network' | 'console' | 'screenshot' | 'state' | 'error';
 export interface ObservationScope {
     contextId?: string;
-    workspace: string;
+    session: string;
     target?: string;
     site?: string;
     command?: string;

package/dist/src/observation/manager.js

@@ -19,7 +19,7 @@ export class ObservationManager {
     }
 }
 function scopeMatches(actual, expected) {
-    return actual.workspace === expected.workspace
+    return actual.session === expected.session
         && (expected.contextId === undefined || actual.contextId === expected.contextId)
         && (expected.target === undefined || actual.target === expected.target)
         && (expected.site === undefined || actual.site === expected.site)

package/dist/src/observation/manager.test.js

@@ -3,10 +3,10 @@ import { ObservationManager } from './manager.js';
 describe('ObservationManager', () => {
     it('indexes sessions by id and scope', () => {
         const manager = new ObservationManager();
-        const work = manager.start({ id: 'work-1', scope: { contextId: 'work', workspace: 'site:x', target: 'tab-1' } });
-        manager.start({ id: 'personal-1', scope: { contextId: 'personal', workspace: 'site:x', target: 'tab-2' } });
+        const work = manager.start({ id: 'work-1', scope: { contextId: 'work', session: 'site:x', target: 'tab-1' } });
+        manager.start({ id: 'personal-1', scope: { contextId: 'personal', session: 'site:x', target: 'tab-2' } });
         expect(manager.get('work-1')).toBe(work);
-        expect(manager.findByScope({ contextId: 'work', workspace: 'site:x' }).map((session) => session.id)).toEqual(['work-1']);
+        expect(manager.findByScope({ contextId: 'work', session: 'site:x' }).map((session) => session.id)).toEqual(['work-1']);
         expect(manager.stop('work-1')).toBe(work);
         expect(manager.get('work-1')).toBeUndefined();
     });

package/dist/src/registry-api.d.ts

@@ -7,7 +7,7 @@
  * plugins are dynamically imported during discoverPlugins().
  */
 export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
-export type { CliCommand, Arg, CliOptions, CommandArgs, BrowserSessionOptions, BrowserSessionReuse } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs, SiteSessionMode } from './registry.js';
 export type { IPage } from './types.js';
 export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
 export type { HookFn, HookContext, HookName } from './hooks.js';

package/dist/src/registry.d.ts

@@ -23,16 +23,7 @@ export type CommandArgs = Record<string, any>;
 export type BrowserCommandFunc = (page: IPage, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type NonBrowserCommandFunc = (kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type CommandAccess = 'read' | 'write';
-export type BrowserSessionReuse = 'none' | 'site';
-export interface BrowserSessionOptions {
-    /**
-     * Control whether browser-backed adapter commands reuse a stable tab lease.
-     *
-     * - `none`: one-shot workspace per command execution (default)
-     * - `site`: all commands for this site share `site:<site>` until idle expiry
-     */
-    reuse?: BrowserSessionReuse;
-}
+export type SiteSessionMode = 'ephemeral' | 'persistent';
 interface BaseCliCommand {
     site: string;
     name: string;
@@ -66,8 +57,8 @@ interface BaseCliCommand {
      * Adapter authors can set this explicitly to override the strategy-based default.
      */
     navigateBefore?: boolean | string;
-    /** Browser session lifecycle defaults for adapter commands. */
-    browserSession?: BrowserSessionOptions;
+    /** Site session lifecycle for adapter commands. */
+    siteSession?: SiteSessionMode;
     /** Override the default CLI output format when the user does not pass -f/--format. */
     defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
 }

package/dist/src/registry.js

@@ -27,7 +27,7 @@ export function cli(opts) {
         pipeline: opts.pipeline,
         footerExtra: opts.footerExtra,
         navigateBefore: opts.navigateBefore,
-        browserSession: opts.browserSession,
+        siteSession: opts.siteSession,
         defaultFormat: opts.defaultFormat,
     };
     registerCommand(cmd);
@@ -57,7 +57,7 @@ export function strategyLabel(cmd) {
  */
 function normalizeCommand(cmd) {
     assertCommandAccess(cmd);
-    assertBrowserSessionOptions(cmd);
+    assertSiteSession(cmd);
     const strategy = cmd.strategy ?? (cmd.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
     const browser = cmd.browser ?? (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL);
     let navigateBefore = cmd.navigateBefore;
@@ -82,16 +82,12 @@ function assertCommandAccess(cmd) {
     const key = `${cmd.site}/${cmd.name}`;
     throw new Error(`Command ${key} must declare access: 'read' | 'write'`);
 }
-function assertBrowserSessionOptions(cmd) {
-    if (cmd.browserSession === undefined)
+function assertSiteSession(cmd) {
+    if (cmd.siteSession === undefined)
         return;
     const key = `${cmd.site}/${cmd.name}`;
-    if (cmd.browserSession === null || typeof cmd.browserSession !== 'object' || Array.isArray(cmd.browserSession)) {
-        throw new Error(`Command ${key} browserSession must be an object`);
-    }
-    const reuse = cmd.browserSession.reuse;
-    if (reuse !== undefined && reuse !== 'none' && reuse !== 'site') {
-        throw new Error(`Command ${key} browserSession.reuse must be one of: none, site`);
+    if (cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
+        throw new Error(`Command ${key} siteSession must be one of: ephemeral, persistent`);
     }
 }
 export function registerCommand(cmd) {

package/dist/src/runtime.d.ts

@@ -6,6 +6,8 @@ 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';
+export type BrowserSurface = 'browser' | 'adapter';
 /**
  * Timeout with seconds unit. Used for high-level command timeouts.
  */
@@ -24,16 +26,22 @@ export declare function withTimeoutMs<T>(promise: Promise<T>, timeoutMs: number,
 export interface IBrowserFactory {
     connect(opts?: {
         timeout?: number;
-        workspace?: string;
+        session?: string;
         cdpEndpoint?: string;
         contextId?: string;
         idleTimeout?: number;
+        windowMode?: BrowserWindowMode;
+        surface?: BrowserSurface;
+        siteSession?: 'ephemeral' | 'persistent';
     }): Promise<IPage>;
     close(): Promise<void>;
 }
 export declare function browserSession<T>(BrowserFactory: new () => IBrowserFactory, fn: (page: IPage) => Promise<T>, opts?: {
-    workspace?: string;
+    session?: string;
     cdpEndpoint?: string;
     contextId?: string;
     idleTimeout?: number;
+    windowMode?: BrowserWindowMode;
+    surface?: BrowserSurface;
+    siteSession?: 'ephemeral' | 'persistent';
 }): Promise<T>;

package/dist/src/runtime.js

@@ -50,10 +50,13 @@ export async function browserSession(BrowserFactory, fn, opts = {}) {
     try {
         const page = await browser.connect({
             timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT,
-            workspace: opts.workspace,
+            session: opts.session,
             cdpEndpoint: opts.cdpEndpoint,
             contextId: opts.contextId,
             idleTimeout: opts.idleTimeout,
+            windowMode: opts.windowMode,
+            surface: opts.surface,
+            siteSession: opts.siteSession,
         });
         return await fn(page);
     }

package/dist/src/serialization.d.ts

@@ -32,7 +32,7 @@ export declare function serializeCommand(cmd: CliCommand): {
     domain: string | null;
     example: string;
     defaultFormat: "table" | "plain" | "json" | "yaml" | "yml" | "md" | "markdown" | "csv" | null;
-    browserSession: import("./registry.js").BrowserSessionOptions | null;
+    siteSession: import("./registry.js").SiteSessionMode | null;
 };
 /** Human-readable arg summary: `<required> [optional]` style. */
 export declare function formatArgSummary(args: Arg[]): string;

package/dist/src/serialization.js

@@ -34,7 +34,7 @@ export function serializeCommand(cmd) {
         domain: cmd.domain ?? null,
         example: formatCommandExample(cmd),
         defaultFormat: cmd.defaultFormat ?? null,
-        browserSession: cmd.browserSession ?? null,
+        siteSession: cmd.siteSession ?? null,
     };
 }
 // ── Formatting ──────────────────────────────────────────────────────────────