@vellumai/cli 0.10.12 → 0.11.0-dev.202607290139.f1746d4

package/src/lib/local-hatch-lock.ts

@@ -0,0 +1,322 @@
+import { execFileSync } from "child_process";
+import { createHash, randomUUID } from "crypto";
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeFileSync,
+} from "fs";
+import { hostname, userInfo } from "os";
+import { dirname, join } from "path";
+
+const DEFAULT_TIMEOUT_MS = 240_000;
+const DEFAULT_RETRY_MS = 100;
+const MAX_LOCK_AGE_MS = DEFAULT_TIMEOUT_MS - 60_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const LIVE_OWNER_RECOVERY_GRACE_MS = 10_000;
+
+interface LocalHatchLockOptions {
+  lockPath?: string;
+  liveOwnerRecoveryGraceMs?: number;
+  timeoutMs?: number;
+  retryMs?: number;
+}
+
+interface LockOwner {
+  pid: number;
+  processStartedAt?: string;
+  token: string;
+}
+
+interface LockSnapshot {
+  owner?: LockOwner;
+  signature: string;
+}
+
+export function resolveLocalHatchLockPath(): string {
+  const machineKey = createHash("sha256")
+    .update(hostname())
+    .digest("hex")
+    .slice(0, 12);
+  return join(
+    userInfo().homedir,
+    ".cache",
+    "vellum",
+    "runtime",
+    machineKey,
+    "local-hatch.lock",
+  );
+}
+
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function processStartedAt(pid: number): string | undefined {
+  try {
+    const value = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1_000,
+    }).trim();
+    return value || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseOwner(raw: string): LockOwner | undefined {
+  try {
+    const parsed = JSON.parse(raw) as {
+      pid?: unknown;
+      processStartedAt?: unknown;
+      token?: unknown;
+    };
+    if (
+      typeof parsed.pid === "number" &&
+      Number.isInteger(parsed.pid) &&
+      parsed.pid > 0 &&
+      typeof parsed.token === "string" &&
+      parsed.token.length > 0
+    ) {
+      return {
+        pid: parsed.pid,
+        processStartedAt:
+          typeof parsed.processStartedAt === "string" &&
+          parsed.processStartedAt.length > 0
+            ? parsed.processStartedAt
+            : undefined,
+        token: parsed.token,
+      };
+    }
+  } catch {}
+  return undefined;
+}
+
+function readSnapshot(path: string): LockSnapshot | undefined {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return {
+      owner: parseOwner(raw),
+      signature: createHash("sha256").update(raw).digest("hex"),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function readOwner(path: string): LockOwner | undefined {
+  return readSnapshot(path)?.owner;
+}
+
+function fileAgeMs(path: string): number | undefined {
+  try {
+    return Date.now() - statSync(path).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+const expiredLiveOwners = new Map<string, number>();
+
+function ownerIsActive(
+  path: string,
+  owner: LockOwner | undefined,
+  liveOwnerRecoveryGraceMs: number,
+): boolean {
+  const ageMs = fileAgeMs(path);
+  if (!owner) {
+    return ageMs !== undefined && ageMs < MAX_LOCK_AGE_MS;
+  }
+  if (!processIsAlive(owner.pid)) {
+    return false;
+  }
+  if (owner.processStartedAt) {
+    const currentStartedAt = processStartedAt(owner.pid);
+    if (currentStartedAt) {
+      expiredLiveOwners.delete(owner.token);
+      return currentStartedAt === owner.processStartedAt;
+    }
+  }
+  if (ageMs !== undefined && ageMs < MAX_LOCK_AGE_MS) {
+    expiredLiveOwners.delete(owner.token);
+    return true;
+  }
+
+  const firstExpiredAt = expiredLiveOwners.get(owner.token) ?? Date.now();
+  expiredLiveOwners.set(owner.token, firstExpiredAt);
+  if (Date.now() - firstExpiredAt < liveOwnerRecoveryGraceMs) {
+    return true;
+  }
+  return false;
+}
+
+function writeOwnerFile(path: string, owner: LockOwner): void {
+  const fd = openSync(path, "wx", 0o600);
+  try {
+    writeFileSync(fd, JSON.stringify(owner) + "\n");
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function acquireRecoveryClaim(
+  lockPath: string,
+  staleSignature: string,
+  owner: LockOwner,
+  liveOwnerRecoveryGraceMs: number,
+): (() => void) | undefined {
+  const recoveryKey = staleSignature.slice(0, 16);
+  for (let generation = 0; generation < 100; generation++) {
+    const claimPath = `${lockPath}.recovery-${recoveryKey}-${generation}`;
+    try {
+      writeOwnerFile(claimPath, owner);
+      return () => releaseLock(claimPath, owner.token);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (
+        ownerIsActive(claimPath, readOwner(claimPath), liveOwnerRecoveryGraceMs)
+      ) {
+        return undefined;
+      }
+    }
+  }
+  return undefined;
+}
+
+function removeStaleLock(
+  lockPath: string,
+  recoveryOwner: LockOwner,
+  liveOwnerRecoveryGraceMs: number,
+): boolean {
+  const staleSnapshot = readSnapshot(lockPath);
+  if (!staleSnapshot) {
+    return true;
+  }
+  if (ownerIsActive(lockPath, staleSnapshot.owner, liveOwnerRecoveryGraceMs)) {
+    return false;
+  }
+
+  const releaseRecoveryClaim = acquireRecoveryClaim(
+    lockPath,
+    staleSnapshot.signature,
+    recoveryOwner,
+    liveOwnerRecoveryGraceMs,
+  );
+  if (!releaseRecoveryClaim) {
+    return false;
+  }
+
+  try {
+    const currentSnapshot = readSnapshot(lockPath);
+    if (!currentSnapshot) {
+      return true;
+    }
+    if (currentSnapshot.signature !== staleSnapshot.signature) {
+      return false;
+    }
+    if (
+      ownerIsActive(lockPath, currentSnapshot.owner, liveOwnerRecoveryGraceMs)
+    ) {
+      return false;
+    }
+    try {
+      unlinkSync(lockPath);
+      return true;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === "ENOENT";
+    }
+  } finally {
+    releaseRecoveryClaim();
+  }
+}
+
+function releaseLock(lockPath: string, token: string): void {
+  if (readOwner(lockPath)?.token !== token) {
+    return;
+  }
+  try {
+    unlinkSync(lockPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+function refreshLock(lockPath: string, token: string): void {
+  if (readOwner(lockPath)?.token !== token) {
+    return;
+  }
+  try {
+    const now = new Date();
+    utimesSync(lockPath, now, now);
+  } catch {}
+}
+
+/**
+ * Serialize local assistant startup across CLI processes. Port availability is
+ * machine-wide even when callers use different lockfile or XDG directories,
+ * so allocation must remain exclusive until the new services have bound their
+ * ports and the assistant entry has been persisted.
+ */
+export async function withLocalHatchLock<T>(
+  action: () => Promise<T>,
+  options: LocalHatchLockOptions = {},
+): Promise<T> {
+  const lockPath = options.lockPath ?? resolveLocalHatchLockPath();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retryMs = options.retryMs ?? DEFAULT_RETRY_MS;
+  const liveOwnerRecoveryGraceMs =
+    options.liveOwnerRecoveryGraceMs ?? LIVE_OWNER_RECOVERY_GRACE_MS;
+  const deadline = Date.now() + timeoutMs;
+  const owner: LockOwner = {
+    pid: process.pid,
+    processStartedAt: processStartedAt(process.pid),
+    token: `${process.pid}-${randomUUID()}`,
+  };
+
+  mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+
+  while (true) {
+    try {
+      writeOwnerFile(lockPath, owner);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+        throw error;
+      }
+      if (removeStaleLock(lockPath, owner, liveOwnerRecoveryGraceMs)) {
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `Timed out waiting for another local assistant to finish starting (${lockPath})`,
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, retryMs));
+      continue;
+    }
+
+    const heartbeat = setInterval(
+      () => refreshLock(lockPath, owner.token),
+      HEARTBEAT_INTERVAL_MS,
+    );
+    try {
+      return await action();
+    } finally {
+      clearInterval(heartbeat);
+      releaseLock(lockPath, owner.token);
+    }
+  }
+}

package/src/lib/local.ts

@@ -548,6 +548,7 @@ export function generateLocalSigningKey(): string {
 type DaemonStartOptions = {
   foreground?: boolean;
   defaultWorkspaceConfigPath?: string;
+  requireReady?: boolean;
   signingKey?: string;
 };
 
@@ -597,7 +598,10 @@ function applyDaemonEnvOverrides(
   applyIpcSocketDirOverride(env);
 }
 
-function logDaemonReadiness(readiness: DaemonReadiness): void {
+function logDaemonReadiness(
+  readiness: DaemonReadiness,
+  requireReady = false,
+): void {
   switch (readiness) {
     case "ready":
       console.log("   Assistant ready\n");
@@ -613,6 +617,11 @@ function logDaemonReadiness(readiness: DaemonReadiness): void {
       );
       break;
     default:
+      if (requireReady) {
+        throw new Error(
+          "Assistant did not bind its local port within 60 seconds.",
+        );
+      }
       console.log(
         "   ⚠️  Assistant did not become ready within 60s — continuing anyway\n",
       );
@@ -1320,6 +1329,7 @@ export async function startLocalDaemon(
           resources.daemonPort,
           Date.now() + 60000,
         ),
+        options?.requireReady,
       );
     }
     return;
@@ -1362,6 +1372,7 @@ export async function startLocalDaemon(
         // classifies it without blocking on an in-flight migration.
         logDaemonReadiness(
           await probeDaemonReadinessWithRetry(resources.daemonPort),
+          options?.requireReady,
         );
         return;
       }
@@ -1513,7 +1524,7 @@ export async function startLocalDaemon(
         readiness = await probeDaemonReadiness(resources.daemonPort);
       }
 
-      logDaemonReadiness(readiness);
+      logDaemonReadiness(readiness, options?.requireReady);
     }
   } else {
     console.log("🔨 Starting local assistant...");
@@ -1535,6 +1546,7 @@ export async function startLocalDaemon(
           resources.daemonPort,
           Date.now() + 60000,
         ),
+        options?.requireReady,
       );
     }
   }
@@ -1547,6 +1559,7 @@ export async function startGateway(
     signingKey?: string;
     bootstrapSecret?: string;
     envOverrides?: Record<string, string>;
+    requireReady?: boolean;
   },
 ): Promise<string> {
   const effectiveGatewayPort = resources?.gatewayPort ?? GATEWAY_PORT;
@@ -1676,6 +1689,11 @@ export async function startGateway(
   // connection-refused errors.
   const ready = await waitForDaemonReady(effectiveGatewayPort, 30000);
   if (!ready) {
+    if (options?.requireReady) {
+      throw new Error(
+        "Assistant gateway did not bind its local port within 30 seconds.",
+      );
+    }
     console.warn(
       "⚠ Gateway started but health check did not respond within 30s",
     );

package/src/lib/provider-secrets.ts

@@ -76,6 +76,7 @@ const PROVIDER_LABELS: Record<LlmProviderId, string> = {
   atlascloud: "Atlas Cloud",
   together: "Together AI",
   baseten: "Baseten",
+  poolside: "Poolside",
 };
 
 export function formatProviderName(provider: LlmProviderId): string {
@@ -194,6 +195,9 @@ export function inferProviderFromModel(model: string): string | undefined {
   if (model.startsWith("thinkingmachines/")) {
     return "baseten";
   }
+  if (model.startsWith("poolside/")) {
+    return "poolside";
+  }
   if (model.includes("/")) {
     return "openrouter";
   }

package/src/shared/provider-env-vars.ts

@@ -32,6 +32,7 @@ export const LLM_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   together: "TOGETHER_API_KEY",
   litellm: "LITELLM_API_KEY",
   baseten: "BASETEN_API_KEY",
+  poolside: "POOLSIDE_API_KEY",
 };
 
 /** Search-provider env var names. Mirrors `SEARCH_PROVIDER_CATALOG` BYOK entries. */
@@ -40,6 +41,7 @@ export const SEARCH_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   brave: "BRAVE_API_KEY",
   tavily: "TAVILY_API_KEY",
   firecrawl: "FIRECRAWL_API_KEY",
+  keenable: "KEENABLE_API_KEY",
 };
 
 /**