@mastra/stagehand 0.1.0-alpha.0 → 0.2.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/README.md +33 -16
  3. package/dist/index.cjs +139 -317
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +72 -119
  6. package/dist/index.d.ts +72 -119
  7. package/dist/index.js +139 -318
  8. package/dist/index.js.map +1 -1
  9. package/package.json +6 -5
package/CHANGELOG.md CHANGED
@@ -1,5 +1,58 @@
1
1
  # @mastra/stagehand
2
2
 
3
+ ## 0.2.0-alpha.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 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))
8
+
9
+ ### Patch Changes
10
+
11
+ - dependencies updates: ([#15209](https://github.com/mastra-ai/mastra/pull/15209))
12
+ - Updated dependency [`@browserbasehq/stagehand@^3.2.1` ↗︎](https://www.npmjs.com/package/@browserbasehq/stagehand/v/3.2.1) (from `^3.2.0`, in `dependencies`)
13
+ - 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)]:
14
+ - @mastra/core@1.25.0-alpha.3
15
+
16
+ ## 0.1.0
17
+
18
+ ### Minor Changes
19
+
20
+ - Add AI-powered browser automation with Stagehand SDK integration ([#14938](https://github.com/mastra-ai/mastra/pull/14938))
21
+
22
+ **New Features:**
23
+ - AI-powered browser automation using Stagehand's act/extract/observe primitives
24
+ - Native Browserbase integration for cloud browser sessions
25
+ - Real-time screencast streaming via WebSocket
26
+ - Mouse and keyboard input injection
27
+ - Thread-scoped browser isolation (`scope: 'thread'`)
28
+ - State persistence and restoration across sessions
29
+
30
+ **Configuration:**
31
+
32
+ ```typescript
33
+ import { StagehandBrowser } from '@mastra/stagehand';
34
+
35
+ // Local browser
36
+ const browser = new StagehandBrowser({
37
+ headless: true,
38
+ scope: 'thread',
39
+ });
40
+
41
+ // Browserbase cloud
42
+ const browser = new StagehandBrowser({
43
+ env: 'BROWSERBASE',
44
+ apiKey: process.env.BROWSERBASE_API_KEY,
45
+ projectId: process.env.BROWSERBASE_PROJECT_ID,
46
+ });
47
+
48
+ const agent = mastra.getAgent('my-agent', { browser });
49
+ ```
50
+
51
+ ### Patch Changes
52
+
53
+ - 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)]:
54
+ - @mastra/core@1.22.0
55
+
3
56
  ## 0.1.0-alpha.0
4
57
 
5
58
  ### Minor Changes
package/README.md CHANGED
@@ -11,12 +11,12 @@ npm install @mastra/stagehand
11
11
  ## Usage
12
12
 
13
13
  ```typescript
14
- import { Agent } from '@mastra/core';
14
+ import { Agent } from '@mastra/core/agent';
15
15
  import { StagehandBrowser } from '@mastra/stagehand';
16
16
 
17
17
  // Create a Stagehand browser
18
18
  const browser = new StagehandBrowser({
19
- model: 'openai/gpt-4o',
19
+ model: 'openai/gpt-5.4',
20
20
  headless: true,
21
21
  });
22
22
 
@@ -24,7 +24,7 @@ const browser = new StagehandBrowser({
24
24
  const agent = new Agent({
25
25
  name: 'web-agent',
26
26
  instructions: 'You are a helpful web assistant.',
27
- model: { provider: 'openai', modelId: 'gpt-4o' },
27
+ model: 'openai/gpt-5.4',
28
28
  browser,
29
29
  });
30
30
 
@@ -39,17 +39,20 @@ const browser = new StagehandBrowser({
39
39
  // Environment: 'LOCAL' or 'BROWSERBASE'
40
40
  env: 'LOCAL',
41
41
 
42
- // Model for AI operations (default: 'openai/gpt-4o')
43
- model: 'openai/gpt-4o',
42
+ // Model for AI operations (default: 'openai/gpt-5.4')
43
+ model: 'openai/gpt-5.4',
44
44
  // Or with custom config:
45
45
  model: {
46
- modelName: 'openai/gpt-4o',
46
+ modelName: 'gpt-5.4',
47
47
  apiKey: process.env.OPENAI_API_KEY,
48
48
  },
49
49
 
50
50
  // Run headless (default: true)
51
51
  headless: true,
52
52
 
53
+ // Viewport dimensions
54
+ viewport: { width: 1280, height: 720 },
55
+
53
56
  // CDP URL for connecting to existing browser
54
57
  cdpUrl: 'ws://localhost:9222',
55
58
 
@@ -57,8 +60,17 @@ const browser = new StagehandBrowser({
57
60
  apiKey: process.env.BROWSERBASE_API_KEY,
58
61
  projectId: process.env.BROWSERBASE_PROJECT_ID,
59
62
 
63
+ // Enable self-healing selectors (default: true)
64
+ selfHeal: true,
65
+
66
+ // DOM settle timeout in ms (default: 5000)
67
+ domSettleTimeout: 5000,
68
+
60
69
  // Logging verbosity (0: silent, 1: errors, 2: verbose)
61
70
  verbose: 1,
71
+
72
+ // Custom system prompt for AI operations
73
+ systemPrompt: 'Focus on finding interactive elements',
62
74
  });
63
75
  ```
64
76
 
@@ -68,25 +80,30 @@ StagehandBrowser exposes 6 AI-powered tools:
68
80
 
69
81
  ### Core AI Tools
70
82
 
71
- - **stagehand_act** - Perform actions using natural language
83
+ - **stagehand_act** - Perform actions using natural language instructions
72
84
  - **stagehand_extract** - Extract structured data from pages
73
- - **stagehand_observe** - Discover actionable elements
85
+ - **stagehand_observe** - Discover actionable elements on the page
74
86
 
75
87
  ### Navigation & State
76
88
 
77
89
  - **stagehand_navigate** - Navigate to a URL
78
- - **stagehand_screenshot** - Take screenshots
90
+ - **stagehand_tabs** - List, switch, open, or close browser tabs
79
91
  - **stagehand_close** - Close the browser
80
92
 
81
93
  ## Comparison with AgentBrowser
82
94
 
83
- | Feature | AgentBrowser | StagehandBrowser |
84
- | ----------- | ----------------------------- | ---------------------------- |
85
- | Approach | Deterministic refs ([ref=e1]) | Natural language |
86
- | Token cost | Low | Higher (LLM calls) |
87
- | Speed | Fast | Slower |
88
- | Reliability | High (exact refs) | Variable (AI interpretation) |
89
- | Best for | Structured workflows | Unknown/dynamic pages |
95
+ | Feature | AgentBrowser | StagehandBrowser |
96
+ | ----------- | ------------------------ | ---------------------------- |
97
+ | Approach | Deterministic refs (@e1) | Natural language |
98
+ | Token cost | Low | Higher (LLM calls) |
99
+ | Speed | Fast | Slower |
100
+ | Reliability | High (exact refs) | Variable (AI interpretation) |
101
+ | Best for | Structured workflows | Unknown/dynamic pages |
102
+
103
+ ## Documentation
104
+
105
+ - [Stagehand guide](https://mastra.ai/docs/browser/stagehand) - Usage guide
106
+ - [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) - API reference
90
107
 
91
108
  ## License
92
109