@kortyx/hooks 0.30.1 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.31.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.30.2...hooks-v0.31.0) (2026-10-08)
+
+
+### Features
+
+* **telemetry:** preserve complete private error diagnostics ([#290](https://github.com/kortyx-io/kortyx/issues/290)) ([e1c5a88](https://github.com/kortyx-io/kortyx/commit/e1c5a88c494016fd84a1af40579412fcfde31271))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.12.0
+    * @kortyx/providers bumped to 0.9.0
+    * @kortyx/telemetry-contracts bumped to 0.15.0
+
+## [0.30.2](https://github.com/kortyx-io/kortyx/compare/hooks-v0.30.1...hooks-v0.30.2) (2026-10-07)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/providers bumped to 0.8.4
+    * @kortyx/telemetry-contracts bumped to 0.14.0
+
 ## [0.30.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.30.0...hooks-v0.30.1) (2026-10-03)
 
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _kortyx_core from '@kortyx/core';
 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 { K as KortyxTelemetryConfig, R as ReasonTraceAdapter, a as KortyxTraceMetadata, b as ReportErrorOptions, c as KortyxTelemetryEventType } from './tracing-mXE0Euvx.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-mXE0Euvx.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';

package/dist/index.js

@@ -717,52 +717,257 @@ var import_core2 = require("@kortyx/core");
 var import_errors3 = require("@kortyx/core/errors");
 
 // src/error-diagnostics.ts
+var import_telemetry_contracts2 = require("@kortyx/telemetry-contracts");
+
+// src/diagnostic-capture.ts
 var import_errors2 = require("@kortyx/core/errors");
-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);
+var import_telemetry_contracts = require("@kortyx/telemetry-contracts");
+var encoder = new TextEncoder();
+var nativeStackGetter = Object.getOwnPropertyDescriptor(
+  new Error(),
+  "stack"
+)?.get;
+function nativeStack(object, getter) {
+  if (!getter || getter !== nativeStackGetter)
+    throw new Error("Custom stack accessor");
+  for (const key of ["name", "message"]) {
+    let cursor = object;
+    while (cursor) {
+      const descriptor = Object.getOwnPropertyDescriptor(cursor, key);
+      if (descriptor) {
+        if (!("value" in descriptor) || typeof descriptor.value !== "string")
+          throw new Error("Custom error formatting");
+        break;
+      }
+      cursor = Object.getPrototypeOf(cursor);
+    }
+  }
+  const formatter = Object.getOwnPropertyDescriptor(Error, "prepareStackTrace");
+  if (formatter && (!("value" in formatter) || !formatter.writable))
+    throw new Error("Custom stack formatter");
+  Object.defineProperty(Error, "prepareStackTrace", {
+    ...formatter ?? { configurable: true, writable: true },
+    value: void 0
+  });
+  try {
+    return getter.call(object);
+  } finally {
+    if (formatter) Object.defineProperty(Error, "prepareStackTrace", formatter);
+    else Reflect.deleteProperty(Error, "prepareStackTrace");
   }
-  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 ? (() => {
+}
+var pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+function captureDiagnosticContent(error, project) {
+  const omissions = [];
+  const redactions = [];
+  const seen = /* @__PURE__ */ new WeakMap();
+  let nodes = 0;
+  let remaining = import_telemetry_contracts.DIAGNOSTIC_LIMITS.bytes - 64 * 1024;
+  const omit = (path, reason, extra = {}) => {
+    if (omissions.length < 1e3)
+      omissions.push({ path: path.slice(0, 4096), reason, ...extra });
+    return { $omitted: reason };
+  };
+  const visit = (value, path, depth) => {
+    if (++nodes > import_telemetry_contracts.DIAGNOSTIC_LIMITS.nodes) return omit(path, "node_limit");
+    if (depth > import_telemetry_contracts.DIAGNOSTIC_LIMITS.depth) return omit(path, "depth_limit");
+    if (typeof value === "string") {
+      const clean = (0, import_telemetry_contracts.redactDiagnosticText)(value);
+      if (clean !== value && redactions.length < 1e3)
+        redactions.push({
+          path: path.slice(0, 4096),
+          reason: "credential_text"
+        });
+      const bytes = encoder.encode(JSON.stringify(clean)).length;
+      if (bytes > remaining)
+        return omit(path, "byte_limit", {
+          originalBytes: encoder.encode(value).length
+        });
+      remaining -= bytes;
+      return clean;
+    }
+    if (value === null || typeof value === "boolean") return value;
+    if (typeof value === "number")
+      return Number.isFinite(value) ? value : { $type: "number", value: String(value) };
+    if (typeof value === "bigint")
+      return { $type: "bigint", value: value.toString() };
+    if (typeof value === "undefined") return { $type: "undefined" };
+    if (typeof value === "function" || typeof value === "symbol")
+      return omit(path, `unsupported_${typeof value}`);
+    const object = value;
+    const reference = seen.get(object);
+    if (reference) return { $ref: reference };
+    seen.set(object, path);
+    remaining -= 32;
+    if (remaining < 0) return omit(path, "byte_limit");
     try {
-      return value.stack;
+      if (value instanceof Date)
+        return { $type: "Date", value: Date.prototype.toISOString.call(value) };
+      if (value instanceof Map || value instanceof Set) {
+        const isMap = value instanceof Map;
+        const iterator = isMap ? Map.prototype.entries.call(value) : Set.prototype.values.call(value);
+        const count = Object.getOwnPropertyDescriptor(
+          isMap ? Map.prototype : Set.prototype,
+          "size"
+        )?.get?.call(value);
+        const entries = [];
+        for (let index = 0; index < Math.min(count, import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties); index++)
+          entries.push(iterator.next().value);
+        if (count > entries.length)
+          omissions.push({
+            path,
+            reason: "collection_limit",
+            originalCount: count
+          });
+        return isMap ? {
+          $type: "Map",
+          entries: visit(entries, `${path}/entries`, depth + 1)
+        } : {
+          $type: "Set",
+          values: visit(entries, `${path}/values`, depth + 1)
+        };
+      }
+      if (Array.isArray(value)) {
+        const count = Math.min(value.length, import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties);
+        const items = Array.from(
+          { length: count },
+          (_, index) => read(value, String(index), `${path}/${index}`, depth)
+        );
+        if (count < value.length)
+          items.push(
+            omit(path, "collection_limit", { originalCount: value.length })
+          );
+        return items;
+      }
+      const keys = Object.getOwnPropertyNames(object);
+      const result = /* @__PURE__ */ Object.create(null);
+      if (value instanceof Error) {
+        const ownName = Object.getOwnPropertyDescriptor(object, "name");
+        let type = ownName && "value" in ownName ? ownName.value : void 0;
+        if (typeof type !== "string") {
+          const name = Object.getOwnPropertyDescriptor(
+            Object.getPrototypeOf(value),
+            "name"
+          );
+          type = name && "value" in name ? name.value : "Error";
+        }
+        result.type = visit(
+          typeof type === "string" ? type : "Error",
+          `${path}/type`,
+          depth + 1
+        );
+      }
+      for (const key of keys.slice(0, import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties)) {
+        if (["__proto__", "constructor", "prototype"].includes(key)) {
+          result[key] = omit(`${path}/${pointer(key)}`, "unsafe_key");
+          continue;
+        }
+        remaining -= encoder.encode(key).length + 4;
+        result[key] = read(object, key, `${path}/${pointer(key)}`, depth);
+      }
+      if (keys.length > import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties)
+        result.$omittedProperties = omit(path, "property_limit", {
+          originalCount: keys.length
+        });
+      return result;
     } catch {
-      return void 0;
+      return omit(path, "unreadable_object");
+    }
+  };
+  const read = (object, key, path, depth) => {
+    if ((0, import_telemetry_contracts.isPrivateDiagnosticField)(key)) {
+      if (redactions.length < 1e3)
+        redactions.push({
+          path: path.slice(0, 4096),
+          reason: "credential_field"
+        });
+      return "[REDACTED]";
+    }
+    try {
+      const property = Object.getOwnPropertyDescriptor(object, key);
+      if (property && "value" in property)
+        return visit(property.value, path, depth + 1);
+      if (key === "stack" && object instanceof Error && property?.get && property.get === nativeStackGetter)
+        return visit(nativeStack(object, property.get), path, depth + 1);
+      return omit(
+        path,
+        property ? "accessor_not_evaluated" : "unavailable_property"
+      );
+    } catch {
+      return omit(path, "unreadable_property");
     }
-  })() : 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 details = project ? project(error) : projectDetails(error, 0, /* @__PURE__ */ new WeakSet());
-    return details ? sanitizeProjectedDetails(details) : null;
+    const original = project ? project(error) : error;
+    if (project && original === null) return null;
+    const captured = visit(original, "#/data", 0);
+    const upstreamOmissions = (0, import_errors2.errorProperty)(original, "diagnosticOmissions");
+    if (Array.isArray(upstreamOmissions))
+      for (const note of upstreamOmissions.slice(0, 1e3)) {
+        const path = (0, import_errors2.errorProperty)(note, "path");
+        const reason = (0, import_errors2.errorProperty)(note, "reason");
+        if (typeof path === "string" && typeof reason === "string")
+          omissions.push({
+            path: (0, import_telemetry_contracts.redactDiagnosticText)(path).slice(0, 4096),
+            reason: (0, import_telemetry_contracts.redactDiagnosticText)(reason).slice(0, 128)
+          });
+      }
+    const data = captured && typeof captured === "object" && !Array.isArray(captured) ? captured : {
+      type: "Error",
+      message: typeof captured === "string" ? captured : "Execution reported a fault.",
+      value: captured
+    };
+    if (typeof data.message !== "string" && !("message" in data))
+      data.message = "Execution reported a fault.";
+    if (!("type" in data))
+      data.type = typeof data.name === "string" ? data.name : "Error";
+    const content = {
+      schemaVersion: 1,
+      data,
+      capture: {
+        status: omissions.length ? "partial" : "complete",
+        omissions,
+        redactions
+      }
+    };
+    if (encoder.encode(JSON.stringify(content)).length > import_telemetry_contracts.DIAGNOSTIC_LIMITS.bytes)
+      return {
+        schemaVersion: 1,
+        data: {
+          type: "Error",
+          message: "Diagnostic exceeded the capture budget."
+        },
+        capture: {
+          status: "partial",
+          redactions: [],
+          omissions: [{ path: "#/data", reason: "serialized_byte_limit" }]
+        }
+      };
+    return content;
   } catch {
-    return null;
+    return {
+      schemaVersion: 1,
+      data: { type: "Error", message: "Diagnostic capture failed." },
+      capture: {
+        status: "failed",
+        redactions: [],
+        omissions: [{ path: "#/data", reason: "projection_or_capture_failed" }]
+      }
+    };
   }
 }
+
+// src/error-diagnostics.ts
+function exceptionDiagnostics(error, project) {
+  const content = captureDiagnosticContent(error, project);
+  return !content || content.capture.status === "failed" ? null : content.data;
+}
 function errorDiagnostics(error, project) {
-  const details = exceptionDiagnostics(error, project);
+  const captured = exceptionDiagnostics(error, project);
+  const details = captured ? (0, import_telemetry_contracts2.summarizeDiagnostic)(captured) : null;
   return details ? {
-    errorMessage: details.message,
-    ...details.type ? { errorType: details.type } : {}
+    errorMessage: details.message.slice(0, 8192),
+    ...details.type ? { errorType: details.type.slice(0, 256) } : {}
   } : {};
 }
 
@@ -854,10 +1059,40 @@ async function closeOwnedTools(owned) {
 function captureToolError(observation, error, policy, returned = false) {
   try {
     const reported = returned && error && typeof error === "object" && "isError" in error && error.isError === true && "content" in error && typeof error.content === "string" ? { name: "ToolError", message: error.content } : error;
+    let projected = false;
+    let projection;
+    let projectionFailure;
+    let projectionFailed = false;
+    const project = policy?.error ? (original) => {
+      if (!projected) {
+        projected = true;
+        try {
+          projection = policy.error?.(original);
+        } catch (error2) {
+          projectionFailure = error2;
+          projectionFailed = true;
+        }
+      }
+      if (projectionFailed) throw projectionFailure;
+      return projection ?? null;
+    } : void 0;
     Object.assign(
       observation,
-      errorDiagnostics(policy?.error ? error : reported, policy?.error)
+      errorDiagnostics(policy?.error ? error : reported, project)
+    );
+    const diagnosticId = getHookContext().reasonTrace?.reportError?.(
+      policy?.error ? error : reported,
+      {
+        mechanism: "tool",
+        ...project ? { error: project } : {},
+        correlation: {
+          toolCallId: observation.toolCallId,
+          attemptId: observation.attemptId
+        }
+      }
     );
+    if (typeof diagnosticId === "string")
+      observation.diagnosticId = diagnosticId;
   } catch {
   }
 }