@vellumai/cli 0.8.11 → 0.8.12-staging.1

package/node_modules/@vellumai/local-mode/src/lockfile-contract.test.ts

@@ -14,6 +14,7 @@ describe("parseLockfile", () => {
           runtimeUrl: "http://127.0.0.1:7777",
           species: "vellum",
           hatchedAt: "2026-01-01T00:00:00.000Z",
+          version: "0.7.0",
           organizationId: "org_1",
           resources: { gatewayPort: 7777, daemonPort: 7778 },
         },
@@ -169,6 +170,20 @@ describe("parseLockfile", () => {
     ]);
   });
 
+  test("keeps version when a string and drops it when mistyped", () => {
+    const raw = {
+      assistants: [
+        { assistantId: "asst_1", cloud: "docker", version: "0.7.0" },
+        { assistantId: "asst_2", cloud: "docker", version: 7 }, // mistyped
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "asst_1", cloud: "docker", version: "0.7.0" },
+      { assistantId: "asst_2", cloud: "docker" },
+    ]);
+  });
+
   test("drops a resources object missing its numeric ports", () => {
     const raw = {
       assistants: [

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -42,6 +42,8 @@ export interface LockfileAssistant {
   runtimeUrl?: string;
   species?: string;
   hatchedAt?: string;
+  /** Installed release version (no `v` prefix), written by the CLI at hatch/upgrade. */
+  version?: string;
   /** Owning org for platform assistants; absent for local ones. */
   organizationId?: string;
   resources?: LocalAssistantResources;
@@ -89,6 +91,7 @@ function parseAssistant(value: unknown): LockfileAssistant | null {
   if (typeof value.runtimeUrl === "string") assistant.runtimeUrl = value.runtimeUrl;
   if (typeof value.species === "string") assistant.species = value.species;
   if (typeof value.hatchedAt === "string") assistant.hatchedAt = value.hatchedAt;
+  if (typeof value.version === "string") assistant.version = value.version;
   if (typeof value.organizationId === "string") assistant.organizationId = value.organizationId;
   const resources = parseResources(value.resources);
   if (resources) assistant.resources = resources;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.11",
+  "version": "0.8.12-staging.1",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-config.test.ts

@@ -75,11 +75,12 @@ describe("assistant-config", () => {
   });
 
   test("saveAssistantEntry and loadAllAssistants round-trip", () => {
-    const entry = makeEntry("test-1");
+    const entry = makeEntry("test-1", undefined, { version: "0.7.0" });
     saveAssistantEntry(entry);
     const all = loadAllAssistants();
     expect(all).toHaveLength(1);
     expect(all[0].assistantId).toBe("test-1");
+    expect(all[0].version).toBe("0.7.0");
   });
 
   test("findAssistantByName returns matching entry", () => {

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

@@ -9,8 +9,12 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { mock } from "bun:test";
+
 import {
   clearPlatformToken,
+  fetchAssistantDetail,
+  fetchUpgradeInProgress,
   getPlatformUrl,
   readPlatformToken,
   savePlatformToken,
@@ -202,3 +206,106 @@ describe("getPlatformUrl resolution order", () => {
     expect(getPlatformUrl()).toBe("https://trimmed.vellum.ai");
   });
 });
+
+describe("fetchAssistantDetail / fetchUpgradeInProgress", () => {
+  // vak_ token → authHeaders skips the org-ID fetch, so the single mocked
+  // fetch call is the endpoint under test.
+  const TOKEN = "vak_test_token";
+  const ASSISTANT_ID = "11111111-2222-3333-4444-555555555555";
+  const PLATFORM_URL = "https://platform.test";
+
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  function mockFetchJson(body: unknown, status = 200) {
+    const fetchMock = mock(
+      async (_url: RequestInfo | URL, _init?: RequestInit) =>
+        new Response(JSON.stringify(body), { status }),
+    );
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    return fetchMock;
+  }
+
+  function mockFetchNetworkError() {
+    globalThis.fetch = mock(async () => {
+      throw new TypeError("fetch failed");
+    }) as unknown as typeof globalThis.fetch;
+  }
+
+  test("fetchAssistantDetail maps fields", async () => {
+    const fetchMock = mockFetchJson({
+      current_release_version: "0.7.0",
+      release_channel: "preview",
+    });
+    const detail = await fetchAssistantDetail(TOKEN, ASSISTANT_ID, PLATFORM_URL);
+    expect(detail).toEqual({
+      currentReleaseVersion: "0.7.0",
+      releaseChannel: "preview",
+    });
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toBe(`${PLATFORM_URL}/v1/assistants/${ASSISTANT_ID}/`);
+  });
+
+  test("fetchAssistantDetail defaults missing fields", async () => {
+    mockFetchJson({});
+    const detail = await fetchAssistantDetail(TOKEN, ASSISTANT_ID, PLATFORM_URL);
+    expect(detail).toEqual({
+      currentReleaseVersion: null,
+      releaseChannel: "stable",
+    });
+  });
+
+  test("fetchAssistantDetail returns null on non-OK", async () => {
+    mockFetchJson({ detail: "not found" }, 404);
+    expect(
+      await fetchAssistantDetail(TOKEN, ASSISTANT_ID, PLATFORM_URL),
+    ).toBeNull();
+  });
+
+  test("fetchAssistantDetail returns null on network error", async () => {
+    mockFetchNetworkError();
+    expect(
+      await fetchAssistantDetail(TOKEN, ASSISTANT_ID, PLATFORM_URL),
+    ).toBeNull();
+  });
+
+  test("fetchUpgradeInProgress returns the boolean", async () => {
+    const fetchMock = mockFetchJson({ in_progress: true });
+    expect(
+      await fetchUpgradeInProgress(TOKEN, ASSISTANT_ID, PLATFORM_URL),
+    ).toBe(true);
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toBe(
+      `${PLATFORM_URL}/v1/assistants/${ASSISTANT_ID}/upgrade-status/`,
+    );
+
+    mockFetchJson({ in_progress: false });
+    expect(
+      await fetchUpgradeInProgress(TOKEN, ASSISTANT_ID, PLATFORM_URL),
+    ).toBe(false);
+  });
+
+  test("fetchUpgradeInProgress returns null on 404 (older platform)", async () => {
+    mockFetchJson({ detail: "not found" }, 404);
+    expect(
+      await fetchUpgradeInProgress(TOKEN, ASSISTANT_ID, PLATFORM_URL),
+    ).toBeNull();
+  });
+
+  test("fetchUpgradeInProgress returns null on network error", async () => {
+    mockFetchNetworkError();
+    expect(
+      await fetchUpgradeInProgress(TOKEN, ASSISTANT_ID, PLATFORM_URL),
+    ).toBeNull();
+  });
+
+  test("fetchUpgradeInProgress returns null on a malformed body", async () => {
+    mockFetchJson({ something_else: 1 });
+    expect(
+      await fetchUpgradeInProgress(TOKEN, ASSISTANT_ID, PLATFORM_URL),
+    ).toBeNull();
+  });
+});

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

@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import {
+  fetchReleases,
+  resolveImageRefsDetailed,
+} from "../lib/platform-releases.js";
+
+const originalFetch = globalThis.fetch;
+
+function mockFetchJson(body: unknown, status = 200) {
+  const fetchMock = mock(
+    async (_url: RequestInfo | URL, _init?: RequestInit) =>
+      new Response(JSON.stringify(body), { status }),
+  );
+  globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+  return fetchMock;
+}
+
+function mockFetchError() {
+  globalThis.fetch = mock(async () => {
+    throw new TypeError("fetch failed");
+  }) as unknown as typeof globalThis.fetch;
+}
+
+beforeEach(() => {
+  process.env.VELLUM_PLATFORM_URL = "https://platform.test";
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  delete process.env.VELLUM_PLATFORM_URL;
+});
+
+const RELEASE = {
+  version: "0.7.0",
+  assistant_image_ref: "gcr.io/vellum/assistant@sha256:aaa",
+  gateway_image_ref: "gcr.io/vellum/gateway@sha256:bbb",
+  credential_executor_image_ref: "gcr.io/vellum/ces@sha256:ccc",
+};
+
+describe("fetchReleases", () => {
+  test("defaults to stable=true and returns the list", async () => {
+    const fetchMock = mockFetchJson([RELEASE]);
+    const releases = await fetchReleases();
+    expect(releases).toEqual([RELEASE]);
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toContain("/v1/releases/?stable=true");
+    expect(url).toContain("limit=100");
+  });
+
+  test("passes the channel param when given", async () => {
+    const fetchMock = mockFetchJson([RELEASE]);
+    await fetchReleases({ channel: "preview" });
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toContain("/v1/releases/?channel=preview");
+    expect(url).toContain("limit=100");
+  });
+
+  test("uses the platformUrl override over the resolved default", async () => {
+    const fetchMock = mockFetchJson([RELEASE]);
+    await fetchReleases({ platformUrl: "https://other-platform.test" });
+    const url = String(fetchMock.mock.calls[0][0]);
+    expect(url).toContain("https://other-platform.test/v1/releases/");
+  });
+
+  test("returns null on non-OK response", async () => {
+    mockFetchJson({ detail: "nope" }, 500);
+    expect(await fetchReleases()).toBeNull();
+  });
+
+  test("returns null on network error", async () => {
+    mockFetchError();
+    expect(await fetchReleases()).toBeNull();
+  });
+});
+
+describe("resolveImageRefsDetailed", () => {
+  test("returns platform refs when the version is found", async () => {
+    mockFetchJson([RELEASE]);
+    const result = await resolveImageRefsDetailed("v0.7.0");
+    expect(result.status).toBe("platform");
+    if (result.status === "platform") {
+      expect(result.imageTags.assistant).toBe(RELEASE.assistant_image_ref);
+      expect(result.imageTags.gateway).toBe(RELEASE.gateway_image_ref);
+    }
+  });
+
+  test("falls back to DockerHub for a null credential-executor ref", async () => {
+    mockFetchJson([{ ...RELEASE, credential_executor_image_ref: null }]);
+    const result = await resolveImageRefsDetailed("0.7.0");
+    expect(result.status).toBe("platform");
+    if (result.status === "platform") {
+      expect(result.imageTags["credential-executor"]).toContain(":0.7.0");
+    }
+  });
+
+  test("returns version-not-found when the platform list lacks the version", async () => {
+    mockFetchJson([RELEASE]);
+    const result = await resolveImageRefsDetailed("v9.9.9");
+    expect(result.status).toBe("version-not-found");
+  });
+
+  test("returns dockerhub-fallback when the platform is unreachable", async () => {
+    mockFetchError();
+    const result = await resolveImageRefsDetailed("v0.7.0");
+    expect(result.status).toBe("dockerhub-fallback");
+    if (result.status === "dockerhub-fallback") {
+      expect(result.imageTags.assistant).toContain(":v0.7.0");
+    }
+  });
+
+  test("returns dockerhub-fallback when required refs are missing", async () => {
+    mockFetchJson([{ ...RELEASE, assistant_image_ref: null }]);
+    const result = await resolveImageRefsDetailed("0.7.0");
+    expect(result.status).toBe("dockerhub-fallback");
+  });
+});

package/src/__tests__/upgrade-preflight.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  evaluateUpgradePoll,
+  resolveUpgradeTarget,
+} from "../lib/upgrade-preflight.js";
+
+const RELEASES = [
+  { version: "0.8.0", is_stable: false },
+  { version: "0.7.0" },
+  { version: "0.6.0" },
+];
+
+describe("resolveUpgradeTarget", () => {
+  test("explicit version present in releases resolves ok", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: "v0.7.0",
+      releases: RELEASES,
+      currentVersion: "0.6.0",
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.target).toBe("v0.7.0");
+    expect(result.isNoOp).toBe(false);
+    expect(result.isDowngrade).toBe(false);
+  });
+
+  test("explicit version absent from releases is version-not-found", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: "v9.9.9",
+      releases: RELEASES,
+      currentVersion: "0.6.0",
+    });
+    expect(result.kind).toBe("version-not-found");
+    expect(result.target).toBeNull();
+  });
+
+  test("explicit version is trusted when releases are unavailable", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: "v0.7.0",
+      releases: null,
+      currentVersion: "0.6.0",
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.target).toBe("v0.7.0");
+  });
+
+  test("default target skips non-stable heads", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: null,
+      releases: RELEASES,
+      currentVersion: "0.6.0",
+    });
+    expect(result.kind).toBe("ok");
+    expect(result.target).toBe("0.7.0");
+  });
+
+  test("default target falls back to first release when none are stable", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: null,
+      releases: [{ version: "0.8.0", is_stable: false }],
+      currentVersion: "0.6.0",
+    });
+    expect(result.target).toBe("0.8.0");
+  });
+
+  test("no explicit version with unreachable releases is no-releases", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: null,
+      releases: null,
+      currentVersion: "0.6.0",
+    });
+    expect(result.kind).toBe("no-releases");
+    expect(result.target).toBeNull();
+  });
+
+  test("no explicit version with empty releases is no-releases", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: null,
+      releases: [],
+      currentVersion: "0.6.0",
+    });
+    expect(result.kind).toBe("no-releases");
+  });
+
+  test("detects no-op across v prefix", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: "v0.7.0",
+      releases: RELEASES,
+      currentVersion: "0.7.0",
+    });
+    expect(result.isNoOp).toBe(true);
+    expect(result.isDowngrade).toBe(false);
+  });
+
+  test("detects downgrade", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: "v0.6.0",
+      releases: RELEASES,
+      currentVersion: "0.7.0",
+    });
+    expect(result.isDowngrade).toBe(true);
+    expect(result.isNoOp).toBe(false);
+  });
+
+  test("unknown current version yields no flags", () => {
+    const result = resolveUpgradeTarget({
+      explicitVersion: "v0.7.0",
+      releases: RELEASES,
+      currentVersion: undefined,
+    });
+    expect(result.comparison).toBeNull();
+    expect(result.isNoOp).toBe(false);
+    expect(result.isDowngrade).toBe(false);
+  });
+});
+
+describe("evaluateUpgradePoll", () => {
+  test("known target completes on version match", () => {
+    expect(
+      evaluateUpgradePoll({
+        targetVersion: "v0.7.0",
+        initialVersion: "0.6.0",
+        observedVersion: "0.7.0",
+        inProgress: null,
+        sawInProgress: false,
+      }),
+    ).toBe("complete");
+  });
+
+  test("known target pends until the version matches", () => {
+    expect(
+      evaluateUpgradePoll({
+        targetVersion: "0.7.0",
+        initialVersion: "0.6.0",
+        observedVersion: "0.6.0",
+        inProgress: false,
+        sawInProgress: false,
+      }),
+    ).toBe("pending");
+  });
+
+  test("unknown target completes when the in-progress lock releases", () => {
+    expect(
+      evaluateUpgradePoll({
+        targetVersion: null,
+        initialVersion: "0.6.0",
+        observedVersion: "0.6.0",
+        inProgress: false,
+        sawInProgress: true,
+      }),
+    ).toBe("complete");
+  });
+
+  test("unknown target pends while the lock was never observed", () => {
+    expect(
+      evaluateUpgradePoll({
+        targetVersion: null,
+        initialVersion: "0.6.0",
+        observedVersion: "0.6.0",
+        inProgress: false,
+        sawInProgress: false,
+      }),
+    ).toBe("pending");
+  });
+
+  test("unknown target without upgrade-status completes on version change", () => {
+    expect(
+      evaluateUpgradePoll({
+        targetVersion: null,
+        initialVersion: "0.6.0",
+        observedVersion: "0.7.0",
+        inProgress: null,
+        sawInProgress: false,
+      }),
+    ).toBe("complete");
+  });
+
+  test("unknown target completes on version change even when the lock was never observed", () => {
+    // Upgrade finished before the first poll: in_progress already false,
+    // sawInProgress never set — the version change alone must complete.
+    expect(
+      evaluateUpgradePoll({
+        targetVersion: null,
+        initialVersion: "0.6.0",
+        observedVersion: "0.7.0",
+        inProgress: false,
+        sawInProgress: false,
+      }),
+    ).toBe("complete");
+  });
+
+  test("unknown target without upgrade-status pends while the version is unchanged", () => {
+    expect(
+      evaluateUpgradePoll({
+        targetVersion: null,
+        initialVersion: "0.6.0",
+        observedVersion: "v0.6.0",
+        inProgress: null,
+        sawInProgress: false,
+      }),
+    ).toBe("pending");
+  });
+});

package/src/__tests__/version-compat.test.ts

@@ -4,6 +4,8 @@ import {
   parseVersion,
   compareVersions,
   isVersionCompatible,
+  stripVersionPrefix,
+  versionsEqual,
 } from "../lib/version-compat.js";
 
 describe("parseVersion", () => {
@@ -204,3 +206,32 @@ describe("isVersionCompatible", () => {
     expect(isVersionCompatible("bad", "1.0.0")).toBe(false);
   });
 });
+
+describe("stripVersionPrefix", () => {
+  test("strips v prefix", () => {
+    expect(stripVersionPrefix("v0.7.0")).toBe("0.7.0");
+  });
+
+  test("strips V prefix", () => {
+    expect(stripVersionPrefix("V0.7.0")).toBe("0.7.0");
+  });
+
+  test("leaves unprefixed versions unchanged", () => {
+    expect(stripVersionPrefix("0.7.0")).toBe("0.7.0");
+  });
+});
+
+describe("versionsEqual", () => {
+  test("equal across v prefix", () => {
+    expect(versionsEqual("v0.7.0", "0.7.0")).toBe(true);
+  });
+
+  test("different versions are not equal", () => {
+    expect(versionsEqual("0.7.0", "0.7.1")).toBe(false);
+  });
+
+  test("unparseable falls back to prefix-stripped string equality", () => {
+    expect(versionsEqual("vweird-build", "weird-build")).toBe(true);
+    expect(versionsEqual("weird-build", "other-build")).toBe(false);
+  });
+});

package/src/commands/hatch.ts

@@ -5,6 +5,7 @@ import cliPkg from "../../package.json";
 
 import { buildOpenclawStartupScript } from "../adapters/openclaw";
 import {
+  normalizeVersion,
   saveAssistantEntry,
   setActiveAssistant,
 } from "../lib/assistant-config";
@@ -638,6 +639,9 @@ async function hatchVellumPlatform(): Promise<void> {
     cloud: "vellum",
     species: "vellum",
     hatchedAt: new Date().toISOString(),
+    ...(result.current_release_version != null && {
+      version: normalizeVersion(result.current_release_version),
+    }),
   });
   setActiveAssistant(result.id);
 

package/src/commands/rollback.ts

@@ -2,6 +2,7 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  normalizeVersion,
   resolveCloud,
   saveAssistantEntry,
   type AssistantEntry,
@@ -402,6 +403,11 @@ export async function rollback(): Promise<void> {
           networkName: res.network,
         },
         previousContainerInfo: entry.containerInfo,
+        // Cleared (not preserved) when the rolled-back-to version is unknown
+        version:
+          previousVersion !== "unknown"
+            ? normalizeVersion(previousVersion)
+            : undefined,
         // Clear the backup path — it belonged to the upgrade we just rolled back
         preUpgradeBackupPath: undefined,
         previousDbMigrationVersion: undefined,