feat: Implement Agent-Controlled Compaction

[AmaadMartin]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: #

2. Or, if no issue exists, describe the change:

Problem:
LLM agents can run out of context window if history grows too large. While automatic token-based compaction exists, agents do not have control over when compaction happens. This can lead to compaction happening in the middle of a complex subtask, potentially losing critical context needed to complete it.

Solution:
Implement Agent-Controlled Compaction. This feature allows agents to explicitly trigger context compaction when they determine it is safe to do so (e.g., after completing a subtask).

• Introduced ConsolidateContextTool (consolidate_context) which agents can call to request compaction.
• Introduced AgentControlledContextCompactor which triggers when the tool is called, compacts active history before the tool call, and optionally appends a summary instruction.

(Note: A planned refactoring to extract getActiveEvents into a shared utility for TokenBasedContextCompactor has been deferred to a follow-up PR to avoid merge conflicts with PR #474).

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Summary of passed npm test results (via vitest):

 ✓ core/test/context/token_based_context_compactor_test.ts (3 tests)
 ✓ core/test/tools/consolidate_context_tool_test.ts (3 tests)
 ✓ core/test/context/agent_controlled_context_compactor_test.ts (5 tests)

Manual End-to-End (E2E) Tests:

Integration tests verify the compaction behavior using a mock LLM and runner.

• Test file: tests/integration/context_compaction/agent_controlled/agent_test.ts
• Verifies that when the agent calls consolidate_context, history is compacted and a CompactedEvent is added.
• Result:

 ✓ tests/integration/context_compaction/agent_controlled/agent_test.ts (1 test)

E2E test structure is also added in tests/e2e/context_compaction/agent_controlled_e2e_test.ts using Gemini API (runs when API keys are available in the environment).

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

This PR introduces the core logic for Agent-Controlled Compaction.

Note on PR #474: There is currently an open PR (#474) awaiting review that modifies TokenBasedContextCompactor to fix token counting. To avoid merge conflicts, we have intentionally avoided modifying TokenBasedContextCompactor in this PR.

Upcoming Refactoring PR: We have staged a follow-up refactoring branch (refactor/compaction-utils) that extracts getActiveEvents into a shared utility for use by both the new AgentControlledContextCompactor and the existing TokenBasedContextCompactor. That PR will be submitted immediately after this PR and PR #474 are both merged.