@kortyx/agent 0.25.0 → 0.26.0

package/dist/index.js

@@ -52,6 +52,7 @@ var require_internal = __commonJS({
     var internal_exports = {};
     __export2(internal_exports, {
       errorDiagnostics: () => errorDiagnostics,
+      exceptionDiagnostics: () => exceptionDiagnostics,
       isModelTraceSpan: () => isModelTraceSpan,
       runReasonEngine: () => runReasonEngine,
       safeSpan: () => safeSpan,
@@ -61,26 +62,53 @@ var require_internal = __commonJS({
     });
     module2.exports = __toCommonJS2(internal_exports);
     var import_errors6 = require("@kortyx/core/errors");
-    function errorDiagnostics(error, project) {
+    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);
+      }
+      const name = (0, import_errors6.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
+      const message = (0, import_errors6.errorProperty)(value, "message");
+      const stack = (0, import_errors6.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
+        try {
+          return value.stack;
+        } catch {
+          return void 0;
+        }
+      })() : void 0);
+      const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors6.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 name = (0, import_errors6.errorProperty)(error, "name") ?? (error instanceof Error ? error.name : void 0);
-        const message = (0, import_errors6.errorProperty)(error, "message");
-        const details = project ? project(error) : {
-          type: typeof name === "string" ? name : "Error",
-          message: typeof error === "string" ? error : typeof message === "string" ? message : "Execution reported a fault."
-        };
-        if (!details) return {};
-        const projectedMessage = details.message;
-        const projectedType = details.type;
-        if (typeof projectedMessage !== "string") return {};
-        return {
-          errorMessage: projectedMessage.slice(0, 8192),
-          ...typeof projectedType === "string" ? { errorType: projectedType.slice(0, 256) } : {}
-        };
+        const details = project ? project(error) : projectDetails(error, 0, /* @__PURE__ */ new WeakSet());
+        return details ? sanitizeProjectedDetails(details) : null;
       } catch {
-        return {};
+        return null;
       }
     }
+    function errorDiagnostics(error, project) {
+      const details = exceptionDiagnostics(error, project);
+      return details ? {
+        errorMessage: details.message,
+        ...details.type ? { errorType: details.type } : {}
+      } : {};
+    }
     function isModelTraceSpan(name) {
       return name === "runReasonEngine" || name === "useReason";
     }
@@ -497,8 +525,10 @@ var require_dist = __commonJS({
       WorkflowCallError: () => WorkflowCallError,
       completeResponse: () => completeResponse,
       createWorkflowHooks: () => createWorkflowHooks,
+      defineInterruptContract: () => defineInterruptContract,
       emitWorkflowCall: () => emitWorkflowCall2,
       parallel: () => parallel,
+      reportError: () => reportError,
       runWithHookContext: () => runWithHookContext,
       useAbortSignal: () => useAbortSignal,
       useInterrupt: () => useInterrupt,
@@ -807,6 +837,95 @@ var require_dist = __commonJS({
       );
       return Promise.resolve(response);
     };
+    var CONTROL_TOOL_PREFIX = "kortyx_request_input__";
+    var LEGACY_CONTRACT_NAME = "default";
+    var legacyWarningEmitted = false;
+    var legacyConfigs = /* @__PURE__ */ new WeakSet();
+    var defineInterruptContract = (contract) => {
+      if (!contract || typeof contract !== "object")
+        throw new Error("defineInterruptContract requires a contract object.");
+      for (const [field, value] of [
+        ["description", contract.description],
+        ["schemaId", contract.schemaId],
+        ["schemaVersion", contract.schemaVersion]
+      ])
+        if (typeof value !== "string" || value.trim().length === 0)
+          throw new Error(
+            `Interrupt contract ${field} must be a non-empty string.`
+          );
+      if (typeof contract.requestSchema?.safeParse !== "function")
+        throw new Error(
+          "Interrupt contract requestSchema must provide safeParse(value)."
+        );
+      if (typeof contract.responseSchema?.safeParse !== "function")
+        throw new Error(
+          "Interrupt contract responseSchema must provide safeParse(value)."
+        );
+      return contract;
+    };
+    var interruptControlToolName = (name) => `${CONTROL_TOOL_PREFIX}${name}`;
+    var isInterruptControlToolName = (name) => name.startsWith(CONTROL_TOOL_PREFIX);
+    var assertInterruptContractName = (name) => {
+      if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name))
+        throw new Error(
+          `Invalid useReason interrupt contract name "${name}". Use letters, numbers, underscores, or hyphens, starting with a letter.`
+        );
+      if (interruptControlToolName(name).length > 64)
+        throw new Error(
+          `useReason interrupt contract name "${name}" is too long for a provider tool name.`
+        );
+    };
+    var warnLegacyUseReasonInterrupt = () => {
+      if (legacyWarningEmitted) return;
+      legacyWarningEmitted = true;
+      process.emitWarning(
+        "useReason({ interrupt }) is deprecated and will be removed in the next major release. Define an interrupt contract with defineInterruptContract() and pass it through useReason({ interrupts: { contracts } }). See docs/internal/next-major-removals.md.",
+        {
+          code: "KORTYX_USE_REASON_INTERRUPT_DEPRECATED",
+          type: "DeprecationWarning"
+        }
+      );
+    };
+    var normalizeReasonInterrupts = (args) => {
+      if (args.interrupt && args.interrupts)
+        throw new Error(
+          "useReason cannot receive both deprecated `interrupt` and `interrupts`. Migrate the legacy configuration to an interrupt contract."
+        );
+      if (args.interrupts) {
+        for (const [name, contract] of Object.entries(args.interrupts.contracts)) {
+          assertInterruptContractName(name);
+          defineInterruptContract(contract);
+        }
+        if (Object.keys(args.interrupts.contracts).length === 0)
+          throw new Error("useReason interrupts.contracts cannot be empty.");
+        if (args.interrupts.maxRequests !== void 0 && (!Number.isInteger(args.interrupts.maxRequests) || args.interrupts.maxRequests < 1))
+          throw new Error("useReason interrupts.maxRequests must be at least 1.");
+        return args.interrupts;
+      }
+      if (!args.interrupt) return void 0;
+      warnLegacyUseReasonInterrupt();
+      const normalized = {
+        mode: args.interrupt.mode,
+        maxRequests: 1,
+        contracts: {
+          [LEGACY_CONTRACT_NAME]: {
+            description: "Ask the user for the additional information required to complete this request.",
+            requestSchema: args.interrupt.requestSchema,
+            responseSchema: args.interrupt.responseSchema ?? {
+              safeParse: (value) => ({
+                success: true,
+                data: value
+              })
+            },
+            schemaId: args.interrupt.schemaId ?? "kortyx.legacy-interrupt",
+            schemaVersion: args.interrupt.schemaVersion ?? "1"
+          }
+        }
+      };
+      legacyConfigs.add(normalized);
+      return normalized;
+    };
+    var isLegacyInterruptContracts = (config) => Boolean(config && legacyConfigs.has(config));
     var import_core62 = require("@kortyx/core");
     function safeSpan(span) {
       const guard = (fn) => (...args) => {
@@ -977,26 +1096,53 @@ var require_dist = __commonJS({
     var import_core22 = require("@kortyx/core");
     var import_errors32 = require("@kortyx/core/errors");
     var import_errors22 = require("@kortyx/core/errors");
-    function errorDiagnostics(error, project) {
+    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);
+      }
+      const name = (0, import_errors22.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
+      const message = (0, import_errors22.errorProperty)(value, "message");
+      const stack = (0, import_errors22.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
+        try {
+          return value.stack;
+        } catch {
+          return void 0;
+        }
+      })() : void 0);
+      const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors22.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 name = (0, import_errors22.errorProperty)(error, "name") ?? (error instanceof Error ? error.name : void 0);
-        const message = (0, import_errors22.errorProperty)(error, "message");
-        const details = project ? project(error) : {
-          type: typeof name === "string" ? name : "Error",
-          message: typeof error === "string" ? error : typeof message === "string" ? message : "Execution reported a fault."
-        };
-        if (!details) return {};
-        const projectedMessage = details.message;
-        const projectedType = details.type;
-        if (typeof projectedMessage !== "string") return {};
-        return {
-          errorMessage: projectedMessage.slice(0, 8192),
-          ...typeof projectedType === "string" ? { errorType: projectedType.slice(0, 256) } : {}
-        };
+        const details = project ? project(error) : projectDetails(error, 0, /* @__PURE__ */ new WeakSet());
+        return details ? sanitizeProjectedDetails(details) : null;
       } catch {
-        return {};
+        return null;
       }
     }
+    function errorDiagnostics(error, project) {
+      const details = exceptionDiagnostics(error, project);
+      return details ? {
+        errorMessage: details.message,
+        ...details.type ? { errorType: details.type } : {}
+      } : {};
+    }
     var import_node_crypto22 = require("crypto");
     function emitWorkflowCall2(telemetry, type, payload) {
       const base = telemetry?.correlation;
@@ -2756,6 +2902,7 @@ ${tryStringify2(args.response)}`
     };
     var import_core52 = require("@kortyx/core");
     var import_errors62 = require("@kortyx/core/errors");
+    var import_zod42 = require("zod");
     var toToolDefinitions = (tools2) => tools2.map((tool) => ({
       name: tool.name,
       ...tool.title ? { title: tool.title } : {},
@@ -2791,7 +2938,12 @@ ${tryStringify2(args.response)}`
       };
     };
     var createInitialMessages = (args) => [
-      ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
+      ...typeof args.system === "string" || args.interruptInstructions ? [
+        {
+          role: "system",
+          content: [args.system, args.interruptInstructions].filter((value) => Boolean(value)).join("\n\n")
+        }
+      ] : [],
       { role: "user", content: String(args.input ?? "") }
     ];
     var runReasonToolLoop = async (args) => {
@@ -2806,19 +2958,23 @@ ${tryStringify2(args.response)}`
       const checkpoint = saved?.status === "tool_loop" ? saved : void 0;
       const opId = checkpoint?.opId ?? args.opId;
       const tools2 = useReasonArgs.tools ?? [];
+      const interruptConfig = normalizeReasonInterrupts({
+        interrupt: useReasonArgs.interrupt,
+        interrupts: useReasonArgs.interrupts
+      });
+      const interruptByToolName = /* @__PURE__ */ new Map();
       const toolByName = /* @__PURE__ */ new Map();
       let separateOutput = false;
       for (const tool of tools2) {
+        if (isInterruptControlToolName(tool.name))
+          throw new Error(
+            `useReason tool name "${tool.name}" uses the reserved interrupt control-tool namespace.`
+          );
         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."
-        );
-      }
       separateOutput = Boolean(
         useReasonArgs.model.provider.getModel(useReasonArgs.model.modelId, {
           ...useReasonArgs.model.options,
@@ -2830,21 +2986,63 @@ ${tryStringify2(args.response)}`
           ) ?? {}
         }).requiresSeparateStructuredOutput
       );
-      const toolDefinitions = toToolDefinitions(tools2);
+      const interruptDefinitions = [];
+      for (const [name, contract] of Object.entries(
+        interruptConfig?.contracts ?? {}
+      )) {
+        const toolName = interruptControlToolName(name);
+        if (toolByName.has(toolName))
+          throw new Error(
+            `useReason tool name "${toolName}" is reserved for interrupt contracts.`
+          );
+        let inputSchema;
+        try {
+          inputSchema = (0, import_zod42.toJSONSchema)(contract.requestSchema);
+        } catch (error) {
+          throw new Error(
+            `useReason interrupt contract "${name}" requestSchema must support JSON Schema conversion.`,
+            { cause: error }
+          );
+        }
+        interruptByToolName.set(toolName, { name, contract });
+        interruptDefinitions.push({
+          name: toolName,
+          title: `Request human input: ${name}`,
+          description: [
+            contract.description,
+            "Call this only when human input is needed. Execution pauses until the validated response is returned as this tool's result."
+          ].join(" "),
+          inputSchema,
+          metadata: {
+            kortyxControl: "interrupt",
+            contract: name,
+            schemaId: contract.schemaId,
+            schemaVersion: contract.schemaVersion
+          }
+        });
+      }
+      const toolDefinitions = [
+        ...toToolDefinitions(tools2),
+        ...interruptDefinitions
+      ];
       let finalizing = checkpoint?.finalizing ?? false;
       let completed = false;
       const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
       const messages = checkpoint?.messages ?? createInitialMessages({
         system: useReasonArgs.system,
-        input: useReasonArgs.outputSchema ? withOutputGuardrails(useReasonArgs.input, useReasonArgs.outputSchema) : useReasonArgs.input
+        input: useReasonArgs.outputSchema ? withOutputGuardrails(useReasonArgs.input, useReasonArgs.outputSchema) : useReasonArgs.input,
+        ...interruptConfig ? {
+          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.",
+            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")
+        } : {}
       });
       const steps = checkpoint?.steps ?? [];
-      const allToolCalls = steps.flatMap(
-        (step) => step.toolCalls
-      );
-      const allToolResults = steps.flatMap(
-        (step) => step.toolResults
-      );
+      const allToolCalls = steps.flatMap((step) => step.toolCalls).filter((call) => !interruptByToolName.has(call.name));
+      const allToolResults = steps.flatMap((step) => step.toolResults).filter((result) => !interruptByToolName.has(result.name));
       let finalText = "";
       let finalRaw;
       let finalOutput;
@@ -2860,6 +3058,7 @@ ${tryStringify2(args.response)}`
       );
       let pending = checkpoint?.pending;
       const approvedCalls = checkpoint?.approvedCalls ?? [];
+      const interruptHistory = checkpoint?.interruptHistory ?? [];
       const save = () => {
         ctx.currentNodeState.byKey[checkpointKey] = {
           status: "tool_loop",
@@ -2867,6 +3066,7 @@ ${tryStringify2(args.response)}`
           messages,
           steps,
           approvedCalls,
+          interruptHistory,
           finalizing,
           ...pending ? { pending } : {}
         };
@@ -2945,6 +3145,10 @@ ${tryStringify2(args.response)}`
               ...step.warnings ? { warnings: step.warnings } : {}
             });
           if (toolCalls.length === 0) {
+            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."
+              );
             if (separateOutput && !finalizing) {
               if (args.allowValidatedToolOutput && useReasonArgs.outputSchema) {
                 try {
@@ -2989,7 +3193,9 @@ ${tryStringify2(args.response)}`
               "Provider requested a tool during schema-only finalization."
             );
           if (!reused) {
-            allToolCalls.push(...toolCalls);
+            allToolCalls.push(
+              ...toolCalls.filter((call) => !interruptByToolName.has(call.name))
+            );
             messages.push({
               role: "assistant",
               content: step.text,
@@ -2999,6 +3205,84 @@ ${tryStringify2(args.response)}`
           }
           pending = step;
           save();
+          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 (toolResults.some((result3) => result3.toolCallId === interruptCall.id)) {
+              pending = void 0;
+              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;
+            save();
+            continue;
+          }
           for (const toolCall of toolCalls) {
             if (toolResults.some((result2) => result2.toolCallId === toolCall.id)) {
               await replayToolObservations(
@@ -3208,7 +3492,11 @@ ${tryStringify2(args.response)}`
           ...finalOutput !== void 0 ? { output: finalOutput } : {},
           toolCalls: allToolCalls,
           toolResults: allToolResults,
-          steps
+          steps,
+          ...interruptHistory.length > 0 ? { interruptHistory } : {},
+          ...isLegacyInterruptContracts(interruptConfig) && interruptHistory.length > 0 ? {
+            interruptResponse: interruptHistory.at(-1)?.response
+          } : {}
         };
         traceSpan?.end?.({
           ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
@@ -3219,7 +3507,8 @@ ${tryStringify2(args.response)}`
             textLength: finalText.length,
             toolCallCount: allToolCalls.length,
             toolResultCount: allToolResults.length,
-            toolStepCount: steps.length
+            toolStepCount: steps.length,
+            interruptCount: interruptHistory.length
           },
           telemetry: {
             ...useReasonArgs.telemetry ?? {},
@@ -3247,7 +3536,7 @@ ${tryStringify2(args.response)}`
     var resolveEffectiveResponseFormatType = (args) => args.responseFormat?.type ?? args.model.options?.responseFormat?.type;
     var assertReasoningThoughtsCompatibility = (args) => {
       if (!resolveEffectiveReasoningIncludeThoughts(args)) return;
-      const usesStructuredOutput = Boolean(args.outputSchema) || Boolean(args.interrupt) || Boolean(args.structured) || resolveEffectiveResponseFormatType(args) === "json";
+      const usesStructuredOutput = Boolean(args.outputSchema) || Boolean(args.interrupt) || Boolean(args.interrupts) || Boolean(args.structured) || resolveEffectiveResponseFormatType(args) === "json";
       if (!usesStructuredOutput) return;
       throw new Error(
         "useReason does not support reasoning.includeThoughts with structured output, interrupt mode, or JSON responseFormat. Disable includeThoughts for this call."
@@ -3255,6 +3544,10 @@ ${tryStringify2(args.response)}`
     };
     async function runReason(args) {
       assertReasoningThoughtsCompatibility(args);
+      const interruptConfig = normalizeReasonInterrupts({
+        interrupt: args.interrupt,
+        interrupts: args.interrupts
+      });
       const ctx = getHookContext();
       const abortSignal = (0, import_core62.combineAbortSignals)(
         ctx.node.abortSignal,
@@ -3269,20 +3562,23 @@ ${tryStringify2(args.response)}`
         args.outputSchema,
         args.responseFormat ?? args.model.options?.responseFormat
       );
+      const usesLegacyNoToolInterrupt = Boolean(
+        args.interrupt && !args.interrupts && !args.tools?.length
+      );
       args = {
         ...args,
         abortSignal,
-        ...!args.interrupt && inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {}
+        ...!usesLegacyNoToolInterrupt && inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {}
       };
       const id = typeof args.id === "string" && args.id.length > 0 ? args.id : void 0;
-      const opId = createRuntimeId2();
+      const provisionalOpId = createRuntimeId2();
       const checkpointKey = resolveReasonCheckpointKey({
         ...id ? { id } : {},
         autoIndex: ctx.reasonCallIndex++
       });
-      const existingCompleted = readReasonCompletedCheckpoint(
-        ctx.currentNodeState.byKey[checkpointKey]
-      );
+      const checkpointValue = ctx.currentNodeState.byKey[checkpointKey];
+      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) {
         await replayToolObservations(
           existingCompleted.result.steps?.flatMap(
@@ -3291,9 +3587,7 @@ ${tryStringify2(args.response)}`
         );
         return existingCompleted.result;
       }
-      const existingCheckpoint = readReasonCheckpoint(
-        ctx.currentNodeState.byKey[checkpointKey]
-      );
+      const existingCheckpoint = readReasonCheckpoint(checkpointValue);
       const reasonMeta = typeof id === "string" ? { id, opId } : { opId };
       return withSafeTraceSpan2(
         getReasonTraceAdapter(),
@@ -3312,7 +3606,8 @@ ${tryStringify2(args.response)}`
             ...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),
+            hasInterrupt: Boolean(interruptConfig),
+            interruptContractCount: Object.keys(interruptConfig?.contracts ?? {}).length,
             hasStructured: Boolean(args.structured),
             hasTools: Boolean(args.tools?.length)
           },
@@ -3322,7 +3617,7 @@ ${tryStringify2(args.response)}`
           }
         },
         async (traceSpan) => {
-          if (args.tools?.length) {
+          if ((args.tools?.length || args.interrupts) && !existingCheckpoint) {
             return runReasonToolLoop({
               useReasonArgs: args,
               allowValidatedToolOutput,
@@ -3589,6 +3884,24 @@ ${tryStringify2(args.response)}`
       return useReason(args);
     }
     function useInterrupt(args) {
+      if ("contract" in args) {
+        const contract = defineInterruptContract(args.contract);
+        return awaitInterruptInternal({
+          request: {
+            kind: "custom",
+            request: parseWithSchema(
+              contract.requestSchema,
+              args.request,
+              "useInterrupt contract request"
+            ),
+            schemaId: contract.schemaId,
+            schemaVersion: contract.schemaVersion,
+            ...args.id ? { id: args.id } : {},
+            ...args.meta ? { meta: args.meta } : {}
+          },
+          responseSchema: contract.responseSchema
+        });
+      }
       return awaitInterruptInternal(args);
     }
     function useAbortSignal() {
@@ -3802,6 +4115,12 @@ ${tryStringify2(args.response)}`
       });
       return promise;
     }
+    function reportError(error, options = {}) {
+      try {
+        getReasonTraceAdapter()?.reportError?.(error, options);
+      } catch {
+      }
+    }
     var import_node_crypto6 = require("crypto");
     var import_core8 = require("@kortyx/core");
     var import_errors8 = require("@kortyx/core/errors");
@@ -4888,7 +5207,10 @@ async function orchestrateGraphStream({
         resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
         resumeOutcome: "failed",
         resumeError: (0, import_errors4.serializeFailure)(resumeError).message,
-        failure: (0, import_errors4.serializeFailure)(resumeError)
+        failure: (0, import_errors4.serializeFailure)(resumeError),
+        ...typeof config.telemetryInterruptContract === "string" ? { contract: config.telemetryInterruptContract } : {},
+        ...typeof config.telemetryInterruptSchemaId === "string" ? { schemaId: config.telemetryInterruptSchemaId } : {},
+        ...typeof config.telemetryInterruptSchemaVersion === "string" ? { schemaVersion: config.telemetryInterruptSchemaVersion } : {}
       },
       flush: true
     });
@@ -4994,6 +5316,7 @@ async function orchestrateGraphStream({
     const optionsList = Array.isArray(input.options) ? input.options : [];
     const kind = input.kind || (input.multiple ? "multi-choice" : "choice");
     const isText = kind === "text";
+    const isCustom = kind === "custom";
     const record = {
       token,
       ready: false,
@@ -5004,7 +5327,17 @@ async function orchestrateGraphStream({
       workflow: payload.workflow || currentState.currentWorkflow,
       node: payload.node || "",
       state: { ...currentState, awaitingHumanInput: true },
-      schema: isText ? {
+      schema: isCustom ? {
+        kind: "custom",
+        multiple: false,
+        ...input.question ? { question: input.question } : {},
+        ...typeof input.id === "string" && input.id.length > 0 ? { id: input.id } : {},
+        ...typeof input.contract === "string" && input.contract.length > 0 ? { contract: input.contract } : {},
+        ...Object.hasOwn(input, "request") ? { request: input.request } : {},
+        ...typeof input.schemaId === "string" && input.schemaId.length > 0 ? { schemaId: input.schemaId } : {},
+        ...typeof input.schemaVersion === "string" && input.schemaVersion.length > 0 ? { schemaVersion: input.schemaVersion } : {},
+        ...input.meta && typeof input.meta === "object" ? { meta: input.meta } : {}
+      } : isText ? {
         kind,
         multiple: Boolean(input.multiple),
         ...input.question ? { question: input.question } : {},
@@ -5059,6 +5392,8 @@ async function orchestrateGraphStream({
         kind: record.schema.kind,
         multiple: record.schema.multiple,
         question: record.schema.question,
+        ...record.schema.contract ? { contract: record.schema.contract } : {},
+        ...Object.hasOwn(record.schema, "request") ? { request: record.schema.request } : {},
         ...typeof record.schema.id === "string" && record.schema.id.length > 0 ? { id: record.schema.id } : {},
         ...typeof record.schema.schemaId === "string" && record.schema.schemaId.length > 0 ? { schemaId: record.schema.schemaId } : {},
         ...typeof record.schema.schemaVersion === "string" && record.schema.schemaVersion.length > 0 ? { schemaVersion: record.schema.schemaVersion } : {},
@@ -5070,6 +5405,11 @@ async function orchestrateGraphStream({
         }))
       }
     });
+    const captureRequest = shouldCaptureTelemetryContent(
+      telemetryConfig.captureContent,
+      "output"
+    );
+    const structuredRequest = isRecord3(record.schema.request) ? record.schema.request : void 0;
     emitTelemetryEvent({
       config,
       type: "interrupt.created",
@@ -5085,11 +5425,11 @@ async function orchestrateGraphStream({
         interactionMode: record.schema.kind === "text" ? "freeform" : record.options.length > 0 ? "static-options" : record.schema.schemaId ? "dynamic-picker" : "unknown",
         ...record.schema.schemaId ? { schemaId: record.schema.schemaId } : {},
         ...record.schema.schemaVersion ? { schemaVersion: record.schema.schemaVersion } : {},
-        ...typeof record.schema.question === "string" && shouldCaptureTelemetryContent(telemetryConfig.captureContent, "output") ? { question: record.schema.question } : {},
-        ...shouldCaptureTelemetryContent(
-          telemetryConfig.captureContent,
-          "output"
-        ) ? {
+        ...record.schema.contract ? { contract: record.schema.contract } : {},
+        requestCaptured: Boolean(captureRequest && structuredRequest),
+        ...captureRequest && structuredRequest ? { request: structuredRequest } : {},
+        ...typeof record.schema.question === "string" && captureRequest ? { question: record.schema.question } : {},
+        ...captureRequest ? {
           options: record.options.map((option) => ({
             id: option.id,
             label: option.label,
@@ -5898,6 +6238,7 @@ function parseResumeMeta(msg) {
   const token = typeof raw.token === "string" ? raw.token : "";
   const requestId = typeof raw.requestId === "string" ? raw.requestId : "";
   const cancel = raw.cancel === true;
+  const hasValue = Object.hasOwn(raw, "value");
   let selected = [];
   const rawSelected = raw.selected;
   if (typeof rawSelected === "string") selected = [rawSelected];
@@ -5907,7 +6248,13 @@ function parseResumeMeta(msg) {
   else if (Array.isArray(raw.choices))
     selected = raw.choices.map((c) => isRecord4(c) ? c.id : void 0).filter((id) => typeof id === "string");
   if (!token || !requestId) return null;
-  return { token, requestId, selected, cancel };
+  return {
+    token,
+    requestId,
+    selected,
+    cancel,
+    ...hasValue ? { value: raw.value, hasValue: true } : {}
+  };
 }
 async function tryPrepareResumeStream({
   limits,
@@ -5994,7 +6341,8 @@ async function tryPrepareResumeStream({
         },
         payload: {
           interruptId: pending.requestId,
-          reason: "cancelled_by_client"
+          reason: "cancelled_by_client",
+          ...pending.schema.contract ? { contract: pending.schema.contract } : {}
         },
         flush: true
       });
@@ -6074,7 +6422,7 @@ async function tryPrepareResumeStream({
       resumeUpdate.runtime = resumeStatePatch;
     }
     const hasResumeUpdate = !isLimitPause && Object.keys(resumeUpdate).length > 0;
-    const resumeValue = isLimitPause ? void 0 : meta.selected?.length && pending.schema.kind === "multi-choice" ? meta.selected.map((x) => String(x)) : meta.selected?.length ? String(meta.selected[0]) : void 0;
+    const resumeValue = isLimitPause ? void 0 : meta.hasValue && pending.schema.kind === "custom" ? meta.value : meta.selected?.length && pending.schema.kind === "multi-choice" ? meta.selected.map((x) => String(x)) : meta.selected?.length ? String(meta.selected[0]) : void 0;
     const resumeCheckpointId = typeof pending.graphCheckpointId === "string" && pending.graphCheckpointId.length > 0 ? pending.graphCheckpointId : void 0;
     const resumedGraph = await (0, import_runtime2.createExecutionGraph)(wf, {
       ...telemetryConfig,
@@ -6084,7 +6432,7 @@ async function tryPrepareResumeStream({
       ...hasResumeUpdate ? { resumeUpdate } : {}
     });
     await store.delete(pending.token);
-    const response = responseFromSelection(meta.selected);
+    const response = meta.hasValue ? JSON.stringify(meta.value) : responseFromSelection(meta.selected);
     const telemetry = isRecord4(telemetryConfig.telemetry) ? telemetryConfig.telemetry : {};
     const responseCaptured = Boolean(
       response && shouldCaptureTelemetryContent(telemetry.captureContent, "input")
@@ -6103,6 +6451,10 @@ async function tryPrepareResumeStream({
         resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
         resumeOutcome: "resumed",
         responseCaptured,
+        ...pending.schema.contract ? { contract: pending.schema.contract } : {},
+        ...pending.schema.schemaId ? { schemaId: pending.schema.schemaId } : {},
+        ...pending.schema.schemaVersion ? { schemaVersion: pending.schema.schemaVersion } : {},
+        ...responseCaptured && meta.hasValue ? { responseValue: meta.value } : {},
         ...responseCaptured && response ? { response } : {}
       },
       flush: true
@@ -6124,6 +6476,11 @@ async function tryPrepareResumeStream({
         resume: true,
         telemetryInterruptId: pending.requestId,
         telemetryInterruptNodeId: pending.node,
+        ...pending.schema.contract ? { telemetryInterruptContract: pending.schema.contract } : {},
+        ...pending.schema.schemaId ? { telemetryInterruptSchemaId: pending.schema.schemaId } : {},
+        ...pending.schema.schemaVersion ? {
+          telemetryInterruptSchemaVersion: pending.schema.schemaVersion
+        } : {},
         ...resumeValue !== void 0 ? { resumeValue } : {},
         ...resumeCheckpointId ? { resumeCheckpointId } : {},
         ...hasResumeUpdate ? { resumeUpdate } : {}
@@ -6157,6 +6514,7 @@ var responseSchema = import_zod3.z.discriminatedUnion("type", [
     type: import_zod3.z.literal("select"),
     ids: import_zod3.z.array(import_zod3.z.string().min(1)).min(1)
   }).strict(),
+  import_zod3.z.object({ type: import_zod3.z.literal("value"), value: import_zod3.z.unknown() }).strict(),
   import_zod3.z.object({ type: import_zod3.z.literal("cancel") }).strict()
 ]);
 function resultFromOutcome(outcome, runId, sessionId) {
@@ -6297,7 +6655,13 @@ async function resumeWorkflow(services, args) {
         "Resume handle does not match the root execution and workflow version."
       );
     if (response.type === "cancel") return;
-    if (response.type === "text") {
+    if (response.type === "value") {
+      if (pending.schema.kind !== "custom")
+        throw new ExecutionRequestError(
+          "INVALID_RESPONSE",
+          "Structured values are only valid for custom interrupts."
+        );
+    } else if (response.type === "text") {
       if (pending.schema.kind !== "text")
         throw new ExecutionRequestError(
           "INVALID_RESPONSE",
@@ -6327,6 +6691,7 @@ async function resumeWorkflow(services, args) {
         token: handle.token,
         requestId: handle.requestId,
         selected: response.type === "text" ? [response.text] : response.type === "select" ? response.ids : [],
+        ...response.type === "value" ? { value: response.value, hasValue: true } : {},
         cancel: response.type === "cancel"
       },
       sessionId: handle.sessionId,