@vellumai/cli 0.8.2 → 0.8.4

package/src/commands/teleport.ts

@@ -877,7 +877,16 @@ export async function resolveOrHatchTarget(
   // Hatch a new assistant in the target environment
   if (targetEnv === "local") {
     const beforeIds = new Set(loadAllAssistants().map((e) => e.assistantId));
-    await hatchLocal("vellum", targetName ?? null, false, false, {});
+    await hatchLocal(
+      "vellum",
+      targetName ?? null,
+      false,
+      false,
+      {},
+      {
+        setupProviderCredentials: false,
+      },
+    );
     const entry = targetName
       ? findAssistantByName(targetName)
       : (loadAllAssistants().find((e) => !beforeIds.has(e.assistantId)) ??
@@ -892,7 +901,16 @@ export async function resolveOrHatchTarget(
 
   if (targetEnv === "docker") {
     const beforeIds = new Set(loadAllAssistants().map((e) => e.assistantId));
-    await hatchDocker("vellum", false, targetName ?? null, false, {});
+    await hatchDocker(
+      "vellum",
+      false,
+      targetName ?? null,
+      false,
+      {},
+      {
+        setupProviderCredentials: false,
+      },
+    );
     const entry = targetName
       ? findAssistantByName(targetName)
       : (loadAllAssistants().find((e) => !beforeIds.has(e.assistantId)) ??

package/src/commands/use.ts

@@ -1,19 +1,24 @@
 import {
-  findAssistantByName,
+  formatAssistantLookupError,
+  formatAssistantReference,
   getActiveAssistant,
+  lookupAssistantByIdentifier,
   setActiveAssistant,
 } from "../lib/assistant-config.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 
 export async function use(): Promise<void> {
   const args = process.argv.slice(3);
 
   if (args.includes("--help") || args.includes("-h")) {
-    console.log("Usage: vellum use [<name>]");
+    console.log("Usage: vellum use [<name-or-id>]");
     console.log("");
     console.log("Set the active assistant for commands.");
     console.log("");
     console.log("Arguments:");
-    console.log("  <name>    Name of the assistant to make active");
+    console.log(
+      "  <name-or-id>    Assistant display name or ID to make active",
+    );
     console.log("");
     console.log(
       "When called without a name, prints the current active assistant.",
@@ -21,24 +26,33 @@ export async function use(): Promise<void> {
     process.exit(0);
   }
 
-  const name = args.find((a) => !a.startsWith("-"));
+  const name = parseAssistantTargetArg(args);
 
   if (!name) {
     const active = getActiveAssistant();
     if (active) {
-      console.log(`Active assistant: ${active}`);
+      const result = lookupAssistantByIdentifier(active);
+      if (result.status === "found") {
+        console.log(
+          `Active assistant: ${formatAssistantReference(result.entry)}`,
+        );
+      } else {
+        console.log(`Active assistant: ${active} (not found in lockfile)`);
+      }
     } else {
       console.log("No active assistant set.");
     }
     return;
   }
 
-  const entry = findAssistantByName(name);
-  if (!entry) {
-    console.error(`No assistant found with name '${name}'.`);
+  const result = lookupAssistantByIdentifier(name);
+  if (result.status !== "found") {
+    console.error(formatAssistantLookupError(name, result));
     process.exit(1);
   }
 
-  setActiveAssistant(name);
-  console.log(`Active assistant set to '${name}'.`);
+  setActiveAssistant(result.entry.assistantId);
+  console.log(
+    `Active assistant set to ${formatAssistantReference(result.entry)}.`,
+  );
 }

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/__tests__/docker.test.ts

@@ -4,6 +4,8 @@ import {
   AVATAR_DEVICE_ENV_VAR,
   dockerResourceNames,
   resolveAvatarDevicePath,
+  resolveDockerHatchMode,
+  resolveDockerProviderCredentialSetupAction,
   type ServiceName,
 } from "../docker.js";
 import { buildServiceRunArgs } from "../statefulset.js";
@@ -103,6 +105,51 @@ describe("buildServiceRunArgs — assistant", () => {
   });
 });
 
+describe("resolveDockerProviderCredentialSetupAction", () => {
+  test("defers provider setup in detached mode", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "anthropic",
+        detached: true,
+      }),
+    ).toBe("defer");
+  });
+
+  test("reports missing guardian token only when a lease was expected", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "anthropic",
+        detached: false,
+      }),
+    ).toBe("missing-token");
+  });
+
+  test("configures provider setup when a guardian token is available", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "anthropic",
+        guardianAccessToken: "guardian-token",
+        detached: false,
+      }),
+    ).toBe("configure");
+  });
+
+  test("skips provider setup for internal hatches and detached keyless hatches", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: undefined,
+        detached: false,
+      }),
+    ).toBe("skip");
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: null,
+        detached: true,
+      }),
+    ).toBe("skip");
+  });
+});
+
 describe("buildServiceRunArgs — gateway", () => {
   const savedVelayBaseUrl = process.env.VELAY_BASE_URL;
 
@@ -171,3 +218,62 @@ describe("VELLUM_AVATAR_DEVICE passthrough", () => {
     );
   });
 });
+
+describe("resolveDockerHatchMode", () => {
+  test("defaults to pulling published images when no source flag is set", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: false,
+        buildFromSource: false,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: false, watcher: false, fellBackToPull: false });
+  });
+
+  test("--source <path> builds without enabling the file watcher", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: false,
+        buildFromSource: true,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: true, watcher: false, fellBackToPull: false });
+  });
+
+  test("--watch builds and enables the file watcher", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: true,
+        buildFromSource: false,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: true, watcher: true, fellBackToPull: false });
+  });
+
+  test("--watch + --source <path> still enables the watcher (watch wins)", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: true,
+        buildFromSource: true,
+        fullSourceTreeAvailable: true,
+      }),
+    ).toEqual({ build: true, watcher: true, fellBackToPull: false });
+  });
+
+  test("falls back to pull when source flag is set but source tree is missing", () => {
+    expect(
+      resolveDockerHatchMode({
+        watch: false,
+        buildFromSource: true,
+        fullSourceTreeAvailable: false,
+      }),
+    ).toEqual({ build: false, watcher: false, fellBackToPull: true });
+    expect(
+      resolveDockerHatchMode({
+        watch: true,
+        buildFromSource: false,
+        fullSourceTreeAvailable: false,
+      }),
+    ).toEqual({ build: false, watcher: false, fellBackToPull: true });
+  });
+});

package/src/lib/assistant-config.ts

@@ -89,6 +89,8 @@ export interface AssistantEntry {
   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. */
+  guardianBootstrapSecret?: string;
   /** Docker image metadata for rollback. Only present for docker topology entries. */
   containerInfo?: ContainerInfo;
   /** Docker image metadata from before the last upgrade. Enables rollback to the prior version. */
@@ -107,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;
@@ -307,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 {
@@ -444,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/config-utils.ts

@@ -32,6 +32,24 @@ export function buildNestedConfig(
   return config;
 }
 
+/**
+ * Ensure hatch always provides enough initial LLM config for the assistant to
+ * detect a fresh off-platform hatch and seed BYOK profiles.
+ */
+export function buildHatchConfigValues(
+  configValues: Record<string, string>,
+  provider: string | null | undefined,
+): Record<string, string> {
+  if (!provider || configValues["llm.default.provider"]) {
+    return configValues;
+  }
+
+  return {
+    ...configValues,
+    "llm.default.provider": provider,
+  };
+}
+
 /**
  * Write arbitrary key-value pairs to a temporary JSON file and return its
  * path. The caller passes this path to the daemon via the