@kortyx/hooks 0.7.0 → 0.9.0

package/dist/index.js

@@ -20,7 +20,6 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   runWithHookContext: () => runWithHookContext,
-  useAiMemory: () => useAiMemory,
   useInterrupt: () => useInterrupt,
   useNodeState: () => useNodeState,
   useReason: () => useReason2,
@@ -45,9 +44,9 @@ var normalizeNodeState = (value) => {
   return { byIndex: [], byKey: {} };
 };
 var cloneWorkflowState = (value) => isRecord(value) ? { ...value } : {};
-var getHookMemory = (state) => {
-  const memory = state.memory ?? {};
-  const internal = isRecord(memory.__kortyx) ? memory.__kortyx : void 0;
+var getHookRuntimeState = (state) => {
+  const runtime = state.runtime ?? {};
+  const internal = isRecord(runtime.__kortyx) ? runtime.__kortyx : void 0;
   const result = {};
   if (isRecord(internal?.nodeState)) result.nodeState = internal?.nodeState;
   if (isRecord(internal?.workflowState)) {
@@ -56,21 +55,22 @@ var getHookMemory = (state) => {
   return result;
 };
 var createInternalContext = (ctx) => {
-  const hookMemory = getHookMemory(ctx.state);
+  const hookRuntimeState = getHookRuntimeState(ctx.state);
   const nodeId = ctx.node.graph.node;
-  const storedNodeId = typeof hookMemory.nodeState?.nodeId === "string" ? String(hookMemory.nodeState?.nodeId) : "";
-  const storedState = hookMemory.nodeState?.state;
+  const storedNodeState = isRecord(hookRuntimeState.nodeState) ? hookRuntimeState.nodeState : void 0;
+  const storedNodeId = typeof storedNodeState?.nodeId === "string" ? String(storedNodeState.nodeId) : "";
+  const storedState = storedNodeState?.state;
   const currentNodeState = storedNodeId && storedNodeId === nodeId ? normalizeNodeState(storedState) : { byIndex: [], byKey: {} };
   return {
     ...ctx,
     nodeStateIndex: 0,
     reasonCallIndex: 0,
     currentNodeState,
-    workflowState: cloneWorkflowState(hookMemory.workflowState),
+    workflowState: cloneWorkflowState(hookRuntimeState.workflowState),
     dirty: false
   };
 };
-var buildMemoryUpdates = (ctx) => {
+var buildRuntimeStateUpdates = (ctx) => {
   if (!ctx.dirty) return null;
   return {
     __kortyx: {
@@ -86,17 +86,17 @@ async function runWithHookContext(ctx, fn) {
   const internal = createInternalContext(ctx);
   try {
     const result = await storage.run(internal, fn);
-    return { result, memoryUpdates: buildMemoryUpdates(internal) };
+    return { result, runtimeUpdates: buildRuntimeStateUpdates(internal) };
   } catch (err) {
-    const memoryUpdates = buildMemoryUpdates(internal);
-    if (memoryUpdates) {
-      const currentMemory = isRecord(internal.state.memory) ? internal.state.memory : {};
-      internal.state.memory = {
-        ...currentMemory,
-        ...memoryUpdates
+    const runtimeUpdates = buildRuntimeStateUpdates(internal);
+    if (runtimeUpdates) {
+      const currentRuntime = isRecord(internal.state.runtime) ? internal.state.runtime : {};
+      internal.state.runtime = {
+        ...currentRuntime,
+        ...runtimeUpdates
       };
       if (err && typeof err === "object") {
-        err.__kortyxMemoryUpdates = memoryUpdates;
+        err.__kortyxHookStatePatch = runtimeUpdates;
       }
     }
     throw err;
@@ -145,31 +145,73 @@ var awaitInterruptInternal = (args) => {
 };
 
 // src/structured.ts
+var import_node_crypto = require("crypto");
+var createStructuredStreamId = () => {
+  try {
+    return (0, import_node_crypto.randomUUID)();
+  } catch {
+    return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  }
+};
 var emitStructuredData = (args) => {
   const ctx = getHookContext();
+  const streamId = typeof args.streamId === "string" && args.streamId.length > 0 ? args.streamId : createStructuredStreamId();
+  const dataType = typeof args.dataType === "string" && args.dataType.length > 0 ? args.dataType : "generic";
+  const base = {
+    node: ctx.node.graph.node,
+    streamId,
+    dataType,
+    ...typeof args.schemaId === "string" && args.schemaId.length > 0 ? { schemaId: args.schemaId } : {},
+    ...typeof args.schemaVersion === "string" && args.schemaVersion.length > 0 ? { schemaVersion: args.schemaVersion } : {},
+    ...typeof args.id === "string" && args.id.length > 0 ? { id: args.id } : {}
+  };
+  if (args.kind === "set") {
+    const value = parseWithSchema(
+      args.valueSchema,
+      args.value,
+      "useStructuredData value"
+    );
+    ctx.node.emit("structured_data", {
+      ...base,
+      kind: "set",
+      path: args.path,
+      value
+    });
+    return;
+  }
+  if (args.kind === "append") {
+    const items = args.items.map(
+      (item) => parseWithSchema(args.itemSchema, item, "useStructuredData append item")
+    );
+    ctx.node.emit("structured_data", {
+      ...base,
+      kind: "append",
+      path: args.path,
+      items
+    });
+    return;
+  }
+  if (args.kind === "text-delta") {
+    ctx.node.emit("structured_data", {
+      ...base,
+      kind: "text-delta",
+      path: args.path,
+      delta: args.delta
+    });
+    return;
+  }
   const validated = parseWithSchema(
     args.dataSchema,
     args.data,
     "useStructuredData data"
   );
   ctx.node.emit("structured_data", {
-    node: ctx.node.graph.node,
-    ...typeof args.dataType === "string" && args.dataType.length > 0 ? { dataType: args.dataType } : {},
-    ...typeof args.mode === "string" ? { mode: args.mode } : {},
-    ...typeof args.schemaId === "string" && args.schemaId.length > 0 ? { schemaId: args.schemaId } : {},
-    ...typeof args.schemaVersion === "string" && args.schemaVersion.length > 0 ? { schemaVersion: args.schemaVersion } : {},
-    ...typeof args.id === "string" && args.id.length > 0 ? { id: args.id } : {},
-    ...typeof args.opId === "string" && args.opId.length > 0 ? { opId: args.opId } : {},
+    ...base,
+    kind: "final",
     data: validated
   });
 };
-var shouldEmitStructured = (cfg) => (cfg?.stream ?? "patch") !== "off";
-var resolveStructuredMode = (cfg) => {
-  const mode = cfg?.stream ?? "patch";
-  if (mode === "snapshot") return "snapshot";
-  if (mode === "patch") return "patch";
-  return "final";
-};
+var shouldEmitStructured = (cfg) => Boolean(cfg) && (cfg?.stream ?? true);
 
 // src/reason/checkpoint.ts
 var resolveReasonCheckpointKey = (args) => typeof args.id === "string" && args.id.length > 0 ? `__useReason:${args.id}` : `__useReason:auto:${args.autoIndex}`;
@@ -187,7 +229,7 @@ var readReasonCheckpoint = (raw) => {
     ...Object.hasOwn(value, "firstOutput") ? { firstOutput: value.firstOutput } : {}
   };
 };
-var resolveHookMemoryPatch = (args) => ({
+var resolveHookStatePatch = (args) => ({
   __kortyx: {
     nodeState: {
       nodeId: args.nodeId,
@@ -198,10 +240,10 @@ var resolveHookMemoryPatch = (args) => ({
 });
 
 // src/reason/engine.ts
-var import_node_crypto2 = require("crypto");
+var import_node_crypto3 = require("crypto");
 
 // src/reason-engine.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var chunkToText = (chunk) => {
   if (typeof chunk === "string") return chunk;
   if (typeof chunk.text === "string") return chunk.text;
@@ -210,7 +252,7 @@ var chunkToText = (chunk) => {
 };
 var createRuntimeId = () => {
   try {
-    return (0, import_node_crypto.randomUUID)();
+    return (0, import_node_crypto2.randomUUID)();
   } catch {
     return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   }
@@ -255,6 +297,7 @@ async function runReasonEngine(args) {
       const text = chunkToText(chunk);
       if (!text) continue;
       final += text;
+      args.onTextChunk?.(text);
       if (typeof chunk === "object" && chunk && "raw" in chunk) {
         raw = chunk.raw;
       }
@@ -299,7 +342,7 @@ async function runReasonEngine(args) {
 // src/reason/engine.ts
 var createRuntimeId2 = () => {
   try {
-    return (0, import_node_crypto2.randomUUID)();
+    return (0, import_node_crypto3.randomUUID)();
   } catch {
     return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   }
@@ -319,6 +362,7 @@ async function reasonEngine(args, meta, inputOverride) {
     defaultTemperature: ctx.node.config?.model?.temperature,
     stream: args.stream,
     emit: args.emit,
+    onTextChunk: args.onTextChunk,
     nodeId: ctx.node.graph.node,
     emitEvent: ctx.node.emit,
     id: meta.id,
@@ -495,6 +539,413 @@ var withOutputGuardrails = (input, schema) => {
   ].join("\n\n");
   return withSchemaHint(base, "Expected output JSON schema", schema);
 };
+var withStructuredStreamHints = (input, args) => {
+  const rules = [];
+  for (const path of args.setFieldPaths ?? []) {
+    rules.push(
+      `- For the top-level field \`${path}\`, write one stable final value and do not rewrite it after it is complete.`
+    );
+  }
+  for (const path of args.appendFieldPaths ?? []) {
+    rules.push(
+      `- For the top-level array field \`${path}\`, write items in final order and finish each item before starting the next.`
+    );
+    rules.push(
+      `- Once an item in \`${path}\` is complete, do not rewrite or reorder earlier items.`
+    );
+  }
+  for (const path of args.textDeltaFieldPaths ?? []) {
+    rules.push(
+      `- For the top-level string field \`${path}\`, write the value progressively by appending text to the end.`
+    );
+    rules.push(
+      `- Do not rewrite or replace the earlier prefix of \`${path}\` once emitted.`
+    );
+  }
+  if (rules.length === 0) return input;
+  return [
+    input,
+    "Streaming rules:",
+    ...rules,
+    "- Keep the overall response as valid JSON."
+  ].join("\n\n");
+};
+
+// src/reason/structured-stream.ts
+var escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var findTopLevelArrayStart = (text, path) => {
+  const match = new RegExp(`"${escapeRegex(path)}"\\s*:\\s*\\[`).exec(text);
+  return match ? match.index + match[0].length : -1;
+};
+var resolveAppendFieldPaths = (cfg) => {
+  const fields = cfg?.fields;
+  if (!fields) return [];
+  const appendPaths = Object.entries(fields).filter(([, mode]) => mode === "append").map(([path]) => path);
+  for (const path of appendPaths) {
+    if (!path || path.includes(".")) {
+      throw new Error(
+        "useReason structured append streaming currently supports top-level array fields only."
+      );
+    }
+  }
+  return appendPaths;
+};
+var resolveSetFieldPaths = (cfg) => {
+  const fields = cfg?.fields;
+  if (!fields) return [];
+  const setPaths = Object.entries(fields).filter(([, mode]) => mode === "set").map(([path]) => path);
+  for (const path of setPaths) {
+    if (!path || path.includes(".")) {
+      throw new Error(
+        "useReason structured set streaming currently supports top-level fields only."
+      );
+    }
+  }
+  return setPaths;
+};
+var resolveTextDeltaFieldPaths = (cfg) => {
+  const fields = cfg?.fields;
+  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(".")) {
+      throw new Error(
+        "useReason structured text-delta streaming currently supports top-level string fields only."
+      );
+    }
+  }
+  return textPaths;
+};
+var findTopLevelFieldValueStart = (text, path) => {
+  const match = new RegExp(`"${escapeRegex(path)}"\\s*:\\s*`).exec(text);
+  return match ? match.index + match[0].length : -1;
+};
+var findTopLevelStringStart = (text, path) => {
+  const match = new RegExp(`"${escapeRegex(path)}"\\s*:\\s*"`).exec(text);
+  return match ? match.index + match[0].length : -1;
+};
+var extractCompletedStringValueAt = (args) => {
+  let value = "";
+  for (let i = args.start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (ch === '"') {
+      return {
+        complete: true,
+        value
+      };
+    }
+    if (ch !== "\\") {
+      value += ch;
+      continue;
+    }
+    const next = args.text[i + 1];
+    if (!next) {
+      return {
+        complete: false
+      };
+    }
+    if (next === '"' || next === "\\" || next === "/" || next === "b" || next === "f" || next === "n" || next === "r" || next === "t") {
+      value += next === "b" ? "\b" : next === "f" ? "\f" : next === "n" ? "\n" : next === "r" ? "\r" : next === "t" ? "	" : next;
+      i += 1;
+      continue;
+    }
+    if (next === "u") {
+      const hex = args.text.slice(i + 2, i + 6);
+      if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+        return {
+          complete: false
+        };
+      }
+      value += String.fromCharCode(Number.parseInt(hex, 16));
+      i += 5;
+      continue;
+    }
+    return {
+      complete: false
+    };
+  }
+  return {
+    complete: false
+  };
+};
+var extractCompletedNestedValueAt = (args) => {
+  let inString = false;
+  let isEscaped = false;
+  let nesting = 0;
+  for (let i = args.start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (inString) {
+      if (isEscaped) {
+        isEscaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        isEscaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === args.opener) {
+      nesting += 1;
+      continue;
+    }
+    if (ch === args.closer) {
+      nesting -= 1;
+      if (nesting === 0) {
+        const raw = args.text.slice(args.start, i + 1);
+        try {
+          return {
+            complete: true,
+            value: JSON.parse(raw)
+          };
+        } catch {
+          return {
+            complete: false
+          };
+        }
+      }
+    }
+  }
+  return {
+    complete: false
+  };
+};
+var extractCompletedFieldValue = (args) => {
+  const start = findTopLevelFieldValueStart(args.text, args.path);
+  if (start < 0) {
+    return {
+      found: false,
+      complete: false
+    };
+  }
+  const first = args.text[start];
+  if (!first) {
+    return {
+      found: true,
+      complete: false
+    };
+  }
+  if (first === '"') {
+    const parsed = extractCompletedStringValueAt({
+      text: args.text,
+      start: start + 1
+    });
+    return parsed.complete ? {
+      found: true,
+      complete: true,
+      value: parsed.value
+    } : {
+      found: true,
+      complete: false
+    };
+  }
+  if (first === "{") {
+    const parsed = extractCompletedNestedValueAt({
+      text: args.text,
+      start,
+      opener: "{",
+      closer: "}"
+    });
+    return parsed.complete ? {
+      found: true,
+      complete: true,
+      value: parsed.value
+    } : {
+      found: true,
+      complete: false
+    };
+  }
+  if (first === "[") {
+    const parsed = extractCompletedNestedValueAt({
+      text: args.text,
+      start,
+      opener: "[",
+      closer: "]"
+    });
+    return parsed.complete ? {
+      found: true,
+      complete: true,
+      value: parsed.value
+    } : {
+      found: true,
+      complete: false
+    };
+  }
+  for (let i = start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (ch !== "," && ch !== "}") continue;
+    const raw = args.text.slice(start, i).trim();
+    if (!raw) {
+      return {
+        found: true,
+        complete: false
+      };
+    }
+    try {
+      return {
+        found: true,
+        complete: true,
+        value: JSON.parse(raw)
+      };
+    } catch {
+      return {
+        found: true,
+        complete: false
+      };
+    }
+  }
+  return {
+    found: true,
+    complete: false
+  };
+};
+var extractCompletedArrayItems = (args) => {
+  const start = findTopLevelArrayStart(args.text, args.path);
+  if (start < 0) return [];
+  const items = [];
+  let inString = false;
+  let isEscaped = false;
+  let nesting = 0;
+  let itemStart = -1;
+  for (let i = start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (inString) {
+      if (isEscaped) {
+        isEscaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        isEscaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      if (itemStart < 0) itemStart = i;
+      continue;
+    }
+    if (itemStart < 0) {
+      if (/\s/.test(ch) || ch === ",") continue;
+      if (ch === "]") break;
+      itemStart = i;
+      if (ch === "{" || ch === "[") {
+        nesting = 1;
+      } else {
+        nesting = 0;
+      }
+      continue;
+    }
+    if (ch === "{" || ch === "[") {
+      nesting += 1;
+      continue;
+    }
+    if (ch === "}" || ch === "]") {
+      if (nesting > 0) {
+        nesting -= 1;
+        if (nesting > 0) continue;
+      }
+      if (ch === "]") {
+        const raw = args.text.slice(itemStart, i).trim();
+        if (raw) {
+          try {
+            items.push(JSON.parse(raw));
+          } catch {
+          }
+        }
+        break;
+      }
+    }
+    if (nesting === 0 && (ch === "," || ch === "]")) {
+      const raw = args.text.slice(itemStart, i).trim();
+      if (raw) {
+        try {
+          items.push(JSON.parse(raw));
+        } catch {
+        }
+      }
+      itemStart = -1;
+      if (ch === "]") break;
+    }
+  }
+  return items;
+};
+var extractStreamingStringValue = (args) => {
+  const start = findTopLevelStringStart(args.text, args.path);
+  if (start < 0) {
+    return {
+      found: false,
+      complete: false,
+      value: ""
+    };
+  }
+  let value = "";
+  for (let i = start; i < args.text.length; i += 1) {
+    const ch = args.text[i];
+    if (ch === void 0) break;
+    if (ch === '"') {
+      return {
+        found: true,
+        complete: true,
+        value
+      };
+    }
+    if (ch !== "\\") {
+      value += ch;
+      continue;
+    }
+    const next = args.text[i + 1];
+    if (!next) {
+      return {
+        found: true,
+        complete: false,
+        value
+      };
+    }
+    if (next === '"' || next === "\\" || next === "/" || next === "b" || next === "f" || next === "n" || next === "r" || next === "t") {
+      value += next === "b" ? "\b" : next === "f" ? "\f" : next === "n" ? "\n" : next === "r" ? "\r" : next === "t" ? "	" : next;
+      i += 1;
+      continue;
+    }
+    if (next === "u") {
+      const hex = args.text.slice(i + 2, i + 6);
+      if (!/^[0-9a-fA-F]{4}$/.test(hex)) {
+        return {
+          found: true,
+          complete: false,
+          value
+        };
+      }
+      value += String.fromCharCode(Number.parseInt(hex, 16));
+      i += 5;
+      continue;
+    }
+    return {
+      found: true,
+      complete: false,
+      value
+    };
+  }
+  return {
+    found: true,
+    complete: false,
+    value
+  };
+};
 
 // src/reason/use-reason.ts
 var emitReasonStructuredOutput = (args) => {
@@ -502,11 +953,11 @@ var emitReasonStructuredOutput = (args) => {
   emitStructuredData({
     dataType: args.structured?.dataType ?? "reason-output",
     data: args.output,
-    mode: resolveStructuredMode(args.structured),
+    kind: "final",
     ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
     ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
     ...args.id ? { id: args.id } : {},
-    opId: args.opId
+    streamId: args.opId
   });
 };
 async function useReason(args) {
@@ -522,6 +973,12 @@ async function useReason(args) {
   );
   const reasonMeta = typeof id === "string" ? { id, opId } : { opId };
   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)
+  );
   let firstText = "";
   let firstRaw;
   let firstOutput;
@@ -529,6 +986,9 @@ async function useReason(args) {
   let finalText = "";
   let finalRaw;
   let finalOutput;
+  const emittedSetValues = /* @__PURE__ */ new Map();
+  const emittedAppendCounts = /* @__PURE__ */ new Map();
+  const emittedTextValues = /* @__PURE__ */ new Map();
   if (existingCheckpoint) {
     firstText = existingCheckpoint.firstText;
     firstRaw = existingCheckpoint.firstRaw;
@@ -541,7 +1001,78 @@ async function useReason(args) {
       {
         ...args,
         emit: suppressTextStream ? false : args.emit,
-        stream: suppressTextStream ? false : args.stream
+        stream: useStructuredIncrementalStreaming ? true : suppressTextStream ? false : args.stream,
+        ...useStructuredIncrementalStreaming ? {
+          onTextChunk: (delta) => {
+            firstText += delta;
+            finalText = firstText;
+            for (const path of setFieldPaths) {
+              const current = extractCompletedFieldValue({
+                text: firstText,
+                path
+              });
+              if (!current.found || !current.complete) continue;
+              const nextSerialized = JSON.stringify(current.value);
+              if (emittedSetValues.get(path) === nextSerialized) continue;
+              emittedSetValues.set(path, nextSerialized);
+              emitStructuredData({
+                kind: "set",
+                path,
+                value: current.value,
+                dataType: args.structured?.dataType ?? "reason-output",
+                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                ...id ? { id } : {},
+                streamId: opId
+              });
+            }
+            for (const path of appendFieldPaths) {
+              const items = extractCompletedArrayItems({
+                text: firstText,
+                path
+              });
+              const emittedAppendCount = emittedAppendCounts.get(path) ?? 0;
+              if (items.length <= emittedAppendCount) continue;
+              const nextItems = items.slice(emittedAppendCount);
+              emittedAppendCounts.set(path, items.length);
+              emitStructuredData({
+                kind: "append",
+                path,
+                items: nextItems,
+                dataType: args.structured?.dataType ?? "reason-output",
+                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                ...id ? { id } : {},
+                streamId: opId
+              });
+            }
+            for (const path of textDeltaFieldPaths) {
+              const current = extractStreamingStringValue({
+                text: firstText,
+                path
+              });
+              const emittedTextValue = emittedTextValues.get(path) ?? "";
+              if (!current.found || current.value.length <= emittedTextValue.length || !current.value.startsWith(emittedTextValue)) {
+                continue;
+              }
+              const nextDelta = current.value.slice(
+                emittedTextValue.length
+              );
+              emittedTextValues.set(path, current.value);
+              if (nextDelta.length === 0) continue;
+              emitStructuredData({
+                kind: "text-delta",
+                path,
+                delta: nextDelta,
+                dataType: args.structured?.dataType ?? "reason-output",
+                ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+                ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+                ...id ? { id } : {},
+                streamId: opId
+              });
+            }
+          }
+        } : {}
       },
       reasonMeta,
       args.interrupt ? defaultInterruptFirstPassInput({
@@ -549,7 +1080,11 @@ async function useReason(args) {
         requestSchema: args.interrupt.requestSchema,
         ...args.outputSchema ? { outputSchema: args.outputSchema } : {}
       }) : args.outputSchema ? withOutputGuardrails(
-        args.input,
+        withStructuredStreamHints(args.input, {
+          ...setFieldPaths.length > 0 ? { setFieldPaths } : {},
+          ...appendFieldPaths.length > 0 ? { appendFieldPaths } : {},
+          ...textDeltaFieldPaths.length > 0 ? { textDeltaFieldPaths } : {}
+        }),
         args.outputSchema
       ) : void 0
     );
@@ -566,14 +1101,6 @@ async function useReason(args) {
       firstInterruptRequest = firstPass.request;
       firstOutput = firstPass.output;
       finalOutput = firstPass.output;
-      if (firstOutput !== void 0) {
-        emitReasonStructuredOutput({
-          ...id ? { id } : {},
-          opId,
-          output: firstOutput,
-          structured: args.structured
-        });
-      }
     } else {
       firstText = first.text;
       finalText = first.text;
@@ -583,12 +1110,6 @@ async function useReason(args) {
           resolveOutputCandidate(first.text),
           "useReason output"
         );
-        emitReasonStructuredOutput({
-          ...id ? { id } : {},
-          opId,
-          output: firstOutput,
-          structured: args.structured
-        });
       }
       finalOutput = firstOutput;
     }
@@ -616,7 +1137,7 @@ async function useReason(args) {
       };
       ctx.dirty = true;
     }
-    const resumeMemoryPatch = resolveHookMemoryPatch({
+    const resumeStatePatch = resolveHookStatePatch({
       nodeId: ctx.node.graph.node,
       currentNodeState: ctx.currentNodeState,
       workflowState: ctx.workflowState
@@ -629,7 +1150,7 @@ async function useReason(args) {
       ...args.interrupt.schemaVersion ? { schemaVersion: args.interrupt.schemaVersion } : {},
       ...id ? { id } : {},
       meta: {
-        __kortyxResumeMemory: resumeMemoryPatch
+        __kortyxResumeStatePatch: resumeStatePatch
       }
     });
     if (Object.hasOwn(ctx.currentNodeState.byKey, checkpointKey)) {
@@ -663,14 +1184,16 @@ async function useReason(args) {
         resolveOutputCandidate(finalText),
         "useReason output"
       );
-      emitReasonStructuredOutput({
-        ...id ? { id } : {},
-        opId,
-        output: finalOutput,
-        structured: args.structured
-      });
     }
   }
+  if (finalOutput !== void 0) {
+    emitReasonStructuredOutput({
+      ...id ? { id } : {},
+      opId,
+      output: finalOutput,
+      structured: args.structured
+    });
+  }
   return {
     ...id ? { id } : {},
     opId,
@@ -688,13 +1211,6 @@ function useStructuredData(args) {
 function useReason2(args) {
   return useReason(args);
 }
-function useAiMemory() {
-  const ctx = getHookContext();
-  if (!ctx.memoryAdapter) {
-    throw new Error("useAiMemory requires a memory adapter in runtime config.");
-  }
-  return ctx.memoryAdapter;
-}
 function useInterrupt(args) {
   return awaitInterruptInternal(args);
 }
@@ -715,10 +1231,11 @@ function useNodeState(initialValue) {
   };
   return [getValue(), setValue];
 }
-function useWorkflowState(key, initialValue) {
+function useWorkflowState(key, ...rest) {
   const ctx = getHookContext();
   const workflowState = ctx.workflowState;
-  const hasInitial = arguments.length > 1;
+  const hasInitial = rest.length > 0;
+  const initialValue = rest[0];
   if (!Object.hasOwn(workflowState, key) && hasInitial) {
     workflowState[key] = initialValue;
     ctx.dirty = true;
@@ -735,7 +1252,6 @@ function useWorkflowState(key, initialValue) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   runWithHookContext,
-  useAiMemory,
   useInterrupt,
   useNodeState,
   useReason,