perf: reuse manifest metadata for read-only model catalogs

steipete · web-flow · commit 0e5f4ea18c29 · 2026-05-15T11:24:06.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -50,6 +50,7 @@ Docs: https://docs.openclaw.ai
 - Require canonical node platform IDs [AI]. (#81880) Thanks @pgondhi987.
 - Agents/Azure OpenAI Responses: default unset Azure OpenAI API versions to `preview` so `/openai/v1/responses` calls use Azure's current Responses API route. (#82026) Thanks @leoge007.
 - Control UI/WebChat: compact the desktop chat header controls into a single aligned row so the session, model, thinking, and action controls no longer waste vertical space. Thanks @BunsDev.
+- Agents/model catalog: reuse manifest model-id normalization metadata while loading persisted read-only catalog rows, avoiding repeated metadata scans.
 - Agents: retry empty final turns for generic `anthropic-messages` providers instead of limiting non-visible recovery to Kimi, so custom/proxied Anthropic-compatible routes can recover with a visible answer. Addresses #46080. Thanks @wmgx, @w1tv, and @iFwu.
 - Agents/replies: strip workflow `<function_response>` scaffolding from user-visible sanitizer paths so raw tool output does not leak into chat history, transcript mirrors, or channel replies. Fixes #47444. Thanks @5toCode.
 - Agents/media: deliver generated image, music, and video results through structured attachments, keep message-tool-only Codex completions on the message tool, and fail completion handoff when expected media is not actually sent.
diff --git a/src/agents/model-catalog.test.ts b/src/agents/model-catalog.test.ts
@@ -105,6 +105,29 @@ function emptyPluginMetadataSnapshot() {
   };
 }
 
+function modelIdNormalizationSnapshot() {
+  return {
+    ...emptyPluginMetadataSnapshot(),
+    configFingerprint: "model-id-normalizers",
+    plugins: [
+      {
+        id: "external-normalizer",
+        modelIdNormalization: {
+          providers: {
+            custom: {
+              aliases: {
+                latest: "modern-model",
+              },
+              stripPrefixes: ["legacy/"],
+              prefixWhenBare: "vendor",
+            },
+          },
+        },
+      },
+    ],
+  };
+}
+
 type ModelCatalogEntry = Awaited<
   ReturnType<typeof import("./model-catalog.js").loadModelCatalog>
 >[number];
@@ -487,6 +510,52 @@ describe("loadModelCatalog", () => {
     expect(augmentCatalogMock).not.toHaveBeenCalled();
   });
 
+  it("normalizes persisted read-only catalog rows with manifest model id policies", async () => {
+    currentPluginMetadataSnapshotMock.mockReturnValueOnce(modelIdNormalizationSnapshot());
+    readFileMock.mockResolvedValueOnce(
+      JSON.stringify({
+        providers: {
+          custom: {
+            models: [
+              { id: "latest", name: "Latest Alias" },
+              { id: "legacy/trimmed" },
+              { id: "vendor/already-prefixed" },
+            ],
+          },
+        },
+      }),
+    );
+
+    const result = await loadModelCatalog({ config: {} as OpenClawConfig, readOnly: true });
+
+    expect(requireCatalogEntry(result, "custom", "vendor/modern-model").name).toBe("Latest Alias");
+    expect(requireCatalogEntry(result, "custom", "vendor/trimmed").name).toBe("vendor/trimmed");
+    expect(requireCatalogEntry(result, "custom", "vendor/already-prefixed").name).toBe(
+      "vendor/already-prefixed",
+    );
+    expect(loadPluginMetadataSnapshotMock).not.toHaveBeenCalled();
+  });
+
+  it("loads manifest model id policies once for persisted read-only catalog rows", async () => {
+    currentPluginMetadataSnapshotMock.mockReturnValue(undefined);
+    loadPluginMetadataSnapshotMock.mockReturnValue(modelIdNormalizationSnapshot());
+    readFileMock.mockResolvedValueOnce(
+      JSON.stringify({
+        providers: {
+          custom: {
+            models: [{ id: "model-a" }, { id: "model-b" }, { id: "model-c" }, { id: "model-d" }],
+          },
+        },
+      }),
+    );
+
+    const result = await loadModelCatalog({ config: {} as OpenClawConfig, readOnly: true });
+
+    expect(requireCatalogEntry(result, "custom", "vendor/model-a").name).toBe("vendor/model-a");
+    expect(requireCatalogEntry(result, "custom", "vendor/model-d").name).toBe("vendor/model-d");
+    expect(loadPluginMetadataSnapshotMock).toHaveBeenCalledTimes(1);
+  });
+
   it("preserves provider context defaults for persisted read-only catalog rows", async () => {
     readFileMock.mockResolvedValueOnce(
       JSON.stringify({
diff --git a/src/agents/model-catalog.ts b/src/agents/model-catalog.ts
@@ -5,7 +5,10 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import { planManifestModelCatalogRows } from "../model-catalog/manifest-planner.js";
 import { getCurrentPluginMetadataSnapshot } from "../plugins/current-plugin-metadata-snapshot.js";
-import { isManifestPluginAvailableForControlPlane } from "../plugins/manifest-contract-eligibility.js";
+import {
+  isManifestPluginAvailableForControlPlane,
+  loadManifestMetadataSnapshot,
+} from "../plugins/manifest-contract-eligibility.js";
 import { loadPluginMetadataSnapshot } from "../plugins/plugin-metadata-snapshot.js";
 import { augmentModelCatalogWithProviderPlugins } from "../plugins/provider-runtime.runtime.js";
 import { createLazyImportLoader } from "../shared/lazy-promise.js";
@@ -16,7 +19,10 @@ import {
 import { resolveDefaultAgentDir } from "./agent-scope.js";
 import { modelSupportsInput as modelCatalogEntrySupportsInput } from "./model-catalog-lookup.js";
 import type { ModelCatalogEntry, ModelInputType } from "./model-catalog.types.js";
-import { normalizeConfiguredProviderCatalogModelId } from "./model-ref-shared.js";
+import {
+  normalizeConfiguredProviderCatalogModelId,
+  type ProviderModelIdNormalizationOptions,
+} from "./model-ref-shared.js";
 import { buildConfiguredModelCatalog } from "./model-selection-shared.js";
 import { ensureOpenClawModelsJson } from "./models-config.js";
 import { normalizeProviderId } from "./provider-id.js";
@@ -196,6 +202,9 @@ function normalizePersistedModelCatalogEntry(
     contextWindow?: number;
     contextTokens?: number;
   },
+  options: {
+    manifestPlugins?: ProviderModelIdNormalizationOptions["manifestPlugins"];
+  } = {},
 ): ModelCatalogEntry | undefined {
   const rawId = normalizeOptionalString(entry.id) ?? "";
   if (!rawId) {
@@ -205,7 +214,7 @@ function normalizePersistedModelCatalogEntry(
   if (!provider) {
     return undefined;
   }
-  const id = normalizeConfiguredProviderCatalogModelId(provider, rawId);
+  const id = normalizeConfiguredProviderCatalogModelId(provider, rawId, options);
   const name = normalizeOptionalString(entry.name ?? id) || id;
   const contextWindow =
     typeof entry?.contextWindow === "number" && entry.contextWindow > 0
@@ -252,6 +261,14 @@ async function loadReadOnlyPersistedModelCatalog(params?: {
   const models: ModelCatalogEntry[] = [];
   const { buildShouldSuppressBuiltInModel } = await loadModelSuppression();
   const shouldSuppressBuiltInModel = buildShouldSuppressBuiltInModel({ config: cfg });
+  let manifestPlugins: ProviderModelIdNormalizationOptions["manifestPlugins"];
+  const getManifestPlugins = () => {
+    manifestPlugins ??= loadManifestMetadataSnapshot({
+      config: cfg,
+      env: process.env,
+    }).plugins;
+    return manifestPlugins;
+  };
   const providers =
     parsed?.providers && typeof parsed.providers === "object"
       ? (parsed.providers as Record<string, Record<string, unknown>>)
@@ -269,10 +286,15 @@ async function loadReadOnlyPersistedModelCatalog(params?: {
         ? providerConfig.contextTokens
         : undefined;
     for (const entry of providerConfig.models as Record<string, unknown>[]) {
-      const normalized = normalizePersistedModelCatalogEntry(providerRaw, entry, {
-        contextWindow: providerContextWindow,
-        contextTokens: providerContextTokens,
-      });
+      const normalized = normalizePersistedModelCatalogEntry(
+        providerRaw,
+        entry,
+        {
+          contextWindow: providerContextWindow,
+          contextTokens: providerContextTokens,
+        },
+        { manifestPlugins: getManifestPlugins() },
+      );
       if (normalized && !shouldSuppressBuiltInModel(normalized)) {
         models.push(normalized);
       }
diff --git a/src/agents/model-ref-shared.test.ts b/src/agents/model-ref-shared.test.ts
@@ -19,6 +19,36 @@ describe("normalizeStaticProviderModelId", () => {
 });
 
 describe("normalizeConfiguredProviderCatalogModelId", () => {
+  const manifestPlugins = [
+    {
+      modelIdNormalization: {
+        providers: {
+          custom: {
+            aliases: {
+              latest: "modern-model",
+            },
+            prefixWhenBare: "vendor",
+          },
+        },
+      },
+    },
+  ];
+
+  it("applies supplied manifest normalization policies to configured catalog ids", () => {
+    expect(normalizeConfiguredProviderCatalogModelId("custom", "latest", { manifestPlugins })).toBe(
+      "vendor/modern-model",
+    );
+  });
+
+  it("can skip manifest normalization while retaining built-in normalization", () => {
+    expect(
+      normalizeConfiguredProviderCatalogModelId("custom", "latest", {
+        allowManifestNormalization: false,
+        manifestPlugins,
+      }),
+    ).toBe("latest");
+  });
+
   it("normalizes nested retired Google Gemini ids in proxy-prefixed rows", () => {
     expect(
       normalizeConfiguredProviderCatalogModelId("kilocode", "kilocode/google/gemini-3-pro-preview"),
diff --git a/src/agents/model-ref-shared.ts b/src/agents/model-ref-shared.ts
@@ -9,6 +9,11 @@ type StaticModelRef = {
   model: string;
 };
 
+export type ProviderModelIdNormalizationOptions = {
+  allowManifestNormalization?: boolean;
+  manifestPlugins?: readonly Pick<PluginManifestRecord, "modelIdNormalization">[];
+};
+
 export function modelKey(provider: string, model: string): string {
   const providerId = provider.trim();
   const modelId = model.trim();
@@ -28,10 +33,7 @@ export function modelKey(provider: string, model: string): string {
 export function normalizeStaticProviderModelId(
   provider: string,
   model: string,
-  options: {
-    allowManifestNormalization?: boolean;
-    manifestPlugins?: readonly Pick<PluginManifestRecord, "modelIdNormalization">[];
-  } = {},
+  options: ProviderModelIdNormalizationOptions = {},
 ): string {
   const normalizedProvider = normalizeProviderId(provider);
   if (options.allowManifestNormalization === false) {
@@ -56,8 +58,12 @@ function normalizeBuiltInProviderModelId(provider: string, model: string): strin
   return model;
 }
 
-export function normalizeConfiguredProviderCatalogModelId(provider: string, model: string): string {
-  const providerModel = normalizeStaticProviderModelId(provider, model);
+export function normalizeConfiguredProviderCatalogModelId(
+  provider: string,
+  model: string,
+  options: ProviderModelIdNormalizationOptions = {},
+): string {
+  const providerModel = normalizeStaticProviderModelId(provider, model, options);
   const googlePrefix = "google/";
   if (!providerModel.startsWith(googlePrefix)) {
     const slash = providerModel.indexOf("/");
