@dreki-gg/pi-code-reviewer 0.4.0 → 0.6.0

package/README.md

@@ -35,6 +35,32 @@ This creates:
 
 The `code_review` tool is also available for programmatic use by the agent.
 
+## How the review runs (Bugbot-style pipeline)
+
+When a session model is available, the `code_review` tool **runs the review
+itself** rather than returning a prompt for one downstream pass. It drives a
+multi-stage pipeline modeled on Cursor's Bugbot:
+
+1. **Parallel adversarial passes** (default 5) over the diff. Each pass gets a
+   different focus — trust boundaries, control flow, async/lifecycle, types,
+   state integrity, security, resources, contracts — plus a temperature jitter,
+   so passes reason down different paths instead of collapsing onto the same
+   findings.
+2. **Bucket + majority vote.** Near-duplicate findings are fused (same file +
+   line proximity + message similarity) and tracked by how many distinct passes
+   surfaced them. Low-signal single-pass *notes* are dropped; blockers and
+   warnings are never dropped for low votes.
+3. **Validator stage.** One batched call tries to *falsify* each surviving
+   candidate and drops false positives. It **fails open** — if the validator
+   errors, candidates are surfaced unvalidated rather than silently lost.
+
+The tool returns finished, validated findings as a Markdown report (vote count,
+confidence, validator justification) plus structured `details`.
+
+**Fallback:** if no model is available (e.g. print mode) or `review.passes` is
+`0`, the tool returns the previous single-pass review prompt and the calling
+agent produces findings in its follow-up message.
+
 ## Lenses
 
 A lens is a markdown file that defines review criteria, project tools to run, and severity rules:
@@ -88,7 +114,17 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
   "lensDir": ".code-review/lenses",
   "defaultLenses": ["code-quality", "maintainability"],
   "toolTimeoutMs": 60000,
-  "toolConcurrency": 4
+  "toolConcurrency": 4,
+  "review": {
+    "passes": 5,
+    "validate": true,
+    "minVotes": 2,
+    "concurrency": 5,
+    "temperature": 0.4,
+    "maxFindings": 50,
+    "passModels": [{ "model": "anthropic/claude-opus-4-8", "reasoning": "low" }],
+    "validateModel": { "model": "anthropic/claude-opus-4-8", "reasoning": "medium" }
+  }
 }
 ```
 
@@ -98,4 +134,30 @@ Run `/review-init` to scaffold these (customized for your project's tools) into
 | `defaultLenses` | `[]` (all) | Lenses to run when none specified |
 | `toolTimeoutMs` | `60000` | Per-tool wall-clock timeout (ms); an exceeding tool is killed and reported as timed-out |
 | `toolConcurrency` | `4` | Max distinct tools run in parallel (tools are deduped across lenses first) |
+| `review.passes` | `5` | Parallel adversarial bug-finding passes. `0` disables the pipeline (single-pass prompt fallback). |
+| `review.validate` | `true` | Run the validator stage that falsifies each surviving candidate. |
+| `review.minVotes` | `2` | Min distinct passes a NOTE bucket needs to survive pre-validation (blockers/warnings exempt). |
+| `review.concurrency` | `= passes` | Max passes run concurrently. |
+| `review.temperature` | `0.4` | Base sampling temperature; each pass adds a small jitter so passes diverge. |
+| `review.maxFindings` | `50` | Hard cap on findings returned. |
+| `review.passModel` | session model | Model for ALL passes: a spec string (`"provider/id"`, bare id, or name) or `{ "model", "reasoning" }`. |
+| `review.passModels` | — | List of models **rotated round-robin across passes** — a bake-off in one run. Overrides `passModel`. |
+| `review.validateModel` | session model | Model for the validator stage (string or `{ "model", "reasoning" }`). |
+
+Each step accepts either a plain spec string or `{ "model": "provider/id", "reasoning": "low" }`
+where `reasoning` is one of `minimal` / `low` / `medium` / `high` / `xhigh` (applied as the
+thinking effort for that step; ignored by providers that don't support it).
+
+> By default the pipeline reuses the **session's current model** (`ctx.model`) —
+> no separate API key or model config. More passes = deeper coverage but higher
+> token/latency cost; tune `review.passes` to taste (3 = cheap, 8 = Bugbot
+> parity).
+>
+> **Model bake-off.** Set `passModels` to a list to run the same diff through
+> several models in one review and compare. Models are assigned round-robin to
+> passes, each finding is annotated with the model(s) that caught it, and the
+> report shows a per-model breakdown. Use a cheap model for `passModels` and a
+> stronger one for `validateModel` (or vice-versa) to probe the speed/cost/
+> quality frontier. Specs are matched as `provider/id`, a bare `id`, or a
+> display `name`; an unknown spec falls back to the session model with a warning.
 

package/extensions/code-reviewer/commands/review-init.ts

@@ -14,7 +14,11 @@ export function registerReviewInitCommand(pi: ExtensionAPI) {
           `1. Read the project's AGENTS.md, package.json, and any CONTEXT.md to understand the stack and conventions.`,
           `2. Create a \`.code-review.json\` config file at the project root. Supported keys:`,
           `   - \`lensDir\` (default \`.code-review/lenses\`), \`defaultLenses\` (lenses run when none are specified),`,
-          `   - \`toolTimeoutMs\` (per-tool timeout, default 60000), \`toolConcurrency\` (parallel tools, default 4).`,
+          `   - \`toolTimeoutMs\` (per-tool timeout, default 60000), \`toolConcurrency\` (parallel tools, default 4),`,
+          `   - \`review\` (self-driving pipeline): \`passes\` (default 5, 0 disables), \`validate\` (default true),`,
+          `     \`minVotes\` (default 2), \`concurrency\` (default = passes), \`temperature\` (default 0.4), \`maxFindings\` (default 50),`,
+          `     and per-step models for a bake-off: \`passModel\`, \`passModels\` (rotated across passes), \`validateModel\``,
+          `     (each a "provider/id", bare id, or display name; default = the session model).`,
           `3. Create lens files in \`.code-review/lenses/\` — start with: code-quality.md, maintainability.md`,
           `4. Each lens's \`## Tools\` must list ONLY fast, non-side-effecting commands that EXIT on their own`,
           `   (e.g. typecheck, lint, unit tests). Do NOT list dev servers, watch mode, e2e suites, or full`,

package/extensions/code-reviewer/commands/review-tool.ts

@@ -4,7 +4,16 @@ import { Type } from 'typebox';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff, getChangedFiles } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { buildDiffSection, buildLensResult, pickLensToolOutputs, runTools } from '../reviewer';
+import { resolveModelPlan } from '../model-plan';
+import { runPipeline } from '../passes';
+import {
+  buildDiffSection,
+  buildLensResult,
+  buildReviewBasePrompt,
+  pickLensToolOutputs,
+  renderPipelineReport,
+  runTools,
+} from '../reviewer';
 import type { DiffSource } from '../diff';
 import type { LensResult, ReviewConfig } from '../types';
 
@@ -106,23 +115,90 @@ export function registerReviewTool(pi: ExtensionAPI) {
         results.push(buildLensResult(lens, content, pickLensToolOutputs(lens, toolOutputs)));
       }
 
+      const changedFiles = await getChangedFiles(pi, cwd, {
+        base: params.base,
+        staged: params.staged,
+      });
+
+      // Self-driving path: when a model is available and passes are enabled,
+      // the tool runs the Bugbot-style pipeline itself (parallel adversarial
+      // passes → bucket → majority vote → validate) and returns FINISHED,
+      // validated findings — not a prompt for a single downstream pass.
+      const lensSections = results.map((result) => result._lensSection).filter(Boolean) as string[];
+      if (ctx.model && config.review.passes > 0 && lensSections.length > 0 && !signal?.aborted) {
+        try {
+          const { resolution, plan, warnings } = resolveModelPlan(
+            config.review,
+            ctx.model,
+            ctx.modelRegistry,
+          );
+          for (const warning of warnings) ctx.ui.notify(warning, 'warning');
+          const basePrompt = buildReviewBasePrompt(lensSections, diff);
+          const pipeline = await runPipeline(
+            resolution,
+            plan,
+            basePrompt,
+            config.review,
+            {
+              onStage: (stage) => {
+                ctx.ui.setStatus('code-review', `🔍 ${stage}...`);
+                onUpdate?.({ content: [{ type: 'text', text: stage }], details: { stage } });
+              },
+            },
+            signal,
+          );
+          ctx.ui.setStatus('code-review', undefined);
+          // Every pass failed (e.g. the review model/pi-ai was unavailable for
+          // each call). The swallowed failures would render as a misleading
+          // "0 findings" report — instead, degrade to the single-pass prompt so
+          // the reviewing agent still produces a real review.
+          const allPassesFailed =
+            config.review.passes > 0 && pipeline.telemetry.failedPasses >= config.review.passes;
+          if (!allPassesFailed) {
+            return {
+              content: [{ type: 'text', text: renderPipelineReport(pipeline, diff) }],
+              details: {
+                mode: 'pipeline',
+                lensCount: lensNames.length,
+                availableLenses: [...available.keys()],
+                changedFiles,
+                findings: pipeline.findings,
+                telemetry: pipeline.telemetry,
+              },
+            };
+          }
+          onUpdate?.({
+            content: [{ type: 'text', text: 'all review passes failed — single-pass fallback' }],
+            details: {
+              failedPasses: pipeline.telemetry.failedPasses,
+              passError: pipeline.telemetry.passErrorSample,
+            },
+          });
+        } catch (cause) {
+          // Pipeline failed hard (e.g. model/pi-ai unavailable at runtime) —
+          // degrade to the single-pass prompt instead of failing the review.
+          ctx.ui.setStatus('code-review', undefined);
+          onUpdate?.({
+            content: [{ type: 'text', text: 'pipeline unavailable — single-pass fallback' }],
+            details: { pipelineError: cause instanceof Error ? cause.message : String(cause) },
+          });
+        }
+      }
+
       ctx.ui.setStatus('code-review', undefined);
 
-      // The tool returns a pre-review skeleton + the review task. Findings are
-      // produced by the agent in its follow-up message (per the instructions
-      // below), NOT parsed back here — so we deliberately do not render a
-      // findings scoreboard that would always read "0".
+      // Fallback: return the review task for a single downstream pass (the
+      // agent produces findings in its follow-up message). Used when no model
+      // is available (e.g. print mode) or passes are disabled in config.
       const text = buildToolContext(results, diff);
 
       return {
         content: [{ type: 'text', text }],
         details: {
+          mode: 'single-pass',
           lensCount: lensNames.length,
           availableLenses: [...available.keys()],
-          changedFiles: await getChangedFiles(pi, cwd, {
-            base: params.base,
-            staged: params.staged,
-          }),
+          changedFiles,
         },
       };
     },

package/extensions/code-reviewer/commands/review.ts

@@ -3,7 +3,16 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { loadConfig, getLensDir } from '../config';
 import { collectDiff } from '../diff';
 import { discoverLenses, getLensContent } from '../lenses';
-import { buildDiffSection, buildLensResult, pickLensToolOutputs, runTools } from '../reviewer';
+import { resolveModelPlan } from '../model-plan';
+import { runPipeline } from '../passes';
+import {
+  buildDiffSection,
+  buildLensResult,
+  buildReviewBasePrompt,
+  pickLensToolOutputs,
+  renderPipelineReport,
+  runTools,
+} from '../reviewer';
 import { parseReviewArgs } from '../parse-args';
 
 export function registerReviewCommand(pi: ExtensionAPI) {
@@ -71,6 +80,32 @@ export function registerReviewCommand(pi: ExtensionAPI) {
 
       ctx.ui.setStatus('code-review', undefined);
 
+      // Self-driving path: run the Bugbot-style pipeline in-command and deliver
+      // the validated report in-session for discussion. Mirrors the tool.
+      if (ctx.model && config.review.passes > 0 && lensSections.length > 0) {
+        try {
+          const { resolution, plan, warnings } = resolveModelPlan(
+            config.review,
+            ctx.model,
+            ctx.modelRegistry,
+          );
+          for (const warning of warnings) ctx.ui.notify(warning, 'warning');
+          const basePrompt = buildReviewBasePrompt(lensSections, diff);
+          const pipeline = await runPipeline(resolution, plan, basePrompt, config.review, {
+            onStage: (stage) => ctx.ui.setStatus('code-review', `🔍 ${stage}...`),
+          });
+          ctx.ui.setStatus('code-review', undefined);
+          pi.sendUserMessage(renderPipelineReport(pipeline, diff), { deliverAs: 'followUp' });
+          return;
+        } catch (cause) {
+          ctx.ui.setStatus('code-review', undefined);
+          ctx.ui.notify(
+            `Pipeline unavailable (${cause instanceof Error ? cause.message : String(cause)}) — single-pass fallback`,
+            'warning',
+          );
+        }
+      }
+
       const combinedPrompt = [
         `Review the following changes through ${lensNames.length} lens(es): ${lensNames.join(', ')}.`,
         '',

package/extensions/code-reviewer/config.ts

@@ -10,19 +10,90 @@ import { Effect } from 'effect';
 import { resolve } from 'node:path';
 
 import { FileSystem, nodeFileSystemService } from './effects/filesystem';
-import type { ReviewConfig } from './types';
+import type { ModelStepConfig, ReasoningLevel, ReviewConfig, ReviewPipelineConfig } from './types';
+
+const REASONING_LEVELS = new Set<ReasoningLevel>(['minimal', 'low', 'medium', 'high', 'xhigh']);
 
 const CONFIG_FILE = '.code-review.json';
 const DEFAULT_LENS_DIR = '.code-review/lenses';
 const DEFAULT_TOOL_TIMEOUT_MS = 60_000;
 const DEFAULT_TOOL_CONCURRENCY = 4;
 
+const DEFAULT_PIPELINE: ReviewPipelineConfig = {
+  passes: 5,
+  validate: true,
+  minVotes: 2,
+  concurrency: 5,
+  temperature: 0.4,
+  maxFindings: 50,
+};
+
 function defaultConfig(): ReviewConfig {
   return {
     lensDir: DEFAULT_LENS_DIR,
     defaultLenses: [],
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
     toolConcurrency: DEFAULT_TOOL_CONCURRENCY,
+    review: { ...DEFAULT_PIPELINE },
+  };
+}
+
+/** Coerce a config value to a non-negative integer (0 allowed: disables passes). */
+function nonNegativeIntOr(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : fallback;
+}
+
+/** Coerce a config value to a number within [min, max]. */
+function clampNumberOr(value: unknown, fallback: number, min: number, max: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.min(max, Math.max(min, value))
+    : fallback;
+}
+
+/** Coerce a config value to a model step: a non-empty spec string or
+ *  `{ model, reasoning }`. Returns undefined for anything else. */
+function parseModelStep(value: unknown): ModelStepConfig | undefined {
+  if (typeof value === 'string') return value.trim() ? value.trim() : undefined;
+  if (typeof value === 'object' && value !== null) {
+    const record = value as Record<string, unknown>;
+    const model = typeof record.model === 'string' ? record.model.trim() : '';
+    if (!model) return undefined;
+    const reasoning =
+      typeof record.reasoning === 'string' &&
+      REASONING_LEVELS.has(record.reasoning as ReasoningLevel)
+        ? (record.reasoning as ReasoningLevel)
+        : undefined;
+    return reasoning ? { model, reasoning } : { model };
+  }
+  return undefined;
+}
+
+/** Coerce a config value to a non-empty array of model steps, or undefined. */
+function parseModelStepArray(value: unknown): ModelStepConfig[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const steps = value
+    .map(parseModelStep)
+    .filter((step): step is ModelStepConfig => step !== undefined);
+  return steps.length > 0 ? steps : undefined;
+}
+
+function parsePipeline(raw: unknown): ReviewPipelineConfig {
+  if (typeof raw !== 'object' || raw === null) return { ...DEFAULT_PIPELINE };
+  const review = raw as Record<string, unknown>;
+  const passes = nonNegativeIntOr(review.passes, DEFAULT_PIPELINE.passes);
+  return {
+    passes,
+    validate: typeof review.validate === 'boolean' ? review.validate : DEFAULT_PIPELINE.validate,
+    minVotes: positiveIntOr(review.minVotes, DEFAULT_PIPELINE.minVotes),
+    // Default concurrency tracks pass count so all passes fan out at once.
+    concurrency: positiveIntOr(review.concurrency, Math.max(1, passes)),
+    temperature: clampNumberOr(review.temperature, DEFAULT_PIPELINE.temperature, 0, 2),
+    maxFindings: positiveIntOr(review.maxFindings, DEFAULT_PIPELINE.maxFindings),
+    passModel: parseModelStep(review.passModel),
+    passModels: parseModelStepArray(review.passModels),
+    validateModel: parseModelStep(review.validateModel),
   };
 }
 
@@ -46,6 +117,7 @@ export function loadConfigEffect(cwd: string): Effect.Effect<ReviewConfig, never
         defaultLenses: parsed.defaultLenses ?? [],
         toolTimeoutMs: positiveIntOr(parsed.toolTimeoutMs, DEFAULT_TOOL_TIMEOUT_MS),
         toolConcurrency: positiveIntOr(parsed.toolConcurrency, DEFAULT_TOOL_CONCURRENCY),
+        review: parsePipeline((parsed as { review?: unknown }).review),
       };
     } catch {
       // Malformed config — fall back to defaults.

package/extensions/code-reviewer/diff.ts

@@ -23,6 +23,14 @@ export type DiffOptions = { base?: string; staged?: boolean };
  *  the whole review. */
 const GIT_TIMEOUT_MS = 30_000;
 
+/** Cap on untracked files diffed against /dev/null so a repo full of generated
+ *  junk can't blow up the prompt. The whole diff is truncated downstream too. */
+const MAX_UNTRACKED_FILES = 200;
+
+/** The empty tree object — diffing a path against it yields a full new-file
+ *  diff portably (no reliance on /dev/null path handling across platforms). */
+const NULL_DEVICE = '/dev/null';
+
 function git(args: string[], cwd: string): Effect.Effect<string, ExecError, Executor> {
   return Effect.gen(function* () {
     const executor = yield* Executor;
@@ -31,6 +39,51 @@ function git(args: string[], cwd: string): Effect.Effect<string, ExecError, Exec
   });
 }
 
+/**
+ * Diff every untracked (new, not-yet-`git add`ed) file against /dev/null so
+ * brand-new files show up in a working-directory review — `git diff HEAD`
+ * omits them entirely, which is exactly the class of change agents introduce.
+ *
+ * Read-only: it NEVER touches the index (no `git add -N`). `git diff --no-index`
+ * exits non-zero when files differ, but pi.exec resolves with the diff on stdout
+ * regardless; any per-file failure degrades to an empty string rather than
+ * sinking the whole review.
+ */
+function collectUntrackedEffect(
+  cwd: string,
+): Effect.Effect<{ diff: string; files: string[] }, never, Executor> {
+  return Effect.gen(function* () {
+    const listed = yield* git(['ls-files', '--others', '--exclude-standard'], cwd).pipe(
+      Effect.orElseSucceed(() => ''),
+    );
+    const files = listed
+      .split('\n')
+      .map((f) => f.trim())
+      .filter(Boolean);
+    if (files.length === 0) return { diff: '', files: [] };
+
+    const parts = yield* Effect.forEach(
+      files.slice(0, MAX_UNTRACKED_FILES),
+      (file) =>
+        git(['diff', '--no-index', '--', NULL_DEVICE, file], cwd).pipe(
+          Effect.orElseSucceed(() => ''),
+        ),
+      { concurrency: 4 },
+    );
+    return { diff: parts.filter((part) => part.trim()).join('\n'), files };
+  });
+}
+
+/** Append a one-line-per-file summary of untracked files to a `--stat` block so
+ *  the change overview reflects new files that git's own stat never lists. */
+function appendUntrackedStat(stat: string, files: string[]): string {
+  if (files.length === 0) return stat;
+  const shown = files.slice(0, MAX_UNTRACKED_FILES);
+  const lines = shown.map((file) => ` ${file} | (new, untracked)`);
+  const note = `${files.length} untracked file(s) included`;
+  return [stat.trimEnd(), ...lines, note].filter(Boolean).join('\n');
+}
+
 /** Collect the diff from the working directory or a specific base ref. */
 export function collectDiffEffect(
   cwd: string,
@@ -49,20 +102,31 @@ export function collectDiffEffect(
       return { diff, stat, label: `changes since ${options.base}` };
     }
 
-    // Default: working directory changes (unstaged + staged) relative to HEAD.
-    // `git diff HEAD` fails on a repo with no commits (HEAD is unborn), so
+    // Default: EVERYTHING the agent is working on but hasn't committed —
+    // tracked changes (unstaged + staged) relative to HEAD, PLUS untracked
+    // (brand-new) files. `git diff HEAD` covers only the former; untracked
+    // files are collected separately and merged so new files are reviewed too.
+    // `git diff HEAD` also fails on a repo with no commits (HEAD is unborn), so
     // tolerate that and fall back to the bare working-directory diff.
     const headDiff = yield* git(['diff', 'HEAD'], cwd).pipe(Effect.either);
+    const untracked = yield* collectUntrackedEffect(cwd);
 
-    // No HEAD (fresh repo) or an empty HEAD diff → fall back to the working dir.
+    let tracked: string;
+    let stat: string;
+    let label: string;
     if (headDiff._tag === 'Left' || !headDiff.right.trim()) {
-      const wdDiff = yield* git(['diff'], cwd);
-      const wdStat = yield* git(['diff', '--stat'], cwd);
-      return { diff: wdDiff, stat: wdStat, label: 'working directory changes' };
+      // No HEAD (fresh repo) or no tracked changes → use the bare working dir.
+      tracked = yield* git(['diff'], cwd);
+      stat = yield* git(['diff', '--stat'], cwd);
+      label = 'working directory changes';
+    } else {
+      tracked = headDiff.right;
+      stat = yield* git(['diff', 'HEAD', '--stat'], cwd);
+      label = 'all uncommitted changes';
     }
 
-    const stat = yield* git(['diff', 'HEAD', '--stat'], cwd);
-    return { diff: headDiff.right, stat, label: 'all uncommitted changes' };
+    const diff = [tracked, untracked.diff].filter((part) => part.trim()).join('\n');
+    return { diff, stat: appendUntrackedStat(stat, untracked.files), label };
   });
 }
 
@@ -72,19 +136,31 @@ export function getChangedFilesEffect(
   options: DiffOptions,
 ): Effect.Effect<string[], ExecError, Executor> {
   return Effect.gen(function* () {
-    const args = ['diff', '--name-only'];
-    if (options.staged) args.push('--staged');
-    else if (options.base) args.push(options.base);
-    else args.push('HEAD');
+    if (options.staged || options.base) {
+      const args = ['diff', '--name-only', options.staged ? '--staged' : options.base!];
+      const stdout = yield* git(args, cwd);
+      return splitPaths(stdout);
+    }
 
-    const stdout = yield* git(args, cwd);
-    return stdout
-      .split('\n')
-      .map((f) => f.trim())
-      .filter(Boolean);
+    // Default: tracked changes vs HEAD (tolerate an unborn HEAD) plus untracked
+    // files, deduped, so the changed-file list mirrors the merged default diff.
+    const tracked = yield* git(['diff', '--name-only', 'HEAD'], cwd).pipe(
+      Effect.orElseSucceed(() => ''),
+    );
+    const untracked = yield* git(['ls-files', '--others', '--exclude-standard'], cwd).pipe(
+      Effect.orElseSucceed(() => ''),
+    );
+    return [...new Set([...splitPaths(tracked), ...splitPaths(untracked)])];
   });
 }
 
+function splitPaths(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((f) => f.trim())
+    .filter(Boolean);
+}
+
 // ── Promise wrappers (live Executor from pi) ──────────────────────────────────
 
 export function collectDiff(

package/extensions/code-reviewer/effects/model.ts

@@ -0,0 +1,112 @@
+/**
+ * Reviewer service — wraps the session's current model so a single completion
+ * becomes an injectable, typed Effect. The self-driving pipeline (see
+ * `passes.ts`) depends on this Tag; the live implementation drives
+ * `@earendil-works/pi-ai`'s `completeSimple` over `ctx.model`, while tests
+ * provide a deterministic fake instead of calling a real provider.
+ *
+ * `@earendil-works/pi-ai` is an OPTIONAL peer dependency, so the runtime import
+ * is deferred (`import()`), reached only when the harness actually hands us a
+ * model. The extension stays loadable in environments without pi-ai.
+ */
+
+import type { Api, AssistantMessage, Model, TextContent } from '@earendil-works/pi-ai';
+import { Context, Effect } from 'effect';
+
+import { ModelError } from '../errors';
+import type { ReasoningLevel } from '../types';
+
+/** The model key meaning "use the session's current model". */
+export const DEFAULT_MODEL_KEY = 'default';
+
+export type CompletionRequest = {
+  /** Which model to run this call on — {@link DEFAULT_MODEL_KEY} or a key the
+   *  resolution map holds. Unknown keys fall back to the default model. */
+  modelKey: string;
+  system: string;
+  user: string;
+  /** Sampling temperature; the pipeline jitters this per pass. */
+  temperature?: number;
+  /** Reasoning/thinking effort for this call (provider-dependent). */
+  reasoning?: ReasoningLevel;
+  /** Identifies which pipeline stage is calling, for error context. */
+  stage: string;
+  signal?: AbortSignal;
+};
+
+export interface ReviewerService {
+  readonly complete: (request: CompletionRequest) => Effect.Effect<string, ModelError>;
+}
+
+export class Reviewer extends Context.Tag('CodeReviewer/Reviewer')<Reviewer, ReviewerService>() {}
+
+/** Resolved models the pipeline can run against: a default (session) model plus
+ *  any config-specified models keyed by their spec string. */
+export type ModelResolution = {
+  defaultModel: Model<Api>;
+  byKey: Map<string, Model<Api>>;
+};
+
+/** Resolve a config model spec to a registered model. Accepts "provider/id",
+ *  a bare model `id`, a `"provider/id"` composite, or a display `name`. */
+export function resolveModelSpec(
+  registry: { getAll: () => Model<Api>[] },
+  spec: string,
+): Model<Api> | undefined {
+  const trimmed = spec.trim();
+  if (!trimmed) return undefined;
+  const all = registry.getAll();
+
+  const slash = trimmed.indexOf('/');
+  if (slash > 0) {
+    const provider = trimmed.slice(0, slash);
+    const id = trimmed.slice(slash + 1);
+    const exact = all.find((model) => model.provider === provider && model.id === id);
+    if (exact) return exact;
+  }
+  return (
+    all.find((model) => model.id === trimmed) ??
+    all.find((model) => `${model.provider}/${model.id}` === trimmed) ??
+    all.find((model) => model.name === trimmed)
+  );
+}
+
+/** Flatten an assistant message to its plain-text content (drop thinking/tool). */
+export function extractText(message: AssistantMessage): string {
+  return message.content
+    .filter((block): block is TextContent => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+    .trim();
+}
+
+/** Build a live Reviewer that routes each call to the model named by its
+ *  `modelKey` (falling back to the default/session model) via pi-ai. */
+export function makeReviewerService(resolution: ModelResolution): ReviewerService {
+  return {
+    complete: (request) =>
+      Effect.tryPromise({
+        try: async () => {
+          const { completeSimple } = await import('@earendil-works/pi-ai');
+          const model = resolution.byKey.get(request.modelKey) ?? resolution.defaultModel;
+          const message = await completeSimple(
+            model,
+            {
+              systemPrompt: request.system,
+              messages: [{ role: 'user', content: request.user, timestamp: Date.now() }],
+            },
+            {
+              temperature: request.temperature,
+              reasoning: request.reasoning,
+              signal: request.signal,
+            },
+          );
+          if (message.stopReason === 'error') {
+            throw new Error(message.errorMessage ?? 'model returned an error stop reason');
+          }
+          return extractText(message);
+        },
+        catch: (cause) => new ModelError({ stage: request.stage, cause }),
+      }),
+  };
+}

package/extensions/code-reviewer/errors.ts

@@ -28,7 +28,16 @@ export class ExecError extends Data.TaggedError('ExecError')<{
   }
 }
 
-export type CodeReviewerError = FileReadError | ExecError;
+export class ModelError extends Data.TaggedError('ModelError')<{
+  readonly stage: string;
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    return `Model call failed during ${this.stage}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export type CodeReviewerError = FileReadError | ExecError | ModelError;
 
 // ── Helpers ───────────────────────────────────────────────────────────────