Update stagehand template to v4 (#221)

Author: dprevoznik

pkg/templates/typescript/stagehand/.env.example

@@ -1,2 +1,4 @@
-# Copy this file to .env and fill in your API key
-OPENAI_API_KEY=your_openai_api_key_here
+# Copy this file to .env and set the model and its API key.
+# MODEL is provider-prefixed, e.g. anthropic/claude-sonnet-4-5, openai/gpt-4.1, google/gemini-2.5-flash
+MODEL=anthropic/claude-sonnet-4-5
+MODEL_API_KEY=your_api_key_here

pkg/templates/typescript/stagehand/README.md

@@ -1,11 +1,19 @@
-# Kernel TypeScript Sample App - Stagehand
+# Kernel TypeScript Sample App - Stagehand (v4)
 
-A Stagehand-powered browser automation app that extracts team size information from Y Combinator company pages.
+A [Stagehand v4](https://docs.stagehand.dev) browser automation app that extracts team size information from Y Combinator company pages, running against a Kernel cloud browser.
 
 ## What it does
 
 The `teamsize-task` searches for a startup on Y Combinator's company directory and extracts the team size (number of employees).
 
+## How Stagehand v4 connects to a Kernel browser
+
+Stagehand v4 no longer drives the browser purely over CDP — it runs as a **Chrome extension** next to the browser. To use it with a remote Kernel browser, this template:
+
+1. Creates a Kernel browser.
+2. Uploads the Stagehand extension (shipped inside the `@browserbasehq/stagehand` package) onto the running browser's filesystem, at the path Stagehand loads it from.
+3. Connects with `localBrowser.connect({ cdpUrl })` — with no `extensionId`, Stagehand loads the extension into the running browser over CDP (`Extensions.loadUnpacked`) — and `Stagehand.create({ browser })`.
+
 ## Input
 
 ```json
@@ -24,12 +32,15 @@ The `teamsize-task` searches for a startup on Y Combinator's company directory a
 
 ## Setup
 
-Create a `.env` file:
+Create a `.env` file with a provider-prefixed `MODEL` and its API key:
 
 ```
-OPENAI_API_KEY=your-openai-api-key
+MODEL=anthropic/claude-sonnet-4-5
+MODEL_API_KEY=your-api-key
 ```
 
+`MODEL` can be any provider Stagehand supports, e.g. `openai/gpt-4.1` or `google/gemini-2.5-flash`.
+
 ## Deploy
 
 ```bash

pkg/templates/typescript/stagehand/index.ts

@@ -1,10 +1,12 @@
-import { Stagehand } from "@browserbasehq/stagehand";
-import { Kernel, type KernelContext } from '@onkernel/sdk';
-import { z } from 'zod';
+import { Stagehand, localBrowser, type ModelName } from "@browserbasehq/stagehand";
+import { Kernel, type KernelContext } from "@onkernel/sdk";
+// Stagehand v4 uses zod v4 schema types.
+import { z } from "zod";
+import { loadStagehandExtension } from "./stagehand-extension";
 
 const kernel = new Kernel();
 
-const app = kernel.app('ts-stagehand');
+const app = kernel.app("ts-stagehand");
 
 interface CompanyInput {
   company: string;
@@ -14,17 +16,19 @@ interface TeamSizeOutput {
   teamSize: string;
 }
 
-// LLM API Keys are set in the environment during `kernel deploy <filename> -e OPENAI_API_KEY=XXX`
+// Set MODEL (provider-prefixed, e.g. anthropic/claude-sonnet-4-5, openai/gpt-4.1,
+// google/gemini-2.5-flash) and MODEL_API_KEY for that provider in the environment
+// during `kernel deploy <filename> -e MODEL=XXX -e MODEL_API_KEY=YYY`.
 // See https://www.kernel.sh/docs/apps/deploy#environment-variables
+const MODEL = process.env.MODEL as ModelName | undefined;
+const MODEL_API_KEY = process.env.MODEL_API_KEY;
 
-const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
-
-if (!OPENAI_API_KEY) {
-  throw new Error('OPENAI_API_KEY is not set');
+if (!MODEL || !MODEL_API_KEY) {
+  throw new Error("MODEL and MODEL_API_KEY must be set");
 }
 
 app.action<CompanyInput, TeamSizeOutput>(
-  'teamsize-task',
+  "teamsize-task",
   async (ctx: KernelContext, payload?: CompanyInput): Promise<TeamSizeOutput> => {
     // A function that returns the team size of a Y Combinator startup
 
@@ -35,7 +39,7 @@ app.action<CompanyInput, TeamSizeOutput>(
     // Returns:
     //     output: The team size (number of employees) of the startup
 
-    const company = payload?.company || 'kernel';
+    const company = payload?.company || "kernel";
 
     const kernelBrowser = await kernel.browsers.create({
       invocation_id: ctx.invocation_id,
@@ -44,39 +48,51 @@ app.action<CompanyInput, TeamSizeOutput>(
 
     console.log("Kernel browser live view url: ", kernelBrowser.browser_live_view_url);
 
-    const stagehand = new Stagehand({
-      env: "LOCAL",
-      localBrowserLaunchOptions: {
+    // Stagehand only closes browsers it launched, so we close the connection and
+    // delete the Kernel browser ourselves, even if the automation throws.
+    let stagehand: Awaited<ReturnType<typeof Stagehand.create>> | undefined;
+    let browser: Awaited<ReturnType<typeof localBrowser.connect>> | undefined;
+    try {
+      // Load the Stagehand extension into the running browser. With no
+      // `extensionId`, `localBrowser.connect` then loads it over CDP.
+      await loadStagehandExtension(kernel, kernelBrowser.session_id);
+      browser = await localBrowser.connect({
         cdpUrl: kernelBrowser.cdp_ws_url,
-      },
-      model: "openai/gpt-4.1",
-      apiKey: OPENAI_API_KEY,
-      verbose: 1,
-      domSettleTimeout: 30_000
-    });
-    await stagehand.init();
-
-    /////////////////////////////////////
-    // Your Stagehand implementation here
-    /////////////////////////////////////
-    const page = stagehand.context.pages()[0];
-    await page.goto("https://www.ycombinator.com/companies");
-
-    await stagehand.act(`Type in ${company} into the search box`);
-    await stagehand.act("Click on the first search result");
-
-    // Schema definition
-    const teamSizeSchema = z.object({
-      teamSize: z.string(),
-    });
-    // Extract team size from the YC startup page
-    const output = await stagehand.extract(
-      "Extract the team size (number of employees) shown on this Y Combinator company page.",
-      teamSizeSchema
-    );
-    await stagehand.close();
-    await kernel.browsers.deleteByID(kernelBrowser.session_id);
-
-    return output;
+      });
+      stagehand = await Stagehand.create({
+        browser,
+        model: { modelName: MODEL, apiKey: MODEL_API_KEY },
+        logging: { level: "info" },
+      });
+
+      /////////////////////////////////////
+      // Your Stagehand implementation here
+      /////////////////////////////////////
+      const page = await browser.context.activePage();
+      if (!page) throw new Error("No active page in the Kernel browser");
+      await page.goto("https://www.ycombinator.com/companies");
+
+      await stagehand.act(`Type in ${company} into the search box`);
+      await stagehand.act("Click on the first search result");
+
+      // Extract team size from the YC startup page. Every v4 primitive returns { data }.
+      const { data } = await stagehand.extract(
+        "Extract the team size (number of employees) shown on this Y Combinator company page.",
+        z.object({ teamSize: z.string() }),
+      );
+
+      return data;
+    } finally {
+      // Nested so a rejected close() never skips deleting the Kernel browser.
+      try {
+        await stagehand?.close();
+      } finally {
+        try {
+          await browser?.close();
+        } finally {
+          await kernel.browsers.deleteByID(kernelBrowser.session_id);
+        }
+      }
+    }
   },
 );

pkg/templates/typescript/stagehand/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "private": true,
   "dependencies": {
-    "@browserbasehq/stagehand": "^3.5.0",
+    "@browserbasehq/stagehand": "^4.0.0",
     "@onkernel/sdk": "^0.23.0",
     "zod": "^4.2.0"
   },