@vellumai/cli 0.7.1 → 0.7.2

package/src/commands/client.ts

@@ -12,6 +12,10 @@ import {
 } from "../lib/constants";
 import { loadGuardianToken } from "../lib/guardian-token";
 import { getLocalLanIPv4 } from "../lib/local";
+import {
+  fetchOrganizationId,
+  readPlatformToken,
+} from "../lib/platform-client";
 import { tuiLog } from "../lib/tui-log";
 
 const ANSI = {
@@ -26,6 +30,11 @@ interface ParsedArgs {
   runtimeUrl: string;
   assistantId: string;
   species: Species;
+  /** "vellum" for platform-hosted assistants, undefined for local. */
+  cloud?: string;
+  /** Platform session token (X-Session-Token), set when cloud === "vellum". */
+  platformToken?: string;
+  /** Guardian JWT (Authorization: Bearer), set for local assistants. */
   bearerToken?: string;
   project?: string;
   zone?: string;
@@ -89,10 +98,17 @@ function parseArgs(): ParsedArgs {
 
   let runtimeUrl = entry?.localUrl || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
   let assistantId = entry?.assistantId || DAEMON_INTERNAL_ASSISTANT_ID;
-  const bearerToken =
-    loadGuardianToken(entry?.assistantId ?? "")?.accessToken ?? undefined;
+  const cloud = entry?.cloud;
   const species: Species = (entry?.species as Species) ?? "vellum";
 
+  // Platform-hosted assistants use a session token; local assistants use a guardian JWT.
+  const platformToken =
+    cloud === "vellum" ? (readPlatformToken() ?? undefined) : undefined;
+  const bearerToken =
+    cloud === "vellum"
+      ? undefined
+      : (loadGuardianToken(entry?.assistantId ?? "")?.accessToken ?? undefined);
+
   for (let i = 0; i < flagArgs.length; i++) {
     const flag = flagArgs[i];
     if ((flag === "--url" || flag === "-u") && flagArgs[i + 1]) {
@@ -109,6 +125,8 @@ function parseArgs(): ParsedArgs {
     runtimeUrl: maybeSwapToLocalhost(runtimeUrl.replace(/\/+$/, "")),
     assistantId,
     species,
+    cloud,
+    platformToken,
     bearerToken,
     project: entry?.project,
     zone: entry?.zone,
@@ -181,11 +199,34 @@ ${ANSI.bold}EXAMPLES:${ANSI.reset}
 }
 
 export async function client(): Promise<void> {
-  const { runtimeUrl, assistantId, species, bearerToken, project, zone } =
-    parseArgs();
+  const {
+    runtimeUrl,
+    assistantId,
+    species,
+    cloud,
+    platformToken,
+    bearerToken,
+    project,
+    zone,
+  } = parseArgs();
 
   tuiLog.init();
-  tuiLog.info("session start", { runtimeUrl, assistantId, species });
+  tuiLog.info("session start", { runtimeUrl, assistantId, species, cloud });
+
+  // Build pre-constructed auth headers so all fetch sites share a single object.
+  let auth: Record<string, string> | undefined;
+  if (cloud === "vellum" && platformToken) {
+    const orgId = await fetchOrganizationId(platformToken).catch((err) => {
+      tuiLog.warn("failed to fetch organization id", { err: String(err) });
+      return undefined;
+    });
+    auth = {
+      "X-Session-Token": platformToken,
+      ...(orgId ? { "Vellum-Organization-Id": orgId } : {}),
+    };
+  } else if (bearerToken) {
+    auth = { Authorization: `Bearer ${bearerToken}` };
+  }
 
   const { renderChatApp } = await import("../components/DefaultMainScreen");
 
@@ -203,6 +244,6 @@ export async function client(): Promise<void> {
       console.log(`${ANSI.dim}Disconnected.${ANSI.reset}`);
       process.exit(0);
     },
-    { bearerToken, project, zone },
+    { auth, project, zone },
   );
 }

package/src/commands/events.ts

@@ -139,6 +139,9 @@ export async function events(): Promise<void> {
     query,
     headers: getClientRegistrationHeaders(),
   })) {
+    if (!event.message) {
+      continue;
+    }
     if (jsonOutput) {
       console.log(JSON.stringify(event));
     } else {

package/src/commands/exec.ts

@@ -156,10 +156,19 @@ export async function exec(): Promise<void> {
   const cloud = resolveCloud(entry);
 
   if (cloud === "local") {
-    console.error(
-      "Cannot exec into a local assistant — it runs directly on this machine.",
-    );
-    process.exit(1);
+    const child = spawn(command[0], command.slice(1), { stdio: "inherit" });
+    await new Promise<void>((resolve) => {
+      child.on("close", (code) => {
+        process.exitCode = code ?? 0;
+        resolve();
+      });
+      child.on("error", (err) => {
+        console.error(`Error: ${err.message}`);
+        process.exitCode = 1;
+        resolve();
+      });
+    });
+    return;
   }
 
   if (cloud === "apple-container") {

package/src/commands/hatch.ts

@@ -32,7 +32,7 @@ export type { PollResult, WatchHatchingResult } from "../lib/gcp";
 const INSTALL_SCRIPT_REMOTE_PATH = "/tmp/vellum-install.sh";
 
 const HATCH_TIMEOUT_MS: Record<Species, number> = {
-  vellum: 2 * 60 * 1000,
+  vellum: 5 * 60 * 1000,
   openclaw: 10 * 60 * 1000,
 };
 const DEFAULT_SPECIES: Species = "vellum";

package/src/commands/restore.ts

@@ -179,7 +179,13 @@ async function restorePlatform(
     process.exit(1);
   }
 
-  // Step 1.5 — Upload to GCS via signed URL
+  // Step 1.5 — Upload to GCS via signed URL.
+  // We deliberately omit min/max runtime version here: restore uploads an
+  // arbitrary .vbundle from disk (often produced by a different runtime
+  // than the one we'd query right now), and the bundle's own manifest is
+  // the authority on its compatibility band. The platform skips the
+  // version gate when these fields are absent and re-derives compat from
+  // the manifest when it processes the import.
   const { url: uploadUrl, bundleKey } = await platformRequestSignedUrl(
     { operation: "upload" },
     token,

package/src/commands/setup.ts

@@ -1,43 +1,6 @@
 import { createInterface } from "readline";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { dirname, join } from "path";
 
-function getVellumDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
-
-function getEnvFilePath(): string {
-  return join(getVellumDir(), ".env");
-}
-
-function readEnvFile(): Record<string, string> {
-  const envPath = getEnvFilePath();
-  const vars: Record<string, string> = {};
-  if (!existsSync(envPath)) return vars;
-
-  const content = readFileSync(envPath, "utf-8");
-  for (const line of content.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-    const eqIdx = trimmed.indexOf("=");
-    if (eqIdx === -1) continue;
-    const key = trimmed.slice(0, eqIdx).trim();
-    const value = trimmed.slice(eqIdx + 1).trim();
-    vars[key] = value;
-  }
-  return vars;
-}
-
-function writeEnvFile(vars: Record<string, string>): void {
-  const envPath = getEnvFilePath();
-  const dir = dirname(envPath);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-
-  const lines = Object.entries(vars).map(([k, v]) => `${k}=${v}`);
-  writeFileSync(envPath, lines.join("\n") + "\n", { mode: 0o600 });
-}
+import { resolveAssistant } from "../lib/assistant-config.js";
 
 async function promptMasked(prompt: string): Promise<string> {
   return new Promise((resolve) => {
@@ -46,7 +9,6 @@ async function promptMasked(prompt: string): Promise<string> {
       output: process.stdout,
     });
 
-    // Disable echoing by writing the prompt manually and intercepting keystrokes
     process.stdout.write(prompt);
 
     const stdin = process.stdin;
@@ -60,7 +22,6 @@ async function promptMasked(prompt: string): Promise<string> {
       const char = key.toString("utf-8");
 
       if (char === "\r" || char === "\n") {
-        // Enter pressed
         stdin.removeListener("data", onData);
         if (stdin.isTTY) {
           stdin.setRawMode(wasRaw ?? false);
@@ -69,11 +30,9 @@ async function promptMasked(prompt: string): Promise<string> {
         rl.close();
         resolve(input);
       } else if (char === "\u0003") {
-        // Ctrl+C
         process.stdout.write("\n");
         process.exit(1);
       } else if (char === "\u007F" || char === "\b") {
-        // Backspace
         if (input.length > 0) {
           input = input.slice(0, -1);
           process.stdout.write("\b \b");
@@ -111,39 +70,23 @@ export async function setup(): Promise<void> {
     console.log("");
     console.log("Interactive wizard to configure API keys.");
     console.log(
-      "Keys are validated against their APIs and saved to <BASE_DATA_DIR>/.vellum/.env.",
+      "Injects secrets into your running assistant via the gateway API.",
     );
     process.exit(0);
   }
 
-  console.log("Vellum Setup");
-  console.log("============\n");
-
-  const existingVars = readEnvFile();
-  const hasExistingKey = !!existingVars.ANTHROPIC_API_KEY;
+  const entry = resolveAssistant();
+  if (!entry) {
+    console.error(
+      "Error: No active assistant found. Run `vellum hatch` first.",
+    );
+    process.exit(1);
+  }
 
-  if (hasExistingKey) {
-    const masked =
-      existingVars.ANTHROPIC_API_KEY.slice(0, 7) +
-      "..." +
-      existingVars.ANTHROPIC_API_KEY.slice(-4);
-    console.log(`Anthropic API key is already configured (${masked}).`);
+  const gatewayUrl = entry.localUrl ?? entry.runtimeUrl;
 
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    const answer = await new Promise<string>((resolve) => {
-      rl.question("Overwrite? [y/N] ", resolve);
-    });
-    rl.close();
-
-    if (answer.trim().toLowerCase() !== "y") {
-      console.log("\nSetup complete. No changes made.");
-      return;
-    }
-    console.log("");
-  }
+  console.log("Vellum Setup");
+  console.log("============\n");
 
   const apiKey = await promptMasked(
     "Enter your Anthropic API key (sk-ant-...): ",
@@ -164,9 +107,31 @@ export async function setup(): Promise<void> {
     process.exit(1);
   }
 
-  existingVars.ANTHROPIC_API_KEY = apiKey.trim();
-  writeEnvFile(existingVars);
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+  if (entry.bearerToken) {
+    headers["Authorization"] = `Bearer ${entry.bearerToken}`;
+  }
+
+  const response = await fetch(`${gatewayUrl}/v1/secrets`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      type: "credential",
+      name: "ANTHROPIC_API_KEY",
+      value: apiKey.trim(),
+    }),
+    signal: AbortSignal.timeout(10_000),
+  });
+
+  if (!response.ok) {
+    console.error(
+      `Error: Failed to store API key in assistant (${response.status}).`,
+    );
+    process.exit(1);
+  }
 
-  console.log(`\nAPI key saved to ${getEnvFilePath()}`);
-  console.log("Setup complete.");
+  console.log("\nAPI key saved to assistant. Setup complete.");
 }

package/src/commands/teleport.ts

@@ -21,6 +21,7 @@ import {
   platformImportBundleFromGcs,
   platformImportPreflightFromGcs,
   platformRequestSignedUrl,
+  VersionMismatchError,
   ensureSelfHostedLocalRegistration,
   readGatewayCredential,
   reprovisionAssistantApiKey,
@@ -30,6 +31,7 @@ import {
 } from "../lib/platform-client.js";
 import {
   localRuntimeExportToGcs,
+  localRuntimeIdentity,
   localRuntimeImportFromGcs,
   localRuntimePollJobStatus,
   MigrationInProgressError,
@@ -254,13 +256,17 @@ async function getAccessToken(
 
 /**
  * Detect a 401 Unauthorized raised by `localRuntimeExportToGcs` /
- * `localRuntimeImportFromGcs`. Both throw Error with a message of the form
- * `"Local runtime <op> failed (401): ..."` when the gateway rejects the
- * cached guardian token.
+ * `localRuntimeImportFromGcs` / `localRuntimeIdentity`. They throw Error
+ * with a message of the form `"Local runtime <op> failed (401): ..."` or
+ * `"Failed to fetch runtime identity: 401 ..."` when the gateway rejects
+ * the cached guardian token.
  */
 function isRuntime401(err: unknown): boolean {
   const msg = err instanceof Error ? err.message : String(err);
-  return /Local runtime [^(]*failed \(401\)/.test(msg);
+  return (
+    /Local runtime [^(]*failed \(401\)/.test(msg) ||
+    /Failed to fetch runtime identity: 401\b/.test(msg)
+  );
 }
 
 /**
@@ -367,13 +373,40 @@ async function exportFromAssistant(
   }
 
   if (cloud === "local" || cloud === "docker") {
+    // Ask the source runtime which version it's running before requesting
+    // the signed upload URL. The bundle is produced by the daemon (not the
+    // CLI), so the daemon's version is what defines the bundle's
+    // `min_runtime_version`. Stamping with `cliPkg.version` instead would
+    // record an inaccurate compatibility band whenever the CLI/daemon have
+    // drifted (a normal case in real usage — `vellum upgrade` swaps the
+    // daemon, the CLI is updated separately).
+    let sourceRuntimeVersion: string;
+    try {
+      const identity = await callRuntimeWithAuthRetry(
+        entry.runtimeUrl,
+        entry.assistantId,
+        async (token) => localRuntimeIdentity(entry, token),
+      );
+      sourceRuntimeVersion = identity.version;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `Error: Could not fetch runtime identity from '${entry.assistantId}': ${msg}`,
+      );
+      process.exit(1);
+    }
+
     // Request a signed upload URL from the platform instance that will
     // eventually own the bundle (i.e. the one the importer will read from).
     // Passing the target's runtime URL here keeps upload and download on
     // the same platform — otherwise a non-default/stale platform URL would
     // cause the import to look at an empty object.
     const { url: uploadUrl, bundleKey } = await platformRequestSignedUrl(
-      { operation: "upload" },
+      {
+        operation: "upload",
+        minRuntimeVersion: sourceRuntimeVersion,
+        maxRuntimeVersion: null,
+      },
       platformToken,
       bundlePlatformUrl,
     );
@@ -440,6 +473,24 @@ async function exportFromAssistant(
   }
 
   if (cloud === "vellum") {
+    // Ask the managed runtime which version it's running so the signed-URL
+    // request records the bundle's actual `min_runtime_version`. The
+    // platform-managed runtime is the exporter; the CLI version is
+    // unrelated. Routed via the wildcard proxy with platform-token auth
+    // (resolveRuntimeUrl + migrationRequestHeaders inside
+    // localRuntimeIdentity).
+    let sourceRuntimeVersion: string;
+    try {
+      const identity = await localRuntimeIdentity(entry, platformToken);
+      sourceRuntimeVersion = identity.version;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `Error: Could not fetch runtime identity from '${entry.assistantId}': ${msg}`,
+      );
+      process.exit(1);
+    }
+
     // 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
@@ -449,7 +500,11 @@ async function exportFromAssistant(
     // 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" },
+      {
+        operation: "upload",
+        minRuntimeVersion: sourceRuntimeVersion,
+        maxRuntimeVersion: null,
+      },
       platformToken,
       bundlePlatformUrl,
     );
@@ -659,11 +714,56 @@ async function importToAssistant(
     // never touches the bytes. The URL must target the same platform the
     // bundle was uploaded to; otherwise the object won't exist on this
     // platform's GCS bucket.
-    const { url: bundleUrl } = await platformRequestSignedUrl(
-      { operation: "download", bundleKey },
-      platformToken,
-      bundlePlatformUrl,
-    );
+    //
+    // The platform's vbundle version gate compares the **target runtime's**
+    // version against the bundle's compatibility range. The CLI and the
+    // target assistant's daemon can diverge (assistants upgrade
+    // independently), so we MUST query the target runtime's `/v1/identity`
+    // for its version rather than sending `cliPkg.version`. Sending the CLI
+    // version here would falsely 422 a valid import (or pass a bundle the
+    // target can't actually load) whenever the two drift apart.
+    let targetRuntimeVersion: string;
+    try {
+      const identity = await callRuntimeWithAuthRetry(
+        entry.runtimeUrl,
+        entry.assistantId,
+        (token) => localRuntimeIdentity(entry, token),
+      );
+      targetRuntimeVersion = identity.version;
+    } catch (err) {
+      // Surface and abort — silently falling back to `cliPkg.version` would
+      // re-introduce the bug this code is fixing. If the runtime is
+      // unreachable, the import would fail downstream anyway.
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `Error: Could not read target runtime version from '${entry.assistantId}': ${msg}`,
+      );
+      console.error(`Try: vellum wake ${entry.assistantId}`);
+      process.exit(1);
+    }
+
+    let bundleUrl: string;
+    try {
+      const result = await platformRequestSignedUrl(
+        {
+          operation: "download",
+          bundleKey,
+          targetRuntimeVersion,
+        },
+        platformToken,
+        bundlePlatformUrl,
+      );
+      bundleUrl = result.url;
+    } catch (err) {
+      if (err instanceof VersionMismatchError) {
+        // 422 version_mismatch is terminal — the bundle's runtime range and
+        // the target runtime's version don't overlap. Surface the
+        // platform-formatted message and exit; do NOT retry.
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      throw err;
+    }
 
     console.log("Importing data...");
 

package/src/commands/upgrade.ts

@@ -40,6 +40,7 @@ import {
   buildStartingEvent,
   buildUpgradeCommitMessage,
   captureContainerEnv,
+  captureUpgradeFailureLogs,
   commitWorkspaceViaGateway,
   CONTAINER_ENV_EXCLUDE_KEYS,
   rollbackMigrations,
@@ -511,6 +512,11 @@ async function upgradeDocker(
   } else {
     console.error(`\n❌ Containers failed to become ready within the timeout.`);
 
+    const logDir = await captureUpgradeFailureLogs(res, `${instanceName}-upgrade-failure`);
+    if (logDir) {
+      console.log(`📋 Container logs saved to: ${logDir}`);
+    }
+
     if (previousImageRefs) {
       await broadcastUpgradeEvent(
         entry.runtimeUrl,

package/src/commands/wake.ts

@@ -195,22 +195,11 @@ export async function wake(): Promise<void> {
   }
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
-  // Scope BASE_DATA_DIR to the woken instance so ngrok reads the correct
-  // instance config, then restore on any exit path.
-  const prevBaseDataDir = process.env.BASE_DATA_DIR;
-  process.env.BASE_DATA_DIR = resources.instanceDir;
-  try {
-    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-    if (ngrokChild?.pid) {
-      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-    }
-  } finally {
-    if (prevBaseDataDir !== undefined) {
-      process.env.BASE_DATA_DIR = prevBaseDataDir;
-    } else {
-      delete process.env.BASE_DATA_DIR;
-    }
+  const workspaceDir = join(resources.instanceDir, ".vellum", "workspace");
+  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort, workspaceDir);
+  if (ngrokChild?.pid) {
+    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
   }
 
   console.log("Wake complete.");