feat: unify context compaction

pi-compaction/README.md

@@ -0,0 +1,63 @@
+# pi-compaction
+
+High-performance unified context projection and compaction for Pi.
+
+## Responsibilities
+
+- incrementally index completed tool calls;
+- replace large tool results with deterministic bounded evidence stubs;
+- refine large stubs with non-blocking semantic summaries;
+- expose one effective context projection to normal provider requests and Codex native compaction;
+- cancel Pi's raw threshold compaction until the effective lower-bound reaches the configured threshold;
+- retain original tool evidence through `context_tree_query`;
+- publish read-only effective metrics for the footer and context observer.
+
+Context Mode remains responsible for preventing large external data from entering the session. RTK remains responsible for ordinary tool-output cleanup.
+
+## Configuration
+
+Set `piCompaction` in the Pi agent `settings.json`:
+
+```json
+{
+  "piCompaction": {
+    "enabled": true,
+    "softRatio": 0.72,
+    "hardRatio": 0.9,
+    "targetRatio": 0.55,
+    "deterministic": {
+      "enabled": true,
+      "maxStubTokens": 256
+    },
+    "semantic": {
+      "enabled": true,
+      "model": "default",
+      "thinking": "low",
+      "concurrency": 1,
+      "minInputChars": 4000,
+      "maxInputChars": 24000,
+      "maxRetries": 2
+    },
+    "native": {
+      "enabled": true
+    }
+  }
+}
+```
+
+The extension never writes settings. Invalid or missing fields are normalized in memory.
+
+## Session format
+
+The only custom entry type is `pi-compaction`, version 1. Segment summary entries contain hashes, summaries, and source references; they never duplicate complete raw tool output. Native checkpoints use Pi compaction-entry details with the same kind/version.
+
+This implementation intentionally does not read legacy `context-prune-*` or `openai-codex-native-compaction` entries. Start a new session after switching to this extension.
+
+## Interfaces
+
+- `context_tree_query`: recover original bounded tool evidence by source key or tool call ID.
+- `/compaction-status`: show raw/effective tokens, reclaimed tokens, confidence, segments, and pending semantic jobs.
+
+## Performance model
+
+The first session hydration scans the branch once. Appended turns use delta projection and immutable cached snapshots. The `context` hook performs no model call and no session write. Semantic summaries run in a bounded background worker and become visible only at later safe event boundaries.