@vellumai/cli 0.8.5 → 0.8.6

package/src/lib/platform-client.ts

@@ -521,6 +521,8 @@ export async function hatchAssistant(
   );
 }
 
+const PLATFORM_FETCH_TIMEOUT_MS = 10_000;
+
 /**
  * Lightweight pre-check: returns the first active managed assistant for the
  * authenticated user, or `null` if none exists. Calls `GET /v1/assistants/`
@@ -536,20 +538,31 @@ export async function checkExistingPlatformAssistant(
   const resolvedUrl = platformUrl || getPlatformUrl();
   const url = `${resolvedUrl}/v1/assistants/`;
 
-  const response = await fetch(url, {
-    headers: await authHeaders(token, platformUrl),
-  });
+  const controller = new AbortController();
+  const timeoutId = setTimeout(
+    () => controller.abort(),
+    PLATFORM_FETCH_TIMEOUT_MS,
+  );
 
-  if (!response.ok) {
-    // Non-fatal: if the list call fails, fall through and let hatch handle it.
-    return null;
-  }
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: await authHeaders(token, platformUrl),
+    });
 
-  const body = (await response.json()) as {
-    results?: HatchedAssistant[];
-  };
-  const active = body.results?.find((a) => a.status === "active");
-  return active ?? null;
+    if (!response.ok) {
+      // Non-fatal: if the list call fails, fall through and let hatch handle it.
+      return null;
+    }
+
+    const body = (await response.json()) as {
+      results?: HatchedAssistant[];
+    };
+    const active = body.results?.find((a) => a.status === "active");
+    return active ?? null;
+  } finally {
+    clearTimeout(timeoutId);
+  }
 }
 
 /**
@@ -563,17 +576,28 @@ export async function fetchPlatformAssistants(
   const resolvedUrl = platformUrl || getPlatformUrl();
   const url = `${resolvedUrl}/v1/assistants/`;
 
-  const response = await fetch(url, {
-    headers: await authHeaders(token, platformUrl),
-  });
+  const controller = new AbortController();
+  const timeoutId = setTimeout(
+    () => controller.abort(),
+    PLATFORM_FETCH_TIMEOUT_MS,
+  );
 
-  if (!response.ok) return [];
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: await authHeaders(token, platformUrl),
+    });
 
-  const body = (await response.json()) as {
-    results?: HatchedAssistant[];
-  };
+    if (!response.ok) return [];
 
-  return (body.results ?? []).filter((a) => a.status === "active");
+    const body = (await response.json()) as {
+      results?: HatchedAssistant[];
+    };
+
+    return (body.results ?? []).filter((a) => a.status === "active");
+  } finally {
+    clearTimeout(timeoutId);
+  }
 }
 
 export interface PlatformUser {
@@ -592,22 +616,34 @@ export async function fetchOrganizationId(
 ): Promise<string> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const url = `${resolvedUrl}/v1/organizations/`;
-  const response = await fetch(url, {
-    headers: { ...tokenAuthHeader(token) },
-  });
 
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch organizations from ${resolvedUrl} (${response.status}). Try logging in again.`,
-    );
-  }
+  const controller = new AbortController();
+  const timeoutId = setTimeout(
+    () => controller.abort(),
+    PLATFORM_FETCH_TIMEOUT_MS,
+  );
 
-  const body = (await response.json()) as OrganizationListResponse;
-  const orgId = body.results?.[0]?.id;
-  if (!orgId) {
-    throw new Error("No organization found for this account.");
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { ...tokenAuthHeader(token) },
+    });
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch organizations from ${resolvedUrl} (${response.status}). Try logging in again.`,
+      );
+    }
+
+    const body = (await response.json()) as OrganizationListResponse;
+    const orgId = body.results?.[0]?.id;
+    if (!orgId) {
+      throw new Error("No organization found for this account.");
+    }
+    return orgId;
+  } finally {
+    clearTimeout(timeoutId);
   }
-  return orgId;
 }
 
 interface AllauthSessionResponse {
@@ -627,25 +663,37 @@ export async function fetchCurrentUser(
 ): Promise<PlatformUser> {
   const resolvedUrl = platformUrl || getPlatformUrl();
   const url = `${resolvedUrl}/_allauth/app/v1/auth/session`;
-  const response = await fetch(url, {
-    headers: { "X-Session-Token": token },
-  });
 
-  if (!response.ok) {
-    if (
-      response.status === 401 ||
-      response.status === 403 ||
-      response.status === 410
-    ) {
-      throw new Error("Invalid or expired token. Please login again.");
+  const controller = new AbortController();
+  const timeoutId = setTimeout(
+    () => controller.abort(),
+    PLATFORM_FETCH_TIMEOUT_MS,
+  );
+
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { "X-Session-Token": token },
+    });
+
+    if (!response.ok) {
+      if (
+        response.status === 401 ||
+        response.status === 403 ||
+        response.status === 410
+      ) {
+        throw new Error("Invalid or expired token. Please login again.");
+      }
+      throw new Error(
+        `Platform API error: ${response.status} ${response.statusText}`,
+      );
     }
-    throw new Error(
-      `Platform API error: ${response.status} ${response.statusText}`,
-    );
-  }
 
-  const body = (await response.json()) as AllauthSessionResponse;
-  return body.data.user;
+    const body = (await response.json()) as AllauthSessionResponse;
+    return body.data.user;
+  } finally {
+    clearTimeout(timeoutId);
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/lib/process.ts

@@ -1,6 +1,8 @@
 import { execFileSync } from "child_process";
 import { existsSync, readFileSync, unlinkSync } from "fs";
 
+import { httpHealthCheck, waitForDaemonReady } from "./http-client.js";
+
 /**
  * Verify that a PID belongs to a vellum-related process by inspecting its
  * command line via `ps`. Prevents killing unrelated processes when a PID file
@@ -21,13 +23,15 @@ export function isVellumProcess(pid: number): boolean {
   }
 }
 
+/** Discriminated union: when `alive` is true, `pid` is guaranteed non-null. */
+export type ProcessAliveResult =
+  | { alive: true; pid: number }
+  | { alive: false; pid: null };
+
 /**
  * Check if a PID file's process is alive.
  */
-export function isProcessAlive(pidFile: string): {
-  alive: boolean;
-  pid: number | null;
-} {
+export function isProcessAlive(pidFile: string): ProcessAliveResult {
   if (!existsSync(pidFile)) {
     return { alive: false, pid: null };
   }
@@ -46,6 +50,91 @@ export function isProcessAlive(pidFile: string): {
   }
 }
 
+/** Discriminated union: when `alive` is true, `pid` is guaranteed non-null. */
+export type ProcessHealthResult =
+  | { alive: true; healthy: boolean; pid: number }
+  | { alive: false; healthy: false; pid: null };
+
+/**
+ * Check if a PID file's process is alive AND responding to HTTP health checks.
+ *
+ * Combines PID existence check with an HTTP `/healthz` probe. A process that
+ * exists but does not respond (hung, deadlocked, at 100% CPU) returns
+ * `alive: true, healthy: false` — callers should kill and restart it.
+ */
+export async function isProcessHealthy(
+  pidFile: string,
+  healthPort: number,
+  timeoutMs: number = 3000,
+): Promise<ProcessHealthResult> {
+  const { alive, pid } = isProcessAlive(pidFile);
+  if (!alive || pid === null) {
+    return { alive: false, healthy: false, pid: null };
+  }
+
+  const healthy = await httpHealthCheck(healthPort, timeoutMs);
+  return { alive: true, healthy, pid };
+}
+
+/**
+ * Outcome of {@link resolveProcessState}. Callers switch on `status`:
+ * - `"healthy"` — process is alive and responding; `pid` is the live PID.
+ * - `"needs_start"` — process was dead, hung (and killed), or a stale PID
+ *   was cleaned up. Caller should start a fresh process.
+ */
+export type ProcessState =
+  | { status: "healthy"; pid: number }
+  | { status: "needs_start"; pid: number | null };
+
+/**
+ * Determine whether a PID-tracked process is alive and healthy. If the
+ * process exists but is unresponsive, waits up to `readinessWaitMs`
+ * (default 60s — matches the spawner's own `waitForDaemonReady` timeout
+ * so a concurrent caller never kills a daemon the spawner is still
+ * waiting on) for it to finish initializing. If it remains unresponsive,
+ * verifies it belongs to Vellum before killing it, then cleans up the
+ * PID file.
+ *
+ * Encapsulates the full health → readiness-wait → guard → kill → cleanup
+ * flow so callers don't need to reimplement it.
+ */
+export async function resolveProcessState(
+  pidFile: string,
+  healthPort: number,
+  label: string,
+  readinessWaitMs: number = 60_000,
+): Promise<ProcessState> {
+  const result = await isProcessHealthy(pidFile, healthPort);
+
+  if (!result.alive) {
+    return { status: "needs_start", pid: null };
+  }
+
+  if (result.healthy) {
+    return { status: "healthy", pid: result.pid };
+  }
+
+  // Alive but not healthy — may still be starting up.
+  const becameHealthy = await waitForDaemonReady(healthPort, readinessWaitMs);
+  if (becameHealthy) {
+    return { status: "healthy", pid: result.pid };
+  }
+
+  // Genuinely hung — kill if it belongs to Vellum, otherwise just clean up.
+  if (isVellumProcess(result.pid)) {
+    console.log(
+      `${label} process alive (pid ${result.pid}) but not responding — killing and restarting...`,
+    );
+    await stopProcess(result.pid, label);
+  } else {
+    console.log(
+      `Stale PID file (pid ${result.pid} is not a Vellum process) — cleaning up...`,
+    );
+  }
+  removeFiles(pidFile);
+  return { status: "needs_start", pid: result.pid };
+}
+
 /**
  * Stop a process by PID: SIGTERM, wait up to `timeoutMs`, then SIGKILL if still alive.
  * Returns true if the process was stopped, false if it wasn't alive.
@@ -85,6 +174,18 @@ export async function stopProcess(
   return true;
 }
 
+/** Remove one or more files, ignoring missing-file errors. */
+function removeFiles(...files: (string | string[] | undefined)[]): void {
+  for (const entry of files) {
+    if (!entry) continue;
+    for (const f of Array.isArray(entry) ? entry : [entry]) {
+      try {
+        unlinkSync(f);
+      } catch {}
+    }
+  }
+}
+
 /**
  * Stop a process tracked by a PID file, then clean up the file.
  * Returns true if the process was stopped, false if it wasn't alive.
@@ -92,24 +193,13 @@ export async function stopProcess(
 export async function stopProcessByPidFile(
   pidFile: string,
   label: string,
-  cleanupFiles?: string[],
+  extraCleanupFiles?: string[],
   timeoutMs?: number,
 ): Promise<boolean> {
   const { alive, pid } = isProcessAlive(pidFile);
 
   if (!alive || pid === null) {
-    if (existsSync(pidFile)) {
-      try {
-        unlinkSync(pidFile);
-      } catch {}
-    }
-    if (cleanupFiles) {
-      for (const f of cleanupFiles) {
-        try {
-          unlinkSync(f);
-        } catch {}
-      }
-    }
+    removeFiles(pidFile, extraCleanupFiles);
     return false;
   }
 
@@ -120,32 +210,12 @@ export async function stopProcessByPidFile(
     console.log(
       `PID ${pid} is not a vellum process — cleaning up stale ${label} PID file.`,
     );
-    try {
-      unlinkSync(pidFile);
-    } catch {}
-    if (cleanupFiles) {
-      for (const f of cleanupFiles) {
-        try {
-          unlinkSync(f);
-        } catch {}
-      }
-    }
+    removeFiles(pidFile, extraCleanupFiles);
     return false;
   }
 
   const stopped = await stopProcess(pid, label, timeoutMs);
-
-  try {
-    unlinkSync(pidFile);
-  } catch {}
-  if (cleanupFiles) {
-    for (const f of cleanupFiles) {
-      try {
-        unlinkSync(f);
-      } catch {}
-    }
-  }
-
+  removeFiles(pidFile, extraCleanupFiles);
   return stopped;
 }
 

package/src/lib/step-runner.ts

@@ -65,10 +65,52 @@ export function exec(
   });
 }
 
-export function execOutput(
+/**
+ * Run `command` with `args` and pipe `input` to its stdin. Mirrors `exec` —
+ * same no-args-in-error-message contract from `buildExecErrorMessage` — but
+ * lets callers stream content (e.g. a small JSON blob) into a child process
+ * without having to put the content on the command line where `ps` could
+ * read it and where Docker bind-mounts would be involved.
+ */
+export function execWithStdin(
   command: string,
   args: string[],
+  input: string,
   options: { cwd?: string } = {},
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    child.stdout.on("data", (data: Buffer) => {
+      stdout += data.toString();
+    });
+
+    let stderr = "";
+    child.stderr.on("data", (data: Buffer) => {
+      stderr += data.toString();
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(buildExecErrorMessage(command, code, stderr, stdout)));
+      }
+    });
+    child.on("error", reject);
+
+    child.stdin.end(input);
+  });
+}
+
+export function execOutput(
+  command: string,
+  args: string[],
+  options: { cwd?: string; timeoutMs?: number } = {},
 ): Promise<string> {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
@@ -76,6 +118,21 @@ export function execOutput(
       stdio: ["pipe", "pipe", "pipe"],
     });
 
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+
+    if (options.timeoutMs !== undefined) {
+      timer = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          child.kill("SIGTERM");
+          reject(
+            new Error(`${command} timed out after ${options.timeoutMs}ms`),
+          );
+        }
+      }, options.timeoutMs);
+    }
+
     let stdout = "";
     child.stdout.on("data", (data: Buffer) => {
       stdout += data.toString();
@@ -87,17 +144,20 @@ export function execOutput(
     });
 
     child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
       if (code === 0) {
         resolve(stdout.trim());
       } else {
-        // execOutput intentionally drops stdout from the error message
-        // (callers that read stdout via the success path don't expect
-        // partial stdout to land in error.message). Stderr is enough
-        // for diagnostics, and the no-args-in-message guarantee from
-        // exec() still holds.
         reject(new Error(buildExecErrorMessage(command, code, stderr, "")));
       }
     });
-    child.on("error", reject);
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
   });
 }

package/src/lib/sync-cloud-assistants.ts

@@ -26,6 +26,13 @@ import {
 
 export type SyncLogger = (message: string) => void;
 
+function isTimeoutError(err: unknown): boolean {
+  return (
+    err instanceof Error &&
+    (err.name === "AbortError" || err.message.includes("timed out"))
+  );
+}
+
 export interface SyncResult {
   added: number;
   removed: number;
@@ -68,6 +75,11 @@ export async function syncCloudAssistants(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     log?.(`Failed to fetch current user: ${msg}`);
+    if (isTimeoutError(err)) {
+      console.warn(
+        "Warning: platform user lookup timed out — skipping cloud sync",
+      );
+    }
   }
 
   let platformAssistants: { id: string; name: string; status: string }[];
@@ -80,6 +92,11 @@ export async function syncCloudAssistants(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     log?.(`fetchPlatformAssistants failed: ${msg}`);
+    if (isTimeoutError(err)) {
+      console.warn(
+        "Warning: platform assistant fetch timed out — using cached data",
+      );
+    }
     return null;
   }