@alexeiled/pi-fusion 0.1.2 → 0.2.1

package/README.md

@@ -1,22 +1,121 @@
 # pi-fusion
 
-[![npm](https://img.shields.io/badge/npm-%40alexeiled%2Fpi--fusion-cb3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@alexeiled/pi-fusion)
+[![npm version](https://img.shields.io/npm/v/%40alexeiled%2Fpi-fusion?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@alexeiled/pi-fusion)
+[![CI](https://img.shields.io/github/actions/workflow/status/alexei-led/pi-fusion/test.yml?branch=master&style=flat-square&label=ci)](https://github.com/alexei-led/pi-fusion/actions/workflows/test.yml?query=branch%3Amaster)
 [![node](https://img.shields.io/badge/node-%3E%3D22.19.0-5fa04e?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
 [![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
 
-When a coding question deserves a design review, not a guess.
+> Parallel models. One judge. Better answers.
+
+`pi-fusion` is a Pi extension for hard technical questions.
+It uses `pi-subagents` to send the same prompt through a small parallel model panel,
+then asks a judge agent to compare the outputs and return the best realistic answer.
+
+CI covers lint, typecheck, unit tests, integration tests, package smoke tests,
+and `npm pack --dry-run`.
+
+![pi-fusion flow](https://raw.githubusercontent.com/alexei-led/pi-fusion/master/docs/assets/fusion-flow.png)
+
+## Why Fusion exists
+
+Hard questions are often bottlenecked by one model's search path.
+`pi-fusion` trades latency for diversity:
+
+- the same prompt fans out to several model runs in parallel
+- each model explores the problem from a different training prior and reasoning path
+- overlap raises confidence
+- disagreement exposes risk
+- the judge keeps the strongest parts and drops weak, partial, or conflicting ones
+
+This is evidence selection, not majority vote.
+
+```mermaid
+%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 28, "rankSpacing": 48}, "themeVariables": {"background": "#050816", "fontFamily": "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace", "primaryTextColor": "#E5F0FF", "lineColor": "#38bdf8", "tertiaryColor": "#0b1220"}}}%%
+flowchart LR
+  classDef prompt fill:#071321,stroke:#38bdf8,color:#dbeafe,stroke-width:2px;
+  classDef modelA fill:#081223,stroke:#38bdf8,color:#dbeafe,stroke-width:2px;
+  classDef modelB fill:#120826,stroke:#a855f7,color:#f3e8ff,stroke-width:2px;
+  classDef modelC fill:#08180f,stroke:#22c55e,color:#dcfce7,stroke-width:2px;
+  classDef modelD fill:#241307,stroke:#f59e0b,color:#fef3c7,stroke-width:2px;
+  classDef modelE fill:#260712,stroke:#ff4d8d,color:#ffd1e7,stroke-width:2px;
+  classDef judge fill:#2b1905,stroke:#f59e0b,color:#fef3c7,stroke-width:3px;
+  classDef answer fill:#062814,stroke:#22c55e,color:#dcfce7,stroke-width:3px;
+  classDef note fill:#0b1220,stroke:#475569,color:#cbd5e1,stroke-width:1px;
+
+  P["input prompt<br/>same question to every model"]:::prompt
+
+  subgraph PANEL[parallel model panel]
+    direction TB
+    A["model A<br/>strong baseline candidate"]:::modelA
+    B["model B<br/>finds contradiction"]:::modelB
+    C["model C<br/>adds unique insight"]:::modelC
+    D["model D<br/>fast practical path"]:::modelD
+    E["model E<br/>catches edge case"]:::modelE
+  end
+
+  J["judge<br/>consensus • contradictions • blind spots"]:::judge
+  R["best answer<br/>selected or synthesized"]:::answer
+  N["not majority vote<br/>best evidence wins"]:::note
+
+  P --> A
+  P --> B
+  P --> C
+  P --> D
+  P --> E
+
+  A --> J
+  B --> J
+  C --> J
+  D --> J
+  E --> J
+
+  J --> R
+  J -.-> N
+
+  linkStyle 0,5 stroke:#38bdf8,stroke-width:3px;
+  linkStyle 1,6 stroke:#a855f7,stroke-width:3px;
+  linkStyle 2,7 stroke:#22c55e,stroke-width:3px;
+  linkStyle 3,8 stroke:#f59e0b,stroke-width:3px;
+  linkStyle 4,9 stroke:#ff4d8d,stroke-width:3px;
+  linkStyle 10 stroke:#22c55e,stroke-width:4px;
+  linkStyle 11 stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5;
+```
+
+## Why a panel can beat one model
+
+Single-model answers are brittle on hard tasks. They are limited by one model's
+priors, one reasoning path, and one failure mode.
+
+A panel helps because:
+
+- different models are trained differently and make different bets
+- errors are less correlated, so blind spots do not line up perfectly
+- consensus is a useful confidence signal without pretending certainty
+- disagreement tells you where the answer is fragile
+- a judge can select or synthesize the best realistic answer from the set
+
+The result is slower, but usually better for design choices, risk review,
+tricky debugging, and research-heavy questions.
+
+## What the judge actually does
+
+The judge gets:
 
-`pi-fusion` is a Pi extension that runs a small panel of read-only subagents in parallel, then asks a judge agent to synthesize one final report.
+- the original prompt
+- every panel output
+- panel failures and blind spots
+- the configured judge model
 
-You get:
+It then:
 
-- consensus
-- disagreements
-- blind spots
-- risks
-- recommended next step
+- finds consensus
+- preserves real disagreements
+- spots weak or incomplete answers
+- pulls forward unique insights worth keeping
+- returns one clear recommendation and next step
 
-It applies the [Fusion](https://openrouter.ai/blog/announcements/fusion-beats-frontier/) idea to Pi: spend extra tokens only on questions where multiple perspectives are worth it.
+It does not edit files or spawn more subagents. It does one job: choose or
+synthesize the best realistic answer.
 
 ## Good fit
 
@@ -30,25 +129,18 @@ Use it for questions like:
 
 Do not use it for trivial edits, formatting, or obvious one-step fixes.
 
-## How it works
+## Commands
 
 ```text
-/fusion Should this extension use node:test or Vitest?
-
-1. Panelists inspect the problem independently.
-2. The judge compares their answers.
-3. Pi shows one final Markdown report.
+/fusion
+/fusion <prompt>
+/fusion --profile <name> <prompt>
+/fusion -p <name> <prompt>
+/fusion status
+/fusion stop
+/fusion init
 ```
 
-Default roles:
-
-- **Architect** — tradeoffs and failure modes
-- **Implementer** — contracts, edge cases, practical fit
-- **Tester** — regressions and verification
-- **Judge** — synthesis and recommendation
-
-Bundled agents are read-only by default. They can inspect files, but they do not edit code, commit changes, or run nested subagents.
-
 ## Quick start
 
 Requirements:
@@ -68,16 +160,7 @@ Then reload Pi:
 /reload
 ```
 
-## Commands
-
-```text
-/fusion
-/fusion <prompt>
-/fusion --profile <name> <prompt>
-/fusion status
-/fusion stop
-/fusion init
-```
+For commands, config, and troubleshooting details, see [`docs/user-guide.md`](./docs/user-guide.md).
 
 ## Notes
 
@@ -85,6 +168,7 @@ Then reload Pi:
 - Config is optional. Defaults work. Use `/fusion init` when you want project config.
 - Project config lives at `.pi/fusion.json`. Global config lives at `~/.pi/agent/fusion.json`.
 - Output appears as a Pi custom message. Active progress also uses the `fusion` status key.
+- Active runs are reconciled from `pi-subagents` lifecycle artifacts, not only completion events.
 - `pi-fusion` does not own the footer.
 - Prompts and inspected snippets may be sent to your configured model providers through `pi-subagents`.
 

package/docs/user-guide.md

@@ -1,15 +1,19 @@
 # pi-fusion user guide
 
-Use this when the README is not enough.
+README covers the why. This guide covers commands, config, and troubleshooting.
 
 ## Mental model
 
-`pi-fusion` turns one hard question into a small review panel:
+`pi-fusion` turns one hard question into a small parallel panel:
 
 ```text
-prompt → panelists in parallel → judge synthesis → final report
+prompt → parallel panel → judge synthesis → final report
 ```
 
+Normal execution is a single `pi-subagents` async chain. If that chain completes without a judge result but at least two panelists still produced usable answers, `pi-fusion` runs one fallback judge pass instead of losing the review.
+
+Panel diversity can come from different model choices, different perspective prompts, or both. In practice, mixing models is usually the main lever.
+
 The base Pi session stays in control. Fusion is a tool for decisions, not a replacement for normal coding.
 
 ## Commands
@@ -30,7 +34,7 @@ Notes:
 
 - Bare `/fusion` shows a short help message.
 - `/fusion status` shows the active run, last run, warnings, and subagent run IDs.
-- `/fusion stop` stops the active panel or judge run.
+- `/fusion stop` stops the active chain or fallback judge run.
 - `/fusion init` writes `.pi/fusion.json` for the current trusted project.
 - Exact one-word prompts `init`, `status`, and `stop` are reserved as `/fusion` subcommands.
 
@@ -106,9 +110,9 @@ Panel member:
 - `id`: stable machine name
 - `label`: human-readable report label
 - `agent`: subagent name
-- `model`: optional model override
+- `model`: optional model override; often the main source of panel diversity
 - `thinking`: optional `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`
-- `role`: short perspective instruction
+- `role`: optional perspective hint layered on top of the model
 
 Judge:
 
@@ -250,3 +254,9 @@ Need the run IDs:
 ```text
 /fusion status
 ```
+
+Notes:
+
+- `Chain run` is the normal end-to-end Fusion run.
+- `Fallback judge run` appears only when Fusion had enough panel output to recover a missing judge result.
+- If `pi-subagents` completion notifications are delayed or missed, Fusion still reconciles from lifecycle artifacts written under the subagent async run directory.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.1.2",
-  "description": "Subagent-native multi-model deliberation for Pi",
+  "version": "0.2.1",
+  "description": "Stronger answers for hard Pi questions via a parallel model panel + judge, built on pi-subagents",
   "type": "module",
   "main": "./src/index.ts",
   "license": "MIT",
@@ -22,11 +22,7 @@
   "files": [
     "agents/*.md",
     "src/*.ts",
-    "README.md",
-    "LICENSE",
-    "AGENTS.md",
-    "docs/user-guide.md",
-    "tsconfig.json"
+    "docs/user-guide.md"
   ],
   "scripts": {
     "check": "tsc --noEmit",
@@ -47,7 +43,8 @@
       "agents": [
         "./agents"
       ]
-    }
+    },
+    "image": "https://raw.githubusercontent.com/alexei-led/pi-fusion/master/docs/assets/fusion-icon.png"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/index.ts

@@ -29,6 +29,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
 
   pi.on("session_shutdown", () => {
     orchestrator.clearUi();
+    orchestrator.dispose();
     if (typeof unsubscribeComplete === "function") unsubscribeComplete();
   });
 }