@mrclrchtr/supi-review 2.8.0 → 3.1.0

package/src/types.ts

@@ -1,292 +1,100 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { ChildLifecycleTrace } from "./tool/child-lifecycle-trace.ts";
 
-/** Closed, host-owned classification for a managed child failure. */
-export type ChildFailureCode =
-  | "session-creation-failed"
-  | "prompt-rejected"
-  | "missing-structured-output"
-  | "unexpected-runner-failure";
-
-/** Managed child role used for host-owned failure copy. */
-export type ChildStage = "brief-synthesis" | "reviewer";
-
-/** Failed child result fields with diagnostics required exactly when a child was observed. */
-export type ChildFailedResult =
-  | { failureCode: "session-creation-failed"; diagnostics?: never }
-  | {
-      failureCode: Exclude<ChildFailureCode, "session-creation-failed">;
-      diagnostics: ChildFailureDiagnostics;
-    };
-
-/** Inclusive 1-based line range reported by the reviewer. */
-export interface ReviewLineRange {
-  start: number;
-  end: number;
-}
-
-/** File location reported by the reviewer. */
-export interface ReviewCodeLocation {
-  absolute_file_path: string;
-  line_range: ReviewLineRange;
-}
-
-export type ReviewItemCategory =
-  | "correctness"
-  | "security"
-  | "performance"
-  | "api"
-  | "test-gap"
-  | "docs"
-  | "cleanup"
-  | "maintainer";
+/** A full hexadecimal Git commit object id supplied by an agent caller. */
+export type CommitId = string;
 
-export type ReviewItemImpact = "low" | "medium" | "high";
-export type ReviewItemEffort = "low" | "medium" | "high";
-export type ReviewItemRecommendedAction = "must-fix" | "should-fix" | "consider";
-export type ReviewOverallCorrectness = "PATCH IS CORRECT" | "PATCH HAS ISSUES";
-
-/** Structured review item returned by the reviewer session. */
-export interface ReviewItem {
-  title: string;
-  body: string;
-  category: ReviewItemCategory;
-  impact: ReviewItemImpact;
-  effort: ReviewItemEffort;
-  recommended_action: ReviewItemRecommendedAction;
-  confidence_score: number;
-  suggested_fix: string;
-  verification_hint: string;
-  code_location?: ReviewCodeLocation;
-}
-
-/** Raw review payload submitted by the reviewer child session. */
-export interface ReviewOutputEvent {
-  items: ReviewItem[];
-  overall_explanation: string;
-  overall_confidence_score: number;
-}
-
-export interface ReviewSummary {
-  actions: {
-    mustFix: number;
-    shouldFix: number;
-    consider: number;
-  };
-  categories: Partial<Record<ReviewItemCategory, number>>;
-}
-
-/** Host-normalized review payload used for rendering and follow-up flow. */
-export interface NormalizedReviewOutput extends ReviewOutputEvent {
-  overall_correctness: ReviewOverallCorrectness;
-  summary: ReviewSummary;
-}
-
-/** User-selected review target. */
+/** The Git change selected for review. */
 export type ReviewTargetSpec =
   | { kind: "working-tree" }
-  | { kind: "branch"; base: string }
-  | { kind: "commit"; sha: string };
+  | { kind: "comparison"; baseCommit: CommitId }
+  | { kind: "commit"; commit: CommitId };
+
+/** Resolved identity of a selected review target. */
+export type ResolvedReviewTarget =
+  | { kind: "working-tree"; headCommit: CommitId }
+  | {
+      kind: "comparison";
+      requestedBaseCommit: CommitId;
+      mergeBaseCommit: CommitId;
+      headCommit: CommitId;
+    }
+  | { kind: "commit"; commit: CommitId; parentCommit?: CommitId };
 
-/** Diff statistics for a resolved snapshot. */
 export interface DiffStats {
   files: number;
   additions: number;
   deletions: number;
 }
 
-/** Concrete git snapshot resolved before synthesis/review starts. */
+/** Concrete target metadata and diff resolved before reviewer execution. */
 export interface ReviewSnapshot {
-  target: ReviewTargetSpec;
+  requestedTarget: ReviewTargetSpec;
+  target: ResolvedReviewTarget;
   title: string;
   changedFiles: string[];
   diffText: string;
   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;
-
-/** Structured brief synthesized from the current session history. */
-export type ReviewInstructionBlockId =
-  | "public-surface"
-  | "cross-layer"
-  | "schema-widening"
-  | "cleanup";
-
-export interface SynthesizedReviewBrief {
-  summary: string;
-  intendedOutcome: string;
-  constraints: string[];
-  focusAreas: string[];
-  riskyFiles: string[];
-  unresolvedQuestions: string[];
-  reviewInstructionBlockIds: ReviewInstructionBlockId[];
-  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 {
+/** One independent caller-defined review objective. */
+export interface ReviewTask {
   id: string;
-  focus: string;
+  instructions: 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;
+/** Semantic input shared with the reviewer tasks in one run. */
+export interface ReviewInput {
+  sharedContext?: string;
+  tasks: ReviewTask[];
 }
 
-/** Normalized reviewer result without repeated snapshot or brief payloads. */
-export type AgentReviewerResult =
-  | {
-      kind: "success";
-      output: NormalizedReviewOutput;
-      modelId: string;
-    }
-  | ({ kind: "failed"; modelId: string } & ChildFailedResult)
-  | {
-      kind: "canceled";
-      modelId: string;
-      diagnostics: ChildFailureDiagnostics;
-    }
-  | {
-      kind: "timeout";
-      timeoutMs: number;
-      modelId: string;
-      diagnostics: ChildFailureDiagnostics;
-    };
+/** Advisory review input generated by the optional lightweight Planner. */
+export type PlannerDraft = ReviewInput;
 
-/** One normalized result from a focused reviewer child session. */
-export interface ReviewerAssignmentResult {
-  assignment: ReviewerAssignment;
-  result: AgentReviewerResult;
-}
+export type FindingImpact = "low" | "medium" | "high";
+export type FindingEffort = "small" | "medium" | "large";
+export type TaskVerdict = "pass" | "issues";
 
-/** Structured details retained on a completed agent-driven review batch. */
-export interface AgentReviewBatchDetails {
-  kind: "review-batch";
-  evaluation: BriefEvaluation;
-  snapshot: ReviewSnapshotSummary;
-  results: ReviewerAssignmentResult[];
+export interface ReviewLocation {
+  path: string;
+  startLine: number;
+  endLine: number;
 }
 
-/** 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;
+/** One structured issue submitted by a reviewer task. */
+export interface ReviewFinding {
+  title: string;
+  description: string;
+  blocksAcceptance: boolean;
+  impact: FindingImpact;
+  effort: FindingEffort;
+  confidence: number;
+  location?: ReviewLocation;
 }
 
-/** Final prompt packet passed to the reviewer child session. */
-export interface ReviewPacket {
-  prompt: string;
-  includedFiles: string[];
-  omittedFiles: string[];
-  charBudget: number;
+/** Fixed Review Engine-owned submission grammar. */
+export interface ReviewSubmission {
+  summary: string;
+  findings: ReviewFinding[];
 }
 
-/** Fully prepared review run. */
-export interface ReviewPlan {
-  model: ReviewModelSelection;
-  snapshot: ReviewSnapshot;
-  brief: SynthesizedReviewBrief;
-  packet: ReviewPacket;
+export interface NormalizedReviewSubmission extends ReviewSubmission {
+  verdict: TaskVerdict;
 }
 
-/** Raw result of the review child session. */
-export type RawReviewResult =
-  | {
-      kind: "success";
-      output: ReviewOutputEvent;
-      snapshot: ReviewSnapshot;
-      brief?: SynthesizedReviewBrief;
-      modelId: string;
-    }
-  | ({
-      kind: "failed";
-      snapshot: ReviewSnapshot;
-      brief?: SynthesizedReviewBrief;
-      modelId: string;
-    } & ChildFailedResult)
-  | {
-      kind: "canceled";
-      snapshot: ReviewSnapshot;
-      brief?: SynthesizedReviewBrief;
-      modelId: string;
-      diagnostics: ChildFailureDiagnostics;
-    }
-  | {
-      kind: "timeout";
-      snapshot: ReviewSnapshot;
-      timeoutMs: number;
-      brief?: SynthesizedReviewBrief;
-      modelId: string;
-      diagnostics: ChildFailureDiagnostics;
-    };
+export type ReviewModelSelection = import("@mrclrchtr/supi-core/model-selection").ModelSelection;
 
-/** Normalized result used by rendering and follow-up logic. */
-export type ReviewResult =
-  | {
-      kind: "success";
-      output: NormalizedReviewOutput;
-      snapshot: ReviewSnapshot;
-      brief?: SynthesizedReviewBrief;
-      modelId: string;
-    }
-  | Extract<RawReviewResult, { kind: "failed" | "canceled" | "timeout" }>;
+export type ChildStage = "planner" | "reviewer";
+
+export type ChildFailureCode =
+  | "session-creation-failed"
+  | "prompt-rejected"
+  | "missing-structured-output"
+  | "unexpected-runner-failure";
 
-/**
- * Safe bounded diagnostics attached only to a non-success managed child run.
- *
- * The trace and Recent Activity lane contain only allowlisted control metadata;
- * no child-generated text, caught error, or raw SDK event is retained.
- */
 export interface ChildFailureDiagnostics {
   lifecycleTrace: ChildLifecycleTrace;
   turns: number;
@@ -301,15 +109,22 @@ export interface ChildFailureDiagnostics {
   recentActivity?: string[];
   lastAssistantStopReason?: string;
   lastAssistantToolCalls?: string[];
+  /** Error text extracted from the last assistant message when stopReason is "error". */
+  lastAssistantErrorText?: string;
+  /** Error text extracted from the most recent lifecycle event (compaction_end, auto_retry_end). */
+  lastLifecycleErrorText?: string;
 }
 
-/** Progress state exposed by review/synthesis runners for widget integration. */
+export type ChildFailedResult =
+  | { failureCode: "session-creation-failed"; diagnostics?: never }
+  | {
+      failureCode: Exclude<ChildFailureCode, "session-creation-failed">;
+      diagnostics: ChildFailureDiagnostics;
+    };
+
 export interface ReviewProgress {
-  /** Number of agent turns completed. */
   turns: number;
-  /** Number of tool executions started. */
   toolUses: number;
-  /** Token usage stats, if available. */
   tokens?: {
     input: number;
     output: number;
@@ -317,42 +132,109 @@ export interface ReviewProgress {
     cacheRead?: number;
     cacheWrite?: number;
   };
-  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
   toolCounts?: Record<string, number>;
-  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
-  filesInspected?: number;
-  /** Total files in the review snapshot. */
-  filesTotal?: number;
-  /** Current tool + context for the progress narrative line. */
   currentFocus?: { label: string; detail: string };
-  /** Elapsed time in milliseconds since the operation started. */
   elapsedMs?: number;
 }
 
-export type BriefSynthesisRunResult =
-  | { kind: "success"; brief: SynthesizedReviewBrief }
-  | ({ kind: "failed" } & ChildFailedResult)
-  | { kind: "canceled"; diagnostics: ChildFailureDiagnostics }
-  | { kind: "timeout"; timeoutMs: number; diagnostics: ChildFailureDiagnostics };
-
-export interface BriefSynthesisInvocation {
+export interface PlannerInvocation {
   prompt: string;
-  // biome-ignore lint/suspicious/noExplicitAny: Model<any> is pi's canonical type
+  // biome-ignore lint/suspicious/noExplicitAny: Model<any> is Pi's canonical type
   model: Model<any>;
   cwd: string;
   signal?: AbortSignal;
-  timeoutMs?: number;
   onProgress?: (progress: ReviewProgress) => void;
 }
 
-export interface ReviewInvocation {
+export type PlannerRunResult =
+  | { kind: "success"; draft: PlannerDraft }
+  | ({ kind: "failed" } & ChildFailedResult)
+  | { kind: "canceled"; diagnostics: ChildFailureDiagnostics }
+  | { kind: "timeout"; timeoutMs: number; diagnostics: ChildFailureDiagnostics };
+
+export interface ReviewerInvocation {
   prompt: string;
+  task: ReviewTask;
   model: ReviewModelSelection;
   cwd: string;
-  signal?: AbortSignal;
   snapshot: ReviewSnapshot;
-  brief: SynthesizedReviewBrief;
-  timeoutMs?: number;
-  onToolActivity?: (event: { toolName: string; phase: "start" | "end" }) => void;
+  signal?: AbortSignal;
   onProgress?: (progress: ReviewProgress) => void;
 }
+
+export type ReviewerRunResult =
+  | { kind: "success"; submission: ReviewSubmission; modelId: string }
+  | ({ kind: "failed"; modelId: string } & ChildFailedResult)
+  | { kind: "canceled"; modelId: string; diagnostics: ChildFailureDiagnostics }
+  | {
+      kind: "timeout";
+      timeoutMs: number;
+      modelId: string;
+      diagnostics: ChildFailureDiagnostics;
+    };
+
+interface ReviewTaskResultIdentity {
+  taskId: string;
+  modelId: string;
+  /** SHA-256 of the exact reviewer packet bytes. */
+  packetHash: string;
+}
+
+export type ReviewTaskResult = ReviewTaskResultIdentity &
+  (
+    | {
+        status: "completed";
+        verdict: TaskVerdict;
+        summary: string;
+        findings: ReviewFinding[];
+      }
+    | {
+        status: "failed";
+        failureCode: ChildFailureCode;
+        diagnostics?: ChildFailureDiagnostics;
+      }
+    | {
+        status: "canceled";
+        diagnostics: ChildFailureDiagnostics;
+      }
+    | {
+        status: "timeout";
+        timeoutMs: number;
+        diagnostics: ChildFailureDiagnostics;
+      }
+  );
+
+export interface PlanningRecord {
+  promptVersion: string;
+  modelId: string;
+  draft: PlannerDraft;
+  effectiveReview: ReviewInput;
+  decision: "accept-draft" | "use-review";
+}
+
+export interface ReviewBatchDetails {
+  kind: "review-batch";
+  mode: "direct" | "prepared";
+  provenance: "caller-supplied" | "planner-assisted";
+  snapshot: ReviewSnapshotSummary;
+  review: ReviewInput;
+  planning?: PlanningRecord;
+  results: ReviewTaskResult[];
+}
+
+export interface PreparedReviewDetails {
+  kind: "review-prepared";
+  planId: string;
+  snapshot: ReviewSnapshotSummary;
+  reviewerModelId: string;
+  plannerDraft?: PlannerDraft;
+  plannerModelId?: string;
+  plannerPromptVersion?: string;
+}
+
+export interface ReviewPacket {
+  prompt: string;
+  /** SHA-256 of prompt encoded as UTF-8, used to verify adapter parity. */
+  packetHash: string;
+  taskId: string;
+}

package/src/history/synthesize.ts

@@ -1,121 +0,0 @@
-import { listReviewInstructionBlocks } from "../target/packet.ts";
-import { runBriefSynthesis } from "../tool/brief-runner.ts";
-import type {
-  BriefSynthesisRunResult,
-  ReviewModelSelection,
-  ReviewProgress,
-  ReviewSnapshot,
-} from "../types.ts";
-
-const DIFF_EXCERPT_CHAR_BUDGET = 12_000;
-
-/** Version of the brief-synthesis prompt contract retained in evaluation artifacts. */
-export const BRIEF_SYNTHESIS_PROMPT_VERSION = "1";
-
-export interface SynthesizeReviewBriefOptions {
-  model: ReviewModelSelection;
-  cwd: string;
-  snapshot: ReviewSnapshot;
-  serializedContext: string;
-  note?: string;
-  signal?: AbortSignal;
-  onProgress?: (progress: ReviewProgress) => void;
-}
-
-/** Synthesize a structured review brief from the current snapshot and session context. */
-export function synthesizeReviewBrief(
-  options: SynthesizeReviewBriefOptions,
-): Promise<BriefSynthesisRunResult> {
-  const { model, cwd, snapshot, serializedContext, note, signal, onProgress } = options;
-
-  return runBriefSynthesis({
-    prompt: buildBriefSynthesisPrompt(snapshot, serializedContext, note),
-    model: model.model,
-    cwd,
-    signal,
-    onProgress,
-  });
-}
-
-export function buildBriefSynthesisPrompt(
-  snapshot: ReviewSnapshot,
-  serializedContext: string,
-  note?: string,
-): string {
-  const diffExcerpt = buildDiffExcerpt(snapshot.diffText);
-  const instructionBlocks = listReviewInstructionBlocks();
-  const parts: string[] = [
-    "# Review Brief Synthesis Input",
-    "",
-    "You are preparing a review brief for a second code-reviewing agent.",
-    "Infer the likely goal, constraints, and focus areas from the active session history.",
-    "Be concise, evidence-based, and avoid inventing requirements that are not supported by the input.",
-    "",
-    "## Snapshot",
-    `Target: ${snapshot.title}`,
-    `Files changed: ${snapshot.changedFiles.length}`,
-    `Diff stats: +${snapshot.stats.additions} / -${snapshot.stats.deletions}`,
-    "",
-    "### Changed files",
-    ...snapshot.changedFiles.map((file) => `- ${file}`),
-  ];
-
-  if (diffExcerpt.text) {
-    parts.push("", "### Diff excerpt", "```diff", diffExcerpt.text, "```");
-    if (diffExcerpt.truncated) {
-      parts.push(`> Note: diff excerpt truncated to ${diffExcerpt.text.length} characters.`);
-    }
-  }
-
-  if (instructionBlocks.length > 0) {
-    parts.push(
-      "",
-      "## Available review instruction blocks",
-      ...instructionBlocks.map((block) => `- ${block.id}: ${block.title} — ${block.instruction}`),
-    );
-  }
-
-  if (note?.trim()) {
-    parts.push("", "## User note", note.trim());
-  }
-
-  parts.push("", "## Serialized session context");
-  if (serializedContext.trim()) {
-    parts.push(serializedContext.trim());
-  } else {
-    parts.push("No session context was available. Derive the brief from the snapshot only.");
-  }
-
-  parts.push(
-    "",
-    "## Output requirements",
-    "Call submit_review_brief with:",
-    "- summary: one-sentence summary of the likely change",
-    "- intendedOutcome: what the session seems to be trying to achieve",
-    "- constraints: invariants or requirements to preserve",
-    "- focusAreas: what the reviewer should inspect carefully",
-    "- riskyFiles: changed files that seem especially important or risky.",
-    "  Prioritize files touching auth, data handling, core logic, error handling, or public APIs.",
-    "  Include only files from the changed-files list above.",
-    "- unresolvedQuestions: ambiguities or concerns that remain unclear",
-    "- reviewInstructionBlockIds: zero or more IDs from the available review instruction block catalog",
-    "  Select only blocks that are clearly supported by the supplied session/snapshot evidence.",
-    "  Prefer omission over guessing. Do not invent new IDs.",
-  );
-
-  return parts.join("\n");
-}
-
-function buildDiffExcerpt(diffText: string): { text: string; truncated: boolean } {
-  const trimmed = diffText.trim();
-  if (!trimmed) {
-    return { text: "", truncated: false };
-  }
-  if (trimmed.length <= DIFF_EXCERPT_CHAR_BUDGET) {
-    return { text: trimmed, truncated: false };
-  }
-  return {
-    text: `${trimmed.slice(0, DIFF_EXCERPT_CHAR_BUDGET)}\n[... diff excerpt truncated ...]`,
-    truncated: true,
-  };
-}