@kortyx/hooks 0.4.1 → 0.5.1

package/dist/index.js

@@ -20,11 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   runWithHookContext: () => runWithHookContext,
-  useAiInterrupt: () => useAiInterrupt,
   useAiMemory: () => useAiMemory,
   useEmit: () => useEmit,
+  useInterrupt: () => useInterrupt,
   useNodeState: () => useNodeState,
-  useReason: () => useReason,
+  useReason: () => useReason2,
   useStructuredData: () => useStructuredData,
   useWorkflowState: () => useWorkflowState
 });
@@ -65,6 +65,7 @@ var createInternalContext = (ctx) => {
   return {
     ...ctx,
     nodeStateIndex: 0,
+    reasonCallIndex: 0,
     currentNodeState,
     workflowState: cloneWorkflowState(hookMemory.workflowState),
     dirty: false
@@ -89,8 +90,15 @@ async function runWithHookContext(ctx, fn) {
     return { result, memoryUpdates: buildMemoryUpdates(internal) };
   } catch (err) {
     const memoryUpdates = buildMemoryUpdates(internal);
-    if (memoryUpdates && err && typeof err === "object") {
-      err.__kortyxMemoryUpdates = memoryUpdates;
+    if (memoryUpdates) {
+      const currentMemory = isRecord(internal.state.memory) ? internal.state.memory : {};
+      internal.state.memory = {
+        ...currentMemory,
+        ...memoryUpdates
+      };
+      if (err && typeof err === "object") {
+        err.__kortyxMemoryUpdates = memoryUpdates;
+      }
     }
     throw err;
   }
@@ -103,13 +111,111 @@ function getHookContext() {
   return ctx;
 }
 
+// src/validation.ts
+var parseWithSchema = (schema, value, label) => {
+  if (!schema) return value;
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const parsedError = "error" in parsed && parsed.error ? parsed.error : void 0;
+  const reason = typeof parsedError?.message === "string" && parsedError.message.length > 0 ? parsedError.message : "invalid payload";
+  throw new Error(`${label} validation failed: ${reason}`);
+};
+
+// src/interrupt.ts
+var awaitInterruptInternal = (args) => {
+  const ctx = getHookContext();
+  const request = parseWithSchema(
+    args.requestSchema,
+    args.request,
+    "useInterrupt request"
+  );
+  const enrichedRequest = {
+    ...request,
+    ...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 } : {},
+    ...args.meta && typeof args.meta === "object" && !Array.isArray(args.meta) ? { meta: args.meta } : {}
+  };
+  const raw = ctx.node.awaitInterrupt(enrichedRequest);
+  const response = parseWithSchema(
+    args.responseSchema,
+    raw,
+    "useInterrupt response"
+  );
+  return Promise.resolve(response);
+};
+
+// src/structured.ts
+var emitStructuredData = (args) => {
+  const ctx = getHookContext();
+  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 } : {},
+    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";
+};
+
+// src/reason/checkpoint.ts
+var resolveReasonCheckpointKey = (args) => typeof args.id === "string" && args.id.length > 0 ? `__useReason:${args.id}` : `__useReason:auto:${args.autoIndex}`;
+var readReasonCheckpoint = (raw) => {
+  if (!raw || typeof raw !== "object") return void 0;
+  const value = raw;
+  if (value.status !== "awaiting_interrupt") return void 0;
+  if (typeof value.firstText !== "string") return void 0;
+  if (!value.request || typeof value.request !== "object") return void 0;
+  return {
+    status: "awaiting_interrupt",
+    request: value.request,
+    firstText: value.firstText,
+    ...Object.hasOwn(value, "firstRaw") ? { firstRaw: value.firstRaw } : {},
+    ...Object.hasOwn(value, "firstOutput") ? { firstOutput: value.firstOutput } : {}
+  };
+};
+var resolveHookMemoryPatch = (args) => ({
+  __kortyx: {
+    nodeState: {
+      nodeId: args.nodeId,
+      state: args.currentNodeState
+    },
+    workflowState: args.workflowState
+  }
+});
+
+// src/reason/engine.ts
+var import_node_crypto2 = require("crypto");
+
 // src/reason-engine.ts
+var import_node_crypto = 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 createRuntimeId = () => {
+  try {
+    return (0, import_node_crypto.randomUUID)();
+  } catch {
+    return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  }
+};
 var emitNodeEvent = (emitEvent, nodeId, event, payload) => {
   if (!emitEvent) return;
   emitEvent(event, {
@@ -130,11 +236,20 @@ async function runReasonEngine(args) {
     messages.push({ role: "system", content: args.system });
   }
   messages.push({ role: "user", content: String(args.input ?? "") });
+  const opId = typeof args.opId === "string" && args.opId.length > 0 ? args.opId : createRuntimeId();
+  const segmentId = typeof args.segmentId === "string" && args.segmentId.length > 0 ? args.segmentId : createRuntimeId();
+  const commonMeta = {
+    ...typeof args.id === "string" && args.id.length > 0 ? { id: args.id } : {},
+    opId,
+    segmentId
+  };
   if (stream) {
     let final = "";
     let raw;
     if (emit) {
-      emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {});
+      emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
+        ...commonMeta
+      });
     }
     const response2 = await model.stream(messages);
     for await (const chunk of response2) {
@@ -146,12 +261,15 @@ async function runReasonEngine(args) {
       }
       if (emit) {
         emitNodeEvent(args.emitEvent, args.nodeId, "text-delta", {
+          ...commonMeta,
           delta: text
         });
       }
     }
     if (emit) {
-      emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {});
+      emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
+        ...commonMeta
+      });
     }
     return {
       text: final,
@@ -160,13 +278,18 @@ async function runReasonEngine(args) {
   }
   const response = await model.invoke(messages);
   if (emit) {
-    emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {});
+    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", {});
+    emitNodeEvent(args.emitEvent, args.nodeId, "text-end", {
+      ...commonMeta
+    });
   }
   return {
     text: response.content,
@@ -174,20 +297,15 @@ async function runReasonEngine(args) {
   };
 }
 
-// src/hooks.ts
-function useEmit() {
-  const ctx = getHookContext();
-  return ctx.node.emit;
-}
-function useStructuredData(args) {
-  const ctx = getHookContext();
-  ctx.node.emit("structured_data", {
-    node: ctx.node.graph.node,
-    ...typeof args.dataType === "string" && args.dataType.length > 0 ? { dataType: args.dataType } : {},
-    data: args.data
-  });
-}
-async function reasonEngine(args) {
+// src/reason/engine.ts
+var createRuntimeId2 = () => {
+  try {
+    return (0, import_node_crypto2.randomUUID)();
+  } catch {
+    return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  }
+};
+async function reasonEngine(args, meta, inputOverride) {
   const ctx = getHookContext();
   const getProvider = ctx.getProvider;
   if (!getProvider) {
@@ -196,18 +314,384 @@ async function reasonEngine(args) {
   return runReasonEngine({
     getProvider,
     model: args.model,
-    input: args.input,
+    input: inputOverride ?? args.input,
     system: args.system,
     temperature: args.temperature,
     defaultTemperature: ctx.node.config?.model?.temperature,
     stream: args.stream,
     emit: args.emit,
     nodeId: ctx.node.graph.node,
-    emitEvent: ctx.node.emit
+    emitEvent: ctx.node.emit,
+    id: meta.id,
+    opId: meta.opId
+  });
+}
+
+// src/reason/parsing.ts
+var tryJsonParse = (value) => {
+  try {
+    return { ok: true, value: JSON.parse(value) };
+  } catch {
+    return { ok: false };
+  }
+};
+var extractJsonCodeBlock = (value) => {
+  const match = value.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (!match || typeof match[1] !== "string") return null;
+  const inner = match[1].trim();
+  return inner.length > 0 ? inner : null;
+};
+var tryStringify = (value) => {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+};
+var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var resolveOutputCandidate = (text) => {
+  const trimmed = text.trim();
+  if (!trimmed) return text;
+  const direct = tryJsonParse(trimmed);
+  if (direct.ok) return direct.value;
+  const block = extractJsonCodeBlock(trimmed);
+  if (block) {
+    const parsedBlock = tryJsonParse(block);
+    if (parsedBlock.ok) return parsedBlock.value;
+  }
+  return text;
+};
+var parseInterruptFirstPassResult = (args) => {
+  const candidate = resolveOutputCandidate(args.text);
+  if (!isRecord2(candidate)) {
+    throw new Error(
+      "useReason first pass with interrupt must return a JSON object."
+    );
+  }
+  const requestCandidates = [
+    candidate.interruptRequest,
+    candidate.request,
+    candidate.interrupt,
+    candidate
+  ];
+  const requestPayload = requestCandidates.find(
+    (value) => value !== null && value !== void 0
+  );
+  const request = parseWithSchema(
+    args.requestSchema,
+    requestPayload,
+    "useReason interrupt.request"
+  );
+  let output;
+  if (args.outputSchema) {
+    const outputPayload = Object.hasOwn(candidate, "output") ? candidate.output : candidate;
+    output = parseWithSchema(
+      args.outputSchema,
+      outputPayload,
+      "useReason output"
+    );
+  }
+  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 Error(
+      "useReason first pass with interrupt requires `draftText` when outputSchema is not provided."
+    );
+  }
+  const draftText = explicitDraft ?? (output !== void 0 ? tryStringify(output) : String(args.text ?? ""));
+  return {
+    draftText,
+    request,
+    ...output !== void 0 ? { output } : {}
+  };
+};
+
+// src/reason/prompting.ts
+var import_zod = require("zod");
+var tryStringify2 = (value) => {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+};
+var tryGetSchemaHint = (schema) => {
+  try {
+    const hint = (0, import_zod.toJSONSchema)(schema);
+    return JSON.stringify(hint, null, 2);
+  } catch {
+    return void 0;
+  }
+};
+var withSchemaHint = (input, label, schema) => {
+  const hint = tryGetSchemaHint(schema);
+  if (!hint) return input;
+  return `${input}
+
+${label}:
+${hint}`;
+};
+var defaultInterruptFirstPassInput = (args) => {
+  const base = args.outputSchema ? [
+    args.input,
+    "Output rules:",
+    "- Return JSON only. No markdown fences.",
+    "- Return an object with keys: output, interruptRequest, draftText.",
+    "- output must match the expected output JSON schema.",
+    "- interruptRequest must match the expected interrupt request JSON schema.",
+    "- interruptRequest must be a non-null object.",
+    "- draftText should be a concise plain-language summary of output.",
+    "- If uncertain, still return a valid interruptRequest with safe default options."
+  ].join("\n\n") : [
+    args.input,
+    "Output rules:",
+    "- Return JSON only. No markdown fences.",
+    "- Return an object with keys: draftText, interruptRequest.",
+    "- draftText should be the current draft answer text.",
+    "- interruptRequest must match the expected interrupt request JSON schema.",
+    "- interruptRequest must be a non-null object.",
+    "- If uncertain, still return a valid interruptRequest with safe default options."
+  ].join("\n\n");
+  const withInterruptSchema = withSchemaHint(
+    base,
+    "Expected interrupt request JSON schema (for `interruptRequest`)",
+    args.requestSchema
+  );
+  if (!args.outputSchema) return withInterruptSchema;
+  const withOutputSchema = withSchemaHint(
+    withInterruptSchema,
+    "Expected output JSON schema (for `output`)",
+    args.outputSchema
+  );
+  return [
+    withOutputSchema,
+    "JSON template:",
+    '{ "output": { ... }, "interruptRequest": { ... }, "draftText": "..." }'
+  ].join("\n\n");
+};
+var defaultContinuationInput = (args) => [
+  "You are continuing a paused reasoning task after user input.",
+  "Update the previous result using the user response and return the final answer only.",
+  "If the previous output was JSON, return JSON in the same schema.",
+  "",
+  `Original request:
+${args.input}`,
+  `Draft answer text:
+${args.draftText}`,
+  `Draft output object:
+${tryStringify2(args.draftOutput ?? args.draftText)}`,
+  `Interrupt request shown to user:
+${tryStringify2(args.request)}`,
+  `User response:
+${tryStringify2(args.response)}`
+].join("\n\n");
+var withOutputGuardrails = (input, schema) => {
+  const base = [
+    input,
+    "Output rules:",
+    "- Return only JSON, no markdown fences.",
+    "- Ensure the response conforms to the expected output schema.",
+    "- Do not include explanatory text outside the JSON object."
+  ].join("\n\n");
+  return withSchemaHint(base, "Expected output JSON schema", schema);
+};
+
+// src/reason/use-reason.ts
+var emitReasonStructuredOutput = (args) => {
+  if (!shouldEmitStructured(args.structured)) return;
+  emitStructuredData({
+    dataType: args.structured?.dataType ?? "reason-output",
+    data: args.output,
+    mode: resolveStructuredMode(args.structured),
+    ...args.structured?.schemaId ? { schemaId: args.structured.schemaId } : {},
+    ...args.structured?.schemaVersion ? { schemaVersion: args.structured.schemaVersion } : {},
+    ...args.id ? { id: args.id } : {},
+    opId: args.opId
   });
+};
+async function useReason(args) {
+  const ctx = getHookContext();
+  const id = typeof args.id === "string" && args.id.length > 0 ? args.id : void 0;
+  const opId = createRuntimeId2();
+  const checkpointKey = resolveReasonCheckpointKey({
+    ...id ? { id } : {},
+    autoIndex: ctx.reasonCallIndex++
+  });
+  const existingCheckpoint = readReasonCheckpoint(
+    ctx.currentNodeState.byKey[checkpointKey]
+  );
+  const reasonMeta = typeof id === "string" ? { id, opId } : { opId };
+  const suppressTextStream = Boolean(args.outputSchema || args.interrupt);
+  let firstText = "";
+  let firstRaw;
+  let firstOutput;
+  let firstInterruptRequest;
+  let finalText = "";
+  let finalRaw;
+  let finalOutput;
+  if (existingCheckpoint) {
+    firstText = existingCheckpoint.firstText;
+    firstRaw = existingCheckpoint.firstRaw;
+    firstOutput = existingCheckpoint.firstOutput;
+    finalText = firstText;
+    finalRaw = firstRaw;
+    finalOutput = firstOutput;
+  } else {
+    const first = await reasonEngine(
+      {
+        ...args,
+        emit: suppressTextStream ? false : args.emit,
+        stream: suppressTextStream ? false : args.stream
+      },
+      reasonMeta,
+      args.interrupt ? defaultInterruptFirstPassInput({
+        input: args.input,
+        requestSchema: args.interrupt.requestSchema,
+        ...args.outputSchema ? { outputSchema: args.outputSchema } : {}
+      }) : args.outputSchema ? withOutputGuardrails(
+        args.input,
+        args.outputSchema
+      ) : void 0
+    );
+    firstRaw = first.raw;
+    finalRaw = first.raw;
+    if (args.interrupt) {
+      const firstPass = parseInterruptFirstPassResult({
+        text: first.text,
+        requestSchema: args.interrupt.requestSchema,
+        ...args.outputSchema ? { outputSchema: args.outputSchema } : {}
+      });
+      firstText = firstPass.draftText;
+      finalText = firstPass.draftText;
+      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;
+      if (args.outputSchema) {
+        firstOutput = parseWithSchema(
+          args.outputSchema,
+          resolveOutputCandidate(first.text),
+          "useReason output"
+        );
+        emitReasonStructuredOutput({
+          ...id ? { id } : {},
+          opId,
+          output: firstOutput,
+          structured: args.structured
+        });
+      }
+      finalOutput = firstOutput;
+    }
+  }
+  let interruptResponse;
+  if (args.interrupt) {
+    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 } : {},
+        ...firstOutput !== void 0 ? { firstOutput } : {}
+      };
+      ctx.dirty = true;
+    }
+    const resumeMemoryPatch = resolveHookMemoryPatch({
+      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: {
+        __kortyxResumeMemory: resumeMemoryPatch
+      }
+    });
+    if (Object.hasOwn(ctx.currentNodeState.byKey, checkpointKey)) {
+      delete ctx.currentNodeState.byKey[checkpointKey];
+      ctx.dirty = true;
+    }
+    const continuationInput = defaultContinuationInput({
+      input: args.input,
+      draftText: firstText,
+      ...firstOutput !== void 0 ? { draftOutput: firstOutput } : {},
+      request: interruptRequest,
+      response: interruptResponse
+    });
+    const second = await reasonEngine(
+      {
+        ...args,
+        emit: suppressTextStream ? false : args.emit,
+        stream: suppressTextStream ? false : args.stream
+      },
+      reasonMeta,
+      args.outputSchema ? withOutputGuardrails(
+        continuationInput,
+        args.outputSchema
+      ) : continuationInput
+    );
+    finalText = second.text;
+    finalRaw = second.raw;
+    if (args.outputSchema) {
+      finalOutput = parseWithSchema(
+        args.outputSchema,
+        resolveOutputCandidate(finalText),
+        "useReason output"
+      );
+      emitReasonStructuredOutput({
+        ...id ? { id } : {},
+        opId,
+        output: finalOutput,
+        structured: args.structured
+      });
+    }
+  }
+  return {
+    ...id ? { id } : {},
+    opId,
+    text: finalText,
+    ...finalRaw !== void 0 ? { raw: finalRaw } : {},
+    ...finalOutput !== void 0 ? { output: finalOutput } : {},
+    ...interruptResponse !== void 0 ? { interruptResponse } : {}
+  };
 }
-function useReason(args) {
-  return reasonEngine(args);
+
+// src/hooks.ts
+function useEmit() {
+  const ctx = getHookContext();
+  return ctx.node.emit;
+}
+function useStructuredData(args) {
+  emitStructuredData(args);
+}
+function useReason2(args) {
+  return useReason(args);
 }
 function useAiMemory() {
   const ctx = getHookContext();
@@ -216,9 +700,8 @@ function useAiMemory() {
   }
   return ctx.memoryAdapter;
 }
-function useAiInterrupt(input) {
-  const ctx = getHookContext();
-  return Promise.resolve(ctx.node.awaitInterrupt(input));
+function useInterrupt(args) {
+  return awaitInterruptInternal(args);
 }
 function useNodeState(keyOrInitial, initialValue) {
   const ctx = getHookContext();
@@ -273,9 +756,9 @@ function useWorkflowState(key, initialValue) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   runWithHookContext,
-  useAiInterrupt,
   useAiMemory,
   useEmit,
+  useInterrupt,
   useNodeState,
   useReason,
   useStructuredData,