From 2173d1bf472b97aedcf0d323b82ed89f4f256dde Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 09:17:00 -0400
Subject: [PATCH] docs: document compaction planning helpers

---
 src/agents/command-poll-backoff.runtime.ts |  4 +++-
 src/agents/compaction-planning-worker.ts   | 10 ++++++++++
 src/agents/compaction-planning.worker.ts   |  8 ++++++--
 src/agents/compaction-real-conversation.ts |  6 ++++++
 src/agents/compaction.ts                   |  7 +++++++
 5 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/src/agents/command-poll-backoff.runtime.ts b/src/agents/command-poll-backoff.runtime.ts
index 86055b20150f..ba22543a6ca1 100644
--- a/src/agents/command-poll-backoff.runtime.ts
+++ b/src/agents/command-poll-backoff.runtime.ts
@@ -1,6 +1,8 @@
+/**
+ * Runtime seam for command poll backoff cleanup.
+ */
 import { pruneStaleCommandPolls as pruneStaleCommandPollsImpl } from "./command-poll-backoff.js";
 
-// Runtime seam for command poll backoff cleanup.
 type PruneStaleCommandPolls = typeof import("./command-poll-backoff.js").pruneStaleCommandPolls;
 
 /** Prune stale command polls using the production backoff implementation. */
diff --git a/src/agents/compaction-planning-worker.ts b/src/agents/compaction-planning-worker.ts
index 94cd99fdb110..aac018363265 100644
--- a/src/agents/compaction-planning-worker.ts
+++ b/src/agents/compaction-planning-worker.ts
@@ -1,3 +1,7 @@
+/**
+ * Runs CPU-heavy compaction planning in a worker thread when histories are
+ * large enough to risk starving the main event loop.
+ */
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Worker } from "node:worker_threads";
@@ -191,6 +195,7 @@ async function runWithUnavailableFallback<T extends CompactionPlanningWorkerValu
   }
 }
 
+/** Builds summary chunks, offloading large histories to the planning worker. */
 export async function buildSummaryChunksWithWorker(params: {
   messages: AgentMessage[];
   maxChunkTokens: number;
@@ -219,6 +224,7 @@ export async function buildSummaryChunksWithWorker(params: {
   return value.chunks;
 }
 
+/** Builds an oversized-message fallback plan, using the worker when worthwhile. */
 export async function buildOversizedFallbackPlanWithWorker(params: {
   messages: AgentMessage[];
   contextWindow: number;
@@ -250,6 +256,7 @@ export async function buildOversizedFallbackPlanWithWorker(params: {
   };
 }
 
+/** Builds a staged summarization split plan with worker fallback. */
 export async function buildStageSplitPlanWithWorker(params: {
   messages: AgentMessage[];
   maxChunkTokens: number;
@@ -282,6 +289,7 @@ export async function buildStageSplitPlanWithWorker(params: {
   return value.mode === "split" ? { mode: "split", chunks: value.chunks } : { mode: "single" };
 }
 
+/** Builds a history-pruning plan with worker fallback for large transcripts. */
 export async function buildHistoryPrunePlanWithWorker(params: {
   messagesToSummarize: AgentMessage[];
   turnPrefixMessages: AgentMessage[];
@@ -324,6 +332,7 @@ export async function buildHistoryPrunePlanWithWorker(params: {
   };
 }
 
+/** Computes the adaptive compaction chunk ratio with worker fallback. */
 export async function computeAdaptiveChunkRatioWithWorker(params: {
   messages: AgentMessage[];
   contextWindow: number;
@@ -352,6 +361,7 @@ export async function computeAdaptiveChunkRatioWithWorker(params: {
   return value.ratio;
 }
 
+/** Test-only worker internals for URL resolution and error-path coverage. */
 export const compactionPlanningWorkerTesting = {
   resolveCompactionPlanningWorkerUrl,
   runCompactionPlanningWorker,
diff --git a/src/agents/compaction-planning.worker.ts b/src/agents/compaction-planning.worker.ts
index 5b94a46f5142..be3dea02a43a 100644
--- a/src/agents/compaction-planning.worker.ts
+++ b/src/agents/compaction-planning.worker.ts
@@ -1,3 +1,6 @@
+/**
+ * Worker-thread entrypoint for serializable compaction planning requests.
+ */
 import { parentPort, workerData } from "node:worker_threads";
 import {
   buildHistoryPrunePlan,
@@ -11,8 +14,7 @@ import {
 } from "./compaction-planning.js";
 import type { AgentMessage } from "./runtime/index.js";
 
-// Worker entry point for CPU-heavy compaction planning. Inputs are validated
-// before delegating to pure planning helpers so failures serialize cleanly.
+/** Serializable request accepted by the compaction planning worker. */
 export type CompactionPlanningWorkerInput =
   | {
       kind: "summaryChunks";
@@ -46,6 +48,7 @@ export type CompactionPlanningWorkerInput =
       contextWindow: number;
     };
 
+/** Serializable successful value returned by the compaction planning worker. */
 export type CompactionPlanningWorkerValue =
   | {
       kind: "summaryChunks";
@@ -65,6 +68,7 @@ export type CompactionPlanningWorkerValue =
       ratio: number;
     };
 
+/** Serializable success/failure envelope posted by the worker. */
 export type CompactionPlanningWorkerResult =
   | {
       status: "ok";
diff --git a/src/agents/compaction-real-conversation.ts b/src/agents/compaction-real-conversation.ts
index fb099a0e2257..fe12fa36cbe9 100644
--- a/src/agents/compaction-real-conversation.ts
+++ b/src/agents/compaction-real-conversation.ts
@@ -1,3 +1,7 @@
+/**
+ * Classifies transcript messages that contain real user-visible conversation
+ * for compaction and history pruning.
+ */
 import { stripHeartbeatToken } from "../auto-reply/heartbeat.js";
 import { isSilentReplyText } from "../auto-reply/tokens.js";
 import type { AgentMessage } from "./runtime/index.js";
@@ -26,6 +30,7 @@ function hasMeaningfulText(text: string): boolean {
   return true;
 }
 
+/** Returns whether a message has content worth preserving as conversation. */
 export function hasMeaningfulConversationContent(message: AgentMessage): boolean {
   if ((message as { role?: unknown }).role === "custom") {
     const custom = message as { content?: unknown; display?: unknown };
@@ -96,6 +101,7 @@ function isToolResultConversationAnchor(message: AgentMessage): boolean {
   );
 }
 
+/** Returns whether a transcript message should count as real conversation. */
 export function isRealConversationMessage(
   message: AgentMessage,
   messages: AgentMessage[],
diff --git a/src/agents/compaction.ts b/src/agents/compaction.ts
index 9869a259e96f..2b901ebf5575 100644
--- a/src/agents/compaction.ts
+++ b/src/agents/compaction.ts
@@ -1,3 +1,6 @@
+/**
+ * Summarization and fallback helpers for transcript compaction.
+ */
 import type { AgentCompactionIdentifierPolicy } from "../config/types.agent-defaults.js";
 import { formatErrorMessage } from "../infra/errors.js";
 import { retryAsync } from "../infra/retry.js";
@@ -78,6 +81,7 @@ const HANDOFF_INSTRUCTIONS = [
   "- Pending items and next intended steps.",
 ].join("\n");
 
+/** Optional instruction policy for preserving identifiers during compaction. */
 export type CompactionSummarizationInstructions = {
   identifierPolicy?: AgentCompactionIdentifierPolicy;
   identifierInstructions?: string;
@@ -121,6 +125,7 @@ function resolveIdentifierPreservationInstructions(
   return IDENTIFIER_PRESERVATION_INSTRUCTIONS;
 }
 
+/** Combines identifier-preservation and caller-provided compaction instructions. */
 export function buildCompactionSummarizationInstructions(
   customInstructions?: string,
   instructions?: CompactionSummarizationInstructions,
@@ -325,6 +330,7 @@ export async function summarizeWithFallback(params: {
   );
 }
 
+/** Summarizes history in multiple stages when a single pass would be too large. */
 export async function summarizeInStages(params: {
   messages: AgentMessage[];
   model: NonNullable<ExtensionContext["model"]>;
@@ -420,6 +426,7 @@ export async function summarizeForHandoff(params: {
   });
 }
 
+/** Resolves a positive context-window token count from model metadata. */
 export function resolveContextWindowTokens(model?: ExtensionContext["model"]): number {
   const effective =
     (model as { contextTokens?: number } | undefined)?.contextTokens ?? model?.contextWindow;