docs: document compaction planning helpers

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. */

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,

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

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[],

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;