remote-agent-browser 1.1.0 → 1.2.0

package/README.md

@@ -102,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
@@ -143,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
@@ -153,6 +183,41 @@ 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

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;
@@ -72,6 +84,8 @@ type BrowserClientOptions = {
     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;
 };
@@ -83,6 +97,12 @@ type KeepaliveOptions = {
     /** 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
@@ -113,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. */
@@ -126,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. */
@@ -141,6 +165,15 @@ interface AgentBrowser$1 {
     /** 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. */
@@ -161,6 +194,10 @@ type CreateAgentBrowserOptions = {
     /** 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.
  *
@@ -184,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.
@@ -198,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, KeepaliveOptions, ProxyOptions, 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([
@@ -150,11 +150,28 @@ function outputSpec(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
@@ -188,25 +205,16 @@ function outputSpec(args) {
             remotePath = recording?.path;
             fileSpec = recording?.spec;
         }
-        let run;
-        try {
-            run = await runner.run('agent-browser', finalArgs, {
-                timeoutMs,
-                env: clientEnv
-            });
-        } catch (error) {
-            if (error instanceof Error) {
-                error.message = redactProxy(error.message);
-                if (error.stack) error.stack = redactProxy(error.stack);
-            }
-            throw error;
-        }
+        const run = await runWithRedaction('agent-browser', finalArgs, {
+            timeoutMs,
+            env: clientEnv
+        });
         const result = {
             args,
             ok: run.exitCode === 0,
             exitCode: run.exitCode,
-            stdout: redactProxy(run.stdout),
-            stderr: redactProxy(run.stderr)
+            stdout: run.stdout,
+            stderr: run.stderr
         };
         if (result.ok && startsRecording && remotePath && fileSpec) {
             recordings.set(useSession, {
@@ -297,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();
@@ -341,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 ?? {};
@@ -392,12 +433,14 @@ function outputSpec(args) {
             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,
-                env: clientEnv
-            }).catch(()=>{});
+            if (closeSession) {
+                await runner.run('agent-browser', withSession(session, clientArgs, [
+                    'close'
+                ]), {
+                    timeoutMs: 15_000,
+                    env: clientEnv
+                }).catch(()=>{});
+            }
             if (ownsRunner) await runner.close();
         }
     };
@@ -416,9 +459,34 @@ const BASE_ENV = {
         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: {
@@ -428,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 {
@@ -449,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',
@@ -467,27 +566,28 @@ 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 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 Sandbox.get({
-            name: this.sandbox.name,
-            resume: false
-        });
+    /** Restore a sliding idle window without cumulatively adding that window. */ async restoreLifetime(sandbox, timeoutMs) {
         if (sandbox.status !== 'running') return;
-        this.sandbox = sandbox;
         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));
@@ -526,8 +626,95 @@ const BASE_ENV = {
         for (const stop of [
             ...this.keepaliveStops
         ])stop();
-        await this.sandbox.stop().catch(()=>{});
+        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.
@@ -590,11 +777,46 @@ const BASE_ENV = {
         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.1.0",
+  "version": "1.2.0",
   "description": "Run agent-browser in a Vercel Sandbox created from a browser-ready container image",
   "license": "MIT",
   "repository": {