remote-agent-browser 1.2.0 → 1.3.0

package/README.md

@@ -3,6 +3,23 @@
 Run [agent-browser](https://github.com/vercel-labs/agent-browser) in the cloud
 with an isolated [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox).
 
+## Benchmark
+
+Loading and taking an interactive snapshot of 100 HTTPS pages in a fresh,
+two-vCPU Vercel Sandbox:
+
+| Metric | Result |
+| --- | ---: |
+| Execution time (100 pages) | 8.01s |
+| Memory (peak, 100 pages) | 461.6MB PSS |
+
+Execution time includes Sandbox creation. The published time is the median and
+memory is the maximum from three successful runs using Chromium 151,
+agent-browser 0.33.2, and `https://example.com/` with a unique query per page.
+Each page must produce the expected content and interactive snapshot references.
+
+See [the benchmark methodology](./benchmarks/BENCHMARK.md) for details.
+
 ## Install
 
 ```bash
@@ -31,6 +48,27 @@ references. `close()` closes Chromium and stops the Sandbox.
 Authentication is automatic when running on Vercel through
 `VERCEL_OIDC_TOKEN`.
 
+To run browsers in another team/project, supply explicit short-lived credentials:
+
+```ts
+const browser = AgentBrowser.session({
+  id: `preview:${chatId}`,
+  resolveSandboxCredentials: async () => ({
+    teamId: resourceTeamId,
+    projectId: resourceProjectId,
+    token: await getShortLivedTeamToken(),
+  }),
+})
+```
+
+The same option works with `AgentBrowser.create()`. Keep the team and project
+fixed for the handle's lifetime; refresh only the token. The resolver is lazy
+for named sessions and runs before creation, cached-runtime command/file access,
+observation/keepalive, and cleanup. A resolver failure rejects the operation;
+commands do not fall back to cached credentials. Returning `undefined` preserves
+deployment authentication. Credentials are not passed into browser command env.
+
+
 For local development, link a Vercel project and pull its environment:
 
 ```bash

package/dist/index.d.ts

@@ -174,8 +174,17 @@ interface AgentBrowserSession extends AgentBrowser$1 {
     /** Permanently remove the runtime currently associated with this id. */
     destroy(): Promise<void>;
 }
+/** Explicit Sandbox scope; resolve a fresh token while keeping team/project fixed. */
+type SandboxCredentials = {
+    token: string;
+    teamId: string;
+    projectId: string;
+};
+type ResolveSandboxCredentials = () => Promise<SandboxCredentials | undefined>;
 
 type CreateAgentBrowserOptions = {
+    /** Fresh credentials for a fixed Sandbox scope; omit for deployment auth. */
+    resolveSandboxCredentials?: ResolveSandboxCredentials;
     /** Named CLI session; state (page, cookies, refs) persists across calls. */
     session?: string;
     /**
@@ -249,4 +258,4 @@ declare const AgentBrowser: {
 type AgentBrowser = AgentBrowser$1;
 
 export { AgentBrowser, createAgentBrowser, createAgentBrowserSession, createBrowserClient };
-export type { AgentBrowserSession, BrowserClientOptions, BrowserCommandResult, BrowserFile, BrowserRunResult, BrowserRuntimeResetEvent, BrowserShellResult, CommandRunner, CreateAgentBrowserOptions, CreateAgentBrowserSessionOptions, ExecOptions, JsonExecOptions, KeepaliveOptions, ProxyOptions, RunOptions, ShellOptions };
+export type { AgentBrowserSession, BrowserClientOptions, BrowserCommandResult, BrowserFile, BrowserRunResult, BrowserRuntimeResetEvent, BrowserShellResult, CommandRunner, CreateAgentBrowserOptions, CreateAgentBrowserSessionOptions, ExecOptions, JsonExecOptions, KeepaliveOptions, ProxyOptions, ResolveSandboxCredentials, RunOptions, SandboxCredentials, ShellOptions };

package/dist/index.js

@@ -453,19 +453,24 @@ const BASE_ENV = {
     AGENT_BROWSER_DEFAULT_TIMEOUT: '25000'
 };
 /** CommandRunner backed by one Vercel Sandbox. */ class SandboxRunner {
-    constructor(sandbox, env, timeoutMs = DEFAULT_TIMEOUT_MS){
+    constructor(sandbox, env, timeoutMs = DEFAULT_TIMEOUT_MS, resolveSandboxCredentials){
         this.keepaliveStops = new Set();
         this.sandbox = sandbox;
         this.env = env;
         this.timeoutMs = timeoutMs;
+        this.resolveSandboxCredentials = resolveSandboxCredentials;
     }
     async acquire() {
         if (!this.sandbox) throw new Error('browser sandbox is unavailable');
         return this.sandbox;
     }
     async observe() {
+        return this.observeWithCredentials(await this.resolveSandboxCredentials?.());
+    }
+    async observeWithCredentials(credentials) {
         if (!this.sandbox) return null;
         const sandbox = await Sandbox.get({
+            ...credentials,
             name: this.sandbox.name,
             resume: false
         });
@@ -473,6 +478,14 @@ const BASE_ENV = {
         return sandbox;
     }
     async destroyRuntime() {
+        if (this.resolveSandboxCredentials) {
+            const credentials = await this.resolveSandboxCredentials();
+            if (credentials) {
+                const sandbox = await this.observeWithCredentials(credentials);
+                await sandbox?.stop();
+                return;
+            }
+        }
         await this.sandbox?.stop().catch(()=>{});
     }
     async run(cmd, args, opts = {}) {
@@ -483,7 +496,14 @@ const BASE_ENV = {
         const hadSandbox = this.sandbox !== undefined;
         let sandbox = await this.acquire();
         if (hadSandbox) {
-            sandbox = await this.observe().catch(()=>null) ?? sandbox;
+            const credentials = await this.resolveSandboxCredentials?.();
+            if (credentials) {
+                const observed = await this.observeWithCredentials(credentials);
+                if (!observed) throw new Error('browser sandbox is unavailable');
+                sandbox = observed;
+            } else {
+                sandbox = await this.observeWithCredentials(undefined).catch(()=>null) ?? sandbox;
+            }
         }
         await this.restoreLifetime(sandbox, this.timeoutMs).catch(()=>{});
         const command = await sandbox.runCommand({
@@ -566,7 +586,16 @@ const BASE_ENV = {
         return Buffer.from(stdout.trim(), 'base64');
     }
     async writeFile(path, bytes) {
-        const sandbox = await this.acquire();
+        const hadSandbox = this.sandbox !== undefined;
+        let sandbox = await this.acquire();
+        if (hadSandbox) {
+            const credentials = await this.resolveSandboxCredentials?.();
+            if (credentials) {
+                const observed = await this.observeWithCredentials(credentials);
+                if (!observed) throw new Error('browser sandbox is unavailable');
+                sandbox = observed;
+            }
+        }
         await sandbox.writeFiles([
             {
                 path,
@@ -648,7 +677,7 @@ class NamedSandboxRunner extends SandboxRunner {
         super(undefined, {
             ...BASE_ENV,
             ...opts.env
-        }, timeoutMs), this.resetListeners = new Set(), this.onResume = async ()=>{
+        }, timeoutMs, opts.resolveSandboxCredentials), this.resetListeners = new Set(), this.onResume = async ()=>{
             const event = {
                 id: this.id,
                 reason: 'resumed'
@@ -673,6 +702,7 @@ class NamedSandboxRunner extends SandboxRunner {
     async acquire() {
         if (this.sandbox) return this.sandbox;
         this.sandbox = await Sandbox.getOrCreate({
+            ...await this.resolveSandboxCredentials?.(),
             name: this.name,
             image: this.image,
             resources: {
@@ -686,9 +716,10 @@ class NamedSandboxRunner extends SandboxRunner {
         });
         return this.sandbox;
     }
-    async observe() {
+    async observeWithCredentials(credentials) {
         try {
             const sandbox = await Sandbox.get({
+                ...credentials,
                 name: this.name,
                 resume: false,
                 onResume: this.onResume
@@ -702,10 +733,15 @@ class NamedSandboxRunner extends SandboxRunner {
     }
     async destroyRuntime() {
         try {
-            const sandbox = this.sandbox ?? await Sandbox.get({
-                name: this.name,
-                resume: false
-            });
+            const credentials = await this.resolveSandboxCredentials?.();
+            let sandbox = this.sandbox;
+            if (credentials || !sandbox) {
+                sandbox = await Sandbox.get({
+                    ...credentials,
+                    name: this.name,
+                    resume: false
+                });
+            }
             await sandbox.delete();
             this.sandbox = undefined;
         } catch (error) {
@@ -730,6 +766,7 @@ class NamedSandboxRunner extends SandboxRunner {
     };
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const sandbox = await Sandbox.create({
+        ...await opts.resolveSandboxCredentials?.(),
         image,
         resources: {
             vcpus: opts.vcpus ?? 2
@@ -739,7 +776,7 @@ class NamedSandboxRunner extends SandboxRunner {
         env,
         persistent: false
     });
-    return new SandboxRunner(sandbox, env, timeoutMs);
+    return new SandboxRunner(sandbox, env, timeoutMs, opts.resolveSandboxCredentials);
 }
 
 /**
@@ -768,7 +805,8 @@ class NamedSandboxRunner extends SandboxRunner {
         image: opts.image,
         timeoutMs: opts.timeoutMs,
         vcpus: opts.vcpus,
-        env: opts.env
+        env: opts.env,
+        resolveSandboxCredentials: opts.resolveSandboxCredentials
     });
     return createBrowserClient(runner, {
         session: opts.session,
@@ -791,7 +829,8 @@ class NamedSandboxRunner extends SandboxRunner {
         image: opts.image,
         timeoutMs: opts.timeoutMs,
         vcpus: opts.vcpus,
-        env: opts.env
+        env: opts.env,
+        resolveSandboxCredentials: opts.resolveSandboxCredentials
     });
     const browser = createBrowserClient(runner, {
         session: opts.session ?? runner.session,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-agent-browser",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Run agent-browser in a Vercel Sandbox created from a browser-ready container image",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
   },
   "scripts": {
     "build": "bunchee --runtime node",
+    "benchmark": "node --run build && node benchmarks/chromium.mjs",
     "prepublishOnly": "node --run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --run build && node --test tests/*.test.mjs",