@mastra/mcp-docs-server 1.1.29-alpha.9 → 1.1.30-alpha.2

package/.docs/models/providers/deepinfra.md

@@ -1,6 +1,6 @@
 # ![Deep Infra logo](https://models.dev/logos/deepinfra.svg)Deep Infra
 
-Access 32 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
+Access 33 Deep Infra models through Mastra's model router. Authentication is handled automatically using the `DEEPINFRA_API_KEY` environment variable.
 
 Learn more in the [Deep Infra documentation](https://deepinfra.com/models).
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
 | `deepinfra/anthropic/claude-4-opus`                           | 200K    |       |           |       |       |       | $17        | $83         |
 | `deepinfra/deepseek-ai/DeepSeek-R1-0528`                      | 164K    |       |           |       |       |       | $0.50      | $2          |
 | `deepinfra/deepseek-ai/DeepSeek-V3.2`                         | 164K    |       |           |       |       |       | $0.26      | $0.38       |
+| `deepinfra/deepseek-ai/DeepSeek-V4-Pro`                       | 66K     |       |           |       |       |       | $2         | $3          |
 | `deepinfra/meta-llama/Llama-3.1-70B-Instruct`                 | 131K    |       |           |       |       |       | $0.40      | $0.40       |
 | `deepinfra/meta-llama/Llama-3.1-70B-Instruct-Turbo`           | 131K    |       |           |       |       |       | $0.40      | $0.40       |
 | `deepinfra/meta-llama/Llama-3.1-8B-Instruct`                  | 131K    |       |           |       |       |       | $0.02      | $0.05       |

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

@@ -1,6 +1,6 @@
 # ![Fireworks AI logo](https://models.dev/logos/fireworks-ai.svg)Fireworks AI
 
-Access 18 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
+Access 19 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
 
 Learn more in the [Fireworks AI documentation](https://fireworks.ai/docs/).
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
 | --------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `fireworks-ai/accounts/fireworks/models/deepseek-v3p1`    | 164K    |       |           |       |       |       | $0.56      | $2          |
 | `fireworks-ai/accounts/fireworks/models/deepseek-v3p2`    | 160K    |       |           |       |       |       | $0.56      | $2          |
+| `fireworks-ai/accounts/fireworks/models/deepseek-v4-pro`  | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `fireworks-ai/accounts/fireworks/models/glm-4p5`          | 131K    |       |           |       |       |       | $0.55      | $2          |
 | `fireworks-ai/accounts/fireworks/models/glm-4p5-air`      | 131K    |       |           |       |       |       | $0.22      | $0.88       |
 | `fireworks-ai/accounts/fireworks/models/glm-4p7`          | 198K    |       |           |       |       |       | $0.60      | $2          |

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

@@ -1,6 +1,6 @@
 # ![Kilo Gateway logo](https://models.dev/logos/kilo.svg)Kilo Gateway
 
-Access 335 Kilo Gateway models through Mastra's model router. Authentication is handled automatically using the `KILO_API_KEY` environment variable.
+Access 337 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).
 
@@ -357,6 +357,8 @@ for await (const chunk of stream) {
 | `kilo/xiaomi/mimo-v2-flash`                         | 262K    |       |           |       |       |       | $0.09      | $0.29       |
 | `kilo/xiaomi/mimo-v2-omni`                          | 262K    |       |           |       |       |       | $0.40      | $2          |
 | `kilo/xiaomi/mimo-v2-pro`                           | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `kilo/xiaomi/mimo-v2.5`                             | 1.0M    |       |           |       |       |       | $0.40      | $2          |
+| `kilo/xiaomi/mimo-v2.5-pro`                         | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `kilo/z-ai/glm-4-32b`                               | 128K    |       |           |       |       |       | $0.10      | $0.10       |
 | `kilo/z-ai/glm-4.5`                                 | 131K    |       |           |       |       |       | $0.60      | $2          |
 | `kilo/z-ai/glm-4.5-air`                             | 131K    |       |           |       |       |       | $0.13      | $0.85       |

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

@@ -1,6 +1,6 @@
 # ![Nvidia logo](https://models.dev/logos/nvidia.svg)Nvidia
 
-Access 79 Nvidia models through Mastra's model router. Authentication is handled automatically using the `NVIDIA_API_KEY` environment variable.
+Access 80 Nvidia models through Mastra's model router. Authentication is handled automatically using the `NVIDIA_API_KEY` environment variable.
 
 Learn more in the [Nvidia documentation](https://docs.api.nvidia.com/nim/).
 
@@ -95,6 +95,7 @@ for await (const chunk of stream) {
 | `nvidia/nvidia/llama3-chatqa-1.5-70b`                  | 128K    |       |           |       |       |       | —          | —           |
 | `nvidia/nvidia/nemoretriever-ocr-v1`                   | —       |       |           |       |       |       | —          | —           |
 | `nvidia/nvidia/nemotron-3-nano-30b-a3b`                | 131K    |       |           |       |       |       | —          | —           |
+| `nvidia/nvidia/nemotron-3-nano-omni-30b-a3b-reasoning` | 256K    |       |           |       |       |       | —          | —           |
 | `nvidia/nvidia/nemotron-3-super-120b-a12b`             | 262K    |       |           |       |       |       | $0.20      | $0.80       |
 | `nvidia/nvidia/nemotron-4-340b-instruct`               | 128K    |       |           |       |       |       | —          | —           |
 | `nvidia/nvidia/nvidia-nemotron-nano-9b-v2`             | 131K    |       |           |       |       |       | —          | —           |

package/.docs/models/providers/openai.md

@@ -1,6 +1,6 @@
 # ![OpenAI logo](https://models.dev/logos/openai.svg)OpenAI
 
-Access 51 OpenAI models through Mastra's model router. Authentication is handled automatically using the `OPENAI_API_KEY` environment variable.
+Access 52 OpenAI models through Mastra's model router. Authentication is handled automatically using the `OPENAI_API_KEY` environment variable.
 
 Learn more in the [OpenAI documentation](https://platform.openai.com/docs/models).
 
@@ -67,6 +67,7 @@ for await (const chunk of stream) {
 | `openai/gpt-5.4-nano`           | 400K    |       |           |       |       |       | $0.20      | $1          |
 | `openai/gpt-5.4-pro`            | 1.1M    |       |           |       |       |       | $30        | $180        |
 | `openai/gpt-5.5`                | 1.1M    |       |           |       |       |       | $5         | $30         |
+| `openai/gpt-5.5-pro`            | 1.1M    |       |           |       |       |       | $30        | $180        |
 | `openai/gpt-image-1`            | —       |       |           |       |       |       | —          | —           |
 | `openai/gpt-image-1-mini`       | —       |       |           |       |       |       | —          | —           |
 | `openai/gpt-image-1.5`          | —       |       |           |       |       |       | —          | —           |

package/.docs/models/providers/wandb.md

@@ -1,6 +1,6 @@
 # ![Weights & Biases logo](https://models.dev/logos/wandb.svg)Weights & Biases
 
-Access 17 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
+Access 18 Weights & Biases models through Mastra's model router. Authentication is handled automatically using the `WANDB_API_KEY` environment variable.
 
 Learn more in the [Weights & Biases documentation](https://docs.wandb.ai).
 
@@ -51,6 +51,7 @@ for await (const chunk of stream) {
 | `wandb/Qwen/Qwen3-30B-A3B-Instruct-2507`             | 262K    |       |           |       |       |       | $0.10      | $0.30       |
 | `wandb/Qwen/Qwen3-Coder-480B-A35B-Instruct`          | 262K    |       |           |       |       |       | $1         | $2          |
 | `wandb/zai-org/GLM-5-FP8`                            | 200K    |       |           |       |       |       | $1         | $3          |
+| `wandb/zai-org/GLM-5.1`                              | 200K    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration
 
@@ -80,7 +81,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "wandb/zai-org/GLM-5-FP8"
+      ? "wandb/zai-org/GLM-5.1"
       : "wandb/MiniMaxAI/MiniMax-M2.5";
   }
 });

package/.docs/models/providers/zai-coding-plan.md

@@ -1,6 +1,6 @@
 # ![Z.AI Coding Plan logo](https://models.dev/logos/zai-coding-plan.svg)Z.AI Coding Plan
 
-Access 4 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
+Access 5 Z.AI Coding Plan models through Mastra's model router. Authentication is handled automatically using the `ZHIPU_API_KEY` environment variable.
 
 Learn more in the [Z.AI Coding Plan documentation](https://docs.z.ai/devpack/overview).
 
@@ -32,12 +32,13 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                         | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| ----------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `zai-coding-plan/glm-4.5-air` | 131K    |       |           |       |       |       | —          | —           |
-| `zai-coding-plan/glm-4.7`     | 205K    |       |           |       |       |       | —          | —           |
-| `zai-coding-plan/glm-5-turbo` | 200K    |       |           |       |       |       | —          | —           |
-| `zai-coding-plan/glm-5.1`     | 200K    |       |           |       |       |       | —          | —           |
+| Model                          | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------------------------ | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `zai-coding-plan/glm-4.5-air`  | 131K    |       |           |       |       |       | —          | —           |
+| `zai-coding-plan/glm-4.7`      | 205K    |       |           |       |       |       | —          | —           |
+| `zai-coding-plan/glm-5-turbo`  | 200K    |       |           |       |       |       | —          | —           |
+| `zai-coding-plan/glm-5.1`      | 200K    |       |           |       |       |       | —          | —           |
+| `zai-coding-plan/glm-5v-turbo` | 200K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration
 
@@ -67,7 +68,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "zai-coding-plan/glm-5.1"
+      ? "zai-coding-plan/glm-5v-turbo"
       : "zai-coding-plan/glm-4.5-air";
   }
 });

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

@@ -1,6 +1,6 @@
 # ![ZenMux logo](https://models.dev/logos/zenmux.svg)ZenMux
 
-Access 89 ZenMux models through Mastra's model router. Authentication is handled automatically using the `ZENMUX_API_KEY` environment variable.
+Access 96 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).
 
@@ -49,6 +49,8 @@ for await (const chunk of stream) {
 | `zenmux/deepseek/deepseek-chat`               | 128K    |       |           |       |       |       | $0.28      | $0.42       |
 | `zenmux/deepseek/deepseek-v3.2`               | 128K    |       |           |       |       |       | $0.28      | $0.43       |
 | `zenmux/deepseek/deepseek-v3.2-exp`           | 163K    |       |           |       |       |       | $0.22      | $0.33       |
+| `zenmux/deepseek/deepseek-v4-flash`           | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `zenmux/deepseek/deepseek-v4-pro`             | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `zenmux/google/gemini-2.5-flash`              | 1.0M    |       |           |       |       |       | $0.30      | $3          |
 | `zenmux/google/gemini-2.5-flash-lite`         | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
 | `zenmux/google/gemini-2.5-pro`                | 1.0M    |       |           |       |       |       | $1         | $10         |
@@ -84,6 +86,8 @@ for await (const chunk of stream) {
 | `zenmux/openai/gpt-5.4-mini`                  | 400K    |       |           |       |       |       | $0.75      | $5          |
 | `zenmux/openai/gpt-5.4-nano`                  | 400K    |       |           |       |       |       | $0.20      | $1          |
 | `zenmux/openai/gpt-5.4-pro`                   | 1.1M    |       |           |       |       |       | $45        | $225        |
+| `zenmux/openai/gpt-5.5`                       | 1.1M    |       |           |       |       |       | $5         | $30         |
+| `zenmux/openai/gpt-5.5-pro`                   | 1.1M    |       |           |       |       |       | $30        | $180        |
 | `zenmux/qwen/qwen3-coder-plus`                | 1.0M    |       |           |       |       |       | $1         | $5          |
 | `zenmux/qwen/qwen3-max`                       | 256K    |       |           |       |       |       | $1         | $6          |
 | `zenmux/qwen/qwen3.5-flash`                   | 1.0M    |       |           |       |       |       | $0.10      | $0.40       |
@@ -94,6 +98,7 @@ for await (const chunk of stream) {
 | `zenmux/stepfun/step-3`                       | 66K     |       |           |       |       |       | $0.21      | $0.57       |
 | `zenmux/stepfun/step-3.5-flash`               | 256K    |       |           |       |       |       | $0.10      | $0.30       |
 | `zenmux/stepfun/step-3.5-flash-free`          | 256K    |       |           |       |       |       | —          | —           |
+| `zenmux/tencent/hy3-preview`                  | 256K    |       |           |       |       |       | $0.17      | $0.57       |
 | `zenmux/volcengine/doubao-seed-1.8`           | 256K    |       |           |       |       |       | $0.11      | $0.28       |
 | `zenmux/volcengine/doubao-seed-2.0-code`      | 256K    |       |           |       |       |       | $0.90      | $4          |
 | `zenmux/volcengine/doubao-seed-2.0-lite`      | 256K    |       |           |       |       |       | $0.09      | $0.51       |
@@ -110,6 +115,8 @@ for await (const chunk of stream) {
 | `zenmux/xiaomi/mimo-v2-flash`                 | 262K    |       |           |       |       |       | $0.10      | $0.30       |
 | `zenmux/xiaomi/mimo-v2-omni`                  | 265K    |       |           |       |       |       | $0.40      | $2          |
 | `zenmux/xiaomi/mimo-v2-pro`                   | 1.0M    |       |           |       |       |       | $2         | $5          |
+| `zenmux/xiaomi/mimo-v2.5`                     | 1.0M    |       |           |       |       |       | $0.40      | $2          |
+| `zenmux/xiaomi/mimo-v2.5-pro`                 | 1.0M    |       |           |       |       |       | $1         | $3          |
 | `zenmux/z-ai/glm-4.5`                         | 128K    |       |           |       |       |       | $0.35      | $2          |
 | `zenmux/z-ai/glm-4.5-air`                     | 128K    |       |           |       |       |       | $0.11      | $0.56       |
 | `zenmux/z-ai/glm-4.6`                         | 200K    |       |           |       |       |       | $0.35      | $2          |

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

@@ -151,6 +151,30 @@ for await (const part of uiMessageStream) {
 }
 ```
 
+### `streamUntilIdle()`
+
+Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call falls through to a plain `stream()`.
+
+```typescript
+const response = await agent.streamUntilIdle('Research solana for me', {
+  memory: {
+    thread: 'thread-1',
+    resource: 'resource-1',
+  },
+  maxIdleMs: 5 * 60_000,
+})
+
+response.processDataStream({
+  onChunk: async chunk => {
+    if (chunk.type === 'background-task-completed') {
+      console.log('task complete:', chunk.payload.taskId)
+    }
+  },
+})
+```
+
+The stream emits the same chunk types as `stream()`, plus `background-task-*` chunks for task lifecycle events. Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full server-side API and [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the payload shapes.
+
 ### `getTool()`
 
 Retrieve information about a specific tool available to the agent:

package/.docs/reference/configuration.md

@@ -36,6 +36,69 @@ export const mastra = new Mastra({
 })
 ```
 
+### backgroundTasks
+
+**Type:** `BackgroundTaskManagerConfig`
+
+Enables and configures the background task manager. When enabled, agents can dispatch long-running tool calls (including subagent invocations) to run asynchronously while the agentic loop continues. Tasks are persisted, so a configured `storage` backend is required.
+
+Visit the [Background tasks documentation](https://mastra.ai/docs/agents/background-tasks) to learn more.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+  backgroundTasks: {
+    enabled: true,
+    globalConcurrency: 10,
+    perAgentConcurrency: 5,
+    backpressure: 'queue',
+    defaultTimeoutMs: 300_000,
+  },
+})
+```
+
+**enabled** (`boolean`): Whether background tasks are enabled. The manager only initializes when this is true and a storage backend is configured. (Default: `false`)
+
+**globalConcurrency** (`number`): Maximum number of background tasks running concurrently across all agents. (Default: `10`)
+
+**perAgentConcurrency** (`number`): Maximum number of background tasks running concurrently for a single agent. (Default: `5`)
+
+**backpressure** (`'queue' | 'reject' | 'fallback-sync'`): Behavior when a concurrency limit is reached. 'queue' waits for a slot, 'reject' throws on enqueue, 'fallback-sync' runs the tool synchronously in the agentic loop instead. (Default: `'queue'`)
+
+**defaultTimeoutMs** (`number`): Default per-task timeout in milliseconds. Can be overridden per-tool or per-call. (Default: `300000`)
+
+**defaultRetries** (`RetryConfig`): Default retry policy applied to tasks that fail.
+
+**defaultRetries.maxRetries** (`number`): Maximum retry attempts before the task is marked failed.
+
+**defaultRetries.retryDelayMs** (`number`): Delay between retries in milliseconds.
+
+**defaultRetries.backoffMultiplier** (`number`): Multiplier applied to retryDelayMs on each subsequent attempt.
+
+**defaultRetries.maxRetryDelayMs** (`number`): Upper bound on the retry delay regardless of backoff.
+
+**defaultRetries.retryableErrors** (`(error: Error) => boolean`): Predicate that decides whether a given error should be retried. Default: retry all errors.
+
+**cleanup** (`CleanupConfig`): Controls how long task records are kept and how often the cleanup process runs.
+
+**cleanup.completedTtlMs** (`number`): How long to keep completed task records, in milliseconds. Default: 1 hour.
+
+**cleanup.failedTtlMs** (`number`): How long to keep failed task records, in milliseconds. Default: 24 hours.
+
+**cleanup.cleanupIntervalMs** (`number`): How often the cleanup process runs, in milliseconds. Default: 1 minute.
+
+**waitTimeoutMs** (`number`): How long the agentic loop waits for a background task to complete before moving on. If a task has not finished within this time, the loop proceeds without setting isContinued. Default: undefined (do not wait). Can be overridden per-agent or per-tool.
+
+**onTaskComplete** (`(task: BackgroundTask) => void | Promise<void>`): Global callback invoked when any background task completes successfully. Fires in addition to per-tool and per-agent callbacks.
+
+**onTaskFailed** (`(task: BackgroundTask) => void | Promise<void>`): Global callback invoked when any background task fails. Fires in addition to per-tool and per-agent callbacks.
+
 ### deployer
 
 **Type:** `MastraDeployer`

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

@@ -90,6 +90,8 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **subagents.stopWhen** (`LoopOptions['stopWhen']`): Optional stop condition for the spawned subagent.
 
+**subagents.forked** (`boolean`): When \`true\`, calls to this subagent default to forked mode: the subagent runs on a clone of the parent thread, reusing the parent agent’s instructions, tools, and model so the prompt-cache prefix stays intact. Requires \`memory\` to be configured. The subagent definition’s own \`instructions\`, \`tools\`, \`allowedHarnessTools\`, \`allowedWorkspaceTools\`, \`defaultModelId\`, \`maxSteps\`, and \`stopWhen\` are ignored in forked mode. Callers can still override per-invocation via \`forked: false\` in the \`subagent\` tool input. See the \[Forked subagents]\(#forked-subagents) section below for full semantics.
+
 **resolveModel** (`(modelId: string) => MastraLanguageModel`): Converts a model ID string (e.g., \`"anthropic/claude-sonnet-4"\`) to a language model instance. Used by subagents and observational memory model resolution.
 
 **omConfig** (`HarnessOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).
@@ -286,16 +288,21 @@ await harness.switchThread({ threadId: 'thread-abc123' })
 
 #### `listThreads(options?)`
 
-List threads from storage. By default, only threads for the current resource are returned.
+List threads from storage. By default, only threads for the current resource are returned, and transient [forked subagent](#forked-subagents) threads are hidden so they don’t appear in user-facing thread pickers / startup flows.
 
 ```typescript
-// List threads for current resource
+// List threads for current resource (forks hidden)
 const threads = await harness.listThreads()
 
-// List all threads across resources
+// List all threads across resources (forks still hidden)
 const allThreads = await harness.listThreads({ allResources: true })
+
+// Include forked subagent fork threads (debug / admin tooling only)
+const everything = await harness.listThreads({ includeForkedSubagents: true })
 ```
 
+Fork threads are tagged with `metadata.forkedSubagent === true` (and `metadata.parentThreadId`) by the harness. Set `includeForkedSubagents: true` to opt back into seeing them — e.g. for a debug panel.
+
 #### `renameThread({ title })`
 
 Update the title of the current thread.
@@ -677,6 +684,42 @@ await harness.setSubagentModelId({ modelId: 'anthropic/claude-sonnet-4-6' })
 await harness.setSubagentModelId({ modelId: 'anthropic/claude-haiku-3.5', agentType: 'explore' })
 ```
 
+### Forked subagents
+
+By default, a subagent runs with a fresh context — it doesn't see the parent conversation. **Forked subagents** opt into a different model: the subagent runs on a clone of the parent thread and reuses the parent agent's full configuration. This is useful when the subagent needs the full context of the conversation so far (e.g., recalling earlier user-supplied facts), and when prompt-cache hit rates matter.
+
+#### Enabling forked mode
+
+Set `forked: true` either on the [`HarnessSubagent` definition](#configuration) (per-type default) or on each `subagent` tool call (per-invocation override):
+
+```typescript
+// Per-type default — every call to this subagent forks unless overridden.
+const subagents: HarnessSubagent[] = [
+  {
+    id: 'collaborator',
+    name: 'Collaborator',
+    description: 'Continues the conversation in a fork to try a different angle.',
+    instructions: '...',
+    forked: true,
+  },
+]
+```
+
+The model can also pass `forked: true` (or `forked: false`) per-invocation in the `subagent` tool input; the per-invocation value wins.
+
+#### Semantics and constraints
+
+- **Memory required.** Forked mode calls `memory.cloneThread` to create the fork, so the harness must have `memory` configured and an active parent thread. Calls without those return a structured error rather than throwing.
+- **Parent agent reused.** The fork runs through the parent agent's `stream(...)` call. The parent's instructions, tools, model, `maxSteps`, and `stopWhen` apply. The subagent definition's `instructions`, `tools`, `allowedHarnessTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode — this is what preserves the prompt-cache prefix.
+- **Toolsets inherited, recursive forks blocked at runtime.** Forks inherit the parent's toolsets verbatim (`ask_user`, `submit_plan`, user-configured harness tools, _including the `subagent` tool itself_) so the LLM request prefix — system prompt + tool list + tool schemas + tool descriptions — stays byte-identical to the parent's. This is what preserves the prompt cache. The `subagent` entry is kept on the model side but its `execute` is replaced inside the fork with a stub that returns a non-error "tool unavailable inside a forked subagent" message: nested forks are blocked at the runtime layer without perturbing the cached prefix.
+- **Fork threads are tagged.** Each fork thread is created with `metadata.forkedSubagent === true` and `metadata.parentThreadId === <parent>`. By default, [`listThreads`](#listthreadsoptions) hides these so they don't show up in user-facing thread pickers / startup flows. Pass `includeForkedSubagents: true` to see them in admin / debug tooling.
+- **Save-queue flushed before clone.** The agent stream batches message saves through a debounced `SaveQueueManager`, so the parent's latest user / assistant turn may not be on disk yet when the subagent tool call fires. The fork tool flushes pending saves first via the `flushMessages` callback on `AgentToolExecutionContext` before cloning, so the fork actually carries the latest turn. Flush failures are non-fatal — the clone still runs.
+- **Parent thread untouched.** All subagent activity (messages, OM writes) lands on the fork. The parent thread is never appended to during a forked subagent run.
+
+#### When to prefer non-forked mode
+
+Forked mode trades isolation for context inheritance. If the subagent should run with a strictly smaller toolset, a different system prompt, or a cheaper model, use the default (non-forked) mode and pass any required context explicitly in the `task` description.
+
 ### Events
 
 #### `subscribe(listener)`
@@ -753,13 +796,13 @@ The harness emits events through registered listeners. The following table lists
 
 The harness provides built-in tools to agents in every mode:
 
-| Tool          | Description                                                                                                               |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `ask_user`    | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices. |
-| `submit_plan` | Submit a plan for user review and approval.                                                                               |
-| `task_write`  | Create or update a structured task list for tracking progress.                                                            |
-| `task_check`  | Check the completion status of the current task list.                                                                     |
-| `subagent`    | Spawn a focused subagent with constrained tools (only available when `subagents` is configured).                          |
+| Tool          | Description                                                                                                                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ask_user`    | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                            |
+| `submit_plan` | Submit a plan for user review and approval.                                                                                                                                                          |
+| `task_write`  | Create or update a structured task list for tracking progress.                                                                                                                                       |
+| `task_check`  | Check the completion status of the current task list.                                                                                                                                                |
+| `subagent`    | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |
 
 ### `ask_user` selections
 

package/.docs/reference/index.md

@@ -169,6 +169,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector)
 - [SemanticRecall](https://mastra.ai/reference/processors/semantic-recall-processor)
 - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
+- [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)
 - [SystemPromptScrubber](https://mastra.ai/reference/processors/system-prompt-scrubber)
 - [TokenLimiterProcessor](https://mastra.ai/reference/processors/token-limiter-processor)
 - [ToolCallFilter](https://mastra.ai/reference/processors/tool-call-filter)
@@ -193,6 +194,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [registerApiRoute()](https://mastra.ai/reference/server/register-api-route)
 - [Server Routes](https://mastra.ai/reference/server/routes)
 - [Overview](https://mastra.ai/reference/storage/overview)
+- [ClickHouse Storage](https://mastra.ai/reference/storage/clickhouse)
 - [Cloudflare D1 Storage](https://mastra.ai/reference/storage/cloudflare-d1)
 - [Cloudflare KV Storage](https://mastra.ai/reference/storage/cloudflare)
 - [Composite Storage](https://mastra.ai/reference/storage/composite)
@@ -209,6 +211,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput)
 - [.stream()](https://mastra.ai/reference/streaming/agents/stream)
 - [.streamLegacy()](https://mastra.ai/reference/streaming/agents/streamLegacy)
+- [.streamUntilIdle()](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
 - [.observeStream()](https://mastra.ai/reference/streaming/workflows/observeStream)
 - [.resumeStream()](https://mastra.ai/reference/streaming/workflows/resumeStream)
 - [.stream()](https://mastra.ai/reference/streaming/workflows/stream)

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -8,14 +8,14 @@ For setup instructions, see the [Metrics overview](https://mastra.ai/docs/observ
 
 Metrics are extracted from spans when they end. The observability layer inspects each completed span, calculates duration, and (for model generation spans) reads token usage data. No manual instrumentation is needed.
 
-Metrics are routed through an internal event bus to the `DefaultExporter`, which batches and flushes them to storage. Only DuckDB and in-memory storage backends support metrics persistence today.
+Metrics are routed through an internal event bus to the `DefaultExporter`, which batches and flushes them to storage.
 
 ### What affects whether a metric is available
 
 Two conditions must be true for a metric to reach storage:
 
 1. `DefaultExporter` is configured as an exporter.
-2. The storage backend supports metrics (`DuckDB` or `InMemory`).
+2. The storage backend supports metrics (ClickHouse, DuckDB, or in-memory).
 
 If metrics aren't appearing, see [troubleshooting](#troubleshooting).
 

package/.docs/reference/observability/tracing/interfaces.md

@@ -126,6 +126,21 @@ interface ObservabilityExporter {
   /** Initialize exporter with tracing configuration and/or access to Mastra */
   init?(options: InitExporterOptions): void
 
+  /** Handle tracing events */
+  onTracingEvent?(event: TracingEvent): void | Promise<void>
+
+  /** Handle log events */
+  onLogEvent?(event: LogEvent): void | Promise<void>
+
+  /** Handle metric events */
+  onMetricEvent?(event: MetricEvent): void | Promise<void>
+
+  /** Handle score events */
+  onScoreEvent?(event: ScoreEvent): void | Promise<void>
+
+  /** Handle feedback events */
+  onFeedbackEvent?(event: FeedbackEvent): void | Promise<void>
+
   /** Export tracing events */
   exportTracingEvent(event: TracingEvent): Promise<void>
 
@@ -154,6 +169,8 @@ interface ObservabilityExporter {
 }
 ```
 
+Event callback payloads use observability event bus envelopes: `TracingEvent` carries span lifecycle events with `exportedSpan`, `LogEvent` wraps `ExportedLog` in `log`, `MetricEvent` wraps `ExportedMetric` in `metric`, `ScoreEvent` wraps `ExportedScore` in `score`, and `FeedbackEvent` wraps `ExportedFeedback` in `feedback`. For Cloud exporter behavior for these callbacks, see [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter).
+
 ### `SpanOutputProcessor`
 
 Interface for span output processors.

package/.docs/reference/processors/stream-error-retry-processor.md

@@ -0,0 +1,54 @@
+# StreamErrorRetryProcessor
+
+`StreamErrorRetryProcessor` is an **error processor** that retries transient errors emitted after an LLM stream starts. It includes built-in matching for OpenAI Responses stream errors and supports additional matchers for other provider-specific stream error shapes.
+
+The processor isn't enabled by default in core. Add it to `errorProcessors` for agents that need stream-error retry handling.
+
+## Usage example
+
+Add `StreamErrorRetryProcessor` to `errorProcessors`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { StreamErrorRetryProcessor } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'openai-agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5',
+  errorProcessors: [new StreamErrorRetryProcessor()],
+})
+```
+
+## How it works
+
+The processor checks the error and its cause chain for:
+
+- Provider retry metadata: `isRetryable === true`
+- Built-in OpenAI Responses stream error matching
+- Matcher results: Any configured matcher that returns `true`
+
+When the error is retryable, the processor returns `{ retry: true }`. It doesn't mutate messages.
+
+## Default OpenAI Responses matcher
+
+`isRetryableOpenAIResponsesStreamError` matches OpenAI Responses stream error chunks with `type: 'error'` or `type: 'response.failed'`. It retries known transient OpenAI error codes and, as a fallback, errors with explicit retry guidance such as `You can retry your request`.
+
+`StreamErrorRetryProcessor` includes this matcher by default. You can also import it and reuse it in custom retry logic.
+
+## Constructor parameters
+
+**options** (`StreamErrorRetryProcessorOptions`): Configuration for retry handling.
+
+## Properties
+
+**id** (`'stream-error-retry-processor'`): Processor identifier.
+
+**name** (`'Stream Error Retry Processor'`): Processor display name.
+
+**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): Retries stream errors up to the configured retry limit.
+
+## Related
+
+- [Processor interface](https://mastra.ai/reference/processors/processor-interface)
+- [Processors](https://mastra.ai/docs/agents/processors)