@kortyx/hooks 0.14.0 → 0.16.0

package/dist/index.js

@@ -373,6 +373,7 @@ async function runReasonEngine(args) {
   const reasoning = args.reasoning ?? args.model.options?.reasoning;
   const responseFormat = args.responseFormat ?? args.model.options?.responseFormat;
   const providerOptions = args.providerOptions ?? args.model.options?.providerOptions;
+  const tools = args.tools ?? args.model.options?.tools;
   const model = args.model.provider.getModel(args.model.modelId, {
     ...temperature !== void 0 ? { temperature } : {},
     streaming: stream,
@@ -381,13 +382,13 @@ async function runReasonEngine(args) {
     ...abortSignal !== void 0 ? { abortSignal } : {},
     ...reasoning !== void 0 ? { reasoning } : {},
     ...responseFormat !== void 0 ? { responseFormat } : {},
+    ...tools !== void 0 ? { tools } : {},
     ...providerOptions !== void 0 ? { providerOptions } : {}
   });
-  const messages = [];
-  if (typeof args.system === "string" && args.system.length > 0) {
-    messages.push({ role: "system", content: args.system });
-  }
-  messages.push({ role: "user", content: String(args.input ?? "") });
+  const messages = args.messages !== void 0 ? args.messages : [
+    ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
+    { role: "user", content: String(args.input ?? "") }
+  ];
   const opId = typeof args.opId === "string" && args.opId.length > 0 ? args.opId : createRuntimeId();
   const segmentId = typeof args.segmentId === "string" && args.segmentId.length > 0 ? args.segmentId : createRuntimeId();
   const commonMeta = {
@@ -403,7 +404,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 +423,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
       }
     });
   };
@@ -431,6 +444,7 @@ async function runReasonEngine(args) {
       let raw;
       let usage;
       let finishReason;
+      let toolCalls;
       let providerMetadata;
       let warnings;
       if (emit) {
@@ -469,6 +483,9 @@ async function runReasonEngine(args) {
             if (chunk.finishReason !== void 0) {
               finishReason = chunk.finishReason;
             }
+            if (chunk.toolCalls !== void 0) {
+              toolCalls = chunk.toolCalls;
+            }
             if (chunk.providerMetadata !== void 0) {
               providerMetadata = chunk.providerMetadata;
             }
@@ -508,6 +525,7 @@ async function runReasonEngine(args) {
         ...raw !== void 0 ? { raw } : {},
         ...usage !== void 0 ? { usage } : {},
         ...finishReason !== void 0 ? { finishReason } : {},
+        ...toolCalls !== void 0 ? { toolCalls } : {},
         ...providerMetadata !== void 0 ? { providerMetadata } : {},
         ...warnings !== void 0 ? { warnings } : {}
       };
@@ -534,6 +552,7 @@ async function runReasonEngine(args) {
       ...response.raw !== void 0 ? { raw: response.raw } : {},
       ...response.usage !== void 0 ? { usage: response.usage } : {},
       ...response.finishReason !== void 0 ? { finishReason: response.finishReason } : {},
+      ...response.toolCalls !== void 0 ? { toolCalls: response.toolCalls } : {},
       ...response.providerMetadata !== void 0 ? { providerMetadata: response.providerMetadata } : {},
       ...response.warnings !== void 0 ? { warnings: response.warnings } : {}
     };
@@ -566,10 +585,13 @@ async function reasonEngine(args, meta, inputOverride) {
     reasoning: args.reasoning,
     responseFormat: args.responseFormat,
     providerOptions: args.providerOptions,
+    tools: args.tools,
+    messages: args.messages,
     defaultTemperature: ctx.node.config?.model?.temperature,
     stream: args.stream,
     emit: args.emit,
     onTextChunk: args.onTextChunk,
+    telemetry: args.telemetry,
     nodeId: ctx.node.graph.node,
     emitEvent: ctx.node.emit,
     reasonTrace: ctx.reasonTrace,
@@ -890,6 +912,65 @@ var withStructuredStreamHints = (input, args) => {
   ].join("\n\n");
 };
 
+// src/reason/result.ts
+var mergeUsage = (left, right) => {
+  if (!left) return right;
+  if (!right) return left;
+  const sum = (a, b) => a === void 0 && b === void 0 ? void 0 : (a ?? 0) + (b ?? 0);
+  const raw = left.raw || right.raw ? {
+    ...left.raw ?? {},
+    ...right.raw ?? {}
+  } : void 0;
+  const input = sum(left.input, right.input);
+  const output = sum(left.output, right.output);
+  const total = sum(left.total, right.total);
+  const reasoning = sum(left.reasoning, right.reasoning);
+  const cacheRead = sum(left.cacheRead, right.cacheRead);
+  const cacheWrite = sum(left.cacheWrite, right.cacheWrite);
+  const merged = {};
+  if (input !== void 0) merged.input = input;
+  if (output !== void 0) merged.output = output;
+  if (total !== void 0) merged.total = total;
+  if (reasoning !== void 0) merged.reasoning = reasoning;
+  if (cacheRead !== void 0) merged.cacheRead = cacheRead;
+  if (cacheWrite !== void 0) merged.cacheWrite = cacheWrite;
+  if (raw) merged.raw = raw;
+  return merged;
+};
+var mergeWarnings = (left, right) => {
+  if (!left?.length) return right;
+  if (!right?.length) return left;
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const warning of [...left, ...right]) {
+    const key = JSON.stringify(warning);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(warning);
+  }
+  return merged;
+};
+var mergeProviderMetadata = (left, right) => {
+  if (!left) return right;
+  if (!right) return left;
+  return {
+    ...left,
+    ...right
+  };
+};
+var emitReasonStructuredOutput = (args) => {
+  if (!args.emit || !shouldEmitStructured(args.structured)) return;
+  emitStructuredData({
+    dataType: args.structured?.dataType ?? "reason-output",
+    data: args.output,
+    kind: "final",
+    ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+    ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+    ...args.id ? { id: args.id } : {},
+    streamId: args.opId
+  });
+};
+
 // src/reason/structured-stream.ts
 var resolveAppendFieldPaths = (cfg) => {
   const fields = cfg?.fields;
@@ -1450,64 +1531,353 @@ var extractStreamingStringValues = (args) => {
   });
 };
 
-// src/reason/use-reason.ts
-var mergeUsage = (left, right) => {
-  if (!left) return right;
-  if (!right) return left;
-  const sum = (a, b) => a === void 0 && b === void 0 ? void 0 : (a ?? 0) + (b ?? 0);
-  const raw = left.raw || right.raw ? {
-    ...left.raw ?? {},
-    ...right.raw ?? {}
-  } : void 0;
-  const input = sum(left.input, right.input);
-  const output = sum(left.output, right.output);
-  const total = sum(left.total, right.total);
-  const reasoning = sum(left.reasoning, right.reasoning);
-  const cacheRead = sum(left.cacheRead, right.cacheRead);
-  const cacheWrite = sum(left.cacheWrite, right.cacheWrite);
-  const merged = {};
-  if (input !== void 0) merged.input = input;
-  if (output !== void 0) merged.output = output;
-  if (total !== void 0) merged.total = total;
-  if (reasoning !== void 0) merged.reasoning = reasoning;
-  if (cacheRead !== void 0) merged.cacheRead = cacheRead;
-  if (cacheWrite !== void 0) merged.cacheWrite = cacheWrite;
-  if (raw) merged.raw = raw;
-  return merged;
+// src/reason/tools.ts
+var toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+var toToolDefinitions = (tools) => tools.map((tool) => ({
+  name: tool.name,
+  ...tool.title ? { title: tool.title } : {},
+  ...tool.description ? { description: tool.description } : {},
+  inputSchema: tool.inputSchema,
+  ...tool.outputSchema !== void 0 ? { outputSchema: tool.outputSchema } : {},
+  ...tool.annotations !== void 0 ? { annotations: tool.annotations } : {},
+  ...tool.metadata !== void 0 ? { metadata: tool.metadata } : {}
+}));
+var resolveToolExecutionBoolean = (value, toolName, fallback) => {
+  if (typeof value === "boolean") return value;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value[toolName] ?? fallback;
+  }
+  return fallback;
 };
-var mergeWarnings = (left, right) => {
-  if (!left?.length) return right;
-  if (!right?.length) return left;
-  const seen = /* @__PURE__ */ new Set();
-  const merged = [];
-  for (const warning of [...left, ...right]) {
-    const key = JSON.stringify(warning);
-    if (seen.has(key)) continue;
-    seen.add(key);
-    merged.push(warning);
+var normalizeToolResult = (toolCall, value) => {
+  if (value && typeof value === "object" && !Array.isArray(value) && "toolCallId" in value && "name" in value && "content" in value) {
+    return value;
+  }
+  let content;
+  try {
+    content = typeof value === "string" ? value : JSON.stringify(value);
+  } catch {
+    content = String(value);
   }
-  return merged;
-};
-var mergeProviderMetadata = (left, right) => {
-  if (!left) return right;
-  if (!right) return left;
   return {
-    ...left,
-    ...right
+    toolCallId: toolCall.id,
+    name: toolCall.name,
+    content,
+    ...value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) ? { structuredContent: value } : {}
   };
 };
-var emitReasonStructuredOutput = (args) => {
-  if (!args.emit || !shouldEmitStructured(args.structured)) return;
-  emitStructuredData({
-    dataType: args.structured?.dataType ?? "reason-output",
-    data: args.output,
-    kind: "final",
-    ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
-    ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
-    ...args.id ? { id: args.id } : {},
-    streamId: args.opId
+var closeOwnedTools = async (tools) => {
+  const closeFns = /* @__PURE__ */ new Set();
+  for (const tool of tools) {
+    if (tool.closeAfterUse === false || !tool.close) continue;
+    closeFns.add(tool.close);
+  }
+  await Promise.all(
+    [...closeFns].map(async (close) => {
+      await close();
+    })
+  );
+};
+var createInitialMessages = (args) => [
+  ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
+  { role: "user", content: String(args.input ?? "") }
+];
+var runReasonToolLoop = async (args) => {
+  const { useReasonArgs, id, opId, traceSpan } = args;
+  const ctx = getHookContext();
+  const tools = useReasonArgs.tools ?? [];
+  const toolByName = /* @__PURE__ */ new Map();
+  let validationCompleted = false;
+  try {
+    for (const tool of tools) {
+      if (toolByName.has(tool.name)) {
+        throw new Error(
+          `useReason received duplicate tool name "${tool.name}".`
+        );
+      }
+      toolByName.set(tool.name, tool);
+    }
+    if (useReasonArgs.interrupt) {
+      throw new Error(
+        "useReason tools cannot be combined with useReason interrupt mode yet. Use toolExecution.approval for tool approval."
+      );
+    }
+    validationCompleted = true;
+  } finally {
+    if (!validationCompleted) {
+      await closeOwnedTools(tools);
+    }
+  }
+  const toolDefinitions = toToolDefinitions(tools);
+  const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
+  const messages = createInitialMessages({
+    system: useReasonArgs.system,
+    input: useReasonArgs.input
   });
+  const steps = [];
+  const allToolCalls = [];
+  const allToolResults = [];
+  let finalText = "";
+  let finalRaw;
+  let finalOutput;
+  let aggregatedUsage;
+  let finalFinishReason;
+  let aggregatedProviderMetadata;
+  let aggregatedWarnings;
+  const emitToolEvent = (event, payload) => {
+    ctx.node.emit(event, {
+      ...payload,
+      node: ctx.node.graph.node,
+      ...id ? { id } : {},
+      opId
+    });
+  };
+  try {
+    for (let stepIndex = 0; stepIndex < maxSteps; stepIndex += 1) {
+      traceSpan?.addEvent?.("useReason.tool-step.start", {
+        stepIndex,
+        toolCount: toolDefinitions.length
+      });
+      const step = await reasonEngine(
+        {
+          ...useReasonArgs,
+          tools: toolDefinitions,
+          messages,
+          emit: false,
+          stream: false
+        },
+        { ...id ? { id } : {}, opId }
+      );
+      finalText = step.text;
+      finalRaw = step.raw;
+      aggregatedUsage = mergeUsage(aggregatedUsage, step.usage);
+      finalFinishReason = step.finishReason;
+      aggregatedProviderMetadata = mergeProviderMetadata(
+        aggregatedProviderMetadata,
+        step.providerMetadata
+      );
+      aggregatedWarnings = mergeWarnings(aggregatedWarnings, step.warnings);
+      const toolCalls = step.toolCalls ?? [];
+      const toolResults = [];
+      steps.push({
+        stepIndex,
+        text: step.text,
+        toolCalls,
+        toolResults,
+        ...step.usage ? { usage: step.usage } : {},
+        ...step.finishReason ? { finishReason: step.finishReason } : {},
+        ...step.providerMetadata ? { providerMetadata: step.providerMetadata } : {},
+        ...step.warnings ? { warnings: step.warnings } : {}
+      });
+      if (toolCalls.length === 0) {
+        if ((useReasonArgs.emit ?? true) && step.text.length > 0) {
+          emitToolEvent("text-start", {});
+          emitToolEvent("text-delta", { delta: step.text });
+          emitToolEvent("text-end", {});
+        }
+        break;
+      }
+      allToolCalls.push(...toolCalls);
+      messages.push({
+        role: "assistant",
+        content: step.text,
+        toolCalls
+      });
+      for (const toolCall of toolCalls) {
+        const tool = toolByName.get(toolCall.name);
+        if (!tool) {
+          throw new Error(
+            `Model requested unknown tool "${toolCall.name}" from useReason.`
+          );
+        }
+        const shouldEmitTool = resolveToolExecutionBoolean(
+          useReasonArgs.toolExecution?.emit,
+          tool.name,
+          false
+        );
+        const shouldApproveTool = resolveToolExecutionBoolean(
+          useReasonArgs.toolExecution?.approval,
+          tool.name,
+          false
+        );
+        if (shouldEmitTool) {
+          emitToolEvent("tool-call-start", {
+            tool: tool.name,
+            toolCallId: toolCall.id,
+            input: toolCall.input
+          });
+        }
+        if (shouldApproveTool) {
+          const approval = await awaitInterruptInternal({
+            id: `tool:${toolCall.id}`,
+            request: {
+              kind: "choice",
+              question: `Approve ${tool.name}?`,
+              options: [
+                { id: "approve", label: "Approve" },
+                { id: "deny", label: "Deny" }
+              ],
+              meta: {
+                tool: tool.name,
+                toolCallId: toolCall.id,
+                input: toolCall.input
+              }
+            }
+          });
+          const approved = Array.isArray(approval) ? approval.includes("approve") : approval === "approve";
+          if (!approved) {
+            const denied = {
+              toolCallId: toolCall.id,
+              name: tool.name,
+              content: "Tool call denied by user.",
+              isError: true
+            };
+            toolResults.push(denied);
+            allToolResults.push(denied);
+            if (shouldEmitTool) {
+              emitToolEvent("tool-call-result", {
+                tool: tool.name,
+                toolCallId: toolCall.id,
+                content: denied.content,
+                isError: true
+              });
+            }
+            continue;
+          }
+        }
+        try {
+          const rawResult = await tool.execute(toolCall.input, {
+            toolCallId: toolCall.id,
+            ...useReasonArgs.abortSignal ? { abortSignal: useReasonArgs.abortSignal } : {}
+          });
+          const result2 = normalizeToolResult(toolCall, rawResult);
+          toolResults.push(result2);
+          allToolResults.push(result2);
+          if (shouldEmitTool) {
+            emitToolEvent("tool-call-result", {
+              tool: result2.name,
+              toolCallId: result2.toolCallId,
+              content: result2.content,
+              ...result2.structuredContent !== void 0 ? { structuredContent: result2.structuredContent } : {},
+              ...result2.isError !== void 0 ? { isError: result2.isError } : {}
+            });
+          }
+          traceSpan?.addEvent?.("useReason.tool-call.complete", {
+            stepIndex,
+            tool: result2.name,
+            toolCallId: result2.toolCallId,
+            isError: Boolean(result2.isError)
+          });
+        } catch (error) {
+          const result2 = {
+            toolCallId: toolCall.id,
+            name: tool.name,
+            content: toErrorMessage(error),
+            isError: true
+          };
+          toolResults.push(result2);
+          allToolResults.push(result2);
+          if (shouldEmitTool) {
+            emitToolEvent("tool-call-error", {
+              tool: tool.name,
+              toolCallId: toolCall.id,
+              message: result2.content
+            });
+          }
+          traceSpan?.addEvent?.("useReason.tool-call.error", {
+            stepIndex,
+            tool: tool.name,
+            toolCallId: toolCall.id,
+            message: result2.content
+          });
+        }
+      }
+      const currentStep = steps[steps.length - 1];
+      if (currentStep) {
+        steps[steps.length - 1] = {
+          ...currentStep,
+          toolResults
+        };
+      }
+      for (const result2 of toolResults) {
+        messages.push({
+          role: "tool",
+          content: result2.content,
+          toolCallId: result2.toolCallId,
+          name: result2.name,
+          ...result2.structuredContent !== void 0 ? { structuredContent: result2.structuredContent } : {},
+          ...result2.isError !== void 0 ? { isError: result2.isError } : {},
+          ...result2.raw !== void 0 ? { raw: result2.raw } : {}
+        });
+      }
+    }
+    if (steps.length >= maxSteps && steps.at(-1)?.toolCalls.length) {
+      throw new Error(
+        `useReason tool loop reached maxSteps (${maxSteps}) before producing a final response.`
+      );
+    }
+    if (useReasonArgs.outputSchema) {
+      finalOutput = parseReasonOutputWithSchema({
+        text: finalText,
+        schema: useReasonArgs.outputSchema,
+        ...finalFinishReason ? { finishReason: finalFinishReason } : {},
+        label: "useReason output"
+      });
+    }
+    if (finalOutput !== void 0) {
+      emitReasonStructuredOutput({
+        ...id ? { id } : {},
+        opId,
+        output: finalOutput,
+        structured: useReasonArgs.structured,
+        emit: useReasonArgs.emit ?? true
+      });
+    }
+    const result = {
+      ...id ? { id } : {},
+      opId,
+      text: finalText,
+      ...finalRaw !== void 0 ? { raw: finalRaw } : {},
+      ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
+      ...finalFinishReason !== void 0 ? { finishReason: finalFinishReason } : {},
+      ...aggregatedProviderMetadata !== void 0 ? { providerMetadata: aggregatedProviderMetadata } : {},
+      ...aggregatedWarnings !== void 0 ? { warnings: aggregatedWarnings } : {},
+      ...finalOutput !== void 0 ? { output: finalOutput } : {},
+      toolCalls: allToolCalls,
+      toolResults: allToolResults,
+      steps
+    };
+    traceSpan?.end?.({
+      ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
+      ...finalFinishReason !== void 0 ? { finishReason: finalFinishReason } : {},
+      ...aggregatedProviderMetadata !== void 0 ? { providerMetadata: aggregatedProviderMetadata } : {},
+      ...aggregatedWarnings !== void 0 ? { warnings: aggregatedWarnings } : {},
+      attributes: {
+        textLength: finalText.length,
+        toolCallCount: allToolCalls.length,
+        toolResultCount: allToolResults.length,
+        toolStepCount: steps.length
+      },
+      telemetry: {
+        ...useReasonArgs.telemetry ?? {},
+        output: useReasonArgs.telemetry?.output ?? finalOutput ?? finalText
+      }
+    });
+    return result;
+  } catch (error) {
+    traceSpan?.fail?.(error, {
+      attributes: {
+        toolStepCount: steps.length,
+        toolCallCount: allToolCalls.length
+      }
+    });
+    throw error;
+  } finally {
+    await closeOwnedTools(tools);
+  }
 };
+
+// src/reason/use-reason.ts
 var shouldStreamReasonStructured = (args) => (args.emit ?? true) && shouldStreamStructured(args.structured);
 var resolveEffectiveReasoningIncludeThoughts = (args) => args.reasoning?.includeThoughts ?? args.model.options?.reasoning?.includeThoughts ?? false;
 var resolveEffectiveResponseFormatType = (args) => args.responseFormat?.type ?? args.model.options?.responseFormat?.type;
@@ -1548,11 +1918,28 @@ 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)
+      hasStructured: Boolean(args.structured),
+      hasTools: Boolean(args.tools?.length)
+    },
+    telemetry: {
+      ...args.telemetry ?? {},
+      input: args.telemetry?.input ?? args.input
     }
   });
+  if (args.tools?.length) {
+    return runReasonToolLoop({
+      useReasonArgs: args,
+      ...id ? { id } : {},
+      opId,
+      ...traceSpan ? { traceSpan } : {}
+    });
+  }
   const suppressTextStream = Boolean(args.outputSchema || args.interrupt);
   const setFieldPaths = resolveSetFieldPaths(args.structured);
   const appendFieldPaths = resolveAppendFieldPaths(args.structured);
@@ -1855,6 +2242,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;