## 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