@vellumai/cli 0.8.3 → 0.8.4

package/src/__tests__/use.test.ts

@@ -0,0 +1,144 @@
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  getActiveAssistant,
+  type AssistantEntry,
+} from "../lib/assistant-config.js";
+import { use } from "../commands/use.js";
+
+const testDir = mkdtempSync(join(tmpdir(), "cli-use-test-"));
+const originalArgv = [...process.argv];
+const originalExit = process.exit;
+const originalLockfileDir = process.env.VELLUM_LOCKFILE_DIR;
+
+let consoleLogSpy: ReturnType<typeof spyOn>;
+let consoleErrorSpy: ReturnType<typeof spyOn>;
+
+function makeEntry(
+  assistantId: string,
+  extra: Partial<AssistantEntry> = {},
+): AssistantEntry {
+  return {
+    assistantId,
+    runtimeUrl: `http://localhost:${7800 + assistantId.length}`,
+    cloud: "local",
+    ...extra,
+  };
+}
+
+function writeLockfile(
+  entries: AssistantEntry[],
+  activeAssistant?: string,
+): void {
+  mkdirSync(testDir, { recursive: true });
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify(
+      {
+        assistants: entries,
+        ...(activeAssistant ? { activeAssistant } : {}),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+describe("vellum use", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    rmSync(join(testDir, ".vellum.lock.json"), { force: true });
+    process.argv = ["bun", "vellum", "use"];
+    process.exit = ((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as typeof process.exit;
+    consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+    consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    process.exit = originalExit;
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+
+  afterAll(() => {
+    if (originalLockfileDir === undefined) {
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    } else {
+      process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+    }
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("sets active assistant by unique display name", async () => {
+    writeLockfile([
+      makeEntry("assistant-1", { name: "Alice" }),
+      makeEntry("assistant-2", { name: "Bob" }),
+    ]);
+    process.argv = ["bun", "vellum", "use", "Alice"];
+
+    await use();
+
+    expect(getActiveAssistant()).toBe("assistant-1");
+    expect(consoleLogSpy.mock.calls.flat().join("\n")).toContain(
+      "Active assistant set to Alice (assistant-1).",
+    );
+  });
+
+  test("sets active assistant by unquoted multi-word display name", async () => {
+    writeLockfile([
+      makeEntry("assistant-1", { name: "Example Assistant" }),
+      makeEntry("assistant-2", { name: "Bob" }),
+    ]);
+    process.argv = ["bun", "vellum", "use", "Example", "Assistant"];
+
+    await use();
+
+    expect(getActiveAssistant()).toBe("assistant-1");
+    expect(consoleLogSpy.mock.calls.flat().join("\n")).toContain(
+      "Active assistant set to Example Assistant (assistant-1).",
+    );
+  });
+
+  test("prints active assistant with display name and id", async () => {
+    writeLockfile([makeEntry("assistant-1", { name: "Alice" })], "assistant-1");
+
+    await use();
+
+    expect(consoleLogSpy.mock.calls.flat().join("\n")).toContain(
+      "Active assistant: Alice (assistant-1)",
+    );
+  });
+
+  test("rejects ambiguous display names without changing active assistant", async () => {
+    writeLockfile(
+      [
+        makeEntry("assistant-1", { name: "Alice" }),
+        makeEntry("assistant-2", { name: "Alice" }),
+      ],
+      "assistant-2",
+    );
+    process.argv = ["bun", "vellum", "use", "Alice"];
+
+    await expect(use()).rejects.toThrow("process.exit:1");
+
+    expect(getActiveAssistant()).toBe("assistant-2");
+    const output = consoleErrorSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Multiple assistants match 'Alice'");
+    expect(output).toContain("assistant-1");
+    expect(output).toContain("assistant-2");
+  });
+});

package/src/commands/client.ts

@@ -4,9 +4,12 @@ import path from "node:path";
 
 import {
   findAssistantByName,
+  formatAssistantLookupError,
   getActiveAssistant,
+  lookupAssistantByIdentifier,
   resolveAssistant,
   saveAssistantEntry,
+  type AssistantEntry,
 } from "../lib/assistant-config";
 import {
   DAEMON_INTERNAL_ASSISTANT_ID,
@@ -20,6 +23,7 @@ import {
   WEB_INTERFACE_ID,
   getClientRegistrationHeaders,
 } from "../lib/client-identity";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import {
   fetchOrganizationId,
   fetchPlatformAssistants,
@@ -51,13 +55,9 @@ interface ParsedArgs {
   bearerToken?: string;
   /** Interface identifier sent as X-Vellum-Interface-Id on all requests. */
   interfaceId: SupportedInterface;
-  project?: string;
-  zone?: string;
 }
 
-function readAssistantName(
-  entry: ReturnType<typeof findAssistantByName>,
-): string | undefined {
+function readAssistantName(entry: AssistantEntry | null): string | undefined {
   const rawName = entry?.name ?? entry?.assistantName;
   return typeof rawName === "string" && rawName.trim()
     ? rawName.trim()
@@ -67,7 +67,14 @@ function readAssistantName(
 function parseArgs(): ParsedArgs {
   const args = process.argv.slice(3);
 
-  let positionalName: string | undefined;
+  const positionalName = parseAssistantTargetArg(args, [
+    "--url",
+    "-u",
+    "--assistant-id",
+    "-a",
+    "--interface",
+    "-i",
+  ]);
   const flagArgs: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -84,29 +91,29 @@ function parseArgs(): ParsedArgs {
       args[i + 1]
     ) {
       flagArgs.push(arg, args[++i]);
-    } else if (!arg.startsWith("-") && positionalName === undefined) {
-      positionalName = arg;
     }
   }
 
-  let entry: ReturnType<typeof findAssistantByName> = null;
+  let entry: AssistantEntry | null = null;
   if (positionalName) {
-    entry = findAssistantByName(positionalName);
-    if (!entry) {
-      console.error(
-        `No assistant instance found with name '${positionalName}'.`,
-      );
+    const result = lookupAssistantByIdentifier(positionalName);
+    if (result.status !== "found") {
+      console.error(formatAssistantLookupError(positionalName, result));
       process.exit(1);
     }
+    entry = result.entry;
   } else {
     const hasExplicitUrl =
       flagArgs.includes("--url") || flagArgs.includes("-u");
     const active = getActiveAssistant();
     if (active) {
-      entry = findAssistantByName(active);
+      const result = lookupAssistantByIdentifier(active);
+      if (result.status === "found") {
+        entry = result.entry;
+      }
       if (!entry && !hasExplicitUrl) {
         console.error(
-          `Active assistant '${active}' not found in lockfile. Set an active assistant with 'vellum use <name>'.`,
+          `Active assistant '${active}' not found in lockfile. Set an active assistant with 'vellum use <name-or-id>'.`,
         );
         process.exit(1);
       }
@@ -116,7 +123,7 @@ function parseArgs(): ParsedArgs {
       entry = resolveAssistant();
     } else if (!entry) {
       console.error(
-        "No active assistant set. Set one with 'vellum use <name>' or specify a name: 'vellum client <name>'.",
+        "No active assistant set. Set one with 'vellum use <name-or-id>' or specify one: 'vellum client <name-or-id>'.",
       );
       process.exit(1);
     }
@@ -169,8 +176,6 @@ function parseArgs(): ParsedArgs {
     platformToken,
     bearerToken,
     interfaceId,
-    project: entry?.project,
-    zone: entry?.zone,
   };
 }
 
@@ -217,10 +222,10 @@ function printUsage(): void {
   console.log(`${ANSI.bold}vellum client${ANSI.reset} - Connect to a hatched assistant
 
 ${ANSI.bold}USAGE:${ANSI.reset}
-    vellum client [name] [options]
+    vellum client [name-or-id] [options]
 
 ${ANSI.bold}ARGUMENTS:${ANSI.reset}
-    [name]                     Instance name (default: active)
+    [name-or-id]               Assistant display name or ID (default: active)
 
 ${ANSI.bold}OPTIONS:${ANSI.reset}
     -u, --url <url>            Runtime URL
@@ -343,8 +348,6 @@ export async function client(): Promise<void> {
     platformToken,
     bearerToken,
     interfaceId,
-    project,
-    zone,
   } = parseArgs();
 
   if (interfaceId === WEB_INTERFACE_ID) {
@@ -404,6 +407,6 @@ export async function client(): Promise<void> {
       console.log(`${ANSI.dim}Disconnected.${ANSI.reset}`);
       process.exit(0);
     },
-    { auth, project, zone, assistantName },
+    { auth, assistantName },
   );
 }

package/src/commands/ps.ts

@@ -2,11 +2,16 @@ import { join } from "path";
 
 import {
   findAssistantByName,
+  formatAssistantLookupError,
+  formatAssistantReference,
   getActiveAssistant,
+  getAssistantDisplayName,
   getDaemonPidPath,
   loadAllAssistants,
+  lookupAssistantByIdentifier,
   type AssistantEntry,
 } from "../lib/assistant-config";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import { resolveEnvironmentSource } from "../lib/environments/resolve";
 import { loadGuardianToken } from "../lib/guardian-token";
 import {
@@ -52,8 +57,10 @@ function pad(s: string, w: number): string {
   return s + " ".repeat(Math.max(0, w - s.length));
 }
 
-function computeColWidths(rows: TableRow[]): ColWidths {
-  const headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" };
+function computeColWidths(
+  rows: TableRow[],
+  headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" },
+): ColWidths {
   const all = [headers, ...rows];
   return {
     name: Math.max(...all.map((r) => r.name.length)),
@@ -66,9 +73,11 @@ function formatRow(r: TableRow, colWidths: ColWidths): string {
   return `  ${pad(r.name, colWidths.name)}  ${pad(r.status, colWidths.status)}  ${r.info}`;
 }
 
-function printTable(rows: TableRow[]): void {
-  const colWidths = computeColWidths(rows);
-  const headers: TableRow = { name: "PROCESS", status: "STATUS", info: "INFO" };
+function printTable(
+  rows: TableRow[],
+  headers: TableRow = { name: "PROCESS", status: "STATUS", info: "INFO" },
+): void {
+  const colWidths = computeColWidths(rows, headers);
   console.log(formatRow(headers, colWidths));
   const sep = `  ${"-".repeat(colWidths.name)}  ${"-".repeat(colWidths.status)}  ${"-".repeat(colWidths.info)}`;
   console.log(sep);
@@ -377,7 +386,7 @@ async function getDockerProcesses(entry: AssistantEntry): Promise<TableRow[]> {
 async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   const cloud = resolveCloud(entry);
 
-  console.log(`Processes for ${entry.assistantId} (${cloud}):\n`);
+  console.log(`Processes for ${formatAssistantReference(entry)} (${cloud}):\n`);
 
   if (cloud === "local") {
     const rows = await getLocalProcesses(entry);
@@ -473,6 +482,75 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
 
 // ── List all assistants (no arg) ────────────────────────────────
 
+type AssistantHealth = {
+  status: string;
+  detail: string | null;
+  version?: string;
+};
+
+async function getAssistantListHealth(
+  entry: AssistantEntry,
+): Promise<AssistantHealth> {
+  const resources = entry.resources;
+  if (entry.cloud === "local" && resources) {
+    // TODO(ATL-306): Remove readPidFile/getDaemonPidPath in favor of
+    // fetching daemon PIDs via the health API (Gateway Security Migration).
+    const pid = readPidFile(getDaemonPidPath(resources));
+    const alive = pid !== null && isProcessAlive(pid);
+    if (!alive) {
+      return { status: "sleeping", detail: null };
+    }
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    return checkHealth(entry.localUrl ?? entry.runtimeUrl, token);
+  }
+
+  if (entry.cloud === "docker") {
+    const res = dockerResourceNames(entry.assistantId);
+    const state = await getDockerContainerState(res.assistantContainer);
+    if (!state || state !== "running") {
+      return { status: "sleeping", detail: null };
+    }
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    return checkHealth(entry.localUrl ?? entry.runtimeUrl, token);
+  }
+
+  if (entry.cloud === "apple-container") {
+    // Apple containers are managed by the macOS app. Probe the gateway
+    // (runtimeUrl is always written to the lockfile during hatch).
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    return entry.runtimeUrl
+      ? checkHealth(entry.runtimeUrl, token)
+      : { status: "unknown", detail: "no runtime URL" };
+  }
+
+  if (entry.cloud === "vellum") {
+    return checkManagedHealth(entry.runtimeUrl, entry.assistantId);
+  }
+
+  const token = loadGuardianToken(entry.assistantId)?.accessToken;
+  return checkHealth(entry.localUrl ?? entry.runtimeUrl, token);
+}
+
+function formatAssistantListRow(
+  entry: AssistantEntry,
+  activeAssistantId: string | null,
+  health: AssistantHealth,
+): TableRow {
+  const infoParts: string[] = [];
+  infoParts.push(`id: ${entry.assistantId}`);
+  if (entry.runtimeUrl) infoParts.push(entry.runtimeUrl);
+  if (entry.cloud) infoParts.push(`cloud: ${entry.cloud}`);
+  if (entry.species) infoParts.push(`species: ${entry.species}`);
+  if (health.detail) infoParts.push(health.detail);
+
+  const prefix = entry.assistantId === activeAssistantId ? "* " : "  ";
+  return {
+    name: prefix + getAssistantDisplayName(entry),
+    status: withStatusEmoji(health.status),
+    info: infoParts.join(" | "),
+  };
+}
+
 export async function listAllAssistants(verbose: boolean): Promise<void> {
   const { name: envName, source: envSource } = resolveEnvironmentSource();
   const sourceLabels: Record<typeof envSource, string> = {
@@ -519,6 +597,9 @@ export async function listAllAssistants(verbose: boolean): Promise<void> {
 
   const assistants = loadAllAssistants();
   const activeId = getActiveAssistant();
+  const activeAssistantId = activeId
+    ? (findAssistantByName(activeId)?.assistantId ?? activeId)
+    : null;
 
   if (assistants.length === 0) {
     console.log("No assistants found.");
@@ -540,97 +621,17 @@ export async function listAllAssistants(verbose: boolean): Promise<void> {
     return;
   }
 
-  const rows: TableRow[] = assistants.map((a) => {
-    const infoParts: string[] = [];
-    if (a.runtimeUrl) infoParts.push(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: prefix + a.assistantId,
-      status: withStatusEmoji("checking..."),
-      info: infoParts.join(" | "),
-    };
-  });
-
-  const colWidths = computeColWidths(rows);
-
-  const headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" };
-  console.log(formatRow(headers, colWidths));
-  const sep = `  ${"-".repeat(colWidths.name)}  ${"-".repeat(colWidths.status)}  ${"-".repeat(colWidths.info)}`;
-  console.log(sep);
-  for (const row of rows) {
-    console.log(formatRow(row, colWidths));
-  }
-
-  const totalDataRows = rows.length;
-
-  await Promise.all(
-    assistants.map(async (a, rowIndex) => {
-      // 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; version?: string };
-      const resources = a.resources;
-      if (a.cloud === "local" && resources) {
-        // TODO(ATL-306): Remove readPidFile/getDaemonPidPath in favor of
-        // fetching daemon PIDs via the health API (Gateway Security Migration).
-        const pid = readPidFile(getDaemonPidPath(resources));
-        const alive = pid !== null && isProcessAlive(pid);
-        if (!alive) {
-          health = { status: "sleeping", detail: null };
-        } else {
-          const token = loadGuardianToken(a.assistantId)?.accessToken;
-          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
-        }
-      } else if (a.cloud === "docker") {
-        const res = dockerResourceNames(a.assistantId);
-        const state = await getDockerContainerState(res.assistantContainer);
-        if (!state || state !== "running") {
-          health = { status: "sleeping", detail: null };
-        } else {
-          const token = loadGuardianToken(a.assistantId)?.accessToken;
-          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
-        }
-      } else if (a.cloud === "apple-container") {
-        // Apple containers are managed by the macOS app. Probe the gateway
-        // (runtimeUrl is always written to the lockfile during hatch).
-        const token = loadGuardianToken(a.assistantId)?.accessToken;
-        health = a.runtimeUrl
-          ? await checkHealth(a.runtimeUrl, token)
-          : { status: "unknown" as const, detail: "no runtime URL" };
-      } else if (a.cloud === "vellum") {
-        health = await checkManagedHealth(a.runtimeUrl, a.assistantId);
-      } else {
-        const token = loadGuardianToken(a.assistantId)?.accessToken;
-        health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
-      }
-
-      const infoParts: string[] = [];
-      if (a.runtimeUrl) infoParts.push(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: prefix + a.assistantId,
-        status: withStatusEmoji(health.status),
-        info: infoParts.join(" | "),
-      };
-
-      const linesUp = totalDataRows - rowIndex;
-      process.stdout.write(
-        `\x1b[${linesUp}A` +
-          `\r\x1b[K` +
-          formatRow(updatedRow, colWidths) +
-          `\n` +
-          (linesUp > 1 ? `\x1b[${linesUp - 1}B` : ""),
-      );
-    }),
+  const rows = await Promise.all(
+    assistants.map(async (entry) =>
+      formatAssistantListRow(
+        entry,
+        activeAssistantId,
+        await getAssistantListHealth(entry),
+      ),
+    ),
   );
+
+  printTable(rows, { name: "NAME", status: "STATUS", info: "INFO" });
 }
 
 // ── Entry point ─────────────────────────────────────────────────
@@ -638,14 +639,16 @@ export async function listAllAssistants(verbose: boolean): Promise<void> {
 export async function ps(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum ps [<name>] [--verbose]");
+    console.log("Usage: vellum ps [<name-or-id>] [--verbose]");
     console.log("");
     console.log(
       "List all assistants, or show processes for a specific assistant.",
     );
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>       Show processes for the named assistant");
+    console.log(
+      "  <name-or-id> Show processes for the assistant display name or ID",
+    );
     console.log("");
     console.log("Options:");
     console.log(
@@ -655,19 +658,18 @@ export async function ps(): Promise<void> {
   }
 
   const verbose = args.includes("--verbose");
-  const positional = args.filter((a) => !a.startsWith("--"));
-  const assistantId = positional[0];
+  const assistantIdentifier = parseAssistantTargetArg(args);
 
-  if (!assistantId) {
+  if (!assistantIdentifier) {
     await listAllAssistants(verbose);
     return;
   }
 
-  const entry = findAssistantByName(assistantId);
-  if (!entry) {
-    console.error(`No assistant found with name '${assistantId}'.`);
+  const result = lookupAssistantByIdentifier(assistantIdentifier);
+  if (result.status !== "found") {
+    console.error(formatAssistantLookupError(assistantIdentifier, result));
     process.exit(1);
   }
 
-  await showAssistantProcesses(entry);
+  await showAssistantProcesses(result.entry);
 }

package/src/commands/use.ts

@@ -1,19 +1,24 @@
 import {
-  findAssistantByName,
+  formatAssistantLookupError,
+  formatAssistantReference,
   getActiveAssistant,
+  lookupAssistantByIdentifier,
   setActiveAssistant,
 } from "../lib/assistant-config.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 
 export async function use(): Promise<void> {
   const args = process.argv.slice(3);
 
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum use [<name>]");
+    console.log("Usage: vellum use [<name-or-id>]");
     console.log("");
     console.log("Set the active assistant for commands.");
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>    Name of the assistant to make active");
+    console.log(
+      "  <name-or-id>    Assistant display name or ID to make active",
+    );
     console.log("");
     console.log(
       "When called without a name, prints the current active assistant.",
@@ -21,24 +26,33 @@ export async function use(): Promise<void> {
     process.exit(0);
   }
 
-  const name = args.find((a) => !a.startsWith("-"));
+  const name = parseAssistantTargetArg(args);
 
   if (!name) {
     const active = getActiveAssistant();
     if (active) {
-      console.log(`Active assistant: ${active}`);
+      const result = lookupAssistantByIdentifier(active);
+      if (result.status === "found") {
+        console.log(
+          `Active assistant: ${formatAssistantReference(result.entry)}`,
+        );
+      } else {
+        console.log(`Active assistant: ${active} (not found in lockfile)`);
+      }
     } else {
       console.log("No active assistant set.");
     }
     return;
   }
 
-  const entry = findAssistantByName(name);
-  if (!entry) {
-    console.error(`No assistant found with name '${name}'.`);
+  const result = lookupAssistantByIdentifier(name);
+  if (result.status !== "found") {
+    console.error(formatAssistantLookupError(name, result));
     process.exit(1);
   }
 
-  setActiveAssistant(name);
-  console.log(`Active assistant set to '${name}'.`);
+  setActiveAssistant(result.entry.assistantId);
+  console.log(
+    `Active assistant set to ${formatAssistantReference(result.entry)}.`,
+  );
 }