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

package/.docs/docs/agents/agent-approval.md

@@ -90,6 +90,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Explaining a decline
+
+`declineToolCall()`, `declineToolCallGenerate()`, and `declineNetworkToolCall()` accept an optional `reason`. The reason is returned to the model in place of the tool result, so the model can adjust instead of retrying blindly. It's also stored on the tool call's `approval` metadata, so it's still there when the conversation is recalled.
+
+```typescript
+const declined = await agent.declineToolCall({
+  runId: stream.runId,
+  toolCallId,
+  reason: 'Reading other users PII is not allowed, ask the user for their own email instead',
+})
+```
+
+Without a `reason`, the model receives the default message `Tool call was not approved by the user`.
+
 #### Conditional approval with a function
 
 Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:

package/.docs/docs/capabilities/subagents.md

@@ -113,7 +113,7 @@ The `context` object includes:
 
 ### Request context at the delegation boundary
 
-Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run doesn't affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -134,6 +134,9 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 
 - `context.bail()`: Stop the parent agent's loop immediately
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
+
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {

package/.docs/docs/datasets/running-experiments.md

@@ -206,6 +206,55 @@ The `experiment.run.finished` event is awaited before Mastra persists the final
 
 The exported event types are `ExperimentEvent`, `ExperimentRunStartedEvent`, `ExperimentItemCompletedEvent`, and `ExperimentRunFinishedEvent`. Use the discriminated `type` field to narrow an event before reading event-specific properties.
 
+## Lifecycle hooks
+
+Use lifecycle hooks to prepare state before a target runs and clean it up afterwards. This is useful when an item can't be evaluated against an empty environment. A run might need a fixture file copied into the agent's workspace, or a sandbox provisioned before the agent can touch it.
+
+Hooks run at two levels. `beforeAll` and `afterAll` run once per experiment, and `beforeEach` and `afterEach` run once per item:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'document-agent',
+  scorers: ['accuracy'],
+  beforeAll: async ({ experimentId }) => {
+    await createWorkspace(experimentId)
+  },
+  beforeEach: async ({ item }) => {
+    await copyFixture(item.metadata?.fixture)
+  },
+  afterEach: async ({ item, result }) => {
+    await clearWorkspaceFiles(item.id)
+  },
+  afterAll: async ({ summary }) => {
+    await deleteWorkspace(summary.experimentId)
+  },
+})
+```
+
+Every hook can be async. Each one receives the `experimentId`, the `mastra` instance, and the run-level `signal`, so long-running setup can be cancelled along with the experiment. The per-item hooks also receive `item`. The teardown hooks receive the result they follow: `afterEach` receives the item's `result` including scores, and `afterAll` receives the `summary` that's about to be returned.
+
+The item passed to hooks exposes `id`, `input`, `groundTruth`, and `metadata`. Fields that control execution, such as tool mocks and scorer selection, aren't exposed, so a hook can't change how the item runs.
+
+### Hook failures
+
+Each hook has a different consequence when it throws, based on how much of the run depends on it:
+
+| Hook         | On failure                                                                       |
+| ------------ | -------------------------------------------------------------------------------- |
+| `beforeAll`  | Fails the experiment. No items run.                                              |
+| `beforeEach` | Fails that item with `EXPERIMENT_ITEM_BEFORE_EACH_FAILED`. Other items continue. |
+| `afterEach`  | Logged. The item's recorded outcome doesn't change.                              |
+| `afterAll`   | Logged. The returned summary doesn't change.                                     |
+
+When `beforeAll` fails, the experiment is marked failed and the `experiment.run.finished` event is still emitted before the error propagates.
+
+When `beforeEach` fails, the target and its scorers are skipped for that item, since the item's preconditions were never met. `afterEach` is also skipped for that item, on the basis that setup which didn't finish owns its own cleanup.
+
+Teardown failures are logged rather than propagated. By the time `afterEach` runs, the target has already produced a real result, and discarding it because cleanup was untidy would lose the data the experiment was run to collect.
+
+`afterAll` runs on every exit path, including when the experiment fails, when `beforeAll` fails, and when an [event observer](#observe-experiment-events) fails, so teardown isn't skipped when something goes wrong. It runs at most once per experiment.
+
 ## Tool mocks
 
 When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.

package/.docs/models/gateways/vercel.md

@@ -2,7 +2,7 @@
 
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 323 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 322 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -247,7 +247,6 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-5.1-codex`                   |
 | `openai/gpt-5.1-codex-max`               |
 | `openai/gpt-5.1-codex-mini`              |
-| `openai/gpt-5.1-instant`                 |
 | `openai/gpt-5.1-thinking`                |
 | `openai/gpt-5.2`                         |
 | `openai/gpt-5.2-codex`                   |

package/.docs/models/index.md

@@ -2,7 +2,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5458 models from 168 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 5460 models from 168 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/alibaba.md

@@ -2,7 +2,7 @@
 
 # ![Alibaba logo](https://models.dev/logos/alibaba.svg)Alibaba
 
-Access 52 Alibaba models through Mastra's model router. Authentication is handled automatically using the `DASHSCOPE_API_KEY` environment variable.
+Access 54 Alibaba models through Mastra's model router. Authentication is handled automatically using the `DASHSCOPE_API_KEY` environment variable.
 
 Learn more in the [Alibaba documentation](https://www.alibabacloud.com/help/en/model-studio/models).
 
@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "alibaba/qvq-max"
+  model: "alibaba/deepseek-v4-flash-0731"
 });
 
 // Generate a response
@@ -36,6 +36,8 @@ for await (const chunk of stream) {
 
 | Model                                        | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | -------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `alibaba/deepseek-v4-flash-0731`             | 1.0M    |       |           |       |       |       | $0.20      | $0.40       |
+| `alibaba/glm-5.2`                            | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `alibaba/qvq-max`                            | 131K    |       |           |       |       |       | $1         | $5          |
 | `alibaba/qwen-flash`                         | 1.0M    |       |           |       |       |       | $0.05      | $0.40       |
 | `alibaba/qwen-max`                           | 33K     |       |           |       |       |       | $2         | $6          |
@@ -99,7 +101,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
-    id: "alibaba/qvq-max",
+    id: "alibaba/deepseek-v4-flash-0731",
     apiKey: process.env.DASHSCOPE_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -118,7 +120,7 @@ const agent = new Agent({
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
       ? "alibaba/qwq-plus"
-      : "alibaba/qvq-max";
+      : "alibaba/deepseek-v4-flash-0731";
   }
 });
 ```

package/.docs/models/providers/cortecs.md

@@ -2,7 +2,7 @@
 
 # ![Cortecs logo](https://models.dev/logos/cortecs.svg)Cortecs
 
-Access 106 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
+Access 105 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
 
 Learn more in the [Cortecs documentation](https://cortecs.ai).
 
@@ -51,7 +51,6 @@ for await (const chunk of stream) {
 | `cortecs/cosmos3-super-reasoner`              | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `cortecs/deepseek-r1-0528`                    | 164K    |       |           |       |       |       | $0.65      | $3          |
 | `cortecs/deepseek-v3.2`                       | 164K    |       |           |       |       |       | $0.30      | $0.49       |
-| `cortecs/deepseek-v4-flash`                   | 1.0M    |       |           |       |       |       | $0.15      | $0.30       |
 | `cortecs/deepseek-v4-flash-0731`              | 1.0M    |       |           |       |       |       | $0.25      | $0.30       |
 | `cortecs/deepseek-v4-pro`                     | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `cortecs/devstral-2512`                       | 262K    |       |           |       |       |       | $0.45      | $2          |

package/.docs/models/providers/digitalocean.md

@@ -59,7 +59,7 @@ for await (const chunk of stream) {
 | `digitalocean/deepseek-4-flash`                      | 1.0M    |       |           |       |       |       | $0.08      | $0.17       |
 | `digitalocean/deepseek-r1-distill-llama-70b`         | 33K     |       |           |       |       |       | $0.99      | $0.99       |
 | `digitalocean/deepseek-v3`                           | 164K    |       |           |       |       |       | —          | —           |
-| `digitalocean/deepseek-v4-flash-0731`                | 1.0M    |       |           |       |       |       | $0.13      | $0.25       |
+| `digitalocean/deepseek-v4-flash-0731`                | 1.0M    |       |           |       |       |       | $0.08      | $0.25       |
 | `digitalocean/deepseek-v4-pro`                       | 1.0M    |       |           |       |       |       | $0.87      | $2          |
 | `digitalocean/e5-large-v2`                           | 512     |       |           |       |       |       | $0.02      | —           |
 | `digitalocean/fal-ai/elevenlabs/tts/multilingual-v2` | —       |       |           |       |       |       | —          | —           |

package/.docs/models/providers/kilo.md

@@ -40,7 +40,7 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                           | 200K    |       |           |       |       |       | $1         | $5          |
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
-| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.09      | $0.18       |
+| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.08      | $0.25       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $2         | $8          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $3         | $14         |

package/.docs/models/providers/nebius.md

@@ -2,7 +2,7 @@
 
 # ![Nebius Token Factory logo](https://models.dev/logos/nebius.svg)Nebius Token Factory
 
-Access 33 Nebius Token Factory models through Mastra's model router. Authentication is handled automatically using the `NEBIUS_API_KEY` environment variable.
+Access 34 Nebius Token Factory models through Mastra's model router. Authentication is handled automatically using the `NEBIUS_API_KEY` environment variable.
 
 Learn more in the [Nebius Token Factory documentation](https://docs.tokenfactory.nebius.com/).
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
 
 | Model                                            | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ------------------------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `nebius/deepseek-ai/DeepSeek-V4-Flash`           | 131K    |       |           |       |       |       | $0.14      | $0.28       |
 | `nebius/deepseek-ai/DeepSeek-V4-Pro`             | 1.0M    |       |           |       |       |       | $2         | $4          |
 | `nebius/google/gemma-3-27b-it`                   | 110K    |       |           |       |       |       | $0.10      | $0.30       |
 | `nebius/meta-llama/Llama-3.3-70B-Instruct`       | 128K    |       |           |       |       |       | $0.13      | $0.40       |

package/.docs/models/providers/tinfoil.md

@@ -2,7 +2,7 @@
 
 # ![Tinfoil logo](https://models.dev/logos/tinfoil.svg)Tinfoil
 
-Access 7 Tinfoil models through Mastra's model router. Authentication is handled automatically using the `TINFOIL_API_KEY` environment variable.
+Access 8 Tinfoil models through Mastra's model router. Authentication is handled automatically using the `TINFOIL_API_KEY` environment variable.
 
 Learn more in the [Tinfoil documentation](https://docs.tinfoil.sh).
 
@@ -41,6 +41,7 @@ for await (const chunk of stream) {
 | `tinfoil/gpt-oss-120b`           | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `tinfoil/gpt-oss-safeguard-120b` | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `tinfoil/kimi-k2-6`              | 256K    |       |           |       |       |       | $2         | $5          |
+| `tinfoil/kimi-k3`                | 256K    |       |           |       |       |       | $2         | $6          |
 | `tinfoil/llama3-3-70b`           | 128K    |       |           |       |       |       | $2         | $3          |
 | `tinfoil/nomic-embed-text`       | 8K      |       |           |       |       |       | $0.05      | —           |
 

package/.docs/models/providers/zeldoc.md

@@ -17,7 +17,7 @@ const agent = new Agent({
   id: "my-agent",
   name: "My Agent",
   instructions: "You are a helpful assistant",
-  model: "zeldoc/z-code"
+  model: "zeldoc/zdev"
 });
 
 // Generate a response
@@ -34,9 +34,9 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model           | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| --------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `zeldoc/z-code` | 1.0M    |       |           |       |       |       | —          | —           |
+| Model         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `zeldoc/zdev` | 1.0M    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -48,7 +48,7 @@ const agent = new Agent({
   name: "custom-agent",
   model: {
     url: "https://api.zeldoc.ai/v1",
-    id: "zeldoc/z-code",
+    id: "zeldoc/zdev",
     apiKey: process.env.ZELDOC_API_KEY,
     headers: {
       "X-Custom-Header": "value"
@@ -66,8 +66,8 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zeldoc/z-code"
-      : "zeldoc/z-code";
+      ? "zeldoc/zdev"
+      : "zeldoc/zdev";
   }
 });
 ```

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

@@ -143,12 +143,14 @@ session.abort()
 
 Return the workspace resolved for this session. This preserves session-level overrides and workspaces selected from the session scope.
 
+A workspace is optional. When neither the session nor the `AgentController` configures one, the session still runs without filesystem or sandbox access, and this returns `undefined`. Check the result before using it.
+
 ```typescript
 const workspace = session.getWorkspace()
-const skill = await workspace.skills?.get('code-review')
+const skill = await workspace?.skills?.get('code-review')
 ```
 
-Returns: `Workspace`
+Returns: `Workspace | undefined`
 
 ### Session grants
 

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

@@ -421,12 +421,13 @@ Returns `{ accepted: true, runId: string, toolCallId?: string }`.
 
 ### `declineToolCall()`
 
-Decline a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the decline response.
+Decline a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the decline response. Pass an optional `reason` to tell the model why the call was rejected. The default is `Tool call was not approved by the user`.
 
 ```typescript
 const response = await agent.declineToolCall({
   runId: 'run-123',
   toolCallId: 'tool-call-456',
+  reason: 'This file is outside the allowed directory', // optional
 })
 
 response.processDataStream({

package/.docs/reference/configuration.md

@@ -574,7 +574,7 @@ export const mastra = new Mastra({
 
 Minifies the bundled output, stripping comments and whitespace and shortening local identifiers. Exported names are preserved.
 
-Off by default so build output stays readable and stack traces stay meaningful. Enable it when bundle size matters, such as packaging a container image for an on-prem deployment. `mastra dev` is never minified.
+Off by default so build output stays readable and stack traces stay usable. Enable it when bundle size matters, such as packaging a container image for an on-prem deployment. `mastra dev` is never minified.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/datasets/startExperiment.md

@@ -79,6 +79,14 @@ console.log(`Status: ${summary2.status}`)
 
 **unmockedToolPolicy** (`'allow' | 'deny'`): Controls undeclared agent tool calls. allow executes them live. deny fails the item with TOOL\_MOCK\_NOT\_DECLARED before execution. An item-level value overrides this experiment default. (Default: `'allow'`)
 
+**beforeAll** (`(args: ExperimentHookArgs) => void | Promise<void>`): Runs once before any item executes. Receives experimentId, mastra, and signal. A failure fails the experiment and no items run.
+
+**beforeEach** (`(args: ExperimentItemHookArgs) => void | Promise<void>`): Runs before each item executes. Also receives the item (id, input, groundTruth, metadata). A failure fails that item with EXPERIMENT\_ITEM\_BEFORE\_EACH\_FAILED and skips its target, scorers, and afterEach.
+
+**afterEach** (`(args: ExperimentItemResultHookArgs) => void | Promise<void>`): Runs after each item completes. Also receives the item's result with its scores. Skipped when beforeEach failed. A failure is logged and doesn't change the item's outcome.
+
+**afterAll** (`(args: ExperimentRunResultHookArgs) => void | Promise<void>`): Runs once after the experiment finishes, on every exit path including failure. Also receives the summary. A failure is logged and doesn't change the summary.
+
 **persistence** (`ExperimentPersistencePolicy`): Controls whether this run writes experiment records and score records. Targets and scorers still execute, and results remain available in the returned summary.
 
 **persistence.experiments** (`'default' | 'none'`): Set to none to skip experiment creation, item results, progress, and terminal status writes.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.15-alpha.14
+
+### Patch Changes
+
+- Updated dependencies [[`86b7b77`](https://github.com/mastra-ai/mastra/commit/86b7b777980d30f66e1fd134a37d2af4c22e54cc), [`80a3324`](https://github.com/mastra-ai/mastra/commit/80a33245d3110204de6f56d61211523ffe338692), [`d9d2881`](https://github.com/mastra-ai/mastra/commit/d9d2881ede6dd6c023d144215fc812062aed0890), [`82e3365`](https://github.com/mastra-ai/mastra/commit/82e3365ef7c9bf7bee2e7a7029035ea262d68895), [`1b482c2`](https://github.com/mastra-ai/mastra/commit/1b482c2d89244dd758c41e5f927a2b44041388d2), [`e6a2860`](https://github.com/mastra-ai/mastra/commit/e6a2860649cc51f87d32d78b766ae2126446ba07), [`7bd85ea`](https://github.com/mastra-ai/mastra/commit/7bd85ea7588b71c25ce9f4019c88f8539be5dcbc)]:
+  - @mastra/core@1.58.0-alpha.9
+
 ## 1.2.15-alpha.12
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.15-alpha.13",
+  "version": "1.2.15-alpha.15",
   "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/core": "1.58.0-alpha.8",
-    "@mastra/mcp": "^1.16.0-alpha.1"
+    "@mastra/mcp": "^1.16.0-alpha.1",
+    "@mastra/core": "1.58.0-alpha.9"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -46,8 +46,8 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
     "@internal/types-builder": "0.0.96",
-    "@mastra/core": "1.58.0-alpha.8",
-    "@internal/lint": "0.0.121"
+    "@internal/lint": "0.0.121",
+    "@mastra/core": "1.58.0-alpha.9"
   },
   "homepage": "https://mastra.ai",
   "repository": {