@mastra/core
Version:
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
113 lines (70 loc) • 4.31 kB
Markdown
# Workflow state reader
Workflow state reader helpers inspect the public `WorkflowState` returned by `workflow.getWorkflowRunById()`. Use them to recover suspended runs, inspect resume labels, and read step payloads or outputs without parsing raw workflow snapshots.
## Usage example
```typescript
import { createWorkflowStateReader } from '@mastra/core/workflows'
const state = await workflow.getWorkflowRunById('run-123')
if (state) {
const reader = createWorkflowStateReader(state)
const suspendedStep = reader.getSuspendedStep()
const labels = reader.getResumeLabels()
console.log(reader.getStatus())
console.log(reader.getStepOutput('extract-data'))
console.log(suspendedStep?.path)
console.log(labels.approve)
}
```
## Functions
### `createWorkflowStateReader(state)`
Creates a reader object with methods bound to one `WorkflowState`.
```typescript
const reader = createWorkflowStateReader(state)
const suspendedStep = reader.getSuspendedStep()
```
### `getWorkflowStepOutput(state, stepId)`
Returns the output for a step ID, including nested workflow dot paths such as `parent.child`. For `foreach` steps, returns one entry per iteration; suspended iterations can have `undefined` output entries.
```typescript
const output = getWorkflowStepOutput(state, 'extract-data')
```
### `getWorkflowStepPayload(state, stepId)`
Returns the payload that was passed to a step. For `foreach` steps, returns one entry per iteration.
```typescript
const payload = getWorkflowStepPayload(state, 'extract-data')
```
### `getWorkflowSuspendedStep(state)`
Returns the first suspended step from the workflow state. When multiple steps are suspended, ordering follows the order stored in `suspendedPaths`.
```typescript
const suspendedStep = getWorkflowSuspendedStep(state)
```
### `getWorkflowSuspendedSteps(state)`
Returns all suspended steps from the workflow state. Each result includes the top-level step ID, resume path, execution path, suspend payload, suspend output, and matching resume labels.
```typescript
const suspendedSteps = getWorkflowSuspendedSteps(state)
```
### `getWorkflowResumeLabel(state, label)`
Returns a resume label by name.
```typescript
const label = getWorkflowResumeLabel(state, 'approve')
```
### `getWorkflowResumeLabels(state)`
Returns all resume labels from the workflow state.
```typescript
const labels = getWorkflowResumeLabels(state)
```
## Reader methods
`createWorkflowStateReader(state)` returns the following methods:
**getStatus** (`() => WorkflowRunStatus`): Returns the workflow run status.
**getResult** (`() => WorkflowState["result"]`): Returns the terminal workflow result when it exists.
**getError** (`() => WorkflowState["error"]`): Returns the terminal workflow error when it exists.
**getStepOutput** (`(stepId: string) => any | Array<any | undefined> | undefined`): Returns the output for a step ID or nested workflow dot path.
**getStepPayload** (`(stepId: string) => any | Array<any | undefined> | undefined`): Returns the payload for a step ID or nested workflow dot path.
**getSuspendedStep** (`() => { stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> } | undefined`): Returns the first suspended step.
**getSuspendedSteps** (`() => Array<{ stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> }>`): Returns all suspended steps.
**getResumeLabel** (`(label: string) => { stepId: string; foreachIndex?: number } | undefined`): Returns a resume label by name.
**getResumeLabels** (`() => Record<string, { stepId: string; foreachIndex?: number }>`): Returns all resume labels.
## Notes
`requestContext` and `tracingContext` are only returned by `workflow.getWorkflowRunById()` when explicitly requested with `fields`.
## Related
- [Suspend & resume](https://mastra.ai/docs/workflows/suspend-and-resume)
- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
- [Workflow class](https://mastra.ai/reference/workflows/workflow)