@vellumai/cli 0.10.5-dev.202607031338.eae4811 → 0.10.5-dev.202607031543.075941f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.5-dev.202607031338.eae4811",
+  "version": "0.10.5-dev.202607031543.075941f",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/sleep.test.ts

@@ -139,7 +139,8 @@ describe("sleep command", () => {
       consoleLog.mockRestore();
     }
 
-    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(2);
+    // assistant + gateway + CES sibling
+    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(3);
   });
 
   test("force stops the assistant even when an active call lease exists", async () => {
@@ -154,7 +155,7 @@ describe("sleep command", () => {
       consoleLog.mockRestore();
     }
 
-    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(2);
+    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(3);
     // The assistant stop passes a generous 120s grace so the daemon's WAL
     // checkpoint completes before any SIGKILL (default 2s would truncate it).
     expect(stopProcessByPidFileMock).toHaveBeenNthCalledWith(
@@ -171,5 +172,12 @@ describe("sleep command", () => {
       undefined,
       7000,
     );
+    // The CES sibling (CES_STANDALONE opt-in) is stopped by its PID file; a
+    // no-op when absent on the default topology.
+    expect(stopProcessByPidFileMock).toHaveBeenNthCalledWith(
+      3,
+      join(assistantRootDir, "ces.pid"),
+      "credential-executor",
+    );
   });
 });

package/src/commands/recover.ts

@@ -12,6 +12,7 @@ import { saveAssistantEntry } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import {
   generateLocalSigningKey,
+  startCes,
   startLocalDaemon,
   startGateway,
 } from "../lib/local";
@@ -117,9 +118,14 @@ export async function recover(): Promise<void> {
   entry.guardianBootstrapSecret = bootstrapSecret;
   saveAssistantEntry(entry);
 
-  // 8. Start daemon + gateway
-  await startLocalDaemon(false, entry.resources, { signingKey });
-  await startGateway(false, entry.resources, { signingKey, bootstrapSecret });
+  // 8. Start CES sibling (opt-in) + daemon + gateway in parallel, the way the
+  // Docker topology brings its sibling processes up together. startCes is a
+  // no-op unless CES_STANDALONE is set.
+  await Promise.all([
+    startCes(false, entry.resources),
+    startLocalDaemon(false, entry.resources, { signingKey }),
+    startGateway(false, entry.resources, { signingKey, bootstrapSecret }),
+  ]);
 
   console.log(`✅ Recovered assistant '${name}'.`);
 }

package/src/commands/sleep.ts

@@ -168,6 +168,18 @@ export async function sleep(): Promise<void> {
     console.log("Gateway stopped.");
   }
 
+  // Stop the CES sibling if one was launched (CES_STANDALONE). No-op when the
+  // PID file is absent — on the default topology the assistant owns CES as an
+  // stdio child and it exits with the daemon.
+  const cesPidFile = join(vellumDir, "ces.pid");
+  const cesStopped = await stopProcessByPidFile(
+    cesPidFile,
+    "credential-executor",
+  );
+  if (cesStopped) {
+    console.log("credential-executor stopped.");
+  }
+
   // Stop the nginx ingress if one is fronting this gateway — otherwise it
   // keeps running against a dead upstream and serves 502s.
   const ingressStopped = await stopIngressNginx(join(vellumDir, "workspace"));

package/src/commands/upgrade.ts

@@ -66,6 +66,7 @@ import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 import {
   generateLocalSigningKey,
   ensureLocalRuntime,
+  startCes,
   startGateway,
   startLocalDaemon,
   stopLocalProcesses,
@@ -434,7 +435,8 @@ async function upgradeDocker(
   }
 
   // Recover the assistant host port from the entry, fall back to default.
-  const assistantPort = entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
+  const assistantPort =
+    entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
 
   // Create pre-upgrade backup (best-effort, daemon must be running)
   await broadcastUpgradeEvent(
@@ -984,8 +986,14 @@ async function upgradeLocal(
   const previousAppVersion = process.env.APP_VERSION;
   process.env.APP_VERSION = stripVersionPrefix(targetVersion);
   try {
-    await startLocalDaemon(false, entry.resources, { signingKey });
-    await startGateway(false, entry.resources, { signingKey, bootstrapSecret });
+    // Bring CES, daemon, and gateway up in parallel, the way the Docker
+    // topology starts its sibling processes together. startCes is a no-op
+    // unless CES_STANDALONE is set.
+    await Promise.all([
+      startCes(false, entry.resources),
+      startLocalDaemon(false, entry.resources, { signingKey }),
+      startGateway(false, entry.resources, { signingKey, bootstrapSecret }),
+    ]);
   } finally {
     if (previousAppVersion === undefined) {
       delete process.env.APP_VERSION;

package/src/commands/wake.ts

@@ -17,6 +17,7 @@ import {
   generateLocalSigningKey,
   isAssistantWatchModeAvailable,
   isGatewayWatchModeAvailable,
+  startCes,
   startLocalDaemon,
   startGateway,
 } from "../lib/local";
@@ -176,7 +177,18 @@ export async function wake(): Promise<void> {
   }
 
   if (!daemonRunning) {
-    await startLocalDaemon(watch, resources, { foreground, signingKey });
+    // Spin up CES and the daemon in parallel, the way the Docker topology
+    // brings its sibling containers up together — the assistant polls for the
+    // CES socket during startup (discoverCesWithRetry), so it tolerates CES
+    // still binding. CES's lifecycle tracks the daemon (its only consumer):
+    // restarting it under a live daemon would sever the daemon's open
+    // connection, so it is only (re)started alongside the daemon. startCes is a
+    // no-op unless CES_STANDALONE is set, in which case the assistant spawns
+    // CES itself as today.
+    await Promise.all([
+      startCes(watch, resources),
+      startLocalDaemon(watch, resources, { foreground, signingKey }),
+    ]);
   }
 
   // Start gateway
@@ -256,7 +268,11 @@ export async function wake(): Promise<void> {
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       try {
         await resetGuardianBootstrap(loopbackUrl, bootstrapSecret);
-        await leaseGuardianToken(loopbackUrl, entry.assistantId, bootstrapSecret);
+        await leaseGuardianToken(
+          loopbackUrl,
+          entry.assistantId,
+          bootstrapSecret,
+        );
         console.log("   Re-provisioned guardian token.");
         break;
       } catch (err) {

package/src/lib/hatch-local.ts

@@ -25,6 +25,7 @@ import type { Species } from "./constants.js";
 import { buildHatchConfigValues, writeInitialConfig } from "./config-utils.js";
 import {
   generateLocalSigningKey,
+  startCes,
   startLocalDaemon,
   startGateway,
   stopLocalProcesses,
@@ -225,10 +226,17 @@ export async function hatchLocal(
   reporter.progress(3, 6, "Starting assistant...");
   const signingKey = generateLocalSigningKey();
   const bootstrapSecret = generateLocalSigningKey();
-  await startLocalDaemon(watch, resources, {
-    defaultWorkspaceConfigPath,
-    signingKey,
-  });
+  // Launch the CES sibling alongside the daemon, in parallel — matching the
+  // Docker topology. Under the opt-in the assistant does not spawn its own CES,
+  // so a freshly hatched instance would otherwise come up with CES unavailable.
+  // startCes is a no-op unless CES_STANDALONE is set.
+  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}`;

package/src/lib/local.ts

@@ -145,6 +145,19 @@ function localRuntimeGatewayDir(
   return isGatewaySourceDir(candidate) ? candidate : undefined;
 }
 
+function localRuntimeCesDir(
+  resources: LocalInstanceResources | undefined,
+): string | undefined {
+  const installDir = resources?.runtimeInstallDir;
+  if (!installDir) return undefined;
+  const candidate = packagePath(
+    installDir,
+    "@vellumai/credential-executor",
+    "",
+  );
+  return isCesSourceDir(candidate) ? candidate : undefined;
+}
+
 export function ensureLocalRuntime(
   resources: LocalInstanceResources,
   version: string,
@@ -347,6 +360,18 @@ function isGatewaySourceDir(dir: string): boolean {
   }
 }
 
+function isCesSourceDir(dir: string): boolean {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "main.ts")))
+    return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.name === "@vellumai/credential-executor";
+  } catch {
+    return false;
+  }
+}
+
 function findGatewaySourceFromCwd(): string | undefined {
   let current = process.cwd();
   while (true) {
@@ -540,6 +565,14 @@ function applyDaemonEnvOverrides(
     env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
       options.defaultWorkspaceConfigPath;
   }
+  // When the CLI launches CES as a sibling (CES_STANDALONE), pin the daemon to
+  // the exact socket the sibling binds so the two agree regardless of any stale
+  // CES_LOCAL_SOCKET inherited from the parent environment. The assistant then
+  // connects to the sibling instead of spawning its own CES.
+  if (isCesSiblingOptIn()) {
+    env.CES_STANDALONE = "1";
+    env.CES_LOCAL_SOCKET = resolveCesSocketPath(resources);
+  }
   applyIpcSocketDirOverride(env);
 }
 
@@ -731,6 +764,168 @@ function resolveGatewayDir(resources?: LocalInstanceResources): string {
   }
 }
 
+function resolveCesDir(resources?: LocalInstanceResources): string {
+  const runtimeCesDir = localRuntimeCesDir(resources);
+  if (runtimeCesDir) return runtimeCesDir;
+
+  // Source tree / npm sibling: cli/src/lib/ → ../../.. → credential-executor/
+  const sourceDir = join(
+    import.meta.dir,
+    "..",
+    "..",
+    "..",
+    "credential-executor",
+  );
+  if (isCesSourceDir(sourceDir)) {
+    return sourceDir;
+  }
+
+  // npm-installed elsewhere on disk: resolve via the package entry.
+  try {
+    const pkgPath = _require.resolve(
+      "@vellumai/credential-executor/package.json",
+    );
+    return dirname(pkgPath);
+  } catch {
+    throw new Error(
+      "credential-executor not found. Ensure @vellumai/credential-executor is installed or run from the source tree.",
+    );
+  }
+}
+
+/**
+ * Resolve the Unix socket path the CLI-launched CES sibling binds and the
+ * daemon connects to. Both sides read `CES_LOCAL_SOCKET`, which the CLI sets to
+ * this exact path so they agree. On macOS, long workspace paths are relocated
+ * to a short tmpdir override (the same one the IPC sockets use) to stay under
+ * the AF_UNIX path limit.
+ */
+function resolveCesSocketPath(resources?: LocalInstanceResources): string {
+  const workspaceDir = resources
+    ? join(resources.instanceDir, ".vellum", "workspace")
+    : join(homedir(), ".vellum", "workspace");
+  const override = computeIpcSocketDirOverride(workspaceDir);
+  const socketDir = override ?? workspaceDir;
+  mkdirSync(socketDir, { recursive: true });
+  return join(socketDir, "ces.sock");
+}
+
+/**
+ * Whether the CLI should launch CES as an independent sibling process instead
+ * of leaving the assistant to spawn it as an stdio child. Temporary opt-in
+ * (`CES_STANDALONE=1`) while local CES converges onto the sibling model that
+ * containerized homes already use.
+ */
+function isCesSiblingOptIn(): boolean {
+  return process.env.CES_STANDALONE === "1";
+}
+
+/**
+ * Launch the local CES sibling over a Unix socket (opted into via
+ * `CES_STANDALONE=1`). No-op unless the opt-in is set, in which case the
+ * assistant continues to spawn CES itself as today.
+ *
+ * The sibling runs with `CES_STANDALONE=1` so its lifecycle is anchored to
+ * SIGTERM rather than stdin EOF, mirroring the gateway: a CLI-owned process
+ * with a PID file under `.vellum/ces.pid`, started by `wake` and stopped by
+ * `sleep`.
+ */
+export async function startCes(
+  watch: boolean = false,
+  resources?: LocalInstanceResources,
+): Promise<void> {
+  if (!isCesSiblingOptIn()) return;
+
+  const vellumDir = resources
+    ? join(resources.instanceDir, ".vellum")
+    : join(homedir(), ".vellum");
+  const cesPidFile = join(vellumDir, "ces.pid");
+
+  // Kill any existing sibling first — a stale CES holds the socket and would
+  // corrupt the shared credential store if a second copy also bound it.
+  await stopProcessByPidFile(cesPidFile, "credential-executor");
+
+  console.log("🔐 Starting credential-executor sibling...");
+
+  const socketPath = resolveCesSocketPath(resources);
+  // A stale socket file from an unclean shutdown blocks re-bind; CES unlinks it
+  // on startup, but remove it here too so a leftover never masks a launch bug.
+  try {
+    unlinkSync(socketPath);
+  } catch {
+    /* no stale socket — fine */
+  }
+
+  const securityDir = resources
+    ? join(resources.instanceDir, ".vellum", "protected")
+    : join(homedir(), ".vellum", "protected");
+  const workspaceDir = resources
+    ? join(resources.instanceDir, ".vellum", "workspace")
+    : join(homedir(), ".vellum", "workspace");
+  mkdirSync(securityDir, { recursive: true });
+
+  const cesEnv: Record<string, string | undefined> = {
+    ...process.env,
+    CES_STANDALONE: "1",
+    CES_LOCAL_SOCKET: socketPath,
+    CREDENTIAL_SECURITY_DIR: securityDir,
+    VELLUM_WORKSPACE_DIR: workspaceDir,
+  };
+
+  let ces;
+  const runtimeCesDir = !watch ? localRuntimeCesDir(resources) : undefined;
+  const cesBinary = join(dirname(process.execPath), "credential-executor");
+  if (!runtimeCesDir && existsSync(cesBinary) && !watch) {
+    // Compiled binary alongside the CLI (desktop app / compiled CLI).
+    const cesLogFd = openLogFile("hatch.log");
+    ces = spawn(cesBinary, [], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: cesEnv,
+    });
+    pipeToLogFile(ces, cesLogFd, "credential-executor");
+  } else {
+    // Source tree / bunx: run the CES entry point via bun.
+    const cesDir = runtimeCesDir ?? resolveCesDir(resources);
+    const bunArgs = watch
+      ? ["--watch", "run", "src/main.ts"]
+      : ["run", "src/main.ts"];
+    const cesLogFd = openLogFile("hatch.log");
+    ces = spawn(resolveBunExecutable(), bunArgs, {
+      cwd: cesDir,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: envWithBunPath(cesEnv),
+    });
+    pipeToLogFile(ces, cesLogFd, "credential-executor");
+    if (watch) {
+      console.log("   credential-executor started in watch mode (bun --watch)");
+    }
+  }
+
+  ces.unref();
+
+  if (ces.pid) {
+    mkdirSync(vellumDir, { recursive: true });
+    writeFileSync(cesPidFile, String(ces.pid), "utf-8");
+  }
+
+  // Wait for the socket to appear so the daemon's discovery finds it on the
+  // first probe rather than burning its retry budget.
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    if (existsSync(socketPath)) break;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  if (!existsSync(socketPath)) {
+    console.warn(
+      "⚠ credential-executor started but its socket did not appear within 10s",
+    );
+  } else {
+    console.log("✅ credential-executor started\n");
+  }
+}
+
 /**
  * Check if the daemon is responsive by hitting its HTTP `/healthz` endpoint.
  * This replaces the socket-based `isSocketResponsive()` check.
@@ -1421,6 +1616,12 @@ export async function stopLocalProcesses(
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
 
+  // Stop the CES sibling if one was launched (CES_STANDALONE). No-op when the
+  // PID file is absent, so this is safe on the default topology where the
+  // assistant owns CES as an stdio child.
+  const cesPidFile = join(vellumDir, "ces.pid");
+  await stopProcessByPidFile(cesPidFile, "credential-executor");
+
   // Kill ngrok directly by PID rather than using stopProcessByPidFile, because
   // isVellumProcess() won't match the ngrok binary — resulting in a no-op that
   // leaves ngrok running. Verify the PID still belongs to ngrok before killing

package/src/lib/process.ts

@@ -15,7 +15,7 @@ export function isVellumProcess(pid: number): boolean {
       timeout: 3000,
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
-    return /vellum-daemon|vellum-cli|vellum-gateway|@vellumai|\/\.?vellum\/|\/daemon\/main|\/\.vellum\/.*qdrant\/bin\/qdrant/.test(
+    return /vellum-daemon|vellum-cli|vellum-gateway|credential-executor|@vellumai|\/\.?vellum\/|\/daemon\/main|\/\.vellum\/.*qdrant\/bin\/qdrant/.test(
       output,
     );
   } catch {