@browserbasehq/orca 3.0.0-preview.0 → 3.0.0-preview.3

package/package.json

@@ -1,37 +1,10 @@
 {
   "name": "@browserbasehq/orca",
-  "version": "3.0.0-preview.0",
+  "version": "3.0.0-preview.3",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "evals": "./dist/evals/cli.js"
-  },
-  "scripts": {
-    "example": "pnpm --filter @browserbasehq/stagehand-examples run start",
-    "format": "prettier --write .",
-    "prettier": "prettier --check .",
-    "prettier:fix": "prettier --write .",
-    "eslint": "eslint .",
-    "cache:clear": "rm -rf .cache",
-    "docs": "pnpm --filter @browserbasehq/stagehand-docs run dev",
-    "evals": "tsx scripts/run-evals.ts",
-    "evals:legacy": "tsx scripts/run-evals.ts",
-    "e2e": "pnpm run build && cd evals/deterministic && playwright test --config=e2e.playwright.config.ts",
-    "e2e:bb": "pnpm run build && cd evals/deterministic && playwright test --config=bb.playwright.config.ts",
-    "e2e:local": "pnpm run build && cd evals/deterministic && playwright test --config=local.playwright.config.ts",
-    "build-v3-dom-scripts": "tsx lib/v3/dom/genDomScripts.ts",
-    "build-types": "tsc --emitDeclarationOnly --outDir dist",
-    "build-js": "tsup --entry.index lib/v3/index.ts --dts",
-    "build:cli": "tsup evals/cli.ts --outDir dist/evals --format cjs && cp evals/evals.config.json dist/evals/ && chmod +x dist/evals/cli.js && npm link",
-    "build": "pnpm run lint && pnpm run gen-version && pnpm run build-v3-dom-scripts && pnpm run build-js && pnpm run build-types",
-    "gen-version": "tsx scripts/gen-version.ts",
-    "prepare": "pnpm run build",
-    "lint": "pnpm run prettier:fix && pnpm run eslint",
-    "release": "pnpm run build && changeset publish",
-    "release-canary": "pnpm run build && changeset version --snapshot && changeset publish --tag alpha"
-  },
   "files": [
     "dist/index.js",
     "dist/index.d.ts",
@@ -39,43 +12,15 @@
     "dist/types",
     "dist/stagehand.config.d.ts"
   ],
-  "keywords": [],
+  "keywords": [
+    "ai",
+    "browser",
+    "automation",
+    "web-scraping",
+    "testing"
+  ],
   "author": "Browserbase",
   "license": "MIT",
-  "devDependencies": {
-    "@changesets/changelog-github": "^0.5.0",
-    "@changesets/cli": "^2.27.9",
-    "@eslint/js": "^9.16.0",
-    "@langchain/core": "^0.3.40",
-    "@langchain/openai": "^0.4.4",
-    "playwright-core": "^1.54.1",
-    "puppeteer-core": "^22.8.0",
-    "chrome-launcher": "^1.2.0",
-    "patchright-core": "^1.55.2",
-    "@playwright/test": "^1.42.1",
-    "@types/adm-zip": "^0.5.7",
-    "@types/cheerio": "^0.22.35",
-    "@types/express": "^4.17.21",
-    "@types/node": "^20.11.30",
-    "@types/ws": "^8.5.13",
-    "adm-zip": "^0.5.16",
-    "autoevals": "^0.0.64",
-    "braintrust": "^0.0.171",
-    "chalk": "^5.4.1",
-    "cheerio": "^1.0.0",
-    "chromium-bidi": "^0.10.0",
-    "esbuild": "^0.21.4",
-    "eslint": "^9.16.0",
-    "express": "^4.21.0",
-    "globals": "^15.13.0",
-    "multer": "^1.4.5-lts.1",
-    "prettier": "^3.2.5",
-    "string-comparison": "^1.3.0",
-    "tsup": "^8.2.1",
-    "tsx": "^4.10.5",
-    "typescript": "^5.2.2",
-    "typescript-eslint": "^8.17.0"
-  },
   "peerDependencies": {
     "deepmerge": "^4.3.1",
     "dotenv": "^16.4.5",
@@ -84,7 +29,8 @@
   "dependencies": {
     "@anthropic-ai/sdk": "0.39.0",
     "@browserbasehq/sdk": "^2.4.0",
-    "@google/genai": "^0.8.0",
+    "@google/genai": "^1.22.0",
+    "@langchain/openai": "^0.4.4",
     "@modelcontextprotocol/sdk": "^1.17.2",
     "ai": "^4.3.9",
     "devtools-protocol": "^0.0.1464554",
@@ -108,23 +54,38 @@
     "@ai-sdk/perplexity": "^1.1.7",
     "@ai-sdk/togetherai": "^0.2.6",
     "@ai-sdk/xai": "^1.2.15",
+    "@langchain/core": "^0.3.40",
+    "playwright-core": "^1.54.1",
+    "puppeteer-core": "^22.8.0",
+    "chrome-launcher": "^1.2.0",
+    "patchright-core": "^1.55.2",
     "ollama-ai-provider": "^1.2.0"
   },
-  "directories": {
-    "doc": "docs",
-    "example": "examples",
-    "lib": "lib"
+  "devDependencies": {
+    "@playwright/test": "^1.42.1",
+    "typescript": "^5.2.2",
+    "tsup": "^8.2.1",
+    "tsx": "^4.10.5",
+    "prettier": "^3.2.5",
+    "eslint": "^9.16.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/browserbase/stagehand.git"
+    "url": "git+https://github.com/browserbase/stagehand.git",
+    "directory": "packages/core"
   },
   "bugs": {
     "url": "https://github.com/browserbase/stagehand/issues"
   },
   "homepage": "https://stagehand.dev",
-  "overrides": {
-    "whatwg-url": "^14.0.0"
-  },
-  "packageManager": "pnpm@9.15.0+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"
-}
+  "scripts": {
+    "gen-version": "tsx scripts/gen-version.ts",
+    "build-dom-scripts": "tsx lib/v3/dom/genDomScripts.ts && tsx lib/v3/dom/genLocatorScripts.ts",
+    "build-js": "tsup --entry.index lib/v3/index.ts --dts",
+    "typecheck": "tsc --noEmit",
+    "build": "pnpm run gen-version && pnpm run build-dom-scripts && pnpm run build-js && pnpm run typecheck",
+    "example": "node --import tsx -e \"const args=process.argv.slice(1).filter(a=>a!=='--'); const [p]=args; const n=(p||'example').replace(/^\\.\\//,'').replace(/\\.ts$/i,''); import(new URL(require('node:path').resolve('examples', n + '.ts'), 'file:'));\" --",
+    "lint": "cd ../.. && prettier --check packages/core && cd packages/core && eslint .",
+    "format": "prettier --write ."
+  }
+}

package/README.md

@@ -1,165 +0,0 @@
-<div id="toc" align="center" style="margin-bottom: 0;">
-  <ul style="list-style: none; margin: 0; padding: 0;">
-    <a href="https://stagehand.dev">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="media/dark_logo.png" />
-        <img alt="Stagehand" src="media/light_logo.png" width="200" style="margin-right: 30px;" />
-      </picture>
-    </a>
-  </ul>
-</div>
-<p align="center">
-  <strong>The AI Browser Automation Framework</strong><br>
-  <a href="https://docs.stagehand.dev">Read the Docs</a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/browserbase/stagehand/tree/main?tab=MIT-1-ov-file#MIT-1-ov-file">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="media/dark_license.svg" />
-      <img alt="MIT License" src="media/light_license.svg" />
-    </picture>
-  </a>
-  <a href="https://join.slack.com/t/stagehand-dev/shared_invite/zt-38khc8iv5-T2acb50_0OILUaX7lxeBOg">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="media/dark_slack.svg" />
-      <img alt="Slack Community" src="media/light_slack.svg" />
-    </picture>
-  </a>
-</p>
-
-<p align="center">
-	<a href="https://trendshift.io/repositories/12122" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12122" alt="browserbase%2Fstagehand | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-</p>
-
-<p align="center">
-If you're looking for the Python implementation, you can find it 
-<a href="https://github.com/browserbase/stagehand-python"> here</a>
-</p>
-
-<div align="center" style="display: flex; align-items: center; justify-content: center; gap: 4px; margin-bottom: 0;">
-  <b>Vibe code</b>
-  <span style="font-size: 1.05em;"> Stagehand with </span>
-  <a href="https://director.ai" style="display: flex; align-items: center;">
-    <span>Director</span>
-  </a>
-  <span> </span>
-  <picture>
-    <img alt="Director" src="media/director_icon.svg" width="25" />
-  </picture>
-</div>
-
-## Why Stagehand?
-
-Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production. By letting developers choose what to write in code vs. natural language, Stagehand is the natural choice for browser automations in production.
-
-1. **Choose when to write code vs. natural language**: use AI when you want to navigate unfamiliar pages, and use code ([Playwright](https://playwright.dev/)) when you know exactly what you want to do.
-
-2. **Preview and cache actions**: Stagehand lets you preview AI actions before running them, and also helps you easily cache repeatable actions to save time and tokens.
-
-3. **Computer use models with one line of code**: Stagehand lets you integrate SOTA computer use models from OpenAI and Anthropic into the browser with one line of code.
-
-## Example
-
-Here's how to build a sample browser automation with Stagehand:
-
-<div align="center">
-  <div style="max-width:300px;">
-    <img src="/media/github_demo.gif" alt="See Stagehand in Action">
-  </div>
-</div>
-
-```typescript
-// Use Playwright functions on the page object
-const page = stagehand.page;
-await page.goto("https://github.com/browserbase");
-
-// Use act() to execute individual actions
-await page.act("click on the stagehand repo");
-
-// Use Computer Use agents for larger actions
-const agent = stagehand.agent({
-    provider: "openai",
-    model: "computer-use-preview",
-});
-await agent.execute("Get to the latest PR");
-
-// Use extract() to read data from the page
-const { author, title } = await page.extract({
-  instruction: "extract the author and title of the PR",
-  schema: z.object({
-    author: z.string().describe("The username of the PR author"),
-    title: z.string().describe("The title of the PR"),
-  }),
-});
-```
-
-## Documentation
-
-Visit [docs.stagehand.dev](https://docs.stagehand.dev) to view the full documentation.
-
-## Getting Started
-
-Start with Stagehand with one line of code, or check out our [Quickstart Guide](https://docs.stagehand.dev/get_started/quickstart) for more information:
-
-```bash
-npx create-browser-app
-```
-
-<div align="center">
-    <a href="https://www.loom.com/share/f5107f86d8c94fa0a8b4b1e89740f7a7">
-      <p>Watch Anirudh demo create-browser-app to create a Stagehand project!</p>
-    </a>
-    <a href="https://www.loom.com/share/f5107f86d8c94fa0a8b4b1e89740f7a7">
-      <img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/f5107f86d8c94fa0a8b4b1e89740f7a7-ec3f428b6775ceeb-full-play.gif">
-    </a>
-  </div>
-
-### Build and Run from Source
-
-```bash
-git clone https://github.com/browserbase/stagehand.git
-cd stagehand
-pnpm install
-pnpm playwright install
-pnpm run build
-pnpm run example # run the blank script at ./examples/example.ts
-pnpm run example 2048 # run the 2048 example at ./examples/2048.ts
-pnpm run evals -man # see evaluation suite options
-```
-
-Stagehand is best when you have an API key for an LLM provider and Browserbase credentials. To add these to your project, run:
-
-```bash
-cp .env.example .env
-nano .env # Edit the .env file to add API keys
-```
-
-## Contributing
-
-> [!NOTE]  
-> We highly value contributions to Stagehand! For questions or support, please join our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-38khc8iv5-T2acb50_0OILUaX7lxeBOg).
-
-At a high level, we're focused on improving reliability, speed, and cost in that order of priority. If you're interested in contributing, we strongly recommend reaching out to [Miguel Gonzalez](https://x.com/miguel_gonzf) or [Paul Klein](https://x.com/pk_iv) in our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-38khc8iv5-T2acb50_0OILUaX7lxeBOg) before starting to ensure that your contribution aligns with our goals.
-
-For more information, please see our [Contributing Guide](https://docs.stagehand.dev/examples/contributing).
-
-## Acknowledgements
-
-This project heavily relies on [Playwright](https://playwright.dev/) as a resilient backbone to automate the web. It also would not be possible without the awesome techniques and discoveries made by [tarsier](https://github.com/reworkd/tarsier), [gemini-zod](https://github.com/jbeoris/gemini-zod), and [fuji-web](https://github.com/normal-computing/fuji-web).
-
-We'd like to thank the following people for their major contributions to Stagehand:
-- [Paul Klein](https://github.com/pkiv)
-- [Anirudh Kamath](https://github.com/kamath)
-- [Sean McGuire](https://github.com/seanmcguire12)
-- [Miguel Gonzalez](https://github.com/miguelg719)
-- [Sameel Arif](https://github.com/sameelarif)
-- [Filip Michalsky](https://github.com/filip-michalsky)
-- [Jeremy Press](https://x.com/jeremypress)
-- [Navid Pour](https://github.com/navidpour)
-
-## License
-
-Licensed under the MIT License.
-
-Copyright 2025 Browserbase, Inc.

package/dist/lib/api.d.ts

@@ -1,23 +0,0 @@
-import { z } from "zod/v3";
-import { StagehandAPIConstructorParams, StartSessionParams, StartSessionResult } from "./v3/types/api";
-import { GotoOptions } from "./v3/types/playwright";
-import { ActOptions, ActResult, AgentConfig, ExtractOptions, ExtractResult, ObserveOptions, Action } from "./v3/types/stagehand";
-import { AgentExecuteOptions, AgentResult } from "@/lib/v3/types/agent";
-export declare class StagehandAPI {
-    private apiKey;
-    private projectId;
-    private sessionId?;
-    private modelApiKey;
-    private logger;
-    private fetchWithCookies;
-    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
-    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, debugDom, systemPrompt, selfHeal, waitForCaptchaSolves, actionTimeoutMs, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
-    act(options: ActOptions | Action): Promise<ActResult>;
-    extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
-    observe(options?: ObserveOptions): Promise<Action[]>;
-    goto(url: string, options?: GotoOptions): Promise<void>;
-    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions): Promise<AgentResult>;
-    end(): Promise<Response>;
-    private execute;
-    private request;
-}

package/dist/lib/dom/build/scriptContent.d.ts

@@ -1 +0,0 @@
-export declare const scriptContent = "(() => {\n  // lib/dom/elementCheckUtils.ts\n  function isElementNode(node) {\n    return node.nodeType === Node.ELEMENT_NODE;\n  }\n  function isTextNode(node) {\n    return node.nodeType === Node.TEXT_NODE && Boolean(node.textContent?.trim());\n  }\n\n  // lib/dom/xpathUtils.ts\n  function getParentElement(node) {\n    return isElementNode(node) ? node.parentElement : node.parentNode;\n  }\n  function getCombinations(attributes, size) {\n    const results = [];\n    function helper(start, combo) {\n      if (combo.length === size) {\n        results.push([...combo]);\n        return;\n      }\n      for (let i = start; i < attributes.length; i++) {\n        combo.push(attributes[i]);\n        helper(i + 1, combo);\n        combo.pop();\n      }\n    }\n    helper(0, []);\n    return results;\n  }\n  function isXPathFirstResultElement(xpath, target) {\n    try {\n      const result = document.evaluate(\n        xpath,\n        document.documentElement,\n        null,\n        XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n        null\n      );\n      return result.snapshotItem(0) === target;\n    } catch (error) {\n      console.warn(`Invalid XPath expression: ${xpath}`, error);\n      return false;\n    }\n  }\n  function escapeXPathString(value) {\n    if (value.includes(\"'\")) {\n      if (value.includes('\"')) {\n        return \"concat(\" + value.split(/('+)/).map((part) => {\n          if (part === \"'\") {\n            return `\"'\"`;\n          } else if (part.startsWith(\"'\") && part.endsWith(\"'\")) {\n            return `\"${part}\"`;\n          } else {\n            return `'${part}'`;\n          }\n        }).join(\",\") + \")\";\n      } else {\n        return `\"${value}\"`;\n      }\n    } else {\n      return `'${value}'`;\n    }\n  }\n  async function generateXPathsForElement(element) {\n    if (!element) return [];\n    const [complexXPath, standardXPath, idBasedXPath] = await Promise.all([\n      generateComplexXPath(element),\n      generateStandardXPath(element),\n      generatedIdBasedXPath(element)\n    ]);\n    return [standardXPath, ...idBasedXPath ? [idBasedXPath] : [], complexXPath];\n  }\n  async function generateComplexXPath(element) {\n    const parts = [];\n    let currentElement = element;\n    while (currentElement && (isTextNode(currentElement) || isElementNode(currentElement))) {\n      if (isElementNode(currentElement)) {\n        const el = currentElement;\n        let selector = el.tagName.toLowerCase();\n        const attributePriority = [\n          \"data-qa\",\n          \"data-component\",\n          \"data-role\",\n          \"role\",\n          \"aria-role\",\n          \"type\",\n          \"name\",\n          \"aria-label\",\n          \"placeholder\",\n          \"title\",\n          \"alt\"\n        ];\n        const attributes = attributePriority.map((attr) => {\n          let value = el.getAttribute(attr);\n          if (attr === \"href-full\" && value) {\n            value = el.getAttribute(\"href\");\n          }\n          return value ? { attr: attr === \"href-full\" ? \"href\" : attr, value } : null;\n        }).filter((attr) => attr !== null);\n        let uniqueSelector = \"\";\n        for (let i = 1; i <= attributes.length; i++) {\n          const combinations = getCombinations(attributes, i);\n          for (const combo of combinations) {\n            const conditions = combo.map((a) => `@${a.attr}=${escapeXPathString(a.value)}`).join(\" and \");\n            const xpath2 = `//${selector}[${conditions}]`;\n            if (isXPathFirstResultElement(xpath2, el)) {\n              uniqueSelector = xpath2;\n              break;\n            }\n          }\n          if (uniqueSelector) break;\n        }\n        if (uniqueSelector) {\n          parts.unshift(uniqueSelector.replace(\"//\", \"\"));\n          break;\n        } else {\n          const parent = getParentElement(el);\n          if (parent) {\n            const siblings = Array.from(parent.children).filter(\n              (sibling) => sibling.tagName === el.tagName\n            );\n            const index = siblings.indexOf(el) + 1;\n            selector += siblings.length > 1 ? `[${index}]` : \"\";\n          }\n          parts.unshift(selector);\n        }\n      }\n      currentElement = getParentElement(currentElement);\n    }\n    const xpath = \"//\" + parts.join(\"/\");\n    return xpath;\n  }\n  async function generateStandardXPath(element) {\n    const parts = [];\n    while (element && (isTextNode(element) || isElementNode(element))) {\n      let index = 0;\n      let hasSameTypeSiblings = false;\n      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];\n      for (let i = 0; i < siblings.length; i++) {\n        const sibling = siblings[i];\n        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {\n          index = index + 1;\n          hasSameTypeSiblings = true;\n          if (sibling.isSameNode(element)) {\n            break;\n          }\n        }\n      }\n      if (element.nodeName !== \"#text\") {\n        const tagName = element.nodeName.toLowerCase();\n        const pathIndex = hasSameTypeSiblings ? `[${index}]` : \"\";\n        parts.unshift(`${tagName}${pathIndex}`);\n      }\n      element = element.parentElement;\n    }\n    return parts.length ? `/${parts.join(\"/\")}` : \"\";\n  }\n  async function generatedIdBasedXPath(element) {\n    if (isElementNode(element) && element.id) {\n      return `//*[@id='${element.id}']`;\n    }\n    return null;\n  }\n\n  // types/stagehandErrors.ts\n  var StagehandError = class extends Error {\n    constructor(message) {\n      super(message);\n      this.name = this.constructor.name;\n    }\n  };\n  var StagehandDomProcessError = class extends StagehandError {\n    constructor(message) {\n      super(`Error Processing Dom: ${message}`);\n    }\n  };\n\n  // lib/dom/utils.ts\n  function canElementScroll(elem) {\n    if (typeof elem.scrollTo !== \"function\") {\n      console.warn(\"canElementScroll: .scrollTo is not a function.\");\n      return false;\n    }\n    try {\n      const originalTop = elem.scrollTop;\n      elem.scrollTo({\n        top: originalTop + 100,\n        left: 0,\n        behavior: \"instant\"\n      });\n      if (elem.scrollTop === originalTop) {\n        throw new StagehandDomProcessError(\"scrollTop did not change\");\n      }\n      elem.scrollTo({\n        top: originalTop,\n        left: 0,\n        behavior: \"instant\"\n      });\n      return true;\n    } catch (error) {\n      console.warn(\"canElementScroll error:\", error.message || error);\n      return false;\n    }\n  }\n  function getNodeFromXpath(xpath) {\n    return document.evaluate(\n      xpath,\n      document.documentElement,\n      null,\n      XPathResult.FIRST_ORDERED_NODE_TYPE,\n      null\n    ).singleNodeValue;\n  }\n  function waitForElementScrollEnd(element, idleMs = 100) {\n    return new Promise((resolve) => {\n      let scrollEndTimer;\n      const handleScroll = () => {\n        clearTimeout(scrollEndTimer);\n        scrollEndTimer = window.setTimeout(() => {\n          element.removeEventListener(\"scroll\", handleScroll);\n          resolve();\n        }, idleMs);\n      };\n      element.addEventListener(\"scroll\", handleScroll, { passive: true });\n      handleScroll();\n    });\n  }\n\n  // lib/dom/process.ts\n  function getScrollableElements(topN) {\n    const docEl = document.documentElement;\n    const scrollableElements = [docEl];\n    const allElements = document.querySelectorAll(\"*\");\n    for (const elem of allElements) {\n      const style = window.getComputedStyle(elem);\n      const overflowY = style.overflowY;\n      const isPotentiallyScrollable = overflowY === \"auto\" || overflowY === \"scroll\" || overflowY === \"overlay\";\n      if (isPotentiallyScrollable) {\n        const candidateScrollDiff = elem.scrollHeight - elem.clientHeight;\n        if (candidateScrollDiff > 0 && canElementScroll(elem)) {\n          scrollableElements.push(elem);\n        }\n      }\n    }\n    scrollableElements.sort((a, b) => b.scrollHeight - a.scrollHeight);\n    if (topN !== void 0) {\n      return scrollableElements.slice(0, topN);\n    }\n    return scrollableElements;\n  }\n  async function getScrollableElementXpaths(topN) {\n    const scrollableElems = getScrollableElements(topN);\n    const xpaths = [];\n    for (const elem of scrollableElems) {\n      const allXPaths = await generateXPathsForElement(elem);\n      const firstXPath = allXPaths?.[0] || \"\";\n      xpaths.push(firstXPath);\n    }\n    return xpaths;\n  }\n  (() => {\n    const closedRoots = /* @__PURE__ */ new WeakMap();\n    const nativeAttachShadow = Element.prototype.attachShadow;\n    Element.prototype.attachShadow = function(init) {\n      const root = nativeAttachShadow.call(this, init);\n      if (init.mode === \"closed\") closedRoots.set(this, root);\n      return root;\n    };\n    const backdoor = {\n      getClosedRoot: (host) => closedRoots.get(host),\n      queryClosed: (host, selector) => {\n        const root = closedRoots.get(host);\n        return root ? Array.from(root.querySelectorAll(selector)) : [];\n      },\n      xpathClosed: (host, xp) => {\n        const root = closedRoots.get(host);\n        if (!root) return [];\n        const it = document.evaluate(\n          xp,\n          root,\n          null,\n          XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n          null\n        );\n        const out = [];\n        for (let i = 0; i < it.snapshotLength; ++i) {\n          const n = it.snapshotItem(i);\n          if (n) out.push(n);\n        }\n        return out;\n      }\n    };\n    if (!(\"__stagehand__\" in window)) {\n      Object.defineProperty(window, \"__stagehand__\", {\n        value: backdoor,\n        enumerable: false,\n        writable: false,\n        configurable: false\n      });\n    }\n  })();\n  window.getScrollableElementXpaths = getScrollableElementXpaths;\n  window.getNodeFromXpath = getNodeFromXpath;\n  window.waitForElementScrollEnd = waitForElementScrollEnd;\n})();\n";

package/dist/lib/inference.d.ts

@@ -1,71 +0,0 @@
-import { z } from "zod/v3";
-import { LogLine } from "./v3/types/log";
-import { LLMClient } from "./v3/llm/LLMClient";
-/** Simple usage shape if your LLM returns usage tokens. */
-interface LLMUsage {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-}
-/**
- * For calls that use a schema: the LLMClient may return { data: T; usage?: LLMUsage }
- */
-export interface LLMParsedResponse<T> {
-    data: T;
-    usage?: LLMUsage;
-}
-export declare function extract({ instruction, domElements, schema, llmClient, logger, userProvidedInstructions, logInferenceToFile, }: {
-    instruction: string;
-    domElements: string;
-    schema: z.ZodObject<z.ZodRawShape>;
-    llmClient: LLMClient;
-    userProvidedInstructions?: string;
-    logger: (message: LogLine) => void;
-    logInferenceToFile?: boolean;
-}): Promise<{
-    metadata: {
-        completed: boolean;
-        progress: string;
-    };
-    prompt_tokens: number;
-    completion_tokens: number;
-    inference_time_ms: number;
-}>;
-export declare function observe({ instruction, domElements, llmClient, userProvidedInstructions, logger, logInferenceToFile, }: {
-    instruction: string;
-    domElements: string;
-    llmClient: LLMClient;
-    userProvidedInstructions?: string;
-    logger: (message: LogLine) => void;
-    logInferenceToFile?: boolean;
-}): Promise<{
-    elements: {
-        elementId: string;
-        description: string;
-        method: string;
-        arguments: string[];
-    }[];
-    prompt_tokens: number;
-    completion_tokens: number;
-    inference_time_ms: number;
-}>;
-export declare function act({ instruction, domElements, llmClient, userProvidedInstructions, logger, logInferenceToFile, }: {
-    instruction: string;
-    domElements: string;
-    llmClient: LLMClient;
-    userProvidedInstructions?: string;
-    logger: (message: LogLine) => void;
-    logInferenceToFile?: boolean;
-}): Promise<{
-    element: {
-        elementId: string;
-        description: string;
-        method: string;
-        arguments: string[];
-    };
-    prompt_tokens: number;
-    completion_tokens: number;
-    inference_time_ms: number;
-    twoStep: boolean;
-}>;
-export {};

package/dist/lib/inferenceLogUtils.d.ts

@@ -1,12 +0,0 @@
-/**
- * Appends a new entry to the act_summary.json file, then writes the file back out.
- */
-export declare function appendSummary<T>(inferenceType: string, entry: T): void;
-/**
- * Writes `data` as JSON into a file in `directory`, using a prefix plus timestamp.
- * Returns both the file name and the timestamp used, so you can log them.
- */
-export declare function writeTimestampedTxtFile(directory: string, prefix: string, data: unknown): {
-    fileName: string;
-    timestamp: string;
-};

package/dist/lib/logger.d.ts

@@ -1,54 +0,0 @@
-import pino from "pino";
-import { LogLine } from "./v3/types/log";
-export interface LoggerOptions {
-    pretty?: boolean;
-    level?: pino.Level;
-    destination?: pino.DestinationStream;
-    usePino?: boolean;
-}
-/**
- * Creates a configured Pino logger instance
- */
-export declare function createLogger(options?: LoggerOptions): import("pino/pino").Logger<never, boolean>;
-/**
- * StagehandLogger class that wraps Pino for our specific needs
- */
-export declare class StagehandLogger {
-    /**
-     * We maintain a single shared Pino instance when `usePino` is enabled.
-     * This prevents spawning a new worker thread for every Stagehand instance
-     * (which happens when `pino-pretty` transport is used), eliminating the
-     * memory/RSS growth observed when many Stagehand objects are created and
-     * disposed within the same process (e.g. a request-per-instance API).
-     */
-    private static sharedPinoLogger;
-    private logger?;
-    private verbose;
-    private externalLogger?;
-    private usePino;
-    private isTest;
-    constructor(options?: LoggerOptions, externalLogger?: (logLine: LogLine) => void);
-    /**
-     * Set the verbosity level
-     */
-    setVerbosity(level: 0 | 1 | 2): void;
-    /**
-     * Log a message using our LogLine format
-     */
-    log(logLine: LogLine): void;
-    /**
-     * Helper to format auxiliary data for structured logging
-     */
-    private formatAuxiliaryData;
-    /**
-     * Convenience methods for different log levels
-     */
-    error(message: string, data?: Record<string, unknown>): void;
-    warn(message: string, data?: Record<string, unknown>): void;
-    info(message: string, data?: Record<string, unknown>): void;
-    debug(message: string, data?: Record<string, unknown>): void;
-    /**
-     * Convert a plain object to our auxiliary format
-     */
-    private convertToAuxiliary;
-}

package/dist/lib/prompt.d.ts

@@ -1,12 +0,0 @@
-import { ChatMessage } from "./v3/llm/LLMClient";
-export declare function buildUserInstructionsString(userProvidedInstructions?: string): string;
-export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, userProvidedInstructions?: string): ChatMessage;
-export declare function buildExtractUserPrompt(instruction: string, domElements: string, isUsingPrintExtractedDataTool?: boolean): ChatMessage;
-export declare function buildMetadataSystemPrompt(): ChatMessage;
-export declare function buildMetadataPrompt(instruction: string, extractionResponse: object): ChatMessage;
-export declare function buildObserveSystemPrompt(userProvidedInstructions?: string): ChatMessage;
-export declare function buildObserveUserMessage(instruction: string, domElements: string): ChatMessage;
-export declare function buildActSystemPrompt(userProvidedInstructions?: string): ChatMessage;
-export declare function buildActPrompt(action: string, supportedActions: string[], variables?: Record<string, string>): string;
-export declare function buildStepTwoPrompt(originalUserAction: string, previousAction: string, supportedActions: string[], variables?: Record<string, string>): string;
-export declare function buildOperatorSystemPrompt(goal: string): ChatMessage;

package/dist/lib/utils.d.ts

@@ -1,65 +0,0 @@
-import { Schema } from "@google/genai";
-import { z, ZodTypeAny } from "zod/v3";
-import { LogLine } from "./v3/types/log";
-import { ModelProvider } from "./v3/types/model";
-import { ZodPathSegments } from "./v3/types/stagehand";
-export declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
-/**
- * Detects if the code is running in the Bun runtime environment.
- * @returns {boolean} True if running in Bun, false otherwise.
- */
-export declare function isRunningInBun(): boolean;
-export declare function toGeminiSchema(zodSchema: z.ZodTypeAny): Schema;
-export declare function getZodType(schema: z.ZodTypeAny): string;
-/**
- * Recursively traverses a given Zod schema, scanning for any fields of type `z.string().url()`.
- * For each such field, it replaces the `z.string().url()` with `z.number()`.
- *
- * This function is used internally by higher-level utilities (e.g., transforming entire object schemas)
- * and handles nested objects, arrays, unions, intersections, optionals.
- *
- * @param schema - The Zod schema to transform.
- * @param currentPath - An array of string/number keys representing the current schema path (used internally for recursion).
- * @returns A two-element tuple:
- *   1. The updated Zod schema, with any `.url()` fields replaced by `z.number()`.
- *   2. An array of {@link ZodPathSegments} objects representing each replaced field, including the path segments.
- */
-export declare function transformSchema(schema: z.ZodTypeAny, currentPath: Array<string | number>): [z.ZodTypeAny, ZodPathSegments[]];
-/**
- * Once we get the final extracted object that has numeric IDs in place of URLs,
- * use `injectUrls` to walk the object and replace numeric IDs
- * with the real URL strings from idToUrlMapping. The `path` may include `*`
- * for array indices (indicating "all items in the array").
- */
-export declare function injectUrls(obj: unknown, path: Array<string | number>, idToUrlMapping: Record<string, string>): void;
-/**
- * Mapping from LLM provider names to their corresponding environment variable names for API keys.
- */
-export declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string>>;
-/**
- * Loads an API key for a provider, checking environment variables.
- * @param provider The name of the provider (e.g., 'openai', 'anthropic')
- * @param logger Optional logger for info/error messages
- * @returns The API key if found, undefined otherwise
- */
-export declare function loadApiKeyFromEnv(provider: string | undefined, logger: (logLine: LogLine) => void): string | undefined;
-export declare function trimTrailingTextNode(path: string | undefined): string | undefined;
-export interface JsonSchemaProperty {
-    type: string;
-    enum?: unknown[];
-    items?: JsonSchemaProperty;
-    properties?: Record<string, JsonSchemaProperty>;
-    required?: string[];
-    minimum?: number;
-    maximum?: number;
-    description?: string;
-}
-export interface JsonSchema extends JsonSchemaProperty {
-    type: string;
-}
-/**
- * Converts a JSON Schema object to a Zod schema
- * @param schema The JSON Schema object to convert
- * @returns A Zod schema equivalent to the input JSON Schema
- */
-export declare function jsonSchemaToZod(schema: JsonSchema): ZodTypeAny;

package/dist/lib/v3/agent/AgentClient.d.ts

@@ -1,18 +0,0 @@
-import { AgentAction, AgentResult, AgentType, AgentExecutionOptions } from "../types/agent";
-/**
- * Abstract base class for agent clients
- * This provides a common interface for all agent implementations
- */
-export declare abstract class AgentClient {
-    type: AgentType;
-    modelName: string;
-    clientOptions: Record<string, unknown>;
-    userProvidedInstructions?: string;
-    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string);
-    abstract execute(options: AgentExecutionOptions): Promise<AgentResult>;
-    abstract captureScreenshot(options?: Record<string, unknown>): Promise<unknown>;
-    abstract setViewport(width: number, height: number): void;
-    abstract setCurrentUrl(url: string): void;
-    abstract setScreenshotProvider(provider: () => Promise<string>): void;
-    abstract setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
-}

package/dist/lib/v3/agent/AgentProvider.d.ts

@@ -1,18 +0,0 @@
-import { AgentType } from "../types/agent";
-import { LogLine } from "../types/log";
-import { ToolSet } from "ai/dist";
-import { AgentClient } from "./AgentClient";
-/**
- * Provider for agent clients
- * This class is responsible for creating the appropriate agent client
- * based on the provider type
- */
-export declare class AgentProvider {
-    private logger;
-    /**
-     * Create a new agent provider
-     */
-    constructor(logger: (message: LogLine) => void);
-    getClient(modelName: string, clientOptions?: Record<string, unknown>, userProvidedInstructions?: string, tools?: ToolSet): AgentClient;
-    static getAgentProvider(modelName: string): AgentType;
-}