@browserbasehq/eve 0.1.0 → 0.2.0-alpha-82ef425ee115dbd63bbff930f9f171fe892d231a

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Browserbase Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,117 +1,63 @@
-# Browserbase for Eve
+# Eve + Stagehand facade (native tools)
 
-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.
+This example gives an Eve agent the native tools `run`, `snapshot`, and `screenshot`. The tools
+share a durable Stagehand session directly; no MCP connection or bridge process is required.
 
-## Install
+## Setup
 
-```bash
-pnpm add @browserbasehq/eve
-```
-
-Add your credentials to the consuming Eve app:
+Use Node.js 24 or later. From the repository root, build the integrations package before running
+the example:
 
 ```bash
-BROWSERBASE_API_KEY=bb_live_...
+pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations
 ```
 
-## Mount the extension
+Configure the environment as needed:
 
-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`.
+| Variable                                                             | Purpose                                                                                                                                                 |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STAGEHAND_BROWSER`                                                  | Browser backend. Defaults to `browserbase` when `BROWSERBASE_API_KEY` is set, otherwise `local`.                                                        |
+| `BROWSERBASE_API_KEY`                                                | Browserbase API key; required when using the Browserbase backend.                                                                                       |
+| `STAGEHAND_MODEL_NAME`                                               | Optional Stagehand model name, such as `openai/gpt-5.6-luna`.                                                                                           |
+| `STAGEHAND_MODEL_API_KEY`                                            | Optional explicit API key for `STAGEHAND_MODEL_NAME`; otherwise the matching provider key is inferred when supported.                                   |
+| `STAGEHAND_EVE_SESSION_FILE`                                         | Optional path used to persist the Browserbase session ID; defaults to a file in the system temporary directory.                                         |
+| `EVE_STAGEHAND_MODEL`                                                | Eve agent model; defaults to `gpt-5.6-luna`.                                                                                                            |
+| `OPENAI_API_KEY`                                                     | OpenAI credential used by the Eve agent model and inferred for an OpenAI Stagehand model.                                                               |
+| `GOOGLE_GENERATIVE_AI_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Google credential inferred by Stagehand. If one is set without explicit Stagehand model configuration, the model defaults to `google/gemini-3.8-flash`. |
 
-```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',
-});
-```
+## Run
 
-Start Eve and give the agent a browser task:
+The tool contract tests need no network, browser, or API keys:
 
 ```bash
-pnpm exec eve dev
+pnpm --filter @browserbasehq/stagehand-integrations-example-eve-facade test
+pnpm --filter @browserbasehq/stagehand-integrations-example-eve-facade typecheck
 ```
 
-```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
+For interactive use, set the browser and model credentials, then run:
 
 ```bash
-nvm use
-pnpm install
-pnpm check
+pnpm --filter @browserbasehq/stagehand-integrations-example-eve-facade dev
 ```
 
-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.
+## Security model
+
+`run(code)` executes model-authored JavaScript in the extension service worker: it runs
+browser-side, never in the host process. Browserbase is the recommended isolation boundary. The
+Eve world process holds only the browser session handle; model-authored JavaScript does not execute
+inside the world process.
+
+## Session lifecycle
 
-`eve extension build` writes the publishable extension and type declarations to
-`dist/`.
+The example holds one shared browser session per Eve world process. Concurrent Eve sessions served
+by the same process share pages, authentication, and other browser state, so this example is
+intended for single-session use.
 
-## Example agent
+On Browserbase, the example creates a `keepAlive: true` session and persists its ID to a temporary
+file. Set `STAGEHAND_EVE_SESSION_FILE` to override that path. Process restarts reattach to this
+session instead of creating and stranding another one. While awaiting reuse, the session keeps
+running and billing until it is reattached, released through the Browserbase dashboard or API, or
+reaches the project timeout.
 
-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.
+Errors from model-authored tool code do not reset the session. The browser session is recreated only
+when its connection is unhealthy.

package/dist/extension/_manifest.json

@@ -1,13 +1,17 @@
 {
   "kind": "eve-extension",
-  "formatVersion": 1,
-  "builtWithEve": "0.25.3",
+  "formatVersion": 2,
+  "builtWithEve": "0.68.0",
+  "build": {
+    "externalDependencies": [
+      "@browserbasehq/sdk",
+      "@browserbasehq/stagehand"
+    ]
+  },
   "requires": {
     "extension": 1,
-    "tool": 1,
-    "dynamicTool": 1,
-    "instructions": 1,
-    "config": 1,
-    "state": 1
+    "tool": 59,
+    "instructions": 2,
+    "config": 1
   }
 }

package/dist/extension/extension.d.ts

@@ -1,8 +1,8 @@
-import { z } from 'zod';
+import { z } from "zod";
 declare const _default: import("eve/extension").ExtensionHandle<z.ZodObject<{
-    apiKey: z.ZodString;
+    apiKey: z.ZodOptional<z.ZodString>;
     model: z.ZodDefault<z.ZodString>;
     sessionTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
-    proxies: z.ZodDefault<z.ZodBoolean>;
+    proxies: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>>;
 export default _default;

package/dist/extension/extension.mjs

@@ -1,14 +1,15 @@
 import { fileURLToPath as __eveFileURLToPath } from "node:url";
 import { dirname as __eveDirname } from "node:path";
 import { createRequire as __eveCreateRequire } from "node:module";
-__eveDirname(__eveFileURLToPath(import.meta.url));
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
 __eveCreateRequire(import.meta.url);
 import { defineExtension } from "eve/extension";
 import { z } from "zod";
 var extension_default = defineExtension({ config: z.object({
-	apiKey: z.string().min(1),
+	apiKey: z.string().min(1).optional(),
 	model: z.string().min(1).default("openai/gpt-5.4-mini"),
 	sessionTimeoutSeconds: z.number().int().min(60).max(21600).default(900),
-	proxies: z.boolean().default(false)
+	proxies: z.boolean().optional()
 }) });
 export { extension_default as default };

package/dist/extension/instructions/browser.md

@@ -1,9 +1,15 @@
-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.
+Browser tool surface: Stagehand Playwright facade.
+You control one persistent browser through exactly three tools:
+
+- run: execute JavaScript against an initialized Playwright page, context, and browser (page.goto, page.locator(selector).click()/fill(), page.getByRole(...), page.evaluate(...), page.waitForURL(...), and the supported Playwright-shaped API). Use await directly and return JSON-serializable values so you can inspect progress. Alternatively, pass snapshot actions.
+- snapshot: inspect the active page's accessibility tree and hydrate bracketed element IDs for run actions.
+- screenshot: inspect the rendered page visually.
+
+Pass run exactly one of code or actions; every action uses "op" and "id", never "kind" or "ref". Snapshot IDs are valid only for the latest snapshot of the active page; snapshot again after navigation or stale IDs. The first browser action should usually be: await page.goto(url, { waitUntil: 'domcontentloaded' }). Do not launch another browser or create a separate browser process.
+
+Snapshot output displays IDs in brackets (for example, `[0-22]`), but action `id` values omit the
+brackets (for example, `"0-22"`).
+
+JavaScript passed to `run` receives Playwright-shaped `page`, `context`, and `browser` objects. Call
+`await browser.close()` only after collecting the final result; Eve then releases the owned
+Browserbase session and creates fresh resources on the next browser tool call.