@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

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

@@ -0,0 +1,133 @@
+---
+title: ".resumeWithEvent() Method | Mastra Docs"
+description: "Reference for the resumeWithEvent method that resumes suspended workflows using event data."
+---
+
+# resumeWithEvent()
+
+The `resumeWithEvent()` method resumes workflow execution by providing data for a specific event that the workflow is waiting for.
+
+## Syntax
+
+```typescript
+const run = workflow.createRun();
+
+// After the workflow has started and suspended at an event step
+await run.resumeWithEvent(eventName: string, data: any): Promise<WorkflowRunResult>
+```
+
+## Parameters
+
+| Parameter | Type   | Description                                                                                             |
+| --------- | ------ | ------------------------------------------------------------------------------------------------------- |
+| eventName | string | The name of the event to trigger. Must match an event defined in the workflow's `events` configuration. |
+| data      | any    | The event data to provide. Must conform to the schema defined for that event.                           |
+
+## Return Value
+
+Returns a Promise that resolves to a `WorkflowRunResult` object, containing:
+
+- `results`: The result status and output of each step in the workflow
+- `activePaths`: A map of active workflow paths and their states
+- `value`: The current state value of the workflow
+- Other workflow execution metadata
+
+## Description
+
+The `resumeWithEvent()` method is used to resume a workflow that has been suspended at an event step created by the `afterEvent()` method. When called, this method:
+
+1. Validates the provided event data against the schema defined for that event
+2. Loads the workflow snapshot from storage
+3. Updates the context with the event data in the `resumedEvent` field
+4. Resumes execution from the event step
+5. Continues workflow execution with the subsequent steps
+
+This method is part of Mastra's event-driven workflow capabilities, allowing you to create workflows that can respond to external events or user interactions.
+
+## Usage Notes
+
+- The workflow must be in a suspended state, specifically at the event step created by `afterEvent(eventName)`
+- The event data must conform to the schema defined for that event in the workflow configuration
+- The workflow will continue execution from the point it was suspended
+- If the workflow is not suspended or is suspended at a different step, this method may throw an error
+- The event data is made available to subsequent steps via `context.inputData.resumedEvent`
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Define and start a workflow
+const workflow = mastra.getWorkflow("approval-workflow");
+const run = workflow.createRun();
+
+// Start the workflow
+await run.start({ triggerData: { requestId: "req-123" } });
+
+// Later, when the approval event occurs:
+const result = await run.resumeWithEvent("approval", {
+  approved: true,
+  approverName: "John Doe",
+  comment: "Looks good to me!",
+});
+
+console.log(result.results);
+```
+
+### With Error Handling
+
+```typescript
+try {
+  const result = await run.resumeWithEvent("paymentReceived", {
+    amount: 100.5,
+    transactionId: "tx-456",
+    paymentMethod: "credit-card",
+  });
+
+  console.log("Workflow resumed successfully:", result.results);
+} catch (error) {
+  console.error("Failed to resume workflow with event:", error);
+  // Handle error - could be invalid event data, workflow not suspended, etc.
+}
+```
+
+### Monitoring and Auto-Resuming
+
+```typescript
+// Start a workflow
+const { start, watch, resumeWithEvent } = workflow.createRun();
+
+// Watch for suspended event steps
+watch(async ({ activePaths }) => {
+  const isApprovalEventSuspended =
+    activePaths.get("__approval_event")?.status === "suspended";
+  // Check if suspended at the approval event step
+  if (isApprovalEventSuspended) {
+    console.log("Workflow waiting for approval");
+
+    // In a real scenario, you would wait for the actual event
+    // Here we're simulating with a timeout
+    setTimeout(async () => {
+      try {
+        await resumeWithEvent("approval", {
+          approved: true,
+          approverName: "Auto Approver",
+        });
+      } catch (error) {
+        console.error("Failed to auto-resume workflow:", error);
+      }
+    }, 5000); // Wait 5 seconds before auto-approving
+  }
+});
+
+// Start the workflow
+await start({ triggerData: { requestId: "auto-123" } });
+```
+
+## Related
+
+- [Event-Driven Workflows](./events.mdx)
+- [afterEvent()](./afterEvent.mdx)
+- [Suspend and Resume](../../workflows/suspend-and-resume.mdx)
+- [resume()](./resume.mdx)
+- [watch()](./watch.mdx)

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

@@ -0,0 +1,207 @@
+---
+title: "Reference: Snapshots | Workflow State Persistence | Mastra Docs"
+description: "Technical reference on snapshots in Mastra - the serialized workflow state that enables suspend and resume functionality"
+---
+
+# Snapshots
+
+In Mastra, a snapshot is a serializable representation of a workflow's complete execution state at a specific point in time. Snapshots capture all the information needed to resume a workflow from exactly where it left off, including:
+
+- The current state of each step in the workflow
+- The outputs of completed steps
+- The execution path taken through the workflow
+- Any suspended steps and their metadata
+- The remaining retry attempts for each step
+- Additional contextual data needed to resume execution
+
+Snapshots are automatically created and managed by Mastra whenever a workflow is suspended, and are persisted to the configured storage system.
+
+## The Role of Snapshots in Suspend and Resume
+
+Snapshots are the key mechanism enabling Mastra's suspend and resume capabilities. When a workflow step calls `await suspend()`:
+
+1. The workflow execution is paused at that exact point
+2. The current state of the workflow is captured as a snapshot
+3. The snapshot is persisted to storage
+4. The workflow step is marked as "suspended" with a status of `'suspended'`
+5. Later, when `resume()` is called on the suspended step, the snapshot is retrieved
+6. The workflow execution resumes from exactly where it left off
+
+This mechanism provides a powerful way to implement human-in-the-loop workflows, handle rate limiting, wait for external resources, and implement complex branching workflows that may need to pause for extended periods.
+
+## Snapshot Anatomy
+
+A Mastra workflow snapshot consists of several key components:
+
+```typescript
+export interface WorkflowRunState {
+  // Core state info
+  value: Record<string, string>; // Current state machine value
+  context: {
+    // Workflow context
+    steps: Record<
+      string,
+      {
+        // Step execution results
+        status: "success" | "failed" | "suspended" | "waiting" | "skipped";
+        payload?: any; // Step-specific data
+        error?: string; // Error info if failed
+      }
+    >;
+    triggerData: Record<string, any>; // Initial trigger data
+    attempts: Record<string, number>; // Remaining retry attempts
+    inputData: Record<string, any>; // Initial input data
+  };
+
+  activePaths: Array<{
+    // Currently active execution paths
+    stepPath: string[];
+    stepId: string;
+    status: string;
+  }>;
+
+  // Metadata
+  runId: string; // Unique run identifier
+  timestamp: number; // Time snapshot was created
+
+  // For nested workflows and suspended steps
+  childStates?: Record<string, WorkflowRunState>; // Child workflow states
+  suspendedSteps?: Record<string, string>; // Mapping of suspended steps
+}
+```
+
+## How Snapshots Are Saved and Retrieved
+
+Mastra persists snapshots to the configured storage system. By default, snapshots are saved to a LibSQL database, but can be configured to use other storage providers like Upstash.
+The snapshots are stored in the `workflow_snapshots` table and identified uniquely by the `run_id` for the associated run when using libsql.
+Utilizing a persistence layer allows for the snapshots to be persisted across workflow runs, allowing for advanced human-in-the-loop functionality.
+
+Read more about [libsql storage](../storage/libsql.mdx) and [upstash storage](../storage/upstash.mdx) here.
+
+### Saving Snapshots
+
+When a workflow is suspended, Mastra automatically persists the workflow snapshot with these steps:
+
+1. The `suspend()` function in a step execution triggers the snapshot process
+2. The `WorkflowInstance.suspend()` method records the suspended machine
+3. `persistWorkflowSnapshot()` is called to save the current state
+4. The snapshot is serialized and stored in the configured database in the `workflow_snapshots` table
+5. The storage record includes the workflow name, run ID, and the serialized snapshot
+
+### Retrieving Snapshots
+
+When a workflow is resumed, Mastra retrieves the persisted snapshot with these steps:
+
+1. The `resume()` method is called with a specific step ID
+2. The snapshot is loaded from storage using `loadWorkflowSnapshot()`
+3. The snapshot is parsed and prepared for resumption
+4. The workflow execution is recreated with the snapshot state
+5. The suspended step is resumed, and execution continues
+
+## Storage Options for Snapshots
+
+Mastra provides multiple storage options for persisting snapshots.
+
+A `storage` instance is configured on the `Mastra` class, and is used to setup a snapshot persistence layer for all workflows registered on the `Mastra` instance.
+This means that storage is shared across all workflows registered with the same `Mastra` instance.
+
+### LibSQL (Default)
+
+The default storage option is LibSQL, a SQLite-compatible database:
+
+```typescript
+import { Mastra } from "@mastra/core/mastra";
+import { DefaultStorage } from "@mastra/core/storage/libsql";
+
+const mastra = new Mastra({
+  storage: new DefaultStorage({
+    config: {
+      url: "file:storage.db", // Local file-based database
+      // For production:
+      // url: process.env.DATABASE_URL,
+      // authToken: process.env.DATABASE_AUTH_TOKEN,
+    },
+  }),
+  workflows: {
+    weatherWorkflow,
+    travelWorkflow,
+  },
+});
+```
+
+### Upstash (Redis-Compatible)
+
+For serverless environments:
+
+```typescript
+import { Mastra } from "@mastra/core/mastra";
+import { UpstashStore } from "@mastra/upstash";
+
+const mastra = new Mastra({
+  storage: new UpstashStore({
+    url: process.env.UPSTASH_URL,
+    token: process.env.UPSTASH_TOKEN,
+  }),
+  workflows: {
+    weatherWorkflow,
+    travelWorkflow,
+  },
+});
+```
+
+## Best Practices for Working with Snapshots
+
+1. **Ensure Serializability**: Any data that needs to be included in the snapshot must be serializable (convertible to JSON).
+
+2. **Minimize Snapshot Size**: Avoid storing large data objects directly in the workflow context. Instead, store references to them (like IDs) and retrieve the data when needed.
+
+3. **Handle Resume Context Carefully**: When resuming a workflow, carefully consider what context to provide. This will be merged with the existing snapshot data.
+
+4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they are properly resumed.
+
+5. **Consider Storage Scaling**: For applications with many suspended workflows, ensure your storage solution is appropriately scaled.
+
+## Advanced Snapshot Patterns
+
+### Custom Snapshot Metadata
+
+When suspending a workflow, you can include custom metadata that can help when resuming:
+
+```typescript
+await suspend({
+  reason: "Waiting for customer approval",
+  requiredApprovers: ["manager", "finance"],
+  requestedBy: currentUser,
+  urgency: "high",
+  expires: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+});
+```
+
+This metadata is stored with the snapshot and available when resuming.
+
+### Conditional Resumption
+
+You can implement conditional logic based on the suspend payload when resuming:
+
+```typescript
+run.watch(async ({ activePaths }) => {
+  const isApprovalStepSuspended =
+    activePaths.get("approval")?.status === "suspended";
+  if (isApprovalStepSuspended) {
+    const payload = activePaths.get("approval")?.suspendPayload;
+    if (payload.urgency === "high" && currentUser.role === "manager") {
+      await resume({
+        stepId: "approval",
+        context: { approved: true, approver: currentUser.id },
+      });
+    }
+  }
+});
+```
+
+## Related
+
+- [Suspend Function Reference](./suspend.mdx)
+- [Resume Function Reference](./resume.mdx)
+- [Watch Function Reference](./watch.mdx)
+- [Suspend and Resume Guide](../../workflows/suspend-and-resume.mdx)

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

@@ -0,0 +1,84 @@
+---
+title: "Reference: start() | Running Workflows | Mastra Docs"
+description: "Documentation for the `start()` method in workflows, which begins execution of a workflow run."
+---
+
+# start()
+
+The start function begins execution of a workflow run. It processes all steps in the defined workflow order, handling parallel execution, branching logic, and step dependencies.
+
+## Usage
+
+```typescript copy showLineNumbers
+const { runId, start } = workflow.createRun();
+const result = await start({ 
+  triggerData: { inputValue: 42 } 
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "config",
+      type: "object",
+      description: "Configuration for starting the workflow run",
+      isOptional: true
+    }
+  ]}
+/>
+
+### config
+
+<PropertiesTable
+  content={[
+    {
+      name: "triggerData",
+      type: "Record<string, any>",
+      description: "Initial data that matches the workflow's triggerSchema",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "results",
+      type: "Record<string, any>",
+      description: "Combined output from all completed workflow steps"
+    },
+    {
+      name: "status",
+      type: "'completed' | 'error' | 'suspended'",
+      description: "Final status of the workflow run"
+    }
+  ]}
+/>
+
+## Error Handling
+
+The start function may throw several types of validation errors:
+
+```typescript copy showLineNumbers
+try {
+  const result = await start({ triggerData: data });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.log(error.type); // 'circular_dependency' | 'no_terminal_path' | 'unreachable_step'
+    console.log(error.details);
+  }
+}
+```
+
+## Related
+
+- [Example: Creating a Workflow](../../../examples/workflows/creating-a-workflow.mdx)
+- [Example: Suspend and Resume](../../../examples/workflows/suspend-and-resume.mdx)
+- [createRun Reference](./createRun.mdx)
+- [Workflow Class Reference](./workflow.mdx)
+- [Step Class Reference](./step-class.mdx)
+```

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

@@ -0,0 +1,100 @@
+---
+title: "Reference: Step | Building Workflows | Mastra Docs"
+description: Documentation for the Step class, which defines individual units of work within a workflow.
+---
+# Step
+
+The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
+
+## Usage
+
+```typescript
+const processOrder = new Step({
+  id: "processOrder",
+  inputSchema: z.object({
+    orderId: z.string(),
+    userId: z.string()
+  }),
+  outputSchema: z.object({
+    status: z.string(),
+    orderId: z.string()
+  }),
+  execute: async ({ context, runId }) => {
+    return {
+      status: "processed",
+      orderId: context.orderId
+    };
+  }
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the step",
+      required: true
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodSchema",
+      description: "Zod schema to validate input data before execution",
+      required: false
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodSchema",
+      description: "Zod schema to validate step output data",
+      required: false
+    },
+    {
+      name: "payload",
+      type: "Record<string, any>",
+      description: "Static data to be merged with variables",
+      required: false
+    },
+    {
+      name: "execute",
+      type: "(params: ExecuteParams) => Promise<any>",
+      description: "Async function containing step logic",
+      required: true
+    }
+  ]}
+/>
+
+### ExecuteParams
+
+<PropertiesTable
+  content={[
+    {
+      name: "context",
+      type: "StepContext",
+      description: "Access to workflow context and step results"
+    },
+    {
+      name: "runId",
+      type: "string",
+      description: "Unique identifier for current workflow run"
+    },
+    {
+      name: "suspend",
+      type: "() => Promise<void>",
+      description: "Function to suspend step execution"
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "Access to Mastra instance"
+    }
+  ]}
+/>
+
+## Related
+
+- [Workflow Reference](./workflow.mdx)
+- [Step Configuration Guide](../../workflows/steps.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```

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

@@ -0,0 +1,134 @@
+---
+title: "Reference: StepCondition | Building Workflows | Mastra"
+description: Documentation for the step condition class in workflows, which determines whether a step should execute based on the output of previous steps or trigger data.
+---
+
+# StepCondition
+
+Conditions determine whether a step should execute based on the output of previous steps or trigger data.
+
+## Usage
+
+There are three ways to specify conditions: function, query object, and simple path comparison.
+
+### 1. Function Condition
+```typescript copy showLineNumbers
+workflow.step(processOrder, {
+  when: async ({ context }) => {
+    const auth = context?.getStepResult<{status: string}>("auth");
+    return auth?.status === "authenticated";
+  }
+});
+```
+
+### 2. Query Object
+```typescript copy showLineNumbers
+workflow.step(processOrder, {
+  when: {
+    ref: { step: 'auth', path: 'status' },
+    query: { $eq: 'authenticated' }
+  }
+});
+```
+
+### 3. Simple Path Comparison
+```typescript copy showLineNumbers
+workflow.step(processOrder, {
+  when: {
+    "auth.status": "authenticated"
+  }
+});
+```
+
+Based on the type of condition, the workflow runner will try to match the condition to one of these types.
+
+1. Simple Path Condition (when there's a dot in the key)
+2. Base/Query Condition (when there's a 'ref' property)
+3. Function Condition (when it's an async function)
+
+## StepCondition
+
+<PropertiesTable
+  content={[
+    {
+      name: "ref",
+      type: "{ stepId: string | 'trigger'; path: string }",
+      description: "Reference to step output value. stepId can be a step ID or 'trigger' for initial data. path specifies location of value in step result",
+      isOptional: false
+    },
+    {
+      name: "query",
+      type: "Query<any>",
+      description: "MongoDB-style query using sift operators ($eq, $gt, etc)",
+      isOptional: false
+    }
+  ]}
+/>
+
+## Query
+
+The Query object provides MongoDB-style query operators for comparing values from previous steps or trigger data. It supports basic comparison operators like `$eq`, `$gt`, `$lt` as well as array operators like `$in` and `$nin`, and can be combined with and/or operators for complex conditions.
+
+This query syntax allows for readable conditional logic for determining whether a step should execute.
+
+<PropertiesTable
+  content={[
+    {
+      name: "$eq",
+      type: "any",
+      description: "Equal to value"
+    },
+    {
+      name: "$ne",
+      type: "any",
+      description: "Not equal to value"
+    },
+    {
+      name: "$gt",
+      type: "number",
+      description: "Greater than value"
+    },
+    {
+      name: "$gte",
+      type: "number",
+      description: "Greater than or equal to value"
+    },
+    {
+      name: "$lt",
+      type: "number",
+      description: "Less than value"
+    },
+    {
+      name: "$lte",
+      type: "number",
+      description: "Less than or equal to value"
+    },
+    {
+      name: "$in",
+      type: "any[]",
+      description: "Value exists in array"
+    },
+    {
+      name: "$nin",
+      type: "any[]",
+      description: "Value does not exist in array"
+    },
+    {
+      name: "and",
+      type: "StepCondition[]",
+      description: "Array of conditions that must all be true"
+    },
+    {
+      name: "or",
+      type: "StepCondition[]",
+      description: "Array of conditions where at least one must be true"
+    }
+  ]}
+/>
+
+## Related
+
+- [Step Options Reference](./step-options.mdx)
+- [Step Function Reference](./step-function.mdx)
+- [Control Flow Guide](../../workflows/control-flow.mdx)
+```