@vellumai/cli 0.6.6 → 0.7.1

package/src/lib/platform-client.ts

@@ -40,6 +40,19 @@ export function getPlatformUrl(): string {
   );
 }
 
+/**
+ * Resolve the web app (Next.js) base URL for browser-facing pages like
+ * `/account/login`. Mirrors `VellumEnvironment.resolvedWebURL` on the
+ * Swift side.
+ *
+ * Resolution order:
+ *   1. `VELLUM_WEB_URL` env var (explicit override)
+ *   2. The current environment's seed web URL
+ */
+export function getWebUrl(): string {
+  return process.env.VELLUM_WEB_URL?.trim() || getCurrentEnvironment().webUrl;
+}
+
 export function readPlatformToken(): string | null {
   try {
     return readFileSync(getPlatformTokenPath(), "utf-8").trim();
@@ -516,6 +529,30 @@ export async function checkExistingPlatformAssistant(
   return active ?? null;
 }
 
+/**
+ * Fetch all active assistants for the authenticated user from the platform.
+ * Returns an empty array on failure (non-fatal).
+ */
+export async function fetchPlatformAssistants(
+  token: string,
+  platformUrl?: string,
+): Promise<HatchedAssistant[]> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const url = `${resolvedUrl}/v1/assistants/`;
+
+  const response = await fetch(url, {
+    headers: await authHeaders(token, platformUrl),
+  });
+
+  if (!response.ok) return [];
+
+  const body = (await response.json()) as {
+    results?: HatchedAssistant[];
+  };
+
+  return (body.results ?? []).filter((a) => a.status === "active");
+}
+
 export interface PlatformUser {
   id: string;
   email: string;
@@ -628,182 +665,10 @@ export async function rollbackPlatformAssistant(
   throw new Error(`Rollback failed: ${response.status} ${response.statusText}`);
 }
 
-// ---------------------------------------------------------------------------
-// Migration export
-// ---------------------------------------------------------------------------
-
-export async function platformInitiateExport(
-  token: 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: await authHeaders(token, platformUrl),
-    body: JSON.stringify({ description: description ?? "CLI backup" }),
-  });
-
-  if (response.status !== 201) {
-    const body = (await response.json().catch(() => ({}))) as {
-      detail?: string;
-    };
-    throw new Error(
-      body.detail ??
-        `Export initiation failed: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const body = (await response.json()) as {
-    job_id: string;
-    status: string;
-  };
-  return { jobId: body.job_id, status: body.status };
-}
-
-export async function platformPollExportStatus(
-  jobId: string,
-  token: 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: await authHeaders(token, platformUrl),
-    },
-  );
-
-  if (response.status === 404) {
-    throw new Error("Export job not found");
-  }
-
-  if (!response.ok) {
-    throw new Error(
-      `Export status check failed: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const body = (await response.json()) as {
-    status: string;
-    download_url?: string;
-    error?: string;
-  };
-  return {
-    status: body.status,
-    downloadUrl: body.download_url,
-    error: body.error,
-  };
-}
-
-export async function platformDownloadExport(
-  downloadUrl: string,
-): Promise<Response> {
-  const response = await fetch(downloadUrl);
-  if (!response.ok) {
-    throw new Error(
-      `Download failed: ${response.status} ${response.statusText}`,
-    );
-  }
-  return response;
-}
-
-// ---------------------------------------------------------------------------
-// Migration import
-// ---------------------------------------------------------------------------
-
-export async function platformImportPreflight(
-  bundleData: Uint8Array<ArrayBuffer>,
-  token: string,
-  platformUrl?: string,
-): Promise<{ statusCode: number; body: Record<string, unknown> }> {
-  const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
-    `${resolvedUrl}/v1/migrations/import-preflight/`,
-    {
-      method: "POST",
-      headers: {
-        ...(await authHeaders(token, platformUrl)),
-        "Content-Type": "application/octet-stream",
-      },
-      body: new Blob([bundleData]),
-      signal: AbortSignal.timeout(120_000),
-    },
-  );
-
-  const body = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >;
-  return { statusCode: response.status, body };
-}
-
-export async function platformImportBundle(
-  bundleData: Uint8Array<ArrayBuffer>,
-  token: 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",
-    },
-    body: new Blob([bundleData]),
-    signal: AbortSignal.timeout(300_000),
-  });
-
-  const body = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >;
-  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>,
@@ -874,42 +739,173 @@ export async function platformImportBundleFromGcs(
   return { statusCode: response.status, body };
 }
 
-export async function platformPollImportStatus(
-  jobId: string,
+// ---------------------------------------------------------------------------
+// Unified signed-url + job-status endpoints (teleport-gcs-unify)
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union representing the unified migration job status shape
+ * returned by `GET /v1/migrations/jobs/{job_id}/` on both the platform and
+ * the local runtime.
+ */
+export type UnifiedJobStatus =
+  | {
+      jobId: string;
+      type: "export" | "import";
+      status: "processing";
+    }
+  | {
+      jobId: string;
+      type: "export" | "import";
+      status: "complete";
+      bundleKey?: string;
+      result?: unknown;
+    }
+  | {
+      jobId: string;
+      type: "export" | "import";
+      status: "failed";
+      error: string;
+    };
+
+interface RawUnifiedJobStatus {
+  job_id: string;
+  type: "export" | "import";
+  status: "processing" | "complete" | "failed";
+  bundle_key?: string;
+  result?: unknown;
+  error?: string;
+}
+
+/**
+ * Normalise the wire-format job-status payload into the TypeScript
+ * discriminated union. Shared between platform and local-runtime helpers
+ * since both endpoints return the same shape.
+ */
+export function parseUnifiedJobStatus(
+  raw: RawUnifiedJobStatus,
+): UnifiedJobStatus {
+  if (raw.status === "processing") {
+    return { jobId: raw.job_id, type: raw.type, status: "processing" };
+  }
+  if (raw.status === "complete") {
+    return {
+      jobId: raw.job_id,
+      type: raw.type,
+      status: "complete",
+      bundleKey: raw.bundle_key,
+      result: raw.result,
+    };
+  }
+  return {
+    jobId: raw.job_id,
+    type: raw.type,
+    status: "failed",
+    error: raw.error ?? "Job failed without an error message",
+  };
+}
+
+/**
+ * Request a signed URL from the platform for either uploading a new bundle
+ * or downloading an existing one. Calls `POST /v1/migrations/signed-url/`.
+ *
+ * - `operation: "upload"` (optionally with `contentType` / `contentLength`)
+ *   returns a URL the CLI can PUT a bundle to.
+ * - `operation: "download"` with a `bundleKey` returns a URL the local
+ *   runtime can GET the bundle from during an import-from-GCS flow.
+ *
+ * Retries once with a fresh org-ID cache on 401 to match the retry pattern
+ * used by other authenticated platform helpers.
+ */
+export async function platformRequestSignedUrl(
+  params: {
+    operation: "upload" | "download";
+    bundleKey?: string;
+    contentType?: string;
+    contentLength?: number;
+  },
   token: string,
   platformUrl?: string,
 ): Promise<{
-  status: string;
-  result?: Record<string, unknown>;
-  error?: string;
+  url: string;
+  bundleKey: string;
+  expiresAt: string;
+  maxContentLength?: number;
 }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
-    `${resolvedUrl}/v1/migrations/import/${jobId}/status/`,
-    {
+  const body: Record<string, unknown> = { operation: params.operation };
+  if (params.bundleKey !== undefined) body.bundle_key = params.bundleKey;
+  if (params.contentType !== undefined) body.content_type = params.contentType;
+  if (params.contentLength !== undefined) {
+    body.content_length = params.contentLength;
+  }
+
+  const doRequest = async (): Promise<Response> =>
+    fetch(`${resolvedUrl}/v1/migrations/signed-url/`, {
+      method: "POST",
       headers: await authHeaders(token, platformUrl),
-    },
+      body: JSON.stringify(body),
+    });
+
+  let response = await doRequest();
+
+  if (response.status === 401) {
+    // Invalidate the cached org-ID (if any) and retry once with a fresh
+    // lookup. For session-token callers, a 401 frequently means the
+    // cached org ID is stale — calling doRequest() again without clearing
+    // the cache would just send the same stale header and fail again.
+    orgIdCache.delete(`${token}::${platformUrl ?? ""}`);
+    response = await doRequest();
+  }
+
+  if (response.status === 201 || response.status === 200) {
+    const json = (await response.json()) as {
+      url: string;
+      bundle_key: string;
+      expires_at: string;
+      max_content_length?: number;
+    };
+    return {
+      url: json.url,
+      bundleKey: json.bundle_key,
+      expiresAt: json.expires_at,
+      maxContentLength: json.max_content_length,
+    };
+  }
+
+  const errorBody = (await response.json().catch(() => ({}))) as {
+    detail?: string;
+  };
+  throw new Error(
+    errorBody.detail ??
+      `Failed to request signed URL: ${response.status} ${response.statusText}`,
   );
+}
+
+/**
+ * Poll the unified job-status endpoint on the platform. Calls
+ * `GET /v1/migrations/jobs/{jobId}/` and parses into {@link UnifiedJobStatus}.
+ */
+export async function platformPollJobStatus(
+  jobId: string,
+  token: string,
+  platformUrl?: string,
+): Promise<UnifiedJobStatus> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(`${resolvedUrl}/v1/migrations/jobs/${jobId}/`, {
+    headers: await authHeaders(token, platformUrl),
+  });
 
   if (response.status === 404) {
-    throw new Error("Import job not found");
+    throw new Error("Migration job not found");
   }
 
   if (!response.ok) {
     throw new Error(
-      `Import status check failed: ${response.status} ${response.statusText}`,
+      `Job status check failed: ${response.status} ${response.statusText}`,
     );
   }
 
-  const body = (await response.json()) as {
-    status: string;
-    job_id?: string;
-    result?: Record<string, unknown>;
-    error?: string;
-  };
-  return {
-    status: body.status,
-    result: body.result,
-    error: body.error,
-  };
+  const raw = (await response.json()) as RawUnifiedJobStatus;
+  return parseUnifiedJobStatus(raw);
 }

package/src/lib/platform-releases.ts

@@ -7,6 +7,29 @@ export interface ResolvedImageRefs {
   source: "platform" | "dockerhub";
 }
 
+/**
+ * Fetch the latest stable release version from the platform API.
+ * Returns the version string (e.g. "0.7.0") or null if unavailable.
+ * The releases endpoint returns entries ordered newest-first.
+ */
+export async function fetchLatestStableVersion(): Promise<string | null> {
+  try {
+    const platformUrl = getPlatformUrl();
+    const response = await fetch(`${platformUrl}/v1/releases/?stable=true`, {
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return null;
+
+    const releases = (await response.json()) as Array<{
+      version?: string;
+    }>;
+    const first = releases[0];
+    return first?.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Resolve image references for a given version.
  *

package/src/lib/retire-local.ts

@@ -2,7 +2,11 @@ import { spawn } from "child_process";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
 
-import { getBaseDir, loadAllAssistants } from "./assistant-config.js";
+import {
+  getBaseDir,
+  getDaemonPidPath,
+  loadAllAssistants,
+} from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
 import {
   stopOrphanedDaemonProcesses,
@@ -41,7 +45,7 @@ export async function retireLocal(
     return;
   }
 
-  const daemonPidFile = resources.pidFile;
+  const daemonPidFile = getDaemonPidPath(resources);
   const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon");
 
   // Stop gateway via PID file — use a longer timeout because the gateway has a

package/src/lib/runtime-url.ts

@@ -0,0 +1,30 @@
+import type { AssistantEntry } from "./assistant-config.js";
+
+/**
+ * Resolve the URL for a runtime migration endpoint, taking the assistant's
+ * topology into account.
+ *
+ * - For local/docker assistants, `runtimeUrl` is the loopback gateway and
+ *   the runtime serves `/v1/migrations/<subpath>` directly. The CLI hits
+ *   that path with guardian-token bearer auth.
+ * - For platform-managed (cloud="vellum") assistants, `runtimeUrl` is the
+ *   platform host (e.g. `https://platform.vellum.ai`). The platform's
+ *   `MigrationViewSet` does NOT expose `export-to-gcs` or arbitrary runtime
+ *   migration paths under `/v1/migrations/...`. The wildcard runtime proxy
+ *   at `/v1/assistants/<id>/<path:rest>` is what forwards arbitrary runtime
+ *   paths to the managed runtime — vembda's unified proxy bootstraps the
+ *   guardian token internally for the runtime call. From the CLI side it's
+ *   user-session auth.
+ *
+ * The `subpath` is appended to the migrations namespace verbatim
+ * (e.g. `"export-to-gcs"`, `"import-from-gcs"`, `\`jobs/${jobId}\``).
+ */
+export function resolveRuntimeMigrationUrl(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  subpath: string,
+): string {
+  if (entry.cloud === "vellum") {
+    return `${entry.runtimeUrl}/v1/assistants/${entry.assistantId}/migrations/${subpath}`;
+  }
+  return `${entry.runtimeUrl}/v1/migrations/${subpath}`;
+}

package/src/lib/sync-cloud-assistants.ts

@@ -0,0 +1,126 @@
+/**
+ * Sync cloud-managed (platform) assistants into the local lockfile.
+ *
+ * - Adds new platform assistants that aren't in the lockfile yet.
+ * - Removes lockfile entries whose IDs are no longer returned by the platform
+ *   (e.g. retired assistants).
+ *
+ * Used by both `vellum login` and `vellum ps` to keep the lockfile fresh.
+ */
+
+import {
+  loadAllAssistants,
+  removeAssistantEntry,
+  saveAssistantEntry,
+} from "./assistant-config.js";
+import {
+  fetchCurrentUser,
+  fetchPlatformAssistants,
+  getPlatformUrl,
+  readPlatformToken,
+} from "./platform-client.js";
+
+export type SyncLogger = (message: string) => void;
+
+export interface SyncResult {
+  added: number;
+  removed: number;
+  email?: string;
+}
+
+export interface SyncOptions {
+  log?: SyncLogger;
+}
+
+/**
+ * Fetch platform assistants and reconcile against the lockfile.
+ * Returns the number of entries added/removed, or `null` if the user
+ * is not logged in or the fetch fails.
+ */
+export async function syncCloudAssistants(
+  options?: SyncOptions,
+): Promise<SyncResult | null> {
+  const log = options?.log;
+  const platformUrl = getPlatformUrl();
+  log?.(`Platform URL: ${platformUrl}`);
+
+  const token = readPlatformToken();
+  if (!token) {
+    log?.("No platform token found — skipping cloud sync");
+    return null;
+  }
+  log?.(
+    `Token found (${token.length} chars, prefix: ${token.slice(0, 6)}…)`,
+  );
+
+  // Fetch user info for the login status line
+  let email: string | undefined;
+  try {
+    log?.("Fetching current user…");
+    const user = await fetchCurrentUser(token);
+    email = user.email;
+    log?.(`Authenticated as ${user.email} (${user.id})`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log?.(`Failed to fetch current user: ${msg}`);
+  }
+
+  let platformAssistants: { id: string; name: string; status: string }[];
+  try {
+    log?.("Fetching platform assistants…");
+    platformAssistants = await fetchPlatformAssistants(token);
+    log?.(
+      `Platform returned ${platformAssistants.length} assistant(s): ${platformAssistants.map((a) => a.name || a.id).join(", ") || "(none)"}`,
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log?.(`fetchPlatformAssistants failed: ${msg}`);
+    return null;
+  }
+
+  if (platformAssistants.length === 0) {
+    log?.(
+      "Platform returned 0 assistants — this may mean the API returned a non-ok status (check token validity)",
+    );
+  }
+
+  const platformIds = new Set(platformAssistants.map((a) => a.id));
+
+  // Add new platform assistants not yet in the lockfile
+  const existingCloudIds = new Set(
+    loadAllAssistants()
+      .filter((a) => a.cloud === "vellum")
+      .map((a) => a.assistantId),
+  );
+  log?.(
+    `Lockfile has ${existingCloudIds.size} cloud assistant(s): ${[...existingCloudIds].join(", ") || "(none)"}`,
+  );
+
+  let added = 0;
+  for (const pa of platformAssistants) {
+    if (!existingCloudIds.has(pa.id)) {
+      log?.(`Adding ${pa.name || pa.id} to lockfile`);
+      saveAssistantEntry({
+        assistantId: pa.id,
+        runtimeUrl: getPlatformUrl(),
+        cloud: "vellum",
+        species: "vellum",
+        hatchedAt: new Date().toISOString(),
+      });
+      added++;
+    }
+  }
+
+  // Remove stale lockfile entries that the platform no longer knows about
+  let removed = 0;
+  for (const id of existingCloudIds) {
+    if (!platformIds.has(id)) {
+      log?.(`Removing stale entry ${id} from lockfile`);
+      removeAssistantEntry(id);
+      removed++;
+    }
+  }
+
+  log?.(`Sync complete: ${added} added, ${removed} removed`);
+  return { added, removed, email };
+}

package/src/lib/terminal-client.ts

@@ -18,14 +18,19 @@ export async function createTerminalSession(
   cols: number,
   rows: number,
   platformUrl?: string,
+  service?: string,
 ): Promise<{ session_id: string }> {
   const baseUrl = platformUrl || getPlatformUrl();
+  const body: Record<string, unknown> = { cols, rows };
+  if (service) {
+    body.service = service;
+  }
   const response = await fetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/`,
     {
       method: "POST",
       headers: await authHeaders(token, platformUrl),
-      body: JSON.stringify({ cols, rows }),
+      body: JSON.stringify(body),
     },
   );
   if (!response.ok) {