@vellumai/cli 0.4.37 → 0.4.40

package/package.json

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

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

@@ -0,0 +1,275 @@
+import { describe, test, expect, beforeEach, afterAll, mock } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Create a temp directory that acts as a fake home, so allocateLocalResources()
+// and defaultLocalResources() never touch the real ~/.vellum directory.
+const testDir = mkdtempSync(join(tmpdir(), "cli-multi-local-test-"));
+process.env.BASE_DATA_DIR = testDir;
+
+// Mock homedir() to return testDir — this isolates allocateLocalResources()
+// which uses homedir() directly for instance directory creation.
+const realOs = await import("node:os");
+mock.module("node:os", () => ({
+  ...realOs,
+  homedir: () => testDir,
+}));
+// Also mock the bare "os" specifier since assistant-config.ts uses `from "os"`
+mock.module("os", () => ({
+  ...realOs,
+  homedir: () => testDir,
+}));
+
+// Mock probePort so we control which ports appear in-use without touching the network
+const probePortMock = mock<(port: number, host?: string) => Promise<boolean>>(
+  () => Promise.resolve(false),
+);
+mock.module("../lib/port-probe.js", () => ({
+  probePort: probePortMock,
+}));
+
+import {
+  allocateLocalResources,
+  defaultLocalResources,
+  resolveTargetAssistant,
+  setActiveAssistant,
+  getActiveAssistant,
+  removeAssistantEntry,
+  saveAssistantEntry,
+  type AssistantEntry,
+} from "../lib/assistant-config.js";
+import { DEFAULT_DAEMON_PORT } from "../lib/constants.js";
+
+afterAll(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  delete process.env.BASE_DATA_DIR;
+});
+
+function writeLockfile(data: unknown): void {
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify(data, null, 2),
+  );
+}
+
+function readLockfileRaw(): Record<string, unknown> {
+  return JSON.parse(
+    readFileSync(join(testDir, ".vellum.lock.json"), "utf-8"),
+  ) as Record<string, unknown>;
+}
+
+const makeEntry = (
+  id: string,
+  cloud = "local",
+  extra?: Partial<AssistantEntry>,
+): AssistantEntry => ({
+  assistantId: id,
+  runtimeUrl: `http://localhost:${DEFAULT_DAEMON_PORT}`,
+  cloud,
+  ...extra,
+});
+
+function resetLockfile(): void {
+  try {
+    rmSync(join(testDir, ".vellum.lock.json"));
+  } catch {
+    // file may not exist
+  }
+  try {
+    rmSync(join(testDir, ".vellum.lockfile.json"));
+  } catch {
+    // file may not exist
+  }
+}
+
+describe("multi-local", () => {
+  beforeEach(() => {
+    resetLockfile();
+    probePortMock.mockReset();
+    probePortMock.mockImplementation(() => Promise.resolve(false));
+  });
+
+  describe("allocateLocalResources() produces non-conflicting ports", () => {
+    test("two instances get distinct ports and dirs when first instance ports are occupied", async () => {
+      // After the first allocation grabs its ports, simulate those ports
+      // being in-use so the second allocation must pick different ones.
+      const a = await allocateLocalResources("instance-a");
+      const occupiedPorts = new Set([
+        a.daemonPort,
+        a.gatewayPort,
+        a.qdrantPort,
+      ]);
+      probePortMock.mockImplementation((port: number) =>
+        Promise.resolve(occupiedPorts.has(port)),
+      );
+
+      const b = await allocateLocalResources("instance-b");
+
+      // All six ports must be unique across both instances
+      const allPorts = [
+        a.daemonPort,
+        a.gatewayPort,
+        a.qdrantPort,
+        b.daemonPort,
+        b.gatewayPort,
+        b.qdrantPort,
+      ];
+      expect(new Set(allPorts).size).toBe(6);
+
+      // Instance dirs must be distinct
+      expect(a.instanceDir).not.toBe(b.instanceDir);
+      expect(a.instanceDir).toContain("instance-a");
+      expect(b.instanceDir).toContain("instance-b");
+    });
+
+    test("skips ports that probePort reports as in-use", async () => {
+      // Simulate the default ports being occupied
+      const portsInUse = new Set([
+        DEFAULT_DAEMON_PORT,
+        DEFAULT_DAEMON_PORT + 1,
+      ]);
+      probePortMock.mockImplementation((port: number) =>
+        Promise.resolve(portsInUse.has(port)),
+      );
+
+      const res = await allocateLocalResources("probe-test");
+      expect(res.daemonPort).toBeGreaterThan(DEFAULT_DAEMON_PORT + 1);
+      expect(portsInUse.has(res.daemonPort)).toBe(false);
+    });
+  });
+
+  describe("defaultLocalResources() returns legacy paths", () => {
+    test("instanceDir is homedir", () => {
+      const res = defaultLocalResources();
+      expect(res.instanceDir).toBe(testDir);
+    });
+
+    test("daemonPort is DEFAULT_DAEMON_PORT", () => {
+      const res = defaultLocalResources();
+      expect(res.daemonPort).toBe(DEFAULT_DAEMON_PORT);
+    });
+  });
+
+  describe("resolveTargetAssistant() priority chain", () => {
+    test("explicit name returns that entry", () => {
+      writeLockfile({
+        assistants: [makeEntry("alpha"), makeEntry("beta")],
+      });
+      const result = resolveTargetAssistant("beta");
+      expect(result.assistantId).toBe("beta");
+    });
+
+    test("active assistant set returns the active entry", () => {
+      writeLockfile({
+        assistants: [makeEntry("alpha"), makeEntry("beta")],
+        activeAssistant: "alpha",
+      });
+      const result = resolveTargetAssistant();
+      expect(result.assistantId).toBe("alpha");
+    });
+
+    test("sole local assistant returns it", () => {
+      writeLockfile({
+        assistants: [makeEntry("only-one")],
+      });
+      const result = resolveTargetAssistant();
+      expect(result.assistantId).toBe("only-one");
+    });
+
+    test("multiple local assistants and no active throws with guidance", () => {
+      writeLockfile({
+        assistants: [makeEntry("x"), makeEntry("y")],
+      });
+      // resolveTargetAssistant calls process.exit(1) on ambiguity
+      const mockExit = mock(() => {
+        throw new Error("process.exit called");
+      });
+      const origExit = process.exit;
+      process.exit = mockExit as unknown as typeof process.exit;
+      try {
+        expect(() => resolveTargetAssistant()).toThrow("process.exit called");
+        expect(mockExit).toHaveBeenCalledWith(1);
+      } finally {
+        process.exit = origExit;
+      }
+    });
+
+    test("no local assistants throws", () => {
+      writeLockfile({ assistants: [] });
+      const mockExit = mock(() => {
+        throw new Error("process.exit called");
+      });
+      const origExit = process.exit;
+      process.exit = mockExit as unknown as typeof process.exit;
+      try {
+        expect(() => resolveTargetAssistant()).toThrow("process.exit called");
+        expect(mockExit).toHaveBeenCalledWith(1);
+      } finally {
+        process.exit = origExit;
+      }
+    });
+  });
+
+  describe("setActiveAssistant() / getActiveAssistant() round-trip", () => {
+    test("set active, read it back", () => {
+      writeLockfile({ assistants: [makeEntry("my-assistant")] });
+      setActiveAssistant("my-assistant");
+      expect(getActiveAssistant()).toBe("my-assistant");
+    });
+
+    test("lockfile is updated on disk", () => {
+      writeLockfile({ assistants: [makeEntry("disk-check")] });
+      setActiveAssistant("disk-check");
+      const raw = readLockfileRaw();
+      expect(raw.activeAssistant).toBe("disk-check");
+    });
+  });
+
+  describe("removeAssistantEntry() clears matching activeAssistant", () => {
+    test("set active to foo, remove foo, verify active is null", () => {
+      writeLockfile({
+        assistants: [makeEntry("foo"), makeEntry("bar")],
+        activeAssistant: "foo",
+      });
+      removeAssistantEntry("foo");
+      expect(getActiveAssistant()).toBeNull();
+    });
+
+    test("set active to foo, remove bar, verify active is still foo", () => {
+      writeLockfile({
+        assistants: [makeEntry("foo"), makeEntry("bar")],
+        activeAssistant: "foo",
+      });
+      removeAssistantEntry("bar");
+      expect(getActiveAssistant()).toBe("foo");
+    });
+  });
+
+  describe("remote non-regression", () => {
+    test("resolveTargetAssistant works with remote entries", () => {
+      writeLockfile({
+        assistants: [
+          makeEntry("my-remote", "gcp", {
+            runtimeUrl: "http://10.0.0.1:7821",
+          }),
+        ],
+        activeAssistant: "my-remote",
+      });
+      const result = resolveTargetAssistant();
+      expect(result.assistantId).toBe("my-remote");
+      expect(result.cloud).toBe("gcp");
+    });
+
+    test("remote entries don't get resources applied", () => {
+      const remoteEntry = makeEntry("cloud-box", "aws", {
+        runtimeUrl: "http://10.0.0.2:7821",
+      });
+      writeLockfile({ assistants: [remoteEntry] });
+      // Save and reload to verify resources are not injected
+      saveAssistantEntry(remoteEntry);
+      const result = resolveTargetAssistant("cloud-box");
+      expect(result.resources).toBeUndefined();
+    });
+  });
+});

package/src/__tests__/skills-uninstall.test.ts

@@ -49,7 +49,9 @@ beforeEach(() => {
 afterEach(() => {
   process.argv = originalArgv;
   process.env.BASE_DATA_DIR = originalBaseDataDir;
-  process.exitCode = originalExitCode;
+  // Bun treats `process.exitCode = undefined` as a no-op, so explicitly
+  // reset to 0 when the original value was not set.
+  process.exitCode = originalExitCode ?? 0;
   rmSync(tempDir, { recursive: true, force: true });
 });
 

package/src/commands/client.ts

@@ -1,5 +1,6 @@
 import {
   findAssistantByName,
+  getActiveAssistant,
   loadLatestAssistant,
 } from "../lib/assistant-config";
 import { GATEWAY_PORT, type Species } from "../lib/constants";
@@ -45,16 +46,31 @@ function parseArgs(): ParsedArgs {
     }
   }
 
-  const entry = positionalName
-    ? findAssistantByName(positionalName)
-    : loadLatestAssistant();
-  if (positionalName && !entry) {
-    console.error(`No assistant instance found with name '${positionalName}'.`);
-    process.exit(1);
+  let entry: ReturnType<typeof findAssistantByName>;
+  if (positionalName) {
+    entry = findAssistantByName(positionalName);
+    if (!entry) {
+      console.error(
+        `No assistant instance found with name '${positionalName}'.`,
+      );
+      process.exit(1);
+    }
+  } else if (process.env.RUNTIME_URL) {
+    // Explicit env var — skip assistant resolution, will use env values below
+    entry = loadLatestAssistant();
+  } else {
+    // Respect active assistant when set, otherwise fall back to latest
+    // for backward compatibility with remote-only setups.
+    const active = getActiveAssistant();
+    const activeEntry = active ? findAssistantByName(active) : null;
+    entry = activeEntry ?? loadLatestAssistant();
   }
 
   let runtimeUrl =
-    process.env.RUNTIME_URL || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
+    process.env.RUNTIME_URL ||
+    entry?.localUrl ||
+    entry?.runtimeUrl ||
+    FALLBACK_RUNTIME_URL;
   let assistantId =
     process.env.ASSISTANT_ID || entry?.assistantId || FALLBACK_ASSISTANT_ID;
   const bearerToken =

package/src/commands/hatch.ts

@@ -21,14 +21,19 @@ import cliPkg from "../../package.json";
 
 import { buildOpenclawStartupScript } from "../adapters/openclaw";
 import {
+  allocateLocalResources,
+  defaultLocalResources,
+  findAssistantByName,
   loadAllAssistants,
   saveAssistantEntry,
   syncConfigToLockfile,
 } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
+import type {
+  AssistantEntry,
+  LocalInstanceResources,
+} from "../lib/assistant-config";
 import { hatchAws } from "../lib/aws";
 import {
-  GATEWAY_PORT,
   SPECIES_CONFIG,
   VALID_REMOTE_HOSTS,
   VALID_SPECIES,
@@ -41,7 +46,6 @@ import {
   startGateway,
   stopLocalProcesses,
 } from "../lib/local";
-import { probePort } from "../lib/port-probe";
 import { isProcessAlive } from "../lib/process";
 import { generateRandomSuffix } from "../lib/random-name";
 import { validateAssistantName } from "../lib/retire-archive";
@@ -583,6 +587,8 @@ async function waitForDaemonReady(
 async function displayPairingQRCode(
   runtimeUrl: string,
   bearerToken: string | undefined,
+  /** External gateway URL for the QR payload. When omitted, runtimeUrl is used. */
+  externalGatewayUrl?: string,
 ): Promise<void> {
   try {
     const pairingRequestId = randomUUID();
@@ -609,7 +615,7 @@ async function displayPairingQRCode(
       body: JSON.stringify({
         pairingRequestId,
         pairingSecret,
-        gatewayUrl: runtimeUrl,
+        gatewayUrl: externalGatewayUrl ?? runtimeUrl,
       }),
     });
 
@@ -628,7 +634,7 @@ async function displayPairingQRCode(
       type: "vellum-daemon",
       v: 4,
       id: hostId,
-      g: runtimeUrl,
+      g: externalGatewayUrl ?? runtimeUrl,
       pairingRequestId,
       pairingSecret,
     });
@@ -703,64 +709,49 @@ async function hatchLocal(
       );
       await stopLocalProcesses();
     }
+  }
 
-    // Verify required ports are available before starting any services.
-    // Only check when no local assistants exist — if there are existing local
-    // assistants, their daemon/gateway/qdrant legitimately own these ports.
-    const RUNTIME_HTTP_PORT = Number(process.env.RUNTIME_HTTP_PORT) || 7821;
-    const QDRANT_PORT = 6333;
-    const requiredPorts = [
-      { name: "daemon", port: RUNTIME_HTTP_PORT },
-      { name: "gateway", port: GATEWAY_PORT },
-      { name: "qdrant", port: QDRANT_PORT },
-    ];
-    const conflicts: string[] = [];
-    await Promise.all(
-      requiredPorts.map(async ({ name, port }) => {
-        if (await probePort(port)) {
-          conflicts.push(`  - Port ${port} (${name}) is already in use`);
-        }
-      }),
-    );
-    if (conflicts.length > 0) {
-      throw new Error(
-        `Cannot hatch — required ports are already in use:\n${conflicts.join("\n")}\n\n` +
-          "Stop the conflicting processes or use environment variables to configure alternative ports " +
-          "(RUNTIME_HTTP_PORT, GATEWAY_PORT).",
-      );
-    }
+  // Reuse existing resources if re-hatching with --name that matches a known
+  // local assistant, otherwise allocate fresh per-instance ports and directories.
+  let resources: LocalInstanceResources;
+  const existingEntry = findAssistantByName(instanceName);
+  if (existingEntry?.cloud === "local" && existingEntry.resources) {
+    resources = existingEntry.resources;
+  } else if (restart && existingEntry?.cloud === "local") {
+    // Legacy entry without resources — use default paths to match existing layout
+    resources = defaultLocalResources();
+  } else {
+    resources = await allocateLocalResources(instanceName);
   }
 
-  const baseDataDir = join(
-    process.env.BASE_DATA_DIR?.trim() ||
-      (process.env.HOME ?? userInfo().homedir),
-    ".vellum",
-  );
+  const baseDataDir = join(resources.instanceDir, ".vellum");
 
   console.log(`🥚 Hatching local assistant: ${instanceName}`);
   console.log(`   Species: ${species}`);
   console.log("");
 
-  await startLocalDaemon(watch);
+  await startLocalDaemon(watch, resources);
 
   let runtimeUrl: string;
   try {
-    runtimeUrl = await startGateway(instanceName, watch);
+    runtimeUrl = await startGateway(instanceName, watch, resources);
   } catch (error) {
     // Gateway failed — stop the daemon we just started so we don't leave
     // orphaned processes with no lock file entry.
     console.error(
       `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
     );
-    await stopLocalProcesses();
+    await stopLocalProcesses(resources);
     throw error;
   }
 
   // Read the bearer token (JWT) written by the daemon so the CLI can
-  // authenticate with the gateway.
+  // with the gateway (which requires auth by default). The daemon writes under
+  // getRootDir() which resolves to <instanceDir>/.vellum/.
   let bearerToken: string | undefined;
   try {
-    const token = readFileSync(join(baseDataDir, "http-token"), "utf-8").trim();
+    const tokenPath = join(resources.instanceDir, ".vellum", "http-token");
+    const token = readFileSync(tokenPath, "utf-8").trim();
     if (token) bearerToken = token;
   } catch {
     // Token file may not exist if daemon started without HTTP server
@@ -769,11 +760,13 @@ async function hatchLocal(
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
+    localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
     baseDataDir,
     bearerToken,
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
+    resources,
   };
   if (!daemonOnly && !restart) {
     saveAssistantEntry(localEntry);
@@ -791,8 +784,11 @@ async function hatchLocal(
     console.log(`  Runtime: ${runtimeUrl}`);
     console.log("");
 
-    // Generate and display pairing QR code
-    await displayPairingQRCode(runtimeUrl, bearerToken);
+    // Use loopback for HTTP calls (health check + pairing register) since
+    // mDNS hostnames may not resolve on the local machine, but keep the
+    // external runtimeUrl in the QR payload so iOS devices can reach it.
+    const localGatewayUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+    await displayPairingQRCode(localGatewayUrl, bearerToken, runtimeUrl);
   }
 }
 

package/src/commands/ps.ts

@@ -3,20 +3,18 @@ import { homedir } from "os";
 import { join } from "path";
 
 import {
+  defaultLocalResources,
   findAssistantByName,
+  getActiveAssistant,
   loadAllAssistants,
   type AssistantEntry,
 } from "../lib/assistant-config";
-import { GATEWAY_PORT } from "../lib/constants";
 import { checkHealth } from "../lib/health-check";
 import { pgrepExact } from "../lib/pgrep";
 import { probePort } from "../lib/port-probe";
 import { withStatusEmoji } from "../lib/status-emoji";
 import { execOutput } from "../lib/step-runner";
 
-const RUNTIME_HTTP_PORT = Number(process.env.RUNTIME_HTTP_PORT) || 7821;
-const QDRANT_PORT = 6333;
-
 // ── Table formatting helpers ────────────────────────────────────
 
 interface TableRow {
@@ -218,25 +216,26 @@ function formatDetectionInfo(proc: DetectedProcess): string {
 }
 
 async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
-  const vellumDir = entry.baseDataDir ?? join(homedir(), ".vellum");
+  const resources = entry.resources ?? defaultLocalResources();
+  const vellumDir = join(resources.instanceDir, ".vellum");
 
   const specs: ProcessSpec[] = [
     {
       name: "assistant",
       pgrepName: "vellum-daemon",
-      port: RUNTIME_HTTP_PORT,
-      pidFile: join(vellumDir, "vellum.pid"),
+      port: resources.daemonPort,
+      pidFile: resources.pidFile,
     },
     {
       name: "qdrant",
       pgrepName: "qdrant",
-      port: QDRANT_PORT,
+      port: resources.qdrantPort,
       pidFile: join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"),
     },
     {
       name: "gateway",
       pgrepName: "vellum-gateway",
-      port: GATEWAY_PORT,
+      port: resources.gatewayPort,
       pidFile: join(vellumDir, "gateway.pid"),
     },
     {
@@ -355,6 +354,7 @@ async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
 
 async function listAllAssistants(): Promise<void> {
   const assistants = loadAllAssistants();
+  const activeId = getActiveAssistant();
 
   if (assistants.length === 0) {
     console.log("No assistants found.");
@@ -381,9 +381,10 @@ async function listAllAssistants(): Promise<void> {
     const infoParts = [a.runtimeUrl];
     if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
     if (a.species) infoParts.push(`species: ${a.species}`);
+    const prefix = a.assistantId === activeId ? "* " : "  ";
 
     return {
-      name: a.assistantId,
+      name: prefix + a.assistantId,
       status: withStatusEmoji("checking..."),
       info: infoParts.join(" | "),
     };
@@ -403,15 +404,34 @@ async function listAllAssistants(): Promise<void> {
 
   await Promise.all(
     assistants.map(async (a, rowIndex) => {
-      const health = await checkHealth(a.runtimeUrl, a.bearerToken);
+      // For local assistants, check if the daemon process is alive before
+      // hitting the health endpoint. If the PID file is missing or the
+      // process isn't running, the assistant is sleeping — skip the
+      // network health check to avoid a misleading "unreachable" status.
+      let health: { status: string; detail: string | null };
+      const resources =
+        a.resources ??
+        (a.cloud === "local" ? defaultLocalResources() : undefined);
+      if (a.cloud === "local" && resources) {
+        const pid = readPidFile(resources.pidFile);
+        const alive = pid !== null && isProcessAlive(pid);
+        if (!alive) {
+          health = { status: "sleeping", detail: null };
+        } else {
+          health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+        }
+      } else {
+        health = await checkHealth(a.localUrl ?? a.runtimeUrl, a.bearerToken);
+      }
 
       const infoParts = [a.runtimeUrl];
       if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
       if (a.species) infoParts.push(`species: ${a.species}`);
       if (health.detail) infoParts.push(health.detail);
 
+      const prefix = a.assistantId === activeId ? "* " : "  ";
       const updatedRow: TableRow = {
-        name: a.assistantId,
+        name: prefix + a.assistantId,
         status: withStatusEmoji(health.status),
         info: infoParts.join(" | "),
       };