@mrclrchtr/supi-review 2.4.1 → 2.6.0

package/src/tool/agent-review-workflow.ts

@@ -0,0 +1,385 @@
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import {
+  checkReviewSnapshotFreshness,
+  fingerprintReviewSnapshot,
+  resolveReviewSnapshot,
+  summarizeReviewSnapshot,
+} from "../git.ts";
+import { BRIEF_SYNTHESIS_PROMPT_VERSION, synthesizeReviewBrief } from "../history/synthesize.ts";
+import { normalizeReviewResult } from "../review-result.ts";
+import type { ReviewPlanStore, StoredAgentReviewPlan } from "../session/review-plan-store.ts";
+import { buildReviewPacket } from "../target/packet.ts";
+import type {
+  AgentReviewBatchDetails,
+  AgentReviewerResult,
+  BriefCritique,
+  BriefEvaluation,
+  BriefSynthesisRunResult,
+  ReviewerAssignment,
+  ReviewerAssignmentResult,
+  ReviewModelSelection,
+  ReviewProgress,
+  ReviewResult,
+  ReviewTargetSpec,
+  SynthesizedReviewBrief,
+} from "../types.ts";
+import { runReviewer } from "./review-runner.ts";
+
+/** Inputs required to synthesize and retain one agent-driven review plan. */
+export interface PrepareAgentReviewWorkflowInput {
+  cwd: string;
+  target: ReviewTargetSpec;
+  note?: string;
+  serializedContext: string;
+  model: ReviewModelSelection;
+  modelRegistry: ModelRegistry;
+  signal?: AbortSignal;
+  onProgress?: (progress: ReviewProgress) => void;
+  planStore: ReviewPlanStore;
+}
+
+/** Typed preparation outcome before any reviewer child session starts. */
+export type PrepareAgentReviewWorkflowOutcome =
+  | { kind: "prepared"; plan: StoredAgentReviewPlan }
+  | { kind: "no-snapshot"; reason: string }
+  | { kind: "synthesis-failed"; result: Exclude<BriefSynthesisRunResult, { kind: "success" }> };
+
+/** Inputs required to critique and execute one prepared review plan. */
+export interface RunAgentReviewWorkflowInput {
+  cwd: string;
+  planId: string;
+  critique: BriefCritique;
+  revisedBrief?: Omit<SynthesizedReviewBrief, "note">;
+  reviewers: ReviewerAssignment[];
+  modelRegistry: ModelRegistry;
+  signal?: AbortSignal;
+  onBriefEvaluation?: (evaluation: BriefEvaluation) => void;
+  onReviewerProgress?: (reviewerId: string, progress: ReviewProgress) => void;
+  onReviewerDone?: (reviewerId: string) => void;
+  planStore: ReviewPlanStore;
+}
+
+/** Typed batch outcome after validation and snapshot freshness checks. */
+export type RunAgentReviewWorkflowOutcome =
+  | { kind: "completed"; details: AgentReviewBatchDetails }
+  | { kind: "invalid"; reason: string }
+  | { kind: "stale"; reason: string };
+
+/** Prepare one session-scoped review plan without starting reviewer sessions. */
+export async function prepareAgentReviewPlan(
+  input: PrepareAgentReviewWorkflowInput,
+): Promise<PrepareAgentReviewWorkflowOutcome> {
+  const snapshot = await resolveReviewSnapshot(input.cwd, input.target);
+  if (!snapshot) {
+    return {
+      kind: "no-snapshot",
+      reason: `No reviewable changes found for ${formatTarget(input.target)}.`,
+    };
+  }
+
+  const synthesis = await synthesizeReviewBrief({
+    model: input.model,
+    modelRegistry: input.modelRegistry,
+    cwd: input.cwd,
+    snapshot,
+    serializedContext: input.serializedContext,
+    note: input.note,
+    signal: input.signal,
+    onProgress: input.onProgress,
+  });
+  if (synthesis.kind !== "success") {
+    return { kind: "synthesis-failed", result: synthesis };
+  }
+
+  const generatedBrief: SynthesizedReviewBrief = {
+    ...synthesis.brief,
+    note: input.note,
+  };
+  const snapshotFingerprint = await fingerprintReviewSnapshot(input.cwd, snapshot, input.signal);
+  const plan = input.planStore.create({
+    snapshot,
+    snapshotFingerprint,
+    generatedBrief,
+    model: input.model,
+    briefPromptVersion: BRIEF_SYNTHESIS_PROMPT_VERSION,
+  });
+  return { kind: "prepared", plan };
+}
+
+/** Validate, atomically consume, freshness-check, and execute one prepared review batch. */
+export async function runAgentReviewBatch(
+  input: RunAgentReviewWorkflowInput,
+): Promise<RunAgentReviewWorkflowOutcome> {
+  const plan = input.planStore.get(input.planId);
+  if (!plan) {
+    return {
+      kind: "invalid",
+      reason: `Review plan "${input.planId}" was not found in this session.`,
+    };
+  }
+
+  const validation = validateRunInput(input, plan);
+  if (validation.kind === "invalid") return validation;
+
+  const claimedPlan = input.planStore.take(input.planId);
+  if (!claimedPlan) {
+    return {
+      kind: "invalid",
+      reason: `Review plan "${input.planId}" has already been consumed.`,
+    };
+  }
+
+  const evaluation: BriefEvaluation = {
+    planId: claimedPlan.id,
+    briefPromptVersion: claimedPlan.briefPromptVersion,
+    generatedBrief: claimedPlan.generatedBrief,
+    critique: validation.critique,
+    effectiveBrief: validation.effectiveBrief,
+    synthesizerModelId: claimedPlan.model.canonicalId,
+    snapshotFingerprint: claimedPlan.snapshotFingerprint,
+  };
+  input.onBriefEvaluation?.(evaluation);
+
+  const freshness = await checkReviewSnapshotFreshness(
+    input.cwd,
+    claimedPlan.snapshot,
+    claimedPlan.snapshotFingerprint,
+    input.signal,
+  );
+  if (!freshness.fresh) return { kind: "stale", reason: freshness.reason };
+
+  const results = await Promise.all(
+    validation.reviewers.map(async (assignment) => {
+      const result = await runAssignment(assignment, claimedPlan, validation.effectiveBrief, input);
+      input.onReviewerDone?.(assignment.id);
+      return result;
+    }),
+  );
+
+  const finalFreshness = await checkReviewSnapshotFreshness(
+    input.cwd,
+    claimedPlan.snapshot,
+    claimedPlan.snapshotFingerprint,
+    input.signal,
+  );
+  if (!finalFreshness.fresh) {
+    return {
+      kind: "stale",
+      reason: "The review target changed while reviewer sessions were running. Prepare a new plan.",
+    };
+  }
+
+  return {
+    kind: "completed",
+    details: {
+      kind: "review-batch",
+      evaluation,
+      snapshot: summarizeReviewSnapshot(claimedPlan.snapshot),
+      results,
+    },
+  };
+}
+
+async function runAssignment(
+  assignment: ReviewerAssignment,
+  plan: StoredAgentReviewPlan,
+  effectiveBrief: SynthesizedReviewBrief,
+  input: RunAgentReviewWorkflowInput,
+): Promise<ReviewerAssignmentResult> {
+  const packet = buildReviewPacket(plan.snapshot, effectiveBrief, plan.model, assignment);
+
+  try {
+    const rawResult = await runReviewer({
+      prompt: packet.prompt,
+      model: plan.model,
+      modelRegistry: input.modelRegistry,
+      cwd: input.cwd,
+      signal: input.signal,
+      snapshot: plan.snapshot,
+      brief: effectiveBrief,
+      onProgress: (progress) => input.onReviewerProgress?.(assignment.id, progress),
+    });
+    return { assignment, result: compactReviewResult(normalizeReviewResult(rawResult)) };
+  } catch (error) {
+    return {
+      assignment,
+      result: {
+        kind: "failed",
+        reason: `Reviewer session failed unexpectedly: ${error instanceof Error ? error.message : String(error)}`,
+        modelId: plan.model.canonicalId,
+      },
+    };
+  }
+}
+
+function compactReviewResult(result: ReviewResult): AgentReviewerResult {
+  switch (result.kind) {
+    case "success":
+      return { kind: "success", output: result.output, modelId: result.modelId };
+    case "failed":
+      return {
+        kind: "failed",
+        reason: result.reason,
+        modelId: result.modelId,
+        debug: result.debug,
+      };
+    case "canceled":
+      return { kind: "canceled", modelId: result.modelId, debug: result.debug };
+    case "timeout":
+      return {
+        kind: "timeout",
+        timeoutMs: result.timeoutMs,
+        partialOutput: result.partialOutput,
+        modelId: result.modelId,
+        debug: result.debug,
+      };
+  }
+}
+
+function validateRunInput(
+  input: RunAgentReviewWorkflowInput,
+  plan: StoredAgentReviewPlan,
+):
+  | {
+      kind: "valid";
+      critique: BriefCritique;
+      effectiveBrief: SynthesizedReviewBrief;
+      reviewers: ReviewerAssignment[];
+    }
+  | { kind: "invalid"; reason: string } {
+  if (input.critique.verdict === "revise" && !input.revisedBrief) {
+    return {
+      kind: "invalid",
+      reason: 'revisedBrief is required when critique.verdict is "revise".',
+    };
+  }
+  if (input.critique.verdict === "accept" && input.revisedBrief) {
+    return {
+      kind: "invalid",
+      reason: 'revisedBrief must be omitted when critique.verdict is "accept".',
+    };
+  }
+
+  const critiqueResult = normalizeBriefCritique(input.critique);
+  if (critiqueResult.kind === "invalid") return critiqueResult;
+  const critique = critiqueResult.critique;
+
+  if (input.reviewers.length < 1 || input.reviewers.length > 4) {
+    return { kind: "invalid", reason: "Provide between one and four reviewer assignments." };
+  }
+
+  const reviewers = input.reviewers.map((assignment) => ({
+    id: assignment.id.trim(),
+    focus: assignment.focus.trim(),
+  }));
+  const invalidAssignment = reviewers.find((assignment) => !assignment.id || !assignment.focus);
+  if (invalidAssignment) {
+    return { kind: "invalid", reason: "Reviewer ids and focus instructions must not be blank." };
+  }
+  const ids = new Set(reviewers.map((assignment) => assignment.id));
+  if (ids.size !== reviewers.length) {
+    return { kind: "invalid", reason: "Reviewer assignment ids must be unique." };
+  }
+
+  const effectiveBriefResult = input.revisedBrief
+    ? normalizeRevisedBrief(input.revisedBrief, plan.generatedBrief.note)
+    : { kind: "valid" as const, brief: plan.generatedBrief };
+  if (effectiveBriefResult.kind === "invalid") return effectiveBriefResult;
+  const effectiveBrief = effectiveBriefResult.brief;
+  const invalidRiskyFile = effectiveBrief.riskyFiles.find(
+    (file) => !plan.snapshot.changedFiles.includes(file),
+  );
+  if (invalidRiskyFile) {
+    return {
+      kind: "invalid",
+      reason: `Revised brief riskyFiles contains "${invalidRiskyFile}", which is not in the prepared snapshot.`,
+    };
+  }
+
+  return { kind: "valid", critique, effectiveBrief, reviewers };
+}
+
+function normalizeBriefCritique(
+  input: BriefCritique,
+): { kind: "valid"; critique: BriefCritique } | { kind: "invalid"; reason: string } {
+  if (input.findings.length > 20) {
+    return { kind: "invalid", reason: "Brief critique supports at most 20 findings." };
+  }
+  if (input.verdict === "revise" && input.findings.length === 0) {
+    return {
+      kind: "invalid",
+      reason: 'critique.findings must contain evidence when critique.verdict is "revise".',
+    };
+  }
+
+  const critique: BriefCritique = {
+    verdict: input.verdict,
+    summary: input.summary.trim(),
+    findings: input.findings.map((finding) => ({
+      ...finding,
+      explanation: finding.explanation.trim(),
+      evidence: finding.evidence.trim(),
+      proposedChange: finding.proposedChange.trim(),
+    })),
+  };
+  if (!critique.summary) {
+    return { kind: "invalid", reason: "Brief critique summary must not be blank." };
+  }
+  if (
+    critique.findings.some(
+      (finding) => !finding.explanation || !finding.evidence || !finding.proposedChange,
+    )
+  ) {
+    return { kind: "invalid", reason: "Brief critique findings must contain non-blank text." };
+  }
+  return { kind: "valid", critique };
+}
+
+function normalizeRevisedBrief(
+  brief: Omit<SynthesizedReviewBrief, "note">,
+  note: string | undefined,
+): { kind: "valid"; brief: SynthesizedReviewBrief } | { kind: "invalid"; reason: string } {
+  const summary = brief.summary.trim();
+  const intendedOutcome = brief.intendedOutcome.trim();
+  if (!summary || !intendedOutcome) {
+    return {
+      kind: "invalid",
+      reason: "revisedBrief.summary and revisedBrief.intendedOutcome must not be blank.",
+    };
+  }
+
+  const constraints = brief.constraints.map((item) => item.trim());
+  const focusAreas = brief.focusAreas.map((item) => item.trim());
+  const riskyFiles = brief.riskyFiles.map((item) => item.trim());
+  const unresolvedQuestions = brief.unresolvedQuestions.map((item) => item.trim());
+  if (
+    [...constraints, ...focusAreas, ...riskyFiles, ...unresolvedQuestions].some((item) => !item)
+  ) {
+    return { kind: "invalid", reason: "revisedBrief arrays must not contain blank entries." };
+  }
+
+  return {
+    kind: "valid",
+    brief: {
+      summary,
+      intendedOutcome,
+      constraints,
+      focusAreas,
+      riskyFiles,
+      unresolvedQuestions,
+      reviewInstructionBlockIds: [...brief.reviewInstructionBlockIds],
+      note,
+    },
+  };
+}
+
+function formatTarget(target: ReviewTargetSpec): string {
+  switch (target.kind) {
+    case "working-tree":
+      return "the working tree";
+    case "branch":
+      return `changes against ${target.base}`;
+    case "commit":
+      return `commit ${target.sha}`;
+  }
+}

package/src/tool/brief-runner.ts

@@ -1,7 +1,6 @@
 import { clampThinkingLevel } from "@earendil-works/pi-ai";
 import {
   type AgentSession,
-  type AgentSessionEvent,
   createAgentSession,
   DefaultResourceLoader,
   defineTool,
@@ -88,16 +87,15 @@ function emitBriefProgress(
   invocation.onProgress?.(ctx.progress);
 }
 
-function handleAgentEnd(options: {
-  event: Extract<AgentSessionEvent, { type: "agent_end" }>;
+/** Finalize after retries and compaction recovery, never at the earlier `agent_end` boundary. */
+function handleAgentSettled(options: {
   session: AgentSession;
   brief: SynthesizedReviewBrief | undefined;
   state: { settled: boolean; aborting: boolean };
   cleanup: (result: BriefSynthesisRunResult) => BriefSynthesisRunResult;
 }): BriefSynthesisRunResult | undefined {
-  const { event, session, brief, state, cleanup } = options;
-  const retryAwareEvent = event as typeof event & { willRetry?: boolean };
-  if (retryAwareEvent.willRetry || state.settled || state.aborting) {
+  const { session, brief, state, cleanup } = options;
+  if (state.settled || state.aborting) {
     return undefined;
   }
   if (brief) {
@@ -156,9 +154,8 @@ export async function runBriefSynthesis(
           ctx.progress.currentFocus = undefined;
           emitBriefProgress(ctx, invocation);
           break;
-        case "agent_end": {
-          const result = handleAgentEnd({
-            event,
+        case "agent_settled": {
+          const result = handleAgentSettled({
             session,
             brief: resultHolder.value,
             state: ctx.state,

package/src/tool/guidance.ts

@@ -0,0 +1,21 @@
+export const PREPARE_REVIEW_TOOL_NAME = "supi_review_prepare";
+export const RUN_REVIEW_TOOL_NAME = "supi_review_run";
+
+export const prepareReviewToolDescription =
+  "Prepare a session-aware review brief for a freshness-checked git target and return a session-scoped planId. " +
+  "After this tool returns, critically compare the generated brief with the user request, session evidence, and snapshot before calling supi_review_run. Does not run reviewers.";
+
+export const prepareReviewPromptSnippet =
+  "Prepare a session-aware review plan for main-agent critique before independent reviewers run";
+
+export const prepareReviewPromptGuidelines = [
+  "Use supi_review_prepare when an independent review is useful; do not combine it in the same tool batch with edit, write, or mutating bash calls.",
+  "After supi_review_prepare, assess the generated brief for omissions, unsupported inferences, misplaced priorities, and unclear wording, then call supi_review_run with an evidence-backed critique.",
+  "Do not mutate the review target between supi_review_prepare and supi_review_run, and call supi_review_run without sibling mutation tools; stale or mid-review changes are rejected.",
+];
+
+export const runReviewToolDescription =
+  "Run one to four independent read-only reviewer child sessions from a prepared plan. " +
+  "Requires the planId from supi_review_prepare and a structured main-agent critique. " +
+  'When critique.verdict is "revise", revisedBrief must contain the full corrected brief. ' +
+  "The prepared snapshot is freshness-checked and the plan is consumed once execution begins.";

package/src/tool/review-debug.ts

@@ -77,6 +77,8 @@ export function summarizeSessionEvent(event: AgentSessionEvent): string | undefi
       return "turn:end";
     case "agent_end":
       return `agent:end${event.willRetry ? ":retry" : ""}`;
+    case "agent_settled":
+      return "agent:settled";
     case "auto_retry_start":
       return `retry:start:${event.attempt}/${event.maxAttempts}`;
     case "auto_retry_end":

package/src/tool/review-handlers.ts

@@ -236,13 +236,12 @@ export function handleMessageEnd(
   ctx.session.steer(STEER_SUBMIT_MESSAGE).catch(() => {});
 }
 
-export function handleAgentEnd(
-  event: Extract<AgentSessionEvent, { type: "agent_end" }>,
-  ctx: RunnerContext,
-): void {
+/**
+ * Finalize only after Pi has no retry, compaction recovery, or queued continuation left.
+ * `agent_end` is a low-level boundary and is not terminal for a managed session.
+ */
+export function handleAgentSettled(ctx: RunnerContext): void {
   if (ctx.state.settled || ctx.state.aborting) return;
-  const retryAwareEvent = event as typeof event & { willRetry?: boolean };
-  if (retryAwareEvent.willRetry) return;
 
   if (ctx.resultHolder.value) {
     ctx.resolve(
@@ -293,8 +292,8 @@ export function handleSessionEvent(event: AgentSessionEvent, ctx: RunnerContext)
       handleMessageEnd(event, ctx);
       break;
     }
-    case "agent_end":
-      handleAgentEnd(event, ctx);
+    case "agent_settled":
+      handleAgentSettled(ctx);
       break;
     default:
       break;

package/src/tool/review-runner.ts

@@ -30,7 +30,7 @@ async function createReviewerSession(
   const resourceLoader = new DefaultResourceLoader({
     cwd: invocation.cwd,
     agentDir: process.env.PI_CODING_AGENT_DIR || "",
-    noExtensions: false,
+    noExtensions: true,
     noSkills: true,
     noPromptTemplates: true,
     noThemes: true,

package/src/tool/schemas.ts

@@ -1,40 +1,33 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
-const reviewItemCategorySchema = Type.Union([
-  Type.Literal("correctness"),
-  Type.Literal("security"),
-  Type.Literal("performance"),
-  Type.Literal("api"),
-  Type.Literal("test-gap"),
-  Type.Literal("docs"),
-  Type.Literal("cleanup"),
-  Type.Literal("maintainer"),
-]);
+const reviewItemCategorySchema = StringEnum([
+  "correctness",
+  "security",
+  "performance",
+  "api",
+  "test-gap",
+  "docs",
+  "cleanup",
+  "maintainer",
+] as const);
 
-const reviewItemImpactSchema = Type.Union([
-  Type.Literal("low"),
-  Type.Literal("medium"),
-  Type.Literal("high"),
-]);
+const reviewItemImpactSchema = StringEnum(["low", "medium", "high"] as const);
 
-const reviewItemEffortSchema = Type.Union([
-  Type.Literal("low"),
-  Type.Literal("medium"),
-  Type.Literal("high"),
-]);
+const reviewItemEffortSchema = StringEnum(["low", "medium", "high"] as const);
 
-const reviewItemRecommendedActionSchema = Type.Union([
-  Type.Literal("must-fix"),
-  Type.Literal("should-fix"),
-  Type.Literal("consider"),
-]);
+const reviewItemRecommendedActionSchema = StringEnum([
+  "must-fix",
+  "should-fix",
+  "consider",
+] as const);
 
-const reviewInstructionBlockIdSchema = Type.Union([
-  Type.Literal("public-surface"),
-  Type.Literal("cross-layer"),
-  Type.Literal("schema-widening"),
-  Type.Literal("cleanup"),
-]);
+const reviewInstructionBlockIdSchema = StringEnum([
+  "public-surface",
+  "cross-layer",
+  "schema-widening",
+  "cleanup",
+] as const);
 
 export const reviewItemSchema = Type.Object({
   title: Type.String(),
@@ -63,12 +56,15 @@ export const reviewOutputSchema = Type.Object({
   overall_confidence_score: Type.Number({ minimum: 0, maximum: 1 }),
 });
 
+const briefRequiredTextSchema = Type.String({ minLength: 1, maxLength: 4_000 });
+const briefListItemSchema = Type.String({ minLength: 1, maxLength: 2_000 });
+
 export const reviewBriefSchema = Type.Object({
-  summary: Type.String(),
-  intendedOutcome: Type.String(),
-  constraints: Type.Array(Type.String()),
-  focusAreas: Type.Array(Type.String()),
-  riskyFiles: Type.Array(Type.String()),
-  unresolvedQuestions: Type.Array(Type.String()),
-  reviewInstructionBlockIds: Type.Array(reviewInstructionBlockIdSchema),
+  summary: briefRequiredTextSchema,
+  intendedOutcome: briefRequiredTextSchema,
+  constraints: Type.Array(briefListItemSchema, { maxItems: 50 }),
+  focusAreas: Type.Array(briefListItemSchema, { maxItems: 50 }),
+  riskyFiles: Type.Array(briefListItemSchema, { maxItems: 200 }),
+  unresolvedQuestions: Type.Array(briefListItemSchema, { maxItems: 50 }),
+  reviewInstructionBlockIds: Type.Array(reviewInstructionBlockIdSchema, { maxItems: 4 }),
 });

package/src/tool/session-lifecycle.ts

@@ -17,7 +17,7 @@ export interface LifecycleCtx<TResult> {
   /**
    * Shared lifecycle state.
    * - `settled`: true once cleanup has been called
-   * - `aborting`: true once abort/timeout begins (prevents agent_end from resolving)
+   * - `aborting`: true once abort/timeout begins (prevents agent_settled from resolving)
    */
   state: { settled: boolean; aborting: boolean };
   /** The managed agent session. */
@@ -142,7 +142,7 @@ export function runWithLifecycle<TResult>(
 
     // Abort signal handler
     const onAbort = () => {
-      if (state.settled) return;
+      if (state.settled || state.aborting) return;
       state.aborting = true;
       void session
         .abort()
@@ -154,11 +154,15 @@ export function runWithLifecycle<TResult>(
     if (signal) {
       signal.addEventListener("abort", onAbort, { once: true });
       addTeardown(() => signal.removeEventListener("abort", onAbort));
+      if (signal.aborted) {
+        onAbort();
+        return;
+      }
     }
 
     // Timeout handler
     const onTimeoutExpired = () => {
-      if (state.settled) return;
+      if (state.settled || state.aborting) return;
 
       if (onTimeout) {
         onTimeout(ctx);

package/src/tool/snapshot-tools.ts

@@ -1,3 +1,4 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { getSnapshotFileContent, getSnapshotFileDiff } from "../git.ts";
@@ -70,7 +71,7 @@ export function createSnapshotFileTool(
       '"after" shows the file after the change. The file must be in the snapshot\'s changed-files list.',
     parameters: Type.Object({
       file: Type.String(),
-      side: Type.Union([Type.Literal("before"), Type.Literal("after")]),
+      side: StringEnum(["before", "after"] as const),
     }),
     execute: async (_toolCallId, args) => {
       const { file, side } = args as { file: string; side: "before" | "after" };