@erichll/pi-auto-review 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.8.2 - 2026-08-21
+
+- Structure interactive review results as headline, target, rationale, and a
+  meta line with the reviewer model name, input/output tokens, duration, and extra
+  calls. The TUI renders them as markdown-style quote rows (`│` + `mdQuote`),
+  with allow/deny verbs and token counts tinted from the theme. The model id is
+  shown without a provider prefix; audit still records the full `provider/id`.
+  Local hard denies omit model and token fields because no model ran.
+
 ## 0.8.1 - 2026-08-21
 
 - Restore TUI auto-confirm for capped `path` / `external_directory` allows on

package/README.md

@@ -133,8 +133,12 @@ only a fixed, budget-checked schema correction.
 ## Operator feedback and exact retry
 
 Interactive sessions show a best-effort footer while review is running and a
-short result toast for allow, local confirmation, defer, deny, or circuit
-breaker outcomes. UI delivery never changes the authorization result.
+structured result row for allow, local confirmation, defer, deny, or circuit
+breaker outcomes. In the TUI this is a quote-style entry (`│`, muted quote
+color) that separates the outcome and surface from the target and rationale,
+then shows the reviewer model name (without provider prefix), input/output
+tokens, and duration when a model call ran. UI delivery never changes the
+authorization result.
 
 In an interactive TUI, `/auto-review-approve` lists up to ten recent
 non-critical model denials from the current session. Selecting one asks the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-auto-review",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Model-backed boundary approval broker for Pi",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -37,12 +37,17 @@ import {
 } from "./broker/index.ts";
 import { PermissionUiAutoConfirmer } from "./ui-auto-confirm.ts";
 import {
+  buildUserReviewEntryData,
   buildUserReviewNotice,
   buildUserReviewStatus,
   notifyUserReview,
+  presentUserReview,
+  renderUserReviewEntry,
   reviewTargetFromRequest,
   setUserReviewStatus,
+  USER_REVIEW_ENTRY_TYPE,
   type UserReviewOutcome,
+  type UserReviewUsage,
 } from "./user-feedback.ts";
 
 export {
@@ -1330,6 +1335,33 @@ function aggregateUsage(attempts: readonly ReviewAttemptObservation[]): {
   return { availability, usage };
 }
 
+function userReviewMetaFromResult(
+  result: ReviewResult | undefined,
+  fallbackModel: string,
+): {
+  model?: string;
+  usage?: UserReviewUsage;
+  durationMs?: number;
+  attempts?: number;
+} {
+  if (!result) return {};
+  const attempts = result.summary.attempts;
+  const aggregate = aggregateUsage(attempts);
+  return {
+    ...(attempts.length > 0
+      ? {
+          model: attempts.at(-1)?.model ?? fallbackModel,
+          usage: {
+            availability: aggregate.availability,
+            ...aggregate.usage,
+          },
+        }
+      : {}),
+    durationMs: result.durationMs,
+    attempts: result.attempts,
+  };
+}
+
 function completeTelemetry(
   request: BoundaryRequest,
   config: Readonly<Config>,
@@ -1885,6 +1917,11 @@ export function createPiAutoReviewExtension(
     process.env.PI_AUTO_REVIEW_ALLOW_UNTRUSTED_DEV === "1";
 
   return (pi: ExtensionAPI): void => {
+  try {
+    pi.registerEntryRenderer(USER_REVIEW_ENTRY_TYPE, renderUserReviewEntry);
+  } catch {
+    // Renderer registration is observational.
+  }
   let context: ExtensionContext | undefined;
   let config: Readonly<Config> = trustedConfig;
   let disposeAuthorizer: (() => void) | undefined;
@@ -1938,6 +1975,23 @@ export function createPiAutoReviewExtension(
           const execution = error instanceof ReviewExecutionError
             ? error
             : new ReviewExecutionError("unknown", noModelSummary());
+          if (request.source === "permission-system") {
+            reviewResults.set(request.id, {
+              decision: {
+                outcome: config.failureMode,
+                risk_level: "high",
+                user_authorization: "unknown",
+                rationale: "Automatic review is unavailable.",
+              },
+              attempts: execution.summary.attempts.length,
+              retryErrors: execution.summary.attempts
+                .map((attempt) => attempt.errorClass)
+                .filter((errorClass) => errorClass !== "none"),
+              durationMs: execution.summary.durationMs,
+              transcript: execution.summary.transcript,
+              summary: execution.summary,
+            });
+          }
           emitTelemetry(
             completeTelemetry(
               request,
@@ -2263,13 +2317,16 @@ export function createPiAutoReviewExtension(
               surface,
               reason,
             });
-            notifyUserReview(
+            const unavailable = {
+              outcome: "unavailable" as const,
+              surface,
+              rationale: reason,
+            };
+            presentUserReview(
+              pi,
               context,
-              buildUserReviewNotice({
-                outcome: "unavailable",
-                surface,
-                rationale: reason,
-              }),
+              buildUserReviewNotice(unavailable),
+              buildUserReviewEntryData(unavailable),
             );
             return { kind: "deny", reason };
           }
@@ -2310,24 +2367,30 @@ export function createPiAutoReviewExtension(
             } else {
               userOutcome = "deny";
             }
-            notifyUserReview(
+            const reviewMeta = userReviewMetaFromResult(result, config.model);
+            const noticeInput = {
+              outcome: userOutcome,
+              surface,
+              target,
+              rationale: decision.review.rationale,
+              recoveryCommand:
+                decision.kind === "deny"
+                  ? decision.recoveryCommand
+                  : undefined,
+              ...reviewMeta,
+            };
+            presentUserReview(
+              pi,
               context,
-              buildUserReviewNotice({
-                outcome: userOutcome,
-                surface,
-                target,
-                rationale: decision.review.rationale,
-                recoveryCommand:
-                  decision.kind === "deny"
-                    ? decision.recoveryCommand
-                    : undefined,
-              }),
+              buildUserReviewNotice(noticeInput),
+              buildUserReviewEntryData(noticeInput),
             );
 
             log.review("pi_auto_review_decision", {
               requestId: request.id,
               surface,
               model: config.model,
+              reviewerModel: reviewMeta.model,
               outcome: allowCapped ? "defer" : decision.kind,
               reviewerOutcome: decision.review.outcome,
               riskLevel: decision.review.riskLevel,
@@ -2343,6 +2406,8 @@ export function createPiAutoReviewExtension(
               attempts: result?.attempts ?? 0,
               retryErrors: result?.retryErrors ?? [],
               durationMs: result?.durationMs,
+              usageAvailability: reviewMeta.usage?.availability,
+              usage: reviewMeta.usage,
               transcriptUserCharacters: result?.transcript.userCharacters,
               transcriptToolCharacters: result?.transcript.toolCharacters,
               transcriptRelevantResultCharacters:

package/src/user-feedback.ts

@@ -1,6 +1,10 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 
 export const USER_REVIEW_STATUS_KEY = "pi-auto-review";
+export const USER_REVIEW_ENTRY_TYPE = "pi-auto-review";
 
 export type UserReviewOutcome =
   | "allow"
@@ -11,6 +15,23 @@ export type UserReviewOutcome =
   | "circuit_breaker"
   | "unavailable";
 
+export type UserReviewUsageAvailability =
+  | "reported"
+  | "estimated"
+  | "unavailable"
+  | "unknown_provenance";
+
+export type UserReviewUsage = {
+  availability: UserReviewUsageAvailability;
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  reasoning?: number;
+  totalTokens?: number;
+  observedInputTokens?: number;
+};
+
 export type UserReviewNotice = {
   message: string;
   type: "info" | "warning" | "error";
@@ -41,7 +62,7 @@ export function reviewTargetFromRequest(request: {
     request.toolName ??
     request.skillName ??
     request.operation;
-  const compact = compactReviewText(target, 90);
+  const compact = compactReviewText(target, 100);
   return compact || undefined;
 }
 
@@ -52,70 +73,356 @@ export function buildUserReviewStatus(
 ): string {
   const compact = compactReviewText(target, 48);
   return compact
-    ? `auto-review: reviewing ${surface} · ${compact}`
-    : `auto-review: reviewing ${surface}`;
+    ? `auto-review · reviewing · ${surface} · ${compact}`
+    : `auto-review · reviewing · ${surface}`;
 }
 
-/**
- * User-facing (not agent-facing) notice after a review decision.
- * Kept short so TUI toasts remain readable.
- */
-export function buildUserReviewNotice(input: {
+export function formatReviewTokenCount(count: number): string {
+  if (!Number.isFinite(count) || count < 0) return "0";
+  if (count < 1000) return String(Math.round(count));
+  if (count < 10_000) {
+    return `${(count / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+  }
+  if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+}
+
+export function formatReviewDuration(durationMs: number): string | undefined {
+  if (!Number.isFinite(durationMs) || durationMs < 0) return undefined;
+  if (durationMs < 1000) return `${Math.round(durationMs)}ms`;
+  const seconds = durationMs / 1000;
+  return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+
+export function formatReviewUsage(usage: UserReviewUsage): string | undefined {
+  if (usage.availability === "unavailable") return undefined;
+  const parts: string[] = [];
+  const input = usage.input ?? usage.observedInputTokens;
+  if (input !== undefined) {
+    const cache =
+      usage.cacheRead && usage.cacheRead > 0
+        ? ` (${formatReviewTokenCount(usage.cacheRead)} cache)`
+        : "";
+    parts.push(`${formatReviewTokenCount(input)} in${cache}`);
+  }
+  if (usage.output !== undefined) {
+    parts.push(`${formatReviewTokenCount(usage.output)} out`);
+  }
+  if (parts.length === 0 && usage.totalTokens !== undefined) {
+    parts.push(`${formatReviewTokenCount(usage.totalTokens)} tok`);
+  }
+  if (parts.length === 0) return undefined;
+  const approx = usage.availability === "estimated" ? "~" : "";
+  return `${approx}${parts.join(" · ")}`;
+}
+
+/** Display-only model id; drop a leading provider segment when present. */
+export function formatReviewModelName(model: unknown): string | undefined {
+  const raw = String(model ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!raw) return undefined;
+  const slash = raw.indexOf("/");
+  const name =
+    slash > 0 && slash < raw.length - 1 ? raw.slice(slash + 1) : raw;
+  return compactReviewText(name, 42) || undefined;
+}
+
+export function formatReviewMeta(input: {
+  model?: string;
+  usage?: UserReviewUsage;
+  durationMs?: number;
+  attempts?: number;
+}): string | undefined {
+  const parts: string[] = [];
+  const model = formatReviewModelName(input.model);
+  if (model) parts.push(model);
+  if (input.usage) {
+    const usage = formatReviewUsage(input.usage);
+    if (usage) parts.push(usage);
+  }
+  const duration = input.durationMs !== undefined
+    ? formatReviewDuration(input.durationMs)
+    : undefined;
+  if (duration) parts.push(duration);
+  if (input.attempts && input.attempts > 1) {
+    parts.push(`${input.attempts} calls`);
+  }
+  return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+
+function reviewHeadline(outcome: UserReviewOutcome, surface: string): string {
+  switch (outcome) {
+    case "allow":
+      return `Auto-review · allowed · ${surface}`;
+    case "auto_confirm":
+      return `Auto-review · allowed · auto-confirm · ${surface}`;
+    case "needs_confirmation":
+      return `Auto-review · allowed · confirm locally · ${surface}`;
+    case "defer":
+      return `Auto-review · deferred · ${surface}`;
+    case "deny":
+      return `Auto-review · denied · ${surface}`;
+    case "circuit_breaker":
+      return `Auto-review · stopped · ${surface}`;
+    case "unavailable":
+      return `Auto-review · unavailable · ${surface}`;
+  }
+}
+
+function recoveryLine(
+  outcome: UserReviewOutcome,
+  recoveryCommand?: "/auto-review-approve" | "/auto-review-break-glass" | false,
+): string | undefined {
+  if (outcome === "circuit_breaker") {
+    return "use /auto-review-approve for one exact retry";
+  }
+  if (outcome !== "deny") return undefined;
+  if (recoveryCommand === false) {
+    return "local safety denials cannot be overridden";
+  }
+  if (recoveryCommand) {
+    return `use ${recoveryCommand} for one exact retry`;
+  }
+  return undefined;
+}
+
+function joinNoticeLines(lines: Array<string | undefined>): string[] {
+  return lines
+    .map((line) => (typeof line === "string" ? line.trimEnd() : ""))
+    .filter((line) => line.length > 0);
+}
+
+export type UserReviewNoticeInput = {
   outcome: UserReviewOutcome;
   surface: string;
   target?: string;
   rationale?: string;
   recoveryCommand?: "/auto-review-approve" | "/auto-review-break-glass" | false;
-}): UserReviewNotice {
-  const target = compactReviewText(input.target, 70);
-  const rationale = compactReviewText(input.rationale, 120);
-  const subject = target ? `${input.surface} · ${target}` : input.surface;
-  const why = rationale ? ` — ${rationale}` : "";
+  model?: string;
+  usage?: UserReviewUsage;
+  durationMs?: number;
+  attempts?: number;
+};
 
-  switch (input.outcome) {
+export type UserReviewEntryData = {
+  outcome: UserReviewOutcome;
+  type: UserReviewNotice["type"];
+  lines: string[];
+};
+
+type UserReviewTheme = {
+  fg(color: string, text: string): string;
+  italic(text: string): string;
+  getFgAnsi(color: string): string;
+};
+
+function noticeType(outcome: UserReviewOutcome): UserReviewNotice["type"] {
+  if (outcome === "unavailable") return "error";
+  if (outcome === "deny" || outcome === "circuit_breaker") return "warning";
+  return "info";
+}
+
+function outcomeAccent(
+  outcome: UserReviewOutcome,
+): "success" | "warning" | "error" | "muted" {
+  switch (outcome) {
+    case "allow":
+    case "auto_confirm":
+    case "needs_confirmation":
+      return "success";
+    case "defer":
+      return "muted";
+    case "deny":
+    case "circuit_breaker":
+      return "warning";
+    case "unavailable":
+      return "error";
+  }
+}
+
+function outcomeVerb(outcome: UserReviewOutcome): string {
+  switch (outcome) {
     case "allow":
-      return {
-        type: "info",
-        message: `Auto-review allowed ${subject}${why}`,
-      };
     case "auto_confirm":
-      return {
-        type: "info",
-        message: `Auto-review allowed ${subject}; auto-confirming the local dialog${why}`,
-      };
     case "needs_confirmation":
-      return {
-        type: "info",
-        message: `Auto-review allowed ${subject}; local confirmation is still required${why}`,
-      };
+      return "allowed";
     case "defer":
-      return {
-        type: "info",
-        message: `Auto-review deferred ${subject} to you${why}`,
-      };
+      return "deferred";
     case "deny":
-      return {
-        type: "warning",
-        message: `Auto-review denied ${subject}${why}${
-          input.recoveryCommand === false
-            ? " — local safety denials cannot be overridden"
-            : input.recoveryCommand
-              ? ` — use ${input.recoveryCommand} for one exact retry`
-              : ""
-        }`,
-      };
+      return "denied";
     case "circuit_breaker":
-      return {
-        type: "warning",
-        message: `Auto-review stopped after repeated denials this turn${
-          why || " — use /auto-review-approve for one exact retry"
-        }`,
-      };
+      return "stopped";
     case "unavailable":
-      return {
-        type: "error",
-        message: `Auto-review is unavailable${why}`,
-      };
+      return "unavailable";
+  }
+}
+
+export function buildUserReviewLines(input: UserReviewNoticeInput): string[] {
+  return joinNoticeLines([
+    reviewHeadline(input.outcome, input.surface),
+    compactReviewText(input.target, 100) || undefined,
+    compactReviewText(input.rationale, 180) || undefined,
+    recoveryLine(input.outcome, input.recoveryCommand),
+    formatReviewMeta({
+      model: input.model,
+      usage: input.usage,
+      durationMs: input.durationMs,
+      attempts: input.attempts,
+    }),
+  ]);
+}
+
+/**
+ * User-facing (not agent-facing) notice after a review decision.
+ * Structured for TUI wrapping: headline, target, rationale, then model/tokens.
+ */
+export function buildUserReviewNotice(
+  input: UserReviewNoticeInput,
+): UserReviewNotice {
+  return {
+    type: noticeType(input.outcome),
+    message: buildUserReviewLines(input).join("\n"),
+  };
+}
+
+export function buildUserReviewEntryData(
+  input: UserReviewNoticeInput,
+): UserReviewEntryData {
+  return {
+    outcome: input.outcome,
+    type: noticeType(input.outcome),
+    lines: buildUserReviewLines(input),
+  };
+}
+
+export function formatUserReviewQuoteMessage(message: string): string {
+  return message
+    .split("\n")
+    .map((line) => `│ ${line}`)
+    .join("\n");
+}
+
+function displayWidth(text: string): number {
+  let width = 0;
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    width += code > 0xff ? 2 : 1;
+  }
+  return width;
+}
+
+export function wrapReviewDisplayText(text: string, width: number): string[] {
+  if (width <= 0) return [text];
+  const lines: string[] = [];
+  let current = "";
+  let currentWidth = 0;
+  const flush = () => {
+    if (current.length > 0) lines.push(current);
+    current = "";
+    currentWidth = 0;
+  };
+  for (const token of text.split(/(\s+)/)) {
+    const tokenWidth = displayWidth(token);
+    if (currentWidth + tokenWidth <= width) {
+      current += token;
+      currentWidth += tokenWidth;
+      continue;
+    }
+    if (/^\s+$/.test(token)) {
+      flush();
+      continue;
+    }
+    if (currentWidth > 0) flush();
+    if (tokenWidth <= width) {
+      current = token;
+      currentWidth = tokenWidth;
+      continue;
+    }
+    for (const char of token) {
+      const charWidth = (char.codePointAt(0) ?? 0) > 0xff ? 2 : 1;
+      if (currentWidth + charWidth > width) flush();
+      current += char;
+      currentWidth += charWidth;
+    }
+  }
+  flush();
+  return lines.length > 0 ? lines : [""];
+}
+
+function withQuoteStyle(theme: UserReviewTheme, text: string): string {
+  const marker = "\u0000";
+  const prefix = theme.italic(theme.fg("mdQuote", marker)).split(marker)[0] ?? "";
+  const body = theme.italic(theme.fg("mdQuote", text));
+  return prefix ? body.replace(/\x1b\[0m/g, `\x1b[0m${prefix}`) : body;
+}
+
+export function renderUserReviewQuoteLines(
+  data: UserReviewEntryData,
+  theme: UserReviewTheme,
+  width: number,
+): string[] {
+  const contentWidth = Math.max(1, width - 2);
+  const border = theme.fg("mdQuoteBorder", "│ ");
+  const verb = outcomeVerb(data.outcome);
+  const verbAnsi = theme.getFgAnsi(outcomeAccent(data.outcome));
+  const numberAnsi = theme.getFgAnsi("success");
+  const rendered: string[] = [];
+  for (const [index, line] of data.lines.entries()) {
+    for (const visual of wrapReviewDisplayText(line, contentWidth)) {
+      let painted = visual;
+      if (index === 0) {
+        painted = painted.replace(
+          verb,
+          `${verbAnsi}${verb}\x1b[0m`,
+        );
+      }
+      if (index === data.lines.length - 1) {
+        painted = painted.replace(
+          /(\d+(?:\.\d+)?[kM]?)(?=\s(?:in|out|tok|cache|calls)|ms\b|s\b)/g,
+          `${numberAnsi}$1\x1b[0m`,
+        );
+      }
+      rendered.push(border + withQuoteStyle(theme, painted));
+    }
+  }
+  return rendered;
+}
+
+export function renderUserReviewEntry(
+  entry: { data?: unknown },
+  _options: unknown,
+  theme: UserReviewTheme,
+): { render(width: number): string[]; invalidate(): void } | undefined {
+  const data = entry.data;
+  if (
+    !data ||
+    typeof data !== "object" ||
+    !Array.isArray((data as UserReviewEntryData).lines) ||
+    (data as UserReviewEntryData).lines.length === 0
+  ) {
+    return undefined;
+  }
+  const parsed = data as UserReviewEntryData;
+  return {
+    render(width: number) {
+      return renderUserReviewQuoteLines(parsed, theme, width);
+    },
+    invalidate() {},
+  };
+}
+
+function presentUserReviewEntry(
+  pi: ExtensionAPI | undefined,
+  ctx: ExtensionContext | undefined,
+  data: UserReviewEntryData,
+): boolean {
+  if (!pi || !ctx?.hasUI || ctx.mode !== "tui") return false;
+  try {
+    pi.appendEntry(USER_REVIEW_ENTRY_TYPE, data);
+    return true;
+  } catch {
+    return false;
   }
 }
 
@@ -126,12 +433,23 @@ export function notifyUserReview(
 ): void {
   if (!ctx?.hasUI) return;
   try {
-    ctx.ui.notify(notice.message, notice.type);
+    ctx.ui.notify(formatUserReviewQuoteMessage(notice.message), notice.type);
   } catch {
     // UI delivery is observational and must not change a decision.
   }
 }
 
+/** TUI quote-style entry when possible; otherwise a quoted notify toast. */
+export function presentUserReview(
+  pi: ExtensionAPI | undefined,
+  ctx: ExtensionContext | undefined,
+  notice: UserReviewNotice,
+  data: UserReviewEntryData,
+): void {
+  if (presentUserReviewEntry(pi, ctx, data)) return;
+  notifyUserReview(ctx, notice);
+}
+
 /** Best-effort footer status; pass undefined to clear. */
 export function setUserReviewStatus(
   ctx: ExtensionContext | undefined,