@kortyx/hooks 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.15.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.14.0...hooks-v0.15.0) (2026-05-24)
+
+
+### Features
+
+* add OpenTelemetry tracing adapter ([dc1218f](https://github.com/kortyx-io/kortyx/commit/dc1218fb3759b8cb467f6c58f953a80127b25783))
+
+## [0.14.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.13.0...hooks-v0.14.0) (2026-05-22)
+
+
+### Features
+
+* **hooks:** support wildcard structured streaming ([cdc646c](https://github.com/kortyx-io/kortyx/commit/cdc646cf7e3a8f36fc62d0cb4123a427eb823f8f))
+* **hooks:** support wildcard structured streaming ([fa7fec7](https://github.com/kortyx-io/kortyx/commit/fa7fec7f5a86a5bad73f3889b9698b8eb62451df))
+
 ## [0.13.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.12.1...hooks-v0.13.0) (2026-05-22)
 
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { NodeConfig, InterruptInput, InterruptResult, GraphState } from '@kortyx/core';
-import { R as ReasonTraceAdapter } from './tracing-BG-j1cer.js';
-export { a as ReasonTraceAttributes, b as ReasonTraceSpan, c as ReasonTraceSpanEndArgs, d as ReasonTraceSpanStartArgs } from './tracing-BG-j1cer.js';
+import { R as ReasonTraceAdapter, K as KortyxTraceMetadata } from './tracing-DK-T8zX5.js';
+export { a as KortyxTelemetryConfig, b as KortyxTelemetryContentCapture, c as KortyxTelemetryPrompt, d as KortyxTraceAdapter, e as ReasonTraceAttributes, f as ReasonTraceSpan, g as ReasonTraceSpanEndArgs, h as ReasonTraceSpanStartArgs } from './tracing-DK-T8zX5.js';
 import { ProviderModelRef, KortyxReasoningOptions, KortyxResponseFormat, KortyxUsage, KortyxFinishReason, KortyxProviderMetadata, KortyxWarning } from '@kortyx/providers';
 
 type HookNodeRuntimeContext = {
@@ -79,7 +79,8 @@ type UseReasonStructuredConfig = {
     schemaVersion?: string | undefined;
     /**
      * Incremental extraction paths for useReason. Dotted paths target nested
-     * object fields, and numeric segments target array indexes.
+     * object fields, numeric segments target array indexes, and `*` matches one
+     * object key or array index segment.
      */
     fields?: UseReasonStructuredFields | undefined;
 };
@@ -104,6 +105,7 @@ type UseReasonArgs<TOutput = unknown, TRequest extends InterruptInput = Interrup
     emit?: boolean | undefined;
     stream?: boolean | undefined;
     id?: string | undefined;
+    telemetry?: KortyxTraceMetadata | undefined;
     outputSchema?: SchemaLike<TOutput> | undefined;
     structured?: UseReasonStructuredConfig | undefined;
     interrupt?: UseReasonInterruptConfig<TRequest, TResponse> | undefined;
@@ -138,4 +140,4 @@ 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>];
 
-export { type HookRuntimeContext, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseStructuredDataArgs, runWithHookContext, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflowState };
+export { type HookRuntimeContext, KortyxTraceMetadata, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseStructuredDataArgs, runWithHookContext, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflowState };

package/dist/index.js

@@ -403,7 +403,15 @@ async function runReasonEngine(args) {
       modelId: args.model.modelId,
       stream,
       emit,
+      ...args.telemetry?.operation ? { operation: args.telemetry.operation } : {},
+      ...args.telemetry?.prompt?.name ? { promptName: args.telemetry.prompt.name } : {},
+      ...args.telemetry?.prompt?.version !== void 0 ? { promptVersion: args.telemetry.prompt.version } : {},
+      ...args.telemetry?.prompt?.type ? { promptType: args.telemetry.prompt.type } : {},
       ...typeof args.nodeId === "string" && args.nodeId.length > 0 ? { nodeId: args.nodeId } : {}
+    },
+    telemetry: {
+      ...args.telemetry ?? {},
+      input: args.telemetry?.input ?? messages
     }
   });
   const endTrace = (span, result) => {
@@ -414,6 +422,10 @@ async function runReasonEngine(args) {
       ...result.warnings !== void 0 ? { warnings: result.warnings } : {},
       attributes: {
         textLength: result.text.length
+      },
+      telemetry: {
+        ...args.telemetry ?? {},
+        output: args.telemetry?.output ?? result.text
       }
     });
   };
@@ -570,6 +582,7 @@ async function reasonEngine(args, meta, inputOverride) {
     stream: args.stream,
     emit: args.emit,
     onTextChunk: args.onTextChunk,
+    telemetry: args.telemetry,
     nodeId: ctx.node.graph.node,
     emitEvent: ctx.node.emit,
     reasonTrace: ctx.reasonTrace,
@@ -862,12 +875,12 @@ var withStructuredStreamHints = (input, args) => {
   const rules = [];
   for (const path of args.setFieldPaths ?? []) {
     rules.push(
-      `- For the field path \`${path}\`, write one stable final value and do not rewrite it after it is complete.`
+      `- For the field path pattern \`${path}\`, write one stable final value and do not rewrite it after it is complete.`
     );
   }
   for (const path of args.appendFieldPaths ?? []) {
     rules.push(
-      `- For the array field path \`${path}\`, write items in final order and finish each item before starting the next.`
+      `- For the array field path pattern \`${path}\`, write items in final order and finish each item before starting the next.`
     );
     rules.push(
       `- Once an item in \`${path}\` is complete, do not rewrite or reorder earlier items.`
@@ -875,7 +888,7 @@ var withStructuredStreamHints = (input, args) => {
   }
   for (const path of args.textDeltaFieldPaths ?? []) {
     rules.push(
-      `- For the string field path \`${path}\`, write the value progressively by appending text to the end.`
+      `- For the string field path pattern \`${path}\`, write the value progressively by appending text to the end.`
     );
     rules.push(
       `- Do not rewrite or replace the earlier prefix of \`${path}\` once emitted.`
@@ -968,8 +981,11 @@ var skipWhitespace = (text, start) => {
   while (i < text.length && /\s/.test(text[i] ?? "")) i += 1;
   return i;
 };
-var pathEquals = (left, right) => left.length === right.length && left.every((part, index) => part === right[index]);
-var isPathPrefix = (prefix, full) => prefix.length <= full.length && prefix.every((part, index) => part === full[index]);
+var pathSegmentMatches = (patternPart, actualPart) => patternPart === "*" || patternPart === actualPart;
+var pathMatchesPattern = (actualParts, patternParts) => actualParts.length === patternParts.length && actualParts.every(
+  (part, index) => pathSegmentMatches(patternParts[index] ?? "", part)
+);
+var isPathPrefix = (prefix, full) => prefix.length <= full.length && prefix.every((part, index) => pathSegmentMatches(full[index] ?? "", part));
 var parseStringToken = (text, start) => {
   if (text[start] !== '"') return { complete: false };
   const parsed = extractCompletedStringValueAt({ text, start: start + 1 });
@@ -1064,78 +1080,92 @@ var skipCompleteValue = (text, start) => {
   return { complete: false };
 };
 var locateValueStart = (args) => {
+  const [first] = locateValueStarts(args);
+  return first ? {
+    found: true,
+    start: first.start
+  } : {
+    found: false
+  };
+};
+var locateValueStarts = (args) => {
   const targetParts = parseStructuredPath(
     args.path,
     "useReason structured field"
   );
+  const matches = [];
   const visitValue = (start, currentParts) => {
     const valueStart = skipWhitespace(args.text, start);
-    if (pathEquals(currentParts, targetParts)) {
-      return { found: true, start: valueStart };
+    if (pathMatchesPattern(currentParts, targetParts)) {
+      matches.push({
+        path: currentParts.join("."),
+        start: valueStart
+      });
+      return;
     }
     if (!isPathPrefix(currentParts, targetParts)) {
-      return { found: false };
+      return;
     }
     const first = args.text[valueStart];
-    if (first === "{") return visitObject(valueStart + 1, currentParts);
-    if (first === "[") return visitArray(valueStart + 1, currentParts);
-    return { found: false };
+    if (first === "{") visitObject(valueStart + 1, currentParts);
+    if (first === "[") visitArray(valueStart + 1, currentParts);
   };
   const visitObject = (start, currentParts) => {
     let i = skipWhitespace(args.text, start);
     while (i < args.text.length) {
       const ch = args.text[i];
-      if (ch === "}") return { found: false };
+      if (ch === "}") return;
       if (ch === ",") {
         i = skipWhitespace(args.text, i + 1);
         continue;
       }
-      if (ch !== '"') return { found: false };
+      if (ch !== '"') return;
       const key = parseStringToken(args.text, i);
       if (!key.complete || key.end === void 0 || key.value === void 0) {
-        return { found: false };
+        return;
       }
       i = skipWhitespace(args.text, key.end);
-      if (args.text[i] !== ":") return { found: false };
+      if (args.text[i] !== ":") return;
       const valueStart = skipWhitespace(args.text, i + 1);
       const childParts = [...currentParts, key.value];
-      if (pathEquals(childParts, targetParts)) {
-        return { found: true, start: valueStart };
-      }
-      if (isPathPrefix(childParts, targetParts)) {
-        const nested = visitValue(valueStart, childParts);
-        if (nested.found) return nested;
+      if (pathMatchesPattern(childParts, targetParts)) {
+        matches.push({
+          path: childParts.join("."),
+          start: valueStart
+        });
+      } else if (isPathPrefix(childParts, targetParts)) {
+        visitValue(valueStart, childParts);
       }
       const skipped = skipCompleteValue(args.text, valueStart);
       if (!skipped.complete || skipped.end === void 0) {
-        return { found: false };
+        return;
       }
       i = skipWhitespace(args.text, skipped.end);
       if (args.text[i] === ",") {
         i = skipWhitespace(args.text, i + 1);
         continue;
       }
-      if (args.text[i] === "}") return { found: false };
-      return { found: false };
+      if (args.text[i] === "}") return;
+      return;
     }
-    return { found: false };
   };
   const visitArray = (start, currentParts) => {
     let i = skipWhitespace(args.text, start);
     let index = 0;
     while (i < args.text.length) {
-      if (args.text[i] === "]") return { found: false };
+      if (args.text[i] === "]") return;
       const childParts = [...currentParts, String(index)];
-      if (pathEquals(childParts, targetParts)) {
-        return { found: true, start: i };
-      }
-      if (isPathPrefix(childParts, targetParts)) {
-        const nested = visitValue(i, childParts);
-        if (nested.found) return nested;
+      if (pathMatchesPattern(childParts, targetParts)) {
+        matches.push({
+          path: childParts.join("."),
+          start: i
+        });
+      } else if (isPathPrefix(childParts, targetParts)) {
+        visitValue(i, childParts);
       }
       const skipped = skipCompleteValue(args.text, i);
       if (!skipped.complete || skipped.end === void 0) {
-        return { found: false };
+        return;
       }
       i = skipWhitespace(args.text, skipped.end);
       if (args.text[i] === ",") {
@@ -1143,12 +1173,12 @@ var locateValueStart = (args) => {
         i = skipWhitespace(args.text, i + 1);
         continue;
       }
-      if (args.text[i] === "]") return { found: false };
-      return { found: false };
+      if (args.text[i] === "]") return;
+      return;
     }
-    return { found: false };
   };
-  return visitValue(0, []);
+  visitValue(0, []);
+  return matches;
 };
 var extractCompletedValueAt = (args) => {
   const start = skipWhitespace(args.text, args.start);
@@ -1249,26 +1279,21 @@ var extractCompletedNestedValueAt = (args) => {
     complete: false
   };
 };
-var extractCompletedFieldValue = (args) => {
-  const located = locateValueStart(args);
-  if (!located.found || located.start === void 0) {
-    return {
-      found: located.found,
-      complete: false
-    };
+var extractCompletedFieldValues = (args) => {
+  const located = locateValueStarts(args);
+  const values = [];
+  for (const match of located) {
+    const parsed = extractCompletedValueAt({
+      text: args.text,
+      start: match.start
+    });
+    if (!parsed.complete) continue;
+    values.push({
+      path: match.path,
+      value: parsed.value
+    });
   }
-  const parsed = extractCompletedValueAt({
-    text: args.text,
-    start: located.start
-  });
-  return parsed.complete ? {
-    found: true,
-    complete: true,
-    value: parsed.value
-  } : {
-    found: true,
-    complete: false
-  };
+  return values;
 };
 var extractCompletedArrayItems = (args) => {
   const located = locateValueStart(args);
@@ -1338,6 +1363,20 @@ var extractCompletedArrayItems = (args) => {
   }
   return items;
 };
+var extractCompletedArrayItemGroups = (args) => {
+  return locateValueStarts(args).flatMap((match) => {
+    const items = extractCompletedArrayItems({
+      text: args.text,
+      path: match.path
+    });
+    return items.length > 0 ? [
+      {
+        path: match.path,
+        items
+      }
+    ] : [];
+  });
+};
 var extractStreamingStringValue = (args) => {
   const located = locateValueStart(args);
   if (!located.found || located.start === void 0) {
@@ -1408,6 +1447,21 @@ var extractStreamingStringValue = (args) => {
     value
   };
 };
+var extractStreamingStringValues = (args) => {
+  return locateValueStarts(args).flatMap((match) => {
+    const current = extractStreamingStringValue({
+      text: args.text,
+      path: match.path
+    });
+    return current.found ? [
+      {
+        path: match.path,
+        complete: current.complete,
+        value: current.value
+      }
+    ] : [];
+  });
+};
 
 // src/reason/use-reason.ts
 var mergeUsage = (left, right) => {
@@ -1507,9 +1561,17 @@ async function useReason(args) {
       modelId: args.model.modelId,
       stream: args.stream ?? args.model.options?.streaming ?? true,
       emit: args.emit ?? true,
+      ...args.telemetry?.operation ? { operation: args.telemetry.operation } : {},
+      ...args.telemetry?.prompt?.name ? { promptName: args.telemetry.prompt.name } : {},
+      ...args.telemetry?.prompt?.version !== void 0 ? { promptVersion: args.telemetry.prompt.version } : {},
+      ...args.telemetry?.prompt?.type ? { promptType: args.telemetry.prompt.type } : {},
       hasOutputSchema: Boolean(args.outputSchema),
       hasInterrupt: Boolean(args.interrupt),
       hasStructured: Boolean(args.structured)
+    },
+    telemetry: {
+      ...args.telemetry ?? {},
+      input: args.telemetry?.input ?? args.input
     }
   });
   const suppressTextStream = Boolean(args.outputSchema || args.interrupt);
@@ -1558,70 +1620,73 @@ async function useReason(args) {
           onTextChunk: (delta) => {
             firstText += delta;
             finalText = firstText;
-            for (const path of setFieldPaths) {
-              const current = extractCompletedFieldValue({
+            for (const fieldPath of setFieldPaths) {
+              const values = extractCompletedFieldValues({
                 text: firstText,
-                path
-              });
-              if (!current.found || !current.complete) continue;
-              const nextSerialized = JSON.stringify(current.value);
-              if (emittedSetValues.get(path) === nextSerialized) continue;
-              emittedSetValues.set(path, nextSerialized);
-              emitStructuredData({
-                kind: "set",
-                path,
-                value: current.value,
-                dataType: args.structured?.dataType ?? "reason-output",
-                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                ...id ? { id } : {},
-                streamId: opId
+                path: fieldPath
               });
+              for (const { path, value } of values) {
+                const nextSerialized = JSON.stringify(value);
+                if (emittedSetValues.get(path) === nextSerialized) continue;
+                emittedSetValues.set(path, nextSerialized);
+                emitStructuredData({
+                  kind: "set",
+                  path,
+                  value,
+                  dataType: args.structured?.dataType ?? "reason-output",
+                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                  ...id ? { id } : {},
+                  streamId: opId
+                });
+              }
             }
-            for (const path of appendFieldPaths) {
-              const items = extractCompletedArrayItems({
+            for (const fieldPath of appendFieldPaths) {
+              const groups = extractCompletedArrayItemGroups({
                 text: firstText,
-                path
-              });
-              const emittedAppendCount = emittedAppendCounts.get(path) ?? 0;
-              if (items.length <= emittedAppendCount) continue;
-              const nextItems = items.slice(emittedAppendCount);
-              emittedAppendCounts.set(path, items.length);
-              emitStructuredData({
-                kind: "append",
-                path,
-                items: nextItems,
-                dataType: args.structured?.dataType ?? "reason-output",
-                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                ...id ? { id } : {},
-                streamId: opId
+                path: fieldPath
               });
+              for (const { path, items } of groups) {
+                const emittedAppendCount = emittedAppendCounts.get(path) ?? 0;
+                if (items.length <= emittedAppendCount) continue;
+                const nextItems = items.slice(emittedAppendCount);
+                emittedAppendCounts.set(path, items.length);
+                emitStructuredData({
+                  kind: "append",
+                  path,
+                  items: nextItems,
+                  dataType: args.structured?.dataType ?? "reason-output",
+                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                  ...id ? { id } : {},
+                  streamId: opId
+                });
+              }
             }
-            for (const path of textDeltaFieldPaths) {
-              const current = extractStreamingStringValue({
+            for (const fieldPath of textDeltaFieldPaths) {
+              const values = extractStreamingStringValues({
                 text: firstText,
-                path
+                path: fieldPath
               });
-              const emittedTextValue = emittedTextValues.get(path) ?? "";
-              if (!current.found || current.value.length <= emittedTextValue.length || !current.value.startsWith(emittedTextValue)) {
-                continue;
+              for (const { path, value } of values) {
+                const emittedTextValue = emittedTextValues.get(path) ?? "";
+                if (value.length <= emittedTextValue.length || !value.startsWith(emittedTextValue)) {
+                  continue;
+                }
+                const nextDelta = value.slice(emittedTextValue.length);
+                emittedTextValues.set(path, value);
+                if (nextDelta.length === 0) continue;
+                emitStructuredData({
+                  kind: "text-delta",
+                  path,
+                  delta: nextDelta,
+                  dataType: args.structured?.dataType ?? "reason-output",
+                  ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                  ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                  ...id ? { id } : {},
+                  streamId: opId
+                });
               }
-              const nextDelta = current.value.slice(
-                emittedTextValue.length
-              );
-              emittedTextValues.set(path, current.value);
-              if (nextDelta.length === 0) continue;
-              emitStructuredData({
-                kind: "text-delta",
-                path,
-                delta: nextDelta,
-                dataType: args.structured?.dataType ?? "reason-output",
-                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-                ...id ? { id } : {},
-                streamId: opId
-              });
             }
           }
         } : {}
@@ -1811,6 +1876,10 @@ async function useReason(args) {
       textLength: finalText.length,
       resumedFromCheckpoint: Boolean(existingCheckpoint),
       interrupted: Boolean(interruptResponse !== void 0)
+    },
+    telemetry: {
+      ...args.telemetry ?? {},
+      output: args.telemetry?.output ?? finalOutput ?? finalText
     }
   });
   return result;