@zephyrdeng/pi-review 0.12.0 → 0.13.0

package/extensions/panel-tool.ts

@@ -13,6 +13,7 @@ import {
   formatTokens,
   formatUsage,
   reducePanelEvent,
+  resolveExclusivePanelShape,
   spawnStreamingChild,
   type PanelReviewMeta,
   type PanelViewState,
@@ -147,15 +148,21 @@ function reviewerSummaryLines(state: PanelViewState): string[] {
  * Full panel conclusion for the parent LLM and expanded TUI.
  * Pure plain text / ASCII only — Pi does not render markdown in tool results.
  */
-export function buildPanelResultContent(state: PanelViewState, error?: string): string {
+export function buildPanelResultContent(state: PanelViewState, error?: string, note?: string): string {
   const meta = state.meta;
-  if (!meta && !error) return "Panel completed: unknown";
-  if (!meta) return error ?? "Panel completed: unknown";
+  if (!meta && !error) {
+    return note ? `${PANEL_TOOL_DISPLAY_NAME}: ${note}\n\nPanel completed: unknown` : "Panel completed: unknown";
+  }
+  if (!meta) {
+    const body = error ?? "Panel completed: unknown";
+    return note ? `${PANEL_TOOL_DISPLAY_NAME}: ${note}\n\n${body}` : body;
+  }
 
   const findings = formatFindingsPlain(meta);
   const ascii = formatPanelMetaAscii(meta);
   const summaries = reviewerSummaryLines(state);
   const parts = [
+    note ? `${PANEL_TOOL_DISPLAY_NAME}: ${note}` : "",
     findings,
     ascii,
     summaries.length ? `Reviewer summaries:\n${summaries.join("\n")}` : "",
@@ -259,15 +266,35 @@ export type PanelToolParams = {
   reviewers?: number;
 };
 
-/** Runtime guard for direct tool calls; schema validation is not the only boundary. */
-export function panelToolParamError(params: PanelToolParams): string | undefined {
+export type NormalizedPanelToolParams = {
+  panel?: string;
+  reviewers?: number;
+  /** Set when both panel and reviewers were provided and reviewers was dropped. */
+  note?: string;
+};
+
+/**
+ * Normalize agent tool args. Named presets own width/roles; if both `panel` and
+ * `reviewers` are set, prefer panel (common host habit) instead of hard-failing.
+ */
+export function normalizePanelToolParams(params: PanelToolParams): NormalizedPanelToolParams | { error: string } {
   if (params.reviewers !== undefined) {
     if (!Number.isSafeInteger(params.reviewers) || params.reviewers < 2 || params.reviewers > 8) {
-      return "reviewers must be an integer between 2 and 8; use the shell CLI for a single reviewer";
+      return { error: "reviewers must be an integer between 2 and 8; use the shell CLI for a single reviewer" };
     }
-    if (params.panel) return "panel cannot be combined with reviewers";
   }
-  return undefined;
+  const shape = resolveExclusivePanelShape(params);
+  const note =
+    shape.ignoredReviewers !== undefined
+      ? `ignored reviewers=${shape.ignoredReviewers}; panel "${shape.panel}" defines the reviewer set`
+      : undefined;
+  return { panel: shape.panel, reviewers: shape.reviewers, ...(note ? { note } : {}) };
+}
+
+/** Runtime guard for direct tool calls; schema validation is not the only boundary. */
+export function panelToolParamError(params: PanelToolParams): string | undefined {
+  const normalized = normalizePanelToolParams(params);
+  return "error" in normalized ? normalized.error : undefined;
 }
 
 export function registerPanelReviewTool(pi: ExtensionAPI): void {
@@ -279,8 +306,8 @@ export function registerPanelReviewTool(pi: ExtensionAPI): void {
     parameters: Type.Object({
       target: Type.String({ description: "Review target as given by the user, such as @src, @src/foo.ts, or a free-text brief. Directories stay tool path targets; only real files are attached." }),
       mode: Type.Optional(Type.String({ description: "Review mode; defaults to code." })),
-      panel: Type.Optional(Type.String({ description: "Named panel preset; defaults to code-experts when reviewers is omitted." })),
-      reviewers: Type.Optional(Type.Number({ minimum: 2, maximum: 8, description: "Independent reviewer count (2-8). Cannot combine with panel; single review uses the shell CLI." })),
+      panel: Type.Optional(Type.String({ description: "Named panel preset; defaults to code-experts when reviewers is omitted. If both panel and reviewers are set, panel wins." })),
+      reviewers: Type.Optional(Type.Number({ minimum: 2, maximum: 8, description: "Independent reviewer count (2-8). Omit when panel is set (panel wins if both appear). Single review uses the shell CLI." })),
       reviewerModels: Type.Optional(Type.Array(Type.String(), { description: "Per-reviewer models as id=provider/model[:thinking] (e.g. r1=openai/gpt-5.6-sol:low). Trailing :thinking wins over shared thinking." })),
       consensus: Type.Optional(Type.String({ description: "any | quorum | majority | unanimous" })),
       minAgree: Type.Optional(Type.Number({ description: "Quorum threshold when consensus=quorum" })),
@@ -317,26 +344,29 @@ export function registerPanelReviewTool(pi: ExtensionAPI): void {
       const stdoutSink = new Writable({ write(chunk, _encoding, callback) { consume(String(chunk)); callback(); } });
       const stderrSink = new Writable({
         write(chunk, _encoding, callback) {
+          // Keep a larger tail so child crash stacks (issue #8) survive when the
+          // panel CLI itself fails before emitting a final event.
           const next = stderr + String(chunk);
-          stderr = next.length > 2000 ? next.slice(-2000) : next;
+          stderr = next.length > 12_000 ? next.slice(-12_000) : next;
           callback();
         },
       });
       // Preserve the full panel configuration and enforce the panel-only tool boundary.
-      const paramError = panelToolParamError(params);
-      if (paramError) {
+      const normalized = normalizePanelToolParams(params);
+      if ("error" in normalized) {
         setAmbientStatus(toolCtx, undefined);
         return {
-          content: [{ type: "text", text: `${PANEL_TOOL_DISPLAY_NAME}: ${paramError}` }],
-          details: { state, error: paramError },
+          content: [{ type: "text", text: `${PANEL_TOOL_DISPLAY_NAME}: ${normalized.error}` }],
+          details: { state, error: normalized.error },
           isError: true,
         };
       }
+      const shapeNote = normalized.note;
       const args = [cliPath, "--mode", params.mode ?? "code", "--output-format", "events-jsonl"];
-      if (params.reviewers !== undefined) {
-        args.push("--reviewers", String(params.reviewers));
+      if (normalized.reviewers !== undefined) {
+        args.push("--reviewers", String(normalized.reviewers));
       } else {
-        args.push("--panel", params.panel ?? "code-experts");
+        args.push("--panel", normalized.panel ?? "code-experts");
       }
       for (const mapping of params.reviewerModels ?? []) args.push("--reviewer-model", mapping);
       if (params.consensus) args.push("--consensus", params.consensus);
@@ -374,14 +404,16 @@ export function registerPanelReviewTool(pi: ExtensionAPI): void {
       const details: PanelToolDetails = { state, ...(error ? { error } : {}) };
       return {
         // Parent LLM must receive the full conclusion; details remain the TUI rendering source.
-        content: [{ type: "text", text: buildPanelResultContent(state, error) }],
+        content: [{ type: "text", text: buildPanelResultContent(state, error, shapeNote) }],
         details,
         ...(error ? { isError: true } : {}),
       };
     },
     renderCall(args, theme, context) {
       const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-      const width = args.reviewers !== undefined ? `reviewers=${args.reviewers}` : (args.panel ?? "code-experts");
+      const shape = resolveExclusivePanelShape(args);
+      const width =
+        shape.reviewers !== undefined ? `reviewers=${shape.reviewers}` : (shape.panel ?? "code-experts");
       text.setText(theme.fg("toolTitle", theme.bold(`${PANEL_TOOL_DISPLAY_NAME} `)) + theme.fg("muted", `${width} · ${args.mode ?? "code"} · ${args.target}`));
       return text;
     },

package/extensions/rv-completions.ts

@@ -77,7 +77,7 @@ export const FLAG_HINTS: Record<string, string> = {
   "--max-rounds": "Loop hard budget: how many review gates (not reviewer count)",
   "--until": "Loop stop goal: clean",
   "--reviewers": "Panel width: independent reviewers per gate (1-8)",
-  "--panel": "Named expert panel preset (cannot combine with --reviewers)",
+  "--panel": "Named expert panel preset (if both set with --reviewers, --panel wins)",
   "--reviewer-model": "Per-reviewer model: pick rK= then model (repeatable)",
   "--consensus": "any | quorum | majority | unanimous",
   "--min-agree": "Quorum threshold (quorum only)",

package/extensions/rv-prompts.test.ts

@@ -84,7 +84,8 @@ describe("parseRvArgs / validateRvParsed", () => {
     assert.match(prompt, /natural-language review request/);
     assert.match(prompt, /Do not expand directory targets into multi-file lists/);
     assert.match(prompt, /panel="code-experts"/);
-    assert.match(prompt, /Do not drop panel\/reviewers\/reviewerModels\/consensus fields/);
+    assert.match(prompt, /Pass only one of panel or reviewers/);
+    assert.match(prompt, /panel wins/);
     assert.match(prompt, /Slash commands select strategy only/);
     assert.doesNotMatch(prompt, /@src\/panel\.ts|@src\/json-events\.ts/);
   });
@@ -235,10 +236,19 @@ describe("parseRvArgs / validateRvParsed", () => {
     ]);
   });
 
-  it("rejects incompatible panel strategy combinations", () => {
+  it("panel + reviewers is accepted and builders prefer panel", () => {
     const both = parseRvArgs("--reviewers 3 --panel code-experts @src", "loop");
-    assert.equal(validateRvParsed(both).ok, false);
+    assert.equal(validateRvParsed(both).ok, true);
+    const argv = buildPiReviewArgv(both, "@src");
+    assert.ok(argv.includes("--panel"));
+    assert.ok(argv.includes("code-experts"));
+    assert.ok(!argv.includes("--reviewers"));
+    const instruction = buildPiReviewToolCallInstruction(both, "@src");
+    assert.match(instruction, /panel="code-experts"/);
+    assert.doesNotMatch(instruction, /reviewers=3/);
+  });
 
+  it("rejects incompatible panel strategy combinations", () => {
     const badConsensus = parseRvArgs("--reviewers 3 --consensus nope @src", "loop");
     assert.equal(validateRvParsed(badConsensus).ok, false);
 

package/extensions/rv-prompts.ts

@@ -52,7 +52,7 @@ export type RvParsed = {
   /** Panel width: independent reviewers for one gate (and each loop round). */
   reviewers?: number;
   reviewersError?: string;
-  /** Named panel preset (e.g. code-experts). Cannot combine with --reviewers. */
+  /** Named panel preset (e.g. code-experts). If both panel and reviewers are set, panel wins. */
   panel?: string;
   /** Per-reviewer model overrides: id=provider/model (repeatable). */
   reviewerModels?: string[];
@@ -403,31 +403,31 @@ export function validateRvParsed(parsed: RvParsed): RvValidation {
   if (parsed.until !== undefined && parsed.strategy !== "loop") {
     return { ok: false, message: "--until is only valid with /rv-loop." };
   }
-  if (parsed.reviewers !== undefined && parsed.panel) {
-    return { ok: false, message: "--reviewers cannot be used with --panel" };
-  }
+  // panel + reviewers is allowed at parse time; builders prefer panel (see preferPanelShape).
   if (parsed.reviewers !== undefined && (parsed.reviewers < 1 || parsed.reviewers > RV_MAX_REVIEWERS)) {
     return { ok: false, message: `--reviewers must be between 1 and ${RV_MAX_REVIEWERS}` };
   }
+  const shape = preferPanelShape(parsed);
   const hasPanelOnlyOptions =
     parsed.consensus !== undefined ||
     parsed.minAgree !== undefined ||
     parsed.consensusModel !== undefined ||
     parsed.concurrency !== undefined ||
     (parsed.reviewerModels?.length ?? 0) > 0;
-  if (parsed.reviewers === 1 && hasPanelOnlyOptions) {
+  if (shape.reviewers === 1 && !shape.panel && hasPanelOnlyOptions) {
     return { ok: false, message: "panel options require --reviewers > 1 or --panel" };
   }
   if (parsed.minAgree !== undefined) {
     if (parsed.consensus && parsed.consensus !== "quorum") {
       return { ok: false, message: "--min-agree is only valid with --consensus quorum" };
     }
-    if (parsed.reviewers !== undefined && parsed.minAgree > parsed.reviewers) {
-      return { ok: false, message: `--min-agree ${parsed.minAgree} cannot exceed reviewers ${parsed.reviewers}` };
+    // Named panels resolve width later; only compare against explicit numeric width.
+    if (shape.reviewers !== undefined && parsed.minAgree > shape.reviewers) {
+      return { ok: false, message: `--min-agree ${parsed.minAgree} cannot exceed reviewers ${shape.reviewers}` };
     }
   }
-  if (parsed.concurrency !== undefined && parsed.reviewers !== undefined && parsed.concurrency > parsed.reviewers) {
-    return { ok: false, message: `--concurrency ${parsed.concurrency} cannot exceed reviewers ${parsed.reviewers}` };
+  if (parsed.concurrency !== undefined && shape.reviewers !== undefined && parsed.concurrency > shape.reviewers) {
+    return { ok: false, message: `--concurrency ${parsed.concurrency} cannot exceed reviewers ${shape.reviewers}` };
   }
   for (const flag of FLAGS_REQUIRING_VALUE) {
     if (parsed.target === flag) {
@@ -445,6 +445,17 @@ export function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 
+/** Prefer named panel over numeric width when both appear (matches CLI/tool soft-resolve). */
+export function preferPanelShape(parsed: Pick<RvParsed, "panel" | "reviewers">): {
+  panel?: string;
+  reviewers?: number;
+} {
+  if (parsed.panel !== undefined && parsed.reviewers !== undefined) {
+    return { panel: parsed.panel };
+  }
+  return { panel: parsed.panel, reviewers: parsed.reviewers };
+}
+
 /** Same optional flags for initial review and --continue follow-up (all optional). */
 export function buildPiReviewArgv(parsed: RvParsed, target: string): string[] {
   const parts = ["pi-review"];
@@ -470,8 +481,9 @@ export function buildPiReviewArgv(parsed: RvParsed, target: string): string[] {
   if (parsed.model) parts.push("--model", parsed.model);
   if (parsed.thinking) parts.push("--thinking", parsed.thinking);
   if (parsed.noStream) parts.push("--no-stream");
-  if (parsed.panel) parts.push("--panel", parsed.panel);
-  if (parsed.reviewers !== undefined) parts.push("--reviewers", String(parsed.reviewers));
+  const shape = preferPanelShape(parsed);
+  if (shape.panel) parts.push("--panel", shape.panel);
+  if (shape.reviewers !== undefined) parts.push("--reviewers", String(shape.reviewers));
   for (const mapping of parsed.reviewerModels ?? []) parts.push("--reviewer-model", mapping);
   if (parsed.consensus) parts.push("--consensus", parsed.consensus);
   if (parsed.minAgree !== undefined) parts.push("--min-agree", String(parsed.minAgree));
@@ -488,12 +500,13 @@ export function formatPiReviewCommandLine(parsed: RvParsed, target: string): str
 
 /** Build the native pi_review tool call instruction without dropping panel config. */
 export function buildPiReviewToolCallInstruction(parsed: RvParsed, target: string): string {
+  const shape = preferPanelShape(parsed);
   const fields: string[] = [
     `target=${JSON.stringify(target)}`,
     `mode=${JSON.stringify(parsed.mode)}`,
   ];
-  if (parsed.panel) fields.push(`panel=${JSON.stringify(parsed.panel)}`);
-  if (parsed.reviewers !== undefined) fields.push(`reviewers=${parsed.reviewers}`);
+  if (shape.panel) fields.push(`panel=${JSON.stringify(shape.panel)}`);
+  if (shape.reviewers !== undefined) fields.push(`reviewers=${shape.reviewers}`);
   if (parsed.reviewerModels?.length) fields.push(`reviewerModels=${JSON.stringify(parsed.reviewerModels)}`);
   if (parsed.consensus) fields.push(`consensus=${JSON.stringify(parsed.consensus)}`);
   if (parsed.minAgree !== undefined) fields.push(`minAgree=${parsed.minAgree}`);
@@ -502,10 +515,10 @@ export function buildPiReviewToolCallInstruction(parsed: RvParsed, target: strin
   if (parsed.model) fields.push(`model=${JSON.stringify(parsed.model)}`);
   if (parsed.thinking) fields.push(`thinking=${JSON.stringify(parsed.thinking)}`);
   // Default panel when /rv has no explicit width/preset: keep code-experts.
-  if (parsed.strategy === "panel" && !parsed.panel && parsed.reviewers === undefined) {
+  if (parsed.strategy === "panel" && !shape.panel && shape.reviewers === undefined) {
     fields.push(`panel=${JSON.stringify("code-experts")}`);
   }
-  return `Call pi_review with ${fields.join(", ")}. Treat target as a natural-language review request. Do not expand directory targets into multi-file lists. Do not drop panel/reviewers/reviewerModels/consensus fields.`;
+  return `Call pi_review with ${fields.join(", ")}. Treat target as a natural-language review request. Do not expand directory targets into multi-file lists. Pass only one of panel or reviewers (if both appear, panel wins). Keep reviewerModels/consensus/minAgree when provided.`;
 }
 
 export function orchestrationLocaleNote(locale: RvLocale = "en"): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zephyrdeng/pi-review",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Isolated AI-powered code and plan reviews from the command line",
   "type": "module",
   "author": "ZephyrDeng <zephyrTang@aliyun.com>",

package/skills/pi-review/SKILL.md

@@ -27,7 +27,7 @@ node ../../bin/pi-review.js --help
 |------|-------------------------|
 | **Pi** (`/rv`) | New panel reviews call the native `pi_review` API tool, shown to users as **Pi Review Panel**, which launches the packaged CLI in event mode and renders live reviewer state. Continuations, kept sessions, `/rv-loop`, and explicit `--no-stream` use the shell CLI. |
 | **Pi terminal** | Foreground `pi-review`; text deltas stream live by default. |
-| **Claude Code / Codex / Cursor** and similar agent hosts | These hosts buffer a shell tool's output until the command exits, so a foreground run looks like a silent wait. **Panel review (`--reviewers`/`--panel`) default: `--ui web --ui-url-file <path>` + background run** — get the dashboard in front of the user: on Claude Code the CLI auto-open lands in the system default browser; on Codex open the `--ui-url-file` URL in the host's built-in browser (the CLI cannot reach a GUI there); hand over the URL as fallback either way. **Single review / `loop` default: `--progress-log <path>` + background run + tail the log** (`--ui web` requires an active panel and rejects `loop`). See [references/codex-tools.md](./references/codex-tools.md). Map skill mentions of `Bash` to your host shell tool. |
+| **Claude Code / Codex / Cursor / agy (Antigravity)** and similar agent hosts | These hosts buffer a shell tool's output until the command exits, so a foreground run looks like a silent wait. **Panel review (`--reviewers`/`--panel`) default: `--ui web --ui-url-file <path>` + background run** — get the dashboard in front of the user: on Claude Code the CLI auto-open lands in the system default browser; on Codex open the `--ui-url-file` URL in the host's built-in browser (the CLI cannot reach a GUI there); on agy prefer the host browser / share the URL the same way; hand over the URL as fallback either way. **Single review / `loop` default: `--progress-log <path>` + background run + tail the log** (`--ui web` requires an active panel and rejects `loop`). See [references/codex-tools.md](./references/codex-tools.md). Map skill mentions of `Bash` to your host shell tool. |
 | Scripts / CI | Foreground is fine; add `--no-stream` only when the caller must buffer until exit (cannot combine with `--progress-log`). |
 
 `--progress-log <path>` tees a compact `--mode json` event stream to a file for outside observation and debugging (each `message_update` reduces its cumulative message snapshots to `usage` to keep the file small; add `--progress-log-raw` for the verbatim stream); it is never a prerequisite for metrics. Token usage accumulates by default, and `pi-review` writes milestone notices (`pi-review: review started`, `pi-review: tool <name> started/finished`, `pi-review: review finished`) to stderr.

package/skills/pi-review/references/codex-tools.md

@@ -1,6 +1,6 @@
-# Agent host tool notes (Codex / Claude Code)
+# Agent host tool notes (Codex / Claude Code / Cursor / agy)
 
-Skills may use Claude Code tool names. On **Codex** or **Claude Code**, map them to your native tools:
+Skills may use Claude Code tool names. On **Codex**, **Claude Code**, **Cursor**, or **agy (Antigravity)**, map them to your native tools:
 
 | Skill references | Typical host equivalent |
 |-----------------|-------------------------|
@@ -10,13 +10,13 @@ Skills may use Claude Code tool names. On **Codex** or **Claude Code**, map them
 
 This file is **pi-review–specific** and ships with the pi-review package.
 
-## Long-running `pi-review` (default on Codex / Claude Code)
+## Long-running `pi-review` (default on Codex / Claude Code / Cursor / agy)
 
 Native shell tools on these hosts **buffer stdout/stderr until the command exits**. A multi-minute foreground `pi-review` run looks like a silent wait, then one large dump — never promise live foreground streaming. Which side channel to use depends on the run type: panel review gets the browser dashboard; single review and `loop` get the tailed progress log.
 
 ### Panel review: browser dashboard (default)
 
-`--reviewers <n>` or `--panel <name>` activates panel review. On Codex, Claude Code, or Cursor, default to the dashboard instead of a tailed log:
+`--reviewers <n>` or `--panel <name>` activates panel review. On Codex, Claude Code, Cursor, or agy, default to the dashboard instead of a tailed log:
 
 1. Run `pi-review --reviewers <n> --ui web --ui-url-file <path> -- <target>` (or `--panel <name>`) in the **background**. Pass `--no-ui-open` only when the user asked not to open a browser (CI, remote shells).
 2. Read `<path>` shortly after launch — it is written atomically as soon as the dashboard server is ready, well before reviewers finish (poll a few times a second for a couple of seconds if the file is not there yet). Then get the dashboard in front of the user: on **Claude Code** the CLI auto-open already lands in the system default browser; on **Codex** the CLI cannot reach a GUI browser, so open the URL from `<path>` in the host's built-in browser yourself. Share the URL either way as a fallback: *"Dashboard opened in your browser (URL: `<url>`). I'll report back when the review completes."*
@@ -32,7 +32,7 @@ Native shell tools on these hosts **buffer stdout/stderr until the command exits
 
 **Pi interactive (`/rv`)**: foreground `pi-review`, default streaming. Text deltas appear live on the terminal; no `--progress-log`/`--ui web` unless the user asked — Pi already renders panel progress natively.
 
-See the parent skill: sections *Default workflow by host* and *Streaming vs agent hosts (Claude Code / Codex)*.
+See the parent skill section *Default workflow by host* (Claude Code / Codex / Cursor / agy row).
 
 ### Loop closeout
 

package/skills/pi-review/references/model-selection.md

@@ -2,7 +2,7 @@
 
 Use this after `pi-review models` (or `pi-review models <search>`). **Never invent** `provider/model` IDs—only IDs that appear in that output.
 
-## Workflow (Claude Code, Codex, Cursor, Pi parent agent)
+## Workflow (Claude Code, Codex, Cursor, agy, Pi parent agent)
 
 1. Run `pi-review models` (narrow with search if the user named a vendor or model family).
 2. Infer **review profile** from the target (see table below).