@jackwener/opencli 1.7.16 → 1.7.17

package/dist/src/browser/network-cache.d.ts

@@ -6,7 +6,7 @@
  * stable references to request bodies after running other commands,
  * so every `browser network` call snapshots its results to disk.
  *
- * Layout: <cacheDir>/browser-network/<workspace>.json
+ * Layout: <cacheDir>/browser-network/<session>.json
  * Entries expire after DEFAULT_TTL_MS (24h).
  */
 export declare const DEFAULT_TTL_MS: number;
@@ -29,12 +29,12 @@ export interface CachedNetworkEntry {
 }
 export interface NetworkCacheFile {
     version: 1;
-    workspace: string;
+    session: string;
     savedAt: string;
     entries: CachedNetworkEntry[];
 }
-export declare function getCachePath(workspace: string, baseDir?: string): string;
-export declare function saveNetworkCache(workspace: string, entries: CachedNetworkEntry[], baseDir?: string): void;
+export declare function getCachePath(session: string, baseDir?: string): string;
+export declare function saveNetworkCache(session: string, entries: CachedNetworkEntry[], baseDir?: string): void;
 export interface LoadOptions {
     baseDir?: string;
     ttlMs?: number;
@@ -45,5 +45,5 @@ export interface LoadResult {
     file?: NetworkCacheFile;
     ageMs?: number;
 }
-export declare function loadNetworkCache(workspace: string, opts?: LoadOptions): LoadResult;
+export declare function loadNetworkCache(session: string, opts?: LoadOptions): LoadResult;
 export declare function findEntry(file: NetworkCacheFile, key: string): CachedNetworkEntry | null;

package/dist/src/browser/network-cache.js

@@ -6,7 +6,7 @@
  * stable references to request bodies after running other commands,
  * so every `browser network` call snapshots its results to disk.
  *
- * Layout: <cacheDir>/browser-network/<workspace>.json
+ * Layout: <cacheDir>/browser-network/<session>.json
  * Entries expire after DEFAULT_TTL_MS (24h).
  */
 import * as fs from 'node:fs';
@@ -16,23 +16,23 @@ export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
 function getDefaultCacheDir() {
     return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
 }
-export function getCachePath(workspace, baseDir = getDefaultCacheDir()) {
-    const safe = workspace.replace(/[^a-zA-Z0-9_-]+/g, '_');
+export function getCachePath(session, baseDir = getDefaultCacheDir()) {
+    const safe = session.replace(/[^a-zA-Z0-9_-]+/g, '_');
     return path.join(baseDir, 'browser-network', `${safe}.json`);
 }
-export function saveNetworkCache(workspace, entries, baseDir) {
-    const target = getCachePath(workspace, baseDir);
+export function saveNetworkCache(session, entries, baseDir) {
+    const target = getCachePath(session, baseDir);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const payload = {
         version: 1,
-        workspace,
+        session,
         savedAt: new Date().toISOString(),
         entries,
     };
     fs.writeFileSync(target, JSON.stringify(payload), 'utf-8');
 }
-export function loadNetworkCache(workspace, opts = {}) {
-    const target = getCachePath(workspace, opts.baseDir);
+export function loadNetworkCache(session, opts = {}) {
+    const target = getCachePath(session, opts.baseDir);
     let raw;
     try {
         raw = fs.readFileSync(target, 'utf-8');

package/dist/src/browser/network-cache.test.js

@@ -14,9 +14,9 @@ describe('network-cache', () => {
     afterEach(() => {
         fs.rmSync(baseDir, { recursive: true, force: true });
     });
-    it('sanitizes workspace names into safe filenames', () => {
-        const p = getCachePath('browser:default', baseDir);
-        expect(path.basename(p)).toBe('browser_default.json');
+    it('sanitizes session names into safe filenames', () => {
+        const p = getCachePath('twitter/agent 1', baseDir);
+        expect(path.basename(p)).toBe('twitter_agent_1.json');
     });
     it('round-trips entries through save + load', () => {
         saveNetworkCache('ws', [makeEntry('UserTweets'), makeEntry('UserByScreenName')], baseDir);
@@ -49,7 +49,7 @@ describe('network-cache', () => {
     });
     it('findEntry returns matching entry or null', () => {
         const file = {
-            version: 1, workspace: 'ws', savedAt: new Date().toISOString(),
+            version: 1, session: 'ws', savedAt: new Date().toISOString(),
             entries: [makeEntry('A'), makeEntry('B')],
         };
         expect(findEntry(file, 'B')?.key).toBe('B');

package/dist/src/browser/page.d.ts

@@ -14,23 +14,24 @@ import { BasePage } from './base-page.js';
  * Page — implements IPage by talking to the daemon via HTTP.
  */
 export declare class Page extends BasePage {
-    private readonly workspace;
+    private readonly session;
     readonly contextId?: string | undefined;
     private readonly windowMode?;
+    private readonly surface;
+    private readonly siteSession?;
     private readonly _idleTimeout;
-    constructor(workspace?: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined);
+    constructor(session: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined, surface?: 'browser' | 'adapter', siteSession?: "ephemeral" | "persistent" | undefined);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;
     private _networkCaptureWarned;
-    /** Helper: spread workspace into command params */
-    private _wsOpt;
-    /** Helper: spread workspace + page identity into command params */
+    /** Helper: spread session into command params */
+    private _sessionOpts;
+    /** Helper: spread session + page identity into command params */
     private _cmdOpts;
     goto(url: string, options?: {
         waitUntil?: 'load' | 'none';
         settleMs?: number;
-        allowBoundNavigation?: boolean;
     }): Promise<void>;
     /** Get the active page identity (targetId) */
     getActivePage(): string | undefined;
@@ -42,7 +43,7 @@ export declare class Page extends BasePage {
         domain?: string;
         url?: string;
     }): Promise<BrowserCookie[]>;
-    /** Release the current automation tab lease in the extension */
+    /** Release the current browser session lease in the extension */
     closeWindow(): Promise<void>;
     tabs(): Promise<unknown[]>;
     newTab(url?: string): Promise<string | undefined>;

package/dist/src/browser/page.js

@@ -26,45 +26,52 @@ function isUnsupportedNetworkCaptureError(err) {
  * Page — implements IPage by talking to the daemon via HTTP.
  */
 export class Page extends BasePage {
-    workspace;
+    session;
     contextId;
     windowMode;
+    surface;
+    siteSession;
     _idleTimeout;
-    constructor(workspace = 'default', idleTimeout, contextId, windowMode) {
+    constructor(session, idleTimeout, contextId, windowMode, surface = 'browser', siteSession) {
         super();
-        this.workspace = workspace;
+        this.session = session;
         this.contextId = contextId;
         this.windowMode = windowMode;
+        this.surface = surface;
+        this.siteSession = siteSession;
         this._idleTimeout = idleTimeout;
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     _page;
     _networkCaptureUnsupported = false;
     _networkCaptureWarned = false;
-    /** Helper: spread workspace into command params */
-    _wsOpt() {
+    /** Helper: spread session into command params */
+    _sessionOpts() {
         return {
-            workspace: this.workspace,
+            session: this.session,
+            surface: this.surface,
             ...(this.contextId && { contextId: this.contextId }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),
+            ...(this.siteSession && { siteSession: this.siteSession }),
         };
     }
-    /** Helper: spread workspace + page identity into command params */
+    /** Helper: spread session + page identity into command params */
     _cmdOpts() {
         return {
-            workspace: this.workspace,
+            session: this.session,
+            surface: this.surface,
             ...(this.contextId && { contextId: this.contextId }),
             ...(this._page !== undefined && { page: this._page }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
             ...(this.windowMode && { windowMode: this.windowMode }),
+            ...(this.siteSession && { siteSession: this.siteSession }),
         };
     }
     async goto(url, options) {
         const result = await sendCommandFull('navigate', {
             url,
             ...this._cmdOpts(),
-            ...(options?.allowBoundNavigation === true && { allowBoundNavigation: true }),
         });
         // Remember the page identity (targetId) for subsequent calls
         if (result.page) {
@@ -144,13 +151,13 @@ export class Page extends BasePage {
         }
     }
     async getCookies(opts = {}) {
-        const result = await sendCommand('cookies', { ...this._wsOpt(), ...opts });
+        const result = await sendCommand('cookies', { ...this._sessionOpts(), ...opts });
         return Array.isArray(result) ? result : [];
     }
-    /** Release the current automation tab lease in the extension */
+    /** Release the current browser session lease in the extension */
     async closeWindow() {
         try {
-            await sendCommand('close-window', { ...this._wsOpt() });
+            await sendCommand('close-window', { ...this._sessionOpts() });
         }
         catch {
             // Window may already be closed or daemon may be down
@@ -163,20 +170,20 @@ export class Page extends BasePage {
         }
     }
     async tabs() {
-        const result = await sendCommand('tabs', { op: 'list', ...this._wsOpt() });
+        const result = await sendCommand('tabs', { op: 'list', ...this._sessionOpts() });
         return Array.isArray(result) ? result : [];
     }
     async newTab(url) {
         const result = await sendCommandFull('tabs', {
             op: 'new',
             ...(url !== undefined && { url }),
-            ...this._wsOpt(),
+            ...this._sessionOpts(),
         });
         this._lastUrl = null;
         return result.page;
     }
     async closeTab(target) {
-        const params = { op: 'close', ...this._wsOpt() };
+        const params = { op: 'close', ...this._sessionOpts() };
         if (typeof target === 'number')
             params.index = target;
         else if (typeof target === 'string')
@@ -194,7 +201,7 @@ export class Page extends BasePage {
         const result = await sendCommandFull('tabs', {
             op: 'select',
             ...(typeof target === 'number' ? { index: target } : { page: target }),
-            ...this._wsOpt(),
+            ...this._sessionOpts(),
         });
         if (result.page)
             this._page = result.page;

package/dist/src/browser/page.test.js

@@ -24,21 +24,40 @@ describe('Page.getCurrentUrl', () => {
     });
     it('reads the real browser URL when no local navigation cache exists', async () => {
         sendCommandMock.mockResolvedValueOnce('https://notebooklm.google.com/notebook/nb-live');
-        const page = new Page('site:notebooklm');
+        const page = new Page('notebooklm', undefined, undefined, undefined, 'adapter');
         const url = await page.getCurrentUrl();
         expect(url).toBe('https://notebooklm.google.com/notebook/nb-live');
         expect(sendCommandMock).toHaveBeenCalledTimes(1);
         expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
-            workspace: 'site:notebooklm',
+            session: 'notebooklm',
+            surface: 'adapter',
         }));
     });
     it('caches the discovered browser URL for later reads', async () => {
         sendCommandMock.mockResolvedValueOnce('https://notebooklm.google.com/notebook/nb-live');
-        const page = new Page('site:notebooklm');
+        const page = new Page('notebooklm', undefined, undefined, undefined, 'adapter');
         expect(await page.getCurrentUrl()).toBe('https://notebooklm.google.com/notebook/nb-live');
         expect(await page.getCurrentUrl()).toBe('https://notebooklm.google.com/notebook/nb-live');
         expect(sendCommandMock).toHaveBeenCalledTimes(1);
     });
+    it('passes adapter site session lifecycle through daemon commands', async () => {
+        sendCommandFullMock.mockResolvedValueOnce({ page: 'page-1', data: { url: 'https://chatgpt.com/' } });
+        sendCommandMock.mockResolvedValueOnce(null);
+        const page = new Page('site:chatgpt', undefined, undefined, undefined, 'adapter', 'persistent');
+        await page.goto('https://chatgpt.com/', { waitUntil: 'none' });
+        await page.evaluate('document.title');
+        expect(sendCommandFullMock).toHaveBeenCalledWith('navigate', expect.objectContaining({
+            session: 'site:chatgpt',
+            surface: 'adapter',
+            siteSession: 'persistent',
+        }));
+        expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
+            session: 'site:chatgpt',
+            surface: 'adapter',
+            siteSession: 'persistent',
+            page: 'page-1',
+        }));
+    });
 });
 describe('Page.evaluate', () => {
     beforeEach(() => {
@@ -50,7 +69,7 @@ describe('Page.evaluate', () => {
         sendCommandMock
             .mockRejectedValueOnce(new Error('{"code":-32000,"message":"Inspected target navigated or closed"}'))
             .mockResolvedValueOnce(42);
-        const page = new Page('site:notebooklm');
+        const page = new Page('notebooklm', undefined, undefined, undefined, 'adapter');
         const value = await page.evaluate('21 + 21');
         expect(value).toBe(42);
         expect(sendCommandMock).toHaveBeenCalledTimes(2);
@@ -64,30 +83,32 @@ describe('Page network capture compatibility', () => {
     });
     it('treats unknown network-capture-start as unsupported and memoizes it', async () => {
         sendCommandMock.mockRejectedValueOnce(new Error('Unknown action: network-capture-start'));
-        const page = new Page('site:notebooklm');
+        const page = new Page('notebooklm', undefined, undefined, undefined, 'adapter');
         await expect(page.startNetworkCapture()).resolves.toBe(false);
         await expect(page.startNetworkCapture()).resolves.toBe(false);
         expect(sendCommandMock).toHaveBeenCalledTimes(1);
         expect(warnMock).toHaveBeenCalledTimes(1);
         expect(warnMock).toHaveBeenCalledWith(expect.stringContaining('does not support network capture'));
         expect(sendCommandMock).toHaveBeenCalledWith('network-capture-start', expect.objectContaining({
-            workspace: 'site:notebooklm',
+            session: 'notebooklm',
+            surface: 'adapter',
         }));
     });
     it('returns an empty capture when network-capture-read is unsupported', async () => {
         sendCommandMock.mockRejectedValueOnce(new Error('Unknown action: network-capture-read'));
-        const page = new Page('site:notebooklm');
+        const page = new Page('notebooklm', undefined, undefined, undefined, 'adapter');
         await expect(page.readNetworkCapture()).resolves.toEqual([]);
         await expect(page.readNetworkCapture()).resolves.toEqual([]);
         expect(sendCommandMock).toHaveBeenCalledTimes(1);
         expect(warnMock).toHaveBeenCalledTimes(1);
         expect(sendCommandMock).toHaveBeenCalledWith('network-capture-read', expect.objectContaining({
-            workspace: 'site:notebooklm',
+            session: 'notebooklm',
+            surface: 'adapter',
         }));
     });
     it('rethrows unrelated network capture failures', async () => {
         sendCommandMock.mockRejectedValueOnce(new Error('Extension disconnected'));
-        const page = new Page('site:notebooklm');
+        const page = new Page('notebooklm', undefined, undefined, undefined, 'adapter');
         await expect(page.startNetworkCapture()).rejects.toThrow('Extension disconnected');
         expect(sendCommandMock).toHaveBeenCalledTimes(1);
         expect(warnMock).not.toHaveBeenCalled();
@@ -96,7 +117,7 @@ describe('Page network capture compatibility', () => {
         sendCommandMock
             .mockRejectedValueOnce(new Error('Unknown action: network-capture-start'))
             .mockRejectedValueOnce(new Error('Unknown action: network-capture-read'));
-        const page = new Page('site:notebooklm');
+        const page = new Page('notebooklm', undefined, undefined, undefined, 'adapter');
         await expect(page.startNetworkCapture()).resolves.toBe(false);
         await expect(page.readNetworkCapture()).resolves.toEqual([]);
         expect(warnMock).toHaveBeenCalledTimes(1);
@@ -108,14 +129,14 @@ describe('Page download waits', () => {
         sendCommandFullMock.mockReset();
         warnMock.mockReset();
     });
-    it('sends wait-download through the daemon with workspace and timeout', async () => {
+    it('sends wait-download through the daemon with session and timeout', async () => {
         sendCommandMock.mockResolvedValueOnce({
             downloaded: true,
             filename: '/tmp/receipt.pdf',
             state: 'complete',
             elapsedMs: 5,
         });
-        const page = new Page('site:mercury');
+        const page = new Page('mercury', undefined, undefined, undefined, 'adapter');
         const result = await page.waitForDownload('receipt', 1234);
         expect(result).toEqual({
             downloaded: true,
@@ -124,7 +145,8 @@ describe('Page download waits', () => {
             elapsedMs: 5,
         });
         expect(sendCommandMock).toHaveBeenCalledWith('wait-download', expect.objectContaining({
-            workspace: 'site:mercury',
+            session: 'mercury',
+            surface: 'adapter',
             pattern: 'receipt',
             timeoutMs: 1234,
         }));
@@ -138,10 +160,11 @@ describe('Page CDP helpers', () => {
     });
     it('handles JavaScript dialogs through the CDP passthrough', async () => {
         sendCommandMock.mockResolvedValueOnce({});
-        const page = new Page('browser:default');
+        const page = new Page('default');
         await page.handleJavaScriptDialog(true, 'confirm');
         expect(sendCommandMock).toHaveBeenCalledWith('cdp', expect.objectContaining({
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
             cdpMethod: 'Page.handleJavaScriptDialog',
             cdpParams: { accept: true, promptText: 'confirm' },
         }));
@@ -158,24 +181,26 @@ describe('Page active target tracking', () => {
             .mockResolvedValueOnce({ data: { url: 'https://first.example' }, page: 'page-1' })
             .mockResolvedValueOnce({ data: { selected: true }, page: 'page-2' });
         sendCommandMock.mockResolvedValue('ok');
-        const page = new Page('browser:default');
+        const page = new Page('default');
         await page.goto('https://first.example', { waitUntil: 'none' });
         expect(page.getActivePage()).toBe('page-1');
         await page.selectTab(1);
         expect(page.getActivePage()).toBe('page-2');
         await page.evaluate('1 + 1');
         expect(sendCommandMock).toHaveBeenLastCalledWith('exec', expect.objectContaining({
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
             page: 'page-2',
         }));
     });
     it('allows the caller to bind a specific active page identity explicitly', async () => {
         sendCommandMock.mockResolvedValue('bound');
-        const page = new Page('browser:default');
+        const page = new Page('default');
         page.setActivePage?.('page-explicit');
         await page.evaluate('1 + 1');
         expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
             page: 'page-explicit',
         }));
     });
@@ -187,14 +212,15 @@ describe('Page active target tracking', () => {
             page: 'page-2',
         });
         sendCommandMock.mockResolvedValue('ok');
-        const page = new Page('browser:default');
+        const page = new Page('default');
         await page.goto('https://first.example', { waitUntil: 'none' });
         const created = await page.newTab?.('https://second.example');
         expect(created).toBe('page-2');
         expect(page.getActivePage()).toBe('page-1');
         await page.evaluate('1 + 1');
         expect(sendCommandMock).toHaveBeenLastCalledWith('exec', expect.objectContaining({
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
             page: 'page-1',
         }));
     });
@@ -203,7 +229,7 @@ describe('Page active target tracking', () => {
             data: { url: 'https://second.example' },
             page: 'page-2',
         });
-        const page = new Page('browser:default');
+        const page = new Page('default');
         const created = await page.newTab?.('https://second.example');
         expect(created).toBe('page-2');
         expect(page.getActivePage()).toBeUndefined();
@@ -212,16 +238,18 @@ describe('Page active target tracking', () => {
         expect(sendCommandFullMock).toHaveBeenCalledWith('tabs', expect.objectContaining({
             op: 'new',
             url: 'https://second.example',
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
         }));
     });
     it('closes a tab by explicit page identity', async () => {
         sendCommandMock.mockResolvedValueOnce({ closed: 'page-2' });
-        const page = new Page('browser:default');
+        const page = new Page('default');
         await page.closeTab?.('page-2');
         expect(sendCommandMock).toHaveBeenCalledWith('tabs', expect.objectContaining({
             op: 'close',
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
             page: 'page-2',
         }));
     });
@@ -230,7 +258,7 @@ describe('Page active target tracking', () => {
         sendCommandMock
             .mockResolvedValueOnce({ closed: 'page-2' })
             .mockResolvedValueOnce('ok');
-        const page = new Page('browser:default');
+        const page = new Page('default');
         await page.selectTab(1);
         expect(page.getActivePage()).toBe('page-2');
         await page.closeTab?.(1);
@@ -239,7 +267,8 @@ describe('Page active target tracking', () => {
         const evalCall = sendCommandMock.mock.calls.at(-1);
         expect(evalCall?.[0]).toBe('exec');
         expect(evalCall?.[1]).toEqual(expect.objectContaining({
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
         }));
         expect(evalCall?.[1]).not.toHaveProperty('page');
     });
@@ -252,18 +281,19 @@ describe('Page.screenshot', () => {
     });
     it('forwards width / height / fullPage options to the bridge', async () => {
         sendCommandMock.mockResolvedValueOnce('BASE64');
-        const page = new Page('browser:default');
+        const page = new Page('default');
         const data = await page.screenshot({ fullPage: true, width: 1080 });
         expect(data).toBe('BASE64');
         expect(sendCommandMock).toHaveBeenCalledWith('screenshot', expect.objectContaining({
-            workspace: 'browser:default',
+            session: 'default',
+            surface: 'browser',
             fullPage: true,
             width: 1080,
         }));
     });
     it('omits viewport overrides when none are set', async () => {
         sendCommandMock.mockResolvedValueOnce('BASE64');
-        const page = new Page('browser:default');
+        const page = new Page('default');
         await page.screenshot();
         const call = sendCommandMock.mock.calls.at(-1);
         expect(call?.[0]).toBe('screenshot');

package/dist/src/build-manifest.js

@@ -102,7 +102,7 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         modulePath,
         sourceFile,
         navigateBefore: cmd.navigateBefore,
-        browserSession: cmd.browserSession,
+        siteSession: cmd.siteSession,
     };
 }
 /**