stack/docs/scratchpads/155-context-monitor.md

Issue #155: Build Basic Context Monitor

Objective

Build a context monitoring service that tracks agent token usage in real-time and identifies threshold crossings.

Implementation Approach

Following TDD principles:

1. RED - Created comprehensive test suite first (25 test cases)
2. GREEN - Implemented ContextMonitor class to pass all tests
3. REFACTOR - Applied linting and type checking

Implementation Details

Files Created

1. src/context_monitor.py - Main ContextMonitor class

   • Polls Claude API for context usage
   • Defines COMPACT_THRESHOLD (0.80) and ROTATE_THRESHOLD (0.95)
   • Returns appropriate ContextAction based on thresholds
   • Background monitoring loop with configurable polling interval
   • Error handling and recovery
   • Usage history tracking

2. src/models.py - Data models

   • ContextAction enum: CONTINUE, COMPACT, ROTATE_SESSION
   • ContextUsage class: Tracks agent token consumption
   • IssueMetadata model: From issue #154 (parser)

3. tests/test_context_monitor.py - Comprehensive test suite

   • 25 test cases covering all functionality
   • Mocked API responses for different usage levels
   • Background monitoring and threshold detection tests
   • Error handling verification
   • Edge case coverage

Key Features

Threshold-Based Actions:

• Below 80%: CONTINUE (keep working)
• 80-94%: COMPACT (summarize and free context)
• 95%+: ROTATE_SESSION (spawn fresh agent)

Background Monitoring:

• Configurable poll interval (default: 10 seconds)
• Non-blocking async monitoring
• Callback-based notification system
• Graceful error handling
• Continues monitoring after API errors

Usage Tracking:

• Historical usage logging
• Per-agent usage history
• Percentage and ratio calculations
• Zero-safe division handling

Progress

• Write comprehensive test suite (TDD RED phase)
• Implement ContextMonitor class (TDD GREEN phase)
• Implement ContextUsage model
• Add tests for IssueMetadata validators
• Run quality gates
• Fix linting issues (imports from collections.abc)
• Verify type checking passes
• Verify all tests pass (25/25)
• Verify coverage meets 85% requirement (100% for new files)
• Commit implementation

Testing Results

Test Suite

25 tests passed
- 4 tests for ContextUsage model
- 13 tests for ContextMonitor class
- 8 tests for IssueMetadata validators

Coverage

context_monitor.py: 100% coverage (50/50 lines)
models.py: 100% coverage (48/48 lines)
Overall: 95.43% coverage (well above 85% requirement)

Quality Gates

• ✅ Type checking: PASS (mypy)
• ✅ Linting: PASS (ruff)
• ✅ Tests: PASS (25/25)
• ✅ Coverage: 100% for new files

Token Tracking

• Estimated: 49,400 tokens
• Actual: ~51,200 tokens (104% of estimate)
• Overhead: Comprehensive test coverage, documentation

Architecture Integration

The ContextMonitor integrates into the Non-AI Coordinator pattern:

┌────────────────────────────────────────────────────────┐
│     ORCHESTRATION LAYER (Non-AI Coordinator)           │
│                                                         │
│  ┌─────────────────────────────────────────┐           │
│  │    ContextMonitor (IMPLEMENTED)         │           │
│  │  - Polls Claude API every 10s           │           │
│  │  - Detects 80% threshold → COMPACT      │           │
│  │  - Detects 95% threshold → ROTATE       │           │
│  └─────────────────────────────────────────┘           │
│                     │                                   │
│                     ▼                                   │
│  ┌─────────────────────────────────────────┐           │
│  │    Agent Coordinator (FUTURE)           │           │
│  │  - Assigns issues to agents             │           │
│  │  - Spawns new sessions on rotation      │           │
│  │  - Triggers compaction                  │           │
│  └─────────────────────────────────────────┘           │
└────────────────────────────────────────────────────────┘

Usage Example

from src.context_monitor import ContextMonitor
from src.models import ContextAction

# Create monitor with 10-second polling
monitor = ContextMonitor(api_client=claude_client, poll_interval=10.0)

# Check current usage
action = await monitor.determine_action("agent-123")

if action == ContextAction.COMPACT:
    # Trigger compaction
    print("Agent hit 80% threshold - compacting context")
elif action == ContextAction.ROTATE_SESSION:
    # Spawn new agent
    print("Agent hit 95% threshold - rotating session")

# Start background monitoring
def on_threshold(agent_id: str, action: ContextAction) -> None:
    if action == ContextAction.COMPACT:
        trigger_compaction(agent_id)
    elif action == ContextAction.ROTATE_SESSION:
        spawn_new_agent(agent_id)

task = asyncio.create_task(
    monitor.start_monitoring("agent-123", on_threshold)
)

# Stop monitoring when done
monitor.stop_monitoring("agent-123")
await task

Next Steps

Issue #155 is complete. This enables:

1. Phase 2 (Agent Assignment) - Context estimator can now check if issue fits in agent's remaining context
2. Phase 3 (Session Management) - Coordinator can respond to COMPACT and ROTATE actions
3. Phase 4 (Quality Gates) - Quality orchestrator can monitor agent context during task execution

Notes

• ContextMonitor uses async/await for non-blocking operation
• Background monitoring is cancellable and recovers from errors
• Usage history is tracked per-agent for analytics
• Thresholds are class constants for easy configuration
• API client is injected for testability

Commit

feat(#155): Build basic context monitor

Fixes #155
Commit: d54c653