@kortyx/hooks 0.23.1 → 0.25.0

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;
       }
@@ -263,13 +289,18 @@ var resolveHookStatePatch = (args) => ({
 });
 
 // src/validation.ts
+var import_errors = require("@kortyx/core/errors");
 var parseWithSchema = (schema, value, label) => {
   if (!schema) return value;
   const parsed = schema.safeParse(value);
   if (parsed.success) return parsed.data;
   const parsedError = "error" in parsed && parsed.error ? parsed.error : void 0;
   const reason = typeof parsedError?.message === "string" && parsedError.message.length > 0 ? parsedError.message : "invalid payload";
-  throw new Error(`${label} validation failed: ${reason}`);
+  throw new import_errors.ValidationError(
+    label === "useReason output" ? "MODEL_OUTPUT_SCHEMA" : "SCHEMA_VALIDATION",
+    `${label} validation failed: ${reason}`,
+    parsedError
+  );
 };
 
 // src/interrupt.ts
@@ -411,6 +442,21 @@ var import_core3 = require("@kortyx/core");
 // src/reason-engine.ts
 var import_node_crypto2 = require("crypto");
 var import_core2 = require("@kortyx/core");
+var import_errors2 = require("@kortyx/core/errors");
+function assertModelFinish(result) {
+  if (result.finishReason?.unified !== "content-filter") return;
+  throw Object.assign(
+    new import_errors2.KortyxError("PROVIDER_REFUSAL", "The provider refused the request.", {
+      category: "provider",
+      retryable: false,
+      safeMessage: "The provider refused the request."
+    }),
+    {
+      ...result.usage ? { usage: result.usage } : {},
+      finishReason: result.finishReason
+    }
+  );
+}
 var toError = (value) => value instanceof Error ? value : new Error(String(value));
 var createRuntimeId = () => {
   try {
@@ -524,15 +570,18 @@ async function runReasonEngine(args) {
   };
   const failTrace = (span, error) => {
     const detail = error;
-    span?.fail?.(error, {
-      ...detail?.usage ? { usage: detail.usage } : {},
-      ...detail?.finishReason ? { finishReason: detail.finishReason } : {},
-      ...detail?.providerMetadata ? { providerMetadata: detail.providerMetadata } : {},
-      attributes: {
-        providerId: args.model.provider.id,
-        modelId: args.model.modelId
-      }
-    });
+    try {
+      span?.fail?.(error, {
+        ...detail?.usage ? { usage: detail.usage } : {},
+        ...detail?.finishReason ? { finishReason: detail.finishReason } : {},
+        ...detail?.providerMetadata ? { providerMetadata: detail.providerMetadata } : {},
+        attributes: {
+          providerId: args.model.provider.id,
+          modelId: args.model.modelId
+        }
+      });
+    } catch {
+    }
   };
   try {
     if (stream) {
@@ -617,6 +666,8 @@ async function runReasonEngine(args) {
           }
         }
       }
+      (0, import_core2.throwIfExecutionAborted)(abortSignal);
+      assertModelFinish({ finishReason, usage });
       if (emit) {
         emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
           ...commonMeta
@@ -638,6 +689,7 @@ async function runReasonEngine(args) {
     }
     const response = await model.invoke(messages);
     (0, import_core2.throwIfExecutionAborted)(abortSignal);
+    assertModelFinish(response);
     if (response.content) args.onTextChunk?.(response.content);
     if (emit) {
       emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
@@ -1437,6 +1489,7 @@ function createStructuredOutputStreamer(args, id, opId) {
 }
 
 // src/reason/parsing.ts
+var import_errors3 = require("@kortyx/core/errors");
 var tryJsonParse = (value) => {
   try {
     return { ok: true, value: JSON.parse(value) };
@@ -1474,132 +1527,135 @@ var resolveOutputCandidate = (text) => {
   }
   return text;
 };
-var looksLikeStructuredJsonAttempt = (value) => {
-  const trimmed = value.trim();
-  if (!trimmed) return false;
-  return trimmed.startsWith("{") || trimmed.startsWith("[") || /^```(?:json)?/i.test(trimmed);
-};
-var isLikelyTruncatedStructuredOutput = (text) => {
-  const trimmed = text.trim();
-  if (!looksLikeStructuredJsonAttempt(trimmed)) return false;
-  const direct = tryJsonParse(trimmed);
-  if (!direct.ok && direct.error) return true;
-  const block = extractJsonCodeBlock(trimmed);
-  if (!block) return false;
-  const parsedBlock = tryJsonParse(block);
-  return !parsedBlock.ok && Boolean(parsedBlock.error);
-};
-var createTruncatedStructuredOutputError = (label) => new Error(
-  `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`
+var createTruncatedStructuredOutputError = (label, cause) => new import_errors3.ValidationError(
+  "OUTPUT_TRUNCATED",
+  `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`,
+  cause
 );
-var createInvalidStructuredOutputError = (label) => new Error(
-  `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. This often happens when output is truncated or the provider does not follow JSON mode. Increase maxOutputTokens or simplify the requested output.`
+var createInvalidStructuredOutputError = (label, cause) => new import_errors3.ValidationError(
+  "INVALID_MODEL_JSON",
+  `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. Check outputSchema and provider structured-output settings.`,
+  cause
 );
 var parseReasonOutputWithSchema = (args) => {
   const candidate = resolveOutputCandidate(args.text);
+  const block = extractJsonCodeBlock(args.text.trim());
+  const validJson = tryJsonParse(args.text.trim()).ok || block !== null && tryJsonParse(block).ok;
   try {
     return parseWithSchema(args.schema, candidate, args.label);
   } catch (error) {
-    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-      throw createTruncatedStructuredOutputError(args.label);
-    }
-    if (typeof candidate === "string" && candidate.trim().length > 0) {
-      throw createInvalidStructuredOutputError(args.label);
-    }
-    throw error;
+    if (!(error instanceof import_errors3.ValidationError)) throw error;
+    const failure = args.finishReason?.unified === "length" ? createTruncatedStructuredOutputError(args.label, error) : typeof candidate === "string" && !validJson ? createInvalidStructuredOutputError(args.label, error) : error;
+    if (failure && typeof failure === "object")
+      Object.assign(failure, {
+        ...args.usage ? { usage: args.usage } : {},
+        ...args.finishReason ? { finishReason: args.finishReason } : {}
+      });
+    throw failure;
   }
 };
 var parseInterruptFirstPassResult = (args) => {
-  const candidate = resolveOutputCandidate(args.text);
-  if (!isRecord2(candidate)) {
-    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-      throw createTruncatedStructuredOutputError("useReason output");
-    }
-    if (typeof candidate === "string" && candidate.trim().length > 0) {
-      throw createInvalidStructuredOutputError("useReason output");
-    }
-    throw new Error(
-      "useReason first pass with interrupt must return a JSON object."
-    );
-  }
-  const mode = args.mode ?? "required";
-  let interruptRequired = true;
-  if (mode === "optional") {
-    if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
-      throw new Error(
-        'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
+  try {
+    const candidate = resolveOutputCandidate(args.text);
+    if (!isRecord2(candidate)) {
+      if (args.finishReason?.unified === "length") {
+        throw createTruncatedStructuredOutputError("useReason output");
+      }
+      if (typeof candidate === "string" && candidate.trim().length > 0) {
+        throw createInvalidStructuredOutputError("useReason output");
+      }
+      throw new import_errors3.ValidationError(
+        "MODEL_OUTPUT_SCHEMA",
+        "useReason first pass with interrupt must return a JSON object."
       );
     }
-    interruptRequired = candidate.decision === "interrupt";
-    if (!interruptRequired) {
-      const hasUnexpectedRequest = [
+    const mode = args.mode ?? "required";
+    let interruptRequired = true;
+    if (mode === "optional") {
+      if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
+        throw new import_errors3.ValidationError(
+          "MODEL_OUTPUT_SCHEMA",
+          'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
+        );
+      }
+      interruptRequired = candidate.decision === "interrupt";
+      if (!interruptRequired) {
+        const hasUnexpectedRequest = [
+          candidate.interruptRequest,
+          candidate.request,
+          candidate.interrupt
+        ].some((value) => value !== null && value !== void 0);
+        if (hasUnexpectedRequest) {
+          throw new import_errors3.ValidationError(
+            "MODEL_OUTPUT_SCHEMA",
+            'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
+          );
+        }
+      }
+    }
+    let request;
+    if (interruptRequired) {
+      const requestCandidates = [
         candidate.interruptRequest,
         candidate.request,
-        candidate.interrupt
-      ].some((value) => value !== null && value !== void 0);
-      if (hasUnexpectedRequest) {
-        throw new Error(
-          'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
+        candidate.interrupt,
+        mode === "required" ? candidate : void 0
+      ];
+      const requestPayload = requestCandidates.find(
+        (value) => value !== null && value !== void 0
+      );
+      request = parseWithSchema(
+        args.requestSchema,
+        requestPayload,
+        "useReason interrupt.request"
+      );
+    }
+    let output;
+    if (args.outputSchema) {
+      const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
+      try {
+        output = parseWithSchema(
+          args.outputSchema,
+          outputPayload,
+          "useReason output"
         );
+      } catch (error) {
+        if (!(error instanceof import_errors3.ValidationError)) throw error;
+        if (args.finishReason?.unified === "length") {
+          throw createTruncatedStructuredOutputError("useReason output", error);
+        }
+        throw error;
       }
     }
-  }
-  let request;
-  if (interruptRequired) {
-    const requestCandidates = [
-      candidate.interruptRequest,
-      candidate.request,
-      candidate.interrupt,
-      mode === "required" ? candidate : void 0
-    ];
-    const requestPayload = requestCandidates.find(
-      (value) => value !== null && value !== void 0
-    );
-    request = parseWithSchema(
-      args.requestSchema,
-      requestPayload,
-      "useReason interrupt.request"
-    );
-  }
-  let output;
-  if (args.outputSchema) {
-    const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
-    try {
-      output = parseWithSchema(
-        args.outputSchema,
-        outputPayload,
-        "useReason output"
+    const explicitDraft = typeof candidate.draftText === "string" && candidate.draftText.length > 0 ? candidate.draftText : typeof candidate.text === "string" && candidate.text.length > 0 ? candidate.text : void 0;
+    if (!args.outputSchema && !explicitDraft) {
+      throw new import_errors3.ValidationError(
+        "MODEL_OUTPUT_SCHEMA",
+        "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
       );
-    } catch (error) {
-      if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-        throw createTruncatedStructuredOutputError("useReason output");
-      }
-      if (typeof outputPayload === "string" && outputPayload.trim().length > 0) {
-        throw createInvalidStructuredOutputError("useReason output");
-      }
-      throw error;
     }
-  }
-  const explicitDraft = typeof candidate.draftText === "string" && candidate.draftText.length > 0 ? candidate.draftText : typeof candidate.text === "string" && candidate.text.length > 0 ? candidate.text : void 0;
-  if (!args.outputSchema && !explicitDraft) {
-    throw new Error(
-      "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
-    );
-  }
-  const draftText = explicitDraft ?? (output !== void 0 ? tryStringify(output) : String(args.text ?? ""));
-  if (!interruptRequired) {
+    const draftText = explicitDraft ?? (output !== void 0 ? tryStringify(output) : String(args.text ?? ""));
+    if (!interruptRequired) {
+      return {
+        draftText,
+        interruptRequired: false,
+        ...output !== void 0 ? { output } : {}
+      };
+    }
     return {
       draftText,
-      interruptRequired: false,
+      interruptRequired: true,
+      request,
       ...output !== void 0 ? { output } : {}
     };
+  } catch (error) {
+    if (error && typeof error === "object")
+      Object.assign(error, {
+        ...args.usage ? { usage: args.usage } : {},
+        ...args.finishReason ? { finishReason: args.finishReason } : {}
+      });
+    throw error;
   }
-  return {
-    draftText,
-    interruptRequired: true,
-    request,
-    ...output !== void 0 ? { output } : {}
-  };
 };
 
 // src/reason/prompting.ts
@@ -1813,7 +1869,7 @@ var emitReasonStructuredOutput = (args) => {
 
 // src/reason/tools.ts
 var import_core4 = require("@kortyx/core");
-var toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+var import_errors4 = require("@kortyx/core/errors");
 var toToolDefinitions = (tools) => tools.map((tool) => ({
   name: tool.name,
   ...tool.title ? { title: tool.title } : {},
@@ -1847,17 +1903,27 @@ var normalizeToolResult = (toolCall, value) => {
     ...value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) ? { structuredContent: value } : {}
   };
 };
-var closeOwnedTools = async (tools) => {
+var closeOwnedTools = async (tools, preserveFailure = false, traceSpan) => {
   const closeFns = /* @__PURE__ */ new Set();
   for (const tool of tools) {
     if (tool.closeAfterUse === false || !tool.close) continue;
     closeFns.add(tool.close);
   }
-  await Promise.all(
-    [...closeFns].map(async (close) => {
-      await close();
-    })
-  );
+  try {
+    await Promise.all(
+      [...closeFns].map(async (close) => {
+        await close();
+      })
+    );
+  } catch (error) {
+    if (!preserveFailure) throw error;
+    try {
+      traceSpan?.addEvent?.("useReason.cleanup.failed", {
+        failure: (0, import_errors4.serializeFailure)(error)
+      });
+    } catch {
+    }
+  }
 };
 var createInitialMessages = (args) => [
   ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
@@ -1874,6 +1940,7 @@ var runReasonToolLoop = async (args) => {
   const saved = ctx.currentNodeState.byKey[checkpointKey];
   const checkpoint = saved?.status === "tool_loop" ? saved : void 0;
   const opId = checkpoint?.opId ?? args.opId;
+  let primaryFailure = false;
   const tools = useReasonArgs.tools ?? [];
   const toolByName = /* @__PURE__ */ new Map();
   let validationCompleted = false;
@@ -1906,7 +1973,7 @@ var runReasonToolLoop = async (args) => {
     validationCompleted = true;
   } finally {
     if (!validationCompleted) {
-      await closeOwnedTools(tools);
+      await closeOwnedTools(tools, true, traceSpan);
     }
   }
   const toolDefinitions = toToolDefinitions(tools);
@@ -2025,6 +2092,7 @@ var runReasonToolLoop = async (args) => {
                 text: step.text,
                 schema: useReasonArgs.outputSchema,
                 ...step.finishReason ? { finishReason: step.finishReason } : {},
+                ...aggregatedUsage ? { usage: aggregatedUsage } : {},
                 label: "useReason output"
               });
               aggregatedWarnings = mergeWarnings(aggregatedWarnings, [
@@ -2112,12 +2180,12 @@ var runReasonToolLoop = async (args) => {
               options: [
                 { id: "approve", label: "Approve" },
                 { id: "deny", label: "Deny" }
-              ],
-              meta: {
-                tool: tool.name,
-                toolCallId: toolCall.id,
-                input: toolCall.input
-              }
+              ]
+            },
+            meta: {
+              tool: tool.name,
+              toolCallId: toolCall.id,
+              input: toolCall.input
             }
           });
           const approved = Array.isArray(approval) ? approval.includes("approve") : approval === "approve";
@@ -2179,12 +2247,12 @@ var runReasonToolLoop = async (args) => {
           });
         } catch (error) {
           (0, import_core4.throwIfExecutionAborted)(abortSignal);
-          if ((0, import_core4.isExecutionLimitReached)(error) || (0, import_core4.isExecutionCancelled)(error))
-            throw error;
+          if ((0, import_errors4.isControlFlowError)(error)) throw error;
           const result2 = {
             toolCallId: toolCall.id,
             name: tool.name,
-            content: toErrorMessage(error),
+            content: (0, import_errors4.serializeFailure)(error).message,
+            failure: (0, import_errors4.serializeFailure)(error),
             isError: true
           };
           toolResults.push(result2);
@@ -2193,14 +2261,16 @@ var runReasonToolLoop = async (args) => {
             emitToolEvent("tool-call-error", {
               tool: tool.name,
               toolCallId: toolCall.id,
-              message: result2.content
+              message: result2.content,
+              failure: result2.failure
             });
           }
           traceSpan?.addEvent?.("useReason.tool-call.error", {
             stepIndex,
             tool: tool.name,
             toolCallId: toolCall.id,
-            message: result2.content
+            message: result2.content,
+            failure: result2.failure
           });
         }
         const completed2 = toolResults.at(-1);
@@ -2227,6 +2297,7 @@ var runReasonToolLoop = async (args) => {
         text: finalText,
         schema: useReasonArgs.outputSchema,
         ...finalFinishReason ? { finishReason: finalFinishReason } : {},
+        ...aggregatedUsage ? { usage: aggregatedUsage } : {},
         label: "useReason output"
       });
     }
@@ -2273,15 +2344,19 @@ var runReasonToolLoop = async (args) => {
     ctx.stateDirty = true;
     return result;
   } catch (error) {
-    traceSpan?.fail?.(error, {
-      attributes: {
-        toolStepCount: steps.length,
-        toolCallCount: allToolCalls.length
-      }
-    });
+    primaryFailure = true;
+    try {
+      traceSpan?.fail?.(error, {
+        attributes: {
+          toolStepCount: steps.length,
+          toolCallCount: allToolCalls.length
+        }
+      });
+    } catch {
+    }
     throw error;
   } finally {
-    await closeOwnedTools(tools);
+    await closeOwnedTools(tools, primaryFailure, traceSpan);
   }
 };
 
@@ -2446,6 +2521,7 @@ async function useReason(args) {
         text: first.text,
         requestSchema: args.interrupt.requestSchema,
         ...first.finishReason ? { finishReason: first.finishReason } : {},
+        ...first.usage ? { usage: first.usage } : {},
         ...args.outputSchema ? { outputSchema: args.outputSchema } : {},
         mode: args.interrupt.mode ?? "required"
       });
@@ -2463,6 +2539,7 @@ async function useReason(args) {
           text: first.text,
           schema: args.outputSchema,
           ...first.finishReason ? { finishReason: first.finishReason } : {},
+          ...first.usage ? { usage: first.usage } : {},
           label: "useReason output"
         });
       }
@@ -2557,6 +2634,7 @@ async function useReason(args) {
         text: finalText,
         schema: args.outputSchema,
         ...second.finishReason ? { finishReason: second.finishReason } : {},
+        ...aggregatedUsage ? { usage: aggregatedUsage } : {},
         label: "useReason output"
       });
     }
@@ -2662,9 +2740,179 @@ function useWorkflowState(key, ...rest) {
   return [getValue(), setValue];
 }
 
+// src/parallel.ts
+var import_core6 = require("@kortyx/core");
+var import_errors5 = require("@kortyx/core/errors");
+var ParallelChildWaiting = class extends Error {
+  name = "ParallelChildWaiting";
+};
+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";
+    this.failure = (0, import_errors5.serializeFailure)({
+      version: 1,
+      code: this.code,
+      category: "workflow",
+      message: this.message,
+      retryable: null,
+      results: results.map(
+        (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors5.serializeFailure)(result.reason) }
+      )
+    });
+  }
+  results;
+  code = "PARALLEL_FAILED";
+  failure;
+  toJSON() {
+    return (0, import_errors5.serializeFailure)(this);
+  }
+};
+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");
+var import_errors6 = require("@kortyx/core/errors");
 
 // src/workflow-telemetry.ts
 var import_node_crypto4 = require("crypto");
@@ -2706,10 +2954,20 @@ function workflowCallContent(telemetry, side, value) {
 }
 
 // src/workflow.ts
-var WorkflowCallError = class extends Error {
-  constructor(workflow, message) {
-    super(`Workflow '${workflow}': ${message}`);
+var WorkflowCallError = class extends import_errors6.KortyxError {
+  constructor(workflow, message, cause, failure) {
+    const detail = (0, import_errors6.serializeFailure)(
+      failure ?? cause ?? new import_errors6.WorkflowContractError(message)
+    );
+    super(detail.code, `Workflow '${workflow}': ${message}`, {
+      ...detail,
+      safeMessage: detail.message,
+      ...cause !== void 0 ? { cause } : {}
+    });
     this.workflow = workflow;
+    Object.assign(this.failure, detail, {
+      context: { ...detail.context, workflow }
+    });
     this.name = "WorkflowCallError";
   }
   workflow;
@@ -2720,10 +2978,12 @@ function workflowCallFingerprint(value) {
     if (v === null || typeof v === "string" || typeof v === "boolean") return v;
     if (typeof v === "number" && Number.isFinite(v)) return v;
     if (typeof v !== "object" || !v || seen.has(v)) {
-      throw new Error("Workflow input and output must be JSON serializable.");
+      throw new import_errors6.WorkflowContractError(
+        "Workflow input and output must be JSON serializable."
+      );
     }
     if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype) {
-      throw new Error(
+      throw new import_errors6.WorkflowContractError(
         "Workflow input and output must contain plain JSON objects."
       );
     }
@@ -2744,29 +3004,49 @@ function createWorkflowHooks(workflows) {
     useWorkflow: (args) => {
       const workflow = workflows[args.workflow];
       if (!workflow || workflow.id !== args.workflow)
-        throw new Error("Workflow registry keys must match definition ids.");
+        throw new import_errors6.WorkflowContractError(
+          "Workflow registry keys must match definition ids."
+        );
       return useWorkflow({ ...args, workflow });
     }
   };
 }
 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.");
+    throw new import_errors6.WorkflowContractError(
+      "useWorkflow requires an agent workflow registry."
+    );
   if (!args.id.trim())
-    throw new Error("useWorkflow requires a stable, nonempty id.");
-  if (ctx.workflowCallActive)
-    throw new Error(
-      "Concurrent workflow calls are not supported; await each call."
+    throw new import_errors6.WorkflowContractError(
+      "useWorkflow requires a stable, nonempty id."
+    );
+  if (ctx.workflowCallActive && !task.group)
+    throw new import_errors6.WorkflowContractError(
+      "Concurrent workflow calls require parallel([...]); otherwise await each call."
     );
   if (ctx.workflowCallIds.has(args.id))
-    throw new Error(
+    throw new import_errors6.WorkflowContractError(
       `Duplicate workflow call id '${args.id}' in one node activation.`
     );
   if (ctx.workflowCallIds.size >= 64)
-    throw new Error(
+    throw new import_errors6.WorkflowContractError(
       "A node may call at most 64 child workflows per activation."
     );
   ctx.workflowCallIds.add(args.id);
@@ -2780,6 +3060,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 +3075,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,14 +3116,21 @@ 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 } : {}
       });
     }
     if (record.status === "failed")
-      throw new WorkflowCallError(workflow, record.error ?? "child failed");
+      throw new WorkflowCallError(
+        workflow,
+        record.error ?? "child failed",
+        void 0,
+        record.failure ?? (0, import_errors6.serializeFailure)(void 0)
+      );
+    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 +3149,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
@@ -2870,11 +3163,17 @@ async function useWorkflow(args) {
           throw error;
         }
         record.status = "failed";
-        record.error = error instanceof Error ? error.message : String(error);
+        record.failure = (0, import_errors6.serializeFailure)(error);
+        record.error = record.failure.message;
         report("failed", { error: "Child workflow failed" });
-        throw new WorkflowCallError(workflow, record.error);
+        throw new WorkflowCallError(
+          workflow,
+          record.error,
+          error,
+          record.failure
+        );
       }
-      (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 +3194,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 +3208,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,