@mastra/mcp-docs-server 0.0.0-studio-deploy-20260404182525 → 0.0.0-studio-cli-20260504022012

package/.docs/docs/agents/adding-voice.md

@@ -327,23 +327,24 @@ For the complete list of supported AI SDK providers and their capabilities:
 
 Mastra supports multiple voice providers for text-to-speech (TTS) and speech-to-text (STT) capabilities:
 
-| Provider        | Package                         | Features                  | Reference                                                          |
-| --------------- | ------------------------------- | ------------------------- | ------------------------------------------------------------------ |
-| OpenAI          | `@mastra/voice-openai`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/openai)          |
-| OpenAI Realtime | `@mastra/voice-openai-realtime` | Realtime speech-to-speech | [Documentation](https://mastra.ai/reference/voice/openai-realtime) |
-| ElevenLabs      | `@mastra/voice-elevenlabs`      | High-quality TTS          | [Documentation](https://mastra.ai/reference/voice/elevenlabs)      |
-| PlayAI          | `@mastra/voice-playai`          | TTS                       | [Documentation](https://mastra.ai/reference/voice/playai)          |
-| Google          | `@mastra/voice-google`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/google)          |
-| Deepgram        | `@mastra/voice-deepgram`        | STT                       | [Documentation](https://mastra.ai/reference/voice/deepgram)        |
-| Murf            | `@mastra/voice-murf`            | TTS                       | [Documentation](https://mastra.ai/reference/voice/murf)            |
-| Speechify       | `@mastra/voice-speechify`       | TTS                       | [Documentation](https://mastra.ai/reference/voice/speechify)       |
-| Sarvam          | `@mastra/voice-sarvam`          | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/sarvam)          |
-| Azure           | `@mastra/voice-azure`           | TTS, STT                  | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
-| Cloudflare      | `@mastra/voice-cloudflare`      | TTS                       | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
+| Provider        | Package                         | Features                                  | Reference                                                          |
+| --------------- | ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| OpenAI          | `@mastra/voice-openai`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/openai)          |
+| OpenAI Realtime | `@mastra/voice-openai-realtime` | Realtime speech-to-speech                 | [Documentation](https://mastra.ai/reference/voice/openai-realtime) |
+| AWS Nova Sonic  | `@mastra/voice-aws-nova-sonic`  | Realtime speech-to-speech via AWS Bedrock | [Documentation](https://mastra.ai/reference/voice/aws-nova-sonic)  |
+| ElevenLabs      | `@mastra/voice-elevenlabs`      | High-quality TTS                          | [Documentation](https://mastra.ai/reference/voice/elevenlabs)      |
+| PlayAI          | `@mastra/voice-playai`          | TTS                                       | [Documentation](https://mastra.ai/reference/voice/playai)          |
+| Google          | `@mastra/voice-google`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/google)          |
+| Deepgram        | `@mastra/voice-deepgram`        | STT                                       | [Documentation](https://mastra.ai/reference/voice/deepgram)        |
+| Murf            | `@mastra/voice-murf`            | TTS                                       | [Documentation](https://mastra.ai/reference/voice/murf)            |
+| Speechify       | `@mastra/voice-speechify`       | TTS                                       | [Documentation](https://mastra.ai/reference/voice/speechify)       |
+| Sarvam          | `@mastra/voice-sarvam`          | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/sarvam)          |
+| Azure           | `@mastra/voice-azure`           | TTS, STT                                  | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
+| Cloudflare      | `@mastra/voice-cloudflare`      | TTS                                       | [Documentation](https://mastra.ai/reference/voice/mastra-voice)    |
 
 ## Next steps
 
-- [Voice API Reference](https://mastra.ai/reference/voice/mastra-voice) - Detailed API documentation for voice capabilities
-- [Text to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/text-to-speech) - Interactive story generator and other TTS implementations
-- [Speech to Text Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-text) - Voice memo app and other STT implementations
-- [Speech to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-speech) - Real-time voice conversation with call analysis
+- [Voice API Reference](https://mastra.ai/reference/voice/mastra-voice): Detailed API documentation for voice capabilities
+- [Text to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/text-to-speech): Interactive story generator and other TTS implementations
+- [Speech to Text Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-text): Voice memo app and other STT implementations
+- [Speech to Speech Examples](https://github.com/mastra-ai/voice-examples/tree/main/speech-to-speech): Real-time voice conversation with call analysis

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

@@ -72,7 +72,7 @@ Platform webhooks need a public URL to reach your local server. Use a tunnel to
 ngrok http 4111
 
 # cloudflared
-cloudflared tunnel --url http://localhost:4111
+npx cloudflared tunnel --url http://localhost:4111
 ```
 
 Copy the generated URL and use it as the base for your webhook paths (e.g. `https://abc123.ngrok.io/api/agents/support-agent/channels/slack/webhook`).
@@ -164,6 +164,7 @@ By default, only images are sent inline (`inlineMedia: ['image/*']`). Unsupporte
 
 ## Related
 
+- [Guide: Building a Slack assistant](https://mastra.ai/guides/guide/slack-assistant)
 - [Agent overview](https://mastra.ai/docs/agents/overview)
 - [Tool approval](https://mastra.ai/docs/agents/agent-approval)
 - [Channels reference](https://mastra.ai/reference/agents/channels)

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

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

package/.docs/docs/agents/processors.md

@@ -11,6 +11,8 @@ You can use individual [`Processor`](https://mastra.ai/reference/processors/proc
 
 Some processors implement both input and output logic and can be used in either array depending on where the transformation should occur.
 
+Some built-in processors also persist hidden system reminder messages using `<system-reminder>...</system-reminder>` text plus `metadata.systemReminder`. These reminders stay available in raw memory history and retry/prompt reconstruction paths, but standard UI-facing message conversions and default memory recall hide them unless you explicitly opt in.
+
 ## When to use processors
 
 Use processors to:
@@ -81,9 +83,64 @@ Your processors run first, then memory persists messages.
 
 This ordering ensures that if your output guardrail calls `abort()`, memory processors are skipped and no messages are saved. See [Memory Processors](https://mastra.ai/docs/memory/memory-processors) for details.
 
+## Attach processors to an agent
+
+Processors are configured on the agent through three arrays:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { PrefillErrorHandler, TokenLimiter, ModerationProcessor } from '@mastra/core/processors'
+
+const agent = new Agent({
+  name: 'support-agent',
+  model: 'openai/gpt-5',
+  instructions: '...',
+  inputProcessors: [
+    new TokenLimiter(4000),
+    new ModerationProcessor({ model: 'openai/gpt-4.1-nano' }),
+  ],
+  outputProcessors: [new ModerationProcessor({ model: 'openai/gpt-4.1-nano' })],
+  errorProcessors: [new PrefillErrorHandler()],
+})
+```
+
+- `inputProcessors` run before the LLM.
+- `outputProcessors` run during and after the LLM response.
+- `errorProcessors` run when the LLM API call throws, so they can recover from provider errors.
+
+Each array also accepts a function that returns an array, so processors can be built per-request from `RequestContext`:
+
+```typescript
+new Agent({
+  // ...
+  inputProcessors: ({ requestContext }) => {
+    const limit = requestContext.get('tokenLimit') ?? 4000
+    return [new TokenLimiter(limit)]
+  },
+})
+```
+
+### Override processors per call
+
+`agent.generate()` and `agent.stream()` accept the same three arrays. When you pass one, it **replaces** the matching array on the agent for that call only. Memory, workspace, and other framework-managed processors still run around your array.
+
+```typescript
+await agent.stream('Summarize this', {
+  inputProcessors: [new TokenLimiter(2000)],
+  maxProcessorRetries: 5,
+})
+```
+
 ## Create custom processors
 
-Custom processors implement the `Processor` interface:
+Custom processors implement the `Processor` interface.
+
+Processor methods receive two arguments for accessing the conversation:
+
+- `messages`: A snapshot array of `MastraDBMessage` objects for the current stage.
+- `messageList`: The live `MessageList` instance. Use it to read other stages, or to add, remove, or replace messages in place.
+
+Text lives in `message.content.parts`, not on `message.content` itself. Iterate `parts` and filter by `part.type === 'text'` to read user or assistant text. A flattened `message.content.content` string exists for legacy compatibility and can be used as a fallback. See [Message arguments](https://mastra.ai/reference/processors/processor-interface) in the `Processor` reference for full details.
 
 ### Transform input messages
 
@@ -95,12 +152,15 @@ export class CustomInputProcessor implements Processor {
   id = 'custom-input'
 
   async processInput({ messages }: ProcessInputArgs): Promise<MastraDBMessage[]> {
-    // Transform messages before they reach the LLM
+    // Transform messages before they reach the LLM.
+    // Text lives in content.parts — iterate parts and rewrite text parts only.
     return messages.map(msg => ({
       ...msg,
       content: {
         ...msg.content,
-        content: msg.content.content.toLowerCase(),
+        parts: msg.content.parts?.map(part =>
+          part.type === 'text' ? { ...part, text: part.text.toLowerCase() } : part,
+        ),
       },
     }))
   }
@@ -212,12 +272,23 @@ export class StreamFilter implements Processor {
   id = 'stream-filter'
 
   async processOutputStream({ part }): Promise<ChunkType | null> {
-    // Transform or filter streaming chunks
+    // Drop text-delta chunks that contain the word "secret"
+    if (part.type === 'text-delta' && part.payload.text.includes('secret')) {
+      return null
+    }
+
+    // Return the (possibly modified) chunk to emit it
     return part
   }
 }
 ```
 
+Return values:
+
+- A `ChunkType` emits that chunk. Return the original `part` to pass it through unchanged.
+- `null` or `undefined` drops the chunk. Both behave the same way, so a method that falls through without returning also drops the chunk.
+- Dropping only affects one chunk. To stop the stream entirely, call `abort()`.
+
 To also receive custom `data-*` chunks emitted by tools via `writer.custom()`, set `processDataParts = true` on your processor. This lets you inspect, modify, or block tool-emitted data chunks before they reach the client.
 
 ### Validate each response
@@ -244,6 +315,31 @@ export class ResponseValidator implements Processor {
 
 For more on retry behavior, see [Retry mechanism](#retry-mechanism) in Advanced patterns.
 
+### Persist data across chunks and steps
+
+Output methods receive a `state` object that persists for the lifetime of one request. State is keyed by the processor's `id`, so each processor sees only its own data, and it is shared between `processOutputStream`, `processOutputStep`, and `processOutputResult`. A new state object is created for every new `agent.generate()` or `agent.stream()` call.
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+
+export class WordCounter implements Processor {
+  id = 'word-counter'
+
+  async processOutputStream({ part, state }) {
+    state.wordCount ??= 0
+    if (part.type === 'text-delta') {
+      state.wordCount += part.payload.text.split(/\s+/).filter(Boolean).length
+    }
+    return part
+  }
+
+  async processOutputResult({ messages, state }) {
+    console.log(`Total words: ${state.wordCount}`)
+    return messages
+  }
+}
+```
+
 ## Built-in utility processors
 
 Mastra provides utility processors for common tasks:
@@ -271,6 +367,14 @@ See the [`TokenLimiterProcessor` reference](https://mastra.ai/reference/processo
 
 Removes tool calls and results from messages sent to the LLM, saving tokens on verbose tool interactions. Optionally exclude only specific tools. This filter only affects the LLM input, filtered messages are still saved to memory.
 
+By default, `ToolCallFilter` filters the initial input before the agent loop starts. Use `filterAfterToolSteps` to also filter during each loop step while preserving recent tool-producing steps.
+
+```typescript
+new ToolCallFilter({
+  filterAfterToolSteps: 2,
+})
+```
+
 See the [`ToolCallFilter` reference](https://mastra.ai/reference/processors/tool-call-filter) for configuration options and the [Memory Processors](https://mastra.ai/docs/memory/memory-processors) page for pre-memory filtering.
 
 ### `ToolSearchProcessor`
@@ -390,6 +494,23 @@ for await (const chunk of stream.fullStream) {
 
 Custom chunk types must use the `data-` prefix (e.g., `data-moderation-update`, `data-status`).
 
+By default, `processOutputStream()` skips `data-*` chunks so it does not accidentally operate on tool telemetry or other processors' output. To inspect, modify, or block these chunks in a processor, set `processDataParts = true` on that processor:
+
+```typescript
+class ModerationCollector implements Processor {
+  id = 'moderation-collector'
+  processDataParts = true
+
+  async processOutputStream({ part, state }) {
+    if (part.type === 'data-moderation-update') {
+      state.warnings ??= []
+      state.warnings.push(part.data)
+    }
+    return part
+  }
+}
+```
+
 ### Add metadata to messages
 
 You can add custom metadata to messages in `processOutputResult`. This metadata is accessible via the response object:
@@ -525,7 +646,7 @@ const agent = new Agent({
   name: 'Quality Agent',
   model: 'openai/gpt-5.4',
   outputProcessors: [new QualityChecker()],
-  maxProcessorRetries: 3, // Maximum retry attempts (default: 3)
+  maxProcessorRetries: 3, // Maximum retry attempts. If unset, retries are disabled (unless errorProcessors are configured, in which case it defaults to 10).
 })
 ```
 
@@ -536,6 +657,57 @@ The retry mechanism:
 - Tracks retry count via the `retryCount` parameter
 - Respects `maxProcessorRetries` limit on the agent
 
+### Abort and tripwire chunks
+
+Calling `abort(reason, options)` throws a `TripWire` error that ends processing. On streams, Mastra emits a `tripwire` chunk clients can detect:
+
+```typescript
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tripwire') {
+    console.log('Blocked by', chunk.payload.processorId, '-', chunk.payload.reason)
+    break
+  }
+}
+```
+
+For `agent.generate()`, the result exposes the same information as `result.tripwire` with `result.finishReason === 'other'`.
+
+`abort` accepts a second options argument:
+
+- `retry: true` asks the agent to retry instead of ending. Retries require `maxProcessorRetries` to be set on the agent or call.
+- `metadata` attaches structured data to the `tripwire` chunk so downstream consumers can branch on categories like `pii`, `quality`, or `moderation`.
+
+## API error handling
+
+The `processAPIError` method handles LLM API rejections — errors where the API rejects the request (such as 400 or 422 status codes) rather than network or server failures. This lets you modify the request and retry when the API rejects the message format.
+
+```typescript
+import { APICallError } from '@ai-sdk/provider'
+import type { Processor, ProcessAPIErrorArgs, ProcessAPIErrorResult } from '@mastra/core/processors'
+
+export class ContextLengthHandler implements Processor {
+  id = 'context-length-handler'
+
+  processAPIError({
+    error,
+    messageList,
+    retryCount,
+  }: ProcessAPIErrorArgs): ProcessAPIErrorResult | void {
+    if (retryCount > 0) return
+
+    if (APICallError.isInstance(error) && error.message.includes('context length exceeded')) {
+      const messages = messageList.get.all.db()
+      if (messages.length > 4) {
+        messageList.removeByIds([messages[1]!.id, messages[2]!.id])
+        return { retry: true }
+      }
+    }
+  }
+}
+```
+
+Mastra includes a built-in [`PrefillErrorHandler`](https://mastra.ai/reference/processors/prefill-error-handler) that automatically handles the Anthropic "assistant message prefill" error. This processor is auto-injected and requires no configuration.
+
 ## Related documentation
 
 - [Guardrails](https://mastra.ai/docs/agents/guardrails): Security and validation processors

package/.docs/docs/agents/structured-output.md

@@ -8,7 +8,7 @@ Use structured output when you need an agent to return a data object rather than
 
 ## Define schemas
 
-Agents can return structured data by defining the expected output with either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). Zod is recommended because it provides TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
+Agents can return structured data by defining the expected output with either [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) or [JSON Schema](https://json-schema.org/). Libraries like Zod are recommended because they provide TypeScript type inference and runtime validation, while JSON Schema is useful when you need a language agnostic format.
 
 **Zod**:
 
@@ -31,6 +31,49 @@ const response = await testAgent.generate('Help me plan my day.', {
 console.log(response.object)
 ```
 
+**Valibot**:
+
+Define the `output` shape using [Valibot](https://valibot.dev/):
+
+```typescript
+import * as v from 'valibot'
+import { toStandardJsonSchema } from '@valibot/to-json-schema'
+
+const response = await testAgent.generate('Help me plan my day.', {
+  structuredOutput: {
+    schema: toStandardJsonSchema(
+      v.array(
+        v.object({
+          name: v.string(),
+          activities: v.array(v.string()),
+        }),
+      ),
+    ),
+  },
+})
+
+console.log(response.object)
+```
+
+**ArkType**:
+
+Define the `output` shape using [ArkType](https://arktype.io/):
+
+```typescript
+import { type } from 'arktype'
+
+const response = await testAgent.generate('Help me plan my day.', {
+  structuredOutput: {
+    schema: type({
+      name: 'string',
+      activities: 'string[]',
+    }).array(),
+  },
+})
+
+console.log(response.object)
+```
+
 **JSON Schema**:
 
 You can also use JSON Schema to define your output structure:
@@ -210,6 +253,28 @@ const response = await testAgent.generate('Tell me about TypeScript.', {
 })
 ```
 
+If you want that structuring model to also see the current conversation history, set `useAgent: true` alongside `model`. Mastra will reuse the parent agent with the separate structuring model and attach read-only memory context when a thread is available.
+
+```typescript
+const response = await testAgent.generate('Return my profile as structured data.', {
+  memory: {
+    thread: 'thread-123',
+    resource: 'user-123',
+  },
+  structuredOutput: {
+    schema: z.object({
+      favoriteColor: z.string(),
+      hometown: z.string(),
+      petName: z.string(),
+    }),
+    model: 'openai/gpt-5.4',
+    useAgent: true,
+  },
+})
+```
+
+Leave `useAgent` unset if you want the separate structuring model to work only from the current response and not inherit prior conversation memory.
+
 ### Multi-step approach with `prepareStep`
 
 For models that don't support tools and structured outputs together, you can use `prepareStep` to handle them in separate steps.