@erichll/pi-auto-review 0.16.0 → 0.18.0

package/src/review/types.ts

@@ -0,0 +1,207 @@
+import {
+  completeSimple,
+  type ApiStreamSimpleFunction,
+} from "@earendil-works/pi-ai/compat";
+import type { ModelDecision, TranscriptResult } from "../policy.ts";
+import type { PolicyAuditConfig } from "../policy-audit/index.ts";
+
+export type ReasoningLevel =
+  | "off"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max";
+
+export type BoundedSurface = "external_directory" | "path";
+
+export type Config = {
+  model: string;
+  reasoning: ReasoningLevel;
+  timeoutMs: number;
+  maxTokens: number;
+  retries: number;
+  maxUserTranscriptTokens: number;
+  maxToolTranscriptTokens: number;
+  maxRelevantResultTokens: number;
+  maxReviewerInputTokens: number;
+  breakGlassEnabled: boolean;
+  failureMode: "deny" | "defer";
+  grantTtlMs: number;
+  autoConfirmBoundedAllows: readonly BoundedSurface[];
+  policyAudit: Readonly<PolicyAuditConfig>;
+};
+
+export type CompletionMessage = {
+  stopReason?: string;
+  responseModel?: string;
+  errorMessage?: string;
+  content?: Array<{ type?: string; text?: string }>;
+  usage?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    reasoning?: number;
+    totalTokens?: number;
+  };
+};
+
+export type UsageAvailability =
+  | "reported"
+  | "estimated"
+  | "unavailable"
+  | "unknown_provenance";
+
+export type ReviewUsage = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  reasoning?: number;
+  totalTokens?: number;
+  observedInputTokens?: number;
+};
+
+export type ReviewAttemptStatus =
+  | "success"
+  | "format_error"
+  | "non_stop"
+  | "transport_failure"
+  | "timeout"
+  | "abort";
+
+export type ReviewErrorClass =
+  | "none"
+  | "non_json"
+  | "schema"
+  | "empty_output"
+  | "output_limit"
+  | "provider_stop"
+  | "transient_connection"
+  | "transient_server"
+  | "rate_limit"
+  | "timeout"
+  | "abort"
+  | "authentication"
+  | "model_resolution"
+  | "request_configuration"
+  | "circuit_breaker"
+  | "critical_evidence_overflow"
+  | "required_profile_overflow"
+  | "reviewer_input_budget_exceeded"
+  | "unknown";
+
+export type ReviewAttemptObservation = {
+  attempt: number;
+  model: string;
+  status: ReviewAttemptStatus;
+  errorClass: ReviewErrorClass;
+  stopReason: "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred" | "unknown";
+  durationMs: number;
+  willRetry: boolean;
+  usageAvailability: UsageAvailability;
+  usage: ReviewUsage;
+};
+
+export type PreflightPart = { characters: number; estimatedTokens: number };
+
+export type ReviewPreflight = {
+  estimator: "conservative:cjk-aware";
+  maxReviewerInputTokens: number;
+  framingReserveTokens: number;
+  fixedPrompt: PreflightPart;
+  canonicalRequest: PreflightPart;
+  override: PreflightPart;
+  user: PreflightPart;
+  tool: PreflightPart;
+  relevantResult: PreflightPart;
+  framing: PreflightPart;
+  total: PreflightPart;
+};
+
+export type ReviewExecutionSummary = {
+  attempts: ReviewAttemptObservation[];
+  errorCounts: Partial<Record<Exclude<ReviewErrorClass, "none">, number>>;
+  durationMs: number;
+  transcript: TranscriptResult;
+  preflight: ReviewPreflight;
+};
+
+export type ReviewerTelemetryEvent =
+  | ({
+      type: "review_attempt";
+      requestId: string;
+      surface: string;
+    } & ReviewAttemptObservation)
+  | {
+      type: "review_complete";
+      requestId: string;
+      surface: string;
+      model: string;
+      reasoning: ReasoningLevel;
+      outcome: "allow" | "deny" | "defer";
+      failureMode?: "deny" | "defer";
+      attempts: number;
+      errorCounts: ReviewExecutionSummary["errorCounts"];
+      durationMs: number;
+      usageAvailability: UsageAvailability;
+      usage: ReviewUsage;
+      transcript: {
+        userCharacters: number;
+        toolCharacters: number;
+        relevantResultCharacters: number;
+        truncated: boolean;
+        selectedCandidates: TranscriptResult["selectedCandidates"];
+        failureCode?: TranscriptResult["failureCode"];
+        userAuthorizationCeiling: TranscriptResult["userAuthorizationCeiling"];
+        userConstraint: TranscriptResult["userConstraint"];
+        compactionState: TranscriptResult["compactionState"];
+        budgetRemovals: TranscriptResult["budgetRemovals"];
+      };
+      preflight: ReviewPreflight;
+    };
+
+export type ReviewerRuntime = {
+  model: Parameters<typeof completeSimple>[0];
+  auth: {
+    apiKey?: string;
+    // ProviderHeaders allows null values (e.g. "clear" directives) in 0.84.x.
+    headers?: Record<string, string | null>;
+    env?: Record<string, string>;
+  };
+  streamSimple?: ApiStreamSimpleFunction;
+  sessionId: string;
+};
+
+// Model/stream metadata is re-resolved for every review instead of being
+// cached for the session: pi can refresh models.json or re-register a
+// provider while a session is live, and the resolved model's baseUrl, api
+// or streamSimple may have changed, so a per-session cache could keep
+// calling a stale endpoint. Authentication is also deliberately excluded
+// because pi resolves models.json auth and headers dynamically on every
+// request (including OAuth refresh); it is reacquired per model call in
+// complete().
+export type ReviewerMeta = Omit<ReviewerRuntime, "auth" | "sessionId">;
+
+export type ReviewResult = {
+  decision: ModelDecision;
+  attempts: number;
+  retryErrors: ReviewErrorClass[];
+  durationMs: number;
+  transcript: TranscriptResult;
+  summary: ReviewExecutionSummary;
+  unavailable?: boolean;
+};
+
+export class ReviewExecutionError extends Error {
+  constructor(
+    readonly errorClass: ReviewErrorClass,
+    readonly summary: ReviewExecutionSummary,
+  ) {
+    super(`automatic review failed (${errorClass})`);
+    this.name = "ReviewExecutionError";
+  }
+}
+

package/src/user-feedback.ts

@@ -3,6 +3,8 @@ import type { 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 const USER_REVIEW_WIDGET_KEY = "pi-auto-review";
+/** How long a successful completed widget stays above the editor. */
+export const USER_REVIEW_SUCCESS_WIDGET_TTL_MS = 8_000;
 
 export type UserReviewOutcome =
   | "allow"
@@ -454,7 +456,7 @@ export function buildUserReviewGroupLines(
   data: UserReviewGroupEntryData,
 ): UserReviewEntryData {
   if (data.members.length === 1) {
-    const member = data.members[0];
+    const member = data.members[0]!;
     const lines = buildUserReviewLines(member);
     if (member.permissionResult === "deny" && member.outcome !== "deny") {
       lines.push("Local confirmation · denied");
@@ -652,9 +654,14 @@ function setWidget(
   }
 }
 
+function isTransientCompletedOutcome(outcome: UserReviewOutcome): boolean {
+  return outcome === "allow" || outcome === "auto_confirm";
+}
+
 /** Owns the single live widget and rejects stale concurrent completions. */
 export class UserReviewWidgetController {
   #generation = 0;
+  #dismissTimer: ReturnType<typeof setTimeout> | undefined;
   /** Set while a `ctx.ui` prompt blocks the session (ui_prompt span). */
   #waiting?: { kind?: unknown; title?: unknown };
   #current?: {
@@ -664,6 +671,9 @@ export class UserReviewWidgetController {
     data?: UserReviewWidgetData;
     notice?: UserReviewNotice;
   };
+  constructor(
+    private readonly successTtlMs = USER_REVIEW_SUCCESS_WIDGET_TTL_MS,
+  ) {}
 
   begin(
     requestId: string,
@@ -671,6 +681,7 @@ export class UserReviewWidgetController {
     input: { surface: string; target?: string; model?: string },
   ): number {
     const generation = ++this.#generation;
+    this.#cancelDismiss();
     this.#current = { requestId, generation, ctx, data: buildUserReviewingWidgetData(input) };
     this.#render();
     return generation;
@@ -715,8 +726,12 @@ export class UserReviewWidgetController {
       return;
     }
     if (!this.#isCurrent(requestId, generation)) return;
+    this.#cancelDismiss();
     this.#current = { requestId, generation, ctx, notice, data };
     if (!setWidget(ctx, data)) notifyUserReview(ctx, notice);
+    if (isTransientCompletedOutcome(data.outcome)) {
+      this.#scheduleDismiss(generation, ctx);
+    }
   }
 
   permissionDecision(event: unknown): void {
@@ -738,18 +753,36 @@ export class UserReviewWidgetController {
       type: current.notice?.type ?? data.type,
       message: data.lines.join("\n"),
     };
+    this.#cancelDismiss();
     this.#current = { ...current, data, notice };
     if (!setWidget(current.ctx, data)) notifyUserReview(current.ctx, notice);
   }
 
   clear(ctx?: ExtensionContext): void {
     ++this.#generation;
+    this.#cancelDismiss();
     this.#waiting = undefined;
     const current = this.#current;
     this.#current = undefined;
     if (current) setWidget(ctx ?? current.ctx, undefined);
   }
 
+  #cancelDismiss(): void {
+    if (this.#dismissTimer === undefined) return;
+    clearTimeout(this.#dismissTimer);
+    this.#dismissTimer = undefined;
+  }
+
+  #scheduleDismiss(generation: number, ctx: ExtensionContext): void {
+    if (this.successTtlMs <= 0) return;
+    this.#dismissTimer = setTimeout(() => {
+      this.#dismissTimer = undefined;
+      if (this.#current?.generation !== generation) return;
+      this.clear(ctx);
+    }, this.successTtlMs);
+    this.#dismissTimer.unref?.();
+  }
+
   #isCurrent(requestId: string, generation: number): boolean {
     return this.#current?.requestId === requestId &&
       this.#current.generation === generation;