@kortyx/hooks 0.30.2 → 0.32.0

package/dist/index.js

@@ -286,7 +286,8 @@ var readReasonCompletedCheckpoint = (raw) => {
   if (!value.result || typeof value.result !== "object") return void 0;
   return {
     status: "completed",
-    result: value.result
+    result: value.result,
+    ...Array.isArray(value.resolvedInterrupts) ? { resolvedInterrupts: value.resolvedInterrupts } : {}
   };
 };
 var resolveHookStatePatch = (args) => ({
@@ -348,6 +349,10 @@ var awaitInterruptInternal = (args) => {
     raw,
     "useInterrupt response"
   );
+  if (args.onResolved) {
+    const { __kortyxResumeStatePatch: _patch, ...meta } = enrichedRequest.meta ?? {};
+    args.onResolved({ ...enrichedRequest, meta });
+  }
   return Promise.resolve(response);
 };
 
@@ -717,52 +722,257 @@ var import_core2 = require("@kortyx/core");
 var import_errors3 = require("@kortyx/core/errors");
 
 // src/error-diagnostics.ts
+var import_telemetry_contracts2 = require("@kortyx/telemetry-contracts");
+
+// src/diagnostic-capture.ts
 var import_errors2 = require("@kortyx/core/errors");
-var MAX_STACK_LENGTH = 32768;
-var MAX_CAUSE_DEPTH = 4;
-var projectDetails = (value, depth, seen) => {
-  const objectValue = value && typeof value === "object" ? value : void 0;
-  if (objectValue) {
-    if (seen.has(objectValue))
-      return { type: "Error", message: "Circular error cause." };
-    seen.add(objectValue);
+var import_telemetry_contracts = require("@kortyx/telemetry-contracts");
+var encoder = new TextEncoder();
+var nativeStackGetter = Object.getOwnPropertyDescriptor(
+  new Error(),
+  "stack"
+)?.get;
+function nativeStack(object, getter) {
+  if (!getter || getter !== nativeStackGetter)
+    throw new Error("Custom stack accessor");
+  for (const key of ["name", "message"]) {
+    let cursor = object;
+    while (cursor) {
+      const descriptor = Object.getOwnPropertyDescriptor(cursor, key);
+      if (descriptor) {
+        if (!("value" in descriptor) || typeof descriptor.value !== "string")
+          throw new Error("Custom error formatting");
+        break;
+      }
+      cursor = Object.getPrototypeOf(cursor);
+    }
   }
-  const name = (0, import_errors2.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
-  const message = (0, import_errors2.errorProperty)(value, "message");
-  const stack = (0, import_errors2.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
+  const formatter = Object.getOwnPropertyDescriptor(Error, "prepareStackTrace");
+  if (formatter && (!("value" in formatter) || !formatter.writable))
+    throw new Error("Custom stack formatter");
+  Object.defineProperty(Error, "prepareStackTrace", {
+    ...formatter ?? { configurable: true, writable: true },
+    value: void 0
+  });
+  try {
+    return getter.call(object);
+  } finally {
+    if (formatter) Object.defineProperty(Error, "prepareStackTrace", formatter);
+    else Reflect.deleteProperty(Error, "prepareStackTrace");
+  }
+}
+var pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+function captureDiagnosticContent(error, project) {
+  const omissions = [];
+  const redactions = [];
+  const seen = /* @__PURE__ */ new WeakMap();
+  let nodes = 0;
+  let remaining = import_telemetry_contracts.DIAGNOSTIC_LIMITS.bytes - 64 * 1024;
+  const omit = (path, reason, extra = {}) => {
+    if (omissions.length < 1e3)
+      omissions.push({ path: path.slice(0, 4096), reason, ...extra });
+    return { $omitted: reason };
+  };
+  const visit = (value, path, depth) => {
+    if (++nodes > import_telemetry_contracts.DIAGNOSTIC_LIMITS.nodes) return omit(path, "node_limit");
+    if (depth > import_telemetry_contracts.DIAGNOSTIC_LIMITS.depth) return omit(path, "depth_limit");
+    if (typeof value === "string") {
+      const clean = (0, import_telemetry_contracts.redactDiagnosticText)(value);
+      if (clean !== value && redactions.length < 1e3)
+        redactions.push({
+          path: path.slice(0, 4096),
+          reason: "credential_text"
+        });
+      const bytes = encoder.encode(JSON.stringify(clean)).length;
+      if (bytes > remaining)
+        return omit(path, "byte_limit", {
+          originalBytes: encoder.encode(value).length
+        });
+      remaining -= bytes;
+      return clean;
+    }
+    if (value === null || typeof value === "boolean") return value;
+    if (typeof value === "number")
+      return Number.isFinite(value) ? value : { $type: "number", value: String(value) };
+    if (typeof value === "bigint")
+      return { $type: "bigint", value: value.toString() };
+    if (typeof value === "undefined") return { $type: "undefined" };
+    if (typeof value === "function" || typeof value === "symbol")
+      return omit(path, `unsupported_${typeof value}`);
+    const object = value;
+    const reference = seen.get(object);
+    if (reference) return { $ref: reference };
+    seen.set(object, path);
+    remaining -= 32;
+    if (remaining < 0) return omit(path, "byte_limit");
     try {
-      return value.stack;
+      if (value instanceof Date)
+        return { $type: "Date", value: Date.prototype.toISOString.call(value) };
+      if (value instanceof Map || value instanceof Set) {
+        const isMap = value instanceof Map;
+        const iterator = isMap ? Map.prototype.entries.call(value) : Set.prototype.values.call(value);
+        const count = Object.getOwnPropertyDescriptor(
+          isMap ? Map.prototype : Set.prototype,
+          "size"
+        )?.get?.call(value);
+        const entries = [];
+        for (let index = 0; index < Math.min(count, import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties); index++)
+          entries.push(iterator.next().value);
+        if (count > entries.length)
+          omissions.push({
+            path,
+            reason: "collection_limit",
+            originalCount: count
+          });
+        return isMap ? {
+          $type: "Map",
+          entries: visit(entries, `${path}/entries`, depth + 1)
+        } : {
+          $type: "Set",
+          values: visit(entries, `${path}/values`, depth + 1)
+        };
+      }
+      if (Array.isArray(value)) {
+        const count = Math.min(value.length, import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties);
+        const items = Array.from(
+          { length: count },
+          (_, index) => read(value, String(index), `${path}/${index}`, depth)
+        );
+        if (count < value.length)
+          items.push(
+            omit(path, "collection_limit", { originalCount: value.length })
+          );
+        return items;
+      }
+      const keys = Object.getOwnPropertyNames(object);
+      const result = /* @__PURE__ */ Object.create(null);
+      if (value instanceof Error) {
+        const ownName = Object.getOwnPropertyDescriptor(object, "name");
+        let type = ownName && "value" in ownName ? ownName.value : void 0;
+        if (typeof type !== "string") {
+          const name = Object.getOwnPropertyDescriptor(
+            Object.getPrototypeOf(value),
+            "name"
+          );
+          type = name && "value" in name ? name.value : "Error";
+        }
+        result.type = visit(
+          typeof type === "string" ? type : "Error",
+          `${path}/type`,
+          depth + 1
+        );
+      }
+      for (const key of keys.slice(0, import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties)) {
+        if (["__proto__", "constructor", "prototype"].includes(key)) {
+          result[key] = omit(`${path}/${pointer(key)}`, "unsafe_key");
+          continue;
+        }
+        remaining -= encoder.encode(key).length + 4;
+        result[key] = read(object, key, `${path}/${pointer(key)}`, depth);
+      }
+      if (keys.length > import_telemetry_contracts.DIAGNOSTIC_LIMITS.properties)
+        result.$omittedProperties = omit(path, "property_limit", {
+          originalCount: keys.length
+        });
+      return result;
     } catch {
-      return void 0;
+      return omit(path, "unreadable_object");
+    }
+  };
+  const read = (object, key, path, depth) => {
+    if ((0, import_telemetry_contracts.isPrivateDiagnosticField)(key)) {
+      if (redactions.length < 1e3)
+        redactions.push({
+          path: path.slice(0, 4096),
+          reason: "credential_field"
+        });
+      return "[REDACTED]";
+    }
+    try {
+      const property = Object.getOwnPropertyDescriptor(object, key);
+      if (property && "value" in property)
+        return visit(property.value, path, depth + 1);
+      if (key === "stack" && object instanceof Error && property?.get && property.get === nativeStackGetter)
+        return visit(nativeStack(object, property.get), path, depth + 1);
+      return omit(
+        path,
+        property ? "accessor_not_evaluated" : "unavailable_property"
+      );
+    } catch {
+      return omit(path, "unreadable_property");
     }
-  })() : void 0);
-  const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors2.errorProperty)(value, "cause") : null;
-  return {
-    type: typeof name === "string" ? name.slice(0, 256) : "Error",
-    message: (typeof value === "string" ? value : typeof message === "string" ? message : "Execution reported a fault.").slice(0, 8192),
-    ...typeof stack === "string" ? { stack: stack.slice(0, MAX_STACK_LENGTH) } : {},
-    ...cause !== null && cause !== void 0 ? { cause: projectDetails(cause, depth + 1, seen) } : {}
   };
-};
-var sanitizeProjectedDetails = (details, depth = 0) => ({
-  ...typeof details.type === "string" ? { type: details.type.slice(0, 256) } : {},
-  message: typeof details.message === "string" ? details.message.slice(0, 8192) : "Execution reported a fault.",
-  ...typeof details.stack === "string" ? { stack: details.stack.slice(0, MAX_STACK_LENGTH) } : {},
-  ...depth < MAX_CAUSE_DEPTH && details.cause ? { cause: sanitizeProjectedDetails(details.cause, depth + 1) } : {}
-});
-function exceptionDiagnostics(error, project) {
   try {
-    const details = project ? project(error) : projectDetails(error, 0, /* @__PURE__ */ new WeakSet());
-    return details ? sanitizeProjectedDetails(details) : null;
+    const original = project ? project(error) : error;
+    if (project && original === null) return null;
+    const captured = visit(original, "#/data", 0);
+    const upstreamOmissions = (0, import_errors2.errorProperty)(original, "diagnosticOmissions");
+    if (Array.isArray(upstreamOmissions))
+      for (const note of upstreamOmissions.slice(0, 1e3)) {
+        const path = (0, import_errors2.errorProperty)(note, "path");
+        const reason = (0, import_errors2.errorProperty)(note, "reason");
+        if (typeof path === "string" && typeof reason === "string")
+          omissions.push({
+            path: (0, import_telemetry_contracts.redactDiagnosticText)(path).slice(0, 4096),
+            reason: (0, import_telemetry_contracts.redactDiagnosticText)(reason).slice(0, 128)
+          });
+      }
+    const data = captured && typeof captured === "object" && !Array.isArray(captured) ? captured : {
+      type: "Error",
+      message: typeof captured === "string" ? captured : "Execution reported a fault.",
+      value: captured
+    };
+    if (typeof data.message !== "string" && !("message" in data))
+      data.message = "Execution reported a fault.";
+    if (!("type" in data))
+      data.type = typeof data.name === "string" ? data.name : "Error";
+    const content = {
+      schemaVersion: 1,
+      data,
+      capture: {
+        status: omissions.length ? "partial" : "complete",
+        omissions,
+        redactions
+      }
+    };
+    if (encoder.encode(JSON.stringify(content)).length > import_telemetry_contracts.DIAGNOSTIC_LIMITS.bytes)
+      return {
+        schemaVersion: 1,
+        data: {
+          type: "Error",
+          message: "Diagnostic exceeded the capture budget."
+        },
+        capture: {
+          status: "partial",
+          redactions: [],
+          omissions: [{ path: "#/data", reason: "serialized_byte_limit" }]
+        }
+      };
+    return content;
   } catch {
-    return null;
+    return {
+      schemaVersion: 1,
+      data: { type: "Error", message: "Diagnostic capture failed." },
+      capture: {
+        status: "failed",
+        redactions: [],
+        omissions: [{ path: "#/data", reason: "projection_or_capture_failed" }]
+      }
+    };
   }
 }
+
+// src/error-diagnostics.ts
+function exceptionDiagnostics(error, project) {
+  const content = captureDiagnosticContent(error, project);
+  return !content || content.capture.status === "failed" ? null : content.data;
+}
 function errorDiagnostics(error, project) {
-  const details = exceptionDiagnostics(error, project);
+  const captured = exceptionDiagnostics(error, project);
+  const details = captured ? (0, import_telemetry_contracts2.summarizeDiagnostic)(captured) : null;
   return details ? {
-    errorMessage: details.message,
-    ...details.type ? { errorType: details.type } : {}
+    errorMessage: details.message.slice(0, 8192),
+    ...details.type ? { errorType: details.type.slice(0, 256) } : {}
   } : {};
 }
 
@@ -854,10 +1064,40 @@ async function closeOwnedTools(owned) {
 function captureToolError(observation, error, policy, returned = false) {
   try {
     const reported = returned && error && typeof error === "object" && "isError" in error && error.isError === true && "content" in error && typeof error.content === "string" ? { name: "ToolError", message: error.content } : error;
+    let projected = false;
+    let projection;
+    let projectionFailure;
+    let projectionFailed = false;
+    const project = policy?.error ? (original) => {
+      if (!projected) {
+        projected = true;
+        try {
+          projection = policy.error?.(original);
+        } catch (error2) {
+          projectionFailure = error2;
+          projectionFailed = true;
+        }
+      }
+      if (projectionFailed) throw projectionFailure;
+      return projection ?? null;
+    } : void 0;
     Object.assign(
       observation,
-      errorDiagnostics(policy?.error ? error : reported, policy?.error)
+      errorDiagnostics(policy?.error ? error : reported, project)
+    );
+    const diagnosticId = getHookContext().reasonTrace?.reportError?.(
+      policy?.error ? error : reported,
+      {
+        mechanism: "tool",
+        ...project ? { error: project } : {},
+        correlation: {
+          toolCallId: observation.toolCallId,
+          attemptId: observation.attemptId
+        }
+      }
     );
+    if (typeof diagnosticId === "string")
+      observation.diagnosticId = diagnosticId;
   } catch {
   }
 }
@@ -2743,7 +2983,7 @@ var runReasonToolLoop = async (args) => {
       interruptInstructions: [
         "Human-input rules:",
         "- The kortyx_request_input__* tools pause this reasoning operation and return the validated human response as a normal tool result.",
-        "- Call at most one human-input tool in a model turn, and do not combine it with other tool calls in that turn.",
+        "- You may combine human-input tools with domain tools and output controls. Tools, emitted outputs, and human-input requests run in their requested order. Terminal output publishes last using the completed results.",
         interruptConfig.mode === "required" ? "- You must call at least one human-input tool before returning the final answer." : "- Human input is optional; call a human-input tool only when the request cannot be completed safely without it."
       ].join("\n")
     } : {},
@@ -2753,7 +2993,7 @@ var runReasonToolLoop = async (args) => {
         "- The kortyx_emit__* tools publish validated structured output and return an acknowledgement. You may continue with text or more tools afterward.",
         "- The kortyx_return__* tools publish a validated result and end this reasoning operation. If return tools are available, call exactly one before finishing.",
         "- For contracts with realtime streaming, use kortyx_stream_emit__* or kortyx_stream_return__*. These start a separate streamed JSON generation; its fields become visible as tokens arrive.",
-        "- Call a structured output control tool alone in its model turn."
+        "- You may combine multiple emit controls, domain tools, and human-input requests in one turn. Tools, emitted outputs, and human-input requests run in their requested order; the terminal return runs last. Outputs after domain tools or human input are regenerated using their completed results. Request at most one terminal return per turn."
       ].join("\n")
     } : {}
   });
@@ -2782,6 +3022,19 @@ var runReasonToolLoop = async (args) => {
   );
   let pending = checkpoint?.pending;
   let pendingStepIndex = checkpoint?.pendingStepIndex;
+  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 }
+    });
+  };
+  const resolvedInterrupts = checkpoint?.resolvedInterrupts ?? [];
+  for (const request of resolvedInterrupts) ctx.node.replayInterrupt?.(request);
   const approvedCalls = checkpoint?.approvedCalls ?? [];
   const interruptHistory = checkpoint?.interruptHistory ?? [];
   const emissions = checkpoint?.emissions ?? [];
@@ -2793,8 +3046,10 @@ var runReasonToolLoop = async (args) => {
       messages,
       steps,
       approvedCalls,
+      resolvedInterrupts,
       interruptHistory,
       emissions,
+      outputContractCorrections,
       ...returned ? { returned } : {},
       finalizing,
       ...pending ? { pending } : {},
@@ -2802,6 +3057,10 @@ var runReasonToolLoop = async (args) => {
     };
     ctx.stateDirty = true;
   };
+  const rememberInterrupt = (request) => {
+    resolvedInterrupts.push(request);
+    save();
+  };
   const emitToolEvent = (event, payload) => {
     ctx.node.emit(event, {
       ...payload,
@@ -2811,7 +3070,7 @@ var runReasonToolLoop = async (args) => {
     });
   };
   try {
-    for (let stepIndex = pending ? pendingStepIndex ?? steps.length - 1 : steps.length; stepIndex < maxSteps; stepIndex += 1) {
+    for (let stepIndex = pending ? pendingStepIndex ?? steps.length - 1 : steps.length; stepIndex < maxSteps; stepIndex = steps.length) {
       (0, import_core5.throwIfExecutionAborted)(abortSignal);
       traceSpan?.addEvent?.("useReason.tool-step.start", {
         stepIndex,
@@ -2948,273 +3207,301 @@ var runReasonToolLoop = async (args) => {
       const outputCalls = toolCalls.filter(
         (call) => outputByToolName.has(call.name)
       );
-      if (outputCalls.length > 0) {
-        if (toolCalls.length !== 1)
-          throw new Error(
-            "A useReason output contract call must be the only tool call in its model turn."
-          );
-        const call = outputCalls[0];
-        if (!call) throw new Error("Missing useReason output control call.");
-        const resolved = outputByToolName.get(call.name);
-        if (!resolved)
-          throw new Error(
-            `Unknown useReason output contract tool "${call.name}".`
-          );
-        if (toolResults.some((result3) => result3.toolCallId === call.id)) {
-          pending = void 0;
-          pendingStepIndex = void 0;
-          save();
-          continue;
+      const returnCalls = outputCalls.filter(
+        (call) => outputByToolName.get(call.name)?.kind === "return"
+      );
+      if (returnCalls.length > 1) {
+        let corrected = false;
+        for (const call of returnCalls) {
+          if (toolResults.some((result3) => result3.toolCallId === call.id))
+            continue;
+          const result2 = {
+            toolCallId: call.id,
+            name: call.name,
+            isError: true,
+            content: "MULTIPLE_TERMINAL_OUTPUTS: No terminal output was published. Select exactly one return contract using the tool and human-input results. Do not repeat completed calls. Multiple emit contracts are allowed."
+          };
+          toolResults.push(result2);
+          messages.push({ role: "tool", ...result2 });
+          corrected = true;
         }
-        if (resolved.kind === "emit" && emissions.length >= (useReasonArgs.outputs?.maxEmissions ?? 16))
-          throw new Error(
-            `useReason reached outputs.maxEmissions (${useReasonArgs.outputs?.maxEmissions ?? 16}).`
+        if (corrected) outputContractCorrections += 1;
+        save();
+      }
+      const orderedCalls = [
+        ...toolCalls.filter(
+          (call) => outputByToolName.get(call.name)?.kind !== "return"
+        ),
+        ...returnCalls
+      ];
+      for (const toolCall of orderedCalls) {
+        (0, import_core5.throwIfExecutionAborted)(abortSignal);
+        if (outputByToolName.has(toolCall.name)) {
+          const call = toolCall;
+          const hasEvidenceCalls = toolResults.some(
+            (result3) => !outputByToolName.has(result3.name)
           );
-        let data;
-        if (resolved.stream) {
-          if (!stream)
+          const resolved = outputByToolName.get(call.name);
+          if (!resolved)
             throw new Error(
-              `useReason streaming output contract "${resolved.name}" requires stream: true.`
+              `Unknown useReason output contract tool "${call.name}".`
             );
-          if (stepIndex + 1 >= maxSteps)
-            throw new Error(
-              `useReason output streaming requires another model pass within maxSteps (${maxSteps}).`
-            );
-          const instruction = call.input && typeof call.input === "object" && !Array.isArray(call.input) ? call.input.instruction : void 0;
-          if (typeof instruction !== "string" || instruction.trim().length === 0)
+          if (toolResults.some((result3) => result3.toolCallId === call.id)) {
+            if (resolved.kind === "return" && returned) completed = true;
+            continue;
+          }
+          if (resolved.kind === "emit" && emissions.length >= (useReasonArgs.outputs?.maxEmissions ?? 16))
             throw new Error(
-              `useReason streaming output contract "${resolved.name}" requires an instruction.`
-            );
-          const streamId = `${opId}:${resolved.kind}:${resolved.name}:${resolved.kind === "emit" ? emissions.length : "return"}`;
-          const structured = {
-            dataType: resolved.contract.schemaId,
-            schemaId: resolved.contract.schemaId,
-            schemaVersion: resolved.contract.schemaVersion,
-            fields: resolved.contract.stream?.fields
-          };
-          const inferred = inferOutputFormat(
-            resolved.contract.schema,
-            void 0
-          );
-          try {
-            const outputStep = await reasonEngine(
-              {
-                ...useReasonArgs,
-                tools: [],
-                ...inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {},
-                messages: [
-                  ...messages,
-                  {
-                    role: "tool",
-                    toolCallId: call.id,
-                    name: call.name,
-                    content: "Generating the requested structured output."
-                  },
-                  {
-                    role: "user",
-                    content: withOutputGuardrails(
-                      instruction,
-                      resolved.contract.schema
-                    )
-                  }
-                ],
-                emit: false,
-                stream,
-                ...emit && stream ? {
-                  onTextChunk: createStructuredOutputStreamer(
-                    { structured },
-                    id,
-                    streamId
-                  )
-                } : {}
-              },
-              { ...id ? { id } : {}, opId }
+              `useReason reached outputs.maxEmissions (${useReasonArgs.outputs?.maxEmissions ?? 16}).`
             );
-            if (outputStep.toolCalls?.length)
+          let data;
+          if (resolved.stream || hasEvidenceCalls) {
+            if (resolved.stream && !stream)
               throw new Error(
-                `Provider requested a tool during streamed output contract "${resolved.name}".`
+                `useReason streaming output contract "${resolved.name}" requires stream: true.`
               );
-            aggregatedUsage = mergeUsage(aggregatedUsage, outputStep.usage);
-            accumulateTokenUsage(outputStep.usage);
-            aggregatedWarnings = mergeWarnings(
-              aggregatedWarnings,
-              mergeWarnings(inferred.warnings, outputStep.warnings)
-            );
-            aggregatedProviderMetadata = mergeProviderMetadata(
-              aggregatedProviderMetadata,
-              outputStep.providerMetadata
+            if (steps.length >= maxSteps) {
+              const message = `useReason output generation requires another model pass within toolExecution.maxSteps (${maxSteps}). Increase maxSteps to allow outputs to use completed tool and interrupt results.`;
+              throw new import_errors6.ProviderRequestError(message, {
+                code: "REASON_OUTPUT_BUDGET_EXHAUSTED",
+                operation: "useReason",
+                safeMessage: message,
+                retryable: false,
+                details: { maxSteps, modelPasses: steps.length }
+              });
+            }
+            const streamInstruction = call.input && typeof call.input === "object" && !Array.isArray(call.input) ? call.input.instruction : void 0;
+            if (resolved.stream && (typeof streamInstruction !== "string" || streamInstruction.trim().length === 0))
+              throw new Error(
+                `useReason streaming output contract "${resolved.name}" requires an instruction.`
+              );
+            const instruction = [
+              `Generate output contract "${resolved.name}": ${resolved.contract.description}`,
+              "Use the completed tool and human-input results. Do not assume results for pending calls.",
+              resolved.stream ? String(streamInstruction) : `Regenerate this original draft, which was written before those results were available: ${JSON.stringify(call.input)}`
+            ].join("\n\n");
+            const streamId = `${opId}:${resolved.kind}:${resolved.name}:${resolved.kind === "emit" ? emissions.length : "return"}`;
+            const structured = {
+              dataType: resolved.contract.schemaId,
+              schemaId: resolved.contract.schemaId,
+              schemaVersion: resolved.contract.schemaVersion,
+              fields: resolved.contract.stream?.fields
+            };
+            const inferred = inferOutputFormat(
+              resolved.contract.schema,
+              void 0
             );
-            finalFinishReason = outputStep.finishReason;
-            finalRaw = outputStep.raw;
-            data = parseReasonOutputWithSchema({
-              text: outputStep.text,
-              schema: resolved.contract.schema,
-              ...outputStep.finishReason ? { finishReason: outputStep.finishReason } : {},
-              ...aggregatedUsage ? { usage: aggregatedUsage } : {},
-              label: `useReason output contract "${resolved.name}"`
-            });
-            steps.push({
-              stepIndex: stepIndex + 1,
+            const outputRecord = {
+              stepIndex: steps.length,
               kind: "output",
-              text: outputStep.text,
+              text: "",
               toolCalls: [],
-              toolResults: [],
-              ...outputStep.usage ? { usage: outputStep.usage } : {},
-              ...outputStep.finishReason ? { finishReason: outputStep.finishReason } : {},
-              ...outputStep.providerMetadata ? { providerMetadata: outputStep.providerMetadata } : {},
-              ...outputStep.warnings ? { warnings: outputStep.warnings } : {}
-            });
-            stepIndex += 1;
-          } catch (error) {
-            traceSpan?.addEvent?.("useReason.output.invalidated", {
-              contract: resolved.name,
-              kind: resolved.kind,
-              schemaId: resolved.contract.schemaId,
-              schemaVersion: resolved.contract.schemaVersion,
-              streamId
-            });
-            if (emit) {
-              try {
-                ctx.node.emit("structured_data_invalidated", {
-                  node: ctx.node.graph.node,
-                  streamId
-                });
-              } catch {
+              toolResults: []
+            };
+            steps.push(outputRecord);
+            save();
+            try {
+              const outputStep = await reasonEngine(
+                {
+                  ...useReasonArgs,
+                  tools: [],
+                  ...inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {},
+                  messages: [
+                    ...messages,
+                    ...toolCalls.filter(
+                      (pendingCall) => !toolResults.some(
+                        (result3) => result3.toolCallId === pendingCall.id
+                      )
+                    ).map(
+                      (pendingCall) => ({
+                        role: "tool",
+                        toolCallId: pendingCall.id,
+                        name: pendingCall.name,
+                        content: "This call has not completed yet. Use only completed results; do not assume a result for this pending call."
+                      })
+                    ),
+                    {
+                      role: "user",
+                      content: withOutputGuardrails(
+                        instruction,
+                        resolved.contract.schema
+                      )
+                    }
+                  ],
+                  emit: false,
+                  stream: resolved.stream && stream,
+                  ...emit && resolved.stream && stream ? {
+                    onTextChunk: createStructuredOutputStreamer(
+                      { structured },
+                      id,
+                      streamId
+                    )
+                  } : {}
+                },
+                { ...id ? { id } : {}, opId }
+              );
+              if (outputStep.toolCalls?.length)
+                throw new Error(
+                  `Provider requested a tool during streamed output contract "${resolved.name}".`
+                );
+              aggregatedUsage = mergeUsage(aggregatedUsage, outputStep.usage);
+              accumulateTokenUsage(outputStep.usage);
+              aggregatedWarnings = mergeWarnings(
+                aggregatedWarnings,
+                mergeWarnings(inferred.warnings, outputStep.warnings)
+              );
+              aggregatedProviderMetadata = mergeProviderMetadata(
+                aggregatedProviderMetadata,
+                outputStep.providerMetadata
+              );
+              finalFinishReason = outputStep.finishReason;
+              finalRaw = outputStep.raw;
+              Object.assign(outputRecord, {
+                stepIndex: outputRecord.stepIndex,
+                kind: "output",
+                text: outputStep.text,
+                toolCalls: [],
+                toolResults: [],
+                ...outputStep.usage ? { usage: outputStep.usage } : {},
+                ...outputStep.finishReason ? { finishReason: outputStep.finishReason } : {},
+                ...outputStep.providerMetadata ? { providerMetadata: outputStep.providerMetadata } : {},
+                ...outputStep.warnings ? { warnings: outputStep.warnings } : {}
+              });
+              save();
+              data = parseReasonOutputWithSchema({
+                text: outputStep.text,
+                schema: resolved.contract.schema,
+                ...outputStep.finishReason ? { finishReason: outputStep.finishReason } : {},
+                ...aggregatedUsage ? { usage: aggregatedUsage } : {},
+                label: `useReason output contract "${resolved.name}"`
+              });
+            } catch (error) {
+              traceSpan?.addEvent?.("useReason.output.invalidated", {
+                contract: resolved.name,
+                kind: resolved.kind,
+                schemaId: resolved.contract.schemaId,
+                schemaVersion: resolved.contract.schemaVersion,
+                streamId
+              });
+              if (emit && resolved.stream) {
+                try {
+                  ctx.node.emit("structured_data_invalidated", {
+                    node: ctx.node.graph.node,
+                    streamId
+                  });
+                } catch {
+                }
               }
+              throw error;
             }
-            throw error;
+          } else {
+            data = parseWithSchema(
+              resolved.contract.schema,
+              call.input,
+              `useReason output contract "${resolved.name}"`
+            );
           }
-        } else {
-          data = parseWithSchema(
-            resolved.contract.schema,
-            call.input,
-            `useReason output contract "${resolved.name}"`
-          );
-        }
-        const entry = { contract: resolved.name, data };
-        const emissionIndex = emissions.length;
-        if (resolved.kind === "emit")
-          emissions.push(entry);
-        else returned = entry;
-        if (emit)
-          emitStructuredData({
-            kind: "final",
-            data,
-            dataType: resolved.contract.schemaId,
+          const entry = { contract: resolved.name, data };
+          const emissionIndex = emissions.length;
+          if (resolved.kind === "emit")
+            emissions.push(entry);
+          else returned = entry;
+          if (emit)
+            emitStructuredData({
+              kind: "final",
+              data,
+              dataType: resolved.contract.schemaId,
+              schemaId: resolved.contract.schemaId,
+              schemaVersion: resolved.contract.schemaVersion,
+              streamId: `${opId}:${resolved.kind}:${resolved.name}:${resolved.kind === "emit" ? emissionIndex : "return"}`,
+              ...id ? { id } : {}
+            });
+          traceSpan?.addEvent?.("useReason.output.emitted", {
+            contract: resolved.name,
+            kind: resolved.kind,
             schemaId: resolved.contract.schemaId,
             schemaVersion: resolved.contract.schemaVersion,
-            streamId: `${opId}:${resolved.kind}:${resolved.name}:${resolved.kind === "emit" ? emissionIndex : "return"}`,
-            ...id ? { id } : {}
+            emissionIndex,
+            data
           });
-        traceSpan?.addEvent?.("useReason.output.emitted", {
-          contract: resolved.name,
-          kind: resolved.kind,
-          schemaId: resolved.contract.schemaId,
-          schemaVersion: resolved.contract.schemaVersion,
-          emissionIndex,
-          data
-        });
-        if (resolved.kind === "return") {
-          pending = void 0;
-          pendingStepIndex = void 0;
-          completed = true;
+          const result2 = normalizeToolResult(call, { emitted: true, data });
+          toolResults.push(result2);
+          messages.push({
+            role: "tool",
+            content: result2.content,
+            toolCallId: result2.toolCallId,
+            name: result2.name
+          });
+          if (resolved.kind === "return") completed = true;
           save();
-          break;
+          continue;
         }
-        const result2 = normalizeToolResult(call, { emitted: true, data });
-        toolResults.push(result2);
-        messages.push({
-          role: "tool",
-          content: result2.content,
-          toolCallId: result2.toolCallId,
-          name: result2.name
-        });
-        pending = void 0;
-        pendingStepIndex = void 0;
-        save();
-        continue;
-      }
-      const interruptCalls = toolCalls.filter(
-        (call) => interruptByToolName.has(call.name)
-      );
-      if (interruptCalls.length > 0) {
-        if (toolCalls.length !== 1)
-          throw new Error(
-            "A useReason interrupt contract call must be the only tool call in its model turn."
-          );
-        const interruptCall = interruptCalls[0];
-        if (!interruptCall)
-          throw new Error("Missing useReason interrupt control call.");
-        if (interruptHistory.length >= (interruptConfig?.maxRequests ?? 1))
-          throw new Error(
-            `useReason reached interrupts.maxRequests (${interruptConfig?.maxRequests ?? 1}).`
-          );
-        const resolved = interruptByToolName.get(interruptCall.name);
-        if (!resolved)
-          throw new Error(
-            `Unknown useReason interrupt contract tool "${interruptCall.name}".`
+        if (interruptByToolName.has(toolCall.name)) {
+          const resolved = interruptByToolName.get(toolCall.name);
+          if (!resolved)
+            throw new Error(
+              `Unknown useReason interrupt contract tool "${toolCall.name}".`
+            );
+          if (toolResults.some((result3) => result3.toolCallId === toolCall.id)) {
+            continue;
+          }
+          if (interruptHistory.length >= (interruptConfig?.maxRequests ?? 1))
+            throw new Error(
+              `useReason reached interrupts.maxRequests (${interruptConfig?.maxRequests ?? 1}).`
+            );
+          const request = parseWithSchema(
+            resolved.contract.requestSchema,
+            toolCall.input,
+            `useReason interrupt contract "${resolved.name}" request`
           );
-        if (toolResults.some((result3) => result3.toolCallId === interruptCall.id)) {
-          pending = void 0;
-          pendingStepIndex = void 0;
+          traceSpan?.addEvent?.("useReason.interrupt.requested", {
+            checkpointKey,
+            contract: resolved.name,
+            interruptIndex: interruptHistory.length
+          });
+          const question = request && typeof request === "object" && !Array.isArray(request) && typeof request.question === "string" ? String(request.question) : void 0;
+          const response = await awaitInterruptInternal({
+            onResolved: rememberInterrupt,
+            request: {
+              kind: "custom",
+              request,
+              contract: resolved.name,
+              ...question ? { question } : {},
+              schemaId: resolved.contract.schemaId,
+              schemaVersion: resolved.contract.schemaVersion
+            },
+            responseSchema: resolved.contract.responseSchema,
+            id: `${id ?? "reason"}:${resolved.name}:${interruptHistory.length + 1}`,
+            meta: {
+              __kortyxReason: {
+                opId,
+                stepIndex,
+                interruptIndex: interruptHistory.length,
+                contract: resolved.name
+              }
+            }
+          });
+          const result2 = normalizeToolResult(toolCall, response);
+          toolResults.push(result2);
+          messages.push({
+            role: "tool",
+            content: result2.content,
+            toolCallId: result2.toolCallId,
+            name: result2.name
+          });
+          interruptHistory.push({
+            contract: resolved.name,
+            request,
+            response
+          });
+          traceSpan?.addEvent?.("useReason.interrupt.resolved", {
+            checkpointKey,
+            contract: resolved.name,
+            interruptIndex: interruptHistory.length - 1
+          });
           save();
           continue;
         }
-        const request = parseWithSchema(
-          resolved.contract.requestSchema,
-          interruptCall.input,
-          `useReason interrupt contract "${resolved.name}" request`
-        );
-        traceSpan?.addEvent?.("useReason.interrupt.requested", {
-          checkpointKey,
-          contract: resolved.name,
-          interruptIndex: interruptHistory.length
-        });
-        const question = request && typeof request === "object" && !Array.isArray(request) && typeof request.question === "string" ? String(request.question) : void 0;
-        const response = await awaitInterruptInternal({
-          request: {
-            kind: "custom",
-            request,
-            contract: resolved.name,
-            ...question ? { question } : {},
-            schemaId: resolved.contract.schemaId,
-            schemaVersion: resolved.contract.schemaVersion
-          },
-          responseSchema: resolved.contract.responseSchema,
-          id: `${id ?? "reason"}:${resolved.name}:${interruptHistory.length + 1}`,
-          meta: {
-            __kortyxReason: {
-              opId,
-              stepIndex,
-              interruptIndex: interruptHistory.length,
-              contract: resolved.name
-            }
-          }
-        });
-        const result2 = normalizeToolResult(interruptCall, response);
-        toolResults.push(result2);
-        messages.push({
-          role: "tool",
-          content: result2.content,
-          toolCallId: result2.toolCallId,
-          name: result2.name
-        });
-        interruptHistory.push({
-          contract: resolved.name,
-          request,
-          response
-        });
-        traceSpan?.addEvent?.("useReason.interrupt.resolved", {
-          checkpointKey,
-          contract: resolved.name,
-          interruptIndex: interruptHistory.length - 1
-        });
-        pending = void 0;
-        pendingStepIndex = void 0;
-        save();
-        continue;
-      }
-      for (const toolCall of toolCalls) {
         if (toolResults.some((result2) => result2.toolCallId === toolCall.id)) {
           await replayToolObservations(
             steps[stepIndex]?.toolObservations?.filter(
@@ -3260,6 +3547,7 @@ var runReasonToolLoop = async (args) => {
             "waiting"
           );
           const approval = await awaitInterruptInternal({
+            onResolved: rememberInterrupt,
             id: `tool:${toolCall.id}`,
             request: {
               kind: "choice",
@@ -3374,22 +3662,24 @@ var runReasonToolLoop = async (args) => {
             });
           }
         }
-        const completed2 = toolResults.at(-1);
-        if (completed2)
+        const completedToolResult = toolResults.at(-1);
+        if (completedToolResult)
           messages.push({
             role: "tool",
-            content: completed2.content,
-            toolCallId: completed2.toolCallId,
-            name: completed2.name,
-            ...completed2.isError !== void 0 ? { isError: completed2.isError } : {}
+            content: completedToolResult.content,
+            toolCallId: completedToolResult.toolCallId,
+            name: completedToolResult.name,
+            ...completedToolResult.isError !== void 0 ? { isError: completedToolResult.isError } : {}
           });
         save();
       }
       pending = void 0;
       pendingStepIndex = void 0;
       save();
+      if (completed) break;
     }
     if (!completed) {
+      if (outputContractCorrections > 0) throw correctionExhausted();
       throw new Error(
         `useReason tool loop reached maxSteps (${maxSteps}) before producing a final response.`
       );
@@ -3451,7 +3741,11 @@ var runReasonToolLoop = async (args) => {
         output: useReasonArgs.telemetry?.output ?? returned?.data ?? finalOutput ?? finalText
       }
     });
-    ctx.currentNodeState.byKey[checkpointKey] = { status: "completed", result };
+    ctx.currentNodeState.byKey[checkpointKey] = {
+      status: "completed",
+      result,
+      resolvedInterrupts
+    };
     ctx.stateDirty = true;
     return result;
   } catch (error) {
@@ -3528,6 +3822,8 @@ async function runReason(args) {
   const opId = checkpointValue && typeof checkpointValue === "object" && "status" in checkpointValue && checkpointValue.status === "tool_loop" && "opId" in checkpointValue && typeof checkpointValue.opId === "string" ? checkpointValue.opId : provisionalOpId;
   const existingCompleted = readReasonCompletedCheckpoint(checkpointValue);
   if (existingCompleted) {
+    for (const request of existingCompleted.resolvedInterrupts ?? [])
+      ctx.node.replayInterrupt?.(request);
     await replayToolObservations(
       existingCompleted.result.steps?.flatMap(
         (step) => step.toolObservations ?? []