@vellumai/cli 0.5.7 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/commands/backup.ts

@@ -4,6 +4,13 @@ import { dirname, join } from "path";
 import { findAssistantByName } from "../lib/assistant-config";
 import { getBackupsDir, formatSize } from "../lib/backup-ops.js";
 import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
+import {
+  readPlatformToken,
+  fetchOrganizationId,
+  platformInitiateExport,
+  platformPollExportStatus,
+  platformDownloadExport,
+} from "../lib/platform-client.js";
 
 export async function backup(): Promise<void> {
   const args = process.argv.slice(3);
@@ -55,6 +62,14 @@ export async function backup(): Promise<void> {
     process.exit(1);
   }
 
+  // Detect topology and route platform assistants through Django export
+  const cloud =
+    entry.cloud || (entry.project ? "gcp" : entry.sshUser ? "custom" : "local");
+  if (cloud === "vellum") {
+    await backupPlatform(name, outputArg);
+    return;
+  }
+
   // Obtain an auth token
   let accessToken: string;
   const tokenData = loadGuardianToken(entry.assistantId);
@@ -164,3 +179,112 @@ export async function backup(): Promise<void> {
     console.log(`Manifest SHA-256: ${manifestSha}`);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Platform (Vellum-hosted) backup via Django async migration export
+// ---------------------------------------------------------------------------
+
+async function backupPlatform(name: string, outputArg?: string): Promise<void> {
+  // Step 1 — Authenticate
+  const token = readPlatformToken();
+  if (!token) {
+    console.error("Not logged in. Run 'vellum login' first.");
+    process.exit(1);
+  }
+
+  let orgId: string;
+  try {
+    orgId = await fetchOrganizationId(token);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("401") || msg.includes("403")) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Step 2 — Initiate export job
+  let jobId: string;
+  try {
+    const result = await platformInitiateExport(token, orgId, "CLI backup");
+    jobId = result.jobId;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("401") || msg.includes("403")) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+    if (msg.includes("429")) {
+      console.error(
+        "Too many export requests. Please wait before trying again.",
+      );
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  console.log(`Export started (job ${jobId})...`);
+
+  // Step 3 — Poll for completion
+  const POLL_INTERVAL_MS = 2_000;
+  const TIMEOUT_MS = 5 * 60 * 1_000; // 5 minutes
+  const deadline = Date.now() + TIMEOUT_MS;
+  let downloadUrl: string | undefined;
+
+  while (Date.now() < deadline) {
+    let status: { status: string; downloadUrl?: string; error?: string };
+    try {
+      status = await platformPollExportStatus(jobId, token, orgId);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      // Let non-transient errors (e.g. 404 "job not found") propagate immediately
+      if (msg.includes("not found")) {
+        throw err;
+      }
+      console.warn(`Polling failed, retrying... (${msg})`);
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+      continue;
+    }
+
+    if (status.status === "complete") {
+      downloadUrl = status.downloadUrl;
+      break;
+    }
+
+    if (status.status === "failed") {
+      console.error(`Export failed: ${status.error ?? "unknown error"}`);
+      process.exit(1);
+    }
+
+    // Still in progress — wait and retry
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+
+  if (!downloadUrl) {
+    console.error("Export timed out after 5 minutes.");
+    process.exit(1);
+  }
+
+  // Step 4 — Download bundle
+  const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const outputPath =
+    outputArg || join(getBackupsDir(), `${name}-${isoTimestamp}.vbundle`);
+
+  mkdirSync(dirname(outputPath), { recursive: true });
+
+  const response = await platformDownloadExport(downloadUrl);
+  const arrayBuffer = await response.arrayBuffer();
+  const data = new Uint8Array(arrayBuffer);
+
+  writeFileSync(outputPath, data);
+
+  // Step 5 — Print success
+  console.log(`Backup saved to ${outputPath}`);
+  console.log(`Size: ${formatSize(data.byteLength)}`);
+
+  const manifestSha = response.headers.get("X-Vbundle-Manifest-Sha256");
+  if (manifestSha) {
+    console.log(`Manifest SHA-256: ${manifestSha}`);
+  }
+}

package/src/commands/hatch.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "crypto";
 import {
   appendFileSync,
   existsSync,
@@ -102,7 +103,7 @@ export async function buildStartupScript(
   instanceName: string,
   cloud: RemoteHost,
   configValues: Record<string, string> = {},
-): Promise<string> {
+): Promise<{ script: string; laptopBootstrapSecret: string }> {
   const platformUrl = getPlatformUrl();
   const logPath =
     cloud === "custom"
@@ -115,18 +116,32 @@ export async function buildStartupScript(
   const ownershipFixup = buildOwnershipFixup();
 
   if (species === "openclaw") {
-    return await buildOpenclawStartupScript(
+    const script = await buildOpenclawStartupScript(
       sshUser,
       providerApiKeys,
       timestampRedirect,
       userSetup,
       ownershipFixup,
     );
+    return { script, laptopBootstrapSecret: "" };
   }
 
+  // Generate a bootstrap secret for the laptop that initiated this remote
+  // hatch. The startup script exports it as GUARDIAN_BOOTSTRAP_SECRET so
+  // that when `vellum hatch --remote docker` runs on the VM, the docker
+  // hatch detects the pre-set env var and appends its own secret.
+  const laptopBootstrapSecret = randomBytes(32).toString("hex");
+
   // Build bash lines that set each provider API key as a shell variable
   // and corresponding dotenv lines for the env file.
-  const envSetLines = Object.entries(providerApiKeys)
+  // Include the laptop bootstrap secret so that when the remote runs
+  // `vellum hatch --remote docker`, the docker hatch detects the pre-set
+  // env var and appends its own secret for multi-secret guardian init.
+  const allEnvEntries: Record<string, string> = {
+    ...providerApiKeys,
+    GUARDIAN_BOOTSTRAP_SECRET: laptopBootstrapSecret,
+  };
+  const envSetLines = Object.entries(allEnvEntries)
     .map(([envVar, value]) => `${envVar}=${value}`)
     .join("\n");
   const dotenvLines = Object.keys(providerApiKeys)
@@ -149,7 +164,9 @@ echo "Default workspace config written to \$VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH
 `;
   }
 
-  return `#!/bin/bash
+  return {
+    laptopBootstrapSecret,
+    script: `#!/bin/bash
 set -e
 
 ${timestampRedirect}
@@ -166,6 +183,7 @@ DOTENV_EOF
 
 ${ownershipFixup}
 ${configWriteBlock}
+export GUARDIAN_BOOTSTRAP_SECRET
 export VELLUM_SSH_USER="\$SSH_USER"
 export VELLUM_ASSISTANT_NAME="\$VELLUM_ASSISTANT_NAME"
 export VELLUM_CLOUD="${cloud}"
@@ -175,7 +193,8 @@ echo "Install script downloaded (\$(wc -c < ${INSTALL_SCRIPT_REMOTE_PATH}) bytes
 chmod +x ${INSTALL_SCRIPT_REMOTE_PATH}
 echo "Running install script..."
 source ${INSTALL_SCRIPT_REMOTE_PATH}
-`;
+`,
+  };
 }
 
 const DEFAULT_REMOTE: RemoteHost = "local";

package/src/commands/restore.ts

@@ -1,45 +1,71 @@
 import { existsSync, readFileSync } from "fs";
 
 import { findAssistantByName } from "../lib/assistant-config.js";
+import type { AssistantEntry } from "../lib/assistant-config.js";
 import {
   loadGuardianToken,
   leaseGuardianToken,
 } from "../lib/guardian-token.js";
+import {
+  readPlatformToken,
+  fetchOrganizationId,
+  rollbackPlatformAssistant,
+  platformImportPreflight,
+  platformImportBundle,
+} from "../lib/platform-client.js";
+import { performDockerRollback } from "../lib/upgrade-lifecycle.js";
 
 function printUsage(): void {
-  console.log("Usage: vellum restore <name> --from <path> [--dry-run]");
+  console.log(
+    "Usage: vellum restore <name> --from <path> [--version <version>] [--dry-run]",
+  );
   console.log("");
-  console.log("Restore a .vbundle backup into a running assistant.");
+  console.log("Restore data from a .vbundle backup into an assistant.");
+  console.log(
+    "With --version, also rolls back to the specified version first.",
+  );
   console.log("");
   console.log("Arguments:");
-  console.log("  <name>              Name of the assistant to restore into");
+  console.log("  <name>               Name of the assistant to restore into");
   console.log("");
   console.log("Options:");
+  console.log("  --from <path>        Path to the .vbundle file (required)");
+  console.log(
+    "  --version <version>  Roll back to this version before importing data",
+  );
   console.log(
-    "  --from <path>       Path to the .vbundle file to restore (required)",
+    "  --dry-run            Show what would change without applying (data-only)",
   );
-  console.log("  --dry-run           Show what would change without applying");
   console.log("");
   console.log("Examples:");
-  console.log("  vellum restore my-assistant --from ~/Desktop/backup.vbundle");
+  console.log("  vellum restore my-assistant --from backup.vbundle");
   console.log(
-    "  vellum restore my-assistant --from ~/Desktop/backup.vbundle --dry-run",
+    "  vellum restore my-assistant --from backup.vbundle --version v1.2.3",
   );
+  console.log("  vellum restore my-assistant --from backup.vbundle --dry-run");
 }
 
 function parseArgs(argv: string[]): {
   name: string | undefined;
   fromPath: string | undefined;
+  version: string | undefined;
   dryRun: boolean;
   help: boolean;
 } {
   const args = argv.slice(3);
 
   if (args.includes("--help") || args.includes("-h")) {
-    return { name: undefined, fromPath: undefined, dryRun: false, help: true };
+    return {
+      name: undefined,
+      fromPath: undefined,
+      version: undefined,
+      dryRun: false,
+      help: true,
+    };
   }
 
   let fromPath: string | undefined;
+  let version: string | undefined;
   const dryRun = args.includes("--dry-run");
   const positionals: string[] = [];
 
@@ -47,6 +73,14 @@ function parseArgs(argv: string[]): {
     if (args[i] === "--from" && args[i + 1]) {
       fromPath = args[i + 1];
       i++; // skip the value
+    } else if (args[i] === "--version") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --version requires a value");
+        process.exit(1);
+      }
+      version = next;
+      i++; // skip the value
     } else if (args[i] === "--dry-run") {
       // already handled above
     } else if (!args[i].startsWith("-")) {
@@ -54,7 +88,7 @@ function parseArgs(argv: string[]): {
     }
   }
 
-  return { name: positionals[0], fromPath, dryRun, help: false };
+  return { name: positionals[0], fromPath, version, dryRun, help: false };
 }
 
 async function getAccessToken(
@@ -126,14 +160,289 @@ interface ImportResponse {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Platform (Vellum-hosted) restore via Django migration import
+// ---------------------------------------------------------------------------
+
+async function restorePlatform(
+  entry: AssistantEntry,
+  name: string,
+  bundleData: Buffer,
+  opts: { version?: string; dryRun: boolean },
+): Promise<void> {
+  // Step 1 — Authenticate
+  const token = readPlatformToken();
+  if (!token) {
+    console.error("Not logged in. Run 'vellum login' first.");
+    process.exit(1);
+  }
+
+  let orgId: string;
+  try {
+    orgId = await fetchOrganizationId(token);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("401") || msg.includes("403")) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Step 2 — Dry-run path
+  if (opts.dryRun) {
+    if (opts.version) {
+      console.error(
+        "Dry-run is not supported with --version. Use `vellum restore --from <path> --dry-run` for data-only preflight.",
+      );
+      process.exit(1);
+    }
+
+    console.log("Running preflight analysis...\n");
+
+    let preflightResult: { statusCode: number; body: Record<string, unknown> };
+    try {
+      preflightResult = await platformImportPreflight(
+        new Uint8Array(bundleData),
+        token,
+        orgId,
+      );
+    } catch (err) {
+      if (err instanceof Error && err.name === "TimeoutError") {
+        console.error("Error: Preflight request timed out after 2 minutes.");
+        process.exit(1);
+      }
+      throw err;
+    }
+
+    if (
+      preflightResult.statusCode === 401 ||
+      preflightResult.statusCode === 403
+    ) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+      process.exit(1);
+    }
+
+    if (preflightResult.statusCode === 404) {
+      console.error(
+        "No managed assistant found. Ensure your assistant is running.",
+      );
+      process.exit(1);
+    }
+
+    if (preflightResult.statusCode === 409) {
+      console.error(
+        "Multiple assistants found. This is a platform configuration issue.",
+      );
+      process.exit(1);
+    }
+
+    if (
+      preflightResult.statusCode === 502 ||
+      preflightResult.statusCode === 503 ||
+      preflightResult.statusCode === 504
+    ) {
+      console.error(
+        `Assistant is unreachable. Try 'vellum wake ${name}' first.`,
+      );
+      process.exit(1);
+    }
+
+    if (preflightResult.statusCode !== 200) {
+      console.error(
+        `Error: Preflight check failed (${preflightResult.statusCode}): ${JSON.stringify(preflightResult.body)}`,
+      );
+      process.exit(1);
+    }
+
+    const result = preflightResult.body as unknown as PreflightResponse;
+
+    if (!result.can_import) {
+      if (result.validation?.errors?.length) {
+        console.error("Import blocked by validation errors:");
+        for (const err of result.validation.errors) {
+          console.error(
+            `  - ${err.message}${err.path ? ` (${err.path})` : ""}`,
+          );
+        }
+      }
+      if (result.conflicts?.length) {
+        console.error("Import blocked by conflicts:");
+        for (const conflict of result.conflicts) {
+          console.error(
+            `  - ${conflict.message}${conflict.path ? ` (${conflict.path})` : ""}`,
+          );
+        }
+      }
+      process.exit(1);
+    }
+
+    // Print summary table
+    const summary = result.summary ?? {
+      files_to_create: 0,
+      files_to_overwrite: 0,
+      files_unchanged: 0,
+      total_files: 0,
+    };
+    console.log("Preflight analysis:");
+    console.log(`  Files to create:    ${summary.files_to_create}`);
+    console.log(`  Files to overwrite: ${summary.files_to_overwrite}`);
+    console.log(`  Files unchanged:    ${summary.files_unchanged}`);
+    console.log(`  Total:              ${summary.total_files}`);
+    console.log("");
+
+    const conflicts = result.conflicts ?? [];
+    console.log(
+      `Conflicts: ${conflicts.length > 0 ? conflicts.map((c) => c.message).join(", ") : "none"}`,
+    );
+
+    // List individual files with their action
+    if (result.files && result.files.length > 0) {
+      console.log("");
+      console.log("Files:");
+      for (const file of result.files) {
+        console.log(`  [${file.action}] ${file.path}`);
+      }
+    }
+
+    return;
+  }
+
+  // Step 3 — Version rollback (if --version set)
+  if (opts.version) {
+    console.log(
+      `Rolling back to version ${opts.version} before restoring data...`,
+    );
+
+    try {
+      await rollbackPlatformAssistant(token, orgId, opts.version);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("401") || msg.includes("403")) {
+        console.error("Authentication failed. Run 'vellum login' to refresh.");
+        process.exit(1);
+      }
+      console.error(`Error: Rollback failed — ${msg}`);
+      process.exit(1);
+    }
+
+    console.log(
+      `Rolled back to ${opts.version}. Proceeding with data restore...`,
+    );
+  }
+
+  // Step 4 — Data import
+  console.log("Importing backup data...");
+
+  let importResult: { statusCode: number; body: Record<string, unknown> };
+  try {
+    importResult = await platformImportBundle(
+      new Uint8Array(bundleData),
+      token,
+      orgId,
+    );
+  } catch (err) {
+    if (err instanceof Error && err.name === "TimeoutError") {
+      console.error("Error: Import request timed out after 2 minutes.");
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  if (importResult.statusCode === 401 || importResult.statusCode === 403) {
+    console.error("Authentication failed. Run 'vellum login' to refresh.");
+    process.exit(1);
+  }
+
+  if (importResult.statusCode === 404) {
+    console.error(
+      "No managed assistant found. Ensure your assistant is running.",
+    );
+    process.exit(1);
+  }
+
+  if (importResult.statusCode === 409) {
+    console.error(
+      "Multiple assistants found. This is a platform configuration issue.",
+    );
+    process.exit(1);
+  }
+
+  if (
+    importResult.statusCode === 502 ||
+    importResult.statusCode === 503 ||
+    importResult.statusCode === 504
+  ) {
+    console.error(`Assistant is unreachable. Try 'vellum wake ${name}' first.`);
+    process.exit(1);
+  }
+
+  if (importResult.statusCode < 200 || importResult.statusCode >= 300) {
+    console.error(`Error: Import failed (${importResult.statusCode})`);
+    process.exit(1);
+  }
+
+  const result = importResult.body as unknown as ImportResponse;
+
+  if (!result.success) {
+    console.error(
+      `Error: Import failed — ${result.message ?? result.reason ?? "unknown reason"}`,
+    );
+    for (const err of result.errors ?? []) {
+      console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
+    }
+    process.exit(1);
+  }
+
+  // Print import report
+  const summary = result.summary ?? {
+    total_files: 0,
+    files_created: 0,
+    files_overwritten: 0,
+    files_skipped: 0,
+    backups_created: 0,
+  };
+  console.log("✅ Restore complete.");
+  console.log(`  Files created:     ${summary.files_created}`);
+  console.log(`  Files overwritten: ${summary.files_overwritten}`);
+  console.log(`  Files skipped:     ${summary.files_skipped}`);
+  console.log(`  Backups created:   ${summary.backups_created}`);
+
+  // Print warnings if any
+  const warnings = result.warnings ?? [];
+  if (warnings.length > 0) {
+    console.log("");
+    console.log("Warnings:");
+    for (const warning of warnings) {
+      console.log(`  ⚠️  ${warning}`);
+    }
+  }
+}
+
 export async function restore(): Promise<void> {
-  const { name, fromPath, dryRun, help } = parseArgs(process.argv);
+  const { name, fromPath, version, dryRun, help } = parseArgs(process.argv);
 
   if (help) {
     printUsage();
     process.exit(0);
   }
 
+  // --version requires --from
+  if (version && !fromPath) {
+    console.error(
+      "A backup file is required for restore. Use --from <path> to specify the .vbundle file.",
+    );
+    process.exit(1);
+  }
+
+  // --dry-run is not supported with --version
+  if (version && dryRun) {
+    console.error(
+      "Dry-run is not supported with --version. Use `vellum restore --from <path> --dry-run` for data-only preflight.",
+    );
+    process.exit(1);
+  }
+
   if (!name || !fromPath) {
     console.error("Error: Both <name> and --from <path> are required.");
     console.error("");
@@ -160,8 +469,24 @@ export async function restore(): Promise<void> {
   const sizeMB = (bundleData.byteLength / (1024 * 1024)).toFixed(2);
   console.log(`Reading ${fromPath} (${sizeMB} MB)...`);
 
-  // Obtain auth token
-  const accessToken = await getAccessToken(
+  // Detect topology and route platform assistants through Django import
+  const cloud =
+    entry.cloud || (entry.project ? "gcp" : entry.sshUser ? "custom" : "local");
+  if (cloud === "vellum") {
+    await restorePlatform(entry, name, bundleData, { version, dryRun });
+    return;
+  }
+
+  if (version && cloud !== "docker") {
+    console.error(
+      "Restore with --version is only supported for Docker and managed assistants.",
+    );
+    process.exit(1);
+  }
+
+  // Obtain auth token (acquired before dry-run or before data import;
+  // re-acquired after version rollback since containers restart).
+  let accessToken = await getAccessToken(
     entry.runtimeUrl,
     entry.assistantId,
     name,
@@ -215,13 +540,17 @@ export async function restore(): Promise<void> {
       if (result.validation?.errors?.length) {
         console.error("Import blocked by validation errors:");
         for (const err of result.validation.errors) {
-          console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
+          console.error(
+            `  - ${err.message}${err.path ? ` (${err.path})` : ""}`,
+          );
         }
       }
       if (result.conflicts?.length) {
         console.error("Import blocked by conflicts:");
         for (const conflict of result.conflicts) {
-          console.error(`  - ${conflict.message}${conflict.path ? ` (${conflict.path})` : ""}`);
+          console.error(
+            `  - ${conflict.message}${conflict.path ? ` (${conflict.path})` : ""}`,
+          );
         }
       }
       process.exit(1);
@@ -255,8 +584,22 @@ export async function restore(): Promise<void> {
       }
     }
   } else {
-    // Full import
-    console.log("Importing backup...\n");
+    // Version rollback (when --version is specified)
+    if (version) {
+      console.log(`Rolling back to version ${version}...`);
+      await performDockerRollback(entry, { targetVersion: version });
+      console.log("");
+
+      // Re-acquire auth token since containers were restarted during rollback
+      accessToken = await getAccessToken(
+        entry.runtimeUrl,
+        entry.assistantId,
+        name,
+      );
+    }
+
+    // Data import
+    console.log("Importing backup data...\n");
 
     let response: Response;
     try {