@mrclrchtr/supi-review 2.7.0 → 3.0.0

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

@@ -1,398 +0,0 @@
-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 { createUnobservedChildFailureDiagnostics } from "./child-failure-diagnostics.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;
-  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[];
-  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)}.`,
-    };
-  }
-
-  let synthesis: BriefSynthesisRunResult;
-  try {
-    synthesis = await synthesizeReviewBrief({
-      model: input.model,
-      cwd: input.cwd,
-      snapshot,
-      serializedContext: input.serializedContext,
-      note: input.note,
-      signal: input.signal,
-      onProgress: input.onProgress,
-    });
-  } catch {
-    return {
-      kind: "synthesis-failed",
-      result: {
-        kind: "failed",
-        failureCode: "unexpected-runner-failure",
-        diagnostics: createUnobservedChildFailureDiagnostics(),
-      },
-    };
-  }
-  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,
-      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 {
-    return {
-      assignment,
-      result: {
-        kind: "failed",
-        failureCode: "unexpected-runner-failure",
-        modelId: plan.model.canonicalId,
-        diagnostics: createUnobservedChildFailureDiagnostics(),
-      },
-    };
-  }
-}
-
-function compactReviewResult(result: ReviewResult): AgentReviewerResult {
-  switch (result.kind) {
-    case "success":
-      return { kind: "success", output: result.output, modelId: result.modelId };
-    case "failed":
-      return result.failureCode === "session-creation-failed"
-        ? {
-            kind: "failed",
-            failureCode: result.failureCode,
-            modelId: result.modelId,
-          }
-        : {
-            kind: "failed",
-            failureCode: result.failureCode,
-            modelId: result.modelId,
-            diagnostics: result.diagnostics,
-          };
-    case "canceled":
-      return {
-        kind: "canceled",
-        modelId: result.modelId,
-        diagnostics: result.diagnostics,
-      };
-    case "timeout":
-      return {
-        kind: "timeout",
-        timeoutMs: result.timeoutMs,
-        modelId: result.modelId,
-        diagnostics: result.diagnostics,
-      };
-  }
-}
-
-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,180 +0,0 @@
-import { clampThinkingLevel } from "@earendil-works/pi-ai";
-import {
-  type AgentSession,
-  createAgentSession,
-  DefaultResourceLoader,
-  defineTool,
-  SessionManager,
-} from "@earendil-works/pi-coding-agent";
-import type {
-  BriefSynthesisInvocation,
-  BriefSynthesisRunResult,
-  SynthesizedReviewBrief,
-} from "../types.ts";
-import { createEarlyCancellationDiagnostics } from "./child-failure-diagnostics.ts";
-import { buildProgressTokens } from "./runner-helpers.ts";
-import { reviewBriefSchema } from "./schemas.ts";
-import { type LifecycleCtx, runWithLifecycle } from "./session-lifecycle.ts";
-
-const DEFAULT_TIMEOUT_MS = 5 * 60 * 1_000;
-
-function createSubmitBriefTool(resultHolder: {
-  value: SynthesizedReviewBrief | undefined;
-}): ReturnType<typeof defineTool> {
-  return defineTool({
-    name: "submit_review_brief",
-    label: "Submit Review Brief",
-    description: "Submit the synthesized review brief once you have inferred it from the input.",
-    parameters: reviewBriefSchema,
-    execute: async (_toolCallId, args) => {
-      resultHolder.value = {
-        ...(args as Omit<SynthesizedReviewBrief, "note">),
-      };
-      return {
-        content: [{ type: "text" as const, text: "Review brief submitted successfully." }],
-        details: args,
-        terminate: true,
-      };
-    },
-  });
-}
-
-function buildBriefSystemPrompt(): string {
-  return [
-    "You synthesize a compact review brief from session history and snapshot metadata.",
-    "Infer the likely intent, constraints, focus areas, risky files, unresolved questions, and applicable review instruction blocks.",
-    "Use only the supplied input. Do not invent requirements or files.",
-    "If the input is thin, produce a conservative brief instead of guessing.",
-    "Call submit_review_brief with the structured result. Do not emit freeform JSON.",
-  ].join("\n");
-}
-
-async function createBriefSession(
-  invocation: BriefSynthesisInvocation,
-  submitBriefTool: ReturnType<typeof defineTool>,
-): Promise<AgentSession> {
-  const resourceLoader = new DefaultResourceLoader({
-    cwd: invocation.cwd,
-    agentDir: process.env.PI_CODING_AGENT_DIR || "",
-    noExtensions: true,
-    noSkills: true,
-    noPromptTemplates: true,
-    noThemes: true,
-    noContextFiles: true,
-    appendSystemPrompt: [buildBriefSystemPrompt()],
-  });
-  await resourceLoader.reload();
-
-  const { session } = await createAgentSession({
-    cwd: invocation.cwd,
-    model: invocation.model,
-    thinkingLevel: clampThinkingLevel(invocation.model, "max"),
-    tools: ["submit_review_brief"],
-    customTools: [submitBriefTool],
-    resourceLoader,
-    sessionManager: SessionManager.inMemory(invocation.cwd),
-  });
-
-  return session;
-}
-
-function emitBriefProgress(
-  ctx: LifecycleCtx<BriefSynthesisRunResult>,
-  invocation: BriefSynthesisInvocation,
-): void {
-  ctx.progress.tokens = buildProgressTokens(() => ctx.session.getSessionStats());
-  ctx.progress.elapsedMs = Date.now() - ctx.startTime;
-  invocation.onProgress?.(ctx.progress);
-}
-
-/** Finalize after retries and compaction recovery, never at the earlier `agent_end` boundary. */
-function handleAgentSettled(options: {
-  brief: SynthesizedReviewBrief | undefined;
-  state: { settled: boolean; aborting: boolean };
-  cleanup: (result: BriefSynthesisRunResult) => BriefSynthesisRunResult;
-  getFailureDiagnostics: LifecycleCtx<BriefSynthesisRunResult>["getFailureDiagnostics"];
-}): BriefSynthesisRunResult | undefined {
-  const { brief, state, cleanup, getFailureDiagnostics } = options;
-  if (state.settled || state.aborting) return undefined;
-  if (brief) return cleanup({ kind: "success", brief });
-
-  return cleanup({
-    kind: "failed",
-    failureCode: "missing-structured-output",
-    diagnostics: getFailureDiagnostics(),
-  });
-}
-
-/** Run the brief-synthesis child session. */
-export async function runBriefSynthesis(
-  invocation: BriefSynthesisInvocation,
-): Promise<BriefSynthesisRunResult> {
-  if (invocation.signal?.aborted) {
-    return { kind: "canceled", diagnostics: createEarlyCancellationDiagnostics() };
-  }
-
-  const resultHolder: { value: SynthesizedReviewBrief | undefined } = { value: undefined };
-  const submitBriefTool = createSubmitBriefTool(resultHolder);
-
-  let session: AgentSession;
-  try {
-    session = await createBriefSession(invocation, submitBriefTool);
-  } catch {
-    return { kind: "failed", failureCode: "session-creation-failed" };
-  }
-
-  return runWithLifecycle<BriefSynthesisRunResult>({
-    session,
-    prompt: invocation.prompt,
-    signal: invocation.signal,
-    timeoutMs: invocation.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-    onEvent: (event, ctx) => {
-      switch (event.type) {
-        case "turn_end":
-          ctx.progress.turns++;
-          emitBriefProgress(ctx, invocation);
-          break;
-        case "tool_execution_start":
-          ctx.progress.toolUses++;
-          ctx.progress.currentFocus = {
-            label: event.toolName === "submit_review_brief" ? "Submitting brief" : event.toolName,
-            detail: "",
-          };
-          emitBriefProgress(ctx, invocation);
-          break;
-        case "tool_execution_end":
-          ctx.progress.currentFocus = undefined;
-          emitBriefProgress(ctx, invocation);
-          break;
-        case "agent_settled": {
-          const result = handleAgentSettled({
-            brief: resultHolder.value,
-            state: ctx.state,
-            cleanup: ctx.cleanup,
-            getFailureDiagnostics: ctx.getFailureDiagnostics,
-          });
-          if (result) {
-            ctx.resolve(result);
-          }
-          break;
-        }
-        default:
-          break;
-      }
-    },
-    canceledResult: (ctx) => ({
-      kind: "canceled" as const,
-      diagnostics: ctx.getFailureDiagnostics(),
-    }),
-    failedResult: (failureCode, ctx) => ({
-      kind: "failed" as const,
-      failureCode,
-      diagnostics: ctx.getFailureDiagnostics(),
-    }),
-    timeoutResult: (ms, ctx) => ({
-      kind: "timeout" as const,
-      timeoutMs: ms,
-      diagnostics: ctx.getFailureDiagnostics(),
-    }),
-  });
-}

package/src/tool/guidance.ts

@@ -1,21 +0,0 @@
-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.";