feat: run code-mode MCP in Vercel Sandbox

.github/workflows/codemode-framework-examples.yml

@@ -0,0 +1,53 @@
+name: Code-mode framework examples
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/codemode-framework-examples.yml"
+      - "packages/integrations/**"
+      - "packages/extension/**"
+      - "packages/protocol/**"
+      - "packages/sdk-ts/**"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+  push:
+    branches: [main, v4-spike]
+    paths:
+      - ".github/workflows/codemode-framework-examples.yml"
+      - "packages/integrations/**"
+      - "packages/extension/**"
+      - "packages/protocol/**"
+      - "packages/sdk-ts/**"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  vercel:
+    name: Vercel AI SDK
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+
+      - uses: ./.github/actions/setup-node-pnpm
+        with:
+          use-prebuilt-artifacts: "false"
+
+      - uses: ./.github/actions/setup-chrome-verified
+        id: setup-chrome
+
+      - run: pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations
+      - run: pnpm --filter @browserbasehq/stagehand-integrations-example-vercel typecheck
+      - run: pnpm --filter @browserbasehq/stagehand-integrations-example-vercel smoke
+        env:
+          CHROME_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+          STAGEHAND_BROWSER: local

packages/integrations/README.md

@@ -44,6 +44,10 @@ STAGEHAND_BROWSER=browserbase
 
 The process stays alive across calls and closes when its input stream ends. `SIGINT` and `SIGTERM` perform bounded graceful cleanup and preserve signal-style exit codes. If generated JavaScript blocks the JavaScript event loop, the server cannot run its cleanup handlers. The owner must terminate the entire process tree, escalate to `SIGKILL` after its own deadline, and start a new process before accepting more work. Killing only the Node process can leave its local browser child alive.
 
+### Framework examples
+
+- [Vercel AI SDK](./examples/vercel) launches the stdio server through the AI SDK MCP client and keeps one process alive for the complete agent run.
+
 ### Configuration
 
 `stagehandCodeConfigFromEnv()` recognizes:

packages/integrations/examples/vercel/README.md

@@ -0,0 +1,17 @@
+# Vercel AI SDK + Stagehand code mode
+
+This example connects the Vercel AI SDK to the workspace's canonical Stagehand code-mode MCP server
+over stdio. One MCP client remains open for the complete `generateText` call, so repeated
+`code_execute` calls share the same browser context.
+
+The MCP child reads the normal code-mode startup environment. Set `STAGEHAND_BROWSER=local` for a
+local headless browser or `STAGEHAND_BROWSER=browserbase` with Browserbase credentials for a remote
+browser.
+
+```bash
+pnpm --filter @browserbasehq/stagehand-integrations build
+STAGEHAND_BROWSER=local pnpm --filter @browserbasehq/stagehand-integrations-example-vercel smoke
+```
+
+See [`src/agent.ts`](./src/agent.ts) for the reusable connection lifecycle and
+[`src/e2e.ts`](./src/e2e.ts) for a real model-driven example.

packages/integrations/examples/vercel/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@browserbasehq/stagehand-integrations-example-vercel",
+  "version": "4.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "e2e": "tsx src/e2e.ts",
+    "smoke": "tsx src/smoke.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/groq": "catalog:",
+    "@ai-sdk/mcp": "catalog:",
+    "@browserbasehq/stagehand-integrations": "workspace:*",
+    "ai": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "catalog:"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

packages/integrations/examples/vercel/src/agent.ts

@@ -0,0 +1,66 @@
+import { fileURLToPath } from "node:url";
+import { createMCPClient, type MCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+import { STAGEHAND_CODEMODE_SKILL } from "@browserbasehq/stagehand-integrations/codemode";
+import { generateText, stepCountIs, type LanguageModel } from "ai";
+
+const DEFAULT_STDIO_SERVER_PATH = fileURLToPath(
+  new URL("../../../dist/codemode/stdio-server.mjs", import.meta.url),
+);
+
+export type StagehandMcpBinding = {
+  client: MCPClient;
+  tools: Awaited<ReturnType<MCPClient["tools"]>>;
+};
+
+export type StagehandAgentResult = {
+  text: string;
+  toolNames: string[];
+};
+
+export async function createStagehandMcpBinding(
+  stdioServerPath = DEFAULT_STDIO_SERVER_PATH,
+): Promise<StagehandMcpBinding> {
+  const client = await createMCPClient({
+    transport: new Experimental_StdioMCPTransport({
+      command: process.execPath,
+      args: [stdioServerPath],
+      env: definedEnvironment(),
+    }),
+  });
+
+  return {
+    client,
+    tools: await client.tools(),
+  };
+}
+
+export async function runStagehandAgent(
+  model: LanguageModel,
+  prompt: string,
+): Promise<StagehandAgentResult> {
+  const { client, tools } = await createStagehandMcpBinding();
+  try {
+    const result = await generateText({
+      model,
+      system: STAGEHAND_CODEMODE_SKILL,
+      prompt,
+      tools,
+      stopWhen: stepCountIs(8),
+    });
+    return {
+      text: result.text,
+      toolNames: result.steps.flatMap((step) => step.toolCalls.map((call) => call.toolName)),
+    };
+  } finally {
+    await client.close();
+  }
+}
+
+function definedEnvironment(): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(process.env).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  );
+}

packages/integrations/examples/vercel/src/e2e.ts

@@ -0,0 +1,25 @@
+import { groq } from "@ai-sdk/groq";
+import { runStagehandAgent } from "./agent.js";
+
+process.env.STAGEHAND_BROWSER ??= "local";
+
+const result = await runStagehandAgent(
+  groq(process.env.VERCEL_STAGEHAND_MODEL ?? "openai/gpt-oss-120b"),
+  [
+    "Use code_execute exactly twice.",
+    "First navigate to https://example.com, open one additional blank tab, then restore the Example Domain page as active.",
+    "Second return the active page title and total context page count.",
+    "Report the title and count in your final answer.",
+  ].join(" "),
+);
+
+if (
+  result.toolNames.length !== 2 ||
+  result.toolNames.some((name) => name !== "code_execute") ||
+  !result.text.includes("Example Domain") ||
+  !result.text.includes("2")
+) {
+  throw new Error(`Unexpected agent result: ${JSON.stringify(result)}`);
+}
+
+process.stdout.write(`${JSON.stringify({ status: "PASS", ...result })}\n`);

packages/integrations/examples/vercel/src/smoke.ts

@@ -0,0 +1,52 @@
+import { createStagehandMcpBinding } from "./agent.js";
+import type { Tool } from "ai";
+
+process.env.STAGEHAND_BROWSER ??= "local";
+
+const { client, tools } = await createStagehandMcpBinding();
+try {
+  const names = Object.keys(tools);
+  if (names.length !== 1 || names[0] !== "code_execute") {
+    throw new Error(`Expected one code_execute tool, got ${names.join(", ")}`);
+  }
+
+  const tool = tools.code_execute as Tool<{ code: string }, unknown>;
+  if (typeof tool?.execute !== "function") {
+    throw new Error("Vercel AI SDK did not expose code_execute as executable.");
+  }
+  const description =
+    typeof tool.description === "function" ? tool.description({ context: {} }) : tool.description;
+  if (!description?.includes("Stagehand V4 code-mode syntax")) {
+    throw new Error("code_execute did not include the canonical Stagehand guidance.");
+  }
+
+  const first = await tool.execute(
+    {
+      code: `
+        await page.goto("https://example.com", { waitUntil: "load" });
+        await context.newPage();
+        await context.setActivePage(page);
+        return { title: await page.title(), pages: (await context.pages()).length };
+      `,
+    },
+    { context: {}, messages: [], toolCallId: "vercel-smoke-1" },
+  );
+  const second = await tool.execute(
+    {
+      code: `return { title: await page.title(), pages: (await context.pages()).length };`,
+    },
+    { context: {}, messages: [], toolCallId: "vercel-smoke-2" },
+  );
+
+  const firstText = JSON.stringify(first);
+  const secondText = JSON.stringify(second);
+  if (!firstText.includes("Example Domain") || !secondText.includes('"pages":2')) {
+    throw new Error(`Expected browser state to persist across calls: ${firstText} ${secondText}`);
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({ status: "PASS", tools: names, statePersisted: true })}\n`,
+  );
+} finally {
+  await client.close();
+}

packages/integrations/examples/vercel/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "target": "ES2022",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

pnpm-workspace.yaml

@@ -1,9 +1,11 @@
 packages:
   - packages/*
+  - packages/integrations/examples/*
 
 catalogMode: prefer
 
 catalog:
+  "@ai-sdk/mcp": 2.0.8
   "@modelcontextprotocol/sdk": 1.29.0
   "@ast-grep/lang-go": 0.0.6
   "@ast-grep/lang-python": 0.0.6