@vellumai/cli 0.5.3 → 0.5.5

package/src/commands/upgrade.ts

@@ -1,9 +1,12 @@
+import { randomBytes } from "crypto";
+
 import cliPkg from "../../package.json";
 
 import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  saveAssistantEntry,
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import {
@@ -12,6 +15,8 @@ import {
   DOCKER_READY_TIMEOUT_MS,
   GATEWAY_INTERNAL_PORT,
   dockerResourceNames,
+  migrateCesSecurityFiles,
+  migrateGatewaySecurityFiles,
   startContainers,
   stopContainers,
 } from "../lib/docker";
@@ -257,10 +262,18 @@ async function upgradeDocker(
     // use default
   }
 
+  // Extract CES_SERVICE_TOKEN from the captured env so it can be passed via
+  // the dedicated cesServiceToken parameter (which propagates it to all three
+  // containers). If the old instance predates CES_SERVICE_TOKEN, generate a
+  // fresh one so gateway and CES can authenticate.
+  const cesServiceToken =
+    capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
+
   // 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([
+    "CES_SERVICE_TOKEN",
     "VELLUM_ASSISTANT_NAME",
     "RUNTIME_HTTP_HOST",
     "PATH",
@@ -278,9 +291,16 @@ async function upgradeDocker(
     }
   }
 
+  console.log("🔄 Migrating security files to gateway volume...");
+  await migrateGatewaySecurityFiles(res, (msg) => console.log(msg));
+
+  console.log("🔄 Migrating credential files to CES security volume...");
+  await migrateCesSecurityFiles(res, (msg) => console.log(msg));
+
   console.log("🚀 Starting upgraded containers...");
   await startContainers(
     {
+      cesServiceToken,
       extraAssistantEnv,
       gatewayPort,
       imageTags,
@@ -294,6 +314,23 @@ async function upgradeDocker(
   console.log("Waiting for assistant to become ready...");
   const ready = await waitForReady(entry.runtimeUrl);
   if (ready) {
+    // Update lockfile with new service group topology
+    const newDigests = await captureImageRefs(res);
+    const updatedEntry: AssistantEntry = {
+      ...entry,
+      serviceGroupVersion: versionTag,
+      containerInfo: {
+        assistantImage: imageTags.assistant,
+        gatewayImage: imageTags.gateway,
+        cesImage: imageTags["credential-executor"],
+        assistantDigest: newDigests?.assistant,
+        gatewayDigest: newDigests?.gateway,
+        cesDigest: newDigests?.["credential-executor"],
+        networkName: res.network,
+      },
+    };
+    saveAssistantEntry(updatedEntry);
+
     console.log(
       `\n✅ Docker assistant '${instanceName}' upgraded to ${versionTag}.`,
     );
@@ -307,6 +344,7 @@ async function upgradeDocker(
 
         await startContainers(
           {
+            cesServiceToken,
             extraAssistantEnv,
             gatewayPort,
             imageTags: previousImageRefs,
@@ -318,6 +356,19 @@ async function upgradeDocker(
 
         const rollbackReady = await waitForReady(entry.runtimeUrl);
         if (rollbackReady) {
+          // Restore previous container info in lockfile after rollback
+          if (previousImageRefs) {
+            const rolledBackEntry: AssistantEntry = {
+              ...entry,
+              containerInfo: {
+                assistantImage: previousImageRefs.assistant,
+                gatewayImage: previousImageRefs.gateway,
+                cesImage: previousImageRefs["credential-executor"],
+                networkName: res.network,
+              },
+            };
+            saveAssistantEntry(rolledBackEntry);
+          }
           console.log(
             `\n⚠️  Rolled back to previous version. Upgrade to ${versionTag} failed.`,
           );

package/src/commands/wake.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 
 import { resolveTargetAssistant } from "../lib/assistant-config.js";
+import { dockerResourceNames, wakeContainers } from "../lib/docker.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 import {
   isAssistantWatchModeAvailable,
@@ -38,9 +39,17 @@ export async function wake(): Promise<void> {
   const nameArg = args.find((a) => !a.startsWith("-"));
   const entry = resolveTargetAssistant(nameArg);
 
+  if (entry.cloud === "docker") {
+    const res = dockerResourceNames(entry.assistantId);
+    await wakeContainers(res);
+    console.log("Docker containers started.");
+    console.log("Wake complete.");
+    return;
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
-      `Error: 'vellum wake' only works with local assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,
+      `Error: 'vellum wake' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,
     );
     process.exit(1);
   }

package/src/index.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import cliPkg from "../package.json";
+import { backup } from "./commands/backup";
 import { clean } from "./commands/clean";
 import { client } from "./commands/client";
 import { hatch } from "./commands/hatch";
@@ -8,6 +9,7 @@ import { login, logout, whoami } from "./commands/login";
 import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
+import { restore } from "./commands/restore";
 import { retire } from "./commands/retire";
 import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
@@ -26,6 +28,7 @@ import { loadGuardianToken } from "./lib/guardian-token";
 import { checkHealth } from "./lib/health-check";
 
 const commands = {
+  backup,
   clean,
   client,
   hatch,
@@ -34,6 +37,7 @@ const commands = {
   pair,
   ps,
   recover,
+  restore,
   retire,
   setup,
   sleep,
@@ -51,6 +55,7 @@ function printHelp(): void {
   console.log("Usage: vellum <command> [options]");
   console.log("");
   console.log("Commands:");
+  console.log("  backup   Export a backup of a running assistant");
   console.log("  clean    Kill orphaned vellum processes");
   console.log("  client   Connect to a hatched assistant");
   console.log("  hatch    Create a new assistant instance");
@@ -61,6 +66,7 @@ function printHelp(): void {
     "  ps       List assistants (or processes for a specific assistant)",
   );
   console.log("  recover  Restore a previously retired local assistant");
+  console.log("  restore  Restore a .vbundle backup into a running assistant");
   console.log("  retire   Delete an assistant instance");
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");

package/src/lib/assistant-config.ts

@@ -4,6 +4,7 @@ import { join } from "path";
 
 import {
   DAEMON_INTERNAL_ASSISTANT_ID,
+  DEFAULT_CES_PORT,
   DEFAULT_DAEMON_PORT,
   DEFAULT_GATEWAY_PORT,
   DEFAULT_QDRANT_PORT,
@@ -29,11 +30,28 @@ export interface LocalInstanceResources {
   gatewayPort: number;
   /** HTTP port for the Qdrant vector store */
   qdrantPort: number;
+  /** HTTP port for the CES (Claude Extension Server) */
+  cesPort: number;
   /** Absolute path to the daemon PID file */
   pidFile: string;
   [key: string]: unknown;
 }
 
+/** Docker image metadata for the service group. Enables rollback to known-good digests. */
+export interface ContainerInfo {
+  assistantImage: string;
+  gatewayImage: string;
+  cesImage: string;
+  /** sha256 digest of the assistant image at time of hatch/upgrade */
+  assistantDigest?: string;
+  /** sha256 digest of the gateway image at time of hatch/upgrade */
+  gatewayDigest?: string;
+  /** sha256 digest of the CES image at time of hatch/upgrade */
+  cesDigest?: string;
+  /** Docker network name for the service group */
+  networkName?: string;
+}
+
 export interface AssistantEntry {
   assistantId: string;
   runtimeUrl: string;
@@ -56,6 +74,10 @@ export interface AssistantEntry {
   resources?: LocalInstanceResources;
   /** PID of the file watcher process for docker instances hatched with --watch. */
   watcherPid?: number;
+  /** Last-known version of the service group, populated at hatch and updated by health checks. */
+  serviceGroupVersion?: string;
+  /** Docker image metadata for rollback. Only present for docker topology entries. */
+  containerInfo?: ContainerInfo;
   [key: string]: unknown;
 }
 
@@ -166,6 +188,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       daemonPort: DEFAULT_DAEMON_PORT,
       gatewayPort,
       qdrantPort: DEFAULT_QDRANT_PORT,
+      cesPort: DEFAULT_CES_PORT,
       pidFile: join(instanceDir, ".vellum", "vellum.pid"),
     };
     mutated = true;
@@ -198,6 +221,10 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       res.qdrantPort = DEFAULT_QDRANT_PORT;
       mutated = true;
     }
+    if (typeof res.cesPort !== "number") {
+      res.cesPort = DEFAULT_CES_PORT;
+      mutated = true;
+    }
     if (typeof res.pidFile !== "string") {
       res.pidFile = join(res.instanceDir as string, ".vellum", "vellum.pid");
       mutated = true;
@@ -373,6 +400,7 @@ export async function allocateLocalResources(
       daemonPort: DEFAULT_DAEMON_PORT,
       gatewayPort: DEFAULT_GATEWAY_PORT,
       qdrantPort: DEFAULT_QDRANT_PORT,
+      cesPort: DEFAULT_CES_PORT,
       pidFile: join(vellumDir, "vellum.pid"),
     };
   }
@@ -423,6 +451,7 @@ export async function allocateLocalResources(
     daemonPort,
     gatewayPort,
     qdrantPort,
+    cesPort: DEFAULT_CES_PORT,
     pidFile: join(instanceDir, ".vellum", "vellum.pid"),
   };
 }

package/src/lib/aws.ts

@@ -6,7 +6,7 @@ import { buildStartupScript, watchHatching } from "../commands/hatch";
 import type { PollResult } from "../commands/hatch";
 import { saveAssistantEntry, setActiveAssistant } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
-import { GATEWAY_PORT } from "./constants";
+import { GATEWAY_PORT, PROVIDER_ENV_VAR_NAMES } from "./constants";
 import type { Species } from "./constants";
 import { leaseGuardianToken } from "./guardian-token";
 import { generateInstanceName } from "./random-name";
@@ -410,10 +410,18 @@ export async function hatchAws(
 
     const sshUser = userInfo().username;
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
-    const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
-    if (!anthropicApiKey) {
+    const providerApiKeys: Record<string, string> = {};
+    for (const [, envVar] of Object.entries(PROVIDER_ENV_VAR_NAMES)) {
+      const value = process.env[envVar];
+      if (value) {
+        providerApiKeys[envVar] = value;
+      }
+    }
+    if (Object.keys(providerApiKeys).length === 0) {
       console.error(
-        "Error: ANTHROPIC_API_KEY environment variable is not set.",
+        "Error: No provider API key environment variable is set. " +
+          "Set at least one of: " +
+          Object.values(PROVIDER_ENV_VAR_NAMES).join(", "),
       );
       process.exit(1);
     }
@@ -437,7 +445,7 @@ export async function hatchAws(
     const startupScript = await buildStartupScript(
       species,
       sshUser,
-      anthropicApiKey,
+      providerApiKeys,
       instanceName,
       "aws",
     );

package/src/lib/constants.ts

@@ -1,3 +1,5 @@
+import providerEnvVarsRegistry from "../../../meta/provider-env-vars.json";
+
 /**
  * Canonical internal assistant ID used as the default/fallback across the CLI
  * and daemon. Mirrors `DAEMON_INTERNAL_ASSISTANT_ID` from
@@ -14,6 +16,16 @@ export const GATEWAY_PORT = process.env.GATEWAY_PORT
 export const DEFAULT_DAEMON_PORT = 7821;
 export const DEFAULT_GATEWAY_PORT = 7830;
 export const DEFAULT_QDRANT_PORT = 6333;
+export const DEFAULT_CES_PORT = 8090;
+
+/**
+ * Environment variable names for provider API keys, keyed by provider ID.
+ * Loaded from the shared registry at `meta/provider-env-vars.json` — the
+ * single source of truth also consumed by the assistant runtime and the
+ * macOS client.
+ */
+export const PROVIDER_ENV_VAR_NAMES: Record<string, string> =
+  providerEnvVarsRegistry.providers;
 
 export const VALID_REMOTE_HOSTS = [
   "local",