feat(core): add workflow time-travel deterministic replay APIs

.changeset/four-cobras-yawn.md

@@ -0,0 +1,25 @@
+---
+"@voltagent/core": minor
+---
+
+Add workflow time-travel and deterministic replay APIs.
+
+New APIs:
+
+- `workflow.timeTravel(options)`
+- `workflow.timeTravelStream(options)`
+- `workflowChain.timeTravel(options)`
+- `workflowChain.timeTravelStream(options)`
+
+`timeTravel` replays a historical execution from a selected step with a new execution ID, preserving the original execution history. Replay runs can optionally override selected-step input (`inputData`), resume payload (`resumeData`), and shared workflow state (`workflowStateOverride`).
+
+Replay lineage metadata is now persisted on workflow state records:
+
+- `replayedFromExecutionId`
+- `replayFromStepId`
+
+New public type exports from `@voltagent/core` include `WorkflowTimeTravelOptions`.
+
+Also adds workflow documentation and usage examples for deterministic replay in overview, suspend/resume, and streaming docs.
+
+Adds REST API documentation for replay endpoint `POST /workflows/:id/executions/:executionId/replay`, including request/response details and both cURL and JavaScript (`fetch`) code examples for default replay and replay with overrides (`inputData`, `resumeData`, `workflowStateOverride`).

packages/core/src/memory/types.ts

@@ -189,6 +189,10 @@ export interface WorkflowStateEntry {
   userId?: string;
   /** Conversation ID if applicable */
   conversationId?: string;
+  /** Source execution ID if this run is a replay */
+  replayedFromExecutionId?: string;
+  /** Source step ID used when this run was replayed */
+  replayFromStepId?: string;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
   /** Timestamps */

packages/core/src/observability/types.ts

@@ -162,6 +162,11 @@ export interface SpanAttributes {
   "workflow.step.index"?: number;
   "workflow.step.type"?: string;
   "workflow.step.name"?: string;
+  "workflow.replayed"?: boolean;
+  "workflow.replay.source_trace_id"?: string;
+  "workflow.replay.source_span_id"?: string;
+  "workflow.replay.source_execution_id"?: string;
+  "workflow.replay.source_step_id"?: string;
 
   // Tool-specific attributes
   "tool.name"?: string;

packages/core/src/workflow/chain.ts

@@ -58,6 +58,7 @@ import type {
   WorkflowStepState,
   WorkflowStreamResult,
   WorkflowStreamWriter,
+  WorkflowTimeTravelOptions,
 } from "./types";
 
 export type { AgentConfig } from "./steps/and-agent";
@@ -987,6 +988,46 @@ export class WorkflowChain<
     return workflow.startAsync(input, options);
   }
 
+  /**
+   * Replay a historical execution from the selected step
+   * This recreates a workflow instance via `createWorkflow(...)` on each call.
+   * Use persistent/shared memory (or register the workflow) so source execution state is discoverable.
+   * For ephemeral setup patterns, prefer `chain.toWorkflow().timeTravel(...)` and reuse that instance.
+   */
+  async timeTravel(
+    options: WorkflowTimeTravelOptions,
+  ): Promise<WorkflowExecutionResult<RESULT_SCHEMA, RESUME_SCHEMA>> {
+    const workflow = createWorkflow<INPUT_SCHEMA, RESULT_SCHEMA, SUSPEND_SCHEMA, RESUME_SCHEMA>(
+      this.config,
+      // @ts-expect-error - upstream types work and this is nature of how the createWorkflow function is typed using variadic args
+      ...this.steps,
+    );
+    return (await workflow.timeTravel(options)) as unknown as WorkflowExecutionResult<
+      RESULT_SCHEMA,
+      RESUME_SCHEMA
+    >;
+  }
+
+  /**
+   * Stream a historical replay from the selected step
+   * This recreates a workflow instance via `createWorkflow(...)` on each call.
+   * Use persistent/shared memory (or register the workflow) so source execution state is discoverable.
+   * For ephemeral setup patterns, prefer `chain.toWorkflow().timeTravelStream(...)` and reuse that instance.
+   */
+  timeTravelStream(
+    options: WorkflowTimeTravelOptions,
+  ): WorkflowStreamResult<RESULT_SCHEMA, RESUME_SCHEMA> {
+    const workflow = createWorkflow<INPUT_SCHEMA, RESULT_SCHEMA, SUSPEND_SCHEMA, RESUME_SCHEMA>(
+      this.config,
+      // @ts-expect-error - upstream types work and this is nature of how the createWorkflow function is typed using variadic args
+      ...this.steps,
+    );
+    return workflow.timeTravelStream(options) as unknown as WorkflowStreamResult<
+      RESULT_SCHEMA,
+      RESUME_SCHEMA
+    >;
+  }
+
   /**
    * Restart an interrupted execution from persisted checkpoint state
    * This recreates a workflow instance via `createWorkflow(...)` on each call.