@kortyx/hooks 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.28.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.27.0...hooks-v0.28.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/core bumped to 0.10.0
+    * @kortyx/providers bumped to 0.8.1
+    * @kortyx/telemetry-contracts bumped to 0.11.0
+
+## [0.27.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.26.0...hooks-v0.27.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/telemetry-contracts bumped to 0.10.0
+
 ## [0.26.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.25.3...hooks-v0.26.0) (2026-09-18)
 
 

package/README.md

@@ -27,9 +27,16 @@ npm install @kortyx/hooks
 - `useRuntimeContext(...)` for request context made available to node execution.
 - `useNodeState(...)` / `useWorkflowState(...)` for stateful node logic.
 
-`useReason({ interrupt })` defaults to required interrupt behavior. Use
-`interrupt.mode: "optional"` when the model should decide whether to continue
-with a single model call or pause for user input.
+Define reusable model-driven human-input contracts with
+`defineInterruptContract(...)`, then pass one or more through
+`useReason({ interrupts: { contracts } })`. Contract calls share the ordinary
+tool loop, so tools can run before and after a pause. Use `mode: "optional"`
+when the model may finish without asking, and `maxRequests` to bound sequential
+human turns.
+
+The singular `useReason({ interrupt })` option and `result.interruptResponse`
+are deprecated and will be removed in the next major release. Migrate to
+`interrupts.contracts` and `result.interruptHistory`.
 
 ## Runtime Resume Behavior
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _kortyx_core from '@kortyx/core';
-import { WorkflowDefinition, TokenUsage, InterruptInput, GraphState, NodeConfig, InterruptResult } from '@kortyx/core';
-import { K as KortyxTelemetryConfig, R as ReasonTraceAdapter, a as KortyxTraceMetadata, b as KortyxTelemetryEventType } from './tracing-BUpf8RrV.js';
-export { E as EnsureWorkflowTopologyRequest, c as EnsureWorkflowTopologyResponse, d as KortyxErrorDetails, e as KortyxTelemetryContentCapture, f as KortyxTelemetryCorrelation, g as KortyxTelemetryEvent, h as KortyxTelemetryPrompt, i as KortyxTelemetryReporter, j as KortyxTelemetryService, k as KortyxTraceAdapter, l as KortyxTraceErrorProjection, m as ReasonTraceAttributes, n as ReasonTraceSpan, o as ReasonTraceSpanEndArgs, p as ReasonTraceSpanStartArgs } from './tracing-BUpf8RrV.js';
+import { WorkflowDefinition, TokenUsage, InterruptInput, GraphState, NodeConfig, InterruptResumeValue, InterruptResult } from '@kortyx/core';
+import { K as KortyxTelemetryConfig, R as ReasonTraceAdapter, a as KortyxTraceMetadata, b as ReportErrorOptions, c as KortyxTelemetryEventType } from './tracing-BsxYlgEw.js';
+export { E as EnsureWorkflowTopologyRequest, d as EnsureWorkflowTopologyResponse, e as KortyxErrorDetails, f as KortyxTelemetryContentCapture, g as KortyxTelemetryCorrelation, h as KortyxTelemetryEvent, i as KortyxTelemetryPrompt, j as KortyxTelemetryReporter, k as KortyxTelemetryService, l as KortyxTraceAdapter, m as KortyxTraceErrorProjection, n as ReasonTraceAttributes, o as ReasonTraceSpan, p as ReasonTraceSpanEndArgs, q as ReasonTraceSpanStartArgs } from './tracing-BsxYlgEw.js';
 import { FailureDescriptor, KortyxError } from '@kortyx/core/errors';
 import * as _kortyx_providers from '@kortyx/providers';
 import { ToolObservation, ProviderModelRef, KortyxReasoningOptions, KortyxResponseFormat, KortyxExecutableTool, KortyxUsage, KortyxFinishReason, KortyxProviderMetadata, KortyxWarning, KortyxToolCall, KortyxToolResult } from '@kortyx/providers';
@@ -95,7 +95,7 @@ type HookNodeRuntimeContext = {
     };
     config: NodeConfig;
     emit: (event: string, payload: unknown) => void;
-    awaitInterrupt: (args: InterruptInput) => InterruptResult;
+    awaitInterrupt: (args: InterruptInput) => InterruptResumeValue;
     callWorkflow?: WorkflowCallService;
     workflowCallTelemetry?: KortyxTelemetryConfig | undefined;
 };
@@ -120,6 +120,30 @@ type SchemaLike<T> = {
         };
     };
 };
+type InterruptContract<TRequest = unknown, TResponse = unknown> = {
+    /** Human-readable guidance included in the model-visible control tool. */
+    description: string;
+    requestSchema: SchemaLike<TRequest>;
+    responseSchema: SchemaLike<TResponse>;
+    /** Stable UI contract identifier. */
+    schemaId: string;
+    /** Version of the UI contract payload. */
+    schemaVersion: string;
+};
+type InterruptContractMap = Record<string, InterruptContract<unknown, unknown>>;
+type UseReasonInterruptsConfig<TContracts extends InterruptContractMap = InterruptContractMap> = {
+    mode?: "required" | "optional" | undefined;
+    /** Maximum number of model-requested human interactions for this operation. */
+    maxRequests?: number | undefined;
+    contracts: TContracts;
+};
+type InterruptHistoryEntry<TContracts extends InterruptContractMap = InterruptContractMap> = {
+    [TName in Extract<keyof TContracts, string>]: TContracts[TName] extends InterruptContract<infer TRequest, infer TResponse> ? {
+        contract: TName;
+        request: TRequest;
+        response: TResponse;
+    } : never;
+}[Extract<keyof TContracts, string>];
 type StructuredPath = string;
 type UseReasonStructuredFieldMode = "append" | "text-delta" | "set";
 type UseReasonStructuredFieldKey = string;
@@ -171,6 +195,10 @@ type UseReasonStructuredConfig = {
      */
     fields?: UseReasonStructuredFields | undefined;
 };
+/**
+ * @deprecated Use `UseReasonInterruptsConfig` and `defineInterruptContract`.
+ * Removed in the next major release.
+ */
 type UseReasonInterruptConfig<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult> = {
     mode?: "required" | "optional" | undefined;
     requestSchema: SchemaLike<TRequest>;
@@ -183,7 +211,7 @@ type UseReasonToolExecution = {
     approval?: boolean | Record<string, boolean> | undefined;
     emit?: boolean | Record<string, boolean> | undefined;
 };
-type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult> = {
+type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap> = {
     model: ProviderModelRef;
     input: string;
     system?: string | undefined;
@@ -200,7 +228,9 @@ type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = Interrup
     telemetry?: KortyxTraceMetadata | undefined;
     outputSchema?: SchemaLike<TOutput> | undefined;
     structured?: UseReasonStructuredConfig | undefined;
+    /** @deprecated Use `interrupts`. Removed in the next major release. */
     interrupt?: UseReasonInterruptConfig<TRequest, TResponse> | undefined;
+    interrupts?: UseReasonInterruptsConfig<TContracts> | undefined;
     tools?: KortyxExecutableTool[] | undefined;
     toolExecution?: UseReasonToolExecution | undefined;
 };
@@ -215,7 +245,7 @@ type UseReasonStep = {
     providerMetadata?: KortyxProviderMetadata | undefined;
     warnings?: KortyxWarning[] | undefined;
 };
-type UseReasonResult<TOutput = unknown, TResponse = InterruptResult> = {
+type UseReasonResult<TOutput = unknown, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap> = {
     id?: string;
     opId: string;
     text: string;
@@ -225,7 +255,9 @@ type UseReasonResult<TOutput = unknown, TResponse = InterruptResult> = {
     providerMetadata?: KortyxProviderMetadata;
     warnings?: KortyxWarning[];
     output?: TOutput;
+    /** @deprecated Use `interruptHistory`. Removed in the next major release. */
     interruptResponse?: TResponse;
+    interruptHistory?: InterruptHistoryEntry<TContracts>[];
     toolCalls?: KortyxToolCall[];
     toolResults?: KortyxToolResult[];
     steps?: UseReasonStep[];
@@ -239,10 +271,19 @@ type UseInterruptArgs<TRequest extends InterruptInput = InterruptInput, TRespons
     id?: string | undefined;
     meta?: Record<string, unknown> | undefined;
 };
+type UseContractInterruptArgs<TRequest, TResponse> = {
+    contract: InterruptContract<TRequest, TResponse>;
+    request: TRequest;
+    id?: string | undefined;
+    meta?: Record<string, unknown> | undefined;
+};
+
+declare const defineInterruptContract: <TRequest, TResponse>(contract: InterruptContract<TRequest, TResponse>) => InterruptContract<TRequest, TResponse>;
 
 type StateSetter<T> = (next: T | ((prev: T) => T)) => void;
 declare function useStructuredData<TData = unknown>(args: UseStructuredDataArgs<TData>): void;
-declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseReasonArgs<TOutput, TRequest, TResponse>): Promise<UseReasonResult<TOutput, TResponse>>;
+declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult, TContracts extends InterruptContractMap = InterruptContractMap>(args: UseReasonArgs<TOutput, TRequest, TResponse, TContracts>): Promise<UseReasonResult<TOutput, TResponse, TContracts>>;
+declare function useInterrupt<TRequest, TResponse>(args: UseContractInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
 declare function useInterrupt<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
 /** Live execution signal for cooperative I/O. Never store it in workflow state. */
 declare function useAbortSignal(): AbortSignal | undefined;
@@ -250,6 +291,9 @@ declare function useRuntimeContext<TContext extends Record<string, unknown> = Re
 declare function useNodeState<T>(initialValue: T): [T, StateSetter<T>];
 declare function useWorkflowState<T>(key: string, ...rest: [] | [T]): [T, StateSetter<T>];
 
+/** Reports a handled error to the configured observer without stopping execution. */
+declare function reportError(error: unknown, options?: ReportErrorOptions): void;
+
 type UseToolArgs<T extends KortyxExecutableTool> = {
     tool: T;
     input: Parameters<T["execute"]> extends [] ? unknown : Parameters<T["execute"]>[0];
@@ -261,4 +305,4 @@ declare function useTool<T extends KortyxExecutableTool>(args: UseToolArgs<T>):
 /** Best effort lifecycle facts. Engine snapshots and interrupt tokens never leave the runtime. */
 declare function emitWorkflowCall(telemetry: KortyxTelemetryConfig | undefined, type: KortyxTelemetryEventType, payload: Record<string, unknown>): void;
 
-export { type CompleteResponseOptions, type HookRuntimeContext, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ParallelError, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, type UseToolArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, emitWorkflowCall, parallel, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };
+export { type CompleteResponseOptions, type HookRuntimeContext, type InterruptContract, type InterruptContractMap, type InterruptHistoryEntry, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ParallelError, ReasonTraceAdapter, ReportErrorOptions, type UseContractInterruptArgs, type UseInterruptArgs, type UseReasonArgs, type UseReasonInterruptConfig, type UseReasonInterruptsConfig, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, type UseToolArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, defineInterruptContract, emitWorkflowCall, parallel, reportError, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };