@kortyx/agent 0.26.2 → 0.27.0

package/dist/index.js

@@ -61,7 +61,7 @@ var require_internal = __commonJS({
       withSafeTraceSpan: () => withSafeTraceSpan2
     });
     module2.exports = __toCommonJS2(internal_exports);
-    var import_errors6 = require("@kortyx/core/errors");
+    var import_errors8 = require("@kortyx/core/errors");
     var MAX_STACK_LENGTH = 32768;
     var MAX_CAUSE_DEPTH = 4;
     var projectDetails = (value, depth, seen) => {
@@ -71,16 +71,16 @@ var require_internal = __commonJS({
           return { type: "Error", message: "Circular error cause." };
         seen.add(objectValue);
       }
-      const name = (0, import_errors6.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
-      const message = (0, import_errors6.errorProperty)(value, "message");
-      const stack = (0, import_errors6.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
+      const name = (0, import_errors8.errorProperty)(value, "name") ?? (value instanceof Error ? value.name : void 0);
+      const message = (0, import_errors8.errorProperty)(value, "message");
+      const stack = (0, import_errors8.errorProperty)(value, "stack") ?? (value instanceof Error ? (() => {
         try {
           return value.stack;
         } catch {
           return void 0;
         }
       })() : void 0);
-      const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors6.errorProperty)(value, "cause") : null;
+      const cause = depth < MAX_CAUSE_DEPTH ? (0, import_errors8.errorProperty)(value, "cause") : null;
       return {
         type: typeof name === "string" ? name.slice(0, 256) : "Error",
         message: (typeof value === "string" ? value : typeof message === "string" ? message : "Execution reported a fault.").slice(0, 8192),
@@ -789,14 +789,14 @@ var require_dist = __commonJS({
         workflowState: args.workflowState
       }
     });
-    var import_errors6 = require("@kortyx/core/errors");
+    var import_errors8 = require("@kortyx/core/errors");
     var parseWithSchema = (schema, value, label) => {
       if (!schema) return value;
       const parsed = schema.safeParse(value);
       if (parsed.success) return parsed.data;
       const parsedError = "error" in parsed && parsed.error ? parsed.error : void 0;
       const reason = typeof parsedError?.message === "string" && parsedError.message.length > 0 ? parsedError.message : "invalid payload";
-      throw new import_errors6.ValidationError(
+      throw new import_errors8.ValidationError(
         label === "useReason output" ? "MODEL_OUTPUT_SCHEMA" : "SCHEMA_VALIDATION",
         `${label} validation failed: ${reason}`,
         parsedError
@@ -3950,7 +3950,7 @@ ${tryStringify2(args.response)}`
       return [getValue(), setValue];
     }
     var import_core7 = require("@kortyx/core");
-    var import_errors7 = require("@kortyx/core/errors");
+    var import_errors72 = require("@kortyx/core/errors");
     var ParallelChildWaiting = class extends Error {
       name = "ParallelChildWaiting";
     };
@@ -3964,14 +3964,14 @@ ${tryStringify2(args.response)}`
         );
         this.results = results;
         this.name = "ParallelError";
-        this.failure = (0, import_errors7.serializeFailure)({
+        this.failure = (0, import_errors72.serializeFailure)({
           version: 1,
           code: this.code,
           category: "workflow",
           message: this.message,
           retryable: null,
           results: results.map(
-            (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors7.serializeFailure)(result.reason) }
+            (result) => result.status === "fulfilled" ? { status: "fulfilled" } : { status: "rejected", failure: (0, import_errors72.serializeFailure)(result.reason) }
           )
         });
       }
@@ -3979,7 +3979,7 @@ ${tryStringify2(args.response)}`
       code = "PARALLEL_FAILED";
       failure;
       toJSON() {
-        return (0, import_errors7.serializeFailure)(this);
+        return (0, import_errors72.serializeFailure)(this);
       }
     };
     function registerWorkflowTask(id) {
@@ -4124,11 +4124,11 @@ ${tryStringify2(args.response)}`
     }
     var import_node_crypto6 = require("crypto");
     var import_core8 = require("@kortyx/core");
-    var import_errors8 = require("@kortyx/core/errors");
-    var WorkflowCallError = class extends import_errors8.KortyxError {
+    var import_errors82 = require("@kortyx/core/errors");
+    var WorkflowCallError = class extends import_errors82.KortyxError {
       constructor(workflow, message, cause, failure) {
-        const detail = (0, import_errors8.serializeFailure)(
-          failure ?? cause ?? new import_errors8.WorkflowContractError(message)
+        const detail = (0, import_errors82.serializeFailure)(
+          failure ?? cause ?? new import_errors82.WorkflowContractError(message)
         );
         super(detail.code, `Workflow '${workflow}': ${message}`, {
           ...detail,
@@ -4149,12 +4149,12 @@ ${tryStringify2(args.response)}`
         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 import_errors8.WorkflowContractError(
+          throw new import_errors82.WorkflowContractError(
             "Workflow input and output must be JSON serializable."
           );
         }
         if (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype) {
-          throw new import_errors8.WorkflowContractError(
+          throw new import_errors82.WorkflowContractError(
             "Workflow input and output must contain plain JSON objects."
           );
         }
@@ -4175,7 +4175,7 @@ ${tryStringify2(args.response)}`
         useWorkflow: (args) => {
           const workflow = workflows[args.workflow];
           if (!workflow || workflow.id !== args.workflow)
-            throw new import_errors8.WorkflowContractError(
+            throw new import_errors82.WorkflowContractError(
               "Workflow registry keys must match definition ids."
             );
           return useWorkflow({ ...args, workflow });
@@ -4201,23 +4201,23 @@ ${tryStringify2(args.response)}`
       (0, import_core8.throwIfExecutionAborted)(ctx.node.abortSignal);
       const service = ctx.node.callWorkflow;
       if (!service)
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "useWorkflow requires an agent workflow registry."
         );
       if (!args.id.trim())
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "useWorkflow requires a stable, nonempty id."
         );
       if (ctx.workflowCallActive && !task.group)
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "Concurrent workflow calls require parallel([...]); otherwise await each call."
         );
       if (ctx.workflowCallIds.has(args.id))
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           `Duplicate workflow call id '${args.id}' in one node activation.`
         );
       if (ctx.workflowCallIds.size >= 64)
-        throw new import_errors8.WorkflowContractError(
+        throw new import_errors82.WorkflowContractError(
           "A node may call at most 64 child workflows per activation."
         );
       ctx.workflowCallIds.add(args.id);
@@ -4298,7 +4298,7 @@ ${tryStringify2(args.response)}`
             workflow,
             record.error ?? "child failed",
             void 0,
-            record.failure ?? (0, import_errors8.serializeFailure)(void 0)
+            record.failure ?? (0, import_errors82.serializeFailure)(void 0)
           );
         if (task.group && record.status === "interrupted" && record.interrupts.at(-1)?.response === void 0)
           throw new ParallelChildWaiting();
@@ -4334,7 +4334,7 @@ ${tryStringify2(args.response)}`
               throw error;
             }
             record.status = "failed";
-            record.failure = (0, import_errors8.serializeFailure)(error);
+            record.failure = (0, import_errors82.serializeFailure)(error);
             record.error = record.failure.message;
             report("failed", { error: "Child workflow failed" });
             throw new WorkflowCallError(
@@ -4395,6 +4395,7 @@ ${tryStringify2(args.response)}`
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ChatLifecycleHookError: () => ChatLifecycleHookError,
   ExecutionRequestError: () => ExecutionRequestError,
   createAgent: () => createAgent,
   createChatRouteHandler: () => createChatRouteHandler,
@@ -4417,183 +4418,29 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/adapters/http.ts
+var import_errors5 = require("@kortyx/core/errors");
+var import_stream2 = require("@kortyx/stream");
+var import_zod2 = require("zod");
+
+// src/chat/lifecycle.ts
 var import_errors = require("@kortyx/core/errors");
-var import_stream = require("@kortyx/stream");
-var import_zod = require("zod");
-var chatMessageSchema = import_zod.z.object({
-  role: import_zod.z.enum(["user", "assistant", "system"]),
-  content: import_zod.z.string(),
-  metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
-  id: import_zod.z.string().optional(),
-  timestamp: import_zod.z.number().refine(Number.isFinite).optional()
-}).strict();
-var chatRequestBodySchema = import_zod.z.looseObject({
-  sessionId: import_zod.z.string().optional(),
-  workflowId: import_zod.z.string().optional(),
-  stream: import_zod.z.boolean().optional(),
-  context: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional(),
-  messages: import_zod.z.array(chatMessageSchema)
-});
-var checkpointRequestBodySchema = import_zod.z.discriminatedUnion("action", [
-  import_zod.z.object({
-    action: import_zod.z.literal("list"),
-    sessionId: import_zod.z.string().min(1)
-  }).strict(),
-  import_zod.z.object({
-    action: import_zod.z.literal("get"),
-    checkpointId: import_zod.z.string().min(1)
-  }).strict(),
-  import_zod.z.object({
-    action: import_zod.z.literal("rollback"),
-    checkpointId: import_zod.z.string().min(1)
-  }).strict(),
-  import_zod.z.object({
-    action: import_zod.z.literal("fork"),
-    checkpointId: import_zod.z.string().min(1),
-    newSessionId: import_zod.z.string().min(1).optional()
-  }).strict()
-]);
-async function readRequestJson(request) {
-  try {
-    const value = await request.json();
-    if (!value || typeof value !== "object" || Array.isArray(value))
-      throw new Error("Expected a JSON object.");
-    return value;
-  } catch (cause) {
-    throw new import_errors.KortyxError(
-      "INVALID_REQUEST",
-      "Request body is not valid JSON.",
+var ChatLifecycleHookError = class extends import_errors.KortyxError {
+  phase;
+  constructor(phase, cause) {
+    super(
+      "CHAT_LIFECYCLE_HOOK_FAILED",
+      `Chat lifecycle hook failed: ${phase}`,
       {
-        category: "request",
-        retryable: false,
-        safeMessage: "The request body must contain a valid JSON object.",
+        category: "persistence",
+        retryable: null,
+        safeMessage: "Chat state could not be saved.",
         cause
       }
     );
+    this.name = "ChatLifecycleHookError";
+    this.phase = phase;
   }
-}
-function createFailureResponse(error, status) {
-  const failure = (0, import_errors.serializeFailure)(error);
-  return Response.json(
-    { error: failure.message, failure },
-    { status: status ?? (0, import_errors.failureHttpStatus)(failure) }
-  );
-}
-function parseChatRequestBody(value) {
-  const parsed = chatRequestBodySchema.safeParse(value);
-  if (!parsed.success) {
-    const [firstIssue] = parsed.error.issues;
-    throw new import_errors.KortyxError("INVALID_REQUEST", firstIssue.message, {
-      category: "request",
-      retryable: false,
-      safeMessage: "The request body is invalid."
-    });
-  }
-  const sessionId = parsed.data.sessionId?.trim();
-  const workflowId = parsed.data.workflowId?.trim();
-  return {
-    ...sessionId ? { sessionId } : {},
-    ...workflowId ? { workflowId } : {},
-    ...typeof parsed.data.stream === "boolean" ? { stream: parsed.data.stream } : {},
-    ...parsed.data.context ? { context: parsed.data.context } : {},
-    messages: parsed.data.messages
-  };
-}
-function parseCheckpointRequestBody(value) {
-  const parsed = checkpointRequestBodySchema.safeParse(value);
-  if (parsed.success) return parsed.data;
-  const [firstIssue] = parsed.error.issues;
-  throw new import_errors.KortyxError("INVALID_REQUEST", firstIssue.message, {
-    category: "request",
-    retryable: false,
-    safeMessage: "The request body is invalid."
-  });
-}
-async function handleChatRequestBody(args) {
-  const { agent, body } = args;
-  const stream = await agent.streamChat(body.messages, {
-    ...args.onExecution ? { onExecution: args.onExecution } : {},
-    ...args.abortSignal ? { abortSignal: args.abortSignal } : {},
-    sessionId: body.sessionId,
-    workflowId: body.workflowId,
-    context: body.context
-  });
-  if (body.stream === false) {
-    const buffered = await (0, import_stream.collectBufferedStream)(stream);
-    return new Response(JSON.stringify(buffered), {
-      headers: {
-        "content-type": "application/json"
-      }
-    });
-  }
-  return (0, import_stream.toSSE)(stream);
-}
-function createChatRouteHandler(args) {
-  const { agent, errorStatus } = args;
-  return async function POST(request) {
-    try {
-      const body = parseChatRequestBody(await readRequestJson(request));
-      return await handleChatRequestBody({
-        agent,
-        body,
-        abortSignal: request.signal,
-        onExecution: args.onExecution
-      });
-    } catch (error) {
-      return createFailureResponse(error, errorStatus);
-    }
-  };
-}
-async function handleCheckpointRequestBody(args) {
-  const { agent, body } = args;
-  const result = body.action === "list" ? await agent.listCheckpoints(body.sessionId) : body.action === "get" ? await agent.getCheckpoint(body.checkpointId) : body.action === "rollback" ? await agent.rollbackTo(body.checkpointId) : await agent.fork(body.checkpointId, {
-    ...body.newSessionId ? { newSessionId: body.newSessionId } : {}
-  });
-  return new Response(JSON.stringify(result), {
-    headers: {
-      "content-type": "application/json"
-    }
-  });
-}
-function createCheckpointRouteHandler(args) {
-  const { agent, errorStatus } = args;
-  return async function POST(request) {
-    try {
-      const body = parseCheckpointRequestBody(await readRequestJson(request));
-      return await handleCheckpointRequestBody({ agent, body });
-    } catch (error) {
-      return createFailureResponse(error, errorStatus);
-    }
-  };
-}
-
-// src/adapters/http-client.ts
-var import_browser = require("@kortyx/stream/browser");
-async function* streamChatFromRoute(args) {
-  yield* (0, import_browser.streamFromRoute)({
-    endpoint: args.endpoint,
-    ...args.fetchImpl ? { fetchImpl: args.fetchImpl } : {},
-    ...args.headers ? { headers: args.headers } : {},
-    body: {
-      sessionId: args.sessionId,
-      workflowId: args.workflowId,
-      messages: args.messages
-    }
-  });
-}
-
-// src/chat/create-agent.ts
-var import_node_path = require("path");
-var import_core5 = require("@kortyx/core");
-var import_providers = require("@kortyx/providers");
-var import_runtime5 = require("@kortyx/runtime");
-var import_zod5 = require("zod");
-
-// src/execution/execute.ts
-var import_core4 = require("@kortyx/core");
-var import_errors5 = require("@kortyx/core/errors");
-var import_runtime3 = require("@kortyx/runtime");
-var import_zod3 = require("zod");
+};
 
 // src/interrupt/resume-handler.ts
 var import_core3 = require("@kortyx/core");
@@ -4619,11 +4466,12 @@ var import_core2 = require("@kortyx/core");
 var import_errors4 = require("@kortyx/core/errors");
 var import_internal = __toESM(require_internal());
 var import_runtime = require("@kortyx/runtime");
+var import_stream = require("@kortyx/stream");
 var import_langgraph = require("@langchain/langgraph");
 
 // src/execution/contracts.ts
 var import_errors3 = require("@kortyx/core/errors");
-var import_zod2 = require("zod");
+var import_zod = require("zod");
 async function resolveExecutionWorkflow(select, reference) {
   const id = typeof reference === "string" ? reference : reference.id;
   let workflow;
@@ -4655,12 +4503,12 @@ async function resolveExecutionWorkflow(select, reference) {
 }
 function parseExecutionInput(workflow, input) {
   try {
-    import_zod2.z.json().parse(input);
+    import_zod.z.json().parse(input);
     const parsed = workflow.inputSchema ? workflow.inputSchema.parse(input) : input;
-    import_zod2.z.json().parse(parsed);
+    import_zod.z.json().parse(parsed);
     return parsed;
   } catch (error) {
-    if (!(error instanceof import_zod2.z.ZodError)) throw error;
+    if (!(error instanceof import_zod.z.ZodError)) throw error;
     throw new ExecutionRequestError("INVALID_INPUT", error.message, error);
   }
 }
@@ -4678,9 +4526,9 @@ async function validateExecutionOutput(state, select) {
     for (const schema of /* @__PURE__ */ new Set([terminal.outputSchema, root.outputSchema])) {
       if (schema) data = schema.parse(data);
     }
-    if (terminal.outputSchema || root.outputSchema) import_zod2.z.json().parse(data);
+    if (terminal.outputSchema || root.outputSchema) import_zod.z.json().parse(data);
   } catch (error) {
-    if (!(error instanceof import_zod2.z.ZodError)) throw error;
+    if (!(error instanceof import_zod.z.ZodError)) throw error;
     const failure = new import_errors3.ValidationError(
       "INVALID_OUTPUT",
       `Workflow output validation failed: ${error.message}`,
@@ -5091,6 +4939,9 @@ async function orchestrateGraphStream({
   abortSignal: requestSignal,
   executionSignal,
   onExecution,
+  clientTurnId,
+  continueOnDisconnect = false,
+  onResponseFinalized,
   emitOutput = true,
   onOutcome,
   selectWorkflow,
@@ -5099,12 +4950,34 @@ async function orchestrateGraphStream({
   executionLeaseRelease
 }) {
   const out = new import_node_stream.PassThrough({ objectMode: true });
+  const visibleMessage = emitOutput && clientTurnId && onResponseFinalized && initialConfig.responseCompleted !== true ? (0, import_stream.createFinalizedChatMessageAccumulator)(clientTurnId) : void 0;
+  let responseFinalized = false;
+  const finalizeVisibleResponse = async (status) => {
+    if (!visibleMessage || !onResponseFinalized || !clientTurnId || !sessionId || responseFinalized)
+      return;
+    responseFinalized = true;
+    try {
+      await onResponseFinalized({
+        sessionId,
+        runId,
+        clientTurnId,
+        status,
+        message: visibleMessage.message(),
+        ...sessionCheckpointId ? { checkpointId: sessionCheckpointId } : {}
+      });
+    } catch (error) {
+      console.error("[chat:onResponseFinalized]", (0, import_errors4.serializeFailure)(error));
+    }
+  };
   const write = (chunk) => {
     if (isRecord3(chunk) && chunk.type === "done" && isGraphState(chunk.data)) {
       const { __kortyxParallelGraph: _journal, ...runtime } = chunk.data.runtime;
       chunk = { ...chunk, data: { ...chunk.data, runtime } };
     }
-    if (emitOutput && !response.closed && !out.destroyed) out.write(chunk);
+    if (emitOutput && !response.closed) {
+      visibleMessage?.apply(chunk);
+      if (!out.destroyed) out.write(chunk);
+    }
   };
   let outcomeState = state;
   let outcomeError;
@@ -5119,7 +4992,7 @@ async function orchestrateGraphStream({
   const response = createResponseLifecycle({
     enabled: emitOutput,
     restored: initialConfig.responseCompleted === true,
-    requestSignal,
+    requestSignal: continueOnDisconnect ? void 0 : requestSignal,
     executionSignal: executionSignal ? AbortSignal.any([executionSignal, leaseAbort.signal]) : leaseAbort.signal,
     onClosed: () => {
       out.write({ type: "done" });
@@ -5183,11 +5056,12 @@ async function orchestrateGraphStream({
         },
         flush: true
       });
+      await finalizeVisibleResponse("completed");
     }
   });
   const abortSignal = response.signal;
   out.on("close", () => {
-    if (!finished) response.disconnect();
+    if (!finished && !continueOnDisconnect) response.disconnect();
   });
   let structuredSeq = 0;
   const debugEnabled = Boolean(config?.features?.tracing);
@@ -5940,6 +5814,9 @@ async function orchestrateGraphStream({
             );
           }
         }
+        await finalizeVisibleResponse(
+          outcomeError ? "failed" : shouldKeepFrameworkState ? "interrupted" : "completed"
+        );
         write({ type: "done", data: workflowFinalState });
         out.end();
         return;
@@ -6017,6 +5894,9 @@ async function orchestrateGraphStream({
       });
       finished = true;
       runTraceSpan.end?.(runTraceEndArgs());
+      await finalizeVisibleResponse(
+        outcomeError ? "failed" : pendingRecordToken || naturalFinalState.awaitingHumanInput ? "interrupted" : "completed"
+      );
       write({ type: "done", data: naturalFinalState });
       out.end();
       return;
@@ -6077,6 +5957,7 @@ async function orchestrateGraphStream({
     fallbackRunSpan?.setAttributes?.({ "kortyx.run.cancelled": true });
     fallbackRunSpan?.end?.();
     write({ type: "cancelled", runId, reason: "Execution cancelled." });
+    await finalizeVisibleResponse("cancelled");
     write({ type: "done" });
     finished = true;
     out.end();
@@ -6223,6 +6104,9 @@ async function orchestrateGraphStream({
       console.error("[execution:releaseLease]", (0, import_errors4.serializeFailure)(error));
     }
     response.dispose();
+    await finalizeVisibleResponse(
+      outcomeError ? (0, import_core2.isExecutionCancelled)(outcomeError) ? "cancelled" : "failed" : pendingRecordToken || outcomeState.awaitingHumanInput ? "interrupted" : "completed"
+    );
     onOutcome?.({
       state: outcomeState,
       pending: pendingRecordToken ? activePendingRequests.get(pendingRecordToken) : void 0,
@@ -6272,6 +6156,9 @@ async function tryPrepareResumeStream({
   abortSignal,
   executionSignal,
   onExecution,
+  clientTurnId,
+  continueOnDisconnect,
+  onResponseFinalized,
   lastMessage,
   meta: suppliedMeta,
   emitOutput,
@@ -6490,6 +6377,9 @@ async function tryPrepareResumeStream({
       executionSignal: continuedSignal ? AbortSignal.any([continuedSignal, leaseAbort.signal]) : leaseAbort.signal,
       executionLeaseRelease: releaseLease,
       onExecution,
+      clientTurnId,
+      continueOnDisconnect,
+      onResponseFinalized,
       emitOutput,
       onOutcome,
       sessionId,
@@ -6526,7 +6416,316 @@ async function tryPrepareResumeStream({
   }
 }
 
+// src/adapters/http.ts
+var reportLifecycleError = async (callback, event) => {
+  if (!callback) {
+    console.error("[chat:lifecycle]", event.error);
+    return;
+  }
+  try {
+    await callback(event);
+  } catch (error) {
+    console.error("[chat:onLifecycleError]", (0, import_errors5.serializeFailure)(error));
+  }
+};
+var chatMessageSchema = import_zod2.z.object({
+  role: import_zod2.z.enum(["user", "assistant", "system"]),
+  content: import_zod2.z.string(),
+  metadata: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).optional(),
+  id: import_zod2.z.string().optional(),
+  timestamp: import_zod2.z.number().refine(Number.isFinite).optional()
+}).strict();
+var chatRequestBodySchema = import_zod2.z.looseObject({
+  sessionId: import_zod2.z.string().optional(),
+  clientTurnId: import_zod2.z.string().max(128).optional(),
+  workflowId: import_zod2.z.string().optional(),
+  stream: import_zod2.z.boolean().optional(),
+  context: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).optional(),
+  messages: import_zod2.z.array(chatMessageSchema)
+});
+var checkpointRequestBodySchema = import_zod2.z.discriminatedUnion("action", [
+  import_zod2.z.object({
+    action: import_zod2.z.literal("list"),
+    sessionId: import_zod2.z.string().min(1)
+  }).strict(),
+  import_zod2.z.object({
+    action: import_zod2.z.literal("get"),
+    checkpointId: import_zod2.z.string().min(1)
+  }).strict(),
+  import_zod2.z.object({
+    action: import_zod2.z.literal("rollback"),
+    checkpointId: import_zod2.z.string().min(1)
+  }).strict(),
+  import_zod2.z.object({
+    action: import_zod2.z.literal("fork"),
+    checkpointId: import_zod2.z.string().min(1),
+    newSessionId: import_zod2.z.string().min(1).optional()
+  }).strict()
+]);
+async function readRequestJson(request) {
+  try {
+    const value = await request.json();
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("Expected a JSON object.");
+    return value;
+  } catch (cause) {
+    throw new import_errors5.KortyxError(
+      "INVALID_REQUEST",
+      "Request body is not valid JSON.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "The request body must contain a valid JSON object.",
+        cause
+      }
+    );
+  }
+}
+function createFailureResponse(error, status) {
+  const failure = (0, import_errors5.serializeFailure)(error);
+  return Response.json(
+    { error: failure.message, failure },
+    { status: status ?? (0, import_errors5.failureHttpStatus)(failure) }
+  );
+}
+function parseChatRequestBody(value) {
+  const parsed = chatRequestBodySchema.safeParse(value);
+  if (!parsed.success) {
+    const [firstIssue] = parsed.error.issues;
+    throw new import_errors5.KortyxError("INVALID_REQUEST", firstIssue.message, {
+      category: "request",
+      retryable: false,
+      safeMessage: "The request body is invalid."
+    });
+  }
+  const sessionId = parsed.data.sessionId?.trim();
+  const workflowId = parsed.data.workflowId?.trim();
+  const clientTurnId = parsed.data.clientTurnId?.trim();
+  return {
+    ...sessionId ? { sessionId } : {},
+    ...workflowId ? { workflowId } : {},
+    ...clientTurnId ? { clientTurnId } : {},
+    ...typeof parsed.data.stream === "boolean" ? { stream: parsed.data.stream } : {},
+    ...parsed.data.context ? { context: parsed.data.context } : {},
+    messages: parsed.data.messages
+  };
+}
+function parseCheckpointRequestBody(value) {
+  const parsed = checkpointRequestBodySchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const [firstIssue] = parsed.error.issues;
+  throw new import_errors5.KortyxError("INVALID_REQUEST", firstIssue.message, {
+    category: "request",
+    retryable: false,
+    safeMessage: "The request body is invalid."
+  });
+}
+async function handleChatRequestBody(args) {
+  const { agent, body } = args;
+  if (args.onResponseFinalized && (!body.sessionId || !body.clientTurnId)) {
+    throw new import_errors5.KortyxError(
+      "INVALID_REQUEST",
+      "sessionId and clientTurnId are required with onResponseFinalized.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "This chat request needs a session and turn ID."
+      }
+    );
+  }
+  const stream = await agent.streamChat(body.messages, {
+    ...args.onExecution ? { onExecution: args.onExecution } : {},
+    ...body.clientTurnId ? { clientTurnId: body.clientTurnId } : {},
+    ...args.continueOnDisconnect ? { continueOnDisconnect: true } : {},
+    ...args.onResponseFinalized ? { onResponseFinalized: args.onResponseFinalized } : {},
+    ...args.abortSignal && !args.continueOnDisconnect ? { abortSignal: args.abortSignal } : {},
+    sessionId: body.sessionId,
+    workflowId: body.workflowId,
+    context: body.context
+  });
+  if (body.stream === false) {
+    const buffered = await (0, import_stream2.collectBufferedStream)(stream);
+    return new Response(JSON.stringify(buffered), {
+      headers: {
+        "content-type": "application/json"
+      }
+    });
+  }
+  return (0, import_stream2.toSSE)(stream);
+}
+function createChatRouteHandler(args) {
+  const { agent, errorStatus } = args;
+  if (args.disconnect === "continue" && !args.onExecution) {
+    throw new Error(
+      'disconnect: "continue" requires onExecution to retain host lifetime.'
+    );
+  }
+  return async function POST(request) {
+    try {
+      const body = parseChatRequestBody(await readRequestJson(request));
+      if (args.onTurnAccepted || args.onResponseFinalized) {
+        if (!body.sessionId || !body.clientTurnId) {
+          throw new import_errors5.KortyxError(
+            "INVALID_REQUEST",
+            "sessionId and clientTurnId are required with chat lifecycle hooks.",
+            {
+              category: "request",
+              retryable: false,
+              safeMessage: "This chat request needs a session and turn ID."
+            }
+          );
+        }
+        const userMessage = body.messages.at(-1);
+        if (!userMessage || userMessage.role !== "user") {
+          throw new import_errors5.KortyxError(
+            "INVALID_REQUEST",
+            "The last chat message must be from the user.",
+            {
+              category: "request",
+              retryable: false,
+              safeMessage: "The chat request needs a user message."
+            }
+          );
+        }
+        if (args.onTurnAccepted) {
+          try {
+            await args.onTurnAccepted({
+              request,
+              sessionId: body.sessionId,
+              clientTurnId: body.clientTurnId,
+              userMessage: { ...userMessage, role: "user" },
+              kind: parseResumeMeta(userMessage) ? "interrupt-response" : "prompt"
+            });
+          } catch (cause) {
+            const error = new ChatLifecycleHookError("turn-accepted", cause);
+            await reportLifecycleError(args.onLifecycleError, {
+              phase: "turn-accepted",
+              clientTurnId: body.clientTurnId,
+              error
+            });
+            throw error;
+          }
+        }
+      }
+      return await handleChatRequestBody({
+        agent,
+        body,
+        abortSignal: request.signal,
+        onExecution: args.onExecution,
+        continueOnDisconnect: args.disconnect === "continue",
+        ...args.onResponseFinalized ? {
+          onResponseFinalized: async (event) => {
+            try {
+              await args.onResponseFinalized?.({ ...event, request });
+            } catch (cause) {
+              await reportLifecycleError(args.onLifecycleError, {
+                phase: "response-finalized",
+                clientTurnId: event.clientTurnId,
+                error: new ChatLifecycleHookError(
+                  "response-finalized",
+                  cause
+                )
+              });
+            }
+          }
+        } : {}
+      });
+    } catch (error) {
+      return createFailureResponse(error, errorStatus);
+    }
+  };
+}
+async function handleCheckpointRequestBody(args) {
+  const { agent, body } = args;
+  const result = body.action === "list" ? await agent.listCheckpoints(body.sessionId) : body.action === "get" ? await agent.getCheckpoint(body.checkpointId) : body.action === "rollback" ? await agent.rollbackTo(body.checkpointId) : await agent.fork(body.checkpointId, {
+    ...body.newSessionId ? { newSessionId: body.newSessionId } : {}
+  });
+  if (args.request && body.action === "fork" && args.onForked) {
+    const fork = result;
+    try {
+      await args.onForked({
+        request: args.request,
+        sourceSessionId: fork.parentSessionId,
+        newSessionId: fork.sessionId,
+        sourceCheckpointId: fork.forkedFrom,
+        newCheckpointId: fork.checkpoint.id
+      });
+    } catch (cause) {
+      await reportLifecycleError(args.onLifecycleError, {
+        phase: "forked",
+        error: new ChatLifecycleHookError("forked", cause)
+      });
+    }
+  }
+  if (args.request && body.action === "rollback" && args.onRolledBack) {
+    const rollback = result;
+    try {
+      await args.onRolledBack({
+        request: args.request,
+        sessionId: rollback.sessionId,
+        headCheckpointId: rollback.head,
+        invalidatedStructuredStreamIds: rollback.invalidatedStructuredStreamIds
+      });
+    } catch (cause) {
+      await reportLifecycleError(args.onLifecycleError, {
+        phase: "rolled-back",
+        error: new ChatLifecycleHookError("rolled-back", cause)
+      });
+    }
+  }
+  return new Response(JSON.stringify(result), {
+    headers: {
+      "content-type": "application/json"
+    }
+  });
+}
+function createCheckpointRouteHandler(args) {
+  const { agent, errorStatus } = args;
+  return async function POST(request) {
+    try {
+      const body = parseCheckpointRequestBody(await readRequestJson(request));
+      return await handleCheckpointRequestBody({
+        agent,
+        body,
+        request,
+        onForked: args.onForked,
+        onRolledBack: args.onRolledBack,
+        onLifecycleError: args.onLifecycleError
+      });
+    } catch (error) {
+      return createFailureResponse(error, errorStatus);
+    }
+  };
+}
+
+// src/adapters/http-client.ts
+var import_browser = require("@kortyx/stream/browser");
+async function* streamChatFromRoute(args) {
+  yield* (0, import_browser.streamFromRoute)({
+    endpoint: args.endpoint,
+    ...args.fetchImpl ? { fetchImpl: args.fetchImpl } : {},
+    ...args.headers ? { headers: args.headers } : {},
+    body: {
+      sessionId: args.sessionId,
+      clientTurnId: args.clientTurnId,
+      workflowId: args.workflowId,
+      messages: args.messages
+    }
+  });
+}
+
+// src/chat/create-agent.ts
+var import_node_path = require("path");
+var import_core5 = require("@kortyx/core");
+var import_providers = require("@kortyx/providers");
+var import_runtime5 = require("@kortyx/runtime");
+var import_zod5 = require("zod");
+
 // src/execution/execute.ts
+var import_core4 = require("@kortyx/core");
+var import_errors6 = require("@kortyx/core/errors");
+var import_runtime3 = require("@kortyx/runtime");
+var import_zod3 = require("zod");
 var handleSchema = import_zod3.z.object({
   token: import_zod3.z.string().min(1),
   requestId: import_zod3.z.string().min(1),
@@ -6557,7 +6756,7 @@ function resultFromOutcome(outcome, runId, sessionId) {
     return {
       ...info,
       status: "failed",
-      error: (0, import_errors5.serializeFailure)(error)
+      error: (0, import_errors6.serializeFailure)(error)
     };
   }
   if (outcome.cancelled)
@@ -6738,7 +6937,7 @@ async function resumeWorkflow(services, args) {
         );
     }).catch(
       (error) => reject(
-        error instanceof Error ? error : new import_errors5.KortyxError("RESUME_FAILED", "Resume failed.", {
+        error instanceof Error ? error : new import_errors6.KortyxError("RESUME_FAILED", "Resume failed.", {
           category: "persistence",
           cause: error,
           safeMessage: "The saved execution could not be resumed."
@@ -6941,6 +7140,7 @@ function restoreWorkflowCallBranch(requests, telemetry, sourceRunId) {
 }
 
 // src/chat/process-chat.ts
+var import_errors7 = require("@kortyx/core/errors");
 var import_runtime4 = require("@kortyx/runtime");
 
 // src/utils/extract-latest-message.ts
@@ -6961,6 +7161,9 @@ async function streamChat({
   abortSignal,
   executionSignal,
   onExecution,
+  clientTurnId,
+  continueOnDisconnect,
+  onResponseFinalized,
   options,
   sessionId,
   defaultWorkflowId,
@@ -6972,6 +7175,18 @@ async function streamChat({
   getProvider,
   applyResumeSelection
 }) {
+  const suppliedSessionId = sessionId || options?.sessionId;
+  if (onResponseFinalized && (!suppliedSessionId || !clientTurnId?.trim() || clientTurnId.length > 128)) {
+    throw new import_errors7.KortyxError(
+      "INVALID_REQUEST",
+      "sessionId and clientTurnId are required with onResponseFinalized.",
+      {
+        category: "request",
+        retryable: false,
+        safeMessage: "This chat request needs a session and turn ID."
+      }
+    );
+  }
   const config = await loadRuntimeConfig(options);
   let runtimeConfig2 = {
     ...config,
@@ -7010,6 +7225,9 @@ async function streamChat({
     abortSignal,
     executionSignal,
     onExecution,
+    clientTurnId,
+    continueOnDisconnect,
+    onResponseFinalized,
     lastMessage: last,
     sessionId: resolvedSessionId,
     config: runtimeConfig2,
@@ -7083,6 +7301,9 @@ async function streamChat({
     abortSignal,
     executionSignal,
     onExecution,
+    clientTurnId,
+    continueOnDisconnect,
+    onResponseFinalized,
     sessionId: resolvedSessionId,
     runId,
     graph,
@@ -7101,6 +7322,9 @@ var agentProcessOptionsSchema = import_zod5.z.object({
   onExecution: import_zod5.z.custom(
     (value) => typeof value === "function"
   ).optional(),
+  clientTurnId: import_zod5.z.string().min(1).max(128).optional(),
+  continueOnDisconnect: import_zod5.z.boolean().optional(),
+  onResponseFinalized: import_zod5.z.custom((value) => typeof value === "function").optional(),
   limits: import_core5.ExecutionLimitsSchema.optional(),
   abortSignal: import_zod5.z.custom((value) => value instanceof AbortSignal).optional(),
   sessionId: import_zod5.z.string().optional(),
@@ -7247,6 +7471,9 @@ function createAgent(args) {
       abortSignal: parsedOptions?.abortSignal,
       executionSignal: parsedOptions?.executionSignal,
       onExecution: parsedOptions?.onExecution,
+      clientTurnId: parsedOptions?.clientTurnId,
+      continueOnDisconnect: parsedOptions?.continueOnDisconnect,
+      onResponseFinalized: parsedOptions?.onResponseFinalized,
       options: parsedOptions,
       workflowRegistry: registry,
       ...knownWorkflowIds ? { knownWorkflowIds } : {},
@@ -7403,6 +7630,7 @@ function createAgent(args) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ChatLifecycleHookError,
   ExecutionRequestError,
   createAgent,
   createChatRouteHandler,