NomadArch/.trae/documents/Implement AI-Powered Smart Session Compression.md

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