my-pi/pi-compaction

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;
• pass small tool results through unchanged whenever a stub would not be shorter;
• refine large stubs with non-blocking semantic summaries;
• expose one effective context projection to normal provider requests and Codex/SubAPI 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

Configuration lives in the installed bundle's config/pi-compaction.json (the bundle repository's config/ directory is the single source of truth; pi update refreshes the installed copy). The extension never reads settings.json and never writes config at runtime:

{
  "enabled": true,
  "softRatio": 0.72,
  "hardRatio": 0.9,
  "targetRatio": 0.55,
  "deterministic": {
    "enabled": true,
    "maxStubTokens": 1024
  },
  "semantic": {
    "enabled": true,
    "model": "default",
    "thinking": "low",
    "concurrency": 1,
    "minInputChars": 4000,
    "maxInputChars": 24000,
    "maxRetries": 2
  },
  "native": {
    "enabled": true
  }
}

Invalid or missing fields are normalized in memory.

Native providers

Native compaction is enabled by the native.enabled config key and uses the model selected in the session when compaction starts. It does not select a separate summarization model.

Provider	API	Native transport
openai-codex	openai-codex-responses	Existing Codex Responses endpoint and JWT/account-ID authentication
sub-api	openai-responses	Public Responses endpoint and resolved gateway headers or API key

For SubAPI, keep the existing models.json API as openai-responses. The adapter requires an explicit HTTP(S) baseUrl: for example, https://gateway.example/v1 becomes https://gateway.example/v1/responses; an existing /responses suffix is not duplicated. It preserves configured headers and merges the native compaction beta feature, without decoding the API key or adding a ChatGPT account ID. No gateway hostname or credentials are bundled.

SubAPI preserves a non-empty explicit Authorization header (case-insensitively) ahead of the API key. Without it, a non-blank API key supplies Bearer authentication; if no key is available, a non-empty cf-aig-authorization header also supports proxy-managed authentication. Header-only credentials do not create a dummy Bearer token. Missing or blank credentials fail before any network request and return control to Pi. Official Codex still requires its API key/JWT even when explicit authentication headers are present.

Both transports send the current projection as ResponseItems, append compaction_trigger, and parse the SSE compaction item. SubAPI must support Sub2API native remote compaction v2 on its public Responses endpoint. This is not a client for the separate /v1/responses/compact endpoint; supporting only that endpoint or ordinary Responses chat is insufficient.

Request interception also restores SubAPI native checkpoints into subsequent Responses input. Checkpoints retain a bounded portable summary for switching models/providers, and their version 1 format is unchanged. Native authentication, transport or response failures return control to Pi's normal compaction fallback. Other provider/API pairs and native.enabled: false retain the existing portable-summary path. Setting native.enabled to false does not discard an already-created native checkpoint.

The gateway must have a compatible deployed version, model and available upstream account. Offline tests cover the protocol and lifecycle; they do not establish live gateway availability. No settings migration, provider rename or Pi core modification is required.

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.

Projection replaces a tool result only when the resulting summary plus its Source: recovery line is strictly shorter than the original text content. Small tool results are therefore passed through byte-for-byte and keep their original content parts, including any non-text parts. Because a stub is only larger than the text it would replace when the original is short, this comparison is the sole gate; no separate size option exists. Every indexed result remains recoverable through context_tree_query whether or not the message was replaced.

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.