@vellumai/cli 0.8.4 → 0.8.6

package/src/commands/upgrade.ts

@@ -7,9 +7,10 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  resolveCloud,
   saveAssistantEntry,
+  type AssistantEntry,
 } from "../lib/assistant-config";
-import type { AssistantEntry } from "../lib/assistant-config";
 import {
   captureImageRefs,
   GATEWAY_INTERNAL_PORT,
@@ -145,19 +146,6 @@ function parseArgs(): UpgradeArgs {
   return { name, version, latest, prepare, finalize };
 }
 
-function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) {
-    return entry.cloud;
-  }
-  if (entry.project) {
-    return "gcp";
-  }
-  if (entry.sshUser) {
-    return "custom";
-  }
-  return "local";
-}
-
 /**
  * Resolve which assistant to target for the upgrade command. Priority:
  * 1. Explicit name argument
@@ -512,7 +500,10 @@ async function upgradeDocker(
   } else {
     console.error(`\n❌ Containers failed to become ready within the timeout.`);
 
-    const logDir = await captureUpgradeFailureLogs(res, `${instanceName}-upgrade-failure`);
+    const logDir = await captureUpgradeFailureLogs(
+      res,
+      `${instanceName}-upgrade-failure`,
+    );
     if (logDir) {
       console.log(`📋 Container logs saved to: ${logDir}`);
     }
@@ -938,7 +929,8 @@ async function resolveLatestAndMaybeSelfUpdate(
     );
     if (installResult.error || installResult.status !== 0) {
       const detail =
-        installResult.error?.message ?? `exited with code ${installResult.status}`;
+        installResult.error?.message ??
+        `exited with code ${installResult.status}`;
       console.error(`\n❌ CLI self-update failed: ${detail}`);
       emitCliError("CLI_UPDATE_FAILED", "CLI self-update failed", detail);
       process.exit(1);

package/src/commands/wake.ts

@@ -8,7 +8,7 @@ import {
 } from "../lib/assistant-config.js";
 import { dockerResourceNames, wakeContainers } from "../lib/docker.js";
 import { seedGuardianTokenFromSiblingEnv } from "../lib/guardian-token.js";
-import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
+import { resolveProcessState, stopProcessByPidFile } from "../lib/process";
 import {
   generateLocalSigningKey,
   isAssistantWatchModeAvailable,
@@ -85,36 +85,26 @@ export async function wake(): Promise<void> {
 
   const pidFile = getDaemonPidPath(resources);
 
-  // Check if daemon is already running
   let daemonRunning = false;
-  if (existsSync(pidFile)) {
-    const pidStr = readFileSync(pidFile, "utf-8").trim();
-    const pid = parseInt(pidStr, 10);
-    if (!isNaN(pid)) {
-      try {
-        process.kill(pid, 0);
-        daemonRunning = true;
-        if (watch) {
-          // Restart in watch mode — but only if source files are available.
-          // Watch mode requires bun --watch with .ts sources; packaged desktop
-          // builds only have a compiled binary. Stopping the daemon without a
-          // viable watch-mode path would leave the user with no running assistant.
-          if (!isAssistantWatchModeAvailable()) {
-            console.log(
-              `Assistant running (pid ${pid}) — watch mode not available (no source files). Keeping existing process.`,
-            );
-          } else {
-            console.log(
-              `Assistant running (pid ${pid}) — restarting in watch mode...`,
-            );
-            await stopProcessByPidFile(pidFile, "assistant");
-            daemonRunning = false;
-          }
-        } else {
-          console.log(`Assistant already running (pid ${pid}).`);
-        }
-      } catch {
-        // Process not alive, will start below
+  const daemonState = await resolveProcessState(
+    pidFile,
+    resources.daemonPort,
+    "Assistant",
+  );
+  if (daemonState.status === "healthy") {
+    if (watch && isAssistantWatchModeAvailable()) {
+      console.log(
+        `Assistant running (pid ${daemonState.pid}) — restarting in watch mode...`,
+      );
+      await stopProcessByPidFile(pidFile, "assistant");
+    } else {
+      daemonRunning = true;
+      if (watch) {
+        console.log(
+          `Assistant running (pid ${daemonState.pid}) — watch mode not available (no source files). Keeping existing process.`,
+        );
+      } else {
+        console.log(`Assistant already running (pid ${daemonState.pid}).`);
       }
     }
   }
@@ -153,6 +143,15 @@ export async function wake(): Promise<void> {
     saveAssistantEntry(entry);
   }
 
+  let bootstrapSecret = entry.guardianBootstrapSecret;
+  let bootstrapSecretBackfilled = false;
+  if (!bootstrapSecret) {
+    bootstrapSecret = generateLocalSigningKey();
+    entry.guardianBootstrapSecret = bootstrapSecret;
+    saveAssistantEntry(entry);
+    bootstrapSecretBackfilled = true;
+  }
+
   if (!daemonRunning) {
     await startLocalDaemon(watch, resources, { foreground, signingKey });
   }
@@ -161,26 +160,47 @@ export async function wake(): Promise<void> {
   {
     const vellumDir = join(resources.instanceDir, ".vellum");
     const gatewayPidFile = join(vellumDir, "gateway.pid");
-    const { alive, pid } = isProcessAlive(gatewayPidFile);
-    if (alive) {
-      if (watch) {
-        // Guard gateway restart separately: check gateway source availability.
-        if (!isGatewayWatchModeAvailable()) {
+    const gatewayState = await resolveProcessState(
+      gatewayPidFile,
+      resources.gatewayPort,
+      "Gateway",
+    );
+    const gatewayAlive = gatewayState.status === "healthy";
+    const needsRestart = bootstrapSecretBackfilled && gatewayAlive;
+    if (needsRestart) {
+      const restartWithWatch = watch && isGatewayWatchModeAvailable();
+      if (restartWithWatch) {
+        console.log(
+          `Gateway running (pid ${gatewayState.pid}) — restarting to apply bootstrap secret...`,
+        );
+      } else {
+        console.log(
+          `Gateway running (pid ${gatewayState.pid}) — restarting without watch mode to apply bootstrap secret...`,
+        );
+      }
+      await stopProcessByPidFile(gatewayPidFile, "gateway");
+      await startGateway(restartWithWatch, resources, {
+        signingKey,
+        bootstrapSecret,
+      });
+    } else if (gatewayAlive) {
+      if (watch && isGatewayWatchModeAvailable()) {
+        console.log(
+          `Gateway running (pid ${gatewayState.pid}) — restarting in watch mode...`,
+        );
+        await stopProcessByPidFile(gatewayPidFile, "gateway");
+        await startGateway(watch, resources, { signingKey, bootstrapSecret });
+      } else {
+        if (watch) {
           console.log(
-            `Gateway running (pid ${pid}) — watch mode not available (no source files). Keeping existing process.`,
+            `Gateway running (pid ${gatewayState.pid}) — watch mode not available (no source files). Keeping existing process.`,
           );
         } else {
-          console.log(
-            `Gateway running (pid ${pid}) — restarting in watch mode...`,
-          );
-          await stopProcessByPidFile(gatewayPidFile, "gateway");
-          await startGateway(watch, resources, { signingKey });
+          console.log(`Gateway already running (pid ${gatewayState.pid}).`);
         }
-      } else {
-        console.log(`Gateway already running (pid ${pid}).`);
       }
     } else {
-      await startGateway(watch, resources, { signingKey });
+      await startGateway(watch, resources, { signingKey, bootstrapSecret });
     }
   }
 
@@ -196,7 +216,10 @@ export async function wake(): Promise<void> {
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
   const workspaceDir = join(resources.instanceDir, ".vellum", "workspace");
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort, workspaceDir);
+  const ngrokChild = await maybeStartNgrokTunnel(
+    resources.gatewayPort,
+    workspaceDir,
+  );
   if (ngrokChild?.pid) {
     const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
     writeFileSync(ngrokPidFile, String(ngrokChild.pid));

package/src/index.ts

@@ -7,6 +7,8 @@ import { client } from "./commands/client";
 import { env } from "./commands/env";
 import { events } from "./commands/events";
 import { exec } from "./commands/exec";
+import { flags } from "./commands/flags";
+import { gateway } from "./commands/gateway";
 import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
 import { logs } from "./commands/logs";
@@ -14,6 +16,7 @@ import { message } from "./commands/message";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
 import { restore } from "./commands/restore";
+import { roadmap } from "./commands/roadmap";
 import { retire } from "./commands/retire";
 import { rollback } from "./commands/rollback";
 import { setup } from "./commands/setup";
@@ -36,6 +39,8 @@ const commands = {
   env,
   events,
   exec,
+  flags,
+  gateway,
   hatch,
   login,
   logout,
@@ -45,6 +50,7 @@ const commands = {
   recover,
   restore,
   retire,
+  roadmap,
   rollback,
   setup,
   sleep,
@@ -70,6 +76,8 @@ function printHelp(): void {
   console.log("  env      Manage the default CLI environment");
   console.log("  events   Stream events from a running assistant");
   console.log("  exec     Execute a command inside an assistant's container");
+  console.log("  flags    Show and toggle feature flags");
+  console.log("  gateway  Gateway management commands");
   console.log("  hatch    Create a new assistant instance");
   console.log("  logs     View logs from an assistant instance");
   console.log("  login    Log in to the Vellum platform");
@@ -83,6 +91,7 @@ function printHelp(): void {
     "  restore  Restore data (and optionally version) from a .vbundle backup",
   );
   console.log("  retire   Delete an assistant instance");
+  console.log("  roadmap  Manage roadmap items");
   console.log("  rollback  Roll back an assistant to a previous version");
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");

package/src/lib/__tests__/port-allocator.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import { createServer, type Server } from "net";
+
+import { findOpenPort } from "../port-allocator.js";
+
+const HOST = "127.0.0.1";
+
+async function bindBlocker(port: number, host: string = HOST): Promise<Server> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.once("listening", () => resolve(server));
+    server.listen(port, host);
+  });
+}
+
+async function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((err) => (err ? reject(err) : resolve()));
+  });
+}
+
+async function getEphemeralPort(): Promise<number> {
+  const server = await new Promise<Server>((resolve, reject) => {
+    const s = createServer();
+    s.once("error", reject);
+    s.once("listening", () => resolve(s));
+    s.listen(0, HOST);
+  });
+  const addr = server.address();
+  if (!addr || typeof addr === "string" || addr.port == null) {
+    throw new Error("Could not obtain ephemeral port");
+  }
+  const port = addr.port;
+  await closeServer(server);
+  return port;
+}
+
+describe("findOpenPort", () => {
+  test("returns the preferred port when it is free", async () => {
+    const port = await getEphemeralPort();
+    const result = await findOpenPort(port, { host: HOST });
+    expect(result).toBe(port);
+  });
+
+  test("walks past an in-use port and returns the next free one", async () => {
+    const blocked = await getEphemeralPort();
+    const blocker = await bindBlocker(blocked);
+    try {
+      const result = await findOpenPort(blocked, { host: HOST });
+      expect(result).toBeGreaterThan(blocked);
+      expect(result).toBeLessThanOrEqual(blocked + 50);
+    } finally {
+      await closeServer(blocker);
+    }
+  });
+
+  test("walks past two consecutive in-use ports", async () => {
+    const first = await getEphemeralPort();
+    const blockerA = await bindBlocker(first);
+    let blockerB: Server | null = null;
+    try {
+      // Best-effort grab of the next consecutive port; if the kernel
+      // handed it to someone else just before we got here, that's still a
+      // valid "two consecutive blockers" scenario for the walk.
+      try {
+        blockerB = await bindBlocker(first + 1);
+      } catch {
+        blockerB = null;
+      }
+      const result = await findOpenPort(first, { host: HOST });
+      expect(result).toBeGreaterThan(first + (blockerB ? 1 : 0));
+    } finally {
+      await closeServer(blockerA);
+      if (blockerB) await closeServer(blockerB);
+    }
+  });
+
+  test("throws when the entire requested window is in use", async () => {
+    const blocked = await getEphemeralPort();
+    const blocker = await bindBlocker(blocked);
+    try {
+      await expect(
+        findOpenPort(blocked, { host: HOST, maxAttempts: 1 }),
+      ).rejects.toThrow(/no open port/i);
+    } finally {
+      await closeServer(blocker);
+    }
+  });
+
+  test("rejects non-integer or out-of-range preferred port", async () => {
+    await expect(findOpenPort(0, { host: HOST })).rejects.toThrow(
+      /not a valid TCP port/i,
+    );
+    await expect(findOpenPort(65536, { host: HOST })).rejects.toThrow(
+      /not a valid TCP port/i,
+    );
+    await expect(findOpenPort(1.5, { host: HOST })).rejects.toThrow(
+      /not a valid TCP port/i,
+    );
+  });
+
+  test("rejects non-positive maxAttempts", async () => {
+    await expect(
+      findOpenPort(20100, { host: HOST, maxAttempts: 0 }),
+    ).rejects.toThrow(/maxAttempts/i);
+  });
+
+  test("does not leak the probe port — port is rebindable after resolution", async () => {
+    const port = await getEphemeralPort();
+    const found = await findOpenPort(port, { host: HOST });
+    expect(found).toBe(port);
+    // If the probe leaked a listener on `port`, this would throw EADDRINUSE.
+    const reuse = await bindBlocker(found);
+    await closeServer(reuse);
+  });
+});

package/src/lib/__tests__/step-runner.test.ts

@@ -0,0 +1,133 @@
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { describe, expect, it } from "bun:test";
+
+import {
+  buildExecErrorMessage,
+  exec,
+  execOutput,
+  execWithStdin,
+} from "../step-runner";
+
+describe("buildExecErrorMessage", () => {
+  it("omits the argv from the header so secrets in args can't leak", () => {
+    // Realistic shape — docker hatch invocations pass `-e <NAME>=<val>`
+    // flags inline. If we ever regress and put argv in the header, this
+    // assertion catches it immediately.
+    const msg = buildExecErrorMessage("docker", 125, "stderr text", "");
+    expect(msg).not.toContain("ANTHROPIC_API_KEY");
+    expect(msg).not.toContain("OPENAI_API_KEY");
+    expect(msg.startsWith("docker exited with code 125")).toBe(true);
+  });
+
+  it("appends stderr below the header when present", () => {
+    const msg = buildExecErrorMessage("docker", 125, "  bind failed\n", "");
+    expect(msg).toBe("docker exited with code 125\nbind failed");
+  });
+
+  it("appends stdout when stderr is empty", () => {
+    const msg = buildExecErrorMessage("docker", 1, "", "stdout-only\n");
+    expect(msg).toBe("docker exited with code 1\nstdout-only");
+  });
+
+  it("appends both streams joined by newline when both present", () => {
+    const msg = buildExecErrorMessage("docker", 1, "stderr-line", "stdout-line");
+    expect(msg).toBe("docker exited with code 1\nstderr-line\nstdout-line");
+  });
+
+  it("collapses an empty output to just the header", () => {
+    const msg = buildExecErrorMessage("docker", 1, "  ", "\n");
+    expect(msg).toBe("docker exited with code 1");
+  });
+
+  it("handles a null exit code (signal-terminated child)", () => {
+    const msg = buildExecErrorMessage("docker", null, "killed", "");
+    expect(msg).toBe("docker exited with an unknown code\nkilled");
+  });
+});
+
+describe("exec — secret leak regression", () => {
+  it("rejects with an Error whose message contains neither the args nor any -e KEY=VALUE pair", async () => {
+    // The classic hatch failure shape: docker invoked with several
+    // -e flags, exiting non-zero. Without the fix, args.join(" ")
+    // would put `-e ANTHROPIC_API_KEY=sk-ant-…` into err.message.
+    const fakeSecret = "sk-ant-this-should-never-appear-in-logs";
+    try {
+      await exec("sh", [
+        "-c",
+        `echo "bind for 0.0.0.0:20100 failed: port is already allocated" 1>&2 && exit 125`,
+        "-e",
+        `ANTHROPIC_API_KEY=${fakeSecret}`,
+      ]);
+      throw new Error("exec should have rejected");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      expect(message).not.toContain(fakeSecret);
+      expect(message).not.toContain("ANTHROPIC_API_KEY");
+      expect(message).toContain("sh exited with code 125");
+      expect(message).toContain("port is already allocated");
+    }
+  });
+});
+
+describe("execWithStdin — pipes input + no secret leak in errors", () => {
+  it("writes the supplied input to the child's stdin", async () => {
+    // Use sh `cat > path` to capture stdin to a real file we can inspect.
+    // Mirrors the Docker-hatch overlay-staging call site shape.
+    const workDir = mkdtempSync(join(tmpdir(), "step-runner-stdin-"));
+    const dest = join(workDir, "captured.txt");
+    try {
+      const payload = '{"hello":"world"}\n';
+      await execWithStdin("sh", ["-c", `cat > ${dest}`], payload);
+      expect(readFileSync(dest, "utf-8")).toBe(payload);
+    } finally {
+      rmSync(workDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects with an Error whose message contains neither the args nor any -e KEY=VALUE pair", async () => {
+    const fakeSecret = "sk-anthropic-stdin-canary";
+    try {
+      await execWithStdin(
+        "sh",
+        [
+          "-c",
+          'echo "permission denied while trying to connect to docker daemon" 1>&2 && exit 1',
+          "-e",
+          `ANTHROPIC_API_KEY=${fakeSecret}`,
+        ],
+        "",
+      );
+      throw new Error("execWithStdin should have rejected");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      expect(message).not.toContain(fakeSecret);
+      expect(message).not.toContain("ANTHROPIC_API_KEY");
+      expect(message).toContain("sh exited with code 1");
+      expect(message).toContain("permission denied");
+    }
+  });
+});
+
+describe("execOutput — secret leak regression", () => {
+  it("rejects with an Error whose message contains neither the args nor any -e KEY=VALUE pair", async () => {
+    const fakeSecret = "sk-openai-leak-canary";
+    try {
+      await execOutput("sh", [
+        "-c",
+        `echo "no such container" 1>&2 && exit 1`,
+        "-e",
+        `OPENAI_API_KEY=${fakeSecret}`,
+      ]);
+      throw new Error("execOutput should have rejected");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      expect(message).not.toContain(fakeSecret);
+      expect(message).not.toContain("OPENAI_API_KEY");
+      expect(message).toContain("sh exited with code 1");
+      expect(message).toContain("no such container");
+    }
+  });
+});

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/assistant-config.ts

@@ -559,6 +559,19 @@ export function resolveCloud(entry: AssistantEntry): string {
   return "local";
 }
 
+/**
+ * Extract the hostname from a URL string. Falls back to stripping the scheme
+ * and taking the hostname portion if URL parsing fails.
+ */
+export function extractHostFromUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname;
+  } catch {
+    return url.replace(/^https?:\/\//, "").split(":")[0];
+  }
+}
+
 export function saveAssistantEntry(entry: AssistantEntry): void {
   const entries = readAssistants().filter(
     (e) => e.assistantId !== entry.assistantId,

package/src/lib/config-utils.ts

@@ -35,6 +35,21 @@ export function buildNestedConfig(
 /**
  * Ensure hatch always provides enough initial LLM config for the assistant to
  * detect a fresh off-platform hatch and seed BYOK profiles.
+ *
+ * @deprecated Part of the workspace-config overlay path — a CLI→Assistant
+ * side channel that bypasses the Assistant's public APIs and has no
+ * equivalent in web/desktop. Two replacement paths are on the table:
+ *
+ *   1. Post-hatch API calls — the CLI calls public Assistant routes after
+ *      boot (`POST /v1/secrets`, plus a small read-only endpoint that
+ *      returns the canonical inference-profile templates so the CLI can
+ *      PATCH them in). See the closed alternatives in PR #32061 and
+ *      PR #32131 for the shape this would take.
+ *   2. Move inference-profile seeds out of workspace config and into
+ *      Assistant code, so there is nothing for the CLI to inject in the
+ *      first place.
+ *
+ * Either path removes the need for this helper.
  */
 export function buildHatchConfigValues(
   configValues: Record<string, string>,
@@ -52,15 +67,21 @@ export function buildHatchConfigValues(
 
 /**
  * Write arbitrary key-value pairs to a temporary JSON file and return its
- * path. The caller passes this path to the daemon via the
- * VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH env var so the daemon can merge the
- * values into its workspace config on first boot.
+ * path. The caller is responsible for getting the file to the daemon — for
+ * the local hatch flow that means setting `VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH`
+ * on the daemon process; for the Docker hatch flow the caller stages the
+ * file into the workspace volume so the rename-after-consume step in
+ * `mergeDefaultWorkspaceConfig` is a same-filesystem rename.
  *
  * Keys use dot-notation to address nested fields. For example:
  *   "llm.default.provider" → {llm: {default: {provider: ...}}}
  *   "llm.default.model"    → {llm: {default: {model: ...}}}
  *
  * Returns undefined when configValues is empty (nothing to write).
+ *
+ * @deprecated See {@link buildHatchConfigValues} for the replacement
+ * direction. This overlay path is a CLI→Assistant side channel and will be
+ * removed once one of the documented replacements lands.
  */
 export function writeInitialConfig(
   configValues: Record<string, string>,