@vellumai/cli 0.4.34 → 0.4.36

package/AGENTS.md

@@ -0,0 +1,47 @@
+# CLI Package — Agent Instructions
+
+## Purpose
+
+The `cli/` package (`@vellumai/cli`) manages the **lifecycle of Vellum assistant instances** — creating, starting, stopping, connecting to, and deleting them. Commands here operate on or across instances and typically require specifying which assistant to target.
+
+This contrasts with `assistant/src/cli/`, where commands are scoped to a **single running assistant** and operate on its local state (config, memory, contacts, etc.).
+
+## When a command belongs here vs `assistant/src/cli/`
+
+| `cli/` (this package)                           | `assistant/src/cli/`                                |
+| ----------------------------------------------- | --------------------------------------------------- |
+| Operates on or across assistant instances       | Operates within a single assistant's workspace      |
+| Manages lifecycle (create, start, stop, delete) | Manages instance-local state (config, memory, etc.) |
+| Requires specifying which assistant to target   | Implicitly scoped to the running assistant          |
+| Works without an assistant process running      | May require or start the daemon                     |
+
+Examples: `hatch`, `wake`, `sleep`, `retire`, `ps`, `ssh` belong here. `config`, `contacts`, `memory` belong in `assistant/src/cli/`.
+
+## Assistant targeting convention
+
+Commands that act on a specific assistant should accept an assistant name or ID as an argument. When none is specified, default to the most recently created local assistant. Use `loadAllAssistants()` and `findAssistantByName()` from `lib/assistant-config` for resolution.
+
+## Conventions
+
+- Commands are standalone exported functions in `src/commands/`.
+- Each command manually parses `process.argv.slice(3)` (no framework — keep it lightweight).
+- Register new commands in the `commands` object in `src/index.ts` and add a help line.
+- User-facing output uses `console.log`/`console.error` directly (no shared logger).
+
+## Help Text Standards
+
+Every command must have high-quality `--help` output optimized for AI/LLM
+consumption. Help text is a primary interface — both humans and AI agents read
+it to understand what a command does and how to use it.
+
+### Requirements
+
+1. **Each command**: Include a concise one-liner description in the help output,
+   followed by an explanation of arguments/options with their formats and
+   constraints.
+
+2. **Include examples**: Show 2-3 concrete invocations with realistic values.
+
+3. **Write for machines**: Be precise about formats, constraints, and side effects.
+   AI agents parse help text to decide which command to run and how. Avoid vague
+   language — say exactly what the command does and where state is stored.

package/package.json

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

package/src/index.ts

@@ -7,11 +7,7 @@ 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 { pair } from "./commands/pair";
@@ -25,11 +21,7 @@ import { tunnel } from "./commands/tunnel";
 import { wake } from "./commands/wake";
 
 const commands = {
-  autonomy,
   client,
-  config,
-  contacts,
-  email,
   hatch,
   login,
   logout,
@@ -88,8 +80,8 @@ async function main() {
     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("  contacts Manage assistant contacts");
+    console.log("  email    Email operations (provider-agnostic)");
     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");

package/src/lib/local.ts

@@ -701,6 +701,7 @@ export async function startLocalDaemon(watch: boolean = false): Promise<void> {
         "VELLUM_DAEMON_TCP_PORT",
         "VELLUM_DAEMON_TCP_HOST",
         "VELLUM_DAEMON_SOCKET",
+        "VELLUM_KEYCHAIN_BROKER_SOCKET",
         "VELLUM_DEBUG",
         "SENTRY_DSN",
         "TMPDIR",

package/src/lib/ngrok.ts

@@ -1,8 +1,31 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
-import { loadRawConfig, saveRawConfig } from "./config";
 import { GATEWAY_PORT } from "./constants";
 
+function getConfigPath(): string {
+  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
+  return join(root, "workspace", "config.json");
+}
+
+function loadRawConfig(): Record<string, unknown> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) return {};
+  return JSON.parse(readFileSync(configPath, "utf-8")) 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");
+}
+
 const NGROK_API_URL = "http://127.0.0.1:4040/api/tunnels";
 const NGROK_POLL_INTERVAL_MS = 500;
 const NGROK_POLL_TIMEOUT_MS = 15_000;

package/src/commands/autonomy.ts

@@ -1,320 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-
-// ---------------------------------------------------------------------------
-// Types & constants (ported from assistant/src/autonomy/types.ts)
-// ---------------------------------------------------------------------------
-
-type AutonomyTier = "auto" | "draft" | "notify";
-
-const AUTONOMY_TIERS: readonly AutonomyTier[] = ["auto", "draft", "notify"];
-
-interface AutonomyConfig {
-  defaultTier: AutonomyTier;
-  channelDefaults: Record<string, AutonomyTier>;
-  categoryOverrides: Record<string, AutonomyTier>;
-  contactOverrides: Record<string, AutonomyTier>;
-}
-
-const DEFAULT_AUTONOMY_CONFIG: AutonomyConfig = {
-  defaultTier: "notify",
-  channelDefaults: {},
-  categoryOverrides: {},
-  contactOverrides: {},
-};
-
-// ---------------------------------------------------------------------------
-// Config persistence (ported from assistant/src/autonomy/autonomy-store.ts)
-// ---------------------------------------------------------------------------
-
-function getConfigPath(): string {
-  const root = join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-  return join(root, "workspace", "autonomy.json");
-}
-
-function isValidTier(value: unknown): value is AutonomyTier {
-  return (
-    typeof value === "string" && AUTONOMY_TIERS.includes(value as AutonomyTier)
-  );
-}
-
-function validateTierRecord(raw: unknown): Record<string, AutonomyTier> {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-  const result: Record<string, AutonomyTier> = {};
-  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
-    if (isValidTier(value)) {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-function validateConfig(raw: unknown): AutonomyConfig {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    return structuredClone(DEFAULT_AUTONOMY_CONFIG);
-  }
-  const obj = raw as Record<string, unknown>;
-  return {
-    defaultTier: isValidTier(obj.defaultTier)
-      ? obj.defaultTier
-      : DEFAULT_AUTONOMY_CONFIG.defaultTier,
-    channelDefaults: validateTierRecord(obj.channelDefaults),
-    categoryOverrides: validateTierRecord(obj.categoryOverrides),
-    contactOverrides: validateTierRecord(obj.contactOverrides),
-  };
-}
-
-function loadConfig(): AutonomyConfig {
-  const configPath = getConfigPath();
-  if (!existsSync(configPath)) {
-    return structuredClone(DEFAULT_AUTONOMY_CONFIG);
-  }
-  try {
-    const raw = readFileSync(configPath, "utf-8");
-    return validateConfig(JSON.parse(raw));
-  } catch {
-    console.error("Warning: failed to parse autonomy config; using defaults");
-    return structuredClone(DEFAULT_AUTONOMY_CONFIG);
-  }
-}
-
-function saveConfig(config: AutonomyConfig): void {
-  const configPath = getConfigPath();
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
-function applyUpdate(updates: Partial<AutonomyConfig>): AutonomyConfig {
-  const current = loadConfig();
-  if (updates.defaultTier !== undefined) {
-    current.defaultTier = updates.defaultTier;
-  }
-  if (updates.channelDefaults !== undefined) {
-    current.channelDefaults = {
-      ...current.channelDefaults,
-      ...updates.channelDefaults,
-    };
-  }
-  if (updates.categoryOverrides !== undefined) {
-    current.categoryOverrides = {
-      ...current.categoryOverrides,
-      ...updates.categoryOverrides,
-    };
-  }
-  if (updates.contactOverrides !== undefined) {
-    current.contactOverrides = {
-      ...current.contactOverrides,
-      ...updates.contactOverrides,
-    };
-  }
-  saveConfig(current);
-  return current;
-}
-
-// ---------------------------------------------------------------------------
-// Output helpers
-// ---------------------------------------------------------------------------
-
-function output(data: unknown, json: boolean): void {
-  process.stdout.write(
-    json ? JSON.stringify(data) + "\n" : JSON.stringify(data, null, 2) + "\n",
-  );
-}
-
-function formatConfigForHuman(config: AutonomyConfig): string {
-  const lines: string[] = [`  Default tier: ${config.defaultTier}`];
-
-  const channelEntries = Object.entries(config.channelDefaults);
-  if (channelEntries.length > 0) {
-    lines.push("  Channel defaults:");
-    for (const [channel, tier] of channelEntries) {
-      lines.push(`    ${channel}: ${tier}`);
-    }
-  } else {
-    lines.push("  Channel defaults: (none)");
-  }
-
-  const categoryEntries = Object.entries(config.categoryOverrides);
-  if (categoryEntries.length > 0) {
-    lines.push("  Category overrides:");
-    for (const [category, tier] of categoryEntries) {
-      lines.push(`    ${category}: ${tier}`);
-    }
-  } else {
-    lines.push("  Category overrides: (none)");
-  }
-
-  const contactEntries = Object.entries(config.contactOverrides);
-  if (contactEntries.length > 0) {
-    lines.push("  Contact overrides:");
-    for (const [contactId, tier] of contactEntries) {
-      lines.push(`    ${contactId}: ${tier}`);
-    }
-  } else {
-    lines.push("  Contact overrides: (none)");
-  }
-
-  return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Arg parsing helpers
-// ---------------------------------------------------------------------------
-
-function hasFlag(args: string[], flag: string): boolean {
-  return args.includes(flag);
-}
-
-function getFlagValue(args: string[], flag: string): string | undefined {
-  const idx = args.indexOf(flag);
-  if (idx === -1 || idx + 1 >= args.length) return undefined;
-  return args[idx + 1];
-}
-
-// ---------------------------------------------------------------------------
-// Usage
-// ---------------------------------------------------------------------------
-
-function printUsage(): void {
-  console.log("Usage: vellum autonomy <subcommand> [options]");
-  console.log("");
-  console.log("Subcommands:");
-  console.log(
-    "  get                              Show current autonomy configuration",
-  );
-  console.log("  set --default <tier>             Set the global default tier");
-  console.log("  set --channel <ch> --tier <t>    Set tier for a channel");
-  console.log("  set --category <cat> --tier <t>  Set tier for a category");
-  console.log("  set --contact <id> --tier <t>    Set tier for a contact");
-  console.log("");
-  console.log("Options:");
-  console.log("  --json    Machine-readable JSON output");
-  console.log("");
-  console.log("Tiers: auto, draft, notify");
-}
-
-// ---------------------------------------------------------------------------
-// Command entry point
-// ---------------------------------------------------------------------------
-
-export function autonomy(): 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 "get": {
-      const config = loadConfig();
-      if (json) {
-        output({ ok: true, config }, true);
-      } else {
-        process.stdout.write("Autonomy configuration:\n\n");
-        process.stdout.write(formatConfigForHuman(config) + "\n");
-      }
-      break;
-    }
-
-    case "set": {
-      const defaultTier = getFlagValue(args, "--default");
-      const channel = getFlagValue(args, "--channel");
-      const category = getFlagValue(args, "--category");
-      const contact = getFlagValue(args, "--contact");
-      const tier = getFlagValue(args, "--tier");
-
-      if (defaultTier) {
-        if (!isValidTier(defaultTier)) {
-          output(
-            {
-              ok: false,
-              error: `Invalid tier "${defaultTier}". Must be one of: ${AUTONOMY_TIERS.join(", ")}`,
-            },
-            true,
-          );
-          process.exitCode = 1;
-          return;
-        }
-        const config = applyUpdate({ defaultTier });
-        if (json) {
-          output({ ok: true, config }, true);
-        } else {
-          console.log(`Set global default tier to "${defaultTier}".`);
-        }
-        return;
-      }
-
-      if (!tier) {
-        output(
-          {
-            ok: false,
-            error: "Missing --tier. Use --tier <auto|draft|notify>.",
-          },
-          true,
-        );
-        process.exitCode = 1;
-        return;
-      }
-      if (!isValidTier(tier)) {
-        output(
-          {
-            ok: false,
-            error: `Invalid tier "${tier}". Must be one of: ${AUTONOMY_TIERS.join(", ")}`,
-          },
-          true,
-        );
-        process.exitCode = 1;
-        return;
-      }
-
-      if (channel) {
-        const config = applyUpdate({ channelDefaults: { [channel]: tier } });
-        if (json) {
-          output({ ok: true, config }, true);
-        } else {
-          console.log(`Set channel "${channel}" default to "${tier}".`);
-        }
-        return;
-      }
-
-      if (category) {
-        const config = applyUpdate({
-          categoryOverrides: { [category]: tier },
-        });
-        if (json) {
-          output({ ok: true, config }, true);
-        } else {
-          console.log(`Set category "${category}" override to "${tier}".`);
-        }
-        return;
-      }
-
-      if (contact) {
-        const config = applyUpdate({ contactOverrides: { [contact]: tier } });
-        if (json) {
-          output({ ok: true, config }, true);
-        } else {
-          console.log(`Set contact "${contact}" override to "${tier}".`);
-        }
-        return;
-      }
-
-      console.error(
-        "Specify one of: --default <tier>, --channel <channel> --tier <tier>, " +
-          "--category <category> --tier <tier>, or --contact <contactId> --tier <tier>.",
-      );
-      process.exitCode = 1;
-      break;
-    }
-
-    default: {
-      console.error(`Unknown autonomy subcommand: ${subcommand}`);
-      printUsage();
-      process.exit(1);
-    }
-  }
-}

package/src/commands/config.ts

@@ -1,178 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-
-import { syncConfigToLockfile } from "../lib/assistant-config";
-import {
-  getAllowlistPath,
-  getNestedValue,
-  loadRawConfig,
-  saveRawConfig,
-  setNestedValue,
-} from "../lib/config";
-
-interface AllowlistConfig {
-  values?: string[];
-  prefixes?: string[];
-  patterns?: string[];
-}
-
-interface AllowlistValidationError {
-  index: number;
-  pattern: string;
-  message: string;
-}
-
-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);
-      syncConfigToLockfile();
-      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/contacts.ts

@@ -1,241 +0,0 @@
-import { loadLatestAssistant } from "../lib/assistant-config";
-import { GATEWAY_PORT } from "../lib/constants.js";
-
-// ---------------------------------------------------------------------------
-// Gateway API client
-// ---------------------------------------------------------------------------
-
-function getGatewayUrl(): string {
-  const entry = loadLatestAssistant();
-  if (entry?.runtimeUrl) return entry.runtimeUrl;
-  return `http://localhost:${GATEWAY_PORT}`;
-}
-
-function getBearerToken(): string | undefined {
-  const entry = loadLatestAssistant();
-  return entry?.bearerToken;
-}
-
-function buildHeaders(): Record<string, string> {
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-  };
-  const token = getBearerToken();
-  if (token) {
-    headers["Authorization"] = `Bearer ${token}`;
-  }
-  return headers;
-}
-
-async function apiGet(path: string): Promise<unknown> {
-  const url = `${getGatewayUrl()}/v1/${path}`;
-  const response = await fetch(url, { headers: buildHeaders() });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`API error ${response.status}: ${text}`);
-  }
-  return response.json();
-}
-
-async function apiPost(path: string, body: unknown): Promise<unknown> {
-  const url = `${getGatewayUrl()}/v1/${path}`;
-  const response = await fetch(url, {
-    method: "POST",
-    headers: buildHeaders(),
-    body: JSON.stringify(body),
-  });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`API error ${response.status}: ${text}`);
-  }
-  return response.json();
-}
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-interface ContactChannel {
-  type: string;
-  address: string;
-  isPrimary: boolean;
-}
-
-interface Contact {
-  id: string;
-  displayName: string;
-  notes: string | null;
-  lastInteraction: number | null;
-  interactionCount: number;
-  channels: ContactChannel[];
-}
-
-// ---------------------------------------------------------------------------
-// Output helpers
-// ---------------------------------------------------------------------------
-
-function hasFlag(args: string[], flag: string): boolean {
-  return args.includes(flag);
-}
-
-function getFlagValue(args: string[], flag: string): string | undefined {
-  const idx = args.indexOf(flag);
-  if (idx === -1 || idx + 1 >= args.length) return undefined;
-  return args[idx + 1];
-}
-
-function formatContact(c: Contact): string {
-  const lines = [
-    `  ID:           ${c.id}`,
-    `  Name:         ${c.displayName}`,
-    `  Notes:        ${c.notes ?? "(none)"}`,
-    `  Interactions: ${c.interactionCount}`,
-  ];
-  if (c.lastInteraction) {
-    lines.push(`  Last seen:    ${new Date(c.lastInteraction).toISOString()}`);
-  }
-  if (c.channels.length > 0) {
-    lines.push("  Channels:");
-    for (const ch of c.channels) {
-      const primary = ch.isPrimary ? " (primary)" : "";
-      lines.push(`    - ${ch.type}: ${ch.address}${primary}`);
-    }
-  }
-  return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Usage
-// ---------------------------------------------------------------------------
-
-function printUsage(): void {
-  console.log("Usage: vellum contacts <subcommand> [options]");
-  console.log("");
-  console.log("Subcommands:");
-  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("");
-  console.log("Options:");
-  console.log("  --json    Machine-readable JSON output");
-}
-
-// ---------------------------------------------------------------------------
-// Command entry point
-// ---------------------------------------------------------------------------
-
-export async function contacts(): 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": {
-      const limit = getFlagValue(args, "--limit") ?? "50";
-      const role = getFlagValue(args, "--role");
-      const query = `contacts?limit=${limit}${role ? `&role=${encodeURIComponent(role)}` : ""}`;
-      const data = (await apiGet(query)) as {
-        ok: boolean;
-        contacts: Contact[];
-      };
-
-      if (json) {
-        console.log(JSON.stringify(data));
-        return;
-      }
-
-      if (data.contacts.length === 0) {
-        console.log("No contacts found.");
-        return;
-      }
-
-      console.log(`Contacts (${data.contacts.length}):\n`);
-      for (const c of data.contacts) {
-        console.log(formatContact(c) + "\n");
-      }
-      break;
-    }
-
-    case "get": {
-      const id = args[1];
-      if (!id || id.startsWith("--")) {
-        console.error("Usage: vellum contacts get <id>");
-        process.exit(1);
-      }
-
-      try {
-        const data = (await apiGet(`contacts/${encodeURIComponent(id)}`)) as {
-          ok: boolean;
-          contact: Contact;
-        };
-
-        if (json) {
-          console.log(JSON.stringify(data));
-        } else {
-          console.log(formatContact(data.contact));
-        }
-      } catch {
-        if (json) {
-          console.log(
-            JSON.stringify({
-              ok: false,
-              error: `Contact "${id}" not found`,
-            }),
-          );
-        } else {
-          console.error(`Contact "${id}" not found.`);
-        }
-        process.exitCode = 1;
-      }
-      break;
-    }
-
-    case "merge": {
-      const keepId = args[1];
-      const mergeId = args[2];
-      if (
-        !keepId ||
-        !mergeId ||
-        keepId.startsWith("--") ||
-        mergeId.startsWith("--")
-      ) {
-        console.error("Usage: vellum contacts merge <keepId> <mergeId>");
-        process.exit(1);
-      }
-
-      try {
-        const data = (await apiPost("contacts/merge", {
-          keepId,
-          mergeId,
-        })) as { ok: boolean; contact: Contact };
-
-        if (json) {
-          console.log(JSON.stringify(data));
-        } else {
-          console.log(`Merged contact "${mergeId}" into "${keepId}".\n`);
-          console.log(formatContact(data.contact));
-        }
-      } 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 contacts subcommand: ${subcommand}`);
-      printUsage();
-      process.exit(1);
-    }
-  }
-}

package/src/commands/email.ts

@@ -1,108 +0,0 @@
-/**
- * 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";
-import { loadLatestAssistant } from "../lib/assistant-config.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:
-  --assistant <id>      Assistant ID (defaults to the most recently hatched)
-  --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;
-  }
-
-  // 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(assistantId);
-        const addresses = await client.status();
-        output({ ok: true, addresses });
-      } 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(assistantId);
-        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/email/vellum.ts

@@ -1,97 +0,0 @@
-/**
- * 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 AssistantEmailAddress {
-  id: string;
-  address: string;
-  created_at: string;
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-  private assistantId: string;
-
-  constructor(assistantId: string, apiKey?: string, baseUrl?: string) {
-    this.assistantId = assistantId;
-    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<AssistantEmailAddress[]> {
-    const result = await vellumFetch(
-      this.apiKey,
-      this.baseUrl,
-      `/v1/assistants/${this.assistantId}/email-addresses/`,
-    );
-    return result as AssistantEmailAddress[];
-  }
-
-  /** Provision a new email address for the given username. */
-  async createInbox(username: string): Promise<AssistantEmailAddress> {
-    const result = await vellumFetch(
-      this.apiKey,
-      this.baseUrl,
-      `/v1/assistants/${this.assistantId}/email-addresses/`,
-      {
-        method: "POST",
-        body: { username },
-      },
-    );
-    return result as AssistantEmailAddress;
-  }
-}

package/src/lib/config.ts

@@ -1,73 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-
-function getRootDir(): string {
-  return join(process.env.BASE_DATA_DIR?.trim() || homedir(), ".vellum");
-}
-
-export function getConfigPath(): string {
-  return join(getRootDir(), "workspace", "config.json");
-}
-
-export function getAllowlistPath(): string {
-  return join(getRootDir(), "protected", "secret-allowlist.json");
-}
-
-export 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>;
-}
-
-export 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");
-}
-
-export 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;
-}
-
-export 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;
-}