pi-precompact 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+Versions follow SemVer. Future entries come from Markdown changesets.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the release workflow.
+
+## 0.2.0 - 2026-10-26
+
+### Added
+
+- Show the precompact state in the footer from session start, including idle, paused, off, and unavailable.
+- Open a status card for /precompact status and announce adopted background summaries.
+- Draw a context bar in Pi's built-in footer with the background start, Pi's threshold, the state, and the expected context after adoption; Pi's own context text stays unchanged.
+- Show nothing in the footer before the first measured response, like Pi, then fade the context bar in once. PI_PRECOMPACT_MOTION=off shows it without animation.
+- Publish the package on npm. Install it with `pi install npm:pi-precompact`.
+
+### Changed
+
+- Name the package pi-precompact, with the command /precompact and the motion variable PI_PRECOMPACT_MOTION.
+- Show the footer short form as pre and Pi's status text as precompact: <state>.
+
+## 0.1.0 - 2026-10-25
+
+Local development baseline, not an npm publication.
+
+### Added
+
+- Prepare native Pi 1.4.0 compaction summaries in the background without interrupting the agent.
+- Apply valid summaries only at native threshold compaction, with cancellation, context validation, and foreground fallback.

package/CONTRIBUTING.md

@@ -0,0 +1,152 @@
+# Contributing
+
+## Setup and checks
+
+Use Node.js 22.19+ and Python 3.11+. Git, npm, Make, and tar must be on `PATH`.
+The lockfile pins development dependencies. Pi supplies the runtime SDK.
+Run all commands from the repository root.
+
+```sh
+npm ci --ignore-scripts
+make hooks-install
+make verify
+```
+
+`make verify` and CI run the same checks:
+
+- Biome formatting, import order, and recommended lint rules.
+- Strict TypeScript checks.
+- Unit tests and Pi SDK integration tests with a local scripted provider.
+- A real npm tarball check, including loading the extracted extension without packaged development dependencies.
+- Changeset parser, Git hook, and release tests in disposable repositories.
+- Pending changeset and manifest/lockfile validation.
+
+The CI definition covers Linux and macOS with Node.js 22 and 24.
+It needs no provider credentials and has read-only GitHub permissions.
+There is no automatic npm publication, OIDC, or release-token workflow.
+
+To apply formatting:
+
+```sh
+npm run format
+```
+
+Do not relax tests to accept an unsupported Pi version. Review the private native adapter before changing the exact SDK pin.
+Runtime changes need applicable regression and integration tests. Pure tooling changes do not need live-provider calls or GUI tests.
+
+## Changesets
+
+This repository uses a small Python changeset flow, not `@changesets/cli`.
+Every non-merge, non-release commit adds one new Markdown changeset.
+Write notes for changelog readers, not as copies of commit messages.
+
+For documentation, tests, formatting, or internal tooling without a release note, add an explicit empty changeset.
+Editing a note from an earlier commit does not count as a new changeset.
+Do not bypass the hook.
+
+Interactive entry:
+
+```sh
+make changeset
+```
+
+Non-interactive entry:
+
+```sh
+python3 scripts/changeset.py add --type fixed --bump patch "Preserve newer messages after compaction."
+python3 scripts/changeset.py add --empty
+```
+
+Stage the generated file with the change it describes. Example note:
+
+```markdown
+---
+type: fixed
+bump: patch
+---
+
+Preserve newer messages after compaction.
+```
+
+| Field | Values |
+| --- | --- |
+| `type` | `added`, `changed`, `fixed`, `removed` |
+| `bump` | `patch`, `minor`, `major` |
+
+The highest pending bump wins. Bumps do not add together.
+Only stable `X.Y.Z` versions are supported. There is no special 0.x rule.
+
+An empty changeset contains two `---` lines. It generates no note or version bump.
+The next release with real notes consumes pending empty changesets too.
+
+Keep related unpublished notes consistent. Do not rewrite published changelog history.
+A changeset is neither release authorization nor evidence of acceptance.
+
+### Hook behavior
+
+Install the hook once per clone with `make hooks-install`.
+The installer preserves existing hooks and `core.hooksPath`. Integrate `check-staged` into an existing hook manager instead.
+
+The hook locates Python 3.11+ on `PATH`. It does not install Python or activate Nix.
+
+The hook checks staged content, not unstaged edits:
+
+- Merge commits use notes from the merged branches. Staged notes still need valid syntax.
+- Amend checks use the commit's parent, so the original note counts.
+- Release commits must exactly match the generated manifest, lockfile, changelog, and consumed notes.
+
+The hook rejects hand-edited version bumps, mismatched lockfile versions, and unrelated changes in release commits.
+CI validates pending notes and tests hook behavior. It does not enforce changesets across all historical commits.
+
+## Prepare a release
+
+Prepare a version only after an explicit release request, from clean `main` with verified, committed changesets.
+Use the changeset tool, not `npm version` or a manual version edit.
+
+```sh
+make changeset-status
+make version
+make verify
+```
+
+`make version` plans all outputs before writing. It:
+
+1. Selects the highest pending SemVer bump.
+2. Updates the version in the package manifest.
+3. Updates the lockfile version and its root package version, without resolving dependencies.
+4. Prepends a dated changelog section and removes all consumed changesets.
+
+It does not run npm, commit, tag, push, install, or publish.
+Review the diff. Commit only the generated release files, with a message such as `version bump to v0.1.1`.
+Feature branches keep their notes until merge. They do not prepare releases.
+
+### Publish a release
+
+A maintainer publishes each release by hand from a local machine, with npm two-factor authentication.
+
+1. Prepare the version with `make version` and commit only the generated release files.
+2. Push `main` and wait for green CI on that exact release commit.
+3. Run the read-only publication gate:
+
+   ```sh
+   npm run release:check
+   ```
+
+   It requires clean `main`, synchronized versions, no pending notes, and an exact changeset-generated release at `HEAD`.
+   It also checks the publication metadata and runs the normal checks. `prepublishOnly` runs the same gate.
+4. Run `npm publish --provenance=false`. A local release has no npm provenance.
+5. Check the exact version on the registry, and install it with `pi install npm:pi-precompact@<version>` in a clean Pi home.
+6. Tag the release commit as `v<version>`, push the tag, and create the GitHub release from the changelog section.
+
+Do not republish a version that the registry already accepted. Repair only the missing tag or release.
+
+## Reference choices
+
+The small Pi plugins supplied the package shape: source exports, explicit Pi resources, host peer dependencies, narrow tarball contents, and CI checks.
+Pi Dynamic Workflows supplied the Biome and pre-publication verification pattern.
+This repository does not copy automatic publishing workflows from existing plugins.
+
+The changeset tool adapts the author's changeset scripts from the TWS, Zugriff-Menu, and Teams-GPUI projects.
+`scripts/LICENSE.tws` keeps the TWS MIT notice.
+This adaptation replaces Cargo version handling with single-package npm version handling.
+It does not copy Teams-GPUI's backlog exemption, Nix fallback, or application installation steps.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Wozniak
+
+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

@@ -1,3 +1,220 @@
-# Temporary Holding Version
+# pi-precompact
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An experimental Pi extension that prepares compaction summaries while the agent continues its work.
+Pi still decides when to compact. The extension supplies a valid prepared summary at that boundary, or leaves the request to Pi.
+
+Inspired by [OpenCode background compaction](https://github.com/anomalyco/opencode/pull/57444).
+This is an independent implementation, not an OpenCode port.
+
+Not related to the npm package `pi-background-compaction`.
+
+## Status
+
+- Targets `@earendil-works/pi-coding-agent` **1.4.0** only.
+- Uses Pi's native context projection, preparation, and summary generator.
+- Does not abort the agent or inject a `continue` message.
+- Does not install itself, change settings, or run a background process.
+- Has deterministic unit tests and SDK integration tests with Pi's local Faux provider.
+- Has no live-provider endurance or latency benchmark yet.
+
+## Install
+
+```sh
+pi install npm:pi-precompact
+```
+
+New sessions load the extension. Run `/reload` in a session that is already open.
+To try it for one invocation without changing settings:
+
+```sh
+pi -e npm:pi-precompact
+```
+
+Do not combine it with another extension that replaces compaction.
+
+Commands:
+
+```text
+/precompact status
+/precompact off
+/precompact on
+/precompact reset
+```
+
+These commands affect only the current session. `reset` cancels the prepared job and clears the failure counter.
+
+`/precompact` and `/precompact status` open a status card in the TUI, in place of the editor.
+The card appears only on this explicit request. It shows the state and last event, a context bar with the plugin's start and Pi's threshold,
+the expected result of a held summary, the request usage, and the failure count. It updates every second.
+Press `r` to reset, `o` to switch off or on, and Escape or Enter to close. RPC, JSON, and print modes keep the one-line answer.
+
+When Pi adopts a background summary, the TUI and RPC clients receive one notice, for example:
+
+```text
+✓ Background summary applied · no wait · 249k → ~38k tokens · prepared in 48s
+```
+
+`waited 12s` replaces `no wait` when Pi had to wait for a running request. The token value after `→` is Pi's estimate.
+Native fallback compactions produce no notice.
+
+The plugin sets one footer status from session start, `precompact: <state>`:
+
+| State | Meaning |
+| --- | --- |
+| `idle` | Enabled; no summary is in progress. |
+| `running` | Preparing a summary while the agent continues. |
+| `ready` | Holding a summary until Pi requests threshold compaction. |
+| `paused` | Two background requests failed; native compaction remains available. |
+| `off` | Disabled for this session, or native auto-compaction is disabled. |
+| `unavailable` | Unsupported Pi installation, virtual model, or no model selected. |
+
+In Pi's built-in TUI footer, the plugin moves this status from the status row into the statistics line.
+Pi's own context segment stays exactly as Pi renders it. From 100 columns, a context bar comes before it:
+
+```text
+━━━━━━━━━━━━━━━━━━━│━━━─│─ 91.6%/272k (auto) → ~14%
+```
+
+- The accent mark is where background preparation starts. The error mark is where Pi compacts.
+- The fill uses the state colour: `running` accent, `ready` success, `paused` warning, the others muted or dim.
+- `→ ~14%` follows while a summary is ready: the estimated context after Pi adopts it.
+- `✓ pre` follows directly after an adopted summary, until the next change.
+- `pre running`, `pre ready` (without an estimate), `pre paused`, `pre off`, and `pre unavailable` name the other states.
+
+Below 100 columns the line shows `91.6%/272k (auto) pre: ready` instead. When even that does not fit,
+or the footer has an unknown layout, Pi's status row keeps `precompact: <state>`.
+
+Before the first response with token usage, Pi shows only its context value and no usage numbers.
+The plugin then shows nothing either: no bar, no `pre` text, and no status row entry.
+With the first measured response, the bar fades in once:
+
+- Pi's numbers appear at once; the bar reserves its columns in the same frame.
+- Each glyph fades from the terminal background to its colour in 120 ms, 5 ms after its left neighbour.
+- The fill grows from 80 to 240 ms. A frame follows every 40 ms; the easing is `cubic-bezier(0.23, 1, 0.32, 1)`.
+- A new width, value, or state during the animation shows the final bar at once.
+- Sessions with earlier responses, for example after `/resume` or `/reload`, show the bar without animation.
+
+The plugin asks the terminal for its background colour once, as Pi's theme does.
+Without an answer or without truecolor, each glyph appears directly in its colour as the wave reaches it.
+Set `PI_PRECOMPACT_MOTION=off` before starting Pi to show the bar without animation.
+The design is on pages 04 and 05 of `design/figcraft/footer-status.figcraft`.
+
+Use `/precompact status` for the last event and failure count.
+Pi's `(auto)` context indicator refers to native automatic compaction, not this plugin.
+
+Pi has no public API to place text inside its footer. A zero-row widget below the editor finds the one mounted
+built-in `FooterComponent` and wraps the render method of that instance; the prototype stays untouched.
+The plugin reads the instance's status provider read-only and never modifies shared statuses.
+Other footer decorators can wrap the same instance before or after it; each keeps the other's lines.
+Custom footers are left alone. Shutdown and reload restore Pi's method and clear this plugin's status only.
+JSON, print, and RPC modes receive no terminal status or footer decoration.
+
+To remove it, run `pi remove npm:pi-precompact`.
+
+## Scheduling
+
+1. After a completed turn, resolve Pi's effective compaction settings for the current model.
+2. Start one summary when context reaches 85% of the native compaction ceiling.
+3. Require at least 64,000 measured input and cache tokens from the latest valid assistant response.
+4. Keep the result in memory while the agent continues.
+5. At native threshold compaction, validate the snapshot and await its result if necessary.
+6. Return the prepared summary to Pi, or let Pi perform normal compaction.
+
+The ceiling is `contextWindow - reserveTokens`. For a 200,000-token model with a 30,000-token reserve, background work starts at 144,500 tokens.
+Pi's model overrides and adaptive reserves remain authoritative.
+The extension does not start speculative work after the ceiling is already reached.
+
+A job has a two-minute deadline from its start. Foreground waiting uses the remaining time, not a new two-minute timeout.
+Two background failures pause speculative work until compaction or an explicit reset.
+Manual compaction, custom instructions, and overflow recovery always use Pi's foreground path.
+
+## Context safety
+
+The summary uses the canonical `prepareCompaction()` and `compact()` functions from the running Pi installation.
+There is no copied cut-point or projection algorithm.
+
+The extension hashes the original branch and checks it again before applying a result.
+It rejects changed models, settings, branch prefixes, context edits, and intervening compactions.
+It also checks after a foreground wait, because session changes can race the request.
+Session replacement, tree navigation, reload, model selection, and cancellation discard pending work.
+
+Pi keeps the retained history as native messages. The extension does not convert recent tool output or attachments into truncated text.
+New messages after the snapshot remain in that retained history. No catch-up summary call is necessary.
+Pi can still make two native summary calls for a split turn.
+
+Before acceptance, an in-memory `SessionManager` previews the real compaction entry, including replayed system state.
+The estimated result must reduce context and fit below the native ceiling with a 15% estimate margin.
+New history after the snapshot must also fit within `min(max(2 × keepRecentTokens, 30,000), ceiling / 4)`.
+These checks use Pi's token estimates, not an exact provider tokenizer. Native overflow recovery remains the final safeguard.
+
+Pi 1.4.0 skips inherited file metadata from all extension-generated compactions.
+A narrow adapter preserves this extension's marked file lists in both background preparation and foreground fallback.
+It leaves other extensions' details alone.
+
+## Compatibility and limits
+
+`prepareCompaction()` is not a public root export in Pi 1.4.0.
+The adapter loads the installed distribution module after checking the runtime and package versions.
+Unknown versions, mismatched installations, and binary installations without distribution modules leave the extension inactive.
+Pi's normal compaction remains available.
+
+Virtual routing models use native compaction only. This avoids speculative work against unresolved model limits.
+Physical models use `ctx.modelRegistry.streamSimple()`, with the configured provider and request-time authentication.
+The extension does not read credential files or resolve secrets itself.
+Background requests do not use custom SDK `agent.streamFunction` overrides or request-transform hooks.
+
+Background summaries consume provider quota, even when discarded. Requests can overlap with ordinary agent requests.
+Accepted summaries carry their native usage into the compaction entry.
+The extension records known discarded-result usage as a non-context `precompact.discarded` custom entry.
+Pi does not include those custom entries in its built-in cost totals.
+
+Partial failures and cancelled or late requests can incur costs without returning usage.
+A provider that ignores abort can continue remote work after the local wait ends.
+
+This extension follows Pi's summary prompt and cache policy. It does not implement OpenCode's prompt-cache optimization.
+It reads persisted context, not temporary `context` or `context_with_system` hook transformations.
+Persistent omissions and replacements must use Pi's `context_edit` entries.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, Changesets, the commit hook, and the separate release procedure.
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+Prerequisites: Node.js 22.19+, Python 3.11+, Git, npm, Make, and tar.
+
+From the repository root, install the locked development dependencies:
+
+```sh
+npm ci --ignore-scripts
+```
+
+Install the changeset hook once per clone:
+
+```sh
+make hooks-install
+```
+
+Run the same checks as CI:
+
+```sh
+npm run check
+```
+
+This checks formatting, lint, types, runtime tests, the actual npm tarball, and the Changesets flow.
+CI runs these checks on Linux and macOS with Node.js 22 and 24.
+
+Tests use temporary directories, in-memory credentials, in-memory sessions, and a local scripted provider.
+They do not load personal extensions, read real credential files, or call a remote model.
+The integration tests inject deterministic token usage through Pi's finalized-message hook.
+They exercise real extension loading, provider streaming, tool-driven turns, threshold compaction, fallback, and shutdown.
+
+Source:
+
+- `src/index.ts`: lifecycle hooks and commands.
+- `src/controller.ts`: job scheduling and cancellation.
+- `src/native.ts`: version-guarded native adapter.
+- `src/validation.ts`: branch validation and context preview.
+- `src/files.ts`: file-metadata inheritance for Pi 1.4.0.
+- `src/card.ts`: the status card for `/precompact status`.
+- `src/footer.ts`: the context bar in Pi's built-in footer.
+- `src/format.ts`: token, duration, and share formatting.

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "pi-precompact",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Precompute Pi compaction summaries without interrupting the agent.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "author": "Patrick Wozniak",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/patlux/pi-precompact.git"
+  },
+  "homepage": "https://github.com/patlux/pi-precompact#readme",
+  "bugs": {
+    "url": "https://github.com/patlux/pi-precompact/issues"
+  },
+  "private": false,
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "compaction"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@types/node": "^22.19.0",
+    "tsx": "4.23.15",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --error-on-warnings .",
+    "format": "biome check --write .",
+    "changeset": "python3 scripts/changeset.py add",
+    "changeset:status": "python3 scripts/changeset.py status",
+    "changeset:test": "python3 -B scripts/test_changeset.py -v",
+    "hooks:install": "python3 scripts/changeset.py install-hook",
+    "version:prepare": "python3 scripts/changeset.py version",
+    "release:check": "python3 scripts/changeset.py release-ready && npm run check",
+    "prepublishOnly": "npm run release:check",
+    "pack:dry": "npm pack --dry-run --ignore-scripts",
+    "check": "npm run lint && npm run typecheck && npm test && npm run changeset:test && npm run changeset:status"
+  }
+}