@vellumai/cli 0.4.37 → 0.4.40

package/src/commands/retire.ts

@@ -4,7 +4,9 @@ import { homedir } from "os";
 import { basename, dirname, join } from "path";
 
 import {
+  defaultLocalResources,
   findAssistantByName,
+  loadAllAssistants,
   removeAssistantEntry,
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
@@ -40,18 +42,44 @@ function extractHostFromUrl(url: string): string {
   }
 }
 
-function getBaseDir(): string {
-  return process.env.BASE_DATA_DIR?.trim() || homedir();
-}
-
 async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
   console.log("\u{1F5D1}\ufe0f  Stopping local assistant...\n");
 
-  const vellumDir = join(getBaseDir(), ".vellum");
+  // Use entry resources when available; for legacy entries, derive paths
+  // from baseDataDir (which may differ from homedir if BASE_DATA_DIR was set).
+  const resources = entry.resources ?? defaultLocalResources();
+  const legacyDir = entry.baseDataDir;
+  const vellumDir = legacyDir ?? join(resources.instanceDir, ".vellum");
+
+  // Check whether another local assistant shares the same data directory.
+  // Legacy entries without `resources` all resolve to ~/.vellum/ — if we
+  // blindly kill processes and archive the directory, we'd destroy the
+  // other assistant's running daemon and data.
+  const otherSharesDir = loadAllAssistants().some((other) => {
+    if (other.cloud !== "local") return false;
+    if (other.assistantId === name) return false;
+    const otherVellumDir =
+      other.baseDataDir ??
+      join((other.resources ?? defaultLocalResources()).instanceDir, ".vellum");
+    return otherVellumDir === vellumDir;
+  });
 
-  // Stop daemon via PID file
-  const daemonPidFile = join(vellumDir, "vellum.pid");
-  const socketFile = join(vellumDir, "vellum.sock");
+  if (otherSharesDir) {
+    console.log(
+      `   Skipping process stop and archive — another local assistant shares ${vellumDir}.`,
+    );
+    console.log("\u2705 Local instance retired (config entry removed only).");
+    return;
+  }
+
+  // Stop daemon via PID file — prefer resources paths, but for legacy entries
+  // with a custom baseDataDir, derive from that directory instead.
+  const daemonPidFile = legacyDir
+    ? join(legacyDir, "vellum.pid")
+    : resources.pidFile;
+  const socketFile = legacyDir
+    ? join(legacyDir, "vellum.sock")
+    : resources.socketPath;
   const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon", [
     socketFile,
   ]);
@@ -67,14 +95,22 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
     await stopOrphanedDaemonProcesses();
   }
 
+  // For named instances (instanceDir differs from homedir), archive and
+  // remove the entire instance directory. For the default instance
+  // (instanceDir is homedir), archive only the .vellum subdirectory.
+  const isNamedInstance = resources.instanceDir !== homedir();
+  const dirToArchive = isNamedInstance ? resources.instanceDir : vellumDir;
+
   // Move the data directory out of the way so the path is immediately available
   // for the next hatch, then kick off the tar archive in the background.
   const archivePath = getArchivePath(name);
   const metadataPath = getMetadataPath(name);
   const stagingDir = `${archivePath}.staging`;
 
-  if (!existsSync(vellumDir)) {
-    console.log(`   No data directory at ${vellumDir} — nothing to archive.`);
+  if (!existsSync(dirToArchive)) {
+    console.log(
+      `   No data directory at ${dirToArchive} — nothing to archive.`,
+    );
     console.log("\u2705 Local instance retired.");
     return;
   }
@@ -83,10 +119,10 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
   mkdirSync(dirname(stagingDir), { recursive: true });
 
   try {
-    renameSync(vellumDir, stagingDir);
+    renameSync(dirToArchive, stagingDir);
   } catch (err) {
     console.warn(
-      `⚠️  Failed to move ${vellumDir}: ${err instanceof Error ? err.message : err}`,
+      `⚠️  Failed to move ${dirToArchive}: ${err instanceof Error ? err.message : err}`,
     );
     console.warn("Skipping archive.");
     console.log("\u2705 Local instance retired.");

package/src/commands/sleep.ts

@@ -1,20 +1,40 @@
-import { homedir } from "os";
 import { join } from "path";
 
+import {
+  defaultLocalResources,
+  resolveTargetAssistant,
+} from "../lib/assistant-config.js";
 import { stopProcessByPidFile } from "../lib/process";
 
 export async function sleep(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum sleep");
+    console.log("Usage: vellum sleep [<name>]");
     console.log("");
     console.log("Stop the assistant and gateway processes.");
+    console.log("");
+    console.log("Arguments:");
+    console.log(
+      "  <name>    Name of the assistant to stop (default: active or only local)",
+    );
     process.exit(0);
   }
 
-  const vellumDir = join(homedir(), ".vellum");
-  const daemonPidFile = join(vellumDir, "vellum.pid");
-  const socketFile = join(vellumDir, "vellum.sock");
+  const nameArg = args.find((a) => !a.startsWith("-"));
+  const entry = resolveTargetAssistant(nameArg);
+
+  if (entry.cloud && entry.cloud !== "local") {
+    console.error(
+      `Error: 'vellum sleep' only works with local assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,
+    );
+    process.exit(1);
+  }
+
+  const resources = entry.resources ?? defaultLocalResources();
+
+  const daemonPidFile = resources.pidFile;
+  const socketFile = resources.socketPath;
+  const vellumDir = join(resources.instanceDir, ".vellum");
   const gatewayPidFile = join(vellumDir, "gateway.pid");
 
   // Stop daemon
@@ -40,5 +60,4 @@ export async function sleep(): Promise<void> {
   } else {
     console.log("Gateway stopped.");
   }
-
 }

package/src/commands/use.ts

@@ -0,0 +1,44 @@
+import {
+  findAssistantByName,
+  getActiveAssistant,
+  setActiveAssistant,
+} from "../lib/assistant-config.js";
+
+export async function use(): Promise<void> {
+  const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum use [<name>]");
+    console.log("");
+    console.log("Set the active assistant for commands.");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>    Name of the assistant to make active");
+    console.log("");
+    console.log(
+      "When called without a name, prints the current active assistant.",
+    );
+    process.exit(0);
+  }
+
+  const name = args.find((a) => !a.startsWith("-"));
+
+  if (!name) {
+    const active = getActiveAssistant();
+    if (active) {
+      console.log(`Active assistant: ${active}`);
+    } else {
+      console.log("No active assistant set.");
+    }
+    return;
+  }
+
+  const entry = findAssistantByName(name);
+  if (!entry) {
+    console.error(`No assistant found with name '${name}'.`);
+    process.exit(1);
+  }
+
+  setActiveAssistant(name);
+  console.log(`Active assistant set to '${name}'.`);
+}

package/src/commands/wake.ts

@@ -1,18 +1,25 @@
 import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
 import { join } from "path";
 
-import { loadAllAssistants } from "../lib/assistant-config";
+import {
+  defaultLocalResources,
+  resolveTargetAssistant,
+} from "../lib/assistant-config.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 import { startLocalDaemon, startGateway } from "../lib/local";
 
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum wake [options]");
+    console.log("Usage: vellum wake [<name>] [options]");
     console.log("");
     console.log("Start the assistant and gateway processes.");
     console.log("");
+    console.log("Arguments:");
+    console.log(
+      "  <name>    Name of the assistant to start (default: active or only local)",
+    );
+    console.log("");
     console.log("Options:");
     console.log(
       "  --watch    Run assistant and gateway in watch mode (hot reload on source changes)",
@@ -21,19 +28,20 @@ export async function wake(): Promise<void> {
   }
 
   const watch = args.includes("--watch");
+  const nameArg = args.find((a) => !a.startsWith("-"));
+  const entry = resolveTargetAssistant(nameArg);
 
-  const assistants = loadAllAssistants();
-  const hasLocal = assistants.some((a) => a.cloud === "local");
-  if (!hasLocal) {
+  if (entry.cloud && entry.cloud !== "local") {
     console.error(
-      "Error: No local assistant found in lock file. Run 'vellum hatch local' first.",
+      `Error: 'vellum wake' only works with local assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,
     );
     process.exit(1);
   }
 
-  const vellumDir = join(homedir(), ".vellum");
-  const pidFile = join(vellumDir, "vellum.pid");
-  const socketFile = join(vellumDir, "vellum.sock");
+  const resources = entry.resources ?? defaultLocalResources();
+
+  const pidFile = resources.pidFile;
+  const socketFile = resources.socketPath;
 
   // Check if daemon is already running
   let daemonRunning = false;
@@ -61,11 +69,12 @@ export async function wake(): Promise<void> {
   }
 
   if (!daemonRunning) {
-    await startLocalDaemon(watch);
+    await startLocalDaemon(watch, resources);
   }
 
-  // Start gateway (non-desktop only)
-  if (!process.env.VELLUM_DESKTOP_APP) {
+  // Start gateway
+  {
+    const vellumDir = join(resources.instanceDir, ".vellum");
     const gatewayPidFile = join(vellumDir, "gateway.pid");
     const { alive, pid } = isProcessAlive(gatewayPidFile);
     if (alive) {
@@ -75,14 +84,14 @@ export async function wake(): Promise<void> {
           `Gateway running (pid ${pid}) — restarting in watch mode...`,
         );
         await stopProcessByPidFile(gatewayPidFile, "gateway");
-        await startGateway(undefined, watch);
+        await startGateway(undefined, watch, resources);
       } else {
         console.log(`Gateway already running (pid ${pid}).`);
       }
     } else {
-      await startGateway(undefined, watch);
+      await startGateway(undefined, watch, resources);
     }
   }
 
-  console.log("✅ Wake complete.");
+  console.log("Wake complete.");
 }

package/src/index.ts

@@ -1,11 +1,5 @@
 #!/usr/bin/env bun
 
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
-
 import cliPkg from "../package.json";
 import { client } from "./commands/client";
 import { hatch } from "./commands/hatch";
@@ -18,6 +12,7 @@ import { skills } from "./commands/skills";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
 import { tunnel } from "./commands/tunnel";
+import { use } from "./commands/use";
 import { wake } from "./commands/wake";
 
 const commands = {
@@ -33,37 +28,13 @@ const commands = {
   sleep,
   ssh,
   tunnel,
+  use,
   wake,
   whoami,
 } as const;
 
 type CommandName = keyof typeof commands;
 
-function resolveAssistantEntry(): string | undefined {
-  // When installed globally, resolve from node_modules
-  try {
-    const require = createRequire(import.meta.url);
-    const assistantPkgPath =
-      require.resolve("@vellumai/assistant/package.json");
-    return join(dirname(assistantPkgPath), "src", "index.ts");
-  } catch {
-    // For local development, resolve from sibling directory
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    const localPath = join(
-      __dirname,
-      "..",
-      "..",
-      "assistant",
-      "src",
-      "index.ts",
-    );
-    if (existsSync(localPath)) {
-      return localPath;
-    }
-  }
-  return undefined;
-}
-
 async function main() {
   const args = process.argv.slice(2);
   const commandName = args[0];
@@ -77,11 +48,7 @@ async function main() {
     console.log("Usage: vellum <command> [options]");
     console.log("");
     console.log("Commands:");
-    console.log("  autonomy View and configure autonomy tiers");
     console.log("  client   Connect to a hatched assistant");
-    console.log("  config   Manage configuration");
-    console.log("  contacts Manage assistant contacts");
-    console.log("  email    Email operations (provider-agnostic)");
     console.log("  hatch    Create a new assistant instance");
     console.log("  login    Log in to the Vellum platform");
     console.log("  logout   Log out of the Vellum platform");
@@ -95,6 +62,7 @@ async function main() {
     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("  use      Set the active assistant for commands");
     console.log("  wake     Start the assistant and gateway");
     console.log("  whoami   Show current logged-in user");
     process.exit(0);
@@ -103,20 +71,8 @@ async function main() {
   const command = commands[commandName as CommandName];
 
   if (!command) {
-    const assistantEntry = resolveAssistantEntry();
-    if (assistantEntry) {
-      const child = spawn("bun", ["run", assistantEntry, ...args], {
-        stdio: "inherit",
-      });
-      child.on("exit", (code) => {
-        process.exit(code ?? 1);
-      });
-    } else {
-      console.error(`Unknown command: ${commandName}`);
-      console.error("Install the full stack with: bun install -g vellum");
-      process.exit(1);
-    }
-    return;
+    console.error(`Unknown command: ${commandName}`);
+    process.exit(1);
   }
 
   try {

package/src/lib/assistant-config.ts

@@ -1,10 +1,49 @@
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
+import {
+  DEFAULT_DAEMON_PORT,
+  DEFAULT_GATEWAY_PORT,
+  DEFAULT_QDRANT_PORT,
+} from "./constants.js";
+import { probePort } from "./port-probe.js";
+
+/**
+ * Per-instance resource paths and ports. Each local assistant instance gets
+ * its own directory tree, ports, and socket so multiple instances can run
+ * side-by-side without conflicts.
+ */
+export interface LocalInstanceResources {
+  /**
+   * Instance-specific data root. The first local assistant uses `~` (workspace
+   * at `~/.vellum`); subsequent assistants use
+   * `~/.local/share/vellum/assistants/<name>/` (workspace at
+   * `~/.local/share/vellum/assistants/<name>/.vellum`).
+   * The daemon's `.vellum/` directory lives inside it. Equivalent to
+   * `AssistantEntry.baseDataDir` minus the trailing `/.vellum` suffix —
+   * `baseDataDir` is kept on the flat entry for legacy lockfile compat.
+   */
+  instanceDir: string;
+  /** HTTP port for the daemon runtime server */
+  daemonPort: number;
+  /** HTTP port for the gateway */
+  gatewayPort: number;
+  /** HTTP port for the Qdrant vector store */
+  qdrantPort: number;
+  /** Absolute path to the Unix domain socket for IPC */
+  socketPath: string;
+  /** Absolute path to the daemon PID file */
+  pidFile: string;
+}
+
 export interface AssistantEntry {
   assistantId: string;
   runtimeUrl: string;
+  /** Loopback URL for same-machine health checks (e.g. `http://127.0.0.1:7831`).
+   *  Avoids mDNS resolution issues when the machine checks its own gateway. */
+  localUrl?: string;
+  /** @deprecated Use `resources.instanceDir` for multi-instance entries. Legacy equivalent of `join(instanceDir, ".vellum")`. */
   baseDataDir?: string;
   bearerToken?: string;
   cloud: string;
@@ -16,10 +55,13 @@ export interface AssistantEntry {
   sshUser?: string;
   zone?: string;
   hatchedAt?: string;
+  /** Per-instance resource config. Present for local entries in multi-instance setups. */
+  resources?: LocalInstanceResources;
 }
 
 interface LockfileData {
   assistants?: AssistantEntry[];
+  activeAssistant?: string;
   platformBaseUrl?: string;
   [key: string]: unknown;
 }
@@ -91,14 +133,70 @@ export function findAssistantByName(name: string): AssistantEntry | null {
 }
 
 export function removeAssistantEntry(assistantId: string): void {
-  const entries = readAssistants();
-  writeAssistants(entries.filter((e) => e.assistantId !== assistantId));
+  const data = readLockfile();
+  const entries = (data.assistants ?? []).filter(
+    (e: AssistantEntry) => e.assistantId !== assistantId,
+  );
+  data.assistants = entries;
+  // Clear active assistant if it matches the removed entry
+  if (data.activeAssistant === assistantId) {
+    delete data.activeAssistant;
+  }
+  writeLockfile(data);
 }
 
 export function loadAllAssistants(): AssistantEntry[] {
   return readAssistants();
 }
 
+export function getActiveAssistant(): string | null {
+  const data = readLockfile();
+  return data.activeAssistant ?? null;
+}
+
+export function setActiveAssistant(assistantId: string): void {
+  const data = readLockfile();
+  data.activeAssistant = assistantId;
+  writeLockfile(data);
+}
+
+/**
+ * Resolve which assistant to target for a command. Priority:
+ * 1. Explicit name argument
+ * 2. Active assistant set via `vellum use`
+ * 3. Sole local assistant (when exactly one exists)
+ */
+export function resolveTargetAssistant(nameArg?: string): 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;
+    // Active assistant no longer exists in lockfile — fall through
+  }
+
+  const all = readAssistants();
+  const locals = all.filter((e) => e.cloud === "local");
+  if (locals.length === 1) return locals[0];
+
+  if (locals.length === 0) {
+    console.error("No local assistant found. Run 'vellum hatch local' first.");
+  } else {
+    console.error(
+      `Multiple assistants found. Set an active assistant with 'vellum use <name>'.`,
+    );
+  }
+  process.exit(1);
+}
+
 export function saveAssistantEntry(entry: AssistantEntry): void {
   const entries = readAssistants().filter(
     (e) => e.assistantId !== entry.assistantId,
@@ -107,6 +205,131 @@ export function saveAssistantEntry(entry: AssistantEntry): void {
   writeAssistants(entries);
 }
 
+/**
+ * Scan upward from `basePort` to find an available port. A port is considered
+ * available when `probePort()` returns false (nothing listening). Scans up to
+ * 100 ports above the base before giving up.
+ */
+async function findAvailablePort(
+  basePort: number,
+  excludedPorts: number[] = [],
+): Promise<number> {
+  const maxOffset = 100;
+  for (let offset = 0; offset < maxOffset; offset++) {
+    const port = basePort + offset;
+    if (excludedPorts.includes(port)) continue;
+    const inUse = await probePort(port);
+    if (!inUse) return port;
+  }
+  throw new Error(
+    `Could not find an available port scanning from ${basePort} to ${basePort + maxOffset - 1}`,
+  );
+}
+
+/**
+ * Allocate an isolated set of resources for a named local instance.
+ * The first local assistant gets `instanceDir = ~` with default ports (same as
+ * legacy single-instance layout). Subsequent assistants are placed under
+ * `~/.local/share/vellum/assistants/<name>/` with scanned ports.
+ */
+export async function allocateLocalResources(
+  instanceName: string,
+): Promise<LocalInstanceResources> {
+  // First local assistant gets the home directory — identical to legacy layout.
+  const existingLocals = loadAllAssistants().filter((e) => e.cloud === "local");
+  if (existingLocals.length === 0) {
+    return defaultLocalResources();
+  }
+
+  const instanceDir = join(
+    homedir(),
+    ".local",
+    "share",
+    "vellum",
+    "assistants",
+    instanceName,
+  );
+  mkdirSync(instanceDir, { recursive: true });
+
+  // Collect ports already assigned to other local instances in the lockfile.
+  // Even if those instances are stopped, we must avoid reusing their ports
+  // to prevent binding collisions when both are woken.
+  const reservedPorts: number[] = [];
+  for (const entry of loadAllAssistants()) {
+    if (entry.cloud !== "local") continue;
+    if (entry.resources) {
+      reservedPorts.push(
+        entry.resources.daemonPort,
+        entry.resources.gatewayPort,
+        entry.resources.qdrantPort,
+      );
+    } else {
+      // Legacy entries without resources use the default ports
+      reservedPorts.push(
+        DEFAULT_DAEMON_PORT,
+        DEFAULT_GATEWAY_PORT,
+        DEFAULT_QDRANT_PORT,
+      );
+    }
+  }
+
+  // Allocate ports sequentially to avoid overlapping ranges assigning the
+  // same port to multiple services (e.g. daemon 7821-7920 overlaps gateway 7830-7929).
+  const daemonPort = await findAvailablePort(
+    DEFAULT_DAEMON_PORT,
+    reservedPorts,
+  );
+  const gatewayPort = await findAvailablePort(DEFAULT_GATEWAY_PORT, [
+    ...reservedPorts,
+    daemonPort,
+  ]);
+  const qdrantPort = await findAvailablePort(DEFAULT_QDRANT_PORT, [
+    ...reservedPorts,
+    daemonPort,
+    gatewayPort,
+  ]);
+
+  return {
+    instanceDir,
+    daemonPort,
+    gatewayPort,
+    qdrantPort,
+    socketPath: join(instanceDir, ".vellum", "vellum.sock"),
+    pidFile: join(instanceDir, ".vellum", "vellum.pid"),
+  };
+}
+
+/**
+ * Return default resources representing the legacy single-instance layout.
+ * Used to normalize existing lockfile entries so callers can treat all local
+ * entries uniformly.
+ */
+export function defaultLocalResources(): LocalInstanceResources {
+  const vellumDir = join(homedir(), ".vellum");
+  return {
+    instanceDir: homedir(),
+    daemonPort: DEFAULT_DAEMON_PORT,
+    gatewayPort: DEFAULT_GATEWAY_PORT,
+    qdrantPort: DEFAULT_QDRANT_PORT,
+    socketPath: join(vellumDir, "vellum.sock"),
+    pidFile: join(vellumDir, "vellum.pid"),
+  };
+}
+
+/**
+ * Normalize existing lockfile entries so local entries include resource fields.
+ * Remote entries are left untouched. Returns a new array (does not mutate input).
+ */
+export function normalizeExistingEntryResources(
+  entries: AssistantEntry[],
+): AssistantEntry[] {
+  return entries.map((entry) => {
+    if (entry.cloud !== "local") return entry;
+    if (entry.resources) return entry;
+    return { ...entry, resources: defaultLocalResources() };
+  });
+}
+
 /**
  * Read the assistant config file and sync client-relevant values to the
  * lockfile. This lets external tools (e.g. vel) discover the platform URL

package/src/lib/constants.ts

@@ -2,6 +2,12 @@ export const FIREWALL_TAG = "vellum-assistant";
 export const GATEWAY_PORT = process.env.GATEWAY_PORT
   ? Number(process.env.GATEWAY_PORT)
   : 7830;
+
+/** Default ports used as scan start points for multi-instance allocation. */
+export const DEFAULT_DAEMON_PORT = 7821;
+export const DEFAULT_GATEWAY_PORT = 7830;
+export const DEFAULT_QDRANT_PORT = 6333;
+
 export const VALID_REMOTE_HOSTS = ["local", "gcp", "aws", "custom"] as const;
 export type RemoteHost = (typeof VALID_REMOTE_HOSTS)[number];
 export const VALID_SPECIES = ["openclaw", "vellum"] as const;