@vellumai/cli 0.8.3 → 0.8.5

package/AGENTS.md

@@ -16,7 +16,17 @@ Examples: `hatch`, `wake`, `sleep`, `retire`, `ps`, `ssh` belong here. `config`,
 
 ## Assistant targeting convention
 
-Commands that act on a specific assistant should accept an assistant name or ID as an argument. When none is specified, default to the most recently created local assistant. Use `loadAllAssistants()` and `findAssistantByName()` from `lib/assistant-config` for resolution.
+New or modified commands that act on a specific assistant should accept an assistant display name or ID as an argument. Exact assistant ID matches must win over display-name matches. Unique display-name matches may resolve to the matching assistant ID, but ambiguous display names must fail with an error that lists the matching IDs.
+
+Use the shared helpers from `lib/assistant-config` instead of hand-rolled lookup:
+
+- `lookupAssistantByIdentifier()` for commands that require an explicit target and need custom error handling.
+- `resolveTargetAssistant()` for commands that may fall back to the active assistant or sole lockfile entry.
+- `formatAssistantReference()` for user-facing output that should include both display name and ID when they differ.
+
+Use `parseAssistantTargetArg()` from `lib/assistant-target-args` when parsing command arguments that may contain an unquoted multi-word display name. Do not store raw display names in `activeAssistant`; persist the resolved `assistantId`.
+
+New or modified destructive lifecycle commands must be explicit and safe. A command that deletes, retires, archives, or removes assistant state must print the resolved assistant identity before acting and require an interactive confirmation, with a documented `--yes` bypass only for automation or higher-level clients that already own confirmation. Do not expose destructive lifecycle actions as `vellum client` slash commands.
 
 ## Conventions
 
@@ -55,14 +65,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                                      | 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)                                           |
+
+The assistant container's root (`/`) holds per-container ephemeral and persistent state: package installs (`~/.bun`), `device.json`, embed-worker PID files.
 
-**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.
+**Lifecycle**:
 
-**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.
+- `hatch` creates the six volumes.
+- `retire` removes all of them.
 
-**Volume cleanup** (`retire`): All volumes (including the legacy data volume if it exists) are removed when an instance is retired.
+**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.
 
-**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.
+**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.
 
-**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.
+**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.5",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/api-key-check.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { checkProviderApiKey } from "../lib/api-key-check.js";
+
+const PROVIDER_KEYS = [
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "GEMINI_API_KEY",
+  "FIREWORKS_API_KEY",
+  "OPENROUTER_API_KEY",
+] as const;
+
+beforeEach(() => {
+  for (const key of PROVIDER_KEYS) {
+    delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  for (const key of PROVIDER_KEYS) {
+    delete process.env[key];
+  }
+});
+
+describe("checkProviderApiKey", () => {
+  test("returns hasKey:false when no provider keys are in process.env", () => {
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:false when ANTHROPIC_API_KEY is a placeholder", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-...";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:false when OPENAI_API_KEY is a placeholder", () => {
+    process.env.OPENAI_API_KEY = "sk-...";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:false when key is empty", () => {
+    process.env.ANTHROPIC_API_KEY = "";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(false);
+  });
+
+  test("returns hasKey:true when ANTHROPIC_API_KEY is a real key", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-api03-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when OPENAI_API_KEY is a real key", () => {
+    process.env.OPENAI_API_KEY = "sk-proj-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when GEMINI_API_KEY is a real key", () => {
+    process.env.GEMINI_API_KEY = "AIzaSyRealKey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when FIREWORKS_API_KEY is a real key", () => {
+    process.env.FIREWORKS_API_KEY = "fw-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+
+  test("returns hasKey:true when OPENROUTER_API_KEY is a real key", () => {
+    process.env.OPENROUTER_API_KEY = "sk-or-realkey123";
+    const result = checkProviderApiKey();
+    expect(result.hasKey).toBe(true);
+  });
+});

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