@mastra/mcp-docs-server 1.2.16 → 1.2.17-alpha.3

package/.docs/models/providers/merge-gateway.md

@@ -2,7 +2,7 @@
 
 # ![Merge Gateway logo](https://models.dev/logos/merge-gateway.svg)Merge Gateway
 
-Access 166 Merge Gateway models through Mastra's model router. Authentication is handled automatically using the `MERGE_GATEWAY_API_KEY` environment variable.
+Access 169 Merge Gateway models through Mastra's model router. Authentication is handled automatically using the `MERGE_GATEWAY_API_KEY` environment variable.
 
 Learn more in the [Merge Gateway documentation](https://docs.merge.dev/merge-gateway).
 
@@ -83,11 +83,13 @@ for await (const chunk of stream) {
 | `merge-gateway/google/gemini-3.5-flash`                        | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `merge-gateway/google/gemini-3.5-flash-lite`                   | 1.0M    |       |           |       |       |       | $0.30      | $3          |
 | `merge-gateway/google/gemini-3.6-flash`                        | 1.0M    |       |           |       |       |       | $2         | $8          |
+| `merge-gateway/google/gemini-3.7-flash`                        | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `merge-gateway/google/gemini-embedding-001`                    | 2K      |       |           |       |       |       | $0.15      | —           |
 | `merge-gateway/google/gemini-flash-latest`                     | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `merge-gateway/google/gemini-flash-lite-latest`                | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `merge-gateway/google/gemma-4-26b-a4b-it`                      | 262K    |       |           |       |       |       | $0.13      | $0.40       |
 | `merge-gateway/google/gemma-4-31b-it`                          | 262K    |       |           |       |       |       | $0.14      | $0.40       |
+| `merge-gateway/meta/llama-3.1-8b-instruct`                     | 128K    |       |           |       |       |       | $0.22      | $0.22       |
 | `merge-gateway/meta/llama-3.3-70b-instruct`                    | 131K    |       |           |       |       |       | $0.22      | $0.50       |
 | `merge-gateway/meta/muse-spark-1.1`                            | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `merge-gateway/meta/muse-spark-1.2`                            | 1.0M    |       |           |       |       |       | $1         | $4          |
@@ -153,6 +155,7 @@ for await (const chunk of stream) {
 | `merge-gateway/qwen/qwen-plus`                                 | 1.0M    |       |           |       |       |       | $0.12      | $0.29       |
 | `merge-gateway/qwen/qwen3-235b-a22b`                           | 131K    |       |           |       |       |       | $0.29      | $1          |
 | `merge-gateway/qwen/qwen3-235b-a22b-instruct-2507`             | 131K    |       |           |       |       |       | $0.10      | $0.60       |
+| `merge-gateway/qwen/qwen3-30b-a3b`                             | 131K    |       |           |       |       |       | $0.11      | $1          |
 | `merge-gateway/qwen/qwen3-32b`                                 | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `merge-gateway/qwen/qwen3-coder-480b-a35b-instruct`            | 131K    |       |           |       |       |       | $0.22      | $2          |
 | `merge-gateway/qwen/qwen3-coder-flash`                         | 1.0M    |       |           |       |       |       | $0.14      | $0.57       |
@@ -165,7 +168,7 @@ for await (const chunk of stream) {
 | `merge-gateway/qwen/qwen3.5-122b-a10b`                         | 256K    |       |           |       |       |       | $0.12      | $0.92       |
 | `merge-gateway/qwen/qwen3.5-27b`                               | 256K    |       |           |       |       |       | $0.09      | $0.69       |
 | `merge-gateway/qwen/qwen3.5-35b-a3b`                           | 256K    |       |           |       |       |       | $0.06      | $0.46       |
-| `merge-gateway/qwen/qwen3.5-397b-a17b`                         | 256K    |       |           |       |       |       | $0.17      | $1          |
+| `merge-gateway/qwen/qwen3.5-397b-a17b`                         | 131K    |       |           |       |       |       | $0.17      | $1          |
 | `merge-gateway/qwen/qwen3.5-9b`                                | 262K    |       |           |       |       |       | $0.09      | $0.13       |
 | `merge-gateway/qwen/qwen3.5-flash`                             | 1.0M    |       |           |       |       |       | $0.03      | $0.29       |
 | `merge-gateway/qwen/qwen3.5-plus`                              | 1.0M    |       |           |       |       |       | $0.12      | $0.69       |

package/.docs/models/providers/nano-gpt.md

@@ -38,7 +38,6 @@ for await (const chunk of stream) {
 | ---------------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `nano-gpt/abacusai/Dracarys-72B-Instruct`                        | 16K     |       |           |       |       |       | $0.49      | $0.49       |
 | `nano-gpt/aion-labs/aion-2.0`                                    | 131K    |       |           |       |       |       | $0.80      | $2          |
-| `nano-gpt/aion-labs/aion-2.5`                                    | 131K    |       |           |       |       |       | $1         | $3          |
 | `nano-gpt/aion-labs/aion-3.0`                                    | 131K    |       |           |       |       |       | $3         | $6          |
 | `nano-gpt/aion-labs/aion-3.0-mini`                               | 131K    |       |           |       |       |       | $0.70      | $1          |
 | `nano-gpt/aion-labs/aion-rp-llama-3.1-8b`                        | 33K     |       |           |       |       |       | $0.80      | $2          |
@@ -145,7 +144,7 @@ for await (const chunk of stream) {
 | `nano-gpt/deepseek-reasoner`                                     | 64K     |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/deepseek-reasoner-cheaper`                             | 128K    |       |           |       |       |       | $0.40      | $2          |
 | `nano-gpt/deepseek-v3-0324`                                      | 128K    |       |           |       |       |       | $0.20      | $0.77       |
-| `nano-gpt/deepseek/deepseek-latest`                              | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
+| `nano-gpt/deepseek/deepseek-latest`                              | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `nano-gpt/deepseek/deepseek-prover-v2-671b`                      | 160K    |       |           |       |       |       | $1         | $3          |
 | `nano-gpt/deepseek/deepseek-v3.2`                                | 163K    |       |           |       |       |       | $0.28      | $0.42       |
 | `nano-gpt/deepseek/deepseek-v3.2:thinking`                       | 163K    |       |           |       |       |       | $0.28      | $0.42       |
@@ -157,8 +156,8 @@ for await (const chunk of stream) {
 | `nano-gpt/deepseek/deepseek-v4-flash-latest`                     | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `nano-gpt/deepseek/deepseek-v4-flash:thinking`                   | 1.0M    |       |           |       |       |       | $0.07      | $0.14       |
 | `nano-gpt/deepseek/deepseek-v4-pro`                              | 1.0M    |       |           |       |       |       | $1         | $2          |
-| `nano-gpt/deepseek/deepseek-v4-pro-0813`                         | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
-| `nano-gpt/deepseek/deepseek-v4-pro-0813:thinking`                | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
+| `nano-gpt/deepseek/deepseek-v4-pro-0813`                         | 1.0M    |       |           |       |       |       | $1         | $4          |
+| `nano-gpt/deepseek/deepseek-v4-pro-0813:thinking`                | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `nano-gpt/deepseek/deepseek-v4-pro-cheaper`                      | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `nano-gpt/deepseek/deepseek-v4-pro-cheaper:thinking`             | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `nano-gpt/deepseek/deepseek-v4-pro:thinking`                     | 1.0M    |       |           |       |       |       | $1         | $2          |
@@ -242,8 +241,9 @@ for await (const chunk of stream) {
 | `nano-gpt/google/gemini-3.5-flash`                               | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `nano-gpt/google/gemini-3.5-flash-lite`                          | 1.0M    |       |           |       |       |       | $0.30      | $3          |
 | `nano-gpt/google/gemini-3.5-flash-thinking`                      | 1.0M    |       |           |       |       |       | $2         | $9          |
-| `nano-gpt/google/gemini-3.6-flash`                               | 1.0M    |       |           |       |       |       | $2         | $8          |
-| `nano-gpt/google/gemini-flash-latest`                            | 1.0M    |       |           |       |       |       | $2         | $8          |
+| `nano-gpt/google/gemini-3.6-flash`                               | 1.0M    |       |           |       |       |       | $0.75      | $4          |
+| `nano-gpt/google/gemini-3.7-flash`                               | 1.0M    |       |           |       |       |       | $0.38      | $2          |
+| `nano-gpt/google/gemini-flash-latest`                            | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `nano-gpt/google/gemini-flash-lite-latest`                       | 1.0M    |       |           |       |       |       | $0.30      | $3          |
 | `nano-gpt/google/gemini-pro-latest`                              | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `nano-gpt/google/gemma-4-26b-a4b-it`                             | 262K    |       |           |       |       |       | $0.13      | $0.40       |

package/.docs/models/providers/ofox.md

@@ -2,7 +2,7 @@
 
 # ![Ofox logo](https://models.dev/logos/ofox.svg)Ofox
 
-Access 72 Ofox models through Mastra's model router. Authentication is handled automatically using the `OFOX_API_KEY` environment variable.
+Access 76 Ofox models through Mastra's model router. Authentication is handled automatically using the `OFOX_API_KEY` environment variable.
 
 Learn more in the [Ofox documentation](https://ofox.ai/docs).
 
@@ -75,9 +75,12 @@ for await (const chunk of stream) {
 | `ofox/google/gemini-3.1-flash-lite`        | 1.0M    |       |           |       |       |       | $0.25      | $2          |
 | `ofox/google/gemini-3.1-pro-preview`       | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `ofox/google/gemini-3.5-flash`             | 1.0M    |       |           |       |       |       | $2         | $9          |
+| `ofox/google/gemini-3.5-flash-lite`        | 1.0M    |       |           |       |       |       | $0.30      | $3          |
 | `ofox/google/gemini-3.6-flash`             | 1.0M    |       |           |       |       |       | $2         | $8          |
+| `ofox/minimax/minimax-m2.7`                | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `ofox/moonshotai/kimi-k2.5`                | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `ofox/moonshotai/kimi-k2.6`                | 262K    |       |           |       |       |       | $0.95      | $4          |
+| `ofox/moonshotai/kimi-k2.7-code`           | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `ofox/moonshotai/kimi-k2.7-code-highspeed` | 262K    |       |           |       |       |       | $2         | $8          |
 | `ofox/moonshotai/kimi-k3`                  | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `ofox/openai/gpt-4.1`                      | 1.0M    |       |           |       |       |       | $2         | $8          |
@@ -93,6 +96,7 @@ for await (const chunk of stream) {
 | `ofox/openai/gpt-5.2-codex`                | 400K    |       |           |       |       |       | $2         | $14         |
 | `ofox/openai/gpt-5.4-mini`                 | 400K    |       |           |       |       |       | $0.75      | $5          |
 | `ofox/openai/gpt-5.4-nano`                 | 400K    |       |           |       |       |       | $0.20      | $1          |
+| `ofox/openai/gpt-5.4-pro`                  | 1.1M    |       |           |       |       |       | $30        | $180        |
 | `ofox/openai/gpt-5.5`                      | 1.1M    |       |           |       |       |       | $5         | $30         |
 | `ofox/openai/gpt-5.6-luna`                 | 1.1M    |       |           |       |       |       | $0.20      | $1          |
 | `ofox/openai/gpt-5.6-sol`                  | 1.1M    |       |           |       |       |       | $5         | $30         |

package/.docs/models/providers/opencode-go.md

@@ -2,7 +2,7 @@
 
 # ![OpenCode Go logo](https://models.dev/logos/opencode-go.svg)OpenCode Go
 
-Access 24 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 25 OpenCode Go models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Go documentation](https://opencode.ai/docs/zen).
 
@@ -40,6 +40,7 @@ for await (const chunk of stream) {
 | `opencode-go/deepseek-v4-pro`   | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `opencode-go/glm-5.1`           | 203K    |       |           |       |       |       | $1         | $4          |
 | `opencode-go/glm-5.2`           | 1.0M    |       |           |       |       |       | $1         | $4          |
+| `opencode-go/glm-5.3`           | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `opencode-go/gpt-5.6-luna`      | 1.1M    |       |           |       |       |       | $0.10      | $0.60       |
 | `opencode-go/grok-4.5`          | 500K    |       |           |       |       |       | $2         | $6          |
 | `opencode-go/hy3`               | 256K    |       |           |       |       |       | $0.14      | $0.58       |

package/.docs/models/providers/opencode.md

@@ -2,7 +2,7 @@
 
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 89 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 91 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Zen documentation](https://opencode.ai/docs/zen).
 
@@ -56,6 +56,7 @@ for await (const chunk of stream) {
 | `opencode/gemini-3.5-flash`            | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `opencode/gemini-3.5-flash-lite`       | 1.0M    |       |           |       |       |       | $0.30      | $3          |
 | `opencode/gemini-3.6-flash`            | 1.0M    |       |           |       |       |       | $2         | $8          |
+| `opencode/gemini-3.7-flash`            | 1.0M    |       |           |       |       |       | $2         | $8          |
 | `opencode/glm-5`                       | 205K    |       |           |       |       |       | $1         | $3          |
 | `opencode/glm-5.1`                     | 205K    |       |           |       |       |       | $1         | $4          |
 | `opencode/glm-5.2`                     | 1.0M    |       |           |       |       |       | $1         | $4          |
@@ -92,6 +93,7 @@ for await (const chunk of stream) {
 | `opencode/minimax-m2.5`                | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `opencode/minimax-m2.7`                | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `opencode/minimax-m3`                  | 512K    |       |           |       |       |       | $0.30      | $1          |
+| `opencode/muse-spark-1.2`              | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `opencode/nemotron-3-ultra-free`       | 1.0M    |       |           |       |       |       | —          | —           |
 | `opencode/nemotron-3.5-lightning-free` | 262K    |       |           |       |       |       | —          | —           |
 | `opencode/qwen3.5-plus`                | 262K    |       |           |       |       |       | $0.20      | $1          |

package/.docs/models/providers/requesty.md

@@ -2,7 +2,7 @@
 
 # ![Requesty logo](https://models.dev/logos/requesty.svg)Requesty
 
-Access 47 Requesty models through Mastra's model router. Authentication is handled automatically using the `REQUESTY_API_KEY` environment variable.
+Access 49 Requesty models through Mastra's model router. Authentication is handled automatically using the `REQUESTY_API_KEY` environment variable.
 
 Learn more in the [Requesty documentation](https://requesty.ai/solution/llm-routing/models).
 
@@ -64,6 +64,8 @@ for await (const chunk of stream) {
 | `requesty/gemini-3.5-flash-lite`     | 1.0M    |       |           |       |       |       | $0.30      | $3          |
 | `requesty/gemini-3.5-flash@eu`       | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `requesty/gemini-3.6-flash`          | 1.0M    |       |           |       |       |       | $2         | $7          |
+| `requesty/gemini-3.7-flash`          | 1.0M    |       |           |       |       |       | $0.75      | $4          |
+| `requesty/gemini-3.7-flash@eu`       | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `requesty/glm-5.2`                   | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `requesty/glm-5.2@eu`                | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `requesty/gpt-4.1-mini@eu`           | 1.0M    |       |           |       |       |       | $0.44      | $2          |

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

@@ -2,7 +2,7 @@
 
 # ![Z.AI Coding Plan logo](https://models.dev/logos/zai-coding-plan.svg)Z.AI Coding Plan
 
-Access 4 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+Access 5 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
 
 Learn more in the [Z.AI Coding Plan documentation](https://docs.z.ai/devpack/overview).
 
@@ -40,6 +40,7 @@ for await (const chunk of stream) {
 | `zai-coding-plan/glm-5-turbo`       | 200K    |       |           |       |       |       | —          | —           |
 | `zai-coding-plan/glm-5.2`           | 1.0M    |       |           |       |       |       | —          | —           |
 | `zai-coding-plan/glm-5.2-highspeed` | 1.0M    |       |           |       |       |       | —          | —           |
+| `zai-coding-plan/glm-5.3`           | 1.0M    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -69,7 +70,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zai-coding-plan/glm-5.2-highspeed"
+      ? "zai-coding-plan/glm-5.3"
       : "zai-coding-plan/glm-4.7";
   }
 });

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

@@ -2,7 +2,7 @@
 
 # ![Zhipu AI Coding Plan logo](https://models.dev/logos/zhipuai-coding-plan.svg)Zhipu AI Coding Plan
 
-Access 7 Zhipu AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+Access 8 Zhipu AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
 
 Learn more in the [Zhipu AI Coding Plan documentation](https://docs.bigmodel.cn/cn/coding-plan/overview).
 
@@ -42,6 +42,7 @@ for await (const chunk of stream) {
 | `zhipuai-coding-plan/glm-5.1`           | 200K    |       |           |       |       |       | —          | —           |
 | `zhipuai-coding-plan/glm-5.2`           | 1.0M    |       |           |       |       |       | —          | —           |
 | `zhipuai-coding-plan/glm-5.2-highspeed` | 1.0M    |       |           |       |       |       | —          | —           |
+| `zhipuai-coding-plan/glm-5.3`           | 1.0M    |       |           |       |       |       | —          | —           |
 | `zhipuai-coding-plan/glm-5v-turbo`      | 200K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration

package/.docs/models/providers.md

@@ -43,6 +43,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Cortecs](https://mastra.ai/models/providers/cortecs)
 - [CrofAI](https://mastra.ai/models/providers/crof)
 - [CrossModel](https://mastra.ai/models/providers/crossmodel)
+- [Crusoe](https://mastra.ai/models/providers/crusoe)
 - [D.Run (China)](https://mastra.ai/models/providers/drun)
 - [DaoXE](https://mastra.ai/models/providers/daoxe)
 - [Databricks](https://mastra.ai/models/providers/databricks)

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

@@ -196,6 +196,31 @@ const session = await controller.getSessionByResource('project-42', 'editor-wind
 
 Returns: `Promise<Session<TState> | undefined>`
 
+#### `onSessionCreated(listener, options?)`
+
+Subscribe to process-local notifications after `createSession()` materializes a new live session. Listener errors are isolated and don't prevent other listeners from running. Call the returned function to unsubscribe.
+
+By default listeners are fire-and-forget. Pass `{ blocking: true }` to make `createSession()` await the listener before resolving the new session, so the host can prepare session state before the caller can start a run. Blocking listeners run sequentially in registration order, before fire-and-forget listeners are notified. A blocking listener must not call `createSession()` for the same `(resourceId, scope)` pair. That call would await its own hydration and deadlock.
+
+```typescript
+const unsubscribe = controller.onSessionCreated(
+  async session => {
+    const settings = await loadSettings(session.identity.getResourceId())
+    if (settings) await session.state.set(settings)
+  },
+  { blocking: true },
+)
+
+// Default listeners stay fire-and-forget.
+controller.onSessionCreated(session => {
+  console.log(`Created ${session.identity.getResourceId()}`)
+})
+```
+
+Listeners run once per newly materialized session, not for cached sessions returned by later `createSession()` calls. They run only in the current process and aren't persisted events.
+
+Returns: `() => void`
+
 #### `onSessionDeleted(listener)`
 
 Subscribe to process-local notifications after `deleteSession()` tears down a live session. Listener errors are isolated and don't prevent other listeners from running. Call the returned function to unsubscribe.
@@ -472,5 +497,5 @@ await controller.stopIntervals()
 - [AgentController guide](https://mastra.ai/docs/harness/agent-controller)
 - [Session reference](https://mastra.ai/reference/agent-controller/session)
 - [Agents](https://mastra.ai/docs/agents/overview)
-- [Workspace](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
 - [Channels](https://mastra.ai/docs/capabilities/channels)

package/.docs/reference/browser/browser-viewer.md

@@ -229,4 +229,4 @@ browse skills install
 
 - [BrowserViewer guide](https://mastra.ai/integrations/browsers/browser-viewer): Setup and usage walkthrough
 - [MastraBrowser](https://mastra.ai/reference/browser/mastra-browser): Base class API reference
-- [Workspace overview](https://mastra.ai/docs/workspace/overview): Workspace configuration
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox): Workspace configuration

package/.docs/reference/configuration.md

@@ -483,7 +483,7 @@ export const mastra = new Mastra({
 
 A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents inherit the global workspace on the `Mastra` class unless they have their own workspace configured.
 
-See the [Workspace documentation](https://mastra.ai/docs/workspace/overview) for implementation details.
+See the [Workspace documentation](https://mastra.ai/docs/workspace/sandbox) for implementation details.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/core/removeWorkspace.md

@@ -24,5 +24,5 @@ When `destroy` is `true` and `workspace.destroy()` throws, the call rejects with
 
 ## Related
 
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)

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

@@ -4,9 +4,9 @@
 
 > **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.
+A [workspace](https://mastra.ai/docs/workspace/sandbox) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents 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).
+Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/workspace/sandbox).
 
 ## Default workspace
 
@@ -65,7 +65,7 @@ Customize the workspace when the default local directory isn't enough. Common re
 - Add workspace search with BM25 or vector search.
 - Share one workspace across multiple agents.
 
-For provider patterns and runtime behavior, see the [workspace overview](https://mastra.ai/docs/workspace/overview), [sandbox guide](https://mastra.ai/docs/workspace/sandbox), and [workspace search](https://mastra.ai/docs/workspace/search).
+For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/workspace/sandbox) and [workspace search](https://mastra.ai/docs/workspace/search).
 
 ## Runtime boundary
 

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -189,6 +189,8 @@ When an organization has exhausted its observability quota, the Mastra platform
 
 The probe timer doesn't keep the Node.js process alive, so short-lived and serverless processes exit normally while paused.
 
+Every request the exporter sends (batch uploads for all five signal types, plus the traces recovery probe) includes the `x-mastra-observability-capabilities: quota-pause-v1` header. This tells the platform that the client understands the quota-pause contract, so it can safely respond with `402` instead of silently dropping telemetry for older clients that would retry it.
+
 ### Endpoint routing
 
 - Base origins derive signal endpoints automatically

package/.docs/reference/processors/skill-search-processor.md

@@ -112,4 +112,4 @@ Reserve workspace file tools such as `mastra_workspace_read_file` for explicit f
 
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Workspace Skills](https://mastra.ai/docs/workspace/overview)
+- [Workspace Skills](https://mastra.ai/docs/workspace/skills)

package/.docs/reference/tools/create-code-mode.md

@@ -126,4 +126,4 @@ export const codeModeTool = createCodeModeTool({
 
 - [Code mode](https://mastra.ai/docs/agents/code-mode)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/reference/tools/create-tool.md

@@ -89,7 +89,7 @@ The first `execute` parameter is the validated value from `inputSchema`. Destruc
 
 **onInputAvailable** (`function`): Optional callback invoked when the complete tool input is available and parsed. Signature: ({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike\<void>.
 
-**onOutput** (`function`): Optional callback invoked after the tool has successfully executed and returned output. Signature: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.
+**onOutput** (`function`): Optional callback invoked after a server-executed tool returns output or after a successful client-executed tool result arrives on a follow-up request. Error results don't invoke the hook. For client-executed results, TSchemaOut is a static type only: the server doesn't validate the result against outputSchema, so treat the output as untrusted. Signature: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.
 
 Runtime-populated fields such as `mastra` and `mcpMetadata` appear in source types but are set by Mastra or MCP adapters. You don't need to configure them for ordinary `createTool()` usage.
 
@@ -440,7 +440,7 @@ export const tool = createTool({
 
 #### `onOutput`
 
-Called after the tool has successfully executed and returned output. Useful for logging results, triggering follow-up actions, or analytics.
+Called after a server-executed tool returns output or after a successful client-executed tool result arrives on a follow-up request. Use it to log results or trigger follow-up actions.
 
 ```typescript
 export const tool = createTool({
@@ -459,9 +459,15 @@ export const tool = createTool({
 })
 ```
 
+Client-executed tools don't define an `execute` function. The browser runs the tool and sends the result on a follow-up request. `onOutput` then runs on the server. Only a correlated successful result invokes the hook: error results, such as the AI SDK `error-text` and `error-json` output types, don't invoke `onOutput`.
+
+For client-executed results, the follow-up request must include both the assistant tool call and the tool result, which `@mastra/client-js` sends automatically. A request that carries only the tool result doesn't fire the hook. In this case the callback receives `{ toolCallId, toolName, output, abortSignal }` only.
+
+Delivery is at least once, so a retried request runs the hook again. Keep the hook idempotent and treat client output as untrusted data: the server doesn't validate the result against `outputSchema`, so the `output` type is a static type only.
+
 ### Hook execution order
 
-For a typical streaming tool call, the hooks are invoked in this order:
+For a typical streaming tool call on a server-executed tool, the hooks are invoked in this order:
 
 1. **onInputStart**: Input streaming begins
 2. **onInputDelta**: Called multiple times as chunks arrive
@@ -469,6 +475,8 @@ For a typical streaming tool call, the hooks are invoked in this order:
 4. Tool's **execute** function runs
 5. **onOutput**: Tool has completed successfully
 
+For a client-executed tool, steps 1-3 run while the model streams the tool call, the client runs the tool instead of a server-side `execute`, and `onOutput` runs on the follow-up request that carries a successful result.
+
 ### Hook parameters
 
 Hook callbacks receive these source-backed parameter shapes:

package/.docs/reference/tools/mcp-server.md

@@ -1637,6 +1637,9 @@ const calculatorTool = createTool({
     num2: z.number(),
     operation: z.enum(['add', 'subtract']),
   }),
+  mcp: {
+    _meta: { ui: { resourceUri: 'ui://calculator/main' } },
+  },
   execute: async ({ num1, num2, operation }) => {
     const result = operation === 'add' ? num1 + num2 : num1 - num2
     return {
@@ -1660,7 +1663,7 @@ const server = new MCPServer({
 })
 ```
 
-Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
+Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
 
 ## Related information
 

package/.docs/reference/workspace/local-filesystem.md

@@ -356,4 +356,4 @@ Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my
 
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/reference/workspace/local-sandbox.md

@@ -223,4 +223,4 @@ This separation prevents sandboxed processes from reading or modifying their own
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox Interface](https://mastra.ai/reference/workspace/sandbox)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
-- [Workspace Overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/reference/workspace/workspace-class.md

@@ -31,9 +31,9 @@ const workspace = new Workspace({
 
 **name** (`string`): Human-readable name (Default: `workspace-{id}`)
 
-**filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives requestContext and returns a filesystem per request. See dynamic filesystem.
+**filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): Filesystem provider instance, or a resolver function that receives requestContext and returns a filesystem per request. See multi-tenant filesystems.
 
-**sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox provider instance, or a resolver function that receives requestContext and returns a sandbox per request. See dynamic sandbox.
+**sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox provider instance, or a resolver function that receives requestContext and returns a sandbox per request. See multi-tenant sandboxes.
 
 **instructions.dynamicSandbox** (`'placeholder' | 'resolve' | (({ requestContext }) => string)`): Controls how a resolver-backed sandbox contributes to workspace instructions. 'placeholder' (default) emits stable text without calling the resolver. 'resolve' calls the resolver and uses the sandbox's own instructions. A function returns custom text without resolving. Has no effect on a static sandbox. (Default: `'placeholder'`)
 
@@ -57,15 +57,9 @@ const workspace = new Workspace({
 
 **tools** (`WorkspaceToolsConfig`): Per-tool configuration for enabling tools and setting safety options
 
-**tools.enabled** (`boolean`): Whether the tool is available to agents
+**tools.enabled** (`boolean | ((context: ToolConfigContext) => boolean | Promise<boolean>)`): Default availability for all workspace tools. Per-tool settings take precedence.
 
-**tools.requireApproval** (`boolean`): Whether the tool requires user approval before execution
-
-**tools.name** (`string`): Custom name to expose this tool as. Replaces the default mastra\_workspace\_\* name. The config key must still use the original WORKSPACE\_TOOLS constant.
-
-**tools.requireReadBeforeWrite** (`boolean`): For write tools: require reading the file first to prevent overwrites
-
-**tools.maxOutputTokens** (`number`): Maximum tokens for tool output. Output exceeding this limit is truncated using tiktoken.
+**tools.requireApproval** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): Default approval policy for all workspace tools. Per-tool settings take precedence.
 
 **tools.writeLockTimeoutMs** (`number`): Maximum time in milliseconds a write tool waits to acquire the per-file write lock before failing. Raise this for slow or cold-starting filesystems (e.g. remote sandboxes).
 
@@ -73,6 +67,17 @@ const workspace = new Workspace({
 
 **operationTimeout** (`number`): Timeout for operations in milliseconds
 
+For a resolver-backed sandbox, the default `'placeholder'` mode avoids provisioning a sandbox while workspace instructions are built. Set `instructions.dynamicSandbox` to `'resolve'` when the instructions must come from the resolved sandbox:
+
+```typescript
+const workspace = new Workspace({
+  sandbox: ({ requestContext }) => resolveSandbox(requestContext),
+  instructions: { dynamicSandbox: 'resolve' },
+})
+```
+
+This calls the resolver while building instructions. To describe a request-specific environment without provisioning it, pass a function that returns instruction text from `requestContext` instead.
+
 ## Tool configuration
 
 The `tools` option accepts a `WorkspaceToolsConfig` object that controls which workspace tools are enabled and their safety settings.
@@ -97,12 +102,44 @@ const workspace = new Workspace({
 })
 ```
 
-The config object has two parts:
+The config object has two types of settings:
+
+- **Global settings**: `enabled` and `requireApproval` apply to all workspace tools unless overridden. `hooks` and `writeLockTimeoutMs` are global-only and can't be configured per tool.
+- **Per-tool overrides**: Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
+
+Per-tool overrides accept the following options:
+
+**enabled** (`boolean | ((context: ToolConfigContext) => boolean | Promise<boolean>)`): Whether the tool is available. Functions are evaluated when Mastra lists tools. (Default: `true`)
+
+**requireApproval** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): Whether the tool requires approval. Functions are evaluated when the tool executes. (Default: `false`)
+
+**name** (`string`): Name exposed to the model instead of the default mastra\_workspace\_\* name.
 
-- **Global defaults** (`enabled`, `requireApproval`): Apply to all tools unless overridden
-- **Per-tool overrides** - Use `WORKSPACE_TOOLS` constants as keys to configure individual tools
+**requireReadBeforeWrite** (`boolean | ((context: ToolConfigWithArgsContext) => boolean | Promise<boolean>)`): For write tools, require the agent to read an existing file before changing it. (Default: `false`)
+
+**maxOutputTokens** (`number`): Maximum output tokens for tools that support token-based truncation.
+
+`ToolConfigContext` contains `{ requestContext, workspace }`. Execution-time policies use `ToolConfigWithArgsContext`, which also contains the tool's `args`.
+
+```typescript
+import { Workspace, WORKSPACE_TOOLS } from '@mastra/core/workspace'
+
+const workspace = new Workspace({
+  id: 'my-workspace',
+  tools: {
+    enabled: ({ requestContext }) => requestContext.get('workspace-tools') === true,
+    [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: {
+      requireApproval: ({ args }) => (args.path as string).startsWith('/protected'),
+      requireReadBeforeWrite: true,
+    },
+    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
+      maxOutputTokens: 5000,
+    },
+  },
+})
+```
 
-See [workspace overview](https://mastra.ai/docs/workspace/overview) for more examples.
+See [Filesystem tools](https://mastra.ai/docs/workspace/filesystem), [Sandbox tools](https://mastra.ai/docs/workspace/sandbox), [LSP inspection](https://mastra.ai/docs/workspace/lsp), and [Search tools](https://mastra.ai/docs/workspace/search) for capability-specific configuration.
 
 ### Tool name remapping
 
@@ -469,7 +506,7 @@ The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle
 
 **backgroundProcesses.abortSignal** (`AbortSignal | null | false`): Abort signal for background processes. undefined (default) uses the agent's signal. null or false disables abort — processes persist after agent shutdown.
 
-See [Background process callbacks](https://mastra.ai/docs/workspace/sandbox) for usage examples.
+See [Background processes](https://mastra.ai/docs/workspace/sandbox) for callback examples.
 
 ### Search tools
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.17-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`15101bb`](https://github.com/mastra-ai/mastra/commit/15101bb53c0d934f31af6b8813b88191e382a5e5), [`c2c3deb`](https://github.com/mastra-ai/mastra/commit/c2c3debcf670c7082d0a5e553aa99818a864698c), [`33374ba`](https://github.com/mastra-ai/mastra/commit/33374ba359e4fb13eaa918ae925fe167a3c55414), [`c5f964d`](https://github.com/mastra-ai/mastra/commit/c5f964d3f77064e978f8066ec506eed77ba5c63c), [`f8f653f`](https://github.com/mastra-ai/mastra/commit/f8f653f10980d01a73706cc3c8689ca5e40ce808)]:
+  - @mastra/core@1.60.0-alpha.1
+
+## 1.2.17-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`587f6ef`](https://github.com/mastra-ai/mastra/commit/587f6efcfc25880b93760a8607d1cd381ec612fe)]:
+  - @mastra/core@1.59.1-alpha.0
+
 ## 1.2.16
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.16",
+  "version": "1.2.17-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/mcp": "^1.16.0",
-    "@mastra/core": "1.59.0"
+    "@mastra/core": "1.60.0-alpha.1",
+    "@mastra/mcp": "^1.16.0"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@internal/lint": "0.0.123",
     "@internal/types-builder": "0.0.98",
-    "@mastra/core": "1.59.0"
+    "@mastra/core": "1.60.0-alpha.1",
+    "@internal/lint": "0.0.123"
   },
   "homepage": "https://mastra.ai",
   "repository": {