@vellumai/cli 0.8.2 → 0.8.3

package/src/commands/hatch.ts

@@ -8,7 +8,6 @@ import {
   saveAssistantEntry,
   setActiveAssistant,
 } from "../lib/assistant-config";
-import { hatchAws } from "../lib/aws";
 import {
   SPECIES_CONFIG,
   VALID_REMOTE_HOSTS,
@@ -17,7 +16,6 @@ import {
 import type { RemoteHost, Species } from "../lib/constants";
 import { buildNestedConfig } from "../lib/config-utils";
 import { hatchDocker } from "../lib/docker";
-import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import { hatchLocal } from "../lib/hatch-local";
 import {
@@ -169,6 +167,7 @@ source ${INSTALL_SCRIPT_REMOTE_PATH}
 }
 
 const DEFAULT_REMOTE: RemoteHost = "local";
+const UNSUPPORTED_REMOTE_HATCH_TARGETS = new Set<RemoteHost>(["aws", "gcp"]);
 
 interface HatchArgs {
   species: Species;
@@ -177,7 +176,9 @@ interface HatchArgs {
   name: string | null;
   remote: RemoteHost;
   watch: boolean;
+  sourcePath: string | null;
   configValues: Record<string, string>;
+  analyze: boolean;
 }
 
 function parseArgs(): HatchArgs {
@@ -188,7 +189,9 @@ function parseArgs(): HatchArgs {
   let name: string | null = null;
   let remote: RemoteHost = DEFAULT_REMOTE;
   let watch = false;
+  let sourcePath: string | null = null;
   const configValues: Record<string, string> = {};
+  let analyze = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -210,17 +213,33 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --watch                   Run assistant and gateway in watch mode (hot reload on source changes)",
       );
+      console.log(
+        "  --source <path>           Build images from a local source tree at <path> (no watcher). Useful for callers (e.g. evals) that want each run to pick up local CLI changes.",
+      );
       console.log(
         "  --keep-alive              Stay alive after hatch, exit when gateway stops",
       );
       console.log(
         "  --config <key=value>      Set a workspace config value (repeatable)",
       );
+      console.log(
+        "  --analyze                 Emit a structured hatch-timing log line on stdout",
+      );
       process.exit(0);
     } else if (arg === "-d") {
       detached = true;
     } else if (arg === "--watch") {
       watch = true;
+    } else if (arg === "--analyze") {
+      analyze = true;
+    } else if (arg === "--source") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --source requires a path argument");
+        process.exit(1);
+      }
+      sourcePath = next;
+      i++;
     } else if (arg === "--keep-alive") {
       keepAlive = true;
     } else if (arg === "--name") {
@@ -270,7 +289,7 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --analyze`,
       );
       process.exit(1);
     }
@@ -283,7 +302,9 @@ function parseArgs(): HatchArgs {
     name,
     remote,
     watch,
+    sourcePath,
     configValues,
+    analyze,
   };
 }
 
@@ -508,8 +529,17 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const { species, detached, keepAlive, name, remote, watch, configValues } =
-    parseArgs();
+  const {
+    species,
+    detached,
+    keepAlive,
+    name,
+    remote,
+    watch,
+    sourcePath,
+    configValues,
+    analyze,
+  } = parseArgs();
 
   if (watch && remote !== "local" && remote !== "docker") {
     console.error(
@@ -518,30 +548,33 @@ export async function hatch(): Promise<void> {
     process.exit(1);
   }
 
-  if (remote === "local") {
-    await hatchLocal(species, name, watch, keepAlive, configValues);
-    return;
+  if (sourcePath !== null && remote !== "docker") {
+    console.error(
+      "Error: --source is only supported for docker hatch targets.",
+    );
+    process.exit(1);
   }
 
-  if (remote === "gcp") {
-    await hatchGcp(
-      species,
-      detached,
-      name,
-      buildStartupScript,
-      watchHatching,
-      configValues,
+  if (UNSUPPORTED_REMOTE_HATCH_TARGETS.has(remote)) {
+    console.error(
+      `Error: \`vellum hatch --remote ${remote}\` is not a supported provisioning target yet.`,
     );
-    return;
+    console.error(
+      "No cloud resources were created. To self-host on AWS/GCP, SSH into the VM and run `vellum hatch` or `vellum hatch --remote docker` there.",
+    );
+    process.exit(1);
   }
 
-  if (remote === "aws") {
-    await hatchAws(species, detached, name, configValues);
+  if (remote === "local") {
+    await hatchLocal(species, name, watch, keepAlive, configValues);
     return;
   }
 
   if (remote === "docker") {
-    await hatchDocker(species, detached, name, watch, configValues);
+    await hatchDocker(species, detached, name, watch, configValues, {
+      sourcePath,
+      analyze,
+    });
     return;
   }
 

package/src/commands/setup.ts

@@ -1,5 +1,6 @@
 import { resolveAssistant } from "../lib/assistant-config.js";
 import {
+  leaseGuardianToken,
   loadGuardianToken,
   refreshGuardianToken,
   type GuardianTokenData,
@@ -41,6 +42,50 @@ function isGuardianAccessTokenUsable(
   return Number.isFinite(expiresAt) && expiresAt > Date.now();
 }
 
+async function resolveSetupBearerToken(
+  entry: NonNullable<ReturnType<typeof resolveAssistant>>,
+  gatewayUrl: string,
+): Promise<string | undefined> {
+  const guardianToken = loadGuardianToken(entry.assistantId);
+  if (isGuardianAccessTokenUsable(guardianToken)) {
+    return guardianToken.accessToken;
+  }
+
+  if (guardianToken) {
+    const refreshedToken = await refreshGuardianToken(
+      gatewayUrl,
+      entry.assistantId,
+    );
+    if (isGuardianAccessTokenUsable(refreshedToken)) {
+      return refreshedToken.accessToken;
+    }
+  }
+
+  const canLeaseGuardianToken =
+    entry.cloud === "local" || entry.cloud === "docker" || entry.localUrl;
+  if (canLeaseGuardianToken) {
+    try {
+      const bootstrapSecret =
+        typeof entry.guardianBootstrapSecret === "string"
+          ? entry.guardianBootstrapSecret
+          : undefined;
+      const leasedToken = await leaseGuardianToken(
+        gatewayUrl,
+        entry.assistantId,
+        bootstrapSecret,
+      );
+      if (isGuardianAccessTokenUsable(leasedToken)) {
+        return leasedToken.accessToken;
+      }
+    } catch {
+      // Fall through to any lockfile bearer token, or let the setup request
+      // surface the gateway's auth error below.
+    }
+  }
+
+  return entry.bearerToken;
+}
+
 export async function setup(): Promise<void> {
   const args = process.argv.slice(3);
 
@@ -85,18 +130,7 @@ export async function setup(): Promise<void> {
   }
 
   const gatewayUrl = entry.localUrl ?? entry.runtimeUrl;
-  let bearerToken: string | undefined;
-  const guardianToken = loadGuardianToken(entry.assistantId);
-  if (isGuardianAccessTokenUsable(guardianToken)) {
-    bearerToken = guardianToken.accessToken;
-  } else {
-    const refreshedToken = guardianToken
-      ? await refreshGuardianToken(gatewayUrl, entry.assistantId)
-      : null;
-    bearerToken = isGuardianAccessTokenUsable(refreshedToken)
-      ? refreshedToken.accessToken
-      : entry.bearerToken;
-  }
+  const bearerToken = await resolveSetupBearerToken(entry, gatewayUrl);
 
   console.log("Vellum Setup");
   console.log("============\n");

package/src/commands/teleport.ts

@@ -877,7 +877,16 @@ export async function resolveOrHatchTarget(
   // Hatch a new assistant in the target environment
   if (targetEnv === "local") {
     const beforeIds = new Set(loadAllAssistants().map((e) => e.assistantId));
-    await hatchLocal("vellum", targetName ?? null, false, false, {});
+    await hatchLocal(
+      "vellum",
+      targetName ?? null,
+      false,
+      false,
+      {},
+      {
+        setupProviderCredentials: false,
+      },
+    );
     const entry = targetName
       ? findAssistantByName(targetName)
       : (loadAllAssistants().find((e) => !beforeIds.has(e.assistantId)) ??
@@ -892,7 +901,16 @@ export async function resolveOrHatchTarget(
 
   if (targetEnv === "docker") {
     const beforeIds = new Set(loadAllAssistants().map((e) => e.assistantId));
-    await hatchDocker("vellum", false, targetName ?? null, false, {});
+    await hatchDocker(
+      "vellum",
+      false,
+      targetName ?? null,
+      false,
+      {},
+      {
+        setupProviderCredentials: false,
+      },
+    );
     const entry = targetName
       ? findAssistantByName(targetName)
       : (loadAllAssistants().find((e) => !beforeIds.has(e.assistantId)) ??

package/src/lib/__tests__/docker.test.ts

@@ -4,6 +4,8 @@ import {
   AVATAR_DEVICE_ENV_VAR,
   dockerResourceNames,
   resolveAvatarDevicePath,
+  resolveDockerHatchMode,
+  resolveDockerProviderCredentialSetupAction,
   type ServiceName,
 } from "../docker.js";
 import { buildServiceRunArgs } from "../statefulset.js";
@@ -103,6 +105,51 @@ describe("buildServiceRunArgs — assistant", () => {
   });
 });
 
+describe("resolveDockerProviderCredentialSetupAction", () => {
+  test("defers provider setup in detached mode", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "anthropic",
+        detached: true,
+      }),
+    ).toBe("defer");
+  });
+
+  test("reports missing guardian token only when a lease was expected", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "anthropic",
+        detached: false,
+      }),
+    ).toBe("missing-token");
+  });
+
+  test("configures provider setup when a guardian token is available", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "anthropic",
+        guardianAccessToken: "guardian-token",
+        detached: false,
+      }),
+    ).toBe("configure");
+  });
+
+  test("skips provider setup for internal hatches and detached keyless hatches", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: undefined,
+        detached: false,
+      }),
+    ).toBe("skip");
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: null,
+        detached: true,
+      }),
+    ).toBe("skip");
+  });
+});
+
 describe("buildServiceRunArgs — gateway", () => {
   const savedVelayBaseUrl = process.env.VELAY_BASE_URL;
 
@@ -171,3 +218,62 @@ describe("VELLUM_AVATAR_DEVICE passthrough", () => {
     );
   });
 });
+
+describe("resolveDockerHatchMode", () => {
+  test("defaults to pulling published images when no source flag is set", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: false,
+        buildFromSource: false,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: false, watcher: false, fellBackToPull: false });
+  });
+
+  test("--source <path> builds without enabling the file watcher", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: false,
+        buildFromSource: true,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: true, watcher: false, fellBackToPull: false });
+  });
+
+  test("--watch builds and enables the file watcher", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: true,
+        buildFromSource: false,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: true, watcher: true, fellBackToPull: false });
+  });
+
+  test("--watch + --source <path> still enables the watcher (watch wins)", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: true,
+        buildFromSource: true,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: true, watcher: true, fellBackToPull: false });
+  });
+
+  test("falls back to pull when source flag is set but source tree is missing", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: false,
+        buildFromSource: true,
+        fullSourceTreeAvailable: false,
+      }),
+    ).toEqual({ build: false, watcher: false, fellBackToPull: true });
+    expect(
+      resolveDockerHatchMode({
+        watch: true,
+        buildFromSource: false,
+        fullSourceTreeAvailable: false,
+      }),
+    ).toEqual({ build: false, watcher: false, fellBackToPull: true });
+  });
+});

package/src/lib/assistant-config.ts

@@ -89,6 +89,8 @@ export interface AssistantEntry {
   resources?: LocalInstanceResources;
   /** PID of the file watcher process for docker instances hatched with --watch. */
   watcherPid?: number;
+  /** Local bootstrap secret used to lease guardian tokens for Docker assistants after detached hatch. */
+  guardianBootstrapSecret?: string;
   /** Docker image metadata for rollback. Only present for docker topology entries. */
   containerInfo?: ContainerInfo;
   /** Docker image metadata from before the last upgrade. Enables rollback to the prior version. */

package/src/lib/config-utils.ts

@@ -32,6 +32,24 @@ export function buildNestedConfig(
   return config;
 }
 
+/**
+ * Ensure hatch always provides enough initial LLM config for the assistant to
+ * detect a fresh off-platform hatch and seed BYOK profiles.
+ */
+export function buildHatchConfigValues(
+  configValues: Record<string, string>,
+  provider: string | null | undefined,
+): Record<string, string> {
+  if (!provider || configValues["llm.default.provider"]) {
+    return configValues;
+  }
+
+  return {
+    ...configValues,
+    "llm.default.provider": provider,
+  };
+}
+
 /**
  * Write arbitrary key-value pairs to a temporary JSON file and return its
  * path. The caller passes this path to the daemon via the