@vellumai/cli 0.10.0 → 0.10.1-staging.1

package/src/commands/upgrade.ts

@@ -1,4 +1,6 @@
 import { spawnSync } from "child_process";
+import { writeFileSync } from "fs";
+import { join } from "path";
 
 import cliPkg from "../../package.json";
 
@@ -6,7 +8,6 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
-  resolveCloud,
   saveAssistantEntry,
   type AssistantEntry,
 } from "../lib/assistant-config";
@@ -56,10 +57,24 @@ import {
 } from "../lib/upgrade-lifecycle.js";
 import {
   compareVersions,
+  parseVersion,
   stripVersionPrefix,
   versionsEqual,
 } from "../lib/version-compat.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import {
+  generateLocalSigningKey,
+  ensureLocalRuntime,
+  startGateway,
+  startLocalDaemon,
+  stopLocalProcesses,
+} from "../lib/local.js";
+import { maybeStartNgrokTunnel } from "../lib/ngrok.js";
+import {
+  leaseGuardianToken,
+  resetGuardianBootstrap,
+  seedGuardianTokenFromSiblingEnv,
+} from "../lib/guardian-token.js";
 
 interface UpgradeArgs {
   name: string | null;
@@ -111,7 +126,7 @@ function parseArgs(): UpgradeArgs {
         "  --no-wait            Platform assistants only: return after the upgrade request is accepted instead of waiting for completion",
       );
       console.log(
-        "  --force              Docker assistants only: reinstall even when already on the target version",
+        "  --force              Local/Docker assistants only: reinstall even when already on the target version",
       );
       console.log("");
       console.log("Examples:");
@@ -724,6 +739,314 @@ async function upgradeDocker(
   }
 }
 
+function isLocalBuildVersion(version: string): boolean {
+  const parsed = parseVersion(version);
+  return parsed?.pre?.split(".")[0] === "local";
+}
+
+export async function targetVersionFromCli(
+  version: string | null,
+  cliVersion = cliPkg.version,
+  resolveLatestStable: () => Promise<string> = resolveLatestStableTag,
+): Promise<string> {
+  const targetVersion = version ?? (cliVersion ? `v${cliVersion}` : "latest");
+  if (!isLocalBuildVersion(targetVersion)) return targetVersion;
+
+  const latestTag = await resolveLatestStable();
+  console.log(
+    `   Local build version ${targetVersion} is not published; using latest stable ${latestTag}.\n`,
+  );
+  return latestTag;
+}
+
+function localAdminUrl(entry: AssistantEntry): string {
+  return entry.localUrl ?? entry.runtimeUrl;
+}
+
+async function ensureGuardianTokenAfterLocalUpgrade(
+  entry: AssistantEntry,
+  gatewayPort: number,
+  bootstrapSecret?: string,
+): Promise<void> {
+  if (seedGuardianTokenFromSiblingEnv(entry.assistantId)) {
+    console.log("   Seeded guardian token from sibling environment.");
+  }
+
+  const loopbackUrl = `http://127.0.0.1:${gatewayPort}`;
+  const maxAttempts = 3;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await resetGuardianBootstrap(loopbackUrl, bootstrapSecret);
+      await leaseGuardianToken(loopbackUrl, entry.assistantId, bootstrapSecret);
+      console.log("   Re-provisioned guardian token.");
+      return;
+    } catch (err) {
+      if (attempt < maxAttempts) {
+        await new Promise((r) => setTimeout(r, 2000 * 2 ** (attempt - 1)));
+      } else {
+        console.warn(
+          `   Guardian token re-provision failed after ${maxAttempts} attempts: ${err}`,
+        );
+      }
+    }
+  }
+}
+
+async function fetchLocalUpgradeState(
+  entry: AssistantEntry,
+  adminUrl: string,
+): Promise<{
+  currentVersion?: string;
+  preMigrationState: {
+    dbVersion?: number;
+    lastWorkspaceMigrationId?: string;
+  };
+}> {
+  try {
+    const healthResp = await loopbackSafeFetch(
+      `${adminUrl}/healthz?include=migrations`,
+      {
+        signal: AbortSignal.timeout(5000),
+      },
+    );
+    if (healthResp.ok) {
+      const health = (await healthResp.json()) as {
+        version?: string;
+        migrations?: { dbVersion?: number; lastWorkspaceMigrationId?: string };
+      };
+      return {
+        currentVersion: health.version,
+        preMigrationState: health.migrations ?? {},
+      };
+    }
+  } catch {
+    // Best-effort — sleeping assistants and unhealthy gateways can still be restarted.
+  }
+
+  return { preMigrationState: {} };
+}
+
+async function upgradeLocal(
+  entry: AssistantEntry,
+  version: string | null,
+  force: boolean,
+): Promise<void> {
+  if (!entry.resources) {
+    const msg = `Local assistant '${entry.assistantId}' is missing resource configuration. Re-hatch to fix.`;
+    console.error(msg);
+    emitCliError("UNKNOWN", msg);
+    process.exit(1);
+  }
+
+  const targetVersion = await targetVersionFromCli(version);
+  const adminUrl = localAdminUrl(entry);
+  const { currentVersion, preMigrationState } = await fetchLocalUpgradeState(
+    entry,
+    adminUrl,
+  );
+
+  if (!currentVersion && targetVersion) {
+    console.warn(
+      "⚠️  Could not determine current version from health endpoint — skipping version-direction check.\n",
+    );
+  }
+  if (currentVersion && targetVersion) {
+    const cmp = compareVersions(targetVersion, currentVersion);
+    if (cmp !== null && cmp < 0) {
+      const msg = `Cannot upgrade to an older version (${targetVersion} < ${currentVersion}). Use \`vellum rollback --version ${targetVersion}\` instead.`;
+      console.error(msg);
+      emitCliError("VERSION_DIRECTION", msg);
+      process.exit(1);
+    }
+  }
+
+  if (currentVersion && versionsEqual(targetVersion, currentVersion)) {
+    if (!force) {
+      console.log(
+        `✅ Already on ${targetVersion}. Nothing to do. Pass --force to reinstall.`,
+      );
+      return;
+    }
+    console.log(`🔁 Reinstalling ${targetVersion} (--force)...\n`);
+  }
+
+  console.log(
+    `🔄 Upgrading local assistant '${entry.assistantId}' to ${targetVersion}...\n`,
+  );
+
+  await commitWorkspaceViaGateway(
+    adminUrl,
+    entry.assistantId,
+    buildUpgradeCommitMessage({
+      action: "upgrade",
+      phase: "starting",
+      from: currentVersion ?? "unknown",
+      to: targetVersion,
+      topology: "local",
+      assistantId: entry.assistantId,
+    }),
+  );
+
+  console.log("📢 Notifying connected clients...");
+  await broadcastUpgradeEvent(
+    adminUrl,
+    entry.assistantId,
+    buildStartingEvent(targetVersion),
+  );
+  await new Promise((r) => setTimeout(r, 500));
+
+  await broadcastUpgradeEvent(
+    adminUrl,
+    entry.assistantId,
+    buildProgressEvent(UPGRADE_PROGRESS.BACKING_UP),
+  );
+  console.log("📦 Creating pre-upgrade backup...");
+  const backupPath = await createBackup(adminUrl, entry.assistantId, {
+    prefix: `${entry.assistantId}-pre-upgrade`,
+    description: `Pre-upgrade snapshot before ${currentVersion ?? "unknown"} → ${targetVersion}`,
+  });
+  if (backupPath) {
+    console.log(`   Backup saved: ${backupPath}\n`);
+    pruneOldBackups(entry.assistantId, 3);
+  } else {
+    console.warn("⚠️  Pre-upgrade backup failed (continuing with upgrade)\n");
+  }
+
+  let signingKey = entry.resources.signingKey;
+  let bootstrapSecret = entry.guardianBootstrapSecret;
+  let entryChanged = false;
+  if (!signingKey) {
+    signingKey = generateLocalSigningKey();
+    entry.resources = { ...entry.resources, signingKey };
+    entryChanged = true;
+  }
+  if (!bootstrapSecret) {
+    bootstrapSecret = generateLocalSigningKey();
+    entry.guardianBootstrapSecret = bootstrapSecret;
+    entryChanged = true;
+  }
+
+  if (
+    entryChanged ||
+    backupPath ||
+    currentVersion ||
+    preMigrationState.dbVersion !== undefined ||
+    preMigrationState.lastWorkspaceMigrationId !== undefined
+  ) {
+    saveAssistantEntry({
+      ...entry,
+      previousVersion: currentVersion,
+      previousDbMigrationVersion: preMigrationState.dbVersion,
+      previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
+      preUpgradeBackupPath: backupPath ?? undefined,
+    });
+  }
+
+  await broadcastUpgradeEvent(
+    adminUrl,
+    entry.assistantId,
+    buildProgressEvent(UPGRADE_PROGRESS.INSTALLING),
+  );
+
+  console.log(
+    "⬇️  Downloading local runtime packages (assistant, gateway, credential-executor)...",
+  );
+  const runtimeInstall = ensureLocalRuntime(entry.resources, targetVersion, {
+    force,
+  });
+  entry.resources = {
+    ...entry.resources,
+    runtimeVersion: runtimeInstall.version,
+    runtimeInstallDir: runtimeInstall.installDir,
+  };
+  saveAssistantEntry({
+    ...entry,
+    previousVersion: currentVersion,
+    previousDbMigrationVersion: preMigrationState.dbVersion,
+    previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
+    preUpgradeBackupPath: backupPath ?? undefined,
+  });
+  console.log(`   Runtime installed: ${runtimeInstall.installDir}\n`);
+
+  console.log("🛑 Stopping local assistant processes...");
+  await stopLocalProcesses(entry.resources);
+  console.log("✅ Local assistant processes stopped\n");
+
+  console.log("🚀 Starting upgraded local assistant...");
+  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 });
+  } finally {
+    if (previousAppVersion === undefined) {
+      delete process.env.APP_VERSION;
+    } else {
+      process.env.APP_VERSION = previousAppVersion;
+    }
+  }
+  await ensureGuardianTokenAfterLocalUpgrade(
+    entry,
+    entry.resources.gatewayPort,
+    bootstrapSecret,
+  );
+  console.log("✅ Local assistant processes started\n");
+
+  const workspaceDir = join(
+    entry.resources.instanceDir,
+    ".vellum",
+    "workspace",
+  );
+  const ngrokChild = await maybeStartNgrokTunnel(
+    entry.resources.gatewayPort,
+    workspaceDir,
+  );
+  if (ngrokChild?.pid) {
+    writeFileSync(
+      join(entry.resources.instanceDir, ".vellum", "ngrok.pid"),
+      String(ngrokChild.pid),
+    );
+  }
+
+  console.log("Waiting for assistant to become ready...");
+  const ready = await waitForReady(adminUrl);
+  if (!ready) {
+    await broadcastUpgradeEvent(
+      adminUrl,
+      entry.assistantId,
+      buildCompleteEvent(currentVersion ?? "unknown", false),
+    );
+    const msg = `Upgrade to ${targetVersion} failed: local assistant did not become ready.`;
+    console.error(`\n❌ ${msg}`);
+    emitCliError("READINESS_TIMEOUT", msg);
+    process.exit(1);
+  }
+
+  await broadcastUpgradeEvent(
+    adminUrl,
+    entry.assistantId,
+    buildCompleteEvent(targetVersion, true),
+  );
+
+  await commitWorkspaceViaGateway(
+    adminUrl,
+    entry.assistantId,
+    buildUpgradeCommitMessage({
+      action: "upgrade",
+      phase: "complete",
+      from: currentVersion ?? "unknown",
+      to: targetVersion,
+      topology: "local",
+      assistantId: entry.assistantId,
+      result: "success",
+    }),
+  );
+
+  console.log(
+    `\n✅ Local assistant '${entry.assistantId}' upgraded to ${targetVersion}.`,
+  );
+}
+
 interface UpgradeApiResponse {
   detail: string;
   version: string | null;
@@ -805,9 +1128,7 @@ async function waitForPlatformUpgrade(
           entry.assistantId,
         );
         if (health.status === "healthy") {
-          console.log(
-            `✅ Upgraded to ${finalVersion} — assistant is healthy.`,
-          );
+          console.log(`✅ Upgraded to ${finalVersion} — assistant is healthy.`);
           return;
         }
         await sleep(PLATFORM_HEALTH_CONFIRM_INTERVAL_MS);
@@ -854,10 +1175,7 @@ async function upgradePlatform(
   // downgrades before POSTing, and bail if an upgrade is already running.
   const [assistantDetail, health] = await Promise.all([
     fetchAssistantDetail(token, entry.assistantId, entry.runtimeUrl),
-    checkManagedHealth(
-      entry.runtimeUrl || getPlatformUrl(),
-      entry.assistantId,
-    ),
+    checkManagedHealth(entry.runtimeUrl || getPlatformUrl(), entry.assistantId),
   ]);
   // Health probe first, DB-backed field as the sleeping-assistant fallback.
   const currentVersion =
@@ -1117,10 +1435,7 @@ async function upgradeFinalize(
  * that need it.  If the CLI was updated and re-exec'd, this function never
  * returns — the process is replaced.
  */
-async function resolveLatestAndMaybeSelfUpdate(
-  name: string | null,
-  flags: { noWait: boolean; force: boolean },
-): Promise<string> {
+async function resolveLatestStableTag(): Promise<string> {
   console.log("🔍 Fetching latest stable release...");
   const latestVersion = await fetchLatestStableVersion();
   if (!latestVersion) {
@@ -1134,9 +1449,14 @@ async function resolveLatestAndMaybeSelfUpdate(
     process.exit(1);
   }
 
-  const latestTag = latestVersion.startsWith("v")
-    ? latestVersion
-    : `v${latestVersion}`;
+  return latestVersion.startsWith("v") ? latestVersion : `v${latestVersion}`;
+}
+
+async function resolveLatestAndMaybeSelfUpdate(
+  name: string | null,
+  flags: { noWait: boolean; force: boolean },
+): Promise<string> {
+  const latestTag = await resolveLatestStableTag();
   const currentTag = cliPkg.version ? `v${cliPkg.version}` : null;
 
   console.log(`   Latest stable: ${latestTag}`);
@@ -1148,7 +1468,7 @@ async function resolveLatestAndMaybeSelfUpdate(
     console.log(`🔄 Updating CLI to ${latestTag}...`);
     const installResult = spawnSync(
       "bun",
-      ["install", "-g", `vellum@${stripVersionPrefix(latestVersion)}`],
+      ["install", "-g", `vellum@${stripVersionPrefix(latestTag)}`],
       { stdio: "inherit" },
     );
     if (installResult.error || installResult.status !== 0) {
@@ -1203,22 +1523,28 @@ export async function upgrade(): Promise<void> {
   // self-update the CLI if it's behind.  The resolved version is then used
   // as the explicit target for the rest of the upgrade flow.
   let effectiveVersion = version;
+  const cloud = entry.cloud;
   if (latest) {
-    const latestTag = await resolveLatestAndMaybeSelfUpdate(name, {
-      noWait,
-      force,
-    });
-    effectiveVersion = latestTag;
+    effectiveVersion =
+      cloud === "local"
+        ? await resolveLatestStableTag()
+        : await resolveLatestAndMaybeSelfUpdate(name, {
+            noWait,
+            force,
+          });
   }
 
-  const cloud = resolveCloud(entry);
-
   try {
     if (cloud === "docker") {
       await upgradeDocker(entry, effectiveVersion, force);
       return;
     }
 
+    if (cloud === "local") {
+      await upgradeLocal(entry, effectiveVersion, force);
+      return;
+    }
+
     if (cloud === "vellum") {
       await upgradePlatform(entry, effectiveVersion, !noWait);
       return;
@@ -1238,7 +1564,7 @@ export async function upgrade(): Promise<void> {
     process.exit(1);
   }
 
-  const msg = `Error: Upgrade is not supported for '${cloud}' assistants. Only 'docker' and 'vellum' assistants can be upgraded via the CLI.`;
+  const msg = `Error: Upgrade is not supported for '${cloud}' assistants. Only 'local', 'docker', and 'vellum' assistants can be upgraded via the CLI.`;
   console.error(msg);
   emitCliError("UNSUPPORTED_TOPOLOGY", msg);
   process.exit(1);

package/src/lib/assistant-config.ts

@@ -11,6 +11,11 @@ import { homedir } from "os";
 import { dirname, join } from "path";
 
 import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+import {
+  resolveCloud,
+  type LocalAssistantResources,
+  type LockfileAssistant,
+} from "@vellumai/local-mode/contract";
 
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./constants.js";
 import {
@@ -23,11 +28,17 @@ import { getCurrentEnvironment } from "./environments/resolve.js";
 import { probePort } from "./port-probe.js";
 
 /**
- * Per-instance resource paths and ports. Each local assistant instance gets
- * its own directory tree, ports, and socket so multiple instances can run
- * side-by-side without conflicts.
+ * Per-instance resource paths and ports. Each local assistant instance gets its
+ * own directory tree, ports, and socket so multiple instances can run
+ * side-by-side without conflicts. Extends the renderer-safe resources contract
+ * (`instanceDir`, `gatewayPort`, `daemonPort`) with the host-only ports and the
+ * signing key. Host-only and same-process, so it is a plain type — the
+ * renderer-facing shape is the one with a Zod contract.
  */
-export interface LocalInstanceResources {
+export type LocalInstanceResources = Omit<
+  LocalAssistantResources,
+  "instanceDir"
+> & {
   /**
    * Instance-specific data root. New local assistants are placed under
    * `$XDG_DATA_HOME/vellum{-env}/assistants/<name>/`. Legacy entries
@@ -36,10 +47,6 @@ export interface LocalInstanceResources {
    * lives inside it.
    */
   instanceDir: string;
-  /** HTTP port for the daemon runtime server */
-  daemonPort: number;
-  /** HTTP port for the gateway */
-  gatewayPort: number;
   /** HTTP port for the Qdrant vector store */
   qdrantPort: number;
   /** HTTP port for the CES (Claude Extension Server) */
@@ -47,8 +54,12 @@ export interface LocalInstanceResources {
   /** Persisted HMAC signing key (hex). Survives daemon/gateway restarts so
    *  client actor tokens remain valid across `wake` cycles. */
   signingKey?: string;
+  /** Version of the npm-backed local runtime this assistant should run. */
+  runtimeVersion?: string;
+  /** Install directory containing the npm-backed local runtime packages. */
+  runtimeInstallDir?: string;
   [key: string]: unknown;
-}
+};
 
 /** Docker image metadata for the service group. Enables rollback to known-good digests. */
 export interface ContainerInfo {
@@ -65,26 +76,32 @@ export interface ContainerInfo {
   networkName?: string;
 }
 
-export interface AssistantEntry {
-  assistantId: string;
-  /** Platform-provided display name, when available. */
-  name?: string;
+/**
+ * The CLI's full view of an assistant entry: the renderer-safe base
+ * (`LockfileAssistant`, the one canonical Zod contract) plus the host-only and
+ * sensitive fields the CLI reads and writes. Those extra fields never cross a
+ * validation boundary — the same toolchain writes and reads them — so they are
+ * modeled as plain types here rather than re-validated.
+ *
+ * `runtimeUrl` is required (`readAssistants` only returns entries that have one)
+ * and `resources` is the richer host shape. `cloud` is inherited from
+ * `LockfileAssistant` (always present; normalized at the read seam — see
+ * `readAssistants`). The index signature preserves unknown on-disk fields so a
+ * read→write round-trip never drops a newer writer's data.
+ */
+export type AssistantEntry = Omit<
+  LockfileAssistant,
+  "runtimeUrl" | "resources"
+> & {
+  runtimeUrl: string;
+  /** Per-instance resource config. Present for local entries in multi-instance setups. */
+  resources?: LocalInstanceResources;
   /** Older lockfile key for the display name, if present. */
   assistantName?: string;
-  runtimeUrl: string;
   /** Loopback URL for same-machine health checks (e.g. `http://127.0.0.1:7831`).
    *  Avoids mDNS resolution issues when the machine checks its own gateway. */
   localUrl?: string;
   bearerToken?: string;
-  /** Deployment topology / how the assistant is reached. Known values:
-   *  `"local"` (on-machine daemon), `"docker"` (local container),
-   *  `"apple-container"` (macOS-app-managed container), `"vellum"`
-   *  (platform-managed, uses the X-Session-Token auth path), `"gcp"` / `"aws"`
-   *  / `"custom"` (remote, SSH-managed), and `"paired"` (a remote assistant
-   *  paired from another machine — reached via a bearer guardian token at
-   *  `runtimeUrl`; has no local process, container, or `resources`).
-   *  Kept as a free `string` (not a union) for forward-compatibility. */
-  cloud: string;
   /** True when this entry was registered via `vellum connect import` (a remote
    *  pairing). Set alongside `cloud: "paired"`; also backs the re-import /
    *  overwrite guard in connect import. */
@@ -93,12 +110,8 @@ export interface AssistantEntry {
   namespace?: string;
   project?: string;
   region?: string;
-  species?: string;
   sshUser?: string;
   zone?: string;
-  hatchedAt?: string;
-  /** Per-instance resource config. Present for local entries in multi-instance setups. */
-  resources?: LocalInstanceResources;
   /** PID of the file watcher process for docker instances hatched with --watch. */
   watcherPid?: number;
   /** Local bootstrap secret used to lease guardian tokens for Docker assistants after detached hatch. */
@@ -119,7 +132,7 @@ export interface AssistantEntry {
   /** Pre-upgrade workspace migration ID — used by rollback to know how far back to revert. */
   previousWorkspaceMigrationId?: string;
   [key: string]: unknown;
-}
+};
 
 export type AssistantLookupResult =
   | { status: "found"; entry: AssistantEntry }
@@ -300,10 +313,20 @@ function readAssistants(): AssistantEntry[] {
     writeLockfile(data);
   }
 
-  return entries.filter(
-    (e): e is AssistantEntry =>
-      typeof e.assistantId === "string" && typeof e.runtimeUrl === "string",
-  );
+  const result: AssistantEntry[] = [];
+  for (const entry of entries) {
+    if (
+      typeof entry.assistantId !== "string" ||
+      typeof entry.runtimeUrl !== "string"
+    ) {
+      continue;
+    }
+    // Normalize `cloud` once, at the read seam every reader shares, so
+    // downstream code reads `entry.cloud` instead of re-deriving the topology.
+    entry.cloud = resolveCloud(entry);
+    result.push(entry as AssistantEntry);
+  }
+  return result;
 }
 
 function writeAssistants(entries: AssistantEntry[]): void {
@@ -471,6 +494,7 @@ export function loadAllAssistantsAcrossEnvs(
       ) {
         continue;
       }
+      entry.cloud = resolveCloud(entry);
       all.push(entry);
     }
   }
@@ -555,22 +579,6 @@ export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
   process.exit(1);
 }
 
-/**
- * Determine which cloud topology an assistant entry is running on.
- */
-export function resolveCloud(entry: AssistantEntry): string {
-  if (entry.cloud) {
-    return entry.cloud;
-  }
-  if (entry.project) {
-    return "gcp";
-  }
-  if (entry.sshUser) {
-    return "custom";
-  }
-  return "local";
-}
-
 /**
  * Extract the hostname from a URL string. Falls back to stripping the scheme
  * and taking the hostname portion if URL parsing fails.