@vellumai/cli 0.8.3 → 0.8.4

package/src/components/DefaultMainScreen.tsx

@@ -1,4 +1,3 @@
-import { spawn } from "child_process";
 import { basename } from "path";
 import {
   useCallback,
@@ -10,8 +9,6 @@ import {
 } from "react";
 import { Box, render as inkRender, Text, useInput, useStdout } from "ink";
 
-import { removeAssistantEntry } from "../lib/assistant-config";
-
 import { SPECIES_CONFIG, type Species } from "../lib/constants";
 import { checkHealth } from "../lib/health-check";
 import { appendHistory, loadHistory } from "../lib/input-history";
@@ -43,9 +40,27 @@ export const SLASH_COMMANDS = [
   "/help",
   "/q",
   "/quit",
-  "/retire",
 ];
 
+const HELP_COMMANDS = [
+  {
+    command: "/btw <question>",
+    description: "Ask a side question while the assistant is working",
+  },
+  {
+    command: "/quit, /exit, /q",
+    description: "Disconnect and exit",
+  },
+  {
+    command: "/clear",
+    description: "Clear the screen",
+  },
+  {
+    command: "/help, ?",
+    description: "Show this help",
+  },
+] as const;
+
 const SEND_TIMEOUT_MS = 5000;
 
 // ── Layout constants ──────────────────────────────────────
@@ -100,12 +115,11 @@ const MIN_FEED_ROWS = 3;
 // Feed item height estimation
 const TOOL_CALL_CHROME_LINES = 2; // header (┌) + footer (└)
 const MESSAGE_SPACING = 1;
-const HELP_DISPLAY_HEIGHT = 7;
+const HELP_DISPLAY_HEIGHT = HELP_COMMANDS.length + 1;
 
 interface ListMessagesResponse {
   messages: RuntimeMessage[];
   nextCursor?: string;
-  interfaces?: string[];
 }
 
 interface SendMessageResponse {
@@ -742,26 +756,12 @@ function HelpDisplay(): ReactElement {
   return (
     <Box flexDirection="column">
       <Text bold>Commands:</Text>
-      <Text>
-        {"  /btw <question>   "}
-        <Text dimColor>Ask a side question while the assistant is working</Text>
-      </Text>
-      <Text>
-        {"  /retire           "}
-        <Text dimColor>Retire the remote instance and exit</Text>
-      </Text>
-      <Text>
-        {"  /quit, /exit, /q  "}
-        <Text dimColor>Disconnect and exit</Text>
-      </Text>
-      <Text>
-        {"  /clear            "}
-        <Text dimColor>Clear the screen</Text>
-      </Text>
-      <Text>
-        {"  /help, ?          "}
-        <Text dimColor>Show this help</Text>
-      </Text>
+      {HELP_COMMANDS.map((entry) => (
+        <Text key={entry.command}>
+          {`  ${entry.command.padEnd(17)} `}
+          <Text dimColor>{entry.description}</Text>
+        </Text>
+      ))}
     </Box>
   );
 }
@@ -1391,8 +1391,6 @@ interface ChatAppProps {
   /** Pre-built auth headers (e.g. { Authorization: "Bearer ..." } for local,
    *  { "X-Session-Token": "...", "Vellum-Organization-Id": "..." } for platform). */
   auth?: Record<string, string>;
-  project?: string;
-  zone?: string;
   onExit: () => void;
   handleRef: (handle: ChatAppHandle) => void;
 }
@@ -1403,8 +1401,6 @@ function ChatApp({
   assistantName,
   species,
   auth,
-  project,
-  zone,
   onExit,
   handleRef,
 }: ChatAppProps): ReactElement {
@@ -1954,86 +1950,6 @@ function ChatApp({
         return;
       }
 
-      if (trimmed === "/retire") {
-        if (!project || !zone) {
-          h.showError(
-            "No instance info available. Connect to a hatched instance first.",
-          );
-          return;
-        }
-
-        const confirmIndex = await h.showSelection(`Retire ${assistantId}?`, [
-          "Yes, retire",
-          "Cancel",
-        ]);
-        if (confirmIndex !== 0) {
-          h.addStatus("Cancelled.");
-          return;
-        }
-
-        h.showSpinner(`Retiring instance ${assistantId}...`);
-
-        try {
-          const labelChild = spawn(
-            "gcloud",
-            [
-              "compute",
-              "instances",
-              "add-labels",
-              assistantId,
-              `--project=${project}`,
-              `--zone=${zone}`,
-              "--labels=retired-by=vel",
-            ],
-            { stdio: "pipe" },
-          );
-          await new Promise<void>((resolve) => {
-            labelChild.on("close", () => resolve());
-            labelChild.on("error", () => resolve());
-          });
-        } catch {
-          // Best-effort labeling before deletion
-        }
-
-        const child = spawn(
-          "gcloud",
-          [
-            "compute",
-            "instances",
-            "delete",
-            assistantId,
-            `--project=${project}`,
-            `--zone=${zone}`,
-            "--quiet",
-          ],
-          { stdio: "pipe" },
-        );
-
-        child.on("close", (code) => {
-          handleRef_.current?.hideSpinner();
-          if (code === 0) {
-            removeAssistantEntry(assistantId);
-            handleRef_.current?.addStatus(
-              `Removed ${assistantId} from lockfile.json`,
-            );
-          } else {
-            handleRef_.current?.showError(
-              `Failed to delete instance (exit code ${code})`,
-            );
-          }
-          cleanup();
-          process.exit(code === 0 ? 0 : 1);
-        });
-
-        child.on("error", (err) => {
-          handleRef_.current?.hideSpinner();
-          handleRef_.current?.showError(
-            `Failed to retire instance: ${err.message}`,
-          );
-        });
-        return;
-      }
-
       // If a connection attempt is already in progress, don't silently drop input
       if (connectingRef.current) {
         h.addStatus(
@@ -2218,7 +2134,7 @@ function ChatApp({
       // racing with SSE events that may arrive during the sendMessage await.
       h.showSpinner("Working...");
     },
-    [runtimeUrl, assistantId, auth, project, zone, cleanup, ensureConnected],
+    [runtimeUrl, assistantId, auth, cleanup, ensureConnected],
   );
 
   const handleSubmit = useCallback(
@@ -2530,8 +2446,6 @@ export function renderChatApp(
   onExit: () => void,
   options?: {
     auth?: Record<string, string>;
-    project?: string;
-    zone?: string;
     assistantName?: string;
   },
 ): ChatAppInstance {
@@ -2544,8 +2458,6 @@ export function renderChatApp(
       assistantName={options?.assistantName}
       species={species}
       auth={options?.auth}
-      project={options?.project}
-      zone={options?.zone}
       onExit={onExit}
       handleRef={(h) => {
         chatHandle = h;

package/src/lib/assistant-config.ts

@@ -109,6 +109,11 @@ export interface AssistantEntry {
   [key: string]: unknown;
 }
 
+export type AssistantLookupResult =
+  | { status: "found"; entry: AssistantEntry }
+  | { status: "not_found" }
+  | { status: "ambiguous"; matches: AssistantEntry[] };
+
 interface LockfileData {
   assistants?: Record<string, unknown>[];
   activeAssistant?: string;
@@ -309,8 +314,70 @@ export function loadLatestAssistant(): AssistantEntry | null {
 }
 
 export function findAssistantByName(name: string): AssistantEntry | null {
+  return readAssistants().find((entry) => entry.assistantId === name) ?? null;
+}
+
+export function getAssistantDisplayName(entry: AssistantEntry): string {
+  const primary = entry.name?.trim();
+  if (primary) return primary;
+
+  const legacy = entry.assistantName?.trim();
+  if (legacy) return legacy;
+
+  return entry.assistantId;
+}
+
+export function formatAssistantReference(entry: AssistantEntry): string {
+  const displayName = getAssistantDisplayName(entry);
+  return displayName === entry.assistantId
+    ? entry.assistantId
+    : `${displayName} (${entry.assistantId})`;
+}
+
+function getAssistantDisplayNameCandidates(entry: AssistantEntry): string[] {
+  return Array.from(
+    new Set(
+      [entry.name?.trim(), entry.assistantName?.trim()].filter(
+        (value): value is string => typeof value === "string" && value !== "",
+      ),
+    ),
+  );
+}
+
+export function lookupAssistantByIdentifier(
+  identifier: string,
+): AssistantLookupResult {
   const entries = readAssistants();
-  return entries.find((e) => e.assistantId === name) ?? null;
+  const exactId = entries.find((entry) => entry.assistantId === identifier);
+  if (exactId) {
+    return { status: "found", entry: exactId };
+  }
+
+  const displayMatches = entries.filter((entry) =>
+    getAssistantDisplayNameCandidates(entry).includes(identifier),
+  );
+  if (displayMatches.length === 1) {
+    return { status: "found", entry: displayMatches[0] };
+  }
+  if (displayMatches.length > 1) {
+    return { status: "ambiguous", matches: displayMatches };
+  }
+
+  return { status: "not_found" };
+}
+
+export function formatAssistantLookupError(
+  identifier: string,
+  result: AssistantLookupResult = lookupAssistantByIdentifier(identifier),
+): string {
+  if (result.status === "ambiguous") {
+    const matches = result.matches
+      .map((entry) => formatAssistantReference(entry))
+      .join(", ");
+    return `Multiple assistants match '${identifier}': ${matches}. Use the assistant ID to disambiguate.`;
+  }
+
+  return `No assistant found with name or ID '${identifier}'.`;
 }
 
 export function removeAssistantEntry(assistantId: string): void {
@@ -446,13 +513,25 @@ export function resolveAssistant(nameArg?: string): AssistantEntry | null {
  * 3. Sole lockfile entry (any cloud)
  */
 export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
-  const entry = resolveAssistant(nameArg);
-  if (entry) return entry;
-
   if (nameArg) {
-    console.error(`No assistant found with name '${nameArg}'.`);
+    const result = lookupAssistantByIdentifier(nameArg);
+    if (result.status === "found") return result.entry;
+    console.error(formatAssistantLookupError(nameArg, result));
   } else {
+    const active = getActiveAssistant();
+    if (active) {
+      const result = lookupAssistantByIdentifier(active);
+      if (result.status === "found") return result.entry;
+      if (result.status === "ambiguous") {
+        console.error(formatAssistantLookupError(active, result));
+        process.exit(1);
+      }
+      // Active assistant no longer exists in lockfile — fall through.
+    }
+
     const all = readAssistants();
+    if (all.length === 1) return all[0];
+
     if (all.length === 0) {
       console.error("No assistant found. Run 'vellum hatch' first.");
     } else {

package/src/lib/assistant-target-args.ts

@@ -0,0 +1,21 @@
+export function parseAssistantTargetArg(
+  args: string[],
+  flagsWithValues: readonly string[] = [],
+): string | undefined {
+  const flagsWithValuesSet = new Set(flagsWithValues);
+  const parts: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (flagsWithValuesSet.has(arg)) {
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      continue;
+    }
+    parts.push(arg);
+  }
+
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}

package/src/lib/docker.ts

@@ -21,7 +21,15 @@ import { leaseGuardianToken } from "./guardian-token";
 import { logHatchNextSteps } from "./hatch-next-steps.js";
 import { isVellumProcess, stopProcess } from "./process";
 import { generateInstanceName } from "./random-name";
-import { resolveImageRefs } from "./platform-releases.js";
+import {
+  HOST_IMAGE_LOADER_URL,
+  isLocalBuildRef,
+  loadImageViaHost,
+} from "./host-image-loader.js";
+import {
+  fetchLatestStableVersion,
+  resolveImageRefs,
+} from "./platform-releases.js";
 import {
   configureHatchProviderApiKey,
   formatProviderName,
@@ -1059,8 +1067,23 @@ export async function hatchDocker(
         imageSource = "env override";
         log("Using image overrides from environment variables");
       } else {
-        const version = cliPkg.version;
-        const versionTag = version ? `v${version}` : "latest";
+        // Resolve image refs from a remote source that may have dev/local
+        // builds. If resolution is unavailable, fall back to the CLI's own
+        // version so a default tag can still be resolved.
+        log("🔍 Fetching latest stable release...");
+        const latestVersion = await fetchLatestStableVersion();
+        let versionTag: string;
+        if (latestVersion) {
+          versionTag = latestVersion.startsWith("v")
+            ? latestVersion
+            : `v${latestVersion}`;
+        } else {
+          const fallback = cliPkg.version;
+          versionTag = fallback ? `v${fallback}` : "latest";
+          log(
+            `⚠️  Platform releases unavailable; falling back to CLI version ${versionTag}`,
+          );
+        }
         log("🔍 Resolving image references...");
         const resolved = await resolveImageRefs(versionTag, log);
         imageTags.assistant = resolved.imageTags.assistant;
@@ -1078,11 +1101,25 @@ export async function hatchDocker(
       log(`     credential-executor:  ${imageTags["credential-executor"]}`);
       log("");
 
-      log("📦 Pulling Docker images...");
-      await exec("docker", ["pull", imageTags.assistant]);
-      await exec("docker", ["pull", imageTags.gateway]);
-      await exec("docker", ["pull", imageTags["credential-executor"]]);
-      log("✅ Docker images pulled");
+      // Per-ref branching: local-build refs need the image-loader; external
+      // registry refs get a normal `docker pull`. The two transports compose
+      // cleanly — a release can mix different sources for different images.
+      log("📦 Acquiring Docker images...");
+      for (const service of [
+        "assistant",
+        "gateway",
+        "credential-executor",
+      ] as const) {
+        const ref = imageTags[service];
+        if (isLocalBuildRef(ref)) {
+          log(`   ↪ loading ${ref} via host image-loader`);
+          await loadImageViaHost(HOST_IMAGE_LOADER_URL, ref, log);
+        } else {
+          log(`   ↪ pulling ${ref}`);
+          await exec("docker", ["pull", ref]);
+        }
+      }
+      log("✅ Docker images acquired");
     }
 
     const res = dockerResourceNames(instanceName);

package/src/lib/host-image-loader.ts

@@ -0,0 +1,138 @@
+/**
+ * Client for the host-side image-loader endpoint. Used to acquire image refs
+ * that aren't pullable from any external registry.
+ *
+ * The endpoint URL is a well-known convention — port 5500 on 127.0.0.1.
+ * The CLI calls in whenever it sees a ref that starts with `vellum-local/`,
+ * which are image refs that only exist in a local docker daemon and can't be
+ * `docker pull`'d from any external registry.
+ *
+ * The endpoint contract is intentionally minimal — POST a ref as JSON, get
+ * back a 200 once the image is in the host docker daemon, or a non-2xx
+ * with a descriptive error message. The client doesn't know (or care) what
+ * transport the server uses to put the image there.
+ */
+
+/**
+ * Well-known URL of the host-side image-loader server.
+ */
+export const HOST_IMAGE_LOADER_URL = "http://127.0.0.1:5500/v1/images/load";
+
+/**
+ * Prefix for image refs that only exist in a local docker daemon.
+ * These cannot be `docker pull`'d from any external registry; the CLI must
+ * route them through the host image-loader instead.
+ */
+const LOCAL_BUILD_REF_PREFIX = "vellum-local/";
+
+/** Whether `ref` points at a local-build image that requires the host loader. */
+export function isLocalBuildRef(ref: string): boolean {
+  return ref.startsWith(LOCAL_BUILD_REF_PREFIX);
+}
+
+/** Default timeout for image-load requests. Large `docker save | docker load`
+ * pipelines for full assistant images can run for a minute or two on cold
+ * caches, so we give plenty of headroom. */
+const LOAD_TIMEOUT_MS = 120_000;
+
+export interface HostImageLoaderResponse {
+  loaded?: boolean;
+  ref?: string;
+  error?: string;
+}
+
+export class HostImageLoaderError extends Error {
+  readonly url: string;
+  readonly ref: string;
+  readonly status?: number;
+
+  constructor(message: string, url: string, ref: string, status?: number) {
+    super(message);
+    this.name = "HostImageLoaderError";
+    this.url = url;
+    this.ref = ref;
+    this.status = status;
+  }
+}
+
+function isConnectionRefused(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { cause?: { code?: string }; code?: string };
+  return e.cause?.code === "ECONNREFUSED" || e.code === "ECONNREFUSED";
+}
+
+/**
+ * Ask the host-side loader to acquire `ref` into the host docker daemon.
+ *
+ * Resolves when the server returns 200; throws a {@link HostImageLoaderError}
+ * with a user-actionable message on any failure (network, timeout, non-2xx).
+ *
+ * The `log` callback receives one-line status updates; pass the same logger
+ * the surrounding command uses.
+ */
+/** Minimal fetch signature accepted for test injection. */
+export type FetchLike = (
+  input: string | URL,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+  },
+) => Promise<Response>;
+
+export async function loadImageViaHost(
+  url: string,
+  ref: string,
+  log: (msg: string) => void,
+  options: { timeoutMs?: number; fetchImpl?: FetchLike } = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? LOAD_TIMEOUT_MS;
+  const fetchImpl: FetchLike =
+    options.fetchImpl ?? (fetch as unknown as FetchLike);
+
+  log(`   ↪ ${ref}`);
+
+  let response: Response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ ref }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    if (isConnectionRefused(err)) {
+      throw new HostImageLoaderError(
+        `Could not reach image-loader at ${url}. The ref \`${ref}\` is a ` +
+          `local-build image that requires the loader. Is the loader running? ` +
+          `Start it, or set VELLUM_ASSISTANT_IMAGE / VELLUM_GATEWAY_IMAGE / ` +
+          `VELLUM_CREDENTIAL_EXECUTOR_IMAGE to bypass image resolution.`,
+        url,
+        ref,
+      );
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new HostImageLoaderError(
+      `Image-loader request for ${ref} failed: ${message}`,
+      url,
+      ref,
+    );
+  }
+
+  if (!response.ok) {
+    let body: HostImageLoaderResponse | null = null;
+    try {
+      body = (await response.json()) as HostImageLoaderResponse;
+    } catch {
+      // Server returned non-JSON; fall through with status-only error.
+    }
+    const detail = body?.error ? `: ${body.error}` : "";
+    throw new HostImageLoaderError(
+      `Image-loader returned HTTP ${response.status} for ${ref}${detail}`,
+      url,
+      ref,
+      response.status,
+    );
+  }
+}

package/src/lib/platform-releases.ts

@@ -46,7 +46,10 @@ export async function resolveImageRefs(
   const platformRefs = await fetchPlatformImageRefs(version, log);
   if (platformRefs) {
     log?.("Resolved image refs from platform API");
-    return { imageTags: platformRefs, source: "platform" };
+    return {
+      imageTags: platformRefs.imageTags,
+      source: "platform",
+    };
   }
 
   log?.("Falling back to DockerHub tags");
@@ -68,7 +71,9 @@ export async function resolveImageRefs(
 async function fetchPlatformImageRefs(
   version: string,
   log?: (msg: string) => void,
-): Promise<Record<ServiceName, string> | null> {
+): Promise<{
+  imageTags: Record<ServiceName, string>;
+} | null> {
   try {
     const platformUrl = getPlatformUrl();
     const url = `${platformUrl}/v1/releases/?stable=true`;
@@ -123,9 +128,11 @@ async function fetchPlatformImageRefs(
     }
 
     return {
-      assistant: assistantImage,
-      "credential-executor": credentialExecutorImage,
-      gateway: gatewayImage,
+      imageTags: {
+        assistant: assistantImage,
+        "credential-executor": credentialExecutorImage,
+        gateway: gatewayImage,
+      },
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);