@vellumai/cli 0.7.0 → 0.7.1

package/src/lib/assistant-client.ts

@@ -13,9 +13,7 @@
  */
 
 import {
-  findAssistantByName,
-  getActiveAssistant,
-  loadLatestAssistant,
+  resolveAssistant,
 } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import { loadGuardianToken } from "./guardian-token.js";
@@ -58,27 +56,13 @@ export class AssistantClient {
    * @throws If no matching assistant is found.
    */
   constructor(opts?: AssistantClientOpts) {
-    const nameOrId = opts?.assistantId;
-    let entry = nameOrId ? findAssistantByName(nameOrId) : null;
-
-    if (nameOrId && !entry) {
-      throw new Error(`No assistant found with name '${nameOrId}'.`);
-    }
-
-    if (!entry) {
-      const active = getActiveAssistant();
-      if (active) {
-        entry = findAssistantByName(active);
-      }
-    }
-
-    if (!entry) {
-      entry = loadLatestAssistant();
-    }
+    const entry = resolveAssistant(opts?.assistantId);
 
     if (!entry) {
       throw new Error(
-        "No assistant found. Hatch one first with 'vellum hatch'.",
+        opts?.assistantId
+          ? `No assistant found with name '${opts.assistantId}'.`
+          : "No assistant found. Hatch one first with 'vellum hatch'.",
       );
     }
 

package/src/lib/assistant-config.ts

@@ -343,19 +343,17 @@ export function setActiveAssistant(assistantId: string): void {
 }
 
 /**
- * Resolve which assistant to target for a command. Priority:
+ * Best-effort resolution of the target assistant. Returns null when no
+ * match is found — callers decide how to handle the absence.
+ *
+ * Priority:
  * 1. Explicit name argument
  * 2. Active assistant set via `vellum use`
- * 3. Sole local assistant (when exactly one exists)
+ * 3. Sole lockfile entry (any cloud)
  */
-export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
+export function resolveAssistant(nameArg?: string): AssistantEntry | null {
   if (nameArg) {
-    const entry = findAssistantByName(nameArg);
-    if (!entry) {
-      console.error(`No assistant found with name '${nameArg}'.`);
-      process.exit(1);
-    }
-    return entry;
+    return findAssistantByName(nameArg);
   }
 
   const active = getActiveAssistant();
@@ -366,15 +364,35 @@ export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
   }
 
   const all = readAssistants();
-  const locals = all.filter((e) => e.cloud === "local");
-  if (locals.length === 1) return locals[0];
+  if (all.length === 1) return all[0];
+
+  return null;
+}
 
-  if (locals.length === 0) {
-    console.error("No local assistant found. Run 'vellum hatch local' first.");
+/**
+ * Resolve which assistant to target for a command, exiting the process
+ * with a user-facing error when resolution fails.
+ *
+ * Priority:
+ * 1. Explicit name argument
+ * 2. Active assistant set via `vellum use`
+ * 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}'.`);
   } else {
-    console.error(
-      `Multiple assistants found. Set an active assistant with 'vellum use <name>'.`,
-    );
+    const all = readAssistants();
+    if (all.length === 0) {
+      console.error("No assistant found. Run 'vellum hatch' first.");
+    } else {
+      console.error(
+        `Multiple assistants found. Set an active assistant with 'vellum use <name>'.`,
+      );
+    }
   }
   process.exit(1);
 }

package/src/lib/cli-error.ts

@@ -9,6 +9,7 @@
 
 /** Known error categories emitted by CLI commands. */
 export type CliErrorCategory =
+  | "CLI_UPDATE_FAILED"
   | "DOCKER_NOT_RUNNING"
   | "IMAGE_PULL_FAILED"
   | "MISSING_VERSION"

package/src/lib/client-identity.ts

@@ -2,7 +2,7 @@
  * Stable per-install client identity for the CLI.
  *
  * Generates a UUID on first use and persists it to
- * `~/.config/vellum/client-id` so the daemon's ClientRegistry can
+ * `~/.config/vellum/client-id` so the daemon's event hub can
  * track this terminal across SSE reconnects and CLI restarts.
  */
 

package/src/lib/config-utils.ts

@@ -2,11 +2,6 @@ import { writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 
-const ANTHROPIC_PROVIDER = "anthropic";
-const ANTHROPIC_DEFAULT_MODEL = "claude-opus-4-7";
-const MAIN_AGENT_OPUS_MODEL = "claude-opus-4-7";
-const MAIN_AGENT_OPUS_MAX_TOKENS = 32000;
-
 /**
  * Convert flat dot-notation key=value pairs into a nested config object.
  *
@@ -37,20 +32,6 @@ export function buildNestedConfig(
   return config;
 }
 
-/**
- * Build the first-boot workspace config overlay passed to the assistant during
- * hatch. Anthropic onboarding sets `llm.default.model` to Sonnet so background
- * fallback work stays cheaper, while the main conversation thread should remain
- * on Opus via the same call-site override seeded by workspace migration 050.
- */
-export function buildInitialConfig(
-  configValues: Record<string, string>,
-): Record<string, unknown> {
-  const config = buildNestedConfig(configValues);
-  seedAnthropicMainAgentCallSite(config);
-  return config;
-}
-
 /**
  * Write arbitrary key-value pairs to a temporary JSON file and return its
  * path. The caller passes this path to the daemon via the
@@ -68,7 +49,7 @@ export function writeInitialConfig(
 ): string | undefined {
   if (Object.keys(configValues).length === 0) return undefined;
 
-  const config = buildInitialConfig(configValues);
+  const config = buildNestedConfig(configValues);
   const tempPath = join(
     tmpdir(),
     `vellum-default-workspace-config-${process.pid}-${Date.now()}.json`,
@@ -76,80 +57,3 @@ export function writeInitialConfig(
   writeFileSync(tempPath, JSON.stringify(config, null, 2) + "\n");
   return tempPath;
 }
-
-function seedAnthropicMainAgentCallSite(config: Record<string, unknown>): void {
-  const llm = ensureObject(config, "llm");
-
-  const existingCallSites = readObject(llm.callSites);
-  if (existingCallSites !== null && "mainAgent" in existingCallSites) return;
-
-  const { provider, model } = resolveInitialMainAgentBaseSelection(llm);
-  if (provider !== ANTHROPIC_PROVIDER) return;
-
-  if (
-    model !== undefined &&
-    model !== ANTHROPIC_DEFAULT_MODEL &&
-    model !== MAIN_AGENT_OPUS_MODEL
-  ) {
-    return;
-  }
-
-  const callSites = ensureObject(llm, "callSites");
-
-  callSites.mainAgent = {
-    model: MAIN_AGENT_OPUS_MODEL,
-    maxTokens: MAIN_AGENT_OPUS_MAX_TOKENS,
-  };
-}
-
-function resolveInitialMainAgentBaseSelection(llm: Record<string, unknown>): {
-  provider: string;
-  model?: string;
-} {
-  const defaultBlock = readObject(llm.default);
-  let provider = readString(defaultBlock?.provider) ?? ANTHROPIC_PROVIDER;
-  let model = readString(defaultBlock?.model);
-
-  const profiles = readObject(llm.profiles);
-  const activeProfileName = readString(llm.activeProfile);
-  const activeProfile =
-    profiles !== null && activeProfileName !== undefined
-      ? readObject(profiles[activeProfileName])
-      : null;
-
-  if (activeProfile !== null) {
-    provider = readString(activeProfile.provider) ?? provider;
-    model = readString(activeProfile.model) ?? model;
-  }
-
-  return model === undefined ? { provider } : { provider, model };
-}
-
-function ensureObject(
-  parent: Record<string, unknown>,
-  key: string,
-): Record<string, unknown> {
-  const existing = parent[key];
-  if (
-    existing != null &&
-    typeof existing === "object" &&
-    !Array.isArray(existing)
-  ) {
-    return existing as Record<string, unknown>;
-  }
-
-  const next: Record<string, unknown> = {};
-  parent[key] = next;
-  return next;
-}
-
-function readObject(value: unknown): Record<string, unknown> | null {
-  if (value == null || typeof value !== "object" || Array.isArray(value)) {
-    return null;
-  }
-  return value as Record<string, unknown>;
-}
-
-function readString(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}

package/src/lib/docker.ts

@@ -662,6 +662,8 @@ export function serviceDockerRunArgs(opts: {
         "-e",
         "IS_CONTAINERIZED=true",
         "-e",
+        "DEBUG_STDOUT_LOGS=1",
+        "-e",
         `VELLUM_ASSISTANT_NAME=${instanceName}`,
         "-e",
         "VELLUM_CLOUD=docker",
@@ -757,8 +759,6 @@ export function serviceDockerRunArgs(opts: {
       "-e",
       `RUNTIME_HTTP_PORT=${ASSISTANT_INTERNAL_PORT}`,
       "-e",
-      "RUNTIME_PROXY_ENABLED=true",
-      "-e",
       "CES_CREDENTIAL_URL=http://localhost:8090",
       "-e",
       "GATEWAY_IPC_SOCKET_DIR=/run/gateway-ipc",

package/src/lib/job-polling.ts

@@ -107,7 +107,7 @@ function isTransientPollError(err: unknown): boolean {
  *
  * Transient errors raised by `poll()` (5xx, network hiccups, rate-limits) are
  * retried up to `maxTransientErrors` times before the last error propagates,
- * matching the pre-rewrite `platformPollExportStatus` loop's behavior so a
+ * matching the pre-rewrite migration-export polling loop's behavior so a
  * single flaky poll doesn't abort a migration that may still be running.
  */
 export async function pollJobUntilDone(

package/src/lib/local-runtime-client.ts

@@ -1,7 +1,10 @@
+import type { AssistantEntry } from "./assistant-config.js";
 import {
+  authHeaders,
   parseUnifiedJobStatus,
   type UnifiedJobStatus,
 } from "./platform-client.js";
+import { resolveRuntimeMigrationUrl } from "./runtime-url.js";
 
 /**
  * Thrown when the local runtime returns 409 for an export/import request
@@ -34,6 +37,29 @@ function bearerHeaders(token: string): Record<string, string> {
   };
 }
 
+/**
+ * Build the auth + content headers for a runtime migration request.
+ *
+ * - For `cloud === "vellum"` we go through the platform's wildcard runtime
+ *   proxy, which authenticates user-session / vak_ tokens via DRF's default
+ *   authentication classes — `authHeaders()` produces the right combination
+ *   (`X-Session-Token` + `Vellum-Organization-Id`, or `Authorization: Bearer
+ *   vak_...`).
+ * - For local/docker the runtime endpoint expects a guardian-token bearer.
+ */
+async function migrationRequestHeaders(
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl">,
+  token: string,
+): Promise<Record<string, string>> {
+  if (entry.cloud === "vellum") {
+    return {
+      ...(await authHeaders(token, entry.runtimeUrl)),
+      Accept: "application/json",
+    };
+  }
+  return bearerHeaders(token);
+}
+
 interface Raw409Body {
   detail?: string;
   // The runtime's current 409 contract nests the payload under `error`:
@@ -69,13 +95,21 @@ async function throwIfInProgress(
 }
 
 /**
- * Kick off an async export-to-GCS job on the local runtime.
- * POSTs to `{runtimeUrl}/v1/migrations/export-to-gcs` and returns the
- * 202-accepted job_id. On 409 (another export in flight) throws
- * {@link MigrationInProgressError} with the existing job_id.
+ * Kick off an async export-to-GCS job on the assistant's runtime.
+ *
+ * For local/docker assistants this POSTs to
+ * `{runtimeUrl}/v1/migrations/export-to-gcs` with guardian-token bearer
+ * auth. For platform-managed (cloud="vellum") assistants the URL is rewritten
+ * to the wildcard-runtime-proxy shape
+ * `{platformUrl}/v1/assistants/<assistantId>/migrations/export-to-gcs` and
+ * authenticated via the platform-token header set the platform's DRF auth
+ * accepts (session / vak_).
+ *
+ * Returns the 202-accepted `job_id`. On 409 (another export in flight)
+ * throws {@link MigrationInProgressError} with the existing job_id.
  */
 export async function localRuntimeExportToGcs(
-  runtimeUrl: string,
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
   token: string,
   params: { uploadUrl: string; description?: string },
 ): Promise<{ jobId: string }> {
@@ -84,11 +118,14 @@ export async function localRuntimeExportToGcs(
     body.description = params.description;
   }
 
-  const response = await fetch(`${runtimeUrl}/v1/migrations/export-to-gcs`, {
-    method: "POST",
-    headers: bearerHeaders(token),
-    body: JSON.stringify(body),
-  });
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, "export-to-gcs"),
+    {
+      method: "POST",
+      headers: await migrationRequestHeaders(entry, token),
+      body: JSON.stringify(body),
+    },
+  );
 
   await throwIfInProgress(response, "export_in_progress");
 
@@ -110,20 +147,29 @@ export async function localRuntimeExportToGcs(
 }
 
 /**
- * Kick off an async import-from-GCS job on the local runtime.
- * POSTs to `{runtimeUrl}/v1/migrations/import-from-gcs` with a signed
- * download URL. On 409 throws {@link MigrationInProgressError}.
+ * Kick off an async import-from-GCS job on the assistant's runtime.
+ *
+ * For local/docker assistants this POSTs to
+ * `{runtimeUrl}/v1/migrations/import-from-gcs` with guardian-token bearer
+ * auth. For platform-managed (cloud="vellum") assistants the URL is rewritten
+ * to the wildcard-runtime-proxy shape
+ * `{platformUrl}/v1/assistants/<assistantId>/migrations/import-from-gcs` and
+ * authenticated via the platform token. On 409 throws
+ * {@link MigrationInProgressError}.
  */
 export async function localRuntimeImportFromGcs(
-  runtimeUrl: string,
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
   token: string,
   params: { bundleUrl: string },
 ): Promise<{ jobId: string }> {
-  const response = await fetch(`${runtimeUrl}/v1/migrations/import-from-gcs`, {
-    method: "POST",
-    headers: bearerHeaders(token),
-    body: JSON.stringify({ bundle_url: params.bundleUrl }),
-  });
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, "import-from-gcs"),
+    {
+      method: "POST",
+      headers: await migrationRequestHeaders(entry, token),
+      body: JSON.stringify({ bundle_url: params.bundleUrl }),
+    },
+  );
 
   await throwIfInProgress(response, "import_in_progress");
 
@@ -145,21 +191,28 @@ export async function localRuntimeImportFromGcs(
 }
 
 /**
- * Poll the local runtime's unified job-status endpoint.
- * GETs `{runtimeUrl}/v1/migrations/jobs/{jobId}` and parses into
- * {@link UnifiedJobStatus}.
+ * Poll the runtime's unified job-status endpoint.
+ *
+ * For local/docker assistants this GETs
+ * `{runtimeUrl}/v1/migrations/jobs/{jobId}` directly (guardian-token
+ * bearer). For platform-managed assistants it routes through the wildcard
+ * runtime proxy at
+ * `{platformUrl}/v1/assistants/<assistantId>/migrations/jobs/{jobId}` with
+ * platform-token auth — important: the platform's dedicated
+ * `/v1/migrations/jobs/{id}/` endpoint queries platform-side ImportJob
+ * records and would 404 on runtime-created job IDs.
  */
 export async function localRuntimePollJobStatus(
-  runtimeUrl: string,
+  entry: Pick<AssistantEntry, "cloud" | "runtimeUrl" | "assistantId">,
   token: string,
   jobId: string,
 ): Promise<UnifiedJobStatus> {
-  const response = await fetch(`${runtimeUrl}/v1/migrations/jobs/${jobId}`, {
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: "application/json",
+  const response = await fetch(
+    resolveRuntimeMigrationUrl(entry, `jobs/${jobId}`),
+    {
+      headers: await migrationRequestHeaders(entry, token),
     },
-  });
+  );
 
   if (response.status === 404) {
     throw new Error("Migration job not found");

package/src/lib/local.ts

@@ -8,7 +8,7 @@ import {
   writeFileSync,
 } from "fs";
 import { createRequire } from "module";
-import { homedir, hostname, networkInterfaces, platform, tmpdir } from "os";
+import { homedir, networkInterfaces, platform, tmpdir } from "os";
 import { dirname, join } from "path";
 
 import {
@@ -392,7 +392,6 @@ async function startDaemonFromSource(
       : {}),
   };
   if (resources) {
-    env.BASE_DATA_DIR = resources.instanceDir;
     env.VELLUM_WORKSPACE_DIR = join(
       resources.instanceDir,
       ".vellum",
@@ -403,6 +402,11 @@ async function startDaemonFromSource(
       ".vellum",
       "protected",
     );
+    env.CREDENTIAL_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -523,7 +527,6 @@ async function startDaemonWatchFromSource(
       : {}),
   };
   if (resources) {
-    env.BASE_DATA_DIR = resources.instanceDir;
     env.VELLUM_WORKSPACE_DIR = join(
       resources.instanceDir,
       ".vellum",
@@ -534,6 +537,11 @@ async function startDaemonWatchFromSource(
       ".vellum",
       "protected",
     );
+    env.CREDENTIAL_SECURITY_DIR = join(
+      resources.instanceDir,
+      ".vellum",
+      "protected",
+    );
     env.RUNTIME_HTTP_PORT = String(resources.daemonPort);
     env.GATEWAY_PORT = String(resources.gatewayPort);
     env.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -675,51 +683,18 @@ export async function discoverPublicUrl(
     return `http://${cloudIp}:${effectivePort}`;
   }
 
-  // Log the local address source only when we actually use it.
-  if (localResult.source === "hostname") {
-    console.log(`   Discovered macOS local hostname: ${localResult.label}`);
-  } else if (localResult.source === "lan") {
-    console.log(`   Discovered LAN IP: ${localResult.label}`);
-  }
-
   return localResult.url;
 }
 
 /**
- * Resolve a LAN-reachable URL without any async I/O. Returns the best local
- * address or falls back to localhost. Does not emit any logs — the caller
- * decides whether to log based on which result is actually used.
+ * Returns the localhost URL for the gateway on the given port.
  */
 function discoverLocalUrl(effectivePort: number): {
   url: string;
-  source: "hostname" | "lan" | "localhost";
-  label?: string;
+  source: "localhost";
 } {
-  // On macOS, prefer the .local hostname (Bonjour/mDNS) so other devices on
-  // the same network can reach the gateway by name.
-  if (platform() === "darwin") {
-    const localHostname = getMacLocalHostname();
-    if (localHostname) {
-      return {
-        url: `http://${localHostname}:${effectivePort}`,
-        source: "hostname",
-        label: localHostname,
-      };
-    }
-  }
-
-  const lanIp = getLocalLanIPv4();
-  if (lanIp) {
-    return {
-      url: `http://${lanIp}:${effectivePort}`,
-      source: "lan",
-      label: lanIp,
-    };
-  }
-
-  // Final fallback to localhost when no LAN address could be discovered.
   return {
-    url: `http://localhost:${effectivePort}`,
+    url: `http://127.0.0.1:${effectivePort}`,
     source: "localhost",
   };
 }
@@ -776,19 +751,6 @@ async function discoverCloudExternalIp(): Promise<string | undefined> {
   return gcpIp ?? awsIp;
 }
 
-/**
- * Returns the macOS Bonjour/mDNS `.local` hostname (e.g. "Vargass-Mac-Mini.local"),
- * or undefined if not running on macOS or the hostname cannot be determined.
- */
-export function getMacLocalHostname(): string | undefined {
-  const host = hostname();
-  if (!host) return undefined;
-  // macOS hostnames already end with .local when Bonjour is active
-  if (host.endsWith(".local")) return host;
-  // Otherwise, append .local — macOS resolves <ComputerName>.local via mDNS
-  return `${host}.local`;
-}
-
 /**
  * Returns the local IPv4 address most likely to be reachable from other
  * devices on the same LAN.
@@ -988,8 +950,8 @@ export async function startLocalDaemon(
       for (const key of [
         "ANTHROPIC_API_KEY",
         "APP_VERSION",
-        "BASE_DATA_DIR",
         "GATEWAY_SECURITY_DIR",
+        "CREDENTIAL_SECURITY_DIR",
         "VELLUM_ENVIRONMENT",
         "VELLUM_PLATFORM_URL",
         "QDRANT_HTTP_PORT",
@@ -1015,7 +977,6 @@ export async function startLocalDaemon(
       // When running a named instance, override env so the daemon resolves
       // all paths under the instance directory and listens on its own port.
       if (resources) {
-        daemonEnv.BASE_DATA_DIR = resources.instanceDir;
         daemonEnv.VELLUM_WORKSPACE_DIR = join(
           resources.instanceDir,
           ".vellum",
@@ -1026,6 +987,11 @@ export async function startLocalDaemon(
           ".vellum",
           "protected",
         );
+        daemonEnv.CREDENTIAL_SECURITY_DIR = join(
+          resources.instanceDir,
+          ".vellum",
+          "protected",
+        );
         daemonEnv.RUNTIME_HTTP_PORT = String(resources.daemonPort);
         daemonEnv.GATEWAY_PORT = String(resources.gatewayPort);
         daemonEnv.QDRANT_HTTP_PORT = String(resources.qdrantPort);
@@ -1165,7 +1131,7 @@ export async function startGateway(
 
   const publicUrl = await discoverPublicUrl(effectiveGatewayPort);
   if (publicUrl) {
-    console.log(`   Public URL: ${publicUrl}`);
+    console.log(`   HTTP URL: ${publicUrl}`);
   }
 
   console.log("🌐 Starting gateway...");
@@ -1179,7 +1145,6 @@ export async function startGateway(
     GATEWAY_PORT: String(effectiveGatewayPort),
     // Pass gateway operational settings via env vars so the CLI does not
     // need direct access to the workspace config file.
-    RUNTIME_PROXY_ENABLED: "true",
     RUNTIME_PROXY_REQUIRE_AUTH: "true",
     UNMAPPED_POLICY: "default",
     DEFAULT_ASSISTANT_ID: "self",
@@ -1197,7 +1162,6 @@ export async function startGateway(
     // assistant DB directly for guardian bootstrap.
     ...(resources
       ? {
-          BASE_DATA_DIR: resources.instanceDir,
           VELLUM_WORKSPACE_DIR: join(
             resources.instanceDir,
             ".vellum",
@@ -1208,6 +1172,11 @@ export async function startGateway(
             ".vellum",
             "protected",
           ),
+          CREDENTIAL_SECURITY_DIR: join(
+            resources.instanceDir,
+            ".vellum",
+            "protected",
+          ),
         }
       : {}),
   };
@@ -1215,7 +1184,7 @@ export async function startGateway(
   applyIpcSocketDirOverride(gatewayEnv);
 
   if (publicUrl) {
-    console.log(`   Ingress URL: ${publicUrl}`);
+    console.log(`   HTTP URL: ${publicUrl}`);
   }
 
   let gateway;