@mastra/browser-viewer 0.0.0-a2a-vnext-20260424123427

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 (10) hide show
  1. package/CHANGELOG.md +80 -0
  2. package/LICENSE.md +30 -0
  3. package/README.md +100 -0
  4. package/dist/index.cjs +796 -0
  5. package/dist/index.cjs.map +1 -0
  6. package/dist/index.d.cts +330 -0
  7. package/dist/index.d.ts +330 -0
  8. package/dist/index.js +768 -0
  9. package/dist/index.js.map +1 -0
  10. package/package.json +65 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,80 @@
1
+ # @mastra/browser-viewer
2
+
3
+ ## 0.0.0-a2a-vnext-20260424123427
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`092271d`](https://github.com/mastra-ai/mastra/commit/092271d86af4cbe0d70cbf32709dd99b58acd3dd)]:
8
+ - @mastra/core@0.0.0-a2a-vnext-20260424123427
9
+
10
+ ## 0.1.1
11
+
12
+ ### Patch Changes
13
+
14
+ - Remove unused `userDataDir` config option from `BrowserViewerConfig`. ([#15696](https://github.com/mastra-ai/mastra/pull/15696))
15
+
16
+ - 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))
17
+
18
+ - 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)]:
19
+ - @mastra/core@1.28.0
20
+
21
+ ## 0.1.1-alpha.0
22
+
23
+ ### Patch Changes
24
+
25
+ - Remove unused `userDataDir` config option from `BrowserViewerConfig`. ([#15696](https://github.com/mastra-ai/mastra/pull/15696))
26
+
27
+ - 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))
28
+
29
+ - Updated dependencies [[`750b4d3`](https://github.com/mastra-ai/mastra/commit/750b4d3d8231f92e769b2c485921ac5a8ca639b9)]:
30
+ - @mastra/core@1.28.0-alpha.1
31
+
32
+ ## 0.1.0
33
+
34
+ ### Minor Changes
35
+
36
+ - Initial release of @mastra/browser-viewer ([#15415](https://github.com/mastra-ai/mastra/pull/15415))
37
+
38
+ Playwright-based browser viewer for CLI providers that enables screencast visualization in Studio. Supports thread-isolated browser sessions and automatic CDP connection management.
39
+
40
+ ```typescript
41
+ import { BrowserViewer } from '@mastra/browser-viewer';
42
+
43
+ const workspace = new Workspace({
44
+ sandbox: new LocalSandbox({ cwd: './workspace' }),
45
+ browser: new BrowserViewer({
46
+ cli: 'agent-browser',
47
+ headless: false,
48
+ }),
49
+ });
50
+ ```
51
+
52
+ ### Patch Changes
53
+
54
+ - Updated dependencies [[`f112db1`](https://github.com/mastra-ai/mastra/commit/f112db179557ae9b5a0f1d25dc47f928d7d61cd9), [`21d9706`](https://github.com/mastra-ai/mastra/commit/21d970604d89eee970cbf8013d26d7551aff6ea5), [`0a0aa94`](https://github.com/mastra-ai/mastra/commit/0a0aa94729592e99885af2efb90c56aaada62247), [`ed07df3`](https://github.com/mastra-ai/mastra/commit/ed07df32a9d539c8261e892fc1bade783f5b41a6), [`01a7d51`](https://github.com/mastra-ai/mastra/commit/01a7d513493d21562f677f98550f7ceb165ba78c)]:
55
+ - @mastra/core@1.27.0
56
+
57
+ ## 0.1.0-alpha.0
58
+
59
+ ### Minor Changes
60
+
61
+ - Initial release of @mastra/browser-viewer ([#15415](https://github.com/mastra-ai/mastra/pull/15415))
62
+
63
+ Playwright-based browser viewer for CLI providers that enables screencast visualization in Studio. Supports thread-isolated browser sessions and automatic CDP connection management.
64
+
65
+ ```typescript
66
+ import { BrowserViewer } from '@mastra/browser-viewer';
67
+
68
+ const workspace = new Workspace({
69
+ sandbox: new LocalSandbox({ cwd: './workspace' }),
70
+ browser: new BrowserViewer({
71
+ cli: 'agent-browser',
72
+ headless: false,
73
+ }),
74
+ });
75
+ ```
76
+
77
+ ### Patch Changes
78
+
79
+ - Updated dependencies [[`0a0aa94`](https://github.com/mastra-ai/mastra/commit/0a0aa94729592e99885af2efb90c56aaada62247), [`01a7d51`](https://github.com/mastra-ai/mastra/commit/01a7d513493d21562f677f98550f7ceb165ba78c)]:
80
+ - @mastra/core@1.27.0-alpha.1
package/LICENSE.md ADDED
@@ -0,0 +1,30 @@
1
+ Portions of this software are licensed as follows:
2
+
3
+ - All content that resides under any directory named "ee/" within this
4
+ repository, including but not limited to:
5
+ - `packages/core/src/auth/ee/`
6
+ - `packages/server/src/server/auth/ee/`
7
+ is licensed under the license defined in `ee/LICENSE`.
8
+
9
+ - All third-party components incorporated into the Mastra Software are
10
+ licensed under the original license provided by the owner of the
11
+ applicable component.
12
+
13
+ - Content outside of the above-mentioned directories or restrictions is
14
+ available under the "Apache License 2.0" as defined below.
15
+
16
+ # Apache License 2.0
17
+
18
+ Copyright (c) 2025 Kepler Software, Inc.
19
+
20
+ Licensed under the Apache License, Version 2.0 (the "License");
21
+ you may not use this file except in compliance with the License.
22
+ You may obtain a copy of the License at
23
+
24
+ http://www.apache.org/licenses/LICENSE-2.0
25
+
26
+ Unless required by applicable law or agreed to in writing, software
27
+ distributed under the License is distributed on an "AS IS" BASIS,
28
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
29
+ See the License for the specific language governing permissions and
30
+ limitations under the License.
package/README.md ADDED
@@ -0,0 +1,100 @@
1
+ # @mastra/browser-viewer
2
+
3
+ Playwright-based browser viewer for Mastra workspaces with CLI provider support.
4
+
5
+ ## Overview
6
+
7
+ `@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:
8
+
9
+ - **Full screencast support** — Direct page-level CDP sessions
10
+ - **Input injection** — Mouse and keyboard events work correctly
11
+ - **Browser lifecycle control** — Browser starts/stops with the server
12
+ - **CLI flexibility** — Agent uses skills + workspace commands to drive any CLI
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install @mastra/browser-viewer
18
+ # or
19
+ pnpm add @mastra/browser-viewer
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ ### Basic Setup
25
+
26
+ ```typescript
27
+ import { BrowserViewer } from '@mastra/browser-viewer';
28
+
29
+ const viewer = new BrowserViewer({
30
+ cli: 'agent-browser', // Which CLI the agent will use
31
+ headless: false, // Show browser window
32
+ });
33
+
34
+ // Launch browser
35
+ await viewer.launch();
36
+
37
+ // Get CDP URL for CLIs to connect
38
+ const cdpUrl = await viewer.getCdpUrl();
39
+ console.log(cdpUrl); // ws://127.0.0.1:9222/devtools/browser/...
40
+ ```
41
+
42
+ ### Connect to Existing Browser
43
+
44
+ ```typescript
45
+ import { BrowserViewer } from '@mastra/browser-viewer';
46
+
47
+ const viewer = new BrowserViewer({
48
+ cli: 'agent-browser',
49
+ cdpUrl: 'ws://127.0.0.1:9222/devtools/browser/abc123',
50
+ });
51
+ ```
52
+
53
+ ### With Workspace
54
+
55
+ The CDP URL is automatically injected into CLI commands when used with workspace tools.
56
+
57
+ ```typescript
58
+ import { Workspace, LocalSandbox } from '@mastra/core';
59
+ import { BrowserViewer } from '@mastra/browser-viewer';
60
+
61
+ const workspace = new Workspace({
62
+ sandbox: new LocalSandbox({ cwd: './workspace' }),
63
+ browser: new BrowserViewer({
64
+ cli: 'agent-browser',
65
+ headless: false,
66
+ }),
67
+ });
68
+
69
+ // When agent runs: agent-browser open https://google.com
70
+ // Mastra auto-injects the CDP connection so CLI uses Mastra's browser
71
+ ```
72
+
73
+ ## Configuration
74
+
75
+ | Option | Type | Default | Description |
76
+ | ---------------- | -------------------------------------------------- | ---------- | ------------------------------------------------ |
77
+ | `cli` | `'agent-browser' \| 'browser-use' \| 'browse-cli'` | Required | Which CLI the agent uses |
78
+ | `cdpUrl` | `string` | - | Connect to existing browser instead of launching |
79
+ | `headless` | `boolean` | `true` | Run browser in headless mode |
80
+ | `cdpPort` | `number` | `0` (auto) | Port for Chrome remote debugging |
81
+ | `viewport` | `{ width, height }` | `1280x720` | Browser viewport size |
82
+ | `executablePath` | `string` | - | Path to Chrome executable |
83
+
84
+ ## How It Works
85
+
86
+ 1. **BrowserViewer launches Chrome** via Playwright with `--remote-debugging-port`
87
+ 2. **Agent calls CLI commands** via `workspace_execute_command`
88
+ 3. **CDP URL is auto-injected** so CLI connects to Mastra-managed Chrome
89
+ 4. **Screencast streams** directly from page-level CDP sessions
90
+ 5. **Browser closes** when server exits
91
+
92
+ ## Supported CLIs
93
+
94
+ - **agent-browser** — Vercel's browser automation CLI (`--cdp <port>`)
95
+ - **browser-use** — Python-based browser automation (`--cdp-url <url>`)
96
+ - **browse-cli** — Browserbase's Stagehand CLI (`--ws <url>`)
97
+
98
+ ## License
99
+
100
+ Apache-2.0