@vellumai/cli 0.7.0 → 0.7.2

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:
@@ -468,6 +485,7 @@ export async function hatchAssistant(
     method: "POST",
     headers: await authHeaders(token, platformUrl),
     body: JSON.stringify({}),
+    signal: AbortSignal.timeout(300_000),
   });
 
   if (response.ok) {
@@ -665,182 +683,10 @@ export async function rollbackPlatformAssistant(
   throw new Error(`Rollback failed: ${response.status} ${response.statusText}`);
 }
 
-// ---------------------------------------------------------------------------
-// Migration export
-// ---------------------------------------------------------------------------
-
-export async function platformInitiateExport(
-  token: string,
-  description?: string,
-  platformUrl?: string,
-): Promise<{ jobId: string; status: string }> {
-  const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(`${resolvedUrl}/v1/migrations/export/`, {
-    method: "POST",
-    headers: await authHeaders(token, platformUrl),
-    body: JSON.stringify({ description: description ?? "CLI backup" }),
-  });
-
-  if (response.status !== 201) {
-    const body = (await response.json().catch(() => ({}))) as {
-      detail?: string;
-    };
-    throw new Error(
-      body.detail ??
-        `Export initiation failed: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const body = (await response.json()) as {
-    job_id: string;
-    status: string;
-  };
-  return { jobId: body.job_id, status: body.status };
-}
-
-export async function platformPollExportStatus(
-  jobId: string,
-  token: string,
-  platformUrl?: string,
-): Promise<{ status: string; downloadUrl?: string; error?: string }> {
-  const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
-    `${resolvedUrl}/v1/migrations/export/${jobId}/status/`,
-    {
-      headers: await authHeaders(token, platformUrl),
-    },
-  );
-
-  if (response.status === 404) {
-    throw new Error("Export job not found");
-  }
-
-  if (!response.ok) {
-    throw new Error(
-      `Export status check failed: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const body = (await response.json()) as {
-    status: string;
-    download_url?: string;
-    error?: string;
-  };
-  return {
-    status: body.status,
-    downloadUrl: body.download_url,
-    error: body.error,
-  };
-}
-
-export async function platformDownloadExport(
-  downloadUrl: string,
-): Promise<Response> {
-  const response = await fetch(downloadUrl);
-  if (!response.ok) {
-    throw new Error(
-      `Download failed: ${response.status} ${response.statusText}`,
-    );
-  }
-  return response;
-}
-
-// ---------------------------------------------------------------------------
-// Migration import
-// ---------------------------------------------------------------------------
-
-export async function platformImportPreflight(
-  bundleData: Uint8Array<ArrayBuffer>,
-  token: string,
-  platformUrl?: string,
-): Promise<{ statusCode: number; body: Record<string, unknown> }> {
-  const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
-    `${resolvedUrl}/v1/migrations/import-preflight/`,
-    {
-      method: "POST",
-      headers: {
-        ...(await authHeaders(token, platformUrl)),
-        "Content-Type": "application/octet-stream",
-      },
-      body: new Blob([bundleData]),
-      signal: AbortSignal.timeout(120_000),
-    },
-  );
-
-  const body = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >;
-  return { statusCode: response.status, body };
-}
-
-export async function platformImportBundle(
-  bundleData: Uint8Array<ArrayBuffer>,
-  token: string,
-  platformUrl?: string,
-): Promise<{ statusCode: number; body: Record<string, unknown> }> {
-  const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(`${resolvedUrl}/v1/migrations/import/`, {
-    method: "POST",
-    headers: {
-      ...(await authHeaders(token, platformUrl)),
-      "Content-Type": "application/octet-stream",
-    },
-    body: new Blob([bundleData]),
-    signal: AbortSignal.timeout(300_000),
-  });
-
-  const body = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >;
-  return { statusCode: response.status, body };
-}
-
 // ---------------------------------------------------------------------------
 // Signed-URL upload flow
 // ---------------------------------------------------------------------------
 
-export async function platformRequestUploadUrl(
-  token: string,
-  platformUrl?: string,
-): Promise<{ uploadUrl: string; bundleKey: string; expiresAt: string }> {
-  const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(`${resolvedUrl}/v1/migrations/upload-url/`, {
-    method: "POST",
-    headers: await authHeaders(token, platformUrl),
-    body: JSON.stringify({ content_type: "application/octet-stream" }),
-  });
-
-  if (response.status === 201) {
-    const body = (await response.json()) as {
-      upload_url: string;
-      bundle_key: string;
-      expires_at: string;
-    };
-    return {
-      uploadUrl: body.upload_url,
-      bundleKey: body.bundle_key,
-      expiresAt: body.expires_at,
-    };
-  }
-
-  if (response.status === 404 || response.status === 503) {
-    throw new Error(
-      "Signed uploads are not available on this platform instance",
-    );
-  }
-
-  const errorBody = (await response.json().catch(() => ({}))) as {
-    detail?: string;
-  };
-  throw new Error(
-    errorBody.detail ??
-      `Failed to request upload URL: ${response.status} ${response.statusText}`,
-  );
-}
-
 export async function platformUploadToSignedUrl(
   uploadUrl: string,
   bundleData: Uint8Array<ArrayBuffer>,
@@ -911,46 +757,6 @@ export async function platformImportBundleFromGcs(
   return { statusCode: response.status, body };
 }
 
-export async function platformPollImportStatus(
-  jobId: string,
-  token: string,
-  platformUrl?: string,
-): Promise<{
-  status: string;
-  result?: Record<string, unknown>;
-  error?: string;
-}> {
-  const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
-    `${resolvedUrl}/v1/migrations/import/${jobId}/status/`,
-    {
-      headers: await authHeaders(token, platformUrl),
-    },
-  );
-
-  if (response.status === 404) {
-    throw new Error("Import job not found");
-  }
-
-  if (!response.ok) {
-    throw new Error(
-      `Import status check failed: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const body = (await response.json()) as {
-    status: string;
-    job_id?: string;
-    result?: Record<string, unknown>;
-    error?: string;
-  };
-  return {
-    status: body.status,
-    result: body.result,
-    error: body.error,
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Unified signed-url + job-status endpoints (teleport-gcs-unify)
 // ---------------------------------------------------------------------------
@@ -1017,6 +823,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/`.
@@ -1027,8 +872,10 @@ export function parseUnifiedJobStatus(
  *   runtime can GET the bundle from during an import-from-GCS flow.
  *
  * Retries once with a fresh org-ID cache on 401 to match the retry pattern
- * used by other authenticated platform helpers. 503 is bubbled up so
- * callers can decide to fall back (e.g. legacy inline upload).
+ * 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: {
@@ -1036,6 +883,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,
@@ -1052,6 +904,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/`, {
@@ -1067,7 +930,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();
   }
 
@@ -1086,15 +949,28 @@ export async function platformRequestSignedUrl(
     };
   }
 
-  if (response.status === 503) {
-    throw new Error(
-      `Signed URL endpoint unavailable (503) — caller may fall back`,
-    );
-  }
-
+  // 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/platform-releases.ts

@@ -7,6 +7,29 @@ export interface ResolvedImageRefs {
   source: "platform" | "dockerhub";
 }
 
+/**
+ * Fetch the latest stable release version from the platform API.
+ * Returns the version string (e.g. "0.7.0") or null if unavailable.
+ * The releases endpoint returns entries ordered newest-first.
+ */
+export async function fetchLatestStableVersion(): Promise<string | null> {
+  try {
+    const platformUrl = getPlatformUrl();
+    const response = await fetch(`${platformUrl}/v1/releases/?stable=true`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return null;
+
+    const releases = (await response.json()) as Array<{
+      version?: string;
+    }>;
+    const first = releases[0];
+    return first?.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Resolve image references for a given version.
  *

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

@@ -0,0 +1,52 @@
+import type { AssistantEntry } from "./assistant-config.js";
+
+/**
+ * Resolve the URL for a runtime migration endpoint, taking the assistant's
+ * topology into account.
+ *
+ * - For local/docker assistants, `runtimeUrl` is the loopback gateway and
+ *   the runtime serves `/v1/migrations/<subpath>` directly. The CLI hits
+ *   that path with guardian-token bearer auth.
+ * - For platform-managed (cloud="vellum") assistants, `runtimeUrl` is the
+ *   platform host (e.g. `https://platform.vellum.ai`). The platform's
+ *   `MigrationViewSet` does NOT expose `export-to-gcs` or arbitrary runtime
+ *   migration paths under `/v1/migrations/...`. The wildcard runtime proxy
+ *   at `/v1/assistants/<id>/<path:rest>` is what forwards arbitrary runtime
+ *   paths to the managed runtime — vembda's unified proxy bootstraps the
+ *   guardian token internally for the runtime call. From the CLI side it's
+ *   user-session auth.
+ *
+ * The `subpath` is appended to the migrations namespace verbatim
+ * (e.g. `"export-to-gcs"`, `"import-from-gcs"`, `\`jobs/${jobId}\``).
+ */
+export function resolveRuntimeMigrationUrl(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  subpath: string,
+): string {
+  if (entry.cloud === "vellum") {
+    return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/migrations/${subpath}`;
+  }
+  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}`;
+}

package/src/lib/sync-cloud-assistants.ts

@@ -0,0 +1,126 @@
+/**
+ * Sync cloud-managed (platform) assistants into the local lockfile.
+ *
+ * - Adds new platform assistants that aren't in the lockfile yet.
+ * - Removes lockfile entries whose IDs are no longer returned by the platform
+ *   (e.g. retired assistants).
+ *
+ * Used by both `vellum login` and `vellum ps` to keep the lockfile fresh.
+ */
+
+import {
+  loadAllAssistants,
+  removeAssistantEntry,
+  saveAssistantEntry,
+} from "./assistant-config.js";
+import {
+  fetchCurrentUser,
+  fetchPlatformAssistants,
+  getPlatformUrl,
+  readPlatformToken,
+} from "./platform-client.js";
+
+export type SyncLogger = (message: string) => void;
+
+export interface SyncResult {
+  added: number;
+  removed: number;
+  email?: string;
+}
+
+export interface SyncOptions {
+  log?: SyncLogger;
+}
+
+/**
+ * Fetch platform assistants and reconcile against the lockfile.
+ * Returns the number of entries added/removed, or `null` if the user
+ * is not logged in or the fetch fails.
+ */
+export async function syncCloudAssistants(
+  options?: SyncOptions,
+): Promise<SyncResult | null> {
+  const log = options?.log;
+  const platformUrl = getPlatformUrl();
+  log?.(`Platform URL: ${platformUrl}`);
+
+  const token = readPlatformToken();
+  if (!token) {
+    log?.("No platform token found — skipping cloud sync");
+    return null;
+  }
+  log?.(
+    `Token found (${token.length} chars, prefix: ${token.slice(0, 6)}…)`,
+  );
+
+  // Fetch user info for the login status line
+  let email: string | undefined;
+  try {
+    log?.("Fetching current user…");
+    const user = await fetchCurrentUser(token);
+    email = user.email;
+    log?.(`Authenticated as ${user.email} (${user.id})`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log?.(`Failed to fetch current user: ${msg}`);
+  }
+
+  let platformAssistants: { id: string; name: string; status: string }[];
+  try {
+    log?.("Fetching platform assistants…");
+    platformAssistants = await fetchPlatformAssistants(token);
+    log?.(
+      `Platform returned ${platformAssistants.length} assistant(s): ${platformAssistants.map((a) => a.name || a.id).join(", ") || "(none)"}`,
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log?.(`fetchPlatformAssistants failed: ${msg}`);
+    return null;
+  }
+
+  if (platformAssistants.length === 0) {
+    log?.(
+      "Platform returned 0 assistants — this may mean the API returned a non-ok status (check token validity)",
+    );
+  }
+
+  const platformIds = new Set(platformAssistants.map((a) => a.id));
+
+  // Add new platform assistants not yet in the lockfile
+  const existingCloudIds = new Set(
+    loadAllAssistants()
+      .filter((a) => a.cloud === "vellum")
+      .map((a) => a.assistantId),
+  );
+  log?.(
+    `Lockfile has ${existingCloudIds.size} cloud assistant(s): ${[...existingCloudIds].join(", ") || "(none)"}`,
+  );
+
+  let added = 0;
+  for (const pa of platformAssistants) {
+    if (!existingCloudIds.has(pa.id)) {
+      log?.(`Adding ${pa.name || pa.id} to lockfile`);
+      saveAssistantEntry({
+        assistantId: pa.id,
+        runtimeUrl: getPlatformUrl(),
+        cloud: "vellum",
+        species: "vellum",
+        hatchedAt: new Date().toISOString(),
+      });
+      added++;
+    }
+  }
+
+  // Remove stale lockfile entries that the platform no longer knows about
+  let removed = 0;
+  for (const id of existingCloudIds) {
+    if (!platformIds.has(id)) {
+      log?.(`Removing stale entry ${id} from lockfile`);
+      removeAssistantEntry(id);
+      removed++;
+    }
+  }
+
+  log?.(`Sync complete: ${added} added, ${removed} removed`);
+  return { added, removed, email };
+}

package/src/lib/terminal-client.ts

@@ -18,14 +18,19 @@ export async function createTerminalSession(
   cols: number,
   rows: number,
   platformUrl?: string,
+  service?: string,
 ): Promise<{ session_id: string }> {
   const baseUrl = platformUrl || getPlatformUrl();
+  const body: Record<string, unknown> = { cols, rows };
+  if (service) {
+    body.service = service;
+  }
   const response = await fetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/`,
     {
       method: "POST",
       headers: await authHeaders(token, platformUrl),
-      body: JSON.stringify({ cols, rows }),
+      body: JSON.stringify(body),
     },
   );
   if (!response.ok) {