@kortyx/agent 0.21.0 → 0.22.0

package/dist/index.js

@@ -309,13 +309,18 @@ var require_dist = __commonJS({
         workflowState: args.workflowState
       }
     });
+    var import_errors6 = require("@kortyx/core/errors");
     var parseWithSchema = (schema, value, label) => {
       if (!schema) return value;
       const parsed = schema.safeParse(value);
       if (parsed.success) return parsed.data;
       const parsedError = "error" in parsed && parsed.error ? parsed.error : void 0;
       const reason = typeof parsedError?.message === "string" && parsedError.message.length > 0 ? parsedError.message : "invalid payload";
-      throw new Error(`${label} validation failed: ${reason}`);
+      throw new import_errors6.ValidationError(
+        label === "useReason output" ? "MODEL_OUTPUT_SCHEMA" : "SCHEMA_VALIDATION",
+        `${label} validation failed: ${reason}`,
+        parsedError
+      );
     };
     var awaitInterruptInternal = (args) => {
       const ctx = getHookContext();
@@ -443,6 +448,21 @@ var require_dist = __commonJS({
     var import_core32 = require("@kortyx/core");
     var import_node_crypto22 = require("crypto");
     var import_core22 = require("@kortyx/core");
+    var import_errors22 = require("@kortyx/core/errors");
+    function assertModelFinish(result) {
+      if (result.finishReason?.unified !== "content-filter") return;
+      throw Object.assign(
+        new import_errors22.KortyxError("PROVIDER_REFUSAL", "The provider refused the request.", {
+          category: "provider",
+          retryable: false,
+          safeMessage: "The provider refused the request."
+        }),
+        {
+          ...result.usage ? { usage: result.usage } : {},
+          finishReason: result.finishReason
+        }
+      );
+    }
     var toError = (value) => value instanceof Error ? value : new Error(String(value));
     var createRuntimeId = () => {
       try {
@@ -556,15 +576,18 @@ var require_dist = __commonJS({
       };
       const failTrace = (span, error) => {
         const detail = error;
-        span?.fail?.(error, {
-          ...detail?.usage ? { usage: detail.usage } : {},
-          ...detail?.finishReason ? { finishReason: detail.finishReason } : {},
-          ...detail?.providerMetadata ? { providerMetadata: detail.providerMetadata } : {},
-          attributes: {
-            providerId: args.model.provider.id,
-            modelId: args.model.modelId
-          }
-        });
+        try {
+          span?.fail?.(error, {
+            ...detail?.usage ? { usage: detail.usage } : {},
+            ...detail?.finishReason ? { finishReason: detail.finishReason } : {},
+            ...detail?.providerMetadata ? { providerMetadata: detail.providerMetadata } : {},
+            attributes: {
+              providerId: args.model.provider.id,
+              modelId: args.model.modelId
+            }
+          });
+        } catch {
+        }
       };
       try {
         if (stream) {
@@ -649,6 +672,8 @@ var require_dist = __commonJS({
               }
             }
           }
+          (0, import_core22.throwIfExecutionAborted)(abortSignal);
+          assertModelFinish({ finishReason, usage });
           if (emit) {
             emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
               ...commonMeta
@@ -670,6 +695,7 @@ var require_dist = __commonJS({
         }
         const response = await model.invoke(messages);
         (0, import_core22.throwIfExecutionAborted)(abortSignal);
+        assertModelFinish(response);
         if (response.content) args.onTextChunk?.(response.content);
         if (emit) {
           emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
@@ -1459,6 +1485,7 @@ var require_dist = __commonJS({
         }
       };
     }
+    var import_errors32 = require("@kortyx/core/errors");
     var tryJsonParse = (value) => {
       try {
         return { ok: true, value: JSON.parse(value) };
@@ -1496,132 +1523,135 @@ var require_dist = __commonJS({
       }
       return text;
     };
-    var looksLikeStructuredJsonAttempt = (value) => {
-      const trimmed = value.trim();
-      if (!trimmed) return false;
-      return trimmed.startsWith("{") || trimmed.startsWith("[") || /^```(?:json)?/i.test(trimmed);
-    };
-    var isLikelyTruncatedStructuredOutput = (text) => {
-      const trimmed = text.trim();
-      if (!looksLikeStructuredJsonAttempt(trimmed)) return false;
-      const direct = tryJsonParse(trimmed);
-      if (!direct.ok && direct.error) return true;
-      const block = extractJsonCodeBlock(trimmed);
-      if (!block) return false;
-      const parsedBlock = tryJsonParse(block);
-      return !parsedBlock.ok && Boolean(parsedBlock.error);
-    };
-    var createTruncatedStructuredOutputError = (label) => new Error(
-      `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`
+    var createTruncatedStructuredOutputError = (label, cause) => new import_errors32.ValidationError(
+      "OUTPUT_TRUNCATED",
+      `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`,
+      cause
     );
-    var createInvalidStructuredOutputError = (label) => new Error(
-      `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. This often happens when output is truncated or the provider does not follow JSON mode. Increase maxOutputTokens or simplify the requested output.`
+    var createInvalidStructuredOutputError = (label, cause) => new import_errors32.ValidationError(
+      "INVALID_MODEL_JSON",
+      `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. Check outputSchema and provider structured-output settings.`,
+      cause
     );
     var parseReasonOutputWithSchema = (args) => {
       const candidate = resolveOutputCandidate(args.text);
+      const block = extractJsonCodeBlock(args.text.trim());
+      const validJson = tryJsonParse(args.text.trim()).ok || block !== null && tryJsonParse(block).ok;
       try {
         return parseWithSchema(args.schema, candidate, args.label);
       } catch (error) {
-        if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-          throw createTruncatedStructuredOutputError(args.label);
-        }
-        if (typeof candidate === "string" && candidate.trim().length > 0) {
-          throw createInvalidStructuredOutputError(args.label);
-        }
-        throw error;
+        if (!(error instanceof import_errors32.ValidationError)) throw error;
+        const failure = args.finishReason?.unified === "length" ? createTruncatedStructuredOutputError(args.label, error) : typeof candidate === "string" && !validJson ? createInvalidStructuredOutputError(args.label, error) : error;
+        if (failure && typeof failure === "object")
+          Object.assign(failure, {
+            ...args.usage ? { usage: args.usage } : {},
+            ...args.finishReason ? { finishReason: args.finishReason } : {}
+          });
+        throw failure;
       }
     };
     var parseInterruptFirstPassResult = (args) => {
-      const candidate = resolveOutputCandidate(args.text);
-      if (!isRecord22(candidate)) {
-        if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-          throw createTruncatedStructuredOutputError("useReason output");
-        }
-        if (typeof candidate === "string" && candidate.trim().length > 0) {
-          throw createInvalidStructuredOutputError("useReason output");
-        }
-        throw new Error(
-          "useReason first pass with interrupt must return a JSON object."
-        );
-      }
-      const mode = args.mode ?? "required";
-      let interruptRequired = true;
-      if (mode === "optional") {
-        if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
-          throw new Error(
-            'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
+      try {
+        const candidate = resolveOutputCandidate(args.text);
+        if (!isRecord22(candidate)) {
+          if (args.finishReason?.unified === "length") {
+            throw createTruncatedStructuredOutputError("useReason output");
+          }
+          if (typeof candidate === "string" && candidate.trim().length > 0) {
+            throw createInvalidStructuredOutputError("useReason output");
+          }
+          throw new import_errors32.ValidationError(
+            "MODEL_OUTPUT_SCHEMA",
+            "useReason first pass with interrupt must return a JSON object."
           );
         }
-        interruptRequired = candidate.decision === "interrupt";
-        if (!interruptRequired) {
-          const hasUnexpectedRequest = [
+        const mode = args.mode ?? "required";
+        let interruptRequired = true;
+        if (mode === "optional") {
+          if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
+            throw new import_errors32.ValidationError(
+              "MODEL_OUTPUT_SCHEMA",
+              'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
+            );
+          }
+          interruptRequired = candidate.decision === "interrupt";
+          if (!interruptRequired) {
+            const hasUnexpectedRequest = [
+              candidate.interruptRequest,
+              candidate.request,
+              candidate.interrupt
+            ].some((value) => value !== null && value !== void 0);
+            if (hasUnexpectedRequest) {
+              throw new import_errors32.ValidationError(
+                "MODEL_OUTPUT_SCHEMA",
+                'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
+              );
+            }
+          }
+        }
+        let request;
+        if (interruptRequired) {
+          const requestCandidates = [
             candidate.interruptRequest,
             candidate.request,
-            candidate.interrupt
-          ].some((value) => value !== null && value !== void 0);
-          if (hasUnexpectedRequest) {
-            throw new Error(
-              'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
+            candidate.interrupt,
+            mode === "required" ? candidate : void 0
+          ];
+          const requestPayload = requestCandidates.find(
+            (value) => value !== null && value !== void 0
+          );
+          request = parseWithSchema(
+            args.requestSchema,
+            requestPayload,
+            "useReason interrupt.request"
+          );
+        }
+        let output;
+        if (args.outputSchema) {
+          const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
+          try {
+            output = parseWithSchema(
+              args.outputSchema,
+              outputPayload,
+              "useReason output"
             );
+          } catch (error) {
+            if (!(error instanceof import_errors32.ValidationError)) throw error;
+            if (args.finishReason?.unified === "length") {
+              throw createTruncatedStructuredOutputError("useReason output", error);
+            }
+            throw error;
           }
         }
-      }
-      let request;
-      if (interruptRequired) {
-        const requestCandidates = [
-          candidate.interruptRequest,
-          candidate.request,
-          candidate.interrupt,
-          mode === "required" ? candidate : void 0
-        ];
-        const requestPayload = requestCandidates.find(
-          (value) => value !== null && value !== void 0
-        );
-        request = parseWithSchema(
-          args.requestSchema,
-          requestPayload,
-          "useReason interrupt.request"
-        );
-      }
-      let output;
-      if (args.outputSchema) {
-        const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
-        try {
-          output = parseWithSchema(
-            args.outputSchema,
-            outputPayload,
-            "useReason output"
+        const explicitDraft = typeof candidate.draftText === "string" && candidate.draftText.length > 0 ? candidate.draftText : typeof candidate.text === "string" && candidate.text.length > 0 ? candidate.text : void 0;
+        if (!args.outputSchema && !explicitDraft) {
+          throw new import_errors32.ValidationError(
+            "MODEL_OUTPUT_SCHEMA",
+            "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
           );
-        } catch (error) {
-          if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
-            throw createTruncatedStructuredOutputError("useReason output");
-          }
-          if (typeof outputPayload === "string" && outputPayload.trim().length > 0) {
-            throw createInvalidStructuredOutputError("useReason output");
-          }
-          throw error;
         }
-      }
-      const explicitDraft = typeof candidate.draftText === "string" && candidate.draftText.length > 0 ? candidate.draftText : typeof candidate.text === "string" && candidate.text.length > 0 ? candidate.text : void 0;
-      if (!args.outputSchema && !explicitDraft) {
-        throw new Error(
-          "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
-        );
-      }
-      const draftText = explicitDraft ?? (output !== void 0 ? tryStringify(output) : String(args.text ?? ""));
-      if (!interruptRequired) {
+        const draftText = explicitDraft ?? (output !== void 0 ? tryStringify(output) : String(args.text ?? ""));
+        if (!interruptRequired) {
+          return {
+            draftText,
+            interruptRequired: false,
+            ...output !== void 0 ? { output } : {}
+          };
+        }
         return {
           draftText,
-          interruptRequired: false,
+          interruptRequired: true,
+          request,
           ...output !== void 0 ? { output } : {}
         };
+      } catch (error) {
+        if (error && typeof error === "object")
+          Object.assign(error, {
+            ...args.usage ? { usage: args.usage } : {},
+            ...args.finishReason ? { finishReason: args.finishReason } : {}
+          });
+        throw error;
       }
-      return {
-        draftText,
-        interruptRequired: true,
-        request,
-        ...output !== void 0 ? { output } : {}
-      };
     };
     var import_zod32 = require("zod");
     var tryStringify2 = (value) => {
@@ -1829,7 +1859,7 @@ ${tryStringify2(args.response)}`
       });
     };
     var import_core42 = require("@kortyx/core");
-    var toErrorMessage2 = (error) => error instanceof Error ? error.message : String(error);
+    var import_errors42 = require("@kortyx/core/errors");
     var toToolDefinitions = (tools) => tools.map((tool) => ({
       name: tool.name,
       ...tool.title ? { title: tool.title } : {},
@@ -1863,17 +1893,27 @@ ${tryStringify2(args.response)}`
         ...value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) ? { structuredContent: value } : {}
       };
     };
-    var closeOwnedTools = async (tools) => {
+    var closeOwnedTools = async (tools, preserveFailure = false, traceSpan) => {
       const closeFns = /* @__PURE__ */ new Set();
       for (const tool of tools) {
         if (tool.closeAfterUse === false || !tool.close) continue;
         closeFns.add(tool.close);
       }
-      await Promise.all(
-        [...closeFns].map(async (close) => {
-          await close();
-        })
-      );
+      try {
+        await Promise.all(
+          [...closeFns].map(async (close) => {
+            await close();
+          })
+        );
+      } catch (error) {
+        if (!preserveFailure) throw error;
+        try {
+          traceSpan?.addEvent?.("useReason.cleanup.failed", {
+            failure: (0, import_errors42.serializeFailure)(error)
+          });
+        } catch {
+        }
+      }
     };
     var createInitialMessages = (args) => [
       ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
@@ -1890,6 +1930,7 @@ ${tryStringify2(args.response)}`
       const saved = ctx.currentNodeState.byKey[checkpointKey];
       const checkpoint = saved?.status === "tool_loop" ? saved : void 0;
       const opId = checkpoint?.opId ?? args.opId;
+      let primaryFailure = false;
       const tools = useReasonArgs.tools ?? [];
       const toolByName = /* @__PURE__ */ new Map();
       let validationCompleted = false;
@@ -1922,7 +1963,7 @@ ${tryStringify2(args.response)}`
         validationCompleted = true;
       } finally {
         if (!validationCompleted) {
-          await closeOwnedTools(tools);
+          await closeOwnedTools(tools, true, traceSpan);
         }
       }
       const toolDefinitions = toToolDefinitions(tools);
@@ -2041,6 +2082,7 @@ ${tryStringify2(args.response)}`
                     text: step.text,
                     schema: useReasonArgs.outputSchema,
                     ...step.finishReason ? { finishReason: step.finishReason } : {},
+                    ...aggregatedUsage ? { usage: aggregatedUsage } : {},
                     label: "useReason output"
                   });
                   aggregatedWarnings = mergeWarnings(aggregatedWarnings, [
@@ -2128,12 +2170,12 @@ ${tryStringify2(args.response)}`
                   options: [
                     { id: "approve", label: "Approve" },
                     { id: "deny", label: "Deny" }
-                  ],
-                  meta: {
-                    tool: tool.name,
-                    toolCallId: toolCall.id,
-                    input: toolCall.input
-                  }
+                  ]
+                },
+                meta: {
+                  tool: tool.name,
+                  toolCallId: toolCall.id,
+                  input: toolCall.input
                 }
               });
               const approved = Array.isArray(approval) ? approval.includes("approve") : approval === "approve";
@@ -2195,12 +2237,12 @@ ${tryStringify2(args.response)}`
               });
             } catch (error) {
               (0, import_core42.throwIfExecutionAborted)(abortSignal);
-              if ((0, import_core42.isExecutionLimitReached)(error) || (0, import_core42.isExecutionCancelled)(error))
-                throw error;
+              if ((0, import_errors42.isControlFlowError)(error)) throw error;
               const result2 = {
                 toolCallId: toolCall.id,
                 name: tool.name,
-                content: toErrorMessage2(error),
+                content: (0, import_errors42.serializeFailure)(error).message,
+                failure: (0, import_errors42.serializeFailure)(error),
                 isError: true
               };
               toolResults.push(result2);
@@ -2209,14 +2251,16 @@ ${tryStringify2(args.response)}`
                 emitToolEvent("tool-call-error", {
                   tool: tool.name,
                   toolCallId: toolCall.id,
-                  message: result2.content
+                  message: result2.content,
+                  failure: result2.failure
                 });
               }
               traceSpan?.addEvent?.("useReason.tool-call.error", {
                 stepIndex,
                 tool: tool.name,
                 toolCallId: toolCall.id,
-                message: result2.content
+                message: result2.content,
+                failure: result2.failure
               });
             }
             const completed2 = toolResults.at(-1);
@@ -2243,6 +2287,7 @@ ${tryStringify2(args.response)}`
             text: finalText,
             schema: useReasonArgs.outputSchema,
             ...finalFinishReason ? { finishReason: finalFinishReason } : {},
+            ...aggregatedUsage ? { usage: aggregatedUsage } : {},
             label: "useReason output"
           });
         }
@@ -2289,15 +2334,19 @@ ${tryStringify2(args.response)}`
         ctx.stateDirty = true;
         return result;
       } catch (error) {
-        traceSpan?.fail?.(error, {
-          attributes: {
-            toolStepCount: steps.length,
-            toolCallCount: allToolCalls.length
-          }
-        });
+        primaryFailure = true;
+        try {
+          traceSpan?.fail?.(error, {
+            attributes: {
+              toolStepCount: steps.length,
+              toolCallCount: allToolCalls.length
+            }
+          });
+        } catch {
+        }
         throw error;
       } finally {
-        await closeOwnedTools(tools);
+        await closeOwnedTools(tools, primaryFailure, traceSpan);
       }
     };
     var shouldStreamReasonStructured = (args) => (args.emit ?? true) && shouldStreamStructured(args.structured);
@@ -2460,6 +2509,7 @@ ${tryStringify2(args.response)}`
             text: first.text,
             requestSchema: args.interrupt.requestSchema,
             ...first.finishReason ? { finishReason: first.finishReason } : {},
+            ...first.usage ? { usage: first.usage } : {},
             ...args.outputSchema ? { outputSchema: args.outputSchema } : {},
             mode: args.interrupt.mode ?? "required"
           });
@@ -2477,6 +2527,7 @@ ${tryStringify2(args.response)}`
               text: first.text,
               schema: args.outputSchema,
               ...first.finishReason ? { finishReason: first.finishReason } : {},
+              ...first.usage ? { usage: first.usage } : {},
               label: "useReason output"
             });
           }
@@ -2571,6 +2622,7 @@ ${tryStringify2(args.response)}`
             text: finalText,
             schema: args.outputSchema,
             ...second.finishReason ? { finishReason: second.finishReason } : {},
+            ...aggregatedUsage ? { usage: aggregatedUsage } : {},
             label: "useReason output"
           });
         }
@@ -2674,7 +2726,9 @@ ${tryStringify2(args.response)}`
       return [getValue(), setValue];
     }
     var import_core62 = require("@kortyx/core");
+    var import_errors52 = require("@kortyx/core/errors");
     var ParallelChildWaiting = class extends Error {
+      name = "ParallelChildWaiting";
     };
     var ParallelError = class extends AggregateError {
       constructor(results) {
@@ -2686,8 +2740,23 @@ ${tryStringify2(args.response)}`
         );
         this.results = results;
         this.name = "ParallelError";
+        this.failure = (0, import_errors52.serializeFailure)({
+          version: 1,
+          code: this.code,
+          category: "workflow",
+          message: this.message,
+          retryable: null,
+          results: results.map(
+            (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors52.serializeFailure)(result.reason) }
+          )
+        });
       }
       results;
+      code = "PARALLEL_FAILED";
+      failure;
+      toJSON() {
+        return (0, import_errors52.serializeFailure)(this);
+      }
     };
     function registerWorkflowTask(id) {
       const ctx = getHookContext();
@@ -2825,6 +2894,7 @@ ${tryStringify2(args.response)}`
     }
     var import_node_crypto5 = require("crypto");
     var import_core7 = require("@kortyx/core");
+    var import_errors62 = require("@kortyx/core/errors");
     var import_node_crypto42 = require("crypto");
     function emitWorkflowCall2(telemetry, type, payload) {
       const base = telemetry?.correlation;
@@ -2862,10 +2932,20 @@ ${tryStringify2(args.response)}`
       const serialized = JSON.stringify(value);
       return serialized && Buffer.byteLength(serialized, "utf8") <= 16384 ? { [side]: JSON.parse(serialized) } : { [`${side}Omitted`]: "Content exceeds 16 KiB" };
     }
-    var WorkflowCallError = class extends Error {
-      constructor(workflow, message) {
-        super(`Workflow '${workflow}': ${message}`);
+    var WorkflowCallError = class extends import_errors62.KortyxError {
+      constructor(workflow, message, cause, failure) {
+        const detail = (0, import_errors62.serializeFailure)(
+          failure ?? cause ?? new import_errors62.WorkflowContractError(message)
+        );
+        super(detail.code, `Workflow '${workflow}': ${message}`, {
+          ...detail,
+          safeMessage: detail.message,
+          ...cause !== void 0 ? { cause } : {}
+        });
         this.workflow = workflow;
+        Object.assign(this.failure, detail, {
+          context: { ...detail.context, workflow }
+        });
         this.name = "WorkflowCallError";
       }
       workflow;
@@ -2876,10 +2956,12 @@ ${tryStringify2(args.response)}`
         if (v === null || typeof v === "string" || typeof v === "boolean") return v;
         if (typeof v === "number" && Number.isFinite(v)) return v;
         if (typeof v !== "object" || !v || seen.has(v)) {
-          throw new Error("Workflow input and output must be JSON serializable.");
+          throw new import_errors62.WorkflowContractError(
+            "Workflow input and output must be JSON serializable."
+          );
         }
         if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype) {
-          throw new Error(
+          throw new import_errors62.WorkflowContractError(
             "Workflow input and output must contain plain JSON objects."
           );
         }
@@ -2900,7 +2982,9 @@ ${tryStringify2(args.response)}`
         useWorkflow: (args) => {
           const workflow = workflows[args.workflow];
           if (!workflow || workflow.id !== args.workflow)
-            throw new Error("Workflow registry keys must match definition ids.");
+            throw new import_errors62.WorkflowContractError(
+              "Workflow registry keys must match definition ids."
+            );
           return useWorkflow({ ...args, workflow });
         }
       };
@@ -2924,19 +3008,23 @@ ${tryStringify2(args.response)}`
       (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
       const service = ctx.node.callWorkflow;
       if (!service)
-        throw new Error("useWorkflow requires an agent workflow registry.");
+        throw new import_errors62.WorkflowContractError(
+          "useWorkflow requires an agent workflow registry."
+        );
       if (!args.id.trim())
-        throw new Error("useWorkflow requires a stable, nonempty id.");
+        throw new import_errors62.WorkflowContractError(
+          "useWorkflow requires a stable, nonempty id."
+        );
       if (ctx.workflowCallActive && !task.group)
-        throw new Error(
+        throw new import_errors62.WorkflowContractError(
           "Concurrent workflow calls require parallel([...]); otherwise await each call."
         );
       if (ctx.workflowCallIds.has(args.id))
-        throw new Error(
+        throw new import_errors62.WorkflowContractError(
           `Duplicate workflow call id '${args.id}' in one node activation.`
         );
       if (ctx.workflowCallIds.size >= 64)
-        throw new Error(
+        throw new import_errors62.WorkflowContractError(
           "A node may call at most 64 child workflows per activation."
         );
       ctx.workflowCallIds.add(args.id);
@@ -3013,7 +3101,12 @@ ${tryStringify2(args.response)}`
           });
         }
         if (record.status === "failed")
-          throw new WorkflowCallError(workflow, record.error ?? "child failed");
+          throw new WorkflowCallError(
+            workflow,
+            record.error ?? "child failed",
+            void 0,
+            record.failure ?? (0, import_errors62.serializeFailure)(void 0)
+          );
         if (task.group && record.status === "interrupted" && record.interrupts.at(-1)?.response === void 0)
           throw new ParallelChildWaiting();
         while (record.status !== "completed") {
@@ -3048,9 +3141,15 @@ ${tryStringify2(args.response)}`
               throw error;
             }
             record.status = "failed";
-            record.error = error instanceof Error ? error.message : String(error);
+            record.failure = (0, import_errors62.serializeFailure)(error);
+            record.error = record.failure.message;
             report("failed", { error: "Child workflow failed" });
-            throw new WorkflowCallError(workflow, record.error);
+            throw new WorkflowCallError(
+              workflow,
+              record.error,
+              error,
+              record.failure
+            );
           }
           (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
           recordUsage(outcome.usage);
@@ -3100,6 +3199,7 @@ __export(index_exports, {
   createAgent: () => createAgent,
   createChatRouteHandler: () => createChatRouteHandler,
   createCheckpointRouteHandler: () => createCheckpointRouteHandler,
+  createFailureResponse: () => createFailureResponse,
   extractLatestUserMessage: () => extractLatestUserMessage,
   handleChatRequestBody: () => handleChatRequestBody,
   handleCheckpointRequestBody: () => handleCheckpointRequestBody,
@@ -3108,6 +3208,7 @@ __export(index_exports, {
   parseCheckpointRequestBody: () => parseCheckpointRequestBody,
   parseResumeMeta: () => parseResumeMeta,
   projectWorkflowTopology: () => projectWorkflowTopology,
+  readRequestJson: () => readRequestJson,
   streamChat: () => streamChat,
   streamChatFromRoute: () => streamChatFromRoute,
   transformGraphStreamForUI: () => transformGraphStreamForUI,
@@ -3116,6 +3217,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/adapters/http.ts
+var import_errors = require("@kortyx/core/errors");
 var import_stream = require("@kortyx/stream");
 var import_zod = require("zod");
 var chatMessageSchema = import_zod.z.object({
@@ -3151,12 +3253,41 @@ var checkpointRequestBodySchema = import_zod.z.discriminatedUnion("action", [
     newSessionId: import_zod.z.string().min(1).optional()
   }).strict()
 ]);
-var toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+async function readRequestJson(request) {
+  try {
+    const value = await request.json();
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("Expected a JSON object.");
+    return value;
+  } catch (cause) {
+    throw new import_errors.KortyxError(
+      "INVALID_REQUEST",
+      "Request body is not valid JSON.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "The request body must contain a valid JSON object.",
+        cause
+      }
+    );
+  }
+}
+function createFailureResponse(error, status) {
+  const failure = (0, import_errors.serializeFailure)(error);
+  return Response.json(
+    { error: failure.message, failure },
+    { status: status ?? (0, import_errors.failureHttpStatus)(failure) }
+  );
+}
 function parseChatRequestBody(value) {
   const parsed = chatRequestBodySchema.safeParse(value);
   if (!parsed.success) {
     const [firstIssue] = parsed.error.issues;
-    throw new Error(firstIssue.message);
+    throw new import_errors.KortyxError("INVALID_REQUEST", firstIssue.message, {
+      category: "request",
+      retryable: false,
+      safeMessage: "The request body is invalid."
+    });
   }
   const sessionId = parsed.data.sessionId?.trim();
   const workflowId = parsed.data.workflowId?.trim();
@@ -3172,7 +3303,11 @@ function parseCheckpointRequestBody(value) {
   const parsed = checkpointRequestBodySchema.safeParse(value);
   if (parsed.success) return parsed.data;
   const [firstIssue] = parsed.error.issues;
-  throw new Error(firstIssue.message);
+  throw new import_errors.KortyxError("INVALID_REQUEST", firstIssue.message, {
+    category: "request",
+    retryable: false,
+    safeMessage: "The request body is invalid."
+  });
 }
 async function handleChatRequestBody(args) {
   const { agent, body } = args;
@@ -3194,10 +3329,10 @@ async function handleChatRequestBody(args) {
   return (0, import_stream.toSSE)(stream);
 }
 function createChatRouteHandler(args) {
-  const { agent, errorStatus = 400 } = args;
+  const { agent, errorStatus } = args;
   return async function POST(request) {
     try {
-      const body = parseChatRequestBody(await request.json());
+      const body = parseChatRequestBody(await readRequestJson(request));
       return await handleChatRequestBody({
         agent,
         body,
@@ -3205,17 +3340,7 @@ function createChatRouteHandler(args) {
         onExecution: args.onExecution
       });
     } catch (error) {
-      return new Response(
-        JSON.stringify({
-          error: toErrorMessage(error)
-        }),
-        {
-          status: errorStatus,
-          headers: {
-            "content-type": "application/json"
-          }
-        }
-      );
+      return createFailureResponse(error, errorStatus);
     }
   };
 }
@@ -3231,23 +3356,13 @@ async function handleCheckpointRequestBody(args) {
   });
 }
 function createCheckpointRouteHandler(args) {
-  const { agent, errorStatus = 400 } = args;
+  const { agent, errorStatus } = args;
   return async function POST(request) {
     try {
-      const body = parseCheckpointRequestBody(await request.json());
+      const body = parseCheckpointRequestBody(await readRequestJson(request));
       return await handleCheckpointRequestBody({ agent, body });
     } catch (error) {
-      return new Response(
-        JSON.stringify({
-          error: toErrorMessage(error)
-        }),
-        {
-          status: errorStatus,
-          headers: {
-            "content-type": "application/json"
-          }
-        }
-      );
+      return createFailureResponse(error, errorStatus);
     }
   };
 }
@@ -3276,6 +3391,7 @@ var import_zod5 = require("zod");
 
 // src/execution/execute.ts
 var import_core4 = require("@kortyx/core");
+var import_errors5 = require("@kortyx/core/errors");
 var import_runtime3 = require("@kortyx/runtime");
 var import_zod3 = require("zod");
 
@@ -3283,32 +3399,37 @@ var import_zod3 = require("zod");
 var import_core3 = require("@kortyx/core");
 var import_runtime2 = require("@kortyx/runtime");
 
+// src/execution/types.ts
+var import_errors2 = require("@kortyx/core/errors");
+var ExecutionRequestError = class extends import_errors2.KortyxError {
+  name = "ExecutionRequestError";
+  constructor(code, message, cause) {
+    super(code, message, {
+      category: "request",
+      retryable: false,
+      safeMessage: "The execution request is invalid. Check the workflow contract and request fields.",
+      cause
+    });
+  }
+};
+
 // src/orchestrator.ts
 var import_node_stream = require("stream");
 var import_core2 = require("@kortyx/core");
+var import_errors4 = require("@kortyx/core/errors");
 var import_runtime = require("@kortyx/runtime");
 var import_langgraph = require("@langchain/langgraph");
 
 // src/execution/contracts.ts
+var import_errors3 = require("@kortyx/core/errors");
 var import_zod2 = require("zod");
-
-// src/execution/types.ts
-var ExecutionRequestError = class extends Error {
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-  }
-  code;
-  name = "ExecutionRequestError";
-};
-
-// src/execution/contracts.ts
 async function resolveExecutionWorkflow(select, reference) {
   const id = typeof reference === "string" ? reference : reference.id;
   let workflow;
   try {
     workflow = await select(id);
-  } catch {
+  } catch (error) {
+    if ((0, import_errors3.errorProperty)(error, "code") !== "UNKNOWN_WORKFLOW") throw error;
     throw new ExecutionRequestError(
       "UNKNOWN_WORKFLOW",
       `Workflow '${id}' is not registered.`
@@ -3338,10 +3459,8 @@ function parseExecutionInput(workflow, input) {
     import_zod2.z.json().parse(parsed);
     return parsed;
   } catch (error) {
-    throw new ExecutionRequestError(
-      "INVALID_INPUT",
-      error instanceof Error ? error.message : String(error)
-    );
+    if (!(error instanceof import_zod2.z.ZodError)) throw error;
+    throw new ExecutionRequestError("INVALID_INPUT", error.message, error);
   }
 }
 async function validateExecutionOutput(state, select) {
@@ -3350,7 +3469,9 @@ async function validateExecutionOutput(state, select) {
   const contract = state.config.executionContract;
   const root = await select(contract.id);
   if (root.id !== contract.id || root.version !== contract.version)
-    throw new Error("The root workflow changed since execution started.");
+    throw new import_errors3.WorkflowContractError(
+      "The root workflow changed since execution started."
+    );
   let data = state.data ?? {};
   try {
     for (const schema of /* @__PURE__ */ new Set([terminal.outputSchema, root.outputSchema])) {
@@ -3358,10 +3479,12 @@ async function validateExecutionOutput(state, select) {
     }
     if (terminal.outputSchema || root.outputSchema) import_zod2.z.json().parse(data);
   } catch (error) {
-    const failure = new Error(
-      `Workflow output validation failed: ${error instanceof Error ? error.message : String(error)}`
+    if (!(error instanceof import_zod2.z.ZodError)) throw error;
+    const failure = new import_errors3.ValidationError(
+      "INVALID_OUTPUT",
+      `Workflow output validation failed: ${error.message}`,
+      error
     );
-    Object.assign(failure, { code: "INVALID_OUTPUT" });
     throw failure;
   }
   return { ...state, data };
@@ -3873,7 +3996,8 @@ async function orchestrateGraphStream({
         interruptId,
         resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
         resumeOutcome: "failed",
-        resumeError: resumeError instanceof Error ? resumeError.message : String(resumeError)
+        resumeError: (0, import_errors4.serializeFailure)(resumeError).message,
+        failure: (0, import_errors4.serializeFailure)(resumeError)
       },
       flush: true
     });
@@ -3944,8 +4068,10 @@ async function orchestrateGraphStream({
     if (response.closed) outcomeState.config.responseCompleted = true;
     if (typeof frameworkAdapter?.checkpointer?.getTuple !== "function") return;
     for (const [token, request] of activePendingRequests) {
-      if (budget) request.state.config.executionBudget = budget;
-      if (response.closed) request.state.config.responseCompleted = true;
+      if (budget && request.state)
+        request.state.config.executionBudget = budget;
+      if (response.closed && request.state)
+        request.state.config.responseCompleted = true;
       const graphSnapshot = await (0, import_runtime.captureGraphSnapshot)(
         frameworkAdapter.checkpointer,
         runId,
@@ -4012,7 +4138,10 @@ async function orchestrateGraphStream({
     if (pendingStore) {
       const savePromise = pendingStore.save(record).catch((error) => {
         outcomeError = error;
-        console.error("[orchestrator] failed to save pending request", error);
+        console.error(
+          "[orchestrator] failed to save pending request",
+          (0, import_errors4.serializeFailure)(error)
+        );
       });
       pendingRequestWrites.push(savePromise);
     }
@@ -4084,8 +4213,13 @@ async function orchestrateGraphStream({
       const msg = String(
         payload?.message ?? "Unexpected error"
       );
-      outcomeError = new Error(msg);
-      write({ type: "error", message: msg });
+      const supplied = payload?.failure;
+      outcomeError = (0, import_errors4.isFailureDescriptor)(supplied) ? (0, import_errors4.errorFromFailure)(supplied) : new Error(msg);
+      write({
+        type: "error",
+        message: (0, import_errors4.serializeFailure)(outcomeError).message,
+        failure: (0, import_errors4.serializeFailure)(outcomeError)
+      });
       write({ type: "done" });
       finished = true;
       out.end();
@@ -4257,7 +4391,10 @@ async function orchestrateGraphStream({
         input: p?.input
       };
       void persistAndEmitInterrupt(local).catch((error) => {
-        console.error("[orchestrator] failed to emit interrupt", error);
+        console.error(
+          "[orchestrator] failed to emit interrupt",
+          (0, import_errors4.serializeFailure)(error)
+        );
       });
       return;
     }
@@ -4444,7 +4581,8 @@ async function orchestrateGraphStream({
           });
           write({
             type: "error",
-            message: `Transition failed to '${transitionTo}': ${err instanceof Error ? err.message : String(err)}`
+            message: (0, import_errors4.serializeFailure)(err).message,
+            failure: (0, import_errors4.serializeFailure)(err)
           });
           write({ type: "done" });
           out.end();
@@ -4493,7 +4631,10 @@ async function orchestrateGraphStream({
               }
             }
           } catch (e) {
-            console.error("[orchestrator] framework cleanup failed", e);
+            console.error(
+              "[orchestrator] framework cleanup failed",
+              (0, import_errors4.serializeFailure)(e)
+            );
           }
         }
         outcomeState = workflowFinalState;
@@ -4544,7 +4685,10 @@ async function orchestrateGraphStream({
             });
           } catch (error) {
             outcomeError = error;
-            console.error("[orchestrator] session checkpoint failed", error);
+            console.error(
+              "[orchestrator] session checkpoint failed",
+              (0, import_errors4.serializeFailure)(error)
+            );
           }
         }
         write({ type: "done", data: workflowFinalState });
@@ -4613,7 +4757,10 @@ async function orchestrateGraphStream({
           });
         } catch (error) {
           outcomeError = error;
-          console.error("[orchestrator] session checkpoint failed", error);
+          console.error(
+            "[orchestrator] session checkpoint failed",
+            (0, import_errors4.serializeFailure)(error)
+          );
         }
       }
       runTraceSpan.setAttributes?.({
@@ -4663,7 +4810,7 @@ async function orchestrateGraphStream({
     try {
       await frameworkAdapter?.cleanupRun?.(runId, [...namespacesUsed]);
     } catch (cleanupError) {
-      console.error("[cancel:cleanupRun]", cleanupError);
+      console.error("[cancel:cleanupRun]", (0, import_errors4.serializeFailure)(cleanupError));
     }
     outcomeError = (0, import_core2.createExecutionCancelledError)();
     fallbackRunSpan?.setAttributes?.({ "kortyx.run.cancelled": true });
@@ -4793,10 +4940,11 @@ async function orchestrateGraphStream({
     outcomeError = err;
     fallbackRunSpan?.fail?.(err);
     emitResumeFailure(err);
-    console.error("[error:orchestrateGraphStream]", err);
+    console.error("[error:orchestrateGraphStream]", (0, import_errors4.serializeFailure)(err));
     write({
       type: "error",
-      message: err instanceof Error ? err.message : String(err)
+      message: (0, import_errors4.serializeFailure)(err).message,
+      failure: (0, import_errors4.serializeFailure)(err)
     });
     write({ type: "done" });
     finished = true;
@@ -4864,12 +5012,16 @@ async function tryPrepareResumeStream({
   if (!store) return null;
   const pending = await store.get(meta.token);
   if (!pending || pending.requestId !== meta.requestId) {
-    throw new Error(
+    throw new ExecutionRequestError(
+      "INVALID_RESUME",
       "Interrupt is expired, already consumed, or does not match the request."
     );
   }
   if (pending.sessionId && pending.sessionId !== sessionId)
-    throw new Error("Interrupt belongs to another session.");
+    throw new ExecutionRequestError(
+      "RESUME_MISMATCH",
+      "Interrupt belongs to another session."
+    );
   await validatePending?.(pending);
   const isLimitPause = Boolean(pending.schema.meta?.__kortyxExecutionLimit);
   const savedBudget = pending.state?.config?.executionBudget;
@@ -4889,7 +5041,10 @@ async function tryPrepareResumeStream({
     })();
   }
   if (store.take && !await store.take(meta.token))
-    throw new Error("Interrupt has already been resumed or cancelled.");
+    throw new ExecutionRequestError(
+      "INVALID_RESUME",
+      "Interrupt has already been resumed or cancelled."
+    );
   if (meta.cancel) {
     await store.delete(pending.token);
     emitTelemetryEvent({
@@ -5077,10 +5232,7 @@ function resultFromOutcome(outcome, runId, sessionId) {
     return {
       ...info,
       status: "failed",
-      error: {
-        code: typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : "EXECUTION_FAILED",
-        message: error instanceof Error ? error.message : String(error)
-      }
+      error: (0, import_errors5.serializeFailure)(error)
     };
   }
   if (outcome.cancelled)
@@ -5254,10 +5406,11 @@ async function resumeWorkflow(services, args) {
         );
     }).catch(
       (error) => reject(
-        error instanceof ExecutionRequestError ? error : new ExecutionRequestError(
-          "INVALID_RESUME",
-          error instanceof Error ? error.message : String(error)
-        )
+        error instanceof Error ? error : new import_errors5.KortyxError("RESUME_FAILED", "Resume failed.", {
+          category: "persistence",
+          cause: error,
+          safeMessage: "The saved execution could not be resumed."
+        })
       )
     );
   });
@@ -5861,6 +6014,7 @@ function createAgent(args) {
   createAgent,
   createChatRouteHandler,
   createCheckpointRouteHandler,
+  createFailureResponse,
   extractLatestUserMessage,
   handleChatRequestBody,
   handleCheckpointRequestBody,
@@ -5869,6 +6023,7 @@ function createAgent(args) {
   parseCheckpointRequestBody,
   parseResumeMeta,
   projectWorkflowTopology,
+  readRequestJson,
   streamChat,
   streamChatFromRoute,
   transformGraphStreamForUI,