@kortyx/agent 0.26.2 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.27.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.26.2...agent-v0.27.0) (2026-09-23)
+
+
+### Features
+
+* **chat:** add server-side transcript lifecycle hooks ([#240](https://github.com/kortyx-io/kortyx/issues/240)) ([f84a674](https://github.com/kortyx-io/kortyx/commit/f84a6749819ee7bab343efb03f38eae743de0655))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/runtime bumped to 0.21.3
+    * @kortyx/stream bumped to 0.14.0
+
 ## [0.26.2](https://github.com/kortyx-io/kortyx/compare/agent-v0.26.1...agent-v0.26.2) (2026-09-22)
 
 

package/dist/{browser-wjeg_MwV.d.ts → browser-EVWVR9BO.d.ts}

@@ -11,6 +11,7 @@ type ChatMessage = {
 interface StreamChatFromRouteArgs {
     endpoint: string;
     sessionId?: string | undefined;
+    clientTurnId?: string | undefined;
     workflowId?: string | undefined;
     messages: ChatMessage[];
     fetchImpl?: typeof fetch;

package/dist/browser.d.ts

@@ -1,2 +1,2 @@
-export { S as StreamChatFromRouteArgs, s as streamChatFromRoute } from './browser-wjeg_MwV.js';
+export { S as StreamChatFromRouteArgs, s as streamChatFromRoute } from './browser-EVWVR9BO.js';
 import '@kortyx/stream/browser';

package/dist/browser.js

@@ -32,6 +32,7 @@ async function* streamChatFromRoute(args) {
     ...args.headers ? { headers: args.headers } : {},
     body: {
       sessionId: args.sessionId,
+      clientTurnId: args.clientTurnId,
       workflowId: args.workflowId,
       messages: args.messages
     }

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/browser.ts","../src/adapters/http-client.ts"],"sourcesContent":["// Browser-safe exports for client bundles.\n// Keep this file free of Node-only imports (fs, path, etc).\n\nexport type { StreamChatFromRouteArgs } from \"./adapters/http-client\";\nexport { streamChatFromRoute } from \"./adapters/http-client\";\n","import { type StreamChunk, streamFromRoute } from \"@kortyx/stream/browser\";\nimport type { ChatMessage } from \"../types/chat-message\";\n\nexport interface StreamChatFromRouteArgs {\n  endpoint: string;\n  sessionId?: string | undefined;\n  workflowId?: string | undefined;\n  messages: ChatMessage[];\n  fetchImpl?: typeof fetch;\n  headers?: Record<string, string> | undefined;\n}\n\nexport async function* streamChatFromRoute(\n  args: StreamChatFromRouteArgs,\n): AsyncGenerator<StreamChunk, void, void> {\n  yield* streamFromRoute({\n    endpoint: args.endpoint,\n    ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),\n    ...(args.headers ? { headers: args.headers } : {}),\n    body: {\n      sessionId: args.sessionId,\n      workflowId: args.workflowId,\n      messages: args.messages,\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,qBAAkD;AAYlD,gBAAuB,oBACrB,MACyC;AACzC,aAAO,gCAAgB;AAAA,IACrB,UAAU,KAAK;AAAA,IACf,GAAI,KAAK,YAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;AAAA,IACtD,GAAI,KAAK,UAAU,EAAE,SAAS,KAAK,QAAQ,IAAI,CAAC;AAAA,IAChD,MAAM;AAAA,MACJ,WAAW,KAAK;AAAA,MAChB,YAAY,KAAK;AAAA,MACjB,UAAU,KAAK;AAAA,IACjB;AAAA,EACF,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/browser.ts","../src/adapters/http-client.ts"],"sourcesContent":["// Browser-safe exports for client bundles.\n// Keep this file free of Node-only imports (fs, path, etc).\n\nexport type { StreamChatFromRouteArgs } from \"./adapters/http-client\";\nexport { streamChatFromRoute } from \"./adapters/http-client\";\n","import { type StreamChunk, streamFromRoute } from \"@kortyx/stream/browser\";\nimport type { ChatMessage } from \"../types/chat-message\";\n\nexport interface StreamChatFromRouteArgs {\n  endpoint: string;\n  sessionId?: string | undefined;\n  clientTurnId?: string | undefined;\n  workflowId?: string | undefined;\n  messages: ChatMessage[];\n  fetchImpl?: typeof fetch;\n  headers?: Record<string, string> | undefined;\n}\n\nexport async function* streamChatFromRoute(\n  args: StreamChatFromRouteArgs,\n): AsyncGenerator<StreamChunk, void, void> {\n  yield* streamFromRoute({\n    endpoint: args.endpoint,\n    ...(args.fetchImpl ? { fetchImpl: args.fetchImpl } : {}),\n    ...(args.headers ? { headers: args.headers } : {}),\n    body: {\n      sessionId: args.sessionId,\n      clientTurnId: args.clientTurnId,\n      workflowId: args.workflowId,\n      messages: args.messages,\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,qBAAkD;AAalD,gBAAuB,oBACrB,MACyC;AACzC,aAAO,gCAAgB;AAAA,IACrB,UAAU,KAAK;AAAA,IACf,GAAI,KAAK,YAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;AAAA,IACtD,GAAI,KAAK,UAAU,EAAE,SAAS,KAAK,QAAQ,IAAI,CAAC;AAAA,IAChD,MAAM;AAAA,MACJ,WAAW,KAAK;AAAA,MAChB,cAAc,KAAK;AAAA,MACnB,YAAY,KAAK;AAAA,MACjB,UAAU,KAAK;AAAA,IACjB;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/index.d.ts

@@ -1,16 +1,31 @@
+import { KortyxError, FailureDescriptor } from '@kortyx/core/errors';
+import { FinalizedChatMessage, StreamChunk } from '@kortyx/stream';
 import { WorkflowDefinition, ExecutionLimits, TokenUsage, ExecutionLimitReached, ExecutionBudget, GraphState } from '@kortyx/core';
 import { GetProviderFn } from '@kortyx/providers';
 import { PendingRequestRecord, PendingRequestStore, CheckpointSummary, CheckpointId, SessionCheckpointRecord, RollbackSessionCheckpointResult, ForkSessionCheckpointResult, WorkflowRegistry, FrameworkAdapter, ExecutionRuntimeConfig } from '@kortyx/runtime';
-import { StreamChunk } from '@kortyx/stream';
 import { z } from 'zod';
-import { FailureDescriptor, KortyxError } from '@kortyx/core/errors';
 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 { C as ChatMessage } from './browser-EVWVR9BO.js';
+export { S as StreamChatFromRouteArgs, s as streamChatFromRoute } from './browser-EVWVR9BO.js';
 import { StreamEvent } from '@langchain/core/tracers/log_stream';
 import '@kortyx/stream/browser';
 
+type ChatResponseStatus = "completed" | "failed" | "cancelled" | "interrupted";
+type ChatResponseFinalized = {
+    sessionId: string;
+    runId: string;
+    clientTurnId: string;
+    status: ChatResponseStatus;
+    message: FinalizedChatMessage;
+    checkpointId?: string;
+};
+type ChatLifecyclePhase = "turn-accepted" | "response-finalized" | "forked" | "rolled-back";
+declare class ChatLifecycleHookError extends KortyxError {
+    readonly phase: ChatLifecyclePhase;
+    constructor(phase: ChatLifecyclePhase, cause: unknown);
+}
+
 type ExecutableWorkflow = WorkflowDefinition & {
     inputSchema: z.ZodType;
     outputSchema: z.ZodType<Record<string, unknown>>;
@@ -135,6 +150,9 @@ declare const projectWorkflowTopology: (args: {
 interface AgentProcessOptions {
     executionSignal?: AbortSignal | undefined;
     onExecution?: ((completion: Promise<void>) => void) | undefined;
+    clientTurnId?: string | undefined;
+    continueOnDisconnect?: boolean | undefined;
+    onResponseFinalized?: ((event: ChatResponseFinalized) => void | Promise<void>) | undefined;
     limits?: ExecutionLimits | undefined;
     abortSignal?: AbortSignal | undefined;
     sessionId?: string | undefined;
@@ -190,8 +208,52 @@ type ChatRequestBody = {
     workflowId?: string | undefined;
     stream?: boolean | undefined;
     context?: Record<string, unknown> | undefined;
+    clientTurnId?: string | undefined;
     messages: ChatMessage[];
 };
+type ChatLifecycleErrorEvent = {
+    phase: ChatLifecyclePhase;
+    clientTurnId?: string;
+    error: ChatLifecycleHookError;
+};
+type ChatRouteHandlerOptions = {
+    agent: Agent;
+    errorStatus?: number | undefined;
+    onExecution?: ((completion: Promise<void>) => void) | undefined;
+    /** Defaults to cancel. Continue requires onExecution to retain host lifetime. */
+    disconnect?: "cancel" | "continue" | undefined;
+    onTurnAccepted?: ((event: {
+        request: Request;
+        sessionId: string;
+        clientTurnId: string;
+        userMessage: ChatMessage & {
+            role: "user";
+        };
+        kind: "prompt" | "interrupt-response";
+    }) => void | Promise<void>) | undefined;
+    onResponseFinalized?: ((event: ChatResponseFinalized & {
+        request: Request;
+    }) => void | Promise<void>) | undefined;
+    onLifecycleError?: ((event: ChatLifecycleErrorEvent) => void | Promise<void>) | undefined;
+};
+type CheckpointRouteHandlerOptions = {
+    agent: Agent;
+    errorStatus?: number | undefined;
+    onForked?: ((event: {
+        request: Request;
+        sourceSessionId: string;
+        newSessionId: string;
+        sourceCheckpointId: string;
+        newCheckpointId: string;
+    }) => void | Promise<void>) | undefined;
+    onRolledBack?: ((event: {
+        request: Request;
+        sessionId: string;
+        headCheckpointId: string;
+        invalidatedStructuredStreamIds: string[];
+    }) => void | Promise<void>) | undefined;
+    onLifecycleError?: ((event: ChatLifecycleErrorEvent) => void | Promise<void>) | undefined;
+};
 type CheckpointRequestBody = {
     action: "list";
     sessionId: string;
@@ -215,22 +277,21 @@ declare function parseCheckpointRequestBody(value: unknown): CheckpointRequestBo
 declare function handleChatRequestBody(args: {
     abortSignal?: AbortSignal | undefined;
     onExecution?: ((completion: Promise<void>) => void) | undefined;
+    continueOnDisconnect?: boolean | undefined;
+    onResponseFinalized?: ((event: ChatResponseFinalized) => void | Promise<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>;
+declare function createChatRouteHandler(args: ChatRouteHandlerOptions): (request: Request) => Promise<Response>;
 declare function handleCheckpointRequestBody(args: {
     agent: Agent;
     body: CheckpointRequestBody;
+    request?: Request | undefined;
+    onForked?: CheckpointRouteHandlerOptions["onForked"];
+    onRolledBack?: CheckpointRouteHandlerOptions["onRolledBack"];
+    onLifecycleError?: CheckpointRouteHandlerOptions["onLifecycleError"];
 }): Promise<Response>;
-declare function createCheckpointRouteHandler(args: {
-    agent: Agent;
-    errorStatus?: number | undefined;
-}): (request: Request) => Promise<Response>;
+declare function createCheckpointRouteHandler(args: CheckpointRouteHandlerOptions): (request: Request) => Promise<Response>;
 
 type SelectWorkflowFn = (workflowId: string) => Promise<WorkflowDefinition>;
 type SaveMemoryFn = (sessionId: string, state: GraphState) => Promise<void>;
@@ -261,6 +322,9 @@ interface OrchestrateArgs {
     executionLeaseRelease?: (() => Promise<void>) | undefined;
     executionSignal?: AbortSignal | undefined;
     onExecution?: ((completion: Promise<void>) => void) | undefined;
+    clientTurnId?: string | undefined;
+    continueOnDisconnect?: boolean | undefined;
+    onResponseFinalized?: ((event: ChatResponseFinalized) => void | Promise<void>) | undefined;
     abortSignal?: AbortSignal | undefined;
     emitOutput?: boolean | undefined;
     onOutcome?: ((outcome: OrchestrationOutcome) => void) | undefined;
@@ -277,7 +341,7 @@ interface OrchestrateArgs {
  * Orchestrates runtime execution with mid-stream transitions emitted by
  * runtime events.
  */
-declare function orchestrateGraphStream({ sessionId, runId, graph, state, config: initialConfig, abortSignal: requestSignal, executionSignal, onExecution, emitOutput, onOutcome, selectWorkflow, knownWorkflowIds, frameworkAdapter, executionLeaseRelease, }: OrchestrateArgs): Promise<NodeJS.ReadableStream>;
+declare function orchestrateGraphStream({ sessionId, runId, graph, state, config: initialConfig, abortSignal: requestSignal, executionSignal, onExecution, clientTurnId, continueOnDisconnect, onResponseFinalized, emitOutput, onOutcome, selectWorkflow, knownWorkflowIds, frameworkAdapter, executionLeaseRelease, }: OrchestrateArgs): Promise<NodeJS.ReadableStream>;
 
 interface ResumeMeta {
     token: string;
@@ -297,6 +361,9 @@ interface TryResumeArgs {
     abortSignal?: AbortSignal | undefined;
     executionSignal?: AbortSignal | undefined;
     onExecution?: ((completion: Promise<void>) => void) | undefined;
+    clientTurnId?: string | undefined;
+    continueOnDisconnect?: boolean | undefined;
+    onResponseFinalized?: OrchestrateArgs["onResponseFinalized"];
     lastMessage?: ChatMessage | undefined;
     meta?: ResumeMeta | undefined;
     emitOutput?: boolean | undefined;
@@ -310,7 +377,7 @@ interface TryResumeArgs {
     applyResumeSelection?: ApplyResumeSelection;
     frameworkAdapter?: FrameworkAdapter;
 }
-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>;
+declare function tryPrepareResumeStream({ limits, abortSignal, executionSignal, onExecution, clientTurnId, continueOnDisconnect, onResponseFinalized, lastMessage, meta: suppliedMeta, emitOutput, onOutcome, validatePending, sessionId, config, selectWorkflow, knownWorkflowIds, defaultWorkflowId, applyResumeSelection, frameworkAdapter, }: TryResumeArgs): Promise<AsyncIterable<StreamChunk> | null>;
 
 interface RuntimeConfig {
     session?: {
@@ -322,6 +389,9 @@ interface StreamChatArgs<Options> {
     abortSignal?: AbortSignal | undefined;
     executionSignal?: AbortSignal | undefined;
     onExecution?: ((completion: Promise<void>) => void) | undefined;
+    clientTurnId?: string | undefined;
+    continueOnDisconnect?: boolean | undefined;
+    onResponseFinalized?: ((event: ChatResponseFinalized) => void | Promise<void>) | undefined;
     messages: ChatMessage[];
     options?: Options | undefined;
     sessionId?: string;
@@ -334,7 +404,7 @@ interface StreamChatArgs<Options> {
     getProvider: GetProviderFn;
     applyResumeSelection?: ApplyResumeSelection;
 }
-declare function streamChat<Options = unknown>({ messages, abortSignal, executionSignal, onExecution, options, sessionId, defaultWorkflowId, loadRuntimeConfig, selectWorkflow, workflowRegistry, knownWorkflowIds, frameworkAdapter, getProvider, applyResumeSelection, }: StreamChatArgs<Options>): Promise<AsyncIterable<StreamChunk>>;
+declare function streamChat<Options = unknown>({ messages, abortSignal, executionSignal, onExecution, clientTurnId, continueOnDisconnect, onResponseFinalized, options, sessionId, defaultWorkflowId, loadRuntimeConfig, selectWorkflow, workflowRegistry, knownWorkflowIds, frameworkAdapter, getProvider, applyResumeSelection, }: StreamChatArgs<Options>): Promise<AsyncIterable<StreamChunk>>;
 
 interface TransformOptions {
     debug?: boolean;
@@ -350,4 +420,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 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, createFailureResponse, extractLatestUserMessage, handleChatRequestBody, handleCheckpointRequestBody, orchestrateGraphStream, parseChatRequestBody, parseCheckpointRequestBody, parseResumeMeta, projectWorkflowTopology, readRequestJson, streamChat, transformGraphStreamForUI, tryPrepareResumeStream };
+export { type Agent, type AgentProcessOptions, type AgentProjectTopologyOptions, type ApplyResumeSelection, type ChatLifecycleErrorEvent, ChatLifecycleHookError, type ChatLifecyclePhase, ChatMessage, type ChatRequestBody, type ChatResponseFinalized, type ChatResponseStatus, type ChatRouteHandlerOptions, type CheckpointRequestBody, type CheckpointRouteHandlerOptions, 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, createFailureResponse, extractLatestUserMessage, handleChatRequestBody, handleCheckpointRequestBody, orchestrateGraphStream, parseChatRequestBody, parseCheckpointRequestBody, parseResumeMeta, projectWorkflowTopology, readRequestJson, streamChat, transformGraphStreamForUI, tryPrepareResumeStream };