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

package/.docs/docs/agents/background-tasks.md

@@ -0,0 +1,242 @@
+# Background tasks
+
+**Added in:** `@mastra/core@1.28.0`
+
+Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) the agent is re-invoked automatically so the result is processed in the same call.
+
+## When to use background tasks
+
+Use background tasks when a tool call may take long enough that the user shouldn't wait for it before seeing a response. Common cases:
+
+- Subagent delegations that themselves run multi-step research or writing.
+- Tool calls that hit slow external services, queues, or large data jobs.
+- Workflows triggered from a tool call that may take minutes to complete.
+
+For tool calls that return quickly, foreground execution using `agent.stream()` and `agent.generate()` is simpler.
+
+> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/memory/storage) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
+
+## Quickstart
+
+Background tasks are off by default. Enable them by setting `backgroundTasks.enabled` on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({ id: 'storage', url: 'file:mastra.db' }),
+  backgroundTasks: {
+    enabled: true,
+    globalConcurrency: 10,
+    perAgentConcurrency: 5,
+    backpressure: 'queue',
+    defaultTimeoutMs: 300_000,
+  },
+})
+```
+
+The full set of options is listed in the [backgroundTasks configuration reference](https://mastra.ai/reference/configuration).
+
+## Run a tool in the background
+
+Enabling the manager doesn't run anything in the background by itself as every tool defaults to foreground execution. You can run a tool in the background at one of three layers, in priority order:
+
+1. **LLM per-call override**: the model decides it should run in the background and includes a `_background` field in the tool arguments.
+2. **Agent-level config**: the agent declares which of its tools are background-eligible.
+3. **Tool-level config**: the tool itself declares it as background-eligible.
+
+### Tool-level
+
+Set `backgroundTasks.enabled: true` on the tool definition. Tools opted in at this layer run in the background whenever called by an agent that has the manager enabled.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const researchTool = createTool({
+  id: 'research',
+  description: 'Run a long research job',
+  inputSchema: z.object({ topic: z.string() }),
+  backgroundTasks: {
+    enabled: true,
+    timeoutMs: 600_000,
+    maxRetries: 1,
+  },
+  execute: async ({ context }) => {
+    // ...
+  },
+})
+```
+
+### Agent-level
+
+Use `backgroundTasks.tools` on the agent to opt in specific tools, override timeouts for individual tools, or run all background-eligible tools in the background. Use `disabled: true` to short-circuit background dispatch for the agent entirely.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const researcher = new Agent({
+  id: 'researcher',
+  instructions: 'You research topics and answer questions.',
+  model: 'openai/gpt-5.4',
+  tools: { researchTool, summarizeTool },
+  backgroundTasks: {
+    tools: {
+      researchTool: { enabled: true, timeoutMs: 600_000 },
+      summarizeTool: false,
+    },
+  },
+})
+```
+
+Set `tools: 'all'` to opt in every tool the agent has.
+
+### LLM per-call override
+
+When a tool is registered on an agent that has background tasks enabled, the model can include a `_background` field in the tool arguments to override the resolved configuration for that specific call. The model only includes what it wants to override, all fields in `_background` are optional. The override is stripped from the arguments before the tool runs.
+
+```json
+{
+  "topic": "solana",
+  "_background": { "enabled": true, "timeoutMs": 900_000 }
+}
+```
+
+### Resolution order
+
+When a tool call is dispatched, the resolved background config is computed in this priority order:
+
+1. LLM `_background` override (if present in the call's arguments).
+2. Agent-level `backgroundTasks.tools` entry for the tool.
+3. Tool-level `backgroundTasks` config.
+4. Manager defaults (`defaultTimeoutMs`, `defaultRetries`).
+
+If the agent has `backgroundTasks.disabled: true`, every tool call runs synchronously regardless of the layers above.
+
+## Background tasks related stream chunks
+
+When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/streaming/background-task-streaming) SSE stream. Each stream covers a different set of chunk types:
+
+| Chunk type                  | When it fires                                                                          | Emitted by     |
+| --------------------------- | -------------------------------------------------------------------------------------- | -------------- |
+| `background-task-started`   | The task has been enqueued and assigned a `taskId`.                                    | Agent stream   |
+| `background-task-running`   | The task picked up a worker and started executing.                                     | Manager stream |
+| `background-task-progress`  | Shows number of running background tasks.                                              | Agent stream   |
+| `background-task-output`    | A streamed output chunk from the task's `execute`.                                     | Manager stream |
+| `background-task-completed` | The task finished successfully. The `payload.result` matches the eventual tool result. | Manager stream |
+| `background-task-failed`    | The task threw or timed out.                                                           | Manager stream |
+| `background-task-cancelled` | The task was cancelled before completing.                                              | Manager stream |
+
+`agent.stream().fullStream` only emits the agent-loop chunks (`background-task-started`, `background-task-progress`) on its own. `agent.streamUntilIdle()` emits the same two chunks and additionally subscribes to the manager pubsub for the run's memory scope and pipes the five manager chunks (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`) into the same `fullStream`, so consumers of `streamUntilIdle().fullStream` see all seven types.
+
+`backgroundTaskManager.stream()` only emits the five manager chunks.
+
+The full payload shapes are documented in the [background task chunks reference](https://mastra.ai/reference/streaming/ChunkType).
+
+## Keep the agent stream open with `streamUntilIdle()`
+
+`agent.stream()` returns once the LLM emits a final response even if a background task is still running. Use `agent.streamUntilIdle()` when you want the stream to stay open until every dispatched background task has completed and the LLM has had a chance to respond to the result:
+
+```typescript
+const stream = await agent.streamUntilIdle('Research solana for me', {
+  memory: { thread: 't1', resource: 'u1' },
+  maxIdleMs: 5 * 60_000,
+})
+
+for await (const chunk of stream.fullStream) {
+  // chunks from the initial turn AND any continuation turns triggered by
+  // background task completions flow through here
+}
+```
+
+When a background task completes, the result is injected into the agent memory, `streamUntilIdle()` re-enters the agentic loop so the LLM can react to it. The stream closes when no tasks are running and no completions are queued.
+
+`maxIdleMs` caps how long the stream waits between turns. The timer only runs while the wrapper is between turns, so a slow first token won't close the stream. The default is 5 minutes.
+
+> **Note:** Visit [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) for the full API.
+
+### Aggregate properties
+
+`streamUntilIdle()` returns a `MastraModelOutput` that looks like the one from `stream()`, but only `fullStream` spans the initial turn **and** any auto-continuations. Aggregate properties (`text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()`) still resolve against the **first turn's** internal buffer. If you need an aggregate view across continuations, consume `fullStream` yourself and accumulate.
+
+## Subagents in the background
+
+Subagent invocations are dispatched as tool calls under the hood, so the same background configuration applies. The recommended pattern is to opt each subagent in on the supervisor, it's clearer and lets you tune `timeoutMs` per subagent in one place:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+const supervisor = new Agent({
+  id: 'supervisor',
+  instructions: 'Coordinate research and writing using the available agents.',
+  model: 'openai/gpt-5.4',
+  agents: { researchAgent, writingAgent },
+  backgroundTasks: {
+    tools: {
+      researchAgent: { enabled: true, timeoutMs: 900_000 },
+      writingAgent: { enabled: true, timeoutMs: 900_000 },
+    },
+  },
+})
+
+const stream = await supervisor.streamUntilIdle('Research AI in education and write an article', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+```
+
+### Inheriting from the subagent
+
+If a subagent isn't listed under the supervisor's `backgroundTasks.tools` but has background-eligible tools of its own (either via tool-level `backgroundTasks.enabled: true` or its own `backgroundTasks.tools` entry) the framework still dispatches the entire subagent invocation as a background task. The supervisor inherits the subagent's intent: the subagent itself becomes the background task, and its inner tools run in the foreground inside the subagent's loop.
+
+The background config used for the inherited dispatch (for example `waitTimeoutMs`) is derived from the subagent's own `backgroundTasks` config.
+
+```typescript
+const researchAgent = new Agent({
+  id: 'research-agent',
+  description: 'Gathers factual information.',
+  model: 'openai/gpt-5-mini',
+  tools: { deepResearchTool },
+  backgroundTasks: {
+    tools: {
+      deepResearchTool: { enabled: true, timeoutMs: 600_000 },
+    },
+    waitTimeoutMs: 900_000,
+  },
+})
+```
+
+When this `researchAgent` is delegated to from a supervisor that has no backgroundTask configuration for the `researchAgent`, the supervisor still dispatches the whole `researchAgent` invocation as a background task, and `deepResearchTool` runs in the foreground inside that invocation, instead of dispatching its own nested background task.
+
+Use this pattern when you want a subagent to behave consistently in the background regardless of which supervisor invokes it. Use the supervisor-side opt-in (above) when you want to tune background behavior centrally per supervisor.
+
+## Lifecycle callbacks
+
+Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their respective outcomes:
+
+- Tool-level `backgroundTasks.onComplete` / `onFailed`: scoped to one tool.
+- Agent-level `backgroundTasks.onTaskComplete` / `onTaskFailed`: scoped to all tasks dispatched by this agent.
+- Manager-level `onTaskComplete` / `onTaskFailed`: scoped globally.
+
+```typescript
+export const mastra = new Mastra({
+  storage,
+  backgroundTasks: {
+    enabled: true,
+    onTaskComplete: task => {
+      logger.info('Background task complete', { taskId: task.id, toolName: task.toolName })
+    },
+    onTaskFailed: task => {
+      logger.error('Background task failed', { taskId: task.id, error: task.error })
+    },
+  },
+})
+```
+
+## Related
+
+- [`Agent.streamUntilIdle()` reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
+- [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
+- [Storage](https://mastra.ai/docs/memory/storage)

package/.docs/docs/agents/supervisor-agents.md

@@ -300,9 +300,38 @@ Success criteria:
 })
 ```
 
-## Sub-agent versioning
+## Running subagents in the background
 
-When using the [editor](https://mastra.ai/docs/editor/overview), you can control which stored version of each sub-agent the supervisor uses at runtime. Set version overrides on the Mastra instance or per invocation:
+Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the supervisor's response.
+
+Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration) on the Mastra instance, then opt subagents in on the supervisor:
+
+```typescript
+const supervisor = new Agent({
+  id: 'supervisor',
+  instructions: 'Coordinate research and writing using the available agents.',
+  model: 'openai/gpt-5.4',
+  agents: { researchAgent, writingAgent },
+  backgroundTasks: {
+    tools: {
+      researchAgent: { enabled: true, timeoutMs: 900_000 },
+      writingAgent: { enabled: true, timeoutMs: 900_000 },
+    },
+  },
+})
+
+const stream = await supervisor.streamUntilIdle('Research AI in education and write an article', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+```
+
+Use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) instead of `stream()` so the stream stays open until the subagents complete and the supervisor has had a chance to respond to their results.
+
+If a subagent isn't listed on the supervisor but has its own background-eligible tools, the supervisor still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/agents/background-tasks) for details.
+
+## Subagent versioning
+
+When using the [editor](https://mastra.ai/docs/editor/overview), you can control which stored version of each subagent the supervisor uses at runtime. Set version overrides on the Mastra instance or per invocation:
 
 ```typescript
 const result = await supervisor.generate('Research and write about AI safety', {
@@ -315,13 +344,15 @@ const result = await supervisor.generate('Research and write about AI safety', {
 })
 ```
 
-Version overrides propagate automatically through delegation. See [Sub-agent versioning](https://mastra.ai/docs/editor/overview) for details on resolution order and server API usage.
+Version overrides propagate automatically through delegation. See [Subagent versioning](https://mastra.ai/docs/editor/overview) for details on resolution order and server API usage.
 
 ## Related
 
-- [Sub-agent versioning](https://mastra.ai/docs/editor/overview)
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [Subagent versioning](https://mastra.ai/docs/editor/overview)
 - [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)
+- [Agent.streamUntilIdle() reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
 - [Agent.generate() reference](https://mastra.ai/reference/agents/generate)
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
 - [Memory in multi-agent systems](https://mastra.ai/docs/memory/overview)

package/.docs/docs/agents/using-tools.md

@@ -290,6 +290,7 @@ Note that for subagents, you'll see two different identifiers in stream response
 
 - [`createTool` reference](https://mastra.ai/reference/tools/create-tool)
 - [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks): Run long-running tools without blocking the agent loop
 - [MCP overview](https://mastra.ai/docs/mcp/overview)
 - [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
 - [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output

package/.docs/docs/streaming/background-task-streaming.md

@@ -0,0 +1,80 @@
+# Background task streaming
+
+**Added in:** `@mastra/core@1.28.0`
+
+`mastra.backgroundTaskManager.stream()` returns a `ReadableStream` of [background task](https://mastra.ai/docs/agents/background-tasks) lifecycle events. Use it to monitor running tasks across the system, for example to drive a status dashboard, surface progress in your own UI, or pipe events into an SSE response.
+
+The stream emits the same chunk types that appear inside `Agent.streamUntilIdle()` (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`). See [background task chunks](https://mastra.ai/reference/streaming/ChunkType) for the full payload shapes.
+
+> **Note:** Background tasks must be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) before `backgroundTaskManager` is available. When disabled, `mastra.backgroundTaskManager` is `undefined`.
+
+## Subscribe to all task events
+
+Calling `stream()` with no filter returns a stream of every task event in the system. On connection, the stream emits a snapshot of all currently running tasks, then forwards live events as they happen.
+
+```typescript
+const bgManager = mastra.backgroundTaskManager
+if (!bgManager) throw new Error('Background tasks are not enabled')
+
+const controller = new AbortController()
+const stream = bgManager.stream({ abortSignal: controller.signal })
+
+for await (const chunk of stream) {
+  switch (chunk.type) {
+    case 'background-task-running':
+      console.log('started', chunk.payload.taskId, chunk.payload.toolName)
+      break
+    case 'background-task-completed':
+      console.log('done', chunk.payload.taskId, chunk.payload.result)
+      break
+    case 'background-task-failed':
+      console.error('failed', chunk.payload.taskId, chunk.payload.error)
+      break
+  }
+}
+```
+
+The stream stays open until the caller's `AbortSignal` fires. Always pass an `abortSignal` so you can disconnect cleanly.
+
+## Filter the stream
+
+Pass any combination of filter options to narrow the events you receive. Filters apply to both the initial snapshot and the live event subscription.
+
+```typescript
+const stream = bgManager.stream({
+  agentId: 'researcher',
+  threadId: 't1',
+  resourceId: 'u1',
+  abortSignal: controller.signal,
+})
+```
+
+| Filter        | Description                                         |
+| ------------- | --------------------------------------------------- |
+| `agentId`     | Only events from tasks dispatched by this agent     |
+| `runId`       | Only events from this specific agent run            |
+| `threadId`    | Only events from tasks scoped to this memory thread |
+| `resourceId`  | Only events from tasks scoped to this resource      |
+| `taskId`      | Only events for a single task                       |
+| `abortSignal` | Closes the stream when the signal aborts            |
+
+## Look up task state directly
+
+For one-off lookups instead of a live stream, use `getTask` and `listTasks`:
+
+```typescript
+const task = await mastra.backgroundTaskManager?.getTask(taskId)
+const { tasks, total } = await mastra.backgroundTaskManager?.listTasks({
+  status: 'running',
+  agentId: 'researcher',
+})
+```
+
+These read from storage rather than the pubsub stream, so they're suitable for paginated lists and detail views.
+
+## Related
+
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [`Agent.streamUntilIdle()` reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
+- [Background task chunks](https://mastra.ai/reference/streaming/ChunkType)
+- [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)

package/.docs/docs/streaming/overview.md

@@ -29,6 +29,8 @@ for await (const chunk of stream.textStream) {
 
 > **Info:** Visit [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream) for more information.
 
+> **Tip:** For agents that dispatch [background tasks](https://mastra.ai/docs/agents/background-tasks), use [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) to keep the stream open until those tasks complete and the agent has had a chance to respond to their results.
+
 ### Output from `Agent.stream()`
 
 The output streams the generated response from the agent.
@@ -129,5 +131,6 @@ A workflow stream provides access to various response properties:
 ## Related
 
 - [Streaming events](https://mastra.ai/docs/streaming/events)
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
 - [Using Agents](https://mastra.ai/docs/agents/overview)
 - [Workflows overview](https://mastra.ai/docs/workflows/overview)

package/.docs/docs/workspace/filesystem.md

@@ -19,7 +19,7 @@ A filesystem provider handles all file operations for a workspace:
 Available providers:
 
 - [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem): Stores files in a directory on disk
-- [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO)
+- [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO, Tigris)
 - [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem): Stores files in Google Cloud Storage
 - [`AzureBlobFilesystem`](https://mastra.ai/reference/workspace/azure-blob-filesystem): Stores files in Azure Blob Storage
 - [`AgentFSFilesystem`](https://mastra.ai/reference/workspace/agentfs-filesystem): Stores files in a Turso/SQLite database via AgentFS

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

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/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)
@@ -209,6 +210,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/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)

package/.docs/reference/streaming/ChunkType.md

@@ -398,6 +398,146 @@ Contains output from workflow step execution, used primarily for usage tracking
 
 **payload.output** (`ChunkType`): Nested chunk data from step execution, typically containing finish events or other step results
 
+## Background task chunks
+
+Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/agents/background-tasks) and `streamUntilIdle()` is used.
+
+### background-task-started
+
+Emitted when a tool call is enqueued as a background task and assigned a `taskId`.
+
+**type** (`"background-task-started"`): Chunk type identifier
+
+**payload** (`BackgroundTaskStartedPayload`): Identifies the newly enqueued task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+### background-task-running
+
+Emitted when a worker picks up the task and execution begins.
+
+**type** (`"background-task-running"`): Chunk type identifier
+
+**payload** (`BackgroundTaskRunningPayload`): Details about the running task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.startedAt** (`Date`): Timestamp at which execution started
+
+**payload.args** (`Record<string, unknown>`): Arguments passed to the tool's execute function
+
+### background-task-progress
+
+Periodic snapshot of how many background tasks are currently running across the agent.
+
+**type** (`"background-task-progress"`): Chunk type identifier
+
+**payload** (`BackgroundTaskProgressPayload`): Aggregate progress for all running tasks
+
+**payload.taskIds** (`string[]`): IDs of all currently running background tasks
+
+**payload.runningCount** (`number`): Number of background tasks currently running
+
+**payload.elapsedMs** (`number`): Milliseconds elapsed since the agent run started
+
+### background-task-output
+
+A streamed output chunk emitted by the task's `execute` function. Wraps an inner [`tool-output`](#tool-output) chunk.
+
+**type** (`"background-task-output"`): Chunk type identifier
+
+**payload** (`BackgroundTaskOutputPayload`): Streamed output from the running task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool being executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.payload** (`ToolOutputChunk`): Inner tool-output chunk produced by the task
+
+### background-task-completed
+
+Emitted when the task finishes successfully. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-completed"`): Chunk type identifier
+
+**payload** (`BackgroundTaskResultPayload`): The completed task's result
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.result** (`unknown`): The tool's resolved return value
+
+**payload.completedAt** (`Date`): Timestamp at which the task completed
+
+**payload.isError** (`boolean`): True when the tool returned an error result rather than throwing
+
+### background-task-failed
+
+Emitted when the task throws or times out. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-failed"`): Chunk type identifier
+
+**payload** (`BackgroundTaskFailedPayload`): Failure details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.error** (`{ message: string }`): Error details thrown by the task
+
+**payload.completedAt** (`Date`): Timestamp at which the task failed
+
+### background-task-cancelled
+
+Emitted when the task is cancelled before completing. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).
+
+**type** (`"background-task-cancelled"`): Chunk type identifier
+
+**payload** (`BackgroundTaskCancelledPayload`): Cancellation details for the task
+
+**payload.taskId** (`string`): Unique identifier for the background task
+
+**payload.toolName** (`string`): Name of the tool that was executed
+
+**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call
+
+**payload.runId** (`string`): Run ID of the agent that dispatched the task
+
+**payload.agentId** (`string`): ID of the agent that dispatched the task
+
+**payload.completedAt** (`Date`): Timestamp at which the task was cancelled
+
 ## Metadata and special chunks
 
 ### response-metadata

package/.docs/reference/streaming/agents/streamUntilIdle.md

@@ -0,0 +1,94 @@
+# Agent.streamUntilIdle()
+
+**Added in:** `@mastra/core@1.28.0`
+
+`streamUntilIdle()` streams an agent's response and keeps the stream open until every background task dispatched during the run completes. When a task finishes, its result is written to memory and the agentic loop re-enters automatically so the LLM can react to it. The stream closes once no tasks are running and no completions are queued.
+
+Use it when the agent dispatches background tasks (typically long-running tools or subagents) and you want a single stream that spans the initial response **plus** every continuation triggered by a task completion. For foreground-only runs or if you prefer to manage the continuation manually (manually prompt agent to process the result), use [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream).
+
+## Usage example
+
+```ts
+const stream = await agent.streamUntilIdle('Research solana for me', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+
+for await (const chunk of stream.fullStream) {
+  // chunks from the initial turn AND any continuation turns triggered by
+  // background task completions flow through here
+}
+```
+
+> **Info:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it falls through to a plain `agent.stream()` call.
+
+## Parameters
+
+**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): The messages to send to the agent. Can be a single string, array of strings, or structured message objects.
+
+**options** (`AgentExecutionOptions<Output> & { maxIdleMs?: number }`): Accepts every option that Agent.stream() accepts, plus maxIdleMs. See the Agent.stream() reference for the full list.
+
+**options.maxIdleMs** (`number`): Closes the outer stream after this many ms of idleness between turns. The timer only runs while the wrapper is between turns, so a slow first token does not close the stream. Default: 5 minutes.
+
+**options.memory** (`{ thread?: string | { id: string }; resource?: string }`): Memory thread and resource for the run. Required for continuations to write background task results back into the conversation.
+
+**options.structuredOutput** (`PublicStructuredOutputOptions<Output>`): Schema-based structured output. Same shape as Agent.stream(). Note that aggregate properties resolve against the first turn only.
+
+For every other option (`maxSteps`, `modelSettings`, `toolChoice`, `outputProcessors`, `onFinish`, `onChunk`, etc.), see the [`Agent.stream()` parameters](https://mastra.ai/reference/streaming/agents/stream). `streamUntilIdle()` forwards them to the initial turn.
+
+## Returns
+
+**stream** (`MastraModelOutput<Output>`): A MastraModelOutput where fullStream spans the initial turn plus every auto-continuation. Aggregate properties (text, toolCalls, toolResults, finishReason, messageList, getFullOutput()) resolve against the first turn only.
+
+### Aggregate properties caveat
+
+`streamUntilIdle()` returns a proxy over the first turn's `MastraModelOutput`. Only `fullStream` is replaced with a combined stream that spans every continuation. Every other property — `text`, `toolCalls`, `toolResults`, `finishReason`, `messageList`, `getFullOutput()` — resolves against the **first turn's** internal buffer.
+
+If you need an aggregate view across all continuations, consume `fullStream` yourself and accumulate.
+
+## Continuation behavior
+
+Internally, `streamUntilIdle()`:
+
+1. Runs the initial turn via `agent.stream(...)` and pipes its `fullStream` into the outer stream.
+2. Subscribes to background-task completion events for the resolved memory scope.
+3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the just-completed `toolCallId`s. The continuation turn flows into the same outer stream.
+4. Closes the outer stream once no tasks are running and no completions are queued.
+
+## Extended usage example
+
+### Cap idle time between turns
+
+```ts
+const stream = await agent.streamUntilIdle('Kick off the long jobs', {
+  memory: { thread: 't1', resource: 'u1' },
+  maxIdleMs: 60_000, // close the stream after 1 minute of idleness between turns
+})
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'background-task-completed') {
+    console.log('Task complete:', chunk.payload.taskId)
+  }
+}
+```
+
+### Aggregate text across continuations
+
+```ts
+const stream = await agent.streamUntilIdle('Research and summarize', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+
+let fullText = ''
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'text-delta') {
+    fullText += chunk.payload.text
+  }
+}
+```
+
+## Related
+
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
+- [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
+- [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)

package/.docs/reference/workspace/s3-filesystem.md

@@ -1,6 +1,6 @@
 # S3Filesystem
 
-Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, and DigitalOcean Spaces.
+Stores files in Amazon S3 or S3-compatible storage services like Cloudflare R2, MinIO, DigitalOcean Spaces, and Tigris.
 
 > **Info:** For interface details, see [WorkspaceFilesystem Interface](https://mastra.ai/reference/workspace/filesystem).
 
@@ -55,6 +55,61 @@ const agent = new Agent({
 })
 ```
 
+### AWS credential provider chain
+
+When no credentials are provided, `S3Filesystem` uses the AWS SDK default credential provider chain. This discovers credentials automatically from environment variables, `~/.aws` config files, ECS container credentials, EC2 instance profiles, and other standard sources.
+
+```typescript
+import { S3Filesystem } from '@mastra/s3'
+
+// SDK discovers credentials from the environment automatically
+const filesystem = new S3Filesystem({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+})
+```
+
+Pass a credential provider function for auto-refreshing credentials. This is useful for deployments on ECS, Lambda, or when using SSO/AssumeRole where temporary credentials expire and need to be refreshed.
+
+Install the AWS SDK credential providers package when calling `fromNodeProviderChain()` directly:
+
+**npm**:
+
+```bash
+npm install @aws-sdk/credential-providers
+```
+
+**pnpm**:
+
+```bash
+pnpm add @aws-sdk/credential-providers
+```
+
+**Yarn**:
+
+```bash
+yarn add @aws-sdk/credential-providers
+```
+
+**Bun**:
+
+```bash
+bun add @aws-sdk/credential-providers
+```
+
+```typescript
+import { S3Filesystem } from '@mastra/s3'
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers'
+
+const filesystem = new S3Filesystem({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  credentials: fromNodeProviderChain(),
+})
+```
+
+Provider functions only apply to `S3Filesystem` API calls. When mounting the filesystem into an E2B sandbox, mount configuration only supports static `accessKeyId`, `secretAccessKey`, and `sessionToken` values, so credential refresh must be handled outside the mount.
+
 ### Cloudflare R2
 
 ```typescript
@@ -83,19 +138,38 @@ const filesystem = new S3Filesystem({
 })
 ```
 
+### Tigris
+
+```typescript
+import { S3Filesystem } from '@mastra/s3'
+
+const filesystem = new S3Filesystem({
+  bucket: 'my-bucket',
+  region: 'auto',
+  endpoint: 'https://t3.storage.dev',
+  accessKeyId: process.env.TIGRIS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.TIGRIS_SECRET_ACCESS_KEY,
+  forcePathStyle: false,
+})
+```
+
+Tigris uses virtual-hosted-style addressing, so `forcePathStyle` must be set to `false` (the default is `true` when a custom endpoint is provided). Create credentials from the [Tigris Dashboard](https://console.tigris.dev/) — access keys are prefixed `tid_` and secrets `tsec_`.
+
 ## Constructor parameters
 
 **bucket** (`string`): S3 bucket name
 
 **region** (`string`): AWS region (use 'auto' for R2)
 
-**accessKeyId** (`string`): AWS access key ID. Optional for public buckets (read-only access).
+**credentials** (`AwsCredentialIdentity | AwsCredentialIdentityProvider`): AWS credentials or credential provider function. Accepts static credentials or a provider that auto-refreshes (e.g. \`fromNodeProviderChain()\` from \`@aws-sdk/credential-providers\`). Takes precedence over \`accessKeyId\`/\`secretAccessKey\`/\`sessionToken\`. When all credential options are omitted, the SDK default credential provider chain is used.
+
+**accessKeyId** (`string`): AWS access key ID. When omitted along with \`secretAccessKey\` and \`credentials\`, the SDK default credential provider chain is used.
 
-**secretAccessKey** (`string`): AWS secret access key. Optional for public buckets (read-only access).
+**secretAccessKey** (`string`): AWS secret access key. When omitted along with \`accessKeyId\` and \`credentials\`, the SDK default credential provider chain is used.
 
-**sessionToken** (`string`): AWS session token for temporary credentials. Required when using SSO, AssumeRole, container credentials, or any other temporary credential provider.
+**sessionToken** (`string`): AWS session token for static temporary credentials. Use with \`accessKeyId\`/\`secretAccessKey\` only when passing a complete temporary credential set manually. For auto-refreshing SSO, AssumeRole, or container credentials, use the \`credentials\` provider parameter or the SDK default credential provider chain.
 
-**endpoint** (`string`): Custom endpoint URL for S3-compatible storage (R2, MinIO, etc.)
+**endpoint** (`string`): Custom endpoint URL for S3-compatible storage (R2, MinIO, Tigris, etc.)
 
 **forcePathStyle** (`boolean`): Force path-style URLs instead of virtual-hosted-style. Required for some S3-compatible services like MinIO. Defaults to true when a custom endpoint is provided. (Default: `true (when endpoint is set)`)
 

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @mastra/mcp-docs-server
 
+## 1.1.29
+
+### Patch Changes
+
+- Updated dependencies [[`28caa5b`](https://github.com/mastra-ai/mastra/commit/28caa5b032358545af2589ed90636eccb4dd9d2f), [`c1ae974`](https://github.com/mastra-ai/mastra/commit/c1ae97491f6e57378ce880c3a397778c42adcdf1), [`b510d36`](https://github.com/mastra-ai/mastra/commit/b510d368f73dab6be2e2c2bc99035aaef1fb7d7a), [`10e1c9a`](https://github.com/mastra-ai/mastra/commit/10e1c9a6a99c14eb055d0f409b603e07af827e68), [`13b4d7c`](https://github.com/mastra-ai/mastra/commit/13b4d7c16de34dff9095d1cd80f22f544b6cfe75), [`7a7b313`](https://github.com/mastra-ai/mastra/commit/7a7b3138fb3bcf0b0c740eaea07971e43d330ef3), [`c04417b`](https://github.com/mastra-ai/mastra/commit/c04417ba0a2e4ded66da4352331ef29cd4bd1d79), [`cf25a03`](https://github.com/mastra-ai/mastra/commit/cf25a03132164b9dc1e5dccf7394824e33007c51), [`8a71261`](https://github.com/mastra-ai/mastra/commit/8a71261e3954ae617c6f8e25767b951f99438ab2), [`9e973b0`](https://github.com/mastra-ai/mastra/commit/9e973b010dacfa15ac82b0072897319f5234b90a), [`dd934a0`](https://github.com/mastra-ai/mastra/commit/dd934a0982ce0f78712fbd559e4f2410bf594b39), [`ba6b0c5`](https://github.com/mastra-ai/mastra/commit/ba6b0c51bfce358554fd33c7f2bcd5593633f2ff), [`a6dac0a`](https://github.com/mastra-ai/mastra/commit/a6dac0a40c7181161b1add4e8534f962bcbc9aa7), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`6c8c6c7`](https://github.com/mastra-ai/mastra/commit/6c8c6c71518394321a4692614aa4b11f3bb0a343), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`7d056b6`](https://github.com/mastra-ai/mastra/commit/7d056b6ecf603cacaa0f663ff1df025ed885b6c1), [`9cef83b`](https://github.com/mastra-ai/mastra/commit/9cef83b8a642b8098747772921e3523b492bafbc), [`d30e215`](https://github.com/mastra-ai/mastra/commit/d30e2156c746bc9fd791745cec1cc24377b66789), [`021a60f`](https://github.com/mastra-ai/mastra/commit/021a60f1f3e0135a70ef23c58be7a9b3aaffe6b4), [`73f2809`](https://github.com/mastra-ai/mastra/commit/73f2809721db24e98cdf122539652a455211b450), [`aedeea4`](https://github.com/mastra-ai/mastra/commit/aedeea48a94f728323f040478775076b9574be50), [`26f1f94`](https://github.com/mastra-ai/mastra/commit/26f1f9490574b864ba1ecedf2c9632e0767a23bd), [`8126d86`](https://github.com/mastra-ai/mastra/commit/8126d8638411eacfafdc29036ac998e8757ea66f), [`73b45fa`](https://github.com/mastra-ai/mastra/commit/73b45facdef4fbcb8af710c50f0646f18619dbaa), [`ae97520`](https://github.com/mastra-ai/mastra/commit/ae975206fdb0f6ef03c4d5bf94f7dc7c3f706c02), [`7a7b313`](https://github.com/mastra-ai/mastra/commit/7a7b3138fb3bcf0b0c740eaea07971e43d330ef3), [`441670a`](https://github.com/mastra-ai/mastra/commit/441670a02c9dc7731c52674f55481e7848a84523)]:
+  - @mastra/core@1.29.0
+  - @mastra/mcp@1.6.0
+
+## 1.1.29-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`c1ae974`](https://github.com/mastra-ai/mastra/commit/c1ae97491f6e57378ce880c3a397778c42adcdf1), [`10e1c9a`](https://github.com/mastra-ai/mastra/commit/10e1c9a6a99c14eb055d0f409b603e07af827e68), [`13b4d7c`](https://github.com/mastra-ai/mastra/commit/13b4d7c16de34dff9095d1cd80f22f544b6cfe75), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`6c8c6c7`](https://github.com/mastra-ai/mastra/commit/6c8c6c71518394321a4692614aa4b11f3bb0a343), [`5a4b1ee`](https://github.com/mastra-ai/mastra/commit/5a4b1ee80212969621228104995589c0fa59e575), [`ec4cb26`](https://github.com/mastra-ai/mastra/commit/ec4cb26919972eb2031fea510f8f013e1d5b7ee2)]:
+  - @mastra/core@1.29.0-alpha.6
+  - @mastra/mcp@1.6.0-alpha.0
+
+## 1.1.29-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`28caa5b`](https://github.com/mastra-ai/mastra/commit/28caa5b032358545af2589ed90636eccb4dd9d2f), [`7d056b6`](https://github.com/mastra-ai/mastra/commit/7d056b6ecf603cacaa0f663ff1df025ed885b6c1), [`26f1f94`](https://github.com/mastra-ai/mastra/commit/26f1f9490574b864ba1ecedf2c9632e0767a23bd)]:
+  - @mastra/core@1.29.0-alpha.5
+
 ## 1.1.29-alpha.9
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.29-alpha.9",
+  "version": "1.1.29",
   "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.29.0-alpha.4",
-    "@mastra/mcp": "^1.5.2"
+    "@mastra/core": "1.29.0",
+    "@mastra/mcp": "^1.6.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -46,9 +46,9 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "4.1.5",
-    "@internal/lint": "0.0.86",
-    "@internal/types-builder": "0.0.61",
-    "@mastra/core": "1.29.0-alpha.4"
+    "@internal/lint": "0.0.87",
+    "@mastra/core": "1.29.0",
+    "@internal/types-builder": "0.0.62"
   },
   "homepage": "https://mastra.ai",
   "repository": {