fix(#180): Update pnpm to 10.27.0 in Dockerfiles
Updated pnpm version from 10.19.0 to 10.27.0 to fix HIGH severity vulnerabilities (CVE-2025-69262, CVE-2025-69263, CVE-2025-6926). Changes: - apps/api/Dockerfile: line 8 - apps/web/Dockerfile: lines 8 and 81 Fixes #180
This commit is contained in:
190
docs/scratchpads/155-context-monitor.md
Normal file
190
docs/scratchpads/155-context-monitor.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# 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
|
||||
|
||||
- [x] Write comprehensive test suite (TDD RED phase)
|
||||
- [x] Implement ContextMonitor class (TDD GREEN phase)
|
||||
- [x] Implement ContextUsage model
|
||||
- [x] Add tests for IssueMetadata validators
|
||||
- [x] Run quality gates
|
||||
- [x] Fix linting issues (imports from collections.abc)
|
||||
- [x] Verify type checking passes
|
||||
- [x] Verify all tests pass (25/25)
|
||||
- [x] Verify coverage meets 85% requirement (100% for new files)
|
||||
- [x] 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
|
||||
|
||||
```python
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user