⚡ SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses

[!NOTE] This repository contains the open-source version of SoL-Pi, a standalone extension for Pi. It is not an official distribution of Pi. The current checkout has primary host evidence on Pi 0.85.1; see release acceptance for the remaining gates.

💡 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 is designed to reduce 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; the TUI HUD is a separate display surface and mounts by default when the host exposes the required status API.

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 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
• Primary tested host: @earendil-works/pi-coding-agent 0.85.1
• Supported peer range: 0.84.2 || 0.85.1; Pi 0.84.2 remains a separately verified compatibility target with a narrower evidence boundary

Install

Install the primary tested Pi release:

npm install --global @earendil-works/[email protected]

From the project where Pi will run, install the published npm package in project-local scope:

pi install npm:[email protected] --local --approve
pi list --approve

For a user-wide npm registration, omit --local:

pi install npm:[email protected] --approve
pi list --approve

Use the source checkout for development validation only; do not register it as the user-facing npm installation. Do not register the npm package in both scopes. For the 0.84.2 compatibility target, use the isolated version-matrix procedure in compatibility-matrix.md; the current source lockfile and primary development checks resolve to 0.85.1.

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:

{
  "version": 1,
  "actionFusion": true,
  "observationPack": true,
  "evidencePreservingReducer": false,
  "evidencePreservingReducerRemote": 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. Coding agents and automated environments should follow the canonical agent installation and configuration protocol. 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:

<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 before enabling it. Do not enable remote reduction for logs that must remain local.

Documentation

| Document | Purpose | |---|---| | Configuration | Config search order, schema, defaults, migration, and trust behavior | | Compatibility | Supported Pi range, public APIs, backend boundaries, and evidence limits | | Troubleshooting | no-session, backend, config, recall, reducer, OCC, conflict, and rollback paths | | Compatibility matrix | Version-specific host evidence and unverified boundaries | | Release acceptance | Current source gates, HUD conclusions, benchmark status, and release blockers | | Security | Local storage, remote reduction, and sensitive behavior | | Agent installation | Reproducible installation and all-enabled validation procedure |

Development

Install from the lockfile and run the complete source checks:

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.85.1; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades. npm audit --audit-level=high is a separate required gate in the agent installation protocol.

Current Evidence Status

As of 2026-09-13, the current checkout has passing source/package gates, Pi 0.85.1 deterministic host and HUD evidence, and a T02 paired-benchmark harness. The harness defaults to dry-run; no real natural-task sample was executed because the target project, clean checkout, provider/model and authorized cost range were not selected. Therefore this repository does not claim a measured cost, latency, quality, or no-loss improvement.

Formal Pi installation is also a separate gate. A source checkout passing tests is not proof that a target project has the intended pi list scope, effective all-enabled sol-pi.json, provider authentication, or offline startup after installation. Use agents-install.md and record every missing step.

SoL-Pi is developed and maintained by NVIDIA as a standalone extension for Pi.

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 for details.

Acknowledgements

SoL-Pi builds on the public extension interfaces provided by Pi. Pi remains an independent upstream project and is not vendored into this repository.

License

SoL-Pi is released under the MIT License.

Star History