@mastra/mcp-docs-server 1.2.13-alpha.9 → 1.2.13

package/.docs/reference/editor/prompt-blocks.md

@@ -0,0 +1,137 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Prompt blocks
+
+Prompt blocks are reusable instruction templates managed by Editor. An agent's instructions can combine inline text, embedded prompt blocks, and references to independently versioned prompt blocks.
+
+See [Prompt blocks](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+
+## Block types
+
+| Type               | Description                                                       |
+| ------------------ | ----------------------------------------------------------------- |
+| `text`             | Free-form text stored only in the agent version                   |
+| `prompt_block`     | A prompt block embedded in the agent version                      |
+| `prompt_block_ref` | A reference to an independently stored and versioned prompt block |
+
+Referenced blocks resolve at runtime. A missing or unpublished reference is omitted from the final instructions. Resolved nonempty blocks are joined with two newlines.
+
+The following example attaches a stored block and inline text to an agent:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.agent.update({
+  id: 'support-agent',
+  instructions: [
+    { type: 'prompt_block_ref', id: 'brand-voice' },
+    { type: 'text', content: 'Answer only questions about Acme products.' },
+  ],
+})
+```
+
+## Template values
+
+Templates resolve values from the request context at runtime.
+
+| Syntax                    | Request context              | Output             |
+| ------------------------- | ---------------------------- | ------------------ |
+| `{{userName}}`            | `{ userName: 'Maya' }`       | `Maya`             |
+| `{{user.name}}`           | `{ user: { name: 'Maya' } }` | `Maya`             |
+| `{{task \|\| 'request'}}` | `{}`                         | `request`          |
+| `{{missingValue}}`        | `{}`                         | `{{missingValue}}` |
+
+Variable names must begin with a letter or underscore. Fallbacks must be single-quoted or double-quoted strings. Unresolved placeholders without a fallback remain unchanged. Objects and arrays are serialized as JSON. Other values are converted to strings.
+
+Pass values through [request context](https://mastra.ai/docs/server/request-context). Editor doesn't read a separate agent `variables` field.
+
+## Display conditions
+
+A prompt block can include a display condition that controls whether it's included in the final instructions. Each condition has three parts:
+
+- **Key**: The request-context field to check, such as `user.role` or `account.plan`.
+- **Operator**: The comparison to make, such as `equals`, `contains`, or `exists`.
+- **Value**: The value to compare against. The `exists` and `not_exists` operators don't need one.
+
+For example, the condition `user.role` `equals` `admin` includes the block only when request context contains `{ user: { role: 'admin' } }`.
+
+| Operator                                       | Example                                       | The block is included when                                |
+| ---------------------------------------------- | --------------------------------------------- | --------------------------------------------------------- |
+| `equals` / `not_equals`                        | `user.role` equals `admin`                    | The field strictly equals, or doesn't equal, the value    |
+| `contains` / `not_contains`                    | `user.tags` contains `beta`                   | A string contains the value or an array contains the item |
+| `greater_than` / `less_than`                   | `order.total` greater than `100`              | The numeric field is above or below the value             |
+| `greater_than_or_equal` / `less_than_or_equal` | `account.seats` greater than or equal to `10` | The numeric field is at or beyond the value               |
+| `in` / `not_in`                                | `user.region` in `['US', 'CA']`               | The field is, or isn't, in the supplied array             |
+| `exists` / `not_exists`                        | `account.plan` exists                         | The field has, or doesn't have, a non-null value          |
+
+Groups combine conditions with `AND` or `OR`. For example, this group includes a block for admins on a paid plan:
+
+```typescript
+const rules = {
+  operator: 'AND',
+  conditions: [
+    {
+      field: 'user.role',
+      operator: 'equals',
+      value: 'admin',
+    },
+    {
+      field: 'account.plan',
+      operator: 'in',
+      value: ['pro', 'enterprise'],
+    },
+  ],
+}
+```
+
+Dot paths are supported. An empty group evaluates to `true`, and an unknown operator evaluates to `false`. The storage type supports up to three nested group levels.
+
+Blocks without conditions are always included.
+
+## Programmatic API
+
+Access prompt blocks through `mastra.getEditor().prompt`. See the [`prompt` namespace](https://mastra.ai/reference/editor/mastra-editor) for complete method signatures.
+
+Create a prompt block:
+
+```typescript
+import { mastra } from '../mastra'
+
+const editor = mastra.getEditor()!
+
+await editor.prompt.create({
+  id: 'brand-voice',
+  name: 'Brand voice',
+  description: 'Acme tone and style guidelines',
+  content: 'Write in a friendly, concise tone. Address the user as {{userName || "there"}}.',
+})
+```
+
+Update an existing block:
+
+```typescript
+await editor.prompt.update({
+  id: 'brand-voice',
+  content: 'Write in a friendly, concise tone. Greet the user by name when available.',
+})
+```
+
+`update()` creates a new draft when the content changes. Use `list()` to paginate through stored blocks, `getById()` to fetch one block, and `preview(blocks, context)` to resolve templates and conditions with draft references.
+
+## REST API
+
+The default Mastra server prefix is `/api`. A custom server prefix changes the paths below.
+
+| Method   | Path                                             | Description                  |
+| -------- | ------------------------------------------------ | ---------------------------- |
+| `GET`    | `/api/stored/prompt-blocks`                      | List stored prompt blocks    |
+| `POST`   | `/api/stored/prompt-blocks`                      | Create a stored prompt block |
+| `GET`    | `/api/stored/prompt-blocks/:storedPromptBlockId` | Get a stored prompt block    |
+| `PATCH`  | `/api/stored/prompt-blocks/:storedPromptBlockId` | Update a stored prompt block |
+| `DELETE` | `/api/stored/prompt-blocks/:storedPromptBlockId` | Delete a stored prompt block |
+
+## Version resolution
+
+Runtime references resolve the active published block. Editor previews resolve the latest draft. See [Editor versioning](https://mastra.ai/docs/editor/overview) for the shared draft, publish, and restore lifecycle.

package/.docs/reference/editor/sandbox-provider.md

@@ -57,7 +57,7 @@ Once registered, admins can reference the provider from an inline workspace conf
 
 ## Related
 
-- [Workspace](https://mastra.ai/docs/agent-builder/workspace): Concept and worked examples.
+- [Workspace](https://agent-builder.mastra.ai/workspace): Concept and worked examples.
 - [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref): Stored configuration consumed by `createSandbox`.
 - [FilesystemProvider](https://mastra.ai/reference/editor/filesystem-provider): Sibling provider for file access.
 - [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor): Provider registry.

package/.docs/reference/editor/storage-browser-ref.md

@@ -4,7 +4,7 @@
 
 `StorageBrowserRef` is the inline browser configuration attached to a stored agent. The `provider` id is resolved at hydration time against the [`BrowserProvider`](https://mastra.ai/reference/editor/browser-provider) registered on [`MastraEditor.browsers`](https://mastra.ai/reference/editor/mastra-editor).
 
-It's the type used by [`BuilderAgentDefaults.browser`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.browser`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 
@@ -76,7 +76,7 @@ The shape embedded under `config`. Defined in `@mastra/core/storage`.
 
 ## Related
 
-- [Browser](https://mastra.ai/docs/agent-builder/browser): Concept and worked examples.
+- [Browser](https://agent-builder.mastra.ai/browser): Concept and worked examples.
 - [BrowserProvider](https://mastra.ai/reference/editor/browser-provider): Implementer-facing provider interface.
-- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Where this type is pinned as the Builder default.
+- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults): Where this type is pinned as the Builder default.
 - [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref): Sibling reference type for workspace configuration.

package/.docs/reference/editor/storage-workspace-ref.md

@@ -4,7 +4,7 @@
 
 `StorageWorkspaceRef` is the discriminated union used to attach a workspace to a stored agent. It either points at a workspace registered on the Mastra runtime by ID, or embeds a workspace snapshot inline.
 
-It's the type used by [`BuilderAgentDefaults.workspace`](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) and by stored agent records.
+It's the type used by [`BuilderAgentDefaults.workspace`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) and by stored agent records.
 
 ## Usage example
 
@@ -89,7 +89,7 @@ The shape embedded under `{ type: 'inline', config }`. Defined in `@mastra/core/
 
 ## Related
 
-- [Workspace](https://mastra.ai/docs/agent-builder/workspace): Concept and worked examples.
-- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults): Where this type is pinned as the Builder default.
+- [Workspace](https://agent-builder.mastra.ai/workspace): Concept and worked examples.
+- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults): Where this type is pinned as the Builder default.
 - [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor): Registers filesystem and sandbox providers.
 - [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref): Sibling reference type for browser configuration.

package/.docs/reference/editor/tool-provider.md

@@ -4,19 +4,47 @@
 
 The `ToolProvider` interface defines how the editor discovers and resolves integration tools from external platforms. Mastra includes two built-in implementations: `ComposioToolProvider` and `ArcadeToolProvider`.
 
-See [Tools](https://mastra.ai/docs/editor/tools) for a guide on setting up tool providers.
+See [Editor tools](https://mastra.ai/docs/editor/overview) for provider setup and the Studio workflow. See [tool configuration](https://mastra.ai/reference/editor/tools) for stored selections and resolution behavior.
 
 ## ToolProvider interface
 
-Tool providers implement these methods:
+Providers expose metadata and the legacy discovery and resolution methods. Agent Builder integrations can also implement the optional VNext catalog, connection, authorization, and health methods.
 
-**listToolkits()** (`() => Promise<Toolkit[]>`): Returns a list of available toolkits (tool categories) from the provider.
+**info** (`ToolProviderInfo`): Provider ID, name, and description.
 
-**listTools(params?)** (`(params?) => Promise<Tool[]>`): Returns a list of available tools. Accepts optional filtering by toolkit, search query, and limit.
+**displayName** (`string`): Optional name shown in the tool picker. Defaults to info.name.
 
-**getToolSchema(slug)** (`(slug: string) => Promise<JSONSchema>`): Returns the JSON schema for a specific tool identified by its slug.
+**capabilities** (`ToolProviderCapabilities`): Static connection and revocation capabilities. Required for VNext providers.
 
-**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. Built-in providers use resourceId from request context for per-user authentication.
+**defaultScope** (`'per-author' | 'caller-supplied'`): Default connection identity scope. Defaults to 'per-author' when omitted.
+
+**listToolkits()** (`() => Promise<ToolProviderListResult<ToolProviderToolkit>>`): Lists available toolkits through the legacy interface.
+
+**listTools(params?)** (`(params?: ListToolProviderToolsOptions) => Promise<ToolProviderListResult<ToolProviderToolInfo>>`): Lists tools with optional toolkit, search, and pagination filters.
+
+**getToolSchema(slug)** (`(slug: string) => Promise<Record<string, unknown> | null>`): Returns a tool input schema through the legacy interface.
+
+**resolveTools(slugs, configs?, options?)** (`(slugs: string[], configs?: Record<string, StorageToolConfig>, options?: ResolveToolProviderToolsOptions) => Promise<Record<string, ToolAction>>`): Resolves legacy tool selections into executable Mastra tools.
+
+**listToolkitsVNext()** (`() => Promise<ListToolkitsResult>`): Lists allowed toolkits for Agent Builder and Editor.
+
+**listToolsVNext(options?)** (`(options?: ListToolsOpts) => Promise<ListToolsResult>`): Lists allowed tools with toolkit, search, and pagination options.
+
+**resolveToolsVNext(options)** (`(options: ResolveToolsOpts) => Promise<Record<string, ToolAction>>`): Resolves tools for one set of slugs and one authorized connection.
+
+**authorize(options)** (`(options: AuthorizeOpts) => Promise<{ url: string; authId: string }>`): Starts an authorization flow.
+
+**listConnectionFields(options)** (`(options: { toolkit: string }) => Promise<ConnectionField[]>`): Lists provider-specific values required to authorize a toolkit.
+
+**getAuthStatus(authId)** (`(authId: string) => Promise<AuthFlowStatus>`): Returns the state of an authorization flow.
+
+**getConnectionStatus(options)** (`(options: { items: Array<{ connectionId: string; toolkit: string }> }) => Promise<Record<string, { connected: boolean }>>`): Checks whether a batch of connections is still active.
+
+**listConnections(options)** (`(options: ListConnectionsOpts) => Promise<ListConnectionsResult>`): Lists existing provider connections for a user and toolkit.
+
+**getHealth()** (`() => Promise<ToolProviderHealth>`): Returns provider configuration and reachability health.
+
+**revokeConnection(connectionId)** (`(connectionId: string) => Promise<void>`): Revokes a provider connection.
 
 ***
 
@@ -28,7 +56,7 @@ Connects to [Composio](https://composio.dev) for access to hundreds of integrati
 
 ```typescript
 import { MastraEditor } from '@mastra/editor'
-import { ComposioToolProvider } from '@mastra/editor/providers/composio'
+import { ComposioToolProvider } from '@mastra/editor/composio'
 
 const editor = new MastraEditor({
   toolProviders: {
@@ -43,13 +71,19 @@ const editor = new MastraEditor({
 
 **apiKey** (`string`): Your Composio API key.
 
+**allowedToolkits** (`readonly string[]`): Toolkit slug allowlist. Supports exact matches and suffix wildcards.
+
+**allowedTools** (`Readonly<Record<string, readonly string[]>>`): Per-toolkit tool slug allowlists. Supports exact matches and prefix wildcards.
+
+**defaultScope** (`'per-author' | 'caller-supplied'`): Connection identity scope. Defaults to per-author. (Default: `'per-author'`)
+
 ### Tool slugs
 
 Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MESSAGE`.
 
 ### Authentication
 
-Tool execution is scoped to the `resourceId` passed through request context. The provider maps that value to the user identity required by Composio's auth flow.
+Connections use per-author scope by default. Set `defaultScope: 'caller-supplied'` to bucket authorization by the caller identity resolved from request context.
 
 ***
 
@@ -61,7 +95,7 @@ Connects to [Arcade](https://arcade.dev) for a curated tool catalog with built-i
 
 ```typescript
 import { MastraEditor } from '@mastra/editor'
-import { ArcadeToolProvider } from '@mastra/editor/providers/arcade'
+import { ArcadeToolProvider } from '@mastra/editor/arcade'
 
 const editor = new MastraEditor({
   toolProviders: {
@@ -84,4 +118,4 @@ Arcade tools use `Toolkit.ToolName` format: `Github.GetRepository`, `Slack.SendM
 
 ### Authentication
 
-Like Composio, tool execution uses `resourceId` from request context for per-user authorization. The provider maps that value to the user identity required by Arcade's auth flow.
+The legacy Arcade resolver uses `resourceId` from request context when available. It otherwise falls back to the supplied `userId`, then to a shared `default` identity. Use `default` only for intentionally shared integrations. In tenant-isolated deployments, provide a trusted, stable `resourceId` or explicit `userId`. Omitting both doesn't isolate callers.

package/.docs/reference/editor/tools.md

@@ -0,0 +1,100 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Tool configuration
+
+Editor stores tool selections as part of an agent version. A stored configuration can add registered tools, tools from integration providers, and tools from Model Context Protocol (MCP) clients.
+
+See [Editor tools](https://mastra.ai/docs/editor/overview) for the Studio workflow and common uses.
+
+## Tool sources
+
+| Source                                                             | Description                                                                          |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| Registered tools                                                   | Tools registered in the Mastra runtime tool registry                                 |
+| MCP clients                                                        | Tools exposed by stored local or remote MCP server configurations                    |
+| Integration tools                                                  | Tools resolved by legacy integration-provider configuration                          |
+| [Tool providers](https://mastra.ai/reference/editor/tool-provider) | Tools resolved by providers registered on `MastraEditor`, such as Composio or Arcade |
+
+Code-defined agents keep their existing tools. The [`editor` override setting](https://mastra.ai/reference/agents/agent) controls whether Editor can add and remove tools or only change descriptions.
+
+## Description overrides
+
+Each selected tool can store an agent-specific description. The description changes what the model sees without modifying the original tool definition.
+
+In description-only mode, Editor applies overrides only to tools that already exist on the code-defined agent. For MCP tools, an agent-level description takes priority over the description stored on the MCP client.
+
+If two sources resolve the same tool ID, the later source replaces the complete earlier tool, including its description. See [Resolution order](#resolution-order).
+
+## Conditional tool sets
+
+Editor can store conditional variants for the `tools`, `mcpClients`, `integrationTools`, and `toolProviders` fields. At runtime, matching variants are shallow-merged based on request-context values.
+
+The rule language uses the same operators and nesting behavior as [prompt block display conditions](https://mastra.ai/reference/editor/prompt-blocks).
+
+Conditions apply to a tool field variant or MCP client reference. Per-tool `rules` values in stored tool entries aren't evaluated by the current Editor resolver.
+
+## Stored MCP clients
+
+The `editor.mcp` namespace manages reusable MCP client configurations. See the [`mcp` namespace](https://mastra.ai/reference/editor/mastra-editor) for CRUD method signatures.
+
+`@mastra/mcp` is an optional peer dependency of `@mastra/editor`. Install it before configuring stored MCP clients so Editor can load their tools at runtime:
+
+**npm**:
+
+```bash
+npm install @mastra/mcp
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mcp
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mcp
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mcp
+```
+
+### Transports
+
+| Transport | Stored configuration                                 |
+| --------- | ---------------------------------------------------- |
+| `stdio`   | `command` with optional `args`, `env`, and `timeout` |
+| HTTP      | `url` with optional `timeout`                        |
+
+Stored HTTP definitions don't accept arbitrary headers. When the reserved `mastra__authToken` value is present in request context, Editor forwards it as an `Authorization: Bearer` header.
+
+### Filtering
+
+MCP tools can be allowlisted at two levels:
+
+1. **Server level**: The stored server's `tools` map limits tools for every agent that uses the client.
+2. **Agent level**: The agent's MCP client reference limits the remaining tools for that agent.
+
+Agent-level tool names can use namespaced or bare names. An explicit empty `tools` map selects all tools. With the current resolver, omitting `tools` from an agent-level MCP reference selects none.
+
+### Namespacing
+
+MCP tools use `serverName_toolName` IDs to avoid conflicts. A `search` tool from the `docs` server becomes `docs_search`.
+
+## Resolution order
+
+Editor merges tool records in the following order. Later records replace earlier records with the same ID.
+
+1. Code-defined tools
+2. Registered stored tools
+3. MCP tools
+4. Legacy integration tools
+5. V1 tool-provider tools
+
+Standalone stored agents use the same order without code-defined tools. Static code-agent overrides stop after legacy integration tools.
+
+Use unique tool IDs across sources when possible. A collision replaces the complete earlier tool rather than merging its fields.

package/.docs/reference/editor/versioning.md

@@ -0,0 +1,130 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Versioning
+
+Editor versions stored agents and prompt blocks. Database-backed resources use draft and publish operations. Code-backed agent overrides use deterministic files and Git history.
+
+See [Editor versioning](https://mastra.ai/docs/editor/overview) for release and experimentation patterns.
+
+## Database lifecycle
+
+The resource record stores an `activeVersionId`. Individual snapshots don't store a lifecycle status.
+
+| Term       | Meaning                                                                                      |
+| ---------- | -------------------------------------------------------------------------------------------- |
+| Latest     | The most recently created configuration snapshot                                             |
+| Published  | The snapshot selected by `activeVersionId`                                                   |
+| Draft      | The latest snapshot when it differs from `activeVersionId`, or when no active version exists |
+| Historical | Any other retained snapshot                                                                  |
+
+Saving changed snapshot fields creates a new latest version. Saving identical snapshot fields or changing metadata alone doesn't create a version.
+
+If an active version exists, creating a draft doesn't change the version handling published requests. Publishing updates `activeVersionId`. Restoring a historical version copies its configuration into a new inactive draft.
+
+The direct namespace methods and REST APIs differ in one important way. `editor.prompt.update()` creates an inactive draft. `editor.agent.update()` creates a version and immediately assigns it to `activeVersionId`. The stored-agent REST `PATCH` route creates an inactive draft unless `autoPublish` is enabled.
+
+When a generic stored resource has no active version, published resolution can fall back to the latest snapshot. For a code-defined agent override, requesting `status: 'published'` without an active override returns the original code agent.
+
+## Code source
+
+With `source: 'code'`, active agent overrides are serialized as deterministic JSON under `<codePath>/agents/<encodedAgentId>.json`. The default `codePath` is `./mastra/editor`.
+
+The initial agent is published to create the file. Later server updates create a draft by default and write the file when that version becomes active. Git versions are read-only in Studio and use the commit message as their change message. The default history scan reads up to 50 recent commits and skips consecutive commits whose parsed JSON snapshot is unchanged.
+
+See [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor) for source options.
+
+## Select an agent version
+
+Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a selector returns the registered code-defined agent. Pass `status` or `versionId` to apply a stored override. See [Select a version](https://mastra.ai/docs/editor/overview) for a TypeScript example.
+
+With the default server prefix, pass selectors as query parameters under `/api`:
+
+```bash
+# Published version
+curl http://localhost:4111/api/agents/support-agent
+
+# Latest draft
+curl http://localhost:4111/api/agents/support-agent?status=draft
+
+# Exact version
+curl http://localhost:4111/api/agents/support-agent?versionId=abc-123
+```
+
+See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agents) for Client SDK and React SDK selectors.
+
+## Sub-agent versioning
+
+Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/agents/supervisor-agents) in request context. Define selectors at three levels:
+
+1. `Mastra` instance `versions`: Defaults for every invocation
+2. Server request-body `versions`: Per-request values added to request context
+3. Direct `generate()` or `stream()` `versions`: Per-invocation values
+
+Entries merge by agent ID. For the same ID, precedence is **direct invocation > request body or existing request context > Mastra instance default**.
+
+Set defaults on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  agents: { supervisor, researchAgent, writerAgent },
+  editor: new MastraEditor(),
+  versions: {
+    agents: {
+      'research-agent': { status: 'published' },
+      'writer-agent': { versionId: 'abc-123' },
+    },
+  },
+})
+```
+
+Override one sub-agent for a direct invocation:
+
+```typescript
+const result = await supervisor.generate('Research and write about AI safety', {
+  versions: {
+    agents: {
+      'research-agent': { status: 'draft' },
+    },
+  },
+})
+```
+
+Or pass selectors in the server request body:
+
+```bash
+curl -X POST http://localhost:4111/api/agents/supervisor/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [{ "role": "user", "content": "Research AI safety" }],
+    "versions": {
+      "agents": {
+        "research-agent": { "status": "draft" }
+      }
+    }
+  }'
+```
+
+If Editor isn't configured or a version can't be resolved, Mastra logs a warning and uses the code-defined sub-agent.
+
+## Stored-agent REST API
+
+The default Mastra server prefix is `/api`. A custom server prefix changes the paths below.
+
+| Method   | Path                                           | Description                                                          |
+| -------- | ---------------------------------------------- | -------------------------------------------------------------------- |
+| `GET`    | `/api/stored/agents`                           | List stored agents                                                   |
+| `POST`   | `/api/stored/agents`                           | Create a stored agent                                                |
+| `GET`    | `/api/stored/agents/:storedAgentId`            | Get a stored agent                                                   |
+| `PATCH`  | `/api/stored/agents/:storedAgentId`            | Update a stored agent                                                |
+| `DELETE` | `/api/stored/agents/:storedAgentId`            | Delete a stored agent                                                |
+| `GET`    | `/api/stored/agents/:storedAgentId/dependents` | List readable dependents and count hidden cross-workspace references |
+| `POST`   | `/api/stored/agents/:storedAgentId/export`     | Export the allowed override fields as deterministic JSON             |
+
+The dependents response lists caller-readable agents by `id` and `name`. Its `hiddenCount` field counts cross-workspace references that the caller can't read, but only when the target agent is public.
+
+Version-management routes are nested under `/api/stored/agents/:storedAgentId/versions`. See [version management](https://mastra.ai/reference/client-js/agents) for operations and Client SDK methods.
+
+The Client SDK exposes `listStoredAgents()`, `createStoredAgent()`, and `getStoredAgent()`. The resource returned by `getStoredAgent(id)` includes methods for updates, deletion, dependents, export, and version management.

package/.docs/reference/evals/mastra-scorer.md

@@ -76,16 +76,19 @@ const result = await scorer.run({
 The optional `judge` record contains details about the judge model calls made by prompt-based scorer steps. Its known keys are `preprocess`, `analyze`, `generateScore`, and `generateReason`. Each key contains an ordered `executions` array.
 
 ```typescript
-interface ScorerJudgeExecutionSuccess {
-  status: 'success'
+interface ScorerJudgeExecutionBase {
   prompt: string
-  output: JSONValue
   judgeModelId: string
   judgeProvider?: string
-  usage: ScorerJudgeUsage
   attemptCount: number
   modelCallCount: number
   durationMs: number
+}
+
+interface ScorerJudgeExecutionSuccess extends ScorerJudgeExecutionBase {
+  status: 'success'
+  output: JSONValue
+  usage: ScorerJudgeUsage
   cost?: {
     amount: number
     unit: string
@@ -93,7 +96,20 @@ interface ScorerJudgeExecutionSuccess {
   }
 }
 
-type ScorerJudgeExecution = ScorerJudgeExecutionSuccess
+interface ScorerJudgeExecutionFailure extends ScorerJudgeExecutionBase {
+  status: 'failed'
+  output?: JSONValue
+  rawOutput?: string
+  usage?: ScorerJudgeUsage
+  finishReason?: string
+  error: {
+    name: string
+    message: string
+    code?: string
+  }
+}
+
+type ScorerJudgeExecution = ScorerJudgeExecutionSuccess | ScorerJudgeExecutionFailure
 
 interface ScorerJudgeUsage {
   inputTokens?: number
@@ -119,18 +135,62 @@ const execution = result.judge?.generateScore?.executions[0]
 
 console.log(execution?.status)
 console.log(execution?.judgeModelId)
-console.log(execution?.usage.totalTokens)
+console.log(execution?.usage?.totalTokens)
 console.log(execution?.durationMs)
 ```
 
-The `status` value describes the outcome of the logical prompt-step execution, not the quality of the evaluated response. A structured-output fallback that eventually succeeds creates one `success` execution with an `attemptCount` greater than one.
+The `status` value describes the outcome of the logical prompt-step execution, not the quality of the evaluated response. A structured-output fallback that eventually succeeds creates one `success` execution with an `attemptCount` greater than one. Exhausted attempts create one `failed` execution.
+
+Successful executions require validated `output` and normalized `usage`. Failed executions require an `error` summary and include only the evidence the runtime received. A failed execution includes `output` only when the output was validated before a later callback or orchestration failure. Mastra doesn't parse `rawOutput` to create `output`.
 
 `attemptCount` counts judge invocations, including a structured-output fallback. `modelCallCount` counts the completed model steps across those attempts. `durationMs` covers the full prompt-step execution.
 
-Function steps don't create `judge` entries. Usage in this record belongs to the scorer's judge model, not the agent or workflow being evaluated. The optional `cost` field is present only when the execution directly reports an authoritative cost, source, and unit.
+Function steps don't create `judge` entries. Usage in this record belongs to the scorer's judge model, not the agent or workflow being evaluated. Filter by `status` when aggregating successful executions. Include both statuses when aggregating all completed provider usage. The optional `cost` field is present only on successful executions that directly report an authoritative cost, source, and unit.
 
 Use Mastra metrics to query aggregate usage, latency, and estimated cost across scorer runs. The `judge` record describes one scorer run and doesn't query metrics or traces.
 
+### Failed runs
+
+A failed scorer stage still rejects the `.run()` promise. Catch `ScorerRunError` to inspect completed stages and any results they produced:
+
+```typescript
+import { ScorerRunError } from '@mastra/core/evals'
+
+try {
+  const result = await scorer.run({ input, output })
+  console.log(result.score)
+} catch (error) {
+  if (error instanceof ScorerRunError) {
+    console.log(error.failedStep)
+    console.log(error.completedSteps)
+    console.log(error.result?.score)
+
+    const failedExecution = error.result?.judge?.[error.failedStep]?.executions.find(
+      execution => execution.status === 'failed',
+    )
+    console.log(failedExecution?.error)
+  }
+
+  throw error
+}
+```
+
+`ScorerRunError` exposes these properties:
+
+**failedStep** (`ScorerStepName`): The scorer stage that failed.
+
+**completedSteps** (`ScorerStepName[]`): The scorer stages that completed before the failure, in execution order.
+
+**result** (`ScorerRunResultSnapshot | undefined`): Outputs from completed scorer stages and judge execution evidence from attempted prompt stages. This property is omitted when neither is available.
+
+The `result` snapshot contains completed stage outputs and judge execution evidence. For example, if `generateReason` fails after `generateScore` returns `0`, `error.result.score` is `0`, the `generateScore` execution has `status: 'success'`, and the `generateReason` execution has `status: 'failed'`. The run remains failed.
+
+A prompt failure can create `error.result` with only run identity, input, and a failed `judge` entry. A function stage that fails before producing a scorer field doesn't create a result.
+
+`JSON.stringify(error)` uses the standard `MastraError` serialization and omits `result`, including successful and failed judge evidence. Read `result` explicitly when you need scorer artifacts or raw failed output.
+
+An in-memory experiment result can keep a completed score or reason from a failed scorer along with `error`, `failedStep`, and `completedSteps`. The scorer is still treated as failed, and a recovered score isn't written to legacy successful-score storage.
+
 ## Step execution flow
 
 When you call `.run()`, the MastraScorer executes the defined steps in this order: