@kortyx/hooks 0.34.2 → 0.35.0

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.35.0",
   private: false,
   description: "Lifecycle hooks and extension points for Kortyx.",
   keywords: [
@@ -822,252 +822,17 @@ var emitStructuredData = (args) => {
 var import_node_async_hooks2 = require("async_hooks");
 var import_node_crypto3 = require("crypto");
 var import_core2 = require("@kortyx/core");
-var import_errors3 = require("@kortyx/core/errors");
+var import_errors2 = 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 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 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 {
-      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 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");
-    }
-  };
-  try {
-    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 {
-      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);
+  const content = (0, import_telemetry_contracts.captureDiagnosticContent)(error, project);
   return !content || content.capture.status === "failed" ? null : content.data;
 }
 function errorDiagnostics(error, project) {
@@ -1332,7 +1097,7 @@ async function executeObservedTool(args) {
         return result;
       } catch (error) {
         if (args.abortSignal?.aborted) observation.outcome = "cancelled";
-        else if (!(0, import_errors3.isControlFlowError)(error)) {
+        else if (!(0, import_errors2.isControlFlowError)(error)) {
           const outcome = classification(
             args.tool,
             error,
@@ -1471,11 +1236,11 @@ var import_prompts = require("@kortyx/prompts");
 // src/reason-engine.ts
 var import_node_crypto4 = require("crypto");
 var import_core3 = require("@kortyx/core");
-var import_errors4 = require("@kortyx/core/errors");
+var import_errors3 = require("@kortyx/core/errors");
 function assertModelFinish(result) {
   if (result.finishReason?.unified !== "content-filter") return;
   throw Object.assign(
-    new import_errors4.KortyxError("PROVIDER_REFUSAL", "The provider refused the request.", {
+    new import_errors3.KortyxError("PROVIDER_REFUSAL", "The provider refused the request.", {
       category: "provider",
       retryable: false,
       safeMessage: "The provider refused the request."
@@ -2549,7 +2314,7 @@ function createStructuredOutputStreamer(args, id, opId) {
 }
 
 // src/reason/parsing.ts
-var import_errors5 = require("@kortyx/core/errors");
+var import_errors4 = require("@kortyx/core/errors");
 var tryJsonParse = (value) => {
   try {
     return { ok: true, value: JSON.parse(value) };
@@ -2587,12 +2352,12 @@ var resolveOutputCandidate = (text) => {
   }
   return text;
 };
-var createTruncatedStructuredOutputError = (label, cause) => new import_errors5.ValidationError(
+var createTruncatedStructuredOutputError = (label, cause) => new import_errors4.ValidationError(
   "OUTPUT_TRUNCATED",
   `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`,
   cause
 );
-var createInvalidStructuredOutputError = (label, cause) => new import_errors5.ValidationError(
+var createInvalidStructuredOutputError = (label, cause) => new import_errors4.ValidationError(
   "INVALID_MODEL_JSON",
   `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. Check the output contract or outputSchema and provider structured-output settings.`,
   cause
@@ -2604,7 +2369,7 @@ var parseReasonOutputWithSchema = (args) => {
   try {
     return parseWithSchema(args.schema, candidate, args.label);
   } catch (error) {
-    if (!(error instanceof import_errors5.ValidationError)) throw error;
+    if (!(error instanceof import_errors4.ValidationError)) throw error;
     const failure = args.finishReason?.unified === "length" ? createTruncatedStructuredOutputError(args.label, error) : typeof candidate === "string" && !validJson ? createInvalidStructuredOutputError(args.label, error) : error;
     if (failure && typeof failure === "object")
       Object.assign(failure, {
@@ -2624,7 +2389,7 @@ var parseInterruptFirstPassResult = (args) => {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
         throw createInvalidStructuredOutputError("useReason output");
       }
-      throw new import_errors5.ValidationError(
+      throw new import_errors4.ValidationError(
         "MODEL_OUTPUT_SCHEMA",
         "useReason first pass with interrupt must return a JSON object."
       );
@@ -2633,7 +2398,7 @@ var parseInterruptFirstPassResult = (args) => {
     let interruptRequired = true;
     if (mode === "optional") {
       if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
-        throw new import_errors5.ValidationError(
+        throw new import_errors4.ValidationError(
           "MODEL_OUTPUT_SCHEMA",
           'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
         );
@@ -2646,7 +2411,7 @@ var parseInterruptFirstPassResult = (args) => {
           candidate.interrupt
         ].some((value) => value !== null && value !== void 0);
         if (hasUnexpectedRequest) {
-          throw new import_errors5.ValidationError(
+          throw new import_errors4.ValidationError(
             "MODEL_OUTPUT_SCHEMA",
             'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
           );
@@ -2680,7 +2445,7 @@ var parseInterruptFirstPassResult = (args) => {
           "useReason output"
         );
       } catch (error) {
-        if (!(error instanceof import_errors5.ValidationError)) throw error;
+        if (!(error instanceof import_errors4.ValidationError)) throw error;
         if (args.finishReason?.unified === "length") {
           throw createTruncatedStructuredOutputError("useReason output", error);
         }
@@ -2689,7 +2454,7 @@ var parseInterruptFirstPassResult = (args) => {
     }
     const explicitDraft = typeof candidate.draftText === "string" && candidate.draftText.length > 0 ? candidate.draftText : typeof candidate.text === "string" && candidate.text.length > 0 ? candidate.text : void 0;
     if (!args.outputSchema && !explicitDraft) {
-      throw new import_errors5.ValidationError(
+      throw new import_errors4.ValidationError(
         "MODEL_OUTPUT_SCHEMA",
         "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
       );
@@ -2963,8 +2728,42 @@ var emitReasonStructuredOutput = (args) => {
 
 // src/reason/tools.ts
 var import_core5 = require("@kortyx/core");
-var import_errors6 = require("@kortyx/core/errors");
+var import_errors5 = 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 } : {},
@@ -3169,7 +2968,7 @@ var runReasonToolLoop = async (args) => {
   const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
   const missingReturnCorrections = useReasonArgs.toolExecution?.missingReturnCorrections ?? 0;
   if (!Number.isSafeInteger(missingReturnCorrections) || missingReturnCorrections < 0)
-    throw new import_errors6.KortyxError(
+    throw new import_errors5.KortyxError(
       "INVALID_REASON_CORRECTION_POLICY",
       "Invalid missing return correction budget.",
       {
@@ -3230,7 +3029,7 @@ var runReasonToolLoop = async (args) => {
   let outputContractCorrections = checkpoint?.outputContractCorrections ?? 0;
   const correctionExhausted = () => {
     const message = `useReason could not complete output-contract correction within toolExecution.maxSteps (${maxSteps}). Select exactly one terminal return contract; multiple emit contracts are allowed. Increase maxSteps to allow correction and output generation.`;
-    return new import_errors6.KortyxError(
+    return new import_errors5.KortyxError(
       "REASON_OUTPUT_CONTRACT_CORRECTION_EXHAUSTED",
       message,
       {
@@ -3327,7 +3126,7 @@ var runReasonToolLoop = async (args) => {
       aggregatedWarnings = mergeWarnings(aggregatedWarnings, step.warnings);
       const toolCalls = step.toolCalls ?? [];
       if (missingReturnAttempts > 0 && toolCalls.some((call) => !outputByToolName.has(call.name)))
-        throw new import_errors6.KortyxError(
+        throw new import_errors5.KortyxError(
           "REASON_OUTPUT_CORRECTION_TOOL_DISALLOWED",
           "A return correction requested a non-output tool.",
           {
@@ -3370,7 +3169,7 @@ var runReasonToolLoop = async (args) => {
             save();
             continue;
           }
-          throw new import_errors6.KortyxError(
+          throw new import_errors5.KortyxError(
             "REASON_TERMINAL_OUTPUT_MISSING",
             "useReason outputs.return requires one terminal output contract call.",
             {
@@ -3504,7 +3303,7 @@ var runReasonToolLoop = async (args) => {
               );
             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, {
+              throw new import_errors5.ProviderRequestError(message, {
                 code: "REASON_OUTPUT_BUDGET_EXHAUSTED",
                 operation: "useReason",
                 safeMessage: message,
@@ -3691,11 +3490,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_errors5.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,
@@ -3885,12 +3708,12 @@ var runReasonToolLoop = async (args) => {
           }
         } catch (error) {
           (0, import_core5.throwIfExecutionAborted)(abortSignal);
-          if ((0, import_errors6.isControlFlowError)(error)) throw error;
+          if ((0, import_errors5.isControlFlowError)(error)) throw error;
           const result2 = {
             toolCallId: toolCall.id,
             name: tool.name,
-            content: (0, import_errors6.serializeFailure)(error).message,
-            failure: (0, import_errors6.serializeFailure)(error),
+            content: (0, import_errors5.serializeFailure)(error).message,
+            failure: (0, import_errors5.serializeFailure)(error),
             isError: true
           };
           toolResults.push(result2);
@@ -4493,7 +4316,7 @@ function useWorkflowState(key, ...rest) {
 
 // src/parallel.ts
 var import_core7 = require("@kortyx/core");
-var import_errors7 = require("@kortyx/core/errors");
+var import_errors6 = require("@kortyx/core/errors");
 var ParallelChildWaiting = class extends Error {
   name = "ParallelChildWaiting";
 };
@@ -4507,14 +4330,14 @@ var ParallelError = class extends AggregateError {
     );
     this.results = results;
     this.name = "ParallelError";
-    this.failure = (0, import_errors7.serializeFailure)({
+    this.failure = (0, import_errors6.serializeFailure)({
       version: 1,
       code: this.code,
       category: "workflow",
       message: this.message,
       retryable: null,
       results: results.map(
-        (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors7.serializeFailure)(result.reason) }
+        (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors6.serializeFailure)(result.reason) }
       )
     });
   }
@@ -4522,7 +4345,7 @@ var ParallelError = class extends AggregateError {
   code = "PARALLEL_FAILED";
   failure;
   toJSON() {
-    return (0, import_errors7.serializeFailure)(this);
+    return (0, import_errors6.serializeFailure)(this);
   }
 };
 function registerWorkflowTask(id) {
@@ -4635,10 +4458,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(
@@ -4703,11 +4526,11 @@ async function usePrompt(reference, options) {
 // src/workflow.ts
 var import_node_crypto6 = require("crypto");
 var import_core8 = require("@kortyx/core");
-var import_errors8 = require("@kortyx/core/errors");
-var WorkflowCallError = class extends import_errors8.KortyxError {
+var import_errors7 = require("@kortyx/core/errors");
+var WorkflowCallError = class extends import_errors7.KortyxError {
   constructor(workflow, message, cause, failure) {
-    const detail = (0, import_errors8.serializeFailure)(
-      failure ?? cause ?? new import_errors8.WorkflowContractError(message)
+    const detail = (0, import_errors7.serializeFailure)(
+      failure ?? cause ?? new import_errors7.WorkflowContractError(message)
     );
     super(detail.code, `Workflow '${workflow}': ${message}`, {
       ...detail,
@@ -4728,12 +4551,12 @@ function workflowCallFingerprint(value) {
     if (v === null || typeof v === "string" || typeof v === "boolean") return v;
     if (typeof v === "number" && Number.isFinite(v)) return v;
     if (typeof v !== "object" || !v || seen.has(v)) {
-      throw new import_errors8.WorkflowContractError(
+      throw new import_errors7.WorkflowContractError(
         "Workflow input and output must be JSON serializable."
       );
     }
     if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype) {
-      throw new import_errors8.WorkflowContractError(
+      throw new import_errors7.WorkflowContractError(
         "Workflow input and output must contain plain JSON objects."
       );
     }
@@ -4754,7 +4577,7 @@ function createWorkflowHooks(workflows) {
     useWorkflow: (args) => {
       const workflow = workflows[args.workflow];
       if (!workflow || workflow.id !== args.workflow)
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors7.WorkflowContractError(
           "Workflow registry keys must match definition ids."
         );
       return useWorkflow({ ...args, workflow });
@@ -4780,23 +4603,23 @@ async function runWorkflowCall(args, task) {
   (0, import_core8.throwIfExecutionAborted)(ctx.node.abortSignal);
   const service = ctx.node.callWorkflow;
   if (!service)
-    throw new import_errors8.WorkflowContractError(
+    throw new import_errors7.WorkflowContractError(
       "useWorkflow requires an agent workflow registry."
     );
   if (!args.id.trim())
-    throw new import_errors8.WorkflowContractError(
+    throw new import_errors7.WorkflowContractError(
       "useWorkflow requires a stable, nonempty id."
     );
   if (ctx.workflowCallActive && !task.group)
-    throw new import_errors8.WorkflowContractError(
+    throw new import_errors7.WorkflowContractError(
       "Concurrent workflow calls require parallel([...]); otherwise await each call."
     );
   if (ctx.workflowCallIds.has(args.id))
-    throw new import_errors8.WorkflowContractError(
+    throw new import_errors7.WorkflowContractError(
       `Duplicate workflow call id '${args.id}' in one node activation.`
     );
   if (ctx.workflowCallIds.size >= 64)
-    throw new import_errors8.WorkflowContractError(
+    throw new import_errors7.WorkflowContractError(
       "A node may call at most 64 child workflows per activation."
     );
   ctx.workflowCallIds.add(args.id);
@@ -4809,26 +4632,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 +4659,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 +4669,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_errors7.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_errors7.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 +4720,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 +4731,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_errors7.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 +4781,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))
     };