@vellumai/cli 0.5.5 → 0.5.7

package/src/lib/docker.ts

@@ -12,11 +12,13 @@ import {
   setActiveAssistant,
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
+import { writeInitialConfig } from "./config-utils";
 import { DEFAULT_GATEWAY_PORT, PROVIDER_ENV_VAR_NAMES } from "./constants";
 import type { Species } from "./constants";
-import { leaseGuardianToken } from "./guardian-token";
+import { leaseGuardianToken, saveBootstrapSecret } from "./guardian-token";
 import { isVellumProcess, stopProcess } from "./process";
 import { generateInstanceName } from "./random-name";
+import { resolveImageRefs } from "./platform-releases.js";
 import { exec, execOutput } from "./step-runner";
 import {
   closeLogFile,
@@ -464,15 +466,19 @@ async function buildAllImages(
  * can be restarted independently.
  */
 export function serviceDockerRunArgs(opts: {
+  signingKey?: string;
+  bootstrapSecret?: string;
   cesServiceToken?: string;
   extraAssistantEnv?: Record<string, string>;
   gatewayPort: number;
   imageTags: Record<ServiceName, string>;
+  defaultWorkspaceConfigPath?: string;
   instanceName: string;
   res: ReturnType<typeof dockerResourceNames>;
 }): Record<ServiceName, () => string[]> {
   const {
     cesServiceToken,
+    defaultWorkspaceConfigPath,
     extraAssistantEnv,
     gatewayPort,
     imageTags,
@@ -495,6 +501,8 @@ export function serviceDockerRunArgs(opts: {
         "-e",
         `VELLUM_ASSISTANT_NAME=${instanceName}`,
         "-e",
+        "VELLUM_CLOUD=docker",
+        "-e",
         "RUNTIME_HTTP_HOST=0.0.0.0",
         "-e",
         "WORKSPACE_DIR=/workspace",
@@ -503,9 +511,21 @@ export function serviceDockerRunArgs(opts: {
         "-e",
         `GATEWAY_INTERNAL_URL=http://${res.gatewayContainer}:${GATEWAY_INTERNAL_PORT}`,
       ];
+      if (defaultWorkspaceConfigPath) {
+        const containerPath = `/tmp/vellum-default-workspace-config-${Date.now()}.json`;
+        args.push(
+          "-v",
+          `${defaultWorkspaceConfigPath}:${containerPath}:ro`,
+          "-e",
+          `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH=${containerPath}`,
+        );
+      }
       if (cesServiceToken) {
         args.push("-e", `CES_SERVICE_TOKEN=${cesServiceToken}`);
       }
+      if (opts.signingKey) {
+        args.push("-e", `ACTOR_TOKEN_SIGNING_KEY=${opts.signingKey}`);
+      }
       for (const envVar of [
         ...Object.values(PROVIDER_ENV_VAR_NAMES),
         "VELLUM_PLATFORM_URL",
@@ -552,6 +572,12 @@ export function serviceDockerRunArgs(opts: {
       ...(cesServiceToken
         ? ["-e", `CES_SERVICE_TOKEN=${cesServiceToken}`]
         : []),
+      ...(opts.signingKey
+        ? ["-e", `ACTOR_TOKEN_SIGNING_KEY=${opts.signingKey}`]
+        : []),
+      ...(opts.bootstrapSecret
+        ? ["-e", `GUARDIAN_BOOTSTRAP_SECRET=${opts.bootstrapSecret}`]
+        : []),
       imageTags.gateway,
     ],
     "credential-executor": () => [
@@ -735,10 +761,13 @@ export const SERVICE_START_ORDER: ServiceName[] = [
 /** Start all three containers in dependency order. */
 export async function startContainers(
   opts: {
+    signingKey?: string;
+    bootstrapSecret?: string;
     cesServiceToken?: string;
     extraAssistantEnv?: Record<string, string>;
     gatewayPort: number;
     imageTags: Record<ServiceName, string>;
+    defaultWorkspaceConfigPath?: string;
     instanceName: string;
     res: ReturnType<typeof dockerResourceNames>;
   },
@@ -760,6 +789,7 @@ export async function stopContainers(
   await removeContainer(res.assistantContainer);
 }
 
+
 /** Stop containers without removing them (preserves state for `docker start`). */
 export async function sleepContainers(
   res: ReturnType<typeof dockerResourceNames>,
@@ -771,8 +801,14 @@ export async function sleepContainers(
   ]) {
     try {
       await exec("docker", ["stop", container]);
-    } catch {
-      // container may not exist or already stopped
+    } catch (err) {
+      const msg =
+        err instanceof Error ? err.message.toLowerCase() : String(err);
+      if (msg.includes("no such container") || msg.includes("is not running")) {
+        // container doesn't exist or already stopped — expected, skip
+        continue;
+      }
+      throw err;
     }
   }
 }
@@ -996,6 +1032,7 @@ export async function hatchDocker(
   detached: boolean,
   name: string | null,
   watch: boolean = false,
+  configValues: Record<string, string> = {},
 ): Promise<void> {
   resetLogFile("hatch.log");
 
@@ -1042,14 +1079,16 @@ export async function hatchDocker(
     } else {
       const version = cliPkg.version;
       const versionTag = version ? `v${version}` : "latest";
-      imageTags.assistant = `${DOCKERHUB_IMAGES.assistant}:${versionTag}`;
-      imageTags.gateway = `${DOCKERHUB_IMAGES.gateway}:${versionTag}`;
+      log("🔍 Resolving image references...");
+      const resolved = await resolveImageRefs(versionTag, log);
+      imageTags.assistant = resolved.imageTags.assistant;
+      imageTags.gateway = resolved.imageTags.gateway;
       imageTags["credential-executor"] =
-        `${DOCKERHUB_IMAGES["credential-executor"]}:${versionTag}`;
+        resolved.imageTags["credential-executor"];
 
       log(`🥚 Hatching Docker assistant: ${instanceName}`);
       log(`   Species: ${species}`);
-      log(`   Images:`);
+      log(`   Images (${resolved.source}):`);
       log(`     assistant:            ${imageTags.assistant}`);
       log(`     gateway:              ${imageTags.gateway}`);
       log(`     credential-executor:  ${imageTags["credential-executor"]}`);
@@ -1071,9 +1110,37 @@ export async function hatchDocker(
     await exec("docker", ["volume", "create", res.cesSecurityVolume]);
     await exec("docker", ["volume", "create", res.gatewaySecurityVolume]);
 
+    // Set workspace volume ownership so non-root containers (UID 1001) can write.
+    await exec("docker", [
+      "run",
+      "--rm",
+      "-v",
+      `${res.workspaceVolume}:/workspace`,
+      "busybox",
+      "chown",
+      "1001:1001",
+      "/workspace",
+    ]);
+
+    // Write --config key=value pairs to a temp file that gets bind-mounted
+    // into the assistant container and read via VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH.
+    const defaultWorkspaceConfigPath = writeInitialConfig(configValues);
+
     const cesServiceToken = randomBytes(32).toString("hex");
+    const signingKey = randomBytes(32).toString("hex");
+    const bootstrapSecret = randomBytes(32).toString("hex");
+    saveBootstrapSecret(instanceName, bootstrapSecret);
     await startContainers(
-      { cesServiceToken, gatewayPort, imageTags, instanceName, res },
+      {
+        signingKey,
+        bootstrapSecret,
+        cesServiceToken,
+        gatewayPort,
+        imageTags,
+        defaultWorkspaceConfigPath,
+        instanceName,
+        res,
+      },
       log,
     );
 
@@ -1252,7 +1319,9 @@ async function waitForGatewayAndLease(opts: {
       // Log periodically so the user knows we're still trying
       const elapsed = ((Date.now() - leaseStart) / 1000).toFixed(0);
       log(
-        `Guardian token lease: attempt failed after ${elapsed}s (${lastLeaseError.split("\n")[0]}), retrying...`,
+        `Guardian token lease: attempt failed after ${elapsed}s (${
+          lastLeaseError.split("\n")[0]
+        }), retrying...`,
       );
     }
     await new Promise((r) => setTimeout(r, 2000));
@@ -1260,7 +1329,10 @@ async function waitForGatewayAndLease(opts: {
 
   if (!leaseSuccess) {
     log(
-      `\u26a0\ufe0f  Guardian token lease: FAILED after ${((Date.now() - leaseStart) / 1000).toFixed(1)}s — ${lastLeaseError ?? "unknown error"}`,
+      `\u26a0\ufe0f  Guardian token lease: FAILED after ${(
+        (Date.now() - leaseStart) /
+        1000
+      ).toFixed(1)}s — ${lastLeaseError ?? "unknown error"}`,
     );
   }
 

package/src/lib/doctor-client.ts

@@ -1,4 +1,4 @@
-const DOCTOR_URL = "https://doctor.vellum.ai";
+const DOCTOR_URL = process.env.DOCTOR_SERVICE_URL?.trim() || "";
 
 export type ProgressPhase =
   | "invoking_prompt"
@@ -107,6 +107,16 @@ async function callDoctorDaemon(
   chatContext?: ChatLogEntry[],
   onLog?: DoctorLogCallback,
 ): Promise<DoctorResult> {
+  if (!DOCTOR_URL) {
+    onLog?.("Doctor service not configured (DOCTOR_SERVICE_URL is not set)");
+    return {
+      assistantId,
+      diagnostics: null,
+      recommendation: null,
+      error: "Doctor service not configured",
+    };
+  }
+
   const MAX_RETRIES = 2;
   let lastError: unknown;
 

package/src/lib/gcp.ts

@@ -11,6 +11,7 @@ import {
 } from "./constants";
 import type { Species } from "./constants";
 import { leaseGuardianToken } from "./guardian-token";
+import { getPlatformUrl } from "./platform-client";
 import { generateInstanceName } from "./random-name";
 import { exec, execOutput } from "./step-runner";
 
@@ -455,6 +456,7 @@ export async function hatchGcp(
     providerApiKeys: Record<string, string>,
     instanceName: string,
     cloud: "gcp",
+    configValues?: Record<string, string>,
   ) => Promise<string>,
   watchHatching: (
     pollFn: () => Promise<PollResult>,
@@ -462,6 +464,7 @@ export async function hatchGcp(
     startTime: number,
     species: Species,
   ) => Promise<WatchHatchingResult>,
+  configValues: Record<string, string> = {},
 ): Promise<void> {
   const startTime = Date.now();
   const account = process.env.GCP_ACCOUNT_EMAIL;
@@ -525,6 +528,7 @@ export async function hatchGcp(
       providerApiKeys,
       instanceName,
       "gcp",
+      configValues,
     );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
@@ -640,7 +644,7 @@ export async function hatchGcp(
           species === "vellum" &&
           (await checkCurlFailure(instanceName, project, zone, account))
         ) {
-          const installScriptUrl = `${process.env.VELLUM_PLATFORM_URL ?? "https://vellum.ai"}/install.sh`;
+          const installScriptUrl = `${getPlatformUrl()}/install.sh`;
           console.log(
             `\ud83d\udd04 Detected install script curl failure for ${installScriptUrl}, attempting recovery...`,
           );

package/src/lib/guardian-token.ts

@@ -42,6 +42,46 @@ function getPersistedDeviceIdPath(): string {
   return join(getXdgConfigHome(), "vellum", "device-id");
 }
 
+function getBootstrapSecretPath(assistantId: string): string {
+  return join(
+    getXdgConfigHome(),
+    "vellum",
+    "assistants",
+    assistantId,
+    "bootstrap-secret",
+  );
+}
+
+/**
+ * Load a previously saved bootstrap secret for the given assistant.
+ * Returns null if the file does not exist or is unreadable.
+ */
+export function loadBootstrapSecret(assistantId: string): string | null {
+  try {
+    const raw = readFileSync(getBootstrapSecretPath(assistantId), "utf-8").trim();
+    return raw.length > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist a bootstrap secret for the given assistant so that the desktop
+ * client and upgrade/rollback paths can retrieve it later.
+ */
+export function saveBootstrapSecret(
+  assistantId: string,
+  secret: string,
+): void {
+  const path = getBootstrapSecretPath(assistantId);
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(path, secret + "\n", { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
 function hashWithSalt(input: string): string {
   return createHash("sha256")
     .update(input + DEVICE_ID_SALT)
@@ -168,9 +208,14 @@ export async function leaseGuardianToken(
   assistantId: string,
 ): Promise<GuardianTokenData> {
   const deviceId = computeDeviceId();
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  const bootstrapSecret = loadBootstrapSecret(assistantId);
+  if (bootstrapSecret) {
+    headers["x-bootstrap-secret"] = bootstrapSecret;
+  }
   const response = await fetch(`${gatewayUrl}/v1/guardian/init`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers,
     body: JSON.stringify({ platform: "cli", deviceId }),
   });
 

package/src/lib/health-check.ts

@@ -3,11 +3,13 @@ export const HEALTH_CHECK_TIMEOUT_MS = 1500;
 interface HealthResponse {
   status: string;
   message?: string;
+  version?: string;
 }
 
 export interface HealthCheckResult {
   status: string;
   detail: string | null;
+  version?: string;
 }
 
 export async function checkManagedHealth(
@@ -63,6 +65,7 @@ export async function checkManagedHealth(
     return {
       status,
       detail: status !== "healthy" ? (data.message ?? null) : null,
+      version: data.version,
     };
   } catch (error) {
     const status =
@@ -108,6 +111,7 @@ export async function checkHealth(
     return {
       status,
       detail: status !== "healthy" ? (data.message ?? null) : null,
+      version: data.version,
     };
   } catch (error) {
     const status =

package/src/lib/local.ts

@@ -192,10 +192,15 @@ function resolveDaemonMainPath(assistantIndex: string): string {
   return join(dirname(assistantIndex), "daemon", "main.ts");
 }
 
+type DaemonStartOptions = {
+  foreground?: boolean;
+  defaultWorkspaceConfigPath?: string;
+};
+
 async function startDaemonFromSource(
   assistantIndex: string,
   resources: LocalInstanceResources,
-  options?: { foreground?: boolean },
+  options?: DaemonStartOptions,
 ): Promise<void> {
   const foreground = options?.foreground ?? false;
   const daemonMainPath = resolveDaemonMainPath(assistantIndex);
@@ -260,6 +265,7 @@ async function startDaemonFromSource(
   const env: Record<string, string | undefined> = {
     ...process.env,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
+    VELLUM_CLOUD: "local",
   };
   if (resources) {
     env.BASE_DATA_DIR = resources.instanceDir;
@@ -268,6 +274,10 @@ async function startDaemonFromSource(
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
     delete env.QDRANT_URL;
   }
+  if (options?.defaultWorkspaceConfigPath) {
+    env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
+      options.defaultWorkspaceConfigPath;
+  }
 
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
@@ -306,6 +316,7 @@ async function startDaemonFromSource(
 async function startDaemonWatchFromSource(
   assistantIndex: string,
   resources: LocalInstanceResources,
+  options?: DaemonStartOptions,
 ): Promise<void> {
   const mainPath = resolveDaemonMainPath(assistantIndex);
   if (!existsSync(mainPath)) {
@@ -381,6 +392,10 @@ async function startDaemonWatchFromSource(
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
     delete env.QDRANT_URL;
   }
+  if (options?.defaultWorkspaceConfigPath) {
+    env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
+      options.defaultWorkspaceConfigPath;
+  }
 
   // Write a sentinel PID file before spawning so concurrent hatch() calls
   // detect the in-progress spawn and wait instead of racing.
@@ -819,7 +834,7 @@ export function isGatewayWatchModeAvailable(): boolean {
 export async function startLocalDaemon(
   watch: boolean = false,
   resources: LocalInstanceResources,
-  options?: { foreground?: boolean },
+  options?: DaemonStartOptions,
 ): Promise<void> {
   const foreground = options?.foreground ?? false;
   // Check for a compiled daemon binary adjacent to the CLI executable.
@@ -905,7 +920,7 @@ export async function startLocalDaemon(
 
       // Build a minimal environment for the daemon. When launched from the
       // macOS app the CLI inherits a huge environment (XPC_SERVICE_NAME,
-      // __CFBundleIdentifier, CLAUDE_CODE_ENTRYPOINT, etc.) that can cause
+      // __CFBundleIdentifier, etc.) that can cause
       // the daemon to take 50+ seconds to start instead of ~1s.
       const home = homedir();
       const bunBinDir = join(home, ".bun", "bin");
@@ -924,20 +939,25 @@ export async function startLocalDaemon(
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
         "BASE_DATA_DIR",
-        "PLATFORM_BASE_URL",
+        "VELLUM_PLATFORM_URL",
         "QDRANT_HTTP_PORT",
         "QDRANT_URL",
         "RUNTIME_HTTP_PORT",
-        "SENTRY_DSN",
+        "SENTRY_DSN_ASSISTANT",
         "TMPDIR",
         "USER",
         "LANG",
         "VELLUM_DEBUG",
+        "VELLUM_DESKTOP_APP",
       ]) {
         if (process.env[key]) {
           daemonEnv[key] = process.env[key]!;
         }
       }
+      if (options?.defaultWorkspaceConfigPath) {
+        daemonEnv.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
+          options.defaultWorkspaceConfigPath;
+      }
       // When running a named instance, override env so the daemon resolves
       // all paths under the instance directory and listens on its own port.
       if (resources) {
@@ -1005,9 +1025,9 @@ export async function startLocalDaemon(
         // Kill the bundled daemon to avoid two processes competing for the same port
         await stopProcessByPidFile(pidFile, "bundled daemon");
         if (watch) {
-          await startDaemonWatchFromSource(assistantIndex, resources);
+          await startDaemonWatchFromSource(assistantIndex, resources, options);
         } else {
-          await startDaemonFromSource(assistantIndex, resources);
+          await startDaemonFromSource(assistantIndex, resources, options);
         }
         daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       }
@@ -1031,7 +1051,7 @@ export async function startLocalDaemon(
       );
     }
     if (watch) {
-      await startDaemonWatchFromSource(assistantIndex, resources);
+      await startDaemonWatchFromSource(assistantIndex, resources, options);
 
       const daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       if (daemonReady) {
@@ -1042,7 +1062,7 @@ export async function startLocalDaemon(
         );
       }
     } else {
-      await startDaemonFromSource(assistantIndex, resources, { foreground });
+      await startDaemonFromSource(assistantIndex, resources, options);
 
       const daemonReady = await waitForDaemonReady(resources.daemonPort, 60000);
       if (daemonReady) {

package/src/lib/platform-client.ts

@@ -9,7 +9,7 @@ import {
 import { homedir } from "os";
 import { join, dirname } from "path";
 
-const DEFAULT_PLATFORM_URL = "https://platform.vellum.ai";
+const DEFAULT_PLATFORM_URL = "";
 
 function getXdgConfigHome(): string {
   return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
@@ -23,6 +23,20 @@ export function getPlatformUrl(): string {
   return process.env.VELLUM_PLATFORM_URL ?? DEFAULT_PLATFORM_URL;
 }
 
+/**
+ * Returns the platform URL, throwing a clear error if it is not configured.
+ * Use this in functions that need a valid URL to make HTTP requests.
+ */
+function requirePlatformUrl(): string {
+  const url = getPlatformUrl();
+  if (!url) {
+    throw new Error(
+      "VELLUM_PLATFORM_URL is not configured. Set it in your environment or .env file.",
+    );
+  }
+  return url;
+}
+
 export function readPlatformToken(): string | null {
   try {
     return readFileSync(getPlatformTokenPath(), "utf-8").trim();
@@ -60,14 +74,15 @@ interface OrganizationListResponse {
 }
 
 export async function fetchOrganizationId(token: string): Promise<string> {
-  const url = `${getPlatformUrl()}/v1/organizations/`;
+  const platformUrl = requirePlatformUrl();
+  const url = `${platformUrl}/v1/organizations/`;
   const response = await fetch(url, {
     headers: { "X-Session-Token": token },
   });
 
   if (!response.ok) {
     throw new Error(
-      `Failed to fetch organizations (${response.status}). Try logging in again.`,
+      `Failed to fetch organizations from ${platformUrl} (${response.status}). Try logging in again.`,
     );
   }
 
@@ -91,7 +106,7 @@ interface AllauthSessionResponse {
 }
 
 export async function fetchCurrentUser(token: string): Promise<PlatformUser> {
-  const url = `${getPlatformUrl()}/_allauth/app/v1/auth/session`;
+  const url = `${requirePlatformUrl()}/_allauth/app/v1/auth/session`;
   const response = await fetch(url, {
     headers: { "X-Session-Token": token },
   });

package/src/lib/platform-releases.ts

@@ -0,0 +1,112 @@
+import { getPlatformUrl } from "./platform-client.js";
+import { DOCKERHUB_IMAGES } from "./docker.js";
+import type { ServiceName } from "./docker.js";
+
+export interface ResolvedImageRefs {
+  imageTags: Record<ServiceName, string>;
+  source: "platform" | "dockerhub";
+}
+
+/**
+ * Resolve image references for a given version.
+ *
+ * Tries the platform API first (returns GCR digest-based refs when available),
+ * then falls back to DockerHub tag-based refs when the platform is unreachable
+ * or the version is not found.
+ */
+export async function resolveImageRefs(
+  version: string,
+  log?: (msg: string) => void,
+): Promise<ResolvedImageRefs> {
+  log?.("Resolving image references...");
+
+  const platformRefs = await fetchPlatformImageRefs(version, log);
+  if (platformRefs) {
+    log?.("Resolved image refs from platform API");
+    return { imageTags: platformRefs, source: "platform" };
+  }
+
+  log?.("Falling back to DockerHub tags");
+  const imageTags: Record<ServiceName, string> = {
+    assistant: `${DOCKERHUB_IMAGES.assistant}:${version}`,
+    "credential-executor": `${DOCKERHUB_IMAGES["credential-executor"]}:${version}`,
+    gateway: `${DOCKERHUB_IMAGES.gateway}:${version}`,
+  };
+  return { imageTags, source: "dockerhub" };
+}
+
+/**
+ * Fetch image references from the platform releases API.
+ *
+ * Returns a record of service name to image ref (GCR digest-based) for the
+ * given version, or null if the platform is unreachable, the version is not
+ * found, or any error occurs.
+ */
+async function fetchPlatformImageRefs(
+  version: string,
+  log?: (msg: string) => void,
+): Promise<Record<ServiceName, string> | null> {
+  try {
+    const platformUrl = getPlatformUrl();
+    const url = `${platformUrl}/v1/releases/?stable=true`;
+
+    log?.(`Fetching releases from ${url}`);
+
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!response.ok) {
+      log?.(`Platform API returned ${response.status}`);
+      return null;
+    }
+
+    const releases = (await response.json()) as Array<{
+      version?: string;
+      assistant_image_ref?: string | null;
+      gateway_image_ref?: string | null;
+      credential_executor_image_ref?: string | null;
+    }>;
+
+    // Strip leading "v" from the requested version for matching
+    const normalizedVersion = version.replace(/^v/, "");
+
+    const release = releases.find((r) => {
+      const releaseVersion = (r.version ?? "").replace(/^v/, "");
+      return releaseVersion === normalizedVersion;
+    });
+
+    if (!release) {
+      log?.(`Version ${version} not found in platform releases`);
+      return null;
+    }
+
+    const assistantImage = release.assistant_image_ref;
+    const gatewayImage = release.gateway_image_ref;
+    let credentialExecutorImage = release.credential_executor_image_ref;
+
+    // Assistant and gateway images are required; credential-executor falls back to DockerHub
+    if (!assistantImage || !gatewayImage) {
+      log?.("Platform release missing required image refs");
+      return null;
+    }
+
+    // Fall back to DockerHub for credential-executor if its image ref is null
+    if (!credentialExecutorImage) {
+      credentialExecutorImage = `${DOCKERHUB_IMAGES["credential-executor"]}:${version}`;
+      log?.(
+        "credential-executor image not in platform release, using DockerHub fallback",
+      );
+    }
+
+    return {
+      assistant: assistantImage,
+      "credential-executor": credentialExecutorImage,
+      gateway: gatewayImage,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log?.(`Platform image ref resolution failed: ${message}`);
+    return null;
+  }
+}