docs: document model selection helpers

steipete · steipete · commit e8895f0a9958 · 2026-06-04T09:51:42.000-04:00
diff --git a/src/agents/model-catalog-browse.ts b/src/agents/model-catalog-browse.ts
@@ -1,3 +1,6 @@
+/**
+ * Loads model catalog views for browse/search UI surfaces.
+ */
 import {
   clampTimerTimeoutMs,
   resolveTimerTimeoutMs,
diff --git a/src/agents/model-catalog-lookup.ts b/src/agents/model-catalog-lookup.ts
@@ -1,3 +1,6 @@
+/**
+ * Looks up model catalog entries and input capability support.
+ */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/agents/model-catalog-scope.ts b/src/agents/model-catalog-scope.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves model catalog scope from config and discovery options.
+ */
 import {
   findNormalizedProviderValue,
   normalizeProviderId,
diff --git a/src/agents/model-catalog.ts b/src/agents/model-catalog.ts
@@ -1,3 +1,6 @@
+/**
+ * Loads bundled, manifest, and discovered model catalog entries.
+ */
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
diff --git a/src/agents/model-fallback.ts b/src/agents/model-fallback.ts
@@ -1,3 +1,6 @@
+/**
+ * Runs model and image fallback chains across provider/model candidates.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { sanitizeForLog } from "../../packages/terminal-core/src/ansi.js";
 import {
diff --git a/src/agents/model-fallback.types.ts b/src/agents/model-fallback.types.ts
@@ -1,3 +1,6 @@
+/**
+ * Shared candidate and attempt types for model fallback execution.
+ */
 import type { FailoverReason } from "./embedded-agent-helpers/types.js";
 
 // Shared model fallback record types used by selection, observation, and retry
diff --git a/src/agents/model-picker-visibility.ts b/src/agents/model-picker-visibility.ts
@@ -1,3 +1,6 @@
+/**
+ * Filters provider/model refs for model picker visibility.
+ */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { listCliRuntimeProviderIds } from "./cli-backends.js";
diff --git a/src/agents/model-provider-auth-state.ts b/src/agents/model-provider-auth-state.ts
@@ -1,3 +1,6 @@
+/**
+ * Process-local state for warmed provider auth snapshots.
+ */
 export type PreparedProviderAuthState = {
   agentId: string;
   configFingerprint: string;
diff --git a/src/agents/model-provider-auth.worker.ts b/src/agents/model-provider-auth.worker.ts
@@ -1,3 +1,6 @@
+/**
+ * Worker entrypoint for warming provider auth state off the main thread.
+ */
 import { parentPort, workerData } from "node:worker_threads";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { replaceRuntimeAuthProfileStoreSnapshots, type AuthProfileStore } from "./auth-profiles.js";
diff --git a/src/agents/model-runtime-aliases.ts b/src/agents/model-runtime-aliases.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves CLI runtime aliases to provider/model auth labels and execution ids.
+ */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/agents/model-scan.ts b/src/agents/model-scan.ts
@@ -1,3 +1,6 @@
+/**
+ * Scans remote provider model catalogs for configured providers.
+ */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import {
   asDateTimestampMs,
diff --git a/src/agents/model-selection-cli.ts b/src/agents/model-selection-cli.ts
@@ -1,3 +1,6 @@
+/**
+ * Detects providers whose model selections are backed by CLI runtimes.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveRuntimeCliBackends } from "../plugins/cli-backends.runtime.js";
 import { resolvePluginSetupCliBackendDescriptor } from "../plugins/setup-registry.runtime.js";
diff --git a/src/agents/model-selection-display.ts b/src/agents/model-selection-display.ts
@@ -1,3 +1,6 @@
+/**
+ * Formats selected model references for UI/session display.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 
 /** Inputs used to choose the visible model ref/name for status surfaces. */
diff --git a/src/agents/model-selection-normalize.ts b/src/agents/model-selection-normalize.ts
@@ -1,3 +1,6 @@
+/**
+ * Normalizes provider/model references and configured model ids.
+ */
 import {
   findNormalizedProviderKey as findNormalizedProviderKeyCore,
   findNormalizedProviderValue as findNormalizedProviderValueCore,
diff --git a/src/agents/model-selection-shared.ts b/src/agents/model-selection-shared.ts
@@ -1,3 +1,6 @@
+/**
+ * Shared model-selection resolution, alias, allowlist, and visibility logic.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/agents/model-selection.ts b/src/agents/model-selection.ts
@@ -1,3 +1,6 @@
+/**
+ * Public model-selection facade for persisted, configured, and allowed refs.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/agents/model-visibility-policy.ts b/src/agents/model-visibility-policy.ts
@@ -1,3 +1,6 @@
+/**
+ * Builds model visibility policies with configured fallbacks included.
+ */
 import { resolveAgentModelFallbackValues } from "../config/model-input.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveAgentModelFallbacksOverride } from "./agent-scope.js";
diff --git a/src/agents/models-config.providers.normalize.ts b/src/agents/models-config.providers.normalize.ts
@@ -1,3 +1,6 @@
+/**
+ * Normalizes configured provider model rows for runtime/discovery use.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { PluginManifestRecord } from "../plugins/manifest-registry.js";
 import { ensureAuthProfileStore } from "./auth-profiles/store.js";
diff --git a/src/agents/models-config.providers.policy.lookup.ts b/src/agents/models-config.providers.policy.lookup.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves provider plugin lookup keys from provider config aliases.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { MODEL_APIS } from "../config/types.models.js";
 import type { ProviderConfig } from "./models-config.providers.secrets.js";
diff --git a/src/agents/models-config.providers.policy.ts b/src/agents/models-config.providers.policy.ts
@@ -1,3 +1,6 @@
+/**
+ * Applies provider plugin policy to configured model provider settings.
+ */
 import {
   applyProviderNativeStreamingUsagePolicy,
   normalizeProviderConfigPolicy,
diff --git a/src/agents/models-config.providers.secret-helpers.ts b/src/agents/models-config.providers.secret-helpers.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves configured provider secrets from env, profiles, and SecretRefs.
+ */
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { coerceSecretRef, resolveSecretInputRef } from "../config/types.secrets.js";
diff --git a/src/agents/models-config.providers.source-managed.ts b/src/agents/models-config.providers.source-managed.ts
@@ -1,3 +1,6 @@
+/**
+ * Enforces source-managed provider secret ownership rules.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { resolveSecretInputRef } from "../config/types.secrets.js";
 import { isRecord } from "../utils.js";
