140 lines
5.4 KiB
Markdown
140 lines
5.4 KiB
Markdown
## Implementation Plan: Enhanced Session Compaction System (9 High-Priority Fixes)
|
|
|
|
### Phase 1: Core Foundation (Types & Configuration)
|
|
|
|
**NEW: `packages/ui/src/stores/session-compaction.ts`**
|
|
|
|
1. **Compaction Types & Interfaces**
|
|
- `CompactionMessageFlags`: summary, mode, provenance flags
|
|
- `StructuredSummary`: Tier A/B schema with what_was_done, files, current_state, key_decisions, next_steps, blockers, artifacts, tags, provenance
|
|
- `CompactionEvent`: Audit trail with event_id, timestamp, actor, trigger_reason, token_before/after, model_used, cost_estimate
|
|
- `CompactionConfig`: autoCompactEnabled, autoCompactThreshold, compactPreserveWindow, pruneReclaimThreshold, userPreference, undoRetentionWindow
|
|
- `SessionCompactingHook`: Plugin contract for domain-specific rules
|
|
|
|
2. **Configuration Store**
|
|
- Default config: auto=80%, preserve=40k tokens, prune_threshold=20k, preference="ask"
|
|
- Export functions: `getCompactionConfig()`, `updateCompactionConfig()`
|
|
|
|
### Phase 2: Overflow Detection Engine
|
|
|
|
**MODIFY: `packages/ui/src/stores/session-compaction.ts`**
|
|
|
|
3. **Token Monitoring Functions**
|
|
- `isOverflowDetected(usage, modelLimit)`: Check if usage >= threshold%
|
|
- `shouldPruneToolOutputs(usage)`: Check if tool outputs > reclaim threshold
|
|
- `estimateTokenReduction(before, after)`: Calculate % reduction
|
|
|
|
4. **Audit Trail System**
|
|
- `recordCompactionEvent(sessionId, event)`: Append-only to audit log
|
|
- `getCompactionHistory(sessionId)`: Retrieve audit trail
|
|
- `exportAuditLog()`: For compliance/debugging
|
|
|
|
### Phase 3: Secrets Detection & Sanitization
|
|
|
|
**NEW: `packages/ui/src/lib/secrets-detector.ts`**
|
|
|
|
5. **Secrets Detector**
|
|
- Pattern matching for: api keys, passwords, tokens, secrets, credentials
|
|
- `redactSecrets(content)`: Returns { clean: string, redactions: { path, reason }[] }
|
|
- Placeholder format: `[REDACTED: {reason}]`
|
|
|
|
### Phase 4: AI-Powered Compaction Agent
|
|
|
|
**MODIFY: `packages/ui/src/stores/session-compaction.ts`**
|
|
|
|
6. **Compaction Agent Integration**
|
|
- `COMPACTION_AGENT_PROMPT`: Structured prompt with instructions
|
|
- `generateCompactionSummary(instanceId, sessionId, window)`: Call sendMessage() to get AI summary
|
|
- Parse response into Tier A (human) and Tier B (structured JSON)
|
|
|
|
7. **Execute Compaction**
|
|
- `executeCompaction(instanceId, sessionId, mode)`: Main compaction orchestration
|
|
- Steps: enumerate → plugin hooks → AI summary → sanitize → store → prune → audit
|
|
- Returns: preview, token estimate, compaction event
|
|
|
|
### Phase 5: Pruning Engine
|
|
|
|
**MODIFY: `packages/ui/src/stores/session-compaction.ts`**
|
|
|
|
8. **Sliding Window Pruning**
|
|
- `pruneToolOutputs(instanceId, sessionId)`: Maintain queue, prune oldest > threshold
|
|
- `isToolOutput(part)`: Classify build logs, test logs, large JSON
|
|
|
|
### Phase 6: Undo & Rehydration
|
|
|
|
**MODIFY: `packages/ui/src/stores/session-compaction.ts`**
|
|
|
|
9. **Undo System**
|
|
- `undoCompaction(sessionId, compactionEventId)`: Rehydrate within retention window
|
|
- `getCompactedSessionSummary(sessionId)`: Retrieve stored summary
|
|
- `expandCompactedView(sessionId)`: Return archived messages
|
|
|
|
### Phase 7: Integration
|
|
|
|
**MODIFY: `packages/ui/src/stores/session-events.ts`**
|
|
|
|
10. **Auto-Compact Trigger**
|
|
- Monitor `EventSessionUpdated` for token usage
|
|
- Trigger based on user preference (auto/ask/never)
|
|
- Call existing `showConfirmDialog()` with compaction preview
|
|
|
|
**MODIFY: `packages/ui/src/stores/session-actions.ts`**
|
|
|
|
11. **Replace compactSession**
|
|
- Use new `executeCompaction()` function
|
|
- Support both "prune" and "compact" modes
|
|
|
|
### Phase 8: Schema Validation
|
|
|
|
**NEW: `packages/ui/src/lib/compaction-validation.ts`**
|
|
|
|
12. **Schema Validation**
|
|
- `validateStructuredSummary(summary)`: Zod schema for Tier B
|
|
- `validateCompactionEvent(event)`: Zod schema for audit trail
|
|
- `ValidationErrors` type with path, message, code
|
|
|
|
### Phase 9: CI Tests
|
|
|
|
**NEW: `packages/ui/src/stores/session-compaction.test.ts`**
|
|
|
|
13. **Test Coverage**
|
|
- `test_overflow_detection`: Verify threshold calculation
|
|
- `test_secrets_redaction`: Verify patterns are caught
|
|
- `test_compaction_execution`: Full compaction flow
|
|
- `test_undo_rehydration`: Verify restore works
|
|
- `test_plugin_hooks`: Verify custom rules apply
|
|
|
|
### Phase 10: Canary Rollout
|
|
|
|
**MODIFY: `packages/ui/src/stores/session-compaction.ts`**
|
|
|
|
14. **Feature Flag**
|
|
- `ENABLE_SMART_COMPACTION`: Environment variable or config flag
|
|
- Default: `false` for canary, set to `true` for full rollout
|
|
- Graceful degradation: fall back to simple compaction if disabled
|
|
|
|
---
|
|
|
|
## Implementation Order (Priority)
|
|
|
|
1. **P0 - Foundation**: Types, config, schema validation (1-2, 12)
|
|
2. **P0 - Core Engine**: Overflow detection, secrets detector (3-5)
|
|
3. **P0 - AI Integration**: Compaction agent, execute function (6-7)
|
|
4. **P1 - Pruning**: Tool output classification, sliding window (8)
|
|
5. **P1 - Undo**: Rehydration system (9)
|
|
6. **P1 - Integration**: Session events, actions integration (10-11)
|
|
7. **P2 - Tests**: CI test coverage (13)
|
|
8. **P2 - Rollout**: Feature flag, canary enablement (14)
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
- ✅ AI generates meaningful summaries (not just "0 AI responses")
|
|
- ✅ Overflow detected before context limit exceeded
|
|
- ✅ Secrets are redacted before storage
|
|
- ✅ Audit trail tracks every compaction
|
|
- ✅ Undo works within retention window
|
|
- ✅ Schema validation prevents corrupt data
|
|
- ✅ CI tests ensure reliability
|
|
- ✅ Canary flag allows safe rollout |