@mastra/mcp-docs-server 1.1.46 → 1.1.49-alpha.0

package/.docs/docs/agent-builder/access-control.md

@@ -15,18 +15,18 @@ The Agent Builder ships with two supported roles: `admin` and `member`. Wire the
 
 The Builder UI calls several resources on load, so a usable `member` role needs explicit grants on each. The Builder action layer (`/agent-builder/*`) is one resource; the data it reads and writes lives under separate resources.
 
-| Permission                            | Used for                                                      |
-| ------------------------------------- | ------------------------------------------------------------- |
-| `agent-builder:*`                     | Load Builder actions, runs, and stream Builder workflows      |
-| `agents:read`, `agents:execute`       | List registered agents and chat with the Builder agent        |
-| `stored-agents:*`                     | List, view, create, and edit agents                           |
-| `stored-skills:*`                     | List, view, create, and edit stored skills                    |
-| `stored-workspaces:*`                 | Pick a workspace when editing an agent                        |
-| `tools:read`, `tools:execute`         | Populate the tool picker and run tools through agents         |
-| `workflows:read`, `workflows:execute` | Populate the workflow picker and run workflows through agents |
-| `memory:read`                         | Preview memory configuration in the picker                    |
-| `channels:read`                       | Show Slack/channel chips on agent pages                       |
-| `infrastructure:read`                 | Builder diagnostics banner on the shell                       |
+| Permission                            | Used for                                                                                                                                                    |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent-builder:*`                     | Load Builder actions and run Builder workflows. The derived Builder actions are `agent-builder:read` and `agent-builder:execute`; the wildcard grants both. |
+| `agents:read`, `agents:execute`       | List registered agents and chat with the Builder agent                                                                                                      |
+| `stored-agents:*`                     | List, view, create, and edit agents                                                                                                                         |
+| `stored-skills:*`                     | List, view, create, and edit stored skills                                                                                                                  |
+| `stored-workspaces:*`                 | Pick a workspace when editing an agent                                                                                                                      |
+| `tools:read`, `tools:execute`         | Populate the tool picker and run tools through agents                                                                                                       |
+| `workflows:read`, `workflows:execute` | Populate the workflow picker and run workflows through agents                                                                                               |
+| `memory:read`                         | Preview memory configuration in the picker                                                                                                                  |
+| `channels:read`                       | Show Slack/channel chips on agent pages                                                                                                                     |
+| `infrastructure:read`                 | Builder diagnostics banner on the shell                                                                                                                     |
 
 Grant `:write`, `:delete`, and `:publish` on `stored-agents` and `stored-skills` for users who should create or modify agents. The `:*` wildcards in the table above cover those actions. `admin` covers everything through the `*` wildcard.
 
@@ -85,13 +85,13 @@ export const mastra = new Mastra({
 
 Permission patterns follow `resource:action`. Wildcards are supported on either side:
 
-- `*` — full access (every resource, every action). Used by `admin`.
-- `agent-builder:*` — every action on the `agent-builder` resource.
-- `*:read` — `read` across every resource.
+- `*`: Full access (every resource, every action). Used by `admin`.
+- `agent-builder:*`: Every action on the `agent-builder` resource.
+- `*:read`: `read` Across every resource.
 
 Patterns resolve through `matchesPermission()`. The first matching role permission grants the action.
 
 ## Related
 
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire RBAC alongside the rest of the Builder config.
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying) — auth, RBAC, and EE license setup for production.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire RBAC alongside the rest of the Builder config.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Auth, RBAC, and EE license setup for production.

package/.docs/docs/agent-builder/browser.md

@@ -2,7 +2,7 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
-The Agent Builder can give end-user agents a browser tool driven by a registered provider. Unlike filesystems and sandboxes, **there are no built-in browser providers** — you must register one through `MastraEditor.browsers`.
+The Agent Builder can give end-user agents a browser tool driven by a registered provider. Unlike filesystems and sandboxes, **there are no built-in browser providers** and you must register one through `MastraEditor.browsers`.
 
 ## Quickstart
 
@@ -44,9 +44,9 @@ new MastraEditor({
 
 `MastraEditor.browsers` accepts a `Record<string, BrowserProvider>`. Each provider exposes:
 
-- `id` — provider identifier, matched against `StorageBrowserConfig.provider` (e.g., `'stagehand'`).
-- `name` — display name shown in the Builder UI.
-- `createBrowser(config)` — hydrates a stored browser config into a runtime `MastraBrowser`. This is where you inject runtime-only credentials (API keys, project IDs) that aren't stored in the agent snapshot.
+- `id`: Provider identifier, matched against `StorageBrowserConfig.provider` (e.g., `'stagehand'`).
+- `name`: Display name shown in the Builder UI.
+- `createBrowser(config)`: Hydrates a stored browser config into a runtime `MastraBrowser`. This is where you inject runtime-only credentials (API keys, project IDs) that aren't stored in the agent snapshot.
 
 Browser classes ship as separate packages (e.g., `@mastra/stagehand`, `@mastra/agent-browser`). The provider entry is a plain object wrapping the class — register one entry per browser you want the Builder to expose to end users. See the [StorageBrowserRef reference](https://mastra.ai/reference/editor/storage-browser-ref) for the full `browser` field schema, including all `StorageBrowserConfig` options.
 
@@ -56,6 +56,6 @@ The `features.agent.browser` toggle controls whether end users can enable browse
 
 ## Related
 
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `browser` field schema.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the full Builder config surface, including `features.agent.browser`.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `browser` alongside the rest of the Builder config.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `browser` field schema.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): The full Builder config surface, including `features.agent.browser`.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `browser` alongside the rest of the Builder config.

package/.docs/docs/agent-builder/channels.md

@@ -63,8 +63,8 @@ The Slack provider handles app creation, OAuth, slash commands, and message rout
 
 `SlackProvider` requires one environment variable and accepts one optional override:
 
-- `SLACK_APP_CONFIG_REFRESH_TOKEN` (required): the refresh token from your Slack app configuration tokens, available under **Your App Configuration Tokens** on [api.slack.com/apps](https://api.slack.com/apps). The refresh token doesn't expire, but the access tokens it issues rotate every 12 hours and are auto-persisted to `Mastra.storage`.
-- `baseUrl` (optional): the public URL Slack should send events and OAuth callbacks to. Defaults to the running Mastra server's host and port (for example, `http://localhost:4111` in local development). Pass `baseUrl` explicitly when the public URL differs from the server's resolved address — typically a tunnel for local development (`cloudflared tunnel --url http://localhost:4111`) or a deployed URL in production.
+- `SLACK_APP_CONFIG_REFRESH_TOKEN` (required): The refresh token from your Slack app configuration tokens, available under **Your App Configuration Tokens** on [api.slack.com/apps](https://api.slack.com/apps). The refresh token doesn't expire, but the access tokens it issues rotate every 12 hours and are auto-persisted to `Mastra.storage`.
+- `baseUrl` (optional): The public URL Slack should send events and OAuth callbacks to. Defaults to the running Mastra server's host and port (for example, `http://localhost:4111` in local development). Pass `baseUrl` explicitly when the public URL differs from the server's resolved address — typically a tunnel for local development (`cloudflared tunnel --url http://localhost:4111`) or a deployed URL in production.
 
 ## Storage requirement
 
@@ -72,5 +72,5 @@ The Slack provider handles app creation, OAuth, slash commands, and message rout
 
 ## Related
 
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying) — set a public `baseUrl` for production deployments.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire channel toggles into the Builder UI.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Set a public `baseUrl` for production deployments.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire channel toggles into the Builder UI.

package/.docs/docs/agent-builder/configuration.md

@@ -39,43 +39,26 @@ new MastraEditor({
         tools: true,
         agents: true,
         workflows: true,
+        scorers: true,
         skills: true,
         memory: true,
+        variables: true,
+        favorites: true,
+        avatarUpload: true,
         model: true,
         browser: true,
-        avatarUpload: true,
-        favorites: true,
       },
     },
   },
 })
 ```
 
-The shipping UI consumes these `AgentFeatures` keys: `tools`, `agents`, `workflows`, `skills`, `memory`, `model`, `browser`, `avatarUpload`, and `favorites`. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full schema.
+The shipping UI consumes these `AgentFeatures` keys: `tools`, `agents`, `workflows`, `scorers`, `skills`, `memory`, `variables`, `favorites`, `avatarUpload`, `model`, and `browser`. See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full schema.
 
 ## Admin defaults
 
 `builder.configuration.agent` pins admin-controlled defaults onto every agent the Builder produces.
 
-```typescript
-new MastraEditor({
-  builder: {
-    enabled: true,
-    configuration: {
-      agent: {
-        models: {
-          allowed: [
-            { provider: 'openai', modelId: 'gpt-5.4-mini' },
-            { provider: 'openai', modelId: 'gpt-5.4' },
-            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
-          ],
-        },
-      },
-    },
-  },
-})
-```
-
 `configuration.agent` accepts `models`, `memory`, `workspace`, `browser`, `tools`, `agents`, and `workflows`. See the [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) for the full shape.
 
 ## Making tools, agents, and workflows available
@@ -118,9 +101,9 @@ MCP tools work the same way: load them via `MCPClient.getTools()` and spread the
 
 `configuration.agent.tools`, `configuration.agent.agents`, and `configuration.agent.workflows` constrain which registered entries appear in the Builder's pickers. Allowlist semantics are the same for all three:
 
-- **Omitted**: unrestricted. The picker shows every registered entry.
-- **`allowed: []`**: explicit lockdown. The picker is empty.
-- **`allowed: [...ids]`**: the picker shows only the listed IDs.
+- **Omitted**: Unrestricted. The picker shows every registered entry.
+- **`allowed: []`**: Explicit lockdown. The picker is empty.
+- **`allowed: [...ids]`**: The picker shows only the listed IDs.
 
 Unknown IDs are dropped and surfaced as warnings through `getModelPolicyWarnings()` and the server logs.
 
@@ -141,7 +124,7 @@ new MastraEditor({
 
 ## Related
 
-- [Model policy](https://mastra.ai/docs/agent-builder/model-policy) — pin the allowed models and default model.
-- [Memory](https://mastra.ai/docs/agent-builder/memory) — set the default memory shape for new agents.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — full property list.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — every field on `configuration.agent`.
+- [Model policy](https://mastra.ai/docs/agent-builder/model-policy): Pin the allowed models and default model.
+- [Memory](https://mastra.ai/docs/agent-builder/memory): Set the default memory shape for new agents.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): Full property list.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Every field on `configuration.agent`.

package/.docs/docs/agent-builder/deploying.md

@@ -2,16 +2,16 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
-Production deployments swap the local primitives in the Quickstart for cloud-backed equivalents. The shape of the `Mastra` and `MastraEditor` config doesn't change — only the providers behind it.
+Production deployments swap the local primitives in the Quickstart for cloud-backed equivalents. The shape of the `Mastra` and `MastraEditor` config doesn't change, only the providers behind it.
 
 ## What a production deployment needs
 
-1. **EE license** — a valid `MASTRA_EE_LICENSE` so the server will start with the Builder enabled.
-2. **Hosted storage** — a shared store for agents, skills, runs, and memory.
-3. **Shared workspace filesystem** — survives across instances; `local` is single-node only.
-4. **Cloud sandbox** — runs agent commands safely; `local` is unsafe in shared environments.
-5. **Auth and RBAC** — gates the Builder UI and `/agent-builder/*` routes.
-6. **Public base URL for channels** — Slack and other channel providers need a reachable URL.
+1. **EE license**: A valid `MASTRA_EE_LICENSE` so the server will start with the Builder enabled.
+2. **Hosted storage**: A shared store for agents, skills, runs, and memory.
+3. **Shared workspace filesystem**: Survives across instances; `local` is single-node only.
+4. **Cloud sandbox**: Runs agent commands safely; `local` is unsafe in shared environments.
+5. **Auth and RBAC**: Gates the Builder UI and `/agent-builder/*` routes.
+6. **Public base URL for channels**: Slack and other channel providers need a reachable URL.
 
 ## EE license
 
@@ -101,7 +101,7 @@ new Mastra({
 
 `S3Filesystem` uses the default AWS credential chain (environment variables, `~/.aws` config, IAM roles, EC2 instance profile). For long-running deployments, use a credential provider function so credentials refresh automatically.
 
-`DockerSandbox` and `VercelSandbox` are alternative cloud sandbox providers — pick whichever matches your runtime.
+`DockerSandbox` and `VercelSandbox` are alternative cloud sandbox providers, pick whichever matches your runtime.
 
 > **Warning:** A local sandbox can't run commands safely in a shared environment. Always register a cloud sandbox provider and reference it in the workspace config before deploying.
 
@@ -117,5 +117,5 @@ Slack needs to reach your server through a public URL. Pass `baseUrl` to `SlackP
 
 ## Related
 
-- [Access control](https://mastra.ai/docs/agent-builder/access-control) — auth and RBAC setup.
-- [Channels](https://mastra.ai/docs/agent-builder/channels) — Slack `baseUrl` and channel-specific setup.
+- [Access control](https://mastra.ai/docs/agent-builder/access-control): Auth and RBAC setup.
+- [Channels](https://mastra.ai/docs/agent-builder/channels): Slack `baseUrl` and channel-specific setup.

package/.docs/docs/agent-builder/memory.md

@@ -60,6 +60,6 @@ If a required adapter is missing, Mastra throws a descriptive error at agent run
 
 ## Related
 
-- [Memory overview](https://mastra.ai/docs/memory/overview) — concepts and core configuration.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `memory` field schema.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `memory` alongside the rest of the Builder config.
+- [Memory overview](https://mastra.ai/docs/memory/overview): Concepts and core configuration.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `memory` field schema.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `memory` alongside the rest of the Builder config.

package/.docs/docs/agent-builder/model-policy.md

@@ -43,6 +43,6 @@ See the [`builder.configuration.agent.models`](https://mastra.ai/reference/edito
 
 ## Related
 
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire the model policy into the broader Builder config.
-- [`builder.configuration.agent.models`](https://mastra.ai/reference/editor/agent-builder/builder-models) — full property list.
-- [Provider registry](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/llm/model/provider-registry.json) — every model ID Mastra recognizes out of the box.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire the model policy into the broader Builder config.
+- [`builder.configuration.agent.models`](https://mastra.ai/reference/editor/agent-builder/builder-models): Full property list.
+- [Provider registry](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/llm/model/provider-registry.json): Every model ID Mastra recognizes out of the box.

package/.docs/docs/agent-builder/overview.md

@@ -7,6 +7,8 @@ The Agent Builder lets you build, configure, and operate Mastra agents all withi
 - [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.
 - [**Model policy**](https://mastra.ai/docs/agent-builder/model-policy): Restrict which providers and models the Builder exposes, and pin a default.
 - [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
+- [**Workspace**](https://mastra.ai/docs/agent-builder/workspace): Configure the default filesystem, sandbox, and skills workspace for Builder-created agents.
+- [**Browser**](https://mastra.ai/docs/agent-builder/browser): Register browser providers and pin a default browser configuration.
 - [**Access control**](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder behind Mastra RBAC roles and permissions.
 - [**Channels**](https://mastra.ai/docs/agent-builder/channels): Connect Builder-created agents to Slack and other channels.
 - [**Tool providers**](https://mastra.ai/docs/agent-builder/integrations): Connect Builder-created agents to third-party apps through OAuth-backed tool providers.
@@ -15,9 +17,18 @@ The Agent Builder lets you build, configure, and operate Mastra agents all withi
 
 For building agents entirely in code, see the [Agents overview](https://mastra.ai/docs/agents/overview). For editing code-defined agents through Studio, see the [Editor overview](https://mastra.ai/docs/editor/overview).
 
+## Prerequisites
+
+The Agent Builder requires:
+
+- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
+- **Storage**: A `@mastra/core` storage adapter on the `Mastra` instance. Agents, memory, and workspace state all persist through `Mastra.storage`.
+- **A builder agent**: Register a `builderAgent` created with the `createBuilderAgent()` factory from `@mastra/editor/ee` on `Mastra.agents`. The chat-based editor invokes it through the same `Mastra.getAgent(id)` lookup as any other agent. Without this registration, the chat-based editor returns 404.
+- **Model credentials**: `createBuilderAgent()` uses an OpenAI model by default, which requires `OPENAI_API_KEY`. To use a different provider, pass a `model` override to `createBuilderAgent({ model })` and set that provider's credentials instead.
+
 ## Get started
 
-Install `@mastra/editor` alongside a storage adapter:
+Install `@mastra/editor` alongside a storage adapter. This example uses `@mastra/libsql`:
 
 **npm**:
 
@@ -43,7 +54,7 @@ yarn add @mastra/editor @mastra/libsql
 bun add @mastra/editor @mastra/libsql
 ```
 
-Wire the Agent Builder onto a `Mastra` instance:
+The example below defines a storage adapter, registers a builder agent, and enables the editor as explained in the prerequisites:
 
 ```typescript
 import { Mastra } from '@mastra/core/mastra'
@@ -67,7 +78,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Start the dev server:
+Start Mastra's development server:
 
 ```bash
 npx mastra dev
@@ -75,14 +86,6 @@ npx mastra dev
 
 The Agent Builder is mounted at `http://localhost:4111/agent-builder`.
 
-## Prerequisites
-
-The Agent Builder requires:
-
-- **Storage**: An `@mastra/core` storage adapter on the `Mastra` instance. Agents, memory, and workspace state all persist through `Mastra.storage`.
-- **The Builder agent**: Register a Builder agent created with the `createBuilderAgent()` factory from `@mastra/editor/ee` on `Mastra.agents`. The chat-based editor invokes it through the same `Mastra.getAgent(id)` lookup as any other agent. Without this registration, the chat-based editor returns 404.
-- **`OPENAI_API_KEY`**: The Builder agent created by `createBuilderAgent()` runs on an OpenAI model, so an `OPENAI_API_KEY` environment variable is required.
-
 ## Disabling the Builder
 
 Set `enabled: false` to keep the config in place but turn the surface off:
@@ -95,4 +98,10 @@ new MastraEditor({
 })
 ```
 
-Omitting the `builder` field has the same effect.
+Omitting the `builder` field has the same effect.
+
+## Next steps
+
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Toggle Builder surfaces and pin defaults for new agents.
+- [Access control](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder with authentication and role-based access control.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.

package/.docs/docs/agent-builder/skill-registries.md

@@ -27,5 +27,5 @@ The Builder library tab now exposes a **Browse** view backed by skills.sh. End u
 
 ## Related
 
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire registries alongside the rest of the Builder config.
-- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — every field on `builder`.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire registries alongside the rest of the Builder config.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options): Every field on `builder`.

package/.docs/docs/agent-builder/workspace.md

@@ -41,8 +41,8 @@ The Builder derives a deterministic id from the inline config and persists the s
 
 `configuration.agent.workspace` accepts a `StorageWorkspaceRef`:
 
-- **`{ type: 'inline', config }`** — embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
-- **`{ type: 'id', workspaceId }`** — references a workspace already registered on the `Mastra` instance via `new Mastra({ workspace })` or `mastra.addWorkspace(...)`. Use this for shared, named workspaces.
+- **`{ type: 'inline', config }`**: Embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
+- **`{ type: 'id', workspaceId }`**: References a workspace already registered on the `Mastra` instance via `new Mastra({ workspace })` or `mastra.addWorkspace(...)`. Use this for shared, named workspaces.
 
 See the [StorageWorkspaceRef reference](https://mastra.ai/reference/editor/storage-workspace-ref) for both variants.
 
@@ -54,7 +54,7 @@ For cloud deployments, swap `LocalFilesystem` / `LocalSandbox` for managed provi
 
 ## Related
 
-- [Workspace overview](https://mastra.ai/docs/workspace/overview) — the underlying workspace model.
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem) and [Sandbox](https://mastra.ai/docs/workspace/sandbox) — the building blocks.
-- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `workspace` field schema.
-- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `workspace` alongside the rest of the Builder config.
+- [Workspace overview](https://mastra.ai/docs/workspace/overview): The underlying workspace model.
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem) and [Sandbox](https://mastra.ai/docs/workspace/sandbox): The building blocks.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): The full `workspace` field schema.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration): Wire `workspace` alongside the rest of the Builder config.

package/.docs/docs/agents/goals.md

@@ -0,0 +1,110 @@
+# Goals
+
+**Added in:** `@mastra/core@1.42.0`
+
+A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it is satisfied or a run budget is exhausted. The objective is persisted in thread state, so it survives reloads and is evaluated in-loop — even when a new message arrives in the middle of an already-running turn.
+
+Goals build on the same machinery as [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents): an LLM-as-judge scores the agent's output each iteration and gates the loop. The difference is that a goal is **durable** (stored in thread state, not passed per call) and is set and updated through `Agent` methods rather than per-`stream()` options.
+
+> **Note:** Goals are experimental and may change in a future release.
+
+## When to use goals
+
+Use a goal when you want an agent to keep working toward a single objective across many iterations and messages, without re-supplying the success criteria on every call:
+
+- A standing objective the agent should pursue until a judge says it's done.
+- Work that should continue across mid-run messages (a message delivered into a live run is still judged against the goal).
+- An objective that must persist across thread reloads or process restarts.
+
+For a one-off completion check within a single `stream()` call, use [`isTaskComplete`](https://mastra.ai/docs/agents/supervisor-agents) instead.
+
+## Quickstart
+
+Goals require a configured [storage](https://mastra.ai/docs/memory/storage) backend and a memory-backed thread. Add a `goal` config to the agent — a judge model is required for the goal to do anything — then set an objective for a thread:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+const worker = new Agent({
+  name: 'worker',
+  instructions: 'You complete software tasks end to end.',
+  model: 'openai/gpt-5.5',
+  memory,
+  goal: {
+    judge: 'openai/gpt-5-mini',
+    maxRuns: 50,
+  },
+})
+
+// Set the durable objective for a thread.
+await worker.setObjective('Add and test a /health endpoint', {
+  threadId,
+  resourceId,
+})
+
+// The objective is judged each iteration until it's complete or maxRuns is hit.
+const stream = await worker.stream('Start working on the goal', {
+  memory: { thread: threadId, resource: resourceId },
+})
+```
+
+The `goal` config auto-registers the state-signal projection, so the model always sees the current objective as `<current-objective>` in its context — no extra setup needed.
+
+## How the goal step works
+
+A goal step runs inside the agentic execution loop, right after `isTaskComplete`. On a real candidate answer it scores the conversation against the objective and gates the loop:
+
+- **Not satisfied, budget remaining** → the loop continues; per-evaluation feedback is injected so the agent iterates.
+- **Satisfied** → the loop stops and the objective is marked `done`.
+- **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops but the objective stays `active`, so raising `maxRuns` later can resume it.
+
+The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations — the same gating as `isTaskComplete`.
+
+**The judge model is the activation switch.** If no judge resolves (neither the per-objective override nor the agent's `goal.judge`), the goal step does nothing: no scoring, no budget consumed, no `goal` chunk. Effective settings resolve as per-objective record value → agent `goal` config → built-in default (`maxRuns` `50`, a default judge prompt).
+
+By default the step uses a built-in LLM-as-judge scorer that returns `1` when the objective is achieved and `0` otherwise. Supply your own scorer with `goal.scorer` to customize judging.
+
+```typescript
+const worker = new Agent({
+  name: 'worker',
+  instructions: 'You complete software tasks end to end.',
+  model: 'openai/gpt-5.5',
+  memory,
+  goal: {
+    // A resolver function lets you inject provider credentials and read the
+    // current judge selection at runtime; returning `undefined` keeps the
+    // goal step a no-op.
+    judge: ({ requestContext }) => resolveJudgeModel(requestContext),
+    maxRuns: 30,
+    prompt: 'Only mark the goal complete when tests pass.',
+  },
+})
+```
+
+Each evaluation emits a typed `goal` stream chunk (`GoalEvaluationPayload`: `objective`, `iteration`, `maxRuns`, `passed`, `status`, `results`, `reason`, `duration`, `timedOut`, `maxRunsReached`, `suppressFeedback`) so a UI can show goal progress mid-run.
+
+## Managing the objective
+
+Control the objective for a thread with `Agent` methods. All of them no-op when the run is not memory-backed (they require storage and a `threadId`):
+
+```typescript
+// Read the current objective record.
+const record = await worker.getObjective({ threadId })
+
+// Update options on the active objective (only provided fields are written;
+// unset fields fall back to the agent's `goal` config).
+await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
+
+// Drop the objective.
+await worker.clearObjective({ threadId })
+```
+
+Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state.
+
+> **Note:** See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
+
+## Related
+
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `isTaskComplete` and the rubric scorer
+- [Signal providers](https://mastra.ai/docs/agents/signal-providers) — how the objective is projected into context
+- [Memory storage](https://mastra.ai/docs/memory/storage) — the storage backend goals require

package/.docs/docs/agents/using-tools.md

@@ -224,6 +224,8 @@ export const weatherTool = createTool({
 })
 ```
 
+`toModelOutput` also works on client-side tools passed through `clientTools`. The mapping runs on the client after the tool executes, and the transformed output is sent back to the server alongside the raw result.
+
 ## Transform tool payloads for UI and transcripts
 
 Use `transform` when a tool returns raw data your application needs, but browser-facing streams or user-visible transcript messages should receive a smaller or safer shape. `transform` is separate from `toModelOutput`: `toModelOutput` shapes the payload sent back to the model, while `transform` shapes tool input, output, errors, approval payloads, and suspension payloads for `display` and `transcript` targets.

package/.docs/docs/browser/agent-browser.md

@@ -84,10 +84,26 @@ const browser = new AgentBrowser({
 
 AgentBrowser uses accessibility tree refs to identify elements. When an agent calls `browser_snapshot`, it receives a text representation of the page with refs like `@e1`, `@e2`, etc. The agent then uses these refs with other tools to interact with elements.
 
+## Recording
+
+AgentBrowser can opt into alpha browser recording tools:
+
+```typescript
+const browser = new AgentBrowser({
+  headless: false,
+  recording: {
+    outputDir: './browser-recordings',
+  },
+})
+```
+
+This adds `browser_record` and `browser_record_caption` to the agent's toolset. See [Browser recording (alpha)](https://mastra.ai/docs/browser/recording) for details.
+
 > **Note:** See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
 
 ## Related
 
 - [Browser overview](https://mastra.ai/docs/browser/overview)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser)

package/.docs/docs/browser/overview.md

@@ -7,6 +7,7 @@ Mastra supports two SDK providers and one CLI provider:
 - [**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.
 - [**BrowserViewer**](https://mastra.ai/docs/browser/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
+- [**Browser recording (alpha)**](https://mastra.ai/docs/browser/recording): An opt-in tool layer that saves browser sessions as Motion-JPEG AVI videos with optional captions.
 
 ## When to use browser
 
@@ -164,5 +165,6 @@ const browser = new AgentBrowser({
 
 - [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
 - [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
 - [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
 - [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/.docs/docs/browser/recording.md

@@ -0,0 +1,108 @@
+# Browser recording (alpha)
+
+Browser recording adds two opt-in tools that let an agent save a browser session as a Motion-JPEG AVI video. The agent can also add short captions while it works.
+
+> **Caution:** Browser recording is an alpha feature. The API and output format may change.
+
+## When to use browser recording
+
+Use browser recording when you need to:
+
+- Review what an agent did in a browser
+- Share a short browser automation run with a teammate
+- Debug missed actions, slow page loads, or unexpected navigation
+- Add short captions that explain each major step
+
+Recording tools are disabled by default. Enable them only for agents that need to write video files.
+
+## Enable recording
+
+Pass `recording.outputDir` to `AgentBrowser` or `StagehandBrowser`. The browser provider adds the `browser_record` and `browser_record_caption` tools to the agent's toolset.
+
+The following example enables recording for `AgentBrowser`:
+
+```typescript
+import { join } from 'node:path'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+export const browser = new AgentBrowser({
+  headless: false,
+  recording: {
+    outputDir: join(process.cwd(), 'browser-recordings'),
+  },
+})
+```
+
+The same option works with `StagehandBrowser`:
+
+```typescript
+import { join } from 'node:path'
+import { StagehandBrowser } from '@mastra/stagehand'
+
+export const browser = new StagehandBrowser({
+  headless: false,
+  recording: {
+    outputDir: join(process.cwd(), 'browser-recordings'),
+  },
+})
+```
+
+## Recording tools
+
+Enabling recording adds these tools:
+
+| Tool                     | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `browser_record`         | Starts, stops, or checks the status of a recording.          |
+| `browser_record_caption` | Adds a short caption at the current moment in the recording. |
+
+`browser_record` accepts an `action` field:
+
+- `start`: Start recording the current browser session.
+- `status`: Check whether a recording is active.
+- `stop`: Stop recording and write the `.avi` file.
+
+The `outputPath` option for `browser_record` must be an absolute path inside the configured `recording.outputDir`. If you omit it, Mastra creates a file in `outputDir`.
+
+## Example agent instructions
+
+Tell the agent when to record and when to add captions:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { browser } from '../browsers'
+
+export const browserAgent = new Agent({
+  id: 'browser-agent',
+  name: 'Browser Agent',
+  model: 'openai/gpt-5.5',
+  browser,
+  instructions: `Use browser tools to complete the requested task.
+
+When the user asks for a recording:
+1. Call browser_record with action="start" before browser work begins.
+2. After each major action, call browser_record_caption with a caption of about six words.
+3. Call browser_record with action="stop" as soon as the task is complete.
+4. Return the saved video path to the user.`,
+})
+```
+
+## Output format and limits
+
+Recordings are saved as Motion-JPEG AVI files. This format is encoded in JavaScript and does not require `ffmpeg` or native dependencies.
+
+Default limits:
+
+- Maximum duration: 30 seconds
+- Hard duration cap: 120 seconds
+- Maximum frame size: 1024 × 720
+- Captions: 80 characters each
+- One active recording per process
+
+Use shorter recordings when possible. Long browser sessions produce larger files and are harder to review.
+
+## Next steps
+
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Browser overview](https://mastra.ai/docs/browser/overview)