sol-pi-axi 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. sol_pi_axi-0.1.0/.gitignore +46 -0
  2. sol_pi_axi-0.1.0/LICENSE +19 -0
  3. sol_pi_axi-0.1.0/PKG-INFO +280 -0
  4. sol_pi_axi-0.1.0/README.md +264 -0
  5. sol_pi_axi-0.1.0/pyproject.toml +53 -0
  6. sol_pi_axi-0.1.0/sol_pi_axi/__init__.py +6 -0
  7. sol_pi_axi-0.1.0/sol_pi_axi/_version.py +1 -0
  8. sol_pi_axi-0.1.0/sol_pi_axi/check.py +239 -0
  9. sol_pi_axi-0.1.0/sol_pi_axi/cli.py +805 -0
  10. sol_pi_axi-0.1.0/sol_pi_axi/config.py +250 -0
  11. sol_pi_axi-0.1.0/sol_pi_axi/install.py +182 -0
  12. sol_pi_axi-0.1.0/sol_pi_axi/pi.py +194 -0
  13. sol_pi_axi-0.1.0/sol_pi_axi/prompt.py +195 -0
  14. sol_pi_axi-0.1.0/sol_pi_axi/setup.py +168 -0
  15. sol_pi_axi-0.1.0/sol_pi_axi/write.py +76 -0
sol_pi_axi-0.1.0/.gitignore ADDED
@@ -0,0 +1,46 @@
1
+ # Machine-local overlay (values that stay on this machine) — never committed.
2
+ .env.local
3
+
4
+ # CR worktrees live inside the repo (inheriting Pi's project trust).
5
+ .worktrees/
6
+
7
+ # Tooling debris.
8
+ __pycache__/
9
+ test-reports/
10
+ # coverage.py data (a parallel run's per-process parts too) and its lcov, when a run reports
11
+ # at the project root rather than into test-reports/<agent>/.
12
+ .coverage
13
+ .coverage.*
14
+ coverage.lcov
15
+
16
+ # Project registry (holds the Crucible project key) — machine-local, never committed.
17
+ .env
18
+
19
+ # Build and dependency output.
20
+ node_modules/
21
+ .venv/
22
+ *.egg-info/
23
+ coverage/
24
+ dist/
25
+ *.tgz
26
+ *.tsbuildinfo
27
+ *.log
28
+
29
+ # Editor / OS / other-harness debris.
30
+ .DS_Store
31
+ .vscode/
32
+ .idea/
33
+ .zed/
34
+ .claude/
35
+ docs/superpowers/plans/
36
+
37
+ # Generated by modelb-axi (Model B scaffold and `modelb-axi agents`) or machine-local Pi
38
+ # session settings — repo-local, never committed.
39
+ .pi/agents/
40
+ .pi/extensions/
41
+ .pi/settings.json
42
+ .pi/sol-pi.json
43
+ .lean-ctx.toml
44
+ hooks/
45
+ .envrc
46
+ crucible.toml
sol_pi_axi-0.1.0/LICENSE ADDED
@@ -0,0 +1,19 @@
1
+ Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a
4
+ copy of this software and associated documentation files (the "Software"),
5
+ to deal in the Software without restriction, including without limitation
6
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
7
+ and/or sell copies of the Software, and to permit persons to whom the
8
+ Software is furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in
11
+ all copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
16
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
19
+ DEALINGS IN THE SOFTWARE.
sol_pi_axi-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,280 @@
1
+ Metadata-Version: 2.5
2
+ Name: sol-pi-axi
3
+ Version: 0.1.0
4
+ Summary: Agent-facing setup command for the SoL-Pi Pi extensions
5
+ Project-URL: Homepage, https://github.com/anthill-tec/SoL-Pi
6
+ Project-URL: Changelog, https://github.com/anthill-tec/SoL-Pi/blob/main/CHANGELOG.md
7
+ Project-URL: Release Notes, https://github.com/anthill-tec/SoL-Pi/releases
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Requires-Python: >=3.14
11
+ Requires-Dist: toon-format==1.2.0
12
+ Provides-Extra: dev
13
+ Requires-Dist: coverage; extra == 'dev'
14
+ Requires-Dist: unittest-xml-reporting; extra == 'dev'
15
+ Description-Content-Type: text/markdown
16
+
17
+ <p align="center">
18
+ <img src="https://raw.githubusercontent.com/anthill-tec/SoL-Pi/main/assets/sol-pi-hero.png" width="100%" alt="SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses" />
19
+ </p>
20
+
21
+ # ⚡ SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses
22
+
23
+ <p align="center">
24
+ <a href="https://arxiv.org/abs/2609.20519"><img src="https://img.shields.io/badge/arXiv-2609.20519-B31B1B?logo=arxiv&amp;logoColor=white" alt="arXiv: 2609.20519" /></a>
25
+ <a href="#getting-started"><img src="https://img.shields.io/badge/Getting%20Started-Install-76B900" alt="Getting Started" /></a>
26
+ <a href="https://github.com/anthill-tec/SoL-Pi/blob/main/docs/configuration.md"><img src="https://img.shields.io/badge/Docs-Configuration-555555" alt="Configuration" /></a>
27
+ <a href="https://nvlabs.github.io/SoL-Pi/"><img src="https://img.shields.io/badge/Blog-SoL--Pi-76B900" alt="SoL-Pi Blog" /></a>
28
+ <a href="https://github.com/anthill-tec/SoL-Pi/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
29
+ </p>
30
+
31
+ > [!NOTE]
32
+ > This repository contains the open-source version of SoL-Pi, a standalone extension for [Pi](https://github.com/earendil-works/pi). It is not an official distribution of Pi.
33
+ >
34
+ > SoL-Pi is under active development to support pi-v1 and the latest model checkpoints.
35
+
36
+ ## 📰 News
37
+
38
+ - **2026-10-14** — Released the [SoL-Pi Skill](https://github.com/anthill-tec/SoL-Pi/blob/main/examples/sol-pi-skill/README.md) example: use SoL-Pi as a skill from Claude Code (`/sol-pi`) or Codex (`$sol-pi`). The current task is handed to SoL-Pi with the host conversation as context, runs in the background, and its result is reported back to the session.
39
+ - **2026-10-13** — Released the [SoL-Pi Visual](https://github.com/anthill-tec/SoL-Pi/blob/main/examples/solpi-visual/README.md) example for 3D scene reconstruction in Blender. On this task, it lowers the cost per scene by **37%** compared with Codex, with 13% fewer model calls. See the example for visual scores and scene comparisons.
40
+
41
+ ## 💡 TL;DR
42
+
43
+ **Spend less without making the agent do less useful work.**
44
+
45
+ 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.
46
+
47
+ SoL-Pi installs on top of an unmodified Pi release. Every mechanism is disabled until a `sol-pi.json` enables it; `sol-pi-axi install` and `sol-pi-axi setup` write one with all four enabled unless `--features` says otherwise.
48
+
49
+ ## Introduction
50
+
51
+ 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.
52
+
53
+ 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.
54
+
55
+ 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.
56
+
57
+ ## What SoL-Pi Adds
58
+
59
+ | Area | Mechanism | What changes |
60
+ |---|---|---|
61
+ | Tools | **Action Fusion** | An edit or write can run its follow-up validation command in the same tool call. |
62
+ | Observations | **ObservationPack** | Repeated large text results become stable handles with exact paged recall. |
63
+ | Delegation | **Evidence-Preserving Reducer** | Long diagnostic logs become compact receipts only when every retained quotation matches the archived source. |
64
+ | 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. |
65
+
66
+ The mechanisms share four rules:
67
+
68
+ - **No Pi patches.** SoL-Pi imports public Pi APIs and does not vendor the Pi source tree.
69
+ - **Explicit opt-in.** A missing configuration leaves every mechanism disabled.
70
+ - **Preserve evidence.** Original observations remain available locally, and reducer failures leave the original result unchanged.
71
+ - **Use Pi's runtime choices.** Authentication, provider URLs, and the main model remain under Pi's control.
72
+
73
+ ## Technical Details and Core Insights
74
+
75
+ 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.
76
+
77
+ ## Paper
78
+
79
+ Read our paper: [SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness](https://arxiv.org/abs/2609.20519).
80
+
81
+ ## Getting Started
82
+
83
+ ### Requirements
84
+
85
+ - Node.js 22.19 or newer
86
+ - Python 3.14 or newer and [uv](https://docs.astral.sh/uv/), for the `sol-pi-axi` command
87
+ - Bun 1.4.4 or newer, only for a source checkout or a Bun-installed Pi
88
+ - `@earendil-works/pi-coding-agent` 0.84.2 or newer; tested with 0.84.2, 1.0.4, 1.3.0, and 1.5.0. Install 1.5.0, the latest tested release: a fresh install of Pi 1.0.x or 1.1.0 now fails to start, because those releases do not pin their internal packages. Other versions are untested: `scripts/check-pi-compat.mjs` warns on them, and `--strict` fails.
89
+
90
+ ### Install
91
+
92
+ Install the latest tested Pi release with Bun:
93
+
94
+ ```bash
95
+ bun add --global @earendil-works/pi-coding-agent@1.5.0
96
+ ```
97
+
98
+ Or, with npm:
99
+
100
+ ```bash
101
+ npm install --global @earendil-works/pi-coding-agent@1.5.0
102
+ ```
103
+
104
+ Pi 1.3.0 and 0.84.2 remain supported and tested; install `@earendil-works/pi-coding-agent@1.3.0` or `@earendil-works/pi-coding-agent@0.84.2` instead to stay on one of them.
105
+
106
+ Then install the `sol-pi-axi` command from PyPI and let it register the extension with Pi. It needs Python 3.14 or newer and [uv](https://docs.astral.sh/uv/); `<version>` is a SoL-Pi release:
107
+
108
+ ```bash
109
+ uv tool install sol-pi-axi==<version>
110
+ sol-pi-axi install
111
+ ```
112
+
113
+ `sol-pi-axi install` registers the extension `npm:@anthill-tec/sol-pi@<version>` with Pi (`pi install`, run from your home directory) and writes the agent directory's `sol-pi.json` with the setup defaults when it has none. On a Pi with no `defaultProvider` and `defaultModel` in its `settings.json` (a Pi never started), give the reducer's route, `sol-pi-axi install --reducer <provider>/<model>`, or leave the reducer off with `--features actionFusion,observationPack,onlineContextCompact`; otherwise the run fails and names `--reducer`. Then configure each project:
114
+
115
+ ```bash
116
+ sol-pi-axi setup <project dir>
117
+ ```
118
+
119
+ Alternatively, register the extension with Pi yourself, from npm:
120
+
121
+ ```bash
122
+ pi install npm:@anthill-tec/sol-pi@<version>
123
+ ```
124
+
125
+ The PyPI package `sol-pi-axi` and the npm package `@anthill-tec/sol-pi` share the same release version; `sol-pi-axi install` registers the extension at its own version.
126
+
127
+ Pi installs an `npm:` source by running `npm`, or the command array in its `npmCommand` setting (for example `["pnpm"]` or `["bun"]`); that command must be on `PATH`.
128
+
129
+ ### Configure
130
+
131
+ 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:
132
+
133
+ 1. `.pi/sol-pi.json` in the current project, if the project is trusted and the file exists;
134
+ 2. `~/.pi/agent/sol-pi.json` otherwise.
135
+
136
+ 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.
137
+
138
+ The following conservative configuration enables only the two local mechanisms that make no additional model calls and do not stop an active run:
139
+
140
+ ```json
141
+ {
142
+ "version": 1,
143
+ "actionFusion": true,
144
+ "observationPack": true,
145
+ "evidencePreservingReducer": false,
146
+ "onlineContextCompact": false,
147
+ "cacheWriteReadRatio": 12.5
148
+ }
149
+ ```
150
+
151
+ Enable additional mechanisms only after reviewing their configuration and security implications. The extension reads one environment variable, `SOL_PI_AXI_VERIFY`, only to answer `sol-pi-axi verify` (it sends the load signal that check waits for); feature flags, the reducer provider/model route, and the compaction ratio are configured in `sol-pi.json`. The `sol-pi-axi` command reads `PI_CODING_AGENT_DIR` to find the agent directory (default `~/.pi/agent`). See [sol-pi.example.json](https://github.com/anthill-tec/SoL-Pi/blob/main/sol-pi.example.json) for a template listing every key.
152
+
153
+ ### `sol-pi-axi setup`
154
+
155
+ `sol-pi-axi setup <project dir>` writes `<project dir>/.pi/sol-pi.json` (creating `.pi/` when missing) and nothing else. It prompts only with `--interactive` (see [Prompting with `--interactive`](#prompting-with---interactive)). Its base values are a valid project file's values, else the agent directory's `sol-pi.json`, else the setup defaults: all four mechanisms on, ratio 12.5, and the reducer on Pi's `defaultProvider` and `defaultModel` from the agent directory's `settings.json`. With no value flag, a valid project file is left `unchanged`. The flags override the base values:
156
+
157
+ | Flag | Value |
158
+ |---|---|
159
+ | `--features` | `all`, `none`, or a comma list of `actionFusion`, `observationPack`, `evidencePreservingReducer`, `onlineContextCompact`; unlisted ones off |
160
+ | `--reducer` | `<provider>/<model>`, split at the first `/` |
161
+ | `--cache-ratio` | digits with an optional decimal fraction |
162
+ | `--format` | `toon` (default) or `json` |
163
+ | `--interactive` | prompt for the values, then confirm (see below) |
164
+ | `--non-interactive` | accepted; setup prompts only with `--interactive`, and the two together are a usage error |
165
+ | `-h`, `--help` | plain-text help |
166
+ | `-v`, `-V`, `--version` | the bare version |
167
+
168
+ ```bash
169
+ sol-pi-axi setup . --features actionFusion,observationPack --cache-ratio 8
170
+ sol-pi-axi setup ~/work/app --reducer anthropic/claude-sonnet-4-5 --format json
171
+ ```
172
+
173
+ Every run except `--help` and `--version` prints one envelope on standard output: [TOON](https://github.com/toon-format/spec) under the root `axi`, or the same object as one JSON line with `--format json`. Every envelope has `verb`, `ok`, `version`, `warnings` and `help` (the next steps), and `error` when `ok` is false. A `setup` envelope adds `outcome` (`written`, `unchanged`, `failed` or `cancelled`), `path` (the file, absolute, or null), `config` (`features`, `reducer`, `cacheRatio`; null on failure, or the values shown so far when cancelled at a prompt) and `context` (`project`, `agentDir`). A usage error has `verb: usage` and `outcome: usage`.
174
+
175
+ With no verb, `sol-pi-axi` prints the home view: `bin`, `description`, and the state (`absent`, `valid` or `invalid`) of the working directory's `.pi/sol-pi.json` and of the agent directory's `sol-pi.json`.
176
+
177
+ Exit codes: exit code 0 for `written`, `unchanged` and the home view; 1 for `failed`; 2 for a usage error; 130, 143 and 129 for a run `cancelled` by `SIGINT`, `SIGTERM` or `SIGHUP` (nothing is written). After `written`, start `pi` in the project and trust it, so the extension reads the project file.
178
+
179
+ ### `sol-pi-axi install`, `sol-pi-axi uninstall` and `sol-pi-axi verify`
180
+
181
+ `sol-pi-axi install` runs Pi as `$PI_BIN` when it is set, else `pi` on `PATH`; with neither it fails, naming both. Every `pi` command runs from your home directory with `--no-approve`. It registers `npm:@anthill-tec/sol-pi@<version>` unless Pi's `settings.json` already holds exactly that source; an `npm:@anthill-tec/sol-pi` entry at another version is replaced in place by Pi, and other SoL-Pi sources (`npm:sol-pi`, a git or URL source, a local checkout path) are removed with `pi remove` only after `pi install` succeeds. An existing `sol-pi.json` in the agent directory is kept untouched; `--features`, `--reducer` and `--cache-ratio` apply only when the file is written. Its envelope adds `outcome` (`installed`, `unchanged`, `failed` or `cancelled`), `extension` (`source`, `registered`, `replaced`, `pi`), `config` (`path`, `state` `written` or `kept`, and the values) and `context` (`agentDir`); `unchanged` means nothing was registered and nothing written.
182
+
183
+ `sol-pi-axi uninstall` removes every SoL-Pi source Pi has registered with `pi remove`, and deletes no configuration file (`warnings` names the agent directory's `sol-pi.json` when it exists). Its envelope adds `outcome` (`removed`, `unchanged`, `failed` or `cancelled`), `removed` (the sources removed) and `context` (`agentDir`).
184
+
185
+ `sol-pi-axi install` ends, once the source is registered (`installed` or `unchanged`), by running the check that `sol-pi-axi verify` runs, proving Pi loads SoL-Pi; a failed check fails the run (exit 1, `failed`) and removes or rewrites nothing, reporting the registration and configuration as the run left them. Its envelope adds `verify` (below), `null` when the run ended before the check. A cancel during the check also gives `verify: null`.
186
+
187
+ `sol-pi-axi verify` runs that check alone; it registers nothing and writes no SoL-Pi file. It first requires exactly one SoL-Pi source in Pi's `settings.json`, an `npm:@anthill-tec/sol-pi` source or a local path, with its package on disk; then it starts `pi --offline --no-approve --mode rpc --no-session` from your home directory with `SOL_PI_AXI_VERIFY` set to a value unique to the run, sends one `get_state` command, and waits at most 30 seconds. It fails when Pi exits non-zero (a load failure: `error` quotes Pi's `Failed to load extension` line), when SoL-Pi reports a handler error (an `extension_error` inside its package, such as an invalid `sol-pi.json` at `session_start`), when no `get_state` response arrives, or when Pi started without loading SoL-Pi (no load signal carried the run's value, for example because a resource filter in `settings.json` excludes it). An extension that opens a dialog (`select`, `confirm`, `input` or `editor`) in `session_start` holds Pi until the 30-second bound kills it; `error` then names the dialog's method and title, as Pi does not name the extension that opened it. Another extension's `extension_error` is a warning. Its envelope adds `outcome` (`verified`, `failed` or `cancelled`), `verify`, `extension` (`state`, `source`) and `context` (`agentDir`); `verify` has `ok`, `loaded` (SoL-Pi's load signal was seen), `exit` (Pi's exit code, `null` when Pi was killed or not started) and `errors` (SoL-Pi's own `extensionPath`, `event`, `error` entries). Exit codes: 0 `verified`, 1 `failed`, 130, 143 and 129 `cancelled`. On failure `help` holds the fix: `sol-pi-axi install` when no usable source is registered; for an invalid agent-directory `sol-pi.json`, correct it, or delete it and run `sol-pi-axi install`; otherwise `sol-pi-axi install` and `sol-pi-axi uninstall`. Pi may create `auth.json` and `models-store.json` in the agent directory.
188
+
189
+ The home view also shows the extension: `extension` has `state` (`absent` or `registered`) and the registered `source`. When the registered source is not `npm:@anthill-tec/sol-pi` at `sol-pi-axi`'s own version, the home view warns and adds `sol-pi-axi install` to `help`.
190
+
191
+ For the complete schema, see [Configuration](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/configuration.md). Coding agents and automated environments should follow the canonical [agent installation and configuration protocol](https://github.com/anthill-tec/SoL-Pi/blob/main/agents-install.md), which describes an all-enabled configuration checked with `scripts/check-sol-pi-config.mjs --require-all-enabled`.
192
+
193
+ ### Prompting with `--interactive`
194
+
195
+ `sol-pi-axi setup --interactive` and `sol-pi-axi install --interactive` ask for the values instead of taking them only from flags: each mechanism (yes or no), the reducer's `<provider>/<model>` when the reducer is on, and the cache ratio. The defaults are the values the run would use without `--interactive`, after any value flags; an answer the matching flag would reject repeats the prompt, and the reducer prompt suggests the usable `enabledModels` entries of the agent directory's `settings.json`. The run then shows the result and asks for confirmation. `setup` prompts for the project file's values; `install` prompts only when it will create the agent directory's `sol-pi.json`, and otherwise installs without prompting. Prompts go to standard error; standard output carries only the envelope. `--interactive` is a usage error with `--non-interactive`, with no verb, and on `uninstall` and `verify`.
196
+
197
+ `--interactive` prompts only when standard input and standard error are both terminals, the process group is that terminal's foreground group, and `PI_NONINTERACTIVE` is unset or empty. Otherwise the run adds a warning saying why and runs as it would without `--interactive`, with the same outcome and exit code.
198
+
199
+ A prompted run can be cancelled before the confirmation: declining it, Ctrl+C, Ctrl+D on an empty line or `SIGINT` exit 130, `SIGTERM` 143, and a closed terminal (`SIGHUP`) 129. These cancel exit codes are an addition to AXI's exit codes (0, 1 and 2); a cancelled run prints a `cancelled` envelope, writes and registers nothing, and leaves no temporary file.
200
+
201
+ ### Pi 1.x and codemode
202
+
203
+ SoL-Pi is tested with Pi 0.84.2, 1.0.4, 1.3.0, and 1.5.0. All four mechanisms work with Pi codemode in both `codemode.mode: "on"` and `"only"`. In `"only"` mode, the model reaches bash, edit, and write through codemode scripts, and Evidence-Preserving Reducer skips script calls, so it has no effect there. See [Codemode](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/compatibility.md#codemode) for per-mechanism behavior.
204
+
205
+ To check the Pi that will load SoL-Pi, install the checkout's dependencies, then run the check from the checkout; `--strict` also fails on an untested Pi version. Without `bun install`, the check cannot load TypeScript, prints a warning, and fails under `--strict` even on a tested Pi. For a Pi installed with Bun:
206
+
207
+ ```bash
208
+ bun install --frozen-lockfile --ignore-scripts
209
+ bun scripts/check-pi-compat.mjs --pi-root "$HOME/.bun/install/global/node_modules"
210
+ ```
211
+
212
+ For a Pi installed with npm:
213
+
214
+ ```bash
215
+ bun scripts/check-pi-compat.mjs --pi-root "$(npm root -g)"
216
+ ```
217
+
218
+ ## Storage and Security
219
+
220
+ ObservationPack and Evidence-Preserving Reducer store session-specific archives under:
221
+
222
+ ```text
223
+ <session-directory>/sol-pi/<session-id>/
224
+ ├── observation-pack/
225
+ └── evidence-preserving-reducer/
226
+ ```
227
+
228
+ They archive eligible source material in this directory. The archived copies remain local and are not automatically deleted when the Pi session ends.
229
+
230
+ With `pi --no-session` or `SessionManager.inMemory()`, Pi provides no session directory. SoL-Pi instead creates a private directory named `sol-pi-<session-id>-<random>/` under the operating system's temporary directory. ObservationPack and Evidence-Preserving Reducer share this directory for the lifetime of the loaded extension. These modes disable Pi's session-log persistence; SoL-Pi still writes archive files for exact recall. Temporary archives are also retained after the session or worker exits so callers can read referenced evidence. Their eventual cleanup follows the host's temporary-file policy or the caller's cleanup, and they are not guaranteed to survive system cleanup or support session recovery.
231
+
232
+ 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; after a failed compaction, it continues the task without compacting and reports the error. Cancelling the compaction or exiting Pi does not trigger automatic continuation.
233
+
234
+ Evidence-Preserving Reducer may send eligible diagnostic-log content to its configured reducer model using Pi-managed authentication. Review [SECURITY.md](https://github.com/anthill-tec/SoL-Pi/blob/main/SECURITY.md) before enabling it. Do not enable remote reduction for logs that must remain local.
235
+
236
+ ## Documentation
237
+
238
+ | Document | Purpose |
239
+ |---|---|
240
+ | [Configuration](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/configuration.md) | Config search order, schema, defaults, and trust behavior |
241
+ | [Compatibility](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/compatibility.md) | Supported Pi APIs and standalone integration details |
242
+ | [Security](https://github.com/anthill-tec/SoL-Pi/blob/main/SECURITY.md) | Local storage, remote reduction, and sensitive behavior |
243
+ | [Agent installation](https://github.com/anthill-tec/SoL-Pi/blob/main/agents-install.md) | Reproducible installation and all-enabled validation procedure |
244
+
245
+ ## Development
246
+
247
+ To install SoL-Pi from a checkout while developing it, see [CONTRIBUTING.md](https://github.com/anthill-tec/SoL-Pi/blob/main/CONTRIBUTING.md). Install from the lockfile and run the complete source checks:
248
+
249
+ ```bash
250
+ bun install --frozen-lockfile --ignore-scripts
251
+ bun run check
252
+ bun audit --audit-level=high
253
+ bun run check:pi
254
+ ```
255
+
256
+ `bun run check` covers TypeScript, the complete test suite, and package inspection. `bun run check:pi` runs `scripts/check-pi-compat.mjs` against the development dependency; pass `-- --strict` to fail on warnings, or `-- --pi-root <dir>` to check another Pi installation. The development dependency set is pinned to Pi 1.5.0. To check another tested Pi version, install its four Pi packages over the development dependency (for 1.0.4 also `pi-codemode`, `pi-mcp` and `chord` at 1.0.4) and rerun the checks; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades.
257
+
258
+ ## Project Status
259
+
260
+ SoL-Pi is developed and maintained by NVIDIA as a standalone extension for Pi.
261
+
262
+ We welcome tested, Pi-compatible extension PRs that improve token efficiency and reduce token cost. Our team will help benchmark contributions, publish results on a regular reporting cycle, and credit authors of accepted PRs as Contributors. See [CONTRIBUTING.md](https://github.com/anthill-tec/SoL-Pi/blob/main/CONTRIBUTING.md) for details.
263
+
264
+ ## Acknowledgements
265
+
266
+ 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.
267
+
268
+ ## License
269
+
270
+ SoL-Pi is released under the [MIT License](https://github.com/anthill-tec/SoL-Pi/blob/main/LICENSE).
271
+
272
+ ## Star History
273
+
274
+ <a href="https://www.star-history.com/?repos=NVlabs%2FSoL-Pi&amp;type=date">
275
+ <picture>
276
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-dark.svg" />
277
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-light.svg" />
278
+ <img alt="SoL-Pi star history chart" src="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-light.svg" width="100%" />
279
+ </picture>
280
+ </a>
sol_pi_axi-0.1.0/README.md ADDED
@@ -0,0 +1,264 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/anthill-tec/SoL-Pi/main/assets/sol-pi-hero.png" width="100%" alt="SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses" />
3
+ </p>
4
+
5
+ # ⚡ SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses
6
+
7
+ <p align="center">
8
+ <a href="https://arxiv.org/abs/2609.20519"><img src="https://img.shields.io/badge/arXiv-2609.20519-B31B1B?logo=arxiv&amp;logoColor=white" alt="arXiv: 2609.20519" /></a>
9
+ <a href="#getting-started"><img src="https://img.shields.io/badge/Getting%20Started-Install-76B900" alt="Getting Started" /></a>
10
+ <a href="https://github.com/anthill-tec/SoL-Pi/blob/main/docs/configuration.md"><img src="https://img.shields.io/badge/Docs-Configuration-555555" alt="Configuration" /></a>
11
+ <a href="https://nvlabs.github.io/SoL-Pi/"><img src="https://img.shields.io/badge/Blog-SoL--Pi-76B900" alt="SoL-Pi Blog" /></a>
12
+ <a href="https://github.com/anthill-tec/SoL-Pi/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a>
13
+ </p>
14
+
15
+ > [!NOTE]
16
+ > This repository contains the open-source version of SoL-Pi, a standalone extension for [Pi](https://github.com/earendil-works/pi). It is not an official distribution of Pi.
17
+ >
18
+ > SoL-Pi is under active development to support pi-v1 and the latest model checkpoints.
19
+
20
+ ## 📰 News
21
+
22
+ - **2026-10-14** — Released the [SoL-Pi Skill](https://github.com/anthill-tec/SoL-Pi/blob/main/examples/sol-pi-skill/README.md) example: use SoL-Pi as a skill from Claude Code (`/sol-pi`) or Codex (`$sol-pi`). The current task is handed to SoL-Pi with the host conversation as context, runs in the background, and its result is reported back to the session.
23
+ - **2026-10-13** — Released the [SoL-Pi Visual](https://github.com/anthill-tec/SoL-Pi/blob/main/examples/solpi-visual/README.md) example for 3D scene reconstruction in Blender. On this task, it lowers the cost per scene by **37%** compared with Codex, with 13% fewer model calls. See the example for visual scores and scene comparisons.
24
+
25
+ ## 💡 TL;DR
26
+
27
+ **Spend less without making the agent do less useful work.**
28
+
29
+ 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.
30
+
31
+ SoL-Pi installs on top of an unmodified Pi release. Every mechanism is disabled until a `sol-pi.json` enables it; `sol-pi-axi install` and `sol-pi-axi setup` write one with all four enabled unless `--features` says otherwise.
32
+
33
+ ## Introduction
34
+
35
+ 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.
36
+
37
+ 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.
38
+
39
+ 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.
40
+
41
+ ## What SoL-Pi Adds
42
+
43
+ | Area | Mechanism | What changes |
44
+ |---|---|---|
45
+ | Tools | **Action Fusion** | An edit or write can run its follow-up validation command in the same tool call. |
46
+ | Observations | **ObservationPack** | Repeated large text results become stable handles with exact paged recall. |
47
+ | Delegation | **Evidence-Preserving Reducer** | Long diagnostic logs become compact receipts only when every retained quotation matches the archived source. |
48
+ | 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. |
49
+
50
+ The mechanisms share four rules:
51
+
52
+ - **No Pi patches.** SoL-Pi imports public Pi APIs and does not vendor the Pi source tree.
53
+ - **Explicit opt-in.** A missing configuration leaves every mechanism disabled.
54
+ - **Preserve evidence.** Original observations remain available locally, and reducer failures leave the original result unchanged.
55
+ - **Use Pi's runtime choices.** Authentication, provider URLs, and the main model remain under Pi's control.
56
+
57
+ ## Technical Details and Core Insights
58
+
59
+ 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.
60
+
61
+ ## Paper
62
+
63
+ Read our paper: [SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness](https://arxiv.org/abs/2609.20519).
64
+
65
+ ## Getting Started
66
+
67
+ ### Requirements
68
+
69
+ - Node.js 22.19 or newer
70
+ - Python 3.14 or newer and [uv](https://docs.astral.sh/uv/), for the `sol-pi-axi` command
71
+ - Bun 1.4.4 or newer, only for a source checkout or a Bun-installed Pi
72
+ - `@earendil-works/pi-coding-agent` 0.84.2 or newer; tested with 0.84.2, 1.0.4, 1.3.0, and 1.5.0. Install 1.5.0, the latest tested release: a fresh install of Pi 1.0.x or 1.1.0 now fails to start, because those releases do not pin their internal packages. Other versions are untested: `scripts/check-pi-compat.mjs` warns on them, and `--strict` fails.
73
+
74
+ ### Install
75
+
76
+ Install the latest tested Pi release with Bun:
77
+
78
+ ```bash
79
+ bun add --global @earendil-works/pi-coding-agent@1.5.0
80
+ ```
81
+
82
+ Or, with npm:
83
+
84
+ ```bash
85
+ npm install --global @earendil-works/pi-coding-agent@1.5.0
86
+ ```
87
+
88
+ Pi 1.3.0 and 0.84.2 remain supported and tested; install `@earendil-works/pi-coding-agent@1.3.0` or `@earendil-works/pi-coding-agent@0.84.2` instead to stay on one of them.
89
+
90
+ Then install the `sol-pi-axi` command from PyPI and let it register the extension with Pi. It needs Python 3.14 or newer and [uv](https://docs.astral.sh/uv/); `<version>` is a SoL-Pi release:
91
+
92
+ ```bash
93
+ uv tool install sol-pi-axi==<version>
94
+ sol-pi-axi install
95
+ ```
96
+
97
+ `sol-pi-axi install` registers the extension `npm:@anthill-tec/sol-pi@<version>` with Pi (`pi install`, run from your home directory) and writes the agent directory's `sol-pi.json` with the setup defaults when it has none. On a Pi with no `defaultProvider` and `defaultModel` in its `settings.json` (a Pi never started), give the reducer's route, `sol-pi-axi install --reducer <provider>/<model>`, or leave the reducer off with `--features actionFusion,observationPack,onlineContextCompact`; otherwise the run fails and names `--reducer`. Then configure each project:
98
+
99
+ ```bash
100
+ sol-pi-axi setup <project dir>
101
+ ```
102
+
103
+ Alternatively, register the extension with Pi yourself, from npm:
104
+
105
+ ```bash
106
+ pi install npm:@anthill-tec/sol-pi@<version>
107
+ ```
108
+
109
+ The PyPI package `sol-pi-axi` and the npm package `@anthill-tec/sol-pi` share the same release version; `sol-pi-axi install` registers the extension at its own version.
110
+
111
+ Pi installs an `npm:` source by running `npm`, or the command array in its `npmCommand` setting (for example `["pnpm"]` or `["bun"]`); that command must be on `PATH`.
112
+
113
+ ### Configure
114
+
115
+ 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:
116
+
117
+ 1. `.pi/sol-pi.json` in the current project, if the project is trusted and the file exists;
118
+ 2. `~/.pi/agent/sol-pi.json` otherwise.
119
+
120
+ 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.
121
+
122
+ The following conservative configuration enables only the two local mechanisms that make no additional model calls and do not stop an active run:
123
+
124
+ ```json
125
+ {
126
+ "version": 1,
127
+ "actionFusion": true,
128
+ "observationPack": true,
129
+ "evidencePreservingReducer": false,
130
+ "onlineContextCompact": false,
131
+ "cacheWriteReadRatio": 12.5
132
+ }
133
+ ```
134
+
135
+ Enable additional mechanisms only after reviewing their configuration and security implications. The extension reads one environment variable, `SOL_PI_AXI_VERIFY`, only to answer `sol-pi-axi verify` (it sends the load signal that check waits for); feature flags, the reducer provider/model route, and the compaction ratio are configured in `sol-pi.json`. The `sol-pi-axi` command reads `PI_CODING_AGENT_DIR` to find the agent directory (default `~/.pi/agent`). See [sol-pi.example.json](https://github.com/anthill-tec/SoL-Pi/blob/main/sol-pi.example.json) for a template listing every key.
136
+
137
+ ### `sol-pi-axi setup`
138
+
139
+ `sol-pi-axi setup <project dir>` writes `<project dir>/.pi/sol-pi.json` (creating `.pi/` when missing) and nothing else. It prompts only with `--interactive` (see [Prompting with `--interactive`](#prompting-with---interactive)). Its base values are a valid project file's values, else the agent directory's `sol-pi.json`, else the setup defaults: all four mechanisms on, ratio 12.5, and the reducer on Pi's `defaultProvider` and `defaultModel` from the agent directory's `settings.json`. With no value flag, a valid project file is left `unchanged`. The flags override the base values:
140
+
141
+ | Flag | Value |
142
+ |---|---|
143
+ | `--features` | `all`, `none`, or a comma list of `actionFusion`, `observationPack`, `evidencePreservingReducer`, `onlineContextCompact`; unlisted ones off |
144
+ | `--reducer` | `<provider>/<model>`, split at the first `/` |
145
+ | `--cache-ratio` | digits with an optional decimal fraction |
146
+ | `--format` | `toon` (default) or `json` |
147
+ | `--interactive` | prompt for the values, then confirm (see below) |
148
+ | `--non-interactive` | accepted; setup prompts only with `--interactive`, and the two together are a usage error |
149
+ | `-h`, `--help` | plain-text help |
150
+ | `-v`, `-V`, `--version` | the bare version |
151
+
152
+ ```bash
153
+ sol-pi-axi setup . --features actionFusion,observationPack --cache-ratio 8
154
+ sol-pi-axi setup ~/work/app --reducer anthropic/claude-sonnet-4-5 --format json
155
+ ```
156
+
157
+ Every run except `--help` and `--version` prints one envelope on standard output: [TOON](https://github.com/toon-format/spec) under the root `axi`, or the same object as one JSON line with `--format json`. Every envelope has `verb`, `ok`, `version`, `warnings` and `help` (the next steps), and `error` when `ok` is false. A `setup` envelope adds `outcome` (`written`, `unchanged`, `failed` or `cancelled`), `path` (the file, absolute, or null), `config` (`features`, `reducer`, `cacheRatio`; null on failure, or the values shown so far when cancelled at a prompt) and `context` (`project`, `agentDir`). A usage error has `verb: usage` and `outcome: usage`.
158
+
159
+ With no verb, `sol-pi-axi` prints the home view: `bin`, `description`, and the state (`absent`, `valid` or `invalid`) of the working directory's `.pi/sol-pi.json` and of the agent directory's `sol-pi.json`.
160
+
161
+ Exit codes: exit code 0 for `written`, `unchanged` and the home view; 1 for `failed`; 2 for a usage error; 130, 143 and 129 for a run `cancelled` by `SIGINT`, `SIGTERM` or `SIGHUP` (nothing is written). After `written`, start `pi` in the project and trust it, so the extension reads the project file.
162
+
163
+ ### `sol-pi-axi install`, `sol-pi-axi uninstall` and `sol-pi-axi verify`
164
+
165
+ `sol-pi-axi install` runs Pi as `$PI_BIN` when it is set, else `pi` on `PATH`; with neither it fails, naming both. Every `pi` command runs from your home directory with `--no-approve`. It registers `npm:@anthill-tec/sol-pi@<version>` unless Pi's `settings.json` already holds exactly that source; an `npm:@anthill-tec/sol-pi` entry at another version is replaced in place by Pi, and other SoL-Pi sources (`npm:sol-pi`, a git or URL source, a local checkout path) are removed with `pi remove` only after `pi install` succeeds. An existing `sol-pi.json` in the agent directory is kept untouched; `--features`, `--reducer` and `--cache-ratio` apply only when the file is written. Its envelope adds `outcome` (`installed`, `unchanged`, `failed` or `cancelled`), `extension` (`source`, `registered`, `replaced`, `pi`), `config` (`path`, `state` `written` or `kept`, and the values) and `context` (`agentDir`); `unchanged` means nothing was registered and nothing written.
166
+
167
+ `sol-pi-axi uninstall` removes every SoL-Pi source Pi has registered with `pi remove`, and deletes no configuration file (`warnings` names the agent directory's `sol-pi.json` when it exists). Its envelope adds `outcome` (`removed`, `unchanged`, `failed` or `cancelled`), `removed` (the sources removed) and `context` (`agentDir`).
168
+
169
+ `sol-pi-axi install` ends, once the source is registered (`installed` or `unchanged`), by running the check that `sol-pi-axi verify` runs, proving Pi loads SoL-Pi; a failed check fails the run (exit 1, `failed`) and removes or rewrites nothing, reporting the registration and configuration as the run left them. Its envelope adds `verify` (below), `null` when the run ended before the check. A cancel during the check also gives `verify: null`.
170
+
171
+ `sol-pi-axi verify` runs that check alone; it registers nothing and writes no SoL-Pi file. It first requires exactly one SoL-Pi source in Pi's `settings.json`, an `npm:@anthill-tec/sol-pi` source or a local path, with its package on disk; then it starts `pi --offline --no-approve --mode rpc --no-session` from your home directory with `SOL_PI_AXI_VERIFY` set to a value unique to the run, sends one `get_state` command, and waits at most 30 seconds. It fails when Pi exits non-zero (a load failure: `error` quotes Pi's `Failed to load extension` line), when SoL-Pi reports a handler error (an `extension_error` inside its package, such as an invalid `sol-pi.json` at `session_start`), when no `get_state` response arrives, or when Pi started without loading SoL-Pi (no load signal carried the run's value, for example because a resource filter in `settings.json` excludes it). An extension that opens a dialog (`select`, `confirm`, `input` or `editor`) in `session_start` holds Pi until the 30-second bound kills it; `error` then names the dialog's method and title, as Pi does not name the extension that opened it. Another extension's `extension_error` is a warning. Its envelope adds `outcome` (`verified`, `failed` or `cancelled`), `verify`, `extension` (`state`, `source`) and `context` (`agentDir`); `verify` has `ok`, `loaded` (SoL-Pi's load signal was seen), `exit` (Pi's exit code, `null` when Pi was killed or not started) and `errors` (SoL-Pi's own `extensionPath`, `event`, `error` entries). Exit codes: 0 `verified`, 1 `failed`, 130, 143 and 129 `cancelled`. On failure `help` holds the fix: `sol-pi-axi install` when no usable source is registered; for an invalid agent-directory `sol-pi.json`, correct it, or delete it and run `sol-pi-axi install`; otherwise `sol-pi-axi install` and `sol-pi-axi uninstall`. Pi may create `auth.json` and `models-store.json` in the agent directory.
172
+
173
+ The home view also shows the extension: `extension` has `state` (`absent` or `registered`) and the registered `source`. When the registered source is not `npm:@anthill-tec/sol-pi` at `sol-pi-axi`'s own version, the home view warns and adds `sol-pi-axi install` to `help`.
174
+
175
+ For the complete schema, see [Configuration](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/configuration.md). Coding agents and automated environments should follow the canonical [agent installation and configuration protocol](https://github.com/anthill-tec/SoL-Pi/blob/main/agents-install.md), which describes an all-enabled configuration checked with `scripts/check-sol-pi-config.mjs --require-all-enabled`.
176
+
177
+ ### Prompting with `--interactive`
178
+
179
+ `sol-pi-axi setup --interactive` and `sol-pi-axi install --interactive` ask for the values instead of taking them only from flags: each mechanism (yes or no), the reducer's `<provider>/<model>` when the reducer is on, and the cache ratio. The defaults are the values the run would use without `--interactive`, after any value flags; an answer the matching flag would reject repeats the prompt, and the reducer prompt suggests the usable `enabledModels` entries of the agent directory's `settings.json`. The run then shows the result and asks for confirmation. `setup` prompts for the project file's values; `install` prompts only when it will create the agent directory's `sol-pi.json`, and otherwise installs without prompting. Prompts go to standard error; standard output carries only the envelope. `--interactive` is a usage error with `--non-interactive`, with no verb, and on `uninstall` and `verify`.
180
+
181
+ `--interactive` prompts only when standard input and standard error are both terminals, the process group is that terminal's foreground group, and `PI_NONINTERACTIVE` is unset or empty. Otherwise the run adds a warning saying why and runs as it would without `--interactive`, with the same outcome and exit code.
182
+
183
+ A prompted run can be cancelled before the confirmation: declining it, Ctrl+C, Ctrl+D on an empty line or `SIGINT` exit 130, `SIGTERM` 143, and a closed terminal (`SIGHUP`) 129. These cancel exit codes are an addition to AXI's exit codes (0, 1 and 2); a cancelled run prints a `cancelled` envelope, writes and registers nothing, and leaves no temporary file.
184
+
185
+ ### Pi 1.x and codemode
186
+
187
+ SoL-Pi is tested with Pi 0.84.2, 1.0.4, 1.3.0, and 1.5.0. All four mechanisms work with Pi codemode in both `codemode.mode: "on"` and `"only"`. In `"only"` mode, the model reaches bash, edit, and write through codemode scripts, and Evidence-Preserving Reducer skips script calls, so it has no effect there. See [Codemode](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/compatibility.md#codemode) for per-mechanism behavior.
188
+
189
+ To check the Pi that will load SoL-Pi, install the checkout's dependencies, then run the check from the checkout; `--strict` also fails on an untested Pi version. Without `bun install`, the check cannot load TypeScript, prints a warning, and fails under `--strict` even on a tested Pi. For a Pi installed with Bun:
190
+
191
+ ```bash
192
+ bun install --frozen-lockfile --ignore-scripts
193
+ bun scripts/check-pi-compat.mjs --pi-root "$HOME/.bun/install/global/node_modules"
194
+ ```
195
+
196
+ For a Pi installed with npm:
197
+
198
+ ```bash
199
+ bun scripts/check-pi-compat.mjs --pi-root "$(npm root -g)"
200
+ ```
201
+
202
+ ## Storage and Security
203
+
204
+ ObservationPack and Evidence-Preserving Reducer store session-specific archives under:
205
+
206
+ ```text
207
+ <session-directory>/sol-pi/<session-id>/
208
+ ├── observation-pack/
209
+ └── evidence-preserving-reducer/
210
+ ```
211
+
212
+ They archive eligible source material in this directory. The archived copies remain local and are not automatically deleted when the Pi session ends.
213
+
214
+ With `pi --no-session` or `SessionManager.inMemory()`, Pi provides no session directory. SoL-Pi instead creates a private directory named `sol-pi-<session-id>-<random>/` under the operating system's temporary directory. ObservationPack and Evidence-Preserving Reducer share this directory for the lifetime of the loaded extension. These modes disable Pi's session-log persistence; SoL-Pi still writes archive files for exact recall. Temporary archives are also retained after the session or worker exits so callers can read referenced evidence. Their eventual cleanup follows the host's temporary-file policy or the caller's cleanup, and they are not guaranteed to survive system cleanup or support session recovery.
215
+
216
+ 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; after a failed compaction, it continues the task without compacting and reports the error. Cancelling the compaction or exiting Pi does not trigger automatic continuation.
217
+
218
+ Evidence-Preserving Reducer may send eligible diagnostic-log content to its configured reducer model using Pi-managed authentication. Review [SECURITY.md](https://github.com/anthill-tec/SoL-Pi/blob/main/SECURITY.md) before enabling it. Do not enable remote reduction for logs that must remain local.
219
+
220
+ ## Documentation
221
+
222
+ | Document | Purpose |
223
+ |---|---|
224
+ | [Configuration](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/configuration.md) | Config search order, schema, defaults, and trust behavior |
225
+ | [Compatibility](https://github.com/anthill-tec/SoL-Pi/blob/main/docs/compatibility.md) | Supported Pi APIs and standalone integration details |
226
+ | [Security](https://github.com/anthill-tec/SoL-Pi/blob/main/SECURITY.md) | Local storage, remote reduction, and sensitive behavior |
227
+ | [Agent installation](https://github.com/anthill-tec/SoL-Pi/blob/main/agents-install.md) | Reproducible installation and all-enabled validation procedure |
228
+
229
+ ## Development
230
+
231
+ To install SoL-Pi from a checkout while developing it, see [CONTRIBUTING.md](https://github.com/anthill-tec/SoL-Pi/blob/main/CONTRIBUTING.md). Install from the lockfile and run the complete source checks:
232
+
233
+ ```bash
234
+ bun install --frozen-lockfile --ignore-scripts
235
+ bun run check
236
+ bun audit --audit-level=high
237
+ bun run check:pi
238
+ ```
239
+
240
+ `bun run check` covers TypeScript, the complete test suite, and package inspection. `bun run check:pi` runs `scripts/check-pi-compat.mjs` against the development dependency; pass `-- --strict` to fail on warnings, or `-- --pi-root <dir>` to check another Pi installation. The development dependency set is pinned to Pi 1.5.0. To check another tested Pi version, install its four Pi packages over the development dependency (for 1.0.4 also `pi-codemode`, `pi-mcp` and `chord` at 1.0.4) and rerun the checks; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades.
241
+
242
+ ## Project Status
243
+
244
+ SoL-Pi is developed and maintained by NVIDIA as a standalone extension for Pi.
245
+
246
+ We welcome tested, Pi-compatible extension PRs that improve token efficiency and reduce token cost. Our team will help benchmark contributions, publish results on a regular reporting cycle, and credit authors of accepted PRs as Contributors. See [CONTRIBUTING.md](https://github.com/anthill-tec/SoL-Pi/blob/main/CONTRIBUTING.md) for details.
247
+
248
+ ## Acknowledgements
249
+
250
+ 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.
251
+
252
+ ## License
253
+
254
+ SoL-Pi is released under the [MIT License](https://github.com/anthill-tec/SoL-Pi/blob/main/LICENSE).
255
+
256
+ ## Star History
257
+
258
+ <a href="https://www.star-history.com/?repos=NVlabs%2FSoL-Pi&amp;type=date">
259
+ <picture>
260
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-dark.svg" />
261
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-light.svg" />
262
+ <img alt="SoL-Pi star history chart" src="https://raw.githubusercontent.com/NVlabs/SoL-Pi/star-history/star-history-light.svg" width="100%" />
263
+ </picture>
264
+ </a>