docs: document cli compat helpers

src/agents/command/cli-compaction.ts

@@ -1,3 +1,9 @@
+/**
+ * CLI turn compaction lifecycle.
+ *
+ * This module decides when CLI-backed sessions need context compaction, chooses
+ * native harness or context-engine compaction, and records resulting session state.
+ */
 import type { SessionEntry } from "../../config/sessions/types.js";
 import type { AgentCompactionMode } from "../../config/types.agent-defaults.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
@@ -123,10 +129,12 @@ const cliCompactionDeps: CliCompactionDeps = {
   recordCliCompactionInStore: recordCliCompactionInStoreImpl,
 };
 
+/** Overrides CLI compaction dependencies for focused tests. */
 export function setCliCompactionTestDeps(overrides: Partial<typeof cliCompactionDeps>): void {
   Object.assign(cliCompactionDeps, overrides);
 }
 
+/** Restores production CLI compaction dependencies after tests. */
 export function resetCliCompactionTestDeps(): void {
   Object.assign(cliCompactionDeps, {
     openSessionManager: (sessionFile: string) => SessionManager.open(sessionFile),
@@ -458,6 +466,8 @@ async function compactNativeHarnessCliTranscript(params: {
     const recoverableBindingFailure = isRecoverableNativeHarnessBindingFailure(result);
     const fallbackToContextEngine =
       isUnsupportedNativeHarnessCompaction(result) || recoverableBindingFailure;
+    // Native harness binding failures can be repaired by clearing the stored CLI
+    // session binding and falling back to the context engine for this turn.
     log.warn(
       `CLI native harness compaction did not reduce context for ${params.provider}/${params.model}: ${reason}`,
     );
@@ -472,6 +482,7 @@ async function compactNativeHarnessCliTranscript(params: {
   return { compacted: true, result };
 }
 
+/** Runs pre-turn compaction for a CLI session and returns the updated session entry. */
 export async function runCliTurnCompactionLifecycle(params: {
   cfg: OpenClawConfig;
   sessionId: string;
@@ -551,6 +562,8 @@ export async function runCliTurnCompactionLifecycle(params: {
       return;
     }
     autoCompactionGuardApplied = true;
+    // Apply once for the selected compaction path; settings are shared between
+    // native-harness and context-engine fallback attempts.
     await cliCompactionDeps.applyAgentAutoCompactionGuard({
       settingsManager,
       contextEngineInfo: contextEngine.info,
@@ -588,6 +601,7 @@ export async function runCliTurnCompactionLifecycle(params: {
       nativeCompactionResult = nativeOutcome.result;
       useContextEngineCompaction = false;
     } else if (nativeOutcome.fallbackToContextEngine) {
+      // Unsupported or recoverable native compaction should not abort the CLI turn.
       nativeFallbackToContextEngine = true;
       nativeFallbackNeedsBindingClear = nativeOutcome.clearCliSessionBinding === true;
     } else if (nativeOutcome.failureReason) {

src/agents/openai-completions-compat.ts

@@ -1,3 +1,9 @@
+/**
+ * OpenAI-completions compatibility defaults.
+ *
+ * Provider transports use these helpers to derive OpenAI-compatible request
+ * behavior from endpoint attribution without scattering provider-specific flags.
+ */
 import type { Model } from "../llm/types.js";
 import type { ProviderEndpointClass, ProviderRequestCapabilities } from "./provider-attribution.js";
 import { resolveProviderRequestCapabilities } from "./provider-attribution.js";
@@ -33,6 +39,7 @@ function isDefaultRouteProvider(provider: string | undefined, ...ids: string[])
   return provider !== undefined && ids.includes(provider);
 }
 
+/** Resolves default request flags for an OpenAI-compatible completions endpoint. */
 export function resolveOpenAICompletionsCompatDefaults(
   input: OpenAICompletionsCompatDefaultsInput,
 ): OpenAICompletionsCompatDefaults {
@@ -136,6 +143,7 @@ function resolveOpenAICompletionsCompatDefaultsFromCapabilities(
   return resolveOpenAICompletionsCompatDefaults(input);
 }
 
+/** Detects endpoint capabilities and defaults for an OpenAI-completions model. */
 export function detectOpenAICompletionsCompat(
   model: Pick<Model<"openai-completions">, "provider" | "baseUrl" | "id"> & {
     compat?: { supportsStore?: boolean } | null;

src/agents/subagent-registry.mocks.shared.ts

@@ -1,3 +1,9 @@
+/**
+ * Shared subagent registry mocks.
+ *
+ * Tests import this module to hoist gateway/event mocks consistently before
+ * registry modules resolve their runtime dependencies.
+ */
 import { vi } from "vitest";
 
 const noop = () => {};

src/agents/tool-display-config.ts

@@ -1,3 +1,9 @@
+/**
+ * Tool display metadata registry.
+ *
+ * Agent UIs use this config to map tool names/actions to stable titles,
+ * icons, and detail keys without embedding presentation data in tool handlers.
+ */
 import type { ToolDisplaySpec as ToolDisplaySpecBase } from "./tool-display-common.js";
 
 type ToolDisplaySpec = ToolDisplaySpecBase & {
@@ -10,6 +16,7 @@ type ToolDisplayConfig = {
   tools: Record<string, ToolDisplaySpec>;
 };
 
+/** Static display metadata for known tools plus fallback detail-key selection. */
 export const TOOL_DISPLAY_CONFIG: ToolDisplayConfig = {
   version: 1,
   fallback: {