@agentrhq/webcmd 0.2.0 → 0.2.2

package/dist/src/constants.js

@@ -1,16 +1,9 @@
 /**
  * Shared constants used across explore, synthesize, and pipeline modules.
  */
-import { CLI_COMMAND, DAEMON_HEADER_NAME, ENV_PREFIX, PRODUCT_DISPLAY_NAME } from './brand.js';
-/** Default daemon port for HTTP/WebSocket communication with browser extension */
-export const DEFAULT_DAEMON_PORT = 19825;
-export function unsupportedDaemonPortEnvMessage(value) {
-    const envName = `${ENV_PREFIX}_DAEMON_PORT`;
-    const suffix = value ? ` (received ${value})` : '';
-    return `${envName} is no longer supported${suffix}. ` +
-        `The ${PRODUCT_DISPLAY_NAME} Chrome extension can only connect to localhost:${DEFAULT_DAEMON_PORT}. ` +
-        `Unset ${envName} and rerun ${CLI_COMMAND}.`;
-}
+import { DAEMON_HEADER_NAME } from './brand.js';
+/** Default daemon port for HTTP communication with the browser runtime. */
+export const DEFAULT_DAEMON_PORT = 9777;
 export { DAEMON_HEADER_NAME };
 /** URL query params that are volatile/ephemeral and should be stripped from patterns */
 export const VOLATILE_PARAMS = new Set([

package/dist/src/daemon.js

@@ -1,13 +1,9 @@
-import { DEFAULT_DAEMON_PORT, unsupportedDaemonPortEnvMessage } from './constants.js';
+import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { EXIT_CODES } from './errors.js';
 import { log } from './logger.js';
 import { PKG_VERSION } from './version.js';
 import { createDaemonServer } from './daemon/server.js';
 import { LocalCloakRuntimeProvider } from './browser/runtime/local-cloak/provider.js';
-if (process.env.WEBCMD_DAEMON_PORT) {
-    log.error(unsupportedDaemonPortEnvMessage(process.env.WEBCMD_DAEMON_PORT));
-    process.exit(EXIT_CODES.USAGE_ERROR);
-}
 const provider = new LocalCloakRuntimeProvider();
 const daemon = createDaemonServer(provider, { port: DEFAULT_DAEMON_PORT, host: '127.0.0.1', version: PKG_VERSION });
 daemon.listen().then(() => {

package/dist/src/discovery.js

@@ -211,6 +211,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                 source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
                 navigateBefore: entry.navigateBefore,
                 siteSession: entry.siteSession,
+                freshPage: entry.freshPage,
                 defaultWindowMode: entry.defaultWindowMode,
                 _lazy: true,
                 _modulePath: modulePath,

package/dist/src/doctor.js

@@ -93,6 +93,18 @@ export async function runBrowserDoctor(opts = {}) {
     if (!connectivity.ok) {
         issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
     }
+    const profileConfig = loadProfileConfig();
+    const staleDefault = profileConfig.defaultContextId;
+    if (staleDefault && profiles?.length && !profiles.some((p) => p.contextId === staleDefault)) {
+        const alias = aliasForContextId(profileConfig, staleDefault);
+        const label = alias ? `${alias} (${staleDefault})` : staleDefault;
+        const fallbackNote = profiles.length === 1
+            ? `Commands currently fall back to the only active profile: ${profiles[0].contextId}.`
+            : 'Multiple profiles are active, so commands will ask you to choose.';
+        issues.push(`Default Cloak profile is not active: ${label}.\n` +
+            `  ${fallbackNote}\n` +
+            '  Refresh it with: webcmd profile list, then webcmd profile use <name>.');
+    }
     if (adapterShadows.length > 0) {
         issues.push(formatAdapterShadowIssue(adapterShadows));
     }

package/dist/src/doctor.test.js

@@ -49,7 +49,7 @@ describe('doctor report rendering', () => {
             runtimeVersion: '1.6.8',
             issues: [],
         }));
-        expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('[OK] Daemon: running on port 9777');
         expect(text).toContain('(v1.7.9)');
         expect(text).toContain('[OK] Runtime: Cloak connected (v1.6.8)');
         expect(text).toContain('Everything looks good!');
@@ -66,7 +66,7 @@ describe('doctor report rendering', () => {
             runtimeVersion: '1.0.3',
             issues: ['Stale daemon detected: daemon v1.7.6 != CLI v1.7.9.\n  Run: webcmd daemon restart'],
         }));
-        expect(text).toContain('[WARN] Daemon: running on port 19825 (v1.7.6, stale; CLI v1.7.9)');
+        expect(text).toContain('[WARN] Daemon: running on port 9777 (v1.7.6, stale; CLI v1.7.9)');
         expect(text).toContain('Run: webcmd daemon restart');
         expect(text).not.toContain('Everything looks good!');
     });
@@ -86,7 +86,7 @@ describe('doctor report rendering', () => {
             runtimeConnected: false,
             issues: ['Daemon is running but the Cloak runtime is not connected.'],
         }));
-        expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('[OK] Daemon: running on port 9777');
         expect(text).toContain('[MISSING] Runtime: Cloak not connected');
     });
     it('renders OK when the connected Cloak runtime version is unknown', () => {
@@ -157,6 +157,33 @@ describe('doctor report rendering', () => {
             expect.stringContaining('Daemon is not running'),
         ]));
     });
+    it('reports a stale default Cloak profile when it is not active', async () => {
+        const fs = await import('node:fs');
+        const os = await import('node:os');
+        const path = await import('node:path');
+        const configDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-doctor-profile-'));
+        fs.writeFileSync(path.join(configDir, 'browser-profiles.json'), JSON.stringify({ version: 1, aliases: { work: 'profile-default' }, defaultContextId: 'profile-default' }));
+        vi.stubEnv('WEBCMD_CONFIG_DIR', configDir);
+        try {
+            mockGetDaemonHealth.mockResolvedValueOnce({
+                state: 'ready',
+                status: {
+                    runtimeConnected: true,
+                    runtimeName: 'Cloak',
+                    profiles: [{ contextId: 'active-profile', runtimeConnected: true, pending: 0 }],
+                },
+            });
+            const report = await runBrowserDoctor();
+            expect(report.issues).toEqual(expect.arrayContaining([
+                expect.stringContaining('Default Cloak profile is not active: work (profile-default)'),
+            ]));
+            expect(report.issues.join('\n')).toContain('fall back to the only active profile: active-profile');
+        }
+        finally {
+            vi.unstubAllEnvs();
+            fs.rmSync(configDir, { recursive: true, force: true });
+        }
+    });
     it('reports flapping when live check succeeds but final status shows runtime disconnected', async () => {
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'no-runtime', status: { runtimeConnected: false, runtimeName: 'Cloak' } });
         const report = await runBrowserDoctor();

package/dist/src/engine.test.js

@@ -3,6 +3,7 @@ import { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdap
 import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
 import { clearAllHooks, onAfterExecute } from './hooks.js';
+import * as runtime from './runtime.js';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -71,6 +72,67 @@ cli({
             await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
         }
     });
+    it('preserves freshPage from manifest before lazy command import', async () => {
+        const site = `manifest-fresh-${Date.now()}`;
+        const tempBuildRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-manifest-fresh-'));
+        const distDir = path.join(tempBuildRoot, 'dist');
+        const siteDir = path.join(distDir, site);
+        const commandPath = path.join(siteDir, 'checkout.js');
+        const manifestPath = path.join(tempBuildRoot, 'cli-manifest.json');
+        const sessionOpts = [];
+        const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(manifestPath, `${JSON.stringify([
+                {
+                    site,
+                    name: 'checkout',
+                    description: 'fresh checkout',
+                    access: 'write',
+                    strategy: 'public',
+                    browser: true,
+                    args: [],
+                    type: 'js',
+                    modulePath: `${site}/checkout.js`,
+                    sourceFile: `${site}/checkout.js`,
+                    siteSession: 'persistent',
+                    freshPage: true,
+                },
+            ], null, 2)}\n`);
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
+cli({
+  site: '${site}',
+  name: 'checkout', access: 'write',
+  description: 'fresh checkout',
+  browser: true,
+  strategy: Strategy.PUBLIC,
+  siteSession: 'persistent',
+  freshPage: true,
+  func: async () => [{ ok: true }],
+});
+`);
+            await discoverClis(distDir);
+            const cmd = getRegistry().get(`${site}/checkout`);
+            expect(cmd?.freshPage).toBe(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+                sessionOpts.push(opts ?? {});
+                return fn(mockPage);
+            });
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true }]);
+            expect(sessionOpts).toHaveLength(1);
+            expect(sessionOpts[0]).toMatchObject({
+                session: `site:${site}`,
+                siteSession: 'persistent',
+                freshPage: true,
+            });
+        }
+        finally {
+            vi.restoreAllMocks();
+            getRegistry().delete(`${site}/checkout`);
+            await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
+        }
+    });
     it('loads user CLI modules via package exports symlink', async () => {
         const tempWebcmdRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-user-clis-'));
         const userClisDir = path.join(tempWebcmdRoot, 'clis');

package/dist/src/execution.js

@@ -18,7 +18,7 @@ import { executePipeline } from './pipeline/index.js';
 import { adapterLoadError, ArgumentError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
-import { resolveProfileContextId } from './browser/profile.js';
+import { profileRouteParams, resolveProfileSelection } from './browser/profile.js';
 import { setDaemonCommandTimeoutSeconds } from './browser/daemon-client.js';
 import { emitHook } from './hooks.js';
 import { log } from './logger.js';
@@ -211,7 +211,9 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                 }
             }
             const BrowserFactory = getBrowserFactory(cmd.site);
-            const contextId = resolveProfileContextId(opts.profile);
+            const profileSelection = resolveProfileSelection(opts.profile);
+            const profileRouting = profileRouteParams(profileSelection);
+            const contextId = profileSelection?.contextId;
             const internal = cmd;
             const siteSession = resolveSiteSession(cmd, opts.siteSession);
             const session = resolveAdapterBrowserSession(cmd, siteSession);
@@ -332,7 +334,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { session, cdpEndpoint, contextId, windowMode, surface: 'adapter', siteSession });
+            }, { session, cdpEndpoint, ...profileRouting, windowMode, surface: 'adapter', siteSession, freshPage: cmd.freshPage === true && siteSession === 'persistent' });
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes

package/dist/src/external.js

@@ -161,16 +161,34 @@ export function executeExternalCli(name, args, preloaded) {
         }
     }
     // 3. Passthrough execution with stdio inherited
-    const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
+    const result = spawnPassthrough(cli.binary, args);
     if (result.error) {
         log.error(`Failed to execute '${cli.binary}': ${result.error.message}`);
         process.exitCode = EXIT_CODES.GENERIC_ERROR;
         return;
     }
+    if (result.signal) {
+        process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        return;
+    }
     if (result.status !== null) {
         process.exitCode = result.status;
     }
 }
+function quoteForCmdShell(token) {
+    if (token !== '' && !/[\s"^&|<>%()]/.test(token))
+        return token;
+    return `"${token.replace(/"/g, '""')}"`;
+}
+function spawnPassthrough(binary, args) {
+    const direct = spawnSync(binary, args, { stdio: 'inherit' });
+    const errorCode = direct.error?.code;
+    if (os.platform() === 'win32' && (errorCode === 'EINVAL' || errorCode === 'ENOENT')) {
+        const command = [binary, ...args].map(quoteForCmdShell).join(' ');
+        return spawnSync(command, { stdio: 'inherit', shell: true });
+    }
+    return direct;
+}
 export function registerExternalCli(name, opts) {
     const userPath = getUserRegistryPath();
     const configDir = path.dirname(userPath);

package/dist/src/external.test.js

@@ -18,7 +18,8 @@ vi.mock('node:os', async () => {
         platform: mockPlatform,
     };
 });
-import { formatExternalCliLabel, installExternalCli, parseCommand } from './external.js';
+import { spawnSync } from 'node:child_process';
+import { executeExternalCli, formatExternalCliLabel, installExternalCli, parseCommand } from './external.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 describe('parseCommand', () => {
     it('splits binaries and quoted arguments without invoking a shell', () => {
@@ -93,3 +94,38 @@ describe('installExternalCli', () => {
         expect(mockExecFileSync).toHaveBeenCalledTimes(1);
     });
 });
+describe('executeExternalCli passthrough', () => {
+    const spawnMock = vi.mocked(spawnSync);
+    const cli = { name: 'tg', binary: 'tg', description: '' };
+    beforeEach(() => {
+        spawnMock.mockReset();
+        mockExecFileSync.mockReset();
+        mockExecFileSync.mockReturnValue(Buffer.from(''));
+        mockPlatform.mockReturnValue('darwin');
+        process.exitCode = undefined;
+    });
+    it('retries through the shell on Windows when the binary is a .cmd shim', () => {
+        mockPlatform.mockReturnValue('win32');
+        const einval = Object.assign(new Error('spawnSync tg EINVAL'), { code: 'EINVAL' });
+        spawnMock
+            .mockReturnValueOnce({ error: einval, status: null, signal: null })
+            .mockReturnValueOnce({ status: 0, signal: null });
+        executeExternalCli('tg', ['send', 'hello world', '--to', 'a"b'], [cli]);
+        expect(spawnMock).toHaveBeenCalledTimes(2);
+        expect(spawnMock).toHaveBeenNthCalledWith(1, 'tg', ['send', 'hello world', '--to', 'a"b'], { stdio: 'inherit' });
+        expect(spawnMock).toHaveBeenNthCalledWith(2, 'tg send "hello world" --to "a""b"', { stdio: 'inherit', shell: true });
+        expect(process.exitCode).toBe(0);
+    });
+    it('does not retry through the shell on non-Windows platforms', () => {
+        const einval = Object.assign(new Error('spawnSync tg EINVAL'), { code: 'EINVAL' });
+        spawnMock.mockReturnValueOnce({ error: einval, status: null, signal: null });
+        executeExternalCli('tg', [], [cli]);
+        expect(spawnMock).toHaveBeenCalledTimes(1);
+        expect(process.exitCode).toBe(1);
+    });
+    it('reports a non-zero exit code when the child dies from a signal', () => {
+        spawnMock.mockReturnValueOnce({ status: null, signal: 'SIGKILL' });
+        executeExternalCli('tg', [], [cli]);
+        expect(process.exitCode).toBe(1);
+    });
+});

package/dist/src/main.js

@@ -21,7 +21,6 @@ import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 import { PKG_VERSION } from './version.js';
 import { EXIT_CODES } from './errors.js';
 import { isSupportedNodeVersion, MIN_SUPPORTED_NODE_MAJOR } from './runtime-detect.js';
-import { unsupportedDaemonPortEnvMessage } from './constants.js';
 import { CONFIG_DIR_NAME } from './brand.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -41,10 +40,6 @@ if (typeof globalThis.Bun === 'undefined' && !isSupportedNodeVersion(process.ver
     ].join('\n'));
     process.exit(EXIT_CODES.CONFIG_ERROR);
 }
-if (process.env.WEBCMD_DAEMON_PORT) {
-    process.stderr.write(`error: ${unsupportedDaemonPortEnvMessage(process.env.WEBCMD_DAEMON_PORT)}\n`);
-    process.exit(EXIT_CODES.CONFIG_ERROR);
-}
 // Fast path: --version (only when it's the top-level intent, not passed to a subcommand)
 // e.g. `webcmd --version` or `webcmd -V`, but NOT `webcmd gh --version`
 if (argv[0] === '--version' || argv[0] === '-V') {

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

@@ -38,6 +38,8 @@ export interface ManifestEntry {
     navigateBefore?: boolean | string;
     /** Site session lifecycle defaults — see CliCommand.siteSession */
     siteSession?: 'ephemeral' | 'persistent';
+    /** Fresh page behavior for persistent site sessions — see CliCommand.freshPage */
+    freshPage?: boolean;
     /** Default browser window visibility — see CliCommand.defaultWindowMode */
     defaultWindowMode?: 'foreground' | 'background';
 }

package/dist/src/node-network.test.js

@@ -22,9 +22,9 @@ describe('node network proxy decisions', () => {
     });
     it('bypasses proxies for loopback addresses', () => {
         const env = { https_proxy: 'http://127.0.0.1:7897', http_proxy: 'http://127.0.0.1:7897' };
-        expect(decideProxy(new URL('http://127.0.0.1:19825/status'), env)).toEqual({ mode: 'direct' });
-        expect(decideProxy(new URL('http://localhost:19825/status'), env)).toEqual({ mode: 'direct' });
-        expect(decideProxy(new URL('http://[::1]:19825/status'), env)).toEqual({ mode: 'direct' });
+        expect(decideProxy(new URL('http://127.0.0.1:9777/status'), env)).toEqual({ mode: 'direct' });
+        expect(decideProxy(new URL('http://localhost:9777/status'), env)).toEqual({ mode: 'direct' });
+        expect(decideProxy(new URL('http://[::1]:9777/status'), env)).toEqual({ mode: 'direct' });
     });
     it('honors NO_PROXY domain matches', () => {
         const decision = decideProxy(new URL('https://api.example.com/v1/items'), {

package/dist/src/registry.d.ts

@@ -63,6 +63,16 @@ interface BaseCliCommand {
     navigateBefore?: boolean | string;
     /** Site session lifecycle for adapter commands. */
     siteSession?: SiteSessionMode;
+    /**
+     * Start this command on a freshly created page even when the persistent
+     * site session already has a leased tab. The old tab is closed and a new
+     * one opened under the same lease, so profile state (cookies, localStorage,
+     * login, location) survives while stale DOM (leftover modals, drawers,
+     * half-finished flows from earlier commands) is discarded. Requires
+     * `siteSession: 'persistent'` — ephemeral sessions always start fresh, so
+     * combining them is a contradiction and fails at registration.
+     */
+    freshPage?: boolean;
     /** Default browser window mode for commands whose UX requires visibility. */
     defaultWindowMode?: 'foreground' | 'background';
     /** Override the default CLI output format when the user does not pass -f/--format. */

package/dist/src/registry.js

@@ -29,6 +29,7 @@ export function cli(opts) {
         validateArgs: opts.validateArgs,
         navigateBefore: opts.navigateBefore,
         siteSession: opts.siteSession,
+        freshPage: opts.freshPage,
         defaultWindowMode: opts.defaultWindowMode,
         defaultFormat: opts.defaultFormat,
         authStatus: opts.authStatus,
@@ -86,12 +87,13 @@ function assertCommandAccess(cmd) {
     throw new Error(`Command ${key} must declare access: 'read' | 'write'`);
 }
 function assertSiteSession(cmd) {
-    if (cmd.siteSession === undefined)
-        return;
     const key = `${cmd.site}/${cmd.name}`;
-    if (cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
+    if (cmd.siteSession !== undefined && cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
         throw new Error(`Command ${key} siteSession must be one of: ephemeral, persistent`);
     }
+    if (cmd.freshPage === true && cmd.siteSession !== 'persistent') {
+        throw new Error(`Command ${key} freshPage requires siteSession: 'persistent' — ephemeral sessions already start on a fresh page`);
+    }
 }
 export function registerCommand(cmd) {
     const normalized = normalizeCommand(cmd);

package/dist/src/registry.test.js

@@ -19,6 +19,31 @@ describe('cli() registration', () => {
         expect(cmd.browser).toBe(false);
         expect(cmd.args).toEqual([]);
     });
+    it('accepts freshPage with a persistent site session', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'fresh-ok', access: 'write',
+            description: 'test',
+            siteSession: 'persistent',
+            freshPage: true,
+        });
+        expect(cmd.freshPage).toBe(true);
+    });
+    it('rejects freshPage without a persistent site session', () => {
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'fresh-bad', access: 'write',
+            description: 'test',
+            freshPage: true,
+        })).toThrow(/freshPage requires siteSession: 'persistent'/);
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'fresh-bad-ephemeral', access: 'write',
+            description: 'test',
+            siteSession: 'ephemeral',
+            freshPage: true,
+        })).toThrow(/freshPage requires siteSession: 'persistent'/);
+    });
     it('puts registered command in the registry', () => {
         cli({
             site: 'test-registry',

package/dist/src/runtime-identity.test.js

@@ -1,6 +1,5 @@
 import { describe, expect, it } from 'vitest';
 import * as path from 'node:path';
-import { unsupportedDaemonPortEnvMessage } from './constants.js';
 import { getUserWebcmdDir, getUserClisDir, getPluginsDir } from './discovery.js';
 describe('webcmd runtime identity', () => {
     it('uses webcmd runtime directories', async () => {
@@ -8,11 +7,4 @@ describe('webcmd runtime identity', () => {
         expect(getUserClisDir('/home/tester')).toBe(path.join('/home/tester', '.webcmd', 'clis'));
         expect(getPluginsDir('/home/tester')).toBe(path.join('/home/tester', '.webcmd', 'plugins'));
     });
-    it('reports unsupported daemon port with WEBCMD env names', () => {
-        const legacyEnvName = ['OPEN', 'CLI_DAEMON_PORT'].join('');
-        expect(unsupportedDaemonPortEnvMessage('1234')).toContain('WEBCMD_DAEMON_PORT');
-        expect(unsupportedDaemonPortEnvMessage('1234')).toContain('Webcmd');
-        expect(unsupportedDaemonPortEnvMessage('1234')).toContain('rerun webcmd');
-        expect(unsupportedDaemonPortEnvMessage('1234')).not.toContain(legacyEnvName);
-    });
 });

package/dist/src/runtime.d.ts

@@ -29,10 +29,12 @@ export interface IBrowserFactory {
         session?: string;
         cdpEndpoint?: string;
         contextId?: string;
+        preferredContextId?: string;
         idleTimeout?: number;
         windowMode?: BrowserWindowMode;
         surface?: BrowserSurface;
         siteSession?: 'ephemeral' | 'persistent';
+        freshPage?: boolean;
     }): Promise<IPage>;
     close(): Promise<void>;
 }
@@ -40,8 +42,10 @@ export declare function browserSession<T>(BrowserFactory: new () => IBrowserFact
     session?: string;
     cdpEndpoint?: string;
     contextId?: string;
+    preferredContextId?: string;
     idleTimeout?: number;
     windowMode?: BrowserWindowMode;
     surface?: BrowserSurface;
     siteSession?: 'ephemeral' | 'persistent';
+    freshPage?: boolean;
 }): Promise<T>;

package/dist/src/runtime.js

@@ -41,10 +41,12 @@ export async function browserSession(BrowserFactory, fn, opts = {}) {
             session: opts.session,
             cdpEndpoint: opts.cdpEndpoint,
             contextId: opts.contextId,
+            preferredContextId: opts.preferredContextId,
             idleTimeout: opts.idleTimeout,
             windowMode: opts.windowMode,
             surface: opts.surface,
             siteSession: opts.siteSession,
+            freshPage: opts.freshPage,
         });
         return await fn(page);
     }

package/dist/src/skills.d.ts

@@ -4,11 +4,29 @@ export interface WebcmdSkillInfo {
     version: string;
     path: string;
 }
-export interface WebcmdSkillReadResult {
-    skill: string;
-    path: string;
-    content: string;
+export interface WebcmdSkillInstallOptions {
+    provider?: string;
+    scope?: string;
+    customPath?: string;
+    packageRoot?: string;
+    homeDir?: string;
+    cwd?: string;
+}
+export interface WebcmdSkillLink {
+    name: string;
+    source: string;
+    stableLink: string;
+    destination?: string;
+}
+export interface WebcmdSkillInstallResult {
+    provider?: SkillProvider;
+    scope?: SkillScope;
+    skills: WebcmdSkillLink[];
 }
+type SkillProvider = 'agents' | 'codex' | 'claude';
+type SkillScope = 'user' | 'project';
 export declare function getSkillsRoot(packageRoot?: string): string;
 export declare function listWebcmdSkills(packageRoot?: string): WebcmdSkillInfo[];
-export declare function readWebcmdSkill(target: string, relpath?: string, packageRoot?: string): WebcmdSkillReadResult;
+export declare function installWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export declare function updateWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export {};