@vellumai/cli 0.8.1 → 0.8.2

package/src/lib/environments/paths.ts

@@ -110,6 +110,21 @@ export function getStateDir(env: EnvironmentDefinition): string {
   return join(xdgDataHome(), `vellum-${env.name}`);
 }
 
+/**
+ * Path to the interactive CLI's input history file.
+ *
+ * Follows the XDG Base Directory spec: history files are state data
+ * (persistent across runs but not portable / user-owned content), so they
+ * belong under `$XDG_STATE_HOME`, mirroring `bash`, `zsh`, `psql`, and `gh`.
+ * Defaults to `~/.local/state/vellum/input-history`.
+ *
+ * Not environment-scoped: terminal input history is per-user, not per-assistant,
+ * so dev and prod CLIs share the same history file.
+ */
+export function getInputHistoryPath(): string {
+  return join(xdgStateHome(), "vellum", "input-history");
+}
+
 /**
  * Named port constants derived from `DEFAULT_PORTS`.
  * These are the ports the assistant and gateway services bind to *inside*
@@ -127,3 +142,9 @@ function xdgDataHome(): string {
 function xdgConfigHome(): string {
   return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
 }
+
+function xdgStateHome(): string {
+  return (
+    process.env.XDG_STATE_HOME?.trim() || join(homedir(), ".local", "state")
+  );
+}

package/src/lib/input-history.ts

@@ -1,16 +1,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { dirname, join } from "path";
+import { dirname } from "path";
 
-const MAX_ENTRIES = 1000;
+import { getInputHistoryPath } from "./environments/paths.js";
 
-function historyPath(): string {
-  return join(homedir(), ".vellum", "input-history");
-}
+const MAX_ENTRIES = 1000;
 
 export function loadHistory(): string[] {
   try {
-    const path = historyPath();
+    const path = getInputHistoryPath();
     if (!existsSync(path)) return [];
     const content = readFileSync(path, "utf-8");
     return content
@@ -26,7 +23,7 @@ export function appendHistory(entry: string): void {
   const trimmed = entry.trim();
   if (!trimmed || trimmed.startsWith("/")) return;
   try {
-    const path = historyPath();
+    const path = getInputHistoryPath();
     const dir = dirname(path);
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });

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/sync-cloud-assistants.ts

@@ -56,9 +56,7 @@ export async function syncCloudAssistants(
   const log = options?.log;
   const platformUrl = getPlatformUrl();
   log?.(`Platform URL: ${platformUrl}`);
-  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;
@@ -94,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++;
     }
   }
 
@@ -128,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 };
 }

package/src/shared/provider-env-vars.ts

@@ -26,6 +26,9 @@ export const LLM_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   gemini: "GEMINI_API_KEY",
   fireworks: "FIREWORKS_API_KEY",
   openrouter: "OPENROUTER_API_KEY",
+  zai: "ZAI_API_KEY",
+  deepseek: "DEEPSEEK_API_KEY",
+  minimax: "MINIMAX_API_KEY",
 };
 
 /** Search-provider env var names. Mirrors `SEARCH_PROVIDER_CATALOG` BYOK entries. */

package/src/lib/doctor-client.ts

@@ -1,153 +0,0 @@
-const DOCTOR_URL = process.env.DOCTOR_SERVICE_URL?.trim() || "";
-
-export type ProgressPhase =
-  | "invoking_prompt"
-  | "calling_tool"
-  | "processing_tool_result";
-
-export interface ProgressEvent {
-  phase: ProgressPhase;
-  toolName?: string;
-}
-
-interface DoctorResult {
-  assistantId: string;
-  diagnostics: string | null;
-  recommendation: string | null;
-  error: string | null;
-}
-
-export interface ChatLogEntry {
-  role: "user" | "assistant" | "error";
-  content: string;
-}
-
-type DoctorProgressCallback = (event: ProgressEvent) => void;
-type DoctorLogCallback = (message: string) => void;
-
-async function streamDoctorResponse(
-  response: globalThis.Response,
-  onProgress?: DoctorProgressCallback,
-  onLog?: DoctorLogCallback,
-): Promise<DoctorResult> {
-  if (!response.body) {
-    throw new Error(
-      `No response body from doctor (HTTP ${response.status} ${response.statusText})`,
-    );
-  }
-
-  let result: DoctorResult | null = null;
-  const decoder = new TextDecoder();
-  let buffer = "";
-  let chunkCount = 0;
-  const receivedEventTypes: string[] = [];
-
-  try {
-    for await (const chunk of response.body) {
-      chunkCount++;
-      buffer += decoder.decode(chunk, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-
-      for (const line of lines) {
-        if (!line.trim()) continue;
-        const parsed = JSON.parse(line) as { type: string } & Record<
-          string,
-          unknown
-        >;
-        receivedEventTypes.push(parsed.type);
-        if (parsed.type === "progress") {
-          onProgress?.(parsed as unknown as ProgressEvent);
-        } else if (parsed.type === "log") {
-          onLog?.((parsed as unknown as { message: string }).message);
-        } else if (parsed.type === "result") {
-          result = parsed as unknown as DoctorResult;
-        }
-      }
-    }
-  } catch (streamErr) {
-    const detail =
-      streamErr instanceof Error ? streamErr.message : String(streamErr);
-    throw new Error(
-      `Doctor stream interrupted after ${chunkCount} chunks ` +
-        `(received events: [${receivedEventTypes.join(", ")}]): ${detail}`,
-    );
-  }
-
-  if (buffer.trim()) {
-    const parsed = JSON.parse(buffer) as { type: string } & Record<
-      string,
-      unknown
-    >;
-    receivedEventTypes.push(parsed.type);
-    if (parsed.type === "result") {
-      result = parsed as unknown as DoctorResult;
-    }
-  }
-
-  if (!result) {
-    throw new Error(
-      `No result received from doctor. ` +
-        `HTTP ${response.status}, ${chunkCount} chunks read, ` +
-        `events received: [${receivedEventTypes.join(", ")}], ` +
-        `trailing buffer: ${buffer.trim() ? JSON.stringify(buffer.trim().slice(0, 200)) : "(empty)"}`,
-    );
-  }
-
-  return result;
-}
-
-async function callDoctorDaemon(
-  assistantId: string,
-  project?: string,
-  zone?: string,
-  userPrompt?: string,
-  onProgress?: DoctorProgressCallback,
-  sessionId?: string,
-  chatContext?: ChatLogEntry[],
-  onLog?: DoctorLogCallback,
-): Promise<DoctorResult> {
-  if (!DOCTOR_URL) {
-    onLog?.("Doctor service not configured (DOCTOR_SERVICE_URL is not set)");
-    return {
-      assistantId,
-      diagnostics: null,
-      recommendation: null,
-      error: "Doctor service not configured",
-    };
-  }
-
-  const MAX_RETRIES = 2;
-  let lastError: unknown;
-
-  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-    try {
-      const response = await fetch(`${DOCTOR_URL}/doctor`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          assistantId,
-          project,
-          zone,
-          userPrompt,
-          sessionId,
-          chatContext,
-        }),
-      });
-      return await streamDoctorResponse(response, onProgress, onLog);
-    } catch (err) {
-      lastError = err;
-      const errMsg = err instanceof Error ? err.message : String(err);
-      const logMsg = `[doctor-client] Attempt ${attempt + 1}/${MAX_RETRIES} failed: ${errMsg}`;
-      onLog?.(logMsg);
-      if (attempt < MAX_RETRIES - 1) {
-        await new Promise((resolve) => setTimeout(resolve, 500));
-      }
-    }
-  }
-
-  throw lastError;
-}
-
-export { callDoctorDaemon };
-export type { DoctorProgressCallback, DoctorResult };