From 73752f07f21983c1cf19a8a8cb598d815b5cbe04 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 12:29:16 -0400 Subject: [PATCH] docs: document model list runtime comments --- src/commands/models/list.model-row.ts | 4 ++++ src/commands/models/list.probe.ts | 15 +++++++++++++++ src/commands/models/list.provider-catalog.ts | 6 ++++++ .../models/list.provider-index-catalog.ts | 2 ++ src/commands/models/list.registry-load.ts | 3 +++ src/commands/models/list.registry.ts | 3 +++ 6 files changed, 33 insertions(+) diff --git a/src/commands/models/list.model-row.ts b/src/commands/models/list.model-row.ts index 46079c69f7bc..fd35ed87b478 100644 --- a/src/commands/models/list.model-row.ts +++ b/src/commands/models/list.model-row.ts @@ -1,7 +1,9 @@ +/** Converts registry/catalog models into printable model-list rows. */ import { modelKey } from "../../agents/model-ref-shared.js"; import { isLocalBaseUrl } from "./list.local-url.js"; import type { ModelRow } from "./list.types.js"; +/** Minimal model shape needed to render a model-list row. */ export type ListRowModel = { id: string; name: string; @@ -12,8 +14,10 @@ export type ListRowModel = { contextTokens?: number | null; }; +/** Provider-auth predicate used when model-level availability is unavailable. */ export type ModelAuthAvailabilityResolver = (provider: string) => boolean; +/** Builds a display row, preserving configured tags and alias metadata. */ export function toModelRow(params: { model?: ListRowModel; key: string; diff --git a/src/commands/models/list.probe.ts b/src/commands/models/list.probe.ts index 38f928b74073..71d52b9a95ed 100644 --- a/src/commands/models/list.probe.ts +++ b/src/commands/models/list.probe.ts @@ -1,3 +1,4 @@ +/** Auth probe planning and execution helpers for model diagnostics. */ import crypto from "node:crypto"; import fs from "node:fs/promises"; import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization"; @@ -46,6 +47,7 @@ function loadEmbeddedRunnerModule() { return embeddedRunnerModuleLoader.load(); } +/** Normalized probe status bucket for auth/model diagnostics. */ export type AuthProbeStatus = | "ok" | "auth" @@ -56,6 +58,7 @@ export type AuthProbeStatus = | "unknown" | "no_model"; +/** Reason code for probes that never reached a model call. */ export type AuthProbeReasonCode = | "excluded_by_auth_order" | "missing_credential" @@ -65,6 +68,7 @@ export type AuthProbeReasonCode = | "ineligible_profile" | "no_model"; +/** Result for one profile/env/models.json auth probe target. */ export type AuthProbeResult = { provider: string; model?: string; @@ -87,6 +91,7 @@ type AuthProbeTarget = { mode?: string; }; +/** Summary for a full auth probe run. */ export type AuthProbeSummary = { startedAt: number; finishedAt: number; @@ -102,6 +107,7 @@ export type AuthProbeSummary = { results: AuthProbeResult[]; }; +/** Runtime options controlling provider/profile filtering and probe cost. */ export type AuthProbeOptions = { provider?: string; profileIds?: string[]; @@ -110,6 +116,7 @@ export type AuthProbeOptions = { maxTokens: number; }; +/** Maps runtime failover reasons into stable auth probe status buckets. */ export function mapFailoverReasonToProbeStatus(reason?: string | null): AuthProbeStatus { if (!reason) { return "unknown"; @@ -285,6 +292,7 @@ async function maybeResolveUnresolvedRefIssue(params: { } } +/** Builds probe targets plus preflight failures for missing/invalid credentials. */ export async function buildProbeTargets(params: { cfg: OpenClawConfig; agentDir?: string; @@ -334,6 +342,8 @@ export async function buildProbeTargets(params: { explicitOrder && explicitOrder.length > 0 ? new Set(resolveAuthProfileOrder({ cfg, store, provider: providerKey })) : null; + // Explicit auth.order both selects and documents profile eligibility; report + // excluded profiles instead of silently skipping them. const filteredProfiles = profileFilter.size ? profileIds.filter((id) => profileFilter.has(id)) : profileIds; @@ -605,6 +615,7 @@ async function runTargetsWithConcurrency(params: { return results.filter((entry): entry is AuthProbeResult => Boolean(entry)); } +/** Runs all auth probes with bounded concurrency and returns a summary. */ export async function runAuthProbes(params: { cfg: OpenClawConfig; agentId?: string; @@ -654,6 +665,7 @@ export async function runAuthProbes(params: { }; } +/** Formats probe latency for table output. */ export function formatProbeLatency(latencyMs?: number | null) { if (!latencyMs && latencyMs !== 0) { return "-"; @@ -661,6 +673,7 @@ export function formatProbeLatency(latencyMs?: number | null) { return formatMs(latencyMs); } +/** Groups probe results by provider. */ export function groupProbeResults(results: AuthProbeResult[]): Map { const map = new Map(); for (const result of results) { @@ -671,6 +684,7 @@ export function groupProbeResults(results: AuthProbeResult[]): Map { const provider = a.provider.localeCompare(b.provider); @@ -683,6 +697,7 @@ export function sortProbeResults(results: AuthProbeResult[]): AuthProbeResult[] }); } +/** Produces the terse completion line for auth probe output. */ export function describeProbeSummary(summary: AuthProbeSummary): string { if (summary.totalTargets === 0) { return "No probe targets."; diff --git a/src/commands/models/list.provider-catalog.ts b/src/commands/models/list.provider-catalog.ts index 84f65d9f77b5..bbb9ec79041d 100644 --- a/src/commands/models/list.provider-catalog.ts +++ b/src/commands/models/list.provider-catalog.ts @@ -1,3 +1,4 @@ +/** Provider plugin catalog loading for model-list output. */ import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id"; import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization"; import { loadAuthProfileStoreWithoutExternalProfiles } from "../../agents/auth-profiles/store.js"; @@ -106,6 +107,7 @@ function resolveInstalledIndexPluginIdsForProviderFilter(params: { return disabledPluginIds.length > 0 ? [] : undefined; } +/** Resolves plugin ids that can provide catalog rows for a provider filter. */ export async function resolveProviderCatalogPluginIdsForFilter(params: { cfg: OpenClawConfig; env?: NodeJS.ProcessEnv; @@ -124,6 +126,8 @@ export async function resolveProviderCatalogPluginIdsForFilter(params: { registryIndex: params.metadataSnapshot?.index ?? params.registryIndex, }); if (installedIndexPluginIds) { + // Installed registry metadata is process-stable and knows disabled plugins, + // so it wins over broader manifest/contract alias fallbacks. return installedIndexPluginIds; } const manifestPluginIds = resolveOwningPluginIdsForProviderRef({ @@ -144,6 +148,7 @@ export async function resolveProviderCatalogPluginIdsForFilter(params: { return undefined; } +/** Returns true when a provider filter can be satisfied by a static bundled catalog. */ export async function hasProviderStaticCatalogForFilter(params: { cfg: OpenClawConfig; env?: NodeJS.ProcessEnv; @@ -212,6 +217,7 @@ function modelFromProviderCatalog(params: { } as Model; } +/** Loads model rows from provider static/runtime catalog hooks for model-list output. */ export async function loadProviderCatalogModelsForList(params: { cfg: OpenClawConfig; agentDir: string; diff --git a/src/commands/models/list.provider-index-catalog.ts b/src/commands/models/list.provider-index-catalog.ts index cc7e91c8651b..9bf96591b872 100644 --- a/src/commands/models/list.provider-index-catalog.ts +++ b/src/commands/models/list.provider-index-catalog.ts @@ -1,3 +1,4 @@ +/** Provider-index-backed model catalog rows for bundled model-list output. */ import { normalizeModelCatalogProviderId } from "@openclaw/model-catalog-core/model-catalog-refs"; import type { NormalizedModelCatalogRow } from "@openclaw/model-catalog-core/model-catalog-types"; import type { OpenClawConfig } from "../../config/types.openclaw.js"; @@ -7,6 +8,7 @@ import { } from "../../model-catalog/index.js"; import { normalizePluginsConfig, resolveEffectiveEnableState } from "../../plugins/config-state.js"; +/** Loads enabled bundled provider-index catalog rows, optionally scoped by provider. */ export function loadProviderIndexCatalogRowsForList(params: { providerFilter?: string; cfg: OpenClawConfig; diff --git a/src/commands/models/list.registry-load.ts b/src/commands/models/list.registry-load.ts index 6431aa499d2a..dbd3a2547fa5 100644 --- a/src/commands/models/list.registry-load.ts +++ b/src/commands/models/list.registry-load.ts @@ -1,3 +1,4 @@ +/** Registry-loading adapters for model-list row construction. */ import { loadAgentModelRegistry } from "../../agents/model-registry-loader.js"; import { shouldSuppressBuiltInModel } from "../../agents/model-suppression.js"; import type { OpenClawConfig } from "../../config/types.openclaw.js"; @@ -7,6 +8,7 @@ import { loadModelRegistry } from "./list.registry.js"; import type { ConfiguredEntry } from "./list.types.js"; import { modelKey } from "./shared.js"; +/** Loads the full model registry and tracks discovered provider/model keys. */ export async function loadListModelRegistry( cfg: OpenClawConfig, opts?: { @@ -45,6 +47,7 @@ function findConfiguredRegistryModel(params: { return model; } +/** Loads only configured registry entries and their auth availability. */ export function loadConfiguredListModelRegistry( cfg: OpenClawConfig, entries: ConfiguredEntry[], diff --git a/src/commands/models/list.registry.ts b/src/commands/models/list.registry.ts index 89c5de7abf49..63b4014528d2 100644 --- a/src/commands/models/list.registry.ts +++ b/src/commands/models/list.registry.ts @@ -1,3 +1,4 @@ +/** Model registry access helpers for `openclaw models list`. */ import { loadAgentModelRegistry } from "../../agents/model-registry-loader.js"; import { shouldSuppressBuiltInModel, @@ -84,6 +85,7 @@ function loadAvailableModels( } } +/** Loads registry models and optional availability keys with suppression applied. */ export async function loadModelRegistry( cfg: OpenClawConfig, opts?: { @@ -137,6 +139,7 @@ export async function loadModelRegistry( return { registry, models, availableKeys, availabilityErrorMessage }; } +/** Compatibility wrapper around the shared model-row builder. */ export function toModelRow(params: Parameters[0]): ModelRow { return toModelRowBase(params); }