@mastra/mcp-docs-server 1.3.6 → 1.3.7-alpha.3

package/.docs/docs/agents/guardrails.md

@@ -232,7 +232,7 @@ inputProcessors: [
 
 ## Violation callbacks
 
-All processors support an `onViolation` callback that fires when a policy violation is detected, regardless of strategy. Use it for side effects like alerting, logging to external systems, or sending notifications.
+Processors support an `onViolation` callback that fires when a policy violation aborts the run, for example with the `block` strategy. Aborts from `processToolResult`, and from processor workflows while streaming output, don't call it. Some processors also call it directly: `RegexFilterProcessor` when it redacts content, and `TokenCostControl` when it warns. Strategies that only log, such as `ModerationProcessor`'s `warn`, don't call it. Use it for side effects like alerting, logging to external systems, or sending notifications.
 
 The callback receives a `ProcessorViolation` object with `processorId`, `message`, and `detail` (processor-specific metadata).
 
@@ -263,7 +263,7 @@ moderation.onViolation = ({ processorId, message, detail }) => {
 }
 ```
 
-The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `TokenCostControl`), the callback also fires on warnings without blocking the request.
+The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when a processor calls `abort()`, except on the paths noted above. For processors using a `warn` strategy (like `TokenCostControl`), the callback also fires on warnings without blocking the request.
 
 Errors thrown by runner-invoked callbacks after `abort()` are silently caught to prevent interfering with the processor's main logic. On the `TokenCostControl` warning path, callback errors are caught and logged through the Mastra logger.
 

package/.docs/docs/auth/fga.md

@@ -79,7 +79,6 @@ resourceMapping: {
 - `user`: the authenticated user
 - `resourceId`: the owning Mastra resource ID when available (for example, a thread's `resourceId`)
 - `requestContext`: the current request context for advanced tenant resolution
-- `metadata`: provider-specific metadata for the attempted action
 
 Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
 

package/.docs/docs/deployment/workers.md

@@ -146,7 +146,7 @@ Workers are internal infrastructure. They're not exposed to end users and don't
 In a split deployment:
 
 - **The API server is the only public-facing process**: It serves all client HTTP requests. These requests include REST endpoints and agent interactions, plus workflow triggers and custom routes.
-- **Workers connect outbound only**: They pull events from the distributed PubSub backend and read/write to the shared storage database. They don't accept inbound traffic from clients.
+- **Workers don't serve client traffic**: They pull events from the distributed PubSub backend and read/write to the shared storage database. Each worker process also listens on `PORT` (default `4111`) for internal health checks. `/health` reports readiness and `/config` returns the worker configuration to authorized callers. Keep this port on the private network.
 - **The orchestration worker calls the API internally**: It sends step execution requests to the API over the container network using `MASTRA_STEP_EXECUTION_URL`. This is internal service-to-service communication, not a public endpoint.
 
 All three worker types (orchestration, scheduler, background task) sit behind the API on a private network. They share access to the PubSub backend and storage database but never receive traffic directly from clients. HTTP routes for worker-related features run on the API server rather than the worker process. One example is creating a token for a voice integration.

package/.docs/docs/evals/datasets.md

@@ -219,7 +219,7 @@ MongoDB storage requires a replica set or sharded deployment with transaction su
 
 ## Listing and searching items
 
-[`listItems()`](https://mastra.ai/reference/datasets/listItems) supports pagination and full-text search:
+[`listItems()`](https://mastra.ai/reference/datasets/listItems) supports pagination and case-insensitive substring search:
 
 ```typescript
 // Paginated list
@@ -228,7 +228,7 @@ const { items, pagination } = await dataset.listItems({
   perPage: 50,
 })
 
-// Full-text search
+// Substring search
 const { items: matches } = await dataset.listItems({
   search: 'Hello',
 })
@@ -240,11 +240,10 @@ const { items: v2Matches } = await dataset.listItems({
   page: 0,
   perPage: 50,
 })
-
-// Version-only snapshot returns a bare DatasetItem[]
-const v2Items = await dataset.listItems({ version: 2 })
 ```
 
+Calling `listItems({ version })` without `search`, `page`, or `perPage` returns a bare `DatasetItem[]`. This form is deprecated. Pass `page` and `perPage` to always receive the paginated shape.
+
 ## Versioning
 
 Adding, updating, or deleting dataset items bumps the dataset version. Purging an item's stored content with [`purgeItem()`](https://mastra.ai/reference/datasets/purgeItem) doesn't create a new version. This lets you pin experiments to a specific snapshot of the data while erasing sensitive content without changing the version history.
@@ -278,7 +277,7 @@ for (const row of history) {
 Fetch the exact items that existed at a past version:
 
 ```typescript
-const items = await dataset.listItems({ version: 2 })
+const { items } = await dataset.listItems({ version: 2, page: 0, perPage: 100 })
 ```
 
 You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.

package/.docs/docs/evals/gates-and-verdicts.md

@@ -4,7 +4,7 @@
 
 # Gates and verdicts
 
-Gates and verdicts add severity semantics to `runEvals`. Gates are scorers that must score 1.0, hard requirements that block a run. Thresholds are minimum acceptable scores on tracked metrics. The verdict summarizes the outcome as `passed`, `scored`, or `failed`.
+Gates and verdicts add severity semantics to `runEvals`. Gates are scorers that must score 1.0, hard requirements that block a run. Thresholds are lower and/or upper bounds on the average score of tracked metrics. The verdict summarizes the outcome as `passed`, `scored`, or `failed`.
 
 ## When to use gates and verdicts
 
@@ -50,7 +50,7 @@ The verdict field is omitted when no gates or threshold-bearing scorers are prov
 
 ## Gates
 
-Gates are scorers passed via the `gates` field. They run before regular scorers on each data item. A gate must average a score of 1.0 across all data items to pass.
+Gates are scorers passed via the `gates` field. They run before regular scorers on each data item. A gate must average a score of 1.0 across the data items it could score to pass. Items where the gate returns `notScorable()` are excluded from the average, and a gate that throws an error counts as 0 for that item.
 
 ```typescript
 import { runEvals } from '@mastra/core/evals'
@@ -87,7 +87,7 @@ You must provide at least one scorer or gate, a run with neither throws an error
 
 ## Thresholds
 
-Wrap a scorer in `{ scorer, threshold }` to set pass/fail bounds. The threshold is compared against the scorer's average score across all data items.
+Wrap a scorer in `{ scorer, threshold }` to set pass/fail bounds. The threshold is compared against the scorer's average score across scored data items. Results that return `notScorable()` are left out of the average.
 
 A `threshold` can be:
 

package/.docs/docs/mastra-platform/deploy.md

@@ -63,7 +63,14 @@ A local `.env` file is optional. Environment variables stored on the platform ar
    > })
    > ```
 
-   If the build statically finds `backgroundTasks.enabled: true`, the deploy artifact includes a worker manifest. Mastra Cloud automatically provisions or updates a dedicated worker service from the same artifact. No separate toggle or add-on is required.
+   If the build statically finds `backgroundTasks.enabled: true`, the CLI decides whether to run background tasks on a dedicated worker service or in-process inside the API server container:
+
+   - A dedicated worker service requires Redis for coordination. Without a usable `REDIS_URL` in the deploy env, background tasks run in-process.
+   - With Redis available, the CLI uses a dedicated worker service when the environment already has one, when you pass `--yes`, or when the deploy runs headless. Otherwise it asks whether to provision one.
+   - Pass `--workers dedicated` or `--workers in-process` to skip the decision. `--workers dedicated` fails if `REDIS_URL` is missing.
+   - Dedicated worker services are rolling out gradually, so for organizations without access the CLI omits the worker manifest and background tasks run in-process, even with Redis and `--workers dedicated`.
+
+   When a dedicated worker service is chosen, the deploy artifact includes a worker manifest, and Mastra Cloud provisions or updates the worker service from the same artifact.
 
    Removing `backgroundTasks` or setting `enabled: false` in a later deploy removes the manifest and spins down the existing worker service. Values that can't be determined statically are omitted from the manifest display, but the worker process still reads the complete configuration from your bundled code.
 

package/.docs/docs/mastra-platform/system-environment-variables.md

@@ -37,7 +37,7 @@ Attaching a hosted database adds its connection variables to the environments th
 | -------- | ---------------------------------------- |
 | Turso    | `TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN` |
 | Neon     | `DATABASE_URL`                           |
-| Postgres | `POSTGRES_URL`                           |
+| Postgres | `DATABASE_URL`                           |
 
 Values are resolved at deploy time and never stored in your project. An environment-scoped database replaces the values of a project-scoped database of the same provider for that environment.
 

package/.docs/docs/mastra-platform/trace-intelligence.md

@@ -83,7 +83,7 @@ Entities appear while their signals are still collecting or processing. The inde
 
 ### Configure a custom signal
 
-Users with project management permission can configure custom signals without leaving Intelligence:
+Organization admins can configure custom signals without leaving Intelligence:
 
 1. Return to the entity index and select **Signal settings**.
 2. Select **Create signal**, provide a stable signal name, display label, description, and signal instructions, then save it. Definitions and their versions are shared across the organization.

package/.docs/docs/mastra-platform/workspaces.md

@@ -82,8 +82,8 @@ export const mastra = new Mastra({
 
 - `start()` provisions a fresh sandbox (or reattaches when you passed `sandboxId`).
 - `executeCommand()` runs commands against it.
-- `stop()` tears down the remote sandbox while preserving its recovery checkpoint when it has one.
-- `destroy()` also releases the recovery checkpoint associated with a caller-supplied recovery `id`.
+- `stop()` releases this process's lease without touching the remote sandbox. The VM keeps running under the environment's idle policy, and a later `start()` with the same `id` or `sandboxId` reattaches to it.
+- `destroy()` releases the VM. On Railway, it also deletes the recovery checkpoint associated with a caller-supplied recovery `id`. On E2B, it only kills the VM, and any snapshot you captured remains yours to manage.
 
 A statically configured `PlatformSandbox` is shared across every request and agent using that configuration rather than creating separate sandboxes for requests or memory threads. `PlatformFilesystem` is also a separate provider: configuring both providers doesn't mount the environment bucket inside the sandbox.
 

package/.docs/docs/memory/multi-user-threads.md

@@ -158,7 +158,7 @@ const memory = new Memory({
 })
 ```
 
-OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, or `@mastra/oracledb`.
+OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, `@mastra/mongodb`, `@mastra/mysql`, `@mastra/convex`, or `@mastra/oracledb`.
 
 > **Note:** If you switch the Observer to a less capable model and see facts attributed to a generic `User` instead of individual participants, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to explain how to interpret the `<turn>` tag.
 

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

@@ -468,7 +468,7 @@ With default settings, the context window doesn't grow unbounded. It oscillates
 3. **Repeat**: History grows from \~6k back toward 30k and shrinks again. Each cycle appends to the observation log, which grows much more slowly than raw history.
 4. **Observations reach 40k**: The Reflector creates a smaller log from the current observations and any earlier reflections.
 
-In the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens. The observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps, so history can grow past the threshold whenever background buffering doesn't keep pace. Above `blockAfter` (default `1.2`, \~36k tokens) activation is allowed to overshoot the retention target instead of activating fewer chunks. It doesn't drain the buffer, and with the default settings it removes the same amount of history as below the threshold. Reflection falls back to a synchronous run above its own `blockAfter` (\~48k tokens).
+In the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens. The observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps, so history can grow past the threshold whenever background buffering doesn't keep pace. Between the threshold and `blockAfter` (default `1.2`, \~36k tokens), buffering keeps running in the background and the next ready chunk activates without blocking the agent. At `blockAfter`, a synchronous observation runs if no buffered chunk activates. Reflection falls back to a synchronous run above its own `blockAfter` (\~48k tokens).
 
 With [`shareTokenBudget`](https://mastra.ai/reference/memory/observational-memory) enabled, the two budgets pool together. While the observation log is small, message history can expand into the unused observation space (up to \~70k tokens with the defaults) before observation triggers. It then shrinks as observations accumulate.
 
@@ -796,23 +796,25 @@ When message tokens reach the `messageTokens` threshold, buffered chunks activat
 
 Async buffered Observer calls don't generate continuation hints because delayed hints can be stale by activation time. When buffered chunks activate, any previously stored suggested response and current task are cleared. The main agent receives the compressed observations without those hints.
 
-When message production outpaces the Observer, the `blockAfter` safety threshold allows activation to overshoot the retention target instead of using fewer chunks. Activation still uses no more chunks than needed to reach the target, and the default settings remain unaffected. A synchronous observation runs when the `messageTokens` threshold is reached and activating buffered chunks doesn't bring pending tokens back under it. For example, this happens when a large tool result arrives after buffering has stopped. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
+When message production outpaces the Observer, history can pass `messageTokens` before a buffered chunk is ready. Between `messageTokens` and `blockAfter`, Mastra keeps buffering in the background and activates the chunk on a later step, so the agent doesn't wait on the Observer. A synchronous observation runs if pending tokens still reach `blockAfter` after buffered activation, for example when a large tool result leaves an uncovered tail. Above `blockAfter`, activation may also overshoot the retention target instead of using fewer chunks. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
+
+At `blockAfter`, activation waits a bounded time for a buffered observation that's still being produced so it activates with the rest. If that takes longer, Mastra observes the remaining messages synchronously. A late observation whose messages are all already observed is then dropped instead of stored. Activations triggered by the idle TTL or a model change don't wait.
 
 Reflection works similarly: the Reflector runs in the background when observations reach a fraction of the reflection threshold.
 
 ### Settings
 
-| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                                                                                 |
-| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                                |
-| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                            |
-| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`. For example, `1.2` creates a threshold of 36k tokens (1.2 × 30k), above which activation may overshoot the retention target rather than use fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
-| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, `"auto"` for a provider-aware prompt cache TTL, or an object of per-provider TTLs such as `{ default: 'auto', anthropic: '1h' }`.                     |
-| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                             |
-| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                             |
-| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                                         |
-| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                                                                       |
-| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate.                                                                                                                                                       |
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                                                                                                                                                                                                    |
+| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                                                                                                                                                                                                |
+| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`. For example, `1.2` creates a threshold of 36k tokens (1.2 × 30k). Below it, only background buffering and activation run. Observation runs synchronously if pending tokens still reach it after buffered activation. Activation may also overshoot the retention target. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. Set `1` to observe synchronously at `messageTokens`. |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, `"auto"` for a provider-aware prompt cache TTL, or an object of per-provider TTLs such as `{ default: 'auto', anthropic: '1h' }`.                                                                                                                                                                                         |
+| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                                                                                                                                                                                                 |
+| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate.                                                                                                                                                                                                                                                                                                                           |
 
 If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a specific cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
 
@@ -909,9 +911,9 @@ const memory = new Memory({
 })
 ```
 
-- `previousObserverTokens: 2000` → default. Keeps \~2k tokens of recent observations.
+- `previousObserverTokens: false` → default. Sends the full previous observations.
+- `previousObserverTokens: 2000` → keeps \~2k tokens of recent observations.
 - `previousObserverTokens: 0` → omit previous observations completely.
-- `previousObserverTokens: false` → disable truncation and keep full previous observations.
 
 ## Hooks
 

package/.docs/docs/observability/metrics/overview.md

@@ -10,7 +10,7 @@ Mastra emits:
 
 - **Duration metrics** for agent runs, workflows, tools, model calls, and processors
 - **Token usage metrics** for model input and output, including detailed token categories when the provider reports them
-- **Cost estimates** calculated from token usage, provider, model, and an embedded pricing registry
+- **Cost estimates** calculated from token usage, provider, model, and model prices from [models.dev](https://models.dev)
 
 Metrics retain trace correlation context, so you can investigate a change in a chart by finding the related span. See the [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics) for metric names, labels, and cost fields.
 

package/.docs/docs/observability/tracing/overview.md

@@ -919,6 +919,12 @@ app.post('/api/analyze', async (req, res) => {
 
 This creates a single distributed trace that includes both the HTTP request handling and the Mastra agent execution, viewable in your observability platform of choice.
 
+### MCP calls
+
+Model Context Protocol (MCP) calls link the caller's trace and the server's trace without any setup. When an agent or workflow calls a tool through `MCPClient`, the `MCPServer` that handles it keeps its own trace and records a link to the tool call span, and the tool call span links back to the server's span. Each side keeps its own trace, root span, and trace summary. When the server uses a tracing bridge and its HTTP instrumentation continues the caller's trace, the request joins that trace instead. Mastra storage saves the links with the spans, and exporters with span link support send them too.
+
+This also works with non-Mastra software on either side. See the [`MCPServer` reference](https://mastra.ai/reference/tools/mcp-server) for details, and the [`MCPClient` reference](https://mastra.ai/reference/tools/mcp-client) to send your own trace context.
+
 ## What gets traced
 
 Mastra automatically creates spans for:

package/.docs/docs/sandbox/computer.md

@@ -10,19 +10,19 @@ Sandboxes that run a desktop environment can expose screenshot, mouse, and keybo
 
 ## Computer tools
 
-| Tool                       | Does                                                                             |
-| -------------------------- | -------------------------------------------------------------------------------- |
-| `computer_screenshot`      | Captures the desktop as a PNG image and returns it to the model as native media. |
-| `computer_click`           | Presses and releases the left mouse button at pixel coordinates.                 |
-| `computer_double_click`    | Presses the left mouse button twice at pixel coordinates.                        |
-| `computer_right_click`     | Presses and releases the right mouse button at pixel coordinates.                |
-| `computer_move_mouse`      | Moves the cursor to pixel coordinates without pressing a button.                 |
-| `computer_drag`            | Presses, drags, and releases between two points.                                 |
-| `computer_type`            | Types text into the focused element.                                             |
-| `computer_press_key`       | Presses a key or key combination, such as `Enter` or `ctrl+s`.                   |
-| `computer_scroll`          | Scrolls up or down.                                                              |
-| `computer_get_screen_info` | Gets the screen dimensions and cursor position.                                  |
-| `computer_wait`            | Waits for the interface to settle.                                               |
+| Tool                                        | Does                                                                             |
+| ------------------------------------------- | -------------------------------------------------------------------------------- |
+| `mastra_workspace_computer_screenshot`      | Captures the desktop as a PNG image and returns it to the model as native media. |
+| `mastra_workspace_computer_click`           | Presses and releases the left mouse button at pixel coordinates.                 |
+| `mastra_workspace_computer_double_click`    | Presses the left mouse button twice at pixel coordinates.                        |
+| `mastra_workspace_computer_right_click`     | Presses and releases the right mouse button at pixel coordinates.                |
+| `mastra_workspace_computer_move_mouse`      | Moves the cursor to pixel coordinates without pressing a button.                 |
+| `mastra_workspace_computer_drag`            | Presses, drags, and releases between two points.                                 |
+| `mastra_workspace_computer_type`            | Types text into the focused element.                                             |
+| `mastra_workspace_computer_press_key`       | Presses a key or key combination, such as `Enter` or `ctrl+s`.                   |
+| `mastra_workspace_computer_scroll`          | Scrolls up or down.                                                              |
+| `mastra_workspace_computer_get_screen_info` | Gets the screen dimensions and cursor position.                                  |
+| `mastra_workspace_computer_wait`            | Waits for the interface to settle.                                               |
 
 ## Configure computer tools
 

package/.docs/docs/sandbox/overview.md

@@ -49,11 +49,11 @@ A static sandbox is shared across every request and memory thread that uses the
 
 Agents receive tools for the capabilities supported by the sandbox backend:
 
-| Tool                 | Does                                                                                                                                                                                                                                    |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `execute_command`    | Runs a shell command and returns stdout, stderr, and the exit code. Supports `background: true` when the backend can spawn long-running processes.                                                                                      |
-| `get_process_output` | Gets stdout, stderr, and status for a background process. Supports `tail` to limit output and `wait: true` to wait for the process to exit. This tool and `kill_process` are only added when the backend supports background processes. |
-| `kill_process`       | Stops a background process and returns its recent output.                                                                                                                                                                               |
+| Tool                 | Does                                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `execute_command`    | Runs a shell command and returns stdout, stderr, and the exit code. Supports `background: true` when the backend can spawn long-running processes.                                                                                                                                                                                                                                                       |
+| `get_process_output` | Gets stdout, stderr, and status for a background process. Supports `tail` to limit output and `wait: true` to wait for the process to exit. For a static sandbox, this tool and `kill_process` are only added when the backend supports background processes. Workspaces that resolve their sandbox per request always include both tools, because capabilities aren't known until the sandbox resolves. |
+| `kill_process`       | Stops a background process and returns its recent output.                                                                                                                                                                                                                                                                                                                                                |
 
 Configured capabilities determine which tools are available. Tool configuration can then disable, rename, or add policies to those tools:
 

package/.docs/docs/server/custom-adapters.md

@@ -162,7 +162,7 @@ async getParams(
   request: MyRequest
 ): Promise<{
   urlParams: Record<string, string>;
-  queryParams: Record<string, string>;
+  queryParams: Record<string, string | string[]>; // repeated keys (?tag=a&tag=b) become arrays
   body: unknown;
 }> {
   return {

package/.docs/docs/server/server-adapters.md

@@ -823,7 +823,7 @@ When using adapters, configure these features directly with your framework. For
 
 Server adapters register MCP (Model Context Protocol) routes during `registerRoutes()` when MCP servers are configured in your Mastra instance. MCP allows external tools and services to connect to your Mastra server and interact with your agents.
 
-Each server is exposed at `/api/mcp/:serverId/mcp` over Streamable HTTP. Because every request is self-contained, the routes work unchanged in serverless environments like Cloudflare Workers or Vercel Edge.
+Each server is exposed at `/api/mcp/:serverId/mcp` over Streamable HTTP. By default the transport keeps session state between requests. For serverless environments like Cloudflare Workers or Vercel Edge, set `mcpOptions: { serverless: true }` to run in stateless mode without session management.
 
 Pass `mcpOptions` to control how the authenticated principal reaches tools. When using the Mastra deployer (the standard `mastra dev` / `mastra build` path), set it in your server config:
 

package/.docs/docs/studio/auth.md

@@ -124,7 +124,7 @@ Permissions follow the pattern `{resource}:{action}`, with optional resource-lev
 | `agents:execute`    | Execute agents only         |
 | `agents:read:my-id` | Read a specific agent by ID |
 
-Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, and others. Actions are `read`, `write`, `execute`, and `delete`.
+Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, and others. Actions are `read`, `write`, `create`, `delete`, `execute`, `publish`, and `share`.
 
 ### Map external provider roles
 

package/.docs/docs/workflows/control-flow.md

@@ -519,6 +519,34 @@ export const testWorkflow = createWorkflow({})
   .commit();
 ```
 
+### Passing data between iterations
+
+Each iteration of `.dountil()` or `.dowhile()` receives the previous iteration's output as its `inputData`. When input validation is enabled (the default), that output is validated against the loop body's `inputSchema` before the body runs. With an object schema such as `z.object()`, keys the schema doesn't declare are removed. Schemas that allow unknown keys, such as `.passthrough()`, keep them.
+
+When the loop body is a nested workflow, the output is validated against the nested workflow's `inputSchema` and then against its first step's `inputSchema`. A value is only available on the next iteration if the nested workflow returns it and both schemas declare it. This includes values produced inside the nested workflow, such as feedback from a step that suspended and resumed.
+
+To carry data across iterations, declare it in the body's `inputSchema` and return it from the body's last step:
+
+```typescript
+const loopSchema = z.object({
+  draft: z.string(),
+  feedback: z.string().optional(),
+  attempts: z.number(),
+})
+
+const reviewStep = createStep({
+  id: 'review',
+  inputSchema: loopSchema,
+  outputSchema: loopSchema,
+  execute: async ({ inputData }) => {
+    // ...
+    return { draft, feedback, attempts: inputData.attempts + 1 }
+  },
+})
+```
+
+For values that don't belong in the step's input, such as counters or audit data, use [workflow state](https://mastra.ai/docs/workflows/workflow-state) instead.
+
 ### Looping with `.foreach()`
 
 Use `.foreach()` to run the same step for each item in an array. The input must be of type `array` so the loop can iterate over its values, applying the step's logic to each one. See [Choosing the right pattern](#choosing-the-right-pattern) for guidance on when to use `.foreach()` vs other methods.

package/.docs/docs/workflows/time-travel.md

@@ -197,7 +197,7 @@ const result = await run.timeTravel({
 
 ## Error handling
 
-Time travel throws errors in specific situations:
+Time travel throws errors in specific situations. It rejects a call that observes a running snapshot, but it doesn't atomically claim the run. Concurrent calls can both pass the status check and proceed, so guard against duplicates in your application. See [Concurrent time travel calls](https://mastra.ai/reference/workflows/run-methods/timeTravel).
 
 ### Running workflow
 

package/.docs/integrations/databases/clickhouse.md

@@ -232,6 +232,19 @@ The same `client` form is accepted by `ObservabilityStorageClickhouse` and `Obse
 
 `ClickhouseStore` also accepts every option from `ClickHouseClientConfigOptions` (such as `database`, `request_timeout`, `compression`, `keep_alive`, and `max_open_connections`).
 
+`ClickhouseStore` and `ObservabilityStorageClickhouseVNext` apply `clickhouse_settings` to every query they run. On ClickHouse services that keep data in object storage, such as ClickHouse Cloud, limiting read-ahead lowers the memory each observability query uses, but queries that miss the local cache can run slower:
+
+```typescript
+const observabilityStore = new ObservabilityStorageClickhouseVNext({
+  url: process.env.CLICKHOUSE_URL!,
+  username: process.env.CLICKHOUSE_USERNAME!,
+  password: process.env.CLICKHOUSE_PASSWORD!,
+  clickhouse_settings: {
+    filesystem_prefetches_limit: 8,
+  },
+})
+```
+
 ### Replicated clusters
 
 Use `replication` when Mastra writes to a multi-replica ClickHouse cluster through a load balancer.

package/.docs/integrations/observability/langfuse.md

@@ -199,6 +199,14 @@ If you set a custom `traceName` via `mastra.metadata.traceName`, your value take
 
 A run started with `tracingOptions.nestUnderParent` doesn't own the trace, so the exporter doesn't write the trace name, input, output, metadata, user, or session from it. See [Nesting a run under an earlier Mastra run](https://mastra.ai/docs/observability/tracing/overview).
 
+## Filtering observations by span attributes
+
+Observation-level evaluators in Langfuse filter on top-level observation metadata. The exporter promotes each scalar span attribute (string, number, or boolean) that the OpenTelemetry exporter writes as `mastra.<span_type>.<key>` to `langfuse.observation.metadata.<key>`, with the key converted to camelCase. The exporter also sets `agentId`, `agentName`, `spanType`, and `operationName` on each observation.
+
+For a `MODEL_STEP` span this produces `stepIndex` and `isContinued`. To judge each agent run once, against the step that produced the final answer, filter an observation-level evaluator on `spanType` equals `model_step` and `isContinued` equals `"false"`.
+
+Values are sent as strings, so compare against string values such as `"false"` or `"1"`. Span input and output keep their own mapping, and attributes that hold objects or arrays stay in the nested `attributes` metadata only.
+
 ## Custom trace metadata
 
 Langfuse filters and groups traces by top-level metadata only. Nested metadata keys can't be used for filtering or grouping.

package/.docs/integrations/observability/opentelemetry.md

@@ -838,6 +838,8 @@ Both services must have:
 2. W3C Trace Context propagator enabled
 3. Mastra with `OtelBridge` configured
 
+A Mastra `MCPServer` request over HTTP follows the same rule. With this setup, it joins the caller's trace. Without HTTP instrumentation on the server, each request keeps its own trace. In both cases, when a request carries a W3C `traceparent`, in `_meta` or as an HTTP header, the request span links to the caller's span, and the exporter and the bridge send that link as an OpenTelemetry span link. See [Linking to the caller's trace](https://mastra.ai/reference/tools/mcp-server).
+
 ### Using tags
 
 Tags help you categorize and filter traces in your OTEL backend. Add tags when executing agents or workflows:

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

@@ -4,7 +4,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 409 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 402 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -42,23 +42,16 @@ ANTHROPIC_API_KEY=ant-...
 | `alibaba/qwen-3-235b`                      |
 | `alibaba/qwen-3-30b`                       |
 | `alibaba/qwen-3-32b`                       |
-| `alibaba/qwen-3.6-max-preview`             |
-| `alibaba/qwen3-235b-a22b-thinking`         |
 | `alibaba/qwen3-coder`                      |
 | `alibaba/qwen3-coder-30b-a3b`              |
 | `alibaba/qwen3-coder-next`                 |
-| `alibaba/qwen3-coder-plus`                 |
 | `alibaba/qwen3-embedding-0.6b`             |
 | `alibaba/qwen3-embedding-4b`               |
 | `alibaba/qwen3-embedding-8b`               |
-| `alibaba/qwen3-max`                        |
-| `alibaba/qwen3-max-preview`                |
 | `alibaba/qwen3-max-thinking`               |
 | `alibaba/qwen3-next-80b-a3b-instruct`      |
 | `alibaba/qwen3-next-80b-a3b-thinking`      |
-| `alibaba/qwen3-vl-235b-a22b-instruct`      |
 | `alibaba/qwen3-vl-instruct`                |
-| `alibaba/qwen3-vl-thinking`                |
 | `alibaba/qwen3.5-flash`                    |
 | `alibaba/qwen3.5-plus`                     |
 | `alibaba/qwen3.6-27b`                      |

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 7822 models from 214 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 7820 models from 214 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/edenai.md

@@ -4,7 +4,7 @@
 
 # ![Eden AI logo](https://models.dev/logos/edenai.svg)Eden AI
 
-Access 302 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
+Access 303 Eden AI models through Mastra's model router. Authentication is handled automatically using the `EDENAI_API_KEY` environment variable.
 
 Learn more in the [Eden AI documentation](https://docs.edenai.co).
 
@@ -152,10 +152,11 @@ for await (const chunk of stream) {
 | `edenai/fireworks_ai/accounts/fireworks/models/gpt-oss-120b`  | 131K    |       |           |       |       |       | $0.15      | $0.60       |
 | `edenai/fireworks_ai/accounts/fireworks/models/inkling`       | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `edenai/fireworks_ai/gpt-oss-120b`                            | 131K    |       |           |       |       |       | $0.15      | $0.60       |
-| `edenai/flexai/DeepSeek-V4-Flash-0731`                        | 1.0M    |       |           |       |       |       | $0.06      | $0.18       |
-| `edenai/flexai/DeepSeek-V4.1-Flash`                           | 1.0M    |       |           |       |       |       | $0.14      | $0.42       |
+| `edenai/flexai/DeepSeek-V4-Flash-0731`                        | 1.0M    |       |           |       |       |       | $0.02      | $0.27       |
+| `edenai/flexai/DeepSeek-V4.1-Flash`                           | 1.0M    |       |           |       |       |       | $0.09      | $0.18       |
 | `edenai/flexai/gpt-oss-120b`                                  | 131K    |       |           |       |       |       | $0.03      | $0.17       |
 | `edenai/flexai/gpt-oss-20b`                                   | 131K    |       |           |       |       |       | $0.02      | $0.10       |
+| `edenai/flexai/Muse-Glimmer-30B`                              | 131K    |       |           |       |       |       | $0.35      | $2          |
 | `edenai/flexai/Step-3.7-Flash`                                | 262K    |       |           |       |       |       | $0.20      | $1          |
 | `edenai/google/deep-research-max-preview-04-2026`             | 1.0M    |       |           |       |       |       | $2         | $12         |
 | `edenai/google/deep-research-preview-04-2026`                 | 1.0M    |       |           |       |       |       | $2         | $12         |

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

@@ -42,20 +42,20 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                           | 1.0M    |       |           |       |       |       | $0.10      | $0.50       |
 | `kilo/~anthropic/claude-opus-latest`                            | 1.0M    |       |           |       |       |       | $4         | $20         |
 | `kilo/~anthropic/claude-sonnet-latest`                          | 1.0M    |       |           |       |       |       | $2         | $10         |
-| `kilo/~deepseek/deepseek-flash-latest`                          | 1.0M    |       |           |       |       |       | $0.03      | $0.14       |
-| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.22      | $0.66       |
-| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.02      | $0.64       |
+| `kilo/~deepseek/deepseek-flash-latest`                          | 1.0M    |       |           |       |       |       | $0.03      | $1          |
+| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.25      | $5          |
+| `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.01      | $0.77       |
 | `kilo/~google/gemini-flash-latest`                              | 1.0M    |       |           |       |       |       | $0.75      | $4          |
 | `kilo/~google/gemini-pro-latest`                                | 1.0M    |       |           |       |       |       | $2         | $12         |
-| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $0.75      | $15         |
+| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $0.72      | $24         |
 | `kilo/~openai/gpt-astra-latest`                                 | 1.1M    |       |           |       |       |       | $10        | $50         |
 | `kilo/~openai/gpt-luna-latest`                                  | 1.1M    |       |           |       |       |       | $0.10      | $0.50       |
 | `kilo/~openai/gpt-mini-latest`                                  | 400K    |       |           |       |       |       | $0.75      | $5          |
 | `kilo/~openai/gpt-sol-latest`                                   | 1.1M    |       |           |       |       |       | $2         | $10         |
 | `kilo/~openai/gpt-terra-latest`                                 | 1.1M    |       |           |       |       |       | $2         | $12         |
 | `kilo/~x-ai/grok-latest`                                        | 500K    |       |           |       |       |       | $2         | $6          |
-| `kilo/~z-ai/glm-flash-latest`                                   | 1.0M    |       |           |       |       |       | $0.04      | $0.50       |
-| `kilo/~z-ai/glm-latest`                                         | 1.0M    |       |           |       |       |       | $0.07      | $5          |
+| `kilo/~z-ai/glm-flash-latest`                                   | 1.0M    |       |           |       |       |       | $0.02      | $1          |
+| `kilo/~z-ai/glm-latest`                                         | 1.0M    |       |           |       |       |       | $0.06      | $5          |
 | `kilo/aion-labs/aion-2.0`                                       | 131K    |       |           |       |       |       | $0.80      | $2          |
 | `kilo/aion-labs/aion-3.0`                                       | 131K    |       |           |       |       |       | $3         | $6          |
 | `kilo/aion-labs/aion-3.0-mini`                                  | 131K    |       |           |       |       |       | $0.70      | $1          |

package/.docs/models/providers/llmgateway-providers.md

@@ -4,7 +4,7 @@
 
 # ![LLM Gateway logo](https://models.dev/logos/llmgateway-providers.svg)LLM Gateway
 
-Access 446 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
+Access 445 LLM Gateway models through Mastra's model router. Authentication is handled automatically using the `LLMGATEWAY_API_KEY` environment variable.
 
 Learn more in the [LLM Gateway documentation](https://llmgateway.io/docs).
 
@@ -202,7 +202,6 @@ for await (const chunk of stream) {
 | `llmgateway-providers/deepinfra/qwen3-vl-235b-a22b-instruct`        | 262K    |       |           |       |       |       | $0.20      | $0.88       |
 | `llmgateway-providers/deepinfra/qwen3-vl-30b-a3b-instruct`          | 262K    |       |           |       |       |       | $0.15      | $0.60       |
 | `llmgateway-providers/deepinfra/qwen3.5-9b`                         | 262K    |       |           |       |       |       | $0.10      | $0.15       |
-| `llmgateway-providers/deepinfra/qwen3.8-2.4t-a95b`                  | 262K    |       |           |       |       |       | $2         | $6          |
 | `llmgateway-providers/deepseek/deepseek-v4-pro`                     | 1.1M    |       |           |       |       |       | $0.43      | $0.87       |
 | `llmgateway-providers/deepseek/deepseek-v4.1-flash`                 | 1.1M    |       |           |       |       |       | $0.15      | $0.60       |
 | `llmgateway-providers/embercloud/glm-4.5`                           | 131K    |       |           |       |       |       | $0.60      | $2          |