@vellumai/cli 0.8.7 → 0.8.8

package/src/lib/confirm-action.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared interactive confirmation for destructive CLI commands (retire, unpair,
+ * …). Per cli/AGENTS.md, a command that removes assistant state must print the
+ * resolved identity and require confirmation, with a `--yes` bypass for
+ * automation.
+ */
+
+/** True only when we can run an interactive raw-mode confirmation prompt. */
+export function canPromptForConfirmation(): boolean {
+  return (
+    process.stdin.isTTY === true &&
+    process.stdout.isTTY === true &&
+    typeof process.stdin.setRawMode === "function"
+  );
+}
+
+/**
+ * Show `prompt` and resolve true on Enter, false on Esc/q/Ctrl-C. Restores the
+ * prior stdin raw/paused state on exit. Caller must gate on
+ * {@link canPromptForConfirmation} first.
+ */
+export async function confirmAction(prompt: string): Promise<boolean> {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  const wasRaw = stdin.isRaw === true;
+  const wasPaused = stdin.isPaused();
+
+  stdout.write(prompt);
+  stdin.setRawMode(true);
+  stdin.resume();
+
+  return await new Promise<boolean>((resolve) => {
+    const cleanup = () => {
+      stdin.off("data", onData);
+      stdin.setRawMode(wasRaw);
+      if (wasPaused) {
+        stdin.pause();
+      }
+      stdout.write("\n");
+    };
+
+    const onData = (chunk: Buffer) => {
+      const byte = chunk[0];
+      if (byte === 13 || byte === 10) {
+        cleanup();
+        resolve(true);
+        return;
+      }
+      if (byte === 27 || byte === 3 || byte === 113 || byte === 81) {
+        cleanup();
+        resolve(false);
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}

package/src/lib/docker.ts

@@ -478,6 +478,17 @@ export async function retireDocker(name: string): Promise<void> {
     }
   }
 
+  // Future: consider stopping Colima VM when no Docker instances remain.
+  // Considerations:
+  // - Use loadAllAssistantsAcrossEnvs() instead of loadAllAssistants() to
+  //   avoid stopping Colima while another VELLUM_ENVIRONMENT still has a
+  //   running Docker instance.
+  // - Track whether Vellum started Colima (vs. the user already had it
+  //   running for non-Vellum workloads) \u2014 e.g. via a dedicated Colima
+  //   profile (`colima start --profile vellum`) or a sentinel file.
+  // - Only stop if both conditions are met: no cross-env Docker instances
+  //   AND Vellum owns the Colima lifecycle.
+
   console.log(`\u2705 Docker instance retired.`);
 }
 
@@ -1137,7 +1148,20 @@ export async function hatchDocker(
           await loadImageViaHost(HOST_IMAGE_LOADER_URL, ref, log);
         } else {
           log(`   ↪ pulling ${ref}`);
-          await exec("docker", ["pull", ref]);
+          const MAX_PULL_RETRIES = 3;
+          for (let attempt = 1; attempt <= MAX_PULL_RETRIES; attempt++) {
+            try {
+              await exec("docker", ["pull", ref]);
+              break;
+            } catch (err) {
+              if (attempt === MAX_PULL_RETRIES) throw err;
+              const delaySec = 2 ** attempt;
+              log(
+                `   ⚠ pull failed (attempt ${attempt}/${MAX_PULL_RETRIES}), retrying in ${delaySec}s...`,
+              );
+              await new Promise((r) => setTimeout(r, delaySec * 1000));
+            }
+          }
         }
       }
       log("✅ Docker images acquired");

package/src/lib/environments/resolve.ts

@@ -1,48 +1,27 @@
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-  writeFileSync,
-} from "fs";
-import { homedir } from "os";
-import { dirname, join } from "path";
+import { mkdirSync, unlinkSync, writeFileSync } from "fs";
+import { dirname } from "path";
 
 import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+import {
+  defaultEnvironmentFilePath,
+  readDefaultEnvironment as readPersistedDefaultEnvironment,
+} from "@vellumai/local-mode";
 
 const DEFAULT_ENVIRONMENT_NAME = "production";
 
-/**
- * Path to the user's persisted default environment file.
- * Lives at `~/.config/vellum/environment` — a fixed, environment-agnostic
- * location so it can be read before the environment is resolved.
- */
-function getDefaultEnvironmentPath(): string {
-  const xdgConfig =
-    process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-  return join(xdgConfig, "vellum", "environment");
-}
-
 /**
  * Read the persisted default environment name, if any.
  * Returns `undefined` if no file exists or the file is empty.
  */
 export function readDefaultEnvironment(): string | undefined {
-  const filePath = getDefaultEnvironmentPath();
-  try {
-    if (!existsSync(filePath)) return undefined;
-    const content = readFileSync(filePath, "utf-8").trim();
-    return content.length > 0 ? content : undefined;
-  } catch {
-    return undefined;
-  }
+  return readPersistedDefaultEnvironment(process.env);
 }
 
 /**
  * Persist a default environment name to the user config file.
  */
 export function writeDefaultEnvironment(name: string): void {
-  const filePath = getDefaultEnvironmentPath();
+  const filePath = defaultEnvironmentFilePath(process.env);
   mkdirSync(dirname(filePath), { recursive: true });
   writeFileSync(filePath, name + "\n", "utf-8");
 }
@@ -51,7 +30,7 @@ export function writeDefaultEnvironment(name: string): void {
  * Remove the persisted default environment file, falling back to production.
  */
 export function clearDefaultEnvironment(): void {
-  const filePath = getDefaultEnvironmentPath();
+  const filePath = defaultEnvironmentFilePath(process.env);
   try {
     unlinkSync(filePath);
   } catch {

package/src/lib/guardian-token.ts

@@ -2,11 +2,16 @@ import { createHash, randomUUID } from "node:crypto";
 import { execSync } from "node:child_process";
 import {
   chmodSync,
+  closeSync,
   existsSync,
   mkdirSync,
+  openSync,
   readFileSync,
+  rmdirSync,
   statSync,
+  unlinkSync,
   writeFileSync,
+  writeSync,
 } from "fs";
 import { platform } from "os";
 import { dirname, join } from "path";
@@ -41,6 +46,27 @@ function getGuardianTokenPath(assistantId: string): string {
   );
 }
 
+/**
+ * Best-effort removal of an assistant's stored guardian token (used by
+ * `vellum unpair` to forget a paired connection). Never throws if the token
+ * file or its per-assistant directory is already absent.
+ */
+export function deleteGuardianToken(assistantId: string): void {
+  const tokenPath = getGuardianTokenPath(assistantId);
+  try {
+    unlinkSync(tokenPath);
+  } catch {
+    /* already gone */
+  }
+  // Clean up the now-empty per-assistant directory; rmdir throws if it still
+  // holds other files, in which case we leave it.
+  try {
+    rmdirSync(dirname(tokenPath));
+  } catch {
+    /* not empty or absent */
+  }
+}
+
 function getPersistedDeviceIdPath(): string {
   return join(getConfigDir(getCurrentEnvironment()), "device-id");
 }
@@ -161,33 +187,121 @@ export function saveGuardianToken(
   chmodSync(tokenPath, 0o600);
 }
 
+/** Abort the refresh POST if the gateway is slow/unreachable (it's now on the
+ *  hot request path, so it must never hang indefinitely). */
+const REFRESH_FETCH_TIMEOUT_MS = 15_000;
+/** Max time to wait for the per-assistant refresh lock before proceeding. */
+const REFRESH_LOCK_WAIT_MS = 10_000;
+/** A lock older than this is treated as stale (holder crashed) and stolen. */
+const REFRESH_LOCK_STALE_MS = 30_000;
+const REFRESH_LOCK_POLL_MS = 100;
+
+function getRefreshLockPath(assistantId: string): string {
+  return join(dirname(getGuardianTokenPath(assistantId)), "refresh.lock");
+}
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Best-effort exclusive cross-process lock for a per-assistant token refresh.
+ * Created atomically with `wx`; a stale lock (crashed holder) is stolen.
+ * Returns true if acquired, false if it timed out (caller proceeds degraded).
+ */
+async function acquireRefreshLock(lockPath: string): Promise<boolean> {
+  mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + REFRESH_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lockPath, "wx", 0o600);
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      return true;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") return false;
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > REFRESH_LOCK_STALE_MS) {
+          unlinkSync(lockPath); // steal a stale lock, then retry
+          continue;
+        }
+      } catch {
+        continue; // lock vanished between open and stat — retry
+      }
+      if (Date.now() >= deadline) return false;
+      await delay(REFRESH_LOCK_POLL_MS);
+    }
+  }
+}
+
+function releaseRefreshLock(lockPath: string): void {
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    /* already released/stolen */
+  }
+}
+
 /**
  * Call POST /v1/guardian/refresh on the remote gateway to obtain a new
  * access token using an existing (possibly expired) access token for auth.
  * Returns the refreshed token data (persisted locally), or null if the
  * refresh fails (e.g. no stored token, or refresh token itself is expired).
+ *
+ * Concurrency-safe: the gateway rotates refresh tokens and treats reuse of an
+ * already-rotated token as replay (revoking the whole token family), so two
+ * processes (e.g. `vellum message` + `vellum events`) refreshing the same
+ * stored token at once would self-revoke and force re-pairing. We serialize on
+ * a per-assistant lock and, once held, re-read the stored token: if another
+ * process already rotated it while we waited, we return that fresh token
+ * instead of replaying our now-stale refresh token.
  */
 export async function refreshGuardianToken(
   gatewayUrl: string,
   assistantId: string,
 ): Promise<GuardianTokenData | null> {
-  const tokenData = loadGuardianToken(assistantId);
-  if (!tokenData) return null;
+  const before = loadGuardianToken(assistantId);
+  if (!before) return null;
 
   // Gateway persists expiresAt as epoch-ms numbers; Date.parse("1234567890000")
   // returns NaN. new Date() accepts both ISO strings and epoch-ms numbers.
-  const refreshExpiry = new Date(tokenData.refreshTokenExpiresAt).getTime();
+  const refreshExpiry = new Date(before.refreshTokenExpiresAt).getTime();
   if (!Number.isFinite(refreshExpiry) || refreshExpiry <= Date.now())
     return null;
 
+  const lockPath = getRefreshLockPath(assistantId);
+  const locked = await acquireRefreshLock(lockPath);
   try {
+    // Re-read under the lock: a concurrent process may have rotated the token
+    // while we waited. If the stored refresh token changed, ours is now stale
+    // (replaying it would trip reuse-detection) — use the fresh token instead.
+    const current = loadGuardianToken(assistantId);
+    if (current && current.refreshToken !== before.refreshToken) {
+      return current;
+    }
+
+    // We did NOT acquire the lock (another process is likely mid-refresh) and
+    // the stored token hasn't been rotated yet. Do NOT call the gateway: our
+    // refresh token may be the one the winner is rotating right now, and
+    // replaying a rotated token revokes the whole family (forcing re-pair).
+    // Give up — the caller surfaces the original 401, and the next attempt
+    // picks up the winner's persisted token.
+    if (!locked) return null;
+
+    const tokenData = current ?? before;
+
     const response = await fetch(`${gatewayUrl}/v1/guardian/refresh`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${tokenData.accessToken}`,
       },
-      body: JSON.stringify({ refreshToken: tokenData.refreshToken }),
+      body: JSON.stringify({
+        refreshToken: tokenData.refreshToken,
+        // The refresh token is device-bound; send the device id used at init
+        // (falling back to a fresh computation for tokens persisted before the
+        // field was stored) so the gateway can verify the binding.
+        deviceId: tokenData.deviceId || computeDeviceId(),
+      }),
+      signal: AbortSignal.timeout(REFRESH_FETCH_TIMEOUT_MS),
     });
     if (!response.ok) return null;
 
@@ -212,6 +326,8 @@ export async function refreshGuardianToken(
     return refreshed;
   } catch {
     return null;
+  } finally {
+    if (locked) releaseRefreshLock(lockPath);
   }
 }
 

package/src/lib/local.ts

@@ -230,8 +230,10 @@ function resolveAssistantIndexPath(): string | undefined {
   }
 
   try {
-    const vellumPkgPath = _require.resolve("vellum/package.json");
-    const resolved = join(dirname(vellumPkgPath), "src", "index.ts");
+    const assistantPkgPath = _require.resolve(
+      "@vellumai/assistant/package.json",
+    );
+    const resolved = join(dirname(assistantPkgPath), "src", "index.ts");
     if (existsSync(resolved)) {
       return resolved;
     }
@@ -416,13 +418,13 @@ async function startDaemonFromSource(
   writeFileSync(pidFile, "starting", "utf-8");
 
   const child = foreground
-    ? spawn("bun", ["run", daemonMainPath], {
+    ? spawn(process.execPath, ["run", daemonMainPath], {
         stdio: "inherit",
         env,
       })
     : (() => {
         const daemonLogFd = openLogFile("hatch.log");
-        const c = spawn("bun", ["run", daemonMainPath], {
+        const c = spawn(process.execPath, ["run", daemonMainPath], {
           detached: true,
           stdio: ["ignore", "pipe", "pipe"],
           env,
@@ -486,7 +488,7 @@ async function startDaemonWatchFromSource(
   writeFileSync(pidFile, "starting", "utf-8");
 
   const daemonLogFd = openLogFile("hatch.log");
-  const child = spawn("bun", ["--watch", "run", mainPath], {
+  const child = spawn(process.execPath, ["--watch", "run", mainPath], {
     detached: true,
     stdio: ["ignore", "pipe", "pipe"],
     env,
@@ -514,6 +516,18 @@ function resolveGatewayDir(): string {
     return sourceDir;
   }
 
+  // npm-installed: @vellumai/cli and @vellumai/vellum-gateway are siblings
+  const npmGatewayDir = join(
+    import.meta.dir,
+    "..",
+    "..",
+    "..",
+    "vellum-gateway",
+  );
+  if (isGatewaySourceDir(npmGatewayDir)) {
+    return npmGatewayDir;
+  }
+
   // Compiled binary: gateway/ bundled adjacent to the CLI executable.
   const binGateway = join(dirname(process.execPath), "gateway");
   if (isGatewaySourceDir(binGateway)) {
@@ -1135,7 +1149,7 @@ export async function startGateway(
       ? ["--watch", "run", "src/index.ts", "--vellum-gateway"]
       : ["run", "src/index.ts", "--vellum-gateway"];
     const gwLogFd = openLogFile("hatch.log");
-    gateway = spawn("bun", bunArgs, {
+    gateway = spawn(process.execPath, bunArgs, {
       cwd: gatewayDir,
       detached: true,
       stdio: ["ignore", "pipe", "pipe"],