@meetopenbot/stagehand 1.0.1

package/README.md

@@ -0,0 +1,68 @@
+# @meetopenbot/stagehand
+
+[Stagehand](https://docs.stagehand.dev) AI-browser-automation plugin for OpenBot.
+
+Give the agent a natural-language task ("Go to news.ycombinator.com and grab the top 3 AI stories") and the plugin will spin up a browser, drive it with an LLM-powered agent, and return the result.
+
+## What is included
+
+- `plugin` registry export compatible with OpenBot
+- `agent:invoke` handler that runs a Stagehand agent (`stagehand.agent().execute(...)`) for the user's prompt
+- `client:ui:widget:response` handler that captures missing API keys from the UI form and persists them via OpenBot storage
+- Per-step progress streaming back to the chat (one line per agent step)
+
+## Install & build
+
+```bash
+npm install
+npm run build
+```
+
+`npm install` will also try to install the Playwright Chromium browser binary via the `postinstall` script. If that fails (e.g. firewall, headless server), run it manually:
+
+```bash
+npx playwright install chromium
+```
+
+Then load `dist/index.js` from your OpenBot plugin registry.
+
+## Configuration
+
+### Required: one LLM key
+
+Set **one** of the following so Stagehand can drive the browser:
+
+- `OPENAI_API_KEY` — default; uses `openai/gpt-4o-mini`
+- `ANTHROPIC_API_KEY` — uses `anthropic/claude-sonnet-4-5-20250929`
+- `GOOGLE_GENERATIVE_AI_API_KEY` — uses `google/gemini-2.5-flash`
+- `BROWSERBASE_API_KEY` — enables Browserbase Model Gateway (only when running with `env: "BROWSERBASE"`)
+
+If no key is set, the plugin will pop up a form widget to capture and persist one.
+
+### Optional: Browserbase (cloud browser)
+
+If both `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID` are set (or you pass `env: "BROWSERBASE"` in plugin options), the plugin will run against Browserbase's cloud browsers instead of local Chromium.
+
+### Plugin options
+
+```ts
+{
+  apiKey?: string;                  // overrides env LLM key
+  provider?: "openai" | "anthropic" | "google"; // overrides auto-detect
+  model?: string;                   // full "provider/model" or short id, overrides default
+  env?: "LOCAL" | "BROWSERBASE";    // default: LOCAL
+  browserbaseApiKey?: string;
+  browserbaseProjectId?: string;
+  headless?: boolean;               // default: true (LOCAL mode)
+  maxSteps?: number;                // default: 25
+  mode?: "dom" | "hybrid" | "cua";  // default: auto
+  systemPrompt?: string;            // optional system prompt override
+  storage?: { createVariable: (...) => Promise<unknown> };
+}
+```
+
+## Notes
+
+- The plugin starts a fresh browser for each invocation and closes it when done. This is the most stable mode — no leaked Chromium processes between turns.
+- Local mode requires the Playwright Chromium binary (~150MB). Use Browserbase if you don't want to ship Chromium locally.
+- `dist/index.js` is intentionally tiny — runtime deps (`@browserbasehq/stagehand`, `playwright`, `zod`) stay external and are resolved from the plugin's local `node_modules`.

package/dist/index.js

@@ -0,0 +1,134 @@
+// index.ts
+import { Stagehand } from "@browserbasehq/stagehand";
+import {
+  agentOutput,
+  definePlugin,
+  shouldHandleInvoke,
+  uiWidget
+} from "@meetopenbot/plugin-sdk";
+var PROVIDER_CONFIG = {
+  openai: { label: "OpenAI", envVar: "OPENAI_API_KEY", defaultModel: "openai/gpt-4o-mini" },
+  anthropic: { label: "Anthropic", envVar: "ANTHROPIC_API_KEY", defaultModel: "anthropic/claude-sonnet-4-5-20250929" },
+  google: { label: "Google Generative AI", envVar: "GOOGLE_GENERATIVE_AI_API_KEY", defaultModel: "google/gemini-2.5-flash" }
+};
+var configSchema = {
+  type: "object",
+  properties: {
+    apiKey: { type: "string", format: "password" },
+    provider: { type: "string", enum: ["openai", "anthropic", "google"] },
+    model: { type: "string" },
+    env: { type: "string", enum: ["LOCAL", "BROWSERBASE"] },
+    browserbaseApiKey: { type: "string", format: "password" },
+    browserbaseProjectId: { type: "string" },
+    headless: { type: "boolean", default: true },
+    maxSteps: { type: "integer", default: 25 },
+    mode: { type: "string", enum: ["dom", "hybrid", "cua"] }
+  }
+};
+var plugin = definePlugin({
+  name: "Stagehand",
+  description: "Stagehand AI browser automation",
+  configSchema,
+  factory: (context) => (builder) => {
+    const env = process.env ?? {};
+    builder.on("agent:invoke", async function* (event) {
+      if (!shouldHandleInvoke(event, context.agentId)) return;
+      const content = event.data?.content;
+      const threadId = event.meta?.threadId;
+      if (!content) return;
+      const config = context.config;
+      const requestedEnv = config.env || (env.BROWSERBASE_API_KEY ? "BROWSERBASE" : "LOCAL");
+      const provider = config.provider || "openai";
+      const pConfig = PROVIDER_CONFIG[provider] || PROVIDER_CONFIG.openai;
+      const apiKey = config.apiKey || env[pConfig.envVar];
+      const model = config.model || pConfig.defaultModel;
+      if (!apiKey && requestedEnv === "LOCAL") {
+        yield uiWidget({
+          agentId: context.agentId,
+          threadId,
+          widget: {
+            widgetId: `stagehand_api_key_${Date.now()}`,
+            kind: "form",
+            title: "API Key Required",
+            description: `Stagehand needs an API key for ${pConfig.label}.`,
+            fields: [
+              { id: "provider", label: "Provider", type: "select", options: Object.entries(PROVIDER_CONFIG).map(([k, v]) => ({ value: k, label: v.label })), defaultValue: provider, required: true },
+              { id: "apiKey", label: "API Key", type: "text", required: true }
+            ],
+            submitLabel: "Save Key",
+            metadata: { type: "api_key_request" }
+          }
+        });
+        return;
+      }
+      let stagehand = null;
+      try {
+        yield agentOutput({ agentId: context.agentId, threadId, content: `Starting Stagehand (${requestedEnv.toLowerCase()})...` });
+        stagehand = new Stagehand({
+          env: requestedEnv,
+          model: apiKey ? { modelName: model, apiKey } : model,
+          apiKey: config.browserbaseApiKey ?? env.BROWSERBASE_API_KEY,
+          projectId: config.browserbaseProjectId ?? env.BROWSERBASE_PROJECT_ID,
+          localBrowserLaunchOptions: { headless: config.headless ?? true },
+          experimental: true
+        });
+        await stagehand.init();
+        const agent = stagehand.agent({
+          systemPrompt: context.agentDetails?.instructions ?? void 0,
+          mode: config.mode,
+          stream: true
+        });
+        const streamResult = await agent.execute({
+          instruction: content,
+          maxSteps: config.maxSteps ?? 25
+        });
+        for await (const part of streamResult.fullStream) {
+          if (part.type === "tool-call") {
+            yield agentOutput({
+              agentId: context.agentId,
+              threadId,
+              content: `
+> [Tool Call] ${part.toolName}: ${JSON.stringify(part.input, null, 2)}
+`
+            });
+          }
+          if (part.type === "tool-result") {
+            yield agentOutput({
+              agentId: context.agentId,
+              threadId,
+              content: `
+> [Tool Result] ${part.toolName}: ${JSON.stringify(part.output, null, 2).slice(0, 800)}
+`
+            });
+          }
+        }
+        const result = await streamResult.result;
+        if (result.message) yield agentOutput({ agentId: context.agentId, threadId, content: result.message });
+        if (result.output && Object.keys(result.output).length > 0) {
+          yield agentOutput({ agentId: context.agentId, threadId, content: "```json\n" + JSON.stringify(result.output, null, 2) + "\n```" });
+        }
+      } catch (error) {
+        yield agentOutput({ agentId: context.agentId, threadId, content: `Error: ${error.message}` });
+      } finally {
+        if (stagehand) await stagehand.close().catch(() => {
+        });
+      }
+    });
+    builder.on("client:ui:widget:response", async function* (event) {
+      const { metadata, values, widgetId } = event.data ?? {};
+      if (metadata?.type !== "api_key_request") return;
+      const provider = values?.provider;
+      const apiKey = values?.apiKey;
+      const pConfig = PROVIDER_CONFIG[provider];
+      if (pConfig && apiKey) {
+        await context.storage.createVariable({ key: pConfig.envVar, value: apiKey, secret: true });
+        env[pConfig.envVar] = apiKey;
+        yield uiWidget({ agentId: context.agentId, widget: { widgetId, kind: "message", title: "Success", body: "API key saved. Please retry your request.", state: "submitted", actions: [{ id: "ok", label: "OK" }] } });
+      }
+    });
+  }
+});
+var stagehand_default = plugin;
+export {
+  stagehand_default as default
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@meetopenbot/stagehand",
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Stagehand AI browser automation plugin for OpenBot",
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "esbuild index.ts --bundle --platform=node --target=node18 --format=esm --packages=external --outfile=dist/index.js",
+    "postinstall": "playwright install chromium --with-deps || playwright install chromium || true",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@browserbasehq/stagehand": "^3.3.0",
+    "@meetopenbot/plugin-sdk": "^0.1.2",
+    "playwright": "^1.52.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.1",
+    "esbuild": "^0.21.0"
+  }
+}