@jackwener/opencli 1.7.15 → 1.7.16

package/clis/twitter/list-remove.js

@@ -92,11 +92,12 @@ cli({
         }
         if (!username) throw new CommandExecutionError('Username is required');
 
+        // Strategy.UI does not get a domain URL pre-nav from the framework.
+        // This page context is load-bearing for pre-target GraphQL calls below.
         await page.goto('https://x.com');
         await page.wait(3);
-        const ct0 = await page.evaluate(`() => {
-            return document.cookie.split(';').map(c => c.trim()).find(c => c.startsWith('ct0='))?.split('=')[1] || null;
-        }`);
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
         if (!ct0) throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
 
         const userByScreenNameQueryId = await resolveTwitterQueryId(page, 'UserByScreenName', USER_BY_SCREEN_NAME_QUERY_ID);

package/clis/twitter/list-remove.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
 import './list-remove.js';
 
@@ -11,4 +11,26 @@ describe('twitter list-remove registration', () => {
         expect(listIdArg).toBeTruthy();
         expect(listIdArg?.required).toBe(true);
     });
+
+    it('keeps the x.com root navigation before pre-target GraphQL calls', async () => {
+        const cmd = getRegistry().get('twitter/list-remove');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            getCookies: vi.fn().mockResolvedValue([{ name: 'ct0', value: 'token' }]),
+            evaluate: vi.fn()
+                .mockResolvedValueOnce(null) // UserByScreenName queryId fallback
+                .mockResolvedValueOnce('user-1')
+                .mockResolvedValueOnce(null) // ListsManagement queryId fallback
+                .mockResolvedValueOnce({}),
+        };
+
+        await expect(cmd.func(page, { listId: '123', username: 'alice' }))
+            .rejects
+            .toThrow(/List 123 not found/);
+        expect(page.goto).toHaveBeenCalledWith('https://x.com');
+        expect(page.goto).toHaveBeenCalledTimes(1);
+        expect(page.wait).toHaveBeenCalledWith(3);
+        expect(page.getCookies).toHaveBeenCalledWith({ url: 'https://x.com' });
+    });
 });

package/clis/twitter/list-tweets.js

@@ -112,6 +112,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'listId', positional: true, type: 'string', required: true, help: 'Numeric ID of a Twitter/X list (e.g. from `opencli twitter lists`)' },
         { name: 'limit', type: 'int', default: 50 },
@@ -124,11 +125,8 @@ cli({
             throw new CommandExecutionError(`Invalid listId: ${JSON.stringify(kwargs.listId)}. Expected a numeric ID (see \`opencli twitter lists\`).`);
         }
         const limit = kwargs.limit || 50;
-        await page.goto('https://x.com');
-        await page.wait(3);
-        const ct0 = await page.evaluate(`() => {
-            return document.cookie.split(';').map(c => c.trim()).find(c => c.startsWith('ct0='))?.split('=')[1] || null;
-        }`);
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
         if (!ct0)
             throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         const queryId = await page.evaluate(`async () => {

package/clis/twitter/lists.js

@@ -92,17 +92,15 @@ export const command = cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'limit', type: 'int', default: 50, help: 'Maximum number of lists to return (default 50).' },
     ],
     columns: ['id', 'name', 'members', 'followers', 'mode'],
     func: async (page, kwargs) => {
         const limit = kwargs.limit || 50;
-        await page.goto('https://x.com');
-        await page.wait(3);
-        const ct0 = await page.evaluate(`() => {
-            return document.cookie.split(';').map(c => c.trim()).find(c => c.startsWith('ct0='))?.split('=')[1] || null;
-        }`);
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
         if (!ct0)
             throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         const queryId = await page.evaluate(`async () => {

package/clis/twitter/notifications.js

@@ -8,6 +8,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.INTERCEPT,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Maximum number of notifications to return (default 20).' },
     ],

package/clis/twitter/profile.js

@@ -11,6 +11,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'username', type: 'string', positional: true, help: 'Twitter screen name (with or without @). Defaults to the logged-in user when omitted.' },
     ],
@@ -32,12 +33,16 @@ cli({
         // Navigate directly to the user's profile page (gives us cookie context)
         await page.goto(`https://x.com/${username}`);
         await page.wait(3);
+        // Read CSRF token directly from the cookie store via CDP — zero page.evaluate round-trip
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
+        if (!ct0)
+            throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         const queryId = await resolveTwitterQueryId(page, 'UserByScreenName', USER_BY_SCREEN_NAME_QUERY_ID);
         const result = await page.evaluate(`
       async () => {
         const screenName = "${username}";
-        const ct0 = document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1];
-        if (!ct0) return {error: 'No ct0 cookie — not logged into x.com'};
+        const ct0 = ${JSON.stringify(ct0)};
 
         const bearer = ${JSON.stringify(TWITTER_BEARER_TOKEN)};
         const headers = {
@@ -96,8 +101,6 @@ cli({
       }
     `);
         if (result?.error) {
-            if (String(result.error).includes('No ct0 cookie'))
-                throw new AuthRequiredError('x.com', result.error);
             throw new CommandExecutionError(result.error + (result.hint ? ` (${result.hint})` : ''));
         }
         return result || [];

package/clis/twitter/search.js

@@ -228,6 +228,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.INTERCEPT, // Use intercept strategy
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'query', type: 'string', required: true, positional: true, help: 'Search query. Raw X operators (e.g. "exact phrase", #tag, OR, lang:en, since:YYYY-MM-DD, from:, since:) are passed through unchanged.' },
         { name: 'filter', type: 'string', default: 'top', choices: ['top', 'live'], help: 'Legacy alias for --product. Kept for backwards compatibility; if --product is set it wins.' },

package/clis/twitter/thread.js

@@ -100,6 +100,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'tweet-id', positional: true, type: 'string', required: true, help: 'Tweet numeric ID (e.g. 1234567890) or full status URL' },
         { name: 'limit', type: 'int', default: 50 },
@@ -111,13 +112,10 @@ cli({
         const urlMatch = tweetId.match(/\/status\/(\d+)/);
         if (urlMatch)
             tweetId = urlMatch[1];
-        // Navigate to x.com for cookie context
-        await page.goto('https://x.com');
-        await page.wait(3);
-        // Extract CSRF token — the only thing we need from the browser
-        const ct0 = await page.evaluate(`() => {
-      return document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1] || null;
-    }`);
+        // Cookie context auto-established by framework pre-nav (Strategy.COOKIE + domain).
+        // Read CSRF token directly from the cookie store via CDP — zero page.evaluate round-trip.
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
         if (!ct0)
             throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         // Build auth headers in TypeScript

package/clis/twitter/timeline.js

@@ -141,6 +141,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         {
             name: 'type',
@@ -156,13 +157,10 @@ cli({
         const limit = kwargs.limit || 20;
         const timelineType = kwargs.type === 'following' ? 'following' : 'for-you';
         const { endpoint, method, fallbackQueryId } = TIMELINE_ENDPOINTS[timelineType];
-        // Navigate to x.com for cookie context
-        await page.goto('https://x.com');
-        await page.wait(3);
-        // Extract CSRF token
-        const ct0 = await page.evaluate(`() => {
-      return document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1] || null;
-    }`);
+        // Cookie context auto-established by framework pre-nav (Strategy.COOKIE + domain).
+        // Read CSRF token directly from the cookie store via CDP — zero page.evaluate round-trip.
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
         if (!ct0)
             throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         // Dynamically resolve queryId for the selected endpoint

package/clis/twitter/trending.js

@@ -17,6 +17,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of trends to show' },
     ],
@@ -26,10 +27,9 @@ cli({
         // Navigate to trending page
         await page.goto('https://x.com/explore/tabs/trending');
         await page.wait(3);
-        // Verify login via CSRF cookie
-        const ct0 = await page.evaluate(`(() => {
-      return document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1] || null;
-    })()`);
+        // Verify login via CSRF cookie (read directly from cookie store via CDP)
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
         if (!ct0)
             throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         await page.wait(2);

package/clis/twitter/tweets.js

@@ -149,6 +149,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'username', type: 'string', positional: true, required: true, help: 'Twitter screen name (with or without @)' },
         { name: 'limit', type: 'int', default: 20, help: 'Max tweets to return' },
@@ -160,12 +161,8 @@ cli({
         const username = String(kwargs.username || '').replace(/^@/, '').trim();
         if (!username) throw new CommandExecutionError('username is required');
 
-        await page.goto('https://x.com');
-        await page.wait(3);
-
-        const ct0 = await page.evaluate(`() => {
-      return document.cookie.split(';').map(c => c.trim()).find(c => c.startsWith('ct0='))?.split('=')[1] || null;
-    }`);
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
         if (!ct0) throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
 
         const userTweetsQueryId = await resolveTwitterQueryId(page, 'UserTweets', USER_TWEETS_QUERY_ID);

package/clis/youtube/like.js

@@ -2,7 +2,7 @@
  * YouTube like — like a video via InnerTube like API (requires SAPISIDHASH auth).
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { parseVideoId, prepareYoutubeApiPage, SAPISID_HASH_FN } from './utils.js';
+import { parseVideoId, prepareYoutubeApiPage, readYoutubeSapisid, SAPISID_HASH_FN } from './utils.js';
 import { CommandExecutionError, AuthRequiredError } from '@jackwener/opencli/errors';
 
 cli({
@@ -19,6 +19,10 @@ cli({
     func: async (page, kwargs) => {
         const videoId = parseVideoId(String(kwargs.url));
         await prepareYoutubeApiPage(page);
+        // Read SAPISID directly from the cookie store via CDP — zero document.cookie round-trip
+        const sapisid = await readYoutubeSapisid(page);
+        if (!sapisid)
+            throw new AuthRequiredError('www.youtube.com', 'Not logged in (SAPISID cookie missing)');
         const result = await page.evaluate(`
       (async () => {
         ${SAPISID_HASH_FN}
@@ -28,7 +32,7 @@ cli({
         const context = cfg.INNERTUBE_CONTEXT;
         if (!apiKey || !context) return { error: 'config', message: 'YouTube config not found' };
 
-        const authHash = await getSapisidHash('https://www.youtube.com');
+        const authHash = await getSapisidHash(${JSON.stringify(sapisid)}, 'https://www.youtube.com');
         if (!authHash) return { error: 'auth', message: 'Not logged in (SAPISID cookie missing)' };
 
         const resp = await fetch('/youtubei/v1/like/like?key=' + apiKey + '&prettyPrint=false', {

package/clis/youtube/subscribe.js

@@ -2,7 +2,7 @@
  * YouTube subscribe — subscribe to a channel via InnerTube subscription API.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { prepareYoutubeApiPage, SAPISID_HASH_FN, RESOLVE_CHANNEL_HANDLE_FN } from './utils.js';
+import { prepareYoutubeApiPage, readYoutubeSapisid, SAPISID_HASH_FN, RESOLVE_CHANNEL_HANDLE_FN } from './utils.js';
 import { CommandExecutionError, AuthRequiredError } from '@jackwener/opencli/errors';
 
 cli({
@@ -19,6 +19,10 @@ cli({
     func: async (page, kwargs) => {
         const channelInput = String(kwargs.channel);
         await prepareYoutubeApiPage(page);
+        // Read SAPISID directly from the cookie store via CDP — zero document.cookie round-trip
+        const sapisid = await readYoutubeSapisid(page);
+        if (!sapisid)
+            throw new AuthRequiredError('www.youtube.com', 'Not logged in (SAPISID cookie missing)');
         const result = await page.evaluate(`
       (async () => {
         ${SAPISID_HASH_FN}
@@ -28,7 +32,7 @@ cli({
         const context = cfg.INNERTUBE_CONTEXT;
         if (!apiKey || !context) return { error: 'config', message: 'YouTube config not found' };
 
-        const authHash = await getSapisidHash('https://www.youtube.com');
+        const authHash = await getSapisidHash(${JSON.stringify(sapisid)}, 'https://www.youtube.com');
         if (!authHash) return { error: 'auth', message: 'Not logged in (SAPISID cookie missing)' };
 
         ${RESOLVE_CHANNEL_HANDLE_FN}

package/clis/youtube/unlike.js

@@ -2,7 +2,7 @@
  * YouTube unlike — remove like from a video via InnerTube like API.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { parseVideoId, prepareYoutubeApiPage, SAPISID_HASH_FN } from './utils.js';
+import { parseVideoId, prepareYoutubeApiPage, readYoutubeSapisid, SAPISID_HASH_FN } from './utils.js';
 import { CommandExecutionError, AuthRequiredError } from '@jackwener/opencli/errors';
 
 cli({
@@ -19,6 +19,10 @@ cli({
     func: async (page, kwargs) => {
         const videoId = parseVideoId(String(kwargs.url));
         await prepareYoutubeApiPage(page);
+        // Read SAPISID directly from the cookie store via CDP — zero document.cookie round-trip
+        const sapisid = await readYoutubeSapisid(page);
+        if (!sapisid)
+            throw new AuthRequiredError('www.youtube.com', 'Not logged in (SAPISID cookie missing)');
         const result = await page.evaluate(`
       (async () => {
         ${SAPISID_HASH_FN}
@@ -28,7 +32,7 @@ cli({
         const context = cfg.INNERTUBE_CONTEXT;
         if (!apiKey || !context) return { error: 'config', message: 'YouTube config not found' };
 
-        const authHash = await getSapisidHash('https://www.youtube.com');
+        const authHash = await getSapisidHash(${JSON.stringify(sapisid)}, 'https://www.youtube.com');
         if (!authHash) return { error: 'auth', message: 'Not logged in (SAPISID cookie missing)' };
 
         const resp = await fetch('/youtubei/v1/like/removelike?key=' + apiKey + '&prettyPrint=false', {

package/clis/youtube/unsubscribe.js

@@ -2,7 +2,7 @@
  * YouTube unsubscribe — unsubscribe from a channel via InnerTube subscription API.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { prepareYoutubeApiPage, SAPISID_HASH_FN, RESOLVE_CHANNEL_HANDLE_FN } from './utils.js';
+import { prepareYoutubeApiPage, readYoutubeSapisid, SAPISID_HASH_FN, RESOLVE_CHANNEL_HANDLE_FN } from './utils.js';
 import { CommandExecutionError, AuthRequiredError } from '@jackwener/opencli/errors';
 
 cli({
@@ -19,6 +19,10 @@ cli({
     func: async (page, kwargs) => {
         const channelInput = String(kwargs.channel);
         await prepareYoutubeApiPage(page);
+        // Read SAPISID directly from the cookie store via CDP — zero document.cookie round-trip
+        const sapisid = await readYoutubeSapisid(page);
+        if (!sapisid)
+            throw new AuthRequiredError('www.youtube.com', 'Not logged in (SAPISID cookie missing)');
         const result = await page.evaluate(`
       (async () => {
         ${SAPISID_HASH_FN}
@@ -28,7 +32,7 @@ cli({
         const context = cfg.INNERTUBE_CONTEXT;
         if (!apiKey || !context) return { error: 'config', message: 'YouTube config not found' };
 
-        const authHash = await getSapisidHash('https://www.youtube.com');
+        const authHash = await getSapisidHash(${JSON.stringify(sapisid)}, 'https://www.youtube.com');
         if (!authHash) return { error: 'auth', message: 'Not logged in (SAPISID cookie missing)' };
 
         ${RESOLVE_CHANNEL_HANDLE_FN}

package/clis/youtube/utils.js

@@ -189,21 +189,13 @@ async function resolveChannelHandle(input, apiKey, context) {
  * Inline SAPISIDHASH helper for use inside page.evaluate() strings.
  * YouTube write APIs (like, subscribe) require:
  *   Authorization: SAPISIDHASH {time}_{SHA1(time + " " + SAPISID + " " + origin)}
+ *
+ * The SAPISID cookie value must be hoisted from the cookie store on the Node side
+ * (via `readYoutubeSapisid(page)`) and passed in here — keeps `crypto.subtle.digest`
+ * (browser Web Crypto) call site, but no `document.cookie` round-trip.
  */
 export const SAPISID_HASH_FN = `
-async function getSapisidHash(origin) {
-  const cookies = document.cookie.split('; ');
-  let sapisid = '';
-  for (const c of cookies) {
-    const eq = c.indexOf('=');
-    if (eq === -1) continue;
-    const name = c.slice(0, eq);
-    const val = c.slice(eq + 1);
-    if (name === '__Secure-3PAPISID' || name === 'SAPISID') {
-      sapisid = val;
-      if (name === '__Secure-3PAPISID') break;
-    }
-  }
+async function getSapisidHash(sapisid, origin) {
   if (!sapisid) return null;
   const time = Math.floor(Date.now() / 1000);
   const msgBuffer = new TextEncoder().encode(time + ' ' + sapisid + ' ' + origin);
@@ -212,3 +204,17 @@ async function getSapisidHash(origin) {
   return 'SAPISIDHASH ' + time + '_' + hashHex;
 }
 `;
+
+/**
+ * Read the YouTube SAPISID cookie via CDP, preferring `__Secure-3PAPISID`
+ * (current first-party cookie) and falling back to the legacy `SAPISID` name.
+ * Returns the cookie value, or null if neither is present.
+ */
+export async function readYoutubeSapisid(page) {
+  const cookies = await page.getCookies({ url: 'https://www.youtube.com' });
+  return (
+    cookies.find((c) => c.name === '__Secure-3PAPISID')?.value
+    || cookies.find((c) => c.name === 'SAPISID')?.value
+    || null
+  );
+}

package/clis/youtube/utils.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { extractJsonAssignmentFromHtml, extractSubscriptionChannel, prepareYoutubeApiPage } from './utils.js';
+import { extractJsonAssignmentFromHtml, extractSubscriptionChannel, prepareYoutubeApiPage, readYoutubeSapisid } from './utils.js';
 describe('youtube utils', () => {
     it('extractJsonAssignmentFromHtml parses bootstrap objects with nested braces in strings', () => {
         const html = `
@@ -34,6 +34,22 @@ describe('youtube utils', () => {
         expect(page.goto).toHaveBeenCalledWith('https://www.youtube.com', { waitUntil: 'none' });
         expect(page.wait).toHaveBeenCalledWith(2);
     });
+    it('readYoutubeSapisid reads URL-scoped cookies and prefers secure SAPISID', async () => {
+        const page = {
+            getCookies: vi.fn().mockResolvedValue([
+                { name: 'SAPISID', value: 'legacy' },
+                { name: '__Secure-3PAPISID', value: 'secure' },
+            ]),
+        };
+        await expect(readYoutubeSapisid(page)).resolves.toBe('secure');
+        expect(page.getCookies).toHaveBeenCalledWith({ url: 'https://www.youtube.com' });
+    });
+    it('readYoutubeSapisid falls back to legacy SAPISID', async () => {
+        const page = {
+            getCookies: vi.fn().mockResolvedValue([{ name: 'SAPISID', value: 'legacy' }]),
+        };
+        await expect(readYoutubeSapisid(page)).resolves.toBe('legacy');
+    });
     it('extractSubscriptionChannel prefers explicit handle and subscriber count fields', () => {
         expect(extractSubscriptionChannel({
             title: { simpleText: 'OpenAI' },

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

@@ -17,6 +17,7 @@ export declare class BrowserBridge implements IBrowserFactory {
         workspace?: string;
         idleTimeout?: number;
         contextId?: string;
+        windowMode?: 'foreground' | 'background';
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;

package/dist/src/browser/bridge.js

@@ -32,7 +32,7 @@ export class BrowserBridge {
         try {
             const contextId = opts.contextId ?? resolveProfileContextId();
             await this._ensureDaemon(opts.timeout, contextId);
-            this._page = new Page(opts.workspace, opts.idleTimeout, contextId);
+            this._page = new Page(opts.workspace, opts.idleTimeout, contextId, opts.windowMode);
             this._state = 'connected';
             return this._page;
         }

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

@@ -27,6 +27,7 @@ export declare class CDPBridge implements IBrowserFactory {
         cdpEndpoint?: string;
         contextId?: string;
         idleTimeout?: number;
+        windowMode?: 'foreground' | 'background';
     }): Promise<IPage>;
     close(): Promise<void>;
     send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;

package/dist/src/browser/daemon-client.d.ts

@@ -36,8 +36,8 @@ export interface DaemonCommand {
     timeoutMs?: number;
     cdpMethod?: string;
     cdpParams?: Record<string, unknown>;
-    /** When true, the owned automation container is created in the foreground */
-    windowFocused?: boolean;
+    /** Window foreground/background policy for owned Browser Bridge containers. */
+    windowMode?: 'foreground' | 'background';
     /** Custom idle timeout in seconds for this workspace session. Overrides the default. */
     idleTimeout?: number;
     /** Explicitly allow navigation inside a borrowed bound tab. */

package/dist/src/browser/daemon-client.js

@@ -89,10 +89,13 @@ async function sendCommandRaw(action, params) {
     const maxRetries = 4;
     for (let attempt = 1; attempt <= maxRetries; attempt++) {
         const id = generateId();
-        const wf = process.env.OPENCLI_WINDOW_FOCUSED;
-        const windowFocused = (wf === '1' || wf === 'true') ? true : undefined;
+        const rawWindowMode = process.env.OPENCLI_WINDOW;
+        const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
+            ? rawWindowMode
+            : undefined;
         const contextId = params.contextId ?? resolveProfileContextId();
-        const command = { id, action, ...params, ...(contextId && { contextId }), ...(windowFocused && { windowFocused }) };
+        const windowMode = params.windowMode ?? envWindowMode;
+        const command = { id, action, ...params, ...(contextId && { contextId }), ...(windowMode && { windowMode }) };
         try {
             const res = await requestDaemon('/command', {
                 method: 'POST',

package/dist/src/browser/daemon-client.test.js

@@ -144,6 +144,16 @@ describe('daemon-client', () => {
         const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
         expect(body.contextId).toBe('work');
     });
+    it('sendCommand uses explicit windowMode before OPENCLI_WINDOW env fallback', async () => {
+        vi.stubEnv('OPENCLI_WINDOW', 'foreground');
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await sendCommand('exec', { code: '1 + 1', windowMode: 'background' });
+        const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+        expect(body.windowMode).toBe('background');
+    });
     it('sendCommand retries with a new id when daemon reports a duplicate pending id', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_123);
         const fetchMock = vi.mocked(fetch);

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

@@ -16,8 +16,9 @@ import { BasePage } from './base-page.js';
 export declare class Page extends BasePage {
     private readonly workspace;
     readonly contextId?: string | undefined;
+    private readonly windowMode?;
     private readonly _idleTimeout;
-    constructor(workspace?: string, idleTimeout?: number, contextId?: string | undefined);
+    constructor(workspace?: string, idleTimeout?: number, contextId?: string | undefined, windowMode?: "foreground" | "background" | undefined);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;

package/dist/src/browser/page.js

@@ -28,11 +28,13 @@ function isUnsupportedNetworkCaptureError(err) {
 export class Page extends BasePage {
     workspace;
     contextId;
+    windowMode;
     _idleTimeout;
-    constructor(workspace = 'default', idleTimeout, contextId) {
+    constructor(workspace = 'default', idleTimeout, contextId, windowMode) {
         super();
         this.workspace = workspace;
         this.contextId = contextId;
+        this.windowMode = windowMode;
         this._idleTimeout = idleTimeout;
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
@@ -45,6 +47,7 @@ export class Page extends BasePage {
             workspace: this.workspace,
             ...(this.contextId && { contextId: this.contextId }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
+            ...(this.windowMode && { windowMode: this.windowMode }),
         };
     }
     /** Helper: spread workspace + page identity into command params */
@@ -54,6 +57,7 @@ export class Page extends BasePage {
             ...(this.contextId && { contextId: this.contextId }),
             ...(this._page !== undefined && { page: this._page }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
+            ...(this.windowMode && { windowMode: this.windowMode }),
         };
     }
     async goto(url, options) {