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

[!NOTE] This package republishes the MIT-licensed SoL-Pi source from NVlabs/SoL-Pi. The complete import baseline remains e1a586af0ad8956f42ae5b26bba20e48fbf30e00, recorded in package.json; Pi 1.x and codemode compatibility fixes from 41fa7e0e230bedc5e639aed2e7b9cc5698726db1..219568034fa54ed121ede80961655e33dfb9d0e3 are selectively ported on top. This is not a complete re-import or an npm sol-pi@0.1.1 release. 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.

Pi 1.x and codemode behavior

Action Fusion reports failed follow-up commands without losing the mutation's edit details, and inherits Pi's file-backed shell settings with project trust respected. Nested codemode calls do not count as independent model round-trips. Evidence-Preserving Reducer leaves nested tool results and their structured content unchanged. ObservationPack preserves message identity so Pi's mid-conversation system messages keep their positions and cached prefixes.

Online Context Compact declares update_plan to the model only, including in codemode-only mode. Codemode scripts cannot call it: plan boundaries must appear as direct tool results in the agent turn. Compaction uses Pi's effective token settings and context projection, does not count cache-warming replays as provider requests, and resumes a stopped task after a non-cancellation compaction failure before reporting that error. User cancellation does not schedule a continuation.

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.

Paper

Read our paper: SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness.

Getting Started

Requirements

• Node.js 24 or newer
• npm
• @earendil-works/pi-coding-agent 1.2.0 (the monorepo's tested host; runtime peers remain *)

Install

Install the tested Pi release:

npm install --global @earendil-works/pi-coding-agent@1.2.0

Install this independently maintained package, or use @herbertgao/pi-extensions for the collection:

pi install npm:@herbertgao/sol-pi

To install it only for the current project, use the project-local scope:

pi install npm:@herbertgao/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:

{
  "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. See sol-pi.example.json for a template listing every key.

For the complete schema, see Configuration. Coding agents and automated environments should follow the canonical agent installation and configuration protocol, which describes an all-enabled configuration 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.

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.

Online Context Compact stores its state in Pi's session log. After a successful compaction, or a recoverable native refusal (session too small, already compacted, or an incomplete summary at the token cap), it automatically continues the active task. A refused attempt retains the existing context and adds no cache debt; plan-only turns cannot repeatedly retry it. 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, and trust behavior
Compatibility	Supported Pi APIs and standalone integration details
Security	Local storage, remote reduction, and sensitive behavior
Agent installation	Reproducible installation and all-enabled validation procedure

Development

From the monorepo root, install from its Bun lockfile and run the complete source checks:

bun install --frozen-lockfile
bun run check
bun audit
node packages/sol-pi/scripts/check-pi-compat.mjs

For package-only checks, run bun run --cwd packages/sol-pi typecheck and bun run --cwd packages/sol-pi test, then inspect the package with npm pack --dry-run from packages/sol-pi. Root development dependencies provide Pi 1.2.0; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades.

Project Status

The original SoL-Pi project is developed by NVIDIA as a standalone extension for Pi. This package is independently maintained in HerbertGao/pi-extensions.

For upstream contributions, see CONTRIBUTING.md. Report collection-specific issues to HerbertGao/pi-extensions; upstream private security channels remain described in SECURITY.md.

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

This chart tracks the original NVIDIA project. Its generator and tests are retained as development-only references; publication stays in the upstream workflow, not this monorepo.