feat: /acp compact — dedicated compression model (session shared-prefix + models.json)

CONFIGURATION.md

@@ -99,6 +99,7 @@ All keys below are currently **ACTIVE**.
 | `toolBashDefaultTimeout` | number | `60` | 🟢 ACTIVE | Default `bash` tool timeout in seconds when the model omits it. |
 | `toolOutputMaxBytes` | number | `200000` | 🟢 ACTIVE | Hard byte cap on tool result text. |
 | `throttleRetry` | boolean \| object | `true` | 🟢 ACTIVE | Auto-retry provider token rate-limit errors with progressive backoff. |
+| `compressionModelId` | string | *(unset)* | 🟢 ACTIVE | How `compress` summaries are produced: `session` (the session model, shared prefix) or a `models.json` id (`provider/id`). Usually set via `/acp compact [session\|<id>]`. |
 
 **Delegate keys**
 
@@ -340,6 +341,40 @@ On `anthropic` / `claude-sonnet-4-5` the effective thresholds become `maxContext
 
 ---
 
+## Compression Model
+
+The `compressionModelId` key designates **how** the `compress` tool's summaries are produced, so your main model spends no output tokens on them and the summary-writing reasoning stays out of its own turn. Two modes: **`session`** (the session's own model, in a separate call that reuses the session prompt prefix for prompt-cache efficiency) or a **`models.json` model id** (a cheaper model, reusing its `baseUrl`/`apiKey` already defined in `~/.pi/agent/models.json`).
+
+### `compressionModelId`
+
+- **Type:** `string`
+- **Default:** *(unset — the main model writes summaries)*
+- **Status:** 🟢 ACTIVE
+- **Description:** How summaries are produced. `session` uses the session's own model in a separate call that reuses the session prompt prefix (system prompt + active tools + the messages Pi just sent) so the provider prompt cache keeps the input cheap. A `models.json` id (`qwen-mini` or `provider/id`) uses that model instead (a different cache namespace — no prefix sharing — but a cheaper per-token price). In both modes the main model's own summary is kept only as a fallback. When unset, the main model writes the summaries itself (the default).
+
+  **Recommended way to set it:** the `/acp compact` command, which validates the id against `models.json` and persists it for you:
+
+   ```
+   /acp compact            # show current + list models.json models
+   /acp compact session    # use the session model (shared prefix → prompt-cache friendly)
+   /acp compact <id>       # set (e.g. /acp compact qwen-mini or /acp compact openai/gpt-4o-mini)
+   /acp compact reset      # clear → fall back to the main model
+   ```
+
+  You can also set it directly in `acp.json`:
+
+  ```json
+  { "compressionModelId": "openai/gpt-4o-mini" }
+  ```
+
+  **Resolution:** `session` resolves to the session's current model and reuses the captured session prefix; if no prefix has been captured yet (first turn) it falls back to a fresh prompt carrying the range's content. A bare id (`qwen-mini`) is matched against the models in `models.json`; if the same id exists under several providers the `provider/id` form is required. A `models.json` model must have a working API key (in `models.json` or `~/.pi/agent/auth.json`); `session` reuses the session's existing credentials.
+
+  **Fallback (guaranteed):** if the configured model cannot be resolved, or its API call fails (network error, timeout, API error, empty response), the extension logs a warning and uses the **main model's summary** for that range instead. Compression never blocks or interrupts the session.
+
+  **Scope:** read like any other `acp.json` key (global `~/.pi/acp.json`, with a project `<project>/.pi/acp.json` overriding it per-field). The `/acp compact` command writes to the **global** file.
+
+---
+
 ## Prompts Customization
 
 The `prompts` object overrides acp-kernel's **load-bearing** compression prompt rules — the verbatim instructions the model receives about *how* to write summaries (keep full file paths, function signatures, decisions and rationale; drop verbose logs, etc.). These four fields are embedded into the system prompt and the compression nudge text:

README.md

@@ -134,6 +134,29 @@ Blocks: 3 active (3.7K summary, 15.2K original compressed)
   b3 (T2)  3.3K→1.0K  age=1m  "Architecture review"
 ```
 
+## `/acp compact` — dedicated compression model
+
+By default the `compress` tool's summaries are written by your **main model** — it spends output tokens producing them, and the summary-writing reasoning runs inside the main model's own turn. `/acp compact` offloads summary-writing to a **separate call** in one of two modes:
+
+- **`session`** — use the **same model as your session**, but in a separate call that **reuses the session's prompt prefix** (system prompt + active tools + the exact messages Pi just sent). Because that prefix matches what the main model already sent, the provider's **prompt cache** makes the input cheap, and the compression reasoning stays out of the main model's context. Recommended way to get isolation without switching models.
+- **`<id>`** — a model from Pi's `~/.pi/agent/models.json` (a cheaper small Qwen, `gpt-4o-mini`, …). No extra `baseUrl`/`apiKey` to duplicate. A different model has its own cache namespace, so it does **not** share the session prefix cache (input is billed in full), but you save on the model's per-token price.
+
+```
+/acp compact            # show the current compression model + list available models
+/acp compact session    # use the session model (shared prefix → prompt-cache friendly)
+/acp compact <id>       # set <id> (or <provider>/<id>) from models.json as the compression model
+/acp compact reset      # clear it — fall back to the main model
+```
+
+- **No argument** (`/acp compact`): shows the currently configured compression model (or "not set — the main model writes summaries") and lists the model ids available in `models.json` for reference.
+- **`/acp compact session`**: sets the compression model to the session model (shared-prefix mode).
+- **`/acp compact <id>`**: sets a `models.json` model. Accepts a bare id (`qwen-mini`) or an explicit `provider/id` (`openai/gpt-4o-mini`). The choice is persisted to `~/.pi/acp.json` (`compressionModelId`) and applies across sessions.
+- **`/acp compact reset`**: clears the setting; compression falls back to the main model (the default behavior).
+
+When a compression model is set, each `compress` call produces the summary in a separate call, so the **main model spends no output tokens** on summaries. If the call fails (network error, API error, empty response), the extension **falls back to the main model's summary** for that range — compression never blocks the session.
+
+> For `<id>` mode the model must have a working API key (in `models.json` or `~/.pi/agent/auth.json`); `session` mode reuses your session's existing credentials. See [CONFIGURATION.md](./CONFIGURATION.md#compressionmodelid) for details.
+
 ## `/acp-subagents` command
 
 **Optional, one-time setup — only if you also use [pi-subagents](https://github.com/nicobailon/pi-subagents).**