@kortyx/agent 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -8,6 +8,30 @@
   event replay, explicit cancellation and optional PostgreSQL recovery.
 
 
+## [0.40.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.39.0...agent-v0.40.0) (2026-10-18)
+
+
+### Features
+
+* **studio:** drain evaluation workers and consumer endpoints safely ([#365](https://github.com/kortyx-io/kortyx/issues/365)) ([0bcd853](https://github.com/kortyx-io/kortyx/commit/0bcd85310f5ccf59772b2fa9ed4dd28d03394546))
+
+
+### Bug Fixes
+
+* retain workflow catalogs and text interrupt questions ([#369](https://github.com/kortyx-io/kortyx/issues/369)) ([7608f65](https://github.com/kortyx-io/kortyx/commit/7608f6503167ed94feda30a1f63db50f475557d6))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/runtime bumped to 0.26.0
+    * @kortyx/prompts bumped to 0.2.3
+    * @kortyx/usage-telemetry bumped to 0.5.0
+    * @kortyx/telemetry-contracts bumped to 0.19.0
+  * devDependencies
+    * @kortyx/hooks bumped to 0.35.1
+
 ## [0.39.0](https://github.com/kortyx-io/kortyx/compare/agent-v0.38.1...agent-v0.39.0) (2026-10-16)
 
 

package/README.md

@@ -9,6 +9,13 @@ Agent creation, chat route handlers, HTTP helpers, and stream orchestration for
 
 Most application code should import these APIs from `kortyx`. Use `@kortyx/agent` directly when you are building framework adapters or want the lower-level agent package without the full facade.
 
+Topology identity excludes handoffs inferred from JavaScript function source, so
+source publication and bundled execution share a revision even when bundling hides
+a target. Inferred handoffs and source-discovered child links remain catalog
+metadata. After upgrading the SDK and CLI, rebuild the application and republish
+its source catalog. Previously inferred handoffs can receive a new topology hash
+once; historical revisions and run references remain readable without migration.
+
 ## Install
 
 ```bash
@@ -112,6 +119,16 @@ The default memory store only survives within its process. See
 [execution resilience](../../docs/evals/execution-resilience.md) for configuration,
 retention, legacy compatibility and upgrade order.
 
+For planned retirement, `await handleEvals.drain()` stops new admissions and
+finishes accepted local/queued executions without aborting them. Keep HTTP and
+the store open for observation/cancellation; `close()` remains explicit abort.
+With one consumer, drain Studio workers first while the consumer still accepts
+later cases, then drain the consumer after Studio persists results. Overlapping
+consumers require a compatible replacement and shared durable execution storage.
+The built-in stores support this; custom `EvalExecutionStore` implementations need
+`queued` and `claimQueued` for drain. Upgrade agent and runtime together. See the
+linked guide for ordering, failure handling and resource lifetime.
+
 ### Evaluation settings and errors
 
 `createEvals` supports `defaults: { repetitions, concurrency, caseTimeoutMs }`,

package/dist/index.d.ts

@@ -294,6 +294,9 @@ declare function createEvalRouteHandler({ evals, serviceKey, maxCases, maxActive
     executionStore?: EvalExecutionStore;
     onExecution?: (completion: Promise<void>) => void;
 }): ((request: Request) => Promise<Response>) & {
+    /** Stop admissions and finish accepted jobs; keep HTTP/store alive for observers. */
+    drain: () => Promise<void>;
+    /** Explicitly abort local execution, then wait for cleanup. */
     close: () => Promise<void>;
 };
 

package/dist/index.js

@@ -165,7 +165,7 @@ var require_internal = __commonJS({
     var import_node2 = require("@kortyx/usage-telemetry/node");
     var package_default2 = {
       name: "@kortyx/hooks",
-      version: "0.35.0",
+      version: "0.35.1",
       private: false,
       description: "Lifecycle hooks and extension points for Kortyx.",
       keywords: [
@@ -801,7 +801,7 @@ var require_dist = __commonJS({
     var import_node2 = require("@kortyx/usage-telemetry/node");
     var package_default2 = {
       name: "@kortyx/hooks",
-      version: "0.35.0",
+      version: "0.35.1",
       private: false,
       description: "Lifecycle hooks and extension points for Kortyx.",
       keywords: [
@@ -5768,7 +5768,10 @@ var projectWorkflowTopology = (args) => {
     workflowId: args.workflow.id,
     nodes: nodes.map((node) => ({ id: node.id, ...node._execution })),
     edges,
-    transitions
+    // Handoffs inferred from function source are catalog enrichment. Bundlers
+    // can hide their targets without changing the executable graph. Keep the
+    // legacy empty list so graphs without inferred handoffs retain their hash.
+    transitions: []
   });
   const topologyHash = (0, import_node_crypto2.createHash)("sha256").update(JSON.stringify(hashInput)).digest("hex");
   return {
@@ -5847,7 +5850,7 @@ var import_node = require("@kortyx/usage-telemetry/node");
 // package.json
 var package_default = {
   name: "@kortyx/agent",
-  version: "0.39.0",
+  version: "0.40.0",
   private: false,
   description: "Agent composition utilities for Kortyx.",
   keywords: [
@@ -10875,8 +10878,32 @@ function createEvalExecutionTransport({
 }) {
   const owner = (0, import_node_crypto6.randomUUID)();
   const active = /* @__PURE__ */ new Map();
-  let ticking = false;
+  let ticking;
+  let draining = false;
   let stopped = false;
+  let drain;
+  let closing;
+  let retirementFailure;
+  const unsupportedRetirement = new Error(
+    "Execution store requires queued and claimQueued for graceful retirement."
+  );
+  const admissions = /* @__PURE__ */ new Set();
+  const heartbeats = /* @__PURE__ */ new Set();
+  const failedRetirement = () => {
+    retirementFailure ??= new Error(
+      "Consumer evaluation retirement could not be confirmed."
+    );
+  };
+  const finish = async (id3, state) => {
+    try {
+      await store.finish(id3, owner, state);
+      if ((await store.status(id3))?.state !== state)
+        throw new Error("Consumer completion was not confirmed.");
+    } catch (error) {
+      failedRetirement();
+      throw error;
+    }
+  };
   const key = (id3) => (0, import_node_crypto6.createHash)("sha256").update(`${scope}\0${id3}`).digest("hex");
   const fail = async (job, error) => {
     const issue2 = createEvalIssue("reporting", error);
@@ -10893,7 +10920,11 @@ function createEvalExecutionTransport({
     const timer2 = setInterval(() => {
       if (renewing) return;
       renewing = true;
-      void store.heartbeat(job.id, owner).then(
+      const pending = Promise.resolve().then(
+        () => store.heartbeat(job.id, owner)
+      );
+      heartbeats.add(pending);
+      void pending.then(
         (current) => {
           if (!current) controller.abort("lease-lost");
           else if (current.cancelRequested)
@@ -10901,6 +10932,7 @@ function createEvalExecutionTransport({
         },
         () => controller.abort("lease-lost")
       ).finally(() => {
+        heartbeats.delete(pending);
         renewing = false;
       });
     }, store.heartbeatIntervalMs);
@@ -10935,9 +10967,8 @@ function createEvalExecutionTransport({
         onProgress: (event) => store.append(job.id, owner, { type: "progress", event })
       });
       await store.append(job.id, owner, { type: "result", result });
-      await store.finish(
+      await finish(
         job.id,
-        owner,
         result.status === "cancelled" ? "cancelled" : "completed"
       );
     } catch (error) {
@@ -10954,12 +10985,12 @@ function createEvalExecutionTransport({
             }
           );
         await fail(job, error);
-        await store.finish(
+        await finish(
           job.id,
-          owner,
           controller.signal.reason === "user-cancelled" ? "cancelled" : "completed"
         );
       } catch {
+        failedRetirement();
       }
     } finally {
       clearInterval(timer2);
@@ -10967,25 +10998,30 @@ function createEvalExecutionTransport({
       active.delete(job.id);
     }
   };
-  const tick = async () => {
-    if (stopped || ticking) return;
-    ticking = true;
-    try {
-      while (!stopped) {
-        const job = await store.claim(owner, scope, limits);
-        if (!job) break;
-        const controller = new AbortController();
-        const completion = run(job, controller);
-        active.set(job.id, { controller, completion });
-        try {
-          onExecution?.(completion);
-        } catch {
+  const tick = (selected) => {
+    if (ticking) return Promise.resolve();
+    if (stopped || draining && !selected) return Promise.resolve();
+    ticking = Promise.resolve().then(async () => {
+      try {
+        while (!stopped && (!draining || selected)) {
+          const job = selected ? await store.claimQueued(owner, scope, limits, selected) : await store.claim(owner, scope, limits);
+          if (!job) break;
+          if (stopped) break;
+          const controller = new AbortController();
+          const completion = run(job, controller);
+          active.set(job.id, { controller, completion });
+          try {
+            onExecution?.(completion);
+          } catch {
+          }
         }
+      } catch {
+        failedRetirement();
+      } finally {
+        ticking = void 0;
       }
-    } catch {
-    } finally {
-      ticking = false;
-    }
+    });
+    return ticking;
   };
   const timer = setInterval(() => {
     void tick();
@@ -11148,20 +11184,21 @@ function createEvalExecutionTransport({
     },
     async submit(request, body) {
       const negotiated = request.headers.get("x-kortyx-eval-protocol") === protocol;
-      if (stopped)
-        return problem(
-          new import_errors13.KortyxError(
-            "EVAL_EXECUTOR_BUSY",
-            "Eval executor is draining; execution was not accepted.",
-            {
-              category: "request",
-              status: 503,
-              retryable: true,
-              safeMessage: "Eval executor is draining; execution was not accepted."
-            }
-          ),
-          negotiated
-        );
+      const retiring = draining;
+      const refused = () => problem(
+        new import_errors13.KortyxError(
+          "EVAL_EXECUTOR_BUSY",
+          "Eval executor is draining; execution was not accepted.",
+          {
+            category: "request",
+            status: 503,
+            retryable: true,
+            safeMessage: "Eval executor is draining; execution was not accepted."
+          }
+        ),
+        negotiated
+      );
+      if (stopped || retiring && !negotiated) return refused();
       const id3 = negotiated ? request.headers.get("idempotency-key") : (0, import_node_crypto6.randomUUID)();
       if (!id3 || !uuid.test(id3))
         return Response.json(
@@ -11176,31 +11213,75 @@ function createEvalExecutionTransport({
           },
           { status: 410 }
         );
+      const fingerprint = (0, import_node_crypto6.createHash)("sha256").update(canonical2(body)).digest("hex");
       try {
-        if (negotiated && request.headers.get("x-kortyx-eval-generation") !== await store.generation())
-          return Response.json(
-            {
-              error: "Execution storage changed; execution status is unknown.",
-              code: "EVAL_EXECUTION_STORE_CHANGED"
-            },
-            { status: 409 }
-          );
-        await store.submit(
-          {
-            id: key(id3),
-            scope,
-            fingerprint: (0, import_node_crypto6.createHash)("sha256").update(canonical2(body)).digest("hex"),
-            group: key(body.attempt?.evaluationId ?? id3),
-            concurrency: body.concurrency,
-            weight: body.attempt ? 1 : body.concurrency,
-            payload: body,
-            queued: negotiated
-          },
-          limits
-        );
+        let admitted;
+        const pending = new Promise((resolve2) => {
+          admitted = resolve2;
+        });
+        admissions.add(pending);
+        try {
+          if (negotiated && request.headers.get("x-kortyx-eval-generation") !== await store.generation())
+            return Response.json(
+              {
+                error: "Execution storage changed; execution status is unknown.",
+                code: "EVAL_EXECUTION_STORE_CHANGED"
+              },
+              { status: 409 }
+            );
+          if (retiring) {
+            const existing = await store.get(key(id3));
+            if (!existing) return refused();
+            if (existing.fingerprint !== fingerprint)
+              throw new import_errors13.KortyxError(
+                "EVAL_EXECUTION_CONFLICT",
+                "Execution identity was reused with a different request.",
+                {
+                  category: "request",
+                  status: 409,
+                  retryable: false,
+                  safeMessage: "Execution identity was reused with a different request."
+                }
+              );
+            return await observe(request, id3);
+          }
+          try {
+            await store.submit(
+              {
+                id: key(id3),
+                scope,
+                fingerprint,
+                group: key(body.attempt?.evaluationId ?? id3),
+                concurrency: body.concurrency,
+                weight: body.attempt ? 1 : body.concurrency,
+                payload: body,
+                queued: negotiated
+              },
+              limits
+            );
+          } catch (error) {
+            if (!(error instanceof import_errors13.KortyxError) || ![
+              "EVAL_EXECUTOR_BUSY",
+              "EVAL_EXECUTION_CONFLICT",
+              "EVAL_CONCURRENCY_UNSUPPORTED",
+              "EVAL_CONCURRENCY_CHANGED",
+              "EVAL_EVIDENCE_LIMIT"
+            ].includes(error.code))
+              failedRetirement();
+            throw error;
+          }
+        } finally {
+          admissions.delete(pending);
+          admitted();
+        }
+        if (stopped && !negotiated) {
+          throw new Error("Consumer execution was explicitly closed.");
+        }
         await tick();
         if (!negotiated) {
           while ((await store.status(key(id3)))?.state === "queued") {
+            if (stopped)
+              throw new Error("Consumer execution was explicitly closed.");
             request.signal.throwIfAborted();
             await wait(10, request.signal);
             await tick();
@@ -11208,7 +11289,7 @@ function createEvalExecutionTransport({
         }
         return await observe(request, id3, 0, negotiated);
       } catch (error) {
-        if (!negotiated && request.signal.aborted) {
+        if (!negotiated && (request.signal.aborted || stopped)) {
           active.get(key(id3))?.controller.abort("user-cancelled");
           await store.cancel(key(id3)).catch(() => {
           });
@@ -11222,11 +11303,53 @@ function createEvalExecutionTransport({
         "x-kortyx-eval-generation": await store.generation()
       };
     },
-    async close() {
+    drain() {
+      draining = true;
+      clearInterval(timer);
+      drain ??= (async () => {
+        try {
+          await Promise.all(admissions);
+          await ticking;
+          if (!store.queued || !store.claimQueued) throw unsupportedRetirement;
+          const selected = new Set(await store.queued(scope));
+          if (selected.size > limits.maxQueuedExecutions)
+            throw new Error("Retirement queue exceeds the configured bound.");
+          while (!stopped) {
+            if (selected.size) await tick([...selected]);
+            for (const id3 of selected) {
+              const status2 = await store.status(id3);
+              if (!status2 || status2.state === "unknown") failedRetirement();
+              if (status2?.state !== "queued") selected.delete(id3);
+            }
+            await Promise.all(
+              [...active.values()].map((job) => job.completion)
+            );
+            if (!selected.size || retirementFailure) break;
+            await new Promise((resolve2) => setTimeout(resolve2, 50));
+          }
+          await Promise.all([...active.values()].map((job) => job.completion));
+          await Promise.allSettled(heartbeats);
+          if (stopped)
+            throw new Error("Consumer retirement was explicitly aborted.");
+          if (retirementFailure) throw retirementFailure;
+        } catch (error) {
+          failedRetirement();
+          throw error === unsupportedRetirement ? unsupportedRetirement : retirementFailure;
+        }
+      })();
+      return drain;
+    },
+    close() {
       stopped = true;
       clearInterval(timer);
-      for (const job of active.values()) job.controller.abort("host-stopped");
-      await Promise.all([...active.values()].map((job) => job.completion));
+      closing ??= (async () => {
+        for (const job of active.values()) job.controller.abort("host-stopped");
+        await Promise.all(admissions);
+        await ticking;
+        await Promise.all([...active.values()].map((job) => job.completion));
+        await Promise.allSettled(heartbeats);
+      })();
+      return closing;
     }
   };
 }
@@ -11360,7 +11483,12 @@ function createEvalRouteHandler({
       return Response.json({ error: "Request cancelled." }, { status: 409 });
     return execution.submit(request, body);
   };
-  return Object.assign(handler3, { close: execution.close });
+  return Object.assign(handler3, {
+    /** Stop admissions and finish accepted jobs; keep HTTP/store alive for observers. */
+    drain: execution.drain,
+    /** Explicitly abort local execution, then wait for cleanup. */
+    close: execution.close
+  });
 }
 
 // src/evals/studio-judge.ts