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

package/.docs/docs/workflows/overview.md

@@ -0,0 +1,370 @@
+# Workflows overview
+
+Workflows let you define complex sequences of tasks using clear, structured steps rather than relying on the reasoning of a single agent. They give you full control over how tasks are broken down, how data moves between them, and what gets executed when. Workflows run using the built-in execution engine by default, or can be deployed to [workflow runners](https://mastra.ai/docs/deployment/workflow-runners) like Inngest for managed infrastructure.
+
+![Workflows overview](/assets/images/workflows-overview-4509c840549a01ff7386daa5101bda26.jpg)
+
+## When to use workflows
+
+Use workflows for tasks that are clearly defined upfront and involve multiple steps with a specific execution order. They give you fine-grained control over how data flows and transforms between steps, and which primitives are called at each stage.
+
+> **Watch an introduction:** An introduction to workflows, and how they compare to agents [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
+
+## Core principles
+
+Mastra workflows operate using these principles:
+
+- Defining **steps** with `createStep`, specifying input/output schemas and business logic.
+- Composing **steps** with `createWorkflow` to define the execution flow.
+- Running **workflows** to execute the entire sequence, with built-in support for suspension, resumption, and streaming results.
+
+## Creating a workflow step
+
+Steps are the building blocks of workflows. Create a step using `createStep()` with `inputSchema` and `outputSchema` to define the data it accepts and returns.
+
+The `execute` function defines what the step does. Use it to call functions in your codebase, external APIs, agents, or tools.
+
+```typescript
+import { createStep } from '@mastra/core/workflows'
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: z.object({
+    message: z.string(),
+  }),
+  outputSchema: z.object({
+    formatted: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    const { message } = inputData
+
+    return {
+      formatted: message.toUpperCase(),
+    }
+  },
+})
+```
+
+> **Info:** Visit [Step Class](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
+
+### Using agents and tools
+
+Workflow steps can also call registered agents or import and execute tools directly, visit the [Using Tools](https://mastra.ai/docs/agents/using-tools) page for more information.
+
+## Creating a workflow
+
+Create a workflow using `createWorkflow()` with `inputSchema` and `outputSchema` to define the data it accepts and returns. Add steps using `.then()` and complete the workflow with `.commit()`.
+
+```typescript
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const step1 = createStep({...});
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    output: z.string()
+  })
+})
+  .then(step1)
+  .commit();
+```
+
+> **Info:** Visit [Workflow Class](https://mastra.ai/reference/workflows/workflow) for a full list of configuration options.
+
+### Understanding control flow
+
+Workflows can be composed using a number of different methods. The method you choose determines how each step's schema should be structured. Visit the [Control Flow](https://mastra.ai/docs/workflows/control-flow) page for more information.
+
+## Workflow state
+
+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
+const step1 = createStep({
+  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 }) => {
+    // Read from state
+    console.log(state.counter)
+
+    // Update state for subsequent steps
+    setState({ ...state, counter: state.counter + 1 })
+
+    return { formatted: inputData.message.toUpperCase() }
+  },
+})
+```
+
+> **Info:** Visit [Workflow State](https://mastra.ai/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](https://mastra.ai/docs/workflows/control-flow).
+
+```typescript
+const step1 = createStep({...});
+const step2 = createStep({...});
+
+const childWorkflow = createWorkflow({
+  id: "child-workflow",
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    emphasized: z.string()
+  })
+})
+  .then(step1)
+  .then(step2)
+  .commit();
+
+export const testWorkflow = createWorkflow({
+  id: "test-workflow",
+  inputSchema: z.object({
+    message: z.string()
+  }),
+  outputSchema: z.object({
+    emphasized: z.string()
+  })
+})
+  .then(childWorkflow)
+  .commit();
+```
+
+### Cloning a workflow
+
+Clone a workflow using `cloneWorkflow()` when you want to reuse its logic but track it separately under a new ID. Each clone runs independently and appears as a distinct workflow in logs and observability tools.
+
+```typescript
+import { cloneWorkflow } from "@mastra/core/workflows";
+
+const step1 = createStep({...});
+
+const parentWorkflow = createWorkflow({...})
+const clonedWorkflow = cloneWorkflow(parentWorkflow, { id: "cloned-workflow" });
+
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
+  .then(clonedWorkflow)
+  .commit();
+```
+
+## Registering a workflow
+
+Register your workflow in the Mastra instance to make it available throughout your application. Once registered, it can be called from agents or tools and has access to shared resources such as logging and observability features:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { testWorkflow } from './workflows/test-workflow'
+
+export const mastra = new Mastra({
+  workflows: { testWorkflow },
+})
+```
+
+## Referencing a workflow
+
+You can run workflows from agents, tools, the Mastra Client, or the command line. Get a reference by calling `.getWorkflow()` on your `mastra` or `mastraClient` instance, depending on your setup:
+
+```typescript
+const testWorkflow = mastra.getWorkflow('testWorkflow')
+```
+
+> **Info:** `mastra.getWorkflow()` is preferred over a direct import for two reasons:
+>
+> 1. It provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores)
+> 2. It provides full TypeScript type inference for workflow input and output schemas
+>
+> **Note:** Use `getWorkflow()` with the workflow's **registration key** (the key used when adding it to Mastra). While `getWorkflowById()` is available for retrieving workflows by their `id` property, it does not provide the same level of type inference.
+
+## Running workflows
+
+Workflows can be run in two modes: start waits for all steps to complete before returning, and stream emits events during execution. Choose the approach that fits your use case: start when you only need the final result, and stream when you want to monitor progress or trigger actions as steps complete.
+
+**Start**:
+
+Create a workflow run instance using `createRun()`, then call `.start()` with `inputData` matching the workflow's `inputSchema`. The workflow executes all steps and returns the final result.
+
+```typescript
+const run = await testWorkflow.createRun()
+
+const result = await run.start({
+  inputData: {
+    message: 'Hello world',
+  },
+})
+
+if (result.status === 'success') {
+  console.log(result.result)
+}
+```
+
+**Stream**:
+
+Create a workflow run instance using `.createRun()`, then call `.stream()` with `inputData` matching the workflow's `inputSchema`. Iterate over `fullStream` to track progress, then await `result` to get the final workflow result.
+
+```typescript
+const run = await testWorkflow.createRun()
+
+const stream = run.stream({
+  inputData: {
+    message: 'Hello world',
+  },
+})
+
+for await (const chunk of stream.fullStream) {
+  console.log(chunk)
+}
+
+// Get the final result (same type as run.start())
+const result = await stream.result
+
+if (result.status === 'success') {
+  console.log(result.result)
+}
+```
+
+### Workflow result type
+
+Both `run.start()` and `stream.result` return a discriminated union based on the `status` property, which can be `success`, `failed`, `suspended`, `tripwire`, or `paused`. You can always safely access `result.status`, `result.input`, `result.steps`, and optionally `result.state` regardless of the status.
+
+Additionally, depending on the status, different properties are available:
+
+| Status      | Unique properties             | Description                                              |
+| ----------- | ----------------------------- | -------------------------------------------------------- |
+| `success`   | `result`                      | The workflow's output data                               |
+| `failed`    | `error`                       | The error that caused the failure                        |
+| `tripwire`  | `tripwire`                    | Contains `reason`, `retry?`, `metadata?`, `processorId?` |
+| `suspended` | `suspendPayload`, `suspended` | Suspension data and array of suspended step paths        |
+| `paused`    | _(none)_                      | Only common properties available                         |
+
+To access status-specific properties, check the `status` first:
+
+```typescript
+const result = await run.start({ inputData: { message: 'Hello world' } })
+
+if (result.status === 'success') {
+  console.log(result.result) // Only available when status is "success"
+} else if (result.status === 'failed') {
+  console.log(result.error.message)
+} else if (result.status === 'suspended') {
+  console.log(result.suspendPayload)
+}
+```
+
+### Workflow output
+
+Here's an example of a successful workflow result, showing the `input`, `steps`, and `result` properties:
+
+```json
+{
+  "status": "success",
+  "steps": {
+    "step-1": {
+      "status": "success",
+      "payload": {
+        "message": "Hello world"
+      },
+      "output": {
+        "formatted": "HELLO WORLD"
+      }
+    },
+    "step-2": {
+      "status": "success",
+      "payload": {
+        "formatted": "HELLO WORLD"
+      },
+      "output": {
+        "emphasized": "HELLO WORLD!!!"
+      }
+    }
+  },
+  "input": {
+    "message": "Hello world"
+  },
+  "result": {
+    "emphasized": "HELLO WORLD!!!"
+  }
+}
+```
+
+## 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
+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
+const run = await workflow.createRun()
+
+const result = await run.start({ inputData: { value: 'initial data' } })
+
+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
+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](https://mastra.ai/docs/server/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
+
+```typescript
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+const step1 = createStep({
+  execute: async ({ requestContext }) => {
+    const userTier = requestContext.get('user-tier') as UserTier['user-tier']
+
+    const maxResults = userTier === 'enterprise' ? 1000 : 50
+
+    return { maxResults }
+  },
+})
+```
+
+> **Info:** Visit [Request Context](https://mastra.ai/docs/server/request-context) for more information.
+
+> **Tip:** For type-safe request context schema validation, see [Schema Validation](https://mastra.ai/docs/server/request-context).
+
+## Testing with Studio
+
+Use [Studio](https://mastra.ai/docs/getting-started/studio) to easily run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
+
+## Related
+
+For a closer look at workflows, see our [Workflow Guide](https://mastra.ai/guides/guide/ai-recruiter), which walks through the core concepts with a practical example.
+
+- [Workflow State](https://mastra.ai/docs/workflows/workflow-state)
+- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
+- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Error Handling](https://mastra.ai/docs/workflows/error-handling)

package/.docs/docs/workflows/snapshots.md

@@ -0,0 +1,238 @@
+# 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
+
+Each snapshot includes the `runId`, input, step status (`success`, `suspended`, etc.), any suspend and resume payloads, and the final output. This ensures full context is available when resuming execution.
+
+```json
+{
+  "runId": "34904c14-e79e-4a12-9804-9655d4616c50",
+  "status": "success",
+  "value": {},
+  "context": {
+    "input": {
+      "value": 100,
+      "user": "Michael",
+      "requiredApprovers": ["manager", "finance"]
+    },
+    "approval-step": {
+      "payload": {
+        "value": 100,
+        "user": "Michael",
+        "requiredApprovers": ["manager", "finance"]
+      },
+      "startedAt": 1758027577955,
+      "status": "success",
+      "suspendPayload": {
+        "message": "Workflow suspended",
+        "requestedBy": "Michael",
+        "approvers": ["manager", "finance"]
+      },
+      "suspendedAt": 1758027578065,
+      "resumePayload": { "confirm": true, "approver": "manager" },
+      "resumedAt": 1758027578517,
+      "output": { "value": 100, "approved": true },
+      "endedAt": 1758027578634
+    }
+  },
+  "activePaths": [],
+  "serializedStepGraph": [
+    {
+      "type": "step",
+      "step": {
+        "id": "approval-step",
+        "description": "Accepts a value, waits for confirmation"
+      }
+    }
+  ],
+  "suspendedPaths": {},
+  "waitingPaths": {},
+  "result": { "value": 100, "approved": true },
+  "requestContext": {},
+  "timestamp": 1758027578740
+}
+```
+
+## How snapshots are saved and retrieved
+
+Snapshots are saved to the configured storage system. By default, they use libSQL, but you can configure Upstash or PostgreSQL instead. Each snapshot is saved in the `workflow_snapshots` table and identified by the workflow's `runId`.
+
+Read more about:
+
+- [libSQL Storage](https://mastra.ai/reference/storage/libsql)
+- [Upstash Storage](https://mastra.ai/reference/storage/upstash)
+- [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
+
+### 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
+
+```typescript
+const storage = mastra.getStorage()
+const workflowStore = await storage?.getStore('workflows')
+
+const snapshot = await workflowStore?.loadWorkflowSnapshot({
+  runId: '<run-id>',
+  workflowName: '<workflow-id>',
+})
+
+console.log(snapshot)
+```
+
+## Storage options for snapshots
+
+Snapshots are persisted using a `storage` instance configured on the `Mastra` class. This storage layer is shared across all workflows registered to that instance. Mastra supports multiple storage options for flexibility in different environments.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { approvalWorkflow } from './workflows'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: ':memory:',
+  }),
+  workflows: { approvalWorkflow },
+})
+```
+
+- [libSQL Storage](https://mastra.ai/reference/storage/libsql)
+- [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
+- [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
+- [Upstash Storage](https://mastra.ai/reference/storage/upstash)
+- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
+- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
+- [More storage providers](https://mastra.ai/docs/memory/storage)
+
+## Best practices
+
+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.
+
+## Custom snapshot metadata
+
+You can attach custom metadata when suspending a workflow by defining a `suspendSchema`. This metadata is stored in the snapshot and made available when the workflow is resumed.
+
+```typescript
+import { createWorkflow, createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+const approvalStep = createStep({
+  id: 'approval-step',
+  description: 'Accepts a value, waits for confirmation',
+  inputSchema: z.object({
+    value: z.number(),
+    user: z.string(),
+    requiredApprovers: z.array(z.string()),
+  }),
+  suspendSchema: z.object({
+    message: z.string(),
+    requestedBy: z.string(),
+    approvers: z.array(z.string()),
+  }),
+  resumeSchema: z.object({
+    confirm: z.boolean(),
+    approver: z.string(),
+  }),
+  outputSchema: z.object({
+    value: z.number(),
+    approved: z.boolean(),
+  }),
+  execute: async ({ inputData, resumeData, suspend }) => {
+    const { value, user, requiredApprovers } = inputData
+    const { confirm } = resumeData ?? {}
+
+    if (!confirm) {
+      return await suspend({
+        message: 'Workflow suspended',
+        requestedBy: user,
+        approvers: [...requiredApprovers],
+      })
+    }
+
+    return {
+      value,
+      approved: confirm,
+    }
+  },
+})
+```
+
+### Providing resume data
+
+Use `resumeData` to pass structured input when resuming a suspended step. It must match the step’s `resumeSchema`.
+
+```typescript
+const workflow = mastra.getWorkflow('approvalWorkflow')
+
+const run = await workflow.createRun()
+
+const result = await run.start({
+  inputData: {
+    value: 100,
+    user: 'Michael',
+    requiredApprovers: ['manager', 'finance'],
+  },
+})
+
+if (result.status === 'suspended') {
+  const resumedResult = await run.resume({
+    step: 'approval-step',
+    resumeData: {
+      confirm: true,
+      approver: 'manager',
+    },
+  })
+}
+```
+
+## Related
+
+- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
+- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
+- [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)