@vellumai/assistant 0.6.3 → 0.6.4

package/src/runtime/migrations/__tests__/vbundle-legacy-user-md.test.ts

@@ -0,0 +1,360 @@
+/**
+ * Tests for legacy `prompts/USER.md` translation during vbundle import.
+ *
+ * Covers:
+ * - `DefaultPathResolver` translates `prompts/USER.md` to the current
+ *   guardian's `users/<slug>.md` path when a guardian exists.
+ * - Missing guardian → resolver returns null (commit skips with warn).
+ * - Full commit round-trip: legacy bundle writes content into
+ *   `users/<slug>.md` on a fresh workspace.
+ * - Missing guardian: commit skips the legacy entry with a warning
+ *   instead of crashing.
+ * - Already-customized `users/<slug>.md` is NOT overwritten.
+ * - Pristine scaffold `users/<slug>.md` (template only) IS overwritten.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { buildVBundle } from "../vbundle-builder.js";
+import {
+  analyzeImport,
+  DefaultPathResolver,
+} from "../vbundle-import-analyzer.js";
+import { commitImport } from "../vbundle-importer.js";
+
+// ---------------------------------------------------------------------------
+// Shared fixture: per-test workspace under VELLUM_WORKSPACE_DIR.
+// ---------------------------------------------------------------------------
+
+const WORKSPACE_ROOT = process.env.VELLUM_WORKSPACE_DIR!;
+const USERS_DIR = join(WORKSPACE_ROOT, "users");
+
+const LEGACY_USER_MD_CONTENT = `# User Profile
+
+- Preferred name/reference: Captain Legacy
+- Pronouns: they/them
+- Work role: Archivist
+- Hobbies/fun: Unearthing old bundles
+`;
+
+/**
+ * Bare scaffold template matching `GUARDIAN_PERSONA_TEMPLATE` in
+ * `persona-resolver.ts`. Duplicated here intentionally so the test
+ * pins the exact bytes that count as "not customized".
+ */
+const PRISTINE_SCAFFOLD = `_ Lines starting with _ are comments - they won't appear in the system prompt
+
+# User Profile
+
+Store details about your user here. Edit freely - build this over time as you learn about them. Don't be pushy about seeking details, but when you learn something, write it down. More context makes you more useful.
+
+- Preferred name/reference:
+- Pronouns:
+- Locale:
+- Work role:
+- Goals:
+- Hobbies/fun:
+- Daily tools:
+`;
+
+/**
+ * Customized guardian persona file — has user-authored content past the
+ * bare scaffold. Must survive an import unchanged.
+ */
+const CUSTOMIZED_PERSONA = `_ Lines starting with _ are comments - they won't appear in the system prompt
+
+# User Profile
+
+- Preferred name/reference: Real User
+- Pronouns: she/her
+- Locale: en-US
+- Work role: Staff Engineer
+- Goals: Ship drop-user-md
+- Hobbies/fun: Reading papers
+- Daily tools: Terminal, Vellum
+`;
+
+function cleanWorkspace() {
+  try {
+    rmSync(USERS_DIR, { recursive: true, force: true });
+  } catch {
+    /* best effort */
+  }
+  mkdirSync(USERS_DIR, { recursive: true });
+}
+
+beforeEach(() => {
+  cleanWorkspace();
+});
+
+afterEach(() => {
+  cleanWorkspace();
+});
+
+// ---------------------------------------------------------------------------
+// DefaultPathResolver — USER.md translation
+// ---------------------------------------------------------------------------
+
+describe("DefaultPathResolver prompts/USER.md translation", () => {
+  test("rewrites prompts/USER.md to the guardian's users/<slug>.md", () => {
+    const guardianPath = join(USERS_DIR, "captain.md");
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => guardianPath,
+    );
+
+    expect(resolver.resolve("prompts/USER.md")).toBe(guardianPath);
+  });
+
+  test("returns null when no guardian exists", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => null,
+    );
+
+    expect(resolver.resolve("prompts/USER.md")).toBeNull();
+  });
+
+  test("rejects guardian paths outside the workspace (traversal guard)", () => {
+    // Stubbed resolver returns a path outside the workspace — the
+    // analyzer resolver must reject it to prevent writing outside
+    // the workspace root.
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => "/etc/passwd",
+    );
+
+    expect(resolver.resolve("prompts/USER.md")).toBeNull();
+  });
+
+  test("still resolves other prompt files (IDENTITY.md) to workspace root", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => join(USERS_DIR, "captain.md"),
+    );
+
+    expect(resolver.resolve("prompts/IDENTITY.md")).toBe(
+      join(WORKSPACE_ROOT, "IDENTITY.md"),
+    );
+    expect(resolver.resolve("prompts/SOUL.md")).toBe(
+      join(WORKSPACE_ROOT, "SOUL.md"),
+    );
+    expect(resolver.resolve("prompts/UPDATES.md")).toBe(
+      join(WORKSPACE_ROOT, "UPDATES.md"),
+    );
+  });
+
+  test("skips unknown prompt filenames regardless of guardian state", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => join(USERS_DIR, "captain.md"),
+    );
+
+    expect(resolver.resolve("prompts/SECRET.md")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// analyzeImport — surfaces the translated destination for preflight
+// ---------------------------------------------------------------------------
+
+describe("analyzeImport for legacy prompts/USER.md", () => {
+  test("reports a `create` action on a fresh users/<slug>.md", () => {
+    const guardianPath = join(USERS_DIR, "captain.md");
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => guardianPath,
+    );
+
+    const { archive, manifest } = buildVBundle({
+      files: [
+        {
+          path: "prompts/USER.md",
+          data: new TextEncoder().encode(LEGACY_USER_MD_CONTENT),
+        },
+      ],
+    });
+    expect(archive.length).toBeGreaterThan(0);
+
+    const report = analyzeImport({ manifest, pathResolver: resolver });
+
+    expect(report.can_import).toBe(true);
+    expect(report.files).toHaveLength(1);
+    expect(report.files[0].path).toBe("prompts/USER.md");
+    expect(report.files[0].action).toBe("create");
+  });
+
+  test("non-blocking skip when no guardian is resolvable (can_import stays true)", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => null,
+    );
+
+    const { manifest } = buildVBundle({
+      files: [
+        {
+          path: "prompts/USER.md",
+          data: new TextEncoder().encode(LEGACY_USER_MD_CONTENT),
+        },
+      ],
+    });
+
+    const report = analyzeImport({ manifest, pathResolver: resolver });
+
+    // Guardian-less workspaces must not block preflight — the commit-time
+    // path warns and skips, so preflight mirrors that behavior.
+    expect(report.can_import).toBe(true);
+    expect(report.conflicts).toHaveLength(0);
+    expect(report.files[0].action).toBe("skip");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// commitImport — end-to-end legacy USER.md import
+// ---------------------------------------------------------------------------
+
+describe("commitImport for legacy prompts/USER.md", () => {
+  test("writes legacy USER.md content into users/<slug>.md", () => {
+    const slug = "captain.md";
+    const guardianPath = join(USERS_DIR, slug);
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => guardianPath,
+    );
+
+    const { archive } = buildVBundle({
+      files: [
+        {
+          path: "prompts/USER.md",
+          data: new TextEncoder().encode(LEGACY_USER_MD_CONTENT),
+        },
+      ],
+    });
+
+    const result = commitImport({ archiveData: archive, pathResolver: resolver });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.report.success).toBe(true);
+      expect(result.report.summary.files_created).toBe(1);
+      expect(result.report.summary.files_skipped).toBe(0);
+    }
+
+    expect(existsSync(guardianPath)).toBe(true);
+    expect(readFileSync(guardianPath, "utf-8")).toBe(LEGACY_USER_MD_CONTENT);
+  });
+
+  test("overwrites a pristine scaffold users/<slug>.md", () => {
+    const slug = "captain.md";
+    const guardianPath = join(USERS_DIR, slug);
+    writeFileSync(guardianPath, PRISTINE_SCAFFOLD, "utf-8");
+
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => guardianPath,
+    );
+
+    const { archive } = buildVBundle({
+      files: [
+        {
+          path: "prompts/USER.md",
+          data: new TextEncoder().encode(LEGACY_USER_MD_CONTENT),
+        },
+      ],
+    });
+
+    const result = commitImport({ archiveData: archive, pathResolver: resolver });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.report.summary.files_overwritten).toBe(1);
+      expect(result.report.summary.files_skipped).toBe(0);
+    }
+    expect(readFileSync(guardianPath, "utf-8")).toBe(LEGACY_USER_MD_CONTENT);
+  });
+
+  test("skips with a warning when no guardian exists (no crash)", () => {
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => null,
+    );
+
+    const { archive } = buildVBundle({
+      files: [
+        {
+          path: "prompts/USER.md",
+          data: new TextEncoder().encode(LEGACY_USER_MD_CONTENT),
+        },
+      ],
+    });
+
+    const result = commitImport({ archiveData: archive, pathResolver: resolver });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.report.summary.files_skipped).toBe(1);
+      expect(result.report.summary.files_created).toBe(0);
+      expect(
+        result.report.warnings.some((w) => w.includes("prompts/USER.md")),
+      ).toBe(true);
+    }
+
+    // No stray file was written anywhere in users/.
+    expect(existsSync(join(USERS_DIR, "USER.md"))).toBe(false);
+  });
+
+  test("does NOT overwrite a customized users/<slug>.md", () => {
+    const slug = "captain.md";
+    const guardianPath = join(USERS_DIR, slug);
+    writeFileSync(guardianPath, CUSTOMIZED_PERSONA, "utf-8");
+
+    const resolver = new DefaultPathResolver(
+      WORKSPACE_ROOT,
+      undefined,
+      () => guardianPath,
+    );
+
+    const { archive } = buildVBundle({
+      files: [
+        {
+          path: "prompts/USER.md",
+          data: new TextEncoder().encode(LEGACY_USER_MD_CONTENT),
+        },
+      ],
+    });
+
+    const result = commitImport({ archiveData: archive, pathResolver: resolver });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.report.summary.files_skipped).toBe(1);
+      expect(result.report.summary.files_overwritten).toBe(0);
+      expect(
+        result.report.warnings.some((w) =>
+          w.includes("guardian persona"),
+        ),
+      ).toBe(true);
+    }
+
+    // Existing customized content is preserved byte-for-byte.
+    expect(readFileSync(guardianPath, "utf-8")).toBe(CUSTOMIZED_PERSONA);
+  });
+});

package/src/runtime/migrations/migration-transport.ts

@@ -207,6 +207,7 @@ export interface ImportCommitSuccessResponse {
     succeeded: number;
     failed: number;
     failedAccounts: string[];
+    skippedPlatform?: number;
   };
 }
 

package/src/runtime/migrations/migration-wizard.ts

@@ -98,6 +98,7 @@ export interface MigrationWizardState {
     succeeded: number;
     failed: number;
     failedAccounts: string[];
+    skippedPlatform?: number;
   };
 
   /** Timestamp of last state change (ISO 8601). */

package/src/runtime/migrations/vbundle-import-analyzer.ts

@@ -17,9 +17,19 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 
+import { resolveGuardianPersonaPath } from "../../prompts/persona-resolver.js";
+import { getLogger } from "../../util/logger.js";
 import type { ManifestType } from "./vbundle-validator.js";
 
-/** Only these prompt filenames are accepted during import. */
+const log = getLogger("vbundle-import-analyzer");
+
+/**
+ * Only these prompt filenames are accepted during import.
+ *
+ * `USER.md` is retained for backward compatibility with legacy bundles —
+ * on import, its content is translated to `users/<slug>.md` at the
+ * current guardian's location (see `DefaultPathResolver.resolve`).
+ */
 const ALLOWED_PROMPT_FILENAMES = new Set([
   "IDENTITY.md",
   "SOUL.md",
@@ -27,6 +37,9 @@ const ALLOWED_PROMPT_FILENAMES = new Set([
   "UPDATES.md",
 ]);
 
+/** Archive path for the legacy guardian user persona file. */
+const LEGACY_USER_MD_ARCHIVE_PATH = "prompts/USER.md";
+
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
@@ -87,9 +100,19 @@ export interface PathResolver {
 }
 
 export class DefaultPathResolver implements PathResolver {
+  /**
+   * @param workspaceDir  absolute path to the workspace directory.
+   * @param hooksDir      absolute path to the hooks directory.
+   * @param guardianPersonaPathResolver  function that returns the
+   *   current guardian's persona path (`users/<slug>.md`) or `null`
+   *   when no guardian exists. Defaults to the production
+   *   `resolveGuardianPersonaPath` helper; tests inject a stub so they
+   *   don't need to mock the contact store.
+   */
   constructor(
     private workspaceDir?: string,
     private hooksDir?: string,
+    private guardianPersonaPathResolver: () => string | null = resolveGuardianPersonaPath,
   ) {}
 
   resolve(archivePath: string): string | null {
@@ -139,6 +162,38 @@ export class DefaultPathResolver implements PathResolver {
       if (!ALLOWED_PROMPT_FILENAMES.has(filename)) {
         return null;
       }
+
+      // Legacy USER.md translation: rewrite the destination to the
+      // current guardian's per-user persona file `users/<slug>.md`.
+      // Guardian-less workspaces return null → importer skips with a
+      // warning (see vbundle-importer.ts). This lookup runs against
+      // whatever DB state is live at the time of resolve — typically
+      // the pre-import workspace, which is the common upgrade case.
+      if (archivePath === LEGACY_USER_MD_ARCHIVE_PATH) {
+        const guardianPath = this.guardianPersonaPathResolver();
+        if (!guardianPath) {
+          log.warn(
+            { path: archivePath },
+            "Legacy prompts/USER.md has no guardian target — will be skipped on import",
+          );
+          return null;
+        }
+        // Containment check: guardian path must live under the workspace.
+        const wsRoot = resolve(this.workspaceDir);
+        const guardianResolved = resolve(guardianPath);
+        if (
+          guardianResolved !== wsRoot &&
+          !guardianResolved.startsWith(wsRoot + "/")
+        ) {
+          log.warn(
+            { path: archivePath, guardianPath },
+            "Guardian persona path falls outside workspace — refusing to write",
+          );
+          return null;
+        }
+        return guardianResolved;
+      }
+
       const resolved = resolve(this.workspaceDir, filename);
       const wsRoot = resolve(this.workspaceDir);
       if (resolved !== wsRoot && !resolved.startsWith(wsRoot + "/")) {
@@ -210,6 +265,27 @@ export function analyzeImport(
     }
 
     if (!diskPath) {
+      // Legacy `prompts/USER.md` in a guardian-less workspace has no
+      // destination to translate to. The commit-time path skips this
+      // entry with a warning rather than failing, so preflight mirrors
+      // that: emit a non-blocking skip so `can_import` stays true and
+      // upgrade paths proceed. No conflict is registered.
+      if (fileEntry.path === LEGACY_USER_MD_ARCHIVE_PATH) {
+        log.warn(
+          { path: fileEntry.path },
+          "Legacy prompts/USER.md has no guardian target — will be skipped on import",
+        );
+        files.push({
+          path: fileEntry.path,
+          action: "skip",
+          bundle_size: fileEntry.size,
+          bundle_sha256: fileEntry.sha256,
+          current_size: null,
+          current_sha256: null,
+        });
+        continue;
+      }
+
       // Unknown archive path — would have nowhere to write
       conflicts.push({
         code: "UNKNOWN_ARCHIVE_PATH",

package/src/runtime/migrations/vbundle-importer.ts

@@ -25,10 +25,17 @@ import {
 import { dirname, join } from "node:path";
 
 import { sanitizeConfigForTransfer } from "../../config/sanitize-for-transfer.js";
+import { isGuardianPersonaCustomized } from "../../prompts/persona-resolver.js";
+import { getLogger } from "../../util/logger.js";
 import type { PathResolver } from "./vbundle-import-analyzer.js";
 import type { ManifestType, VBundleTarEntry } from "./vbundle-validator.js";
 import { validateVBundle } from "./vbundle-validator.js";
 
+const log = getLogger("vbundle-importer");
+
+/** Archive path for the legacy guardian user persona file. */
+const LEGACY_USER_MD_ARCHIVE_PATH = "prompts/USER.md";
+
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
@@ -270,6 +277,33 @@ export function commitImport(options: ImportCommitOptions): ImportCommitResult {
       continue;
     }
 
+    // Legacy guardian persona (prompts/USER.md) is translated to the
+    // current guardian's users/<slug>.md by DefaultPathResolver. If
+    // that target already holds user-authored content, skip rather
+    // than clobber — the user has curated their persona since the
+    // bundle was exported.
+    if (
+      fileEntry.path === LEGACY_USER_MD_ARCHIVE_PATH &&
+      isGuardianPersonaCustomized(diskPath)
+    ) {
+      log.warn(
+        { archivePath: fileEntry.path, diskPath },
+        "Skipping legacy prompts/USER.md import: guardian persona is already customized",
+      );
+      warnings.push(
+        `Skipped "${fileEntry.path}": guardian persona at "${diskPath}" is already customized`,
+      );
+      importedFiles.push({
+        path: fileEntry.path,
+        disk_path: diskPath,
+        action: "skipped",
+        size: fileEntry.size,
+        sha256: fileEntry.sha256,
+        backup_path: null,
+      });
+      continue;
+    }
+
     // Determine action and create backup if needed
     let backupPath: string | null = null;
     let action: ImportFileAction;

package/src/runtime/pending-interactions.ts

@@ -52,17 +52,6 @@ export interface PendingInteraction {
   confirmationDetails?: ConfirmationDetails;
   /** For ACP permissions: resolves directly without a Conversation object. */
   directResolve?: (decision: UserDecision) => void;
-  /**
-   * For host_browser interactions originating outside an agent loop
-   * (e.g. the `assistant browser chrome relay` CLI shim that POSTs to
-   * /v1/browser-cdp). Resolves the CDP round-trip directly without
-   * touching a Conversation. When set, /v1/host-browser-result invokes
-   * this instead of `interaction.conversation.resolveHostBrowser`.
-   */
-  directBrowserResolve?: (response: {
-    content: string;
-    isError: boolean;
-  }) => void;
 }
 
 const pending = new Map<string, PendingInteraction>();