@mastra/mcp-docs-server 1.2.15-alpha.15 → 1.2.15-alpha.20

package/.docs/models/providers/zenmux.md

@@ -30,14 +30,12 @@ for await (const chunk of stream) {
 }
 ```
 
-> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [ZenMux documentation](https://docs.zenmux.ai) for details.
+> **Note:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [ZenMux documentation](https://docs.zenmux.ai) for details.
 
 ## Models
 
 | Model                                         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | --------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `zenmux/anthropic/claude-3.5-haiku`           | 200K    |       |           |       |       |       | $0.80      | $4          |
-| `zenmux/anthropic/claude-3.7-sonnet`          | 200K    |       |           |       |       |       | $3         | $15         |
 | `zenmux/anthropic/claude-fable-5`             | 1.0M    |       |           |       |       |       | $10        | $50         |
 | `zenmux/anthropic/claude-haiku-4.5`           | 200K    |       |           |       |       |       | $1         | $5          |
 | `zenmux/anthropic/claude-opus-4`              | 200K    |       |           |       |       |       | $15        | $75         |
@@ -52,7 +50,6 @@ for await (const chunk of stream) {
 | `zenmux/anthropic/claude-sonnet-5`            | 1.0M    |       |           |       |       |       | $2         | $10         |
 | `zenmux/anthropic/claude-sonnet-5-free`       | 1.0M    |       |           |       |       |       | —          | —           |
 | `zenmux/baidu/ernie-5.0-thinking-preview`     | 128K    |       |           |       |       |       | $0.84      | $3          |
-| `zenmux/deepseek/deepseek-chat`               | 128K    |       |           |       |       |       | $0.28      | $0.42       |
 | `zenmux/deepseek/deepseek-v3.2`               | 128K    |       |           |       |       |       | $0.28      | $0.43       |
 | `zenmux/deepseek/deepseek-v3.2-exp`           | 163K    |       |           |       |       |       | $0.22      | $0.33       |
 | `zenmux/deepseek/deepseek-v4-flash`           | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
@@ -65,8 +62,6 @@ for await (const chunk of stream) {
 | `zenmux/google/gemini-3.1-flash-lite-preview` | 1.1M    |       |           |       |       |       | $0.25      | $2          |
 | `zenmux/google/gemini-3.1-pro-preview`        | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `zenmux/google/gemini-3.5-flash`              | 1.0M    |       |           |       |       |       | $2         | $9          |
-| `zenmux/inclusionai/ling-1t`                  | 128K    |       |           |       |       |       | $0.56      | $2          |
-| `zenmux/inclusionai/ring-1t`                  | 128K    |       |           |       |       |       | $0.56      | $2          |
 | `zenmux/inclusionai/ring-2.6-1t`              | 262K    |       |           |       |       |       | $0.30      | $3          |
 | `zenmux/kuaishou/kat-coder-pro-v2`            | 256K    |       |           |       |       |       | $0.30      | $1          |
 | `zenmux/minimax/minimax-m2`                   | 204K    |       |           |       |       |       | $0.30      | $1          |
@@ -76,9 +71,6 @@ for await (const chunk of stream) {
 | `zenmux/minimax/minimax-m2.7`                 | 205K    |       |           |       |       |       | $0.31      | $1          |
 | `zenmux/minimax/minimax-m2.7-highspeed`       | 205K    |       |           |       |       |       | $0.61      | $2          |
 | `zenmux/minimax/minimax-m3`                   | 512K    |       |           |       |       |       | $0.60      | $2          |
-| `zenmux/moonshotai/kimi-k2-0905`              | 262K    |       |           |       |       |       | $0.60      | $3          |
-| `zenmux/moonshotai/kimi-k2-thinking`          | 262K    |       |           |       |       |       | $0.60      | $3          |
-| `zenmux/moonshotai/kimi-k2-thinking-turbo`    | 262K    |       |           |       |       |       | $1         | $8          |
 | `zenmux/moonshotai/kimi-k2.5`                 | 262K    |       |           |       |       |       | $0.58      | $3          |
 | `zenmux/moonshotai/kimi-k2.6`                 | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `zenmux/moonshotai/kimi-k2.7-code`            | 262K    |       |           |       |       |       | $0.95      | $4          |
@@ -115,7 +107,6 @@ for await (const chunk of stream) {
 | `zenmux/qwen/qwen3.7-plus`                    | 1.0M    |       |           |       |       |       | $0.40      | $2          |
 | `zenmux/sapiens-ai/agnes-1.5-lite`            | 256K    |       |           |       |       |       | $0.12      | $0.60       |
 | `zenmux/sapiens-ai/agnes-1.5-pro`             | 256K    |       |           |       |       |       | $0.16      | $0.80       |
-| `zenmux/stepfun/step-3`                       | 66K     |       |           |       |       |       | $0.21      | $0.57       |
 | `zenmux/stepfun/step-3.5-flash`               | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `zenmux/stepfun/step-3.7-flash`               | 256K    |       |           |       |       |       | $0.20      | $1          |
 | `zenmux/stepfun/step-3.7-flash-free`          | 256K    |       |           |       |       |       | —          | —           |
@@ -125,17 +116,11 @@ for await (const chunk of stream) {
 | `zenmux/volcengine/doubao-seed-2.0-lite`      | 256K    |       |           |       |       |       | $0.09      | $0.51       |
 | `zenmux/volcengine/doubao-seed-2.0-mini`      | 256K    |       |           |       |       |       | $0.03      | $0.28       |
 | `zenmux/volcengine/doubao-seed-2.0-pro`       | 256K    |       |           |       |       |       | $0.45      | $2          |
-| `zenmux/volcengine/doubao-seed-code`          | 256K    |       |           |       |       |       | $0.17      | $1          |
-| `zenmux/x-ai/grok-4`                          | 256K    |       |           |       |       |       | $3         | $15         |
-| `zenmux/x-ai/grok-4-fast`                     | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
-| `zenmux/x-ai/grok-4.1-fast`                   | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
-| `zenmux/x-ai/grok-4.1-fast-non-reasoning`     | 2.0M    |       |           |       |       |       | $0.20      | $0.50       |
 | `zenmux/x-ai/grok-4.2-fast`                   | 2.0M    |       |           |       |       |       | $3         | $9          |
 | `zenmux/x-ai/grok-4.2-fast-non-reasoning`     | 2.0M    |       |           |       |       |       | $3         | $9          |
 | `zenmux/x-ai/grok-4.3`                        | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `zenmux/x-ai/grok-4.5`                        | 500K    |       |           |       |       |       | $2         | $6          |
 | `zenmux/x-ai/grok-build-0.1`                  | 256K    |       |           |       |       |       | $1         | $2          |
-| `zenmux/x-ai/grok-code-fast-1`                | 256K    |       |           |       |       |       | $0.20      | $2          |
 | `zenmux/xiaomi/mimo-v2-flash`                 | 262K    |       |           |       |       |       | $0.10      | $0.30       |
 | `zenmux/xiaomi/mimo-v2-omni`                  | 265K    |       |           |       |       |       | $0.40      | $2          |
 | `zenmux/xiaomi/mimo-v2-pro`                   | 1.0M    |       |           |       |       |       | $1         | $3          |

package/.docs/models/providers/zhipuai-coding-plan.md

@@ -30,7 +30,7 @@ for await (const chunk of stream) {
 }
 ```
 
-> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Zhipu AI Coding Plan documentation](https://docs.bigmodel.cn/cn/coding-plan/overview) for details.
+> **Note:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Zhipu AI Coding Plan documentation](https://docs.bigmodel.cn/cn/coding-plan/overview) for details.
 
 ## Models
 

package/.docs/models/providers/zhipuai.md

@@ -30,7 +30,7 @@ for await (const chunk of stream) {
 }
 ```
 
-> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Zhipu AI documentation](https://docs.z.ai/guides/overview/pricing) for details.
+> **Note:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Zhipu AI documentation](https://docs.z.ai/guides/overview/pricing) for details.
 
 ## Models
 

package/.docs/models/providers.md

@@ -39,6 +39,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [ClinePass](https://mastra.ai/models/providers/cline-pass)
 - [CloudFerro Sherlock](https://mastra.ai/models/providers/cloudferro-sherlock)
 - [Cloudflare Workers AI](https://mastra.ai/models/providers/cloudflare-workers-ai)
+- [CoralBricks](https://mastra.ai/models/providers/coralbricks)
 - [Cortecs](https://mastra.ai/models/providers/cortecs)
 - [CrofAI](https://mastra.ai/models/providers/crof)
 - [CrossModel](https://mastra.ai/models/providers/crossmodel)

package/.docs/reference/agent-controller/agent-controller-class.md

@@ -2,7 +2,7 @@
 
 # AgentController
 
-> **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 The `AgentController` class is a shared host for one or more [`Session`](https://mastra.ai/reference/agent-controller/session) instances. Initialize the controller, create a session, then use `session.*` APIs for conversation state and run control.
 
@@ -280,7 +280,7 @@ Returns: `boolean`
 
 #### `getWorkspace()`
 
-Return a static controller workspace. Dynamic workspace factories return `undefined` until resolved.
+Return a static controller workspace. Dynamic workspace factories resolve per session and return `undefined` here, so use `resolveWorkspace` instead.
 
 ```typescript
 const workspace = controller.getWorkspace()
@@ -290,7 +290,7 @@ Returns: `Workspace | undefined`
 
 #### `resolveWorkspace({ session, requestContext? })`
 
-Resolve a dynamic workspace for a session and cache the result on the controller.
+Return the workspace a session runs against. Sessions resolve theirs at creation, dynamic factories included, so this returns that instance and only falls back to the factory for a session created without one.
 
 ```typescript
 const workspace = await controller.resolveWorkspace({ session, requestContext })

package/.docs/reference/agent-controller/session.md

@@ -2,7 +2,7 @@
 
 # Session
 
-> **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A `Session` is the isolated runtime for one resource and optional scope. It owns its event bus, thread binding, state, mode and model selections, run control, approvals, suspensions, follow-ups, and display state. The [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) supplies shared agents, configuration, storage, workspaces, and services.
 

package/.docs/reference/agents/durable-agent.md

@@ -2,6 +2,8 @@
 
 # DurableAgent
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `DurableAgent` wraps an existing [`Agent`](https://mastra.ai/reference/agents/agent) with durable execution and resumable streams. It runs the agentic loop so that a client can disconnect and reconnect without missing events, and it streams those events over [PubSub](https://mastra.ai/docs/server/pubsub). Use it when a run must outlive a single request or survive a dropped connection.
 
 Create one with the [`createDurableAgent`](#createdurableagentoptions) factory, or use [`createEventedAgent`](#createeventedagentoptions) for fire-and-forget execution on the built-in workflow engine. For Inngest-powered execution, use [`createInngestAgent`](https://mastra.ai/reference/agents/inngest-agent) from `@mastra/inngest`.

package/.docs/reference/agents/generateLegacy.md

@@ -138,7 +138,7 @@ Scorer judges with legacy model adapters call `generateLegacy()`. They don't rec
 
 ## Migration to new API
 
-> **Info:** The new `.generate()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved streaming support. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for detailed migration instructions.
+> **Note:** The new `.generate()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved streaming support. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for detailed migration instructions.
 
 ### Quick Migration Example
 

package/.docs/reference/agents/inngest-agent.md

@@ -2,6 +2,8 @@
 
 # `createInngestAgent()`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `createInngestAgent()` wraps an existing [`Agent`](https://mastra.ai/reference/agents/agent) with [Inngest](https://www.inngest.com/docs)-powered durable execution. Like [`createDurableAgent()`](https://mastra.ai/reference/agents/durable-agent), it streams events over [PubSub](https://mastra.ai/docs/server/pubsub) and supports resumable streams, but runs the agentic loop on Inngest's execution engine instead of in-process. Use it when a run must survive process restarts or run in a distributed environment.
 
 For in-process durable execution, use [`createDurableAgent()`](https://mastra.ai/reference/agents/durable-agent). For fire-and-forget execution on the built-in workflow engine, use [`createEventedAgent()`](https://mastra.ai/reference/agents/durable-agent).

package/.docs/reference/auth/okta.md

@@ -38,6 +38,8 @@ export const mastra = new Mastra({
 
 **redirectUri** (`string`): The OAuth redirect URI for the SSO callback. Must match the redirect URI configured in your Okta application. (Default: `process.env.OKTA_REDIRECT_URI`)
 
+**audience** (`string | string[]`): Expected aud claim for Bearer tokens. Defaults to the client ID, which matches Okta ID tokens. Set it to the authorization server's audience to accept access tokens, or pass an array to accept several. Does not affect the ID token verified during the SSO login flow, which always uses the client ID. (Default: `process.env.OKTA_AUDIENCE ?? clientId`)
+
 **scopes** (`string[]`): OAuth scopes to request during the login flow. (Default: `['openid', 'profile', 'email', 'groups']`)
 
 **apiToken** (`string`): Okta API token for user lookups via the Users API. Required for getUser() to return user data by ID. (Default: `process.env.OKTA_API_TOKEN`)
@@ -66,6 +68,8 @@ The following environment variables are automatically used when constructor opti
 
 **OKTA\_ISSUER** (`string`): Token issuer URL. Defaults to https\://{domain}/oauth2/default if not set.
 
+**OKTA\_AUDIENCE** (`string`): Expected aud claim for Bearer tokens. Defaults to the client ID if not set.
+
 **OKTA\_REDIRECT\_URI** (`string`): OAuth redirect URI for the SSO callback.
 
 **OKTA\_COOKIE\_PASSWORD** (`string`): Password for encrypting session cookies. Must be at least 32 characters.
@@ -77,7 +81,7 @@ The following environment variables are automatically used when constructor opti
 `MastraAuthOkta` authenticates requests in the following order:
 
 1. **Session cookie**: Reads the encrypted session cookie and decrypts it. If the session is valid and not expired, the user is authenticated.
-2. **JWT fallback**: If no session cookie is present, verifies the `Authorization` header token against Okta's JWKS endpoint.
+2. **JWT fallback**: If no session cookie is present, verifies the `Authorization` header token against Okta's JWKS endpoint. The token's `iss` claim is checked against `issuer` and its `aud` claim against `audience`.
 
 After authentication, `authorizeUser` checks that the user has a valid `oktaId`. Provide a custom `authorizeUser` function to implement additional logic.
 

package/.docs/reference/cli/mastra.md

@@ -153,7 +153,7 @@ MASTRA_CONCURRENCY=2 mastra build
 
 ## `mastra start`
 
-> **Info:** You need to run `mastra build` before using `mastra start`.
+> **Note:** You need to run `mastra build` before using `mastra start`.
 
 Starts a local server to serve your built Mastra application in production mode. By default, [OTEL Tracing](https://mastra.ai/docs/observability/tracing/overview) is enabled.
 
@@ -266,7 +266,7 @@ Enable debug logging during the build.
 
 ## `mastra worker start`
 
-> **Info:** You need to run `mastra worker build` or `mastra build` before using `mastra worker start`.
+> **Note:** You need to run `mastra worker build` or `mastra build` before using `mastra worker start`.
 
 Starts a worker process from a previously built bundle. The optional `name` argument sets `MASTRA_WORKERS` in the spawned process, controlling which worker starts.
 
@@ -609,7 +609,7 @@ Emit machine-readable JSON.
 
 ## `mastra studio deploy`
 
-> **Info:** `mastra studio deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which supports environments (`--env staging`, `--env production`) on a single project. New setups should use `mastra deploy`.
+> **Note:** `mastra studio deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which supports environments (`--env staging`, `--env production`) on a single project. New setups should use `mastra deploy`.
 
 Builds and deploys your project to Mastra platform. Requires authentication via [`mastra auth login`](#mastra-auth-login) or a `MASTRA_API_TOKEN` environment variable.
 
@@ -727,7 +727,7 @@ Creates a new project through an interactive prompt. This command doesn't accept
 
 ## `mastra server deploy`
 
-> **Info:** `mastra server deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which deploys a single project to multiple environments instead of separate Studio and Server commands. New setups should use `mastra deploy`.
+> **Note:** `mastra server deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which deploys a single project to multiple environments instead of separate Studio and Server commands. New setups should use `mastra deploy`.
 
 Builds and deploys your project to Server on Mastra platform. Works the same as [`mastra studio deploy`](#mastra-studio-deploy) with the same flags, arguments, and resolution logic.
 

package/.docs/reference/client-js/workflows.md

@@ -14,7 +14,7 @@ const workflows = await mastraClient.listWorkflows()
 
 ## Getting workflow run counts
 
-Retrieve per-workflow counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs in a single request. The counts are computed on the server and keyed by the workflow's registry key — the key used when registering the workflow in the Mastra config, which can differ from the workflow's own `id`:
+Retrieve per-workflow counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs in a single request. The counts are computed on the server and keyed by the workflow's registry key, the key used when registering the workflow in the Mastra config, which can differ from the workflow's own `id`:
 
 ```typescript
 const runCounts = await mastraClient.listWorkflowRunCounts()
@@ -23,7 +23,7 @@ const runCounts = await mastraClient.listWorkflowRunCounts()
 
 Returns: `Record<string, { running: number; suspended: number }>`
 
-The server may cache the counts for a few seconds between requests. Servers that predate this endpoint respond with `404 Not Found` — handle the error when the client can talk to older deployments.
+The server may cache the counts for a few seconds between requests. Servers that predate this endpoint respond with `404 Not Found`. Handle the error when the client can talk to older deployments.
 
 ## Working with a specific workflow
 
@@ -227,7 +227,7 @@ A workflow run result yields the following:
 
 ## Dynamic workflows
 
-> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Dynamic workflows are workflow definitions expressed as JSON. The server persists each definition and registers it as a runnable workflow. See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) for the definition format.
 

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -2,7 +2,7 @@
 
 # mountAgentControllerOnMastra()
 
-> **Beta:** The `@mastra/code-sdk` package is experimental and subject to breaking changes in minor versions.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller (the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management) and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
 

package/.docs/reference/core/addDynamicWorkflow.md

@@ -2,7 +2,7 @@
 
 # Mastra.addDynamicWorkflow()
 
-> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 The `.addDynamicWorkflow()` method validates a dynamic workflow definition and registers it as a live workflow on the instance, persisting it through the `workflowDefinitions` storage domain. Once registered, the workflow runs like any other workflow via [`getWorkflow()`](https://mastra.ai/reference/core/getWorkflow).
 

package/.docs/reference/core/addDynamicWorkflows.md

@@ -2,7 +2,7 @@
 
 # Mastra.addDynamicWorkflows()
 
-> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 The `.addDynamicWorkflows()` method adds a bundle of dynamic workflow definitions that may reference each other. The typical case is a root workflow plus helper workflows it nests, where none of the definitions exist yet.
 

package/.docs/reference/file-based-agents/config.md

@@ -2,6 +2,8 @@
 
 # config.ts
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 An agent's `config.ts` sets its model and runtime options. Use it for options that belong to the [`Agent`](https://mastra.ai/reference/agents/agent) itself, while sibling files provide instructions, tools, skills, et cetera.
 
 ## What belongs in `config.ts`

package/.docs/reference/file-based-agents/instructions.md

@@ -2,6 +2,8 @@
 
 # Instructions
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 An agent's instructions hold its always-on system prompt: the model reads it on every turn. Use them to define the agent's identity, tone, role, and standing rules.
 
 Write them in one of two files at the agent root. Use `instructions.md` when the prompt is fixed text. Use `instructions.ts` when the prompt needs code, for example when it's built from shared constants or resolved per request.

package/.docs/reference/file-based-agents/logger.md

@@ -2,6 +2,8 @@
 
 # Logger
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra sets the project's [logger](https://mastra.ai/docs/observability/logging) from a `logger.ts` file directly under `src/mastra/`. The file default-exports a logger, which replaces the built-in `ConsoleLogger` used across agents, workflows, and other components.
 
 Use this page for the file-based convention. For log levels, transports, and provider details, see [logging](https://mastra.ai/docs/observability/logging).

package/.docs/reference/file-based-agents/memory.md

@@ -2,6 +2,8 @@
 
 # Memory
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent gets [memory](https://mastra.ai/docs/memory/overview) from a `memory.ts` file that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance. Use this page for the file-based convention; use the memory docs for message history, semantic recall, storage, and processors.
 
 Without `memory.ts` or `config.memory`, the agent has no memory by default. Each `generate()` or `stream()` call starts without remembered conversation state unless you pass the prior context yourself.

package/.docs/reference/file-based-agents/observability.md

@@ -2,6 +2,8 @@
 
 # Observability
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra configures [observability](https://mastra.ai/docs/observability/overview) from an `observability.ts` file directly under `src/mastra/`. The file default-exports an `Observability` instance that sets up tracing, logging, metrics, and feedback for the project.
 
 Use this page for the file-based convention. For the signal model, exporters, storage, and multi-config setup, see the [observability overview](https://mastra.ai/docs/observability/overview) and [observability configuration](https://mastra.ai/docs/observability/overview).

package/.docs/reference/file-based-agents/processors.md

@@ -2,6 +2,8 @@
 
 # Processors
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent discovers [processors](https://mastra.ai/docs/agents/processors) from its `processors/` directory. Use this page for the file-based convention; use the processors guide for built-in processors, custom processors, streaming behavior, and advanced patterns.
 
 Files under `processors/input/` run before messages reach the model. Files under `processors/output/` run after the model responds. Each file default-exports one [`Processor`](https://mastra.ai/reference/processors/processor-interface), and the filename becomes its discovery key.

package/.docs/reference/file-based-agents/schedules.md

@@ -2,6 +2,8 @@
 
 # Schedules
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent discovers **schedules** from its `schedules/` directory. Each file declares one recurring task: a cron expression plus what the agent should do when it fires. Mastra registers them into schedule storage at startup, so a scheduled agent needs no runtime registration code.
 
 Use this page for the file-based convention. To create schedules at runtime instead, see [Schedules](https://mastra.ai/reference/schedules/overview).

package/.docs/reference/file-based-agents/scorers.md

@@ -2,6 +2,8 @@
 
 # Scorers
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent discovers [scorers](https://mastra.ai/docs/evals/overview) from its `scorers/` directory. Use this page for the file-based convention; use the scorers guide for built-in scorers, custom scorers, and sampling.
 
 Each file under `scorers/` default-exports one scorer, and the filename becomes its key. The default export is either a [`MastraScorer`](https://mastra.ai/reference/evals/create-scorer) or a `{ scorer, sampling }` entry.

package/.docs/reference/file-based-agents/server.md

@@ -2,6 +2,8 @@
 
 # Server
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra configures its HTTP [server](https://mastra.ai/docs/server/mastra-server) from a `server.ts` file directly under `src/mastra/`. The server exposes agents, workflows, and other registered primitives as REST endpoints, and the file default-exports the same `ServerConfig` shape you'd pass to [`new Mastra()`](https://mastra.ai/reference/core/mastra-class).
 
 Use this page for the file-based convention. For server features, middleware, custom routes, generated API docs, and deployment behavior, see [Server overview](https://mastra.ai/docs/server/mastra-server).

package/.docs/reference/file-based-agents/skills.md

@@ -2,6 +2,8 @@
 
 # Skills
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent discovers skills from its `skills/` directory and bundles them at build time. Skills are reusable procedures or reference material that the agent can load when relevant, instead of putting every detail into the always-on prompt.
 
 Use this page for the file-based convention. For code-defined skills, see [Agent skills](https://mastra.ai/docs/agents/skills). For the `SKILL.md` package format, see [Workspace skills](https://mastra.ai/docs/workspace/skills).

package/.docs/reference/file-based-agents/storage.md

@@ -2,6 +2,8 @@
 
 # Storage
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra sets the project's default [storage](https://mastra.ai/docs/storage/overview) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
 
 Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage/overview).

package/.docs/reference/file-based-agents/studio.md

@@ -2,6 +2,8 @@
 
 # Studio
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra configures [Studio](https://mastra.ai/docs/studio/overview) from a `studio.ts` file directly under `src/mastra/`. The file default-exports a `StudioConfig` object for Studio authentication and authorization: who can access Studio, and what authenticated users can do.
 
 Use this page for the file-based convention. For auth providers, role-based access control (RBAC), and fine-grained authorization (FGA), see [Studio auth](https://mastra.ai/docs/studio/auth).

package/.docs/reference/file-based-agents/subagents.md

@@ -2,6 +2,8 @@
 
 # Subagents
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory and calls that tool to hand off a task. The subagent's result returns to the parent conversation.
 
 Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/capabilities/subagents).

package/.docs/reference/file-based-agents/tools.md

@@ -2,6 +2,8 @@
 
 # Tools
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A file-based agent discovers tools from `.ts` and `.js` files directly under its `tools/` directory. Each discovered file is imported at build time, the file must default-export a [`createTool()`](https://mastra.ai/reference/tools/create-tool) result, and the filename without its extension becomes the tool key the model can call.
 
 Use this page for the file-based convention. For tool schemas, execution options, output shaping, and approval options, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool).

package/.docs/reference/file-based-agents/workflows.md

@@ -2,6 +2,8 @@
 
 # Workflows
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Mastra discovers project-level workflows from `.ts` and `.js` files under `src/mastra/workflows/`. This convention isn't scoped to one agent: every file with a default export becomes a registered workflow, and the filename becomes the workflow key.
 
 Use this page for the file-based convention. For steps, schemas, control flow, streaming, state, and workflow execution, see [Workflows overview](https://mastra.ai/docs/workflows/overview).

package/.docs/reference/file-based-agents/workspace.md

@@ -2,6 +2,8 @@
 
 # Workspace
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 A [workspace](https://mastra.ai/docs/workspace/overview) gives an agent filesystem access and command execution. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`, so they can read and write files and run shell commands without extra configuration.
 
 Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Workspaces](https://mastra.ai/docs/workspace/overview).

package/.docs/reference/index.md

@@ -313,6 +313,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [MCPClient](https://mastra.ai/reference/tools/mcp-client)
 - [MCPServer](https://mastra.ai/reference/tools/mcp-server)
 - [Perplexity Tools](https://mastra.ai/reference/tools/perplexity)
+- [QuickJsCodeModeTransport](https://mastra.ai/reference/tools/quickjs-transport)
 - [submitPlanTool](https://mastra.ai/reference/tools/submit-plan-tool)
 - [Task tools](https://mastra.ai/reference/tools/task-tools)
 - [Tavily Tools](https://mastra.ai/reference/tools/tavily)

package/.docs/reference/observability/tracing/exporters/datadog.md

@@ -4,7 +4,7 @@
 
 Sends Tracing data to Datadog's LLM Observability product for monitoring and analytics.
 
-> **Info:** If you also use `dd-trace` APM auto-instrumentation and need it correctly parented under Mastra spans, use the [DatadogBridge](https://mastra.ai/reference/observability/tracing/bridges/datadog) instead. The exporter sends LLM Observability data after execution completes, so it doesn't participate in `dd-trace`'s live scope.
+> **Note:** If you also use `dd-trace` APM auto-instrumentation and need it correctly parented under Mastra spans, use the [DatadogBridge](https://mastra.ai/reference/observability/tracing/bridges/datadog) instead. The exporter sends LLM Observability data after execution completes, so it doesn't participate in `dd-trace`'s live scope.
 
 ## Constructor
 

package/.docs/reference/processors/pii-detector.md

@@ -42,6 +42,8 @@ const processor = new PIIDetector({
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })
 
+**options.onDetection** (`(event: PIIDetectionEvent) => void | Promise<void>`): Called whenever a detection result is produced, with detectionResult, the analyzed input, whether it was flagged, and the strategyApplied (the configured strategy when flagged, otherwise none). Fires for every analyzed message in processInput and processOutputResult, and for every LLM buffer flush during streaming; the streaming regex pass only reports when PII is found. Errors thrown by the callback are logged and ignored
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'pii-detector'

package/.docs/reference/processors/prompt-injection-detector.md

@@ -38,6 +38,8 @@ const processor = new PromptInjectionDetector({
 
 **options.providerOptions** (`ProviderOptions`): Provider-specific options passed to the internal detection agent. Use this to control model behavior like reasoning effort for thinking models (e.g., { openai: { reasoningEffort: 'low' } })
 
+**options.onDetection** (`(event: PromptInjectionDetectionEvent) => void | Promise<void>`): Called for every analyzed message with detectionResult, the analyzed input, whether it was flagged, and the strategyApplied (the configured strategy when flagged, otherwise none). Use it to emit custom metrics. Errors thrown by the callback are logged and ignored
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'prompt-injection-detector'

package/.docs/reference/processors/response-cache.md

@@ -2,6 +2,8 @@
 
 # ResponseCache
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` for cache lookup and short-circuits on a hit. It uses `processLLMResponse` to write the completed response.
 
 The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model (i.e. _after_ memory has loaded and earlier input processors have transformed the prompt) so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.

package/.docs/reference/schedules/overview.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.50.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `mastra.schedules` is the CRUD service for persisted cron schedules. Use it to create, list, update, pause, resume, manually run, and delete schedules for agents or workflows.
 
 For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules).

package/.docs/reference/server/create-route.md

@@ -72,10 +72,36 @@ handler: async params => {
 
 ## Return value
 
-Returns a `ServerRoute` object that can be registered with an adapter.
+Returns a `ServerRoute` object that can be registered with an adapter or passed to `server.apiRoutes` on the `Mastra` instance.
 
 ## Examples
 
+### Register through `server.apiRoutes`
+
+Routes created with `createRoute()` can be passed to `server.apiRoutes`. The adapter registers them with runtime validation, typed handler parameters, and generated OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { createRoute } from '@mastra/server/server-adapter'
+import { z } from 'zod'
+
+const createItemRoute = createRoute({
+  method: 'POST',
+  path: '/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string(),
+  }),
+  handler: async ({ name }) => ({ id: 'new-id', name }),
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [createItemRoute],
+  },
+})
+```
+
 ### GET route with path params
 
 ```typescript

package/.docs/reference/signals/create-notification-inbox-tool.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `createNotificationInboxTool()` creates a Mastra tool that lets an agent inspect and manage notification inbox records for the current thread.
 
 Use this tool with durable notification signals. For sending notification records, see [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent).

package/.docs/reference/signals/signal-provider.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Abstract base class for building signal providers. A signal provider monitors external sources (APIs, webhooks, event streams) and pushes notification signals into agent threads through a built-in subscription registry.
 
 Signal providers aren't processors by default. Providers that need to intercept agent execution return processors from `getInputProcessors()` or `getOutputProcessors()`. Providers that expose agent-callable tools return them from `getTools()`.

package/.docs/reference/signals/task-signal-provider.md

@@ -2,6 +2,8 @@
 
 # TaskSignalProvider
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Bundles the built-in task tools (`task_write`, `task_update`, `task_complete`, `task_check`) and the `TaskStateProcessor` behind a single agent registration. Use it to add a structured, durable task list to an agent without wiring the tools and processor separately.
 
 Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider). The task list is stored in the thread-scoped `tasks` storage domain (the source of truth) and projected onto the agent state-signal lane by the processor, so it survives observational-memory truncation without invalidating the prompt cache.

package/.docs/reference/signals/webhook-signal-provider.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Concrete signal provider for push-based event delivery. Routes incoming webhook payloads to subscribed agent threads by matching the payload against a configurable resource ID extractor.
 
 Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider) with public subscription management and a built-in `handleWebhook()` implementation.