@kortyx/hooks 0.9.0 → 0.10.0

package/dist/index.js

@@ -44,6 +44,20 @@ var normalizeNodeState = (value) => {
   return { byIndex: [], byKey: {} };
 };
 var cloneWorkflowState = (value) => isRecord(value) ? { ...value } : {};
+var cloneTokenUsage = (value) => {
+  if (!isRecord(value)) return void 0;
+  const input = typeof value.input === "number" ? value.input : void 0;
+  const output = typeof value.output === "number" ? value.output : void 0;
+  const total = typeof value.total === "number" ? value.total : void 0;
+  if (input === void 0 && output === void 0 && total === void 0) {
+    return void 0;
+  }
+  return {
+    input: input ?? 0,
+    output: output ?? 0,
+    total: total ?? 0
+  };
+};
 var getHookRuntimeState = (state) => {
   const runtime = state.runtime ?? {};
   const internal = isRecord(runtime.__kortyx) ? runtime.__kortyx : void 0;
@@ -67,21 +81,60 @@ var createInternalContext = (ctx) => {
     reasonCallIndex: 0,
     currentNodeState,
     workflowState: cloneWorkflowState(hookRuntimeState.workflowState),
-    dirty: false
+    tokenUsage: cloneTokenUsage(ctx.state.runtime?.tokenUsage),
+    stateDirty: false,
+    runtimeDirty: false
   };
 };
 var buildRuntimeStateUpdates = (ctx) => {
-  if (!ctx.dirty) return null;
-  return {
-    __kortyx: {
+  const updates = {};
+  if (ctx.stateDirty) {
+    updates.__kortyx = {
       nodeState: {
         nodeId: ctx.node.graph.node,
         state: ctx.currentNodeState
       },
       workflowState: ctx.workflowState
-    }
+    };
+  }
+  if (ctx.runtimeDirty && ctx.tokenUsage) {
+    updates.tokenUsage = ctx.tokenUsage;
+  }
+  return Object.keys(updates).length > 0 ? updates : null;
+};
+var toTokenUsageDelta = (usage) => {
+  if (!usage) return void 0;
+  const input = usage.input ?? 0;
+  const output = usage.output ?? 0;
+  const total = usage.total ?? input + output + (usage.reasoning ?? 0);
+  if (input === 0 && output === 0 && total === 0) {
+    return void 0;
+  }
+  return {
+    input,
+    output,
+    total
   };
 };
+function accumulateTokenUsage(usage) {
+  const delta = toTokenUsageDelta(usage);
+  if (!delta) return;
+  const ctx = getHookContext();
+  const current = ctx.tokenUsage ?? {
+    input: 0,
+    output: 0,
+    total: 0
+  };
+  ctx.tokenUsage = {
+    input: current.input + delta.input,
+    output: current.output + delta.output,
+    total: current.total + delta.total
+  };
+  ctx.runtimeDirty = true;
+}
+function getReasonTraceAdapter() {
+  return getHookContext().reasonTrace;
+}
 async function runWithHookContext(ctx, fn) {
   const internal = createInternalContext(ctx);
   try {
@@ -146,6 +199,25 @@ var awaitInterruptInternal = (args) => {
 
 // src/structured.ts
 var import_node_crypto = require("crypto");
+
+// src/structured-path.ts
+var parseStructuredPath = (path, source) => {
+  if (path.length === 0) {
+    throw new Error(`${source} path must be a non-empty dot-separated string.`);
+  }
+  const parts = path.split(".");
+  if (parts.some((part) => part.length === 0)) {
+    throw new Error(
+      `${source} path "${path}" must not contain empty segments.`
+    );
+  }
+  return parts;
+};
+var assertStructuredPath = (path, source) => {
+  parseStructuredPath(path, source);
+};
+
+// src/structured.ts
 var createStructuredStreamId = () => {
   try {
     return (0, import_node_crypto.randomUUID)();
@@ -166,6 +238,7 @@ var emitStructuredData = (args) => {
     ...typeof args.id === "string" && args.id.length > 0 ? { id: args.id } : {}
   };
   if (args.kind === "set") {
+    assertStructuredPath(args.path, "useStructuredData");
     const value = parseWithSchema(
       args.valueSchema,
       args.value,
@@ -180,6 +253,7 @@ var emitStructuredData = (args) => {
     return;
   }
   if (args.kind === "append") {
+    assertStructuredPath(args.path, "useStructuredData");
     const items = args.items.map(
       (item) => parseWithSchema(args.itemSchema, item, "useStructuredData append item")
     );
@@ -192,6 +266,7 @@ var emitStructuredData = (args) => {
     return;
   }
   if (args.kind === "text-delta") {
+    assertStructuredPath(args.path, "useStructuredData");
     ctx.node.emit("structured_data", {
       ...base,
       kind: "text-delta",
@@ -226,6 +301,12 @@ var readReasonCheckpoint = (raw) => {
     request: value.request,
     firstText: value.firstText,
     ...Object.hasOwn(value, "firstRaw") ? { firstRaw: value.firstRaw } : {},
+    ...Object.hasOwn(value, "firstUsage") ? { firstUsage: value.firstUsage } : {},
+    ...Object.hasOwn(value, "firstFinishReason") ? { firstFinishReason: value.firstFinishReason } : {},
+    ...Object.hasOwn(value, "firstProviderMetadata") ? {
+      firstProviderMetadata: value.firstProviderMetadata
+    } : {},
+    ...Object.hasOwn(value, "firstWarnings") ? { firstWarnings: value.firstWarnings } : {},
     ...Object.hasOwn(value, "firstOutput") ? { firstOutput: value.firstOutput } : {}
   };
 };
@@ -244,12 +325,7 @@ var import_node_crypto3 = require("crypto");
 
 // src/reason-engine.ts
 var import_node_crypto2 = require("crypto");
-var chunkToText = (chunk) => {
-  if (typeof chunk === "string") return chunk;
-  if (typeof chunk.text === "string") return chunk.text;
-  if (typeof chunk.content === "string") return chunk.content;
-  return "";
-};
+var toError = (value) => value instanceof Error ? value : new Error(String(value));
 var createRuntimeId = () => {
   try {
     return (0, import_node_crypto2.randomUUID)();
@@ -268,9 +344,21 @@ async function runReasonEngine(args) {
   const stream = args.stream ?? args.model.options?.streaming ?? true;
   const emit = args.emit ?? true;
   const temperature = args.temperature ?? args.model.options?.temperature ?? args.defaultTemperature;
-  const model = args.getProvider(args.model.providerId, args.model.modelId, {
+  const maxOutputTokens = args.maxOutputTokens ?? args.model.options?.maxOutputTokens;
+  const stopSequences = args.stopSequences ?? args.model.options?.stopSequences;
+  const abortSignal = args.abortSignal ?? args.model.options?.abortSignal;
+  const reasoning = args.reasoning ?? args.model.options?.reasoning;
+  const responseFormat = args.responseFormat ?? args.model.options?.responseFormat;
+  const providerOptions = args.providerOptions ?? args.model.options?.providerOptions;
+  const model = args.model.provider.getModel(args.model.modelId, {
     ...temperature !== void 0 ? { temperature } : {},
-    streaming: stream
+    streaming: stream,
+    ...maxOutputTokens !== void 0 ? { maxOutputTokens } : {},
+    ...stopSequences !== void 0 ? { stopSequences } : {},
+    ...abortSignal !== void 0 ? { abortSignal } : {},
+    ...reasoning !== void 0 ? { reasoning } : {},
+    ...responseFormat !== void 0 ? { responseFormat } : {},
+    ...providerOptions !== void 0 ? { providerOptions } : {}
   });
   const messages = [];
   if (typeof args.system === "string" && args.system.length > 0) {
@@ -284,59 +372,154 @@ async function runReasonEngine(args) {
     opId,
     segmentId
   };
-  if (stream) {
-    let final = "";
-    let raw;
+  const traceSpan = args.reasonTrace?.startSpan({
+    name: "runReasonEngine",
+    attributes: {
+      ...commonMeta,
+      providerId: args.model.provider.id,
+      modelId: args.model.modelId,
+      stream,
+      emit,
+      ...typeof args.nodeId === "string" && args.nodeId.length > 0 ? { nodeId: args.nodeId } : {}
+    }
+  });
+  const endTrace = (span, result) => {
+    span?.end?.({
+      ...result.usage !== void 0 ? { usage: result.usage } : {},
+      ...result.finishReason !== void 0 ? { finishReason: result.finishReason } : {},
+      ...result.providerMetadata !== void 0 ? { providerMetadata: result.providerMetadata } : {},
+      ...result.warnings !== void 0 ? { warnings: result.warnings } : {},
+      attributes: {
+        textLength: result.text.length
+      }
+    });
+  };
+  const failTrace = (span, error) => {
+    span?.fail?.(error, {
+      attributes: {
+        providerId: args.model.provider.id,
+        modelId: args.model.modelId
+      }
+    });
+  };
+  try {
+    if (stream) {
+      let final = "";
+      let raw;
+      let usage;
+      let finishReason;
+      let providerMetadata;
+      let warnings;
+      if (emit) {
+        emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
+          ...commonMeta
+        });
+      }
+      const response2 = await model.stream(messages);
+      for await (const chunk of response2) {
+        switch (chunk.type) {
+          case "text-delta": {
+            if (chunk.delta.length === 0) break;
+            final += chunk.delta;
+            args.onTextChunk?.(chunk.delta);
+            if (chunk.raw !== void 0) {
+              raw = chunk.raw;
+            }
+            if (chunk.providerMetadata !== void 0) {
+              providerMetadata = chunk.providerMetadata;
+            }
+            if (emit) {
+              emitNodeEvent(args.emitEvent, args.nodeId, "text-delta", {
+                ...commonMeta,
+                delta: chunk.delta
+              });
+            }
+            break;
+          }
+          case "finish": {
+            if (chunk.raw !== void 0) {
+              raw = chunk.raw;
+            }
+            if (chunk.usage !== void 0) {
+              usage = chunk.usage;
+            }
+            if (chunk.finishReason !== void 0) {
+              finishReason = chunk.finishReason;
+            }
+            if (chunk.providerMetadata !== void 0) {
+              providerMetadata = chunk.providerMetadata;
+            }
+            if (chunk.warnings !== void 0) {
+              warnings = chunk.warnings;
+            }
+            break;
+          }
+          case "raw": {
+            raw = chunk.raw;
+            if (chunk.providerMetadata !== void 0) {
+              providerMetadata = chunk.providerMetadata;
+            }
+            break;
+          }
+          case "error": {
+            if (chunk.raw !== void 0) {
+              raw = chunk.raw;
+            }
+            if (chunk.providerMetadata !== void 0) {
+              providerMetadata = chunk.providerMetadata;
+            }
+            if (chunk.warnings !== void 0) {
+              warnings = chunk.warnings;
+            }
+            throw toError(chunk.error);
+          }
+        }
+      }
+      if (emit) {
+        emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
+          ...commonMeta
+        });
+      }
+      const result2 = {
+        text: final,
+        ...raw !== void 0 ? { raw } : {},
+        ...usage !== void 0 ? { usage } : {},
+        ...finishReason !== void 0 ? { finishReason } : {},
+        ...providerMetadata !== void 0 ? { providerMetadata } : {},
+        ...warnings !== void 0 ? { warnings } : {}
+      };
+      endTrace(traceSpan, result2);
+      return result2;
+    }
+    const response = await model.invoke(messages);
     if (emit) {
       emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
         ...commonMeta
       });
-    }
-    const response2 = await model.stream(messages);
-    for await (const chunk of response2) {
-      const text = chunkToText(chunk);
-      if (!text) continue;
-      final += text;
-      args.onTextChunk?.(text);
-      if (typeof chunk === "object" && chunk && "raw" in chunk) {
-        raw = chunk.raw;
-      }
-      if (emit) {
+      if (response.content) {
         emitNodeEvent(args.emitEvent, args.nodeId, "text-delta", {
           ...commonMeta,
-          delta: text
+          delta: response.content
         });
       }
-    }
-    if (emit) {
       emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
         ...commonMeta
       });
     }
-    return {
-      text: final,
-      ...raw !== void 0 ? { raw } : {}
+    const result = {
+      text: response.content,
+      ...response.raw !== void 0 ? { raw: response.raw } : {},
+      ...response.usage !== void 0 ? { usage: response.usage } : {},
+      ...response.finishReason !== void 0 ? { finishReason: response.finishReason } : {},
+      ...response.providerMetadata !== void 0 ? { providerMetadata: response.providerMetadata } : {},
+      ...response.warnings !== void 0 ? { warnings: response.warnings } : {}
     };
+    endTrace(traceSpan, result);
+    return result;
+  } catch (error) {
+    failTrace(traceSpan, error);
+    throw error;
   }
-  const response = await model.invoke(messages);
-  if (emit) {
-    emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
-      ...commonMeta
-    });
-    if (response.content) {
-      emitNodeEvent(args.emitEvent, args.nodeId, "text-delta", {
-        ...commonMeta,
-        delta: response.content
-      });
-    }
-    emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
-      ...commonMeta
-    });
-  }
-  return {
-    text: response.content,
-    ...response.raw !== void 0 ? { raw: response.raw } : {}
-  };
 }
 
 // src/reason/engine.ts
@@ -349,22 +532,24 @@ var createRuntimeId2 = () => {
 };
 async function reasonEngine(args, meta, inputOverride) {
   const ctx = getHookContext();
-  const getProvider = ctx.getProvider;
-  if (!getProvider) {
-    throw new Error("useReason requires a provider factory in runtime config.");
-  }
   return runReasonEngine({
-    getProvider,
     model: args.model,
     input: inputOverride ?? args.input,
     system: args.system,
     temperature: args.temperature,
+    maxOutputTokens: args.maxOutputTokens,
+    stopSequences: args.stopSequences,
+    abortSignal: args.abortSignal,
+    reasoning: args.reasoning,
+    responseFormat: args.responseFormat,
+    providerOptions: args.providerOptions,
     defaultTemperature: ctx.node.config?.model?.temperature,
     stream: args.stream,
     emit: args.emit,
     onTextChunk: args.onTextChunk,
     nodeId: ctx.node.graph.node,
     emitEvent: ctx.node.emit,
+    reasonTrace: ctx.reasonTrace,
     id: meta.id,
     opId: meta.opId
   });
@@ -374,8 +559,11 @@ async function reasonEngine(args, meta, inputOverride) {
 var tryJsonParse = (value) => {
   try {
     return { ok: true, value: JSON.parse(value) };
-  } catch {
-    return { ok: false };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
   }
 };
 var extractJsonCodeBlock = (value) => {
@@ -405,9 +593,50 @@ var resolveOutputCandidate = (text) => {
   }
   return text;
 };
+var looksLikeStructuredJsonAttempt = (value) => {
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  return trimmed.startsWith("{") || trimmed.startsWith("[") || /^```(?:json)?/i.test(trimmed);
+};
+var isLikelyTruncatedStructuredOutput = (text) => {
+  const trimmed = text.trim();
+  if (!looksLikeStructuredJsonAttempt(trimmed)) return false;
+  const direct = tryJsonParse(trimmed);
+  if (!direct.ok && direct.error) return true;
+  const block = extractJsonCodeBlock(trimmed);
+  if (!block) return false;
+  const parsedBlock = tryJsonParse(block);
+  return !parsedBlock.ok && Boolean(parsedBlock.error);
+};
+var createTruncatedStructuredOutputError = (label) => new Error(
+  `${label} was truncated before producing valid structured output. The model stopped due to output length. Increase maxOutputTokens or simplify the requested output.`
+);
+var createInvalidStructuredOutputError = (label) => new Error(
+  `${label} did not produce valid structured output. The model returned text instead of the expected JSON payload. This often happens when output is truncated or the provider does not follow JSON mode. Increase maxOutputTokens or simplify the requested output.`
+);
+var parseReasonOutputWithSchema = (args) => {
+  const candidate = resolveOutputCandidate(args.text);
+  try {
+    return parseWithSchema(args.schema, candidate, args.label);
+  } catch (error) {
+    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
+      throw createTruncatedStructuredOutputError(args.label);
+    }
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      throw createInvalidStructuredOutputError(args.label);
+    }
+    throw error;
+  }
+};
 var parseInterruptFirstPassResult = (args) => {
   const candidate = resolveOutputCandidate(args.text);
   if (!isRecord2(candidate)) {
+    if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
+      throw createTruncatedStructuredOutputError("useReason output");
+    }
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      throw createInvalidStructuredOutputError("useReason output");
+    }
     throw new Error(
       "useReason first pass with interrupt must return a JSON object."
     );
@@ -429,11 +658,21 @@ var parseInterruptFirstPassResult = (args) => {
   let output;
   if (args.outputSchema) {
     const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
-    output = parseWithSchema(
-      args.outputSchema,
-      outputPayload,
-      "useReason output"
-    );
+    try {
+      output = parseWithSchema(
+        args.outputSchema,
+        outputPayload,
+        "useReason output"
+      );
+    } catch (error) {
+      if (args.finishReason?.unified === "length" || isLikelyTruncatedStructuredOutput(args.text)) {
+        throw createTruncatedStructuredOutputError("useReason output");
+      }
+      if (typeof outputPayload === "string" && outputPayload.trim().length > 0) {
+        throw createInvalidStructuredOutputError("useReason output");
+      }
+      throw error;
+    }
   }
   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) {
@@ -582,9 +821,10 @@ var resolveAppendFieldPaths = (cfg) => {
   if (!fields) return [];
   const appendPaths = Object.entries(fields).filter(([, mode]) => mode === "append").map(([path]) => path);
   for (const path of appendPaths) {
-    if (!path || path.includes(".")) {
+    assertStructuredPath(path, "useReason structured append");
+    if (path.includes(".")) {
       throw new Error(
-        "useReason structured append streaming currently supports top-level array fields only."
+        "useReason structured append streaming requires non-empty top-level array field keys."
       );
     }
   }
@@ -595,9 +835,10 @@ var resolveSetFieldPaths = (cfg) => {
   if (!fields) return [];
   const setPaths = Object.entries(fields).filter(([, mode]) => mode === "set").map(([path]) => path);
   for (const path of setPaths) {
-    if (!path || path.includes(".")) {
+    assertStructuredPath(path, "useReason structured set");
+    if (path.includes(".")) {
       throw new Error(
-        "useReason structured set streaming currently supports top-level fields only."
+        "useReason structured set streaming requires non-empty top-level field keys."
       );
     }
   }
@@ -608,9 +849,10 @@ var resolveTextDeltaFieldPaths = (cfg) => {
   if (!fields) return [];
   const textPaths = Object.entries(fields).filter(([, mode]) => mode === "text-delta").map(([path]) => path);
   for (const path of textPaths) {
-    if (!path || path.includes(".")) {
+    assertStructuredPath(path, "useReason structured text-delta");
+    if (path.includes(".")) {
       throw new Error(
-        "useReason structured text-delta streaming currently supports top-level string fields only."
+        "useReason structured text-delta streaming requires non-empty top-level string field keys."
       );
     }
   }
@@ -948,8 +1190,53 @@ var extractStreamingStringValue = (args) => {
 };
 
 // src/reason/use-reason.ts
+var mergeUsage = (left, right) => {
+  if (!left) return right;
+  if (!right) return left;
+  const sum = (a, b) => a === void 0 && b === void 0 ? void 0 : (a ?? 0) + (b ?? 0);
+  const raw = left.raw || right.raw ? {
+    ...left.raw ?? {},
+    ...right.raw ?? {}
+  } : void 0;
+  const input = sum(left.input, right.input);
+  const output = sum(left.output, right.output);
+  const total = sum(left.total, right.total);
+  const reasoning = sum(left.reasoning, right.reasoning);
+  const cacheRead = sum(left.cacheRead, right.cacheRead);
+  const cacheWrite = sum(left.cacheWrite, right.cacheWrite);
+  const merged = {};
+  if (input !== void 0) merged.input = input;
+  if (output !== void 0) merged.output = output;
+  if (total !== void 0) merged.total = total;
+  if (reasoning !== void 0) merged.reasoning = reasoning;
+  if (cacheRead !== void 0) merged.cacheRead = cacheRead;
+  if (cacheWrite !== void 0) merged.cacheWrite = cacheWrite;
+  if (raw) merged.raw = raw;
+  return merged;
+};
+var mergeWarnings = (left, right) => {
+  if (!left?.length) return right;
+  if (!right?.length) return left;
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const warning of [...left, ...right]) {
+    const key = JSON.stringify(warning);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(warning);
+  }
+  return merged;
+};
+var mergeProviderMetadata = (left, right) => {
+  if (!left) return right;
+  if (!right) return left;
+  return {
+    ...left,
+    ...right
+  };
+};
 var emitReasonStructuredOutput = (args) => {
-  if (!shouldEmitStructured(args.structured)) return;
+  if (!args.emit || !shouldEmitStructured(args.structured)) return;
   emitStructuredData({
     dataType: args.structured?.dataType ?? "reason-output",
     data: args.output,
@@ -960,7 +1247,19 @@ var emitReasonStructuredOutput = (args) => {
     streamId: args.opId
   });
 };
+var shouldEmitReasonStructured = (args) => (args.emit ?? true) && shouldEmitStructured(args.structured);
+var resolveEffectiveReasoningIncludeThoughts = (args) => args.reasoning?.includeThoughts ?? args.model.options?.reasoning?.includeThoughts ?? false;
+var resolveEffectiveResponseFormatType = (args) => args.responseFormat?.type ?? args.model.options?.responseFormat?.type;
+var assertReasoningThoughtsCompatibility = (args) => {
+  if (!resolveEffectiveReasoningIncludeThoughts(args)) return;
+  const usesStructuredOutput = Boolean(args.outputSchema) || Boolean(args.interrupt) || Boolean(args.structured) || resolveEffectiveResponseFormatType(args) === "json";
+  if (!usesStructuredOutput) return;
+  throw new Error(
+    "useReason does not support reasoning.includeThoughts with structured output, interrupt mode, or JSON responseFormat. Disable includeThoughts for this call."
+  );
+};
 async function useReason(args) {
+  assertReasoningThoughtsCompatibility(args);
   const ctx = getHookContext();
   const id = typeof args.id === "string" && args.id.length > 0 ? args.id : void 0;
   const opId = createRuntimeId2();
@@ -972,12 +1271,27 @@ async function useReason(args) {
     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,
+      hasOutputSchema: Boolean(args.outputSchema),
+      hasInterrupt: Boolean(args.interrupt),
+      hasStructured: Boolean(args.structured)
+    }
+  });
   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 && shouldEmitStructured(args.structured)
+    args.outputSchema && !args.interrupt && (setFieldPaths.length > 0 || appendFieldPaths.length > 0 || textDeltaFieldPaths.length > 0) && args.stream !== false && shouldEmitReasonStructured(args)
   );
   let firstText = "";
   let firstRaw;
@@ -986,6 +1300,10 @@ async function useReason(args) {
   let finalText = "";
   let finalRaw;
   let finalOutput;
+  let aggregatedUsage;
+  let finalFinishReason;
+  let aggregatedProviderMetadata;
+  let aggregatedWarnings;
   const emittedSetValues = /* @__PURE__ */ new Map();
   const emittedAppendCounts = /* @__PURE__ */ new Map();
   const emittedTextValues = /* @__PURE__ */ new Map();
@@ -996,6 +1314,13 @@ async function useReason(args) {
     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(
       {
@@ -1090,10 +1415,23 @@ async function useReason(args) {
     );
     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 } : {},
         ...args.outputSchema ? { outputSchema: args.outputSchema } : {}
       });
       firstText = firstPass.draftText;
@@ -1105,11 +1443,12 @@ async function useReason(args) {
       firstText = first.text;
       finalText = first.text;
       if (args.outputSchema) {
-        firstOutput = parseWithSchema(
-          args.outputSchema,
-          resolveOutputCandidate(first.text),
-          "useReason output"
-        );
+        firstOutput = parseReasonOutputWithSchema({
+          text: first.text,
+          schema: args.outputSchema,
+          ...first.finishReason ? { finishReason: first.finishReason } : {},
+          label: "useReason output"
+        });
       }
       finalOutput = firstOutput;
     }
@@ -1133,9 +1472,13 @@ async function useReason(args) {
         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.dirty = true;
+      ctx.stateDirty = true;
     }
     const resumeStatePatch = resolveHookStatePatch({
       nodeId: ctx.node.graph.node,
@@ -1153,9 +1496,12 @@ async function useReason(args) {
         __kortyxResumeStatePatch: resumeStatePatch
       }
     });
+    traceSpan?.addEvent?.("useReason.interrupt.resolved", {
+      checkpointKey
+    });
     if (Object.hasOwn(ctx.currentNodeState.byKey, checkpointKey)) {
       delete ctx.currentNodeState.byKey[checkpointKey];
-      ctx.dirty = true;
+      ctx.stateDirty = true;
     }
     const continuationInput = defaultContinuationInput({
       input: args.input,
@@ -1178,12 +1524,24 @@ async function useReason(args) {
     );
     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 = parseWithSchema(
-        args.outputSchema,
-        resolveOutputCandidate(finalText),
-        "useReason output"
-      );
+      finalOutput = parseReasonOutputWithSchema({
+        text: finalText,
+        schema: args.outputSchema,
+        ...second.finishReason ? { finishReason: second.finishReason } : {},
+        label: "useReason output"
+      });
     }
   }
   if (finalOutput !== void 0) {
@@ -1191,17 +1549,34 @@ async function useReason(args) {
       ...id ? { id } : {},
       opId,
       output: finalOutput,
-      structured: args.structured
+      structured: args.structured,
+      emit: args.emit ?? true
     });
   }
-  return {
+  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 } : {}
   };
+  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)
+    }
+  });
+  return result;
 }
 
 // src/hooks.ts
@@ -1220,14 +1595,14 @@ function useNodeState(initialValue) {
   const index = ctx.nodeStateIndex++;
   if (index >= nodeState.byIndex.length) {
     nodeState.byIndex[index] = initialValue;
-    ctx.dirty = true;
+    ctx.stateDirty = true;
   }
   const getValue = () => nodeState.byIndex[index];
   const setValue = (next) => {
     const prev = getValue();
     const resolved = typeof next === "function" ? next(prev) : next;
     nodeState.byIndex[index] = resolved;
-    ctx.dirty = true;
+    ctx.stateDirty = true;
   };
   return [getValue(), setValue];
 }
@@ -1238,14 +1613,14 @@ function useWorkflowState(key, ...rest) {
   const initialValue = rest[0];
   if (!Object.hasOwn(workflowState, key) && hasInitial) {
     workflowState[key] = initialValue;
-    ctx.dirty = true;
+    ctx.stateDirty = true;
   }
   const getValue = () => workflowState[key];
   const setValue = (next) => {
     const prev = getValue();
     const resolved = typeof next === "function" ? next(prev) : next;
     workflowState[key] = resolved;
-    ctx.dirty = true;
+    ctx.stateDirty = true;
   };
   return [getValue(), setValue];
 }