docs: document models config runtime

src/agents/embedded-agent-subscribe.handlers.compaction.ts

@@ -1,3 +1,8 @@
+/**
+ * Handles embedded-agent compaction lifecycle events. The handlers pause
+ * liveness, emit agent events, run hooks, reconcile persisted counts, and
+ * clear stale usage after compaction rewrites history.
+ */
 import { emitAgentEvent } from "../infra/agent-events.js";
 import { getGlobalHookRunner } from "../plugins/hook-runner-global.js";
 import type { EmbeddedAgentSubscribeContext } from "./embedded-agent-subscribe.handlers.types.js";

src/agents/models-config.providers.implicit.ts

@@ -1,3 +1,8 @@
+/**
+ * Discovers implicit model-provider config from plugin provider catalogs and
+ * static catalogs. It merges discovered provider models with explicit config
+ * while preserving user-controlled provider fields.
+ */
 import {
   findNormalizedProviderValue,
   normalizeProviderId,
@@ -35,9 +40,6 @@ import {
   createProviderAuthResolver,
 } from "./models-config.providers.secrets.js";
 
-// Discovers implicit model providers from plugin catalogs and merges them with
-// configured provider state. Discovery is scoped for live lanes and can fall
-// back to static catalogs when runtime catalog calls are unavailable.
 const log = createSubsystemLogger("agents/model-providers");
 
 const PROVIDER_IMPLICIT_MERGERS: Partial<

src/agents/models-config.providers.ts

@@ -1,6 +1,8 @@
-// Provider-config public barrel. Keep provider normalization, implicit provider
-// discovery, policy hooks, and secret enforcement imports centralized here so
-// model config callers do not depend on each implementation file.
+/**
+ * Provider-config public barrel. It centralizes provider normalization,
+ * implicit discovery, policy hooks, and secret enforcement imports for
+ * models-config callers.
+ */
 export { resolveImplicitProviders } from "./models-config.providers.implicit.js";
 export {
   normalizeProviderCatalogModelsForConfig,

src/agents/models-config.ts

@@ -1,3 +1,8 @@
+/**
+ * Ensures the agent-local models.json and plugin model catalog sidecars match
+ * runtime config, discovered providers, auth-profile state, and generated
+ * catalog ownership.
+ */
 import fs from "node:fs/promises";
 import path from "node:path";
 import {
@@ -118,12 +123,14 @@ async function readExistingModelsFile(pathname: string): Promise<{
   }
 }
 
+/** Best-effort chmod for generated models.json and plugin catalog files. */
 export async function ensureModelsFileModeForModelsJson(pathname: string): Promise<void> {
   await fs.chmod(pathname, 0o600).catch(() => {
     // best-effort
   });
 }
 
+/** Atomic private-file-store write used by models.json generation. */
 export async function writeModelsFileAtomicForModelsJson(
   targetPath: string,
   contents: string,
@@ -282,6 +289,7 @@ async function withModelsJsonWriteLock<T>(targetPath: string, run: () => Promise
   }
 }
 
+/** Ensures models.json and plugin catalog sidecars are current for an agent. */
 export async function ensureOpenClawModelsJson(
   config?: OpenClawConfig,
   agentDirOverride?: string,

src/agents/provider-model-normalization.runtime.ts

@@ -1,3 +1,8 @@
+/**
+ * Runtime bridge for provider-owned model id normalization hooks. Source and
+ * built artifacts can resolve different extensions, so this module probes both
+ * once and caches the result.
+ */
 import { createRequire } from "node:module";
 
 type ProviderRuntimeModule = Pick<

src/agents/subagent-spawn.runtime.ts

@@ -1,4 +1,8 @@
-// Runtime dependency barrel for subagent spawning.
+/**
+ * Runtime dependency barrel for subagent spawning. Keeping these imports in a
+ * single module lets spawn tests replace runtime seams without loading the
+ * entire gateway/channel stack.
+ */
 export {
   DEFAULT_SUBAGENT_MAX_CHILDREN_PER_AGENT,
   DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH,