@vellumai/cli 0.5.16 → 0.6.1

package/src/lib/hatch-local.ts

@@ -308,10 +308,13 @@ export async function hatchLocal(
   }
 
   // Lease a guardian token so the desktop app can import it on first launch
-  // instead of hitting /v1/guardian/init itself.
+  // 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...");
+  const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
   try {
-    await leaseGuardianToken(runtimeUrl, instanceName);
+    await leaseGuardianToken(loopbackUrl, instanceName);
   } catch (err) {
     console.error(`⚠️  Guardian token lease failed: ${err}`);
   }

package/src/lib/health-check.ts

@@ -25,10 +25,10 @@ export async function checkManagedHealth(
     };
   }
 
-  let orgId: string;
+  let headers: Record<string, string>;
   try {
-    const { fetchOrganizationId } = await import("./platform-client.js");
-    orgId = await fetchOrganizationId(token, runtimeUrl);
+    const { authHeaders } = await import("./platform-client.js");
+    headers = await authHeaders(token, runtimeUrl);
   } catch (err) {
     return {
       status: "error (auth)",
@@ -44,11 +44,6 @@ export async function checkManagedHealth(
       HEALTH_CHECK_TIMEOUT_MS,
     );
 
-    const headers: Record<string, string> = {
-      "X-Session-Token": token,
-      "Vellum-Organization-Id": orgId,
-    };
-
     const response = await fetch(url, {
       signal: controller.signal,
       headers,

package/src/lib/ngrok.ts

@@ -1,5 +1,6 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 import {
+  closeSync,
   existsSync,
   mkdirSync,
   openSync,
@@ -130,10 +131,11 @@ export function startNgrokProcess(
   logFilePath?: string,
 ): ChildProcess {
   let stdio: ("ignore" | "pipe" | number)[] = ["ignore", "pipe", "pipe"];
+  let fd: number | undefined;
   if (logFilePath) {
     const dir = dirname(logFilePath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const fd = openSync(logFilePath, "a");
+    fd = openSync(logFilePath, "a");
     stdio = ["ignore", fd, fd];
   }
 
@@ -141,6 +143,14 @@ export function startNgrokProcess(
     detached: true,
     stdio,
   });
+
+  // The child process inherits a duplicate of the fd via dup2, so the
+  // parent's copy is no longer needed. Close it to avoid leaking the
+  // file descriptor for the lifetime of the parent process.
+  if (fd !== undefined) {
+    closeSync(fd);
+  }
+
   return child;
 }
 

package/src/lib/platform-client.ts

@@ -68,34 +68,94 @@ export function clearPlatformToken(): void {
 const VAK_PREFIX = "vak_";
 
 /**
- * Returns the appropriate auth header for the given platform token.
+ * Sync helper – returns only the token-based auth header.
  *
- * - `vak_`-prefixed tokens are long-lived platform API keys and use
- *   `Authorization: Bearer`.
- * - All other tokens are allauth session tokens and use `X-Session-Token`.
+ * Used internally by {@link fetchOrganizationId} (which cannot call the
+ * async {@link authHeaders} without creating a cycle) and by functions
+ * that already have an org ID in hand.
  */
-export function authHeaders(token: string): Record<string, string> {
+function tokenAuthHeader(token: string): Record<string, string> {
   if (token.startsWith(VAK_PREFIX)) {
     return { Authorization: `Bearer ${token}` };
   }
   return { "X-Session-Token": token };
 }
 
+/** Module-level cache for org IDs to avoid redundant fetches in polling loops. */
+const orgIdCache = new Map<string, { orgId: string; expiresAt: number }>();
+const ORG_ID_CACHE_TTL_MS = 60_000; // 60 seconds
+
+/**
+ * Returns the full set of headers needed for an authenticated platform
+ * API request:
+ *
+ * - `Content-Type: application/json`
+ * - The appropriate auth header (`Authorization: Bearer` for `vak_`
+ *   API keys, `X-Session-Token` for session tokens).
+ * - `Vellum-Organization-Id` – fetched from the platform.  Only
+ *   included for session-token callers; API keys are already org-scoped.
+ *
+ * The org ID is cached per (token, platformUrl) for 60 seconds to avoid
+ * redundant HTTP requests in tight polling loops.
+ *
+ * Auth errors (401 / 403) from the org-ID fetch are logged with a
+ * user-friendly message before re-throwing, so callers don't need to
+ * repeat that logic.
+ */
+export async function authHeaders(
+  token: string,
+  platformUrl?: string,
+): Promise<Record<string, string>> {
+  const base: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...tokenAuthHeader(token),
+  };
+
+  if (token.startsWith(VAK_PREFIX)) {
+    // API keys are org-scoped – no need to fetch the org ID.
+    return base;
+  }
+
+  const cacheKey = `${token}::${platformUrl ?? ""}`;
+  const cached = orgIdCache.get(cacheKey);
+  if (cached && Date.now() < cached.expiresAt) {
+    return { ...base, "Vellum-Organization-Id": cached.orgId };
+  }
+
+  try {
+    const orgId = await fetchOrganizationId(token, platformUrl);
+    orgIdCache.set(cacheKey, {
+      orgId,
+      expiresAt: Date.now() + ORG_ID_CACHE_TTL_MS,
+    });
+    return { ...base, "Vellum-Organization-Id": orgId };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("401") || msg.includes("403")) {
+      console.error("Authentication failed. Run 'vellum login' to refresh.");
+    } else {
+      console.error(`Failed to fetch organization: ${msg}`);
+    }
+    throw err;
+  }
+}
+
 export interface HatchedAssistant {
   id: string;
   name: string;
   status: string;
 }
 
-export async function hatchAssistant(token: string): Promise<HatchedAssistant> {
-  const url = `${getPlatformUrl()}/v1/assistants/hatch/`;
+export async function hatchAssistant(
+  token: string,
+  platformUrl?: string,
+): Promise<HatchedAssistant> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const url = `${resolvedUrl}/v1/assistants/hatch/`;
 
   const response = await fetch(url, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      ...authHeaders(token),
-    },
+    headers: await authHeaders(token, platformUrl),
     body: JSON.stringify({}),
   });
 
@@ -143,7 +203,7 @@ export async function fetchOrganizationId(
   const resolvedUrl = platformUrl || getPlatformUrl();
   const url = `${resolvedUrl}/v1/organizations/`;
   const response = await fetch(url, {
-    headers: { "X-Session-Token": token },
+    headers: { ...tokenAuthHeader(token) },
   });
 
   if (!response.ok) {
@@ -204,18 +264,13 @@ export async function fetchCurrentUser(
 
 export async function rollbackPlatformAssistant(
   token: string,
-  orgId: string,
   version?: string,
   platformUrl?: string,
 ): Promise<{ detail: string; version: string | null }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const response = await fetch(`${resolvedUrl}/v1/assistants/rollback/`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-Session-Token": token,
-      "Vellum-Organization-Id": orgId,
-    },
+    headers: await authHeaders(token, platformUrl),
     body: JSON.stringify(version ? { version } : {}),
   });
 
@@ -249,18 +304,13 @@ export async function rollbackPlatformAssistant(
 
 export async function platformInitiateExport(
   token: string,
-  orgId: string,
   description?: string,
   platformUrl?: string,
 ): Promise<{ jobId: string; status: string }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const response = await fetch(`${resolvedUrl}/v1/migrations/export/`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-Session-Token": token,
-      "Vellum-Organization-Id": orgId,
-    },
+    headers: await authHeaders(token, platformUrl),
     body: JSON.stringify({ description: description ?? "CLI backup" }),
   });
 
@@ -284,17 +334,13 @@ export async function platformInitiateExport(
 export async function platformPollExportStatus(
   jobId: string,
   token: string,
-  orgId: string,
   platformUrl?: string,
 ): Promise<{ status: string; downloadUrl?: string; error?: string }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const response = await fetch(
     `${resolvedUrl}/v1/migrations/export/${jobId}/status/`,
     {
-      headers: {
-        "X-Session-Token": token,
-        "Vellum-Organization-Id": orgId,
-      },
+      headers: await authHeaders(token, platformUrl),
     },
   );
 
@@ -339,7 +385,6 @@ export async function platformDownloadExport(
 export async function platformImportPreflight(
   bundleData: Uint8Array<ArrayBuffer>,
   token: string,
-  orgId: string,
   platformUrl?: string,
 ): Promise<{ statusCode: number; body: Record<string, unknown> }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
@@ -348,9 +393,8 @@ export async function platformImportPreflight(
     {
       method: "POST",
       headers: {
+        ...(await authHeaders(token, platformUrl)),
         "Content-Type": "application/octet-stream",
-        "X-Session-Token": token,
-        "Vellum-Organization-Id": orgId,
       },
       body: new Blob([bundleData]),
       signal: AbortSignal.timeout(120_000),
@@ -367,19 +411,17 @@ export async function platformImportPreflight(
 export async function platformImportBundle(
   bundleData: Uint8Array<ArrayBuffer>,
   token: string,
-  orgId: string,
   platformUrl?: string,
 ): Promise<{ statusCode: number; body: Record<string, unknown> }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const response = await fetch(`${resolvedUrl}/v1/migrations/import/`, {
     method: "POST",
     headers: {
+      ...(await authHeaders(token, platformUrl)),
       "Content-Type": "application/octet-stream",
-      "X-Session-Token": token,
-      "Vellum-Organization-Id": orgId,
     },
     body: new Blob([bundleData]),
-    signal: AbortSignal.timeout(120_000),
+    signal: AbortSignal.timeout(300_000),
   });
 
   const body = (await response.json().catch(() => ({}))) as Record<
@@ -388,3 +430,116 @@ export async function platformImportBundle(
   >;
   return { statusCode: response.status, body };
 }
+
+// ---------------------------------------------------------------------------
+// Signed-URL upload flow
+// ---------------------------------------------------------------------------
+
+export async function platformRequestUploadUrl(
+  token: string,
+  platformUrl?: string,
+): Promise<{ uploadUrl: string; bundleKey: string; expiresAt: string }> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(`${resolvedUrl}/v1/migrations/upload-url/`, {
+    method: "POST",
+    headers: await authHeaders(token, platformUrl),
+    body: JSON.stringify({ content_type: "application/octet-stream" }),
+  });
+
+  if (response.status === 201) {
+    const body = (await response.json()) as {
+      upload_url: string;
+      bundle_key: string;
+      expires_at: string;
+    };
+    return {
+      uploadUrl: body.upload_url,
+      bundleKey: body.bundle_key,
+      expiresAt: body.expires_at,
+    };
+  }
+
+  if (response.status === 404 || response.status === 503) {
+    throw new Error(
+      "Signed uploads are not available on this platform instance",
+    );
+  }
+
+  const errorBody = (await response.json().catch(() => ({}))) as {
+    detail?: string;
+  };
+  throw new Error(
+    errorBody.detail ??
+      `Failed to request upload URL: ${response.status} ${response.statusText}`,
+  );
+}
+
+export async function platformUploadToSignedUrl(
+  uploadUrl: string,
+  bundleData: Uint8Array<ArrayBuffer>,
+): Promise<void> {
+  const response = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/octet-stream",
+    },
+    body: new Blob([bundleData]),
+    signal: AbortSignal.timeout(600_000),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Upload to signed URL failed: ${response.status} ${response.statusText}`,
+    );
+  }
+}
+
+export async function platformImportPreflightFromGcs(
+  bundleKey: string,
+  token: string,
+  platformUrl?: string,
+): Promise<{ statusCode: number; body: Record<string, unknown> }> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(
+    `${resolvedUrl}/v1/migrations/import-preflight-from-gcs/`,
+    {
+      method: "POST",
+      headers: await authHeaders(token, platformUrl),
+      signal: AbortSignal.timeout(120_000),
+      body: JSON.stringify({ bundle_key: bundleKey }),
+    },
+  );
+
+  const body = (await response.json().catch(() => ({}))) as Record<
+    string,
+    unknown
+  >;
+  return { statusCode: response.status, body };
+}
+
+export async function platformImportBundleFromGcs(
+  bundleKey: string,
+  token: string,
+  platformUrl?: string,
+): Promise<{ statusCode: number; body: Record<string, unknown> }> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(
+    `${resolvedUrl}/v1/migrations/import-from-gcs/`,
+    {
+      method: "POST",
+      headers: await authHeaders(token, platformUrl),
+      body: JSON.stringify({ bundle_key: bundleKey }),
+      signal: AbortSignal.timeout(300_000),
+    },
+  );
+
+  if (response.status === 413) {
+    throw new Error("Bundle too large to import");
+  }
+
+  const body = (await response.json().catch(() => ({}))) as Record<
+    string,
+    unknown
+  >;
+  return { statusCode: response.status, body };
+}

package/src/lib/upgrade-lifecycle.ts

@@ -16,7 +16,7 @@ import { loadGuardianToken } from "./guardian-token.js";
 import { getPlatformUrl } from "./platform-client.js";
 import { resolveImageRefs } from "./platform-releases.js";
 import { exec, execOutput } from "./step-runner.js";
-import { parseVersion } from "./version-compat.js";
+import { compareVersions } from "./version-compat.js";
 
 // ---------------------------------------------------------------------------
 // Shared constants & builders for upgrade / rollback lifecycle events
@@ -90,6 +90,7 @@ export function buildUpgradeCommitMessage(options: {
  */
 export const CONTAINER_ENV_EXCLUDE_KEYS: ReadonlySet<string> = new Set([
   "CES_SERVICE_TOKEN",
+  "GUARDIAN_BOOTSTRAP_SECRET",
   "VELLUM_ASSISTANT_NAME",
   "RUNTIME_HTTP_HOST",
   "PATH",
@@ -317,26 +318,16 @@ export async function performDockerRollback(
 
   // Validate target version < current version
   if (currentVersion) {
-    const current = parseVersion(currentVersion);
-    const target = parseVersion(targetVersion);
-    if (current && target) {
-      const isNewer = (() => {
-        if (target.major !== current.major) return target.major > current.major;
-        if (target.minor !== current.minor) return target.minor > current.minor;
-        return target.patch > current.patch;
-      })();
-      if (isNewer) {
+    const cmp = compareVersions(targetVersion, currentVersion);
+    if (cmp !== null) {
+      if (cmp > 0) {
         const msg =
           "Cannot roll back to a newer version. Use `vellum upgrade` instead.";
         console.error(msg);
         emitCliError("VERSION_DIRECTION", msg);
         process.exit(1);
       }
-      const isSame =
-        target.major === current.major &&
-        target.minor === current.minor &&
-        target.patch === current.patch;
-      if (isSame) {
+      if (cmp === 0) {
         const msg = `Already on version ${targetVersion}. Nothing to roll back to.`;
         console.error(msg);
         emitCliError("VERSION_DIRECTION", msg);
@@ -467,6 +458,11 @@ export async function performDockerRollback(
     `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
   );
 
+  // Capture GUARDIAN_BOOTSTRAP_SECRET from the gateway container (it is only
+  // set on gateway, not assistant) so it persists across container restarts.
+  const gatewayEnv = await captureContainerEnv(res.gatewayContainer);
+  const bootstrapSecret = gatewayEnv["GUARDIAN_BOOTSTRAP_SECRET"];
+
   const cesServiceToken =
     capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
 
@@ -575,6 +571,7 @@ export async function performDockerRollback(
   await startContainers(
     {
       signingKey,
+      bootstrapSecret,
       cesServiceToken,
       extraAssistantEnv,
       gatewayPort,
@@ -695,6 +692,7 @@ export async function performDockerRollback(
         await startContainers(
           {
             signingKey,
+            bootstrapSecret,
             cesServiceToken,
             extraAssistantEnv,
             gatewayPort,

package/src/lib/version-compat.ts

@@ -1,13 +1,16 @@
 /**
- * Parse a version string into { major, minor, patch } components.
- * Handles optional `v` prefix (e.g., "v1.2.3" or "1.2.3").
+ * Parse a version string into { major, minor, patch, pre } components.
+ * Handles optional `v`/`V` prefix (e.g., "v1.2.3" or "1.2.3").
+ * Pre-release suffixes are captured (e.g., "0.6.0-staging.5" → pre: "staging.5").
  * Returns null if the string cannot be parsed as semver.
  */
 export function parseVersion(
   version: string,
-): { major: number; minor: number; patch: number } | null {
+): { major: number; minor: number; patch: number; pre: string | null } | null {
   const stripped = version.replace(/^[vV]/, "");
-  const segments = stripped.split(".");
+  const [core, ...rest] = stripped.split("-");
+  const pre = rest.length > 0 ? rest.join("-") : null;
+  const segments = (core ?? "").split(".");
 
   if (segments.length < 2) {
     return null;
@@ -21,7 +24,66 @@ export function parseVersion(
     return null;
   }
 
-  return { major, minor, patch };
+  return { major, minor, patch, pre };
+}
+
+/**
+ * Compare two pre-release strings per semver §11:
+ *   - Dot-separated identifiers compared left to right.
+ *   - Both numeric → compare as integers.
+ *   - Both non-numeric → compare lexically.
+ *   - Numeric vs non-numeric → numeric sorts lower (§11.4.4).
+ *   - Fewer identifiers sorts earlier when all preceding are equal.
+ */
+function comparePreRelease(a: string, b: string): number {
+  const pa = a.split(".");
+  const pb = b.split(".");
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    if (i >= pa.length) return -1; // a has fewer fields → a < b
+    if (i >= pb.length) return 1;
+    const aIsNum = /^\d+$/.test(pa[i]);
+    const bIsNum = /^\d+$/.test(pb[i]);
+    if (aIsNum && bIsNum) {
+      const diff = Number(pa[i]) - Number(pb[i]);
+      if (diff !== 0) return diff;
+    } else if (aIsNum !== bIsNum) {
+      return aIsNum ? -1 : 1; // numeric < non-numeric per §11.4.4
+    } else {
+      const cmp = (pa[i] ?? "").localeCompare(pb[i] ?? "");
+      if (cmp !== 0) return cmp;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Compare two semver version strings.
+ * Returns negative if a < b, 0 if equal, positive if a > b.
+ *
+ * Handles pre-release suffixes per semver spec:
+ *   - `0.6.0-staging.1 < 0.6.0` (pre-release < release)
+ *   - `0.6.0-staging.1 < 0.6.0-staging.2` (numeric postfix comparison)
+ *
+ * Returns null if either version cannot be parsed.
+ */
+export function compareVersions(a: string, b: string): number | null {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (pa === null || pb === null) return null;
+
+  const majorDiff = pa.major - pb.major;
+  if (majorDiff !== 0) return majorDiff;
+  const minorDiff = pa.minor - pb.minor;
+  if (minorDiff !== 0) return minorDiff;
+  const patchDiff = pa.patch - pb.patch;
+  if (patchDiff !== 0) return patchDiff;
+
+  // Same major.minor.patch — compare pre-release
+  if (pa.pre === null && pb.pre === null) return 0;
+  if (pa.pre !== null && pb.pre === null) return -1; // pre-release < release
+  if (pa.pre === null && pb.pre !== null) return 1;
+  return comparePreRelease(pa.pre!, pb.pre!);
 }
 
 /**

package/src/shared/provider-env-vars.ts

@@ -0,0 +1,19 @@
+/**
+ * Provider API key environment variable names, keyed by provider ID.
+ *
+ * Keep in sync with:
+ *   - assistant/src/shared/provider-env-vars.ts
+ *   - meta/provider-env-vars.json  (consumed by the macOS client build)
+ *
+ * Once a consolidated shared package exists in packages/, all three
+ * copies can be replaced by a single import.
+ */
+export const PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
+  anthropic: "ANTHROPIC_API_KEY",
+  openai: "OPENAI_API_KEY",
+  gemini: "GEMINI_API_KEY",
+  fireworks: "FIREWORKS_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+  brave: "BRAVE_API_KEY",
+  perplexity: "PERPLEXITY_API_KEY",
+};