@vellumai/cli 0.10.3 → 0.10.4-dev.202607010119.ad15dbb

package/src/commands/retire.ts

@@ -20,7 +20,9 @@ import { getConfigDir } from "../lib/environments/paths.js";
 import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 import {
   authHeaders,
+  authHeadersForKnownOrganization,
   getPlatformUrl,
+  readGatewayCredential,
   readPlatformToken,
 } from "../lib/platform-client.js";
 import { retireInstance as retireAwsInstance } from "../lib/aws.js";
@@ -45,6 +47,180 @@ interface RetireArgs {
   yes: boolean;
 }
 
+interface SelfHostedPlatformRegistration {
+  platformAssistantId: string;
+  platformBaseUrl: string | null;
+  organizationId: string | null;
+}
+
+const PLATFORM_TOKEN_ENV = "VELLUM_PLATFORM_TOKEN";
+
+function readPlatformRetireToken(): string | null {
+  const envToken = process.env[PLATFORM_TOKEN_ENV]?.trim();
+  if (envToken) return envToken;
+  return readPlatformToken();
+}
+
+function platformOrigin(platformUrl: string): string | null {
+  try {
+    return new URL(platformUrl).origin;
+  } catch {
+    return null;
+  }
+}
+
+function resolveTrustedSelfHostedPlatformUrl(
+  storedPlatformUrl: string | null,
+): string | null {
+  const configuredPlatformUrl = getPlatformUrl();
+  if (!storedPlatformUrl) return configuredPlatformUrl;
+
+  const storedOrigin = platformOrigin(storedPlatformUrl);
+  const configuredOrigin = platformOrigin(configuredPlatformUrl);
+  if (storedOrigin && configuredOrigin && storedOrigin === configuredOrigin) {
+    return configuredPlatformUrl;
+  }
+
+  console.warn(
+    "⚠️  Stored platform URL does not match the configured platform URL; skipping platform unregister.",
+  );
+  return null;
+}
+
+function nonEmptyString(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function lockfileSelfHostedPlatformRegistration(
+  entry: AssistantEntry,
+): SelfHostedPlatformRegistration | null {
+  const platformAssistantId = nonEmptyString(entry.platformAssistantId);
+  if (!platformAssistantId) return null;
+
+  return {
+    platformAssistantId,
+    platformBaseUrl: nonEmptyString(entry.platformBaseUrl),
+    organizationId: nonEmptyString(entry.platformOrganizationId),
+  };
+}
+
+async function deletePlatformAssistant(
+  assistantId: string,
+  options: {
+    token: string;
+    platformUrl?: string;
+    organizationId?: string;
+    label: string;
+    successMessage: string;
+    alreadyGoneMessage: string;
+  },
+): Promise<void> {
+  const platformUrl = options.platformUrl || getPlatformUrl();
+  const url = `${platformUrl}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
+  const headers = options.organizationId
+    ? authHeadersForKnownOrganization(options.token, options.organizationId)
+    : await authHeaders(options.token, platformUrl);
+
+  const response = await loopbackSafeFetch(url, {
+    method: "DELETE",
+    headers,
+  });
+
+  if (!response.ok && response.status !== 404) {
+    const body = await response.text();
+    throw new Error(`${options.label} failed (${response.status}): ${body}`);
+  }
+
+  if (response.status === 404) {
+    console.log(options.alreadyGoneMessage);
+  } else {
+    console.log(options.successMessage);
+  }
+}
+
+async function readSelfHostedPlatformRegistration(
+  entry: AssistantEntry,
+): Promise<SelfHostedPlatformRegistration | null> {
+  const fallback = lockfileSelfHostedPlatformRegistration(entry);
+  const gatewayUrl = entry.localUrl ?? entry.runtimeUrl;
+  const platformAssistant = await readGatewayCredential(
+    gatewayUrl,
+    "vellum:platform_assistant_id",
+    entry.bearerToken,
+  );
+  if (platformAssistant.unreachable) {
+    if (fallback) {
+      console.warn(
+        "\u26a0\ufe0f  Could not read platform registration from the local assistant; using saved platform registration.",
+      );
+      return fallback;
+    }
+    console.warn(
+      "\u26a0\ufe0f  Could not read platform registration from the local assistant and no saved platform registration is available; skipping platform unregister.",
+    );
+    return null;
+  }
+
+  const platformAssistantId =
+    nonEmptyString(platformAssistant.value) ?? fallback?.platformAssistantId;
+  if (!platformAssistantId) return null;
+
+  const [platformBaseUrl, organizationId] = await Promise.all([
+    readGatewayCredential(
+      gatewayUrl,
+      "vellum:platform_base_url",
+      entry.bearerToken,
+    ),
+    readGatewayCredential(
+      gatewayUrl,
+      "vellum:platform_organization_id",
+      entry.bearerToken,
+    ),
+  ]);
+
+  return {
+    platformAssistantId,
+    platformBaseUrl:
+      nonEmptyString(platformBaseUrl.value) ??
+      fallback?.platformBaseUrl ??
+      null,
+    organizationId:
+      nonEmptyString(organizationId.value) ?? fallback?.organizationId ?? null,
+  };
+}
+
+async function unregisterSelfHostedLocalPlatformRecord(
+  entry: AssistantEntry,
+): Promise<void> {
+  const token = readPlatformRetireToken();
+  if (!token) return;
+
+  const registration = await readSelfHostedPlatformRegistration(entry);
+  if (!registration) return;
+
+  const platformUrl = resolveTrustedSelfHostedPlatformUrl(
+    registration.platformBaseUrl,
+  );
+  if (!platformUrl) return;
+  if (!registration.organizationId) {
+    console.warn(
+      "⚠️  Could not read platform organization ID from the local assistant; skipping platform unregister.",
+    );
+    return;
+  }
+
+  await deletePlatformAssistant(registration.platformAssistantId, {
+    token,
+    platformUrl,
+    organizationId: registration.organizationId,
+    label: "Platform self-hosted unregister",
+    successMessage: "\u2705 Platform self-hosted registration unregistered.",
+    alreadyGoneMessage:
+      "\u2705 Platform self-hosted registration already unregistered (404).",
+  });
+}
+
 async function retireCustom(entry: AssistantEntry): Promise<void> {
   const host = extractHostFromUrl(entry.runtimeUrl);
   const sshUser = entry.sshUser ?? "root";
@@ -86,7 +262,7 @@ async function retireVellum(
 ): Promise<void> {
   console.log("\u{1F5D1}\ufe0f  Retiring platform-hosted instance...\n");
 
-  const token = readPlatformToken();
+  const token = readPlatformRetireToken();
   if (!token) {
     console.error(
       "Error: Not logged in. Run `vellum login --token <token>` first.",
@@ -94,33 +270,21 @@ async function retireVellum(
     process.exit(1);
   }
 
-  const platformUrl = runtimeUrl || getPlatformUrl();
-  const url = `${platformUrl}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
-  const response = await loopbackSafeFetch(url, {
-    method: "DELETE",
-    headers: await authHeaders(token, runtimeUrl),
-  });
-
-  // Treat 404 as success: the assistant is already gone from the platform
-  // (previously retired, deleted from the web UI, or retired from another
-  // device) so the caller's job is done. Falling through to the lockfile
-  // cleanup avoids leaving a stale entry that would otherwise wedge the
-  // macOS app in a permanent health-check loop.
-  if (!response.ok && response.status !== 404) {
-    const body = await response.text();
+  try {
+    await deletePlatformAssistant(assistantId, {
+      token,
+      platformUrl: runtimeUrl,
+      label: "Platform retire",
+      successMessage: "\u2705 Platform-hosted instance retired.",
+      alreadyGoneMessage:
+        "\u2705 Platform-hosted instance already retired (404) \u2014 cleaning up local state.",
+    });
+  } catch (error) {
     console.error(
-      `Error: Platform retire failed (${response.status}): ${body}`,
+      `Error: ${error instanceof Error ? error.message : String(error)}`,
     );
     process.exit(1);
   }
-
-  if (response.status === 404) {
-    console.log(
-      "\u2705 Platform-hosted instance already retired (404) — cleaning up local state.",
-    );
-  } else {
-    console.log("\u2705 Platform-hosted instance retired.");
-  }
 }
 
 function parseRetireArgs(args: string[]): RetireArgs {
@@ -303,6 +467,15 @@ async function retireInner(): Promise<void> {
   } else if (cloud === "docker") {
     await retireDocker(assistantId);
   } else if (cloud === "local") {
+    try {
+      await unregisterSelfHostedLocalPlatformRecord(entry);
+    } catch (error) {
+      console.warn(
+        `⚠️  Platform self-hosted unregister failed; continuing local retire: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
     await retireLocal(assistantId, entry);
   } else if (cloud === "custom") {
     await retireCustom(entry);

package/src/commands/teleport.ts

@@ -33,6 +33,7 @@ import {
   localRuntimeExportToGcs,
   localRuntimeIdentity,
   localRuntimeImportFromGcs,
+  localRuntimePreflightFromGcs,
   localRuntimePollJobStatus,
   MigrationInProgressError,
 } from "../lib/local-runtime-client.js";
@@ -707,11 +708,46 @@ async function importToAssistant(
 
   if (cloud === "local" || cloud === "docker") {
     if (dryRun) {
-      // TODO(cli): support dry-run against local targets
-      console.error(
-        "Error: --dry-run is not yet supported for local or docker targets (no preflight-from-gcs endpoint on the runtime).",
+      console.log("Running preflight analysis...\n");
+
+      // Query the target runtime's version before requesting a signed
+      // download URL — the platform uses it for the bundle compatibility check.
+      let targetRuntimeVersion: string;
+      try {
+        const identity = await callRuntimeWithAuthRetry(entry, (token) =>
+          localRuntimeIdentity(entry, token),
+        );
+        targetRuntimeVersion = identity.version;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(
+          `Error: Could not read target runtime version from '${entry.assistantId}': ${msg}`,
+        );
+        console.error(`Try: vellum wake ${entry.assistantId}`);
+        process.exit(1);
+      }
+
+      let bundleUrl: string;
+      try {
+        const result = await platformRequestSignedUrl(
+          { operation: "download", bundleKey, targetRuntimeVersion },
+          platformToken,
+          bundlePlatformUrl,
+        );
+        bundleUrl = result.url;
+      } catch (err) {
+        if (err instanceof VersionMismatchError) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+        throw err;
+      }
+
+      const preflightData = await callRuntimeWithAuthRetry(entry, (token) =>
+        localRuntimePreflightFromGcs(entry, token, { bundleUrl }),
       );
-      process.exit(1);
+      printPreflightSummary(preflightData as unknown as PreflightResponse);
+      return;
     }
 
     // Ask the platform for a signed download URL and hand it to the local
@@ -1087,6 +1123,7 @@ async function tryInjectPlatformCredentials(
       fetchCurrentVersion(entry.runtimeUrl),
       fetchAssistantIngressUrl(entry.runtimeUrl, entry.bearerToken),
     ]);
+    const platformUrl = getPlatformUrl();
     const registration = await ensureSelfHostedLocalRegistration(
       token,
       orgId,
@@ -1094,9 +1131,15 @@ async function tryInjectPlatformCredentials(
       entry.assistantId,
       "cli",
       assistantVersion,
-      getPlatformUrl(),
+      platformUrl,
       ingressUrl,
     );
+    saveAssistantEntry({
+      ...entry,
+      platformAssistantId: registration.assistant.id,
+      platformBaseUrl: platformUrl,
+      platformOrganizationId: orgId,
+    });
 
     // Resolve the API key: 1) fresh from registration, 2) existing from
     // daemon credential store, 3) reprovision as last resort (revokes old key).
@@ -1128,7 +1171,7 @@ async function tryInjectPlatformCredentials(
       bearerToken: entry.bearerToken,
       assistantApiKey,
       platformAssistantId: registration.assistant.id,
-      platformBaseUrl: getPlatformUrl(),
+      platformBaseUrl: platformUrl,
       organizationId: orgId,
       userId: user.id,
       webhookSecret: registration.webhook_secret,
@@ -1231,18 +1274,8 @@ export async function teleport(): Promise<void> {
         process.exit(1);
       }
 
-      // Dry-run feasibility check — reject local/docker targets BEFORE any
-      // export work. The local runtime has no preflight-from-gcs endpoint yet,
-      // so we can't actually run a dry-run against it; burning a GCS upload
-      // just to fail afterwards would be wasteful.
-      // TODO(cli): support dry-run against local targets (needs a
-      // preflight-from-gcs endpoint on the runtime).
-      if (toCloud === "local" || toCloud === "docker") {
-        console.error(
-          "Error: --dry-run is not yet supported for local or docker targets (no preflight-from-gcs endpoint on the runtime).",
-        );
-        process.exit(1);
-      }
+      // Nothing to reject — preflight-from-gcs is now implemented for all
+      // target topologies including local and docker.
 
       // Version guard: block platform→non-platform when target is behind
       if (fromCloud === "vellum" && toCloud !== "vellum") {

package/src/lib/local-runtime-client.ts

@@ -195,6 +195,44 @@ export async function localRuntimeImportFromGcs(
   return { jobId: json.job_id };
 }
 
+/**
+ * Run a dry-run preflight analysis on a .vbundle archive stored at a signed
+ * GCS download URL.
+ *
+ * For local/docker assistants this POSTs to
+ * `{runtimeUrl}/v1/migrations/preflight-from-gcs` with guardian-token bearer
+ * auth. The daemon fetches the bundle from GCS, validates it, and returns a
+ * report of what would change on import — without writing anything to disk.
+ *
+ * Returns the raw preflight response body. Callers should cast to their
+ * local `PreflightResponse` shape (mirrors the `/import-preflight` shape).
+ */
+export async function localRuntimePreflightFromGcs(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
+  token: string,
+  params: { bundleUrl: string },
+): Promise<Record<string, unknown>> {
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, "preflight-from-gcs"),
+    {
+      method: "POST",
+      headers: await migrationRequestHeaders(entry, token),
+      body: JSON.stringify({ bundle_url: params.bundleUrl }),
+    },
+  );
+
+  if (response.status !== 200) {
+    const errText = await response.text().catch(() => "");
+    throw new Error(
+      `Local runtime preflight-from-gcs failed (${response.status}): ${
+        errText || response.statusText
+      }`,
+    );
+  }
+
+  return (await response.json()) as Record<string, unknown>;
+}
+
 /**
  * Poll the runtime's unified job-status endpoint.
  *

package/src/lib/platform-client.ts

@@ -96,6 +96,20 @@ function tokenAuthHeader(token: string): Record<string, string> {
   return { "X-Session-Token": token };
 }
 
+export function authHeadersForKnownOrganization(
+  token: string,
+  organizationId: string,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    ...tokenAuthHeader(token),
+  };
+  if (!token.startsWith(VAK_PREFIX)) {
+    headers["Vellum-Organization-Id"] = organizationId;
+  }
+  return headers;
+}
+
 /** 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