@jackwener/opencli 1.7.16 → 1.7.18

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, windowMode: 'background' });
-        expect(sessionOpts[1]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600, windowMode: 'background' });
+        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,9 +184,9 @@ 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');
@@ -192,7 +194,7 @@ describe('executeCommand — non-browser timeout', () => {
         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 = [];
@@ -201,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 = {
@@ -239,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, {});
@@ -252,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 = {
@@ -264,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, {});

package/dist/src/help.js

@@ -35,6 +35,12 @@ const BROWSER_COMMON_OPTIONS = [
         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',
@@ -323,7 +329,7 @@ function compactCommand(cmd) {
         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 } : {}),
     };

package/dist/src/main.js

@@ -27,25 +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');
-// ── 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 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

@@ -7,6 +7,7 @@ export declare function getBrowserFactory(site?: string): new () => IBrowserFact
 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.
  */
@@ -25,18 +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,11 +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 ──────────────────────────────────────────────────────────────

package/dist/src/types.d.ts

@@ -60,25 +60,10 @@ export interface FetchJsonOptions {
     body?: unknown;
     timeoutMs?: number;
 }
-export interface BrowserSessionInfo {
-    workspace?: string;
-    connected?: boolean;
-    windowId?: number;
-    preferredTabId?: number | null;
-    owned?: boolean;
-    ownership?: 'owned' | 'borrowed';
-    lifecycle?: 'ephemeral' | 'persistent' | 'pinned';
-    windowRole?: 'interactive' | 'automation' | 'borrowed-user';
-    contextId?: string;
-    tabCount?: number;
-    idleMsRemaining?: number | null;
-    [key: string]: unknown;
-}
 export interface IPage {
     goto(url: string, options?: {
         waitUntil?: 'load' | 'none';
         settleMs?: number;
-        allowBoundNavigation?: boolean;
     }): Promise<void>;
     evaluate(js: string): Promise<any>;
     /** Safely evaluate JS with pre-serialized arguments — prevents injection. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.16",
+  "version": "1.7.18",
   "publishConfig": {
     "access": "public"
   },