@vellumai/cli 0.10.4-dev.202607012136.5ef7865 → 0.10.4-dev.202607012234.a9be056

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.4-dev.202607012136.5ef7865",
+  "version": "0.10.4-dev.202607012234.a9be056",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/platform-releases.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 import {
+  fetchLatestVersion,
   fetchReleases,
   resolveImageRefsDetailed,
 } from "../lib/platform-releases.js";
@@ -114,4 +115,45 @@ describe("resolveImageRefsDetailed", () => {
     const result = await resolveImageRefsDetailed("0.7.0");
     expect(result.status).toBe("dockerhub-fallback");
   });
+
+  test("requests the preview channel when channel=preview", async () => {
+    const fetchMock = mockFetchJson([RELEASE]);
+    await resolveImageRefsDetailed("v0.7.0", undefined, "preview");
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toContain("channel=preview");
+    expect(url).not.toContain("stable=true");
+  });
+
+  test("keeps the stable filter when channel=stable (default)", async () => {
+    const fetchMock = mockFetchJson([RELEASE]);
+    await resolveImageRefsDetailed("v0.7.0", undefined, "stable");
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toContain("stable=true");
+    expect(url).not.toContain("channel=");
+  });
+});
+
+describe("fetchLatestVersion", () => {
+  test("defaults to the stable channel", async () => {
+    const fetchMock = mockFetchJson([RELEASE]);
+    const version = await fetchLatestVersion();
+    expect(version).toBe("0.7.0");
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toContain("stable=true");
+    expect(url).not.toContain("channel=");
+  });
+
+  test("requests the preview channel when asked", async () => {
+    const preview = { ...RELEASE, version: "0.8.0-preview.3" };
+    const fetchMock = mockFetchJson([preview]);
+    const version = await fetchLatestVersion("preview");
+    expect(version).toBe("0.8.0-preview.3");
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toContain("channel=preview");
+  });
+
+  test("returns null when the channel has no releases", async () => {
+    mockFetchJson([]);
+    expect(await fetchLatestVersion("preview")).toBeNull();
+  });
 });

package/src/commands/hatch.ts

@@ -178,6 +178,7 @@ interface HatchArgs {
   remote: RemoteHost;
   watch: boolean;
   sourcePath: string | null;
+  preview: boolean;
   configValues: Record<string, string>;
   flagEnvVars: Record<string, string>;
   analyze: boolean;
@@ -203,6 +204,7 @@ function parseArgs(): HatchArgs {
   let remote: RemoteHost = DEFAULT_REMOTE;
   let watch = false;
   let sourcePath: string | null = null;
+  let preview = false;
   const configValues: Record<string, string> = {};
   let analyze = false;
   let netnsContainer: string | null = null;
@@ -231,6 +233,7 @@ function parseArgs(): HatchArgs {
       );
       console.log(
         "  --source <path>           Build images from a local source tree at <path> (no watcher). Useful for callers (e.g. evals) that want each run to pick up local CLI changes.",
+        "  --preview                 When pulling published images (no local source), resolve from the preview channel (latest preview release) instead of latest-stable. Also settable via VELLUM_HATCH_CHANNEL=preview.",
       );
       console.log(
         "  --keep-alive              Stay alive after hatch, exit when gateway stops",
@@ -263,6 +266,8 @@ function parseArgs(): HatchArgs {
       watch = true;
     } else if (arg === "--analyze") {
       analyze = true;
+    } else if (arg === "--preview") {
+      preview = true;
     } else if (arg === "--source") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
@@ -349,7 +354,7 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --flag <key=value>, --analyze, --disable-platform, --netns-container <name>, --gateway-port <port>, --assistant-ca-cert <path>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --preview, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --flag <key=value>, --analyze, --disable-platform, --netns-container <name>, --gateway-port <port>, --assistant-ca-cert <path>`,
       );
       process.exit(1);
     }
@@ -363,6 +368,7 @@ function parseArgs(): HatchArgs {
     remote,
     watch,
     sourcePath,
+    preview,
     configValues,
     flagEnvVars,
     analyze,
@@ -602,6 +608,7 @@ export async function hatch(): Promise<void> {
     remote,
     watch,
     sourcePath,
+    preview,
     configValues,
     flagEnvVars,
     analyze,
@@ -681,6 +688,7 @@ export async function hatch(): Promise<void> {
       flagEnvVars,
       sourcePath,
       analyze,
+      channel: preview ? "preview" : undefined,
       netnsContainer: netnsContainer ?? undefined,
       gatewayPort: gatewayPort ?? undefined,
       assistantCaCertPath: assistantCaCert ?? undefined,

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-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" };