@mastra/stagehand 0.0.0-a2a-vnext-20260424123427

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# @mastra/stagehand
+
+## 0.0.0-a2a-vnext-20260424123427
+
+### Patch Changes
+
+- Updated dependencies [[`092271d`](https://github.com/mastra-ai/mastra/commit/092271d86af4cbe0d70cbf32709dd99b58acd3dd)]:
+  - @mastra/core@0.0.0-a2a-vnext-20260424123427
+
+## 0.2.1
+
+### Patch Changes
+
+- Standardize `headless` default to `true` across all browser providers. Each provider now resolves `headless` once in its constructor and passes it to the thread manager via the base class getter, removing duplicate fallback logic. ([#15696](https://github.com/mastra-ai/mastra/pull/15696))
+
+- Updated dependencies [[`733bf53`](https://github.com/mastra-ai/mastra/commit/733bf53d9352aedd3ef38c3d501edb275b65b43c), [`5405b3b`](https://github.com/mastra-ai/mastra/commit/5405b3b35325c5b8fb34fc7ac109bd2feb7bb6fe), [`45e29cb`](https://github.com/mastra-ai/mastra/commit/45e29cb5b5737f3083eb3852db02b944b9cf37ed), [`750b4d3`](https://github.com/mastra-ai/mastra/commit/750b4d3d8231f92e769b2c485921ac5a8ca639b9), [`c321127`](https://github.com/mastra-ai/mastra/commit/c3211275fc195de9ad1ead2746b354beb8eae6e8), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1), [`696694e`](https://github.com/mastra-ai/mastra/commit/696694e00f29241a25dd1a1b749afa06c3a626b4), [`b084a80`](https://github.com/mastra-ai/mastra/commit/b084a800db0f82d62e1fc3d6e3e3480da1ba5a53), [`82b7a96`](https://github.com/mastra-ai/mastra/commit/82b7a964169636c1d1e0c694fc892a213b0179d5), [`df97812`](https://github.com/mastra-ai/mastra/commit/df97812bd949dcafeb074b80ecab501724b49c3b), [`8bbe360`](https://github.com/mastra-ai/mastra/commit/8bbe36042af7fc4be0244dffd8913f6795179421), [`f6b8ba8`](https://github.com/mastra-ai/mastra/commit/f6b8ba8dbf533b7a8db90c72b6805ddc804a3a72), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1)]:
+  - @mastra/core@1.28.0
+
+## 0.2.1-alpha.0
+
+### Patch Changes
+
+- Standardize `headless` default to `true` across all browser providers. Each provider now resolves `headless` once in its constructor and passes it to the thread manager via the base class getter, removing duplicate fallback logic. ([#15696](https://github.com/mastra-ai/mastra/pull/15696))
+
+- Updated dependencies [[`750b4d3`](https://github.com/mastra-ai/mastra/commit/750b4d3d8231f92e769b2c485921ac5a8ca639b9)]:
+  - @mastra/core@1.28.0-alpha.1
+
+## 0.2.0
+
+### Minor Changes
+
+- Added automatic cleanup on browser close: patches `exit_type` to prevent restore dialogs, kills orphaned Chrome child processes, and uses CDP events for reliable disconnect detection in both shared and thread scope. ([#15194](https://github.com/mastra-ai/mastra/pull/15194))
+
+### Patch Changes
+
+- dependencies updates: ([#15209](https://github.com/mastra-ai/mastra/pull/15209))
+  - Updated dependency [`@browserbasehq/stagehand@^3.2.1` ↗︎](https://www.npmjs.com/package/@browserbasehq/stagehand/v/3.2.1) (from `^3.2.0`, in `dependencies`)
+- Updated dependencies [[`87df955`](https://github.com/mastra-ai/mastra/commit/87df955c028660c075873fd5d74af28233ce32eb), [`8fad147`](https://github.com/mastra-ai/mastra/commit/8fad14759804179c8e080ce4d9dec6ef1a808b31), [`582644c`](https://github.com/mastra-ai/mastra/commit/582644c4a87f83b4f245a84d72b9e8590585012e), [`cbdf3e1`](https://github.com/mastra-ai/mastra/commit/cbdf3e12b3d0c30a6e5347be658e2009648c130a), [`8fe46d3`](https://github.com/mastra-ai/mastra/commit/8fe46d354027f3f0f0846e64219772348de106dd), [`18c67db`](https://github.com/mastra-ai/mastra/commit/18c67dbb9c9ebc26f26f65f7d3ff836e5691ef46), [`4ba3bb1`](https://github.com/mastra-ai/mastra/commit/4ba3bb1e465ad2ddaba3bbf2bc47e0faec32985e), [`5d84914`](https://github.com/mastra-ai/mastra/commit/5d84914e0e520c642a40329b210b413fcd139898), [`8dcc77e`](https://github.com/mastra-ai/mastra/commit/8dcc77e78a5340f5848f74b9e9f1b3da3513c1f5), [`aa67fc5`](https://github.com/mastra-ai/mastra/commit/aa67fc59ee8a5eeff1f23eb05970b8d7a536c8ff), [`fd2f314`](https://github.com/mastra-ai/mastra/commit/fd2f31473d3449b6b97e837ef8641264377f41a7), [`fa8140b`](https://github.com/mastra-ai/mastra/commit/fa8140bcd4251d2e3ac85fdc5547dfc4f372b5be), [`190f452`](https://github.com/mastra-ai/mastra/commit/190f45258b0640e2adfc8219fa3258cdc5b8f071), [`e80fead`](https://github.com/mastra-ai/mastra/commit/e80fead1412cc0d1b2f7d6a1ce5017d9e0098ff7), [`0287b64`](https://github.com/mastra-ai/mastra/commit/0287b644a5c3272755cf3112e71338106664103b), [`7e7bf60`](https://github.com/mastra-ai/mastra/commit/7e7bf606886bf374a6f9d4ca9b09dd83d0533372), [`184907d`](https://github.com/mastra-ai/mastra/commit/184907d775d8609c03c26e78ccaf37315f3aa287), [`075e91a`](https://github.com/mastra-ai/mastra/commit/075e91a4549baf46ad7a42a6a8ac8dfa78cc09e6), [`0c4cd13`](https://github.com/mastra-ai/mastra/commit/0c4cd131931c04ac5405373c932a242dbe88edd6), [`b16a753`](https://github.com/mastra-ai/mastra/commit/b16a753d5748440248d7df82e29bb987a9c8386c)]:
+  - @mastra/core@1.25.0
+
+## 0.2.0-alpha.0
+
+### Minor Changes
+
+- Added automatic cleanup on browser close: patches `exit_type` to prevent restore dialogs, kills orphaned Chrome child processes, and uses CDP events for reliable disconnect detection in both shared and thread scope. ([#15194](https://github.com/mastra-ai/mastra/pull/15194))
+
+### Patch Changes
+
+- dependencies updates: ([#15209](https://github.com/mastra-ai/mastra/pull/15209))
+  - Updated dependency [`@browserbasehq/stagehand@^3.2.1` ↗︎](https://www.npmjs.com/package/@browserbasehq/stagehand/v/3.2.1) (from `^3.2.0`, in `dependencies`)
+- Updated dependencies [[`cbdf3e1`](https://github.com/mastra-ai/mastra/commit/cbdf3e12b3d0c30a6e5347be658e2009648c130a), [`8fe46d3`](https://github.com/mastra-ai/mastra/commit/8fe46d354027f3f0f0846e64219772348de106dd), [`18c67db`](https://github.com/mastra-ai/mastra/commit/18c67dbb9c9ebc26f26f65f7d3ff836e5691ef46), [`8dcc77e`](https://github.com/mastra-ai/mastra/commit/8dcc77e78a5340f5848f74b9e9f1b3da3513c1f5), [`aa67fc5`](https://github.com/mastra-ai/mastra/commit/aa67fc59ee8a5eeff1f23eb05970b8d7a536c8ff), [`fa8140b`](https://github.com/mastra-ai/mastra/commit/fa8140bcd4251d2e3ac85fdc5547dfc4f372b5be), [`190f452`](https://github.com/mastra-ai/mastra/commit/190f45258b0640e2adfc8219fa3258cdc5b8f071), [`7e7bf60`](https://github.com/mastra-ai/mastra/commit/7e7bf606886bf374a6f9d4ca9b09dd83d0533372), [`184907d`](https://github.com/mastra-ai/mastra/commit/184907d775d8609c03c26e78ccaf37315f3aa287), [`0c4cd13`](https://github.com/mastra-ai/mastra/commit/0c4cd131931c04ac5405373c932a242dbe88edd6), [`b16a753`](https://github.com/mastra-ai/mastra/commit/b16a753d5748440248d7df82e29bb987a9c8386c)]:
+  - @mastra/core@1.25.0-alpha.3
+
+## 0.1.0
+
+### Minor Changes
+
+- Add AI-powered browser automation with Stagehand SDK integration ([#14938](https://github.com/mastra-ai/mastra/pull/14938))
+
+  **New Features:**
+  - AI-powered browser automation using Stagehand's act/extract/observe primitives
+  - Native Browserbase integration for cloud browser sessions
+  - Real-time screencast streaming via WebSocket
+  - Mouse and keyboard input injection
+  - Thread-scoped browser isolation (`scope: 'thread'`)
+  - State persistence and restoration across sessions
+
+  **Configuration:**
+
+  ```typescript
+  import { StagehandBrowser } from '@mastra/stagehand';
+
+  // Local browser
+  const browser = new StagehandBrowser({
+    headless: true,
+    scope: 'thread',
+  });
+
+  // Browserbase cloud
+  const browser = new StagehandBrowser({
+    env: 'BROWSERBASE',
+    apiKey: process.env.BROWSERBASE_API_KEY,
+    projectId: process.env.BROWSERBASE_PROJECT_ID,
+  });
+
+  const agent = mastra.getAgent('my-agent', { browser });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`cb15509`](https://github.com/mastra-ai/mastra/commit/cb15509b58f6a83e11b765c945082afc027db972), [`81e4259`](https://github.com/mastra-ai/mastra/commit/81e425939b4ceeb4f586e9b6d89c3b1c1f2d2fe7), [`951b8a1`](https://github.com/mastra-ai/mastra/commit/951b8a1b5ef7e1474c59dc4f2b9fc1a8b1e508b6), [`80c5668`](https://github.com/mastra-ai/mastra/commit/80c5668e365470d3a96d3e953868fd7a643ff67c), [`3d478c1`](https://github.com/mastra-ai/mastra/commit/3d478c1e13f17b80f330ac49d7aa42ef929b93ff), [`2b4ea10`](https://github.com/mastra-ai/mastra/commit/2b4ea10b053e4ea1ab232d536933a4a3c4cba999), [`a0544f0`](https://github.com/mastra-ai/mastra/commit/a0544f0a1e6bd52ac12676228967c1938e43648d), [`6039f17`](https://github.com/mastra-ai/mastra/commit/6039f176f9c457304825ff1df8c83b8e457376c0), [`06b928d`](https://github.com/mastra-ai/mastra/commit/06b928dfc2f5630d023467476cc5919dfa858d0a), [`6a8d984`](https://github.com/mastra-ai/mastra/commit/6a8d9841f2933456ee1598099f488d742b600054), [`c8c86aa`](https://github.com/mastra-ai/mastra/commit/c8c86aa1458017fbd1c0776fdc0c520d129df8a6)]:
+  - @mastra/core@1.22.0
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Add AI-powered browser automation with Stagehand SDK integration ([#14938](https://github.com/mastra-ai/mastra/pull/14938))
+
+  **New Features:**
+  - AI-powered browser automation using Stagehand's act/extract/observe primitives
+  - Native Browserbase integration for cloud browser sessions
+  - Real-time screencast streaming via WebSocket
+  - Mouse and keyboard input injection
+  - Thread-scoped browser isolation (`scope: 'thread'`)
+  - State persistence and restoration across sessions
+
+  **Configuration:**
+
+  ```typescript
+  import { StagehandBrowser } from '@mastra/stagehand';
+
+  // Local browser
+  const browser = new StagehandBrowser({
+    headless: true,
+    scope: 'thread',
+  });
+
+  // Browserbase cloud
+  const browser = new StagehandBrowser({
+    env: 'BROWSERBASE',
+    apiKey: process.env.BROWSERBASE_API_KEY,
+    projectId: process.env.BROWSERBASE_PROJECT_ID,
+  });
+
+  const agent = mastra.getAgent('my-agent', { browser });
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`cb15509`](https://github.com/mastra-ai/mastra/commit/cb15509b58f6a83e11b765c945082afc027db972), [`80c5668`](https://github.com/mastra-ai/mastra/commit/80c5668e365470d3a96d3e953868fd7a643ff67c), [`3d478c1`](https://github.com/mastra-ai/mastra/commit/3d478c1e13f17b80f330ac49d7aa42ef929b93ff), [`6039f17`](https://github.com/mastra-ai/mastra/commit/6039f176f9c457304825ff1df8c83b8e457376c0), [`06b928d`](https://github.com/mastra-ai/mastra/commit/06b928dfc2f5630d023467476cc5919dfa858d0a), [`6a8d984`](https://github.com/mastra-ai/mastra/commit/6a8d9841f2933456ee1598099f488d742b600054)]:
+  - @mastra/core@1.22.0-alpha.2

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,110 @@
+# @mastra/stagehand
+
+AI-powered browser automation for Mastra agents using [Stagehand](https://github.com/browserbase/stagehand).
+
+## Installation
+
+```bash
+npm install @mastra/stagehand
+```
+
+## Usage
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+import { StagehandBrowser } from '@mastra/stagehand';
+
+// Create a Stagehand browser
+const browser = new StagehandBrowser({
+  model: 'openai/gpt-5.4',
+  headless: true,
+});
+
+// Create an agent with the browser
+const agent = new Agent({
+  name: 'web-agent',
+  instructions: 'You are a helpful web assistant.',
+  model: 'openai/gpt-5.4',
+  browser,
+});
+
+// Use the agent to browse the web with natural language
+const result = await agent.generate('Go to google.com and search for "Mastra AI"');
+```
+
+## Configuration
+
+```typescript
+const browser = new StagehandBrowser({
+  // Environment: 'LOCAL' or 'BROWSERBASE'
+  env: 'LOCAL',
+
+  // Model for AI operations (default: 'openai/gpt-5.4')
+  model: 'openai/gpt-5.4',
+  // Or with custom config:
+  model: {
+    modelName: 'gpt-5.4',
+    apiKey: process.env.OPENAI_API_KEY,
+  },
+
+  // Run headless (default: true)
+  headless: true,
+
+  // Viewport dimensions
+  viewport: { width: 1280, height: 720 },
+
+  // CDP URL for connecting to existing browser
+  cdpUrl: 'ws://localhost:9222',
+
+  // Browserbase config (when env: 'BROWSERBASE')
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+
+  // Enable self-healing selectors (default: true)
+  selfHeal: true,
+
+  // DOM settle timeout in ms (default: 5000)
+  domSettleTimeout: 5000,
+
+  // Logging verbosity (0: silent, 1: errors, 2: verbose)
+  verbose: 1,
+
+  // Custom system prompt for AI operations
+  systemPrompt: 'Focus on finding interactive elements',
+});
+```
+
+## Tools
+
+StagehandBrowser exposes 6 AI-powered tools:
+
+### Core AI Tools
+
+- **stagehand_act** - Perform actions using natural language instructions
+- **stagehand_extract** - Extract structured data from pages
+- **stagehand_observe** - Discover actionable elements on the page
+
+### Navigation & State
+
+- **stagehand_navigate** - Navigate to a URL
+- **stagehand_tabs** - List, switch, open, or close browser tabs
+- **stagehand_close** - Close the browser
+
+## Comparison with AgentBrowser
+
+| Feature     | AgentBrowser             | StagehandBrowser             |
+| ----------- | ------------------------ | ---------------------------- |
+| Approach    | Deterministic refs (@e1) | Natural language             |
+| Token cost  | Low                      | Higher (LLM calls)           |
+| Speed       | Fast                     | Slower                       |
+| Reliability | High (exact refs)        | Variable (AI interpretation) |
+| Best for    | Structured workflows     | Unknown/dynamic pages        |
+
+## Documentation
+
+- [Stagehand guide](https://mastra.ai/docs/browser/stagehand) - Usage guide
+- [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) - API reference
+
+## License
+
+Apache-2.0