# nvlabs/sol-pi architecture

> Architecture diagram of the GitHub repository nvlabs/sol-pi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvlabs/sol-pi
- Repository: https://github.com/nvlabs/sol-pi

## Overview

SoL-Pi is an opt-in extension for Pi that reduces repeated tool turns, replayed observations, long diagnostic output, and context overhead. Pi starts the extension, which loads configuration and registers enabled mechanisms. Those mechanisms act at different points in the agent loop: file mutation, context preparation and recall, tool-result handling, and plan-aware compaction. The README documents all four mechanisms; the sampled source confirms their registration and several internal flows, but some event-handler wiring is only partially excerpted.

Main entry points: [`src/sol-pi/extensions/evidence-preserving-reducer/index.ts`](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/index.ts) (Evidence-Preserving Reducer), [`src/sol-pi/extensions/online-context-compact/extension.ts`](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/extension.ts) (Online Context Compact), [`src/sol-pi/index.ts`](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/index.ts) (Extension entry), [`src/sol-pi/extensions/observation-pack/index.ts`](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/observation-pack/index.ts) (ObservationPack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Extension Setup"]
  node_config["Configuration loader<br/>[config.ts]"]
  node_entry["Extension entry<br/>[index.ts]"]
  node_tui["Savings display<br/>[tui.ts]"]
end

subgraph group_tools["Tool Efficiency"]
  node_action["Action Fusion<br/>[index.ts]"]
  node_thenrun["Mutation then run<br/>[then-run.ts]"]
  node_observation["ObservationPack<br/>[index.ts]"]
  node_obs_logic["Observation storage and recall<br/>[observation.ts]"]
  node_obs_ledger["Observation ledger<br/>[ledger.ts]"]
end

subgraph group_evidence["Evidence Handling"]
  node_reducer["Evidence-Preserving Reducer<br/>[index.ts]"]
  node_candidate["Log candidate filter<br/>[candidate.ts]"]
  node_archive["Log archive<br/>[archive.ts]"]
  node_receipt["Receipt validation<br/>[receipt.ts]"]
  node_journal["Reducer journal<br/>[journal.ts]"]
end

subgraph group_context["Context Management"]
  node_online["Online Context Compact<br/>[extension.ts]"]
  node_plan["Plan transition analysis<br/>[plan.ts]"]
  node_economics["Compaction economics<br/>[economics.ts]"]
  node_online_state["Compaction state<br/>[state.ts]"]
end

node_pi_user(("Pi user/agent"))
node_pi_runtime["Pi runtime"]
node_bash["Pi bash tool"]
node_session_store[("Session archives<br/>[runtime-paths.ts]")]
node_reducer_model["Configured reducer model"]
node_pi_session[("Pi session log")]

node_pi_user -->|"uses"| node_pi_runtime
node_pi_runtime -->|"loads extension"| node_entry
node_entry -->|"loads settings"| node_config
node_entry -->|"registers enabled"| node_action
node_entry -->|"registers enabled"| node_observation
node_entry -->|"registers enabled"| node_reducer
node_entry -->|"registers enabled"| node_online
node_action -->|"executes mutation and command"| node_thenrun
node_thenrun -->|"runs follow-up"| node_bash
node_observation -->|"stores and recalls"| node_obs_logic
node_observation -->|"records events"| node_obs_ledger
node_obs_logic -->|"writes and reads objects"| node_session_store
node_obs_ledger -->|"writes ledger"| node_session_store
node_reducer -->|"filters tool result"| node_candidate
node_reducer -->|"archives eligible log"| node_archive
node_reducer -.->|"requests reduction"| node_reducer_model
node_reducer -->|"validates response"| node_receipt
node_reducer -->|"records decisions"| node_journal
node_archive -->|"stores source"| node_session_store
node_journal -->|"writes journal"| node_session_store
node_online -->|"analyzes plan"| node_plan
node_online -->|"decides compaction"| node_economics
node_online -->|"restores and records"| node_online_state
node_online -->|"reads and updates session"| node_pi_session
node_online -->|"requests native compaction"| node_pi_runtime
node_action -->|"renders savings"| node_tui
node_observation -->|"renders recall"| node_tui
node_reducer -->|"reports savings"| node_tui
node_online -->|"reports savings"| node_tui

click node_config "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/config.ts"
click node_entry "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/index.ts"
click node_action "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/action-fusion/index.ts"
click node_thenrun "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/action-fusion/then-run.ts"
click node_observation "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/observation-pack/index.ts"
click node_obs_logic "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/observation-pack/observation.ts"
click node_obs_ledger "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/observation-pack/ledger.ts"
click node_session_store "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/runtime-paths.ts"
click node_reducer "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/index.ts"
click node_candidate "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/candidate.ts"
click node_archive "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/archive.ts"
click node_receipt "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/receipt.ts"
click node_journal "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/journal.ts"
click node_online "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/extension.ts"
click node_plan "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/plan.ts"
click node_economics "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/economics.ts"
click node_online_state "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/state.ts"
click node_tui "https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/tui.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_entry,node_tui,node_pi_user toneBlue
class node_action,node_thenrun,node_observation,node_obs_logic,node_obs_ledger,node_session_store,node_pi_session toneAmber
class node_reducer,node_candidate,node_archive,node_receipt,node_journal toneMint
class node_online,node_plan,node_economics,node_online_state toneRose
class node_pi_runtime,node_bash,node_reducer_model toneIndigo
```

## Components

### Extension Setup

- [Configuration loader](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/config.ts): `src/sol-pi/config.ts`
- [Extension entry](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/index.ts): `src/sol-pi/index.ts`
- [Savings display](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/tui.ts): `src/sol-pi/tui.ts`

### Tool Efficiency

- [Action Fusion](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/action-fusion/index.ts): `src/sol-pi/extensions/action-fusion/index.ts`
- [Mutation then run](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/action-fusion/then-run.ts): `src/sol-pi/extensions/action-fusion/then-run.ts`
- [ObservationPack](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/observation-pack/index.ts): `src/sol-pi/extensions/observation-pack/index.ts`
- [Observation storage and recall](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/observation-pack/observation.ts): `src/sol-pi/extensions/observation-pack/observation.ts`
- [Observation ledger](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/observation-pack/ledger.ts): `src/sol-pi/extensions/observation-pack/ledger.ts`

### Evidence Handling

- [Evidence-Preserving Reducer](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/index.ts): `src/sol-pi/extensions/evidence-preserving-reducer/index.ts`
- [Log candidate filter](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/candidate.ts): `src/sol-pi/extensions/evidence-preserving-reducer/candidate.ts`
- [Log archive](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/archive.ts): `src/sol-pi/extensions/evidence-preserving-reducer/archive.ts`
- [Receipt validation](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/receipt.ts): `src/sol-pi/extensions/evidence-preserving-reducer/receipt.ts`
- [Reducer journal](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/evidence-preserving-reducer/journal.ts): `src/sol-pi/extensions/evidence-preserving-reducer/journal.ts`

### Context Management

- [Online Context Compact](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/extension.ts): `src/sol-pi/extensions/online-context-compact/extension.ts`
- [Plan transition analysis](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/plan.ts): `src/sol-pi/extensions/online-context-compact/plan.ts`
- [Compaction economics](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/economics.ts): `src/sol-pi/extensions/online-context-compact/economics.ts`
- [Compaction state](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/extensions/online-context-compact/state.ts): `src/sol-pi/extensions/online-context-compact/state.ts`

### Other components

- **Pi user/agent**
- **Pi runtime**
- **Pi bash tool**
- [Session archives](https://github.com/nvlabs/sol-pi/blob/main/src/sol-pi/runtime-paths.ts): `src/sol-pi/runtime-paths.ts`
- **Configured reducer model**
- **Pi session log**

## Connections

- Pi user/agent → Pi runtime: uses
- Pi runtime → Extension entry: loads extension
- Extension entry → Configuration loader: loads settings
- Extension entry → Action Fusion: registers enabled
- Extension entry → ObservationPack: registers enabled
- Extension entry → Evidence-Preserving Reducer: registers enabled
- Extension entry → Online Context Compact: registers enabled
- Action Fusion → Mutation then run: executes mutation and command
- Mutation then run → Pi bash tool: runs follow-up
- ObservationPack → Observation storage and recall: stores and recalls
- ObservationPack → Observation ledger: records events
- Observation storage and recall → Session archives: writes and reads objects
- Observation ledger → Session archives: writes ledger
- Evidence-Preserving Reducer → Log candidate filter: filters tool result
- Evidence-Preserving Reducer → Log archive: archives eligible log
- Evidence-Preserving Reducer → Configured reducer model: requests reduction
- Evidence-Preserving Reducer → Receipt validation: validates response
- Evidence-Preserving Reducer → Reducer journal: records decisions
- Log archive → Session archives: stores source
- Reducer journal → Session archives: writes journal
- Online Context Compact → Plan transition analysis: analyzes plan
- Online Context Compact → Compaction economics: decides compaction
- Online Context Compact → Compaction state: restores and records
- Online Context Compact → Pi session log: reads and updates session
- Online Context Compact → Pi runtime: requests native compaction
- Action Fusion → Savings display: renders savings
- ObservationPack → Savings display: renders recall
- Evidence-Preserving Reducer → Savings display: reports savings
- Online Context Compact → Savings display: reports savings