@kortyx/hooks 0.23.1 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.24.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.23.1...hooks-v0.24.0) (2026-09-11)
+
+
+### Features
+
+* **hooks:** support durable parallel child workflows ([#171](https://github.com/kortyx-io/kortyx/issues/171)) ([fdf2d56](https://github.com/kortyx-io/kortyx/commit/fdf2d564d88e921988e8f3e20da9fe0c30bbcdf9))
+
 ## [0.23.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.23.0...hooks-v0.23.1) (2026-09-11)
 
 

package/README.md

@@ -78,6 +78,19 @@ string ids. Register the same definitions with the agent.
 Calls need stable ids. A child interrupt pauses the chain; resuming replays
 the enclosing node and reuses saved child results. Keep effects before calls
 idempotent. Fork/rollback retain nested checkpoints; use Redis for persistence
-across server restarts. Concurrent calls are unsupported.
+across server restarts. Join concurrent children with `parallel`:
+
+```ts
+const [first, second] = await parallel([
+  useWorkflow({ id: "first", workflow: researchWorkflow, input: { topic: "AI" } }),
+  useWorkflow({ id: "second", workflow: researchWorkflow, input: { topic: "Robotics" } }),
+]);
+```
+
+The tuple follows input order. The join preserves all siblings before pausing and
+presents waiting questions individually through the parent handle. Terminal group
+failures throw `ParallelError`, whose `results` exposes each settled outcome.
+Await groups sequentially within one node; children may contain nested groups.
+Native `Promise.all` calls and parallel graph edges remain unsupported.
 
 See [the execution and replay contract](../../docs/design-specs/child-workflows.md).

package/dist/index.d.ts

@@ -13,6 +13,16 @@ type CompleteResponseOptions = {
 /** Finish client delivery, leaving the node and workflow execution running. */
 declare function completeResponse(options?: CompleteResponseOptions): Promise<void>;
 
+/** All siblings have settled; results retain the order passed to parallel(). */
+declare class ParallelError extends AggregateError {
+    readonly results: readonly PromiseSettledResult<unknown>[];
+    constructor(results: readonly PromiseSettledResult<unknown>[]);
+}
+/** Join concurrent child calls, preserving their snapshots before suspending. */
+declare function parallel<const T extends readonly unknown[]>(values: T): Promise<{
+    -readonly [K in keyof T]: Awaited<T[K]>;
+}>;
+
 type WorkflowCallOutcome = {
     status: "completed";
     data: Record<string, unknown>;
@@ -236,4 +246,4 @@ declare function useWorkflowState<T>(key: string, ...rest: [] | [T]): [T, StateS
 /** Best effort lifecycle facts. Engine snapshots and interrupt tokens never leave the runtime. */
 declare function emitWorkflowCall(telemetry: KortyxTelemetryConfig | undefined, type: KortyxTelemetryEventType, payload: Record<string, unknown>): void;
 
-export { type CompleteResponseOptions, type HookRuntimeContext, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, emitWorkflowCall, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflow, useWorkflowState, workflowCallFingerprint };
+export { type CompleteResponseOptions, type HookRuntimeContext, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ParallelError, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, emitWorkflowCall, parallel, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflow, useWorkflowState, workflowCallFingerprint };

package/dist/index.js

@@ -19,10 +19,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ParallelError: () => ParallelError,
   WorkflowCallError: () => WorkflowCallError,
   completeResponse: () => completeResponse,
   createWorkflowHooks: () => createWorkflowHooks,
   emitWorkflowCall: () => emitWorkflowCall,
+  parallel: () => parallel,
   runWithHookContext: () => runWithHookContext,
   useAbortSignal: () => useAbortSignal,
   useInterrupt: () => useInterrupt,
@@ -90,6 +92,11 @@ var createInternalContext = (ctx) => {
     ...ctx,
     workflowCallActive: false,
     workflowCallIds: /* @__PURE__ */ new Set(),
+    workflowTasks: [],
+    parallelJoins: [],
+    parallelGroup: void 0,
+    parallelIndex: 0,
+    workflowContextClosed: false,
     nodeStateIndex: 0,
     reasonCallIndex: 0,
     currentNodeState,
@@ -161,10 +168,29 @@ function getReasonTraceAdapter() {
 async function runWithHookContext(ctx, fn) {
   const internal = createInternalContext(ctx);
   try {
-    const result = await storage.run(internal, fn);
+    const result = await storage.run(internal, async () => {
+      const drain = async () => {
+        let drained = -1;
+        while (drained !== internal.parallelJoins.length + internal.workflowTasks.length) {
+          drained = internal.parallelJoins.length + internal.workflowTasks.length;
+          await Promise.allSettled(internal.parallelJoins);
+          await Promise.all(internal.workflowTasks.map((task) => task.done));
+        }
+        internal.workflowContextClosed = true;
+      };
+      try {
+        const result2 = await fn();
+        await drain();
+        if (internal.workflowControlError) throw internal.workflowControlError;
+        return result2;
+      } catch (error) {
+        await drain();
+        throw internal.workflowControlError ?? error;
+      }
+    });
     cleanupCompletedReasonCheckpoints(internal);
     for (const key of Object.keys(internal.currentNodeState.byKey)) {
-      if (key.startsWith("__useWorkflow:") || key === "__useWorkflowActivation") {
+      if (key.startsWith("__useWorkflow:") || key.startsWith("__parallel:") || key === "__useWorkflowActivation") {
         internal.currentNodeState.byKey[key] = null;
         internal.stateDirty = true;
       }
@@ -2662,9 +2688,161 @@ function useWorkflowState(key, ...rest) {
   return [getValue(), setValue];
 }
 
+// src/parallel.ts
+var import_core6 = require("@kortyx/core");
+var ParallelChildWaiting = class extends Error {
+};
+var ParallelError = class extends AggregateError {
+  constructor(results) {
+    super(
+      results.flatMap(
+        (result) => result.status === "rejected" ? [result.reason] : []
+      ),
+      "One or more parallel operations failed."
+    );
+    this.results = results;
+    this.name = "ParallelError";
+  }
+  results;
+};
+function registerWorkflowTask(id) {
+  const ctx = getHookContext();
+  if (ctx.workflowControlError) throw ctx.workflowControlError;
+  if (ctx.workflowContextClosed)
+    throw new Error("The workflow node activation has finished.");
+  const group = ctx.parallelGroup;
+  if (group?.restored && !group.record.calls.includes(id)) {
+    throw new Error(`Parallel call membership changed during replay: '${id}'.`);
+  }
+  let finish;
+  const task = {
+    id,
+    ...group ? { group } : {},
+    completed: false,
+    done: new Promise((resolve) => {
+      finish = resolve;
+    }),
+    finish: () => {
+      task.completed = true;
+      finish();
+    }
+  };
+  ctx.workflowTasks.push(task);
+  if (group && !group.record.calls.includes(id)) group.record.calls.push(id);
+  return task;
+}
+function parallel(values) {
+  const settled = Promise.allSettled(values);
+  let ctx;
+  try {
+    ctx = getHookContext();
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  const join = async () => {
+    if (ctx.workflowControlError) throw ctx.workflowControlError;
+    if (ctx.parallelGroup)
+      throw new Error(
+        "Await each parallel group before starting another in the same node."
+      );
+    const key = `__parallel:${ctx.parallelIndex++}`;
+    const saved = ctx.currentNodeState.byKey[key];
+    const tasks = ctx.workflowTasks.filter(
+      (task) => !task.completed && !task.group
+    );
+    const ids = tasks.map((task) => task.id);
+    if (saved && (saved.version !== 1 || ids.some((id) => !saved.calls.includes(id)))) {
+      throw new Error("Parallel call membership changed during replay.");
+    }
+    const group = {
+      key,
+      record: saved ?? { version: 1, calls: ids, interrupts: [] },
+      restored: Boolean(saved),
+      ready: Promise.resolve()
+    };
+    ctx.currentNodeState.byKey[key] = group.record;
+    ctx.stateDirty = true;
+    ctx.parallelGroup = group;
+    for (const task of tasks) task.group = group;
+    const callRecord = (id) => ctx.currentNodeState.byKey[`__useWorkflow:${id}`];
+    const bridge = async (callId, index) => {
+      const interruption = callRecord(callId)?.interrupts[index];
+      if (!interruption)
+        throw new Error(
+          "Parallel interrupt history does not match the saved child."
+        );
+      try {
+        interruption.response = await awaitInterruptInternal({
+          request: interruption.request,
+          ...interruption.request.meta ? { meta: interruption.request.meta } : {}
+        });
+      } catch (error) {
+        ctx.workflowControlError = error;
+        throw error;
+      }
+    };
+    group.ready = (async () => {
+      for (const entry of group.record.interrupts)
+        await bridge(entry.callId, entry.index);
+    })();
+    try {
+      const [ready, outcomes] = await Promise.all([
+        Promise.allSettled([group.ready]),
+        settled
+      ]);
+      let drained = -1;
+      while (drained !== ctx.workflowTasks.length) {
+        drained = ctx.workflowTasks.length;
+        await Promise.all(
+          ctx.workflowTasks.filter((task) => task.group === group).map((task) => task.done)
+        );
+      }
+      if (ready[0]?.status === "rejected") throw ready[0].reason;
+      (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+      if (ctx.workflowControlError) throw ctx.workflowControlError;
+      const rejected = outcomes.filter(
+        (outcome) => outcome.status === "rejected"
+      );
+      const control = rejected.find(
+        (outcome) => (0, import_core6.isExecutionCancelled)(outcome.reason) || (0, import_core6.isExecutionLimitReached)(outcome.reason)
+      );
+      if (control) {
+        ctx.workflowControlError = control.reason;
+        throw control.reason;
+      }
+      const actual = ctx.workflowTasks.filter((task) => task.group === group).map((task) => task.id);
+      if (group.record.calls.length !== actual.length || group.record.calls.some((id) => !actual.includes(id))) {
+        throw new Error("Parallel call membership changed during replay.");
+      }
+      for (const callId of group.record.calls) {
+        const record = callRecord(callId);
+        if (record?.status !== "interrupted") continue;
+        const index = record.interrupts.length - 1;
+        if (record.interrupts[index]?.response !== void 0) continue;
+        group.record.interrupts.push({ callId, index });
+        await bridge(callId, index);
+        throw new Error(
+          "Parallel interrupt unexpectedly resumed without replay."
+        );
+      }
+      if (rejected.length) throw new ParallelError(outcomes);
+      return outcomes.map(
+        (outcome) => outcome.value
+      );
+    } finally {
+      ctx.parallelGroup = void 0;
+    }
+  };
+  const promise = join();
+  ctx.parallelJoins.push(promise);
+  void promise.catch(() => {
+  });
+  return promise;
+}
+
 // src/workflow.ts
 var import_node_crypto5 = require("crypto");
-var import_core6 = require("@kortyx/core");
+var import_core7 = require("@kortyx/core");
 
 // src/workflow-telemetry.ts
 var import_node_crypto4 = require("crypto");
@@ -2750,16 +2928,30 @@ function createWorkflowHooks(workflows) {
   };
 }
 async function useWorkflow(args) {
+  const task = registerWorkflowTask(args.id);
+  try {
+    await Promise.resolve();
+    if (task.group) await task.group.ready;
+    return await runWorkflowCall(args, task);
+  } catch (error) {
+    if ((0, import_core7.isExecutionCancelled)(error) || (0, import_core7.isExecutionLimitReached)(error))
+      getHookContext().workflowControlError = error;
+    throw error;
+  } finally {
+    task.finish();
+  }
+}
+async function runWorkflowCall(args, task) {
   const ctx = getHookContext();
-  (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+  (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
   const service = ctx.node.callWorkflow;
   if (!service)
     throw new Error("useWorkflow requires an agent workflow registry.");
   if (!args.id.trim())
     throw new Error("useWorkflow requires a stable, nonempty id.");
-  if (ctx.workflowCallActive)
+  if (ctx.workflowCallActive && !task.group)
     throw new Error(
-      "Concurrent workflow calls are not supported; await each call."
+      "Concurrent workflow calls require parallel([...]); otherwise await each call."
     );
   if (ctx.workflowCallIds.has(args.id))
     throw new Error(
@@ -2780,6 +2972,11 @@ async function useWorkflow(args) {
   });
   const key = `__useWorkflow:${args.id}`;
   let record = ctx.currentNodeState.byKey[key];
+  if (record && record.parallelKey !== task.group?.key)
+    throw new WorkflowCallError(
+      workflow,
+      "parallel call membership changed during replay"
+    );
   if (record && record.fingerprint !== fingerprint)
     throw new WorkflowCallError(
       workflow,
@@ -2790,11 +2987,12 @@ async function useWorkflow(args) {
     fingerprint,
     invocationId: (0, import_node_crypto5.randomUUID)(),
     status: "running",
-    interrupts: []
+    interrupts: [],
+    ...task.group ? { parallelKey: task.group.key } : {}
   };
   ctx.currentNodeState.byKey[key] = record;
   ctx.stateDirty = true;
-  ctx.workflowCallActive = true;
+  if (!task.group) ctx.workflowCallActive = true;
   const telemetry = ctx.node.workflowCallTelemetry;
   const activationKey = "__useWorkflowActivation";
   ctx.currentNodeState.byKey[activationKey] ??= (0, import_node_crypto5.randomUUID)();
@@ -2830,7 +3028,7 @@ async function useWorkflow(args) {
   };
   const cached = record.status === "completed";
   try {
-    for (const interruption of record.interrupts) {
+    for (const interruption of task.group ? [] : record.interrupts) {
       interruption.response = await awaitInterruptInternal({
         request: interruption.request,
         ...interruption.request.meta ? { meta: interruption.request.meta } : {}
@@ -2838,6 +3036,8 @@ async function useWorkflow(args) {
     }
     if (record.status === "failed")
       throw new WorkflowCallError(workflow, record.error ?? "child failed");
+    if (task.group && record.status === "interrupted" && record.interrupts.at(-1)?.response === void 0)
+      throw new ParallelChildWaiting();
     while (record.status !== "completed") {
       let outcome;
       try {
@@ -2856,13 +3056,13 @@ async function useWorkflow(args) {
           ...record.interrupts.length ? { response: record.interrupts.at(-1)?.response } : {}
         });
       } catch (error) {
-        (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
-        if ((0, import_core6.isExecutionCancelled)(error)) throw error;
-        if ((0, import_core6.isExecutionLimitReached)(error)) {
-          const child = error;
-          if (child.__kortyxChildSnapshot)
+        const child = error;
+        recordUsage(child?.__kortyxChildUsage);
+        (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
+        if ((0, import_core7.isExecutionCancelled)(error)) throw error;
+        if ((0, import_core7.isExecutionLimitReached)(error)) {
+          if (child?.__kortyxChildSnapshot)
             record.snapshot = child.__kortyxChildSnapshot;
-          recordUsage(child.__kortyxChildUsage);
           report("suspended", {
             reason: "limit_reached",
             limit: error.limitReached
@@ -2874,7 +3074,7 @@ async function useWorkflow(args) {
         report("failed", { error: "Child workflow failed" });
         throw new WorkflowCallError(workflow, record.error);
       }
-      (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+      (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
       recordUsage(outcome.usage);
       if (outcome.status === "completed") {
         record.data = outcome.data;
@@ -2895,6 +3095,7 @@ async function useWorkflow(args) {
           request: outcome.request
         };
         record.interrupts.push(interruption);
+        if (task.group) throw new ParallelChildWaiting();
         interruption.response = await awaitInterruptInternal({
           request: interruption.request,
           ...interruption.request.meta ? { meta: interruption.request.meta } : {}
@@ -2908,15 +3109,17 @@ async function useWorkflow(args) {
       data: JSON.parse(JSON.stringify(data))
     };
   } finally {
-    ctx.workflowCallActive = false;
+    if (!task.group) ctx.workflowCallActive = false;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ParallelError,
   WorkflowCallError,
   completeResponse,
   createWorkflowHooks,
   emitWorkflowCall,
+  parallel,
   runWithHookContext,
   useAbortSignal,
   useInterrupt,