@vellumai/cli 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

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

@@ -1123,6 +1123,7 @@ async function tryInjectPlatformCredentials(
       fetchCurrentVersion(entry.runtimeUrl),
       fetchAssistantIngressUrl(entry.runtimeUrl, entry.bearerToken),
     ]);
+    const platformUrl = getPlatformUrl();
     const registration = await ensureSelfHostedLocalRegistration(
       token,
       orgId,
@@ -1130,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).
@@ -1164,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,

package/src/lib/docker.ts

@@ -35,8 +35,9 @@ import {
   loadImageViaHost,
 } from "./host-image-loader.js";
 import {
-  fetchLatestStableVersion,
+  fetchLatestVersion,
   resolveImageRefs,
+  type ReleaseChannel,
 } from "./platform-releases.js";
 import {
   configureHatchProviderApiKey,
@@ -321,6 +322,15 @@ export interface HatchDockerParams {
    * connection.
    */
   assistantCaCertPath?: string;
+  /**
+   * Release channel to resolve published images from when hatching without a
+   * local source tree (the image-pull fallback). `stable` (default) keeps the
+   * latest-stable behavior; `preview` pulls the latest preview release. Only
+   * affects the pull path — a local source build ignores it. Falls back to
+   * the `VELLUM_HATCH_CHANNEL` env var when unset, so callers that hatch via
+   * env (e.g. evals) can opt in without changing the invocation.
+   */
+  channel?: ReleaseChannel;
 }
 
 export type DockerProviderCredentialSetupAction =
@@ -1093,6 +1103,14 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
     flagEnvVars = {},
   } = params;
   let watch = params.watch ?? false;
+  // Resolve the release channel for the image-pull fallback: explicit param
+  // wins, then the VELLUM_HATCH_CHANNEL env var, else stable. Any value other
+  // than "preview" (case-insensitive) is treated as stable.
+  const channel: ReleaseChannel =
+    params.channel ??
+    (process.env.VELLUM_HATCH_CHANNEL?.trim().toLowerCase() === "preview"
+      ? "preview"
+      : "stable");
 
   resetLogFile("hatch.log");
   const provider =
@@ -1250,8 +1268,8 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         // Resolve image refs from a remote source that may have dev/local
         // builds. If resolution is unavailable, fall back to the CLI's own
         // version so a default tag can still be resolved.
-        log("🔍 Fetching latest stable release...");
-        const latestVersion = await fetchLatestStableVersion();
+        log(`🔍 Fetching latest ${channel} release...`);
+        const latestVersion = await fetchLatestVersion(channel);
         let versionTag: string;
         if (latestVersion) {
           versionTag = latestVersion.startsWith("v")
@@ -1265,7 +1283,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
           );
         }
         log("🔍 Resolving image references...");
-        const resolved = await resolveImageRefs(versionTag, log);
+        const resolved = await resolveImageRefs(versionTag, log, channel);
         imageTags.assistant = resolved.imageTags.assistant;
         imageTags.gateway = resolved.imageTags.gateway;
         imageTags["credential-executor"] =

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

package/src/lib/platform-releases.ts

@@ -9,6 +9,25 @@ export interface ResolvedImageRefs {
   source: "platform" | "dockerhub";
 }
 
+/**
+ * Release channel to resolve images from. `stable` is the default and maps
+ * to the server's `stable=true` filter (unchanged behavior). `preview` opts
+ * into the platform's preview channel — the newest release regardless of
+ * stability — used by callers (e.g. evals) that want to always hatch the
+ * latest preview image instead of latest-stable.
+ */
+export type ReleaseChannel = "stable" | "preview";
+
+/**
+ * Map a channel to `fetchReleases` options. `stable` passes no `channel`
+ * param so the server keeps its `stable=true` default (we don't rely on an
+ * unverified `channel=stable` filter); `preview` requests the preview
+ * channel explicitly.
+ */
+function releasesOptsFor(channel: ReleaseChannel): { channel?: "preview" } {
+  return channel === "preview" ? { channel: "preview" } : {};
+}
+
 export interface ReleaseListItem {
   version: string;
   is_stable?: boolean;
@@ -51,15 +70,26 @@ export async function fetchReleases(opts?: {
 }
 
 /**
- * Fetch the latest stable release version from the platform API.
+ * Fetch the latest release version for a channel 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.
+ * The releases endpoint returns entries ordered newest-first, so the first
+ * entry is the latest for the requested channel.
  */
-export async function fetchLatestStableVersion(): Promise<string | null> {
-  const releases = await fetchReleases();
+export async function fetchLatestVersion(
+  channel: ReleaseChannel = "stable",
+): Promise<string | null> {
+  const releases = await fetchReleases(releasesOptsFor(channel));
   return releases?.[0]?.version ?? null;
 }
 
+/**
+ * Fetch the latest stable release version. Thin back-compat wrapper around
+ * {@link fetchLatestVersion} for existing callers.
+ */
+export async function fetchLatestStableVersion(): Promise<string | null> {
+  return fetchLatestVersion("stable");
+}
+
 export type ImageRefResolution =
   | { status: "platform"; imageTags: Record<ServiceName, string> }
   | { status: "dockerhub-fallback"; imageTags: Record<ServiceName, string> }
@@ -87,10 +117,11 @@ function dockerhubImageTags(version: string): Record<ServiceName, string> {
 export async function resolveImageRefsDetailed(
   version: string,
   log?: (msg: string) => void,
+  channel: ReleaseChannel = "stable",
 ): Promise<ImageRefResolution> {
   log?.("Resolving image references...");
 
-  const releases = await fetchReleases();
+  const releases = await fetchReleases(releasesOptsFor(channel));
   if (releases === null) {
     log?.("Platform unreachable — falling back to DockerHub tags");
     return {
@@ -151,8 +182,9 @@ export async function resolveImageRefsDetailed(
 export async function resolveImageRefs(
   version: string,
   log?: (msg: string) => void,
+  channel: ReleaseChannel = "stable",
 ): Promise<ResolvedImageRefs> {
-  const resolution = await resolveImageRefsDetailed(version, log);
+  const resolution = await resolveImageRefsDetailed(version, log, channel);
   if (resolution.status === "platform") {
     log?.("Resolved image refs from platform API");
     return { imageTags: resolution.imageTags, source: "platform" };

package/src/lib/workos-pkce.ts

@@ -33,7 +33,6 @@ export interface AuthorizeUrlOptions {
   challenge: string;
   state: string;
   loginHint?: string;
-  providerHint?: string;
 }
 
 export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
@@ -46,7 +45,7 @@ export function buildAuthorizeUrl(options: AuthorizeUrlOptions): string {
   url.searchParams.set("code_challenge_method", "S256");
   url.searchParams.set("state", options.state);
   // No `prompt`: lets the browser's existing IdP session be reused.
-  url.searchParams.set("provider", options.providerHint || "authkit");
+  url.searchParams.set("provider", "authkit");
   if (options.loginHint) url.searchParams.set("login_hint", options.loginHint);
   return url.toString();
 }