docs: document agent model auth helpers

src/agents/agent-auth-discovery-core.ts

@@ -6,12 +6,14 @@ import {
 } from "./model-auth-env-vars.js";
 import { resolveEnvApiKey } from "./model-auth-env.js";
 
+/** Options for discovering env-backed credentials during agent auth discovery. */
 export type AgentDiscoveryAuthLookupOptions = {
   config?: OpenClawConfig;
   workspaceDir?: string;
   env?: NodeJS.ProcessEnv;
 };
 
+/** Adds provider credentials resolvable from env/config without mutating existing credentials. */
 export function addEnvBackedAgentCredentials(
   credentials: AgentCredentialMap,
   options: AgentDiscoveryAuthLookupOptions = {},

src/agents/agent-model-discovery.ts

@@ -39,6 +39,7 @@ type DiscoverModelsOptions = {
   normalizeModels?: boolean;
 };
 
+/** Applies plugin model normalization and transport hooks to discovered agent models. */
 export function normalizeDiscoveredAgentModel<T>(value: T, agentDir: string): T {
   if (!isRecord(value)) {
     return value;
@@ -145,6 +146,7 @@ function createOpenClawModelRegistry(
   return registry;
 }
 
+/** Creates auth storage for model discovery from stored and env-backed credentials. */
 export function discoverAuthStorage(
   agentDir: string,
   options?: DiscoverAuthStorageOptions,
@@ -154,6 +156,7 @@ export function discoverAuthStorage(
   return AuthStorage.inMemory(credentials);
 }
 
+/** Creates the model registry used by agent model discovery. */
 export function discoverModels(
   authStorage: AgentAuthStorage,
   agentDir: string,

src/agents/live-model-switch-error.ts

@@ -5,6 +5,7 @@ type LiveSessionModelSelection = {
   authProfileIdSource?: "auto" | "user";
 };
 
+/** Control-flow error used to request a live session model switch. */
 export class LiveSessionModelSwitchError extends Error {
   provider: string;
   model: string;

src/agents/mcp-http-fetch.ts

@@ -2,14 +2,17 @@ import fs from "node:fs";
 import type { FetchLike } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { loadUndiciRuntimeDeps } from "../infra/net/undici-runtime.js";
 
+/** MCP SDK-compatible fetch function type. */
 export type { FetchLike };
 
+/** Default MCP HTTP fetch backed by lazy-loaded undici runtime deps. */
 export const fetchWithUndici: FetchLike = async (url, init) =>
   (await loadUndiciRuntimeDeps().fetch(
     url,
     init as Parameters<ReturnType<typeof loadUndiciRuntimeDeps>["fetch"]>[1],
   )) as unknown as Response;
 
+/** Builds an MCP fetch function with optional TLS/client-cert dispatcher support. */
 export function buildMcpHttpFetch(params: {
   sslVerify?: boolean;
   clientCert?: string;
@@ -47,6 +50,7 @@ export function buildMcpHttpFetch(params: {
   };
 }
 
+/** Removes Authorization from MCP headers before forwarding to non-authorized paths. */
 export function withoutMcpAuthorizationHeader(
   headers: Record<string, string> | undefined,
 ): Record<string, string> | undefined {
@@ -57,6 +61,7 @@ export function withoutMcpAuthorizationHeader(
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }
 
+/** Wraps MCP fetch so configured headers are applied only to the resource origin. */
 export function withSameOriginMcpHttpHeaders(params: {
   fetchFn: FetchLike;
   headers: Record<string, string> | undefined;

src/agents/models-config.merge.ts

@@ -2,6 +2,7 @@ import { normalizeOptionalString } from "@openclaw/normalization-core/string-coe
 import { isNonSecretApiKeyMarker } from "./model-auth-markers.js";
 import type { ProviderConfig } from "./models-config.providers.secrets.js";
 
+/** Existing provider config shape that may carry persisted secret/base URL fields. */
 export type ExistingProviderConfig = ProviderConfig & {
   apiKey?: string;
   baseUrl?: string;
@@ -34,6 +35,7 @@ function getProviderModelId(model: unknown): string {
   return normalizeOptionalString(id) ?? "";
 }
 
+/** Merges implicit provider models with explicit config while preserving explicit fields. */
 export function mergeProviderModels(
   implicit: ProviderConfig,
   explicit: ProviderConfig,
@@ -134,6 +136,7 @@ export function mergeProviderModels(
   };
 }
 
+/** Merges implicit and explicit provider config maps by provider id. */
 export function mergeProviders(params: {
   implicit?: Record<string, ProviderConfig> | null;
   explicit?: Record<string, ProviderConfig> | null;
@@ -219,6 +222,7 @@ function isExistingProviderSelfContained(entry: ExistingProviderConfig): boolean
   return Boolean(entry.baseUrl?.trim() && entry.apiKey);
 }
 
+/** Merges generated provider config with existing secrets safe to preserve. */
 export function mergeWithExistingProviderSecrets(params: {
   nextProviders: Record<string, ProviderConfig>;
   existingProviders: Record<string, ExistingProviderConfig>;

src/agents/stable-stringify.ts

@@ -1,5 +1,6 @@
 import { Buffer } from "node:buffer";
 
+/** Deterministically stringifies unknown values for cache keys and diagnostics. */
 export function stableStringify(value: unknown): string {
   return stringifyStableValue(value, new WeakSet());
 }

src/agents/tools-effective-inventory.types.ts

@@ -1,8 +1,10 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { ProviderRuntimeModel } from "../plugins/provider-runtime-model.types.js";
 
+/** Source bucket for an effective agent tool inventory entry. */
 export type EffectiveToolSource = "core" | "plugin" | "channel" | "mcp";
 
+/** One tool listed in the effective inventory for an agent/session context. */
 export type EffectiveToolInventoryEntry = {
   id: string;
   label: string;
@@ -15,6 +17,7 @@ export type EffectiveToolInventoryEntry = {
   tags?: string[];
 };
 
+/** Grouped effective tools for one source bucket. */
 export type EffectiveToolInventoryGroup = {
   id: EffectiveToolSource;
   label: string;
@@ -22,12 +25,14 @@ export type EffectiveToolInventoryGroup = {
   tools: EffectiveToolInventoryEntry[];
 };
 
+/** Operator-facing notice emitted while building effective tool inventory. */
 export type EffectiveToolInventoryNotice = {
   id: string;
   severity: "info" | "warning";
   message: string;
 };
 
+/** Effective tool inventory result for one agent/profile. */
 export type EffectiveToolInventoryResult = {
   agentId: string;
   profile: string;
@@ -35,6 +40,7 @@ export type EffectiveToolInventoryResult = {
   notices?: EffectiveToolInventoryNotice[];
 };
 
+/** Inputs for resolving the effective tool inventory in a session/runtime context. */
 export type ResolveEffectiveToolInventoryParams = {
   cfg: OpenClawConfig;
   agentId?: string;