@kortyx/runtime 0.17.2 → 0.18.0

package/dist/index.js

@@ -205,9 +205,9 @@ function createInMemoryPendingRequestStore() {
     },
     async take(token) {
       prune();
-      const record = store.get(token);
+      const record2 = store.get(token);
       store.delete(token);
-      return record ? JSON.parse(JSON.stringify(record)) : null;
+      return record2 ? JSON.parse(JSON.stringify(record2)) : null;
     },
     async save(rec) {
       prune();
@@ -761,19 +761,19 @@ var createId = (prefix) => {
   return `${prefix}-${(0, import_node_crypto.randomUUID)()}`;
 };
 var createResumeToken = () => (0, import_node_crypto.randomUUID)();
-var toSummary = (record) => ({
-  id: record.id,
-  sessionId: record.sessionId,
-  turnIndex: record.turnIndex,
-  createdAt: record.createdAt,
-  nodes: [...record.nodes],
-  workflow: record.workflow,
-  ...record.label ? { label: record.label } : {},
-  ...record.parentCheckpointId ? { parentCheckpointId: record.parentCheckpointId } : {},
-  ...record.parentSessionId ? { parentSessionId: record.parentSessionId } : {},
-  ...record.forkedFrom ? { forkedFrom: record.forkedFrom } : {},
-  ...record.workflowVersion ? { workflowVersion: record.workflowVersion } : {},
-  ...record.buildId ? { buildId: record.buildId } : {}
+var toSummary = (record2) => ({
+  id: record2.id,
+  sessionId: record2.sessionId,
+  turnIndex: record2.turnIndex,
+  createdAt: record2.createdAt,
+  nodes: [...record2.nodes],
+  workflow: record2.workflow,
+  ...record2.label ? { label: record2.label } : {},
+  ...record2.parentCheckpointId ? { parentCheckpointId: record2.parentCheckpointId } : {},
+  ...record2.parentSessionId ? { parentSessionId: record2.parentSessionId } : {},
+  ...record2.forkedFrom ? { forkedFrom: record2.forkedFrom } : {},
+  ...record2.workflowVersion ? { workflowVersion: record2.workflowVersion } : {},
+  ...record2.buildId ? { buildId: record2.buildId } : {}
 });
 function createRedisSessionCheckpointStore(options) {
   const store = options.store;
@@ -784,22 +784,22 @@ function createRedisSessionCheckpointStore(options) {
   const sessionRecordKey = (sessionId, id) => `${prefix}session:${sessionId}:${id}`;
   const sessionPrefix = (sessionId) => `${prefix}session:${sessionId}:`;
   const headKey = (sessionId) => `${prefix}head:${sessionId}`;
-  const saveRecord = async (record) => {
-    const serialized = JSON.stringify(record);
+  const saveRecord = async (record2) => {
+    const serialized = JSON.stringify(record2);
     await Promise.all([
-      store.set(byIdKey(record.id), serialized, ttlMs),
+      store.set(byIdKey(record2.id), serialized, ttlMs),
       store.set(
-        sessionRecordKey(record.sessionId, record.id),
+        sessionRecordKey(record2.sessionId, record2.id),
         serialized,
         ttlMs
       ),
-      store.set(headKey(record.sessionId), record.id, ttlMs)
+      store.set(headKey(record2.sessionId), record2.id, ttlMs)
     ]);
   };
-  const deleteRecord = async (record) => {
+  const deleteRecord = async (record2) => {
     await Promise.all([
-      store.del(byIdKey(record.id)),
-      store.del(sessionRecordKey(record.sessionId, record.id))
+      store.del(byIdKey(record2.id)),
+      store.del(sessionRecordKey(record2.sessionId, record2.id))
     ]);
   };
   const getRecord = async (id) => {
@@ -815,7 +815,7 @@ function createRedisSessionCheckpointStore(options) {
         return raw ? JSON.parse(raw) : null;
       })
     );
-    return records.filter((record) => Boolean(record)).sort((a, b) => a.turnIndex - b.turnIndex || a.createdAt - b.createdAt);
+    return records.filter((record2) => Boolean(record2)).sort((a, b) => a.turnIndex - b.turnIndex || a.createdAt - b.createdAt);
   };
   const prune = async (sessionId) => {
     const records = await sortedRecords(sessionId);
@@ -825,22 +825,22 @@ function createRedisSessionCheckpointStore(options) {
   const getHead = async (sessionId) => {
     const headId = await store.get(headKey(sessionId));
     if (!headId) return null;
-    const record = await getRecord(headId);
-    return record ? clone(record) : null;
+    const record2 = await getRecord(headId);
+    return record2 ? clone(record2) : null;
   };
   return {
     async list(sessionId) {
       return (await sortedRecords(sessionId)).map(toSummary);
     },
     async get(id) {
-      const record = await getRecord(id);
-      return record ? clone(record) : null;
+      const record2 = await getRecord(id);
+      return record2 ? clone(record2) : null;
     },
     getHead,
     async append(args) {
       const previousHead = await getHead(args.sessionId);
       const pendingRequests = args.pendingRequests ?? [];
-      const record = {
+      const record2 = {
         id: createId("cp"),
         sessionId: args.sessionId,
         runId: args.runId,
@@ -862,9 +862,9 @@ function createRedisSessionCheckpointStore(options) {
         ...args.workflowVersion ? { workflowVersion: args.workflowVersion } : {},
         ...args.buildId ? { buildId: args.buildId } : {}
       };
-      await saveRecord(record);
+      await saveRecord(record2);
       await prune(args.sessionId);
-      return clone(record);
+      return clone(record2);
     },
     async rollbackTo(id) {
       const target = await getRecord(id);
@@ -876,15 +876,15 @@ function createRedisSessionCheckpointStore(options) {
         });
       const records = await sortedRecords(target.sessionId);
       const trailing = records.filter(
-        (record) => record.turnIndex > target.turnIndex
+        (record2) => record2.turnIndex > target.turnIndex
       );
       const invalidatedStructuredStreamIds = uniqueStrings(
-        trailing.flatMap((record) => record.effects.structuredStreamIds)
+        trailing.flatMap((record2) => record2.effects.structuredStreamIds)
       );
       const invalidatedInterruptTokens = uniqueStrings(
-        trailing.flatMap((record) => [
-          ...record.effects.interruptTokens,
-          ...record.activePendingRequests.map((request) => request.token)
+        trailing.flatMap((record2) => [
+          ...record2.effects.interruptTokens,
+          ...record2.activePendingRequests.map((request) => request.token)
         ])
       );
       await Promise.all(trailing.map(deleteRecord));
@@ -947,19 +947,19 @@ var createSessionId = () => `session-${(0, import_node_crypto2.randomUUID)()}`;
 var createResumeToken2 = () => (0, import_node_crypto2.randomUUID)();
 var createRequestId = () => `human-${(0, import_node_crypto2.randomUUID)()}`;
 var clone2 = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
-var toSummary2 = (record) => ({
-  id: record.id,
-  sessionId: record.sessionId,
-  turnIndex: record.turnIndex,
-  createdAt: record.createdAt,
-  nodes: [...record.nodes],
-  workflow: record.workflow,
-  ...record.label ? { label: record.label } : {},
-  ...record.parentCheckpointId ? { parentCheckpointId: record.parentCheckpointId } : {},
-  ...record.parentSessionId ? { parentSessionId: record.parentSessionId } : {},
-  ...record.forkedFrom ? { forkedFrom: record.forkedFrom } : {},
-  ...record.workflowVersion ? { workflowVersion: record.workflowVersion } : {},
-  ...record.buildId ? { buildId: record.buildId } : {}
+var toSummary2 = (record2) => ({
+  id: record2.id,
+  sessionId: record2.sessionId,
+  turnIndex: record2.turnIndex,
+  createdAt: record2.createdAt,
+  nodes: [...record2.nodes],
+  workflow: record2.workflow,
+  ...record2.label ? { label: record2.label } : {},
+  ...record2.parentCheckpointId ? { parentCheckpointId: record2.parentCheckpointId } : {},
+  ...record2.parentSessionId ? { parentSessionId: record2.parentSessionId } : {},
+  ...record2.forkedFrom ? { forkedFrom: record2.forkedFrom } : {},
+  ...record2.workflowVersion ? { workflowVersion: record2.workflowVersion } : {},
+  ...record2.buildId ? { buildId: record2.buildId } : {}
 });
 var uniqueStrings2 = (values) => Array.from(
   new Set(
@@ -973,49 +973,49 @@ function createInMemorySessionCheckpointStore(options) {
   const byId = /* @__PURE__ */ new Map();
   const bySession = /* @__PURE__ */ new Map();
   const headBySession = /* @__PURE__ */ new Map();
-  const sortedRecords = (sessionId) => (bySession.get(sessionId) ?? []).map((id) => byId.get(id)).filter((record) => Boolean(record)).sort((a, b) => a.turnIndex - b.turnIndex || a.createdAt - b.createdAt);
-  const saveRecord = (record) => {
-    byId.set(record.id, clone2(record));
-    const ids = bySession.get(record.sessionId) ?? [];
-    if (!ids.includes(record.id)) ids.push(record.id);
-    bySession.set(record.sessionId, ids);
-    headBySession.set(record.sessionId, record.id);
+  const sortedRecords = (sessionId) => (bySession.get(sessionId) ?? []).map((id) => byId.get(id)).filter((record2) => Boolean(record2)).sort((a, b) => a.turnIndex - b.turnIndex || a.createdAt - b.createdAt);
+  const saveRecord = (record2) => {
+    byId.set(record2.id, clone2(record2));
+    const ids = bySession.get(record2.sessionId) ?? [];
+    if (!ids.includes(record2.id)) ids.push(record2.id);
+    bySession.set(record2.sessionId, ids);
+    headBySession.set(record2.sessionId, record2.id);
   };
-  const deleteRecord = (record) => {
-    byId.delete(record.id);
+  const deleteRecord = (record2) => {
+    byId.delete(record2.id);
     bySession.set(
-      record.sessionId,
+      record2.sessionId,
       /* v8 ignore next -- deleteRecord only receives records that came from this session index. */
-      (bySession.get(record.sessionId) ?? []).filter((id) => id !== record.id)
+      (bySession.get(record2.sessionId) ?? []).filter((id) => id !== record2.id)
     );
   };
   const prune = (sessionId) => {
     const records = sortedRecords(sessionId);
     const overflow = Math.max(0, records.length - maxCheckpointsPerSession);
-    for (const record of records.slice(0, overflow)) {
-      deleteRecord(record);
+    for (const record2 of records.slice(0, overflow)) {
+      deleteRecord(record2);
     }
   };
   const getHead = async (sessionId) => {
     const headId = headBySession.get(sessionId);
     if (!headId) return null;
-    const record = byId.get(headId);
-    return record ? clone2(record) : null;
+    const record2 = byId.get(headId);
+    return record2 ? clone2(record2) : null;
   };
   return {
     async list(sessionId) {
       return sortedRecords(sessionId).map(toSummary2);
     },
     async get(id) {
-      const record = byId.get(id);
-      return record ? clone2(record) : null;
+      const record2 = byId.get(id);
+      return record2 ? clone2(record2) : null;
     },
     getHead,
     async append(args) {
       const previousHead = await getHead(args.sessionId);
       const turnIndex = previousHead ? previousHead.turnIndex + 1 : 0;
       const pendingRequests = args.pendingRequests ?? [];
-      const record = {
+      const record2 = {
         id: createCheckpointId(),
         sessionId: args.sessionId,
         runId: args.runId,
@@ -1037,9 +1037,9 @@ function createInMemorySessionCheckpointStore(options) {
         ...args.workflowVersion ? { workflowVersion: args.workflowVersion } : {},
         ...args.buildId ? { buildId: args.buildId } : {}
       };
-      saveRecord(record);
+      saveRecord(record2);
       prune(args.sessionId);
-      return clone2(record);
+      return clone2(record2);
     },
     async rollbackTo(id) {
       const target = byId.get(id);
@@ -1052,18 +1052,18 @@ function createInMemorySessionCheckpointStore(options) {
       }
       const records = sortedRecords(target.sessionId);
       const trailing = records.filter(
-        (record) => record.turnIndex > target.turnIndex
+        (record2) => record2.turnIndex > target.turnIndex
       );
       const invalidatedStructuredStreamIds = uniqueStrings2(
-        trailing.flatMap((record) => record.effects.structuredStreamIds)
+        trailing.flatMap((record2) => record2.effects.structuredStreamIds)
       );
       const invalidatedInterruptTokens = uniqueStrings2(
-        trailing.flatMap((record) => [
-          ...record.effects.interruptTokens,
-          ...record.activePendingRequests.map((request) => request.token)
+        trailing.flatMap((record2) => [
+          ...record2.effects.interruptTokens,
+          ...record2.activePendingRequests.map((request) => request.token)
         ])
       );
-      for (const record of trailing) deleteRecord(record);
+      for (const record2 of trailing) deleteRecord(record2);
       headBySession.set(target.sessionId, target.id);
       return {
         sessionId: target.sessionId,
@@ -1221,10 +1221,11 @@ async function restoreGraphSnapshot(saver, snapshot, threadId) {
 
 // src/graph/create-execution-graph.ts
 var import_promises = require("timers/promises");
-var import_core2 = require("@kortyx/core");
+var import_core3 = require("@kortyx/core");
+var import_errors8 = require("@kortyx/core/errors");
 var import_hooks2 = require("@kortyx/hooks");
-var import_utils = require("@kortyx/utils");
-var import_langgraph2 = require("@langchain/langgraph");
+var import_utils2 = require("@kortyx/utils");
+var import_langgraph3 = require("@langchain/langgraph");
 
 // src/node-loader.ts
 var import_node_path = require("path");
@@ -1312,25 +1313,10 @@ var import_errors6 = require("@kortyx/core/errors");
 var import_hooks = require("@kortyx/hooks");
 var import_singletons = require("@langchain/core/singletons");
 var import_langgraph = require("@langchain/langgraph");
-function assertSequentialWorkflow(workflow) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const [from, , condition] of workflow.edges) {
-    const group = groups.get(from) ?? { plain: 0, conditional: 0 };
-    if (condition) group.conditional++;
-    else group.plain++;
-    groups.set(from, group);
-    if (group.plain > 1 || group.plain > 0 && group.conditional > 0) {
-      throw new import_errors6.WorkflowContractError(
-        `Workflow '${workflow.id}' has parallel edges; child calls require sequential graphs.`
-      );
-    }
-  }
-}
-function createWorkflowCallService(config, parent, execution = {}) {
+function createWorkflowCallService(config, _parent, execution = {}) {
   return async (args) => {
     const execute = async () => {
       (0, import_core.throwIfExecutionAborted)(execution.abortSignal);
-      if (parent) assertSequentialWorkflow(parent);
       const depth = (config.workflowCallDepth ?? 0) + 1;
       if (depth > 16)
         throw new import_errors6.WorkflowContractError(
@@ -1350,7 +1336,6 @@ function createWorkflowCallService(config, parent, execution = {}) {
           "The typed workflow contract does not match the registered definition."
         );
       }
-      assertSequentialWorkflow(workflow);
       const snapshot = args.snapshot;
       if (snapshot && snapshot.version !== workflow.version)
         throw new import_errors6.WorkflowContractError(
@@ -1363,6 +1348,7 @@ function createWorkflowCallService(config, parent, execution = {}) {
       let request;
       const invocationPath = `${config.invocationPath ?? "root"}/${encodeURIComponent(args.id)}:${args.invocationId}`;
       let childConfig = {
+        resume: Boolean(snapshot),
         executionBranchId: config.executionBranchId,
         prepareChildTelemetry: config.prepareChildTelemetry,
         context: config.context,
@@ -1557,34 +1543,504 @@ function createWorkflowCallService(config, parent, execution = {}) {
   };
 }
 
+// src/graph/parallel-graph.ts
+var import_core2 = require("@kortyx/core");
+var import_errors7 = require("@kortyx/core/errors");
+var import_utils = require("@kortyx/utils");
+var import_langgraph2 = require("@langchain/langgraph");
+var WORK = "__kortyx_parallel_work";
+var WAIT = "__kortyx_parallel_wait";
+var FINISH = "__kortyx_parallel_finish";
+var KEY = "__kortyxParallelGraph";
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var clone3 = (value) => JSON.parse(JSON.stringify(value));
+var zeroUsage = () => ({ input: 0, output: 0, total: 0 });
+function hasParallelEdges(workflow) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const [from, , condition] of workflow.edges) {
+    const group = groups.get(from) ?? { plain: 0, conditional: 0 };
+    if (condition?.when) group.conditional++;
+    else group.plain++;
+    groups.set(from, group);
+    if (group.plain > 1 || group.plain && group.conditional) return true;
+  }
+  return false;
+}
+function addParallelGraphCoordinator(builder, workflow, config, execution, executors) {
+  const ids = [...Object.keys(workflow.nodes), "__end__"];
+  const incoming = new Map(ids.map((id) => [id, []]));
+  const outgoing = /* @__PURE__ */ new Map();
+  for (const [from, to, condition] of workflow.edges) {
+    if (from === "__end__" || to === "__start__" || from !== "__start__" && !Object.hasOwn(workflow.nodes, from) || !incoming.has(to))
+      throw new import_errors7.WorkflowContractError(
+        `Invalid parallel graph edge '${from}' \u2192 '${to}'.`
+      );
+    if (!incoming.get(to)?.includes(from)) incoming.get(to)?.push(from);
+    const edges = outgoing.get(from) ?? [];
+    if (!edges.some((edge) => edge.to === to && edge.when === condition?.when))
+      edges.push({ to, ...condition ? { when: condition.when } : {} });
+    outgoing.set(from, edges);
+  }
+  const ancestors = /* @__PURE__ */ new Map([["__start__", /* @__PURE__ */ new Set()]]);
+  const remaining = new Set(ids);
+  const ordered = [];
+  while (remaining.size) {
+    const ready = [...remaining].filter(
+      (id) => incoming.get(id)?.every((from) => ancestors.has(from))
+    );
+    if (!ready.length)
+      throw new import_errors7.KortyxError(
+        "GRAPH_CYCLE",
+        "Parallel graph back-edges are not supported: use a sequential child workflow for loops.",
+        {
+          category: "workflow",
+          retryable: false,
+          safeMessage: "Parallel graph back-edges are not supported: use a sequential child workflow for loops."
+        }
+      );
+    for (const id of ready) {
+      const parents = incoming.get(id) ?? [];
+      ancestors.set(
+        id,
+        new Set(
+          parents.flatMap((from) => [from, ...ancestors.get(from) ?? []])
+        )
+      );
+      remaining.delete(id);
+      ordered.push(id);
+    }
+  }
+  ids.splice(0, ids.length, ...ordered);
+  const failure = (code, message, node, cause) => new import_errors7.KortyxError(code, message, {
+    category: "workflow",
+    retryable: false,
+    safeMessage: message,
+    context: { workflow: workflow.id, node },
+    ...cause ? { cause } : {}
+  });
+  const mergeFields = (parents, node, property, journal) => {
+    const merged = {};
+    for (const parent of parents) {
+      for (const [key, field] of Object.entries(parent[property])) {
+        const previous = Object.hasOwn(merged, key) ? merged[key] : void 0;
+        if (previous && previous.writer !== field.writer) {
+          if (journal.nodes[previous.writer]?.ancestors.includes(field.writer))
+            continue;
+          if (!journal.nodes[field.writer]?.ancestors.includes(previous.writer))
+            throw failure(
+              "GRAPH_OUTPUT_CONFLICT",
+              `Node '${node}' cannot combine ${property === "fields" ? "data" : property === "workflowFields" ? "workflow state" : "runtime"} field '${key}': branches '${previous.writer}' and '${field.writer}' both wrote it. Return separate fields in application logic.`,
+              node
+            );
+        }
+        Object.defineProperty(merged, key, {
+          value: field,
+          enumerable: true,
+          configurable: true,
+          writable: true
+        });
+      }
+    }
+    return merged;
+  };
+  const values = (fields) => Object.fromEntries(
+    Object.entries(fields).map(([key, field]) => [key, field.value])
+  );
+  const initialWorkflowState = (journal) => {
+    const internal = journal.initialRuntime.__kortyx;
+    return record(internal) && record(internal.workflowState) ? internal.workflowState : {};
+  };
+  const usage = (journal) => {
+    const total = {
+      ...zeroUsage(),
+      ...journal.initialRuntime.tokenUsage
+    };
+    for (const node of Object.values(journal.nodes)) {
+      const used = node.runtime.tokenUsage;
+      if (used)
+        for (const key of ["input", "output", "total"])
+          total[key] += used[key] ?? 0;
+    }
+    return total;
+  };
+  const runtimePatch = (journal) => ({
+    [KEY]: journal,
+    tokenUsage: usage(journal)
+  });
+  const load = (state) => {
+    const saved = state.runtime[KEY];
+    if (saved && (config.resume === true || !config.executionRunId || saved.runId === config.executionRunId)) {
+      const journal = clone3(saved);
+      if (journal.version !== 1 || journal.workflowVersion !== workflow.version)
+        throw new import_errors7.WorkflowContractError(
+          "Parallel workflow changed since its execution was suspended."
+        );
+      return journal;
+    }
+    const initialRuntime = clone3(state.runtime);
+    delete initialRuntime[KEY];
+    return {
+      version: 1,
+      runId: config.executionRunId,
+      workflowVersion: workflow.version,
+      initialInput: state.input,
+      initialData: clone3(state.data ?? {}),
+      initialRuntime,
+      nodes: Object.fromEntries(
+        ids.map((id) => [
+          id,
+          {
+            id,
+            ancestors: [],
+            status: "pending",
+            responses: [],
+            runtime: {},
+            fields: {},
+            workflowFields: {},
+            runtimeFields: {},
+            selected: []
+          }
+        ])
+      )
+    };
+  };
+  const terminal = (node) => ["completed", "failed", "skipped"].includes(node.status);
+  builder.addNode(WORK, async (state) => {
+    const journal = load(state);
+    let control;
+    const running = /* @__PURE__ */ new Map();
+    for (const node of Object.values(journal.nodes))
+      if (node.status === "limited") node.status = "pending";
+    const start = async (id, parents) => {
+      const node = journal.nodes[id];
+      let privateState;
+      try {
+        node.ancestors = [
+          ...new Set(
+            parents.flatMap((parent) => [parent.id, ...parent.ancestors])
+          )
+        ];
+        const failed = parents.find((parent) => parent.status === "failed");
+        if (failed)
+          throw failure(
+            "GRAPH_DEPENDENCY_FAILED",
+            `Node '${id}' did not run because required dependency '${failed.id}' failed.`,
+            id,
+            failed.failure
+          );
+        node.fields = mergeFields(parents, id, "fields", journal);
+        node.workflowFields = mergeFields(
+          parents,
+          id,
+          "workflowFields",
+          journal
+        );
+        node.runtimeFields = mergeFields(parents, id, "runtimeFields", journal);
+        if (id === "__end__") {
+          node.status = "completed";
+          return;
+        }
+        const data = (0, import_utils.deepMergeWithArrayOverwrite)(
+          journal.initialData,
+          values(node.fields)
+        );
+        const nodeInput = Object.keys(node.fields).length ? (0, import_utils.deepMergeWithArrayOverwrite)(
+          record(journal.initialInput) ? journal.initialInput : { rawInput: journal.initialInput },
+          values(node.fields)
+        ) : journal.initialInput;
+        const workflowState = (0, import_utils.deepMergeWithArrayOverwrite)(
+          initialWorkflowState(journal),
+          values(node.workflowFields)
+        );
+        const ownInternal = node.runtime.__kortyx;
+        const inheritedRuntime = (0, import_utils.deepMergeWithArrayOverwrite)(
+          journal.initialRuntime,
+          values(node.runtimeFields)
+        );
+        privateState = {
+          ...state,
+          input: nodeInput === void 0 ? void 0 : clone3(nodeInput),
+          data: clone3(data),
+          runtime: clone3({
+            ...inheritedRuntime,
+            tokenUsage: zeroUsage(),
+            ...node.runtime,
+            __kortyx: {
+              ...record(ownInternal) ? ownInternal : {},
+              workflowState: record(ownInternal) && record(ownInternal.workflowState) ? ownInternal.workflowState : workflowState
+            }
+          }),
+          conversationHistory: [],
+          awaitingHumanInput: false
+        };
+        let index = 0;
+        node.status = "running";
+        const updates = await executors[id](
+          privateState,
+          (request) => {
+            const position = index++;
+            if (position < node.responses.length)
+              return node.responses[position];
+            node.request = request;
+            throw new import_langgraph2.GraphInterrupt([]);
+          },
+          (nodeState) => {
+            const snapshot = clone3(journal);
+            snapshot.nodes[id].runtime = clone3(
+              nodeState.runtime
+            );
+            for (const activation of Object.values(snapshot.nodes))
+              if (activation.status === "running")
+                activation.status = "pending";
+            return {
+              ...state,
+              lastNode: id,
+              input: nodeState.input,
+              data: nodeState.data ?? {},
+              conversationHistory: [
+                ...state.conversationHistory,
+                ...ids.flatMap(
+                  (nodeId) => snapshot.nodes[nodeId]?.history ?? []
+                )
+              ],
+              runtime: { ...nodeState.runtime, ...runtimePatch(snapshot) }
+            };
+          }
+        );
+        node.runtime = updates.runtime ?? privateState.runtime;
+        const delta = updates.__kortyxNodeData;
+        const updatedData = updates.data;
+        for (const key of Object.keys(delta))
+          Object.defineProperty(node.fields, key, {
+            value: { writer: id, value: updatedData?.[key] },
+            enumerable: true,
+            configurable: true,
+            writable: true
+          });
+        const internal = node.runtime.__kortyx;
+        for (const [key, value] of Object.entries(node.runtime)) {
+          if ([KEY, "__kortyx", "tokenUsage"].includes(key)) continue;
+          if (JSON.stringify(value) !== JSON.stringify(inheritedRuntime[key]))
+            Object.defineProperty(node.runtimeFields, key, {
+              value: { writer: id, value },
+              enumerable: true,
+              configurable: true,
+              writable: true
+            });
+        }
+        const updatedWorkflow = record(internal) && record(internal.workflowState) ? internal.workflowState : {};
+        for (const [key, value] of Object.entries(updatedWorkflow)) {
+          if (JSON.stringify(value) !== JSON.stringify(workflowState[key]))
+            Object.defineProperty(node.workflowFields, key, {
+              value: { writer: id, value },
+              enumerable: true,
+              configurable: true,
+              writable: true
+            });
+        }
+        node.history = updates.conversationHistory ?? [];
+        node.selected = (outgoing.get(id) ?? []).filter(
+          (edge) => !edge.when || edge.when === (updates.lastCondition ?? updates.lastIntent)
+        ).map((edge) => edge.to);
+        node.status = "completed";
+        delete node.request;
+      } catch (error) {
+        const patch = error?.__kortyxHookStatePatch;
+        if (privateState) node.runtime = { ...privateState.runtime, ...patch };
+        if ((0, import_langgraph2.isGraphInterrupt)(error)) node.status = "waiting";
+        else if ((0, import_core2.isExecutionLimitReached)(error)) {
+          node.status = "limited";
+          control ??= error;
+        } else if ((0, import_core2.isExecutionCancelled)(error) || execution.abortSignal?.aborted) {
+          control ??= error;
+        } else if ((0, import_errors7.serializeFailure)(error).category === "persistence")
+          control ??= error;
+        else {
+          node.failure = (0, import_errors7.serializeFailure)(error);
+          node.failure.context = {
+            ...node.failure.context,
+            node: id,
+            workflow: workflow.id
+          };
+          node.status = "failed";
+          node.selected = (outgoing.get(id) ?? []).map((edge) => edge.to);
+        }
+      }
+    };
+    const launch = () => {
+      if (control || execution.abortSignal?.aborted) return;
+      for (const id of ids) {
+        if (id === "__end__") continue;
+        const node = journal.nodes[id];
+        if (node.status !== "pending" || running.has(id)) continue;
+        const sources = incoming.get(id) ?? [];
+        if (!sources.every(
+          (from) => from === "__start__" || terminal(journal.nodes[from])
+        ))
+          continue;
+        const activeSources = sources.filter(
+          (from) => from === "__start__" ? (outgoing.get(from) ?? []).some(
+            (edge) => edge.to === id && (!edge.when || edge.when === (state.lastCondition ?? state.lastIntent))
+          ) : journal.nodes[from]?.selected.includes(id)
+        );
+        if (!activeSources.length) {
+          node.status = "skipped";
+          continue;
+        }
+        const task = start(
+          id,
+          activeSources.filter((from) => from !== "__start__").map((from) => journal.nodes[from])
+        );
+        running.set(
+          id,
+          task.finally(() => running.delete(id))
+        );
+      }
+    };
+    try {
+      while (true) {
+        launch();
+        if (!running.size) break;
+        await Promise.race(running.values());
+      }
+      (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+      if (control) throw control;
+    } catch (error) {
+      await Promise.allSettled(running.values());
+      if (error && typeof error === "object")
+        Object.assign(error, { __kortyxHookStatePatch: runtimePatch(journal) });
+      throw error;
+    }
+    journal.waitingNode = ids.find(
+      (id) => journal.nodes[id]?.status === "waiting"
+    );
+    if (!journal.waitingNode) {
+      const leaves = ids.filter(
+        (id) => id !== "__end__" && journal.nodes[id]?.status !== "skipped" && !journal.nodes[id]?.selected.some((to) => to !== "__end__")
+      );
+      await start(
+        "__end__",
+        leaves.map((id) => journal.nodes[id])
+      );
+    }
+    const end = journal.nodes.__end__;
+    return {
+      runtime: {
+        ...end.status === "completed" ? values(end.runtimeFields) : {},
+        ...runtimePatch(journal)
+      },
+      ...end.status === "completed" ? {
+        input: Object.keys(end.fields).length ? (0, import_utils.deepMergeWithArrayOverwrite)(
+          record(journal.initialInput) ? journal.initialInput : { rawInput: journal.initialInput },
+          values(end.fields)
+        ) : journal.initialInput,
+        data: (0, import_utils.deepMergeWithArrayOverwrite)(
+          journal.initialData,
+          values(end.fields)
+        ),
+        conversationHistory: ids.flatMap(
+          (id) => journal.nodes[id]?.history ?? []
+        )
+      } : {}
+    };
+  });
+  builder.addNode(WAIT, (state) => {
+    const journal = load(state);
+    const id = journal.waitingNode;
+    const node = id ? journal.nodes[id] : void 0;
+    if (!id || !node?.request)
+      throw new import_errors7.WorkflowContractError("Missing waiting parallel node.");
+    const request = {
+      ...node.request,
+      meta: {
+        ...node.request.meta,
+        __kortyxResumeStatePatch: runtimePatch(journal)
+      }
+    };
+    let response;
+    try {
+      response = (0, import_langgraph2.interrupt)(request);
+    } catch (error) {
+      config.emit?.("interrupt", {
+        node: id,
+        workflow: workflow.id,
+        input: request
+      });
+      throw error;
+    }
+    node.responses.push(response);
+    node.status = "pending";
+    delete journal.waitingNode;
+    return { runtime: runtimePatch(journal) };
+  });
+  builder.addNode(FINISH, (state) => {
+    const journal = load(state);
+    const failed = ids.filter((id) => journal.nodes[id]?.status === "failed");
+    if (failed.length) {
+      const relevant = [...failed].reverse().find((id) => id !== "__end__") ?? failed[0];
+      const detail = journal.nodes[relevant]?.failure;
+      const error = (0, import_errors7.errorFromFailure)({
+        ...detail,
+        results: failed.map((id) => ({
+          status: "rejected",
+          failure: journal.nodes[id]?.failure
+        }))
+      });
+      Object.assign(error, { __kortyxHookStatePatch: runtimePatch(journal) });
+      throw error;
+    }
+    return {
+      runtime: {
+        [KEY]: null,
+        __kortyx: {
+          workflowState: (0, import_utils.deepMergeWithArrayOverwrite)(
+            initialWorkflowState(journal),
+            values(journal.nodes.__end__?.workflowFields ?? {})
+          )
+        }
+      }
+    };
+  });
+  builder.addEdge("__start__", WORK);
+  builder.addConditionalEdges(
+    WORK,
+    (state) => load(state).waitingNode ? "wait" : "finish",
+    { wait: WAIT, finish: FINISH }
+  );
+  builder.addEdge(WAIT, WORK);
+  builder.addEdge(FINISH, "__end__");
+}
+
 // src/graph/create-execution-graph.ts
 async function createExecutionGraph(workflow, config, execution = {}) {
-  const StateAnnotation = import_langgraph2.Annotation.Root({
-    currentWorkflow: import_langgraph2.Annotation,
-    input: import_langgraph2.Annotation,
-    output: import_langgraph2.Annotation,
-    lastNode: import_langgraph2.Annotation,
-    lastCondition: import_langgraph2.Annotation,
-    lastIntent: import_langgraph2.Annotation,
-    runtime: (0, import_langgraph2.Annotation)({
-      reducer: (l, r) => (0, import_utils.deepMergeWithArrayOverwrite)(l ?? {}, r ?? {}),
+  const StateAnnotation = import_langgraph3.Annotation.Root({
+    currentWorkflow: import_langgraph3.Annotation,
+    input: import_langgraph3.Annotation,
+    output: import_langgraph3.Annotation,
+    lastNode: import_langgraph3.Annotation,
+    lastCondition: import_langgraph3.Annotation,
+    lastIntent: import_langgraph3.Annotation,
+    runtime: (0, import_langgraph3.Annotation)({
+      reducer: (l, r) => (0, import_utils2.deepMergeWithArrayOverwrite)(l ?? {}, r ?? {}),
       default: () => ({})
     }),
-    config: import_langgraph2.Annotation,
-    transitionTo: import_langgraph2.Annotation,
-    data: (0, import_langgraph2.Annotation)({
-      reducer: (l, r) => (0, import_utils.deepMergeWithArrayOverwrite)(l ?? {}, r ?? {}),
+    config: import_langgraph3.Annotation,
+    transitionTo: import_langgraph3.Annotation,
+    data: (0, import_langgraph3.Annotation)({
+      reducer: (l, r) => (0, import_utils2.deepMergeWithArrayOverwrite)(l ?? {}, r ?? {}),
       default: () => ({})
     }),
-    conversationHistory: (0, import_langgraph2.Annotation)({
+    conversationHistory: (0, import_langgraph3.Annotation)({
       reducer: (l, r) => [...l ?? [], ...r ?? []],
       default: () => []
     }),
-    awaitingHumanInput: import_langgraph2.Annotation
+    awaitingHumanInput: import_langgraph3.Annotation
   });
-  const builder = new import_langgraph2.StateGraph(StateAnnotation);
+  const builder = new import_langgraph3.StateGraph(StateAnnotation);
   const edgeApi = builder;
   const workflowName = workflow.id;
+  const parallelGraph = hasParallelEdges(workflow);
+  const nodeExecutors = {};
   const runtimeConfig = config;
   if (!runtimeConfig.emit) {
     runtimeConfig.emit = () => {
@@ -1626,22 +2082,32 @@ async function createExecutionGraph(workflow, config, execution = {}) {
       nodeDef.behavior ?? void 0
     );
     const behavior = nodeConfig.behavior ?? {};
-    builder.addNode(nodeId, async (state) => {
-      (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+    const executeNode = async (state, awaitInput, snapshotGraph) => {
+      (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
       const emitRuntimeEvent = (event, payload) => {
         runtimeConfig.emit(event, payload);
       };
+      if (awaitInput)
+        emitRuntimeEvent("status", {
+          node: nodeId,
+          message: `Processing node: ${nodeId}`
+        });
       let suspension;
       let deniedAdmission;
       const hookNodeContext = {
-        completeResponse: runtimeConfig.workflowCallDepth ? void 0 : execution.completeResponse,
+        completeResponse: runtimeConfig.workflowCallDepth ? void 0 : execution.completeResponse ? async (options, nodeState) => {
+          await execution.completeResponse?.(
+            options,
+            snapshotGraph ? snapshotGraph(nodeState) : nodeState
+          );
+        } : void 0,
         abortSignal: execution.abortSignal,
         consumeExecution: (limit) => {
-          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+          (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
           if (suspension) throw suspension;
           try {
             if (execution.budget)
-              (0, import_core2.consumeExecutionBudget)(execution.budget, limit);
+              (0, import_core3.consumeExecutionBudget)(execution.budget, limit);
           } catch (error) {
             deniedAdmission = error;
             throw error;
@@ -1669,8 +2135,8 @@ async function createExecutionGraph(workflow, config, execution = {}) {
         config: nodeConfig,
         emit: emitRuntimeEvent,
         awaitInterrupt: (interruptConfig) => {
-          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
-          if (execution.budget) (0, import_core2.assertExecutionBudget)(execution.budget);
+          (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
+          if (execution.budget) (0, import_core3.assertExecutionBudget)(execution.budget);
           const { kind, question } = interruptConfig;
           const isMulti = kind === "multi-choice" || interruptConfig.kind !== "text" && interruptConfig.multiple === true;
           const sharedInterruptFields = {
@@ -1692,14 +2158,15 @@ async function createExecutionGraph(workflow, config, execution = {}) {
           };
           let resumed;
           try {
-            resumed = (0, import_langgraph2.interrupt)(payload);
+            resumed = awaitInput ? awaitInput(payload) : (0, import_langgraph3.interrupt)(payload);
           } catch (error) {
             suspension = error;
-            emitRuntimeEvent("interrupt", {
-              node: nodeId,
-              workflow: workflowName,
-              input: payload
-            });
+            if (!awaitInput)
+              emitRuntimeEvent("interrupt", {
+                node: nodeId,
+                workflow: workflowName,
+                input: payload
+              });
             throw error;
           }
           if (isMulti) {
@@ -1728,11 +2195,11 @@ async function createExecutionGraph(workflow, config, execution = {}) {
       let retryHookRuntime = null;
       while (attempt < maxAttempts) {
         try {
-          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+          (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
           attempt++;
           const attemptState = retryHookRuntime && typeof retryHookRuntime === "object" ? {
             ...state,
-            runtime: (0, import_utils.deepMergeWithArrayOverwrite)(
+            runtime: (0, import_utils2.deepMergeWithArrayOverwrite)(
               state.runtime ?? {},
               retryHookRuntime
             )
@@ -1750,12 +2217,12 @@ async function createExecutionGraph(workflow, config, execution = {}) {
                 input: state.input,
                 params: nodeParams ?? {}
               });
-              (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+              (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
               if (deniedAdmission) throw deniedAdmission;
               if (suspension) throw suspension;
               return result;
             } catch (error) {
-              (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+              (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
               if (deniedAdmission) throw deniedAdmission;
               throw error;
             }
@@ -1794,21 +2261,21 @@ async function createExecutionGraph(workflow, config, execution = {}) {
         } catch (err) {
           const patch = err?.__kortyxHookStatePatch;
           if (patch && typeof patch === "object") {
-            state.runtime = (0, import_utils.deepMergeWithArrayOverwrite)(
+            state.runtime = (0, import_utils2.deepMergeWithArrayOverwrite)(
               state.runtime ?? {},
               patch
             );
-            retryHookRuntime = (0, import_utils.deepMergeWithArrayOverwrite)(
+            retryHookRuntime = (0, import_utils2.deepMergeWithArrayOverwrite)(
               retryHookRuntime ?? {},
               patch
             );
           }
-          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
-          if ((0, import_core2.isExecutionLimitReached)(err)) {
+          (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
+          if ((0, import_core3.isExecutionLimitReached)(err)) {
             Object.assign(err, { nodeId, workflowId: workflowName });
             throw err;
           }
-          if ((0, import_core2.isExecutionCancelled)(err) || (0, import_langgraph2.isGraphInterrupt)(err)) throw err;
+          if ((0, import_core3.isExecutionCancelled)(err) || (0, import_langgraph3.isGraphInterrupt)(err)) throw err;
           const hasMore = attempt < maxAttempts;
           const delayMs = behavior.retry?.delayMs ?? 0;
           if (hasMore && delayMs > 0) {
@@ -1818,12 +2285,12 @@ async function createExecutionGraph(workflow, config, execution = {}) {
           if (!hasMore) throw err;
         }
       }
-      (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+      (0, import_core3.throwIfExecutionAborted)(execution.abortSignal);
       const res = nodeResult ?? {};
       if (hookRuntimeUpdates) {
         res.infra = {
           ...res.infra ?? {},
-          runtime: (0, import_utils.deepMergeWithArrayOverwrite)(
+          runtime: (0, import_utils2.deepMergeWithArrayOverwrite)(
             (res.infra?.runtime ?? {}) || {},
             hookRuntimeUpdates
           )
@@ -1835,6 +2302,19 @@ async function createExecutionGraph(workflow, config, execution = {}) {
         emitRuntimeEvent("message", { node: nodeId, content: uiMessage });
       }
       if (res.transitionTo) {
+        if (awaitInput)
+          throw Object.assign(
+            new import_errors8.KortyxError(
+              "GRAPH_BRANCH_HANDOFF",
+              "transitionTo cannot hand off from a parallel branch; useWorkflow returns to its caller.",
+              {
+                category: "workflow",
+                retryable: false,
+                safeMessage: "transitionTo cannot hand off from a parallel branch; useWorkflow returns to its caller."
+              }
+            ),
+            { __kortyxHookStatePatch: hookRuntimeUpdates }
+          );
         emitRuntimeEvent("transition", {
           node: nodeId,
           workflow: workflowName,
@@ -1847,17 +2327,17 @@ async function createExecutionGraph(workflow, config, execution = {}) {
         updates.lastCondition = res.condition;
       if (typeof res.intent === "string") updates.lastIntent = res.intent;
       if (res.data && typeof res.data === "object") {
-        updates.input = (0, import_utils.deepMergeWithArrayOverwrite)(
+        updates.input = (0, import_utils2.deepMergeWithArrayOverwrite)(
           toRecordInput(state.input),
           res.data
         );
-        updates.data = (0, import_utils.deepMergeWithArrayOverwrite)(
+        updates.data = (0, import_utils2.deepMergeWithArrayOverwrite)(
           state.data ?? {},
           res.data
         );
       }
       if (res.infra?.runtime && typeof res.infra.runtime === "object") {
-        updates.runtime = (0, import_utils.deepMergeWithArrayOverwrite)(
+        updates.runtime = (0, import_utils2.deepMergeWithArrayOverwrite)(
           state.runtime ?? {},
           res.infra.runtime
         );
@@ -1865,7 +2345,7 @@ async function createExecutionGraph(workflow, config, execution = {}) {
       if (res.ui) {
         updates.ui = {
           message: typeof res.ui.message === "string" ? res.ui.message : state.ui?.message ?? "",
-          structured: (0, import_utils.deepMergeWithArrayOverwrite)(
+          structured: (0, import_utils2.deepMergeWithArrayOverwrite)(
             state.ui?.structured ?? {},
             res.ui.structured ?? {}
           )
@@ -1890,8 +2370,20 @@ async function createExecutionGraph(workflow, config, execution = {}) {
           data: payload
         });
       }
+      if (awaitInput) updates.__kortyxNodeData = res.data ?? {};
+      if (awaitInput)
+        emitRuntimeEvent("status", {
+          node: nodeId,
+          message: `\u2705 Completed node: ${nodeId}`
+        });
       return updates;
+    };
+    Object.defineProperty(nodeExecutors, nodeId, {
+      value: executeNode,
+      enumerable: true
     });
+    if (!parallelGraph)
+      builder.addNode(nodeId, (state) => executeNode(state));
   }
   const condGroups = {};
   const plainEdges = [];
@@ -1904,26 +2396,36 @@ async function createExecutionGraph(workflow, config, execution = {}) {
       plainEdges.push([from, to]);
     }
   }
-  for (const [from, to] of plainEdges) {
-    edgeApi.addEdge(from, to);
-  }
-  for (const [from, rules] of Object.entries(condGroups)) {
-    const mapping = Object.fromEntries(
-      rules.map((r) => [r.when, r.to])
-    );
-    const fallbackKey = `__default__:${from}`;
-    mapping[fallbackKey] = "__end__";
-    edgeApi.addConditionalEdges(
-      from,
-      (s) => {
-        const trigger = s.lastCondition ?? s.lastIntent;
-        if (trigger && Object.hasOwn(mapping, trigger)) {
-          return trigger;
-        }
-        return fallbackKey;
-      },
-      mapping
+  if (parallelGraph) {
+    addParallelGraphCoordinator(
+      builder,
+      workflow,
+      runtimeConfig,
+      execution,
+      nodeExecutors
     );
+  } else {
+    for (const [from, to] of plainEdges) {
+      edgeApi.addEdge(from, to);
+    }
+    for (const [from, rules] of Object.entries(condGroups)) {
+      const mapping = Object.fromEntries(
+        rules.map((r) => [r.when, r.to])
+      );
+      const fallbackKey = `__default__:${from}`;
+      mapping[fallbackKey] = "__end__";
+      edgeApi.addConditionalEdges(
+        from,
+        (s) => {
+          const trigger = s.lastCondition ?? s.lastIntent;
+          if (trigger && Object.hasOwn(mapping, trigger)) {
+            return trigger;
+          }
+          return fallbackKey;
+        },
+        mapping
+      );
+    }
   }
   const sessionId = typeof config.session === "object" && config.session && "id" in config.session && typeof config.session.id === "string" ? config.session.id : "__default__";
   const checkpointer = config.checkpointer ?? getCheckpointer(sessionId);
@@ -1959,8 +2461,8 @@ function makeRequestId(prefix = "req") {
 // src/registry/file-registry.ts
 var import_promises2 = require("fs/promises");
 var import_node_path2 = require("path");
-var import_core3 = require("@kortyx/core");
-var import_errors7 = require("@kortyx/core/errors");
+var import_core4 = require("@kortyx/core");
+var import_errors9 = require("@kortyx/core/errors");
 var DEFAULT_EXTENSIONS = [
   ".workflow.ts",
   ".workflow.mts",
@@ -1992,7 +2494,7 @@ function createFileWorkflowRegistry(options) {
         const modulePath = (0, import_node_path2.join)(workflowsDir, file);
         if (isDeclarativeWorkflowFile(file)) {
           const raw = await (0, import_promises2.readFile)(modulePath, "utf8");
-          const workflow = (0, import_core3.loadWorkflow)(raw);
+          const workflow = (0, import_core4.loadWorkflow)(raw);
           workflow.metadata = {
             ...workflow.metadata ?? {},
             __filePath: modulePath
@@ -2034,7 +2536,7 @@ function createFileWorkflowRegistry(options) {
     const fallback = selectOptions?.fallbackId ?? fallbackId;
     const selected = workflows[id] ?? (fallback ? workflows[fallback] : null);
     if (!selected) {
-      throw new import_errors7.KortyxError(
+      throw new import_errors9.KortyxError(
         "UNKNOWN_WORKFLOW",
         `No workflow found for id "${id}" and no fallback "${fallback}" workflow available`,
         {
@@ -2059,7 +2561,7 @@ function createFileWorkflowRegistry(options) {
 }
 
 // src/registry/in-memory-registry.ts
-var import_errors8 = require("@kortyx/core/errors");
+var import_errors10 = require("@kortyx/core/errors");
 function createInMemoryWorkflowRegistry(workflows, options) {
   const byId = /* @__PURE__ */ new Map();
   for (const wf of workflows) byId.set(wf.id, wf);
@@ -2075,7 +2577,7 @@ function createInMemoryWorkflowRegistry(workflows, options) {
       const fallback = selectOptions?.fallbackId ?? fallbackId;
       const wf = byId.get(id) ?? (fallback ? byId.get(fallback) : void 0);
       if (!wf) {
-        throw new import_errors8.KortyxError(
+        throw new import_errors10.KortyxError(
           "UNKNOWN_WORKFLOW",
           `Workflow "${id}" not found${fallback ? ` (fallback "${fallback}" missing too)` : ""}.`,
           {