@vellumai/cli 0.8.2 → 0.8.4

package/src/commands/client.ts

@@ -4,9 +4,12 @@ import path from "node:path";
 
 import {
   findAssistantByName,
+  formatAssistantLookupError,
   getActiveAssistant,
+  lookupAssistantByIdentifier,
   resolveAssistant,
   saveAssistantEntry,
+  type AssistantEntry,
 } from "../lib/assistant-config";
 import {
   DAEMON_INTERNAL_ASSISTANT_ID,
@@ -20,6 +23,7 @@ import {
   WEB_INTERFACE_ID,
   getClientRegistrationHeaders,
 } from "../lib/client-identity";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import {
   fetchOrganizationId,
   fetchPlatformAssistants,
@@ -51,13 +55,9 @@ interface ParsedArgs {
   bearerToken?: string;
   /** Interface identifier sent as X-Vellum-Interface-Id on all requests. */
   interfaceId: SupportedInterface;
-  project?: string;
-  zone?: string;
 }
 
-function readAssistantName(
-  entry: ReturnType<typeof findAssistantByName>,
-): string | undefined {
+function readAssistantName(entry: AssistantEntry | null): string | undefined {
   const rawName = entry?.name ?? entry?.assistantName;
   return typeof rawName === "string" && rawName.trim()
     ? rawName.trim()
@@ -67,7 +67,14 @@ function readAssistantName(
 function parseArgs(): ParsedArgs {
   const args = process.argv.slice(3);
 
-  let positionalName: string | undefined;
+  const positionalName = parseAssistantTargetArg(args, [
+    "--url",
+    "-u",
+    "--assistant-id",
+    "-a",
+    "--interface",
+    "-i",
+  ]);
   const flagArgs: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -84,29 +91,29 @@ function parseArgs(): ParsedArgs {
       args[i + 1]
     ) {
       flagArgs.push(arg, args[++i]);
-    } else if (!arg.startsWith("-") && positionalName === undefined) {
-      positionalName = arg;
     }
   }
 
-  let entry: ReturnType<typeof findAssistantByName> = null;
+  let entry: AssistantEntry | null = null;
   if (positionalName) {
-    entry = findAssistantByName(positionalName);
-    if (!entry) {
-      console.error(
-        `No assistant instance found with name '${positionalName}'.`,
-      );
+    const result = lookupAssistantByIdentifier(positionalName);
+    if (result.status !== "found") {
+      console.error(formatAssistantLookupError(positionalName, result));
       process.exit(1);
     }
+    entry = result.entry;
   } else {
     const hasExplicitUrl =
       flagArgs.includes("--url") || flagArgs.includes("-u");
     const active = getActiveAssistant();
     if (active) {
-      entry = findAssistantByName(active);
+      const result = lookupAssistantByIdentifier(active);
+      if (result.status === "found") {
+        entry = result.entry;
+      }
       if (!entry && !hasExplicitUrl) {
         console.error(
-          `Active assistant '${active}' not found in lockfile. Set an active assistant with 'vellum use <name>'.`,
+          `Active assistant '${active}' not found in lockfile. Set an active assistant with 'vellum use <name-or-id>'.`,
         );
         process.exit(1);
       }
@@ -116,7 +123,7 @@ function parseArgs(): ParsedArgs {
       entry = resolveAssistant();
     } else if (!entry) {
       console.error(
-        "No active assistant set. Set one with 'vellum use <name>' or specify a name: 'vellum client <name>'.",
+        "No active assistant set. Set one with 'vellum use <name-or-id>' or specify one: 'vellum client <name-or-id>'.",
       );
       process.exit(1);
     }
@@ -169,8 +176,6 @@ function parseArgs(): ParsedArgs {
     platformToken,
     bearerToken,
     interfaceId,
-    project: entry?.project,
-    zone: entry?.zone,
   };
 }
 
@@ -217,10 +222,10 @@ function printUsage(): void {
   console.log(`${ANSI.bold}vellum client${ANSI.reset} - Connect to a hatched assistant
 
 ${ANSI.bold}USAGE:${ANSI.reset}
-    vellum client [name] [options]
+    vellum client [name-or-id] [options]
 
 ${ANSI.bold}ARGUMENTS:${ANSI.reset}
-    [name]                     Instance name (default: active)
+    [name-or-id]               Assistant display name or ID (default: active)
 
 ${ANSI.bold}OPTIONS:${ANSI.reset}
     -u, --url <url>            Runtime URL
@@ -343,8 +348,6 @@ export async function client(): Promise<void> {
     platformToken,
     bearerToken,
     interfaceId,
-    project,
-    zone,
   } = parseArgs();
 
   if (interfaceId === WEB_INTERFACE_ID) {
@@ -404,6 +407,6 @@ export async function client(): Promise<void> {
       console.log(`${ANSI.dim}Disconnected.${ANSI.reset}`);
       process.exit(0);
     },
-    { auth, project, zone, assistantName },
+    { auth, assistantName },
   );
 }

package/src/commands/hatch.ts

@@ -8,7 +8,6 @@ import {
   saveAssistantEntry,
   setActiveAssistant,
 } from "../lib/assistant-config";
-import { hatchAws } from "../lib/aws";
 import {
   SPECIES_CONFIG,
   VALID_REMOTE_HOSTS,
@@ -17,7 +16,6 @@ import {
 import type { RemoteHost, Species } from "../lib/constants";
 import { buildNestedConfig } from "../lib/config-utils";
 import { hatchDocker } from "../lib/docker";
-import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import { hatchLocal } from "../lib/hatch-local";
 import {
@@ -169,6 +167,7 @@ source ${INSTALL_SCRIPT_REMOTE_PATH}
 }
 
 const DEFAULT_REMOTE: RemoteHost = "local";
+const UNSUPPORTED_REMOTE_HATCH_TARGETS = new Set<RemoteHost>(["aws", "gcp"]);
 
 interface HatchArgs {
   species: Species;
@@ -177,7 +176,9 @@ interface HatchArgs {
   name: string | null;
   remote: RemoteHost;
   watch: boolean;
+  sourcePath: string | null;
   configValues: Record<string, string>;
+  analyze: boolean;
 }
 
 function parseArgs(): HatchArgs {
@@ -188,7 +189,9 @@ function parseArgs(): HatchArgs {
   let name: string | null = null;
   let remote: RemoteHost = DEFAULT_REMOTE;
   let watch = false;
+  let sourcePath: string | null = null;
   const configValues: Record<string, string> = {};
+  let analyze = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -210,17 +213,33 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --watch                   Run assistant and gateway in watch mode (hot reload on source changes)",
       );
+      console.log(
+        "  --source <path>           Build images from a local source tree at <path> (no watcher). Useful for callers (e.g. evals) that want each run to pick up local CLI changes.",
+      );
       console.log(
         "  --keep-alive              Stay alive after hatch, exit when gateway stops",
       );
       console.log(
         "  --config <key=value>      Set a workspace config value (repeatable)",
       );
+      console.log(
+        "  --analyze                 Emit a structured hatch-timing log line on stdout",
+      );
       process.exit(0);
     } else if (arg === "-d") {
       detached = true;
     } else if (arg === "--watch") {
       watch = true;
+    } else if (arg === "--analyze") {
+      analyze = true;
+    } else if (arg === "--source") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --source requires a path argument");
+        process.exit(1);
+      }
+      sourcePath = next;
+      i++;
     } else if (arg === "--keep-alive") {
       keepAlive = true;
     } else if (arg === "--name") {
@@ -270,7 +289,7 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --analyze`,
       );
       process.exit(1);
     }
@@ -283,7 +302,9 @@ function parseArgs(): HatchArgs {
     name,
     remote,
     watch,
+    sourcePath,
     configValues,
+    analyze,
   };
 }
 
@@ -508,8 +529,17 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const { species, detached, keepAlive, name, remote, watch, configValues } =
-    parseArgs();
+  const {
+    species,
+    detached,
+    keepAlive,
+    name,
+    remote,
+    watch,
+    sourcePath,
+    configValues,
+    analyze,
+  } = parseArgs();
 
   if (watch && remote !== "local" && remote !== "docker") {
     console.error(
@@ -518,30 +548,33 @@ export async function hatch(): Promise<void> {
     process.exit(1);
   }
 
-  if (remote === "local") {
-    await hatchLocal(species, name, watch, keepAlive, configValues);
-    return;
+  if (sourcePath !== null && remote !== "docker") {
+    console.error(
+      "Error: --source is only supported for docker hatch targets.",
+    );
+    process.exit(1);
   }
 
-  if (remote === "gcp") {
-    await hatchGcp(
-      species,
-      detached,
-      name,
-      buildStartupScript,
-      watchHatching,
-      configValues,
+  if (UNSUPPORTED_REMOTE_HATCH_TARGETS.has(remote)) {
+    console.error(
+      `Error: \`vellum hatch --remote ${remote}\` is not a supported provisioning target yet.`,
     );
-    return;
+    console.error(
+      "No cloud resources were created. To self-host on AWS/GCP, SSH into the VM and run `vellum hatch` or `vellum hatch --remote docker` there.",
+    );
+    process.exit(1);
   }
 
-  if (remote === "aws") {
-    await hatchAws(species, detached, name, configValues);
+  if (remote === "local") {
+    await hatchLocal(species, name, watch, keepAlive, configValues);
     return;
   }
 
   if (remote === "docker") {
-    await hatchDocker(species, detached, name, watch, configValues);
+    await hatchDocker(species, detached, name, watch, configValues, {
+      sourcePath,
+      analyze,
+    });
     return;
   }
 

package/src/commands/ps.ts

@@ -2,11 +2,16 @@ import { join } from "path";
 
 import {
   findAssistantByName,
+  formatAssistantLookupError,
+  formatAssistantReference,
   getActiveAssistant,
+  getAssistantDisplayName,
   getDaemonPidPath,
   loadAllAssistants,
+  lookupAssistantByIdentifier,
   type AssistantEntry,
 } from "../lib/assistant-config";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import { resolveEnvironmentSource } from "../lib/environments/resolve";
 import { loadGuardianToken } from "../lib/guardian-token";
 import {
@@ -52,8 +57,10 @@ function pad(s: string, w: number): string {
   return s + " ".repeat(Math.max(0, w - s.length));
 }
 
-function computeColWidths(rows: TableRow[]): ColWidths {
-  const headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" };
+function computeColWidths(
+  rows: TableRow[],
+  headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" },
+): ColWidths {
   const all = [headers, ...rows];
   return {
     name: Math.max(...all.map((r) => r.name.length)),
@@ -66,9 +73,11 @@ function formatRow(r: TableRow, colWidths: ColWidths): string {
   return `  ${pad(r.name, colWidths.name)}  ${pad(r.status, colWidths.status)}  ${r.info}`;
 }
 
-function printTable(rows: TableRow[]): void {
-  const colWidths = computeColWidths(rows);
-  const headers: TableRow = { name: "PROCESS", status: "STATUS", info: "INFO" };
+function printTable(
+  rows: TableRow[],
+  headers: TableRow = { name: "PROCESS", status: "STATUS", info: "INFO" },
+): void {
+  const colWidths = computeColWidths(rows, headers);
   console.log(formatRow(headers, colWidths));
   const sep = `  ${"-".repeat(colWidths.name)}  ${"-".repeat(colWidths.status)}  ${"-".repeat(colWidths.info)}`;
   console.log(sep);
@@ -377,7 +386,7 @@ async function getDockerProcesses(entry: AssistantEntry): Promise<TableRow[]> {
 async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
   const cloud = resolveCloud(entry);
 
-  console.log(`Processes for ${entry.assistantId} (${cloud}):\n`);
+  console.log(`Processes for ${formatAssistantReference(entry)} (${cloud}):\n`);
 
   if (cloud === "local") {
     const rows = await getLocalProcesses(entry);
@@ -473,6 +482,75 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
 
 // ── List all assistants (no arg) ────────────────────────────────
 
+type AssistantHealth = {
+  status: string;
+  detail: string | null;
+  version?: string;
+};
+
+async function getAssistantListHealth(
+  entry: AssistantEntry,
+): Promise<AssistantHealth> {
+  const resources = entry.resources;
+  if (entry.cloud === "local" && resources) {
+    // TODO(ATL-306): Remove readPidFile/getDaemonPidPath in favor of
+    // fetching daemon PIDs via the health API (Gateway Security Migration).
+    const pid = readPidFile(getDaemonPidPath(resources));
+    const alive = pid !== null && isProcessAlive(pid);
+    if (!alive) {
+      return { status: "sleeping", detail: null };
+    }
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    return checkHealth(entry.localUrl ?? entry.runtimeUrl, token);
+  }
+
+  if (entry.cloud === "docker") {
+    const res = dockerResourceNames(entry.assistantId);
+    const state = await getDockerContainerState(res.assistantContainer);
+    if (!state || state !== "running") {
+      return { status: "sleeping", detail: null };
+    }
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    return checkHealth(entry.localUrl ?? entry.runtimeUrl, token);
+  }
+
+  if (entry.cloud === "apple-container") {
+    // Apple containers are managed by the macOS app. Probe the gateway
+    // (runtimeUrl is always written to the lockfile during hatch).
+    const token = loadGuardianToken(entry.assistantId)?.accessToken;
+    return entry.runtimeUrl
+      ? checkHealth(entry.runtimeUrl, token)
+      : { status: "unknown", detail: "no runtime URL" };
+  }
+
+  if (entry.cloud === "vellum") {
+    return checkManagedHealth(entry.runtimeUrl, entry.assistantId);
+  }
+
+  const token = loadGuardianToken(entry.assistantId)?.accessToken;
+  return checkHealth(entry.localUrl ?? entry.runtimeUrl, token);
+}
+
+function formatAssistantListRow(
+  entry: AssistantEntry,
+  activeAssistantId: string | null,
+  health: AssistantHealth,
+): TableRow {
+  const infoParts: string[] = [];
+  infoParts.push(`id: ${entry.assistantId}`);
+  if (entry.runtimeUrl) infoParts.push(entry.runtimeUrl);
+  if (entry.cloud) infoParts.push(`cloud: ${entry.cloud}`);
+  if (entry.species) infoParts.push(`species: ${entry.species}`);
+  if (health.detail) infoParts.push(health.detail);
+
+  const prefix = entry.assistantId === activeAssistantId ? "* " : "  ";
+  return {
+    name: prefix + getAssistantDisplayName(entry),
+    status: withStatusEmoji(health.status),
+    info: infoParts.join(" | "),
+  };
+}
+
 export async function listAllAssistants(verbose: boolean): Promise<void> {
   const { name: envName, source: envSource } = resolveEnvironmentSource();
   const sourceLabels: Record<typeof envSource, string> = {
@@ -519,6 +597,9 @@ export async function listAllAssistants(verbose: boolean): Promise<void> {
 
   const assistants = loadAllAssistants();
   const activeId = getActiveAssistant();
+  const activeAssistantId = activeId
+    ? (findAssistantByName(activeId)?.assistantId ?? activeId)
+    : null;
 
   if (assistants.length === 0) {
     console.log("No assistants found.");
@@ -540,97 +621,17 @@ export async function listAllAssistants(verbose: boolean): Promise<void> {
     return;
   }
 
-  const rows: TableRow[] = assistants.map((a) => {
-    const infoParts: string[] = [];
-    if (a.runtimeUrl) infoParts.push(a.runtimeUrl);
-    if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
-    if (a.species) infoParts.push(`species: ${a.species}`);
-    const prefix = a.assistantId === activeId ? "* " : "  ";
-
-    return {
-      name: prefix + a.assistantId,
-      status: withStatusEmoji("checking..."),
-      info: infoParts.join(" | "),
-    };
-  });
-
-  const colWidths = computeColWidths(rows);
-
-  const headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" };
-  console.log(formatRow(headers, colWidths));
-  const sep = `  ${"-".repeat(colWidths.name)}  ${"-".repeat(colWidths.status)}  ${"-".repeat(colWidths.info)}`;
-  console.log(sep);
-  for (const row of rows) {
-    console.log(formatRow(row, colWidths));
-  }
-
-  const totalDataRows = rows.length;
-
-  await Promise.all(
-    assistants.map(async (a, rowIndex) => {
-      // For local assistants, check if the daemon process is alive before
-      // hitting the health endpoint. If the PID file is missing or the
-      // process isn't running, the assistant is sleeping — skip the
-      // network health check to avoid a misleading "unreachable" status.
-      let health: { status: string; detail: string | null; version?: string };
-      const resources = a.resources;
-      if (a.cloud === "local" && resources) {
-        // TODO(ATL-306): Remove readPidFile/getDaemonPidPath in favor of
-        // fetching daemon PIDs via the health API (Gateway Security Migration).
-        const pid = readPidFile(getDaemonPidPath(resources));
-        const alive = pid !== null && isProcessAlive(pid);
-        if (!alive) {
-          health = { status: "sleeping", detail: null };
-        } else {
-          const token = loadGuardianToken(a.assistantId)?.accessToken;
-          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
-        }
-      } else if (a.cloud === "docker") {
-        const res = dockerResourceNames(a.assistantId);
-        const state = await getDockerContainerState(res.assistantContainer);
-        if (!state || state !== "running") {
-          health = { status: "sleeping", detail: null };
-        } else {
-          const token = loadGuardianToken(a.assistantId)?.accessToken;
-          health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
-        }
-      } else if (a.cloud === "apple-container") {
-        // Apple containers are managed by the macOS app. Probe the gateway
-        // (runtimeUrl is always written to the lockfile during hatch).
-        const token = loadGuardianToken(a.assistantId)?.accessToken;
-        health = a.runtimeUrl
-          ? await checkHealth(a.runtimeUrl, token)
-          : { status: "unknown" as const, detail: "no runtime URL" };
-      } else if (a.cloud === "vellum") {
-        health = await checkManagedHealth(a.runtimeUrl, a.assistantId);
-      } else {
-        const token = loadGuardianToken(a.assistantId)?.accessToken;
-        health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
-      }
-
-      const infoParts: string[] = [];
-      if (a.runtimeUrl) infoParts.push(a.runtimeUrl);
-      if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
-      if (a.species) infoParts.push(`species: ${a.species}`);
-      if (health.detail) infoParts.push(health.detail);
-
-      const prefix = a.assistantId === activeId ? "* " : "  ";
-      const updatedRow: TableRow = {
-        name: prefix + a.assistantId,
-        status: withStatusEmoji(health.status),
-        info: infoParts.join(" | "),
-      };
-
-      const linesUp = totalDataRows - rowIndex;
-      process.stdout.write(
-        `\x1b[${linesUp}A` +
-          `\r\x1b[K` +
-          formatRow(updatedRow, colWidths) +
-          `\n` +
-          (linesUp > 1 ? `\x1b[${linesUp - 1}B` : ""),
-      );
-    }),
+  const rows = await Promise.all(
+    assistants.map(async (entry) =>
+      formatAssistantListRow(
+        entry,
+        activeAssistantId,
+        await getAssistantListHealth(entry),
+      ),
+    ),
   );
+
+  printTable(rows, { name: "NAME", status: "STATUS", info: "INFO" });
 }
 
 // ── Entry point ─────────────────────────────────────────────────
@@ -638,14 +639,16 @@ export async function listAllAssistants(verbose: boolean): Promise<void> {
 export async function ps(): Promise<void> {
   const args = process.argv.slice(3);
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum ps [<name>] [--verbose]");
+    console.log("Usage: vellum ps [<name-or-id>] [--verbose]");
     console.log("");
     console.log(
       "List all assistants, or show processes for a specific assistant.",
     );
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>       Show processes for the named assistant");
+    console.log(
+      "  <name-or-id> Show processes for the assistant display name or ID",
+    );
     console.log("");
     console.log("Options:");
     console.log(
@@ -655,19 +658,18 @@ export async function ps(): Promise<void> {
   }
 
   const verbose = args.includes("--verbose");
-  const positional = args.filter((a) => !a.startsWith("--"));
-  const assistantId = positional[0];
+  const assistantIdentifier = parseAssistantTargetArg(args);
 
-  if (!assistantId) {
+  if (!assistantIdentifier) {
     await listAllAssistants(verbose);
     return;
   }
 
-  const entry = findAssistantByName(assistantId);
-  if (!entry) {
-    console.error(`No assistant found with name '${assistantId}'.`);
+  const result = lookupAssistantByIdentifier(assistantIdentifier);
+  if (result.status !== "found") {
+    console.error(formatAssistantLookupError(assistantIdentifier, result));
     process.exit(1);
   }
 
-  await showAssistantProcesses(entry);
+  await showAssistantProcesses(result.entry);
 }

package/src/commands/setup.ts

@@ -1,5 +1,6 @@
 import { resolveAssistant } from "../lib/assistant-config.js";
 import {
+  leaseGuardianToken,
   loadGuardianToken,
   refreshGuardianToken,
   type GuardianTokenData,
@@ -41,6 +42,50 @@ function isGuardianAccessTokenUsable(
   return Number.isFinite(expiresAt) && expiresAt > Date.now();
 }
 
+async function resolveSetupBearerToken(
+  entry: NonNullable<ReturnType<typeof resolveAssistant>>,
+  gatewayUrl: string,
+): Promise<string | undefined> {
+  const guardianToken = loadGuardianToken(entry.assistantId);
+  if (isGuardianAccessTokenUsable(guardianToken)) {
+    return guardianToken.accessToken;
+  }
+
+  if (guardianToken) {
+    const refreshedToken = await refreshGuardianToken(
+      gatewayUrl,
+      entry.assistantId,
+    );
+    if (isGuardianAccessTokenUsable(refreshedToken)) {
+      return refreshedToken.accessToken;
+    }
+  }
+
+  const canLeaseGuardianToken =
+    entry.cloud === "local" || entry.cloud === "docker" || entry.localUrl;
+  if (canLeaseGuardianToken) {
+    try {
+      const bootstrapSecret =
+        typeof entry.guardianBootstrapSecret === "string"
+          ? entry.guardianBootstrapSecret
+          : undefined;
+      const leasedToken = await leaseGuardianToken(
+        gatewayUrl,
+        entry.assistantId,
+        bootstrapSecret,
+      );
+      if (isGuardianAccessTokenUsable(leasedToken)) {
+        return leasedToken.accessToken;
+      }
+    } catch {
+      // Fall through to any lockfile bearer token, or let the setup request
+      // surface the gateway's auth error below.
+    }
+  }
+
+  return entry.bearerToken;
+}
+
 export async function setup(): Promise<void> {
   const args = process.argv.slice(3);
 
@@ -85,18 +130,7 @@ export async function setup(): Promise<void> {
   }
 
   const gatewayUrl = entry.localUrl ?? entry.runtimeUrl;
-  let bearerToken: string | undefined;
-  const guardianToken = loadGuardianToken(entry.assistantId);
-  if (isGuardianAccessTokenUsable(guardianToken)) {
-    bearerToken = guardianToken.accessToken;
-  } else {
-    const refreshedToken = guardianToken
-      ? await refreshGuardianToken(gatewayUrl, entry.assistantId)
-      : null;
-    bearerToken = isGuardianAccessTokenUsable(refreshedToken)
-      ? refreshedToken.accessToken
-      : entry.bearerToken;
-  }
+  const bearerToken = await resolveSetupBearerToken(entry, gatewayUrl);
 
   console.log("Vellum Setup");
   console.log("============\n");