@mastra/mcp-docs-server 1.3.2-alpha.1 → 1.3.2-alpha.10

package/.docs/docs/agents/processors.md

@@ -879,7 +879,7 @@ const agent = new Agent({
 The retry mechanism:
 
 - Works in `processOutputStep()` and `processInputStep()` methods
-- Replays the step with the abort reason added as context for the LLM
+- Replays the step with the abort reason appended verbatim to the end of the conversation as a system reminder. The retry keeps the previous request as its prefix, which preserves provider prompt caching
 - Tracks retry count via the `retryCount` parameter
 - Requires an explicit `maxProcessorRetries` limit on the agent or call
 

package/.docs/docs/evals/evals-with-memory.md

@@ -90,7 +90,9 @@ const average = scores.reduce((a, b) => a + b, 0) / scores.length
 
 ## Dataset experiments with an inline task
 
-`dataset.startExperiment({ target: agent })` **doesn't** forward a `memory` option to the agent, only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
+`dataset.startExperiment()` accepts `targetType` and `targetId` for a registered target, or an inline `task` function. For a registered memory-enabled agent, the runner creates a fresh thread per item by default. See [memory-enabled experiment targets](https://mastra.ai/docs/evals/experiments) for resource isolation and request context options.
+
+To choose each item's thread explicitly through `agent.generate()`, use an inline `task` and store `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
 
 ```typescript
 import { randomUUID } from 'node:crypto'

package/.docs/docs/evals/experiments.md

@@ -53,7 +53,9 @@ You can also delete experiments with the [Core API](https://mastra.ai/reference/
 
 ## Experiment targets
 
-You can point an experiment at a registered agent, workflow, or scorer.
+Use `targetType` and `targetId` to select an agent, workflow, or scorer registered on your Mastra instance. The target processes each dataset item. The experiment's `scorers` evaluate the target's output afterward.
+
+For custom execution, pass an inline `task` function instead. See [dataset experiments with an inline task](https://mastra.ai/docs/evals/evals-with-memory) for an example that controls each item's memory thread.
 
 ### Registered agent
 
@@ -68,25 +70,27 @@ const summary = await dataset.startExperiment({
 })
 ```
 
-Each item's `input` is passed directly to `agent.generate()`, so it must be a `string`, `string[]`, or `CoreMessage[]`.
+Each item's `input` is passed directly to the agent. Use a supported message format, such as a prompt string, a message object, or an array of messages. See the [`agent.generate()` reference](https://mastra.ai/reference/agents/generate) for accepted inputs.
 
 #### Memory-enabled agents
 
-When the target agent has its own memory and the request context carries a resource id (`MASTRA_RESOURCE_ID_KEY`, set by auth middleware, the experiment or item `requestContext`, or the Studio **Run Experiment** form), the experiment runner injects a fresh memory thread for each item. A resource id in the request context means "run as this resource": each item's conversation persists as a thread under that resource, and retried items get a new thread per attempt so earlier failed attempts can't leak into the retry's context.
+When the target agent has its own memory, the experiment runner injects a fresh memory thread for each item and retry. Without a resource id in the request context, each thread gets an isolated, experiment-owned resource.
+
+To run against an existing resource, set `MASTRA_RESOURCE_ID_KEY` in the experiment's `requestContext` or in an item's `requestContext`. Item values override experiment values. The runner still creates a fresh thread for each item and retry, but all threads using the same resource id share that resource's memory.
 
 Injected threads are tagged so you can map them back to the run: thread metadata carries the `experimentId` and the dataset item's id as `experimentItemId`. No thread title is generated for them.
 
-Because the threads belong to the caller's resource, resource-scoped memory features both read and write that resource's state during the run:
+When items share a resource, resource-scoped memory features can read and write the same state:
 
-- Resource-scoped working memory updates persist to the resource, and later items in the run see updates made by earlier items.
+- Resource-scoped working memory updates persist to the resource and can affect other items. Items run concurrently by default, so don't rely on an execution order.
 - Resource-scoped semantic recall can surface the resource's prior conversations to the experiment, and experiment transcripts become recallable in that resource's later conversations.
 
 Use this approach to evaluate an agent against a real user's accumulated context. To keep experiment runs from touching real user state, use a dedicated evaluation resource id instead.
 
 Thread injection is skipped in the following cases:
 
-- If the request context also sets `MASTRA_THREAD_ID_KEY`, the runner uses that thread as-is, so every item (and retry) shares the same conversation.
-- If the agent has no memory, or the request context has no resource id, the run is memoryless and nothing is persisted.
+- If the request context sets `MASTRA_THREAD_ID_KEY`, the runner uses that thread as-is. Items and retries using the same thread id share a conversation.
+- If the agent has no memory, or the request context explicitly sets the resource id to an empty string or `null`, the runner skips thread injection.
 
 ### Registered workflow
 
@@ -101,13 +105,24 @@ const summary = await dataset.startExperiment({
 })
 ```
 
-The workflow receives each item's `input` as its trigger data.
+The workflow receives each item's `input` as `inputData` in `run.start()`. Structure the input to match the workflow's input schema.
 
 ### Registered scorer
 
-Point to a scorer to evaluate an LLM judge against ground truth:
+Use a scorer as the target to evaluate the judge itself. The runner calls `scorer.run(item.input)`, so the dataset item's `input` must contain the full payload the scorer expects.
+
+This example assumes a registered `accuracy` scorer that accepts string `input`, `output`, and `groundTruth` fields. Adapt those fields to your scorer's expected shape:
 
 ```typescript
+await dataset.addItem({
+  input: {
+    input: 'What is the capital of France?',
+    output: 'Paris',
+    groundTruth: 'Paris',
+  },
+  groundTruth: { score: 1 },
+})
+
 const summary = await dataset.startExperiment({
   name: 'judge-accuracy-eval',
   targetType: 'scorer',
@@ -115,7 +130,12 @@ const summary = await dataset.startExperiment({
 })
 ```
 
-The scorer receives each item's `input` and `groundTruth`. LLM-based judges can drift over time as underlying models change, so it's important to periodically realign them against known-good labels. A dataset gives you a stable benchmark to detect that drift.
+The two `groundTruth` fields serve different purposes:
+
+- `input.groundTruth` is the reference answer passed to the judge: `'Paris'`.
+- The top-level `groundTruth` is the expected result from the judge: `{ score: 1 }`. It isn't passed to the target scorer.
+
+The target's output contains its `score` and `reason`. To evaluate that output against the top-level ground truth, add another scorer through the experiment's `scorers` option. Without an additional scorer, the experiment records the judge's output but doesn't score its agreement with the expected result.
 
 ## Scoring results
 

package/.docs/docs/harness/durable-agents.md

@@ -278,6 +278,8 @@ Under the default persistence policy, these `running` checkpoints are only writt
 
 Durable agent runs are excluded from the generic boot-time restart of active workflow runs. The only automatic recovery path for durable agent runs is `recovery.durableAgents: 'auto'`, which holds a recovery lease and registers thread runtimes before re-driving each run.
 
+> **Warning:** Automatic and manual recovery re-run the agentic loop from the last persisted snapshot, which can reissue LLM calls (with real cost) and re-execute tool calls. A sub-agent delegation is one generated `agent-<name>` tool call, and recovery doesn't checkpoint the LLM or tool calls inside that delegation independently. If recovery replays the delegation step, the entire sub-agent run starts again and can repeat inner LLM calls and already-completed tool side effects. Make tools, including tools used by sub-agents, idempotent, or deduplicate their external side effects.
+
 ### Snapshot persistence
 
 The `shouldPersistSnapshot` option on `createDurableAgent()` (also accepted in the agent-level `durable` config) controls which workflow snapshots a durable agent writes. The default policy:
@@ -313,8 +315,6 @@ export const mastra = new Mastra({
 
 On startup, this discovers every registered durable agent with runs stuck in `running` status and re-drives them from the last persisted snapshot.
 
-> **Warning:** Recovery re-runs the agentic loop from the last snapshot, which re-issues LLM calls (real cost) and re-executes tool calls. Make sure your tools are idempotent before enabling automatic recovery.
-
 ### Manual recovery
 
 If you need finer control, such as gating recovery behind a leader election or running it on a schedule, call the methods directly:

package/.docs/docs/memory/observational-memory.md

@@ -191,6 +191,40 @@ const memory = new Memory({
 
 `bufferOnIdle` is off by default. It's separate from `bufferTokens`: `bufferTokens` controls step-time async buffering, while `bufferOnIdle` controls end-of-turn buffering for idle turns.
 
+### Retries and failure policy
+
+Observer and Reflector model calls are retried on transient provider errors, and a turn aborts if they still fail. Each stage is controlled independently by:
+
+- `maxRetries`: retries after the initial model call (default `8`).
+- `failurePolicy`: what happens once retries are exhausted, either `'abort'` (default) or `'continue'`.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      observation: {
+        maxRetries: 8,
+        failurePolicy: 'continue',
+      },
+      reflection: {
+        maxRetries: 8,
+        failurePolicy: 'continue',
+      },
+    },
+  },
+})
+```
+
+`maxRetries` governs OM's own retry ladder; the underlying model call is configured with no provider-level retries, so the option is the single retry knob for the stage.
+
+With `failurePolicy: 'continue'`, Mastra retries as configured, reports the failure through the existing OM diagnostics, keeps the failed input pending for a later cycle, and lets the main agent turn continue. It doesn't advance observation boundaries or discard unobserved messages. A Reflector failure under `'continue'` leaves any already-persisted observations committed and defers reflection to the next threshold crossing.
+
+A provider outage usually takes out both stages, so set the policy on both if you want the turn to survive one.
+
+This policy applies only to Observer and Reflector model and provider failures in synchronous, resource-scoped, and buffered observation. Persistence, indexing, transform, locking, invariant, and explicit abort failures remain fatal. It doesn't prevent the underlying provider or network error, change `blockAfter`, or change attachment handling.
+
+> **Warning:** `'continue'` has no backstop for a sustained outage. Unobserved messages stay pending and keep accruing in the main agent's context, so a long outage moves the failure from the memory layer to the model's context limit.
+
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
 ## Benefits

package/.docs/integrations/sandboxes/modal.md

@@ -100,6 +100,8 @@ Get your credentials from the [Modal dashboard](https://modal.com/settings/token
 
 **onStart** (`function`): Lifecycle hook called after the sandbox reaches running status.
 
+**volumes** (`Record<string, Volume>`): Modal Volumes to mount into the sandbox, keyed by absolute mount path. The working directory must not be at or inside a mount path.
+
 **onStop** (`function`): Lifecycle hook called before the sandbox stops.
 
 **onDestroy** (`function`): Lifecycle hook called before the sandbox is destroyed.
@@ -137,6 +139,44 @@ await sandbox._stop()
 await sandbox._start()
 ```
 
+## Volumes and persistent files
+
+Mount [Modal Volumes](https://modal.com/docs/guide/volumes) with the `volumes` option, then use `ModalFilesystem` to expose a mounted path to the agent's workspace file tools. Files written under the mount persist across sandbox restarts.
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { ModalFilesystem, ModalSandbox } from '@mastra/modal'
+import { ModalClient } from 'modal'
+
+const modal = new ModalClient()
+const privateVolume = await modal.volumes.fromName('agent-user-123', { createIfMissing: true })
+const teamVolume = await modal.volumes.fromName('agent-team', { createIfMissing: true })
+
+const sandbox = new ModalSandbox({
+  id: 'agent-sandbox',
+  workingDirectory: '/workspace',
+  volumes: {
+    '/mnt/agent': privateVolume,
+    '/mnt/team': teamVolume,
+  },
+})
+
+const workspace = new Workspace({
+  sandbox,
+  filesystem: new ModalFilesystem({ sandbox, basePath: '/mnt/agent' }),
+})
+```
+
+`ModalFilesystem` runs file operations inside the sandbox and confines all paths to `basePath`. Set `readOnly: true` to reject writes.
+
+Writes made by other sandboxes to the same Volume are only visible after a reload. Call `reloadVolumes()` on a long-lived sandbox to pick them up:
+
+```typescript
+await sandbox.reloadVolumes()
+```
+
+> **Note:** Keep the working directory outside every Volume mount (for example `/workspace`). Modal can't reload a Volume that is the current working directory, so `ModalSandbox` throws if `workingDirectory` is at or inside a mount path.
+
 ## Background processes
 
 `ModalSandbox` includes a built-in process manager for spawning and managing background processes. Each `spawn()` call creates a new `ContainerProcess` via the Modal SDK's `Sandbox.exec()` API.

package/.docs/models/gateways/netlify.md

@@ -4,7 +4,7 @@
 
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 269 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 270 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -229,6 +229,7 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/openrouter/free`                                          |
 | `openrouter/openrouter/pareto-code`                                   |
 | `openrouter/perceptron/perceptron-mk1`                                |
+| `openrouter/perceptron/perceptron-mk1.5`                              |
 | `openrouter/perplexity/sonar`                                         |
 | `openrouter/perplexity/sonar-deep-research`                           |
 | `openrouter/perplexity/sonar-pro`                                     |
@@ -279,6 +280,7 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/thedrummer/unslopnemo-12b`                                |
 | `openrouter/thinkingmachines/inkling`                                 |
 | `openrouter/thinkingmachines/inkling-small`                           |
+| `openrouter/typesafe/jev-router`                                      |
 | `openrouter/undi95/remm-slerp-l2-13b`                                 |
 | `openrouter/upstage/solar-mini4`                                      |
 | `openrouter/upstage/solar-pro4`                                       |
@@ -302,7 +304,6 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/z-ai/glm-5`                                               |
 | `openrouter/z-ai/glm-5.1`                                             |
 | `openrouter/z-ai/glm-5.2`                                             |
-| `openrouter/z-ai/glm-5.2:free`                                        |
 | `openrouter/z-ai/glm-5.3`                                             |
 | `openrouter/z-ai/glm-5.3-flash`                                       |
 | `typesafe/jev-1.13.0`                                                 |

package/.docs/models/gateways/openrouter.md

@@ -4,7 +4,7 @@
 
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 387 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 384 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -68,7 +68,6 @@ ANTHROPIC_API_KEY=ant-...
 | `amazon/nova-premier-v1`                                   |
 | `amazon/nova-pro-v1`                                       |
 | `anthracite-org/magnum-v4-72b`                             |
-| `anthropic/claude-3-haiku`                                 |
 | `anthropic/claude-fable-5`                                 |
 | `anthropic/claude-fable-5.1`                               |
 | `anthropic/claude-haiku-4.5`                               |
@@ -214,8 +213,6 @@ ANTHROPIC_API_KEY=ant-...
 | `moonshotai/kimi-k3`                                       |
 | `morph/morph-v3-fast`                                      |
 | `morph/morph-v3-large`                                     |
-| `nex-agi/nex-n2.5-mini:free`                               |
-| `nex-agi/nex-n2.5-pro:free`                                |
 | `nousresearch/hermes-3-llama-3.1-405b`                     |
 | `nousresearch/hermes-3-llama-3.1-70b`                      |
 | `nousresearch/hermes-4-405b`                               |
@@ -298,6 +295,7 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/fusion`                                        |
 | `openrouter/pareto-code`                                   |
 | `perceptron/perceptron-mk1`                                |
+| `perceptron/perceptron-mk1.5`                              |
 | `perplexity/sonar`                                         |
 | `perplexity/sonar-deep-research`                           |
 | `perplexity/sonar-pro`                                     |
@@ -419,7 +417,6 @@ ANTHROPIC_API_KEY=ant-...
 | `z-ai/glm-5-turbo`                                         |
 | `z-ai/glm-5.1`                                             |
 | `z-ai/glm-5.2`                                             |
-| `z-ai/glm-5.2:free`                                        |
 | `z-ai/glm-5.3`                                             |
 | `z-ai/glm-5.3-flash`                                       |
 | `z-ai/glm-5.3-flashx`                                      |

package/.docs/models/index.md

@@ -4,7 +4,7 @@
 
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7624 models from 210 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7618 models from 210 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/above.md

@@ -4,7 +4,7 @@
 
 # ![above.dev logo](https://models.dev/logos/above.svg)above.dev
 
-Access 9 above.dev models through Mastra's model router. Authentication is handled automatically using the `ABOVE_API_KEY` environment variable.
+Access 10 above.dev models through Mastra's model router. Authentication is handled automatically using the `ABOVE_API_KEY` environment variable.
 
 Learn more in the [above.dev documentation](https://above.dev/docs).
 
@@ -38,8 +38,8 @@ for await (const chunk of stream) {
 
 | Model                            | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | -------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `above/deepseek-v4-flash`        | 1.0M    |       |           |       |       |       | $0.17      | $0.66       |
 | `above/deepseek-v4-pro`          | 1.0M    |       |           |       |       |       | $0.73      | $2          |
+| `above/deepseek-v4.1-flash`      | 1.0M    |       |           |       |       |       | $0.17      | $0.66       |
 | `above/glm-5.2`                  | 1.0M    |       |           |       |       |       | $2         | $5          |
 | `above/glm-5.2-fast`             | 1.0M    |       |           |       |       |       | $2         | $7          |
 | `above/glm-5.3-flash`            | 1.0M    |       |           |       |       |       | $0.17      | $0.55       |

package/.docs/models/providers/cerebras.md

@@ -37,7 +37,7 @@ for await (const chunk of stream) {
 | Model                   | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | ----------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `cerebras/gpt-oss-120b` | 131K    |       |           |       |       |       | $0.35      | $0.75       |
-| `cerebras/qwen-3.8-27b` | 66K     |       |           |       |       |       | $0.99      | $1          |
+| `cerebras/qwen-3.8-27b` | 131K    |       |           |       |       |       | $0.99      | $1          |
 
 Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.
 

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

@@ -56,7 +56,7 @@ for await (const chunk of stream) {
 | `cortecs/deepseek-v4-flash-0731`              | 1.0M    |       |           |       |       |       | $0.09      | $0.17       |
 | `cortecs/deepseek-v4-pro`                     | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `cortecs/deepseek-v4-pro-0813`                | 1.0M    |       |           |       |       |       | $2         | $4          |
-| `cortecs/deepseek-v4.1-flash`                 | 1.0M    |       |           |       |       |       | $0.50      | $1          |
+| `cortecs/deepseek-v4.1-flash`                 | 1.0M    |       |           |       |       |       | $0.30      | $1          |
 | `cortecs/devstral-2512`                       | 256K    |       |           |       |       |       | $0.48      | $2          |
 | `cortecs/gemini-2.5-flash`                    | 1.0M    |       |           |       |       |       | $0.30      | $2          |
 | `cortecs/gemini-2.5-pro`                      | 1.0M    |       |           |       |       |       | $1         | $10         |
@@ -107,7 +107,7 @@ for await (const chunk of stream) {
 | `cortecs/minimax-m2.1`                        | 196K    |       |           |       |       |       | $0.36      | $1          |
 | `cortecs/minimax-m2.5`                        | 196K    |       |           |       |       |       | $0.30      | $1          |
 | `cortecs/minimax-m2.7`                        | 197K    |       |           |       |       |       | $0.67      | $3          |
-| `cortecs/minimax-m3`                          | 1.0M    |       |           |       |       |       | $0.40      | $2          |
+| `cortecs/minimax-m3`                          | 1.0M    |       |           |       |       |       | $0.30      | $1          |
 | `cortecs/ministral-14b-2512`                  | 256K    |       |           |       |       |       | $0.24      | $0.24       |
 | `cortecs/ministral-3b-2512`                   | 256K    |       |           |       |       |       | $0.12      | $0.12       |
 | `cortecs/ministral-8b-2512`                   | 256K    |       |           |       |       |       | $0.18      | $0.18       |
@@ -142,7 +142,7 @@ for await (const chunk of stream) {
 | `cortecs/qwen3.6-27b`                         | 262K    |       |           |       |       |       | $0.45      | $3          |
 | `cortecs/qwen3.6-35b-a3b`                     | 262K    |       |           |       |       |       | $0.17      | $0.56       |
 | `cortecs/qwen3.8-2.4t-a95b`                   | 262K    |       |           |       |       |       | $3         | $6          |
-| `cortecs/qwen3.8-27b`                         | 262K    |       |           |       |       |       | $0.10      | $0.40       |
+| `cortecs/qwen3.8-27b`                         | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
 | `cortecs/qwen3.8-flash-next`                  | 262K    |       |           |       |       |       | $0.20      | $0.50       |
 | `cortecs/qwen3guard-gen-0.6b`                 | 32K     |       |           |       |       |       | —          | —           |
 | `cortecs/qwen3guard-gen-8b`                   | 32K     |       |           |       |       |       | —          | —           |

package/.docs/models/providers/deepseek.md

@@ -91,8 +91,14 @@ const response = await agent.generate("Hello!", {
 
 ### Available Options
 
-**thinking** (`{ type?: "adaptive" | "enabled" | "disabled" | undefined; } | undefined`)
+**logprobs** (`boolean | undefined`): Whether to return log probabilities for generated tokens.
 
-**reasoningEffort** (`"low" | "medium" | "high" | "xhigh" | "max" | undefined`)
+**topLogprobs** (`number | undefined`): Number of most likely tokens to return at each token position. Setting this option automatically enables logprobs.
 
-**strictJsonSchema** (`boolean | undefined`)
+**userId** (`string | undefined`): An opaque identifier for the end user. DeepSeek uses this identifier for content-safety tracing and request isolation. Must contain only ASCII letters, numbers, underscores, and hyphens, and must be at most 512 characters long.
+
+**strictJsonSchema** (`boolean | undefined`): Whether to use strict JSON schema validation for structured outputs. Only applies when the serving endpoint supports JSON schema response formats (e.g. Azure). Defaults to true.
+
+**thinking** (`{ type?: "enabled" | "disabled" | "adaptive" | undefined; } | undefined`)
+
+**reasoningEffort** (`"low" | "high" | "max" | "medium" | "xhigh" | undefined`)