From d07cce7bd166e6c6ac254d990ad89dee5ff2b72e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 09:25:41 -0400 Subject: [PATCH] docs: document runner compaction helpers --- src/agents/embedded-agent-runner/abort.ts | 9 ++++----- src/agents/embedded-agent-runner/cache-ttl.ts | 9 +++------ src/agents/embedded-agent-runner/compact-reasons.ts | 6 ++++++ .../embedded-agent-runner/compact.hooks.harness.ts | 3 +++ src/agents/embedded-agent-runner/compact.queued.ts | 3 +++ src/agents/embedded-agent-runner/compact.runtime.ts | 6 +++--- .../embedded-agent-runner/compact.runtime.types.ts | 3 +++ src/agents/embedded-agent-runner/compact.ts | 3 +++ src/agents/embedded-agent-runner/compact.types.ts | 3 +++ .../compaction-duplicate-user-messages.ts | 10 ++++------ src/agents/embedded-agent-runner/compaction-hooks.ts | 9 +++------ .../compaction-runtime-context.ts | 3 +++ .../embedded-agent-runner/compaction-safety-timeout.ts | 3 +++ .../compaction-successor-transcript.ts | 3 +++ 14 files changed, 47 insertions(+), 26 deletions(-) diff --git a/src/agents/embedded-agent-runner/abort.ts b/src/agents/embedded-agent-runner/abort.ts index fe1aed3531a0..3e3daa9a646b 100644 --- a/src/agents/embedded-agent-runner/abort.ts +++ b/src/agents/embedded-agent-runner/abort.ts @@ -1,10 +1,9 @@ +/** + * Detects abort-shaped errors from embedded-agent runner dependencies. + */ import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce"; -/** - * Runner abort check. Catches any abort-related message for embedded runners. - * More permissive than the core isAbortError since runners need to catch - * various abort signals from different sources. - */ +/** Return true for AbortError objects or lower-level aborted messages. */ export function isRunnerAbortError(err: unknown): boolean { if (!err || typeof err !== "object") { return false; diff --git a/src/agents/embedded-agent-runner/cache-ttl.ts b/src/agents/embedded-agent-runner/cache-ttl.ts index 9e23ab63c54c..b7e1eb5e731e 100644 --- a/src/agents/embedded-agent-runner/cache-ttl.ts +++ b/src/agents/embedded-agent-runner/cache-ttl.ts @@ -1,3 +1,6 @@ +/** + * Resolves cache-TTL eligibility and session markers for prompt-cache retention. + */ import { normalizeLowercaseStringOrEmpty, normalizeOptionalLowercaseString, @@ -9,12 +12,6 @@ import { import { resolveProviderCacheTtlEligibility } from "../../plugins/provider-runtime.js"; import { isGooglePromptCacheEligible } from "./prompt-cache-retention.js"; -/** - * Cache-TTL eligibility and session markers for provider prompt-cache retention. - * - * Providers can override eligibility through plugin runtime hooks; built-in fallback logic covers - * Anthropic-family and Google prompt-cache semantics. - */ type CustomEntryLike = { type?: unknown; customType?: unknown; data?: unknown }; const CACHE_TTL_CUSTOM_TYPE = "openclaw.cache-ttl"; diff --git a/src/agents/embedded-agent-runner/compact-reasons.ts b/src/agents/embedded-agent-runner/compact-reasons.ts index da6486514d51..8ab8ba6a73c4 100644 --- a/src/agents/embedded-agent-runner/compact-reasons.ts +++ b/src/agents/embedded-agent-runner/compact-reasons.ts @@ -1,3 +1,6 @@ +/** + * Normalizes and classifies compaction failure reasons for diagnostics. + */ import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce"; import { sanitizeForLog } from "../../../packages/terminal-core/src/ansi.js"; @@ -11,6 +14,7 @@ function isGenericCompactionCancelledReason(reason: string): boolean { return normalized === "compaction cancelled" || normalized === "error: compaction cancelled"; } +/** Prefer a safeguard cancel reason when the runtime only reports generic cancellation. */ export function resolveCompactionFailureReason(params: { reason: string; safeguardCancelReason?: string | null; @@ -21,6 +25,7 @@ export function resolveCompactionFailureReason(params: { return params.reason; } +/** Bucket a raw compaction reason into stable telemetry/status classes. */ export function classifyCompactionReason(reason?: string): string { const text = normalizeLowercaseStringOrEmpty(reason); if (!text) { @@ -71,6 +76,7 @@ export function classifyCompactionReason(reason?: string): string { return "unknown"; } +/** Sanitize an unknown reason into a short log/metric-safe detail suffix. */ export function formatUnknownCompactionReasonDetail(reason?: string): string | undefined { const sanitized = sanitizeForLog((reason ?? "").replace(/\s+/g, " ")) .trim() diff --git a/src/agents/embedded-agent-runner/compact.hooks.harness.ts b/src/agents/embedded-agent-runner/compact.hooks.harness.ts index f4a99623d05a..5b1d5e263c66 100644 --- a/src/agents/embedded-agent-runner/compact.hooks.harness.ts +++ b/src/agents/embedded-agent-runner/compact.hooks.harness.ts @@ -1,3 +1,6 @@ +/** + * Test harness mocks for embedded-agent compaction hook coverage. + */ import { vi, type Mock } from "vitest"; import type { PluginMetadataSnapshot } from "../../plugins/plugin-metadata-snapshot.js"; import { clearAgentHarnesses } from "../harness/registry.js"; diff --git a/src/agents/embedded-agent-runner/compact.queued.ts b/src/agents/embedded-agent-runner/compact.queued.ts index e0e836cd96cf..300109149b9f 100644 --- a/src/agents/embedded-agent-runner/compact.queued.ts +++ b/src/agents/embedded-agent-runner/compact.queued.ts @@ -15,6 +15,9 @@ import { import { formatErrorMessage } from "../../infra/errors.js"; import { getGlobalHookRunner } from "../../plugins/hook-runner-global.js"; import type { ProviderRuntimeModel } from "../../plugins/provider-runtime-model.types.js"; +/** + * Queues embedded-agent session compaction onto the correct command lane. + */ import { enqueueCommandInLane } from "../../process/command-queue.js"; import { parseAgentSessionKey } from "../../routing/session-key.js"; import { resolveUserPath } from "../../utils.js"; diff --git a/src/agents/embedded-agent-runner/compact.runtime.ts b/src/agents/embedded-agent-runner/compact.runtime.ts index cc0f86ad39c5..7cd1530aad96 100644 --- a/src/agents/embedded-agent-runner/compact.runtime.ts +++ b/src/agents/embedded-agent-runner/compact.runtime.ts @@ -1,9 +1,9 @@ +/** + * Lazy-loads the embedded-agent compaction runtime. + */ import { createLazyImportLoader } from "../../shared/lazy-promise.js"; import type { CompactEmbeddedAgentSessionDirect } from "./compact.runtime.types.js"; -/** - * Lazy boundary for embedded session compaction. - */ const compactRuntimeLoader = createLazyImportLoader(() => import("./compact.js")); function loadCompactRuntime() { diff --git a/src/agents/embedded-agent-runner/compact.runtime.types.ts b/src/agents/embedded-agent-runner/compact.runtime.types.ts index 9dcdfffae59a..525728c7e3d8 100644 --- a/src/agents/embedded-agent-runner/compact.runtime.types.ts +++ b/src/agents/embedded-agent-runner/compact.runtime.types.ts @@ -1,3 +1,6 @@ +/** + * Types for the lazy embedded-agent compaction runtime boundary. + */ import type { CompactEmbeddedAgentSessionParams } from "./compact.types.js"; import type { EmbeddedAgentCompactResult } from "./types.js"; diff --git a/src/agents/embedded-agent-runner/compact.ts b/src/agents/embedded-agent-runner/compact.ts index d12ad028af19..261801f97330 100644 --- a/src/agents/embedded-agent-runner/compact.ts +++ b/src/agents/embedded-agent-runner/compact.ts @@ -1,3 +1,6 @@ +/** + * Implements embedded-agent transcript compaction and runtime handoff. + */ import fs from "node:fs/promises"; import os from "node:os"; import { isAcpRuntimeSpawnAvailable } from "../../acp/runtime/availability.js"; diff --git a/src/agents/embedded-agent-runner/compact.types.ts b/src/agents/embedded-agent-runner/compact.types.ts index 7dad8233a2be..e67a78430c30 100644 --- a/src/agents/embedded-agent-runner/compact.types.ts +++ b/src/agents/embedded-agent-runner/compact.types.ts @@ -1,3 +1,6 @@ +/** + * Shared parameter and metric types for embedded-agent compaction. + */ import type { SourceReplyDeliveryMode } from "../../auto-reply/get-reply-options.types.js"; import type { ReasoningLevel, ThinkLevel } from "../../auto-reply/thinking.js"; import type { OpenClawConfig } from "../../config/types.openclaw.js"; diff --git a/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts b/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts index 290cd7b7d1e5..e68963d97fa6 100644 --- a/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts +++ b/src/agents/embedded-agent-runner/compaction-duplicate-user-messages.ts @@ -1,11 +1,8 @@ +/** + * Removes short-window duplicate user turns from compaction summaries. + */ import { isRecord } from "@openclaw/normalization-core/record-coerce"; -/** - * Duplicate user-message filtering for compaction inputs. - * - * This removes immediate repeated user prompts from compaction summaries without touching short - * prompts, image-bearing prompts, or duplicates outside the retry window. - */ const DEFAULT_DUPLICATE_USER_MESSAGE_WINDOW_MS = 60_000; const MIN_DUPLICATE_USER_MESSAGE_CHARS = 24; @@ -61,6 +58,7 @@ function duplicateSignature(message: unknown): { key: string; timestamp: number }; } +/** Drop later duplicate user messages while preserving the first prompt. */ export function dedupeDuplicateUserMessagesForCompaction( messages: readonly T[], options: DuplicateUserMessageOptions = {}, diff --git a/src/agents/embedded-agent-runner/compaction-hooks.ts b/src/agents/embedded-agent-runner/compaction-hooks.ts index 759968844230..1477f432e212 100644 --- a/src/agents/embedded-agent-runner/compaction-hooks.ts +++ b/src/agents/embedded-agent-runner/compaction-hooks.ts @@ -1,3 +1,6 @@ +/** + * Runs compaction hooks and post-compaction side effects for embedded sessions. + */ import type { OpenClawConfig } from "../../config/types.openclaw.js"; import { createInternalHookEvent, triggerInternalHook } from "../../hooks/internal-hooks.js"; import { formatErrorMessage } from "../../infra/errors.js"; @@ -9,12 +12,6 @@ import { resolveMemorySearchConfig } from "../memory-search.js"; import type { AgentMessage } from "../runtime/index.js"; import { log } from "./logger.js"; -/** - * Compaction hook and side-effect helpers for embedded runner sessions. - * - * The runner calls these around transcript compaction so internal hooks, memory indexing, and - * transcript listeners observe one canonical compacted-session event. - */ function resolvePostCompactionIndexSyncMode(config?: OpenClawConfig): "off" | "async" | "await" { const mode = config?.agents?.defaults?.compaction?.postIndexSync; if (mode === "off" || mode === "async" || mode === "await") { diff --git a/src/agents/embedded-agent-runner/compaction-runtime-context.ts b/src/agents/embedded-agent-runner/compaction-runtime-context.ts index bbc0a9d5b01e..70d0fb02bed4 100644 --- a/src/agents/embedded-agent-runner/compaction-runtime-context.ts +++ b/src/agents/embedded-agent-runner/compaction-runtime-context.ts @@ -1,5 +1,8 @@ import type { SourceReplyDeliveryMode } from "../../auto-reply/get-reply-options.types.js"; import type { ReasoningLevel, ThinkLevel } from "../../auto-reply/thinking.js"; +/** + * Builds runtime context for context-engine backed embedded compaction. + */ import type { OpenClawConfig } from "../../config/types.openclaw.js"; import type { SkillSnapshot } from "../../skills/types.js"; import { normalizeOptionalAgentRuntimeId } from "../agent-runtime-id.js"; diff --git a/src/agents/embedded-agent-runner/compaction-safety-timeout.ts b/src/agents/embedded-agent-runner/compaction-safety-timeout.ts index 24060db03b74..febe10331707 100644 --- a/src/agents/embedded-agent-runner/compaction-safety-timeout.ts +++ b/src/agents/embedded-agent-runner/compaction-safety-timeout.ts @@ -1,4 +1,7 @@ import { finiteSecondsToTimerSafeMilliseconds } from "@openclaw/normalization-core/number-coercion"; +/** + * Wraps compaction calls with a safety timeout and abort cleanup. + */ import type { OpenClawConfig } from "../../config/types.openclaw.js"; import type { CompactResult, ContextEngine } from "../../context-engine/types.js"; import { withTimeout } from "../../node-host/with-timeout.js"; diff --git a/src/agents/embedded-agent-runner/compaction-successor-transcript.ts b/src/agents/embedded-agent-runner/compaction-successor-transcript.ts index 775f1a2e7205..912be8d80a60 100644 --- a/src/agents/embedded-agent-runner/compaction-successor-transcript.ts +++ b/src/agents/embedded-agent-runner/compaction-successor-transcript.ts @@ -1,3 +1,6 @@ +/** + * Rotates compacted sessions into successor transcript files when configured. + */ import { randomUUID } from "node:crypto"; import path from "node:path"; import { resolveTimestampMsToIsoString } from "@openclaw/normalization-core/number-coercion";