@vellumai/cli 0.3.5 → 0.3.7

package/package.json

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

package/src/commands/config.ts

@@ -0,0 +1,244 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+interface AllowlistConfig {
+  values?: string[];
+  prefixes?: string[];
+  patterns?: string[];
+}
+
+interface AllowlistValidationError {
+  index: number;
+  pattern: string;
+  message: string;
+}
+
+function getRootDir(): string {
+  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
+}
+
+function getConfigPath(): string {
+  return join(getRootDir(), "workspace", "config.json");
+}
+
+function getAllowlistPath(): string {
+  return join(getRootDir(), "protected", "secret-allowlist.json");
+}
+
+function loadRawConfig(): Record<string, unknown> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  const raw = readFileSync(configPath, "utf-8");
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+function saveRawConfig(config: Record<string, unknown>): void {
+  const configPath = getConfigPath();
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+function getNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+): unknown {
+  const keys = path.split(".");
+  let current: unknown = obj;
+  for (const key of keys) {
+    if (
+      current === null ||
+      current === undefined ||
+      typeof current !== "object"
+    ) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+function setNestedValue(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const keys = path.split(".");
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (
+      current[key] === undefined ||
+      current[key] === null ||
+      typeof current[key] !== "object"
+    ) {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  current[keys[keys.length - 1]] = value;
+}
+
+function validateAllowlist(
+  allowlistConfig: AllowlistConfig,
+): AllowlistValidationError[] {
+  const errors: AllowlistValidationError[] = [];
+  if (!allowlistConfig.patterns) return errors;
+  if (!Array.isArray(allowlistConfig.patterns)) {
+    errors.push({
+      index: -1,
+      pattern: String(allowlistConfig.patterns),
+      message: '"patterns" must be an array',
+    });
+    return errors;
+  }
+
+  for (let i = 0; i < allowlistConfig.patterns.length; i++) {
+    const p = allowlistConfig.patterns[i];
+    if (typeof p !== "string") {
+      errors.push({
+        index: i,
+        pattern: String(p),
+        message: "Pattern is not a string",
+      });
+      continue;
+    }
+    try {
+      new RegExp(p);
+    } catch (err) {
+      errors.push({
+        index: i,
+        pattern: p,
+        message: (err as Error).message,
+      });
+    }
+  }
+  return errors;
+}
+
+function validateAllowlistFile(): AllowlistValidationError[] | null {
+  const filePath = getAllowlistPath();
+  if (!existsSync(filePath)) return null;
+
+  const raw = readFileSync(filePath, "utf-8");
+  const allowlistConfig: AllowlistConfig = JSON.parse(
+    raw,
+  ) as AllowlistConfig;
+  return validateAllowlist(allowlistConfig);
+}
+
+function printUsage(): void {
+  console.log("Usage: vellum config <subcommand> [options]");
+  console.log("");
+  console.log("Subcommands:");
+  console.log(
+    "  get <key>              Get a config value (supports dotted paths)",
+  );
+  console.log(
+    "  set <key> <value>      Set a config value (supports dotted paths like apiKeys.anthropic)",
+  );
+  console.log(
+    "  list                   List all config values",
+  );
+  console.log(
+    "  validate-allowlist     Validate regex patterns in secret-allowlist.json",
+  );
+}
+
+export function config(): void {
+  const args = process.argv.slice(3);
+  const subcommand = args[0];
+
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    printUsage();
+    return;
+  }
+
+  switch (subcommand) {
+    case "set": {
+      const key = args[1];
+      const value = args[2];
+      if (!key || value === undefined) {
+        console.error("Usage: vellum config set <key> <value>");
+        process.exit(1);
+      }
+      const raw = loadRawConfig();
+      let parsed: unknown = value;
+      try {
+        parsed = JSON.parse(value);
+      } catch {
+        // keep as string
+      }
+      setNestedValue(raw, key, parsed);
+      saveRawConfig(raw);
+      console.log(`Set ${key} = ${JSON.stringify(parsed)}`);
+      break;
+    }
+
+    case "get": {
+      const key = args[1];
+      if (!key) {
+        console.error("Usage: vellum config get <key>");
+        process.exit(1);
+      }
+      const raw = loadRawConfig();
+      const val = getNestedValue(raw, key);
+      if (val === undefined) {
+        console.log("(not set)");
+      } else {
+        console.log(
+          typeof val === "object" ? JSON.stringify(val, null, 2) : String(val),
+        );
+      }
+      break;
+    }
+
+    case "list": {
+      const raw = loadRawConfig();
+      if (Object.keys(raw).length === 0) {
+        console.log("No configuration set");
+      } else {
+        console.log(JSON.stringify(raw, null, 2));
+      }
+      break;
+    }
+
+    case "validate-allowlist": {
+      try {
+        const errors = validateAllowlistFile();
+        if (errors === null) {
+          console.log("No secret-allowlist.json file found");
+          return;
+        }
+        if (errors.length === 0) {
+          console.log("All patterns in secret-allowlist.json are valid");
+          return;
+        }
+        console.error(
+          `Found ${errors.length} invalid pattern(s) in secret-allowlist.json:`,
+        );
+        for (const e of errors) {
+          console.error(`  [${e.index}] "${e.pattern}": ${e.message}`);
+        }
+        process.exit(1);
+      } catch (err) {
+        console.error(
+          `Failed to read secret-allowlist.json: ${(err as Error).message}`,
+        );
+        process.exit(1);
+      }
+      break;
+    }
+
+    default: {
+      console.error(`Unknown config subcommand: ${subcommand}`);
+      printUsage();
+      process.exit(1);
+    }
+  }
+}

package/src/commands/email.ts

@@ -7,6 +7,7 @@
  */
 
 import { VellumEmailClient } from "../email/vellum.js";
+import { loadLatestAssistant } from "../lib/assistant-config.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -33,6 +34,7 @@ Subcommands:
   create <username>     Create a new email inbox for the given username
 
 Options:
+  --assistant <id>      Assistant ID (defaults to the most recently hatched)
   --help, -h            Show this help message
 `);
 }
@@ -49,18 +51,36 @@ export async function email(): Promise<void> {
     return;
   }
 
+  // Resolve assistant ID from --assistant flag or latest assistant
+  const assistantFlagIdx = args.indexOf("--assistant");
+  let assistantId: string | undefined;
+  if (assistantFlagIdx !== -1) {
+    const value = args[assistantFlagIdx + 1];
+    if (!value || value.startsWith("-")) {
+      exitError("--assistant requires a value.");
+      return;
+    }
+    assistantId = value;
+    args.splice(assistantFlagIdx, 2);
+  }
+  if (!assistantId) {
+    assistantId = loadLatestAssistant()?.assistantId;
+  }
+  if (!assistantId) {
+    exitError(
+      "No assistant ID available. Pass --assistant <id> or hatch an assistant first.",
+    );
+    return;
+  }
+
   const subcommand = args[0];
 
   switch (subcommand) {
     case "status": {
       try {
-        const client = new VellumEmailClient();
-        const status = await client.status();
-        output({
-          ok: true,
-          provider: status.provider,
-          inboxes: status.inboxes,
-        });
+        const client = new VellumEmailClient(assistantId);
+        const addresses = await client.status();
+        output({ ok: true, addresses });
       } catch (err) {
         exitError(err instanceof Error ? err.message : String(err));
       }
@@ -73,7 +93,7 @@ export async function email(): Promise<void> {
         return;
       }
       try {
-        const client = new VellumEmailClient();
+        const client = new VellumEmailClient(assistantId);
         const inbox = await client.createInbox(username);
         output({ ok: true, inbox });
       } catch (err) {

package/src/commands/hatch.ts

@@ -22,6 +22,7 @@ import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import { startLocalDaemon, startGateway, stopLocalProcesses } from "../lib/local";
 import { isProcessAlive } from "../lib/process";
 import { generateRandomSuffix } from "../lib/random-name";
+import { validateAssistantName } from "../lib/retire-archive";
 import { exec } from "../lib/step-runner";
 
 export type { PollResult, WatchHatchingResult } from "../lib/gcp";
@@ -169,6 +170,12 @@ function parseArgs(): HatchArgs {
         console.error("Error: --name requires a value");
         process.exit(1);
       }
+      try {
+        validateAssistantName(next);
+      } catch {
+        console.error(`Error: --name contains invalid characters (path separators or traversal segments are not allowed)`);
+        process.exit(1);
+      }
       name = next;
       i++;
     } else if (arg === "--remote") {

package/src/commands/ps.ts

@@ -245,6 +245,57 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   printTable(rows);
 }
 
+// ── Orphaned process detection ──────────────────────────────────
+
+interface OrphanedProcess {
+  name: string;
+  pid: string;
+  source: string;
+}
+
+async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
+  const results: OrphanedProcess[] = [];
+  const seenPids = new Set<string>();
+  const vellumDir = join(homedir(), ".vellum");
+
+  // Strategy 1: PID file scan
+  const pidFiles: Array<{ file: string; name: string }> = [
+    { file: join(vellumDir, "vellum.pid"), name: "daemon" },
+    { file: join(vellumDir, "gateway.pid"), name: "gateway" },
+    { file: join(vellumDir, "qdrant.pid"), name: "qdrant" },
+  ];
+
+  for (const { file, name } of pidFiles) {
+    const result = checkPidFile(file);
+    if (result.status === "running" && result.pid) {
+      results.push({ name, pid: result.pid, source: "pid file" });
+      seenPids.add(result.pid);
+    }
+  }
+
+  // Strategy 2: Process table scan
+  try {
+    const output = await execOutput("sh", [
+      "-c",
+      "ps ax -o pid=,ppid=,args= | grep -E 'vellum|gateway|qdrant|openclaw' | grep -v grep",
+    ]);
+    const procs = parseRemotePs(output);
+    const ownPid = String(process.pid);
+
+    for (const p of procs) {
+      if (p.pid === ownPid || seenPids.has(p.pid)) continue;
+      const type = classifyProcess(p.command);
+      if (type === "unknown") continue;
+      results.push({ name: type, pid: p.pid, source: "process table" });
+      seenPids.add(p.pid);
+    }
+  } catch {
+    // grep exits 1 when no matches found — ignore
+  }
+
+  return results;
+}
+
 // ── List all assistants (no arg) ────────────────────────────────
 
 async function listAllAssistants(): Promise<void> {
@@ -252,6 +303,20 @@ async function listAllAssistants(): Promise<void> {
 
   if (assistants.length === 0) {
     console.log("No assistants found.");
+
+    const orphans = await detectOrphanedProcesses();
+    if (orphans.length > 0) {
+      console.log("\nOrphaned processes detected:\n");
+      const rows: TableRow[] = orphans.map((o) => ({
+        name: o.name,
+        status: withStatusEmoji("running"),
+        info: `PID ${o.pid} (from ${o.source})`,
+      }));
+      printTable(rows);
+      const pids = orphans.map((o) => o.pid).join(" ");
+      console.log(`\nHint: Run \`kill ${pids}\` to clean up orphaned processes.`);
+    }
+
     return;
   }
 

package/src/commands/recover.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync, unlinkSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+import { saveAssistantEntry } from "../lib/assistant-config";
+import type { AssistantEntry } from "../lib/assistant-config";
+import { startLocalDaemon, startGateway } from "../lib/local";
+import { getArchivePath, getMetadataPath } from "../lib/retire-archive";
+import { exec } from "../lib/step-runner";
+
+export async function recover(): Promise<void> {
+  const name = process.argv[3];
+  if (!name) {
+    console.error("Usage: vellum-cli recover <name>");
+    process.exit(1);
+  }
+
+  const archivePath = getArchivePath(name);
+  const metadataPath = getMetadataPath(name);
+
+  // 1. Verify archive exists
+  if (!existsSync(archivePath) || !existsSync(metadataPath)) {
+    console.error(`No retired archive found for '${name}'.`);
+    process.exit(1);
+  }
+
+  // 2. Check ~/.vellum doesn't already exist
+  const vellumDir = join(homedir(), ".vellum");
+  if (existsSync(vellumDir)) {
+    console.error(
+      "Error: ~/.vellum already exists. Retire the current assistant first."
+    );
+    process.exit(1);
+  }
+
+  // 3. Extract archive
+  await exec("tar", ["xzf", archivePath, "-C", homedir()]);
+
+  // 4. Restore lockfile entry
+  const entry: AssistantEntry = JSON.parse(readFileSync(metadataPath, "utf-8"));
+  saveAssistantEntry(entry);
+
+  // 5. Clean up archive
+  unlinkSync(archivePath);
+  unlinkSync(metadataPath);
+
+  // 6. Start daemon + gateway (same as wake)
+  await startLocalDaemon();
+  if (!process.env.VELLUM_DESKTOP_APP) {
+    await startGateway();
+  }
+
+  console.log(`✅ Recovered assistant '${name}'.`);
+}

package/src/commands/retire.ts

@@ -1,13 +1,14 @@
 import { spawn } from "child_process";
-import { rmSync } from "fs";
+import { rmSync, writeFileSync } from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { basename, dirname, join } from "path";
 
 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 { stopProcessByPidFile } from "../lib/process";
+import { getArchivePath, getMetadataPath } from "../lib/retire-archive";
 import { exec } from "../lib/step-runner";
 
 function resolveCloud(entry: AssistantEntry): string {
@@ -32,7 +33,7 @@ function extractHostFromUrl(url: string): string {
   }
 }
 
-async function retireLocal(): Promise<void> {
+async function retireLocal(name: string, entry: AssistantEntry): Promise<void> {
   console.log("\u{1F5D1}\ufe0f  Stopping local daemon...\n");
 
   const vellumDir = join(homedir(), ".vellum");
@@ -61,6 +62,18 @@ async function retireLocal(): Promise<void> {
     } catch {}
   }
 
+  // Archive ~/.vellum before deleting
+  try {
+    const archivePath = getArchivePath(name);
+    const metadataPath = getMetadataPath(name);
+    await exec("tar", ["czf", archivePath, "-C", dirname(vellumDir), basename(vellumDir)]);
+    writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
+    console.log(`📦 Archived to ${archivePath}`);
+  } catch (err) {
+    console.warn(`⚠️  Failed to archive: ${err instanceof Error ? err.message : err}`);
+    console.warn("Proceeding with permanent deletion.");
+  }
+
   rmSync(vellumDir, { recursive: true, force: true });
 
   console.log("\u2705 Local instance retired.");
@@ -142,7 +155,7 @@ export async function retire(): Promise<void> {
     }
     await retireAwsInstance(name, region, source);
   } else if (cloud === "local") {
-    await retireLocal();
+    await retireLocal(name, entry);
   } else if (cloud === "custom") {
     await retireCustom(entry);
   } else {

package/src/email/vellum.ts

@@ -9,17 +9,10 @@ const DEFAULT_VELLUM_API_URL = "https://api.vellum.ai";
 // Types
 // ---------------------------------------------------------------------------
 
-export interface EmailInbox {
+export interface AssistantEmailAddress {
   id: string;
   address: string;
-  displayName?: string;
-  createdAt: string;
-}
-
-export interface EmailStatus {
-  provider: string;
-  ok: boolean;
-  inboxes: EmailInbox[];
+  created_at: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -63,8 +56,10 @@ async function vellumFetch(
 export class VellumEmailClient {
   private apiKey: string;
   private baseUrl: string;
+  private assistantId: string;
 
-  constructor(apiKey?: string, baseUrl?: string) {
+  constructor(assistantId: string, apiKey?: string, baseUrl?: string) {
+    this.assistantId = assistantId;
     const resolvedKey = apiKey ?? process.env.VELLUM_API_KEY;
     if (!resolvedKey) {
       throw new Error(
@@ -77,27 +72,26 @@ export class VellumEmailClient {
   }
 
   /** List existing email addresses and check connectivity. */
-  async status(): Promise<EmailStatus> {
+  async status(): Promise<AssistantEmailAddress[]> {
     const result = await vellumFetch(
       this.apiKey,
       this.baseUrl,
-      "/v1/email-addresses",
+      `/v1/assistants/${this.assistantId}/email-addresses/`,
     );
-    const inboxes = (result as { inboxes: EmailInbox[] }).inboxes;
-    return { provider: "vellum", ok: true, inboxes };
+    return result as AssistantEmailAddress[];
   }
 
   /** Provision a new email address for the given username. */
-  async createInbox(username: string): Promise<EmailInbox> {
+  async createInbox(username: string): Promise<AssistantEmailAddress> {
     const result = await vellumFetch(
       this.apiKey,
       this.baseUrl,
-      "/v1/email-addresses",
+      `/v1/assistants/${this.assistantId}/email-addresses/`,
       {
         method: "POST",
         body: { username },
       },
     );
-    return result as EmailInbox;
+    return result as AssistantEmailAddress;
   }
 }

package/src/index.ts

@@ -6,9 +6,11 @@ import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { client } from "./commands/client";
+import { config } from "./commands/config";
 import { email } from "./commands/email";
 import { hatch } from "./commands/hatch";
 import { ps } from "./commands/ps";
+import { recover } from "./commands/recover";
 import { retire } from "./commands/retire";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
@@ -16,9 +18,11 @@ import { wake } from "./commands/wake";
 
 const commands = {
   client,
+  config,
   email,
   hatch,
   ps,
+  recover,
   retire,
   sleep,
   ssh,
@@ -62,9 +66,11 @@ async function main() {
     console.log("");
     console.log("Commands:");
     console.log("  client   Connect to a hatched assistant");
+    console.log("  config   Manage configuration");
     console.log("  email    Email operations (status, create inbox)");
     console.log("  hatch    Create a new assistant instance");
     console.log("  ps       List assistants (or processes for a specific assistant)");
+    console.log("  recover  Restore a previously retired local assistant");
     console.log("  retire   Delete an assistant instance");
     console.log("  sleep    Stop the daemon process");
     console.log("  ssh      SSH into a remote assistant instance");

package/src/lib/local.ts

@@ -193,6 +193,7 @@ export async function startLocalDaemon(): Promise<void> {
       for (const key of [
         "ANTHROPIC_API_KEY",
         "BASE_DATA_DIR",
+        "RUNTIME_HTTP_PORT",
         "VELLUM_DAEMON_TCP_PORT",
         "VELLUM_DAEMON_TCP_HOST",
         "VELLUM_DAEMON_SOCKET",

package/src/lib/retire-archive.ts

@@ -0,0 +1,43 @@
+import { mkdirSync } from "fs";
+import { homedir } from "os";
+import { basename, join, resolve } from "path";
+
+export function getRetiredDir(): string {
+  const xdgData =
+    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share");
+  const dir = join(xdgData, "vellum", "retired");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Throws if the name contains path separators or traversal segments. */
+export function validateAssistantName(name: string): void {
+  if (
+    !name ||
+    name.includes("/") ||
+    name.includes("\\") ||
+    name === ".." ||
+    name === "."
+  ) {
+    throw new Error(`Invalid assistant name: '${name}'`);
+  }
+}
+
+function safeName(assistantId: string): string {
+  validateAssistantName(assistantId);
+  // Canonicalize and verify the result stays inside the retired directory
+  const retiredDir = getRetiredDir();
+  const candidate = resolve(retiredDir, basename(assistantId));
+  if (!candidate.startsWith(retiredDir + "/")) {
+    throw new Error(`Invalid assistant name: '${assistantId}'`);
+  }
+  return basename(assistantId);
+}
+
+export function getArchivePath(assistantId: string): string {
+  return join(getRetiredDir(), `${safeName(assistantId)}.tar.gz`);
+}
+
+export function getMetadataPath(assistantId: string): string {
+  return join(getRetiredDir(), `${safeName(assistantId)}.json`);
+}