From ff43ede8878cad9fe5d3d3ee4162e2dbbc28e838 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 3 Jun 2026 23:45:12 -0400 Subject: [PATCH] docs: document cli compat helpers --- src/agents/command/cli-compaction.ts | 14 ++++++++++++++ src/agents/openai-completions-compat.ts | 8 ++++++++ src/agents/subagent-registry.mocks.shared.ts | 6 ++++++ src/agents/tool-display-config.ts | 7 +++++++ 4 files changed, 35 insertions(+) diff --git a/src/agents/command/cli-compaction.ts b/src/agents/command/cli-compaction.ts index 66417fd8c0d4..fa71c46406e1 100644 --- a/src/agents/command/cli-compaction.ts +++ b/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): 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) { diff --git a/src/agents/openai-completions-compat.ts b/src/agents/openai-completions-compat.ts index 0ea57fdbff64..a92a11bbfbed 100644 --- a/src/agents/openai-completions-compat.ts +++ b/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, "provider" | "baseUrl" | "id"> & { compat?: { supportsStore?: boolean } | null; diff --git a/src/agents/subagent-registry.mocks.shared.ts b/src/agents/subagent-registry.mocks.shared.ts index bae479f9126a..5f9f35668966 100644 --- a/src/agents/subagent-registry.mocks.shared.ts +++ b/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 = () => {}; diff --git a/src/agents/tool-display-config.ts b/src/agents/tool-display-config.ts index 2b9106ced8c1..57b9ff78493a 100644 --- a/src/agents/tool-display-config.ts +++ b/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; }; +/** Static display metadata for known tools plus fallback detail-key selection. */ export const TOOL_DISPLAY_CONFIG: ToolDisplayConfig = { version: 1, fallback: {