remote-agent-browser 1.0.0 → 1.2.0

package/README.md

@@ -1,8 +1,7 @@
 # remote-agent-browser
 
-Run [agent-browser](https://github.com/vercel-labs/agent-browser) in an isolated
-[Vercel Sandbox](https://vercel.com/docs/vercel-sandbox). Chromium and the CLI
-come preinstalled, so there is no browser or Docker setup at runtime.
+Run [agent-browser](https://github.com/vercel-labs/agent-browser) in the cloud
+with an isolated [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox).
 
 ## Install
 
@@ -22,6 +21,10 @@ references. `close()` closes Chromium and stops the Sandbox.
   PNG and save it locally.
 - [Agent Bash tool integration](./examples/agent-bash-tool/README.md) — let an
   agent use normal `agent-browser <command>` invocations through its Bash tool.
+- [Bypass BotID for trusted automation](./examples/botid-bypass/README.md) —
+  pass a Vercel automation bypass token as an origin-scoped header.
+- [Route traffic through a proxy](./examples/proxy/README.md) — configure an
+  authenticated proxy and verify the browser's egress address.
 
 ## Authentication
 
@@ -45,7 +48,7 @@ Starts a fresh browser in a disposable Vercel Sandbox. Always call
 
 Pass agent-browser global options with `args`. They are placed before
 every command, which is required for launch settings such as color scheme,
-profiles, proxies, and init scripts:
+profiles, and init scripts:
 
 ```ts
 const browser = await AgentBrowser.create({
@@ -53,6 +56,28 @@ const browser = await AgentBrowser.create({
 })
 ```
 
+### Proxy
+
+Set a proxy for the browser client's lifetime with `proxy`. Use the object form
+to configure hosts that should connect directly:
+
+```ts
+const browser = await AgentBrowser.create({
+  proxy: {
+    url: 'http://user:password@proxy.example.com:8080',
+    bypass: ['localhost', '*.internal.example.com'],
+  },
+})
+```
+
+For a proxy without bypass rules, pass its URL directly:
+
+```ts
+const browser = await AgentBrowser.create({
+  proxy: 'http://proxy.example.com:8080',
+})
+```
+
 ### `browser.run(commands)`
 
 Run several agent-browser commands in the same session:
@@ -77,6 +102,25 @@ await browser.exec('find', {
 })
 ```
 
+### `browser.shell(command, options?)`
+
+Use this when forwarding a Bash-tool command or composing `agent-browser` with
+normal shell utilities. The command runs verbatim, so quoting, pipes,
+redirection, and control operators keep their shell semantics. Prefer `exec()`
+or `run()` for browser commands that do not need a shell. Every `agent-browser`
+invocation inherits the client's CLI session through `AGENT_BROWSER_SESSION`.
+
+```ts
+const result = await browser.shell(
+  'agent-browser read "https://example.com" | grep -io "example" | wc -l',
+)
+console.log(result.stdout)
+```
+
+Client-wide `args` are not inserted into a shell string because doing so would
+require rewriting arbitrary shell syntax. Put global CLI arguments directly in
+the command when using `shell()`.
+
 ### Typed JSON
 
 Set `output: 'json'` for commands that support `--json`. `exec<T>()` adds the
@@ -118,6 +162,17 @@ const result = await browser.exec('network', { args: ['har', 'stop'] })
 await writeFile('capture.har', result.file.bytes)
 ```
 
+When a command already contains an explicit remote output path, read it back
+without changing the command:
+
+```ts
+await browser.shell(
+  'agent-browser screenshot /tmp/verification.png',
+)
+const file = await browser.readFile('/tmp/verification.png', 'image/png')
+await writeFile('verification.png', file.bytes)
+```
+
 ### Convenience methods
 
 - `browser.snapshot(url?)` optionally opens a page, then returns its interactive
@@ -128,4 +183,59 @@ await writeFile('capture.har', result.file.bytes)
 
 All methods use the same disposable browser session until `close()` is called.
 
+### Stable browser ids
+
+Use `AgentBrowser.session()` when browser identity must survive process
+boundaries. It returns a lazy handle: constructing it or starting keepalive
+does not create a Sandbox. The first browser command finds or creates a runtime
+derived from the caller-defined id, and another process using the same id finds
+that runtime again.
+
+```ts
+const browser = AgentBrowser.session({ id: `environment:${chatId}` })
+const stopKeepalive = browser.keepalive()
+try {
+  await browser.exec('open', { args: ['https://example.com'] })
+} finally {
+  stopKeepalive()
+}
+```
+
+Ids are project-scoped. Include the deployment environment or another namespace
+when the same application uses one Vercel project for multiple environments.
+The underlying Sandbox name is private and derived from a hash of the id.
+
+If an expired Sandbox resumes, its Chromium process starts fresh. Subscribe to
+`reset` before running commands when the caller needs to surface that page,
+cookies, refs, tabs, and console history were lost:
+
+```ts
+browser.on('reset', ({ reason }) => {
+  console.log(`Browser runtime reset: ${reason}`)
+})
+```
+
+`browser.destroy()` permanently removes the named runtime. Stopping keepalive
+only allows its normal idle timeout to resume.
+
+### Keepalive
+
+Keep the Sandbox alive across idle gaps during long-running work. Always stop
+the heartbeat in a `finally` block; after it stops, the Sandbox expires at its
+normal timeout unless it is closed earlier:
+
+```ts
+const stopKeepalive = browser.keepalive()
+try {
+  await runLongAgentTurn(browser)
+} finally {
+  stopKeepalive()
+}
+```
+
+By default, each heartbeat restores the wall-clock timeout configured by
+`AgentBrowser.create()` and runs halfway through that window, capped at five
+minutes. Override either value with `timeoutMs` and `intervalMs`. Renewal is
+best-effort; pass `onError` to observe failures.
+
 Container image and development details are in [docs.md](./docs.md).

package/dist/index.d.ts

@@ -36,6 +36,18 @@ type BrowserRunResult = {
     results: BrowserCommandResult[];
     ok: boolean;
 };
+/** Result from a verbatim shell command running in the browser environment. */
+type BrowserShellResult = {
+    ok: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+};
+type ShellOptions = {
+    /** Named agent-browser CLI session available to commands through the environment. */
+    session?: string;
+    timeoutMs?: number;
+};
 type RunOptions = {
     /** Named session to reuse browser state across calls. Default: ephemeral. */
     session?: string;
@@ -60,13 +72,37 @@ type ExecOptions = {
 type JsonExecOptions = Omit<ExecOptions, 'output'> & {
     output: 'json';
 };
+type ProxyOptions = string | {
+    /** Proxy server URL, optionally including authentication. */
+    url: string;
+    /** Host patterns that should connect directly instead of using the proxy. */
+    bypass?: string | readonly string[];
+};
 type BrowserClientOptions = {
     session?: string;
     /** agent-browser CLI arguments inserted before every command. */
     args?: string[];
+    /** Proxy configuration fixed for this client's lifetime. */
+    proxy?: ProxyOptions;
+    /** Run `agent-browser close` before closing the runner. Default: true. */
+    closeSession?: boolean;
     /** Whether close() also tears down the command runner. Default: true. */
     ownsRunner?: boolean;
 };
+type KeepaliveOptions = {
+    /** Remaining sandbox lifetime to maintain. Defaults to its creation timeout. */
+    timeoutMs?: number;
+    /** Heartbeat cadence. Defaults to half the timeout, capped at 5 minutes. */
+    intervalMs?: number;
+    /** Optional observer for best-effort heartbeat failures. */
+    onError?: (error: unknown) => void;
+};
+type BrowserRuntimeResetEvent = {
+    /** Stable logical browser id supplied by the caller. */
+    id: string;
+    /** Why the backing runtime no longer has its previous in-memory state. */
+    reason: 'resumed';
+};
 /**
  * Minimal command executor the browser client needs. Implemented by the
  * Vercel Sandbox adapter; anything with the same shape can back a
@@ -88,6 +124,8 @@ interface CommandRunner {
     writeFile(path: string, bytes: Buffer): Promise<void>;
     /** Tear the remote environment down. */
     close(): Promise<void>;
+    /** Keep the remote environment alive until the returned stop function runs. */
+    keepalive?(opts?: KeepaliveOptions): () => void;
 }
 /** Session-oriented remote browser client. */
 interface AgentBrowser$1 {
@@ -95,6 +133,8 @@ interface AgentBrowser$1 {
     readonly session: string;
     /** Run a batch of agent-browser arg-arrays sequentially. */
     run(commands: string[][], opts?: RunOptions): Promise<BrowserRunResult>;
+    /** Run a shell command verbatim, preserving quoting and control operators. */
+    shell(command: string, opts?: ShellOptions): Promise<BrowserShellResult>;
     /** Run one command and unwrap its typed --json data payload. */
     exec<T>(command: string, opts: JsonExecOptions): Promise<BrowserCommandResult<T>>;
     /** Run one agent-browser command with text output. */
@@ -108,6 +148,8 @@ interface AgentBrowser$1 {
         file: BrowserFile;
         result: BrowserCommandResult;
     }>;
+    /** Read an explicitly named artifact from the browser environment. */
+    readFile(path: string, contentType?: string): Promise<BrowserFile>;
     /** Optionally open a URL, then return the interactive accessibility snapshot. */
     snapshot(urlOrOptions?: string | RunOptions, opts?: RunOptions): Promise<BrowserRunResult>;
     /** Optionally open a URL, then return a PNG screenshot. */
@@ -115,9 +157,23 @@ interface AgentBrowser$1 {
         png: Buffer;
         result: BrowserRunResult;
     }>;
+    /**
+     * Keep the backing Sandbox alive across idle gaps. Call the returned stop
+     * function in a finally block so the Sandbox can expire when work finishes.
+     */
+    keepalive(opts?: KeepaliveOptions): () => void;
     /** Close the browser session (and the sandbox when it owns it). */
     close(): Promise<void>;
 }
+/** A lazily acquired browser whose logical identity survives runtime expiry. */
+interface AgentBrowserSession extends AgentBrowser$1 {
+    /** Stable caller-defined identity. The backing runtime may be replaced. */
+    readonly id: string;
+    /** Observe when an expired runtime resumes with fresh in-memory browser state. */
+    on(event: 'reset', listener: (event: BrowserRuntimeResetEvent) => void): () => void;
+    /** Permanently remove the runtime currently associated with this id. */
+    destroy(): Promise<void>;
+}
 
 type CreateAgentBrowserOptions = {
     /** Named CLI session; state (page, cookies, refs) persists across calls. */
@@ -135,6 +191,12 @@ type CreateAgentBrowserOptions = {
     env?: Record<string, string>;
     /** agent-browser CLI arguments inserted before every command. */
     args?: string[];
+    /** Proxy configuration fixed for this browser's lifetime. */
+    proxy?: ProxyOptions;
+};
+type CreateAgentBrowserSessionOptions = CreateAgentBrowserOptions & {
+    /** Stable logical identity used to find this browser across processes. */
+    id: string;
 };
 /**
  * Create an agent-browser client running inside a fresh Vercel Sandbox.
@@ -159,6 +221,15 @@ type CreateAgentBrowserOptions = {
  * ```
  */
 declare function createAgentBrowser(opts?: CreateAgentBrowserOptions): Promise<AgentBrowser$1>;
+/**
+ * Create a lazy browser handle with a stable logical id.
+ *
+ * The first operation finds or creates a named Vercel Sandbox. Later handles
+ * created with the same id attach to that Sandbox, including from another
+ * process. If an expired Sandbox resumes, listeners are told that its
+ * in-memory page, refs, cookies, and console history were reset.
+ */
+declare function createAgentBrowserSession(opts: CreateAgentBrowserSessionOptions): AgentBrowserSession;
 
 /**
  * Create a session-oriented browser client over any CommandRunner.
@@ -173,8 +244,9 @@ declare function createBrowserClient(runner: CommandRunner, opts?: BrowserClient
 /** Create AgentBrowser clients backed by a fresh Vercel Sandbox. */
 declare const AgentBrowser: {
     create: typeof createAgentBrowser;
+    session: typeof createAgentBrowserSession;
 };
 type AgentBrowser = AgentBrowser$1;
 
-export { AgentBrowser, createAgentBrowser, createBrowserClient };
-export type { BrowserClientOptions, BrowserCommandResult, BrowserRunResult, CommandRunner, CreateAgentBrowserOptions, ExecOptions, JsonExecOptions, RunOptions };
+export { AgentBrowser, createAgentBrowser, createAgentBrowserSession, createBrowserClient };
+export type { AgentBrowserSession, BrowserClientOptions, BrowserCommandResult, BrowserFile, BrowserRunResult, BrowserRuntimeResetEvent, BrowserShellResult, CommandRunner, CreateAgentBrowserOptions, CreateAgentBrowserSessionOptions, ExecOptions, JsonExecOptions, KeepaliveOptions, ProxyOptions, RunOptions, ShellOptions };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'node:crypto';
+import { randomUUID, createHash } from 'node:crypto';
 import { Sandbox } from '@vercel/sandbox';
 
 const FLAGS_WITH_VALUE = new Set([
@@ -12,6 +12,39 @@ const FLAGS_WITH_VALUE = new Set([
     '--scale'
 ]);
 const SESSION_NAME = /^[\w.-]{1,64}$/;
+const PROXY_FLAGS = [
+    '--proxy',
+    '--proxy-bypass'
+];
+function proxyEnvironment(proxy) {
+    if (proxy === undefined) return undefined;
+    const url = typeof proxy === 'string' ? proxy : proxy.url;
+    const bypass = typeof proxy === 'string' ? undefined : proxy.bypass;
+    if (url.length === 0) {
+        throw new RangeError('proxy url must not be empty');
+    }
+    const env = {
+        AGENT_BROWSER_PROXY: url
+    };
+    if (bypass !== undefined) {
+        const serialized = typeof bypass === 'string' ? bypass : bypass.join(',');
+        if (serialized.length === 0) {
+            throw new RangeError('proxy bypass must not be empty');
+        }
+        env.AGENT_BROWSER_PROXY_BYPASS = serialized;
+    }
+    return env;
+}
+function hasProxyFlag(args) {
+    return args.some((arg)=>PROXY_FLAGS.some((flag)=>arg === flag || arg.startsWith(`${flag}=`)));
+}
+function proxyOutputRedactor(proxy) {
+    if (proxy === undefined) return (value)=>value;
+    const url = typeof proxy === 'string' ? proxy : proxy.url;
+    const redacted = url.replace(/^([a-z][a-z\d+.-]*:\/\/)([^/@]+)@/i, '$1***:***@');
+    if (redacted === url) return (value)=>value;
+    return (value)=>value.replaceAll(url, redacted);
+}
 function safeFilename(name) {
     const filename = name.split(/[\\/]/).at(-1)?.replace(/[^\w.-]/g, '-');
     return filename || 'file';
@@ -111,12 +144,34 @@ function outputSpec(args) {
     const clientArgs = [
         ...opts.args ?? []
     ];
+    if (opts.proxy !== undefined && hasProxyFlag(clientArgs)) {
+        throw new Error('proxy cannot be combined with --proxy or --proxy-bypass args');
+    }
+    const clientEnv = proxyEnvironment(opts.proxy);
+    const redactProxy = proxyOutputRedactor(opts.proxy);
     const ownsRunner = opts.ownsRunner ?? true;
+    const closeSession = opts.closeSession ?? true;
     const recordings = new Map();
     let closed = false;
     function assertOpen() {
         if (closed) throw new Error('AgentBrowser is closed');
     }
+    async function runWithRedaction(cmd, args, options) {
+        try {
+            const run = await runner.run(cmd, args, options);
+            return {
+                ...run,
+                stdout: redactProxy(run.stdout),
+                stderr: redactProxy(run.stderr)
+            };
+        } catch (error) {
+            if (error instanceof Error) {
+                error.message = redactProxy(error.message);
+                if (error.stack) error.stack = redactProxy(error.stack);
+            }
+            throw error;
+        }
+    }
     async function execCommand(args, timeoutMs, useSession = session) {
         const [name, ...rest] = args;
         // File-producing commands get a temporary remote output path when the
@@ -150,8 +205,9 @@ function outputSpec(args) {
             remotePath = recording?.path;
             fileSpec = recording?.spec;
         }
-        const run = await runner.run('agent-browser', finalArgs, {
-            timeoutMs
+        const run = await runWithRedaction('agent-browser', finalArgs, {
+            timeoutMs,
+            env: clientEnv
         });
         const result = {
             args,
@@ -249,6 +305,30 @@ function outputSpec(args) {
                 ok: results.every((r)=>r.ok)
             };
         },
+        async shell (command, shellOpts = {}) {
+            assertOpen();
+            if (!command.trim()) throw new Error('shell command must not be empty');
+            const useSession = shellOpts.session ?? session;
+            if (!SESSION_NAME.test(useSession)) {
+                throw new Error(`session must match [A-Za-z0-9_.-]{1,64}, got "${useSession}"`);
+            }
+            const run = await runWithRedaction('sh', [
+                '-c',
+                command
+            ], {
+                timeoutMs: shellOpts.timeoutMs,
+                env: {
+                    ...clientEnv,
+                    AGENT_BROWSER_SESSION: useSession
+                }
+            });
+            return {
+                ok: run.exitCode === 0,
+                exitCode: run.exitCode,
+                stdout: run.stdout,
+                stderr: run.stderr
+            };
+        },
         exec,
         async upload (selector, files, execOpts = {}) {
             assertOpen();
@@ -293,6 +373,15 @@ function outputSpec(args) {
                 result
             };
         },
+        async readFile (path, contentType = 'application/octet-stream') {
+            assertOpen();
+            if (!path) throw new Error('file path must not be empty');
+            return {
+                path,
+                bytes: await runner.readFile(path),
+                contentType
+            };
+        },
         async snapshot (urlOrOptions, opts = {}) {
             const url = typeof urlOrOptions === 'string' ? urlOrOptions : undefined;
             const runOpts = typeof urlOrOptions === 'string' ? opts : urlOrOptions ?? {};
@@ -333,15 +422,25 @@ function outputSpec(args) {
                 result: run
             };
         },
+        keepalive (opts = {}) {
+            assertOpen();
+            if (!runner.keepalive) {
+                throw new Error('the command runner does not support keepalive');
+            }
+            return runner.keepalive(opts);
+        },
         async close () {
             if (closed) return;
             closed = true;
             // Close the CLI session's browser first so the sandbox can stop cleanly.
-            await runner.run('agent-browser', withSession(session, clientArgs, [
-                'close'
-            ]), {
-                timeoutMs: 15_000
-            }).catch(()=>{});
+            if (closeSession) {
+                await runner.run('agent-browser', withSession(session, clientArgs, [
+                    'close'
+                ]), {
+                    timeoutMs: 15_000,
+                    env: clientEnv
+                }).catch(()=>{});
+            }
             if (ownsRunner) await runner.close();
         }
     };
@@ -354,13 +453,40 @@ const BASE_ENV = {
     AGENT_BROWSER_DEFAULT_TIMEOUT: '25000'
 };
 /** CommandRunner backed by one Vercel Sandbox. */ class SandboxRunner {
-    constructor(sandbox, env){
+    constructor(sandbox, env, timeoutMs = DEFAULT_TIMEOUT_MS){
+        this.keepaliveStops = new Set();
         this.sandbox = sandbox;
         this.env = env;
+        this.timeoutMs = timeoutMs;
+    }
+    async acquire() {
+        if (!this.sandbox) throw new Error('browser sandbox is unavailable');
+        return this.sandbox;
+    }
+    async observe() {
+        if (!this.sandbox) return null;
+        const sandbox = await Sandbox.get({
+            name: this.sandbox.name,
+            resume: false
+        });
+        this.sandbox = sandbox;
+        return sandbox;
+    }
+    async destroyRuntime() {
+        await this.sandbox?.stop().catch(()=>{});
     }
     async run(cmd, args, opts = {}) {
         const timeoutMs = opts.timeoutMs ?? 60_000;
-        const command = await this.sandbox.runCommand({
+        // A command is activity: restore the configured idle window even when no
+        // explicit heartbeat is running. Renewal is best-effort so an observability
+        // or platform hiccup does not block useful browser work.
+        const hadSandbox = this.sandbox !== undefined;
+        let sandbox = await this.acquire();
+        if (hadSandbox) {
+            sandbox = await this.observe().catch(()=>null) ?? sandbox;
+        }
+        await this.restoreLifetime(sandbox, this.timeoutMs).catch(()=>{});
+        const command = await sandbox.runCommand({
             cmd,
             args,
             env: {
@@ -370,8 +496,12 @@ const BASE_ENV = {
             detached: true
         });
         let timer;
+        let timedOut = false;
         const timeout = new Promise((_, reject)=>{
-            timer = setTimeout(()=>reject(new Error(`command timed out after ${timeoutMs}ms`)), timeoutMs);
+            timer = setTimeout(()=>{
+                timedOut = true;
+                reject(new Error(`command timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
             if (typeof timer.unref === 'function') timer.unref();
         });
         try {
@@ -391,11 +521,38 @@ const BASE_ENV = {
             };
         } catch (error) {
             await command.kill().catch(()=>{});
+            if (timedOut) await this.reclaimBrowser(sandbox);
             throw error;
         } finally{
             if (timer) clearTimeout(timer);
         }
     }
+    /** A timed-out CLI call may leave Chromium wedged; force a clean relaunch. */ async reclaimBrowser(sandbox) {
+        try {
+            const command = await sandbox.runCommand({
+                cmd: 'sh',
+                args: [
+                    '-c',
+                    'pkill -9 chromium || true; pkill -9 chrome || true'
+                ],
+                detached: true
+            });
+            let timer;
+            const timeout = new Promise((resolve)=>{
+                // Cleanup must not turn the original command timeout into an unbounded wait.
+                timer = setTimeout(resolve, 30_000);
+                if (typeof timer.unref === 'function') timer.unref();
+            });
+            try {
+                await Promise.race([
+                    command.wait(),
+                    timeout
+                ]);
+            } finally{
+                if (timer) clearTimeout(timer);
+            }
+        } catch  {}
+    }
     async readFile(path) {
         const { stdout, exitCode, stderr } = await this.run('base64', [
             '-w0',
@@ -409,17 +566,156 @@ const BASE_ENV = {
         return Buffer.from(stdout.trim(), 'base64');
     }
     async writeFile(path, bytes) {
-        await this.sandbox.writeFiles([
+        const sandbox = await this.acquire();
+        await sandbox.writeFiles([
             {
                 path,
                 content: bytes
             }
         ]);
     }
+    /** Restore a sliding idle window without cumulatively adding that window. */ async restoreLifetime(sandbox, timeoutMs) {
+        if (sandbox.status !== 'running') return;
+        const targetExpiresAt = Date.now() + timeoutMs;
+        const currentExpiresAt = sandbox.expiresAt?.getTime();
+        const extensionMs = currentExpiresAt === undefined ? timeoutMs : Math.ceil(targetExpiresAt - currentExpiresAt);
+        if (extensionMs > 0) await sandbox.extendTimeout(extensionMs);
+    }
+    async renewLifetime(timeoutMs) {
+        // Poll without resuming: a late heartbeat must not resurrect an already
+        // expired Sandbox whose in-memory browser state is gone.
+        const sandbox = await this.observe();
+        if (!sandbox) return;
+        await this.restoreLifetime(sandbox, timeoutMs);
+    }
+    keepalive(opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? this.timeoutMs;
+        const intervalMs = opts.intervalMs ?? Math.min(5 * 60 * 1000, Math.floor(timeoutMs / 2));
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new RangeError('keepalive timeoutMs must be greater than 0');
+        }
+        if (!Number.isFinite(intervalMs) || intervalMs <= 0 || intervalMs >= timeoutMs) {
+            throw new RangeError('keepalive intervalMs must be greater than 0 and less than timeoutMs');
+        }
+        let stopped = false;
+        let renewing = false;
+        const tick = async ()=>{
+            if (stopped || renewing) return;
+            renewing = true;
+            try {
+                await this.renewLifetime(timeoutMs);
+            } catch (error) {
+                opts.onError?.(error);
+            } finally{
+                renewing = false;
+            }
+        };
+        const timer = setInterval(()=>void tick(), intervalMs);
+        timer.unref?.();
+        void tick();
+        const stop = ()=>{
+            if (stopped) return;
+            stopped = true;
+            clearInterval(timer);
+            this.keepaliveStops.delete(stop);
+        };
+        this.keepaliveStops.add(stop);
+        return stop;
+    }
     async close() {
-        await this.sandbox.stop().catch(()=>{});
+        for (const stop of [
+            ...this.keepaliveStops
+        ])stop();
+        await this.destroyRuntime();
     }
 }
+function stableNames(id) {
+    const hash = createHash('sha256').update(id).digest('hex');
+    return {
+        sandbox: `remote-browser-${hash.slice(0, 32)}`,
+        session: `session-${hash.slice(0, 32)}`
+    };
+}
+function isMissingSandbox(error) {
+    if (!(error instanceof Error)) return false;
+    const code = error.json?.error?.code;
+    return code === 'not_found' || error.message.includes('Status code 404');
+}
+class NamedSandboxRunner extends SandboxRunner {
+    constructor(opts){
+        const names = stableNames(opts.id);
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        super(undefined, {
+            ...BASE_ENV,
+            ...opts.env
+        }, timeoutMs), this.resetListeners = new Set(), this.onResume = async ()=>{
+            const event = {
+                id: this.id,
+                reason: 'resumed'
+            };
+            for (const listener of this.resetListeners){
+                try {
+                    listener(event);
+                } catch  {}
+            }
+        };
+        this.id = opts.id;
+        this.name = names.sandbox;
+        this.session = names.session;
+        this.image = opts.image ?? process.env.REMOTE_AGENT_BROWSER_IMAGE ?? DEFAULT_BROWSER_IMAGE;
+        this.vcpus = opts.vcpus ?? 2;
+    }
+    on(event, listener) {
+        if (event !== 'reset') throw new Error(`unsupported browser event: ${event}`);
+        this.resetListeners.add(listener);
+        return ()=>this.resetListeners.delete(listener);
+    }
+    async acquire() {
+        if (this.sandbox) return this.sandbox;
+        this.sandbox = await Sandbox.getOrCreate({
+            name: this.name,
+            image: this.image,
+            resources: {
+                vcpus: this.vcpus
+            },
+            timeout: this.timeoutMs,
+            ports: [],
+            env: this.env,
+            persistent: false,
+            onResume: this.onResume
+        });
+        return this.sandbox;
+    }
+    async observe() {
+        try {
+            const sandbox = await Sandbox.get({
+                name: this.name,
+                resume: false,
+                onResume: this.onResume
+            });
+            this.sandbox = sandbox;
+            return sandbox;
+        } catch (error) {
+            if (isMissingSandbox(error)) return null;
+            throw error;
+        }
+    }
+    async destroyRuntime() {
+        try {
+            const sandbox = this.sandbox ?? await Sandbox.get({
+                name: this.name,
+                resume: false
+            });
+            await sandbox.delete();
+            this.sandbox = undefined;
+        } catch (error) {
+            if (!isMissingSandbox(error)) throw error;
+        }
+    }
+}
+/** Create a lazy runner backed by a stable, project-scoped browser id. */ function createNamedBrowserSandboxRunner(opts) {
+    return new NamedSandboxRunner(opts);
+}
 /**
  * Start an ephemeral Vercel Sandbox from the pre-built browser image.
  *
@@ -432,17 +728,18 @@ const BASE_ENV = {
         ...BASE_ENV,
         ...opts.env
     };
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const sandbox = await Sandbox.create({
         image,
         resources: {
             vcpus: opts.vcpus ?? 2
         },
-        timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        timeout: timeoutMs,
         ports: [],
         env,
         persistent: false
     });
-    return new SandboxRunner(sandbox, env);
+    return new SandboxRunner(sandbox, env, timeoutMs);
 }
 
 /**
@@ -476,14 +773,50 @@ const BASE_ENV = {
     return createBrowserClient(runner, {
         session: opts.session,
         args: opts.args,
+        proxy: opts.proxy,
+        ownsRunner: true
+    });
+}
+/**
+ * Create a lazy browser handle with a stable logical id.
+ *
+ * The first operation finds or creates a named Vercel Sandbox. Later handles
+ * created with the same id attach to that Sandbox, including from another
+ * process. If an expired Sandbox resumes, listeners are told that its
+ * in-memory page, refs, cookies, and console history were reset.
+ */ function createAgentBrowserSession(opts) {
+    if (!opts.id.trim()) throw new Error('browser id must not be empty');
+    const runner = createNamedBrowserSandboxRunner({
+        id: opts.id,
+        image: opts.image,
+        timeoutMs: opts.timeoutMs,
+        vcpus: opts.vcpus,
+        env: opts.env
+    });
+    const browser = createBrowserClient(runner, {
+        session: opts.session ?? runner.session,
+        args: opts.args,
+        proxy: opts.proxy,
+        closeSession: false,
         ownsRunner: true
     });
+    return {
+        ...browser,
+        id: opts.id,
+        on (event, listener) {
+            return runner.on(event, listener);
+        },
+        destroy () {
+            return browser.close();
+        }
+    };
 }
 
 // Public library surface: create an agent browser in a Vercel Sandbox and
 // drive it with the agent-browser CLI.
 /** Create AgentBrowser clients backed by a fresh Vercel Sandbox. */ const AgentBrowser = {
-    create: createAgentBrowser
+    create: createAgentBrowser,
+    session: createAgentBrowserSession
 };
 
-export { AgentBrowser, createAgentBrowser, createBrowserClient };
+export { AgentBrowser, createAgentBrowser, createAgentBrowserSession, createBrowserClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-agent-browser",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Run agent-browser in a Vercel Sandbox created from a browser-ready container image",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,7 @@
     "prepublishOnly": "node --run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --run build && node --test tests/*.test.mjs",
-    "test:integration": "node --run build && node --test tests/integration.test.mjs",
+    "test:integration": "node --run build && node --test --test-concurrency=1 tests/*.integration.ts",
     "test:unit": "node --run build && node --test tests/unit.test.mjs"
   },
   "files": [