@vellumai/assistant 0.6.3 → 0.6.4

package/src/__tests__/tool-executor-lifecycle-events.test.ts

@@ -72,8 +72,12 @@ mock.module("../permissions/checker.js", () => ({
   generateScopeOptions: () => [{ label: "/tmp", scope: "/tmp" }],
 }));
 
+// Mock every export so downstream test files that dynamically import modules
+// with a static `from "../memory/tool-usage-store.js"` still see all symbols.
 mock.module("../memory/tool-usage-store.js", () => ({
   recordToolInvocation: () => {},
+  getRecentInvocations: () => [],
+  rotateToolInvocations: () => 0,
 }));
 
 mock.module("../tools/registry.js", () => ({
@@ -621,11 +625,11 @@ describe("ToolExecutor lifecycle events", () => {
     expect(events.map((e) => e.type)).toEqual(["start", "executed"]);
   });
 
-  test("file_edit to USER.md emits permission_prompt under forcePromptSideEffects", async () => {
-    // Security invariant: editing USER.md in a private thread must always
-    // prompt, even when a trust rule would auto-allow.
+  test("file_edit to guardian persona emits permission_prompt under forcePromptSideEffects", async () => {
+    // Security invariant: editing the guardian persona file in a private
+    // thread must always prompt, even when a trust rule would auto-allow.
     checkerDecision = "allow";
-    checkerReason = "Matched trust rule: file_edit:*/USER.md";
+    checkerReason = "Matched trust rule: file_edit:*/users/*.md";
     checkerRisk = "low";
     promptDecision = "allow";
 
@@ -635,7 +639,7 @@ describe("ToolExecutor lifecycle events", () => {
     const result = await executor.execute(
       "file_edit",
       {
-        path: "/Users/sidd/.vellum/workspace/USER.md",
+        path: "/Users/sidd/.vellum/workspace/users/sidd.md",
         old_string: "old",
         new_string: "new",
       },

package/src/__tests__/tool-executor-shell-integration.test.ts

@@ -92,8 +92,12 @@ mock.module("../permissions/trust-store.js", () => ({
 }));
 
 // ── Tool usage store ──
+// Mock every export so downstream test files that dynamically import modules
+// with a static `from "../memory/tool-usage-store.js"` still see all symbols.
 mock.module("../memory/tool-usage-store.js", () => ({
   recordToolInvocation: () => {},
+  getRecentInvocations: () => [],
+  rotateToolInvocations: () => 0,
 }));
 
 // ── Path policy ──

package/src/__tests__/tool-executor.test.ts

@@ -129,8 +129,12 @@ mock.module("../permissions/checker.js", () => ({
     scopeOptionsOverride ?? [{ label: "/tmp", scope: "/tmp" }],
 }));
 
+// Mock every export so downstream test files that dynamically import modules
+// with a static `from "../memory/tool-usage-store.js"` still see all symbols.
 mock.module("../memory/tool-usage-store.js", () => ({
   recordToolInvocation: () => {},
+  getRecentInvocations: () => [],
+  rotateToolInvocations: () => 0,
 }));
 
 mock.module("../tools/registry.js", () => ({
@@ -1148,6 +1152,8 @@ describe("isSideEffectTool", () => {
       "browser_type",
       "browser_press_key",
       "browser_close",
+      "browser_attach",
+      "browser_detach",
       "browser_fill_credential",
       "document_create",
       "document_update",
@@ -1220,12 +1226,13 @@ describe("isSideEffectTool", () => {
   });
 });
 
-// Baseline: allow rules can auto-allow file_edit for USER.md today (no forced prompting).
-// The mock check() delegates to findHighestPriorityRule (via spy) so a regression
-// in trust-rule matching would cause this test to fail instead of being masked by
-// a blanket mock-allow.
-describe("ToolExecutor baseline: allow rule auto-allows file_edit USER.md", () => {
-  const userMdPath = "/Users/sidd/.vellum/workspace/USER.md";
+// Baseline: allow rules can auto-allow file_edit for the guardian persona
+// today (no forced prompting). The mock check() delegates to
+// findHighestPriorityRule (via spy) so a regression in trust-rule matching
+// would cause this test to fail instead of being masked by a blanket
+// mock-allow.
+describe("ToolExecutor baseline: allow rule auto-allows file_edit guardian persona", () => {
+  const guardianPersonaPath = "/Users/sidd/.vellum/workspace/users/sidd.md";
   let ruleSpy: ReturnType<typeof spyOn> | undefined;
 
   beforeEach(() => {
@@ -1239,18 +1246,19 @@ describe("ToolExecutor baseline: allow rule auto-allows file_edit USER.md", () =
       addRuleSpy = undefined;
     }
 
-    // Simulate a trust rule that allows file_edit on USER.md by stubbing
-    // findHighestPriorityRule. This mirrors the default allow rules that
-    // the trust-store creates for workspace prompt files.
+    // Simulate a trust rule that allows file_edit on the guardian's per-user
+    // persona file by stubbing findHighestPriorityRule. This mirrors the
+    // default allow rules that the trust-store creates for the guardian
+    // persona file (see permissions/defaults.ts).
     ruleSpy = spyOn(trustStore, "findHighestPriorityRule").mockImplementation(
       (tool: string, commands: string[], _scope: string) => {
         if (tool !== "file_edit") return null;
         for (const cmd of commands) {
-          if (cmd === `file_edit:${userMdPath}`) {
+          if (cmd === `file_edit:${guardianPersonaPath}`) {
             return {
-              id: "default:allow-file_edit-user",
+              id: "default:allow-file_edit-guardian-persona",
               tool: "file_edit",
-              pattern: `file_edit:${userMdPath}`,
+              pattern: `file_edit:${guardianPersonaPath}`,
               scope: "everywhere",
               decision: "allow" as const,
               priority: 100,
@@ -1294,11 +1302,11 @@ describe("ToolExecutor baseline: allow rule auto-allows file_edit USER.md", () =
     }
   });
 
-  test("file_edit to USER.md is auto-allowed via trust rule", async () => {
+  test("file_edit to guardian persona is auto-allowed via trust rule", async () => {
     const executor = new ToolExecutor(makePrompter());
     const result = await executor.execute(
       "file_edit",
-      { path: userMdPath, content: "hello" },
+      { path: guardianPersonaPath, content: "hello" },
       makeContext(),
     );
     expect(result.isError).toBe(false);
@@ -1310,7 +1318,7 @@ describe("ToolExecutor baseline: allow rule auto-allows file_edit USER.md", () =
     expect(ruleSpy).toHaveBeenCalled();
   });
 
-  test("file_edit to a non-USER.md path is NOT auto-allowed without a matching rule", async () => {
+  test("file_edit to a non-guardian-persona path is NOT auto-allowed without a matching rule", async () => {
     let promptCalled = false;
     const trackingPrompter = {
       prompt: async () => {
@@ -1530,22 +1538,23 @@ describe("ToolExecutor forcePromptSideEffects enforcement", () => {
     expect(promptCount).toBe(1);
   });
 
-  // ── USER.md security invariant (PR 31) ──────────
+  // ── Guardian persona security invariant (PR 31) ──────────
 
-  test("file_edit to USER.md forces prompt in private conversation even with matching trust rule", async () => {
-    // This is a key security invariant: USER.md contains the user's persistent
-    // memory. In a private conversation (forcePromptSideEffects=true), edits to it
-    // must always require explicit approval, even when a trust rule matches.
+  test("file_edit to guardian persona forces prompt in private conversation even with matching trust rule", async () => {
+    // This is a key security invariant: the guardian persona file contains
+    // the user's persistent memory. In a private conversation
+    // (forcePromptSideEffects=true), edits to it must always require explicit
+    // approval, even when a trust rule matches.
     checkResultOverride = {
       decision: "allow",
-      reason: "Matched trust rule: file_edit:*/USER.md",
+      reason: "Matched trust rule: file_edit:*/users/*.md",
     };
 
     const executor = new ToolExecutor(makeTrackingPrompter());
     const result = await executor.execute(
       "file_edit",
       {
-        path: "/Users/sidd/.vellum/workspace/USER.md",
+        path: "/Users/sidd/.vellum/workspace/users/sidd.md",
         old_string: "old pref",
         new_string: "new pref",
       },
@@ -1557,14 +1566,14 @@ describe("ToolExecutor forcePromptSideEffects enforcement", () => {
     expect(promptCalled).toBe(true);
   });
 
-  test("host_file_edit to USER.md forces prompt in private conversation", async () => {
+  test("host_file_edit to guardian persona forces prompt in private conversation", async () => {
     checkResultOverride = { decision: "allow", reason: "Matched trust rule" };
 
     const executor = new ToolExecutor(makeTrackingPrompter());
     const result = await executor.execute(
       "host_file_edit",
       {
-        path: "/Users/sidd/.vellum/workspace/USER.md",
+        path: "/Users/sidd/.vellum/workspace/users/sidd.md",
         old_string: "x",
         new_string: "y",
       },

package/src/__tests__/tool-result-truncation.test.ts

@@ -11,6 +11,20 @@ import {
 } from "../context/tool-result-truncation.js";
 import type { ContentBlock, ToolResultContent } from "../providers/types.js";
 
+function hasOrphanedSurrogate(str: string): boolean {
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = i + 1 < str.length ? str.charCodeAt(i + 1) : 0;
+      if (next < 0xdc00 || next > 0xdfff) return true;
+      i++;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -100,6 +114,28 @@ describe("truncateToolResultText", () => {
     expect(result).toBe(text);
     expect(result).not.toContain(TRUNCATION_SUFFIX);
   });
+
+  test("does not orphan a UTF-16 surrogate pair at the cut boundary", () => {
+    // Regression for the "no low surrogate in string" Anthropic 400 error.
+    // Build a string where the cut point lands inside a surrogate pair:
+    // 4999 padding chars, then an emoji (2 code units), then enough filler
+    // to push the cut inside the pair.
+    const EMOJI = "\uD83C\uDF89";
+    // maxChars = 5_000, so cutPoint = 5_000 - TRUNCATION_SUFFIX.length.
+    // Put the emoji so its high surrogate lands exactly at cutPoint - 1.
+    const maxChars = 5_000;
+    const cutPoint = maxChars - TRUNCATION_SUFFIX.length;
+    // Fill up to cutPoint - 1 with "a"s, then place the emoji so the high
+    // surrogate is the character at cutPoint - 1 and the low is at cutPoint.
+    const prefix = "a".repeat(cutPoint - 1);
+    const text = prefix + EMOJI + "b".repeat(100);
+    // Use a long filler with no newlines so lastIndexOf("\n", cutPoint) === -1
+    // and the function falls back to cutPoint itself.
+    const result = truncateToolResultText(text, maxChars);
+    expect(hasOrphanedSurrogate(result)).toBe(false);
+    // JSON.stringify must not throw on the result.
+    expect(() => JSON.stringify(result)).not.toThrow();
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/__tests__/trust-store.test.ts

@@ -740,8 +740,10 @@ describe("Trust Store", () => {
       ].sort();
       expect(defaultTools).toEqual([
         "bash",
+        "browser_attach",
         "browser_click",
         "browser_close",
+        "browser_detach",
         "browser_extract",
         "browser_fill_credential",
         "browser_hover",
@@ -751,6 +753,7 @@ describe("Trust Store", () => {
         "browser_scroll",
         "browser_select_option",
         "browser_snapshot",
+        "browser_status",
         "browser_type",
         "browser_wait_for",
         "browser_wait_for_download",
@@ -1078,13 +1081,15 @@ describe("Trust Store", () => {
 
     // ── default allow: browser tools ────────────────────────────
 
-    test("all 14 browser tools have default allow rules", () => {
+    test("all browser tools have default allow rules", () => {
       const templates = getDefaultRuleTemplates();
       const browserTools = [
         "browser_navigate",
         "browser_snapshot",
         "browser_screenshot",
         "browser_close",
+        "browser_attach",
+        "browser_detach",
         "browser_click",
         "browser_type",
         "browser_press_key",
@@ -1095,6 +1100,7 @@ describe("Trust Store", () => {
         "browser_extract",
         "browser_wait_for_download",
         "browser_fill_credential",
+        "browser_status",
       ];
 
       for (const tool of browserTools) {

package/src/__tests__/trusted-contact-approval-notifier.test.ts

@@ -117,7 +117,7 @@ mock.module("../prompts/user-reference.js", () => ({
   ...realUserReference,
   resolveUserReference: () => "my human",
   resolveGuardianName: (guardianDisplayName?: string | null): string => {
-    // Mirror the real implementation: USER.md name > guardianDisplayName > default
+    // Mirror the real implementation: guardian persona name (from users/<slug>.md) > guardianDisplayName > default
     const userRef = "my human"; // In tests, resolveUserReference() returns this
     if (userRef !== "my human") return userRef;
     if (guardianDisplayName && guardianDisplayName.trim().length > 0) {

package/src/__tests__/tts-catalog-parity.test.ts

@@ -0,0 +1,345 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  getCatalogProvider,
+  listCatalogProviderIds,
+} from "../tts/provider-catalog.js";
+import type { TtsProviderId } from "../tts/types.js";
+
+/**
+ * Parity guard: daemon TTS provider catalog vs client TTS catalog JSON.
+ *
+ * The daemon maintains its canonical provider catalog in
+ * `assistant/src/tts/provider-catalog.ts`.
+ * The client-facing metadata lives in `meta/tts-provider-catalog.json` and is
+ * bundled into native clients at build time.
+ *
+ * These tests enforce that both catalogs stay in sync on the fields they
+ * share: provider IDs, ordering, and credential metadata needed for client
+ * key handling. CI will fail when they drift, forcing the developer to update
+ * whichever side fell behind.
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve repo root (tests run from assistant/) */
+function getRepoRoot(): string {
+  return join(process.cwd(), "..");
+}
+
+interface ClientCatalogCredentialsGuide {
+  description: string;
+  url: string;
+  linkLabel: string;
+}
+
+interface ClientCatalogEntry {
+  id: string;
+  displayName: string;
+  subtitle: string;
+  setupMode: string;
+  setupHint: string;
+  credentialMode: "api-key" | "credential";
+  /** Present when credentialMode is "api-key". */
+  apiKeyProviderName?: string;
+  /** Present when credentialMode is "credential". */
+  credentialNamespace?: string;
+  credentialsGuide: ClientCatalogCredentialsGuide;
+}
+
+interface ClientCatalog {
+  version: number;
+  providers: ClientCatalogEntry[];
+}
+
+function loadClientCatalog(): ClientCatalog {
+  const catalogPath = join(getRepoRoot(), "meta", "tts-provider-catalog.json");
+  const raw = readFileSync(catalogPath, "utf-8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Derive the expected credentialMode and associated metadata from a daemon
+ * catalog entry's secret requirements.
+ *
+ * Convention:
+ * - If the first secretRequirement.credentialStoreKey starts with "credential/",
+ *   the client uses credentialMode "credential" and credentialNamespace is the
+ *   second path segment.
+ * - Otherwise, the client uses credentialMode "api-key" and apiKeyProviderName
+ *   is the bare key.
+ */
+function deriveCredentialMetadata(daemonEntry: {
+  secretRequirements: readonly { readonly credentialStoreKey: string }[];
+}): {
+  credentialMode: "api-key" | "credential";
+  apiKeyProviderName?: string;
+  credentialNamespace?: string;
+} {
+  const key = daemonEntry.secretRequirements[0]?.credentialStoreKey ?? "";
+  if (key.startsWith("credential/")) {
+    const parts = key.split("/");
+    return { credentialMode: "credential", credentialNamespace: parts[1] };
+  }
+  return { credentialMode: "api-key", apiKeyProviderName: key };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("TTS catalog parity: daemon vs client", () => {
+  // -----------------------------------------------------------------------
+  // Provider ID parity
+  // -----------------------------------------------------------------------
+
+  test("client catalog provider IDs match daemon catalog provider IDs", () => {
+    const daemonIds = listCatalogProviderIds();
+    const clientCatalog = loadClientCatalog();
+    const clientIds = clientCatalog.providers.map((p) => p.id);
+
+    // Every daemon provider ID must appear in the client catalog
+    const missingInClient = daemonIds.filter((id) => !clientIds.includes(id));
+    if (missingInClient.length > 0) {
+      const message = [
+        "Daemon catalog has provider IDs not present in meta/tts-provider-catalog.json.",
+        "",
+        "Missing in client catalog:",
+        ...missingInClient.map((id) => `  - ${id}`),
+        "",
+        "Add entries for these providers to meta/tts-provider-catalog.json.",
+      ].join("\n");
+      expect(missingInClient, message).toEqual([]);
+    }
+
+    // Every client catalog provider ID must appear in the daemon catalog
+    const missingInDaemon = clientIds.filter(
+      (id) => !daemonIds.includes(id as never),
+    );
+    if (missingInDaemon.length > 0) {
+      const message = [
+        "Client catalog (meta/tts-provider-catalog.json) has provider IDs not present in daemon catalog.",
+        "",
+        "Missing in daemon catalog:",
+        ...missingInDaemon.map((id) => `  - ${id}`),
+        "",
+        "Add entries for these providers to assistant/src/tts/provider-catalog.ts.",
+      ].join("\n");
+      expect(missingInDaemon, message).toEqual([]);
+    }
+  });
+
+  test("daemon and client catalog list providers in the same order", () => {
+    const daemonIds = listCatalogProviderIds();
+    const clientCatalog = loadClientCatalog();
+    const clientIds = clientCatalog.providers.map((p) => p.id);
+
+    expect(clientIds).toEqual([...daemonIds]);
+  });
+
+  // -----------------------------------------------------------------------
+  // Credential metadata parity
+  // -----------------------------------------------------------------------
+
+  test("each client catalog entry credentialMode matches its daemon counterpart", () => {
+    const clientCatalog = loadClientCatalog();
+    const violations: string[] = [];
+
+    for (const clientEntry of clientCatalog.providers) {
+      try {
+        const daemonEntry = getCatalogProvider(clientEntry.id as TtsProviderId);
+        const expected = deriveCredentialMetadata(daemonEntry);
+        if (clientEntry.credentialMode !== expected.credentialMode) {
+          violations.push(
+            `Provider "${clientEntry.id}": client credentialMode="${clientEntry.credentialMode}" ` +
+              `!= expected "${expected.credentialMode}" (derived from daemon credentialStoreKey)`,
+          );
+        }
+      } catch {
+        // Unknown ID — covered by the provider ID parity test above.
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "Credential mode mismatch between daemon and client TTS catalogs.",
+        "",
+        "Violations:",
+        ...violations.map((v) => `  - ${v}`),
+        "",
+        "Update meta/tts-provider-catalog.json or assistant/src/tts/provider-catalog.ts to match.",
+      ].join("\n");
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  test("api-key providers: client apiKeyProviderName matches daemon credentialStoreKey", () => {
+    const clientCatalog = loadClientCatalog();
+    const violations: string[] = [];
+
+    for (const clientEntry of clientCatalog.providers) {
+      if (clientEntry.credentialMode !== "api-key") continue;
+
+      try {
+        const daemonEntry = getCatalogProvider(clientEntry.id as TtsProviderId);
+        const expected = deriveCredentialMetadata(daemonEntry);
+        if (clientEntry.apiKeyProviderName !== expected.apiKeyProviderName) {
+          violations.push(
+            `Provider "${clientEntry.id}": client apiKeyProviderName="${clientEntry.apiKeyProviderName}" ` +
+              `!= expected "${expected.apiKeyProviderName}" (derived from daemon credentialStoreKey)`,
+          );
+        }
+      } catch {
+        // Unknown ID — covered by the provider ID parity test above.
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "apiKeyProviderName mismatch between daemon and client TTS catalogs.",
+        "",
+        "Violations:",
+        ...violations.map((v) => `  - ${v}`),
+        "",
+        "Update meta/tts-provider-catalog.json or assistant/src/tts/provider-catalog.ts to match.",
+      ].join("\n");
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  test("credential providers: client credentialNamespace matches daemon credentialStoreKey namespace", () => {
+    const clientCatalog = loadClientCatalog();
+    const violations: string[] = [];
+
+    for (const clientEntry of clientCatalog.providers) {
+      if (clientEntry.credentialMode !== "credential") continue;
+
+      try {
+        const daemonEntry = getCatalogProvider(clientEntry.id as TtsProviderId);
+        const expected = deriveCredentialMetadata(daemonEntry);
+        if (clientEntry.credentialNamespace !== expected.credentialNamespace) {
+          violations.push(
+            `Provider "${clientEntry.id}": client credentialNamespace="${clientEntry.credentialNamespace}" ` +
+              `!= expected "${expected.credentialNamespace}" (derived from daemon credentialStoreKey)`,
+          );
+        }
+      } catch {
+        // Unknown ID — covered by the provider ID parity test above.
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "credentialNamespace mismatch between daemon and client TTS catalogs.",
+        "",
+        "Violations:",
+        ...violations.map((v) => `  - ${v}`),
+        "",
+        "Update meta/tts-provider-catalog.json or assistant/src/tts/provider-catalog.ts to match.",
+      ].join("\n");
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // Display name parity
+  // -----------------------------------------------------------------------
+
+  test("each client catalog entry displayName matches its daemon counterpart", () => {
+    const clientCatalog = loadClientCatalog();
+    const violations: string[] = [];
+
+    for (const clientEntry of clientCatalog.providers) {
+      try {
+        const daemonEntry = getCatalogProvider(clientEntry.id as TtsProviderId);
+        if (clientEntry.displayName !== daemonEntry.displayName) {
+          violations.push(
+            `Provider "${clientEntry.id}": client displayName="${clientEntry.displayName}" ` +
+              `!= daemon displayName="${daemonEntry.displayName}"`,
+          );
+        }
+      } catch {
+        // Unknown ID — covered by the provider ID parity test above.
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "Display name mismatch between daemon and client TTS catalogs.",
+        "",
+        "Violations:",
+        ...violations.map((v) => `  - ${v}`),
+        "",
+        "Update meta/tts-provider-catalog.json or assistant/src/tts/provider-catalog.ts to match.",
+      ].join("\n");
+      expect(violations, message).toEqual([]);
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // Structural sanity
+  // -----------------------------------------------------------------------
+
+  test("client catalog JSON has a version field", () => {
+    const clientCatalog = loadClientCatalog();
+    expect(typeof clientCatalog.version).toBe("number");
+    expect(clientCatalog.version).toBeGreaterThanOrEqual(1);
+  });
+
+  test("client catalog has at least one provider", () => {
+    const clientCatalog = loadClientCatalog();
+    expect(clientCatalog.providers.length).toBeGreaterThan(0);
+  });
+
+  test("every client catalog entry has required fields", () => {
+    const clientCatalog = loadClientCatalog();
+    const violations: string[] = [];
+
+    for (const entry of clientCatalog.providers) {
+      if (!entry.id || typeof entry.id !== "string") {
+        violations.push(`Entry missing or invalid 'id'`);
+      }
+      if (!entry.displayName || typeof entry.displayName !== "string") {
+        violations.push(`${entry.id}: missing or invalid 'displayName'`);
+      }
+      if (!entry.setupMode || typeof entry.setupMode !== "string") {
+        violations.push(`${entry.id}: missing or invalid 'setupMode'`);
+      }
+      if (
+        !entry.credentialMode ||
+        !["api-key", "credential"].includes(entry.credentialMode)
+      ) {
+        violations.push(
+          `${entry.id}: missing or invalid 'credentialMode' (expected "api-key" or "credential")`,
+        );
+      }
+      if (entry.credentialMode === "api-key" && !entry.apiKeyProviderName) {
+        violations.push(
+          `${entry.id}: credentialMode is "api-key" but apiKeyProviderName is missing`,
+        );
+      }
+      if (entry.credentialMode === "credential" && !entry.credentialNamespace) {
+        violations.push(
+          `${entry.id}: credentialMode is "credential" but credentialNamespace is missing`,
+        );
+      }
+      if (!entry.credentialsGuide || !entry.credentialsGuide.url) {
+        violations.push(`${entry.id}: missing or invalid 'credentialsGuide'`);
+      }
+    }
+
+    if (violations.length > 0) {
+      const message = [
+        "Client catalog entries have missing or invalid required fields.",
+        "",
+        "Violations:",
+        ...violations.map((v) => `  - ${v}`),
+      ].join("\n");
+      expect(violations, message).toEqual([]);
+    }
+  });
+});