@vellumai/cli 0.6.6 → 0.7.0

package/src/commands/env.ts

@@ -0,0 +1,93 @@
+import { SEEDS } from "../lib/environments/seeds.js";
+import {
+  clearDefaultEnvironment,
+  readDefaultEnvironment,
+  resolveEnvironmentSource,
+  writeDefaultEnvironment,
+} from "../lib/environments/resolve.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum env <subcommand>");
+  console.log("");
+  console.log("Manage the default CLI environment.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  set <name>   Set the default environment");
+  console.log("  get          Show the current environment and its source");
+  console.log("  clear        Remove the default, falling back to production");
+  console.log("");
+  console.log(`Known environments: ${Object.keys(SEEDS).join(", ")}`);
+  console.log("");
+  console.log("Examples:");
+  console.log("  $ vellum env set local    # all commands default to local");
+  console.log("  $ vellum env get          # show resolved environment");
+  console.log("  $ vellum env clear        # revert to production default");
+}
+
+function envSet(name: string | undefined): void {
+  if (!name) {
+    console.error(
+      `Usage: vellum env set <name>\nKnown environments: ${Object.keys(SEEDS).join(", ")}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!SEEDS[name]) {
+    console.error(
+      `Unknown environment "${name}". Known environments: ${Object.keys(SEEDS).join(", ")}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  writeDefaultEnvironment(name);
+  console.log(`Default environment set to "${name}".`);
+}
+
+function envGet(): void {
+  const { name, source } = resolveEnvironmentSource();
+  const sourceLabels: Record<typeof source, string> = {
+    flag: "--environment flag",
+    env: "VELLUM_ENVIRONMENT env var",
+    config: "~/.config/vellum/environment",
+    default: "default",
+  };
+  console.log(`${name} (from ${sourceLabels[source]})`);
+}
+
+function envClear(): void {
+  const current = readDefaultEnvironment();
+  if (!current) {
+    console.log("No default environment is set (already using production).");
+    return;
+  }
+  clearDefaultEnvironment();
+  console.log(
+    `Cleared default environment "${current}". Falling back to production.`,
+  );
+}
+
+export async function env(): Promise<void> {
+  const args = process.argv.slice(3);
+  const sub = args[0];
+
+  if (!sub || sub === "--help" || sub === "-h") {
+    printUsage();
+    return;
+  }
+
+  switch (sub) {
+    case "set":
+      envSet(args[1]);
+      break;
+    case "get":
+      envGet();
+      break;
+    case "clear":
+      envClear();
+      break;
+    default:
+      console.error(`Unknown subcommand: ${sub}`);
+      printUsage();
+      process.exitCode = 1;
+  }
+}

package/src/commands/events.ts

@@ -9,6 +9,7 @@
 
 import { extractFlag } from "../lib/arg-utils.js";
 import { AssistantClient } from "../lib/assistant-client.js";
+import { getClientRegistrationHeaders } from "../lib/client-identity.js";
 
 function printUsage(): void {
   console.log(`vellum events - Stream events from a running assistant
@@ -136,6 +137,7 @@ export async function events(): Promise<void> {
   for await (const event of client.stream<AssistantEvent>("/events", {
     signal: controller.signal,
     query,
+    headers: getClientRegistrationHeaders(),
   })) {
     if (jsonOutput) {
       console.log(JSON.stringify(event));

package/src/commands/exec.ts

@@ -8,7 +8,13 @@ import {
 import { dockerResourceNames } from "../lib/docker";
 import type { ServiceName } from "../lib/docker";
 import { execAppleContainer } from "../lib/exec-apple-container";
+import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
 import { sshAppleContainer } from "../lib/ssh-apple-container";
+import {
+  interactiveSession,
+  nonInteractiveExec,
+  shellEscapeArgs,
+} from "../lib/terminal-session";
 
 const SERVICE_ALIASES: Record<string, ServiceName> = {
   assistant: "assistant",
@@ -74,11 +80,12 @@ export async function exec(): Promise<void> {
     );
     console.log("");
     console.log("Options:");
+    console.log("  --service <svc>     Target service (default: assistant)");
     console.log(
-      "  --service <svc>     Target service (default: assistant)",
+      "  -it                 Interactive mode with TTY (like docker exec -it)",
     );
     console.log(
-      "  -it                 Interactive mode with TTY (like docker exec -it)",
+      "  --verbose           Show debug output (SSE events, sentinel parsing)",
     );
     console.log("");
     console.log("Services:");
@@ -90,9 +97,7 @@ export async function exec(): Promise<void> {
     console.log("  vellum exec -- ls -la /workspace");
     console.log("  vellum exec -- cat /workspace/NOW.md");
     console.log("  vellum exec -it -- /bin/bash");
-    console.log(
-      "  vellum exec --service gateway -- cat /tmp/gateway.log",
-    );
+    console.log("  vellum exec --service gateway -- cat /tmp/gateway.log");
     process.exit(0);
   }
 
@@ -114,12 +119,15 @@ export async function exec(): Promise<void> {
   let nameArg: string | undefined;
   let serviceRaw = "assistant";
   let interactive = false;
+  let verbose = false;
 
   for (let i = 0; i < preArgs.length; i++) {
     if (preArgs[i] === "--service" && preArgs[i + 1]) {
       serviceRaw = preArgs[++i];
     } else if (preArgs[i] === "-it" || preArgs[i] === "-ti") {
       interactive = true;
+    } else if (preArgs[i] === "--verbose") {
+      verbose = true;
     } else if (!preArgs[i].startsWith("-")) {
       nameArg = preArgs[i];
     }
@@ -127,9 +135,7 @@ export async function exec(): Promise<void> {
 
   const service = normalizeService(serviceRaw);
 
-  const entry = nameArg
-    ? findAssistantByName(nameArg)
-    : loadLatestAssistant();
+  const entry = nameArg ? findAssistantByName(nameArg) : loadLatestAssistant();
 
   if (!entry) {
     if (nameArg) {
@@ -179,6 +185,32 @@ export async function exec(): Promise<void> {
     return;
   }
 
+  if (cloud === "vellum") {
+    const token = readPlatformToken();
+    if (!token) {
+      console.error(
+        "Not logged in. Run `vellum login` first to authenticate with the platform.",
+      );
+      process.exit(1);
+    }
+
+    const assistant = {
+      assistantId: entry.assistantId,
+      token,
+      platformUrl: getPlatformUrl(),
+    };
+
+    if (interactive) {
+      // Interactive mode: shell-escape argv and delegate to full terminal
+      await interactiveSession(assistant, shellEscapeArgs(command));
+      return;
+    }
+
+    // Non-interactive: sentinel-based output capture with exit code
+    await nonInteractiveExec(assistant, command, { verbose });
+    return;
+  }
+
   console.error(
     `Error: 'vellum exec' is not supported for ${cloud} instances.`,
   );

package/src/commands/hatch.ts

@@ -15,7 +15,7 @@ import {
   VALID_SPECIES,
 } from "../lib/constants";
 import type { RemoteHost, Species } from "../lib/constants";
-import { buildNestedConfig } from "../lib/config-utils";
+import { buildInitialConfig } from "../lib/config-utils";
 import { hatchDocker } from "../lib/docker";
 import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
@@ -123,7 +123,11 @@ export async function buildStartupScript(
   // and export the env var so the daemon reads it on first boot.
   let configWriteBlock = "";
   if (Object.keys(configValues).length > 0) {
-    const configJson = JSON.stringify(buildNestedConfig(configValues), null, 2);
+    const configJson = JSON.stringify(
+      buildInitialConfig(configValues),
+      null,
+      2,
+    );
     configWriteBlock = `
 echo "Writing default workspace config..."
 VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH="/tmp/vellum-initial-config-$$.json"

package/src/commands/login.ts

@@ -6,6 +6,10 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadLatestAssistant,
+  loadAllAssistants,
+  removeAssistantEntry,
+  saveAssistantEntry,
+  setActiveAssistant,
 } from "../lib/assistant-config";
 import { computeDeviceId } from "../lib/guardian-token";
 import {
@@ -13,7 +17,9 @@ import {
   ensureSelfHostedLocalRegistration,
   fetchCurrentUser,
   fetchOrganizationId,
+  fetchPlatformAssistants,
   getPlatformUrl,
+  getWebUrl,
   injectCredentialsIntoAssistant,
   readGatewayCredential,
   readPlatformToken,
@@ -45,7 +51,7 @@ function openBrowser(url: string): void {
  * Start a local HTTP server, open the browser to the platform login page,
  * and wait for the platform to redirect back with the session token.
  */
-function browserLogin(platformUrl: string): Promise<string> {
+function browserLogin(webUrl: string): Promise<string> {
   return new Promise((resolve, reject) => {
     const state = randomBytes(32).toString("hex");
 
@@ -112,7 +118,7 @@ function browserLogin(platformUrl: string): Promise<string> {
 
       const port = addr.port;
       const returnTo = `/accounts/cli/callback?port=${port}&state=${state}`;
-      const loginUrl = `${platformUrl}/account/login?returnTo=${encodeURIComponent(returnTo)}`;
+      const loginUrl = `${webUrl}/account/login?returnTo=${encodeURIComponent(returnTo)}`;
 
       console.log("Opening browser for login...");
       console.log(`If the browser doesn't open, visit: ${loginUrl}`);
@@ -125,22 +131,30 @@ export async function login(): Promise<void> {
   const args = process.argv.slice(3);
 
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum login [--token <session-token>]");
+    console.log("Usage: vellum login [--token <session-token>] [--force]");
     console.log("");
     console.log("Log in to the Vellum platform.");
     console.log("");
     console.log("By default, opens a browser window for authentication.");
     console.log("Alternatively, pass a session token directly with --token.");
     console.log("");
+    console.log("On success, syncs cloud-managed assistants to the local");
+    console.log("lockfile so they appear in `vellum ps`.");
+    console.log("");
     console.log("Options:");
     console.log("  --token <token>    Session token from the Vellum platform");
+    console.log(
+      "  --force, -f        Re-authenticate even if already logged in",
+    );
     console.log("");
     console.log("Examples:");
     console.log("  vellum login");
     console.log("  vellum login --token <session-token>");
+    console.log("  vellum login --force");
     process.exit(0);
   }
 
+  const forceFlag = args.includes("--force") || args.includes("-f");
   let token: string | null = null;
 
   for (let i = 0; i < args.length; i++) {
@@ -154,11 +168,27 @@ export async function login(): Promise<void> {
     }
   }
 
+  // Block if already authenticated (unless --force)
+  if (!forceFlag && !token) {
+    const existingToken = readPlatformToken();
+    if (existingToken) {
+      try {
+        const existingUser = await fetchCurrentUser(existingToken);
+        console.error(
+          `Already logged in as ${existingUser.email}. Run \`vellum logout\` first, or use \`vellum login --force\` to re-authenticate.`,
+        );
+        process.exit(1);
+      } catch {
+        // Token is stale/invalid — proceed with login
+      }
+    }
+  }
+
   // If no --token flag, use browser-based login
   if (!token) {
-    const platformUrl = getPlatformUrl();
+    const webUrl = getWebUrl();
     try {
-      token = await browserLogin(platformUrl);
+      token = await browserLogin(webUrl);
     } catch (error) {
       console.error(`❌ ${error instanceof Error ? error.message : error}`);
       process.exit(1);
@@ -247,6 +277,45 @@ export async function login(): Promise<void> {
     } catch {
       // Non-fatal — login succeeded even if registration fails
     }
+
+    // Sync cloud assistants from the platform into the local lockfile.
+    // This ensures `vellum ps` shows managed assistants immediately
+    // after login (e.g. after a retire-and-rehatch cycle).
+    try {
+      const platformAssistants = await fetchPlatformAssistants(token);
+      const existingIds = new Set(
+        loadAllAssistants()
+          .filter((a) => a.cloud === "vellum")
+          .map((a) => a.assistantId),
+      );
+
+      let synced = 0;
+      for (const pa of platformAssistants) {
+        if (!existingIds.has(pa.id)) {
+          saveAssistantEntry({
+            assistantId: pa.id,
+            runtimeUrl: getPlatformUrl(),
+            cloud: "vellum",
+            species: "vellum",
+            hatchedAt: new Date().toISOString(),
+          });
+          synced++;
+        }
+      }
+
+      if (synced > 0) {
+        console.log(
+          `Synced ${synced} cloud assistant${synced > 1 ? "s" : ""} to local lockfile.`,
+        );
+      }
+
+      // If no active assistant is set, activate the first cloud one.
+      if (!getActiveAssistant() && platformAssistants.length > 0) {
+        setActiveAssistant(platformAssistants[0].id);
+      }
+    } catch {
+      // Non-fatal — login succeeded even if sync fails
+    }
   } catch (error) {
     console.error(
       `❌ Login failed: ${error instanceof Error ? error.message : error}`,
@@ -261,11 +330,25 @@ export async function logout(): Promise<void> {
     console.log("Usage: vellum logout");
     console.log("");
     console.log(
-      "Log out of the Vellum platform and remove the stored session token.",
+      "Log out of the Vellum platform, remove the stored session token,",
     );
+    console.log("and remove cloud-managed assistants from the local lockfile.");
     process.exit(0);
   }
 
+  // Remove cloud-managed assistants from the lockfile.
+  const cloudAssistants = loadAllAssistants().filter(
+    (a) => a.cloud === "vellum",
+  );
+  for (const a of cloudAssistants) {
+    removeAssistantEntry(a.assistantId);
+  }
+  if (cloudAssistants.length > 0) {
+    console.log(
+      `Removed ${cloudAssistants.length} cloud assistant${cloudAssistants.length > 1 ? "s" : ""} from local lockfile.`,
+    );
+  }
+
   clearPlatformToken();
   console.log("Logged out. Platform token removed.");
 }

package/src/commands/ps.ts

@@ -3,11 +3,18 @@ import { join } from "path";
 import {
   findAssistantByName,
   getActiveAssistant,
+  getDaemonPidPath,
   loadAllAssistants,
   type AssistantEntry,
 } from "../lib/assistant-config";
+import { resolveEnvironmentSource } from "../lib/environments/resolve";
 import { loadGuardianToken } from "../lib/guardian-token";
-import { checkHealth, checkManagedHealth } from "../lib/health-check";
+import {
+  checkHealth,
+  checkManagedHealth,
+  fetchManagedPs,
+  type ManagedProcessEntry,
+} from "../lib/health-check";
 import { dockerResourceNames } from "../lib/docker";
 import { existsSync } from "fs";
 import {
@@ -65,6 +72,49 @@ function printTable(rows: TableRow[]): void {
   }
 }
 
+// ── Managed process tree rendering ──────────────────────────────
+
+const STATUS_LABELS: Record<ManagedProcessEntry["status"], string> = {
+  running: "running",
+  not_running: "not running",
+  unreachable: "unreachable",
+};
+
+function flattenProcessTree(
+  entries: ManagedProcessEntry[],
+  depth = 0,
+): TableRow[] {
+  const rows: TableRow[] = [];
+  for (const entry of entries) {
+    const children = entry.children ?? [];
+
+    rows.push({
+      name:
+        depth === 0 ? entry.name : `${"  ".repeat(depth - 1)}├─ ${entry.name}`,
+      status: withStatusEmoji(STATUS_LABELS[entry.status]),
+      info: entry.info ?? "",
+    });
+
+    for (let j = 0; j < children.length; j++) {
+      const child = children[j];
+      const isLast = j === children.length - 1;
+      const prefix = `${"  ".repeat(depth)}${isLast ? "└─" : "├─"} ${child.name}`;
+      rows.push({
+        name: prefix,
+        status: withStatusEmoji(STATUS_LABELS[child.status]),
+        info: child.info ?? "",
+      });
+
+      // Recurse into grandchildren
+      const grandchildren = child.children ?? [];
+      if (grandchildren.length > 0) {
+        rows.push(...flattenProcessTree(grandchildren, depth + 2));
+      }
+    }
+  }
+  return rows;
+}
+
 // ── Remote process listing via SSH ──────────────────────────────
 
 const SSH_OPTS = [
@@ -215,37 +265,38 @@ async function getLocalProcesses(entry: AssistantEntry): Promise<TableRow[]> {
   const resources = entry.resources;
   const vellumDir = join(resources.instanceDir, ".vellum");
 
-  const specs: ProcessSpec[] = [
-    {
-      name: "assistant",
-      pgrepName: "vellum-daemon",
-      port: resources.daemonPort,
-      pidFile: resources.pidFile,
-    },
+  const assistantSpec: ProcessSpec = {
+    name: "assistant",
+    pgrepName: "vellum-daemon",
+    port: resources.daemonPort,
+    pidFile: getDaemonPidPath(resources),
+  };
+  const subSpecs: ProcessSpec[] = [
     {
-      name: "qdrant",
+      name: "├─ qdrant",
       pgrepName: "qdrant",
       port: resources.qdrantPort,
       pidFile: join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"),
     },
     {
-      name: "gateway",
-      pgrepName: "vellum-gateway",
-      port: resources.gatewayPort,
-      pidFile: join(vellumDir, "gateway.pid"),
-    },
-    {
-      name: "embed-worker",
+      name: "└─ embed-worker",
       pgrepName: "embed-worker",
       port: 0,
       pidFile: join(vellumDir, "workspace", "embed-worker.pid"),
     },
   ];
+  const gatewaySpec: ProcessSpec = {
+    name: "gateway",
+    pgrepName: "vellum-gateway",
+    port: resources.gatewayPort,
+    pidFile: join(vellumDir, "gateway.pid"),
+  };
 
-  const results = await Promise.all(specs.map(detectProcess));
+  const allSpecs = [assistantSpec, ...subSpecs, gatewaySpec];
+  const results = await Promise.all(allSpecs.map(detectProcess));
 
-  return results.map((proc) => ({
-    name: proc.name,
+  return results.map((proc, i) => ({
+    name: allSpecs[i].name,
     status: withStatusEmoji(proc.running ? "running" : "not running"),
     info: proc.running ? formatDetectionInfo(proc) : "not detected",
   }));
@@ -335,6 +386,28 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
     return;
   }
 
+  if (cloud === "vellum") {
+    console.log(`  Platform ID: ${entry.assistantId}\n`);
+
+    const psData = await fetchManagedPs(entry.runtimeUrl, entry.assistantId);
+
+    if (!psData) {
+      const rows: TableRow[] = [
+        {
+          name: "assistant",
+          status: withStatusEmoji("unreachable"),
+          info: "could not reach platform API — run `vellum login`",
+        },
+      ];
+      printTable(rows);
+      return;
+    }
+
+    const rows = flattenProcessTree(psData.processes);
+    printTable(rows);
+    return;
+  }
+
   if (cloud === "apple-container") {
     const mgmtSocket = entry.mgmtSocket as string | undefined;
     const socketAlive = mgmtSocket ? existsSync(mgmtSocket) : false;
@@ -396,6 +469,15 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
 // ── List all assistants (no arg) ────────────────────────────────
 
 async function listAllAssistants(): Promise<void> {
+  const { name: envName, source: envSource } = resolveEnvironmentSource();
+  const sourceLabels: Record<typeof envSource, string> = {
+    flag: "--environment flag",
+    env: "VELLUM_ENVIRONMENT",
+    config: "~/.config/vellum/environment",
+    default: "default",
+  };
+  console.log(`Environment: ${envName} (${sourceLabels[envSource]})\n`);
+
   const assistants = loadAllAssistants();
   const activeId = getActiveAssistant();
 
@@ -454,7 +536,9 @@ async function listAllAssistants(): Promise<void> {
       let health: { status: string; detail: string | null; version?: string };
       const resources = a.resources;
       if (a.cloud === "local" && resources) {
-        const pid = readPidFile(resources.pidFile);
+        // TODO(ATL-306): Remove readPidFile/getDaemonPidPath in favor of
+        // fetching daemon PIDs via the health API (Gateway Security Migration).
+        const pid = readPidFile(getDaemonPidPath(resources));
         const alive = pid !== null && isProcessAlive(pid);
         if (!alive) {
           health = { status: "sleeping", detail: null };

package/src/commands/sleep.ts

@@ -1,7 +1,10 @@
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 
-import { resolveTargetAssistant } from "../lib/assistant-config.js";
+import {
+  getDaemonPidPath,
+  resolveTargetAssistant,
+} from "../lib/assistant-config.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
 import { dockerResourceNames, sleepContainers } from "../lib/docker.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
@@ -93,7 +96,7 @@ export async function sleep(): Promise<void> {
     process.exit(1);
   }
   const resources = entry.resources;
-  const assistantPidFile = resources.pidFile;
+  const assistantPidFile = getDaemonPidPath(resources);
   const vellumDir = getAssistantRootDir(entry);
   const gatewayPidFile = join(vellumDir, "gateway.pid");
 

package/src/commands/ssh.ts

@@ -6,7 +6,9 @@ import {
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
+import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
 import { sshAppleContainer } from "../lib/ssh-apple-container";
+import { interactiveSession } from "../lib/terminal-session";
 
 const SSH_OPTS = [
   "-o",
@@ -121,8 +123,19 @@ export async function ssh(): Promise<void> {
       { stdio: "inherit" },
     );
   } else if (cloud === "vellum") {
-    console.error("SSH to Vellum-managed instances is not yet supported.");
-    process.exit(1);
+    const token = readPlatformToken();
+    if (!token) {
+      console.error(
+        "Not logged in. Run `vellum login` first to authenticate with the platform.",
+      );
+      process.exit(1);
+    }
+    await interactiveSession({
+      assistantId: entry.assistantId,
+      token,
+      platformUrl: getPlatformUrl(),
+    });
+    return;
   } else if (cloud === "custom") {
     const host = extractHostFromUrl(entry.runtimeUrl);
     const sshUser = entry.sshUser ?? "root";