@kortyx/hooks 0.19.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.22.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.21.0...hooks-v0.22.0) (2026-09-11)
+
+
+### Features
+
+* complete client responses while workflows continue in background ([#165](https://github.com/kortyx-io/kortyx/issues/165)) ([a8a08cd](https://github.com/kortyx-io/kortyx/commit/a8a08cd1e9533e4b44efa4af54a2d2cec54431ae))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/telemetry-contracts bumped to 0.5.0
+
+## [0.21.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.20.0...hooks-v0.21.0) (2026-09-10)
+
+
+### Features
+
+* **runtime:** add shared execution limits and checkpoint continuation ([#163](https://github.com/kortyx-io/kortyx/issues/163)) ([e22232c](https://github.com/kortyx-io/kortyx/commit/e22232c059fae4f7df1bd36423902bd365887942))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.8.0
+    * @kortyx/telemetry-contracts bumped to 0.4.0
+
+## [0.20.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.19.0...hooks-v0.20.0) (2026-09-10)
+
+
+### Features
+
+* cancel workflow trees and reflect cancellation in Studio ([#161](https://github.com/kortyx-io/kortyx/issues/161)) ([699ad18](https://github.com/kortyx-io/kortyx/commit/699ad18905955c6340c3d85b9fae7f0bffd00a0d))
+* execute and resume workflows without chat transport ([#159](https://github.com/kortyx-io/kortyx/issues/159)) ([6decb17](https://github.com/kortyx-io/kortyx/commit/6decb1714fedc021ac9e125b6ed9f75475ed928a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.7.0
+
 ## [0.19.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.18.0...hooks-v0.19.0) (2026-09-09)
 
 

package/dist/index.d.ts

@@ -1,10 +1,18 @@
-import { WorkflowDefinition, TokenUsage, InterruptInput, NodeConfig, InterruptResult, GraphState } from '@kortyx/core';
+import * as _kortyx_core from '@kortyx/core';
+import { WorkflowDefinition, TokenUsage, InterruptInput, GraphState, NodeConfig, InterruptResult } from '@kortyx/core';
 import { K as KortyxTelemetryConfig, R as ReasonTraceAdapter, a as KortyxTraceMetadata, b as KortyxTelemetryEventType } from './tracing-BI6YKHSf.js';
 export { E as EnsureWorkflowTopologyRequest, c as EnsureWorkflowTopologyResponse, d as KortyxTelemetryContentCapture, e as KortyxTelemetryCorrelation, f as KortyxTelemetryEvent, g as KortyxTelemetryPrompt, h as KortyxTelemetryReporter, i as KortyxTelemetryService, j as KortyxTraceAdapter, k as ReasonTraceAttributes, l as ReasonTraceSpan, m as ReasonTraceSpanEndArgs, n as ReasonTraceSpanStartArgs } from './tracing-BI6YKHSf.js';
 import { z } from 'zod';
 import { ProviderModelRef, KortyxReasoningOptions, KortyxResponseFormat, KortyxExecutableTool, KortyxUsage, KortyxFinishReason, KortyxProviderMetadata, KortyxWarning, KortyxToolCall, KortyxToolResult } from '@kortyx/providers';
 import '@kortyx/telemetry-contracts';
 
+type CompleteResponseOptions = {
+    message?: string | undefined;
+    data?: unknown;
+};
+/** Finish client delivery, leaving the node and workflow execution running. */
+declare function completeResponse(options?: CompleteResponseOptions): Promise<void>;
+
 type WorkflowCallOutcome = {
     status: "completed";
     data: Record<string, unknown>;
@@ -13,6 +21,7 @@ type WorkflowCallOutcome = {
     status: "interrupted";
     request: InterruptInput;
     snapshot: unknown;
+    usage?: TokenUsage | undefined;
 };
 type WorkflowCallService = (args: {
     id: string;
@@ -60,6 +69,10 @@ declare function useWorkflow(args: {
 }>;
 
 type HookNodeRuntimeContext = {
+    completeResponse?: ((options: CompleteResponseOptions, state: GraphState) => Promise<void>) | undefined;
+    /** Transient execution control; never part of checkpointed state. */
+    abortSignal?: AbortSignal | undefined;
+    consumeExecution?: ((limit: _kortyx_core.ExecutionLimit) => void) | undefined;
     graph: {
         name: string;
         node: string;
@@ -214,6 +227,8 @@ type StateSetter<T> = (next: T | ((prev: T) => T)) => void;
 declare function useStructuredData<TData = unknown>(args: UseStructuredDataArgs<TData>): void;
 declare function useReason<TOutput = unknown, TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseReasonArgs<TOutput, TRequest, TResponse>): Promise<UseReasonResult<TOutput, TResponse>>;
 declare function useInterrupt<TRequest extends InterruptInput = InterruptInput, TResponse = InterruptResult>(args: UseInterruptArgs<TRequest, TResponse>): Promise<TResponse>;
+/** Live execution signal for cooperative I/O. Never store it in workflow state. */
+declare function useAbortSignal(): AbortSignal | undefined;
 declare function useRuntimeContext<TContext extends Record<string, unknown> = Record<string, unknown>>(): TContext;
 declare function useNodeState<T>(initialValue: T): [T, StateSetter<T>];
 declare function useWorkflowState<T>(key: string, ...rest: [] | [T]): [T, StateSetter<T>];
@@ -221,4 +236,4 @@ declare function useWorkflowState<T>(key: string, ...rest: [] | [T]): [T, StateS
 /** Best effort lifecycle facts. Engine snapshots and interrupt tokens never leave the runtime. */
 declare function emitWorkflowCall(telemetry: KortyxTelemetryConfig | undefined, type: KortyxTelemetryEventType, payload: Record<string, unknown>): void;
 
-export { type HookRuntimeContext, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, createWorkflowHooks, emitWorkflowCall, runWithHookContext, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflow, useWorkflowState, workflowCallFingerprint };
+export { type CompleteResponseOptions, type HookRuntimeContext, KortyxTelemetryConfig, KortyxTelemetryEventType, KortyxTraceMetadata, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, WorkflowCallError, type WorkflowCallOutcome, type WorkflowCallService, completeResponse, createWorkflowHooks, emitWorkflowCall, runWithHookContext, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflow, useWorkflowState, workflowCallFingerprint };

package/dist/index.js

@@ -20,9 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   WorkflowCallError: () => WorkflowCallError,
+  completeResponse: () => completeResponse,
   createWorkflowHooks: () => createWorkflowHooks,
   emitWorkflowCall: () => emitWorkflowCall,
   runWithHookContext: () => runWithHookContext,
+  useAbortSignal: () => useAbortSignal,
   useInterrupt: () => useInterrupt,
   useNodeState: () => useNodeState,
   useReason: () => useReason2,
@@ -34,6 +36,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/complete-response.ts
+var import_zod = require("zod");
+
 // src/context.ts
 var import_node_async_hooks = require("async_hooks");
 var storage = new import_node_async_hooks.AsyncLocalStorage();
@@ -187,6 +192,33 @@ function getHookContext() {
   }
   return ctx;
 }
+function snapshotHookState() {
+  const ctx = getHookContext();
+  return {
+    ...ctx.state,
+    lastNode: ctx.node.graph.node,
+    runtime: { ...ctx.state.runtime, ...buildRuntimeStateUpdates(ctx) }
+  };
+}
+
+// src/complete-response.ts
+var optionsSchema = import_zod.z.object({
+  message: import_zod.z.string().optional(),
+  data: import_zod.z.json().optional()
+}).strict();
+async function completeResponse(options = {}) {
+  const ctx = getHookContext();
+  const parsed = optionsSchema.parse(options);
+  if (!ctx.node.completeResponse) {
+    throw new Error(
+      "completeResponse requires an agent-managed root workflow."
+    );
+  }
+  await ctx.node.completeResponse(parsed, snapshotHookState());
+}
+
+// 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}`;
@@ -243,6 +275,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,
@@ -276,6 +309,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");
 
@@ -370,9 +406,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 {
@@ -399,6 +437,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,
@@ -491,6 +530,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;
@@ -569,10 +609,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
@@ -599,8 +641,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;
   }
 }
 
@@ -614,6 +657,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,
@@ -621,7 +671,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,
@@ -807,7 +857,7 @@ var parseInterruptFirstPassResult = (args) => {
 };
 
 // src/reason/prompting.ts
-var import_zod = require("zod");
+var import_zod2 = require("zod");
 var tryStringify2 = (value) => {
   if (typeof value === "string") return value;
   try {
@@ -818,7 +868,7 @@ var tryStringify2 = (value) => {
 };
 var tryGetSchemaHint = (schema) => {
   try {
-    const hint = (0, import_zod.toJSONSchema)(schema);
+    const hint = (0, import_zod2.toJSONSchema)(schema);
     return JSON.stringify(hint, null, 2);
   } catch {
     return void 0;
@@ -1572,6 +1622,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,
@@ -1625,6 +1676,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;
@@ -1674,6 +1730,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
@@ -1691,6 +1748,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,
@@ -1724,6 +1782,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(
@@ -1791,10 +1850,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);
@@ -1814,6 +1876,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,
@@ -1937,6 +2002,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({
@@ -2306,6 +2378,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;
@@ -2350,6 +2425,7 @@ function useWorkflowState(key, ...rest) {
 
 // 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");
@@ -2436,6 +2512,7 @@ function createWorkflowHooks(workflows) {
 }
 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.");
@@ -2469,6 +2546,7 @@ async function useWorkflow(args) {
       workflow,
       "call input or target changed during replay"
     );
+  if (!record) ctx.node.consumeExecution?.("maxChildInvocations");
   record ??= {
     fingerprint,
     invocationId: (0, import_node_crypto5.randomUUID)(),
@@ -2502,6 +2580,15 @@ async function useWorkflow(args) {
       ...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) {
@@ -2530,14 +2617,28 @@ async function useWorkflow(args) {
           ...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;
-        accumulateTokenUsage(outcome.usage);
         workflowCallFingerprint(record.data);
         record.status = "completed";
         delete record.snapshot;
@@ -2574,9 +2675,11 @@ async function useWorkflow(args) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   WorkflowCallError,
+  completeResponse,
   createWorkflowHooks,
   emitWorkflowCall,
   runWithHookContext,
+  useAbortSignal,
   useInterrupt,
   useNodeState,
   useReason,