@kortyx/runtime 0.10.3 → 0.11.1

package/dist/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   createFrameworkAdapterFromEnv: () => createFrameworkAdapterFromEnv,
   createInMemoryFrameworkAdapter: () => createInMemoryFrameworkAdapter,
   createInMemoryPendingRequestStore: () => createInMemoryPendingRequestStore,
+  createInMemorySessionCheckpointStore: () => createInMemorySessionCheckpointStore,
   createInMemoryWorkflowRegistry: () => createInMemoryWorkflowRegistry,
   createRedisFrameworkAdapter: () => createRedisFrameworkAdapter,
   getCheckpointer: () => getCheckpointer,
@@ -112,7 +113,6 @@ function createInMemoryCheckpointSaver(options) {
         );
       }
       const ns = nsKey(threadId, checkpointNs);
-      const prevId = latest.get(ns);
       const prepared = (0, import_langgraph_checkpoint.copyCheckpoint)(checkpoint);
       const entry = {
         checkpoint: prepared,
@@ -123,9 +123,6 @@ function createInMemoryCheckpointSaver(options) {
       const id = checkpoint.id;
       checkpoints.set(chkKey(threadId, checkpointNs, id), entry);
       latest.set(ns, id);
-      if (prevId && prevId !== id) {
-        checkpoints.delete(chkKey(threadId, checkpointNs, prevId));
-      }
       return {
         configurable: {
           thread_id: threadId,
@@ -159,6 +156,15 @@ function createInMemoryCheckpointSaver(options) {
       for (const k of Array.from(checkpoints.keys())) {
         if (k.startsWith(`${threadId}
`)) checkpoints.delete(k);
       }
+    },
+    async deleteCheckpointWrites(threadId, checkpointNs, checkpointId) {
+      const stored = checkpoints.get(
+        chkKey(threadId, checkpointNs, checkpointId)
+      );
+      stored?.writes.clear();
+    },
+    async getLatestCheckpointId(threadId, checkpointNs = "") {
+      return latest.get(nsKey(threadId, checkpointNs));
     }
   };
   return saver;
@@ -335,7 +341,6 @@ function createRedisCheckpointSaver(options) {
           'Failed to put checkpoint: missing "thread_id" in config.configurable.'
         );
       }
-      const prevId = await store.get(latestKey(threadId, checkpointNs));
       const prepared = (0, import_langgraph_checkpoint2.copyCheckpoint)(checkpoint);
       const [[, chkBytes], [, metaBytes]] = await Promise.all([
         serde.dumpsTyped(prepared),
@@ -350,10 +355,6 @@ function createRedisCheckpointSaver(options) {
       };
       await store.set(key, JSON.stringify(stored), ttlMs);
       await store.set(latestKey(threadId, checkpointNs), checkpointId, ttlMs);
-      if (prevId && prevId !== checkpointId) {
-        await store.del(checkpointKey(threadId, checkpointNs, prevId));
-        await store.del(writesKey(threadId, checkpointNs, prevId));
-      }
       return {
         configurable: {
           thread_id: threadId,
@@ -402,6 +403,12 @@ function createRedisCheckpointSaver(options) {
       const wrKeys = await store.scanKeys(`${prefix}wr:${threadId}:`);
       const latestKeys = await store.scanKeys(`${prefix}latest:${threadId}:`);
       await store.delRaw([...chkKeys, ...wrKeys, ...latestKeys]);
+    },
+    async deleteCheckpointWrites(threadId, checkpointNs, checkpointId) {
+      await store.del(writesKey(threadId, checkpointNs, checkpointId));
+    },
+    async getLatestCheckpointId(threadId, checkpointNs = "") {
+      return await store.get(latestKey(threadId, checkpointNs)) ?? void 0;
     }
   };
   return saver;
@@ -498,7 +505,7 @@ function createRedisClient(options) {
     const payload = encodeCommand(cmd, args);
     return new Promise((resolve2, reject) => {
       inflight.push({ resolve: resolve2, reject });
-      socket.write(payload);
+      socket?.write(payload);
     });
   };
   const ensureConnected = async () => {
@@ -521,12 +528,12 @@ function createRedisClient(options) {
       });
       s.on("error", (err) => {
         ready = false;
-        while (inflight.length) inflight.shift().reject(err);
+        while (inflight.length) inflight.shift()?.reject(err);
       });
       s.on("close", () => {
         ready = false;
         while (inflight.length)
-          inflight.shift().reject(new Error("Redis socket closed"));
+          inflight.shift()?.reject(new Error("Redis socket closed"));
       });
       await new Promise((resolve2, reject) => {
         const timer = setTimeout(
@@ -670,6 +677,346 @@ function createRedisFrameworkStore(options) {
   };
 }
 
+// src/framework/redis/session-checkpoint-store.ts
+var import_node_crypto = require("crypto");
+var DEFAULT_MAX_CHECKPOINTS_PER_SESSION = 50;
+var clone = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
+var uniqueStrings = (values) => Array.from(
+  new Set(
+    Array.from(values).filter(
+      (value) => typeof value === "string" && value.length > 0
+    )
+  )
+);
+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 } : {}
+});
+function createRedisSessionCheckpointStore(options) {
+  const store = options.store;
+  const ttlMs = options.ttlMs;
+  const prefix = options.prefix ?? "kortyx:session-cp:";
+  const maxCheckpointsPerSession = options.maxCheckpointsPerSession ?? DEFAULT_MAX_CHECKPOINTS_PER_SESSION;
+  const byIdKey = (id) => `${prefix}by-id:${id}`;
+  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);
+    await Promise.all([
+      store.set(byIdKey(record.id), serialized, ttlMs),
+      store.set(
+        sessionRecordKey(record.sessionId, record.id),
+        serialized,
+        ttlMs
+      ),
+      store.set(headKey(record.sessionId), record.id, ttlMs)
+    ]);
+  };
+  const deleteRecord = async (record) => {
+    await Promise.all([
+      store.del(byIdKey(record.id)),
+      store.del(sessionRecordKey(record.sessionId, record.id))
+    ]);
+  };
+  const getRecord = async (id) => {
+    const raw = await store.get(byIdKey(id));
+    return raw ? JSON.parse(raw) : null;
+  };
+  const sortedRecords = async (sessionId) => {
+    const keys = await store.scanKeys(sessionPrefix(sessionId));
+    const records = await Promise.all(
+      keys.map(async (rawKey) => {
+        const logicalKey = rawKey.includes(sessionPrefix(sessionId)) ? rawKey.slice(rawKey.indexOf(sessionPrefix(sessionId))) : rawKey;
+        const raw = await store.get(logicalKey);
+        return raw ? JSON.parse(raw) : null;
+      })
+    );
+    return records.filter((record) => Boolean(record)).sort((a, b) => a.turnIndex - b.turnIndex || a.createdAt - b.createdAt);
+  };
+  const prune = async (sessionId) => {
+    const records = await sortedRecords(sessionId);
+    const overflow = Math.max(0, records.length - maxCheckpointsPerSession);
+    await Promise.all(records.slice(0, overflow).map(deleteRecord));
+  };
+  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;
+  };
+  return {
+    async list(sessionId) {
+      return (await sortedRecords(sessionId)).map(toSummary);
+    },
+    async get(id) {
+      const record = await getRecord(id);
+      return record ? clone(record) : null;
+    },
+    getHead,
+    async append(args) {
+      const previousHead = await getHead(args.sessionId);
+      const pendingRequests = args.pendingRequests ?? [];
+      const record = {
+        id: createId("cp"),
+        sessionId: args.sessionId,
+        runId: args.runId,
+        ...args.graphCheckpointId ? { graphCheckpointId: args.graphCheckpointId } : {},
+        turnIndex: previousHead ? previousHead.turnIndex + 1 : 0,
+        createdAt: Date.now(),
+        workflow: args.workflow,
+        state: clone(args.state),
+        nodes: uniqueStrings(args.nodes ?? []),
+        effects: {
+          structuredStreamIds: uniqueStrings(args.structuredStreamIds ?? []),
+          interruptTokens: uniqueStrings(
+            pendingRequests.map((request) => request.token)
+          )
+        },
+        activePendingRequests: clone(pendingRequests),
+        ...previousHead ? { parentCheckpointId: previousHead.id } : {},
+        ...args.label ? { label: args.label } : {},
+        ...args.workflowVersion ? { workflowVersion: args.workflowVersion } : {},
+        ...args.buildId ? { buildId: args.buildId } : {}
+      };
+      await saveRecord(record);
+      await prune(args.sessionId);
+      return clone(record);
+    },
+    async rollbackTo(id) {
+      const target = await getRecord(id);
+      if (!target) throw new Error(`Checkpoint "${id}" not found.`);
+      const records = await sortedRecords(target.sessionId);
+      const trailing = records.filter(
+        (record) => record.turnIndex > target.turnIndex
+      );
+      const invalidatedStructuredStreamIds = uniqueStrings(
+        trailing.flatMap((record) => record.effects.structuredStreamIds)
+      );
+      const invalidatedInterruptTokens = uniqueStrings(
+        trailing.flatMap((record) => [
+          ...record.effects.interruptTokens,
+          ...record.activePendingRequests.map((request) => request.token)
+        ])
+      );
+      await Promise.all(trailing.map(deleteRecord));
+      await store.set(headKey(target.sessionId), target.id, ttlMs);
+      return {
+        sessionId: target.sessionId,
+        head: target.id,
+        invalidatedStructuredStreamIds,
+        invalidatedInterruptTokens,
+        activePendingRequests: clone(target.activePendingRequests)
+      };
+    },
+    async fork(id, options2) {
+      const source = await getRecord(id);
+      if (!source) throw new Error(`Checkpoint "${id}" not found.`);
+      const sessionId = options2?.newSessionId || createId("session");
+      const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone(source);
+      const forked = {
+        ...sourceRecord,
+        id: createId("cp"),
+        sessionId,
+        parentSessionId: source.sessionId,
+        forkedFrom: source.id,
+        activePendingRequests: clone(source.activePendingRequests).map(
+          (request) => ({
+            ...request,
+            token: createResumeToken(),
+            requestId: createId("human"),
+            sessionId
+          })
+        )
+      };
+      await saveRecord(forked);
+      return {
+        sessionId,
+        parentSessionId: source.sessionId,
+        forkedFrom: source.id,
+        checkpoint: clone(forked)
+      };
+    }
+  };
+}
+
+// src/framework/session-checkpoints.ts
+var import_node_crypto2 = require("crypto");
+var DEFAULT_MAX_CHECKPOINTS_PER_SESSION2 = 50;
+var createCheckpointId = () => `cp-${(0, import_node_crypto2.randomUUID)()}`;
+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 uniqueStrings2 = (values) => Array.from(
+  new Set(
+    Array.from(values).filter(
+      (value) => typeof value === "string" && value.length > 0
+    )
+  )
+);
+function createInMemorySessionCheckpointStore(options) {
+  const maxCheckpointsPerSession = options?.maxCheckpointsPerSession ?? DEFAULT_MAX_CHECKPOINTS_PER_SESSION2;
+  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 deleteRecord = (record) => {
+    byId.delete(record.id);
+    bySession.set(
+      record.sessionId,
+      /* v8 ignore next -- deleteRecord only receives records that came from this session index. */
+      (bySession.get(record.sessionId) ?? []).filter((id) => id !== record.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);
+    }
+  };
+  const getHead = async (sessionId) => {
+    const headId = headBySession.get(sessionId);
+    if (!headId) return null;
+    const record = byId.get(headId);
+    return record ? clone2(record) : null;
+  };
+  return {
+    async list(sessionId) {
+      return sortedRecords(sessionId).map(toSummary2);
+    },
+    async get(id) {
+      const record = byId.get(id);
+      return record ? clone2(record) : null;
+    },
+    getHead,
+    async append(args) {
+      const previousHead = await getHead(args.sessionId);
+      const turnIndex = previousHead ? previousHead.turnIndex + 1 : 0;
+      const pendingRequests = args.pendingRequests ?? [];
+      const record = {
+        id: createCheckpointId(),
+        sessionId: args.sessionId,
+        runId: args.runId,
+        ...args.graphCheckpointId ? { graphCheckpointId: args.graphCheckpointId } : {},
+        turnIndex,
+        createdAt: Date.now(),
+        workflow: args.workflow,
+        state: clone2(args.state),
+        nodes: uniqueStrings2(args.nodes ?? []),
+        effects: {
+          structuredStreamIds: uniqueStrings2(args.structuredStreamIds ?? []),
+          interruptTokens: uniqueStrings2(
+            pendingRequests.map((request) => request.token)
+          )
+        },
+        activePendingRequests: clone2(pendingRequests),
+        ...previousHead ? { parentCheckpointId: previousHead.id } : {},
+        ...args.label ? { label: args.label } : {},
+        ...args.workflowVersion ? { workflowVersion: args.workflowVersion } : {},
+        ...args.buildId ? { buildId: args.buildId } : {}
+      };
+      saveRecord(record);
+      prune(args.sessionId);
+      return clone2(record);
+    },
+    async rollbackTo(id) {
+      const target = byId.get(id);
+      if (!target) {
+        throw new Error(`Checkpoint "${id}" not found.`);
+      }
+      const records = sortedRecords(target.sessionId);
+      const trailing = records.filter(
+        (record) => record.turnIndex > target.turnIndex
+      );
+      const invalidatedStructuredStreamIds = uniqueStrings2(
+        trailing.flatMap((record) => record.effects.structuredStreamIds)
+      );
+      const invalidatedInterruptTokens = uniqueStrings2(
+        trailing.flatMap((record) => [
+          ...record.effects.interruptTokens,
+          ...record.activePendingRequests.map((request) => request.token)
+        ])
+      );
+      for (const record of trailing) deleteRecord(record);
+      headBySession.set(target.sessionId, target.id);
+      return {
+        sessionId: target.sessionId,
+        head: target.id,
+        invalidatedStructuredStreamIds,
+        invalidatedInterruptTokens,
+        activePendingRequests: clone2(target.activePendingRequests)
+      };
+    },
+    async fork(id, options2) {
+      const source = byId.get(id);
+      if (!source) {
+        throw new Error(`Checkpoint "${id}" not found.`);
+      }
+      const sessionId = options2?.newSessionId || createSessionId();
+      const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone2(source);
+      const forked = {
+        ...sourceRecord,
+        id: createCheckpointId(),
+        sessionId,
+        parentSessionId: source.sessionId,
+        forkedFrom: source.id,
+        activePendingRequests: clone2(source.activePendingRequests).map(
+          (request) => ({
+            ...request,
+            token: createResumeToken2(),
+            requestId: createRequestId(),
+            sessionId
+          })
+        )
+      };
+      saveRecord(forked);
+      return {
+        sessionId,
+        parentSessionId: source.sessionId,
+        forkedFrom: source.id,
+        checkpoint: clone2(forked)
+      };
+    }
+  };
+}
+
 // src/framework/adapter.ts
 function createInMemoryFrameworkAdapter(options) {
   const ttlMs = options?.ttlMs ?? 15 * 60 * 1e3;
@@ -678,6 +1025,9 @@ function createInMemoryFrameworkAdapter(options) {
     kind: "in-memory",
     ttlMs,
     pendingRequests: createInMemoryPendingRequestStore(),
+    sessionCheckpoints: createInMemorySessionCheckpointStore({
+      ...options?.maxSessionCheckpoints !== void 0 ? { maxCheckpointsPerSession: options.maxSessionCheckpoints } : {}
+    }),
     checkpointer,
     cleanupRun: async (runId) => {
       try {
@@ -701,6 +1051,12 @@ function createRedisFrameworkAdapter(options) {
       store,
       prefix: "kortyx:pending:"
     }),
+    sessionCheckpoints: createRedisSessionCheckpointStore({
+      store,
+      ttlMs,
+      prefix: "kortyx:session-cp:",
+      ...options.maxSessionCheckpoints !== void 0 ? { maxCheckpointsPerSession: options.maxSessionCheckpoints } : {}
+    }),
     checkpointer: createRedisCheckpointSaver({
       store,
       ttlMs,
@@ -798,7 +1154,7 @@ function pickNodeExport(mod, exportName) {
   const fnExports = Object.entries(mod).filter(
     ([, v]) => typeof v === "function"
   );
-  if (fnExports.length === 1) return fnExports[0][1];
+  if (fnExports.length === 1) return fnExports[0]?.[1];
   const names = fnExports.map(([k]) => k).sort();
   throw new Error(
     `Node module must export a default function or exactly one named function (found: ${names.join(", ") || "none"}).`
@@ -852,6 +1208,7 @@ async function createExecutionGraph(workflow, config) {
   }
   const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
   const traceAdapter = () => runtimeConfig.telemetry?.trace ?? runtimeConfig.reasonTrace;
+  const telemetryCorrelation = () => runtimeConfig.telemetry?.correlation;
   const configContext = () => isRecord(runtimeConfig.context) ? runtimeConfig.context : void 0;
   const toRecordInput = (value) => {
     if (isRecord(value)) return value;
@@ -975,7 +1332,13 @@ async function createExecutionGraph(workflow, config) {
           const spanArgs = {
             name: "kortyx.node",
             attributes: {
+              ...typeof telemetryCorrelation()?.runId === "string" ? { runId: telemetryCorrelation()?.runId } : {},
+              ...typeof telemetryCorrelation()?.sessionId === "string" ? { sessionId: telemetryCorrelation()?.sessionId } : {},
               workflowId: workflowName,
+              ...typeof telemetryCorrelation()?.workflowRevisionId === "string" ? {
+                workflowRevisionId: telemetryCorrelation()?.workflowRevisionId
+              } : {},
+              ...typeof telemetryCorrelation()?.topologyHash === "string" ? { topologyHash: telemetryCorrelation()?.topologyHash } : {},
               nodeId,
               attempt,
               ...typeof context?.userId === "string" ? { userId: context.userId } : {},
@@ -1032,6 +1395,8 @@ async function createExecutionGraph(workflow, config) {
       }
       if (res.transitionTo) {
         emitRuntimeEvent("transition", {
+          node: nodeId,
+          workflow: workflowName,
           transitionTo: res.transitionTo,
           payload: res.data ?? {}
         });
@@ -1141,18 +1506,18 @@ async function createExecutionGraph(workflow, config) {
 }
 
 // src/interrupt/tokens.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto3 = require("crypto");
 function makeResumeToken() {
-  return (0, import_node_crypto.randomUUID)();
+  return (0, import_node_crypto3.randomUUID)();
 }
 function makeRequestId(prefix = "req") {
-  return `${prefix}-${(0, import_node_crypto.randomUUID)()}`;
+  return `${prefix}-${(0, import_node_crypto3.randomUUID)()}`;
 }
 
 // src/registry/file-registry.ts
-var import_core = require("@kortyx/core");
 var import_promises = require("fs/promises");
-var import_path = require("path");
+var import_node_path2 = require("path");
+var import_core = require("@kortyx/core");
 var DEFAULT_EXTENSIONS = [
   ".workflow.ts",
   ".workflow.mts",
@@ -1181,7 +1546,7 @@ function createFileWorkflowRegistry(options) {
     const workflows = {};
     for (const file of workflowFiles) {
       try {
-        const modulePath = (0, import_path.join)(workflowsDir, file);
+        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);
@@ -1301,6 +1666,7 @@ async function buildInitialGraphState({
   createFrameworkAdapterFromEnv,
   createInMemoryFrameworkAdapter,
   createInMemoryPendingRequestStore,
+  createInMemorySessionCheckpointStore,
   createInMemoryWorkflowRegistry,
   createRedisFrameworkAdapter,
   getCheckpointer,