@kortyx/hooks 0.34.2 → 0.34.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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)
 
 

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`.

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.2",
+  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 } : {},
@@ -3691,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,
@@ -4635,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(
@@ -4809,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;
@@ -4836,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,
@@ -4846,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({
@@ -4894,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;
@@ -4905,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,
@@ -4955,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))
     };