@alexeiled/pi-fusion 0.5.2 → 0.6.1

package/skills/fusion-review/SKILL.md

@@ -1,34 +1,85 @@
 ---
 name: fusion-review
 description: >
-  Trigger a pi-fusion multi-model panel review implicitly. Use when the user asks to
-  "invoke fusion", "run a fusion panel", "discuss this through fusion", "get multi-model
-  opinions", "panel review", or any phrasing that implies running a parallel model review.
-  Call the start_fusion_review tool with the user's topic or prompt.
+  Run a pi-fusion review: several models answer in parallel, then one synthesis
+  step returns a single report. Use when the user says "invoke fusion", "run a
+  fusion panel", "discuss this through fusion", "get multi-model opinions",
+  "panel review", "compare <model> and <model> on this", or asks to cover
+  something from several angles ("what did we miss", "audit this release").
+  Call the start_fusion_review tool with the topic. NOT for routine edits,
+  formatting, or one-step fixes. NOT for arguing one claim from both sides (use
+  dialectic) and NOT for open-ended idea generation (use brainstorming) —
+  Fusion panelists work independently and never talk to each other.
 ---
 
 # Fusion Review
 
-Use the `start_fusion_review` tool to launch a fusion panel without the user needing to type `/fusion`.
+Call `start_fusion_review` so the user does not have to type `/fusion`.
 
 ## When to use
 
-Use Fusion for hard decisions, design tradeoffs, risk review, tricky debugging, or questions where independent model perspectives are useful.
+Use Fusion when independent perspectives are worth the extra latency:
 
-Do not use Fusion for routine edits, formatting, obvious one-step fixes, or simple questions. Keep those on the normal Pi path.
+- a hard decision or a design tradeoff
+- risk or release review
+- tricky debugging
+- a research-heavy question
+- a breadth sweep, such as an audit or "what did we miss"
 
-- "invoke fusion panel to discuss this"
-- "run fusion on this"
-- "get a panel review of …"
-- "use multi-model review for …"
-- "discuss this through fusion"
-- Any prompt that implies parallel model review or multi-perspective analysis
+Do not use Fusion for routine edits, formatting, obvious one-step fixes, or
+simple questions. Keep those on the normal Pi path.
 
-## How to use
+## Not this skill
 
-Call `start_fusion_review` with:
+- The user wants one claim argued for and against. That is `dialectic`.
+- The user wants options generated, or a draft plan stress-tested. That is
+  `brainstorming-ideas`.
 
-- `prompt` — the topic, question, or code excerpt to review (required)
-- `profile` — a named fusion profile (optional; omit to use the default)
+Fusion differs from both. Panelists run in isolation and never see the answers of
+the others. The value is uncorrelated errors, not debate.
 
-The tool queues a `/fusion` command as a follow-up, so the panel starts immediately after the current turn.
+## How to call it
+
+| Parameter | Required | Use                                                           |
+| --------- | -------- | ------------------------------------------------------------- |
+| `prompt`  | yes      | The topic, question, or code excerpt                          |
+| `profile` | no       | A named profile that the user already has. Omit it otherwise. |
+| `panel`   | no       | Models for this run only. Use it when the user names models.  |
+
+Each `panel` entry is `<model>` or `<agent>:<model>`. For example: `opus`, or
+`pi-fusion.fusion-panelist-web:gpt-5.5`.
+
+Pass `panel` only when the user names the models. If the user asks for a kind of
+review but names no model, omit `panel` and let the profile decide.
+
+Do not pass a `profile` name that you have not seen in the config of the user.
+An unknown name fails the run.
+
+## Two shapes of report
+
+The shape follows the profile. You do not select it, and there is no flag.
+
+**Select** is the default. Every panelist answers the whole question. The judge
+compares the answers and reports consensus, disagreements, contested claims, and
+blind spots. This fits a decision question, where the failure mode is the bad
+reasoning path of one model.
+
+**Merge** happens when the profile gives its members a `question` field. Each
+panelist then answers a different facet. A composer unions the answers into a
+coverage map, a combined answer, and a list of gaps. This fits a breadth
+question, where the failure mode is incomplete coverage.
+
+If the user asks for a multi-angle audit and has no faceted profile, run the
+default panel. Then tell them that a profile with `question` fields covers this
+better.
+
+## After the call
+
+The tool returns at once. The panel and the synthesis step run in the background,
+and Fusion posts the report when they finish.
+
+- Do not call the tool again while a run is active. It returns a conflict with
+  the id of the active run.
+- Do not summarize or predict the report. Wait for it.
+- To show progress or stop a run, tell the user to type `/fusion status` or
+  `/fusion stop`. No tool does this.

package/src/commands.ts

@@ -16,6 +16,7 @@ const FUSION_HELP = [
   "Fusion commands",
   "/fusion <prompt>",
   "/fusion --profile <name> <prompt>",
+  "/fusion --panel <models> <prompt>",
   "/fusion status",
   "/fusion stop",
   "/fusion init",

package/src/config.ts

@@ -4,6 +4,8 @@ import { dirname, join } from "node:path";
 import { applyClaudeAliasShorthand } from "./claude-aliases.js";
 import { FusionConfigError } from "./errors.js";
 import {
+  JUDGE_AGENT,
+  PANEL_AGENT,
   THINKING_LEVELS,
   type FusionConfig,
   type FusionContextMode,
@@ -11,6 +13,7 @@ import {
   type JudgeConfig,
   type PanelMemberConfig,
   type ThinkingLevel,
+  type ToolBudget,
 } from "./types.js";
 import {
   isNodeErrorCode,
@@ -21,8 +24,43 @@ import {
 
 export const FUSION_CONFIG_FILE = "fusion.json";
 export const DEFAULT_PROFILE_NAME = "quality";
-export const PANEL_AGENT = "pi-fusion.fusion-panelist";
-export const JUDGE_AGENT = "pi-fusion.fusion-judge";
+export {
+  COMPOSER_AGENT,
+  JUDGE_AGENT,
+  PANEL_AGENT,
+  PANEL_AGENT_FULL,
+  PANEL_AGENT_WEB,
+} from "./types.js";
+
+/**
+ * Tool names Fusion's bundled agents may declare: Pi core child tools plus the
+ * tools contributed by `pi-web-providers`. A name outside this set resolves to
+ * nothing at runtime, so a typo is only discovered after a panel run is spent.
+ * Single source of truth for `test/unit/agents.test.ts`.
+ */
+export const KNOWN_TOOL_NAMES: readonly string[] = [
+  "read",
+  "bash",
+  "edit",
+  "write",
+  "grep",
+  "find",
+  "ls",
+  "web_search",
+  "web_contents",
+  "web_answer",
+  "web_research",
+];
+
+/**
+ * Agent references are dot-separated (`<package>.<name>`, or a bare local name).
+ * This deliberately does not enforce the lowercase `IDENTIFIER_PATTERN` that
+ * pi-subagents applies to package names: that pattern does not cover the
+ * frontmatter `name`, and rejecting a config that would actually run is worse
+ * than accepting a malformed one. It catches the real typo classes only —
+ * embedded whitespace, empty segments, leading or trailing dots.
+ */
+const AGENT_REFERENCE_PATTERN = /^[^\s.]+(?:\.[^\s.]+)*$/;
 
 export interface FusionConfigLoadContext {
   cwd: string;
@@ -138,6 +176,89 @@ export function resolveProfile(
   return { name, profile };
 }
 
+/**
+ * Splits an inline `--panel` entry into agent and model.
+ *
+ * Two shapes collide on `:` — an agent-qualified entry
+ * (`pi-fusion.fusion-panelist-web:gpt-5.5`) and a model with a thinking suffix
+ * (`gpt-4.1:high`). A dot in the prefix is not enough to tell them apart:
+ * dotted model versions like `gpt-4.1`, `claude-3.5-haiku`, and
+ * `gemini-2.5-pro` are common. The suffix decides — if it is a thinking level,
+ * the whole entry is a model.
+ */
+export function splitInlinePanelEntry(entry: string): {
+  agent: string;
+  model: string;
+} {
+  const trimmed = entry.trim();
+  const separator = trimmed.indexOf(":");
+  if (separator > 0) {
+    const prefix = trimmed.slice(0, separator);
+    const rest = trimmed.slice(separator + 1).trim();
+    if (
+      prefix.includes(".") &&
+      !prefix.includes("/") &&
+      rest &&
+      !isThinkingLevel(rest)
+    ) {
+      return { agent: prefix, model: rest };
+    }
+  }
+  return { agent: PANEL_AGENT, model: trimmed };
+}
+
+/**
+ * Builds an ephemeral profile from `--panel`. The resolved profile still
+ * supplies the judge and every other setting; only the panel is replaced.
+ */
+export function buildInlinePanelProfile(
+  base: FusionProfile,
+  entries: readonly string[],
+): FusionProfile {
+  const usedIds = new Set<string>();
+  const panel = entries.map((entry, index) => {
+    const { agent, model } = splitInlinePanelEntry(entry);
+    if (!model) {
+      throw new FusionConfigError(
+        `Inline panel entry "${entry}" has no model.`,
+      );
+    }
+    if (!isAgentReference(agent)) {
+      throw new FusionConfigError(
+        `Inline panel entry "${entry}" has a malformed agent reference.`,
+      );
+    }
+    return {
+      id: uniqueInlineId(model, index, usedIds),
+      label: model,
+      agent,
+      model,
+    };
+  });
+  // Inline members have no `question`, so they all answer the whole task.
+  // Carrying `synthesis: "merge"` over from the base profile would tell the
+  // composer to merge facets that do not exist.
+  const { synthesis: _dropped, ...rest } = base;
+  return { ...rest, panel };
+}
+
+function uniqueInlineId(
+  model: string,
+  index: number,
+  used: Set<string>,
+): string {
+  const base =
+    model
+      .replace(/[^A-Za-z0-9]+/g, "_")
+      .replace(/^_+|_+$/g, "")
+      .toLowerCase() || `panel_${index + 1}`;
+  let candidate = base;
+  let suffix = 2;
+  while (used.has(candidate)) candidate = `${base}_${suffix++}`;
+  used.add(candidate);
+  return candidate;
+}
+
 export async function writeProjectFusionConfigTemplate(
   cwd: string,
   deps: FileWriteDeps = {},
@@ -209,24 +330,65 @@ function isFusionProfile(value: unknown): value is FusionProfile {
   ) {
     return false;
   }
+  if (
+    value.blindPanelLabels !== undefined &&
+    typeof value.blindPanelLabels !== "boolean"
+  ) {
+    return false;
+  }
+  if (
+    value.judgeToolBudget !== undefined &&
+    !isToolBudget(value.judgeToolBudget)
+  ) {
+    return false;
+  }
+  if (
+    value.synthesis !== undefined &&
+    value.synthesis !== "select" &&
+    value.synthesis !== "merge"
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function isToolBudget(value: unknown): value is ToolBudget {
+  if (!isRecord(value)) return false;
+  if (value.soft !== undefined && !isPositiveInteger(value.soft)) return false;
+  if (value.hard !== undefined && !isPositiveInteger(value.hard)) return false;
+  if (value.soft === undefined && value.hard === undefined) return false;
+  if (
+    isPositiveInteger(value.soft) &&
+    isPositiveInteger(value.hard) &&
+    value.soft > value.hard
+  ) {
+    return false;
+  }
   return true;
 }
 
+export function isAgentReference(value: unknown): value is string {
+  return isNonEmptyString(value) && AGENT_REFERENCE_PATTERN.test(value.trim());
+}
+
 function isPanelMemberConfig(value: unknown): value is PanelMemberConfig {
   if (!isRecord(value)) return false;
   if (!isNonEmptyString(value.id)) return false;
-  if (!isNonEmptyString(value.label)) return false;
-  if (!isNonEmptyString(value.agent)) return false;
+  if (value.label !== undefined && !isNonEmptyString(value.label)) return false;
+  if (!isAgentReference(value.agent)) return false;
   if (value.model !== undefined && !isNonEmptyString(value.model)) return false;
   if (value.thinking !== undefined && !isThinkingLevel(value.thinking))
     return false;
   if (value.role !== undefined && typeof value.role !== "string") return false;
+  if (value.question !== undefined && !isNonEmptyString(value.question)) {
+    return false;
+  }
   return true;
 }
 
 function isJudgeConfig(value: unknown): value is JudgeConfig {
   if (!isRecord(value)) return false;
-  if (!isNonEmptyString(value.agent)) return false;
+  if (!isAgentReference(value.agent)) return false;
   if (value.model !== undefined && !isNonEmptyString(value.model)) return false;
   if (value.thinking !== undefined && !isThinkingLevel(value.thinking))
     return false;

package/src/fusion-args.ts

@@ -2,7 +2,7 @@ import { FusionArgsError } from "./errors.js";
 import type { ParsedFusionArgs } from "./types.js";
 
 const FUSION_USAGE =
-  "Usage: /fusion <prompt> | /fusion --profile <name> <prompt> | /fusion status | /fusion stop | /fusion init.";
+  "Usage: /fusion <prompt> | /fusion --profile <name> <prompt> | /fusion --panel <models> <prompt> | /fusion status | /fusion stop | /fusion init.";
 
 export type FusionInlineCommand = "init" | "status" | "stop";
 
@@ -27,12 +27,31 @@ export function parseFusionArgs(
   if (tokens[0] === "/fusion" || tokens[0] === "fusion") tokens.shift();
 
   let profile: string | undefined;
+  let panel: string[] | undefined;
   const promptTokens: string[] = [];
 
   for (let index = 0; index < tokens.length; index++) {
     const token = tokens[index];
     if (!token) continue;
 
+    if (promptTokens.length === 0 && token === "--panel") {
+      const value = tokens[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new FusionArgsError(`Missing value for --panel. ${FUSION_USAGE}`);
+      }
+      if (panel) throw new FusionArgsError("Panel can only be provided once.");
+      panel = parsePanelEntries(value);
+      index++;
+      continue;
+    }
+
+    if (promptTokens.length === 0 && token.startsWith("--panel=")) {
+      const value = token.slice("--panel=".length);
+      if (panel) throw new FusionArgsError("Panel can only be provided once.");
+      panel = parsePanelEntries(value);
+      continue;
+    }
+
     if (
       promptTokens.length === 0 &&
       (token === "--profile" || token === "-p")
@@ -72,7 +91,22 @@ export function parseFusionArgs(
 
   const prompt = promptTokens.join(" ").trim();
   if (!prompt) throw new FusionArgsError(FUSION_USAGE);
-  return profile ? { prompt, profile } : { prompt };
+  return {
+    prompt,
+    ...(profile ? { profile } : {}),
+    ...(panel ? { panel } : {}),
+  };
+}
+
+function parsePanelEntries(value: string): string[] {
+  const entries = value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (entries.length === 0) {
+    throw new FusionArgsError(`Missing value for --panel. ${FUSION_USAGE}`);
+  }
+  return entries;
 }
 
 export function tokenizeCommandArgs(input: string): string[] {

package/src/index.ts

@@ -18,22 +18,30 @@ function registerFusionTool(
     name: "start_fusion_review",
     label: "Fusion Review",
     description:
-      "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.",
+      "Start a pi-fusion review. Several models answer in parallel, then one synthesis step returns a single report. Use it for a hard decision, a design tradeoff, a risk or release review, tricky debugging, a research-heavy question, or a breadth sweep such as an audit or 'what did we miss'. Do not use it 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 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.",
+      "Use start_fusion_review only for hard decisions, design tradeoffs, risk review, tricky debugging, research-heavy questions, or breadth sweeps such as audits. Do not use it for routine edits, formatting, or obvious one-step fixes.",
+      "Pass panel only when the user names the models to compare. Otherwise omit it and let the profile decide.",
     ],
     parameters: Type.Object({
       prompt: Type.String({ description: "What to review or discuss" }),
       profile: Type.Optional(
         Type.String({ description: "Fusion profile name (optional)" }),
       ),
+      panel: Type.Optional(
+        Type.Array(Type.String(), {
+          description:
+            "Models to use for this run, overriding the profile panel. Each entry is <model> or <agent>:<model>. Use only when the user names specific models.",
+        }),
+      ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const result = await orchestrator.startRun(
         {
           prompt: params.prompt,
           ...(params.profile ? { profile: params.profile } : {}),
+          ...(params.panel?.length ? { panel: params.panel } : {}),
         },
         ctx,
       );
@@ -48,6 +56,7 @@ function registerFusionTool(
         details: {
           prompt: params.prompt,
           profile: params.profile,
+          panel: params.panel,
           status: result.status,
         },
       };