@mrclrchtr/supi-review 1.4.0 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @mrclrchtr/supi-review
 
-Adds a guided `/supi-review` command to the [pi coding agent](https://github.com/earendil-works/pi) for structured code review.
+Adds an interactive `/supi-review` command to the [pi coding agent](https://github.com/earendil-works/pi) for session-aware code review.
 
 ## Install
 
@@ -22,58 +22,63 @@ After editing the source, run `/reload`.
 
 After install, pi gets one command:
 
-- `/supi-review` — launch an interactive review flow and render a structured review result
+- `/supi-review` — launch a guided review flow over a concrete git snapshot
 
-The reviewer runs in a managed child agent session with read-only review tools:
+The reviewer runs in managed child agent sessions:
 
-- `read`
-- `grep`
-- `find`
-- `ls`
-- `submit_review` (internal result-submission tool)
+- a **brief synthesizer** creates a structured review brief from the active session branch
+- a **read-only reviewer** inspects the selected snapshot and submits structured findings
 
 ## Review flow
 
 `/supi-review` walks you through:
 
-1. choose a review mode
-2. choose a review target
-3. build a review brief
-4. edit and approve the final review prompt
-5. run the review with a live progress widget
-6. show the result as a structured custom message
-7. optionally trigger an auto-fix follow-up turn
+1. choose a review target
+2. choose the reviewer model
+3. optionally add a short note
+4. resolve the snapshot
+5. synthesize a review brief from the current session history
+6. preview the synthesized brief + prompt coverage
+7. run the review with a live progress widget
+8. show the structured result as a custom message
+9. if findings exist, hand off to the main agent so it can ask what to do next
 
-## Review modes
+## Review targets
 
-### Dynamic review
+Current targets:
 
-You provide:
+- working tree
+- branch diff vs a selected local base branch
+- one recent commit
 
-- what changed
-- the intended outcome
-- what the reviewer should focus on
+## Session-aware brief synthesis
 
-The package turns that into a review brief and lets you edit the final prompt before the review starts.
+The generated review prompt is **not** just a static diff wrapper.
 
-### Standard review
+Before the actual review starts, the package:
 
-You choose one of the built-in profiles:
+- resolves the **active session branch into the current LLM-visible context**
+- extracts high-signal user/assistant/custom/compaction context from that resolved view
+- synthesizes a structured brief with:
+  - summary
+  - intended outcome
+  - constraints to preserve
+  - focus areas
+  - risky files
+  - unresolved questions
 
-- `general`
-- `security`
-- `api-maintainability`
+The synthesizer also receives a bounded diff excerpt from the snapshot so it can reason about actual code changes, not just filenames.
 
-The package builds the review brief from the selected profile and again lets you edit the final prompt before running.
+That synthesized brief is then combined with the git snapshot into the final reviewer prompt.
 
-## Review targets
+## Model selection
 
-Current target presets:
+Every `/supi-review` run asks you to choose the reviewer model.
 
-- base branch diff
-- uncommitted changes
-- one commit
-- custom review instructions
+- the picker only shows **scoped models** from Pi's `enabledModels` configuration
+- the current session model is preselected only when it is inside that scoped set
+- the selected model is used for both brief synthesis and the final review
+- no review model is persisted in settings
 
 ## Result shape
 
@@ -83,36 +88,25 @@ A successful review includes:
 - overall explanation
 - overall confidence score
 - structured findings with title, body, priority, confidence score, and code location
+- the synthesized brief that drove the review
 
 The renderer also handles failed, canceled, and timed-out reviews.
 
-## Settings
-
-This package registers a **Review** section in `/supi-settings`.
-
-Available settings:
+When a successful review contains findings, `supi-review` also injects an agent-visible hidden follow-up message that asks the main agent to decide the next step with the user. If `ask_user` is available, the main agent is instructed to use it and offer:
 
-- `reviewModel` — preselect the model used by `/supi-review`; empty means inherit the active session model
-- `maxDiffBytes` — maximum diff size before the prompt builder truncates the diff
-- `autoFix` — automatically send a follow-up user message to fix findings after a successful review with findings
-
-Defaults:
-
-```json
-{
-  "review": {
-    "reviewModel": "",
-    "maxDiffBytes": 100000,
-    "autoFix": false
-  }
-}
-```
+- Done
+- Fix all
+- Fix selected
+- Verify findings
 
 ## Source
 
 - `src/review.ts` — command orchestration and interactive flow
-- `src/ui.ts` — TUI selection and approval steps
-- `src/profiles.ts` — built-in review profiles
-- `src/runner.ts` — managed reviewer session
-- `src/settings.ts` — `/supi-settings` integration
-- `src/renderer.ts` — structured result rendering
+- `src/model.ts` — explicit model selection helpers
+- `src/git.ts` — git snapshot resolution
+- `src/history/collect.ts` — active-branch evidence extraction
+- `src/history/synthesize.ts` — brief synthesis orchestration
+- `src/target/packet.ts` — final reviewer packet builder
+- `src/tool/brief-runner.ts` — brief synthesis child session
+- `src/tool/review-runner.ts` — read-only reviewer child session
+- `src/ui/renderer.ts` — structured result rendering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "SuPi Review extension — structured code review via /supi-review command",
   "license": "MIT",
   "repository": {
@@ -19,12 +19,6 @@
     "src/**/*.ts",
     "README.md"
   ],
-  "dependencies": {
-    "@mrclrchtr/supi-core": "1.4.0"
-  },
-  "bundledDependencies": [
-    "@mrclrchtr/supi-core"
-  ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
@@ -47,8 +41,7 @@
   },
   "pi": {
     "extensions": [
-      "./src/extension.ts",
-      "node_modules/@mrclrchtr/supi-core/src/extension.ts"
+      "./src/extension.ts"
     ]
   },
   "main": "src/api.ts",

package/src/git.ts

@@ -1,5 +1,7 @@
 import { execFile } from "node:child_process";
+import { basename } from "node:path";
 import { promisify } from "node:util";
+import type { DiffStats, ReviewSnapshot } from "./types.ts";
 
 const execFileAsync = promisify(execFile);
 
@@ -23,6 +25,32 @@ function gitExecOptions(repoPath: string) {
   };
 }
 
+/** Parse simple git diff statistics from diff/show text. */
+export function parseDiffStats(text: string): DiffStats {
+  let files = 0;
+  let additions = 0;
+  let deletions = 0;
+  let inDiff = false;
+
+  for (const line of text.split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      files++;
+      inDiff = true;
+      continue;
+    }
+
+    if (!inDiff) continue;
+
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      additions++;
+    } else if (line.startsWith("-") && !line.startsWith("---")) {
+      deletions++;
+    }
+  }
+
+  return { files, additions, deletions };
+}
+
 export async function getMergeBase(repoPath: string, branch: string): Promise<string | undefined> {
   try {
     const { stdout } = await execFileAsync(
@@ -99,7 +127,7 @@ export async function getRecentCommits(repoPath: string, limit = 20): Promise<Co
       if (idx <= 0) return undefined;
       return { sha: line.slice(0, idx), subject: line.slice(idx + 1) };
     })
-    .filter((e): e is CommitEntry => e !== undefined);
+    .filter((entry): entry is CommitEntry => entry !== undefined);
 }
 
 export async function getCommitShow(repoPath: string, sha: string): Promise<string> {
@@ -200,3 +228,81 @@ export async function getLocalBranches(repoPath: string): Promise<string[]> {
   sorted.push(...remaining);
   return sorted;
 }
+
+/** Resolve the current working tree into a concrete review snapshot. */
+export async function resolveWorkingTreeSnapshot(
+  repoPath: string,
+): Promise<ReviewSnapshot | undefined> {
+  const [diffText, changedFiles] = await Promise.all([
+    getUncommittedDiff(repoPath),
+    getUncommittedFileNames(repoPath),
+  ]);
+
+  if (!diffText.trim() && changedFiles.length === 0) {
+    return undefined;
+  }
+
+  return {
+    target: { kind: "working-tree" },
+    title: "Working tree changes",
+    changedFiles,
+    diffText,
+    stats: parseDiffStats(diffText),
+  };
+}
+
+/** Resolve a branch-vs-base diff into a concrete review snapshot. */
+export async function resolveBranchSnapshot(
+  repoPath: string,
+  base: string,
+): Promise<ReviewSnapshot | undefined> {
+  const baseSha = await getMergeBase(repoPath, base);
+  if (!baseSha) {
+    return undefined;
+  }
+
+  const [diffText, changedFiles] = await Promise.all([
+    getDiff(repoPath, baseSha),
+    getDiffFileNames(repoPath, baseSha),
+  ]);
+
+  if (!diffText.trim() && changedFiles.length === 0) {
+    return undefined;
+  }
+
+  return {
+    target: { kind: "branch", base },
+    title: `Changes vs ${base}`,
+    changedFiles,
+    diffText,
+    stats: parseDiffStats(diffText),
+  };
+}
+
+/** Resolve one commit into a concrete review snapshot. */
+export async function resolveCommitSnapshot(
+  repoPath: string,
+  sha: string,
+): Promise<ReviewSnapshot | undefined> {
+  const [diffText, changedFiles] = await Promise.all([
+    getCommitShow(repoPath, sha),
+    getCommitFileNames(repoPath, sha),
+  ]);
+
+  if (!diffText.trim() && changedFiles.length === 0) {
+    return undefined;
+  }
+
+  return {
+    target: { kind: "commit", sha },
+    title: `Commit ${sha.slice(0, 7)}`,
+    changedFiles,
+    diffText,
+    stats: parseDiffStats(diffText),
+  };
+}
+
+/** Convenience label for one changed file, used in synthesized prompts/UI. */
+export function formatChangedFileLabel(file: string): string {
+  return basename(file) === file ? file : `${basename(file)} (${file})`;
+}

package/src/history/collect.ts

@@ -0,0 +1,210 @@
+import type { SessionContext } from "@earendil-works/pi-coding-agent";
+import type { HistoryEvidence, ReviewSnapshot } from "../types.ts";
+
+const INTENT_PATTERN =
+  /\b(fix|refactor|rename|preserve|avoid|should|must|ensure|intended|goal|risk|concern|regression|security|correctness|performance|api|breaking|review)\b/i;
+
+type ResolvedSessionMessage = SessionContext["messages"][number];
+
+/**
+ * Extract the highest-signal evidence from the resolved LLM-visible session context.
+ *
+ * The collector intentionally favors user intent, assistant plans, compaction
+ * summaries, and custom extension messages over raw tool chatter.
+ */
+export function collectHistoryEvidence(
+  messages: ResolvedSessionMessage[],
+  snapshot: ReviewSnapshot,
+  note?: string,
+): HistoryEvidence[] {
+  const scoringContext = {
+    changedPathTokens: collectPathTokens(snapshot.changedFiles),
+    noteTokens: collectFreeformTokens(note),
+    total: messages.length,
+  };
+
+  const scored = messages
+    .map((message) => toEvidence(message))
+    .filter(
+      (evidence): evidence is Omit<HistoryEvidence, "score" | "reason"> => evidence !== undefined,
+    )
+    .map((evidence, index) => scoreEvidence(evidence, index, scoringContext))
+    .sort((a, b) => b.score - a.score || b.text.length - a.text.length);
+
+  return capEvidence(scored, 10, 4_500);
+}
+
+function toEvidence(
+  message: ResolvedSessionMessage,
+): Omit<HistoryEvidence, "score" | "reason"> | undefined {
+  switch (message.role) {
+    case "user":
+    case "assistant": {
+      return {
+        kind: message.role,
+        text: normalizeText(extractMessageText(message.content)),
+      };
+    }
+    case "custom": {
+      return {
+        kind: "custom",
+        text: normalizeText(extractMessageText(message.content)),
+      };
+    }
+    case "compactionSummary": {
+      return {
+        kind: "compaction",
+        text: normalizeText(message.summary),
+      };
+    }
+    case "branchSummary": {
+      return {
+        kind: "branch-summary",
+        text: normalizeText(message.summary),
+      };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function scoreEvidence(
+  evidence: Omit<HistoryEvidence, "score" | "reason">,
+  index: number,
+  context: { total: number; changedPathTokens: string[]; noteTokens: string[] },
+): HistoryEvidence {
+  const recencyBoost = context.total > 0 ? (index / context.total) * 3 : 0;
+  const pathMatches = countTokenMatches(evidence.text, context.changedPathTokens);
+  const noteMatches = countTokenMatches(evidence.text, context.noteTokens);
+  const intentBoost = INTENT_PATTERN.test(evidence.text) ? 4 : 0;
+  const shortTextPenalty = evidence.text.length < 24 ? -2 : 0;
+  const longTextPenalty = evidence.text.length > 900 ? -1 : 0;
+  const score =
+    baseKindScore(evidence.kind) +
+    recencyBoost +
+    pathMatches * 3 +
+    noteMatches * 2 +
+    intentBoost +
+    shortTextPenalty +
+    longTextPenalty;
+
+  return {
+    ...evidence,
+    score,
+    reason: buildReason(pathMatches, noteMatches, intentBoost),
+  };
+}
+
+function buildReason(pathMatches: number, noteMatches: number, intentBoost: number): string {
+  const reasons: string[] = [];
+  if (pathMatches > 0) {
+    reasons.push(`mentions ${pathMatches} changed-path token${pathMatches === 1 ? "" : "s"}`);
+  }
+  if (noteMatches > 0) {
+    reasons.push(`matches ${noteMatches} note token${noteMatches === 1 ? "" : "s"}`);
+  }
+  if (intentBoost > 0) {
+    reasons.push("contains intent/constraint language");
+  }
+  return reasons.join(", ") || "high-signal session context";
+}
+
+function extractMessageText(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  if (!Array.isArray(content)) {
+    return "";
+  }
+
+  return content
+    .map((part) => {
+      if (typeof part !== "object" || !part) return "";
+      const text = (part as { text?: unknown }).text;
+      return typeof text === "string" ? text : "";
+    })
+    .filter((text) => text.length > 0)
+    .join("\n");
+}
+
+function normalizeText(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function collectPathTokens(paths: string[]): string[] {
+  const tokens = new Set<string>();
+
+  for (const path of paths) {
+    for (const part of path.split(/[\\/]/)) {
+      addToken(tokens, part);
+      for (const inner of part.split(/[-_.]/)) {
+        addToken(tokens, inner);
+      }
+    }
+    addToken(tokens, path);
+  }
+
+  return Array.from(tokens);
+}
+
+function collectFreeformTokens(text: string | undefined): string[] {
+  if (!text) return [];
+
+  const tokens = new Set<string>();
+  for (const part of text.split(/\W+/)) {
+    addToken(tokens, part);
+  }
+  return Array.from(tokens);
+}
+
+function addToken(tokens: Set<string>, token: string): void {
+  const normalized = token.trim().toLowerCase();
+  if (normalized.length < 3) return;
+  tokens.add(normalized);
+}
+
+function countTokenMatches(text: string, tokens: string[]): number {
+  if (tokens.length === 0 || text.length === 0) return 0;
+  const lower = text.toLowerCase();
+  return tokens.reduce((count, token) => count + (lower.includes(token) ? 1 : 0), 0);
+}
+
+function baseKindScore(kind: HistoryEvidence["kind"]): number {
+  switch (kind) {
+    case "user":
+      return 8;
+    case "assistant":
+      return 5;
+    case "compaction":
+    case "branch-summary":
+      return 6;
+    case "custom":
+      return 4;
+  }
+}
+
+function capEvidence(
+  evidence: HistoryEvidence[],
+  maxItems: number,
+  maxChars: number,
+): HistoryEvidence[] {
+  const kept: HistoryEvidence[] = [];
+  let used = 0;
+
+  for (const item of evidence) {
+    if (kept.length >= maxItems) break;
+    const text = truncate(item.text, 600);
+    const nextUsed = used + text.length;
+    if (kept.length > 0 && nextUsed > maxChars) break;
+    kept.push({ ...item, text });
+    used = nextUsed;
+  }
+
+  return kept;
+}
+
+function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}…`;
+}

package/src/history/synthesize.ts

@@ -0,0 +1,109 @@
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { runBriefSynthesis } from "../tool/brief-runner.ts";
+import type { BriefSynthesisRunResult, ReviewProgress } from "../tool/runner-types.ts";
+import type { HistoryEvidence, ReviewModelSelection, ReviewSnapshot } from "../types.ts";
+
+const DIFF_EXCERPT_CHAR_BUDGET = 12_000;
+
+export interface SynthesizeReviewBriefOptions {
+  model: ReviewModelSelection;
+  modelRegistry: ModelRegistry;
+  cwd: string;
+  snapshot: ReviewSnapshot;
+  evidence: HistoryEvidence[];
+  note?: string;
+  signal?: AbortSignal;
+  onProgress?: (progress: ReviewProgress) => void;
+}
+
+/** Synthesize a structured review brief from the current snapshot and session evidence. */
+export function synthesizeReviewBrief(
+  options: SynthesizeReviewBriefOptions,
+): Promise<BriefSynthesisRunResult> {
+  const { model, modelRegistry, cwd, snapshot, evidence, note, signal, onProgress } = options;
+
+  return runBriefSynthesis({
+    prompt: buildBriefSynthesisPrompt(snapshot, evidence, note),
+    model: model.model,
+    modelRegistry,
+    cwd,
+    signal,
+    onProgress,
+  });
+}
+
+export function buildBriefSynthesisPrompt(
+  snapshot: ReviewSnapshot,
+  evidence: HistoryEvidence[],
+  note?: string,
+): string {
+  const diffExcerpt = buildDiffExcerpt(snapshot.diffText);
+  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 (note?.trim()) {
+    parts.push("", "## User note", note.trim());
+  }
+
+  parts.push("", "## Session evidence");
+  if (evidence.length === 0) {
+    parts.push(
+      "- No strong session evidence was extracted. Derive a minimal brief from the snapshot only.",
+    );
+  } else {
+    parts.push(
+      ...evidence.flatMap((item, index) => [
+        `${index + 1}. [${item.kind}] ${item.reason}`,
+        `   ${item.text}`,
+      ]),
+    );
+  }
+
+  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",
+    "- unresolvedQuestions: ambiguities or concerns that remain unclear",
+  );
+
+  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,
+  };
+}