feat(browser): add @mastra/browser-viewer package with Playwright-based CLI provider (#15415)

## Summary

Adds package for Playwright-based browser management with CLI providers
(agent-browser, browser-use, browse-cli), enabling screencast
visualization in Studio.

## What's New

### @mastra/browser-viewer (new package)
- **`BrowserViewer`** class that launches Chrome via Playwright with
`--remote-debugging-port`
- Thread-isolated browser sessions with automatic lifecycle management
- CDP URL exposure for CLI tools to connect as secondary clients
- Screencast support via direct page-level CDP sessions

### @mastra/core changes
- **`Workspace.browser`** configuration for CLI provider integration
- **`BrowserCliHandler`** for automatic CDP URL injection into browser
CLI commands
- **`MastraBrowser.providerType`** property (`'sdk'` | `'cli'`) and
`connectToExternalCdp()` method
- Support for external CDP connections when agents provide their own
browser endpoints
- Fixed CWD path duplication in LocalProcessManager

## How It Works

```typescript
import { BrowserViewer } from '@mastra/browser-viewer';

const workspace = new Workspace({
  sandbox: new LocalSandbox({ cwd: './workspace' }),
  browser: new BrowserViewer({ headless: false }),
});
```

When an agent uses a browser CLI command:
1. `BrowserViewer` lazily launches Chrome with remote debugging enabled
2. `BrowserCliHandler` automatically injects the CDP URL into CLI
commands
3. CLI tools connect to the existing browser as secondary CDP clients
4. Screencast streams from the browser to Studio

**Supported CLIs:**
- `agent-browser` — via `--cdp <port>` and warmup `connect` command
- `browser-use` — via `--cdp-url <url>`
- `browse` — via `--ws <url>`

**External CDP support:** If an agent provides their own CDP URL (e.g.,
browser-use cloud), the system detects it, skips injection, and connects
`BrowserViewer` to the external browser for screencast.

## Testing Notes

- **Local sandbox only** — Remote sandbox support not yet implemented
(would need different CDP discovery)
- Browser CLIs must be installed separately (`npm i -g agent-browser`,
`pipx install browser-use`, etc.)

## Related
- Builds on SDK providers from #14938 (merged)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
ELI5: This PR adds a small tool that can launch or connect to Chrome and
share a WebSocket CDP URL so CLI browser tools can talk to it—letting
Studio show live browser screencasts and interact with those CLIs. It
also wires core workspace/agent logic so CLI browser commands get
auto-configured, warmed up, and lifecycle-managed.

- New package: @mastra/browser-viewer
- Playwright-based BrowserViewer that can launch Chrome (with
--remote-debugging-port) or connect to an existing CDP endpoint.
- Thread-isolated or shared browser sessions via
BrowserViewerThreadManager; exposes getCdpUrl(threadId?) for external
CLI clients.
- Screencast support using per-page CDP sessions with reconnection
handling, URL update events, and input injection (mouse/keyboard)
through CDP.
- Public API exports: BrowserViewer, BrowserViewerThreadManager,
BrowserViewerConfig, CLIProvider, and thread-manager config type.
- README, build/test/lint configs, package.json, ESLint config and
changeset for initial release.

- Core integrations (packages/core)
- Workspace.browser: optional MastraBrowser provider (must be
providerType: 'cli'); browser closed on workspace.destroy; browser not
auto-launched on init.
  - MastraBrowser additions:
    - providerType: 'sdk' | 'cli' (default 'sdk').
    - getCdpUrl(threadId?): string | null.
- launch(threadId?) and isBrowserRunning(threadId?) support thread-aware
lifecycles.
- connectToExternalCdp(cdpUrl, threadId?) hook (base throws by default;
BrowserViewer implements).
- Screencast gating now checks thread-aware running state and
thread-session presence.
  - Browser CLI handling:
- New BrowserCliHandler (singleton browserCliHandler) with CLI
detection, external-CDP extraction, CDP injection into chained shell
commands, warmup command generation, and warmup lifecycle cleanup tied
to browser close.
- Shell utilities: splitShellCommand and reassembleShellCommand for
quote-aware command splitting/rewriting, plus tests.
  - execute-command flow:
    - Commands are analyzed for browser CLIs before sandbox execution.
- If workspace.browser exists and the CLI is internal (no external CDP),
launch browser per-thread as needed, obtain cdpUrl, run warmup commands
(best-effort), inject CDP URL and session flags into the command, and
register warmup cleanup.
- If an external CDP URL is detected, attempt
browser.connectToExternalCdp(externalCdpUrl, threadId) (errors ignored),
and skip injection.
  - Agent/browser interactions:
- Agent construction now validates explicit config.browser must be
providerType === 'sdk' (otherwise AGENT_INVALID_BROWSER_PROVIDER).
- Agent resolution favors explicitly configured browser;
workspace-derived browser is applied unless explicit.
- Per-request browser context injection now includes providerType and,
for CLI providers, cdpUrl when the thread is running.
- Agents without browsers can use a workspace-provided browser when
appropriate.
- ThreadManager visibility tweak: onSessionCreated/onSessionDestroyed
changed to protected for subclass use.

- Browser-viewer internals
- Thread manager supports owned browserServer launches
(chromium.launchServer), discovers DevToolsActivePort to build CDP URL,
connects via Playwright (connectOverCDP) for external endpoints, creates
contexts/pages, caches per-page CDP sessions, wires disconnect handlers,
and supports clean closeAll.
- BrowserViewer implements startScreencast to provide a stream backed by
per-page CDP sessions and handles reconnects on navigation/new
page/close.
- Input injection routes Input.dispatchMouseEvent/Input.dispatchKeyEvent
via per-thread CDP sessions.

- Commits / runtime fixes and refinements
- Fixes to active-tab logic and caching of CDP sessions for input
injection to reduce overhead.
- Dedicated screencast CDP session creation and improved external CDP
detection (including --cdp <port> patterns).
- Explicit browser unset/ disconnect detection (Target.targetDestroyed)
and propagation of browser close events from ThreadManager to
ViewerRegistry.
- ViewerRegistry enhanced to explicitly stop streams and broadcast
browser_closed on screencast errors.

- Bug fixes
- LocalProcessManager cwd duplication fixed: relative cwd resolution
avoids duplicating workspace path when already workspace-relative.
- ViewerRegistry now broadcasts browser_closed on screencast stream
errors so UI won't remain 'Live' after errors.

- Tests
  - New and extended tests:
- BrowserCliHandler end-to-end suite (detection, extraction, injection,
warmup lifecycle).
    - Utilities tests for shell splitting and reassembly.
- execute-command tests validating browser launch, CDP injection, warmup
behavior, and external CDP connect handling.
    - Adjusted mocks/serialization to include providerType where needed.

- Docs & release
- README for @mastra/browser-viewer and changesets added for
@mastra/browser-viewer and @mastra/core; release notes document initial
package and core CLI-browser integration.
- Operational notes: local sandbox only; browser CLIs must be installed
separately (e.g., agent-browser, browser-use, browse). Remote
sandbox/browser-hosting not included in this PR.

- Scope & reviewer notes
- Large new feature surface: major review focus on browser-viewer thread
manager/browser-viewer files and core/browser CLI-handling integration.
Backwards compatibility preserved: MastraBrowser defaults remain
SDK-type and workspace.browser validation prevents misconfiguration.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Mastra Code (anthropic/claude-opus-4-5) <noreply@mastra.ai>

Author: NikAiyer

.changeset/bright-windows-glow.md

@@ -0,0 +1,19 @@
+---
+'@mastra/browser-viewer': minor
+---
+
+Initial release of @mastra/browser-viewer
+
+Playwright-based browser viewer for CLI providers that enables screencast visualization in Studio. Supports thread-isolated browser sessions and automatic CDP connection management.
+
+```typescript
+import { BrowserViewer } from '@mastra/browser-viewer';
+
+const workspace = new Workspace({
+  sandbox: new LocalSandbox({ cwd: './workspace' }),
+  browser: new BrowserViewer({
+    cli: 'agent-browser',
+    headless: false,
+  }),
+});
+```

.changeset/old-guests-hammer.md

@@ -0,0 +1,7 @@
+---
+'@mastra/core': minor
+---
+
+Added support for CLI-driven browser automation with screencast support in `@mastra/core`, including automatic CDP injection for browser CLIs.
+
+Fixed local process spawning so workspace-relative `cwd` values no longer get duplicated.

.changeset/warm-dots-flow.md

@@ -0,0 +1,5 @@
+---
+'@mastra/server': patch
+---
+
+Fixed screencast panel staying "Live" after browser closes due to an error. The `ViewerRegistry` now broadcasts `browser_closed` status when a screencast stream emits an error, not just when it stops cleanly.

browser/agent-browser/tsconfig.json

@@ -2,7 +2,6 @@
   "extends": "../../tsconfig.node.json",
   "compilerOptions": {
     "outDir": "./dist",
-    "rootDir": "./src",
     "moduleResolution": "bundler",
     "types": ["node"]
   },

browser/browser-viewer/README.md

@@ -0,0 +1,101 @@
+# @mastra/browser-viewer
+
+Playwright-based browser viewer for Mastra workspaces with CLI provider support.
+
+## Overview
+
+`@mastra/browser-viewer` provides `BrowserViewer`, which launches Chrome via Playwright and exposes the CDP URL for CLI tools (agent-browser, browser-use, browse-cli) to connect. This gives you:
+
+- **Full screencast support** — Direct page-level CDP sessions
+- **Input injection** — Mouse and keyboard events work correctly
+- **Browser lifecycle control** — Browser starts/stops with the server
+- **CLI flexibility** — Agent uses skills + workspace commands to drive any CLI
+
+## Installation
+
+```bash
+npm install @mastra/browser-viewer
+# or
+pnpm add @mastra/browser-viewer
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { BrowserViewer } from '@mastra/browser-viewer';
+
+const viewer = new BrowserViewer({
+  cli: 'agent-browser', // Which CLI the agent will use
+  headless: false, // Show browser window
+});
+
+// Launch browser
+await viewer.launch();
+
+// Get CDP URL for CLIs to connect
+const cdpUrl = await viewer.getCdpUrl();
+console.log(cdpUrl); // ws://127.0.0.1:9222/devtools/browser/...
+```
+
+### Connect to Existing Browser
+
+```typescript
+import { BrowserViewer } from '@mastra/browser-viewer';
+
+const viewer = new BrowserViewer({
+  cli: 'agent-browser',
+  cdpUrl: 'ws://127.0.0.1:9222/devtools/browser/abc123',
+});
+```
+
+### With Workspace
+
+The CDP URL is automatically injected into CLI commands when used with workspace tools.
+
+```typescript
+import { Workspace, LocalSandbox } from '@mastra/core';
+import { BrowserViewer } from '@mastra/browser-viewer';
+
+const workspace = new Workspace({
+  sandbox: new LocalSandbox({ cwd: './workspace' }),
+  browser: new BrowserViewer({
+    cli: 'agent-browser',
+    headless: false,
+  }),
+});
+
+// When agent runs: agent-browser open https://google.com
+// Mastra auto-injects the CDP connection so CLI uses Mastra's browser
+```
+
+## Configuration
+
+| Option           | Type                                               | Default    | Description                                      |
+| ---------------- | -------------------------------------------------- | ---------- | ------------------------------------------------ |
+| `cli`            | `'agent-browser' \| 'browser-use' \| 'browse-cli'` | Required   | Which CLI the agent uses                         |
+| `cdpUrl`         | `string`                                           | -          | Connect to existing browser instead of launching |
+| `headless`       | `boolean`                                          | `false`    | Run browser in headless mode                     |
+| `cdpPort`        | `number`                                           | `0` (auto) | Port for Chrome remote debugging                 |
+| `viewport`       | `{ width, height }`                                | `1280x720` | Browser viewport size                            |
+| `userDataDir`    | `string`                                           | -          | Chrome profile directory                         |
+| `executablePath` | `string`                                           | -          | Path to Chrome executable                        |
+
+## How It Works
+
+1. **BrowserViewer launches Chrome** via Playwright with `--remote-debugging-port`
+2. **Agent calls CLI commands** via `workspace_execute_command`
+3. **CDP URL is auto-injected** so CLI connects to Mastra-managed Chrome
+4. **Screencast streams** directly from page-level CDP sessions
+5. **Browser closes** when server exits
+
+## Supported CLIs
+
+- **agent-browser** — Vercel's browser automation CLI (`--cdp <port>`)
+- **browser-use** — Python-based browser automation (`--cdp-url <url>`)
+- **browse-cli** — Browserbase's Stagehand CLI (`--ws <url>`)
+
+## License
+
+Apache-2.0

browser/browser-viewer/eslint.config.js

@@ -0,0 +1,6 @@
+import { createConfig } from '@internal/lint/eslint';
+
+const config = await createConfig();
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [...config];

browser/browser-viewer/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@mastra/browser-viewer",
+  "version": "0.0.0",
+  "description": "Playwright-based browser viewer for Mastra CLI providers",
+  "type": "module",
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup --silent --config tsup.config.ts",
+    "build:watch": "tsup --watch --silent --config tsup.config.ts",
+    "test": "vitest run",
+    "lint": "eslint ."
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "playwright-core": "^1.52.0",
+    "typed-emitter": "^2.1.0"
+  },
+  "devDependencies": {
+    "@internal/lint": "workspace:*",
+    "@internal/types-builder": "workspace:*",
+    "@mastra/core": "workspace:*",
+    "@types/node": "22.15.21",
+    "@vitest/coverage-v8": "catalog:",
+    "@vitest/ui": "catalog:",
+    "eslint": "^9.27.0",
+    "tsup": "^8.5.0",
+    "typescript": "catalog:",
+    "vitest": "catalog:",
+    "zod": "catalog:"
+  },
+  "peerDependencies": {
+    "@mastra/core": ">=1.26.0-0 <2.0.0-0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "homepage": "https://mastra.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mastra-ai/mastra.git",
+    "directory": "browser/browser-viewer"
+  },
+  "bugs": {
+    "url": "https://github.com/mastra-ai/mastra/issues"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  }
+}