docs: document auth health helpers

src/agents/auth-health.test.ts

@@ -1,3 +1,8 @@
+/**
+ * Tests auth health rollups.
+ * Covers OAuth/API-key status classification, external CLI bootstrap, provider
+ * auth ordering, and prompt-free credential checks.
+ */
 import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OAuthCredential } from "./auth-profiles/types.js";

src/agents/auth-health.ts

@@ -1,3 +1,8 @@
+/**
+ * Auth profile health summarization.
+ * Classifies stored and runtime credentials into profile/provider rollups for
+ * status commands and doctor output without prompting keychain access.
+ */
 import {
   findNormalizedProviderValue,
   normalizeProviderId,
@@ -61,6 +66,7 @@ function resolveAuthProfileSource(_profileId: string): AuthProfileSource {
   return "store";
 }
 
+/** Format a remaining-duration value for compact auth status displays. */
 export function formatRemainingShort(
   remainingMs?: number,
   opts?: {
@@ -253,6 +259,7 @@ function buildProfileHealth(params: {
   };
 }
 
+/** Build profile and provider auth health rollups from an auth profile store. */
 export function buildAuthHealthSummary(params: {
   store: AuthProfileStore;
   cfg?: OpenClawConfig;

src/agents/auth-profile-runtime-contract.test.ts

@@ -1,3 +1,8 @@
+/**
+ * Runtime contract tests for auth profile forwarding.
+ * Ensures CLI and embedded agent runtimes receive the selected auth profile
+ * across provider aliases and plugin runtime manifests.
+ */
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/agents/auth-profiles/clone.ts

@@ -1,3 +1,8 @@
+/**
+ * Auth profile store cloning helpers.
+ * Keeps store snapshots JSON-serializable before callers mutate or persist
+ * profile state.
+ */
 import type { AuthProfileStore } from "./types.js";
 
 /** Deep-clones an auth profile store and rejects non-JSON values. */

src/agents/auth-profiles/constants.ts

@@ -1,3 +1,8 @@
+/**
+ * Shared auth-profile constants.
+ * Defines store versions, built-in CLI profile ids, lock budgets, refresh
+ * timing, and logging used by auth profile runtime modules.
+ */
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 export {
   AUTH_PROFILE_FILENAME,
@@ -5,16 +10,19 @@ export {
   LEGACY_AUTH_FILENAME,
 } from "./path-constants.js";
 
+/** Current persisted auth profile store schema version. */
 export const AUTH_STORE_VERSION = 1;
 
 /** @deprecated Anthropic provider-owned CLI profile id; do not use from third-party plugins. */
 export const CLAUDE_CLI_PROFILE_ID = "anthropic:claude-cli";
 /** @deprecated OpenAI provider-owned CLI profile id; do not use from third-party plugins. */
 export const CODEX_CLI_PROFILE_ID = "openai:codex-cli";
+/** Default OpenAI/Codex OAuth profile id used for migrated stores. */
 export const OPENAI_CODEX_DEFAULT_PROFILE_ID = "openai:default";
 /** @deprecated MiniMax provider-owned CLI profile id; do not use from third-party plugins. */
 export const MINIMAX_CLI_PROFILE_ID = "minimax-portal:minimax-cli";
 
+/** File-lock policy for auth profile store reads/writes. */
 export const AUTH_STORE_LOCK_OPTIONS = {
   retries: {
     retries: 10,
@@ -40,6 +48,7 @@ export const AUTH_STORE_LOCK_OPTIONS = {
 // Retry budget note: keep the MINIMUM cumulative retry window comfortably
 // above OAUTH_REFRESH_CALL_TIMEOUT_MS so waiters do not give up while a
 // legitimate slow refresh is still within its allowed runtime budget.
+/** Cross-agent lock policy for shared OAuth refresh operations. */
 export const OAUTH_REFRESH_LOCK_OPTIONS = {
   retries: {
     retries: 20,
@@ -56,9 +65,13 @@ export const OAUTH_REFRESH_LOCK_OPTIONS = {
 // surfaced as a refresh failure. Keep strictly below
 // OAUTH_REFRESH_LOCK_OPTIONS.stale so the lock is never treated as stale
 // by a waiter while the owner is still doing legitimate work.
+/** Maximum duration for one OAuth refresh call inside the refresh lock. */
 export const OAUTH_REFRESH_CALL_TIMEOUT_MS = 120_000;
 
+/** Freshness window for syncing external CLI auth into auth profiles. */
 export const EXTERNAL_CLI_SYNC_TTL_MS = 15 * 60 * 1000;
+/** Near-expiry threshold that triggers external CLI credential resync. */
 export const EXTERNAL_CLI_NEAR_EXPIRY_MS = 10 * 60 * 1000;
 
+/** Auth profile subsystem logger. */
 export const log = createSubsystemLogger("agents/auth-profiles");

src/agents/auth-profiles/credential-state.test.ts

@@ -1,3 +1,8 @@
+/**
+ * Tests credential eligibility and expiry classification.
+ * Protects missing, expired, near-expiry, and SecretRef credential handling for
+ * auth profile selection.
+ */
 import { describe, expect, it } from "vitest";
 import {
   DEFAULT_OAUTH_REFRESH_MARGIN_MS,

src/agents/auth-profiles/credential-state.ts

@@ -1,3 +1,8 @@
+/**
+ * Credential state classification for auth profiles.
+ * Centralizes expiry, missing-secret, and unresolved-reference checks used by
+ * auth selection, refresh, health, and doctor flows.
+ */
 import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion";
 import { coerceSecretRef, normalizeSecretInputString } from "../../config/types.secrets.js";
 import type { AuthProfileCredential, OAuthCredential } from "./types.js";

src/agents/auth-profiles/display.test.ts

@@ -1,3 +1,7 @@
+/**
+ * Tests auth profile display labels.
+ * Verifies configured display names/emails are used without fabricating labels.
+ */
 import { describe, expect, it } from "vitest";
 import { resolveAuthProfileDisplayLabel } from "./display.js";
 

src/agents/auth-profiles/display.ts

@@ -1,3 +1,7 @@
+/**
+ * Auth profile display labels.
+ * Combines profile ids with configured human metadata for CLI/status output.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { resolveAuthProfileMetadata } from "./identity.js";
 import type { AuthProfileStore } from "./types.js";

src/agents/auth-profiles/doctor.ts

@@ -1,3 +1,8 @@
+/**
+ * Provider-specific auth doctor hints.
+ * Adds local migration guidance for known legacy profiles before falling back
+ * to provider plugin doctor copy.
+ */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 import { buildProviderAuthDoctorHintWithPlugin } from "../../plugins/provider-runtime.runtime.js";