@kortyx/runtime 0.11.1 → 0.14.0

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   buildInitialGraphState: () => buildInitialGraphState,
+  captureGraphSnapshot: () => captureGraphSnapshot,
   clearRegisteredNodes: () => clearRegisteredNodes,
   createExecutionGraph: () => createExecutionGraph,
   createFileWorkflowRegistry: () => createFileWorkflowRegistry,
@@ -35,7 +36,8 @@ __export(index_exports, {
   makeRequestId: () => makeRequestId,
   makeResumeToken: () => makeResumeToken,
   registerNode: () => registerNode,
-  resolveNode: () => resolveNode
+  resolveNode: () => resolveNode,
+  restoreGraphSnapshot: () => restoreGraphSnapshot
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -100,7 +102,7 @@ function createInMemoryCheckpointSaver(options) {
           }
         };
       }
-      return tuple;
+      return JSON.parse(JSON.stringify(tuple));
     },
     async *list(_config, _options) {
     },
@@ -195,6 +197,12 @@ function createInMemoryPendingRequestStore() {
     }
   };
   return {
+    async take(token) {
+      prune();
+      const record = store.get(token);
+      store.delete(token);
+      return record ? JSON.parse(JSON.stringify(record)) : null;
+    },
     async save(rec) {
       prune();
       store.set(rec.token, rec);
@@ -219,6 +227,12 @@ function createRedisPendingRequestStore(options) {
   const prefix = options.prefix ?? "kortyx:pending:";
   const key = (token) => `${prefix}${token}`;
   return {
+    ...options.store.take ? {
+      take: async (token) => {
+        const raw = await options.store.take(key(token));
+        return raw ? JSON.parse(raw) : null;
+      }
+    } : {},
     async save(rec) {
       await options.store.set(key(rec.token), JSON.stringify(rec), rec.ttlMs);
     },
@@ -586,6 +600,11 @@ function createRedisFrameworkStore(options) {
   const prefix = options.prefix ?? "kortyx:fw:";
   const k = (key) => `${prefix}${key}`;
   return {
+    async take(key) {
+      const r = await client.command("GETDEL", [k(key)]);
+      if (isRedisError(r)) throw new Error(`Redis GETDEL error: ${r.message}`);
+      return typeof r === "string" ? r : null;
+    },
     async get(key) {
       const r = await client.command("GET", [k(key)]);
       if (r === null) return null;
@@ -828,8 +847,12 @@ function createRedisSessionCheckpointStore(options) {
       if (!source) throw new Error(`Checkpoint "${id}" not found.`);
       const sessionId = options2?.newSessionId || createId("session");
       const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone(source);
+      const runId = source.activePendingRequests.some(
+        (request) => request.graphSnapshot
+      ) ? `run-${(0, import_node_crypto.randomUUID)()}` : source.runId;
       const forked = {
         ...sourceRecord,
+        runId,
         id: createId("cp"),
         sessionId,
         parentSessionId: source.sessionId,
@@ -837,6 +860,7 @@ function createRedisSessionCheckpointStore(options) {
         activePendingRequests: clone(source.activePendingRequests).map(
           (request) => ({
             ...request,
+            runId,
             token: createResumeToken(),
             requestId: createId("human"),
             sessionId
@@ -991,8 +1015,12 @@ function createInMemorySessionCheckpointStore(options) {
       }
       const sessionId = options2?.newSessionId || createSessionId();
       const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone2(source);
+      const runId = source.activePendingRequests.some(
+        (request) => request.graphSnapshot
+      ) ? `run-${(0, import_node_crypto2.randomUUID)()}` : source.runId;
       const forked = {
         ...sourceRecord,
+        runId,
         id: createCheckpointId(),
         sessionId,
         parentSessionId: source.sessionId,
@@ -1000,6 +1028,7 @@ function createInMemorySessionCheckpointStore(options) {
         activePendingRequests: clone2(source.activePendingRequests).map(
           (request) => ({
             ...request,
+            runId,
             token: createResumeToken2(),
             requestId: createRequestId(),
             sessionId
@@ -1089,10 +1118,44 @@ function createFrameworkAdapterFromEnv(env = process.env) {
   return createInMemoryFrameworkAdapter({ ...ttlMs ? { ttlMs } : {} });
 }
 
+// src/framework/graph-snapshot.ts
+async function captureGraphSnapshot(saver, threadId, checkpointId) {
+  const tuple = await saver.getTuple({
+    configurable: {
+      thread_id: threadId,
+      checkpoint_ns: "",
+      ...checkpointId ? { checkpoint_id: checkpointId } : {}
+    }
+  });
+  return tuple ? JSON.parse(JSON.stringify(tuple)) : void 0;
+}
+async function restoreGraphSnapshot(saver, snapshot, threadId) {
+  const copy = JSON.parse(JSON.stringify(snapshot));
+  const config = await saver.put(
+    { configurable: { thread_id: threadId, checkpoint_ns: "" } },
+    copy.checkpoint,
+    copy.metadata,
+    copy.checkpoint.channel_versions
+  );
+  const reset = saver;
+  if (reset.deleteCheckpointWrites)
+    await reset.deleteCheckpointWrites(threadId, "", copy.checkpoint.id);
+  const writes = /* @__PURE__ */ new Map();
+  for (const [task, channel, value] of copy.pendingWrites ?? []) {
+    const group = writes.get(task) ?? [];
+    group.push([channel, value]);
+    writes.set(task, group);
+  }
+  for (const [task, group] of writes)
+    await saver.putWrites(config, group, task);
+}
+
 // src/graph/create-execution-graph.ts
-var import_hooks = require("@kortyx/hooks");
+var import_promises = require("timers/promises");
+var import_core2 = require("@kortyx/core");
+var import_hooks2 = require("@kortyx/hooks");
 var import_utils = require("@kortyx/utils");
-var import_langgraph = require("@langchain/langgraph");
+var import_langgraph2 = require("@langchain/langgraph");
 
 // src/node-loader.ts
 var import_node_path = require("path");
@@ -1174,31 +1237,250 @@ async function resolveNodeHandler(args) {
   return resolveNode(run);
 }
 
+// src/graph/call-workflow.ts
+var import_core = require("@kortyx/core");
+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 Error(
+        `Workflow '${workflow.id}' has parallel edges; child calls require sequential graphs.`
+      );
+    }
+  }
+}
+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 Error("Maximum child workflow depth (16) exceeded.");
+      const workflow = await config.selectWorkflow?.(args.workflow);
+      if (!workflow || workflow.id !== args.workflow)
+        throw new Error(`Workflow '${args.workflow}' is not registered.`);
+      if (!workflow.inputSchema || !workflow.outputSchema)
+        throw new Error(
+          `Callable workflow '${workflow.id}' requires inputSchema and outputSchema.`
+        );
+      if (args.definition && (args.definition.version !== workflow.version || args.definition.inputSchema !== workflow.inputSchema || args.definition.outputSchema !== workflow.outputSchema)) {
+        throw new Error(
+          "The typed workflow contract does not match the registered definition."
+        );
+      }
+      assertSequentialWorkflow(workflow);
+      const snapshot = args.snapshot;
+      if (snapshot && snapshot.version !== workflow.version)
+        throw new Error(
+          `Workflow '${workflow.id}' changed since the call was suspended.`
+        );
+      const input = snapshot ? void 0 : workflow.inputSchema.parse(args.input);
+      if (!snapshot) (0, import_hooks.workflowCallFingerprint)(input);
+      const saver = createInMemoryCheckpointSaver();
+      const threadId = "child";
+      let request;
+      const invocationPath = `${config.invocationPath ?? "root"}/${encodeURIComponent(args.id)}:${args.invocationId}`;
+      let childConfig = {
+        executionBranchId: config.executionBranchId,
+        prepareChildTelemetry: config.prepareChildTelemetry,
+        context: config.context,
+        session: config.session,
+        selectWorkflow: config.selectWorkflow,
+        getProvider: config.getProvider,
+        telemetry: config.telemetry ? {
+          ...config.telemetry,
+          correlation: {
+            runId: config.telemetry.correlation?.runId,
+            sessionId: config.telemetry.correlation?.sessionId,
+            workflowId: workflow.id,
+            invocationId: args.invocationId,
+            parentInvocationId: config.telemetry.correlation?.invocationId,
+            branchId: config.executionBranchId ?? config.executionRunId
+          }
+        } : void 0,
+        reasonTrace: config.reasonTrace,
+        checkpointer: saver,
+        executionRunId: config.executionRunId,
+        workflowCallDepth: depth,
+        invocationPath,
+        emit: (event, payload) => {
+          if (event === "interrupt") {
+            const original = payload.input;
+            request = {
+              ...original,
+              meta: {
+                ...original.meta,
+                workflowCallPath: [
+                  {
+                    workflowId: workflow.id,
+                    invocationId: args.invocationId,
+                    callId: args.id
+                  },
+                  ...Array.isArray(original.meta?.workflowCallPath) ? original.meta.workflowCallPath : []
+                ],
+                workflowCall: original.meta?.workflowCall ?? {
+                  invocationId: args.invocationId,
+                  workflowId: workflow.id,
+                  nodeId: payload.node
+                }
+              }
+            };
+            return;
+          }
+          if (event === "error")
+            throw new Error(
+              String(
+                payload.message ?? "Child workflow failed."
+              )
+            );
+          if (event === "transition")
+            throw new Error(
+              "transitionTo is not supported inside child workflows; useWorkflow returns to its caller."
+            );
+          const value = payload;
+          const scoped = { ...value, workflow: workflow.id, invocationPath };
+          for (const key of ["node", "streamId", "opId", "segmentId"]) {
+            if (typeof value[key] === "string")
+              scoped[key] = `${config.executionRunId ?? "run"}/${args.invocationId}/${value[key]}`;
+          }
+          config.emit?.(event, scoped);
+        }
+      };
+      childConfig = config.prepareChildTelemetry?.(workflow, childConfig) ?? childConfig;
+      if (snapshot) {
+        if (snapshot.limitPaused)
+          snapshot.checkpoint.checkpoint.channel_values.config = childConfig;
+        await restoreGraphSnapshot(saver, snapshot.checkpoint, threadId);
+      }
+      const graph = await createExecutionGraph(
+        workflow,
+        childConfig,
+        execution
+      );
+      const initial = {
+        input,
+        data: {},
+        runtime: {},
+        config: childConfig,
+        currentWorkflow: workflow.id,
+        lastNode: "__start__",
+        awaitingHumanInput: false,
+        conversationHistory: []
+      };
+      const resumePatch = snapshot?.request?.meta?.__kortyxResumeStatePatch;
+      const command = snapshot?.limitPaused ? null : snapshot ? new import_langgraph.Command({
+        resume: args.response,
+        update: {
+          config: childConfig,
+          ...resumePatch ? { runtime: resumePatch } : {}
+        }
+      }) : initial;
+      let result;
+      try {
+        result = await import_singletons.AsyncLocalStorageProviderSingleton.runWithConfig(
+          {},
+          () => graph.invoke(command, {
+            configurable: { thread_id: threadId, checkpoint_ns: "" },
+            callbacks: []
+          })
+        );
+      } catch (error) {
+        (0, import_core.throwIfExecutionAborted)(execution.abortSignal);
+        if ((0, import_core.isExecutionLimitReached)(error)) {
+          const checkpoint = await captureGraphSnapshot(saver, threadId);
+          if (checkpoint) {
+            const state = checkpoint.checkpoint.channel_values;
+            const patch = error.__kortyxHookStatePatch;
+            if (patch) state.runtime = { ...state.runtime, ...patch };
+            Object.assign(error, {
+              __kortyxChildSnapshot: {
+                version: workflow.version,
+                checkpoint,
+                limitPaused: true
+              },
+              __kortyxChildUsage: state.runtime.tokenUsage
+            });
+          }
+        }
+        throw error;
+      }
+      (0, import_core.throwIfExecutionAborted)(execution.abortSignal);
+      if (request) {
+        const checkpoint = await captureGraphSnapshot(saver, threadId);
+        if (!checkpoint)
+          throw new Error("Child interrupted without a graph checkpoint.");
+        return {
+          status: "interrupted",
+          usage: request.meta?.__kortyxResumeStatePatch?.tokenUsage ?? result.runtime.tokenUsage,
+          request,
+          snapshot: {
+            version: workflow.version,
+            checkpoint,
+            request
+          }
+        };
+      }
+      const data = workflow.outputSchema.parse(result.data ?? {});
+      (0, import_hooks.workflowCallFingerprint)(data);
+      return {
+        status: "completed",
+        data,
+        usage: result.runtime.tokenUsage
+      };
+    };
+    const trace = config.telemetry?.trace ?? config.reasonTrace;
+    return trace?.withSpan ? trace.withSpan(
+      {
+        name: "kortyx.workflow.call",
+        attributes: {
+          workflowId: args.workflow,
+          runId: config.executionRunId,
+          branchId: config.executionBranchId ?? config.executionRunId,
+          parentInvocationId: config.telemetry?.correlation?.invocationId,
+          callerNodeExecutionId: args.callerNodeExecutionId,
+          callId: args.id,
+          invocationId: args.invocationId
+        }
+      },
+      execute
+    ) : execute();
+  };
+}
+
 // src/graph/create-execution-graph.ts
-async function createExecutionGraph(workflow, config) {
-  const StateAnnotation = import_langgraph.Annotation.Root({
-    input: import_langgraph.Annotation,
-    output: import_langgraph.Annotation,
-    lastNode: import_langgraph.Annotation,
-    lastCondition: import_langgraph.Annotation,
-    lastIntent: import_langgraph.Annotation,
-    runtime: (0, import_langgraph.Annotation)({
+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 ?? {}),
       default: () => ({})
     }),
-    config: import_langgraph.Annotation,
-    transitionTo: import_langgraph.Annotation,
-    data: (0, import_langgraph.Annotation)({
+    config: import_langgraph2.Annotation,
+    transitionTo: import_langgraph2.Annotation,
+    data: (0, import_langgraph2.Annotation)({
       reducer: (l, r) => (0, import_utils.deepMergeWithArrayOverwrite)(l ?? {}, r ?? {}),
       default: () => ({})
     }),
-    conversationHistory: (0, import_langgraph.Annotation)({
+    conversationHistory: (0, import_langgraph2.Annotation)({
       reducer: (l, r) => [...l ?? [], ...r ?? []],
       default: () => []
     }),
-    awaitingHumanInput: import_langgraph.Annotation
+    awaitingHumanInput: import_langgraph2.Annotation
   });
-  const builder = new import_langgraph.StateGraph(StateAnnotation);
+  const builder = new import_langgraph2.StateGraph(StateAnnotation);
   const edgeApi = builder;
   const workflowName = workflow.id;
   const runtimeConfig = config;
@@ -1243,14 +1525,41 @@ async function createExecutionGraph(workflow, config) {
     );
     const behavior = nodeConfig.behavior ?? {};
     builder.addNode(nodeId, async (state) => {
+      (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
       const emitRuntimeEvent = (event, payload) => {
         runtimeConfig.emit(event, payload);
       };
+      let suspension;
       const hookNodeContext = {
+        abortSignal: execution.abortSignal,
+        consumeExecution: (limit) => {
+          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+          if (execution.budget) (0, import_core2.consumeExecutionBudget)(execution.budget, limit);
+        },
+        workflowCallTelemetry: runtimeConfig.telemetry ? {
+          ...runtimeConfig.telemetry,
+          correlation: {
+            ...runtimeConfig.telemetry.correlation,
+            runId: runtimeConfig.executionRunId,
+            branchId: runtimeConfig.executionBranchId ?? runtimeConfig.executionRunId
+          }
+        } : void 0,
+        ...runtimeConfig.selectWorkflow ? {
+          callWorkflow: createWorkflowCallService(
+            {
+              ...runtimeConfig,
+              context: state.config?.context ?? runtimeConfig.context
+            },
+            workflow,
+            execution
+          )
+        } : {},
         graph: { name: workflowName, node: nodeId },
         config: nodeConfig,
         emit: emitRuntimeEvent,
         awaitInterrupt: (interruptConfig) => {
+          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+          if (execution.budget) (0, import_core2.assertExecutionBudget)(execution.budget);
           const { kind, question } = interruptConfig;
           const isMulti = kind === "multi-choice" || interruptConfig.kind !== "text" && interruptConfig.multiple === true;
           const sharedInterruptFields = {
@@ -1272,8 +1581,9 @@ async function createExecutionGraph(workflow, config) {
           };
           let resumed;
           try {
-            resumed = (0, import_langgraph.interrupt)(payload);
+            resumed = (0, import_langgraph2.interrupt)(payload);
           } catch (error) {
+            suspension = error;
             emitRuntimeEvent("interrupt", {
               node: nodeId,
               workflow: workflowName,
@@ -1307,6 +1617,7 @@ async function createExecutionGraph(workflow, config) {
       let retryHookRuntime = null;
       while (attempt < maxAttempts) {
         try {
+          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
           attempt++;
           const attemptState = retryHookRuntime && typeof retryHookRuntime === "object" ? {
             ...state,
@@ -1321,13 +1632,23 @@ async function createExecutionGraph(workflow, config) {
             state: attemptState,
             reasonTrace: activeTrace
           };
-          const runNode = () => (0, import_hooks.runWithHookContext)(
-            hookContext,
-            async () => resolvedRun({
-              input: state.input,
-              params: nodeParams ?? {}
-            })
-          );
+          const runNode = () => (0, import_hooks2.runWithHookContext)(hookContext, async () => {
+            try {
+              hookNodeContext.consumeExecution("maxNodeExecutions");
+              const result = await resolvedRun({
+                input: state.input,
+                params: nodeParams ?? {}
+              });
+              (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+              if (execution.budget) (0, import_core2.assertExecutionBudget)(execution.budget);
+              if (suspension) throw suspension;
+              return result;
+            } catch (error) {
+              (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+              if (execution.budget) (0, import_core2.assertExecutionBudget)(execution.budget);
+              throw error;
+            }
+          });
           const context = configContext();
           const spanArgs = {
             name: "kortyx.node",
@@ -1339,6 +1660,8 @@ async function createExecutionGraph(workflow, config) {
                 workflowRevisionId: telemetryCorrelation()?.workflowRevisionId
               } : {},
               ...typeof telemetryCorrelation()?.topologyHash === "string" ? { topologyHash: telemetryCorrelation()?.topologyHash } : {},
+              invocationId: runtimeConfig.telemetry?.correlation?.invocationId,
+              branchId: runtimeConfig.executionBranchId ?? runtimeConfig.executionRunId,
               nodeId,
               attempt,
               ...typeof context?.userId === "string" ? { userId: context.userId } : {},
@@ -1369,15 +1692,22 @@ async function createExecutionGraph(workflow, config) {
               patch
             );
           }
+          (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
+          if ((0, import_core2.isExecutionLimitReached)(err)) {
+            Object.assign(err, { nodeId, workflowId: workflowName });
+            throw err;
+          }
+          if ((0, import_core2.isExecutionCancelled)(err) || (0, import_langgraph2.isGraphInterrupt)(err)) throw err;
           const hasMore = attempt < maxAttempts;
           const delayMs = behavior.retry?.delayMs ?? 0;
           if (hasMore && delayMs > 0) {
-            await new Promise((r) => setTimeout(r, delayMs));
+            await (0, import_promises.setTimeout)(delayMs, void 0, { signal: execution.abortSignal });
             continue;
           }
           if (!hasMore) throw err;
         }
       }
+      (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
       const res = nodeResult ?? {};
       if (hookRuntimeUpdates) {
         res.infra = {
@@ -1490,6 +1820,7 @@ async function createExecutionGraph(workflow, config) {
   const runtimeGraph = graph;
   runtimeGraph.name = workflow.id;
   runtimeGraph.config = config;
+  runtimeGraph.execution = execution;
   runtimeGraph.resume = async (state, input) => {
     const resumed = { ...state, input, awaitingHumanInput: false };
     return await graph.invoke(resumed);
@@ -1515,9 +1846,9 @@ function makeRequestId(prefix = "req") {
 }
 
 // src/registry/file-registry.ts
-var import_promises = require("fs/promises");
+var import_promises2 = require("fs/promises");
 var import_node_path2 = require("path");
-var import_core = require("@kortyx/core");
+var import_core3 = require("@kortyx/core");
 var DEFAULT_EXTENSIONS = [
   ".workflow.ts",
   ".workflow.mts",
@@ -1541,15 +1872,15 @@ function createFileWorkflowRegistry(options) {
   let workflowCache = null;
   async function loadWorkflows() {
     if (shouldCache && workflowCache) return workflowCache;
-    const files = await (0, import_promises.readdir)(workflowsDir, { withFileTypes: true });
+    const files = await (0, import_promises2.readdir)(workflowsDir, { withFileTypes: true });
     const workflowFiles = files.filter((entry) => entry.isFile()).map((entry) => entry.name).filter((file) => isWorkflowFile(file, extensions));
     const workflows = {};
     for (const file of workflowFiles) {
       try {
         const modulePath = (0, import_node_path2.join)(workflowsDir, file);
         if (isDeclarativeWorkflowFile(file)) {
-          const raw = await (0, import_promises.readFile)(modulePath, "utf8");
-          const workflow = (0, import_core.loadWorkflow)(raw);
+          const raw = await (0, import_promises2.readFile)(modulePath, "utf8");
+          const workflow = (0, import_core3.loadWorkflow)(raw);
           workflow.metadata = {
             ...workflow.metadata ?? {},
             __filePath: modulePath
@@ -1660,6 +1991,7 @@ async function buildInitialGraphState({
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   buildInitialGraphState,
+  captureGraphSnapshot,
   clearRegisteredNodes,
   createExecutionGraph,
   createFileWorkflowRegistry,
@@ -1675,6 +2007,7 @@ async function buildInitialGraphState({
   makeRequestId,
   makeResumeToken,
   registerNode,
-  resolveNode
+  resolveNode,
+  restoreGraphSnapshot
 });
 //# sourceMappingURL=index.js.map