[GRO-1938] feat: Add Browserbase Eve extension

examples/integrations/vercel/README.md

@@ -14,8 +14,14 @@ Browserbase is a perfect addition to the Vercel AI SDK, bringing headless browse
 
 ## Examples
 
-In this directory we have two examples of using Vercel & Browserbase together:
+In this directory we have three examples of using Vercel & Browserbase together:
 
 BrowseGPT is a chat interface that allows users to search the web and get answers to their questions. It demonstrates how to use Vercel AI SDK with Browserbase to create an AI assistant that can browse the web in real-time to provide up-to-date information.
 
 The second example shows how to use Puppeteer with Vercel on Fluid Compute. It demonstrates setting up a Next.js application with Puppeteer for browser automation tasks, deployed on Vercel's Fluid Compute infrastructure which provides longer execution times needed for browser automation.
+
+The [`@browserbasehq/eve`](../../../packages/eve-browserbase/) package gives Eve
+agents a persistent Browserbase browser through Stagehand's `act`, `observe`,
+`extract`, and autonomous agent primitives. The
+[example agent](./eve-example/) mounts the extension in a runnable pnpm
+workspace.

examples/integrations/vercel/eve-example/.env.example

@@ -0,0 +1,2 @@
+BROWSERBASE_API_KEY=bb_live_...
+AI_GATEWAY_API_KEY=your_vercel_ai_gateway_key

examples/integrations/vercel/eve-example/.gitignore

@@ -0,0 +1,9 @@
+node_modules
+.env*
+!.env.example
+.eve
+.vercel
+.output
+.nitro
+dist
+*.tsbuildinfo

examples/integrations/vercel/eve-example/.nvmrc

@@ -0,0 +1 @@
+24.16.0

examples/integrations/vercel/eve-example/README.md

@@ -0,0 +1,49 @@
+# Example Eve browser agent
+
+This agent mounts the local `@browserbasehq/eve` extension as `browserbase`, so
+its tools are available as `browserbase__create_session`,
+`browserbase__navigate`, `browserbase__observe`, `browserbase__act`,
+`browserbase__extract`, `browserbase__agent`, and
+`browserbase__stop_session`. It also exposes `browserbase__search` and
+`browserbase__fetch`, which do not require a browser session.
+
+## Run it
+
+From the repository root, enter the `eve` package directory:
+
+```bash
+cd packages/eve-browserbase
+nvm use
+pnpm install
+pnpm build
+cp ../../examples/integrations/vercel/eve-example/.env.example ../../examples/integrations/vercel/eve-example/.env
+```
+
+Fill in the values in `../../examples/integrations/vercel/eve-example/.env`,
+then start the agent from the same `packages/eve-browserbase` directory:
+
+```bash
+pnpm --filter browserbase-eve-example dev
+```
+
+Eve requires Node.js 24 or newer. Both workspace packages include an `.nvmrc`
+for Node 24.16.0. If that version is not installed yet, run
+`nvm install 24.16.0` before `nvm use`.
+
+The Eve terminal UI opens. Try this prompt:
+
+```text
+Open https://news.ycombinator.com and return the titles and URLs of the first
+five stories. Use a Browserbase session and stop it when you are done.
+```
+
+The environment requires:
+
+- `BROWSERBASE_API_KEY` to create the cloud browser and power Stagehand through
+  Browserbase Model Gateway.
+- `AI_GATEWAY_API_KEY` to power the Eve agent model. A linked Vercel project's
+  `VERCEL_OIDC_TOKEN` can be used instead.
+
+The dependency on `@browserbasehq/eve` uses pnpm's `workspace:*` protocol, so
+the example exercises the local package without publishing it first. The
+workspace-level install provides dependencies for both packages.

examples/integrations/vercel/eve-example/agent/agent.ts

@@ -0,0 +1,5 @@
+import { defineAgent } from 'eve';
+
+export default defineAgent({
+  model: 'openai/gpt-5.4-mini',
+});

examples/integrations/vercel/eve-example/agent/extensions/browserbase.ts

@@ -0,0 +1,6 @@
+import browserbase from '@browserbasehq/eve';
+
+export default browserbase({
+  apiKey: process.env.BROWSERBASE_API_KEY!,
+  model: 'openai/gpt-5.4-mini',
+});

examples/integrations/vercel/eve-example/agent/instructions.md

@@ -0,0 +1,19 @@
+# Identity
+
+You are a browser research agent. Use the Browserbase extension whenever a task
+requires opening or interacting with a website.
+
+# Browser workflow
+
+1. Use Browserbase Search when you need to discover relevant URLs.
+2. Use Browserbase Fetch when you only need page content and the page does not
+   require JavaScript or interaction.
+3. For interactive or rendered pages, create a Browserbase session and navigate
+   to the requested URL.
+4. Use observe before interacting with an unfamiliar page.
+5. Prefer act for one interaction and extract for structured results.
+6. Use the autonomous agent tool only for genuinely multi-step browser work.
+7. Stop any Browserbase session before returning the final answer.
+
+Never invent page contents. Report a browser failure clearly if a tool cannot
+complete the requested operation.

examples/integrations/vercel/eve-example/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "browserbase-eve-example",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.9.0",
+  "scripts": {
+    "build": "eve build",
+    "dev": "eve dev",
+    "start": "eve start",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@browserbasehq/eve": "workspace:*",
+    "ai": "^7.0.26",
+    "eve": "0.25.3",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "typescript": "7.0.2"
+  },
+  "overrides": {
+    "ai": "^7.0.26"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

examples/integrations/vercel/eve-example/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["agent/**/*.ts"]
+}

packages/eve-browserbase/.gitignore

@@ -0,0 +1,8 @@
+node_modules
+.env*
+.eve
+.vercel
+.output
+.nitro
+dist
+*.tsbuildinfo

packages/eve-browserbase/.nvmrc

@@ -0,0 +1 @@
+24.16.0

packages/eve-browserbase/README.md

@@ -0,0 +1,117 @@
+# Browserbase for Eve
+
+An [Eve extension](https://eve.dev/docs/extensions) that gives an agent
+Browserbase Search and Fetch plus a persistent Browserbase browser powered by
+[Stagehand](https://docs.stagehand.dev/). It exposes Stagehand's focused
+primitives (`act`, `observe`, and `extract`) plus navigation and autonomous agent
+tools.
+
+## Install
+
+```bash
+pnpm add @browserbasehq/eve
+```
+
+Add your credentials to the consuming Eve app:
+
+```bash
+BROWSERBASE_API_KEY=bb_live_...
+```
+
+## Mount the extension
+
+The filename under `agent/extensions/` becomes the tool namespace. Mounting the
+extension as `browserbase.ts` creates tools such as `browserbase__search`,
+`browserbase__fetch`, `browserbase__create_session`, and
+`browserbase__navigate`.
+
+```ts
+// agent/extensions/browserbase.ts
+import browserbase from '@browserbasehq/eve';
+
+export default browserbase({
+  apiKey: process.env.BROWSERBASE_API_KEY!,
+  model: 'openai/gpt-5.4-mini',
+});
+```
+
+Start Eve and give the agent a browser task:
+
+```bash
+pnpm exec eve dev
+```
+
+```text
+Open https://news.ycombinator.com and extract the titles and URLs of the first
+five stories.
+```
+
+The extension keeps the Browserbase session ID in Eve's durable per-session
+state. Each browser tool reconnects to that browser, performs one operation,
+and disconnects without terminating it. `browserbase__create_session` creates
+or reconnects the browser explicitly, and `browserbase__stop_session`
+terminates it.
+
+## Tools
+
+| Tool             | Purpose                                                 |
+| ---------------- | ------------------------------------------------------- |
+| `search`         | Find relevant public web pages with Browserbase Search. |
+| `fetch`          | Retrieve raw, markdown, or structured page content.     |
+| `create_session` | Create or reconnect the Browserbase session.            |
+| `stop_session`   | Stop the Browserbase session and release resources.     |
+| `navigate`       | Open a URL in the current browser.                      |
+| `observe`        | Find relevant elements and candidate actions.           |
+| `act`            | Perform one natural-language page interaction.          |
+| `extract`        | Return data validated against a supplied JSON Schema.   |
+| `agent`          | Run a multi-step autonomous Stagehand task.             |
+
+Use Search → Fetch → browser as an escalation path: discover sources cheaply,
+retrieve straightforward content without a session, and create a browser only
+when the page requires JavaScript or interaction. Fetch supports Browserbase's
+`raw`, `markdown`, and schema-driven `json` formats.
+
+For predictable and efficient runs, use `create_session` → `navigate` →
+`observe` → `act` or `extract`, then `stop_session`. Reserve `agent` for
+workflows that need Stagehand to plan several steps on its own.
+
+## Configuration
+
+| Option                  | Default               | Description                                         |
+| ----------------------- | --------------------- | --------------------------------------------------- |
+| `apiKey`                | required              | Browserbase API key for browsers and Model Gateway. |
+| `model`                 | `openai/gpt-5.4-mini` | Stagehand Model Gateway model identifier.           |
+| `sessionTimeoutSeconds` | `900`                 | Session timeout, from 60 to 21,600 seconds.         |
+| `proxies`               | `false`               | Enable Browserbase proxies for new sessions.        |
+
+Stagehand runs through Browserbase Model Gateway, so consumers do not need an
+OpenAI or other model-provider API key. The Browserbase API key covers both the
+browser session and Stagehand inference.
+
+The extension uses Browserbase `keepAlive` sessions so it can reconnect across
+Eve workflow steps and Vercel function invocations. Parallel browser calls made
+inside one Eve workflow step are queued in that step's managed runtime; durable
+state reconnects later steps and invocations. Close the session after the task
+to avoid leaving billable browser time running. Keep-alive availability depends
+on your Browserbase plan.
+
+## Build
+
+```bash
+nvm use
+pnpm install
+pnpm check
+```
+
+Eve requires Node.js 24 or newer. This directory's `.nvmrc` pins Node 24.16.0;
+run `nvm install 24.16.0` first if needed.
+
+`eve extension build` writes the publishable extension and type declarations to
+`dist/`.
+
+## Example agent
+
+The [`eve-example`](../../examples/integrations/vercel/eve-example/) directory
+contains a runnable Eve agent that mounts this package locally. It includes the
+agent instructions, environment template, and a Browserbase research prompt for
+a complete smoke test.

packages/eve-browserbase/extension/extension.ts

@@ -0,0 +1,11 @@
+import { defineExtension } from 'eve/extension';
+import { z } from 'zod';
+
+export default defineExtension({
+  config: z.object({
+    apiKey: z.string().min(1),
+    model: z.string().min(1).default('openai/gpt-5.4-mini'),
+    sessionTimeoutSeconds: z.number().int().min(60).max(21_600).default(900),
+    proxies: z.boolean().default(false),
+  }),
+});

packages/eve-browserbase/extension/instructions/browser.md

@@ -0,0 +1,9 @@
+Use Browserbase Search to discover relevant URLs and Browserbase Fetch for quick
+retrievals that do not need JavaScript or interaction. Escalate to a browser
+session when a page needs rendering or interaction: create a session, navigate,
+then use observe to plan, act for one interaction, and extract for structured
+results. Use agent only for genuinely multi-step work. Browser tools share one
+Browserbase session per Eve session. Parallel browser calls from the same Eve
+workflow step are queued within that step; later steps reconnect through durable
+state. Prefer calling tools sequentially, and stop the browser session when the
+task is complete.

packages/eve-browserbase/extension/lib/browserbase.ts

@@ -0,0 +1,7 @@
+import Browserbase from '@browserbasehq/sdk';
+
+import extension from '../extension';
+
+export function createBrowserbaseClient(): Browserbase {
+  return new Browserbase({ apiKey: extension.config.apiKey });
+}

packages/eve-browserbase/extension/lib/disconnect.ts

@@ -0,0 +1,9 @@
+interface ClosableStagehand {
+  close(): Promise<void>;
+}
+
+export async function disconnectStagehand(
+  stagehand: ClosableStagehand
+): Promise<void> {
+  await stagehand.close().catch(() => {});
+}