@alexeiled/pi-fusion 0.5.2 → 0.6.0

package/src/report.ts

@@ -1,6 +1,18 @@
-import type { FailedPanelSummary, PanelOutput } from "./run-builder.js";
+import {
+  buildBlindLabelMap,
+  type FailedPanelSummary,
+  type PanelOutput,
+} from "./run-builder.js";
 import { summarizeProviderFailures } from "./run-observations.js";
-import type { FusionRun, ProviderFailure, RunObservation } from "./types.js";
+import {
+  memberLabel,
+  panelItemLabel,
+  type FusionRun,
+  type FusionSynthesisMode,
+  type PanelMemberConfig,
+  type ProviderFailure,
+  type RunObservation,
+} from "./types.js";
 
 type ReportRun = Pick<
   FusionRun,
@@ -19,6 +31,9 @@ export interface RenderPanelFailureReportInput {
   failures: readonly FailedPanelSummary[];
   error?: string;
   judgeModel?: string;
+  synthesis?: FusionSynthesisMode;
+  /** Configured members, so a merge failure can name the uncovered facets. */
+  panel?: readonly PanelMemberConfig[];
 }
 
 export interface RenderSinglePanelReportInput {
@@ -35,9 +50,19 @@ export interface RenderJudgeReportInput {
   failures?: readonly FailedPanelSummary[];
   judgeModel?: string;
   judgeObservation?: RunObservation;
+  /**
+   * Set when the judge was shown neutral candidate names. The report always
+   * shows real member names, so the judge's prose is rewritten before parsing.
+   */
+  blindPanelLabels?: boolean;
+  /** Selects which synthesis sections the report renders. Defaults to `select`. */
+  synthesis?: FusionSynthesisMode;
 }
 
 export interface RenderFailureReportInput {
+  synthesis?: FusionSynthesisMode;
+  /** Configured members, so a merge failure can name the uncovered facets. */
+  panel?: readonly PanelMemberConfig[];
   run: ReportRun;
   error: string;
   panelOutputs?: readonly PanelOutput[];
@@ -46,6 +71,9 @@ export interface RenderFailureReportInput {
 }
 
 export interface RenderCancelledReportInput {
+  synthesis?: FusionSynthesisMode;
+  /** Configured members, so a merge failure can name the uncovered facets. */
+  panel?: readonly PanelMemberConfig[];
   run: ReportRun;
   method: "stop" | "interrupt" | "local";
   targetRunId?: string;
@@ -59,8 +87,13 @@ type ReportSectionTitle =
   | "Agent Status"
   | "Consensus"
   | "Disagreements"
+  | "Contested Claims"
   | "Unique Insights"
   | "Blind Spots"
+  | "Coverage Map"
+  | "Combined Answer"
+  | "Gaps"
+  | "Conflicts At Seams"
   | "Recommendation"
   | "Risks"
   | "Next Step"
@@ -78,11 +111,86 @@ interface AgentStatusOptions {
   judgeStatus: string;
   judgeModel?: string;
   extra?: readonly string[];
+  /** Names the synthesis step for the reader. Merge runs the composer. */
+  synthesis?: FusionSynthesisMode;
+}
+
+/** Lists the facets that no panelist covered, for a merge-mode failure. */
+function formatUncoveredFacets(
+  panel?: readonly PanelMemberConfig[],
+): string | string[] {
+  if (!panel?.length) return "Every configured facet is uncovered.";
+  return panel.map((member) => {
+    const facet =
+      member.question?.trim() ?? member.role?.trim() ?? "the whole task";
+    return `- ${memberLabel(member)}: ${facet} (uncovered)`;
+  });
+}
+
+/**
+ * The synthesis-shaped sections for a report that has no synthesis output:
+ * failure, cancellation, or an all-failed panel. Select and merge need
+ * different section names, so every such renderer goes through here rather than
+ * hardcoding one shape.
+ */
+function emptySynthesisSections(input: {
+  synthesis?: FusionSynthesisMode;
+  reason: string;
+  /** Select-mode wording, passed verbatim so each caller keeps its own text. */
+  select: {
+    consensus: string;
+    disagreements: string;
+    uniqueInsights: string;
+    blindSpots: string;
+  };
+  panel?: readonly PanelMemberConfig[];
+}): ReportSection[] {
+  if (input.synthesis === "merge") {
+    return [
+      {
+        title: "Coverage Map",
+        content: `Nothing was covered because ${input.reason}.`,
+      },
+      { title: "Combined Answer", content: "No answer is available." },
+      { title: "Gaps", content: formatUncoveredFacets(input.panel) },
+      {
+        title: "Conflicts At Seams",
+        content: "No answers were produced, so no seams could conflict.",
+      },
+    ];
+  }
+  return [
+    { title: "Consensus", content: input.select.consensus },
+    { title: "Disagreements", content: input.select.disagreements },
+    { title: "Unique Insights", content: input.select.uniqueInsights },
+    { title: "Blind Spots", content: input.select.blindSpots },
+  ];
+}
+
+/** What actually ran in the synthesis slot, for report labels. */
+function synthesisLabel(synthesis?: FusionSynthesisMode): string {
+  return synthesis === "merge" ? "Composer" : "Judge";
 }
 
 export function renderPanelFailureReport(
   input: RenderPanelFailureReportInput,
 ): string {
+  const synthesisName = synthesisLabel(input.synthesis);
+  // Under merge the select sections are meaningless: nobody answered the same
+  // question, so there is no consensus to be absent. What the reader needs is
+  // which facets went uncovered.
+  const emptySections = emptySynthesisSections({
+    ...(input.synthesis ? { synthesis: input.synthesis } : {}),
+    reason: "all panelists failed",
+    select: {
+      consensus: "No consensus was available because all panelists failed.",
+      disagreements: `No disagreements were synthesized because the ${synthesisName.toLowerCase()} did not run.`,
+      uniqueInsights: "No panel output was available to summarize.",
+      blindSpots:
+        "All panelists failed, so the report may be missing every intended review perspective.",
+    },
+    ...(input.panel ? { panel: input.panel } : {}),
+  });
   return renderReport([
     {
       title: "Summary",
@@ -96,26 +204,10 @@ export function renderPanelFailureReport(
         failures: input.failures,
         judgeStatus: "not run - no successful panelists",
         ...(input.judgeModel ? { judgeModel: input.judgeModel } : {}),
+        ...(input.synthesis ? { synthesis: input.synthesis } : {}),
       }),
     },
-    {
-      title: "Consensus",
-      content: "No consensus was available because all panelists failed.",
-    },
-    {
-      title: "Disagreements",
-      content:
-        "No disagreements were synthesized because the judge did not run.",
-    },
-    {
-      title: "Unique Insights",
-      content: "No panel output was available to summarize.",
-    },
-    {
-      title: "Blind Spots",
-      content:
-        "All panelists failed, so the report may be missing every intended review perspective.",
-    },
+    ...emptySections,
     { title: "Recommendation", content: "No recommendation is available." },
     {
       title: "Risks",
@@ -195,15 +287,97 @@ export function renderSinglePanelReport(
   return renderReport(sections);
 }
 
+/**
+ * Rewrites the neutral names the judge saw back to the configured member names.
+ * Longest label first so "Candidate AA" is not partly replaced by "Candidate A".
+ */
+function restoreBlindLabels(
+  judgeOutput: string,
+  panelOutputs: readonly PanelOutput[],
+  failures: readonly FailedPanelSummary[],
+): string {
+  const items = [...panelOutputs, ...failures];
+  const blindLabels = buildBlindLabelMap(items);
+  const realNames = new Map(
+    items.map((item) => [item.index, panelItemLabel(item)]),
+  );
+
+  let restored = judgeOutput;
+  const ordered = [...blindLabels.entries()].sort(
+    (left, right) => right[1].length - left[1].length,
+  );
+  for (const [index, blindLabel] of ordered) {
+    const realName = realNames.get(index);
+    if (!realName) continue;
+    restored = restored.replaceAll(blindLabel, realName);
+  }
+  return restored;
+}
+
 export function renderJudgeReport(input: RenderJudgeReportInput): string {
   const panelOutputs = input.panelOutputs ?? [];
   const failures = input.failures ?? [];
-  const sections = parseMarkdownSections(input.judgeOutput);
-  const unsectionedOutput = stripReportTitle(input.judgeOutput);
+  const judgeOutput = input.blindPanelLabels
+    ? restoreBlindLabels(input.judgeOutput, panelOutputs, failures)
+    : input.judgeOutput;
+  const sections = parseMarkdownSections(judgeOutput);
+  const unsectionedOutput = stripReportTitle(judgeOutput);
   const recommendationFallback =
     sections.size === 0 && unsectionedOutput
       ? unsectionedOutput
-      : "Judge completed without a recommendation.";
+      : `${synthesisLabel(input.synthesis)} completed without a recommendation.`;
+
+  // Section titles differ by synthesis mode; everything around them - agent
+  // status, metadata, run details - is shared.
+  const merging = input.synthesis === "merge";
+  const synthesisSections: ReportSection[] = merging
+    ? [
+        {
+          title: "Coverage Map",
+          content:
+            sections.get("Coverage Map") ?? "Not specified by the composer.",
+        },
+        {
+          title: "Combined Answer",
+          content:
+            sections.get("Combined Answer") ?? "Not specified by the composer.",
+        },
+        {
+          title: "Gaps",
+          content: sections.get("Gaps") ?? "Not specified by the composer.",
+        },
+        {
+          title: "Conflicts At Seams",
+          content:
+            sections.get("Conflicts At Seams") ??
+            "Not specified by the composer.",
+        },
+      ]
+    : [
+        {
+          title: "Consensus",
+          content: sections.get("Consensus") ?? "Not specified by the judge.",
+        },
+        {
+          title: "Disagreements",
+          content:
+            sections.get("Disagreements") ?? "Not specified by the judge.",
+        },
+        {
+          title: "Contested Claims",
+          content:
+            sections.get("Contested Claims") ?? "Not specified by the judge.",
+        },
+        {
+          title: "Unique Insights",
+          content:
+            sections.get("Unique Insights") ?? "Not specified by the judge.",
+        },
+        {
+          title: "Blind Spots",
+          content: sections.get("Blind Spots") ?? "Not specified by the judge.",
+        },
+      ];
 
   const reportSections: ReportSection[] = [
     {
@@ -217,24 +391,10 @@ export function renderJudgeReport(input: RenderJudgeReportInput): string {
         failures,
         judgeStatus: "succeeded",
         ...(input.judgeModel ? { judgeModel: input.judgeModel } : {}),
+        ...(input.synthesis ? { synthesis: input.synthesis } : {}),
       }),
     },
-    {
-      title: "Consensus",
-      content: sections.get("Consensus") ?? "Not specified by the judge.",
-    },
-    {
-      title: "Disagreements",
-      content: sections.get("Disagreements") ?? "Not specified by the judge.",
-    },
-    {
-      title: "Unique Insights",
-      content: sections.get("Unique Insights") ?? "Not specified by the judge.",
-    },
-    {
-      title: "Blind Spots",
-      content: sections.get("Blind Spots") ?? "Not specified by the judge.",
-    },
+    ...synthesisSections,
     {
       title: "Recommendation",
       content: sections.get("Recommendation") ?? recommendationFallback,
@@ -258,6 +418,7 @@ export function renderJudgeReport(input: RenderJudgeReportInput): string {
     ...(input.judgeObservation
       ? { judgeObservation: input.judgeObservation }
       : {}),
+    ...(input.synthesis ? { synthesis: input.synthesis } : {}),
   });
   if (runDetails) reportSections.splice(-1, 0, runDetails);
   return renderReport(reportSections);
@@ -282,23 +443,20 @@ export function renderFailureReport(input: RenderFailureReportInput): string {
         extra: [`- Phase: ${phase}`],
       }),
     },
-    {
-      title: "Consensus",
-      content: "No consensus was available because fusion failed.",
-    },
-    {
-      title: "Disagreements",
-      content: "No disagreements were synthesized because fusion failed.",
-    },
-    {
-      title: "Unique Insights",
-      content: "No unique insights were synthesized because fusion failed.",
-    },
-    {
-      title: "Blind Spots",
-      content:
-        "The failure may hide panel disagreements, missing evidence, or provider-specific errors.",
-    },
+    ...emptySynthesisSections({
+      ...(input.synthesis ? { synthesis: input.synthesis } : {}),
+      reason: "fusion failed",
+      select: {
+        consensus: "No consensus was available because fusion failed.",
+        disagreements:
+          "No disagreements were synthesized because fusion failed.",
+        uniqueInsights:
+          "No unique insights were synthesized because fusion failed.",
+        blindSpots:
+          "The failure may hide panel disagreements, missing evidence, or provider-specific errors.",
+      },
+      ...(input.panel ? { panel: input.panel } : {}),
+    }),
     { title: "Recommendation", content: "No recommendation is available." },
     {
       title: "Risks",
@@ -334,25 +492,21 @@ export function renderCancelledReport(
         ],
       }),
     },
-    {
-      title: "Consensus",
-      content: "No final consensus was available because fusion was cancelled.",
-    },
-    {
-      title: "Disagreements",
-      content:
-        "No final disagreements were synthesized because fusion was cancelled.",
-    },
-    {
-      title: "Unique Insights",
-      content:
-        "No final unique insights were synthesized because fusion was cancelled.",
-    },
-    {
-      title: "Blind Spots",
-      content:
-        "Cancellation may leave in-flight panel or judge output incomplete.",
-    },
+    ...emptySynthesisSections({
+      ...(input.synthesis ? { synthesis: input.synthesis } : {}),
+      reason: "fusion was cancelled",
+      select: {
+        consensus:
+          "No final consensus was available because fusion was cancelled.",
+        disagreements:
+          "No final disagreements were synthesized because fusion was cancelled.",
+        uniqueInsights:
+          "No final unique insights were synthesized because fusion was cancelled.",
+        blindSpots:
+          "Cancellation may leave in-flight panel or judge output incomplete.",
+      },
+      ...(input.panel ? { panel: input.panel } : {}),
+    }),
     { title: "Recommendation", content: "No recommendation is available." },
     {
       title: "Risks",
@@ -387,6 +541,7 @@ interface RunDetailsInput {
   failures: readonly FailedPanelSummary[];
   judgeModel?: string;
   judgeObservation?: RunObservation;
+  synthesis?: FusionSynthesisMode;
 }
 
 function formatRunDetails(input: RunDetailsInput): ReportSection | undefined {
@@ -406,7 +561,7 @@ function formatRunDetails(input: RunDetailsInput): ReportSection | undefined {
   ];
   if (input.judgeObservation) {
     entries.push({
-      label: "Judge",
+      label: synthesisLabel(input.synthesis),
       status: "completed",
       configuredModel: input.judgeModel,
       observation: input.judgeObservation,
@@ -518,7 +673,7 @@ function formatAgentStatus(options: AgentStatusOptions): string[] {
     lines.push("- Panel status: not available");
   }
 
-  lines.push(`- Judge: ${options.judgeStatus}`);
+  lines.push(`- ${synthesisLabel(options.synthesis)}: ${options.judgeStatus}`);
   if (options.judgeModel) {
     lines.push(`  Configured model: ${options.judgeModel}`);
   }
@@ -638,7 +793,7 @@ function plural(count: number, singular: string): string {
 function formatPanelName(
   item: Pick<PanelOutput, "index" | "id" | "label">,
 ): string {
-  return item.label ?? item.id ?? `Panelist ${item.index + 1}`;
+  return panelItemLabel(item);
 }
 
 function comparePanelItems(