@kortyx/hooks 0.25.3 → 0.26.0

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   useReason: () => useReason2,
   useRuntimeContext: () => useRuntimeContext,
   useStructuredData: () => useStructuredData,
+  useTool: () => useTool,
   useWorkflow: () => useWorkflow,
   useWorkflowState: () => useWorkflowState,
   workflowCallFingerprint: () => workflowCallFingerprint
@@ -99,6 +100,7 @@ var createInternalContext = (ctx) => {
     workflowContextClosed: false,
     nodeStateIndex: 0,
     reasonCallIndex: 0,
+    toolCallIndex: 0,
     currentNodeState,
     workflowState: cloneWorkflowState(hookRuntimeState.workflowState),
     tokenUsage: cloneTokenUsage(ctx.state.runtime?.tokenUsage),
@@ -189,6 +191,12 @@ async function runWithHookContext(ctx, fn) {
       }
     });
     cleanupCompletedReasonCheckpoints(internal);
+    for (const key of Object.keys(internal.currentNodeState.byKey)) {
+      if (key.startsWith("__useTool:")) {
+        delete internal.currentNodeState.byKey[key];
+        internal.stateDirty = true;
+      }
+    }
     for (const key of Object.keys(internal.currentNodeState.byKey)) {
       if (key.startsWith("__useWorkflow:") || key.startsWith("__parallel:") || key === "__useWorkflowActivation") {
         internal.currentNodeState.byKey[key] = null;
@@ -341,7 +349,87 @@ var awaitInterruptInternal = (args) => {
 };
 
 // src/reason/use-reason.ts
-var import_core5 = require("@kortyx/core");
+var import_core6 = require("@kortyx/core");
+
+// src/safe-tracing.ts
+function safeSpan(span) {
+  const guard = (fn) => (...args) => {
+    try {
+      fn?.(...args);
+    } catch {
+    }
+  };
+  let ended = false;
+  const finish = (fn) => (...args) => {
+    if (ended) return;
+    ended = true;
+    guard(fn)(...args);
+  };
+  return {
+    addEvent: guard(
+      (name, attributes) => span?.addEvent?.(name, attributes)
+    ),
+    setAttributes: guard(
+      (attributes) => span?.setAttributes?.(attributes)
+    ),
+    end: finish((args) => span?.end?.(args)),
+    fail: finish((error, args) => {
+      if (span?.fail) span.fail(error, args);
+      else span?.end?.(args);
+    })
+  };
+}
+function safeStartSpan(adapter, args) {
+  try {
+    return safeSpan(adapter?.startSpan?.(args));
+  } catch {
+    return safeSpan(void 0);
+  }
+}
+async function withSafeTraceSpan(adapter, args, fn) {
+  let execution;
+  const invoke = (span) => {
+    execution ??= Promise.resolve().then(async () => {
+      const observed = safeSpan(span);
+      try {
+        const result = await fn(observed);
+        observed.end?.();
+        return result;
+      } catch (error) {
+        observed.fail?.(error);
+        throw error;
+      }
+    });
+    return execution;
+  };
+  let activeScope;
+  try {
+    activeScope = adapter?.withSpan?.bind(adapter);
+  } catch {
+  }
+  if (activeScope) {
+    let started;
+    const invoked = new Promise((resolve) => {
+      started = resolve;
+    });
+    const observe = async () => {
+      try {
+        await activeScope(args, (span) => {
+          const result = invoke(span);
+          started?.();
+          return result;
+        });
+      } catch {
+      }
+    };
+    const observation = observe();
+    if (!execution) await Promise.race([invoked, observation]);
+  } else {
+    await invoke(safeStartSpan(adapter, args)).catch(() => {
+    });
+  }
+  return execution ?? invoke(safeSpan(void 0));
+}
 
 // src/structured.ts
 var import_node_crypto = require("crypto");
@@ -435,18 +523,392 @@ var emitStructuredData = (args) => {
 var shouldEmitStructured = (cfg) => Boolean(cfg);
 var shouldStreamStructured = (cfg) => Boolean(cfg) && (cfg?.stream ?? true);
 
-// src/reason/engine.ts
+// src/tool.ts
+var import_node_async_hooks2 = require("async_hooks");
 var import_node_crypto3 = require("crypto");
-var import_core3 = require("@kortyx/core");
-
-// src/reason-engine.ts
-var import_node_crypto2 = require("crypto");
 var import_core2 = require("@kortyx/core");
+var import_errors3 = require("@kortyx/core/errors");
+
+// src/error-diagnostics.ts
 var import_errors2 = require("@kortyx/core/errors");
+function errorDiagnostics(error, project) {
+  try {
+    const name = (0, import_errors2.errorProperty)(error, "name") ?? (error instanceof Error ? error.name : void 0);
+    const message = (0, import_errors2.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) } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+
+// src/workflow-telemetry.ts
+var import_node_crypto2 = require("crypto");
+function emitWorkflowCall(telemetry, type, payload) {
+  const base = telemetry?.correlation;
+  if (!telemetry?.reporter || !telemetry.environment || !telemetry.service || !base?.runId || !base.workflowId)
+    return;
+  try {
+    const active = telemetry.trace?.getActiveContext?.();
+    void Promise.resolve(
+      telemetry.reporter.emit([
+        {
+          schemaVersion: 1,
+          eventId: (0, import_node_crypto2.randomUUID)(),
+          occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+          environment: telemetry.environment,
+          service: telemetry.service,
+          correlation: {
+            ...base,
+            runId: base.runId,
+            workflowId: base.workflowId,
+            ...active
+          },
+          type,
+          payload
+        }
+      ])
+    ).catch(() => {
+    });
+  } catch {
+  }
+}
+function workflowCallContent(telemetry, side, value) {
+  const policy = telemetry?.captureContent;
+  if (!(policy === true || policy && typeof policy === "object" && policy[side]))
+    return {};
+  const serialized = JSON.stringify(value);
+  return serialized && Buffer.byteLength(serialized, "utf8") <= 16384 ? { [side]: JSON.parse(serialized) } : { [`${side}Omitted`]: "Content exceeds 16 KiB" };
+}
+
+// src/tool.ts
+var tools = new import_node_async_hooks2.AsyncLocalStorage();
+function classification(tool, value, thrown, policy = tool.outcomes) {
+  const fallback = {
+    outcome: thrown ? "fault" : "success"
+  };
+  try {
+    if (value && typeof value === "object" && "isError" in value && value.isError === true)
+      fallback.outcome = "fault";
+    const result = thrown ? policy?.classifyError?.(value) : policy?.classifyResult?.(value);
+    if (!result || !["success", "denied", "fault"].includes(result.outcome))
+      return fallback;
+    if (result.outcome !== "denied")
+      return thrown || fallback.outcome === "fault" ? fallback : { outcome: result.outcome };
+    const code = result.code;
+    return {
+      outcome: "denied",
+      code: typeof code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(code) && policy?.denialCodes?.includes(code) ? code : "DENIED"
+    };
+  } catch {
+    return fallback;
+  }
+}
+async function closeOwnedTools(owned) {
+  const closers = /* @__PURE__ */ new Map();
+  for (const tool of owned) {
+    if (tool.closeAfterUse !== false && tool.close && !closers.has(tool.close))
+      closers.set(tool.close, tool);
+  }
+  await Promise.all(
+    [...closers].map(async ([close, tool]) => {
+      try {
+        await close.call(tool);
+      } catch {
+        const ctx = getHookContext();
+        try {
+          ctx.reasonTrace?.startSpan({
+            name: "kortyx.tool.cleanup",
+            attributes: { cleanupFailed: true }
+          })?.end?.();
+        } catch {
+        }
+      }
+    })
+  );
+}
+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;
+    Object.assign(
+      observation,
+      errorDiagnostics(policy?.error ? error : reported, policy?.error)
+    );
+  } catch {
+  }
+}
+function ownership() {
+  const ctx = getHookContext();
+  const correlation = ctx.node.workflowCallTelemetry?.correlation;
+  return {
+    workflowId: ctx.node.graph.name,
+    nodeId: ctx.node.graph.node,
+    ...correlation?.workflowRevisionId ? { workflowRevisionId: correlation.workflowRevisionId } : {},
+    ...correlation?.parentInvocationId ? { parentInvocationId: correlation.parentInvocationId } : {},
+    ...correlation?.runId ? { runId: correlation.runId } : {},
+    ...correlation?.invocationId ? { invocationId: correlation.invocationId } : {},
+    ...correlation?.branchId ? { branchId: correlation.branchId } : {}
+  };
+}
+function rememberToolObservation(observation) {
+  const ctx = getHookContext();
+  const existing = ctx.workflowState.__kortyxToolObservations;
+  const observations = Array.isArray(existing) ? existing : [];
+  if (!observations.some((item) => item.attemptId === observation.attemptId))
+    observations.push({ ...observation });
+  ctx.workflowState.__kortyxToolObservations = observations;
+  ctx.stateDirty = true;
+}
+function toolTrace(observation) {
+  const ctx = getHookContext();
+  const adapter = ctx.reasonTrace ?? ctx.node.workflowCallTelemetry?.trace;
+  if (adapter) return adapter;
+  const telemetry = ctx.node.workflowCallTelemetry;
+  if (!telemetry?.reporter) return void 0;
+  const correlation = { ...telemetry.correlation, ...observation };
+  const spanId = (0, import_node_crypto3.randomUUID)();
+  const emit = (type, payload) => emitWorkflowCall(
+    {
+      ...telemetry,
+      correlation,
+      trace: {
+        startSpan: () => void 0,
+        getActiveContext: () => ({
+          traceId: correlation.runId ?? spanId,
+          spanId
+        })
+      }
+    },
+    type,
+    payload
+  );
+  return {
+    startSpan: ({ attributes = {} }) => {
+      if (attributes.executed === true) emit("tool.started", attributes);
+      let ended = false;
+      return {
+        end: (args) => {
+          if (ended) return;
+          ended = true;
+          const payload = { ...attributes, ...args?.attributes };
+          const type = payload.observationKind === "reused" ? "tool.reused" : payload.observationKind === "waiting" ? "tool.waiting" : payload.suspended ? "tool.suspended" : payload.outcome === "denied" ? "tool.denied" : payload.outcome === "fault" ? "tool.failed" : payload.outcome === "cancelled" ? "tool.cancelled" : "tool.completed";
+          emit(type, payload);
+        }
+      };
+    }
+  };
+}
+async function executeObservedTool(args) {
+  const ctx = getHookContext();
+  const observation = {
+    version: 1,
+    name: args.tool.name,
+    toolCallId: args.toolCallId,
+    attemptId: (0, import_node_crypto3.randomUUID)(),
+    callingMode: args.callingMode,
+    executed: false,
+    ...ownership()
+  };
+  const scope = {
+    tool: args.tool,
+    input: args.input,
+    signal: args.abortSignal,
+    mode: args.callingMode,
+    providerToolCallId: args.providerToolCallId ?? args.toolCallId,
+    adopted: false
+  };
+  try {
+    (0, import_core2.throwIfExecutionAborted)(args.abortSignal);
+  } catch (error) {
+    observation.outcome = "cancelled";
+    await observeToolFact(observation);
+    args.onObservation?.(observation);
+    throw error;
+  }
+  ctx.node.consumeExecution?.("maxToolCalls");
+  observation.executed = true;
+  const started = performance.now();
+  return withSafeTraceSpan(
+    toolTrace(observation),
+    {
+      name: "kortyx.tool",
+      attributes: { ...observation, nodeId: ctx.node.graph.node }
+    },
+    async (span) => tools.run(scope, async () => {
+      try {
+        const result = await args.tool.execute(args.input, {
+          toolCallId: args.providerToolCallId ?? args.toolCallId,
+          ...args.abortSignal ? { abortSignal: args.abortSignal } : {}
+        });
+        (0, import_core2.throwIfExecutionAborted)(args.abortSignal);
+        const outcome = classification(
+          args.tool,
+          result,
+          false,
+          scope.classify ?? args.tool.outcomes
+        );
+        observation.outcome = outcome.outcome;
+        if (outcome.code) observation.denialCode = outcome.code;
+        if (observation.outcome === "fault") {
+          captureToolError(
+            observation,
+            result,
+            scope.telemetry ?? args.tool.telemetry,
+            true
+          );
+        }
+        return result;
+      } catch (error) {
+        if (args.abortSignal?.aborted) observation.outcome = "cancelled";
+        else if (!(0, import_errors3.isControlFlowError)(error)) {
+          const outcome = classification(
+            args.tool,
+            error,
+            true,
+            scope.classify ?? args.tool.outcomes
+          );
+          observation.outcome = outcome.outcome;
+          if (outcome.code) observation.denialCode = outcome.code;
+          if (observation.outcome === "fault")
+            captureToolError(
+              observation,
+              error,
+              scope.telemetry ?? args.tool.telemetry
+            );
+        }
+        throw error;
+      } finally {
+        observation.durationMs = Math.max(0, performance.now() - started);
+        span.end?.({
+          attributes: {
+            ...observation,
+            ...observation.outcome ? {} : { suspended: true }
+          }
+        });
+        rememberToolObservation(observation);
+        args.onObservation?.({ ...observation });
+      }
+    })
+  );
+}
+async function observeToolFact(observation, kind, preserveOwner = false) {
+  const ctx = getHookContext();
+  if (!preserveOwner) Object.assign(observation, ownership());
+  if (observation.outcome && kind !== "reused")
+    rememberToolObservation(observation);
+  await withSafeTraceSpan(
+    toolTrace(observation),
+    {
+      name: "kortyx.tool",
+      attributes: {
+        ...observation,
+        executed: false,
+        ...kind ? { observationKind: kind } : {},
+        nodeId: observation.nodeId ?? ctx.node.graph.node
+      }
+    },
+    async (span) => {
+      span.end?.({
+        attributes: {
+          ...observation,
+          executed: false,
+          ...kind ? { observationKind: kind } : {}
+        }
+      });
+    }
+  );
+}
+async function useTool(args) {
+  const ctx = getHookContext();
+  const scope = tools.getStore();
+  if (scope?.mode === "model" && !scope.adopted && scope.tool.name === args.tool.name && scope.input === args.input) {
+    scope.adopted = true;
+    scope.classify = args.tool.outcomes ?? scope.classify;
+    scope.telemetry = args.tool.telemetry ?? scope.telemetry;
+    return tools.run(
+      { ...scope, mode: "direct" },
+      () => args.tool.execute(args.input, {
+        toolCallId: scope.providerToolCallId,
+        ...scope.signal ? { abortSignal: scope.signal } : {}
+      })
+    );
+  }
+  const index = ctx.toolCallIndex++;
+  const key = `__useTool:${args.id ?? `auto:${index}`}`;
+  let id = ctx.currentNodeState.byKey[key];
+  if (typeof id !== "string") {
+    id = (0, import_node_crypto3.randomUUID)();
+    ctx.currentNodeState.byKey[key] = id;
+    ctx.stateDirty = true;
+  }
+  try {
+    return await executeObservedTool({
+      tool: args.tool,
+      input: args.input,
+      toolCallId: String(id),
+      callingMode: "direct",
+      abortSignal: (0, import_core2.combineAbortSignals)(ctx.node.abortSignal, args.abortSignal)
+    });
+  } finally {
+    await closeOwnedTools([args.tool]);
+  }
+}
+async function replayToolObservations(observations, child = false) {
+  for (const original of observations) {
+    const source = original.source ?? {
+      ...ownershipFrom(original),
+      toolCallId: original.toolCallId,
+      attemptId: original.attemptId
+    };
+    await observeToolFact(
+      {
+        ...original,
+        ...ownership(),
+        ...child ? {
+          workflowId: original.workflowId,
+          nodeId: original.nodeId,
+          workflowRevisionId: original.workflowRevisionId,
+          invocationId: original.invocationId,
+          parentInvocationId: original.parentInvocationId
+        } : {},
+        attemptId: (0, import_node_crypto3.randomUUID)(),
+        executed: false,
+        source,
+        durationMs: void 0
+      },
+      "reused",
+      child
+    );
+  }
+}
+var ownershipFrom = (observation) => ({
+  runId: observation.runId,
+  invocationId: observation.invocationId,
+  branchId: observation.branchId
+});
+
+// src/reason/engine.ts
+var import_node_crypto5 = require("crypto");
+var import_core4 = require("@kortyx/core");
+
+// src/reason-engine.ts
+var import_node_crypto4 = require("crypto");
+var import_core3 = require("@kortyx/core");
+var import_errors4 = require("@kortyx/core/errors");
 function assertModelFinish(result) {
   if (result.finishReason?.unified !== "content-filter") return;
   throw Object.assign(
-    new import_errors2.KortyxError("PROVIDER_REFUSAL", "The provider refused the request.", {
+    new import_errors4.KortyxError("PROVIDER_REFUSAL", "The provider refused the request.", {
       category: "provider",
       retryable: false,
       safeMessage: "The provider refused the request."
@@ -460,7 +922,7 @@ function assertModelFinish(result) {
 var toError = (value) => value instanceof Error ? value : new Error(String(value));
 var createRuntimeId = () => {
   try {
-    return (0, import_node_crypto2.randomUUID)();
+    return (0, import_node_crypto4.randomUUID)();
   } catch {
     return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   }
@@ -495,8 +957,8 @@ async function runReasonEngine(args) {
     args.model.options?.providerOptions,
     args.providerOptions
   );
-  const tools = args.tools ?? args.model.options?.tools;
-  (0, import_core2.throwIfExecutionAborted)(abortSignal);
+  const tools2 = args.tools ?? args.model.options?.tools;
+  (0, import_core3.throwIfExecutionAborted)(abortSignal);
   const model = args.model.provider.getModel(args.model.modelId, {
     ...temperature !== void 0 ? { temperature } : {},
     streaming: stream,
@@ -505,10 +967,10 @@ async function runReasonEngine(args) {
     ...abortSignal !== void 0 ? { abortSignal } : {},
     ...reasoning !== void 0 ? { reasoning } : {},
     ...responseFormat !== void 0 ? { responseFormat } : {},
-    ...tools !== void 0 ? { tools } : {},
+    ...tools2 !== void 0 ? { tools: tools2 } : {},
     ...providerOptions !== void 0 ? { providerOptions } : {}
   });
-  if (tools?.length && !model.supportsToolStreaming) stream = false;
+  if (tools2?.length && !model.supportsToolStreaming) stream = false;
   const messages = args.messages !== void 0 ? args.messages : [
     ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
     { role: "user", content: String(args.input ?? "") }
@@ -520,7 +982,7 @@ async function runReasonEngine(args) {
     opId,
     segmentId
   };
-  const traceSpan = args.reasonTrace?.startSpan({
+  const traceSpan = safeStartSpan(args.reasonTrace, {
     name: "runReasonEngine",
     attributes: {
       ...commonMeta,
@@ -600,7 +1062,7 @@ async function runReasonEngine(args) {
       }
       const response2 = await model.stream(messages);
       for await (const chunk of response2) {
-        (0, import_core2.throwIfExecutionAborted)(abortSignal);
+        (0, import_core3.throwIfExecutionAborted)(abortSignal);
         switch (chunk.type) {
           case "text-delta": {
             if (chunk.delta.length === 0) break;
@@ -666,7 +1128,7 @@ async function runReasonEngine(args) {
           }
         }
       }
-      (0, import_core2.throwIfExecutionAborted)(abortSignal);
+      (0, import_core3.throwIfExecutionAborted)(abortSignal);
       assertModelFinish({ finishReason, usage });
       if (emit) {
         emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
@@ -683,12 +1145,12 @@ async function runReasonEngine(args) {
         ...providerMetadata !== void 0 ? { providerMetadata } : {},
         ...warnings !== void 0 ? { warnings } : {}
       };
-      (0, import_core2.throwIfExecutionAborted)(abortSignal);
+      (0, import_core3.throwIfExecutionAborted)(abortSignal);
       endTrace(traceSpan, result2);
       return result2;
     }
     const response = await model.invoke(messages);
-    (0, import_core2.throwIfExecutionAborted)(abortSignal);
+    (0, import_core3.throwIfExecutionAborted)(abortSignal);
     assertModelFinish(response);
     if (response.content) args.onTextChunk?.(response.content);
     if (emit) {
@@ -718,7 +1180,7 @@ async function runReasonEngine(args) {
     endTrace(traceSpan, result);
     return result;
   } catch (error) {
-    const failure = abortSignal?.aborted ? (0, import_core2.createExecutionCancelledError)() : error;
+    const failure = abortSignal?.aborted ? (0, import_core3.createExecutionCancelledError)() : error;
     failTrace(traceSpan, failure);
     throw failure;
   }
@@ -727,19 +1189,19 @@ async function runReasonEngine(args) {
 // src/reason/engine.ts
 var createRuntimeId2 = () => {
   try {
-    return (0, import_node_crypto3.randomUUID)();
+    return (0, import_node_crypto5.randomUUID)();
   } catch {
     return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   }
 };
 async function reasonEngine(args, meta, inputOverride) {
   const ctx = getHookContext();
-  const abortSignal = (0, import_core3.combineAbortSignals)(
+  const abortSignal = (0, import_core4.combineAbortSignals)(
     ctx.node.abortSignal,
     args.abortSignal,
     args.model.options?.abortSignal
   );
-  (0, import_core3.throwIfExecutionAborted)(abortSignal);
+  (0, import_core4.throwIfExecutionAborted)(abortSignal);
   ctx.node.consumeExecution?.("maxModelPasses");
   try {
     return await runReasonEngine({
@@ -1489,7 +1951,7 @@ function createStructuredOutputStreamer(args, id, opId) {
 }
 
 // src/reason/parsing.ts
-var import_errors3 = require("@kortyx/core/errors");
+var import_errors5 = require("@kortyx/core/errors");
 var tryJsonParse = (value) => {
   try {
     return { ok: true, value: JSON.parse(value) };
@@ -1527,12 +1989,12 @@ var resolveOutputCandidate = (text) => {
   }
   return text;
 };
-var createTruncatedStructuredOutputError = (label, cause) => new import_errors3.ValidationError(
+var createTruncatedStructuredOutputError = (label, cause) => new import_errors5.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_errors3.ValidationError(
+var createInvalidStructuredOutputError = (label, cause) => new import_errors5.ValidationError(
   "INVALID_MODEL_JSON",
   `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. Check outputSchema and provider structured-output settings.`,
   cause
@@ -1544,7 +2006,7 @@ var parseReasonOutputWithSchema = (args) => {
   try {
     return parseWithSchema(args.schema, candidate, args.label);
   } catch (error) {
-    if (!(error instanceof import_errors3.ValidationError)) throw error;
+    if (!(error instanceof import_errors5.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, {
@@ -1564,7 +2026,7 @@ var parseInterruptFirstPassResult = (args) => {
       if (typeof candidate === "string" && candidate.trim().length > 0) {
         throw createInvalidStructuredOutputError("useReason output");
       }
-      throw new import_errors3.ValidationError(
+      throw new import_errors5.ValidationError(
         "MODEL_OUTPUT_SCHEMA",
         "useReason first pass with interrupt must return a JSON object."
       );
@@ -1573,7 +2035,7 @@ var parseInterruptFirstPassResult = (args) => {
     let interruptRequired = true;
     if (mode === "optional") {
       if (candidate.decision !== "continue" && candidate.decision !== "interrupt") {
-        throw new import_errors3.ValidationError(
+        throw new import_errors5.ValidationError(
           "MODEL_OUTPUT_SCHEMA",
           'useReason optional interrupt first pass must include decision "continue" or "interrupt".'
         );
@@ -1586,7 +2048,7 @@ var parseInterruptFirstPassResult = (args) => {
           candidate.interrupt
         ].some((value) => value !== null && value !== void 0);
         if (hasUnexpectedRequest) {
-          throw new import_errors3.ValidationError(
+          throw new import_errors5.ValidationError(
             "MODEL_OUTPUT_SCHEMA",
             'useReason optional interrupt first pass with decision "continue" must not include an interrupt request.'
           );
@@ -1620,7 +2082,7 @@ var parseInterruptFirstPassResult = (args) => {
           "useReason output"
         );
       } catch (error) {
-        if (!(error instanceof import_errors3.ValidationError)) throw error;
+        if (!(error instanceof import_errors5.ValidationError)) throw error;
         if (args.finishReason?.unified === "length") {
           throw createTruncatedStructuredOutputError("useReason output", error);
         }
@@ -1629,7 +2091,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_errors3.ValidationError(
+      throw new import_errors5.ValidationError(
         "MODEL_OUTPUT_SCHEMA",
         "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
       );
@@ -1819,6 +2281,7 @@ var mergeUsage = (left, right) => {
   const reasoning = sum(left.reasoning, right.reasoning);
   const cacheRead = sum(left.cacheRead, right.cacheRead);
   const cacheWrite = sum(left.cacheWrite, right.cacheWrite);
+  const cacheWrite1h = sum(left.cacheWrite1h, right.cacheWrite1h);
   const merged = {
     ...right.outputIncludesReasoning !== void 0 ? { outputIncludesReasoning: right.outputIncludesReasoning } : {},
     ...right.inputIncludesCacheWrite !== void 0 ? { inputIncludesCacheWrite: right.inputIncludesCacheWrite } : {},
@@ -1830,6 +2293,7 @@ var mergeUsage = (left, right) => {
   if (reasoning !== void 0) merged.reasoning = reasoning;
   if (cacheRead !== void 0) merged.cacheRead = cacheRead;
   if (cacheWrite !== void 0) merged.cacheWrite = cacheWrite;
+  if (cacheWrite1h !== void 0) merged.cacheWrite1h = cacheWrite1h;
   if (raw) merged.raw = raw;
   return merged;
 };
@@ -1868,9 +2332,9 @@ var emitReasonStructuredOutput = (args) => {
 };
 
 // src/reason/tools.ts
-var import_core4 = require("@kortyx/core");
-var import_errors4 = require("@kortyx/core/errors");
-var toToolDefinitions = (tools) => tools.map((tool) => ({
+var import_core5 = require("@kortyx/core");
+var import_errors6 = require("@kortyx/core/errors");
+var toToolDefinitions = (tools2) => tools2.map((tool) => ({
   name: tool.name,
   ...tool.title ? { title: tool.title } : {},
   ...tool.description ? { description: tool.description } : {},
@@ -1887,12 +2351,13 @@ var resolveToolExecutionBoolean = (value, toolName, fallback) => {
   return fallback;
 };
 var normalizeToolResult = (toolCall, value) => {
-  if (value && typeof value === "object" && !Array.isArray(value) && "toolCallId" in value && "name" in value && "content" in value) {
-    return value;
+  if (value && typeof value === "object" && !Array.isArray(value) && "toolCallId" in value && "name" in value && "content" in value && typeof value.content === "string") {
+    const result = value;
+    return { ...result, toolCallId: toolCall.id, name: toolCall.name };
   }
   let content;
   try {
-    content = typeof value === "string" ? value : JSON.stringify(value);
+    content = typeof value === "string" ? value : JSON.stringify(value) ?? String(value);
   } catch {
     content = String(value);
   }
@@ -1903,28 +2368,6 @@ var normalizeToolResult = (toolCall, value) => {
     ...value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value) ? { structuredContent: value } : {}
   };
 };
-var closeOwnedTools = async (tools, preserveFailure = false, traceSpan) => {
-  const closeFns = /* @__PURE__ */ new Set();
-  for (const tool of tools) {
-    if (tool.closeAfterUse === false || !tool.close) continue;
-    closeFns.add(tool.close);
-  }
-  try {
-    await Promise.all(
-      [...closeFns].map(async (close) => {
-        await close();
-      })
-    );
-  } catch (error) {
-    if (!preserveFailure) throw error;
-    try {
-      traceSpan?.addEvent?.("useReason.cleanup.failed", {
-        failure: (0, import_errors4.serializeFailure)(error)
-      });
-    } catch {
-    }
-  }
-};
 var createInitialMessages = (args) => [
   ...typeof args.system === "string" && args.system.length > 0 ? [{ role: "system", content: args.system }] : [],
   { role: "user", content: String(args.input ?? "") }
@@ -1932,7 +2375,7 @@ var createInitialMessages = (args) => [
 var runReasonToolLoop = async (args) => {
   const { useReasonArgs, id, traceSpan, checkpointKey } = args;
   const ctx = getHookContext();
-  const abortSignal = (0, import_core4.combineAbortSignals)(
+  const abortSignal = (0, import_core5.combineAbortSignals)(
     ctx.node.abortSignal,
     useReasonArgs.abortSignal,
     useReasonArgs.model.options?.abortSignal
@@ -1940,43 +2383,32 @@ var runReasonToolLoop = async (args) => {
   const saved = ctx.currentNodeState.byKey[checkpointKey];
   const checkpoint = saved?.status === "tool_loop" ? saved : void 0;
   const opId = checkpoint?.opId ?? args.opId;
-  let primaryFailure = false;
-  const tools = useReasonArgs.tools ?? [];
+  const tools2 = useReasonArgs.tools ?? [];
   const toolByName = /* @__PURE__ */ new Map();
-  let validationCompleted = false;
   let separateOutput = false;
-  try {
-    for (const tool of tools) {
-      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."
-      );
+  for (const tool of tools2) {
+    if (toolByName.has(tool.name)) {
+      throw new Error(`useReason received duplicate tool name "${tool.name}".`);
     }
-    separateOutput = Boolean(
-      useReasonArgs.model.provider.getModel(useReasonArgs.model.modelId, {
-        ...useReasonArgs.model.options,
-        ...useReasonArgs.reasoning !== void 0 ? { reasoning: useReasonArgs.reasoning } : {},
-        ...useReasonArgs.responseFormat ? { responseFormat: useReasonArgs.responseFormat } : {},
-        providerOptions: resolveProviderOptions(
-          useReasonArgs.model.options?.providerOptions,
-          useReasonArgs.providerOptions
-        ) ?? {}
-      }).requiresSeparateStructuredOutput
+    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."
     );
-    validationCompleted = true;
-  } finally {
-    if (!validationCompleted) {
-      await closeOwnedTools(tools, true, traceSpan);
-    }
   }
-  const toolDefinitions = toToolDefinitions(tools);
+  separateOutput = Boolean(
+    useReasonArgs.model.provider.getModel(useReasonArgs.model.modelId, {
+      ...useReasonArgs.model.options,
+      ...useReasonArgs.reasoning !== void 0 ? { reasoning: useReasonArgs.reasoning } : {},
+      ...useReasonArgs.responseFormat ? { responseFormat: useReasonArgs.responseFormat } : {},
+      providerOptions: resolveProviderOptions(
+        useReasonArgs.model.options?.providerOptions,
+        useReasonArgs.providerOptions
+      ) ?? {}
+    }).requiresSeparateStructuredOutput
+  );
+  const toolDefinitions = toToolDefinitions(tools2);
   let finalizing = checkpoint?.finalizing ?? false;
   let completed = false;
   const maxSteps = Math.max(1, useReasonArgs.toolExecution?.maxSteps ?? 3);
@@ -2028,7 +2460,7 @@ var runReasonToolLoop = async (args) => {
   };
   try {
     for (let stepIndex = pending ? steps.length - 1 : steps.length; stepIndex < maxSteps; stepIndex += 1) {
-      (0, import_core4.throwIfExecutionAborted)(abortSignal);
+      (0, import_core5.throwIfExecutionAborted)(abortSignal);
       traceSpan?.addEvent?.("useReason.tool-step.start", {
         stepIndex,
         toolCount: toolDefinitions.length
@@ -2072,6 +2504,12 @@ var runReasonToolLoop = async (args) => {
       );
       aggregatedWarnings = mergeWarnings(aggregatedWarnings, step.warnings);
       const toolCalls = step.toolCalls ?? [];
+      const ids = /* @__PURE__ */ new Set();
+      for (const call of toolCalls) {
+        if (!call.id || ids.has(call.id) || !reused && allToolCalls.some((prior) => prior.id === call.id))
+          throw new Error("Model returned duplicate or empty tool call IDs.");
+        ids.add(call.id);
+      }
       const toolResults = reused ? steps[stepIndex]?.toolResults ?? [] : [];
       if (!reused)
         steps.push({
@@ -2140,9 +2578,15 @@ var runReasonToolLoop = async (args) => {
       pending = step;
       save();
       for (const toolCall of toolCalls) {
-        if (toolResults.some((result2) => result2.toolCallId === toolCall.id))
+        if (toolResults.some((result2) => result2.toolCallId === toolCall.id)) {
+          await replayToolObservations(
+            steps[stepIndex]?.toolObservations?.filter(
+              (observation) => observation.toolCallId === `${opId}:${toolCall.id}`
+            ) ?? []
+          );
           continue;
-        (0, import_core4.throwIfExecutionAborted)(abortSignal);
+        }
+        (0, import_core5.throwIfExecutionAborted)(abortSignal);
         const tool = toolByName.get(toolCall.name);
         if (!tool) {
           throw new Error(
@@ -2159,11 +2603,6 @@ var runReasonToolLoop = async (args) => {
           tool.name,
           false
         );
-        traceSpan?.addEvent?.("useReason.tool-call.start", {
-          stepIndex,
-          tool: tool.name,
-          toolCallId: toolCall.id
-        });
         if (shouldEmitTool) {
           emitToolEvent("tool-call-start", {
             tool: tool.name,
@@ -2172,6 +2611,17 @@ var runReasonToolLoop = async (args) => {
           });
         }
         if (shouldApproveTool && !approvedCalls.includes(toolCall.id)) {
+          await observeToolFact(
+            {
+              version: 1,
+              name: tool.name,
+              toolCallId: `${opId}:${toolCall.id}`,
+              attemptId: `${opId}:${toolCall.id}:approval`,
+              callingMode: "model",
+              executed: false
+            },
+            "waiting"
+          );
           const approval = await awaitInterruptInternal({
             id: `tool:${toolCall.id}`,
             request: {
@@ -2190,6 +2640,22 @@ var runReasonToolLoop = async (args) => {
           });
           const approved = Array.isArray(approval) ? approval.includes("approve") : approval === "approve";
           if (!approved) {
+            const deniedObservation = {
+              version: 1,
+              name: tool.name,
+              toolCallId: `${opId}:${toolCall.id}`,
+              attemptId: `${opId}:${toolCall.id}:approval`,
+              callingMode: "model",
+              executed: false,
+              outcome: "denied",
+              denialCode: "APPROVAL_DENIED"
+            };
+            await observeToolFact(deniedObservation);
+            const entry = steps[stepIndex];
+            if (entry) {
+              entry.toolObservations ??= [];
+              entry.toolObservations.push(deniedObservation);
+            }
             const denied = {
               toolCallId: toolCall.id,
               name: tool.name,
@@ -2220,13 +2686,24 @@ var runReasonToolLoop = async (args) => {
           save();
         }
         try {
-          (0, import_core4.throwIfExecutionAborted)(abortSignal);
-          ctx.node.consumeExecution?.("maxToolCalls");
-          const rawResult = await tool.execute(toolCall.input, {
-            toolCallId: toolCall.id,
-            ...abortSignal ? { abortSignal } : {}
+          (0, import_core5.throwIfExecutionAborted)(abortSignal);
+          const rawResult = await executeObservedTool({
+            tool,
+            input: toolCall.input,
+            toolCallId: `${opId}:${toolCall.id}`,
+            providerToolCallId: toolCall.id,
+            callingMode: "model",
+            abortSignal,
+            onObservation: (observation) => {
+              const entry = steps[stepIndex];
+              if (entry) {
+                entry.toolObservations ??= [];
+                entry.toolObservations.push(observation);
+                save();
+              }
+            }
           });
-          (0, import_core4.throwIfExecutionAborted)(abortSignal);
+          (0, import_core5.throwIfExecutionAborted)(abortSignal);
           const result2 = normalizeToolResult(toolCall, rawResult);
           toolResults.push(result2);
           allToolResults.push(result2);
@@ -2239,20 +2716,14 @@ var runReasonToolLoop = async (args) => {
               ...result2.isError !== void 0 ? { isError: result2.isError } : {}
             });
           }
-          traceSpan?.addEvent?.("useReason.tool-call.complete", {
-            stepIndex,
-            tool: result2.name,
-            toolCallId: result2.toolCallId,
-            isError: Boolean(result2.isError)
-          });
         } catch (error) {
-          (0, import_core4.throwIfExecutionAborted)(abortSignal);
-          if ((0, import_errors4.isControlFlowError)(error)) throw error;
+          (0, import_core5.throwIfExecutionAborted)(abortSignal);
+          if ((0, import_errors6.isControlFlowError)(error)) throw error;
           const result2 = {
             toolCallId: toolCall.id,
             name: tool.name,
-            content: (0, import_errors4.serializeFailure)(error).message,
-            failure: (0, import_errors4.serializeFailure)(error),
+            content: (0, import_errors6.serializeFailure)(error).message,
+            failure: (0, import_errors6.serializeFailure)(error),
             isError: true
           };
           toolResults.push(result2);
@@ -2265,13 +2736,6 @@ var runReasonToolLoop = async (args) => {
               failure: result2.failure
             });
           }
-          traceSpan?.addEvent?.("useReason.tool-call.error", {
-            stepIndex,
-            tool: tool.name,
-            toolCallId: toolCall.id,
-            message: result2.content,
-            failure: result2.failure
-          });
         }
         const completed2 = toolResults.at(-1);
         if (completed2)
@@ -2344,7 +2808,6 @@ var runReasonToolLoop = async (args) => {
     ctx.stateDirty = true;
     return result;
   } catch (error) {
-    primaryFailure = true;
     try {
       traceSpan?.fail?.(error, {
         attributes: {
@@ -2355,8 +2818,6 @@ var runReasonToolLoop = async (args) => {
     } catch {
     }
     throw error;
-  } finally {
-    await closeOwnedTools(tools, primaryFailure, traceSpan);
   }
 };
 
@@ -2372,15 +2833,15 @@ var assertReasoningThoughtsCompatibility = (args) => {
     "useReason does not support reasoning.includeThoughts with structured output, interrupt mode, or JSON responseFormat. Disable includeThoughts for this call."
   );
 };
-async function useReason(args) {
+async function runReason(args) {
   assertReasoningThoughtsCompatibility(args);
   const ctx = getHookContext();
-  const abortSignal = (0, import_core5.combineAbortSignals)(
+  const abortSignal = (0, import_core6.combineAbortSignals)(
     ctx.node.abortSignal,
     args.abortSignal,
     args.model.options?.abortSignal
   );
-  (0, import_core5.throwIfExecutionAborted)(abortSignal);
+  (0, import_core6.throwIfExecutionAborted)(abortSignal);
   const allowValidatedToolOutput = Boolean(
     args.outputSchema && !(args.responseFormat ?? args.model.options?.responseFormat)
   );
@@ -2403,286 +2864,303 @@ async function useReason(args) {
     ctx.currentNodeState.byKey[checkpointKey]
   );
   if (existingCompleted) {
+    await replayToolObservations(
+      existingCompleted.result.steps?.flatMap(
+        (step) => step.toolObservations ?? []
+      ) ?? []
+    );
     return existingCompleted.result;
   }
   const existingCheckpoint = readReasonCheckpoint(
     ctx.currentNodeState.byKey[checkpointKey]
   );
   const reasonMeta = typeof id === "string" ? { id, opId } : { opId };
-  const traceSpan = getReasonTraceAdapter()?.startSpan({
-    name: "useReason",
-    attributes: {
-      ...id ? { id } : {},
-      opId,
-      nodeId: ctx.node.graph.node,
-      providerId: args.model.provider.id,
-      modelId: args.model.modelId,
-      stream: args.stream ?? args.model.options?.streaming ?? true,
-      emit: args.emit ?? true,
-      ...args.telemetry?.operation ? { operation: args.telemetry.operation } : {},
-      ...args.telemetry?.prompt?.name ? { promptName: args.telemetry.prompt.name } : {},
-      ...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),
-      hasStructured: Boolean(args.structured),
-      hasTools: Boolean(args.tools?.length)
-    },
-    telemetry: {
-      ...args.telemetry ?? {},
-      input: args.telemetry?.input ?? args.input
-    }
-  });
-  if (args.tools?.length) {
-    return runReasonToolLoop({
-      useReasonArgs: args,
-      allowValidatedToolOutput,
-      checkpointKey,
-      initialWarnings: inferred.warnings,
-      ...id ? { id } : {},
-      opId,
-      ...traceSpan ? { traceSpan } : {}
-    });
-  }
-  const suppressTextStream = Boolean(args.outputSchema || args.interrupt);
-  const setFieldPaths = resolveSetFieldPaths(args.structured);
-  const appendFieldPaths = resolveAppendFieldPaths(args.structured);
-  const textDeltaFieldPaths = resolveTextDeltaFieldPaths(args.structured);
-  const useStructuredIncrementalStreaming = Boolean(
-    args.outputSchema && !args.interrupt && (setFieldPaths.length > 0 || appendFieldPaths.length > 0 || textDeltaFieldPaths.length > 0) && args.stream !== false && shouldStreamReasonStructured(args)
-  );
-  let firstText = "";
-  let firstRaw;
-  let firstOutput;
-  let firstInterruptRequest;
-  let firstInterruptRequired = false;
-  let finalText = "";
-  let finalRaw;
-  let finalOutput;
-  let aggregatedUsage;
-  let finalFinishReason;
-  let aggregatedProviderMetadata;
-  let aggregatedWarnings = inferred.warnings;
-  if (existingCheckpoint) {
-    firstText = existingCheckpoint.firstText;
-    firstRaw = existingCheckpoint.firstRaw;
-    firstOutput = existingCheckpoint.firstOutput;
-    finalText = firstText;
-    finalRaw = firstRaw;
-    finalOutput = firstOutput;
-    aggregatedUsage = existingCheckpoint.firstUsage;
-    finalFinishReason = existingCheckpoint.firstFinishReason;
-    aggregatedProviderMetadata = existingCheckpoint.firstProviderMetadata;
-    aggregatedWarnings = existingCheckpoint.firstWarnings;
-    traceSpan?.addEvent?.("useReason.resume", {
-      checkpointKey
-    });
-  } else {
-    const first = await reasonEngine(
-      {
-        ...args,
-        emit: suppressTextStream ? false : args.emit,
-        stream: useStructuredIncrementalStreaming ? true : suppressTextStream ? false : args.stream,
-        ...useStructuredIncrementalStreaming ? {
-          onTextChunk: createStructuredOutputStreamer(args, id, opId)
-        } : {}
+  return withSafeTraceSpan(
+    getReasonTraceAdapter(),
+    {
+      name: "useReason",
+      attributes: {
+        ...id ? { id } : {},
+        opId,
+        nodeId: ctx.node.graph.node,
+        providerId: args.model.provider.id,
+        modelId: args.model.modelId,
+        stream: args.stream ?? args.model.options?.streaming ?? true,
+        emit: args.emit ?? true,
+        ...args.telemetry?.operation ? { operation: args.telemetry.operation } : {},
+        ...args.telemetry?.prompt?.name ? { promptName: args.telemetry.prompt.name } : {},
+        ...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),
+        hasStructured: Boolean(args.structured),
+        hasTools: Boolean(args.tools?.length)
       },
-      reasonMeta,
-      args.interrupt ? defaultInterruptFirstPassInput({
-        input: args.input,
-        requestSchema: args.interrupt.requestSchema,
-        mode: args.interrupt.mode ?? "required",
-        ...args.outputSchema ? { outputSchema: args.outputSchema } : {}
-      }) : args.outputSchema ? withOutputGuardrails(
-        withStructuredStreamHints(args.input, {
-          ...setFieldPaths.length > 0 ? { setFieldPaths } : {},
-          ...appendFieldPaths.length > 0 ? { appendFieldPaths } : {},
-          ...textDeltaFieldPaths.length > 0 ? { textDeltaFieldPaths } : {}
-        }),
-        args.outputSchema
-      ) : void 0
-    );
-    firstRaw = first.raw;
-    finalRaw = first.raw;
-    accumulateTokenUsage(first.usage);
-    aggregatedUsage = mergeUsage(aggregatedUsage, first.usage);
-    finalFinishReason = first.finishReason;
-    aggregatedProviderMetadata = mergeProviderMetadata(
-      aggregatedProviderMetadata,
-      first.providerMetadata
-    );
-    aggregatedWarnings = mergeWarnings(aggregatedWarnings, first.warnings);
-    traceSpan?.addEvent?.("useReason.first-pass.complete", {
-      textLength: first.text.length,
-      hasInterrupt: Boolean(args.interrupt)
-    });
-    if (args.interrupt) {
-      const firstPass = parseInterruptFirstPassResult({
-        text: first.text,
-        requestSchema: args.interrupt.requestSchema,
-        ...first.finishReason ? { finishReason: first.finishReason } : {},
-        ...first.usage ? { usage: first.usage } : {},
-        ...args.outputSchema ? { outputSchema: args.outputSchema } : {},
-        mode: args.interrupt.mode ?? "required"
-      });
-      firstText = firstPass.draftText;
-      finalText = firstPass.draftText;
-      firstInterruptRequired = firstPass.interruptRequired;
-      firstInterruptRequest = firstPass.request;
-      firstOutput = firstPass.output;
-      finalOutput = firstPass.output;
-    } else {
-      firstText = first.text;
-      finalText = first.text;
-      if (args.outputSchema) {
-        firstOutput = parseReasonOutputWithSchema({
-          text: first.text,
-          schema: args.outputSchema,
-          ...first.finishReason ? { finishReason: first.finishReason } : {},
-          ...first.usage ? { usage: first.usage } : {},
-          label: "useReason output"
+      telemetry: {
+        ...args.telemetry ?? {},
+        input: args.telemetry?.input ?? args.input
+      }
+    },
+    async (traceSpan) => {
+      if (args.tools?.length) {
+        return runReasonToolLoop({
+          useReasonArgs: args,
+          allowValidatedToolOutput,
+          checkpointKey,
+          initialWarnings: inferred.warnings,
+          ...id ? { id } : {},
+          opId,
+          ...traceSpan ? { traceSpan } : {}
         });
       }
-      finalOutput = firstOutput;
-    }
-  }
-  let interruptResponse;
-  if (args.interrupt && (existingCheckpoint || firstInterruptRequired)) {
-    const requestSchema = args.interrupt.requestSchema;
-    const interruptRequest = existingCheckpoint ? parseWithSchema(
-      requestSchema,
-      existingCheckpoint.request,
-      "useReason interrupt.request"
-    ) : firstInterruptRequest;
-    if (!interruptRequest) {
-      throw new Error(
-        "useReason interrupt request is missing; first pass did not produce a valid interrupt payload."
+      const suppressTextStream = Boolean(args.outputSchema || args.interrupt);
+      const setFieldPaths = resolveSetFieldPaths(args.structured);
+      const appendFieldPaths = resolveAppendFieldPaths(args.structured);
+      const textDeltaFieldPaths = resolveTextDeltaFieldPaths(args.structured);
+      const useStructuredIncrementalStreaming = Boolean(
+        args.outputSchema && !args.interrupt && (setFieldPaths.length > 0 || appendFieldPaths.length > 0 || textDeltaFieldPaths.length > 0) && args.stream !== false && shouldStreamReasonStructured(args)
       );
-    }
-    if (!existingCheckpoint) {
-      ctx.currentNodeState.byKey[checkpointKey] = {
-        status: "awaiting_interrupt",
-        request: interruptRequest,
-        firstText,
-        ...firstRaw !== void 0 ? { firstRaw } : {},
-        ...aggregatedUsage !== void 0 ? { firstUsage: aggregatedUsage } : {},
-        ...finalFinishReason !== void 0 ? { firstFinishReason: finalFinishReason } : {},
-        ...aggregatedProviderMetadata !== void 0 ? { firstProviderMetadata: aggregatedProviderMetadata } : {},
-        ...aggregatedWarnings !== void 0 ? { firstWarnings: aggregatedWarnings } : {},
-        ...firstOutput !== void 0 ? { firstOutput } : {}
-      };
-      ctx.stateDirty = true;
-    }
-    const resumeStatePatch = resolveHookStatePatch({
-      nodeId: ctx.node.graph.node,
-      currentNodeState: ctx.currentNodeState,
-      workflowState: ctx.workflowState
-    });
-    interruptResponse = await awaitInterruptInternal({
-      request: interruptRequest,
-      requestSchema,
-      responseSchema: args.interrupt.responseSchema,
-      ...args.interrupt.schemaId ? { schemaId: args.interrupt.schemaId } : {},
-      ...args.interrupt.schemaVersion ? { schemaVersion: args.interrupt.schemaVersion } : {},
-      ...id ? { id } : {},
-      meta: {
-        __kortyxResumeStatePatch: resumeStatePatch
+      let firstText = "";
+      let firstRaw;
+      let firstOutput;
+      let firstInterruptRequest;
+      let firstInterruptRequired = false;
+      let finalText = "";
+      let finalRaw;
+      let finalOutput;
+      let aggregatedUsage;
+      let finalFinishReason;
+      let aggregatedProviderMetadata;
+      let aggregatedWarnings = inferred.warnings;
+      if (existingCheckpoint) {
+        firstText = existingCheckpoint.firstText;
+        firstRaw = existingCheckpoint.firstRaw;
+        firstOutput = existingCheckpoint.firstOutput;
+        finalText = firstText;
+        finalRaw = firstRaw;
+        finalOutput = firstOutput;
+        aggregatedUsage = existingCheckpoint.firstUsage;
+        finalFinishReason = existingCheckpoint.firstFinishReason;
+        aggregatedProviderMetadata = existingCheckpoint.firstProviderMetadata;
+        aggregatedWarnings = existingCheckpoint.firstWarnings;
+        traceSpan?.addEvent?.("useReason.resume", {
+          checkpointKey
+        });
+      } else {
+        const first = await reasonEngine(
+          {
+            ...args,
+            emit: suppressTextStream ? false : args.emit,
+            stream: useStructuredIncrementalStreaming ? true : suppressTextStream ? false : args.stream,
+            ...useStructuredIncrementalStreaming ? {
+              onTextChunk: createStructuredOutputStreamer(args, id, opId)
+            } : {}
+          },
+          reasonMeta,
+          args.interrupt ? defaultInterruptFirstPassInput({
+            input: args.input,
+            requestSchema: args.interrupt.requestSchema,
+            mode: args.interrupt.mode ?? "required",
+            ...args.outputSchema ? { outputSchema: args.outputSchema } : {}
+          }) : args.outputSchema ? withOutputGuardrails(
+            withStructuredStreamHints(args.input, {
+              ...setFieldPaths.length > 0 ? { setFieldPaths } : {},
+              ...appendFieldPaths.length > 0 ? { appendFieldPaths } : {},
+              ...textDeltaFieldPaths.length > 0 ? { textDeltaFieldPaths } : {}
+            }),
+            args.outputSchema
+          ) : void 0
+        );
+        firstRaw = first.raw;
+        finalRaw = first.raw;
+        accumulateTokenUsage(first.usage);
+        aggregatedUsage = mergeUsage(aggregatedUsage, first.usage);
+        finalFinishReason = first.finishReason;
+        aggregatedProviderMetadata = mergeProviderMetadata(
+          aggregatedProviderMetadata,
+          first.providerMetadata
+        );
+        aggregatedWarnings = mergeWarnings(aggregatedWarnings, first.warnings);
+        traceSpan?.addEvent?.("useReason.first-pass.complete", {
+          textLength: first.text.length,
+          hasInterrupt: Boolean(args.interrupt)
+        });
+        if (args.interrupt) {
+          const firstPass = parseInterruptFirstPassResult({
+            text: first.text,
+            requestSchema: args.interrupt.requestSchema,
+            ...first.finishReason ? { finishReason: first.finishReason } : {},
+            ...first.usage ? { usage: first.usage } : {},
+            ...args.outputSchema ? { outputSchema: args.outputSchema } : {},
+            mode: args.interrupt.mode ?? "required"
+          });
+          firstText = firstPass.draftText;
+          finalText = firstPass.draftText;
+          firstInterruptRequired = firstPass.interruptRequired;
+          firstInterruptRequest = firstPass.request;
+          firstOutput = firstPass.output;
+          finalOutput = firstPass.output;
+        } else {
+          firstText = first.text;
+          finalText = first.text;
+          if (args.outputSchema) {
+            firstOutput = parseReasonOutputWithSchema({
+              text: first.text,
+              schema: args.outputSchema,
+              ...first.finishReason ? { finishReason: first.finishReason } : {},
+              ...first.usage ? { usage: first.usage } : {},
+              label: "useReason output"
+            });
+          }
+          finalOutput = firstOutput;
+        }
       }
-    });
-    traceSpan?.addEvent?.("useReason.interrupt.resolved", {
-      checkpointKey
-    });
-    if (Object.hasOwn(ctx.currentNodeState.byKey, checkpointKey)) {
-      delete ctx.currentNodeState.byKey[checkpointKey];
-      ctx.stateDirty = true;
-    }
-    const continuationInput = defaultContinuationInput({
-      input: args.input,
-      draftText: firstText,
-      ...firstOutput !== void 0 ? { draftOutput: firstOutput } : {},
-      request: interruptRequest,
-      response: interruptResponse
-    });
-    const second = await reasonEngine(
-      {
-        ...args,
-        ...inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {},
-        emit: suppressTextStream ? false : args.emit,
-        stream: suppressTextStream ? false : args.stream
-      },
-      reasonMeta,
-      args.outputSchema ? withOutputGuardrails(
-        continuationInput,
-        args.outputSchema
-      ) : continuationInput
-    );
-    finalText = second.text;
-    finalRaw = second.raw;
-    accumulateTokenUsage(second.usage);
-    aggregatedUsage = mergeUsage(aggregatedUsage, second.usage);
-    finalFinishReason = second.finishReason;
-    aggregatedProviderMetadata = mergeProviderMetadata(
-      aggregatedProviderMetadata,
-      second.providerMetadata
-    );
-    aggregatedWarnings = mergeWarnings(aggregatedWarnings, second.warnings);
-    traceSpan?.addEvent?.("useReason.continuation.complete", {
-      textLength: second.text.length
-    });
-    if (args.outputSchema) {
-      finalOutput = parseReasonOutputWithSchema({
+      let interruptResponse;
+      if (args.interrupt && (existingCheckpoint || firstInterruptRequired)) {
+        const requestSchema = args.interrupt.requestSchema;
+        const interruptRequest = existingCheckpoint ? parseWithSchema(
+          requestSchema,
+          existingCheckpoint.request,
+          "useReason interrupt.request"
+        ) : firstInterruptRequest;
+        if (!interruptRequest) {
+          throw new Error(
+            "useReason interrupt request is missing; first pass did not produce a valid interrupt payload."
+          );
+        }
+        if (!existingCheckpoint) {
+          ctx.currentNodeState.byKey[checkpointKey] = {
+            status: "awaiting_interrupt",
+            request: interruptRequest,
+            firstText,
+            ...firstRaw !== void 0 ? { firstRaw } : {},
+            ...aggregatedUsage !== void 0 ? { firstUsage: aggregatedUsage } : {},
+            ...finalFinishReason !== void 0 ? { firstFinishReason: finalFinishReason } : {},
+            ...aggregatedProviderMetadata !== void 0 ? { firstProviderMetadata: aggregatedProviderMetadata } : {},
+            ...aggregatedWarnings !== void 0 ? { firstWarnings: aggregatedWarnings } : {},
+            ...firstOutput !== void 0 ? { firstOutput } : {}
+          };
+          ctx.stateDirty = true;
+        }
+        const resumeStatePatch = resolveHookStatePatch({
+          nodeId: ctx.node.graph.node,
+          currentNodeState: ctx.currentNodeState,
+          workflowState: ctx.workflowState
+        });
+        interruptResponse = await awaitInterruptInternal({
+          request: interruptRequest,
+          requestSchema,
+          responseSchema: args.interrupt.responseSchema,
+          ...args.interrupt.schemaId ? { schemaId: args.interrupt.schemaId } : {},
+          ...args.interrupt.schemaVersion ? { schemaVersion: args.interrupt.schemaVersion } : {},
+          ...id ? { id } : {},
+          meta: {
+            __kortyxResumeStatePatch: resumeStatePatch
+          }
+        });
+        traceSpan?.addEvent?.("useReason.interrupt.resolved", {
+          checkpointKey
+        });
+        if (Object.hasOwn(ctx.currentNodeState.byKey, checkpointKey)) {
+          delete ctx.currentNodeState.byKey[checkpointKey];
+          ctx.stateDirty = true;
+        }
+        const continuationInput = defaultContinuationInput({
+          input: args.input,
+          draftText: firstText,
+          ...firstOutput !== void 0 ? { draftOutput: firstOutput } : {},
+          request: interruptRequest,
+          response: interruptResponse
+        });
+        const second = await reasonEngine(
+          {
+            ...args,
+            ...inferred.responseFormat ? { responseFormat: inferred.responseFormat } : {},
+            emit: suppressTextStream ? false : args.emit,
+            stream: suppressTextStream ? false : args.stream
+          },
+          reasonMeta,
+          args.outputSchema ? withOutputGuardrails(
+            continuationInput,
+            args.outputSchema
+          ) : continuationInput
+        );
+        finalText = second.text;
+        finalRaw = second.raw;
+        accumulateTokenUsage(second.usage);
+        aggregatedUsage = mergeUsage(aggregatedUsage, second.usage);
+        finalFinishReason = second.finishReason;
+        aggregatedProviderMetadata = mergeProviderMetadata(
+          aggregatedProviderMetadata,
+          second.providerMetadata
+        );
+        aggregatedWarnings = mergeWarnings(aggregatedWarnings, second.warnings);
+        traceSpan?.addEvent?.("useReason.continuation.complete", {
+          textLength: second.text.length
+        });
+        if (args.outputSchema) {
+          finalOutput = parseReasonOutputWithSchema({
+            text: finalText,
+            schema: args.outputSchema,
+            ...second.finishReason ? { finishReason: second.finishReason } : {},
+            ...aggregatedUsage ? { usage: aggregatedUsage } : {},
+            label: "useReason output"
+          });
+        }
+      }
+      if (finalOutput !== void 0) {
+        emitReasonStructuredOutput({
+          ...id ? { id } : {},
+          opId,
+          output: finalOutput,
+          structured: args.structured,
+          emit: args.emit ?? true
+        });
+      }
+      const result = {
+        ...id ? { id } : {},
+        opId,
         text: finalText,
-        schema: args.outputSchema,
-        ...second.finishReason ? { finishReason: second.finishReason } : {},
-        ...aggregatedUsage ? { usage: aggregatedUsage } : {},
-        label: "useReason output"
+        ...finalRaw !== void 0 ? { raw: finalRaw } : {},
+        ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
+        ...finalFinishReason !== void 0 ? { finishReason: finalFinishReason } : {},
+        ...aggregatedProviderMetadata !== void 0 ? { providerMetadata: aggregatedProviderMetadata } : {},
+        ...aggregatedWarnings !== void 0 ? { warnings: aggregatedWarnings } : {},
+        ...finalOutput !== void 0 ? { output: finalOutput } : {},
+        ...interruptResponse !== void 0 ? { interruptResponse } : {}
+      };
+      if (args.interrupt) {
+        ctx.currentNodeState.byKey[checkpointKey] = {
+          status: "completed",
+          result
+        };
+        ctx.stateDirty = true;
+      }
+      traceSpan?.end?.({
+        ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
+        ...finalFinishReason !== void 0 ? { finishReason: finalFinishReason } : {},
+        ...aggregatedProviderMetadata !== void 0 ? { providerMetadata: aggregatedProviderMetadata } : {},
+        ...aggregatedWarnings !== void 0 ? { warnings: aggregatedWarnings } : {},
+        attributes: {
+          textLength: finalText.length,
+          resumedFromCheckpoint: Boolean(existingCheckpoint),
+          interrupted: Boolean(interruptResponse !== void 0)
+        },
+        telemetry: {
+          ...args.telemetry ?? {},
+          output: args.telemetry?.output ?? finalOutput ?? finalText
+        }
       });
+      return result;
     }
+  );
+}
+async function useReason(args) {
+  try {
+    return await runReason(args);
+  } finally {
+    await closeOwnedTools(args.tools ?? []);
   }
-  if (finalOutput !== void 0) {
-    emitReasonStructuredOutput({
-      ...id ? { id } : {},
-      opId,
-      output: finalOutput,
-      structured: args.structured,
-      emit: args.emit ?? true
-    });
-  }
-  const result = {
-    ...id ? { id } : {},
-    opId,
-    text: finalText,
-    ...finalRaw !== void 0 ? { raw: finalRaw } : {},
-    ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
-    ...finalFinishReason !== void 0 ? { finishReason: finalFinishReason } : {},
-    ...aggregatedProviderMetadata !== void 0 ? { providerMetadata: aggregatedProviderMetadata } : {},
-    ...aggregatedWarnings !== void 0 ? { warnings: aggregatedWarnings } : {},
-    ...finalOutput !== void 0 ? { output: finalOutput } : {},
-    ...interruptResponse !== void 0 ? { interruptResponse } : {}
-  };
-  if (args.interrupt) {
-    ctx.currentNodeState.byKey[checkpointKey] = {
-      status: "completed",
-      result
-    };
-    ctx.stateDirty = true;
-  }
-  traceSpan?.end?.({
-    ...aggregatedUsage !== void 0 ? { usage: aggregatedUsage } : {},
-    ...finalFinishReason !== void 0 ? { finishReason: finalFinishReason } : {},
-    ...aggregatedProviderMetadata !== void 0 ? { providerMetadata: aggregatedProviderMetadata } : {},
-    ...aggregatedWarnings !== void 0 ? { warnings: aggregatedWarnings } : {},
-    attributes: {
-      textLength: finalText.length,
-      resumedFromCheckpoint: Boolean(existingCheckpoint),
-      interrupted: Boolean(interruptResponse !== void 0)
-    },
-    telemetry: {
-      ...args.telemetry ?? {},
-      output: args.telemetry?.output ?? finalOutput ?? finalText
-    }
-  });
-  return result;
 }
 
 // src/hooks.ts
@@ -2741,8 +3219,8 @@ function useWorkflowState(key, ...rest) {
 }
 
 // src/parallel.ts
-var import_core6 = require("@kortyx/core");
-var import_errors5 = require("@kortyx/core/errors");
+var import_core7 = require("@kortyx/core");
+var import_errors7 = require("@kortyx/core/errors");
 var ParallelChildWaiting = class extends Error {
   name = "ParallelChildWaiting";
 };
@@ -2756,14 +3234,14 @@ var ParallelError = class extends AggregateError {
     );
     this.results = results;
     this.name = "ParallelError";
-    this.failure = (0, import_errors5.serializeFailure)({
+    this.failure = (0, import_errors7.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_errors5.serializeFailure)(result.reason) }
+        (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors7.serializeFailure)(result.reason) }
       )
     });
   }
@@ -2771,7 +3249,7 @@ var ParallelError = class extends AggregateError {
   code = "PARALLEL_FAILED";
   failure;
   toJSON() {
-    return (0, import_errors5.serializeFailure)(this);
+    return (0, import_errors7.serializeFailure)(this);
   }
 };
 function registerWorkflowTask(id) {
@@ -2867,13 +3345,13 @@ function parallel(values) {
         );
       }
       if (ready[0]?.status === "rejected") throw ready[0].reason;
-      (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+      (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
       if (ctx.workflowControlError) throw ctx.workflowControlError;
       const rejected = outcomes.filter(
         (outcome) => outcome.status === "rejected"
       );
       const control = rejected.find(
-        (outcome) => (0, import_core6.isExecutionCancelled)(outcome.reason) || (0, import_core6.isExecutionLimitReached)(outcome.reason)
+        (outcome) => (0, import_core7.isExecutionCancelled)(outcome.reason) || (0, import_core7.isExecutionLimitReached)(outcome.reason)
       );
       if (control) {
         ctx.workflowControlError = control.reason;
@@ -2910,54 +3388,13 @@ function parallel(values) {
 }
 
 // src/workflow.ts
-var import_node_crypto5 = require("crypto");
-var import_core7 = require("@kortyx/core");
-var import_errors6 = require("@kortyx/core/errors");
-
-// src/workflow-telemetry.ts
-var import_node_crypto4 = require("crypto");
-function emitWorkflowCall(telemetry, type, payload) {
-  const base = telemetry?.correlation;
-  if (!telemetry?.reporter || !telemetry.environment || !telemetry.service || !base?.runId || !base.workflowId)
-    return;
-  try {
-    const active = telemetry.trace?.getActiveContext?.();
-    void Promise.resolve(
-      telemetry.reporter.emit([
-        {
-          schemaVersion: 1,
-          eventId: (0, import_node_crypto4.randomUUID)(),
-          occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
-          environment: telemetry.environment,
-          service: telemetry.service,
-          correlation: {
-            ...base,
-            runId: base.runId,
-            workflowId: base.workflowId,
-            ...active
-          },
-          type,
-          payload
-        }
-      ])
-    ).catch(() => {
-    });
-  } catch {
-  }
-}
-function workflowCallContent(telemetry, side, value) {
-  const policy = telemetry?.captureContent;
-  if (!(policy === true || policy && typeof policy === "object" && policy[side]))
-    return {};
-  const serialized = JSON.stringify(value);
-  return serialized && Buffer.byteLength(serialized, "utf8") <= 16384 ? { [side]: JSON.parse(serialized) } : { [`${side}Omitted`]: "Content exceeds 16 KiB" };
-}
-
-// src/workflow.ts
-var WorkflowCallError = class extends import_errors6.KortyxError {
+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 {
   constructor(workflow, message, cause, failure) {
-    const detail = (0, import_errors6.serializeFailure)(
-      failure ?? cause ?? new import_errors6.WorkflowContractError(message)
+    const detail = (0, import_errors8.serializeFailure)(
+      failure ?? cause ?? new import_errors8.WorkflowContractError(message)
     );
     super(detail.code, `Workflow '${workflow}': ${message}`, {
       ...detail,
@@ -2978,12 +3415,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_errors6.WorkflowContractError(
+      throw new import_errors8.WorkflowContractError(
         "Workflow input and output must be JSON serializable."
       );
     }
     if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype) {
-      throw new import_errors6.WorkflowContractError(
+      throw new import_errors8.WorkflowContractError(
         "Workflow input and output must contain plain JSON objects."
       );
     }
@@ -3004,7 +3441,7 @@ function createWorkflowHooks(workflows) {
     useWorkflow: (args) => {
       const workflow = workflows[args.workflow];
       if (!workflow || workflow.id !== args.workflow)
-        throw new import_errors6.WorkflowContractError(
+        throw new import_errors8.WorkflowContractError(
           "Workflow registry keys must match definition ids."
         );
       return useWorkflow({ ...args, workflow });
@@ -3018,7 +3455,7 @@ async function useWorkflow(args) {
     if (task.group) await task.group.ready;
     return await runWorkflowCall(args, task);
   } catch (error) {
-    if ((0, import_core7.isExecutionCancelled)(error) || (0, import_core7.isExecutionLimitReached)(error))
+    if ((0, import_core8.isExecutionCancelled)(error) || (0, import_core8.isExecutionLimitReached)(error))
       getHookContext().workflowControlError = error;
     throw error;
   } finally {
@@ -3027,26 +3464,26 @@ async function useWorkflow(args) {
 }
 async function runWorkflowCall(args, task) {
   const ctx = getHookContext();
-  (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
+  (0, import_core8.throwIfExecutionAborted)(ctx.node.abortSignal);
   const service = ctx.node.callWorkflow;
   if (!service)
-    throw new import_errors6.WorkflowContractError(
+    throw new import_errors8.WorkflowContractError(
       "useWorkflow requires an agent workflow registry."
     );
   if (!args.id.trim())
-    throw new import_errors6.WorkflowContractError(
+    throw new import_errors8.WorkflowContractError(
       "useWorkflow requires a stable, nonempty id."
     );
   if (ctx.workflowCallActive && !task.group)
-    throw new import_errors6.WorkflowContractError(
+    throw new import_errors8.WorkflowContractError(
       "Concurrent workflow calls require parallel([...]); otherwise await each call."
     );
   if (ctx.workflowCallIds.has(args.id))
-    throw new import_errors6.WorkflowContractError(
+    throw new import_errors8.WorkflowContractError(
       `Duplicate workflow call id '${args.id}' in one node activation.`
     );
   if (ctx.workflowCallIds.size >= 64)
-    throw new import_errors6.WorkflowContractError(
+    throw new import_errors8.WorkflowContractError(
       "A node may call at most 64 child workflows per activation."
     );
   ctx.workflowCallIds.add(args.id);
@@ -3073,7 +3510,7 @@ async function runWorkflowCall(args, task) {
   if (!record) ctx.node.consumeExecution?.("maxChildInvocations");
   record ??= {
     fingerprint,
-    invocationId: (0, import_node_crypto5.randomUUID)(),
+    invocationId: (0, import_node_crypto6.randomUUID)(),
     status: "running",
     interrupts: [],
     ...task.group ? { parallelKey: task.group.key } : {}
@@ -3083,7 +3520,7 @@ async function runWorkflowCall(args, task) {
   if (!task.group) ctx.workflowCallActive = true;
   const telemetry = ctx.node.workflowCallTelemetry;
   const activationKey = "__useWorkflowActivation";
-  ctx.currentNodeState.byKey[activationKey] ??= (0, import_node_crypto5.randomUUID)();
+  ctx.currentNodeState.byKey[activationKey] ??= (0, import_node_crypto6.randomUUID)();
   const callerNodeExecutionId = ctx.currentNodeState.byKey[activationKey];
   const metadata = {
     invocationId: record.invocationId,
@@ -3127,7 +3564,7 @@ async function runWorkflowCall(args, task) {
         workflow,
         record.error ?? "child failed",
         void 0,
-        record.failure ?? (0, import_errors6.serializeFailure)(void 0)
+        record.failure ?? (0, import_errors8.serializeFailure)(void 0)
       );
     if (task.group && record.status === "interrupted" && record.interrupts.at(-1)?.response === void 0)
       throw new ParallelChildWaiting();
@@ -3151,9 +3588,9 @@ async function runWorkflowCall(args, task) {
       } catch (error) {
         const child = error;
         recordUsage(child?.__kortyxChildUsage);
-        (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
-        if ((0, import_core7.isExecutionCancelled)(error)) throw error;
-        if ((0, import_core7.isExecutionLimitReached)(error)) {
+        (0, import_core8.throwIfExecutionAborted)(ctx.node.abortSignal);
+        if ((0, import_core8.isExecutionCancelled)(error)) throw error;
+        if ((0, import_core8.isExecutionLimitReached)(error)) {
           if (child?.__kortyxChildSnapshot)
             record.snapshot = child.__kortyxChildSnapshot;
           report("suspended", {
@@ -3163,7 +3600,7 @@ async function runWorkflowCall(args, task) {
           throw error;
         }
         record.status = "failed";
-        record.failure = (0, import_errors6.serializeFailure)(error);
+        record.failure = (0, import_errors8.serializeFailure)(error);
         record.error = record.failure.message;
         report("failed", { error: "Child workflow failed" });
         throw new WorkflowCallError(
@@ -3173,12 +3610,15 @@ async function runWorkflowCall(args, task) {
           record.failure
         );
       }
-      (0, import_core7.throwIfExecutionAborted)(ctx.node.abortSignal);
+      (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)
+          rememberToolObservation(observation);
         delete record.snapshot;
         report(
           "completed",
@@ -3201,8 +3641,12 @@ async function runWorkflowCall(args, task) {
         });
       }
     }
-    if (cached)
+    if (cached) {
       report("reused", workflowCallContent(telemetry, "output", record.data));
+      if (record.restoredToolBranch !== telemetry?.correlation?.branchId)
+        await replayToolObservations(record.toolObservations ?? [], true);
+      delete record.restoredToolBranch;
+    }
     const data = record.data ?? {};
     return {
       data: JSON.parse(JSON.stringify(data))
@@ -3226,6 +3670,7 @@ async function runWorkflowCall(args, task) {
   useReason,
   useRuntimeContext,
   useStructuredData,
+  useTool,
   useWorkflow,
   useWorkflowState,
   workflowCallFingerprint