docs: document runner compaction helpers

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;

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";

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()

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";

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";

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() {

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";
 

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";

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";

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<T extends MessageLike>(
   messages: readonly T[],
   options: DuplicateUserMessageOptions = {},

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") {

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";

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";

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";