@alexeiled/pi-fusion 0.1.0

package/AGENTS.md

@@ -0,0 +1,7 @@
+# Contributor notes
+
+- Keep the extension small, typed, and testable.
+- Do not own or replace the Pi footer. Publish only the `fusion` status key.
+- Use `pi-subagents` RPC for panel and judge execution. Do not import its internals.
+- Keep bundled panel agents read-only by default.
+- Do not add runtime dependencies unless the task needs them.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Ledenev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# 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)
+[![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.
+
+`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.
+
+You get:
+
+- consensus
+- disagreements
+- blind spots
+- risks
+- recommended 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.
+
+## Good fit
+
+Use it for questions like:
+
+- Which design should we choose?
+- What will break if I change this?
+- Is this PR or release flow safe?
+- What did I miss?
+- What is the right test strategy here?
+
+Do not use it for trivial edits, formatting, or obvious one-step fixes.
+
+## How it works
+
+```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.
+```
+
+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:
+
+- Pi
+- Node.js 22.19+
+- `pi-subagents`
+
+```bash
+pi install npm:pi-subagents
+pi install npm:@alexeiled/pi-fusion
+```
+
+Then reload Pi:
+
+```text
+/reload
+```
+
+## Commands
+
+```text
+/fusion
+/fusion <prompt>
+/fusion --profile <name> <prompt>
+/fusion status
+/fusion stop
+/fusion init
+```
+
+## Notes
+
+- Bare `/fusion` shows a short command summary.
+- 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.
+- `pi-fusion` does not own the footer.
+- Prompts and inspected snippets may be sent to your configured model providers through `pi-subagents`.
+
+## Read more
+
+- [`docs/user-guide.md`](./docs/user-guide.md) — commands, config, profiles, privacy, troubleshooting
+- [`DEVELOPMENT.md`](./DEVELOPMENT.md) — contributor workflow

package/agents/fusion-judge.md

@@ -0,0 +1,38 @@
+---
+name: fusion-judge
+package: pi-fusion
+description: Judge and synthesizer for pi-fusion panel outputs.
+tools: read, grep, find, ls
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fresh
+completionGuard: false
+---
+
+You are the pi-fusion judge.
+
+Compare panel outputs. Do not invent consensus. Preserve disagreements. Prefer the smallest realistic recommendation.
+Do not edit files. Do not ask other agents. Do not run subagents.
+
+Return final Markdown with these sections:
+
+# Fusion Report
+
+## Summary
+
+## Agent Status
+
+## Consensus
+
+## Disagreements
+
+## Unique Insights
+
+## Blind Spots
+
+## Recommendation
+
+## Risks
+
+## Next Step

package/agents/fusion-panelist.md

@@ -0,0 +1,30 @@
+---
+name: fusion-panelist
+package: pi-fusion
+description: Independent read-only panel member for pi-fusion deliberation.
+tools: read, grep, find, ls
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+defaultContext: fresh
+completionGuard: false
+---
+
+You are a pi-fusion panelist.
+
+Work independently. Inspect relevant local files when the task needs code evidence.
+Do not edit files. Do not ask other agents. Do not run subagents.
+
+Return concise Markdown with these sections:
+
+## Summary
+
+## Recommendation
+
+## Evidence
+
+## Risks
+
+## Confidence
+
+## Open Questions

package/docs/user-guide.md

@@ -0,0 +1,252 @@
+# pi-fusion user guide
+
+Use this when the README is not enough.
+
+## Mental model
+
+`pi-fusion` turns one hard question into a small review panel:
+
+```text
+prompt → panelists in parallel → judge synthesis → final report
+```
+
+The base Pi session stays in control. Fusion is a tool for decisions, not a replacement for normal coding.
+
+## Commands
+
+Preferred command shape:
+
+```text
+/fusion
+/fusion <prompt>
+/fusion --profile <name> <prompt>
+/fusion -p <name> <prompt>
+/fusion status
+/fusion stop
+/fusion init
+```
+
+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 init` writes `.pi/fusion.json` for the current trusted project.
+- Exact one-word prompts `init`, `status`, and `stop` are reserved as `/fusion` subcommands.
+
+## Configuration files
+
+Config lookup order:
+
+1. trusted project config: `.pi/fusion.json`
+2. global config: `~/.pi/agent/fusion.json`
+3. built-in defaults
+
+Run this inside a trusted project:
+
+```text
+/fusion init
+```
+
+## Minimal config
+
+```json
+{
+  "defaultProfile": "quality",
+  "profiles": {
+    "quality": {
+      "panel": [
+        {
+          "id": "architect",
+          "label": "Architect",
+          "agent": "pi-fusion.fusion-panelist",
+          "role": "architecture, tradeoffs, and failure modes"
+        },
+        {
+          "id": "implementer",
+          "label": "Implementer",
+          "agent": "pi-fusion.fusion-panelist",
+          "role": "implementation details, API contracts, and edge cases"
+        },
+        {
+          "id": "tester",
+          "label": "Tester",
+          "agent": "pi-fusion.fusion-panelist",
+          "role": "test strategy, regressions, and verification"
+        }
+      ],
+      "judge": {
+        "agent": "pi-fusion.fusion-judge"
+      },
+      "concurrency": 3,
+      "timeoutMs": 300000,
+      "context": "fresh"
+    }
+  }
+}
+```
+
+## Profile fields
+
+Top level:
+
+- `defaultProfile`: profile used when `/fusion` has no `--profile`
+- `profiles`: named profile map
+
+Profile:
+
+- `panel`: one or more panel members
+- `judge`: judge agent config
+- `concurrency`: max parallel panelists
+- `timeoutMs`: async subagent timeout in milliseconds
+- `context`: `fresh` or `fork`
+
+Panel member:
+
+- `id`: stable machine name
+- `label`: human-readable report label
+- `agent`: subagent name
+- `model`: optional model override
+- `thinking`: optional `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`
+- `role`: short perspective instruction
+
+Judge:
+
+- `agent`: judge subagent name
+- `model`: optional model override
+- `thinking`: optional thinking level
+
+## Example profiles
+
+Fast and cheap:
+
+```json
+{
+  "defaultProfile": "fast",
+  "profiles": {
+    "fast": {
+      "panel": [
+        {
+          "id": "reviewer",
+          "label": "Reviewer",
+          "agent": "pi-fusion.fusion-panelist",
+          "thinking": "low",
+          "role": "practical risks and next step"
+        }
+      ],
+      "judge": {
+        "agent": "pi-fusion.fusion-judge",
+        "thinking": "low"
+      },
+      "concurrency": 1,
+      "timeoutMs": 120000,
+      "context": "fresh"
+    }
+  }
+}
+```
+
+Deliberate review:
+
+```json
+{
+  "defaultProfile": "quality",
+  "profiles": {
+    "quality": {
+      "panel": [
+        {
+          "id": "architect",
+          "label": "Architect",
+          "agent": "pi-fusion.fusion-panelist",
+          "model": "anthropic/claude-sonnet-4",
+          "thinking": "high",
+          "role": "architecture and failure modes"
+        },
+        {
+          "id": "tester",
+          "label": "Tester",
+          "agent": "pi-fusion.fusion-panelist",
+          "model": "openai/gpt-5.5",
+          "thinking": "medium",
+          "role": "tests, regressions, and observability"
+        }
+      ],
+      "judge": {
+        "agent": "pi-fusion.fusion-judge",
+        "model": "anthropic/claude-sonnet-4",
+        "thinking": "high"
+      },
+      "concurrency": 2,
+      "timeoutMs": 300000,
+      "context": "fresh"
+    }
+  }
+}
+```
+
+## Output
+
+Panelists return:
+
+- summary
+- recommendation
+- evidence
+- risks
+- confidence
+- open questions
+
+The judge returns:
+
+- summary
+- agent status
+- consensus
+- disagreements
+- unique insights
+- blind spots
+- recommendation
+- risks
+- next step
+
+## Status and footer integration
+
+`pi-fusion` uses only the Pi status key `fusion` while a run is active.
+
+It does not own the footer. If you use a footer extension, configure it to read the `fusion` status key.
+
+## Privacy and provider use
+
+Fusion sends work to `pi-subagents`. Those subagents use your configured Pi model providers.
+
+Data that may leave your machine:
+
+- the prompt you pass to `/fusion`
+- relevant local file snippets read by panelists or the judge
+- panel outputs sent to the judge
+
+Default bundled agents are read-only, but model providers still receive the context needed to answer.
+
+## Troubleshooting
+
+`pi-subagents RPC is unavailable`
+
+- install `pi-subagents`
+- reload Pi
+- retry `/fusion status`
+
+`Unknown fusion profile`
+
+- check `defaultProfile`
+- check the requested `--profile` name
+- run `/fusion init` to regenerate a known-good template
+
+Run is stuck or no longer useful:
+
+```text
+/fusion stop
+```
+
+Need the run IDs:
+
+```text
+/fusion status
+```

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@alexeiled/pi-fusion",
+  "version": "0.1.0",
+  "description": "Subagent-native multi-model deliberation for Pi",
+  "type": "module",
+  "main": "./src/index.ts",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-subagents",
+    "fusion",
+    "multi-agent",
+    "multi-model"
+  ],
+  "files": [
+    "agents/*.md",
+    "src/*.ts",
+    "README.md",
+    "LICENSE",
+    "AGENTS.md",
+    "docs/user-guide.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "npm run test:unit",
+    "test:unit": "node --import jiti/register --test test/unit/*.test.ts",
+    "test:integration": "node --import jiti/register --test test/integration/*.test.ts",
+    "test:e2e": "node --import jiti/register --test test/e2e/*.test.ts",
+    "pack:dry": "npm pack --dry-run",
+    "publish:dry": "npm publish --dry-run",
+    "lint": "eslint . --cache --cache-strategy content",
+    "test:all": "npm run lint && npm run check && npm run test:unit && npm run test:integration && npm run test:e2e && npm run pack:dry"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "subagents": {
+      "agents": [
+        "./agents"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.6.0",
+    "globals": "^17.7.0",
+    "jiti": "^2.7.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1"
+  },
+  "packageManager": "npm@11.18.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexei-led/pi-fusion.git"
+  },
+  "homepage": "https://github.com/alexei-led/pi-fusion#readme",
+  "bugs": {
+    "url": "https://github.com/alexei-led/pi-fusion/issues"
+  }
+}