@kortyx/hooks 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.19.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.18.0...hooks-v0.19.0) (2026-09-09)
+
+
+### Features
+
+* add resumable child workflows and Studio inspection ([#157](https://github.com/kortyx-io/kortyx/issues/157)) ([542ba29](https://github.com/kortyx-io/kortyx/commit/542ba29b3b57217e6e5d98c1b409bbec5ce3261f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/core bumped to 0.6.0
+    * @kortyx/telemetry-contracts bumped to 0.3.0
+
 ## [0.18.0](https://github.com/kortyx-io/kortyx/compare/hooks-v0.17.1...hooks-v0.18.0) (2026-08-02)
 
 

package/README.md

@@ -53,3 +53,31 @@ Workarounds:
 ## License
 
 Apache-2.0. See [LICENSE](https://github.com/kortyx-io/kortyx/blob/main/LICENSE).
+
+
+## Child workflows
+
+Call a registered workflow from a node or custom hook and continue with its
+result:
+
+```ts
+const result = await useWorkflow({
+  id: "research",
+  workflow: researchWorkflow,
+  input: { topic: "AI agents" },
+});
+return { data: { summary: result.data.summary } };
+```
+
+The child defines `inputSchema` and `outputSchema` on `defineWorkflow`.
+Inputs and returned data are inferred from those schemas and validated at
+runtime. The result is the child's accumulated data parsed by its output
+schema. Use `createWorkflowHooks({ research: researchWorkflow })` for typed
+string ids. Register the same definitions with the agent.
+
+Calls need stable ids. A child interrupt pauses the chain; resuming replays
+the enclosing node and reuses saved child results. Keep effects before calls
+idempotent. Fork/rollback retain nested checkpoints; use Redis for persistence
+across server restarts. Concurrent calls are unsupported.
+
+See [the execution and replay contract](../../docs/design-specs/child-workflows.md).

package/dist/index.d.ts

@@ -1,9 +1,64 @@
-import { NodeConfig, InterruptInput, InterruptResult, GraphState } from '@kortyx/core';
-import { R as ReasonTraceAdapter, K as KortyxTraceMetadata } from './tracing-DeYHBpY1.js';
-export { E as EnsureWorkflowTopologyRequest, a as EnsureWorkflowTopologyResponse, b as KortyxTelemetryConfig, c as KortyxTelemetryContentCapture, d as KortyxTelemetryCorrelation, e as KortyxTelemetryEvent, f as KortyxTelemetryEventType, 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-DeYHBpY1.js';
+import { WorkflowDefinition, TokenUsage, InterruptInput, NodeConfig, InterruptResult, GraphState } 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 WorkflowCallOutcome = {
+    status: "completed";
+    data: Record<string, unknown>;
+    usage?: TokenUsage | undefined;
+} | {
+    status: "interrupted";
+    request: InterruptInput;
+    snapshot: unknown;
+};
+type WorkflowCallService = (args: {
+    id: string;
+    workflow: string;
+    input: unknown;
+    snapshot?: unknown;
+    definition?: WorkflowDefinition | undefined;
+    invocationId: string;
+    response?: string | string[] | undefined;
+    callerNodeExecutionId?: string | undefined;
+}) => Promise<WorkflowCallOutcome>;
+declare class WorkflowCallError extends Error {
+    readonly workflow: string;
+    constructor(workflow: string, message: string);
+}
+declare function workflowCallFingerprint(value: unknown): string;
+type SchematizedWorkflow = WorkflowDefinition & {
+    inputSchema: z.ZodType;
+    outputSchema: z.ZodType<Record<string, unknown>>;
+};
+/** Bind string workflow ids to the same definitions registered with the agent. */
+declare function createWorkflowHooks<const W extends Record<string, SchematizedWorkflow>>(workflows: W): {
+    useWorkflow: <K extends keyof W & string>(args: {
+        id: string;
+        workflow: K;
+        input: z.input<W[K]["inputSchema"]>;
+    }) => Promise<{
+        data: z.output<W[K]["outputSchema"]>;
+    }>;
+};
+/** Typed references avoid caller-supplied result type assertions. */
+declare function useWorkflow<W extends SchematizedWorkflow>(args: {
+    id: string;
+    workflow: W;
+    input: z.input<W["inputSchema"]>;
+}): Promise<{
+    data: z.output<W["outputSchema"]>;
+}>;
+declare function useWorkflow(args: {
+    id: string;
+    workflow: string;
+    input: unknown;
+}): Promise<{
+    data: Record<string, unknown>;
+}>;
+
 type HookNodeRuntimeContext = {
     graph: {
         name: string;
@@ -12,6 +67,8 @@ type HookNodeRuntimeContext = {
     config: NodeConfig;
     emit: (event: string, payload: unknown) => void;
     awaitInterrupt: (args: InterruptInput) => InterruptResult;
+    callWorkflow?: WorkflowCallService;
+    workflowCallTelemetry?: KortyxTelemetryConfig | undefined;
 };
 type HookRuntimeContext = {
     node: HookNodeRuntimeContext;
@@ -161,4 +218,7 @@ declare function useRuntimeContext<TContext extends Record<string, unknown> = Re
 declare function useNodeState<T>(initialValue: T): [T, StateSetter<T>];
 declare function useWorkflowState<T>(key: string, ...rest: [] | [T]): [T, StateSetter<T>];
 
-export { type HookRuntimeContext, KortyxTraceMetadata, ReasonTraceAdapter, type UseInterruptArgs, type UseReasonArgs, type UseReasonResult, type UseReasonStep, type UseReasonToolExecution, type UseStructuredDataArgs, runWithHookContext, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflowState };
+/** 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 };

package/dist/index.js

@@ -19,13 +19,18 @@ 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,
   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 +83,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 +158,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);
@@ -248,7 +261,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);
@@ -2331,14 +2347,243 @@ function useWorkflowState(key, ...rest) {
   };
   return [getValue(), setValue];
 }
+
+// src/workflow.ts
+var import_node_crypto5 = require("crypto");
+
+// 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();
+  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"
+    );
+  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 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) {
+        record.status = "failed";
+        record.error = error instanceof Error ? error.message : String(error);
+        report("failed", { error: "Child workflow failed" });
+        throw new WorkflowCallError(workflow, record.error);
+      }
+      if (outcome.status === "completed") {
+        record.data = outcome.data;
+        accumulateTokenUsage(outcome.usage);
+        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,
   useInterrupt,
   useNodeState,
   useReason,
   useRuntimeContext,
   useStructuredData,
-  useWorkflowState
+  useWorkflow,
+  useWorkflowState,
+  workflowCallFingerprint
 });
 //# sourceMappingURL=index.js.map