@vellumai/cli 0.4.29 → 0.4.30

package/package.json

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

package/src/commands/contacts.ts

@@ -136,7 +136,7 @@ function printUsage(): void {
   console.log("Usage: vellum contacts <subcommand> [options]");
   console.log("");
   console.log("Subcommands:");
-  console.log("  list [--limit N]               List all contacts");
+  console.log("  list [--limit N] [--role ROLE]  List all contacts");
   console.log("  get <id>                       Get a contact by ID");
   console.log("  merge <keepId> <mergeId>       Merge two contacts");
   console.log("");
@@ -161,7 +161,9 @@ export async function contacts(): Promise<void> {
   switch (subcommand) {
     case "list": {
       const limit = getFlagValue(args, "--limit") ?? "50";
-      const data = (await apiGet(`contacts?limit=${limit}`)) as {
+      const role = getFlagValue(args, "--role");
+      const query = `contacts?limit=${limit}${role ? `&role=${encodeURIComponent(role)}` : ""}`;
+      const data = (await apiGet(query)) as {
         ok: boolean;
         contacts: Contact[];
       };

package/src/commands/retire.ts

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { renameSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { basename, dirname, join } from "path";
 
@@ -40,10 +40,14 @@ function extractHostFromUrl(url: string): string {
   }
 }
 
+function getBaseDir(): string {
+  return process.env.BASE_DATA_DIR?.trim() || homedir();
+}
+
 async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
   console.log("\u{1F5D1}\ufe0f  Stopping local assistant...\n");
 
-  const vellumDir = join(homedir(), ".vellum");
+  const vellumDir = join(getBaseDir(), ".vellum");
 
   // Stop daemon via PID file
   const daemonPidFile = join(vellumDir, "vellum.pid");
@@ -66,12 +70,21 @@ async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
     await stopOrphanedDaemonProcesses();
   }
 
-  // Move ~/.vellum out of the way so the path is immediately available for the
-  // next hatch, then kick off the tar archive in the background.
+  // Move the data directory out of the way so the path is immediately available
+  // for the next hatch, then kick off the tar archive in the background.
   const archivePath = getArchivePath(name);
   const metadataPath = getMetadataPath(name);
   const stagingDir = `${archivePath}.staging`;
 
+  if (!existsSync(vellumDir)) {
+    console.log(`   No data directory at ${vellumDir} — nothing to archive.`);
+    console.log("\u2705 Local instance retired.");
+    return;
+  }
+
+  // Ensure the retired archive directory exists before attempting the rename
+  mkdirSync(dirname(stagingDir), { recursive: true });
+
   try {
     renameSync(vellumDir, stagingDir);
   } catch (err) {

package/src/commands/skills.ts

@@ -0,0 +1,389 @@
+import { execSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+function getRootDir(): string {
+  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
+}
+
+function getSkillsDir(): string {
+  return join(getRootDir(), "workspace", "skills");
+}
+
+function getSkillsIndexPath(): string {
+  return join(getSkillsDir(), "SKILLS.md");
+}
+
+// ---------------------------------------------------------------------------
+// Platform API client
+// ---------------------------------------------------------------------------
+
+function getConfigPlatformUrl(): string | undefined {
+  try {
+    const configPath = join(getRootDir(), "workspace", "config.json");
+    if (!existsSync(configPath)) return undefined;
+    const raw = JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+    const platform = raw.platform as Record<string, unknown> | undefined;
+    const baseUrl = platform?.baseUrl;
+    if (typeof baseUrl === "string" && baseUrl.trim()) return baseUrl.trim();
+  } catch {
+    // ignore
+  }
+  return undefined;
+}
+
+function getPlatformUrl(): string {
+  return (
+    process.env.VELLUM_ASSISTANT_PLATFORM_URL ??
+    getConfigPlatformUrl() ??
+    "https://platform.vellum.ai"
+  );
+}
+
+function getPlatformToken(): string | null {
+  try {
+    return readFileSync(join(getRootDir(), "platform-token"), "utf-8").trim();
+  } catch {
+    return null;
+  }
+}
+
+function buildHeaders(): Record<string, string> {
+  const headers: Record<string, string> = {};
+  const token = getPlatformToken();
+  if (token) {
+    headers["X-Session-Token"] = token;
+  }
+  return headers;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface CatalogSkill {
+  id: string;
+  name: string;
+  description: string;
+  emoji?: string;
+  includes?: string[];
+  version?: string;
+}
+
+interface CatalogManifest {
+  version: number;
+  skills: CatalogSkill[];
+}
+
+// ---------------------------------------------------------------------------
+// Catalog operations
+// ---------------------------------------------------------------------------
+
+async function fetchCatalog(): Promise<CatalogSkill[]> {
+  const url = `${getPlatformUrl()}/v1/skills/`;
+  const response = await fetch(url, {
+    headers: buildHeaders(),
+    signal: AbortSignal.timeout(10000),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Platform API error ${response.status}: ${response.statusText}`,
+    );
+  }
+
+  const manifest = (await response.json()) as CatalogManifest;
+  if (!Array.isArray(manifest.skills)) {
+    throw new Error("Platform catalog has invalid skills array");
+  }
+  return manifest.skills;
+}
+
+/**
+ * Extract all files from a tar archive (uncompressed) into a directory.
+ * Returns true if a SKILL.md was found in the archive.
+ */
+function extractTarToDir(tarBuffer: Buffer, destDir: string): boolean {
+  let foundSkillMd = false;
+  let offset = 0;
+  while (offset + 512 <= tarBuffer.length) {
+    const header = tarBuffer.subarray(offset, offset + 512);
+
+    // End-of-archive (two consecutive zero blocks)
+    if (header.every((b) => b === 0)) break;
+
+    // Filename (bytes 0-99, null-terminated)
+    const nameEnd = header.indexOf(0, 0);
+    const name = header
+      .subarray(0, Math.min(nameEnd >= 0 ? nameEnd : 100, 100))
+      .toString("utf-8");
+
+    // File type (byte 156): '5' = directory, '0' or '\0' = regular file
+    const typeFlag = header[156];
+
+    // File size (bytes 124-135, octal)
+    const sizeStr = header.subarray(124, 136).toString("utf-8").trim();
+    const size = parseInt(sizeStr, 8) || 0;
+
+    offset += 512; // past header
+
+    // Skip directories and empty names
+    if (name && typeFlag !== 53 /* '5' */) {
+      // Prevent path traversal
+      const normalizedName = name.replace(/^\.\//, "");
+      if (!normalizedName.startsWith("..") && !normalizedName.includes("/..")) {
+        const destPath = join(destDir, normalizedName);
+        mkdirSync(dirname(destPath), { recursive: true });
+        writeFileSync(destPath, tarBuffer.subarray(offset, offset + size));
+
+        if (
+          normalizedName === "SKILL.md" ||
+          normalizedName.endsWith("/SKILL.md")
+        ) {
+          foundSkillMd = true;
+        }
+      }
+    }
+
+    // Skip to next header (data padded to 512 bytes)
+    offset += Math.ceil(size / 512) * 512;
+  }
+  return foundSkillMd;
+}
+
+async function fetchAndExtractSkill(
+  skillId: string,
+  destDir: string,
+): Promise<void> {
+  const url = `${getPlatformUrl()}/v1/skills/${encodeURIComponent(skillId)}/`;
+  const response = await fetch(url, {
+    headers: buildHeaders(),
+    signal: AbortSignal.timeout(15000),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch skill "${skillId}": HTTP ${response.status}`,
+    );
+  }
+
+  const gzipBuffer = Buffer.from(await response.arrayBuffer());
+  const tarBuffer = gunzipSync(gzipBuffer);
+  const foundSkillMd = extractTarToDir(tarBuffer, destDir);
+
+  if (!foundSkillMd) {
+    throw new Error(`SKILL.md not found in archive for "${skillId}"`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Managed skill installation
+// ---------------------------------------------------------------------------
+
+function atomicWriteFile(filePath: string, content: string): void {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmpPath = join(dir, `.tmp-${randomUUID()}`);
+  writeFileSync(tmpPath, content, "utf-8");
+  renameSync(tmpPath, filePath);
+}
+
+function upsertSkillsIndex(id: string): void {
+  const indexPath = getSkillsIndexPath();
+  let lines: string[] = [];
+  if (existsSync(indexPath)) {
+    lines = readFileSync(indexPath, "utf-8").split("\n");
+  }
+
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^[-*]\\s+(?:\`)?${escaped}(?:\`)?\\s*$`);
+  if (lines.some((line) => pattern.test(line))) return;
+
+  const nonEmpty = lines.filter((l) => l.trim());
+  nonEmpty.push(`- ${id}`);
+  const content = nonEmpty.join("\n");
+  atomicWriteFile(indexPath, content.endsWith("\n") ? content : content + "\n");
+}
+
+async function installSkillLocally(
+  skillId: string,
+  catalogEntry: CatalogSkill,
+  overwrite: boolean,
+): Promise<void> {
+  const skillDir = join(getSkillsDir(), skillId);
+  const skillFilePath = join(skillDir, "SKILL.md");
+
+  if (existsSync(skillFilePath) && !overwrite) {
+    throw new Error(
+      `Skill "${skillId}" is already installed. Use --overwrite to replace it.`,
+    );
+  }
+
+  mkdirSync(skillDir, { recursive: true });
+
+  // Extract all files from the archive into the skill directory
+  await fetchAndExtractSkill(skillId, skillDir);
+
+  // Write version metadata
+  if (catalogEntry.version) {
+    const meta = {
+      version: catalogEntry.version,
+      installedAt: new Date().toISOString(),
+    };
+    atomicWriteFile(
+      join(skillDir, "version.json"),
+      JSON.stringify(meta, null, 2) + "\n",
+    );
+  }
+
+  // Install npm dependencies if the skill has a package.json
+  if (existsSync(join(skillDir, "package.json"))) {
+    const bunPath = `${process.env.HOME || "/root"}/.bun/bin`;
+    execSync("bun install", {
+      cwd: skillDir,
+      stdio: "inherit",
+      env: { ...process.env, PATH: `${bunPath}:${process.env.PATH}` },
+    });
+  }
+
+  // Register in SKILLS.md only after all steps succeed
+  upsertSkillsIndex(skillId);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+
+function printUsage(): void {
+  console.log("Usage: vellum skills <subcommand> [options]");
+  console.log("");
+  console.log("Subcommands:");
+  console.log(
+    "  list                             List available catalog skills",
+  );
+  console.log(
+    "  install <skill-id> [--overwrite]  Install a skill from the catalog",
+  );
+  console.log("");
+  console.log("Options:");
+  console.log("  --json    Machine-readable JSON output");
+}
+
+// ---------------------------------------------------------------------------
+// Command entry point
+// ---------------------------------------------------------------------------
+
+export async function skills(): Promise<void> {
+  const args = process.argv.slice(3);
+  const subcommand = args[0];
+  const json = hasFlag(args, "--json");
+
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    printUsage();
+    return;
+  }
+
+  switch (subcommand) {
+    case "list": {
+      try {
+        const catalog = await fetchCatalog();
+
+        if (json) {
+          console.log(JSON.stringify({ ok: true, skills: catalog }));
+          return;
+        }
+
+        if (catalog.length === 0) {
+          console.log("No skills available in the catalog.");
+          return;
+        }
+
+        console.log(`Available skills (${catalog.length}):\n`);
+        for (const s of catalog) {
+          const emoji = s.emoji ? `${s.emoji} ` : "";
+          const deps = s.includes?.length
+            ? ` (requires: ${s.includes.join(", ")})`
+            : "";
+          console.log(`  ${emoji}${s.id}`);
+          console.log(`    ${s.name} — ${s.description}${deps}`);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (json) {
+          console.log(JSON.stringify({ ok: false, error: msg }));
+        } else {
+          console.error(`Error: ${msg}`);
+        }
+        process.exitCode = 1;
+      }
+      break;
+    }
+
+    case "install": {
+      const skillId = args.find((a) => !a.startsWith("--") && a !== "install");
+      if (!skillId) {
+        console.error("Usage: vellum skills install <skill-id>");
+        process.exit(1);
+      }
+
+      const overwrite = hasFlag(args, "--overwrite");
+
+      try {
+        // Verify skill exists in catalog
+        const catalog = await fetchCatalog();
+        const entry = catalog.find((s) => s.id === skillId);
+        if (!entry) {
+          throw new Error(`Skill "${skillId}" not found in the Vellum catalog`);
+        }
+
+        // Fetch, extract, and install
+        await installSkillLocally(skillId, entry, overwrite);
+
+        if (json) {
+          console.log(JSON.stringify({ ok: true, skillId }));
+        } else {
+          console.log(`Installed skill "${skillId}".`);
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (json) {
+          console.log(JSON.stringify({ ok: false, error: msg }));
+        } else {
+          console.error(`Error: ${msg}`);
+        }
+        process.exitCode = 1;
+      }
+      break;
+    }
+
+    default: {
+      console.error(`Unknown skills subcommand: ${subcommand}`);
+      printUsage();
+      process.exit(1);
+    }
+  }
+}

package/src/commands/wake.ts

@@ -3,7 +3,7 @@ import { homedir } from "os";
 import { join } from "path";
 
 import { loadAllAssistants } from "../lib/assistant-config";
-import { isProcessAlive } from "../lib/process";
+import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 import {
   startLocalDaemon,
   startGateway,
@@ -13,12 +13,19 @@ import {
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum wake");
+    console.log("Usage: vellum wake [options]");
     console.log("");
     console.log("Start the assistant and gateway processes.");
+    console.log("");
+    console.log("Options:");
+    console.log(
+      "  --watch    Run assistant and gateway in watch mode (hot reload on source changes)",
+    );
     process.exit(0);
   }
 
+  const watch = args.includes("--watch");
+
   const assistants = loadAllAssistants();
   const hasLocal = assistants.some((a) => a.cloud === "local");
   if (!hasLocal) {
@@ -30,6 +37,7 @@ export async function wake(): Promise<void> {
 
   const vellumDir = join(homedir(), ".vellum");
   const pidFile = join(vellumDir, "vellum.pid");
+  const socketFile = join(vellumDir, "vellum.sock");
 
   // Check if daemon is already running
   let daemonRunning = false;
@@ -40,7 +48,16 @@ export async function wake(): Promise<void> {
       try {
         process.kill(pid, 0);
         daemonRunning = true;
-        console.log(`Assistant already running (pid ${pid}).`);
+        if (watch) {
+          // Restart in watch mode
+          console.log(
+            `Assistant running (pid ${pid}) — restarting in watch mode...`,
+          );
+          await stopProcessByPidFile(pidFile, "assistant", [socketFile]);
+          daemonRunning = false;
+        } else {
+          console.log(`Assistant already running (pid ${pid}).`);
+        }
       } catch {
         // Process not alive, will start below
       }
@@ -48,7 +65,7 @@ export async function wake(): Promise<void> {
   }
 
   if (!daemonRunning) {
-    await startLocalDaemon();
+    await startLocalDaemon(watch);
   }
 
   // Start gateway (non-desktop only)
@@ -56,14 +73,32 @@ export async function wake(): Promise<void> {
     const gatewayPidFile = join(vellumDir, "gateway.pid");
     const { alive, pid } = isProcessAlive(gatewayPidFile);
     if (alive) {
-      console.log(`Gateway already running (pid ${pid}).`);
+      if (watch) {
+        // Restart in watch mode
+        console.log(
+          `Gateway running (pid ${pid}) — restarting in watch mode...`,
+        );
+        await stopProcessByPidFile(gatewayPidFile, "gateway");
+        await startGateway(undefined, watch);
+      } else {
+        console.log(`Gateway already running (pid ${pid}).`);
+      }
     } else {
-      await startGateway();
+      await startGateway(undefined, watch);
     }
   }
 
   // Start outbound proxy
-  await startOutboundProxy();
+  const outboundProxyPidFile = join(vellumDir, "outbound-proxy.pid");
+  const outboundProxyStatus = isProcessAlive(outboundProxyPidFile);
+  if (outboundProxyStatus.alive && watch) {
+    // Restart in watch mode
+    console.log(
+      `Outbound proxy running (pid ${outboundProxyStatus.pid}) — restarting in watch mode...`,
+    );
+    await stopProcessByPidFile(outboundProxyPidFile, "outbound-proxy");
+  }
+  await startOutboundProxy(watch);
 
   console.log("✅ Wake complete.");
 }

package/src/index.ts

@@ -18,6 +18,7 @@ import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
 import { retire } from "./commands/retire";
+import { skills } from "./commands/skills";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
 import { tunnel } from "./commands/tunnel";
@@ -36,6 +37,7 @@ const commands = {
   ps,
   recover,
   retire,
+  skills,
   sleep,
   ssh,
   tunnel,
@@ -97,6 +99,7 @@ async function main() {
     );
     console.log("  recover  Restore a previously retired local assistant");
     console.log("  retire   Delete an assistant instance");
+    console.log("  skills   Browse and install skills from the Vellum catalog");
     console.log("  sleep    Stop the assistant process");
     console.log("  ssh      SSH into a remote assistant instance");
     console.log("  tunnel   Create a tunnel for a locally hosted assistant");