@nuanu-ai/agentbrowse 0.2.22 → 0.2.23

package/README.md

@@ -47,6 +47,16 @@ agentbrowse launch https://example.com
 agentbrowse launch https://example.com --headless
 ```
 
+By default, `launch` runs in headful mode. Use `--headless` only when you
+intentionally want a hidden browser:
+
+```bash
+agentbrowse launch https://example.com --headless
+```
+
+If you want to state the default mode explicitly in scripts, use
+`--headful`.
+
 Navigate current session:
 
 ```bash

package/dist/commands/close.d.ts

@@ -1,5 +1,16 @@
 /**
  * browse close — Close the browser and clean up session.
  */
-export declare function close(): Promise<void>;
+export type CloseSuccessResult = {
+    success: true;
+};
+export type CloseFailureResult = {
+    success: false;
+    error: 'browser_close_failed';
+    outcomeType: 'blocked';
+    message: 'Browser close failed.';
+    reason: string;
+};
+export type CloseResult = CloseSuccessResult | CloseFailureResult;
+export declare function close(): Promise<CloseResult>;
 //# sourceMappingURL=close.d.ts.map

package/dist/commands/close.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close.d.ts","sourceRoot":"","sources":["../../src/commands/close.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,wBAAsB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B3C"}
+{"version":3,"file":"close.d.ts","sourceRoot":"","sources":["../../src/commands/close.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,sBAAsB,CAAC;IAC9B,WAAW,EAAE,SAAS,CAAC;IACvB,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAMlE,wBAAsB,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,CAwBlD"}

package/dist/commands/close.js

@@ -1,32 +1,30 @@
 /**
  * browse close — Close the browser and clean up session.
  */
-import { execSync } from 'node:child_process';
-import { loadSession, deleteSession, getSessionPort } from '../session.js';
-import { outputJSON, info } from '../output.js';
+import { loadSession, deleteSession } from '../session.js';
+import { info } from '../output.js';
+import { terminateOwnedPid } from '../owned-process.js';
+function isOwnedSessionRecord(session) {
+    return session?.identity?.ownership === 'agentbrowse';
+}
 export async function close() {
     const session = loadSession();
-    const port = getSessionPort(session);
-    // Kill Chrome on the current session CDP port regardless of session state
-    try {
-        const out = execSync(`lsof -ti :${port}`, { encoding: 'utf-8' }).trim();
-        if (out) {
-            for (const pid of out.split('\n')) {
-                try {
-                    process.kill(Number(pid), 'SIGTERM');
-                }
-                catch {
-                    /* already dead */
-                }
-            }
-            info(`Killed Chrome on port ${port}`);
+    if (isOwnedSessionRecord(session)) {
+        const termination = await terminateOwnedPid(session.pid);
+        if (termination === 'still_alive') {
+            info(`Owned browser pid ${session.pid} did not exit; keeping session record`);
+            return {
+                success: false,
+                error: 'browser_close_failed',
+                outcomeType: 'blocked',
+                message: 'Browser close failed.',
+                reason: `Owned browser pid ${session.pid} did not exit after SIGTERM/SIGKILL.`,
+            };
         }
-    }
-    catch {
-        /* no process on port */
+        info(`Killed owned browser pid ${session.pid}`);
     }
     if (session) {
         deleteSession();
     }
-    outputJSON({ success: true });
+    return { success: true };
 }

package/dist/commands/launch.d.ts

@@ -1,10 +1,31 @@
 /**
  * browse launch [url] — Start browser session, optionally navigate.
  */
+import type { SecretCatalogSummary } from '../secrets/catalog-sync.js';
 export type LaunchCliOptions = {
     compact?: boolean;
     profile?: string;
     headless?: boolean;
+    proxy?: string;
+    noProxy?: boolean;
 };
-export declare function launch(url?: string, opts?: LaunchCliOptions): Promise<void>;
+export type LaunchSuccessResult = {
+    success: true;
+    runtime: 'managed';
+    captchaSolveCapable: true;
+    profile: string;
+    cdpUrl: string;
+    url: string;
+    title: string;
+    secretCatalog?: SecretCatalogSummary;
+};
+export type LaunchFailureResult = {
+    success: false;
+    error: 'browser_launch_failed';
+    outcomeType: 'blocked';
+    message: 'Browser launch failed.';
+    reason: string;
+};
+export type LaunchResult = LaunchSuccessResult | LaunchFailureResult;
+export declare function launch(url?: string, opts?: LaunchCliOptions): Promise<LaunchResult>;
 //# sourceMappingURL=launch.d.ts.map

package/dist/commands/launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/commands/launch.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsBH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,wBAAsB,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQjF"}
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../../src/commands/launch.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAWvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,SAAS,CAAC;IACnB,mBAAmB,EAAE,IAAI,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,oBAAoB,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,uBAAuB,CAAC;IAC/B,WAAW,EAAE,SAAS,CAAC;IACvB,OAAO,EAAE,wBAAwB,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAErE,wBAAsB,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAazF"}

package/dist/commands/launch.js

@@ -1,92 +1,112 @@
 /**
  * browse launch [url] — Start browser session, optionally navigate.
  */
-import { execSync } from 'node:child_process';
 import { readConfig } from '../solver/config.js';
 import { ensureProfile } from '../solver/profile-manager.js';
 import { launchSolver } from '../solver/browser-launcher.js';
-import { saveSession } from '../session.js';
+import { buildOwnedSession, isOwnedSession, loadSession, saveSession } from '../session.js';
 import { findChromePid } from '../stagehand.js';
-import { outputContractFailure, outputJSON } from '../output.js';
 import { applyAgentpayGatewayEnv, tryResolveAgentpayGatewayConfig } from '../agentpay-gateway.js';
 import { connectPlaywright, disconnectPlaywright, syncLaunchPage } from '../playwright-runtime.js';
 import { summarizeSecretCatalog, syncSecretCatalogForUrl } from '../secrets/catalog-sync.js';
-const CDP_PORT = 9222;
+import { terminateOwnedPid } from '../owned-process.js';
+import { info } from '../output.js';
 const DEFAULT_PROFILE = 'default';
 const COMPACT_WINDOW = {
     width: 1280,
     height: 900,
 };
 export async function launch(url, opts) {
-    await killChromeOnPort(CDP_PORT);
+    const cleanupFailure = await cleanupOwnedSession();
+    if (cleanupFailure) {
+        return cleanupFailure;
+    }
     const compact = opts?.compact ?? true;
     const profileName = opts?.profile ?? DEFAULT_PROFILE;
     const headless = opts?.headless ?? false;
-    await launchManaged(url, profileName, headless, compact);
+    const proxyOverride = opts?.proxy;
+    const noProxy = opts?.noProxy ?? false;
+    return launchManaged(url, profileName, headless, compact, proxyOverride, noProxy);
 }
-async function killChromeOnPort(port) {
-    const pids = getPidsOnPort(port);
-    if (pids.length === 0)
-        return;
-    for (const pid of pids) {
-        try {
-            process.kill(pid, 'SIGTERM');
-        }
-        catch {
-            // Skip stale PID.
-        }
+async function cleanupOwnedSession() {
+    const existingSession = loadSession();
+    if (!isOwnedSession(existingSession)) {
+        return null;
     }
-    for (let i = 0; i < 20; i++) {
-        if (getPidsOnPort(port).length === 0)
-            return;
-        await sleep(100);
+    const termination = await terminateOwnedPid(existingSession.pid);
+    if (termination === 'still_alive') {
+        return buildLaunchFailure(new Error(`Existing owned browser pid ${existingSession.pid} did not exit after SIGTERM/SIGKILL.`));
     }
-    for (const pid of getPidsOnPort(port)) {
-        try {
-            process.kill(pid, 'SIGKILL');
-        }
-        catch {
-            // Skip stale PID.
+    return null;
+}
+function buildLaunchFailure(err) {
+    return {
+        success: false,
+        error: 'browser_launch_failed',
+        outcomeType: 'blocked',
+        message: 'Browser launch failed.',
+        reason: formatUnknownError(err),
+    };
+}
+function getPortFromCdpUrl(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        if (!url.port) {
+            return undefined;
         }
+        const port = Number(url.port);
+        return Number.isFinite(port) && port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
     }
 }
-async function launchManaged(url, profileName, headless, compact) {
+async function launchManaged(url, profileName, headless, compact, proxyOverride, noProxy = false) {
     let session;
     let browser = null;
     let secretCatalogSummary;
     try {
-        const profile = ensureProfile(profileName);
+        const baseProfile = ensureProfile(profileName);
         const config = readConfig();
+        const runtimeProxy = resolveLaunchProxy({
+            profileProxy: baseProfile.fingerprint.proxy,
+            configProxy: config.defaults?.proxy,
+            cliProxy: proxyOverride,
+            noProxy,
+        });
+        const profile = withLaunchProxy(baseProfile, runtimeProxy);
         const gateway = tryResolveAgentpayGatewayConfig();
         if (gateway) {
             applyAgentpayGatewayEnv(gateway);
         }
+        if (runtimeProxy) {
+            info(`[launch] starting browser with proxy ${runtimeProxy.server}`);
+        }
         session = await launchSolver(profile, {
             headless: headless || config.defaults?.headless,
             url,
-            cdpPort: CDP_PORT,
+            cdpPort: undefined,
             windowSize: compact ? COMPACT_WINDOW : undefined,
         });
     }
     catch (err) {
-        outputContractFailure({
-            error: 'browser_launch_failed',
-            outcomeType: 'blocked',
-            message: 'Browser launch failed.',
-            reason: formatUnknownError(err),
-        });
+        return buildLaunchFailure(err);
+    }
+    const cdpPort = getPortFromCdpUrl(session.cdpUrl);
+    const chromePid = findChromePid(cdpPort);
+    if (!chromePid) {
+        await session.close().catch(() => undefined);
+        return buildLaunchFailure(new Error('Launched browser PID could not be resolved.'));
     }
-    const chromePid = findChromePid(CDP_PORT) ?? process.pid;
-    const persistedSession = {
+    const persistedSession = buildOwnedSession({
         cdpUrl: session.cdpUrl,
         pid: chromePid,
-        port: CDP_PORT,
         profile: profileName,
         launchedAt: new Date().toISOString(),
         capabilities: {
             captchaSolve: true,
         },
-    };
+    });
     saveSession(persistedSession);
     let currentUrl = session.page.url();
     let title = await session.page.title().catch(() => '');
@@ -111,10 +131,12 @@ async function launchManaged(url, profileName, headless, compact) {
     }
     if (url) {
         const snapshot = await syncSecretCatalogForUrl(persistedSession, currentUrl || url);
-        secretCatalogSummary = summarizeSecretCatalog(snapshot);
+        if (snapshot) {
+            secretCatalogSummary = summarizeSecretCatalog(snapshot);
+        }
     }
     saveSession(persistedSession);
-    outputJSON({
+    return {
         success: true,
         runtime: 'managed',
         captchaSolveCapable: true,
@@ -123,21 +145,7 @@ async function launchManaged(url, profileName, headless, compact) {
         url: currentUrl,
         title,
         secretCatalog: secretCatalogSummary,
-    });
-}
-function getPidsOnPort(port) {
-    try {
-        const out = execSync(`lsof -ti :${port}`, { encoding: 'utf-8' }).trim();
-        if (!out)
-            return [];
-        return out
-            .split('\n')
-            .map((value) => Number(value))
-            .filter((value) => Number.isFinite(value) && value > 0);
-    }
-    catch {
-        return [];
-    }
+    };
 }
 function formatUnknownError(err) {
     if (err instanceof Error)
@@ -154,6 +162,61 @@ function formatUnknownError(err) {
     }
     return String(err);
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function resolveLaunchProxy(options) {
+    if (options.noProxy) {
+        return undefined;
+    }
+    if (options.cliProxy) {
+        return normalizeProxySetting(options.cliProxy);
+    }
+    if (options.configProxy) {
+        return normalizeProxySetting(options.configProxy);
+    }
+    if (options.profileProxy) {
+        return normalizeProxySetting(options.profileProxy);
+    }
+    return undefined;
+}
+function withLaunchProxy(profile, proxy) {
+    return {
+        ...profile,
+        fingerprint: {
+            ...profile.fingerprint,
+            proxy,
+        },
+    };
+}
+function normalizeProxySetting(value) {
+    if (typeof value === 'string') {
+        return parseProxyString(value);
+    }
+    const normalized = parseProxyString(value.server);
+    const username = value.username?.trim() || normalized.username;
+    const password = value.password ?? normalized.password;
+    return {
+        server: normalized.server,
+        ...(username ? { username } : {}),
+        ...(password ? { password } : {}),
+    };
+}
+function parseProxyString(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error('Proxy value must not be empty.');
+    }
+    try {
+        const parsed = new URL(trimmed);
+        const server = `${parsed.protocol}//${parsed.host}`;
+        if (!parsed.hostname) {
+            throw new Error('missing hostname');
+        }
+        return {
+            server,
+            ...(parsed.username ? { username: decodeURIComponent(parsed.username) } : {}),
+            ...(parsed.password ? { password: decodeURIComponent(parsed.password) } : {}),
+        };
+    }
+    catch {
+        return { server: trimmed };
+    }
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAiPA,iBAAe,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4JhE;AAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA0QA,iBAAe,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgKhE;AAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}

package/dist/index.js

@@ -6,7 +6,7 @@ loadEnv();
 import { preflightAgentpayGateway } from './agentpay-gateway.js';
 import { browseCommand, browseCommandName } from './command-name.js';
 import { loadSession } from './session.js';
-import { outputError, fatal, info } from './output.js';
+import { outputError, outputJSON, fatal, info } from './output.js';
 function usageText() {
     return `Usage: ${browseCommandName()} <command> [args] [options]
 
@@ -32,8 +32,10 @@ Options:
   --compact                       Launch browser in compact window size (1280x900, default)
   --full                          Launch browser in full-size window
   --profile <name>                Solver profile name for launch (default: "default")
+  --proxy <url>                   Launch browser through proxy for this run only
+  --proxyless                     Ignore configured/profile proxy for this run only
+  --headful                       Explicit alias for headful browser mode (default)
   --headless                      Launch browser in headless mode
-  --no-headless                   Explicit alias for visible browser mode
   --path <file>                   Output path for screenshot
   --timeout <seconds>             Timeout for solve-captcha command (default: 90)
   --help                          Show this help message
@@ -113,13 +115,15 @@ function parseLaunchArgs(args) {
     let compact = true;
     let profile;
     let headless = false;
+    let proxy;
+    let noProxy = false;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--headless') {
             headless = true;
             continue;
         }
-        if (arg === '--no-headless') {
+        if (arg === '--headful') {
             headless = false;
             continue;
         }
@@ -134,21 +138,36 @@ function parseLaunchArgs(args) {
         if (arg === '--profile') {
             const value = args[i + 1];
             if (!value || value.startsWith('--')) {
-                outputError(`Usage: ${browseCommand('launch', '[url]', '[--profile <name>]', '[--headless]')}`);
+                outputError(`Usage: ${browseCommand('launch', '[url]', '[--profile <name>]', '[--proxy <url>|--proxyless]', '[--headful|--headless]')}`);
             }
             profile = value;
             i += 1;
             continue;
         }
+        if (arg === '--proxy') {
+            const value = args[i + 1];
+            if (!value || value.startsWith('--')) {
+                outputError(`Usage: ${browseCommand('launch', '[url]', '[--profile <name>]', '[--proxy <url>|--proxyless]', '[--headful|--headless]')}`);
+            }
+            proxy = value;
+            noProxy = false;
+            i += 1;
+            continue;
+        }
+        if (arg === '--proxyless') {
+            proxy = undefined;
+            noProxy = true;
+            continue;
+        }
         if (arg.startsWith('--')) {
             outputError(`Unknown launch option: ${arg}`);
         }
         if (url) {
-            outputError(`Usage: ${browseCommand('launch', '[url]', '[--profile <name>]', '[--headless]')}`);
+            outputError(`Usage: ${browseCommand('launch', '[url]', '[--profile <name>]', '[--proxy <url>|--proxyless]', '[--headful|--headless]')}`);
         }
         url = arg;
     }
-    return { url, compact, profile, headless };
+    return { url, compact, profile, headless, proxy, noProxy };
 }
 function parseCaptchaTimeout(args) {
     const timeoutRaw = getFlag(args, '--timeout');
@@ -220,11 +239,13 @@ async function main(argv = process.argv) {
         case 'launch': {
             const { launch } = await import('./commands/launch.js');
             const launchArgs = parseLaunchArgs(args);
-            await launch(launchArgs.url, {
+            outputJSON(await launch(launchArgs.url, {
                 compact: launchArgs.compact,
                 profile: launchArgs.profile,
                 headless: launchArgs.headless,
-            });
+                proxy: launchArgs.proxy,
+                noProxy: launchArgs.noProxy,
+            }));
             break;
         }
         case 'navigate': {
@@ -322,7 +343,7 @@ async function main(argv = process.argv) {
         }
         case 'close': {
             const { close } = await import('./commands/close.js');
-            await close();
+            outputJSON(await close());
             break;
         }
     }

package/dist/owned-process.d.ts

@@ -0,0 +1,4 @@
+export type OwnedPidTerminationResult = 'not_found' | 'terminated' | 'sigkilled' | 'still_alive';
+export declare function isPidAlive(pid: number): boolean;
+export declare function terminateOwnedPid(pid: number): Promise<OwnedPidTerminationResult>;
+//# sourceMappingURL=owned-process.d.ts.map

package/dist/owned-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owned-process.d.ts","sourceRoot":"","sources":["../src/owned-process.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,yBAAyB,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,GAAG,aAAa,CAAC;AAEjG,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAW/C;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAsBvF"}

package/dist/owned-process.js

@@ -0,0 +1,57 @@
+const TERM_WAIT_ATTEMPTS = 10;
+const TERM_WAIT_MS = 100;
+const KILL_WAIT_ATTEMPTS = 5;
+const KILL_WAIT_MS = 20;
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = getErrorCode(error);
+        if (code === 'EPERM') {
+            return true;
+        }
+        return false;
+    }
+}
+export async function terminateOwnedPid(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (error) {
+        return isPidAlive(pid) ? 'still_alive' : 'not_found';
+    }
+    if (await waitForPidExit(pid, TERM_WAIT_ATTEMPTS, TERM_WAIT_MS)) {
+        return 'terminated';
+    }
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch {
+        return isPidAlive(pid) ? 'still_alive' : 'sigkilled';
+    }
+    if (await waitForPidExit(pid, KILL_WAIT_ATTEMPTS, KILL_WAIT_MS)) {
+        return 'sigkilled';
+    }
+    return 'still_alive';
+}
+async function waitForPidExit(pid, attempts, intervalMs) {
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (!isPidAlive(pid)) {
+            return true;
+        }
+        await sleep(intervalMs);
+    }
+    return !isPidAlive(pid);
+}
+function getErrorCode(error) {
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const code = Reflect.get(error, 'code');
+    return typeof code === 'string' ? code : undefined;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/session.d.ts

@@ -19,12 +19,21 @@ export interface BrowseSession {
     launchedAt: string;
     port?: number;
     profile?: string;
+    identity?: BrowseSessionIdentity;
     capabilities?: {
         captchaSolve?: boolean;
     };
     runtime?: BrowseRuntimeState;
     transientSecretCache?: Record<string, CachedTransientSecretEntry>;
 }
+export interface BrowseSessionIdentity {
+    browserInstanceRef: string;
+    endpoint: string;
+    pid: number;
+    profile?: string;
+    launchedAt: string;
+    ownership: 'agentbrowse';
+}
 export declare function cleanupTransientSecretCache(session: BrowseSession, options?: {
     now?: string;
 }): boolean;
@@ -34,11 +43,15 @@ export declare function getCachedTransientSecret(session: BrowseSession, intentI
 }): CachedTransientSecretEntry | null;
 export declare function deleteCachedTransientSecret(session: BrowseSession, intentId: string): boolean;
 export declare function serializeSession(session: BrowseSession): string;
+export declare function buildOwnedSession(session: Omit<BrowseSession, 'port' | 'identity'>): BrowseSession;
 export declare function saveSession(session: BrowseSession): void;
 export declare function loadSession(): BrowseSession | null;
 export declare function getSessionPort(session: BrowseSession | null): number;
 export declare function deleteSession(): void;
 export declare function supportsCaptchaSolve(session: BrowseSession | null): boolean;
+export declare function isOwnedSession(session: BrowseSession | null | undefined): session is BrowseSession & {
+    identity: BrowseSessionIdentity;
+};
 /** Check if the Chrome process from the session is still alive. */
 export declare function isSessionAlive(session: BrowseSession): boolean;
 //# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAK/D,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE;QACb,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;CACnE;AAyBD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,OAAO,CAqBT;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,0BAA0B,GAChC,0BAA0B,CAQ5B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,0BAA0B,GAAG,IAAI,CAMnC;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAW7F;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAW/D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAGxD;AAED,wBAAgB,WAAW,IAAI,aAAa,GAAG,IAAI,CAclD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,CAapE;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAE3E;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAO9D"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAK/D,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,YAAY,CAAC,EAAE;QACb,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,aAAa,CAAC;CAC1B;AAkDD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,OAAO,CAqBT;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,0BAA0B,GAChC,0BAA0B,CAQ5B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,0BAA0B,GAAG,IAAI,CAMnC;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAW7F;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAW/D;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,UAAU,CAAC,GAChD,aAAa,CAaf;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAGxD;AAED,wBAAgB,WAAW,IAAI,aAAa,GAAG,IAAI,CAclD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,MAAM,CAWpE;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAE3E;AAED,wBAAgB,cAAc,CAC5B,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,SAAS,GACxC,OAAO,IAAI,aAAa,GAAG;IAAE,QAAQ,EAAE,qBAAqB,CAAA;CAAE,CAahE;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAO9D"}

package/dist/session.js

@@ -20,6 +20,30 @@ function ensureDir() {
         mkdirSync(SESSION_DIR, { recursive: true });
     }
 }
+function parseSessionPort(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        if (!url.port) {
+            return undefined;
+        }
+        const port = Number(url.port);
+        return Number.isFinite(port) && port > 0 ? port : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseBrowserInstanceRef(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        const pathSegments = url.pathname.split('/').filter(Boolean);
+        return pathSegments.at(-1) ?? cdpUrl;
+    }
+    catch {
+        const pathSegments = cdpUrl.split('/').filter(Boolean);
+        return pathSegments.at(-1) ?? cdpUrl;
+    }
+}
 function isExpired(expiresAt, now) {
     if (!expiresAt) {
         return false;
@@ -79,6 +103,20 @@ export function serializeSession(session) {
         return value;
     }, 2);
 }
+export function buildOwnedSession(session) {
+    return {
+        ...session,
+        port: parseSessionPort(session.cdpUrl),
+        identity: {
+            browserInstanceRef: parseBrowserInstanceRef(session.cdpUrl),
+            endpoint: session.cdpUrl,
+            pid: session.pid,
+            profile: session.profile,
+            launchedAt: session.launchedAt,
+            ownership: 'agentbrowse',
+        },
+    };
+}
 export function saveSession(session) {
     ensureDir();
     writeFileSync(SESSION_PATH, serializeSession(session));
@@ -105,13 +143,9 @@ export function getSessionPort(session) {
     if (session?.port)
         return session.port;
     if (session?.cdpUrl) {
-        try {
-            const url = new URL(session.cdpUrl);
-            if (url.port)
-                return Number(url.port);
-        }
-        catch {
-            // Ignore malformed cdpUrl and use default fallback.
+        const parsedPort = parseSessionPort(session.cdpUrl);
+        if (parsedPort) {
+            return parsedPort;
         }
     }
     return 9222;
@@ -123,6 +157,17 @@ export function deleteSession() {
 export function supportsCaptchaSolve(session) {
     return session?.capabilities?.captchaSolve === true;
 }
+export function isOwnedSession(session) {
+    if (!session?.identity) {
+        return false;
+    }
+    return (session.identity.ownership === 'agentbrowse' &&
+        session.identity.endpoint === session.cdpUrl &&
+        session.identity.pid === session.pid &&
+        session.identity.launchedAt === session.launchedAt &&
+        session.identity.browserInstanceRef.length > 0 &&
+        session.identity.profile === session.profile);
+}
 /** Check if the Chrome process from the session is still alive. */
 export function isSessionAlive(session) {
     try {

package/dist/solver/types.d.ts

@@ -24,6 +24,7 @@ export type ProxyConfig = {
     username?: string;
     password?: string;
 };
+export type ProxySetting = string | ProxyConfig;
 export type ProfileInfo = {
     name: string;
     fingerprint: BrowserFingerprint;
@@ -37,6 +38,7 @@ export type SolverConfig = {
     };
     defaults?: {
         headless?: boolean;
+        proxy?: ProxySetting;
     };
 };
 export type CaptchaType = 'recaptcha-v2' | 'hcaptcha' | 'turnstile';

package/dist/solver/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/solver/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,kBAAkB,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpE,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,sBAAsB,CAAC;AACrE,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,UAAU,GAAG,cAAc,CAAC;AAEjF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/solver/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,kBAAkB,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,KAAK,CAAC,EAAE,YAAY,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpE,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,sBAAsB,CAAC;AACrE,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,UAAU,GAAG,cAAc,CAAC;AAEjF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentbrowse",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "type": "module",
   "description": "Browser automation CLI for AI agents: control a CDP browser, observe UI surfaces, act on refs, extract data, capture screenshots, complete protected fills, and solve captchas",
   "keywords": [