@vellumai/cli 0.6.6 → 0.7.1

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/env.ts

@@ -0,0 +1,93 @@
+import { SEEDS } from "../lib/environments/seeds.js";
+import {
+  clearDefaultEnvironment,
+  readDefaultEnvironment,
+  resolveEnvironmentSource,
+  writeDefaultEnvironment,
+} from "../lib/environments/resolve.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum env <subcommand>");
+  console.log("");
+  console.log("Manage the default CLI environment.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  set <name>   Set the default environment");
+  console.log("  get          Show the current environment and its source");
+  console.log("  clear        Remove the default, falling back to production");
+  console.log("");
+  console.log(`Known environments: ${Object.keys(SEEDS).join(", ")}`);
+  console.log("");
+  console.log("Examples:");
+  console.log("  $ vellum env set local    # all commands default to local");
+  console.log("  $ vellum env get          # show resolved environment");
+  console.log("  $ vellum env clear        # revert to production default");
+}
+
+function envSet(name: string | undefined): void {
+  if (!name) {
+    console.error(
+      `Usage: vellum env set <name>\nKnown environments: ${Object.keys(SEEDS).join(", ")}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!SEEDS[name]) {
+    console.error(
+      `Unknown environment "${name}". Known environments: ${Object.keys(SEEDS).join(", ")}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  writeDefaultEnvironment(name);
+  console.log(`Default environment set to "${name}".`);
+}
+
+function envGet(): void {
+  const { name, source } = resolveEnvironmentSource();
+  const sourceLabels: Record<typeof source, string> = {
+    flag: "--environment flag",
+    env: "VELLUM_ENVIRONMENT env var",
+    config: "~/.config/vellum/environment",
+    default: "default",
+  };
+  console.log(`${name} (from ${sourceLabels[source]})`);
+}
+
+function envClear(): void {
+  const current = readDefaultEnvironment();
+  if (!current) {
+    console.log("No default environment is set (already using production).");
+    return;
+  }
+  clearDefaultEnvironment();
+  console.log(
+    `Cleared default environment "${current}". Falling back to production.`,
+  );
+}
+
+export async function env(): Promise<void> {
+  const args = process.argv.slice(3);
+  const sub = args[0];
+
+  if (!sub || sub === "--help" || sub === "-h") {
+    printUsage();
+    return;
+  }
+
+  switch (sub) {
+    case "set":
+      envSet(args[1]);
+      break;
+    case "get":
+      envGet();
+      break;
+    case "clear":
+      envClear();
+      break;
+    default:
+      console.error(`Unknown subcommand: ${sub}`);
+      printUsage();
+      process.exitCode = 1;
+  }
+}

package/src/commands/events.ts

@@ -9,6 +9,7 @@
 
 import { extractFlag } from "../lib/arg-utils.js";
 import { AssistantClient } from "../lib/assistant-client.js";
+import { getClientRegistrationHeaders } from "../lib/client-identity.js";
 
 function printUsage(): void {
   console.log(`vellum events - Stream events from a running assistant
@@ -136,6 +137,7 @@ export async function events(): Promise<void> {
   for await (const event of client.stream<AssistantEvent>("/events", {
     signal: controller.signal,
     query,
+    headers: getClientRegistrationHeaders(),
   })) {
     if (jsonOutput) {
       console.log(JSON.stringify(event));

package/src/commands/exec.ts

@@ -1,14 +1,16 @@
 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";
+import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
 import { sshAppleContainer } from "../lib/ssh-apple-container";
+import {
+  interactiveSession,
+  nonInteractiveExec,
+  shellEscapeArgs,
+} from "../lib/terminal-session";
 
 const SERVICE_ALIASES: Record<string, ServiceName> = {
   assistant: "assistant",
@@ -74,11 +76,15 @@ export async function exec(): Promise<void> {
     );
     console.log("");
     console.log("Options:");
+    console.log("  --service <svc>     Target service (default: assistant)");
     console.log(
-      "  --service <svc>     Target service (default: assistant)",
+      "  -it                 Interactive mode with TTY (like docker exec -it)",
     );
     console.log(
-      "  -it                 Interactive mode with TTY (like docker exec -it)",
+      "  --timeout <secs>    Timeout in seconds (default: 30, 0 = no timeout)",
+    );
+    console.log(
+      "  --verbose           Show debug output (SSE events, sentinel parsing)",
     );
     console.log("");
     console.log("Services:");
@@ -90,9 +96,7 @@ export async function exec(): Promise<void> {
     console.log("  vellum exec -- ls -la /workspace");
     console.log("  vellum exec -- cat /workspace/NOW.md");
     console.log("  vellum exec -it -- /bin/bash");
-    console.log(
-      "  vellum exec --service gateway -- cat /tmp/gateway.log",
-    );
+    console.log("  vellum exec --service gateway -- cat /tmp/gateway.log");
     process.exit(0);
   }
 
@@ -114,12 +118,23 @@ export async function exec(): Promise<void> {
   let nameArg: string | undefined;
   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("-")) {
       nameArg = preArgs[i];
     }
@@ -127,9 +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) {
@@ -179,6 +192,38 @@ export async function exec(): Promise<void> {
     return;
   }
 
+  if (cloud === "vellum") {
+    const token = readPlatformToken();
+    if (!token) {
+      console.error(
+        "Not logged in. Run `vellum login` first to authenticate with the platform.",
+      );
+      process.exit(1);
+    }
+
+    const assistant = {
+      assistantId: entry.assistantId,
+      token,
+      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), serviceParam);
+      return;
+    }
+
+    // Non-interactive: sentinel-based output capture with exit code
+    await nonInteractiveExec(assistant, command, {
+      verbose,
+      timeoutMs,
+      service: serviceParam,
+    });
+    return;
+  }
+
   console.error(
     `Error: 'vellum exec' is not supported for ${cloud} instances.`,
   );