kortyx 0.19.0 → 0.20.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.20.1](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.20.0...kortyx-v0.20.1) (2026-09-14)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/agent bumped to 0.22.1
+    * @kortyx/cli bumped to 0.7.0
+    * @kortyx/hooks bumped to 0.25.1
+    * @kortyx/runtime bumped to 0.17.1
+
+## [0.20.0](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.19.0...kortyx-v0.20.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/agent bumped to 0.22.0
+    * @kortyx/cli bumped to 0.6.0
+    * @kortyx/core bumped to 0.9.0
+    * @kortyx/hooks bumped to 0.25.0
+    * @kortyx/mcp bumped to 0.2.3
+    * @kortyx/providers bumped to 0.7.0
+    * @kortyx/runtime bumped to 0.17.0
+    * @kortyx/stream bumped to 0.12.0
+    * @kortyx/utils bumped to 0.3.0
+
 ## [0.19.0](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.18.2...kortyx-v0.19.0) (2026-09-11)
 
 

package/README.md

@@ -258,3 +258,7 @@ are never emitted.
 ## License
 
 Apache-2.0. See [LICENSE](https://github.com/kortyx-io/kortyx/blob/main/LICENSE).
+
+## Error handling
+
+Use `serializeFailure` for safe structured diagnostics and `DomainError` for explicitly approved domain details that must survive child checkpoint restore. Cancellation, execution limits and human interrupts remain control flow. Applications own retry and schema correction policy. See the [error handling guide](../../apps/website/src/docs/v0/03-guides/08-error-handling.md).

package/dist/browser.d.ts

@@ -1,3 +1,4 @@
+export * from '@kortyx/core/errors';
 export { StreamChatFromRouteArgs, streamChatFromRoute } from '@kortyx/agent/browser';
 export { ConsumeStreamHandlers, StreamChunk, StreamFromRouteArgs, StructuredDataChunk, StructuredStreamAccumulator, StructuredStreamState, applyStructuredChunk, consumeStream, createStructuredStreamAccumulator, readStream, reduceStructuredChunks, streamFromRoute } from '@kortyx/stream/browser';
 import '@kortyx/agent';

package/dist/browser.js

@@ -14,6 +14,7 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/browser.ts
@@ -28,6 +29,7 @@ __export(browser_exports, {
   streamFromRoute: () => import_browser2.streamFromRoute
 });
 module.exports = __toCommonJS(browser_exports);
+__reExport(browser_exports, require("@kortyx/core/errors"), module.exports);
 var import_browser = require("@kortyx/agent/browser");
 var import_browser2 = require("@kortyx/stream/browser");
 // Annotate the CommonJS export names for ESM import in node:
@@ -38,6 +40,7 @@ var import_browser2 = require("@kortyx/stream/browser");
   readStream,
   reduceStructuredChunks,
   streamChatFromRoute,
-  streamFromRoute
+  streamFromRoute,
+  ...require("@kortyx/core/errors")
 });
 //# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["// Browser-safe exports for client bundles (e.g. Next.js Client Components).\n// Keep this file free of Node-only imports (fs, path, etc).\n\nexport type { StreamChatFromRouteArgs } from \"@kortyx/agent/browser\";\nexport { streamChatFromRoute } from \"@kortyx/agent/browser\";\nexport type {\n  ConsumeStreamHandlers,\n  StreamChunk,\n  StreamFromRouteArgs,\n  StructuredDataChunk,\n  StructuredStreamAccumulator,\n  StructuredStreamState,\n} from \"@kortyx/stream/browser\";\nexport {\n  applyStructuredChunk,\n  consumeStream,\n  createStructuredStreamAccumulator,\n  readStream,\n  reduceStructuredChunks,\n  streamFromRoute,\n} from \"@kortyx/stream/browser\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAIA,qBAAoC;AASpC,IAAAA,kBAOO;","names":["import_browser"]}
+{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["export * from \"@kortyx/core/errors\";\n// Browser-safe exports for client bundles (e.g. Next.js Client Components).\n// Keep this file free of Node-only imports (fs, path, etc).\n\nexport type { StreamChatFromRouteArgs } from \"@kortyx/agent/browser\";\nexport { streamChatFromRoute } from \"@kortyx/agent/browser\";\nexport type {\n  ConsumeStreamHandlers,\n  StreamChunk,\n  StreamFromRouteArgs,\n  StructuredDataChunk,\n  StructuredStreamAccumulator,\n  StructuredStreamState,\n} from \"@kortyx/stream/browser\";\nexport {\n  applyStructuredChunk,\n  consumeStream,\n  createStructuredStreamAccumulator,\n  readStream,\n  reduceStructuredChunks,\n  streamFromRoute,\n} from \"@kortyx/stream/browser\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,4BAAc,gCAAd;AAKA,qBAAoC;AASpC,IAAAA,kBAOO;","names":["import_browser"]}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { Agent, AgentProcessOptions, ChatRequestBody, CheckpointRequestBody, CreateAgentArgs, ExecutableWorkflow, ExecuteOptions, ExecutionInfo, ExecutionInterrupt, ExecutionRequestError, ExecutionResult, InterruptScope, ListInterruptsOptions, PendingInterrupt, ResumableInterrupt, ResumeHandle, ResumeOptions, ResumeResponse, StreamChatFromRouteArgs, createAgent, createChatRouteHandler, createCheckpointRouteHandler, handleChatRequestBody, handleCheckpointRequestBody, parseChatRequestBody, parseCheckpointRequestBody, streamChatFromRoute } from '@kortyx/agent';
+export * from '@kortyx/core/errors';
+export { Agent, AgentProcessOptions, ChatRequestBody, CheckpointRequestBody, CreateAgentArgs, ExecutableWorkflow, ExecuteOptions, ExecutionInfo, ExecutionInterrupt, ExecutionRequestError, ExecutionResult, InterruptScope, ListInterruptsOptions, PendingInterrupt, ResumableInterrupt, ResumeHandle, ResumeOptions, ResumeResponse, StreamChatFromRouteArgs, createAgent, createChatRouteHandler, createCheckpointRouteHandler, createFailureResponse, handleChatRequestBody, handleCheckpointRequestBody, parseChatRequestBody, parseCheckpointRequestBody, readRequestJson, streamChatFromRoute } from '@kortyx/agent';
 export { ExecutionLimit, ExecutionLimitReached, ExecutionLimits, GraphState, NodeConfig, NodeContext, NodeFn, NodeHandler, NodeResult, RuntimeEnvelope, WorkflowDefinition, WorkflowId, defineWorkflow, loadWorkflow, validateWorkflow } from '@kortyx/core';
 export { CompleteResponseOptions, EnsureWorkflowTopologyRequest, EnsureWorkflowTopologyResponse, KortyxTelemetryConfig, KortyxTelemetryContentCapture, KortyxTelemetryCorrelation, KortyxTelemetryEvent, KortyxTelemetryEventType, KortyxTelemetryPrompt, KortyxTelemetryReporter, KortyxTelemetryService, KortyxTraceAdapter, KortyxTraceMetadata, ParallelError, UseInterruptArgs, UseReasonArgs, UseReasonResult, UseReasonStep, UseReasonToolExecution, UseStructuredDataArgs, WorkflowCallError, completeResponse, createWorkflowHooks, parallel, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflow, useWorkflowState } from '@kortyx/hooks';
 export { CreateMCPClientArgs, MCPClient, McpToolsArgs, McpTransportConfig, createMCPClient } from '@kortyx/mcp';

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   createAgent: () => import_agent.createAgent,
   createChatRouteHandler: () => import_agent.createChatRouteHandler,
   createCheckpointRouteHandler: () => import_agent.createCheckpointRouteHandler,
+  createFailureResponse: () => import_agent.createFailureResponse,
   createFileWorkflowRegistry: () => import_runtime.createFileWorkflowRegistry,
   createFrameworkAdapterFromEnv: () => import_runtime.createFrameworkAdapterFromEnv,
   createInMemoryFrameworkAdapter: () => import_runtime.createInMemoryFrameworkAdapter,
@@ -50,6 +51,7 @@ __export(index_exports, {
   parallel: () => import_hooks.parallel,
   parseChatRequestBody: () => import_agent.parseChatRequestBody,
   parseCheckpointRequestBody: () => import_agent.parseCheckpointRequestBody,
+  readRequestJson: () => import_agent.readRequestJson,
   readStream: () => import_stream.readStream,
   reduceStructuredChunks: () => import_stream.reduceStructuredChunks,
   registerNode: () => import_runtime.registerNode,
@@ -67,6 +69,7 @@ __export(index_exports, {
   validateWorkflow: () => import_core.validateWorkflow
 });
 module.exports = __toCommonJS(index_exports);
+__reExport(index_exports, require("@kortyx/core/errors"), module.exports);
 var import_agent = require("@kortyx/agent");
 var import_core = require("@kortyx/core");
 var import_hooks = require("@kortyx/hooks");
@@ -88,6 +91,7 @@ var import_stream = require("@kortyx/stream");
   createAgent,
   createChatRouteHandler,
   createCheckpointRouteHandler,
+  createFailureResponse,
   createFileWorkflowRegistry,
   createFrameworkAdapterFromEnv,
   createInMemoryFrameworkAdapter,
@@ -106,6 +110,7 @@ var import_stream = require("@kortyx/stream");
   parallel,
   parseChatRequestBody,
   parseCheckpointRequestBody,
+  readRequestJson,
   readStream,
   reduceStructuredChunks,
   registerNode,
@@ -121,6 +126,7 @@ var import_stream = require("@kortyx/stream");
   useWorkflow,
   useWorkflowState,
   validateWorkflow,
+  ...require("@kortyx/core/errors"),
   ...require("@kortyx/providers")
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// release-test: 2026-01-22\n// Public DX surface for the Kortyx framework.\n\nexport type {\n  Agent,\n  AgentProcessOptions,\n  ChatRequestBody,\n  CheckpointRequestBody,\n  CreateAgentArgs,\n  ExecutableWorkflow,\n  ExecuteOptions,\n  ExecutionInfo,\n  ExecutionInterrupt,\n  ExecutionResult,\n  InterruptScope,\n  ListInterruptsOptions,\n  PendingInterrupt,\n  ResumableInterrupt,\n  ResumeHandle,\n  ResumeOptions,\n  ResumeResponse,\n  StreamChatFromRouteArgs,\n} from \"@kortyx/agent\";\nexport {\n  createAgent,\n  createChatRouteHandler,\n  createCheckpointRouteHandler,\n  ExecutionRequestError,\n  handleChatRequestBody,\n  handleCheckpointRequestBody,\n  parseChatRequestBody,\n  parseCheckpointRequestBody,\n  streamChatFromRoute,\n} from \"@kortyx/agent\";\nexport type {\n  ExecutionLimit,\n  ExecutionLimitReached,\n  ExecutionLimits,\n  GraphState,\n  NodeConfig,\n  NodeContext,\n  NodeFn,\n  NodeHandler,\n  NodeResult,\n  RuntimeEnvelope,\n  WorkflowDefinition,\n  WorkflowId,\n} from \"@kortyx/core\";\nexport { defineWorkflow, loadWorkflow, validateWorkflow } from \"@kortyx/core\";\nexport type {\n  EnsureWorkflowTopologyRequest,\n  EnsureWorkflowTopologyResponse,\n  KortyxTelemetryConfig,\n  KortyxTelemetryContentCapture,\n  KortyxTelemetryCorrelation,\n  KortyxTelemetryEvent,\n  KortyxTelemetryEventType,\n  KortyxTelemetryPrompt,\n  KortyxTelemetryReporter,\n  KortyxTelemetryService,\n  KortyxTraceAdapter,\n  KortyxTraceMetadata,\n  UseInterruptArgs,\n  UseReasonArgs,\n  UseReasonResult,\n  UseReasonStep,\n  UseReasonToolExecution,\n  UseStructuredDataArgs,\n} from \"@kortyx/hooks\";\nexport {\n  type CompleteResponseOptions,\n  completeResponse,\n  createWorkflowHooks,\n  ParallelError,\n  parallel,\n  useAbortSignal,\n  useInterrupt,\n  useNodeState,\n  useReason,\n  useRuntimeContext,\n  useStructuredData,\n  useWorkflow,\n  useWorkflowState,\n  WorkflowCallError,\n} from \"@kortyx/hooks\";\nexport type {\n  CreateMCPClientArgs,\n  MCPClient,\n  McpToolsArgs,\n  McpTransportConfig,\n} from \"@kortyx/mcp\";\nexport { createMCPClient } from \"@kortyx/mcp\";\nexport * from \"@kortyx/providers\";\nexport type { WorkflowRegistry } from \"@kortyx/runtime\";\nexport {\n  clearRegisteredNodes,\n  createFileWorkflowRegistry,\n  createFrameworkAdapterFromEnv,\n  createInMemoryFrameworkAdapter,\n  createInMemoryWorkflowRegistry,\n  createRedisFrameworkAdapter,\n  getRegisteredNode,\n  listRegisteredNodes,\n  registerNode,\n} from \"@kortyx/runtime\";\nexport type {\n  BufferedStreamResult,\n  ConsumeStreamHandlers,\n  StreamChunk,\n  StructuredDataChunk,\n  StructuredStreamAccumulator,\n  StructuredStreamState,\n} from \"@kortyx/stream\";\nexport {\n  applyStructuredChunk,\n  collectBufferedStream,\n  collectStream,\n  consumeStream,\n  createStreamResponse,\n  createStructuredStreamAccumulator,\n  readStream,\n  reduceStructuredChunks,\n  summarizeStreamChunks,\n  toSSE,\n} from \"@kortyx/stream\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBA,mBAUO;AAeP,kBAA+D;AAqB/D,mBAeO;AAOP,iBAAgC;AAChC,0BAAc,8BA5Fd;AA8FA,qBAUO;AASP,oBAWO;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"@kortyx/core/errors\";\n// release-test: 2026-01-22\n// Public DX surface for the Kortyx framework.\n\nexport type {\n  Agent,\n  AgentProcessOptions,\n  ChatRequestBody,\n  CheckpointRequestBody,\n  CreateAgentArgs,\n  ExecutableWorkflow,\n  ExecuteOptions,\n  ExecutionInfo,\n  ExecutionInterrupt,\n  ExecutionResult,\n  InterruptScope,\n  ListInterruptsOptions,\n  PendingInterrupt,\n  ResumableInterrupt,\n  ResumeHandle,\n  ResumeOptions,\n  ResumeResponse,\n  StreamChatFromRouteArgs,\n} from \"@kortyx/agent\";\nexport {\n  createAgent,\n  createChatRouteHandler,\n  createCheckpointRouteHandler,\n  createFailureResponse,\n  ExecutionRequestError,\n  handleChatRequestBody,\n  handleCheckpointRequestBody,\n  parseChatRequestBody,\n  parseCheckpointRequestBody,\n  readRequestJson,\n  streamChatFromRoute,\n} from \"@kortyx/agent\";\nexport type {\n  ExecutionLimit,\n  ExecutionLimitReached,\n  ExecutionLimits,\n  GraphState,\n  NodeConfig,\n  NodeContext,\n  NodeFn,\n  NodeHandler,\n  NodeResult,\n  RuntimeEnvelope,\n  WorkflowDefinition,\n  WorkflowId,\n} from \"@kortyx/core\";\nexport { defineWorkflow, loadWorkflow, validateWorkflow } from \"@kortyx/core\";\nexport type {\n  EnsureWorkflowTopologyRequest,\n  EnsureWorkflowTopologyResponse,\n  KortyxTelemetryConfig,\n  KortyxTelemetryContentCapture,\n  KortyxTelemetryCorrelation,\n  KortyxTelemetryEvent,\n  KortyxTelemetryEventType,\n  KortyxTelemetryPrompt,\n  KortyxTelemetryReporter,\n  KortyxTelemetryService,\n  KortyxTraceAdapter,\n  KortyxTraceMetadata,\n  UseInterruptArgs,\n  UseReasonArgs,\n  UseReasonResult,\n  UseReasonStep,\n  UseReasonToolExecution,\n  UseStructuredDataArgs,\n} from \"@kortyx/hooks\";\nexport {\n  type CompleteResponseOptions,\n  completeResponse,\n  createWorkflowHooks,\n  ParallelError,\n  parallel,\n  useAbortSignal,\n  useInterrupt,\n  useNodeState,\n  useReason,\n  useRuntimeContext,\n  useStructuredData,\n  useWorkflow,\n  useWorkflowState,\n  WorkflowCallError,\n} from \"@kortyx/hooks\";\nexport type {\n  CreateMCPClientArgs,\n  MCPClient,\n  McpToolsArgs,\n  McpTransportConfig,\n} from \"@kortyx/mcp\";\nexport { createMCPClient } from \"@kortyx/mcp\";\nexport * from \"@kortyx/providers\";\nexport type { WorkflowRegistry } from \"@kortyx/runtime\";\nexport {\n  clearRegisteredNodes,\n  createFileWorkflowRegistry,\n  createFrameworkAdapterFromEnv,\n  createInMemoryFrameworkAdapter,\n  createInMemoryWorkflowRegistry,\n  createRedisFrameworkAdapter,\n  getRegisteredNode,\n  listRegisteredNodes,\n  registerNode,\n} from \"@kortyx/runtime\";\nexport type {\n  BufferedStreamResult,\n  ConsumeStreamHandlers,\n  StreamChunk,\n  StructuredDataChunk,\n  StructuredStreamAccumulator,\n  StructuredStreamState,\n} from \"@kortyx/stream\";\nexport {\n  applyStructuredChunk,\n  collectBufferedStream,\n  collectStream,\n  consumeStream,\n  createStreamResponse,\n  createStructuredStreamAccumulator,\n  readStream,\n  reduceStructuredChunks,\n  summarizeStreamChunks,\n  toSSE,\n} from \"@kortyx/stream\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,gCAAd;AAwBA,mBAYO;AAeP,kBAA+D;AAqB/D,mBAeO;AAOP,iBAAgC;AAChC,0BAAc,8BA/Fd;AAiGA,qBAUO;AASP,oBAWO;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kortyx",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "private": false,
   "description": "TypeScript framework for production AI agents with explicit workflows, provider-agnostic models, streaming, interrupts, and runtime persistence.",
   "keywords": [
@@ -43,15 +43,15 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@kortyx/agent": "0.21.0",
-    "@kortyx/cli": "0.5.6",
-    "@kortyx/hooks": "0.24.0",
-    "@kortyx/core": "0.8.0",
-    "@kortyx/mcp": "0.2.2",
-    "@kortyx/providers": "0.6.1",
-    "@kortyx/runtime": "0.16.0",
-    "@kortyx/utils": "0.2.6",
-    "@kortyx/stream": "0.11.0"
+    "@kortyx/agent": "0.22.1",
+    "@kortyx/cli": "0.7.0",
+    "@kortyx/core": "0.9.0",
+    "@kortyx/hooks": "0.25.1",
+    "@kortyx/mcp": "0.2.3",
+    "@kortyx/runtime": "0.17.1",
+    "@kortyx/stream": "0.12.0",
+    "@kortyx/providers": "0.7.0",
+    "@kortyx/utils": "0.3.0"
   },
   "devDependencies": {
     "turbo": "2.6.1",