@vellumai/cli 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/teleport.test.ts

@@ -728,7 +728,6 @@ describe("resolveOrHatchTarget", () => {
       null,
       false,
       false,
-      false,
       {},
     );
     expect(result).toBe(newEntry);

package/src/commands/hatch.ts

@@ -176,7 +176,6 @@ interface HatchArgs {
   keepAlive: boolean;
   name: string | null;
   remote: RemoteHost;
-  restart: boolean;
   watch: boolean;
   configValues: Record<string, string>;
 }
@@ -188,7 +187,6 @@ function parseArgs(): HatchArgs {
   let keepAlive = false;
   let name: string | null = null;
   let remote: RemoteHost = DEFAULT_REMOTE;
-  let restart = false;
   let watch = false;
   const configValues: Record<string, string> = {};
 
@@ -209,9 +207,6 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --remote <host>           Remote host (local, gcp, aws, docker, custom, vellum)",
       );
-      console.log(
-        "  --restart                 Restart processes without onboarding side effects",
-      );
       console.log(
         "  --watch                   Run assistant and gateway in watch mode (hot reload on source changes)",
       );
@@ -224,8 +219,6 @@ function parseArgs(): HatchArgs {
       process.exit(0);
     } else if (arg === "-d") {
       detached = true;
-    } else if (arg === "--restart") {
-      restart = true;
     } else if (arg === "--watch") {
       watch = true;
     } else if (arg === "--keep-alive") {
@@ -277,7 +270,7 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --restart, --watch, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>`,
       );
       process.exit(1);
     }
@@ -289,7 +282,6 @@ function parseArgs(): HatchArgs {
     keepAlive,
     name,
     remote,
-    restart,
     watch,
     configValues,
   };
@@ -516,23 +508,8 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const {
-    species,
-    detached,
-    keepAlive,
-    name,
-    remote,
-    restart,
-    watch,
-    configValues,
-  } = parseArgs();
-
-  if (restart && remote !== "local") {
-    console.error(
-      "Error: --restart is only supported for local hatch targets.",
-    );
-    process.exit(1);
-  }
+  const { species, detached, keepAlive, name, remote, watch, configValues } =
+    parseArgs();
 
   if (watch && remote !== "local" && remote !== "docker") {
     console.error(
@@ -542,7 +519,7 @@ export async function hatch(): Promise<void> {
   }
 
   if (remote === "local") {
-    await hatchLocal(species, name, restart, watch, keepAlive, configValues);
+    await hatchLocal(species, name, watch, keepAlive, configValues);
     return;
   }
 

package/src/commands/restore.ts

@@ -11,6 +11,11 @@ import {
   rollbackPlatformAssistant,
   platformImportPreflight,
   platformImportBundle,
+  platformRequestUploadUrl,
+  platformUploadToSignedUrl,
+  platformImportPreflightFromGcs,
+  platformImportBundleFromGcs,
+  platformPollImportStatus,
 } from "../lib/platform-client.js";
 import { performDockerRollback } from "../lib/upgrade-lifecycle.js";
 
@@ -176,6 +181,25 @@ async function restorePlatform(
     process.exit(1);
   }
 
+  // Step 1.5 — Upload to GCS via signed URL (with fallback to inline)
+  let bundleKey: string | null = null;
+  try {
+    const { uploadUrl, bundleKey: key } = await platformRequestUploadUrl(
+      token,
+      entry.runtimeUrl,
+    );
+    bundleKey = key;
+    console.log("Uploading bundle...");
+    await platformUploadToSignedUrl(uploadUrl, new Uint8Array(bundleData));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("not available")) {
+      bundleKey = null;
+    } else {
+      throw err;
+    }
+  }
+
   // Step 2 — Dry-run path
   if (opts.dryRun) {
     if (opts.version) {
@@ -189,11 +213,17 @@ async function restorePlatform(
 
     let preflightResult: { statusCode: number; body: Record<string, unknown> };
     try {
-      preflightResult = await platformImportPreflight(
-        new Uint8Array(bundleData),
-        token,
-        entry.runtimeUrl,
-      );
+      preflightResult = bundleKey
+        ? await platformImportPreflightFromGcs(
+            bundleKey,
+            token,
+            entry.runtimeUrl,
+          )
+        : await platformImportPreflight(
+            new Uint8Array(bundleData),
+            token,
+            entry.runtimeUrl,
+          );
     } catch (err) {
       if (err instanceof Error && err.name === "TimeoutError") {
         console.error("Error: Preflight request timed out after 2 minutes.");
@@ -323,14 +353,16 @@ async function restorePlatform(
 
   let importResult: { statusCode: number; body: Record<string, unknown> };
   try {
-    importResult = await platformImportBundle(
-      new Uint8Array(bundleData),
-      token,
-      entry.runtimeUrl,
-    );
+    importResult = bundleKey
+      ? await platformImportBundleFromGcs(bundleKey, token, entry.runtimeUrl)
+      : await platformImportBundle(
+          new Uint8Array(bundleData),
+          token,
+          entry.runtimeUrl,
+        );
   } catch (err) {
     if (err instanceof Error && err.name === "TimeoutError") {
-      console.error("Error: Import request timed out after 2 minutes.");
+      console.error("Error: Import request timed out after 5 minutes.");
       process.exit(1);
     }
     throw err;
@@ -364,11 +396,83 @@ async function restorePlatform(
     process.exit(1);
   }
 
-  if (importResult.statusCode < 200 || importResult.statusCode >= 300) {
+  if (
+    importResult.statusCode !== 202 &&
+    (importResult.statusCode < 200 || importResult.statusCode >= 300)
+  ) {
     console.error(`Error: Import failed (${importResult.statusCode})`);
     process.exit(1);
   }
 
+  // Async import — poll until complete
+  if (importResult.statusCode === 202) {
+    const jobId = (importResult.body as { job_id?: string }).job_id;
+    if (!jobId) {
+      console.error("Error: Import accepted but no job ID returned.");
+      process.exit(1);
+    }
+
+    const POLL_INTERVAL_MS = 5_000;
+    const TIMEOUT_MS = 10 * 60 * 1_000; // 10 minutes
+    const startTime = Date.now();
+    const deadline = startTime + TIMEOUT_MS;
+
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+
+      let status: {
+        status: string;
+        result?: Record<string, unknown>;
+        error?: string;
+      };
+      try {
+        status = await platformPollImportStatus(jobId, token, entry.runtimeUrl);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("not found")) {
+          throw err;
+        }
+        // Fail fast on auth errors from authHeaders() which don't
+        // match the "status check failed: NNN" format
+        if (msg.includes("401") || msg.includes("403")) {
+          throw err;
+        }
+        // Re-throw permanent 4xx errors, retry transient 5xx
+        const statusMatch = msg.match(/status check failed: (\d+)/);
+        if (statusMatch) {
+          const statusCode = parseInt(statusMatch[1], 10);
+          if (statusCode >= 400 && statusCode < 500) {
+            throw err;
+          }
+        }
+        // Transient error (5xx, network) — retry
+        console.warn(`Polling failed, retrying... (${msg})`);
+        continue;
+      }
+
+      if (status.status === "complete") {
+        importResult = { statusCode: 200, body: status.result ?? {} };
+        break;
+      }
+
+      if (status.status === "failed") {
+        console.error(`Import failed: ${status.error ?? "unknown error"}`);
+        process.exit(1);
+      }
+
+      const elapsed = Math.round((Date.now() - startTime) / 1000);
+      process.stdout.write(`\rImporting... ${elapsed}s elapsed`);
+    }
+
+    // Clear the progress line
+    process.stdout.write("\r" + " ".repeat(40) + "\r");
+
+    if (importResult.statusCode === 202) {
+      console.error("Import timed out after 10 minutes.");
+      process.exit(1);
+    }
+  }
+
   const result = importResult.body as unknown as ImportResponse;
 
   if (!result.success) {

package/src/commands/retire.ts

@@ -200,6 +200,13 @@ async function retireInner(): Promise<void> {
   const source = parseSource();
   const cloud = resolveCloud(entry);
 
+  if (cloud === "apple-container") {
+    console.error(
+      `Error: '${name}' uses the Apple Containers runtime. Its lifecycle is managed by the macOS app — use the app to retire it.`,
+    );
+    process.exit(1);
+  }
+
   if (cloud === "gcp") {
     const project = entry.project;
     const zone = entry.zone;

package/src/commands/sleep.ts

@@ -72,6 +72,13 @@ export async function sleep(): Promise<void> {
     return;
   }
 
+  if (entry.cloud === "apple-container") {
+    console.error(
+      `Error: '${entry.assistantId}' uses the Apple Containers runtime. Its lifecycle is managed by the macOS app — use the app to stop it.`,
+    );
+    process.exit(1);
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
       `Error: 'vellum sleep' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,

package/src/commands/teleport.ts

@@ -23,6 +23,7 @@ import {
   platformUploadToSignedUrl,
   platformImportPreflightFromGcs,
   platformImportBundleFromGcs,
+  platformPollImportStatus,
 } from "../lib/platform-client.js";
 import {
   hatchDocker,
@@ -512,6 +513,16 @@ async function exportFromAssistant(
         if (msg.includes("not found")) {
           throw err;
         }
+        // Re-throw permanent 4xx errors (auth, forbidden, etc.)
+        // but retry transient 5xx errors
+        const statusMatch = msg.match(/status check failed: (\d+)/);
+        if (statusMatch) {
+          const statusCode = parseInt(statusMatch[1], 10);
+          if (statusCode >= 400 && statusCode < 500) {
+            throw err;
+          }
+        }
+        // Transient error — retry
         console.warn(`Polling failed, retrying... (${msg})`);
         await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
         continue;
@@ -706,7 +717,7 @@ async function importToAssistant(
         : await platformImportBundle(bundleData, token, entry.runtimeUrl);
     } catch (err) {
       if (err instanceof Error && err.name === "TimeoutError") {
-        console.error("Error: Import request timed out after 5 minutes.");
+        console.error("Error: Import request timed out.");
         process.exit(1);
       }
       throw err;
@@ -714,6 +725,74 @@ async function importToAssistant(
 
     handleImportStatusErrors(importResult.statusCode, entry.assistantId);
 
+    if (importResult.statusCode === 202) {
+      const jobId = (importResult.body as { job_id?: string }).job_id;
+      if (!jobId) {
+        console.error("Error: Import accepted but no job ID returned.");
+        process.exit(1);
+      }
+
+      const POLL_INTERVAL_MS = 5_000;
+      const TIMEOUT_MS = 10 * 60 * 1_000; // 10 minutes (platform staleness is 930s)
+      const startTime = Date.now();
+      const deadline = startTime + TIMEOUT_MS;
+
+      while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+
+        let status: {
+          status: string;
+          result?: Record<string, unknown>;
+          error?: string;
+        };
+        try {
+          status = await platformPollImportStatus(
+            jobId,
+            token,
+            entry.runtimeUrl,
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (msg.includes("not found")) {
+            throw err;
+          }
+          // Re-throw permanent 4xx errors (auth, forbidden, etc.)
+          // but retry transient 5xx errors
+          const statusMatch = msg.match(/status check failed: (\d+)/);
+          if (statusMatch) {
+            const statusCode = parseInt(statusMatch[1], 10);
+            if (statusCode >= 400 && statusCode < 500) {
+              throw err;
+            }
+          }
+          // Transient error — retry
+          console.warn(`Polling failed, retrying... (${msg})`);
+          continue;
+        }
+
+        if (status.status === "complete") {
+          importResult = { statusCode: 200, body: status.result ?? {} };
+          break;
+        }
+
+        if (status.status === "failed") {
+          console.error(`Import failed: ${status.error ?? "unknown error"}`);
+          process.exit(1);
+        }
+
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        process.stdout.write(`\rImporting... ${elapsed}s elapsed`);
+      }
+
+      // Clear the progress line
+      process.stdout.write("\r" + " ".repeat(40) + "\r");
+
+      if (importResult.statusCode === 202) {
+        console.error("Import timed out after 10 minutes.");
+        process.exit(1);
+      }
+    }
+
     const result = importResult.body as unknown as ImportResponse;
     printImportSummary(result);
     return;
@@ -779,7 +858,7 @@ 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, false, {});
+    await hatchLocal("vellum", targetName ?? null, false, false, {});
     const entry = targetName
       ? findAssistantByName(targetName)
       : (loadAllAssistants().find((e) => !beforeIds.has(e.assistantId)) ??

package/src/commands/wake.ts

@@ -59,6 +59,13 @@ export async function wake(): Promise<void> {
     return;
   }
 
+  if (entry.cloud === "apple-container") {
+    console.error(
+      `Error: '${entry.assistantId}' uses the Apple Containers runtime. Its lifecycle is managed by the macOS app — use the app to start it.`,
+    );
+    process.exit(1);
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
       `Error: 'vellum wake' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,

package/src/lib/assistant-config.ts

@@ -181,6 +181,12 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
     return false;
   }
 
+  // Apple-containers entries are fully managed by the macOS app.
+  // Skip legacy migration to avoid corrupting their fields.
+  if (raw.cloud === "apple-container") {
+    return false;
+  }
+
   let mutated = false;
 
   // Migrate top-level `baseDataDir` → `resources.instanceDir`

package/src/lib/docker.ts

@@ -644,6 +644,9 @@ export function serviceDockerRunArgs(opts: {
       ...(opts.bootstrapSecret
         ? ["-e", `GUARDIAN_BOOTSTRAP_SECRET=${opts.bootstrapSecret}`]
         : []),
+      ...(process.env.VELLUM_PLATFORM_URL
+        ? ["-e", `VELLUM_PLATFORM_URL=${process.env.VELLUM_PLATFORM_URL}`]
+        : []),
       imageTags.gateway,
     ],
     "credential-executor": () => [

package/src/lib/hatch-local.ts

@@ -144,18 +144,10 @@ function installCLISymlink(): void {
 export async function hatchLocal(
   species: Species,
   name: string | null,
-  restart: boolean = false,
   watch: boolean = false,
   keepAlive: boolean = false,
   configValues: Record<string, string> = {},
 ): Promise<void> {
-  if (restart && !name && !process.env.VELLUM_ASSISTANT_NAME) {
-    console.error(
-      "Error: Cannot restart without a known assistant ID. Provide --name or ensure VELLUM_ASSISTANT_NAME is set.",
-    );
-    process.exit(1);
-  }
-
   const instanceName = generateInstanceName(
     species,
     name ?? process.env.VELLUM_ASSISTANT_NAME,
@@ -345,24 +337,22 @@ export async function hatchLocal(
     resources: { ...resources, signingKey },
   };
   emitProgress(7, 7, "Saving configuration...");
-  if (!restart) {
-    saveAssistantEntry(localEntry);
-    setActiveAssistant(instanceName);
-    syncConfigToLockfile();
-
-    if (process.env.VELLUM_DESKTOP_APP) {
-      installCLISymlink();
-    }
+  saveAssistantEntry(localEntry);
+  setActiveAssistant(instanceName);
+  syncConfigToLockfile();
 
-    console.log("");
-    console.log(`✅ Local assistant hatched!`);
-    console.log("");
-    console.log("Instance details:");
-    console.log(`  Name: ${instanceName}`);
-    console.log(`  Runtime: ${runtimeUrl}`);
-    console.log("");
+  if (process.env.VELLUM_DESKTOP_APP) {
+    installCLISymlink();
   }
 
+  console.log("");
+  console.log(`✅ Local assistant hatched!`);
+  console.log("");
+  console.log("Instance details:");
+  console.log(`  Name: ${instanceName}`);
+  console.log(`  Runtime: ${runtimeUrl}`);
+  console.log("");
+
   if (keepAlive) {
     const healthUrl = `http://127.0.0.1:${resources.gatewayPort}/healthz`;
     const healthTarget = "Gateway";

package/src/lib/platform-client.ts

@@ -529,7 +529,7 @@ export async function platformImportBundleFromGcs(
       method: "POST",
       headers: await authHeaders(token, platformUrl),
       body: JSON.stringify({ bundle_key: bundleKey }),
-      signal: AbortSignal.timeout(300_000),
+      signal: AbortSignal.timeout(60_000),
     },
   );
 
@@ -543,3 +543,43 @@ export async function platformImportBundleFromGcs(
   >;
   return { statusCode: response.status, body };
 }
+
+export async function platformPollImportStatus(
+  jobId: string,
+  token: string,
+  platformUrl?: string,
+): Promise<{
+  status: string;
+  result?: Record<string, unknown>;
+  error?: string;
+}> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(
+    `${resolvedUrl}/v1/migrations/import/${jobId}/status/`,
+    {
+      headers: await authHeaders(token, platformUrl),
+    },
+  );
+
+  if (response.status === 404) {
+    throw new Error("Import job not found");
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Import status check failed: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const body = (await response.json()) as {
+    status: string;
+    job_id?: string;
+    result?: Record<string, unknown>;
+    error?: string;
+  };
+  return {
+    status: body.status,
+    result: body.result,
+    error: body.error,
+  };
+}