@kortyx/agent 0.18.0 → 0.19.0

package/dist/index.js

@@ -52,6 +52,7 @@ var require_dist = __commonJS({
     var index_exports2 = {};
     __export2(index_exports2, {
       WorkflowCallError: () => WorkflowCallError,
+      completeResponse: () => completeResponse,
       createWorkflowHooks: () => createWorkflowHooks,
       emitWorkflowCall: () => emitWorkflowCall2,
       runWithHookContext: () => runWithHookContext,
@@ -66,6 +67,7 @@ var require_dist = __commonJS({
       workflowCallFingerprint: () => workflowCallFingerprint
     });
     module2.exports = __toCommonJS2(index_exports2);
+    var import_zod6 = require("zod");
     var import_node_async_hooks = require("async_hooks");
     var storage = new import_node_async_hooks.AsyncLocalStorage();
     var isRecord5 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -218,7 +220,29 @@ var require_dist = __commonJS({
       }
       return ctx;
     }
-    var import_core5 = require("@kortyx/core");
+    function snapshotHookState() {
+      const ctx = getHookContext();
+      return {
+        ...ctx.state,
+        lastNode: ctx.node.graph.node,
+        runtime: { ...ctx.state.runtime, ...buildRuntimeStateUpdates(ctx) }
+      };
+    }
+    var optionsSchema = import_zod6.z.object({
+      message: import_zod6.z.string().optional(),
+      data: import_zod6.z.json().optional()
+    }).strict();
+    async function completeResponse(options = {}) {
+      const ctx = getHookContext();
+      const parsed = optionsSchema.parse(options);
+      if (!ctx.node.completeResponse) {
+        throw new Error(
+          "completeResponse requires an agent-managed root workflow."
+        );
+      }
+      await ctx.node.completeResponse(parsed, snapshotHookState());
+    }
+    var import_core6 = require("@kortyx/core");
     var resolveReasonCheckpointKey = (args) => typeof args.id === "string" && args.id.length > 0 ? `__useReason:${args.id}` : `__useReason:auto:${args.autoIndex}`;
     var readReasonCheckpoint = (raw) => {
       if (!raw || typeof raw !== "object") return void 0;
@@ -269,7 +293,7 @@ var require_dist = __commonJS({
     };
     var awaitInterruptInternal = (args) => {
       const ctx = getHookContext();
-      (0, import_core5.throwIfExecutionAborted)(ctx.node.abortSignal);
+      (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
       const request = parseWithSchema(
         args.requestSchema,
         args.request,
@@ -833,7 +857,7 @@ var require_dist = __commonJS({
         ...output !== void 0 ? { output } : {}
       };
     };
-    var import_zod5 = require("zod");
+    var import_zod22 = require("zod");
     var tryStringify2 = (value) => {
       if (typeof value === "string") return value;
       try {
@@ -844,7 +868,7 @@ var require_dist = __commonJS({
     };
     var tryGetSchemaHint = (schema) => {
       try {
-        const hint = (0, import_zod5.toJSONSchema)(schema);
+        const hint = (0, import_zod22.toJSONSchema)(schema);
         return JSON.stringify(hint, null, 2);
       } catch {
         return void 0;
@@ -1223,11 +1247,11 @@ ${tryStringify2(args.response)}`
         args.path,
         "useReason structured field"
       );
-      const matches = [];
+      const matches2 = [];
       const visitValue = (start, currentParts) => {
         const valueStart = skipWhitespace(args.text, start);
         if (pathMatchesPattern(currentParts, targetParts)) {
-          matches.push({
+          matches2.push({
             path: currentParts.join("."),
             start: valueStart
           });
@@ -1259,7 +1283,7 @@ ${tryStringify2(args.response)}`
           const valueStart = skipWhitespace(args.text, i + 1);
           const childParts = [...currentParts, key.value];
           if (pathMatchesPattern(childParts, targetParts)) {
-            matches.push({
+            matches2.push({
               path: childParts.join("."),
               start: valueStart
             });
@@ -1286,7 +1310,7 @@ ${tryStringify2(args.response)}`
           if (args.text[i] === "]") return;
           const childParts = [...currentParts, String(index)];
           if (pathMatchesPattern(childParts, targetParts)) {
-            matches.push({
+            matches2.push({
               path: childParts.join("."),
               start: i
             });
@@ -1308,7 +1332,7 @@ ${tryStringify2(args.response)}`
         }
       };
       visitValue(0, []);
-      return matches;
+      return matches2;
     };
     var extractCompletedValueAt = (args) => {
       const start = skipWhitespace(args.text, args.start);
@@ -2389,7 +2413,7 @@ ${tryStringify2(args.response)}`
       return [getValue(), setValue];
     }
     var import_node_crypto5 = require("crypto");
-    var import_core6 = require("@kortyx/core");
+    var import_core62 = require("@kortyx/core");
     var import_node_crypto42 = require("crypto");
     function emitWorkflowCall2(telemetry, type, payload) {
       const base = telemetry?.correlation;
@@ -2472,7 +2496,7 @@ ${tryStringify2(args.response)}`
     }
     async function useWorkflow(args) {
       const ctx = getHookContext();
-      (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+      (0, import_core62.throwIfExecutionAborted)(ctx.node.abortSignal);
       const service = ctx.node.callWorkflow;
       if (!service)
         throw new Error("useWorkflow requires an agent workflow registry.");
@@ -2577,9 +2601,9 @@ ${tryStringify2(args.response)}`
               ...record.interrupts.length ? { response: record.interrupts.at(-1)?.response } : {}
             });
           } catch (error) {
-            (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
-            if ((0, import_core6.isExecutionCancelled)(error)) throw error;
-            if ((0, import_core6.isExecutionLimitReached)(error)) {
+            (0, import_core62.throwIfExecutionAborted)(ctx.node.abortSignal);
+            if ((0, import_core62.isExecutionCancelled)(error)) throw error;
+            if ((0, import_core62.isExecutionLimitReached)(error)) {
               const child = error;
               if (child.__kortyxChildSnapshot)
                 record.snapshot = child.__kortyxChildSnapshot;
@@ -2595,7 +2619,7 @@ ${tryStringify2(args.response)}`
             report("failed", { error: "Child workflow failed" });
             throw new WorkflowCallError(workflow, record.error);
           }
-          (0, import_core6.throwIfExecutionAborted)(ctx.node.abortSignal);
+          (0, import_core62.throwIfExecutionAborted)(ctx.node.abortSignal);
           recordUsage(outcome.usage);
           if (outcome.status === "completed") {
             record.data = outcome.data;
@@ -2719,6 +2743,7 @@ function parseCheckpointRequestBody(value) {
 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,
@@ -2742,7 +2767,8 @@ function createChatRouteHandler(args) {
       return await handleChatRequestBody({
         agent,
         body,
-        abortSignal: request.signal
+        abortSignal: request.signal,
+        onExecution: args.onExecution
       });
     } catch (error) {
       return new Response(
@@ -2809,23 +2835,23 @@ async function* streamChatFromRoute(args) {
 
 // src/chat/create-agent.ts
 var import_node_path = require("path");
-var import_core4 = require("@kortyx/core");
+var import_core5 = require("@kortyx/core");
 var import_providers = require("@kortyx/providers");
 var import_runtime5 = require("@kortyx/runtime");
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 
 // src/execution/execute.ts
-var import_core3 = require("@kortyx/core");
+var import_core4 = require("@kortyx/core");
 var import_runtime3 = require("@kortyx/runtime");
 var import_zod3 = require("zod");
 
 // src/interrupt/resume-handler.ts
-var import_core2 = require("@kortyx/core");
+var import_core3 = require("@kortyx/core");
 var import_runtime2 = require("@kortyx/runtime");
 
 // src/orchestrator.ts
 var import_node_stream = require("stream");
-var import_core = require("@kortyx/core");
+var import_core2 = require("@kortyx/core");
 var import_runtime = require("@kortyx/runtime");
 var import_langgraph = require("@langchain/langgraph");
 
@@ -2907,6 +2933,47 @@ async function validateExecutionOutput(state, select) {
   return { ...state, data };
 }
 
+// src/stream/response-lifecycle.ts
+var import_core = require("@kortyx/core");
+function createResponseLifecycle(args) {
+  const controller = new AbortController();
+  let closed = args.restored;
+  let completing;
+  const abort = () => controller.abort();
+  const detachRequest = () => args.requestSignal?.removeEventListener("abort", abort);
+  if (!closed) {
+    args.requestSignal?.addEventListener("abort", abort, { once: true });
+    if (args.requestSignal?.aborted) abort();
+  }
+  args.executionSignal?.addEventListener("abort", abort, { once: true });
+  if (args.executionSignal?.aborted) abort();
+  return {
+    get closed() {
+      return closed;
+    },
+    signal: controller.signal,
+    disconnect() {
+      if (!closed) abort();
+    },
+    dispose() {
+      detachRequest();
+      args.executionSignal?.removeEventListener("abort", abort);
+    },
+    complete(options, state) {
+      if (!args.enabled || closed) return Promise.resolve();
+      completing ??= (async () => {
+        (0, import_core.throwIfExecutionAborted)(controller.signal);
+        await args.finalize(options, state);
+        (0, import_core.throwIfExecutionAborted)(controller.signal);
+        closed = true;
+        detachRequest();
+        args.onClosed();
+      })();
+      return completing;
+    }
+  };
+}
+
 // src/stream/transform-graph-stream-for-ui.ts
 var isGraphStateOutput = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && "currentWorkflow" in value;
 async function* transformGraphStreamForUI(stream, options = {}) {
@@ -3263,6 +3330,8 @@ async function orchestrateGraphStream({
   state,
   config: initialConfig,
   abortSignal: requestSignal,
+  executionSignal,
+  onExecution,
   emitOutput = true,
   onOutcome,
   selectWorkflow,
@@ -3271,20 +3340,88 @@ async function orchestrateGraphStream({
 }) {
   const out = new import_node_stream.PassThrough({ objectMode: true });
   const write = (chunk) => {
-    if (emitOutput && !out.destroyed) out.write(chunk);
+    if (emitOutput && !response.closed && !out.destroyed) out.write(chunk);
   };
   let outcomeState = state;
   let outcomeError;
-  let sessionCheckpointId;
+  let sessionCheckpointId = initialConfig.responseCheckpointId;
   let config = initialConfig;
   const budget = config.executionBudget;
   let currentGraph = graph;
   let currentState = state;
   let finished = false;
-  const controller = new AbortController();
-  const abortSignal = (0, import_core.combineAbortSignals)(requestSignal, controller.signal);
+  const response = createResponseLifecycle({
+    enabled: emitOutput,
+    restored: initialConfig.responseCompleted === true,
+    requestSignal,
+    executionSignal,
+    onClosed: () => {
+      out.write({ type: "done" });
+      out.end();
+    },
+    finalize: async (options, nodeState) => {
+      const snapshot = JSON.parse(JSON.stringify(nodeState));
+      delete snapshot.config.responseCompleted;
+      delete snapshot.config.responseCheckpointId;
+      if (options.message !== void 0) {
+        forwardEmit("message", {
+          node: nodeState.lastNode,
+          content: options.message
+        });
+      }
+      if (options.data !== void 0) {
+        forwardEmit("structured_data", {
+          node: nodeState.lastNode,
+          data: options.data
+        });
+      }
+      if (sessionId && frameworkAdapter) {
+        const checkpoint = await frameworkAdapter.sessionCheckpoints.append({
+          sessionId,
+          runId,
+          workflow: String(snapshot.currentWorkflow),
+          state: snapshot,
+          nodes: [...touchedNodes],
+          structuredStreamIds: [...structuredStreamIds],
+          pendingRequests: []
+        });
+        sessionCheckpointId = checkpoint.id;
+        write({
+          type: "checkpoint",
+          id: checkpoint.id,
+          sessionId,
+          turnIndex: checkpoint.turnIndex
+        });
+        emitTelemetryEvent({
+          config,
+          type: "session.checkpointed",
+          payload: {
+            checkpointId: checkpoint.id,
+            turnIndex: checkpoint.turnIndex,
+            nodes: checkpoint.nodes
+          }
+        });
+      }
+      (0, import_core2.throwIfExecutionAborted)(abortSignal);
+      config.responseCompleted = true;
+      config.responseCheckpointId = sessionCheckpointId;
+      currentState.config.responseCompleted = true;
+      nodeState.config.responseCompleted = true;
+      currentGraph.config.responseCompleted = true;
+      emitTelemetryEvent({
+        config,
+        type: "response.completed",
+        payload: {
+          nodeId: nodeState.lastNode,
+          checkpointId: sessionCheckpointId
+        },
+        flush: true
+      });
+    }
+  });
+  const abortSignal = response.signal;
   out.on("close", () => {
-    if (!finished) controller.abort();
+    if (!finished) response.disconnect();
   });
   let structuredSeq = 0;
   const debugEnabled = Boolean(config?.features?.tracing);
@@ -3370,19 +3507,22 @@ async function orchestrateGraphStream({
   const pendingStore = frameworkAdapter?.pendingRequests;
   const sealPendingSnapshots = async () => {
     if (budget) outcomeState.config.executionBudget = budget;
+    if (response.closed) outcomeState.config.responseCompleted = true;
     if (typeof frameworkAdapter?.checkpointer?.getTuple !== "function") return;
     for (const [token, request] of activePendingRequests) {
       if (budget) request.state.config.executionBudget = budget;
+      if (response.closed) request.state.config.responseCompleted = true;
       const graphSnapshot = await (0, import_runtime.captureGraphSnapshot)(
         frameworkAdapter.checkpointer,
         runId,
         request.graphCheckpointId
       );
       if (graphSnapshot) {
-        const sealed = { ...request, graphSnapshot };
+        const sealed = { ...request, graphSnapshot, ready: true };
         activePendingRequests.set(token, sealed);
         await pendingStore?.update(token, {
           graphSnapshot,
+          ready: true,
           state: request.state
         });
       }
@@ -3400,6 +3540,8 @@ async function orchestrateGraphStream({
     const isText = kind === "text";
     const record = {
       token,
+      ready: false,
+      responseCompleted: response.closed,
       requestId,
       sessionId,
       runId,
@@ -3478,6 +3620,7 @@ async function orchestrateGraphStream({
         workflowCallPath: record.schema.meta?.workflowCallPath ?? null,
         branchId: config.executionBranchId ?? runId,
         interruptId: record.requestId,
+        responseCompleted: response.closed,
         requestId: record.requestId,
         kind: record.schema.kind,
         interactionMode: record.schema.kind === "text" ? "freeform" : record.options.length > 0 ? "static-options" : record.schema.schemaId ? "dynamic-picker" : "unknown",
@@ -3687,7 +3830,7 @@ async function orchestrateGraphStream({
   };
   const runLoop = async (runTraceSpan) => {
     while (true) {
-      (0, import_core.throwIfExecutionAborted)(abortSignal);
+      (0, import_core2.throwIfExecutionAborted)(abortSignal);
       let workflowFinalState = null;
       let workflowFinalGraphCheckpointId;
       let sawWorkflowDone = false;
@@ -3695,6 +3838,7 @@ async function orchestrateGraphStream({
       currentGraph.execution ??= {};
       currentGraph.execution.abortSignal = abortSignal;
       currentGraph.execution.budget = budget;
+      currentGraph.execution.completeResponse = response.complete;
       currentGraph.config = currentGraph.config || {};
       currentGraph.config.emit = forwardEmit;
       currentGraph.config.executionRunId = runId;
@@ -3792,7 +3936,7 @@ async function orchestrateGraphStream({
         workflowFinalGraphCheckpointId = graphSnapshot?.checkpointId;
         workflowFinalState = isGraphState(workflowDoneData) ? workflowDoneData : graphSnapshot?.state ?? currentState;
       }
-      (0, import_core.throwIfExecutionAborted)(abortSignal);
+      (0, import_core2.throwIfExecutionAborted)(abortSignal);
       const transitionTo = pending.to;
       const transitionPayload = pending.payload;
       const sourceNodeId = pending.sourceNodeId;
@@ -3857,8 +4001,8 @@ async function orchestrateGraphStream({
           currentGraph = nextGraph;
           continue;
         } catch (err) {
-          (0, import_core.throwIfExecutionAborted)(abortSignal);
-          if ((0, import_core.isExecutionCancelled)(err)) throw err;
+          (0, import_core2.throwIfExecutionAborted)(abortSignal);
+          if ((0, import_core2.isExecutionCancelled)(err)) throw err;
           outcomeError = err;
           runTraceSpan.fail?.(err);
           runTraceSpan.addEvent?.("kortyx.transition.error", {
@@ -3932,7 +4076,7 @@ async function orchestrateGraphStream({
         runTraceSpan.end?.(runTraceEndArgs());
         const resolvedSessionId2 = config?.session?.id || sessionId || "";
         await sealPendingSnapshots();
-        if (resolvedSessionId2 && frameworkAdapter?.sessionCheckpoints) {
+        if (!response.closed && resolvedSessionId2 && frameworkAdapter?.sessionCheckpoints) {
           try {
             const checkpoint = await frameworkAdapter.sessionCheckpoints.append(
               {
@@ -4003,7 +4147,7 @@ async function orchestrateGraphStream({
       }
       const resolvedSessionId = config?.session?.id || sessionId || "";
       await sealPendingSnapshots();
-      if (resolvedSessionId && frameworkAdapter?.sessionCheckpoints) {
+      if (!response.closed && resolvedSessionId && frameworkAdapter?.sessionCheckpoints) {
         try {
           const checkpoint = await frameworkAdapter.sessionCheckpoints.append({
             sessionId: resolvedSessionId,
@@ -4087,7 +4231,7 @@ async function orchestrateGraphStream({
     } catch (cleanupError) {
       console.error("[cancel:cleanupRun]", cleanupError);
     }
-    outcomeError = (0, import_core.createExecutionCancelledError)();
+    outcomeError = (0, import_core2.createExecutionCancelledError)();
     fallbackRunSpan?.setAttributes?.({ "kortyx.run.cancelled": true });
     fallbackRunSpan?.end?.();
     write({ type: "cancelled", runId, reason: "Execution cancelled." });
@@ -4095,15 +4239,15 @@ async function orchestrateGraphStream({
     finished = true;
     out.end();
   };
-  runPromise.catch(async (err) => {
-    if (abortSignal?.aborted || (0, import_core.isExecutionCancelled)(err)) {
+  const completion = runPromise.catch(async (err) => {
+    if (abortSignal?.aborted || (0, import_core2.isExecutionCancelled)(err)) {
       await finishCancelled();
       return;
     }
-    if ((0, import_core.isExecutionLimitReached)(err)) {
+    if ((0, import_core2.isExecutionLimitReached)(err)) {
       try {
         const snapshot = frameworkAdapter && await (0, import_runtime.captureGraphSnapshot)(frameworkAdapter.checkpointer, runId);
-        (0, import_core.throwIfExecutionAborted)(abortSignal);
+        (0, import_core2.throwIfExecutionAborted)(abortSignal);
         if (!snapshot)
           throw new Error(
             "Execution limit reached without a resumable checkpoint."
@@ -4145,46 +4289,50 @@ async function orchestrateGraphStream({
           }
         });
         await Promise.all(pendingRequestWrites);
-        (0, import_core.throwIfExecutionAborted)(abortSignal);
+        (0, import_core2.throwIfExecutionAborted)(abortSignal);
         if (outcomeError) throw outcomeError;
         const request = activePendingRequests.get(pendingRecordToken);
         const sealed = {
           ...request,
           state: pausedState,
           graphCheckpointId: snapshot.checkpoint.id,
-          graphSnapshot: snapshot
+          graphSnapshot: snapshot,
+          ready: true
         };
         activePendingRequests.set(request.token, sealed);
         await pendingStore?.update(request.token, sealed);
-        const checkpoint = await frameworkAdapter.sessionCheckpoints.append({
-          sessionId,
-          runId,
-          graphCheckpointId: snapshot.checkpoint.id,
-          workflow: String(pausedState.currentWorkflow),
-          state: pausedState,
-          nodes: Array.from(touchedNodes),
-          structuredStreamIds: Array.from(structuredStreamIds),
-          pendingRequests: [sealed],
-          label: "Execution limit reached"
-        });
-        (0, import_core.throwIfExecutionAborted)(abortSignal);
-        sessionCheckpointId = checkpoint.id;
-        write({
-          type: "checkpoint",
-          id: checkpoint.id,
-          sessionId: checkpoint.sessionId,
-          turnIndex: checkpoint.turnIndex,
-          label: checkpoint.label
-        });
-        emitTelemetryEvent({
-          config,
-          type: "session.checkpointed",
-          payload: {
-            checkpointId: checkpoint.id,
+        if (response.closed) pausedState.config.responseCompleted = true;
+        if (!response.closed) {
+          const checkpoint = await frameworkAdapter.sessionCheckpoints.append({
+            sessionId,
+            runId,
+            graphCheckpointId: snapshot.checkpoint.id,
+            workflow: String(pausedState.currentWorkflow),
+            state: pausedState,
+            nodes: Array.from(touchedNodes),
+            structuredStreamIds: Array.from(structuredStreamIds),
+            pendingRequests: [sealed],
+            label: "Execution limit reached"
+          });
+          (0, import_core2.throwIfExecutionAborted)(abortSignal);
+          sessionCheckpointId = checkpoint.id;
+          write({
+            type: "checkpoint",
+            id: checkpoint.id,
+            sessionId: checkpoint.sessionId,
             turnIndex: checkpoint.turnIndex,
-            nodes: checkpoint.nodes
-          }
-        });
+            label: checkpoint.label
+          });
+          emitTelemetryEvent({
+            config,
+            type: "session.checkpointed",
+            payload: {
+              checkpointId: checkpoint.id,
+              turnIndex: checkpoint.turnIndex,
+              nodes: checkpoint.nodes
+            }
+          });
+        }
         fallbackRunSpan?.setAttributes?.({
           "kortyx.run.awaiting_human_input": true,
           "kortyx.run.limit_reached": limitReached.limit
@@ -4195,7 +4343,7 @@ async function orchestrateGraphStream({
         out.end();
         return;
       } catch (pauseError) {
-        if (abortSignal?.aborted || (0, import_core.isExecutionCancelled)(pauseError)) {
+        if (abortSignal?.aborted || (0, import_core2.isExecutionCancelled)(pauseError)) {
           await finishCancelled();
           return;
         }
@@ -4220,6 +4368,7 @@ async function orchestrateGraphStream({
     finished = true;
     out.end();
   }).finally(() => {
+    response.dispose();
     onOutcome?.({
       state: outcomeState,
       pending: pendingRecordToken ? activePendingRequests.get(pendingRecordToken) : void 0,
@@ -4227,6 +4376,8 @@ async function orchestrateGraphStream({
       ...outcomeError ? { error: outcomeError } : {}
     });
   });
+  onExecution?.(completion);
+  if (response.closed) out.end();
   return out;
 }
 
@@ -4258,6 +4409,8 @@ function parseResumeMeta(msg) {
 async function tryPrepareResumeStream({
   limits,
   abortSignal,
+  executionSignal,
+  onExecution,
   lastMessage,
   meta: suppliedMeta,
   emitOutput,
@@ -4286,11 +4439,11 @@ async function tryPrepareResumeStream({
   await validatePending?.(pending);
   const isLimitPause = Boolean(pending.schema.meta?.__kortyxExecutionLimit);
   const savedBudget = pending.state?.config?.executionBudget;
-  const resumedBudget = savedBudget && isLimitPause && !meta.cancel ? (0, import_core2.restartExecutionBudget)(savedBudget, limits) : savedBudget;
+  const resumedBudget = savedBudget && isLimitPause && !meta.cancel ? (0, import_core3.restartExecutionBudget)(savedBudget, limits) : savedBudget;
   if (abortSignal?.aborted) {
     onOutcome?.({
       state: pending.state,
-      error: (0, import_core2.createExecutionCancelledError)()
+      error: (0, import_core3.createExecutionCancelledError)()
     });
     return (async function* () {
       yield {
@@ -4351,6 +4504,10 @@ async function tryPrepareResumeStream({
     const telemetryConfig = prepareWorkflowTelemetry({
       config: {
         ...config,
+        ...pending.responseCompleted ? {
+          responseCompleted: true,
+          responseCheckpointId: pending.state?.config?.responseCheckpointId
+        } : {},
         ...resumedBudget ? { executionBudget: resumedBudget } : {},
         ...pending.state?.config?.context ? { context: pending.state.config.context } : {},
         ...pending.state?.config?.executionContract ? { executionContract: pending.state.config.executionContract } : {},
@@ -4427,6 +4584,8 @@ async function tryPrepareResumeStream({
     });
     const args = {
       abortSignal,
+      executionSignal: pending.responseCompleted && emitOutput === false ? abortSignal : executionSignal,
+      onExecution,
       emitOutput,
       onOutcome,
       sessionId,
@@ -4477,7 +4636,7 @@ function resultFromOutcome(outcome, runId, sessionId) {
     ...outcome.checkpointId ? { checkpointId: outcome.checkpointId } : {},
     ...usage ? { usage } : {}
   };
-  if ((0, import_core3.isExecutionCancelled)(outcome.error))
+  if ((0, import_core4.isExecutionCancelled)(outcome.error))
     return { ...info, status: "cancelled", reason: "Execution cancelled." };
   if (outcome.error) {
     const error = outcome.error;
@@ -4554,7 +4713,7 @@ async function executeWorkflow(services, args) {
     config: {
       ...runtimeConfig(services, sessionId, args.context),
       ...services.limits || args.limits ? {
-        executionBudget: (0, import_core3.createExecutionBudget)(
+        executionBudget: (0, import_core4.createExecutionBudget)(
           services.limits,
           args.limits
         )
@@ -4575,7 +4734,7 @@ async function executeWorkflow(services, args) {
   return new Promise((resolve2) => {
     const onOutcome = (outcome) => resolve2(resultFromOutcome(outcome, runId, sessionId));
     void (async () => {
-      (0, import_core3.throwIfExecutionAborted)(args.abortSignal);
+      (0, import_core4.throwIfExecutionAborted)(args.abortSignal);
       const graph = await (0, import_runtime3.createExecutionGraph)(workflow, config);
       await orchestrateGraphStream({
         graph,
@@ -4670,6 +4829,98 @@ async function resumeWorkflow(services, args) {
   });
 }
 
+// src/interrupt/discovery.ts
+var import_zod4 = require("zod");
+var scopeSchema = import_zod4.z.object({
+  sessionId: import_zod4.z.string().min(1).optional(),
+  runId: import_zod4.z.string().min(1).optional(),
+  context: import_zod4.z.record(
+    import_zod4.z.string(),
+    import_zod4.z.union([import_zod4.z.string(), import_zod4.z.number(), import_zod4.z.boolean(), import_zod4.z.null()])
+  ).optional()
+}).strict().refine(
+  (scope) => Boolean(
+    scope.sessionId || scope.runId || Object.keys(scope.context ?? {}).length
+  ),
+  "Interrupt discovery requires an authorized session, run, or context scope."
+);
+var matches = (record, scope) => record.ready !== false && Date.now() < record.createdAt + record.ttlMs && (!scope.sessionId || record.sessionId === scope.sessionId) && (!scope.runId || record.runId === scope.runId) && Object.entries(scope.context ?? {}).every(
+  ([key, value]) => record.state?.config.context?.[key] === value
+);
+var summary = (record) => {
+  const { meta: _meta, ...input } = record.schema;
+  const contract = record.state?.config.executionContract;
+  return {
+    id: record.requestId,
+    status: "pending",
+    runId: record.runId,
+    sessionId: record.sessionId ?? "",
+    workflow: contract?.id ?? record.workflow,
+    node: record.node,
+    createdAt: new Date(record.createdAt).toISOString(),
+    expiresAt: new Date(record.createdAt + record.ttlMs).toISOString(),
+    afterResponseCompleted: record.responseCompleted === true,
+    input: {
+      ...input,
+      options: record.options.map(({ id, label, description }) => ({
+        id,
+        label,
+        ...description !== void 0 ? { description } : {}
+      }))
+    }
+  };
+};
+function createInterruptDiscovery(store) {
+  const records = () => {
+    if (!store.list)
+      throw new Error(
+        "This persistence adapter does not support interrupt discovery; implement pendingRequests.list."
+      );
+    return store.list();
+  };
+  return {
+    async listInterrupts(options) {
+      const {
+        status: _status,
+        afterResponseCompleted,
+        ...scope
+      } = import_zod4.z.object({
+        sessionId: import_zod4.z.string().optional(),
+        runId: import_zod4.z.string().optional(),
+        context: import_zod4.z.record(
+          import_zod4.z.string(),
+          import_zod4.z.union([import_zod4.z.string(), import_zod4.z.number(), import_zod4.z.boolean(), import_zod4.z.null()])
+        ).optional(),
+        status: import_zod4.z.literal("pending").optional(),
+        afterResponseCompleted: import_zod4.z.boolean().optional()
+      }).strict().parse(options);
+      scopeSchema.parse(scope);
+      return (await records()).filter(
+        (record) => matches(record, scope) && (afterResponseCompleted === void 0 || record.responseCompleted === true === afterResponseCompleted)
+      ).sort(
+        (a, b) => a.createdAt - b.createdAt || a.requestId.localeCompare(b.requestId)
+      ).map(summary);
+    },
+    async getInterrupt(id, scope) {
+      import_zod4.z.string().min(1).parse(id);
+      scopeSchema.parse(scope);
+      const record = (await records()).find(
+        (record2) => record2.requestId === id && matches(record2, scope)
+      );
+      if (!record) return null;
+      return {
+        ...summary(record),
+        resume: {
+          token: record.token,
+          requestId: record.requestId,
+          sessionId: record.sessionId ?? "",
+          runId: record.runId
+        }
+      };
+    }
+  };
+}
+
 // src/telemetry/workflow-call-branch.ts
 var import_node_crypto3 = require("crypto");
 var import_hooks = __toESM(require_dist());
@@ -4742,6 +4993,8 @@ function extractLatestUserMessage(messages) {
 async function streamChat({
   messages,
   abortSignal,
+  executionSignal,
+  onExecution,
   options,
   sessionId,
   defaultWorkflowId,
@@ -4789,6 +5042,8 @@ async function streamChat({
   }
   const resumeStream = await tryPrepareResumeStream({
     abortSignal,
+    executionSignal,
+    onExecution,
     lastMessage: last,
     sessionId: resolvedSessionId,
     config: runtimeConfig2,
@@ -4860,6 +5115,8 @@ async function streamChat({
   };
   const orchestratedStream = await orchestrateGraphStream({
     abortSignal,
+    executionSignal,
+    onExecution,
     sessionId: resolvedSessionId,
     runId,
     graph,
@@ -4873,22 +5130,26 @@ async function streamChat({
 }
 
 // src/chat/create-agent.ts
-var agentProcessOptionsSchema = import_zod4.z.object({
-  limits: import_core4.ExecutionLimitsSchema.optional(),
-  abortSignal: import_zod4.z.custom((value) => value instanceof AbortSignal).optional(),
-  sessionId: import_zod4.z.string().optional(),
-  workflowId: import_zod4.z.string().optional(),
-  context: import_zod4.z.record(import_zod4.z.string(), import_zod4.z.unknown()).optional()
+var agentProcessOptionsSchema = import_zod5.z.object({
+  executionSignal: import_zod5.z.custom((value) => value instanceof AbortSignal).optional(),
+  onExecution: 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(),
+  workflowId: import_zod5.z.string().optional(),
+  context: import_zod5.z.record(import_zod5.z.string(), import_zod5.z.unknown()).optional()
 }).strict();
-var createAgentArgsBaseSchema = import_zod4.z.object({
-  limits: import_core4.ExecutionLimitsSchema.optional(),
-  getProvider: import_zod4.z.unknown().optional(),
-  workflows: import_zod4.z.array(import_zod4.z.unknown()).optional(),
-  workflowsDir: import_zod4.z.string().optional(),
-  workflowRegistry: import_zod4.z.unknown().optional(),
-  defaultWorkflowId: import_zod4.z.string().optional(),
-  frameworkAdapter: import_zod4.z.unknown().optional(),
-  telemetry: import_zod4.z.unknown().optional()
+var createAgentArgsBaseSchema = import_zod5.z.object({
+  limits: import_core5.ExecutionLimitsSchema.optional(),
+  getProvider: import_zod5.z.unknown().optional(),
+  workflows: import_zod5.z.array(import_zod5.z.unknown()).optional(),
+  workflowsDir: import_zod5.z.string().optional(),
+  workflowRegistry: import_zod5.z.unknown().optional(),
+  defaultWorkflowId: import_zod5.z.string().optional(),
+  frameworkAdapter: import_zod5.z.unknown().optional(),
+  telemetry: import_zod5.z.unknown().optional()
 }).strict();
 var createAgentArgsSchema = createAgentArgsBaseSchema.superRefine(
   (value, ctx) => {
@@ -5018,6 +5279,8 @@ function createAgent(args) {
       ...resolvedDefaultWorkflowId ? { defaultWorkflowId: resolvedDefaultWorkflowId } : {},
       messages,
       abortSignal: parsedOptions?.abortSignal,
+      executionSignal: parsedOptions?.executionSignal,
+      onExecution: parsedOptions?.onExecution,
       options: parsedOptions,
       workflowRegistry: registry,
       ...knownWorkflowIds ? { knownWorkflowIds } : {},
@@ -5025,7 +5288,7 @@ function createAgent(args) {
       getProvider: resolvedGetProvider,
       loadRuntimeConfig: (runtimeOptions) => ({
         ...limits || runtimeOptions?.limits ? {
-          executionBudget: (0, import_core4.createExecutionBudget)(
+          executionBudget: (0, import_core5.createExecutionBudget)(
             limits,
             runtimeOptions?.limits
           )
@@ -5147,6 +5410,7 @@ function createAgent(args) {
   const execute = (async (options) => executeWorkflow(await services(), options));
   const resume = (async (options) => resumeWorkflow(await services(), options));
   return {
+    ...createInterruptDiscovery(resolvedFrameworkAdapter.pendingRequests),
     execute,
     resume,
     projectTopology,