@vellumai/cli 0.8.5 → 0.8.6

package/src/commands/client.ts

@@ -278,18 +278,29 @@ async function maybeHydratePlatformAssistantName(
   }
 }
 
+const SPA_BASE = "/assistant/";
+
 /**
- * Walk up from this file's location to find a sibling `clients/web` package.
+ * Locate the pre-built @vellumai/web dist directory.
  *
- * Returns the absolute path to its directory, or null when not found —
- * e.g. when the CLI is installed via npm/bunx, where the `clients/web`
- * source isn't shipped alongside `@vellumai/cli`. For now we treat the
- * `--interface web` path as source-checkout-only.
+ * Resolution order:
+ *   1. npm-installed package — require.resolve('@vellumai/web/package.json')
+ *   2. Source checkout — walk up from cli/ to find apps/web/dist/
  */
-function findClientsWebDir(): string | null {
+function findWebDistDir(): string | null {
+  try {
+    const pkgPath = require.resolve("@vellumai/web/package.json");
+    const distDir = path.join(path.dirname(pkgPath), "dist");
+    if (existsSync(path.join(distDir, "index.html"))) {
+      return distDir;
+    }
+  } catch {
+    // Package not installed; try source checkout.
+  }
+
   let dir = import.meta.dir;
   for (let depth = 0; depth < 8; depth++) {
-    const candidate = path.join(dir, "clients", "web", "package.json");
+    const candidate = path.join(dir, "apps", "web", "dist", "index.html");
     if (existsSync(candidate)) {
       return path.dirname(candidate);
     }
@@ -300,42 +311,61 @@ function findClientsWebDir(): string | null {
   return null;
 }
 
-/**
- * Spawn the `clients/web` package's `local` script and proxy its lifecycle.
- *
- * The web client is deliberately not declared as a dependency of `@vellumai/cli`:
- * the CLI is published, the web package is not. Locating it on disk and
- * shelling out keeps the two packages independent.
- */
 async function runWebInterface(): Promise<void> {
-  const webDir = findClientsWebDir();
-  if (!webDir) {
+  const distDir = findWebDistDir();
+  if (!distDir) {
     console.error(
       `${ANSI.bold}--interface web${ANSI.reset}: unable to locate ` +
-        `clients/web. This interface currently requires running ` +
-        `vellum from a source checkout of vellum-assistant.`,
+        `@vellumai/web assets.\n\n` +
+        `  npm/bunx install:   npm install @vellumai/web\n` +
+        `  source checkout:    cd apps/web && VITE_PLATFORM_MODE=false bun run build`,
     );
     process.exit(1);
   }
 
-  const child = Bun.spawn({
-    cmd: ["bun", "run", "local"],
-    cwd: webDir,
-    stdio: ["inherit", "inherit", "inherit"],
+  const indexHtml = await Bun.file(path.join(distDir, "index.html")).text();
+
+  const server = Bun.serve({
+    port: 3000,
+    hostname: "127.0.0.1",
+    fetch: async (req) => {
+      const url = new URL(req.url);
+      const { pathname } = url;
+
+      if (pathname === "/") {
+        return Response.redirect(SPA_BASE, 302);
+      }
+
+      if (pathname.startsWith(SPA_BASE)) {
+        const relPath = pathname.slice(SPA_BASE.length);
+        if (relPath) {
+          const filePath = path.join(distDir, relPath);
+          const file = Bun.file(filePath);
+          if (await file.exists()) {
+            return new Response(file);
+          }
+        }
+        return new Response(indexHtml, {
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
+
+      return new Response("Not Found", { status: 404 });
+    },
   });
 
-  const forward = (signal: "SIGINT" | "SIGTERM"): void => {
-    try {
-      child.kill(signal);
-    } catch {
-      // Child already exited; nothing to forward.
-    }
+  console.log(
+    `Vellum web interface: http://${server.hostname}:${server.port}${SPA_BASE}`,
+  );
+
+  const shutdown = (): void => {
+    server.stop();
+    process.exit(0);
   };
-  process.on("SIGINT", () => forward("SIGINT"));
-  process.on("SIGTERM", () => forward("SIGTERM"));
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
 
-  const exitCode = await child.exited;
-  process.exit(typeof exitCode === "number" ? exitCode : 0);
+  await new Promise(() => {});
 }
 
 export async function client(): Promise<void> {

package/src/commands/flags.ts

@@ -0,0 +1,197 @@
+import { AssistantClient } from "../lib/assistant-client.js";
+
+type FeatureFlagEntry = {
+  key: string;
+  label: string;
+  enabled: boolean;
+  defaultEnabled: boolean;
+  description: string;
+};
+
+type FlagsResponse = {
+  flags: FeatureFlagEntry[];
+};
+
+function pad(s: string, w: number): string {
+  return s + " ".repeat(Math.max(0, w - s.length));
+}
+
+function printFlagTable(flags: FeatureFlagEntry[]): void {
+  const headers = { key: "KEY", enabled: "ENABLED", default: "DEFAULT", label: "LABEL" };
+
+  const rows = flags
+    .slice()
+    .sort((a, b) => a.key.localeCompare(b.key))
+    .map((f) => ({
+      key: f.enabled !== f.defaultEnabled ? `* ${f.key}` : `  ${f.key}`,
+      enabled: String(f.enabled),
+      default: String(f.defaultEnabled),
+      label: f.label,
+    }));
+
+  const all = [headers, ...rows];
+  const colWidths = {
+    key: Math.max(...all.map((r) => r.key.length)),
+    enabled: Math.max(...all.map((r) => r.enabled.length)),
+    default: Math.max(...all.map((r) => r.default.length)),
+    label: Math.max(...all.map((r) => r.label.length)),
+  };
+
+  const formatRow = (r: typeof headers) =>
+    `${pad(r.key, colWidths.key)}  ${pad(r.enabled, colWidths.enabled)}  ${pad(r.default, colWidths.default)}  ${r.label}`;
+
+  console.log(formatRow(headers));
+  console.log(
+    `${"-".repeat(colWidths.key)}  ${"-".repeat(colWidths.enabled)}  ${"-".repeat(colWidths.default)}  ${"-".repeat(colWidths.label)}`,
+  );
+  for (const row of rows) {
+    console.log(formatRow(row));
+  }
+  console.log("");
+  console.log("* = overridden (differs from default)");
+}
+
+function printHelp(): void {
+  console.log("Usage: vellum flags [subcommand] [options]");
+  console.log("");
+  console.log("Show and toggle feature flags for the active assistant.");
+  console.log("Reads from the gateway's merged flag state (persisted overrides > remote > defaults).");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  (none)              List all feature flags in a table");
+  console.log("  get <key>           Show details for a single flag");
+  console.log("  set <key> <bool>    Set a flag override to true or false");
+  console.log("");
+  console.log("Options:");
+  console.log("  --help, -h          Show this help");
+  console.log("");
+  console.log("Examples:");
+  console.log("  $ vellum flags                                 # list all flags");
+  console.log("  $ vellum flags get query-complexity-routing     # inspect one flag");
+  console.log("  $ vellum flags set voice-mode true              # enable a flag");
+}
+
+function createClient(): AssistantClient {
+  try {
+    return new AssistantClient();
+  } catch {
+    throw new Error(
+      "No assistant found. Hatch one with 'vellum hatch' first.",
+    );
+  }
+}
+
+function rethrowFetchError(err: unknown): never {
+  if (
+    err instanceof TypeError &&
+    (err.message.includes("fetch") || err.message.includes("connect"))
+  ) {
+    throw new Error(
+      "Could not reach the assistant gateway. Is it running? Try 'vellum wake'.",
+    );
+  }
+  throw err;
+}
+
+async function listFlags(): Promise<void> {
+  const client = createClient();
+  let res: Response;
+  try {
+    res = await client.get("/feature-flags");
+  } catch (err) {
+    rethrowFetchError(err);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Failed to fetch flags: HTTP ${res.status} ${body}`.trim());
+  }
+  const data = (await res.json()) as FlagsResponse;
+  if (data.flags.length === 0) {
+    console.log("No feature flags found.");
+    return;
+  }
+  printFlagTable(data.flags);
+}
+
+async function getFlag(key: string): Promise<void> {
+  const client = createClient();
+  let res: Response;
+  try {
+    res = await client.get("/feature-flags");
+  } catch (err) {
+    rethrowFetchError(err);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Failed to fetch flags: HTTP ${res.status} ${body}`.trim());
+  }
+  const data = (await res.json()) as FlagsResponse;
+  const flag = data.flags.find((f) => f.key === key);
+  if (!flag) {
+    throw new Error(`Flag "${key}" not found.`);
+  }
+  console.log(`Key:            ${flag.key}`);
+  console.log(`Enabled:        ${flag.enabled}`);
+  console.log(`Default:        ${flag.defaultEnabled}`);
+  console.log(`Description:    ${flag.description || "(none)"}`);
+}
+
+async function setFlag(key: string, value: boolean): Promise<void> {
+  const client = createClient();
+  let res: Response;
+  try {
+    res = await client.patch(`/feature-flags/${key}`, { enabled: value });
+  } catch (err) {
+    rethrowFetchError(err);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Failed to set flag: HTTP ${res.status} ${body}`.trim());
+  }
+  console.log(`Flag "${key}" set to ${value}`);
+}
+
+export async function flags(): Promise<void> {
+  const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const subcommand = args[0];
+
+  if (!subcommand) {
+    await listFlags();
+    return;
+  }
+
+  if (subcommand === "get") {
+    const key = args[1];
+    if (!key) {
+      console.error("Usage: vellum flags get <key>");
+      process.exit(1);
+    }
+    await getFlag(key);
+    return;
+  }
+
+  if (subcommand === "set") {
+    const key = args[1];
+    const rawValue = args[2];
+    if (!key || rawValue === undefined) {
+      console.error("Usage: vellum flags set <key> <true|false>");
+      process.exit(1);
+    }
+    if (rawValue !== "true" && rawValue !== "false") {
+      console.error(`Invalid value "${rawValue}". Must be "true" or "false".`);
+      process.exit(1);
+    }
+    await setFlag(key, rawValue === "true");
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${subcommand}`);
+  printHelp();
+  process.exit(1);
+}

package/src/commands/gateway/token.ts

@@ -0,0 +1,73 @@
+import {
+  lookupAssistantByIdentifier,
+  formatAssistantLookupError,
+} from "../../lib/assistant-config.js";
+import {
+  loadGuardianToken,
+  refreshGuardianToken,
+} from "../../lib/guardian-token.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum gateway token <subcommand> <assistantId>");
+  console.log("");
+  console.log("Manage gateway authentication tokens.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  get       Print the current guardian access token");
+  console.log("  refresh   Refresh an expired access token and print it");
+}
+
+export async function gatewayToken(): Promise<void> {
+  const args = process.argv.slice(4);
+  const subcommand = args[0];
+
+  if (subcommand === "--help" || subcommand === "-h" || !subcommand) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (subcommand !== "get" && subcommand !== "refresh") {
+    console.error(`Unknown subcommand: ${subcommand}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  const assistantId = args[1];
+  if (!assistantId) {
+    console.error("Missing required argument: <assistantId>");
+    printUsage();
+    process.exit(1);
+  }
+
+  const result = lookupAssistantByIdentifier(assistantId);
+  if (result.status !== "found") {
+    console.error(formatAssistantLookupError(assistantId, result));
+    process.exit(1);
+  }
+  const entry = result.entry;
+
+  const tokenData = loadGuardianToken(entry.assistantId);
+  if (!tokenData) {
+    console.error("No guardian token found for this assistant.");
+    process.exit(1);
+  }
+
+  if (subcommand === "get") {
+    console.log(tokenData.accessToken);
+    return;
+  }
+
+  const gatewayUrl = entry.localUrl || entry.runtimeUrl;
+  if (!gatewayUrl) {
+    console.error("No gateway URL found for this assistant.");
+    process.exit(1);
+  }
+
+  const refreshed = await refreshGuardianToken(gatewayUrl, entry.assistantId);
+  if (!refreshed) {
+    console.error("Failed to refresh guardian token.");
+    process.exit(1);
+  }
+
+  console.log(refreshed.accessToken);
+}

package/src/commands/gateway.ts

@@ -0,0 +1,29 @@
+import { gatewayToken } from "./gateway/token.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum gateway <subcommand>");
+  console.log("");
+  console.log("Gateway management commands.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  token    Manage gateway authentication tokens");
+}
+
+export async function gateway(): Promise<void> {
+  const args = process.argv.slice(3);
+  const subcommand = args[0];
+
+  if (subcommand === "--help" || subcommand === "-h" || !subcommand) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (subcommand === "token") {
+    await gatewayToken();
+    return;
+  }
+
+  console.error(`Unknown subcommand: ${subcommand}`);
+  printUsage();
+  process.exit(1);
+}

package/src/commands/logs.ts

@@ -4,8 +4,12 @@ import { createInterface } from "readline";
 import { watch } from "fs";
 import { join } from "path";
 
-import { resolveAssistant } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
+import {
+  extractHostFromUrl,
+  resolveAssistant,
+  resolveCloud,
+  type AssistantEntry,
+} from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import { getLogDir } from "../lib/xdg-log";
 import { execOutput } from "../lib/step-runner";
@@ -112,13 +116,6 @@ function parseArgs(): LogsArgs {
 
 // ── Helpers ─────────────────────────────────────────────────────
 
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) return entry.cloud;
-  if (entry.project) return "gcp";
-  if (entry.sshUser) return "custom";
-  return "local";
-}
-
 /**
  * Parse a relative time string like "10m", "2h", "30s" into a Date.
  * Returns null if the string doesn't look like a relative time.
@@ -494,15 +491,6 @@ async function showGcpLogs(
   }
 }
 
-function extractHostFromUrl(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname;
-  } catch {
-    return url.replace(/^https?:\/\//, "").split(":")[0];
-  }
-}
-
 async function showCustomLogs(
   entry: AssistantEntry,
   opts: LogsArgs,

package/src/commands/ps.ts

@@ -1,6 +1,7 @@
 import { join } from "path";
 
 import {
+  extractHostFromUrl,
   findAssistantByName,
   formatAssistantLookupError,
   formatAssistantReference,
@@ -9,6 +10,7 @@ import {
   getDaemonPidPath,
   loadAllAssistants,
   lookupAssistantByIdentifier,
+  resolveCloud,
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
@@ -26,7 +28,7 @@ import { existsSync } from "fs";
 import {
   classifyProcess,
   detectOrphanedProcesses,
-  isProcessAlive,
+  isPidAlive,
   parseRemotePs,
   readPidFile,
 } from "../lib/orphan-detection";
@@ -149,35 +151,25 @@ const REMOTE_PS_CMD = [
   "| grep -v grep",
 ].join(" ");
 
-function extractHostFromUrl(url: string): string {
-  try {
-    const parsed = new URL(url);
-    return parsed.hostname;
-  } catch {
-    return url.replace(/^https?:\/\//, "").split(":")[0];
-  }
-}
-
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) return entry.cloud;
-  if (entry.project) return "gcp";
-  if (entry.sshUser) return "custom";
-  return "local";
-}
+const REMOTE_SSH_TIMEOUT_MS = 30_000;
 
 async function getRemoteProcessesGcp(entry: AssistantEntry): Promise<string> {
-  return execOutput("gcloud", [
-    "compute",
-    "ssh",
-    `${entry.sshUser ?? entry.assistantId}@${entry.assistantId}`,
-    `--zone=${entry.zone}`,
-    `--project=${entry.project}`,
-    `--command=${REMOTE_PS_CMD}`,
-    "--ssh-flag=-o StrictHostKeyChecking=no",
-    "--ssh-flag=-o UserKnownHostsFile=/dev/null",
-    "--ssh-flag=-o ConnectTimeout=10",
-    "--ssh-flag=-o LogLevel=ERROR",
-  ]);
+  return execOutput(
+    "gcloud",
+    [
+      "compute",
+      "ssh",
+      `${entry.sshUser ?? entry.assistantId}@${entry.assistantId}`,
+      `--zone=${entry.zone}`,
+      `--project=${entry.project}`,
+      `--command=${REMOTE_PS_CMD}`,
+      "--ssh-flag=-o StrictHostKeyChecking=no",
+      "--ssh-flag=-o UserKnownHostsFile=/dev/null",
+      "--ssh-flag=-o ConnectTimeout=10",
+      "--ssh-flag=-o LogLevel=ERROR",
+    ],
+    { timeoutMs: REMOTE_SSH_TIMEOUT_MS },
+  );
 }
 
 async function getRemoteProcessesCustom(
@@ -185,7 +177,9 @@ async function getRemoteProcessesCustom(
 ): Promise<string> {
   const host = extractHostFromUrl(entry.runtimeUrl);
   const sshUser = entry.sshUser ?? "root";
-  return execOutput("ssh", [...SSH_OPTS, `${sshUser}@${host}`, REMOTE_PS_CMD]);
+  return execOutput("ssh", [...SSH_OPTS, `${sshUser}@${host}`, REMOTE_PS_CMD], {
+    timeoutMs: REMOTE_SSH_TIMEOUT_MS,
+  });
 }
 
 interface ProcessSpec {
@@ -203,9 +197,13 @@ interface DetectedProcess {
   watch: boolean;
 }
 
+const LOCAL_CMD_TIMEOUT_MS = 5_000;
+
 async function isWatchMode(pid: string): Promise<boolean> {
   try {
-    const args = await execOutput("ps", ["-p", pid, "-o", "args="]);
+    const args = await execOutput("ps", ["-p", pid, "-o", "args="], {
+      timeoutMs: LOCAL_CMD_TIMEOUT_MS,
+    });
     return args.includes("--watch");
   } catch {
     return false;
@@ -242,7 +240,7 @@ async function detectProcess(spec: ProcessSpec): Promise<DetectedProcess> {
 
   // Tier 3: PID file fallback
   const filePid = readPidFile(spec.pidFile);
-  if (filePid && isProcessAlive(filePid)) {
+  if (filePid && isPidAlive(filePid)) {
     const watch = await isWatchMode(filePid);
     return {
       name: spec.name,
@@ -320,12 +318,11 @@ async function getDockerContainerState(
   containerName: string,
 ): Promise<string | null> {
   try {
-    const output = await execOutput("docker", [
-      "inspect",
-      "--format",
-      "{{.State.Status}}",
-      containerName,
-    ]);
+    const output = await execOutput(
+      "docker",
+      ["inspect", "--format", "{{.State.Status}}", containerName],
+      { timeoutMs: LOCAL_CMD_TIMEOUT_MS },
+    );
     return output.trim() || "unknown";
   } catch {
     return null;
@@ -458,9 +455,12 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
       process.exit(1);
     }
   } catch (error) {
-    console.error(
-      `Failed to list processes: ${error instanceof Error ? error.message : error}`,
-    );
+    const msg = error instanceof Error ? error.message : String(error);
+    if (msg.includes("timed out")) {
+      console.warn(`Warning: remote process listing timed out — ${msg}`);
+      return;
+    }
+    console.error(`Failed to list processes: ${msg}`);
     process.exit(1);
   }
 
@@ -496,7 +496,7 @@ async function getAssistantListHealth(
     // 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);
+    const alive = pid !== null && isPidAlive(pid);
     if (!alive) {
       return { status: "sleeping", detail: null };
     }