@zhivex-ai/core 1.5.0 → 1.7.0

package/dist/workflow.d.ts

@@ -1,9 +1,8 @@
 import type { AgentSession, Runner, SessionService } from "./runner.js";
-import type { AgentApprovalRequest, AgentApprovalResponse, AgentStatus, JsonValue, LanguageModel } from "./types.js";
-import type { WorkflowStateService } from "./workflow-state-service.js";
-export declare const WORKFLOW_RUN_STATE_SCHEMA_VERSION: 1;
-export type WorkflowStatus = "running" | "completed" | "waiting_approval" | "failed";
-export type WorkflowStepStatus = "pending" | "running" | "completed" | "waiting_approval" | "failed";
+import type { AgentApprovalRequest, AgentApprovalResponse, JsonValue, LanguageModel } from "./types.js";
+import { type WorkflowRunState, type WorkflowStateService, type WorkflowStatus, type WorkflowStepResult, type WorkflowStepStatus } from "./workflow-state-contracts.js";
+export { migrateWorkflowRunState, normalizeWorkflowRunState, WORKFLOW_RUN_STATE_SCHEMA_VERSION } from "./workflow-state-contracts.js";
+export type { PersistedWorkflowRunState, WorkflowRunState, WorkflowRunStateMigrationTarget, WorkflowStatus, WorkflowStepResult, WorkflowStepStatus } from "./workflow-state-contracts.js";
 export interface WorkflowPromptContext {
     workflowId?: string;
     runId: string;
@@ -57,9 +56,12 @@ export interface WorkflowLoopStep<TModel extends LanguageModel = LanguageModel>
 export type WorkflowStep<TModel extends LanguageModel = LanguageModel> = WorkflowTaskStep<TModel> | WorkflowParallelStep | WorkflowLoopStep<TModel>;
 export interface WorkflowDefinition {
     id?: string;
+    name?: string;
     steps: WorkflowStep[];
     metadata?: Record<string, JsonValue>;
     persistence?: WorkflowPersistenceOptions;
+    /** Best-effort operational telemetry. Observer failures never fail workflow execution. */
+    onTelemetryEvent?: WorkflowTelemetryObserver;
 }
 export interface WorkflowPersistenceOptions {
     appName: string;
@@ -71,6 +73,7 @@ export interface WorkflowPersistenceOptions {
 export interface WorkflowRunInput {
     userId: string;
     sessionId?: string;
+    abortSignal?: AbortSignal;
     input?: JsonValue;
     state?: WorkflowRunState;
     approvals?: AgentApprovalResponse[];
@@ -78,42 +81,9 @@ export interface WorkflowRunInput {
     eventMetadata?: Record<string, JsonValue>;
     metadata?: Record<string, JsonValue>;
     resumeFromPersistedState?: boolean;
+    /** Overrides the definition observer for this invocation. Fail-open by contract. */
+    onTelemetryEvent?: WorkflowTelemetryObserver;
 }
-export interface WorkflowStepResult {
-    id: string;
-    kind?: "task" | "parallel" | "loop";
-    status: WorkflowStepStatus;
-    outputKey?: string;
-    outputText?: string;
-    runId?: string;
-    agentStatus?: AgentStatus;
-    approvals?: AgentApprovalRequest[];
-    children?: WorkflowStepResult[];
-    startedAt?: number;
-    finishedAt?: number;
-    error?: {
-        message: string;
-    };
-    metadata?: Record<string, JsonValue>;
-}
-export interface WorkflowRunState {
-    schemaVersion: typeof WORKFLOW_RUN_STATE_SCHEMA_VERSION;
-    workflowId?: string;
-    runId: string;
-    userId: string;
-    sessionId: string;
-    status: WorkflowStatus;
-    input?: JsonValue;
-    outputs: Record<string, JsonValue>;
-    steps: WorkflowStepResult[];
-    currentStepIndex: number;
-    session?: AgentSession;
-    metadata?: Record<string, JsonValue>;
-    createdAt: number;
-    updatedAt: number;
-}
-export type PersistedWorkflowRunState = Omit<WorkflowRunState, "session">;
-export type WorkflowRunStateMigrationTarget = typeof WORKFLOW_RUN_STATE_SCHEMA_VERSION;
 export interface WorkflowStateLookup {
     userId: string;
     sessionId: string;
@@ -125,6 +95,49 @@ export interface WorkflowRunOutput {
     steps: WorkflowStepResult[];
     session?: AgentSession;
 }
+export type WorkflowTelemetryTerminalStatus = "completed" | "waiting_approval" | "failed" | "cancelled";
+export type WorkflowTelemetryStepKind = "task" | "parallel" | "loop";
+export interface WorkflowTelemetryContext {
+    runId: string;
+    workflowId?: string;
+    workflowName?: string;
+    userId: string;
+    sessionId?: string;
+}
+export interface WorkflowTelemetryStartEvent extends WorkflowTelemetryContext {
+    type: "workflow-start";
+    startedAt: number;
+}
+export interface WorkflowTelemetryStepStartEvent extends WorkflowTelemetryContext {
+    type: "workflow-step-start";
+    stepId: string;
+    stepIndex: number;
+    stepKind: WorkflowTelemetryStepKind;
+    startedAt: number;
+}
+export interface WorkflowTelemetryStepFinishEvent extends WorkflowTelemetryContext {
+    type: "workflow-step-finish";
+    stepId: string;
+    stepIndex: number;
+    stepKind: WorkflowTelemetryStepKind;
+    status: WorkflowTelemetryTerminalStatus;
+    startedAt: number;
+    finishedAt: number;
+    error?: Error;
+}
+export interface WorkflowTelemetryFinishEvent extends WorkflowTelemetryContext {
+    type: "workflow-finish";
+    status: WorkflowTelemetryTerminalStatus;
+    startedAt: number;
+    finishedAt: number;
+    error?: Error;
+}
+export type WorkflowTelemetryEvent = WorkflowTelemetryStartEvent | WorkflowTelemetryStepStartEvent | WorkflowTelemetryStepFinishEvent | WorkflowTelemetryFinishEvent;
+export interface WorkflowTelemetryObserver {
+    (event: WorkflowTelemetryEvent): void | Promise<void>;
+    /** Runs a step while an observer-specific context is active. Implementations must invoke callback once. */
+    withStepContext?<T>(runId: string, stepIndex: number, callback: () => Promise<T>): Promise<T>;
+}
 export type WorkflowReplayTimelineEvent = {
     type: "workflow-start";
     runId: string;
@@ -196,8 +209,6 @@ export interface WorkflowReplayResult {
     timeline: WorkflowReplayTimelineEvent[];
     outputs: Record<string, JsonValue>;
 }
-export declare const normalizeWorkflowRunState: (value: unknown) => WorkflowRunState;
-export declare const migrateWorkflowRunState: (value: unknown, targetVersion?: WorkflowRunStateMigrationTarget) => WorkflowRunState;
 export declare const loadWorkflowState: (workflow: WorkflowDefinition, input: WorkflowStateLookup) => Promise<WorkflowRunState | undefined>;
 export declare const saveWorkflowState: (workflow: WorkflowDefinition, state: WorkflowRunState) => Promise<AgentSession | undefined>;
 export declare const createWorkflow: (definition: WorkflowDefinition) => WorkflowDefinition;

package/dist/workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../src/workflow.ts"],"names":[],"mappings":"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"}

package/dist/workflow.js

@@ -1,8 +1,8 @@
-import { ValidationError } from "./errors.js";
-import { createSecureId } from "./secure-id.js";
+import { normalizeWorkflowRunState, WORKFLOW_RUN_STATE_SCHEMA_VERSION } from "./workflow-state-contracts.js";
+import { createSecureId } from "#secure-id";
+export { migrateWorkflowRunState, normalizeWorkflowRunState, WORKFLOW_RUN_STATE_SCHEMA_VERSION } from "./workflow-state-contracts.js";
 const randomId = createSecureId;
 const cloneJson = (value) => JSON.parse(JSON.stringify(value));
-export const WORKFLOW_RUN_STATE_SCHEMA_VERSION = 1;
 const toOutput = (state) => ({
     status: state.status,
     state: cloneJson(state),
@@ -28,50 +28,6 @@ const createBaseState = (workflow, input) => {
         updatedAt: now
     };
 };
-export const normalizeWorkflowRunState = (value) => {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new ValidationError("WorkflowRunState must be an object.");
-    }
-    const state = value;
-    if (state.schemaVersion !== undefined && state.schemaVersion > WORKFLOW_RUN_STATE_SCHEMA_VERSION) {
-        throw new ValidationError(`Unsupported WorkflowRunState schemaVersion ${state.schemaVersion}.`);
-    }
-    if (typeof state.runId !== "string" ||
-        typeof state.userId !== "string" ||
-        typeof state.sessionId !== "string" ||
-        typeof state.status !== "string" ||
-        !state.outputs ||
-        typeof state.outputs !== "object" ||
-        Array.isArray(state.outputs) ||
-        !Array.isArray(state.steps) ||
-        typeof state.currentStepIndex !== "number" ||
-        typeof state.createdAt !== "number" ||
-        typeof state.updatedAt !== "number") {
-        throw new ValidationError("WorkflowRunState is missing required fields.");
-    }
-    return {
-        schemaVersion: WORKFLOW_RUN_STATE_SCHEMA_VERSION,
-        workflowId: state.workflowId,
-        runId: state.runId,
-        userId: state.userId,
-        sessionId: state.sessionId,
-        status: state.status,
-        input: state.input === undefined ? undefined : cloneJson(state.input),
-        outputs: cloneJson(state.outputs),
-        steps: cloneJson(state.steps),
-        currentStepIndex: state.currentStepIndex,
-        session: state.session ? cloneJson(state.session) : undefined,
-        metadata: state.metadata ? cloneJson(state.metadata) : undefined,
-        createdAt: state.createdAt,
-        updatedAt: state.updatedAt
-    };
-};
-export const migrateWorkflowRunState = (value, targetVersion = WORKFLOW_RUN_STATE_SCHEMA_VERSION) => {
-    if (targetVersion !== WORKFLOW_RUN_STATE_SCHEMA_VERSION) {
-        throw new ValidationError(`Unsupported WorkflowRunState migration target ${targetVersion}.`);
-    }
-    return normalizeWorkflowRunState(value);
-};
 const normalizeState = (state) => normalizeWorkflowRunState(state);
 const workflowPersistenceKey = (workflow) => workflow.persistence?.workflowKey ?? workflow.id ?? "default";
 const workflowMetadataKey = (workflow) => workflow.persistence?.metadataKey ?? "workflowRuns";
@@ -350,6 +306,7 @@ const runTaskStep = async (workflow, state, step, input, options) => {
             userId: state.userId,
             sessionId: state.sessionId,
             approvals: input.approvals,
+            abortSignal: input.abortSignal,
             sessionMetadata: input.sessionMetadata,
             eventMetadata: input.eventMetadata
         }
@@ -358,6 +315,7 @@ const runTaskStep = async (workflow, state, step, input, options) => {
             sessionId: state.sessionId,
             prompt: await resolveTaskPrompt(workflow, state, step, input),
             system: step.system,
+            abortSignal: input.abortSignal,
             sessionMetadata: input.sessionMetadata,
             eventMetadata: {
                 ...(input.eventMetadata ?? {}),
@@ -506,103 +464,278 @@ const runLoopStep = async (workflow, state, step, input, existingResult, started
         session: state.session
     };
 };
+const workflowTelemetryContext = (workflow, state) => ({
+    runId: state.runId,
+    workflowId: workflow.id,
+    workflowName: workflow.name,
+    userId: state.userId,
+    sessionId: state.sessionId
+});
+const preStartWorkflowTelemetryContext = (workflow, input) => ({
+    runId: input.state && typeof input.state.runId === "string" && input.state.runId
+        ? input.state.runId
+        : randomId("wfr"),
+    workflowId: workflow.id,
+    workflowName: workflow.name,
+    userId: input.userId,
+    sessionId: input.state && typeof input.state.sessionId === "string" && input.state.sessionId
+        ? input.state.sessionId
+        : input.sessionId
+});
+const emitWorkflowTelemetry = async (observer, event) => {
+    if (!observer) {
+        return;
+    }
+    try {
+        await observer(event);
+    }
+    catch {
+        // Workflow telemetry is operational and fail-open by contract.
+    }
+};
+const runWithWorkflowStepContext = async (observer, runId, stepIndex, callback) => {
+    if (!observer?.withStepContext) {
+        return callback();
+    }
+    let execution;
+    const executeOnce = () => {
+        execution ??= callback();
+        return execution;
+    };
+    try {
+        await observer.withStepContext(runId, stepIndex, executeOnce);
+    }
+    catch {
+        // Ignore context/exporter failures; the business callback result remains authoritative.
+    }
+    return execution ? await execution : callback();
+};
+const workflowStepKind = (step) => isParallelStep(step) ? "parallel" : isLoopStep(step) ? "loop" : "task";
+const toWorkflowError = (error, fallback) => error instanceof Error ? error : new Error(error === undefined ? fallback : String(error));
+const isCancellationError = (error) => error instanceof Error && (error.name === "AbortError" || error.name === "CancellationError");
+const hasCancelledAgentResult = (result) => result.agentStatus === "cancelled" || (result.children?.some(hasCancelledAgentResult) ?? false);
+const workflowStepTelemetryStatus = (result, input, error) => {
+    if (hasCancelledAgentResult(result) ||
+        isCancellationError(error) ||
+        (result.status === "failed" && input.abortSignal?.aborted)) {
+        return "cancelled";
+    }
+    if (result.status === "completed" || result.status === "waiting_approval" || result.status === "failed") {
+        return result.status;
+    }
+    return "failed";
+};
+const workflowStepTelemetryError = (result, status, input, error) => {
+    if (status === "cancelled") {
+        const cancellation = toWorkflowError(error ?? input.abortSignal?.reason, "Workflow execution was cancelled.");
+        cancellation.name = "AbortError";
+        return cancellation;
+    }
+    if (status === "failed") {
+        return toWorkflowError(error ?? result.error?.message, "Workflow step failed.");
+    }
+    return undefined;
+};
 export const runWorkflow = async (workflow, input) => {
-    const definition = validateWorkflow(workflow);
-    const state = await resolveInitialState(definition, input);
+    const invocationStartedAt = Date.now();
+    const observer = input.onTelemetryEvent ?? workflow.onTelemetryEvent;
+    let definition;
+    let state;
+    try {
+        definition = validateWorkflow(workflow);
+        state = await resolveInitialState(definition, input);
+    }
+    catch (error) {
+        const telemetryContext = preStartWorkflowTelemetryContext(workflow, input);
+        const telemetryError = toWorkflowError(error, "Workflow initialization failed.");
+        await emitWorkflowTelemetry(observer, {
+            ...telemetryContext,
+            type: "workflow-start",
+            startedAt: invocationStartedAt
+        });
+        await emitWorkflowTelemetry(observer, {
+            ...telemetryContext,
+            type: "workflow-finish",
+            status: "failed",
+            startedAt: invocationStartedAt,
+            finishedAt: Date.now(),
+            error: telemetryError
+        });
+        throw error;
+    }
     state.status = "running";
     state.updatedAt = Date.now();
-    const waitingIndex = state.steps.findIndex((step) => step.status === "waiting_approval");
-    if (waitingIndex >= 0 && !input.approvals?.length) {
-        state.status = "waiting_approval";
-        state.currentStepIndex = waitingIndex;
-        state.updatedAt = Date.now();
-        return finalizeWorkflowOutput(definition, state);
-    }
-    const startIndex = waitingIndex >= 0 ? waitingIndex : state.currentStepIndex;
-    for (let index = startIndex; index < definition.steps.length; index += 1) {
-        const step = definition.steps[index];
-        const startedAt = Date.now();
-        state.currentStepIndex = index;
-        const existingResult = state.steps[index];
-        setStepResult(state, index, isParallelStep(step)
-            ? {
-                id: step.id,
-                kind: "parallel",
-                status: "running",
-                children: existingResult?.children,
-                metadata: step.metadata ? cloneJson(step.metadata) : undefined,
-                startedAt
-            }
-            : isLoopStep(step)
+    const telemetryContext = workflowTelemetryContext(definition, state);
+    let terminalEventEmitted = false;
+    await emitWorkflowTelemetry(observer, {
+        ...telemetryContext,
+        type: "workflow-start",
+        startedAt: invocationStartedAt
+    });
+    const emitWorkflowFinish = async (status, error) => {
+        if (terminalEventEmitted) {
+            return;
+        }
+        terminalEventEmitted = true;
+        await emitWorkflowTelemetry(observer, {
+            ...telemetryContext,
+            type: "workflow-finish",
+            status,
+            startedAt: invocationStartedAt,
+            finishedAt: Date.now(),
+            error
+        });
+    };
+    const finalizeInvocation = async (status, error) => {
+        const output = await finalizeWorkflowOutput(definition, state);
+        await emitWorkflowFinish(status, error);
+        return output;
+    };
+    try {
+        const waitingIndex = state.steps.findIndex((step) => step.status === "waiting_approval");
+        if (waitingIndex >= 0 && !input.approvals?.length) {
+            state.status = "waiting_approval";
+            state.currentStepIndex = waitingIndex;
+            state.updatedAt = Date.now();
+            return await finalizeInvocation("waiting_approval");
+        }
+        const startIndex = waitingIndex >= 0 ? waitingIndex : state.currentStepIndex;
+        for (let index = startIndex; index < definition.steps.length; index += 1) {
+            const step = definition.steps[index];
+            const stepKind = workflowStepKind(step);
+            const startedAt = Date.now();
+            state.currentStepIndex = index;
+            const existingResult = state.steps[index];
+            setStepResult(state, index, isParallelStep(step)
                 ? {
                     id: step.id,
-                    kind: "loop",
+                    kind: "parallel",
                     status: "running",
                     children: existingResult?.children,
                     metadata: step.metadata ? cloneJson(step.metadata) : undefined,
                     startedAt
                 }
-                : {
-                    id: step.id,
-                    kind: "task",
-                    status: "running",
-                    outputKey: step.outputKey,
-                    metadata: step.metadata ? cloneJson(step.metadata) : undefined,
-                    startedAt
-                });
-        try {
-            const stepRun = isParallelStep(step)
-                ? await runParallelStep(definition, state, step, input, existingResult, startedAt)
                 : isLoopStep(step)
-                    ? await runLoopStep(definition, state, step, input, existingResult, startedAt)
-                    : await runTaskStep(definition, state, step, input, {
-                        startedAt,
-                        isApprovalResume: index === waitingIndex && Boolean(input.approvals?.length)
+                    ? {
+                        id: step.id,
+                        kind: "loop",
+                        status: "running",
+                        children: existingResult?.children,
+                        metadata: step.metadata ? cloneJson(step.metadata) : undefined,
+                        startedAt
+                    }
+                    : {
+                        id: step.id,
+                        kind: "task",
+                        status: "running",
+                        outputKey: step.outputKey,
+                        metadata: step.metadata ? cloneJson(step.metadata) : undefined,
+                        startedAt
                     });
-            const { result } = stepRun;
-            const output = "output" in stepRun ? stepRun.output : undefined;
-            const session = "session" in stepRun ? stepRun.session : undefined;
-            if (output?.session) {
-                state.session = output.session;
-            }
-            else if (session) {
-                state.session = session;
-            }
-            const status = result.status;
-            setStepResult(state, index, result);
-            if (status === "completed") {
-                if (!isParallelStep(step) && !isLoopStep(step)) {
-                    collectStepOutputs(state.outputs, step, result, output);
+            await emitWorkflowTelemetry(observer, {
+                ...telemetryContext,
+                type: "workflow-step-start",
+                stepId: step.id,
+                stepIndex: index,
+                stepKind,
+                startedAt
+            });
+            let stepTerminalEventEmitted = false;
+            try {
+                const stepRun = await runWithWorkflowStepContext(observer, state.runId, index, () => isParallelStep(step)
+                    ? runParallelStep(definition, state, step, input, existingResult, startedAt)
+                    : isLoopStep(step)
+                        ? runLoopStep(definition, state, step, input, existingResult, startedAt)
+                        : runTaskStep(definition, state, step, input, {
+                            startedAt,
+                            isApprovalResume: index === waitingIndex && Boolean(input.approvals?.length)
+                        }));
+                const { result } = stepRun;
+                const output = stepRun.output;
+                const session = stepRun.session;
+                if (output?.session) {
+                    state.session = output.session;
                 }
-                state.currentStepIndex = index + 1;
+                else if (session) {
+                    state.session = session;
+                }
+                const status = result.status;
+                setStepResult(state, index, result);
+                const telemetryStatus = workflowStepTelemetryStatus(result, input);
+                const telemetryError = workflowStepTelemetryError(result, telemetryStatus, input);
+                await emitWorkflowTelemetry(observer, {
+                    ...telemetryContext,
+                    type: "workflow-step-finish",
+                    stepId: step.id,
+                    stepIndex: index,
+                    stepKind,
+                    status: telemetryStatus,
+                    startedAt,
+                    finishedAt: result.finishedAt ?? Date.now(),
+                    error: telemetryError
+                });
+                stepTerminalEventEmitted = true;
+                if (status === "completed") {
+                    if (!isParallelStep(step) && !isLoopStep(step)) {
+                        collectStepOutputs(state.outputs, step, result, output);
+                    }
+                    state.currentStepIndex = index + 1;
+                    state.updatedAt = Date.now();
+                    continue;
+                }
+                state.status = status === "waiting_approval" ? "waiting_approval" : "failed";
+                state.currentStepIndex = index;
                 state.updatedAt = Date.now();
-                continue;
+                return await finalizeInvocation(telemetryStatus, telemetryError);
             }
-            state.status = status === "waiting_approval" ? "waiting_approval" : "failed";
-            state.currentStepIndex = index;
-            state.updatedAt = Date.now();
-            return finalizeWorkflowOutput(definition, state);
-        }
-        catch (error) {
-            setStepResult(state, index, isParallelStep(step)
-                ? createParallelResult(step, "failed", startedAt, existingResult?.children ?? [], {
-                    message: error instanceof Error ? error.message : String(error)
-                })
-                : isLoopStep(step)
-                    ? createLoopResult(step, "failed", startedAt, existingResult?.children ?? [], {
+            catch (error) {
+                if (stepTerminalEventEmitted) {
+                    throw error;
+                }
+                const result = isParallelStep(step)
+                    ? createParallelResult(step, "failed", startedAt, existingResult?.children ?? [], {
                         message: error instanceof Error ? error.message : String(error)
                     })
-                    : createStepResult(step, "failed", startedAt, undefined, error));
-            state.status = "failed";
-            state.currentStepIndex = index;
-            state.updatedAt = Date.now();
-            return finalizeWorkflowOutput(definition, state);
+                    : isLoopStep(step)
+                        ? createLoopResult(step, "failed", startedAt, existingResult?.children ?? [], {
+                            message: error instanceof Error ? error.message : String(error)
+                        })
+                        : createStepResult(step, "failed", startedAt, undefined, error);
+                setStepResult(state, index, result);
+                const telemetryStatus = workflowStepTelemetryStatus(result, input, error);
+                const telemetryError = workflowStepTelemetryError(result, telemetryStatus, input, error);
+                await emitWorkflowTelemetry(observer, {
+                    ...telemetryContext,
+                    type: "workflow-step-finish",
+                    stepId: step.id,
+                    stepIndex: index,
+                    stepKind,
+                    status: telemetryStatus,
+                    startedAt,
+                    finishedAt: result.finishedAt ?? Date.now(),
+                    error: telemetryError
+                });
+                stepTerminalEventEmitted = true;
+                state.status = "failed";
+                state.currentStepIndex = index;
+                state.updatedAt = Date.now();
+                return await finalizeInvocation(telemetryStatus, telemetryError);
+            }
         }
+        state.status = "completed";
+        state.currentStepIndex = definition.steps.length;
+        state.updatedAt = Date.now();
+        return await finalizeInvocation("completed");
+    }
+    catch (error) {
+        const terminalStatus = isCancellationError(error) || input.abortSignal?.aborted ? "cancelled" : "failed";
+        const terminalError = toWorkflowError(error ?? input.abortSignal?.reason, terminalStatus === "cancelled" ? "Workflow execution was cancelled." : "Workflow execution failed.");
+        if (terminalStatus === "cancelled") {
+            terminalError.name = "AbortError";
+        }
+        await emitWorkflowFinish(terminalStatus, terminalError);
+        throw error;
     }
-    state.status = "completed";
-    state.currentStepIndex = definition.steps.length;
-    state.updatedAt = Date.now();
-    return finalizeWorkflowOutput(definition, state);
 };
 export const replayWorkflowRun = (state) => {
     const timeline = [