@kortyx/agent 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 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)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/providers bumped to 0.6.1
+    * @kortyx/runtime bumped to 0.15.2
+  * devDependencies
+    * @kortyx/hooks bumped to 0.23.1
+
 ## [0.20.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.19.0...agent-v0.20.0) (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;
           }
@@ -432,6 +458,16 @@ var require_dist = __commonJS({
         ...typeof nodeId === "string" && nodeId.length > 0 ? { node: nodeId } : {}
       });
     };
+    var resolveProviderOptions = (defaults, overrides) => {
+      const providerOptions = defaults || overrides ? { ...defaults, ...overrides } : void 0;
+      for (const [key, value] of Object.entries(overrides ?? {})) {
+        const previous = defaults?.[key];
+        if (previous && value && typeof previous === "object" && typeof value === "object" && !Array.isArray(previous) && !Array.isArray(value)) {
+          if (providerOptions) providerOptions[key] = { ...previous, ...value };
+        }
+      }
+      return providerOptions;
+    };
     async function runReasonEngine(args) {
       let stream = args.stream ?? args.model.options?.streaming ?? true;
       const emit = args.emit ?? true;
@@ -441,14 +477,10 @@ var require_dist = __commonJS({
       const abortSignal = args.abortSignal ?? args.model.options?.abortSignal;
       const reasoning = args.reasoning ?? args.model.options?.reasoning;
       const responseFormat = args.responseFormat ?? args.model.options?.responseFormat;
-      const defaults = args.model.options?.providerOptions;
-      const providerOptions = defaults || args.providerOptions ? { ...defaults, ...args.providerOptions } : void 0;
-      for (const [key, value] of Object.entries(args.providerOptions ?? {})) {
-        const previous = defaults?.[key];
-        if (previous && value && typeof previous === "object" && typeof value === "object" && !Array.isArray(previous) && !Array.isArray(value)) {
-          if (providerOptions) providerOptions[key] = { ...previous, ...value };
-        }
-      }
+      const providerOptions = resolveProviderOptions(
+        args.model.options?.providerOptions,
+        args.providerOptions
+      );
       const tools = args.tools ?? args.model.options?.tools;
       (0, import_core22.throwIfExecutionAborted)(abortSignal);
       const model = args.model.provider.getModel(args.model.modelId, {
@@ -1861,6 +1893,7 @@ ${tryStringify2(args.response)}`
       const tools = useReasonArgs.tools ?? [];
       const toolByName = /* @__PURE__ */ new Map();
       let validationCompleted = false;
+      let separateOutput = false;
       try {
         for (const tool of tools) {
           if (toolByName.has(tool.name)) {
@@ -1875,6 +1908,17 @@ ${tryStringify2(args.response)}`
             "useReason tools cannot be combined with useReason interrupt mode yet. Use toolExecution.approval for tool approval."
           );
         }
+        separateOutput = Boolean(
+          useReasonArgs.model.provider.getModel(useReasonArgs.model.modelId, {
+            ...useReasonArgs.model.options,
+            ...useReasonArgs.reasoning !== void 0 ? { reasoning: useReasonArgs.reasoning } : {},
+            ...useReasonArgs.responseFormat ? { responseFormat: useReasonArgs.responseFormat } : {},
+            providerOptions: resolveProviderOptions(
+              useReasonArgs.model.options?.providerOptions,
+              useReasonArgs.providerOptions
+            ) ?? {}
+          }).requiresSeparateStructuredOutput
+        );
         validationCompleted = true;
       } finally {
         if (!validationCompleted) {
@@ -1882,6 +1926,8 @@ ${tryStringify2(args.response)}`
         }
       }
       const toolDefinitions = toToolDefinitions(tools);
+      let finalizing = checkpoint?.finalizing ?? false;
+      let completed = false;
       const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
       const messages = checkpoint?.messages ?? createInitialMessages({
         system: useReasonArgs.system,
@@ -1916,6 +1962,7 @@ ${tryStringify2(args.response)}`
           messages,
           steps,
           approvedCalls,
+          finalizing,
           ...pending ? { pending } : {}
         };
         ctx.stateDirty = true;
@@ -1939,11 +1986,12 @@ ${tryStringify2(args.response)}`
           const stream = useReasonArgs.stream ?? useReasonArgs.model.options?.streaming ?? true;
           const emit = useReasonArgs.emit ?? true;
           let textStarted = false;
-          const structuredChunk = useReasonArgs.outputSchema && stream && emit && shouldStreamStructured(useReasonArgs.structured) ? createStructuredOutputStreamer(useReasonArgs, id, opId) : void 0;
+          const structuredChunk = useReasonArgs.outputSchema && (!separateOutput || finalizing) && stream && emit && shouldStreamStructured(useReasonArgs.structured) ? createStructuredOutputStreamer(useReasonArgs, id, opId) : void 0;
           const step = pending ?? await reasonEngine(
             {
               ...useReasonArgs,
-              tools: toolDefinitions,
+              tools: finalizing ? [] : toolDefinitions,
+              ...separateOutput && !finalizing ? { responseFormat: { type: "text" } } : {},
               messages,
               emit: false,
               stream,
@@ -1986,8 +2034,48 @@ ${tryStringify2(args.response)}`
               ...step.warnings ? { warnings: step.warnings } : {}
             });
           if (toolCalls.length === 0) {
+            if (separateOutput && !finalizing) {
+              if (args.allowValidatedToolOutput && useReasonArgs.outputSchema) {
+                try {
+                  finalOutput = parseReasonOutputWithSchema({
+                    text: step.text,
+                    schema: useReasonArgs.outputSchema,
+                    ...step.finishReason ? { finishReason: step.finishReason } : {},
+                    label: "useReason output"
+                  });
+                  aggregatedWarnings = mergeWarnings(aggregatedWarnings, [
+                    {
+                      type: "compatibility",
+                      feature: "responseFormat",
+                      details: "Reused locally validated tool-phase output without an extra native-schema request. Set responseFormat.schema explicitly to require provider schema enforcement."
+                    }
+                  ]);
+                  completed = true;
+                  break;
+                } catch {
+                }
+              }
+              messages.push({
+                role: "assistant",
+                content: step.text,
+                ...step.continuation ? { continuation: step.continuation } : {}
+              });
+              messages.push({
+                role: "user",
+                content: "Return the final answer using the requested output schema and the tool results above."
+              });
+              finalizing = true;
+              pending = void 0;
+              save();
+              continue;
+            }
+            completed = true;
             break;
           }
+          if (finalizing)
+            throw new Error(
+              "Provider requested a tool during schema-only finalization."
+            );
           if (!reused) {
             allToolCalls.push(...toolCalls);
             messages.push({
@@ -2131,26 +2219,26 @@ ${tryStringify2(args.response)}`
                 message: result2.content
               });
             }
-            const completed = toolResults.at(-1);
-            if (completed)
+            const completed2 = toolResults.at(-1);
+            if (completed2)
               messages.push({
                 role: "tool",
-                content: completed.content,
-                toolCallId: completed.toolCallId,
-                name: completed.name,
-                ...completed.isError !== void 0 ? { isError: completed.isError } : {}
+                content: completed2.content,
+                toolCallId: completed2.toolCallId,
+                name: completed2.name,
+                ...completed2.isError !== void 0 ? { isError: completed2.isError } : {}
               });
             save();
           }
           pending = void 0;
           save();
         }
-        if (steps.length >= maxSteps && steps.at(-1)?.toolCalls.length) {
+        if (!completed) {
           throw new Error(
             `useReason tool loop reached maxSteps (${maxSteps}) before producing a final response.`
           );
         }
-        if (useReasonArgs.outputSchema) {
+        if (useReasonArgs.outputSchema && finalOutput === void 0) {
           finalOutput = parseReasonOutputWithSchema({
             text: finalText,
             schema: useReasonArgs.outputSchema,
@@ -2232,6 +2320,9 @@ ${tryStringify2(args.response)}`
         args.model.options?.abortSignal
       );
       (0, import_core52.throwIfExecutionAborted)(abortSignal);
+      const allowValidatedToolOutput = Boolean(
+        args.outputSchema && !(args.responseFormat ?? args.model.options?.responseFormat)
+      );
       const inferred = inferOutputFormat(
         args.outputSchema,
         args.responseFormat ?? args.model.options?.responseFormat
@@ -2284,6 +2375,7 @@ ${tryStringify2(args.response)}`
       if (args.tools?.length) {
         return runReasonToolLoop({
           useReasonArgs: args,
+          allowValidatedToolOutput,
           checkpointKey,
           initialWarnings: inferred.warnings,
           ...id ? { id } : {},
@@ -2581,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;
@@ -2664,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(
@@ -2694,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,
@@ -2704,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)();
@@ -2744,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 } : {}
@@ -2752,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 {
@@ -2770,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
@@ -2788,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;
@@ -2809,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 } : {}
@@ -2822,7 +3087,7 @@ ${tryStringify2(args.response)}`
           data: JSON.parse(JSON.stringify(data))
         };
       } finally {
-        ctx.workflowCallActive = false;
+        if (!task.group) ctx.workflowCallActive = false;
       }
     }
   }