cprune-pi-extension 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## v0.2.0 - 2026-06-24
+
+First public release candidate for cprune as a Pi context-pruning extension.
+
+### Added
+
+- Global pruning modes: `off`, `safe`, and `full`.
+- Compact `/cprune` report comparing off/safe/full context sizes with red/orange/green bars.
+- Conservative persist-time pruning for duplicate, normalized-duplicate, append/repeated-prefix, and oversized tool results.
+- Prompt-time pruning for duplicate/append outputs, repeated line chunks, stale reads, entity/latest-wins snapshots, historical tool-call arguments, oversized old results, structured notices, and user-approved exclusions.
+- `/cprune review` for excluding selected large older context entries from future prompts.
+- `/cprune review-prompts [safe|full] [N] [page]` for excluding selected prompt/response turns.
+- `/cprune compact` for explicit lossy Pi compaction.
+- LLM-callable `cprune_status` tool for mode changes, compact requests, and off/safe/full comparison.
+
+### Changed
+
+- `/cprune` with no subcommand is now the primary status/statistics view.
+- Removed separate `/cprune status` and `/cprune stats` commands to keep the UI simpler.
+- Simplified the report by removing noisy rule/entity-family detail sections.
+
+### Safety notes
+
+- cprune does not rewrite active Pi session JSONL files.
+- Persist-time pruning is conservative but still replaces saved bytes for selected mechanical cases.
+- Prompt-time pruning is non-destructive to stored history but intentionally lossy in the model request.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reza Baram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# cprune Pi extension
+
+Context pruning extension for Pi. It reduces duplicate, append-only, stale, and oversized context before model calls. It can also request Pi's supported persistent compaction mechanism when you explicitly want a lossy summary.
+
+Append/contained pruning detects exact byte prefixes, normalized line-prefixes, substantial normalized contained blocks, and repeated line chunks, so it can catch repeated output with new lines appended even when ANSI escapes, CRLF/LF, trailing whitespace, small wrappers, or some middle insertions differ. Older repeated read-only snapshot commands such as `rg`, `find`, `ls`, and `git status` are also pruned when the same command is run again later. Old custom extension messages are deduped/truncated generically, structured entity notifications are compacted when superseded, and boilerplate “run/show for full context” tails are stripped without hardcoding one extension.
+
+Entity-aware pruning is generic rather than tied to one extension: it detects IDs like `TASK-123`, `SPEC-12`, `DISC-3`, `ISSUE-9`, `PR-42`, etc., then applies a latest-entity-snapshot-wins policy across older user messages, custom extension messages, tool results, assistant text, and summaries while preserving IDs, hashes, and short previews. Old successful assistant tool calls can be compacted to tool name, IDs/paths, hash, and preview, so large prior spec/comment bodies do not remain in request context. Non-core tool results with the same tool+entity are also superseded by newer successful results.
+
+## Highlights
+
+- Three operating modes: **off**, **safe**, and **full**.
+- `/cprune` shows a compact off/safe/full comparison with red/orange/green bars.
+- Conservative persist-time pruning handles exact/normalized duplicates, append repeats, and oversized tool results.
+- Prompt-time pruning removes stale, duplicate, oversized, or explicitly user-excluded context before model calls.
+- `/cprune review` and `/cprune review-prompts` let users explicitly exclude large entries or prompt/response turns without rewriting Pi history.
+- `/cprune compact` requests Pi's supported lossy compaction mechanism.
+
+## Screenshot
+
+![cprune off/safe/full context comparison](screenshot.png)
+
+## Safety and information loss
+
+cprune has two pruning points:
+
+- **Persist-time pruning** runs on new tool results before Pi stores them. This is intentionally conservative and limited to mechanical cases: exact duplicates, normalized duplicates where only ANSI/CRLF/trailing whitespace differ, append/prefix repeats, and oversized tool results with hash/original-size metadata plus retained head/tail preview.
+- **Prompt-time pruning** runs before a model request. It is non-destructive to Pi's active session files, but can be more aggressive because it only changes the context sent to the model for that request. `/cprune review` adds explicit user-approved prompt-time exclusions for large older entries; `/cprune review-prompts [safe|full] [N] [page]` lets you exclude a selected prompt/response turn from prompt history. These exclusions are persisted as cprune state, not by rewriting Pi history.
+
+cprune should not be described as fully lossless. Persist-time pruning is near-lossless but still replaces bytes in saved tool results for the safe cases above. Prompt-time pruning may replace older details with hashes, IDs, previews, and re-run hints. This reduces token use, but the model may no longer see every historical byte in the immediate request.
+
+cprune has three operating modes:
+
+- **off**: no pruning is applied to future tool results or model prompts.
+- **safe**: conservative mode. Persist-time pruning still handles mechanical duplicate/append/oversized tool results, and prompt-time pruning applies low-risk mechanical rules plus user-approved exclusions. It avoids semantic/latest-wins rules such as stale reads, entity snapshot pruning, old thinking removal, and historical tool-call argument compaction.
+- **full**: aggressive/default legacy behavior. Includes safe rules plus semantic/latest-wins prompt-time pruning, stale reads, entity/tool-result supersession, old thinking removal, and tool-call argument compaction.
+
+Risk levels:
+
+- Low risk / near-lossless: exact duplicates, normalized duplicates, exact append/prefix repeats, and repeated chunks where a newer full copy remains.
+- Medium risk: stale file-read pruning, superseded entity/tool-result pruning, structured notice compaction, and historical tool-call argument compaction.
+- Explicitly lossy: old assistant thinking removal, latest-entity-snapshot-wins summaries, and `/cprune compact`.
+
+Recommended wording: cprune uses **conservative near-lossless persist-time pruning** plus **non-destructive but lossy-at-prompt-time pruning**. It preserves recent context, errors, entity IDs, hashes, previews, and re-run hints, but it may remove historical details from saved tool results in safe mechanical cases and from the model request in broader prompt-time cases.
+
+## Install / use
+
+From this directory:
+
+```bash
+pi -e ./src/cprune.ts
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/amutix/cprune
+```
+
+Or install/configure it as a Pi package; `package.json` exposes `src/cprune.ts` under the `pi.extensions` field.
+
+## Commands
+
+```text
+/cprune                    Compare off/safe/full context sizes
+/cprune review             Pick large older context entries to exclude from future prompts
+/cprune review-prompts [safe|full] [N] [page] Pick a prompt/response turn from history
+/cprune clear-exclusions   Clear user-approved prompt-time exclusions
+/cprune safe               Enable conservative pruning
+/cprune full               Enable full/aggressive pruning (`on` is an alias)
+/cprune off                Disable pruning
+/cprune compact            Lossily compact/prune context via Pi compaction
+```
+
+## Tool
+
+cprune also registers an LLM-callable tool named `cprune_status`. Omitting `action` returns the same off/safe/full comparison as `/cprune`; actions `safe`, `full`, `off`, and `compact` change mode or request lossy compaction.
+
+`/cprune` works in any mode, so you can compare estimated savings before enabling pruning. The output compares **off** (red), **safe** (orange), and **full** (green), includes a few useful state counters, then shows the concise context-part breakdown.
+
+`/cprune review-prompts [safe|full] [N] [page]` is useful after accidentally pushing a noisy prompt/response/tool-output turn into context. Safe mode is the default and mirrors Pi prompt behavior: it skips hidden shell entries such as `!!cmd` because Pi marks them `excludeFromContext`, while keeping normal `!cmd` entries as selectable shell-command items. Full mode shows raw branch history, including hidden `!!cmd` entries, for users who want complete visibility. The selected turn is excluded from future prompts when it appears in model context; Pi session entries are not deleted. Results are paginated; jump directly with e.g. `/cprune review-prompts safe 50 2` or `/cprune review-prompts full 50`.
+
+Note: `/cprune compact` is intentionally named compact because it is lossy summarization. It does not rewrite Pi session JSONL files in place; it uses Pi's compaction API to append a normal compaction entry, which is safer for Pi's append-only session/tree model. Turning pruning off prevents future pruning; it does not reconstruct tool outputs that were already pruned before persistence.

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "cprune-pi-extension",
+  "version": "0.2.0",
+  "description": "Pi extension for safe/full context pruning, prompt review, and compact off/safe/full context comparisons.",
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "src/cprune.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@types/node": "latest",
+    "typebox": "latest",
+    "typescript": "latest"
+  }
+}