@vellumai/cli 0.6.0 → 0.6.1

package/src/lib/assistant-client.ts

@@ -0,0 +1,228 @@
+/**
+ * Gateway client for authenticated requests to a hatched assistant's runtime.
+ *
+ * Encapsulates lockfile reading, guardian-token resolution, and
+ * authenticated fetch so callers can simply do:
+ *
+ * ```ts
+ * const client = new AssistantClient();                          // active / latest
+ * const client = new AssistantClient({ assistantId: "my-bot" }); // by name
+ * await client.get("/healthz");
+ * await client.post("/messages/", { content: "hi" });
+ * ```
+ */
+
+import {
+  findAssistantByName,
+  getActiveAssistant,
+  loadLatestAssistant,
+} from "./assistant-config.js";
+import { GATEWAY_PORT } from "./constants.js";
+import { loadGuardianToken } from "./guardian-token.js";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
+
+export interface AssistantClientOpts {
+  assistantId?: string;
+  /**
+   * When provided alongside `orgId`, the client authenticates with a
+   * session token instead of a guardian token.  The session token is
+   * sent as `Authorization: Bearer <sessionToken>` and the org id is
+   * sent via the `X-Vellum-Org-Id` header.
+   */
+  sessionToken?: string;
+  /** Required when `sessionToken` is provided. */
+  orgId?: string;
+}
+
+export interface RequestOpts {
+  timeout?: number;
+  signal?: AbortSignal;
+  headers?: Record<string, string>;
+  query?: Record<string, string>;
+}
+
+export class AssistantClient {
+  readonly runtimeUrl: string;
+
+  private readonly _assistantId: string;
+  private readonly token: string | undefined;
+  private readonly orgId: string | undefined;
+
+  /**
+   * Resolves an assistant entry from the lockfile and loads auth credentials.
+   *
+   * @param opts.assistantId - Explicit assistant name. When omitted, the
+   *   active assistant is used, falling back to the most recently hatched one.
+   * @throws If no matching assistant is found.
+   */
+  constructor(opts?: AssistantClientOpts) {
+    const nameOrId = opts?.assistantId;
+    let entry = nameOrId ? findAssistantByName(nameOrId) : null;
+
+    if (nameOrId && !entry) {
+      throw new Error(`No assistant found with name '${nameOrId}'.`);
+    }
+
+    if (!entry) {
+      const active = getActiveAssistant();
+      if (active) {
+        entry = findAssistantByName(active);
+      }
+    }
+
+    if (!entry) {
+      entry = loadLatestAssistant();
+    }
+
+    if (!entry) {
+      throw new Error(
+        "No assistant found. Hatch one first with 'vellum hatch'.",
+      );
+    }
+
+    this.runtimeUrl = (
+      entry.localUrl ||
+      entry.runtimeUrl ||
+      FALLBACK_RUNTIME_URL
+    ).replace(/\/+$/, "");
+    this._assistantId = entry.assistantId;
+
+    if (opts?.sessionToken) {
+      // Platform assistant: use session token + org id header.
+      this.token = opts.sessionToken;
+      this.orgId = opts.orgId;
+    } else {
+      this.token =
+        loadGuardianToken(this._assistantId)?.accessToken ?? entry.bearerToken;
+      this.orgId = undefined;
+    }
+  }
+
+  /** GET request to the gateway. Auth headers are added automatically. */
+  async get(urlPath: string, opts?: RequestOpts): Promise<Response> {
+    return this.request("GET", urlPath, undefined, opts);
+  }
+
+  /**
+   * Subscribe to an SSE endpoint and yield parsed JSON objects from `data:` lines.
+   * Automatically sets `Accept: text/event-stream` and skips heartbeat comments.
+   */
+  async *stream<T = unknown>(
+    urlPath: string,
+    opts?: RequestOpts,
+  ): AsyncGenerator<T> {
+    const response = await this.get(urlPath, {
+      ...opts,
+      headers: { Accept: "text/event-stream", ...opts?.headers },
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new Error(
+        `HTTP ${response.status}: ${body || response.statusText}`,
+      );
+    }
+
+    if (!response.body) {
+      throw new Error("No response body received.");
+    }
+
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    for await (const chunk of response.body) {
+      buffer += decoder.decode(chunk, { stream: true });
+
+      let boundary: number;
+      while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+
+        if (!frame.trim() || frame.startsWith(":")) continue;
+
+        let data: string | undefined;
+        for (const line of frame.split("\n")) {
+          if (line.startsWith("data: ")) {
+            data = line.slice(6);
+          }
+        }
+
+        if (!data) continue;
+
+        try {
+          yield JSON.parse(data) as T;
+        } catch {
+          // Skip malformed JSON
+        }
+      }
+    }
+  }
+
+  /** POST request to the gateway with a JSON body. Auth headers are added automatically. */
+  async post(
+    urlPath: string,
+    body: unknown,
+    opts?: RequestOpts,
+  ): Promise<Response> {
+    return this.request("POST", urlPath, body, opts);
+  }
+
+  /** PATCH request to the gateway with a JSON body. Auth headers are added automatically. */
+  async patch(
+    urlPath: string,
+    body: unknown,
+    opts?: RequestOpts,
+  ): Promise<Response> {
+    return this.request("PATCH", urlPath, body, opts);
+  }
+
+  private async request(
+    method: string,
+    urlPath: string,
+    body: unknown | undefined,
+    opts?: RequestOpts,
+  ): Promise<Response> {
+    const qs = opts?.query
+      ? `?${new URLSearchParams(opts.query).toString()}`
+      : "";
+    const url = `${this.runtimeUrl}/v1/assistants/${this._assistantId}${urlPath}${qs}`;
+
+    const headers: Record<string, string> = { ...opts?.headers };
+    if (this.token) {
+      headers["Authorization"] ??= `Bearer ${this.token}`;
+    }
+    if (this.orgId) {
+      headers["X-Vellum-Org-Id"] ??= this.orgId;
+    }
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    const jsonBody = body !== undefined ? JSON.stringify(body) : undefined;
+
+    if (opts?.signal) {
+      return fetch(url, {
+        method,
+        headers,
+        body: jsonBody,
+        signal: opts.signal,
+      });
+    }
+
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      return await fetch(url, {
+        method,
+        headers,
+        body: jsonBody,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}

package/src/lib/docker.ts

@@ -92,51 +92,60 @@ async function downloadAndExtract(
 }
 
 /**
- * Installs Docker CLI, Colima, and Lima by downloading pre-built binaries
- * directly into ~/.vellum/bin/. No Homebrew or sudo required.
- *
- * Falls back to Homebrew if available (e.g. admin users who prefer it).
+ * Installs Docker CLI (and Colima + Lima on macOS) by downloading pre-built
+ * binaries directly into ~/.local/bin/. No Homebrew or sudo required.
  */
 async function installDockerToolchain(): Promise<void> {
-  // Try Homebrew first if available — it handles updates and dependencies.
-  let hasBrew = false;
-  try {
-    await execOutput("brew", ["--version"]);
-    hasBrew = true;
-  } catch {
-    // brew not found
-  }
+  const isMac = platform() === "darwin";
+  const isLinux = platform() === "linux";
+
+  mkdirSync(LOCAL_BIN_DIR, { recursive: true });
+
+  const cpuArch = releaseArch();
 
-  if (hasBrew) {
-    console.log("🐳 Docker not found. Installing via Homebrew...");
+  if (isLinux) {
+    // On Linux, Docker runs natively — only need the Docker CLI.
+    console.log(
+      "🐳 Docker not found. Installing Docker CLI to ~/.local/bin/...",
+    );
+
+    const dockerArch = cpuArch === "aarch64" ? "aarch64" : "x86_64";
+    const dockerTarUrl = `https://download.docker.com/linux/static/stable/${dockerArch}/docker-27.5.1.tgz`;
+    const dockerTmpDir = join(LOCAL_BIN_DIR, ".docker-tmp");
+    mkdirSync(dockerTmpDir, { recursive: true });
     try {
-      await exec("brew", ["install", "colima", "docker"]);
-      return;
-    } catch {
-      console.log(
-        "  ⚠ Homebrew install failed, falling back to direct binary download...",
-      );
+      await downloadAndExtract(dockerTarUrl, dockerTmpDir, "Docker CLI");
+      await exec("mv", [
+        join(dockerTmpDir, "docker", "docker"),
+        join(LOCAL_BIN_DIR, "docker"),
+      ]);
+      chmodSync(join(LOCAL_BIN_DIR, "docker"), 0o755);
+    } finally {
+      await exec("rm", ["-rf", dockerTmpDir]).catch(() => {});
     }
-  }
 
-  // Direct binary install — no sudo required.
-  console.log(
-    "🐳 Docker not found. Installing Docker, Colima, and Lima to ~/.local/bin/...",
-  );
-
-  mkdirSync(LOCAL_BIN_DIR, { recursive: true });
+    if (!existsSync(join(LOCAL_BIN_DIR, "docker"))) {
+      throw new Error(
+        "docker binary not found after installation. Please install Docker manually: https://docs.docker.com/engine/install/",
+      );
+    }
 
-  const cpuArch = releaseArch();
-  const isMac = platform() === "darwin";
+    console.log("  ✅ Docker CLI installed to ~/.local/bin/");
+    return;
+  }
 
   if (!isMac) {
     throw new Error(
-      "Automatic Docker installation is only supported on macOS. " +
+      "Automatic Docker installation is only supported on macOS and Linux. " +
         "Please install Docker manually: https://docs.docker.com/engine/install/",
     );
   }
 
-  // --- Docker CLI ---
+  console.log(
+    "🐳 Docker not found. Installing Docker, Colima, and Lima to ~/.local/bin/...",
+  );
+
+  // --- Docker CLI (macOS) ---
   // Docker publishes static binaries at download.docker.com.
   const dockerArch = cpuArch === "aarch64" ? "aarch64" : "x86_64";
   const dockerTarUrl = `https://download.docker.com/mac/static/stable/${dockerArch}/docker-27.5.1.tgz`;
@@ -223,13 +232,17 @@ async function ensureDockerInstalled(): Promise<void> {
   // Always add ~/.local/bin to PATH so previously installed binaries are found.
   ensureLocalBinOnPath();
 
-  // Check that docker, colima, and limactl are all available. If any is
-  // missing (e.g. partial install from a previous failure), re-run install.
+  const isLinux = platform() === "linux";
+
+  // On Linux, Docker runs natively — only need the docker CLI + daemon.
+  // On macOS, we also need Colima and Lima to provide a Linux VM.
   const toolchainComplete = await (async () => {
     try {
       await execOutput("docker", ["--version"]);
-      await execOutput("colima", ["version"]);
-      await execOutput("limactl", ["--version"]);
+      if (!isLinux) {
+        await execOutput("colima", ["version"]);
+        await execOutput("limactl", ["--version"]);
+      }
       return true;
     } catch {
       return false;
@@ -251,10 +264,19 @@ async function ensureDockerInstalled(): Promise<void> {
     }
   }
 
-  // Verify the Docker daemon is reachable; start Colima if it isn't.
+  // Verify the Docker daemon is reachable.
   try {
     await exec("docker", ["info"]);
   } catch {
+    // On Linux, the daemon must already be running (systemd, etc.).
+    if (isLinux) {
+      throw new Error(
+        "Docker daemon is not running. Please start it with 'sudo systemctl start docker' " +
+          "or ensure the Docker service is enabled.",
+      );
+    }
+
+    // On macOS, try starting Colima.
     let hasColima = false;
     try {
       await execOutput("colima", ["version"]);
@@ -394,6 +416,15 @@ function walkUpForRepoRoot(startDir: string): string | undefined {
   return undefined;
 }
 
+/**
+ * Returns `true` when the given root looks like a full source checkout
+ * (has assistant source code), as opposed to a packaged `.app` bundle
+ * that only contains the Dockerfiles.
+ */
+function hasFullSourceTree(root: string): boolean {
+  return existsSync(join(root, "assistant", "package.json"));
+}
+
 /**
  * Locate the repository root by walking up from `cli/src/lib/` until we
  * find a directory containing the expected Dockerfiles.
@@ -414,6 +445,20 @@ function findRepoRoot(): string {
     return execRoot;
   }
 
+  // Check the app bundle's Resources directory. Debug DMG builds bundle
+  // Dockerfiles at Contents/Resources/dockerfiles/{assistant,gateway,...}/Dockerfile.
+  // The CLI binary lives at Contents/MacOS/vellum-cli, so Resources is at
+  // ../Resources relative to the binary.
+  const bundledRoot = join(
+    dirname(process.execPath),
+    "..",
+    "Resources",
+    "dockerfiles",
+  );
+  if (existsSync(join(bundledRoot, "assistant", "Dockerfile"))) {
+    return bundledRoot;
+  }
+
   // Walk up from cwd as a final fallback
   const cwdRoot = walkUpForRepoRoot(process.cwd());
   if (cwdRoot) {
@@ -691,11 +736,13 @@ export async function sleepContainers(
   }
 }
 
-/** Start existing stopped containers, starting Colima first if it isn't running. */
+/** Start existing stopped containers, starting Colima first if it isn't running (macOS only). */
 export async function wakeContainers(
   res: ReturnType<typeof dockerResourceNames>,
 ): Promise<void> {
-  await ensureColimaRunning();
+  if (platform() !== "linux") {
+    await ensureColimaRunning();
+  }
   for (const container of [
     res.assistantContainer,
     res.gatewayContainer,
@@ -805,6 +852,9 @@ function affectedServices(
  * images and restart their containers.
  */
 function startFileWatcher(opts: {
+  signingKey?: string;
+  bootstrapSecret?: string;
+  cesServiceToken?: string;
   gatewayPort: number;
   imageTags: Record<ServiceName, string>;
   instanceName: string;
@@ -826,6 +876,9 @@ function startFileWatcher(opts: {
 
   const configs = serviceImageConfigs(repoRoot, imageTags);
   const runArgs = serviceDockerRunArgs({
+    signingKey: opts.signingKey,
+    bootstrapSecret: opts.bootstrapSecret,
+    cesServiceToken: opts.cesServiceToken,
     gatewayPort,
     imageTags,
     instanceName,
@@ -963,8 +1016,23 @@ export async function hatchDocker(
     let repoRoot: string | undefined;
 
     if (watch) {
-      emitProgress(2, 6, "Building images...");
       repoRoot = 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)) {
+        log(
+          "⚠️  Dockerfiles found but no source tree — falling back to image pull",
+        );
+        watch = false;
+        repoRoot = undefined;
+      }
+    }
+
+    if (watch && repoRoot) {
+      emitProgress(2, 6, "Building images...");
       const localTag = `local-${instanceName}`;
       imageTags.assistant = `vellum-assistant:${localTag}`;
       imageTags.gateway = `vellum-gateway:${localTag}`;
@@ -983,20 +1051,41 @@ export async function hatchDocker(
 
       await buildAllImages(repoRoot, imageTags, log);
       log("✅ Docker images built");
-    } else {
+    }
+
+    if (!watch || !repoRoot) {
       emitProgress(2, 6, "Pulling images...");
-      const version = cliPkg.version;
-      const versionTag = version ? `v${version}` : "latest";
-      log("🔍 Resolving image references...");
-      const resolved = await resolveImageRefs(versionTag, log);
-      imageTags.assistant = resolved.imageTags.assistant;
-      imageTags.gateway = resolved.imageTags.gateway;
-      imageTags["credential-executor"] =
-        resolved.imageTags["credential-executor"];
+
+      // Allow explicit image overrides via environment variables.
+      // When all three are set, skip version-based resolution entirely.
+      const envAssistant = process.env.VELLUM_ASSISTANT_IMAGE;
+      const envGateway = process.env.VELLUM_GATEWAY_IMAGE;
+      const envCredentialExecutor =
+        process.env.VELLUM_CREDENTIAL_EXECUTOR_IMAGE;
+
+      let imageSource: string;
+
+      if (envAssistant && envGateway && envCredentialExecutor) {
+        imageTags.assistant = envAssistant;
+        imageTags.gateway = envGateway;
+        imageTags["credential-executor"] = envCredentialExecutor;
+        imageSource = "env override";
+        log("Using image overrides from environment variables");
+      } else {
+        const version = cliPkg.version;
+        const versionTag = version ? `v${version}` : "latest";
+        log("🔍 Resolving image references...");
+        const resolved = await resolveImageRefs(versionTag, log);
+        imageTags.assistant = resolved.imageTags.assistant;
+        imageTags.gateway = resolved.imageTags.gateway;
+        imageTags["credential-executor"] =
+          resolved.imageTags["credential-executor"];
+        imageSource = resolved.source;
+      }
 
       log(`🥚 Hatching Docker assistant: ${instanceName}`);
       log(`   Species: ${species}`);
-      log(`   Images (${resolved.source}):`);
+      log(`   Images (${imageSource}):`);
       log(`     assistant:            ${imageTags.assistant}`);
       log(`     gateway:              ${imageTags.gateway}`);
       log(`     credential-executor:  ${imageTags["credential-executor"]}`);
@@ -1106,6 +1195,9 @@ export async function hatchDocker(
       saveAssistantEntry({ ...dockerEntry, watcherPid: process.pid });
 
       const stopWatcher = startFileWatcher({
+        signingKey,
+        bootstrapSecret,
+        cesServiceToken,
         gatewayPort,
         imageTags,
         instanceName,

package/src/lib/hatch-local.ts

@@ -308,10 +308,13 @@ export async function hatchLocal(
   }
 
   // Lease a guardian token so the desktop app can import it on first launch
-  // instead of hitting /v1/guardian/init itself.
+  // 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(6, 7, "Securing connection...");
+  const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
   try {
-    await leaseGuardianToken(runtimeUrl, instanceName);
+    await leaseGuardianToken(loopbackUrl, instanceName);
   } catch (err) {
     console.error(`⚠️  Guardian token lease failed: ${err}`);
   }

package/src/lib/health-check.ts

@@ -25,10 +25,10 @@ export async function checkManagedHealth(
     };
   }
 
-  let orgId: string;
+  let headers: Record<string, string>;
   try {
-    const { fetchOrganizationId } = await import("./platform-client.js");
-    orgId = await fetchOrganizationId(token, runtimeUrl);
+    const { authHeaders } = await import("./platform-client.js");
+    headers = await authHeaders(token, runtimeUrl);
   } catch (err) {
     return {
       status: "error (auth)",
@@ -44,11 +44,6 @@ export async function checkManagedHealth(
       HEALTH_CHECK_TIMEOUT_MS,
     );
 
-    const headers: Record<string, string> = {
-      "X-Session-Token": token,
-      "Vellum-Organization-Id": orgId,
-    };
-
     const response = await fetch(url, {
       signal: controller.signal,
       headers,

package/src/lib/ngrok.ts

@@ -1,5 +1,6 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
 import {
+  closeSync,
   existsSync,
   mkdirSync,
   openSync,
@@ -130,10 +131,11 @@ export function startNgrokProcess(
   logFilePath?: string,
 ): ChildProcess {
   let stdio: ("ignore" | "pipe" | number)[] = ["ignore", "pipe", "pipe"];
+  let fd: number | undefined;
   if (logFilePath) {
     const dir = dirname(logFilePath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const fd = openSync(logFilePath, "a");
+    fd = openSync(logFilePath, "a");
     stdio = ["ignore", fd, fd];
   }
 
@@ -141,6 +143,14 @@ export function startNgrokProcess(
     detached: true,
     stdio,
   });
+
+  // The child process inherits a duplicate of the fd via dup2, so the
+  // parent's copy is no longer needed. Close it to avoid leaking the
+  // file descriptor for the lifetime of the parent process.
+  if (fd !== undefined) {
+    closeSync(fd);
+  }
+
   return child;
 }