@vellumai/cli 0.8.0 → 0.8.2

package/src/lib/orphan-detection.ts

@@ -1,5 +1,11 @@
 import { existsSync, readFileSync } from "fs";
+import { join } from "path";
 
+import {
+  getDaemonPidPath,
+  loadAllAssistantsAcrossEnvs,
+  type AssistantEntry,
+} from "./assistant-config.js";
 import { execOutput } from "./step-runner";
 
 export interface RemoteProcess {
@@ -67,10 +73,68 @@ export interface OrphanedProcess {
   source: string;
 }
 
-export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
+/**
+ * Collect PIDs that belong to a known assistant in any environment.
+ *
+ * For local entries this reads the daemon/gateway/qdrant/embed-worker PID
+ * files under each entry's `instanceDir`. For docker entries we include the
+ * `watcherPid` field when present (the file watcher runs as a host process,
+ * unlike the containers themselves). Other cloud topologies don't have
+ * host-side processes that show up in `ps ax`.
+ *
+ * This set is the basis for filtering the orphan list: if a running process
+ * matches a recorded PID for *any* env's assistant, it's not an orphan.
+ */
+export function getKnownPidsFromAssistants(
+  entries: AssistantEntry[],
+): Set<string> {
+  const pids = new Set<string>();
+  for (const entry of entries) {
+    if (entry.cloud === "local" && entry.resources) {
+      const vellumDir = join(entry.resources.instanceDir, ".vellum");
+      const candidates = [
+        getDaemonPidPath(entry.resources),
+        join(vellumDir, "gateway.pid"),
+        join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"),
+        join(vellumDir, "workspace", "embed-worker.pid"),
+      ];
+      for (const file of candidates) {
+        const pid = readPidFile(file);
+        if (pid) pids.add(pid);
+      }
+    }
+    if (typeof entry.watcherPid === "number") {
+      pids.add(String(entry.watcherPid));
+    }
+  }
+  return pids;
+}
+
+export interface DetectOrphansOptions {
+  /**
+   * Set of PIDs to treat as known and exclude from the orphan list. When
+   * omitted, defaults to the union of every env's recorded assistant PIDs
+   * via {@link loadAllAssistantsAcrossEnvs} +
+   * {@link getKnownPidsFromAssistants}. Tests can inject an explicit set to
+   * avoid touching the real on-host lockfiles.
+   */
+  excludePids?: Set<string>;
+}
+
+export async function detectOrphanedProcesses(
+  options: DetectOrphansOptions = {},
+): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
 
+  // PIDs that belong to a known assistant in *any* environment are not
+  // orphans. Without this filter, running `vellum ps` from an env that has
+  // no assistants — or `vellum clean` from any env — would flag (or kill)
+  // another env's healthy services as orphans.
+  const knownPids =
+    options.excludePids ??
+    getKnownPidsFromAssistants(loadAllAssistantsAcrossEnvs());
+
   // Process table scan — discover orphaned processes by scanning the OS
   // process table rather than reading PID files from the workspace.
   try {
@@ -83,6 +147,7 @@ export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
 
     for (const p of procs) {
       if (p.pid === ownPid || seenPids.has(p.pid)) continue;
+      if (knownPids.has(p.pid)) continue;
       const type = classifyProcess(p.command);
       if (type === "unknown") continue;
       results.push({ name: type, pid: p.pid, source: "process table" });

package/src/lib/platform-client.ts

@@ -129,9 +129,12 @@ export function invalidateOrgIdCache(
  * The org ID is cached per (token, platformUrl) for 60 seconds to avoid
  * redundant HTTP requests in tight polling loops.
  *
- * Auth errors (401 / 403) from the org-ID fetch are logged with a
- * user-friendly message before re-throwing, so callers don't need to
- * repeat that logic.
+ * Auth errors (401 / 403) from the org-ID fetch are wrapped in a
+ * user-friendly Error message before re-throwing, so callers can surface
+ * a useful message without doing their own classification. Callers that
+ * handle the throw (e.g. `syncCloudAssistants`) stay silent on stderr;
+ * callers that let it bubble get a single clean line from the top-level
+ * runner.
  */
 export async function authHeaders(
   token: string,
@@ -163,11 +166,9 @@ export async function authHeaders(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("401") || msg.includes("403")) {
-      console.error("Authentication failed. Run 'vellum login' to refresh.");
-    } else {
-      console.error(`Failed to fetch organization: ${msg}`);
+      throw new Error("Authentication failed. Run 'vellum login' to refresh.");
     }
-    throw err;
+    throw new Error(`Failed to fetch organization: ${msg}`);
   }
 }
 

package/src/lib/provider-secrets.ts

@@ -0,0 +1,413 @@
+import { spawnSync } from "node:child_process";
+
+import { LLM_PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
+
+export type LlmProviderId = keyof typeof LLM_PROVIDER_ENV_VAR_NAMES;
+
+export type ProviderApiKeySource = "env" | "prompt";
+export type ProviderSecretFetch = (
+  input: Parameters<typeof fetch>[0],
+  init?: Parameters<typeof fetch>[1],
+) => ReturnType<typeof fetch>;
+
+export type EnsureProviderApiKeyResult =
+  | {
+      status: "already_configured";
+      provider: LlmProviderId;
+    }
+  | {
+      status: "configured";
+      provider: LlmProviderId;
+      source: ProviderApiKeySource;
+    }
+  | {
+      status: "missing";
+      provider: LlmProviderId;
+      message: string;
+    }
+  | {
+      status: "failed";
+      provider: LlmProviderId;
+      message: string;
+    }
+  | {
+      status: "skipped";
+      message: string;
+    };
+
+export interface EnsureProviderApiKeyOptions {
+  gatewayUrl: string;
+  provider: string | null;
+  bearerToken?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: ProviderSecretFetch;
+  prompt?: (prompt: string) => Promise<string>;
+  stdinIsTTY?: boolean;
+  input?: NodeJS.ReadStream;
+  output?: NodeJS.WriteStream;
+}
+
+export interface GatewayApiKeyReadResult {
+  found: boolean;
+  unreachable: boolean;
+}
+
+const PROVIDER_LABELS: Record<LlmProviderId, string> = {
+  anthropic: "Anthropic",
+  openai: "OpenAI",
+  gemini: "Gemini",
+  fireworks: "Fireworks",
+  openrouter: "OpenRouter",
+};
+
+export function formatProviderName(provider: LlmProviderId): string {
+  return PROVIDER_LABELS[provider];
+}
+
+export function isSupportedLlmProvider(
+  provider: string,
+): provider is LlmProviderId {
+  return Object.hasOwn(LLM_PROVIDER_ENV_VAR_NAMES, provider);
+}
+
+function gatewayUrlWithPath(gatewayUrl: string, path: string): string {
+  return `${gatewayUrl.replace(/\/+$/, "")}${path}`;
+}
+
+function secretHeaders(bearerToken?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+  if (bearerToken) {
+    headers.Authorization = `Bearer ${bearerToken}`;
+  }
+  return headers;
+}
+
+async function parseErrorMessage(response: Response): Promise<string> {
+  let text = "";
+  try {
+    text = await response.text();
+  } catch {
+    // Fall through to status text.
+  }
+
+  try {
+    const body = JSON.parse(text) as {
+      error?: unknown;
+    };
+    const message = extractErrorMessage(body.error);
+    if (message) return message;
+  } catch {
+    // Fall back to raw text below.
+  }
+
+  if (text.trim().length > 0) {
+    return text.trim();
+  }
+
+  return response.statusText || `HTTP ${response.status}`;
+}
+
+function extractErrorMessage(error: unknown): string | null {
+  if (typeof error === "string" && error.trim().length > 0) {
+    return error.trim();
+  }
+  if (!error || typeof error !== "object") {
+    return null;
+  }
+
+  const maybeMessage = (error as { message?: unknown }).message;
+  if (typeof maybeMessage === "string" && maybeMessage.trim().length > 0) {
+    return maybeMessage.trim();
+  }
+
+  return null;
+}
+
+export async function readGatewayApiKey(
+  gatewayUrl: string,
+  provider: LlmProviderId,
+  bearerToken?: string,
+  fetchImpl: ProviderSecretFetch = fetch,
+): Promise<GatewayApiKeyReadResult> {
+  const response = await fetchImpl(
+    gatewayUrlWithPath(gatewayUrl, "/v1/secrets/read"),
+    {
+      method: "POST",
+      headers: secretHeaders(bearerToken),
+      body: JSON.stringify({
+        type: "api_key",
+        name: provider,
+        reveal: false,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    },
+  );
+
+  if (!response.ok) {
+    const message = await parseErrorMessage(response);
+    if (response.status === 404) {
+      throw new Error(
+        `Active assistant at ${gatewayUrl} does not expose /v1/secrets/read (${message}). Run \`vellum ps\` to confirm the active assistant, then select a self-hosted assistant with \`vellum use <assistant>\` or wake a current assistant before running setup.`,
+      );
+    }
+    throw new Error(
+      `Failed to check ${formatProviderName(provider)} API key: ${message}`,
+    );
+  }
+
+  const body = (await response.json()) as {
+    found?: unknown;
+    unreachable?: unknown;
+  };
+  return {
+    found: body.found === true,
+    unreachable: body.unreachable === true,
+  };
+}
+
+export async function injectGatewayApiKey(
+  gatewayUrl: string,
+  provider: LlmProviderId,
+  value: string,
+  bearerToken?: string,
+  fetchImpl: ProviderSecretFetch = fetch,
+): Promise<void> {
+  const response = await fetchImpl(
+    gatewayUrlWithPath(gatewayUrl, "/v1/secrets"),
+    {
+      method: "POST",
+      headers: secretHeaders(bearerToken),
+      body: JSON.stringify({
+        type: "api_key",
+        name: provider,
+        value,
+      }),
+      signal: AbortSignal.timeout(10_000),
+    },
+  );
+
+  if (!response.ok) {
+    const message = await parseErrorMessage(response);
+    throw new Error(
+      `Failed to store ${formatProviderName(provider)} API key: ${message}`,
+    );
+  }
+
+  const body = (await response.json().catch(() => ({}))) as {
+    success?: unknown;
+    error?: unknown;
+  };
+  if (body.success === false) {
+    const message =
+      typeof body.error === "string" && body.error.trim().length > 0
+        ? body.error
+        : "Assistant rejected the API key.";
+    throw new Error(message);
+  }
+}
+
+export async function promptSecret(
+  prompt: string,
+  streams: {
+    input?: NodeJS.ReadStream;
+    output?: NodeJS.WriteStream;
+  } = {},
+): Promise<string> {
+  const input = streams.input ?? process.stdin;
+  const output = streams.output ?? process.stdout;
+
+  const restoreEcho = disableTerminalEcho(input);
+  output.write(prompt);
+
+  return new Promise((resolve, reject) => {
+    const wasRaw = input.isRaw;
+    if (input.isTTY) {
+      input.setRawMode(true);
+    }
+    input.resume();
+
+    let value = "";
+
+    const cleanup = (): void => {
+      input.removeListener("data", onData);
+      if (input.isTTY) {
+        input.setRawMode(wasRaw ?? false);
+      }
+      restoreEcho();
+      input.pause();
+    };
+
+    const finish = (): void => {
+      cleanup();
+      output.write("\n");
+      resolve(value);
+    };
+
+    const cancel = (): void => {
+      cleanup();
+      output.write("\n");
+      reject(new Error("Input cancelled."));
+    };
+
+    const onData = (chunk: Buffer | string): void => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      if (bytes[0] === 27) {
+        return;
+      }
+
+      for (const byte of bytes) {
+        if (byte === 3) {
+          cancel();
+          return;
+        }
+        if (byte === 10 || byte === 13) {
+          finish();
+          return;
+        }
+        if (byte === 8 || byte === 127) {
+          value = value.slice(0, -1);
+          continue;
+        }
+        if (byte >= 32 && byte <= 126) {
+          value += String.fromCharCode(byte);
+        }
+      }
+    };
+
+    input.on("data", onData);
+  });
+}
+
+function disableTerminalEcho(input: NodeJS.ReadStream): () => void {
+  if (input !== process.stdin || !input.isTTY || process.platform === "win32") {
+    return () => {};
+  }
+
+  const currentState = spawnSync("stty", ["-g"], {
+    encoding: "utf8",
+    stdio: ["inherit", "pipe", "ignore"],
+  });
+  const state = currentState.stdout.trim();
+  if (currentState.status !== 0 || state.length === 0) {
+    return () => {};
+  }
+
+  const disabled = spawnSync("stty", ["-echo"], {
+    stdio: ["inherit", "ignore", "ignore"],
+  });
+  if (disabled.status !== 0) {
+    return () => {};
+  }
+
+  let restored = false;
+  return () => {
+    if (restored) {
+      return;
+    }
+    restored = true;
+    spawnSync("stty", [state], {
+      stdio: ["inherit", "ignore", "ignore"],
+    });
+  };
+}
+
+export async function ensureProviderApiKey(
+  options: EnsureProviderApiKeyOptions,
+): Promise<EnsureProviderApiKeyResult> {
+  if (options.provider === null) {
+    return {
+      status: "skipped",
+      message: "Selected provider does not require an API key.",
+    };
+  }
+
+  const normalizedProvider = options.provider.trim().toLowerCase();
+  if (!isSupportedLlmProvider(normalizedProvider)) {
+    throw new Error(
+      `Provider '${options.provider}' does not have a supported API-key setup flow.`,
+    );
+  }
+  const provider = normalizedProvider;
+  const providerName = formatProviderName(provider);
+  const envVarName = LLM_PROVIDER_ENV_VAR_NAMES[provider];
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  const existing = await readGatewayApiKey(
+    options.gatewayUrl,
+    provider,
+    options.bearerToken,
+    fetchImpl,
+  );
+  if (existing.unreachable) {
+    return {
+      status: "failed",
+      provider,
+      message:
+        "Assistant credential store is unavailable. Try again after the assistant finishes starting.",
+    };
+  }
+  if (existing.found) {
+    return {
+      status: "already_configured",
+      provider,
+    };
+  }
+
+  const envValue = options.env?.[envVarName]?.trim();
+  let apiKey = envValue;
+  let source: ProviderApiKeySource = "env";
+
+  if (!apiKey) {
+    source = "prompt";
+    if (options.prompt) {
+      apiKey = (
+        await options.prompt(
+          `Enter your ${providerName} API key (${envVarName}): `,
+        )
+      ).trim();
+    } else {
+      const stdinIsTTY = options.stdinIsTTY ?? process.stdin.isTTY;
+      if (!stdinIsTTY) {
+        return {
+          status: "missing",
+          provider,
+          message: `Missing ${envVarName}. Set it in the environment or run vellum setup from an interactive terminal.`,
+        };
+      }
+      apiKey = (
+        await promptSecret(
+          `Enter your ${providerName} API key (${envVarName}): `,
+          {
+            input: options.input,
+            output: options.output,
+          },
+        )
+      ).trim();
+    }
+  }
+
+  if (!apiKey) {
+    return {
+      status: "missing",
+      provider,
+      message: "API key cannot be empty.",
+    };
+  }
+
+  await injectGatewayApiKey(
+    options.gatewayUrl,
+    provider,
+    apiKey,
+    options.bearerToken,
+    fetchImpl,
+  );
+
+  return {
+    status: "configured",
+    provider,
+    source,
+  };
+}

package/src/lib/statefulset.ts

@@ -99,6 +99,11 @@ export interface DockerContainerSpec {
   ports?: PortSpec[];
   env: EnvEntry[];
   volumeMounts: VolumeMount[];
+  /**
+   * Optional `--user` override for `docker run`. Mirrors K8s
+   * `securityContext.runAsUser`. Omitted ⇒ image's `USER` directive wins.
+   */
+  user?: string;
 }
 
 export interface DockerVolumeClaimTemplate {
@@ -168,6 +173,7 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
         { kind: "static", name: "DEBUG_STDOUT_LOGS",         value: "1" },
         { kind: "static", name: "VELLUM_CLOUD",              value: "docker" },
         { kind: "static", name: "RUNTIME_HTTP_HOST",         value: "0.0.0.0" },
+        { kind: "static", name: "RUNTIME_HTTP_PORT",         value: `${ASSISTANT_INTERNAL_PORT}` },
         { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
         { kind: "static", name: "VELLUM_BACKUP_DIR",         value: "/workspace/.backups" },
         { kind: "static", name: "VELLUM_BACKUP_KEY_PATH",    value: "/workspace/.backup.key" },
@@ -196,6 +202,7 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
       name: "gateway-sidecar",
       internalName: "gateway",
       network: "container",
+      user: "0",
       env: [
         { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
         { kind: "static", name: "GATEWAY_SECURITY_DIR",      value: "/gateway-security" },
@@ -300,6 +307,11 @@ export function buildServiceRunArgs(
             : res.cesContainer;
       args.push("--name", containerName);
 
+      // User override (mirrors K8s securityContext.runAsUser)
+      if (container.user !== undefined) {
+        args.push("--user", container.user);
+      }
+
       // Network
       if (container.network === "bridge") {
         args.push(`--network=${res.network}`);

package/src/lib/sync-cloud-assistants.ts

@@ -6,6 +6,11 @@
  *   (e.g. retired assistants).
  *
  * Used by both `vellum login` and `vellum ps` to keep the lockfile fresh.
+ *
+ * **Contract:** callers must verify the user is logged in (i.e. a non-empty
+ * platform token exists) before invoking this helper. The "is there a token?"
+ * decision belongs at the command level so commands can render the right
+ * "Platform: …" status without ever entering the platform fetch path.
  */
 
 import {
@@ -17,7 +22,6 @@ import {
   fetchCurrentUser,
   fetchPlatformAssistants,
   getPlatformUrl,
-  readPlatformToken,
 } from "./platform-client.js";
 
 export type SyncLogger = (message: string) => void;
@@ -34,24 +38,25 @@ export interface SyncOptions {
 
 /**
  * Fetch platform assistants and reconcile against the lockfile.
- * Returns the number of entries added/removed, or `null` if the user
- * is not logged in or the fetch fails.
+ *
+ * Returns the number of entries added/removed, or `null` if the fetch fails
+ * (e.g. platform unreachable, invalid token). Callers must pre-verify a
+ * non-empty token; this function assumes one is present and will throw if
+ * called with an empty string.
  */
 export async function syncCloudAssistants(
+  token: string,
   options?: SyncOptions,
 ): Promise<SyncResult | null> {
+  if (!token) {
+    throw new Error(
+      "syncCloudAssistants called without a token. Callers must check `readPlatformToken()` first.",
+    );
+  }
   const log = options?.log;
   const platformUrl = getPlatformUrl();
   log?.(`Platform URL: ${platformUrl}`);
-
-  const token = readPlatformToken();
-  if (!token) {
-    log?.("No platform token found — skipping cloud sync");
-    return null;
-  }
-  log?.(
-    `Token found (${token.length} chars, prefix: ${token.slice(0, 6)}…)`,
-  );
+  log?.(`Token found (${token.length} chars, prefix: ${token.slice(0, 6)}…)`);
 
   // Fetch user info for the login status line
   let email: string | undefined;
@@ -87,27 +92,41 @@ export async function syncCloudAssistants(
   const platformIds = new Set(platformAssistants.map((a) => a.id));
 
   // Add new platform assistants not yet in the lockfile
-  const existingCloudIds = new Set(
-    loadAllAssistants()
-      .filter((a) => a.cloud === "vellum")
-      .map((a) => a.assistantId),
+  const existingCloudEntries = loadAllAssistants().filter(
+    (a) => a.cloud === "vellum",
+  );
+  const existingCloudById = new Map(
+    existingCloudEntries.map((a) => [a.assistantId, a]),
   );
+  const existingCloudIds = new Set(existingCloudById.keys());
   log?.(
     `Lockfile has ${existingCloudIds.size} cloud assistant(s): ${[...existingCloudIds].join(", ") || "(none)"}`,
   );
 
   let added = 0;
+  let updated = 0;
   for (const pa of platformAssistants) {
-    if (!existingCloudIds.has(pa.id)) {
+    const existing = existingCloudById.get(pa.id);
+    const assistantName = pa.name.trim();
+    const nameFields = assistantName ? { name: assistantName } : {};
+    if (!existing) {
       log?.(`Adding ${pa.name || pa.id} to lockfile`);
       saveAssistantEntry({
         assistantId: pa.id,
+        ...nameFields,
         runtimeUrl: getPlatformUrl(),
         cloud: "vellum",
         species: "vellum",
         hatchedAt: new Date().toISOString(),
       });
       added++;
+    } else if (assistantName && existing.name !== assistantName) {
+      log?.(`Updating ${pa.id} name to ${assistantName}`);
+      saveAssistantEntry({
+        ...existing,
+        name: assistantName,
+      });
+      updated++;
     }
   }
 
@@ -121,6 +140,8 @@ export async function syncCloudAssistants(
     }
   }
 
-  log?.(`Sync complete: ${added} added, ${removed} removed`);
+  log?.(
+    `Sync complete: ${added} added, ${updated} updated, ${removed} removed`,
+  );
   return { added, removed, email };
 }