@kortyx/agent 0.16.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [0.19.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.18.0...agent-v0.19.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/runtime bumped to 0.15.0
+  * devDependencies
+    * @kortyx/hooks bumped to 0.22.0
+
+## [0.18.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.17.0...agent-v0.18.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/runtime bumped to 0.14.0
+    * @kortyx/stream bumped to 0.11.0
+  * devDependencies
+    * @kortyx/hooks bumped to 0.21.0
+
+## [0.17.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.16.0...agent-v0.17.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
+    * @kortyx/runtime bumped to 0.13.0
+    * @kortyx/stream bumped to 0.10.0
+  * devDependencies
+    * @kortyx/hooks bumped to 0.20.0
+
 ## [0.16.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.15.0...agent-v0.16.0) (2026-09-09)
 
 

package/dist/index.d.ts

@@ -1,13 +1,129 @@
-import { WorkflowDefinition, GraphState } from '@kortyx/core';
+import { WorkflowDefinition, ExecutionLimits, TokenUsage, ExecutionLimitReached, ExecutionBudget, GraphState } from '@kortyx/core';
 import { GetProviderFn } from '@kortyx/providers';
-import { CheckpointSummary, CheckpointId, SessionCheckpointRecord, RollbackSessionCheckpointResult, ForkSessionCheckpointResult, WorkflowRegistry, FrameworkAdapter, ExecutionRuntimeConfig, PendingRequestRecord } from '@kortyx/runtime';
+import { PendingRequestRecord, PendingRequestStore, CheckpointSummary, CheckpointId, SessionCheckpointRecord, RollbackSessionCheckpointResult, ForkSessionCheckpointResult, WorkflowRegistry, FrameworkAdapter, ExecutionRuntimeConfig } from '@kortyx/runtime';
 import { StreamChunk } from '@kortyx/stream';
+import { z } from 'zod';
+import * as _kortyx_hooks from '@kortyx/hooks';
 import { KortyxTelemetryConfig, EnsureWorkflowTopologyRequest } from '@kortyx/hooks';
 import { C as ChatMessage } from './browser-wjeg_MwV.js';
 export { S as StreamChatFromRouteArgs, s as streamChatFromRoute } from './browser-wjeg_MwV.js';
 import { StreamEvent } from '@langchain/core/tracers/log_stream';
 import '@kortyx/stream/browser';
 
+type ExecutableWorkflow = WorkflowDefinition & {
+    inputSchema: z.ZodType;
+    outputSchema: z.ZodType<Record<string, unknown>>;
+};
+/** Serializable identity of a waiting request. Treat tokens as private credentials. */
+type ResumeHandle = {
+    token: string;
+    requestId: string;
+    sessionId: string;
+    runId: string;
+};
+type ResumeResponse = {
+    type: "text";
+    text: string;
+} | {
+    type: "select";
+    ids: string[];
+} | {
+    type: "cancel";
+};
+type ExecutionInterrupt = {
+    workflow: string;
+    node: string;
+    input: PendingRequestRecord["schema"] & {
+        options: Array<{
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }>;
+    };
+};
+type ExecutionInfo = {
+    runId: string;
+    sessionId: string;
+    checkpointId?: string;
+    usage?: TokenUsage;
+};
+type ExecutionResult<T = Record<string, unknown>> = ExecutionInfo & ({
+    status: "completed";
+    data: T;
+} | {
+    status: "suspended";
+    reason?: "limit_reached";
+    limit?: ExecutionLimitReached;
+    interrupt: ExecutionInterrupt;
+    resume: ResumeHandle;
+} | {
+    status: "cancelled";
+    reason: string;
+} | {
+    status: "failed";
+    error: {
+        code: string;
+        message: string;
+    };
+});
+type ExecuteOptions<W extends ExecutableWorkflow> = {
+    limits?: ExecutionLimits;
+    abortSignal?: AbortSignal;
+    workflow: W;
+    input: z.input<W["inputSchema"]>;
+    sessionId?: string;
+    context?: Record<string, unknown>;
+};
+type ResumeOptions<W extends ExecutableWorkflow> = {
+    limits?: ExecutionLimits;
+    abortSignal?: AbortSignal;
+    workflow: W;
+    resume: ResumeHandle;
+    response: ResumeResponse;
+};
+/** The command was rejected before starting work or claiming an interrupt. */
+declare class ExecutionRequestError extends Error {
+    readonly code: string;
+    name: string;
+    constructor(code: string, message: string);
+}
+
+declare const scopeSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+}, z.core.$strict>;
+type InterruptScope = z.input<typeof scopeSchema>;
+type ListInterruptsOptions = InterruptScope & {
+    status?: "pending";
+    afterResponseCompleted?: boolean;
+};
+type PendingInterrupt = {
+    id: string;
+    status: "pending";
+    runId: string;
+    sessionId: string;
+    workflow: string;
+    node: string;
+    createdAt: string;
+    expiresAt: string;
+    afterResponseCompleted: boolean;
+    input: Omit<PendingRequestRecord["schema"], "meta"> & {
+        options: Array<{
+            id: string;
+            label: string;
+            description?: string;
+        }>;
+    };
+};
+type ResumableInterrupt = PendingInterrupt & {
+    resume: ResumeHandle;
+};
+declare function createInterruptDiscovery(store: PendingRequestStore): {
+    listInterrupts(options: ListInterruptsOptions): Promise<PendingInterrupt[]>;
+    getInterrupt(id: string, scope: InterruptScope): Promise<ResumableInterrupt | null>;
+};
+
 /** Produces the topology-only, deterministic Contract A snapshot. */
 declare const projectWorkflowTopology: (args: {
     workflow: WorkflowDefinition;
@@ -17,6 +133,10 @@ declare const projectWorkflowTopology: (args: {
 }) => EnsureWorkflowTopologyRequest;
 
 interface AgentProcessOptions {
+    executionSignal?: AbortSignal | undefined;
+    onExecution?: ((completion: Promise<void>) => void) | undefined;
+    limits?: ExecutionLimits | undefined;
+    abortSignal?: AbortSignal | undefined;
     sessionId?: string | undefined;
     workflowId?: string | undefined;
     context?: Record<string, unknown> | undefined;
@@ -27,6 +147,7 @@ interface AgentProjectTopologyOptions {
     service: AgentTopologySnapshot["service"];
 }
 interface CreateAgentArgs {
+    limits?: ExecutionLimits | undefined;
     getProvider?: GetProviderFn | undefined;
     workflows?: WorkflowDefinition[];
     workflowsDir?: string;
@@ -35,7 +156,24 @@ interface CreateAgentArgs {
     frameworkAdapter?: FrameworkAdapter;
     telemetry?: ExecutionRuntimeConfig["telemetry"];
 }
-interface Agent {
+interface Agent extends ReturnType<typeof createInterruptDiscovery> {
+    execute<W extends ExecutableWorkflow>(args: ExecuteOptions<W>): Promise<ExecutionResult<z.output<W["outputSchema"]>>>;
+    execute(args: {
+        limits?: ExecutionLimits;
+        abortSignal?: AbortSignal;
+        workflow: string;
+        input: unknown;
+        sessionId?: string;
+        context?: Record<string, unknown>;
+    }): Promise<ExecutionResult>;
+    resume<W extends ExecutableWorkflow>(args: ResumeOptions<W>): Promise<ExecutionResult<z.output<W["outputSchema"]>>>;
+    resume(args: {
+        limits?: ExecutionLimits;
+        abortSignal?: AbortSignal;
+        workflow: string;
+        resume: ResumeHandle;
+        response: ResumeResponse;
+    }): Promise<ExecutionResult>;
     projectTopology?: (options: AgentProjectTopologyOptions) => Promise<AgentTopologySnapshot[]>;
     streamChat: (messages: ChatMessage[], options?: AgentProcessOptions) => Promise<AsyncIterable<StreamChunk>>;
     listCheckpoints: (sessionId: string) => Promise<CheckpointSummary[]>;
@@ -71,10 +209,13 @@ type CheckpointRequestBody = {
 declare function parseChatRequestBody(value: unknown): ChatRequestBody;
 declare function parseCheckpointRequestBody(value: unknown): CheckpointRequestBody;
 declare function handleChatRequestBody(args: {
+    abortSignal?: AbortSignal | undefined;
+    onExecution?: ((completion: Promise<void>) => void) | undefined;
     agent: Agent;
     body: ChatRequestBody;
 }): Promise<Response>;
 declare function createChatRouteHandler(args: {
+    onExecution?: ((completion: Promise<void>) => void) | undefined;
     agent: Agent;
     errorStatus?: number | undefined;
 }): (request: Request) => Promise<Response>;
@@ -90,6 +231,11 @@ declare function createCheckpointRouteHandler(args: {
 type SelectWorkflowFn = (workflowId: string) => Promise<WorkflowDefinition>;
 type SaveMemoryFn = (sessionId: string, state: GraphState) => Promise<void>;
 interface CompiledGraphLike {
+    execution?: {
+        abortSignal?: AbortSignal | undefined;
+        budget?: ExecutionBudget | undefined;
+        completeResponse?: ((options: _kortyx_hooks.CompleteResponseOptions, state: GraphState) => Promise<void>) | undefined;
+    };
     config?: Record<string, unknown>;
     streamEvents: (state: GraphState, options?: {
         version?: string;
@@ -99,7 +245,19 @@ interface CompiledGraphLike {
         configurable?: Record<string, unknown>;
     }) => Promise<unknown>;
 }
+type OrchestrationOutcome = {
+    cancelled?: boolean;
+    state: GraphState;
+    pending?: PendingRequestRecord | undefined;
+    checkpointId?: string | undefined;
+    error?: unknown;
+};
 interface OrchestrateArgs {
+    executionSignal?: AbortSignal | undefined;
+    onExecution?: ((completion: Promise<void>) => void) | undefined;
+    abortSignal?: AbortSignal | undefined;
+    emitOutput?: boolean | undefined;
+    onOutcome?: ((outcome: OrchestrationOutcome) => void) | undefined;
     sessionId?: string;
     runId: string;
     graph: CompiledGraphLike;
@@ -113,7 +271,7 @@ interface OrchestrateArgs {
  * Orchestrates runtime execution with mid-stream transitions emitted by
  * runtime events.
  */
-declare function orchestrateGraphStream({ sessionId, runId, graph, state, config: initialConfig, selectWorkflow, knownWorkflowIds, frameworkAdapter, }: OrchestrateArgs): Promise<NodeJS.ReadableStream>;
+declare function orchestrateGraphStream({ sessionId, runId, graph, state, config: initialConfig, abortSignal: requestSignal, executionSignal, onExecution, emitOutput, onOutcome, selectWorkflow, knownWorkflowIds, frameworkAdapter, }: OrchestrateArgs): Promise<NodeJS.ReadableStream>;
 
 interface ResumeMeta {
     token: string;
@@ -127,7 +285,15 @@ type ApplyResumeSelection = (args: {
 }) => Record<string, unknown> | null | undefined;
 declare function parseResumeMeta(msg: ChatMessage | undefined): ResumeMeta | null;
 interface TryResumeArgs {
-    lastMessage: ChatMessage | undefined;
+    limits?: ExecutionLimits | undefined;
+    abortSignal?: AbortSignal | undefined;
+    executionSignal?: AbortSignal | undefined;
+    onExecution?: ((completion: Promise<void>) => void) | undefined;
+    lastMessage?: ChatMessage | undefined;
+    meta?: ResumeMeta | undefined;
+    emitOutput?: boolean | undefined;
+    onOutcome?: OrchestrateArgs["onOutcome"];
+    validatePending?: ((pending: PendingRequestRecord) => void | Promise<void>) | undefined;
     sessionId: string;
     config: Record<string, unknown>;
     selectWorkflow: SelectWorkflowFn;
@@ -136,7 +302,7 @@ interface TryResumeArgs {
     applyResumeSelection?: ApplyResumeSelection;
     frameworkAdapter?: FrameworkAdapter;
 }
-declare function tryPrepareResumeStream({ lastMessage, sessionId, config, selectWorkflow, knownWorkflowIds, defaultWorkflowId, applyResumeSelection, frameworkAdapter, }: TryResumeArgs): Promise<AsyncIterable<StreamChunk> | null>;
+declare function tryPrepareResumeStream({ limits, abortSignal, executionSignal, onExecution, lastMessage, meta: suppliedMeta, emitOutput, onOutcome, validatePending, sessionId, config, selectWorkflow, knownWorkflowIds, defaultWorkflowId, applyResumeSelection, frameworkAdapter, }: TryResumeArgs): Promise<AsyncIterable<StreamChunk> | null>;
 
 interface RuntimeConfig {
     session?: {
@@ -145,6 +311,9 @@ interface RuntimeConfig {
     [key: string]: unknown;
 }
 interface StreamChatArgs<Options> {
+    abortSignal?: AbortSignal | undefined;
+    executionSignal?: AbortSignal | undefined;
+    onExecution?: ((completion: Promise<void>) => void) | undefined;
     messages: ChatMessage[];
     options?: Options | undefined;
     sessionId?: string;
@@ -157,7 +326,7 @@ interface StreamChatArgs<Options> {
     getProvider: GetProviderFn;
     applyResumeSelection?: ApplyResumeSelection;
 }
-declare function streamChat<Options = unknown>({ messages, options, sessionId, defaultWorkflowId, loadRuntimeConfig, selectWorkflow, workflowRegistry, knownWorkflowIds, frameworkAdapter, getProvider, applyResumeSelection, }: StreamChatArgs<Options>): Promise<AsyncIterable<StreamChunk>>;
+declare function streamChat<Options = unknown>({ messages, abortSignal, executionSignal, onExecution, options, sessionId, defaultWorkflowId, loadRuntimeConfig, selectWorkflow, workflowRegistry, knownWorkflowIds, frameworkAdapter, getProvider, applyResumeSelection, }: StreamChatArgs<Options>): Promise<AsyncIterable<StreamChunk>>;
 
 interface TransformOptions {
     debug?: boolean;
@@ -173,4 +342,4 @@ declare function transformGraphStreamForUI(stream: AsyncIterable<StreamEvent>, o
 
 declare function extractLatestUserMessage(messages: ChatMessage[]): string;
 
-export { type Agent, type AgentProcessOptions, type AgentProjectTopologyOptions, type ApplyResumeSelection, ChatMessage, type ChatRequestBody, type CheckpointRequestBody, type CompiledGraphLike, type CreateAgentArgs, type OrchestrateArgs, type ResumeMeta, type SaveMemoryFn, type SelectWorkflowFn, type StreamChatArgs, createAgent, createChatRouteHandler, createCheckpointRouteHandler, extractLatestUserMessage, handleChatRequestBody, handleCheckpointRequestBody, orchestrateGraphStream, parseChatRequestBody, parseCheckpointRequestBody, parseResumeMeta, projectWorkflowTopology, streamChat, transformGraphStreamForUI, tryPrepareResumeStream };
+export { type Agent, type AgentProcessOptions, type AgentProjectTopologyOptions, type ApplyResumeSelection, ChatMessage, type ChatRequestBody, type CheckpointRequestBody, type CompiledGraphLike, type CreateAgentArgs, type ExecutableWorkflow, type ExecuteOptions, type ExecutionInfo, type ExecutionInterrupt, ExecutionRequestError, type ExecutionResult, type InterruptScope, type ListInterruptsOptions, type OrchestrateArgs, type PendingInterrupt, type ResumableInterrupt, type ResumeHandle, type ResumeMeta, type ResumeOptions, type ResumeResponse, type SaveMemoryFn, type SelectWorkflowFn, type StreamChatArgs, createAgent, createChatRouteHandler, createCheckpointRouteHandler, extractLatestUserMessage, handleChatRequestBody, handleCheckpointRequestBody, orchestrateGraphStream, parseChatRequestBody, parseCheckpointRequestBody, parseResumeMeta, projectWorkflowTopology, streamChat, transformGraphStreamForUI, tryPrepareResumeStream };