@alexeiled/pi-fusion 0.5.2 → 0.6.0

package/src/run-builder.ts

@@ -3,12 +3,18 @@ import {
   PANEL_DECISION_OPEN,
 } from "./run-observations.js";
 import {
+  COMPOSER_AGENT,
+  JUDGE_AGENT,
+  memberLabel,
+  panelItemLabel,
+  resolveSynthesisMode,
   THINKING_LEVELS,
   type FailedPanelSummary,
   type FusionProfile,
   type PanelMemberConfig,
   type PanelOutput,
   type ThinkingLevel,
+  type ToolBudget,
 } from "./types.js";
 
 export const FUSION_ACCEPTANCE_DISABLED = {
@@ -90,6 +96,8 @@ export interface JudgeSpawnParams {
   acceptance: FusionAcceptanceDisabled;
   model?: string;
   timeoutMs?: number;
+  /** Per-task cap on judge tool calls; see `FusionProfile.judgeToolBudget`. */
+  toolBudget?: ToolBudget;
 }
 
 export type { FailedPanelSummary, PanelOutput } from "./types.js";
@@ -99,6 +107,12 @@ export interface BuildJudgeSpawnParamsInput {
   prompt: string;
   panelOutputs: readonly PanelOutput[];
   failedPanelists: readonly FailedPanelSummary[];
+  /**
+   * Seeds the order panel answers are presented to the judge. Required rather
+   * than optional: a missing seed would silently restore the fixed index order
+   * and its position bias.
+   */
+  runId: string;
 }
 
 const PANEL_OUTPUT_CONTRACT = [
@@ -116,6 +130,7 @@ const JUDGE_OUTPUT_CONTRACT = [
   "## Agent Status",
   "## Consensus",
   "## Disagreements",
+  "## Contested Claims",
   "## Unique Insights",
   "## Blind Spots",
   "## Recommendation",
@@ -123,6 +138,36 @@ const JUDGE_OUTPUT_CONTRACT = [
   "## Next Step",
 ] as const;
 
+const COMPOSER_OUTPUT_CONTRACT = [
+  "# Fusion Report",
+  "## Summary",
+  "## Coverage Map",
+  "## Combined Answer",
+  "## Gaps",
+  "## Conflicts At Seams",
+  "## Agent Status",
+  "## Risks",
+  "## Next Step",
+] as const;
+
+const COMPOSER_INSTRUCTIONS = [
+  "You are the fusion composer.",
+  "Read-only synthesis only. Leave files, git state, and the workspace untouched. Do not ask other agents. Do not run subagents.",
+  "The panelists answered DIFFERENT facets of one task. Merge their answers; do not pick a winner.",
+  "- Do not rank panelists. They were not competing.",
+  "- Report a conflict only where facets genuinely overlap and disagree. Different subject matter is not disagreement.",
+  "- Name facets nobody covered, or covered only in passing.",
+  "- Where facets overlap and state conflicting facts about this codebase, check the claim with your read tools and cite file:line under Conflicts At Seams. Do not settle it by whose wording sounds more confident.",
+] as const;
+
+const CONTESTED_CLAIMS_INSTRUCTIONS = [
+  "Contested claims:",
+  "- Where panelists state conflicting facts about this codebase, do not pick the more confident wording.",
+  "- Check the claim yourself with your read tools and cite file:line.",
+  "- Report each contested claim as: the claim, what you found, and which panelist was right.",
+  "- If you could not verify a claim, say so explicitly rather than choosing.",
+] as const;
+
 export function appendThinkingSuffix(
   model: string | undefined,
   thinking: ThinkingLevel | undefined,
@@ -207,7 +252,7 @@ export function buildJudgeSpawnParams(
     input.profile.judge.thinking,
   );
   return {
-    agent: input.profile.judge.agent,
+    agent: resolveSynthesisAgent(input.profile),
     task: buildJudgeTask(input),
     async: true,
     clarify: false,
@@ -217,6 +262,9 @@ export function buildJudgeSpawnParams(
     skill: false,
     acceptance: FUSION_ACCEPTANCE_DISABLED,
     ...(model ? { model } : {}),
+    ...(input.profile.judgeToolBudget
+      ? { toolBudget: input.profile.judgeToolBudget }
+      : {}),
     ...(input.profile.timeoutMs !== undefined
       ? { timeoutMs: input.profile.timeoutMs }
       : {}),
@@ -250,7 +298,7 @@ function buildPanelChainTaskParams(
     agent: member.agent,
     task: buildPanelTask(member, "{task}", false),
     as: chainOutputName(member, index),
-    label: member.label,
+    label: memberLabel(member),
     phase: "Panel",
     output: true,
     outputMode: "inline",
@@ -268,11 +316,10 @@ function buildPanelTask(
 ): string {
   const role = member.role?.trim() || "independent analysis and critique";
   return [
-    `Panel member: ${member.label} (${member.id})`,
+    `Panel member: ${memberLabel(member)} (${member.id})`,
     `Role: ${role}`,
     "",
-    "Original task:",
-    prompt.trim(),
+    ...formatMemberTask(member, prompt),
     "",
     "Instructions:",
     "- Work independently from the other panelists.",
@@ -300,31 +347,120 @@ function buildPanelTask(
   ].join("\n");
 }
 
+/**
+ * Merge mode swaps the synthesis agent, not the run slot. It still spawns into
+ * `judgeRunId`/`judgeAsyncDir` under phase `judge`, so `fusion:rpc:v1` consumers
+ * see no new phase value.
+ *
+ * An explicitly configured judge agent still wins: a user who names their own
+ * synthesis agent means it.
+ */
+function resolveSynthesisAgent(profile: FusionProfile): string {
+  if (resolveSynthesisMode(profile) !== "merge") return profile.judge.agent;
+  return profile.judge.agent === JUDGE_AGENT
+    ? COMPOSER_AGENT
+    : profile.judge.agent;
+}
+
+const TASK_PLACEHOLDER = "{task}";
+
+/**
+ * A member with a `question` answers that facet instead of the whole prompt.
+ * If the template omits `{task}` the original prompt is still appended: dropping
+ * it would silently strip the context the panelist needs.
+ */
+function formatMemberTask(member: PanelMemberConfig, prompt: string): string[] {
+  const question = member.question?.trim();
+  const task = prompt.trim();
+  if (!question) return ["Original task:", task];
+
+  const facet = question.replaceAll(TASK_PLACEHOLDER, task);
+  if (question.includes(TASK_PLACEHOLDER)) {
+    return ["Your assigned facet of the task:", facet];
+  }
+  return [
+    "Your assigned facet of the task:",
+    facet,
+    "",
+    "Original task:",
+    task,
+  ];
+}
+
 function buildJudgeTask(input: BuildJudgeSpawnParamsInput): string {
   const sortedOutputs = [...input.panelOutputs].sort(comparePanelItems);
   const sortedFailures = [...input.failedPanelists].sort(comparePanelItems);
+  // Status and failure lists stay in configuration order so the reader can map
+  // them to the profile. Only the answers the judge weighs are shuffled.
+  const presentedOutputs = shufflePanelItems(sortedOutputs, input.runId);
+  const blindLabels = input.profile.blindPanelLabels
+    ? buildBlindLabelMap([...sortedOutputs, ...sortedFailures])
+    : undefined;
+  const merging = resolveSynthesisMode(input.profile) === "merge";
   return [
-    "You are the fusion judge.",
-    "Read-only synthesis only. Leave files, git state, and the workspace untouched. Do not ask other agents. Do not run subagents.",
-    "Synthesize the panel results. Preserve disagreement instead of forcing consensus.",
+    ...(merging
+      ? COMPOSER_INSTRUCTIONS
+      : [
+          "You are the fusion judge.",
+          "Read-only synthesis only. Leave files, git state, and the workspace untouched. Do not ask other agents. Do not run subagents.",
+          "Synthesize the panel results. Preserve disagreement instead of forcing consensus.",
+        ]),
     "",
     "Original task:",
     input.prompt.trim(),
     "",
     "Panel status:",
-    ...formatPanelStatus(sortedOutputs, sortedFailures),
+    ...formatPanelStatus(sortedOutputs, sortedFailures, blindLabels),
     "",
+    ...(merging
+      ? [
+          "Facet assignments:",
+          ...formatFacetAssignments(input.profile, input.prompt, blindLabels),
+          "",
+        ]
+      : []),
     "Successful panel outputs:",
-    ...formatPanelOutputs(sortedOutputs),
+    ...formatPanelOutputs(presentedOutputs, blindLabels),
     "",
     "Failed panelists:",
-    ...formatFailedPanelists(sortedFailures),
+    ...formatFailedPanelists(sortedFailures, blindLabels),
     "",
+    // Judge-only. The composer has no Contested Claims section, so this block
+    // produces content the report silently drops, and its "which panelist was
+    // right" wording contradicts the composer's "do not rank panelists".
+    ...(merging ? [] : [...CONTESTED_CLAIMS_INSTRUCTIONS, ""]),
     "Output contract:",
-    ...JUDGE_OUTPUT_CONTRACT,
+    ...(merging ? COMPOSER_OUTPUT_CONTRACT : JUDGE_OUTPUT_CONTRACT),
   ].join("\n");
 }
 
+/**
+ * Lists what each member was asked to cover, so the composer can name gaps
+ * without reverse-engineering them from the answers it did receive.
+ */
+function formatFacetAssignments(
+  profile: FusionProfile,
+  prompt: string,
+  blindLabels?: ReadonlyMap<number, string>,
+): string[] {
+  return profile.panel.map((member, index) => {
+    // Substituted the same way the panelist saw it; the raw template would put
+    // a literal "{task}" in front of the composer.
+    const question = member.question?.trim();
+    const facet = question
+      ? question.replaceAll(TASK_PLACEHOLDER, prompt.trim())
+      : (member.role?.trim() ?? "the whole task");
+    // The blind map only covers members that produced an output or a failure.
+    // A member stopped early by `stopWhenPanelAgrees` is in neither, and
+    // falling back to `member.label` would leak the name into the very prompt
+    // that is meant to hide it.
+    const name = blindLabels
+      ? (blindLabels.get(index) ?? "Candidate (did not report)")
+      : memberLabel(member);
+    return `- ${name}: ${facet}`;
+  });
+}
+
 function buildChainJudgeTask(panel: readonly PanelMemberConfig[]): string {
   return [
     "You are the fusion judge.",
@@ -338,7 +474,7 @@ function buildChainJudgeTask(panel: readonly PanelMemberConfig[]): string {
     "",
     "Panel outputs:",
     ...panel.flatMap((member, index) => [
-      `## ${member.label} (${member.id})`,
+      `## ${memberLabel(member)} (${member.id})`,
       `Agent: ${member.agent}`,
       "",
       `{outputs.${chainOutputName(member, index)}}`,
@@ -352,29 +488,39 @@ function buildChainJudgeTask(panel: readonly PanelMemberConfig[]): string {
 function formatPanelStatus(
   outputs: readonly PanelOutput[],
   failures: readonly FailedPanelSummary[],
+  blindLabels?: ReadonlyMap<number, string>,
 ): string[] {
   const lines = [
     `- Successful panelists: ${outputs.length}`,
     `- Failed panelists: ${failures.length}`,
   ];
   for (const output of outputs) {
-    lines.push(`- ${formatPanelName(output)}: succeeded`);
+    lines.push(`- ${formatPanelName(output, blindLabels)}: succeeded`);
   }
   for (const failure of failures) {
     lines.push(
-      `- ${formatPanelName(failure)}: failed - ${firstLine(failure.summary)}`,
+      `- ${formatPanelName(failure, blindLabels)}: failed - ${firstLine(failure.summary)}`,
     );
   }
   return lines;
 }
 
-function formatPanelOutputs(outputs: readonly PanelOutput[]): string[] {
+function formatPanelOutputs(
+  outputs: readonly PanelOutput[],
+  blindLabels?: ReadonlyMap<number, string>,
+): string[] {
   if (outputs.length === 0) return ["(none)"];
+  // Agent names and artifact paths carry the member id, so they are withheld
+  // when blinding. They are debugging aids for the reader, not judging inputs.
   return outputs.flatMap((output) => [
-    `## ${formatPanelName(output)}`,
-    `Agent: ${output.agent}`,
-    ...(output.artifactPath ? [`Artifact: ${output.artifactPath}`] : []),
-    ...(output.sessionPath ? [`Session: ${output.sessionPath}`] : []),
+    `## ${formatPanelName(output, blindLabels)}`,
+    ...(blindLabels
+      ? []
+      : [
+          `Agent: ${output.agent}`,
+          ...(output.artifactPath ? [`Artifact: ${output.artifactPath}`] : []),
+          ...(output.sessionPath ? [`Session: ${output.sessionPath}`] : []),
+        ]),
     "",
     output.output,
     "",
@@ -383,19 +529,56 @@ function formatPanelOutputs(outputs: readonly PanelOutput[]): string[] {
 
 function formatFailedPanelists(
   failures: readonly FailedPanelSummary[],
+  blindLabels?: ReadonlyMap<number, string>,
 ): string[] {
   if (failures.length === 0) return ["(none)"];
-  return failures.flatMap((failure) => [
-    `- ${formatPanelName(failure)} (${failure.agent}): ${failure.summary}`,
-    ...(failure.artifactPath ? [`  Artifact: ${failure.artifactPath}`] : []),
-    ...(failure.sessionPath ? [`  Session: ${failure.sessionPath}`] : []),
-  ]);
+  return failures.flatMap((failure) =>
+    blindLabels
+      ? [`- ${formatPanelName(failure, blindLabels)}: ${failure.summary}`]
+      : [
+          `- ${formatPanelName(failure)} (${failure.agent}): ${failure.summary}`,
+          ...(failure.artifactPath
+            ? [`  Artifact: ${failure.artifactPath}`]
+            : []),
+          ...(failure.sessionPath ? [`  Session: ${failure.sessionPath}`] : []),
+        ],
+  );
 }
 
 function formatPanelName(
   item: Pick<PanelOutput, "index" | "id" | "label">,
+  blindLabels?: ReadonlyMap<number, string>,
 ): string {
-  return item.label ?? item.id ?? `Panelist ${item.index + 1}`;
+  return blindLabels?.get(item.index) ?? panelItemLabel(item);
+}
+
+/**
+ * Maps panel indices to neutral "Candidate X" names. Assigned by index rather
+ * than presentation order so the mapping is stable and the report can restore
+ * real names without persisting extra run state.
+ */
+export function buildBlindLabelMap(
+  items: readonly Pick<PanelOutput, "index">[],
+): Map<number, string> {
+  const labels = new Map<number, string>();
+  const indices = [...new Set(items.map((item) => item.index))].sort(
+    (left, right) => left - right,
+  );
+  indices.forEach((index, position) => {
+    labels.set(index, `Candidate ${blindLabelFor(position)}`);
+  });
+  return labels;
+}
+
+function blindLabelFor(position: number): string {
+  // A..Z, then AA, AB, ... for panels larger than the alphabet.
+  let remaining = position;
+  let label = "";
+  do {
+    label = String.fromCharCode(65 + (remaining % 26)) + label;
+    remaining = Math.floor(remaining / 26) - 1;
+  } while (remaining >= 0);
+  return label;
 }
 
 function comparePanelItems(
@@ -405,6 +588,39 @@ function comparePanelItems(
   return left.index - right.index;
 }
 
+/**
+ * LLM judges favour whichever candidate is presented first or last. A fixed
+ * order therefore advantages the same panel member on every run. Shuffling
+ * removes the bias; seeding it from the run id keeps a persisted run rendering
+ * identically when it is replayed through `fusion:rpc:v1` adopt.
+ */
+export function shufflePanelItems<T>(items: readonly T[], seed: string): T[] {
+  const shuffled = [...items];
+  const nextRandom = createSeededRandom(seed);
+  for (let index = shuffled.length - 1; index > 0; index--) {
+    const swap = Math.floor(nextRandom() * (index + 1));
+    [shuffled[index], shuffled[swap]] = [shuffled[swap]!, shuffled[index]!];
+  }
+  return shuffled;
+}
+
+function createSeededRandom(seed: string): () => number {
+  // FNV-1a over the seed, then mulberry32. Small, dependency-free, and stable
+  // across Node versions - the reproducibility guarantee depends on that.
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < seed.length; index++) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  let state = hash >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let drawn = Math.imul(state ^ (state >>> 15), 1 | state);
+    drawn = (drawn + Math.imul(drawn ^ (drawn >>> 7), 61 | drawn)) ^ drawn;
+    return ((drawn ^ (drawn >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
 function firstLine(value: string): string {
   return value.split(/\r?\n/, 1)[0]?.trim() || "unknown failure";
 }

package/src/run-store.ts

@@ -40,6 +40,8 @@ export interface FusionRunStartInput {
   id?: string;
   prompt: string;
   profileName: string;
+  inlinePanel?: string[];
+  baseProfileName?: string;
   operationId?: string;
   phase?: Exclude<FusionPhase, FusionTerminalPhase>;
   createdAt?: number;
@@ -149,6 +151,14 @@ export class FusionRunStore {
       id: input.id ?? this.idFactory(),
       prompt: input.prompt,
       profileName: input.profileName,
+      ...(input.inlinePanel?.length
+        ? {
+            inlinePanel: input.inlinePanel,
+            ...(input.baseProfileName
+              ? { baseProfileName: input.baseProfileName }
+              : {}),
+          }
+        : {}),
       ...(input.operationId !== undefined
         ? { operationId: input.operationId }
         : {}),
@@ -385,6 +395,14 @@ function cloneRun(run: FusionRun): FusionRun {
     id: run.id,
     prompt: run.prompt,
     profileName: run.profileName,
+    // cloneRun is a strict field allowlist: a new FusionRun field is dropped on
+    // both write and read until it is listed here.
+    ...(run.inlinePanel !== undefined
+      ? { inlinePanel: [...run.inlinePanel] }
+      : {}),
+    ...(run.baseProfileName !== undefined
+      ? { baseProfileName: run.baseProfileName }
+      : {}),
     ...(run.operationId !== undefined ? { operationId: run.operationId } : {}),
     phase: run.phase,
     createdAt: run.createdAt,
@@ -444,6 +462,19 @@ function isFusionRunState(value: unknown): value is FusionRun {
   if (value.operationId !== undefined && !isNonEmptyString(value.operationId)) {
     return false;
   }
+  if (
+    value.inlinePanel !== undefined &&
+    (!Array.isArray(value.inlinePanel) ||
+      !value.inlinePanel.every(isNonEmptyString))
+  ) {
+    return false;
+  }
+  if (
+    value.baseProfileName !== undefined &&
+    !isNonEmptyString(value.baseProfileName)
+  ) {
+    return false;
+  }
   if (!isFusionPhase(value.phase)) return false;
   if (!isFiniteNumber(value.createdAt)) return false;
   if (!isFiniteNumber(value.updatedAt)) return false;

package/src/types.ts

@@ -8,15 +8,34 @@ export const THINKING_LEVELS = [
 ] as const;
 
 export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export const PANEL_AGENT = "pi-fusion.fusion-panelist";
+export const PANEL_AGENT_WEB = "pi-fusion.fusion-panelist-web";
+export const PANEL_AGENT_FULL = "pi-fusion.fusion-panelist-full";
+export const JUDGE_AGENT = "pi-fusion.fusion-judge";
+export const COMPOSER_AGENT = "pi-fusion.fusion-composer";
+
 export type FusionContextMode = "fresh" | "fork";
 
+/**
+ * How panel answers become one report.
+ * `select` — panelists answered the same question; the judge picks or reconciles.
+ * `merge`  — panelists answered different facets; the composer unions them.
+ */
+export type FusionSynthesisMode = "select" | "merge";
+
 export interface PanelMemberConfig {
   id: string;
-  label: string;
+  /** Report label. Defaults to `id` — set it only when they should differ. */
+  label?: string;
   agent: string;
   model?: string;
   thinking?: ThinkingLevel;
   role?: string;
+  /**
+   * Facet prompt sent instead of the raw task. `{task}` is substituted with the
+   * original prompt. Turns a redundant panel into one that divides the work.
+   */
+  question?: string;
 }
 
 export interface JudgeConfig {
@@ -32,6 +51,65 @@ export interface FusionProfile {
   timeoutMs?: number;
   context?: FusionContextMode;
   stopWhenPanelAgrees?: boolean;
+  /**
+   * Present panel answers to the judge as "Candidate A/B/C" instead of the
+   * configured labels. Role names read as authority cues before a word of
+   * content is compared. The report always restores the real labels.
+   */
+  blindPanelLabels?: boolean;
+  /**
+   * Caps the tool calls the judge may spend verifying contested claims.
+   * `soft` nudges, `hard` blocks further tool use so the judge still finalises.
+   */
+  judgeToolBudget?: ToolBudget;
+  /**
+   * Usually omit this. It is inferred: a panel where any member has a
+   * `question` is answering facets, so it merges; otherwise it selects.
+   * Set it only to override that — most often `"select"` on a faceted panel
+   * when you deliberately want the judge to pick rather than union.
+   *
+   * Under `merge` the synthesis spawn uses the composer agent and contract
+   * instead of the judge's. It reuses the judge run slot, so no new
+   * `FusionPhase` is introduced and `fusion:rpc:v1` stays compatible.
+   */
+  synthesis?: FusionSynthesisMode;
+}
+
+/**
+ * Facets are the thing that actually decides how answers combine, so the mode
+ * follows them by default. Requiring `synthesis` and `question` to agree made
+ * two ways to get a silently wrong report: facets judged for consensus they
+ * cannot have, or a composer told to merge facets that do not exist.
+ */
+/**
+ * Report label for a panel item. `label` is optional; it falls back to `id`, and
+ * then to the position. One definition so report and prompt never disagree.
+ */
+export function panelItemLabel(
+  item: Pick<PanelOutput, "index" | "id" | "label">,
+): string {
+  return item.label?.trim() || item.id?.trim() || `Panelist ${item.index + 1}`;
+}
+
+/** Report label for a member; `label` is optional and falls back to `id`. */
+export function memberLabel(
+  member: Pick<PanelMemberConfig, "id" | "label">,
+): string {
+  return member.label?.trim() || member.id;
+}
+
+export function resolveSynthesisMode(
+  profile: Pick<FusionProfile, "panel" | "synthesis">,
+): FusionSynthesisMode {
+  if (profile.synthesis) return profile.synthesis;
+  return profile.panel.some((member) => member.question?.trim())
+    ? "merge"
+    : "select";
+}
+
+export interface ToolBudget {
+  soft?: number;
+  hard?: number;
 }
 
 export type PanelConfidence = "low" | "medium" | "high";
@@ -79,6 +157,8 @@ export interface ParsedFusionArgs {
   prompt: string;
   profile?: string;
   operationId?: string;
+  /** Inline panel entries from `--panel`: `<model>` or `<agent>:<model>`. */
+  panel?: string[];
 }
 
 export interface PanelOutput {
@@ -121,6 +201,14 @@ export interface FusionRun {
   id: string;
   prompt: string;
   profileName: string;
+  /**
+   * Inline `--panel` entries, when the run used them. `profileName` then carries
+   * a display name that no config defines, so restore rebuilds the profile from
+   * `baseProfileName` plus these entries instead of looking the display name up.
+   */
+  inlinePanel?: string[];
+  /** Name of the config profile the inline panel was layered onto. */
+  baseProfileName?: string;
   operationId?: string;
   phase: FusionPhase;
   createdAt: number;