tests — context

tests — context

The tests/context module is a critical part of the codebase, dedicated to ensuring the robustness, correctness, and efficiency of the application's context management system. It provides comprehensive test coverage for the various components responsible for handling, processing, and optimizing conversational context for interactions with Large Language Models (LLMs).

This documentation outlines the purpose of the tests/context module and details the key components within src/context that are rigorously tested, highlighting their functionality and the specific aspects verified by the tests.

Core Context Management

The foundation of context handling revolves around a pluggable engine and a central manager, supported by a guard for token limits.

ContextEngine (Interface & DefaultContextEngine)

• Purpose: Defines a pluggable interface (ContextEngine) for custom context management logic, allowing different strategies to be swapped in. DefaultContextEngine provides a baseline implementation.
• Tested Aspects:
• Hook Call Order: Verifies that all lifecycle hooks (bootstrap, ingest, assemble, compact, afterTurn, prepareSubagentSpawn, onSubagentEnded) are called in the expected sequence.
• Default Behaviors: Confirms that the DefaultContextEngine performs pass-through operations for ingest and compact, and provides sensible defaults for assemble (returning messages with zero token count if no manager is set) and subagent context preparation (limiting messages based on role).
• ownsCompaction Flag: Tests the behavior of engines that declare ownsCompaction = true, demonstrating how they can take over the assemble step to implement custom message trimming.

ContextManagerV2

• Purpose: The central orchestrator for conversational context. It manages message history, applies various compaction strategies, and interacts with other context components to maintain an optimal context window for LLM interactions.
• Tested Aspects (specifically gap coverage from context-manager-v2-gaps.test.ts):
• Memory Metrics: Verifies the accurate tracking and reporting of summaryCount, summaryTokens, peakMessageCount, compressionCount, totalTokensSaved, lastCompressionTime, and warningsTriggered.
• Warning Thresholds: Ensures shouldWarn() correctly identifies when context usage exceeds configured thresholds (e.g., 50%, 75%, 90%) and that warnings are deduplicated (not re-triggered for the same threshold) and can be reset.
• Auto-Compaction: Tests shouldAutoCompact() to confirm it correctly signals when the current token count surpasses the autoCompactThreshold.
• Lifecycle Management: Verifies forceCleanup() resets metrics and clears warnings, and dispose() safely clears internal state and can be called multiple times.
• Enhanced Compression API: Checks the initial state and basic functionality of getLastCompressionResult(), listContextArchives(), and recoverFullContext().

ContextWindowGuard

• Purpose: Acts as a gatekeeper for the LLM's context window, preventing token overruns and providing warnings when usage approaches critical limits.
• Tested Aspects:
• Token Resolution Hierarchy: Verifies the correct priority for determining the effective context window size (session config > agent config > model config > model default > system default).
• Warning and Blocking Logic: Ensures evaluateContextWindowGuard() correctly identifies when to warn (below CONTEXT_WINDOW_WARN_BELOW_TOKENS) or block (below CONTEXT_WINDOW_HARD_MIN_TOKENS) based on current usage.
• Event Emission: Confirms the ContextWindowGuard class emits warning, blocked, and threshold-crossed events at appropriate times.
• Configuration: Tests that enableWarnings and enableBlocking flags correctly control the guard's behavior.
• Singleton Pattern: Verifies that getContextWindowGuard() consistently returns the same instance and resetContextWindowGuard() creates a fresh one.
• Utility Functions: Tests normalizePositiveInt() for input validation and shouldCompact() for determining when compaction is necessary.

Initial Context & Bootstrap

BootstrapLoader

• Purpose: Responsible for discovering and loading initial context files (e.g., BOOTSTRAP.md, SOUL.md) from both project-specific (.codebuddy/) and global directories at session start.
• Tested Aspects:
• File Discovery: Verifies that the loader correctly finds and loads single or multiple files from both project and global directories, and checks all default file names.
• Project Overrides Global: Ensures that project-level files take precedence over global files with the same name, and gracefully falls back to global if the project file is missing or empty.
• Token Limit & Truncation: Tests that content exceeding maxChars is truncated, and that the loader stops processing additional files once the limit is reached. It also verifies tokenCount accuracy.
• Security Pattern Rejection: Crucially, it tests the rejection of files containing dangerous patterns (e.g., eval(), require('child_process'),