@vellumai/cli 0.4.54 → 0.4.56

package/src/lib/gcp.ts

@@ -1,4 +1,3 @@
-import { randomBytes } from "crypto";
 import { unlinkSync, writeFileSync } from "fs";
 import { tmpdir, userInfo } from "os";
 import { join } from "path";
@@ -7,7 +6,8 @@ import { saveAssistantEntry, setActiveAssistant } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { FIREWALL_TAG, 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";
 
 export async function getActiveProject(): Promise<string> {
@@ -447,7 +447,6 @@ export async function hatchGcp(
   name: string | null,
   buildStartupScript: (
     species: Species,
-    bearerToken: string,
     sshUser: string,
     anthropicApiKey: string,
     instanceName: string,
@@ -467,12 +466,7 @@ export async function hatchGcp(
     const project = process.env.GCP_PROJECT ?? (await getActiveProject());
     let instanceName: string;
 
-    if (name) {
-      instanceName = name;
-    } else {
-      const suffix = generateRandomSuffix();
-      instanceName = `${species}-${suffix}`;
-    }
+    instanceName = generateInstanceName(species, name);
 
     console.log(`\ud83e\udd5a Creating new assistant: ${instanceName}`);
     console.log(`   Species: ${species}`);
@@ -500,13 +494,11 @@ export async function hatchGcp(
         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) {
@@ -517,7 +509,6 @@ export async function hatchGcp(
     }
     const startupScript = await buildStartupScript(
       species,
-      bearerToken,
       sshUser,
       anthropicApiKey,
       instanceName,
@@ -637,7 +628,7 @@ export async function hatchGcp(
           species === "vellum" &&
           (await checkCurlFailure(instanceName, project, zone, account))
         ) {
-          const installScriptUrl = `${process.env.VELLUM_PLATFORM_URL ?? "https://assistant.vellum.ai"}/install.sh`;
+          const installScriptUrl = `${process.env.VELLUM_PLATFORM_URL ?? "https://vellum.ai"}/install.sh`;
           console.log(
             `\ud83d\udd04 Detected install script curl failure for ${installScriptUrl}, attempting recovery...`,
           );
@@ -654,6 +645,16 @@ export async function hatchGcp(
         }
       }
 
+      try {
+        const tokenData = await leaseGuardianToken(runtimeUrl, instanceName);
+        gcpEntry.bearerToken = tokenData.accessToken;
+        saveAssistantEntry(gcpEntry);
+      } catch (err) {
+        console.warn(
+          `\u26a0\ufe0f  Could not lease guardian token: ${err instanceof Error ? err.message : err}`,
+        );
+      }
+
       console.log("Instance details:");
       console.log(`  Name: ${instanceName}`);
       console.log(`  Project: ${project}`);

package/src/lib/guardian-token.ts

@@ -0,0 +1,174 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir, platform } from "os";
+import { dirname, join } from "path";
+
+const DEVICE_ID_SALT = "vellum-assistant-host-id";
+
+export interface GuardianTokenData {
+  guardianPrincipalId: string;
+  accessToken: string;
+  accessTokenExpiresAt: string;
+  refreshToken: string;
+  refreshTokenExpiresAt: string;
+  refreshAfter: string;
+  isNew: boolean;
+  deviceId: string;
+  leasedAt: string;
+}
+
+function getXdgConfigHome(): string {
+  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+}
+
+function getGuardianTokenPath(assistantId: string): string {
+  return join(
+    getXdgConfigHome(),
+    "vellum",
+    "assistants",
+    assistantId,
+    "guardian-token.json",
+  );
+}
+
+function getPersistedDeviceIdPath(): string {
+  return join(getXdgConfigHome(), "vellum", "device-id");
+}
+
+function hashWithSalt(input: string): string {
+  return createHash("sha256")
+    .update(input + DEVICE_ID_SALT)
+    .digest("hex");
+}
+
+function getMacOSPlatformUUID(): string | null {
+  try {
+    const output = execSync(
+      "ioreg -rd1 -c IOPlatformExpertDevice | awk '/IOPlatformUUID/{print $3}'",
+      { encoding: "utf-8", timeout: 5000 },
+    ).trim();
+    const uuid = output.replace(/"/g, "");
+    return uuid.length > 0 ? uuid : null;
+  } catch {
+    return null;
+  }
+}
+
+function getLinuxMachineId(): string | null {
+  try {
+    return readFileSync("/etc/machine-id", "utf-8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function getWindowsMachineGuid(): string | null {
+  try {
+    const output = execSync(
+      'reg query "HKLM\\SOFTWARE\\Microsoft\\Cryptography" /v MachineGuid',
+      { encoding: "utf-8", timeout: 5000 },
+    ).trim();
+    const match = output.match(/MachineGuid\s+REG_SZ\s+(.+)/);
+    return match?.[1]?.trim() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function getOrCreatePersistedDeviceId(): string {
+  const path = getPersistedDeviceIdPath();
+  try {
+    const existing = readFileSync(path, "utf-8").trim();
+    if (existing.length > 0) {
+      return existing;
+    }
+  } catch {
+    // File doesn't exist yet
+  }
+  const newId = randomUUID();
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(path, newId + "\n", { mode: 0o600 });
+  return newId;
+}
+
+/**
+ * Compute a stable device identifier matching the native client conventions.
+ *
+ * - macOS: SHA-256 of IOPlatformUUID + salt (matches PairingQRCodeSheet.computeHostId)
+ * - Linux: SHA-256 of /etc/machine-id + salt
+ * - Windows: SHA-256 of HKLM MachineGuid + salt
+ * - Fallback: persisted random UUID in XDG config
+ */
+export function computeDeviceId(): string {
+  const os = platform();
+
+  if (os === "darwin") {
+    const uuid = getMacOSPlatformUUID();
+    if (uuid) return hashWithSalt(uuid);
+  } else if (os === "linux") {
+    const machineId = getLinuxMachineId();
+    if (machineId) return hashWithSalt(machineId);
+  } else if (os === "win32") {
+    const guid = getWindowsMachineGuid();
+    if (guid) return hashWithSalt(guid);
+  }
+
+  return getOrCreatePersistedDeviceId();
+}
+
+export function saveGuardianToken(
+  assistantId: string,
+  data: GuardianTokenData,
+): void {
+  const tokenPath = getGuardianTokenPath(assistantId);
+  const dir = dirname(tokenPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(tokenPath, JSON.stringify(data, null, 2) + "\n", {
+    mode: 0o600,
+  });
+  chmodSync(tokenPath, 0o600);
+}
+
+/**
+ * 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`.
+ */
+export async function leaseGuardianToken(
+  gatewayUrl: string,
+  assistantId: string,
+): Promise<GuardianTokenData> {
+  const deviceId = computeDeviceId();
+  const response = await fetch(`${gatewayUrl}/v1/guardian/init`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ platform: "cli", deviceId }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`guardian/init failed (${response.status}): ${body}`);
+  }
+
+  const json = (await response.json()) as Record<string, unknown>;
+  const tokenData: GuardianTokenData = {
+    guardianPrincipalId: json.guardianPrincipalId as string,
+    accessToken: json.accessToken as string,
+    accessTokenExpiresAt: json.accessTokenExpiresAt as string,
+    refreshToken: json.refreshToken as string,
+    refreshTokenExpiresAt: json.refreshTokenExpiresAt as string,
+    refreshAfter: json.refreshAfter as string,
+    isNew: json.isNew as boolean,
+    deviceId,
+    leasedAt: new Date().toISOString(),
+  };
+
+  saveGuardianToken(assistantId, tokenData);
+  return tokenData;
+}

package/src/lib/health-check.ts

@@ -10,32 +10,6 @@ export interface HealthCheckResult {
   detail: string | null;
 }
 
-interface OrgListResponse {
-  results: { id: string }[];
-}
-
-async function fetchOrganizationId(
-  platformUrl: string,
-  token: string,
-): Promise<{ orgId: string } | { error: string }> {
-  try {
-    const response = await fetch(`${platformUrl}/v1/organizations/`, {
-      headers: { "X-Session-Token": token },
-    });
-    if (!response.ok) {
-      return { error: `org lookup failed (${response.status})` };
-    }
-    const body = (await response.json()) as OrgListResponse;
-    const orgId = body.results?.[0]?.id;
-    if (!orgId) {
-      return { error: "no organization found" };
-    }
-    return { orgId };
-  } catch {
-    return { error: "org lookup unreachable" };
-  }
-}
-
 export async function checkManagedHealth(
   runtimeUrl: string,
   assistantId: string,
@@ -49,14 +23,16 @@ export async function checkManagedHealth(
     };
   }
 
-  const orgResult = await fetchOrganizationId(runtimeUrl, token);
-  if ("error" in orgResult) {
+  let orgId: string;
+  try {
+    const { fetchOrganizationId } = await import("./platform-client.js");
+    orgId = await fetchOrganizationId(token);
+  } catch (err) {
     return {
       status: "error (auth)",
-      detail: orgResult.error,
+      detail: err instanceof Error ? err.message : "org lookup failed",
     };
   }
-  const { orgId } = orgResult;
 
   try {
     const url = `${runtimeUrl}/v1/assistants/${encodeURIComponent(assistantId)}/healthz/`;

package/src/lib/local.ts

@@ -195,7 +195,9 @@ function resolveDaemonMainPath(assistantIndex: string): string {
 async function startDaemonFromSource(
   assistantIndex: string,
   resources: LocalInstanceResources,
+  options?: { foreground?: boolean },
 ): Promise<void> {
+  const foreground = options?.foreground ?? false;
   const daemonMainPath = resolveDaemonMainPath(assistantIndex);
 
   // Ensure the directory containing PID/socket files exists. For named
@@ -207,7 +209,25 @@ async function startDaemonFromSource(
   // --- Lifecycle guard: prevent split-brain daemon state ---
   if (existsSync(pidFile)) {
     try {
-      const pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+      const content = readFileSync(pidFile, "utf-8").trim();
+
+      // Another caller is already spawning the daemon — wait for it
+      // instead of racing to spawn a duplicate.
+      if (content === "starting") {
+        console.log(
+          "   Assistant is starting — waiting for it to become ready...",
+        );
+        if (await waitForDaemonReady(resources.daemonPort, 60000)) {
+          console.log("   Assistant is ready\n");
+          return;
+        }
+        // The other spawn may have failed; clean up and proceed to spawn.
+        try {
+          unlinkSync(pidFile);
+        } catch {}
+      }
+
+      const pid = parseInt(content, 10);
       if (!isNaN(pid)) {
         try {
           process.kill(pid, 0);
@@ -249,17 +269,33 @@ async function startDaemonFromSource(
     delete env.QDRANT_URL;
   }
 
-  const daemonLogFd = openLogFile("hatch.log");
-  const child = spawn("bun", ["run", daemonMainPath], {
-    detached: true,
-    stdio: ["ignore", "pipe", "pipe"],
-    env,
-  });
-  pipeToLogFile(child, daemonLogFd, "daemon");
-  child.unref();
+  // Write a sentinel PID file before spawning so concurrent hatch() calls
+  // detect the in-progress spawn and wait instead of racing.
+  writeFileSync(pidFile, "starting", "utf-8");
+
+  const child = foreground
+    ? spawn("bun", ["run", daemonMainPath], {
+        stdio: "inherit",
+        env,
+      })
+    : (() => {
+        const daemonLogFd = openLogFile("hatch.log");
+        const c = spawn("bun", ["run", daemonMainPath], {
+          detached: true,
+          stdio: ["ignore", "pipe", "pipe"],
+          env,
+        });
+        pipeToLogFile(c, daemonLogFd, "daemon");
+        c.unref();
+        return c;
+      })();
 
   if (child.pid) {
     writeFileSync(pidFile, String(child.pid), "utf-8");
+  } else {
+    try {
+      unlinkSync(pidFile);
+    } catch {}
   }
 }
 
@@ -284,7 +320,25 @@ async function startDaemonWatchFromSource(
   // If a daemon is already running, skip spawning a new one.
   if (existsSync(pidFile)) {
     try {
-      const pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+      const content = readFileSync(pidFile, "utf-8").trim();
+
+      // Another caller is already spawning the daemon — wait for it
+      // instead of racing to spawn a duplicate.
+      if (content === "starting") {
+        console.log(
+          "   Assistant is starting — waiting for it to become ready...",
+        );
+        if (await waitForDaemonReady(resources.daemonPort, 60000)) {
+          console.log("   Assistant is ready\n");
+          return;
+        }
+        // The other spawn may have failed; clean up and proceed to spawn.
+        try {
+          unlinkSync(pidFile);
+        } catch {}
+      }
+
+      const pid = parseInt(content, 10);
       if (!isNaN(pid)) {
         try {
           process.kill(pid, 0); // Check if alive
@@ -328,6 +382,10 @@ async function startDaemonWatchFromSource(
     delete env.QDRANT_URL;
   }
 
+  // Write a sentinel PID file before spawning so concurrent hatch() calls
+  // detect the in-progress spawn and wait instead of racing.
+  writeFileSync(pidFile, "starting", "utf-8");
+
   const daemonLogFd = openLogFile("hatch.log");
   const child = spawn("bun", ["--watch", "run", mainPath], {
     detached: true,
@@ -338,8 +396,13 @@ async function startDaemonWatchFromSource(
   child.unref();
   const daemonPid = child.pid;
 
+  // Overwrite sentinel with real PID, or clean up on spawn failure.
   if (daemonPid) {
     writeFileSync(pidFile, String(daemonPid), "utf-8");
+  } else {
+    try {
+      unlinkSync(pidFile);
+    } catch {}
   }
 
   console.log("   Assistant started in watch mode (bun --watch)");
@@ -716,19 +779,39 @@ export function getLocalLanIPv4(): string | undefined {
 }
 
 /**
- * Check whether watch-mode startup is possible. Watch mode requires source
- * files (bun --watch only works with .ts sources, not compiled binaries).
- * Returns true when assistant source can be resolved, false otherwise.
+ * Check whether watch-mode startup is possible for the assistant daemon.
+ * Watch mode requires source files (bun --watch only works with .ts sources,
+ * not compiled binaries). Returns true when assistant source can be resolved,
+ * false otherwise.
  *
  * Use this before stopping a running assistant for a watch-mode restart — if
  * watch mode isn't available (e.g. packaged desktop app without source), the
  * caller should keep the existing process alive rather than killing it and
  * failing.
  */
-export function isWatchModeAvailable(): boolean {
+export function isAssistantWatchModeAvailable(): boolean {
   return resolveAssistantIndexPath() !== undefined;
 }
 
+/**
+ * Check whether watch-mode startup is possible for the gateway. Watch mode
+ * requires gateway source files (bun --watch only works with .ts sources).
+ * Returns true when the gateway source directory can be resolved, false
+ * otherwise.
+ *
+ * Use this before stopping a running gateway for a watch-mode restart — if
+ * watch mode isn't available, the caller should keep the existing process
+ * alive rather than killing it and failing.
+ */
+export function isGatewayWatchModeAvailable(): boolean {
+  try {
+    resolveGatewayDir();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // NOTE: startLocalDaemon() is the CLI-side daemon lifecycle manager.
 // It should eventually converge with
 // assistant/src/daemon/daemon-control.ts::startDaemon which is the
@@ -736,7 +819,9 @@ export function isWatchModeAvailable(): boolean {
 export async function startLocalDaemon(
   watch: boolean = false,
   resources: LocalInstanceResources,
+  options?: { foreground?: boolean },
 ): Promise<void> {
+  const foreground = options?.foreground ?? false;
   // Check for a compiled daemon binary adjacent to the CLI executable.
   // This covers both the desktop app (VELLUM_DESKTOP_APP) and the case where
   // the user runs the compiled CLI directly from the terminal (e.g. via a
@@ -754,7 +839,26 @@ export async function startLocalDaemon(
     let daemonAlive = false;
     if (existsSync(pidFile)) {
       try {
-        const pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+        const content = readFileSync(pidFile, "utf-8").trim();
+
+        // Another caller is already spawning the daemon — wait for it
+        // instead of racing to spawn a duplicate.
+        if (content === "starting") {
+          console.log(
+            "   Assistant is starting — waiting for it to become ready...",
+          );
+          if (await waitForDaemonReady(resources.daemonPort, 60000)) {
+            console.log("   Assistant is ready\n");
+            ensureBunInstalled();
+            return;
+          }
+          // The other spawn may have failed; clean up and proceed to spawn.
+          try {
+            unlinkSync(pidFile);
+          } catch {}
+        }
+
+        const pid = parseInt(content, 10);
         if (!isNaN(pid)) {
           try {
             process.kill(pid, 0); // Check if alive
@@ -820,6 +924,7 @@ export async function startLocalDaemon(
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
         "BASE_DATA_DIR",
+        "PLATFORM_BASE_URL",
         "QDRANT_HTTP_PORT",
         "QDRANT_URL",
         "RUNTIME_HTTP_PORT",
@@ -827,6 +932,7 @@ export async function startLocalDaemon(
         "TMPDIR",
         "USER",
         "LANG",
+        "VELLUM_DEBUG",
       ]) {
         if (process.env[key]) {
           daemonEnv[key] = process.env[key]!;
@@ -842,21 +948,38 @@ export async function startLocalDaemon(
         delete daemonEnv.QDRANT_URL;
       }
 
-      const daemonLogFd = openLogFile("hatch.log");
-      const child = spawn(daemonBinary, [], {
-        cwd: dirname(daemonBinary),
-        detached: true,
-        stdio: ["ignore", "pipe", "pipe"],
-        env: daemonEnv,
-      });
-      pipeToLogFile(child, daemonLogFd, "daemon");
-      child.unref();
+      // Write a sentinel PID file before spawning so concurrent hatch() calls
+      // see the file and fall through to the isDaemonResponsive() port check
+      // instead of racing to spawn a duplicate daemon.
+      writeFileSync(pidFile, "starting", "utf-8");
+
+      const child = foreground
+        ? spawn(daemonBinary, [], {
+            cwd: dirname(daemonBinary),
+            stdio: "inherit",
+            env: daemonEnv,
+          })
+        : (() => {
+            const daemonLogFd = openLogFile("hatch.log");
+            const c = spawn(daemonBinary, [], {
+              cwd: dirname(daemonBinary),
+              detached: true,
+              stdio: ["ignore", "pipe", "pipe"],
+              env: daemonEnv,
+            });
+            pipeToLogFile(c, daemonLogFd, "daemon");
+            c.unref();
+            return c;
+          })();
       const daemonPid = child.pid;
 
-      // Write PID file immediately so the health monitor can find the process
-      // and concurrent hatch() calls see it as alive.
+      // Overwrite sentinel with real PID, or clean up on spawn failure.
       if (daemonPid) {
         writeFileSync(pidFile, String(daemonPid), "utf-8");
+      } else {
+        try {
+          unlinkSync(pidFile);
+        } catch {}
       }
     }
 
@@ -919,7 +1042,7 @@ export async function startLocalDaemon(
         );
       }
     } else {
-      await startDaemonFromSource(assistantIndex, resources);
+      await startDaemonFromSource(assistantIndex, resources, { foreground });
 
       const daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       if (daemonReady) {

package/src/lib/platform-client.ts

@@ -55,6 +55,30 @@ export interface PlatformUser {
   display: string;
 }
 
+interface OrganizationListResponse {
+  results: { id: string; name: string }[];
+}
+
+export async function fetchOrganizationId(token: string): Promise<string> {
+  const url = `${getPlatformUrl()}/v1/organizations/`;
+  const response = await fetch(url, {
+    headers: { "X-Session-Token": token },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch organizations (${response.status}). Try logging in again.`,
+    );
+  }
+
+  const body = (await response.json()) as OrganizationListResponse;
+  const orgId = body.results?.[0]?.id;
+  if (!orgId) {
+    throw new Error("No organization found for this account.");
+  }
+  return orgId;
+}
+
 interface AllauthSessionResponse {
   status: number;
   data: {

package/src/lib/process.ts

@@ -13,7 +13,7 @@ function isVellumProcess(pid: number): boolean {
       timeout: 3000,
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
-    return /vellum-daemon|vellum-cli|vellum-gateway|@vellumai|\/vellum\/|\/daemon\/main/.test(
+    return /vellum-daemon|vellum-cli|vellum-gateway|@vellumai|\/\.?vellum\/|\/daemon\/main|\/\.vellum\/.*qdrant\/bin\/qdrant/.test(
       output,
     );
   } catch {

package/src/lib/random-name.ts

@@ -1,3 +1,7 @@
+import { customAlphabet } from "nanoid";
+
+const nanoidLower = customAlphabet("abcdefghijklmnopqrstuvwxyz0123456789", 6);
+
 const ADJECTIVES = [
   "brave",
   "calm",
@@ -129,5 +133,17 @@ function randomElement<T>(arr: T[]): T {
 }
 
 export function generateRandomSuffix(): string {
-  return `${randomElement(ADJECTIVES)}-${randomElement(NOUNS)}`;
+  return `${randomElement(ADJECTIVES)}-${randomElement(NOUNS)}-${nanoidLower()}`;
+}
+
+/**
+ * Generate an instance name for a new assistant. Uses the explicit name if
+ * provided, otherwise produces `<species>-<adjective>-<noun>-<nanoid>`.
+ */
+export function generateInstanceName(
+  species: string,
+  explicitName?: string | null,
+): string {
+  if (explicitName) return explicitName;
+  return `${species}-${generateRandomSuffix()}`;
 }