@kortyx/runtime 0.15.2 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.17.0](https://github.com/kortyx-io/kortyx/compare/runtime-v0.16.0...runtime-v0.17.0) (2026-09-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* **errors:** public failure messages and default HTTP statuses change; malformed streams fail explicitly, provider error classes are shared, and retry helpers exclude control flow. Existing calls and legacy records remain supported. See the error-contract migration and release notes.
+
+### Features
+
+* **errors:** harden failure contracts across execution and recovery ([#175](https://github.com/kortyx-io/kortyx/issues/175)) ([d231e36](https://github.com/kortyx-io/kortyx/commit/d231e364259a4f23fc3675d8783fde5ba338416e))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/stream bumped to 0.12.0
+    * @kortyx/core bumped to 0.9.0
+    * @kortyx/hooks bumped to 0.25.0
+    * @kortyx/providers bumped to 0.7.0
+    * @kortyx/utils bumped to 0.3.0
+
+## [0.16.0](https://github.com/kortyx-io/kortyx/compare/runtime-v0.15.2...runtime-v0.16.0) (2026-09-11)
+
+
+### Features
+
+* **hooks:** support durable parallel child workflows ([#171](https://github.com/kortyx-io/kortyx/issues/171)) ([fdf2d56](https://github.com/kortyx-io/kortyx/commit/fdf2d564d88e921988e8f3e20da9fe0c30bbcdf9))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/hooks bumped to 0.24.0
+
 ## [0.15.2](https://github.com/kortyx-io/kortyx/compare/runtime-v0.15.1...runtime-v0.15.2) (2026-09-11)
 
 

package/dist/index.js

@@ -267,6 +267,7 @@ function createRedisPendingRequestStore(options) {
 }
 
 // src/framework/redis/redis-checkpointer.ts
+var import_errors = require("@kortyx/core/errors");
 var import_langgraph_checkpoint2 = require("@langchain/langgraph-checkpoint");
 var utf8Bytes2 = (s) => new Uint8Array(Buffer.from(s, "utf8"));
 var utf8String2 = (u8) => typeof u8 === "string" ? u8 : Buffer.from(u8).toString("utf8");
@@ -296,7 +297,9 @@ function createRedisCheckpointSaver(options) {
     },
     getNextVersion(current) {
       if (typeof current === "string") {
-        throw new Error("Please override this method to use string versions.");
+        throw new import_errors.PersistenceError(
+          "Please override this method to use string versions."
+        );
       }
       return current !== void 0 && typeof current === "number" ? current + 1 : 1;
     },
@@ -362,7 +365,7 @@ function createRedisCheckpointSaver(options) {
       const threadId = config.configurable?.thread_id;
       const checkpointNs = config.configurable?.checkpoint_ns ?? "";
       if (!threadId) {
-        throw new Error(
+        throw new import_errors.PersistenceError(
           'Failed to put checkpoint: missing "thread_id" in config.configurable.'
         );
       }
@@ -393,12 +396,12 @@ function createRedisCheckpointSaver(options) {
       const checkpointNs = config.configurable?.checkpoint_ns;
       const checkpointId = config.configurable?.checkpoint_id;
       if (!threadId) {
-        throw new Error(
+        throw new import_errors.PersistenceError(
           'Failed to put writes: missing "thread_id" in config.configurable.'
         );
       }
       if (!checkpointId) {
-        throw new Error(
+        throw new import_errors.PersistenceError(
           'Failed to put writes: missing "checkpoint_id" in config.configurable.'
         );
       }
@@ -439,9 +442,13 @@ function createRedisCheckpointSaver(options) {
   return saver;
 }
 
+// src/framework/redis/redis-store.ts
+var import_errors3 = require("@kortyx/core/errors");
+
 // src/framework/redis/redis-client.ts
 var import_node_net = require("net");
 var import_node_tls = require("tls");
+var import_errors2 = require("@kortyx/core/errors");
 var encodeBulk = (s) => {
   const b = Buffer.from(s, "utf8");
   return Buffer.concat([
@@ -579,13 +586,17 @@ function createRedisClient(options) {
       if (password) {
         const r = await send("AUTH", [password]);
         if (typeof r === "object" && r && r.type === "error") {
-          throw new Error(`Redis AUTH failed: ${r.message}`);
+          throw new import_errors2.PersistenceError(
+            `Redis AUTH failed: ${r.message}`
+          );
         }
       }
       if (db && Number.isFinite(db) && db > 0) {
         const r = await send("SELECT", [String(db)]);
         if (typeof r === "object" && r && r.type === "error") {
-          throw new Error(`Redis SELECT failed: ${r.message}`);
+          throw new import_errors2.PersistenceError(
+            `Redis SELECT failed: ${r.message}`
+          );
         }
       }
       ready = true;
@@ -607,7 +618,17 @@ function createRedisClient(options) {
 // src/framework/redis/redis-store.ts
 var isRedisError = (r) => Boolean(r) && typeof r === "object" && r.type === "error";
 function createRedisFrameworkStore(options) {
-  const client = createRedisClient({ url: options.url });
+  const rawClient = createRedisClient({ url: options.url });
+  const client = {
+    ...rawClient,
+    command: async (...args) => {
+      try {
+        return await rawClient.command(...args);
+      } catch (cause) {
+        throw new import_errors3.PersistenceError("Redis command failed.", cause);
+      }
+    }
+  };
   const prefix = options.prefix ?? "kortyx:fw:";
   const k = (key) => `${prefix}${key}`;
   return {
@@ -617,7 +638,7 @@ function createRedisFrameworkStore(options) {
         [...new Set(keys)].map(async (key) => {
           const value = await client.command("GET", [key]);
           if (isRedisError(value))
-            throw new Error(`Redis GET error: ${value.message}`);
+            throw new import_errors3.PersistenceError(`Redis GET error: ${value.message}`);
           return value;
         })
       );
@@ -627,7 +648,8 @@ function createRedisFrameworkStore(options) {
     },
     async take(key) {
       const r = await client.command("GETDEL", [k(key)]);
-      if (isRedisError(r)) throw new Error(`Redis GETDEL error: ${r.message}`);
+      if (isRedisError(r))
+        throw new import_errors3.PersistenceError(`Redis GETDEL error: ${r.message}`);
       return typeof r === "string" ? r : null;
     },
     async get(key) {
@@ -635,7 +657,7 @@ function createRedisFrameworkStore(options) {
       if (r === null) return null;
       if (typeof r === "string") return r;
       if (isRedisError(r)) {
-        throw new Error(`Redis GET error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis GET error: ${r.message}`);
       }
       return null;
     },
@@ -643,32 +665,32 @@ function createRedisFrameworkStore(options) {
       const args = [k(key), value, "PX", String(Math.max(1, ttlMs))];
       const r = await client.command("SET", args);
       if (isRedisError(r)) {
-        throw new Error(`Redis SET error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis SET error: ${r.message}`);
       }
     },
     async del(key) {
       const r = await client.command("DEL", [k(key)]);
       if (isRedisError(r)) {
-        throw new Error(`Redis DEL error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis DEL error: ${r.message}`);
       }
     },
     async hset(key, field, value) {
       const r = await client.command("HSET", [k(key), field, value]);
       if (isRedisError(r)) {
-        throw new Error(`Redis HSET error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis HSET error: ${r.message}`);
       }
     },
     async hsetnx(key, field, value) {
       const r = await client.command("HSETNX", [k(key), field, value]);
       if (isRedisError(r)) {
-        throw new Error(`Redis HSETNX error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis HSETNX error: ${r.message}`);
       }
       return typeof r === "number" ? r : 0;
     },
     async hgetall(key) {
       const r = await client.command("HGETALL", [k(key)]);
       if (isRedisError(r)) {
-        throw new Error(`Redis HGETALL error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis HGETALL error: ${r.message}`);
       }
       if (!Array.isArray(r)) return {};
       const out = {};
@@ -685,7 +707,7 @@ function createRedisFrameworkStore(options) {
         String(Math.max(1, ttlMs))
       ]);
       if (isRedisError(r)) {
-        throw new Error(`Redis PEXPIRE error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis PEXPIRE error: ${r.message}`);
       }
     },
     async scanKeys(prefixKey) {
@@ -700,7 +722,8 @@ function createRedisFrameworkStore(options) {
           "COUNT",
           "200"
         ]);
-        if (isRedisError(r)) throw new Error(`Redis SCAN error: ${r.message}`);
+        if (isRedisError(r))
+          throw new import_errors3.PersistenceError(`Redis SCAN error: ${r.message}`);
         if (!Array.isArray(r) || r.length < 2) break;
         cursor = typeof r[0] === "string" ? r[0] : "0";
         const batch = r[1];
@@ -716,7 +739,7 @@ function createRedisFrameworkStore(options) {
       if (keys.length === 0) return;
       const r = await client.command("DEL", keys);
       if (isRedisError(r)) {
-        throw new Error(`Redis DEL error: ${r.message}`);
+        throw new import_errors3.PersistenceError(`Redis DEL error: ${r.message}`);
       }
     }
   };
@@ -724,6 +747,7 @@ function createRedisFrameworkStore(options) {
 
 // src/framework/redis/session-checkpoint-store.ts
 var import_node_crypto = require("crypto");
+var import_errors4 = require("@kortyx/core/errors");
 var DEFAULT_MAX_CHECKPOINTS_PER_SESSION = 50;
 var clone = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
 var uniqueStrings = (values) => Array.from(
@@ -844,7 +868,12 @@ function createRedisSessionCheckpointStore(options) {
     },
     async rollbackTo(id) {
       const target = await getRecord(id);
-      if (!target) throw new Error(`Checkpoint "${id}" not found.`);
+      if (!target)
+        throw new import_errors4.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+          category: "request",
+          retryable: false,
+          safeMessage: "The requested checkpoint was not found."
+        });
       const records = await sortedRecords(target.sessionId);
       const trailing = records.filter(
         (record) => record.turnIndex > target.turnIndex
@@ -870,7 +899,12 @@ function createRedisSessionCheckpointStore(options) {
     },
     async fork(id, options2) {
       const source = await getRecord(id);
-      if (!source) throw new Error(`Checkpoint "${id}" not found.`);
+      if (!source)
+        throw new import_errors4.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+          category: "request",
+          retryable: false,
+          safeMessage: "The requested checkpoint was not found."
+        });
       const sessionId = options2?.newSessionId || createId("session");
       const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone(source);
       const runId = source.activePendingRequests.some(
@@ -906,6 +940,7 @@ function createRedisSessionCheckpointStore(options) {
 
 // src/framework/session-checkpoints.ts
 var import_node_crypto2 = require("crypto");
+var import_errors5 = require("@kortyx/core/errors");
 var DEFAULT_MAX_CHECKPOINTS_PER_SESSION2 = 50;
 var createCheckpointId = () => `cp-${(0, import_node_crypto2.randomUUID)()}`;
 var createSessionId = () => `session-${(0, import_node_crypto2.randomUUID)()}`;
@@ -1009,7 +1044,11 @@ function createInMemorySessionCheckpointStore(options) {
     async rollbackTo(id) {
       const target = byId.get(id);
       if (!target) {
-        throw new Error(`Checkpoint "${id}" not found.`);
+        throw new import_errors5.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+          category: "request",
+          retryable: false,
+          safeMessage: "The requested checkpoint was not found."
+        });
       }
       const records = sortedRecords(target.sessionId);
       const trailing = records.filter(
@@ -1037,7 +1076,11 @@ function createInMemorySessionCheckpointStore(options) {
     async fork(id, options2) {
       const source = byId.get(id);
       if (!source) {
-        throw new Error(`Checkpoint "${id}" not found.`);
+        throw new import_errors5.KortyxError("NOT_FOUND", `Checkpoint "${id}" not found.`, {
+          category: "request",
+          retryable: false,
+          safeMessage: "The requested checkpoint was not found."
+        });
       }
       const sessionId = options2?.newSessionId || createSessionId();
       const { parentCheckpointId: _parentCheckpointId, ...sourceRecord } = clone2(source);
@@ -1265,6 +1308,7 @@ async function resolveNodeHandler(args) {
 
 // src/graph/call-workflow.ts
 var import_core = require("@kortyx/core");
+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");
@@ -1276,7 +1320,7 @@ function assertSequentialWorkflow(workflow) {
     else group.plain++;
     groups.set(from, group);
     if (group.plain > 1 || group.plain > 0 && group.conditional > 0) {
-      throw new Error(
+      throw new import_errors6.WorkflowContractError(
         `Workflow '${workflow.id}' has parallel edges; child calls require sequential graphs.`
       );
     }
@@ -1289,23 +1333,27 @@ function createWorkflowCallService(config, parent, execution = {}) {
       if (parent) assertSequentialWorkflow(parent);
       const depth = (config.workflowCallDepth ?? 0) + 1;
       if (depth > 16)
-        throw new Error("Maximum child workflow depth (16) exceeded.");
+        throw new import_errors6.WorkflowContractError(
+          "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.`);
+        throw new import_errors6.WorkflowContractError(
+          `Workflow '${args.workflow}' is not registered.`
+        );
       if (!workflow.inputSchema || !workflow.outputSchema)
-        throw new Error(
+        throw new import_errors6.WorkflowContractError(
           `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(
+        throw new import_errors6.WorkflowContractError(
           "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(
+        throw new import_errors6.WorkflowContractError(
           `Workflow '${workflow.id}' changed since the call was suspended.`
         );
       const input = snapshot ? void 0 : workflow.inputSchema.parse(args.input);
@@ -1361,14 +1409,12 @@ function createWorkflowCallService(config, parent, execution = {}) {
             };
             return;
           }
-          if (event === "error")
-            throw new Error(
-              String(
-                payload.message ?? "Child workflow failed."
-              )
-            );
+          if (event === "error") {
+            const failure = payload?.failure;
+            throw (0, import_errors6.isFailureDescriptor)(failure) ? (0, import_errors6.errorFromFailure)(failure) : new Error("Child workflow failed.");
+          }
           if (event === "transition")
-            throw new Error(
+            throw new import_errors6.WorkflowContractError(
               "transitionTo is not supported inside child workflows; useWorkflow returns to its caller."
             );
           const value = payload;
@@ -1420,11 +1466,29 @@ function createWorkflowCallService(config, parent, execution = {}) {
         );
       } catch (error) {
         (0, import_core.throwIfExecutionAborted)(execution.abortSignal);
+        const checkpoint = await captureGraphSnapshot(saver, threadId).catch(
+          (cause) => {
+            if ((0, import_core.isExecutionLimitReached)(error))
+              throw new import_errors6.PersistenceError(
+                "Cannot checkpoint a suspended child workflow.",
+                cause
+              );
+            return void 0;
+          }
+        );
+        const state = checkpoint?.checkpoint.channel_values;
+        const patch = error?.__kortyxHookStatePatch;
+        const usage = patch?.tokenUsage ?? state?.runtime.tokenUsage;
+        if (error && typeof error === "object")
+          Object.assign(error, { __kortyxChildUsage: usage });
+        try {
+          (0, import_core.throwIfExecutionAborted)(execution.abortSignal);
+        } catch (cancelled) {
+          Object.assign(cancelled, { __kortyxChildUsage: usage });
+          throw cancelled;
+        }
         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 (checkpoint && state) {
             if (patch) state.runtime = { ...state.runtime, ...patch };
             Object.assign(error, {
               __kortyxChildSnapshot: {
@@ -1442,7 +1506,9 @@ function createWorkflowCallService(config, parent, execution = {}) {
       if (request) {
         const checkpoint = await captureGraphSnapshot(saver, threadId);
         if (!checkpoint)
-          throw new Error("Child interrupted without a graph checkpoint.");
+          throw new import_errors6.WorkflowContractError(
+            "Child interrupted without a graph checkpoint."
+          );
         return {
           status: "interrupted",
           usage: request.meta?.__kortyxResumeStatePatch?.tokenUsage ?? result.runtime.tokenUsage,
@@ -1454,7 +1520,17 @@ function createWorkflowCallService(config, parent, execution = {}) {
           }
         };
       }
-      const data = workflow.outputSchema.parse(result.data ?? {});
+      let data;
+      try {
+        data = workflow.outputSchema.parse(result.data ?? {});
+      } catch (cause) {
+        if (!Array.isArray((0, import_errors6.errorProperty)(cause, "issues"))) throw cause;
+        throw new import_errors6.ValidationError(
+          "INVALID_OUTPUT",
+          "Child output validation failed.",
+          cause
+        );
+      }
       (0, import_hooks.workflowCallFingerprint)(data);
       return {
         status: "completed",
@@ -1556,12 +1632,20 @@ async function createExecutionGraph(workflow, config, execution = {}) {
         runtimeConfig.emit(event, payload);
       };
       let suspension;
+      let deniedAdmission;
       const hookNodeContext = {
         completeResponse: runtimeConfig.workflowCallDepth ? void 0 : execution.completeResponse,
         abortSignal: execution.abortSignal,
         consumeExecution: (limit) => {
           (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
-          if (execution.budget) (0, import_core2.consumeExecutionBudget)(execution.budget, limit);
+          if (suspension) throw suspension;
+          try {
+            if (execution.budget)
+              (0, import_core2.consumeExecutionBudget)(execution.budget, limit);
+          } catch (error) {
+            deniedAdmission = error;
+            throw error;
+          }
         },
         workflowCallTelemetry: runtimeConfig.telemetry ? {
           ...runtimeConfig.telemetry,
@@ -1667,12 +1751,12 @@ async function createExecutionGraph(workflow, config, execution = {}) {
                 params: nodeParams ?? {}
               });
               (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
-              if (execution.budget) (0, import_core2.assertExecutionBudget)(execution.budget);
+              if (deniedAdmission) throw deniedAdmission;
               if (suspension) throw suspension;
               return result;
             } catch (error) {
               (0, import_core2.throwIfExecutionAborted)(execution.abortSignal);
-              if (execution.budget) (0, import_core2.assertExecutionBudget)(execution.budget);
+              if (deniedAdmission) throw deniedAdmission;
               throw error;
             }
           });
@@ -1876,6 +1960,7 @@ function makeRequestId(prefix = "req") {
 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 DEFAULT_EXTENSIONS = [
   ".workflow.ts",
   ".workflow.mts",
@@ -1949,8 +2034,14 @@ function createFileWorkflowRegistry(options) {
     const fallback = selectOptions?.fallbackId ?? fallbackId;
     const selected = workflows[id] ?? (fallback ? workflows[fallback] : null);
     if (!selected) {
-      throw new Error(
-        `No workflow found for id "${id}" and no fallback "${fallback}" workflow available`
+      throw new import_errors7.KortyxError(
+        "UNKNOWN_WORKFLOW",
+        `No workflow found for id "${id}" and no fallback "${fallback}" workflow available`,
+        {
+          category: "request",
+          retryable: false,
+          safeMessage: "The requested workflow is not registered."
+        }
       );
     }
     return selected;
@@ -1968,6 +2059,7 @@ function createFileWorkflowRegistry(options) {
 }
 
 // src/registry/in-memory-registry.ts
+var import_errors8 = require("@kortyx/core/errors");
 function createInMemoryWorkflowRegistry(workflows, options) {
   const byId = /* @__PURE__ */ new Map();
   for (const wf of workflows) byId.set(wf.id, wf);
@@ -1983,8 +2075,14 @@ function createInMemoryWorkflowRegistry(workflows, options) {
       const fallback = selectOptions?.fallbackId ?? fallbackId;
       const wf = byId.get(id) ?? (fallback ? byId.get(fallback) : void 0);
       if (!wf) {
-        throw new Error(
-          `Workflow "${id}" not found${fallback ? ` (fallback "${fallback}" missing too)` : ""}.`
+        throw new import_errors8.KortyxError(
+          "UNKNOWN_WORKFLOW",
+          `Workflow "${id}" not found${fallback ? ` (fallback "${fallback}" missing too)` : ""}.`,
+          {
+            category: "request",
+            retryable: false,
+            safeMessage: "The requested workflow is not registered."
+          }
         );
       }
       return wf;