@mastra/core 1.23.0-alpha.8 → 1.23.0-alpha.9

package/dist/docs/references/docs-browser-overview.md

@@ -0,0 +1,136 @@
+# Browser overview
+
+Browser support enables agents to navigate websites, interact with page elements, fill forms, and extract data. Mastra provides browser capabilities through SDK providers that wrap popular browser automation libraries.
+
+Mastra supports two browser SDK providers:
+
+- [**AgentBrowser**](https://mastra.ai/docs/browser/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
+- [**Stagehand**](https://mastra.ai/docs/browser/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
+
+## When to use browser
+
+Use browser when your agent needs to:
+
+- Navigate websites and interact with page elements
+- Fill out forms and submit data
+- Extract structured data from web pages
+- Automate multi-step web workflows
+- Take actions that require a real browser (JavaScript rendering, authentication flows)
+
+## How it works
+
+When you assign a browser to an agent, Mastra includes the provider's tools in the agent's toolset. The agent uses these tools to control the browser: navigating to URLs, selecting elements, typing text, and reading page content.
+
+Each provider offers a different set of tools optimized for its approach.
+
+## Quickstart
+
+Install your provider of choice, for this example you'll use the AgentBrowser provider.
+
+**npm**:
+
+```bash
+npm install @mastra/agent-browser
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/agent-browser
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/agent-browser
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/agent-browser
+```
+
+Create a new browser instance:
+
+```typescript
+import { AgentBrowser } from '@mastra/agent-browser'
+
+export const browser = new AgentBrowser({
+  headless: false,
+})
+```
+
+Assign the browser to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { browser } from '../browsers'
+
+export const webAgent = new Agent({
+  id: 'web-agent',
+  model: 'openai/gpt-5.4',
+  browser,
+  instructions:
+    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
+})
+```
+
+The agent automatically receives all browser tools from the provider.
+
+## Cloud providers
+
+Both SDK providers support connecting to cloud browser services instead of launching a local browser.
+
+### Browserbase (Stagehand native)
+
+Stagehand has native Browserbase integration:
+
+```typescript
+import { StagehandBrowser } from '@mastra/stagehand'
+
+const browser = new StagehandBrowser({
+  env: 'BROWSERBASE',
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+})
+```
+
+### CDP URL (any provider)
+
+Connect to any browser exposing a Chrome DevTools Protocol (CDP) endpoint:
+
+```typescript
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  cdpUrl: process.env.BROWSER_CDP_URL,
+  headless: true,
+})
+```
+
+This works with any [CDP-compatible](https://chromedevtools.github.io/devtools-protocol/) browser service.
+
+## Screencast
+
+Browser providers stream a live video feed of the browser to the Mastra Studio UI. This lets you watch the agent interact with pages in real-time.
+
+Screencast is enabled by default and can be configured:
+
+```typescript
+const browser = new AgentBrowser({
+  screencast: {
+    enabled: true,
+    format: 'jpeg',
+    quality: 80,
+    maxWidth: 1280,
+    maxHeight: 720,
+  },
+})
+```
+
+## Next steps
+
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/dist/docs/references/reference-browser-mastra-browser.md

@@ -0,0 +1,284 @@
+# MastraBrowser class
+
+The `MastraBrowser` class is the abstract base class for browser automation providers. It defines the common interface for launching browsers, managing thread isolation, streaming screencasts, and handling input events.
+
+You don't instantiate `MastraBrowser` directly. Instead, use a provider implementation:
+
+- [`AgentBrowser`](https://mastra.ai/reference/browser/agent-browser): Deterministic browser automation using refs
+- [`StagehandBrowser`](https://mastra.ai/reference/browser/stagehand-browser): AI-powered browser automation using natural language
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  headless: true,
+  viewport: { width: 1280, height: 720 },
+  scope: 'thread',
+})
+
+export const browserAgent = new Agent({
+  name: 'browser-agent',
+  instructions: 'You can browse the web to find information.',
+  model: 'openai/gpt-5.4',
+  browser,
+})
+```
+
+## Constructor parameters
+
+**headless** (`boolean`): Whether to run the browser in headless mode (no visible UI). (Default: `true`)
+
+**viewport** (`{ width: number; height: number }`): Browser viewport dimensions. Controls the size of the browser window. (Default: `{ width: 1280, height: 720 }`)
+
+**timeout** (`number`): Default timeout in milliseconds for browser operations. (Default: `10000`)
+
+**cdpUrl** (`string | (() => string | Promise<string>)`): CDP WebSocket URL, HTTP endpoint, or sync/async provider function. When provided, connects to an existing browser instead of launching a new one. HTTP endpoints are resolved to WebSocket internally. Can't be used with scope: 'thread' (automatically uses shared scope).
+
+**scope** (`'shared' | 'thread'`): Browser instance scope across threads. 'shared' means all threads share a single browser instance. 'thread' means each thread gets its own browser instance (full isolation). (Default: `'thread' (or 'shared' when cdpUrl is provided)`)
+
+**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked after the browser reaches 'ready' status.
+
+**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback invoked before the browser is closed.
+
+**screencast** (`ScreencastOptions`): Configuration for streaming browser frames.
+
+**screencast.format** (`'jpeg' | 'png'`): Image format for screencast frames.
+
+**screencast.quality** (`number`): Image quality (1-100). Only applies to JPEG format.
+
+**screencast.maxWidth** (`number`): Maximum width for screencast frames.
+
+**screencast.maxHeight** (`number`): Maximum height for screencast frames.
+
+**screencast.everyNthFrame** (`number`): Capture every Nth frame to reduce bandwidth.
+
+## Properties
+
+The following properties (`id`, `name`, `provider`) are abstract and must be defined by concrete provider implementations:
+
+**id** (`string`): Unique identifier for this browser instance. Abstract - defined by provider.
+
+**name** (`string`): Human-readable name of the browser provider (e.g., 'AgentBrowser', 'StagehandBrowser'). Abstract - defined by provider.
+
+**provider** (`string`): Provider identifier (e.g., 'vercel-labs/agent-browser', 'browserbase/stagehand'). Abstract - defined by provider.
+
+**headless** (`boolean`): Whether the browser is running in headless mode.
+
+**status** (`BrowserStatus`): Current browser status: 'pending', 'launching', 'ready', 'error', 'closing', or 'closed'.
+
+## Methods
+
+### Lifecycle
+
+#### `ensureReady()`
+
+Ensures the browser is launched and ready for use. Automatically called before tool execution. Implemented in the base class.
+
+```typescript
+await browser.ensureReady()
+```
+
+#### `close()`
+
+Closes the browser and cleans up all resources. Implemented in the base class with race-condition-safe handling.
+
+```typescript
+await browser.close()
+```
+
+#### `isBrowserRunning()`
+
+Checks if the browser is currently running.
+
+```typescript
+const isRunning = browser.isBrowserRunning()
+```
+
+**Returns:** `boolean`
+
+### Thread management
+
+#### `setCurrentThread(threadId)`
+
+Sets the current thread ID for browser operations. Used internally by the agent runtime.
+
+```typescript
+browser.setCurrentThread('thread-123')
+```
+
+#### `getCurrentThread()`
+
+Gets the current thread ID.
+
+```typescript
+const threadId = browser.getCurrentThread()
+```
+
+**Returns:** `string`
+
+#### `hasThreadSession(threadId)`
+
+Checks if a thread has an active browser session.
+
+```typescript
+const hasSession = browser.hasThreadSession('thread-123')
+```
+
+**Returns:** `boolean`
+
+#### `closeThreadSession(threadId)`
+
+Closes a specific thread's browser session. For 'thread' scope, this closes that thread's browser instance. For 'shared' scope, this clears the thread's state.
+
+```typescript
+await browser.closeThreadSession('thread-123')
+```
+
+### Tools
+
+#### `getTools()`
+
+Returns the browser tools for use with agents. Each provider returns different tools based on its paradigm.
+
+```typescript
+const tools = browser.getTools()
+```
+
+**Returns:** `Record<string, Tool>`
+
+### Screencast
+
+#### `startScreencast(options?, threadId?)`
+
+Starts streaming browser frames. Returns a `ScreencastStream` that emits frame events.
+
+```typescript
+const stream = await browser.startScreencast({ format: 'jpeg', quality: 80 }, 'thread-123')
+
+stream.on('frame', frame => {
+  console.log('Frame received:', frame.data.length, 'bytes')
+})
+
+stream.on('stop', reason => {
+  console.log('Screencast stopped:', reason)
+})
+```
+
+**Returns:** `Promise<ScreencastStream>`
+
+### Input injection
+
+#### `injectMouseEvent(params, threadId?)`
+
+Injects a mouse event into the browser. Used by Studio for live interaction.
+
+```typescript
+await browser.injectMouseEvent({
+  type: 'mousePressed',
+  x: 100,
+  y: 200,
+  button: 'left',
+  clickCount: 1,
+})
+```
+
+#### `injectKeyboardEvent(params, threadId?)`
+
+Injects a keyboard event into the browser. Used by Studio for live interaction.
+
+```typescript
+await browser.injectKeyboardEvent({
+  type: 'keyDown',
+  key: 'Enter',
+  code: 'Enter',
+})
+```
+
+### State
+
+#### `getState(threadId?)`
+
+Gets the current browser state including URL and tabs.
+
+```typescript
+const state = await browser.getState('thread-123')
+console.log('Current URL:', state.currentUrl)
+console.log('Tabs:', state.tabs)
+```
+
+**Returns:** `Promise<BrowserState>`
+
+```typescript
+interface BrowserState {
+  currentUrl: string | null
+  tabs: BrowserTabState[]
+  activeTabIndex: number
+}
+
+interface BrowserTabState {
+  id: string
+  url: string
+  title: string
+}
+```
+
+#### `getCurrentUrl(threadId?)`
+
+Gets the current page URL.
+
+```typescript
+const url = await browser.getCurrentUrl()
+```
+
+**Returns:** `Promise<string | null>`
+
+## Browser scope
+
+The `scope` option controls how browser instances are shared across conversation threads:
+
+| Scope      | Description                                 | Use case                                 |
+| ---------- | ------------------------------------------- | ---------------------------------------- |
+| `'shared'` | All threads share a single browser instance | Cost-efficient for non-conflicting tasks |
+| `'thread'` | Each thread gets its own browser instance   | Full isolation for concurrent users      |
+
+```typescript
+// Shared browser for all threads
+const sharedBrowser = new AgentBrowser({
+  scope: 'shared',
+})
+
+// Isolated browser per thread
+const isolatedBrowser = new AgentBrowser({
+  scope: 'thread',
+})
+```
+
+When using `cdpUrl` to connect to an external browser, the scope automatically falls back to `'shared'` since you can't spawn new browser instances.
+
+## Cloud browser providers
+
+Connect to cloud browser services using the `cdpUrl` option:
+
+```typescript
+// Static CDP URL
+const browser = new AgentBrowser({
+  cdpUrl: 'wss://browser.example.com/ws',
+})
+
+// Dynamic CDP URL (e.g., session-based)
+const browser = new AgentBrowser({
+  cdpUrl: async () => {
+    const session = await createBrowserSession()
+    return session.wsUrl
+  },
+})
+```
+
+## Related
+
+- [AgentBrowser](https://mastra.ai/reference/browser/agent-browser): Deterministic browser automation
+- [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser): AI-powered browser automation
+- [Browser overview](https://mastra.ai/docs/browser/overview): Conceptual guide to browser automation

package/dist/docs/references/reference.md

@@ -39,6 +39,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Okta](https://mastra.ai/reference/auth/okta)
 - [Supabase](https://mastra.ai/reference/auth/supabase)
 - [WorkOS](https://mastra.ai/reference/auth/workos)
+- [AgentBrowser](https://mastra.ai/reference/browser/agent-browser)
+- [MastraBrowser Class](https://mastra.ai/reference/browser/mastra-browser)
+- [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser)
 - [create-mastra](https://mastra.ai/reference/cli/create-mastra)
 - [mastra](https://mastra.ai/reference/cli/mastra)
 - [Agents API](https://mastra.ai/reference/client-js/agents)

package/dist/evals/index.cjs

@@ -1,22 +1,22 @@
 'use strict';
 
-var chunkB35QXEMG_cjs = require('../chunk-B35QXEMG.cjs');
-var chunkON4TYQED_cjs = require('../chunk-ON4TYQED.cjs');
+var chunkJ5KOS6DG_cjs = require('../chunk-J5KOS6DG.cjs');
+var chunkS4FM2VDW_cjs = require('../chunk-S4FM2VDW.cjs');
 var chunk3UBTJXPW_cjs = require('../chunk-3UBTJXPW.cjs');
 
 
 
 Object.defineProperty(exports, "runEvals", {
   enumerable: true,
-  get: function () { return chunkB35QXEMG_cjs.runEvals; }
+  get: function () { return chunkJ5KOS6DG_cjs.runEvals; }
 });
 Object.defineProperty(exports, "MastraScorer", {
   enumerable: true,
-  get: function () { return chunkON4TYQED_cjs.MastraScorer; }
+  get: function () { return chunkS4FM2VDW_cjs.MastraScorer; }
 });
 Object.defineProperty(exports, "createScorer", {
   enumerable: true,
-  get: function () { return chunkON4TYQED_cjs.createScorer; }
+  get: function () { return chunkS4FM2VDW_cjs.createScorer; }
 });
 Object.defineProperty(exports, "extractTrajectory", {
   enumerable: true,

package/dist/evals/index.js

@@ -1,5 +1,5 @@
-export { runEvals } from '../chunk-I7VQPDZ7.js';
-export { MastraScorer, createScorer } from '../chunk-AGEOFSDZ.js';
+export { runEvals } from '../chunk-NDJMYGSX.js';
+export { MastraScorer, createScorer } from '../chunk-CFYLBHVD.js';
 export { extractTrajectory, extractTrajectoryFromTrace, extractWorkflowTrajectory, listScoresResponseSchema, saveScorePayloadSchema, scoreResultSchema, scoreRowDataSchema, scoringEntityTypeSchema, scoringExtractStepResultSchema, scoringHookInputSchema, scoringInputSchema, scoringInputWithExtractStepResultAndAnalyzeStepResultSchema, scoringInputWithExtractStepResultAndScoreAndReasonSchema, scoringInputWithExtractStepResultSchema, scoringPromptsSchema, scoringSourceSchema, scoringValueSchema } from '../chunk-5OXVECLF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/evals/scoreTraces/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkI3Y3GPMU_cjs = require('../../chunk-I3Y3GPMU.cjs');
+var chunkB2PK5R4Q_cjs = require('../../chunk-B2PK5R4Q.cjs');
 var chunk3UBTJXPW_cjs = require('../../chunk-3UBTJXPW.cjs');
 var chunkPHSDY5MP_cjs = require('../../chunk-PHSDY5MP.cjs');
 var chunk4U7ZLI36_cjs = require('../../chunk-4U7ZLI36.cjs');
@@ -234,7 +234,7 @@ function transformTraceToScorerInputAndOutput(trace) {
 }
 
 // src/evals/scoreTraces/scoreTracesWorkflow.ts
-var getTraceStep = chunkI3Y3GPMU_cjs.createStep({
+var getTraceStep = chunkB2PK5R4Q_cjs.createStep({
   id: "__process-trace-scoring",
   inputSchema: v4.z.object({
     targets: v4.z.array(
@@ -429,7 +429,7 @@ async function attachScoreToSpan({
   } catch {
   }
 }
-var scoreTracesWorkflow = chunkI3Y3GPMU_cjs.createWorkflow({
+var scoreTracesWorkflow = chunkB2PK5R4Q_cjs.createWorkflow({
   id: "__batch-scoring-traces",
   inputSchema: v4.z.object({
     targets: v4.z.array(

package/dist/evals/scoreTraces/index.js

@@ -1,4 +1,4 @@
-import { createStep, createWorkflow } from '../../chunk-VVGJHIQH.js';
+import { createStep, createWorkflow } from '../../chunk-S2B7VZP2.js';
 import { saveScorePayloadSchema } from '../../chunk-5OXVECLF.js';
 import { getEntityTypeForSpan } from '../../chunk-JVXQTSRU.js';
 import { MastraError } from '../../chunk-FJEVLHJT.js';

package/dist/harness/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkFDZIDJEN_cjs = require('../chunk-FDZIDJEN.cjs');
-var chunkON4TYQED_cjs = require('../chunk-ON4TYQED.cjs');
+var chunkC7Y7CU7Z_cjs = require('../chunk-C7Y7CU7Z.cjs');
+var chunkS4FM2VDW_cjs = require('../chunk-S4FM2VDW.cjs');
 var chunkRNJ2FXGD_cjs = require('../chunk-RNJ2FXGD.cjs');
 var chunkNAYAEPMW_cjs = require('../chunk-NAYAEPMW.cjs');
 var chunkLDLHW3QN_cjs = require('../chunk-LDLHW3QN.cjs');
@@ -313,7 +313,7 @@ Use this tool when:
         };
       }
       const workspace = context?.workspace;
-      const subagent = new chunkON4TYQED_cjs.Agent({
+      const subagent = new chunkS4FM2VDW_cjs.Agent({
         id: `subagent-${definition.id}`,
         name: `${definition.name} Subagent`,
         instructions: definition.instructions,
@@ -576,7 +576,7 @@ var Harness = class {
    */
   async init() {
     if (this.config.storage) {
-      this.#internalMastra = new chunkFDZIDJEN_cjs.Mastra({ logger: false, storage: this.config.storage });
+      this.#internalMastra = new chunkC7Y7CU7Z_cjs.Mastra({ logger: false, storage: this.config.storage });
       await this.#internalMastra.getStorage().init();
     }
     if (this.config.workspace && !this.workspaceInitialized && !this.workspaceFn) {
@@ -832,7 +832,7 @@ var Harness = class {
       }
     }
     try {
-      const { PROVIDER_REGISTRY } = await import('../provider-registry-3AYLGCSG.cjs');
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-NOT45GOM.cjs');
       const registry = PROVIDER_REGISTRY;
       const providerConfig = registry[provider];
       const envVars = providerConfig?.apiKeyEnvVar;
@@ -852,7 +852,7 @@ var Harness = class {
    */
   async listAvailableModels() {
     try {
-      const { PROVIDER_REGISTRY } = await import('../provider-registry-3AYLGCSG.cjs');
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-NOT45GOM.cjs');
       if (!PROVIDER_REGISTRY) return [];
       const registry = PROVIDER_REGISTRY;
       const providers = Object.keys(registry);
@@ -911,7 +911,7 @@ var Harness = class {
   }
   async getProviderApiKeyEnvVar(provider) {
     try {
-      const { PROVIDER_REGISTRY } = await import('../provider-registry-3AYLGCSG.cjs');
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-NOT45GOM.cjs');
       const registry = PROVIDER_REGISTRY;
       const envVars = registry[provider]?.apiKeyEnvVar;
       return Array.isArray(envVars) ? envVars[0] : envVars;

package/dist/harness/index.js

@@ -1,5 +1,5 @@
-import { Mastra } from '../chunk-6DMP7UU3.js';
-import { Agent } from '../chunk-AGEOFSDZ.js';
+import { Mastra } from '../chunk-TF3R5TSU.js';
+import { Agent } from '../chunk-CFYLBHVD.js';
 import { Workspace, createWorkspaceTools } from '../chunk-TD7IL7ZC.js';
 import { safeStringify } from '../chunk-OLCO53KU.js';
 import { createTool } from '../chunk-JTIQYXE2.js';
@@ -830,7 +830,7 @@ var Harness = class {
       }
     }
     try {
-      const { PROVIDER_REGISTRY } = await import('../provider-registry-5XBG4HYJ.js');
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-36IRBNPU.js');
       const registry = PROVIDER_REGISTRY;
       const providerConfig = registry[provider];
       const envVars = providerConfig?.apiKeyEnvVar;
@@ -850,7 +850,7 @@ var Harness = class {
    */
   async listAvailableModels() {
     try {
-      const { PROVIDER_REGISTRY } = await import('../provider-registry-5XBG4HYJ.js');
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-36IRBNPU.js');
       if (!PROVIDER_REGISTRY) return [];
       const registry = PROVIDER_REGISTRY;
       const providers = Object.keys(registry);
@@ -909,7 +909,7 @@ var Harness = class {
   }
   async getProviderApiKeyEnvVar(provider) {
     try {
-      const { PROVIDER_REGISTRY } = await import('../provider-registry-5XBG4HYJ.js');
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-36IRBNPU.js');
       const registry = PROVIDER_REGISTRY;
       const envVars = registry[provider]?.apiKeyEnvVar;
       return Array.isArray(envVars) ? envVars[0] : envVars;

package/dist/index.cjs

@@ -1,12 +1,12 @@
 'use strict';
 
-var chunkFDZIDJEN_cjs = require('./chunk-FDZIDJEN.cjs');
+var chunkC7Y7CU7Z_cjs = require('./chunk-C7Y7CU7Z.cjs');
 
 
 
 Object.defineProperty(exports, "Mastra", {
   enumerable: true,
-  get: function () { return chunkFDZIDJEN_cjs.Mastra; }
+  get: function () { return chunkC7Y7CU7Z_cjs.Mastra; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.js

@@ -1,3 +1,3 @@
-export { Mastra } from './chunk-6DMP7UU3.js';
+export { Mastra } from './chunk-TF3R5TSU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map