@mrclrchtr/supi-review 2.4.1 → 2.6.0

package/src/types.ts

@@ -86,6 +86,9 @@ export interface ReviewSnapshot {
   stats: DiffStats;
 }
 
+/** Snapshot metadata safe to retain without duplicating bulk diff text. */
+export type ReviewSnapshotSummary = Omit<ReviewSnapshot, "diffText">;
+
 /** Model picked explicitly for the current review run. */
 export type ReviewModelSelection = import("@mrclrchtr/supi-core/model-selection").ModelSelection;
 
@@ -107,6 +110,107 @@ export interface SynthesizedReviewBrief {
   note?: string;
 }
 
+/** Brief field evaluated by the main agent before reviewer sessions run. */
+export type ReviewBriefField =
+  | "summary"
+  | "intendedOutcome"
+  | "constraints"
+  | "focusAreas"
+  | "riskyFiles"
+  | "unresolvedQuestions"
+  | "reviewInstructionBlockIds";
+
+/** Class of defect identified in a generated review brief. */
+export type BriefCritiqueFindingKind =
+  | "omission"
+  | "unsupported-inference"
+  | "misprioritized"
+  | "unclear";
+
+/** One evidence-backed main-agent criticism of a generated review brief. */
+export interface BriefCritiqueFinding {
+  kind: BriefCritiqueFindingKind;
+  field: ReviewBriefField;
+  explanation: string;
+  evidence: string;
+  proposedChange: string;
+}
+
+/** Structured quality gate completed by the main agent before review execution. */
+export interface BriefCritique {
+  verdict: "accept" | "revise";
+  summary: string;
+  findings: BriefCritiqueFinding[];
+}
+
+/** One independent reviewer child-session assignment. */
+export interface ReviewerAssignment {
+  id: string;
+  focus: string;
+}
+
+/** Generated/effective brief pair retained for synthesis-prompt evaluation. */
+export interface BriefEvaluation {
+  planId: string;
+  briefPromptVersion: string;
+  generatedBrief: SynthesizedReviewBrief;
+  critique: BriefCritique;
+  effectiveBrief: SynthesizedReviewBrief;
+  synthesizerModelId: string;
+  snapshotFingerprint: string;
+}
+
+/** Normalized reviewer result without repeated snapshot or brief payloads. */
+export type AgentReviewerResult =
+  | {
+      kind: "success";
+      output: NormalizedReviewOutput;
+      modelId: string;
+    }
+  | {
+      kind: "failed";
+      reason: string;
+      modelId: string;
+      debug?: ReviewFailureDebugInfo;
+    }
+  | {
+      kind: "canceled";
+      modelId: string;
+      debug?: ReviewFailureDebugInfo;
+    }
+  | {
+      kind: "timeout";
+      timeoutMs: number;
+      partialOutput?: string;
+      modelId: string;
+      debug?: ReviewFailureDebugInfo;
+    };
+
+/** One normalized result from a focused reviewer child session. */
+export interface ReviewerAssignmentResult {
+  assignment: ReviewerAssignment;
+  result: AgentReviewerResult;
+}
+
+/** Structured details retained on a completed agent-driven review batch. */
+export interface AgentReviewBatchDetails {
+  kind: "review-batch";
+  evaluation: BriefEvaluation;
+  snapshot: ReviewSnapshotSummary;
+  results: ReviewerAssignmentResult[];
+}
+
+/** Structured details returned when an agent-driven review plan is prepared. */
+export interface PreparedAgentReviewDetails {
+  kind: "review-prepared";
+  planId: string;
+  briefPromptVersion: string;
+  generatedBrief: SynthesizedReviewBrief;
+  snapshot: ReviewSnapshotSummary;
+  snapshotFingerprint: string;
+  modelId: string;
+}
+
 /** Final prompt packet passed to the reviewer child session. */
 export interface ReviewPacket {
   prompt: string;

package/src/ui/review-tool-format.ts

@@ -0,0 +1,138 @@
+import type {
+  AgentReviewBatchDetails,
+  AgentReviewerResult,
+  BriefCritique,
+  PreparedAgentReviewDetails,
+  ReviewResult,
+  ReviewSnapshotSummary,
+  SynthesizedReviewBrief,
+} from "../types.ts";
+import { formatReviewContent } from "./format-content.ts";
+
+/** Format a generated brief and the required main-agent quality gate. */
+export function formatPreparedAgentReview(details: PreparedAgentReviewDetails): string {
+  return [
+    "# Review Brief Prepared",
+    "",
+    `Plan ID: ${details.planId}`,
+    `Brief prompt version: ${details.briefPromptVersion}`,
+    `Model: ${details.modelId}`,
+    `Snapshot: ${details.snapshot.title}`,
+    `Snapshot fingerprint: ${details.snapshotFingerprint}`,
+    `Files changed: ${details.snapshot.changedFiles.length}`,
+    `Diff stats: +${details.snapshot.stats.additions} / -${details.snapshot.stats.deletions}`,
+    "",
+    "## Generated brief",
+    "",
+    ...formatBrief(details.generatedBrief),
+    "",
+    "## Required next step",
+    "",
+    "Critically compare this brief with the user request, session evidence, and snapshot.",
+    "Then call supi_review_run with this planId, an evidence-backed critique, and one to four reviewer assignments.",
+    'When the critique verdict is "revise", provide the full corrected revisedBrief.',
+    "Do not mutate the review target before running the prepared plan, and call supi_review_run without sibling mutation tools.",
+    "",
+    "## Changed files",
+    "",
+    ...details.snapshot.changedFiles.map((file) => `- ${file}`),
+  ].join("\n");
+}
+
+/** Format a completed review batch for the parent agent. */
+export function formatAgentReviewBatch(details: AgentReviewBatchDetails): string {
+  const lines = [
+    "# Review Batch Complete",
+    "",
+    `Plan ID: ${details.evaluation.planId}`,
+    `Snapshot: ${details.snapshot.title}`,
+    `Model: ${details.evaluation.synthesizerModelId}`,
+    `Brief critique: ${details.evaluation.critique.verdict.toUpperCase()} — ${details.evaluation.critique.summary}`,
+    `Brief critique findings: ${details.evaluation.critique.findings.length}`,
+  ];
+
+  for (const { assignment, result } of details.results) {
+    lines.push(
+      "",
+      "---",
+      "",
+      `## Reviewer: ${assignment.id}`,
+      "",
+      `Focus: ${assignment.focus}`,
+      "",
+      formatReviewContent(hydrateResult(result, details.snapshot)),
+    );
+  }
+
+  lines.push(
+    "",
+    "---",
+    "",
+    "## Retained main-agent brief critique",
+    "",
+    ...formatCritique(details.evaluation.critique),
+  );
+  if (details.evaluation.critique.verdict === "revise") {
+    lines.push(
+      "",
+      "## Effective revised brief",
+      "",
+      ...formatBrief(details.evaluation.effectiveBrief),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** Format one structured main-agent brief critique. */
+export function formatCritique(critique: BriefCritique): string[] {
+  const lines = [`Verdict: ${critique.verdict.toUpperCase()}`, `Summary: ${critique.summary}`];
+  if (critique.findings.length === 0) {
+    lines.push("Findings: none");
+    return lines;
+  }
+
+  lines.push("Findings:");
+  for (const [index, finding] of critique.findings.entries()) {
+    lines.push(
+      `${index + 1}. [${finding.kind}] ${finding.field}: ${finding.explanation}`,
+      `   Evidence: ${finding.evidence}`,
+      `   Proposed change: ${finding.proposedChange}`,
+    );
+  }
+  return lines;
+}
+
+/** Format all structured fields of a synthesized review brief. */
+export function formatBrief(brief: SynthesizedReviewBrief): string[] {
+  const lines = [
+    `Summary: ${brief.summary}`,
+    `Intended outcome: ${brief.intendedOutcome}`,
+    ...formatList("Constraints", brief.constraints),
+    ...formatList("Focus areas", brief.focusAreas),
+    ...formatList("Risky files", brief.riskyFiles),
+    ...formatList("Unresolved questions", brief.unresolvedQuestions),
+    ...formatList("Review instruction blocks", brief.reviewInstructionBlockIds),
+  ];
+  if (brief.note) lines.push(`Note: ${brief.note}`);
+  return lines;
+}
+
+function formatList(label: string, values: readonly string[]): string[] {
+  if (values.length === 0) return [`${label}: none`];
+  return [`${label}:`, ...values.map((value) => `- ${value}`)];
+}
+
+function hydrateResult(result: AgentReviewerResult, summary: ReviewSnapshotSummary): ReviewResult {
+  const snapshot = { ...summary, diffText: "" };
+  switch (result.kind) {
+    case "success":
+      return { ...result, snapshot };
+    case "failed":
+      return { ...result, snapshot };
+    case "canceled":
+      return { ...result, snapshot };
+    case "timeout":
+      return { ...result, snapshot };
+  }
+}

package/src/ui/review-tool-renderer.ts

@@ -0,0 +1,203 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import type { PrepareAgentReviewInput, RunAgentReviewInput } from "../tool/agent-review-schemas.ts";
+import type {
+  AgentReviewBatchDetails,
+  PreparedAgentReviewDetails,
+  ReviewProgress,
+} from "../types.ts";
+import { formatBrief, formatCritique } from "./review-tool-format.ts";
+
+type ReviewTheme = Parameters<Parameters<ExtensionAPI["registerMessageRenderer"]>[1]>[2];
+
+interface ToolResultLike {
+  content: Array<{ type: string; text?: string }>;
+  details?: unknown;
+}
+
+/** Partial tool-result details used while synthesis or reviewer sessions are active. */
+export interface AgentReviewProgressDetails {
+  kind: "review-progress";
+  phase: "prepare" | "review";
+  completed: number;
+  total: number;
+  reviewers?: Record<string, ReviewProgress>;
+}
+
+export function renderPrepareReviewCall(args: PrepareAgentReviewInput, theme: ReviewTheme): Text {
+  const target = args.target?.kind ?? "working-tree";
+  const ref = args.target?.base ?? args.target?.sha;
+  const suffix = ref ? ` (${ref})` : "";
+  return new Text(
+    `${theme.fg("toolTitle", theme.bold("supi_review_prepare "))}${theme.fg("accent", target)}${theme.fg("dim", suffix)}`,
+    0,
+    0,
+  );
+}
+
+export function renderPrepareReviewResult(
+  result: ToolResultLike,
+  expanded: boolean,
+  theme: ReviewTheme,
+): Container | Text {
+  const details = result.details as
+    | PreparedAgentReviewDetails
+    | AgentReviewProgressDetails
+    | undefined;
+  if (details?.kind === "review-progress") {
+    return new Text(theme.fg("warning", "Synthesizing review brief…"), 0, 0);
+  }
+  if (details?.kind !== "review-prepared") return fallbackResult(result, theme);
+
+  const container = new Container();
+  container.addChild(
+    new Text(
+      `${theme.fg("success", "✓")} ${theme.fg("toolTitle", theme.bold("Review brief prepared"))}`,
+      0,
+      0,
+    ),
+  );
+  container.addChild(new Text(theme.fg("dim", `Plan: ${details.planId}`), 0, 0));
+  container.addChild(new Text(theme.fg("dim", `Snapshot: ${details.snapshot.title}`), 0, 0));
+  container.addChild(
+    new Text(theme.fg("muted", `Summary: ${details.generatedBrief.summary}`), 0, 0),
+  );
+  container.addChild(
+    new Text(theme.fg("warning", "Main-agent critique required before run"), 0, 0),
+  );
+
+  if (expanded) {
+    container.addChild(new Spacer(1));
+    for (const line of formatBrief(details.generatedBrief)) {
+      container.addChild(new Text(theme.fg("dim", line), 0, 0));
+    }
+  }
+  return container;
+}
+
+export function renderRunReviewCall(
+  args: RunAgentReviewInput,
+  expanded: boolean,
+  theme: ReviewTheme,
+): Container | Text {
+  const verdictColor = args.critique.verdict === "revise" ? "warning" : "success";
+  const header = `${theme.fg("toolTitle", theme.bold("supi_review_run "))}${theme.fg(verdictColor, args.critique.verdict)}${theme.fg("dim", ` · ${args.critique.findings.length} critique finding(s) · ${args.reviewers.length} reviewer(s)`)}`;
+  if (!expanded) return new Text(header, 0, 0);
+
+  const container = new Container();
+  container.addChild(new Text(header, 0, 0));
+  for (const line of formatCritique(args.critique)) {
+    container.addChild(new Text(theme.fg("dim", line), 0, 0));
+  }
+  if (args.revisedBrief) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("accent", "Proposed revised brief"), 0, 0));
+    for (const line of formatBrief(args.revisedBrief)) {
+      container.addChild(new Text(theme.fg("dim", line), 0, 0));
+    }
+  }
+  container.addChild(new Spacer(1));
+  for (const reviewer of args.reviewers) {
+    container.addChild(new Text(theme.fg("muted", `${reviewer.id}: ${reviewer.focus}`), 0, 0));
+  }
+  return container;
+}
+
+export function renderRunReviewResult(
+  result: ToolResultLike,
+  expanded: boolean,
+  theme: ReviewTheme,
+): Container | Text {
+  const details = result.details as
+    | AgentReviewBatchDetails
+    | AgentReviewProgressDetails
+    | undefined;
+  if (details?.kind === "review-progress") {
+    return renderProgress(details, theme);
+  }
+  if (details?.kind !== "review-batch") return fallbackResult(result, theme);
+
+  const container = new Container();
+  const successCount = details.results.filter((entry) => entry.result.kind === "success").length;
+  const verdictColor = details.evaluation.critique.verdict === "revise" ? "warning" : "success";
+  container.addChild(
+    new Text(
+      `${theme.fg("success", "✓")} ${theme.fg("toolTitle", theme.bold("Review batch complete"))}${theme.fg("dim", ` · ${successCount}/${details.results.length} succeeded`)}`,
+      0,
+      0,
+    ),
+  );
+  container.addChild(
+    new Text(
+      theme.fg(
+        verdictColor,
+        `Brief ${details.evaluation.critique.verdict}: ${details.evaluation.critique.summary}`,
+      ),
+      0,
+      0,
+    ),
+  );
+
+  for (const entry of details.results) {
+    const status = summarizeResult(entry.result);
+    container.addChild(
+      new Text(
+        `${theme.fg(status.color, status.icon)} ${entry.assignment.id}: ${status.text}`,
+        0,
+        0,
+      ),
+    );
+  }
+
+  if (expanded) {
+    container.addChild(new Spacer(1));
+    for (const line of formatCritique(details.evaluation.critique)) {
+      container.addChild(new Text(theme.fg("dim", line), 0, 0));
+    }
+    if (details.evaluation.critique.verdict === "revise") {
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("accent", "Effective revised brief"), 0, 0));
+      for (const line of formatBrief(details.evaluation.effectiveBrief)) {
+        container.addChild(new Text(theme.fg("dim", line), 0, 0));
+      }
+    }
+  }
+  return container;
+}
+
+function renderProgress(details: AgentReviewProgressDetails, theme: ReviewTheme): Text {
+  if (details.phase === "prepare") {
+    return new Text(theme.fg("warning", "Synthesizing review brief…"), 0, 0);
+  }
+  return new Text(
+    theme.fg("warning", `Running reviewers… ${details.completed}/${details.total} completed`),
+    0,
+    0,
+  );
+}
+
+function summarizeResult(result: AgentReviewBatchDetails["results"][number]["result"]): {
+  icon: string;
+  color: "success" | "warning" | "error";
+  text: string;
+} {
+  switch (result.kind) {
+    case "success":
+      return {
+        icon: "✓",
+        color: result.output.items.length > 0 ? "warning" : "success",
+        text: `${result.output.items.length} item(s), ${result.output.overall_correctness}`,
+      };
+    case "failed":
+      return { icon: "✗", color: "error", text: result.reason };
+    case "canceled":
+      return { icon: "○", color: "warning", text: "canceled" };
+    case "timeout":
+      return { icon: "◷", color: "warning", text: "timed out" };
+  }
+}
+
+function fallbackResult(result: ToolResultLike, theme: ReviewTheme): Text {
+  const content = result.content.find((part) => part.type === "text")?.text ?? "No review output";
+  return new Text(theme.fg("dim", content), 0, 0);
+}