@vellumai/cli 0.8.3 → 0.8.4

package/AGENTS.md

@@ -55,14 +55,26 @@ For example, the signing key used for JWT auth between the daemon and gateway is
 
 ## Docker Volume Management
 
-The CLI creates and manages Docker volumes for containerized instances. See the root `AGENTS.md` § Docker Volume Architecture for the full volume layout.
+The CLI creates and manages six per-instance Docker volumes with strict per-service access boundaries (least-privilege at the container level).
 
-**Volume creation** (`hatch`): Creates six volumes per instance — workspace, gateway-security, ces-security, socket, assistant-ipc, and gateway-ipc. The legacy data volume is no longer created.
+| Volume                                      | Mount path           | Access                              | Contents                                                                         |
+| ------------------------------------------- | -------------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
+| **Workspace** (`<name>-workspace`)          | `/workspace`         | Assistant: rw, Gateway: rw, CES: ro | `config.json`, conversations, apps, skills, db, logs, `.backups/`, `.backup.key` |
+| **Gateway security** (`<name>-gateway-sec`) | `/gateway-security`  | Gateway only                        | `trust.json`, `actor-token-signing-key`, capability-token secrets                |
+| **CES security** (`<name>-ces-sec`)         | `/ces-security`      | CES only                            | `keys.enc`, `store.key`                                                          |
+| **Socket** (`<name>-socket`)                | `/run/ces-bootstrap` | Assistant + CES                     | CES bootstrap socket for initial handshake                                       |
+| **Gateway IPC** (`<name>-gateway-ipc`)      | `/run/gateway-ipc`   | Assistant + Gateway                 | `gateway.sock` (assistant → gateway)                                             |
+| **Assistant IPC** (`<name>-assistant-ipc`)  | `/run/assistant-ipc` | Assistant + Gateway                 | `assistant.sock` (gateway → assistant)                                           |
 
-**Volume migration** (`wake`/`hatch`): On startup, existing instances that still have a legacy data volume are migrated. `migrateGatewaySecurityFiles()` and `migrateCesSecurityFiles()` in `lib/docker.ts` copy security files from the data volume to their respective security volumes. Migrations are idempotent and non-fatal.
+The assistant container's root (`/`) holds per-container ephemeral and persistent state: package installs (`~/.bun`), `device.json`, embed-worker PID files.
 
-**Volume cleanup** (`retire`): All volumes (including the legacy data volume if it exists) are removed when an instance is retired.
+**Lifecycle**:
 
-**Volume mount rules**: Each service container receives only the volumes it needs. The assistant never mounts `gateway-security` or `ces-security`. The gateway never mounts `ces-security`. The CES mounts the workspace volume as read-only.
+- `hatch` creates the six volumes.
+- `retire` removes all of them.
 
-**Container security posture**: The assistant container runs as a non-root user (UID 1001) with no elevated capabilities. `--privileged`, `--cap-add`, and `--security-opt` overrides are NOT used. The host Docker socket is NOT bind-mounted. Do NOT re-add elevated capabilities without a concrete runtime requirement — the Docker Engine packages and inner `dockerd` supervisor were reverted (PR #26028) and the capabilities they required are no longer needed.
+**Mount rules**: each container receives only the volumes it needs. The assistant never mounts `gateway-security` or `ces-security`. The gateway never mounts `ces-security`. The CES mounts the workspace volume as read-only.
+
+**Container security posture**: the assistant container runs as a non-root user (UID 1001) with no elevated capabilities — `--privileged`, `--cap-add`, and `--security-opt` overrides are not used; the host Docker socket is not bind-mounted; default Docker seccomp and AppArmor profiles remain active. Do not add elevated capabilities without a concrete runtime requirement.
+
+**Backup paths in Docker mode**: backups land on the workspace volume (`VELLUM_BACKUP_DIR` defaults to `/workspace/.backups/`, key at `VELLUM_BACKUP_KEY_PATH` defaults to `/workspace/.backup.key`), so workspace-volume destruction loses both data and backups.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

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

@@ -10,6 +10,10 @@ process.env.VELLUM_LOCKFILE_DIR = testDir;
 import {
   loadLatestAssistant,
   findAssistantByName,
+  formatAssistantLookupError,
+  formatAssistantReference,
+  getAssistantDisplayName,
+  lookupAssistantByIdentifier,
   removeAssistantEntry,
   loadAllAssistants,
   saveAssistantEntry,
@@ -87,6 +91,110 @@ describe("assistant-config", () => {
     expect(result!.assistantId).toBe("beta");
   });
 
+  test("getAssistantDisplayName prefers platform and legacy display names", () => {
+    expect(
+      getAssistantDisplayName(
+        makeEntry("assistant-1", undefined, { name: "Alice" }),
+      ),
+    ).toBe("Alice");
+    expect(
+      getAssistantDisplayName(
+        makeEntry("assistant-2", undefined, { assistantName: "Legacy Alice" }),
+      ),
+    ).toBe("Legacy Alice");
+    expect(getAssistantDisplayName(makeEntry("assistant-3"))).toBe(
+      "assistant-3",
+    );
+  });
+
+  test("findAssistantByName only resolves assistant IDs", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Bob" }),
+      ],
+    });
+
+    expect(findAssistantByName("Alice")).toBeNull();
+    expect(findAssistantByName("assistant-1")?.assistantId).toBe("assistant-1");
+  });
+
+  test("lookupAssistantByIdentifier resolves a unique display name", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Bob" }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Alice");
+    expect(result.status).toBe("found");
+    expect(result.status === "found" ? result.entry.assistantId : null).toBe(
+      "assistant-1",
+    );
+  });
+
+  test("lookupAssistantByIdentifier resolves a unique legacy assistantName", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", {
+          assistantName: "Legacy Alice",
+        }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Legacy Alice");
+    expect(result.status).toBe("found");
+    expect(result.status === "found" ? result.entry.assistantId : null).toBe(
+      "assistant-1",
+    );
+  });
+
+  test("assistant ID lookup wins over a display name match", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("Alice", "http://localhost:7821", { name: "Primary" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Alice" }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Alice");
+    expect(result.status).toBe("found");
+    expect(result.status === "found" ? result.entry.assistantId : null).toBe(
+      "Alice",
+    );
+  });
+
+  test("ambiguous display name lookup is explicit", () => {
+    writeLockfile({
+      assistants: [
+        makeEntry("assistant-1", "http://localhost:7821", { name: "Alice" }),
+        makeEntry("assistant-2", "http://localhost:7822", { name: "Alice" }),
+      ],
+    });
+
+    const result = lookupAssistantByIdentifier("Alice");
+    expect(result.status).toBe("ambiguous");
+    expect(findAssistantByName("Alice")).toBeNull();
+    expect(formatAssistantLookupError("Alice", result)).toContain(
+      "assistant-1",
+    );
+    expect(formatAssistantLookupError("Alice", result)).toContain(
+      "assistant-2",
+    );
+  });
+
+  test("formatAssistantReference includes distinct display name and id", () => {
+    expect(
+      formatAssistantReference(
+        makeEntry("assistant-1", undefined, { name: "Alice" }),
+      ),
+    ).toBe("Alice (assistant-1)");
+    expect(formatAssistantReference(makeEntry("assistant-2"))).toBe(
+      "assistant-2",
+    );
+  });
+
   test("findAssistantByName returns null for non-existent name", () => {
     writeLockfile({ assistants: [makeEntry("alpha")] });
     expect(findAssistantByName("missing")).toBeNull();

package/src/__tests__/assistant-target-args.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+
+describe("parseAssistantTargetArg", () => {
+  test("joins unquoted display-name words into one assistant target", () => {
+    expect(parseAssistantTargetArg(["Example", "Assistant"])).toBe(
+      "Example Assistant",
+    );
+  });
+
+  test("skips boolean flags", () => {
+    expect(parseAssistantTargetArg(["Example", "Assistant", "--verbose"])).toBe(
+      "Example Assistant",
+    );
+  });
+
+  test("skips configured flags and their values", () => {
+    expect(
+      parseAssistantTargetArg(
+        ["--url", "http://localhost:7830", "Example", "Assistant"],
+        ["--url"],
+      ),
+    ).toBe("Example Assistant");
+  });
+
+  test("returns undefined when no target is present", () => {
+    expect(parseAssistantTargetArg(["--verbose"])).toBeUndefined();
+  });
+});

package/src/__tests__/host-image-loader.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  type FetchLike,
+  HOST_IMAGE_LOADER_URL,
+  HostImageLoaderError,
+  isLocalBuildRef,
+  loadImageViaHost,
+} from "../lib/host-image-loader.js";
+
+describe("HOST_IMAGE_LOADER_URL", () => {
+  test("resolves to the well-known image-loader port/path", () => {
+    expect(HOST_IMAGE_LOADER_URL).toBe("http://127.0.0.1:5500/v1/images/load");
+  });
+});
+
+describe("isLocalBuildRef", () => {
+  test("recognizes the `vellum-local/` prefix as a local build", () => {
+    expect(isLocalBuildRef("vellum-local/assistant-server:sha-abc123")).toBe(
+      true,
+    );
+    expect(isLocalBuildRef("vellum-local/gateway:sha-def")).toBe(true);
+  });
+
+  test("treats external registry refs as pullable", () => {
+    expect(isLocalBuildRef("docker.io/example/image:v0.8.2")).toBe(false);
+    expect(
+      isLocalBuildRef("us-east1-docker.pkg.dev/example/image@sha256:deadbeef"),
+    ).toBe(false);
+    expect(isLocalBuildRef("postgres:17")).toBe(false);
+  });
+});
+
+function silentLog(_msg: string): void {
+  // intentionally swallow logs in test
+}
+
+function makeFetch(
+  responses: Array<{ url: string; body: unknown; status: number }>,
+  recordedRequests: Array<{ url: string; body: unknown }>,
+): FetchLike {
+  return async (input, init) => {
+    const url = typeof input === "string" ? input : input.toString();
+    const body = init?.body ? JSON.parse(init.body) : null;
+    recordedRequests.push({ url, body });
+    const planned = responses.shift();
+    if (!planned) throw new Error(`unexpected request to ${url}`);
+    return new Response(JSON.stringify(planned.body), {
+      status: planned.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+}
+
+describe("loadImageViaHost", () => {
+  test("POSTs {ref} to the URL and resolves on 200", async () => {
+    const recorded: Array<{ url: string; body: unknown }> = [];
+    const fetchImpl = makeFetch(
+      [
+        {
+          url: "http://127.0.0.1:5500/v1/images/load",
+          body: {
+            loaded: true,
+            ref: "vellum-local/assistant:sha-abc",
+          },
+          status: 200,
+        },
+      ],
+      recorded,
+    );
+
+    await loadImageViaHost(
+      "http://127.0.0.1:5500/v1/images/load",
+      "vellum-local/assistant:sha-abc",
+      silentLog,
+      { fetchImpl },
+    );
+
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0].url).toBe("http://127.0.0.1:5500/v1/images/load");
+    expect(recorded[0].body).toEqual({
+      ref: "vellum-local/assistant:sha-abc",
+    });
+  });
+
+  test("throws HostImageLoaderError with status when server returns non-2xx", async () => {
+    const recorded: Array<{ url: string; body: unknown }> = [];
+    const fetchImpl = makeFetch(
+      [
+        {
+          url: "http://127.0.0.1:5500/v1/images/load",
+          body: { loaded: false, error: "docker save failed: image not found" },
+          status: 502,
+        },
+      ],
+      recorded,
+    );
+
+    await expect(
+      loadImageViaHost(
+        "http://127.0.0.1:5500/v1/images/load",
+        "vellum-local/nope:abc",
+        silentLog,
+        { fetchImpl },
+      ),
+    ).rejects.toBeInstanceOf(HostImageLoaderError);
+
+    // Re-run to inspect fields (one-shot fetchImpl, so build a new one)
+    const recorded2: Array<{ url: string; body: unknown }> = [];
+    const fetchImpl2 = makeFetch(
+      [
+        {
+          url: "http://127.0.0.1:5500/v1/images/load",
+          body: { loaded: false, error: "docker save failed: image not found" },
+          status: 502,
+        },
+      ],
+      recorded2,
+    );
+
+    let caught: HostImageLoaderError | null = null;
+    try {
+      await loadImageViaHost(
+        "http://127.0.0.1:5500/v1/images/load",
+        "vellum-local/nope:abc",
+        silentLog,
+        { fetchImpl: fetchImpl2 },
+      );
+    } catch (err) {
+      caught = err as HostImageLoaderError;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught?.status).toBe(502);
+    expect(caught?.ref).toBe("vellum-local/nope:abc");
+    expect(caught?.message).toContain("502");
+    expect(caught?.message).toContain("docker save failed");
+  });
+
+  test("provides helpful guidance when the loader is unreachable", async () => {
+    const fetchImpl: FetchLike = async () => {
+      const err = new TypeError("fetch failed") as TypeError & {
+        cause?: { code?: string };
+      };
+      err.cause = { code: "ECONNREFUSED" };
+      throw err;
+    };
+
+    let caught: HostImageLoaderError | null = null;
+    try {
+      await loadImageViaHost(
+        "http://127.0.0.1:5500/v1/images/load",
+        "vellum-local/anything:xyz",
+        silentLog,
+        { fetchImpl },
+      );
+    } catch (err) {
+      caught = err as HostImageLoaderError;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught?.message).toContain("loader running");
+    expect(caught?.message).toContain("VELLUM_ASSISTANT_IMAGE");
+  });
+
+  test("wraps generic fetch errors", async () => {
+    const fetchImpl: FetchLike = async () => {
+      throw new Error("ETIMEDOUT");
+    };
+
+    let caught: HostImageLoaderError | null = null;
+    try {
+      await loadImageViaHost(
+        "http://127.0.0.1:5500/v1/images/load",
+        "x",
+        silentLog,
+        { fetchImpl },
+      );
+    } catch (err) {
+      caught = err as HostImageLoaderError;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught?.message).toContain("ETIMEDOUT");
+  });
+
+  test("handles non-JSON error bodies", async () => {
+    const fetchImpl: FetchLike = async () =>
+      new Response("<html>500 internal</html>", {
+        status: 500,
+        headers: { "Content-Type": "text/html" },
+      });
+
+    let caught: HostImageLoaderError | null = null;
+    try {
+      await loadImageViaHost(
+        "http://127.0.0.1:5500/v1/images/load",
+        "x",
+        silentLog,
+        { fetchImpl },
+      );
+    } catch (err) {
+      caught = err as HostImageLoaderError;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught?.status).toBe(500);
+    expect(caught?.message).toContain("HTTP 500");
+  });
+});

package/src/__tests__/ps-platform-status.test.ts

@@ -1,4 +1,12 @@
-import { afterAll, afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -16,6 +24,7 @@ process.env.VELLUM_LOCKFILE_DIR = testDir;
 // ---------------------------------------------------------------------------
 
 import * as assistantConfig from "../lib/assistant-config.js";
+import * as healthCheck from "../lib/health-check.js";
 import * as orphanDetection from "../lib/orphan-detection.js";
 import * as platformClient from "../lib/platform-client.js";
 
@@ -57,6 +66,10 @@ const fetchPlatformAssistantsMock = spyOn(
   platformClient,
   "fetchPlatformAssistants",
 ).mockResolvedValue([]);
+const checkManagedHealthMock = spyOn(
+  healthCheck,
+  "checkManagedHealth",
+).mockResolvedValue({ status: "healthy", detail: null });
 
 // ---------------------------------------------------------------------------
 // stdout / stderr capture
@@ -66,23 +79,32 @@ let stdout: string[];
 let stderr: string[];
 let originalLog: typeof console.log;
 let originalError: typeof console.error;
+let originalStdoutWrite: typeof process.stdout.write;
 
 beforeEach(() => {
   stdout = [];
   stderr = [];
   originalLog = console.log;
   originalError = console.error;
+  originalStdoutWrite = process.stdout.write;
   console.log = ((...args: unknown[]) => {
     stdout.push(args.map((a) => String(a)).join(" "));
   }) as typeof console.log;
   console.error = ((...args: unknown[]) => {
     stderr.push(args.map((a) => String(a)).join(" "));
   }) as typeof console.error;
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    stdout.push(String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
 });
 
 afterEach(() => {
   console.log = originalLog;
   console.error = originalError;
+  process.stdout.write = originalStdoutWrite;
+  loadAllAssistantsMock.mockReturnValue([]);
+  getActiveAssistantMock.mockReturnValue(null);
   readPlatformTokenMock.mockReturnValue(null);
   fetchCurrentUserMock.mockReset();
   fetchCurrentUserMock.mockResolvedValue({
@@ -92,6 +114,8 @@ afterEach(() => {
   });
   fetchPlatformAssistantsMock.mockReset();
   fetchPlatformAssistantsMock.mockResolvedValue([]);
+  checkManagedHealthMock.mockReset();
+  checkManagedHealthMock.mockResolvedValue({ status: "healthy", detail: null });
 });
 
 afterAll(() => {
@@ -102,6 +126,7 @@ afterAll(() => {
   readPlatformTokenMock.mockRestore();
   fetchCurrentUserMock.mockRestore();
   fetchPlatformAssistantsMock.mockRestore();
+  checkManagedHealthMock.mockRestore();
   rmSync(testDir, { recursive: true, force: true });
 });
 
@@ -125,12 +150,12 @@ describe("vellum ps — platform status line", () => {
     expect(stdout.filter((l) => l.startsWith("Platform:"))).toEqual([
       "Platform: not logged in",
     ]);
-    expect(
-      stderr.some((l) => l.includes("Failed to fetch organization")),
-    ).toBe(false);
-    expect(
-      stdout.some((l) => l.includes("Failed to fetch organization")),
-    ).toBe(false);
+    expect(stderr.some((l) => l.includes("Failed to fetch organization"))).toBe(
+      false,
+    );
+    expect(stdout.some((l) => l.includes("Failed to fetch organization"))).toBe(
+      false,
+    );
 
     // Structural guarantee: we never even tried to talk to the platform.
     expect(fetchCurrentUserMock).not.toHaveBeenCalled();
@@ -152,31 +177,84 @@ describe("vellum ps — platform status line", () => {
     expect(stdout.filter((l) => l.startsWith("Platform:"))).toEqual([
       "Platform: not logged in",
     ]);
-    expect(
-      stderr.some((l) => l.includes("Failed to fetch organization")),
-    ).toBe(false);
-    expect(
-      stdout.some((l) => l.includes("Failed to fetch organization")),
-    ).toBe(false);
-    expect(
-      stderr.some((l) => l.includes("Unable to connect")),
-    ).toBe(false);
+    expect(stderr.some((l) => l.includes("Failed to fetch organization"))).toBe(
+      false,
+    );
+    expect(stdout.some((l) => l.includes("Failed to fetch organization"))).toBe(
+      false,
+    );
+    expect(stderr.some((l) => l.includes("Unable to connect"))).toBe(false);
   });
 
   test("local token present and platform reachable: prints 'Platform: logged in as <email>'", async () => {
     readPlatformTokenMock.mockReturnValue("session_abc123");
     fetchCurrentUserMock.mockResolvedValue({
       id: "u1",
-      email: "vargas@vellum.ai",
-      display: "Vargas",
+      email: "user@example.com",
+      display: "Example User",
     });
     fetchPlatformAssistantsMock.mockResolvedValue([]);
 
     await listAllAssistants(false);
 
-    expect(stdout).toContain("Platform: logged in as vargas@vellum.ai");
-    expect(
-      stderr.some((l) => l.includes("Failed to fetch organization")),
-    ).toBe(false);
+    expect(stdout).toContain("Platform: logged in as user@example.com");
+    expect(stderr.some((l) => l.includes("Failed to fetch organization"))).toBe(
+      false,
+    );
+  });
+
+  test("assistant rows use display name as primary label and keep id visible", async () => {
+    loadAllAssistantsMock.mockReturnValue([
+      {
+        assistantId: "assistant-123",
+        name: "Alice",
+        runtimeUrl: "https://platform.example",
+        cloud: "vellum",
+        species: "vellum",
+      },
+    ]);
+    getActiveAssistantMock.mockReturnValue("assistant-123");
+
+    await listAllAssistants(false);
+
+    const output = stdout.join("\n");
+    expect(output).toContain("* Alice");
+    expect(output).toContain("id: assistant-123");
+    expect(output).toContain("https://platform.example");
+    expect(output).not.toContain("* assistant-123");
+  });
+
+  test("assistant list renders one stable final row per assistant", async () => {
+    loadAllAssistantsMock.mockReturnValue([
+      {
+        assistantId: "assistant-123",
+        name: "Alice",
+        runtimeUrl: "https://platform.example/a",
+        cloud: "vellum",
+        species: "vellum",
+      },
+      {
+        assistantId: "assistant-456",
+        name: "Bob",
+        runtimeUrl: "https://platform.example/b",
+        cloud: "vellum",
+        species: "vellum",
+      },
+    ]);
+    getActiveAssistantMock.mockReturnValue("assistant-123");
+    checkManagedHealthMock.mockImplementation(async (_runtimeUrl, id) => ({
+      status: id === "assistant-123" ? "healthy" : "sleeping",
+      detail: null,
+    }));
+
+    await listAllAssistants(false);
+
+    const output = stdout.join("\n");
+    expect(output).not.toContain("\x1b[");
+    expect(output).not.toContain("checking...");
+    expect(output.match(/Alice/g)).toHaveLength(1);
+    expect(output.match(/Bob/g)).toHaveLength(1);
+    expect(output).toContain("healthy");
+    expect(output).toContain("sleeping");
   });
 });