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

package/.docs/raw/workflows/input-data-mapping.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Input Data Mapping | Workflows | Mastra Docs"
+title: "Input Data Mapping | Workflows"
 description: "Learn how to use workflow input mapping to create more dynamic data flows in your Mastra workflows."
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Workflows overview | Workflows | Mastra Docs"
+title: "Workflows overview | Workflows"
 description: "Workflows in Mastra help you orchestrate complex sequences of tasks with features like branching, parallel execution, resource suspension, and more."
 ---
 
@@ -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;
+    // Read from state
+    console.log(state.counter);
 
-    setState({
-      ...state,
-      processedItems: [...processedItems, "item-1", "item-2"],
-    });
+    // Update state for subsequent steps
+    setState({ ...state, counter: state.counter + 1 });
 
-    return {
-      formatted: message.toUpperCase(),
-    };
-  },
-});
-
-const step2 = createStep({
-  // ...
-  stateSchema: z.object({
-    metadata: z.object({
-      processedBy: z.string(),
-    }),
-  }),
-  execute: async ({ inputData, state }) => {
-    const { formatted } = inputData;
-    const { metadata } = state;
-
-    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).
@@ -253,14 +221,19 @@ const result = await run.stream({
   }
 });
 
-for await (const chunk of result.stream) {
+for await (const chunk of result.fullStream) {
   console.log(chunk);
 }
 ```
   </TabItem>
 </Tabs>
 
-## Workflow output
+
+### Workflow status types
+
+When running a workflow, its `status` can be `running`, `suspended`, `success`, or `failed`.
+
+### Workflow output
 
 The workflow output includes the full execution lifecycle, showing the input and output for each step. It also includes the status of each step, the overall workflow status, and the final result. This gives you clear insight into how data moved through the workflow, what each step produced, and how the workflow completed.
 
@@ -297,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.
@@ -330,3 +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

@@ -1,5 +1,5 @@
 ---
-title: "Snapshots | Workflows | Mastra Docs"
+title: "Snapshots | Workflows"
 description: "Learn how to save and resume workflow execution state with snapshots in Mastra"
 ---
 
@@ -266,5 +266,7 @@ if (result.status === "suspended") {
 
 ## Related
 
-- [Suspend and resume](/docs/v1/workflows/suspend-and-resume)
-- [Human in the loop example](/docs/v1/workflows/human-in-the-loop)
+- [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

@@ -1,289 +1,199 @@
 ---
-title: "Suspend & Resume | Workflows | Mastra Docs"
+title: "Suspend & Resume | Workflows"
 description: "Suspend and resume in Mastra workflows allows you to pause execution while waiting for external input or resources."
 ---
 
 # Suspend & Resume
 
-Workflows can be paused at any step, with their current state persisted as a [snapshot](./snapshots) in storage. Execution can then be resumed from this saved snapshot when ready. Persisting the snapshot ensures the workflow state is maintained across sessions, deployments, and server restarts, essential for workflows that may remain suspended while awaiting external input or resources.
+Workflows can be paused at any step to collect additional data, wait for API callbacks, throttle costly operations, or request [human-in-the-loop](/docs/v1/workflows/human-in-the-loop) input. When a workflow is suspended, its current execution state is saved as a snapshot. You can later resume the workflow from a [specific step ID](/docs/v1/workflows/snapshots#retrieving-snapshots), restoring the exact state captured in that snapshot. [Snapshots](/docs/v1/workflows/snapshots) are stored in your configured storage provider and across deployments and application restarts.
+## Pausing a workflow with `suspend()`
 
-Common scenarios for suspending workflows include:
+Use `suspend()` to pause workflow execution at a specific step. You can define a suspend condition in the step’s `execute` block using values from `resumeData`.
 
-- Waiting for human approval or input
-- Pausing until external API resources become available
-- Collecting additional data needed for later steps
-- Rate limiting or throttling expensive operations
-- Handling event-driven processes with external triggers
+- 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.
 
-> **New to suspend and resume?** Watch these official video tutorials:
->
-> - **[Mastering Human-in-the-Loop with Suspend & Resume](https://youtu.be/aORuNG8Tq_k)** - Learn how to suspend workflows and accept user inputs
-> - **[Building Multi-Turn Chat Interfaces with React](https://youtu.be/UMVm8YZwlxc)** - Implement multi-turn human-involved interactions with a React chat interface
+![Pausing a workflow with suspend()](/img/workflows/workflows-suspend.jpg)
 
-## Workflow status types
-
-When running a workflow, its `status` can be one of the following:
-
-- `running` - The workflow is currently running
-- `suspended` - The workflow is suspended
-- `success` - The workflow has completed
-- `failed` - The workflow has failed
-
-## Suspending a workflow with `suspend()`
-
-To pause execution at a specific step until user input is received, use the `⁠suspend` function to temporarily halt the workflow, allowing it to resume only when the necessary data is provided.
-
-![Suspending a workflow with suspend()](/img/workflows/workflows-suspend-resume-suspend.jpg)
-
-```typescript {16} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {9-11,16-18} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 const step1 = createStep({
   id: "step-1",
   inputSchema: z.object({
-    input: z.string(),
+    userEmail: z.string()
   }),
   outputSchema: z.object({
-    output: z.string(),
+    output: z.string()
   }),
   resumeSchema: z.object({
-    city: z.string(),
+    approved: z.boolean()
   }),
-  execute: async ({ resumeData, suspend }) => {
-    const { city } = resumeData ?? {};
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { userEmail } = inputData;
+    const { approved } = resumeData ?? {};
 
-    if (!city) {
+    if (!approved) {
       return await suspend({});
     }
 
-    return { output: "" };
-  },
+    return {
+      output: `Email sent to ${userEmail}`
+    };
+  }
 });
 
 export const testWorkflow = createWorkflow({
-  // ...
+  id: "test-workflow",
+  inputSchema: z.object({
+    userEmail: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  })
 })
   .then(step1)
   .commit();
 ```
 
-> For more details, check out the [Suspend & Resume documentation](/docs/v1/workflows/suspend-and-resume).
+## Restarting a workflow with `resume()`
 
-### Identifying suspended steps
+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.
 
-To resume a suspended workflow, inspect the `suspended` array in the result to determine which step needs input:
+![Restarting a workflow with resume()](/img/workflows/workflows-resume.jpg)
 
-```typescript {15} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
+```typescript showLineNumbers copy
+import { step1 } from "./workflows/test-workflow";
 
-const run = await mastra.getWorkflow("testWorkflow").createRun();
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRun();
 
-const result = await run.start({
+await run.start({
   inputData: {
-    city: "London",
-  },
+    userEmail: "alex@example.com"
+  }
 });
 
-console.log(JSON.stringify(result, null, 2));
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    step: result.suspended[0],
-    resumeData: {
-      city: "Berlin",
-    },
+const handleResume = async () => {
+  const result = await run.resume({
+    step: step1,
+    resumeData: { approved: true }
   });
-}
+};
 ```
 
-In this case, the logic resumes the first step listed in the `suspended` array. A `step` can also be defined using it's `id`, for example: 'step-1'.
+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.
 
-```json
-{
-  "status": "suspended",
-  "steps": {
-    // ...
-    "step-1": {
-      // ...
-      "status": "suspended"
-    }
-  },
-  "suspended": [["step-1"]]
-}
+```typescript showLineNumbers copy
+const result = await run.resume({
+  step: "step-1",
+  resumeData: { approved: true }
+});
 ```
 
-> See [Workflow Output](./overview#workflow-output) for more details.
+If only one step is suspended, you can omit the step argument entirely and Mastra will resume the last suspended step in the workflow.
 
-## Providing user feedback with suspend
+When resuming with only a `runId`, create a run instance first using `createRunAsync()`.
 
-When a workflow is suspended, feedback can be surfaced to the user through the `suspendSchema`. Include a reason in the `suspend` payload to explain why the workflow paused.
+```typescript showLineNumbers copy
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRunAsync({ runId: "123" });
 
-```typescript {13,23} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
+const stream = run.resume({
+  resumeData: { approved: true }
+});
+```
 
-const step1 = createStep({
-  id: "step-1",
+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(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({
-    value: z.string(),
+    requestId: z.string()
   }),
   resumeSchema: z.object({
-    confirm: z.boolean(),
+    approved: z.boolean()
   }),
   suspendSchema: z.object({
     reason: z.string(),
+    requestDetails: z.string()
   }),
   outputSchema: z.object({
-    value: z.string(),
+    result: z.string()
   }),
-  execute: async ({ resumeData, suspend }) => {
-    const { confirm } = resumeData ?? {};
-
-    if (!confirm) {
+  execute: async ({ inputData, resumeData, suspend, suspendData }) => {
+    const { requestId } = inputData;
+    const { approved } = resumeData ?? {};
+    
+    // On first execution, suspend with context
+    if (!approved) {
       return await suspend({
-        reason: "Confirm to continue",
+        reason: "User approval required",
+        requestDetails: `Request ${requestId} pending review`
       });
     }
-
-    return { value: "" };
-  },
-});
-
-export const testWorkflow = createWorkflow({
-  // ...
-})
-  .then(step1)
-  .commit();
-```
-
-In this case, the reason provided explains that the user must confirm to continue.
-
-```json
-{
-  "step-1": {
-    // ...
-    "status": "suspended",
-    "suspendPayload": {
-      "reason": "Confirm to continue"
-    }
+    
+    // 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'}`
+    };
   }
-}
+});
 ```
 
-> See [Workflow Output](./overview#workflow-output) for more details.
-
-## Resuming a workflow with `resume()`
+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.
 
-A workflow can be resumed by calling `resume` and providing the required `resumeData`. You can either explicitly specify which step to resume from, or when exactly one step is suspended, omit the `step` parameter and the workflow will automatically resume that step.
+## Identifying suspended executions
 
-```typescript {16-18} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { mastra } from "./mastra";
+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).
 
-const run = await mastra.getWorkflow("testWorkflow").createRun();
+```typescript {11} showLineNumbers copy
+const workflow = mastra.getWorkflow("testWorkflow");
+const run = await workflow.createRun();
 
 const result = await run.start({
   inputData: {
-    city: "London",
-  },
+    userEmail: "alex@example.com"
+  }
 });
 
-console.log(JSON.stringify(result, null, 2));
-
 if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    step: "step-1",
-    resumeData: {
-      city: "Berlin",
-    },
+  console.log(result.suspended[0]);
+  await run.resume({
+    step: result.suspended[0],
+    resumeData: { approved: true }
   });
-
-  console.log(JSON.stringify(resumedResult, null, 2));
 }
 ```
 
-You can also omit the `step` parameter when exactly one step is suspended:
-
-```typescript {5} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const resumedResult = await run.resume({
-  resumeData: {
-    city: "Berlin",
-  },
-  // step parameter omitted - automatically resumes the single suspended step
-});
-```
-
-You can pass `requestContext` as an argument to both the `start` and `resume` commands.
-
-```typescript title="src/mastra/workflows/test-workflow.ts"
-import { RequestContext } from "@mastra/core/request-context";
+**Example output**
 
-const requestContext = new RequestContext();
+The `suspended` array contains the IDs of any suspended workflows and steps from the run. These can be passed to the `step` parameter when calling `resume()` to target and resume the suspended execution path.
 
-const result = await run.start({
-  step: "step-1",
-  inputData: {
-    city: "London",
-  },
-  requestContext,
-});
-
-const resumedResult = await run.resume({
-  step: "step-1",
-  resumeData: {
-    city: "New York",
-  },
-  requestContext,
-});
-```
-
-> See [Request Context](/docs/v1/server-db/request-context) for more information.
-
-### Resuming nested workflows
-
-To resume a suspended nested workflow pass the workflow instance to the `step` parameter of the `resume` function.
-
-```typescript {33-34} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const dowhileWorkflow = createWorkflow({
-  id: "dowhile-workflow",
-  inputSchema: z.object({ value: z.number() }),
-  outputSchema: z.object({ value: z.number() }),
-})
-  .dountil(
-    createWorkflow({
-      id: "simple-resume-workflow",
-      inputSchema: z.object({ value: z.number() }),
-      outputSchema: z.object({ value: z.number() }),
-      steps: [incrementStep, resumeStep],
-    })
-      .then(incrementStep)
-      .then(resumeStep)
-      .commit(),
-    async ({ inputData }) => inputData.value >= 10,
-  )
-  .then(
-    createStep({
-      id: "final",
-      inputSchema: z.object({ value: z.number() }),
-      outputSchema: z.object({ value: z.number() }),
-      execute: async ({ inputData }) => ({ value: inputData.value }),
-    }),
-  )
-  .commit();
-
-const run = await dowhileWorkflow.createRun();
-const result = await run.start({ inputData: { value: 0 } });
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    resumeData: { value: 2 },
-    step: ["simple-resume-workflow", "resume"],
-  });
-
-  console.log(JSON.stringify(resumedResult, null, 2));
-}
+```typescript
+[ 'nested-workflow', 'step-1' ]
 ```
 
 ## Sleep & Events
 
-Workflows can also pause execution for timed delays or external events. These methods set the workflow status to `waiting` rather than `suspended`, and are useful for polling, delayed retries, or event-driven processes.
+Sleep and event methods can be used to pause execution at the workflow level, which sets the status to `waiting`. By comparison, `suspend()` pauses execution within a specific step and sets the status to `suspended`.
 
 **Available methods:**
 
@@ -291,3 +201,10 @@ Workflows can also pause execution for timed delays or external events. These me
 - [`.sleepUntil()`](/reference/v1/workflows/workflow-methods/sleepUntil) : Pause until a specific date
 - [`.waitForEvent()`](/reference/v1/workflows/workflow-methods/waitForEvent): Pause until an external event is received
 - [`.sendEvent()`](/reference/v1/workflows/workflow-methods/sendEvent) : Send an event to resume a waiting workflow
+
+## Related
+
+- [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)