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