@vellumai/cli 0.7.0 → 0.7.1

package/src/commands/login.ts

@@ -3,12 +3,10 @@ import { spawn } from "child_process";
 import { randomBytes } from "crypto";
 
 import {
-  findAssistantByName,
   getActiveAssistant,
-  loadLatestAssistant,
+  resolveAssistant,
   loadAllAssistants,
   removeAssistantEntry,
-  saveAssistantEntry,
   setActiveAssistant,
 } from "../lib/assistant-config";
 import { computeDeviceId } from "../lib/guardian-token";
@@ -26,6 +24,7 @@ import {
   reprovisionAssistantApiKey,
   savePlatformToken,
 } from "../lib/platform-client";
+import { syncCloudAssistants } from "../lib/sync-cloud-assistants";
 
 const LOGIN_TIMEOUT_MS = 120_000; // 2 minutes
 
@@ -205,10 +204,7 @@ export async function login(): Promise<void> {
     // Register the local assistant with the platform (non-fatal).
     // Mirrors the desktop app's LocalAssistantBootstrapService flow.
     try {
-      const activeName = getActiveAssistant();
-      const entry = activeName
-        ? findAssistantByName(activeName)
-        : loadLatestAssistant();
+      const entry = resolveAssistant();
 
       // Skip managed ("vellum") assistants — they are handled by the platform.
       if (entry && entry.cloud !== "vellum") {
@@ -282,36 +278,22 @@ export async function login(): Promise<void> {
     // This ensures `vellum ps` shows managed assistants immediately
     // after login (e.g. after a retire-and-rehatch cycle).
     try {
-      const platformAssistants = await fetchPlatformAssistants(token);
-      const existingIds = new Set(
-        loadAllAssistants()
-          .filter((a) => a.cloud === "vellum")
-          .map((a) => a.assistantId),
-      );
-
-      let synced = 0;
-      for (const pa of platformAssistants) {
-        if (!existingIds.has(pa.id)) {
-          saveAssistantEntry({
-            assistantId: pa.id,
-            runtimeUrl: getPlatformUrl(),
-            cloud: "vellum",
-            species: "vellum",
-            hatchedAt: new Date().toISOString(),
-          });
-          synced++;
+      const result = await syncCloudAssistants();
+      if (result) {
+        const total = result.added + result.removed;
+        if (total > 0) {
+          console.log(
+            `Synced cloud assistants (${result.added} added, ${result.removed} removed).`,
+          );
         }
       }
 
-      if (synced > 0) {
-        console.log(
-          `Synced ${synced} cloud assistant${synced > 1 ? "s" : ""} to local lockfile.`,
-        );
-      }
-
       // If no active assistant is set, activate the first cloud one.
-      if (!getActiveAssistant() && platformAssistants.length > 0) {
-        setActiveAssistant(platformAssistants[0].id);
+      if (!getActiveAssistant()) {
+        const platformAssistants = await fetchPlatformAssistants(token);
+        if (platformAssistants.length > 0) {
+          setActiveAssistant(platformAssistants[0].id);
+        }
       }
     } catch {
       // Non-fatal — login succeeded even if sync fails

package/src/commands/logs.ts

@@ -4,10 +4,7 @@ import { createInterface } from "readline";
 import { watch } from "fs";
 import { join } from "path";
 
-import {
-  findAssistantByName,
-  loadLatestAssistant,
-} from "../lib/assistant-config";
+import { resolveAssistant } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import { getLogDir } from "../lib/xdg-log";
@@ -593,9 +590,7 @@ async function showAwsLogs(
 export async function logs(): Promise<void> {
   const opts = parseArgs();
 
-  const entry = opts.name
-    ? findAssistantByName(opts.name)
-    : loadLatestAssistant();
+  const entry = resolveAssistant(opts.name);
 
   if (!entry) {
     if (opts.name) {

package/src/commands/ps.ts

@@ -28,6 +28,10 @@ import { pgrepExact } from "../lib/pgrep";
 import { probePort } from "../lib/port-probe";
 import { withStatusEmoji } from "../lib/status-emoji";
 import { execOutput } from "../lib/step-runner";
+import {
+  syncCloudAssistants,
+  type SyncLogger,
+} from "../lib/sync-cloud-assistants";
 
 // ── Table formatting helpers ────────────────────────────────────
 
@@ -468,7 +472,7 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
 
 // ── List all assistants (no arg) ────────────────────────────────
 
-async function listAllAssistants(): Promise<void> {
+async function listAllAssistants(verbose: boolean): Promise<void> {
   const { name: envName, source: envSource } = resolveEnvironmentSource();
   const sourceLabels: Record<typeof envSource, string> = {
     flag: "--environment flag",
@@ -476,7 +480,31 @@ async function listAllAssistants(): Promise<void> {
     config: "~/.config/vellum/environment",
     default: "default",
   };
-  console.log(`Environment: ${envName} (${sourceLabels[envSource]})\n`);
+  console.log(`Environment: ${envName} (${sourceLabels[envSource]})`);
+
+  const log: SyncLogger | undefined = verbose
+    ? (msg) => console.log(`  [verbose] ${msg}`)
+    : undefined;
+
+  // Refresh cloud assistants from the platform before listing.
+  const syncResult = await syncCloudAssistants({ log });
+
+  // Show platform login status
+  if (syncResult) {
+    const parts = [`Platform: logged in`];
+    if (syncResult.email) parts[0] += ` as ${syncResult.email}`;
+    if (syncResult.added > 0 || syncResult.removed > 0) {
+      const changes: string[] = [];
+      if (syncResult.added > 0) changes.push(`${syncResult.added} added`);
+      if (syncResult.removed > 0)
+        changes.push(`${syncResult.removed} removed`);
+      parts.push(`(${changes.join(", ")})`);
+    }
+    console.log(parts.join(" "));
+  } else {
+    console.log("Platform: not logged in");
+  }
+  console.log("");
 
   const assistants = loadAllAssistants();
   const activeId = getActiveAssistant();
@@ -599,21 +627,28 @@ async function listAllAssistants(): Promise<void> {
 export async function ps(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum ps [<name>]");
+    console.log("Usage: vellum ps [<name>] [--verbose]");
     console.log("");
     console.log(
       "List all assistants, or show processes for a specific assistant.",
     );
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>    Show processes for the named assistant");
+    console.log("  <name>       Show processes for the named assistant");
+    console.log("");
+    console.log("Options:");
+    console.log(
+      "  --verbose    Show diagnostic logs (platform sync, auth issues)",
+    );
     process.exit(0);
   }
 
-  const assistantId = process.argv[3];
+  const verbose = args.includes("--verbose");
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const assistantId = positional[0];
 
   if (!assistantId) {
-    await listAllAssistants();
+    await listAllAssistants(verbose);
     return;
   }
 

package/src/commands/restore.ts

@@ -9,13 +9,11 @@ import {
 import {
   readPlatformToken,
   rollbackPlatformAssistant,
-  platformImportPreflight,
-  platformImportBundle,
-  platformRequestUploadUrl,
+  platformRequestSignedUrl,
   platformUploadToSignedUrl,
   platformImportPreflightFromGcs,
   platformImportBundleFromGcs,
-  platformPollImportStatus,
+  platformPollJobStatus,
 } from "../lib/platform-client.js";
 import { performDockerRollback } from "../lib/upgrade-lifecycle.js";
 
@@ -181,24 +179,14 @@ async function restorePlatform(
     process.exit(1);
   }
 
-  // Step 1.5 — Upload to GCS via signed URL (with fallback to inline)
-  let bundleKey: string | null = null;
-  try {
-    const { uploadUrl, bundleKey: key } = await platformRequestUploadUrl(
-      token,
-      entry.runtimeUrl,
-    );
-    bundleKey = key;
-    console.log("Uploading bundle...");
-    await platformUploadToSignedUrl(uploadUrl, new Uint8Array(bundleData));
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("not available")) {
-      bundleKey = null;
-    } else {
-      throw err;
-    }
-  }
+  // Step 1.5 — Upload to GCS via signed URL
+  const { url: uploadUrl, bundleKey } = await platformRequestSignedUrl(
+    { operation: "upload" },
+    token,
+    entry.runtimeUrl,
+  );
+  console.log("Uploading bundle...");
+  await platformUploadToSignedUrl(uploadUrl, new Uint8Array(bundleData));
 
   // Step 2 — Dry-run path
   if (opts.dryRun) {
@@ -213,17 +201,11 @@ async function restorePlatform(
 
     let preflightResult: { statusCode: number; body: Record<string, unknown> };
     try {
-      preflightResult = bundleKey
-        ? await platformImportPreflightFromGcs(
-            bundleKey,
-            token,
-            entry.runtimeUrl,
-          )
-        : await platformImportPreflight(
-            new Uint8Array(bundleData),
-            token,
-            entry.runtimeUrl,
-          );
+      preflightResult = await platformImportPreflightFromGcs(
+        bundleKey,
+        token,
+        entry.runtimeUrl,
+      );
     } catch (err) {
       if (err instanceof Error && err.name === "TimeoutError") {
         console.error("Error: Preflight request timed out after 2 minutes.");
@@ -353,13 +335,11 @@ async function restorePlatform(
 
   let importResult: { statusCode: number; body: Record<string, unknown> };
   try {
-    importResult = bundleKey
-      ? await platformImportBundleFromGcs(bundleKey, token, entry.runtimeUrl)
-      : await platformImportBundle(
-          new Uint8Array(bundleData),
-          token,
-          entry.runtimeUrl,
-        );
+    importResult = await platformImportBundleFromGcs(
+      bundleKey,
+      token,
+      entry.runtimeUrl,
+    );
   } catch (err) {
     if (err instanceof Error && err.name === "TimeoutError") {
       console.error("Error: Import request timed out after 5 minutes.");
@@ -420,13 +400,9 @@ async function restorePlatform(
     while (Date.now() < deadline) {
       await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
 
-      let status: {
-        status: string;
-        result?: Record<string, unknown>;
-        error?: string;
-      };
+      let status: Awaited<ReturnType<typeof platformPollJobStatus>>;
       try {
-        status = await platformPollImportStatus(jobId, token, entry.runtimeUrl);
+        status = await platformPollJobStatus(jobId, token, entry.runtimeUrl);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         if (msg.includes("not found")) {
@@ -451,7 +427,10 @@ async function restorePlatform(
       }
 
       if (status.status === "complete") {
-        importResult = { statusCode: 200, body: status.result ?? {} };
+        importResult = {
+          statusCode: 200,
+          body: (status.result as Record<string, unknown>) ?? {},
+        };
         break;
       }
 

package/src/commands/ssh.ts

@@ -1,9 +1,6 @@
 import { spawn } from "child_process";
 
-import {
-  findAssistantByName,
-  loadLatestAssistant,
-} from "../lib/assistant-config";
+import { resolveAssistant } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
@@ -58,7 +55,7 @@ export async function ssh(): Promise<void> {
   }
 
   const name = process.argv[3];
-  const entry = name ? findAssistantByName(name) : loadLatestAssistant();
+  const entry = resolveAssistant(name);
 
   if (!entry) {
     if (name) {

package/src/commands/teleport.ts

@@ -17,7 +17,6 @@ import {
   getPlatformUrl,
   hatchAssistant,
   checkExistingPlatformAssistant,
-  platformInitiateExport,
   platformPollJobStatus,
   platformImportBundleFromGcs,
   platformImportPreflightFromGcs,
@@ -391,7 +390,7 @@ async function exportFromAssistant(
         entry.runtimeUrl,
         entry.assistantId,
         async (token) => {
-          const r = await localRuntimeExportToGcs(entry.runtimeUrl, token, {
+          const r = await localRuntimeExportToGcs(entry, token, {
             uploadUrl,
             description: "teleport export",
           });
@@ -418,8 +417,7 @@ async function exportFromAssistant(
 
     const terminal = await pollJobUntilDone({
       label: "local-runtime export",
-      poll: () =>
-        localRuntimePollJobStatus(entry.runtimeUrl, accessToken, jobId),
+      poll: () => localRuntimePollJobStatus(entry, accessToken, jobId),
       // Large exports can take longer than a guardian-token lease. If the
       // runtime returns 401 mid-poll, re-lease a fresh token and rebind the
       // closure variable so the next poll uses it.
@@ -442,22 +440,46 @@ async function exportFromAssistant(
   }
 
   if (cloud === "vellum") {
-    // Platform source — initiate a server-side export. The platform writes
-    // the bundle to its own `exports/<org>/<id>.vbundle` key; we discover
-    // that key via the unified job-status endpoint's `bundle_key` field.
-    const { jobId } = await platformInitiateExport(
+    // Platform source — request a signed upload URL on the same platform
+    // instance the bundle will eventually be imported from, then ask the
+    // managed runtime to export directly to GCS. The runtime endpoint is
+    // reached via the platform's wildcard runtime proxy at
+    // `/v1/assistants/<id>/migrations/export-to-gcs` — the
+    // `localRuntimeExportToGcs` helper uses `resolveRuntimeMigrationUrl` to
+    // pick that shape for `cloud === "vellum"` and `migrationRequestHeaders`
+    // to send platform-token auth (no guardian-token bootstrap).
+    const { url: uploadUrl, bundleKey } = await platformRequestSignedUrl(
+      { operation: "upload" },
       platformToken,
-      "teleport export",
-      entry.runtimeUrl,
+      bundlePlatformUrl,
     );
 
+    let jobId: string;
+    let exportPlatformToken = platformToken;
+    try {
+      ({ jobId } = await localRuntimeExportToGcs(entry, exportPlatformToken, {
+        uploadUrl,
+        description: "teleport export",
+      }));
+    } catch (err) {
+      if (err instanceof MigrationInProgressError) {
+        console.error(
+          `Error: Another teleport export is already in progress on '${entry.assistantId}' (job ${err.existingJobId}). Wait for it to finish or check its status, then re-run.`,
+        );
+        process.exit(1);
+      }
+      throw err;
+    }
+
     console.log(`Export started (job ${jobId})...`);
 
-    let exportPlatformToken = platformToken;
+    // Polling also goes through the wildcard proxy — `localRuntimePollJobStatus`
+    // builds `/v1/assistants/<id>/migrations/jobs/<jobId>` for `cloud === "vellum"`
+    // (the dedicated `/v1/migrations/jobs/{id}/` endpoint queries platform-side
+    // ImportJob records and 404s on runtime-created job IDs).
     const terminal = await pollJobUntilDone({
       label: "platform export",
-      poll: () =>
-        platformPollJobStatus(jobId, exportPlatformToken, entry.runtimeUrl),
+      poll: () => localRuntimePollJobStatus(entry, exportPlatformToken, jobId),
       // The platform token is normally static per-process, but re-reading the
       // on-disk credential covers the case where the user ran `vellum login`
       // in another terminal during a long migration. A persistent 401 after
@@ -478,14 +500,7 @@ async function exportFromAssistant(
       process.exit(1);
     }
 
-    if (!terminal.bundleKey) {
-      console.error(
-        "Export completed but the platform did not return a bundle_key. Is the platform up to date?",
-      );
-      process.exit(1);
-    }
-
-    return { bundleKey: terminal.bundleKey };
+    return { bundleKey };
   }
 
   console.error(
@@ -659,7 +674,7 @@ async function importToAssistant(
         entry.runtimeUrl,
         entry.assistantId,
         async (token) => {
-          const r = await localRuntimeImportFromGcs(entry.runtimeUrl, token, {
+          const r = await localRuntimeImportFromGcs(entry, token, {
             bundleUrl,
           });
           return { jobId: r.jobId, token };
@@ -682,8 +697,7 @@ async function importToAssistant(
 
     const terminal = await pollJobUntilDone({
       label: "local-runtime import",
-      poll: () =>
-        localRuntimePollJobStatus(entry.runtimeUrl, accessToken, jobId),
+      poll: () => localRuntimePollJobStatus(entry, accessToken, jobId),
       refreshOn401: async () => {
         accessToken = await getAccessToken(
           entry.runtimeUrl,

package/src/commands/tunnel.ts

@@ -1,7 +1,4 @@
-import {
-  findAssistantByName,
-  loadLatestAssistant,
-} from "../lib/assistant-config";
+import { resolveAssistant } from "../lib/assistant-config";
 import { runNgrokTunnel } from "../lib/ngrok";
 
 const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
@@ -63,9 +60,7 @@ function parseArgs(): TunnelArgs {
 export async function tunnel(): Promise<void> {
   const { assistantName, provider } = parseArgs();
 
-  const entry = assistantName
-    ? findAssistantByName(assistantName)
-    : loadLatestAssistant();
+  const entry = resolveAssistant(assistantName ?? undefined);
 
   if (!entry) {
     if (assistantName) {

package/src/commands/upgrade.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from "crypto";
+import { spawnSync } from "child_process";
 
 import cliPkg from "../../package.json";
 
@@ -16,7 +17,10 @@ import {
   startContainers,
   stopContainers,
 } from "../lib/docker";
-import { resolveImageRefs } from "../lib/platform-releases";
+import {
+  fetchLatestStableVersion,
+  resolveImageRefs,
+} from "../lib/platform-releases";
 import {
   authHeaders,
   getPlatformUrl,
@@ -47,6 +51,7 @@ import { compareVersions } from "../lib/version-compat.js";
 interface UpgradeArgs {
   name: string | null;
   version: string | null;
+  latest: boolean;
   prepare: boolean;
   finalize: boolean;
 }
@@ -55,6 +60,7 @@ function parseArgs(): UpgradeArgs {
   const args = process.argv.slice(3);
   let name: string | null = null;
   let version: string | null = null;
+  let latest = false;
   let prepare = false;
   let finalize = false;
 
@@ -73,7 +79,10 @@ function parseArgs(): UpgradeArgs {
       console.log("");
       console.log("Options:");
       console.log(
-        "  --version <version>  Target version to upgrade to (default: latest)",
+        "  --version <version>  Target version to upgrade to (default: CLI version)",
+      );
+      console.log(
+        "  --latest             Upgrade to the latest stable release, updating the CLI first if needed",
       );
       console.log(
         "  --prepare            Run pre-upgrade steps only (backup, notify) without swapping versions",
@@ -84,7 +93,10 @@ function parseArgs(): UpgradeArgs {
       console.log("");
       console.log("Examples:");
       console.log(
-        "  vellum upgrade                              # Upgrade the active assistant to the latest version",
+        "  vellum upgrade                              # Upgrade the active assistant to the CLI's version",
+      );
+      console.log(
+        "  vellum upgrade --latest                     # Upgrade CLI + assistant to the latest stable release",
       );
       console.log(
         "  vellum upgrade my-assistant                  # Upgrade a specific assistant by name",
@@ -102,6 +114,8 @@ function parseArgs(): UpgradeArgs {
       }
       version = next;
       i++;
+    } else if (arg === "--latest") {
+      latest = true;
     } else if (arg === "--prepare") {
       prepare = true;
     } else if (arg === "--finalize") {
@@ -121,7 +135,13 @@ function parseArgs(): UpgradeArgs {
     process.exit(1);
   }
 
-  return { name, version, prepare, finalize };
+  if (latest && version) {
+    console.error("Error: --latest and --version are mutually exclusive.");
+    emitCliError("UNKNOWN", "--latest and --version are mutually exclusive");
+    process.exit(1);
+  }
+
+  return { name, version, latest, prepare, finalize };
 }
 
 function resolveCloud(entry: AssistantEntry): string {
@@ -867,8 +887,80 @@ async function upgradeFinalize(
   );
 }
 
+/**
+ * When `--latest` is passed, resolve the latest stable version from the
+ * platform API.  If the running CLI is older than that version, self-update
+ * the CLI via `bun install -g` and re-exec so the new CLI's upgrade logic
+ * (and its cliPkg.version) drives the rest of the upgrade.
+ *
+ * Returns the resolved latest version string (e.g. "v0.7.0") for callers
+ * that need it.  If the CLI was updated and re-exec'd, this function never
+ * returns — the process is replaced.
+ */
+async function resolveLatestAndMaybeSelfUpdate(
+  name: string | null,
+): Promise<string> {
+  console.log("🔍 Fetching latest stable release...");
+  const latestVersion = await fetchLatestStableVersion();
+  if (!latestVersion) {
+    console.error(
+      "Error: Could not determine the latest stable release from the platform API.",
+    );
+    emitCliError(
+      "UNKNOWN",
+      "Could not determine the latest stable release from the platform API",
+    );
+    process.exit(1);
+  }
+
+  const latestTag = latestVersion.startsWith("v")
+    ? latestVersion
+    : `v${latestVersion}`;
+  const currentTag = cliPkg.version ? `v${cliPkg.version}` : null;
+
+  console.log(`   Latest stable: ${latestTag}`);
+  console.log(`   CLI version:   ${currentTag ?? "unknown"}\n`);
+
+  // Check if the CLI needs updating
+  const cmp = currentTag ? compareVersions(latestTag, currentTag) : null;
+  if (cmp !== null && cmp > 0) {
+    console.log(`🔄 Updating CLI to ${latestTag}...`);
+    const installResult = spawnSync(
+      "bun",
+      ["install", "-g", `vellum@${latestVersion}`],
+      { stdio: "inherit" },
+    );
+    if (installResult.error || installResult.status !== 0) {
+      const detail =
+        installResult.error?.message ?? `exited with code ${installResult.status}`;
+      console.error(`\n❌ CLI self-update failed: ${detail}`);
+      emitCliError("CLI_UPDATE_FAILED", "CLI self-update failed", detail);
+      process.exit(1);
+    }
+    console.log(`✅ CLI updated to ${latestTag}\n`);
+
+    // Re-exec with the updated CLI. Pass --version instead of --latest
+    // to avoid re-fetching and to prevent infinite re-exec loops.
+    const reexecArgs = ["upgrade"];
+    if (name) reexecArgs.push(name);
+    reexecArgs.push("--version", latestTag);
+
+    console.log(`🚀 Re-running upgrade with updated CLI...\n`);
+    const reexecResult = spawnSync("vellum", reexecArgs, {
+      stdio: "inherit",
+    });
+    process.exit(reexecResult.status ?? 1);
+  }
+
+  if (cmp !== null && cmp === 0) {
+    console.log(`✅ CLI is already on the latest version (${latestTag})\n`);
+  }
+
+  return latestTag;
+}
+
 export async function upgrade(): Promise<void> {
-  const { name, version, prepare, finalize } = parseArgs();
+  const { name, version, latest, prepare, finalize } = parseArgs();
   const entry = resolveTargetAssistant(name);
 
   if (prepare) {
@@ -881,16 +973,25 @@ export async function upgrade(): Promise<void> {
     return;
   }
 
+  // When --latest is passed, resolve the target from the platform API and
+  // self-update the CLI if it's behind.  The resolved version is then used
+  // as the explicit target for the rest of the upgrade flow.
+  let effectiveVersion = version;
+  if (latest) {
+    const latestTag = await resolveLatestAndMaybeSelfUpdate(name);
+    effectiveVersion = latestTag;
+  }
+
   const cloud = resolveCloud(entry);
 
   try {
     if (cloud === "docker") {
-      await upgradeDocker(entry, version);
+      await upgradeDocker(entry, effectiveVersion);
       return;
     }
 
     if (cloud === "vellum") {
-      await upgradePlatform(entry, version);
+      await upgradePlatform(entry, effectiveVersion);
       return;
     }
   } catch (err) {