@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/raw/reference/legacyWorkflows/events.mdx

@@ -1,305 +0,0 @@
----
-title: "Event-Driven Workflows (Legacy) | Mastra Docs"
-description: "Learn how to create event-driven workflows using afterEvent and resumeWithEvent methods in Mastra."
----
-
-# Event-Driven Workflows
-
-Mastra provides built-in support for event-driven workflows through the `afterEvent` and `resumeWithEvent` methods. These methods allow you to create workflows that pause execution while waiting for specific events to occur, then resume with the event data when it's available.
-
-## Overview
-
-Event-driven workflows are useful for scenarios where:
-
-- You need to wait for external systems to complete processing
-- User approval or input is required at specific points
-- Asynchronous operations need to be coordinated
-- Long-running processes need to break up execution across different services
-
-## Defining Events
-
-Before using event-driven methods, you must define the events your workflow will listen for in the workflow configuration:
-
-```typescript
-import { LegacyWorkflow } from "@mastra/core/workflows/legacy";
-import { z } from "zod";
-
-const workflow = new LegacyWorkflow({
-  name: "approval-workflow",
-  triggerSchema: z.object({ requestId: z.string() }),
-  events: {
-    // Define events with their validation schemas
-    approvalReceived: {
-      schema: z.object({
-        approved: z.boolean(),
-        approverName: z.string(),
-        comment: z.string().optional(),
-      }),
-    },
-    documentUploaded: {
-      schema: z.object({
-        documentId: z.string(),
-        documentType: z.enum(["invoice", "receipt", "contract"]),
-        metadata: z.record(z.string()).optional(),
-      }),
-    },
-  },
-});
-```
-
-Each event must have a name and a schema that defines the structure of data expected when the event occurs.
-
-## afterEvent()
-
-The `afterEvent` method creates a suspension point in your workflow that automatically waits for a specific event.
-
-### Syntax
-
-```typescript
-workflow.afterEvent(eventName: string): LegacyWorkflow
-```
-
-### Parameters
-
-- `eventName`: The name of the event to wait for (must be defined in the workflow's `events` configuration)
-
-### Return Value
-
-Returns the workflow instance for method chaining.
-
-### How It Works
-
-When `afterEvent` is called, Mastra:
-
-1. Creates a special step with ID `__eventName_event`
-2. Configures this step to automatically suspend workflow execution
-3. Sets up the continuation point after the event is received
-
-### Usage Example
-
-```typescript
-workflow
-  .step(initialProcessStep)
-  .afterEvent("approvalReceived") // Workflow suspends here
-  .step(postApprovalStep) // This runs after event is received
-  .then(finalStep)
-  .commit();
-```
-
-## resumeWithEvent()
-
-The `resumeWithEvent` method resumes a suspended workflow by providing data for a specific event.
-
-### Syntax
-
-```typescript
-run.resumeWithEvent(eventName: string, data: any): Promise<LegacyWorkflowRunResult>
-```
-
-### Parameters
-
-- `eventName`: The name of the event being triggered
-- `data`: The event data (must conform to the schema defined for this event)
-
-### Return Value
-
-Returns a Promise that resolves to the workflow execution results after resumption.
-
-### How It Works
-
-When `resumeWithEvent` is called, Mastra:
-
-1. Validates the event data against the schema defined for that event
-2. Loads the workflow snapshot
-3. Updates the context with the event data
-4. Resumes execution from the event step
-5. Continues workflow execution with the subsequent steps
-
-### Usage Example
-
-```typescript
-// Create a workflow run
-const run = workflow.createRun();
-
-// Start the workflow
-await run.start({ triggerData: { requestId: "req-123" } });
-
-// Later, when the event occurs:
-const result = await run.resumeWithEvent("approvalReceived", {
-  approved: true,
-  approverName: "John Doe",
-  comment: "Looks good to me!",
-});
-
-console.log(result.results);
-```
-
-## Accessing Event Data
-
-When a workflow is resumed with event data, that data is available in the step context as `context.inputData.resumedEvent`:
-
-```typescript
-const processApprovalStep = new LegacyStep({
-  id: "processApproval",
-  execute: async ({ context }) => {
-    // Access the event data
-    const eventData = context.inputData.resumedEvent;
-
-    return {
-      processingResult: `Processed approval from ${eventData.approverName}`,
-      wasApproved: eventData.approved,
-    };
-  },
-});
-```
-
-## Multiple Events
-
-You can create workflows that wait for multiple different events at various points:
-
-```typescript
-workflow
-  .step(createRequest)
-  .afterEvent("approvalReceived")
-  .step(processApproval)
-  .afterEvent("documentUploaded")
-  .step(processDocument)
-  .commit();
-```
-
-When resuming a workflow with multiple event suspension points, you need to provide the correct event name and data for the current suspension point.
-
-## Practical Example
-
-This example shows a complete workflow that requires both approval and document upload:
-
-```typescript
-import { LegacyWorkflow, LegacyStep } from "@mastra/core/workflows/legacy";
-import { z } from "zod";
-
-// Define steps
-const createRequest = new LegacyStep({
-  id: "createRequest",
-  execute: async () => ({ requestId: `req-${Date.now()}` }),
-});
-
-const processApproval = new LegacyStep({
-  id: "processApproval",
-  execute: async ({ context }) => {
-    const approvalData = context.inputData.resumedEvent;
-    return {
-      approved: approvalData.approved,
-      approver: approvalData.approverName,
-    };
-  },
-});
-
-const processDocument = new LegacyStep({
-  id: "processDocument",
-  execute: async ({ context }) => {
-    const documentData = context.inputData.resumedEvent;
-    return {
-      documentId: documentData.documentId,
-      processed: true,
-      type: documentData.documentType,
-    };
-  },
-});
-
-const finalizeRequest = new LegacyStep({
-  id: "finalizeRequest",
-  execute: async ({ context }) => {
-    const requestId = context.steps.createRequest.output.requestId;
-    const approved = context.steps.processApproval.output.approved;
-    const documentId = context.steps.processDocument.output.documentId;
-
-    return {
-      finalized: true,
-      summary: `Request ${requestId} was ${approved ? "approved" : "rejected"} with document ${documentId}`,
-    };
-  },
-});
-
-// Create workflow
-const requestWorkflow = new LegacyWorkflow({
-  name: "document-request-workflow",
-  events: {
-    approvalReceived: {
-      schema: z.object({
-        approved: z.boolean(),
-        approverName: z.string(),
-      }),
-    },
-    documentUploaded: {
-      schema: z.object({
-        documentId: z.string(),
-        documentType: z.enum(["invoice", "receipt", "contract"]),
-      }),
-    },
-  },
-});
-
-// Build workflow
-requestWorkflow
-  .step(createRequest)
-  .afterEvent("approvalReceived")
-  .step(processApproval)
-  .afterEvent("documentUploaded")
-  .step(processDocument)
-  .then(finalizeRequest)
-  .commit();
-
-// Export workflow
-export { requestWorkflow };
-```
-
-### Running the Example Workflow
-
-```typescript
-import { requestWorkflow } from "./workflows";
-import { mastra } from "./mastra";
-
-async function runWorkflow() {
-  // Get the workflow
-  const workflow = mastra.legacy_getWorkflow("document-request-workflow");
-  const run = workflow.createRun();
-
-  // Start the workflow
-  const initialResult = await run.start();
-  console.log("Workflow started:", initialResult.results);
-
-  // Simulate receiving approval
-  const afterApprovalResult = await run.resumeWithEvent("approvalReceived", {
-    approved: true,
-    approverName: "Jane Smith",
-  });
-  console.log("After approval:", afterApprovalResult.results);
-
-  // Simulate document upload
-  const finalResult = await run.resumeWithEvent("documentUploaded", {
-    documentId: "doc-456",
-    documentType: "invoice",
-  });
-  console.log("Final result:", finalResult.results);
-}
-
-runWorkflow().catch(console.error);
-```
-
-## Best Practices
-
-1. **Define Clear Event Schemas**: Use Zod to create precise schemas for event data validation
-2. **Use Descriptive Event Names**: Choose event names that clearly communicate their purpose
-3. **Handle Missing Events**: Ensure your workflow can handle cases where events don't occur or time out
-4. **Include Monitoring**: Use the `watch` method to monitor suspended workflows waiting for events
-5. **Consider Timeouts**: Implement timeout mechanisms for events that may never occur
-6. **Document Events**: Clearly document the events your workflow depends on for other developers
-
-## Related
-
-- [Suspend and Resume in Workflows](../../docs/workflows-legacy/suspend-and-resume.mdx)
-- [Workflow Class Reference](./workflow.mdx)
-- [Resume Method Reference](./resume.mdx)
-- [Watch Method Reference](./watch.mdx)
-- [After Event Reference](./afterEvent.mdx)
-- [Resume With Event Reference](./resumeWithEvent.mdx)

package/.docs/raw/reference/legacyWorkflows/execute.mdx

@@ -1,110 +0,0 @@
----
-title: "Reference: Workflow.execute() | Workflows (Legacy) | Mastra Docs"
-description: "Documentation for the `.execute()` method in Mastra workflows, which runs workflow steps and returns results."
----
-
-# Workflow.execute()
-
-Executes a workflow with the provided trigger data and returns the results. The workflow must be committed before execution.
-
-## Usage Example
-
-```typescript
-const workflow = new LegacyWorkflow({
-  name: "my-workflow",
-  triggerSchema: z.object({
-    inputValue: z.number(),
-  }),
-});
-
-workflow.step(stepOne).then(stepTwo).commit();
-
-const result = await workflow.execute({
-  triggerData: { inputValue: 42 },
-});
-```
-
-## Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: "options",
-      type: "ExecuteOptions",
-      description: "Options for workflow execution",
-      isOptional: true,
-      properties: [
-        {
-          name: "triggerData",
-          type: "TriggerSchema",
-          description: "Input data matching the workflow's trigger schema",
-          isOptional: false,
-        },
-        {
-          name: "runId",
-          type: "string",
-          description: "Optional ID to track this execution run",
-          isOptional: true,
-        },
-      ],
-    },
-  ]}
-/>
-
-## Returns
-
-<PropertiesTable
-  content={[
-    {
-      name: "WorkflowResult",
-      type: "object",
-      description: "Results from workflow execution",
-      properties: [
-        {
-          name: "runId",
-          type: "string",
-          description: "Unique identifier for this execution run",
-        },
-        {
-          name: "results",
-          type: "Record<string, StepResult>",
-          description: "Results from each completed step",
-        },
-        {
-          name: "status",
-          type: "WorkflowStatus",
-          description: "Final status of the workflow run",
-        },
-      ],
-    },
-  ]}
-/>
-
-## Additional Examples
-
-Execute with run ID:
-
-```typescript
-const result = await workflow.execute({
-  runId: "custom-run-id",
-  triggerData: { inputValue: 42 },
-});
-```
-
-Handle execution results:
-
-```typescript
-const { runId, results, status } = await workflow.execute({
-  triggerData: { inputValue: 42 },
-});
-
-if (status === "COMPLETED") {
-  console.log("Step results:", results);
-}
-```
-
-### Related
-
-- [Workflow.createRun()](./createRun.mdx)
-- [Workflow.commit()](./commit.mdx)
-- [Workflow.start()](./start.mdx)

package/.docs/raw/reference/legacyWorkflows/if.mdx

@@ -1,108 +0,0 @@
----
-title: "Reference: Workflow.if() | Conditional Branching | Mastra Docs"
-description: "Documentation for the `.if()` method in Mastra workflows, which creates conditional branches based on specified conditions."
----
-
-# Workflow.if()
-
-> Experimental
-
-The `.if()` method creates a conditional branch in the workflow, allowing steps to execute only when a specified condition is true. This enables dynamic workflow paths based on the results of previous steps.
-
-## Usage
-
-```typescript copy showLineNumbers
-workflow
-  .step(startStep)
-  .if(async ({ context }) => {
-    const value = context.getStepResult<{ value: number }>("start")?.value;
-    return value < 10; // If true, execute the "if" branch
-  })
-  .then(ifBranchStep)
-  .else()
-  .then(elseBranchStep)
-  .commit();
-```
-
-## Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: "condition",
-      type: "Function | ReferenceCondition",
-      description:
-        "A function or reference condition that determines whether to execute the 'if' branch",
-      isOptional: false,
-    },
-  ]}
-/>
-
-## Condition Types
-
-### Function Condition
-
-You can use a function that returns a boolean:
-
-```typescript
-workflow
-  .step(startStep)
-  .if(async ({ context }) => {
-    const result = context.getStepResult<{ status: string }>("start");
-    return result?.status === "success"; // Execute "if" branch when status is "success"
-  })
-  .then(successStep)
-  .else()
-  .then(failureStep);
-```
-
-### Reference Condition
-
-You can use a reference-based condition with comparison operators:
-
-```typescript
-workflow
-  .step(startStep)
-  .if({
-    ref: { step: startStep, path: "value" },
-    query: { $lt: 10 }, // Execute "if" branch when value is less than 10
-  })
-  .then(ifBranchStep)
-  .else()
-  .then(elseBranchStep);
-```
-
-## Returns
-
-<PropertiesTable
-  content={[
-    {
-      name: "workflow",
-      type: "LegacyWorkflow",
-      description: "The workflow instance for method chaining",
-    },
-  ]}
-/>
-
-## Error Handling
-
-The `if` method requires a previous step to be defined. If you try to use it without a preceding step, an error will be thrown:
-
-```typescript
-try {
-  // This will throw an error
-  workflow
-    .if(async ({ context }) => true)
-    .then(someStep)
-    .commit();
-} catch (error) {
-  console.error(error); // "Condition requires a step to be executed after"
-}
-```
-
-## Related
-
-- [else Reference](./else.mdx)
-- [then Reference](./then.mdx)
-- [Control Flow Guide](../../docs/workflows-legacy/control-flow.mdx)
-- [Step Condition Reference](./step-condition.mdx)

package/.docs/raw/reference/legacyWorkflows/resume.mdx

@@ -1,158 +0,0 @@
----
-title: "Reference: run.resume() | Running Workflows (Legacy) | Mastra Docs"
-description: Documentation for the `.resume()` method in workflows, which continues execution of a suspended workflow step.
----
-
-# run.resume()
-
-The `.resume()` method continues execution of a suspended workflow step, optionally providing new context data that can be accessed by the step on the inputData property.
-
-## Usage
-
-```typescript copy showLineNumbers
-await run.resume({
-  runId: "abc-123",
-  stepId: "stepTwo",
-  context: {
-    secondValue: 100,
-  },
-});
-```
-
-## Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: "config",
-      type: "object",
-      description: "Configuration for resuming the workflow",
-      isOptional: false,
-    },
-  ]}
-/>
-
-### config
-
-<PropertiesTable
-  content={[
-    {
-      name: "runId",
-      type: "string",
-      description: "Unique identifier of the workflow run to resume",
-      isOptional: false,
-    },
-    {
-      name: "stepId",
-      type: "string",
-      description: "ID of the suspended step to resume",
-      isOptional: false,
-    },
-    {
-      name: "context",
-      type: "Record<string, any>",
-      description:
-        "New context data to inject into the step's inputData property",
-      isOptional: true,
-    },
-  ]}
-/>
-
-## Returns
-
-<PropertiesTable
-  content={[
-    {
-      name: "Promise<LegacyWorkflowResult>",
-      type: "object",
-      description: "Result of the resumed workflow execution",
-    },
-  ]}
-/>
-
-## Async/Await Flow
-
-When a workflow is resumed, execution continues from the point immediately after the `suspend()` call in the step's execution function. This creates a natural flow in your code:
-
-```typescript
-// Step definition with suspend point
-const reviewStep = new LegacyStep({
-  id: "review",
-  execute: async ({ context, suspend }) => {
-    // First part of execution
-    const initialAnalysis = analyzeData(context.inputData.data);
-
-    if (initialAnalysis.needsReview) {
-      // Suspend execution here
-      await suspend({ analysis: initialAnalysis });
-
-      // This code runs after resume() is called
-      // context.inputData now contains any data provided during resume
-      return {
-        reviewedData: enhanceWithFeedback(
-          initialAnalysis,
-          context.inputData.feedback,
-        ),
-      };
-    }
-
-    return { reviewedData: initialAnalysis };
-  },
-});
-
-const { runId, resume, start } = workflow.createRun();
-
-await start({
-  inputData: {
-    data: "some data",
-  },
-});
-
-// Later, resume the workflow
-const result = await resume({
-  runId: "workflow-123",
-  stepId: "review",
-  context: {
-    // This data will be available in `context.inputData`
-    feedback: "Looks good, but improve section 3",
-  },
-});
-```
-
-### Execution Flow
-
-1. The workflow runs until it hits `await suspend()` in the `review` step
-2. The workflow state is persisted and execution pauses
-3. Later, `run.resume()` is called with new context data
-4. Execution continues from the point after `suspend()` in the `review` step
-5. The new context data (`feedback`) is available to the step on the `inputData` property
-6. The step completes and returns its result
-7. The workflow continues with subsequent steps
-
-## Error Handling
-
-The resume function may throw several types of errors:
-
-```typescript
-try {
-  await run.resume({
-    runId,
-    stepId: "stepTwo",
-    context: newData,
-  });
-} catch (error) {
-  if (error.message === "No snapshot found for workflow run") {
-    // Handle missing workflow state
-  }
-  if (error.message === "Failed to parse workflow snapshot") {
-    // Handle corrupted workflow state
-  }
-}
-```
-
-## Related
-
-- [Suspend and Resume](../../docs/workflows-legacy/suspend-and-resume.mdx)
-- [`suspend` Reference](./suspend.mdx)
-- [`watch` Reference](./watch.mdx)
-- [Workflow Class Reference](./workflow.mdx)