@alexeiled/pi-fusion 0.3.0 → 0.5.0

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
 
@@ -170,7 +171,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.0",
+  "version": "0.5.0",
   "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;
 }
 

package/src/index.ts

@@ -8,15 +8,18 @@ import {
 import { FusionRunStore } from "./run-store.js";
 import { SubagentsRpcClient } from "./subagents-rpc.js";
 
-function registerFusionTool(pi: ExtensionAPI): void {
+function registerFusionTool(
+  pi: ExtensionAPI,
+  orchestrator: FusionOrchestrator,
+): void {
   pi.registerTool({
     name: "start_fusion_review",
     label: "Fusion Review",
     description:
-      "Start a pi-fusion multi-model panel review. Use when the user asks to invoke fusion, run a panel review, get multi-model opinions, or discuss something through the fusion panel.",
+      "Start a pi-fusion multi-model panel review for a hard decision, design tradeoff, risk review, tricky debugging question, or research-heavy topic. Do not use for routine edits, formatting, or obvious one-step fixes.",
     promptSnippet: "Start a fusion panel review for a topic or code",
     promptGuidelines: [
-      "Use start_fusion_review when the user says 'invoke fusion', 'run fusion', 'fusion panel', 'multi-model review', 'panel review', or similar.",
+      "Use start_fusion_review only for hard decisions, design tradeoffs, risk review, tricky debugging, or research-heavy questions. Do not use it for routine edits, formatting, or obvious one-step fixes.",
     ],
     parameters: Type.Object({
       prompt: Type.String({ description: "What to review or discuss" }),
@@ -24,15 +27,28 @@ function registerFusionTool(pi: ExtensionAPI): void {
         Type.String({ description: "Fusion profile name (optional)" }),
       ),
     }),
-    execute(_toolCallId, params) {
-      const cmd = params.profile
-        ? `/fusion --profile ${params.profile} ${params.prompt}`
-        : `/fusion ${params.prompt}`;
-      pi.sendUserMessage(cmd, { deliverAs: "followUp" });
-      return Promise.resolve({
-        content: [{ type: "text", text: "Starting fusion panel review…" }],
-        details: { prompt: params.prompt, profile: params.profile },
-      });
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const result = await orchestrator.startRun(
+        {
+          prompt: params.prompt,
+          ...(params.profile ? { profile: params.profile } : {}),
+        },
+        ctx,
+      );
+      const text =
+        result.status === "started"
+          ? "Fusion panel review started. The report will be posted when the panel and judge finish."
+          : result.status === "conflict"
+            ? `A fusion run is already active (${result.activeRunId}). Do not start another; wait for its report.`
+            : `Fusion review failed to start: ${result.status === "failed" ? result.error : result.status}`;
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          prompt: params.prompt,
+          profile: params.profile,
+          status: result.status,
+        },
+      };
     },
   });
 }
@@ -45,7 +61,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   });
 
   registerFusionCommands(pi, orchestrator);
-  registerFusionTool(pi);
+  registerFusionTool(pi, orchestrator);
 
   const unsubscribeComplete = pi.events.on(
     SUBAGENT_ASYNC_COMPLETE_EVENT,