@vellumai/cli 0.6.2 → 0.6.4

package/AGENTS.md

@@ -51,10 +51,20 @@ For example, the signing key used for JWT auth between the daemon and gateway is
 
 The CLI creates and manages Docker volumes for containerized instances. See the root `AGENTS.md` § Docker Volume Architecture for the full volume layout.
 
-**Volume creation** (`hatch`): Creates four volumes per instance — workspace, gateway-security, ces-security, and socket. The legacy data volume is no longer created.
+**Volume creation** (`hatch`): Creates five volumes per instance — workspace, gateway-security, ces-security, socket, and dockerd-data (the last backs the inner Docker engine used for Meet; see below). The legacy data volume is no longer created.
 
 **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.
 
 **Volume cleanup** (`retire`): All volumes (including the legacy data volume if it exists) are removed when an instance is retired.
 
-**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.
+**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. The `dockerd-data` volume is mounted only on the assistant container.
+
+**Meet Docker-in-Docker support** (assistant container only): The assistant container runs an inner `dockerd` that hosts the Meet-bot containers as nested children. The CLI supports this by:
+
+- Creating a dedicated `<name>-dockerd-data` volume mounted at `/var/lib/docker` so pulled images and container state persist across assistant restarts.
+- Running the assistant container with `--privileged` (or `CAP_SYS_ADMIN` + `CAP_NET_ADMIN`) so the inner dockerd can configure cgroups, overlay mounts, and container networking.
+- No longer bind-mounting the host's `/var/run/docker.sock`; Meet-bot spawning happens entirely inside the assistant container.
+
+Both are wired in `serviceDockerRunArgs()` in `lib/docker.ts`.
+
+The privileged assistant container is acceptable for single-user local deployments. Managed/multi-tenant mode needs a different spawn model (e.g. a Kubernetes job runner) and is out of scope for this CLI.

package/README.md

@@ -105,12 +105,12 @@ Delete a provisioned assistant instance. The cloud provider and connection detai
 vellum retire <name>
 ```
 
-The CLI looks up the instance by name in `~/.vellum.lock.json` and determines how to retire it based on the saved `cloud` field:
+The CLI looks up the instance by name in the production lockfile (`~/.vellum.lock.json`) or the env-scoped lockfile under `$XDG_CONFIG_HOME/vellum-<env>/lockfile.json` for non-production environments, then determines how to retire it based on the saved `cloud` field:
 
 - **`gcp`** -- Deletes the GCP Compute Engine instance via `gcloud compute instances delete`.
 - **`aws`** -- Terminates the AWS EC2 instance by looking up the instance ID from its Name tag.
-- **`local`** -- Stops the local assistant (`vellum sleep`) and removes the `~/.vellum` directory.
-- **`custom`** -- SSHs to the remote host to stop the assistant/gateway and remove the `~/.vellum` directory.
+- **`local`** -- Stops the local assistant (`vellum sleep`) and removes the assistant's instance directory (`resources.instanceDir` in the lockfile; typically `~/.local/share/vellum/assistants/<name>/` for new hatches, or `~/.vellum/` for legacy entries).
+- **`custom`** -- SSHs to the remote host to stop the assistant/gateway and remove the remote `~/.vellum` directory.
 
 #### Examples
 

package/bunfig.toml

@@ -0,0 +1,6 @@
+[install]
+exact = true
+
+[test]
+root = "./src"
+preload = ["./src/__tests__/preload.ts"]

package/package.json

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

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

@@ -474,3 +474,127 @@ describe("legacy migration via loadAllAssistants", () => {
     );
   });
 });
+
+describe("env-scoped lockfile and migration", () => {
+  test("migrateLegacyEntry uses env-scoped multi-instance dir in non-prod", () => {
+    // GIVEN VELLUM_ENVIRONMENT=dev and an XDG_DATA_HOME override
+    const prevEnv = process.env.VELLUM_ENVIRONMENT;
+    const prevXdg = process.env.XDG_DATA_HOME;
+    const xdgDataHome = mkdtempSync(join(tmpdir(), "cli-xdg-data-"));
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    process.env.XDG_DATA_HOME = xdgDataHome;
+    try {
+      // AND a legacy local entry with no resources
+      const entry: Record<string, unknown> = {
+        assistantId: "dev-bot",
+        runtimeUrl: "http://localhost:7830",
+        cloud: "local",
+      };
+
+      // WHEN we migrate it
+      const changed = migrateLegacyEntry(entry);
+
+      // THEN resources.instanceDir points at the env-scoped multi-instance dir
+      expect(changed).toBe(true);
+      const resources = entry.resources as Record<string, unknown>;
+      expect(resources.instanceDir).toBe(
+        join(xdgDataHome, "vellum-dev", "assistants", "dev-bot"),
+      );
+    } finally {
+      if (prevEnv !== undefined) {
+        process.env.VELLUM_ENVIRONMENT = prevEnv;
+      } else {
+        delete process.env.VELLUM_ENVIRONMENT;
+      }
+      if (prevXdg !== undefined) {
+        process.env.XDG_DATA_HOME = prevXdg;
+      } else {
+        delete process.env.XDG_DATA_HOME;
+      }
+      rmSync(xdgDataHome, { recursive: true, force: true });
+    }
+  });
+
+  test("readLockfile/writeLockfile use $XDG_CONFIG_HOME/vellum-<env>/lockfile.json in non-prod", () => {
+    // The env package's xdgConfigHome() reads process.env.XDG_CONFIG_HOME
+    // fresh on every call, so redirecting via that env var works without
+    // mocking `os`. We temporarily unset VELLUM_LOCKFILE_DIR so the env
+    // package falls through to getConfigDir(env).
+    const prevEnv = process.env.VELLUM_ENVIRONMENT;
+    const prevXdgConfig = process.env.XDG_CONFIG_HOME;
+    const prevLockDir = process.env.VELLUM_LOCKFILE_DIR;
+    const xdgConfigHome = mkdtempSync(join(tmpdir(), "cli-xdg-config-"));
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    process.env.XDG_CONFIG_HOME = xdgConfigHome;
+    delete process.env.VELLUM_LOCKFILE_DIR;
+    try {
+      // WHEN we save an assistant entry (which triggers writeLockfile)
+      saveAssistantEntry({
+        assistantId: "dev-env-bot",
+        runtimeUrl: "http://localhost:7830",
+        cloud: "local",
+      });
+
+      // THEN the lockfile lives at the env-scoped XDG config path
+      const expectedPath = join(xdgConfigHome, "vellum-dev", "lockfile.json");
+      const raw = JSON.parse(readFileSync(expectedPath, "utf-8"));
+      expect(raw.assistants).toHaveLength(1);
+      expect(raw.assistants[0].assistantId).toBe("dev-env-bot");
+
+      // AND readLockfile reads it back via loadAllAssistants()
+      const all = loadAllAssistants();
+      expect(all).toHaveLength(1);
+      expect(all[0].assistantId).toBe("dev-env-bot");
+    } finally {
+      if (prevEnv !== undefined) {
+        process.env.VELLUM_ENVIRONMENT = prevEnv;
+      } else {
+        delete process.env.VELLUM_ENVIRONMENT;
+      }
+      if (prevXdgConfig !== undefined) {
+        process.env.XDG_CONFIG_HOME = prevXdgConfig;
+      } else {
+        delete process.env.XDG_CONFIG_HOME;
+      }
+      if (prevLockDir !== undefined) {
+        process.env.VELLUM_LOCKFILE_DIR = prevLockDir;
+      }
+      rmSync(xdgConfigHome, { recursive: true, force: true });
+    }
+  });
+
+  test("production lockfile path is unchanged — uses .vellum.lock.json", () => {
+    // With VELLUM_ENVIRONMENT unset, the env package resolves production,
+    // whose canonical lockfile filename is `.vellum.lock.json`. This test
+    // uses the existing VELLUM_LOCKFILE_DIR=testDir override to route the
+    // lockfile to a scratch directory but verifies the FILENAME matches
+    // the production convention (not the non-prod "lockfile.json").
+    const prevEnv = process.env.VELLUM_ENVIRONMENT;
+    delete process.env.VELLUM_ENVIRONMENT;
+    try {
+      // Clear any existing lockfile from earlier tests
+      try {
+        rmSync(join(testDir, ".vellum.lock.json"));
+      } catch {
+        // ignore
+      }
+
+      saveAssistantEntry({
+        assistantId: "prod-bot",
+        runtimeUrl: "http://localhost:7830",
+        cloud: "local",
+      });
+
+      // The file should land at testDir/.vellum.lock.json — the production
+      // filename — rather than testDir/lockfile.json.
+      const prodPath = join(testDir, ".vellum.lock.json");
+      const raw = JSON.parse(readFileSync(prodPath, "utf-8"));
+      expect(raw.assistants).toHaveLength(1);
+      expect(raw.assistants[0].assistantId).toBe("prod-bot");
+    } finally {
+      if (prevEnv !== undefined) {
+        process.env.VELLUM_ENVIRONMENT = prevEnv;
+      }
+    }
+  });
+});

package/src/__tests__/env-drift.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { SEEDS } from "../lib/environments/seeds.js";
+
+// Drift guard for the three TypeScript sites that each hardcode the set of
+// known environment names:
+//
+//   1. cli/src/lib/environments/seeds.ts          — SEEDS record (source of truth)
+//   2. assistant/src/util/platform.ts             — KNOWN_ENVIRONMENTS set
+//   3. clients/chrome-extension/native-host/
+//         src/lockfile.ts                         — NON_PRODUCTION_ENVIRONMENTS set
+//
+// Cross-package relative imports don't work here: assistant's tsconfig
+// restricts `include` to its own src tree, and the native host is a
+// standalone TS project with `rootDir: ./src`. So this test parses the
+// literal sets out of the two external files and asserts they agree with
+// CLI's SEEDS.
+//
+// FOLLOW-UP: split the env name list into a shared `packages/environments`
+// package (mirroring `packages/ces-contracts`, `credential-storage`) so
+// all three sites can `import { KNOWN_ENVIRONMENTS }` from one place and
+// this drift guard becomes a compile-time check. Planned alongside CLI-
+// driven context support — see the "Environments" design doc.
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..");
+const ASSISTANT_PLATFORM = join(
+  REPO_ROOT,
+  "assistant",
+  "src",
+  "util",
+  "platform.ts",
+);
+const NATIVE_HOST_LOCKFILE = join(
+  REPO_ROOT,
+  "clients",
+  "chrome-extension",
+  "native-host",
+  "src",
+  "lockfile.ts",
+);
+
+/**
+ * Extract the string literals from a Set constructor body in a TS source
+ * file. Looks for `<setName>: ReadonlySet<string> = new Set([ ... ])` and
+ * pulls out every `"..."` entry within the array. The match is anchored to
+ * the `setName` to avoid picking up unrelated sets that happen to live in
+ * the same file.
+ */
+function extractSetLiterals(source: string, setName: string): string[] {
+  const pattern = new RegExp(
+    `${setName}\\s*:\\s*ReadonlySet<string>\\s*=\\s*new Set\\(\\[([^\\]]*)\\]`,
+    "m",
+  );
+  const match = source.match(pattern);
+  if (!match) {
+    throw new Error(
+      `Could not find Set literal for ${setName}. Update the drift-guard regex in env-drift.test.ts.`,
+    );
+  }
+  const body = match[1];
+  const literals = body.match(/"([^"]+)"/g) ?? [];
+  return literals.map((lit) => lit.slice(1, -1));
+}
+
+describe("KNOWN_ENVIRONMENTS drift guard (TS-side)", () => {
+  const seedNames = new Set(Object.keys(SEEDS));
+
+  test("assistant/src/util/platform.ts KNOWN_ENVIRONMENTS matches CLI SEEDS", () => {
+    const source = readFileSync(ASSISTANT_PLATFORM, "utf8");
+    const assistantNames = new Set(
+      extractSetLiterals(source, "KNOWN_ENVIRONMENTS"),
+    );
+    expect([...assistantNames].sort()).toEqual([...seedNames].sort());
+  });
+
+  test("native-host/src/lockfile.ts NON_PRODUCTION_ENVIRONMENTS matches CLI SEEDS minus production", () => {
+    const source = readFileSync(NATIVE_HOST_LOCKFILE, "utf8");
+    const nativeNames = new Set(
+      extractSetLiterals(source, "NON_PRODUCTION_ENVIRONMENTS"),
+    );
+    const expected = new Set(seedNames);
+    expected.delete("production");
+    expect([...nativeNames].sort()).toEqual([...expected].sort());
+  });
+});

package/src/__tests__/guardian-token.test.ts

@@ -0,0 +1,172 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  getOrCreatePersistedDeviceId,
+  loadGuardianToken,
+  saveGuardianToken,
+  type GuardianTokenData,
+} from "../lib/guardian-token.js";
+
+function makeTokenData(suffix: string): GuardianTokenData {
+  const now = new Date().toISOString();
+  return {
+    guardianPrincipalId: `principal-${suffix}`,
+    accessToken: `access-${suffix}`,
+    accessTokenExpiresAt: now,
+    refreshToken: `refresh-${suffix}`,
+    refreshTokenExpiresAt: now,
+    refreshAfter: now,
+    isNew: true,
+    deviceId: `device-${suffix}`,
+    leasedAt: now,
+  };
+}
+
+describe("guardian-token paths are env-scoped", () => {
+  let tempHome: string;
+  let savedXdg: string | undefined;
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    savedXdg = process.env.XDG_CONFIG_HOME;
+    savedEnv = process.env.VELLUM_ENVIRONMENT;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-guardian-token-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    delete process.env.VELLUM_ENVIRONMENT;
+  });
+
+  afterEach(() => {
+    if (savedXdg === undefined) {
+      delete process.env.XDG_CONFIG_HOME;
+    } else {
+      process.env.XDG_CONFIG_HOME = savedXdg;
+    }
+    if (savedEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = savedEnv;
+    }
+    rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  test("prod: guardian token lands at $XDG_CONFIG_HOME/vellum/assistants/<id>/guardian-token.json", () => {
+    const data = makeTokenData("prod");
+    saveGuardianToken("alpha", data);
+
+    const prodPath = join(
+      tempHome,
+      "vellum",
+      "assistants",
+      "alpha",
+      "guardian-token.json",
+    );
+    expect(existsSync(prodPath)).toBe(true);
+    const parsed = JSON.parse(readFileSync(prodPath, "utf-8"));
+    expect(parsed.guardianPrincipalId).toBe("principal-prod");
+
+    const loaded = loadGuardianToken("alpha");
+    expect(loaded).not.toBeNull();
+    expect(loaded!.guardianPrincipalId).toBe("principal-prod");
+  });
+
+  test("dev: guardian token lands at $XDG_CONFIG_HOME/vellum-dev/assistants/<id>/guardian-token.json", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    const data = makeTokenData("dev");
+    saveGuardianToken("alpha", data);
+
+    const devPath = join(
+      tempHome,
+      "vellum-dev",
+      "assistants",
+      "alpha",
+      "guardian-token.json",
+    );
+    expect(existsSync(devPath)).toBe(true);
+
+    // Prod directory must NOT have this token
+    const prodPath = join(
+      tempHome,
+      "vellum",
+      "assistants",
+      "alpha",
+      "guardian-token.json",
+    );
+    expect(existsSync(prodPath)).toBe(false);
+
+    const loaded = loadGuardianToken("alpha");
+    expect(loaded).not.toBeNull();
+    expect(loaded!.guardianPrincipalId).toBe("principal-dev");
+  });
+
+  test("same assistant id in prod and dev is isolated on disk", () => {
+    // Write prod token for assistant 'alpha'
+    delete process.env.VELLUM_ENVIRONMENT;
+    saveGuardianToken("alpha", makeTokenData("prod"));
+
+    // Write dev token for assistant 'alpha'
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    saveGuardianToken("alpha", makeTokenData("dev"));
+
+    // Dev load returns dev
+    expect(loadGuardianToken("alpha")!.guardianPrincipalId).toBe(
+      "principal-dev",
+    );
+
+    // Back to prod — prod token is unchanged
+    delete process.env.VELLUM_ENVIRONMENT;
+    expect(loadGuardianToken("alpha")!.guardianPrincipalId).toBe(
+      "principal-prod",
+    );
+
+    // Both files exist at distinct paths
+    const prodPath = join(
+      tempHome,
+      "vellum",
+      "assistants",
+      "alpha",
+      "guardian-token.json",
+    );
+    const devPath = join(
+      tempHome,
+      "vellum-dev",
+      "assistants",
+      "alpha",
+      "guardian-token.json",
+    );
+    expect(existsSync(prodPath)).toBe(true);
+    expect(existsSync(devPath)).toBe(true);
+    expect(prodPath).not.toBe(devPath);
+  });
+
+  test("prod: persisted device id lands at $XDG_CONFIG_HOME/vellum/device-id", () => {
+    const id = getOrCreatePersistedDeviceId();
+    expect(id.length).toBeGreaterThan(0);
+
+    const prodPath = join(tempHome, "vellum", "device-id");
+    expect(existsSync(prodPath)).toBe(true);
+    expect(readFileSync(prodPath, "utf-8").trim()).toBe(id);
+  });
+
+  test("dev: persisted device id lands at $XDG_CONFIG_HOME/vellum-dev/device-id", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    const id = getOrCreatePersistedDeviceId();
+    expect(id.length).toBeGreaterThan(0);
+
+    const devPath = join(tempHome, "vellum-dev", "device-id");
+    expect(existsSync(devPath)).toBe(true);
+    expect(readFileSync(devPath, "utf-8").trim()).toBe(id);
+
+    const prodPath = join(tempHome, "vellum", "device-id");
+    expect(existsSync(prodPath)).toBe(false);
+  });
+
+  test("device id is stable across repeated calls in the same env", () => {
+    delete process.env.VELLUM_ENVIRONMENT;
+    const first = getOrCreatePersistedDeviceId();
+    const second = getOrCreatePersistedDeviceId();
+    expect(first).toBe(second);
+  });
+});

package/src/__tests__/multi-local.test.ts

@@ -94,22 +94,69 @@ describe("multi-local", () => {
   });
 
   describe("allocateLocalResources() produces non-conflicting ports", () => {
-    test("first instance gets home directory and default ports", async () => {
-      // GIVEN no local assistants exist in the lockfile
-
-      // WHEN we allocate resources for the first instance
-      const res = await allocateLocalResources("instance-a");
-
-      // THEN it gets the home directory as its instance root
-      expect(res.instanceDir).toBe(testDir);
+    test("first instance (prod) gets XDG multi-instance dir with default ports", async () => {
+      // GIVEN XDG_DATA_HOME points at a scratch directory and no local
+      // assistants exist in the lockfile
+      const prevXdg = process.env.XDG_DATA_HOME;
+      const xdgDataHome = mkdtempSync(join(tmpdir(), "cli-multi-xdg-data-"));
+      process.env.XDG_DATA_HOME = xdgDataHome;
+      try {
+        // WHEN we allocate resources for the first instance
+        const res = await allocateLocalResources("instance-a");
+
+        // THEN it lands under the XDG multi-instance dir (no "first = home"
+        // special case anymore)
+        expect(res.instanceDir).toBe(
+          join(xdgDataHome, "vellum", "assistants", "instance-a"),
+        );
+
+        // AND it gets the default ports since no other instances exist
+        expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
+        expect(res.gatewayPort).toBe(DEFAULT_GATEWAY_PORT);
+        expect(res.qdrantPort).toBe(DEFAULT_QDRANT_PORT);
+
+        // AND the PID file is under the instance's .vellum/
+        expect(res.pidFile).toBe(
+          join(res.instanceDir, ".vellum", "vellum.pid"),
+        );
+      } finally {
+        if (prevXdg !== undefined) {
+          process.env.XDG_DATA_HOME = prevXdg;
+        } else {
+          delete process.env.XDG_DATA_HOME;
+        }
+        rmSync(xdgDataHome, { recursive: true, force: true });
+      }
+    });
 
-      // AND it gets the default ports since no other instances exist
-      expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
-      expect(res.gatewayPort).toBe(DEFAULT_GATEWAY_PORT);
-      expect(res.qdrantPort).toBe(DEFAULT_QDRANT_PORT);
+    test("first instance (dev) uses env-scoped multi-instance dir", async () => {
+      // GIVEN VELLUM_ENVIRONMENT=dev and XDG_DATA_HOME set to scratch
+      const prevEnv = process.env.VELLUM_ENVIRONMENT;
+      const prevXdg = process.env.XDG_DATA_HOME;
+      const xdgDataHome = mkdtempSync(join(tmpdir(), "cli-multi-xdg-dev-"));
+      process.env.VELLUM_ENVIRONMENT = "dev";
+      process.env.XDG_DATA_HOME = xdgDataHome;
+      try {
+        // WHEN we allocate resources for the first instance
+        const res = await allocateLocalResources("instance-a");
 
-      // AND the PID file is under ~/.vellum/
-      expect(res.pidFile).toBe(join(testDir, ".vellum", "vellum.pid"));
+        // THEN it lands under the env-scoped multi-instance dir
+        expect(res.instanceDir).toBe(
+          join(xdgDataHome, "vellum-dev", "assistants", "instance-a"),
+        );
+      } finally {
+        if (prevEnv !== undefined) {
+          process.env.VELLUM_ENVIRONMENT = prevEnv;
+        } else {
+          delete process.env.VELLUM_ENVIRONMENT;
+        }
+        if (prevXdg !== undefined) {
+          process.env.XDG_DATA_HOME = prevXdg;
+        } else {
+          delete process.env.XDG_DATA_HOME;
+        }
+        rmSync(xdgDataHome, { recursive: true, force: true });
+      }
     });
 
     test("second instance gets distinct ports and dir when first instance is saved", async () => {