@vellumai/cli 0.4.26 → 0.4.30

package/src/commands/retire.ts

@@ -1,13 +1,19 @@
 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";
 
-import { findAssistantByName, removeAssistantEntry } from "../lib/assistant-config";
+import {
+  findAssistantByName,
+  removeAssistantEntry,
+} from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import { retireInstance as retireAwsInstance } from "../lib/aws";
 import { retireInstance as retireGcpInstance } from "../lib/gcp";
-import { stopOrphanedDaemonProcesses, stopProcessByPidFile } from "../lib/process";
+import {
+  stopOrphanedDaemonProcesses,
+  stopProcessByPidFile,
+} from "../lib/process";
 import { getArchivePath, getMetadataPath } from "../lib/retire-archive";
 import { exec } from "../lib/step-runner";
 import { openLogFile, closeLogFile, writeToLogFile } from "../lib/xdg-log";
@@ -34,36 +40,57 @@ 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 daemon...\n");
+  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");
   const socketFile = join(vellumDir, "vellum.sock");
-  const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon", [socketFile]);
+  const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon", [
+    socketFile,
+  ]);
 
   // Stop gateway via PID file
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway");
 
+  // Stop outbound proxy via PID file
+  const outboundProxyPidFile = join(vellumDir, "outbound-proxy.pid");
+  await stopProcessByPidFile(outboundProxyPidFile, "outbound-proxy");
+
   // If the PID file didn't track a running daemon, scan for orphaned
   // daemon processes that may have been started without writing a PID.
   if (!daemonStopped) {
     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) {
-    console.warn(`⚠️  Failed to move ${vellumDir}: ${err instanceof Error ? err.message : err}`);
+    console.warn(
+      `⚠️  Failed to move ${vellumDir}: ${err instanceof Error ? err.message : err}`,
+    );
     console.warn("Skipping archive.");
     console.log("\u2705 Local instance retired.");
     return;
@@ -96,17 +123,21 @@ async function retireCustom(entry: AssistantEntry): Promise<void> {
   console.log(`\u{1F5D1}\ufe0f  Retiring custom instance on ${sshHost}...\n`);
 
   const remoteCmd = [
-    "bunx vellum daemon stop 2>/dev/null || true",
+    "bunx vellum sleep 2>/dev/null || true",
     "pkill -f gateway 2>/dev/null || true",
     "rm -rf ~/.vellum",
   ].join(" && ");
 
   try {
     await exec("ssh", [
-      "-o", "StrictHostKeyChecking=no",
-      "-o", "UserKnownHostsFile=/dev/null",
-      "-o", "ConnectTimeout=10",
-      "-o", "LogLevel=ERROR",
+      "-o",
+      "StrictHostKeyChecking=no",
+      "-o",
+      "UserKnownHostsFile=/dev/null",
+      "-o",
+      "ConnectTimeout=10",
+      "-o",
+      "LogLevel=ERROR",
       sshHost,
       remoteCmd,
     ]);
@@ -145,16 +176,24 @@ function teeConsoleToLogFile(fd: number | "ignore"): void {
   };
   console.warn = (...args: unknown[]) => {
     origWarn(...args);
-    writeToLogFile(fd, `[${timestamp()}] WARN: ${args.map(String).join(" ")}\n`);
+    writeToLogFile(
+      fd,
+      `[${timestamp()}] WARN: ${args.map(String).join(" ")}\n`,
+    );
   };
   console.error = (...args: unknown[]) => {
     origError(...args);
-    writeToLogFile(fd, `[${timestamp()}] ERROR: ${args.map(String).join(" ")}\n`);
+    writeToLogFile(
+      fd,
+      `[${timestamp()}] ERROR: ${args.map(String).join(" ")}\n`,
+    );
   };
 }
 
 export async function retire(): Promise<void> {
-  const logFd = process.env.VELLUM_DESKTOP_APP ? openLogFile("retire.log") : "ignore";
+  const logFd = process.env.VELLUM_DESKTOP_APP
+    ? openLogFile("retire.log")
+    : "ignore";
   teeConsoleToLogFile(logFd);
 
   try {
@@ -201,7 +240,9 @@ async function retireInner(): Promise<void> {
     const project = entry.project;
     const zone = entry.zone;
     if (!project || !zone) {
-      console.error("Error: GCP project and zone not found in assistant config.");
+      console.error(
+        "Error: GCP project and zone not found in assistant config.",
+      );
       process.exit(1);
     }
     await retireGcpInstance(name, project, zone, source);

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/sleep.ts

@@ -8,7 +8,7 @@ export async function sleep(): Promise<void> {
   if (args.includes("--help") || args.includes("-h")) {
     console.log("Usage: vellum sleep");
     console.log("");
-    console.log("Stop the daemon and gateway processes.");
+    console.log("Stop the assistant, gateway, and outbound-proxy processes.");
     process.exit(0);
   }
 
@@ -16,15 +16,16 @@ export async function sleep(): Promise<void> {
   const daemonPidFile = join(vellumDir, "vellum.pid");
   const socketFile = join(vellumDir, "vellum.sock");
   const gatewayPidFile = join(vellumDir, "gateway.pid");
+  const outboundProxyPidFile = join(vellumDir, "outbound-proxy.pid");
 
   // Stop daemon
   const daemonStopped = await stopProcessByPidFile(daemonPidFile, "daemon", [
     socketFile,
   ]);
   if (!daemonStopped) {
-    console.log("Daemon is not running.");
+    console.log("Assistant is not running.");
   } else {
-    console.log("Daemon stopped.");
+    console.log("Assistant stopped.");
   }
 
   // Stop gateway
@@ -34,4 +35,15 @@ export async function sleep(): Promise<void> {
   } else {
     console.log("Gateway stopped.");
   }
+
+  // Stop outbound proxy
+  const outboundProxyStopped = await stopProcessByPidFile(
+    outboundProxyPidFile,
+    "outbound-proxy",
+  );
+  if (!outboundProxyStopped) {
+    console.log("Outbound proxy is not running.");
+  } else {
+    console.log("Outbound proxy stopped.");
+  }
 }

package/src/commands/ssh.ts

@@ -1,13 +1,20 @@
 import { spawn } from "child_process";
 
-import { findAssistantByName, loadLatestAssistant } from "../lib/assistant-config";
+import {
+  findAssistantByName,
+  loadLatestAssistant,
+} from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 
 const SSH_OPTS = [
-  "-o", "StrictHostKeyChecking=no",
-  "-o", "UserKnownHostsFile=/dev/null",
-  "-o", "ConnectTimeout=10",
-  "-o", "LogLevel=ERROR",
+  "-o",
+  "StrictHostKeyChecking=no",
+  "-o",
+  "UserKnownHostsFile=/dev/null",
+  "-o",
+  "ConnectTimeout=10",
+  "-o",
+  "LogLevel=ERROR",
 ];
 
 function resolveCloud(entry: AssistantEntry): string {
@@ -40,7 +47,9 @@ export async function ssh(): Promise<void> {
     console.log("SSH into a remote assistant instance.");
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>    Name of the assistant to connect to (defaults to latest)");
+    console.log(
+      "  <name>    Name of the assistant to connect to (defaults to latest)",
+    );
     process.exit(0);
   }
 
@@ -61,7 +70,7 @@ export async function ssh(): Promise<void> {
   if (cloud === "local") {
     console.error(
       "Cannot SSH into a local assistant. Local assistants run directly on this machine.\n" +
-      `Use 'vellum ps ${entry.assistantId}' to check its processes instead.`,
+        `Use 'vellum ps ${entry.assistantId}' to check its processes instead.`,
     );
     process.exit(1);
   }
@@ -77,7 +86,9 @@ export async function ssh(): Promise<void> {
     const project = entry.project;
     const zone = entry.zone;
     if (!project || !zone) {
-      console.error("Error: GCP project and zone not found in assistant config.");
+      console.error(
+        "Error: GCP project and zone not found in assistant config.",
+      );
       process.exit(1);
     }
 
@@ -102,11 +113,7 @@ export async function ssh(): Promise<void> {
 
     console.log(`🔗 Connecting to ${entry.assistantId} via ssh...\n`);
 
-    child = spawn(
-      "ssh",
-      [...SSH_OPTS, sshTarget],
-      { stdio: "inherit" },
-    );
+    child = spawn("ssh", [...SSH_OPTS, sshTarget], { stdio: "inherit" });
   } else {
     console.error(`Error: Unknown cloud type '${cloud}'.`);
     process.exit(1);

package/src/commands/tunnel.ts

@@ -1,4 +1,7 @@
-import { findAssistantByName, loadLatestAssistant } from "../lib/assistant-config";
+import {
+  findAssistantByName,
+  loadLatestAssistant,
+} from "../lib/assistant-config";
 import { runNgrokTunnel } from "../lib/ngrok";
 
 const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
@@ -70,9 +73,7 @@ export async function tunnel(): Promise<void> {
         `No assistant instance found with name '${assistantName}'.`,
       );
     } else {
-      console.error(
-        "No assistant instance found. Run `vellum hatch` first.",
-      );
+      console.error("No assistant instance found. Run `vellum hatch` first.");
     }
     process.exit(1);
   }
@@ -82,7 +83,5 @@ export async function tunnel(): Promise<void> {
     return;
   }
 
-  throw new Error(
-    `Tunnel provider '${provider}' is not yet implemented.`,
-  );
+  throw new Error(`Tunnel provider '${provider}' is not yet implemented.`);
 }