@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/raw/workflows/overview.mdx

@@ -90,60 +90,28 @@ Workflows can be composed using a number of different methods. The method you ch
 
 ## Workflow state
 
-Workflow state lets you share values across steps without passing them through every step’s inputSchema and outputSchema. All state values are defined in the workflow’s stateSchema, but each step only declares the values it needs. To set initial values, use initialState when running the workflow.
+Workflow state lets you share values across steps without passing them through every step's inputSchema and outputSchema. Use state for tracking progress, accumulating results, or sharing configuration across the entire workflow.
 
 ```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
-  // ...
-  stateSchema: z.object({
-    processedItems: z.array(z.string()),
-  }),
+  id: "step-1",
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ formatted: z.string() }),
+  stateSchema: z.object({ counter: z.number() }),
   execute: async ({ inputData, state, setState }) => {
-    const { message } = inputData;
-    const { processedItems } = state;
-
-    setState({
-      ...state,
-      processedItems: [...processedItems, "item-1", "item-2"],
-    });
-
-    return {
-      formatted: message.toUpperCase(),
-    };
-  },
-});
+    // Read from state
+    console.log(state.counter);
 
-const step2 = createStep({
-  // ...
-  stateSchema: z.object({
-    metadata: z.object({
-      processedBy: z.string(),
-    }),
-  }),
-  execute: async ({ inputData, state }) => {
-    const { formatted } = inputData;
-    const { metadata } = state;
+    // Update state for subsequent steps
+    setState({ ...state, counter: state.counter + 1 });
 
-    return {
-      emphasized: `${formatted}!! ${metadata.processedBy}`,
-    };
+    return { formatted: inputData.message.toUpperCase() };
   },
 });
-
-export const testWorkflow = createWorkflow({
-  // ...
-  stateSchema: z.object({
-    processedItems: z.array(z.string()),
-    metadata: z.object({
-      processedBy: z.string(),
-    }),
-  }),
-})
-  .then(step1)
-  .then(step2)
-  .commit();
 ```
 
+> See [Workflow State](/docs/v1/workflows/workflow-state) for complete documentation on state schemas, initial state, persistence across suspend/resume, and nested workflows.
+
 ## Workflows as steps
 
 Use a workflow as a step to reuse its logic within a larger composition. Input and output follow the same schema rules described in [Core principles](/docs/v1/workflows/control-flow).
@@ -302,6 +270,49 @@ The workflow output includes the full execution lifecycle, showing the input and
 }
 ```
 
+## Restarting active workflow runs
+
+When a workflow run loses connection to the server, it can be restarted from the last active step. This is useful for long-running workflows that might still be running when the server loses connection. Restarting a workflow run will resume execution from the last active step, and the workflow will continue from there.
+
+### Restarting all active workflow runs of a workflow with `restartAllActiveWorkflowRuns()`
+
+Use `restartAllActiveWorkflowRuns()` to restart all active workflow runs of a workflow. This helps restart all active workflow runs of a workflow, without having to manually loop through each run and restart.
+
+```typescript showLineNumbers copy
+workflow.restartAllActiveWorkflowRuns();
+```
+
+### Restarting an active workflow run with `restart()`
+
+Use `restart()` to restart an active workflow run from the last active step. This will resume execution from the last active step, and the workflow will continue from there.
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const result = await run.start({ inputData: { value: "initial data" } });
+
+//.. server connection lost,
+
+const restartedResult = await run.restart();
+```
+
+### Identifying active workflow runs
+
+When a workflow run is active, it will have a `status` of `running` or `waiting`. You can check the workflow's `status` to confirm it's active, and use `active` to identify the active workflow run.
+
+```typescript showLineNumbers copy
+const activeRuns = await workflow.listActiveWorkflowRuns();
+if (activeRuns.runs.length > 0) {
+  console.log(activeRuns.runs);
+}
+```
+
+:::Note
+
+When running the local mastra server, all active workflow runs will be restarted automatically when the server starts.
+
+:::
+
 ## Using `RequestContext`
 
 Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
@@ -335,6 +346,7 @@ Use [Studio](/docs/v1/getting-started/studio) to easily run workflows with diffe
 
 For a closer look at workflows, see our [Workflow Guide](/guides/v1/guide/ai-recruiter), which walks through the core concepts with a practical example.
 
+- [Workflow State](/docs/v1/workflows/workflow-state)
 - [Control Flow](/docs/v1/workflows/control-flow)
 - [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
 - [Error Handling](/docs/v1/workflows/error-handling)

package/.docs/raw/workflows/snapshots.mdx

@@ -268,4 +268,5 @@ if (result.status === "suspended") {
 
 - [Control Flow](/docs/v1/workflows/control-flow)
 - [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Time Travel](/docs/v1/workflows/time-travel)
 - [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)

package/.docs/raw/workflows/suspend-and-resume.mdx

@@ -13,7 +13,7 @@ Use `suspend()` to pause workflow execution at a specific step. You can define a
 - If the condition isn’t met, the workflow pauses and returns `suspend()`.
 - If the condition is met, the workflow continues with the remaining logic in the step.
 
-![Pausing a workflow with suspend()](/img/workflows/workflows-suspend-resume-suspend.jpg)
+![Pausing a workflow with suspend()](/img/workflows/workflows-suspend.jpg)
 
 ```typescript {9-11,16-18} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
@@ -56,13 +56,15 @@ export const testWorkflow = createWorkflow({
 
 ## Restarting a workflow with `resume()`
 
-Use `resume()` to restart a suspended workflow from the step where it paused. To satisfy the step’s suspend condition, pass a value using `resumeData` that matches the step's `resumeSchema`, allowing execution to continue from the suspended step.
+Use `resume()` to restart a suspended workflow from the step where it paused. Pass `resumeData` matching the step's `resumeSchema` to satisfy the suspend condition and continue execution.
 
-![Restarting a workflow with resume()](/img/workflows/workflows-suspend-resume-resume.jpg)
+![Restarting a workflow with resume()](/img/workflows/workflows-resume.jpg)
+
+```typescript showLineNumbers copy
+import { step1 } from "./workflows/test-workflow";
 
-```typescript {13} showLineNumbers copy
 const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRunAsync();
+const run = await workflow.createRun();
 
 await run.start({
   inputData: {
@@ -72,34 +74,99 @@ await run.start({
 
 const handleResume = async () => {
   const result = await run.resume({
-    step: 'step-1',
+    step: step1,
     resumeData: { approved: true }
   });
 };
 ```
 
-You can resume a suspended workflow using different triggers, including [human input](/docs/v1/workflows/human-in-the-loop), external events from your application, or time-based conditions.
+Passing the `step` object provides full type-safety for `resumeData`. Alternatively, you can pass a step ID for more flexibility when the ID comes from user input or a database.
 
-```typescript {10} showLineNumbers copy
-const handleResume = async () => {
-  const result = await run.resume({
-    step: 'step-1',
-    resumeData: { approved: true }
-  });
-};
+```typescript showLineNumbers copy
+const result = await run.resume({
+  step: "step-1",
+  resumeData: { approved: true }
+});
+```
+
+If only one step is suspended, you can omit the step argument entirely and Mastra will resume the last suspended step in the workflow.
+
+When resuming with only a `runId`, create a run instance first using `createRunAsync()`.
 
+```typescript showLineNumbers copy
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRunAsync({ runId: "123" });
+
+const stream = run.resume({
+  resumeData: { approved: true }
+});
+```
+
+You can call `resume()` from anywhere in your application, including HTTP endpoints, event handlers, in response to [human input](/docs/v1/workflows/human-in-the-loop), or timers.
+
+```typescript showLineNumbers copy
 const midnight = new Date();
 midnight.setUTCHours(24, 0, 0, 0);
-setTimeout(handleResume, midnight.getTime() - Date.now());
+
+setTimeout(async () => {
+  await run.resume({
+    step: "step-1",
+    resumeData: { approved: true }
+  });
+}, midnight.getTime() - Date.now());
 ```
 
+## Accessing suspend data with `suspendData`
+When a step is suspended, you may want to access the data that was provided to `suspend()` when the step is later resumed. Use the `suspendData` parameter in your step's execute function to access this data.
+
+```typescript {22-25,29-30} title="src/mastra/workflows/user-approval.ts" showLineNumbers copy
+const approvalStep = createStep({
+  id: "user-approval",
+  inputSchema: z.object({
+    requestId: z.string()
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean()
+  }),
+  suspendSchema: z.object({
+    reason: z.string(),
+    requestDetails: z.string()
+  }),
+  outputSchema: z.object({
+    result: z.string()
+  }),
+  execute: async ({ inputData, resumeData, suspend, suspendData }) => {
+    const { requestId } = inputData;
+    const { approved } = resumeData ?? {};
+    
+    // On first execution, suspend with context
+    if (!approved) {
+      return await suspend({
+        reason: "User approval required",
+        requestDetails: `Request ${requestId} pending review`
+      });
+    }
+    
+    // On resume, access the original suspend data
+    const suspendReason = suspendData?.reason || "Unknown";
+    const details = suspendData?.requestDetails || "No details";
+    
+    return {
+      result: `${details} - ${suspendReason} - Decision: ${approved ? 'Approved' : 'Rejected'}`
+    };
+  }
+});
+```
+
+The `suspendData` parameter is automatically populated when a step is resumed and contains the exact data that was passed to the `suspend()` function during the original suspension. This allows you to maintain context about why the workflow was suspended and use that information during the resume process.
+
 ## Identifying suspended executions
 
 When a workflow is suspended, it restarts from the step where it paused. You can check the workflow's `status` to confirm it's suspended, and use `suspended` to identify the paused step or [nested workflow](/docs/v1/workflows/overview#workflows-as-steps).
 
 ```typescript {11} showLineNumbers copy
 const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRunAsync();
+const run = await workflow.createRun();
 
 const result = await run.start({
   inputData: {
@@ -139,3 +206,5 @@ Sleep and event methods can be used to pause execution at the workflow level, wh
 
 - [Control Flow](/docs/v1/workflows/control-flow)
 - [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)
+- [Snapshots](/docs/v1/workflows/snapshots)
+- [Time Travel](/docs/v1/workflows/time-travel)

package/.docs/raw/workflows/time-travel.mdx

@@ -0,0 +1,313 @@
+---
+title: "Time Travel | Workflows"
+description: "Re-execute workflow steps from a specific point using time travel debugging in Mastra"
+---
+
+# Time Travel
+
+Time travel allows you to re-execute 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.
+You can also use time travel to execute a workflow that has not been run yet, starting from any specific step.
+
+## How time travel works
+
+When you call `timeTravel()` on a workflow run:
+
+1. The workflow loads the existing snapshot from storage (if available)
+2. Step results before the target step are reconstructed from the snapshot or provided context
+3. Execution begins from the specified step with the provided or reconstructed input data
+4. The workflow continues to completion from that point forward
+
+Time travel requires storage to be configured since it relies on persisted workflow snapshots.
+
+## Basic usage
+
+Use `run.timeTravel()` to re-execute a workflow from a specific step:
+
+```typescript showLineNumbers copy
+import { mastra } from "./mastra";
+
+const workflow = mastra.getWorkflow("myWorkflow");
+const run = await workflow.createRun();
+
+const result = await run.timeTravel({
+  step: "step2",
+  inputData: { previousStepResult: "custom value" },
+});
+```
+
+## Specifying the target step
+
+You can specify the target step using either a step reference or a step ID:
+
+### Using step reference
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: step2,
+  inputData: { value: 10 },
+});
+```
+
+### Using step ID
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: "step2",
+  inputData: { value: 10 },
+});
+```
+
+### Nested workflow steps
+
+For steps inside nested workflows, use dot notation, an array of step IDS or an array of step references:
+
+```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 },
+});
+
+// Using array of step references
+const result = await run.timeTravel({
+  step: [nestedWorkflow, step3],
+  inputData: { value: 10 },
+});
+```
+
+## Providing execution context
+
+You can provide context to specify the state of previous steps when time traveling:
+
+```typescript {3-13} 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(),
+    },
+  },
+});
+```
+
+The context object contains step results keyed by step ID. Each step result includes:
+
+- `status`: The step's execution status (`success`, `failed`, `suspended`)
+- `payload`: The input data passed to the step
+- `output`: The step's output data (for successful steps)
+- `startedAt`: Timestamp when the step started
+- `endedAt`: Timestamp when the step ended (for completed steps)
+- `suspendPayload`: Data passed to `suspend()` (for suspended steps)
+- `resumePayload`: Data passed to `resume()` (for resumed steps)
+
+## Re-running failed workflows
+
+Time travel is particularly useful for debugging and recovering from failed workflow executions:
+
+```typescript showLineNumbers copy
+const workflow = mastra.getWorkflow("myWorkflow");
+const run = await workflow.createRun();
+
+// Initial run fails at step2
+const failedResult = await run.start({
+  inputData: { value: 1 },
+});
+
+if (failedResult.status === "failed") {
+  // Re-run from step2 with corrected input
+  const recoveredResult = await run.timeTravel({
+    step: "step2",
+    inputData: { step1Result: 5 }, // Provide corrected input
+  });
+}
+```
+
+## Time travel with suspended workflows
+
+You can time travel to resume a suspended workflow from an earlier step:
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+// Start workflow - suspends at promptAgent step
+const initialResult = await run.start({
+  inputData: { input: "test" },
+});
+
+if (initialResult.status === "suspended") {
+  // Time travel back to an earlier step with resume data
+  const result = await run.timeTravel({
+    step: "getUserInput",
+    resumeData: {
+      userInput: "corrected input",
+    },
+  });
+}
+```
+
+## Streaming time travel results
+
+Use `timeTravelStream()` to receive streaming events during time travel execution:
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const output = run.timeTravelStream({
+  step: "step2",
+  inputData: { value: 10 },
+});
+
+// Access the stream
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload);
+}
+
+// Get final result
+const result = await output.result;
+```
+
+## Time travel with initial state
+
+You can provide initial state when time traveling to set workflow-level state:
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: "step2",
+  inputData: { value: 10 },
+  initialState: {
+    counter: 5,
+    metadata: { source: "time-travel" },
+  },
+});
+```
+
+## Error handling
+
+Time travel throws errors in specific situations:
+
+### Running workflow
+
+You cannot time travel to a workflow that is currently running:
+
+```typescript showLineNumbers copy
+try {
+  await run.timeTravel({ step: "step2" });
+} catch (error) {
+  // "This workflow run is still running, cannot time travel"
+}
+```
+
+### Invalid step ID
+
+Time travel throws if the target step doesn't exist in the workflow:
+
+```typescript showLineNumbers copy
+try {
+  await run.timeTravel({ step: "nonExistentStep" });
+} catch (error) {
+  // "Time travel target step not found in execution graph: 'nonExistentStep'. Verify the step id/path."
+}
+```
+
+### Invalid input data
+
+When `validateInputs` is enabled, time travel validates the input data against the step's schema:
+
+```typescript showLineNumbers copy
+try {
+  await run.timeTravel({
+    step: "step2",
+    inputData: { invalidField: "value" },
+  });
+} catch (error) {
+  // "Invalid inputData: \n- step1Result: Required"
+}
+```
+
+## Nested workflows context
+
+When time traveling into a nested workflow, you can provide context for both the parent and nested workflow steps:
+
+```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(),
+      },
+    },
+  },
+});
+```
+
+## Use cases
+
+### Debugging failed steps
+
+Re-run a failed step with the same or modified input to diagnose issues:
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: failedStepId,
+  context: originalContext, // Use context from the failed run
+});
+```
+
+### Testing step logic on new workflow run
+
+Test individual steps with specific inputs on a new workflow run, useful for testing a step logic without starting workflow execution from the beginning.
+
+```typescript showLineNumbers copy
+const result = await run.timeTravel({
+  step: "processData",
+  inputData: { testData: "specific test case" },
+});
+```
+
+### Recovering from transient failures
+
+Re-run steps that failed due to temporary issues (network errors, rate limits):
+
+```typescript showLineNumbers copy
+// After fixing the external service issue
+const result = await run.timeTravel({
+  step: "callExternalApi",
+  inputData: savedInputData,
+});
+```
+
+## Related
+
+- [Snapshots](/docs/v1/workflows/snapshots)
+- [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
+- [Error Handling](/docs/v1/workflows/error-handling)
+- [Control Flow](/docs/v1/workflows/control-flow)