@mastra/mcp-docs-server 0.13.46-alpha.0 → 0.13.46-alpha.1

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

@@ -124,6 +124,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 +160,6 @@ const step1 = createStep({
 
 ## Related
 
+- [Workflow state](/docs/workflows/workflow-state)
 - [Control flow](/docs/workflows/control-flow)
 - [Using agents and tools](/docs/workflows/agents-and-tools)

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

@@ -88,6 +88,24 @@ export const workflow = createWorkflow({
   ]}
 />
 
+## Running with initial state
+
+When starting a workflow run, you can pass `initialState` to set the starting values for the workflow's state:
+
+```typescript showLineNumbers copy
+const run = await workflow.createRunAsync();
+
+const result = await run.start({
+  inputData: { value: "hello" },
+  initialState: {
+    counter: 0,
+    items: [],
+  },
+});
+```
+
+The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](/docs/workflows/workflow-state) for more details.
+
 ## Workflow status
 
 A workflow's `status` indicates its current execution state. The possible values are:
@@ -118,4 +136,5 @@ A workflow's `status` indicates its current execution state. The possible values
 ## Related
 
 - [Step Class](./step)
+- [Workflow State](/docs/workflows/workflow-state)
 - [Control flow](/docs/workflows/control-flow)

package/.docs/raw/server-db/mastra-server.mdx

@@ -36,7 +36,7 @@ export const mastra = new Mastra({
   // ...
   server: {
     port: 3000, // Defaults to 4111
-    timeout: 10000, // Defaults to 30000 (30s)
+    timeout: 10000, // Defaults to 3 * 60 * 1000 (3 minutes)
   },
 });
 ```

package/.docs/raw/workflows/error-handling.mdx

@@ -208,4 +208,5 @@ for await (const chunk of stream.stream) {
 
 - [Control Flow](/docs/workflows/control-flow)
 - [Suspend & Resume](/docs/workflows/suspend-and-resume)
+- [Time Travel](/docs/workflows/time-travel)
 - [Human-in-the-loop](/docs/workflows/human-in-the-loop)

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/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/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.getActiveWorkflowRuns();
+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 `RuntimeContext`
 
 Use [RuntimeContext](/docs/server-db/runtime-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/getting-started/studio) to easily run workflows with differen
 
 For a closer look at workflows, see our [Workflow Guide](/guides/guide/ai-recruiter), which walks through the core concepts with a practical example.
 
+- [Workflow State](/docs/workflows/workflow-state)
 - [Control Flow](/docs/workflows/control-flow)
 - [Suspend & Resume](/docs/workflows/suspend-and-resume)
 - [Error Handling](/docs/workflows/error-handling)

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

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

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

@@ -140,3 +140,5 @@ Sleep and event methods can be used to pause execution at the workflow level, wh
 
 - [Control Flow](/docs/workflows/control-flow)
 - [Human-in-the-loop](/docs/workflows/human-in-the-loop)
+- [Snapshots](/docs/workflows/snapshots)
+- [Time Travel](/docs/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.createRunAsync();
+
+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.createRunAsync();
+
+// 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.createRunAsync();
+
+// 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.createRunAsync();
+
+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/workflows/snapshots)
+- [Suspend & Resume](/docs/workflows/suspend-and-resume)
+- [Error Handling](/docs/workflows/error-handling)
+- [Control Flow](/docs/workflows/control-flow)