# pi-smart-compaction

Native-lifecycle compaction for Pi 0.83+: choose a dedicated local summary model and optionally reuse OpenAI Responses compaction artifacts.

## How it works

Pi remains the sole owner of compaction timing. The extension does not add threshold checks, compact between tool calls, create shadow checkpoints, or start synthetic continuations. Pi's existing `compaction.enabled`, `reserveTokens`, and `keepRecentTokens` settings decide when automatic compaction runs, and `/compact` continues to use Pi's native lifecycle.

When Pi starts a compaction:

1. If `compaction.json` selects a different model or reasoning effort, the extension asks that target to generate Pi's portable summary.
2. If that attempt fails, the extension returns control to Pi, which runs its built-in compaction once with the current session model.
3. If no override is configured, or the configured target exactly matches Pi's built-in target, Pi handles the local summary directly.

For models using the `openai` + `openai-responses` or `openai-codex` + `openai-codex-responses` pairing, the extension also starts Responses compaction v2 from the same native branch snapshot. A successful artifact is attached to the completed Pi compaction and preferred for compatible provider requests. The normal Pi summary remains canonical and is used when the latest compaction has no compatible artifact. Focused `/compact <instructions>` requests stay local-only because the remote protocol cannot preserve Pi's custom summary focus.

| Working provider | Portable summary | Optional request replay |
|---|---|---|
| `openai` + `openai-responses`, or `openai-codex` + `openai-codex-responses` | Configured target, then Pi built-in | Responses compaction v2 artifact |
| Other providers | Configured target, then Pi built-in | None |

## Install

From npm:

```bash
pi install npm:@kky42/pi-smart-compaction
```

Or from GitHub:

```bash
pi install git:github.com/kky42/pi-smart-compaction
```

## Configure

Create `~/.pi/agent/compaction.json`:

```json
{
  "model": "deepseek/deepseek-v4-flash",
  "reasoningEffort": "high"
}
```

Both fields are optional:

- `model` uses a `provider/model` selector.
- `reasoningEffort` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` and is clamped to the selected model.
- Omitted fields inherit the current session target.
- Missing or empty configuration leaves local compaction entirely to Pi.

Remote attempts start alongside local compaction. After Pi finishes the formal local compaction, an unfinished remote attempt gets at most a 2-minute completion grace period. If the grace period expires, or Pi cancels the compaction, the extension aborts remote authentication and transport, discards any artifact, and continues with the local summary.

"Local" means a portable Pi summary, not necessarily an on-device model. The selected compaction model receives the context being summarized. Eligible OpenAI or Codex sessions also send that context to their current Responses endpoint to create the optional remote artifact. Eligibility uses only provider and API type; custom `baseUrl` values are not filtered.

## Fallback behavior

- Configured local success: Pi commits that `CompactionResult`.
- Configured local failure: Pi runs its built-in compaction once.
- Remote failure: local compaction continues normally and no artifact is attached.
- Remote replay failure: the current request fails normally; the extension does not classify the error, retry it, or disable the artifact. A later compatible request reuses the artifact.
- Cancellation: the extension cancels instead of starting another fallback request.

Existing sessions containing old `pi-smart-compaction-shadow` entries remain readable. Those entries are no longer generated or used as context.

## Live validation

The unit and smoke suite runs without provider access:

```bash
npm test
```

Run the deterministic Pi RPC lifecycle integration with a local transport:

```bash
npm run test:integration
```

Run the opt-in real-provider RPC matrix with existing Pi credentials:

```bash
PI_SMART_COMPACTION_LIVE=1 npm run test:live
```