@herbertgao/pi-extensions 2026.9.2 → 2026.9.3

package/README.md

@@ -10,12 +10,13 @@ pi install npm:@herbertgao/pi-extensions
 
 Requires Node.js 24 or newer and Pi 0.84.4 or newer.
 
-The package bundles 4 active `@herbertgao/*` child packages—`pi-bark`, `pi-cc-extensions`, `resume-from`, and `pi-subagents`—plus the following upstream packages under their original names:
+The package bundles 5 active `@herbertgao/*` child packages—`pi-bark`, `pi-cc-extensions`, `resume-from`, `pi-subagents`, and `sol-pi`—plus the following upstream packages under their original names:
 
 - `@dietrichgebert/ponytail@4.9.0`
 - `@juicesharp/rpiv-ask-user-question@2.8.0`
 - `@luxusai/pi-hindsight@0.12.0`
 - `@narumitw/pi-btw@0.57.0`
+
 - `@narumitw/pi-caffeinate@0.49.7`
 - `@pi-plugins/fast-mode@0.1.10`
 - `@tifan/pi-copy-response@0.2.6`
@@ -40,7 +41,7 @@ Pi loads their extensions and skills through `node_modules/` paths inside one pa
 
 `@narumitw/pi-caffeinate@0.49.7` uses the host platform's sleep inhibitor during each Pi agent run. On macOS, `/caffeinate sleep` keeps the system awake while allowing the display to sleep; `/caffeinate display` also keeps the display awake. It releases the inhibitor when the run or session ends.
 
-`@herbertgao/resume-from@0.2.0` keeps Claude Code sessions associated with their original repository when the active transcript later moves into a nested cwd. `pi-lens@4.1.3` expands language routing and bounds retained diagnostic facts across multi-root sessions. `pi-automode@1.15.0` preserves dynamic providers on legacy registries. `pi-web-access@0.27.0` adds configurable fetch deadlines and answer models plus isolated GitHub clone runtimes. Preferred Thinking 1.0.1 preserves an explicit subagent `--thinking` choice. Deprecated `@tifan/pi-titlebar-spinner` is no longer bundled; Rename remains the single owner of Herdr tab naming.
+`@herbertgao/resume-from@0.2.0` keeps Claude Code sessions associated with their original repository when the active transcript later moves into a nested cwd. `@herbertgao/sol-pi@0.1.0` adds opt-in Action Fusion, ObservationPack, Evidence-Preserving Reducer, and Online Context Compact; see its [configuration guide](../sol-pi/docs/configuration.md). `pi-lens@4.1.3` expands language routing and bounds retained diagnostic facts across multi-root sessions. `pi-automode@1.15.0` preserves dynamic providers on legacy registries. `pi-web-access@0.27.0` adds configurable fetch deadlines and answer models plus isolated GitHub clone runtimes. Preferred Thinking 1.0.1 preserves an explicit subagent `--thinking` choice. Deprecated `@tifan/pi-titlebar-spinner` is no longer bundled; Rename remains the single owner of Herdr tab naming.
 
 `pi-stash` is no longer bundled: `/btw` already preserves the main editor draft while handling side questions outside the main conversation. Prior `@herbertgao/pi-stash` releases remain available but are no longer maintained here.
 

package/THIRD_PARTY_NOTICES.md

@@ -63,3 +63,27 @@ 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.
+
+## `@herbertgao/sol-pi`
+
+The aggregate bundles [`@herbertgao/sol-pi`](https://github.com/HerbertGao/pi-extensions/tree/master/packages/sol-pi) version 0.1.0. Its source is republished from [`NVlabs/SoL-Pi`](https://github.com/NVlabs/SoL-Pi) under the MIT license:
+
+Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+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/node_modules/@herbertgao/sol-pi/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+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/node_modules/@herbertgao/sol-pi/README.md

@@ -0,0 +1,159 @@
+<p align="center">
+  <img src="assets/sol-pi-hero.png" width="100%" alt="SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses" />
+</p>
+
+# ⚡ SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses
+
+<p align="center">
+  <a href="#getting-started"><img src="https://img.shields.io/badge/Getting%20Started-Install-76B900" alt="Getting Started" /></a>
+  <a href="docs/configuration.md"><img src="https://img.shields.io/badge/Docs-Configuration-555555" alt="Configuration" /></a>
+  <a href="https://nvlabs.github.io/SoL-Pi/"><img src="https://img.shields.io/badge/Blog-SoL--Pi-76B900" alt="SoL-Pi Blog" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
+</p>
+
+> [!NOTE]
+> This package republishes the MIT-licensed SoL-Pi source from [NVlabs/SoL-Pi](https://github.com/NVlabs/SoL-Pi) at the reviewed commit recorded in `package.json`. It is maintained here as `@herbertgao/sol-pi`, not an official distribution of Pi or NVIDIA.
+>
+> The package is independently loadable and is bundled by `@herbertgao/pi-extensions`; its aggregate entry is covered by the collection smoke test.
+
+## 💡 TL;DR
+
+**Spend less without making the agent do less useful work.**
+
+SoL-Pi is a standalone extension for Pi that packages four reusable efficiency mechanisms discovered through scaled auto-research loops. It reduces repeated model turns, context replay, oversized observations, and unnecessary long-log reading while preserving the work and evidence an agent needs to finish a task.
+
+SoL-Pi installs on top of an unmodified Pi release. Every mechanism is opt-in and disabled by default.
+
+## Introduction
+
+Long-running coding agents accumulate repeated work. A file edit is often followed by a predictable validation command. Large tool results are replayed long after their first use. Completed subtasks remain in active context, and a frontier model may spend a full request reading a log when only a few lines affect the next decision.
+
+SoL-Pi grew out of a broader question from our auto-research work: before scaling agent loops, can agents first make the harness itself more efficient? The search focused on constrained efficiency: reducing token traffic, inference work, and agent turns without stopping early, skipping verification, or hiding evidence.
+
+The standalone release contains four mechanisms that survived that process. They operate at different parts of the harness and compose through Pi's public extension APIs.
+
+## What SoL-Pi Adds
+
+| Area | Mechanism | What changes |
+| --- | --- | --- |
+| Tools | **Action Fusion** | An edit or write can run its follow-up validation command in the same tool call. |
+| Observations | **ObservationPack** | Repeated large text results become stable handles with exact paged recall. |
+| Delegation | **Evidence-Preserving Reducer** | Long diagnostic logs become compact receipts only when every retained quotation matches the archived source. |
+| Context | **Online Context Compact** | Completed plan steps become candidate points for Pi's native compaction, subject to economic and window-pressure checks; after a successful compaction, Pi continues the task in a new turn. |
+
+The mechanisms share four rules:
+
+- **No Pi patches.** SoL-Pi imports public Pi APIs and does not vendor the Pi source tree.
+- **Explicit opt-in.** A missing configuration leaves every mechanism disabled.
+- **Preserve evidence.** Original observations remain available locally, and reducer failures leave the original result unchanged.
+- **Use Pi's runtime choices.** Authentication, provider URLs, the main model, and shell behavior remain under Pi's control.
+
+## Technical Details and Core Insights
+
+Read the [SoL-Pi blog](https://nvlabs.github.io/SoL-Pi/) for a deeper look at the technical details, design rationale, and core insights behind SoL-Pi, including how auto-research led to the four efficiency mechanisms and how they work.
+
+## Getting Started
+
+### Requirements
+
+- Node.js 22.19 or newer
+- npm
+- `@earendil-works/pi-coding-agent` 0.84.2
+
+### Install
+
+Install the tested Pi release:
+
+```bash
+npm install --global @earendil-works/pi-coding-agent@0.84.2
+```
+
+Then install SoL-Pi directly from [NVlabs/SoL-Pi](https://github.com/NVlabs/SoL-Pi):
+
+```bash
+pi install git:github.com/NVlabs/SoL-Pi
+```
+
+To install it only for the current project, use the project-local scope:
+
+```bash
+pi install git:github.com/NVlabs/SoL-Pi --local --approve
+```
+
+### Configure
+
+SoL-Pi uses a single effective configuration. With the official Pi distribution, it looks for a `sol-pi.json` file in the following locations, in order:
+
+1. `.pi/sol-pi.json` in the current project, if the project is trusted and the file exists;
+2. `~/.pi/agent/sol-pi.json` otherwise.
+
+If neither file exists, SoL-Pi uses its built-in defaults. The project-level configuration takes precedence over the user-level configuration; the two files are not merged.
+
+The following conservative configuration enables only the two local mechanisms that make no additional model calls and do not stop an active run:
+
+```json
+{
+  "version": 1,
+  "actionFusion": true,
+  "observationPack": true,
+  "evidencePreservingReducer": false,
+  "onlineContextCompact": false,
+  "cacheWriteReadRatio": 12.5
+}
+```
+
+Enable additional mechanisms only after reviewing their configuration and security implications. SoL-Pi uses no dedicated environment variables; feature flags, the reducer provider/model route, and the compaction ratio are configured in `sol-pi.json`.
+
+For the complete schema, see [Configuration](docs/configuration.md). Coding agents and automated environments should follow the canonical [agent installation and configuration protocol](agents-install.md). Its all-enabled profile is checked with `scripts/check-sol-pi-config.mjs --require-all-enabled`.
+
+## Storage and Security
+
+ObservationPack and Evidence-Preserving Reducer store session-specific archives under:
+
+```text
+<session-directory>/sol-pi/<session-id>/
+├── observation-pack/
+└── evidence-preserving-reducer/
+```
+
+They archive eligible source material in this directory. The archived copies remain local and are not automatically deleted when the Pi session ends.
+
+Online Context Compact stores its state in Pi's session log. After a successful compaction, it starts a new turn and automatically continues the active task. Cancelling the run or exiting Pi does not trigger automatic continuation.
+
+Evidence-Preserving Reducer may send eligible diagnostic-log content to its configured reducer model using Pi-managed authentication. Review [SECURITY.md](SECURITY.md) before enabling it. Do not enable remote reduction for logs that must remain local.
+
+## Documentation
+
+| Document | Purpose |
+| --- | --- |
+| [Configuration](docs/configuration.md) | Config search order, schema, defaults, and trust behavior |
+| [Compatibility](docs/compatibility.md) | Supported Pi APIs and standalone integration details |
+| [Security](SECURITY.md) | Local storage, remote reduction, and sensitive behavior |
+| [Agent installation](agents-install.md) | Reproducible installation and all-enabled validation procedure |
+
+## Development
+
+Install from the lockfile and run the complete source checks:
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm audit --audit-level=high
+node scripts/check-pi-compat.mjs
+```
+
+`npm run check` covers TypeScript, the complete test suite, and package inspection. The development dependency set is pinned to Pi 0.84.2; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades.
+
+## Project Status
+
+SoL-Pi is developed and maintained by NVIDIA as a standalone extension for Pi.
+
+External code contributions are not accepted at this time. Bug reports and private security reports remain welcome through the channels described in [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+## Acknowledgements
+
+SoL-Pi builds on the public extension interfaces provided by [Pi](https://github.com/earendil-works/pi). Pi remains an independent upstream project and is not vendored into this repository.
+
+## License
+
+SoL-Pi is released under the [MIT License](LICENSE).

package/node_modules/@herbertgao/sol-pi/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+SoL-Pi is a Pi extension. It runs with the filesystem, process, network, and credential permissions of the Pi process that loads it. SoL-Pi is not a sandbox or permission boundary.
+
+## Sensitive behavior
+
+- Action Fusion can modify files and run shell commands requested by the model.
+- ObservationPack stores large tool results under Pi's session directory.
+- Evidence-Preserving Reducer archives diagnostic logs locally and, when explicitly enabled, sends eligible logs through the configured reducer model using Pi-managed authentication.
+- The reducer skips text matching its likely-secret detector, but that detector is a precaution rather than a complete secret scanner. Do not enable remote reduction for workloads whose logs must remain local.
+- Online Context Compact stores plan and compaction state in Pi's session log; see below.
+- Project-local `.pi/sol-pi.json` files should be used only in trusted repositories.
+
+## Online Context Compact data
+
+Online Context Compact is off by default. When enabled, every `update_plan` call appends a versioned custom state entry to Pi's session log. The latest valid entry holds the model-authored plan, concise progress fields, request counts, token-growth estimates, and compaction debt. These values can include paths, command names, and design notes and should be treated as sensitive as the rest of the conversation. After a successful compaction, the extension also writes one hidden, generic custom message that tells the assistant to rebuild its plan; the reminder contains no task-specific data.
+
+The extension creates no sidecar, attestation, payload-capture, or research-instrumentation files. State entries do not enter the model context; only the generic post-compaction reminder does. Deleting the Pi session removes both kinds of persisted Online Context Compact data.
+
+Evidence-Preserving Reducer may temporarily read an overlong bash result from outside its session archive. It accepts only a regular, non-symlink `pi-bash-*.log` file directly inside the operating system's temporary directory and copies eligible content into the session-specific archive before any nested model call.
+
+## Reporting a vulnerability
+
+Use the repository's GitHub Security Advisories page to submit a private report. Do not open a public issue for a suspected vulnerability.
+
+Include the affected commit or version, configuration, impact, reproduction steps, and any available mitigation. Reports about Pi itself should be sent to the upstream Pi project.

package/node_modules/@herbertgao/sol-pi/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-Party Notices
+
+SoL-Pi does not vendor third-party source code. Its npm tarball contains only SoL-Pi source, documentation, tests-excluded assets, and project metadata.
+
+## Runtime peer dependencies
+
+The following packages are supplied by the user's Pi installation and retain their own licenses:
+
+| Package | Development-tested version | License | Source |
+| --- | ---: | --- | --- |
+| `@earendil-works/pi-agent-core` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-ai` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-coding-agent` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-tui` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `typebox` | 1.3.7 | MIT | <https://github.com/sinclairzx81/typebox> |
+
+## Development-only dependencies
+
+`@types/node` (MIT), TypeScript (Apache-2.0), and Vitest (MIT) are used to type-check and test the repository. They are not included in the SoL-Pi npm tarball. Exact versions and transitive dependency metadata are recorded in `package-lock.json`.

package/node_modules/@herbertgao/sol-pi/agents-install.md

@@ -0,0 +1,150 @@
+# SoL-Pi Agent Installation and Configuration Protocol
+
+This is the canonical procedure for Codex, Claude Code, and other coding agents that install, configure, or validate SoL-Pi from a full source checkout. Follow the phases in order. Explicit user instructions take precedence. An extracted npm package is not a substitute for the checkout because it does not contain the test suite.
+
+Installation and configuration are complete only when Pi remains unmodified, the repository checks pass, Pi lists the package, all four mechanisms are enabled in one effective `sol-pi.json`, and Pi starts without an extension error.
+
+## Rules
+
+- Do not modify, patch, fork, or vendor upstream Pi. SoL-Pi must load as a standalone extension through Pi's public package interface.
+- Use Node.js 22.19 or newer and the tested Pi release `@earendil-works/pi-coding-agent@0.84.2`. Treat a different Pi version as a compatibility change and rerun the full suite before using it.
+- Do not clean, reset, switch, or overwrite unrelated repository changes.
+- Do not print, log, commit, upload, or include any secret in a command line. Check only whether a credential is present.
+- Keep SoL-Pi settings in `sol-pi.json`. The Evidence-Preserving Reducer provider/model route is a SoL-Pi setting; provider URLs, credentials, the main agent model, and shell behavior remain Pi settings.
+- Keep persistent artifacts under Pi's session-derived `sol-pi/<session-id>/` root; do not configure a separate storage path.
+
+## Inputs
+
+Resolve these values before making changes:
+
+- `sol_pi_root`: absolute path to the intended SoL-Pi checkout;
+- `target_project`: project in which Pi will run;
+- install scope: project-local or user-wide;
+- exact SoL-Pi branch and commit.
+
+Do not guess an ambiguous path or install scope.
+
+## Phase 1: validate the checkout
+
+From `sol_pi_root`, record the repository state without changing it:
+
+```bash
+git status --short --branch
+git rev-parse HEAD
+node --version
+npm --version
+```
+
+Require Node.js 22.19 or newer. Install from the lockfile and run the source checks:
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm audit --audit-level=high
+node scripts/check-pi-compat.mjs
+npx vitest run tests/all-mechanisms.test.ts
+```
+
+`npm run check` covers type checking, the complete test suite, and package inspection. `tests/all-mechanisms.test.ts` confirms that one all-enabled configuration registers all four mechanisms against Pi's public extension API. The tests run without a model provider.
+
+Stop if any command fails. Do not hide a failure with `|| true` or replace `npm ci` with an unlocked install.
+
+## Phase 2: install Pi and SoL-Pi
+
+Install the tested Pi release without changing its source:
+
+```bash
+npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.84.2
+pi --version
+```
+
+Require `pi --version` to report `0.84.2`.
+
+For a project-local registration, run this from `target_project` and substitute the resolved absolute `sol_pi_root`:
+
+```bash
+pi install "/absolute/path/to/SoL-Pi" --local --approve
+pi list --approve
+```
+
+For a user-wide registration, omit `--local`:
+
+```bash
+pi install "/absolute/path/to/SoL-Pi" --approve
+pi list --approve
+```
+
+The `pi list` output must show the exact SoL-Pi source in the selected scope. Do not install the same checkout in both scopes. A project-local registration must run only in a trusted project; use `--approve` for automated invocations unless trust has already been explicitly persisted.
+
+## Phase 3: configure all four mechanisms
+
+SoL-Pi defaults every mechanism to disabled. For this managed installation, create exactly one effective configuration with every mechanism enabled:
+
+```json
+{
+  "version": 1,
+  "actionFusion": true,
+  "observationPack": true,
+  "evidencePreservingReducer": true,
+  "evidencePreservingReducerProvider": "provider-id",
+  "evidencePreservingReducerModel": "model-id",
+  "onlineContextCompact": true,
+  "cacheWriteReadRatio": 12.5
+}
+```
+
+`evidencePreservingReducerProvider` and `evidencePreservingReducerModel` select the nested reducer route that Evidence-Preserving Reducer resolves through Pi's model registry. They default to the built-in reducer route and must be non-empty strings when supplied. Change them only when a different reducer model is intended.
+
+`cacheWriteReadRatio` is the only pricing-related input SoL-Pi reads. It defaults to `12.5`, accepts any finite non-negative number, and treats `0` as an explicit statement that a cache write adds no cost relative to a cache read. SoL-Pi does not inspect Pi model prices. The value controls one compaction decision and is not a bill estimate. The default follows the GPT-5.6 Sol OpenAI Standard cache-write/read ratio checked on 2026-08-21; see [OpenAI API pricing](https://developers.openai.com/api/docs/pricing). Change it when a different policy is required.
+
+Use one location matching the selected scope. Resolve the directory through Pi; the official Pi defaults are shown in parentheses:
+
+- project-local: `<target_project>/<Pi config directory>/sol-pi.json` (`<target_project>/.pi/sol-pi.json`);
+- user-wide: `<Pi agent directory>/sol-pi.json` (`~/.pi/agent/sol-pi.json`).
+
+SoL-Pi uses Pi's public `CONFIG_DIR_NAME` and `getAgentDir()` APIs. Do not assume the defaults when Pi reports different directories.
+
+The project file replaces the user-wide file; the two are not merged. If both exist, inspect them and obtain direction before changing either one. Unknown keys, unsupported versions, malformed JSON, non-boolean feature values, invalid reducer model fields, and invalid ratios must remain fatal.
+
+Do not put provider URL, credentials, shell path, command prefix, storage path, or run ID in `sol-pi.json`. SoL-Pi either reads those values from Pi or derives them from the Pi session.
+
+SoL-Pi reads no dedicated environment variables. Evidence-Preserving Reducer uses the configured reducer provider/model route and Pi-managed authentication. Configure credentials in Pi and do not copy them into `sol-pi.json`.
+
+From `sol_pi_root`, validate the exact effective file:
+
+```bash
+node scripts/check-sol-pi-config.mjs \
+  --config /absolute/path/to/effective/sol-pi.json \
+  --require-all-enabled
+```
+
+Require exit status 0 and retain its JSON output. The check applies SoL-Pi's default values, rejects unknown keys and wrong types, and confirms all four mechanisms are enabled. A partially enabled file can be valid SoL-Pi configuration, but it does not satisfy this all-enabled profile.
+
+## Phase 4: verify the installation
+
+1. Run `pi list --approve` from `target_project` and confirm the expected SoL-Pi source and scope.
+2. Run `check-sol-pi-config.mjs --require-all-enabled` against the effective `sol-pi.json`.
+3. Re-run `npx vitest run tests/all-mechanisms.test.ts` from `sol_pi_root`.
+4. Start Pi with `--offline --approve`, send no prompt, confirm there is no extension load error, and exit.
+5. Confirm that upstream Pi was not patched and that the SoL-Pi checkout contains no vendored Pi monorepo source.
+
+## Completion report
+
+Report:
+
+- SoL-Pi absolute path, branch, and commit;
+- repository state before and after installation;
+- Node, npm, and Pi versions;
+- install scope and the exact entry shown by `pi list`;
+- effective config path, four enabled flags, EPR reducer provider/model, and `cacheWriteReadRatio`, without secrets;
+- every validation command and result;
+- any blocker or deviation.
+
+Do not describe the installation as successful if a required check is missing.
+
+## Agent entry files
+
+`agents-install.md` is the single source of truth, but agents do not universally auto-discover arbitrary filenames. Root `AGENTS.md` tells Codex to read this file, while root `CLAUDE.md` imports it for Claude Code. Keep those entry files short and keep executable installation details here.
+
+- [Codex `AGENTS.md` discovery](https://developers.openai.com/codex/guides/agents-md)
+- [Claude Code project memory and imports](https://docs.anthropic.com/zh-CN/docs/claude-code/memory)

package/node_modules/@herbertgao/sol-pi/docs/compatibility.md

@@ -0,0 +1,69 @@
+# Pi Compatibility
+
+SoL-Pi is developed and tested against `@earendil-works/pi-coding-agent` 0.84.2. Its public API surface is also type-checked and exercised against Pi 0.81.1, the base used by the original Pi fork. The runtime range is deliberately expressed as a peer dependency because Pi owns installation and upgrade of its packages.
+
+SoL-Pi imports only public package exports:
+
+- `createEditToolDefinition`
+- `createWriteToolDefinition`
+- `createBashToolDefinition`
+- extension types and `ExtensionAPI.registerTool`
+- `context`, `before_provider_request`, `tool_result`, `turn_end`, `agent_settled`, and `session_before_tree` extension events
+- native compaction events, `ExtensionContext.getContextUsage()`, and `ExtensionContext.compact()`
+- `ExtensionContext.model` and `ExtensionContext.modelRegistry`
+- the public session-manager methods exposed through `ExtensionContext`
+
+## Action Fusion
+
+The built-in edit/write definitions capture their working directory, so SoL-Pi caches one definition per `ctx.cwd`. Its own per-file queue surrounds the built-in mutation and follow-up command. It does not nest Pi's built-in mutation queue.
+
+Action Fusion decodes `file://` targets with Node's `fileURLToPath()` before resolving the queue and hash-check path. This keeps file URLs, including percent-encoded filenames and Pi's optional `@` prefix, aligned with the file handled by the built-in mutation tool.
+
+The queue covers only fused operations registered by this SoL-Pi instance. External processes, direct built-in-tool calls outside the replacement, and unrelated extensions are not globally locked. SoL-Pi hashes the target immediately before launching `then_run` and skips the command if it observes an intervening content change.
+
+When another extension already owns `write`, Action Fusion leaves that tool in place and only registers its `edit` replacement. When `pi-automode` exposes `automode_inspect`, Action Fusion registers neither mutation replacement: nested `then_run` cannot re-enter Pi's public `tool_call` permission pipeline, so disabling the fusion is the safe fallback.
+
+## ObservationPack
+
+ObservationPack changes only the messages projected through the public `context` event. Stored session history remains intact. Original bytes and the JSONL ledger live under the session-derived SoL-Pi directory.
+
+## Evidence-Preserving Reducer
+
+The reducer handles public `tool_result` events and resolves the configured reducer provider/model through Pi's model registry before calling `ExtensionContext.modelRegistry.complete()` when available. For the Pi 0.81.1 fork, which exposes no registry `complete()` method, it resolves authentication for that reducer model through `getApiKeyAndHeaders()` and calls the shared `@earendil-works/pi-ai/compat` completion API. The reducer preserves the original result whenever the configured reducer model is unavailable or eligibility, model-call, schema, source-hash, exact-quote, size, or likely-secret checks fail.
+
+All persistent paths use `SessionManager.getSessionDir()` and `getSessionId()`, which are present in both the fork and Pi 0.84.2. SoL-Pi creates no configurable storage-path surface.
+
+The unpublished shared artifact layout is not read or migrated. Each session starts from its own `<sessionDir>/sol-pi/<sessionId>/` directory.
+
+## Online Context Compact
+
+Online Context Compact uses ordinary public `context` and `before_provider_request` handlers instead of fork-only post-transform observer methods. Public handlers run in extension load order, so the SoL-Pi entrypoint registers Online Context Compact after its other context transformers. A third-party transformer loaded later is outside the context-growth observation used by its estimate.
+
+Before selecting or executing a boundary compaction, it also checks the optional `Symbol.for("pi-subagents:manager")` registry exposed by `pi-subagents`. A running top-level subagent, or an unreadable registry, suppresses that compaction rather than risking a context rewrite during delegated work. When the registry is absent, the check is a no-op.
+
+Pi does not expose its active retained-tail compaction setting through the public extension context. The standalone extension therefore uses the documented Pi 0.84.2 default of 20,000 tokens for its economic estimate. Its programmatic factory accepts an explicit matching value for a non-default Pi setting.
+
+Pi 0.84.2's `ExtensionContext.compact()` aborts the active agent before it summarizes, and `agent_settled` fires only once a whole run has drained every turn, retry, auto-compaction, and queued continuation. A plan boundary that selects compaction therefore saves its plan and progress state, calls `ExtensionContext.abort()` to stop the run, and runs compaction from the `agent_settled` that stop produces. The handler awaits the compaction's own `onComplete`/`onError` callbacks. On success, the extension sends a hidden reminder through public `ExtensionAPI.sendMessage()` with `triggerTurn: true`, so Pi starts a new turn against the compacted context and rebuilds the plan even when the native summary omits that instruction.
+
+A settlement barrier keeps the original `agent_settled` dispatch open until the triggered continuation settles. Print- and JSON-mode processes therefore complete the compact-and-continue sequence within the same Pi invocation; an outer driver does not need to resume the session or send `Continue working`. This continuation is armed only by a successful boundary compaction. Cancelling or exiting does not schedule one. A Pi build that never emits `agent_settled` starts no boundary compaction.
+
+Pi 0.84.2 does not return a promise from `ExtensionAPI.sendMessage()`. The barrier is therefore verified for standalone SoL-Pi and depends on Pi starting the requested turn synchronously. A later-loaded third-party extension that performs long asynchronous work in its own `agent_settled` handler is outside this guarantee and needs an integration test with that extension set.
+
+Pi reports the session as idle while an extension-requested manual compaction is running. SoL-Pi cancels `session_before_tree` during that interval to prevent tree navigation from moving the active leaf underneath the compaction. Navigation works normally after the compaction callback settles.
+
+Online Context Compact reads `ExtensionContext.getContextUsage()` for both the context window and the provider-counted context size. When Pi reports no size — as it does between a compaction and the next answered request — the boundary falls back to its own estimate.
+
+The standalone entry passes `cacheWriteReadRatio` from `sol-pi.json` directly into Online Context Compact's economic check. It does not inspect model price metadata. Changing models during a session does not change the ratio; users who want a different decision policy update the configuration and start a new session.
+
+## Interactive TUI
+
+The lightning savings treatment uses Pi 0.84.2's public `renderCall`,
+`renderResult`, `ctx.ui.notify()`, and keyed `ctx.ui.setStatus()` APIs. It checks
+`ctx.mode === "tui"` rather than `ctx.hasUI`, because RPC mode also reports UI
+support. The renderer therefore changes only the interactive terminal display;
+it does not change session messages, provider requests, tool results, JSON
+events, print output, or RPC UI requests.
+
+## Test doubles
+
+The test suite drives every extension through the same public `ExtensionAPI` and `ExtensionContext` surface Pi provides, over a real public `SessionManager`, with no provider registered. That keeps the suite zero-spend and independent of the deleted Pi monorepo test harness. Suites that need a genuine session tree — branch order, compaction entries, custom entries, resume — use `SessionManager.inMemory()` or `SessionManager.create()` rather than reimplementing them.

package/node_modules/@herbertgao/sol-pi/docs/configuration.md

@@ -0,0 +1,75 @@
+# Configuration
+
+SoL-Pi reads one effective JSON configuration file at extension startup. It uses Pi's public `CONFIG_DIR_NAME` and `getAgentDir()` APIs rather than assuming fixed directories.
+
+## Search order
+
+1. `<working-directory>/<Pi config directory>/sol-pi.json`, only after Pi marks the project trusted
+2. `<Pi agent directory>/sol-pi.json`
+3. Built-in defaults when neither file exists
+
+For the official Pi distribution, the first two locations normally resolve to `.pi/sol-pi.json` and `~/.pi/agent/sol-pi.json`.
+
+The project file replaces the global file. SoL-Pi does not merge them.
+
+## Schema
+
+```json
+{
+  "version": 1,
+  "actionFusion": false,
+  "observationPack": false,
+  "evidencePreservingReducer": false,
+  "evidencePreservingReducerProvider": "provider-id",
+  "evidencePreservingReducerModel": "model-id",
+  "onlineContextCompact": false,
+  "cacheWriteReadRatio": 12.5
+}
+```
+
+Feature keys may be omitted and then default to `false`. `cacheWriteReadRatio` may be omitted and then defaults to `12.5`; when present it must be a finite non-negative number, and `0` explicitly means that a cache write adds no cost relative to a cache read. `evidencePreservingReducerProvider` and `evidencePreservingReducerModel` may be omitted and then use the built-in reducer route; when present each must be a non-empty string. Unknown keys, unsupported versions, malformed JSON, non-boolean feature values, invalid ratios, and invalid reducer model fields stop extension loading with a direct error.
+
+For the managed all-enabled installation described in the [agent installation and configuration protocol](../agents-install.md), validate the effective file before starting Pi:
+
+```bash
+node scripts/check-sol-pi-config.mjs \
+  --config /absolute/path/to/effective/sol-pi.json \
+  --require-all-enabled
+```
+
+This preflight does not make every valid SoL-Pi configuration all-enabled. Without `--require-all-enabled`, omitted feature keys retain their normal `false` defaults. The managed workflow uses the flag because its acceptance criterion is that all four mechanisms are active.
+
+## Feature behavior
+
+- `actionFusion`: registers SoL-Pi replacements for Pi's `edit` and `write` tools.
+- `observationPack`: registers `obs_recall` and a provider-context projection handler.
+- `evidencePreservingReducer`: registers a `tool_result` handler and delegates long diagnostic-log reduction to the configured reducer provider/model.
+- `evidencePreservingReducerProvider`: provider namespace used to resolve the reducer model through Pi's model registry.
+- `evidencePreservingReducerModel`: model id used for Evidence-Preserving Reducer.
+- `onlineContextCompact`: registers `update_plan` and boundary-driven native compaction after the other SoL-Pi context transformers.
+- `cacheWriteReadRatio`: supplies the single economic decision ratio used by Online Context Compact.
+
+## Evidence-Preserving Reducer runtime inputs
+
+The release entry supplies the run label and session-derived storage. It uses one configurable model route:
+
+- **Reducer provider/model** — from `evidencePreservingReducerProvider` and `evidencePreservingReducerModel` in the effective `sol-pi.json`. If omitted, SoL-Pi uses its built-in reducer route. SoL-Pi resolves that model through Pi's model registry and still relies on Pi-managed authentication; do not put credentials in `sol-pi.json`.
+
+## Online Context Compact runtime inputs
+
+The release entry uses two runtime inputs:
+
+- **Context window** — from `ExtensionContext.getContextUsage()`, used for window-pressure protection.
+- **Cache write/read ratio** — from `cacheWriteReadRatio` in the effective `sol-pi.json`. The value remains fixed for the session and is not recomputed when the model changes. It drives one runtime decision and is not a cost report.
+
+The configured ratio stays fixed for the loaded extension. The mechanism stores its current plan, progress summaries, request horizon, context growth, and compaction debt as versioned custom entries in Pi's session log. After a successful compaction it sends one hidden, generic message with `triggerTurn: true`, which starts a new turn and instructs the assistant to rebuild its plan. A settlement barrier keeps print and JSON modes in the same Pi invocation until that continuation settles, so callers do not need to resume the session or inject `Continue working`. Cancelling or exiting does not schedule an automatic continuation. The mechanism creates no separate Online Context Compact files. The programmatic factory exposes only a matching retained-tail value for installations whose Pi compaction setting differs from the default.
+
+## Pi integration
+
+SoL-Pi reads no dedicated environment variables. Evidence-Preserving Reducer resolves its configured reducer provider/model through `ExtensionContext.modelRegistry` and uses Pi-managed authentication. If the configured reducer model is unavailable or the nested model call fails, the original tool result continues unchanged.
+
+SoL-Pi does not configure shell paths, command prefixes, storage paths, run IDs, provider URLs, reasoning levels, timeouts, or per-mechanism enable flags through environment variables. Apart from the EPR reducer provider/model route in `sol-pi.json`, model selection remains with Pi. Action Fusion uses Pi's default shell behavior. Persistent artifacts are derived from Pi's session directory and session ID.
+
+## Trust
+
+A project-local config can enable file mutation, shell execution, local archival, and remote diagnostic-log reduction. SoL-Pi waits for Pi's `session_start` context and ignores the project file unless `ctx.isProjectTrusted()` is true. Prefer the global file when you want one personal configuration across trusted projects.