@djoeyg/pi-review 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joey Goldman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# pi-review
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Gives the agent a background code reviewer it can steer.
+
+- `request_review` starts a reviewer and returns a review id (`R1`, `R2`, …) immediately. The reviewer is a headless pi on its own model, with fresh context and read-only tools (`read`, `grep`, `find`, `ls`, `bash`). When it finishes, its verdict and findings arrive in the session as a message, which starts a turn if the agent is idle.
+- `steer_review` messages a review. While it runs, the message redirects it. After it finishes, the message starts another round in the same reviewer context, so the agent can dispute findings or ask for a re-review after fixing them.
+
+Reviewers live until the session ends. The footer shows which are running.
+
+`/review off` removes both tools from the agent and stops running reviewers; `/review on` restores them, and `/review` toggles. The choice persists in `~/.pi/agent/review.json` as `"enabled"`.
+
+The reviewer prompt ([`src/reviewer.md`](src/reviewer.md)) asks for a strict maintainability review: correctness first, then structural simplification, ownership boundaries, and illegal state.
+
+## Models
+
+The agent picks the reviewer model per request. Offer it a menu in `~/.pi/agent/review.json`: keys are `provider/id`, optionally with a `:thinking` suffix, and values say when to pick each. The first entry is the default.
+
+```json
+{
+  "models": {
+    "openai/gpt-6.1-sol:high": "Default. Deep structural and correctness review.",
+    "claude-bridge/claude-opus-5-5:high": "Second opinion from another model family; large or cross-cutting changes.",
+    "openai/gpt-6-luna:medium": "Small, low-risk diffs where speed matters."
+  }
+}
+```
+
+Without a menu, the agent may name any model that has credentials, and defaults to its own. An optional `"promptFile"` (absolute path) replaces the bundled reviewer prompt.
+
+## Install
+
+```sh
+pi install npm:@djoeyg/pi-review
+```

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@djoeyg/pi-review",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "request_review / steer_review: background code review by an independent, steerable reviewer model",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "code-review",
+    "subagent"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "author": "Joey Goldman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/D-Joey-G/pi-extensions.git",
+    "directory": "packages/pi-review"
+  },
+  "homepage": "https://github.com/D-Joey-G/pi-extensions/tree/main/packages/pi-review#readme",
+  "bugs": "https://github.com/D-Joey-G/pi-extensions/issues",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { type ReviewOutcome, Reviewer } from "./reviewer.ts";
+
+const CONFIG_PATH = path.join(getAgentDir(), "review.json");
+const DEFAULT_PROMPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "reviewer.md");
+const TOOL_NAMES = ["request_review", "steer_review"];
+
+interface Config {
+  /** `provider/id[:thinking]` -> when to pick it. First entry is the default. */
+  models: Record<string, string>;
+  promptFile?: string;
+  enabled: boolean;
+}
+
+function readRaw(): Record<string, any> {
+  if (!fs.existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
+  } catch (e) {
+    throw new Error(`Invalid ${CONFIG_PATH}: ${e}`);
+  }
+}
+
+function loadConfig(): Config {
+  const raw = readRaw();
+  return { models: raw.models ?? {}, promptFile: raw.promptFile, enabled: raw.enabled ?? true };
+}
+
+function saveEnabled(enabled: boolean): void {
+  fs.writeFileSync(CONFIG_PATH, `${JSON.stringify({ ...readRaw(), enabled }, null, 2)}\n`);
+}
+
+function modelDescription(config: Config): string {
+  const entries = Object.entries(config.models);
+  if (!entries.length) {
+    return "Reviewer model as `provider/id`, optionally with `:thinking` (e.g. `openai/gpt-5:high`). Defaults to your own model.";
+  }
+  const menu = entries.map(([model, note], i) => `- \`${model}\`${i === 0 ? " (default)" : ""}: ${note}`).join("\n");
+  return `Reviewer model. Pick the one that best fits the change:\n${menu}`;
+}
+
+function resolveModel(requested: string | undefined, config: Config, ctx: ExtensionContext): string {
+  const configured = Object.keys(config.models);
+  const spec = requested ?? configured[0] ?? (ctx.model && `${ctx.model.provider}/${ctx.model.id}`);
+  if (!spec) throw new Error("No reviewer model: pass `model`.");
+  if (configured.length && !configured.includes(spec)) {
+    throw new Error(`Model ${spec} is not offered. Choose one of: ${configured.join(", ")}`);
+  }
+  const [ref] = spec.split(":");
+  if (!ctx.modelRegistry.getAvailable().some((m) => `${m.provider}/${m.id}` === ref)) {
+    throw new Error(`Model ${ref} is unknown or has no credentials.`);
+  }
+  return spec;
+}
+
+function outcomeMessage(reviewer: Reviewer, outcome: ReviewOutcome): string {
+  const head = `Review ${reviewer.id} (${reviewer.model})`;
+  if (outcome.kind === "failed") return `${head} failed: ${outcome.error}`;
+  return (
+    `${head} finished:\n\n${outcome.text}\n\n` +
+    `Use steer_review with id ${reviewer.id} to dispute findings or to request a re-review after fixing them.`
+  );
+}
+
+export default function (pi: ExtensionAPI) {
+  const config = loadConfig();
+  const promptFile = config.promptFile ?? DEFAULT_PROMPT;
+  const reviewers = new Map<string, Reviewer>();
+  let ui: ExtensionContext["ui"] | undefined;
+
+  const updateStatus = () => {
+    const running = [...reviewers.values()].filter((r) => r.running).map((r) => r.id);
+    ui?.setStatus("review", running.length ? `reviewing: ${running.join(", ")}` : undefined);
+  };
+
+  const onOutcome = (reviewer: Reviewer, outcome: ReviewOutcome) => {
+    updateStatus();
+    pi.sendMessage(
+      {
+        customType: "review",
+        content: outcomeMessage(reviewer, outcome),
+        display: true,
+        details: { id: reviewer.id, model: reviewer.model },
+      },
+      { triggerTurn: true, deliverAs: "steer" },
+    );
+  };
+
+  pi.registerTool({
+    name: "request_review",
+    label: "Request Review",
+    description:
+      "Start a code review in the background. The reviewer runs on its own model with fresh context and read-only tools. " +
+      "Returns a review id immediately; the review arrives later as a message. Keep working meanwhile, or end your turn " +
+      "if there is nothing else to do: the result starts a new turn. Do not poll. " +
+      "The reviewer cannot see this conversation, so state the goal, constraints, and scope (base ref, files).",
+    promptSnippet: "Start a background code review by an independent reviewer model",
+    parameters: Type.Object({
+      request: Type.String({ description: "What changed and why, constraints, and what to review (base ref, files)." }),
+      model: Type.Optional(Type.String({ description: modelDescription(config) })),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      ui = ctx.ui;
+      const model = resolveModel(params.model, config, ctx);
+      const id = `R${reviewers.size + 1}`;
+      const reviewer = new Reviewer({ id, model, cwd: ctx.cwd, promptFile, onOutcome });
+      reviewers.set(id, reviewer);
+      reviewer.send(params.request);
+      updateStatus();
+      return {
+        content: [{ type: "text", text: `Review ${id} started with ${model}. Its result will arrive as a message.` }],
+        details: { id, model },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "steer_review",
+    label: "Steer Review",
+    description:
+      "Message a review started with request_review. While it runs, the message redirects it. After it finishes, the " +
+      "message starts another round in the same reviewer context: dispute findings, answer its questions, or ask for a " +
+      "re-review after fixes. Returns immediately; the reply arrives as a message.",
+    promptSnippet: "Redirect a running review, or continue a finished one",
+    parameters: Type.Object({
+      id: Type.String({ description: "Review id from request_review, e.g. R1." }),
+      message: Type.String(),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      ui = ctx.ui;
+      const reviewer = reviewers.get(params.id);
+      if (!reviewer) throw new Error(`No review ${params.id}. Known: ${[...reviewers.keys()].join(", ") || "none"}`);
+      const wasRunning = reviewer.running;
+      reviewer.send(params.message);
+      updateStatus();
+      const text = wasRunning ? `Steered review ${params.id}.` : `Started another round of review ${params.id}.`;
+      return {
+        content: [{ type: "text", text: `${text} The reply will arrive as a message.` }],
+        details: { id: params.id },
+      };
+    },
+  });
+
+  const stopAll = () => {
+    for (const reviewer of reviewers.values()) reviewer.stop();
+    reviewers.clear();
+    ui?.setStatus("review", undefined);
+  };
+
+  let enabled = config.enabled;
+  const applyEnabled = () => {
+    const others = pi.getActiveTools().filter((name) => !TOOL_NAMES.includes(name));
+    pi.setActiveTools(enabled ? [...others, ...TOOL_NAMES] : others);
+  };
+
+  pi.registerCommand("review", {
+    description: "Turn the review tools on or off (persists): /review [on|off]",
+    handler: async (args, ctx) => {
+      const arg = args.trim();
+      if (arg && arg !== "on" && arg !== "off") return void ctx.ui.notify("Usage: /review [on|off]", "warning");
+      enabled = arg ? arg === "on" : !enabled;
+      saveEnabled(enabled);
+      applyEnabled();
+      if (!enabled) stopAll();
+      ctx.ui.notify(`Review tools ${enabled ? "on" : "off"}`, "info");
+    },
+  });
+
+  pi.on("session_start", applyEnabled);
+  pi.on("session_shutdown", stopAll);
+}

package/src/reviewer.md

@@ -0,0 +1,99 @@
+# Reviewer
+
+Another coding agent asked you to review its work. You cannot see its conversation; rely on the request and the repository. It may message you mid-review to redirect you, or after you finish to discuss findings or ask for a re-review. On a re-review, re-verify every earlier finding against the code: drop it if fixed, or if the agent's rationale for disputing it holds; otherwise keep it and say why.
+
+Do not edit files. Bash is for read-only work: `git diff`, `git log`, `git show`, and running tests, linters, or type-checkers.
+
+Start from the request. If it names a base ref or files, review those; otherwise run `git status` and `git diff HEAD`. Read the changed code and enough of its surroundings to judge where it belongs.
+
+## Standard
+
+Perform a deep, strict review of implementation quality. Find correctness defects first. Then rethink how the change could be structured to be meaningfully simpler without changing behavior: better abstractions, fewer concepts, less spaghetti, more legible code. Be thorough and rigorous: measure twice, cut once.
+
+Be **ambitious** about structure. Do not stop at local cleanup. Look for the "code judo" move: a reorganization that uses the existing architecture better so that whole branches, helpers, modes, conditionals, or layers disappear, and the code feels inevitable in hindsight. Prefer deleting complexity to rearranging it.
+
+The test for every finding: **what does the next maintainer no longer need to know or do?** Use it to judge; state the answer when it isn't obvious.
+
+When principles conflict, resolve in order; a lower item never overrides a higher one:
+
+1. Contract correctness, including failure and compatibility semantics.
+2. Caller simplicity: fewer things a caller must know or remember.
+3. Fewer concepts: types, layers, parameters, modes.
+4. Fewer lines.
+
+So a long cohesive function beats fragments joined by hidden assumptions, and duplicated code beats coupling unrelated concepts.
+
+## Lenses
+
+Sweep every change through each lens.
+
+### Structure and spaghetti
+
+- New ad-hoc conditionals, scattered special cases, or one-off branches in unrelated flows are a design problem, not a nit. Push the logic into a dedicated abstraction, helper, state machine, policy, or module.
+- One-off booleans, nullable modes, or flags that complicate existing control flow; repeated conditionals that signal a missing model.
+- Narrow edge-case handling in the middle of an already busy function.
+- "Temporary" branching likely to become permanent debt.
+- A file pushed from under 1000 lines to over 1000 is a presumptive blocker: ask whether it should be decomposed first.
+- Refactors that move complexity around without reducing the concepts a reader must hold.
+- Independent work serialized for no reason; related updates that can leave state half-applied.
+
+### Machinery
+
+An abstraction earns its place by deleting something: a check, a rule callers must remember, a branch repeated across modules, a pass-through layer. Name what it deletes. A type, base class, protocol, option, wrapper, or helper that deletes nothing is machinery; flag it. Be skeptical of generic "magic" that hides a simple data shape. Prefer direct, boring code.
+
+### Ownership and contracts
+
+Every responsibility, invariant, and format has one owner. For each one the change touches, name the owner and check the rest of the system defers to it.
+
+- Put work where the knowledge already is. Downstream layers stay generic.
+- Carry a value whole through layers; don't unpack it and rebuild it later.
+- Related facts travel together: if callers reach into `a.b.c` for a fact that belongs with `a`, put it on `a`.
+- When two sides validate the same format, the contract belongs in one shared place. Duplicate validators drift.
+- Feature logic leaking into shared paths, implementation details leaking through APIs, bespoke helpers duplicating a canonical one, and logic in the wrong layer are findings.
+- One conceptual change should touch one place. A diff editing one idea in five files is the finding.
+- Errors are contract: expected outcomes are return variants; caller bugs raise uncaught; environment faults raise with identifying context and are caught only where something can act.
+- A required call order becomes one call, or a type the next call requires.
+- Clocks, randomness, env, and capabilities are passed in where callers need control.
+- Consumers upgrade in lock-step: shims, aliases, and re-exports kept for an old shape are findings.
+- A test that patches internals marks a misplaced seam.
+
+### Illegal state
+
+A type admits a **contradiction** when it can hold a value the domain says cannot exist. Each contradiction forces a **defense** on a consumer: `error ?? "Unknown error"`, `assert x is not None`, a non-null `!`, `raise ValueError("unexpected ...")`, a cast.
+
+List every model, schema, signature, and boundary the change adds or modifies, including persisted state. For each, name the concrete illegal value and the defense it forces, with file and line. A fix succeeds only if it deletes a defense; a new union that deletes none is machinery.
+
+Parse, don't validate: parse untrusted input once, at the outermost boundary that holds it, into a type that cannot hold the contradiction. Reject impossible input there rather than mapping it to the nearest legal state. An illegal combination becomes a visible variant or an error, never a quiet fallback.
+
+Not worth fixing: a value that only packages a branch one caller unpacks immediately; types whose invalid instances stay constructible anyway and closing them removes no checks; contradictions only producible by parse paths that already filter them; independent state machines that would multiply if merged; types a pending redesign deletes anyway.
+
+Also watch: defaulted discriminators dropped by serializers; wire and persisted shapes whose existing tags must keep parsing; hand-written types that should derive from generated ones.
+
+## Approval bar
+
+Do not approve because behavior seems correct. Treat these as presumptive blockers unless clearly justified:
+
+- a correctness defect or contract break;
+- a plausible code-judo move that would delete much incidental complexity;
+- a file pushed past 1000 lines;
+- ad-hoc branching that tangles an existing flow, or feature checks scattered across shared code;
+- an abstraction, wrapper, cast, or optional that makes the design more indirect;
+- a duplicated canonical helper or logic in the wrong layer;
+- a type change that admits a contradiction consumers must defend against.
+
+## Tone and output
+
+Be direct, serious, and demanding. Not rude, but do not soften structural problems into mild suggestions. Prefer a few high-conviction findings to a long list; skip cosmetic nits when larger issues exist. Don't invent issues.
+
+Order findings: correctness, structural regressions and missed simplifications, spaghetti growth, boundary/type/illegal-state problems, file size and decomposition, legibility.
+
+```
+## Verdict
+approve | changes_requested — one sentence why.
+
+## Findings
+- **blocker|major|minor|nit** `path/to/file:line` — the problem; the change; what it deletes.
+
+## Summary
+2–3 sentences.
+```

package/src/reviewer.ts

@@ -0,0 +1,138 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import fs from "node:fs";
+
+export type ReviewOutcome = { kind: "done"; text: string } | { kind: "failed"; error: string };
+
+type State = "running" | "idle" | "dead";
+
+const TOOLS = "read,grep,find,ls,bash";
+
+function piInvocation(args: string[]): { command: string; args: string[] } {
+  const script = process.argv[1];
+  if (script && !script.startsWith("/$bunfs/root/") && fs.existsSync(script)) {
+    return { command: process.execPath, args: [script, ...args] };
+  }
+  return { command: "pi", args };
+}
+
+function tail(text: string): string {
+  return text.trim().split("\n").slice(-5).join("\n");
+}
+
+/**
+ * A long-lived reviewer: a headless pi in RPC mode that keeps its context between rounds.
+ * Every settled run reports one outcome through `onOutcome`.
+ */
+export class Reviewer {
+  readonly id: string;
+  readonly model: string;
+  private state: State = "idle";
+  private readonly proc: ChildProcess;
+  private readonly onOutcome: (reviewer: Reviewer, outcome: ReviewOutcome) => void;
+  private stdout = "";
+  private stderr = "";
+  private lastText = "";
+  private lastError = "";
+
+  constructor(opts: {
+    id: string;
+    model: string;
+    cwd: string;
+    promptFile: string;
+    onOutcome: (reviewer: Reviewer, outcome: ReviewOutcome) => void;
+  }) {
+    this.id = opts.id;
+    this.model = opts.model;
+    this.onOutcome = opts.onOutcome;
+    const inv = piInvocation([
+      "--mode",
+      "rpc",
+      "--no-session",
+      "--model",
+      opts.model,
+      "--tools",
+      TOOLS,
+      "--append-system-prompt",
+      opts.promptFile,
+    ]);
+    this.proc = spawn(inv.command, inv.args, { cwd: opts.cwd, stdio: ["pipe", "pipe", "pipe"] });
+    this.proc.stdout!.on("data", (d) => this.read(d.toString()));
+    this.proc.stderr!.on("data", (d) => (this.stderr += d.toString()));
+    this.proc.on("error", (e) => this.die(String(e)));
+    this.proc.on("exit", (code, signal) => this.die(`reviewer exited (${signal ?? code}). ${tail(this.stderr)}`));
+  }
+
+  get running(): boolean {
+    return this.state === "running";
+  }
+
+  get alive(): boolean {
+    return this.state !== "dead";
+  }
+
+  /**
+   * Steers a running review, or starts a new round in the same context when idle.
+   */
+  send(message: string): void {
+    if (this.state === "dead") throw new Error(`Review ${this.id} has ended; request a new review.`);
+    this.state = "running";
+    this.proc.stdin!.write(`${JSON.stringify({ type: "prompt", message, streamingBehavior: "steer" })}\n`);
+  }
+
+  stop(): void {
+    if (this.state === "dead") return;
+    this.state = "dead";
+    this.proc.stdin!.end();
+    setTimeout(() => this.proc.kill("SIGKILL"), 2000).unref();
+  }
+
+  private read(chunk: string): void {
+    this.stdout += chunk;
+    const lines = this.stdout.split("\n");
+    this.stdout = lines.pop() ?? "";
+    for (const line of lines) {
+      let event: any;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      this.handle(event);
+    }
+  }
+
+  private handle(event: any): void {
+    if (event.type === "response" && !event.success) {
+      this.settle({ kind: "failed", error: `${event.command} rejected: ${event.error}` });
+    } else if (event.type === "message_end" && event.message?.role === "assistant") {
+      const text = (event.message.content as any[])
+        .filter((p) => p.type === "text")
+        .map((p) => p.text)
+        .join("\n")
+        .trim();
+      if (text) this.lastText = text;
+      if (event.message.errorMessage) this.lastError = event.message.errorMessage;
+    } else if (event.type === "agent_settled") {
+      this.settle(
+        this.lastText
+          ? { kind: "done", text: this.lastText }
+          : { kind: "failed", error: this.lastError || "no output" },
+      );
+    }
+  }
+
+  private settle(outcome: ReviewOutcome): void {
+    if (this.state !== "running") return;
+    this.state = "idle";
+    this.lastText = "";
+    this.lastError = "";
+    this.onOutcome(this, outcome);
+  }
+
+  private die(error: string): void {
+    if (this.state === "dead") return;
+    const wasRunning = this.state === "running";
+    this.state = "dead";
+    if (wasRunning) this.onOutcome(this, { kind: "failed", error });
+  }
+}