@vellumai/cli 0.8.2 → 0.8.4

package/src/lib/docker.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "crypto";
 import { chmodSync, existsSync, mkdirSync, watch as fsWatch } from "fs";
 import { arch, platform } from "os";
-import { dirname, join } from "path";
+import { dirname, join, resolve } from "path";
 
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
 import cliPkg from "../../package.json";
@@ -12,15 +12,29 @@ import {
   setActiveAssistant,
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
-import { writeInitialConfig } from "./config-utils";
+import { buildHatchConfigValues, writeInitialConfig } from "./config-utils";
 import { buildServiceRunArgs } from "./statefulset.js";
 import type { Species } from "./constants";
 import { getDefaultPorts } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { leaseGuardianToken } from "./guardian-token";
+import { logHatchNextSteps } from "./hatch-next-steps.js";
 import { isVellumProcess, stopProcess } from "./process";
 import { generateInstanceName } from "./random-name";
-import { resolveImageRefs } from "./platform-releases.js";
+import {
+  HOST_IMAGE_LOADER_URL,
+  isLocalBuildRef,
+  loadImageViaHost,
+} from "./host-image-loader.js";
+import {
+  fetchLatestStableVersion,
+  resolveImageRefs,
+} from "./platform-releases.js";
+import {
+  configureHatchProviderApiKey,
+  formatProviderName,
+  resolveHatchProvider,
+} from "./provider-secrets.js";
 import { exec, execOutput } from "./step-runner";
 import {
   closeLogFile,
@@ -40,10 +54,13 @@ export const DOCKERHUB_IMAGES: Record<ServiceName, string> = {
 };
 
 /** Internal ports exposed by each service's Dockerfile. Re-exported from environments/paths.ts. */
-export { ASSISTANT_INTERNAL_PORT, GATEWAY_INTERNAL_PORT } from "./environments/paths.js";
+export {
+  ASSISTANT_INTERNAL_PORT,
+  GATEWAY_INTERNAL_PORT,
+} from "./environments/paths.js";
 
 /** Max time to wait for the assistant container to emit the readiness sentinel. */
-export const DOCKER_READY_TIMEOUT_MS = 3 * 60 * 1000;
+export const DOCKER_READY_TIMEOUT_MS = 5 * 60 * 1000;
 
 /** Default virtual-camera device path. Overridable via `VELLUM_AVATAR_DEVICE`. */
 const DEFAULT_AVATAR_DEVICE_PATH = "/dev/video10";
@@ -247,6 +264,28 @@ function ensureLocalBinOnPath(): void {
   }
 }
 
+export interface HatchDockerOptions {
+  setupProviderCredentials?: boolean;
+}
+
+export type DockerProviderCredentialSetupAction =
+  | "configure"
+  | "defer"
+  | "missing-token"
+  | "skip";
+
+export function resolveDockerProviderCredentialSetupAction(options: {
+  provider: string | null | undefined;
+  guardianAccessToken?: string;
+  detached: boolean;
+}): DockerProviderCredentialSetupAction {
+  if (options.provider === undefined) return "skip";
+  if (options.provider === null) return options.detached ? "skip" : "configure";
+  if (options.detached) return "defer";
+  if (!options.guardianAccessToken) return "missing-token";
+  return "configure";
+}
+
 /**
  * Checks whether the `docker` CLI and daemon are available on the system.
  * Installs Colima and Docker via direct binary download if missing (no sudo
@@ -461,6 +500,37 @@ function hasFullSourceTree(root: string): boolean {
   return existsSync(join(root, "assistant", "package.json"));
 }
 
+/**
+ * Decide which image-source path `hatchDocker` should take given the user
+ * flags and a probe result for the source tree.
+ *
+ * - `watch` always wants source-build *and* file-watcher (when the source
+ *   tree is available).
+ * - `buildFromSource` wants source-build but no watcher — used by evals so
+ *   each run picks up fresh CLI changes from the repo.
+ * - Without either flag we pull the published images.
+ * - If either flag was set but the source tree is missing (e.g. the CLI is
+ *   running from a packaged .app bundle), fall back to pulling and surface
+ *   the reason so the caller can log a warning.
+ *
+ * Returning a plain record keeps this trivially unit-testable — see
+ * `__tests__/docker.test.ts`.
+ */
+export function resolveDockerHatchMode(opts: {
+  watch: boolean;
+  buildFromSource: boolean;
+  fullSourceTreeAvailable: boolean;
+}): { build: boolean; watcher: boolean; fellBackToPull: boolean } {
+  const requested = opts.watch || opts.buildFromSource;
+  if (!requested) {
+    return { build: false, watcher: false, fellBackToPull: false };
+  }
+  if (!opts.fullSourceTreeAvailable) {
+    return { build: false, watcher: false, fellBackToPull: true };
+  }
+  return { build: true, watcher: opts.watch, fellBackToPull: false };
+}
+
 /**
  * Locate the repository root by walking up from `cli/src/lib/` until we
  * find a directory containing the expected Dockerfiles.
@@ -581,7 +651,10 @@ export async function startContainers(
   },
   log: (msg: string) => void,
 ): Promise<void> {
-  const runArgs = buildServiceRunArgs({ ...opts, avatarDevicePath: resolveAvatarDevicePath() });
+  const runArgs = buildServiceRunArgs({
+    ...opts,
+    avatarDevicePath: resolveAvatarDevicePath(),
+  });
   for (const service of SERVICE_START_ORDER) {
     log(`🚀 Starting ${service} container...`);
     await exec("docker", runArgs[service]());
@@ -870,14 +943,32 @@ function startFileWatcher(opts: {
   };
 }
 
+export interface HatchDockerOptions {
+  /**
+   * Path to a local source tree to build images from before hatching. When
+   * provided, this path is used directly as the repo root and no file
+   * watcher is started — useful for callers (e.g. evals) that want each
+   * run to pick up local CLI changes without keeping a long-lived watcher
+   * process around. `--watch` independently auto-detects the repo root and
+   * also enables hot-reload.
+   */
+  sourcePath?: string | null;
+  analyze?: boolean;
+}
+
 export async function hatchDocker(
   species: Species,
   detached: boolean,
   name: string | null,
   watch: boolean = false,
   configValues: Record<string, string> = {},
+  options: HatchDockerOptions = {},
 ): Promise<void> {
   resetLogFile("hatch.log");
+  const provider =
+    options.setupProviderCredentials === false
+      ? undefined
+      : resolveHatchProvider(configValues);
 
   let logFd = openLogFile("hatch.log");
   const log = (msg: string): void => {
@@ -898,25 +989,42 @@ export async function hatchDocker(
       gateway: "",
     };
 
+    const sourcePath =
+      typeof options.sourcePath === "string" && options.sourcePath.length > 0
+        ? options.sourcePath
+        : null;
+    const buildFromSource = sourcePath !== null;
     let repoRoot: string | undefined;
+    let fullSourceTreeAvailable = false;
 
-    if (watch) {
-      repoRoot = findRepoRoot();
+    if (watch || buildFromSource) {
+      // When --source <path> is supplied, trust the caller and use it
+      // directly. Otherwise (the --watch case) walk up from known locations
+      // to find the repo root.
+      repoRoot = sourcePath ? resolve(sourcePath) : findRepoRoot();
 
       // When running from a packaged .app bundle, the Dockerfiles are
       // present (so findRepoRoot succeeds) but the full source tree is
       // not — we can't build images locally. Fall back to pulling
       // pre-built images instead.
-      if (!hasFullSourceTree(repoRoot)) {
+      fullSourceTreeAvailable = hasFullSourceTree(repoRoot);
+      if (!fullSourceTreeAvailable) {
         log(
           "⚠️  Dockerfiles found but no source tree — falling back to image pull",
         );
-        watch = false;
         repoRoot = undefined;
       }
     }
 
-    if (watch && repoRoot) {
+    const mode = resolveDockerHatchMode({
+      watch,
+      buildFromSource,
+      fullSourceTreeAvailable,
+    });
+    // Honour the resolved mode for the rest of the flow.
+    watch = mode.watcher;
+
+    if (mode.build && repoRoot) {
       emitProgress(2, 6, "Building images...");
       const localTag = `local-${instanceName}`;
       imageTags.assistant = `vellum-assistant:${localTag}`;
@@ -926,7 +1034,9 @@ export async function hatchDocker(
 
       log(`🥚 Hatching Docker assistant: ${instanceName}`);
       log(`   Species: ${species}`);
-      log(`   Mode: development (watch)`);
+      log(
+        `   Mode: ${mode.watcher ? "development (watch)" : "build-from-source"}`,
+      );
       log(`   Repo: ${repoRoot}`);
       log(`   Images (local build):`);
       log(`     assistant:            ${imageTags.assistant}`);
@@ -938,7 +1048,7 @@ export async function hatchDocker(
       log("✅ Docker images built");
     }
 
-    if (!watch || !repoRoot) {
+    if (!mode.build || !repoRoot) {
       emitProgress(2, 6, "Pulling images...");
 
       // Allow explicit image overrides via environment variables.
@@ -957,8 +1067,23 @@ export async function hatchDocker(
         imageSource = "env override";
         log("Using image overrides from environment variables");
       } else {
-        const version = cliPkg.version;
-        const versionTag = version ? `v${version}` : "latest";
+        // Resolve image refs from a remote source that may have dev/local
+        // builds. If resolution is unavailable, fall back to the CLI's own
+        // version so a default tag can still be resolved.
+        log("🔍 Fetching latest stable release...");
+        const latestVersion = await fetchLatestStableVersion();
+        let versionTag: string;
+        if (latestVersion) {
+          versionTag = latestVersion.startsWith("v")
+            ? latestVersion
+            : `v${latestVersion}`;
+        } else {
+          const fallback = cliPkg.version;
+          versionTag = fallback ? `v${fallback}` : "latest";
+          log(
+            `⚠️  Platform releases unavailable; falling back to CLI version ${versionTag}`,
+          );
+        }
         log("🔍 Resolving image references...");
         const resolved = await resolveImageRefs(versionTag, log);
         imageTags.assistant = resolved.imageTags.assistant;
@@ -976,11 +1101,25 @@ export async function hatchDocker(
       log(`     credential-executor:  ${imageTags["credential-executor"]}`);
       log("");
 
-      log("📦 Pulling Docker images...");
-      await exec("docker", ["pull", imageTags.assistant]);
-      await exec("docker", ["pull", imageTags.gateway]);
-      await exec("docker", ["pull", imageTags["credential-executor"]]);
-      log("✅ Docker images pulled");
+      // Per-ref branching: local-build refs need the image-loader; external
+      // registry refs get a normal `docker pull`. The two transports compose
+      // cleanly — a release can mix different sources for different images.
+      log("📦 Acquiring Docker images...");
+      for (const service of [
+        "assistant",
+        "gateway",
+        "credential-executor",
+      ] as const) {
+        const ref = imageTags[service];
+        if (isLocalBuildRef(ref)) {
+          log(`   ↪ loading ${ref} via host image-loader`);
+          await loadImageViaHost(HOST_IMAGE_LOADER_URL, ref, log);
+        } else {
+          log(`   ↪ pulling ${ref}`);
+          await exec("docker", ["pull", ref]);
+        }
+      }
+      log("✅ Docker images acquired");
     }
 
     const res = dockerResourceNames(instanceName);
@@ -1013,7 +1152,8 @@ export async function hatchDocker(
 
     // 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 defaultWorkspaceConfigPath = writeInitialConfig(configValues);
+    const hatchConfigValues = buildHatchConfigValues(configValues, provider);
+    const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
 
     const cesServiceToken = randomBytes(32).toString("hex");
     const signingKey = randomBytes(32).toString("hex");
@@ -1043,6 +1183,7 @@ export async function hatchDocker(
       },
       log,
     );
+    const containersUpAt = Date.now();
 
     const imageDigests = await captureImageRefs(res);
 
@@ -1053,6 +1194,7 @@ export async function hatchDocker(
       cloud: "docker",
       species,
       hatchedAt: new Date().toISOString(),
+      guardianBootstrapSecret: ownSecret,
       containerInfo: {
         assistantImage: imageTags.assistant,
         gatewayImage: imageTags.gateway,
@@ -1068,19 +1210,59 @@ export async function hatchDocker(
     setActiveAssistant(instanceName);
 
     emitProgress(6, 6, "Waiting for services...");
-    const { ready } = await waitForGatewayAndLease({
+    const waitDetached = watch ? false : detached;
+    const { ready, guardianAccessToken } = await waitForGatewayAndLease({
       bootstrapSecret: ownSecret,
       containerName: res.assistantContainer,
-      detached: watch ? false : detached,
+      detached: waitDetached,
       instanceName,
       logFd,
       runtimeUrl,
+      containersUpAt,
+      analyze: options.analyze ?? false,
     });
 
     if (!ready && !(watch && repoRoot)) {
       throw new Error("Timed out waiting for assistant to become ready");
     }
 
+    if (ready) {
+      const providerSetupAction = resolveDockerProviderCredentialSetupAction({
+        provider,
+        guardianAccessToken,
+        detached: waitDetached,
+      });
+
+      if (providerSetupAction === "defer" && provider !== null) {
+        log(
+          `Provider credential setup deferred in detached mode.\n` +
+            `Run \`vellum setup --provider ${provider}\` after the assistant is ready.`,
+        );
+      } else if (providerSetupAction === "missing-token" && provider !== null) {
+        log(
+          `⚠️  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 (
+        providerSetupAction === "configure" &&
+        provider !== undefined
+      ) {
+        log(
+          provider === null
+            ? "Checking provider credentials..."
+            : `Checking ${formatProviderName(provider)} credentials...`,
+        );
+        await configureHatchProviderApiKey({
+          gatewayUrl: runtimeUrl,
+          provider,
+          bearerToken: guardianAccessToken,
+          env: process.env,
+          log,
+        });
+      }
+      logHatchNextSteps(log, instanceName);
+    }
+
     if (watch && repoRoot) {
       saveAssistantEntry({ ...dockerEntry, watcherPid: process.pid });
 
@@ -1136,7 +1318,9 @@ async function waitForGatewayAndLease(opts: {
   instanceName: string;
   logFd: number | "ignore";
   runtimeUrl: string;
-}): Promise<{ ready: boolean }> {
+  containersUpAt: number;
+  analyze: boolean;
+}): Promise<{ ready: boolean; guardianAccessToken?: string }> {
   const {
     bootstrapSecret,
     containerName,
@@ -1144,6 +1328,8 @@ async function waitForGatewayAndLease(opts: {
     instanceName,
     logFd,
     runtimeUrl,
+    containersUpAt,
+    analyze,
   } = opts;
 
   const log = (msg: string): void => {
@@ -1168,7 +1354,7 @@ async function waitForGatewayAndLease(opts: {
   log("Waiting for assistant to become ready...");
 
   const readyUrl = `${runtimeUrl}/readyz`;
-  const start = Date.now();
+  const start = containersUpAt;
   let ready = false;
 
   while (Date.now() - start < DOCKER_READY_TIMEOUT_MS) {
@@ -1204,8 +1390,18 @@ async function waitForGatewayAndLease(opts: {
     return { ready: false };
   }
 
-  const elapsedSec = ((Date.now() - start) / 1000).toFixed(1);
+  const readyAt = Date.now();
+  const containersUpToReadyMs = readyAt - start;
+  const elapsedSec = (containersUpToReadyMs / 1000).toFixed(1);
   log(`Assistant ready after ${elapsedSec}s`);
+  if (analyze) {
+    console.info(
+      `[vellum-hatch-timing] ${JSON.stringify({
+        containers_up_to_ready_ms: containersUpToReadyMs,
+        instance: instanceName,
+      })}`,
+    );
+  }
 
   // Lease guardian token. The /readyz check confirms both gateway and
   // assistant are reachable. Retry with backoff in case there is a brief
@@ -1215,6 +1411,7 @@ async function waitForGatewayAndLease(opts: {
   const leaseDeadline = start + DOCKER_READY_TIMEOUT_MS;
   let leaseSuccess = false;
   let lastLeaseError: string | undefined;
+  let guardianAccessToken: string | undefined;
 
   while (Date.now() < leaseDeadline) {
     try {
@@ -1227,6 +1424,7 @@ async function waitForGatewayAndLease(opts: {
       log(
         `Guardian token lease: success after ${leaseElapsed}s (principalId=${tokenData.guardianPrincipalId}, expiresAt=${tokenData.accessTokenExpiresAt})`,
       );
+      guardianAccessToken = tokenData.accessToken;
       leaseSuccess = true;
       break;
     } catch (err) {
@@ -1257,5 +1455,5 @@ async function waitForGatewayAndLease(opts: {
   log(`   Name: ${instanceName}`);
   log(`   Runtime: ${runtimeUrl}`);
   log("");
-  return { ready: true };
+  return { ready: true, guardianAccessToken };
 }

package/src/lib/hatch-local.ts

@@ -22,7 +22,7 @@ import {
 } from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
 import type { Species } from "./constants.js";
-import { writeInitialConfig } from "./config-utils.js";
+import { buildHatchConfigValues, writeInitialConfig } from "./config-utils.js";
 import {
   generateLocalSigningKey,
   startLocalDaemon,
@@ -34,6 +34,12 @@ 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 {
+  configureHatchProviderApiKey,
+  formatProviderName,
+  resolveHatchProvider,
+} from "./provider-secrets.js";
+import { logHatchNextSteps } from "./hatch-next-steps.js";
 
 /**
  * Attempts to place a symlink at the given path pointing to cliBinary.
@@ -125,13 +131,22 @@ function installCLISymlink(): void {
   );
 }
 
+export interface HatchLocalOptions {
+  setupProviderCredentials?: boolean;
+}
+
 export async function hatchLocal(
   species: Species,
   name: string | null,
   watch: boolean = false,
   keepAlive: boolean = false,
   configValues: Record<string, string> = {},
+  options: HatchLocalOptions = {},
 ): Promise<void> {
+  const provider =
+    options.setupProviderCredentials === false
+      ? undefined
+      : resolveHatchProvider(configValues);
   const instanceName = generateInstanceName(
     species,
     name ?? process.env.VELLUM_ASSISTANT_NAME,
@@ -168,7 +183,8 @@ export async function hatchLocal(
   }
 
   emitProgress(2, 6, "Writing configuration...");
-  const defaultWorkspaceConfigPath = writeInitialConfig(configValues);
+  const hatchConfigValues = buildHatchConfigValues(configValues, provider);
+  const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
 
   emitProgress(3, 6, "Starting assistant...");
   const signingKey = generateLocalSigningKey();
@@ -198,9 +214,11 @@ export async function hatchLocal(
   emitProgress(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 {
-      await leaseGuardianToken(loopbackUrl, instanceName);
+      const tokenData = await leaseGuardianToken(loopbackUrl, instanceName);
+      guardianAccessToken = tokenData.accessToken;
       break;
     } catch (err) {
       if (attempt < maxLeaseAttempts) {
@@ -238,6 +256,26 @@ export async function hatchLocal(
     installCLISymlink();
   }
 
+  if (provider !== undefined && provider !== null && !guardianAccessToken) {
+    console.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(
+      provider === null
+        ? "Checking provider credentials..."
+        : `Checking ${formatProviderName(provider)} credentials...`,
+    );
+    await configureHatchProviderApiKey({
+      gatewayUrl: loopbackUrl,
+      provider,
+      bearerToken: guardianAccessToken,
+      env: process.env,
+    });
+  }
+
   console.log("");
   console.log(`✅ Local assistant hatched!`);
   console.log("");
@@ -245,6 +283,7 @@ export async function hatchLocal(
   console.log(`  Name: ${instanceName}`);
   console.log(`  Runtime: ${runtimeUrl}`);
   console.log("");
+  logHatchNextSteps(console.log, instanceName);
 
   if (keepAlive) {
     const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;

package/src/lib/hatch-next-steps.ts

@@ -0,0 +1,12 @@
+export function logHatchNextSteps(
+  log: (message: string) => void,
+  instanceName: string,
+): void {
+  log("Next steps:");
+  log("  vellum client");
+  log('  vellum message "hello"');
+  log("  vellum events");
+  log("  vellum ps");
+  log(`  vellum use ${instanceName}`);
+  log("");
+}