@vellumai/cli 0.8.2 → 0.8.4

package/src/lib/host-image-loader.ts

@@ -0,0 +1,138 @@
+/**
+ * Client for the host-side image-loader endpoint. Used to acquire image refs
+ * that aren't pullable from any external registry.
+ *
+ * The endpoint URL is a well-known convention — port 5500 on 127.0.0.1.
+ * The CLI calls in whenever it sees a ref that starts with `vellum-local/`,
+ * which are image refs that only exist in a local docker daemon and can't be
+ * `docker pull`'d from any external registry.
+ *
+ * The endpoint contract is intentionally minimal — POST a ref as JSON, get
+ * back a 200 once the image is in the host docker daemon, or a non-2xx
+ * with a descriptive error message. The client doesn't know (or care) what
+ * transport the server uses to put the image there.
+ */
+
+/**
+ * Well-known URL of the host-side image-loader server.
+ */
+export const HOST_IMAGE_LOADER_URL = "http://127.0.0.1:5500/v1/images/load";
+
+/**
+ * Prefix for image refs that only exist in a local docker daemon.
+ * These cannot be `docker pull`'d from any external registry; the CLI must
+ * route them through the host image-loader instead.
+ */
+const LOCAL_BUILD_REF_PREFIX = "vellum-local/";
+
+/** Whether `ref` points at a local-build image that requires the host loader. */
+export function isLocalBuildRef(ref: string): boolean {
+  return ref.startsWith(LOCAL_BUILD_REF_PREFIX);
+}
+
+/** Default timeout for image-load requests. Large `docker save | docker load`
+ * pipelines for full assistant images can run for a minute or two on cold
+ * caches, so we give plenty of headroom. */
+const LOAD_TIMEOUT_MS = 120_000;
+
+export interface HostImageLoaderResponse {
+  loaded?: boolean;
+  ref?: string;
+  error?: string;
+}
+
+export class HostImageLoaderError extends Error {
+  readonly url: string;
+  readonly ref: string;
+  readonly status?: number;
+
+  constructor(message: string, url: string, ref: string, status?: number) {
+    super(message);
+    this.name = "HostImageLoaderError";
+    this.url = url;
+    this.ref = ref;
+    this.status = status;
+  }
+}
+
+function isConnectionRefused(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { cause?: { code?: string }; code?: string };
+  return e.cause?.code === "ECONNREFUSED" || e.code === "ECONNREFUSED";
+}
+
+/**
+ * Ask the host-side loader to acquire `ref` into the host docker daemon.
+ *
+ * Resolves when the server returns 200; throws a {@link HostImageLoaderError}
+ * with a user-actionable message on any failure (network, timeout, non-2xx).
+ *
+ * The `log` callback receives one-line status updates; pass the same logger
+ * the surrounding command uses.
+ */
+/** Minimal fetch signature accepted for test injection. */
+export type FetchLike = (
+  input: string | URL,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+  },
+) => Promise<Response>;
+
+export async function loadImageViaHost(
+  url: string,
+  ref: string,
+  log: (msg: string) => void,
+  options: { timeoutMs?: number; fetchImpl?: FetchLike } = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? LOAD_TIMEOUT_MS;
+  const fetchImpl: FetchLike =
+    options.fetchImpl ?? (fetch as unknown as FetchLike);
+
+  log(`   ↪ ${ref}`);
+
+  let response: Response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ref }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    if (isConnectionRefused(err)) {
+      throw new HostImageLoaderError(
+        `Could not reach image-loader at ${url}. The ref \`${ref}\` is a ` +
+          `local-build image that requires the loader. Is the loader running? ` +
+          `Start it, or set VELLUM_ASSISTANT_IMAGE / VELLUM_GATEWAY_IMAGE / ` +
+          `VELLUM_CREDENTIAL_EXECUTOR_IMAGE to bypass image resolution.`,
+        url,
+        ref,
+      );
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new HostImageLoaderError(
+      `Image-loader request for ${ref} failed: ${message}`,
+      url,
+      ref,
+    );
+  }
+
+  if (!response.ok) {
+    let body: HostImageLoaderResponse | null = null;
+    try {
+      body = (await response.json()) as HostImageLoaderResponse;
+    } catch {
+      // Server returned non-JSON; fall through with status-only error.
+    }
+    const detail = body?.error ? `: ${body.error}` : "";
+    throw new HostImageLoaderError(
+      `Image-loader returned HTTP ${response.status} for ${ref}${detail}`,
+      url,
+      ref,
+      response.status,
+    );
+  }
+}

package/src/lib/platform-releases.ts

@@ -46,7 +46,10 @@ export async function resolveImageRefs(
   const platformRefs = await fetchPlatformImageRefs(version, log);
   if (platformRefs) {
     log?.("Resolved image refs from platform API");
-    return { imageTags: platformRefs, source: "platform" };
+    return {
+      imageTags: platformRefs.imageTags,
+      source: "platform",
+    };
   }
 
   log?.("Falling back to DockerHub tags");
@@ -68,7 +71,9 @@ export async function resolveImageRefs(
 async function fetchPlatformImageRefs(
   version: string,
   log?: (msg: string) => void,
-): Promise<Record<ServiceName, string> | null> {
+): Promise<{
+  imageTags: Record<ServiceName, string>;
+} | null> {
   try {
     const platformUrl = getPlatformUrl();
     const url = `${platformUrl}/v1/releases/?stable=true`;
@@ -123,9 +128,11 @@ async function fetchPlatformImageRefs(
     }
 
     return {
-      assistant: assistantImage,
-      "credential-executor": credentialExecutorImage,
-      gateway: gatewayImage,
+      imageTags: {
+        assistant: assistantImage,
+        "credential-executor": credentialExecutorImage,
+        gateway: gatewayImage,
+      },
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/lib/provider-secrets.ts

@@ -52,6 +52,19 @@ export interface GatewayApiKeyReadResult {
   unreachable: boolean;
 }
 
+export interface HatchProviderApiKeyOptions {
+  gatewayUrl: string;
+  provider: LlmProviderId | null;
+  bearerToken?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: ProviderSecretFetch;
+  log?: (message: string) => void;
+  prompt?: (prompt: string) => Promise<string>;
+  stdinIsTTY?: boolean;
+  input?: NodeJS.ReadStream;
+  output?: NodeJS.WriteStream;
+}
+
 const PROVIDER_LABELS: Record<LlmProviderId, string> = {
   anthropic: "Anthropic",
   openai: "OpenAI",
@@ -70,6 +83,84 @@ export function isSupportedLlmProvider(
   return Object.hasOwn(LLM_PROVIDER_ENV_VAR_NAMES, provider);
 }
 
+export function resolveHatchProvider(
+  configValues: Record<string, string | undefined>,
+): LlmProviderId | null {
+  const provider = (
+    resolveConfiguredMainAgentProvider(configValues) || "anthropic"
+  ).toLowerCase();
+
+  if (provider === "ollama") {
+    return null;
+  }
+
+  if (!isSupportedLlmProvider(provider)) {
+    throw new Error(
+      `Provider '${provider}' does not have a supported API-key setup flow.`,
+    );
+  }
+
+  return provider;
+}
+
+function resolveConfiguredMainAgentProvider(
+  configValues: Record<string, string | undefined>,
+): string | undefined {
+  // Fresh hatches seed the active custom profile from llm.default and then
+  // that active profile wins over static mainAgent call-site defaults. Match
+  // that startup behavior so hatch prompts for the provider the assistant will
+  // actually use on first chat.
+  return (
+    resolveProfileProvider(
+      configValues,
+      readConfigValue(configValues, "llm.activeProfile"),
+    ) ??
+    resolveFragmentProvider(configValues, "llm.default") ??
+    resolveFragmentProvider(configValues, "llm.callSites.mainAgent") ??
+    resolveProfileProvider(
+      configValues,
+      readConfigValue(configValues, "llm.callSites.mainAgent.profile"),
+    )
+  );
+}
+
+function resolveProfileProvider(
+  configValues: Record<string, string | undefined>,
+  profileName: string | undefined,
+): string | undefined {
+  if (!profileName) return undefined;
+  return resolveFragmentProvider(configValues, `llm.profiles.${profileName}`);
+}
+
+function resolveFragmentProvider(
+  configValues: Record<string, string | undefined>,
+  prefix: string,
+): string | undefined {
+  const provider = readConfigValue(configValues, `${prefix}.provider`);
+  if (provider) return provider;
+
+  const model = readConfigValue(configValues, `${prefix}.model`);
+  return model ? inferProviderFromModel(model) : undefined;
+}
+
+function readConfigValue(
+  configValues: Record<string, string | undefined>,
+  key: string,
+): string | undefined {
+  const value = configValues[key]?.trim();
+  return value && value.length > 0 ? value : undefined;
+}
+
+function inferProviderFromModel(model: string): string | undefined {
+  if (model.startsWith("claude-")) return "anthropic";
+  if (model.startsWith("gpt-")) return "openai";
+  if (model.startsWith("gemini-")) return "gemini";
+  if (model.startsWith("accounts/fireworks/models/")) return "fireworks";
+  if (model.includes("/")) return "openrouter";
+  if (model === "llama3.2" || model === "mistral") return "ollama";
+  return undefined;
+}
+
 function gatewayUrlWithPath(gatewayUrl: string, path: string): string {
   return `${gatewayUrl.replace(/\/+$/, "")}${path}`;
 }
@@ -411,3 +502,63 @@ export async function ensureProviderApiKey(
     source,
   };
 }
+
+export async function configureHatchProviderApiKey(
+  options: HatchProviderApiKeyOptions,
+): Promise<void> {
+  const log = options.log ?? console.log;
+  const { provider } = options;
+
+  if (provider === null) {
+    log("Provider credentials not required for the selected provider.");
+    return;
+  }
+
+  try {
+    const result = await ensureProviderApiKey({
+      gatewayUrl: options.gatewayUrl,
+      provider,
+      bearerToken: options.bearerToken,
+      env: options.env,
+      fetchImpl: options.fetchImpl,
+      prompt: options.prompt,
+      stdinIsTTY: options.stdinIsTTY,
+      input: options.input,
+      output: options.output,
+    });
+
+    if (result.status === "already_configured") {
+      log(
+        `Provider credentials already configured for ${formatProviderName(result.provider)}.`,
+      );
+      return;
+    }
+
+    if (result.status === "configured") {
+      if (result.source === "env") {
+        log(
+          `Configured ${formatProviderName(result.provider)} credentials from ${LLM_PROVIDER_ENV_VAR_NAMES[result.provider]}.`,
+        );
+      } else {
+        log(`Configured ${formatProviderName(result.provider)} credentials.`);
+      }
+      return;
+    }
+
+    if (result.status === "skipped") {
+      log(result.message);
+      return;
+    }
+
+    log(
+      `⚠️  Provider credential setup skipped: ${result.message}\n` +
+        `   The assistant is still hatched. Run \`vellum setup --provider ${provider}\` to finish setup.`,
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log(
+      `⚠️  Provider credential setup failed: ${message}\n` +
+        `   The assistant is still hatched. Run \`vellum setup --provider ${provider}\` after fixing the issue.`,
+    );
+  }
+}

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

@@ -26,9 +26,6 @@ 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. */