@kortyx/hooks 0.18.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [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)
+
+
+### 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,10 +1,70 @@
-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 * as _kortyx_core from '@kortyx/core';
+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;
+    usage?: TokenUsage | undefined;
+};
+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 = {
+    /** Transient execution control; never part of checkpointed state. */
+    abortSignal?: AbortSignal | undefined;
+    consumeExecution?: ((limit: _kortyx_core.ExecutionLimit) => void) | undefined;
     graph: {
         name: string;
         node: string;
@@ -12,6 +72,8 @@ type HookNodeRuntimeContext = {
     config: NodeConfig;
     emit: (event: string, payload: unknown) => void;
     awaitInterrupt: (args: InterruptInput) => InterruptResult;
+    callWorkflow?: WorkflowCallService;
+    workflowCallTelemetry?: KortyxTelemetryConfig | undefined;
 };
 type HookRuntimeContext = {
     node: HookNodeRuntimeContext;
@@ -157,8 +219,13 @@ 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>];
 
-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, useAbortSignal, useInterrupt, useNodeState, useReason, useRuntimeContext, useStructuredData, useWorkflow, useWorkflowState, workflowCallFingerprint };