@vellumai/cli 0.8.5 → 0.8.7

package/src/lib/assistant-config.ts

@@ -10,6 +10,8 @@ import {
 import { homedir } from "os";
 import { dirname, join } from "path";
 
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./constants.js";
 import {
   getDefaultPorts,
@@ -18,8 +20,6 @@ import {
   getMultiInstanceDir,
 } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
-import { SEEDS } from "./environments/seeds.js";
-import type { EnvironmentDefinition } from "./environments/types.js";
 import { probePort } from "./port-probe.js";
 
 /**
@@ -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,
@@ -618,7 +631,7 @@ export async function allocateLocalResources(
 
   // Env-aware bases: non-prod envs sit in their own 1000-port window so
   // running prod and staging assistants side-by-side doesn't collide. See
-  // `environments/seeds.ts:portBlock` for the layout.
+  // the `@vellumai/environments` `portBlock` layout.
   const basePorts = getDefaultPorts(env);
   const daemonPort = await findAvailablePort(basePorts.daemon, reservedPorts);
   const gatewayPort = await findAvailablePort(basePorts.gateway, [

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>,

package/src/lib/docker.ts

@@ -1,5 +1,11 @@
 import { randomBytes } from "crypto";
-import { chmodSync, existsSync, mkdirSync, watch as fsWatch } from "fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  watch as fsWatch,
+} from "fs";
 import { arch, platform } from "os";
 import { dirname, join, resolve } from "path";
 
@@ -12,6 +18,7 @@ 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,7 +42,7 @@ import {
   resolveHatchProvider,
 } from "./provider-secrets.js";
 import { findOpenPort } from "./port-allocator.js";
-import { exec, execOutput } from "./step-runner";
+import { exec, execOutput, execWithStdin } from "./step-runner";
 import {
   closeLogFile,
   openLogFile,
@@ -1164,11 +1171,53 @@ export async function hatchDocker(
       "chown 1001:1001 /workspace /run/assistant-ipc /run/gateway-ipc",
     ]);
 
-    // 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.
+    // Stage the BYOK default-workspace-config overlay *inside* the workspace
+    // volume so the daemon's startup loader can consume it. The loader
+    // (`mergeDefaultWorkspaceConfig` in assistant/src/config/loader.ts) does:
+    //   1. JSON.parse + deep-merge into the workspace's config.json.
+    //   2. `renameSync(defaultConfigPath, <workspace>/default-config.json)`
+    //      to mark the overlay consumed so subsequent restarts skip it.
+    //
+    // The rename must be same-filesystem. Bind-mounting the host file into
+    // `/tmp/...` (the pre-#32025 design) crossed filesystems and silently
+    // failed with EXDEV, so every `docker start` re-applied the overlay.
+    // Staging into the workspace volume keeps the rename in-place.
+    //
+    // Streaming the JSON via stdin (instead of bind-mounting the host file
+    // into the staging container) sidesteps macOS Colima's virtiofs share,
+    // which doesn't expose `/var/folders/...` (where `os.tmpdir()` resolves
+    // on macOS) and would otherwise materialize an empty directory at the
+    // bind-mount target.
+    //
+    // @deprecated stopgap. Replacement direction is one of:
+    //   1. Post-hatch API calls (POST /v1/secrets + a small endpoint that
+    //      returns canonical inference-profile templates).
+    //   2. Move inference-profile seeds out of workspace config and into
+    //      Assistant code, eliminating the overlay entirely.
+    // See `cli/src/lib/config-utils.ts` JSDoc for context.
+    const hatchConfigValues = buildHatchConfigValues(configValues, provider);
+    const hostOverlayPath = writeInitialConfig(hatchConfigValues);
+    const stagedOverlayInContainer = "/workspace/.default-config-overlay.json";
+    const extraAssistantEnv: Record<string, string> = {};
+    if (hostOverlayPath) {
+      await execWithStdin(
+        "docker",
+        [
+          "run",
+          "--rm",
+          "-i",
+          "-v",
+          `${res.workspaceVolume}:/workspace`,
+          "busybox",
+          "sh",
+          "-c",
+          `cat > ${stagedOverlayInContainer} && chown 1001:1001 ${stagedOverlayInContainer}`,
+        ],
+        readFileSync(hostOverlayPath, "utf-8"),
+      );
+      extraAssistantEnv.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
+        stagedOverlayInContainer;
+    }
 
     const cesServiceToken = randomBytes(32).toString("hex");
     const signingKey = randomBytes(32).toString("hex");
@@ -1190,6 +1239,7 @@ export async function hatchDocker(
         signingKey,
         bootstrapSecret,
         cesServiceToken,
+        extraAssistantEnv,
         gatewayPort,
         imageTags,
         instanceName,

package/src/lib/environments/__tests__/paths.test.ts

@@ -27,7 +27,8 @@ const {
   getLockfilePaths,
   getMultiInstanceDir,
 } = await import("../paths.js");
-type EnvironmentDefinition = import("../types.js").EnvironmentDefinition;
+type EnvironmentDefinition =
+  import("@vellumai/environments").EnvironmentDefinition;
 
 const prod: EnvironmentDefinition = {
   name: "production",

package/src/lib/environments/__tests__/seeds.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, test } from "bun:test";
 
+import { SEEDS } from "@vellumai/environments";
+
 import { getDefaultPorts } from "../paths.js";
-import { SEEDS } from "../seeds.js";
 
 describe("SEEDS port blocks", () => {
   test("production uses the legacy (pre-MVP) port layout", () => {

package/src/lib/environments/paths.ts

@@ -1,7 +1,7 @@
 import { homedir } from "os";
 import { join } from "path";
 
-import type { EnvironmentDefinition, PortMap } from "./types.js";
+import type { EnvironmentDefinition, PortMap } from "@vellumai/environments";
 
 const PRODUCTION_ENVIRONMENT_NAME = "production";
 

package/src/lib/environments/resolve.ts

@@ -8,8 +8,7 @@ import {
 import { homedir } from "os";
 import { dirname, join } from "path";
 
-import { SEEDS } from "./seeds.js";
-import type { EnvironmentDefinition } from "./types.js";
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
 
 const DEFAULT_ENVIRONMENT_NAME = "production";
 
@@ -115,7 +114,7 @@ export function getCurrentEnvironment(
       // writers don't end up in disjoint states on a typo.
       process.stderr.write(
         `warning: unknown environment "${name}"; falling back to "${DEFAULT_ENVIRONMENT_NAME}". ` +
-          `Add it to cli/src/lib/environments/seeds.ts and rebuild if this was intentional.\n`,
+          `Add it to packages/environments/src/seeds.ts and rebuild if this was intentional.\n`,
       );
     }
     const fallback = SEEDS[DEFAULT_ENVIRONMENT_NAME];
@@ -174,5 +173,3 @@ export function resolveEnvironmentSource(override?: string): {
   }
   return { name: DEFAULT_ENVIRONMENT_NAME, source: "default" };
 }
-
-

package/src/lib/guardian-token.ts

@@ -11,9 +11,10 @@ import {
 import { platform } from "os";
 import { dirname, join } from "path";
 
+import { SEEDS } from "@vellumai/environments";
+
 import { getConfigDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
-import { SEEDS } from "./environments/seeds.js";
 
 const DEVICE_ID_SALT = "vellum-assistant-host-id";
 
@@ -176,7 +177,8 @@ export async function refreshGuardianToken(
   // Gateway persists expiresAt as epoch-ms numbers; Date.parse("1234567890000")
   // returns NaN. new Date() accepts both ISO strings and epoch-ms numbers.
   const refreshExpiry = new Date(tokenData.refreshTokenExpiresAt).getTime();
-  if (!Number.isFinite(refreshExpiry) || refreshExpiry <= Date.now()) return null;
+  if (!Number.isFinite(refreshExpiry) || refreshExpiry <= Date.now())
+    return null;
 
   try {
     const response = await fetch(`${gatewayUrl}/v1/guardian/refresh`, {
@@ -191,11 +193,16 @@ export async function refreshGuardianToken(
 
     const json = (await response.json()) as Record<string, unknown>;
     const refreshed: GuardianTokenData = {
-      guardianPrincipalId: (json.guardianPrincipalId as string) ?? tokenData.guardianPrincipalId,
+      guardianPrincipalId:
+        (json.guardianPrincipalId as string) ?? tokenData.guardianPrincipalId,
       accessToken: json.accessToken as string,
-      accessTokenExpiresAt: (json.accessTokenExpiresAt as string | number) ?? tokenData.accessTokenExpiresAt,
+      accessTokenExpiresAt:
+        (json.accessTokenExpiresAt as string | number) ??
+        tokenData.accessTokenExpiresAt,
       refreshToken: (json.refreshToken as string) ?? tokenData.refreshToken,
-      refreshTokenExpiresAt: (json.refreshTokenExpiresAt as string | number) ?? tokenData.refreshTokenExpiresAt,
+      refreshTokenExpiresAt:
+        (json.refreshTokenExpiresAt as string | number) ??
+        tokenData.refreshTokenExpiresAt,
       refreshAfter: (json.refreshAfter as string) ?? tokenData.refreshAfter,
       isNew: false,
       deviceId: tokenData.deviceId,

package/src/lib/hatch-local.ts

@@ -33,7 +33,10 @@ import {
 import { generateInstanceName } from "./random-name.js";
 import { leaseGuardianToken } from "./guardian-token.js";
 import { archiveLogFile, resetLogFile } from "./xdg-log.js";
-import { emitProgress } from "./desktop-progress.js";
+import {
+  consoleLifecycleReporter,
+  type LifecycleReporter,
+} from "./lifecycle-reporter.js";
 import {
   configureHatchProviderApiKey,
   formatProviderName,
@@ -134,6 +137,25 @@ function installCLISymlink(): void {
 
 export interface HatchLocalOptions {
   setupProviderCredentials?: boolean;
+  /**
+   * Sink for progress and log output. Defaults to the console reporter so CLI
+   * callers keep their existing terminal output; in-process callers can inject
+   * their own reporter to consume progress without writing to stdout.
+   */
+  reporter?: LifecycleReporter;
+}
+
+export interface HatchLocalResult {
+  assistantId: string;
+  runtimeUrl: string;
+  localUrl: string;
+  species: Species;
+  /**
+   * Guardian access token leased during hatch, when the lease succeeded. The
+   * full token pair is persisted to disk regardless; this is surfaced so an
+   * in-process caller can prime a connection without re-reading the file.
+   */
+  guardianAccessToken?: string;
 }
 
 export async function hatchLocal(
@@ -143,7 +165,8 @@ export async function hatchLocal(
   keepAlive: boolean = false,
   configValues: Record<string, string> = {},
   options: HatchLocalOptions = {},
-): Promise<void> {
+): Promise<HatchLocalResult> {
+  const reporter = options.reporter ?? consoleLifecycleReporter;
   const provider =
     options.setupProviderCredentials === false
       ? undefined
@@ -153,7 +176,7 @@ export async function hatchLocal(
     name ?? process.env.VELLUM_ASSISTANT_NAME,
   );
 
-  emitProgress(1, 6, "Allocating resources...");
+  reporter.progress(1, 6, "Allocating resources...");
 
   const existing = findAssistantByName(instanceName);
   if (existing && (!existing.cloud || existing.cloud === "local")) {
@@ -175,43 +198,47 @@ export async function hatchLocal(
   archiveLogFile("hatch.log", logsDir);
   resetLogFile("hatch.log");
 
-  console.log(`🥚 Hatching local assistant: ${instanceName}`);
-  console.log(`   Species: ${species}`);
-  console.log("");
+  reporter.log(`🥚 Hatching local assistant: ${instanceName}`);
+  reporter.log(`   Species: ${species}`);
+  reporter.log("");
 
   const apiKeyCheck = checkProviderApiKey();
   if (!apiKeyCheck.hasKey) {
-    console.warn(
+    reporter.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("");
+    reporter.warn("  To fix, export your key before running vellum hatch:");
+    reporter.warn("  export ANTHROPIC_API_KEY=<your-key>");
+    reporter.warn("");
   }
 
   if (!process.env.APP_VERSION) {
     process.env.APP_VERSION = cliPkg.version;
   }
 
-  emitProgress(2, 6, "Writing configuration...");
+  reporter.progress(2, 6, "Writing configuration...");
   const hatchConfigValues = buildHatchConfigValues(configValues, provider);
   const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
 
-  emitProgress(3, 6, "Starting assistant...");
+  reporter.progress(3, 6, "Starting assistant...");
   const signingKey = generateLocalSigningKey();
+  const bootstrapSecret = generateLocalSigningKey();
   await startLocalDaemon(watch, resources, {
     defaultWorkspaceConfigPath,
     signingKey,
   });
 
-  emitProgress(4, 6, "Starting gateway...");
+  reporter.progress(4, 6, "Starting gateway...");
   let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
   try {
-    runtimeUrl = await startGateway(watch, resources, { signingKey });
+    runtimeUrl = await startGateway(watch, resources, {
+      signingKey,
+      bootstrapSecret,
+    });
   } catch (error) {
     // Gateway failed — stop the daemon we just started so we don't leave
     // orphaned processes with no lock file entry.
-    console.error(
+    reporter.error(
       `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
     );
     await stopLocalProcesses(resources);
@@ -222,24 +249,28 @@ export async function hatchLocal(
   // instead of hitting /v1/guardian/init itself. Use loopback to satisfy
   // the daemon's local-only check — the mDNS runtimeUrl resolves to a LAN
   // IP which the daemon rejects as non-loopback.
-  emitProgress(5, 6, "Securing connection...");
+  reporter.progress(5, 6, "Securing connection...");
   const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
   const maxLeaseAttempts = 3;
   let guardianAccessToken: string | undefined;
   for (let attempt = 1; attempt <= maxLeaseAttempts; attempt++) {
     try {
-      const tokenData = await leaseGuardianToken(loopbackUrl, instanceName);
+      const tokenData = await leaseGuardianToken(
+        loopbackUrl,
+        instanceName,
+        bootstrapSecret,
+      );
       guardianAccessToken = tokenData.accessToken;
       break;
     } catch (err) {
       if (attempt < maxLeaseAttempts) {
         const delayMs = 2000 * 2 ** (attempt - 1);
-        console.error(
+        reporter.error(
           `⚠️  Guardian token lease attempt ${attempt}/${maxLeaseAttempts} failed — retrying in ${delayMs / 1000}s: ${err}`,
         );
         await new Promise((r) => setTimeout(r, delayMs));
       } else {
-        console.error(
+        reporter.error(
           `⚠️  Guardian token lease failed after ${maxLeaseAttempts} attempts: ${err}\n` +
             `   The assistant is running but guardian-token.json was not written.\n` +
             `   If the desktop app loses its stored credentials, re-hatch to recover.`,
@@ -257,9 +288,10 @@ export async function hatchLocal(
     species,
     hatchedAt: new Date().toISOString(),
     resources: { ...resources, signingKey },
+    guardianBootstrapSecret: bootstrapSecret,
   };
 
-  emitProgress(6, 6, "Saving configuration...");
+  reporter.progress(6, 6, "Saving configuration...");
   saveAssistantEntry(localEntry);
   setActiveAssistant(instanceName);
 
@@ -268,13 +300,13 @@ export async function hatchLocal(
   }
 
   if (provider !== undefined && provider !== null && !guardianAccessToken) {
-    console.error(
+    reporter.error(
       `⚠️  Provider credential setup skipped because the guardian token was not leased.\n` +
         `   The assistant is still hatched. Run \`vellum setup --provider ${provider}\` after fixing the connection.`,
     );
   } else if (provider !== undefined) {
-    console.log("");
-    console.log(
+    reporter.log("");
+    reporter.log(
       provider === null
         ? "Checking provider credentials..."
         : `Checking ${formatProviderName(provider)} credentials...`,
@@ -287,14 +319,22 @@ export async function hatchLocal(
     });
   }
 
-  console.log("");
-  console.log(`✅ Local assistant hatched!`);
-  console.log("");
-  console.log("Instance details:");
-  console.log(`  Name: ${instanceName}`);
-  console.log(`  Runtime: ${runtimeUrl}`);
-  console.log("");
-  logHatchNextSteps(console.log, instanceName);
+  reporter.log("");
+  reporter.log(`✅ Local assistant hatched!`);
+  reporter.log("");
+  reporter.log("Instance details:");
+  reporter.log(`  Name: ${instanceName}`);
+  reporter.log(`  Runtime: ${runtimeUrl}`);
+  reporter.log("");
+  logHatchNextSteps((message) => reporter.log(message), instanceName);
+
+  const result: HatchLocalResult = {
+    assistantId: instanceName,
+    runtimeUrl,
+    localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
+    species,
+    guardianAccessToken,
+  };
 
   if (keepAlive) {
     const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
@@ -304,7 +344,7 @@ export async function hatchLocal(
     let consecutiveFailures = 0;
 
     const shutdown = async (): Promise<void> => {
-      console.log("\nShutting down local processes...");
+      reporter.log("\nShutting down local processes...");
       await stopLocalProcesses(resources);
       process.exit(0);
     };
@@ -328,7 +368,7 @@ export async function hatchLocal(
         consecutiveFailures++;
       }
       if (consecutiveFailures >= MAX_FAILURES) {
-        console.log(
+        reporter.log(
           `\n⚠️  ${healthTarget} stopped responding — shutting down.`,
         );
         await stopLocalProcesses(resources);
@@ -336,4 +376,6 @@ export async function hatchLocal(
       }
     }
   }
+
+  return result;
 }

package/src/lib/http-client.ts

@@ -8,8 +8,6 @@ export function buildDaemonUrl(port: number): string {
 /**
  * Perform an HTTP health check against the daemon's `/healthz` endpoint.
  * Returns true if the daemon responds with HTTP 200, false otherwise.
- *
- * This replaces the socket-based `isSocketResponsive()` check.
  */
 export async function httpHealthCheck(
   port: number,
@@ -28,7 +26,7 @@ export async function httpHealthCheck(
 
 /**
  * Poll the daemon's `/healthz` endpoint until it responds with 200 or the
- * timeout is reached. This replaces `waitForSocketFile()`.
+ * timeout is reached.
  *
  * Returns true if the daemon became healthy within the timeout, false otherwise.
  */

package/src/lib/lifecycle-reporter.ts

@@ -0,0 +1,31 @@
+import { emitProgress } from "./desktop-progress.js";
+
+/**
+ * Sink for the human-facing and structured output of long-running lifecycle
+ * operations (hatch, retire). Injecting it lets an in-process caller (e.g. a
+ * desktop main process embedding these functions) observe progress without the
+ * operation writing to the terminal, while the CLI keeps its existing stdout.
+ */
+export interface LifecycleReporter {
+  /**
+   * Coarse step progress. The CLI reporter mirrors this to the desktop
+   * `HATCH_PROGRESS:` stdout channel.
+   */
+  progress(step: number, total: number, label: string): void;
+  log(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+/**
+ * Reporter used by the CLI commands: human-readable lines to the console plus
+ * structured step events on the desktop progress channel. Reproduces the exact
+ * terminal output — and the `HATCH_PROGRESS:` lines under `VELLUM_DESKTOP_APP` —
+ * that existing subprocess consumers parse.
+ */
+export const consoleLifecycleReporter: LifecycleReporter = {
+  progress: (step, total, label) => emitProgress(step, total, label),
+  log: (message) => console.log(message),
+  warn: (message) => console.warn(message),
+  error: (message) => console.error(message),
+};