@vellumai/cli 0.7.1 → 0.7.3

package/src/lib/local.ts

@@ -111,7 +111,9 @@ function computeIpcSocketDirOverride(workspaceDir: string): string | undefined {
  * a short override directory and set all IPC socket env vars on the target
  * env object. No-op on non-macOS or when paths are within limits.
  */
-function applyIpcSocketDirOverride(env: Record<string, string>): void {
+function applyIpcSocketDirOverride(
+  env: Record<string, string | undefined>,
+): void {
   const workspaceDir =
     env.VELLUM_WORKSPACE_DIR || join(homedir(), ".vellum", "workspace");
   const override = computeIpcSocketDirOverride(workspaceDir);
@@ -417,6 +419,8 @@ async function startDaemonFromSource(
       options.defaultWorkspaceConfigPath;
   }
 
+  applyIpcSocketDirOverride(env);
+
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
   writeFileSync(pidFile, "starting", "utf-8");
@@ -552,6 +556,8 @@ async function startDaemonWatchFromSource(
       options.defaultWorkspaceConfigPath;
   }
 
+  applyIpcSocketDirOverride(env);
+
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
   writeFileSync(pidFile, "starting", "utf-8");
@@ -1183,10 +1189,6 @@ export async function startGateway(
 
   applyIpcSocketDirOverride(gatewayEnv);
 
-  if (publicUrl) {
-    console.log(`   HTTP URL: ${publicUrl}`);
-  }
-
   let gateway;
 
   const gatewayBinary = join(dirname(process.execPath), "vellum-gateway");
@@ -1232,8 +1234,8 @@ export async function startGateway(
   const gatewayUrl = publicUrl || `http://localhost:${effectiveGatewayPort}`;
 
   // Wait for the gateway to be responsive before returning. Without this,
-  // callers (e.g. displayPairingQRCode) may try to connect before the HTTP
-  // server is listening and get connection-refused errors.
+  // callers may try to connect before the HTTP server is listening and get
+  // connection-refused errors.
   const start = Date.now();
   const timeoutMs = 30000;
   let ready = false;

package/src/lib/ngrok.ts

@@ -12,13 +12,19 @@ import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants";
 
-function getConfigPath(): string {
-  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-  return join(root, "workspace", "config.json");
+function getDefaultWorkspaceDir(): string {
+  return (
+    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
+    join(homedir(), ".vellum", "workspace")
+  );
+}
+
+function getConfigPath(workspaceDir: string): string {
+  return join(workspaceDir, "config.json");
 }
 
-function loadRawConfig(): Record<string, unknown> {
-  const configPath = getConfigPath();
+function loadRawConfig(workspaceDir: string): Record<string, unknown> {
+  const configPath = getConfigPath(workspaceDir);
   if (!existsSync(configPath)) return {};
   return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
     string,
@@ -26,8 +32,11 @@ function loadRawConfig(): Record<string, unknown> {
   >;
 }
 
-function saveRawConfig(config: Record<string, unknown>): void {
-  const configPath = getConfigPath();
+function saveRawConfig(
+  workspaceDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = getConfigPath(workspaceDir);
   const dir = dirname(configPath);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
@@ -182,33 +191,33 @@ export async function waitForNgrokUrl(
 /**
  * Persist a public ingress URL to the workspace config and enable ingress.
  */
-function saveIngressUrl(publicUrl: string): void {
-  const config = loadRawConfig();
+function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
+  const config = loadRawConfig(workspaceDir);
   const ingress = (config.ingress ?? {}) as Record<string, unknown>;
   ingress.publicBaseUrl = publicUrl;
   ingress.enabled = true;
   config.ingress = ingress;
-  saveRawConfig(config);
+  saveRawConfig(workspaceDir, config);
 }
 
 /**
  * Clear the ingress public base URL from the workspace config.
  */
-function clearIngressUrl(): void {
-  const config = loadRawConfig();
+function clearIngressUrl(workspaceDir: string): void {
+  const config = loadRawConfig(workspaceDir);
   const ingress = (config.ingress ?? {}) as Record<string, unknown>;
   delete ingress.publicBaseUrl;
   config.ingress = ingress;
-  saveRawConfig(config);
+  saveRawConfig(workspaceDir, config);
 }
 
 /**
  * Check whether any webhook-based integrations (e.g. Telegram, Twilio) are
  * configured that require a public ingress URL.
  */
-function hasWebhookIntegrationsConfigured(): boolean {
+function hasWebhookIntegrationsConfigured(workspaceDir: string): boolean {
   try {
-    const config = loadRawConfig();
+    const config = loadRawConfig(workspaceDir);
     const telegram = config.telegram as Record<string, unknown> | undefined;
     if (telegram?.botUsername) return true;
     const twilio = config.twilio as Record<string, unknown> | undefined;
@@ -223,9 +232,9 @@ function hasWebhookIntegrationsConfigured(): boolean {
  * Check whether a non-ngrok ingress URL is already configured (e.g. custom
  * domain or cloud deployment), meaning ngrok is not needed.
  */
-function hasNonNgrokIngressUrl(): boolean {
+function hasNonNgrokIngressUrl(workspaceDir: string): boolean {
   try {
-    const config = loadRawConfig();
+    const config = loadRawConfig(workspaceDir);
     const ingress = config.ingress as Record<string, unknown> | undefined;
     const publicBaseUrl = ingress?.publicBaseUrl;
     if (!publicBaseUrl || typeof publicBaseUrl !== "string") return false;
@@ -244,6 +253,7 @@ function hasNonNgrokIngressUrl(): boolean {
  */
 export async function maybeStartNgrokTunnel(
   targetPort: number,
+  workspaceDir: string,
 ): Promise<ChildProcess | null> {
   // Managed/containerized deployments route webhooks through the platform's
   // callback proxy. ngrok is not needed and would not be reachable from the
@@ -252,8 +262,8 @@ export async function maybeStartNgrokTunnel(
     process.env.IS_CONTAINERIZED === "true" ||
     process.env.IS_CONTAINERIZED === "1";
   if (isContainerized) return null;
-  if (!hasWebhookIntegrationsConfigured()) return null;
-  if (hasNonNgrokIngressUrl()) return null;
+  if (!hasWebhookIntegrationsConfigured(workspaceDir)) return null;
+  if (hasNonNgrokIngressUrl(workspaceDir)) return null;
 
   const version = getNgrokVersion();
   if (!version) return null;
@@ -262,7 +272,7 @@ export async function maybeStartNgrokTunnel(
   const existingUrl = await findExistingTunnel(targetPort);
   if (existingUrl) {
     console.log(`   Found existing ngrok tunnel: ${existingUrl}`);
-    saveIngressUrl(existingUrl);
+    saveIngressUrl(workspaceDir, existingUrl);
     return null;
   }
 
@@ -274,14 +284,13 @@ export async function maybeStartNgrokTunnel(
   //   2. If pipe handles are destroyed, SIGPIPE kills ngrok on its next write.
   // Writing to a log file sidesteps both issues — the file descriptor is
   // inherited by the detached ngrok process and remains valid after CLI exit.
-  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-  const ngrokLogPath = join(root, "workspace", "data", "logs", "ngrok.log");
+  const ngrokLogPath = join(workspaceDir, "data", "logs", "ngrok.log");
   const ngrokProcess = startNgrokProcess(targetPort, ngrokLogPath);
   ngrokProcess.unref();
 
   try {
     const publicUrl = await waitForNgrokUrl();
-    saveIngressUrl(publicUrl);
+    saveIngressUrl(workspaceDir, publicUrl);
     console.log(`   Tunnel established: ${publicUrl}`);
 
     return ngrokProcess;
@@ -317,12 +326,13 @@ export async function runNgrokTunnel(): Promise<void> {
   console.log(`Using ${version}`);
 
   const port = GATEWAY_PORT;
+  const workspaceDir = getDefaultWorkspaceDir();
 
   // Check for an existing ngrok tunnel pointing at the gateway
   const existingUrl = await findExistingTunnel(port);
   if (existingUrl) {
     console.log(`Found existing ngrok tunnel: ${existingUrl}`);
-    saveIngressUrl(existingUrl);
+    saveIngressUrl(workspaceDir, existingUrl);
     console.log("Ingress URL saved to config.");
     console.log("");
     console.log(
@@ -349,7 +359,7 @@ export async function runNgrokTunnel(): Promise<void> {
     }
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
-      clearIngressUrl();
+      clearIngressUrl(workspaceDir);
     }
   };
 
@@ -398,7 +408,7 @@ export async function runNgrokTunnel(): Promise<void> {
   console.log(`Tunnel established: ${publicUrl}`);
   console.log(`Forwarding to:     localhost:${port}`);
 
-  saveIngressUrl(publicUrl);
+  saveIngressUrl(workspaceDir, publicUrl);
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");

package/src/lib/platform-client.ts

@@ -99,6 +99,23 @@ function tokenAuthHeader(token: string): Record<string, string> {
 const orgIdCache = new Map<string, { orgId: string; expiresAt: number }>();
 const ORG_ID_CACHE_TTL_MS = 60_000; // 60 seconds
 
+/**
+ * Drop the cached org ID for a given (token, platformUrl) pair. Used by the
+ * one-shot 401-retry path: a 401 on a session-token request frequently means
+ * the cached `Vellum-Organization-Id` header is stale (e.g. user switched
+ * orgs in another tab). Clearing the entry forces the next `authHeaders`
+ * call to refetch the org ID from the platform.
+ *
+ * Exported so other modules (e.g. local-runtime-client) can implement the
+ * same retry pattern without needing direct access to the cache map.
+ */
+export function invalidateOrgIdCache(
+  token: string,
+  platformUrl?: string,
+): void {
+  orgIdCache.delete(`${token}::${platformUrl ?? ""}`);
+}
+
 /**
  * Returns the full set of headers needed for an authenticated platform
  * API request:
@@ -196,6 +213,7 @@ export async function ensureSelfHostedLocalRegistration(
   clientPlatform: string,
   assistantVersion?: string,
   platformUrl?: string,
+  publicBaseUrl?: string,
 ): Promise<EnsureRegistrationResponse> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const body: Record<string, string> = {
@@ -206,6 +224,9 @@ export async function ensureSelfHostedLocalRegistration(
   if (assistantVersion) {
     body.assistant_version = assistantVersion;
   }
+  if (publicBaseUrl) {
+    body.public_ingress_url = publicBaseUrl;
+  }
 
   const response = await fetch(
     `${resolvedUrl}/v1/assistants/self-hosted-local/ensure-registration/`,
@@ -468,6 +489,7 @@ export async function hatchAssistant(
     method: "POST",
     headers: await authHeaders(token, platformUrl),
     body: JSON.stringify({}),
+    signal: AbortSignal.timeout(300_000),
   });
 
   if (response.ok) {
@@ -805,6 +827,45 @@ export function parseUnifiedJobStatus(
   };
 }
 
+export interface BundleCompatibility {
+  min_runtime_version: string;
+  max_runtime_version: string | null;
+}
+
+/**
+ * Thrown by platformRequestSignedUrl when the platform rejects a download
+ * signed-URL request because the target runtime version is outside the
+ * ExportJob's [min_runtime_version, max_runtime_version] band. Terminal
+ * — callers must NOT retry; surface to the user and abort the
+ * teleport/restore wizard.
+ */
+export class VersionMismatchError extends Error {
+  readonly bundleCompat: BundleCompatibility;
+  readonly targetRuntimeVersion: string;
+
+  constructor(bundleCompat: BundleCompatibility, targetRuntimeVersion: string) {
+    super(
+      VersionMismatchError.formatMessage(bundleCompat, targetRuntimeVersion),
+    );
+    this.name = "VersionMismatchError";
+    this.bundleCompat = bundleCompat;
+    this.targetRuntimeVersion = targetRuntimeVersion;
+  }
+
+  static formatMessage(
+    compat: BundleCompatibility,
+    targetRuntimeVersion: string,
+  ): string {
+    const range = compat.max_runtime_version
+      ? `${compat.min_runtime_version}–${compat.max_runtime_version}`
+      : `${compat.min_runtime_version}+`;
+    return (
+      `Cannot import: bundle requires runtime ${range}, but this runtime is ${targetRuntimeVersion}. ` +
+      `Update your runtime before importing.`
+    );
+  }
+}
+
 /**
  * Request a signed URL from the platform for either uploading a new bundle
  * or downloading an existing one. Calls `POST /v1/migrations/signed-url/`.
@@ -816,6 +877,9 @@ export function parseUnifiedJobStatus(
  *
  * Retries once with a fresh org-ID cache on 401 to match the retry pattern
  * used by other authenticated platform helpers.
+ *
+ * Throws {@link VersionMismatchError} on a 422 `version_mismatch` response,
+ * which is terminal — callers must NOT retry.
  */
 export async function platformRequestSignedUrl(
   params: {
@@ -823,6 +887,11 @@ export async function platformRequestSignedUrl(
     bundleKey?: string;
     contentType?: string;
     contentLength?: number;
+    // Source-side, upload only: runtime version that produced the bundle.
+    minRuntimeVersion?: string;
+    maxRuntimeVersion?: string | null;
+    // Target-side, download only: runtime version that will import.
+    targetRuntimeVersion?: string;
   },
   token: string,
   platformUrl?: string,
@@ -839,6 +908,17 @@ export async function platformRequestSignedUrl(
   if (params.contentLength !== undefined) {
     body.content_length = params.contentLength;
   }
+  if (params.minRuntimeVersion !== undefined) {
+    body.min_runtime_version = params.minRuntimeVersion;
+  }
+  if (params.maxRuntimeVersion !== undefined) {
+    // Explicit null is the documented "no upper bound" sentinel; keep it
+    // in the payload rather than stripping to undefined.
+    body.max_runtime_version = params.maxRuntimeVersion;
+  }
+  if (params.targetRuntimeVersion !== undefined) {
+    body.target_runtime_version = params.targetRuntimeVersion;
+  }
 
   const doRequest = async (): Promise<Response> =>
     fetch(`${resolvedUrl}/v1/migrations/signed-url/`, {
@@ -854,7 +934,7 @@ export async function platformRequestSignedUrl(
     // lookup. For session-token callers, a 401 frequently means the
     // cached org ID is stale — calling doRequest() again without clearing
     // the cache would just send the same stale header and fail again.
-    orgIdCache.delete(`${token}::${platformUrl ?? ""}`);
+    invalidateOrgIdCache(token, platformUrl);
     response = await doRequest();
   }
 
@@ -873,9 +953,28 @@ export async function platformRequestSignedUrl(
     };
   }
 
+  // Non-success body. Read once and reuse for both the 422 version-mismatch
+  // branch and the generic-error fallthrough — `response.json()` consumes
+  // the body, so a second read would always return undefined.
   const errorBody = (await response.json().catch(() => ({}))) as {
     detail?: string;
+    reason?: string;
+    bundle_compat?: BundleCompatibility;
+    target_runtime_version?: string;
   };
+
+  if (
+    response.status === 422 &&
+    errorBody.reason === "version_mismatch" &&
+    errorBody.bundle_compat &&
+    typeof errorBody.target_runtime_version === "string"
+  ) {
+    throw new VersionMismatchError(
+      errorBody.bundle_compat,
+      errorBody.target_runtime_version,
+    );
+  }
+
   throw new Error(
     errorBody.detail ??
       `Failed to request signed URL: ${response.status} ${response.statusText}`,

package/src/lib/retire-local.ts

@@ -1,9 +1,9 @@
 import { spawn } from "child_process";
+import { homedir } from "os";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
 
 import {
-  getBaseDir,
   getDaemonPidPath,
   loadAllAssistants,
 } from "./assistant-config.js";
@@ -77,7 +77,7 @@ export async function retireLocal(
   // For named instances (instanceDir differs from the base directory),
   // archive and remove the entire instance directory. For the default
   // instance, archive only the .vellum subdirectory.
-  const isNamedInstance = resources.instanceDir !== getBaseDir();
+  const isNamedInstance = resources.instanceDir !== homedir();
   const dirToArchive = isNamedInstance ? resources.instanceDir : vellumDir;
 
   // Move the data directory out of the way so the path is immediately available

package/src/lib/runtime-url.ts

@@ -28,3 +28,25 @@ export function resolveRuntimeMigrationUrl(
   }
   return `${entry.runtimeUrl}/v1/migrations/${subpath}`;
 }
+
+/**
+ * Resolve the URL for a generic runtime endpoint under `/v1/<subpath>`,
+ * taking the assistant's topology into account.
+ *
+ * - For local/docker assistants, `runtimeUrl` is the loopback gateway and
+ *   the runtime serves `/v1/<subpath>` directly.
+ * - For platform-managed (cloud="vellum") assistants the path is rewritten
+ *   to the wildcard runtime proxy:
+ *   `{platformUrl}/v1/assistants/<assistantId>/<subpath>`.
+ *
+ * The `subpath` is appended verbatim (e.g. `"identity"`).
+ */
+export function resolveRuntimeUrl(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  subpath: string,
+): string {
+  if (entry.cloud === "vellum") {
+    return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/${subpath}`;
+  }
+  return `${entry.runtimeUrl}/v1/${subpath}`;
+}