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

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

@@ -0,0 +1,242 @@
+# Background tasks
+
+**Added in:** `@mastra/core@1.29.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/observability/metrics/overview.md

@@ -8,9 +8,9 @@ Three categories of metrics are emitted automatically:
 - **Token usage metrics**: Input and output token counts broken down by type (text, cache, audio, image, reasoning).
 - **Cost estimation**: Estimated cost per model call based on an embedded pricing registry.
 
-> **Note:** Metrics require a separate OLAP store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
+> **Note:** Metrics require an OLAP-capable store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
 >
-> For local development, you can use [DuckDB](https://mastra.ai/reference/vectors/duckdb). We don't recommend using in-memory/DuckDB for production, ClickHouse support is coming soon for scalable metrics storage.
+> For local development, use [DuckDB](https://duckdb.org/) through `@mastra/duckdb`. For production, use [ClickHouse](https://clickhouse.com/) through `@mastra/clickhouse`.
 
 ## When to use metrics
 

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

@@ -2,7 +2,7 @@
 
 The `DefaultExporter` persists traces to your configured storage backend, making them accessible through Studio. It's automatically enabled when using the default observability configuration and requires no external services.
 
-> **Production Observability:** Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, we recommend using **ClickHouse** for the observability storage domain via [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](#production-recommendations) for details.
+> **Production Observability:** Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, route the observability storage domain to [ClickHouse](https://mastra.ai/reference/storage/clickhouse) through [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](#production-recommendations) for details.
 
 ## Configuration
 
@@ -114,7 +114,7 @@ If you set the strategy to `'auto'`, the `DefaultExporter` automatically selects
 
 | Storage Provider                                                 | Preferred Strategy | Supported Strategies            | Recommended Use                       |
 | ---------------------------------------------------------------- | ------------------ | ------------------------------- | ------------------------------------- |
-| **ClickHouse** (`@mastra/clickhouse`)                            | insert-only        | insert-only                     | Production (high-volume)              |
+| **[ClickHouse](https://mastra.ai/reference/storage/clickhouse)** | insert-only        | insert-only                     | Production (high-volume)              |
 | **[PostgreSQL](https://mastra.ai/reference/storage/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
 | **[MSSQL](https://mastra.ai/reference/storage/mssql)**           | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
 | **[MongoDB](https://mastra.ai/reference/storage/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
@@ -143,7 +143,7 @@ Observability data grows quickly in production environments. A single agent inte
 
 ### Recommended: ClickHouse for High-Volume Production
 
-[ClickHouse](https://mastra.ai/reference/storage/composite) is a columnar database designed for high-volume analytics workloads. It's the recommended choice for production observability because:
+[ClickHouse](https://mastra.ai/reference/storage/clickhouse) is a columnar database designed for high-volume analytics workloads. It's the recommended choice for production observability because:
 
 - **Optimized for writes**: Handles millions of inserts per second
 - **Efficient compression**: Reduces storage costs for trace data

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

@@ -1,31 +1,31 @@
 # Laminar exporter
 
-[Laminar](https://laminar.sh/) is an open-source platform for engineering LLM products. The Laminar exporter sends your Mastra traces to Laminar via OTLP/HTTP (protobuf), with Laminar-native span attributes for correct rendering (paths, inputs/outputs, tags, metadata).
+[Laminar](https://laminar.sh/) is an open-source, OpenTelemetry-native observability platform for AI agents. Trace, debug, and monitor every Mastra agent run, model step, tool call, and sub-agent with a single `MastraExporter` wired into your `Observability` config.
 
 ## Installation
 
 **npm**:
 
 ```bash
-npm install @mastra/laminar@latest
+npm install @lmnr-ai/lmnr
 ```
 
 **pnpm**:
 
 ```bash
-pnpm add @mastra/laminar@latest
+pnpm add @lmnr-ai/lmnr
 ```
 
 **Yarn**:
 
 ```bash
-yarn add @mastra/laminar@latest
+yarn add @lmnr-ai/lmnr
 ```
 
 **Bun**:
 
 ```bash
-bun add @mastra/laminar@latest
+bun add @lmnr-ai/lmnr
 ```
 
 ## Configuration
@@ -42,7 +42,6 @@ LMNR_PROJECT_API_KEY=lmnr_...
 
 # Optional
 LMNR_BASE_URL=https://api.lmnr.ai
-LAMINAR_ENDPOINT=https://api.lmnr.ai/v1/traces
 ```
 
 ### Zero-Config Setup
@@ -52,14 +51,16 @@ With environment variables set, use the exporter with no configuration:
 ```typescript
 import { Mastra } from '@mastra/core'
 import { Observability } from '@mastra/observability'
-import { LaminarExporter } from '@mastra/laminar'
+import { Laminar, MastraExporter } from '@lmnr-ai/lmnr'
+
+Laminar.initialize()
 
 export const mastra = new Mastra({
   observability: new Observability({
     configs: {
       laminar: {
         serviceName: 'my-service',
-        exporters: [new LaminarExporter()],
+        exporters: [new MastraExporter()],
       },
     },
   }),
@@ -73,7 +74,13 @@ You can also pass credentials directly (takes precedence over environment variab
 ```typescript
 import { Mastra } from '@mastra/core'
 import { Observability } from '@mastra/observability'
-import { LaminarExporter } from '@mastra/laminar'
+import { Laminar, MastraExporter } from '@lmnr-ai/lmnr'
+
+Laminar.initialize({
+  projectApiKey: process.env.LMNR_PROJECT_API_KEY!,
+  baseUrl: process.env.LMNR_BASE_URL, // Optional
+  // ...other options
+})
 
 export const mastra = new Mastra({
   observability: new Observability({
@@ -81,10 +88,7 @@ export const mastra = new Mastra({
       laminar: {
         serviceName: 'my-service',
         exporters: [
-          new LaminarExporter({
-            apiKey: process.env.LMNR_PROJECT_API_KEY!,
-            baseUrl: process.env.LMNR_BASE_URL, // Optional
-            endpoint: process.env.LAMINAR_ENDPOINT, // Optional
+          new MastraExporter({
             realtime: process.env.NODE_ENV === 'development', // Optional
           }),
         ],
@@ -94,7 +98,11 @@ export const mastra = new Mastra({
 })
 ```
 
+> **Note:** For advanced usage, including the full `MastraExporter` options and multi-agent trace examples, see [Laminar's Mastra integration guide](https://laminar.sh/docs/tracing/integrations/mastra).
+
+Mastra also ships a standalone [`LaminarExporter`](https://mastra.ai/reference/observability/tracing/exporters/laminar) in `@mastra/laminar` that sends spans over OTLP/HTTP. It cannot inherit an active OTel context and does not fully map Mastra spans to Laminar's native format, so use the `@lmnr-ai/lmnr` integration above for `observe()` wrappers, multi-agent root spans, and accurate Laminar rendering.
+
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
-- [Laminar Documentation](https://docs.laminar.sh)
+- [Laminar Documentation](https://laminar.sh/docs)

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

@@ -0,0 +1,80 @@
+# Background task streaming
+
+**Added in:** `@mastra/core@1.29.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/guides/build-your-ui/assistant-ui.md

@@ -2,7 +2,7 @@
 
 [Assistant UI](https://assistant-ui.com) is the TypeScript/React library for AI Chat. Built on shadcn/ui and Tailwind CSS, it enables developers to create beautiful, enterprise-grade chat experiences in minutes.
 
-> **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/runtimes/mastra/full-stack-integration) on Assistant UI's documentation site.
+> **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/integrations/frameworks/mastra/full-stack) on Assistant UI's documentation site.
 
 > **Tip:** Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of Assistant UI integrated with Mastra.
 

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

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 179 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 181 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -125,6 +125,7 @@ ANTHROPIC_API_KEY=ant-...
 | `nousresearch/hermes-4-405b`                                    |
 | `nousresearch/hermes-4-70b`                                     |
 | `nvidia/nemotron-3-nano-30b-a3b:free`                           |
+| `nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free`            |
 | `nvidia/nemotron-3-super-120b-a12b`                             |
 | `nvidia/nemotron-3-super-120b-a12b:free`                        |
 | `nvidia/nemotron-nano-12b-v2-vl:free`                           |
@@ -155,6 +156,7 @@ ANTHROPIC_API_KEY=ant-...
 | `openai/gpt-5.4-nano`                                           |
 | `openai/gpt-5.4-pro`                                            |
 | `openai/gpt-5.5`                                                |
+| `openai/gpt-5.5-pro`                                            |
 | `openai/gpt-oss-120b`                                           |
 | `openai/gpt-oss-120b:exacto`                                    |
 | `openai/gpt-oss-120b:free`                                      |

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 3775 models from 106 providers through a single API.
 
 ## Features
 

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

@@ -109,7 +109,7 @@ const response = await agent.generate("Hello!", {
 
 **structuredOutputMode** (`"outputFormat" | "jsonTool" | "auto" | undefined`)
 
-**thinking** (`{ type: "adaptive"; } | { type: "enabled"; budgetTokens?: number | undefined; } | { type: "disabled"; } | undefined`)
+**thinking** (`{ type: "adaptive"; display?: "omitted" | "summarized" | undefined; } | { type: "enabled"; budgetTokens?: number | undefined; } | { type: "disabled"; } | undefined`)
 
 **disableParallelToolUse** (`boolean | undefined`)
 
@@ -123,7 +123,9 @@ const response = await agent.generate("Hello!", {
 
 **toolStreaming** (`boolean | undefined`)
 
-**effort** (`"low" | "medium" | "high" | "max" | undefined`)
+**effort** (`"low" | "medium" | "high" | "xhigh" | "max" | undefined`)
+
+**taskBudget** (`{ type: "tokens"; total: number; remaining?: number | undefined; } | undefined`)
 
 **speed** (`"fast" | "standard" | undefined`)
 

package/.docs/models/providers/baseten.md

@@ -1,6 +1,6 @@
 # ![Baseten logo](https://models.dev/logos/baseten.svg)Baseten
 
-Access 10 Baseten models through Mastra's model router. Authentication is handled automatically using the `BASETEN_API_KEY` environment variable.
+Access 11 Baseten models through Mastra's model router. Authentication is handled automatically using the `BASETEN_API_KEY` environment variable.
 
 Learn more in the [Baseten documentation](https://docs.baseten.co/development/model-apis/overview).
 
@@ -36,6 +36,7 @@ for await (const chunk of stream) {
 | -------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
 | `baseten/deepseek-ai/DeepSeek-V3-0324` | 164K    |       |           |       |       |       | $0.77      | $0.77       |
 | `baseten/deepseek-ai/DeepSeek-V3.1`    | 164K    |       |           |       |       |       | $0.50      | $2          |
+| `baseten/deepseek-ai/DeepSeek-V4-Pro`  | 1.0M    |       |           |       |       |       | $2         | $3          |
 | `baseten/MiniMaxAI/MiniMax-M2.5`       | 204K    |       |           |       |       |       | $0.30      | $1          |
 | `baseten/moonshotai/Kimi-K2.5`         | 262K    |       |           |       |       |       | $0.60      | $3          |
 | `baseten/moonshotai/Kimi-K2.6`         | 262K    |       |           |       |       |       | $0.95      | $4          |