# pi-context-cost

`pi-context-cost` is a [pi](https://github.com/badlogic/pi-mono) extension that reduces coding-session context costs. It removes recoverable text from active model context while preserving the original text for restoration.

The extension starts in `observe` mode. This mode reports possible savings without changing model context.

## Features

The extension provides the following context controls:

- Records provider input, cache-read, cache-write, output, request, and cost data.
- Archives large text results from `bash`, `read`, `grep`, and `find` before their first model exposure.
- Keeps bounded, tool-specific previews in active context.
- Removes superseded file reads from the context copy sent to the model.
- Applies cache-aware local context slimming at profile thresholds.
- Compacts older history with an available Haiku model.
- Delegates bounded exploration to an isolated pi process.
- Restores archived tool results and fenced blocks on request.
- Stores owner-only artifacts and session audit logs.
- Removes expired artifacts after 30 days.

The extension doesn't modify errors, images, non-text results, or results from unknown tools.

## Install the extension

To install the npm package, run the following command:

```bash
pi install npm:pi-context-cost
```

Restart pi after installation.

To load a local checkout instead, install its dependencies and pass the extension path to pi:

```bash
bun install
pi -e ./extensions/context-cost.ts
```

## Choose an operating mode

New installations use `observe` mode. After you review the reported savings, enable `safe` mode:

```text
/cost-mode safe
```

The available modes have the following behavior:

| Mode | Context changes | Compaction trigger | Recent protected context |
|---|---|---:|---:|
| `observe` | Reports opportunities only | 65% | All content |
| `safe` | Applies reversible changes | 65% | 25% of the window, up to 64K tokens |
| `aggressive` | Applies earlier reversible changes | 55% | 16K tokens |

## Use commands

The extension registers the following commands:

| Command | Description |
|---|---|
| `/cost-status` | Shows provider usage, spend, archives, and estimated savings. |
| `/cost-mode MODE` | Selects `observe`, `safe`, or `aggressive` mode. |
| `/cost-compact` | Requests history compaction with the configured cheap model. |
| `/cost-shake` | Applies a one-time local tool-result slimming pass on the next request. |
| `/cost-shake --all` | Also slims large fenced user and assistant blocks. |
| `/cost-restore REFERENCE` | Adds recovered text to future model context. |
| `/cost-purge` | Deletes artifacts and audit data for the active session. |

`/cost-restore` accepts an artifact ID, a `cost-history://` reference, or a `cost-history-block://` reference. Restoration adds a new context message and doesn't rewrite old history.

## Configure model selection

The extension uses pi's model registry and existing provider credentials. It searches for an available Haiku model when you don't specify one.

To select explicit models, set one or both environment variables before you start pi:

```bash
export PI_CONTEXT_COST_SUMMARIZER_MODEL="PROVIDER/MODEL_ID"
export PI_CONTEXT_COST_WORKER_MODEL="PROVIDER/MODEL_ID"
```

If no cheap model is available, deterministic slimming continues to work. Pi handles compaction when custom summarization isn't available.

## Configure persistent settings

The extension reads `context-cost.json` from the pi project session directory. The `/cost-mode` command creates or updates this file.

The following example shows all supported settings:

```json
{
  "mode": "observe",
  "cacheTtl": "5m",
  "initialResultTokenThreshold": 12000,
  "previewTokenLimit": 2000
}
```

Use `"5m"`, `"1h"`, or a positive number of milliseconds for `cacheTtl`. Invalid values use the default settings.

The default limits are:

- Initial archive threshold: 12,000 estimated tokens.
- Preview limit: 2,000 estimated tokens.
- Artifact retention: 30 days.
- Delegate token ceiling: 50,000 tokens.
- Delegate cost ceiling: $0.25.

## Understand storage and recovery

The extension stores artifacts in the pi session directory:

```text
<context-cost-artifacts>/<session-hash>/
```

Artifact files use owner-only permissions. Each artifact directory contains an `audit.jsonl` file with metadata and recovery pointers. The audit log doesn't duplicate archived content.

The canonical pi session retains text removed only from a derived context view. Artifact-backed results retain their original text in the extension's storage directory.

## Run a benchmark

The package includes a benchmark command that reads pi JSONL session files. It counts main-model, nested-tool, and compaction usage.

To compare candidate sessions with the recorded baseline, run the following command:

```bash
bun run benchmark -- \
  --candidate PATH_TO_SESSION.jsonl \
  --task-success equal \
  --output benchmark-report.md
```

Repeat `--candidate` to combine candidate sessions. Repeat `--baseline` to provide paired baseline sessions. If you omit `--baseline`, the command uses the recorded specification baseline.

The command checks these acceptance gates:

- Spend decreases by at least 25%.
- Total tokens decrease by at least 40%.
- The request failure rate doesn't increase.
- Task success is equal or better.

The command exits with status `1` when any gate fails.

## Develop the extension

To run the test suite, use the following command:

```bash
bun test
```

To check TypeScript types, use the following command:

```bash
bun run typecheck
```

To inspect the npm package contents, use the following command:

```bash
npm pack --dry-run
```

## Token estimates

Local estimates use four characters per token. Use provider-reported usage as the source for billed token counts and cost.

## License

This project uses the MIT License.