@kortyx/agent 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.21.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.20.1...agent-v0.21.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))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/runtime bumped to 0.16.0
+  * devDependencies
+    * @kortyx/hooks bumped to 0.24.0
+
 ## [0.20.1](https://github.com/kortyx-io/kortyx/compare/agent-v0.20.0...agent-v0.20.1) (2026-09-11)
 
 

package/dist/index.js

@@ -51,10 +51,12 @@ var require_dist = __commonJS({
     var __toCommonJS2 = (mod) => __copyProps2(__defProp2({}, "__esModule", { value: true }), mod);
     var index_exports2 = {};
     __export2(index_exports2, {
+      ParallelError: () => ParallelError,
       WorkflowCallError: () => WorkflowCallError,
       completeResponse: () => completeResponse,
       createWorkflowHooks: () => createWorkflowHooks,
       emitWorkflowCall: () => emitWorkflowCall2,
+      parallel: () => parallel,
       runWithHookContext: () => runWithHookContext,
       useAbortSignal: () => useAbortSignal,
       useInterrupt: () => useInterrupt,
@@ -118,6 +120,11 @@ var require_dist = __commonJS({
         ...ctx,
         workflowCallActive: false,
         workflowCallIds: /* @__PURE__ */ new Set(),
+        workflowTasks: [],
+        parallelJoins: [],
+        parallelGroup: void 0,
+        parallelIndex: 0,
+        workflowContextClosed: false,
         nodeStateIndex: 0,
         reasonCallIndex: 0,
         currentNodeState,
@@ -189,10 +196,29 @@ var require_dist = __commonJS({
     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;
           }
@@ -2647,8 +2673,158 @@ ${tryStringify2(args.response)}`
       };
       return [getValue(), setValue];
     }
-    var import_node_crypto5 = require("crypto");
     var import_core62 = 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((resolve2) => {
+          finish = resolve2;
+        }),
+        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_core62.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_core62.isExecutionCancelled)(outcome.reason) || (0, import_core62.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;
+    }
+    var import_node_crypto5 = require("crypto");
+    var import_core7 = require("@kortyx/core");
     var import_node_crypto42 = require("crypto");
     function emitWorkflowCall2(telemetry, type, payload) {
       const base = telemetry?.correlation;
@@ -2730,16 +2906,30 @@ ${tryStringify2(args.response)}`
       };
     }
     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_core62.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(
@@ -2760,6 +2950,11 @@ ${tryStringify2(args.response)}`
       });
       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,
@@ -2770,11 +2965,12 @@ ${tryStringify2(args.response)}`
         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)();
@@ -2810,7 +3006,7 @@ ${tryStringify2(args.response)}`
       };
       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 } : {}
@@ -2818,6 +3014,8 @@ ${tryStringify2(args.response)}`
         }
         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 {
@@ -2836,13 +3034,13 @@ ${tryStringify2(args.response)}`
               ...record.interrupts.length ? { response: record.interrupts.at(-1)?.response } : {}
             });
           } catch (error) {
-            (0, import_core62.throwIfExecutionAborted)(ctx.node.abortSignal);
-            if ((0, import_core62.isExecutionCancelled)(error)) throw error;
-            if ((0, import_core62.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
@@ -2854,7 +3052,7 @@ ${tryStringify2(args.response)}`
             report("failed", { error: "Child workflow failed" });
             throw new WorkflowCallError(workflow, record.error);
           }
-          (0, import_core62.throwIfExecutionAborted)(ctx.node.abortSignal);
+          (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
           recordUsage(outcome.usage);
           if (outcome.status === "completed") {
             record.data = outcome.data;
@@ -2875,6 +3073,7 @@ ${tryStringify2(args.response)}`
               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 } : {}
@@ -2888,7 +3087,7 @@ ${tryStringify2(args.response)}`
           data: JSON.parse(JSON.stringify(data))
         };
       } finally {
-        ctx.workflowCallActive = false;
+        if (!task.group) ctx.workflowCallActive = false;
       }
     }
   }