@alexeiled/pi-fusion 0.3.1 → 0.5.1

package/README.md

@@ -95,7 +95,8 @@ A panel helps because:
 - 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.
+tricky debugging, and research-heavy questions. It is not intended for routine
+edits, formatting, or obvious one-step fixes.
 
 ## What the judge actually does
 
@@ -141,6 +142,34 @@ Do not use it for trivial edits, formatting, or obvious one-step fixes.
 /fusion init
 ```
 
+## Plan execution RPC
+
+Other Pi extensions can control Fusion through the versioned event-bus contract
+`fusion:rpc:v1`:
+
+- emit requests on `fusion:rpc:v1:request`
+- listen for the response on `fusion:rpc:v1:reply:<requestId>` before emitting
+- send `{ "version": 1, "requestId": "...", "method": "...", "params": {} }`
+- receive `{ "version": 1, "requestId": "...", "method": "...", "success": true, "data": {} }` or a failure with a typed `error`
+
+Methods:
+
+- `ping` — return the RPC version and supported methods
+- `start` — requires `prompt` and a non-empty `operationId`; accepts optional `profile`. Reusing an operation ID returns the original run instead of starting another, including after Fusion restores the Pi session history.
+- `status` — return structured run state by `operationId`, `runId`, or the current/last run
+- `result` — return a terminal run and report; active runs return `not_ready`
+- `cancel` — cancel the selected active run, or report that the selected terminal run was not cancelled
+- `adopt` — confirm and return a run from restored session history by `runId`
+
+`start` returns `{ operationId, replayed, run }`. `status` and `result`
+return `{ run }`. `cancel` returns `{ cancelled, run? }`. `adopt` returns
+`{ adopted: true, run }`. Run state contains `runId`, optional `operationId`,
+`phase`, `terminal`, and optional `report` or `error`.
+
+Failure codes are `invalid_request`, `unsupported_method`, `busy`, `not_found`,
+`not_ready`, `unavailable`, `start_failed`, `cancel_failed`, and `internal`.
+`busy`, `not_ready`, and lookup failures include structured details when available.
+
 ## Quick start
 
 Requirements:
@@ -170,7 +199,10 @@ For commands, config, and troubleshooting details, see [`docs/user-guide.md`](./
 - 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`.
+- Prompts and inspected snippets may be sent to every configured panel provider and to the judge through `pi-subagents`.
+- Reports include available per-panel and judge time, aggregate model time, usage, estimated cost, and model failure details. Missing provider usage is shown as unknown; `$0.0000` remains a known zero-cost value.
+- `Model` is lifecycle metadata. `Configured model` is the profile request; both appear when execution differs from the request.
+- `stopWhenPanelAgrees` is an opt-in profile setting. It requires matching high-confidence decision records with no request for more evidence, stops only unfinished panelists, and still runs the judge.
 
 ## Read more
 

package/agents/fusion-panelist.md

@@ -15,7 +15,13 @@ 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:
+Return concise Markdown with these sections.
+
+When the task includes a decision-record contract:
+
+- Append exactly one `<fusion-panel-decision>{...}</fusion-panel-decision>` JSON record as the final line.
+- Do not write any text after it.
+- Fusion uses the record only for early-stop orchestration; users receive the preceding Markdown answer.
 
 ## Summary
 

package/docs/user-guide.md

@@ -10,7 +10,7 @@ README covers the why. This guide covers commands, config, and troubleshooting.
 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.
+Fusion keeps the command simple: one prompt starts the panel, then the judge turns the collected evidence into a human-readable Markdown report. Older runs created as a single `pi-subagents` chain remain supported when restored.
 
 Panel diversity can come from different model choices, different perspective prompts, or both. In practice, mixing models is usually the main lever.
 
@@ -34,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 chain or fallback judge run.
+- `/fusion stop` stops the active panel, legacy chain, 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.
 
@@ -84,7 +84,8 @@ Run this inside a trusted project:
       },
       "concurrency": 3,
       "timeoutMs": 300000,
-      "context": "fresh"
+      "context": "fresh",
+      "stopWhenPanelAgrees": false
     }
   }
 }
@@ -104,6 +105,7 @@ Profile:
 - `concurrency`: max parallel panelists
 - `timeoutMs`: async subagent timeout in milliseconds
 - `context`: `fresh` or `fork`
+- `stopWhenPanelAgrees`: optional boolean, default `false`. When enabled, Fusion may stop unfinished panelists only when at least two completed panelists have the same normalized recommendation, every successful panelist reports `high` confidence, none requests more evidence, and work remains. The judge still runs over the collected answers. The policy is intentionally fixed; there are no agreement threshold knobs.
 
 Panel member:
 
@@ -191,14 +193,7 @@ Deliberate review:
 
 ## Output
 
-Panelists return:
-
-- summary
-- recommendation
-- evidence
-- risks
-- confidence
-- open questions
+When agreement stopping is enabled, panelists append a final tagged JSON decision record containing a short recommendation, confidence, and whether more evidence is needed. Fusion uses it only to decide whether an unfinished panel may stop early; malformed, missing, or non-final records disable early stopping. Users see the preceding human-readable Markdown answer, not the record.
 
 The judge returns:
 
@@ -212,23 +207,64 @@ The judge returns:
 - risks
 - next step
 
+When lifecycle data is available, the final report also includes per-panel and judge time, aggregate model time, token usage, estimated cost, and concise model/provider failure summaries. Aggregate model time sums agent durations and is not wall-clock latency when panelists overlap. Missing usage is shown as unknown; local zero-cost usage remains zero. `Model` comes from lifecycle metadata; `Configured model` is the profile request. Both appear when a provider reports a different executed model.
+
 ## 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
+## Data sharing and provider use
+
+Fusion uses model providers the same way normal Pi work does. The difference is fan-out:
+
+- normal work usually sends a prompt and tool results to one selected model;
+- Fusion sends the prompt to every configured panel model;
+- local file snippets read by a panelist go to that panelist's model;
+- the judge receives the original prompt plus successful panel answers and failure summaries.
+
+This is not an extra privacy guarantee. A mixed-provider panel can send copies of the work to several providers. An all-local panel can keep those model calls local, depending on your Pi model configuration. Bundled Fusion agents are read-only, but providers still receive the context needed to answer.
 
-Fusion sends work to `pi-subagents`. Those subagents use your configured Pi model providers.
+Fusion does not currently inspect or rewrite the final provider payload. Configure provider privacy and local-model routing in Pi.
 
-Data that may leave your machine:
+## Small and economical profiles
 
-- the prompt you pass to `/fusion`
-- relevant local file snippets read by panelists or the judge
-- panel outputs sent to the judge
+These are configuration examples, not built-in provider presets. Omit `model` to inherit the model selected in Pi, or set any model IDs supported by your Pi `models.json` configuration.
+
+Small local-style panel:
+
+```json
+{
+  "defaultProfile": "small",
+  "profiles": {
+    "small": {
+      "panel": [
+        {
+          "id": "reviewer",
+          "label": "Reviewer",
+          "agent": "pi-fusion.fusion-panelist",
+          "thinking": "low",
+          "role": "practical risks and next step"
+        },
+        {
+          "id": "tester",
+          "label": "Tester",
+          "agent": "pi-fusion.fusion-panelist",
+          "thinking": "low",
+          "role": "edge cases and verification"
+        }
+      ],
+      "judge": { "agent": "pi-fusion.fusion-judge", "thinking": "low" },
+      "concurrency": 2,
+      "timeoutMs": 120000,
+      "context": "fresh"
+    }
+  }
+}
+```
 
-Default bundled agents are read-only, but model providers still receive the context needed to answer.
+For an economical mixed panel, give each member a fast or inexpensive frontier, Chinese-lab, or local Ollama/LM Studio/vLLM model ID. Keep the profile composition small instead of adding provider-specific code to Fusion.
 
 ## Troubleshooting
 
@@ -258,6 +294,6 @@ Need the run IDs:
 
 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.
+- `Panel run` is the normal panel phase for new Fusion runs.
+- `Judge run` is the normal synthesis phase for new runs. `Fallback judge run` appears only while restoring a legacy chain that completed without its 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,6 +1,6 @@
 {
   "name": "@alexeiled/pi-fusion",
-  "version": "0.3.1",
+  "version": "0.5.1",
   "description": "Stronger answers for hard Pi questions via a parallel model panel + judge, built on pi-subagents",
   "type": "module",
   "main": "./src/index.ts",

package/skills/fusion-review/SKILL.md

@@ -13,6 +13,10 @@ Use the `start_fusion_review` tool to launch a fusion panel without the user nee
 
 ## When to use
 
+Use Fusion for hard decisions, design tradeoffs, risk review, tricky debugging, or questions where independent model perspectives are useful.
+
+Do not use Fusion for routine edits, formatting, obvious one-step fixes, or simple questions. Keep those on the normal Pi path.
+
 - "invoke fusion panel to discuss this"
 - "run fusion on this"
 - "get a panel review of …"

package/src/config.ts

@@ -79,6 +79,7 @@ export function createDefaultFusionConfig(): FusionConfig {
         concurrency: 3,
         timeoutMs: 300_000,
         context: "fresh",
+        stopWhenPanelAgrees: false,
       },
     },
   };
@@ -202,6 +203,12 @@ function isFusionProfile(value: unknown): value is FusionProfile {
     return false;
   if (value.context !== undefined && !isFusionContextMode(value.context))
     return false;
+  if (
+    value.stopWhenPanelAgrees !== undefined &&
+    typeof value.stopWhenPanelAgrees !== "boolean"
+  ) {
+    return false;
+  }
   return true;
 }