@vellumai/cli 0.8.4 → 0.8.5

package/src/lib/api-key-check.ts

@@ -0,0 +1,40 @@
+import { LLM_PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
+
+export interface ApiKeyCheckResult {
+  hasKey: boolean;
+}
+
+/**
+ * Returns true when a key value is a real credential rather than a placeholder.
+ *
+ * .env.example ships values like `sk-ant-...`, `sk-...`, and `...` to show
+ * where credentials go. Any value containing `...` or that is empty is treated
+ * as a placeholder that the user has not replaced yet.
+ */
+function isPlaceholder(value: string | undefined): boolean {
+  if (!value || value.trim() === "") return true;
+  if (value.includes("...")) return true;
+  return false;
+}
+
+/**
+ * Check whether at least one LLM provider API key is configured in the
+ * current process environment.
+ *
+ * The CLI's job is to spawn the daemon and pass configuration via environment
+ * variables — it does not read from the .vellum/ directory (see AGENTS.md).
+ * Checking process.env is sufficient: the daemon forwards whatever is set
+ * in the environment, so exporting a key before running `vellum hatch` is
+ * the correct way to supply it.
+ *
+ * Uses the canonical LLM provider env-var catalog so the list stays in sync
+ * automatically as new providers are added.
+ */
+export function checkProviderApiKey(): ApiKeyCheckResult {
+  for (const envVar of Object.values(LLM_PROVIDER_ENV_VAR_NAMES)) {
+    if (!isPlaceholder(process.env[envVar])) {
+      return { hasKey: true };
+    }
+  }
+  return { hasKey: false };
+}

package/src/lib/docker.ts

@@ -12,7 +12,6 @@ import {
   setActiveAssistant,
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
-import { buildHatchConfigValues, writeInitialConfig } from "./config-utils";
 import { buildServiceRunArgs } from "./statefulset.js";
 import type { Species } from "./constants";
 import { getDefaultPorts } from "./environments/paths.js";
@@ -35,6 +34,7 @@ import {
   formatProviderName,
   resolveHatchProvider,
 } from "./provider-secrets.js";
+import { findOpenPort } from "./port-allocator.js";
 import { exec, execOutput } from "./step-runner";
 import {
   closeLogFile,
@@ -645,7 +645,6 @@ export async function startContainers(
     extraAssistantEnv?: Record<string, string>;
     gatewayPort: number;
     imageTags: Record<ServiceName, string>;
-    defaultWorkspaceConfigPath?: string;
     instanceName: string;
     res: ReturnType<typeof dockerResourceNames>;
   },
@@ -981,7 +980,22 @@ export async function hatchDocker(
     await ensureDockerInstalled();
 
     const instanceName = generateInstanceName(species, name);
-    const gatewayPort = getDefaultPorts(getCurrentEnvironment()).gateway;
+    // Resolve the gateway's host port dynamically. The env-default
+    // (production 7830 / non-prod overrides) is just the *preferred*
+    // starting point — if it's taken by another local assistant, eval
+    // run, or unrelated process, we walk upward until we find a free
+    // port. This replaces the previous "first one in wins, everyone
+    // else gets a docker bind error" behavior and removes the need for
+    // an orphan-cleanup pre-flight in the evals harness.
+    const preferredGatewayPort = getDefaultPorts(
+      getCurrentEnvironment(),
+    ).gateway;
+    const gatewayPort = await findOpenPort(preferredGatewayPort);
+    if (gatewayPort !== preferredGatewayPort) {
+      log(
+        `Preferred gateway port ${preferredGatewayPort} is in use; allocated ${gatewayPort} for this instance.`,
+      );
+    }
 
     const imageTags: Record<ServiceName, string> = {
       assistant: "",
@@ -1150,10 +1164,11 @@ export async function hatchDocker(
       "chown 1001:1001 /workspace /run/assistant-ipc /run/gateway-ipc",
     ]);
 
-    // Write --config key=value pairs to a temp file that gets bind-mounted
-    // into the assistant container and read via VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH.
-    const hatchConfigValues = buildHatchConfigValues(configValues, provider);
-    const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
+    // BYOK setup (API key, custom profiles, active-profile selection) is
+    // driven post-boot by the CLI calling the Assistant's public APIs
+    // (`POST /v1/secrets`, etc.) via `configureHatchProviderApiKey` below.
+    // The Assistant container comes up clean — no overlay file, no
+    // client-side workspace-config injection.
 
     const cesServiceToken = randomBytes(32).toString("hex");
     const signingKey = randomBytes(32).toString("hex");
@@ -1177,7 +1192,6 @@ export async function hatchDocker(
         cesServiceToken,
         gatewayPort,
         imageTags,
-        defaultWorkspaceConfigPath,
         instanceName,
         res,
       },

package/src/lib/hatch-local.ts

@@ -40,6 +40,7 @@ import {
   resolveHatchProvider,
 } from "./provider-secrets.js";
 import { logHatchNextSteps } from "./hatch-next-steps.js";
+import { checkProviderApiKey } from "./api-key-check.js";
 
 /**
  * Attempts to place a symlink at the given path pointing to cliBinary.
@@ -178,6 +179,16 @@ export async function hatchLocal(
   console.log(`   Species: ${species}`);
   console.log("");
 
+  const apiKeyCheck = checkProviderApiKey();
+  if (!apiKeyCheck.hasKey) {
+    console.warn(
+      "Warning: No LLM provider API key is configured. The assistant will fail when you try to send a message.",
+    );
+    console.warn("  To fix, export your key before running vellum hatch:");
+    console.warn("  export ANTHROPIC_API_KEY=<your-key>");
+    console.warn("");
+  }
+
   if (!process.env.APP_VERSION) {
     process.env.APP_VERSION = cliPkg.version;
   }

package/src/lib/port-allocator.ts

@@ -0,0 +1,93 @@
+import { createServer } from "net";
+
+/**
+ * Walks upward from `preferred` and returns the first host port that the
+ * kernel will let us bind to. Used by `hatchDocker` to pick the gateway's
+ * host-side port instead of always grabbing the env-default (e.g. 7830 /
+ * 20100), which collides with any other local assistant — eval-spawned or
+ * otherwise — already bound there.
+ *
+ * The previous design (`evals/src/lib/orphan-cleanup.ts`) tried to fix this
+ * by sweeping dead eval-run resources before the next hatch. That only
+ * helped when the conflict came from a prior eval run; an unrelated local
+ * `vellum hatch` holding the port wedged the whole flow. Discovering an
+ * open port at hatch time is the proper fix and lets us delete the cleanup
+ * pre-flight entirely.
+ *
+ * Walks linearly from `preferred` upward rather than asking the kernel for
+ * an arbitrary ephemeral port (`listen(0)`) so the resulting port stays
+ * legible to operators — three local assistants land on N, N+1, N+2
+ * instead of three random numbers in the 32768-60999 range.
+ */
+export async function findOpenPort(
+  preferred: number,
+  options: { maxAttempts?: number; host?: string } = {},
+): Promise<number> {
+  const maxAttempts = options.maxAttempts ?? 50;
+  const host = options.host ?? "0.0.0.0";
+
+  if (!Number.isInteger(preferred) || preferred < 1 || preferred > 65535) {
+    throw new Error(
+      `findOpenPort: preferred port ${preferred} is not a valid TCP port`,
+    );
+  }
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new Error(
+      `findOpenPort: maxAttempts ${maxAttempts} must be a positive integer`,
+    );
+  }
+
+  let lastError: Error | null = null;
+  for (let offset = 0; offset < maxAttempts; offset++) {
+    const port = preferred + offset;
+    if (port > 65535) break;
+    try {
+      await probePort(port, host);
+      return port;
+    } catch (err) {
+      lastError = err as Error;
+      if (!isPortInUseError(err)) {
+        // EACCES / EPERM / etc. are not "try the next port" signals — those
+        // are configuration problems an operator needs to see immediately.
+        throw err;
+      }
+    }
+  }
+  throw new Error(
+    `findOpenPort: no open port in range [${preferred}, ${preferred + maxAttempts - 1}]` +
+      (lastError ? ` (last error: ${lastError.message})` : ""),
+  );
+}
+
+/**
+ * Resolves if `port` on `host` can be bound right now. Rejects with the
+ * server's `error` event (typically `EADDRINUSE`) otherwise. Always closes
+ * the probe server before resolving so we don't leak the port we just
+ * proved was free.
+ */
+function probePort(port: number, host: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    const cleanup = (cb: () => void): void => {
+      server.removeAllListeners();
+      server.close(() => cb());
+    };
+    server.once("error", (err) => {
+      // close() on a server that never listened is a no-op; calling it
+      // anyway keeps cleanup uniform.
+      cleanup(() => reject(err));
+    });
+    server.once("listening", () => {
+      cleanup(() => resolve());
+    });
+    server.listen(port, host);
+  });
+}
+
+function isPortInUseError(err: unknown): boolean {
+  if (err instanceof Error && "code" in err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    return code === "EADDRINUSE" || code === "EADDRNOTAVAIL";
+  }
+  return false;
+}

package/src/lib/statefulset.ts

@@ -257,7 +257,6 @@ export interface BuildServiceRunArgsOpts extends DockerRunSecrets {
   instanceName: string;
   res: DockerResourceNames;
   extraAssistantEnv?: Record<string, string>;
-  defaultWorkspaceConfigPath?: string;
   /** Avatar device path, if available. Injected by `docker.ts` after resolving. */
   avatarDevicePath?: string;
 }
@@ -286,7 +285,6 @@ export function buildServiceRunArgs(
     instanceName,
     res,
     extraAssistantEnv,
-    defaultWorkspaceConfigPath,
     avatarDevicePath,
   } = opts;
 
@@ -355,14 +353,6 @@ export function buildServiceRunArgs(
           "-e", `GATEWAY_INTERNAL_URL=http://localhost:${GATEWAY_INTERNAL_PORT}`,
         );
 
-        if (defaultWorkspaceConfigPath) {
-          const cPath = `/tmp/vellum-default-workspace-config-${Date.now()}.json`;
-          args.push(
-            "-v", `${defaultWorkspaceConfigPath}:${cPath}:ro`,
-            "-e", `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH=${cPath}`,
-          );
-        }
-
         if (extraAssistantEnv) {
           for (const [k, v] of Object.entries(extraAssistantEnv)) {
             args.push("-e", `${k}=${v}`);

package/src/lib/step-runner.ts

@@ -1,5 +1,38 @@
 import { spawn } from "child_process";
 
+/**
+ * Build the error message for a failed child process. **Never include the
+ * argv** — `docker run ...` invocations carry `-e ANTHROPIC_API_KEY=…` /
+ * `-e OPENAI_API_KEY=…` style flags, and the resulting `Error.message`
+ * propagates all the way to:
+ *
+ *   - the CLI's top-level catch (`console.error("Error:", err.message)`)
+ *     which leaks them onto stderr,
+ *   - `subprocess-*.log` files captured by the evals harness when it
+ *     spawns `vellum hatch` (which then becomes the inlined log on the
+ *     run-detail report page),
+ *   - `run.json#error` and the last-N-lines tail in `progress.ndjson`
+ *     that the evals harness emits for `SubprocessFailedError`.
+ *
+ * The diagnostic substring callers actually grep for ("no such container",
+ * "is not running", "port is already allocated", …) lives in the child's
+ * stderr/stdout, which we DO preserve below. Keep the command name only —
+ * it's enough to disambiguate which step failed without quoting secrets.
+ *
+ * Exported so the unit test can assert no `-e KEY=...` slips back in.
+ */
+export function buildExecErrorMessage(
+  command: string,
+  code: number | null,
+  stderr: string,
+  stdout: string,
+): string {
+  const codeLabel = code === null ? "an unknown code" : `code ${code}`;
+  const header = `${command} exited with ${codeLabel}`;
+  const output = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+  return output ? `${header}\n${output}` : header;
+}
+
 export function exec(
   command: string,
   args: string[],
@@ -25,11 +58,7 @@ export function exec(
       if (code === 0) {
         resolve();
       } else {
-        const msg = `"${command} ${args.join(" ")}" exited with code ${code}`;
-        const output = [stderr.trim(), stdout.trim()]
-          .filter(Boolean)
-          .join("\n");
-        reject(new Error(output ? `${msg}\n${output}` : msg));
+        reject(new Error(buildExecErrorMessage(command, code, stderr, stdout)));
       }
     });
     child.on("error", reject);
@@ -61,8 +90,12 @@ export function execOutput(
       if (code === 0) {
         resolve(stdout.trim());
       } else {
-        const msg = `"${command} ${args.join(" ")}" exited with code ${code}`;
-        reject(new Error(stderr.trim() ? `${msg}\n${stderr.trim()}` : msg));
+        // execOutput intentionally drops stdout from the error message
+        // (callers that read stdout via the success path don't expect
+        // partial stdout to land in error.message). Stderr is enough
+        // for diagnostics, and the no-args-in-message guarantee from
+        // exec() still holds.
+        reject(new Error(buildExecErrorMessage(command, code, stderr, "")));
       }
     });
     child.on("error", reject);

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

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