@mastra/mcp-docs-server 1.3.1 → 1.3.2-alpha.3

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

@@ -163,15 +163,29 @@ Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/
 Durable agents support resumable streams through PubSub and an event cache. When a client disconnects mid-stream, the cache continues storing events. The same client can reconnect by calling `observe()` with the `runId`:
 
 ```typescript
-const { output, cleanup } = await durableResearcher.observe(runId)
+const { output } = await durableResearcher.observe(runId)
 
 for await (const chunk of output.fullStream) {
   // Chunks from the run, including any missed while disconnected
 }
+```
 
-cleanup()
+Observing doesn't own the run. When the loop ends, or you leave it early with `break`, `return`, or an error, the observer unsubscribes and the run keeps going for anyone else watching it. To stop observing from outside the loop, for example when the client disconnects, call `detach()`:
+
+```typescript
+const { output, detach } = await durableResearcher.observe(runId)
+
+request.signal.addEventListener('abort', detach, { once: true })
+
+if (request.signal.aborted) detach()
+
+for await (const chunk of output.fullStream) {
+  // Stops when the run finishes or the client disconnects
+}
 ```
 
+If you pass `idleTimeoutMs` and no chunks arrive for that long, Mastra checks `isAlive` when you provide it. If `isAlive` returns `true` or throws, the timer restarts and the stream stays open. Otherwise the stream ends with an error chunk and detaches the observer. The run itself is only cleaned up when `isAlive` returns `false`.
+
 `createDurableAgent()` and `createEventedAgent()` use an in-memory cache by default, which means resumable streams work within a single process. For production, provide a persistent cache backend (e.g., Redis) so cached events survive process restarts:
 
 ```typescript
@@ -231,7 +245,11 @@ Visit [Background tasks](https://mastra.ai/docs/harness/background-tasks) for th
 
 ## Cleanup
 
-Every `stream()` and `observe()` call returns a `cleanup` function. Calling it unsubscribes from PubSub and removes the run from the internal registry. If you forget to call it, an automatic timer fires after the stream ends, but calling `cleanup()` yourself frees resources immediately.
+Every `stream()` and `observe()` call returns a `cleanup` function that tears the run down: it unsubscribes from PubSub, removes the run from the internal registry, and deletes the run's cached events so nobody can replay it afterward.
+
+When you don't call `cleanup()` yourself, Mastra calls it `cleanupTimeoutMs` after the run finishes, errors, or is aborted. Detaching an observer or reaching a plain `idleTimeoutMs` doesn't start this timer. Set `cleanupTimeoutMs: 0` to turn the timer off.
+
+Call `cleanup()` from the process that started the run. To stop watching a run from `observe()`, use `detach()` or leave the loop instead.
 
 ## Tool approval
 

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

@@ -615,29 +615,42 @@ const memory = new Memory({
 
 Thread scope requires a valid `threadId` to be provided when calling the agent. If `threadId` is missing, Observational Memory throws an error. This prevents multiple threads from silently sharing a single observation record, which can cause database deadlocks.
 
-### Resource scope (experimental)
+### Resource scope (deprecated)
 
-Observations are shared across all threads for a resource (typically a user). Enables cross-conversation memory.
+> **Deprecated:** `scope: 'resource'` is deprecated and will be removed in a future release. Mastra logs a warning the first time Observational Memory is created with resource scope. Remove the `scope` option to use the default thread scope, and use the [alternatives below](#cross-thread-continuity-without-resource-scope) for cross-conversation continuity.
+
+In resource scope, observations are shared across all threads for a resource (typically a user). Resource scope works much worse than thread scope for prompt caching and for the agent's understanding of the conversation:
+
+- **Prompt caching:** Observations from every thread share one record. When any thread is observed, the observation context changes for all other threads, which invalidates their cached prompt prefix.
+- **Agent understanding:** Each thread sees a mix of observations from every thread for the resource. Every new thread starts with context from earlier threads, and the agent may continue work that another thread started but didn't finish.
+- **Performance:** Unobserved messages across _all_ threads are processed together, which is slow for users with many existing threads.
+
+A new knowledge and subconscious memory primitive for cross-thread memory is coming soon and will replace resource scope. Until then, use the alternatives below.
+
+#### Cross-thread continuity without resource scope
+
+Switching from resource scope to thread scope doesn't migrate resource-scoped observations. Each thread uses its existing thread-scoped record if it has one, or starts a new, empty one, and messages already observed under resource scope aren't observed again. Keep facts that must carry over in resource-scoped working memory.
+
+Use thread scope with one or both of these features instead:
+
+- [Retrieval mode](#retrieval-mode): The agent gets a `recall` tool that can list and browse other threads for the same resource, and optionally search them semantically. The agent looks up earlier conversations only when it needs them.
+- [Resource-scoped working memory](https://mastra.ai/docs/memory/working-memory): Stores small, durable facts about the user that every thread can read.
 
 ```typescript
 const memory = new Memory({
   options: {
     observationalMemory: {
       model: 'google/gemini-2.5-flash',
+      retrieval: true,
+    },
+    workingMemory: {
+      enabled: true,
       scope: 'resource',
     },
   },
 })
 ```
 
-Resource scope works, however it's marked as experimental for now until we prove task adherence/continuity across multiple ongoing simultaneous threads. As of today, you may need to tweak your system prompt to prevent one thread from continuing the work that another had already started (but hadn't finished).
-
-This is because in resource scope, each thread is a perspective on _all_ threads for the resource.
-
-For your use-case this may not be a problem, so your mileage may vary.
-
-> **Warning:** In resource scope, unobserved messages across _all_ threads are processed together. For users with many existing threads, this can be slow. Use thread scope for existing apps.
-
 ## Token budgets
 
 OM uses token thresholds to decide when to observe and reflect. See [token budget configuration](https://mastra.ai/reference/memory/observational-memory) for details.
@@ -786,7 +799,7 @@ const memory = new Memory({
 
 Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
 
-> **Note:** Resource scope automatically disables async buffering.
+> **Note:** Resource scope (deprecated) automatically disables async buffering.
 
 ## Observer Context Optimization
 
@@ -889,7 +902,7 @@ hooks: {
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.
 
 - **Thread scope**: The first time a thread exceeds `observation.messageTokens`, the Observer processes the backlog.
-- **Resource scope**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take substantial time.
+- **Resource scope (deprecated)**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take substantial time.
 
 ## Comparing OM with other memory features
 

package/.docs/docs/memory/overview.md

@@ -212,7 +212,7 @@ To go beyond this default isolation, you can share memory between agents by pass
 
 When you call agents directly (outside the delegation flow), memory sharing is controlled by two identifiers: `resourceId` and `threadId`. Agents that use the same values read and write to the same data. This is useful when agents collaborate on a shared context, for example, a researcher that saves notes and a writer that reads them.
 
-**Resource-scoped sharing** is the most common pattern. [Working memory](https://mastra.ai/docs/memory/working-memory) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) default to `scope: 'resource'`. If two agents share a `resourceId`, they share observations, working memory, and embeddings, even across different threads:
+**Resource-scoped sharing** is the most common pattern. [Working memory](https://mastra.ai/docs/memory/working-memory) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) default to `scope: 'resource'`. If two agents share a `resourceId`, they share working memory and embeddings, even across different threads:
 
 ```typescript
 // Both agents share the same resource-scoped memory
@@ -225,7 +225,7 @@ await writer.generate('Write a summary from the research notes.', {
 })
 ```
 
-Because both calls use `resource: 'project-42'`, the writer can access the researcher's observations and working memory. Semantic embeddings are also shared through the resource. Each agent still has its own thread, so message histories stay separate.
+Because both calls use `resource: 'project-42'`, the writer can access the researcher's working memory. Semantic embeddings are also shared through the resource. Each agent still has its own thread, so message histories stay separate.
 
 **Thread-scoped sharing** gives tighter coupling. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses `scope: 'thread'` by default. If two agents use the same `resource` and `thread`, they share the full message history. Each agent sees every message the other has written. This is useful when agents need to build on each other's exact outputs.
 

package/.docs/integrations/deploy/kubernetes.md

@@ -251,18 +251,20 @@ Register the durable agent with the `Mastra` instance above. Its run state now l
 A durable agent publishes stream chunks to a per-run topic through the shared pub/sub. A client that disconnects reconnects by calling `observe()` with the run's ID, and replays the chunks it missed from the shared cache:
 
 ```typescript
-const { output, cleanup } = await durableAssistant.observe(runId)
+const { output, detach } = await durableAssistant.observe(runId)
+
+request.signal.addEventListener('abort', detach, { once: true })
+
+if (request.signal.aborted) detach()
 
 for await (const chunk of output.fullStream) {
   // Chunks from the run, including any missed while disconnected
 }
-
-cleanup()
 ```
 
 Because the run state is in Postgres and the events are in Redis, the reconnecting request can be served by any pod, not only the one that started the run. See [Resumable streams](https://mastra.ai/docs/harness/durable-agents).
 
-Multiple clients can observe the same run at once. Each `observe()` call receives the full stream, so a user watching from two devices, or two people following the same run, stay in sync.
+Multiple clients can observe the same run at once. Each `observe()` call receives the full stream, so a user watching from two devices, or two people following the same run, stay in sync. When one client leaves the loop or calls `detach()`, only that client stops watching. Don't call `cleanup()` from an observer, because it clears the cached events the other clients need to reconnect.
 
 ## Tool approval across pods
 

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 265 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 269 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -188,11 +188,15 @@ ANTHROPIC_API_KEY=ant-...
 | `openrouter/minimax/minimax-m2.5`                                     |
 | `openrouter/minimax/minimax-m2.7`                                     |
 | `openrouter/minimax/minimax-m3`                                       |
+| `openrouter/mistralai/devstral-2512`                                  |
 | `openrouter/mistralai/ministral-14b-2512`                             |
 | `openrouter/mistralai/ministral-3b-2512`                              |
 | `openrouter/mistralai/ministral-8b-2512`                              |
 | `openrouter/mistralai/mistral-large-2407`                             |
+| `openrouter/mistralai/mistral-large-2512`                             |
+| `openrouter/mistralai/mistral-medium-3`                               |
 | `openrouter/mistralai/mistral-medium-3-5`                             |
+| `openrouter/mistralai/mistral-medium-3.1`                             |
 | `openrouter/mistralai/mistral-nemo`                                   |
 | `openrouter/mistralai/mistral-saba`                                   |
 | `openrouter/mistralai/mistral-small-24b-instruct-2501`                |

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 385 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 387 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -187,11 +187,13 @@ ANTHROPIC_API_KEY=ant-...
 | `minimax/minimax-m2.7`                                     |
 | `minimax/minimax-m3`                                       |
 | `mistralai/codestral-2508`                                 |
+| `mistralai/devstral-2512`                                  |
 | `mistralai/ministral-14b-2512`                             |
 | `mistralai/ministral-3b-2512`                              |
 | `mistralai/ministral-8b-2512`                              |
 | `mistralai/mistral-large`                                  |
 | `mistralai/mistral-large-2407`                             |
+| `mistralai/mistral-large-2512`                             |
 | `mistralai/mistral-medium-3`                               |
 | `mistralai/mistral-medium-3-5`                             |
 | `mistralai/mistral-medium-3.1`                             |

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

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/kilo.md

@@ -4,7 +4,7 @@
 
 # ![Kilo Gateway logo](https://models.dev/logos/kilo.svg)Kilo Gateway
 
-Access 392 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
+Access 394 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
 
 Learn more in the [Kilo Gateway documentation](https://kilo.ai).
 
@@ -42,12 +42,12 @@ for await (const chunk of stream) {
 | `kilo/~anthropic/claude-haiku-latest`                           | 200K    |       |           |       |       |       | $1         | $5          |
 | `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.04      | $1          |
-| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.39      | $1          |
+| `kilo/~deepseek/deepseek-flash-latest`                          | 1.0M    |       |           |       |       |       | $0.04      | $0.49       |
+| `kilo/~deepseek/deepseek-pro-latest`                            | 1.0M    |       |           |       |       |       | $0.25      | $3          |
 | `kilo/~deepseek/deepseek-v4-flash-latest`                       | 1.0M    |       |           |       |       |       | $0.03      | $0.32       |
 | `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    |       |           |       |       |       | $1         | $12         |
+| `kilo/~moonshotai/kimi-latest`                                  | 1.0M    |       |           |       |       |       | $0.88      | $11         |
 | `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          |
@@ -190,20 +190,22 @@ for await (const chunk of stream) {
 | `kilo/minimax/minimax-m2.7`                                     | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/minimax/minimax-m3`                                       | 524K    |       |           |       |       |       | $0.30      | $1          |
 | `kilo/mistralai/codestral-2508`                                 | 256K    |       |           |       |       |       | $0.30      | $0.90       |
+| `kilo/mistralai/devstral-2512`                                  | 262K    |       |           |       |       |       | $0.40      | $2          |
 | `kilo/mistralai/ministral-14b-2512`                             | 262K    |       |           |       |       |       | $0.20      | $0.20       |
 | `kilo/mistralai/ministral-3b-2512`                              | 131K    |       |           |       |       |       | $0.10      | $0.10       |
 | `kilo/mistralai/ministral-8b-2512`                              | 262K    |       |           |       |       |       | $0.15      | $0.15       |
 | `kilo/mistralai/mistral-large`                                  | 128K    |       |           |       |       |       | $2         | $6          |
 | `kilo/mistralai/mistral-large-2407`                             | 131K    |       |           |       |       |       | $2         | $6          |
+| `kilo/mistralai/mistral-large-2512`                             | 262K    |       |           |       |       |       | $0.50      | $2          |
 | `kilo/mistralai/mistral-medium-3`                               | 131K    |       |           |       |       |       | $0.40      | $2          |
 | `kilo/mistralai/mistral-medium-3-5`                             | 262K    |       |           |       |       |       | $2         | $8          |
 | `kilo/mistralai/mistral-medium-3.1`                             | 131K    |       |           |       |       |       | $0.40      | $2          |
-| `kilo/mistralai/mistral-nemo`                                   | 131K    |       |           |       |       |       | $0.02      | $0.03       |
+| `kilo/mistralai/mistral-nemo`                                   | 131K    |       |           |       |       |       | $0.15      | $0.15       |
 | `kilo/mistralai/mistral-saba`                                   | 33K     |       |           |       |       |       | $0.20      | $0.60       |
 | `kilo/mistralai/mistral-small-24b-instruct-2501`                | 33K     |       |           |       |       |       | $0.05      | $0.08       |
 | `kilo/mistralai/mistral-small-2603`                             | 262K    |       |           |       |       |       | $0.15      | $0.60       |
 | `kilo/mistralai/mistral-small-3.1-24b-instruct`                 | 128K    |       |           |       |       |       | $0.35      | $0.56       |
-| `kilo/mistralai/mistral-small-3.2-24b-instruct`                 | 256K    |       |           |       |       |       | $0.09      | $0.25       |
+| `kilo/mistralai/mistral-small-3.2-24b-instruct`                 | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `kilo/mistralai/mixtral-8x22b-instruct`                         | 66K     |       |           |       |       |       | $2         | $6          |
 | `kilo/mistralai/voxtral-small-24b-2507`                         | 33K     |       |           |       |       |       | $0.10      | $0.30       |
 | `kilo/moonshotai/kimi-k2`                                       | 131K    |       |           |       |       |       | $0.57      | $2          |
@@ -334,7 +336,7 @@ for await (const chunk of stream) {
 | `kilo/qwen/qwen3-next-80b-a3b-thinking`                         | 262K    |       |           |       |       |       | $0.15      | $1          |
 | `kilo/qwen/qwen3-vl-235b-a22b-instruct`                         | 131K    |       |           |       |       |       | $0.26      | $1          |
 | `kilo/qwen/qwen3-vl-235b-a22b-thinking`                         | 131K    |       |           |       |       |       | $0.40      | $4          |
-| `kilo/qwen/qwen3-vl-30b-a3b-instruct`                           | 131K    |       |           |       |       |       | $0.13      | $0.52       |
+| `kilo/qwen/qwen3-vl-30b-a3b-instruct`                           | 262K    |       |           |       |       |       | $0.13      | $0.52       |
 | `kilo/qwen/qwen3-vl-30b-a3b-thinking`                           | 131K    |       |           |       |       |       | $0.20      | $2          |
 | `kilo/qwen/qwen3-vl-32b-instruct`                               | 131K    |       |           |       |       |       | $0.10      | $0.42       |
 | `kilo/qwen/qwen3-vl-8b-instruct`                                | 131K    |       |           |       |       |       | $0.12      | $0.46       |
@@ -386,7 +388,7 @@ for await (const chunk of stream) {
 | `kilo/tencent/hy-mt2-1.8b`                                      | 8K      |       |           |       |       |       | $0.04      | $0.18       |
 | `kilo/tencent/hy-mt2-30b-a3b`                                   | 8K      |       |           |       |       |       | $0.07      | $0.29       |
 | `kilo/tencent/hy-mt2-7b`                                        | 8K      |       |           |       |       |       | $0.07      | $0.29       |
-| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.08      | $0.33       |
+| `kilo/tencent/hy3`                                              | 262K    |       |           |       |       |       | $0.13      | $0.53       |
 | `kilo/tencent/hy3-preview`                                      | 262K    |       |           |       |       |       | $0.18      | $0.60       |
 | `kilo/tencent/hy4-preview`                                      | 1.0M    |       |           |       |       |       | $0.83      | $3          |
 | `kilo/thedrummer/cydonia-24b-v4.1`                              | 131K    |       |           |       |       |       | $0.30      | $0.50       |
@@ -418,11 +420,11 @@ for await (const chunk of stream) {
 | `kilo/z-ai/glm-4.5v`                                            | 66K     |       |           |       |       |       | $0.60      | $2          |
 | `kilo/z-ai/glm-4.6`                                             | 198K    |       |           |       |       |       | $0.43      | $2          |
 | `kilo/z-ai/glm-4.6v`                                            | 131K    |       |           |       |       |       | $0.30      | $0.90       |
-| `kilo/z-ai/glm-4.7`                                             | 203K    |       |           |       |       |       | $0.40      | $2          |
+| `kilo/z-ai/glm-4.7`                                             | 203K    |       |           |       |       |       | $0.60      | $2          |
 | `kilo/z-ai/glm-4.7-flash`                                       | 131K    |       |           |       |       |       | $0.06      | $0.40       |
 | `kilo/z-ai/glm-5`                                               | 198K    |       |           |       |       |       | $0.60      | $2          |
 | `kilo/z-ai/glm-5-turbo`                                         | 203K    |       |           |       |       |       | $1         | $4          |
-| `kilo/z-ai/glm-5.1`                                             | 200K    |       |           |       |       |       | $1         | $4          |
+| `kilo/z-ai/glm-5.1`                                             | 203K    |       |           |       |       |       | $1         | $4          |
 | `kilo/z-ai/glm-5.2`                                             | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `kilo/z-ai/glm-5.2:free`                                        | 33K     |       |           |       |       |       | —          | —           |
 | `kilo/z-ai/glm-5.3`                                             | 1.0M    |       |           |       |       |       | $1         | $4          |

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

@@ -4,7 +4,7 @@
 
 # ![NanoGPT logo](https://models.dev/logos/nano-gpt.svg)NanoGPT
 
-Access 592 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
+Access 593 NanoGPT models through Mastra's model router. Authentication is handled automatically using the `NANO_GPT_API_KEY` environment variable.
 
 Learn more in the [NanoGPT documentation](https://docs.nano-gpt.com).
 
@@ -83,7 +83,7 @@ for await (const chunk of stream) {
 | `nano-gpt/anthropic/claude-opus-4.8:thinking`                    | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `nano-gpt/anthropic/claude-opus-5`                               | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `nano-gpt/anthropic/claude-opus-5.5`                             | 1.0M    |       |           |       |       |       | $4         | $20         |
-| `nano-gpt/anthropic/claude-opus-latest`                          | 1.0M    |       |           |       |       |       | $5         | $25         |
+| `nano-gpt/anthropic/claude-opus-latest`                          | 1.0M    |       |           |       |       |       | $4         | $20         |
 | `nano-gpt/anthropic/claude-sonnet-4`                             | 200K    |       |           |       |       |       | $3         | $15         |
 | `nano-gpt/anthropic/claude-sonnet-4:thinking`                    | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `nano-gpt/anthropic/claude-sonnet-4:thinking:1024`               | 1.0M    |       |           |       |       |       | $3         | $15         |
@@ -400,7 +400,7 @@ for await (const chunk of stream) {
 | `nano-gpt/openai/gpt-astra-latest`                               | 1.1M    |       |           |       |       |       | $10        | $50         |
 | `nano-gpt/openai/gpt-chat-latest`                                | 1.1M    |       |           |       |       |       | $2         | $10         |
 | `nano-gpt/openai/gpt-latest`                                     | 1.1M    |       |           |       |       |       | $10        | $50         |
-| `nano-gpt/openai/gpt-luna-latest`                                | 1.1M    |       |           |       |       |       | $0.20      | $1          |
+| `nano-gpt/openai/gpt-luna-latest`                                | 1.1M    |       |           |       |       |       | $0.10      | $0.50       |
 | `nano-gpt/openai/gpt-oss-120b`                                   | 128K    |       |           |       |       |       | $0.35      | $0.75       |
 | `nano-gpt/openai/gpt-oss-20b`                                    | 128K    |       |           |       |       |       | $0.20      | $0.30       |
 | `nano-gpt/openai/gpt-oss-safeguard-20b`                          | 128K    |       |           |       |       |       | $0.07      | $0.30       |
@@ -586,12 +586,13 @@ for await (const chunk of stream) {
 | `nano-gpt/x-ai/grok-4.6`                                         | 500K    |       |           |       |       |       | $2         | $6          |
 | `nano-gpt/x-ai/grok-4.7`                                         | 500K    |       |           |       |       |       | $2         | $5          |
 | `nano-gpt/x-ai/grok-build-0.1`                                   | 256K    |       |           |       |       |       | $1         | $2          |
-| `nano-gpt/x-ai/grok-latest`                                      | 500K    |       |           |       |       |       | $2         | $6          |
+| `nano-gpt/x-ai/grok-latest`                                      | 500K    |       |           |       |       |       | $2         | $5          |
 | `nano-gpt/xiaomi/mimo-v2.5`                                      | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `nano-gpt/xiaomi/mimo-v2.5-pro`                                  | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `nano-gpt/xiaomi/mimo-v2.5-pro:thinking`                         | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `nano-gpt/xiaomi/mimo-v2.5:thinking`                             | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `nano-gpt/xiaomi/mimo-v2.6-flash`                                | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `nano-gpt/xiaomi/mimo-v2.6-flash-uncensored`                     | 1.0M    |       |           |       |       |       | $0.50      | $2          |
 | `nano-gpt/xiaomi/mimo-v2.6-pro`                                  | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `nano-gpt/xiaomi/mimo-v2.6-pro-ultraspeed`                       | 1.0M    |       |           |       |       |       | $4         | $9          |
 | `nano-gpt/z-ai/glm-4.5`                                          | 128K    |       |           |       |       |       | $0.30      | $1          |

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

@@ -4,7 +4,7 @@
 
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 110 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 111 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
 
 Learn more in the [OpenCode Zen documentation](https://opencode.ai/docs/zen).
 
@@ -105,7 +105,6 @@ for await (const chunk of stream) {
 | `opencode/minimax-m2.7`                    | 205K    |       |           |       |       |       | $0.30      | $1          |
 | `opencode/minimax-m3`                      | 512K    |       |           |       |       |       | $0.30      | $1          |
 | `opencode/muse-spark-1.2`                  | 1.0M    |       |           |       |       |       | $1         | $4          |
-| `opencode/muse-spark-1.2-contributor-free` | 1.0M    |       |           |       |       |       | —          | —           |
 | `opencode/muse-spark-1.3`                  | 1.0M    |       |           |       |       |       | $1         | $4          |
 | `opencode/muse-spark-1.3-contributor-free` | 1.0M    |       |           |       |       |       | —          | —           |
 | `opencode/nemotron-3-ultra-free`           | 1.0M    |       |           |       |       |       | —          | —           |
@@ -113,6 +112,7 @@ for await (const chunk of stream) {
 | `opencode/qwen3.5-plus`                    | 262K    |       |           |       |       |       | $0.20      | $1          |
 | `opencode/qwen3.6-plus`                    | 262K    |       |           |       |       |       | $0.50      | $3          |
 | `opencode/qwen3.8-flash`                   | 1.0M    |       |           |       |       |       | $0.15      | $0.47       |
+| `opencode/qwen3.8-max`                     | 262K    |       |           |       |       |       | $2         | $6          |
 | `opencode/space-bunny-free`                | 1.0M    |       |           |       |       |       | —          | —           |
 
 Model availability, capabilities, context windows, and pricing are sourced from [models.dev](https://models.dev) and may change.

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

@@ -510,6 +510,8 @@ Subscribes to raw stream chunks for a memory thread. Use this before calling `se
 
 **options.hideSignals** (`boolean | AgentSignalType[]`): Use true to hide all recognized signals, false to show all, or an array to hide selected types from this subscription, including live, idle-persisted, and replayed signals. Other subscribers and the initiating stream keep their own policies.
 
+**options.withInitialHistory** (`boolean | { perPage?: number }`): Emit the stored thread messages as one thread-history chunk first, then only retained parts newer than that history, then live parts. Completed runs already in storage aren't replayed; pending tool approvals are still emitted. perPage limits how many recent messages are loaded (default 40). Requires agent memory; without it the subscription is live-only.
+
 By default, subscriptions include every signal type, including reactive reminders. To hide reminders for one subscriber without affecting another:
 
 ```ts
@@ -520,6 +522,19 @@ const filtered = await agent.subscribeToThread({
 })
 ```
 
+To render a thread without replaying finished runs, request initial history. The first chunk carries the stored messages:
+
+```ts
+const subscription = await agent.subscribeToThread({
+  threadId: 'thread-abc',
+  withInitialHistory: true,
+})
+for await (const chunk of subscription.stream) {
+  if (chunk.type === 'thread-history') render(chunk.payload.messages)
+  else handle(chunk)
+}
+```
+
 `hideSignals: true` hides all recognized signal types. Set it to `false` to show all signals. An array accepts `user`, `state`, `reactive`, `notification`, `user-message`, and `system-reminder`. Matching normalizes `system-reminder` to `reactive` and `user-message` to `user`. An omitted option, `false`, or `[]` excludes nothing. Each subscriber filters its own live and replayed chunks, including remote pubsub events and idle-persisted signals. Filtering preserves non-signal chunks, unknown or malformed signal chunks, ordering, and completion/error events, even when every signal type is excluded.
 
 Exclusions don't change model context, storage, shared broadcasts, or another caller's output. They aren't a security boundary and don't replace `ifActive`/`ifIdle` delivery policies or `transient` persistence behavior. This option is supported by the in-process core API, not HTTP or client-js subscription requests. See [stream signal visibility](https://mastra.ai/reference/streaming/agents/stream) for transform ordering and the distinction from recall's exact stored-type matching and reminder-hidden history default.

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

@@ -96,7 +96,7 @@ Returns: `DurableAgent`
 
 ## `createEventedAgent(options)`
 
-Wraps an `Agent` with fire-and-forget durable execution on the built-in workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the underlying workflow runs non-blocking (via `startAsync`) instead of running to completion before the stream is wired up. Use it when you want the run to progress independently of the caller. It doesn't accept `id` or `name` overrides.
+Wraps an `Agent` with fire-and-forget durable execution on the built-in evented workflow engine. Like `createDurableAgent`, it returns a result you stream from, but the run is started without being awaited: execution is driven by events on the Mastra instance's PubSub, so the run progresses independently of the caller. Register the agent on a `Mastra` instance with storage to get evented execution; without one, the agent falls back to the default in-process engine and logs a warning. It doesn't accept `id` or `name` overrides.
 
 ```typescript
 import { createEventedAgent } from '@mastra/core/agent/durable'

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

@@ -302,6 +302,8 @@ await subscription.processDataStream({
 })
 ```
 
+Pass `withInitialHistory: true` (or `{ perPage }`) to receive the stored messages as a first `thread-history` chunk instead of fetching history separately. Finished runs aren't replayed after it, so completed answers don't stream again on reconnect.
+
 `subscribeToThread()` returns the underlying `Response` plus a `processDataStream()` helper. The helper reads the subscription stream until the connection closes or the request is aborted. Pass `reconnect: true` to resubscribe when the transport closes or a reconnect request fails, such as after a proxy idle timeout.
 
 **resourceId** (`string`): Resource ID for the memory thread.

package/.docs/reference/memory/cloneThread.md

@@ -171,7 +171,7 @@ When working memory is enabled, `cloneThread()` copies or shares working memory
 When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, `cloneThread()` automatically clones the OM records associated with the source thread. The behavior depends on the OM scope:
 
 - **Thread-scoped OM**: The OM record is cloned to the new thread. All internal message ID references are remapped to point to the cloned messages.
-- **Resource-scoped OM (same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
-- **Resource-scoped OM (different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
+- **Resource-scoped OM (deprecated, same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
+- **Resource-scoped OM (deprecated, different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
 
 Only the current (most recent) OM generation is cloned. Older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.

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

@@ -39,7 +39,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with observation.model or reflection.model — an error will be thrown if both are set. When this and observation.model/reflection.model are all omitted, OM falls back to google/gemini-2.5-flash. Use "default" to explicitly use the default model (google/gemini-2.5-flash). (Default: `'google/gemini-2.5-flash'`)
 
-**scope** (`'resource' | 'thread'`): Memory scope for observations. 'thread' keeps observations per-thread. 'resource' (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
+**scope** (`'resource' | 'thread'`): Memory scope for observations. 'thread' keeps observations per-thread. 'resource' is deprecated and will be removed in a future release. It shares observations across all threads for a resource and works much worse than thread scope for prompt caching and agent understanding. For cross-thread continuity, use thread scope with retrieval or resource-scoped working memory. See resource scope (deprecated). (Default: `'thread'`)
 
 **activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after 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 false to disable inherited observation idle activation. Reflections do not inherit this setting. Use reflection.activateAfterIdle to opt reflections into idle activation.
 
@@ -71,7 +71,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Text is estimated locally with tokenx. Image parts are included with model-aware heuristics when possible, with deterministic fallbacks when image metadata is incomplete. Image-like file parts are counted the same way when uploads are normalized as files.
 
-**observation.maxTokensPerBatch** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls.
+**observation.maxTokensPerBatch** (`number`): Maximum tokens per batch when observing multiple threads in resource scope (deprecated). Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls.
 
 **observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. The temperature: 0.3 default is only applied when the resolved model is known to support temperature. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
 
@@ -216,7 +216,7 @@ const memory = new Memory({
 
 Set `workingMemory.agentManaged: true` if the main agent should still receive working memory tool and instruction injection.
 
-### Resource scope with custom thresholds (experimental)
+### Custom thresholds
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -231,7 +231,6 @@ export const agent = new Agent({
     options: {
       observationalMemory: {
         model: 'google/gemini-2.5-flash',
-        scope: 'resource',
         observation: {
           messageTokens: 20_000,
         },
@@ -420,7 +419,7 @@ observationalMemory: {
 
 Setting `bufferTokens: false` disables both observation and reflection async buffering. Observations and reflections will run synchronously when their thresholds are reached.
 
-> **Note:** Async buffering isn't supported with `scope: 'resource'` and is automatically disabled in resource scope.
+> **Note:** Async buffering isn't supported with the deprecated `scope: 'resource'` and is automatically disabled in resource scope.
 
 ## Streaming data parts
 
@@ -734,7 +733,6 @@ const om = new ObservationalMemory({
   storage: storage.stores.memory!,
   memory,
   model: 'google/gemini-2.5-flash',
-  scope: 'resource',
   observation: {
     messageTokens: 20_000,
   },

package/.docs/reference/processors/agents-md-injector.md

@@ -32,6 +32,8 @@ Add the processor to an agent's `inputProcessors`. Each invocation injects at mo
 
 **getReader** (`(args: ProcessInputStepArgs) => ReminderFileReader | undefined`): Select a reader for this request. Returning undefined keeps the instance defaults.
 
+**getBasePath** (`(args: ProcessInputStepArgs) => string | undefined`): Return the project root for this request. Relative tool paths resolve against it instead of process.cwd(), and instruction files outside it are never loaded. Returning undefined keeps process.cwd() resolution with no boundary.
+
 ## `ReminderFileReader`
 
 A reader controls both file access and optional path identity. Return one from `getReader` when instruction files live in a virtual filesystem or a trusted git ref rather than the current checkout.

package/.docs/reference/pubsub/base.md

@@ -119,6 +119,17 @@ The default implementation is a no-op because transports that retain nothing per
 await pubsub.clearTopic('workflow.events.v2.run-123')
 ```
 
+#### `trimTopic(topic, { runId, producedBefore? })`
+
+Deletes every retained entry on the topic that was published with `runId`. Other entries are untouched. Mastra calls this once a run completes successfully and its messages are saved to storage, so finished runs leave the topic while runs still in progress or waiting for approval stay. The default implementation is a no-op. [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) overrides it. Same best-effort contract as `clearTopic`.
+
+With `producedBefore` (epoch ms), only entries whose `data.producedAt` is at or before it are deleted, and entries marked `data.pinned` (approval and suspension prompts) are kept. Mastra uses this while a run continues: each time the run's messages are saved mid-run, the parts up to the last finished step leave the topic.
+
+```typescript
+await pubsub.trimTopic('agent.thread.thread-abc', { runId: 'run-123' })
+await pubsub.trimTopic('agent.thread.thread-abc', { runId: 'run-123', producedBefore: Date.now() })
+```
+
 ### Replay methods
 
 These methods support resuming a stream after a disconnect. The default implementations fall back to a regular `subscribe`, so backends without history support behave as live-only. [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub) overrides them to replay cached events.

package/.docs/reference/pubsub/redis-streams.md

@@ -159,6 +159,14 @@ Not every topic reaches a `clearTopic` call. Topics without a defined end of lif
 await pubsub.clearTopic('workflow.events.run-123')
 ```
 
+### `trimTopic(topic, { runId, producedBefore? })`
+
+Pages through the stream with `XRANGE` and runs `XDEL` for every entry published with `runId`. With `producedBefore`, only entries produced at or before that time are deleted, skipping approval and suspension prompts. Mastra uses this to trim a long run each time its messages are saved. Mastra calls this once a thread run's messages are persisted, so an idle thread's stream empties instead of growing to `maxLen`. Because entries are matched by `runId`, a run resumed after a restart also removes the entries it published before the restart. Entries from other runs, including those from other processes, are never touched. Best-effort. Failures are logged at warn level.
+
+```typescript
+await pubsub.trimTopic('agent.thread.thread-abc', { runId: 'run-123' })
+```
+
 ### `close()`
 
 Closes the Redis connections and stops all subscriptions. Call this during graceful shutdown.

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

@@ -516,7 +516,7 @@ Added when a sandbox is configured:
 
 With a static sandbox, capability checks (`executeCommand`, `processes`) decide which tool variants are exposed. With a [runtime-defined sandbox](https://mastra.ai/docs/sandbox/overview), all sandbox tools are registered and the runtime throws a clear error if the resolved sandbox doesn't implement a requested capability.
 
-The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle callbacks on background processes:
+The `execute_command` tool accepts these options:
 
 **backgroundProcesses** (`BackgroundProcessesConfig`): Configuration for handling background processes. Only applicable if the sandbox supports background execution.
 
@@ -528,6 +528,19 @@ The `execute_command` tool accepts a `backgroundProcesses` option for lifecycle
 
 **backgroundProcesses.abortSignal** (`AbortSignal | null | false`): Abort signal for background processes. undefined (default) uses the agent's signal. null or false disables abort — processes persist after agent shutdown.
 
+**requireDescription** (`boolean`): Adds a required description argument, listed before command, where the model says in a few words what the command does. Use it to show a readable label in place of the raw command. When false, the tool schema has no description argument. (Default: `false`)
+
+```typescript
+const workspace = new Workspace({
+  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
+  tools: {
+    [WORKSPACE_TOOLS.SANDBOX.EXECUTE_COMMAND]: {
+      requireDescription: true,
+    },
+  },
+})
+```
+
 See [Background processes](https://mastra.ai/docs/sandbox/overview) for callback examples.
 
 ### Search tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.3.1",
+  "version": "1.3.2-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@mastra/mcp-legacy": "npm:@mastra/mcp@^1.18.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.6.4",
-    "@mastra/core": "1.71.0",
+    "@mastra/core": "1.72.0-alpha.1",
     "@mastra/mcp": "^2.1.0"
   },
   "devDependencies": {
@@ -44,8 +44,8 @@
     "typescript": "^7.0.2",
     "vitest": "4.1.11",
     "@internal/lint": "0.0.137",
-    "@mastra/core": "1.71.0",
-    "@internal/types-builder": "0.0.112"
+    "@internal/types-builder": "0.0.112",
+    "@mastra/core": "1.72.0-alpha.1"
   },
   "homepage": "https://mastra.ai",
   "repository": {