@vellumai/cli 0.12.7 → 0.12.9

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/package.json

@@ -29,6 +29,7 @@
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
     "./integration-categories": "./src/integration-categories.ts",
+    "./migration-import": "./src/migration-import.ts",
     "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/__tests__/migration-import.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseImportFailure } from "../migration-import.js";
+
+describe("parseImportFailure", () => {
+  test("parses a validation report", () => {
+    const failure = parseImportFailure(
+      JSON.stringify({
+        success: false,
+        reason: "validation_failed",
+        errors: [
+          {
+            code: "entry_hash",
+            message: "Checksum mismatch",
+            path: "workspace/a.md",
+          },
+        ],
+      }),
+    );
+    expect(failure).toEqual({
+      reason: "validation_failed",
+      errors: [{ message: "Checksum mismatch", path: "workspace/a.md" }],
+    });
+  });
+
+  test("parses a plain message body", () => {
+    expect(parseImportFailure('{"message":"disk full"}')).toEqual({
+      message: "disk full",
+    });
+  });
+
+  test("returns null for text that is not an import failure", () => {
+    expect(parseImportFailure("not json")).toBeNull();
+    expect(parseImportFailure('{"job_id":"abc"}')).toBeNull();
+  });
+});

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/migration-import.ts

@@ -0,0 +1,31 @@
+/**
+ * Failure body of a `.vbundle` import from the assistant's migration routes:
+ * a structured validation report (`reason` plus per-file `errors`) or a plain
+ * `message`. Clients that restore bundles parse it to tell the owner which
+ * file failed instead of printing raw JSON.
+ */
+
+import { z } from "zod";
+
+export const importFailureSchema = z.object({
+  reason: z.string().optional(),
+  message: z.string().optional(),
+  errors: z
+    .array(z.object({ message: z.string(), path: z.string().optional() }))
+    .optional(),
+});
+
+export type ImportFailure = z.infer<typeof importFailureSchema>;
+
+/** Parse an import failure from JSON text, or null when the text is not one. */
+export function parseImportFailure(text: string): ImportFailure | null {
+  try {
+    const parsed = importFailureSchema.safeParse(JSON.parse(text));
+    return parsed.success &&
+      (parsed.data.reason || parsed.data.message || parsed.data.errors)
+      ? parsed.data
+      : null;
+  } catch {
+    return null;
+  }
+}

package/node_modules/@vellumai/service-contracts/package.json

@@ -29,6 +29,7 @@
     "./platform-credential": "./src/platform-credential.ts",
     "./plan-credit": "./src/plan-credit.ts",
     "./integration-categories": "./src/integration-categories.ts",
+    "./migration-import": "./src/migration-import.ts",
     "./mcp-oauth": "./src/mcp-oauth.ts"
   },
   "scripts": {

package/node_modules/@vellumai/service-contracts/src/__tests__/migration-import.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseImportFailure } from "../migration-import.js";
+
+describe("parseImportFailure", () => {
+  test("parses a validation report", () => {
+    const failure = parseImportFailure(
+      JSON.stringify({
+        success: false,
+        reason: "validation_failed",
+        errors: [
+          {
+            code: "entry_hash",
+            message: "Checksum mismatch",
+            path: "workspace/a.md",
+          },
+        ],
+      }),
+    );
+    expect(failure).toEqual({
+      reason: "validation_failed",
+      errors: [{ message: "Checksum mismatch", path: "workspace/a.md" }],
+    });
+  });
+
+  test("parses a plain message body", () => {
+    expect(parseImportFailure('{"message":"disk full"}')).toEqual({
+      message: "disk full",
+    });
+  });
+
+  test("returns null for text that is not an import failure", () => {
+    expect(parseImportFailure("not json")).toBeNull();
+    expect(parseImportFailure('{"job_id":"abc"}')).toBeNull();
+  });
+});

package/node_modules/@vellumai/service-contracts/src/migration-import.ts

@@ -0,0 +1,31 @@
+/**
+ * Failure body of a `.vbundle` import from the assistant's migration routes:
+ * a structured validation report (`reason` plus per-file `errors`) or a plain
+ * `message`. Clients that restore bundles parse it to tell the owner which
+ * file failed instead of printing raw JSON.
+ */
+
+import { z } from "zod";
+
+export const importFailureSchema = z.object({
+  reason: z.string().optional(),
+  message: z.string().optional(),
+  errors: z
+    .array(z.object({ message: z.string(), path: z.string().optional() }))
+    .optional(),
+});
+
+export type ImportFailure = z.infer<typeof importFailureSchema>;
+
+/** Parse an import failure from JSON text, or null when the text is not one. */
+export function parseImportFailure(text: string): ImportFailure | null {
+  try {
+    const parsed = importFailureSchema.safeParse(JSON.parse(text));
+    return parsed.success &&
+      (parsed.data.reason || parsed.data.message || parsed.data.errors)
+      ? parsed.data
+      : null;
+  } catch {
+    return null;
+  }
+}

package/package.json

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

package/src/__tests__/backup.test.ts

@@ -324,6 +324,7 @@ describe("vellum backup <platform-managed>: GCS happy path", () => {
         operation: "upload",
         minRuntimeVersion: "0.6.5",
         maxRuntimeVersion: null,
+        consumer: "runtime",
       }),
       "platform-token",
       "https://platform.vellum.ai",

package/src/__tests__/bundle-staging.test.ts

@@ -23,6 +23,7 @@ import { restoreBackup } from "../lib/backup-ops.js";
 import {
   bundleFileSizeBytes,
   formatBundleSizeMb,
+  importJobFailure,
   importStagedBundle,
   RESTORE_STAGING_DIRNAME,
   stageBundleForRestore,
@@ -44,7 +45,9 @@ function makeEntry(overrides: Partial<AssistantEntry> = {}): AssistantEntry {
 }
 
 let tmpRoot: string;
-let fetchSpy: ReturnType<typeof spyOn<typeof loopbackFetch, "loopbackSafeFetch">>;
+let fetchSpy: ReturnType<
+  typeof spyOn<typeof loopbackFetch, "loopbackSafeFetch">
+>;
 let execSpy: ReturnType<typeof spyOn<typeof stepRunner, "exec">>;
 
 beforeEach(() => {
@@ -98,12 +101,7 @@ describe("stageBundleForRestore", () => {
       hostBundle,
     );
 
-    const dest = join(
-      instanceDir,
-      ".vellum",
-      "workspace",
-      staged.relativePath,
-    );
+    const dest = join(instanceDir, ".vellum", "workspace", staged.relativePath);
     expect(staged.relativePath.startsWith(`${RESTORE_STAGING_DIRNAME}/`)).toBe(
       true,
     );
@@ -270,3 +268,40 @@ describe("bundle size helpers", () => {
     expect(bundleFileSizeBytes(join(tmpRoot, "missing.vbundle"))).toBe(0);
   });
 });
+
+describe("importJobFailure", () => {
+  test("restores a validation report recorded as the job error", () => {
+    const report = {
+      success: false,
+      reason: "validation_failed",
+      errors: [
+        {
+          code: "entry_hash",
+          message: "Checksum mismatch",
+          path: "workspace/data/monitoring/samples.jsonl",
+        },
+      ],
+    };
+    const failure = importJobFailure(JSON.stringify(report));
+    expect(failure.status).toBe(400);
+    expect(failure.body.reason).toBe("validation_failed");
+    expect(failure.body.errors).toEqual([
+      {
+        message: "Checksum mismatch",
+        path: "workspace/data/monitoring/samples.jsonl",
+      },
+    ]);
+  });
+
+  test("keeps a plain error message as a 500", () => {
+    const failure = importJobFailure("disk full");
+    expect(failure).toEqual({
+      status: 500,
+      body: { success: false, message: "disk full" },
+    });
+  });
+
+  test("reports a missing error as a generic failure", () => {
+    expect(importJobFailure(undefined).body.message).toBe("Import failed");
+  });
+});

package/src/commands/backup.ts

@@ -288,6 +288,10 @@ async function backupPlatform(
       operation: "upload",
       minRuntimeVersion: runtimeIdentity.version,
       maxRuntimeVersion: null,
+      // The managed pod PUTs the bundle. A runtime-consumer upload also
+      // registers the platform export record that Step 4's download URL
+      // request is checked against.
+      consumer: "runtime",
     },
     exportPlatformToken,
     platformUrl,

package/src/commands/restore.ts

@@ -10,6 +10,10 @@ import {
   stageBundleForRestore,
   stagingTargetFromEntry,
 } from "../lib/bundle-staging.js";
+import {
+  type ImportFailure,
+  parseImportFailure,
+} from "@vellumai/service-contracts/migration-import";
 import {
   loadGuardianToken,
   leaseGuardianToken,
@@ -161,6 +165,24 @@ interface PreflightResponse {
   conflicts?: StructuredError[];
 }
 
+const IMPORT_FAILURE_REASONS: Record<string, string> = {
+  validation_failed: "the backup file failed validation",
+  version_incompatible: "the backup needs a different assistant version",
+  extraction_failed: "the backup could not be unpacked",
+};
+
+function printImportFailure(failure: ImportFailure): void {
+  const reason = failure.reason
+    ? (IMPORT_FAILURE_REASONS[failure.reason] ?? failure.reason)
+    : undefined;
+  console.error(
+    `Error: Import failed: ${failure.message ?? reason ?? "unknown reason"}`,
+  );
+  for (const err of failure.errors ?? []) {
+    console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
+  }
+}
+
 interface ImportResponse {
   success: boolean;
   reason?: string;
@@ -480,12 +502,7 @@ async function restorePlatform(
   const result = importResult.body as unknown as ImportResponse;
 
   if (!result.success) {
-    console.error(
-      `Error: Import failed — ${result.message ?? result.reason ?? "unknown reason"}`,
-    );
-    for (const err of result.errors ?? []) {
-      console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
-    }
+    printImportFailure(result);
     process.exit(1);
   }
 
@@ -771,7 +788,12 @@ async function runLocalRestore(opts: {
           });
       if (!response.ok) {
         const body = await response.text();
-        console.error(`Error: Import failed (${response.status}): ${body}`);
+        const failure = parseImportFailure(body);
+        if (failure) {
+          printImportFailure(failure);
+        } else {
+          console.error(`Error: Import failed (${response.status}): ${body}`);
+        }
         process.exit(1);
       }
       result = (await response.json()) as ImportResponse;
@@ -792,12 +814,7 @@ async function runLocalRestore(opts: {
     }
 
     if (!result.success) {
-      console.error(
-        `Error: Import failed — ${result.message ?? result.reason ?? "unknown reason"}`,
-      );
-      for (const err of result.errors ?? []) {
-        console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
-      }
+      printImportFailure(result);
       process.exit(1);
     }
 

package/src/lib/bundle-staging.ts

@@ -1,13 +1,12 @@
 import { randomUUID } from "crypto";
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  statSync,
-  unlinkSync,
-} from "fs";
+import { copyFileSync, existsSync, mkdirSync, statSync, unlinkSync } from "fs";
 import { join } from "path";
 
+import {
+  type ImportFailure,
+  parseImportFailure,
+} from "@vellumai/service-contracts/migration-import";
+
 import type { AssistantEntry } from "./assistant-config.js";
 import { dockerResourceNames } from "./docker.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
@@ -156,6 +155,28 @@ export async function importStagedBundle(
   return response;
 }
 
+/**
+ * Decode a failed import job's error into the body and status the import
+ * route would have returned. The runtime records a validation failure as that
+ * JSON body, so a plain 500 would hide the per-file errors.
+ */
+export function importJobFailure(error: string | undefined): {
+  status: number;
+  body: ImportFailure & { success: false };
+} {
+  const report = error ? parseImportFailure(error) : null;
+  if (report?.reason) {
+    return {
+      status: report.reason === "validation_failed" ? 400 : 500,
+      body: { ...report, success: false },
+    };
+  }
+  return {
+    status: 500,
+    body: { success: false, message: error ?? "Import failed" },
+  };
+}
+
 async function pollImportJob(
   runtimeUrl: string,
   accessToken: string,
@@ -194,16 +215,16 @@ async function pollImportJob(
       });
     }
     if (job.status === "failed") {
-      return new Response(
-        JSON.stringify({
-          success: false,
-          message: job.error ?? "Import failed",
-        }),
-        { status: 500, headers: { "Content-Type": "application/json" } },
-      );
+      const failure = importJobFailure(job.error);
+      return new Response(JSON.stringify(failure.body), {
+        status: failure.status,
+        headers: { "Content-Type": "application/json" },
+      });
     }
 
-    await new Promise((resolve) => setTimeout(resolve, IMPORT_POLL_INTERVAL_MS));
+    await new Promise((resolve) =>
+      setTimeout(resolve, IMPORT_POLL_INTERVAL_MS),
+    );
   }
 
   return new Response(