# Design and compatibility audit

## Package layout

The package has one Pi extension entry point:

```text
index.ts
```

That root entry registers its cooperating feature modules in this order:

```text
src/remote-compaction.ts
src/preemptive-compaction.ts
```

Standalone copies of the same extensions must not be enabled alongside the package, because Pi loads standalone files and package extensions independently.

## Current architecture

- `preemptive-compaction.ts` decides **when** to request compaction.
- `remote-compaction.ts` can decide **how** eligible `gpt-*` models are compacted.
- Actual execution remains Pi's ordinary `ctx.compact()` and `session_before_compact` chain.
- The preemptive extension never returns a compaction result from `session_before_compact`.

The primary threshold check runs at `turn_end`, after the current tool batch has completed. `agent_settled` remains a fallback for restored-session and usage edge cases. Pi 0.82 exposes `ctx.compact()` as fire-and-forget, so same-task continuation is best-effort: it is submitted only after successful compaction, only for a normal tool-use turn, and only when no newer pending input is detected. User input takes precedence.

## Threshold resolution

Resolution order:

1. `compaction.enabled: false` or `preemptive-compaction.enabled: false` disables the trigger.
2. `PI_PREEMPTIVE_COMPACTION_TOKENS`.
3. `PI_PREEMPTIVE_COMPACTION_RATIO`.
4. `preemptive-compaction.usePiNativeThreshold: true` uses Pi's effective reserve threshold, including Pi's default `reserveTokens: 16384` when unset.
5. Explicit `preemptive-compaction.thresholdTokens` or `.thresholdRatio`.
6. Active non-passive Observational Memory threshold.
7. Explicit Pi `compaction.reserveTokens`.
8. Default 85% of the active context window, with a 32,768-token floor.

A maximum-output safety cap prevents scheduling later than `contextWindow - model.maxTokens`. Pi-native threshold comparison is strict unless this cap lowers it to the last safe inclusive boundary.

## Remote routing and cost

| Model/API | Route |
| --- | --- |
| `gpt-*` + `openai-responses` | Opaque `/responses/compact`, encrypted checkpoint persistence, and Responses payload replay. |
| `gpt-*` + `openai-completions` | `/responses/compact` compatibility validation followed by a second `/chat/completions` text-summary request. |
| Other model/API | Returns `undefined`; later hooks or Pi fallback retain control. |

The compatibility path sends the serialized compacted segment twice to the configured endpoint family. When both responses expose usage, their token counts and configured-model estimated costs are combined into the saved compaction usage. This estimate follows the local model pricing configuration and may differ from provider invoices.

Opaque history always follows the latest compaction boundary. Consecutive opaque compactions carry forward the latest encrypted checkpoint. If another compaction mechanism produced the immediately preceding entry, the next opaque request includes that entry's text summary and does not search farther back for a stale opaque checkpoint.

Pi's `session_before_compact` result semantics are last-defined-result-wins unless a handler cancels. Therefore independent compaction-result hooks can supersede earlier results; installation order remains relevant and remote requests already completed by an earlier hook cannot be reclaimed.

## Rendered transcript retention

TUI cleanup is enabled by default. It mutates rendered components only; session JSONL, compaction summaries, and LLM context are unchanged. It keeps the newest rendered compaction result plus the configured recent tail. A forced full redraw is requested only if at least one rendered component was removed; that redraw can clear terminal scrollback.

The implementation depends on Pi 0.82's current TUI component shape and `CompactionSummaryMessageComponent` name. If that internal layout changes, cleanup safely no-ops rather than editing session state.

## Validation

Tracked tests cover:

- compaction-method labels;
- transcript retention and no-redraw no-op;
- boundary token estimates;
- continuation eligibility including error/length/abort/terminate cases;
- 85% default and native-threshold semantics;
- environment/settings precedence and compaction opt-out;
- response/chat usage normalization, cost calculation, tier pricing, and aggregation.

Run:

```bash
npm run check
npm test
npm pack --dry-run
```

## Residual limitations under Pi 0.82 APIs

1. `ctx.compact()` is fire-and-forget; Pi exposes no atomic “pause next provider request and await compaction” operation.
2. Pending-message detection and hidden continuation submission are not one atomic operation; the package rechecks after a timer boundary and always gives detected user input precedence.
3. Cross-extension compaction ownership is cooperative, not locked.
4. Opaque mode relies on Pi's installed Responses converter and request payload shape; resolution failure falls back safely.
5. TUI transcript pruning relies on current internal rendered component structure.