@vellumai/cli 0.6.6 → 0.7.1

package/src/lib/environments/seeds.ts

@@ -28,13 +28,11 @@ function portBlock(base: number): PortMap {
  * Built-in environment definitions. Mirrors Swift's
  * `clients/macos/vellum-assistant/App/VellumEnvironment.swift` enum and is
  * the TS-side source of truth for the set of known environment names.
- * Two other TS sites duplicate the name list:
+ * One other TS site duplicates the name list:
  *   - `assistant/src/util/platform.ts` (`KNOWN_ENVIRONMENTS`)
- *   - `clients/chrome-extension/native-host/src/lockfile.ts`
- *     (`NON_PRODUCTION_ENVIRONMENTS`, excludes `production`)
- * Drift between these three sites is caught at test time by
+ * Drift between these two sites is caught at test time by
  * `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
- * list into a `packages/environments` package so all three sites import
+ * list into a `packages/environments` package so both sites import
  * from one place.
  *
  * Custom environments via a user config file are a future phase — see the
@@ -45,10 +43,12 @@ export const SEEDS: Record<string, EnvironmentDefinition> = {
   production: {
     name: "production",
     platformUrl: "https://platform.vellum.ai",
+    webUrl: "https://www.vellum.ai",
   },
   staging: {
     name: "staging",
     platformUrl: "https://staging-platform.vellum.ai",
+    webUrl: "https://staging-assistant.vellum.ai",
     portsOverride: portBlock(17000),
   },
   test: {
@@ -56,16 +56,19 @@ export const SEEDS: Record<string, EnvironmentDefinition> = {
     // Non-functional URL — used only by unit tests for URL resolution, never
     // hit in production.
     platformUrl: "https://test-platform.vellum.ai",
+    webUrl: "https://dev-assistant.vellum.ai",
     portsOverride: portBlock(19000),
   },
   dev: {
     name: "dev",
     platformUrl: "https://dev-platform.vellum.ai",
+    webUrl: "https://dev-assistant.vellum.ai",
     portsOverride: portBlock(18000),
   },
   local: {
     name: "local",
     platformUrl: "http://localhost:8000",
+    webUrl: "http://localhost:3000",
     // assistantPlatformUrl: "http://host.docker.internal:8000",
     // ^ uncomment this once dockerized hatch path is live.
     // The assistant runs in a different network namespace than the host.

package/src/lib/environments/types.ts

@@ -30,6 +30,16 @@ export interface EnvironmentDefinition {
   name: string;
   platformUrl: string;
 
+  /**
+   * The web app (Next.js) base URL for browser-facing pages like
+   * `/account/login`. In production this is separate from the API backend
+   * (e.g. `www.vellum.ai` vs `platform.vellum.ai`); locally it's
+   * `localhost:3000` vs `localhost:8000`.
+   *
+   * Mirrors `VellumEnvironment.webURL` on the Swift side.
+   */
+  webUrl: string;
+
   /**
    * Override for the platform URL the assistant process itself uses. Only
    * differs from `platformUrl` when the assistant runs in a different network

package/src/lib/hatch-local.ts

@@ -3,7 +3,6 @@ import {
   lstatSync,
   mkdirSync,
   readlinkSync,
-  rmSync,
   symlinkSync,
   unlinkSync,
   writeFileSync,
@@ -19,15 +18,11 @@ import cliPkg from "../../package.json";
 import {
   allocateLocalResources,
   findAssistantByName,
-  loadAllAssistants,
   saveAssistantEntry,
   setActiveAssistant,
   syncConfigToLockfile,
 } from "./assistant-config.js";
-import type {
-  AssistantEntry,
-  LocalInstanceResources,
-} from "./assistant-config.js";
+import type { AssistantEntry } from "./assistant-config.js";
 import type { Species } from "./constants.js";
 import { writeInitialConfig } from "./config-utils.js";
 import {
@@ -37,20 +32,12 @@ import {
   stopLocalProcesses,
 } from "./local.js";
 import { maybeStartNgrokTunnel } from "./ngrok.js";
-import { httpHealthCheck } from "./http-client.js";
-import { detectOrphanedProcesses } from "./orphan-detection.js";
-import { isProcessAlive, stopProcess } from "./process.js";
+
 import { generateInstanceName } from "./random-name.js";
 import { leaseGuardianToken } from "./guardian-token.js";
 import { archiveLogFile, resetLogFile } from "./xdg-log.js";
 import { emitProgress } from "./desktop-progress.js";
 
-const IS_DESKTOP = !!process.env.VELLUM_DESKTOP_APP;
-
-function desktopLog(msg: string): void {
-  process.stdout.write(msg + "\n");
-}
-
 /**
  * Attempts to place a symlink at the given path pointing to cliBinary.
  * Returns true if the symlink was created (or already correct), false on failure.
@@ -153,110 +140,18 @@ export async function hatchLocal(
     name ?? process.env.VELLUM_ASSISTANT_NAME,
   );
 
-  emitProgress(1, 7, "Preparing workspace...");
-
-  // Clean up stale local state: if daemon/gateway processes are running but
-  // 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");
-  if (localAssistants.length === 0) {
-    const daemonPid = isProcessAlive(join(vellumDir, "vellum.pid"));
-    const gatewayPid = isProcessAlive(join(vellumDir, "gateway.pid"));
-    if (daemonPid.alive || gatewayPid.alive) {
-      // 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();
-      }
-    }
-  }
-
-  // On desktop, scan the process table for orphaned vellum processes that
-  // 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 existingResources = findAssistantByName(instanceName);
-    const expectedPort =
-      existingResources?.cloud === "local" && existingResources.resources
-        ? existingResources.resources.daemonPort
-        : undefined;
-    const daemonAlreadyHealthy = expectedPort
-      ? await httpHealthCheck(expectedPort)
-      : false;
+  emitProgress(1, 6, "Allocating resources...");
 
-    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})`,
-          );
-        }
-      }
-    }
-  }
-
-  emitProgress(2, 7, "Allocating resources...");
-
-  // Reuse existing resources if re-hatching with --name that matches a known
-  // local assistant, otherwise allocate fresh per-instance ports and directories.
-  let resources: LocalInstanceResources;
-  const existingEntry = findAssistantByName(instanceName);
-  if (existingEntry?.cloud === "local" && existingEntry.resources) {
-    resources = existingEntry.resources;
-  } else {
-    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",
+  const existing = findAssistantByName(instanceName);
+  if (existing && (!existing.cloud || existing.cloud === "local")) {
+    throw new Error(
+      `An assistant named "${instanceName}" is already hatched.\n` +
+        `Run \`vellum wake\` to restart it, or \`vellum retire ${instanceName}\` to remove it first.`,
     );
-    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 resources = await allocateLocalResources(instanceName);
+
   const logsDir = join(
     resources.instanceDir,
     ".vellum",
@@ -275,17 +170,17 @@ export async function hatchLocal(
     process.env.APP_VERSION = cliPkg.version;
   }
 
-  emitProgress(3, 7, "Writing configuration...");
+  emitProgress(2, 6, "Writing configuration...");
   const defaultWorkspaceConfigPath = writeInitialConfig(configValues);
 
-  emitProgress(4, 7, "Starting assistant...");
+  emitProgress(3, 6, "Starting assistant...");
   const signingKey = generateLocalSigningKey();
   await startLocalDaemon(watch, resources, {
     defaultWorkspaceConfigPath,
     signingKey,
   });
 
-  emitProgress(5, 7, "Starting gateway...");
+  emitProgress(4, 6, "Starting gateway...");
   let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
   try {
     runtimeUrl = await startGateway(watch, resources, { signingKey });
@@ -303,7 +198,7 @@ export async function hatchLocal(
   // instead of hitting /v1/guardian/init itself. Use loopback to satisfy
   // the daemon's local-only check — the mDNS runtimeUrl resolves to a LAN
   // IP which the daemon rejects as non-loopback.
-  emitProgress(6, 7, "Securing connection...");
+  emitProgress(5, 6, "Securing connection...");
   const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
   const maxLeaseAttempts = 3;
   for (let attempt = 1; attempt <= maxLeaseAttempts; attempt++) {
@@ -350,7 +245,7 @@ export async function hatchLocal(
       writeFileSync(ngrokPidFile, String(ngrokChild.pid));
     }
 
-    emitProgress(7, 7, "Saving configuration...");
+    emitProgress(6, 6, "Saving configuration...");
     saveAssistantEntry(localEntry);
     setActiveAssistant(instanceName);
     syncConfigToLockfile();

package/src/lib/health-check.ts

@@ -71,6 +71,104 @@ export async function checkManagedHealth(
   }
 }
 
+export interface ManagedProcessEntry {
+  name: string;
+  status: "running" | "not_running" | "unreachable";
+  children?: ManagedProcessEntry[];
+  info?: string;
+}
+
+export interface ManagedPsResponse {
+  processes: ManagedProcessEntry[];
+}
+
+export async function fetchManagedPs(
+  runtimeUrl: string,
+  assistantId: string,
+): Promise<ManagedPsResponse | null> {
+  const { readPlatformToken, authHeaders } =
+    await import("./platform-client.js");
+  const token = readPlatformToken();
+  if (!token) return null;
+
+  let headers: Record<string, string>;
+  try {
+    headers = await authHeaders(token, runtimeUrl);
+  } catch {
+    return null;
+  }
+
+  // Try the /ps endpoint first; fall back to legacy /connection-status
+  // for platform versions that haven't rolled it out yet.
+  try {
+    const psUrl = `${runtimeUrl}/v1/assistants/${encodeURIComponent(assistantId)}/ps/`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+    const response = await fetch(psUrl, {
+      signal: controller.signal,
+      headers,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (response.ok) {
+      return (await response.json()) as ManagedPsResponse;
+    }
+
+    // /ps not available — fall back to legacy connection-status
+    if (response.status === 404 || response.status === 405) {
+      return fetchLegacyConnectionStatus(runtimeUrl, assistantId, headers);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+interface LegacyConnectionStatus {
+  state: string;
+  is_awake: boolean;
+  pod_status: string | null;
+  detail: string | null;
+}
+
+async function fetchLegacyConnectionStatus(
+  runtimeUrl: string,
+  assistantId: string,
+  headers: Record<string, string>,
+): Promise<ManagedPsResponse | null> {
+  try {
+    const url = `${runtimeUrl}/v1/assistants/${encodeURIComponent(assistantId)}/connection-status/`;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+
+    const response = await fetch(url, {
+      method: "POST",
+      signal: controller.signal,
+      headers,
+    });
+
+    clearTimeout(timeoutId);
+    if (!response.ok) return null;
+
+    const data = (await response.json()) as LegacyConnectionStatus;
+
+    // Translate legacy shape into the ps process tree
+    const status: ManagedProcessEntry["status"] = data.is_awake
+      ? "running"
+      : "not_running";
+    return {
+      processes: [
+        { name: "assistant", status, info: data.detail ?? undefined },
+      ],
+    };
+  } catch {
+    return null;
+  }
+}
+
 export async function checkHealth(
   runtimeUrl: string,
   bearerToken?: string,

package/src/lib/job-polling.ts

@@ -0,0 +1,195 @@
+import type { UnifiedJobStatus } from "./platform-client.js";
+
+/**
+ * Terminal status returned by {@link pollJobUntilDone}. Callers decide
+ * whether to treat `failed` as a fatal error or retry logic concern.
+ */
+export type TerminalJobStatus = Extract<
+  UnifiedJobStatus,
+  { status: "complete" | "failed" }
+>;
+
+export interface PollJobUntilDoneOptions {
+  /** Async producer that returns the latest job status. */
+  poll: () => Promise<UnifiedJobStatus>;
+  /** Sleep between successive polls. Defaults to 2_000 ms. */
+  intervalMs?: number;
+  /** Maximum wall-clock time to wait. Defaults to 60 minutes. */
+  timeoutMs?: number;
+  /** Human-readable label used in the timeout error message (e.g. "export job"). */
+  label: string;
+  /**
+   * Maximum consecutive transient (retryable) poll errors tolerated before
+   * the last error is propagated. Transient errors (5xx / network) between
+   * successful polls reset the counter. Defaults to 5.
+   */
+  maxTransientErrors?: number;
+  /**
+   * Optional async hook invoked when `poll()` throws an error containing a
+   * `401` HTTP status. The callback is expected to refresh whatever
+   * credential the poll closure reads (e.g. re-lease a guardian token), then
+   * return. The polling loop will retry the poll after the callback resolves
+   * instead of propagating the 401.
+   *
+   * Used by long-running migrations where the cached access token may expire
+   * mid-poll. Without this hook, 4xx errors (except 429) are permanent and
+   * would abandon a migration that's still running on the server.
+   */
+  refreshOn401?: () => Promise<void>;
+  /**
+   * Maximum consecutive 401 refreshes tolerated before the last 401 is
+   * propagated. Tracked separately from {@link maxTransientErrors} because
+   * a persistent 401 after a refresh usually means the underlying credential
+   * is revoked, not a transient network issue. Defaults to 3.
+   */
+  maxAuthRefreshes?: number;
+}
+
+const DEFAULT_INTERVAL_MS = 2_000;
+// Matches the server-side runtime migration window: the GCS upload PUT and
+// the import-URL fetch in assistant/src/runtime/routes/migration-routes.ts
+// use AbortSignal.timeout(60 * 60 * 1000), so a shorter CLI poll cap would
+// abort a job that's still legitimately in progress on the server.
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
+const DEFAULT_MAX_TRANSIENT_ERRORS = 5;
+const DEFAULT_MAX_AUTH_REFRESHES = 3;
+
+function is401Error(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return /\b401\b/.test(msg);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Heuristic classification used by {@link pollJobUntilDone} to decide whether
+ * to retry a failed poll.
+ *
+ * - 5xx responses and unclassifiable network-style errors (fetch failed,
+ *   ECONNRESET, etc.) are treated as transient.
+ * - 4xx responses are treated as permanent, except 429 (rate limited) which is
+ *   transient.
+ * - "not found" errors are permanent — they indicate the job id is wrong and
+ *   retrying won't help.
+ *
+ * The poll helpers (`platformPollJobStatus`, `localRuntimePollJobStatus`)
+ * raise errors whose message contains the HTTP status (e.g. `"Local job
+ * status check failed: 503 Service Unavailable"`), so we parse that out when
+ * available and default to "retry" when unsure.
+ */
+function isTransientPollError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+
+  if (msg.includes("not found")) return false;
+
+  const match = msg.match(/(?:status check failed|failed)[^\d]*(\d{3})/i);
+  if (match) {
+    const code = parseInt(match[1], 10);
+    if (code === 429) return true;
+    if (code >= 400 && code < 500) return false;
+    if (code >= 500) return true;
+  }
+
+  // Unclassifiable (e.g. "fetch failed", ECONNRESET) — treat as transient so
+  // a single network hiccup doesn't abort a long-running migration.
+  return true;
+}
+
+/**
+ * Poll `options.poll` until it returns a terminal status (`complete` or
+ * `failed`), or until `timeoutMs` elapses.
+ *
+ * On terminal status, returns the status object — including the `failed`
+ * case. The caller decides how to treat a failed terminal status (e.g.
+ * print the `error` field and exit). Timeouts throw.
+ *
+ * Transient errors raised by `poll()` (5xx, network hiccups, rate-limits) are
+ * retried up to `maxTransientErrors` times before the last error propagates,
+ * matching the pre-rewrite migration-export polling loop's behavior so a
+ * single flaky poll doesn't abort a migration that may still be running.
+ */
+export async function pollJobUntilDone(
+  options: PollJobUntilDoneOptions,
+): Promise<TerminalJobStatus> {
+  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxTransientErrors =
+    options.maxTransientErrors ?? DEFAULT_MAX_TRANSIENT_ERRORS;
+  const maxAuthRefreshes =
+    options.maxAuthRefreshes ?? DEFAULT_MAX_AUTH_REFRESHES;
+  const deadline = Date.now() + timeoutMs;
+
+  let consecutiveTransientErrors = 0;
+  let consecutiveAuthRefreshes = 0;
+
+  // First poll happens immediately so fast-path completions don't wait
+  // one interval before returning.
+  while (true) {
+    let status: UnifiedJobStatus;
+    try {
+      status = await options.poll();
+      consecutiveTransientErrors = 0;
+      consecutiveAuthRefreshes = 0;
+    } catch (err) {
+      // 401 Unauthorized takes precedence over the generic transient
+      // classifier: when a refresh callback is registered, a long-running
+      // poll loop can re-lease its credential and keep going instead of
+      // abandoning a migration that's still running on the server.
+      if (options.refreshOn401 && is401Error(err)) {
+        consecutiveAuthRefreshes += 1;
+        if (consecutiveAuthRefreshes > maxAuthRefreshes) {
+          throw err;
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(
+          `${options.label} polling got 401, refreshing auth and retrying... (${msg})`,
+        );
+        await options.refreshOn401();
+        if (Date.now() >= deadline) {
+          throw new Error(
+            `Timed out waiting for ${options.label} after ${Math.round(
+              timeoutMs / 1000,
+            )}s`,
+          );
+        }
+        await sleep(intervalMs);
+        continue;
+      }
+
+      if (!isTransientPollError(err)) {
+        throw err;
+      }
+      consecutiveTransientErrors += 1;
+      if (consecutiveTransientErrors > maxTransientErrors) {
+        throw err;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`${options.label} polling failed, retrying... (${msg})`);
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Timed out waiting for ${options.label} after ${Math.round(
+            timeoutMs / 1000,
+          )}s`,
+        );
+      }
+      await sleep(intervalMs);
+      continue;
+    }
+
+    if (status.status === "complete" || status.status === "failed") {
+      return status;
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Timed out waiting for ${options.label} after ${Math.round(
+          timeoutMs / 1000,
+        )}s`,
+      );
+    }
+
+    await sleep(intervalMs);
+  }
+}