@vellumai/cli 0.7.0 → 0.7.1

package/src/__tests__/teleport.test.ts

@@ -91,14 +91,6 @@ const hatchAssistantMock = spyOn(
   reusedExisting: false,
 });
 
-const platformInitiateExportMock = spyOn(
-  platformClient,
-  "platformInitiateExport",
-).mockResolvedValue({
-  jobId: "platform-export-job-1",
-  status: "pending",
-});
-
 const platformPollJobStatusMock = spyOn(
   platformClient,
   "platformPollJobStatus",
@@ -294,7 +286,6 @@ afterAll(() => {
   getPlatformUrlMock.mockRestore();
   hatchAssistantMock.mockRestore();
   checkExistingPlatformAssistantMock.mockRestore();
-  platformInitiateExportMock.mockRestore();
   platformPollJobStatusMock.mockRestore();
   platformRequestSignedUrlMock.mockRestore();
   platformImportBundleFromGcsMock.mockRestore();
@@ -319,7 +310,7 @@ let consoleErrorSpy: ReturnType<typeof spyOn>;
 let fetchCalls: Array<{ url: string; body: unknown }>;
 
 function defaultLocalRuntimePollImpl(
-  _runtimeUrl: string,
+  _entry: unknown,
   _token: string,
   jobId: string,
 ): Promise<{
@@ -378,11 +369,6 @@ beforeEach(() => {
     },
     reusedExisting: false,
   });
-  platformInitiateExportMock.mockReset();
-  platformInitiateExportMock.mockResolvedValue({
-    jobId: "platform-export-job-1",
-    status: "pending",
-  });
   platformPollJobStatusMock.mockReset();
   platformPollJobStatusMock.mockResolvedValue({
     jobId: "platform-job-1",
@@ -869,9 +855,14 @@ describe("unified GCS flow — four directions", () => {
         "https://platform.vellum.ai",
       );
 
-      // Runtime export-to-gcs kicked off with the signed upload URL
+      // Runtime export-to-gcs kicked off with the signed upload URL.
+      // Helper takes an entry, not a bare URL — the entry's cloud drives
+      // URL construction (local → gateway loopback path).
       expect(localRuntimeExportToGcsMock).toHaveBeenCalledWith(
-        "http://localhost:7821",
+        expect.objectContaining({
+          cloud: "local",
+          runtimeUrl: "http://localhost:7821",
+        }),
         "local-token",
         expect.objectContaining({
           uploadUrl: "https://storage.googleapis.com/bucket/signed-upload",
@@ -926,13 +917,58 @@ describe("unified GCS flow — four directions", () => {
       bundleKey: "platform-exports/org-1/bundle-abc.vbundle",
     });
 
+    // The bundle key now flows from the upload signed-URL request rather than
+    // the job-status payload — pin it so the download-URL assertion below
+    // still uses the same expected key.
+    platformRequestSignedUrlMock.mockImplementation(async (params) => ({
+      url:
+        params.operation === "upload"
+          ? "https://storage.googleapis.com/bucket/signed-upload"
+          : "https://storage.googleapis.com/bucket/signed-download",
+      bundleKey:
+        params.bundleKey ?? "platform-exports/org-1/bundle-abc.vbundle",
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+    }));
+
     const restoreFetch = installTrackingFetch();
     try {
       await teleport();
 
-      // Platform side: initiated server export and polled the unified status.
-      expect(platformInitiateExportMock).toHaveBeenCalled();
-      expect(platformPollJobStatusMock).toHaveBeenCalled();
+      // Platform side: requested an upload URL, kicked off a runtime export to
+      // GCS, and polled the unified job status.
+      expect(platformRequestSignedUrlMock).toHaveBeenCalledWith(
+        expect.objectContaining({ operation: "upload" }),
+        "platform-token",
+        "https://platform.vellum.ai",
+      );
+      // For platform sources, export-to-gcs is reached via the platform's
+      // wildcard runtime proxy. The helper builds the assistant-scoped URL
+      // from the entry (`/v1/assistants/<id>/migrations/export-to-gcs`) and
+      // sends platform-token auth — no guardian-token bootstrap.
+      expect(localRuntimeExportToGcsMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          cloud: "vellum",
+          runtimeUrl: "https://platform.vellum.ai",
+          assistantId: "my-platform",
+        }),
+        "platform-token",
+        expect.objectContaining({
+          uploadUrl: "https://storage.googleapis.com/bucket/signed-upload",
+          description: "teleport export",
+        }),
+      );
+      // Polling for platform sources also goes through the wildcard via
+      // localRuntimePollJobStatus(entry, ...) — the dedicated
+      // `/v1/migrations/jobs/{id}/` endpoint queries platform-side
+      // ImportJob records and would 404 on runtime-created job IDs.
+      expect(localRuntimePollJobStatusMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          cloud: "vellum",
+          runtimeUrl: "https://platform.vellum.ai",
+        }),
+        "platform-token",
+        "local-export-job-1",
+      );
 
       // For the local target we request a download URL keyed by the
       // platform's bundle_key. The URL must target the SOURCE platform
@@ -949,7 +985,10 @@ describe("unified GCS flow — four directions", () => {
 
       // Runtime import-from-gcs was kicked off with that URL.
       expect(localRuntimeImportFromGcsMock).toHaveBeenCalledWith(
-        "http://localhost:7821",
+        expect.objectContaining({
+          cloud: "local",
+          runtimeUrl: "http://localhost:7821",
+        }),
         "local-token",
         expect.objectContaining({
           bundleUrl: "https://storage.googleapis.com/bucket/signed-download",
@@ -1009,7 +1048,10 @@ describe("unified GCS flow — four directions", () => {
         "https://platform.vellum.ai",
       );
       expect(localRuntimeImportFromGcsMock).toHaveBeenCalledWith(
-        "http://localhost:7822",
+        expect.objectContaining({
+          cloud: "docker",
+          runtimeUrl: "http://localhost:7822",
+        }),
         "local-token",
         expect.objectContaining({
           bundleUrl: "https://storage.googleapis.com/bucket/signed-download",
@@ -1062,7 +1104,10 @@ describe("unified GCS flow — four directions", () => {
         "https://platform.vellum.ai",
       );
       expect(localRuntimeExportToGcsMock).toHaveBeenCalledWith(
-        "http://localhost:7822",
+        expect.objectContaining({
+          cloud: "docker",
+          runtimeUrl: "http://localhost:7822",
+        }),
         "local-token",
         expect.objectContaining({
           uploadUrl: "https://storage.googleapis.com/bucket/signed-upload",
@@ -1071,7 +1116,10 @@ describe("unified GCS flow — four directions", () => {
 
       // Import leg: download-URL targets the new local runtime
       expect(localRuntimeImportFromGcsMock).toHaveBeenCalledWith(
-        "http://localhost:7823",
+        expect.objectContaining({
+          cloud: "local",
+          runtimeUrl: "http://localhost:7823",
+        }),
         "local-token",
         expect.anything(),
       );
@@ -1159,12 +1207,23 @@ describe("signed-URL request targets the bundle-owning platform", () => {
       bundleKey: "dev-bundle-key",
     });
 
+    // Bundle key flows from the upload signed-URL request now; pin it so the
+    // download-URL assertion below uses the same key.
+    platformRequestSignedUrlMock.mockImplementation(async (params) => ({
+      url:
+        params.operation === "upload"
+          ? "https://storage.googleapis.com/bucket/signed-upload"
+          : "https://storage.googleapis.com/bucket/signed-download",
+      bundleKey: params.bundleKey ?? "dev-bundle-key",
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+    }));
+
     const restoreFetch = installTrackingFetch();
     try {
       await teleport();
 
       // The download URL must be requested from the SOURCE platform (where
-      // the bundle was written by the server-side export), not the default.
+      // the bundle was written by the runtime export), not the default.
       expect(platformRequestSignedUrlMock).toHaveBeenCalledWith(
         { operation: "download", bundleKey: "dev-bundle-key" },
         "platform-token",
@@ -1555,10 +1614,9 @@ describe("dry-run", () => {
         ),
       );
 
-      // Must fail BEFORE any export work — no signed URL request, no platform
-      // export initiation, nothing that costs time or bandwidth.
+      // Must fail BEFORE any export work — no signed URL request, no runtime
+      // export kickoff, nothing that costs time or bandwidth.
       expect(platformRequestSignedUrlMock).not.toHaveBeenCalled();
-      expect(platformInitiateExportMock).not.toHaveBeenCalled();
       expect(localRuntimeExportToGcsMock).not.toHaveBeenCalled();
     } finally {
       restoreFetch();

package/src/commands/backup.ts

@@ -1,14 +1,19 @@
 import { mkdirSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
 
-import { findAssistantByName } from "../lib/assistant-config";
+import type { AssistantEntry } from "../lib/assistant-config.js";
+import { findAssistantByName } from "../lib/assistant-config.js";
 import { getBackupsDir, formatSize } from "../lib/backup-ops.js";
 import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
+import { pollJobUntilDone } from "../lib/job-polling.js";
 import {
+  MigrationInProgressError,
+  localRuntimeExportToGcs,
+  localRuntimePollJobStatus,
+} from "../lib/local-runtime-client.js";
+import {
+  platformRequestSignedUrl,
   readPlatformToken,
-  platformInitiateExport,
-  platformPollExportStatus,
-  platformDownloadExport,
 } from "../lib/platform-client.js";
 
 export async function backup(): Promise<void> {
@@ -73,7 +78,7 @@ export async function backup(): Promise<void> {
   }
 
   if (cloud === "vellum") {
-    await backupPlatform(name, outputArg, entry.runtimeUrl);
+    await backupPlatform(entry, name, outputArg);
     return;
   }
 
@@ -188,39 +193,66 @@ export async function backup(): Promise<void> {
 }
 
 // ---------------------------------------------------------------------------
-// Platform (Vellum-hosted) backup via Django async migration export
+// Platform-managed (cloud="vellum") backup over GCS.
+//
+// The runtime exports the bundle straight to a platform-issued signed GCS
+// URL; the CLI then downloads from GCS to local disk. Bytes never flow
+// through Django. Same architectural shape as the platform-source half of
+// `vellum teleport`. Output format and success log lines match mode 1
+// (runtime-direct local backup) so users see one consistent UX.
+//
+// Lifecycle: the GCS bucket has a 1-day TTL on `uploads/<org>/*` objects
+// (see `vellum-assistant-platform/django/app/assistant/migration/views.py`
+// and `migration/services.py`). Backup is single-shot with no import to
+// trigger best-effort cleanup, so the bundle sits in GCS up to 24h before
+// TTL deletion. No explicit cleanup endpoint exists; relying on TTL is
+// intentional.
 // ---------------------------------------------------------------------------
-
 async function backupPlatform(
+  entry: AssistantEntry,
   name: string,
   outputArg?: string,
-  runtimeUrl?: string,
 ): Promise<void> {
-  // Step 1 — Authenticate
-  const token = readPlatformToken();
-  if (!token) {
-    console.error("Not logged in. Run 'vellum login' first.");
+  const platformToken = readPlatformToken();
+  if (!platformToken) {
+    console.error(
+      "Not logged in. Run 'vellum login' first (required for platform-managed backup).",
+    );
     process.exit(1);
   }
-
-  // Step 2 — Initiate export job
+  // Pin upload, download, and runtime requests to the same platform instance
+  // the assistant lives on. Using `getPlatformUrl()` instead would target
+  // whatever the lockfile / env-var resolves to, which may differ from
+  // `entry.runtimeUrl` for staging/dev assistants and end up signing URLs
+  // for the wrong GCS bucket. Mirrors the teleport bundlePlatformUrl
+  // threading at `cli/src/commands/teleport.ts:1311-1312`.
+  const platformUrl = entry.runtimeUrl;
+  // Track the working platform token across kickoff/poll/download so a
+  // 401-driven refresh during polling stays consistent through the final
+  // signed-download request.
+  let exportPlatformToken = platformToken;
+
+  // Step 1 — Request a signed upload URL.
+  const { url: uploadUrl, bundleKey } = await platformRequestSignedUrl(
+    { operation: "upload" },
+    exportPlatformToken,
+    platformUrl,
+  );
+
+  // Step 2 — Kick off runtime export-to-GCS through the platform's
+  // wildcard runtime proxy. `localRuntimeExportToGcs` builds the
+  // `/v1/assistants/<id>/migrations/export-to-gcs` URL for cloud="vellum"
+  // and uses platform-token auth (no guardian-token bootstrap).
   let jobId: string;
   try {
-    const result = await platformInitiateExport(
-      token,
-      "CLI backup",
-      runtimeUrl,
-    );
-    jobId = result.jobId;
+    ({ jobId } = await localRuntimeExportToGcs(entry, exportPlatformToken, {
+      uploadUrl,
+      description: "CLI backup",
+    }));
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("401") || msg.includes("403")) {
-      console.error("Authentication failed. Run 'vellum login' to refresh.");
-      process.exit(1);
-    }
-    if (msg.includes("429")) {
+    if (err instanceof MigrationInProgressError) {
       console.error(
-        "Too many export requests. Please wait before trying again.",
+        `Error: Another backup or teleport export is already in progress on '${entry.assistantId}' (job ${err.existingJobId}). Wait for it to finish, then re-run.`,
       );
       process.exit(1);
     }
@@ -229,65 +261,79 @@ async function backupPlatform(
 
   console.log(`Export started (job ${jobId})...`);
 
-  // Step 3 — Poll for completion
-  const POLL_INTERVAL_MS = 2_000;
-  const TIMEOUT_MS = 5 * 60 * 1_000; // 5 minutes
-  const deadline = Date.now() + TIMEOUT_MS;
-  let downloadUrl: string | undefined;
-
-  while (Date.now() < deadline) {
-    let status: { status: string; downloadUrl?: string; error?: string };
-    try {
-      status = await platformPollExportStatus(jobId, token, runtimeUrl);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      // Let non-transient errors (e.g. 404 "job not found") propagate immediately
-      if (msg.includes("not found")) {
-        throw err;
+  // Step 3 — Poll the job through the wildcard proxy. The dedicated
+  // `/v1/migrations/jobs/{id}/` endpoint queries platform-side ImportJob
+  // records and would 404 on runtime-created job IDs.
+  const terminal = await pollJobUntilDone({
+    label: "platform export",
+    poll: () => localRuntimePollJobStatus(entry, exportPlatformToken, jobId),
+    refreshOn401: async () => {
+      const refreshed = readPlatformToken();
+      if (!refreshed) {
+        throw new Error(
+          "Platform auth expired during export and no credential was found on disk. Run 'vellum login' and retry.",
+        );
       }
-      console.warn(`Polling failed, retrying... (${msg})`);
-      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-      continue;
-    }
+      exportPlatformToken = refreshed;
+    },
+  });
 
-    if (status.status === "complete") {
-      downloadUrl = status.downloadUrl;
-      break;
-    }
-
-    if (status.status === "failed") {
-      console.error(`Export failed: ${status.error ?? "unknown error"}`);
-      process.exit(1);
-    }
-
-    // Still in progress — wait and retry
-    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  if (terminal.status === "failed") {
+    console.error(`Error: Export failed: ${terminal.error}`);
+    process.exit(1);
   }
 
-  if (!downloadUrl) {
-    console.error("Export timed out after 5 minutes.");
+  // Step 4 — Request a signed download URL for the same bundle and fetch
+  // it from GCS directly. No auth on signed URLs.
+  // Use `exportPlatformToken` (not the original `platformToken`) so a
+  // poll-loop 401 refresh doesn't get clobbered here — otherwise a long
+  // export that recovered mid-poll via re-auth would still 401 on the
+  // download-URL request and abort an otherwise successful run.
+  const { url: bundleUrl } = await platformRequestSignedUrl(
+    { operation: "download", bundleKey },
+    exportPlatformToken,
+    platformUrl,
+  );
+
+  let downloadResponse: Response;
+  try {
+    downloadResponse = await fetch(bundleUrl);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Error: Failed to fetch bundle from GCS: ${msg}`);
+    process.exit(1);
+  }
+  if (!downloadResponse.ok) {
+    const body = await downloadResponse.text().catch(() => "");
+    console.error(
+      `Error: Failed to fetch bundle from GCS (${downloadResponse.status}): ${body}`,
+    );
     process.exit(1);
   }
 
-  // Step 4 — Download bundle
+  const arrayBuffer = await downloadResponse.arrayBuffer();
+  const data = new Uint8Array(arrayBuffer);
+
+  // Step 5 — Write to disk using the same path resolution mode 1 uses.
   const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
   const outputPath =
     outputArg || join(getBackupsDir(), `${name}-${isoTimestamp}.vbundle`);
-
   mkdirSync(dirname(outputPath), { recursive: true });
-
-  const response = await platformDownloadExport(downloadUrl);
-  const arrayBuffer = await response.arrayBuffer();
-  const data = new Uint8Array(arrayBuffer);
-
   writeFileSync(outputPath, data);
 
-  // Step 5 — Print success
+  // Step 6 — Print success. Manifest SHA is included only if the runtime
+  // surfaced it via the unified job result; the export-to-gcs runtime
+  // route does not set the legacy `X-Vbundle-Manifest-Sha256` response
+  // header.
   console.log(`Backup saved to ${outputPath}`);
   console.log(`Size: ${formatSize(data.byteLength)}`);
-
-  const manifestSha = response.headers.get("X-Vbundle-Manifest-Sha256");
-  if (manifestSha) {
+  const manifestSha =
+    terminal.status === "complete" &&
+    terminal.result &&
+    typeof terminal.result === "object"
+      ? (terminal.result as Record<string, unknown>).manifest_sha256
+      : undefined;
+  if (typeof manifestSha === "string") {
     console.log(`Manifest SHA-256: ${manifestSha}`);
   }
 }

package/src/commands/client.ts

@@ -3,7 +3,7 @@ import { hostname } from "os";
 import {
   findAssistantByName,
   getActiveAssistant,
-  loadLatestAssistant,
+  resolveAssistant,
 } from "../lib/assistant-config";
 import {
   DAEMON_INTERNAL_ASSISTANT_ID,
@@ -11,7 +11,8 @@ import {
   type Species,
 } from "../lib/constants";
 import { loadGuardianToken } from "../lib/guardian-token";
-import { getLocalLanIPv4, getMacLocalHostname } from "../lib/local";
+import { getLocalLanIPv4 } from "../lib/local";
+import { tuiLog } from "../lib/tui-log";
 
 const ANSI = {
   reset: "\x1b[0m",
@@ -76,8 +77,8 @@ function parseArgs(): ParsedArgs {
       }
     }
     if (!entry && hasExplicitUrl) {
-      // URL provided but active assistant missing or unset — use latest for remaining defaults
-      entry = loadLatestAssistant();
+      // URL provided but active assistant missing or unset — resolve for remaining defaults
+      entry = resolveAssistant();
     } else if (!entry) {
       console.error(
         "No active assistant set. Set one with 'vellum use <name>' or specify a name: 'vellum client <name>'.",
@@ -140,11 +141,6 @@ function maybeSwapToLocalhost(url: string): string {
     }
   }
 
-  const macHost = getMacLocalHostname();
-  if (macHost) {
-    localNames.push(macHost.toLowerCase());
-  }
-
   const lanIp = getLocalLanIPv4();
   if (lanIp) {
     localNames.push(lanIp);
@@ -188,6 +184,9 @@ export async function client(): Promise<void> {
   const { runtimeUrl, assistantId, species, bearerToken, project, zone } =
     parseArgs();
 
+  tuiLog.init();
+  tuiLog.info("session start", { runtimeUrl, assistantId, species });
+
   const { renderChatApp } = await import("../components/DefaultMainScreen");
 
   process.stdout.write("\x1b[2J\x1b[H");
@@ -197,6 +196,8 @@ export async function client(): Promise<void> {
     assistantId,
     species,
     () => {
+      tuiLog.info("session end (user disconnect)");
+      tuiLog.close();
       app.unmount();
       process.stdout.write("\x1b[2J\x1b[H");
       console.log(`${ANSI.dim}Disconnected.${ANSI.reset}`);

package/src/commands/exec.ts

@@ -1,10 +1,6 @@
 import { spawn } from "child_process";
 
-import {
-  findAssistantByName,
-  loadLatestAssistant,
-  resolveCloud,
-} from "../lib/assistant-config";
+import { resolveAssistant, resolveCloud } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import type { ServiceName } from "../lib/docker";
 import { execAppleContainer } from "../lib/exec-apple-container";
@@ -84,6 +80,9 @@ export async function exec(): Promise<void> {
     console.log(
       "  -it                 Interactive mode with TTY (like docker exec -it)",
     );
+    console.log(
+      "  --timeout <secs>    Timeout in seconds (default: 30, 0 = no timeout)",
+    );
     console.log(
       "  --verbose           Show debug output (SSE events, sentinel parsing)",
     );
@@ -120,12 +119,20 @@ export async function exec(): Promise<void> {
   let serviceRaw = "assistant";
   let interactive = false;
   let verbose = false;
+  let timeoutMs = 30_000;
 
   for (let i = 0; i < preArgs.length; i++) {
     if (preArgs[i] === "--service" && preArgs[i + 1]) {
       serviceRaw = preArgs[++i];
     } else if (preArgs[i] === "-it" || preArgs[i] === "-ti") {
       interactive = true;
+    } else if (preArgs[i] === "--timeout" && preArgs[i + 1]) {
+      const secs = Number(preArgs[++i]);
+      if (!Number.isFinite(secs) || secs < 0) {
+        console.error("Error: --timeout must be a non-negative number.");
+        process.exit(1);
+      }
+      timeoutMs = secs === 0 ? 0 : secs * 1000;
     } else if (preArgs[i] === "--verbose") {
       verbose = true;
     } else if (!preArgs[i].startsWith("-")) {
@@ -135,7 +142,7 @@ export async function exec(): Promise<void> {
 
   const service = normalizeService(serviceRaw);
 
-  const entry = nameArg ? findAssistantByName(nameArg) : loadLatestAssistant();
+  const entry = resolveAssistant(nameArg);
 
   if (!entry) {
     if (nameArg) {
@@ -200,14 +207,20 @@ export async function exec(): Promise<void> {
       platformUrl: getPlatformUrl(),
     };
 
+    const serviceParam = service === "assistant" ? undefined : service;
+
     if (interactive) {
       // Interactive mode: shell-escape argv and delegate to full terminal
-      await interactiveSession(assistant, shellEscapeArgs(command));
+      await interactiveSession(assistant, shellEscapeArgs(command), serviceParam);
       return;
     }
 
     // Non-interactive: sentinel-based output capture with exit code
-    await nonInteractiveExec(assistant, command, { verbose });
+    await nonInteractiveExec(assistant, command, {
+      verbose,
+      timeoutMs,
+      service: serviceParam,
+    });
     return;
   }
 

package/src/commands/hatch.ts

@@ -15,7 +15,7 @@ import {
   VALID_SPECIES,
 } from "../lib/constants";
 import type { RemoteHost, Species } from "../lib/constants";
-import { buildInitialConfig } from "../lib/config-utils";
+import { buildNestedConfig } from "../lib/config-utils";
 import { hatchDocker } from "../lib/docker";
 import { hatchGcp } from "../lib/gcp";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
@@ -123,11 +123,7 @@ export async function buildStartupScript(
   // and export the env var so the daemon reads it on first boot.
   let configWriteBlock = "";
   if (Object.keys(configValues).length > 0) {
-    const configJson = JSON.stringify(
-      buildInitialConfig(configValues),
-      null,
-      2,
-    );
+    const configJson = JSON.stringify(buildNestedConfig(configValues), null, 2);
     configWriteBlock = `
 echo "Writing default workspace config..."
 VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH="/tmp/vellum-initial-config-$$.json"