@vellumai/cli 0.3.3 → 0.3.5

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./package.json": "./package.json",
     "./src/components/DefaultMainScreen": "./src/components/DefaultMainScreen.tsx",
-    "./src/lib/constants": "./src/lib/constants.ts"
+    "./src/lib/constants": "./src/lib/constants.ts",
+    "./src/commands/*": "./src/commands/*.ts"
   },
   "bin": {
     "vellum-cli": "./src/index.ts"

package/src/commands/client.ts

@@ -1,3 +1,6 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+
 import { ANSI, renderChatApp } from "../components/DefaultMainScreen";
 import { findAssistantByName, loadLatestAssistant } from "../lib/assistant-config";
 import { GATEWAY_PORT, type Species } from "../lib/constants";
@@ -42,7 +45,19 @@ function parseArgs(): ParsedArgs {
 
   let runtimeUrl = process.env.RUNTIME_URL || entry?.runtimeUrl || FALLBACK_RUNTIME_URL;
   let assistantId = process.env.ASSISTANT_ID || entry?.assistantId || FALLBACK_ASSISTANT_ID;
-  const bearerToken = process.env.RUNTIME_PROXY_BEARER_TOKEN || entry?.bearerToken || undefined;
+  let bearerToken = process.env.RUNTIME_PROXY_BEARER_TOKEN || entry?.bearerToken || undefined;
+
+  // For local assistants, read the daemon's http-token file as a fallback
+  // when the lockfile doesn't include a bearer token.
+  if (!bearerToken && entry?.cloud === "local") {
+    const tokenDir = entry.baseDataDir ?? join(process.env.HOME ?? "", ".vellum");
+    try {
+      const token = readFileSync(join(tokenDir, "http-token"), "utf-8").trim();
+      if (token) bearerToken = token;
+    } catch {
+      // Token file may not exist
+    }
+  }
   const species: Species = (entry?.species as Species) ?? "vellum";
 
   for (let i = 0; i < flagArgs.length; i++) {

package/src/commands/email.ts

@@ -0,0 +1,88 @@
+/**
+ * CLI command: `vellum email`
+ *
+ * Supports:
+ *   - `vellum email status`            — show current email configuration
+ *   - `vellum email create <username>`  — provision a new email inbox
+ */
+
+import { VellumEmailClient } from "../email/vellum.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function output(data: unknown): void {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+
+function exitError(message: string): void {
+  output({ ok: false, error: message });
+  process.exitCode = 1;
+}
+
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+
+function printUsage(): void {
+  console.log(`Usage: vellum email <subcommand> [options]
+
+Subcommands:
+  status                Show email status (address, inboxes, callback URL)
+  create <username>     Create a new email inbox for the given username
+
+Options:
+  --help, -h            Show this help message
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+export async function email(): Promise<void> {
+  const args = process.argv.slice(3); // everything after "email"
+
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    printUsage();
+    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,
+        });
+      } catch (err) {
+        exitError(err instanceof Error ? err.message : String(err));
+      }
+      break;
+    }
+    case "create": {
+      const username = args[1];
+      if (!username) {
+        exitError("Usage: vellum email create <username>");
+        return;
+      }
+      try {
+        const client = new VellumEmailClient();
+        const inbox = await client.createInbox(username);
+        output({ ok: true, inbox });
+      } catch (err) {
+        exitError(err instanceof Error ? err.message : String(err));
+      }
+      break;
+    }
+    default:
+      exitError(`Unknown email subcommand: ${subcommand}`);
+      printUsage();
+  }
+}

package/src/commands/hatch.ts

@@ -1,5 +1,5 @@
 import { randomBytes } from "crypto";
-import { existsSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { homedir, tmpdir, userInfo } from "os";
 import { join } from "path";
 
@@ -549,10 +549,22 @@ async function hatchLocal(species: Species, name: string | null, daemonOnly: boo
   }
 
   const baseDataDir = join(process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? userInfo().homedir), ".vellum");
+
+  // Read the bearer token written by the daemon so the client can authenticate
+  // with the gateway (which requires auth by default).
+  let bearerToken: string | undefined;
+  try {
+    const token = readFileSync(join(baseDataDir, "http-token"), "utf-8").trim();
+    if (token) bearerToken = token;
+  } catch {
+    // Token file may not exist if daemon started without HTTP server
+  }
+
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
     baseDataDir,
+    bearerToken,
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),

package/src/commands/ps.ts

@@ -145,53 +145,59 @@ async function getRemoteProcessesCustom(
   ]);
 }
 
-function getLocalProcesses(): TableRow[] {
+function checkPidFile(pidFile: string): { status: string; pid: string | null } {
+  if (!existsSync(pidFile)) {
+    return { status: "not running", pid: null };
+  }
+  const pid = readFileSync(pidFile, "utf-8").trim();
+  try {
+    process.kill(parseInt(pid, 10), 0);
+    return { status: "running", pid };
+  } catch {
+    return { status: "not running", pid };
+  }
+}
+
+async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
+  const vellumDir = entry.baseDataDir ?? join(homedir(), ".vellum");
   const rows: TableRow[] = [];
-  const vellumDir = join(homedir(), ".vellum");
 
   // Check daemon PID
-  const pidFile = join(vellumDir, "vellum.pid");
-  if (existsSync(pidFile)) {
-    const pid = readFileSync(pidFile, "utf-8").trim();
-    let status = "running";
-    try {
-      process.kill(parseInt(pid, 10), 0);
-    } catch {
-      status = "not running";
-    }
-    rows.push({ name: "daemon", status: withStatusEmoji(status), info: `PID ${pid}` });
-  } else {
-    rows.push({ name: "daemon", status: withStatusEmoji("not running"), info: "no PID file" });
-  }
+  const daemon = checkPidFile(join(vellumDir, "vellum.pid"));
+  rows.push({
+    name: "daemon",
+    status: withStatusEmoji(daemon.status),
+    info: daemon.pid ? `PID ${daemon.pid}` : "no PID file",
+  });
 
   // Check qdrant PID
-  const qdrantPidFile = join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid");
-  if (existsSync(qdrantPidFile)) {
-    const pid = readFileSync(qdrantPidFile, "utf-8").trim();
-    let status = "running";
-    try {
-      process.kill(parseInt(pid, 10), 0);
-    } catch {
-      status = "not running";
-    }
-    rows.push({ name: "qdrant", status: withStatusEmoji(status), info: `PID ${pid} | port 6333` });
-  } else {
-    rows.push({ name: "qdrant", status: withStatusEmoji("not running"), info: "no PID file" });
-  }
+  const qdrant = checkPidFile(join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"));
+  rows.push({
+    name: "qdrant",
+    status: withStatusEmoji(qdrant.status),
+    info: qdrant.pid ? `PID ${qdrant.pid} | port 6333` : "no PID file",
+  });
 
   // Check gateway PID
-  const gatewayPidFile = join(vellumDir, "gateway.pid");
-  if (existsSync(gatewayPidFile)) {
-    const pid = readFileSync(gatewayPidFile, "utf-8").trim();
-    let status = "running";
-    try {
-      process.kill(parseInt(pid, 10), 0);
-    } catch {
-      status = "not running";
+  const gateway = checkPidFile(join(vellumDir, "gateway.pid"));
+  rows.push({
+    name: "gateway",
+    status: withStatusEmoji(gateway.status),
+    info: gateway.pid ? `PID ${gateway.pid} | port 7830` : "no PID file",
+  });
+
+  // If no PID files found, fall back to health check
+  const allMissingPid = !daemon.pid && !qdrant.pid && !gateway.pid;
+  if (allMissingPid) {
+    const health = await checkHealth(entry.runtimeUrl);
+    if (health.status === "healthy" || health.status === "ok") {
+      rows.length = 0;
+      rows.push({
+        name: "daemon",
+        status: withStatusEmoji("running"),
+        info: "no PID file (detected via health check)",
+      });
     }
-    rows.push({ name: "gateway", status: withStatusEmoji(status), info: `PID ${pid} | port 7830` });
-  } else {
-    rows.push({ name: "gateway", status: withStatusEmoji("not running"), info: "no PID file" });
   }
 
   return rows;
@@ -203,7 +209,7 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   console.log(`Processes for ${entry.assistantId} (${cloud}):\n`);
 
   if (cloud === "local") {
-    const rows = getLocalProcesses();
+    const rows = await getLocalProcesses(entry);
     printTable(rows);
     return;
   }

package/src/commands/ssh.ts

@@ -0,0 +1,111 @@
+import { spawn } from "child_process";
+
+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",
+];
+
+function resolveCloud(entry: AssistantEntry): string {
+  if (entry.cloud) {
+    return entry.cloud;
+  }
+  if (entry.project) {
+    return "gcp";
+  }
+  if (entry.sshUser) {
+    return "custom";
+  }
+  return "local";
+}
+
+function extractHostFromUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname;
+  } catch {
+    return url.replace(/^https?:\/\//, "").split(":")[0];
+  }
+}
+
+export async function ssh(): Promise<void> {
+  const name = process.argv[3];
+  const entry = name ? findAssistantByName(name) : loadLatestAssistant();
+
+  if (!entry) {
+    if (name) {
+      console.error(`No assistant instance found with name '${name}'.`);
+    } else {
+      console.error("No assistant instance found. Run `vellum-cli hatch` first.");
+    }
+    process.exit(1);
+  }
+
+  const cloud = resolveCloud(entry);
+
+  if (cloud === "local") {
+    console.error(
+      "Cannot SSH into a local assistant. Local assistants run directly on this machine.\n" +
+      `Use 'vellum-cli ps ${entry.assistantId}' to check its processes instead.`,
+    );
+    process.exit(1);
+  }
+
+  if (cloud === "aws") {
+    console.error("SSH to AWS instances is not yet supported.");
+    process.exit(1);
+  }
+
+  let child;
+
+  if (cloud === "gcp") {
+    const project = entry.project;
+    const zone = entry.zone;
+    if (!project || !zone) {
+      console.error("Error: GCP project and zone not found in assistant config.");
+      process.exit(1);
+    }
+
+    const sshTarget = entry.sshUser
+      ? `${entry.sshUser}@${entry.assistantId}`
+      : entry.assistantId;
+
+    console.log(`🔗 Connecting to ${entry.assistantId} via gcloud...\n`);
+
+    child = spawn(
+      "gcloud",
+      ["compute", "ssh", sshTarget, `--project=${project}`, `--zone=${zone}`],
+      { stdio: "inherit" },
+    );
+  } else if (cloud === "custom") {
+    const host = extractHostFromUrl(entry.runtimeUrl);
+    const sshUser = entry.sshUser ?? "root";
+    const sshTarget = `${sshUser}@${host}`;
+
+    console.log(`🔗 Connecting to ${entry.assistantId} via ssh...\n`);
+
+    child = spawn(
+      "ssh",
+      [...SSH_OPTS, sshTarget],
+      { stdio: "inherit" },
+    );
+  } else {
+    console.error(`Error: Unknown cloud type '${cloud}'.`);
+    process.exit(1);
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`ssh exited with code ${code}`));
+      }
+    });
+    child.on("error", reject);
+  });
+}

package/src/email/vellum.ts

@@ -0,0 +1,103 @@
+/**
+ * Vellum email API client — calls the Vellum platform email endpoints.
+ */
+
+// The domain for the Vellum email API is still being finalized and may change.
+const DEFAULT_VELLUM_API_URL = "https://api.vellum.ai";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EmailInbox {
+  id: string;
+  address: string;
+  displayName?: string;
+  createdAt: string;
+}
+
+export interface EmailStatus {
+  provider: string;
+  ok: boolean;
+  inboxes: EmailInbox[];
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helper
+// ---------------------------------------------------------------------------
+
+async function vellumFetch(
+  apiKey: string,
+  baseUrl: string,
+  path: string,
+  opts: { method?: string; body?: unknown } = {},
+): Promise<unknown> {
+  const url = `${baseUrl}${path}`;
+  const response = await fetch(url, {
+    method: opts.method ?? "GET",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: opts.body ? JSON.stringify(opts.body) : undefined,
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(
+      `Vellum email API error: ${response.status} ${response.statusText}${text ? ` — ${text}` : ""}`,
+    );
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return response.json();
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+export class VellumEmailClient {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(apiKey?: string, baseUrl?: string) {
+    const resolvedKey = apiKey ?? process.env.VELLUM_API_KEY;
+    if (!resolvedKey) {
+      throw new Error(
+        "No Vellum API key configured. Set the VELLUM_API_KEY environment variable.",
+      );
+    }
+    this.apiKey = resolvedKey;
+    this.baseUrl =
+      baseUrl ?? process.env.VELLUM_API_URL ?? DEFAULT_VELLUM_API_URL;
+  }
+
+  /** List existing email addresses and check connectivity. */
+  async status(): Promise<EmailStatus> {
+    const result = await vellumFetch(
+      this.apiKey,
+      this.baseUrl,
+      "/v1/email-addresses",
+    );
+    const inboxes = (result as { inboxes: EmailInbox[] }).inboxes;
+    return { provider: "vellum", ok: true, inboxes };
+  }
+
+  /** Provision a new email address for the given username. */
+  async createInbox(username: string): Promise<EmailInbox> {
+    const result = await vellumFetch(
+      this.apiKey,
+      this.baseUrl,
+      "/v1/email-addresses",
+      {
+        method: "POST",
+        body: { username },
+      },
+    );
+    return result as EmailInbox;
+  }
+}

package/src/index.ts

@@ -1,26 +1,58 @@
 #!/usr/bin/env bun
 
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { client } from "./commands/client";
+import { email } from "./commands/email";
 import { hatch } from "./commands/hatch";
 import { ps } from "./commands/ps";
 import { retire } from "./commands/retire";
 import { sleep } from "./commands/sleep";
+import { ssh } from "./commands/ssh";
 import { wake } from "./commands/wake";
 
 const commands = {
   client,
+  email,
   hatch,
   ps,
   retire,
   sleep,
+  ssh,
   wake,
 } as const;
 
 type CommandName = keyof typeof commands;
 
+function resolveAssistantEntry(): string | undefined {
+  // When installed globally, resolve from node_modules
+  try {
+    const require = createRequire(import.meta.url);
+    const assistantPkgPath = require.resolve(
+      "@vellumai/assistant/package.json"
+    );
+    return join(dirname(assistantPkgPath), "src", "index.ts");
+  } catch {
+    // For local development, resolve from sibling directory
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const localPath = join(
+      __dirname,
+      "..",
+      "..",
+      "assistant",
+      "src",
+      "index.ts"
+    );
+    if (existsSync(localPath)) {
+      return localPath;
+    }
+  }
+  return undefined;
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const commandName = args[0];
@@ -30,10 +62,12 @@ async function main() {
     console.log("");
     console.log("Commands:");
     console.log("  client   Connect to a hatched assistant");
+    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("  retire   Delete an assistant instance");
     console.log("  sleep    Stop the daemon process");
+    console.log("  ssh      SSH into a remote assistant instance");
     console.log("  wake     Start the daemon and gateway");
     process.exit(0);
   }
@@ -41,23 +75,15 @@ async function main() {
   const command = commands[commandName as CommandName];
 
   if (!command) {
-    try {
-      const require = createRequire(import.meta.url);
-      const assistantPkgPath = require.resolve(
-        "@vellumai/assistant/package.json"
-      );
-      const assistantEntry = join(
-        dirname(assistantPkgPath),
-        "src",
-        "index.ts"
-      );
+    const assistantEntry = resolveAssistantEntry();
+    if (assistantEntry) {
       const child = spawn("bun", ["run", assistantEntry, ...args], {
         stdio: "inherit",
       });
       child.on("exit", (code) => {
         process.exit(code ?? 1);
       });
-    } catch {
+    } else {
       console.error(`Unknown command: ${commandName}`);
       console.error(
         "Install the full stack with: bun install -g vellum"

package/src/lib/assistant-config.ts

@@ -22,30 +22,33 @@ interface LockfileData {
   [key: string]: unknown;
 }
 
-function getLockfilePath(): string {
-  return join(homedir(), ".vellum.lock.json");
+function getBaseDir(): string {
+  return process.env.BASE_DATA_DIR?.trim() || homedir();
 }
 
 function readLockfile(): LockfileData {
-  const lockfilePath = getLockfilePath();
-  if (!existsSync(lockfilePath)) {
-    return {};
-  }
-
-  try {
-    const raw = readFileSync(lockfilePath, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed as LockfileData;
+  const base = getBaseDir();
+  const candidates = [
+    join(base, ".vellum.lock.json"),
+    join(base, ".vellum.lockfile.json"),
+  ];
+  for (const lockfilePath of candidates) {
+    if (!existsSync(lockfilePath)) continue;
+    try {
+      const raw = readFileSync(lockfilePath, "utf-8");
+      const parsed = JSON.parse(raw) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as LockfileData;
+      }
+    } catch {
+      // Malformed lockfile; try next
     }
-  } catch {
-    // Malformed lockfile; return empty
   }
   return {};
 }
 
 function writeLockfile(data: LockfileData): void {
-  const lockfilePath = getLockfilePath();
+  const lockfilePath = join(getBaseDir(), ".vellum.lock.json");
   writeFileSync(lockfilePath, JSON.stringify(data, null, 2) + "\n");
 }
 

package/src/lib/local.ts

@@ -302,13 +302,62 @@ export async function startGateway(): Promise<string> {
   const assistants = loadAllAssistants();
   const isSingleAssistant = assistants.length === 1;
 
+  // Read the bearer token so the gateway can authenticate proxied requests
+  // (e.g. from paired iOS devices). Respect VELLUM_HTTP_TOKEN_PATH and
+  // BASE_DATA_DIR for consistency with gateway/config.ts and the daemon.
+  const httpTokenPath = process.env.VELLUM_HTTP_TOKEN_PATH
+    ?? join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum", "http-token");
+  let runtimeProxyBearerToken: string | undefined;
+  try {
+    const tok = readFileSync(httpTokenPath, "utf-8").trim();
+    if (tok) runtimeProxyBearerToken = tok;
+  } catch {
+    // Token file doesn't exist yet — daemon hasn't written it.
+  }
+
+  // If no token is available (first startup — daemon hasn't written it yet),
+  // poll for the file to appear. The daemon writes the token shortly after
+  // startup, so a short wait avoids starting the gateway without auth
+  // (which would leave it permanently unauthenticated since the gateway
+  // config is loaded once at startup and never reloads).
+  if (!runtimeProxyBearerToken) {
+    console.log("   Waiting for bearer token file...");
+    const maxWait = 10000;
+    const pollInterval = 500;
+    const start = Date.now();
+    while (Date.now() - start < maxWait) {
+      await new Promise((r) => setTimeout(r, pollInterval));
+      try {
+        const tok = readFileSync(httpTokenPath, "utf-8").trim();
+        if (tok) {
+          runtimeProxyBearerToken = tok;
+          break;
+        }
+      } catch {
+        // File still doesn't exist, keep polling.
+      }
+    }
+  }
+
+  // If the token still isn't available after polling, fall back to starting
+  // the gateway without auth so it doesn't block forever. This is a degraded
+  // mode — the proxy will be broken because the runtime expects a token.
+  const proxyRequireAuth = runtimeProxyBearerToken ? "true" : "false";
+  if (!runtimeProxyBearerToken) {
+    console.log("   ⚠️  Bearer token not found after 10s — gateway proxy auth disabled");
+  }
+
   const gatewayEnv: Record<string, string> = {
     ...process.env as Record<string, string>,
     GATEWAY_RUNTIME_PROXY_ENABLED: "true",
-    GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH: "false",
+    GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH: proxyRequireAuth,
     RUNTIME_HTTP_PORT: process.env.RUNTIME_HTTP_PORT || "7821",
   };
 
+  if (runtimeProxyBearerToken) {
+    gatewayEnv.RUNTIME_PROXY_BEARER_TOKEN = runtimeProxyBearerToken;
+  }
+
   if (process.env.GATEWAY_UNMAPPED_POLICY) {
     gatewayEnv.GATEWAY_UNMAPPED_POLICY = process.env.GATEWAY_UNMAPPED_POLICY;
   } else if (isSingleAssistant) {