@kortyx/hooks 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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/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 { 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';
@@ -250,6 +250,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 +264,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, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ParallelError, ReasonTraceAdapter, ReportErrorOptions, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, type UseToolArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, emitWorkflowCall, parallel, reportError, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useTool, useWorkflow, useWorkflowState, workflowCallFingerprint };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   createWorkflowHooks: () => createWorkflowHooks,
   emitWorkflowCall: () => emitWorkflowCall,
   parallel: () => parallel,
+  reportError: () => reportError,
   runWithHookContext: () => runWithHookContext,
   useAbortSignal: () => useAbortSignal,
   useInterrupt: () => useInterrupt,
@@ -531,26 +532,53 @@ var import_errors3 = require("@kortyx/core/errors");
 
 // src/error-diagnostics.ts
 var import_errors2 = require("@kortyx/core/errors");
-function errorDiagnostics(error, project) {
+var MAX_STACK_LENGTH = 32768;
+var MAX_CAUSE_DEPTH = 4;
+var projectDetails = (value, depth, seen) => {
+  const objectValue = value && typeof value === "object" ? value : void 0;
+  if (objectValue) {
+    if (seen.has(objectValue))
+      return { type: "Error", message: "Circular error cause." };
+    seen.add(objectValue);
+  }
+  const name = (0, import_errors2.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
+  const message = (0, import_errors2.errorProperty)(value, "message");
+  const stack = (0, import_errors2.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
+    try {
+      return value.stack;
+    } catch {
+      return void 0;
+    }
+  })() : void 0);
+  const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors2.errorProperty)(value, "cause") : null;
+  return {
+    type: typeof name === "string" ? name.slice(0, 256) : "Error",
+    message: (typeof value === "string" ? value : typeof message === "string" ? message : "Execution reported a fault.").slice(0, 8192),
+    ...typeof stack === "string" ? { stack: stack.slice(0, MAX_STACK_LENGTH) } : {},
+    ...cause !== null && cause !== void 0 ? { cause: projectDetails(cause, depth + 1, seen) } : {}
+  };
+};
+var sanitizeProjectedDetails = (details, depth = 0) => ({
+  ...typeof details.type === "string" ? { type: details.type.slice(0, 256) } : {},
+  message: typeof details.message === "string" ? details.message.slice(0, 8192) : "Execution reported a fault.",
+  ...typeof details.stack === "string" ? { stack: details.stack.slice(0, MAX_STACK_LENGTH) } : {},
+  ...depth < MAX_CAUSE_DEPTH && details.cause ? { cause: sanitizeProjectedDetails(details.cause, depth + 1) } : {}
+});
+function exceptionDiagnostics(error, project) {
   try {
-    const name = (0, import_errors2.errorProperty)(error, "name") ?? (error instanceof Error ? error.name : void 0);
-    const message = (0, import_errors2.errorProperty)(error, "message");
-    const details = project ? project(error) : {
-      type: typeof name === "string" ? name : "Error",
-      message: typeof error === "string" ? error : typeof message === "string" ? message : "Execution reported a fault."
-    };
-    if (!details) return {};
-    const projectedMessage = details.message;
-    const projectedType = details.type;
-    if (typeof projectedMessage !== "string") return {};
-    return {
-      errorMessage: projectedMessage.slice(0, 8192),
-      ...typeof projectedType === "string" ? { errorType: projectedType.slice(0, 256) } : {}
-    };
+    const details = project ? project(error) : projectDetails(error, 0, /* @__PURE__ */ new WeakSet());
+    return details ? sanitizeProjectedDetails(details) : null;
   } catch {
-    return {};
+    return null;
   }
 }
+function errorDiagnostics(error, project) {
+  const details = exceptionDiagnostics(error, project);
+  return details ? {
+    errorMessage: details.message,
+    ...details.type ? { errorType: details.type } : {}
+  } : {};
+}
 
 // src/workflow-telemetry.ts
 var import_node_crypto2 = require("crypto");
@@ -3387,6 +3415,14 @@ function parallel(values) {
   return promise;
 }
 
+// src/report-error.ts
+function reportError(error, options = {}) {
+  try {
+    getReasonTraceAdapter()?.reportError?.(error, options);
+  } catch {
+  }
+}
+
 // src/workflow.ts
 var import_node_crypto6 = require("crypto");
 var import_core8 = require("@kortyx/core");
@@ -3663,6 +3699,7 @@ async function runWorkflowCall(args, task) {
   createWorkflowHooks,
   emitWorkflowCall,
   parallel,
+  reportError,
   runWithHookContext,
   useAbortSignal,
   useInterrupt,