@kortyx/agent 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.24.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.23.0...agent-v0.24.0) (2026-09-16)
+
+
+### Features
+
+* **runtime:** add PostgreSQL persistence, caching composition, and retention ([#207](https://github.com/kortyx-io/kortyx/issues/207)) ([6c1e7df](https://github.com/kortyx-io/kortyx/commit/6c1e7df22ffe8c792bf52b7dba5ae6ea04c1eb2a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/runtime bumped to 0.19.0
+  * devDependencies
+    * @kortyx/hooks bumped to 0.25.3
+
 ## [0.23.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.22.2...agent-v0.23.0) (2026-09-16)
 
 

package/dist/index.d.ts

@@ -254,6 +254,8 @@ type OrchestrationOutcome = {
     error?: unknown;
 };
 interface OrchestrateArgs {
+    /** Resume owns the lease while restoring its snapshot, then transfers it to execution. */
+    executionLeaseRelease?: (() => Promise<void>) | undefined;
     executionSignal?: AbortSignal | undefined;
     onExecution?: ((completion: Promise<void>) => void) | undefined;
     abortSignal?: AbortSignal | undefined;
@@ -272,7 +274,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, }: OrchestrateArgs): Promise<NodeJS.ReadableStream>;
+declare function orchestrateGraphStream({ sessionId, runId, graph, state, config: initialConfig, abortSignal: requestSignal, executionSignal, onExecution, emitOutput, onOutcome, selectWorkflow, knownWorkflowIds, frameworkAdapter, executionLeaseRelease, }: OrchestrateArgs): Promise<NodeJS.ReadableStream>;
 
 interface ResumeMeta {
     token: string;

package/dist/index.js

@@ -3894,7 +3894,8 @@ async function orchestrateGraphStream({
   onOutcome,
   selectWorkflow,
   knownWorkflowIds,
-  frameworkAdapter
+  frameworkAdapter,
+  executionLeaseRelease
 }) {
   const out = new import_node_stream.PassThrough({ objectMode: true });
   const write = (chunk) => {
@@ -3912,11 +3913,13 @@ async function orchestrateGraphStream({
   let currentGraph = graph;
   let currentState = state;
   let finished = false;
+  const leaseAbort = new AbortController();
+  let releaseLease = executionLeaseRelease;
   const response = createResponseLifecycle({
     enabled: emitOutput,
     restored: initialConfig.responseCompleted === true,
     requestSignal,
-    executionSignal,
+    executionSignal: executionSignal ? AbortSignal.any([executionSignal, leaseAbort.signal]) : leaseAbort.signal,
     onClosed: () => {
       out.write({ type: "done" });
       out.end();
@@ -4795,10 +4798,18 @@ async function orchestrateGraphStream({
   if (!traceAdapter?.withSpan) {
     emitTraceChunk();
   }
-  const runPromise = traceAdapter?.withSpan ? traceAdapter.withSpan(runSpanArgs, (runTraceSpan) => {
+  const startRun = () => traceAdapter?.withSpan ? traceAdapter.withSpan(runSpanArgs, (runTraceSpan) => {
     emitTraceChunk();
     return runLoop(runTraceSpan);
   }) : runLoop(fallbackRunSpan ?? {});
+  const runPromise = frameworkAdapter?.acquireRunLease && !releaseLease ? frameworkAdapter.acquireRunLease({
+    runId,
+    ...sessionId ? { sessionId } : {},
+    onLost: (cause) => leaseAbort.abort(cause)
+  }).then((release) => {
+    releaseLease = release;
+    return startRun();
+  }) : startRun();
   const finishCancelled = async () => {
     emitTelemetryEvent({
       config,
@@ -4962,7 +4973,12 @@ async function orchestrateGraphStream({
     write({ type: "done" });
     finished = true;
     out.end();
-  }).finally(() => {
+  }).finally(async () => {
+    try {
+      await releaseLease?.();
+    } catch (error) {
+      console.error("[execution:releaseLease]", (0, import_errors4.serializeFailure)(error));
+    }
     response.dispose();
     onOutcome?.({
       state: outcomeState,
@@ -5023,7 +5039,7 @@ async function tryPrepareResumeStream({
   if (!meta) return null;
   const store = frameworkAdapter?.pendingRequests;
   if (!store) return null;
-  const pending = await store.get(meta.token);
+  let pending = await store.get(meta.token);
   if (!pending || pending.requestId !== meta.requestId) {
     throw new ExecutionRequestError(
       "INVALID_RESUME",
@@ -5053,34 +5069,48 @@ async function tryPrepareResumeStream({
       yield { type: "done" };
     })();
   }
-  if (store.take && !await store.take(meta.token))
-    throw new ExecutionRequestError(
-      "INVALID_RESUME",
-      "Interrupt has already been resumed or cancelled."
-    );
-  if (meta.cancel) {
-    await store.delete(pending.token);
-    emitTelemetryEvent({
-      config,
-      type: "interrupt.cancelled",
-      correlation: {
-        runId: pending.runId,
-        sessionId,
-        workflowId: pending.workflow,
-        nodeId: pending.node
-      },
-      payload: {
-        interruptId: pending.requestId,
-        reason: "cancelled_by_client"
-      },
-      flush: true
-    });
-    onOutcome?.({ state: pending.state, cancelled: true });
-    return (async function* () {
-      yield { type: "done" };
-    })();
-  }
+  const leaseAbort = new AbortController();
+  let releaseLease;
+  let consumed = false;
   try {
+    releaseLease = await frameworkAdapter?.acquireRunLease?.({
+      runId: pending.runId,
+      sessionId,
+      onLost: (cause) => leaseAbort.abort(cause)
+    });
+    leaseAbort.signal.throwIfAborted();
+    if (store.take) {
+      const taken = await store.take(meta.token);
+      if (!taken)
+        throw new ExecutionRequestError(
+          "INVALID_RESUME",
+          "Interrupt has already been resumed or cancelled."
+        );
+      pending = taken;
+    }
+    consumed = true;
+    if (meta.cancel) {
+      await store.delete(pending.token);
+      emitTelemetryEvent({
+        config,
+        type: "interrupt.cancelled",
+        correlation: {
+          runId: pending.runId,
+          sessionId,
+          workflowId: pending.workflow,
+          nodeId: pending.node
+        },
+        payload: {
+          interruptId: pending.requestId,
+          reason: "cancelled_by_client"
+        },
+        flush: true
+      });
+      onOutcome?.({ state: pending.state, cancelled: true });
+      return (async function* () {
+        yield { type: "done" };
+      })();
+    }
     const resumeData = isLimitPause ? {} : applyResumeSelection ? applyResumeSelection({ pending, selected: meta.selected }) : meta.selected?.length ? { coordinates: String(meta.selected[0]) } : {};
     const resumeDataPatch = isRecord4(resumeData) ? resumeData : {};
     const pendingMeta = isRecord4(pending.schema?.meta) ? pending.schema.meta : {};
@@ -5135,6 +5165,7 @@ async function tryPrepareResumeStream({
           ...resumeStatePatch
         };
     }
+    leaseAbort.signal.throwIfAborted();
     if (pending.graphSnapshot && frameworkAdapter)
       await (0, import_runtime2.restoreGraphSnapshot)(
         frameworkAdapter.checkpointer,
@@ -5184,9 +5215,11 @@ async function tryPrepareResumeStream({
       },
       flush: true
     });
+    const continuedSignal = pending.responseCompleted && emitOutput === false ? abortSignal : executionSignal;
     const args = {
       abortSignal,
-      executionSignal: pending.responseCompleted && emitOutput === false ? abortSignal : executionSignal,
+      executionSignal: continuedSignal ? AbortSignal.any([continuedSignal, leaseAbort.signal]) : leaseAbort.signal,
+      executionLeaseRelease: releaseLease,
       onExecution,
       emitOutput,
       onOutcome,
@@ -5207,11 +5240,15 @@ async function tryPrepareResumeStream({
       knownWorkflowIds,
       frameworkAdapter
     };
+    leaseAbort.signal.throwIfAborted();
     const stream = await orchestrateGraphStream(args);
+    releaseLease = void 0;
     return stream;
   } catch (error) {
-    await store.save(pending);
+    if (consumed && !leaseAbort.signal.aborted) await store.save(pending);
     throw error;
+  } finally {
+    await releaseLease?.();
   }
 }
 
@@ -5907,30 +5944,38 @@ function createAgent(args) {
   const getCheckpoint = (id) => resolvedFrameworkAdapter.sessionCheckpoints.get(id);
   const rollbackTo = async (id) => {
     const target = await resolvedFrameworkAdapter.sessionCheckpoints.get(id);
-    const result = await resolvedFrameworkAdapter.sessionCheckpoints.rollbackTo(id);
-    const activePendingRequests = await Promise.all(
-      result.activePendingRequests.map(
-        (request) => hydratePendingGraphCheckpoint(resolvedFrameworkAdapter, request)
-      )
-    );
-    restoreWorkflowCallBranch(
-      activePendingRequests,
-      telemetry,
-      target?.runId ?? "unknown"
-    );
-    await Promise.all(
-      activePendingRequests.map(
-        (request) => clearPendingGraphWrites(resolvedFrameworkAdapter, request)
-      )
+    const sourceRunId = target?.runId ?? "unknown";
+    const managed = resolvedFrameworkAdapter.sessionCheckpoints.managesPendingRequests;
+    const result = await resolvedFrameworkAdapter.sessionCheckpoints.rollbackTo(
+      id,
+      managed ? {
+        preparePendingRequests: (requests) => restoreWorkflowCallBranch(requests, telemetry, sourceRunId)
+      } : void 0
     );
-    await Promise.all([
-      ...result.invalidatedInterruptTokens.map(
-        (token) => resolvedFrameworkAdapter.pendingRequests.delete(token)
-      ),
-      ...activePendingRequests.map(
-        (request) => resolvedFrameworkAdapter.pendingRequests.save(request)
-      )
-    ]);
+    let activePendingRequests;
+    if (managed) {
+      activePendingRequests = result.activePendingRequests;
+    } else {
+      activePendingRequests = await Promise.all(
+        result.activePendingRequests.map(
+          (request) => hydratePendingGraphCheckpoint(resolvedFrameworkAdapter, request)
+        )
+      );
+      restoreWorkflowCallBranch(activePendingRequests, telemetry, sourceRunId);
+      await Promise.all(
+        activePendingRequests.map(
+          (request) => clearPendingGraphWrites(resolvedFrameworkAdapter, request)
+        )
+      );
+      await Promise.all([
+        ...result.invalidatedInterruptTokens.map(
+          (token) => resolvedFrameworkAdapter.pendingRequests.delete(token)
+        ),
+        ...activePendingRequests.map(
+          (request) => resolvedFrameworkAdapter.pendingRequests.save(request)
+        )
+      ]);
+    }
     if (target) {
       emitTelemetryEvent({
         config: { ...telemetry ? { telemetry } : {} },
@@ -5950,30 +5995,36 @@ function createAgent(args) {
   };
   const fork = async (id, options) => {
     const source = await resolvedFrameworkAdapter.sessionCheckpoints.get(id);
+    const sourceRunId = source?.runId ?? "unknown";
+    const managed = resolvedFrameworkAdapter.sessionCheckpoints.managesPendingRequests;
     const result = await resolvedFrameworkAdapter.sessionCheckpoints.fork(
       id,
-      options
-    );
-    const activePendingRequests = await Promise.all(
-      result.checkpoint.activePendingRequests.map(
-        (request) => hydratePendingGraphCheckpoint(resolvedFrameworkAdapter, request)
-      )
-    );
-    restoreWorkflowCallBranch(
-      activePendingRequests,
-      telemetry,
-      source?.runId ?? "unknown"
-    );
-    await Promise.all(
-      activePendingRequests.map(
-        (request) => clearPendingGraphWrites(resolvedFrameworkAdapter, request)
-      )
-    );
-    await Promise.all(
-      activePendingRequests.map(
-        (request) => resolvedFrameworkAdapter.pendingRequests.save(request)
-      )
+      managed ? {
+        ...options,
+        preparePendingRequests: (requests) => restoreWorkflowCallBranch(requests, telemetry, sourceRunId)
+      } : options
     );
+    let activePendingRequests;
+    if (managed) {
+      activePendingRequests = result.checkpoint.activePendingRequests;
+    } else {
+      activePendingRequests = await Promise.all(
+        result.checkpoint.activePendingRequests.map(
+          (request) => hydratePendingGraphCheckpoint(resolvedFrameworkAdapter, request)
+        )
+      );
+      restoreWorkflowCallBranch(activePendingRequests, telemetry, sourceRunId);
+      await Promise.all(
+        activePendingRequests.map(
+          (request) => clearPendingGraphWrites(resolvedFrameworkAdapter, request)
+        )
+      );
+      await Promise.all(
+        activePendingRequests.map(
+          (request) => resolvedFrameworkAdapter.pendingRequests.save(request)
+        )
+      );
+    }
     emitTelemetryEvent({
       config: { ...telemetry ? { telemetry } : {} },
       type: "session.forked",