Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUv3fcb4becad02
diff --git a/v3/implementation/adrs/ADR-051-infinite-context-compaction-bridge.md b/v3/implementation/adrs/ADR-051-infinite-context-compaction-bridge.md
index 0f0838e568..c033bd8122 100644
--- a/v3/implementation/adrs/ADR-051-infinite-context-compaction-bridge.md
+++ b/v3/implementation/adrs/ADR-051-infinite-context-compaction-bridge.md
@@ -315,6 +315,125 @@ function createHashEmbedding(text, dimensions = 768) {
}
```
+## Context Autopilot
+
+The Context Autopilot is a real-time context window management system that prevents
+Claude Code's automatic compaction from ever firing. Instead of letting the context
+window fill up and trigger lossy compaction, the autopilot tracks usage and optimizes
+proactively.
+
+### How It Works
+
+```
+Every User Prompt
+ β”‚
+ β–Ό
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ estimateContextTokens() β”‚ Read API usage from transcript JSONL
+β”‚ input_tokens + β”‚ (actual Claude API token counts, not
+β”‚ cache_read_input_tokens + β”‚ character estimates)
+β”‚ cache_creation_input_tokensβ”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚
+ β–Ό
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ Calculate percentage β”‚ tokens / CONTEXT_WINDOW_TOKENS (200K)
+β”‚ Update autopilot-state.jsonβ”‚ Persistent across hook invocations
+β”‚ Track growth history β”‚ Last 50 data points for trend analysis
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚
+ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+ β–Ό β–Ό β–Ό
+ <70% 70-85% 85%+
+ OK WARNING OPTIMIZE
+ β”‚ β”‚ β”‚
+ β”‚ β”‚ Prune stale archive entries
+ β”‚ β”‚ Keep responses concise
+ β”‚ β”‚ β”‚
+ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚
+ β–Ό
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ Inject report into context β”‚ [ContextAutopilot] [===----] 43% ...
+β”‚ via additionalContext β”‚ Includes: bar, %, tokens, trend
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+### Token Estimation (API-Accurate)
+
+The autopilot reads **actual API usage data** from the transcript JSONL, not character
+estimates. Each assistant message in the transcript contains:
+
+```json
+{
+ "message": {
+ "usage": {
+ "input_tokens": 45000,
+ "cache_read_input_tokens": 30000,
+ "cache_creation_input_tokens": 5000
+ }
+ }
+}
+```
+
+Total context = `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`
+
+This matches what Claude Code reports as context usage (e.g., "Context left until
+auto-compact: 8%" corresponds to ~92% usage). Falls back to character-based estimation
+(`chars / 3.5`) only when API usage data is unavailable.
+
+### Compaction Control
+
+| Trigger | Autopilot Behavior | Exit Code |
+|---------|-------------------|-----------|
+| `auto` (context full) | **BLOCKED** β€” archives turns, returns exit 2 | 2 |
+| `manual` (`/compact`) | **ALLOWED** β€” archives turns, resets autopilot state, proceeds | 0 |
+
+The shell wrapper in settings.json preserves exit code 2:
+```bash
+/bin/bash -c 'node ... pre-compact 2>/dev/null; RC=$?; if [ $RC -eq 2 ]; then exit 2; fi; exit 0'
+```
+
+This ensures hook crashes (exit 1) don't accidentally block compaction, while
+intentional blocking (exit 2) always propagates to Claude Code.
+
+### Statusline Integration (ADR-052)
+
+The autopilot state is read by the statusline script to display real-time metrics:
+
+```
+πŸ›‘οΈ 43% 86.7K ⊘ (autopilot active, 43% used, 86.7K tokens, no prune cycles)
+πŸ›‘οΈ 72% 144K ⊘ (warning zone, yellow color)
+πŸ›‘οΈ 88% 176K ⟳2 (prune zone, red, 2 optimization cycles completed)
+```
+
+### Optimization Phases
+
+| Phase | Threshold | Actions |
+|-------|-----------|---------|
+| **OK** | <70% | Normal operation, track growth trend |
+| **Warning** | 70-85% | Flag approaching limit, archive aggressively |
+| **Optimize** | 85%+ | Prune stale archive entries, increment prune counter, keep responses concise |
+
+### Autopilot State Persistence
+
+State is persisted to `.claude-flow/data/autopilot-state.json`:
+
+```json
+{
+ "sessionId": "f1bd5b59-...",
+ "lastTokenEstimate": 86736,
+ "lastPercentage": 0.434,
+ "pruneCount": 0,
+ "warningIssued": false,
+ "lastCheck": 1770750408022,
+ "history": [
+ { "ts": 1770749467007, "tokens": 45430, "pct": 0.227, "turns": 48 },
+ { "ts": 1770750408022, "tokens": 86736, "pct": 0.434, "turns": 53 }
+ ]
+}
+```
+
## Performance Budget
| Operation | Time Budget | Actual |