@vellumai/cli 0.8.5 → 0.8.7-dev.202606052118.34cd356

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/retire-local.ts

@@ -3,22 +3,34 @@ import { homedir } from "os";
 import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
 
-import {
-  getDaemonPidPath,
-  loadAllAssistants,
-} from "./assistant-config.js";
+import { getDaemonPidPath, loadAllAssistants } from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
 import {
   stopOrphanedDaemonProcesses,
   stopProcessByPidFile,
 } from "./process.js";
 import { getArchivePath, getMetadataPath } from "./retire-archive.js";
+import {
+  consoleLifecycleReporter,
+  type LifecycleReporter,
+} from "./lifecycle-reporter.js";
+
+export interface RetireLocalResult {
+  assistantId: string;
+  /** Whether the instance data directory was archived (false when skipped). */
+  archived: boolean;
+  /** Path to the background tar archive, when archiving was started. */
+  archivePath?: string;
+  /** True when another local assistant shared the data dir, so it was kept. */
+  sharedDataDir?: boolean;
+}
 
 export async function retireLocal(
   name: string,
   entry: AssistantEntry,
-): Promise<void> {
-  console.log("\u{1F5D1}\ufe0f  Stopping local assistant...\n");
+  reporter: LifecycleReporter = consoleLifecycleReporter,
+): Promise<RetireLocalResult> {
+  reporter.log("\u{1F5D1}\ufe0f  Stopping local assistant...\n");
 
   if (!entry.resources) {
     throw new Error(
@@ -38,11 +50,11 @@ export async function retireLocal(
   });
 
   if (otherSharesDir) {
-    console.log(
+    reporter.log(
       `   Skipping process stop and archive — another local assistant shares ${vellumDir}.`,
     );
-    console.log("\u2705 Local instance retired (config entry removed only).");
-    return;
+    reporter.log("\u2705 Local instance retired (config entry removed only).");
+    return { assistantId: name, archived: false, sharedDataDir: true };
   }
 
   const daemonPidFile = getDaemonPidPath(resources);
@@ -87,11 +99,11 @@ export async function retireLocal(
   const stagingDir = `${archivePath}.staging`;
 
   if (!existsSync(dirToArchive)) {
-    console.log(
+    reporter.log(
       `   No data directory at ${dirToArchive} — nothing to archive.`,
     );
-    console.log("\u2705 Local instance retired.");
-    return;
+    reporter.log("\u2705 Local instance retired.");
+    return { assistantId: name, archived: false };
   }
 
   // Ensure the retired archive directory exists before attempting the rename
@@ -123,6 +135,8 @@ export async function retireLocal(
   });
   child.unref();
 
-  console.log(`📦 Archiving to ${archivePath} in the background.`);
-  console.log("\u2705 Local instance retired.");
+  reporter.log(`📦 Archiving to ${archivePath} in the background.`);
+  reporter.log("\u2705 Local instance retired.");
+
+  return { assistantId: name, archived: true, archivePath };
 }

package/src/lib/segments-to-plain-text.ts

@@ -0,0 +1,35 @@
+/**
+ * Derive a message's flat plain-text body from its ordered text segments.
+ *
+ * Mirrors the daemon's `joinWithSpacing` (assistant `daemon/handlers/shared.ts`):
+ * adjacent segments are concatenated, inserting a single space between two
+ * segments only when neither the end of the left nor the start of the right is
+ * already whitespace. Keeping these byte-identical means CLI-rendered text
+ * matches what the daemon would have produced for the now-removed flat
+ * `content` field.
+ */
+export function segmentsToPlainText(segments: string[] | undefined): string {
+  if (!segments || segments.length === 0) {
+    return "";
+  }
+  let result = segments[0] ?? "";
+  for (let i = 1; i < segments.length; i++) {
+    const prev = result[result.length - 1];
+    const next = segments[i]![0];
+    // Only insert a space when neither side already has whitespace.
+    if (
+      prev &&
+      next &&
+      prev !== " " &&
+      prev !== "\n" &&
+      prev !== "\t" &&
+      next !== " " &&
+      next !== "\n" &&
+      next !== "\t"
+    ) {
+      result += " ";
+    }
+    result += segments[i];
+  }
+  return result;
+}

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;
   }