feat(workflow): add execution primitives for step context (#1102)

* feat(workflow): add execution primitives for step context

* fix(workflow): handle bail without result and close bail step span

* fix(workflow): unify bail handling and type bail payload

* fix(workflow): update bail state before step-end hook

Author: omeraplak

.changeset/fresh-otters-melt.md

@@ -0,0 +1,85 @@
+---
+"@voltagent/core": minor
+---
+
+feat: add workflow execution primitives (`bail`, `abort`, `getStepResult`, `getInitData`)
+
+### What's New
+
+Step execution context now includes four new primitives:
+
+- `bail(result?)`: complete the workflow early with a custom final result
+- `abort()`: cancel the workflow immediately
+- `getStepResult(stepId)`: get a prior step output directly (returns `null` if not available)
+- `getInitData()`: get the original workflow input (stable across resume paths)
+
+These primitives are available in all step contexts, including nested step flows.
+
+### Example: Early Complete with `bail`
+
+```ts
+const workflow = createWorkflowChain({
+  id: "bail-demo",
+  input: z.object({ amount: z.number() }),
+  result: z.object({ status: z.string() }),
+})
+  .andThen({
+    id: "risk-check",
+    execute: async ({ data, bail }) => {
+      if (data.amount > 10_000) {
+        bail({ status: "rejected" });
+      }
+      return { status: "approved" };
+    },
+  })
+  .andThen({
+    id: "never-runs-on-bail",
+    execute: async () => ({ status: "approved" }),
+  });
+```
+
+### Example: Cancel with `abort`
+
+```ts
+const workflow = createWorkflowChain({
+  id: "abort-demo",
+  input: z.object({ requestId: z.string() }),
+  result: z.object({ done: z.boolean() }),
+})
+  .andThen({
+    id: "authorization",
+    execute: async ({ abort }) => {
+      abort(); // terminal status: cancelled
+    },
+  })
+  .andThen({
+    id: "never-runs-on-abort",
+    execute: async () => ({ done: true }),
+  });
+```
+
+### Example: Use `getStepResult` + `getInitData`
+
+```ts
+const workflow = createWorkflowChain({
+  id: "introspection-demo",
+  input: z.object({ userId: z.string(), value: z.number() }),
+  result: z.object({ total: z.number(), userId: z.string() }),
+})
+  .andThen({
+    id: "step-1",
+    execute: async ({ data }) => ({ partial: data.value + 1 }),
+  })
+  .andThen({
+    id: "step-2",
+    execute: async ({ getStepResult, getInitData }) => {
+      const s1 = getStepResult<{ partial: number }>("step-1");
+      const init = getInitData();
+
+      return {
+        total: (s1?.partial ?? 0) + init.value,
+        userId: init.userId,
+      };
+    },
+  });
+```

packages/core/src/test-utils/mocks/workflows.ts

@@ -24,7 +24,19 @@ export function createMockWorkflowExecuteContext(
     data: overrides.data ?? ({} as DangerouslyAllowAny),
     state: overrides.state ?? ({} as DangerouslyAllowAny),
     getStepData: overrides.getStepData ?? (() => undefined),
+    getStepResult: overrides.getStepResult ?? (() => null),
+    getInitData: overrides.getInitData ?? (() => ({}) as DangerouslyAllowAny),
     suspend: overrides.suspend ?? vi.fn(),
+    bail:
+      overrides.bail ??
+      (() => {
+        throw new Error("WORKFLOW_BAIL_NOT_CONFIGURED");
+      }),
+    abort:
+      overrides.abort ??
+      (() => {
+        throw new Error("WORKFLOW_ABORT_NOT_CONFIGURED");
+      }),
     workflowState: overrides.workflowState ?? {},
     setWorkflowState: (() => undefined) as MockWorkflowExecuteContext["setWorkflowState"],
     logger: overrides.logger ?? {

packages/core/src/workflow/core.spec-d.ts

@@ -104,7 +104,11 @@ describe("non-chaining API type inference", () => {
         (update: WorkflowStateUpdater) => void
       >();
       expectTypeOf<Context["suspend"]>().toBeFunction();
+      expectTypeOf<Context["bail"]>().toBeFunction();
+      expectTypeOf<Context["abort"]>().toBeFunction();
       expectTypeOf<Context["getStepData"]>().toBeFunction();
+      expectTypeOf<Context["getStepResult"]>().toBeFunction();
+      expectTypeOf<Context["getInitData"]>().toBeFunction();
       expectTypeOf<Context["logger"]>().not.toBeNever();
       expectTypeOf<Context["writer"]>().not.toBeNever();
     });