@vellumai/cli 0.10.11 → 0.10.12-dev.202607242326.75b9ec6

package/src/lib/hatch-local.ts

@@ -46,6 +46,7 @@ import {
 import { logHatchNextSteps } from "./hatch-next-steps.js";
 import { checkProviderApiKey } from "./api-key-check.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
+import { withLocalHatchLock } from "./local-hatch-lock.js";
 
 /**
  * Attempts to place a symlink at the given path pointing to cliBinary.
@@ -179,89 +180,116 @@ export async function hatchLocal(
     name ?? process.env.VELLUM_ASSISTANT_NAME,
   );
 
-  reporter.progress(1, 6, "Allocating resources...");
+  const { resources, runtimeUrl, loopbackUrl, bootstrapSecret } =
+    await withLocalHatchLock(async () => {
+      reporter.progress(1, 6, "Allocating resources...");
 
-  const existing = findAssistantByName(instanceName);
-  if (existing && (!existing.cloud || existing.cloud === "local")) {
-    throw new Error(
-      `An assistant named "${instanceName}" is already hatched.\n` +
-        `Run \`vellum wake\` to restart it, or \`vellum retire ${instanceName}\` to remove it first.`,
-    );
-  }
+      const existing = findAssistantByName(instanceName);
+      if (existing && (!existing.cloud || existing.cloud === "local")) {
+        throw new Error(
+          `An assistant named "${instanceName}" is already hatched.\n` +
+            `Run \`vellum wake\` to restart it, or \`vellum retire ${instanceName}\` to remove it first.`,
+        );
+      }
 
-  const resources = await allocateLocalResources(instanceName);
+      const resources = await allocateLocalResources(instanceName);
 
-  const logsDir = join(
-    resources.instanceDir,
-    ".vellum",
-    "workspace",
-    "data",
-    "logs",
-  );
-  archiveLogFile("hatch.log", logsDir);
-  resetLogFile("hatch.log");
+      const logsDir = join(
+        resources.instanceDir,
+        ".vellum",
+        "workspace",
+        "data",
+        "logs",
+      );
+      archiveLogFile("hatch.log", logsDir);
+      resetLogFile("hatch.log");
 
-  reporter.log(`🥚 Hatching local assistant: ${instanceName}`);
-  reporter.log(`   Species: ${species}`);
-  reporter.log("");
+      reporter.log(`🥚 Hatching local assistant: ${instanceName}`);
+      reporter.log(`   Species: ${species}`);
+      reporter.log("");
 
-  const apiKeyCheck = checkProviderApiKey();
-  if (!apiKeyCheck.hasKey) {
-    reporter.warn(
-      "Warning: No LLM provider API key is configured. The assistant will fail when you try to send a message.",
-    );
-    reporter.warn("  To fix, export your key before running vellum hatch:");
-    reporter.warn("  export ANTHROPIC_API_KEY=<your-key>");
-    reporter.warn("");
-  }
+      const apiKeyCheck = checkProviderApiKey();
+      if (!apiKeyCheck.hasKey) {
+        reporter.warn(
+          "Warning: No LLM provider API key is configured. The assistant will fail when you try to send a message.",
+        );
+        reporter.warn("  To fix, export your key before running vellum hatch:");
+        reporter.warn("  export ANTHROPIC_API_KEY=<your-key>");
+        reporter.warn("");
+      }
 
-  if (!process.env.APP_VERSION) {
-    process.env.APP_VERSION = cliPkg.version;
-  }
+      if (!process.env.APP_VERSION) {
+        process.env.APP_VERSION = cliPkg.version;
+      }
 
-  reporter.progress(2, 6, "Writing configuration...");
-  const hatchConfigValues = buildHatchConfigValues(configValues, provider);
-  const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
-
-  reporter.progress(3, 6, "Starting assistant...");
-  const signingKey = generateLocalSigningKey();
-  const bootstrapSecret = generateLocalSigningKey();
-  // Launch the CES sibling alongside the daemon, in parallel — matching the
-  // Docker topology. The assistant does not spawn its own CES, so a freshly
-  // hatched instance would otherwise come up with CES unavailable.
-  // startCes always launches the CES sibling.
-  await Promise.all([
-    startCes(watch, resources),
-    startLocalDaemon(watch, resources, {
-      defaultWorkspaceConfigPath,
-      signingKey,
-    }),
-  ]);
-
-  reporter.progress(4, 6, "Starting gateway...");
-  let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
-  try {
-    runtimeUrl = await startGateway(watch, resources, {
-      signingKey,
-      bootstrapSecret,
-      envOverrides: flagEnvVars,
+      reporter.progress(2, 6, "Writing configuration...");
+      const hatchConfigValues = buildHatchConfigValues(configValues, provider);
+      const defaultWorkspaceConfigPath = writeInitialConfig(hatchConfigValues);
+
+      reporter.progress(3, 6, "Starting assistant...");
+      const signingKey = generateLocalSigningKey();
+      const bootstrapSecret = generateLocalSigningKey();
+      let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+      try {
+        // Launch the CES sibling alongside the daemon, in parallel — matching the
+        // Docker topology. The assistant does not spawn its own CES, so a freshly
+        // hatched instance would otherwise come up with CES unavailable.
+        // startCes always launches the CES sibling.
+        const startupResults = await Promise.allSettled([
+          startCes(watch, resources),
+          startLocalDaemon(watch, resources, {
+            defaultWorkspaceConfigPath,
+            requireReady: true,
+            signingKey,
+          }),
+        ]);
+        const startupFailure = startupResults.find(
+          (result): result is PromiseRejectedResult =>
+            result.status === "rejected",
+        );
+        if (startupFailure) {
+          throw startupFailure.reason;
+        }
+
+        reporter.progress(4, 6, "Starting gateway...");
+        runtimeUrl = await startGateway(watch, resources, {
+          signingKey,
+          bootstrapSecret,
+          envOverrides: flagEnvVars,
+          requireReady: true,
+        });
+      } catch (error) {
+        reporter.error(
+          `\n❌ Local assistant startup failed — stopping partial processes.`,
+        );
+        await stopLocalProcesses(resources);
+        throw error;
+      }
+
+      const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+      const localEntry: AssistantEntry = {
+        assistantId: instanceName,
+        runtimeUrl,
+        localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
+        cloud: "local",
+        species,
+        hatchedAt: new Date().toISOString(),
+        resources: { ...resources, signingKey },
+        guardianBootstrapSecret: bootstrapSecret,
+      };
+
+      reporter.progress(5, 6, "Saving configuration...");
+      saveAssistantEntry(localEntry);
+      setActiveAssistant(instanceName);
+
+      return { resources, runtimeUrl, loopbackUrl, bootstrapSecret };
     });
-  } catch (error) {
-    // Gateway failed — stop the daemon we just started so we don't leave
-    // orphaned processes with no lock file entry.
-    reporter.error(
-      `\n❌ Gateway startup failed — stopping assistant to avoid orphaned processes.`,
-    );
-    await stopLocalProcesses(resources);
-    throw error;
-  }
 
   // Lease a guardian token so the desktop app can import it on first launch
   // 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.
-  reporter.progress(5, 6, "Securing connection...");
-  const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+  reporter.progress(6, 6, "Securing connection...");
   const maxLeaseAttempts = 3;
   let guardianAccessToken: string | undefined;
   for (let attempt = 1; attempt <= maxLeaseAttempts; attempt++) {
@@ -290,22 +318,6 @@ export async function hatchLocal(
     }
   }
 
-  // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.
-  const localEntry: AssistantEntry = {
-    assistantId: instanceName,
-    runtimeUrl,
-    localUrl: `http://127.0.0.1:${resources.gatewayPort}`,
-    cloud: "local",
-    species,
-    hatchedAt: new Date().toISOString(),
-    resources: { ...resources, signingKey },
-    guardianBootstrapSecret: bootstrapSecret,
-  };
-
-  reporter.progress(6, 6, "Saving configuration...");
-  saveAssistantEntry(localEntry);
-  setActiveAssistant(instanceName);
-
   if (process.env.VELLUM_DESKTOP_APP) {
     installCLISymlink();
   }

package/src/lib/ingress-config.ts

@@ -0,0 +1,101 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  lookupAssistantByIdentifier,
+  saveAssistantEntry,
+} from "./assistant-config.js";
+
+/**
+ * Shared workspace-config helpers for tunnel providers (ngrok, cloudflare,
+ * tailscale) and the nginx ingress proxy. Each provider fronts the local edge
+ * and records the resulting public URL under `ingress.publicBaseUrl` so webhook
+ * integrations can reach the assistant. The workspace config is the
+ * gateway-facing contract; when an `assistantId` is supplied, the URL is also
+ * mirrored onto the lockfile entry (`ingressUrl`) — the CLI-owned contract
+ * that CLI features (e.g. remote-web pairing defaults) read, per the
+ * no-`.vellum/`-reads boundary in cli/AGENTS.md.
+ */
+
+/** Default workspace dir: `$VELLUM_WORKSPACE_DIR` or `~/.vellum/workspace`. */
+export function getDefaultWorkspaceDir(): string {
+  return (
+    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
+    join(homedir(), ".vellum", "workspace")
+  );
+}
+
+function getConfigPath(workspaceDir: string): string {
+  return join(workspaceDir, "config.json");
+}
+
+/** Read the workspace `config.json`, or an empty object when it is absent. */
+export function loadRawConfig(workspaceDir: string): Record<string, unknown> {
+  const configPath = getConfigPath(workspaceDir);
+  if (!existsSync(configPath)) return {};
+  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+/** Write the workspace `config.json`, creating parent directories as needed. */
+export function saveRawConfig(
+  workspaceDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = getConfigPath(workspaceDir);
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+/** Mirror the ingress URL onto the lockfile entry; null removes it. */
+function stampLockfileIngressUrl(
+  assistantId: string,
+  publicUrl: string | null,
+): void {
+  const result = lookupAssistantByIdentifier(assistantId);
+  if (result.status !== "found") {
+    return;
+  }
+  const entry = result.entry;
+  if (publicUrl) {
+    entry.ingressUrl = publicUrl;
+  } else {
+    delete entry.ingressUrl;
+  }
+  saveAssistantEntry(entry);
+}
+
+/** Persist a public ingress URL to the workspace config and enable ingress. */
+export function saveIngressUrl(
+  workspaceDir: string,
+  publicUrl: string,
+  assistantId?: string,
+): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  ingress.publicBaseUrl = publicUrl;
+  ingress.enabled = true;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+  if (assistantId) {
+    stampLockfileIngressUrl(assistantId, publicUrl);
+  }
+}
+
+/** Clear the ingress public base URL from the workspace config. */
+export function clearIngressUrl(
+  workspaceDir: string,
+  assistantId?: string,
+): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  delete ingress.publicBaseUrl;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+  if (assistantId) {
+    stampLockfileIngressUrl(assistantId, null);
+  }
+}

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