remote-agent-browser 0.2.0 → 1.1.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:
@@ -128,4 +153,24 @@ await writeFile('capture.har', result.file.bytes)
 
 All methods use the same disposable browser session until `close()` is called.
 
+### 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

@@ -60,13 +60,29 @@ 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;
     /** 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;
+};
 /**
  * Minimal command executor the browser client needs. Implemented by the
  * Vercel Sandbox adapter; anything with the same shape can back a
@@ -88,6 +104,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 {
@@ -115,6 +133,11 @@ 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>;
 }
@@ -135,6 +158,8 @@ 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;
 };
 /**
  * Create an agent-browser client running inside a fresh Vercel Sandbox.
@@ -177,4 +202,4 @@ declare const AgentBrowser: {
 type AgentBrowser = AgentBrowser$1;
 
 export { AgentBrowser, createAgentBrowser, createBrowserClient };
-export type { BrowserClientOptions, BrowserCommandResult, BrowserRunResult, CommandRunner, CreateAgentBrowserOptions, ExecOptions, JsonExecOptions, RunOptions };
+export type { BrowserClientOptions, BrowserCommandResult, BrowserRunResult, CommandRunner, CreateAgentBrowserOptions, ExecOptions, JsonExecOptions, KeepaliveOptions, ProxyOptions, RunOptions };

package/dist/index.js

@@ -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,6 +144,11 @@ 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 recordings = new Map();
     let closed = false;
@@ -150,15 +188,25 @@ function outputSpec(args) {
             remotePath = recording?.path;
             fileSpec = recording?.spec;
         }
-        const run = await runner.run('agent-browser', finalArgs, {
-            timeoutMs
-        });
+        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 result = {
             args,
             ok: run.exitCode === 0,
             exitCode: run.exitCode,
-            stdout: run.stdout,
-            stderr: run.stderr
+            stdout: redactProxy(run.stdout),
+            stderr: redactProxy(run.stderr)
         };
         if (result.ok && startsRecording && remotePath && fileSpec) {
             recordings.set(useSession, {
@@ -333,6 +381,13 @@ 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;
@@ -340,7 +395,8 @@ function outputSpec(args) {
             await runner.run('agent-browser', withSession(session, clientArgs, [
                 'close'
             ]), {
-                timeoutMs: 15_000
+                timeoutMs: 15_000,
+                env: clientEnv
             }).catch(()=>{});
             if (ownsRunner) await runner.close();
         }
@@ -354,9 +410,11 @@ 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 run(cmd, args, opts = {}) {
         const timeoutMs = opts.timeoutMs ?? 60_000;
@@ -416,7 +474,58 @@ const BASE_ENV = {
             }
         ]);
     }
+    /** 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
+        });
+        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);
+    }
+    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() {
+        for (const stop of [
+            ...this.keepaliveStops
+        ])stop();
         await this.sandbox.stop().catch(()=>{});
     }
 }
@@ -432,17 +541,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,6 +586,7 @@ const BASE_ENV = {
     return createBrowserClient(runner, {
         session: opts.session,
         args: opts.args,
+        proxy: opts.proxy,
         ownsRunner: true
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-agent-browser",
-  "version": "0.2.0",
+  "version": "1.1.0",
   "description": "Run agent-browser in a Vercel Sandbox created from a browser-ready container image",
   "license": "MIT",
   "repository": {
@@ -8,22 +8,18 @@
     "url": "git+https://github.com/vercel-labs/remote-agent-browser.git"
   },
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "packageManager": "pnpm@11.18.0",
   "publishConfig": {
     "access": "public"
   },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
   "scripts": {
     "build": "bunchee --runtime node",
     "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": [