@kortyx/cli 0.8.0 → 0.10.0

package/dist/index.js

@@ -23,21 +23,179 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/index.ts
-var import_promises3 = require("fs/promises");
+var import_promises4 = require("fs/promises");
 var import_node_module = __toESM(require("module"));
-var import_node_os2 = require("os");
-var import_node_path3 = require("path");
+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_contracts = require("@kortyx/telemetry-contracts");
-var import_commander2 = require("commander");
+var import_telemetry_contracts4 = require("@kortyx/telemetry-contracts");
+var import_commander4 = require("commander");
 var import_api = require("tsx/cjs/api");
 
-// src/studio/command.ts
+// src/connections-command.ts
+var import_telemetry_contracts = require("@kortyx/telemetry-contracts");
 var import_commander = require("commander");
 
-// src/studio/local-stack.ts
+// src/connections.ts
+var import_node_crypto = require("crypto");
 var import_promises2 = require("fs/promises");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var import_zod2 = require("zod");
+
+// src/studio/read-client.ts
+var StudioReadError = class extends Error {
+  constructor(code, message, status, requestId) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.requestId = requestId;
+    this.name = "StudioReadError";
+  }
+  code;
+  status;
+  requestId;
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        status: this.status,
+        requestId: this.requestId
+      }
+    };
+  }
+};
+var normalizeConnectionUrl = (input) => {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new StudioReadError(
+      "invalid_url",
+      "Provide an absolute HTTP(S) connection URL."
+    );
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.username || url.password || url.search || url.hash || !(url.protocol === "https:" || url.protocol === "http:" && loopback)) {
+    throw new StudioReadError(
+      "invalid_url",
+      "Connection URLs require HTTPS (HTTP is allowed on loopback), without credentials, query, or fragment."
+    );
+  }
+  return url.toString().replace(/\/+$/, "");
+};
+var StudioReadClient = class {
+  constructor(apiUrl, apiKey, request = fetch) {
+    this.apiKey = apiKey;
+    this.request = request;
+    this.apiUrl = normalizeConnectionUrl(apiUrl);
+    if (!/^ktyx_(?:test|live)_[^_]+_\S+$/.test(apiKey)) {
+      throw new StudioReadError(
+        "invalid_key",
+        "Expected a Kortyx API key with studio:read permission."
+      );
+    }
+  }
+  apiKey;
+  request;
+  apiUrl;
+  async get(path, schema, query = {}) {
+    if (!/^\/v1\/studio\/(?:context|catalogs|workflows|(?:runs|sessions|interrupts)(?:\/[^/?#]+)?)$/.test(
+      path
+    ) || /(?:^|\/)(?:\.|\.\.|%2e(?:%2e)?)(?:\/|$)/i.test(path)) {
+      throw new StudioReadError(
+        "invalid_endpoint",
+        "Only supported Studio read endpoints are allowed."
+      );
+    }
+    const url = new URL(`${this.apiUrl}${path}`);
+    for (const [key, value2] of Object.entries(query))
+      url.searchParams.set(key, value2);
+    let response;
+    try {
+      response = await this.request(url, {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${this.apiKey}`,
+          accept: "application/json"
+        },
+        redirect: "error",
+        signal: AbortSignal.timeout(15e3)
+      });
+    } catch {
+      throw new StudioReadError(
+        "connection_failed",
+        "Studio API request failed or timed out. Check the URL, network/VPN, and TLS. Redirects are not followed."
+      );
+    }
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    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}.`;
+      throw new StudioReadError(
+        "api_error",
+        message,
+        response.status,
+        requestId
+      );
+    }
+    let value;
+    const reader = response.body?.getReader();
+    if (!reader)
+      throw new StudioReadError(
+        "invalid_response",
+        "Studio returned an empty response."
+      );
+    try {
+      const decoder = new TextDecoder();
+      let body = "";
+      let bytes = 0;
+      for (; ; ) {
+        const chunk = await reader.read();
+        if (chunk.done) break;
+        bytes += chunk.value.byteLength;
+        if (bytes > 20 * 1024 * 1024) {
+          await reader.cancel();
+          throw new StudioReadError(
+            "response_too_large",
+            "Studio response exceeded the 20 MiB safety limit. Use a smaller query or inspect an individual run."
+          );
+        }
+        body += decoder.decode(chunk.value, { stream: true });
+      }
+      body += decoder.decode();
+      value = JSON.parse(body);
+    } catch (error) {
+      if (error instanceof StudioReadError) throw error;
+      throw new StudioReadError(
+        "invalid_response",
+        "Could not read Studio JSON response.",
+        response.status,
+        requestId
+      );
+    } finally {
+      reader.releaseLock();
+    }
+    const result = schema.safeParse(value);
+    if (!result.success) {
+      throw new StudioReadError(
+        "schema_mismatch",
+        "Studio response does not match this CLI's contracts. Check API/CLI version compatibility.",
+        response.status,
+        requestId
+      );
+    }
+    return result.data;
+  }
+};
+
+// src/studio/state.ts
+var import_promises = require("fs/promises");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_zod = require("zod");
 
 // src/studio/compose.ts
 var STUDIO_COMPOSE_FILE = `name: \${KORTYX_COMPOSE_PROJECT_NAME:-kortyx-studio}
@@ -158,10 +316,6 @@ function studioComposeFile(updater) {
 }
 
 // src/studio/state.ts
-var import_promises = require("fs/promises");
-var import_node_os = require("os");
-var import_node_path = require("path");
-var import_zod = require("zod");
 var CONFIG_VERSION = 1;
 var DEFAULT_API_PORT = 6400;
 var DEFAULT_STUDIO_PORT = 6300;
@@ -381,7 +535,309 @@ var requireStudioConfig = async (home) => {
   return config;
 };
 
+// src/connections.ts
+var ProfileSchema = import_zod2.z.object({
+  name: import_zod2.z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/),
+  apiUrl: import_zod2.z.string(),
+  studioUrl: import_zod2.z.string().optional(),
+  apiKeyEnv: import_zod2.z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/),
+  environment: import_zod2.z.string().min(1).optional(),
+  project: import_zod2.z.string(),
+  organization: import_zod2.z.string()
+}).strict();
+var ConfigSchema = import_zod2.z.object({
+  version: import_zod2.z.literal(1),
+  current: import_zod2.z.string().optional(),
+  profiles: import_zod2.z.array(ProfileSchema)
+}).strict().superRefine((config, ctx) => {
+  const names = config.profiles.map((profile) => profile.name);
+  if (names.includes("local") || new Set(names).size !== names.length || config.current && config.current !== "local" && !names.includes(config.current)) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Invalid connection names or selection."
+    });
+  }
+});
+var defaultConnectionsHome = () => (0, import_node_path2.resolve)(process.env.KORTYX_CONFIG_HOME ?? (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".kortyx"));
+var readConnections = async (home = defaultConnectionsHome()) => {
+  try {
+    const result = ConfigSchema.safeParse(
+      JSON.parse(await (0, import_promises2.readFile)((0, import_node_path2.join)(home, "connections.json"), "utf8"))
+    );
+    if (!result.success) throw new Error("invalid");
+    for (const profile of result.data.profiles) {
+      normalizeConnectionUrl(profile.apiUrl);
+      if (profile.studioUrl) normalizeConnectionUrl(profile.studioUrl);
+    }
+    return result.data;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT")
+      return { version: 1, profiles: [] };
+    throw new StudioReadError(
+      "invalid_config",
+      "Invalid or unreadable connections.json. Fix the configuration; it will not be overwritten."
+    );
+  }
+};
+var saveConnections = async (config, home = defaultConnectionsHome()) => {
+  const result = ConfigSchema.safeParse(config);
+  if (!result.success)
+    throw new StudioReadError(
+      "invalid_config",
+      "Invalid connection name or configuration."
+    );
+  await (0, import_promises2.mkdir)(home, { recursive: true, mode: 448 });
+  const temporary = (0, import_node_path2.join)(home, `.connections-${(0, import_node_crypto.randomUUID)()}.tmp`);
+  try {
+    await (0, import_promises2.writeFile)(temporary, `${JSON.stringify(result.data, null, 2)}
+`, {
+      mode: 384,
+      flag: "wx"
+    });
+    await (0, import_promises2.rename)(temporary, (0, import_node_path2.join)(home, "connections.json"));
+  } finally {
+    await (0, import_promises2.unlink)(temporary).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+};
+var urlMatches = (target, base) => {
+  const url = new URL(base);
+  const prefix = url.pathname.replace(/\/+$/, "");
+  return target.origin === url.origin && (target.pathname === prefix || target.pathname.startsWith(`${prefix}/`));
+};
+var resolveConnection = async (options, targetUrl) => {
+  const config = await readConnections(options.configHome);
+  const local = await readStudioConfig(options.home ?? defaultStudioHome());
+  const localLocator = local ? {
+    name: "local",
+    apiUrl: `http://localhost:${local.apiPort}`,
+    studioUrl: `http://localhost:${local.studioPort}`
+  } : void 0;
+  let selected = options.connection ?? (process.env.KORTYX_CONNECTION || void 0);
+  if (options.apiUrl || options.apiKeyEnv) {
+    if (selected || !options.apiUrl || !options.apiKeyEnv) {
+      throw new StudioReadError(
+        "invalid_connection",
+        "Direct connections require both --api-url and --api-key-env, without --connection/KORTYX_CONNECTION. Keys are never reused for URL overrides."
+      );
+    }
+    if (targetUrl)
+      throw new StudioReadError(
+        "unmapped_url",
+        "Register a connection with --studio-url before inspecting a URL. Direct connections accept entity IDs only."
+      );
+    return {
+      name: "direct",
+      apiUrl: normalizeConnectionUrl(options.apiUrl),
+      apiKey: readKeyEnv(options.apiKeyEnv)
+    };
+  }
+  const locators = [
+    ...config.profiles,
+    ...localLocator ? [localLocator] : []
+  ];
+  if (targetUrl) {
+    const target = new URL(targetUrl);
+    const matches = locators.filter(
+      (profile2) => urlMatches(target, profile2.apiUrl) || profile2.studioUrl && urlMatches(target, profile2.studioUrl)
+    );
+    if (selected) {
+      if (!matches.some((profile2) => profile2.name === selected)) {
+        throw new StudioReadError(
+          "connection_mismatch",
+          "The supplied URL does not match the selected connection's API or Studio URL."
+        );
+      }
+    } else if (matches.length === 1) selected = matches[0]?.name;
+    else
+      throw new StudioReadError(
+        "unmapped_url",
+        matches.length ? "URL matches multiple projects. Specify --connection explicitly." : "URL does not match a configured connection. Add one with the correct --studio-url."
+      );
+  }
+  selected ??= config.current ?? "local";
+  if (selected === "local") {
+    if (!localLocator)
+      throw new StudioReadError(
+        "not_configured",
+        "Local Studio is not configured. Run kortyx studio start or select a remote connection."
+      );
+    const environment = await readStudioEnvironment(
+      options.home ?? defaultStudioHome()
+    );
+    return { ...localLocator, apiKey: environment.KORTYX_STUDIO_API_KEY };
+  }
+  const profile = config.profiles.find((item) => item.name === selected);
+  if (!profile)
+    throw new StudioReadError(
+      "unknown_connection",
+      "Connection not found. Run kortyx connections list."
+    );
+  return {
+    name: profile.name,
+    apiUrl: profile.apiUrl,
+    studioUrl: profile.studioUrl,
+    environment: profile.environment,
+    apiKey: readKeyEnv(profile.apiKeyEnv)
+  };
+};
+var readKeyEnv = (name) => {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+    throw new StudioReadError(
+      "invalid_key_env",
+      "Provide a valid environment variable name."
+    );
+  const value = process.env[name];
+  if (!value)
+    throw new StudioReadError(
+      "missing_key",
+      `Set ${name} to a project-scoped Studio read key. Do not use the telemetry write key.`
+    );
+  return value;
+};
+
+// src/connections-command.ts
+var createConnectionsCommand = (log = console.log, request = fetch) => {
+  const command = new import_commander.Command("connections").description(
+    "Manage Studio connection profiles (no remote mutations or stored secrets)."
+  );
+  const common = (child) => child.option(
+    "--config-home <path>",
+    "Connection configuration directory.",
+    defaultConnectionsHome()
+  ).option(
+    "--home <path>",
+    "Managed local Studio directory.",
+    defaultStudioHome()
+  ).option("--json", "Print machine-readable JSON.");
+  const print = (value, options) => log(JSON.stringify(value, null, options.json ? 0 : 2));
+  common(
+    command.command("list").description("List profiles without reading or displaying their keys.")
+  ).action(async (options) => {
+    const config = await readConnections(options.configHome);
+    const local = await readStudioConfig(options.home);
+    print(
+      {
+        current: config.current ?? "local",
+        connections: [
+          ...local ? [
+            {
+              name: "local",
+              apiUrl: `http://localhost:${local.apiPort}`,
+              studioUrl: `http://localhost:${local.studioPort}`,
+              credential: "managed-local"
+            }
+          ] : [],
+          ...config.profiles
+        ]
+      },
+      options
+    );
+  });
+  common(
+    command.command("add <name>").description(
+      "Validate a read key and save URL locators plus an environment-variable reference."
+    ).requiredOption(
+      "--api-url <url>",
+      "Studio API base URL (not the browser URL)."
+    ).requiredOption(
+      "--api-key-env <name>",
+      "Environment variable containing the project-scoped read key."
+    ).option(
+      "--studio-url <url>",
+      "Studio browser base URL, used to resolve pasted links."
+    ).option("--environment <name>", "Default environment filter for lists.").option("--replace", "Explicitly replace an existing named connection.")
+  ).action(
+    async (name, options) => {
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name) || name === "local") {
+        throw new StudioReadError(
+          "invalid_name",
+          "Use a connection name of 1\u201364 letters, digits, hyphens or underscores; local is reserved."
+        );
+      }
+      const config = await readConnections(options.configHome);
+      if (config.profiles.some((profile2) => profile2.name === name) && !options.replace) {
+        throw new StudioReadError(
+          "connection_exists",
+          "Connection already exists. Use --replace to update it."
+        );
+      }
+      const apiUrl = normalizeConnectionUrl(options.apiUrl);
+      const studioUrl = options.studioUrl ? normalizeConnectionUrl(options.studioUrl) : void 0;
+      const client = new StudioReadClient(
+        apiUrl,
+        readKeyEnv(options.apiKeyEnv),
+        request
+      );
+      const context = await client.get(
+        "/v1/studio/context",
+        import_telemetry_contracts.StudioContextResponseSchema
+      );
+      if (!context.apiKey.scopes.includes("studio:read"))
+        throw new StudioReadError(
+          "missing_scope",
+          "The API key lacks studio:read permission."
+        );
+      const profile = {
+        name,
+        apiUrl,
+        apiKeyEnv: options.apiKeyEnv,
+        project: context.project.name,
+        organization: context.organization.name,
+        ...studioUrl ? { studioUrl } : {},
+        ...options.environment ? { environment: options.environment } : {}
+      };
+      config.profiles = [
+        ...config.profiles.filter((item) => item.name !== name),
+        profile
+      ];
+      await saveConnections(config, options.configHome);
+      print({ connection: profile, verified: true }, options);
+    }
+  );
+  common(
+    command.command("use <name>").description(
+      "Select the default connection; agents should prefer per-command --connection."
+    )
+  ).action(async (name, options) => {
+    const config = await readConnections(options.configHome);
+    if (name === "local" ? !await readStudioConfig(options.home) : !config.profiles.some((profile) => profile.name === name)) {
+      throw new StudioReadError(
+        "unknown_connection",
+        "Connection not found. Run kortyx connections list."
+      );
+    }
+    config.current = name;
+    await saveConnections(config, options.configHome);
+    print({ current: name }, options);
+  });
+  common(
+    command.command("remove <name>").description(
+      "Remove a saved locator, not its credential or remote project."
+    )
+  ).action(async (name, options) => {
+    const config = await readConnections(options.configHome);
+    if (!config.profiles.some((profile) => profile.name === name))
+      throw new StudioReadError(
+        "unknown_connection",
+        "Saved connection not found; managed local cannot be removed."
+      );
+    config.profiles = config.profiles.filter(
+      (profile) => profile.name !== name
+    );
+    if (config.current === name) delete config.current;
+    await saveConnections(config, options.configHome);
+    print({ removed: name }, options);
+  });
+  return command;
+};
+
+// src/studio/command.ts
+var import_commander3 = require("commander");
+
 // src/studio/local-stack.ts
+var import_promises3 = require("fs/promises");
 var composeArgs = (home, args) => [
   "compose",
   "--env-file",
@@ -543,7 +999,7 @@ var startStudio = async (options, runtime) => {
     ],
     { inherit: false }
   );
-  await (0, import_promises2.writeFile)(
+  await (0, import_promises3.writeFile)(
     studioComposePath(options.home),
     studioComposeFile(
       process.platform !== "win32" && capability.stdout.trim() === "supported"
@@ -615,8 +1071,878 @@ var resetStudio = async (home, confirm, runtime) => {
   );
 };
 
+// src/studio/read-command.ts
+var import_telemetry_contracts3 = require("@kortyx/telemetry-contracts");
+var import_commander2 = require("commander");
+
+// src/studio/read-analysis.ts
+var import_telemetry_contracts2 = 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 : {};
+var toolTerminalTypes = /* @__PURE__ */ new Set([
+  "tool.completed",
+  "tool.failed",
+  "tool.denied",
+  "tool.cancelled",
+  "tool.reused"
+]);
+var buildStudioTimeline = (events, interrupts = []) => {
+  const interruptById = new Map(interrupts.map((item) => [item.id, item]));
+  const items = [];
+  const ordered = [...events].sort(
+    (left, right) => Date.parse(left.occurredAt) - Date.parse(right.occurredAt) || Date.parse(left.receivedAt) - Date.parse(right.receivedAt) || left.id.localeCompare(right.id)
+  );
+  for (const event of ordered) {
+    const payload = event.payload;
+    const base = {
+      eventId: event.id,
+      at: event.occurredAt,
+      nodeId: event.nodeId,
+      workflowId: event.workflowId
+    };
+    if (event.type === "generation.completed") {
+      items.push({
+        ...base,
+        kind: "model",
+        ...numberValue(payload.durationMs) !== void 0 ? { durationMs: numberValue(payload.durationMs) } : {},
+        ...stringValue(payload.provider) ? { provider: stringValue(payload.provider) } : {},
+        ...stringValue(payload.model) ? { model: stringValue(payload.model) } : {},
+        ...payload.finishReason !== void 0 ? { finishReason: payload.finishReason } : {}
+      });
+      continue;
+    }
+    if (toolTerminalTypes.has(event.type)) {
+      const fallbackOutcome = event.type.slice("tool.".length);
+      items.push({
+        ...base,
+        kind: "tool",
+        ...numberValue(payload.durationMs) !== void 0 ? { durationMs: numberValue(payload.durationMs) } : {},
+        ...stringValue(payload.name) || stringValue(payload.tool) ? { toolName: stringValue(payload.name) ?? stringValue(payload.tool) } : {},
+        toolOutcome: stringValue(payload.outcome) ?? (fallbackOutcome === "completed" ? "success" : fallbackOutcome),
+        ...stringValue(payload.toolCallId) ? { toolCallId: stringValue(payload.toolCallId) } : {},
+        ...payload.input !== void 0 ? { input: payload.input } : {},
+        ...payload.output !== void 0 ? { output: payload.output } : {}
+      });
+      continue;
+    }
+    if (event.type === "interrupt.created") {
+      const id = stringValue(payload.interruptId);
+      const interrupt = id ? interruptById.get(id) : void 0;
+      items.push({
+        ...base,
+        kind: "interrupt",
+        ...id ? { interruptId: id } : {},
+        ...interrupt?.type || stringValue(payload.kind) ? { interruptType: interrupt?.type ?? stringValue(payload.kind) } : {},
+        ...interrupt?.interactionMode || stringValue(payload.interactionMode) ? {
+          interactionMode: interrupt?.interactionMode ?? stringValue(payload.interactionMode)
+        } : {},
+        ...interrupt?.question !== void 0 && interrupt.question !== null ? { question: interrupt.question } : payload.question !== void 0 ? { question: payload.question } : {}
+      });
+      continue;
+    }
+    if (event.type === "interrupt.resolved") {
+      items.push({
+        ...base,
+        kind: "resume",
+        ...stringValue(payload.interruptId) ? { interruptId: stringValue(payload.interruptId) } : {},
+        ...stringValue(payload.resumeOutcome) ? { resumeOutcome: stringValue(payload.resumeOutcome) } : {}
+      });
+      continue;
+    }
+    if (event.type === "run.limit_reached") {
+      items.push({
+        ...base,
+        kind: "limit",
+        ...stringValue(payload.limit) ? { limit: stringValue(payload.limit) } : {},
+        ...payload.consumed !== void 0 ? { consumed: payload.consumed } : {},
+        ...payload.maximum !== void 0 ? { maximum: payload.maximum } : {}
+      });
+    }
+  }
+  return items.map((item, index) => ({ step: index + 1, ...item }));
+};
+var selectedValue = (event, key) => {
+  const payload = event.payload;
+  if (key === "branch")
+    return [stringValue(payload.branchId)].filter(
+      (value) => Boolean(value)
+    );
+  return [
+    stringValue(payload.callId),
+    stringValue(payload.invocationId)
+  ].filter((value) => Boolean(value));
+};
+var focusStudioEvents = (events, target) => {
+  const selection = target.selection ?? {};
+  const applied = Object.fromEntries(
+    ["event", "trace", "node", "branch", "call"].filter((key) => Boolean(selection[key])).map((key) => [key, selection[key]])
+  );
+  if (Object.keys(applied).length === 0)
+    throw new StudioReadError(
+      "selection_not_focusable",
+      "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(
+      (call) => call.id === selection.call || call.callId === selection.call || call.invocationId === selection.call
+    ).flatMap((call) => call.events.map((event) => event.id)) : []
+  );
+  const focused = events.filter(
+    (event) => Object.entries(applied).every(([key, value]) => {
+      if (key === "event") return event.id === value;
+      if (key === "trace") return event.traceId === value;
+      if (key === "node") return event.nodeId === value;
+      if (key === "branch")
+        return selectedValue(event, "branch").includes(value);
+      return callEventIds.has(event.id) || selectedValue(event, "call").includes(value);
+    })
+  );
+  if (focused.length === 0)
+    throw new StudioReadError(
+      "selection_not_found",
+      "The pasted URL selector did not match any returned Studio events."
+    );
+  return { events: focused, applied };
+};
+var stableValue = (value) => {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, stableValue(item)])
+    );
+  return value;
+};
+var analyzeStudioDiagnostics = (events, run2, interrupts = []) => {
+  const findings = [];
+  const terminalTools = events.filter(
+    (event) => toolTerminalTypes.has(event.type)
+  );
+  for (let index = 1; index < terminalTools.length; index++) {
+    const previous = terminalTools[index - 1];
+    const current = terminalTools[index];
+    if (!previous || !current) continue;
+    const previousName = stringValue(previous.payload.name) ?? stringValue(previous.payload.tool);
+    const currentName = stringValue(current.payload.name) ?? stringValue(current.payload.tool);
+    if (previousName && previousName === currentName && previous.payload.input !== void 0 && current.payload.input !== void 0 && JSON.stringify(stableValue(previous.payload.input)) === JSON.stringify(stableValue(current.payload.input))) {
+      findings.push({
+        code: "repeated_tool_input",
+        severity: "warning",
+        message: `Tool ${currentName} was called consecutively with the same captured input.`,
+        eventIds: [previous.id, current.id],
+        evidence: { toolName: currentName, input: current.payload.input }
+      });
+    }
+  }
+  let lastInterrupt;
+  for (const event of events) {
+    if (toolTerminalTypes.has(event.type)) lastInterrupt = void 0;
+    if (event.type !== "interrupt.created") continue;
+    if (lastInterrupt)
+      findings.push({
+        code: "consecutive_human_interrupts",
+        severity: "warning",
+        message: "Human input was requested again without an intervening terminal tool event.",
+        eventIds: [lastInterrupt.id, event.id]
+      });
+    lastInterrupt = event;
+  }
+  for (const event of events.filter(
+    (item) => item.type === "run.limit_reached"
+  ))
+    findings.push({
+      code: "tool_step_limit_reached",
+      severity: "warning",
+      message: "The runtime reported that an execution limit was reached.",
+      eventIds: [event.id],
+      evidence: event.payload
+    });
+  const schemaFailures = events.filter((event) => {
+    if (event.type !== "span.failed") return false;
+    const error = recordValue(event.payload.error);
+    const failure = recordValue(event.payload.failure);
+    const haystack = [
+      error.code,
+      error.message,
+      failure.code,
+      failure.message,
+      event.payload.code,
+      event.payload.message
+    ].filter((value) => typeof value === "string").join(" ");
+    return /MODEL_OUTPUT_SCHEMA|INVALID_OUTPUT|output (?:schema|validation)|schema validation/i.test(
+      haystack
+    );
+  });
+  for (const failure of schemaFailures) {
+    const laterGeneration = events.find(
+      (event) => event.type === "generation.completed" && Date.parse(event.occurredAt) > Date.parse(failure.occurredAt)
+    );
+    findings.push({
+      code: laterGeneration ? "output_schema_retry" : "output_schema_failure",
+      severity: laterGeneration ? "warning" : "error",
+      message: laterGeneration ? "An output-schema failure was followed by another model generation." : "The runtime reported an output-schema validation failure.",
+      eventIds: [failure.id, ...laterGeneration ? [laterGeneration.id] : []],
+      evidence: failure.payload
+    });
+  }
+  const pending = interrupts.filter((item) => item.status === "pending");
+  if (run2?.status === "interrupted" && pending.length > 0)
+    findings.push({
+      code: "unresolved_interrupt",
+      severity: "warning",
+      message: "The workflow is suspended with unresolved human input.",
+      eventIds: events.filter(
+        (event) => event.type === "interrupt.created" && pending.some((item) => item.id === event.payload.interruptId)
+      ).map((event) => event.id),
+      evidence: { interruptIds: pending.map((item) => item.id) }
+    });
+  return findings;
+};
+var compareCatalogRuntime = (run2, workflows) => {
+  const rootReferences = run2.workflowRefs.filter(
+    (reference) => reference.workflowId === run2.workflowId
+  );
+  const rows = rootReferences.length ? rootReferences : [
+    {
+      workflowId: run2.workflowId,
+      workflowRevisionId: run2.workflowRevisionId,
+      declaredVersion: run2.declaredVersion
+    }
+  ];
+  const compared = rows.map((reference) => {
+    const workflow = workflows.find((item) => item.id === reference.workflowId);
+    return {
+      workflowId: reference.workflowId,
+      executedRevisionId: reference.workflowRevisionId,
+      executedVersion: reference.declaredVersion,
+      activeRevisionId: workflow?.activeRevisionId ?? null,
+      activeVersion: workflow?.activeVersion ?? null,
+      drift: Boolean(
+        workflow?.activeRevisionId && reference.workflowRevisionId && workflow.activeRevisionId !== reference.workflowRevisionId || !reference.workflowRevisionId && workflow?.activeVersion && reference.declaredVersion && workflow.activeVersion !== reference.declaredVersion
+      )
+    };
+  });
+  const published = compared.some((item) => item.activeRevisionId);
+  return {
+    status: !published ? "not-published" : compared.some((item) => item.drift) ? "drift" : "current",
+    workflows: compared
+  };
+};
+var compareRunAnalysis = (left, right) => {
+  const metadataFields = [
+    "workflowId",
+    "workflowRevisionId",
+    "declaredVersion",
+    "environment",
+    "provider",
+    "model",
+    "status",
+    "result"
+  ];
+  const metadata = metadataFields.flatMap(
+    (field) => JSON.stringify(left.run[field]) === JSON.stringify(right.run[field]) ? [] : [{ field, left: left.run[field], right: right.run[field] }]
+  );
+  if (JSON.stringify(left.deploymentRefs ?? []) !== JSON.stringify(right.deploymentRefs ?? []))
+    metadata.push({
+      field: "deploymentRefs",
+      left: left.deploymentRefs ?? [],
+      right: right.deploymentRefs ?? []
+    });
+  const signature = (item) => `${item.kind}:${item.toolName ?? item.interruptType ?? item.limit ?? ""}`;
+  const length = Math.max(left.timeline.length, right.timeline.length);
+  const comparable = (item) => {
+    const { step: _step, eventId: _eventId, at: _at, ...rest } = item;
+    return rest;
+  };
+  const timeline = Array.from({ length }, (_, index) => {
+    const leftItem = left.timeline[index] ?? null;
+    const rightItem = right.timeline[index] ?? null;
+    return {
+      index: index + 1,
+      status: leftItem && rightItem ? JSON.stringify(comparable(leftItem)) === JSON.stringify(comparable(rightItem)) ? "same" : signature(leftItem) === signature(rightItem) ? "changed" : "diverged" : leftItem ? "removed" : "added",
+      left: leftItem,
+      right: rightItem
+    };
+  });
+  return {
+    metadata,
+    timeline,
+    firstDivergence: timeline.find((item) => item.status !== "same")?.index ?? null,
+    different: metadata.length > 0 || timeline.some((item) => item.status !== "same")
+  };
+};
+
+// src/studio/read-output.ts
+var parseStudioTarget = (input, entity) => {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(input)) {
+    let url;
+    try {
+      url = new URL(input);
+    } catch {
+      throw new StudioReadError("invalid_target", "Invalid Studio URL.");
+    }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
+      throw new StudioReadError(
+        "invalid_target",
+        "Use an HTTP(S) Studio entity URL without embedded credentials."
+      );
+    }
+    const match = url.pathname.match(
+      /\/(runs|sessions|interrupts)\/([^/]+)\/?$/
+    );
+    if (!match)
+      throw new StudioReadError(
+        "invalid_target",
+        "Expected a Studio /runs/<id>, /sessions/<id>, or /interrupts/<id> URL."
+      );
+    if (entity && match[1] !== entity)
+      throw new StudioReadError(
+        "invalid_target",
+        "URL entity type does not match the command."
+      );
+    let id;
+    try {
+      id = decodeURIComponent(match[2] ?? "");
+    } catch {
+      throw new StudioReadError(
+        "invalid_target",
+        "Invalid entity ID encoding."
+      );
+    }
+    validateId(id);
+    const selection = {};
+    for (const key of [
+      "tab",
+      "sessionTab",
+      "call",
+      "branch",
+      "node",
+      "event",
+      "trace",
+      "detailView"
+    ]) {
+      const value = url.searchParams.get(key);
+      if (value) selection[key] = value;
+    }
+    url.search = "";
+    url.hash = "";
+    return {
+      entity: match[1],
+      id,
+      url: url.toString(),
+      selection
+    };
+  }
+  if (!entity)
+    throw new StudioReadError(
+      "invalid_target",
+      "inspect requires a Studio entity URL. Use runs/sessions/interrupts get for a bare ID."
+    );
+  validateId(input);
+  return { entity, id: input };
+};
+var validateId = (id) => {
+  if (!id || id.length > 512 || id === "." || id === ".." || /[\s/?#\\]/.test(id) || [...id].some(
+    (char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127
+  )) {
+    throw new StudioReadError("invalid_target", "Invalid Studio entity ID.");
+  }
+};
+var secretKey = /(?:password|secret|authorization|cookie|apikey|credential|resumetoken|accesstoken|refreshtoken|bearertoken|sessiontoken|authtoken)/i;
+var contentKey = /^(?:input|output|inputs|outputs|inputmessages|outputmessages|messages|prompt|systemprompt|question|response|result|latestresult|arguments|args|content|text|options)$/i;
+var sanitizeStudioData = (value, includeContent, key = "") => {
+  const normalized = key.replace(/[^a-z0-9]/gi, "");
+  const keyPolicy = normalized.toLowerCase() === "apikey" && value && typeof value === "object" && "scopes" in value && "mode" in value;
+  if (secretKey.test(normalized) && !keyPolicy) return "[REDACTED]";
+  if (!includeContent && contentKey.test(normalized))
+    return "[CONTENT OMITTED: use --include-content]";
+  if (typeof value === "string")
+    return value.replace(/ktyx_(?:test|live)_[^\s"'<>]+/g, "[REDACTED]").replace(/Bearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer [REDACTED]");
+  if (Array.isArray(value))
+    return value.map((item) => sanitizeStudioData(item, includeContent));
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).map(([name, item]) => [
+        name,
+        sanitizeStudioData(item, includeContent, name)
+      ])
+    );
+  return value;
+};
+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(
+      event.type
+    ) || ["denied", "cancelled"].includes(String(payload.outcome));
+    if (!failed && !warning) return [];
+    return [
+      {
+        eventId: event.id,
+        runId: event.runId,
+        nodeId: event.nodeId,
+        type: event.type,
+        occurredAt: event.occurredAt,
+        severity: failed ? "error" : "context",
+        evidence: payload
+      }
+    ];
+  });
+  return {
+    findings,
+    note: "Evidence, not an automated root-cause verdict. Interrupts, cancellations, and retries can be expected; correlate with the final run outcome. Missing telemetry does not prove an action did not occur."
+  };
+};
+var formatReadOutput = (value, json) => {
+  if (json) return JSON.stringify(value);
+  return JSON.stringify(value, null, 2);
+};
+
+// src/studio/read-command.ts
+var integer = (min, max) => (value) => {
+  if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < min || Number(value) > max) {
+    throw new import_commander2.InvalidArgumentError(
+      `Expected an integer between ${min} and ${max}.`
+    );
+  }
+  return Number(value);
+};
+var rangeAliases = {
+  "1h": "Last hour",
+  "24h": "24 hours",
+  "7d": "7 days",
+  "30d": "30 days",
+  all: "All time"
+};
+var registerStudioReadCommands = (studio, log, request = fetch) => {
+  const common = (command) => command.option(
+    "--connection <name>",
+    "Named project/URL connection (or KORTYX_CONNECTION)."
+  ).option(
+    "--config-home <path>",
+    "Connection configuration directory.",
+    defaultConnectionsHome()
+  ).option(
+    "--home <path>",
+    "Managed local Studio directory.",
+    defaultStudioHome()
+  ).option(
+    "--api-url <url>",
+    "Direct API URL; requires --api-key-env. Never reuses a profile key."
+  ).option(
+    "--api-key-env <name>",
+    "Environment variable holding a direct connection read key."
+  ).option("--json", "Print stable machine-readable JSON.").option(
+    "--include-content",
+    "Include captured input/output and prompts (may contain sensitive data)."
+  );
+  const print = (value, options) => log(
+    formatReadOutput(
+      sanitizeStudioData(value, options.includeContent ?? false),
+      options.json ?? false
+    )
+  );
+  const clientFor = async (options, targetUrl) => {
+    const connection = await resolveConnection(options, targetUrl);
+    return {
+      connection,
+      client: new StudioReadClient(
+        connection.apiUrl,
+        connection.apiKey,
+        request
+      )
+    };
+  };
+  const inspect = async (input, options, entity) => {
+    const target = parseStudioTarget(input, entity);
+    const { connection, client } = await clientFor(options, target.url);
+    const context = await client.get(
+      "/v1/studio/context",
+      import_telemetry_contracts3.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 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)
+    );
+    const focus = options.focusSelection ? focusStudioEvents(events, target) : { events, applied: {} };
+    const selectedEvents = focus.events;
+    const evidence = summarizeEvidence(selectedEvents);
+    const run2 = "run" in detail ? detail.run : null;
+    const interrupts = "interrupts" in detail ? detail.interrupts : "interrupt" in detail ? [detail.interrupt] : [];
+    const analyzedFindings = analyzeStudioDiagnostics(
+      selectedEvents,
+      run2,
+      interrupts
+    );
+    const supersededEventIds = new Set(
+      analyzedFindings.flatMap((finding) => finding.eventIds)
+    );
+    const findings = [
+      ...evidence.findings.filter(
+        (finding) => !supersededEventIds.has(finding.eventId)
+      ),
+      ...analyzedFindings
+    ];
+    const calls = (0, import_telemetry_contracts3.projectWorkflowCalls)(selectedEvents);
+    let catalog;
+    if (target.entity === "runs" && run2) {
+      try {
+        const workflows2 = await client.get(
+          "/v1/studio/workflows",
+          import_telemetry_contracts3.StudioWorkflowsResponseSchema,
+          { range: "All time", workflow: run2.workflowId }
+        );
+        catalog = compareCatalogRuntime(run2, workflows2.workflows);
+      } catch (error) {
+        catalog = {
+          status: "unavailable",
+          workflows: [],
+          reason: error instanceof StudioReadError ? error.code : "catalog_comparison_failed"
+        };
+      }
+    }
+    const catalogFinding = catalog?.status === "drift" ? [
+      {
+        code: "catalog_runtime_drift",
+        severity: "warning",
+        message: "The executed workflow revision differs from the currently active catalog revision.",
+        eventIds: [],
+        evidence: catalog.workflows
+      }
+    ] : [];
+    const allFindings = [...findings, ...catalogFinding];
+    print(
+      {
+        schemaVersion: 1,
+        connection: {
+          name: connection.name,
+          apiUrl: connection.apiUrl,
+          context
+        },
+        target,
+        detail: { ...detail, events: selectedEvents.slice(-limit) },
+        timeline: buildStudioTimeline(selectedEvents, interrupts).slice(-limit),
+        calls: calls.slice(-limit).map(({ events: callEvents, ...call }) => ({
+          ...call,
+          eventIds: callEvents.map((event) => event.id)
+        })),
+        diagnostics: {
+          ...evidence,
+          findings: allFindings.slice(-limit),
+          findingCount: allFindings.length,
+          findingsOmitted: Math.max(0, allFindings.length - limit)
+        },
+        ...catalog ? { catalog } : {},
+        coverage: {
+          returnedEvents: Math.min(selectedEvents.length, limit),
+          availableEvents: selectedEvents.length,
+          omittedEvents: Math.max(0, selectedEvents.length - limit),
+          eventWindow: "latest",
+          selectionFocus: options.focusSelection ? {
+            applied: focus.applied,
+            matchedEvents: selectedEvents.length,
+            totalEvents: events.length
+          } : null,
+          contentIncluded: options.includeContent ?? false,
+          availableCalls: calls.length,
+          omittedCalls: Math.max(0, calls.length - limit),
+          note: "Available events are those returned by Studio, not a guarantee of complete runtime history. Content capture is opt-in; secrets are redacted on a best-effort basis even with --include-content."
+        }
+      },
+      options
+    );
+  };
+  const detailOptions = (command) => common(command).option(
+    "--event-limit <count>",
+    "Maximum latest events and diagnostic findings (1\u201310000).",
+    integer(1, 1e4),
+    100
+  ).option(
+    "--focus-selection",
+    "Focus events using call/event/branch/node/trace selectors from the URL."
+  );
+  detailOptions(
+    studio.command("inspect <url>").description(
+      "Inspect a pasted run/session/interrupt URL using a matching configured connection."
+    )
+  ).action((input, options) => inspect(input, options));
+  common(
+    studio.command("doctor").description(
+      "Verify the read credential, project, environments, and API compatibility."
+    )
+  ).action(async (options) => {
+    const { connection, client } = await clientFor(options);
+    const context = await client.get(
+      "/v1/studio/context",
+      import_telemetry_contracts3.StudioContextResponseSchema
+    );
+    print(
+      {
+        schemaVersion: 1,
+        connection: connection.name,
+        apiUrl: connection.apiUrl,
+        context
+      },
+      options
+    );
+  });
+  common(
+    studio.command("catalogs").description(
+      "Read available environment/provider/model/workflow/tag filters."
+    )
+  ).action(async (options) => {
+    const { connection, client } = await clientFor(options);
+    print(
+      {
+        schemaVersion: 1,
+        connection: connection.name,
+        data: await client.get(
+          "/v1/studio/catalogs",
+          import_telemetry_contracts3.StudioCatalogsResponseSchema
+        )
+      },
+      options
+    );
+  });
+  const filters = (command) => common(command).option(
+    "--environment <name>",
+    "Environment filter; overrides the connection default."
+  ).addOption(
+    new import_commander2.Option(
+      "--range <range>",
+      "Studio time range: 1h, 24h, 7d, 30d, all (or Studio preset name)."
+    ).choices([
+      ...Object.keys(rangeAliases),
+      ...import_telemetry_contracts3.StudioTimeRangeSchema.options
+    ]).default("24h")
+  ).option(
+    "--started-after <iso>",
+    "Explicit start boundary (requires --started-before)."
+  ).option(
+    "--started-before <iso>",
+    "Explicit end boundary (requires --started-after)."
+  ).option("--workflow <id>", "Workflow filter.");
+  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)({
+      range,
+      startedAfter: options.startedAfter,
+      startedBefore: options.startedBefore
+    });
+    if ("error" in resolution)
+      throw new StudioReadError("invalid_time_range", resolution.error);
+    return custom ? {
+      range,
+      startedAfter: String(resolution.value.startedAfter),
+      startedBefore: String(resolution.value.startedBefore)
+    } : { range };
+  };
+  for (const entity of ["runs", "sessions", "interrupts"]) {
+    const group = studio.command(entity).description(`Read Studio ${entity}.`);
+    detailOptions(
+      group.command("get <id-or-url>").description("Read detail, events, and diagnostic evidence.")
+    ).action(
+      (input, options) => inspect(input, options, entity)
+    );
+    if (entity === "runs") {
+      common(
+        group.command("compare <left-id-or-url> <right-id-or-url>").description(
+          "Compare two runs' versions, outcomes, and compact execution timelines."
+        )
+      ).option(
+        "--event-limit <count>",
+        "Maximum timeline steps returned per run (1\u201310000).",
+        integer(1, 1e4),
+        100
+      ).action(
+        async (leftInput, rightInput, options) => {
+          const leftTarget = parseStudioTarget(leftInput, "runs");
+          const rightTarget = parseStudioTarget(rightInput, "runs");
+          const { connection, client } = await clientFor(
+            options,
+            leftTarget.url
+          );
+          await resolveConnection(
+            { ...options, connection: connection.name },
+            rightTarget.url
+          );
+          const context = await client.get(
+            "/v1/studio/context",
+            import_telemetry_contracts3.StudioContextResponseSchema
+          );
+          const [leftDetail, rightDetail] = await Promise.all([
+            client.get(
+              `/v1/studio/runs/${encodeURIComponent(leftTarget.id)}`,
+              import_telemetry_contracts3.StudioRunDetailResponseSchema
+            ),
+            client.get(
+              `/v1/studio/runs/${encodeURIComponent(rightTarget.id)}`,
+              import_telemetry_contracts3.StudioRunDetailResponseSchema
+            )
+          ]);
+          const catalogFor = async (detail) => {
+            try {
+              const response = await client.get(
+                "/v1/studio/workflows",
+                import_telemetry_contracts3.StudioWorkflowsResponseSchema,
+                { range: "All time", workflow: detail.run.workflowId }
+              );
+              return compareCatalogRuntime(detail.run, response.workflows);
+            } catch (error) {
+              return {
+                status: "unavailable",
+                workflows: [],
+                reason: error instanceof StudioReadError ? error.code : "catalog_comparison_failed"
+              };
+            }
+          };
+          const [leftCatalog, rightCatalog] = await Promise.all([
+            catalogFor(leftDetail),
+            catalogFor(rightDetail)
+          ]);
+          const side = (target, detail, catalog) => {
+            const ordered = [...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)
+            );
+            const timeline = buildStudioTimeline(
+              ordered,
+              detail.interrupts
+            ).slice(-options.eventLimit);
+            return {
+              target,
+              run: detail.run,
+              timeline,
+              catalog,
+              deploymentRefs: [
+                ...new Set(
+                  ordered.map((event) => event.deploymentRef).filter((value) => Boolean(value))
+                )
+              ],
+              diagnostics: analyzeStudioDiagnostics(
+                ordered,
+                detail.run,
+                detail.interrupts
+              ),
+              coverage: {
+                returnedTimelineSteps: timeline.length,
+                availableEvents: ordered.length,
+                contentIncluded: options.includeContent ?? false
+              }
+            };
+          };
+          const left = side(leftTarget, leftDetail, leftCatalog);
+          const right = side(rightTarget, rightDetail, rightCatalog);
+          print(
+            {
+              schemaVersion: 1,
+              connection: {
+                name: connection.name,
+                apiUrl: connection.apiUrl,
+                context
+              },
+              left,
+              right,
+              comparison: compareRunAnalysis(left, right),
+              note: "Comparison reports observed differences, not an automated root-cause verdict. Missing or omitted content cannot prove equivalence."
+            },
+            options
+          );
+        }
+      );
+    }
+    const list = filters(
+      group.command("list").description("Read a bounded, filtered page.")
+    ).option("--limit <count>", "Page size (1\u2013100).", integer(1, 100), 25).option(
+      "--cursor <offset>",
+      "Numeric offset returned as nextCursor.",
+      integer(0, Number.MAX_SAFE_INTEGER),
+      0
+    ).option("--status <status>", "Entity status filter.").option("--session <id>", "Session filter.").option("--user <id>", "User filter.").option("--tenant <id>", "Tenant filter.").option("--model <name>", "Model filter.").option("--node <id>", "Node filter.").option("--tool <name>", "Tool name filter.").addOption(
+      new import_commander2.Option("--tool-outcome <outcome>", "Tool outcome filter.").choices([
+        "success",
+        "denied",
+        "fault",
+        "cancelled",
+        "reused"
+      ])
+    ).option("--q <text>", "Search filter.").option("--include-children", "Include child workflow runs.");
+    list.action(async (options) => {
+      const query = timeQuery(options);
+      const { connection, client } = await clientFor(options);
+      const environment = options.environment ?? connection.environment;
+      if (environment) query.env = environment;
+      for (const key of [
+        "status",
+        "workflow",
+        "session",
+        "user",
+        "tenant",
+        "model",
+        "node",
+        "tool",
+        "toolOutcome",
+        "q"
+      ]) {
+        const value = options[key];
+        if (value) query[key] = value;
+      }
+      query.pageSize = String(options.limit);
+      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 items = "runs" in data ? data.runs : "sessions" in data ? data.sessions : data.interrupts;
+      const next = options.cursor + items.length;
+      print(
+        {
+          schemaVersion: 1,
+          connection: connection.name,
+          data,
+          page: {
+            cursor: options.cursor,
+            limit: options.limit,
+            nextCursor: items.length && next < data.totalCount ? next : null
+          }
+        },
+        options
+      );
+    });
+  }
+  const workflows = studio.command("workflows").description("Read declared topology and observed workflow metrics.");
+  filters(
+    workflows.command("list").description("Read workflow topology in a time cohort.")
+  ).option("--version <version>", "Declared version filter.").action(async (options) => {
+    if (options.environment)
+      throw new StudioReadError(
+        "unsupported_filter",
+        "The workflow API does not currently support environment filtering."
+      );
+    const query = timeQuery(options);
+    if (options.workflow) query.workflow = options.workflow;
+    if (options.version) query.version = options.version;
+    const { connection, client } = await clientFor(options);
+    print(
+      {
+        schemaVersion: 1,
+        connection: connection.name,
+        data: await client.get(
+          "/v1/studio/workflows",
+          import_telemetry_contracts3.StudioWorkflowsResponseSchema,
+          query
+        ),
+        note: "Workflow metrics span environments; connection environment defaults are not applied by this API."
+      },
+      options
+    );
+  });
+};
+
 // src/studio/runtime.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var import_node_net = require("net");
 var stringOutput = (value) => typeof value === "string" ? value : "";
 var isCommandNotFound = (error) => error instanceof Error && ("code" in error && error.code === "ENOENT" || error.message.includes("ENOENT"));
@@ -655,32 +1981,33 @@ var defaultStudioRuntime = {
   run,
   portAvailable,
   now: () => (/* @__PURE__ */ new Date()).toISOString(),
-  random: (bytes) => (0, import_node_crypto.randomBytes)(bytes).toString("base64url"),
-  log: (message = "") => console.log(message)
+  random: (bytes) => (0, import_node_crypto2.randomBytes)(bytes).toString("base64url"),
+  log: (message = "") => console.log(message),
+  error: (message = "") => console.error(message)
 };
 
 // src/studio/command.ts
 var portParser = (value) => {
   const port = Number(value);
   if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new import_commander.InvalidArgumentError(
+    throw new import_commander3.InvalidArgumentError(
       "Port must be an integer between 1 and 65535."
     );
   }
   return port;
 };
 var withHome = (command) => command.addOption(
-  new import_commander.Option("--home <path>", "Local Studio state directory.").default(
+  new import_commander3.Option("--home <path>", "Local Studio state directory.").default(
     defaultStudioHome()
   )
 );
 var configureOutput = (command, runtime) => command.configureOutput({
   writeOut: (output) => runtime.log(output.trimEnd()),
-  writeErr: (output) => runtime.log(output.trimEnd())
+  writeErr: (output) => (runtime.error ?? runtime.log)(output.trimEnd())
 });
 var createStudioCommand = (runtime = defaultStudioRuntime) => {
   const studio = configureOutput(
-    new import_commander.Command("studio").description("Run and manage Kortyx Studio.").showHelpAfterError().addHelpText(
+    new import_commander3.Command("studio").description("Run and manage Kortyx Studio.").showHelpAfterError().addHelpText(
       "after",
       "\nLocal state and generated credentials are stored in ~/.kortyx/studio by default."
     ),
@@ -723,7 +2050,7 @@ var createStudioCommand = (runtime = defaultStudioRuntime) => {
       "Generate unpersisted credentials for a self-hosted deployment.",
       false
     ).addOption(
-      new import_commander.Option("--format <format>", "Credential output format.").choices(["human", "dotenv"]).default("human")
+      new import_commander3.Option("--format <format>", "Credential output format.").choices(["human", "dotenv"]).default("human")
     ).option(
       "--service-name <name>",
       "SDK service name used by dotenv output.",
@@ -765,19 +2092,20 @@ var createStudioCommand = (runtime = defaultStudioRuntime) => {
   ).action(async ({ home, confirm }) => {
     await resetStudio(home, confirm, runtime);
   });
+  registerStudioReadCommands(studio, (message) => runtime.log(message));
   return studio;
 };
 
 // src/workflow-calls.ts
-var import_node_path2 = require("path");
+var import_node_path3 = require("path");
 var import_typescript = __toESM(require("typescript"));
 function discoverWorkflowCalls(entry, snapshots) {
-  const configPath = import_typescript.default.findConfigFile((0, import_node_path2.dirname)(entry), import_typescript.default.sys.fileExists);
+  const configPath = import_typescript.default.findConfigFile((0, import_node_path3.dirname)(entry), import_typescript.default.sys.fileExists);
   const config = configPath ? import_typescript.default.readConfigFile(configPath, import_typescript.default.sys.readFile).config : {};
   const parsed = import_typescript.default.parseJsonConfigFileContent(
     config ?? {},
     import_typescript.default.sys,
-    configPath ? (0, import_node_path2.dirname)(configPath) : (0, import_node_path2.dirname)(entry)
+    configPath ? (0, import_node_path3.dirname)(configPath) : (0, import_node_path3.dirname)(entry)
   );
   const program = import_typescript.default.createProgram([entry], {
     ...parsed.options,
@@ -793,6 +2121,7 @@ function discoverWorkflowCalls(entry, snapshots) {
   );
   const calls = /* @__PURE__ */ new Map();
   const warnings = /* @__PURE__ */ new Set();
+  const attachedTools = /* @__PURE__ */ new Map();
   const definitions = /* @__PURE__ */ new Map();
   const local = (n) => !n.getSourceFile().isDeclarationFile && !n.getSourceFile().fileName.includes("node_modules");
   const symbol = (n) => {
@@ -816,7 +2145,8 @@ function discoverWorkflowCalls(entry, snapshots) {
       )
     );
   };
-  function resolve3(e, bindings, seen = /* @__PURE__ */ new Set()) {
+  const factoryBindings = /* @__PURE__ */ new WeakMap();
+  function resolve4(e, bindings, seen = /* @__PURE__ */ new Set()) {
     if (!e) return;
     e = unwrap(e);
     if (seen.has(e)) return;
@@ -824,18 +2154,18 @@ function discoverWorkflowCalls(entry, snapshots) {
     if (import_typescript.default.isIdentifier(e)) {
       const s = symbol(e);
       const bound = s && bindings.get(s);
-      if (bound) return resolve3(bound, bindings, seen);
+      if (bound) return resolve4(bound, bindings, seen);
       const d = s?.valueDeclaration;
       if (d && (import_typescript.default.isVariableDeclaration(d) || import_typescript.default.isPropertyAssignment(d)) && d.initializer && (!import_typescript.default.isVariableDeclaration(d) || import_typescript.default.isVariableDeclarationList(d.parent) && (d.parent.flags & import_typescript.default.NodeFlags.Const) !== 0))
-        return resolve3(d.initializer, bindings, seen);
+        return resolve4(d.initializer, bindings, seen);
     }
     if (import_typescript.default.isPropertyAccessExpression(e)) {
       const found = property(e.expression, e.name.text, bindings, seen);
-      if (found) return resolve3(found, bindings, seen);
+      if (found) return resolve4(found, bindings, seen);
       const owner = symbol(e.expression);
       const declaration = symbol(e.name)?.valueDeclaration;
       if (owner && owner.flags & import_typescript.default.SymbolFlags.Module && declaration && import_typescript.default.isVariableDeclaration(declaration))
-        return resolve3(declaration.initializer, bindings, seen);
+        return resolve4(declaration.initializer, bindings, seen);
       return e;
     }
     if (import_typescript.default.isElementAccessExpression(e) && e.argumentExpression && import_typescript.default.isStringLiteralLike(e.argumentExpression)) {
@@ -845,32 +2175,58 @@ function discoverWorkflowCalls(entry, snapshots) {
         bindings,
         seen
       );
-      return found ? resolve3(found, bindings, seen) : e;
+      return found ? resolve4(found, bindings, seen) : e;
+    }
+    if (import_typescript.default.isCallExpression(e)) {
+      const d = symbol(
+        import_typescript.default.isPropertyAccessExpression(e.expression) ? e.expression.name : e.expression
+      )?.valueDeclaration;
+      const fn = d && import_typescript.default.isFunctionDeclaration(d) ? d : d && import_typescript.default.isVariableDeclaration(d) && d.initializer && (import_typescript.default.isArrowFunction(d.initializer) || import_typescript.default.isFunctionExpression(d.initializer)) ? d.initializer : void 0;
+      if (fn?.body && local(fn)) {
+        const bound = new Map(bindings);
+        fn.parameters.forEach((p, i) => {
+          if (import_typescript.default.isIdentifier(p.name)) {
+            const key = symbol(p.name);
+            const arg = e.arguments[i] ?? p.initializer;
+            if (key && arg)
+              bound.set(key, resolve4(arg, bindings, new Set(seen)) ?? arg);
+          }
+        });
+        const returned = import_typescript.default.isBlock(fn.body) ? fn.body.statements.filter(import_typescript.default.isReturnStatement).map((r) => r.expression) : [fn.body];
+        if (returned.length === 1 && returned[0]) {
+          const value = resolve4(returned[0], bound, seen);
+          if (value) factoryBindings.set(value, bound);
+          return value;
+        }
+      }
     }
     return e;
   }
   function property(e, key, bindings, seen = /* @__PURE__ */ new Set()) {
-    const obj = resolve3(e, bindings, seen);
+    const obj = resolve4(e, bindings, seen);
     if (!obj || !import_typescript.default.isObjectLiteralExpression(obj)) return;
+    const scoped = factoryBindings.get(obj) ?? bindings;
     for (const p of [...obj.properties].reverse()) {
       if (import_typescript.default.isSpreadAssignment(p)) {
-        const spread = resolve3(p.expression, bindings, new Set(seen));
+        const spread = resolve4(p.expression, scoped, new Set(seen));
         if (!spread || !import_typescript.default.isObjectLiteralExpression(spread)) return void 0;
-        const found = property(p.expression, key, bindings, new Set(seen));
+        const found = property(p.expression, key, scoped, new Set(seen));
         if (found) return found;
       } else if (p.name && (import_typescript.default.isIdentifier(p.name) || import_typescript.default.isStringLiteralLike(p.name)) && p.name.text === key) {
-        if (import_typescript.default.isPropertyAssignment(p)) return p.initializer;
-        if (import_typescript.default.isShorthandPropertyAssignment(p)) return p.name;
+        if (import_typescript.default.isPropertyAssignment(p))
+          return resolve4(p.initializer, scoped, new Set(seen));
+        if (import_typescript.default.isShorthandPropertyAssignment(p))
+          return resolve4(p.name, scoped, new Set(seen));
       }
     }
     return void 0;
   }
   function literal(e, bindings) {
-    const value = resolve3(e, bindings);
+    const value = resolve4(e, bindings);
     return value && import_typescript.default.isStringLiteralLike(value) ? value.text : void 0;
   }
   function workflowId(e, bindings) {
-    const value = resolve3(e, bindings);
+    const value = resolve4(e, bindings);
     if (!value) return;
     if (import_typescript.default.isStringLiteralLike(value)) return value.text;
     if (import_typescript.default.isCallExpression(value) && api(value.expression, "defineWorkflow"))
@@ -886,19 +2242,19 @@ function discoverWorkflowCalls(entry, snapshots) {
     if (d && import_typescript.default.isBindingElement(d) && (d.propertyName?.getText() ?? d.name.getText()) === "useWorkflow") {
       const decl = d.parent.parent;
       if (import_typescript.default.isVariableDeclaration(decl) && decl.initializer) {
-        const value2 = resolve3(decl.initializer, /* @__PURE__ */ new Map());
+        const value2 = resolve4(decl.initializer, /* @__PURE__ */ new Map());
         return !!value2 && import_typescript.default.isCallExpression(value2) && api(value2.expression, "createWorkflowHooks");
       }
     }
     if (import_typescript.default.isPropertyAccessExpression(e) && e.name.text === "useWorkflow") {
-      const value2 = resolve3(e.expression, /* @__PURE__ */ new Map());
+      const value2 = resolve4(e.expression, /* @__PURE__ */ new Map());
       return !!value2 && import_typescript.default.isCallExpression(value2) && api(value2.expression, "createWorkflowHooks");
     }
-    const value = resolve3(e, /* @__PURE__ */ new Map());
+    const value = resolve4(e, /* @__PURE__ */ new Map());
     return !!value && value !== e && api(value, "useWorkflow");
   }
   function functionFor(e) {
-    const value = resolve3(e, /* @__PURE__ */ new Map());
+    const value = resolve4(e, /* @__PURE__ */ new Map());
     if (value && (import_typescript.default.isArrowFunction(value) || import_typescript.default.isFunctionExpression(value)))
       return value;
     const d = symbol(
@@ -906,12 +2262,110 @@ function discoverWorkflowCalls(entry, snapshots) {
     )?.valueDeclaration;
     return d && (import_typescript.default.isFunctionDeclaration(d) || import_typescript.default.isMethodDeclaration(d)) ? d : void 0;
   }
+  function recordTools(expression, mode, bindings, workflow, node, list = false, seen = /* @__PURE__ */ new Set()) {
+    const byNode = attachedTools.get(workflow) ?? /* @__PURE__ */ new Map();
+    attachedTools.set(workflow, byNode);
+    const target = byNode.get(node) ?? {
+      tools: [],
+      toolDiscovery: { status: "complete", warnings: [] }
+    };
+    byNode.set(node, target);
+    const unresolved = () => {
+      target.toolDiscovery.status = "unresolved";
+      const warning = `${workflow}/${node}: tool attachment is not statically resolved; real execution supplies observed tools.`;
+      if (!target.toolDiscovery.warnings.includes(warning))
+        target.toolDiscovery.warnings.push(warning);
+      warnings.add(warning);
+    };
+    const value = resolve4(expression, bindings);
+    if (!value || seen.has(value)) {
+      unresolved();
+      return;
+    }
+    seen.add(value);
+    if (list && import_typescript.default.isArrayLiteralExpression(value)) {
+      for (const item of value.elements) {
+        if (import_typescript.default.isSpreadElement(item))
+          recordTools(
+            item.expression,
+            mode,
+            bindings,
+            workflow,
+            node,
+            true,
+            new Set(seen)
+          );
+        else
+          recordTools(
+            item,
+            mode,
+            bindings,
+            workflow,
+            node,
+            false,
+            new Set(seen)
+          );
+      }
+      return;
+    }
+    if (list) {
+      unresolved();
+      return;
+    }
+    const name = literal(property(value, "name", bindings), bindings);
+    if (!name) {
+      unresolved();
+      return;
+    }
+    const description = literal(
+      property(value, "description", bindings),
+      bindings
+    );
+    const schema = property(value, "inputSchema", bindings);
+    const fields = resolve4(property(schema, "properties", bindings), bindings);
+    const requiredValue = resolve4(
+      property(schema, "required", bindings),
+      bindings
+    );
+    const required = requiredValue && import_typescript.default.isArrayLiteralExpression(requiredValue) ? requiredValue.elements.map((entry2) => literal(entry2, bindings)) : [];
+    const inputFields = fields && import_typescript.default.isObjectLiteralExpression(fields) ? fields.properties.flatMap((field) => {
+      if (!import_typescript.default.isPropertyAssignment(field) || !(import_typescript.default.isIdentifier(field.name) || import_typescript.default.isStringLiteralLike(field.name)))
+        return [];
+      return [
+        {
+          name: field.name.text,
+          type: literal(
+            property(field.initializer, "type", bindings),
+            bindings
+          ) ?? "unknown",
+          required: required.includes(field.name.text)
+        }
+      ];
+    }) : [];
+    if (!target.tools.some(
+      (tool) => tool.name === name && tool.callingMode === mode
+    ))
+      target.tools.push({
+        name,
+        callingMode: mode,
+        provenance: "source",
+        ...description ? { description } : {},
+        ...inputFields.length ? { inputFields } : {}
+      });
+  }
   function scanFunction(fn, bindings, workflow, node, stack) {
     if (!fn.body || !local(fn) || stack.has(fn)) return;
     if (stack.size >= 32) {
       warnings.add(
         `${workflow}/${node}: custom-hook discovery depth exceeded.`
       );
+      const attached = attachedTools.get(workflow)?.get(node);
+      if (attached) {
+        attached.toolDiscovery.status = "unresolved";
+        attached.toolDiscovery.warnings.push(
+          "Custom-hook discovery depth exceeded."
+        );
+      }
       return;
     }
     const next = new Set(stack).add(fn);
@@ -920,7 +2374,18 @@ function discoverWorkflowCalls(entry, snapshots) {
       if (import_typescript.default.isVariableDeclaration(n) && n.initializer && (import_typescript.default.isArrowFunction(n.initializer) || import_typescript.default.isFunctionExpression(n.initializer)))
         return;
       if (import_typescript.default.isCallExpression(n)) {
-        if (isHook(n.expression)) {
+        if (api(n.expression, "useTool")) {
+          recordTools(
+            property(n.arguments[0], "tool", bindings),
+            "direct",
+            bindings,
+            workflow,
+            node
+          );
+        } else if (api(n.expression, "useReason")) {
+          const list = property(n.arguments[0], "tools", bindings);
+          if (list) recordTools(list, "model", bindings, workflow, node, true);
+        } else if (isHook(n.expression)) {
           const target = workflowId(
             property(n.arguments[0], "workflow", bindings),
             bindings
@@ -947,7 +2412,7 @@ function discoverWorkflowCalls(entry, snapshots) {
               if (!arg) return;
               if (import_typescript.default.isIdentifier(p.name)) {
                 const s = symbol(p.name);
-                if (s) bound.set(s, resolve3(arg, bindings) ?? arg);
+                if (s) bound.set(s, resolve4(arg, bindings) ?? arg);
               } else if (import_typescript.default.isObjectBindingPattern(p.name)) {
                 for (const b of p.name.elements) {
                   const value = property(
@@ -957,7 +2422,7 @@ function discoverWorkflowCalls(entry, snapshots) {
                   );
                   const s = symbol(b.name);
                   if (s && value)
-                    bound.set(s, resolve3(value, bindings) ?? value);
+                    bound.set(s, resolve4(value, bindings) ?? value);
                 }
               }
             });
@@ -972,7 +2437,7 @@ function discoverWorkflowCalls(entry, snapshots) {
   for (const source of program.getSourceFiles().filter(local)) {
     const walk = (n) => {
       if (import_typescript.default.isCallExpression(n) && api(n.expression, "defineWorkflow")) {
-        const obj = resolve3(n.arguments[0], /* @__PURE__ */ new Map());
+        const obj = resolve4(n.arguments[0], /* @__PURE__ */ new Map());
         const id = obj && literal(property(obj, "id", /* @__PURE__ */ new Map()), /* @__PURE__ */ new Map());
         if (id && known.has(id) && obj && import_typescript.default.isObjectLiteralExpression(obj))
           definitions.set(id, [...definitions.get(id) ?? [], obj]);
@@ -982,11 +2447,26 @@ function discoverWorkflowCalls(entry, snapshots) {
     walk(source);
   }
   for (const [id, nodes] of known) {
+    attachedTools.set(
+      id,
+      new Map(
+        [...nodes].map((node) => [
+          node,
+          { tools: [], toolDiscovery: { status: "complete", warnings: [] } }
+        ])
+      )
+    );
     const defs = definitions.get(id) ?? [];
     if (defs.length !== 1) {
       warnings.add(
         `${id}: ${defs.length ? "ambiguous" : "unavailable"} workflow source; child-call discovery skipped.`
       );
+      for (const node of attachedTools.get(id)?.values() ?? []) {
+        node.toolDiscovery.status = "unresolved";
+        node.toolDiscovery.warnings.push(
+          "Workflow source unavailable or ambiguous."
+        );
+      }
       continue;
     }
     calls.set(id, []);
@@ -996,16 +2476,27 @@ function discoverWorkflowCalls(entry, snapshots) {
       const run2 = property(property(obj, node, bindings), "run", bindings);
       const fn = run2 && functionFor(run2);
       if (fn) scanFunction(fn, bindings, id, node, /* @__PURE__ */ new Set());
-      else
+      else {
+        const tools = attachedTools.get(id)?.get(node);
+        if (tools) {
+          tools.toolDiscovery.status = "unresolved";
+          tools.toolDiscovery.warnings.push("Node source unavailable.");
+        }
         warnings.add(
           `${id}/${node}: node source unavailable; child-call discovery skipped.`
         );
+      }
     }
     calls.get(id)?.sort(
       (a, b) => a.sourceNodeId.localeCompare(b.sourceNodeId) || a.targetWorkflowId.localeCompare(b.targetWorkflowId)
     );
   }
-  return { calls, warnings: [...warnings].sort() };
+  for (const nodes of attachedTools.values())
+    for (const node of nodes.values())
+      node.tools.sort(
+        (a, b) => a.name.localeCompare(b.name) || a.callingMode.localeCompare(b.callingMode)
+      );
+  return { calls, tools: attachedTools, warnings: [...warnings].sort() };
 }
 
 // src/index.ts
@@ -1016,24 +2507,24 @@ var readPackageName = async (cwd) => {
   let current = cwd;
   for (; ; ) {
     try {
-      const raw = await (0, import_promises3.readFile)((0, import_node_path3.join)(current, "package.json"), "utf8");
+      const raw = await (0, import_promises4.readFile)((0, import_node_path4.join)(current, "package.json"), "utf8");
       const parsed = JSON.parse(raw);
       if (isRecord(parsed) && typeof parsed.name === "string") {
         return parsed.name;
       }
     } catch {
     }
-    const parent = (0, import_node_path3.dirname)(current);
+    const parent = (0, import_node_path4.dirname)(current);
     if (parent === current) return void 0;
     current = parent;
   }
 };
 var loadEnvFiles = async (cwd) => {
   for (const filename of [".env", ".env.local"]) {
-    const path = (0, import_node_path3.join)(cwd, filename);
+    const path = (0, import_node_path4.join)(cwd, filename);
     let raw;
     try {
-      raw = await (0, import_promises3.readFile)(path, "utf8");
+      raw = await (0, import_promises4.readFile)(path, "utf8");
     } catch {
       continue;
     }
@@ -1059,7 +2550,7 @@ var resolveOptions = async (options) => {
   if (!options.entry) {
     throw new Error("Missing required option: --entry <path>.");
   }
-  const entry = (0, import_node_path3.isAbsolute)(options.entry) ? options.entry : (0, import_node_path3.resolve)(options.cwd, options.entry);
+  const entry = (0, import_node_path4.isAbsolute)(options.entry) ? options.entry : (0, import_node_path4.resolve)(options.cwd, options.entry);
   const environment = options.environment ?? process.env.KORTYX_TELEMETRY_ENVIRONMENT ?? process.env.NODE_ENV ?? "development";
   const serviceName = options.serviceName ?? process.env.KORTYX_TELEMETRY_SERVICE_NAME ?? await readPackageName(options.cwd) ?? "kortyx-app";
   return {
@@ -1073,19 +2564,19 @@ var resolveOptions = async (options) => {
   };
 };
 var createFrameworkMarkerStubs = async () => {
-  const root = await (0, import_promises3.mkdtemp)((0, import_node_path3.join)((0, import_node_os2.tmpdir)(), "kortyx-cli-stubs-"));
+  const root = await (0, import_promises4.mkdtemp)((0, import_node_path4.join)((0, import_node_os3.tmpdir)(), "kortyx-cli-stubs-"));
   for (const moduleName of ["server-only", "client-only"]) {
-    const directory = (0, import_node_path3.join)(root, moduleName);
-    await (0, import_promises3.mkdir)(directory, { recursive: true });
-    await (0, import_promises3.writeFile)((0, import_node_path3.join)(directory, "index.js"), "", "utf8");
-    await (0, import_promises3.writeFile)(
-      (0, import_node_path3.join)(directory, "package.json"),
+    const directory = (0, import_node_path4.join)(root, moduleName);
+    await (0, import_promises4.mkdir)(directory, { recursive: true });
+    await (0, import_promises4.writeFile)((0, import_node_path4.join)(directory, "index.js"), "", "utf8");
+    await (0, import_promises4.writeFile)(
+      (0, import_node_path4.join)(directory, "package.json"),
       JSON.stringify({ name: moduleName, version: "0.0.0", main: "index.js" }),
       "utf8"
     );
   }
   const previousNodePath = process.env.NODE_PATH;
-  process.env.NODE_PATH = previousNodePath ? `${root}${import_node_path3.delimiter}${previousNodePath}` : root;
+  process.env.NODE_PATH = previousNodePath ? `${root}${import_node_path4.delimiter}${previousNodePath}` : root;
   const moduleWithPrivateInit = import_node_module.default;
   moduleWithPrivateInit._initPaths?.();
   return {
@@ -1093,7 +2584,7 @@ var createFrameworkMarkerStubs = async () => {
       if (previousNodePath === void 0) delete process.env.NODE_PATH;
       else process.env.NODE_PATH = previousNodePath;
       moduleWithPrivateInit._initPaths?.();
-      await (0, import_promises3.rm)(root, { recursive: true, force: true });
+      await (0, import_promises4.rm)(root, { recursive: true, force: true });
     }
   };
 };
@@ -1101,9 +2592,9 @@ var importEntry = async (entry) => {
   const stubs = await createFrameworkMarkerStubs();
   let unregisterPaths;
   try {
-    const tsconfig = await findNearestFile((0, import_node_path3.dirname)(entry), "tsconfig.json");
+    const tsconfig = await findNearestFile((0, import_node_path4.dirname)(entry), "tsconfig.json");
     unregisterPaths = tsconfig ? await registerTsconfigPaths(tsconfig) : void 0;
-    const module2 = (0, import_api.require)(entry, (0, import_node_path3.join)((0, import_node_path3.dirname)(entry), "kortyx-cli.cjs"));
+    const module2 = (0, import_api.require)(entry, (0, import_node_path4.join)((0, import_node_path4.dirname)(entry), "kortyx-cli.cjs"));
     if (!isRecord(module2)) {
       throw new Error(`Entry module did not export an object: ${entry}`);
     }
@@ -1116,25 +2607,25 @@ var importEntry = async (entry) => {
 var findNearestFile = async (startDirectory, filename) => {
   let current = startDirectory;
   for (; ; ) {
-    const candidate = (0, import_node_path3.join)(current, filename);
+    const candidate = (0, import_node_path4.join)(current, filename);
     try {
-      await (0, import_promises3.access)(candidate);
+      await (0, import_promises4.access)(candidate);
       return candidate;
     } catch {
-      const parent = (0, import_node_path3.dirname)(current);
+      const parent = (0, import_node_path4.dirname)(current);
       if (parent === current) return void 0;
       current = parent;
     }
   }
 };
 var registerTsconfigPaths = async (tsconfigPath) => {
-  const raw = JSON.parse(await (0, import_promises3.readFile)(tsconfigPath, "utf8"));
+  const raw = JSON.parse(await (0, import_promises4.readFile)(tsconfigPath, "utf8"));
   if (!isRecord(raw)) return () => void 0;
   const compilerOptions = isRecord(raw.compilerOptions) ? raw.compilerOptions : void 0;
   const paths = isRecord(compilerOptions?.paths) ? compilerOptions.paths : void 0;
   if (!paths) return () => void 0;
-  const tsconfigDirectory = (0, import_node_path3.dirname)(tsconfigPath);
-  const baseUrl = typeof compilerOptions?.baseUrl === "string" ? (0, import_node_path3.resolve)(tsconfigDirectory, compilerOptions.baseUrl) : tsconfigDirectory;
+  const tsconfigDirectory = (0, import_node_path4.dirname)(tsconfigPath);
+  const baseUrl = typeof compilerOptions?.baseUrl === "string" ? (0, import_node_path4.resolve)(tsconfigDirectory, compilerOptions.baseUrl) : tsconfigDirectory;
   const mappings = Object.entries(paths).flatMap(([pattern, rawTargets]) => {
     if (!Array.isArray(rawTargets)) return [];
     return rawTargets.filter((target) => typeof target === "string").map((target) => ({ pattern, target }));
@@ -1163,7 +2654,7 @@ var registerTsconfigPaths = async (tsconfigPath) => {
         request.length - mapping.patternSuffix.length
       ) : "";
       const mapped = mapping.wildcard ? `${mapping.targetPrefix}${wildcardValue}${mapping.targetSuffix}` : mapping.target;
-      for (const candidate of candidateModulePaths((0, import_node_path3.resolve)(baseUrl, mapped))) {
+      for (const candidate of candidateModulePaths((0, import_node_path4.resolve)(baseUrl, mapped))) {
         try {
           return originalResolve.call(this, candidate, parent, isMain, options);
         } catch {
@@ -1184,10 +2675,10 @@ var candidateModulePaths = (basePath) => [
   `${basePath}.cts`,
   `${basePath}.js`,
   `${basePath}.jsx`,
-  (0, import_node_path3.join)(basePath, "index.ts"),
-  (0, import_node_path3.join)(basePath, "index.tsx"),
-  (0, import_node_path3.join)(basePath, "index.js"),
-  (0, import_node_path3.join)(basePath, "index.jsx")
+  (0, import_node_path4.join)(basePath, "index.ts"),
+  (0, import_node_path4.join)(basePath, "index.tsx"),
+  (0, import_node_path4.join)(basePath, "index.js"),
+  (0, import_node_path4.join)(basePath, "index.jsx")
 ];
 var valueFromModule = (module2, exportName) => {
   if (exportName) {
@@ -1249,7 +2740,7 @@ var pushSnapshot = async (apiUrl, apiKey, snapshot) => {
       }
     );
   }
-  return import_telemetry_contracts.EnsureWorkflowTopologyResponseSchema.parse(await response.json());
+  return import_telemetry_contracts4.EnsureWorkflowTopologyResponseSchema.parse(await response.json());
 };
 var printResults = (results, options) => {
   if (options.json) {
@@ -1262,6 +2753,11 @@ var printResults = (results, options) => {
             topologyHash: snapshot.workflow.topologyHash,
             transitionCount: snapshot.workflow.transitions?.length ?? 0,
             calls: snapshot.workflow.calls ?? [],
+            tools: snapshot.workflow.nodes.map((node) => ({
+              nodeId: node.id,
+              tools: node.tools ?? [],
+              discovery: node.toolDiscovery
+            })),
             workflowRevisionId: response?.workflowRevisionId,
             created: response?.created
           }))
@@ -1280,7 +2776,7 @@ var printResults = (results, options) => {
       `- ${snapshot.workflow.id}@${snapshot.workflow.declaredVersion} hash=${snapshot.workflow.topologyHash.slice(
         0,
         12
-      )} transitions=${snapshot.workflow.transitions?.length ?? 0} calls=${snapshot.workflow.calls?.length ?? 0}${revision}`
+      )} transitions=${snapshot.workflow.transitions?.length ?? 0} calls=${snapshot.workflow.calls?.length ?? 0} tools=${snapshot.workflow.nodes.reduce((sum, node) => sum + (node.tools?.length ?? 0), 0)}${revision}`
     );
   }
 };
@@ -1312,9 +2808,19 @@ var runTopologyPush = async (rawOptions) => {
   for (const snapshot of snapshots) {
     const calls = discovered.calls.get(snapshot.workflow.id);
     if (calls) snapshot.workflow.calls = calls;
+    for (const node of snapshot.workflow.nodes) {
+      const discoveredTools = discovered.tools.get(snapshot.workflow.id)?.get(node.id);
+      if (discoveredTools)
+        Object.assign(node, discoveredTools, {
+          toolDiscovery: {
+            ...discoveredTools.toolDiscovery,
+            publishedAt: (/* @__PURE__ */ new Date()).toISOString()
+          }
+        });
+    }
   }
   const parsedSnapshots = snapshots.map(
-    (snapshot) => import_telemetry_contracts.EnsureWorkflowTopologyRequestSchema.parse(snapshot)
+    (snapshot) => import_telemetry_contracts4.EnsureWorkflowTopologyRequestSchema.parse(snapshot)
   );
   const results = [];
   for (const snapshot of parsedSnapshots) {
@@ -1330,11 +2836,12 @@ var runTopologyPush = async (rawOptions) => {
   printResults(results, options);
 };
 var createCliProgram = () => {
-  const program = new import_commander2.Command().name("kortyx").description("Build, observe, and operate Kortyx projects.").showHelpAfterError().addHelpText(
+  const program = new import_commander4.Command().name("kortyx").description("Build, observe, and operate Kortyx projects.").showHelpAfterError().addHelpText(
     "after",
     '\nRun "kortyx <command> --help" for detailed command options.'
   );
   program.addCommand(createStudioCommand());
+  program.addCommand(createConnectionsCommand());
   const topology = program.command("topology").description("Publish deterministic workflow topology to Studio.");
   topology.command("push").description("Project and publish workflow topology.").requiredOption(
     "--entry <path>",
@@ -1372,7 +2879,14 @@ var main = async () => {
   try {
     await program.parseAsync(process.argv);
   } catch (error) {
-    if (error instanceof import_commander2.CommanderError && error.exitCode === 0) return;
+    if (error instanceof import_commander4.CommanderError && error.exitCode === 0) return;
+    if (error instanceof StudioReadError) {
+      console.error(
+        process.argv.includes("--json") ? JSON.stringify(error.toJSON()) : `[${error.code}] ${error.message}`
+      );
+      process.exitCode = 1;
+      return;
+    }
     const failure = (0, import_errors.serializeFailure)(error);
     console.error(
       error instanceof import_errors.KortyxError ? `[${failure.code}] ${failure.message}` : error instanceof Error ? error.message.slice(0, 1024) : failure.message