@vellumai/cli 0.8.4 → 0.8.6

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 };
     }

package/src/commands/recover.ts

@@ -1,6 +1,12 @@
-import { existsSync, readFileSync, unlinkSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+} from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { basename, dirname, join } from "path";
 
 import { saveAssistantEntry } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
@@ -21,8 +27,22 @@ export async function recover(): Promise<void> {
       "Restore a previously retired local assistant from its archive.",
     );
     console.log("");
+    console.log(
+      "Extracts the archived workspace data back to its original location,",
+    );
+    console.log(
+      "restores the lockfile entry, and starts the assistant and gateway.",
+    );
+    console.log(
+      "Archives are stored in $XDG_DATA_HOME/vellum/retired/ (default: ~/.local/share/vellum/retired/).",
+    );
+    console.log("");
     console.log("Arguments:");
     console.log("  <name>    Name of the retired assistant to recover");
+    console.log("");
+    console.log("Examples:");
+    console.log("  $ vellum recover my-assistant");
+    console.log("  $ vellum recover aria-7f3a");
     process.exit(0);
   }
 
@@ -61,11 +81,27 @@ export async function recover(): Promise<void> {
     process.exit(1);
   }
 
-  // 4. Extract archive
-  // TODO: extraction target is hardcoded to homedir(); multi-instance entries
-  //       whose instanceDir differs from homedir will extract to the wrong
-  //       location. Tracked separately from the collision-check regression.
-  await exec("tar", ["xzf", archivePath, "-C", homedir()]);
+  // 4. Determine the original target directory, then extract and rename.
+  //
+  // retireLocal archives either the full instanceDir (named instances) or just
+  // the .vellum/ subdirectory (default instance whose instanceDir === homedir()).
+  // The directory is staged under `<archive>.staging` inside the retired dir
+  // before being packed with `tar -C <retiredDir> <stagingBasename>`, so the
+  // top-level entry inside the tarball is always `<name>.tar.gz.staging`.
+  //
+  // Correct restoration: extract to retiredDir, then rename the staging entry
+  // back to the original target path.  Using homedir() as the -C target was
+  // wrong for any instance stored outside the home directory.
+  const isNamedInstance = entry.resources.instanceDir !== homedir();
+  const targetDir = isNamedInstance
+    ? entry.resources.instanceDir
+    : join(entry.resources.instanceDir, ".vellum");
+  const retiredDir = dirname(archivePath);
+  const extractedPath = join(retiredDir, basename(archivePath) + ".staging");
+
+  await exec("tar", ["xzf", archivePath, "-C", retiredDir]);
+  mkdirSync(dirname(targetDir), { recursive: true });
+  renameSync(extractedPath, targetDir);
 
   // 5. Restore lockfile entry
   saveAssistantEntry(entry);
@@ -74,14 +110,16 @@ export async function recover(): Promise<void> {
   unlinkSync(archivePath);
   unlinkSync(metadataPath);
 
-  // 7. Persist signing key so it survives daemon/gateway restarts (same as wake)
+  // 7. Persist signing key and bootstrap secret so they survive daemon/gateway restarts
   const signingKey = generateLocalSigningKey();
+  const bootstrapSecret = generateLocalSigningKey();
   entry.resources = { ...entry.resources, signingKey };
+  entry.guardianBootstrapSecret = bootstrapSecret;
   saveAssistantEntry(entry);
 
   // 8. Start daemon + gateway
   await startLocalDaemon(false, entry.resources, { signingKey });
-  await startGateway(false, entry.resources, { signingKey });
+  await startGateway(false, entry.resources, { signingKey, bootstrapSecret });
 
   console.log(`✅ Recovered assistant '${name}'.`);
 }

package/src/commands/restore.ts

@@ -97,6 +97,7 @@ async function getAccessToken(
   runtimeUrl: string,
   assistantId: string,
   displayName: string,
+  bootstrapSecret?: string,
 ): Promise<string> {
   const tokenData = loadGuardianToken(assistantId);
 
@@ -105,7 +106,11 @@ async function getAccessToken(
   }
 
   try {
-    const freshToken = await leaseGuardianToken(runtimeUrl, assistantId);
+    const freshToken = await leaseGuardianToken(
+      runtimeUrl,
+      assistantId,
+      bootstrapSecret,
+    );
     return freshToken.accessToken;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -574,6 +579,7 @@ export async function restore(): Promise<void> {
     entry.runtimeUrl,
     entry.assistantId,
     name,
+    entry.guardianBootstrapSecret,
   );
 
   if (dryRun) {
@@ -679,6 +685,7 @@ export async function restore(): Promise<void> {
         entry.runtimeUrl,
         entry.assistantId,
         name,
+        entry.guardianBootstrapSecret,
       );
     }