@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/tools/network/web-search.ts

@@ -6,6 +6,7 @@ import type {
 import { RiskLevel } from "../../permissions/types.js";
 import { getProviderKeyAsync } from "../../security/secure-keys.js";
 import { wrapUntrustedContent } from "../../security/untrusted-content.js";
+import { isAbortReason } from "../../util/abort-reasons.js";
 import { faviconUrlForDomain } from "../../util/favicon.js";
 import { getLogger } from "../../util/logger.js";
 import {
@@ -22,6 +23,11 @@ import type {
 } from "../types.js";
 import { extractDomain } from "./domain-normalize.js";
 import type { ManagedSearchProxyResult } from "./managed-search-proxy.js";
+import {
+  classifyWebSearchFailure,
+  logWebSearchBackendFailure,
+  WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+} from "./web-search-error.js";
 
 const log = getLogger("web-search");
 
@@ -381,6 +387,115 @@ function errorResult(
   };
 }
 
+/**
+ * Wrap an already-read provider response body so {@link backendFailureResult}
+ * forwards it into the classifier's internal-only `rawDetail` (telemetry). The
+ * classifier reads `error.message`; `buildRawDetail` truncates to ≤500 chars.
+ * Returns `undefined` for an empty body so we don't pad `rawDetail` with noise.
+ * The body must NEVER reach user-facing `content`/`errorMessage`.
+ */
+function rawBodyDetail(body: unknown): { message: string } | undefined {
+  if (body == null) return undefined;
+  const text =
+    typeof body === "string" ? body : safeStringifyBody(body);
+  const trimmed = text.trim();
+  return trimmed ? { message: trimmed } : undefined;
+}
+
+function safeStringifyBody(body: unknown): string {
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return String(body);
+  }
+}
+
+/**
+ * Build a {@link ToolExecutionResult} for a genuine backend/transport failure
+ * (5xx, post-retry rate-limit, thrown network/timeout error). Routes the raw
+ * detail through {@link classifyWebSearchFailure}: when it is a backend failure
+ * we surface the friendly recoverable copy (the bare sentence so the model
+ * reads it as guidance — retry / continue-without-search / paste-details —
+ * rather than fabricating) in both the model-facing `content` and the client
+ * `errorMessage`, and log the raw detail via telemetry. Non-backend categories
+ * (e.g. an unexpected 4xx) fall back to {@link errorResult} with `fallback`.
+ *
+ * Raw provider JSON / status text must never reach `content` or `errorMessage`;
+ * only `rawDetail` (internal-only) captures it for the log.
+ */
+function backendFailureResult(
+  query: string,
+  provider: WebSearchProvider,
+  startedAt: number,
+  raw: { error?: unknown; statusCode?: number; errorCode?: string },
+  fallback: string,
+): ToolExecutionResult {
+  const classification = classifyWebSearchFailure({
+    isError: true,
+    error: raw.error,
+    statusCode: raw.statusCode,
+    errorCode: raw.errorCode,
+  });
+
+  if (!classification.isBackendFailure) {
+    return errorResult(query, provider, startedAt, fallback);
+  }
+
+  logWebSearchBackendFailure(log, {
+    provider,
+    errorCategory: classification.category,
+    rawDetail: classification.rawDetail,
+    fallbackShown: true,
+    queryLength: query.length,
+  });
+
+  return {
+    content: WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+    isError: true,
+    activityMetadata: {
+      webSearch: {
+        query,
+        provider,
+        resultCount: 0,
+        durationMs: Date.now() - startedAt,
+        results: [],
+        errorMessage: WEB_SEARCH_BACKEND_FAILURE_MESSAGE,
+      },
+    },
+  };
+}
+
+/**
+ * Route a thrown fetch error (network/timeout) through {@link backendFailureResult}
+ * as a `backend_unavailable` candidate, falling back to a `Web search failed: …`
+ * error for non-backend throws (e.g. a JSON parse error).
+ *
+ * If the caller aborted the request (`signal.aborted` — the user hit Stop/Esc,
+ * or an external caller cancelled), the thrown error is re-thrown so the
+ * executor's existing cancellation handling takes over. A user-cancel must NOT
+ * surface the friendly backend copy or emit `web_search_backend_failure`
+ * telemetry. Internal fetch timeouts (where the caller's signal is not aborted)
+ * still route to the friendly backend result.
+ */
+function networkFailureResult(
+  query: string,
+  provider: WebSearchProvider,
+  startedAt: number,
+  err: unknown,
+  signal?: AbortSignal,
+): ToolExecutionResult {
+  if (signal?.aborted || isAbortReason((err as { reason?: unknown })?.reason)) {
+    throw err;
+  }
+  return backendFailureResult(
+    query,
+    provider,
+    startedAt,
+    { error: err },
+    `Web search failed: ${err instanceof Error ? err.message : String(err)}`,
+  );
+}
+
 async function executeBraveSearch(
   query: string,
   count: number,
@@ -396,21 +511,26 @@ async function executeBraveSearch(
   const startedAt = Date.now();
 
   for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
-    const response = await fetch(url, {
-      headers: {
-        Accept: "application/json",
-        "Accept-Encoding": "gzip",
-        "X-Subscription-Token": apiKey,
-      },
-      signal,
-    });
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          Accept: "application/json",
+          "Accept-Encoding": "gzip",
+          "X-Subscription-Token": apiKey,
+        },
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "brave", startedAt, err, signal);
+    }
 
     if (response.ok) {
       const data = (await response.json()) as BraveSearchResponse;
       return successfulBraveResult(data, query, startedAt);
     }
 
-    await response.text();
+    const bodyText = await response.text();
 
     if (response.status === 401 || response.status === 403) {
       return errorResult(
@@ -436,20 +556,22 @@ async function executeBraveSearch(
     }
 
     log.warn({ status: response.status }, "Brave Search API error");
-    return errorResult(
+    return backendFailureResult(
       query,
       "brave",
       startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
       response.status === 429
         ? "Brave Search rate limit exceeded after retries. Try again shortly."
         : `Brave Search API returned status ${response.status}`,
     );
   }
 
-  return errorResult(
+  return backendFailureResult(
     query,
     "brave",
     startedAt,
+    { statusCode: 429 },
     "Brave Search rate limit exceeded after retries. Try again shortly.",
   );
 }
@@ -478,6 +600,23 @@ async function executeManagedBraveSearch(
   );
 
   if (!proxyResult.ok) {
+    // Keep billing/auth/unavailable mapping as specific copy; route genuine
+    // platform 5xx (transport-level failures) to the friendly backend helper.
+    if (
+      proxyResult.kind === "platform-error" &&
+      proxyResult.status >= 500
+    ) {
+      return backendFailureResult(
+        query,
+        "brave",
+        startedAt,
+        {
+          statusCode: proxyResult.status,
+          error: rawBodyDetail(proxyResult.body),
+        },
+        managedSearchProxyErrorMessage(proxyResult),
+      );
+    }
     return errorResult(
       query,
       "brave",
@@ -503,12 +642,18 @@ async function executeManagedBraveSearch(
     );
   }
 
-  if (proxyResult.status === 429) {
-    return errorResult(
+  if (proxyResult.status === 429 || proxyResult.status >= 500) {
+    return backendFailureResult(
       query,
       "brave",
       startedAt,
-      "Managed Brave Search rate limit exceeded. Try again shortly.",
+      {
+        statusCode: proxyResult.status,
+        error: rawBodyDetail(proxyResult.body),
+      },
+      proxyResult.status === 429
+        ? "Managed Brave Search rate limit exceeded. Try again shortly."
+        : `Managed Brave Search provider returned status ${proxyResult.status}`,
     );
   }
 
@@ -545,18 +690,23 @@ async function executePerplexitySearch(
 ): Promise<ToolExecutionResult> {
   const startedAt = Date.now();
   for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
-    const response = await fetch(PERPLEXITY_API_URL, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey}`,
-      },
-      body: JSON.stringify({
-        model: "sonar",
-        messages: [{ role: "user", content: query }],
-      }),
-      signal,
-    });
+    let response: Response;
+    try {
+      response = await fetch(PERPLEXITY_API_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: "sonar",
+          messages: [{ role: "user", content: query }],
+        }),
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "perplexity", startedAt, err, signal);
+    }
 
     if (response.ok) {
       const data = (await response.json()) as PerplexityResponse;
@@ -574,7 +724,7 @@ async function executePerplexitySearch(
       };
     }
 
-    await response.text();
+    const bodyText = await response.text();
 
     if (response.status === 401 || response.status === 403) {
       return errorResult(
@@ -600,20 +750,22 @@ async function executePerplexitySearch(
     }
 
     log.warn({ status: response.status }, "Perplexity API error");
-    return errorResult(
+    return backendFailureResult(
       query,
       "perplexity",
       startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
       response.status === 429
         ? "Perplexity rate limit exceeded after retries. Try again shortly."
         : `Perplexity API returned status ${response.status}`,
     );
   }
 
-  return errorResult(
+  return backendFailureResult(
     query,
     "perplexity",
     startedAt,
+    { statusCode: 429 },
     "Perplexity rate limit exceeded after retries. Try again shortly.",
   );
 }
@@ -638,16 +790,21 @@ async function executeTavilySearch(
   const startedAt = Date.now();
 
   for (let attempt = 0; attempt <= DEFAULT_MAX_RETRIES; attempt++) {
-    const response = await fetch(TAVILY_API_URL, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey}`,
-        "X-Client-Source": "vellum-assistant",
-      },
-      body: JSON.stringify(body),
-      signal,
-    });
+    let response: Response;
+    try {
+      response = await fetch(TAVILY_API_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+          "X-Client-Source": "vellum-assistant",
+        },
+        body: JSON.stringify(body),
+        signal,
+      });
+    } catch (err) {
+      return networkFailureResult(query, "tavily", startedAt, err, signal);
+    }
 
     if (response.ok) {
       const data = (await response.json()) as TavilySearchResponse;
@@ -665,7 +822,7 @@ async function executeTavilySearch(
       };
     }
 
-    await response.text();
+    const bodyText = await response.text();
 
     if (response.status === 401 || response.status === 403) {
       return errorResult(
@@ -691,20 +848,22 @@ async function executeTavilySearch(
     }
 
     log.warn({ status: response.status }, "Tavily Search API error");
-    return errorResult(
+    return backendFailureResult(
       query,
       "tavily",
       startedAt,
+      { statusCode: response.status, error: rawBodyDetail(bodyText) },
       response.status === 429
         ? "Tavily Search rate limit exceeded after retries. Try again shortly."
         : `Tavily Search API returned status ${response.status}`,
     );
   }
 
-  return errorResult(
+  return backendFailureResult(
     query,
     "tavily",
     startedAt,
+    { statusCode: 429 },
     "Tavily Search rate limit exceeded after retries. Try again shortly.",
   );
 }
@@ -844,13 +1003,13 @@ export const webSearchTool = {
           signal: context.signal,
         });
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
         log.error({ err }, "Managed web search failed");
-        return errorResult(
+        return networkFailureResult(
           query,
           "brave",
           startedAt,
-          `Managed web search failed: ${msg}`,
+          err,
+          context.signal,
         );
       }
     }
@@ -897,13 +1056,13 @@ export const webSearchTool = {
         signal: context.signal,
       });
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
       log.error({ err }, "Web search failed");
-      return errorResult(
+      return networkFailureResult(
         query,
         provider,
         startedAt,
-        `Web search failed: ${msg}`,
+        err,
+        context.signal,
       );
     }
   },

package/src/tools/schedule/create.ts

@@ -144,6 +144,7 @@ export async function executeScheduleCreate(
         maxRetries,
         retryBackoffMs,
         timeoutMs,
+        createdFromConversationId: context.conversationId,
       });
 
       const fireDate = formatLocalDate(job.nextRunAt);
@@ -225,6 +226,7 @@ export async function executeScheduleCreate(
       maxRetries,
       retryBackoffMs,
       timeoutMs,
+      createdFromConversationId: context.conversationId,
     });
 
     const scheduleDescription =

package/src/tools/subagent/spawn.ts

@@ -1,4 +1,4 @@
-import { findConversation } from "../../daemon/conversation-store.js";
+import { findConversation } from "../../daemon/conversation-registry.js";
 import { getConversationOverrideProfile } from "../../memory/conversation-crud.js";
 import type { Message } from "../../providers/types.js";
 import { getSubagentManager } from "../../subagent/index.js";
@@ -102,9 +102,7 @@ export async function executeSubagentSpawn(
         ...(inheritedOverrideProfile
           ? { overrideProfile: inheritedOverrideProfile }
           : {}),
-        ...(context.toolUseId
-          ? { parentToolUseId: context.toolUseId }
-          : {}),
+        ...(context.toolUseId ? { parentToolUseId: context.toolUseId } : {}),
         ...forkFields,
       },
       sendToClient as (msg: unknown) => void,

package/src/tools/terminal/safe-env.ts

@@ -69,6 +69,15 @@ export const KATA_SAFE_ENV_VARS = [
 export const KATA_INJECTED_ENV_VARS = ["LD_LIBRARY_PATH"] as const;
 
 const KATA_APT_DATA_ROOT = "/data/system";
+const KATA_FAMILY_SANDBOX_RUNTIMES = new Set([
+  "kata",
+  "firecracker",
+  "cloud-hypervisor",
+]);
+
+function isKataFamilyRuntime(runtime: string | undefined): boolean {
+  return runtime != null && KATA_FAMILY_SANDBOX_RUNTIMES.has(runtime);
+}
 
 function kataAptPaths(dataRoot: string): string[] {
   return [
@@ -118,7 +127,7 @@ function appendUniquePathEntries(
 
 export function buildSanitizedEnv(): Record<string, string> {
   const env: Record<string, string> = {};
-  const isKataRuntime = process.env.VELLUM_SANDBOX_RUNTIME === "kata";
+  const isKataRuntime = isKataFamilyRuntime(process.env.VELLUM_SANDBOX_RUNTIME);
   const safeEnvVars = isKataRuntime
     ? [...SAFE_ENV_VARS, ...KATA_SAFE_ENV_VARS]
     : SAFE_ENV_VARS;

package/src/tools/ui-surface/definitions.ts

@@ -19,7 +19,7 @@ import type {
 // ---------------------------------------------------------------------------
 
 const APP_BUILDER_ARTIFACT_RE =
-  /\b(app|apps|application|applications|website|websites|site|sites|dashboard|dashboards|game|games|calculator|calculators|tracker|trackers|visualization|visualizations|visualisation|visualisations|tool|tools|utility|utilities|counter|counters)\b/i;
+  /\b(app|apps|application|applications|website|websites|site|sites|dashboard|dashboards|game|games|calculator|calculators|tracker|trackers|visualization|visualizations|visualisation|visualisations|visualize|visualise|artifact|artifacts|chart|charts|graph|graphs|tool|tools|utility|utilities|counter|counters)\b/i;
 const APP_BUILDER_BUILD_RE =
   /\b(build|building|built|create|creating|created|make|making|made|generate|generating|generated)\b/i;
 
@@ -58,11 +58,32 @@ function isDynamicPageAppSubstitute(input: Record<string, unknown>): boolean {
   }
 
   const text = collectRoutingText(input).join(" ");
-  if (!APP_BUILDER_ARTIFACT_RE.test(text)) {
-    return false;
+  if (
+    APP_BUILDER_ARTIFACT_RE.test(text) &&
+    (APP_BUILDER_BUILD_RE.test(text) || /\b(app|application)\b/i.test(text))
+  ) {
+    return true;
   }
 
-  return APP_BUILDER_BUILD_RE.test(text) || /\b(app|application)\b/i.test(text);
+  // Second signal: even when the model gives the surface a clean,
+  // non-app-sounding title (dodging the text regex above), substantial
+  // interactive HTML is an app being smuggled in as a transient surface.
+  // A genuinely transient page is small and static; an app has real
+  // scripted markup. Keep the bar high so simple snippets still pass.
+  return isSubstantialInteractiveHtml(input);
+}
+
+const INTERACTIVE_HTML_RE = /<script\b|on[a-z]+\s*=|addEventListener|new Chart\b|window\.vellum\b/i;
+
+function isSubstantialInteractiveHtml(
+  input: Record<string, unknown>,
+): boolean {
+  const data = asRecord(input.data);
+  const html = data?.html;
+  if (typeof html !== "string") {
+    return false;
+  }
+  return html.length > 2000 && INTERACTIVE_HTML_RE.test(html);
 }
 
 function collectRoutingText(input: Record<string, unknown>): string[] {
@@ -105,13 +126,17 @@ export const uiShowTool = {
     'Surface structured data or UI in the conversation. For long-form writing use the document skill. For interactive apps, dashboards, games, calculators, or durable tools, call `skill_load` with `skill: "app-builder"` and use the app-builder workflow; do not use `dynamic_page` as a substitute for a persistent app. App-like `dynamic_page` calls are rejected.\n\n' +
     "Surface types (data shapes):\n" +
     '- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: "weather_forecast" (native weather widget), "task_progress" (live step tracker - update via ui_update on data.templateData; shape: { title, status: "in_progress"|"completed"|"failed", steps: [{ label, status: "pending"|"in_progress"|"completed"|"failed", detail? }] })\n' +
+    "- copy_block: { text, label?, language? }. Shows copyable text with a visible copy button; use for prompts, commands, paths, or snippets the user should copy.\n" +
+    '- choice: { description?, options: [{ id, title, description?, recommended?, data? }], selectionMode?: "single"|"multiple", commitOnSelect?, submitLabel? }. Single-select choices commit on option click by default. Use for outcome offers and follow-up choices; mark the strongest option with recommended: true.\n' +
+    "- oauth_connect: { providerKey, displayName?, description?, logoUrl? }. Shows a managed OAuth connection CTA in chat; use when the current task needs a managed integration account (Google, Linear, GitHub, etc.) instead of asking the user to visit settings or attempting OAuth through shell/tools. The client supplies the CTA label. Do not include OAuth scopes in the surface; managed providers use the platform's configured scopes.\n" +
     '- table: { columns: [{ id, label }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
     '- form: { description?, fields: [{ id, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label, placeholder?, required?, defaultValue?, options?: [{ label, value }] }], submitLabel? }. Multi-page: { pages: [{ id, title, description?, fields }], pageLabels?: { next?, back?, submit? }, submitLabel? }\n' +
     '- list: { items: [{ id, title, subtitle?, icon?, selected? }], selectionMode: "single"|"multiple"|"none" }\n' +
     "- confirmation: { message, detail?, confirmLabel?, confirmedLabel?, cancelLabel?, destructive? }\n" +
     "- dynamic_page: { html, width?, height?, preview?: { title, subtitle?, description?, icon?, metrics?: [{ label, value }] } }\n" +
     "- file_upload: { prompt, acceptedTypes?, maxFiles? }\n" +
-    "- task_preferences: {} (no data needed — categories are rendered client-side)\n\n" +
+    "- task_preferences: {} (no data needed — categories are rendered client-side)\n" +
+    '- work_result: { eyebrow?, status?: "completed"|"partial"|"failed"|"in_progress", summary?, metrics?: [{ label, value, detail?, tone?: "neutral"|"positive"|"warning"|"negative" }], sections?: [{ id?, title, description?, type?: "items"|"timeline"|"diff"|"artifacts"|"warnings", items?: [{ id?, title, description?, status?, tone?, metadata?: [{ label, value }], href? }], diffs?: [{ label?, before?, after? }] }] }. Shows a structured receipt after real work: what changed, what was skipped, proof points, and next actions. Keep display-only unless explicit follow-up buttons are needed.\n\n' +
     "Proactively show a task_progress card before multi-step or long-running work (web searches, file operations, research). Show it before your first tool call, then update steps as work progresses.",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
@@ -124,6 +149,9 @@ export const uiShowTool = {
         type: "string",
         enum: [
           "card",
+          "choice",
+          "copy_block",
+          "oauth_connect",
           "form",
           "list",
           "table",
@@ -131,6 +159,7 @@ export const uiShowTool = {
           "dynamic_page",
           "file_upload",
           "task_preferences",
+          "work_result",
         ],
         description: "The type of surface to display",
       },

package/src/tts/__tests__/provider-catalog-consistency.test.ts

@@ -30,8 +30,10 @@ import {
 interface ClientCatalogProvider {
   id: string;
   displayName: string;
+  subtitle?: string;
+  supportsVoiceSelection?: boolean;
   credentialMode?: string;
-  credentialsGuide?: { url: string };
+  credentialsGuide?: { description: string; url: string; linkLabel: string };
 }
 
 interface ClientCatalog {
@@ -144,6 +146,88 @@ describe("TTS provider catalog / client artifact consistency", () => {
     }
   });
 
+  // -- Display field parity --------------------------------------------------
+
+  test("subtitle matches between assistant catalog and client artifact", () => {
+    const violations: string[] = [];
+    for (const clientEntry of clientCatalog.providers) {
+      try {
+        const assistantEntry = getCatalogProvider(clientEntry.id as any);
+        if (clientEntry.subtitle !== assistantEntry.subtitle) {
+          violations.push(
+            `"${clientEntry.id}": client="${clientEntry.subtitle}" vs assistant="${assistantEntry.subtitle}"`,
+          );
+        }
+      } catch {
+        // Unknown ID — covered by provider ID parity tests above.
+      }
+    }
+    if (violations.length > 0) {
+      expect(violations, "Subtitle mismatch:\n" + violations.join("\n")).toEqual(
+        [],
+      );
+    }
+  });
+
+  test("supportsVoiceSelection matches between assistant catalog and client artifact", () => {
+    const violations: string[] = [];
+    for (const clientEntry of clientCatalog.providers) {
+      try {
+        const assistantEntry = getCatalogProvider(clientEntry.id as any);
+        if (
+          clientEntry.supportsVoiceSelection !==
+          assistantEntry.supportsVoiceSelection
+        ) {
+          violations.push(
+            `"${clientEntry.id}": client=${clientEntry.supportsVoiceSelection} vs assistant=${assistantEntry.supportsVoiceSelection}`,
+          );
+        }
+      } catch {
+        // Unknown ID — covered by provider ID parity tests above.
+      }
+    }
+    if (violations.length > 0) {
+      expect(
+        violations,
+        "supportsVoiceSelection mismatch:\n" + violations.join("\n"),
+      ).toEqual([]);
+    }
+  });
+
+  test("credentialsGuide matches between assistant catalog and client artifact", () => {
+    const violations: string[] = [];
+    for (const clientEntry of clientCatalog.providers) {
+      try {
+        const assistantEntry = getCatalogProvider(clientEntry.id as any);
+        const cg = clientEntry.credentialsGuide;
+        const ag = assistantEntry.credentialsGuide;
+        if (cg && ag) {
+          if (cg.url !== ag.url) {
+            violations.push(`"${clientEntry.id}": credentialsGuide.url mismatch`);
+          }
+          if (cg.description !== ag.description) {
+            violations.push(
+              `"${clientEntry.id}": credentialsGuide.description mismatch`,
+            );
+          }
+          if (cg.linkLabel !== ag.linkLabel) {
+            violations.push(
+              `"${clientEntry.id}": credentialsGuide.linkLabel mismatch`,
+            );
+          }
+        }
+      } catch {
+        // Unknown ID — covered by provider ID parity tests above.
+      }
+    }
+    if (violations.length > 0) {
+      expect(
+        violations,
+        "credentialsGuide mismatch:\n" + violations.join("\n"),
+      ).toEqual([]);
+    }
+  });
+
   // -- Structural sanity ----------------------------------------------------
 
   test("client artifact version is a positive integer", () => {