@kortyx/hooks 0.18.0 → 0.21.0

package/dist/index.js

@@ -19,13 +19,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  WorkflowCallError: () => WorkflowCallError,
+  createWorkflowHooks: () => createWorkflowHooks,
+  emitWorkflowCall: () => emitWorkflowCall,
   runWithHookContext: () => runWithHookContext,
+  useAbortSignal: () => useAbortSignal,
   useInterrupt: () => useInterrupt,
   useNodeState: () => useNodeState,
   useReason: () => useReason2,
   useRuntimeContext: () => useRuntimeContext,
   useStructuredData: () => useStructuredData,
-  useWorkflowState: () => useWorkflowState
+  useWorkflow: () => useWorkflow,
+  useWorkflowState: () => useWorkflowState,
+  workflowCallFingerprint: () => workflowCallFingerprint
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -78,6 +84,8 @@ var createInternalContext = (ctx) => {
   const currentNodeState = storedNodeId && storedNodeId === nodeId ? normalizeNodeState(storedState) : { byIndex: [], byKey: {} };
   return {
     ...ctx,
+    workflowCallActive: false,
+    workflowCallIds: /* @__PURE__ */ new Set(),
     nodeStateIndex: 0,
     reasonCallIndex: 0,
     currentNodeState,
@@ -151,6 +159,12 @@ async function runWithHookContext(ctx, fn) {
   try {
     const result = await storage.run(internal, fn);
     cleanupCompletedReasonCheckpoints(internal);
+    for (const key of Object.keys(internal.currentNodeState.byKey)) {
+      if (key.startsWith("__useWorkflow:") || key === "__useWorkflowActivation") {
+        internal.currentNodeState.byKey[key] = null;
+        internal.stateDirty = true;
+      }
+    }
     return { result, runtimeUpdates: buildRuntimeStateUpdates(internal) };
   } catch (err) {
     const runtimeUpdates = buildRuntimeStateUpdates(internal);
@@ -175,6 +189,9 @@ function getHookContext() {
   return ctx;
 }
 
+// src/interrupt.ts
+var import_core = require("@kortyx/core");
+
 // 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) => {
@@ -230,6 +247,7 @@ var parseWithSchema = (schema, value, label) => {
 // src/interrupt.ts
 var awaitInterruptInternal = (args) => {
   const ctx = getHookContext();
+  (0, import_core.throwIfExecutionAborted)(ctx.node.abortSignal);
   const request = parseWithSchema(
     args.requestSchema,
     args.request,
@@ -248,7 +266,10 @@ var awaitInterruptInternal = (args) => {
     ...typeof args.id === "string" && args.id.length > 0 ? { id: args.id } : {},
     meta: {
       ...userMeta,
-      __kortyxResumeStatePatch: resumeStatePatch
+      __kortyxResumeStatePatch: {
+        ...resumeStatePatch,
+        ...ctx.tokenUsage ? { tokenUsage: ctx.tokenUsage } : {}
+      }
     }
   };
   const raw = ctx.node.awaitInterrupt(enrichedRequest);
@@ -260,6 +281,9 @@ var awaitInterruptInternal = (args) => {
   return Promise.resolve(response);
 };
 
+// src/reason/use-reason.ts
+var import_core5 = require("@kortyx/core");
+
 // src/structured.ts
 var import_node_crypto = require("crypto");
 
@@ -354,9 +378,11 @@ var shouldStreamStructured = (cfg) => Boolean(cfg) && (cfg?.stream ?? true);
 
 // src/reason/engine.ts
 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 toError = (value) => value instanceof Error ? value : new Error(String(value));
 var createRuntimeId = () => {
   try {
@@ -383,6 +409,7 @@ async function runReasonEngine(args) {
   const responseFormat = args.responseFormat ?? args.model.options?.responseFormat;
   const providerOptions = args.providerOptions ?? args.model.options?.providerOptions;
   const tools = args.tools ?? args.model.options?.tools;
+  (0, import_core2.throwIfExecutionAborted)(abortSignal);
   const model = args.model.provider.getModel(args.model.modelId, {
     ...temperature !== void 0 ? { temperature } : {},
     streaming: stream,
@@ -475,6 +502,7 @@ async function runReasonEngine(args) {
       }
       const response2 = await model.stream(messages);
       for await (const chunk of response2) {
+        (0, import_core2.throwIfExecutionAborted)(abortSignal);
         switch (chunk.type) {
           case "text-delta": {
             if (chunk.delta.length === 0) break;
@@ -553,10 +581,12 @@ async function runReasonEngine(args) {
         ...providerMetadata !== void 0 ? { providerMetadata } : {},
         ...warnings !== void 0 ? { warnings } : {}
       };
+      (0, import_core2.throwIfExecutionAborted)(abortSignal);
       endTrace(traceSpan, result2);
       return result2;
     }
     const response = await model.invoke(messages);
+    (0, import_core2.throwIfExecutionAborted)(abortSignal);
     if (emit) {
       emitNodeEvent(args.emitEvent, args.nodeId, "text-start", {
         ...commonMeta
@@ -583,8 +613,9 @@ async function runReasonEngine(args) {
     endTrace(traceSpan, result);
     return result;
   } catch (error) {
-    failTrace(traceSpan, error);
-    throw error;
+    const failure = abortSignal?.aborted ? (0, import_core2.createExecutionCancelledError)() : error;
+    failTrace(traceSpan, failure);
+    throw failure;
   }
 }
 
@@ -598,6 +629,13 @@ var createRuntimeId2 = () => {
 };
 async function reasonEngine(args, meta, inputOverride) {
   const ctx = getHookContext();
+  const abortSignal = (0, import_core3.combineAbortSignals)(
+    ctx.node.abortSignal,
+    args.abortSignal,
+    args.model.options?.abortSignal
+  );
+  (0, import_core3.throwIfExecutionAborted)(abortSignal);
+  ctx.node.consumeExecution?.("maxModelPasses");
   return runReasonEngine({
     model: args.model,
     input: inputOverride ?? args.input,
@@ -605,7 +643,7 @@ async function reasonEngine(args, meta, inputOverride) {
     temperature: args.temperature,
     maxOutputTokens: args.maxOutputTokens,
     stopSequences: args.stopSequences,
-    abortSignal: args.abortSignal,
+    abortSignal,
     reasoning: args.reasoning,
     responseFormat: args.responseFormat,
     providerOptions: args.providerOptions,
@@ -1556,6 +1594,7 @@ var extractStreamingStringValues = (args) => {
 };
 
 // src/reason/tools.ts
+var import_core4 = require("@kortyx/core");
 var toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 var toToolDefinitions = (tools) => tools.map((tool) => ({
   name: tool.name,
@@ -1609,6 +1648,11 @@ var createInitialMessages = (args) => [
 var runReasonToolLoop = async (args) => {
   const { useReasonArgs, id, opId, traceSpan } = args;
   const ctx = getHookContext();
+  const abortSignal = (0, import_core4.combineAbortSignals)(
+    ctx.node.abortSignal,
+    useReasonArgs.abortSignal,
+    useReasonArgs.model.options?.abortSignal
+  );
   const tools = useReasonArgs.tools ?? [];
   const toolByName = /* @__PURE__ */ new Map();
   let validationCompleted = false;
@@ -1658,6 +1702,7 @@ var runReasonToolLoop = async (args) => {
   };
   try {
     for (let stepIndex = 0; stepIndex < maxSteps; stepIndex += 1) {
+      (0, import_core4.throwIfExecutionAborted)(abortSignal);
       traceSpan?.addEvent?.("useReason.tool-step.start", {
         stepIndex,
         toolCount: toolDefinitions.length
@@ -1675,6 +1720,7 @@ var runReasonToolLoop = async (args) => {
       finalText = step.text;
       finalRaw = step.raw;
       aggregatedUsage = mergeUsage(aggregatedUsage, step.usage);
+      accumulateTokenUsage(step.usage);
       finalFinishReason = step.finishReason;
       aggregatedProviderMetadata = mergeProviderMetadata(
         aggregatedProviderMetadata,
@@ -1708,6 +1754,7 @@ var runReasonToolLoop = async (args) => {
         toolCalls
       });
       for (const toolCall of toolCalls) {
+        (0, import_core4.throwIfExecutionAborted)(abortSignal);
         const tool = toolByName.get(toolCall.name);
         if (!tool) {
           throw new Error(
@@ -1775,10 +1822,13 @@ var runReasonToolLoop = async (args) => {
           }
         }
         try {
+          (0, import_core4.throwIfExecutionAborted)(abortSignal);
+          ctx.node.consumeExecution?.("maxToolCalls");
           const rawResult = await tool.execute(toolCall.input, {
             toolCallId: toolCall.id,
-            ...useReasonArgs.abortSignal ? { abortSignal: useReasonArgs.abortSignal } : {}
+            ...abortSignal ? { abortSignal } : {}
           });
+          (0, import_core4.throwIfExecutionAborted)(abortSignal);
           const result2 = normalizeToolResult(toolCall, rawResult);
           toolResults.push(result2);
           allToolResults.push(result2);
@@ -1798,6 +1848,9 @@ var runReasonToolLoop = async (args) => {
             isError: Boolean(result2.isError)
           });
         } catch (error) {
+          (0, import_core4.throwIfExecutionAborted)(abortSignal);
+          if ((0, import_core4.isExecutionLimitReached)(error) || (0, import_core4.isExecutionCancelled)(error))
+            throw error;
           const result2 = {
             toolCallId: toolCall.id,
             name: tool.name,
@@ -1921,6 +1974,13 @@ var assertReasoningThoughtsCompatibility = (args) => {
 async function useReason(args) {
   assertReasoningThoughtsCompatibility(args);
   const ctx = getHookContext();
+  const abortSignal = (0, import_core5.combineAbortSignals)(
+    ctx.node.abortSignal,
+    args.abortSignal,
+    args.model.options?.abortSignal
+  );
+  (0, import_core5.throwIfExecutionAborted)(abortSignal);
+  args = { ...args, abortSignal };
   const id = typeof args.id === "string" && args.id.length > 0 ? args.id : void 0;
   const opId = createRuntimeId2();
   const checkpointKey = resolveReasonCheckpointKey({
@@ -2290,6 +2350,9 @@ function useReason2(args) {
 function useInterrupt(args) {
   return awaitInterruptInternal(args);
 }
+function useAbortSignal() {
+  return getHookContext().node.abortSignal;
+}
 function useRuntimeContext() {
   const ctx = getHookContext();
   const config = ctx.state.config;
@@ -2331,14 +2394,270 @@ function useWorkflowState(key, ...rest) {
   };
   return [getValue(), setValue];
 }
+
+// src/workflow.ts
+var import_node_crypto5 = require("crypto");
+var import_core6 = require("@kortyx/core");
+
+// 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 Error {
+  constructor(workflow, message) {
+    super(`Workflow '${workflow}': ${message}`);
+    this.workflow = workflow;
+    this.name = "WorkflowCallError";
+  }
+  workflow;
+};
+function workflowCallFingerprint(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const canonical = (v) => {
+    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 Error("Workflow input and output must be JSON serializable.");
+    }
+    if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype) {
+      throw new Error(
+        "Workflow input and output must contain plain JSON objects."
+      );
+    }
+    seen.add(v);
+    const result = Array.isArray(v) ? v.map(canonical) : Object.fromEntries(
+      Object.keys(v).sort().map((key) => [
+        key,
+        canonical(v[key])
+      ])
+    );
+    seen.delete(v);
+    return result;
+  };
+  return JSON.stringify(canonical(value));
+}
+function createWorkflowHooks(workflows) {
+  return {
+    useWorkflow: (args) => {
+      const workflow = workflows[args.workflow];
+      if (!workflow || workflow.id !== args.workflow)
+        throw new Error("Workflow registry keys must match definition ids.");
+      return useWorkflow({ ...args, workflow });
+    }
+  };
+}
+async function useWorkflow(args) {
+  const ctx = getHookContext();
+  (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+  const service = ctx.node.callWorkflow;
+  if (!service)
+    throw new Error("useWorkflow requires an agent workflow registry.");
+  if (!args.id.trim())
+    throw new Error("useWorkflow requires a stable, nonempty id.");
+  if (ctx.workflowCallActive)
+    throw new Error(
+      "Concurrent workflow calls are not supported; await each call."
+    );
+  if (ctx.workflowCallIds.has(args.id))
+    throw new Error(
+      `Duplicate workflow call id '${args.id}' in one node activation.`
+    );
+  if (ctx.workflowCallIds.size >= 64)
+    throw new Error(
+      "A node may call at most 64 child workflows per activation."
+    );
+  ctx.workflowCallIds.add(args.id);
+  const definition = typeof args.workflow === "string" ? void 0 : args.workflow;
+  const workflow = definition?.id ?? args.workflow;
+  const input = args.input;
+  const fingerprint = workflowCallFingerprint({
+    workflow,
+    input,
+    version: definition?.version ?? null
+  });
+  const key = `__useWorkflow:${args.id}`;
+  let record = ctx.currentNodeState.byKey[key];
+  if (record && record.fingerprint !== fingerprint)
+    throw new WorkflowCallError(
+      workflow,
+      "call input or target changed during replay"
+    );
+  if (!record) ctx.node.consumeExecution?.("maxChildInvocations");
+  record ??= {
+    fingerprint,
+    invocationId: (0, import_node_crypto5.randomUUID)(),
+    status: "running",
+    interrupts: []
+  };
+  ctx.currentNodeState.byKey[key] = record;
+  ctx.stateDirty = true;
+  ctx.workflowCallActive = true;
+  const telemetry = ctx.node.workflowCallTelemetry;
+  const activationKey = "__useWorkflowActivation";
+  ctx.currentNodeState.byKey[activationKey] ??= (0, import_node_crypto5.randomUUID)();
+  const callerNodeExecutionId = ctx.currentNodeState.byKey[activationKey];
+  const metadata = {
+    invocationId: record.invocationId,
+    parentInvocationId: telemetry?.correlation?.invocationId ?? null,
+    branchId: telemetry?.correlation?.branchId ?? telemetry?.correlation?.runId ?? "unknown",
+    callId: args.id,
+    callerNodeId: ctx.node.graph.node,
+    callerNodeExecutionId,
+    sourceWorkflowId: ctx.node.graph.name,
+    targetWorkflowId: workflow,
+    targetVersion: definition?.version ?? null
+  };
+  record.telemetry = metadata;
+  const report = (status, content = {}) => {
+    record.sequence = (record.sequence ?? 0) + 1;
+    emitWorkflowCall(telemetry, `workflow.call.${status}`, {
+      ...metadata,
+      sequence: record.sequence,
+      ...content
+    });
+  };
+  const recordUsage = (usage) => {
+    if (!usage) return;
+    accumulateTokenUsage({
+      input: usage.input - (record.usage?.input ?? 0),
+      output: usage.output - (record.usage?.output ?? 0),
+      total: usage.total - (record.usage?.total ?? 0)
+    });
+    record.usage = usage;
+  };
+  const cached = record.status === "completed";
+  try {
+    for (const interruption of record.interrupts) {
+      interruption.response = await awaitInterruptInternal({
+        request: interruption.request,
+        ...interruption.request.meta ? { meta: interruption.request.meta } : {}
+      });
+    }
+    if (record.status === "failed")
+      throw new WorkflowCallError(workflow, record.error ?? "child failed");
+    while (record.status !== "completed") {
+      let outcome;
+      try {
+        report(
+          record.snapshot ? "resumed" : "started",
+          workflowCallContent(telemetry, "input", input)
+        );
+        outcome = await service({
+          callerNodeExecutionId,
+          id: args.id,
+          workflow,
+          input,
+          definition,
+          invocationId: record.invocationId,
+          ...record.snapshot ? { snapshot: record.snapshot } : {},
+          ...record.interrupts.length ? { response: record.interrupts.at(-1)?.response } : {}
+        });
+      } catch (error) {
+        (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+        if ((0, import_core6.isExecutionCancelled)(error)) throw error;
+        if ((0, import_core6.isExecutionLimitReached)(error)) {
+          const child = error;
+          if (child.__kortyxChildSnapshot)
+            record.snapshot = child.__kortyxChildSnapshot;
+          recordUsage(child.__kortyxChildUsage);
+          report("suspended", {
+            reason: "limit_reached",
+            limit: error.limitReached
+          });
+          throw error;
+        }
+        record.status = "failed";
+        record.error = error instanceof Error ? error.message : String(error);
+        report("failed", { error: "Child workflow failed" });
+        throw new WorkflowCallError(workflow, record.error);
+      }
+      (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+      recordUsage(outcome.usage);
+      if (outcome.status === "completed") {
+        record.data = outcome.data;
+        workflowCallFingerprint(record.data);
+        record.status = "completed";
+        delete record.snapshot;
+        report(
+          "completed",
+          workflowCallContent(telemetry, "output", record.data)
+        );
+      } else {
+        record.status = "interrupted";
+        record.snapshot = outcome.snapshot;
+        report("suspended", {
+          leaf: outcome.request.meta?.workflowCall ?? null
+        });
+        const interruption = {
+          request: outcome.request
+        };
+        record.interrupts.push(interruption);
+        interruption.response = await awaitInterruptInternal({
+          request: interruption.request,
+          ...interruption.request.meta ? { meta: interruption.request.meta } : {}
+        });
+      }
+    }
+    if (cached)
+      report("reused", workflowCallContent(telemetry, "output", record.data));
+    const data = record.data ?? {};
+    return {
+      data: JSON.parse(JSON.stringify(data))
+    };
+  } finally {
+    ctx.workflowCallActive = false;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  WorkflowCallError,
+  createWorkflowHooks,
+  emitWorkflowCall,
   runWithHookContext,
+  useAbortSignal,
   useInterrupt,
   useNodeState,
   useReason,
   useRuntimeContext,
   useStructuredData,
-  useWorkflowState
+  useWorkflow,
+  useWorkflowState,
+  workflowCallFingerprint
 });
 //# sourceMappingURL=index.js.map