Context Compaction Engine

Relevant source files

The following files were used as context for generating this wiki page:

• packages/harness/src/compaction-prompts.ts
• packages/harness/src/checkpoint-history.ts
• packages/harness/src/compaction-policy.ts
• packages/harness/src/compaction-types.test.ts
• packages/harness/src/compaction-orchestrator.ts
• packages/harness/src/compaction-planner.ts
• packages/harness/src/tool-pruning.ts

The Context Compaction Engine is a core component of the plugsuits harness designed to manage Large Language Model (LLM) context windows through intelligent summarization and message history pruning. It ensures that long-running conversations remain within model token limits while preserving critical technical details, architectural decisions, and task progress.

The engine operates by monitoring token usage, triggering summarization routines when thresholds are met, and maintaining a structured "handoff" summary that replaces older conversation segments. This allows the agent to maintain high performance and context awareness even during complex, multi-turn software engineering tasks.

Core Architecture

The engine is structured as a multi-layered system involving policy definition, planning, and orchestration. It utilizes a "segment-based" approach where conversation history is divided into manageable blocks for evaluation and compaction.

Key Components

Component	Role	Source
CheckpointHistory	Manages the persistent and in-memory conversation log, tracking checkpoints and summaries.	packages/harness/src/checkpoint-history.ts
CompactionOrchestrator	Coordinates the timing of compaction tasks, including speculative (background) and blocking compactions.	packages/harness/src/compaction-orchestrator.ts
CompactionPolicy	Defines the logic for when compaction should occur based on token ratios and hard limits.	packages/harness/src/compaction-policy.ts
ModelSummarizer	A model-backed function that transforms raw message history into structured summaries.	packages/harness/src/compaction-prompts.ts
ToolPruning	Handles surgical removal of large tool outputs (e.g., broad file reads) to save space without full summarization.	packages/harness/src/tool-pruning.ts

Compaction Policies and Thresholds

Compaction is not a single event but a tiered process triggered by different usage levels. The engine uses thresholdRatio and speculativeStartRatio to determine when to act.

Trigger Logic

1. Speculative Compaction: Triggered when usage exceeds the speculativeStartRatio (often ~75% of the threshold). It runs in the background to prepare a summary before the limit is reached.
2. Blocking Compaction: Triggered when usage exceeds the thresholdRatio. This prevents the agent from sending a request that would exceed the model's context window.
3. Hard Limit Recovery: Triggered by specific error messages like context_length_exceeded or too many tokens in input.

Summarization Strategy

The engine utilizes highly structured prompts to ensure the LLM captures essential information. The default strategy uses a 5-section handoff format.

Handoff Summary Structure

• Current Goal: Verbatim quotes of the primary objective.
• Files & Changes: Precise lists of READ, MODIFIED, and CREATED files.
• Technical Discoveries: Patterns, decisions, and resolved errors.
• Strategy & Approach: Logic behind current actions and alternatives considered.
• Exact Next Steps: Directly actionable next items.

Sources: [packages/harness/src/compaction-prompts.ts:12-42](https://github.com/minpeter/plugsuits/blob/HEAD/packages/harness/src/compaction-prompts.ts#L12-L42)

Task-Aware Compaction

To prevent context drift, the engine supports a 2-step Task-Aware Compaction mode.

1. Intent Extraction: The model first extracts the "task intent" (e.g., refactoring, debugging) and identifies specific entities that must not be lost (e.g., specific file paths already explored).
2. Biased Summarization: The final summary is generated using this intent as a guide to prioritize relevant information.

Sources: [packages/harness/src/compaction-prompts.ts:167-190](https://github.com/minpeter/plugsuits/blob/HEAD/packages/harness/src/compaction-prompts.ts#L167-L190), [packages/harness/CHANGELOG.md:16-19](https://github.com/minpeter/plugsuits/blob/HEAD/packages/harness/CHANGELOG.md#L16-L19)

Implementation Details

Model Summarizer Configuration

The summarizer is configured via ModelSummarizerOptions, allowing for context limits and structured state injection.

export interface ModelSummarizerOptions {
  contextLimit?: number;
  getStructuredState?: () => string | undefined;
  instructions?: string | (() => string | Promise<string>);
  maxOutputTokens?: number;
  prompt?: string;
  taskAwareCompaction?: boolean;
}

Source: packages/harness/src/compaction-prompts.ts:74-88

Session Data Structures

Compaction state is tracked using several TypeScript interfaces to ensure consistency during history revisions.

Interface	Description
CheckpointMessage	A message in history that may include an isSummary flag.
CompactionResult	The outcome of a compaction job, including tokensBefore and tokensAfter.
PreparedCompaction	A speculative compaction result ready to be applied to the history.
StructuredState	Optional data (like TODOs) injected into the summarizer to maintain state.

Sources: [packages/harness/src/compaction-types.test.ts:86-130](https://github.com/minpeter/plugsuits/blob/HEAD/packages/harness/src/compaction-types.test.ts#L86-L130), [packages/harness/src/compaction-types.test.ts:316-340](https://github.com/minpeter/plugsuits/blob/HEAD/packages/harness/src/compaction-types.test.ts#L316-L340)

Performance and Recovery

The engine includes a Compaction Circuit Breaker to prevent infinite compaction loops, especially in scenarios with very small context windows. It tracks failures and can enforce a maxAcceptedCompactionsPerTurn (defaulting to 10) to ensure the system remains stable even if the model struggles to produce a valid summary.

Sources: [packages/harness/CHANGELOG.md:16-19](https://github.com/minpeter/plugsuits/blob/HEAD/packages/harness/CHANGELOG.md#L16-L19), [packages/headless/CHANGELOG.md:12-15](https://github.com/minpeter/plugsuits/blob/HEAD/packages/headless/CHANGELOG.md#L12-L15)

Context Management Parity

The engine implements several advanced features found in other professional AI coding tools:

• Context Collapse: Grouping consecutive read/search operations.
• Output Token Reserve: Reserving space for the model to actually generate the summary.
• Tool Pair Validation: Ensuring tool_result messages are never orphaned from their tool_call during history pruning.

Sources: [packages/harness/CONTEXT-MANAGEMENT-PARITY.md:5-25](https://github.com/minpeter/plugsuits/blob/HEAD/packages/harness/CONTEXT-MANAGEMENT-PARITY.md#L5-L25)

Conclusion

The Context Compaction Engine is critical for the autonomy of plugsuits. By combining proactive speculative summarization with reactive tool pruning and task-aware intent extraction, it allows the agent to handle large-scale engineering tasks that exceed standard LLM context windows without losing track of previous decisions or discoveries.