@kortyx/hooks 0.34.1 → 0.34.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.34.2](https://github.com/kortyx-io/kortyx/compare/hooks-v0.34.1...hooks-v0.34.2) (2026-10-13)
+
+
+### Bug Fixes
+
+* **evals:** preserve diagnostics and separate postcondition failures ([#337](https://github.com/kortyx-io/kortyx/issues/337)) ([d4fce4e](https://github.com/kortyx-io/kortyx/commit/d4fce4e670971d3b755835fc681c8125f67a9c70))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.14.0
+    * @kortyx/providers bumped to 0.9.3
+    * @kortyx/telemetry-contracts bumped to 0.17.2
+    * @kortyx/prompts bumped to 0.2.1
+    * @kortyx/usage-telemetry bumped to 0.3.0
+
 ## [0.34.1](https://github.com/kortyx-io/kortyx/compare/hooks-v0.34.0...hooks-v0.34.1) (2026-10-13)
 
 

package/README.md

@@ -137,3 +137,9 @@ Await groups sequentially within one node; children may contain nested groups.
 Native `Promise.all` calls and parallel graph edges remain unsupported.
 
 See [the execution and replay contract](../../docs/design-specs/child-workflows.md).
+
+When a required `outputs.return` is missing, `useReason` raises the typed
+`REASON_TERMINAL_OUTPUT_MISSING` validation error. Optional
+`toolExecution: { maxSteps: 4, missingReturnCorrections: 1 }` allows an output-only
+correction within the existing step budget, without replaying business tools.
+The correction budget defaults to zero.

package/dist/index.d.ts

@@ -262,6 +262,8 @@ type UseReasonInterruptConfig<TRequest extends InterruptInput = InterruptInput,
     schemaVersion?: string | undefined;
 };
 type UseReasonToolExecution = {
+    /** Extra model corrections for a missing terminal return; defaults to zero and shares maxSteps. Completed calls are not replayed. */
+    missingReturnCorrections?: number | undefined;
     /** Model-pass budget, including output generation and correction across resume. */
     maxSteps?: number | undefined;
     approval?: boolean | Record<string, boolean> | undefined;

package/dist/index.js

@@ -245,7 +245,7 @@ var import_node = require("@kortyx/usage-telemetry/node");
 // package.json
 var package_default = {
   name: "@kortyx/hooks",
-  version: "0.34.1",
+  version: "0.34.2",
   private: false,
   description: "Lifecycle hooks and extension points for Kortyx.",
   keywords: [
@@ -3167,6 +3167,18 @@ var runReasonToolLoop = async (args) => {
   let finalizing = checkpoint?.finalizing ?? false;
   let completed = false;
   const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
+  const missingReturnCorrections = useReasonArgs.toolExecution?.missingReturnCorrections ?? 0;
+  if (!Number.isSafeInteger(missingReturnCorrections) || missingReturnCorrections < 0)
+    throw new import_errors6.KortyxError(
+      "INVALID_REASON_CORRECTION_POLICY",
+      "Invalid missing return correction budget.",
+      {
+        category: "configuration",
+        retryable: false,
+        safeMessage: "toolExecution.missingReturnCorrections must be a nonnegative safe integer."
+      }
+    );
+  let missingReturnAttempts = checkpoint?.missingReturnAttempts ?? 0;
   const messages = checkpoint?.messages ?? createInitialMessages({
     messages: useReasonArgs.messages,
     inputOverride: Boolean(useReasonArgs.outputSchema),
@@ -3218,13 +3230,17 @@ var runReasonToolLoop = async (args) => {
   let outputContractCorrections = checkpoint?.outputContractCorrections ?? 0;
   const correctionExhausted = () => {
     const message = `useReason could not complete output-contract correction within toolExecution.maxSteps (${maxSteps}). Select exactly one terminal return contract; multiple emit contracts are allowed. Increase maxSteps to allow correction and output generation.`;
-    return new import_errors6.ProviderRequestError(message, {
-      code: "REASON_OUTPUT_CONTRACT_CORRECTION_EXHAUSTED",
-      operation: "useReason",
-      safeMessage: message,
-      retryable: false,
-      details: { maxSteps, outputContractCorrections }
-    });
+    return new import_errors6.KortyxError(
+      "REASON_OUTPUT_CONTRACT_CORRECTION_EXHAUSTED",
+      message,
+      {
+        category: "validation",
+        operation: "useReason",
+        safeMessage: message,
+        retryable: false,
+        details: { maxSteps, outputContractCorrections }
+      }
+    );
   };
   const resolvedInterrupts = checkpoint?.resolvedInterrupts ?? [];
   for (const request of resolvedInterrupts) ctx.node.replayInterrupt?.(request);
@@ -3243,6 +3259,7 @@ var runReasonToolLoop = async (args) => {
       interruptHistory,
       emissions,
       outputContractCorrections,
+      missingReturnAttempts,
       ...returned ? { returned } : {},
       finalizing,
       ...pending ? { pending } : {},
@@ -3278,7 +3295,7 @@ var runReasonToolLoop = async (args) => {
       const step = pending ?? await reasonEngine(
         {
           ...useReasonArgs,
-          tools: finalizing ? [] : toolDefinitions,
+          tools: finalizing ? [] : missingReturnAttempts > 0 ? outputDefinitions : toolDefinitions,
           ...separateOutput && !finalizing ? { responseFormat: { type: "text" } } : {},
           messages,
           emit: false,
@@ -3309,6 +3326,16 @@ var runReasonToolLoop = async (args) => {
       );
       aggregatedWarnings = mergeWarnings(aggregatedWarnings, step.warnings);
       const toolCalls = step.toolCalls ?? [];
+      if (missingReturnAttempts > 0 && toolCalls.some((call) => !outputByToolName.has(call.name)))
+        throw new import_errors6.KortyxError(
+          "REASON_OUTPUT_CORRECTION_TOOL_DISALLOWED",
+          "A return correction requested a non-output tool.",
+          {
+            category: "validation",
+            retryable: false,
+            safeMessage: "A terminal output correction cannot rerun tools or human-input requests."
+          }
+        );
       const ids = /* @__PURE__ */ new Set();
       for (const call of toolCalls) {
         if (!call.id || ids.has(call.id) || !reused && knownToolCallIds.has(call.id))
@@ -3329,10 +3356,32 @@ var runReasonToolLoop = async (args) => {
         });
       if (!reused) for (const call of toolCalls) knownToolCallIds.add(call.id);
       if (toolCalls.length === 0) {
-        if (Object.keys(useReasonArgs.outputs?.return ?? {}).length > 0 && !returned)
-          throw new Error(
-            "useReason outputs.return requires one terminal output contract call."
+        if (Object.keys(useReasonArgs.outputs?.return ?? {}).length > 0 && !returned) {
+          if (missingReturnAttempts < missingReturnCorrections) {
+            messages.push({ role: "assistant", content: step.text });
+            messages.push({
+              role: "user",
+              content: "MISSING_TERMINAL_OUTPUT: No terminal output was published. Select exactly one configured return contract using the completed tool and human-input results. Do not repeat completed calls."
+            });
+            missingReturnAttempts += 1;
+            outputContractCorrections += 1;
+            pending = void 0;
+            pendingStepIndex = void 0;
+            save();
+            continue;
+          }
+          throw new import_errors6.KortyxError(
+            "REASON_TERMINAL_OUTPUT_MISSING",
+            "useReason outputs.return requires one terminal output contract call.",
+            {
+              category: "validation",
+              operation: "useReason",
+              retryable: false,
+              safeMessage: "useReason outputs.return requires one terminal output contract call.",
+              details: { missingReturnAttempts }
+            }
           );
+        }
         if (interruptConfig?.mode === "required" && interruptHistory.length === 0)
           throw new Error(
             "useReason interrupts.mode is required, but the model returned a final answer without requesting human input."
@@ -3847,11 +3896,15 @@ var runReasonToolLoop = async (args) => {
           toolResults.push(result2);
           allToolResults.push(result2);
           if (shouldEmitTool) {
+            const diagnosticId = steps[stepIndex]?.toolObservations?.slice().reverse().find(
+              (observation) => observation.toolCallId === `${opId}:${toolCall.id}`
+            )?.diagnosticId;
             emitToolEvent("tool-call-error", {
               tool: tool.name,
               toolCallId: toolCall.id,
               message: result2.content,
-              failure: result2.failure
+              failure: result2.failure,
+              ...diagnosticId ? { diagnosticId } : {}
             });
           }
         }