@kortyx/cli 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.11.2](https://github.com/kortyx-io/kortyx/compare/cli-v0.11.1...cli-v0.11.2) (2026-09-22)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/agent bumped to 0.26.2
+    * @kortyx/core bumped to 0.11.0
+
+## [0.11.1](https://github.com/kortyx-io/kortyx/compare/cli-v0.11.0...cli-v0.11.1) (2026-09-21)
+
+
+### Bug Fixes
+
+* preserve interrupt control flow and Studio compatibility ([#226](https://github.com/kortyx-io/kortyx/issues/226)) ([72ba7c2](https://github.com/kortyx-io/kortyx/commit/72ba7c2b9a467db0e54b5a4ab5844c8d7f895135))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @kortyx/agent bumped to 0.26.1
+    * @kortyx/core bumped to 0.10.1
+    * @kortyx/telemetry-contracts bumped to 0.11.1
+
 ## [0.11.0](https://github.com/kortyx-io/kortyx/compare/cli-v0.10.1...cli-v0.11.0) (2026-09-21)
 
 

package/dist/index.js

@@ -29,12 +29,12 @@ var import_node_os3 = require("os");
 var import_node_path4 = require("path");
 var import_agent = require("@kortyx/agent");
 var import_errors = require("@kortyx/core/errors");
-var import_telemetry_contracts4 = require("@kortyx/telemetry-contracts");
+var import_telemetry_contracts6 = require("@kortyx/telemetry-contracts");
 var import_commander4 = require("commander");
 var import_api = require("tsx/cjs/api");
 
 // src/connections-command.ts
-var import_telemetry_contracts = require("@kortyx/telemetry-contracts");
+var import_telemetry_contracts2 = require("@kortyx/telemetry-contracts");
 var import_commander = require("commander");
 
 // src/connections.ts
@@ -45,6 +45,7 @@ var import_node_path2 = require("path");
 var import_zod2 = require("zod");
 
 // src/studio/read-client.ts
+var import_telemetry_contracts = require("@kortyx/telemetry-contracts");
 var StudioReadError = class extends Error {
   constructor(code, message, status, requestId) {
     super(message);
@@ -101,6 +102,10 @@ var StudioReadClient = class {
   apiKey;
   request;
   apiUrl;
+  compatibility = {
+    protocolVersion: null,
+    release: null
+  };
   async get(path, schema, query = {}) {
     if (!/^\/v1\/studio\/(?:context|catalogs|workflows|(?:runs|sessions|interrupts)(?:\/[^/?#]+)?)$/.test(
       path
@@ -119,7 +124,8 @@ var StudioReadClient = class {
         method: "GET",
         headers: {
           authorization: `Bearer ${this.apiKey}`,
-          accept: "application/json"
+          accept: "application/json",
+          "x-kortyx-studio-api-version": import_telemetry_contracts.STUDIO_API_PROTOCOL_VERSION
         },
         redirect: "error",
         signal: AbortSignal.timeout(15e3)
@@ -131,6 +137,19 @@ var StudioReadClient = class {
       );
     }
     const requestId = response.headers.get("x-request-id") ?? void 0;
+    this.compatibility = {
+      protocolVersion: response.headers.get("x-kortyx-studio-api-version"),
+      release: response.headers.get("x-kortyx-studio-release")
+    };
+    if (this.compatibility.protocolVersion && this.compatibility.protocolVersion !== import_telemetry_contracts.STUDIO_API_PROTOCOL_VERSION) {
+      await response.body?.cancel();
+      throw new StudioReadError(
+        "incompatible_studio_api",
+        `This CLI supports Studio API v${import_telemetry_contracts.STUDIO_API_PROTOCOL_VERSION}, but the server reports v${this.compatibility.protocolVersion}${this.compatibility.release ? ` (${this.compatibility.release})` : ""}. Install a CLI and Studio release that use the same Studio API major.`,
+        response.status,
+        requestId
+      );
+    }
     if (!response.ok) {
       await response.body?.cancel();
       const message = response.status === 401 ? "Invalid, expired, or revoked Studio read key." : response.status === 403 ? "The API key lacks studio:read permission." : response.status === 404 ? "Entity not found in this connection's project. Check the URL and selected connection." : `Studio API returned HTTP ${response.status}.`;
@@ -180,9 +199,10 @@ var StudioReadClient = class {
     }
     const result = schema.safeParse(value);
     if (!result.success) {
+      const server = this.compatibility.protocolVersion ? `Studio API v${this.compatibility.protocolVersion}${this.compatibility.release ? ` (${this.compatibility.release})` : ""}` : "a server that did not report its Studio API version";
       throw new StudioReadError(
         "schema_mismatch",
-        "Studio response does not match this CLI's contracts. Check API/CLI version compatibility.",
+        `Studio response does not match this CLI's Studio API v${import_telemetry_contracts.STUDIO_API_PROTOCOL_VERSION} contracts. The response came from ${server}. Upgrade both components if this server predates protocol negotiation; otherwise report this as an API compatibility regression.`,
         response.status,
         requestId
       );
@@ -245,6 +265,7 @@ services:
       NODE_ENV: production
       API_HOST: 0.0.0.0
       API_PORT: 6400
+      KORTYX_STUDIO_RELEASE: \${KORTYX_STUDIO_IMAGE_TAG:-latest}
     ports:
       - "127.0.0.1:\${API_PORT:-6400}:6400"
     depends_on:
@@ -447,6 +468,29 @@ var writePrivateFileAtomically = async (path, contents) => {
     }
   }
 };
+var readOptionalFile = async (path) => {
+  try {
+    return await (0, import_promises.readFile)(path, "utf8");
+  } catch (error) {
+    if (isMissingFile(error)) return null;
+    throw error;
+  }
+};
+var captureStudioState = async (home) => ({
+  config: await readOptionalFile(studioConfigPath(home)),
+  environment: await readOptionalFile(studioEnvPath(home)),
+  compose: await readOptionalFile(studioComposePath(home))
+});
+var restoreStudioState = async (home, snapshot) => {
+  for (const [path, contents] of [
+    [studioConfigPath(home), snapshot.config],
+    [studioEnvPath(home), snapshot.environment],
+    [studioComposePath(home), snapshot.compose]
+  ]) {
+    if (contents === null) await (0, import_promises.unlink)(path).catch(() => void 0);
+    else await writePrivateFileAtomically(path, contents);
+  }
+};
 var readStudioEnvironment = async (home) => {
   const path = studioEnvPath(home);
   return parseEnvironmentFile(await (0, import_promises.readFile)(path, "utf8"), path);
@@ -490,17 +534,15 @@ var ensureStudioState = async (options, runtime) => {
   await (0, import_promises.mkdir)((0, import_node_path.join)(options.home, ".updates"), { recursive: true, mode: 448 });
   const existing = await readStudioConfig(options.home);
   const config = resolveConfig(existing, options, runtime);
-  await (0, import_promises.writeFile)(
+  await writePrivateFileAtomically(
     studioConfigPath(options.home),
     `${JSON.stringify(config, null, 2)}
-`,
-    { mode: 384 }
+`
+  );
+  await writePrivateFileAtomically(
+    studioComposePath(options.home),
+    STUDIO_COMPOSE_FILE
   );
-  await (0, import_promises.chmod)(studioConfigPath(options.home), 384);
-  await (0, import_promises.writeFile)(studioComposePath(options.home), STUDIO_COMPOSE_FILE, {
-    mode: 384
-  });
-  await (0, import_promises.chmod)(studioComposePath(options.home), 384);
   let environment;
   try {
     environment = await readStudioEnvironment(options.home);
@@ -772,7 +814,7 @@ var createConnectionsCommand = (log = console.log, request = fetch) => {
       );
       const context = await client.get(
         "/v1/studio/context",
-        import_telemetry_contracts.StudioContextResponseSchema
+        import_telemetry_contracts2.StudioContextResponseSchema
       );
       if (!context.apiKey.scopes.includes("studio:read"))
         throw new StudioReadError(
@@ -838,6 +880,7 @@ var import_commander3 = require("commander");
 
 // src/studio/local-stack.ts
 var import_promises3 = require("fs/promises");
+var import_telemetry_contracts3 = require("@kortyx/telemetry-contracts");
 var composeArgs = (home, args) => [
   "compose",
   "--env-file",
@@ -980,45 +1023,63 @@ var rotateStudioCredentials = async (home, runtime) => {
 };
 var startStudio = async (options, runtime) => {
   await preflightDocker(runtime);
-  const config = await ensureStudioState(options, runtime);
-  const environment = await readStudioEnvironment(options.home);
-  const apiImage = String(
-    environment.KORTYX_API_IMAGE_REF ?? `${environment.KORTYX_API_IMAGE ?? "ghcr.io/kortyx-io/kortyx-api"}:${config.imageTag}`
-  );
-  await runtime.run("docker", ["pull", apiImage], { inherit: true });
-  const capability = await runtime.run(
-    "docker",
-    [
-      "run",
-      "--rm",
-      "--entrypoint",
-      "node",
-      apiImage,
-      "-e",
-      'if (require("node:fs").existsSync("/app/apps/api/dist/updater.js")) console.log("supported")'
-    ],
-    { inherit: false }
-  );
-  await (0, import_promises3.writeFile)(
-    studioComposePath(options.home),
-    studioComposeFile(
-      process.platform !== "win32" && capability.stdout.trim() === "supported"
-    ),
-    { mode: 384 }
-  );
-  if (!await hasRunningServices(options.home, runtime)) {
-    await assertPortsAvailable(config, runtime);
+  const snapshot = await captureStudioState(options.home);
+  try {
+    const config = await ensureStudioState(options, runtime);
+    const environment = await readStudioEnvironment(options.home);
+    const apiImage = String(
+      environment.KORTYX_API_IMAGE_REF ?? `${environment.KORTYX_API_IMAGE ?? "ghcr.io/kortyx-io/kortyx-api"}:${config.imageTag}`
+    );
+    const studioImage = String(
+      environment.KORTYX_STUDIO_IMAGE_REF ?? `${environment.KORTYX_STUDIO_IMAGE ?? "ghcr.io/kortyx-io/kortyx-studio"}:${config.imageTag}`
+    );
+    await runtime.run("docker", ["pull", apiImage], { inherit: true });
+    if (studioImage !== apiImage)
+      await runtime.run("docker", ["pull", studioImage], { inherit: true });
+    const capability = await runtime.run(
+      "docker",
+      [
+        "run",
+        "--rm",
+        "--entrypoint",
+        "node",
+        apiImage,
+        "-e",
+        'if (require("node:fs").existsSync("/app/apps/api/dist/updater.js")) console.log("supported")'
+      ],
+      { inherit: false }
+    );
+    await (0, import_promises3.writeFile)(
+      studioComposePath(options.home),
+      studioComposeFile(
+        process.platform !== "win32" && capability.stdout.trim() === "supported"
+      ),
+      { mode: 384 }
+    );
+    if (!await hasRunningServices(options.home, runtime)) {
+      await assertPortsAvailable(config, runtime);
+    }
+    runtime.log(
+      "Starting Kortyx Studio. The first image pull can take a few minutes."
+    );
+    await runCompose(
+      options.home,
+      ["up", "-d", "--remove-orphans", "--wait", "--wait-timeout", "180"],
+      runtime
+    );
+    runtime.log("Kortyx Studio is ready.");
+    await printStudioConnection(options.home, config, runtime);
+  } catch (error) {
+    try {
+      await restoreStudioState(options.home, snapshot);
+    } catch (rollbackError) {
+      throw new AggregateError(
+        [error, rollbackError],
+        `Studio startup failed and the previous configuration could not be restored. Inspect "${options.home}" before retrying.`
+      );
+    }
+    throw error;
   }
-  runtime.log(
-    "Starting Kortyx Studio. The first image pull can take a few minutes."
-  );
-  await runCompose(
-    options.home,
-    ["up", "-d", "--remove-orphans", "--wait", "--wait-timeout", "180"],
-    runtime
-  );
-  runtime.log("Kortyx Studio is ready.");
-  await printStudioConnection(options.home, config, runtime);
 };
 var stopStudio = async (home, runtime) => {
   await preflightDocker(runtime);
@@ -1046,6 +1107,24 @@ var showStudioStatus = async (home, runtime) => {
   runtime.log();
   runtime.log(`Studio: http://localhost:${config.studioPort}`);
   runtime.log(`API:    http://localhost:${config.apiPort}`);
+  if (runtime.request) {
+    const environment = await readStudioEnvironment(home);
+    const client = new StudioReadClient(
+      `http://localhost:${config.apiPort}`,
+      environment.KORTYX_STUDIO_API_KEY,
+      runtime.request
+    );
+    try {
+      await client.get("/v1/studio/context", import_telemetry_contracts3.StudioContextResponseSchema);
+      runtime.log(
+        client.compatibility.protocolVersion ? `Compatibility: Studio API v${client.compatibility.protocolVersion} (${client.compatibility.release ?? config.imageTag}) is compatible with CLI API v${import_telemetry_contracts3.STUDIO_API_PROTOCOL_VERSION}.` : `Compatibility: response is compatible with CLI API v${import_telemetry_contracts3.STUDIO_API_PROTOCOL_VERSION}; this older server does not report its protocol version.`
+      );
+    } catch (error) {
+      runtime.log(
+        `Compatibility: ${error instanceof StudioReadError ? error.message : "could not query the Studio API."}`
+      );
+    }
+  }
   runtime.log(`State:  ${home}`);
 };
 var showStudioLogs = async (home, follow, runtime) => {
@@ -1072,11 +1151,11 @@ var resetStudio = async (home, confirm, runtime) => {
 };
 
 // src/studio/read-command.ts
-var import_telemetry_contracts3 = require("@kortyx/telemetry-contracts");
+var import_telemetry_contracts5 = require("@kortyx/telemetry-contracts");
 var import_commander2 = require("commander");
 
 // src/studio/read-analysis.ts
-var import_telemetry_contracts2 = require("@kortyx/telemetry-contracts");
+var import_telemetry_contracts4 = require("@kortyx/telemetry-contracts");
 var stringValue = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
 var numberValue = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
 var recordValue = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -1192,7 +1271,7 @@ var focusStudioEvents = (events, target) => {
       "The URL has no event, trace, node, branch, or call selector to focus."
     );
   const callEventIds = new Set(
-    selection.call ? (0, import_telemetry_contracts2.projectWorkflowCalls)(events).filter(
+    selection.call ? (0, import_telemetry_contracts4.projectWorkflowCalls)(events).filter(
       (call) => call.id === selection.call || call.callId === selection.call || call.invocationId === selection.call
     ).flatMap((call) => call.events.map((event) => event.id)) : []
   );
@@ -1480,8 +1559,12 @@ var sanitizeStudioData = (value, includeContent, key = "") => {
 var summarizeEvidence = (events) => {
   const findings = events.flatMap((event) => {
     const payload = event.payload;
-    const failed = /(?:failed|error|fault)/i.test(event.type) || payload.outcome === "fault" || payload.status === "failed";
-    const warning = /(?:retry|cancel|interrupt|limit_reached|denied|suspended|waiting)/i.test(
+    const error = payload.error && typeof payload.error === "object" && !Array.isArray(payload.error) ? payload.error : {};
+    const suspension = event.type === "span.failed" && (error.controlFlow === true || ["GraphInterrupt", "NodeInterrupt", "ParallelChildWaiting"].includes(
+      String(error.name)
+    ));
+    const failed = !suspension && (/(?:failed|error|fault)/i.test(event.type) || payload.outcome === "fault" || payload.status === "failed");
+    const warning = suspension || /(?:retry|cancel|interrupt|limit_reached|denied|suspended|waiting)/i.test(
       event.type
     ) || ["denied", "cancelled"].includes(String(payload.outcome));
     if (!failed && !warning) return [];
@@ -1567,10 +1650,10 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
     const { connection, client } = await clientFor(options, target.url);
     const context = await client.get(
       "/v1/studio/context",
-      import_telemetry_contracts3.StudioContextResponseSchema
+      import_telemetry_contracts5.StudioContextResponseSchema
     );
     const path = `/v1/studio/${target.entity}/${encodeURIComponent(target.id)}`;
-    const detail = target.entity === "runs" ? await client.get(path, import_telemetry_contracts3.StudioRunDetailResponseSchema) : target.entity === "sessions" ? await client.get(path, import_telemetry_contracts3.StudioSessionDetailResponseSchema) : await client.get(path, import_telemetry_contracts3.StudioInterruptDetailResponseSchema);
+    const detail = target.entity === "runs" ? await client.get(path, import_telemetry_contracts5.StudioRunDetailResponseSchema) : target.entity === "sessions" ? await client.get(path, import_telemetry_contracts5.StudioSessionDetailResponseSchema) : await client.get(path, import_telemetry_contracts5.StudioInterruptDetailResponseSchema);
     const limit = options.eventLimit;
     const events = [...detail.events].sort(
       (a, b) => Date.parse(a.occurredAt) - Date.parse(b.occurredAt) || Date.parse(a.receivedAt) - Date.parse(b.receivedAt) || a.id.localeCompare(b.id)
@@ -1594,13 +1677,13 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
       ),
       ...analyzedFindings
     ];
-    const calls = (0, import_telemetry_contracts3.projectWorkflowCalls)(selectedEvents);
+    const calls = (0, import_telemetry_contracts5.projectWorkflowCalls)(selectedEvents);
     let catalog;
     if (target.entity === "runs" && run2) {
       try {
         const workflows2 = await client.get(
           "/v1/studio/workflows",
-          import_telemetry_contracts3.StudioWorkflowsResponseSchema,
+          import_telemetry_contracts5.StudioWorkflowsResponseSchema,
           { range: "All time", workflow: run2.workflowId }
         );
         catalog = compareCatalogRuntime(run2, workflows2.workflows);
@@ -1685,7 +1768,7 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
     const { connection, client } = await clientFor(options);
     const context = await client.get(
       "/v1/studio/context",
-      import_telemetry_contracts3.StudioContextResponseSchema
+      import_telemetry_contracts5.StudioContextResponseSchema
     );
     print(
       {
@@ -1709,7 +1792,7 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
         connection: connection.name,
         data: await client.get(
           "/v1/studio/catalogs",
-          import_telemetry_contracts3.StudioCatalogsResponseSchema
+          import_telemetry_contracts5.StudioCatalogsResponseSchema
         )
       },
       options
@@ -1724,7 +1807,7 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
       "Studio time range: 1h, 24h, 7d, 30d, all (or Studio preset name)."
     ).choices([
       ...Object.keys(rangeAliases),
-      ...import_telemetry_contracts3.StudioTimeRangeSchema.options
+      ...import_telemetry_contracts5.StudioTimeRangeSchema.options
     ]).default("24h")
   ).option(
     "--started-after <iso>",
@@ -1736,7 +1819,7 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
   const timeQuery = (options) => {
     const custom = Boolean(options.startedAfter || options.startedBefore);
     const range = custom ? "Custom range" : rangeAliases[options.range] ?? options.range;
-    const resolution = (0, import_telemetry_contracts3.resolveStudioTimeRange)({
+    const resolution = (0, import_telemetry_contracts5.resolveStudioTimeRange)({
       range,
       startedAfter: options.startedAfter,
       startedBefore: options.startedBefore
@@ -1780,23 +1863,23 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
           );
           const context = await client.get(
             "/v1/studio/context",
-            import_telemetry_contracts3.StudioContextResponseSchema
+            import_telemetry_contracts5.StudioContextResponseSchema
           );
           const [leftDetail, rightDetail] = await Promise.all([
             client.get(
               `/v1/studio/runs/${encodeURIComponent(leftTarget.id)}`,
-              import_telemetry_contracts3.StudioRunDetailResponseSchema
+              import_telemetry_contracts5.StudioRunDetailResponseSchema
             ),
             client.get(
               `/v1/studio/runs/${encodeURIComponent(rightTarget.id)}`,
-              import_telemetry_contracts3.StudioRunDetailResponseSchema
+              import_telemetry_contracts5.StudioRunDetailResponseSchema
             )
           ]);
           const catalogFor = async (detail) => {
             try {
               const response = await client.get(
                 "/v1/studio/workflows",
-                import_telemetry_contracts3.StudioWorkflowsResponseSchema,
+                import_telemetry_contracts5.StudioWorkflowsResponseSchema,
                 { range: "All time", workflow: detail.run.workflowId }
               );
               return compareCatalogRuntime(detail.run, response.workflows);
@@ -1902,7 +1985,7 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
       query.cursor = String(options.cursor);
       if (options.includeChildren) query.includeChildren = "true";
       const path = `/v1/studio/${entity}`;
-      const data = entity === "runs" ? await client.get(path, import_telemetry_contracts3.StudioRunsResponseSchema, query) : entity === "sessions" ? await client.get(path, import_telemetry_contracts3.StudioSessionsResponseSchema, query) : await client.get(path, import_telemetry_contracts3.StudioInterruptsResponseSchema, query);
+      const data = entity === "runs" ? await client.get(path, import_telemetry_contracts5.StudioRunsResponseSchema, query) : entity === "sessions" ? await client.get(path, import_telemetry_contracts5.StudioSessionsResponseSchema, query) : await client.get(path, import_telemetry_contracts5.StudioInterruptsResponseSchema, query);
       const items = "runs" in data ? data.runs : "sessions" in data ? data.sessions : data.interrupts;
       const next = options.cursor + items.length;
       print(
@@ -1939,7 +2022,7 @@ var registerStudioReadCommands = (studio, log, request = fetch) => {
         connection: connection.name,
         data: await client.get(
           "/v1/studio/workflows",
-          import_telemetry_contracts3.StudioWorkflowsResponseSchema,
+          import_telemetry_contracts5.StudioWorkflowsResponseSchema,
           query
         ),
         note: "Workflow metrics span environments; connection environment defaults are not applied by this API."
@@ -1990,6 +2073,7 @@ var defaultStudioRuntime = {
   portAvailable,
   now: () => (/* @__PURE__ */ new Date()).toISOString(),
   random: (bytes) => (0, import_node_crypto2.randomBytes)(bytes).toString("base64url"),
+  request: fetch,
   log: (message = "") => console.log(message),
   error: (message = "") => console.error(message)
 };
@@ -2748,7 +2832,7 @@ var pushSnapshot = async (apiUrl, apiKey, snapshot) => {
       }
     );
   }
-  return import_telemetry_contracts4.EnsureWorkflowTopologyResponseSchema.parse(await response.json());
+  return import_telemetry_contracts6.EnsureWorkflowTopologyResponseSchema.parse(await response.json());
 };
 var printResults = (results, options) => {
   if (options.json) {
@@ -2828,7 +2912,7 @@ var runTopologyPush = async (rawOptions) => {
     }
   }
   const parsedSnapshots = snapshots.map(
-    (snapshot) => import_telemetry_contracts4.EnsureWorkflowTopologyRequestSchema.parse(snapshot)
+    (snapshot) => import_telemetry_contracts6.EnsureWorkflowTopologyRequestSchema.parse(snapshot)
   );
   const results = [];
   for (const snapshot of parsedSnapshots) {