docs: document runtime utility helpers

src/agents/auth-profiles.ts

@@ -1,3 +1,5 @@
+// Public auth-profile barrel for agent/provider auth code. Keep external callers
+// on these exported contracts instead of deep auth-profile implementation files.
 export { CLAUDE_CLI_PROFILE_ID, CODEX_CLI_PROFILE_ID } from "./auth-profiles/constants.js";
 export type {
   AuthCredentialReasonCode,

src/agents/code-mode-control-tools.ts

@@ -2,6 +2,8 @@ import { isPlainObject } from "../utils.js";
 import { normalizeToolName } from "./tool-policy.js";
 import type { AnyAgentTool } from "./tools/common.js";
 
+// Code-mode control tool helpers. They mark exec/wait tools that belong to the
+// isolated code-mode runtime and keep before-tool-call params in code/command sync.
 export const CODE_MODE_EXEC_TOOL_NAME = "exec";
 export const CODE_MODE_WAIT_TOOL_NAME = "wait";
 export const CODE_MODE_EXEC_TOOL_KIND = "code_mode_exec";
@@ -15,11 +17,13 @@ export type CodeModeExecHookMetadata = {
 
 const codeModeControlTools = new WeakSet<AnyAgentTool>();
 
+/** Mark a tool as owned by code mode control flow. */
 export function markCodeModeControlTool<T extends AnyAgentTool>(tool: T): T {
   codeModeControlTools.add(tool);
   return tool;
 }
 
+/** Return whether a tool was marked as code-mode owned. */
 export function isCodeModeControlTool(tool: AnyAgentTool): boolean {
   return codeModeControlTools.has(tool);
 }
@@ -49,6 +53,8 @@ function normalizeCodeModeExecParams(params: unknown): unknown {
   const code = params.code;
   const command = params.command;
   if (typeof code === "string" && typeof command !== "string") {
+    // Code-mode accepts both `code` and generic exec `command`; keep them paired
+    // so downstream hooks can read either shape.
     return { ...params, command: params.code };
   }
   if (typeof command === "string" && typeof code !== "string") {
@@ -57,6 +63,7 @@ function normalizeCodeModeExecParams(params: unknown): unknown {
   return params;
 }
 
+/** Build before-tool-call metadata for a marked code-mode exec tool. */
 export function getCodeModeExecBeforeHookMetadata(params: {
   tool: AnyAgentTool;
   params: unknown;
@@ -71,6 +78,7 @@ export function getCodeModeExecBeforeHookMetadata(params: {
   };
 }
 
+/** Build before-tool-call metadata when only the tool kind is available. */
 export function getCodeModeExecBeforeHookMetadataForToolKind(params: {
   toolKind: unknown;
   params: unknown;
@@ -85,6 +93,7 @@ export function getCodeModeExecBeforeHookMetadataForToolKind(params: {
   };
 }
 
+/** Normalize before-hook params for a marked code-mode exec tool. */
 export function normalizeCodeModeExecBeforeHookParams(params: {
   tool: AnyAgentTool;
   params: unknown;
@@ -95,6 +104,7 @@ export function normalizeCodeModeExecBeforeHookParams(params: {
   return normalizeCodeModeExecParams(params.params);
 }
 
+/** Normalize before-hook params when only the code-mode tool kind is available. */
 export function normalizeCodeModeExecBeforeHookParamsForToolKind(params: {
   toolKind: unknown;
   params: unknown;
@@ -105,6 +115,7 @@ export function normalizeCodeModeExecBeforeHookParamsForToolKind(params: {
   return normalizeCodeModeExecParams(params.params);
 }
 
+/** Reconcile hook-adjusted `code` and `command` fields after code-mode normalization. */
 export function reconcileCodeModeExecBeforeHookParams(params: {
   tool: AnyAgentTool;
   originalParams: unknown;

src/agents/configured-provider-fallback.ts

@@ -1,10 +1,13 @@
 import type { OpenClawConfig } from "../config/types.js";
 
+// Selects a configured provider/model fallback when the default provider/model is
+// not present in models config.
 type ProviderModelRef = {
   provider: string;
   model: string;
 };
 
+/** Resolve the first configured provider/model that can replace a missing default. */
 export function resolveConfiguredProviderFallback(params: {
   cfg: Pick<OpenClawConfig, "models">;
   defaultProvider: string;
@@ -24,6 +27,8 @@ export function resolveConfiguredProviderFallback(params: {
   if (defaultProviderConfig && (!defaultModel || defaultProviderHasDefaultModel)) {
     return null;
   }
+  // Fall back to the first provider with at least one configured model, preserving
+  // config insertion order as operator preference.
   const availableProvider = Object.entries(configuredProviders).find(
     ([, providerCfg]) =>
       providerCfg &&

src/agents/console-sanitize.ts

@@ -1,3 +1,6 @@
+// Console text sanitizer for short diagnostic strings. It removes control
+// characters, flattens whitespace, and caps length before logging/display.
+/** Sanitize optional text for compact console output. */
 export function sanitizeForConsole(text: string | undefined, maxChars = 200): string | undefined {
   const trimmed = text?.trim();
   if (!trimmed) {

src/agents/context-runtime-state.ts

@@ -2,6 +2,8 @@ import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createLazyImportLoader, type LazyPromiseLoader } from "../shared/lazy-promise.js";
 import { MODEL_CONTEXT_TOKEN_CACHE } from "./context-cache.js";
 
+// Process-global context-window runtime state. Keeping this on globalThis avoids
+// duplicate model-config loads when modules are reloaded in tests/runtime seams.
 const CONTEXT_WINDOW_RUNTIME_STATE_KEY = Symbol.for("openclaw.contextWindowRuntimeState");
 
 type ContextWindowRuntimeState = {
@@ -17,6 +19,8 @@ export const CONTEXT_WINDOW_RUNTIME_STATE = (() => {
     [CONTEXT_WINDOW_RUNTIME_STATE_KEY]?: ContextWindowRuntimeState;
   };
   if (!globalState[CONTEXT_WINDOW_RUNTIME_STATE_KEY]) {
+    // The loader is lifecycle-owned here; callers reuse the same pending load
+    // promise and backoff counters instead of racing config discovery.
     globalState[CONTEXT_WINDOW_RUNTIME_STATE_KEY] = {
       loadPromise: null,
       configuredConfig: undefined,
@@ -28,6 +32,7 @@ export const CONTEXT_WINDOW_RUNTIME_STATE = (() => {
   return globalState[CONTEXT_WINDOW_RUNTIME_STATE_KEY];
 })();
 
+/** Reset context-window runtime state and token cache for isolated tests. */
 export function resetContextWindowCacheForTest(): void {
   CONTEXT_WINDOW_RUNTIME_STATE.loadPromise = null;
   CONTEXT_WINDOW_RUNTIME_STATE.configuredConfig = undefined;

src/agents/current-time.ts

@@ -6,6 +6,8 @@ import {
   resolveUserTimezone,
 } from "./date-time.js";
 
+// Current-time helpers for cron-style prompts and status lines. They include
+// both localized user time and a UTC reference for unambiguous scheduling.
 export type CronStyleNow = {
   userTimezone: string;
   formattedTime: string;
@@ -21,6 +23,7 @@ type TimeConfigLike = {
   };
 };
 
+/** Resolve localized and UTC current-time text for agent prompts. */
 export function resolveCronStyleNow(cfg: TimeConfigLike, nowMs: number): CronStyleNow {
   const userTimezone = resolveUserTimezone(cfg.agents?.defaults?.userTimezone);
   const userTimeFormat = resolveUserTimeFormat(cfg.agents?.defaults?.timeFormat);
@@ -32,6 +35,7 @@ export function resolveCronStyleNow(cfg: TimeConfigLike, nowMs: number): CronSty
   return { userTimezone, formattedTime, timeLine };
 }
 
+/** Append a current-time block unless the text already contains one. */
 export function appendCronStyleCurrentTimeLine(text: string, cfg: TimeConfigLike, nowMs: number) {
   const base = text.trimEnd();
   if (!base || base.includes("Current time:")) {