kortyx 0.22.1 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.24.0](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.23.0...kortyx-v0.24.0) (2026-09-21)
+
+
+### Features
+
+* **hooks:** add model-driven interrupt contracts to useReason ([#224](https://github.com/kortyx-io/kortyx/issues/224)) ([e0147d5](https://github.com/kortyx-io/kortyx/commit/e0147d5234ca38d450d452af924b242f8cbdeb16))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/agent bumped to 0.26.0
+    * @kortyx/cli bumped to 0.11.0
+    * @kortyx/core bumped to 0.10.0
+    * @kortyx/hooks bumped to 0.28.0
+    * @kortyx/mcp bumped to 0.2.5
+    * @kortyx/providers bumped to 0.8.1
+    * @kortyx/runtime bumped to 0.21.0
+    * @kortyx/stream bumped to 0.13.0
+    * @kortyx/utils bumped to 0.3.1
+
+## [0.23.0](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.22.1...kortyx-v0.23.0) (2026-09-21)
+
+
+### Features
+
+* **observability:** report handled workflow errors ([#222](https://github.com/kortyx-io/kortyx/issues/222)) ([68a3b0e](https://github.com/kortyx-io/kortyx/commit/68a3b0eea5d93cb89bdcef63c4767f3b0d59e60d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/agent bumped to 0.25.1
+    * @kortyx/cli bumped to 0.10.1
+    * @kortyx/hooks bumped to 0.27.0
+    * @kortyx/runtime bumped to 0.20.1
+
 ## [0.22.1](https://github.com/kortyx-io/kortyx/compare/kortyx-v0.22.0...kortyx-v0.22.1) (2026-09-19)
 
 

package/README.md

@@ -263,6 +263,8 @@ Apache-2.0. See [LICENSE](https://github.com/kortyx-io/kortyx/blob/main/LICENSE)
 
 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).
 
+Throw ordinary `Error` instances when a workflow cannot continue; configured tracing records them automatically before the run fails. Use `reportError(error, {severity?, metadata?, tags?})` only for handled errors when application code deliberately continues with a fallback. Reporting is best-effort observation and never changes workflow control flow.
+
 ## Shared tools
 
 `await useTool({tool, input})` executes a typed plain tool immediately inside a workflow node, without a model call or MCP transport. Pass the same definition to `useReason({tools: [tool]})` for model-driven selection and arguments. Tool definitions can provide `outcomes.denialCodes`, `classifyResult` and `classifyError`; permission enforcement remains application-owned. Direct calls preserve result/error identity and do not cache executions.
@@ -270,4 +272,4 @@ Use `serializeFailure` for safe structured diagnostics and `DomainError` for exp
 Studio records individual durations and separate success, denial, fault and cancellation outcomes; cached native and child calls appear as reuse with their original scope. Tool faults automatically include error type and message (up to 256/8192 characters), without extra call-site wiring. Observations exclude raw inputs/results, exception objects, causes and stacks. Error messages are exported verbatim and can contain sensitive text; an optional tool `telemetry.error(error)` callback can replace them with `{type, message}` or return `null` to suppress them. Throwing projections suppress diagnostics and never alter execution. Observer and delivery failures cannot change execution. `kortyx topology push` discovers attached tools from source, marks dynamic attachments unresolved, and makes available tools visible before traffic.
 
 
-Configured Studio/OpenTelemetry tracing also captures model provider failures and `useReason` output-parsing failures automatically, including bounded error type/message. No extra wiring is needed. Studio opens the failed model event and displays reasoning/output failures separately when the model response itself completed normally. Prompts, outputs, exception stacks/causes and raw provider responses are excluded by default. Messages are verbatim; the optional trace adapter `error(error)` override can return `{type, message}` or `null` to replace/suppress model diagnostics without changing execution. Client-facing failure contracts remain unchanged.
+Configured Studio/OpenTelemetry tracing captures thrown workflow/model errors automatically, including bounded type, message, stack and cause details. Studio also records manual `reportError` calls as handled errors without failing the span. Prompts, outputs and raw provider responses remain excluded by default. Diagnostics are verbatim and may contain sensitive text; the optional trace adapter `error(error)` override can return `{type, message, stack?, cause?}` or `null` to replace or suppress them without changing execution. Client-facing failure contracts remain sanitized and unchanged.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, KortyxErrorDetails, KortyxTelemetryConfig, KortyxTelemetryContentCapture, KortyxTelemetryCorrelation, KortyxTelemetryEvent, KortyxTelemetryEventType, KortyxTelemetryPrompt, KortyxTelemetryReporter, KortyxTelemetryService, KortyxTraceAdapter, KortyxTraceErrorProjection, KortyxTraceMetadata, ParallelError, UseInterruptArgs, UseReasonArgs, UseReasonResult, UseReasonStep, UseReasonToolExecution, UseStructuredDataArgs, UseToolArgs, WorkflowCallError, completeResponse, createWorkflowHooks, parallel, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState } from '@kortyx/hooks';
+export { CompleteResponseOptions, EnsureWorkflowTopologyRequest, EnsureWorkflowTopologyResponse, InterruptContract, InterruptContractMap, InterruptHistoryEntry, KortyxErrorDetails, KortyxTelemetryConfig, KortyxTelemetryContentCapture, KortyxTelemetryCorrelation, KortyxTelemetryEvent, KortyxTelemetryEventType, KortyxTelemetryPrompt, KortyxTelemetryReporter, KortyxTelemetryService, KortyxTraceAdapter, KortyxTraceErrorProjection, KortyxTraceMetadata, ParallelError, ReportErrorOptions, UseContractInterruptArgs, UseInterruptArgs, UseReasonArgs, UseReasonInterruptConfig, UseReasonInterruptsConfig, UseReasonResult, UseReasonStep, UseReasonToolExecution, UseStructuredDataArgs, UseToolArgs, WorkflowCallError, completeResponse, createWorkflowHooks, defineInterruptContract, parallel, reportError, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState } from '@kortyx/hooks';
 export { CreateMCPClientArgs, MCPClient, McpToolsArgs, McpTransportConfig, createMCPClient } from '@kortyx/mcp';
 export * from '@kortyx/providers';
 export { CreateCachingFrameworkAdapterOptions, CreatePostgresFrameworkAdapterOptions, FrameworkAdapter, ManagedFrameworkAdapter, PostgresFrameworkAdapter, PruneRuntimeOptions, PruneRuntimeResult, RuntimeMaintenance, RuntimeRetentionPolicy, WorkflowRegistry, clearRegisteredNodes, createCachingFrameworkAdapter, createFileWorkflowRegistry, createFrameworkAdapterFromEnv, createInMemoryFrameworkAdapter, createInMemoryWorkflowRegistry, createPostgresFrameworkAdapter, createRedisFrameworkAdapter, getRegisteredNode, listRegisteredNodes, registerNode } from '@kortyx/runtime';

package/dist/index.js

@@ -44,6 +44,7 @@ __export(index_exports, {
   createStreamResponse: () => import_stream.createStreamResponse,
   createStructuredStreamAccumulator: () => import_stream.createStructuredStreamAccumulator,
   createWorkflowHooks: () => import_hooks.createWorkflowHooks,
+  defineInterruptContract: () => import_hooks.defineInterruptContract,
   defineWorkflow: () => import_core.defineWorkflow,
   getRegisteredNode: () => import_runtime.getRegisteredNode,
   handleChatRequestBody: () => import_agent.handleChatRequestBody,
@@ -57,6 +58,7 @@ __export(index_exports, {
   readStream: () => import_stream.readStream,
   reduceStructuredChunks: () => import_stream.reduceStructuredChunks,
   registerNode: () => import_runtime.registerNode,
+  reportError: () => import_hooks.reportError,
   streamChatFromRoute: () => import_agent.streamChatFromRoute,
   summarizeStreamChunks: () => import_stream.summarizeStreamChunks,
   toSSE: () => import_stream.toSSE,
@@ -106,6 +108,7 @@ var import_stream = require("@kortyx/stream");
   createStreamResponse,
   createStructuredStreamAccumulator,
   createWorkflowHooks,
+  defineInterruptContract,
   defineWorkflow,
   getRegisteredNode,
   handleChatRequestBody,
@@ -119,6 +122,7 @@ var import_stream = require("@kortyx/stream");
   readStream,
   reduceStructuredChunks,
   registerNode,
+  reportError,
   streamChatFromRoute,
   summarizeStreamChunks,
   toSSE,

package/dist/index.js.map

@@ -1 +1 @@
-{"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  KortyxErrorDetails,\n  KortyxTelemetryConfig,\n  KortyxTelemetryContentCapture,\n  KortyxTelemetryCorrelation,\n  KortyxTelemetryEvent,\n  KortyxTelemetryEventType,\n  KortyxTelemetryPrompt,\n  KortyxTelemetryReporter,\n  KortyxTelemetryService,\n  KortyxTraceAdapter,\n  KortyxTraceErrorProjection,\n  KortyxTraceMetadata,\n  UseInterruptArgs,\n  UseReasonArgs,\n  UseReasonResult,\n  UseReasonStep,\n  UseReasonToolExecution,\n  UseStructuredDataArgs,\n  UseToolArgs,\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  useTool,\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 {\n  CreateCachingFrameworkAdapterOptions,\n  CreatePostgresFrameworkAdapterOptions,\n  FrameworkAdapter,\n  ManagedFrameworkAdapter,\n  PostgresFrameworkAdapter,\n  PruneRuntimeOptions,\n  PruneRuntimeResult,\n  RuntimeMaintenance,\n  RuntimeRetentionPolicy,\n  WorkflowRegistry,\n} from \"@kortyx/runtime\";\nexport {\n  clearRegisteredNodes,\n  createCachingFrameworkAdapter,\n  createFileWorkflowRegistry,\n  createFrameworkAdapterFromEnv,\n  createInMemoryFrameworkAdapter,\n  createInMemoryWorkflowRegistry,\n  createPostgresFrameworkAdapter,\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;AAAA;AAAA;AAAA,0BAAc,gCAAd;AAwBA,mBAYO;AAeP,kBAA+D;AAwB/D,mBAgBO;AAOP,iBAAgC;AAChC,0BAAc,8BAnGd;AAgHA,qBAYO;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  InterruptContract,\n  InterruptContractMap,\n  InterruptHistoryEntry,\n  KortyxErrorDetails,\n  KortyxTelemetryConfig,\n  KortyxTelemetryContentCapture,\n  KortyxTelemetryCorrelation,\n  KortyxTelemetryEvent,\n  KortyxTelemetryEventType,\n  KortyxTelemetryPrompt,\n  KortyxTelemetryReporter,\n  KortyxTelemetryService,\n  KortyxTraceAdapter,\n  KortyxTraceErrorProjection,\n  KortyxTraceMetadata,\n  ReportErrorOptions,\n  UseContractInterruptArgs,\n  UseInterruptArgs,\n  UseReasonArgs,\n  UseReasonInterruptConfig,\n  UseReasonInterruptsConfig,\n  UseReasonResult,\n  UseReasonStep,\n  UseReasonToolExecution,\n  UseStructuredDataArgs,\n  UseToolArgs,\n} from \"@kortyx/hooks\";\nexport {\n  type CompleteResponseOptions,\n  completeResponse,\n  createWorkflowHooks,\n  defineInterruptContract,\n  ParallelError,\n  parallel,\n  reportError,\n  useAbortSignal,\n  useInterrupt,\n  useNodeState,\n  useReason,\n  useRuntimeContext,\n  useStructuredData,\n  useTool,\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 {\n  CreateCachingFrameworkAdapterOptions,\n  CreatePostgresFrameworkAdapterOptions,\n  FrameworkAdapter,\n  ManagedFrameworkAdapter,\n  PostgresFrameworkAdapter,\n  PruneRuntimeOptions,\n  PruneRuntimeResult,\n  RuntimeMaintenance,\n  RuntimeRetentionPolicy,\n  WorkflowRegistry,\n} from \"@kortyx/runtime\";\nexport {\n  clearRegisteredNodes,\n  createCachingFrameworkAdapter,\n  createFileWorkflowRegistry,\n  createFrameworkAdapterFromEnv,\n  createInMemoryFrameworkAdapter,\n  createInMemoryWorkflowRegistry,\n  createPostgresFrameworkAdapter,\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;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAc,gCAAd;AAwBA,mBAYO;AAeP,kBAA+D;AA+B/D,mBAkBO;AAOP,iBAAgC;AAChC,0BAAc,8BA5Gd;AAyHA,qBAYO;AASP,oBAWO;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kortyx",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "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/cli": "0.10.0",
-    "@kortyx/agent": "0.25.0",
-    "@kortyx/core": "0.9.0",
-    "@kortyx/hooks": "0.26.0",
-    "@kortyx/mcp": "0.2.4",
-    "@kortyx/providers": "0.8.0",
-    "@kortyx/runtime": "0.20.0",
-    "@kortyx/stream": "0.12.0",
-    "@kortyx/utils": "0.3.0"
+    "@kortyx/core": "0.10.0",
+    "@kortyx/cli": "0.11.0",
+    "@kortyx/agent": "0.26.0",
+    "@kortyx/hooks": "0.28.0",
+    "@kortyx/mcp": "0.2.5",
+    "@kortyx/providers": "0.8.1",
+    "@kortyx/stream": "0.13.0",
+    "@kortyx/runtime": "0.21.0",
+    "@kortyx/utils": "0.3.1"
   },
   "devDependencies": {
     "turbo": "2.6.1",