@mastra/mcp-docs-server 1.0.0-beta.10 → 1.0.0-beta.11

package/.docs/raw/reference/processors/processor-interface.mdx

@@ -9,7 +9,7 @@ The `Processor` interface defines the contract for all processors in Mastra. Pro
 
 ## When processor methods run
 
-The four processor methods run at different points in the agent execution lifecycle:
+The five processor methods run at different points in the agent execution lifecycle:
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -39,6 +39,11 @@ The four processor methods run at different points in the agent execution lifecy
 │  │  └──────────┬───────────┘                               │    │
 │  │             │                                           │    │
 │  │             ▼                                           │    │
+│  │  ┌──────────────────────┐                               │    │
+│  │  │  processOutputStep   │  ← Runs after EACH LLM step   │    │
+│  │  └──────────┬───────────┘                               │    │
+│  │             │                                           │    │
+│  │             ▼                                           │    │
 │  │     Tool Execution (if needed)                          │    │
 │  │             │                                           │    │
 │  │             └──────── Loop back if tools called ────────│    │
@@ -60,6 +65,7 @@ The four processor methods run at different points in the agent execution lifecy
 | `processInput` | Once at the start, before the agentic loop | Validate/transform initial user input, add context |
 | `processInputStep` | At each step of the agentic loop, before each LLM call | Transform messages between steps, handle tool results |
 | `processOutputStream` | On each streaming chunk during LLM response | Filter/modify streaming content, detect patterns in real-time |
+| `processOutputStep` | After each LLM response, before tool execution | Validate output quality, implement guardrails with retry |
 | `processOutputResult` | Once after generation completes | Post-process final response, log results |
 
 ## Interface definition
@@ -70,9 +76,10 @@ interface Processor<TId extends string = string> {
   readonly name?: string;
 
   processInput?(args: ProcessInputArgs): Promise<ProcessInputResult> | ProcessInputResult;
+  processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
   processOutputStream?(args: ProcessOutputStreamArgs): Promise<ChunkType | null | undefined>;
+  processOutputStep?(args: ProcessOutputStepArgs): ProcessorMessageResult;
   processOutputResult?(args: ProcessOutputResultArgs): ProcessorMessageResult;
-  processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
 }
 ```
 
@@ -129,10 +136,16 @@ processInput?(args: ProcessInputArgs): Promise<ProcessInputResult> | ProcessInpu
     },
     {
       name: "abort",
-      type: "(reason?: string) => never",
-      description: "Function to abort processing. Throws a TripWire error that stops execution.",
+      type: "(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never",
+      description: "Function to abort processing. Throws a TripWire error that stops execution. Pass `retry: true` to request the LLM retry the step with feedback.",
       isOptional: false,
     },
+    {
+      name: "retryCount",
+      type: "number",
+      description: "Number of times processors have triggered retry for this generation. Use this to limit retry attempts.",
+      isOptional: true,
+    },
     {
       name: "tracingContext",
       type: "TracingContext",
@@ -185,8 +198,8 @@ processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
 #### Execution order in the agentic loop
 
 1. `processInput` (once at start)
-2. `processInputStep` (at each step, before LLM call)
-3. `prepareStep` callback (if provided)
+2. `processInputStep` from inputProcessors (at each step, before LLM call)
+3. `prepareStep` callback (runs as part of the processInputStep pipeline, after inputProcessors)
 4. LLM execution
 5. Tool execution (if needed)
 6. Repeat from step 2 if tools were called
@@ -198,13 +211,13 @@ processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
     {
       name: "messages",
       type: "MastraDBMessage[]",
-      description: "All messages including tool calls and results from previous steps.",
+      description: "All messages including tool calls and results from previous steps (read-only snapshot).",
       isOptional: false,
     },
     {
       name: "messageList",
       type: "MessageList",
-      description: "MessageList instance for managing messages.",
+      description: "MessageList instance for managing messages. Can mutate directly or return in result.",
       isOptional: false,
     },
     {
@@ -213,12 +226,60 @@ processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
       description: "Current step number (0-indexed). Step 0 is the initial LLM call.",
       isOptional: false,
     },
+    {
+      name: "steps",
+      type: "StepResult[]",
+      description: "Results from previous steps, including text, toolCalls, and toolResults.",
+      isOptional: false,
+    },
     {
       name: "systemMessages",
       type: "CoreMessage[]",
-      description: "All system messages for read/modify access.",
+      description: "All system messages (read-only snapshot). Return in result to replace.",
       isOptional: false,
     },
+    {
+      name: "model",
+      type: "MastraLanguageModelV2",
+      description: "Current model being used. Return a different model in result to switch.",
+      isOptional: false,
+    },
+    {
+      name: "toolChoice",
+      type: "ToolChoice",
+      description: "Current tool choice setting ('auto', 'none', 'required', or specific tool).",
+      isOptional: true,
+    },
+    {
+      name: "activeTools",
+      type: "string[]",
+      description: "Currently active tool names. Return filtered array to limit tools.",
+      isOptional: true,
+    },
+    {
+      name: "tools",
+      type: "ToolSet",
+      description: "Current tools available for this step. Return in result to add/replace tools.",
+      isOptional: true,
+    },
+    {
+      name: "providerOptions",
+      type: "SharedV2ProviderOptions",
+      description: "Provider-specific options (e.g., Anthropic cacheControl, OpenAI reasoningEffort).",
+      isOptional: true,
+    },
+    {
+      name: "modelSettings",
+      type: "CallSettings",
+      description: "Model settings like temperature, maxTokens, topP.",
+      isOptional: true,
+    },
+    {
+      name: "structuredOutput",
+      type: "StructuredOutputOptions",
+      description: "Structured output configuration (schema, output mode). Return in result to modify.",
+      isOptional: true,
+    },
     {
       name: "abort",
       type: "(reason?: string) => never",
@@ -240,12 +301,99 @@ processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
   ]}
 />
 
+#### ProcessInputStepResult
+
+The method can return any combination of these properties:
+
+<PropertiesTable
+  content={[
+    {
+      name: "model",
+      type: "LanguageModelV2 | string",
+      description: "Change the model for this step. Can be a model instance or router ID like 'openai/gpt-4o'.",
+      isOptional: true,
+    },
+    {
+      name: "toolChoice",
+      type: "ToolChoice",
+      description: "Change tool selection behavior for this step.",
+      isOptional: true,
+    },
+    {
+      name: "activeTools",
+      type: "string[]",
+      description: "Filter which tools are available for this step.",
+      isOptional: true,
+    },
+    {
+      name: "tools",
+      type: "ToolSet",
+      description: "Replace or modify tools for this step. Use spread to merge: { tools: { ...tools, newTool } }.",
+      isOptional: true,
+    },
+    {
+      name: "messages",
+      type: "MastraDBMessage[]",
+      description: "Replace all messages. Cannot be used with messageList.",
+      isOptional: true,
+    },
+    {
+      name: "messageList",
+      type: "MessageList",
+      description: "Return the same messageList instance (indicates you mutated it). Cannot be used with messages.",
+      isOptional: true,
+    },
+    {
+      name: "systemMessages",
+      type: "CoreMessage[]",
+      description: "Replace all system messages for this step only.",
+      isOptional: true,
+    },
+    {
+      name: "providerOptions",
+      type: "SharedV2ProviderOptions",
+      description: "Change provider-specific options for this step.",
+      isOptional: true,
+    },
+    {
+      name: "modelSettings",
+      type: "CallSettings",
+      description: "Change model settings for this step.",
+      isOptional: true,
+    },
+    {
+      name: "structuredOutput",
+      type: "StructuredOutputOptions",
+      description: "Change structured output configuration for this step.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+#### Processor chaining
+
+When multiple processors implement `processInputStep`, they run in order and changes chain through:
+
+```
+Processor 1: receives { model: 'gpt-4o' } → returns { model: 'gpt-4o-mini' }
+Processor 2: receives { model: 'gpt-4o-mini' } → returns { toolChoice: 'none' }
+Final: model = 'gpt-4o-mini', toolChoice = 'none'
+```
+
+#### System message isolation
+
+System messages are **reset to their original values** at the start of each step. Modifications made in `processInputStep` only affect the current step, not subsequent steps.
+
 #### Use cases
 
+- Dynamic model switching based on step number or context
+- Disabling tools after a certain number of steps
+- Dynamically adding or replacing tools based on conversation context
 - Transforming message part types between providers (e.g., `reasoning` → `thinking` for Anthropic)
 - Modifying messages based on step number or accumulated context
-- Implementing per-step message filtering or enrichment
-- Adding step-specific context or instructions
+- Adding step-specific system instructions
+- Adjusting provider options per step (e.g., cache control)
+- Modifying structured output schema based on step context
 
 ---
 
@@ -358,6 +506,125 @@ processOutputResult?(args: ProcessOutputResultArgs): ProcessorMessageResult;
   ]}
 />
 
+---
+
+### processOutputStep
+
+Processes output after each LLM response in the agentic loop, before tool execution. Unlike `processOutputResult` which runs once at the end, this runs at every step. This is the ideal method for implementing guardrails that can trigger retries.
+
+```typescript copy
+processOutputStep?(args: ProcessOutputStepArgs): ProcessorMessageResult;
+```
+
+#### ProcessOutputStepArgs
+
+<PropertiesTable
+  content={[
+    {
+      name: "messages",
+      type: "MastraDBMessage[]",
+      description: "All messages including the latest LLM response.",
+      isOptional: false,
+    },
+    {
+      name: "messageList",
+      type: "MessageList",
+      description: "MessageList instance for managing messages.",
+      isOptional: false,
+    },
+    {
+      name: "stepNumber",
+      type: "number",
+      description: "Current step number (0-indexed).",
+      isOptional: false,
+    },
+    {
+      name: "finishReason",
+      type: "string",
+      description: "The finish reason from the LLM (stop, tool-use, length, etc.).",
+      isOptional: true,
+    },
+    {
+      name: "toolCalls",
+      type: "ToolCallInfo[]",
+      description: "Tool calls made in this step (if any).",
+      isOptional: true,
+    },
+    {
+      name: "text",
+      type: "string",
+      description: "Generated text from this step.",
+      isOptional: true,
+    },
+    {
+      name: "systemMessages",
+      type: "CoreMessage[]",
+      description: "All system messages for read/modify access.",
+      isOptional: true,
+    },
+    {
+      name: "abort",
+      type: "(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never",
+      description: "Function to abort processing. Pass `retry: true` to request the LLM retry the step.",
+      isOptional: false,
+    },
+    {
+      name: "retryCount",
+      type: "number",
+      description: "Number of times processors have triggered retry. Use this to limit retry attempts.",
+      isOptional: true,
+    },
+    {
+      name: "tracingContext",
+      type: "TracingContext",
+      description: "Tracing context for observability.",
+      isOptional: true,
+    },
+    {
+      name: "requestContext",
+      type: "RequestContext",
+      description: "Request-scoped context with execution metadata.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+#### Use cases
+
+- Implementing quality guardrails that can request retries
+- Validating LLM output before tool execution
+- Adding per-step logging or metrics
+- Implementing output moderation with retry capability
+
+#### Example: Quality guardrail with retry
+
+```typescript title="src/mastra/processors/quality-guardrail.ts" showLineNumbers copy
+import type { Processor } from "@mastra/core";
+
+export class QualityGuardrail implements Processor {
+  id = "quality-guardrail";
+
+  async processOutputStep({ text, abort, retryCount }) {
+    const score = await evaluateResponseQuality(text);
+
+    if (score < 0.7) {
+      if (retryCount < 3) {
+        // Request retry with feedback for the LLM
+        abort("Response quality too low. Please provide more detail.", {
+          retry: true,
+          metadata: { qualityScore: score },
+        });
+      } else {
+        // Max retries reached, block the response
+        abort("Response quality too low after multiple attempts.");
+      }
+    }
+
+    return [];
+  }
+}
+```
+
 ## Processor types
 
 Mastra provides type aliases to ensure processors implement the required methods:
@@ -369,9 +636,10 @@ type InputProcessor = Processor & (
   | { processInputStep: required }
 );
 
-// Must implement processOutputStream OR processOutputResult (or both)
+// Must implement processOutputStream, processOutputStep, OR processOutputResult (or any combination)
 type OutputProcessor = Processor & (
   | { processOutputStream: required }
+  | { processOutputStep: required }
   | { processOutputResult: required }
 );
 ```
@@ -404,13 +672,46 @@ export class LowercaseProcessor implements Processor {
 
 ### Per-step processor with processInputStep
 
+```typescript title="src/mastra/processors/dynamic-model.ts" showLineNumbers copy
+import type { Processor, ProcessInputStepArgs, ProcessInputStepResult } from "@mastra/core";
+
+export class DynamicModelProcessor implements Processor {
+  id = "dynamic-model";
+
+  async processInputStep({
+    stepNumber,
+    steps,
+    toolChoice,
+  }: ProcessInputStepArgs): Promise<ProcessInputStepResult> {
+    // Use a fast model for initial response
+    if (stepNumber === 0) {
+      return { model: "openai/gpt-4o-mini" };
+    }
+
+    // Switch to powerful model after tool calls
+    if (steps.length > 0 && steps[steps.length - 1].toolCalls?.length) {
+      return { model: "openai/gpt-4o" };
+    }
+
+    // Disable tools after 5 steps to force completion
+    if (stepNumber > 5) {
+      return { toolChoice: "none" };
+    }
+
+    return {};
+  }
+}
+```
+
+### Message transformer with processInputStep
+
 ```typescript title="src/mastra/processors/reasoning-transformer.ts" showLineNumbers copy
 import type { Processor, MastraDBMessage } from "@mastra/core";
 
 export class ReasoningTransformer implements Processor {
   id = "reasoning-transformer";
 
-  async processInputStep({ messages, messageList, stepNumber }) {
+  async processInputStep({ messages, messageList }) {
     // Transform reasoning parts to thinking parts at each step
     // This is useful when switching between model providers
     for (const msg of messages) {

package/.docs/raw/reference/streaming/ChunkType.mdx

@@ -1255,7 +1255,7 @@ Contains monitoring and observability data from agent execution. Can include wor
 
 ### tripwire
 
-Emitted when the stream is forcibly terminated due to content being blocked by output processors. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed.
+Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.
 
 <PropertiesTable
   content={[
@@ -1274,11 +1274,32 @@ Emitted when the stream is forcibly terminated due to content being blocked by o
           type: "TripwirePayload",
           parameters: [
             {
-              name: "tripwireReason",
+              name: "reason",
               type: "string",
               description:
                 "Explanation of why the content was blocked (e.g., 'Output processor blocked content')",
             },
+            {
+              name: "retry",
+              type: "boolean",
+              isOptional: true,
+              description:
+                "Whether the processor requested a retry of the step",
+            },
+            {
+              name: "metadata",
+              type: "unknown",
+              isOptional: true,
+              description:
+                "Additional metadata from the processor (e.g., scores, categories)",
+            },
+            {
+              name: "processorId",
+              type: "string",
+              isOptional: true,
+              description:
+                "ID of the processor that triggered the tripwire",
+            },
           ],
         },
       ],

package/.docs/raw/reference/streaming/agents/stream.mdx

@@ -12,13 +12,7 @@ The `.stream()` method enables real-time streaming of responses from an agent wi
 ## Usage example
 
 ```ts title="index.ts" copy
-// Default Mastra format
-const mastraStream = await agent.stream("message for agent");
-
-// AI SDK v5 compatible format
-const aiSdkStream = await agent.stream("message for agent", {
-  format: "aisdk",
-});
+const stream = await agent.stream("message for agent");
 ```
 
 :::info
@@ -50,14 +44,6 @@ const aiSdkStream = await agent.stream("message for agent", {
 
 <PropertiesTable
   content={[
-    {
-      name: "format",
-      type: "'mastra' | 'aisdk'",
-      isOptional: true,
-      defaultValue: "'mastra'",
-      description:
-        "Determines the output stream format. Use 'mastra' for Mastra's native format (default) or 'aisdk' for AI SDK v5 compatibility.",
-    },
     {
       name: "maxSteps",
       type: "number",
@@ -650,9 +636,9 @@ const aiSdkStream = await agent.stream("message for agent", {
   content={[
     {
       name: "stream",
-      type: "MastraModelOutput<Output> | AISDKV5OutputStream<Output>",
+      type: "MastraModelOutput<Output>",
       description:
-        "Returns a streaming interface based on the format parameter. When format is 'mastra' (default), returns MastraModelOutput. When format is 'aisdk', returns AISDKV5OutputStream for AI SDK v5 compatibility.",
+        "Returns a MastraModelOutput instance that provides access to the streaming output.",
     },
     {
       name: "traceId",
@@ -683,32 +669,34 @@ for await (const chunk of stream.textStream) {
   console.log(chunk);
 }
 
+// or access full stream
+for await (const chunk of stream.fullStream) {
+  console.log(chunk);
+}
+
 // Get full text after streaming
 const fullText = await stream.text;
 ```
 
 ### AI SDK v5 Format
 
+To use the stream with AI SDK v5, you can convert it using our utility function `toAISdkStream`.
+
 ```ts title="index.ts" showLineNumbers copy
-import { stepCountIs } from "ai-v5";
+import { stepCountIs, createUIMessageStreamResponse } from "ai";
+import { toAISdkStream } from "@mastra/ai-sdk";
 
 const stream = await agent.stream("Tell me a story", {
-  format: "aisdk",
   stopWhen: stepCountIs(3), // Stop after 3 steps
   modelSettings: {
     temperature: 0.7,
   },
 });
 
-// Use with AI SDK v5 compatible interfaces
-for await (const part of stream.fullStream) {
-  if (part.type === "text-delta") {
-    console.log(part.text);
-  }
-}
-
 // In an API route for frontend integration
-return stream.toUIMessageStreamResponse();
+return createUIMessageStreamResponse({
+  stream: toAISdkStream(stream, { from: "agent" }),
+})
 ```
 
 ### Using Callbacks
@@ -744,10 +732,9 @@ for await (const chunk of stream.textStream) {
 
 ```ts title="index.ts" showLineNumbers copy
 import { z } from "zod";
-import { stepCountIs } from "ai-v5";
+import { stepCountIs } from "ai";
 
 await agent.stream("message for agent", {
-  format: "aisdk", // Enable AI SDK v5 compatibility
   stopWhen: stepCountIs(3), // Stop after 3 steps
   modelSettings: {
     temperature: 0.7,

package/.docs/raw/reference/workflows/workflow-methods/foreach.mdx

@@ -5,7 +5,7 @@ description: Documentation for the `Workflow.foreach()` method in workflows, whi
 
 # Workflow.foreach()
 
-The `.foreach()` method creates a loop that executes a step for each item in an array.
+The `.foreach()` method creates a loop that executes a step for each item in an array. It always returns an array containing the output from each iteration, preserving the original order.
 
 ## Usage example
 
@@ -50,11 +50,76 @@ workflow.foreach(step1, { concurrency: 2 });
     {
       name: "workflow",
       type: "Workflow",
-      description: "The workflow instance for method chaining",
+      description: "The workflow instance for method chaining. The output type is an array of the step's output type.",
     },
   ]}
 />
 
+## Behavior
+
+### Execution and waiting
+
+The `.foreach()` method processes all items before the next step executes. The step following `.foreach()` only runs after every iteration has completed, regardless of concurrency settings. With `concurrency: 1` (default), items process sequentially. With higher concurrency, items process in parallel batches, but the next step still waits for all batches to finish.
+
+If you need to run multiple operations per item, use a nested workflow as the step. This keeps all operations for each item together and is cleaner than chaining multiple `.foreach()` calls. See [Nested workflows inside foreach](/docs/v1/workflows/control-flow#nested-workflows-inside-foreach) for examples.
+
+### Output structure
+
+`.foreach()` always outputs an array. Each element in the output array corresponds to the result of processing the element at the same index in the input array.
+
+```typescript copy
+// Input: [{ value: 1 }, { value: 2 }, { value: 3 }]
+// Step adds 10 to each value
+// Output: [{ value: 11 }, { value: 12 }, { value: 13 }]
+```
+
+### Using `.then()` after `.foreach()`
+
+When you chain `.then()` after `.foreach()`, the next step receives the entire output array as its input. This allows you to aggregate or process all results together.
+
+```typescript copy
+workflow
+  .foreach(processItemStep)    // Output: array of processed items
+  .then(aggregateStep)         // Input: the entire array
+  .commit();
+```
+
+### Using `.map()` after `.foreach()`
+
+Use `.map()` to transform the array output before passing it to the next step:
+
+```typescript copy
+workflow
+  .foreach(processItemStep)
+  .map(async ({ inputData }) => ({
+    total: inputData.reduce((sum, item) => sum + item.value, 0),
+    count: inputData.length
+  }))
+  .then(nextStep)
+  .commit();
+```
+
+### Chaining multiple `.foreach()` calls
+
+When you chain `.foreach()` calls, each operates on the array from the previous step:
+
+```typescript copy
+workflow
+  .foreach(stepA)    // If input is [a, b, c], output is [A, B, C]
+  .foreach(stepB)    // Operates on [A, B, C], output is [A', B', C']
+  .commit();
+```
+
+If a step inside `.foreach()` returns an array, the output becomes an array of arrays. Use `.map()` with `.flat()` to flatten:
+
+```typescript copy
+workflow
+  .foreach(chunkStep)           // Output: [[chunk1, chunk2], [chunk3, chunk4]]
+  .map(async ({ inputData }) => inputData.flat())  // Output: [chunk1, chunk2, chunk3, chunk4]
+  .foreach(embedStep)
+  .commit();
+```
+
 ## Related
 
-- [Repeating with foreach](/docs/v1/workflows/control-flow#looping-with-foreach)
+- [Looping with foreach](/docs/v1/workflows/control-flow#looping-with-foreach)

package/.docs/raw/reference/workflows/workflow.mdx

@@ -130,9 +130,32 @@ A workflow's `status` indicates its current execution state. The possible values
       description:
         "Workflow execution is paused waiting for resume, with suspended step information",
     },
+    {
+      name: "tripwire",
+      type: "string",
+      description:
+        "Workflow was terminated by a processor tripwire. This occurs when an agent step within the workflow triggers a tripwire (e.g., content was blocked by a guardrail). The tripwire information is available on the result.",
+    },
   ]}
 />
 
+### Handling tripwire status
+
+When a workflow contains an agent step that triggers a tripwire, the workflow returns with `status: 'tripwire'` and includes tripwire details:
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+const result = await run.start({ inputData: { message: "Hello" } });
+
+if (result.status === "tripwire") {
+  console.log("Workflow terminated by tripwire:", result.tripwire?.reason);
+  console.log("Processor ID:", result.tripwire?.processorId);
+  console.log("Retry requested:", result.tripwire?.retry);
+}
+```
+
+This is distinct from `status: 'failed'` which indicates an unexpected error. A tripwire status means a processor intentionally stopped execution (e.g., for content moderation).
+
 ## Related
 
 - [Step Class](./step)