@vellumai/cli 0.4.55 → 0.4.57

package/src/commands/upgrade.ts

@@ -0,0 +1,366 @@
+import cliPkg from "../../package.json";
+
+import {
+  findAssistantByName,
+  getActiveAssistant,
+  loadAllAssistants,
+} from "../lib/assistant-config";
+import type { AssistantEntry } from "../lib/assistant-config";
+import {
+  DOCKERHUB_IMAGES,
+  DOCKER_READY_TIMEOUT_MS,
+  GATEWAY_INTERNAL_PORT,
+  dockerResourceNames,
+  startContainers,
+  stopContainers,
+} from "../lib/docker";
+import type { ServiceName } from "../lib/docker";
+import {
+  fetchOrganizationId,
+  getPlatformUrl,
+  readPlatformToken,
+} from "../lib/platform-client";
+import { exec, execOutput } from "../lib/step-runner";
+
+interface UpgradeArgs {
+  name: string | null;
+  version: string | null;
+}
+
+function parseArgs(): UpgradeArgs {
+  const args = process.argv.slice(3);
+  let name: string | null = null;
+  let version: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum upgrade [<name>] [options]");
+      console.log("");
+      console.log("Upgrade an assistant to the latest version.");
+      console.log("");
+      console.log("Arguments:");
+      console.log(
+        "  <name>               Name of the assistant to upgrade (default: active or only assistant)",
+      );
+      console.log("");
+      console.log("Options:");
+      console.log(
+        "  --version <version>  Target version to upgrade to (default: latest)",
+      );
+      console.log("");
+      console.log("Examples:");
+      console.log(
+        "  vellum upgrade                              # Upgrade the active assistant to the latest version",
+      );
+      console.log(
+        "  vellum upgrade my-assistant                  # Upgrade a specific assistant by name",
+      );
+      console.log(
+        "  vellum upgrade my-assistant --version v1.2.3 # Upgrade to a specific version",
+      );
+      process.exit(0);
+    } else if (arg === "--version") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --version requires a value");
+        process.exit(1);
+      }
+      version = next;
+      i++;
+    } else if (!arg.startsWith("-")) {
+      name = arg;
+    } else {
+      console.error(`Error: Unknown option '${arg}'.`);
+      process.exit(1);
+    }
+  }
+
+  return { name, version };
+}
+
+function resolveCloud(entry: AssistantEntry): string {
+  if (entry.cloud) {
+    return entry.cloud;
+  }
+  if (entry.project) {
+    return "gcp";
+  }
+  if (entry.sshUser) {
+    return "custom";
+  }
+  return "local";
+}
+
+/**
+ * Resolve which assistant to target for the upgrade command. Priority:
+ * 1. Explicit name argument
+ * 2. Active assistant set via `vellum use`
+ * 3. Sole assistant (when exactly one exists)
+ */
+function resolveTargetAssistant(nameArg: string | null): AssistantEntry {
+  if (nameArg) {
+    const entry = findAssistantByName(nameArg);
+    if (!entry) {
+      console.error(`No assistant found with name '${nameArg}'.`);
+      process.exit(1);
+    }
+    return entry;
+  }
+
+  const active = getActiveAssistant();
+  if (active) {
+    const entry = findAssistantByName(active);
+    if (entry) return entry;
+  }
+
+  const all = loadAllAssistants();
+  if (all.length === 1) return all[0];
+
+  if (all.length === 0) {
+    console.error("No assistants found. Run 'vellum hatch' first.");
+  } else {
+    console.error(
+      "Multiple assistants found. Specify a name or set an active assistant with 'vellum use <name>'.",
+    );
+  }
+  process.exit(1);
+}
+
+/**
+ * Capture environment variables from a running Docker container so they
+ * can be replayed onto the replacement container after upgrade.
+ */
+async function captureContainerEnv(
+  containerName: string,
+): Promise<Record<string, string>> {
+  const captured: Record<string, string> = {};
+  try {
+    const raw = await execOutput("docker", [
+      "inspect",
+      "--format",
+      "{{json .Config.Env}}",
+      containerName,
+    ]);
+    const entries = JSON.parse(raw) as string[];
+    for (const entry of entries) {
+      const eqIdx = entry.indexOf("=");
+      if (eqIdx > 0) {
+        captured[entry.slice(0, eqIdx)] = entry.slice(eqIdx + 1);
+      }
+    }
+  } catch {
+    // Container may not exist or not be inspectable
+  }
+  return captured;
+}
+
+/**
+ * Poll the gateway `/readyz` endpoint until it returns 200 or the timeout
+ * elapses. Returns whether the assistant became ready.
+ */
+async function waitForReady(runtimeUrl: string): Promise<boolean> {
+  const readyUrl = `${runtimeUrl}/readyz`;
+  const start = Date.now();
+
+  while (Date.now() - start < DOCKER_READY_TIMEOUT_MS) {
+    try {
+      const resp = await fetch(readyUrl, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (resp.ok) {
+        const elapsedSec = ((Date.now() - start) / 1000).toFixed(1);
+        console.log(`Assistant ready after ${elapsedSec}s`);
+        return true;
+      }
+      let detail = "";
+      try {
+        const body = await resp.text();
+        const json = JSON.parse(body);
+        const parts = [json.status];
+        if (json.upstream != null) parts.push(`upstream=${json.upstream}`);
+        detail = ` — ${parts.join(", ")}`;
+      } catch {
+        // ignore parse errors
+      }
+      console.log(`Readiness check: ${resp.status}${detail} (retrying...)`);
+    } catch {
+      // Connection refused / timeout — not up yet
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+
+  return false;
+}
+
+async function upgradeDocker(
+  entry: AssistantEntry,
+  version: string | null,
+): Promise<void> {
+  const instanceName = entry.assistantId;
+  const res = dockerResourceNames(instanceName);
+
+  const versionTag =
+    version ?? (cliPkg.version ? `v${cliPkg.version}` : "latest");
+  const imageTags: Record<ServiceName, string> = {
+    assistant: `${DOCKERHUB_IMAGES.assistant}:${versionTag}`,
+    "credential-executor": `${DOCKERHUB_IMAGES["credential-executor"]}:${versionTag}`,
+    gateway: `${DOCKERHUB_IMAGES.gateway}:${versionTag}`,
+  };
+
+  console.log(
+    `🔄 Upgrading Docker assistant '${instanceName}' to ${versionTag}...\n`,
+  );
+
+  console.log("📦 Pulling new Docker images...");
+  await exec("docker", ["pull", imageTags.assistant]);
+  await exec("docker", ["pull", imageTags.gateway]);
+  await exec("docker", ["pull", imageTags["credential-executor"]]);
+  console.log("✅ Docker images pulled\n");
+
+  console.log("💾 Capturing existing container environment...");
+  const capturedEnv = await captureContainerEnv(res.assistantContainer);
+  console.log(
+    `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
+  );
+
+  console.log("🛑 Stopping existing containers...");
+  await stopContainers(res);
+  console.log("✅ Containers stopped\n");
+
+  // Parse gateway port from entry's runtimeUrl, fall back to default
+  let gatewayPort = GATEWAY_INTERNAL_PORT;
+  try {
+    const parsed = new URL(entry.runtimeUrl);
+    const port = parseInt(parsed.port, 10);
+    if (!isNaN(port)) {
+      gatewayPort = port;
+    }
+  } catch {
+    // use default
+  }
+
+  // Build the set of extra env vars to replay on the new assistant container.
+  // Captured env vars serve as the base; keys already managed by
+  // serviceDockerRunArgs are excluded to avoid duplicates.
+  const envKeysSetByRunArgs = new Set([
+    "VELLUM_ASSISTANT_NAME",
+    "RUNTIME_HTTP_HOST",
+    "PATH",
+  ]);
+  // Only exclude keys that serviceDockerRunArgs will actually set
+  for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
+    if (process.env[envVar]) {
+      envKeysSetByRunArgs.add(envVar);
+    }
+  }
+  const extraAssistantEnv: Record<string, string> = {};
+  for (const [key, value] of Object.entries(capturedEnv)) {
+    if (!envKeysSetByRunArgs.has(key)) {
+      extraAssistantEnv[key] = value;
+    }
+  }
+
+  console.log("🚀 Starting upgraded containers...");
+  await startContainers(
+    {
+      extraAssistantEnv,
+      gatewayPort,
+      imageTags,
+      instanceName,
+      res,
+    },
+    (msg) => console.log(msg),
+  );
+  console.log("✅ Containers started\n");
+
+  console.log("Waiting for assistant to become ready...");
+  const ready = await waitForReady(entry.runtimeUrl);
+  if (ready) {
+    console.log(
+      `\n✅ Docker assistant '${instanceName}' upgraded to ${versionTag}.`,
+    );
+  } else {
+    console.log(
+      `\n⚠️  Containers are running but the assistant did not become ready within the timeout.`,
+    );
+    console.log(`   Check logs with: docker logs -f ${res.assistantContainer}`);
+  }
+}
+
+interface UpgradeApiResponse {
+  detail: string;
+  version: string | null;
+}
+
+async function upgradePlatform(
+  entry: AssistantEntry,
+  version: string | null,
+): Promise<void> {
+  console.log(
+    `🔄 Upgrading platform-hosted assistant '${entry.assistantId}'...\n`,
+  );
+
+  const token = readPlatformToken();
+  if (!token) {
+    console.error(
+      "Error: Not logged in. Run `vellum login --token <token>` first.",
+    );
+    process.exit(1);
+  }
+
+  const orgId = await fetchOrganizationId(token);
+
+  const url = `${getPlatformUrl()}/v1/assistants/upgrade/`;
+  const body: { assistant_id?: string; version?: string } = {
+    assistant_id: entry.assistantId,
+  };
+  if (version) {
+    body.version = version;
+  }
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Session-Token": token,
+      "Vellum-Organization-Id": orgId,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    console.error(
+      `Error: Platform upgrade failed (${response.status}): ${text}`,
+    );
+    process.exit(1);
+  }
+
+  const result = (await response.json()) as UpgradeApiResponse;
+  console.log(`✅ ${result.detail}`);
+  if (result.version) {
+    console.log(`   Version: ${result.version}`);
+  }
+}
+
+export async function upgrade(): Promise<void> {
+  const { name, version } = parseArgs();
+  const entry = resolveTargetAssistant(name);
+  const cloud = resolveCloud(entry);
+
+  if (cloud === "docker") {
+    await upgradeDocker(entry, version);
+    return;
+  }
+
+  if (cloud === "vellum") {
+    await upgradePlatform(entry, version);
+    return;
+  }
+
+  console.error(
+    `Error: Upgrade is not supported for '${cloud}' assistants. Only 'docker' and 'vellum' assistants can be upgraded via the CLI.`,
+  );
+  process.exit(1);
+}

package/src/commands/wake.ts

@@ -4,7 +4,8 @@ import { join } from "path";
 import { resolveTargetAssistant } from "../lib/assistant-config.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 import {
-  isWatchModeAvailable,
+  isAssistantWatchModeAvailable,
+  isGatewayWatchModeAvailable,
   startLocalDaemon,
   startGateway,
 } from "../lib/local";
@@ -24,12 +25,16 @@ export async function wake(): Promise<void> {
     console.log("");
     console.log("Options:");
     console.log(
-      "  --watch    Run assistant and gateway in watch mode (hot reload on source changes)",
+      "  --watch        Run assistant and gateway in watch mode (hot reload on source changes)",
+    );
+    console.log(
+      "  --foreground   Run assistant in foreground with logs printed to terminal",
     );
     process.exit(0);
   }
 
   const watch = args.includes("--watch");
+  const foreground = args.includes("--foreground");
   const nameArg = args.find((a) => !a.startsWith("-"));
   const entry = resolveTargetAssistant(nameArg);
 
@@ -64,7 +69,7 @@ export async function wake(): Promise<void> {
           // Watch mode requires bun --watch with .ts sources; packaged desktop
           // builds only have a compiled binary. Stopping the daemon without a
           // viable watch-mode path would leave the user with no running assistant.
-          if (!isWatchModeAvailable()) {
+          if (!isAssistantWatchModeAvailable()) {
             console.log(
               `Assistant running (pid ${pid}) — watch mode not available (no source files). Keeping existing process.`,
             );
@@ -85,7 +90,7 @@ export async function wake(): Promise<void> {
   }
 
   if (!daemonRunning) {
-    await startLocalDaemon(watch, resources);
+    await startLocalDaemon(watch, resources, { foreground });
   }
 
   // Start gateway
@@ -95,8 +100,8 @@ export async function wake(): Promise<void> {
     const { alive, pid } = isProcessAlive(gatewayPidFile);
     if (alive) {
       if (watch) {
-        // Same guard as the daemon: only restart if watch mode is viable.
-        if (!isWatchModeAvailable()) {
+        // Guard gateway restart separately: check gateway source availability.
+        if (!isGatewayWatchModeAvailable()) {
           console.log(
             `Gateway running (pid ${pid}) — watch mode not available (no source files). Keeping existing process.`,
           );
@@ -131,4 +136,18 @@ export async function wake(): Promise<void> {
   }
 
   console.log("Wake complete.");
+
+  if (foreground) {
+    console.log("Running in foreground (Ctrl+C to stop)...\n");
+    // Block forever — the daemon is running with inherited stdio so its
+    // output streams to this terminal. When the user hits Ctrl+C, SIGINT
+    // propagates to the daemon child and both exit.
+    await new Promise<void>((resolve) => {
+      process.on("SIGINT", () => {
+        console.log("\nShutting down...");
+        resolve();
+      });
+      process.on("SIGTERM", () => resolve());
+    });
+  }
 }

package/src/components/DefaultMainScreen.tsx

@@ -1943,7 +1943,7 @@ function ChatApp({
             .update(hostname() + userInfo().username)
             .digest("hex");
           const payload = JSON.stringify({
-            type: "vellum-daemon",
+            type: "vellum-assistant",
             v: 4,
             id: hostId,
             g: gatewayUrl,

package/src/index.ts

@@ -13,6 +13,7 @@ import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
 import { tunnel } from "./commands/tunnel";
+import { upgrade } from "./commands/upgrade";
 import { use } from "./commands/use";
 import { wake } from "./commands/wake";
 import {
@@ -21,6 +22,7 @@ import {
   loadLatestAssistant,
   setActiveAssistant,
 } from "./lib/assistant-config";
+import { loadGuardianToken } from "./lib/guardian-token";
 import { checkHealth } from "./lib/health-check";
 
 const commands = {
@@ -37,6 +39,7 @@ const commands = {
   sleep,
   ssh,
   tunnel,
+  upgrade,
   use,
   wake,
   whoami,
@@ -63,6 +66,7 @@ function printHelp(): void {
   console.log("  sleep    Stop the assistant process");
   console.log("  ssh      SSH into a remote assistant instance");
   console.log("  tunnel   Create a tunnel for a locally hosted assistant");
+  console.log("  upgrade  Upgrade an assistant to the latest version");
   console.log("  use      Set the active assistant for commands");
   console.log("  wake     Start the assistant and gateway");
   console.log("  whoami   Show current logged-in user");
@@ -103,7 +107,8 @@ async function tryLaunchClient(): Promise<boolean> {
   const url = entry.localUrl || entry.runtimeUrl;
   if (!url) return false;
 
-  const result = await checkHealth(url, entry.bearerToken);
+  const token = loadGuardianToken(entry.assistantId)?.accessToken;
+  const result = await checkHealth(url, token);
   if (result.status !== "healthy") return false;
 
   // Ensure the resolved assistant is active so client() can find it

package/src/lib/assistant-config.ts

@@ -3,6 +3,7 @@ import { homedir } from "os";
 import { join } from "path";
 
 import {
+  DAEMON_INTERNAL_ASSISTANT_ID,
   DEFAULT_DAEMON_PORT,
   DEFAULT_GATEWAY_PORT,
   DEFAULT_QDRANT_PORT,
@@ -49,8 +50,12 @@ export interface AssistantEntry {
   sshUser?: string;
   zone?: string;
   hatchedAt?: string;
+  /** Name of the shared volume backing BASE_DATA_DIR for containerised instances. */
+  volume?: string;
   /** Per-instance resource config. Present for local entries in multi-instance setups. */
   resources?: LocalInstanceResources;
+  /** PID of the file watcher process for docker instances hatched with --watch. */
+  watcherPid?: number;
   [key: string]: unknown;
 }
 
@@ -152,7 +157,9 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       "share",
       "vellum",
       "assistants",
-      typeof raw.assistantId === "string" ? raw.assistantId : "default",
+      typeof raw.assistantId === "string"
+        ? raw.assistantId
+        : DAEMON_INTERNAL_ASSISTANT_ID,
     );
     raw.resources = {
       instanceDir,
@@ -172,7 +179,9 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
         "share",
         "vellum",
         "assistants",
-        typeof raw.assistantId === "string" ? raw.assistantId : "default",
+        typeof raw.assistantId === "string"
+          ? raw.assistantId
+          : DAEMON_INTERNAL_ASSISTANT_ID,
       );
       mutated = true;
     }

package/src/lib/aws.ts

@@ -1,4 +1,3 @@
-import { randomBytes } from "crypto";
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "fs";
 import { homedir, tmpdir, userInfo } from "os";
 import { join } from "path";
@@ -9,7 +8,8 @@ import { saveAssistantEntry, setActiveAssistant } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { GATEWAY_PORT } from "./constants";
 import type { Species } from "./constants";
-import { generateRandomSuffix } from "./random-name";
+import { leaseGuardianToken } from "./guardian-token";
+import { generateInstanceName } from "./random-name";
 import { exec, execOutput } from "./step-runner";
 
 const KEY_PAIR_NAME = "vellum-assistant";
@@ -370,28 +370,6 @@ async function pollAwsInstance(
   }
 }
 
-async function fetchRemoteBearerToken(
-  ip: string,
-  keyPath: string,
-): Promise<string | null> {
-  try {
-    const remoteCmd =
-      'cat ~/.vellum.lock.json 2>/dev/null || cat ~/.vellum.lockfile.json 2>/dev/null || echo "{}"';
-    const output = await awsSshExec(ip, keyPath, remoteCmd);
-    const data = JSON.parse(output.trim());
-    const assistants = data.assistants;
-    if (Array.isArray(assistants) && assistants.length > 0) {
-      const token = assistants[0].bearerToken;
-      if (typeof token === "string" && token) {
-        return token;
-      }
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
 export async function hatchAws(
   species: Species,
   detached: boolean,
@@ -405,12 +383,7 @@ export async function hatchAws(
       (await getActiveRegion().catch(() => AWS_DEFAULT_REGION));
     let instanceName: string;
 
-    if (name) {
-      instanceName = name;
-    } else {
-      const suffix = generateRandomSuffix();
-      instanceName = `${species}-${suffix}`;
-    }
+    instanceName = generateInstanceName(species, name);
 
     console.log(`\u{1F95A} Creating new assistant: ${instanceName}`);
     console.log(`   Species: ${species}`);
@@ -431,13 +404,11 @@ export async function hatchAws(
         console.log(
           `\u26a0\ufe0f  Instance name ${instanceName} already exists, generating a new name...`,
         );
-        const suffix = generateRandomSuffix();
-        instanceName = `${species}-${suffix}`;
+        instanceName = generateInstanceName(species);
       }
     }
 
     const sshUser = userInfo().username;
-    const bearerToken = randomBytes(32).toString("hex");
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
     const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
     if (!anthropicApiKey) {
@@ -465,7 +436,6 @@ export async function hatchAws(
 
     const startupScript = await buildStartupScript(
       species,
-      bearerToken,
       sshUser,
       anthropicApiKey,
       instanceName,
@@ -558,10 +528,12 @@ export async function hatchAws(
           process.exit(1);
         }
 
-        const remoteBearerToken = await fetchRemoteBearerToken(ip, keyPath);
-        if (remoteBearerToken) {
-          awsEntry.bearerToken = remoteBearerToken;
-          saveAssistantEntry(awsEntry);
+        try {
+          await leaseGuardianToken(runtimeUrl, instanceName);
+        } catch (err) {
+          console.warn(
+            `\u26a0\ufe0f  Could not lease guardian token: ${err instanceof Error ? err.message : err}`,
+          );
         }
       } else {
         console.log(

package/src/lib/constants.ts

@@ -1,3 +1,10 @@
+/**
+ * Canonical internal assistant ID used as the default/fallback across the CLI
+ * and daemon. Mirrors `DAEMON_INTERNAL_ASSISTANT_ID` from
+ * `assistant/src/runtime/assistant-scope.ts`.
+ */
+export const DAEMON_INTERNAL_ASSISTANT_ID = "self" as const;
+
 export const FIREWALL_TAG = "vellum-assistant";
 export const GATEWAY_PORT = process.env.GATEWAY_PORT
   ? Number(process.env.GATEWAY_PORT)