@mastra/mcp-docs-server 1.1.25 → 1.1.26-alpha.10

package/.docs/docs/agents/overview.md

@@ -52,6 +52,8 @@ When referencing an agent from your Mastra instance, use `mastra.getAgentById()`
 
 Returns the full response after all tool calls and steps complete. The result includes `text`, `toolCalls`, `toolResults`, `steps`, and token `usage` statistics.
 
+See the [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate) for the response shape, including tool call and tool result payloads.
+
 ```ts
 const agent = mastra.getAgentById('test-agent')
 const response = await agent.generate('Help me organize my day')
@@ -62,6 +64,8 @@ console.log(response.text)
 
 Returns a stream you can consume as tokens arrive. The result exposes `textStream` for incremental output and promises for `toolCalls`, `toolResults`, `steps`, and token `usage` that resolve when the stream finishes.
 
+See the [`MastraModelOutput` reference](https://mastra.ai/reference/streaming/agents/MastraModelOutput) for the stream shape, including tool call and tool result payloads.
+
 ```ts
 const agent = mastra.getAgentById('test-agent')
 const stream = await agent.stream('Help me organize my day')

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

@@ -73,4 +73,6 @@ Develop your project locally with [`mastra dev`](https://mastra.ai/reference/cli
 
 Once you're ready to deploy your application to production, use [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra) and [`mastra server deploy`](https://mastra.ai/reference/cli/mastra) to push your application to the cloud.
 
-Follow the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform) for step-by-step instructions.
+Follow the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform) for step-by-step instructions.
+
+If you host your Mastra application on your own infrastructure, you can still send observability data to Studio using the [CloudExporter](https://mastra.ai/docs/observability/tracing/exporters/cloud).

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

@@ -333,13 +333,33 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### 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 threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                  |
-| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                  |
-| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                           |
+| 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 threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                                   |
+| `activateAfterIdle`            | none    | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
+| `activateOnProviderChange`     | `false` | Forces buffered observations and reflections 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.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                            |
+
+If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      activateOnProviderChange: true,
+    },
+  },
+})
+```
+
+With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
+
+Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
 
 ### Disabling
 

package/.docs/docs/observability/tracing/exporters/cloud.md

@@ -2,6 +2,18 @@
 
 The `CloudExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.
 
+> **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra Platform), you still need a deployed Studio project to view traces, logs, and metrics. `CloudExporter` sends data to a Studio project, so one must exist before you can use it.
+>
+> 1. [Create a Mastra project](https://mastra.ai/guides/getting-started/quickstart) if you don't have one yet.
+> 2. [Deploy Studio](https://mastra.ai/docs/studio/deployment) to the Mastra platform with `mastra studio deploy`.
+> 3. Follow the [quickstart steps below](#quickstart) to create an access token and find your project ID.
+
+## Version compatibility
+
+- Use `CloudExporter` with `@mastra/observability@1.8.0` or later.
+- If you use `@mastra/observability@1.8.0` through `1.9.1`, set `MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai` in addition to `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID`.
+- Starting in `@mastra/observability@1.9.2`, `CloudExporter` defaults to `https://observability.mastra.ai`, so `MASTRA_CLOUD_TRACES_ENDPOINT` is only required when you want to send telemetry to a different collector.
+
 ## Quickstart
 
 To connect `CloudExporter`, create an access token, find the destination `projectId`, and add the exporter to your observability config.
@@ -57,52 +69,30 @@ MASTRA_PROJECT_ID=<your-project-id>
 
 ### 3. Set your environment variables
 
-Tokens created with `mastra auth tokens create` are organization-scoped, so `MASTRA_PROJECT_ID` is required.
-
-If you use a project-scoped token from the Mastra platform instead, `CloudExporter` can route without `projectId`, but setting it explicitly is still supported.
-
-Add both values to your environment:
+Set both values in your environment so `CloudExporter` can authenticate and route telemetry to the correct project:
 
 ```bash
 MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
 MASTRA_PROJECT_ID=<your-project-id>
 ```
 
-For example:
+If you use `@mastra/observability@1.8.0` through `1.9.1`, also set the Mastra platform collector explicitly:
 
 ```bash
-MASTRA_CLOUD_ACCESS_TOKEN=<your-cloud-access-token>
-MASTRA_PROJECT_ID=<your-project-id>
+MASTRA_CLOUD_TRACES_ENDPOINT=https://observability.mastra.ai
 ```
 
-### 4. Enable `CloudExporter`
-
-The following example demonstrates how to add `CloudExporter` to your observability config:
-
-```ts
-import { Mastra } from '@mastra/core'
-import { Observability, CloudExporter } from '@mastra/observability'
+If you want to send telemetry somewhere other than Mastra platform, set `MASTRA_CLOUD_TRACES_ENDPOINT` as well. Pass either a base origin or a full traces publish URL ending in `/spans/publish`.
 
-export const mastra = new Mastra({
-  observability: new Observability({
-    configs: {
-      production: {
-        serviceName: 'my-service',
-        exporters: [
-          new CloudExporter({
-            accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
-            projectId: process.env.MASTRA_PROJECT_ID,
-          }),
-        ],
-      },
-    },
-  }),
-})
+```bash
+MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
 ```
 
-Set `serviceName` in code on the observability config, not on `CloudExporter` itself. In the example above, the value is `configs.production.serviceName`.
+When you pass a base origin, `CloudExporter` derives the matching publish URLs for traces, logs, metrics, scores, and feedback automatically.
+
+### 4. Enable `CloudExporter`
 
-For example:
+The following example demonstrates how to add `CloudExporter` to your observability config:
 
 ```ts
 import { Mastra } from '@mastra/core'
@@ -120,6 +110,8 @@ export const mastra = new Mastra({
 })
 ```
 
+Set `serviceName` on the observability config, not on `CloudExporter` itself.
+
 Use a stable `serviceName` value. In Studio, traces can be filtered by **Deployments → Service Name**, so a consistent name makes traces easier to find.
 
 Visit [Observability configuration reference](https://mastra.ai/reference/observability/tracing/configuration) for the full observability config shape.
@@ -130,7 +122,7 @@ If you prefer, rely entirely on environment variables:
 new CloudExporter()
 ```
 
-With `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `CloudExporter` automatically sends data to the correct Mastra platform project.
+With `MASTRA_CLOUD_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `CloudExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_CLOUD_TRACES_ENDPOINT`, it sends data to that collector instead.
 
 > **Note:** Visit [CloudExporter reference](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter) for the full list of configuration options.
 
@@ -162,13 +154,17 @@ export const mastra = new Mastra({
 
 ## Complete configuration
 
-The following example demonstrates how to configure custom endpoints and batching behavior:
+`CloudExporter` defaults to Mastra platform. If you want to send telemetry to a different collector, set `MASTRA_CLOUD_TRACES_ENDPOINT` in your environment or pass `endpoint` in code.
+
+```bash
+MASTRA_CLOUD_TRACES_ENDPOINT=https://collector.example.com
+```
+
+The following example demonstrates how to override the collector endpoint and batching behavior in code:
 
 ```ts
 new CloudExporter({
-  accessToken: process.env.MASTRA_CLOUD_ACCESS_TOKEN,
-  projectId: process.env.MASTRA_PROJECT_ID,
-  endpoint: 'https://cloud.your-domain.com',
+  endpoint: 'https://collector.example.com',
   maxBatchSize: 1000,
   maxBatchWaitMs: 5000,
   logLevel: 'info',
@@ -179,13 +175,10 @@ new CloudExporter({
 
 After you enable `CloudExporter`, open your project in [Mastra Studio](https://projects.mastra.ai) to inspect the exported data.
 
-- Open your project and select **Open Studio**.
+- Open the project you set `MASTRA_PROJECT_ID` to and select **Open Studio**.
 - In Studio, go to **Traces** to inspect agent and workflow traces.
 - Open the filter menu and use **Deployments → Service Name** to isolate traces from a specific app or deployment.
 - Use the **Logs** page in the project dashboard to inspect exported logs.
-- Use the project named by `MASTRA_PROJECT_ID` when you work with organization-scoped tokens.
-
-> **Note:** If you use a project-scoped token, open the project that issued the token. If you use an organization-scoped token, open the project named by `MASTRA_PROJECT_ID`.
 
 When you deploy with Mastra Studio, set **Deployment → Service Name** to a stable value and keep it aligned with the `serviceName` in your observability config. This makes traces easier to filter in Studio through **Deployments → Service Name** when multiple services or deployments send data to the same project.
 

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -242,7 +242,7 @@ Use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/u
 
 When your agent has [memory](https://mastra.ai/docs/memory/overview) configured, Mastra loads conversation history from storage on the server. Send only the new message from the client instead of the full conversation history.
 
-Sending the full history is redundant and can cause message ordering bugs because client-side timestamps can conflict with the timestamps stored in your database.
+Sending the full history is redundant and can cause message-ordering bugs because client-side timestamps can conflict with the timestamps stored in your database.
 
 ```typescript
 import { useChat } from '@ai-sdk/react'
@@ -392,7 +392,8 @@ Mastra streams data to the frontend as "parts" within messages. Each part has a
 | Data Part Type       | Source                  | Description                                                                        |
 | -------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
 | `tool-{toolKey}`     | AI SDK built-in         | Tool invocation with states: `input-available`, `output-available`, `output-error` |
-| `data-workflow`      | `workflowRoute()`       | Workflow execution with step inputs, outputs, and status                           |
+| `data-workflow`      | `workflowRoute()`       | Workflow execution state snapshots with step status and final outputs              |
+| `data-workflow-step` | `workflowRoute()`       | Workflow step delta with the full payload for the step that just changed           |
 | `data-network`       | `networkRoute()`        | Agent network execution with ordered steps and outputs                             |
 | `data-tool-agent`    | Nested agent in tool    | Agent output streamed from within a tool's `execute()`                             |
 | `data-tool-workflow` | Nested workflow in tool | Workflow output streamed from within a tool's `execute()`                          |
@@ -505,11 +506,11 @@ export function Chat() {
 
 ### Rendering workflow data
 
-When using `workflowRoute()` or `handleWorkflowStream()`, Mastra emits `data-workflow` parts that contain the workflow's execution state, including step statuses and outputs.
+When using `workflowRoute()` or `handleWorkflowStream()`, Mastra emits `data-workflow` parts for workflow state snapshots and `data-workflow-step` parts for the full payload of the step that just changed. This keeps long-running workflows from repeating every completed step output in every intermediate snapshot.
 
 **Backend**:
 
-Define a workflow with multiple steps that will emit `data-workflow` parts as it executes.
+Define a workflow with multiple steps that will emit `data-workflow` and `data-workflow-step` parts as it executes.
 
 ```typescript
 import { createStep, createWorkflow } from '@mastra/core/workflows'
@@ -584,14 +585,15 @@ export const mastra = new Mastra({
 
 **Frontend**:
 
-Check for `data-workflow` parts and render each step's status and output using the `WorkflowDataPart` type for type safety.
+Check for `data-workflow` parts to render workflow status snapshots. If you need the full payload for the step that just changed, also read `data-workflow-step` parts.
 
 ```typescript
 import { useChat } from '@ai-sdk/react'
 import { DefaultChatTransport } from 'ai'
-import type { WorkflowDataPart } from '@mastra/ai-sdk'
+import type { WorkflowDataPart, WorkflowStepDataPart } from '@mastra/ai-sdk'
 
 type WorkflowData = WorkflowDataPart['data']
+type WorkflowStepData = WorkflowStepDataPart['data']
 type StepStatus = 'running' | 'success' | 'failed' | 'suspended' | 'waiting'
 
 function StepIndicator({
@@ -652,6 +654,17 @@ export function WorkflowChat() {
                 </div>
               )
             }
+            if (part.type === 'data-workflow-step') {
+              const stepData = part.data as WorkflowStepData
+              return (
+                <StepIndicator
+                  key={index}
+                  name={stepData.step.name}
+                  status={stepData.step.status}
+                  output={stepData.step.output}
+                />
+              )
+            }
             return null
           })}
         </div>

package/.docs/guides/migrations/mastra-cloud.md

@@ -56,11 +56,136 @@ The Mastra platform replaces Mastra Cloud with separate Studio and Server produc
 
 ## Replace Mastra Cloud Store with a hosted database
 
-Mastra Cloud provided a managed LibSQL database. The Mastra platform does not host a database for you, so you need to point your storage at an externally hosted instance.
+Mastra Cloud provided a managed libSQL database, backed by [Turso](https://turso.tech). The Mastra platform does not host a database for you, so you need to point your storage at an externally hosted instance.
 
-If you were already using a hosted database ("bring your own"), no changes are needed. Make sure the connection string is set as an environment variable in the dashboard rather than hardcoded.
+If you were already using a hosted database ("bring your own"), no changes are needed. Ensure the connection string is set as an environment variable in the dashboard rather than hardcoded.
 
-If you were using `file:./mastra.db` with Cloud Store, please [contact support](mailto:support@mastra.ai) for a migration path to export and import your data.
+If you were using Cloud Store, follow the steps below to export your data and load it into a new libSQL database that you control.
+
+### Export your Cloud Store data
+
+There are two ways to export your Cloud Store data: a one-click download from the dashboard, or a manual dump via the Turso CLI.
+
+#### Option A — Export from the dashboard (recommended)
+
+Open your project in the [Mastra dashboard](https://projects.mastra.ai) and navigate to **Runtime → Settings → Storage**. Click the **Export Database** button. The dashboard generates a full `.sql` dump of your Cloud Store and downloads it directly to your Downloads folder.
+
+Once the download completes, convert the dump into a SQLite database file:
+
+```bash
+sqlite3 mydb.db < ~/Downloads/mastra-cloud-dump.sql
+```
+
+You now have a portable `mydb.db` file you can inspect locally, back up, or use as the source for the new database in the steps that follow.
+
+#### Option B — Export via the Turso CLI
+
+If you prefer to work from the command line, or need to script the export, you can dump the database directly using the [Turso CLI](https://docs.turso.tech/cli). This approach requires the database URL and an auth token, both surfaced in the dashboard.
+
+1. Retrieve your Cloud Store credentials from the dashboard.
+
+   Open your project in the [Mastra dashboard](https://projects.mastra.ai) and navigate to **Runtime → Settings → Env Variables**. For Cloud Store–backed projects, two variables are injected alongside your own:
+
+   - `MASTRA_STORAGE_URL`: A libSQL connection string (e.g. `libsql://<db-name>-<org>.turso.io`).
+   - `MASTRA_STORAGE_AUTH_TOKEN`: A read-capable auth token scoped to that database.
+
+   Each row supports the standard environment variable actions — show/hide via the eye toggle, Edit, Delete, and Copy Value. Use **Copy Value** to grab both values for the dump command below.
+
+   > **Note:** These variables only appear for projects that were provisioned with Cloud Store. If you brought your own database to Mastra Cloud, you already have these credentials and can skip ahead to [Point your Mastra app at the new database](#point-your-mastra-app-at-the-new-database).
+
+   > **Info:** If the variables are missing, the values do not decrypt, or the Turso CLI rejects the token, email <support@mastra.ai> from the address associated with your Mastra Cloud account and ask for the libSQL URL and auth token for the project you want to export. Include the project name/ID. Support can also run the dump on your behalf if CLI access is blocked on your network.
+
+2. Install the Turso CLI.
+
+   ```bash
+   brew install tursodatabase/tap/turso
+   ```
+
+   ```bash
+   curl -sSfL https://get.tur.so/install.sh | bash
+   ```
+
+   See the [Turso CLI introduction](https://docs.turso.tech/cli/introduction) for Windows and headless-install options.
+
+3. Export the database to a SQL dump.
+
+   Set the credentials provided by support (or use the dashboard values if you already copied them earlier) as environment variables, then dump the database to a local file:
+
+   ```bash
+   export MASTRA_STORAGE_URL="libsql://<db-name>-<org>.turso.io"
+   export MASTRA_STORAGE_AUTH_TOKEN="<token-from-dashboard-or-support>"
+
+   turso db shell "$MASTRA_STORAGE_URL?authToken=$MASTRA_STORAGE_AUTH_TOKEN" ".dump" > mastra-cloud-dump.sql
+   ```
+
+   > **Warning:** Embedding the auth token in the connection string is less secure than Turso's recommended pattern — the full URL (with token) can end up in shell history, process listings, and terminal logs. Turso officially recommends running `turso auth login` and then dumping by database name only: `turso db shell <database-name> ".dump" > mastra-cloud-dump.sql`. That flow requires the database to live in a Turso account you own, which is not the case for Cloud Store, so the env-var example above is provided as an alternative for this one-time export. If you prefer to avoid token interpolation entirely, ask support to run the dump on your behalf and send you the resulting SQL file.
+
+   The resulting `mastra-cloud-dump.sql` contains the full schema and data: thread and message history, workflow snapshots, traces, and eval scores. Store it somewhere safe before continuing.
+
+### Load the dump into a new libSQL database
+
+The dump is a standard SQL file and can be loaded into any libSQL-compatible database. The example below uses a new Turso-hosted database, which keeps the migration like-for-like and avoids schema translation.
+
+1. Authenticate the Turso CLI against your own Turso account.
+
+   ```bash
+   turso auth login
+   ```
+
+   If you do not have a Turso account, the CLI will prompt you to create one. See [Turso pricing](https://turso.tech/pricing) for plan details.
+
+2. Create a new database and load the dump in one step.
+
+   ```bash
+   turso db create mastra-migrated --from-dump ./mastra-cloud-dump.sql
+   ```
+
+   `--from-dump` restores a local SQLite/libSQL dump at create time, which is faster and safer than piping statements through `turso db shell` after the fact. Pick a region close to where your Mastra Server runs to minimize latency — list available regions with `turso db locations` and pass `--group <group-name>` if you manage multiple groups.
+
+   For multi-gigabyte dumps, add `--wait` so the CLI blocks until the database is fully available.
+
+3. Generate connection credentials for the new database.
+
+   ```bash
+   turso db show mastra-migrated --url
+   turso db tokens create mastra-migrated
+   ```
+
+   The first command prints the libSQL URL. The second prints an auth token. Both are needed by `LibSQLStore`.
+
+### Point your Mastra app at the new database
+
+Set the new credentials as environment variables, either locally in `.env` or in the Mastra platform dashboard:
+
+```bash
+TURSO_DATABASE_URL="libsql://mastra-migrated-<org>.turso.io"
+TURSO_AUTH_TOKEN="<token-from-turso-db-tokens-create>"
+```
+
+Configure `LibSQLStore` to read from those variables:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'libsql-storage',
+    url: process.env.TURSO_DATABASE_URL!,
+    authToken: process.env.TURSO_AUTH_TOKEN,
+  }),
+})
+```
+
+See the [libSQL storage reference](https://mastra.ai/reference/storage/libsql) for the full set of options.
+
+### Verify the migration
+
+Before decommissioning your Cloud project, confirm the new database serves the data your app expects.
+
+- Run `turso db shell mastra-migrated "SELECT name FROM sqlite_master WHERE type='table';"` to list tables. The output should include the Mastra-managed tables (e.g. `mastra_threads`, `mastra_messages`, `mastra_workflow_snapshot`, `mastra_traces`).
+- Run a row count against a known-populated table, for example `turso db shell mastra-migrated "SELECT COUNT(*) FROM mastra_messages;"`, and compare it to the same query against the Cloud Store URL.
+- Start your Mastra app against the new credentials and confirm that an existing thread or workflow run loads as expected in [Studio](https://mastra.ai/docs/studio/observability).
 
 ## Update observability configuration
 

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

@@ -1,6 +1,6 @@
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 62 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 63 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -43,6 +43,7 @@ ANTHROPIC_API_KEY=ant-...
 | `anthropic/claude-opus-4-5`                 |
 | `anthropic/claude-opus-4-5-20251101`        |
 | `anthropic/claude-opus-4-6`                 |
+| `anthropic/claude-opus-4-7`                 |
 | `anthropic/claude-sonnet-4-0`               |
 | `anthropic/claude-sonnet-4-20250514`        |
 | `anthropic/claude-sonnet-4-5`               |

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

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 170 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 171 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -41,6 +41,7 @@ ANTHROPIC_API_KEY=ant-...
 | `anthropic/claude-opus-4.1`                                     |
 | `anthropic/claude-opus-4.5`                                     |
 | `anthropic/claude-opus-4.6`                                     |
+| `anthropic/claude-opus-4.7`                                     |
 | `anthropic/claude-sonnet-4`                                     |
 | `anthropic/claude-sonnet-4.5`                                   |
 | `anthropic/claude-sonnet-4.6`                                   |

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

@@ -1,6 +1,6 @@
 # ![Vercel logo](https://models.dev/logos/vercel.svg)Vercel
 
-Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 231 models through Mastra's model router.
+Vercel aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 234 models through Mastra's model router.
 
 Learn more in the [Vercel documentation](https://ai-sdk.dev/providers/ai-sdk-providers).
 
@@ -72,6 +72,7 @@ ANTHROPIC_API_KEY=ant-...
 | `anthropic/claude-opus-4.1`                    |
 | `anthropic/claude-opus-4.5`                    |
 | `anthropic/claude-opus-4.6`                    |
+| `anthropic/claude-opus-4.7`                    |
 | `anthropic/claude-sonnet-4`                    |
 | `anthropic/claude-sonnet-4.5`                  |
 | `anthropic/claude-sonnet-4.6`                  |
@@ -119,6 +120,7 @@ ANTHROPIC_API_KEY=ant-...
 | `google/text-embedding-005`                    |
 | `google/text-multilingual-embedding-002`       |
 | `inception/mercury-2`                          |
+| `inception/mercury-coder-small`                |
 | `inception/mercury-edit-2`                     |
 | `kwaipilot/kat-coder-pro-v1`                   |
 | `kwaipilot/kat-coder-pro-v2`                   |
@@ -264,4 +266,5 @@ ANTHROPIC_API_KEY=ant-...
 | `zai/glm-4.7-flashx`                           |
 | `zai/glm-5`                                    |
 | `zai/glm-5-turbo`                              |
+| `zai/glm-5.1`                                  |
 | `zai/glm-5v-turbo`                             |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3596 models from 99 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 3610 models from 100 providers through a single API.
 
 ## Features
 
@@ -228,6 +228,41 @@ Mastra tries your primary model first. If it encounters a 500 error, rate limit,
 
 Your users never experience the disruption - the response comes back with the same format, just from a different model. The error context is preserved as the system moves through your fallback chain, ensuring clean error propagation while maintaining streaming compatibility.
 
+### Per-model settings
+
+Each fallback entry can carry its own `modelSettings`, `providerOptions`, and `headers` — useful when models in the chain need different temperatures or provider-specific knobs to produce comparable output.
+
+```typescript
+import { Agent } from '@mastra/core/agent';
+
+const agent = new Agent({
+  id: 'tuned-resilient',
+  name: 'Tuned Resilient Agent',
+  instructions: 'You are a helpful assistant.',
+  model: [
+    {
+      model: 'google/gemini-2.5-flash',
+      maxRetries: 2,
+      modelSettings: { temperature: 0.3 },
+      providerOptions: { google: { thinkingConfig: { thinkingBudget: 0 } } },
+    },
+    {
+      model: 'openai/gpt-5-mini',
+      maxRetries: 2,
+      modelSettings: { temperature: 0.7 },
+      providerOptions: { openai: { reasoningEffort: 'low' } },
+    },
+  ],
+});
+```
+
+**Precedence:**
+
+- `modelSettings` and `providerOptions`: per-fallback entry overrides call-time options, which override agent `defaultOptions`. `modelSettings` shallow-merges by key. `providerOptions` deep-merges recursively, so nested provider config (e.g. `google.thinkingConfig`) preserves sibling keys across layers.
+- `headers`: call-time `modelSettings.headers` overrides per-fallback `headers`, which overrides headers extracted from model-router models. Runtime headers (tracing, auth, tenancy) intentionally take precedence over model-level headers.
+
+Each field also accepts a function of `requestContext`, matching how dynamic models are resolved.
+
 ## Use local models with Mastra
 
 Mastra also supports local models like `gpt-oss`, `Qwen3`, `DeepSeek` and many more that you run on your own hardware. The application running your local model needs to provide an OpenAI-compatible API server for Mastra to connect to. We recommend using [LMStudio](https://lmstudio.ai/) (see [Running the LMStudio server](https://lmstudio.ai/docs/developer/core/server)).

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

@@ -1,6 +1,6 @@
 # ![Alibaba (China) logo](https://models.dev/logos/alibaba-cn.svg)Alibaba (China)
 
-Access 75 Alibaba (China) models through Mastra's model router. Authentication is handled automatically using the `DASHSCOPE_API_KEY` environment variable.
+Access 76 Alibaba (China) models through Mastra's model router. Authentication is handled automatically using the `DASHSCOPE_API_KEY` environment variable.
 
 Learn more in the [Alibaba (China) documentation](https://www.alibabacloud.com/help/en/model-studio/models).
 
@@ -46,6 +46,7 @@ for await (const chunk of stream) {
 | `alibaba-cn/deepseek-v3-1`                      | 131K    |       |           |       |       |       | $0.57      | $2          |
 | `alibaba-cn/deepseek-v3-2-exp`                  | 131K    |       |           |       |       |       | $0.29      | $0.43       |
 | `alibaba-cn/glm-5`                              | 203K    |       |           |       |       |       | $0.86      | $3          |
+| `alibaba-cn/glm-5.1`                            | 203K    |       |           |       |       |       | $0.87      | $3          |
 | `alibaba-cn/kimi-k2-thinking`                   | 262K    |       |           |       |       |       | $0.57      | $2          |
 | `alibaba-cn/kimi-k2.5`                          | 262K    |       |           |       |       |       | $0.57      | $2          |
 | `alibaba-cn/kimi/kimi-k2.5`                     | 262K    |       |           |       |       |       | $0.60      | $3          |

package/.docs/models/providers/anthropic.md

@@ -1,6 +1,6 @@
 # ![Anthropic logo](https://models.dev/logos/anthropic.svg)Anthropic
 
-Access 22 Anthropic models through Mastra's model router. Authentication is handled automatically using the `ANTHROPIC_API_KEY` environment variable.
+Access 23 Anthropic models through Mastra's model router. Authentication is handled automatically using the `ANTHROPIC_API_KEY` environment variable.
 
 Learn more in the [Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/models).
 
@@ -49,6 +49,7 @@ for await (const chunk of stream) {
 | `anthropic/claude-opus-4-5`            | 200K    |       |           |       |       |       | $5         | $25         |
 | `anthropic/claude-opus-4-5-20251101`   | 200K    |       |           |       |       |       | $5         | $25         |
 | `anthropic/claude-opus-4-6`            | 1.0M    |       |           |       |       |       | $5         | $25         |
+| `anthropic/claude-opus-4-7`            | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `anthropic/claude-sonnet-4-0`          | 200K    |       |           |       |       |       | $3         | $15         |
 | `anthropic/claude-sonnet-4-20250514`   | 200K    |       |           |       |       |       | $3         | $15         |
 | `anthropic/claude-sonnet-4-5`          | 200K    |       |           |       |       |       | $3         | $15         |

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

@@ -1,6 +1,6 @@
 # ![Cortecs logo](https://models.dev/logos/cortecs.svg)Cortecs
 
-Access 30 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
+Access 32 Cortecs models through Mastra's model router. Authentication is handled automatically using the `CORTECS_API_KEY` environment variable.
 
 Learn more in the [Cortecs documentation](https://cortecs.ai).
 
@@ -49,6 +49,7 @@ for await (const chunk of stream) {
 | `cortecs/glm-4.7`                        | 198K    |       |           |       |       |       | $0.45      | $2          |
 | `cortecs/glm-4.7-flash`                  | 203K    |       |           |       |       |       | $0.09      | $0.53       |
 | `cortecs/glm-5`                          | 203K    |       |           |       |       |       | $1         | $3          |
+| `cortecs/glm-5.1`                        | 205K    |       |           |       |       |       | $1         | $4          |
 | `cortecs/gpt-4.1`                        | 1.0M    |       |           |       |       |       | $2         | $9          |
 | `cortecs/gpt-oss-120b`                   | 128K    |       |           |       |       |       | —          | —           |
 | `cortecs/intellect-3`                    | 128K    |       |           |       |       |       | $0.22      | $1          |
@@ -59,6 +60,7 @@ for await (const chunk of stream) {
 | `cortecs/minimax-m2`                     | 400K    |       |           |       |       |       | $0.39      | $2          |
 | `cortecs/minimax-m2.1`                   | 196K    |       |           |       |       |       | $0.34      | $1          |
 | `cortecs/minimax-m2.5`                   | 197K    |       |           |       |       |       | $0.32      | $1          |
+| `cortecs/minimax-M2.7`                   | 203K    |       |           |       |       |       | $0.47      | $1          |
 | `cortecs/nova-pro-v1`                    | 300K    |       |           |       |       |       | $1         | $4          |
 | `cortecs/qwen3-32b`                      | 16K     |       |           |       |       |       | $0.10      | $0.33       |
 | `cortecs/qwen3-coder-480b-a35b-instruct` | 262K    |       |           |       |       |       | $0.44      | $2          |

package/.docs/models/providers/firmware.md

@@ -1,6 +1,6 @@
 # ![Firmware logo](https://models.dev/logos/firmware.svg)Firmware
 
-Access 25 Firmware models through Mastra's model router. Authentication is handled automatically using the `FIRMWARE_API_KEY` environment variable.
+Access 24 Firmware models through Mastra's model router. Authentication is handled automatically using the `FIRMWARE_API_KEY` environment variable.
 
 Learn more in the [Firmware documentation](https://docs.frogbot.ai).
 
@@ -35,9 +35,8 @@ for await (const chunk of stream) {
 | Model                                  | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | -------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `firmware/claude-haiku-4-5`            | 200K    |       |           |       |       |       | $1         | $5          |
-| `firmware/claude-opus-4-5`             | 200K    |       |           |       |       |       | $5         | $25         |
 | `firmware/claude-opus-4-6`             | 200K    |       |           |       |       |       | $5         | $25         |
-| `firmware/claude-sonnet-4-5`           | 200K    |       |           |       |       |       | $3         | $15         |
+| `firmware/claude-opus-4-7`             | 200K    |       |           |       |       |       | $5         | $25         |
 | `firmware/claude-sonnet-4-6`           | 200K    |       |           |       |       |       | $3         | $15         |
 | `firmware/deepseek-v3-2`               | 128K    |       |           |       |       |       | $0.58      | $2          |
 | `firmware/gemini-2.5-flash`            | 1.0M    |       |           |       |       |       | $0.30      | $3          |

package/.docs/models/providers/hpc-ai.md

@@ -0,0 +1,73 @@
+# ![HPC-AI logo](https://models.dev/logos/hpc-ai.svg)HPC-AI
+
+Access 3 HPC-AI models through Mastra's model router. Authentication is handled automatically using the `HPC_AI_API_KEY` environment variable.
+
+Learn more in the [HPC-AI documentation](https://www.hpc-ai.com/doc/docs/quickstart/).
+
+```bash
+HPC_AI_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "hpc-ai/minimax/minimax-m2.5"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [HPC-AI documentation](https://www.hpc-ai.com/doc/docs/quickstart/) for details.
+
+## Models
+
+| Model                         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ----------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `hpc-ai/minimax/minimax-m2.5` | 1.0M    |       |           |       |       |       | $0.14      | $0.56       |
+| `hpc-ai/moonshotai/kimi-k2.5` | 262K    |       |           |       |       |       | $0.21      | $1          |
+| `hpc-ai/zai-org/glm-5.1`      | 202K    |       |           |       |       |       | $0.66      | $2          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://api.hpc-ai.com/inference/v1",
+    id: "hpc-ai/minimax/minimax-m2.5",
+    apiKey: process.env.HPC_AI_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "hpc-ai/zai-org/glm-5.1"
+      : "hpc-ai/minimax/minimax-m2.5";
+  }
+});
+```

package/.docs/models/providers/nvidia.md

@@ -71,7 +71,7 @@ for await (const chunk of stream) {
 | `nvidia/microsoft/phi-4-mini-instruct`                 | 131K    |       |           |       |       |       | —          | —           |
 | `nvidia/minimaxai/minimax-m2.1`                        | 205K    |       |           |       |       |       | —          | —           |
 | `nvidia/minimaxai/minimax-m2.5`                        | 205K    |       |           |       |       |       | —          | —           |
-| `nvidia/minimaxai/minimax-m2.7`                        | 205K    |       |           |       |       |       | $0.30      | $1          |
+| `nvidia/minimaxai/minimax-m2.7`                        | 205K    |       |           |       |       |       | —          | —           |
 | `nvidia/mistralai/codestral-22b-instruct-v0.1`         | 128K    |       |           |       |       |       | —          | —           |
 | `nvidia/mistralai/devstral-2-123b-instruct-2512`       | 262K    |       |           |       |       |       | —          | —           |
 | `nvidia/mistralai/mamba-codestral-7b-v0.1`             | 128K    |       |           |       |       |       | —          | —           |

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

@@ -1,6 +1,6 @@
 # ![OpenCode Zen logo](https://models.dev/logos/opencode.svg)OpenCode Zen
 
-Access 34 OpenCode Zen models through Mastra's model router. Authentication is handled automatically using the `OPENCODE_API_KEY` environment variable.
+Access 35 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).
 
@@ -40,6 +40,7 @@ for await (const chunk of stream) {
 | `opencode/claude-opus-4-1`       | 200K    |       |           |       |       |       | $15        | $75         |
 | `opencode/claude-opus-4-5`       | 200K    |       |           |       |       |       | $5         | $25         |
 | `opencode/claude-opus-4-6`       | 1.0M    |       |           |       |       |       | $5         | $25         |
+| `opencode/claude-opus-4-7`       | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `opencode/claude-sonnet-4`       | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `opencode/claude-sonnet-4-5`     | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `opencode/claude-sonnet-4-6`     | 1.0M    |       |           |       |       |       | $3         | $15         |

package/.docs/models/providers/poe.md

@@ -1,6 +1,6 @@
 # ![Poe logo](https://models.dev/logos/poe.svg)Poe
 
-Access 117 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
+Access 118 Poe models through Mastra's model router. Authentication is handled automatically using the `POE_API_KEY` environment variable.
 
 Learn more in the [Poe documentation](https://creator.poe.com/docs/external-applications/openai-compatible-api).
 
@@ -41,6 +41,7 @@ for await (const chunk of stream) {
 | `poe/anthropic/claude-opus-4.1`        | 197K    |       |           |       |       |       | $13        | $64         |
 | `poe/anthropic/claude-opus-4.5`        | 197K    |       |           |       |       |       | $4         | $21         |
 | `poe/anthropic/claude-opus-4.6`        | 983K    |       |           |       |       |       | $4         | $21         |
+| `poe/anthropic/claude-opus-4.7`        | 1.0M    |       |           |       |       |       | $4         | $21         |
 | `poe/anthropic/claude-sonnet-3.7`      | 197K    |       |           |       |       |       | $3         | $13         |
 | `poe/anthropic/claude-sonnet-4`        | 983K    |       |           |       |       |       | $3         | $13         |
 | `poe/anthropic/claude-sonnet-4.5`      | 983K    |       |           |       |       |       | $3         | $13         |

package/.docs/models/providers/zenmux.md

@@ -1,6 +1,6 @@
 # ![ZenMux logo](https://models.dev/logos/zenmux.svg)ZenMux
 
-Access 87 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
+Access 88 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
 
 Learn more in the [ZenMux documentation](https://docs.zenmux.ai).
 
@@ -41,6 +41,7 @@ for await (const chunk of stream) {
 | `zenmux/anthropic/claude-opus-4.1`            | 200K    |       |           |       |       |       | $15        | $75         |
 | `zenmux/anthropic/claude-opus-4.5`            | 200K    |       |           |       |       |       | $5         | $25         |
 | `zenmux/anthropic/claude-opus-4.6`            | 1.0M    |       |           |       |       |       | $5         | $25         |
+| `zenmux/anthropic/claude-opus-4.7`            | 1.0M    |       |           |       |       |       | $5         | $25         |
 | `zenmux/anthropic/claude-sonnet-4`            | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `zenmux/anthropic/claude-sonnet-4.5`          | 1.0M    |       |           |       |       |       | $3         | $15         |
 | `zenmux/anthropic/claude-sonnet-4.6`          | 1.0M    |       |           |       |       |       | $3         | $15         |

package/.docs/models/providers.md

@@ -34,6 +34,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Friendli](https://mastra.ai/models/providers/friendli)
 - [GitHub Models](https://mastra.ai/models/providers/github-models)
 - [Helicone](https://mastra.ai/models/providers/helicone)
+- [HPC-AI](https://mastra.ai/models/providers/hpc-ai)
 - [Hugging Face](https://mastra.ai/models/providers/huggingface)
 - [iFlow](https://mastra.ai/models/providers/iflowcn)
 - [Inception](https://mastra.ai/models/providers/inception)

package/.docs/reference/agents/generate.md

@@ -300,6 +300,34 @@ const response = await agent.generate('Help me organize my day', {
 
 **options.includeRawChunks** (`boolean`): Whether to include raw chunks in the stream output. Not available on all model providers.
 
+## Response structure
+
+`Agent.generate()` returns the final data collected during execution. `steps` is an array of step objects. The tool arrays in the result, including top-level `toolCalls` and `toolResults` and the nested `step.toolCalls` and `step.toolResults` arrays, use Mastra's chunk format.
+
+That means tool data is wrapped in `payload`:
+
+```ts
+const response = await agent.generate('Check the weather in Lagos')
+
+for (const toolCall of response.toolCalls) {
+  console.log(toolCall.type) // 'tool-call'
+  console.log(toolCall.runId)
+  console.log(toolCall.from)
+  console.log(toolCall.payload.toolName)
+  console.log(toolCall.payload.args)
+}
+
+for (const step of response.steps) {
+  for (const toolResult of step.toolResults) {
+    console.log(toolResult.type) // 'tool-result'
+    console.log(toolResult.payload.toolName)
+    console.log(toolResult.payload.result)
+  }
+}
+```
+
+For the streaming version of the same chunk shape, see the [ChunkType reference](https://mastra.ai/reference/streaming/ChunkType).
+
 ## Returns
 
 **result** (`Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>`): Returns the full output of the generation process including text, object (if structured output), tool calls, tool results, usage statistics, and step information.
@@ -308,13 +336,59 @@ const response = await agent.generate('Help me organize my day', {
 
 **object** (`Output | undefined`): The structured output object if structuredOutput was provided, validated against the schema.
 
-**toolCalls** (`ToolCall[]`): Array of tool calls made during generation.
+**toolCalls** (`ToolCallChunk[]`): Array of tool call chunks made during generation.
+
+**toolCalls.type** (`'tool-call'`): Chunk type identifier.
+
+**toolCalls.runId** (`string`): Execution run identifier.
+
+**toolCalls.from** (`ChunkFrom`): Source of the chunk, such as AGENT or WORKFLOW.
+
+**toolCalls.payload** (`ToolCallPayload`): Tool call data.
+
+**toolCalls.payload.toolCallId** (`string`): Unique identifier for the tool call.
+
+**toolCalls.payload.toolName** (`string`): Name of the tool that was called.
+
+**toolCalls.payload.args** (`Record<string, unknown>`): Arguments passed to the tool.
+
+**toolCalls.payload.providerExecuted** (`boolean`): Whether the model provider executed the tool directly.
 
-**toolResults** (`ToolResult[]`): Array of results from tool executions.
+**toolResults** (`ToolResultChunk[]`): Array of tool result chunks from tool executions.
+
+**toolResults.type** (`'tool-result'`): Chunk type identifier.
+
+**toolResults.runId** (`string`): Execution run identifier.
+
+**toolResults.from** (`ChunkFrom`): Source of the chunk, such as AGENT or WORKFLOW.
+
+**toolResults.payload** (`ToolResultPayload`): Tool result data.
+
+**toolResults.payload.toolCallId** (`string`): Unique identifier for the tool call.
+
+**toolResults.payload.toolName** (`string`): Name of the tool that produced the result.
+
+**toolResults.payload.result** (`unknown`): Value returned by the tool.
+
+**toolResults.payload.isError** (`boolean`): Whether the tool execution failed.
 
 **usage** (`TokenUsage`): Token usage statistics for the generation.
 
-**steps** (`Step[]`): Array of execution steps, useful for debugging multi-step generations.
+**steps** (`object[]`): Array of execution steps, useful for debugging multi-step generations.
+
+**steps.text** (`string`): Text generated in this step.
+
+**steps.toolCalls** (`ToolCallChunk[]`): Tool calls emitted during this step.
+
+**steps.toolResults** (`ToolResultChunk[]`): Tool results emitted during this step.
+
+**steps.finishReason** (`string`): Why this step finished.
+
+**steps.usage** (`LanguageModelUsage`): Token usage for this step.
+
+**steps.request** (`{ body?: unknown }`): Request metadata for this step.
+
+**steps.response** (`object`): Response metadata for this step.
 
 **finishReason** (`string`): The reason generation finished. Values include 'stop' (normal completion), 'tool-calls' (ended with tool calls), 'suspended' (waiting for tool approval), or 'error' (error occurred).
 

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

@@ -12,6 +12,29 @@ export const mastraClient = new MastraClient({
 })
 ```
 
+## `RequestContext`
+
+When you use `RequestContext` with the client SDK, import it from `@mastra/client-js`.
+
+```typescript
+import { MastraClient, RequestContext } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111/',
+})
+
+const requestContext = new RequestContext()
+requestContext.set('userId', 'user-123')
+
+const agent = client.getAgent('support-agent')
+
+const response = await agent.generate('Summarize this ticket', {
+  requestContext,
+})
+```
+
+You can also pass `requestContext` as a `Record<string, any>`.
+
 ## Parameters
 
 **baseUrl** (`string`): The base URL for the Mastra API. All requests will be sent relative to this URL.

package/.docs/reference/index.md

@@ -284,6 +284,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [AgentFSFilesystem](https://mastra.ai/reference/workspace/agentfs-filesystem)
 - [BlaxelSandbox](https://mastra.ai/reference/workspace/blaxel-sandbox)
 - [DaytonaSandbox](https://mastra.ai/reference/workspace/daytona-sandbox)
+- [DockerSandbox](https://mastra.ai/reference/workspace/docker-sandbox)
 - [E2BSandbox](https://mastra.ai/reference/workspace/e2b-sandbox)
 - [GCSFilesystem](https://mastra.ai/reference/workspace/gcs-filesystem)
 - [LocalFilesystem](https://mastra.ai/reference/workspace/local-filesystem)

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

@@ -36,6 +36,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **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'`)
 
+**activateAfterIdle** (`number | string`): Time before buffered observations or buffered reflections are forced to activate after inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like \`300\_000\`, \`"5m"\`, or \`"1hr"\`. When the gap between the current time and the last assistant message part timestamp exceeds this value, buffered observational memory activates before the next prompt. Useful for aligning with prompt cache TTLs.
+
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
 **retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -1,5 +1,7 @@
 # CloudExporter
 
+**Added in:** `@mastra/observability@1.8.0`
+
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 
 ## Constructor
@@ -56,9 +58,9 @@ Extends `BaseExporterConfig`, which includes:
 
 The exporter reads these environment variables if not provided in config:
 
-- `MASTRA_CLOUD_ACCESS_TOKEN` - Authentication token. Project-scoped tokens work with the default `/ai/{signal}/publish` routes. Organization API keys require `projectId` or `MASTRA_PROJECT_ID`.
+- `MASTRA_CLOUD_ACCESS_TOKEN` - Authentication token for `CloudExporter` requests
 - `MASTRA_PROJECT_ID` - Project ID to use when deriving project-scoped collector routes such as `/projects/:projectId/ai/spans/publish`
-- `MASTRA_CLOUD_TRACES_ENDPOINT` - Traces endpoint override. Pass either a base origin or a full traces publish URL. Defaults to `https://api.mastra.ai`
+- `MASTRA_CLOUD_TRACES_ENDPOINT` - Traces endpoint override. Pass either a base origin or a full traces publish URL. Defaults to `https://observability.mastra.ai` in `@mastra/observability@1.9.2` and later
 
 ## Properties
 

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

@@ -0,0 +1,196 @@
+# DockerSandbox
+
+Executes commands inside Docker containers on the local machine. Uses long-lived containers with `docker exec` for command execution. Targets local development, CI/CD, air-gapped deployments, and cost-sensitive scenarios where cloud sandboxes are unnecessary.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/docker
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/docker
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/docker
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/docker
+```
+
+Requires [Docker Engine](https://docs.docker.com/engine/install/) running on the host machine.
+
+## Usage
+
+Add a `DockerSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { DockerSandbox } from '@mastra/docker'
+
+const workspace = new Workspace({
+  sandbox: new DockerSandbox({
+    image: 'node:22-slim',
+  }),
+})
+
+const agent = new Agent({
+  name: 'dev-agent',
+  model: 'anthropic/claude-opus-4-6',
+  workspace,
+})
+```
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for this sandbox instance. Used for container naming and reconnection via labels. (Default: `Auto-generated`)
+
+**image** (`string`): Docker image to use for the container. (Default: `'node:22-slim'`)
+
+**command** (`string[]`): Container entrypoint command. Must keep the container alive for exec-based command execution. (Default: `['sleep', 'infinity']`)
+
+**env** (`Record<string, string>`): Environment variables to set in the container.
+
+**volumes** (`Record<string, string>`): Host-to-container bind mounts. Keys are host paths, values are container paths.
+
+**network** (`string`): Docker network to join.
+
+**privileged** (`boolean`): Run in privileged mode. (Default: `false`)
+
+**workingDir** (`string`): Working directory inside the container. (Default: `'/workspace'`)
+
+**labels** (`Record<string, string>`): Additional container labels. Mastra labels (mastra.sandbox, mastra.sandbox.id) are always included.
+
+**timeout** (`number`): Default command timeout in milliseconds. (Default: `300000 (5 minutes)`)
+
+**dockerOptions** (`Docker.DockerOptions`): Pass-through dockerode connection options for custom socket paths, remote hosts, or TLS certificates.
+
+**instructions** (`string | function`): Custom instructions that override the default instructions returned by getInstructions(). Pass an empty string to suppress instructions.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): Provider name ('DockerSandbox').
+
+**provider** (`string`): Provider identifier ('docker').
+
+**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
+
+**container** (`Container`): The underlying dockerode Container instance. Throws SandboxNotReadyError if the sandbox has not been started.
+
+**processes** (`DockerProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
+
+## Background processes
+
+`DockerSandbox` includes a built-in process manager for spawning and managing background processes. Processes run inside the container using `docker exec`.
+
+```typescript
+const sandbox = new DockerSandbox({ id: 'dev-sandbox' })
+await sandbox._start()
+
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node server.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
+})
+
+// Interact with the process
+console.log(handle.stdout)
+await handle.sendStdin('input\n')
+await handle.kill()
+```
+
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
+
+## Environment variables
+
+Set environment variables at the container level with `env`. Per-command environment variables can also be passed when spawning processes:
+
+```typescript
+const sandbox = new DockerSandbox({
+  image: 'node:22-slim',
+  env: {
+    NODE_ENV: 'production',
+    DATABASE_URL: 'postgres://localhost:5432/mydb',
+  },
+})
+```
+
+## Bind mounts
+
+Mount host directories into the container using the `volumes` option:
+
+```typescript
+const sandbox = new DockerSandbox({
+  image: 'node:22-slim',
+  volumes: {
+    '/my/project': '/workspace/project',
+    '/shared/data': '/data',
+  },
+})
+```
+
+Bind mounts are applied at container creation time. The host paths must exist before the sandbox starts.
+
+## Reconnection
+
+`DockerSandbox` can reconnect to existing containers by matching labels. When `start()` is called, it checks for a container with the `mastra.sandbox.id` label matching the sandbox ID. If found:
+
+- A running container is reused directly.
+- A stopped container is restarted.
+
+```typescript
+// First run — creates a new container
+const sandbox = new DockerSandbox({ id: 'persistent-sandbox' })
+await sandbox._start()
+
+// Later — reconnects to the existing container
+const sandbox2 = new DockerSandbox({ id: 'persistent-sandbox' })
+await sandbox2._start()
+```
+
+## Docker connection options
+
+Connect to remote Docker hosts or use custom socket paths via `dockerOptions`:
+
+```typescript
+// Remote Docker host
+const sandbox = new DockerSandbox({
+  dockerOptions: {
+    host: '192.168.1.100',
+    port: 2376,
+    ca: fs.readFileSync('ca.pem'),
+    cert: fs.readFileSync('cert.pem'),
+    key: fs.readFileSync('key.pem'),
+  },
+})
+
+// Custom socket path
+const sandbox = new DockerSandbox({
+  dockerOptions: {
+    socketPath: '/var/run/docker.sock',
+  },
+})
+```
+
+## Related
+
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [LocalSandbox reference](https://mastra.ai/reference/workspace/local-sandbox)
+- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @mastra/mcp-docs-server
 
+## 1.1.26-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`92dcf02`](https://github.com/mastra-ai/mastra/commit/92dcf029294210ac91b090900c1a0555a425c57a)]:
+  - @mastra/core@1.26.0-alpha.5
+
+## 1.1.26-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`0474c2b`](https://github.com/mastra-ai/mastra/commit/0474c2b2e7c7e1ad8691dca031284841391ff1ef), [`f607106`](https://github.com/mastra-ai/mastra/commit/f607106854c6416c4a07d4082604b9f66d047221), [`62919a6`](https://github.com/mastra-ai/mastra/commit/62919a6ee0fbf3779ad21a97b1ec6696515d5104), [`0fd90a2`](https://github.com/mastra-ai/mastra/commit/0fd90a215caf5fca8099c15a67ca03e4427747a3)]:
+  - @mastra/core@1.26.0-alpha.4
+
+## 1.1.26-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`fdd54cf`](https://github.com/mastra-ai/mastra/commit/fdd54cf612a9af876e9fdd85e534454f6e7dd518), [`30456b6`](https://github.com/mastra-ai/mastra/commit/30456b6b08c8fd17e109dd093b73d93b65e83bc5), [`9d11a8c`](https://github.com/mastra-ai/mastra/commit/9d11a8c1c8924eb975a245a5884d40ca1b7e0491), [`d246696`](https://github.com/mastra-ai/mastra/commit/d246696139a3144a5b21b042d41c532688e957e1), [`354f9ce`](https://github.com/mastra-ai/mastra/commit/354f9ce1ca6af2074b6a196a23f8ec30012dccca), [`e9837b5`](https://github.com/mastra-ai/mastra/commit/e9837b53699e18711b09e0ca010a4106376f2653)]:
+  - @mastra/core@1.26.0-alpha.3
+  - @mastra/mcp@1.5.1-alpha.1
+
+## 1.1.26-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`3d83d06`](https://github.com/mastra-ai/mastra/commit/3d83d06f776f00fb5f4163dddd32a030c5c20844), [`7e0e63e`](https://github.com/mastra-ai/mastra/commit/7e0e63e2e485e84442351f4c7a79a424c83539dc), [`9467ea8`](https://github.com/mastra-ai/mastra/commit/9467ea87695749a53dfc041576410ebf9ee7bb67), [`7338d94`](https://github.com/mastra-ai/mastra/commit/7338d949380cf68b095342e8e42610dc51d557c1), [`c65aec3`](https://github.com/mastra-ai/mastra/commit/c65aec356cc037ee7c4b30ccea946807d4c4f443)]:
+  - @mastra/core@1.26.0-alpha.2
+  - @mastra/mcp@1.5.1-alpha.1
+
+## 1.1.26-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`7020c06`](https://github.com/mastra-ai/mastra/commit/7020c0690b199d9da337f0e805f16948e557922e), [`7020c06`](https://github.com/mastra-ai/mastra/commit/7020c0690b199d9da337f0e805f16948e557922e)]:
+  - @mastra/mcp@1.5.1-alpha.0
+  - @mastra/core@1.25.1-alpha.1
+
+## 1.1.26-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`d63ffdb`](https://github.com/mastra-ai/mastra/commit/d63ffdbb2c11e76fe5ea45faab44bc15460f010c)]:
+  - @mastra/core@1.25.1-alpha.0
+
 ## 1.1.25
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.25",
+  "version": "1.1.26-alpha.10",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.3.6",
-    "@mastra/core": "1.25.0",
-    "@mastra/mcp": "^1.5.0"
+    "@mastra/mcp": "^1.5.1-alpha.1",
+    "@mastra/core": "1.26.0-alpha.5"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "4.0.18",
-    "@mastra/core": "1.25.0",
     "@internal/lint": "0.0.83",
-    "@internal/types-builder": "0.0.58"
+    "@internal/types-builder": "0.0.58",
+    "@mastra/core": "1.26.0-alpha.5"
   },
   "homepage": "https://mastra.ai",
   "repository": {