@mastra/mcp-docs-server 1.0.0-beta.5 → 1.0.0-beta.7

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 (163) hide show
  1. package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +9 -9
  2. package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +67 -67
  3. package/.docs/organized/changelogs/%40mastra%2Fastra.md +10 -10
  4. package/.docs/organized/changelogs/%40mastra%2Fchroma.md +12 -12
  5. package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +57 -57
  6. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +110 -110
  7. package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +57 -57
  8. package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +57 -57
  9. package/.docs/organized/changelogs/%40mastra%2Fcodemod.md +6 -0
  10. package/.docs/organized/changelogs/%40mastra%2Fconvex.md +60 -0
  11. package/.docs/organized/changelogs/%40mastra%2Fcore.md +358 -358
  12. package/.docs/organized/changelogs/%40mastra%2Fcouchbase.md +11 -11
  13. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +24 -24
  14. package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +12 -12
  15. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +79 -79
  16. package/.docs/organized/changelogs/%40mastra%2Fduckdb.md +42 -0
  17. package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +57 -57
  18. package/.docs/organized/changelogs/%40mastra%2Felasticsearch.md +61 -0
  19. package/.docs/organized/changelogs/%40mastra%2Fevals.md +12 -12
  20. package/.docs/organized/changelogs/%40mastra%2Flance.md +57 -57
  21. package/.docs/organized/changelogs/%40mastra%2Flibsql.md +55 -55
  22. package/.docs/organized/changelogs/%40mastra%2Floggers.md +12 -12
  23. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +17 -17
  24. package/.docs/organized/changelogs/%40mastra%2Fmcp.md +125 -125
  25. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +36 -36
  26. package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +57 -57
  27. package/.docs/organized/changelogs/%40mastra%2Fmssql.md +57 -57
  28. package/.docs/organized/changelogs/%40mastra%2Fopensearch.md +10 -10
  29. package/.docs/organized/changelogs/%40mastra%2Fpg.md +59 -59
  30. package/.docs/organized/changelogs/%40mastra%2Fpinecone.md +10 -10
  31. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +77 -77
  32. package/.docs/organized/changelogs/%40mastra%2Fqdrant.md +10 -10
  33. package/.docs/organized/changelogs/%40mastra%2Frag.md +43 -43
  34. package/.docs/organized/changelogs/%40mastra%2Freact.md +16 -0
  35. package/.docs/organized/changelogs/%40mastra%2Fs3vectors.md +9 -0
  36. package/.docs/organized/changelogs/%40mastra%2Fschema-compat.md +6 -0
  37. package/.docs/organized/changelogs/%40mastra%2Fserver.md +113 -113
  38. package/.docs/organized/changelogs/%40mastra%2Fturbopuffer.md +10 -10
  39. package/.docs/organized/changelogs/%40mastra%2Fupstash.md +57 -57
  40. package/.docs/organized/changelogs/%40mastra%2Fvectorize.md +10 -10
  41. package/.docs/organized/changelogs/%40mastra%2Fvoice-google.md +19 -19
  42. package/.docs/organized/changelogs/create-mastra.md +15 -15
  43. package/.docs/organized/changelogs/mastra.md +30 -30
  44. package/.docs/organized/code-examples/agui.md +1 -0
  45. package/.docs/organized/code-examples/ai-elements.md +1 -1
  46. package/.docs/organized/code-examples/ai-sdk-useChat.md +1 -1
  47. package/.docs/organized/code-examples/ai-sdk-v5.md +2 -1
  48. package/.docs/organized/code-examples/assistant-ui.md +1 -1
  49. package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md +1 -1
  50. package/.docs/organized/code-examples/bird-checker-with-nextjs.md +1 -1
  51. package/.docs/organized/code-examples/crypto-chatbot.md +1 -1
  52. package/.docs/organized/code-examples/mcp-server-adapters.md +721 -0
  53. package/.docs/organized/code-examples/server-app-access.md +342 -0
  54. package/.docs/organized/code-examples/server-express-adapter.md +87 -0
  55. package/.docs/organized/code-examples/server-hono-adapter.md +85 -0
  56. package/.docs/raw/agents/agent-approval.mdx +189 -0
  57. package/.docs/raw/agents/guardrails.mdx +13 -9
  58. package/.docs/raw/agents/networks.mdx +1 -0
  59. package/.docs/raw/agents/overview.mdx +8 -152
  60. package/.docs/raw/agents/processors.mdx +279 -0
  61. package/.docs/raw/agents/structured-output.mdx +224 -0
  62. package/.docs/raw/deployment/cloud-providers/index.mdx +19 -26
  63. package/.docs/raw/deployment/cloud-providers/netlify-deployer.mdx +44 -13
  64. package/.docs/raw/evals/running-in-ci.mdx +0 -2
  65. package/.docs/raw/{guides/getting-started → getting-started}/manual-install.mdx +2 -2
  66. package/.docs/raw/getting-started/start.mdx +1 -1
  67. package/.docs/raw/guides/build-your-ui/ai-sdk-ui.mdx +8 -0
  68. package/.docs/raw/guides/getting-started/quickstart.mdx +1 -1
  69. package/.docs/raw/guides/guide/whatsapp-chat-bot.mdx +421 -0
  70. package/.docs/raw/guides/index.mdx +3 -35
  71. package/.docs/raw/guides/migrations/upgrade-to-v1/agent.mdx +11 -0
  72. package/.docs/raw/guides/migrations/upgrade-to-v1/workflows.mdx +37 -0
  73. package/.docs/raw/index.mdx +1 -1
  74. package/.docs/raw/memory/memory-processors.mdx +265 -79
  75. package/.docs/raw/memory/working-memory.mdx +11 -2
  76. package/.docs/raw/observability/overview.mdx +0 -1
  77. package/.docs/raw/observability/tracing/bridges/otel.mdx +200 -0
  78. package/.docs/raw/observability/tracing/exporters/arize.mdx +36 -0
  79. package/.docs/raw/observability/tracing/exporters/braintrust.mdx +19 -0
  80. package/.docs/raw/observability/tracing/exporters/langfuse.mdx +83 -0
  81. package/.docs/raw/observability/tracing/exporters/langsmith.mdx +12 -0
  82. package/.docs/raw/observability/tracing/exporters/otel.mdx +34 -22
  83. package/.docs/raw/observability/tracing/exporters/posthog.mdx +20 -0
  84. package/.docs/raw/observability/tracing/overview.mdx +76 -6
  85. package/.docs/raw/observability/tracing/processors/sensitive-data-filter.mdx +0 -1
  86. package/.docs/raw/rag/retrieval.mdx +23 -6
  87. package/.docs/raw/rag/vector-databases.mdx +93 -2
  88. package/.docs/raw/reference/agents/generate.mdx +55 -6
  89. package/.docs/raw/reference/agents/network.mdx +44 -0
  90. package/.docs/raw/reference/client-js/memory.mdx +43 -0
  91. package/.docs/raw/reference/client-js/workflows.mdx +92 -63
  92. package/.docs/raw/reference/deployer/netlify.mdx +1 -2
  93. package/.docs/raw/reference/evals/scorer-utils.mdx +362 -0
  94. package/.docs/raw/reference/index.mdx +1 -0
  95. package/.docs/raw/reference/observability/tracing/bridges/otel.mdx +177 -0
  96. package/.docs/raw/reference/observability/tracing/configuration.mdx +0 -4
  97. package/.docs/raw/reference/observability/tracing/exporters/arize.mdx +29 -0
  98. package/.docs/raw/reference/observability/tracing/exporters/langfuse.mdx +43 -0
  99. package/.docs/raw/reference/observability/tracing/exporters/langsmith.mdx +17 -1
  100. package/.docs/raw/reference/observability/tracing/exporters/otel.mdx +33 -43
  101. package/.docs/raw/reference/observability/tracing/instances.mdx +0 -4
  102. package/.docs/raw/reference/observability/tracing/interfaces.mdx +29 -4
  103. package/.docs/raw/reference/observability/tracing/spans.mdx +0 -4
  104. package/.docs/raw/reference/processors/language-detector.mdx +9 -2
  105. package/.docs/raw/reference/processors/message-history-processor.mdx +131 -0
  106. package/.docs/raw/reference/processors/moderation-processor.mdx +10 -3
  107. package/.docs/raw/reference/processors/pii-detector.mdx +10 -3
  108. package/.docs/raw/reference/processors/processor-interface.mdx +502 -0
  109. package/.docs/raw/reference/processors/prompt-injection-detector.mdx +9 -2
  110. package/.docs/raw/reference/processors/semantic-recall-processor.mdx +197 -0
  111. package/.docs/raw/reference/processors/system-prompt-scrubber.mdx +2 -2
  112. package/.docs/raw/reference/processors/tool-call-filter.mdx +125 -0
  113. package/.docs/raw/reference/processors/working-memory-processor.mdx +221 -0
  114. package/.docs/raw/reference/server/create-route.mdx +314 -0
  115. package/.docs/raw/reference/server/express-adapter.mdx +193 -0
  116. package/.docs/raw/reference/server/hono-adapter.mdx +174 -0
  117. package/.docs/raw/reference/server/mastra-server.mdx +316 -0
  118. package/.docs/raw/reference/server/routes.mdx +250 -0
  119. package/.docs/raw/reference/storage/cloudflare-d1.mdx +37 -0
  120. package/.docs/raw/reference/storage/convex.mdx +164 -0
  121. package/.docs/raw/reference/storage/lance.mdx +33 -0
  122. package/.docs/raw/reference/storage/libsql.mdx +37 -0
  123. package/.docs/raw/reference/storage/mongodb.mdx +39 -0
  124. package/.docs/raw/reference/storage/mssql.mdx +37 -0
  125. package/.docs/raw/reference/storage/postgresql.mdx +37 -0
  126. package/.docs/raw/reference/streaming/ChunkType.mdx +1 -1
  127. package/.docs/raw/reference/streaming/agents/stream.mdx +56 -1
  128. package/.docs/raw/reference/streaming/workflows/observeStream.mdx +7 -9
  129. package/.docs/raw/reference/streaming/workflows/{resumeStreamVNext.mdx → resumeStream.mdx} +51 -11
  130. package/.docs/raw/reference/streaming/workflows/stream.mdx +83 -24
  131. package/.docs/raw/reference/streaming/workflows/timeTravelStream.mdx +170 -0
  132. package/.docs/raw/reference/tools/mcp-client.mdx +128 -18
  133. package/.docs/raw/reference/vectors/convex.mdx +429 -0
  134. package/.docs/raw/reference/vectors/duckdb.mdx +462 -0
  135. package/.docs/raw/reference/vectors/elasticsearch.mdx +310 -0
  136. package/.docs/raw/reference/voice/google.mdx +159 -20
  137. package/.docs/raw/reference/workflows/run-methods/restart.mdx +142 -0
  138. package/.docs/raw/reference/workflows/run-methods/resume.mdx +44 -0
  139. package/.docs/raw/reference/workflows/run-methods/start.mdx +44 -0
  140. package/.docs/raw/reference/workflows/run-methods/timeTravel.mdx +310 -0
  141. package/.docs/raw/reference/workflows/run.mdx +27 -5
  142. package/.docs/raw/reference/workflows/step.mdx +13 -0
  143. package/.docs/raw/reference/workflows/workflow.mdx +19 -0
  144. package/.docs/raw/server-db/custom-adapters.mdx +380 -0
  145. package/.docs/raw/server-db/mastra-server.mdx +16 -8
  146. package/.docs/raw/server-db/request-context.mdx +0 -1
  147. package/.docs/raw/server-db/server-adapters.mdx +286 -0
  148. package/.docs/raw/server-db/storage.mdx +11 -0
  149. package/.docs/raw/streaming/overview.mdx +6 -6
  150. package/.docs/raw/streaming/tool-streaming.mdx +2 -2
  151. package/.docs/raw/streaming/workflow-streaming.mdx +5 -11
  152. package/.docs/raw/workflows/error-handling.mdx +1 -0
  153. package/.docs/raw/workflows/human-in-the-loop.mdx +4 -4
  154. package/.docs/raw/workflows/overview.mdx +56 -44
  155. package/.docs/raw/workflows/snapshots.mdx +1 -0
  156. package/.docs/raw/workflows/suspend-and-resume.mdx +85 -16
  157. package/.docs/raw/workflows/time-travel.mdx +313 -0
  158. package/.docs/raw/workflows/workflow-state.mdx +191 -0
  159. package/CHANGELOG.md +16 -0
  160. package/package.json +4 -4
  161. package/.docs/raw/agents/human-in-the-loop-with-tools.mdx +0 -91
  162. package/.docs/raw/reference/streaming/workflows/observeStreamVNext.mdx +0 -47
  163. package/.docs/raw/reference/streaming/workflows/streamVNext.mdx +0 -153
@@ -13,7 +13,7 @@ Use `suspend()` to pause workflow execution at a specific step. You can define a
13
13
  - If the condition isn’t met, the workflow pauses and returns `suspend()`.
14
14
  - If the condition is met, the workflow continues with the remaining logic in the step.
15
15
 
16
- ![Pausing a workflow with suspend()](/img/workflows/workflows-suspend-resume-suspend.jpg)
16
+ ![Pausing a workflow with suspend()](/img/workflows/workflows-suspend.jpg)
17
17
 
18
18
  ```typescript {9-11,16-18} title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
19
19
  const step1 = createStep({
@@ -56,13 +56,15 @@ export const testWorkflow = createWorkflow({
56
56
 
57
57
  ## Restarting a workflow with `resume()`
58
58
 
59
- Use `resume()` to restart a suspended workflow from the step where it paused. To satisfy the step’s suspend condition, pass a value using `resumeData` that matches the step's `resumeSchema`, allowing execution to continue from the suspended step.
59
+ 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.
60
60
 
61
- ![Restarting a workflow with resume()](/img/workflows/workflows-suspend-resume-resume.jpg)
61
+ ![Restarting a workflow with resume()](/img/workflows/workflows-resume.jpg)
62
+
63
+ ```typescript showLineNumbers copy
64
+ import { step1 } from "./workflows/test-workflow";
62
65
 
63
- ```typescript {13} showLineNumbers copy
64
66
  const workflow = mastra.getWorkflow("testWorkflow");
65
- const run = await workflow.createRunAsync();
67
+ const run = await workflow.createRun();
66
68
 
67
69
  await run.start({
68
70
  inputData: {
@@ -72,34 +74,99 @@ await run.start({
72
74
 
73
75
  const handleResume = async () => {
74
76
  const result = await run.resume({
75
- step: 'step-1',
77
+ step: step1,
76
78
  resumeData: { approved: true }
77
79
  });
78
80
  };
79
81
  ```
80
82
 
81
- You can resume a suspended workflow using different triggers, including [human input](/docs/v1/workflows/human-in-the-loop), external events from your application, or time-based conditions.
83
+ 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.
82
84
 
83
- ```typescript {10} showLineNumbers copy
84
- const handleResume = async () => {
85
- const result = await run.resume({
86
- step: 'step-1',
87
- resumeData: { approved: true }
88
- });
89
- };
85
+ ```typescript showLineNumbers copy
86
+ const result = await run.resume({
87
+ step: "step-1",
88
+ resumeData: { approved: true }
89
+ });
90
+ ```
91
+
92
+ If only one step is suspended, you can omit the step argument entirely and Mastra will resume the last suspended step in the workflow.
93
+
94
+ When resuming with only a `runId`, create a run instance first using `createRunAsync()`.
90
95
 
96
+ ```typescript showLineNumbers copy
97
+ const workflow = mastra.getWorkflow("testWorkflow");
98
+ const run = await workflow.createRunAsync({ runId: "123" });
99
+
100
+ const stream = run.resume({
101
+ resumeData: { approved: true }
102
+ });
103
+ ```
104
+
105
+ You can call `resume()` from anywhere in your application, including HTTP endpoints, event handlers, in response to [human input](/docs/v1/workflows/human-in-the-loop), or timers.
106
+
107
+ ```typescript showLineNumbers copy
91
108
  const midnight = new Date();
92
109
  midnight.setUTCHours(24, 0, 0, 0);
93
- setTimeout(handleResume, midnight.getTime() - Date.now());
110
+
111
+ setTimeout(async () => {
112
+ await run.resume({
113
+ step: "step-1",
114
+ resumeData: { approved: true }
115
+ });
116
+ }, midnight.getTime() - Date.now());
94
117
  ```
95
118
 
119
+ ## Accessing suspend data with `suspendData`
120
+ 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.
121
+
122
+ ```typescript {22-25,29-30} title="src/mastra/workflows/user-approval.ts" showLineNumbers copy
123
+ const approvalStep = createStep({
124
+ id: "user-approval",
125
+ inputSchema: z.object({
126
+ requestId: z.string()
127
+ }),
128
+ resumeSchema: z.object({
129
+ approved: z.boolean()
130
+ }),
131
+ suspendSchema: z.object({
132
+ reason: z.string(),
133
+ requestDetails: z.string()
134
+ }),
135
+ outputSchema: z.object({
136
+ result: z.string()
137
+ }),
138
+ execute: async ({ inputData, resumeData, suspend, suspendData }) => {
139
+ const { requestId } = inputData;
140
+ const { approved } = resumeData ?? {};
141
+
142
+ // On first execution, suspend with context
143
+ if (!approved) {
144
+ return await suspend({
145
+ reason: "User approval required",
146
+ requestDetails: `Request ${requestId} pending review`
147
+ });
148
+ }
149
+
150
+ // On resume, access the original suspend data
151
+ const suspendReason = suspendData?.reason || "Unknown";
152
+ const details = suspendData?.requestDetails || "No details";
153
+
154
+ return {
155
+ result: `${details} - ${suspendReason} - Decision: ${approved ? 'Approved' : 'Rejected'}`
156
+ };
157
+ }
158
+ });
159
+ ```
160
+
161
+ 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.
162
+
96
163
  ## Identifying suspended executions
97
164
 
98
165
  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](/docs/v1/workflows/overview#workflows-as-steps).
99
166
 
100
167
  ```typescript {11} showLineNumbers copy
101
168
  const workflow = mastra.getWorkflow("testWorkflow");
102
- const run = await workflow.createRunAsync();
169
+ const run = await workflow.createRun();
103
170
 
104
171
  const result = await run.start({
105
172
  inputData: {
@@ -139,3 +206,5 @@ Sleep and event methods can be used to pause execution at the workflow level, wh
139
206
 
140
207
  - [Control Flow](/docs/v1/workflows/control-flow)
141
208
  - [Human-in-the-loop](/docs/v1/workflows/human-in-the-loop)
209
+ - [Snapshots](/docs/v1/workflows/snapshots)
210
+ - [Time Travel](/docs/v1/workflows/time-travel)
@@ -0,0 +1,313 @@
1
+ ---
2
+ title: "Time Travel | Workflows"
3
+ description: "Re-execute workflow steps from a specific point using time travel debugging in Mastra"
4
+ ---
5
+
6
+ # Time Travel
7
+
8
+ 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.
9
+ You can also use time travel to execute a workflow that has not been run yet, starting from any specific step.
10
+
11
+ ## How time travel works
12
+
13
+ When you call `timeTravel()` on a workflow run:
14
+
15
+ 1. The workflow loads the existing snapshot from storage (if available)
16
+ 2. Step results before the target step are reconstructed from the snapshot or provided context
17
+ 3. Execution begins from the specified step with the provided or reconstructed input data
18
+ 4. The workflow continues to completion from that point forward
19
+
20
+ Time travel requires storage to be configured since it relies on persisted workflow snapshots.
21
+
22
+ ## Basic usage
23
+
24
+ Use `run.timeTravel()` to re-execute a workflow from a specific step:
25
+
26
+ ```typescript showLineNumbers copy
27
+ import { mastra } from "./mastra";
28
+
29
+ const workflow = mastra.getWorkflow("myWorkflow");
30
+ const run = await workflow.createRun();
31
+
32
+ const result = await run.timeTravel({
33
+ step: "step2",
34
+ inputData: { previousStepResult: "custom value" },
35
+ });
36
+ ```
37
+
38
+ ## Specifying the target step
39
+
40
+ You can specify the target step using either a step reference or a step ID:
41
+
42
+ ### Using step reference
43
+
44
+ ```typescript showLineNumbers copy
45
+ const result = await run.timeTravel({
46
+ step: step2,
47
+ inputData: { value: 10 },
48
+ });
49
+ ```
50
+
51
+ ### Using step ID
52
+
53
+ ```typescript showLineNumbers copy
54
+ const result = await run.timeTravel({
55
+ step: "step2",
56
+ inputData: { value: 10 },
57
+ });
58
+ ```
59
+
60
+ ### Nested workflow steps
61
+
62
+ For steps inside nested workflows, use dot notation, an array of step IDS or an array of step references:
63
+
64
+ ```typescript showLineNumbers copy
65
+ // Using dot notation
66
+ const result = await run.timeTravel({
67
+ step: "nestedWorkflow.step3",
68
+ inputData: { value: 10 },
69
+ });
70
+
71
+ // Using array of step IDs
72
+ const result = await run.timeTravel({
73
+ step: ["nestedWorkflow", "step3"],
74
+ inputData: { value: 10 },
75
+ });
76
+
77
+ // Using array of step references
78
+ const result = await run.timeTravel({
79
+ step: [nestedWorkflow, step3],
80
+ inputData: { value: 10 },
81
+ });
82
+ ```
83
+
84
+ ## Providing execution context
85
+
86
+ You can provide context to specify the state of previous steps when time traveling:
87
+
88
+ ```typescript {3-13} showLineNumbers copy
89
+ const result = await run.timeTravel({
90
+ step: "step2",
91
+ context: {
92
+ step1: {
93
+ status: "success",
94
+ payload: { value: 0 },
95
+ output: { step1Result: 2 },
96
+ startedAt: Date.now(),
97
+ endedAt: Date.now(),
98
+ },
99
+ },
100
+ });
101
+ ```
102
+
103
+ The context object contains step results keyed by step ID. Each step result includes:
104
+
105
+ - `status`: The step's execution status (`success`, `failed`, `suspended`)
106
+ - `payload`: The input data passed to the step
107
+ - `output`: The step's output data (for successful steps)
108
+ - `startedAt`: Timestamp when the step started
109
+ - `endedAt`: Timestamp when the step ended (for completed steps)
110
+ - `suspendPayload`: Data passed to `suspend()` (for suspended steps)
111
+ - `resumePayload`: Data passed to `resume()` (for resumed steps)
112
+
113
+ ## Re-running failed workflows
114
+
115
+ Time travel is particularly useful for debugging and recovering from failed workflow executions:
116
+
117
+ ```typescript showLineNumbers copy
118
+ const workflow = mastra.getWorkflow("myWorkflow");
119
+ const run = await workflow.createRun();
120
+
121
+ // Initial run fails at step2
122
+ const failedResult = await run.start({
123
+ inputData: { value: 1 },
124
+ });
125
+
126
+ if (failedResult.status === "failed") {
127
+ // Re-run from step2 with corrected input
128
+ const recoveredResult = await run.timeTravel({
129
+ step: "step2",
130
+ inputData: { step1Result: 5 }, // Provide corrected input
131
+ });
132
+ }
133
+ ```
134
+
135
+ ## Time travel with suspended workflows
136
+
137
+ You can time travel to resume a suspended workflow from an earlier step:
138
+
139
+ ```typescript showLineNumbers copy
140
+ const run = await workflow.createRun();
141
+
142
+ // Start workflow - suspends at promptAgent step
143
+ const initialResult = await run.start({
144
+ inputData: { input: "test" },
145
+ });
146
+
147
+ if (initialResult.status === "suspended") {
148
+ // Time travel back to an earlier step with resume data
149
+ const result = await run.timeTravel({
150
+ step: "getUserInput",
151
+ resumeData: {
152
+ userInput: "corrected input",
153
+ },
154
+ });
155
+ }
156
+ ```
157
+
158
+ ## Streaming time travel results
159
+
160
+ Use `timeTravelStream()` to receive streaming events during time travel execution:
161
+
162
+ ```typescript showLineNumbers copy
163
+ const run = await workflow.createRun();
164
+
165
+ const output = run.timeTravelStream({
166
+ step: "step2",
167
+ inputData: { value: 10 },
168
+ });
169
+
170
+ // Access the stream
171
+ for await (const event of output.fullStream) {
172
+ console.log(event.type, event.payload);
173
+ }
174
+
175
+ // Get final result
176
+ const result = await output.result;
177
+ ```
178
+
179
+ ## Time travel with initial state
180
+
181
+ You can provide initial state when time traveling to set workflow-level state:
182
+
183
+ ```typescript showLineNumbers copy
184
+ const result = await run.timeTravel({
185
+ step: "step2",
186
+ inputData: { value: 10 },
187
+ initialState: {
188
+ counter: 5,
189
+ metadata: { source: "time-travel" },
190
+ },
191
+ });
192
+ ```
193
+
194
+ ## Error handling
195
+
196
+ Time travel throws errors in specific situations:
197
+
198
+ ### Running workflow
199
+
200
+ You cannot time travel to a workflow that is currently running:
201
+
202
+ ```typescript showLineNumbers copy
203
+ try {
204
+ await run.timeTravel({ step: "step2" });
205
+ } catch (error) {
206
+ // "This workflow run is still running, cannot time travel"
207
+ }
208
+ ```
209
+
210
+ ### Invalid step ID
211
+
212
+ Time travel throws if the target step doesn't exist in the workflow:
213
+
214
+ ```typescript showLineNumbers copy
215
+ try {
216
+ await run.timeTravel({ step: "nonExistentStep" });
217
+ } catch (error) {
218
+ // "Time travel target step not found in execution graph: 'nonExistentStep'. Verify the step id/path."
219
+ }
220
+ ```
221
+
222
+ ### Invalid input data
223
+
224
+ When `validateInputs` is enabled, time travel validates the input data against the step's schema:
225
+
226
+ ```typescript showLineNumbers copy
227
+ try {
228
+ await run.timeTravel({
229
+ step: "step2",
230
+ inputData: { invalidField: "value" },
231
+ });
232
+ } catch (error) {
233
+ // "Invalid inputData: \n- step1Result: Required"
234
+ }
235
+ ```
236
+
237
+ ## Nested workflows context
238
+
239
+ When time traveling into a nested workflow, you can provide context for both the parent and nested workflow steps:
240
+
241
+ ```typescript showLineNumbers copy
242
+ const result = await run.timeTravel({
243
+ step: "nestedWorkflow.step3",
244
+ context: {
245
+ step1: {
246
+ status: "success",
247
+ payload: { value: 0 },
248
+ output: { step1Result: 2 },
249
+ startedAt: Date.now(),
250
+ endedAt: Date.now(),
251
+ },
252
+ nestedWorkflow: {
253
+ status: "running",
254
+ payload: { step1Result: 2 },
255
+ startedAt: Date.now(),
256
+ },
257
+ },
258
+ nestedStepsContext: {
259
+ nestedWorkflow: {
260
+ step2: {
261
+ status: "success",
262
+ payload: { step1Result: 2 },
263
+ output: { step2Result: 3 },
264
+ startedAt: Date.now(),
265
+ endedAt: Date.now(),
266
+ },
267
+ },
268
+ },
269
+ });
270
+ ```
271
+
272
+ ## Use cases
273
+
274
+ ### Debugging failed steps
275
+
276
+ Re-run a failed step with the same or modified input to diagnose issues:
277
+
278
+ ```typescript showLineNumbers copy
279
+ const result = await run.timeTravel({
280
+ step: failedStepId,
281
+ context: originalContext, // Use context from the failed run
282
+ });
283
+ ```
284
+
285
+ ### Testing step logic on new workflow run
286
+
287
+ Test individual steps with specific inputs on a new workflow run, useful for testing a step logic without starting workflow execution from the beginning.
288
+
289
+ ```typescript showLineNumbers copy
290
+ const result = await run.timeTravel({
291
+ step: "processData",
292
+ inputData: { testData: "specific test case" },
293
+ });
294
+ ```
295
+
296
+ ### Recovering from transient failures
297
+
298
+ Re-run steps that failed due to temporary issues (network errors, rate limits):
299
+
300
+ ```typescript showLineNumbers copy
301
+ // After fixing the external service issue
302
+ const result = await run.timeTravel({
303
+ step: "callExternalApi",
304
+ inputData: savedInputData,
305
+ });
306
+ ```
307
+
308
+ ## Related
309
+
310
+ - [Snapshots](/docs/v1/workflows/snapshots)
311
+ - [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
312
+ - [Error Handling](/docs/v1/workflows/error-handling)
313
+ - [Control Flow](/docs/v1/workflows/control-flow)
@@ -0,0 +1,191 @@
1
+ ---
2
+ title: "Workflow state | Workflows"
3
+ description: "Share values across workflow steps using global state that persists through the entire workflow run."
4
+ ---
5
+
6
+ # Workflow State
7
+
8
+ 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.
9
+
10
+ ## State vs step input/output
11
+
12
+ It's important to understand the difference between **state** and **step input/output**:
13
+
14
+ - **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.
15
+ - **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.
16
+
17
+ ```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
18
+ const step1 = createStep({
19
+ id: "step-1",
20
+ inputSchema: z.object({ workflowInput: z.string() }),
21
+ outputSchema: z.object({ step1Output: z.string() }),
22
+ stateSchema: z.object({ sharedCounter: z.number() }),
23
+ execute: async ({ inputData, state, setState }) => {
24
+ // inputData comes from workflow input or previous step's output
25
+ console.log(inputData.workflowInput);
26
+
27
+ // state is the shared workflow state
28
+ console.log(state.sharedCounter);
29
+
30
+ // Update state for subsequent steps
31
+ setState({ ...state, sharedCounter: state.sharedCounter + 1 });
32
+
33
+ // Return output that flows to next step's inputData
34
+ return { step1Output: "processed" };
35
+ },
36
+ });
37
+ ```
38
+
39
+ ## Defining state schemas
40
+
41
+ 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:
42
+
43
+ ```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
44
+ const step1 = createStep({
45
+ // ...
46
+ stateSchema: z.object({
47
+ processedItems: z.array(z.string()),
48
+ }),
49
+ execute: async ({ inputData, state, setState }) => {
50
+ const { message } = inputData;
51
+ const { processedItems } = state;
52
+
53
+ setState({
54
+ ...state,
55
+ processedItems: [...processedItems, "item-1", "item-2"],
56
+ });
57
+
58
+ return {
59
+ formatted: message.toUpperCase(),
60
+ };
61
+ },
62
+ });
63
+
64
+ const step2 = createStep({
65
+ // ...
66
+ stateSchema: z.object({
67
+ metadata: z.object({
68
+ processedBy: z.string(),
69
+ }),
70
+ }),
71
+ execute: async ({ inputData, state }) => {
72
+ const { formatted } = inputData;
73
+ const { metadata } = state;
74
+
75
+ return {
76
+ emphasized: `${formatted}!! ${metadata.processedBy}`,
77
+ };
78
+ },
79
+ });
80
+
81
+ export const testWorkflow = createWorkflow({
82
+ // ...
83
+ stateSchema: z.object({
84
+ processedItems: z.array(z.string()),
85
+ metadata: z.object({
86
+ processedBy: z.string(),
87
+ }),
88
+ }),
89
+ })
90
+ .then(step1)
91
+ .then(step2)
92
+ .commit();
93
+ ```
94
+
95
+ ## Setting initial state
96
+
97
+ Pass `initialState` when starting a workflow run to set the starting values:
98
+
99
+ ```typescript showLineNumbers copy
100
+ const run = await workflow.createRun();
101
+
102
+ const result = await run.start({
103
+ inputData: { message: "Hello" },
104
+ initialState: {
105
+ processedItems: [],
106
+ metadata: { processedBy: "system" },
107
+ },
108
+ });
109
+ ```
110
+
111
+ The `initialState` object should match the structure defined in the workflow's `stateSchema`.
112
+
113
+ ## State persistence across suspend/resume
114
+
115
+ State automatically persists across suspend and resume cycles. When a workflow suspends and later resumes, all state updates made before the suspension are preserved:
116
+
117
+ ```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
118
+ const step1 = createStep({
119
+ id: "step-1",
120
+ inputSchema: z.object({}),
121
+ outputSchema: z.object({}),
122
+ stateSchema: z.object({ count: z.number(), items: z.array(z.string()) }),
123
+ resumeSchema: z.object({ proceed: z.boolean() }),
124
+ execute: async ({ state, setState, suspend, resumeData }) => {
125
+ if (!resumeData) {
126
+ // First run: update state and suspend
127
+ setState({ ...state, count: state.count + 1, items: [...state.items, "item-1"] });
128
+ await suspend({});
129
+ return {};
130
+ }
131
+ // After resume: state changes are preserved (count: 1, items: ["item-1"])
132
+ return {};
133
+ },
134
+ });
135
+ ```
136
+
137
+ ## State in nested workflows
138
+
139
+ 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:
140
+
141
+ ```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
142
+ const nestedStep = createStep({
143
+ id: "nested-step",
144
+ inputSchema: z.object({}),
145
+ outputSchema: z.object({ result: z.string() }),
146
+ stateSchema: z.object({ sharedValue: z.string() }),
147
+ execute: async ({ state }) => {
148
+ // Receives state modified by parent workflow
149
+ return { result: `Received: ${state.sharedValue}` };
150
+ },
151
+ });
152
+
153
+ const nestedWorkflow = createWorkflow({
154
+ id: "nested-workflow",
155
+ inputSchema: z.object({}),
156
+ outputSchema: z.object({ result: z.string() }),
157
+ stateSchema: z.object({ sharedValue: z.string() }),
158
+ })
159
+ .then(nestedStep)
160
+ .commit();
161
+
162
+ const parentStep = createStep({
163
+ id: "parent-step",
164
+ inputSchema: z.object({}),
165
+ outputSchema: z.object({}),
166
+ stateSchema: z.object({ sharedValue: z.string() }),
167
+ execute: async ({ state, setState }) => {
168
+ // Modify state before nested workflow runs
169
+ setState({ ...state, sharedValue: "modified-by-parent" });
170
+ return {};
171
+ },
172
+ });
173
+
174
+ const parentWorkflow = createWorkflow({
175
+ id: "parent-workflow",
176
+ inputSchema: z.object({}),
177
+ outputSchema: z.object({ result: z.string() }),
178
+ stateSchema: z.object({ sharedValue: z.string() }),
179
+ })
180
+ .then(parentStep)
181
+ .then(nestedWorkflow)
182
+ .commit();
183
+ ```
184
+
185
+ ## Related
186
+
187
+ - [Workflows overview](/docs/v1/workflows/overview)
188
+ - [Suspend & Resume](/docs/v1/workflows/suspend-and-resume)
189
+ - [Step Class](/reference/v1/workflows/step)
190
+ - [Workflow Class](/reference/v1/workflows/workflow)
191
+
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # @mastra/mcp-docs-server
2
2
 
3
+ ## 1.0.0-beta.7
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies [[`7a3c1b4`](https://github.com/mastra-ai/mastra/commit/7a3c1b41815496da2a8cfff4cfb0c712b4ebf535), [`3076c67`](https://github.com/mastra-ai/mastra/commit/3076c6778b18988ae7d5c4c5c466366974b2d63f), [`85d7ee1`](https://github.com/mastra-ai/mastra/commit/85d7ee18ff4e14d625a8a30ec6656bb49804989b), [`c6c1092`](https://github.com/mastra-ai/mastra/commit/c6c1092f8fbf76109303f69e000e96fd1960c4ce), [`81dc110`](https://github.com/mastra-ai/mastra/commit/81dc11008d147cf5bdc8996ead1aa61dbdebb6fc), [`bfe1de6`](https://github.com/mastra-ai/mastra/commit/bfe1de659a279e6b2204a1c540a1fb9919299c0a), [`7aedb74`](https://github.com/mastra-ai/mastra/commit/7aedb74883adf66af38e270e4068fd42e7a37036), [`8f02d80`](https://github.com/mastra-ai/mastra/commit/8f02d800777397e4b45d7f1ad041988a8b0c6630), [`d7aad50`](https://github.com/mastra-ai/mastra/commit/d7aad501ce61646b76b4b511e558ac4eea9884d0), [`def4a85`](https://github.com/mastra-ai/mastra/commit/def4a856057db7d79d1d7c64894a2236be8b4ddd), [`ce0a73a`](https://github.com/mastra-ai/mastra/commit/ce0a73abeaa75b10ca38f9e40a255a645d50ebfb), [`a02e542`](https://github.com/mastra-ai/mastra/commit/a02e542d23179bad250b044b17ff023caa61739f), [`a372c64`](https://github.com/mastra-ai/mastra/commit/a372c640ad1fd12e8f0613cebdc682fc156b4d95), [`8846867`](https://github.com/mastra-ai/mastra/commit/8846867ffa9a3746767618e314bebac08eb77d87), [`42a42cf`](https://github.com/mastra-ai/mastra/commit/42a42cf3132b9786feecbb8c13c583dce5b0e198), [`ae08bf0`](https://github.com/mastra-ai/mastra/commit/ae08bf0ebc6a4e4da992b711c4a389c32ba84cf4), [`21735a7`](https://github.com/mastra-ai/mastra/commit/21735a7ef306963554a69a89b44f06c3bcd85141), [`1d877b8`](https://github.com/mastra-ai/mastra/commit/1d877b8d7b536a251c1a7a18db7ddcf4f68d6f8b)]:
8
+ - @mastra/mcp@1.0.0-beta.5
9
+ - @mastra/core@1.0.0-beta.7
10
+
11
+ ## 1.0.0-beta.6
12
+
13
+ ### Patch Changes
14
+
15
+ - Updated dependencies [[`ac0d2f4`](https://github.com/mastra-ai/mastra/commit/ac0d2f4ff8831f72c1c66c2be809706d17f65789), [`1a0d3fc`](https://github.com/mastra-ai/mastra/commit/1a0d3fc811482c9c376cdf79ee615c23bae9b2d6), [`85a628b`](https://github.com/mastra-ai/mastra/commit/85a628b1224a8f64cd82ea7f033774bf22df7a7e), [`8215ab3`](https://github.com/mastra-ai/mastra/commit/8215ab3c3cc4af96e53ef76f58873a8749ed056a), [`c237233`](https://github.com/mastra-ai/mastra/commit/c23723399ccedf7f5744b3f40997b79246bfbe64), [`15f9e21`](https://github.com/mastra-ai/mastra/commit/15f9e216177201ea6e3f6d0bfb063fcc0953444f), [`ff94dea`](https://github.com/mastra-ai/mastra/commit/ff94dea935f4e34545c63bcb6c29804732698809), [`5b2ff46`](https://github.com/mastra-ai/mastra/commit/5b2ff4651df70c146523a7fca773f8eb0a2272f8), [`db41688`](https://github.com/mastra-ai/mastra/commit/db4168806d007417e2e60b4f68656dca4e5f40c9), [`5ca599d`](https://github.com/mastra-ai/mastra/commit/5ca599d0bb59a1595f19f58473fcd67cc71cef58), [`bff1145`](https://github.com/mastra-ai/mastra/commit/bff114556b3cbadad9b2768488708f8ad0e91475), [`5c8ca24`](https://github.com/mastra-ai/mastra/commit/5c8ca247094e0cc2cdbd7137822fb47241f86e77), [`e191844`](https://github.com/mastra-ai/mastra/commit/e1918444ca3f80e82feef1dad506cd4ec6e2875f), [`22553f1`](https://github.com/mastra-ai/mastra/commit/22553f11c63ee5e966a9c034a349822249584691), [`7237163`](https://github.com/mastra-ai/mastra/commit/72371635dbf96a87df4b073cc48fc655afbdce3d), [`2500740`](https://github.com/mastra-ai/mastra/commit/2500740ea23da067d6e50ec71c625ab3ce275e64), [`873ecbb`](https://github.com/mastra-ai/mastra/commit/873ecbb517586aa17d2f1e99283755b3ebb2863f), [`4cbb849`](https://github.com/mastra-ai/mastra/commit/4cbb8492ee4eb92ac875c59695dfae308cd3d33a), [`06ecd8f`](https://github.com/mastra-ai/mastra/commit/06ecd8fd03932e6a57f55346ee659ecc431d337a), [`4f9bbe5`](https://github.com/mastra-ai/mastra/commit/4f9bbe5968f42c86f4930b8193de3c3c17e5bd36), [`02e51fe`](https://github.com/mastra-ai/mastra/commit/02e51feddb3d4155cfbcc42624fd0d0970d032c0), [`8f3fa3a`](https://github.com/mastra-ai/mastra/commit/8f3fa3a652bb77da092f913ec51ae46e3a7e27dc), [`cd29ad2`](https://github.com/mastra-ai/mastra/commit/cd29ad23a255534e8191f249593849ed29160886), [`bdf4d8c`](https://github.com/mastra-ai/mastra/commit/bdf4d8cdc656d8a2c21d81834bfa3bfa70f56c16), [`854e3da`](https://github.com/mastra-ai/mastra/commit/854e3dad5daac17a91a20986399d3a51f54bf68b), [`ce18d38`](https://github.com/mastra-ai/mastra/commit/ce18d38678c65870350d123955014a8432075fd9), [`cccf9c8`](https://github.com/mastra-ai/mastra/commit/cccf9c8b2d2dfc1a5e63919395b83d78c89682a0), [`5a9bafc`](https://github.com/mastra-ai/mastra/commit/5a9bafcaaa859898e954456e781a1552dc0ad4f1), [`61a5705`](https://github.com/mastra-ai/mastra/commit/61a570551278b6743e64243b3ce7d73de915ca8a), [`db70a48`](https://github.com/mastra-ai/mastra/commit/db70a48aeeeeb8e5f92007e8ede52c364ce15287), [`f0fdc14`](https://github.com/mastra-ai/mastra/commit/f0fdc14ee233d619266b3d2bbdeea7d25cfc6d13), [`db18bc9`](https://github.com/mastra-ai/mastra/commit/db18bc9c3825e2c1a0ad9a183cc9935f6691bfa1), [`9b37b56`](https://github.com/mastra-ai/mastra/commit/9b37b565e1f2a76c24f728945cc740c2b09be9da), [`41a23c3`](https://github.com/mastra-ai/mastra/commit/41a23c32f9877d71810f37e24930515df2ff7a0f), [`5d171ad`](https://github.com/mastra-ai/mastra/commit/5d171ad9ef340387276b77c2bb3e83e83332d729), [`f03ae60`](https://github.com/mastra-ai/mastra/commit/f03ae60500fe350c9d828621006cdafe1975fdd8), [`d1e74a0`](https://github.com/mastra-ai/mastra/commit/d1e74a0a293866dece31022047f5dbab65a304d0), [`39e7869`](https://github.com/mastra-ai/mastra/commit/39e7869bc7d0ee391077ce291474d8a84eedccff), [`adb5346`](https://github.com/mastra-ai/mastra/commit/adb534629c7e7a992e7e163617c41c6239e946a3), [`5761926`](https://github.com/mastra-ai/mastra/commit/57619260c4a2cdd598763abbacd90de594c6bc76), [`c900fdd`](https://github.com/mastra-ai/mastra/commit/c900fdd504c41348efdffb205cfe80d48c38fa33), [`604a79f`](https://github.com/mastra-ai/mastra/commit/604a79fecf276e26a54a3fe01bb94e65315d2e0e), [`887f0b4`](https://github.com/mastra-ai/mastra/commit/887f0b4746cdbd7cb7d6b17ac9f82aeb58037ea5), [`376986c`](https://github.com/mastra-ai/mastra/commit/376986cba2f30faf84006b57cad85e9ce94e51d0), [`2562143`](https://github.com/mastra-ai/mastra/commit/256214336b4faa78646c9c1776612393790d8784), [`ef11a61`](https://github.com/mastra-ai/mastra/commit/ef11a61920fa0ed08a5b7ceedd192875af119749)]:
16
+ - @mastra/core@1.0.0-beta.6
17
+ - @mastra/mcp@1.0.0-beta.4
18
+
3
19
  ## 1.0.0-beta.5
4
20
 
5
21
  ### Patch Changes