@vellumai/cli 0.3.11 → 0.3.13

package/src/commands/skills.ts

@@ -0,0 +1,355 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { randomUUID } from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// 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 SKILL.md content from a tar archive (uncompressed).
+ */
+function extractSkillMdFromTar(tarBuffer: Buffer): string | null {
+  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 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
+
+    if (name.endsWith("SKILL.md") || name === "SKILL.md") {
+      return tarBuffer.subarray(offset, offset + size).toString("utf-8");
+    }
+
+    // Skip to next header (data padded to 512 bytes)
+    offset += Math.ceil(size / 512) * 512;
+  }
+  return null;
+}
+
+async function fetchSkillContent(skillId: string): Promise<string> {
+  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 skillMd = extractSkillMdFromTar(tarBuffer);
+
+  if (!skillMd) {
+    throw new Error(`SKILL.md not found in archive for "${skillId}"`);
+  }
+
+  return skillMd;
+}
+
+// ---------------------------------------------------------------------------
+// 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");
+}
+
+function installSkillLocally(
+  skillId: string,
+  skillMdContent: string,
+  catalogEntry: CatalogSkill,
+  overwrite: boolean,
+): 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 });
+  atomicWriteFile(skillFilePath, skillMdContent);
+
+  // 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",
+    );
+  }
+
+  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 SKILL.md from platform
+        const content = await fetchSkillContent(skillId);
+
+        // Install locally
+        installSkillLocally(skillId, content, 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/ssh.ts

@@ -40,7 +40,7 @@ export async function ssh(): Promise<void> {
     if (name) {
       console.error(`No assistant instance found with name '${name}'.`);
     } else {
-      console.error("No assistant instance found. Run `vellum-cli hatch` first.");
+      console.error("No assistant instance found. Run `vellum hatch` first.");
     }
     process.exit(1);
   }
@@ -50,7 +50,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-cli ps ${entry.assistantId}' to check its processes instead.`,
+      `Use 'vellum ps ${entry.assistantId}' to check its processes instead.`,
     );
     process.exit(1);
   }
@@ -81,6 +81,9 @@ export async function ssh(): Promise<void> {
       ["compute", "ssh", sshTarget, `--project=${project}`, `--zone=${zone}`],
       { stdio: "inherit" },
     );
+  } else if (cloud === "vellum") {
+    console.error("SSH to Vellum-managed instances is not yet supported.");
+    process.exit(1);
   } else if (cloud === "custom") {
     const host = extractHostFromUrl(entry.runtimeUrl);
     const sshUser = entry.sshUser ?? "root";

package/src/components/DefaultMainScreen.tsx

@@ -1,6 +1,7 @@
 import { spawn } from "child_process";
-import { randomUUID } from "crypto";
+import { randomBytes, randomUUID } from "crypto";
 import { basename } from "path";
+import qrcode from "qrcode-terminal";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactElement } from "react";
 import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 
@@ -23,7 +24,7 @@ export const ANSI = {
   gray: "\x1b[90m",
 } as const;
 
-export const SLASH_COMMANDS = ["/clear", "/doctor", "/exit", "/help", "/q", "/quit", "/retire"];
+export const SLASH_COMMANDS = ["/clear", "/doctor", "/exit", "/help", "/pair", "/q", "/quit", "/retire"];
 
 const POLL_INTERVAL_MS = 3000;
 const SEND_TIMEOUT_MS = 5000;
@@ -157,7 +158,7 @@ async function sendMessage(
     "/messages",
     {
       method: "POST",
-      body: JSON.stringify({ conversationKey: assistantId, content }),
+      body: JSON.stringify({ conversationKey: assistantId, content, sourceChannel: "vellum", interface: "cli" }),
       signal,
     },
     bearerToken,
@@ -529,6 +530,10 @@ function HelpDisplay(): ReactElement {
         {"  /clear            "}
         <Text dimColor>Clear the screen</Text>
       </Text>
+      <Text>
+        {"  /pair             "}
+        <Text dimColor>Generate a QR code for mobile device pairing</Text>
+      </Text>
       <Text>
         {"  /help, ?          "}
         <Text dimColor>Show this help</Text>
@@ -1280,6 +1285,65 @@ function ChatApp({
         return;
       }
 
+      if (trimmed === "/pair") {
+        h.showSpinner("Generating pairing credentials...");
+
+        const isConnected = await ensureConnected();
+        if (!isConnected) {
+          h.hideSpinner();
+          h.showError("Cannot pair — not connected to the assistant runtime.");
+          return;
+        }
+
+        try {
+          const pairingRequestId = randomUUID();
+          const pairingSecret = randomBytes(32).toString("hex");
+          const gatewayUrl = runtimeUrl;
+
+          // Call /v1/pairing/register directly (not under /v1/assistants/:id/)
+          const registerUrl = `${runtimeUrl}/v1/pairing/register`;
+          const registerRes = await fetch(registerUrl, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+            },
+            body: JSON.stringify({ pairingRequestId, pairingSecret, gatewayUrl }),
+          });
+
+          if (!registerRes.ok) {
+            const body = await registerRes.text().catch(() => "");
+            throw new Error(`HTTP ${registerRes.status}: ${body || registerRes.statusText}`);
+          }
+
+          const payload = JSON.stringify({
+            type: "vellum-daemon",
+            v: 4,
+            g: gatewayUrl,
+            pairingRequestId,
+            pairingSecret,
+          });
+
+          const qrString = await new Promise<string>((resolve) => {
+            qrcode.generate(payload, { small: true }, (code: string) => {
+              resolve(code);
+            });
+          });
+
+          h.hideSpinner();
+          h.addStatus(
+            `Pairing Ready\n\n` +
+              `Scan this QR code with the Vellum iOS app:\n\n` +
+              `${qrString}\n` +
+              `This pairing request expires in 5 minutes. Run /pair again to generate a new one.`,
+          );
+        } catch (err) {
+          h.hideSpinner();
+          h.showError(`Pairing failed: ${err instanceof Error ? err.message : err}`);
+        }
+        return;
+      }
+
       if (trimmed === "/retire") {
         if (!project || !zone) {
           h.showError("No instance info available. Connect to a hatched instance first.");

package/src/index.ts

@@ -5,28 +5,40 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+
+import cliPkg from "../package.json";
+import { autonomy } from "./commands/autonomy";
 import { client } from "./commands/client";
 import { config } from "./commands/config";
+import { contacts } from "./commands/contacts";
 import { email } from "./commands/email";
 import { hatch } from "./commands/hatch";
+import { login, logout, whoami } from "./commands/login";
 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 { wake } from "./commands/wake";
 
 const commands = {
+  autonomy,
   client,
   config,
+  contacts,
   email,
   hatch,
+  login,
+  logout,
   ps,
   recover,
   retire,
+  skills,
   sleep,
   ssh,
   wake,
+  whoami,
 } as const;
 
 type CommandName = keyof typeof commands;
@@ -61,20 +73,31 @@ async function main() {
   const args = process.argv.slice(2);
   const commandName = args[0];
 
+  if (commandName === "--version" || commandName === "-v") {
+    console.log(`@vellumai/cli v${cliPkg.version}`);
+    process.exit(0);
+  }
+
   if (!commandName || commandName === "--help" || commandName === "-h") {
     console.log("Usage: vellum <command> [options]");
     console.log("");
     console.log("Commands:");
+    console.log("  autonomy View and configure autonomy tiers");
     console.log("  client   Connect to a hatched assistant");
     console.log("  config   Manage configuration");
+    console.log("  contacts Manage the contact graph");
     console.log("  email    Email operations (status, create inbox)");
     console.log("  hatch    Create a new assistant instance");
+    console.log("  login    Log in to the Vellum platform");
+    console.log("  logout   Log out of the Vellum platform");
     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("  skills   Browse and install skills from the Vellum catalog");
     console.log("  sleep    Stop the daemon process");
     console.log("  ssh      SSH into a remote assistant instance");
     console.log("  wake     Start the daemon and gateway");
+    console.log("  whoami   Show current logged-in user");
     process.exit(0);
   }
 

package/src/lib/assistant-config.ts

@@ -9,6 +9,7 @@ export interface AssistantEntry {
   bearerToken?: string;
   cloud: string;
   instanceId?: string;
+  namespace?: string;
   project?: string;
   region?: string;
   species?: string;

package/src/lib/gcp.ts

@@ -1,5 +1,5 @@
 import { randomBytes } from "crypto";
-import { existsSync, unlinkSync, writeFileSync } from "fs";
+import { unlinkSync, writeFileSync } from "fs";
 import { tmpdir, userInfo } from "os";
 import { join } from "path";
 
@@ -370,13 +370,12 @@ const DESIRED_FIREWALL_RULES: FirewallRuleSpec[] = [
   },
 ];
 
-async function resolveInstallScriptPath(): Promise<string | null> {
-  const sourcePath = join(import.meta.dir, "..", "adapters", "install.sh");
-  if (existsSync(sourcePath)) {
-    return sourcePath;
-  }
-  console.warn("\u26a0\ufe0f  Install script not found at", sourcePath, "(expected in compiled binary)");
-  return null;
+import INSTALL_SCRIPT_CONTENT from "../adapters/install.sh" with { type: "text" };
+
+function resolveInstallScriptPath(): string {
+  const tmpPath = join(tmpdir(), `vellum-install-${process.pid}.sh`);
+  writeFileSync(tmpPath, INSTALL_SCRIPT_CONTENT, { mode: 0o755 });
+  return tmpPath;
 }
 
 async function pollInstance(
@@ -459,11 +458,7 @@ async function recoverFromCurlFailure(
   sshUser: string,
   account?: string,
 ): Promise<void> {
-  const installScriptPath = await resolveInstallScriptPath();
-  if (!installScriptPath) {
-    console.warn("\u26a0\ufe0f  Skipping install script upload (not available in compiled binary)");
-    return;
-  }
+  const installScriptPath = resolveInstallScriptPath();
 
   const scpArgs = [
     "compute",
@@ -488,6 +483,7 @@ async function recoverFromCurlFailure(
   if (account) sshArgs.push(`--account=${account}`);
   console.log("\ud83d\udd27 Running install script on instance...");
   await exec("gcloud", sshArgs);
+  try { unlinkSync(installScriptPath); } catch {}
 }
 
 export async function hatchGcp(