@vellumai/cli 0.4.55 → 0.4.57

package/src/commands/hatch.ts

@@ -1,4 +1,3 @@
-import { createHash, randomBytes, randomUUID } from "crypto";
 import {
   appendFileSync,
   existsSync,
@@ -6,16 +5,14 @@ import {
   mkdirSync,
   readFileSync,
   readlinkSync,
+  rmSync,
   symlinkSync,
   unlinkSync,
   writeFileSync,
 } from "fs";
-import { homedir, hostname, userInfo } from "os";
+import { homedir } from "os";
 import { join } from "path";
 
-import QRCode from "qrcode";
-import qrcode from "qrcode-terminal";
-
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
 import cliPkg from "../../package.json";
 
@@ -40,7 +37,6 @@ import {
 } from "../lib/constants";
 import type { RemoteHost, Species } from "../lib/constants";
 import { hatchDocker } from "../lib/docker";
-import { mintLocalBearerToken } from "../lib/jwt";
 import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import {
@@ -49,9 +45,10 @@ import {
   stopLocalProcesses,
 } from "../lib/local";
 import { maybeStartNgrokTunnel } from "../lib/ngrok";
+import { httpHealthCheck } from "../lib/http-client";
 import { detectOrphanedProcesses } from "../lib/orphan-detection";
 import { isProcessAlive, stopProcess } from "../lib/process";
-import { generateRandomSuffix } from "../lib/random-name";
+import { generateInstanceName } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
 import { archiveLogFile, resetLogFile } from "../lib/xdg-log";
 
@@ -97,14 +94,12 @@ chown -R "$SSH_USER:$SSH_USER" "$SSH_USER_HOME" 2>/dev/null || true
 
 export async function buildStartupScript(
   species: Species,
-  bearerToken: string,
   sshUser: string,
   anthropicApiKey: string,
   instanceName: string,
   cloud: RemoteHost,
 ): Promise<string> {
-  const platformUrl =
-    process.env.VELLUM_PLATFORM_URL ?? "https://assistant.vellum.ai";
+  const platformUrl = process.env.VELLUM_PLATFORM_URL ?? "https://vellum.ai";
   const logPath =
     cloud === "custom"
       ? "/tmp/vellum-startup.log"
@@ -117,7 +112,6 @@ export async function buildStartupScript(
 
   if (species === "openclaw") {
     return await buildOpenclawStartupScript(
-      bearerToken,
       sshUser,
       anthropicApiKey,
       timestampRedirect,
@@ -389,7 +383,7 @@ export async function watchHatching(
         );
         console.log(`   Monitor with: vel logs ${instanceName}`);
         console.log("");
-        resolve({ success: true, errorContent: lastErrorContent });
+        resolve({ success: false, errorContent: lastErrorContent });
         return;
       }
 
@@ -434,7 +428,7 @@ function watchHatchingDesktop(
           `Timed out after ${formatElapsed(elapsed)}. Instance is still running.`,
         );
         desktopLog(`Monitor with: vel logs ${instanceName}`);
-        resolve({ success: true, errorContent: lastErrorContent });
+        resolve({ success: false, errorContent: lastErrorContent });
         return;
       }
 
@@ -567,121 +561,6 @@ function installCLISymlink(): void {
   );
 }
 
-async function waitForDaemonReady(
-  runtimeUrl: string,
-  bearerToken: string | undefined,
-  timeoutMs = 15000,
-): Promise<boolean> {
-  const start = Date.now();
-  const pollInterval = 1000;
-  while (Date.now() - start < timeoutMs) {
-    try {
-      const res = await fetch(`${runtimeUrl}/v1/health`, {
-        method: "GET",
-        headers: bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {},
-        signal: AbortSignal.timeout(2000),
-      });
-      if (res.ok) return true;
-    } catch {
-      // Daemon not ready yet
-    }
-    await new Promise((r) => setTimeout(r, pollInterval));
-  }
-  return false;
-}
-
-async function displayPairingQRCode(
-  runtimeUrl: string,
-  bearerToken: string | undefined,
-  /** External gateway URL for the QR payload. When omitted, runtimeUrl is used. */
-  externalGatewayUrl?: string,
-): Promise<void> {
-  try {
-    const pairingRequestId = randomUUID();
-    const pairingSecret = randomBytes(32).toString("hex");
-
-    // The daemon's HTTP server may not be fully ready even though the gateway
-    // health check passed (the gateway is up, but the upstream daemon HTTP
-    // endpoint it proxies to may still be initializing). Poll the daemon's
-    // health endpoint through the gateway to ensure it's reachable.
-    const daemonReady = await waitForDaemonReady(runtimeUrl, bearerToken);
-    if (!daemonReady) {
-      console.warn(
-        "⚠ Assistant health check did not pass within 15s. Run `vellum pair` to try again.\n",
-      );
-      return;
-    }
-
-    const registerRes = await fetch(`${runtimeUrl}/pairing/register`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
-      },
-      body: JSON.stringify({
-        pairingRequestId,
-        pairingSecret,
-        gatewayUrl: externalGatewayUrl ?? runtimeUrl,
-      }),
-    });
-
-    if (!registerRes.ok) {
-      const body = await registerRes.text().catch(() => "");
-      console.warn(
-        `⚠ Could not register pairing request: ${registerRes.status} ${registerRes.statusText}${body ? ` — ${body}` : ""}. Run \`vellum pair\` to try again.\n`,
-      );
-      return;
-    }
-
-    const hostId = createHash("sha256")
-      .update(hostname() + userInfo().username)
-      .digest("hex");
-    const payload = JSON.stringify({
-      type: "vellum-daemon",
-      v: 4,
-      id: hostId,
-      g: externalGatewayUrl ?? runtimeUrl,
-      pairingRequestId,
-      pairingSecret,
-    });
-
-    const qrString = await new Promise<string>((resolve) => {
-      qrcode.generate(payload, { small: true }, (code: string) => {
-        resolve(code);
-      });
-    });
-
-    // Save QR code as PNG to a well-known location so it can be retrieved
-    // (e.g. via SCP) for pairing through the Desktop app.
-    const qrDir = join(homedir(), ".vellum", "pairing-qr");
-    mkdirSync(qrDir, { recursive: true });
-    const qrPngPath = join(qrDir, "initial.png");
-    try {
-      const pngBuffer = await QRCode.toBuffer(payload, {
-        type: "png",
-        width: 512,
-      });
-      writeFileSync(qrPngPath, pngBuffer);
-      console.log(`QR code PNG saved to ${qrPngPath}\n`);
-    } catch (pngErr) {
-      const pngReason =
-        pngErr instanceof Error ? pngErr.message : String(pngErr);
-      console.warn(`\u26A0 Could not save QR code PNG: ${pngReason}\n`);
-    }
-
-    console.log("Scan this QR code with the Vellum iOS app to pair:\n");
-    console.log(qrString);
-    console.log("This pairing request expires in 5 minutes.");
-    console.log("Run `vellum pair` to generate a new one.\n");
-  } catch (err) {
-    // Non-fatal — pairing is optional
-    const reason = err instanceof Error ? err.message : String(err);
-    console.warn(
-      `⚠ Could not generate pairing QR code: ${reason}. Run \`vellum pair\` to try again.\n`,
-    );
-  }
-}
-
 async function hatchLocal(
   species: Species,
   name: string | null,
@@ -697,13 +576,15 @@ async function hatchLocal(
     process.exit(1);
   }
 
-  const instanceName =
-    name ??
-    process.env.VELLUM_ASSISTANT_NAME ??
-    `${species}-${generateRandomSuffix()}`;
+  const instanceName = generateInstanceName(
+    species,
+    name ?? process.env.VELLUM_ASSISTANT_NAME,
+  );
 
   // Clean up stale local state: if daemon/gateway processes are running but
-  // the lock file has no entries, stop them before starting fresh.
+  // the lock file has no entries AND the daemon is not healthy, stop them
+  // before starting fresh. A healthy daemon should be reused, not killed —
+  // it may have been started intentionally via `vellum wake`.
   const vellumDir = join(homedir(), ".vellum");
   const existingAssistants = loadAllAssistants();
   const localAssistants = existingAssistants.filter((a) => a.cloud === "local");
@@ -711,10 +592,16 @@ async function hatchLocal(
     const daemonPid = isProcessAlive(join(vellumDir, "vellum.pid"));
     const gatewayPid = isProcessAlive(join(vellumDir, "gateway.pid"));
     if (daemonPid.alive || gatewayPid.alive) {
-      console.log(
-        "🧹 Cleaning up stale local processes (no lock file entry)...\n",
-      );
-      await stopLocalProcesses();
+      // Check if the daemon is actually healthy before killing it.
+      // Default port 7821 is used when there's no lockfile entry.
+      const defaultPort = parseInt(process.env.RUNTIME_HTTP_PORT || "7821", 10);
+      const healthy = await httpHealthCheck(defaultPort);
+      if (!healthy) {
+        console.log(
+          "🧹 Cleaning up stale local processes (no lock file entry)...\n",
+        );
+        await stopLocalProcesses();
+      }
     }
   }
 
@@ -722,17 +609,32 @@ async function hatchLocal(
   // are not tracked by any PID file or lock file entry and kill them before
   // starting new ones. This prevents resource leaks when the desktop app
   // crashes or is force-quit without a clean shutdown.
+  //
+  // Skip orphan cleanup if the daemon is already healthy on the expected port
+  // — those processes are intentional (e.g. started via `vellum wake`) and
+  // startLocalDaemon() will reuse them.
   if (IS_DESKTOP) {
-    const orphans = await detectOrphanedProcesses();
-    if (orphans.length > 0) {
-      desktopLog(
-        `🧹 Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"} — cleaning up...`,
-      );
-      for (const orphan of orphans) {
-        await stopProcess(
-          parseInt(orphan.pid, 10),
-          `${orphan.name} (PID ${orphan.pid})`,
+    const existingResources = findAssistantByName(instanceName);
+    const expectedPort =
+      existingResources?.cloud === "local" && existingResources.resources
+        ? existingResources.resources.daemonPort
+        : undefined;
+    const daemonAlreadyHealthy = expectedPort
+      ? await httpHealthCheck(expectedPort)
+      : false;
+
+    if (!daemonAlreadyHealthy) {
+      const orphans = await detectOrphanedProcesses();
+      if (orphans.length > 0) {
+        desktopLog(
+          `🧹 Found ${orphans.length} orphaned process${orphans.length === 1 ? "" : "es"} — cleaning up...`,
         );
+        for (const orphan of orphans) {
+          await stopProcess(
+            parseInt(orphan.pid, 10),
+            `${orphan.name} (PID ${orphan.pid})`,
+          );
+        }
       }
     }
   }
@@ -747,6 +649,38 @@ async function hatchLocal(
     resources = await allocateLocalResources(instanceName);
   }
 
+  // Clean up stale workspace data: if the workspace directory already exists for
+  // this instance but no local lockfile entry owns it, a previous retire failed
+  // to archive it (or a managed-only retire left local data behind). Remove the
+  // workspace subtree so the new assistant starts fresh — but preserve the rest
+  // of .vellum (e.g. protected/, credentials) which may be shared.
+  if (
+    !existingEntry ||
+    (existingEntry.cloud != null && existingEntry.cloud !== "local")
+  ) {
+    const instanceWorkspaceDir = join(
+      resources.instanceDir,
+      ".vellum",
+      "workspace",
+    );
+    if (existsSync(instanceWorkspaceDir)) {
+      const ownedByOther = loadAllAssistants().some((a) => {
+        if ((a.cloud != null && a.cloud !== "local") || !a.resources)
+          return false;
+        return (
+          join(a.resources.instanceDir, ".vellum", "workspace") ===
+          instanceWorkspaceDir
+        );
+      });
+      if (!ownedByOther) {
+        console.log(
+          `🧹 Removing stale workspace at ${instanceWorkspaceDir} (not owned by any assistant)...\n`,
+        );
+        rmSync(instanceWorkspaceDir, { recursive: true, force: true });
+      }
+    }
+  }
+
   const logsDir = join(
     resources.instanceDir,
     ".vellum",
@@ -795,15 +729,10 @@ async function hatchLocal(
     delete process.env.BASE_DATA_DIR;
   }
 
-  // Mint a JWT from the signing key so the CLI can authenticate with the
-  // daemon/gateway (which requires auth by default).
-  const bearerToken = mintLocalBearerToken(resources.instanceDir);
-
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
     localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
-    bearerToken,
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
@@ -825,12 +754,6 @@ async function hatchLocal(
     console.log(`  Name: ${instanceName}`);
     console.log(`  Runtime: ${runtimeUrl}`);
     console.log("");
-
-    // Use loopback for HTTP calls (health check + pairing register) since
-    // mDNS hostnames may not resolve on the local machine, but keep the
-    // external runtimeUrl in the QR payload so iOS devices can reach it.
-    const localGatewayUrl = `http://127.0.0.1:${resources.gatewayPort}`;
-    await displayPairingQRCode(localGatewayUrl, bearerToken, runtimeUrl);
   }
 
   if (keepAlive) {

package/src/commands/pair.ts

@@ -7,7 +7,9 @@ import { PNG } from "pngjs";
 import { saveAssistantEntry } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import type { Species } from "../lib/constants";
-import { generateRandomSuffix } from "../lib/random-name";
+import { saveGuardianToken } from "../lib/guardian-token";
+import type { GuardianTokenData } from "../lib/guardian-token";
+import { generateInstanceName } from "../lib/random-name";
 
 interface QRPairingPayload {
   type: string;
@@ -119,7 +121,7 @@ export async function pair(): Promise<void> {
       throw new Error("QR code does not contain valid Vellum pairing data.");
     }
 
-    const instanceName = `${species}-${generateRandomSuffix()}`;
+    const instanceName = generateInstanceName(species);
     const runtimeUrl = payload.g;
     const deviceId = getDeviceId();
     const deviceName = hostname();
@@ -168,13 +170,27 @@ export async function pair(): Promise<void> {
     const customEntry: AssistantEntry = {
       assistantId: instanceName,
       runtimeUrl,
-      bearerToken,
       cloud: "custom",
       species,
       hatchedAt: new Date().toISOString(),
     };
     saveAssistantEntry(customEntry);
 
+    if (bearerToken) {
+      const tokenData: GuardianTokenData = {
+        guardianPrincipalId: "",
+        accessToken: bearerToken,
+        accessTokenExpiresAt: "",
+        refreshToken: "",
+        refreshTokenExpiresAt: "",
+        refreshAfter: "",
+        isNew: true,
+        deviceId: getDeviceId(),
+        leasedAt: new Date().toISOString(),
+      };
+      saveGuardianToken(instanceName, tokenData);
+    }
+
     console.log("");
     console.log("Successfully paired with remote assistant!");
     console.log("Instance details:");

package/src/commands/ps.ts

@@ -6,7 +6,9 @@ import {
   loadAllAssistants,
   type AssistantEntry,
 } from "../lib/assistant-config";
+import { loadGuardianToken } from "../lib/guardian-token";
 import { checkHealth, checkManagedHealth } from "../lib/health-check";
+import { dockerResourceNames } from "../lib/docker";
 import {
   classifyProcess,
   detectOrphanedProcesses,
@@ -248,6 +250,73 @@ async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
   }));
 }
 
+async function getDockerContainerState(
+  containerName: string,
+): Promise<string | null> {
+  try {
+    const output = await execOutput("docker", [
+      "inspect",
+      "--format",
+      "{{.State.Status}}",
+      containerName,
+    ]);
+    return output.trim() || "unknown";
+  } catch {
+    return null;
+  }
+}
+
+function isLocalProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function getDockerProcesses(entry: AssistantEntry): Promise<TableRow[]> {
+  const res = dockerResourceNames(entry.assistantId);
+
+  const containers: { name: string; containerName: string }[] = [
+    { name: "assistant", containerName: res.assistantContainer },
+    { name: "gateway", containerName: res.gatewayContainer },
+    { name: "credential-executor", containerName: res.cesContainer },
+  ];
+
+  const results = await Promise.all(
+    containers.map(async ({ name, containerName }) => {
+      const state = await getDockerContainerState(containerName);
+      if (!state) {
+        return {
+          name,
+          status: withStatusEmoji("not found"),
+          info: `container ${containerName}`,
+        };
+      }
+      return {
+        name,
+        status: withStatusEmoji(state === "running" ? "running" : state),
+        info: `container ${containerName}`,
+      };
+    }),
+  );
+
+  // Show the file watcher process if the instance was hatched with --watch.
+  const watcherPid =
+    typeof entry.watcherPid === "number" ? entry.watcherPid : null;
+  if (watcherPid !== null) {
+    const alive = isLocalProcessAlive(watcherPid);
+    results.push({
+      name: "file-watcher",
+      status: withStatusEmoji(alive ? "running" : "not running"),
+      info: alive ? `PID ${watcherPid}` : "not detected",
+    });
+  }
+
+  return results;
+}
+
 async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   const cloud = resolveCloud(entry);
 
@@ -259,6 +328,12 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
     return;
   }
 
+  if (cloud === "docker") {
+    const rows = await getDockerProcesses(entry);
+    printTable(rows);
+    return;
+  }
+
   let output: string;
   try {
     if (cloud === "gcp") {
@@ -357,12 +432,23 @@ async function listAllAssistants(): Promise<void> {
         if (!alive) {
           health = { status: "sleeping", detail: null };
         } else {
-          health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+          const token = loadGuardianToken(a.assistantId)?.accessToken;
+          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
+        }
+      } else if (a.cloud === "docker") {
+        const res = dockerResourceNames(a.assistantId);
+        const state = await getDockerContainerState(res.assistantContainer);
+        if (!state || state !== "running") {
+          health = { status: "sleeping", detail: null };
+        } else {
+          const token = loadGuardianToken(a.assistantId)?.accessToken;
+          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
         }
       } else if (a.cloud === "vellum") {
         health = await checkManagedHealth(a.runtimeUrl, a.assistantId);
       } else {
-        health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+        const token = loadGuardianToken(a.assistantId)?.accessToken;
+        health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
       }
 
       const infoParts = [a.runtimeUrl];

package/src/commands/retire.ts

@@ -9,7 +9,11 @@ import {
   removeAssistantEntry,
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
-import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
+import {
+  fetchOrganizationId,
+  getPlatformUrl,
+  readPlatformToken,
+} from "../lib/platform-client";
 import { retireInstance as retireAwsInstance } from "../lib/aws";
 import { retireDocker } from "../lib/docker";
 import { retireInstance as retireGcpInstance } from "../lib/gcp";
@@ -84,6 +88,21 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
 
+  // Stop Qdrant — the daemon's graceful shutdown tries to stop it via
+  // qdrantManager.stop(), but if the daemon was SIGKILL'd (after 2s timeout)
+  // Qdrant may still be running as an orphan. Check both the current PID file
+  // location and the legacy location.
+  const qdrantPidFile = join(
+    vellumDir,
+    "workspace",
+    "data",
+    "qdrant",
+    "qdrant.pid",
+  );
+  const qdrantLegacyPidFile = join(vellumDir, "qdrant.pid");
+  await stopProcessByPidFile(qdrantPidFile, "qdrant", undefined, 5000);
+  await stopProcessByPidFile(qdrantLegacyPidFile, "qdrant", undefined, 5000);
+
   // If the PID file didn't track a running daemon, scan for orphaned
   // daemon processes that may have been started without writing a PID.
   if (!daemonStopped) {
@@ -116,12 +135,12 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
   try {
     renameSync(dirToArchive, stagingDir);
   } catch (err) {
-    console.warn(
-      `⚠️  Failed to move ${dirToArchive}: ${err instanceof Error ? err.message : err}`,
+    // Re-throw so the caller (and the desktop app) knows the archive failed.
+    // If the rename fails, old workspace data stays in place and a subsequent
+    // hatch would inherit stale SOUL.md, IDENTITY.md, and memories.
+    throw new Error(
+      `Failed to archive ${dirToArchive}: ${err instanceof Error ? err.message : err}`,
     );
-    console.warn("Skipping archive.");
-    console.log("\u2705 Local instance retired.");
-    return;
   }
 
   writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
@@ -189,10 +208,15 @@ async function retireVellum(assistantId: string): Promise<void> {
     process.exit(1);
   }
 
+  const orgId = await fetchOrganizationId(token);
+
   const url = `${getPlatformUrl()}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
   const response = await fetch(url, {
     method: "DELETE",
-    headers: { "X-Session-Token": token },
+    headers: {
+      "X-Session-Token": token,
+      "Vellum-Organization-Id": orgId,
+    },
   });
 
   if (!response.ok) {