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

package/.docs/raw/reference/workflows/run-methods/timeTravel.mdx

@@ -0,0 +1,310 @@
+---
+title: "Reference: Run.timeTravel() | Workflows"
+description: Documentation for the `Run.timeTravel()` method in workflows, which re-executes a workflow from a specific step.
+---
+
+# Run.timeTravel()
+
+The `.timeTravel()` method re-executes a workflow starting from any specific step, using either stored snapshot data or custom context you provide. This is useful for debugging failed workflows, testing individual steps with different inputs, or recovering from errors without re-running the entire workflow.
+
+## Usage example
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const result = await run.timeTravel({
+  step: "step2",
+  inputData: { value: 10 },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step<string, any, TInputSchema, any, any, any, TEngineType> | [...Step<string, any, any, any, any, any, TEngineType>[], Step<string, any, TInputSchema, any, any, any, TEngineType>] | string | string[]",
+      description:
+        "The target step to start execution from. It can be a Step instance, array of Steps (for nested workflows), step ID string, or array of step ID strings. Use dot notation or arrays for nested workflow steps (e.g., 'nestedWorkflow.step3' or ['nestedWorkflow', 'step3'])",
+      isOptional: false,
+    },
+    {
+      name: "inputData",
+      type: "z.infer<TInputSchema>",
+      description: "Input data for the target step. Must match the step's input schema. If not provided, uses data from the workflow snapshot",
+      isOptional: true,
+    },
+    {
+      name: "resumeData",
+      type: "any",
+      description: "Resume data to provide if the workflow was previously suspended",
+      isOptional: true,
+    },
+    {
+      name: "initialState",
+      type: "z.infer<TState>",
+      description: "Initial state to set for the workflow run. Used to set workflow-level state before execution",
+      isOptional: true,
+    },
+    {
+      name: "context",
+      type: "TimeTravelContext<any, any, any, any>",
+      description:
+        "Execution context containing step results for steps before the target step. Each key is a step ID with a StepResult object containing status, payload, output, startedAt, endedAt, suspendPayload, and resumePayload",
+      isOptional: true,
+    },
+    {
+      name: "nestedStepsContext",
+      type: "Record<string, TimeTravelContext<any, any, any, any>>",
+      description:
+        "Context for nested workflow steps. Keyed by nested workflow ID, each containing step results for that nested workflow",
+      isOptional: true,
+    },
+    {
+      name: "requestContext",
+      type: "RequestContext",
+      description: "Request Context data to use during time travel execution",
+      isOptional: true,
+    },
+    {
+      name: "outputWriter",
+      type: "(chunk: TOutput) => Promise<void>",
+      description: "Optional asynchronous function to handle output chunks as they are produced",
+      isOptional: true,
+    },
+    {
+      name: "tracingContext",
+      type: "TracingContext",
+      isOptional: true,
+      description:
+        "Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "currentSpan",
+              type: "Span",
+              isOptional: true,
+              description:
+                "Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "tracingOptions",
+      type: "TracingOptions",
+      isOptional: true,
+      description: "Options for Tracing configuration.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "metadata",
+              type: "Record<string, any>",
+              isOptional: true,
+              description:
+                "Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "requestContextKeys",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "traceId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "parentSpanId",
+              type: "string",
+              isOptional: true,
+              description:
+                "Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "tags",
+              type: "string[]",
+              isOptional: true,
+              description:
+                "Tags to apply to this trace. String labels for categorizing and filtering traces.",
+            },
+          ],
+        },
+      ],
+    },
+    {
+      name: "outputOptions",
+      type: "OutputOptions",
+      isOptional: true,
+      description: "Options for output configuration.",
+      properties: [
+        {
+          parameters: [
+            {
+              name: "includeState",
+              type: "boolean",
+              isOptional: true,
+              description:
+                "Whether to include the workflow run state in the result.",
+            },
+          ],
+        },
+        {
+          parameters: [
+            {
+              name: "includeResumeLabels",
+              type: "boolean",
+              isOptional: true,
+              description:
+                "Whether to include resume labels in the result.",
+            },
+          ],
+        },
+      ],
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>",
+      description:
+        "A promise that resolves to the workflow execution result containing step outputs and status",
+    },
+    {
+      name: "traceId",
+      type: "string",
+      isOptional: true,
+      description:
+        "The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.",
+    },
+  ]}
+/>
+
+## Extended usage examples
+
+### Time travel with custom context
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: "step2",
+  context: {
+    step1: {
+      status: "success",
+      payload: { value: 0 },
+      output: { step1Result: 2 },
+      startedAt: Date.now(),
+      endedAt: Date.now(),
+    },
+  },
+});
+```
+
+### Time travel to nested workflow step
+
+```typescript showLineNumbers copy
+// Using dot notation
+const result = await run.timeTravel({
+  step: "nestedWorkflow.step3",
+  inputData: { value: 10 },
+});
+
+// Using array of step IDs
+const result = await run.timeTravel({
+  step: ["nestedWorkflow", "step3"],
+  inputData: { value: 10 },
+});
+```
+
+### Time travel with initial state
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: "step2",
+  inputData: { value: 10 },
+  initialState: {
+    counter: 5,
+    metadata: { source: "time-travel" },
+  },
+});
+```
+
+### Time travel with nested workflows context
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: "nestedWorkflow.step3",
+  context: {
+    step1: {
+      status: "success",
+      payload: { value: 0 },
+      output: { step1Result: 2 },
+      startedAt: Date.now(),
+      endedAt: Date.now(),
+    },
+    nestedWorkflow: {
+      status: "running",
+      payload: { step1Result: 2 },
+      startedAt: Date.now(),
+    },
+  },
+  nestedStepsContext: {
+    nestedWorkflow: {
+      step2: {
+        status: "success",
+        payload: { step1Result: 2 },
+        output: { step2Result: 3 },
+        startedAt: Date.now(),
+        endedAt: Date.now(),
+      },
+    },
+  },
+});
+```
+
+## Notes
+
+- Time travel requires storage to be configured since it relies on persisted workflow snapshots
+- When re-executing a workflow, the workflow loads the existing snapshot from storage (if available)
+- Step results before the target step are reconstructed from the snapshot or provided context
+- Execution begins from the specified step with the provided or reconstructed input data
+- The workflow continues to completion from that point forward
+- Time travel can be used on workflows that have not been run yet by providing custom context or input data for the step to start from.
+
+
+## Related
+
+- [Time Travel](/docs/v1/workflows/time-travel)
+- [Workflows overview](/docs/v1/workflows/overview#running-workflows)
+- [Workflow.createRun()](../workflow-methods/create-run)
+- [Snapshots](/docs/v1/workflows/snapshots)
+- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Run Class | Workflows | Mastra Docs"
+title: "Reference: Run Class | Workflows"
 description: Documentation for the Run class in Mastra, which represents a workflow execution instance.
 ---
 
@@ -41,14 +41,14 @@ if (result.status === "suspended") {
     },
     {
       name: "stream",
-      type: "(options?: StreamOptions) => Promise<StreamResult>",
-      description: "Monitors workflow execution as a stream of events",
+      type: "(options?: StreamOptions) => MastraWorkflowStream",
+      description: "Monitors workflow execution as a stream of events with enhanced streaming features",
       required: true,
     },
     {
-      name: "streamVNext",
-      type: "(options?: StreamOptions) => MastraWorkflowStream",
-      description: "Enables real-time streaming with enhanced features",
+      name: "resumeStream",
+      type: "(options?: ResumeStreamOptions) => MastraWorkflowStream",
+      description: "Resumes a suspended workflow with streaming support",
       required: true,
     },
     {
@@ -57,6 +57,24 @@ if (result.status === "suspended") {
       description: "Cancels the workflow execution",
       required: true,
     },
+    {
+      name: "restart",
+      type: "(options?: RestartOptions) => Promise<WorkflowResult>",
+      description: "Restarts the workflow execution from last active step",
+      required: true,
+    },
+    {
+      name: "timeTravel",
+      type: "(options?: TimeTravelOptions) => Promise<WorkflowResult>",
+      description: "Re-executes a workflow starting from any specific step, using either stored snapshot data or custom context you provide.",
+      required: true,
+    },
+    {
+      name: "timeTravelStream",
+      type: "(options?: TimeTravelOptions) => MastraWorkflowStream",
+      description: "Time travels a workflow execution with streaming support",
+      required: true,
+    },
   ]}
 />
 
@@ -92,3 +110,7 @@ A workflow run's `status` indicates its current execution state. The possible va
 - [Run.start()](./run-methods/start)
 - [Run.resume()](./run-methods/resume)
 - [Run.cancel()](./run-methods/cancel)
+- [Run.restart()](./run-methods/restart)
+- [Run.timeTravel()](./run-methods/timeTravel)
+- [Run.stream()](/docs/v1/streaming/workflow-streaming)
+- [Run.timeTravelStream()](../streaming/workflows/timeTravelStream)

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Step Class | Workflows | Mastra Docs"
+title: "Reference: Step Class | Workflows"
 description: Documentation for the Step class in Mastra, which defines individual units of work within a workflow.
 ---
 
@@ -32,6 +32,57 @@ const step1 = createStep({
 });
 ```
 
+## Creating steps from agents
+
+You can create a step directly from an agent. The step will use the agent's name as its ID.
+
+### Basic agent step
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { testAgent } from "../agents/test-agent";
+
+const agentStep = createStep(testAgent);
+// inputSchema: { prompt: string }
+// outputSchema: { text: string }
+```
+
+### Agent step with structured output
+
+Pass `structuredOutput` to have the agent return typed structured data:
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const articleSchema = z.object({
+  title: z.string(),
+  summary: z.string(),
+  tags: z.array(z.string()),
+});
+
+const agentStep = createStep(testAgent, {
+  structuredOutput: { schema: articleSchema },
+});
+// inputSchema: { prompt: string }
+// outputSchema: { title: string, summary: string, tags: string[] }
+```
+
+### Agent step options
+
+<PropertiesTable
+  content={[
+    {
+      name: "structuredOutput",
+      type: "{ schema: z.ZodType<any> }",
+      description: "When provided, the agent returns structured data matching this schema instead of plain text. The step's outputSchema is set to the provided schema.",
+      required: false,
+    },
+    {
+      name: "onFinish",
+      type: "(result: AgentResult) => void",
+      description: "Callback invoked when the agent completes generation.",
+      required: false,
+    },
+  ]}
+/>
+
 ## Constructor Parameters
 
 <PropertiesTable
@@ -103,6 +154,12 @@ const step1 = createStep({
       description:
         "The resume data matching the resumeSchema, when resuming the step from a suspended state. Only exists if the step is being resumed.",
     },
+    {
+      name: "suspendData",
+      type: "z.infer<TSuspendSchema>",
+      description:
+        "The suspend data that was originally passed to suspend() when the step was suspended. Only exists if the step is being resumed and was previously suspended with data.",
+    },
     {
       name: "mastra",
       type: "Mastra",
@@ -124,6 +181,12 @@ const step1 = createStep({
       type: "(suspendPayload: any, suspendOptions?: { resumeLabel?: string }) => Promise<void>",
       description: "Function to pause workflow execution",
     },
+    {
+      name: "state",
+      type: "z.infer<TState>",
+      description:
+        "The current workflow state. Contains shared values that persist across all steps and suspend/resume cycles. The structure is defined by the step's stateSchema.",
+    },
     {
       name: "setState",
       type: "(state: z.infer<TState>) => void",
@@ -154,5 +217,6 @@ const step1 = createStep({
 
 ## Related
 
+- [Workflow state](/docs/v1/workflows/workflow-state)
 - [Control flow](/docs/v1/workflows/control-flow)
 - [Using agents and tools](/docs/v1/workflows/agents-and-tools)

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.branch() | Workflows | Mastra Docs"
+title: "Reference: Workflow.branch() | Workflows"
 description: Documentation for the `Workflow.branch()` method in workflows, which creates conditional branches between steps.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.commit() | Workflows | Mastra Docs"
+title: "Reference: Workflow.commit() | Workflows"
 description: Documentation for the `Workflow.commit()` method in workflows, which finalizes the workflow and returns the final result.
 ---
 

package/.docs/raw/reference/workflows/workflow-methods/create-run.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.createRun() | Workflows | Mastra Docs"
+title: "Reference: Workflow.createRun() | Workflows"
 description: Documentation for the `Workflow.createRun()` method in workflows, which creates a new workflow run instance.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.dountil() | Workflows | Mastra Docs"
+title: "Reference: Workflow.dountil() | Workflows"
 description: Documentation for the `Workflow.dountil()` method in workflows, which creates a loop that executes a step until a condition is met.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.dowhile() | Workflows | Mastra Docs"
+title: "Reference: Workflow.dowhile() | Workflows"
 description: Documentation for the `Workflow.dowhile()` method in workflows, which creates a loop that executes a step while a condition is met.
 ---
 

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

@@ -1,11 +1,11 @@
 ---
-title: "Reference: Workflow.foreach() | Workflows | Mastra Docs"
+title: "Reference: Workflow.foreach() | Workflows"
 description: Documentation for the `Workflow.foreach()` method in workflows, which creates a loop that executes a step for each item in an array.
 ---
 
 # 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-methods/map.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.map() | Workflows | Mastra Docs"
+title: "Reference: Workflow.map() | Workflows"
 description: Documentation for the `Workflow.map()` method in workflows, which maps output data from a previous step to the input of a subsequent step.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.parallel() | Workflows | Mastra Docs"
+title: "Reference: Workflow.parallel() | Workflows"
 description: Documentation for the `Workflow.parallel()` method in workflows, which executes multiple steps in parallel.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.sendEvent() | Workflows | Mastra Docs"
+title: "Reference: Workflow.sendEvent() | Workflows"
 description: Documentation for the `Workflow.sendEvent()` method in workflows, which resumes execution when an event is sent.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.sleep() | Workflows | Mastra Docs"
+title: "Reference: Workflow.sleep() | Workflows"
 description: Documentation for the `Workflow.sleep()` method in workflows, which pauses execution for a specified number of milliseconds.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.sleepUntil() | Workflows | Mastra Docs"
+title: "Reference: Workflow.sleepUntil() | Workflows"
 description: Documentation for the `Workflow.sleepUntil()` method in workflows, which pauses execution until a specified date.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.then() | Workflows | Mastra Docs"
+title: "Reference: Workflow.then() | Workflows"
 description: Documentation for the `Workflow.then()` method in workflows, which creates sequential dependencies between steps.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Workflow.waitForEvent() | Workflows | Mastra Docs"
+title: "Reference: Workflow.waitForEvent() | Workflows"
 description: Documentation for the `Workflow.waitForEvent()` method in workflows, which pauses execution until an event is received.
 ---