@vellumai/cli 0.4.42 → 0.4.43

package/package.json

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

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

@@ -5,7 +5,7 @@ import { join } from "node:path";
 
 // Point lockfile operations at a temp directory
 const testDir = mkdtempSync(join(tmpdir(), "cli-assistant-config-test-"));
-process.env.BASE_DATA_DIR = testDir;
+process.env.VELLUM_LOCKFILE_DIR = testDir;
 
 import {
   loadLatestAssistant,
@@ -13,12 +13,13 @@ import {
   removeAssistantEntry,
   loadAllAssistants,
   saveAssistantEntry,
+  getActiveAssistant,
   type AssistantEntry,
 } from "../lib/assistant-config.js";
 
 afterAll(() => {
   rmSync(testDir, { recursive: true, force: true });
-  delete process.env.BASE_DATA_DIR;
+  delete process.env.VELLUM_LOCKFILE_DIR;
 });
 
 function writeLockfile(data: unknown): void {
@@ -100,6 +101,36 @@ describe("assistant-config", () => {
     expect(all.map((e) => e.assistantId)).toEqual(["a", "c"]);
   });
 
+  test("removeAssistantEntry reassigns activeAssistant to remaining entry", () => {
+    writeLockfile({
+      assistants: [makeEntry("a"), makeEntry("b")],
+      activeAssistant: "a",
+    });
+    removeAssistantEntry("a");
+    expect(getActiveAssistant()).toBe("b");
+    expect(loadAllAssistants()).toHaveLength(1);
+  });
+
+  test("removeAssistantEntry clears activeAssistant when no entries remain", () => {
+    writeLockfile({
+      assistants: [makeEntry("only")],
+      activeAssistant: "only",
+    });
+    removeAssistantEntry("only");
+    expect(getActiveAssistant()).toBeNull();
+    expect(loadAllAssistants()).toHaveLength(0);
+  });
+
+  test("removeAssistantEntry preserves activeAssistant when removing a different entry", () => {
+    writeLockfile({
+      assistants: [makeEntry("a"), makeEntry("b"), makeEntry("c")],
+      activeAssistant: "a",
+    });
+    removeAssistantEntry("b");
+    expect(getActiveAssistant()).toBe("a");
+    expect(loadAllAssistants()).toHaveLength(2);
+  });
+
   test("loadLatestAssistant returns null when empty", () => {
     expect(loadLatestAssistant()).toBeNull();
   });

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

@@ -4,9 +4,9 @@ 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.
+// never touches the real ~/.vellum directory.
 const testDir = mkdtempSync(join(tmpdir(), "cli-multi-local-test-"));
-process.env.BASE_DATA_DIR = testDir;
+process.env.VELLUM_LOCKFILE_DIR = testDir;
 
 // Mock homedir() to return testDir — this isolates allocateLocalResources()
 // which uses homedir() directly for instance directory creation.
@@ -31,7 +31,6 @@ mock.module("../lib/port-probe.js", () => ({
 
 import {
   allocateLocalResources,
-  defaultLocalResources,
   resolveTargetAssistant,
   setActiveAssistant,
   getActiveAssistant,
@@ -47,7 +46,7 @@ import {
 
 afterAll(() => {
   rmSync(testDir, { recursive: true, force: true });
-  delete process.env.BASE_DATA_DIR;
+  delete process.env.VELLUM_LOCKFILE_DIR;
 });
 
 function writeLockfile(data: unknown): void {
@@ -95,14 +94,18 @@ describe("multi-local", () => {
   });
 
   describe("allocateLocalResources() produces non-conflicting ports", () => {
-    test("first instance returns default legacy resources", async () => {
+    test("first instance gets XDG path 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 returns the default legacy layout (home dir, default ports)
-      expect(res.instanceDir).toBe(testDir);
+      // THEN it gets an XDG instance directory under the home dir
+      expect(res.instanceDir).toBe(
+        join(testDir, ".local", "share", "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);
@@ -156,18 +159,6 @@ describe("multi-local", () => {
     });
   });
 
-  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({
@@ -243,14 +234,14 @@ describe("multi-local", () => {
     });
   });
 
-  describe("removeAssistantEntry() clears matching activeAssistant", () => {
-    test("set active to foo, remove foo, verify active is null", () => {
+  describe("removeAssistantEntry() reassigns activeAssistant on removal", () => {
+    test("set active to foo, remove foo, verify active is reassigned to bar", () => {
       writeLockfile({
         assistants: [makeEntry("foo"), makeEntry("bar")],
         activeAssistant: "foo",
       });
       removeAssistantEntry("foo");
-      expect(getActiveAssistant()).toBeNull();
+      expect(getActiveAssistant()).toBe("bar");
     });
 
     test("set active to foo, remove bar, verify active is still foo", () => {

package/src/__tests__/sleep.test.ts

@@ -0,0 +1,172 @@
+import {
+  afterAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Create a temp directory and set VELLUM_LOCKFILE_DIR so the real
+// assistant-config module reads/writes the lockfile here instead of ~/.
+const testDir = mkdtempSync(join(tmpdir(), "sleep-command-test-"));
+const assistantRootDir = join(testDir, ".vellum");
+process.env.VELLUM_LOCKFILE_DIR = testDir;
+
+const stopProcessByPidFileMock = mock(async () => true);
+const isProcessAliveMock = mock((): { alive: boolean; pid: number | null } => ({
+  alive: false,
+  pid: null,
+}));
+
+mock.module("../lib/process.js", () => ({
+  isProcessAlive: isProcessAliveMock,
+  stopProcessByPidFile: stopProcessByPidFileMock,
+}));
+
+import { sleep } from "../commands/sleep.js";
+import {
+  DEFAULT_DAEMON_PORT,
+  DEFAULT_GATEWAY_PORT,
+  DEFAULT_QDRANT_PORT,
+} from "../lib/constants.js";
+
+// Write a lockfile entry so the real resolveTargetAssistant() finds our test
+// assistant without needing to mock the entire assistant-config module.
+function writeLockfile(): void {
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify(
+      {
+        assistants: [
+          {
+            assistantId: "sleep-test",
+            runtimeUrl: `http://127.0.0.1:${DEFAULT_DAEMON_PORT}`,
+            cloud: "local",
+            resources: {
+              instanceDir: testDir,
+              daemonPort: DEFAULT_DAEMON_PORT,
+              gatewayPort: DEFAULT_GATEWAY_PORT,
+              qdrantPort: DEFAULT_QDRANT_PORT,
+              pidFile: join(assistantRootDir, "vellum.pid"),
+            },
+          },
+        ],
+        activeAssistant: "sleep-test",
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function writeLeaseFile(callSessionIds: string[]): void {
+  mkdirSync(assistantRootDir, { recursive: true });
+  writeFileSync(
+    join(assistantRootDir, "active-call-leases.json"),
+    JSON.stringify(
+      {
+        version: 1,
+        leases: callSessionIds.map((callSessionId) => ({
+          callSessionId,
+          providerCallSid: null,
+          updatedAt: Date.now(),
+        })),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+describe("sleep command", () => {
+  let originalArgv: string[];
+
+  beforeEach(() => {
+    originalArgv = [...process.argv];
+    isProcessAliveMock.mockReset();
+    isProcessAliveMock.mockReturnValue({ alive: false, pid: null });
+    stopProcessByPidFileMock.mockReset();
+    stopProcessByPidFileMock.mockResolvedValue(true);
+    rmSync(assistantRootDir, { recursive: true, force: true });
+    writeLockfile();
+  });
+
+  afterAll(() => {
+    process.argv = originalArgv;
+    rmSync(testDir, { recursive: true, force: true });
+    delete process.env.VELLUM_LOCKFILE_DIR;
+  });
+
+  test("refuses normal sleep while an active call lease exists", async () => {
+    isProcessAliveMock.mockReturnValue({ alive: true, pid: 12345 });
+    writeLeaseFile(["call-active-1", "call-active-2"]);
+    process.argv = ["bun", "vellum", "sleep", "sleep-test"];
+
+    const consoleError = spyOn(console, "error").mockImplementation(() => {});
+    const exitMock = mock((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    });
+    const originalExit = process.exit;
+    process.exit = exitMock as unknown as typeof process.exit;
+
+    try {
+      await expect(sleep()).rejects.toThrow("process.exit:1");
+      expect(consoleError).toHaveBeenCalledWith(
+        expect.stringContaining("vellum sleep --force"),
+      );
+    } finally {
+      process.exit = originalExit;
+      consoleError.mockRestore();
+    }
+
+    expect(stopProcessByPidFileMock).not.toHaveBeenCalled();
+  });
+
+  test("proceeds when assistant is not running even with stale lease file", async () => {
+    isProcessAliveMock.mockReturnValue({ alive: false, pid: null });
+    writeLeaseFile(["call-stale-1"]);
+    process.argv = ["bun", "vellum", "sleep", "sleep-test"];
+
+    const consoleLog = spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await sleep();
+    } finally {
+      consoleLog.mockRestore();
+    }
+
+    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("force stops the assistant even when an active call lease exists", async () => {
+    writeLeaseFile(["call-active-1"]);
+    process.argv = ["bun", "vellum", "sleep", "sleep-test", "--force"];
+
+    const consoleLog = spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await sleep();
+    } finally {
+      consoleLog.mockRestore();
+    }
+
+    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(2);
+    expect(stopProcessByPidFileMock).toHaveBeenNthCalledWith(
+      1,
+      join(assistantRootDir, "vellum.pid"),
+      "assistant",
+    );
+    expect(stopProcessByPidFileMock).toHaveBeenNthCalledWith(
+      2,
+      join(assistantRootDir, "gateway.pid"),
+      "gateway",
+      undefined,
+      7000,
+    );
+  });
+});

package/src/commands/client.ts

@@ -1,9 +1,12 @@
+import { hostname } from "os";
+
 import {
   findAssistantByName,
   getActiveAssistant,
   loadLatestAssistant,
 } from "../lib/assistant-config";
 import { GATEWAY_PORT, type Species } from "../lib/constants";
+import { getLocalLanIPv4, getMacLocalHostname } from "../lib/local";
 
 const ANSI = {
   reset: "\x1b[0m",
@@ -46,7 +49,7 @@ function parseArgs(): ParsedArgs {
     }
   }
 
-  let entry: ReturnType<typeof findAssistantByName>;
+  let entry: ReturnType<typeof findAssistantByName> = null;
   if (positionalName) {
     entry = findAssistantByName(positionalName);
     if (!entry) {
@@ -55,15 +58,30 @@ function parseArgs(): ParsedArgs {
       );
       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 hasExplicitUrl =
+      process.env.RUNTIME_URL ||
+      flagArgs.includes("--url") ||
+      flagArgs.includes("-u");
     const active = getActiveAssistant();
-    const activeEntry = active ? findAssistantByName(active) : null;
-    entry = activeEntry ?? loadLatestAssistant();
+    if (active) {
+      entry = findAssistantByName(active);
+      if (!entry && !hasExplicitUrl) {
+        console.error(
+          `Active assistant '${active}' not found in lockfile. Set an active assistant with 'vellum use <name>'.`,
+        );
+        process.exit(1);
+      }
+    }
+    if (!entry && hasExplicitUrl) {
+      // URL provided but active assistant missing or unset — use latest for remaining defaults
+      entry = loadLatestAssistant();
+    } else if (!entry) {
+      console.error(
+        "No active assistant set. Set one with 'vellum use <name>' or specify a name: 'vellum client <name>'.",
+      );
+      process.exit(1);
+    }
   }
 
   let runtimeUrl =
@@ -90,7 +108,7 @@ function parseArgs(): ParsedArgs {
   }
 
   return {
-    runtimeUrl: runtimeUrl.replace(/\/+$/, ""),
+    runtimeUrl: maybeSwapToLocalhost(runtimeUrl.replace(/\/+$/, "")),
     assistantId,
     species,
     bearerToken,
@@ -99,6 +117,50 @@ function parseArgs(): ParsedArgs {
   };
 }
 
+/**
+ * If the hostname in `url` matches this machine's local DNS name, LAN IP, or
+ * raw hostname, replace it with 127.0.0.1 so the client avoids mDNS round-trips
+ * when talking to an assistant running on the same machine.
+ */
+function maybeSwapToLocalhost(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+
+  const urlHost = parsed.hostname.toLowerCase();
+
+  const localNames: string[] = [];
+
+  const host = hostname();
+  if (host) {
+    localNames.push(host.toLowerCase());
+    // Also consider the bare name without .local suffix
+    if (host.toLowerCase().endsWith(".local")) {
+      localNames.push(host.toLowerCase().slice(0, -".local".length));
+    }
+  }
+
+  const macHost = getMacLocalHostname();
+  if (macHost) {
+    localNames.push(macHost.toLowerCase());
+  }
+
+  const lanIp = getLocalLanIPv4();
+  if (lanIp) {
+    localNames.push(lanIp);
+  }
+
+  if (localNames.includes(urlHost)) {
+    parsed.hostname = "127.0.0.1";
+    return parsed.toString().replace(/\/+$/, "");
+  }
+
+  return url;
+}
+
 function printUsage(): void {
   console.log(`${ANSI.bold}vellum client${ANSI.reset} - Connect to a hatched assistant
 
@@ -106,7 +168,7 @@ ${ANSI.bold}USAGE:${ANSI.reset}
     vellum client [name] [options]
 
 ${ANSI.bold}ARGUMENTS:${ANSI.reset}
-    [name]                     Instance name (default: latest)
+    [name]                     Instance name (default: active)
 
 ${ANSI.bold}OPTIONS:${ANSI.reset}
     -u, --url <url>            Runtime URL

package/src/commands/hatch.ts

@@ -22,10 +22,10 @@ import cliPkg from "../../package.json";
 import { buildOpenclawStartupScript } from "../adapters/openclaw";
 import {
   allocateLocalResources,
-  defaultLocalResources,
   findAssistantByName,
   loadAllAssistants,
   saveAssistantEntry,
+  setActiveAssistant,
   syncConfigToLockfile,
 } from "../lib/assistant-config";
 import type {
@@ -39,6 +39,7 @@ import {
   VALID_SPECIES,
 } from "../lib/constants";
 import type { RemoteHost, Species } from "../lib/constants";
+import { hatchDocker } from "../lib/docker";
 import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import {
@@ -169,6 +170,7 @@ const DEFAULT_REMOTE: RemoteHost = "local";
 interface HatchArgs {
   species: Species;
   detached: boolean;
+  keepAlive: boolean;
   name: string | null;
   remote: RemoteHost;
   daemonOnly: boolean;
@@ -180,6 +182,7 @@ function parseArgs(): HatchArgs {
   const args = process.argv.slice(3);
   let species: Species = DEFAULT_SPECIES;
   let detached = false;
+  let keepAlive = false;
   let name: string | null = null;
   let remote: RemoteHost = DEFAULT_REMOTE;
   let daemonOnly = false;
@@ -212,6 +215,9 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --watch                   Run assistant and gateway in watch mode (hot reload on source changes)",
       );
+      console.log(
+        "  --keep-alive              Stay alive after hatch, exit when gateway stops",
+      );
       process.exit(0);
     } else if (arg === "-d") {
       detached = true;
@@ -221,6 +227,8 @@ function parseArgs(): HatchArgs {
       restart = true;
     } else if (arg === "--watch") {
       watch = true;
+    } else if (arg === "--keep-alive") {
+      keepAlive = true;
     } else if (arg === "--name") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
@@ -251,13 +259,13 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --daemon-only, --restart, --watch, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --daemon-only, --restart, --watch, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
       );
       process.exit(1);
     }
   }
 
-  return { species, detached, name, remote, daemonOnly, restart, watch };
+  return { species, detached, keepAlive, name, remote, daemonOnly, restart, watch };
 }
 
 function formatElapsed(ms: number): string {
@@ -682,6 +690,7 @@ async function hatchLocal(
   daemonOnly: boolean = false,
   restart: boolean = false,
   watch: boolean = false,
+  keepAlive: boolean = false,
 ): Promise<void> {
   if (restart && !name && !process.env.VELLUM_ASSISTANT_NAME) {
     console.error(
@@ -717,15 +726,10 @@ async function hatchLocal(
   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(resources.instanceDir, ".vellum");
-
   console.log(`🥚 Hatching local assistant: ${instanceName}`);
   console.log(`   Species: ${species}`);
   console.log("");
@@ -761,7 +765,6 @@ async function hatchLocal(
     assistantId: instanceName,
     runtimeUrl,
     localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
-    baseDataDir,
     bearerToken,
     cloud: "local",
     species,
@@ -770,6 +773,7 @@ async function hatchLocal(
   };
   if (!daemonOnly && !restart) {
     saveAssistantEntry(localEntry);
+    setActiveAssistant(instanceName);
     syncConfigToLockfile();
 
     if (process.env.VELLUM_DESKTOP_APP) {
@@ -790,6 +794,46 @@ async function hatchLocal(
     const localGatewayUrl = `http://127.0.0.1:${resources.gatewayPort}`;
     await displayPairingQRCode(localGatewayUrl, bearerToken, runtimeUrl);
   }
+
+  if (keepAlive) {
+    const gatewayHealthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
+    const POLL_INTERVAL_MS = 5000;
+    const MAX_FAILURES = 3;
+    let consecutiveFailures = 0;
+
+    const shutdown = async (): Promise<void> => {
+      console.log("\nShutting down local processes...");
+      await stopLocalProcesses(resources);
+      process.exit(0);
+    };
+
+    process.on("SIGTERM", () => void shutdown());
+    process.on("SIGINT", () => void shutdown());
+
+    // Poll the gateway health endpoint until it stops responding.
+    while (true) {
+      await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+      try {
+        const res = await fetch(gatewayHealthUrl, {
+          signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+          consecutiveFailures = 0;
+        } else {
+          consecutiveFailures++;
+        }
+      } catch {
+        consecutiveFailures++;
+      }
+      if (consecutiveFailures >= MAX_FAILURES) {
+        console.log(
+          "\n⚠️  Gateway stopped responding — shutting down.",
+        );
+        await stopLocalProcesses(resources);
+        process.exit(1);
+      }
+    }
+  }
 }
 
 function getCliVersion(): string {
@@ -800,7 +844,7 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const { species, detached, name, remote, daemonOnly, restart, watch } =
+  const { species, detached, keepAlive, name, remote, daemonOnly, restart, watch } =
     parseArgs();
 
   if (restart && remote !== "local") {
@@ -810,13 +854,15 @@ export async function hatch(): Promise<void> {
     process.exit(1);
   }
 
-  if (watch && remote !== "local") {
-    console.error("Error: --watch is only supported for local hatch targets.");
+  if (watch && remote !== "local" && remote !== "docker") {
+    console.error(
+      "Error: --watch is only supported for local and docker hatch targets.",
+    );
     process.exit(1);
   }
 
   if (remote === "local") {
-    await hatchLocal(species, name, daemonOnly, restart, watch);
+    await hatchLocal(species, name, daemonOnly, restart, watch, keepAlive);
     return;
   }
 
@@ -831,8 +877,8 @@ export async function hatch(): Promise<void> {
   }
 
   if (remote === "docker") {
-    console.error("Error: Docker remote host is not yet implemented.");
-    process.exit(1);
+    await hatchDocker(species, detached, name, watch);
+    return;
   }
 
   console.error(`Error: Remote host '${remote}' is not yet supported.`);