@mastra/core 1.18.0 → 1.18.1-alpha.1

package/dist/docs/references/docs-streaming-events.md

@@ -145,93 +145,4 @@ Each progress event includes:
 - **`totalCount`**: Total number of iterations
 - **`currentIndex`**: Index of the iteration that completed
 - **`iterationStatus`**: Status of the iteration (`success`, `failed`, or `suspended`)
-- **`iterationOutput`**: Output of the iteration (when successful)
-
-## Inspecting agent networks
-
-When using multi-agent collaboration with `agent.network()`, iterate over the stream to track how tasks are delegated and executed across agents, workflows, and tools.
-
-```typescript
-const networkAgent = mastra.getAgent('networkAgent')
-
-const networkStream = await networkAgent.network('Research dolphins then write a report')
-
-for await (const chunk of networkStream) {
-  console.log(chunk)
-}
-```
-
-> **Info:** Visit [Agent.network()](https://mastra.ai/reference/agents/network) for more information.
-
-### Example network output
-
-Network streams emit events that track the orchestration flow. Each iteration begins with routing, followed by execution of the selected primitive.
-
-```typescript
-// Routing agent decides what to do
-{
-  type: 'routing-agent-start',
-  from: 'NETWORK',
-  runId: '7a3b9c2d-1e4f-5a6b-8c9d-0e1f2a3b4c5d',
-  payload: {
-    agentId: 'routing-agent',
-    // ...
-  }
-}
-// Routing agent makes a selection
-{
-  type: 'routing-agent-end',
-  from: 'NETWORK',
-  runId: '7a3b9c2d-1e4f-5a6b-8c9d-0e1f2a3b4c5d',
-  payload: {
-    // ...
-  }
-}
-// Delegated agent begins execution
-{
-  type: 'agent-execution-start',
-  from: 'NETWORK',
-  runId: '8b4c0d3e-2f5a-6b7c-9d0e-1f2a3b4c5d6e',
-  payload: {
-    // ...
-  }
-}
-// Events from the delegated agent's execution
-{
-  type: 'agent-execution-event-text-delta',
-  from: 'NETWORK',
-  runId: '8b4c0d3e-2f5a-6b7c-9d0e-1f2a3b4c5d6e',
-  payload: {
-    type: 'text-delta',
-    payload: {
-      // ...
-    }
-  }
-}
-```
-
-### Filtering network events
-
-You can filter events by type to track specific aspects of the network execution:
-
-```typescript
-const networkStream = await networkAgent.network('Analyze data and create visualization')
-
-for await (const chunk of networkStream) {
-  // Track routing decisions
-  if (chunk.type === 'routing-agent-end') {
-    console.log('Selected:', chunk.payload.resourceType, chunk.payload.resourceId)
-    console.log('Reason:', chunk.payload.selectionReason)
-  }
-
-  // Track agent delegations
-  if (chunk.type === 'agent-execution-start') {
-    console.log('Delegating to agent:', chunk.payload.agentId)
-  }
-
-  // Track workflow delegations
-  if (chunk.type === 'workflow-execution-start') {
-    console.log('Executing workflow:', chunk.payload.name)
-  }
-}
-```
+- **`iterationOutput`**: Output of the iteration (when successful)

package/dist/docs/references/docs-studio-auth.md

@@ -0,0 +1,142 @@
+# Studio auth
+
+When you configure [authentication](https://mastra.ai/docs/server/auth) on your Mastra server, Studio automatically displays a login screen and enforces access control. One configuration secures both the Studio UI and your API routes.
+
+Without authentication, Studio and all API routes are publicly accessible.
+
+## When to use Studio Auth
+
+- Multiple team members need to interact with agents, workflows, and tools through a shared Studio deployment.
+- Permissions must restrict who can execute agents, edit workflows, or delete datasets.
+- A login screen (SSO, email/password, or both) should gate access to your Studio deployment.
+
+## Quickstart
+
+Add an auth provider to your Mastra server configuration. This example uses [Simple Auth](https://mastra.ai/docs/server/auth/simple-auth) for a minimal setup:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { SimpleAuth } from '@mastra/core/server'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new SimpleAuth({
+      users: {
+        'my-api-key': {
+          id: 'user-1',
+          name: 'Alice',
+          role: 'admin',
+        },
+      },
+    }),
+  },
+})
+```
+
+Once configured, Studio shows a login screen and requires authentication for all API requests.
+
+> **Note:** Visit the [Auth docs](https://mastra.ai/docs/server/auth) for a full list of supported providers.
+
+## How it works
+
+Setting [`server.auth`](https://mastra.ai/reference/configuration) does two things at once:
+
+- **Studio UI**: Displays a login screen. Depending on the provider, users sign in through SSO, email/password, or both.
+- **API routes**: Requires authentication for all built-in routes (`/api/agents/*`, `/api/workflows/*`, etc.) and custom routes. This applies whether requests come from Studio or direct API calls.
+
+Studio detects available capabilities by calling the `GET /api/auth/capabilities` endpoint. The response tells Studio which login methods to render and, if the user is already authenticated, includes their user info and permissions.
+
+## Role-based access control
+
+RBAC lets you control what each user can see and do inside Studio. It's separate from authentication: `server.auth` handles who the user is, while `server.rbac` handles what they can do.
+
+### Default roles
+
+Mastra ships four default roles. Import them from `@mastra/core/auth/ee`:
+
+| Role     | Permissions              |
+| -------- | ------------------------ |
+| `owner`  | Full access (`*`)        |
+| `admin`  | Read, write, and execute |
+| `member` | Read and execute         |
+| `viewer` | Read-only                |
+
+### Enable RBAC
+
+Use `StaticRBACProvider` with the default roles or define your own:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { SimpleAuth } from '@mastra/core/server'
+import { StaticRBACProvider, DEFAULT_ROLES } from '@mastra/core/auth/ee'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new SimpleAuth({
+      users: {
+        'admin-key': { id: 'user-1', name: 'Alice', role: 'admin' },
+        'viewer-key': { id: 'user-2', name: 'Bob', role: 'viewer' },
+      },
+    }),
+    rbac: new StaticRBACProvider({
+      roles: DEFAULT_ROLES,
+      getUserRoles: user => [user.role],
+    }),
+  },
+})
+```
+
+When RBAC is active, Studio hides actions the user doesn't have permission for. A viewer doesn't see delete buttons; a member can't modify agent configurations.
+
+### Permission format
+
+Permissions follow the pattern `{resource}:{action}`, with optional resource-level scoping:
+
+| Pattern             | Meaning                     |
+| ------------------- | --------------------------- |
+| `*`                 | Full access to everything   |
+| `*:read`            | Read all resources          |
+| `agents:*`          | All actions on agents       |
+| `agents:execute`    | Execute agents only         |
+| `agents:read:my-id` | Read a specific agent by ID |
+
+Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, and others. Actions are `read`, `write`, `execute`, and `delete`.
+
+### Map external provider roles
+
+If your identity provider already defines roles (for example, Clerk organizations or WorkOS groups), map them to Mastra permissions with `roleMapping`:
+
+```typescript
+import { StaticRBACProvider } from '@mastra/core/auth/ee'
+
+const rbac = new StaticRBACProvider({
+  roleMapping: {
+    'org:admin': ['*'],
+    'org:member': ['*:read', '*:execute'],
+    'org:viewer': ['*:read'],
+  },
+  getUserRoles: user => user.providerRoles,
+})
+```
+
+## Login methods
+
+Studio adapts its login screen based on the auth provider:
+
+| Provider type    | Login UI                                |
+| ---------------- | --------------------------------------- |
+| SSO only         | SSO button (e.g. "Sign in with WorkOS") |
+| Credentials only | Email and password form                 |
+| Both             | SSO button and email/password form      |
+
+Sign-up can be enabled or disabled per provider. When disabled, Studio hides the sign-up link and forces the sign-in form.
+
+## EE licensing
+
+Studio Auth features (SSO login, RBAC, permission-based UI) are part of the Mastra Enterprise Edition. They work without a license during local development and with Simple Auth. For production deployments with third-party providers, a valid EE license is required. [Contact sales](https://mastra.ai/contact) for more information.
+
+## Related
+
+- [Auth overview](https://mastra.ai/docs/server/auth): Full list of supported auth providers.
+- [Studio deployment](https://mastra.ai/docs/studio/deployment): Deploy Studio to production.
+- [Custom API routes](https://mastra.ai/docs/server/custom-api-routes): Control authentication on individual endpoints.

package/dist/docs/references/docs-studio-deployment.md

@@ -0,0 +1,260 @@
+# Studio deployment
+
+Studio is a React-based Single Page Application (SPA) that runs in the browser and connects to a running [Mastra server](https://mastra.ai/docs/deployment/mastra-server).
+
+You can deploy Studio in two primary ways:
+
+- [Cloud](https://mastra.ai/docs/mastra-cloud/overview) hosts Studio for you and allows you to share access with your team via link
+- You can self-host Studio on your own infrastructure, either alongside your Mastra server or separately as a standalone SPA
+
+On this page you'll learn how to deploy Studio on your own infrastructure. As the finer details of deployment can vary widely based on your needs and setup, we'll cover the general principles and options available to you.
+
+## Quickstart
+
+The easiest way to run Studio is the [`mastra studio`](https://mastra.ai/reference/cli/mastra) command.
+
+Whereas `mastra dev` runs both Studio and an API for development purposes, the purpose of `mastra studio` is to serve a standalone, static UI that connects to an already-running Mastra server. This allows you to deploy Studio on its own, separate from the Mastra server, if desired.
+
+Open a terminal and install the `mastra` CLI globally:
+
+**npm**:
+
+```bash
+npm install -g mastra
+```
+
+**pnpm**:
+
+```bash
+pnpm add -g mastra
+```
+
+**Yarn**:
+
+```bash
+yarn global add mastra
+```
+
+**Bun**:
+
+```bash
+bun add --global mastra
+```
+
+Run the `mastra studio` command:
+
+```bash
+mastra studio
+```
+
+Open [localhost:3000](http://localhost:3000) in your browser to see the Studio UI. By default, it will attempt to connect to a Mastra server running at `http://localhost:4111`. If it doesn't find one there, you'll see a form where you can enter your Mastra instance URL and API prefix.
+
+If you're hosting Studio under a subpath (for example `/agents` behind Nginx), set `MASTRA_STUDIO_BASE_PATH` before starting Studio:
+
+```bash
+MASTRA_STUDIO_BASE_PATH=/agents mastra studio
+```
+
+This updates the HTML base URL and static asset routing so the standalone Studio works correctly under that subpath.
+
+The command uses Node's built-in `http` module and [`serve-handler`](https://www.npmjs.com/package/serve-handler) to serve the static files.
+
+## Running a server
+
+Running `mastra studio` as a long-running process is no different from running any other Node.js service. All the best practices, tools, and options for deployment apply here as well. You can use process managers like PM2, use Docker, or cloud services that support Node.js applications. You'll need to ensure CORS is configured correctly and errors are monitored, as with any web service.
+
+> **Warning:** Once Studio is connected to your Mastra server, it has full access to your agents, workflows, and tools. Be sure to secure it properly in production (e.g. behind authentication, VPN, etc.) to prevent unauthorized access.
+>
+> Visit the [Authentication](https://mastra.ai/docs/studio/auth) docs to learn more.
+
+### Alongside your API
+
+Alternatively, you can serve Studio alongside your [Mastra server](https://mastra.ai/docs/deployment/mastra-server). This way you only have one service to deploy and manage.
+
+To do this, run `mastra build` with the `--studio` flag:
+
+```bash
+mastra build --studio
+```
+
+It'll create a `.mastra/output/studio` folder with the built Studio assets. By defining the `MASTRA_STUDIO_PATH` environment variable, the Mastra server can serve the Studio UI, too.
+
+```bash
+MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs
+```
+
+## Using a CDN
+
+### Automatic
+
+Some of the [Cloud providers](https://mastra.ai/docs/deployment/cloud-providers) offer an option to deploy Studio alongside your serverless function. Currently, the supported providers are:
+
+- [`VercelDeployer`](https://mastra.ai/reference/deployer/vercel)
+
+### Manual
+
+You can't directly deploy the built Studio assets to a CDN, as the UI relies on some dynamic configuration. With a bit of extra setup, you can create a standalone SPA out of the built assets and deploy it to any static hosting service.
+
+Follow the example below to create a SPA using Vite.
+
+1. Create a new folder and initialize a new Node.js project:
+
+   **npm**:
+
+   ```bash
+   mkdir studio-spa
+   cd studio-spa
+   npm init
+   ```
+
+   **pnpm**:
+
+   ```bash
+   mkdir studio-spa
+   cd studio-spa
+   pnpm init
+   ```
+
+   **Yarn**:
+
+   ```bash
+   mkdir studio-spa
+   cd studio-spa
+   yarn init
+   ```
+
+   **Bun**:
+
+   ```bash
+   mkdir studio-spa
+   cd studio-spa
+   bun init
+   ```
+
+2. Install `vite` and `mastra` as dependencies:
+
+   **npm**:
+
+   ```bash
+   npm install vite mastra
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add vite mastra
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add vite mastra
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add vite mastra
+   ```
+
+3. Add a build script to your `package.json`:
+
+   ```json
+   {
+     "scripts": {
+       "build": "vite build"
+     }
+   }
+   ```
+
+4. Create a placeholder `index.html` file:
+
+   ```html
+   <!doctype html>
+   <html>
+     <head></head>
+     <body></body>
+   </html>
+   ```
+
+5. Create a `vite.config.js` file. It copies the built Studio assets to the `dist` folder and replaces any `%%PLACEHOLDER%%` values in the HTML with environment variable values.
+
+   ```js
+   import { defineConfig, loadEnv } from 'vite'
+   import { readFileSync, cpSync, writeFileSync } from 'node:fs'
+   import { resolve, join } from 'node:path'
+
+   const studioDir = resolve(import.meta.dirname, 'node_modules/mastra/dist/studio')
+
+   export default defineConfig(({ mode }) => {
+     const env = loadEnv(mode, process.cwd(), 'MASTRA_')
+
+     return {
+       plugins: [
+         {
+           name: 'mastra-studio',
+           closeBundle() {
+             const outDir = resolve(import.meta.dirname, 'dist')
+             cpSync(studioDir, outDir, { recursive: true })
+
+             const indexPath = join(outDir, 'index.html')
+             const html = readFileSync(indexPath, 'utf-8')
+             writeFileSync(
+               indexPath,
+               html.replaceAll(/%%(\w+)%%/g, (_, key) => env[key] ?? ''),
+             )
+           },
+         },
+       ],
+       build: {
+         emptyOutDir: true,
+       },
+     }
+   })
+   ```
+
+6. Create a `.env` file with the necessary environment variables.
+
+   ```env
+   MASTRA_SERVER_HOST=localhost
+   MASTRA_SERVER_PORT=4111
+   MASTRA_SERVER_PROTOCOL=http
+   MASTRA_API_PREFIX=/api
+   MASTRA_HIDE_CLOUD_CTA=false
+   MASTRA_CLOUD_API_ENDPOINT=
+   MASTRA_EXPERIMENTAL_FEATURES=false
+   MASTRA_TEMPLATES=false
+   MASTRA_TELEMETRY_DISABLED=true
+   MASTRA_REQUEST_CONTEXT_PRESETS=
+   MASTRA_THEME_TOGGLE=false
+   MASTRA_EXPERIMENTAL_UI=false
+   MASTRA_STUDIO_BASE_PATH=
+   ```
+
+7. Run the build script to generate the static files in the `dist` folder:
+
+   **npm**:
+
+   ```bash
+   npm run build
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run build
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn build
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run build
+   ```
+
+8. Point your hosting provider to the `dist` folder and deploy!

package/dist/docs/references/docs-studio-observability.md

@@ -0,0 +1,98 @@
+# Studio observability
+
+Studio includes these observability views:
+
+- **Metrics** for aggregate performance data
+- **Traces** for individual request inspection
+
+All require an [observability storage backend](#quickstart) to be configured.
+
+## Metrics
+
+A dashboard that summarizes agent, workflow, and tool performance over a configurable time range (last 24 hours to 30 days). The top row shows total agent runs, model cost, token consumption, and average scorer performance. Below that, detailed cards break down model usage and cost per model, token usage per agent, trace volume with completed and error counts, latency percentiles (p50 and p95), and scorer trends over time.
+
+Visit the [metrics overview](https://mastra.ai/docs/observability/metrics/overview) for more details.
+
+> **Note:** Metrics require a separate OLAP store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
+
+## Traces
+
+When you run an agent or workflow, the Observability tab displays traces that highlight the key AI operations such as model calls, tool executions, and workflow steps. Follow these traces to see how data moves, where time is spent, and what's happening under the hood.
+
+Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.
+
+## Quickstart
+
+For detailed instructions, follow the [observability instructions](https://mastra.ai/docs/observability/overview). To get up and running quickly, add the `@mastra/observability` package to your project and configure it with [LibSQL](https://mastra.ai/reference/storage/libsql) and [DuckDB](https://mastra.ai/reference/vectors/duckdb) for a local development setup that supports both traces and metrics.
+
+**npm**:
+
+```bash
+npm install @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+Then add the following to your `src/mastra/index.ts`:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { LibSQLStore } from '@mastra/libsql'
+import { DuckDBStore } from '@mastra/duckdb'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new LibSQLStore({
+      id: 'mastra-storage',
+      url: 'file:./mastra.db',
+    }),
+    domains: {
+      observability: await new DuckDBStore().getStore('observability'),
+    },
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [
+          new DefaultExporter(), // Persists traces to storage for Mastra Studio
+          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
+        ],
+      },
+    },
+  }),
+})
+```
+
+## Related
+
+- [Observability overview](https://mastra.ai/docs/observability/overview)
+- [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
+- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)