@vellumai/cli 0.6.3 → 0.6.5

package/src/lib/exec-apple-container.ts

@@ -0,0 +1,122 @@
+import { createConnection } from "net";
+import { existsSync } from "fs";
+
+import type { AssistantEntry } from "./assistant-config";
+
+/**
+ * Execute a command inside an Apple Container assistant via the management
+ * socket. Non-interactive: sends the command, streams stdout/stderr to the
+ * terminal, and exits with the appropriate code.
+ */
+export async function execAppleContainer(
+  entry: AssistantEntry,
+  command: string[],
+  service: string,
+): Promise<void> {
+  const mgmtSocket = entry.mgmtSocket as string | undefined;
+  if (!mgmtSocket) {
+    console.error(
+      `No management socket found for '${entry.assistantId}'.\n` +
+        "The assistant may not be running.",
+    );
+    process.exit(1);
+  }
+
+  if (!existsSync(mgmtSocket)) {
+    console.error(
+      `Management socket not found at ${mgmtSocket}.\n` +
+        "The assistant may have been stopped.",
+    );
+    process.exit(1);
+  }
+
+  const handshake =
+    JSON.stringify({
+      command,
+      service,
+      cols: process.stdout.columns || 120,
+      rows: process.stdout.rows || 40,
+    }) + "\n";
+
+  return new Promise<void>((resolve, reject) => {
+    const socket = createConnection({ path: mgmtSocket }, () => {
+      socket.write(handshake);
+    });
+
+    const HANDSHAKE_TIMEOUT_MS = 10_000;
+    let handshakeComplete = false;
+    const handshakeChunks: Buffer[] = [];
+    let handshakeLen = 0;
+
+    socket.setTimeout(HANDSHAKE_TIMEOUT_MS);
+    socket.on("timeout", () => {
+      if (!handshakeComplete) {
+        console.error("Timed out waiting for response from management socket.");
+        socket.destroy();
+        process.exit(1);
+      }
+    });
+
+    socket.on("data", (data: Buffer) => {
+      if (!handshakeComplete) {
+        handshakeChunks.push(data);
+        handshakeLen += data.length;
+        const accumulated = Buffer.concat(handshakeChunks, handshakeLen);
+        const nlIndex = accumulated.indexOf(0x0a);
+        if (nlIndex === -1) return;
+
+        const responseLine = accumulated.slice(0, nlIndex).toString("utf-8");
+        const remainder = accumulated.slice(nlIndex + 1);
+        handshakeComplete = true;
+        socket.setTimeout(0);
+
+        let response: { status: string; message?: string };
+        try {
+          response = JSON.parse(responseLine) as {
+            status: string;
+            message?: string;
+          };
+        } catch {
+          console.error("Invalid response from management socket.");
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        if (response.status !== "ok") {
+          console.error(`Exec failed: ${response.message || "unknown error"}`);
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        // Write any bytes that arrived after the handshake newline.
+        if (remainder.length > 0) {
+          process.stdout.write(remainder);
+        }
+        return;
+      }
+
+      // Stream command output to stdout.
+      process.stdout.write(data);
+    });
+
+    socket.on("end", () => {
+      if (handshakeComplete) {
+        resolve();
+      } else {
+        reject(new Error("Connection closed before handshake completed."));
+      }
+    });
+
+    socket.on("error", (err) => {
+      reject(new Error(`Management socket error: ${err.message}`));
+    });
+
+    socket.on("close", () => {
+      if (handshakeComplete) {
+        resolve();
+      }
+    });
+  });
+}

package/src/lib/gcp.ts

@@ -503,7 +503,18 @@ export async function hatchGcp(
       }
     }
 
-    const sshUser = userInfo().username;
+    let sshUser: string;
+    try {
+      sshUser = userInfo().username;
+    } catch {
+      sshUser = process.env.USER ?? "";
+    }
+    if (!sshUser) {
+      console.error(
+        "Error: Could not determine SSH username. Set the USER environment variable and try again.",
+      );
+      process.exit(1);
+    }
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
     const providerApiKeys: Record<string, string> = {};
     for (const [, envVar] of Object.entries(PROVIDER_ENV_VAR_NAMES)) {

package/src/lib/guardian-token.ts

@@ -5,11 +5,16 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  statSync,
   writeFileSync,
 } from "fs";
-import { homedir, platform } from "os";
+import { platform } from "os";
 import { dirname, join } from "path";
 
+import { getConfigDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
+import { SEEDS } from "./environments/seeds.js";
+
 const DEVICE_ID_SALT = "vellum-assistant-host-id";
 
 export interface GuardianTokenData {
@@ -24,14 +29,9 @@ export interface GuardianTokenData {
   leasedAt: string;
 }
 
-function getXdgConfigHome(): string {
-  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-}
-
 function getGuardianTokenPath(assistantId: string): string {
   return join(
-    getXdgConfigHome(),
-    "vellum",
+    getConfigDir(getCurrentEnvironment()),
     "assistants",
     assistantId,
     "guardian-token.json",
@@ -39,7 +39,7 @@ function getGuardianTokenPath(assistantId: string): string {
 }
 
 function getPersistedDeviceIdPath(): string {
-  return join(getXdgConfigHome(), "vellum", "device-id");
+  return join(getConfigDir(getCurrentEnvironment()), "device-id");
 }
 
 function hashWithSalt(input: string): string {
@@ -82,7 +82,7 @@ function getWindowsMachineGuid(): string | null {
   }
 }
 
-function getOrCreatePersistedDeviceId(): string {
+export function getOrCreatePersistedDeviceId(): string {
   const path = getPersistedDeviceIdPath();
   try {
     const existing = readFileSync(path, "utf-8").trim();
@@ -161,7 +161,7 @@ export function saveGuardianToken(
 /**
  * Call POST /v1/guardian/init on the remote gateway to bootstrap a JWT
  * credential pair. The returned tokens are persisted locally under
- * `$XDG_CONFIG_HOME/vellum/assistants/<assistantId>/guardian-token.json`.
+ * `$XDG_CONFIG_HOME/vellum{-env}/assistants/<assistantId>/guardian-token.json`.
  */
 export async function leaseGuardianToken(
   gatewayUrl: string,
@@ -202,3 +202,64 @@ export async function leaseGuardianToken(
   saveGuardianToken(assistantId, tokenData);
   return tokenData;
 }
+
+/**
+ * Copy a guardian token from a sibling environment's config directory into
+ * the current environment's dir when the current one is missing it.
+ *
+ * The CLI's per-environment config layout (`~/.config/vellum{-env}/`) scopes
+ * the lockfile and the guardian token by VELLUM_ENVIRONMENT. Lockfiles are
+ * cross-written at hatch time, but a guardian token is only written under
+ * the env the assistant was hatched in. If the user later wakes the same
+ * assistant under a different env (e.g. a freshly built desktop app ships
+ * with VELLUM_ENVIRONMENT=local while the original hatch was under dev),
+ * the app cannot locate a bearer token and falls into a 401 → auth-rate-
+ * limit → 429 cascade against the local gateway.
+ *
+ * Returns true if a token was seeded, false if a token was already present
+ * or no sibling env had one to copy.
+ */
+export function seedGuardianTokenFromSiblingEnv(assistantId: string): boolean {
+  if (loadGuardianToken(assistantId) !== null) return false;
+
+  const currentEnvName = getCurrentEnvironment().name;
+  const destPath = getGuardianTokenPath(assistantId);
+
+  const candidates: { path: string; mtimeMs: number }[] = [];
+  for (const env of Object.values(SEEDS)) {
+    if (env.name === currentEnvName) continue;
+    const sibling = join(
+      getConfigDir(env),
+      "assistants",
+      assistantId,
+      "guardian-token.json",
+    );
+    try {
+      const stat = statSync(sibling);
+      candidates.push({ path: sibling, mtimeMs: stat.mtimeMs });
+    } catch {
+      continue;
+    }
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const now = Date.now();
+  for (const { path: sibling } of candidates) {
+    try {
+      const raw = readFileSync(sibling);
+      const parsed = JSON.parse(raw.toString("utf-8")) as GuardianTokenData;
+      const refreshExpiry = Date.parse(parsed.refreshTokenExpiresAt);
+      if (!Number.isFinite(refreshExpiry) || refreshExpiry <= now) continue;
+      const dir = dirname(destPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+      }
+      writeFileSync(destPath, raw, { mode: 0o600 });
+      chmodSync(destPath, 0o600);
+      return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}

package/src/lib/hatch-local.ts

@@ -305,27 +305,32 @@ export async function hatchLocal(
   // IP which the daemon rejects as non-loopback.
   emitProgress(6, 7, "Securing connection...");
   const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
-  try {
-    await leaseGuardianToken(loopbackUrl, instanceName);
-  } catch (err) {
-    console.error(`⚠️  Guardian token lease failed: ${err}`);
+  const maxLeaseAttempts = 3;
+  for (let attempt = 1; attempt <= maxLeaseAttempts; attempt++) {
+    try {
+      await leaseGuardianToken(loopbackUrl, instanceName);
+      break;
+    } catch (err) {
+      if (attempt < maxLeaseAttempts) {
+        const delayMs = 2000 * 2 ** (attempt - 1);
+        console.error(
+          `⚠️  Guardian token lease attempt ${attempt}/${maxLeaseAttempts} failed — retrying in ${delayMs / 1000}s: ${err}`,
+        );
+        await new Promise((r) => setTimeout(r, delayMs));
+      } else {
+        console.error(
+          `⚠️  Guardian token lease failed after ${maxLeaseAttempts} attempts: ${err}\n` +
+            `   The assistant is running but guardian-token.json was not written.\n` +
+            `   If the desktop app loses its stored credentials, re-hatch to recover.`,
+        );
+      }
+    }
   }
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
-  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
-  const prevBaseDataDir = process.env.BASE_DATA_DIR;
-  process.env.BASE_DATA_DIR = resources.instanceDir;
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-  if (ngrokChild?.pid) {
-    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-  }
-  if (prevBaseDataDir !== undefined) {
-    process.env.BASE_DATA_DIR = prevBaseDataDir;
-  } else {
-    delete process.env.BASE_DATA_DIR;
-  }
-
+  // Set BASE_DATA_DIR so ngrok reads the correct instance config. Keep the
+  // lockfile save/sync inside the same scope so syncConfigToLockfile() reads
+  // this instance's workspace/config.json rather than a stale default path.
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
@@ -333,13 +338,29 @@ export async function hatchLocal(
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
-    serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
     resources: { ...resources, signingKey },
   };
-  emitProgress(7, 7, "Saving configuration...");
-  saveAssistantEntry(localEntry);
-  setActiveAssistant(instanceName);
-  syncConfigToLockfile();
+
+  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));
+    }
+
+    emitProgress(7, 7, "Saving configuration...");
+    saveAssistantEntry(localEntry);
+    setActiveAssistant(instanceName);
+    syncConfigToLockfile();
+  } finally {
+    if (prevBaseDataDir !== undefined) {
+      process.env.BASE_DATA_DIR = prevBaseDataDir;
+    } else {
+      delete process.env.BASE_DATA_DIR;
+    }
+  }
 
   if (process.env.VELLUM_DESKTOP_APP) {
     installCLISymlink();

package/src/lib/local.ts

@@ -283,12 +283,18 @@ async function startDaemonFromSource(
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
     VELLUM_CLOUD: "local",
     VELLUM_DEV: "1",
+    VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.GATEWAY_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -404,12 +410,18 @@ async function startDaemonWatchFromSource(
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
     VELLUM_DEV: "1",
+    VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
+    env.GATEWAY_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -855,11 +867,16 @@ export async function startLocalDaemon(
         HOME: process.env.HOME || home,
         PATH: [...extraDirs, basePath].filter(Boolean).join(":"),
       };
-      // Forward optional config env vars the daemon may need
+      // Forward optional config env vars the daemon may need.
+      // `VELLUM_ENVIRONMENT` must be forwarded so the daemon resolves
+      // env-scoped paths (device ID, platform/guardian tokens, XDG
+      // config dir) to the same location as the CLI that spawned it.
       for (const key of [
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
         "BASE_DATA_DIR",
+        "GATEWAY_SECURITY_DIR",
+        "VELLUM_ENVIRONMENT",
         "VELLUM_PLATFORM_URL",
         "QDRANT_HTTP_PORT",
         "QDRANT_URL",
@@ -885,6 +902,11 @@ export async function startLocalDaemon(
       // all paths under the instance directory and listens on its own port.
       if (resources) {
         daemonEnv.BASE_DATA_DIR = resources.instanceDir;
+        daemonEnv.GATEWAY_SECURITY_DIR = join(
+          resources.instanceDir,
+          ".vellum",
+          "protected",
+        );
         daemonEnv.RUNTIME_HTTP_PORT = String(resources.daemonPort);
         daemonEnv.GATEWAY_PORT = String(resources.gatewayPort);
         daemonEnv.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -1043,10 +1065,30 @@ export async function startGateway(
     ...(options?.signingKey
       ? { ACTOR_TOKEN_SIGNING_KEY: options.signingKey }
       : {}),
-    ...(watch ? { VELLUM_DEV: "1" } : {}),
-    // Set BASE_DATA_DIR so the gateway loads the correct credentials and
-    // workspace config for this instance (mirrors the daemon env setup).
-    ...(resources ? { BASE_DATA_DIR: resources.instanceDir } : {}),
+    ...(watch
+      ? {
+          VELLUM_DEV: "1",
+          VELLUM_ENVIRONMENT: process.env.VELLUM_ENVIRONMENT || "local",
+        }
+      : {}),
+    // Set VELLUM_WORKSPACE_DIR and GATEWAY_SECURITY_DIR so the gateway
+    // loads the correct credentials and workspace config for this instance
+    // (mirrors the daemon env setup).
+    ...(resources
+      ? {
+          BASE_DATA_DIR: resources.instanceDir,
+          VELLUM_WORKSPACE_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "workspace",
+          ),
+          GATEWAY_SECURITY_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "protected",
+          ),
+        }
+      : {}),
   };
   if (publicUrl) {
     console.log(`   Ingress URL: ${publicUrl}`);

package/src/lib/orphan-detection.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
+import { loadAllAssistants } from "./assistant-config.js";
 import { execOutput } from "./step-runner";
 
 export interface RemoteProcess {
@@ -72,20 +73,35 @@ export interface OrphanedProcess {
 export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
-  const vellumDir = join(homedir(), ".vellum");
 
-  // Strategy 1: PID file scan
-  const pidFiles: Array<{ file: string; name: string }> = [
-    { file: join(vellumDir, "vellum.pid"), name: "assistant" },
-    { file: join(vellumDir, "gateway.pid"), name: "gateway" },
-    { file: join(vellumDir, "qdrant.pid"), name: "qdrant" },
-  ];
+  // Collect every known local instance's `.vellum/` directory from the
+  // lockfile so orphan detection scans all containers under the current
+  // multi-instance data layout, not just the legacy `~/.vellum/` root.
+  const dirs = new Set<string>();
+  for (const entry of loadAllAssistants()) {
+    if (entry.cloud !== "local" || !entry.resources) continue;
+    dirs.add(join(entry.resources.instanceDir, ".vellum"));
+  }
+  // Preserve the legacy root scan for installs that predate multi-instance
+  // tracking. This catches orphans from a pre-upgrade `~/.vellum/` that
+  // may not have a lockfile entry at all.
+  dirs.add(join(homedir(), ".vellum"));
+
+  // Strategy 1: PID file scan — check every known data directory.
+  for (const dir of dirs) {
+    const pidFiles: Array<{ file: string; name: string }> = [
+      { file: join(dir, "vellum.pid"), name: "assistant" },
+      { file: join(dir, "gateway.pid"), name: "gateway" },
+      { file: join(dir, "qdrant.pid"), name: "qdrant" },
+    ];
 
-  for (const { file, name } of pidFiles) {
-    const pid = readPidFile(file);
-    if (pid && isProcessAlive(pid)) {
-      results.push({ name, pid, source: "pid file" });
-      seenPids.add(pid);
+    for (const { file, name } of pidFiles) {
+      const pid = readPidFile(file);
+      if (!pid || seenPids.has(pid)) continue;
+      if (isProcessAlive(pid)) {
+        results.push({ name, pid, source: "pid file" });
+        seenPids.add(pid);
+      }
     }
   }