npm - @mastra/core - Versions diffs - 1.6.0 → 1.7.0-alpha.0 - Mend

@mastra/core 1.6.0 → 1.7.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (452) hide show

package/dist/docs/references/docs-workflows-suspend-and-resume.md DELETED Viewed

@@ -1,205 +0,0 @@
-# Suspend & Resume
-Workflows can be paused at any step to collect additional data, wait for API callbacks, throttle costly operations, or request [human-in-the-loop](https://mastra.ai/docs/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](https://mastra.ai/docs/workflows/snapshots), restoring the exact state captured in that snapshot. [Snapshots](https://mastra.ai/docs/workflows/snapshots) are stored in your configured storage provider and persist across deployments and application restarts.
-## Pausing a workflow with `suspend()`
-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`.
-- 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.
-![Pausing a workflow with suspend()](/assets/images/workflows-suspend-4540783670f918109ac35beaf4db914b.jpg)
-```typescript
-const step1 = createStep({
-  id: "step-1",
-  inputSchema: z.object({
-    userEmail: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  }),
-  resumeSchema: z.object({
-    approved: z.boolean()
-  }),
-  execute: async ({ inputData, resumeData, suspend }) => {
-    const { userEmail } = inputData;
-    const { approved } = resumeData ?? {};
-    if (!approved) {
-      return await suspend({});
-    }
-    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();
-```
-## Restarting a workflow with `resume()`
-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.
-![Restarting a workflow with resume()](/assets/images/workflows-resume-1e54b4d0c753ff79571f6d6b05109a60.jpg)
-```typescript
-import { step1 } from "./workflows/test-workflow";
-const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRun();
-await run.start({
-  inputData: {
-    userEmail: "alex@example.com"
-  }
-});
-const handleResume = async () => {
-  const result = await run.resume({
-    step: step1,
-    resumeData: { approved: true }
-  });
-};
-```
-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.
-```typescript
-const result = await run.resume({
-  step: "step-1",
-  resumeData: { approved: true }
-});
-```
-If only one step is suspended, you can omit the step argument entirely and Mastra will resume the last suspended step in the workflow.
-When resuming with only a `runId`, create a run instance first using `createRun()`.
-```typescript
-const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRun({ runId: "123" });
-const stream = run.resume({
-  resumeData: { approved: true }
-});
-```
-You can call `resume()` from anywhere in your application, including HTTP endpoints, event handlers, in response to [human input](https://mastra.ai/docs/workflows/human-in-the-loop), or timers.
-```typescript
-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
-const approvalStep = createStep({
-  id: "user-approval",
-  inputSchema: z.object({
-    requestId: z.string()
-  }),
-  resumeSchema: z.object({
-    approved: z.boolean()
-  }),
-  suspendSchema: z.object({
-    reason: z.string(),
-    requestDetails: z.string()
-  }),
-  outputSchema: z.object({
-    result: z.string()
-  }),
-  execute: async ({ inputData, resumeData, suspend, suspendData }) => {
-    const { requestId } = inputData;
-    const { approved } = resumeData ?? {};
-    // On first execution, suspend with context
-    if (!approved) {
-      return await suspend({
-        reason: "User approval required",
-        requestDetails: `Request ${requestId} pending review`
-      });
-    }
-    // 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'}`
-    };
-  }
-});
-```
-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.
-## Identifying suspended executions
-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](https://mastra.ai/docs/workflows/overview).
-```typescript
-const workflow = mastra.getWorkflow("testWorkflow");
-const run = await workflow.createRun();
-const result = await run.start({
-  inputData: {
-    userEmail: "alex@example.com"
-  }
-});
-if (result.status === "suspended") {
-  console.log(result.suspended[0]);
-  await run.resume({
-    step: result.suspended[0],
-    resumeData: { approved: true }
-  });
-}
-```
-**Example output**
-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.
-```typescript
-[ 'nested-workflow', 'step-1' ]
-```
-## Sleep
-Sleep 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:**
-- [`.sleep()`](https://mastra.ai/reference/workflows/workflow-methods/sleep): Pause for a specified number of milliseconds
-- [`.sleepUntil()`](https://mastra.ai/reference/workflows/workflow-methods/sleepUntil): Pause until a specific date
-## Related
-- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
-- [Human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop)
-- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
-- [Time Travel](https://mastra.ai/docs/workflows/time-travel)

package/dist/docs/references/docs-workflows-time-travel.md DELETED Viewed

@@ -1,309 +0,0 @@
-# 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
-import { mastra } from "./mastra";
-const workflow = mastra.getWorkflow("myWorkflow");
-const run = await workflow.createRun();
-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
-const result = await run.timeTravel({
-  step: step2,
-  inputData: { value: 10 },
-});
-```
-### Using step ID
-```typescript
-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
-// 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
-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
-const workflow = mastra.getWorkflow("myWorkflow");
-const run = await workflow.createRun();
-// 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
-const run = await workflow.createRun();
-// 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
-const run = await workflow.createRun();
-const stream = run.timeTravelStream({
-  step: "step2",
-  inputData: { value: 10 },
-});
-for await (const event of stream.fullStream) {
-  console.log(event.type, event.payload);
-}
-const result = await stream.result;
-if (result.status === "success") {
-  console.log(result.result);
-}
-```
-## Time travel with initial state
-You can provide initial state when time traveling to set workflow-level state:
-```typescript
-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
-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
-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
-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
-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
-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
-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
-// After fixing the external service issue
-const result = await run.timeTravel({
-  step: "callExternalApi",
-  inputData: savedInputData,
-});
-```
-## Related
-- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
-- [Error Handling](https://mastra.ai/docs/workflows/error-handling)
-- [Control Flow](https://mastra.ai/docs/workflows/control-flow)

package/dist/docs/references/docs-workflows-workflow-state.md DELETED Viewed

@@ -1,181 +0,0 @@
-# Workflow State
-Workflow state lets you share values across steps without passing them through every step's inputSchema and outputSchema. This is useful for tracking progress, accumulating results, or sharing configuration across the entire workflow.
-## State vs step input/output
-It's important to understand the difference between **state** and **step input/output**:
-- **Step input/output**: Data flows sequentially between steps. Each step receives the previous step's output as its `inputData`, and returns an output for the next step.
-- **State**: A shared store that all steps can read and update via `state` and `setState`. State persists across the entire workflow run, including suspend/resume cycles.
-```typescript
-const step1 = createStep({
-  id: "step-1",
-  inputSchema: z.object({ workflowInput: z.string() }),
-  outputSchema: z.object({ step1Output: z.string() }),
-  stateSchema: z.object({ sharedCounter: z.number() }),
-  execute: async ({ inputData, state, setState }) => {
-    // inputData comes from workflow input or previous step's output
-    console.log(inputData.workflowInput);
-    // state is the shared workflow state
-    console.log(state.sharedCounter);
-    // Update state for subsequent steps
-    await setState({ sharedCounter: state.sharedCounter + 1 });
-    // Return output that flows to next step's inputData
-    return { step1Output: "processed" };
-  },
-});
-```
-## Defining state schemas
-Define a `stateSchema` on both the workflow and individual steps. The workflow's stateSchema is the master schema containing all possible state values, while each step declares only the subset it needs:
-```typescript
-const step1 = createStep({
-  stateSchema: z.object({
-    processedItems: z.array(z.string()),
-  }),
-  execute: async ({ inputData, state, setState }) => {
-    const { message } = inputData;
-    const { processedItems } = state;
-    await setState({
-      processedItems: [...processedItems, "item-1", "item-2"],
-    });
-    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}`,
-    };
-  },
-});
-export const testWorkflow = createWorkflow({
-  stateSchema: z.object({
-    processedItems: z.array(z.string()),
-    metadata: z.object({
-      processedBy: z.string(),
-    }),
-  }),
-})
-  .then(step1)
-  .then(step2)
-  .commit();
-```
-## Setting initial state
-Pass `initialState` when starting a workflow run to set the starting values:
-```typescript
-const run = await workflow.createRun();
-const result = await run.start({
-  inputData: { message: "Hello" },
-  initialState: {
-    processedItems: [],
-    metadata: { processedBy: "system" },
-  },
-});
-```
-The `initialState` object should match the structure defined in the workflow's `stateSchema`.
-## State persistence across suspend/resume
-State automatically persists across suspend and resume cycles. When a workflow suspends and later resumes, all state updates made before the suspension are preserved:
-```typescript
-const step1 = createStep({
-  id: "step-1",
-  inputSchema: z.object({}),
-  outputSchema: z.object({}),
-  stateSchema: z.object({ count: z.number(), items: z.array(z.string()) }),
-  resumeSchema: z.object({ proceed: z.boolean() }),
-  execute: async ({ state, setState, suspend, resumeData }) => {
-    if (!resumeData) {
-      // First run: update state and suspend
-      await setState({ count: state.count + 1, items: [...state.items, "item-1"] });
-      await suspend({});
-      return {};
-    }
-    // After resume: state changes are preserved (count: 1, items: ["item-1"])
-    return {};
-  },
-});
-```
-## State in nested workflows
-When using nested workflows, state propagates from parent to child. Changes made by the parent workflow before calling a nested workflow are visible to steps inside the nested workflow:
-```typescript
-const nestedStep = createStep({
-  id: "nested-step",
-  inputSchema: z.object({}),
-  outputSchema: z.object({ result: z.string() }),
-  stateSchema: z.object({ sharedValue: z.string() }),
-  execute: async ({ state }) => {
-    // Receives state modified by parent workflow
-    return { result: `Received: ${state.sharedValue}` };
-  },
-});
-const nestedWorkflow = createWorkflow({
-  id: "nested-workflow",
-  inputSchema: z.object({}),
-  outputSchema: z.object({ result: z.string() }),
-  stateSchema: z.object({ sharedValue: z.string() }),
-})
-  .then(nestedStep)
-  .commit();
-const parentStep = createStep({
-  id: "parent-step",
-  inputSchema: z.object({}),
-  outputSchema: z.object({}),
-  stateSchema: z.object({ sharedValue: z.string() }),
-  execute: async ({ state, setState }) => {
-    // Modify state before nested workflow runs
-    await setState({ sharedValue: "modified-by-parent" });
-    return {};
-  },
-});
-const parentWorkflow = createWorkflow({
-  id: "parent-workflow",
-  inputSchema: z.object({}),
-  outputSchema: z.object({ result: z.string() }),
-  stateSchema: z.object({ sharedValue: z.string() }),
-})
-  .then(parentStep)
-  .then(nestedWorkflow)
-  .commit();
-```
-## Related
-- [Workflows overview](https://mastra.ai/docs/workflows/overview)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
-- [Step Class](https://mastra.ai/reference/workflows/step)
-- [Workflow Class](https://mastra.ai/reference/workflows/workflow)