docs: document model helper normalization

src/agents/embedded-agent-runner/model.inline-provider.ts

@@ -10,6 +10,9 @@ import {
   sanitizeConfiguredModelProviderRequest,
 } from "../provider-request-config.js";
 
+/**
+ * Normalizes inline `models.providers` config into runtime model entries.
+ */
 export type InlineModelEntry = Omit<ModelDefinitionConfig, "api"> & {
   api?: Api;
   provider: string;
@@ -32,6 +35,7 @@ export type InlineProviderConfig = {
   localService?: ModelProviderConfig["localService"];
 };
 
+/** Returns a supported transport API id from raw config values. */
 export function normalizeResolvedTransportApi(
   api: unknown,
 ): ModelDefinitionConfig["api"] | undefined {
@@ -52,6 +56,7 @@ export function normalizeResolvedTransportApi(
   }
 }
 
+/** Sanitizes configured provider/model headers before they enter runtime model metadata. */
 export function sanitizeModelHeaders(
   headers: unknown,
   opts?: { stripSecretRefMarkers?: boolean },
@@ -65,6 +70,8 @@ export function sanitizeModelHeaders(
       continue;
     }
     if (opts?.stripSecretRefMarkers && isSecretRefHeaderValueMarker(headerValue)) {
+      // Catalog/runtime model records are inspectable. Secret-ref markers are resolved later during
+      // auth setup, so inline provider discovery must not expose them as literal headers.
       continue;
     }
     next[headerName] = headerValue;
@@ -94,6 +101,7 @@ function isLegacyFoundryVisionModelCandidate(params: {
   );
 }
 
+/** Resolves model input modalities with Foundry legacy vision-model compatibility. */
 export function resolveProviderModelInput(params: {
   provider?: string;
   modelId?: string;
@@ -127,6 +135,7 @@ function resolveInlineProviderTransport(params: { api?: Api | null; baseUrl?: st
   };
 }
 
+/** Builds runtime model records from inline provider config, inheriting provider-level defaults. */
 export function buildInlineProviderModels(
   providers: Record<string, InlineProviderConfig>,
 ): InlineModelEntry[] {

src/agents/embedded-agent-runner/model.provider-normalization.ts

@@ -1,6 +1,9 @@
 import type { Model } from "../../llm/types.js";
 import { normalizeModelCompat } from "../../plugins/provider-model-compat.js";
 
+/**
+ * Applies provider compatibility normalization to a resolved model record.
+ */
 export function normalizeResolvedProviderModel(params: { provider: string; model: Model }): Model {
   return normalizeModelCompat(params.model);
 }

src/agents/embedded-agent-runner/model.static-catalog.ts

@@ -10,6 +10,9 @@ import type { ProviderRuntimeModel } from "../../plugins/provider-runtime-model.
 import { DEFAULT_CONTEXT_TOKENS } from "../defaults.js";
 import { normalizeStaticProviderModelId } from "../model-ref-shared.js";
 
+/**
+ * Resolves bundled plugin static model-catalog rows into runtime model records.
+ */
 function rowMatchesModel(params: {
   row: NormalizedModelCatalogRow;
   provider: string;
@@ -45,6 +48,7 @@ function normalizeStaticCatalogCost(
   };
 }
 
+/** Converts a normalized catalog row into the provider runtime model shape. */
 function modelFromStaticCatalogRow(row: NormalizedModelCatalogRow): ProviderRuntimeModel {
   return {
     id: row.id,
@@ -112,6 +116,7 @@ function resolveManifestModelCatalogProviderAlias(params: {
   return targets.size === 1 ? [...targets][0] : undefined;
 }
 
+/** Resolves a provider alias from plugin model-catalog metadata when the alias is unambiguous. */
 export function canonicalizeManifestModelCatalogProviderAlias(params: {
   provider: string;
   cfg?: OpenClawConfig;
@@ -134,6 +139,7 @@ export function canonicalizeManifestModelCatalogProviderAlias(params: {
   );
 }
 
+/** Returns whether a bundled static catalog asks runtime discovery to augment its rows. */
 export function bundledStaticCatalogProviderUsesRuntimeAugment(params: {
   provider: string;
   env?: NodeJS.ProcessEnv;
@@ -158,6 +164,7 @@ export function bundledStaticCatalogProviderUsesRuntimeAugment(params: {
   });
 }
 
+/** Resolves one bundled static-catalog model row for provider/model lookup. */
 export function resolveBundledStaticCatalogModel(params: {
   provider: string;
   modelId: string;
@@ -183,6 +190,8 @@ export function resolveBundledStaticCatalogModel(params: {
       entry.discovery !== "static" &&
       !(params.includeRuntimeDiscovery && entry.discovery === "runtime")
     ) {
+      // Static lookups normally ignore runtime-discovery rows. Callers opt in only when they are
+      // merging static catalog facts with already-discovered provider runtime state.
       continue;
     }
     const row = entry.rows.find((candidate) =>