@kortyx/hooks 0.34.1 → 0.34.3

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## Unreleased
+
+- Return recoverable, bounded model feedback for invalid named interrupt requests. Preserve strict human responses, request quotas, approval gates, and tool-loop limits.
+- Replace child execution snapshots natively while reading legacy object and single-element array snapshots.
+
+## [0.34.3](https://github.com/kortyx-io/kortyx/compare/hooks-v0.34.2...hooks-v0.34.3) (2026-10-14)
+
+
+### Bug Fixes
+
+* **runtime:** preserve interrupt state across pauses and resume ([#348](https://github.com/kortyx-io/kortyx/issues/348)) ([03b49f2](https://github.com/kortyx-io/kortyx/commit/03b49f2b8b6b44a2852d16fd4fe1b3e199316072))
+
+## [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

@@ -35,6 +35,8 @@ tool loop, so tools can run before and after a pause. Use `mode: "optional"`
 when the model may finish without asking, and `maxRequests` to bound sequential
 human turns.
 
+Malformed model-authored requests return an `isError` tool result so the model can correct its arguments. They consume the existing model/loop allowance, but do not issue a human request or consume `maxRequests`. Required mode still requires a valid request. Human response validation and approval denial remain strict.
+
 The singular `useReason({ interrupt })` option and `result.interruptResponse`
 are deprecated and will be removed in the next major release. Migrate to
 `interrupts.contracts` and `result.interruptHistory`.
@@ -137,3 +139,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.3",
   private: false,
   description: "Lifecycle hooks and extension points for Kortyx.",
   keywords: [
@@ -2965,6 +2965,40 @@ var emitReasonStructuredOutput = (args) => {
 var import_core5 = require("@kortyx/core");
 var import_errors6 = require("@kortyx/core/errors");
 var import_zod5 = require("zod");
+
+// src/reason/input-feedback.ts
+var record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function schemaPath(schema, path) {
+  let current = schema;
+  let label = "";
+  for (const part of path.slice(0, 8)) {
+    if (!record(current)) break;
+    if (typeof part === "number" && Number.isSafeInteger(part) && part >= 0) {
+      if (!record(current.items)) break;
+      current = current.items;
+      label += `[${part}]`;
+    } else if (typeof part === "string" && record(current.properties) && Object.hasOwn(current.properties, part)) {
+      current = current.properties[part];
+      label += `${label ? "." : ""}${part.slice(0, 64)}`;
+    } else break;
+  }
+  return label || "input";
+}
+function interruptInputFeedback(error, schema, name, required) {
+  const issues = Array.isArray(error.issues) ? error.issues : [];
+  const problems = issues.slice(0, 5).map((issue) => {
+    const path = record(issue) && Array.isArray(issue.path) ? issue.path : [];
+    return `- ${schemaPath(schema, path)} must satisfy its declared input schema.`;
+  });
+  return [
+    `Invalid input for ${name}:`,
+    ...problems,
+    ...issues.length > 5 ? ["- Additional input fields are invalid."] : [],
+    required ? "Correct the input and call the tool again. Human input is required before finishing." : "Correct the input and call the tool again, or finish without requesting human input when none is needed."
+  ].join("\n");
+}
+
+// src/reason/tools.ts
 var toToolDefinitions = (tools2) => tools2.map((tool) => ({
   name: tool.name,
   ...tool.title ? { title: tool.title } : {},
@@ -3167,6 +3201,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 +3264,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 +3293,7 @@ var runReasonToolLoop = async (args) => {
       interruptHistory,
       emissions,
       outputContractCorrections,
+      missingReturnAttempts,
       ...returned ? { returned } : {},
       finalizing,
       ...pending ? { pending } : {},
@@ -3278,7 +3329,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 +3360,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 +3390,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."
@@ -3642,11 +3725,35 @@ var runReasonToolLoop = async (args) => {
             throw new Error(
               `useReason reached interrupts.maxRequests (${interruptConfig?.maxRequests ?? 1}).`
             );
-          const request = parseWithSchema(
-            resolved.contract.requestSchema,
-            toolCall.input,
-            `useReason interrupt contract "${resolved.name}" request`
-          );
+          let request;
+          try {
+            request = parseWithSchema(
+              resolved.contract.requestSchema,
+              toolCall.input,
+              `useReason interrupt contract "${resolved.name}" request`
+            );
+          } catch (error) {
+            if (!(error instanceof import_errors6.ValidationError)) throw error;
+            const result3 = {
+              toolCallId: toolCall.id,
+              name: toolCall.name,
+              isError: true,
+              content: interruptInputFeedback(
+                error,
+                interruptDefinitions.find((tool2) => tool2.name === toolCall.name)?.inputSchema,
+                toolCall.name,
+                interruptConfig?.mode === "required"
+              )
+            };
+            toolResults.push(result3);
+            messages.push({ role: "tool", ...result3 });
+            traceSpan?.addEvent?.("useReason.interrupt.invalid", {
+              checkpointKey,
+              contract: resolved.name
+            });
+            save();
+            continue;
+          }
           traceSpan?.addEvent?.("useReason.interrupt.requested", {
             checkpointKey,
             contract: resolved.name,
@@ -3847,11 +3954,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 } : {}
             });
           }
         }
@@ -4582,10 +4693,10 @@ function parallel(values) {
         throw new Error("Parallel call membership changed during replay.");
       }
       for (const callId of group.record.calls) {
-        const record = callRecord(callId);
-        if (record?.status !== "interrupted") continue;
-        const index = record.interrupts.length - 1;
-        if (record.interrupts[index]?.response !== void 0) continue;
+        const record2 = callRecord(callId);
+        if (record2?.status !== "interrupted") continue;
+        const index = record2.interrupts.length - 1;
+        if (record2.interrupts[index]?.response !== void 0) continue;
         group.record.interrupts.push({ callId, index });
         await bridge(callId, index);
         throw new Error(
@@ -4756,26 +4867,26 @@ async function runWorkflowCall(args, task) {
     version: definition?.version ?? null
   });
   const key = `__useWorkflow:${args.id}`;
-  let record = ctx.currentNodeState.byKey[key];
-  if (record && record.parallelKey !== task.group?.key)
+  let record2 = ctx.currentNodeState.byKey[key];
+  if (record2 && record2.parallelKey !== task.group?.key)
     throw new WorkflowCallError(
       workflow,
       "parallel call membership changed during replay"
     );
-  if (record && record.fingerprint !== fingerprint)
+  if (record2 && record2.fingerprint !== fingerprint)
     throw new WorkflowCallError(
       workflow,
       "call input or target changed during replay"
     );
-  if (!record) ctx.node.consumeExecution?.("maxChildInvocations");
-  record ??= {
+  if (!record2) ctx.node.consumeExecution?.("maxChildInvocations");
+  record2 ??= {
     fingerprint,
     invocationId: (0, import_node_crypto6.randomUUID)(),
     status: "running",
     interrupts: [],
     ...task.group ? { parallelKey: task.group.key } : {}
   };
-  ctx.currentNodeState.byKey[key] = record;
+  ctx.currentNodeState.byKey[key] = record2;
   ctx.stateDirty = true;
   if (!task.group) ctx.workflowCallActive = true;
   const telemetry = ctx.node.workflowCallTelemetry;
@@ -4783,7 +4894,7 @@ async function runWorkflowCall(args, task) {
   ctx.currentNodeState.byKey[activationKey] ??= (0, import_node_crypto6.randomUUID)();
   const callerNodeExecutionId = ctx.currentNodeState.byKey[activationKey];
   const metadata = {
-    invocationId: record.invocationId,
+    invocationId: record2.invocationId,
     parentInvocationId: telemetry?.correlation?.invocationId ?? null,
     branchId: telemetry?.correlation?.branchId ?? telemetry?.correlation?.runId ?? "unknown",
     callId: args.id,
@@ -4793,46 +4904,49 @@ async function runWorkflowCall(args, task) {
     targetWorkflowId: workflow,
     targetVersion: definition?.version ?? null
   };
-  record.telemetry = metadata;
+  record2.telemetry = metadata;
   const report = (status, content = {}) => {
-    record.sequence = (record.sequence ?? 0) + 1;
+    record2.sequence = (record2.sequence ?? 0) + 1;
     emitWorkflowCall(telemetry, `workflow.call.${status}`, {
       ...metadata,
-      sequence: record.sequence,
+      sequence: record2.sequence,
       ...content
     });
   };
   const recordUsage = (usage2) => {
     if (!usage2) return;
     accumulateTokenUsage({
-      input: usage2.input - (record.usage?.input ?? 0),
-      output: usage2.output - (record.usage?.output ?? 0),
-      total: usage2.total - (record.usage?.total ?? 0)
+      input: usage2.input - (record2.usage?.input ?? 0),
+      output: usage2.output - (record2.usage?.output ?? 0),
+      total: usage2.total - (record2.usage?.total ?? 0)
     });
-    record.usage = usage2;
+    record2.usage = usage2;
   };
-  const cached = record.status === "completed";
+  const cached = record2.status === "completed";
   try {
-    for (const interruption of task.group ? [] : record.interrupts) {
+    for (const interruption of task.group ? [] : record2.interrupts) {
       interruption.response = await awaitInterruptInternal({
         request: interruption.request,
         ...interruption.request.meta ? { meta: interruption.request.meta } : {}
       });
     }
-    if (record.status === "failed")
+    if (record2.status === "failed")
       throw new WorkflowCallError(
         workflow,
-        record.error ?? "child failed",
+        record2.error ?? "child failed",
         void 0,
-        record.failure ?? (0, import_errors8.serializeFailure)(void 0)
+        record2.failure ?? (0, import_errors8.serializeFailure)(void 0)
       );
-    if (task.group && record.status === "interrupted" && record.interrupts.at(-1)?.response === void 0)
+    if (task.group && record2.status === "interrupted" && record2.interrupts.at(-1)?.response === void 0)
       throw new ParallelChildWaiting();
-    while (record.status !== "completed") {
+    while (record2.status !== "completed") {
       let outcome;
       try {
+        if (Array.isArray(record2.snapshot) && record2.snapshot.length !== 1)
+          throw new import_errors8.WorkflowContractError("Invalid child workflow snapshot.");
+        const snapshot = Array.isArray(record2.snapshot) ? record2.snapshot[0] : record2.snapshot;
         report(
-          record.snapshot ? "resumed" : "started",
+          snapshot ? "resumed" : "started",
           workflowCallContent(telemetry, "input", input)
         );
         outcome = await service({
@@ -4841,9 +4955,9 @@ async function runWorkflowCall(args, task) {
           workflow,
           input,
           definition,
-          invocationId: record.invocationId,
-          ...record.snapshot ? { snapshot: record.snapshot } : {},
-          ...record.interrupts.length ? { response: record.interrupts.at(-1)?.response } : {}
+          invocationId: record2.invocationId,
+          ...snapshot ? { snapshot } : {},
+          ...record2.interrupts.length ? { response: record2.interrupts.at(-1)?.response } : {}
         });
       } catch (error) {
         const child = error;
@@ -4852,48 +4966,48 @@ async function runWorkflowCall(args, task) {
         if ((0, import_core8.isExecutionCancelled)(error)) throw error;
         if ((0, import_core8.isExecutionLimitReached)(error)) {
           if (child?.__kortyxChildSnapshot)
-            record.snapshot = child.__kortyxChildSnapshot;
+            record2.snapshot = child.__kortyxChildSnapshot;
           report("suspended", {
             reason: "limit_reached",
             limit: error.limitReached
           });
           throw error;
         }
-        record.status = "failed";
-        record.failure = (0, import_errors8.serializeFailure)(error);
-        record.error = record.failure.message;
+        record2.status = "failed";
+        record2.failure = (0, import_errors8.serializeFailure)(error);
+        record2.error = record2.failure.message;
         report("failed", { error: "Child workflow failed" });
         throw new WorkflowCallError(
           workflow,
-          record.error,
+          record2.error,
           error,
-          record.failure
+          record2.failure
         );
       }
       (0, import_core8.throwIfExecutionAborted)(ctx.node.abortSignal);
       recordUsage(outcome.usage);
       if (outcome.status === "completed") {
-        record.data = outcome.data;
-        workflowCallFingerprint(record.data);
-        record.status = "completed";
-        record.toolObservations = outcome.toolObservations ?? [];
-        for (const observation of record.toolObservations)
+        record2.data = outcome.data;
+        workflowCallFingerprint(record2.data);
+        record2.status = "completed";
+        record2.toolObservations = outcome.toolObservations ?? [];
+        for (const observation of record2.toolObservations)
           rememberToolObservation(observation);
-        delete record.snapshot;
+        delete record2.snapshot;
         report(
           "completed",
-          workflowCallContent(telemetry, "output", record.data)
+          workflowCallContent(telemetry, "output", record2.data)
         );
       } else {
-        record.status = "interrupted";
-        record.snapshot = outcome.snapshot;
+        record2.status = "interrupted";
+        record2.snapshot = outcome.snapshot;
         report("suspended", {
           leaf: outcome.request.meta?.workflowCall ?? null
         });
         const interruption = {
           request: outcome.request
         };
-        record.interrupts.push(interruption);
+        record2.interrupts.push(interruption);
         if (task.group) throw new ParallelChildWaiting();
         interruption.response = await awaitInterruptInternal({
           request: interruption.request,
@@ -4902,12 +5016,12 @@ async function runWorkflowCall(args, task) {
       }
     }
     if (cached) {
-      report("reused", workflowCallContent(telemetry, "output", record.data));
-      if (record.restoredToolBranch !== telemetry?.correlation?.branchId)
-        await replayToolObservations(record.toolObservations ?? [], true);
-      delete record.restoredToolBranch;
+      report("reused", workflowCallContent(telemetry, "output", record2.data));
+      if (record2.restoredToolBranch !== telemetry?.correlation?.branchId)
+        await replayToolObservations(record2.toolObservations ?? [], true);
+      delete record2.restoredToolBranch;
     }
-    const data = record.data ?? {};
+    const data = record2.data ?? {};
     return {
       data: JSON.parse(JSON.stringify(data))
     };